@amberstack/comp-lib 0.0.0-stage → 0.1.0

package/dist/components/Button/Button.d.ts

@@ -0,0 +1,16 @@
+import { type ButtonHTMLAttributes } from 'react';
+import { type IconName } from '../../icons';
+export type ButtonVariant = 'primary' | 'inverse' | 'secondary' | 'ghost' | 'danger';
+export type ButtonSize = 'md' | 'sm';
+export interface ButtonProps extends ButtonHTMLAttributes<HTMLButtonElement> {
+    /** Visual emphasis. Use `primary` at most once per view. */
+    variant?: ButtonVariant;
+    /** Control height: `md` is 34 px and `sm` is 28 px. */
+    size?: ButtonSize;
+    /** Icon before the label. */
+    leadingIcon?: IconName;
+    /** Icon after the label, for direction or a menu. */
+    trailingIcon?: IconName;
+}
+/** Triggers an action. For navigation, use Link instead. */
+export declare const Button: import("react").ForwardRefExoticComponent<ButtonProps & import("react").RefAttributes<HTMLButtonElement>>;

package/dist/components/Button/index.d.ts

@@ -0,0 +1 @@
+export * from './Button';

package/dist/components/Calendar/Calendar.d.ts

@@ -0,0 +1,49 @@
+import { type HTMLAttributes } from 'react';
+import { type DateRange, type WeekStart } from './dateUtils';
+export interface CalendarProps extends Omit<HTMLAttributes<HTMLDivElement>, 'onChange' | 'defaultValue'> {
+    /** The selected day, when controlled. Use a Date at local midnight. */
+    value?: Date | null;
+    /** The first selected day, when uncontrolled. */
+    defaultValue?: Date | null;
+    /** Called with the day, at local midnight, when a day is chosen. */
+    onChange?: (date: Date) => void;
+    /** Shows a range instead of a single day. The parent decides what a chosen day does to it. */
+    range?: DateRange;
+    /** While `range` has only a start, previews the range from the start to this day. */
+    rangePreview?: Date | null;
+    /** Called when the pointer or keyboard focus reaches a day that can be chosen. */
+    onDayPreview?: (date: Date) => void;
+    /** The first month shown, when controlled. */
+    month?: Date;
+    /** The first month shown at the start, when uncontrolled. Defaults to the selected month, or else `today`. */
+    defaultMonth?: Date;
+    /** Called with the first day of the first month shown, when it changes. */
+    onMonthChange?: (month: Date) => void;
+    /** The earliest day that can be chosen. */
+    min?: Date;
+    /** The latest day that can be chosen. */
+    max?: Date;
+    /** Returns true for a day that can't be chosen. */
+    isDateDisabled?: (date: Date) => boolean;
+    /** BCP 47 locale for names and numbers. Leave out to use the browser's locale. */
+    locale?: string;
+    /** The first column of the grid: 0 is Sunday and 1 is Monday. */
+    weekStartsOn?: WeekStart;
+    /** How many months to show. Two months sit side by side, and stack when the container is narrow. */
+    months?: 1 | 2;
+    /** The day marked as today. Defaults to now. Pass it for repeatable tests. */
+    today?: Date;
+    /** Shows days of the months around a month. Defaults to true for one month. With two months it would repeat days. */
+    showOutsideDays?: boolean;
+    /** Moves focus to the current day when the calendar appears, as a date picker popup does. */
+    autoFocusDay?: boolean;
+    /** Accessible name of the previous month button. */
+    previousMonthLabel?: string;
+    /** Accessible name of the next month button. */
+    nextMonthLabel?: string;
+}
+/**
+ * A month grid for choosing a day, following the WAI-ARIA grid pattern with a roving tabindex. Arrow keys move by day
+ * and week, Home and End to the ends of the week, PageUp and PageDown by month, and with Shift by year.
+ */
+export declare const Calendar: import("react").ForwardRefExoticComponent<CalendarProps & import("react").RefAttributes<HTMLDivElement>>;

package/dist/components/Calendar/CalendarDay.d.ts

