` (LAB-AT21). | | `onAnimationComplete` | `((event: AnimationCompleteEvent) => void)` | no | Fired when a chart animation completes. - `'load'`: initial mount animation finished (or immediately if animation disabled / prefers-reduced-motion is active). - `'update'`: data-update transition finished. Not triggered by zoom animations (use `onZoomChange`) or tooltip fades. | | `onExportComplete` | `((result: ChartExportResult) => void)` | no | Fired after a successful export action (PNG/SVG/CSV/PDF), including from the context menu and from imperative `ChartHandle` calls. | | `onExportError` | `((format: ChartExportFormat, error: unknown) => void)` | no | Fired when an export could not produce its file (W11), from the handle as well as from the context menu. Without it a failed context-menu export is reported as an error diagnostic (`<ChartDefaults diagnostics>`). | | `onItemActivate` | `((item: ChartSeriesItem<TDatum>, source: ChartInteractionSource) => void)` | no | Fired when the reader activates an item: a click or tap on it, or `Enter` on the focused item (`Shift+Enter` on a sankey, whose `Enter` moves between nodes and links). With a handler, `Enter` activates instead of opening the context menu (`Shift+F10` and the context-menu key still open it). | | `onLegendChange` | `((change: ChartLegendChange) => void)` | no | Fired once for every legend change the chart applies: a hide, a show, an isolation or a show-all, from the built-in legend (click, key, double click, double tap), its menu, or `useChartLegend()`. The change names the entry and its target by identity and lists every hidden target after it. A refused action (the last visible target, `legend.interactive: false`) changes nothing and reports nothing. | | `onReady` | `(() => void)` | no | Fired exactly once per chart instance, after the first successful mount with valid dimensions and **before** any entrance animation starts. "Ready" means: the SVG is in the DOM, layout has run with real dimensions, and the chart can be queried by integration tests. Distinct from {@link onAnimationComplete} with `type: 'load'`, which fires *after* the load animation finishes. A chart with `animation={false}` still fires `onReady` — animation state has no effect on readiness. A new React `key` on the host produces a new component instance and `onReady` fires again. Identity changes of the callback itself after the first fire are ignored (latch is per-instance). **Consumer requirement — stable from first render.** The latch closes on the first effect run regardless of whether `onReady` was defined at that moment. If `onReady` is initially `undefined` and later resolves to a function, the callback will **never** fire — the latch has already closed with a no-op. Pass a stable reference (typically via `useCallback`) or pass the final function unconditionally from the first render. | | `onSelectionChange` | `((selection: ChartItemRef[], change: ChartSelectionChange<TDatum, ChartSeriesItem<TDatum>>) => void)` | no | Fired when the reader changes the selection (pointer, touch or keyboard), and when an uncontrolled selection drops items the data no longer contains. `selection` is the complete selection the change makes; it keeps every reference the selection held, of whatever form. On a controlled chart it is a proposal (`change.requested: true`), computed from the current `selectedItems` and never from an earlier proposal; the host applies it, changes it or ignores it. | | `padAngle` | `number` | no | The gap between segments, in degrees. Default: about 1.146° (0.02 rad, the default drawing unchanged by T2-D5). | | `paint` | `DatumPaintResolver<DatumFill, TDatum>` | no | A segment's own fill, by a rule over its row (T1, the contract of BC-P1, ADR-092): the one category in breach in the negative role. Returns `{fill}` or `undefined` for the segment's palette colour; paint only. The segment IS its legend category, so its legend key, its tooltip swatch and its export show the painted fill; forced colours override it. The context's `seriesId` is `'nightingale'` and its `seriesName` the chart's `name`. See {@link DatumPaintResolver}. | | `ref` | `Ref<ChartExportHandle>` | no | Imperative handle: exports and element access. A family built on this type has no data-range zoom, so its handle has no `setZoom`. Allows getting a ref to the component instance. Once the component unmounts, React will set `ref.current` to `null` (or call the ref with `null` if you passed a callback ref). | | `selectedItems` | `readonly ChartItemRef[]` | no | The selection, controlled by the host. The chart draws, announces and lists the items it resolves to and never changes it; the host updates it from `onSelectionChange`. A request the host applies is announced when the host passes it back; one it ignores is never announced. A reference to an item that is hidden, zoomed or drilled out of view, or not in the data stays in the host's selection and is not shown as selected. | | `selection` | `FeatureOption<ChartSelectionOptions>` | no | Item selection. `true` = single selection keyed by the default key. | | `startAngle` | `number` | no | Where the first segment starts: degrees clockwise from 12 o'clock, the one radial convention (T2, ADR-095). Default: `0` (12 o'clock). Any finite number; the rose stays whole. The segments keep their data order clockwise from here, and the legend, the keyboard, the table and the announcement keep that order. The sweep entrance starts here. An angle that is not a finite number is reported to the host's diagnostics and draws the default. | | `t` | `ChartTranslateFn` | no | The host translator for every text the chart shows or announces. When omitted, `<ChartDefaults>` supplies it; with neither, the chart throws a configuration error (no English fallback, ADR-028). | | `tooltip` | `StandaloneTooltipOption<never>` | no | Tooltip of the slice under the pointer: `enabled`, `renderer`, `valueFormatter` and `style` (ADR-082, LAB-AT17). | | `valueSemantics` | `ChartValueSemantics` | no | What the segment values mean (BC1): unit and precision, declared once with the type the Cartesian charts read (`ChartValueSemantics`). The value labels, the tooltip, the data table and the announcement write each value in it; a share of the whole stays a percentage. The label's own `formatter` or `format` (and `tooltip.valueFormatter`) still wins; without a declaration the chart presentation's number applies. CSV and Copy value keep the raw number. | | `width` | `number` | no | Optional fixed width in pixels. Default: fill container. | ## Types **NightingaleChartProps** ```ts interface NightingaleChartProps<TDatum extends ChartDatum = ChartDatum> extends Omit<CategoricalChartProps<TDatum>, 'events'>, ChartSelectionProps<TDatum, ChartSeriesItem<TDatum>> { events?: NonNullable<CategoricalChartProps<TDatum>['events']> & ChartSelectionEvents<TDatum, ChartSeriesItem<TDatum>>; name?: string; innerRadiusFraction?: number; padAngle?: number; startAngle?: number; dataLabels?: NightingaleDataLabelOptions | DataLabelOptions | boolean; legend?: LegendOptions | boolean; legendLink?: ChartLegendLink; valueSemantics?: ChartValueSemantics; paint?: DatumPaintResolver<DatumFill, TDatum>; } ``` Props for {@link NightingaleChart}. Extends {@link CategoricalChartProps} to join the wrapper contract. Chart-specific fields (`innerRadiusFraction`, `padAngle`, `startAngle`, `dataLabels`, `legend`) remain on this interface. Entrance animation: defaults to `sweep` (clockwise radial reveal of all segments). `fade` and `none` are also supported. Hover- transitions (100–150ms opacity) are retained as interaction feedback and fall below the WCAG 2.3.3 threshold for reduced-motion concerns; the global media query in `accessibility.css` suppresses them defensively under `prefers-reduced-motion: reduce`.

--- id: "packages/active-charts/all-exports/nightingale-chart" title: "NightingaleChart" description: "NightingaleChart, NightingaleChartProps: generated from the source of active-charts." url: "/packages/active-charts/all-exports/nightingale-chart" locale: "en" revision: "g0mvjxwj5c-88bdbe1c:nightingale-chart" --- # NightingaleChart Exported by `@workspace/active-charts`. Generated from the package source; part of [the index of every export](/packages/active-charts/all-exports). ## `NightingaleChart` | Prop | Type | Required | Description | | --- | --- | --- | --- | | `categoryKey` | `string` | yes | Category/label field name. Drives tooltip/legend/label text. | | `data` | `TDatum[]` | yes | Flat array of row objects. Each row is one slice/segment/spoke. | | `height` | `number` | yes | Container height in pixels. Width is always responsive. | | `valueKey` | `string` | yes | Numeric value field name. Drives slice/segment size. | | `accessibility` | `StandaloneAccessibilityOptions` | no | Accessible name, description, data table and keyboard navigation. No `announcements`: it switches ``'s interaction announcements, which this family does not make. | | `animation` | `StandaloneAnimationOption<"type">` | no | The entrance: on, off, `duration`, `easing` and the family's entrance `type`. One entrance and no series, so no `stagger`, `update`, `layers` or `exit` (ADR-082, LAB-AT17). | | `className` | `string` | no | Optional className applied to the outer container. | | `colors` | `string[]` | no | Categorical palette for this chart only: replaces the host palette (`--chart-1` … `--chart-10`) in the chart's colour assignment, and nothing else. It is a data encoding, not a theme: surfaces, text, grid and semantic roles keep coming from the CSS token contract, and a series, datum or annotation that sets its own colour keeps it. Any CSS colour string (a public token reference such as `var(--chart-3)`, hex, oklch). | | `contextMenu` | `FeatureOption, "copy" \| "export" \| "series">>` | no | The context menu. Opened on a slice, the host's builder receives a typed {@link CategoricalSlice} (datum, index, value, category, share) as `context.target.element`; on empty space the target is the chart, on a legend entry the entry. | | `dataLabels` | `boolean \| DataLabelOptions \| NightingaleDataLabelOptions` | no | Data label configuration. Default: disabled. Accepts the shared {@link DataLabelOptions} or the nightingale-specific {@link NightingaleDataLabelOptions} (adds `connector`, `offset`, `nameFontWeight`, `valueFontWeight`). `boolean` shorthand enables with defaults. | | `defaultSelectedItems` | `readonly ChartItemRef[]` | no | The initial selection of an uncontrolled chart. | | `dir` | `"ltr" \| "rtl"` | no | The chart's UI direction: the reading direction of its HTML text and chrome (tooltip, legend, menus, the accessible table), and the direction the context menu carries under ``. Left out, the chart inherits the direction of the page around it (the nearest `dir` attribute, else the computed CSS direction) and follows a later change of that attribute. It is never inferred from `locale`, and it never reverses an axis or reorders data: `reversed` stays an explicit axis choice. Under `rtl` the chrome mirrors (legend flow, tooltip side, context menu and submenus, report text in exports), a title-like label starts at the inline start, and a label placed by geometry (an axis tick, a slice or bar label) keeps its physical side; plot arrow keys stay spatial while legend and menu arrows follow the reading direction. | | `events` | `(Omit & ChartSelectionEvents>)` | no | The chart's events, and the selection events (T8): a sector is an item of the chart's one series (`seriesId` `'nightingale'`), keyed by its `categoryKey` value unless `selection.itemKey` names another field. | | `innerRadiusFraction` | `number` | no | Inner radius fraction (0 = filled, 0.3 = donut). Default: 0. | | `legend` | `boolean \| LegendOptions` | no | Enable legend. | | `legendLink` | `ChartLegendLink` | no | Connects the chart's legend to `useChartLegend()`, for a legend the host renders itself. Give one link to one chart. | | `locale` | `ValuePresentation` | no | Presentation input for axis labels, tooltips, labels and accessibility announcements: a locale code (notation follows the language), or a presentation-context object (`{languageLocale, dateShape?, dateFormat?, timeFormat?, numberFormat?, currencyDisplay?}`) carrying language and notation independently. `dateShape` is the normal human date shape a plain date consumer inherits; an axis that declares its own preset for readability keeps it. Forwarded untouched to the central `@workspace/active-format`; the package never resolves tenant or application settings itself. When omitted, `` supplies it; with neither, the chart throws a configuration error (no `'en'` fallback, active-format D14). Object inputs must be referentially stable across renders. | | `name` | `string` | no | The chart's name: its accessible name and `` (LAB-AT21). | | `onAnimationComplete` | `((event: AnimationCompleteEvent) => void)` | no | Fired when a chart animation completes. - `'load'`: initial mount animation finished (or immediately if animation disabled / prefers-reduced-motion is active). - `'update'`: data-update transition finished. Not triggered by zoom animations (use `onZoomChange`) or tooltip fades. | | `onExportComplete` | `((result: ChartExportResult) => void)` | no | Fired after a successful export action (PNG/SVG/CSV/PDF), including from the context menu and from imperative `ChartHandle` calls. | | `onExportError` | `((format: ChartExportFormat, error: unknown) => void)` | no | Fired when an export could not produce its file (W11), from the handle as well as from the context menu. Without it a failed context-menu export is reported as an error diagnostic (`<ChartDefaults diagnostics>`). | | `onItemActivate` | `((item: ChartSeriesItem<TDatum>, source: ChartInteractionSource) => void)` | no | Fired when the reader activates an item: a click or tap on it, or `Enter` on the focused item (`Shift+Enter` on a sankey, whose `Enter` moves between nodes and links). With a handler, `Enter` activates instead of opening the context menu (`Shift+F10` and the context-menu key still open it). | | `onLegendChange` | `((change: ChartLegendChange) => void)` | no | Fired once for every legend change the chart applies: a hide, a show, an isolation or a show-all, from the built-in legend (click, key, double click, double tap), its menu, or `useChartLegend()`. The change names the entry and its target by identity and lists every hidden target after it. A refused action (the last visible target, `legend.interactive: false`) changes nothing and reports nothing. | | `onReady` | `(() => void)` | no | Fired exactly once per chart instance, after the first successful mount with valid dimensions and **before** any entrance animation starts. "Ready" means: the SVG is in the DOM, layout has run with real dimensions, and the chart can be queried by integration tests. Distinct from {@link onAnimationComplete} with `type: 'load'`, which fires *after* the load animation finishes. A chart with `animation={false}` still fires `onReady` — animation state has no effect on readiness. A new React `key` on the host produces a new component instance and `onReady` fires again. Identity changes of the callback itself after the first fire are ignored (latch is per-instance). **Consumer requirement — stable from first render.** The latch closes on the first effect run regardless of whether `onReady` was defined at that moment. If `onReady` is initially `undefined` and later resolves to a function, the callback will **never** fire — the latch has already closed with a no-op. Pass a stable reference (typically via `useCallback`) or pass the final function unconditionally from the first render. | | `onSelectionChange` | `((selection: ChartItemRef[], change: ChartSelectionChange<TDatum, ChartSeriesItem<TDatum>>) => void)` | no | Fired when the reader changes the selection (pointer, touch or keyboard), and when an uncontrolled selection drops items the data no longer contains. `selection` is the complete selection the change makes; it keeps every reference the selection held, of whatever form. On a controlled chart it is a proposal (`change.requested: true`), computed from the current `selectedItems` and never from an earlier proposal; the host applies it, changes it or ignores it. | | `padAngle` | `number` | no | The gap between segments, in degrees. Default: about 1.146° (0.02 rad, the default drawing unchanged by T2-D5). | | `paint` | `DatumPaintResolver<DatumFill, TDatum>` | no | A segment's own fill, by a rule over its row (T1, the contract of BC-P1, ADR-092): the one category in breach in the negative role. Returns `{fill}` or `undefined` for the segment's palette colour; paint only. The segment IS its legend category, so its legend key, its tooltip swatch and its export show the painted fill; forced colours override it. The context's `seriesId` is `'nightingale'` and its `seriesName` the chart's `name`. See {@link DatumPaintResolver}. | | `ref` | `Ref<ChartExportHandle>` | no | Imperative handle: exports and element access. A family built on this type has no data-range zoom, so its handle has no `setZoom`. Allows getting a ref to the component instance. Once the component unmounts, React will set `ref.current` to `null` (or call the ref with `null` if you passed a callback ref). | | `selectedItems` | `readonly ChartItemRef[]` | no | The selection, controlled by the host. The chart draws, announces and lists the items it resolves to and never changes it; the host updates it from `onSelectionChange`. A request the host applies is announced when the host passes it back; one it ignores is never announced. A reference to an item that is hidden, zoomed or drilled out of view, or not in the data stays in the host's selection and is not shown as selected. | | `selection` | `FeatureOption<ChartSelectionOptions>` | no | Item selection. `true` = single selection keyed by the default key. | | `startAngle` | `number` | no | Where the first segment starts: degrees clockwise from 12 o'clock, the one radial convention (T2, ADR-095). Default: `0` (12 o'clock). Any finite number; the rose stays whole. The segments keep their data order clockwise from here, and the legend, the keyboard, the table and the announcement keep that order. The sweep entrance starts here. An angle that is not a finite number is reported to the host's diagnostics and draws the default. | | `t` | `ChartTranslateFn` | no | The host translator for every text the chart shows or announces. When omitted, `<ChartDefaults>` supplies it; with neither, the chart throws a configuration error (no English fallback, ADR-028). | | `tooltip` | `StandaloneTooltipOption<never>` | no | Tooltip of the slice under the pointer: `enabled`, `renderer`, `valueFormatter` and `style` (ADR-082, LAB-AT17). | | `valueSemantics` | `ChartValueSemantics` | no | What the segment values mean (BC1): unit and precision, declared once with the type the Cartesian charts read (`ChartValueSemantics`). The value labels, the tooltip, the data table and the announcement write each value in it; a share of the whole stays a percentage. The label's own `formatter` or `format` (and `tooltip.valueFormatter`) still wins; without a declaration the chart presentation's number applies. CSV and Copy value keep the raw number. | | `width` | `number` | no | Optional fixed width in pixels. Default: fill container. | ## Types **NightingaleChartProps** ```ts interface NightingaleChartProps<TDatum extends ChartDatum = ChartDatum> extends Omit<CategoricalChartProps<TDatum>, 'events'>, ChartSelectionProps<TDatum, ChartSeriesItem<TDatum>> { events?: NonNullable<CategoricalChartProps<TDatum>['events']> & ChartSelectionEvents<TDatum, ChartSeriesItem<TDatum>>; name?: string; innerRadiusFraction?: number; padAngle?: number; startAngle?: number; dataLabels?: NightingaleDataLabelOptions | DataLabelOptions | boolean; legend?: LegendOptions | boolean; legendLink?: ChartLegendLink; valueSemantics?: ChartValueSemantics; paint?: DatumPaintResolver<DatumFill, TDatum>; } ``` Props for {@link NightingaleChart}. Extends {@link CategoricalChartProps} to join the wrapper contract. Chart-specific fields (`innerRadiusFraction`, `padAngle`, `startAngle`, `dataLabels`, `legend`) remain on this interface. Entrance animation: defaults to `sweep` (clockwise radial reveal of all segments). `fade` and `none` are also supported. Hover- transitions (100–150ms opacity) are retained as interaction feedback and fall below the WCAG 2.3.3 threshold for reduced-motion concerns; the global media query in `accessibility.css` suppresses them defensively under `prefers-reduced-motion: reduce`.