An open source design system that's fully customizable and agent ready
schema_version: 3 template_version: 7 kind: component id: component:TableHeaderCell authority: current archive_reason: null superseded_by: null approved_by: cixzhang approved_at: 2026-11-01 owners: [cixzhang] review_triggers: [public-api, behavior, layout, theming, accessibility] verified_by: [ packages/core/src/Table/TableHeaderCell.test.tsx, packages/core/src/Table/tableContextMenu.test.tsx, packages/core/src/Table/Table.test.tsx, packages/core/src/theme/themingTargets.test.ts, scripts/check-knowledge.mjs, apps/storybook/rtl-audit/targets.json, ] modules: [] families: [] design_specs: [] architecture: [ architecture:component-theming-surface, architecture:public-component-api, architecture:container-padding, ] contributing: []
system_specs: []
TableHeaderCell component contract
Contract at a glance
| Area | Contract |
|---|---|
| Public contract | children, scope, contextMenuActions, xstyle (one style or a list), root BaseProps, and a ref. |
| Behavior | A native th carrying the table-header-cell target that takes the Table's density and column dividers, always draws its bottom divider, and truncates its text. |
| End-user impact | People see column headings set apart by weight, color, and a rule, aligned with the cells below. |
| Builder impact | None; the record describes shipped behavior. |
| Compatibility/readiness | Released behavior recorded as current; no API, default, or output changes. |
| Review checks | Reject a missing bottom divider, a scope the caller did not set, a lost target or density reflection, or caller xstyle that loses to context styling. |
| Governing rules | architecture:container-padding; architecture:public-component-api INV5–INV8; architecture:component-theming-surface. |
This table is a review projection; the body below is authoritative.
Intent
TableHeaderCell is the header cell a caller composes inside a children-mode
Table, as a column header or, with scope="row", a row header, and the column
header cell Table renders in data mode. It owns
the th and its header treatment; the caller owns the heading content.
Consumer syntax and examples belong in TableHeaderCell.doc.mjs.
Compatibility and migration
- Released default preserved:
yes— noscopeunless given. - Compatibility class: records shipped behavior; no public prop, default, DOM, target, or styling output changes.
- Controlled/uncontrolled behavior: not applicable
- Migration decision: none
Consumer migration instructions belong in consumer docs and release notes.
Ownership boundary
Owns
- The
thelement, which carries thetable-header-celltarget thatcomponent:Tableowns and maps. - Header weight, color, bottom divider, truncation, and the Table's density and column dividers on the header cell.
Does not own / non-goals
- Sorting, filtering, resizing, and selection controls in headers — owned by
component:Tableand its plugins. - Heading content — owned by the caller.
Public concepts
| Concept | Closed values or states | Meaning | Availability by variant/orientation/state | Default | Owner | Stability | Invalid-value behavior |
|---|---|---|---|---|---|---|---|
| Scope | col, row, colgroup, rowgroup; unset |
Native header scope. | Always | unset | caller | Stable | Closed union. |
| Context actions | action list or getter; unset | Actions shown in a context menu on the header. | Always | none | caller | Stable | An empty list renders no menu. |
| Content | ReactNode | The heading. | Always | — | caller | Stable | — |
Behavioral and layout contract
| ID | Invariant | Basis |
|---|---|---|
| FR1 | TableHeaderCell renders one th carrying the table-header-cell target, which reflects the Table's density, holding its content, with scope only when given. Outside a Table it adds no header treatment. |
Current source and tests |
| FR2 | Inside a Table, the header cell uses semibold --color-text-secondary text aligned to the start, pads by the Table's density, truncates its text, aligns its outer edge cells to the container inset like component:TableCell FR3, and always draws a --border-width --color-border bottom divider, even when the Table's dividers are off. With columns or grid dividers it draws an inline-end divider that the last header cell omits. |
Current source and tests |
| FR3 | With context actions, the content sits in a context menu trigger. | Current source and tests |
| FR4 | ref reaches the th; supported DOM, data, ARIA, and event props reach it before the component's target and styles; xstyle (one style or a list) wins over the context styling, and className and style compose alongside the target. |
Current source and tests; architecture:public-component-api INV5–INV8 |
Allowed variation
- AV1 — Content. Any heading content may fill the cell.
Representative states
| State | Required invariant | Allowed variation |
|---|---|---|
| Standalone | A th with the target and no treatment. |
— |
| Each density | Density padding and data-density. |
— |
| Dividers off | The bottom divider still draws. | — |
| Column dividers | Inline-end divider except on the last header cell. | — |
Transformation and precedence order
- ORD1 — Styles. Header treatment → column divider → caller
xstyle,className, andstyle.
Performance and resources
- PR1 — No resources. TableHeaderCell reads the Table's appearance and holds no state.
Accessibility contract
- AR1 — Native header semantics. The
thkeeps its native header role — a column header, or a row header underscope="row"or"rowgroup"— with the caller'sscopewhen given; truncation is visual only, so the full heading remains its accessible content.
Design relationships
| Anatomy or state | Design requirement | Representation authority | Hierarchy role | Component contract |
|---|---|---|---|---|
| Column header cell | A heading cell set apart by weight, color, and a bottom rule. | Current source and docs | Supporting | FR1, FR2 |
Theming: the th carries the table-header-cell target, which Table.doc.mjs
maps as the Column header cell part of component:Table.
TableHeaderCell.doc.mjs declares no anatomy of its own, so no anatomy-theming
block is declared here.
Family and system relationships
component:Tableowns appearance settings, header controls, and the target mapping.component:TableCellFR3 defines the edge alignment the header cell shares.
Verification map
| Contract | Verification | Representative states | Mutation or failure expectation | Audit section |
|---|---|---|---|---|
| FR1, AR1 | TableHeaderCell.test.tsx element, scope, and outside-Table tests; Table.test.tsx density-reflection test; themingTargets.test.ts |
Default; scope; standalone; densities |
A non-th element, an unrequested or missing scope, styling outside a Table, or a missing target or data-density fails. themingTargets.test.ts catches only a renamed or undocumented target. |
audit:TableHeaderCell/anatomy |
| FR2 | TableHeaderCell.test.tsx density, weight and color, bottom divider, and column divider tests |
Three densities; dividers off, rows, columns, grid | Wrong density padding, weight, or color, a missing bottom divider, or a wrong column divider fails. Gap: truncation and edge alignment have no check. | audit:TableHeaderCell/layout |
| FR3 | tableContextMenu.test.tsx header context-menu tests |
Header cell with actions | A header cell with actions that does not open its menu, or one without actions that does, fails. | audit:TableHeaderCell/behavior |
| FR4, ORD1 | TableHeaderCell.test.tsx xstyle, array xstyle, ref, attribute, and className and style tests |
Caller inputs | A ref off the th, a dropped attribute, context styling that beats xstyle, or a lost caller class or style fails. |
audit:TableHeaderCell/api |
| PR1 | Source review | Every state | Gap: no automated check fails if TableHeaderCell adds state. | audit:TableHeaderCell/behavior |
| RTL relation | RTL audit curated D2 and D8 targets (apps/storybook/rtl-audit/targets.json) on the In Card story |
A Card with padding={0}, where the first column's logical inline-start padding differs from its inline-end padding; LTR and RTL |
A first column not at the inline start, or an edge padding that stays on the same physical side in RTL, fails D2 or D8. | audit:TableHeaderCell/i18n-rtl |
Decision log
None recorded. The record describes shipped behavior.
Open questions
None.
Content boundary
This file does not duplicate consumer prop tables/examples, current audit results, implementation steps, or Table rules. It links to their owners.