@apliteni/apliteni-ui 0.108.0 → 0.114.0

package/guidelines/labels-and-titles.md

@@ -6,9 +6,9 @@
 
 **Rule:** Use body ink for all words; use size, weight and spacing for hierarchy.
 
-**Why:** Muted text can look decorative, especially at small sizes, even when contrast passes.
+**Why:** Muted text can look decorative at small sizes, even when contrast passes.
 
-**Do:** Use body ink at xs, sm and base; let size show hierarchy.
+**Do:** Use body ink at every size; let size show hierarchy.
 
 **Don't:** Use muted ink at different sizes to show rank.
 
@@ -16,15 +16,15 @@
 
 <!-- rule: text-ink-exceptions -->
 
-**Rule:** Use muted or dim ink only for the three named exception classes.
+**Rule:** Use muted or dim ink only for the four named exception classes.
 
-**Why:** A closed list prevents fading from becoming a hierarchy cue.
+**Why:** A closed list keeps fading from becoming hierarchy.
 
-**Do:** Use muted ink for a disabled control or empty field placeholder.
+**Do:** Use muted ink for a placeholder or an axis.
 
 **Don't:** Fade timestamps, counts or enabled actions.
 
-**Except:** Only: (1) non-word glyphs, such as arrows, chevrons or dismiss marks; (2) colour reporting off, unset, disabled or archived state; (3) a valueless slot, such as an empty field or cell placeholder. Unselected options, “No earlier figure” sentences, counts, timestamps, keyboard shortcuts, enabled actions and empty-state instructions are information, not exceptions.
+**Except:** Only: (1) non-word glyphs — arrows, chevrons, dismiss marks; (2) colour reporting off, unset, disabled or archived; (3) a valueless slot, such as an empty field or cell; (4) a drawing’s furniture — a chart’s axis, period row and legend — whose values remain reachable in full. Unselected options, counts, timestamps, shortcuts, enabled actions and empty-state text are information, not exceptions.
 
 ## Use sentence case
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@apliteni/apliteni-ui",
-  "version": "0.108.0",
+  "version": "0.114.0",
   "workspaces": [
     "react"
   ],

package/react/README.md

@@ -32,7 +32,7 @@ import { DataTable, Modal, Button } from '@apliteni/apliteni-ui/react';
 Both stylesheets. The React one adds what React's own components need — it carries no tokens, no
 reset and none of the kit's control CSS, so it cannot stand in for the first import.
 
-Components: `Success`, `SuccessPanel`, `SuccessCheck`, `Checkbox`, `Switch`, `SearchField`, `EmptyState`, `DataTable`, `Pagination`, `StatBand`, `Modal`, `Confirm`, `Drawer`, `CommandPalette`, `Dropdown`, `BackLink`, `Tooltip`, `Snippet`, `Segmented`, `Tabs`, `Button`, `Badge`, `Pill`, `StatusDot`, `Card`, `Callout`, `Icon`.
+Components: `Success`, `SuccessPanel`, `SuccessCheck`, `Checkbox`, `Switch`, `SearchField`, `EmptyState`, `DataTable`, `Pagination`, `StatBand`, `Chart`, `Modal`, `Confirm`, `Drawer`, `CommandPalette`, `Dropdown`, `BackLink`, `Tooltip`, `Snippet`, `Segmented`, `Tabs`, `Button`, `Badge`, `Pill`, `StatusDot`, `Card`, `Callout`, `Icon`.
 
 `Segmented` is a controlled choice toolbar: pass `options`, `value`, `onChange`,
 and a `label` for its accessible name. `size="sm"` compacts it, `block` makes it
@@ -831,3 +831,71 @@ control ever draws: selection and focus are one signal each, and only focus is a
 accent. Accent names and swatch paints come from the kit's `ACCENTS` and
 `accentSwatchStyle`, which the vanilla factory also reads, so the two pickers cannot
 drift.