@@ -0,0 +1,25 @@
+import { type ButtonHTMLAttributes } from 'react';
+export interface CalendarDayProps extends Omit<ButtonHTMLAttributes<HTMLButtonElement>, 'children' | 'value'> {
+    /** The day this cell shows. */
+    date: Date;
+    /** BCP 47 locale for the number and the accessible name. Leave out to use the browser's locale. */
+    locale?: string;
+    /** Marks the current day with a dot and `aria-current="date"`. */
+    today?: boolean;
+    /** Fills the day with the accent colour. */
+    selected?: boolean;
+    /** The first day of a range. */
+    rangeStart?: boolean;
+    /** The last day of a range. */
+    rangeEnd?: boolean;
+    /** A day between the two ends of a range. */
+    inRange?: boolean;
+    /** The range state on this day is only a preview, while the end date is being chosen. It isn't selected yet. */
+    preview?: boolean;
+    /** A day from the month before or after the one shown. */
+    outsideMonth?: boolean;
+    /** The day can't be chosen. It uses `aria-disabled`, so the keyboard can still reach it and hear why. */
+    disabled?: boolean;
+}
+/** One day of the month grid: a grid cell holding a button. Render it inside a row of a `role="grid"` table. */
+export declare const CalendarDay: import("react").ForwardRefExoticComponent<CalendarDayProps & import("react").RefAttributes<HTMLButtonElement>>;

package/dist/components/Calendar/CalendarHeader.d.ts

@@ -0,0 +1,27 @@
+import { type HTMLAttributes } from 'react';
+export interface CalendarHeaderProps extends HTMLAttributes<HTMLDivElement> {
+    /** Any day in the month to name. */
+    month: Date;
+    /** BCP 47 locale for the month name. Leave out to use the browser's locale. */
+    locale?: string;
+    /** The id of the month label, so a grid can name itself with it. */
+    labelId?: string;
+    /** Called when the previous month button is used. */
+    onPrevious?: () => void;
+    /** Called when the next month button is used. */
+    onNext?: () => void;
+    /** Stops the previous month button, at the first month allowed. */
+    previousDisabled?: boolean;
+    /** Stops the next month button, at the last month allowed. */
+    nextDisabled?: boolean;
+    /** Leaves out the previous month button, for the later months of a multi-month calendar. Its space stays. */
+    hidePrevious?: boolean;
+    /** Leaves out the next month button, for the earlier months of a multi-month calendar. Its space stays. */
+    hideNext?: boolean;
+    /** Accessible name of the previous month button. */
+    previousLabel?: string;
+    /** Accessible name of the next month button. */
+    nextLabel?: string;
+}
+/** The month name with previous and next buttons, above a month grid. Month changes are announced politely. */
+export declare const CalendarHeader: import("react").ForwardRefExoticComponent<CalendarHeaderProps & import("react").RefAttributes<HTMLDivElement>>;

package/dist/components/Calendar/DateTriggerInternal.d.ts

@@ -0,0 +1,30 @@
+import { type ButtonHTMLAttributes, type Ref } from 'react';
+export interface DateTriggerInternalProps extends Omit<ButtonHTMLAttributes<HTMLButtonElement>, 'value' | 'children'> {
+    /** The formatted value, or null when there is none. */
+    text: string | null;
+    /** Text shown when there is no value. */
+    placeholder?: string;
+    /** Shows the error state and sets `aria-invalid`. */
+    invalid?: boolean;
+    /** Read-only look with a "Locked" tag. */
+    locked?: boolean;
+    /** Marks the control as required. */
+    required?: boolean;
+    /** Whether the popup is showing. */
+    open?: boolean;
+    /** Shows a clear button while there is a value. */
+    clearable?: boolean;
+    /** Called when the clear button is used. */
+    onClear?: () => void;
+    /** Accessible name of the clear button. */
+    clearLabel?: string;
+    /** The id of the popup, while it shows. */
+    popupId?: string;
+    /** Receives the outer box, which the popup lines up with. */
+    anchorRef?: Ref<HTMLDivElement>;
+}
+/**
+ * The box of DatePicker and DateRangeTrigger. It looks like the Select control, and like Select it is a select-only
+ * combobox. The clear button can't sit inside a button, so the combobox button is stretched over the box instead.
+ */
+export declare const DateTriggerInternal: import("react").ForwardRefExoticComponent<DateTriggerInternalProps & import("react").RefAttributes<HTMLButtonElement>>;

