An open source design system that's fully customizable and agent ready
TypeScript
docs(charts): document ChartLegend audit surface (#6379)
Cindy Zhanga907275695d1
diff --git a/apps/docsite/src/__tests__/data-extraction.test.ts b/apps/docsite/src/__tests__/data-extraction.test.tsindex 86fd733192..42a9895c45 100644--- a/apps/docsite/src/__tests__/data-extraction.test.ts+++ b/apps/docsite/src/__tests__/data-extraction.test.ts@@ -246,6 +246,7 @@ describe('componentRegistry', () => {'Chart','ChartAxis','ChartGrid',+ 'ChartLegend','ChartSwatch',]);expect(components['@astryxdesign/richtext'].map(comp => comp.name)).toEqual(diff --git a/internal/shadcn-registry/routes.lock.json b/internal/shadcn-registry/routes.lock.jsonindex c6c4745cf4..32a95243e6 100644--- a/internal/shadcn-registry/routes.lock.json+++ b/internal/shadcn-registry/routes.lock.json@@ -121,6 +121,11 @@"path": "components/charts/chart-grid","aliases": []},+ {+ "name": "component-charts-chart-legend",+ "path": "components/charts/chart-legend",+ "aliases": []+ },{"name": "component-charts-chart-swatch","path": "components/charts/chart-swatch",diff --git a/packages/charts/src/ChartLegend.doc.mjs b/packages/charts/src/ChartLegend.doc.mjsnew file mode 100644index 0000000000..8397b1c107--- /dev/null+++ b/packages/charts/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"+/>;`,+ },+ ],+};diff --git a/packages/charts/src/ChartLegend.spec.md b/packages/charts/src/ChartLegend.spec.mdnew file mode 100644index 0000000000..3be2294ebe--- /dev/null+++ b/packages/charts/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.