@astryxdesign/charts 0.6.2-canary.2b2113d → 0.6.2-canary.413fa55

package/dist/ChartGrid.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ChartGrid.d.ts","sourceRoot":"","sources":["../src/ChartGrid.tsx"],"names":[],"mappings":"AAeA,MAAM,WAAW,cAAc;IAC7B,mDAAmD;IACnD,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,kDAAkD;IAClD,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB;;;;OAIG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AASD;;;;;;;;;;;GAWG;AACH,wBAAgB,SAAS,CAAC,EACxB,UAAiB,EACjB,QAAgB,EAChB,SAAa,GACd,EAAE,cAAc,+BAmEhB"}
+{"version":3,"file":"ChartGrid.d.ts","sourceRoot":"","sources":["../src/ChartGrid.tsx"],"names":[],"mappings":"AAgBA,MAAM,WAAW,cAAc;IAC7B,mDAAmD;IACnD,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,kDAAkD;IAClD,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB;;;;OAIG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AASD;;;;;;;;;;;GAWG;AACH,wBAAgB,SAAS,CAAC,EACxB,UAAiB,EACjB,QAAgB,EAChB,SAAa,GACd,EAAE,cAAc,+BAmEhB"}

package/dist/ChartGrid.js

@@ -2,6 +2,7 @@
 
 /**
  * @file ChartGrid.tsx (v2)
+ * @input Chart context scales and dimensions, guide visibility, and tick density
  * @output Grid lines behind chart marks
  * @position Child of Chart v2; reads scales from chart context
  */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@astryxdesign/charts",
-  "version": "0.6.2-canary.2b2113d",
+  "version": "0.6.2-canary.413fa55",
   "description": "Astryx charts — a config-model data visualization library (d3-based). Published to npm only under the @canary dist-tag for early testing; never released as a stable (latest) version.",
   "author": "Meta Open Source",
   "license": "MIT",
@@ -47,7 +47,7 @@
   },
   "peerDependencies": {
     "@stylexjs/stylex": ">=0.10.0",
-    "@astryxdesign/core": "0.6.2-canary.2b2113d",
+    "@astryxdesign/core": "0.6.2-canary.413fa55",
     "react": ">=19.0.0",
     "react-dom": ">=19.0.0"
   },