package/dist/components/Calendar/dateUtils.d.ts

@@ -0,0 +1,95 @@
+/**
+ * Pure date maths for the calendar components.
+ *
+ * A date here is a local calendar day. Every calculation goes through the year, month and day numbers, never through
+ * a count of milliseconds, so a daylight saving change or a time zone can't move a date onto another day.
+ */
+/** A range of local calendar days. Either end can be empty while it is being chosen. */
+export interface DateRange {
+    /** The first day of the range. */
+    start: Date | null;
+    /** The last day of the range. */
+    end: Date | null;
+}
+/** The first column of the month grid: 0 is Sunday, 1 is Monday and 6 is Saturday. */
+export type WeekStart = 0 | 1 | 2 | 3 | 4 | 5 | 6;
+/** The limits on which days can be chosen. */
+export interface DateLimits {
+    /** The earliest day that can be chosen. */
+    min?: Date;
+    /** The latest day that can be chosen. */
+    max?: Date;
+    /** Returns true for a day that can't be chosen. */
+    isDateDisabled?: (date: Date) => boolean;
+}
+/** The limits on a whole range. */
+export interface RangeLimits extends DateLimits {
+    /** The fewest days a range can include, counting both ends. */
+    minDays?: number;
+    /** The most days a range can include, counting both ends. */
+    maxDays?: number;
+    /** Lets a range run across a disabled day. Neither end can be on one. */
+    allowDisabledInRange?: boolean;
+}
+/** The same calendar day at local midnight. */
+export declare function startOfDay(date: Date): Date;
+/** True when both are the same calendar day. Empty values are never the same. */
+export declare function isSameDay(a: Date | null | undefined, b: Date | null | undefined): boolean;
+/** True when both are in the same month of the same year. */
+export declare function isSameMonth(a: Date, b: Date): boolean;
+/** Negative when `a` is the earlier day, positive when it is the later day, and 0 when they are the same day. */
+export declare function compareDays(a: Date, b: Date): number;
+/** The number of days from `a` to `b`. Negative when `b` is earlier. */
+export declare function daysBetween(a: Date, b: Date): number;
+/** The number of days in a range, counting both ends. */
+export declare function rangeLength(a: Date, b: Date): number;
+/** The calendar day `amount` days away. */
+export declare function addDays(date: Date, amount: number): Date;
+/** The same day `amount` months away. A day the target month doesn't have becomes its last day: 31 Jan to 28 Feb. */
+export declare function addMonths(date: Date, amount: number): Date;
+/** The same day `amount` years away. 29 Feb becomes 28 Feb when the target year isn't a leap year. */
+export declare function addYears(date: Date, amount: number): Date;
+/** The first day of the month. */
+export declare function startOfMonth(date: Date): Date;
+/** The last day of the month. */
+export declare function endOfMonth(date: Date): Date;
+/** The first day of the week containing `date`. */
+export declare function startOfWeek(date: Date, weekStartsOn?: WeekStart): Date;
+/** The last day of the week containing `date`. */
+export declare function endOfWeek(date: Date, weekStartsOn?: WeekStart): Date;
+/** The month as six full weeks, so the grid keeps its height from month to month. */
+export declare function monthWeeks(month: Date, weekStartsOn?: WeekStart): Date[][];
+/** Seven days in column order, for naming the columns of the grid. 1 Jan 2024 was a Monday. */
+export declare function weekdayDates(weekStartsOn?: WeekStart): Date[];
+/** The day moved just enough to sit between `min` and `max`. */
+export declare function clampDay(date: Date, min?: Date, max?: Date): Date;
+/** True when a day can't be chosen, because of `min`, `max` or `isDateDisabled`. */
+export declare function isDayDisabled(date: Date, { min, max, isDateDisabled }: DateLimits): boolean;
+/** The range with its ends in order. Days are kept at local midnight. */
+export declare function sortRange(a: Date, b: Date): {
+    start: Date;
+    end: Date;
+};
+/**
+ * Makes a test for which days can end a range that begins at `start`, once a start date is chosen. It remembers the
+ * nearest disabled day found on each side, so testing a whole month of days doesn't walk the calendar each time.
+ */
+export declare function createEndDateTest(start: Date, limits: RangeLimits): (date: Date) => boolean;
+/** True when a whole range can be used, for example a preset. */
+export declare function isRangeAllowed(range: DateRange, limits: RangeLimits): boolean;
+/** The day as `YYYY-MM-DD`, in local time. */
+export declare function toISODay(date: Date): string;
+/** Short date for the triggers: `12 Mar 2026`. */
+export declare function formatShortDate(date: Date, locale?: string): string;
+/** Long date for announcements: `12 March 2026`. */
+export declare function formatLongDate(date: Date, locale?: string): string;
+/** The full name of a day cell: `Thursday 12 March 2026`. */
+export declare function formatFullDate(date: Date, locale?: string): string;
+/** The month heading: `March 2026`. */
+export declare function formatMonthLabel(date: Date, locale?: string): string;
+/** The column heading of a weekday: `Mon`, or `Monday` when `long`. */
+export declare function formatWeekday(date: Date, locale?: string, long?: boolean): string;
+/** The number in a day cell, in the digits of the locale but without a suffix such as the Japanese 日. */
+export declare function formatDayNumber(date: Date, locale?: string): string;
+/** A range for a trigger: `12 Mar 2026 – 18 Mar 2026`. An empty end leaves the dash open. Null when there is no start. */
+export declare function formatRangeText(range: DateRange | null | undefined, locale?: string): string | null;

