Clarify page field caption and tooltip inheritance (#160)

* Clarify page field caption and tooltip inheritance

Prevent redundant page-level properties by documenting inherited captions and BC24/runtime 13.0 table-field tooltips. Correct companion examples and version-scoped tooltip guidance.

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>

* Address tooltip quality and knowledge scope review feedback

Require useful, behavior-grounded tooltip text rather than caption repetition, improve the samples, and explain why compiler feedback does not prevent redundant page captions.

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>

---------

Co-authored-by: Jesper Schulz-Wedde <jesper.schulzwedde@microsoft.com>
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>

microsoft/knowledge/style/caption-required-on-page-fields.bad.al

@@ -9,16 +9,22 @@ page 50253 "Sample Caption Bad"
         {
             group(General)
             {
-                field("Customer No."; Rec."No.")
+                Caption = 'General';
+                field(CustomerNoValue; CustomerNoValue)
                 {
                     ApplicationArea = All;
+                    ToolTip = 'Specifies the customer number to look up.';
                 }
                 field("Customer Name"; Rec.Name)
                 {
                     ApplicationArea = All;
                     Caption = '';
+                    ToolTip = 'Specifies the customer name shown on sales documents.';
                 }
             }
         }
     }
+
+    var
+        CustomerNoValue: Code[20];
 }

microsoft/knowledge/style/caption-required-on-page-fields.good.al

@@ -1,7 +1,36 @@
+// BC24 / runtime 13.0 or later for table-field tooltips.
+table 50252 "Sample Caption Source"
+{
+    Caption = 'Caption Source';
+    DataClassification = CustomerContent;
+
+    fields
+    {
+        field(1; "No."; Code[20])
+        {
+            Caption = 'No.';
+            ToolTip = 'Specifies the unique number used to distinguish this customer record from other records.';
+        }
+        field(2; Name; Text[100])
+        {
+            Caption = 'Name';
+            ToolTip = 'Specifies the name used to identify the customer alongside the unique customer number.';
+        }
+    }
+
+    keys
+    {
+        key(PK; "No.")
+        {
+            Clustered = true;
+        }
+    }
+}
+
 page 50252 "Sample Caption Good"
 {
     PageType = Card;
-    SourceTable = Customer;
+    SourceTable = "Sample Caption Source";
 
     layout
     {
@@ -10,19 +39,25 @@ page 50252 "Sample Caption Good"
             group(General)
             {
                 Caption = 'General';
-                field("Customer No."; Rec."No.")
+                field("No."; Rec."No.")
                 {
                     ApplicationArea = All;
-                    Caption = 'Customer No.';
-                    ToolTip = 'Specifies the customer number.';
                 }
                 field("Customer Name"; Rec.Name)
                 {
                     ApplicationArea = All;
                     Caption = 'Customer Name';
-                    ToolTip = 'Specifies the customer name.';
+                }
+                field(DisplayValue; DisplayValue)
+                {
+                    ApplicationArea = All;
+                    Caption = 'Display Value';
+                    ToolTip = 'Specifies temporary text for this page; the text is not saved in the customer record.';
                 }
             }
         }
     }
+
+    var
+        DisplayValue: Text[100];
 }

microsoft/knowledge/style/caption-required-on-page-fields.md

@@ -1,28 +1,38 @@
 ---
 bc-version: [all]
 domain: style
-keywords: [caption, page-field, aa0225, aa0226, codecop, captionclass]
+keywords: [caption, page-field, source-field, inheritance, aa0225, aa0226, codecop, captionclass, false-positive]
 technologies: [al]
 countries: [w1]
 application-area: [all]
 ---
 
-# Every page field needs a `Caption` (CodeCop AA0225/AA0226)
+# Page fields can inherit their source table field's `Caption`
 
 ## Description
 
-CodeCop AA0225 and AA0226 require every field control to expose a `Caption` property, separately from the field's source name. The caption is what the user sees as the column header or label; the source name is what the code uses to reference the field. Without an explicit `Caption`, AL falls back to the source field's caption — which may be wrong for the page's context — or to the field name itself in code casing, which surfaces internal naming to users and to translators.
+A page field bound to a table field inherits the source field's `Caption` unless the page overrides it. An inherited caption is valid, user-facing, and translatable; omitting a page-level `Caption` does not mean the control displays an internal identifier or loses translations. CodeCop AA0225/AA0226 concern missing or empty captions, not a requirement to duplicate a caption already supplied by the source table field.
 