@@ -57,7 +57,7 @@
     "d3-shape": "^3.2.0"
   },
   "devDependencies": {
-    "@astryxdesign/cli": "0.6.2-canary.2b2113d",
+    "@astryxdesign/cli": "0.6.2-canary.413fa55",
     "@babel/cli": "^7.29.7",
     "@babel/core": "^7.29.7",
     "@babel/preset-react": "^7.29.7",

package/src/ChartGrid.doc.mjs

@@ -0,0 +1,114 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/** @type {import('@astryxdesign/cli/authoring').ComponentDoc} */
+
+export const docs = {
+  name: 'ChartGrid',
+  displayName: 'Chart Grid',
+  group: 'Charts',
+  category: 'Data Visualization',
+  isHiddenFromOverview: true,
+  keywords: ['chart', 'grid', 'guides', 'axis', 'ticks', 'data visualization'],
+
+  usage: {
+    description:
+      'ChartGrid draws horizontal and vertical guide lines from the scales owned by a parent Chart. Use it in the Chart grid slot so guides share the plot dimensions and tick values used by the chart.',
+    bestPractices: [
+      {
+        guidance: true,
+        description:
+          'Pair ChartGrid with ChartAxis when readers need labelled values beside the guide lines.',
+      },
+      {
+        guidance: true,
+        description:
+          'Use horizontal guides for value comparison and add vertical guides only when they help readers align categories or continuous x values.',
+      },
+      {
+        guidance: false,
+        description:
+          'Use grid lines as the only way to communicate a value or distinction. Keep meaningful chart information in labels, marks, and the parent Chart alternative.',
+      },
+      {
+        guidance: false,
+        description:
+          'Expect tickCount to thin categorical band centers. It requests density only for continuous scales; categorical vertical guides render once per band.',
+      },
+    ],
+    accessibility: [
+      {
+        name: 'Chart alternative',
+        category: 'Content',
+        criterion: '1.1.1 Non-text Content',
+        requirement: 'Required on the parent Chart',
+        states: ['All'],
+        description:
+          'Chart owns the accessible image name and supported small-data table. Grid lines supplement that chart-level alternative rather than replacing it.',
+      },
+      {
+        name: 'Visual-only guides',
+        category: 'Color contrast',
+        criterion: '1.4.11 Non-text Contrast',
+        requirement: 'Do not carry information alone',
+        states: ['Horizontal', 'Vertical', 'Combined'],
+        description:
+          'Grid lines are supporting guides. Preserve visible labels, marks, or another qualifying cue so understanding does not depend on the grid alone.',
+      },
+    ],
+    anatomy: [
+      {
+        name: 'Grid lines',
+        required: false,
+        description:
+          'Horizontal lines at continuous y ticks and vertical lines at x ticks or categorical band centers.',
+      },
+    ],
+  },
+
+  props: [
+    {
+      name: 'horizontal',
+      type: 'boolean',
+      description:
+        'Whether to draw horizontal guides at continuous y ticks other than zero.',
+      default: 'true',
+    },
+    {
+      name: 'vertical',
+      type: 'boolean',
+      description:
+        'Whether to draw vertical guides at continuous x ticks or categorical band centers.',
+      default: 'false',
+    },
+    {
+      name: 'tickCount',
+      type: 'number',
+      description:
+        'Approximate guide count requested from continuous scales. It does not thin categorical band centers.',
+      default: '5',
+    },
+  ],
+
+  examples: [
+    {
+      label: 'Horizontal guides',
+      code: `import {Chart, ChartGrid, bar} from '@astryxdesign/charts';
+
+<Chart
+  data={monthlyRevenue}
+  xKey="month"
+  series={[bar('revenue')]}
+  grid={<ChartGrid />}
+/>;`,
+    },
+    {
+      label: 'Horizontal and vertical guides',
+      code: `<Chart
+  data={monthlyRevenue}
+  xKey="month"
+  series={[bar('revenue')]}
+  grid={<ChartGrid horizontal vertical tickCount={6} />}
+/>;`,
+    },
+  ],
+};

package/src/ChartGrid.spec.md

@@ -0,0 +1,184 @@
+---
+schema_version: 3
+template_version: 5
+kind: component
+id: component:ChartGrid
+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/charts/src/ChartGrid.test.tsx,
+    apps/storybook/stories/charts/ChartGrid.stories.tsx,
+  ]
+modules: []
+families: []
+design_specs: []
+architecture:
+  [
+    architecture:component-test-sufficiency,
+    architecture:component-theming-surface,
+  ]
+contributing: []
+system_specs: [spec:AST-002, spec:AST-029]
+---
+
+# ChartGrid component contract
+
+## Contract at a glance
+
+| Area                    | Contract                                                                                                                                                                         |
+| ----------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Public contract         | No API shape or default changes. This draft records the current horizontal, vertical, and continuous-scale tick-density surface.                                                 |
+| Behavior                | Horizontal guides follow continuous y ticks except zero; vertical guides follow categorical x-band centers or continuous x ticks; both directions remain independently optional. |
+| End-user impact         | Chart readers receive guide lines aligned with the parent Chart's plot scales; this audit changes no rendered behavior.                                                          |
+| Builder impact          | Existing callsites remain valid and gain direct CLI documentation and focused evidence for current density fallbacks.                                                            |
+| Compatibility/readiness | The package remains canary-only. This observational draft is non-authoritative, and exact rendered/accessibility evidence remains pending.                                       |
+| Review checks           | Reject a changed public shape/default, a guide using a scale outside Chart context, a zero baseline drawn twice, or categorical guides no longer centered on their bands.        |
+| Governing rules         | `spec:AST-029/FR3–FR7`, `architecture:component-test-sufficiency/INV1–INV11`, `architecture:component-theming-surface/INV1–INV6`, and `spec:AST-002`.                            |
+
+This table is a review projection; the body below is authoritative.
+
+## Intent
+
+ChartGrid renders passive Cartesian guide lines inside a Chart. It owns line
+selection and placement from Chart-provided scales and plot dimensions while Chart
+owns the coordinate system, rendering order, and chart-level alternative.
+
+## Compatibility and migration
+
+- Released default preserved: yes at the canary surface; the package has no stable release.
+- Compatibility class: no public API, default, or rendered-behavior change.
+- Controlled/uncontrolled behavior: not applicable.
+- Migration decision: none; this draft does not authorize a public API change.
+
+Consumer migration instructions belong in consumer docs and release notes.
+
+## Ownership boundary
+
+**Owns**
+
+- Selecting horizontal and vertical guide values from Chart-provided scales.
+- Positioning each guide across the current plot width or height.
+- Omitting the horizontal zero guide that the paired axis may emphasize.
+- Sanitizing continuous-scale tick requests before passing them to d3.
+
+**Does not own / non-goals**
+
+- Data, domains, scale construction, plot dimensions, or paint order — owned by `component:Chart`.
+- Axis labels, tick marks, or plot-edge lines — owned by `component:ChartAxis`.
+- The chart's accessible name, description, or data alternative — owned by `component:Chart` and the product callsite.
+- Product-specific decisions about whether guides are needed.
+
+## Public concepts
+
+| Concept             | Closed values or states                 | Meaning                                                       | Availability by variant/orientation/state | Default   | Owner                 | Stability    | Invalid-value behavior                                                             |
+| ------------------- | --------------------------------------- | ------------------------------------------------------------- | ----------------------------------------- | --------- | --------------------- | ------------ | ---------------------------------------------------------------------------------- |
+| Horizontal guides   | shown or hidden                         | Draws lines at continuous y ticks, excluding zero.            | Every ChartGrid                           | shown     | `component:ChartGrid` | experimental | Not applicable.                                                                    |
+| Vertical guides     | shown or hidden                         | Draws lines at x ticks or categorical x-band centers.         | Every ChartGrid                           | hidden    | `component:ChartGrid` | experimental | Not applicable.                                                                    |
+| Continuous density  | finite non-negative number              | Requests an approximate line count from d3 continuous scales. | Horizontal guides and continuous x guides | `5`       | `component:ChartGrid` | experimental | Fractions floor; values above 1000 cap; negative/non-finite values fall back to 5. |
+| Categorical density | one guide per categorical x-band center | Keeps vertical guides aligned to every band.                  | Categorical x with vertical guides        | all bands | `component:ChartGrid` | experimental | `tickCount` currently has no effect.                                               |
+| Chart context       | inside a parent `Chart`                 | Supplies scales and current plot dimensions.                  | Always                                    | none      | `component:Chart`     | experimental | Rendering outside Chart throws the shared context error.                           |
+
+## Behavioral and layout contract
+
+Draft requirements identify their basis so observed code is not mistaken for an
+intentional decision.
+
+| ID  | Candidate invariant                                                                                                                                | Basis                                                  | Draft review state |
+| --- | -------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------ | ------------------ |
+| FR1 | ChartGrid MUST consume the current width, height, x scale, and y scale from its parent Chart context.                                              | implementation, package composition, and focused tests | verify             |
+| FR2 | `horizontal` and `vertical` MUST independently enable their guide sets; enabling both MUST render both sets.                                       | implementation, JSDoc, tests, and Storybook            | verify             |
+| FR3 | Horizontal guides MUST use continuous y ticks, span the plot width, and omit y=0 so a paired axis does not receive a duplicate line.               | implementation, JSDoc, and focused tests               | verify             |
+| FR4 | Vertical guides MUST use categorical band centers for band x scales and d3 tick positions for continuous x scales, spanning the plot height.       | implementation and focused tests                       | verify             |
+| FR5 | Continuous tick requests MUST be finite, non-negative integers no greater than 1000; zero yields no continuous guides and invalid values use five. | implementation, crash-prevention rationale, and tests  | verify             |
+| FR6 | Guide paint MUST consume a semantic theme token. Whether grid lines become a public theme target remains unsettled.                                | implementation and current theming architecture        | verify             |
+
+### Allowed variation
+
+- **AV1 — Continuous tick count.** d3 may choose a nearby set of values rather than exactly the requested number.
+- **AV2 — Categorical values.** Each current x-band domain value contributes one centered vertical guide.
+
+### Representative states
+
+| State                      | Required invariant                                               | Allowed variation                              |
+| -------------------------- | ---------------------------------------------------------------- | ---------------------------------------------- |
+| Default                    | Horizontal guides only; continuous density defaults to five.     | d3 chooses the exact y tick set.               |
+| Horizontal disabled        | No horizontal guides.                                            | Vertical guides may remain enabled.            |
+| Vertical categorical       | One vertical guide at each x-band center.                        | Band width and center follow Chart's x scale.  |
+| Vertical continuous        | One guide at each generated continuous x tick.                   | d3 chooses the exact x tick set.               |
+| Both directions            | Horizontal and vertical sets render together.                    | Their exact counts may differ.                 |
+| Zero continuous tick count | Continuous guide sets are empty.                                 | Categorical vertical guides remain unaffected. |
+| Invalid tick count         | Continuous guide generation falls back to the default request.   | d3 chooses the resulting exact ticks.          |
+| Narrow / RTL               | Guides remain tied to physical data coordinates and plot bounds. | Plot width and data-domain order vary.         |
+
+### Transformation and precedence order
+
+- **ORD1 — Continuous density.** Validate finiteness and non-negativity → floor fractions → cap at 1000 → request d3 ticks.
+- **ORD2 — Placement.** Select enabled directions → choose the scale path → derive tick or band-center positions → span the current opposite plot dimension.
+
+### Performance and resources
+
+- **PR1 — Derived output.** Guide arrays remain render-derived and memoized from enabled directions, scales, dimensions, and sanitized density. ChartGrid owns no listener, observer, timer, or persistent resource.
+- **PR2 — Bounded tick allocation.** A public density value cannot request more than 1000 continuous ticks from d3.
+
+## Accessibility contract
+
+- **AR1 — Chart-level alternative.** ChartGrid renders passive supporting guides inside Chart's named image. Chart owns the accessible chart name and supported data-table alternative.
+- **AR2 — No grid-only information.** Grid lines do not replace visible labels, meaningful marks, or the parent Chart alternative.
+
+## Design relationships
+
+| Anatomy or state | Design requirement                                                | Representation authority                      | Hierarchy role | Component contract |
+| ---------------- | ----------------------------------------------------------------- | --------------------------------------------- | -------------- | ------------------ |
+| Grid lines       | Support position comparison without carrying chart meaning alone. | unsettled; no current design record is linked | supporting     | FR2–FR6, AR1–AR2   |
+
+### Theming anatomy
+
+<!-- anatomy-theming:v1 -->
+
+```json
+{
+  "Grid lines": {
+    "none": {
+      "reason": "unsettled: ChartGrid consumes a semantic color token, but no current component or family contract decides whether grid lines are a public theme target."
+    }
+  }
+}
+```
+
+## Family and system relationships
+
+- No current family or design record governs ChartGrid.
+- `architecture:component-test-sufficiency` owns rational public-state partitions, observable assertions, and audit evidence quality.
+- `architecture:component-theming-surface` owns anatomy-to-target disposition; token consumption alone does not enroll ChartGrid in public component theming.
+- `spec:AST-002` owns public API admission and prevents this audit from adding or reinterpreting a public choice.
+- `spec:AST-029` owns this observational backfill, closed evidence receipt, safe remediation, and fail-closed eligibility report.
+
+## Verification map
+
+| Contract | Verification                                           | Representative states                                       | Mutation or failure expectation                                                    | Audit section                      |
+| -------- | ------------------------------------------------------ | ----------------------------------------------------------- | ---------------------------------------------------------------------------------- | ---------------------------------- |
+| FR1–FR2  | `ChartGrid.test.tsx`; `ChartGrid.stories.tsx`          | default, horizontal off, vertical on, both, neither         | A direction stops respecting its input or output escapes the parent Chart context. | `audit:ChartGrid/behavior`         |
+| FR3      | `ChartGrid.test.tsx`                                   | positive and mixed-sign y domains                           | Guides stop spanning the plot or y=0 is drawn twice.                               | `audit:ChartGrid/behavior-layout`  |
+| FR4      | `ChartGrid.test.tsx`; `ChartGrid.stories.tsx`          | categorical and continuous x                                | A band guide leaves its center or a continuous tick lands at the wrong coordinate. | `audit:ChartGrid/behavior-layout`  |
+| FR5, PR2 | focused zero/invalid-density tests and source review   | zero and invalid requests; fractional and capped partitions | Invalid input crashes render or bypasses the bounded fallback.                     | `audit:ChartGrid/behavior-testing` |
+| FR6      | strict lint; Storybook theme matrix remains pending    | light, dark, and supported non-default themes               | A raw color or component-side mode choice replaces semantic token paint.           | `audit:ChartGrid/theming-design`   |
+| AR1–AR2  | Chart accessibility tests; package axe remains pending | named Chart, small-data table, grid enabled                 | Grid content replaces or becomes the only source of required chart information.    | `audit:ChartGrid/accessibility`    |
+
+## Decision log
+
+None. This draft records observed behavior and evidence gaps only.
+
+## Open questions
+
+- **OQ1 — Categorical density.** Should `tickCount` remain continuous-scale-only, or should vertical categorical guides gain a documented thinning contract aligned with ChartAxis? (`human-api`)
+
+## Content boundary
+
+This file does not duplicate consumer prop tables/examples, current audit results,
+implementation steps, or shared system rules. It links to their owners.