package/dist/components/Calendar/index.d.ts

@@ -0,0 +1,4 @@
+export * from './Calendar';
+export * from './CalendarDay';
+export * from './CalendarHeader';
+export type { DateLimits, DateRange, RangeLimits, WeekStart } from './dateUtils';

package/dist/components/Calendar/useDatePopup.d.ts

@@ -0,0 +1,22 @@
+import { type ForwardedRef, type KeyboardEvent } from 'react';
+export interface UseDatePopupOptions {
+    /** Whether the popup is rendered. */
+    open: boolean;
+    /** Sets `open` to false and drops any unfinished selection. It doesn't move focus. */
+    onDismiss: () => void;
+    /** The ref given to the picker, which receives the combobox button. */
+    forwardedRef: ForwardedRef<HTMLButtonElement>;
+}
+/**
+ * The popup behaviour shared by DatePicker and DateRangePicker. It positions against the trigger box and dismisses on
+ * Escape or an outside press. Like the WAI-ARIA date picker dialog it keeps Tab inside, and focus returns to the trigger
+ * on the way out. A press on something else focusable still moves focus there, because the browser acts after this does.
+ */
+export declare function useDatePopup({ open, onDismiss, forwardedRef }: UseDatePopupOptions): {
+    buttonRef: import("react").RefObject<HTMLButtonElement | null>;
+    triggerRef: import("react").RefObject<HTMLDivElement | null>;
+    popupRef: import("react").RefObject<HTMLDivElement | null>;
+    popupStyle: import("react").CSSProperties;
+    focusTrigger: () => void | undefined;
+    onPopupKeyDown: (event: KeyboardEvent<HTMLElement>) => void;
+};

package/dist/components/Card/Card.d.ts

@@ -0,0 +1,10 @@
+import { type ElementType, type HTMLAttributes } from 'react';
+export type CardPadding = 'md' | 'lg' | 'none';
+export interface CardProps extends HTMLAttributes<HTMLElement> {
+    /** Inner padding: `md` is 16 px and `lg` is 24 px. Use `none` for content that touches the edges, such as a table. */
+    padding?: CardPadding;
+    /** Element to render, such as `section` or `article`. */
+    as?: ElementType;
+}
+/** Bordered container for a group of related content. It has no shadow. */
+export declare const Card: import("react").ForwardRefExoticComponent<CardProps & import("react").RefAttributes<HTMLElement>>;