-Acceptable exceptions: a field whose caption is inherited via `CaptionClass = '3,5,' + CurrencyCode` (or another CaptionClass formula) does not need a literal `Caption`; the formula provides it. API pages and test pages may omit captions because their consumers are not human users. Boolean fields whose name already reads as a sentence — `Enabled`, `Posted`, `Released` — do not need a redundant Caption that repeats the name.
+Redundant page-level captions compile successfully, so compiler-error recovery does not prevent an agent from adding them. This guidance prevents that false positive rather than replacing analyzer diagnostics.
+
+Controls bound to variables or expressions cannot rely on table-field caption inheritance. For user-facing fields that need a label, supply a `Caption` or a `CaptionClass` that resolves to the intended caption. API pages are not human-facing UI; do not apply this UI-label guidance to their API contract names.
 
 ## Best Practice
 
-`Caption = 'Customer No.';` paired with `ToolTip = 'Specifies …';`. Captions are short, noun-phrase, title-case for primary labels; sentence-case is allowed for descriptive labels that read as a sentence fragment.
+Define the shared caption on the table field and let bound page fields inherit it. Add a page-level `Caption` only when there is no suitable inherited caption or the page genuinely needs different wording. Keep a valid `CaptionClass` rather than adding a redundant literal caption.
 
-See sample: `caption-required-on-page-fields.good.al`.
+Before reporting a missing caption, inspect the binding and source field, including dependency symbols when needed. If the source definition is unavailable, do not treat an omitted page property as proof that the caption is missing. Caption and tooltip requirements are separate: do not add a `ToolTip` just because a caption is being reviewed; see [tooltip inheritance guidance](tooltip-required-on-page-fields.md).
+
+See sample: `caption-required-on-page-fields.good.al`. Caption inheritance applies across BC versions; the sample uses BC24/runtime 13.0 or later to also define tooltips on its table fields.
 
 ## Anti Pattern
 
-A field control with no `Caption` and no `CaptionClass`, or `Caption = '';`. The user sees the internal identifier as the column header and the translation pipeline has nothing to translate.
+A user-facing field that needs a label but has no non-empty explicit or inherited caption and no resolving `CaptionClass` has a genuine labeling gap. This includes `Caption = '';` when no `CaptionClass` supplies the label. A variable name alone is not a translatable caption.
+
+The opposite review defect is flagging a bound field solely because it omits a page-level `Caption`, or inserting a copy of the table field's caption to satisfy AA0225/AA0226. That adds redundant text and prevents subsequent table-caption changes from flowing through to the page.
 
 See sample: `caption-required-on-page-fields.bad.al`.
