themelia-react-ui 2.0.4 → 2.0.6

package/docs/consumer-skill/references/view-craft.md

@@ -0,0 +1,153 @@
+# View craft
+
+Themelia already sets type, colour, spacing and surfaces. Craft is what remains:
+deciding what a view shows, how much emphasis each part gets and how the parts
+are arranged, so the user understands the screen at a glance. Each rule below is
+a decision you can explain and check on the rendered result. Most improvements
+remove something.
+
+Start from the [data brief](data-reading.md#write-the-data-brief). Owner
+selection, surfaces and inset ownership follow
+[screen decisions](screen-decisions.md); this reference does not restate them.
+
+## One focal point
+
+Each view, and each region in it, has one thing the eye reaches first: the
+figure that answers the question, the subject's identity and state, or the queue
+of records that need action. Choose it from the brief. When two things compete,
+demote one: a smaller text role, secondary tone, or a supporting region.
+
+Check it by looking at a reduced screenshot: the focal point is still the
+strongest mass. It sits in the first viewport at both 390 and 1440 wide.
+
+## Spend emphasis on purpose
+
+Emphasis works only by contrast, so it is a budget:
+
+- **Commands.** One solid primary command per page or surface. Other commands
+  are outline or ghost, or sit in the same scope's overflow menu.
+- **Text.** At most three levels in a region: title (`Heading`), body and values
+  (`Text`), supporting copy (`Text` secondary, smaller size). A fourth level
+  signals a hierarchy problem, not a missing style.
+- **Tone.** `success`, `warning`, `destructive` and `info` mark a status that
+  changes what the user does. Kinds, categories and counts stay neutral. When
+  everything is coloured, nothing reads as status.
+- **Size.** One hero figure size per region; peer figures share one size.
+
+Adding emphasis in one place means removing it from another.
+
+## Choose the encoding from the fact
+
+| The fact | Encoding | Owner family (confirm with the finder and inspector) |
+| --- | --- | --- |
+| A figure the user must judge | Figure with its baseline delta; a sparkline when the path matters | `Metric`, `MetricTrendChip`, `MetricSparkline`; `MetricComparison` for current versus previous |
+| Several peer figures for one period | One strip, not a grid of identical cards | `MetricBar`; `MetricGrid` with a quiet variant inside one surface |
+| A series whose shape is the message | Chart with one emphasised series and minimal axes | `ChartCard` with Recharts children |
+| Part of a whole, or use against a limit | Bar with the figure as its label | `Progress`, `UsageCard` |
+| Facts about one record | Label and value list; one inline line for two to four short facts | `MetadataList` (inline or stacked), `InlineStat` |
+| A lifecycle with a current stage | Steps with only the current stage emphasised | `StepsHorizontal`, `Timeline` |
+| Events and history | Newest first, grouped by day | `Timeline`, `features/activities` |
+| Many records compared on shared columns | Table whose columns are what users compare or sort | `DataTable`, `DataView` |
+| Records that differ in shape | List rows: identity, one line of context, state, action | `Item`, `ItemGroup` |
+| A money ledger | Right-aligned amounts, one rule above the grand total | `SummaryPanel` with `AmountRow`, `OrderSummary` |
+| Nothing to show yet | What is missing and the next action | `EmptyState` |
+
+Read [metrics and statistics](analytics.md) for the exact metric owner. A chart
+must answer a question you can write in one sentence; otherwise show the figure.
+Do not chart three values. Prefer a sparkline in a strip to a large chart that
+repeats what the figures already say.
+
+## Spend words carefully
+
+- Label a value only when it is ambiguous. A ledger amount needs "Total"; an
+  order number in a header does not need "Order number".
+- Do not repeat a column header inside its cells or a section title in each row.
+- State a unit once, in the header or the value.
+- A sentence fragment often reads better than three label and value pairs:
+  "2 of 3 shipped · 1 reserved at Plovdiv".
+- Omit zero and not-applicable counters, or collapse them into one "Nothing
+  outstanding" line.
+- Do not explain the interface on the page. A description states scope or
+  as-of time, not instructions.
+
+## Density follows the audience
+
+- **Queues** for operators: compact rows, more records per screen, identity,
+  state and amount; detail on open.
+- **Overviews**: fewer, larger figures with room around them, each answering a
+  question.
+- **Records**: the subject leads; evidence and history follow.
+
+Change global density through the provider and density roots described in
+[theming](theming.md). Do not shrink text roles to fit more data; remove
+low-value content first.
+
+## Rhythm groups content
+
+- Gaps grow outward: within a group, between groups, between sections. Equal
+  gaps everywhere mean nothing groups. Use `Stack` and `Grid` gap roles.
+- Few edges: peer regions share content start edges; numbers right-align on one
+  axis; labels share one axis.
+- Few frames: one `Card` per independent subject. Continuous sections of one
+  subject share one surface and are separated by space, not rules or nested
+  boxes.
+- Narrow widths keep the decision content first in reading order. Only data
+  tables that own horizontal scrolling may scroll sideways.
+
+## Numbers and copy
+
+- Numbers use tabular figures through the value primitives (`Money`, `Number`,
+  `Percent`, `Date`, `RelativeTime`) with one precision per column.
+- Recency reads as relative time with the exact date available; documents show
+  absolute dates.
+- A delta states direction and baseline: "↓ 0.9% vs September".
+- Sentence case everywhere. Buttons are a verb and an object ("Record payment").
+  Empty states say what is missing and what to do. Errors say what happened and
+  how to recover.
+
+## Modern patterns and their owners
+
+- **Overview.** A header with the period control, one figure strip (three to
+  five figures with deltas or sparklines), one chart answering the main
+  question, and a "needs attention" list that links to records. Not a wall of
+  identical cards.
+- **Index.** Search plus the work queues users actually work; rows lead with
+  identity and the deciding column; bulk actions appear with a selection;
+  export states how many rows match.
+- **Record.** The page header carries identity, status badges in `titleSuffix`,
+  one metadata line (date · channel · customer) and the primary command. The
+  main column holds the subject's working content, an aside holds context
+  (customer, payment, notes) and history comes last.
+- **Editing.** `InlineEdit` for one field; `ActionDrawer` for a focused
+  multi-field edit that keeps the record visible; `ActionDialog` for short
+  creation; `ConfirmDialog` for destructive commands.
+- **Progressive disclosure.** `Collapsible` or `Accordion` for evidence and
+  technical detail; overflow menus for rare commands.
+- **Loading.** Owners' loading states and `Skeleton` shaped like the content,
+  not spinners in empty boxes.
+
+Inspect each owner's declaration before using it; a pattern names a direction,
+not a prop list.
+
+## Anti-patterns seen in trials
+
+- A grid of identical metric cards whose figures have no baseline.
+- A facts card that repeats the header's identifier, status and date.
+- Every lifecycle counter on every line, zeros included.
+- Column headers repeated in cells; units on every value.
+- Filler cards added to balance a column's whitespace.
+- Decorative icons on titles, rows or badges; tinted icon tiles.
+- Status tones on kinds or categories; three badges on one row saying related
+  things.
+- A storefront hero image inside an operational editor.
+- A framed box inside a card for sub-content that is not a distinct object.
+- A chart of three values, or a chart whose question cannot be stated.
+- Prose explaining what the screen does.
+
+## When an owner limits the view
+
+When an owner cannot express the hierarchy the data needs, compose its public
+parts or app markup with token-backed utilities
+([domain structures](domain-structures.md)) and report the gap by owner and
+prop. Never override anatomy classes, add colours or add tokens to make a view
+look designed.

package/docs/consumer-skill/references/view-spec.md

@@ -0,0 +1,73 @@
+# View spec
+
+Write this before JSX for a new view or a substantial redesign. Keep it short
+enough to read in a minute; it is a working note, not an approval document. Every
+line should change a later decision. Save it beside the app's other design notes
+so a reviewer can compare the result with the intent.
+
+```md
+# <View name> (<route>)
+
+## Decision
+<who> decides <what>, <how often>. Success: <what they can do faster or with more confidence>.
+
+## Data brief
+<the data brief from data-reading.md>
+
+## Ranked information
+- Must (first viewport at 390 and 1440): …
+- Should (visible without interaction): …
+- Could (behind disclosure, overflow or a detail view): …
+- Omit: … (why: zero, not applicable, duplicated elsewhere, not used for this decision)
+
+## Focal point
+<the one element the eye reaches first, and why>
+
+## Wireframes
+1440:
+┌──────────────────────────────────────────────┐
+│ Title · status          [secondary] [Primary]│
+│ meta · meta · meta                           │
+├──────────────────────────────┬───────────────┤
+│ main subject                 │ context       │
+│ …                            │ …             │
+└──────────────────────────────┴───────────────┘
+
+390:
+┌────────────────────┐
+│ Title · status     │
+│ [Primary]   [⋯]    │
+│ main subject       │
+│ context            │
+└────────────────────┘
+
+## Encodings
+| Fact | Encoding | Why |
+| --- | --- | --- |
+
+## Owners
+| Region | Owner | Exact import | Verified with |
+| --- | --- | --- | --- |
+(found with find-components.mjs and map-composition.mjs; props checked with inspect-component.mjs)
+
+## Commands
+<command: scope, emphasis (primary, secondary, overflow), eligibility and disabled reason>
+
+## States
+Loading: … Empty: … Error and retry: … Accepted: … Long text and narrow parent: …
+
+## Open questions and data gaps
+…
+```
+
+## Notes
+
+- Draw wireframes in text so they survive any editor and diff. Boxes show
+  regions and order, not pixel sizes.
+- The ranked list is where most quality comes from. If "must" has more than
+  five items, the decision is not specific enough yet.
+- Fill "Owners" only after running the finder and inspector. An owner that does
+  not fit is recorded with the reason, and the region becomes app markup over
+  public parts.
+- After building, score the result with the [critique rubric](critique-rubric.md)
+  and note any departure from this spec with its reason.

package/docs/consumer-skill/references/workflows.md

@@ -124,7 +124,13 @@ back navigation, content bounds, commands and section tabs. Pass the record's
 main command as `header.primaryAction`, supporting commands as
 `header.secondaryActions` and separately selected/routed sections as `header.tabs`;
 continuous sections can stay in the body. One status badge goes in
-`header.titleBadges`. `PageHeader` serves a custom shell; `PageActions` is
+`header.slots.titleSuffix` as a composed Badge. Place supporting facts in
+`header.slots.afterDescription` as a MetadataList when useful. The four header
+slots (`beforeTitle`, `titleSuffix`, `afterDescription`, `actions`) accept content
+or a callback receiving `{ renderLink, defaultContent }`; an actions callback
+can wrap or return `defaultContent` to retain responsive commands. A replacement
+owns its behavior. Below 40rem of actual header width, all commands, including
+primary, share one More actions trigger. `PageHeader` serves a custom shell; `PageActions` is
 deprecated. The [layout recipe](../examples/app-layout.tsx) demonstrates that
 route boundary; the [detail recipe](../examples/detail.tsx) demonstrates the
 record route and an independently framed subject with MetadataList and value

package/docs/consumer-skill/scripts/composition-policy.mjs

@@ -44,6 +44,8 @@ export function analyzeComposition(text, { filename, index, ts }) {
   const families = new Map(index.families.map(owner => [owner.import, owner]));
   const bindings = new Map();
   const namespaces = new Map();
+  const portalBindings = new Set();
+  const portalNamespaces = new Set();
   const declarations = new Map();
   const findings = [];
   const unresolved = [];
@@ -135,14 +137,23 @@ export function analyzeComposition(text, { filename, index, ts }) {
     if (names && ts.isNamespaceImport(names)) namespaces.set(symbolFor(names.name), specifier);
   }
   function gather(node) {
+    if (ts.isImportDeclaration(node) && ts.isStringLiteralLike(node.moduleSpecifier) && node.moduleSpecifier.text === 'react-dom') {
+      const names = node.importClause?.namedBindings;
+      if (names && ts.isNamedImports(names)) for (const item of names.elements) if ((item.propertyName ?? item.name).text === 'createPortal') portalBindings.add(symbolFor(item.name));
+      if (names && ts.isNamespaceImport(names)) portalNamespaces.add(symbolFor(names.name));
+      if (node.importClause?.name) portalNamespaces.add(symbolFor(node.importClause.name));
+    }
     if (ts.isImportDeclaration(node) && ts.isStringLiteralLike(node.moduleSpecifier) && importsModal(node, ts)) add(node, 'raw-overlay-primitive', 'warning', `${node.moduleSpecifier.text} builds a second dialog system. ${overlayRemedy}`);
     if (ts.isVariableDeclaration(node) && ts.isIdentifier(node.name) && node.initializer) declarations.set(symbolFor(node.name), node.initializer);
+    if (ts.isFunctionDeclaration(node) && node.name && node.body) declarations.set(symbolFor(node.name), node);
     if ((ts.isImportDeclaration(node) || ts.isExportDeclaration(node)) && node.moduleSpecifier && ts.isStringLiteralLike(node.moduleSpecifier)) importOwner(node, node.moduleSpecifier.text);
     if (ts.isImportTypeNode(node) && ts.isLiteralTypeNode(node.argument) && ts.isStringLiteralLike(node.argument.literal)) importOwner(node, node.argument.literal.text);
     if (ts.isCallExpression(node) && node.expression.kind === ts.SyntaxKind.ImportKeyword && ts.isStringLiteralLike(node.arguments[0])) importOwner(node, node.arguments[0].text);
     ts.forEachChild(node, gather);
   }
   gather(source);
+  const portalCall = node => ts.isCallExpression(node) && (ts.isIdentifier(node.expression) && portalBindings.has(symbolFor(node.expression))
+    || ts.isPropertyAccessExpression(node.expression) && node.expression.name.text === 'createPortal' && ts.isIdentifier(node.expression.expression) && portalNamespaces.has(symbolFor(node.expression.expression)));
   for (const diagnostic of source.parseDiagnostics) add(source, 'syntax', 'error', ts.flattenDiagnosticMessageText(diagnostic.messageText, '\n'));
   const ownerFor = tag => {
     if (ts.isIdentifier(tag)) return bindings.get(symbolFor(tag));
@@ -157,16 +168,23 @@ export function analyzeComposition(text, { filename, index, ts }) {
     const expression = ts.isJsxExpression(attribute.initializer) ? attribute.initializer.expression : attribute.initializer;
     return [[attribute.name.getText(source), expression]];
   });
+  const unknownSpread = (expression, visiting = new Set()) => {
+    const value = resolve(expression);
+    if (!value || !ts.isObjectLiteralExpression(value) || visiting.has(value)) return true;
+    const next = new Set(visiting).add(value);
+    return value.properties.some(property => ts.isSpreadAssignment(property) && unknownSpread(property.expression, next));
+  };
   const isOwner = (owner, suffix, names) => owner?.import === `${index.package}/${suffix}` && names.includes(owner.symbol);
   const framedOwner = (owner, props) => {
-    if (literal(props.get('surface')) === 'flat') return false;
-    if (isOwner(owner, 'base/cards', ['Card', 'SmartCard']) || isOwner(owner, 'features/table', ['DataTable']) || isOwner(owner, 'features/data-view', ['DataView'])) return true;
+    if (props.has('surface') && (literal(props.get('surface')) === undefined || literal(props.get('surface')) === 'flat')) return false;
+    if (isOwner(owner, 'base/cards', ['Card', 'SmartCard']) || isOwner(owner, 'base/forms', ['FormSection']) || isOwner(owner, 'features/table', ['DataTable']) || isOwner(owner, 'features/data-view', ['DataView'])) return true;
+    if (isOwner(owner, 'blocks/analytics', ['ChartCard']) || isOwner(owner, 'base/display', ['ContentBlock'])) return props.has('surface');
     if (isOwner(owner, 'blocks/analytics', ['Metric'])) return literal(props.get('variant')) === 'card';
     if (isOwner(owner, 'blocks/analytics', ['MetricGrid'])) return !props.has('variant') || literal(props.get('variant')) === 'card';
     return isOwner(owner, 'blocks/analytics/usage-card', ['UsageCard']) || isOwner(owner, 'blocks/analytics', ['UsageCard']) || isOwner(owner, 'blocks/planning', ['TaskCard']);
   };
   // Examine lexical JSX only. Names ending in Card are not evidence of framing;
-  // ChartCard is card-free; Receipt's flat paper has no ordinary Card frame.
+  // ChartCard is card-free by default; Receipt's paper has no ordinary Card frame.
   const contentElements = element => {
     const found = [];
     function collect(child) {
@@ -184,6 +202,25 @@ export function analyzeComposition(text, { filename, index, ts }) {
     if (ts.isJsxElement(element.parent)) element.parent.children.forEach(collect);
     return found;
   };
+  // Static region children only: inspect known passive wrappers and providers,
+  // never assume an opaque app component renders its lexical children.
+  const regionElements = (opening, deep = false) => {
+    const found = [];
+    const collect = (child, scope = opening, subject) => {
+      if (ts.isJsxFragment(child)) { child.children.forEach(item => collect(item, scope, subject)); return; }
+      if (ts.isJsxExpression(child)) { const value = resolve(child.expression); if (value) collect(value, scope, subject); return; }
+      const node = ts.isJsxElement(child) ? child.openingElement : ts.isJsxSelfClosingElement(child) ? child : undefined;
+      if (!node) return;
+      const owner = ownerFor(node.tagName);
+      found.push({node, owner, tag: node.tagName.getText(source), scope, subject});
+      const provider = isOwner(owner, 'features/filters', ['FilterProvider']);
+      const card = isOwner(owner, 'base/cards', ['Card', 'SmartCard']);
+      // Cards delimit independent subjects; providers delimit query state.
+      if (deep && ts.isJsxElement(child) && (/^(div|section|form)$/.test(node.tagName.getText(source)) || isOwner(owner, 'base/structure', ['Stack', 'Grid', 'AdaptiveGrid', 'GridCell']) || card || provider)) child.children.forEach(item => collect(item, provider ? node : scope, card ? node : subject));
+    };
+    if (ts.isJsxElement(opening.parent)) opening.parent.children.forEach(child => collect(child));
+    return found;
+  };
   const renderedText = element => ts.isJsxElement(element) ? element.children.map(child => ts.isJsxText(child) ? child.text : ts.isJsxExpression(child) ? literal(child.expression) ?? '' : '').join(' ').trim() : '';
   const slotBadge = expression => {
     const node = resolve(expression);
@@ -241,25 +278,43 @@ export function analyzeComposition(text, { filename, index, ts }) {
   };
   // tone="primary" is solid unless a buttonStyle says otherwise; untoned Buttons are neutral.
   const solidPrimary = (opening, owner) => {
-    if (!isOwner(owner, 'base/buttons', ['Button'])) return false;
+    const submit = isOwner(owner, 'base/forms', ['SubmitStateButton']);
+    if (!submit && !isOwner(owner, 'base/buttons', ['Button'])) return false;
     const props = new Map(attributes(opening));
     const style = props.has('buttonStyle') ? literal(props.get('buttonStyle')) : 'solid';
-    return literal(props.get('tone')) === 'primary' && style === 'solid';
+    return (literal(props.get('tone')) ?? (submit && !props.has('tone') ? 'primary' : undefined)) === 'primary' && style === 'solid';
+  };
+  const formRoot = opening => {
+    if (opening.tagName.getText(source) === 'form') return true;
+    const render = resolve(new Map(attributes(opening)).get('render'));
+    return render && (ts.isJsxElement(render) ? render.openingElement : ts.isJsxSelfClosingElement(render) ? render : undefined)?.tagName.getText(source) === 'form';
   };
-  // Overlays are separate surfaces with their own primary command.
+  // A form owns its submit command; overlays and exclusive branches are not
+  // simultaneously competing page commands. Follow same-file slot values only.
   const solidPrimaryCount = root => {
-    let count = 0;
-    const walk = child => {
+    const count = (expression, visiting = new Set()) => {
+      if (!expression) return 0;
+      const child = resolve(expression) ?? expression;
+      if (visiting.has(child)) return 0;
+      const next = new Set(visiting).add(child);
+      if (portalCall(child)) return 0;
+      if (ts.isConditionalExpression(child)) return Math.max(count(child.whenTrue, next), count(child.whenFalse, next));
+      if (ts.isBinaryExpression(child) && [ts.SyntaxKind.BarBarToken, ts.SyntaxKind.QuestionQuestionToken].includes(child.operatorToken.kind)) return Math.max(count(child.left, next), count(child.right, next));
       if (ts.isJsxElement(child) || ts.isJsxSelfClosingElement(child)) {
         const opening = ts.isJsxElement(child) ? child.openingElement : child;
         const owner = ownerFor(opening.tagName);
-        if (isOwner(owner, 'features/overlays', overlayOwners)) return;
-        if (solidPrimary(opening, owner)) count++;
+        if (isOwner(owner, 'features/overlays', overlayOwners) || formRoot(opening) || !owner && /^[A-Z]/.test(opening.tagName.getText(source))) return 0;
+        const props = new Map(attributes(opening));
+        if (resolve(props.get('hidden'))?.kind === ts.SyntaxKind.TrueKeyword || props.has('hidden') && props.get('hidden') === undefined) return 0;
+        const children = ts.isJsxElement(child) ? child.children.reduce((total, item) => total + count(item, next), 0) : 0;
+        const slots = [...props].filter(([name]) => !['header', 'render'].includes(name)).reduce((total, [, value]) => total + count(value, next), 0);
+        return Number(solidPrimary(opening, owner)) + children + slots;
       }
-      ts.forEachChild(child, walk);
+      let total = 0;
+      ts.forEachChild(child, item => { total += count(item, next); });
+      return total;
     };
-    ts.forEachChild(root, walk);
-    return count;
+    return count(root);
   };
   const peerCards = element => {
     if (!ts.isJsxElement(element.parent)) return new Set();
@@ -303,18 +358,78 @@ export function analyzeComposition(text, { filename, index, ts }) {
       return smallPeerGaps.has(row ?? gap) || smallPeerGaps.has(column ?? gap);
     });
   };
-  function visit(node, parents = []) {
+  const separateRegion = owner => isOwner(owner, 'features/overlays', overlayOwners)
+    || isOwner(owner, 'base/popover', ['PopoverContent'])
+    || isOwner(owner, 'base/navigation', ['DropdownMenuContent', 'DropdownMenuSubContent', 'ContextMenuContent', 'ContextMenuSubContent'])
+    || isOwner(owner, 'base/combobox', ['ComboboxContent', 'ComboboxPopup'])
+    || isOwner(owner, 'base/choice-inputs', ['SelectPopupContent']);
+  function regionParents(element, parents, context, slot) {
+    if (slot === 'render') return parents;
+    if (separateRegion(context?.owner) || !context && /^[A-Z]/.test(element.tagName.getText(source))) parents = [];
+    return context ? [...parents, { ...context, slot }] : parents;
+  }
+  function visitValue(value, parents, visiting) {
+    if (value) visit(resolve(value) ?? value, parents, visiting);
+  }
+  function visit(node, parents = [], visiting = new Set()) {
+    if (visiting.has(node)) return;
+    const next = new Set(visiting).add(node);
     if (ts.isJsxElement(node)) {
       const element = node.openingElement;
       const context = inspect(element, parents);
-      for (const child of node.children) visit(child, context ? [...parents, context] : parents);
-      // JSX in props is a separate region, not a child frame.
-      for (const attribute of element.attributes.properties) ts.forEachChild(attribute, child => visit(child, parents));
+      for (const child of node.children) visit(child, regionParents(element, parents, context, 'children'), next);
+      for (const [slot, value] of attributes(element)) visitValue(value, regionParents(element, parents, context, slot), next);
+      return;
+    }
+    if (ts.isJsxSelfClosingElement(node)) {
+      const context = inspect(node, parents);
+      for (const [slot, value] of attributes(node)) visitValue(value, regionParents(node, parents, context, slot), next);
+      return;
+    }
+    if (ts.isJsxExpression(node)) { visitValue(node.expression, parents, next); return; }
+    if (ts.isPropertyAssignment(node) || ts.isShorthandPropertyAssignment(node) || ts.isMethodDeclaration(node)) {
+      const member = ts.isIdentifier(node.name) || ts.isStringLiteralLike(node.name) ? node.name.text : undefined;
+      // columns contains header/footer renderers as well as cells. Only a cell
+      // owns the table-row height addressed by heavy-cell-disclosure.
+      const nextParents = parents.map(parent => parent.slot === 'columns' && ['cell', 'header', 'footer'].includes(member) ? {...parent, member} : parent);
+      if (ts.isMethodDeclaration(node)) { if (node.body) visit(node.body, nextParents, next); }
+      else visitValue(ts.isShorthandPropertyAssignment(node) ? node.name : node.initializer, nextParents, next);
       return;
     }
-    if (ts.isJsxSelfClosingElement(node)) inspect(node, parents);
-    ts.forEachChild(node, child => visit(child, parents));
+    if (portalCall(node)) {
+      for (const [index, value] of node.arguments.entries()) visitValue(value, index === 0 ? [] : parents, next);
+      return;
+    }
+    ts.forEachChild(node, child => visit(child, parents, next));
   }
+  const surfaceOwner = owner => isOwner(owner, 'base/cards', ['Card', 'SmartCard', 'CardFooter']) || isOwner(owner, 'base/forms', ['FormSection']) || isOwner(owner, 'blocks/analytics', ['ChartCard']) || isOwner(owner, 'base/display', ['ContentBlock']);
+  const footerRegion = parent => surfaceOwner(parent.owner) && (['footerSlot', 'footer'].includes(parent.slot) || parent.owner.symbol === 'CardFooter');
+  const paddedRegion = parent => {
+    if (!surfaceOwner(parent.owner) || parent.unknownProps) return false;
+    if (parent.props.has('padding')) {
+      const padding = literal(parent.props.get('padding'));
+      return padding !== undefined && padding !== 'none';
+    }
+    // Flat removes the frame, not Card/FormSection's ordinary region insets.
+    // ChartCard and ContentBlock instead default to no inset when card-free.
+    return isOwner(parent.owner, 'base/cards', ['Card', 'SmartCard', 'CardFooter']) || isOwner(parent.owner, 'base/forms', ['FormSection']) || parent.framed;
+  };
+  const remoteSubmit = expression => {
+    const calls = new Set();
+    const walk = (node, visiting = new Set()) => {
+      if (!node) return;
+      const value = resolve(node) ?? node;
+      if (visiting.has(value)) return;
+      const next = new Set(visiting).add(value);
+      if (ts.isCallExpression(value) && ts.isPropertyAccessExpression(value.expression)) {
+        if (value.expression.name.text === 'requestSubmit') calls.add('submit');
+        if (value.expression.name.text === 'getElementById' && value.expression.expression.getText(source) === 'document' && !symbolFor(value.expression.expression)) calls.add('lookup');
+      }
+      ts.forEachChild(value, child => walk(child, next));
+    };
+    walk(expression);
+    return calls.size === 2;
+  };
   // A native element passed as a package owner's `render` is that owner's root, such as
   // an Item row rendered as a button; the owner keeps its focus, hover and row anatomy.
   const renderRoots = new Set();
@@ -342,7 +457,7 @@ export function analyzeComposition(text, { filename, index, ts }) {
       if (modalRole || scrim) add(node, 'raw-overlay-primitive', 'warning', `A hand-rolled ${modalRole ? 'dialog' : 'full-screen layer'} must own focus, dismissal, pending state and theming itself. ${overlayRemedy}`);
       if (/^(?:input|textarea)$/.test(node.tagName.getText(source))) {
         const props = new Map(attributes(node));
-        if (props.has('className') && classStrings(props.get('className')).flatMap(value=>value.split(/\s+/)).some(value=>replacesSharedRadius(value,'inner'))) add(node,'shared-radius','error','Native editable controls follow bounded rounded-inner; change the global theme root, not per-field corners.');
+        if (props.has('className') && classStrings(props.get('className')).flatMap(value=>value.split(/\s+/)).some(value=>replacesSharedRadius(value,'radius'))) add(node,'shared-radius','error','Native editable controls follow bounded rounded-radius; change the global theme root, not per-field corners.');
         if (props.has('style') && properties(props.get('style')).some(([name])=>radiusProperty.test(name))) add(node,'shared-radius','error','Native editable corners belong to the global radius root, not inline styles.');
       }
       if (nativeDisplayNames.test(node.tagName.getText(source))) {
@@ -356,9 +471,10 @@ export function analyzeComposition(text, { filename, index, ts }) {
       add(node, 'public-symbol', 'error', `${owner.import} does not export ${owner.symbol}.`);
       return;
     }
-    const unresolvedBeforeProps = unresolved.length;
     const props = new Map(attributes(node));
-    const unknownProps = unresolved.length !== unresolvedBeforeProps;
+    // Other reviews can have already disclosed this spread. Deduplication of
+    // unresolved output must not turn an unknown value into a known default.
+    const unknownProps = node.attributes.properties.some(attribute => ts.isJsxSpreadAttribute(attribute) && unknownSpread(attribute.expression));
     const family = owner.import.split('/base/')[1];
     const anatomy = surfaceParts[family]?.test(owner.symbol);
     const forwarder = surfaceForwarders[family] === owner.symbol;
@@ -375,7 +491,7 @@ export function analyzeComposition(text, { filename, index, ts }) {
       const focusDrift = focusRingDrift(tokens);
       if ((anatomy || forwarder && name === 'contentClassName') && classes.some(value => paddingClass.test(value))) add(node, 'surface-padding', 'error', `${owner.symbol}: use inset/type/density and public regions; padding overrides replace owned anatomy.`);
       if (control && name === 'className' && classes.some(value => fixedControlClass.test(value))) add(node, 'control-anatomy', 'error', `${owner.symbol}: use its size/variant props; preserve shared control height, inset, corners and typography.`);
-      if ((name === 'className' && (control || sharedCorners) || name === 'contentClassName' && forwarder) && classes.some(value=>replacesSharedRadius(value, control && name === 'className' ? 'inner' : cornerRole(family,owner.symbol)))) add(node,'shared-radius','error',`${owner.symbol}: outer shells use rounded-radius; controls and collection rows use bounded rounded-inner. Preserve the owning role and joined-edge resets.`);
+      if ((name === 'className' && (control || sharedCorners) || name === 'contentClassName' && forwarder) && classes.some(value=>replacesSharedRadius(value, control && name === 'className' ? 'radius' : cornerRole(family,owner.symbol)))) add(node,'shared-radius','error',`${owner.symbol}: outer shells use rounded-surface; controls and collection rows use bounded rounded-radius. Preserve the owning role and joined-edge resets.`);
       if (display && classes.some(addsCopyMargin)) add(node,'copy-margin','error',`${owner.symbol}: typography is margin-free; use textGap on the headed owner or gap on Stack/Grid.`);
       if (textContent && name === 'className' && tokens.some(token=>fadedText(token)||textOpacityDrift(token))) add(node,'faded-text','error',`${owner.symbol}: use its semantic type instead of adding an opacity tier to the text. Presence endpoints and shared disabled state remain valid.`);
       if ((control || family === 'buttons' && owner.symbol === 'TextButton') && name === 'className' && focusDrift.length) add(node, 'focus-ring-recipe', 'error', `${owner.symbol}: keep the shared focus indicator (a ring-3 halo of ring-ring/50 around a full-strength ring edge); ${[...new Set(focusDrift)].join(', ')} redraws it.`);
@@ -391,7 +507,7 @@ export function analyzeComposition(text, { filename, index, ts }) {
     if ((isOwner(owner, 'base/cards', ['Card', 'SmartCard']) || isOwner(owner, 'base/display', ['ContentBlock'])) && props.get('icon')) add(node, 'decorative-icon', 'warning', `${owner.symbol}: a title icon is decoration unless it encodes state or a brand; let the title name the subject.`);
     const facts = isOwner(owner, 'base/metadata-list', ['MetadataList']) || isOwner(owner, 'blocks/data-display', ['MetadataList']) ? resolve(props.get('items')) : undefined;
     if (facts && ts.isArrayLiteralExpression(facts) && facts.elements.filter(item => properties(item, false).some(([name]) => name === 'icon')).length > 1) add(node, 'decorative-icon', 'warning', 'MetadataList: an icon on every fact repeats what its label says; keep labels and drop the icons.');
-    const framed = framedOwner(owner, props);
+    const framed = !unknownProps && framedOwner(owner, props);
     if (isOwner(owner, 'base/cards', ['Card', 'SmartCard'])) {
       for (const slot of ['headerAction', 'headerStart']) if (slotBadge(props.get(slot))) add(node, 'card-badge-placement', 'error', `${owner.symbol}: put status/count/version badges in titleSuffix; ${slot} owns ${slot === 'headerAction' ? 'commands' : 'pre-title context'}.`);
       const contents = contentElements(node);
@@ -404,6 +520,37 @@ export function analyzeComposition(text, { filename, index, ts }) {
     }
     if (isOwner(owner, 'base/feedback', ['Empty'])) add(node, 'reinvented-empty-state', 'warning', 'Empty exposes lower-level anatomy. Compare EmptyState from blocks/data-display for a routine no-data/no-results region; keep Empty when custom anatomy is required.');
     if (isOwner(owner, 'base/sheet', ['Sheet', 'SheetContent']) || isOwner(owner, 'base/display', ['Dialog', 'DialogContent', 'AlertDialog', 'AlertDialogContent'])) add(node, 'raw-overlay-primitive', 'warning', 'This lower-level modal needs application lifecycle coordination. Prefer ActionDialog, ConfirmDialog or ActionDrawer from features/overlays when their workflow fits.');
+    if (isOwner(owner, 'base/forms', ['FormActionsBar'])) {
+      const footer = parents.findLast(footerRegion);
+      const padded = parents.findLast(paddedRegion);
+      if (footer || padded) add(node, 'form-actions-bar-placement', 'warning', `FormActionsBar owns a divider, background and inset; ${footer ? `${footer.owner.symbol}.${footer.slot} already owns footer geometry` : `${padded.owner.symbol} already owns body padding`}. Put action buttons directly in the footer slot, or place the bar at the end of the form inside Card padding="none" with flat FormSection siblings. Review intentional custom hosts.`);
+    }
+    if (isOwner(owner, 'features/table', ['DataTable']) || isOwner(owner, 'base/table', ['Table'])) {
+      const footer = parents.findLast(footerRegion);
+      const padded = parents.findLast(paddedRegion);
+      if (footer || padded) add(node, 'uncontained-table-in-card', 'warning', `${owner.symbol} is inside ${footer ? `${footer.owner.symbol}.${footer.slot}` : `a padded ${padded.owner.symbol}`}. Keep substantial tables in a body or peer region; a deliberate Card host uses padding="none" with a flat table. Review the actual surface and inset ownership.`);
+    }
+    if ((isOwner(owner, 'base/accordion', ['Accordion', 'SmartAccordion']) || isOwner(owner, 'features/table', ['DataTable']) || isOwner(owner, 'base/code-block', ['CodeBlock'])) && parents.some(parent => isOwner(parent.owner, 'features/table', ['DataTable']) && parent.slot === 'columns' && parent.member === 'cell')) {
+      add(node, 'heavy-cell-disclosure', 'warning', `${owner.symbol} in a DataTable cell can disrupt row scanning. Prefer a compact summary with rowActions opening an ActionDrawer, ActionDialog or detail route; retain an intentional inline disclosure after checking expanded rows and keyboard access.`);
+    }
+    if (isOwner(owner, 'base/choice-inputs', ['CardCheckboxGroup', 'CardRadioGroup', 'ListRadioGroup', 'PillRadioGroup'])) {
+      const options = resolve(props.get('options'));
+      if (options && ts.isArrayLiteralExpression(options) && options.elements.length === 1 && !ts.isSpreadElement(options.elements[0])) add(node, 'single-option-choice-group', 'warning', `${owner.symbol} has one static option. For a boolean setting prefer Checkbox, Switch, ToggleField or SwitchCard; retain a genuine choice set whose available options happen to contain one item.`);
+    }
+    const routeOwner = isOwner(owner, 'layout/page', ['Page']) || isOwner(owner, 'layout', ['Page']);
+    if (routeOwner) {
+      for (const name of ['narrow', 'maxWidth']) {
+        const value = resolve(props.get(name));
+        if (value && (ts.isConditionalExpression(value) || ts.isBinaryExpression(value) || ts.isPrefixUnaryExpression(value))) add(props.get(name), 'dynamic-page-measure', 'warning', `Page ${name} depends on an expression and may resize the header and tabs when sections change. Keep the route measure stable and constrain a focused tab panel with Container maxWidth="md" gutter="none"; responsive route sizing can be intentional.`);
+      }
+      const children = regionElements(node);
+      const contents = regionElements(node, true);
+      const tables = contents.filter(child => isOwner(child.owner, 'features/table', ['DataTable']));
+      for (const child of contents) if (isOwner(child.owner, 'features/filters', ['FilterLayout']) && tables.some(table => table.scope === child.scope && (!child.subject || table.subject === child.subject))) add(child.node, 'detached-filter-layout', 'warning', 'Pass FilterLayout into DataTable topbarContent with variant="compact", or use DataView so filters and table chrome share one surface.');
+      const hasAsideSlot = properties(props.get('slots'), false).some(([name]) => name === 'aside');
+      const onlyForms = children.length > 0 && children.every(child => child.tag === 'form' || isOwner(child.owner, 'base/forms', ['FormSection']));
+      if (onlyForms && !unknownProps && !['narrow', 'maxWidth', 'aside'].some(name => props.has(name)) && !hasAsideSlot) add(node, 'wide-single-column-form', 'warning', 'Review this single-column form measure: a focused form can use Page narrow (48rem centered), an explicit maxWidth, or a supporting aside. In a mixed/tabbed route, keep Page stable and constrain only the form panel with Container maxWidth="md" gutter="none".');
+    }
     if (owner.symbol === 'Page' && literal(props.get('gutter')) === 'none' && !parents.some(parent => parent.framed)) add(node, 'page-gutter', 'warning', 'Page gutter="none" delegates inline padding to a real parent. PageViewport owns scrolling, not padding; verify the parent inset.');
     if (owner.symbol === 'Card' && framed && literal(props.get('padding')) === 'sm' && !parents.some(parent => parent.framed)) add(node, 'compact-card', 'warning', 'Standalone Card padding="sm" halves the normal inset. Omit padding for ordinary subjects; retain sm only for an intentional compact composition.');
     const peers = parents.findLast(parent => parent.structure);
@@ -411,6 +558,8 @@ export function analyzeComposition(text, { filename, index, ts }) {
     if (framed && parents.some(parent => parent.framed)) add(node, 'nested-surface', 'warning', `${owner.symbol} is inside a framed owner. Review subject boundaries; use surface="flat" when the parent owns the frame.`);
     const header = properties(props.get('header'), false);
     const pageOwner = owner.import === `${index.package}/layout/page` || owner.import === `${index.package}/layout`;
+    const headerValue = resolve(props.get('header'));
+    if (routeOwner && props.has('header') && headerValue && !ts.isObjectLiteralExpression(headerValue)) unknown(props.get('header'));
     // Every header owner takes role-based commands; its free-form regions hold
     // non-command controls only.
     const commandHeader = (pageOwner && owner.symbol === 'PageHeader') || isOwner(owner, 'base/navigation', ['PageHeading']) || isOwner(owner, 'features/resource', ['ResourceHeader', 'ResourceIndexShell', 'ResourceShowShell', 'TabbedResourceShell']) || isOwner(owner, 'layout/settings', ['SettingsShell', 'AsideNavShell']) || isOwner(owner, 'layout', ['SettingsShell', 'AsideNavShell']) || isOwner(owner, 'layout/workspace', ['WorkspaceRecordHeader']);
@@ -418,11 +567,12 @@ export function analyzeComposition(text, { filename, index, ts }) {
     const elementSecondary = isOwner(owner, 'layout/workspace', ['WorkspaceRecordHeader']) ? props.get('secondaryActions') : undefined;
     if (pageOwner && owner.symbol === 'Page') {
       const primaries = solidPrimaryCount(ts.isJsxSelfClosingElement(node) ? node : node.parent) + (new Map(header).has('primaryAction') ? 1 : 0);
-      if (primaries > 1) add(node, 'multiple-primary-commands', 'warning', `Page has ${primaries} solid primary commands. Keep one primary per page as header.primaryAction; leave other commands untoned (the neutral button) or list them in secondaryActions.`);
+      if (primaries > 1) add(node, 'multiple-primary-commands', 'warning', `Page has ${primaries} solid primary commands in the same task scope. Keep one leading command per task/surface; forms keep their local SubmitStateButton or FormActionsBar. Use header.primaryAction for route-level commands and secondaryActions for supporting route commands.`);
     }
     if ((headerActions && commandButtons(headerActions)) || (elementSecondary && commandButtons(elementSecondary))) add(node, 'page-command-roles', 'warning', `${owner.symbol}: buttons, command rows and menus in the header actions region choose their own emphasis, order and overflow. Pass commands as primaryAction (one) and ordered secondaryActions; keep actions for non-command controls.`);
     const headerProps = pageOwner && owner.symbol === 'Page' ? new Map(header) : pageOwner && owner.symbol === 'PageHeader' ? props : undefined;
     if (headerProps) {
+      for (const name of ['primaryAction', 'secondaryActions']) if (headerProps.has(name) && remoteSubmit(headerProps.get(name))) add(headerProps.get(name), 'remote-header-form-submit', 'warning', `${owner.symbol}: ${name} submits a form through document.getElementById(...).requestSubmit(). Keep task-local submission beside its fields or in the form footer. A single full-page editor can deliberately own a header submit; preserve native validation and avoid duplicate commands.`);
       if (headerProps.has('titleIcon') && !headerProps.has('titleIconHref') && !headerProps.has('onTitleIconClick')) add(headerProps.get('titleIcon') ?? node, 'decorative-icon', 'warning', `${owner.symbol}: titleIcon decorates the page title; let the title name the page, or link the icon with titleIconHref.`);
       const hasIcon = action => properties(action, false).some(([name]) => name === 'icon');
       const secondary = resolve(headerProps.get('secondaryActions'));
@@ -432,7 +582,7 @@ export function analyzeComposition(text, { filename, index, ts }) {
     const title = literal(props.get('title')) ?? literal(new Map(header).get('title'));
     if (title && parents.some(parent => parent.title === title)) add(node, 'duplicate-heading', 'warning', `The heading "${title}" repeats its ancestor. Keep one route/subject title unless a distinct task warrants repetition.`);
     const structure = owner.import === `${index.package}/base/structure` && Object.hasOwn(structureDefaults, owner.symbol);
-    return { framed, title, structure, cards: structure ? peerCards(node) : new Set(), smallGap: structure ? smallGap(props, owner.symbol, unknownProps) : false };
+    return { owner, props, unknownProps, framed, title, structure, cards: structure ? peerCards(node) : new Set(), smallGap: structure ? smallGap(props, owner.symbol, unknownProps) : false };
   }
   visit(source);
   return { findings, unresolved };

package/docs/consumer-skill/scripts/composition-schema.mjs

@@ -4,7 +4,7 @@ const name = value => typeof value === 'string' && /^[A-Za-z][A-Za-z0-9]*$/.test
 const uniqueList = (value, valid, maximum) => Array.isArray(value) && value.length <= maximum && value.every(valid) && new Set(value).size === value.length;
 const scalar = value => value === null || typeof value === 'boolean' || (typeof value === 'string' && value.length <= 500) || (typeof value === 'number' && Number.isFinite(value));
 const kinds = ['shell', 'page', 'layout', 'surface', 'content', 'workflow'];
-const placements = ['region', 'cell', 'overlay'];
+const placements = ['region', 'toolbar', 'cell', 'overlay'];
 const surfaces = ['none', 'parent', 'self', 'variant'];
 
 /** One literal metadata shape shared by authored catalogue and copied tools. */