package/dist/components/Card/CardFooter.d.ts

@@ -0,0 +1,8 @@
+import { type HTMLAttributes } from 'react';
+export type CardFooterAlign = 'start' | 'end' | 'between';
+export interface CardFooterProps extends HTMLAttributes<HTMLDivElement> {
+    /** How the content sits along the footer. */
+    align?: CardFooterAlign;
+}
+/** Bottom section of a Card, usually for actions. Use it as the last child of the card. */
+export declare const CardFooter: import("react").ForwardRefExoticComponent<CardFooterProps & import("react").RefAttributes<HTMLDivElement>>;

package/dist/components/Card/CardHeader.d.ts

@@ -0,0 +1,14 @@
+import { type HTMLAttributes, type ReactNode } from 'react';
+export type CardHeadingLevel = 2 | 3 | 4 | 5 | 6;
+export interface CardHeaderProps extends Omit<HTMLAttributes<HTMLDivElement>, 'title'> {
+    /** Card title, rendered as a heading. */
+    title: ReactNode;
+    /** Supporting text under the title. */
+    description?: ReactNode;
+    /** Controls at the end of the header, such as an IconButton. */
+    actions?: ReactNode;
+    /** Heading level of the title, to fit the outline of the page. */
+    headingLevel?: CardHeadingLevel;
+}
+/** Top section of a Card, with a title and optional description and actions. Use it as the first child of the card. */
+export declare const CardHeader: import("react").ForwardRefExoticComponent<CardHeaderProps & import("react").RefAttributes<HTMLDivElement>>;

package/dist/components/Card/index.d.ts

@@ -0,0 +1,3 @@
+export * from './Card';
+export * from './CardFooter';
+export * from './CardHeader';

package/dist/components/CatalogCard/CatalogCard.d.ts

@@ -0,0 +1,18 @@
+import { type HTMLAttributes, type ReactNode } from 'react';
+import { type IconName } from '../../icons';
+export interface CatalogCardProps extends Omit<HTMLAttributes<HTMLElement>, 'title'> {
+    /** Icon in the tile at the top left. */
+    icon?: IconName;
+    /** The name of the item. */
+    title: ReactNode;
+    /** A short line below the name. */
+    subtitle?: ReactNode;
+    /** What the item does. */
+    description?: ReactNode;
+    /** A quieter action at the bottom left, such as a docs Button. */
+    secondaryAction?: ReactNode;
+    /** The main action at the bottom right, normally a Button. */
+    primaryAction?: ReactNode;
+}
+/** An item that can be added or started, in a catalog of choices. */
+export declare const CatalogCard: import("react").ForwardRefExoticComponent<CatalogCardProps & import("react").RefAttributes<HTMLElement>>;

package/dist/components/CatalogCard/index.d.ts

@@ -0,0 +1 @@
+export * from './CatalogCard';

package/dist/components/ChartCard/ChartCard.d.ts

@@ -0,0 +1,30 @@
+import { type HTMLAttributes, type ReactNode } from 'react';
+/** One choice in the range control. */
+export interface ChartCardRange {
+    /** Stable value reported on change. */
+    value: string;
+    /** Text on the tab. */
+    label: string;
+}
+export interface ChartCardProps extends Omit<HTMLAttributes<HTMLElement>, 'title' | 'onChange'> {
+    /** What the chart is about. */
+    title: ReactNode;
+    /** What the chart shows and where the data comes from. */
+    subtitle?: ReactNode;
+    /** Heading level of the title, to fit the page's outline. */
+    headingLevel?: 2 | 3 | 4 | 5;
+    /** Choices for the range control. Without them there is no control. */
+    ranges?: ChartCardRange[];
+    /** Selected range, when controlled. */
+    rangeValue?: string;
+    /** Selected range at first, when uncontrolled. */
+    defaultRangeValue?: string;
+    /** Called with the new range. */
+    onRangeChange?: (value: string) => void;
+    /** Accessible name of the range control. */
+    rangeLabel?: string;
+    /** The chart. */
+    children?: ReactNode;
+}
+/** A titled container for any chart, with a time range control. */
+export declare const ChartCard: import("react").ForwardRefExoticComponent<ChartCardProps & import("react").RefAttributes<HTMLElement>>;

