@astryxdesign/core 0.5.2-canary.c9c8564 → 0.5.2-canary.e03511b

package/src/Switch/Switch.spec.md

@@ -0,0 +1,174 @@
+---
+schema_version: 1
+template_version: 3
+kind: component
+id: component:Switch
+authority: draft
+archive_reason: null
+superseded_by: null
+approved_by: null
+approved_at: null
+owners: [cixzhang]
+review_triggers: [theming]
+verified_by:
+  [
+    packages/core/src/Switch/Switch.test.tsx,
+    packages/core/src/theme/themingTargets.test.ts,
+    scripts/check-knowledge.mjs,
+  ]
+families: []
+design_specs: []
+architecture: [architecture:component-theming-surface]
+contributing: []
+system_specs: []
+---
+
+# Switch component contract
+
+## Intent
+
+Switch presents a labeled boolean control whose change takes effect immediately.
+This draft records current consumer anatomy and theming ownership without
+changing runtime behavior, styling, targets, or public API.
+
+## Compatibility and migration
+
+- Released default preserved: `yes`
+- Compatibility class: additive documentation only; runtime, DOM, styling,
+  targets, and public API remain unchanged
+- Controlled/uncontrolled behavior: unchanged; Switch remains controlled
+- Migration decision: none
+
+Consumer migration instructions belong in consumer docs and release notes.
+
+## Ownership boundary
+
+**Owns**
+
+- The switch field, track, thumb, and label presentations represented by the
+  existing `switch-field`, `switch`, `switch-thumb`, and `switch-label` targets.
+
+**Does not own / non-goals**
+
+- Description styling through a dedicated public target; none currently exists.
+- Validation-message presentation — owned by `component:FieldStatus`.
+- Loading-indicator presentation — owned by `component:Spinner`.
+- Tooltip surfaces used for shared label and disabled-reason behavior.
+
+## Public concepts
+
+No new public concept is introduced. Consumer props, states, and usage remain
+documented in `Switch.doc.mjs`.
+
+## Behavioral and layout contract
+
+| ID  | Candidate invariant                                                                                    | Basis                                   | Draft review state                                 |
+| --- | ------------------------------------------------------------------------------------------------------ | --------------------------------------- | -------------------------------------------------- |
+| FR1 | The current render places a thumb inside the switch track and arranges that control with its label.    | Current source, docs, and focused tests | Verified current behavior; no new behavior decided |
+| FR2 | The field, track, thumb, and label carry their existing local targets.                                 | Current source, public docs, and tests  | Verified current behavior; no target change        |
+| FR3 | A busy switch renders Spinner inside the thumb; a status message renders through detached FieldStatus. | Current source, docs, and focused tests | Verified conditional composition                   |
+
+### Allowed variation
+
+- Label position and spacing, size, checked state, and disabled state remain
+  current target capabilities rather than separate anatomy parts.
+- A description may be absent without changing the remaining anatomy.
+
+### Representative states
+
+| State               | Required invariant                                      | Allowed variation                      |
+| ------------------- | ------------------------------------------------------- | -------------------------------------- |
+| Off or on           | Track, thumb, and label render within the switch field. | Checked state, size, label placement   |
+| Busy                | Spinner renders inside the thumb.                       | Controlled or optimistic checked value |
+| Status with message | Detached FieldStatus follows the switch row.            | Error, warning, or success status      |
+
+### Transformation and precedence order
+
+- No new state, event, layout, or styling precedence rule is introduced.
+
+### Performance and resources
+
+- No new performance or resource rule is introduced.
+
+## Accessibility contract
+
+This draft does not change or extend Switch's existing accessible name, switch
+role, checked state, busy state, description/status association, or disabled
+behavior.
+
+## Design relationships
+
+| Anatomy or state | Design requirement                                       | Representation authority        | Hierarchy role | Component contract |
+| ---------------- | -------------------------------------------------------- | ------------------------------- | -------------- | ------------------ |
+| Field            | Arranges the switch control with its label and feedback. | Current source and public docs  | Supporting     | FR1, FR2           |
+| Track and thumb  | Present the current on/off control.                      | Current source and public docs  | Prominent      | FR1, FR2           |
+| Label            | Identifies the controlled setting.                       | Current source and public docs  | Prominent      | FR1, FR2           |
+| Spinner/status   | Present conditional progress and validation feedback.    | Current shared-component source | Supporting     | FR3                |
+
+### Theming anatomy
+
+<!-- anatomy-theming:v1 -->
+
+```json
+{
+  "Field": {"target": "switch-field"},
+  "Track": {"target": "switch"},
+  "Thumb": {"target": "switch-thumb"},
+  "Label": {"target": "switch-label"},
+  "Description": {
+    "none": {
+      "reason": "unsettled: No current public target reaches the stable Description; future exposure still needs an owner decision"
+    }
+  },
+  "Spinner": {
+    "delegatesTo": {"owner": "component:Spinner", "target": "spinner"}
+  },
+  "Status message": {
+    "delegatesTo": {
+      "owner": "component:FieldStatus",
+      "target": "field-status"
+    }
+  }
+}
+```
+
+`Description` remains stable consumer anatomy, but no current public target
+reaches it. The map classifies future exposure as unsettled rather than silently
+making the absence intentional.
+
+## Family and system relationships
+
+- `architecture:component-theming-surface` owns anatomy qualification, factual
+  `none` dispositions, and composition-preserving target ownership.
+- FieldStatus and Spinner retain their existing public target contracts when
+  composed by Switch.
+
+## Verification map
+
+| Contract            | Verification                                                      | Representative states                      | Mutation or failure expectation                                                                                                 | Audit section          |
+| ------------------- | ----------------------------------------------------------------- | ------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------- | ---------------------- |
+| FR1                 | `Switch.test.tsx` structure and interaction suites                | On/off, size, label position, hidden label | Removing or reordering stable parts breaks existing role, label, or DOM assertions.                                             | `audit:Switch/anatomy` |
+| FR2                 | `Switch.test.tsx` label-target suite and `themingTargets.test.ts` | Current local targets                      | Removing the label target fails focused coverage; source/docs drift fails the target guard.                                     | `audit:Switch/theming` |
+| FR3                 | `Switch.test.tsx` loading and status suites                       | Busy and detached status                   | Removing composed feedback breaks existing spinner, busy-state, or message assertions.                                          | `audit:Switch/anatomy` |
+| Theming anatomy map | `scripts/check-knowledge.mjs`                                     | Canonical anatomy and all current targets  | Canonical-key drift, invalid dispositions or target spelling, or an unclaimed current local target fails repository validation. | `audit:Switch/theming` |
+
+The focused Switch suite pins `switch-label`, but does not separately assert the
+exact `switch-field`, `switch`, or `switch-thumb` class placement. The
+source/metadata target guard covers those local declarations. No current
+repository check resolves `delegatesTo` owner/target pairs; the pairs in this
+draft were verified manually, so semantic delegation drift remains a validation
+gap.
+
+## Decision log
+
+None. This draft records current facts and introduces no component-local design
+or API decision.
+
+## Open questions
+
+None.
+
+## Content boundary
+
+This file does not duplicate consumer prop tables, examples, implementation
+steps, or shared-component contracts. It links to their owners.