+
+## Chart
+
+`Chart` draws three shapes from the kit's tokens: `months`, a column per period with bars and
+a line across them; `bridge`, one period walked from a starting total to a result; and `spark`,
+one series at text size with no axis, for a stat band's `trend` slot.
+
+The numbers are yours and so is the wording. `format` prints exact values in the readout, the
+live region and the table; `formatAxis` prints the ticks, which are whole units, and defaults
+to `format`. A `bars-below` series takes positive magnitudes and is drawn under the zero line.
+A period marked `estimated` keeps its series fill with a dashed edge. The legend names the state.
+The readout and the optional table show the state and its `note`.
+
+A bar series names a tone. `accent` and `accent-soft` are one hue at two weights, which is how
+two series read apart without spending a second colour on them; `good` and `bad` say which way
+the news runs, and belong to a series where some direction is better. Every tone is opaque and
+clears 3:1 against the card and against the page, in both themes and under every accent.
+
+The plot draws a hairline at every tick and the zero rule over them, and the axis keeps a label
+at every tick. A bar is flat, rounded only at the end away from zero, and **never wider than a
+mark**: a chart that grows with the card gains ground between its columns rather than twelve
+wider blocks. Two bar series on the same side of the zero line stand side by side with ground
+between them. A bridge carries each step's running total across to the step beside it. The
+value axis, the period row and the legend are drawn quietly, and every value they name is also
+in the readout and in the table at full strength.
+
+Picking a column paints the column's own ground behind it and sets its label in the strong ink
+at a heavier weight. No mark changes colour, so the accent stays with the series it names, and
+the only outline the chart draws is the focus ring on the plot.
+
+The plot is one tab stop. Left, Right, Home and End step columns and announce each one
+politely, Enter picks one when `selectable` is set, and `title` names the `role="img"` plot and
+the table under it without being drawn — the card around the chart already carries its title.
+The table the reader opens adds the two stops it needs of its own: its summary, and the named
+scroller that carries its columns sideways so your card and your page keep their width.
+At phone widths the plot scrolls with the value axis held in place, and the side that still
+hides columns is faded. Nothing animates.
+
+On a touch screen a tap opens the readout and a second tap on the same mark closes it. **The
+tap that opens a readout does not call `onSelect`** — it is the reader asking what a mark is
+worth — while the tap that closes one, and an ordinary mouse click, do. The click itself is
+never swallowed, so your own listener around the chart still hears every tap. Below 560px, to
+a coarse pointer, a line's point grows an invisible target that stops at its own column so
+no two periods answer for each other. A narrow sparkline can own less than 44px across, but it
+still owns at least 24px across and the full 44px down. The drawn line does not change. A
+sparkline's box grows with it — 32px of drawing cannot hold the vertical target, and the part
+outside the box would be clipped by the chart's own edge — so a `trend` slot is 44px tall there
+instead of 32, with the same line drawn in the middle of it.
+
+```tsx
+<Chart title="Income and spend by month, last 12 months, with net"
+  periods={months.map(label => ({ label }))}
+  series={[
+    { id: 'income', name: 'Income', values: income, tone: 'accent' },
+    { id: 'spend', name: 'Spend', values: spend, shape: 'bars-below', tone: 'accent-soft' },
+    /* or `shape: 'bars'` for the two standing side by side on the zero line */
+    { id: 'net', name: 'Net', values: net, shape: 'line', tone: 'info' },
+  ]}
+  format={eur} formatAxis={eurShort} />
+
+<Chart variant="bridge" title="Cash from opening to closing" format={eur}
+  steps={[
+    { label: 'Opening', value: 120000 },
+    { label: 'Subscriptions', value: 42600 },
+    { label: 'Payroll', value: -58200 },
+    { label: 'Closing', kind: 'total' },
+  ]} />
+```

package/react/dist/index.d.ts

@@ -900,6 +900,87 @@ declare const Success: react.ForwardRefExoticComponent<Omit<HTMLAttributes<HTMLD
     onCountdownEnd?: () => void;
 } & react.RefAttributes<HTMLDivElement>>;
 