package/dist/components/ChartCard/index.d.ts

@@ -0,0 +1 @@
+export * from './ChartCard';

package/dist/components/ChartCore/ChartAxes.d.ts

@@ -0,0 +1,24 @@
+import type { PlotArea } from './types';
+/** A labelled position along an axis. */
+export interface AxisTick {
+    /** Pixel position along the axis. */
+    position: number;
+    /** Text to show. */
+    label: string;
+}
+export interface ChartAxesProps {
+    /** The rectangle the marks are drawn in. */
+    plot: PlotArea;
+    /** Labels under the plot. */
+    xTicks?: AxisTick[];
+    /** Labels to the left of the plot. */
+    yTicks?: AxisTick[];
+    /** Hairlines across the plot at each y tick. Turn off when the y axis names categories. */
+    grid?: boolean;
+    /** Whether the y labels name categories. They then read in a stronger text colour. */
+    categoryY?: boolean;
+    /** Draws a hairline up the left of the plot, as the baseline of horizontal bars. */
+    leftBaseline?: boolean;
+}
+/** SVG axis labels and hairline gridlines. Render it inside an `svg`, before the marks. */
+export declare function ChartAxes({ plot, xTicks, yTicks, grid, categoryY, leftBaseline }: ChartAxesProps): import("react").JSX.Element;

package/dist/components/ChartCore/ChartDataTable.d.ts

@@ -0,0 +1,19 @@
+/** One row of a chart's data table. */
+export interface ChartDataTableRow {
+    /** Stable identifier. */
+    id: string;
+    /** Text in the first cell, which names the row. */
+    header: string;
+    /** Remaining cells, in column order. */
+    cells: string[];
+}
+export interface ChartDataTableProps {
+    /** Names the table. Usually the chart's accessible name. */
+    caption: string;
+    /** Column headings, including the one above the row names. */
+    columns: string[];
+    /** The values. */
+    rows: ChartDataTableRow[];
+}
+/** Visually hidden table of a chart's values, so that nothing depends on seeing the marks or hovering them. */
+export declare function ChartDataTable({ caption, columns, rows }: ChartDataTableProps): import("react").JSX.Element;

package/dist/components/ChartCore/ChartFrame.d.ts

@@ -0,0 +1,11 @@
+import { type HTMLAttributes, type ReactNode } from 'react';
+export interface ChartFrameProps extends HTMLAttributes<HTMLDivElement> {
+    /** Height reserved for the message when there is nothing to draw. */
+    height: number;
+    /** Shows `emptyMessage` in place of the chart and draws nothing. */
+    empty?: boolean;
+    /** Explains why there is nothing to draw. */
+    emptyMessage?: ReactNode;
+}
+/** Root of every chart. Sets the surface the marks sit on, bounds the tooltip and shows the empty message. */
+export declare const ChartFrame: import("react").ForwardRefExoticComponent<ChartFrameProps & import("react").RefAttributes<HTMLDivElement>>;

package/dist/components/ChartCore/ChartHoverLayer.d.ts

@@ -0,0 +1,21 @@
+import { type HTMLAttributes, type ReactNode } from 'react';
+import type { ChartAnchor } from './types';
+import type { ChartHover } from './useChartHover';
+export interface ChartHoverLayerProps extends Omit<HTMLAttributes<HTMLDivElement>, 'children'> {
+    /** State and handlers from `useChartHover`. */
+    hover: ChartHover;
+    /** Accessible name of the plot. */
+    label: string;
+    /** Height of the plot in pixels. */
+    height: number;
+    /** Where the tooltip points. Leave unset when nothing is active. */
+    anchor?: ChartAnchor | null;
+    /** The tooltip for the active point. */
+    tooltip?: ReactNode;
+    /** Text read out by screen readers when the keyboard moves the active point. */
+    announcement?: string;
+    /** The chart's `svg`. */
+    children?: ReactNode;
+}
+/** The focusable plot. Takes pointer and keyboard input, and keeps the tooltip beside the active point and inside the chart. */
+export declare const ChartHoverLayer: import("react").ForwardRefExoticComponent<ChartHoverLayerProps & import("react").RefAttributes<HTMLDivElement>>;