+
+## References
+
+[Caption property](https://learn.microsoft.com/en-us/dynamics365/business-central/dev-itpro/developer/properties/devenv-caption-property) and [ToolTip property remarks documenting inheritance of both properties](https://learn.microsoft.com/en-us/dynamics365/business-central/dev-itpro/developer/properties/devenv-tooltip-property).

microsoft/knowledge/style/tooltip-required-on-page-fields.bad.al

@@ -1,23 +1,29 @@
 page 50251 "Sample Tooltip Bad"
 {
     PageType = Card;
-    SourceTable = Customer;
     layout
     {
         area(Content)
         {
             group(General)
             {
-                field("No."; Rec."No.")
+                Caption = 'General';
+                field(CustomerNoValue; CustomerNoValue)
                 {
                     ApplicationArea = All;
+                    Caption = 'Customer No.';
                 }
-                field(Amount; Rec."Balance (LCY)")
+                field(PreviewAmount; PreviewAmount)
                 {
                     ApplicationArea = All;
+                    Caption = 'Preview Amount';
                     ToolTip = '';
                 }
             }
         }
     }
+
+    var
+        CustomerNoValue: Code[20];
+        PreviewAmount: Decimal;
 }

microsoft/knowledge/style/tooltip-required-on-page-fields.good.al

@@ -1,24 +1,62 @@
+// BC24 / runtime 13.0 or later.
+table 50250 "Sample Tooltip Source"
+{
+    Caption = 'Tooltip Source';
+    DataClassification = CustomerContent;
+
+    fields
+    {
+        field(1; "No."; Code[20])
+        {
+            Caption = 'No.';
+            ToolTip = 'Specifies the unique number used to distinguish this entry from other entries.';
+        }
+        field(2; Amount; Decimal)
+        {
+            Caption = 'Amount';
+            ToolTip = 'Specifies the monetary value recorded for this entry; changing it updates the saved entry.';
+        }
+    }
+
+    keys
+    {
+        key(PK; "No.")
+        {
+            Clustered = true;
+        }
+    }
+}
+
 page 50250 "Sample Tooltip Good"
 {
     PageType = Card;
-    SourceTable = Customer;
+    SourceTable = "Sample Tooltip Source";
     layout
     {
         area(Content)
         {
             group(General)
             {
+                Caption = 'General';
                 field("No."; Rec."No.")
                 {
                     ApplicationArea = All;
-                    ToolTip = 'Specifies the number that identifies the customer.';
                 }
-                field(Amount; Rec."Balance (LCY)")
+                field(Amount; Rec.Amount)
                 {
                     ApplicationArea = All;
-                    ToolTip = 'Shows the total balance in local currency.';
+                    ToolTip = 'Specifies the recorded amount to compare with the temporary preview amount.';
+                }
+                field(PreviewAmount; PreviewAmount)
+                {
+                    ApplicationArea = All;
+                    Caption = 'Preview Amount';
+                    ToolTip = 'Specifies a temporary amount to compare with the recorded entry amount; this value is not saved.';
                 }
             }
         }
     }
+
+    var
+        PreviewAmount: Decimal;
 }

microsoft/knowledge/style/tooltip-required-on-page-fields.md

@@ -1,30 +1,44 @@
 ---
 bc-version: [all]
 domain: style
-keywords: [tooltip, page-field, aa0218, codecop, accessibility, specifies]
+keywords: [tooltip, page-field, source-field, inheritance, aa0218, codecop, accessibility, specifies]
 technologies: [al]
 countries: [w1]
 application-area: [all]
 ---
 
-# Every page field needs a `ToolTip` (CodeCop AA0218)
+# Page fields need an explicit or inherited `ToolTip` (CodeCop AA0218)
 
 ## Description
 
-CodeCop AA0218 requires a non-empty `ToolTip` property on every field control on a page. The tooltip is what users see on hover and is what screen readers announce; an empty or missing tooltip removes a piece of UI affordance that is part of BC's accessibility baseline. AppSource technical validation rejects pages with missing tooltips. The companion rules AA0219 and AA0220 push the wording further — tooltips should describe what the field shows, conventionally starting with `'Specifies …'`, though `'Shows …'` and similar variants are acceptable when they clearly describe the field's purpose.
+User-facing page fields need tooltip text, but it does not have to be declared on each page control. Starting with BC24 (2024 release wave 1), runtime 13.0 supports `ToolTip` on table fields, and bound page fields inherit it unless they override it. A non-empty inherited tooltip satisfies the requirement; do not interpret CodeCop AA0218 as a requirement to repeat it on the page.
 
-Acceptable exceptions: table fields inside `Upgrade`, `Migration`, `HybridBC14`, `HybridSL`, and `HybridGP` codeunits and tables are allowed to omit the tooltip — those types are not surfaced to users.
+For targets before runtime 13.0, table-field tooltip inheritance is not available, so user-facing page fields need page-level tooltips. Controls bound to variables or expressions also need page-level tooltips because they have no table field to inherit from. This is UI guidance, not a blanket requirement to add tooltips to every table field, including fields never exposed to users.
 
-AA0218 is a compiler analyzer, but its severity is configured per app in the ruleset and is frequently downgraded to `info`/`None` or disabled entirely. PR review therefore cannot assume the compiler will surface the gap: it is the last line of defence for a missing tooltip and should flag it independently. The one case review must *not* flag is a bound field that inherits a `ToolTip` from its source table field — see `bound-page-field-inherits-source-field-tooltip`.
+AA0218's severity is configured per app and may be downgraded or disabled. Review should still report a genuinely missing tooltip, but absence of a page-level declaration alone is not evidence of a gap. See [bound page-field tooltip inheritance](../ui/bound-page-field-inherits-source-field-tooltip.md).
 
 ## Best Practice
 
-Every field control on a regular page carries `ToolTip = 'Specifies …';` (or a clear alternative phrasing). Compose the text in the form "what this value shows" rather than "what the user does with it". In review, raise a `medium`-severity finding for a field that has neither an inline nor an inherited tooltip, independently of whether AA0218 is active in the app's ruleset.
+On runtime 13.0 or later, define shared tooltip text on the table field and omit duplicate page-level properties. Add a page-level `ToolTip` when no tooltip can be inherited or when the page needs different, context-specific help. Describe what the value shows, conventionally starting with "Specifies" or another clear phrasing.
 
-See sample: `tooltip-required-on-page-fields.good.al`.
+Make the text answer a question the caption does not: what the value is used for, which values or units are expected, or what changing it affects. Do not mechanically generate "Specifies the <field name>." and consider the help complete. Use behavior established by the implementation or requirements; do not invent effects, defaults, or constraints to make a tooltip sound useful. Keep shared table-field help applicable to all pages that inherit it, and improve that shared text rather than duplicating it on each page.
+
+Before raising a `medium`-severity finding, check the target runtime, the control's binding, and the source field's tooltip, including dependency symbols when needed. Report a field with neither an explicit nor an inherited tooltip independently of whether AA0218 is active. If the source definition or target runtime is unavailable, do not assume a missing page property means missing tooltip text.
+
+See sample: `tooltip-required-on-page-fields.good.al` (BC24/runtime 13.0 or later).
 
 ## Anti Pattern
 
-A field control with no `ToolTip` property at all, or `ToolTip = '';`. AA0218 flags both; the hover state is blank and the screen reader has nothing to announce.
+A user-facing control with no page-level `ToolTip` and no non-empty source tooltip it can inherit, or a page-level `ToolTip = '';` that leaves the effective tooltip empty.
+
+Flagging a bound field that already inherits its tooltip, or adding the same tooltip to every page, is also incorrect: duplicate overrides add maintenance and translation work and prevent source-field tooltip changes from reaching those pages.
+
+Treating a non-empty tooltip that merely repeats the caption as useful help is a separate quality issue, not a missing-tooltip finding. Point out the concrete information users need rather than demanding longer wording or a page-level override for its own sake.
 
 See sample: `tooltip-required-on-page-fields.bad.al`.
+
+## References
+
+[ToolTip property](https://learn.microsoft.com/en-us/dynamics365/business-central/dev-itpro/developer/properties/devenv-tooltip-property).
+
+[Guidelines for tooltip text](https://learn.microsoft.com/en-us/dynamics365/business-central/dev-itpro/user-assistance#guidelines-for-tooltip-text).

microsoft/knowledge/ui/bound-page-field-inherits-source-field-tooltip.md

@@ -1,5 +1,5 @@
 ---
-bc-version: [all]
+bc-version: [24..]
 domain: ui
 keywords: [tooltip, page-field, source-field, inheritance, aa0218, false-positive]
 technologies: [al]
@@ -11,14 +11,20 @@ application-area: [all]
 
 ## Description
 
-A page field bound to a table field inherits the source field's `ToolTip` at runtime: the control shows the table field's `ToolTip` even when the page control declares none of its own. A page field without an inline `ToolTip` is therefore not, by itself, a missing-tooltip defect — the text may be supplied by the bound source field.
+Starting with BC24 (2024 release wave 1), runtime 13.0 supports `ToolTip` on table fields. A page field bound to a table field inherits the source field's `ToolTip` when the page control declares none of its own. A page field without an inline `ToolTip` is therefore not, by itself, a missing-tooltip defect. This inheritance is not available when targeting earlier runtimes.
 
-The genuinely-missing case is different: a bound field whose source table field *also* carries no `ToolTip`, or an unbound control, has no text to inherit and is a real accessibility gap. The compiler analyzer AA0218 detects this mechanically, but its severity is set by each app's ruleset and is routinely downgraded or disabled — so it cannot be relied on as the only net. PR review is the last line of defence and should raise this case independently.
+The genuinely-missing case is different: a control with no inline `ToolTip` also has no text to inherit when it is unbound or its source table field carries no non-empty `ToolTip`. This leaves a real user-assistance gap. The compiler analyzer AA0218 detects this mechanically, but its severity is set by each app's ruleset and may be downgraded or disabled, so review should raise the genuine gap independently.
 
 ## Best Practice
 
-Do not raise a missing-`ToolTip` finding for a bound page field whose source table field supplies a `ToolTip`; assume the control inherits it. Do raise a `medium`-severity finding when the field has no inline `ToolTip` **and** no inherited one — that is, a bound field whose source field is also tooltip-less, or an unbound control — rather than assuming AA0218 will catch it downstream.
+Check the target runtime and inspect the source field, including dependency symbols when needed. On runtime 13.0 or later, do not raise a missing-`ToolTip` finding for a bound page field whose source table field supplies a non-empty `ToolTip`, and do not add a duplicate page-level property. A page-level override is appropriate only when the page needs different help text or no tooltip can be inherited.
+
+Do raise a `medium`-severity finding when the field has no inline `ToolTip` **and** no inherited one, rather than assuming AA0218 will catch it downstream. If the source definition is unavailable, do not infer that its tooltip is missing. See [tooltip requirements across target versions](../style/tooltip-required-on-page-fields.md).
 
 ## Anti Pattern
 
 Two opposite failures: (1) flagging every page field that has no inline `ToolTip` as a violation, ignoring that a bound field inherits its source field's tooltip; and (2) staying silent on a field that has neither an inline nor an inherited tooltip on the assumption that the compiler's AA0218 will report it — a ruleset that downgrades or disables AA0218 then lets a genuine gap ship unflagged.
+
+## References
+
+[ToolTip property](https://learn.microsoft.com/en-us/dynamics365/business-central/dev-itpro/developer/properties/devenv-tooltip-property).