+type ChartTone = 'accent' | 'accent-soft' | 'good' | 'bad' | 'warn' | 'info' | 'neutral';
+type ChartPeriod = {
+    /** The period as the readout and the table name it: `Jan 2026`. */
+    label: string;
+    /** The period as the axis names it. Defaults to `label`'s first word. */
+    short?: string;
+    /** The period is not final — estimated, forecast, or still running. */
+    estimated?: boolean;
+    /** Why it is not final. Printed in the readout and in the legend. */
+    note?: string;
+};
+type ChartSeries = {
+    id: string;
+    name: string;
+    values: readonly number[];
+    /**
+     * `bars` stand on the zero line, `bars-below` hang under it from positive
+     * magnitudes (spend given as 31870, not −31870), and `line` crosses both.
+     */
+    shape?: 'bars' | 'bars-below' | 'line';
+    /**
+     * Bars take a tone. A line is `neutral` unless the caller says otherwise.
+     * `accent` and `accent-soft` are one hue at two weights, which is how two
+     * series read apart without spending a second colour on them.
+     */
+    tone?: ChartTone;
+};
+type ChartBridgeStep = {
+    label: string;
+    short?: string;
+    /**
+     * A `total` is an absolute column; a `change` is added to the running total.
+     * The first step is a total and every later one a change, unless it says so.
+     */
+    kind?: 'total' | 'change';
+    /** A change's amount. A `total` without one takes the running total. */
+    value?: number;
+    estimated?: boolean;
+    note?: string;
+};
+type ChartBridgeTones = {
+    rise?: ChartTone;
+    fall?: ChartTone;
+    total?: ChartTone;
+};
+type ChartCommon = {
+    /**
+     * Names the chart for a reader who cannot see it, and the table under it.
+     * Never drawn: the card around a chart already carries its title.
+     */
+    title: string;
+    /** Exact values, for the readout, the live region and the table. */
+    format: (value: number) => string;
+    /** Axis ticks, which are whole units. Defaults to `format`. */
+    formatAxis?: (value: number) => string;
+    /** The plot's height in CSS px. */
+    height?: number;
+    /** Offer the same numbers as a table. On by default, off for a sparkline. */
+    table?: boolean;
+    /** Let Enter and a click pick a column. */
+    selectable?: boolean;
+    /** The picked column, when the caller keeps that state. */
+    selected?: number | null;
+    onSelect?: (index: number) => void;
+    className?: string;
+};
+type ChartProps = ChartCommon & ({
+    variant?: 'months';
+    periods: readonly ChartPeriod[];
+    series: readonly ChartSeries[];
+} | {
+    variant: 'spark';
+    periods: readonly ChartPeriod[];
+    series: readonly ChartSeries[];
+} | {
+    variant: 'bridge';
+    steps: readonly ChartBridgeStep[];
+    tones?: ChartBridgeTones;
+});
+declare function Chart(props: ChartProps): react.JSX.Element;
+
 type SidebarNavBadge = string | number | {
     text: string | number;
     tone?: 'neutral' | 'accent' | 'live' | 'danger';
@@ -965,4 +1046,4 @@ declare const AccentPicker: react.ForwardRefExoticComponent<Omit<HTMLAttributes<
 declare const PAGE_SIZES: readonly number[];
 declare const DEFAULT_PAGE_SIZE: number;
 
-export { type Accent, AccentPicker, type AccentPickerProps, AppShell, type AppShellProps, type AppShellSection, BackLink, type BackLinkOwnProps, type BackLinkProps, Badge, BusyRegion, type BusyRegionProps, Button, type ButtonLinkProps, type ButtonProps, Callout, type CalloutProps, type CalloutVariant, Card, Checkbox, type CheckboxProps, type Column, type CommandGroup, type CommandItem, CommandPalette, type CommandPaletteProps, Confirm, type ConfirmProps, DEFAULT_PAGE_SIZE, DataTable, type DataTableProps, DatePicker, type DatePickerMode, type DatePickerPreset, type DatePickerProps, type DatePickerRange, DeltaValue, type DeltaValueProps, Denied, type DeniedProps, Drawer, type DrawerProps, DrawerSection, type DrawerSectionProps, Dropdown, type DropdownBadge, type DropdownEntry, type DropdownItem, type DropdownProps, type DropdownRowProps, type DropdownSearch, type DropdownSection, type DropdownSeparator, EmptyState, type EmptyStateProps, type EmptyStateVariant, Field, type FieldControlProps, type FieldProps, FileDrop, type FileDropFile, type FileDropProps, type FileDropStatus, FileField, type FileFieldProps, type Filter, FilterBar, type FilterBarProps, Icon, KeyValueList, type KeyValueListProps, type KeyValueRow, Modal, type ModalProps, type NativeButtonProps, NumericValue, type NumericValueProps, PAGE_SIZES, Pagination, type PaginationProps, Pill, type PillProps, RowIdentity, type RowIdentityProps, SearchField, type SearchFieldProps, type SegmentOption, Segmented, type SegmentedProps, SelectField, type SelectFieldProps, SidebarNav, type SidebarNavBadge, type SidebarNavItem, type SidebarNavLeaf, type SidebarNavProps, type SidebarNavSection, Skeleton, type SkeletonProps, SkeletonTable, type SkeletonTableProps, Snippet, type SnippetProps, StatBand, type StatBandProps, type StatDelta, type StatFigure, type StatTone, type StatVariant, StatusDot, type StatusDotProps, Success, SuccessCheck, type SuccessCheckProps, type SuccessCountdown, SuccessPanel, type SuccessPanelProps, type SuccessProps, Switch, type SwitchProps, THEME_INIT_SCRIPT, type TabItem, type TableSort, Tabs, type TabsProps, TextArea, type TextAreaProps, TextField, type TextFieldProps, ThemeToggle, type ThemeToggleProps, Timeline, type TimelineEvent, type TimelineEventKind, type TimelineProps, Toast, type ToastNotice, type ToastProps, Tooltip, type TooltipProps, sortTableRows, useToast };
+export { type Accent, AccentPicker, type AccentPickerProps, AppShell, type AppShellProps, type AppShellSection, BackLink, type BackLinkOwnProps, type BackLinkProps, Badge, BusyRegion, type BusyRegionProps, Button, type ButtonLinkProps, type ButtonProps, Callout, type CalloutProps, type CalloutVariant, Card, Chart, type ChartBridgeStep, type ChartBridgeTones, type ChartPeriod, type ChartProps, type ChartSeries, type ChartTone, Checkbox, type CheckboxProps, type Column, type CommandGroup, type CommandItem, CommandPalette, type CommandPaletteProps, Confirm, type ConfirmProps, DEFAULT_PAGE_SIZE, DataTable, type DataTableProps, DatePicker, type DatePickerMode, type DatePickerPreset, type DatePickerProps, type DatePickerRange, DeltaValue, type DeltaValueProps, Denied, type DeniedProps, Drawer, type DrawerProps, DrawerSection, type DrawerSectionProps, Dropdown, type DropdownBadge, type DropdownEntry, type DropdownItem, type DropdownProps, type DropdownRowProps, type DropdownSearch, type DropdownSection, type DropdownSeparator, EmptyState, type EmptyStateProps, type EmptyStateVariant, Field, type FieldControlProps, type FieldProps, FileDrop, type FileDropFile, type FileDropProps, type FileDropStatus, FileField, type FileFieldProps, type Filter, FilterBar, type FilterBarProps, Icon, KeyValueList, type KeyValueListProps, type KeyValueRow, Modal, type ModalProps, type NativeButtonProps, NumericValue, type NumericValueProps, PAGE_SIZES, Pagination, type PaginationProps, Pill, type PillProps, RowIdentity, type RowIdentityProps, SearchField, type SearchFieldProps, type SegmentOption, Segmented, type SegmentedProps, SelectField, type SelectFieldProps, SidebarNav, type SidebarNavBadge, type SidebarNavItem, type SidebarNavLeaf, type SidebarNavProps, type SidebarNavSection, Skeleton, type SkeletonProps, SkeletonTable, type SkeletonTableProps, Snippet, type SnippetProps, StatBand, type StatBandProps, type StatDelta, type StatFigure, type StatTone, type StatVariant, StatusDot, type StatusDotProps, Success, SuccessCheck, type SuccessCheckProps, type SuccessCountdown, SuccessPanel, type SuccessPanelProps, type SuccessProps, Switch, type SwitchProps, THEME_INIT_SCRIPT, type TabItem, type TableSort, Tabs, type TabsProps, TextArea, type TextAreaProps, TextField, type TextFieldProps, ThemeToggle, type ThemeToggleProps, Timeline, type TimelineEvent, type TimelineEventKind, type TimelineProps, Toast, type ToastNotice, type ToastProps, Tooltip, type TooltipProps, sortTableRows, useToast };