package/src/Table/Table.doc.mjs

@@ -1,5 +1,104 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
+/** @type {import('@astryxdesign/cli/authoring').ComponentAnatomyElement[]} */
+const anatomy = [
+  {
+    name: 'Table',
+    required: true,
+    description:
+      'Semantic table element that groups the table sections, rows, and cells.',
+  },
+  {
+    name: 'Scroll region',
+    required: true,
+    description:
+      'Keyboard-focusable outer region that scrolls horizontally when the columns overflow.',
+  },
+  {
+    name: 'Header section',
+    required: false,
+    description:
+      'Column-heading section generated when data-driven columns are present or supplied with TableHeader in children mode.',
+  },
+  {
+    name: 'Column header cell',
+    required: false,
+    description:
+      'Cell that identifies one column and may contain sorting or bulk-selection controls.',
+  },
+  {
+    name: 'Sort control',
+    required: false,
+    description:
+      "Button that wraps a sortable column label and changes that column's sort direction.",
+  },
+  {
+    name: 'Sort indicator glyph',
+    required: false,
+    description: 'Directional symbol rendered by Icon inside a Sort control.',
+  },
+  {
+    name: 'Sort priority',
+    required: false,
+    description:
+      'Number shown for a sorted column when multi-column sorting is active.',
+  },
+  {
+    name: 'Selection control',
+    required: false,
+    description:
+      'CheckboxInput rendered in the header and selectable body rows by the selection plugin.',
+  },
+  {
+    name: 'Body section',
+    required: true,
+    description:
+      'Section containing data rows or the current empty state; data-driven mode renders it automatically.',
+  },
+  {
+    name: 'Row',
+    required: false,
+    description:
+      'Repeated TableRow that groups cells in a standard header, body, or footer row.',
+  },
+  {
+    name: 'Cell',
+    required: false,
+    description:
+      'TableCell containing one value or caller-provided content in a standard body or footer row.',
+  },
+  {
+    name: 'Default empty state',
+    required: false,
+    description:
+      'Compact EmptyState shown for an empty data array unless it is replaced or disabled.',
+  },
+  {
+    name: 'Expansion control',
+    required: false,
+    description:
+      'Button in a leading cell that expands or collapses one expandable row.',
+  },
+  {
+    name: 'Expansion glyph',
+    required: false,
+    description:
+      'Directional symbol rendered by Icon inside an Expansion control.',
+  },
+  {
+    name: 'Expanded detail panel',
+    required: false,
+    description:
+      'Detail row and spanning cell rendered below an expanded row around caller-provided content.',
+  },
+  {
+    name: 'Footer section',
+    required: false,
+    description:
+      'Optional summary or totals section supplied with TableFooter in children mode.',
+  },
+];
+
 /** @type {import('@astryxdesign/cli/authoring').ComponentDoc} */
 
 export const docs = {
@@ -147,14 +246,7 @@ export const docs = {
       { guidance: false, description: 'Enable every plugin at once. Add only the features your use case requires to keep the interface focused.' },
       { guidance: false, description: 'Omit width on text-heavy columns; without an explicit proportional() width they have no minimum and can squish to near-zero on mobile.' },
     ],
-    anatomy: [
-      {name: 'Column Header', required: true, description: 'Displays titles, sorting controls, and bulk selection.'},
-      {name: 'Body Rows', required: true, description: 'Rows with consistent data structure.'},
-      {name: 'Footer', required: false, description: 'Displays summary or totals.'},
-      {name: 'Top Bar', required: false, description: 'Contains title, toolbar, and filters.'},
-      {name: 'Bottom Bar', required: false, description: 'Contains pagination controls.'},
-      {name: 'Support Panels', required: false, description: 'Displays row details in a side panel.'},
-    ],
+    anatomy,
   },
 };
 