package/dist/components/ChartCore/chartPlayHelpers.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Builds the input for `userEvent.pointer` that moves the pointer to a spot in a plot, given as fractions of its size.
+ * Used by play functions. Not exported from the package.
+ */
+export declare function pointerAt(target: Element, xFraction: number, yFraction?: number): {
+    target: Element;
+    coords: {
+        clientX: number;
+        clientY: number;
+    };
+};

package/dist/components/ChartCore/index.d.ts

@@ -0,0 +1,10 @@
+export * from './types';
+export * from './scales';
+export * from './paths';
+export * from './series';
+export * from './useChartSize';
+export * from './useChartHover';
+export * from './ChartAxes';
+export * from './ChartHoverLayer';
+export * from './ChartDataTable';
+export * from './ChartFrame';

package/dist/components/ChartCore/paths.d.ts

@@ -0,0 +1,23 @@
+/** A plotted position, or `null` where nothing was recorded. */
+export type PathPoint = {
+    x: number;
+    y: number;
+} | null;
+/** Which way a bar grows from its baseline. Only that end is rounded. */
+export type BarDirection = 'up' | 'down' | 'right' | 'left';
+/** SVG path for a line. A missing value breaks the line rather than dropping it to zero. */
+export declare function linePath(points: PathPoint[]): string;
+/** SVG path for the wash under a line, closed along the baseline. */
+export declare function areaPath(points: PathPoint[], baselineY: number): string;
+/** SVG path for a bar: rounded at the data end when `radius` is set, always square at the baseline. */
+export declare function barPath(x: number, y: number, width: number, height: number, direction: BarDirection, radius?: number): string;
+/** A point on a circle. Angle 0 is 12 o'clock and angles run clockwise. */
+export declare function polar(cx: number, cy: number, radius: number, angle: number): {
+    x: number;
+    y: number;
+};
+/**
+ * SVG path for a ring segment between two angles. `gap` is the width in pixels of the space between
+ * neighbouring segments: the angle is trimmed per radius so that the gap has parallel sides.
+ */
+export declare function arcPath(cx: number, cy: number, outer: number, inner: number, start: number, end: number, gap?: number): string;

package/dist/components/ChartCore/scales.d.ts

@@ -0,0 +1,40 @@
+import type { ChartAnchor, ChartSegment, ChartSeries } from './types';
+/** The most series or segments a chart colours. Past this, the rest fold into Other. */
+export declare const MAX_SERIES = 5;
+/** Keeps a number inside a range. */
+export declare function clamp(value: number, min: number, max: number): number;
+/** Returns a function that maps a value from one numeric range to another. */
+export declare function linearScale(domain: [number, number], range: [number, number]): (value: number) => number;
+/** Round axis ticks that cover the values and leave a little headroom above the highest one. */
+export declare function niceTicks(min: number, max: number, count?: number): number[];
+/** Formats axis ticks in one style: in full under 10,000, compact when the axis reaches it. */
+export declare function formatTicks(ticks: number[]): string[];
+/** Default value format for labels, tooltips and tables. */
+export declare function formatValue(value: number): string;
+/** Which label positions to show so that labels sit at least `minSpacing` pixels apart. */
+export declare function thinTickIndexes(count: number, spacing: number, minSpacing?: number): number[];
+/** Rough width of a caption-sized string, used to reserve room before the text is drawn. */
+export declare function estimateTextWidth(text: string): number;
+/** The position labels of a set of series, taken from the longest. */
+export declare function seriesLabels(series: ChartSeries[]): string[];
+/** The position of the last recorded value, or -1 when there is none. */
+export declare function lastRecordedIndex(values: (number | null)[]): number;
+/** Whether any series has at least one recorded value. */
+export declare function hasSeriesData(series: ChartSeries[]): boolean;
+/** Recorded values across a set of series. */
+export declare function seriesValues(series: ChartSeries[]): number[];
+/** Keeps the first four series and sums the rest into Other when there are more than five. */
+export declare function foldSeries(series: ChartSeries[], otherName?: string): ChartSeries[];
+/** Keeps the first four segments and sums the rest into Other when there are more than five. */
+export declare function foldSegments(segments: ChartSegment[], otherLabel?: string): ChartSegment[];
+/** Places a tooltip beside its anchor, flipping sides and clamping so that it stays inside the bounds. */
+export declare function placeTooltip(anchor: ChartAnchor, tooltip: {
+    width: number;
+    height: number;
+}, bounds: {
+    width: number;
+    height: number;
+}, gap?: number): {
+    x: number;
+    y: number;
+};