package/src/ChartGrid.test.tsx

@@ -4,7 +4,8 @@
  * @file ChartGrid.test.tsx
  * @input Uses vitest, @testing-library/react, Chart, ChartGrid, bar mark
  * @output Functional tests for grid lines — horizontal default, the skipped
- *         y=0 line, and vertical lines at band centers
+ *         y=0 line, vertical lines at band/continuous positions, combined
+ *         directions, and safe continuous tick-count handling
  * @position Colocated test for ChartGrid.tsx (issue #4295 viz coverage)
  */
 
@@ -95,6 +96,24 @@ describe('ChartGrid', () => {
     expect(lines).toHaveLength(8); // 5 horizontal + 3 vertical
   });
 
+  it('uses zero to request no continuous grid lines', () => {
+    const {lines} = renderGrid(<ChartGrid tickCount={0} />);
+    expect(lines).toHaveLength(0);
+  });
+
+  it('falls back to the default density for a non-finite tick count', () => {
+    const {lines} = renderGrid(
+      <ChartGrid tickCount={Number.POSITIVE_INFINITY} />,
+    );
+    expect(lines).toHaveLength(5);
+  });
+
+  it('caps a huge continuous tick request without throwing', () => {
+    const {lines} = renderGrid(<ChartGrid tickCount={1e9} />);
+    expect(lines.length).toBeGreaterThan(0);
+    expect(lines.length).toBeLessThanOrEqual(1001);
+  });
+
   it('places vertical lines at d3 tick values on a linear x scale', () => {
     const numeric = [
       {month: 0, sales: 1},

package/src/ChartGrid.tsx

@@ -2,6 +2,7 @@
 
 /**
  * @file ChartGrid.tsx (v2)
+ * @input Chart context scales and dimensions, guide visibility, and tick density
  * @output Grid lines behind chart marks
  * @position Child of Chart v2; reads scales from chart context
  */

package/src/ChartLegend.doc.mjs

@@ -0,0 +1,146 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/** @type {import('@astryxdesign/cli/authoring').ComponentDoc} */
+
+export const docs = {
+  name: 'ChartLegend',
+  displayName: 'Chart Legend',
+  group: 'Charts',
+  category: 'Data Visualization',
+  isHiddenFromOverview: true,
+  keywords: ['chart', 'legend', 'series', 'key', 'label', 'data visualization'],
+
+  usage: {
+    description:
+      'ChartLegend pairs series labels with decorative mark-shaped color swatches. Use Chart legend options for the generated legend, or render ChartLegend directly when the caller already owns the legend items.',
+    bestPractices: [
+      {
+        guidance: true,
+        description:
+          'Give every item a concise label that identifies the corresponding series without relying on its color name.',
+      },
+      {
+        guidance: true,
+        description:
+          'Use start or end for a vertical legend and top or bottom for a wrapping horizontal legend.',
+      },
+      {
+        guidance: false,
+        description:
+          'Use the legend as the chart’s only text alternative. Give the parent Chart an accessible name and preserve an equivalent data view or summary when the data requires one.',
+      },
+      {
+        guidance: false,
+        description:
+          'Assume arbitrary series colors will remain distinguishable in every theme. Verify the complete chart and legend together against the surfaces where they render.',
+      },
+    ],
+    accessibility: [
+      {
+        name: 'Named list',
+        category: 'Semantics',
+        criterion: '1.3.1 Info and Relationships',
+        requirement: 'Built in',
+        states: ['Non-empty'],
+        description:
+          'Entries render as items in a localized Chart legend list. Each visible label supplies the series name while its swatch stays hidden from assistive technology.',
+      },
+      {
+        name: 'Chart alternative',
+        category: 'Content',
+        criterion: '1.1.1 Non-text Content',
+        requirement: 'Required on the parent Chart',
+        states: ['All'],
+        description:
+          'The legend supplements the parent Chart. It does not replace the Chart accessible name, data table, summary, or other equivalent alternative.',
+      },
+      {
+        name: 'Series distinction',
+        category: 'Color contrast',
+        criterion: '1.4.1 Use of Color; 1.4.11 Non-text Contrast',
+        requirement: 'Consumer verification required',
+        states: ['Non-empty'],
+        description:
+          'Caller-supplied series colors must remain distinguishable on the rendered surface. Do not depend on color alone when otherwise identical marks need to be matched across the chart and legend.',
+      },
+    ],
+    anatomy: [
+      {
+        name: 'Legend list',
+        required: true,
+        description:
+          'Wrapping horizontal or stacked vertical list that groups the legend entries.',
+      },
+      {
+        name: 'Legend entry',
+        required: true,
+        description: 'One series label paired with its decorative swatch.',
+      },
+      {
+        name: 'Series swatch',
+        required: true,
+        description:
+          'Decorative square for bar marks or short line for other mark types, painted with the item color.',
+      },
+      {
+        name: 'Series label',
+        required: true,
+        description: 'Supporting text that names the series.',
+      },
+    ],
+  },
+
+  props: [
+    {
+      name: 'items',
+      type: 'LegendItem[]',
+      description:
+        'Series entries to render. Each entry supplies a label, color, and optional mark type. An omitted or empty array renders nothing.',
+      default: '[]',
+    },
+    {
+      name: 'position',
+      type: "'top' | 'bottom' | 'start' | 'end'",
+      description:
+        'Logical placement used by Chart and the legend orientation: top and bottom are horizontal; start and end are vertical.',
+      default: "'bottom'",
+    },
+    {
+      name: 'alignment',
+      type: "'start' | 'center' | 'end'",
+      description:
+        'For top and bottom, distributes the row along its inline axis. For start and end, aligns each entry horizontally within the vertical list.',
+      default: "'start'",
+    },
+  ],
+
+  examples: [
+    {
+      label: 'Generated chart legend',
+      code: `import {Chart, bar, line} from '@astryxdesign/charts';
+
+<Chart
+  data={monthlyRevenue}
+  xKey="month"
+  series={[
+    bar('revenue', {label: 'Revenue'}),
+    line('forecast', {label: 'Forecast'}),
+  ]}
+  legend={{position: 'top', alignment: 'start'}}
+/>;`,
+    },
+    {
+      label: 'Standalone legend',
+      code: `import {ChartLegend} from '@astryxdesign/charts';
+
+<ChartLegend
+  items={[
+    {label: 'Revenue', color: '#3b82f6', type: 'bar'},
+    {label: 'Forecast', color: '#f59e0b', type: 'line'},
+  ]}
+  position="start"
+  alignment="center"
+/>;`,
+    },
+  ],
+};

package/src/ChartLegend.spec.md

@@ -0,0 +1,203 @@
+---
+schema_version: 3
+template_version: 5
+kind: component
+id: component:ChartLegend
+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/charts/src/ChartLegend.test.tsx,
+    apps/storybook/stories/charts/Legend.stories.tsx,
+  ]
+modules: []
+families: []
+design_specs: []
+architecture:
+  [
+    architecture:component-test-sufficiency,
+    architecture:component-theming-surface,
+  ]
+contributing: []
+system_specs: [spec:AST-002, spec:AST-029]
+---
+
+# ChartLegend component contract
+
+## Contract at a glance
+
+| Area                    | Contract                                                                                                                                                                      |
+| ----------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Public contract         | No API shape or default changes. This draft records the current item, logical placement, alignment, list-semantics, and empty-output surface.                                 |
+| Behavior                | Non-empty items render in order as a named list; top/bottom use a wrapping row, start/end use a column, alignment remains logical, and omitted or empty items render nothing. |
+| End-user impact         | Chart readers receive visible series names paired with decorative mark-shaped color keys; this audit changes no rendered behavior.                                            |
+| Builder impact          | Existing callsites remain valid and gain direct CLI documentation for the shipped props, defaults, composition, and accessibility boundary.                                   |
+| Compatibility/readiness | The package remains canary-only. This observational draft is non-authoritative; series distinction by arbitrary caller colors remains unresolved.                             |
+| Review checks           | Reject a changed public shape/default, lost list semantics or localization, reordered items, a wrong orientation, or a new claim that color alone is sufficient.              |
+| Governing rules         | `spec:AST-029/FR3–FR7`, `architecture:component-test-sufficiency/INV1–INV11`, `architecture:component-theming-surface/INV1–INV6`, and `spec:AST-002`.                         |
+
+This table is a review projection; the body below is authoritative.
+
+## Intent
+
+ChartLegend presents the visible key for a chart's series. It owns the ordered
+legend list, entry layout, mark-shaped decorative swatches, series labels, and
+the empty render. A parent Chart may derive its items and place the resulting
+legend around the plot; callers may also render the component directly.
+
+## Compatibility and migration
+
+- Released default preserved: yes at the canary surface; the package has no stable release.
+- Compatibility class: no public API, default, or rendered-behavior change.
+- Controlled/uncontrolled behavior: not applicable.
+- Migration decision: none; this draft does not authorize a public API change.
+
+Consumer migration instructions belong in consumer docs and release notes.
+
+## Ownership boundary
+
+**Owns**
+
+- Rendering non-empty legend items in caller order.
+- Choosing horizontal or vertical layout from logical placement.
+- Aligning the entry collection along the relevant logical axis.
+- Pairing each visible series label with a decorative swatch shape and caller color.
+- Localizing and exposing the legend list name.
+
+**Does not own / non-goals**
+
+- Series derivation, palette assignment, plot placement, or chart render order — owned by `component:Chart` and its series utilities.
+- The chart's accessible name, data alternative, or product summary — owned by `component:Chart` and the product callsite.
+- Custom legend interactions, selection, filtering, or visibility controls.
+- A guarantee that arbitrary caller-supplied colors alone distinguish every series.
+
+## Public concepts
+
+| Concept          | Closed values or states                     | Meaning                                                                                    | Availability by variant/orientation/state | Default  | Owner                   | Stability    | Invalid-value behavior                        |
+| ---------------- | ------------------------------------------- | ------------------------------------------------------------------------------------------ | ----------------------------------------- | -------- | ----------------------- | ------------ | --------------------------------------------- |
+| Legend items     | ordered array or empty                      | Supplies each entry's label, color, and optional mark type.                                | Every ChartLegend                         | `[]`     | `component:ChartLegend` | experimental | Omitted and empty arrays render nothing.      |
+| Logical position | `top`, `bottom`, `start`, `end`             | Gives Chart placement intent and selects row or column orientation.                        | Non-empty                                 | `bottom` | `component:ChartLegend` | experimental | Closed by the exported TypeScript union.      |
+| Alignment        | `start`, `center`, `end`                    | Distributes a horizontal row inline or aligns entries horizontally inside a vertical list. | Non-empty                                 | `start`  | `component:ChartLegend` | experimental | Closed by the exported TypeScript union.      |
+| Swatch shape     | square for `bar`; line for every other type | Visually echoes the item's mark category without adding AT content.                        | Each rendered item                        | line     | `component:ChartSwatch` | experimental | Unknown and omitted types use the line shape. |
+| List semantics   | localized list with one item per entry      | Groups the visible labels as one named legend.                                             | Non-empty                                 | built in | `component:ChartLegend` | experimental | Not applicable.                               |
+
+## Behavioral and layout contract
+
+Draft requirements identify their basis so observed code is not mistaken for an
+intentional decision.
+
+| ID  | Candidate invariant                                                                                                                                                                                       | Basis                                                        | Draft review state |
+| --- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------ | ------------------ |
+| FR1 | ChartLegend MUST render nothing when `items` is omitted or empty and MUST otherwise preserve item order and duplicate labels.                                                                             | implementation and focused tests                             | verify             |
+| FR2 | Each rendered item MUST remain one visible label plus one assistive-technology-hidden ChartSwatch inside a list item.                                                                                     | implementation, focused tests, and browser accessibility run | verify             |
+| FR3 | The root MUST remain a localized named list with exactly one list item per supplied entry.                                                                                                                | implementation, locale catalog, focused tests, and axe       | verify             |
+| FR4 | `top` and `bottom` MUST use a wrapping horizontal row; `start` and `end` MUST use a vertical column.                                                                                                      | implementation and receipted browser matrix                  | verify             |
+| FR5 | Alignment MUST remain logical: for `top` and `bottom`, it distributes the row along the inline axis; for `start` and `end`, it aligns entries horizontally within the vertical list, including under RTL. | implementation and receipted LTR/RTL browser evidence        | verify             |
+| FR6 | Swatch shape MUST be square for `bar` and a short line for every other or omitted type; caller color supplies its paint.                                                                                  | ChartSwatch implementation and focused tests                 | verify             |
+| FR7 | Long labels MUST wrap without horizontal viewport overflow at 320 CSS pixels; no fixed-width truncation contract is currently exposed.                                                                    | receipted browser evidence                                   | verify             |
+
+### Allowed variation
+
+- **AV1 — Available space.** Horizontal entries wrap to additional rows as the containing width narrows; vertical entry labels may wrap within the available inline size.
+- **AV2 — Series paint.** Swatch color is caller-owned and may vary by chart palette and rendered surface, subject to the unresolved distinction requirement below.
+
+### Representative states
+
+| State                 | Required invariant                                                  | Allowed variation                                                   |
+| --------------------- | ------------------------------------------------------------------- | ------------------------------------------------------------------- |
+| Omitted / empty items | No legend DOM is rendered.                                          | Surrounding Chart layout may omit its legend slot.                  |
+| Bottom or top         | Entries form a wrapping horizontal list.                            | Logical alignment and wrapping depend on available width.           |
+| Start or end          | Entries form a vertical list.                                       | Alignment changes each entry's horizontal position within the list. |
+| Duplicate labels      | Every supplied item remains present and ordered.                    | Internal React keys may disambiguate equal labels.                  |
+| Long narrow labels    | Labels wrap and the page remains free of horizontal overflow.       | Entry and list height grow with content.                            |
+| RTL                   | Logical start/end behavior follows the computed document direction. | Visual item order follows the flex and direction model.             |
+
+### Transformation and precedence order
+
+- **ORD1 — Render.** Default omitted props → return nothing for zero items → derive orientation from logical position → map items in caller order → apply logical alignment to the list root.
+- **ORD2 — Entry.** Map mark type to a swatch shape → paint the swatch with caller color → render the caller label as supporting text.
+
+### Performance and resources
+
+- **PR1 — Derived output.** ChartLegend remains render-derived. It owns no state, Effect, listener, observer, timer, request, or persistent resource.
+
+## Accessibility contract
+
+- **AR1 — Named structure.** A non-empty legend exposes one localized named list and one list item for every visible series label.
+- **AR2 — Decorative swatches.** Series swatches stay hidden from assistive technology; the adjacent visible text supplies each entry name.
+- **AR3 — Chart-level alternative.** The legend supplements rather than replaces the parent Chart's accessible name and equivalent data representation.
+- **AR4 — Composed association evidence.** Standalone ChartLegend evidence does not establish how readers associate legend entries with rendered chart marks. Evaluate same-mark-shape series in a composed Chart or product callsite before deciding whether an additional visual cue is needed or which layer owns it.
+
+## Design relationships
+
+| Anatomy or state | Design requirement                                                | Representation authority                      | Hierarchy role | Component contract |
+| ---------------- | ----------------------------------------------------------------- | --------------------------------------------- | -------------- | ------------------ |
+| Legend list      | Group related series entries without adding an interactive state. | unsettled; no current design record is linked | supporting     | FR1, FR3–FR5       |
+| Legend entry     | Keep each label associated with one series key.                   | unsettled; no current design record is linked | supporting     | FR1–FR3            |
+| Series swatch    | Echo the chart mark while remaining decorative to AT.             | unsettled; caller color is current behavior   | supporting     | FR2, FR6, AR2–AR4  |
+| Series label     | Name the series as readable supporting text.                      | delegated to Text                             | supporting     | FR2, AR1–AR2       |
+
+### Theming anatomy
+
+<!-- anatomy-theming:v1 -->
+
+```json
+{
+  "Legend list": {
+    "delegatesTo": {"owner": "component:Stack", "target": "stack"}
+  },
+  "Legend entry": {
+    "delegatesTo": {"owner": "component:Stack", "target": "stack"}
+  },
+  "Series swatch": {
+    "none": {
+      "reason": "unsettled: ChartSwatch owns the visible painter but exposes no current public target; this draft does not decide future reachability."
+    }
+  },
+  "Series label": {
+    "delegatesTo": {"owner": "component:Text", "target": "text"}
+  }
+}
+```
+
+ChartLegend delegates list and entry layout to Stack's existing target, and
+series labels to Text. ChartSwatch is the visible swatch painter but does not
+currently expose a public theme target. Whether that anatomy should become
+reachable remains with the ChartSwatch and theming owners.
+
+## Family and system relationships
+
+- No current family or design record governs ChartLegend.
+- `architecture:component-test-sufficiency` owns rational public-state partitions, observable assertions, and audit evidence quality.
+- `architecture:component-theming-surface` owns anatomy-to-target disposition; composition from themed primitives does not enroll ChartLegend in public component theming.
+- `spec:AST-002` owns public API admission and prevents this audit from adding or reinterpreting a public choice.
+- `spec:AST-029` owns this observational backfill, closed evidence receipt, safe remediation, and fail-closed eligibility report.
+
+## Verification map
+
+| Contract     | Verification                                             | Representative states                                        | Mutation or failure expectation                                                                               | Audit section                              |
+| ------------ | -------------------------------------------------------- | ------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------- | ------------------------------------------ |
+| FR1–FR3      | `ChartLegend.test.tsx`; focused axe run                  | omitted, empty, non-empty, localized, duplicate              | Empty output leaves DOM, an entry disappears, or list semantics/name are lost.                                | `audit:ChartLegend/accessibility-behavior` |
+| FR4–FR5, FR7 | receipted Storybook browser matrix; RTL geometry receipt | row, column, all alignments, 320px long text, RTL            | Orientation, logical alignment, wrapping, or viewport containment changes.                                    | `audit:ChartLegend/layout-responsive-rtl`  |
+| FR6          | `ChartLegend.test.tsx`; `ChartSwatch.test.tsx`           | bar, line, omitted and unknown types                         | A bar loses its square, another type gains one, or swatch paint stops following color.                        | `audit:ChartLegend/behavior-design`        |
+| AR1–AR3      | role/name DOM assertions; focused axe run; Chart tests   | standalone and Chart-composed legend                         | Labels leave the named list or the legend replaces the Chart alternative.                                     | `audit:ChartLegend/accessibility`          |
+| AR4          | future composed Chart/callsite browser evidence          | at least two same-mark-shape series and their rendered marks | Association evidence must cover the legend and plotted marks before recording a defect or assigning an owner. | `audit:ChartLegend/unscored-evidence-gap`  |
+
+## Decision log
+
+None. This draft records observed behavior and evidence gaps only.
+
+## Open questions
+
+- **OQ1 — Composed series association.** In a composed Chart or product callsite, does evidence with two or more same-mark-shape series show that readers need an additional visual association cue? If so, which layer owns it: ChartLegend, the parent Chart/series definition, or the product callsite? (`human-design`)
+- **OQ2 — Swatch theming reachability.** Should series swatches become a public ChartSwatch theme target, or should their paint remain caller-owned? (`human-api`)
+
+## Content boundary
+
+This file does not duplicate consumer prop tables/examples, current audit results,
+implementation steps, or shared system rules. It links to their owners.