@@ -169,14 +261,7 @@ export const docsZh = {
       { guidance: false, description: 'Use a table for data without consistent columns. Use a list or card layout for heterogeneous content.' },
       { guidance: false, description: 'Enable every plugin at once. Add only the features your use case requires to keep the interface focused.' },
     ],
-    anatomy: [
-      {name: 'Column Header', required: true, description: 'Displays titles, sorting controls, and bulk selection.'},
-      {name: 'Body Rows', required: true, description: 'Rows with consistent data structure.'},
-      {name: 'Footer', required: false, description: 'Displays summary or totals.'},
-      {name: 'Top Bar', required: false, description: 'Contains title, toolbar, and filters.'},
-      {name: 'Bottom Bar', required: false, description: 'Contains pagination controls.'},
-      {name: 'Support Panels', required: false, description: 'Displays row details in a side panel.'},
-    ],
+    anatomy,
   },
 };
 
@@ -196,13 +281,6 @@ export const docsDense = {
       { guidance: false, description: 'Enable every plugin at once. Add only the features your use case requires to keep the interface focused.' },
       { guidance: false, description: 'Omit width on text-heavy columns; w/o explicit proportional() width they have no minimum and can squish to near-zero on mobile.' },
     ],
-    anatomy: [
-      {name: 'Column Header', required: true, description: 'Displays titles, sorting controls, and bulk selection.'},
-      {name: 'Body Rows', required: true, description: 'Rows with consistent data structure.'},
-      {name: 'Footer', required: false, description: 'Displays summary or totals.'},
-      {name: 'Top Bar', required: false, description: 'Contains title, toolbar, and filters.'},
-      {name: 'Bottom Bar', required: false, description: 'Contains pagination controls.'},
-      {name: 'Support Panels', required: false, description: 'Displays row details in a side panel.'},
-    ],
+    anatomy,
   },
 };

package/src/Table/Table.spec.md