package/dist/components/ChartCore/series.d.ts

@@ -0,0 +1,4 @@
+import marks from './marks.module.css';
+/** Class that sets the colour of a series, by its fixed position: 0 is chart/1 and 4 is chart/5. */
+export declare function seriesColorClass(index: number): string;
+export { marks as chartMarks };

package/dist/components/ChartCore/types.d.ts

@@ -0,0 +1,38 @@
+/** One position on a series. A `null` value means nothing was recorded there: it leaves a gap and is never drawn as zero. */
+export interface ChartPoint {
+    /** Position name, such as a month or category. */
+    label: string;
+    /** Measured value, or `null` when nothing was recorded. */
+    value: number | null;
+}
+/** A named run of values. Its position in the array sets its colour, so hiding another series never repaints it. */
+export interface ChartSeries {
+    /** Stable identifier. */
+    id: string;
+    /** Name shown in the legend and tooltip. */
+    name: string;
+    /** Values in display order. */
+    points: ChartPoint[];
+}
+/** A slice of a whole, used by the donut chart. */
+export interface ChartSegment {
+    /** Stable identifier. */
+    id: string;
+    /** Name shown in the legend and tooltip. */
+    label: string;
+    /** Size of this slice, in the same unit as the others. */
+    value: number;
+}
+/** The rectangle that the marks are drawn in, in SVG pixels. */
+export interface PlotArea {
+    left: number;
+    right: number;
+    top: number;
+    bottom: number;
+}
+/** Where the tooltip points. `reach` is how far the highlighted mark extends sideways from `x`, so the tooltip clears it. */
+export interface ChartAnchor {
+    x: number;
+    y: number;
+    reach?: number;
+}

package/dist/components/ChartCore/useChartHover.d.ts

@@ -0,0 +1,25 @@
+import { type KeyboardEvent, type PointerEvent } from 'react';
+/** What set the active point. Only keyboard moves are announced, because a moving pointer would flood a screen reader. */
+export type ChartHoverSource = 'pointer' | 'keyboard';
+export interface UseChartHoverOptions {
+    /** How many points the keyboard can move through. */
+    count: number;
+    /** Finds the point for a pointer position in plot pixels, or `null` when the pointer is near none. */
+    locate: (x: number, y: number) => number | null;
+}
+export interface ChartHover {
+    /** The active point, or `null`. */
+    activeIndex: number | null;
+    /** What set the active point. */
+    source: ChartHoverSource;
+    /** Handlers to spread onto the focusable plot. */
+    plotProps: {
+        onPointerMove: (event: PointerEvent<HTMLElement>) => void;
+        onPointerDown: (event: PointerEvent<HTMLElement>) => void;
+        onPointerLeave: () => void;
+        onKeyDown: (event: KeyboardEvent<HTMLElement>) => void;
+        onBlur: () => void;
+    };
+}
+/** Tracks a chart's active point from the pointer and the keyboard: arrows, Home and End move it, and Escape clears it. */
+export declare function useChartHover({ count, locate }: UseChartHoverOptions): ChartHover;

package/dist/components/ChartCore/useChartSize.d.ts

@@ -0,0 +1,6 @@
+import { type ForwardedRef } from 'react';
+/** Measures an element's width with a ResizeObserver, so a chart fills its container. Width is 0 until first measured. */
+export declare function useChartSize<T extends HTMLElement = HTMLDivElement>(forwardedRef?: ForwardedRef<T>): {
+    ref: (node: T | null) => void;
+    width: number;
+};