@@ -0,0 +1,283 @@
+---
+schema_version: 1
+template_version: 3
+kind: component
+id: component:Table
+authority: draft
+archive_reason: null
+superseded_by: null
+approved_by: null
+approved_at: null
+owners: [cixzhang]
+review_triggers: [public-api, behavior, layout, theming, accessibility]
+verified_by:
+  [
+    packages/core/src/Table/Table.test.tsx,
+    packages/core/src/Table/plugins/selection/useTableSelection.test.tsx,
+    packages/core/src/Table/plugins/sortable/useTableSortable.test.tsx,
+    packages/core/src/Table/plugins/rowExpansion/useTableRowExpansion.test.tsx,
+    packages/cli/foundation/discovery/theming-targets.test.mjs,
+    packages/cli/api/theme/targets/targets.test.mjs,
+    packages/core/src/theme/themingTargets.test.ts,
+    scripts/check-knowledge.mjs,
+  ]
+families: []
+design_specs: []
+architecture:
+  [
+    architecture:component-theming-surface,
+    architecture:container-padding,
+    architecture:interaction-modality,
+    architecture:public-component-api,
+  ]
+contributing: []
+system_specs: []
+---
+
+# Table component contract
+
+## Intent
+
+Table presents consistently structured data in semantic rows and columns. This
+draft records its current aggregate anatomy, parent-owned target inventory, and
+stable sorting, selection, expansion, and empty-state parts without changing
+runtime behavior, DOM, styling, targets, aliases, or public API.
+
+## Compatibility and migration
+
+- Released default preserved: `yes`
+- Compatibility class: additive documentation only; runtime, DOM, styling,
+  targets, aliases, and public API remain unchanged
+- Controlled/uncontrolled behavior: unchanged
+- Migration decision: none
+
+Consumer migration instructions belong in consumer docs and release notes.
+
+## Ownership boundary
+
+**Owns**
+
+- The Table and Scroll region, the aggregate Header section, Body section,
+  conditional Footer section, Row, Column header cell, and Cell anatomy, and the
+  eight current `table*` targets mapped below.
+- The stable Sort control and Sort priority rendered by useTableSortable.
+- The stable Expansion control and Expanded detail panel rendered by
+  useTableRowExpansion.
+- Placement of selection-plugin CheckboxInput controls in generated header and
+  body cells.
+
+**Does not own / non-goals**
+
+- CheckboxInput visuals, Icon glyphs, or the default EmptyState surface; those
+  remain owned by their respective components.
+- Cell values, custom cell renderers, custom empty states, footer content, or
+  expanded detail content supplied by the caller.
+- Pagination, filtering, column-management, tree, grouping, sticky-column, or
+  context-menu anatomy beyond the stable parts explicitly recorded here.
+- New targets for current untargeted plugin parts, or correction of current
+  target-reachability gaps.
+- New runtime behavior, DOM, API, target, alias, or plugin contract.
+
+## Public concepts
+
+No new public concept is introduced. Consumer data, columns, props, composition,
+plugins, defaults, and usage remain documented in `Table.doc.mjs` and the member
+and hook docs.
+
+## Behavioral and layout contract
+
+| ID  | Candidate invariant                                                                                                                                                                                                                                                                                      | Basis                             | Draft review state                                                        |
+| --- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------- | ------------------------------------------------------------------------- |
+| FR1 | Styled Table renders one keyboard-focusable Scroll region around one semantic Table.                                                                                                                                                                                                                     | Current source, docs, and tests   | Verified current behavior; no new behavior decided                        |
+| FR2 | Data-driven mode renders a Body section and a Header section with Column header cells when columns are present. Each data item renders a standard Row and Cells; an empty data array instead renders the configured empty-state row when enabled. It never creates a Footer section.                     | Current source, docs, and tests   | Verified current behavior; no new behavior decided                        |
+| FR3 | Children mode passes caller composition through to the Table. TableHeader, TableBody, and TableFooter provide the respective sections, and TableRow, TableHeaderCell, and TableCell provide standard rows and cells.                                                                                     | Current source, docs, and tests   | Verified current composition; no new API or DOM rule                      |
+| FR4 | `Table.doc.mjs` is the canonical aggregate consumer owner for the eight current targets: `table`, `table-scroll-wrapper`, `table-header`, `table-body`, `table-footer`, `table-row`, `table-cell`, and `table-header-cell`. Member docs retain direct lookup metadata through `subComponentOf: 'Table'`. | Current docs and CLI target tests | Verified parent ownership; focused placement coverage is partial          |
+| FR5 | For a sortable column, useTableSortable renders a Sort control around the column label, an Icon-owned Sort indicator glyph, and a numeric Sort priority only while multi-sort has more than one active entry.                                                                                            | Current source, docs, and tests   | Control and priority are tested; glyph presence is source-inspected only  |
+| FR6 | useTableSelection renders CheckboxInput-owned Selection controls in the generated selection Column header cell and each selectable body Cell; selection remains row state rather than separate anatomy.                                                                                                  | Current source, docs, and tests   | Verified stable delegated controls; no target or state change             |
+| FR7 | For an expandable row, useTableRowExpansion renders an Expansion control with an Icon-owned Expansion glyph and conditionally appends an Expanded detail panel whose cell spans the column count captured by that plugin's `transformColumns` step.                                                      | Current source, docs, and tests   | Verified stable plugin parts; current target gaps remain                  |
+| FR8 | Empty data renders the default compact EmptyState unless the caller supplies replacement content or disables it.                                                                                                                                                                                         | Current source, docs, and tests   | Verified conditional delegation; caller content remains outside ownership |
+
+### Current evidence and gaps
+
+- The `table`, `table-scroll-wrapper`, `table-row`, `table-cell`, and
+  `table-header-cell` placements have focused runtime assertions. The
+  `table-header`, `table-body`, and `table-footer` placements are source-inspected;
+  existing section tests assert element structure and prop forwarding but not the
+  target classes.
+- Sort tests assert the Sort control, labels, state, and conditional priority, but
+  the test named `renders sort icon for sortable columns` checks only the buttons.
+  Sort indicator glyph presence is source-inspected and lacks focused regression
+  evidence. Selection and expansion suites assert their stable controls, states,
+  and panel structure; delegated Icon and CheckboxInput target classes also remain
+  source-inspected.
+- The Expanded detail panel uses raw `tr` and `td` elements rather than TableRow
+  and TableCell, so the existing `table-row` and `table-cell` targets do not reach
+  that panel wrapper. Its `colSpan` comes from the column count captured when the
+  expansion plugin runs `transformColumns`; a later custom plugin can add or remove
+  columns and leave the span stale. The current full-span test covers only the case
+  where expansion captures the final column set. This draft records both gaps and
+  does not correct them.
+
+### Allowed variation
+
+- **AV1 - Rendering mode.** Data-driven mode generates sections, rows, and cells;
+  children mode uses the caller-supplied composition without changing aggregate
+  ownership.
+- **AV2 - Repetition and content.** Column, Row, and Cell counts and caller-owned
+  content may vary without creating new anatomy parts.
+- **AV3 - Optional parts.** Header section, Footer section, default EmptyState,
+  Sort, Selection, and Expansion parts may be absent according to columns,
+  rendering mode, plugin configuration, data, and row eligibility.
+- **AV4 - Delegated rendering.** CheckboxInput, Icon, and EmptyState may change
+  internal element shape while preserving their own public contracts.
+
+### Representative states
+
+| State            | Required invariant                                                                                                                              | Allowed variation                                                          |
+| ---------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------- |
+| Data-driven rows | Scroll region contains Table, Header section when columns exist, Body section, and one standard Row with Cells per data item.                   | Counts, values, density, dividers, and cell content.                       |
+| Empty data       | Body section contains default EmptyState unless replaced or disabled.                                                                           | Caller replacement content or no empty state.                              |
+| Children mode    | Caller-supplied sections are passed directly to Table.                                                                                          | Header, Body, and Footer section presence and content.                     |
+| Sortable column  | Column header cell contains Sort control and Sort indicator glyph.                                                                              | Direction and conditional multi-sort priority.                             |
+| Selectable rows  | Selection controls occupy generated header and body cells.                                                                                      | Checked, indeterminate, disabled, or absent per row.                       |
+| Expandable row   | Expansion control occupies a generated Cell; open state adds the detail panel after its row using the expansion plugin's captured column count. | Expanded state, caller detail content, and later plugin column transforms. |
+
+### Transformation and precedence order
+
+- No new plugin ordering, column transformation, slot placement, wrapping,
+  sizing, or styling precedence rule is introduced.
+
+### Performance and resources
+
+- No new performance or resource rule is introduced. Existing memoization and
+  plugin-specific render behavior remain outside this documentation change.
+
+## Accessibility contract
+
+This draft does not change or extend the current native table semantics,
+focusable Scroll region, column-header scope, sort `aria-sort`, selection
+`aria-selected`, CheckboxInput labels, or expansion `aria-expanded` behavior.
+
+## Design relationships
+
+| Anatomy or state      | Design requirement                                                                | Representation authority       | Hierarchy role | Component contract |
+| --------------------- | --------------------------------------------------------------------------------- | ------------------------------ | -------------- | ------------------ |
+| Table                 | Groups the semantic table structure.                                              | Current source and public docs | Supporting     | FR1-FR4            |
+| Scroll region         | Provides keyboard-reachable horizontal overflow around Table.                     | Current source and public docs | Supporting     | FR1, FR4           |
+| Header section        | Groups Column header cells separately from body data.                             | Current source and public docs | Supporting     | FR2-FR4            |
+| Column header cell    | Identifies one column and hosts optional header controls.                         | Current source and public docs | Prominent      | FR2-FR6            |
+| Sort control          | Activates sorting for one sortable column.                                        | Current source and public docs | Prominent      | FR5                |
+| Sort indicator glyph  | Shows the current sort direction through Icon.                                    | `component:Icon`               | Supporting     | FR5                |
+| Sort priority         | Shows a column's position in active multi-sort order.                             | Current source and public docs | Supporting     | FR5                |
+| Selection control     | Selects all eligible rows or one eligible row through CheckboxInput.              | `component:CheckboxInput`      | Prominent      | FR6                |
+| Body section          | Groups data, empty-state, and expanded-detail rows.                               | Current source and public docs | Supporting     | FR2-FR4, FR7, FR8  |
+| Row                   | Groups standard header, body, or footer cells.                                    | Current source and public docs | Supporting     | FR2-FR4, FR6       |
+| Cell                  | Contains one value or caller-provided content in a standard body or footer row.   | Current source and public docs | Prominent      | FR2-FR4, FR6, FR7  |
+| Default empty state   | Communicates that the current data array has no rows through EmptyState.          | `component:EmptyState`         | Prominent      | FR8                |
+| Expansion control     | Expands or collapses one eligible row.                                            | Current source and public docs | Prominent      | FR7                |
+| Expansion glyph       | Shows the current expansion direction through Icon.                               | `component:Icon`               | Supporting     | FR7                |
+| Expanded detail panel | Presents caller-provided detail content in a spanning row below the expanded row. | Current source and public docs | Prominent      | FR7                |
+| Footer section        | Groups caller-supplied summary or total rows below the body.                      | Current source and public docs | Supporting     | FR3, FR4           |
+
+### Theming anatomy
+
+<!-- anatomy-theming:v1 -->
+
+```json
+{
+  "Table": {"target": "table"},
+  "Scroll region": {"target": "table-scroll-wrapper"},
+  "Header section": {"target": "table-header"},
+  "Column header cell": {"target": "table-header-cell"},
+  "Sort control": {"inherits": "table-header-cell"},
+  "Sort indicator glyph": {
+    "delegatesTo": {"owner": "component:Icon", "target": "icon"}
+  },
+  "Sort priority": {
+    "none": {
+      "reason": "unsettled: The multi-sort rank has no direct public target and uses a component-owned accent style; future exposure still needs an owner decision"
+    }
+  },
+  "Selection control": {
+    "delegatesTo": {
+      "owner": "component:CheckboxInput",
+      "target": "checkbox-input"
+    }
+  },
+  "Body section": {"target": "table-body"},
+  "Row": {"target": "table-row"},
+  "Cell": {"target": "table-cell"},
+  "Default empty state": {
+    "delegatesTo": {"owner": "component:EmptyState", "target": "empty-state"}
+  },
+  "Expansion control": {
+    "none": {
+      "reason": "unsettled: The expansion button has no direct public target and uses component-owned styles; future exposure still needs an owner decision"
+    }
+  },
+  "Expansion glyph": {
+    "delegatesTo": {"owner": "component:Icon", "target": "icon"}
+  },
+  "Expanded detail panel": {
+    "none": {
+      "reason": "reachability-gap: The plugin renders its detail row and cell as raw elements, so the current table-row and table-cell targets do not reach the panel wrapper"
+    }
+  },
+  "Footer section": {"target": "table-footer"}
+}
+```
+
+The exact map records all eight current non-deprecated Table targets once. The
+legacy `base-table` alias is compatibility, not anatomy. TableHeader, TableBody,
+TableFooter, TableRow, TableCell, and TableHeaderCell retain direct docs linked by
+`subComponentOf: 'Table'`; they do not need independent component specs for this
+aggregate ownership.
+
+## Family and system relationships
+
+- `architecture:component-theming-surface` owns anatomy qualification, exact
+  target mapping, delegation, inheritance, factual `none` classifications, and
+  the rule that deprecated aliases do not count as anatomy.
+- `architecture:container-padding` owns the inherited inset protocol consumed by
+  the Scroll region and Cell edge compensation.
+- `architecture:interaction-modality` owns shared keyboard and pointer modality;
+  Table and its plugins retain their current local interactions.
+- `architecture:public-component-api` owns the stable props, components, hooks,
+  exports, and compatibility boundary; this documentation adds no API.
+
+## Verification map
+
+| Contract            | Verification                                                                                         | Representative states                                  | Mutation or failure expectation                                                                                                                                                                                                                                           | Audit section         |
+| ------------------- | ---------------------------------------------------------------------------------------------------- | ------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------- |
+| FR1-FR3             | `Table.test.tsx` render, structure, children-mode, section, and target assertions                    | Data-driven rows, empty data, and children composition | Removing Table, Scroll region, or configured structure fails existing role, structure, class, or prop-forwarding assertions; Row and Cell are conditional on rendered data or caller composition.                                                                         | `audit:Table/anatomy` |
+| FR4                 | CLI discovery and API target tests plus source inspection                                            | Direct member docs and unfiltered/scoped target output | Duplicating a parent/member target or changing the canonical owner fails parent-aware discovery assertions; section target placement remains source-inspected.                                                                                                            | `audit:Table/theming` |
+| FR5                 | `plugins/sortable/useTableSortable.test.tsx` plus source inspection                                  | Unsorted, ascending, descending, and multi-sort        | Removing the Sort control, conditional priority, or ARIA state fails existing assertions. Removing the Sort indicator glyph does not currently fail a focused test; glyph presence and delegated Icon target placement remain source-inspected.                           | `audit:Table/anatomy` |
+| FR6                 | `plugins/selection/useTableSelection.test.tsx`                                                       | Select all, individual, disabled, and non-selectable   | Removing header/body Selection controls or row selection state fails existing structure, label, interaction, and ARIA assertions; delegated CheckboxInput target placement remains source-inspected.                                                                      | `audit:Table/anatomy` |
+| FR7                 | `plugins/rowExpansion/useTableRowExpansion.test.tsx` plus source inspection                          | Collapsed, expanded, and non-expandable rows           | Removing the Expansion control, conditional detail panel, captured-count `colSpan`, or ARIA state fails existing assertions in the covered plugin order; later column transforms, delegated Icon target placement, and untargeted panel wrappers remain source-inspected. | `audit:Table/anatomy` |
+| FR8                 | `Table.test.tsx` empty-state suite plus EmptyState public target metadata                            | Default, custom, disabled, and non-empty               | Removing conditional empty behavior fails existing assertions; default EmptyState delegation remains source-inspected.                                                                                                                                                    | `audit:Table/anatomy` |
+| Theming anatomy map | `scripts/check-knowledge.mjs`, `themingTargets.test.ts`, and CLI parent-aware target discovery tests | Canonical anatomy, eight current targets, legacy alias | Missing, extra, duplicated, prefixed, stale, alias-backed, or independently owned member mappings fail repository validation or discovery coverage.                                                                                                                       | `audit:Table/theming` |
+
+## Decision log
+
+None. This draft records current facts and the user-directed canonical parent
+ownership without introducing a component-local design, API, behavior, layout,
+or theming decision.
+
+## Open questions
+
+- **OQ1 - Should the current untargeted Sort priority, Expansion control, or
+  Expanded detail panel gain direct public theming targets?** (`human-api`) This
+  factual map does not decide future exposure.
+- **OQ2 - Should focused runtime tests pin the Sort indicator glyph, the
+  `table-header`, `table-body`, and `table-footer` target classes, and delegated
+  component target placement?** (`checkable`) Current evidence is source
+  inspection plus structural and global inventory tests.
+- **OQ3 - Should row expansion derive its panel span after all column transforms?**
+  (`checkable`) A later custom `transformColumns` plugin can currently make the
+  captured count stale.
+
+## Content boundary
+
+This file does not duplicate consumer prop tables or examples, plugin usage,
+container-padding mechanics, shared modality rules, current audit results, or
+implementation steps. It links to their owners.