@ceebee/ui 1.8.0 → 1.10.0

package/dist/client.d.ts

@@ -377,6 +377,452 @@ declare const PanZoomCanvas: typeof PanZoomCanvasRoot & {
     Skeleton: typeof PanZoomCanvasSkeleton;
 };
 
+interface BoardSkeletonProps {
+    /** How many columns to stand in for — the same shape the real board will draw. */
+    columns?: number;
+    /** Cards per column. */
+    cards?: number;
+    label?: string;
+}
+/**
+ * The board's placeholder, built from the same geometry as the board itself, so the page does not
+ * reflow when the real columns arrive.
+ */
+declare function BoardSkeleton({ columns, cards, label }: BoardSkeletonProps): react.JSX.Element;
+
+/** One card on the board. `disabled` refuses movement without hiding the card. */
+interface BoardCard {
+    id: string;
+    title: ReactNode;
+    /**
+     * The card's name in an announcement and on the drag handle, when `title` is a node rather than a
+     * string. Without it a node-titled card is announced by its id, which is a uuid read aloud.
+     */
+    label?: string;
+    /** Whatever a person triages by — an owner, an age, a due date, a blocked marker. */
+    meta?: ReactNode;
+    /** A card that cannot move: it stays visible, is not a drag source, and is skipped by the keyboard path. */
+    disabled?: boolean;
+    /** Why it cannot move, announced when a move is attempted on it. */
+    disabledReason?: string;
+}
+/** One column: a state of the workflow, not a category of thing. */
+interface BoardColumn {
+    id: string;
+    name: ReactNode;
+    /**
+     * The column's accessible name, when `name` is a node rather than a string — a header carrying
+     * status tags still has to be nameable. Without it a node-named column has no accessible name.
+     */
+    label?: string;
+    cards: BoardCard[];
+    /** A work-in-progress limit, shown beside the count; exceeding it marks the column, never blocks a move. */
+    limit?: number;
+    /** Shown when the column holds no cards. An empty column must still invite one. */
+    empty?: ReactNode;
+    /** A column that takes no cards — an end state, say. Dropping onto it is refused with `refusal`. */
+    accepts?: boolean;
+    /** Why this column refuses a card, announced and shown on an attempted drop. */
+    refusal?: string;
+}
+/** Where a card is, or is going. `index` is its position within the column, 0-based. */
+interface BoardPosition {
+    columnId: string;
+    index: number;
+}
+/** A move the consumer is asked to validate and apply. */
+interface BoardMove {
+    cardId: string;
+    from: BoardPosition;
+    to: BoardPosition;
+}
+/**
+ * What the consumer answers with. Resolving accepts the move; rejecting — or resolving with a
+ * `refused` reason — rolls the board back and says why.
+ */
+type BoardMoveResult = void | {
+    refused: string;
+};
+/** The shape the pure logic needs: ids and order, no React. */
+interface BoardShape {
+    id: string;
+    cards: {
+        id: string;
+        disabled?: boolean;
+    }[];
+    accepts?: boolean;
+}
+
+interface BoardLabels {
+    pickUp: string;
+    dropped: (card: string, column: string) => string;
+    cancelled: string;
+    refused: (reason: string) => string;
+    undo: string;
+    /** The drag handle's accessible name, when cards carry their own actions. */
+    move: (card: string) => string;
+    undone: string;
+    lanes: string;
+    over: (count: number, limit: number) => string;
+}
+interface BoardProps {
+    columns: BoardColumn[];
+    /**
+     * The one path every move takes, from the pointer and from the keyboard alike. Return nothing to
+     * accept it; return `{ refused }` or reject to roll the board back and say why.
+     */
+    onMove: (move: BoardMove) => BoardMoveResult | Promise<BoardMoveResult>;
+    /** `auto` switches to lanes on a narrow viewport; force either to prove one in a test. */
+    layout?: 'auto' | 'board' | 'lanes';
+    /** What `auto` calls narrow. */
+    phoneQuery?: string;
+    labels?: Partial<BoardLabels>;
+    motion?: boolean;
+    /**
+     * Put the grab on a handle instead of the whole card. Use it whenever a card carries its own
+     * buttons: a card that is itself a control has **presentational children**, so anything
+     * interactive inside it disappears from the accessibility tree. With a handle the card is plain
+     * markup, its buttons stay reachable, and the handle is the one thing that drags and takes the
+     * keyboard.
+     */
+    handle?: boolean;
+    'aria-label'?: string;
+}
+declare function BoardRoot({ columns, onMove, layout, phoneQuery, labels, motion, handle, 'aria-label': ariaLabel, }: BoardProps): react.JSX.Element;
+declare const Board: typeof BoardRoot & {
+    Skeleton: typeof BoardSkeleton;
+};
+
+/**
+ * What a dated series means, with no chart and no DOM in sight.
+ *
+ * Kept pure for the usual reason and one extra: these charts are drawn on a **canvas**, so nothing
+ * about them is inspectable from the outside. These functions are the only testable description of
+ * what the picture claims, and they are also what feeds the text alternative a screen reader reads
+ * and what a forced-colors viewer gets instead of the bitmap.
+ */
+/** One reading: a day, and a value on that day. */
+interface SeriesPoint {
+    /** `YYYY-MM-DD`. A calendar day, not an instant. */
+    day: string;
+    value: number;
+}
+/**
+ * `YYYY-MM-DD`, or null when it is not a day at all.
+ *
+ * The pattern is not the check: `2026-02-30` matches it and is not a day. The round-trip through `Date`
+ * settles that — but **an impossible month makes an Invalid Date, and `toISOString()` throws on one**
+ * rather than returning anything falsy. So the time value is tested before it is formatted; otherwise
+ * `2026-13-01` takes the whole chart down instead of being ignored.
+ */
+declare function asDay(value: string): string | null;
+/**
+ * The points as the chart substrate demands them: ascending, and one per day.
+ *
+ * This is not tidying. The library **throws** on a repeated or out-of-order time rather than ignoring
+ * it, so a source that reports the same day twice — a correction, two crews reporting the same site —
+ * would take the whole screen down. The later value wins, because a correction is the point of sending
+ * the day again.
+ */
+declare function seriesPoints(points: readonly SeriesPoint[]): SeriesPoint[];
+/** The value a series holds on a day: its last reading at or before it, or null before it starts. */
+declare function valueOn(points: readonly SeriesPoint[], day: string): number | null;
+/**
+ * Every day any series reports, with each series' value on it — the accessible rendering, not a caption.
+ *
+ * A canvas has no DOM, so this is the *only* thing a screen reader can be given, and it is what a
+ * forced-colors viewer sees in place of the bitmap. It is therefore the same data, not a summary. A
+ * value is carried forward from the last reading: a day nobody reported is not a day of nothing, and
+ * showing it as zero would say the measure collapsed.
+ */
+declare function alignRows(series: readonly {
+    key: string;
+    points: readonly SeriesPoint[];
+}[]): {
+    day: string;
+    values: Record<string, number | null>;
+}[];
+/** The span the axis has to cover, or null when there is nothing to draw. */
+declare function seriesSpan(series: readonly {
+    points: readonly SeriesPoint[];
+}[]): {
+    from: string;
+    to: string;
+} | null;
+/**
+ * The reported day closest to a given one, or null when nothing was reported.
+ *
+ * A marker attaches to a data point — the substrate has no vertical line of its own — so anything a
+ * chart wants to mark has to land on a day some series actually reports.
+ */
+declare function nearestDay(days: readonly string[], day: string): string | null;
+/** One decimal, because a figure read to four is false precision on a number somebody estimated. */
+declare function round1(value: number): number;
+
+/** The colours a canvas is drawn in, resolved from Tokens rather than written down. */
+interface ChartPalette {
+    text: string;
+    muted: string;
+    grid: string;
+    background: string;
+    font: string;
+    /** One entry per series, in the order the series were given. */
+    series: string[];
+    /** Where a baseline series sits above its base, and below it. */
+    above: string;
+    below: string;
+}
+/** How thick, and solid or dashed. A plan reads as a reference; delivery reads as the fact. */
+type SeriesEmphasis = 'reference' | 'primary';
+interface SeriesSpec {
+    /** Stable key, used in the accessible table and to look a value up. */
+    key: string;
+    /** What a reader calls it. */
+    label: string;
+    points: SeriesPoint[];
+    emphasis?: SeriesEmphasis;
+    /** The Token this series takes its colour from, e.g. `--cb-tone-brand`. */
+    colorToken: string;
+}
+/**
+ * A fixed vertical range, when autoscale would lie.
+ *
+ * A percentage chart pins 0–100: autoscale stretches a job at 30% to the full height of the plot,
+ * which reads as *nearly there* — the opposite of the truth. A money chart normally does not pin,
+ * because there is no natural ceiling.
+ */
+interface ValueRange {
+    min: number;
+    max: number;
+}
+/**
+ * A baseline: the value the series is read against, coloured differently above and below.
+ *
+ * Zero on a cash projection is the obvious one — the day the balance crosses it is the whole point of
+ * the chart — and a minimum buffer is the useful one, because a business that must keep 50 juta on hand
+ * is in trouble well before it reaches zero.
+ */
+interface Baseline {
+    value: number;
+    label?: string;
+}
+interface TimeSeriesChartProps {
+    /** Accessible name. It is the chart's title as a screen reader announces it. */
+    label: string;
+    series: SeriesSpec[];
+    /** Turns a value into the text on the price scale and in the table. */
+    format: (value: number) => string;
+    range?: ValueRange;
+    /** Draws one series against a base value, shaded above and below. Only the first series is drawn. */
+    baseline?: Baseline;
+    /** A day to mark, and what to call it. The mark lands on the nearest day any series reports. */
+    mark?: {
+        day: string;
+        label: string;
+    };
+    height?: number;
+    emptyLabel?: string;
+    tableLabel?: string;
+    dayLabel?: string;
+    loading?: boolean;
+    className?: string;
+}
+interface TimeSeriesChartSkeletonProps {
+    height?: number;
+    label?: string;
+    className?: string;
+}
+
+/**
+ * A dated chart: any number of series over calendar days, or one series read against a baseline.
+ *
+ * It is drawn on a canvas, and that has one consequence which shapes this whole file: **the picture is
+ * not in the DOM.** A screen reader finds nothing, a forced-colors viewer gets a bitmap the system
+ * cannot recolour, and no test can look at it. So the table below the plot is not a caption or a
+ * fallback — it is the chart's other rendering, always present, built from the same numbers, and it is
+ * what a forced-colors viewer sees *instead of* the canvas.
+ *
+ * This is the primitive the library's dated Compositions are built from. It carries no domain meaning:
+ * it does not know what a plan is or what money is, only how to draw dated values honestly and how to
+ * say the same thing in words.
+ */
+declare function TimeSeriesChart({ label, series, format, range, baseline, mark, height, emptyLabel, tableLabel, dayLabel, loading, className, }: TimeSeriesChartProps): react.JSX.Element;
+
+/** Holds the chart's geometry while the readings load, so the page does not jump when they land. */
+declare function TimeSeriesChartSkeleton({ height, label, className, }: TimeSeriesChartSkeletonProps): react.JSX.Element;
+
+interface BalanceCurveProps {
+    /** Accessible name. It is the chart's title as a screen reader announces it. */
+    label: string;
+    /** The running balance, by day. One point per day the balance is known for. */
+    balances: SeriesPoint[];
+    /**
+     * How a value is written. The library holds no currency: a product passes its own formatter, so the
+     * same chart serves rupiah, a percentage of a budget, or litres of diesel.
+     */
+    format: (value: number) => string;
+    /**
+     * The line the balance is read against, and what to call it. Defaults to zero.
+     *
+     * Not always zero, and that is the point: a business that must keep a minimum on hand is in trouble
+     * well before it reaches nothing.
+     */
+    threshold?: {
+        value: number;
+        label?: string;
+    };
+    height?: number;
+    seriesLabel?: string;
+    emptyLabel?: string;
+    tableLabel?: string;
+    /** How the reading is worded. Each takes the formatted figures the component computed. */
+    belowLabel?: (from: string, lowest: string, days: number) => string;
+    clearLabel?: (lowest: string) => string;
+    loading?: boolean;
+    className?: string;
+}
+interface BalanceCurveSkeletonProps {
+    height?: number;
+    label?: string;
+    className?: string;
+}
+
+/** Holds the chart's geometry while the balances load, so the page does not jump when they land. */
+declare function BalanceCurveSkeleton({ height, label, className, }: BalanceCurveSkeletonProps): react.JSX.Element;
+
+/**
+ * A running balance over days, read against a line: a cash projection, a budget remaining, a tank.
+ *
+ * The substrate draws this as a **baseline** series rather than a line, which is not decoration: it
+ * shades above and below the threshold in the semantic colours, so the stretch that is in trouble is
+ * coloured by its own values instead of by a tag somebody has to read. Seven red tags in a row say
+ * nothing about how far down the dip goes; a shaded area says it at a glance.
+ *
+ * The sentence above the plot is the other half. A chart shows the shape; the sentence gives the two
+ * figures a decision needs — the day it goes under and the lowest it gets — so nobody has to read a
+ * position off an axis to act on it.
+ */
+declare function BalanceCurveRoot({ label, balances, format, threshold, height, seriesLabel, emptyLabel, tableLabel, belowLabel, clearLabel, loading, className, }: BalanceCurveProps): react.JSX.Element;
+/** The Composition and its Skeleton, so a loading page keeps the chart's geometry. */
+declare const BalanceCurve: typeof BalanceCurveRoot & {
+    Skeleton: typeof BalanceCurveSkeleton;
+};
+
+/**
+ * What a running balance says about itself.
+ *
+ * A balance chart exists to answer two questions a list of days cannot: **when does this dip below the
+ * line, and how far down does it go.** Both are computed here rather than left to the reader, because
+ * the reader's alternative is scanning thirty rows — which is exactly the thing the chart replaces.
+ */
+
+interface BalanceReading {
+    /** The lowest balance over the window, and the day it happens. Null when there is nothing to read. */
+    lowest: number | null;
+    lowestDay: string | null;
+    /** The first day the balance is below the threshold, or null when it never is. */
+    firstBelowDay: string | null;
+    /** How many days sit below the threshold. Zero is the answer somebody is hoping for. */
+    daysBelow: number;
+    /** The balance on the last day of the window. */
+    closing: number | null;
+}
+/**
+ * The reading, against a threshold.
+ *
+ * The threshold is not always zero, and that is the point of it being a parameter: a business that must
+ * keep fifty million on hand is in trouble well before it reaches nothing, and a chart drawn against
+ * zero would tell it everything is fine right up to the day it is not.
+ *
+ * "Below" is strict. A balance sitting exactly on the threshold has met it, and reporting that as a
+ * breach would cry wolf on the one day the business did precisely what it planned to.
+ */
+declare function balanceReading(points: readonly SeriesPoint[], threshold: number): BalanceReading;
+
+/** One reading: a day, and the share of the work complete by then. */
+interface CurvePoint {
+    /** `YYYY-MM-DD`. A calendar day, not an instant — progress is reported for a day's work. */
+    day: string;
+    /** 0–100. */
+    percent: number;
+}
+interface CurveReading {
+    plannedPercent: number | null;
+    actualPercent: number | null;
+    /** Actual minus planned, in points. Negative is behind. Null when either side is unknown. */
+    gap: number | null;
+}
+/** The library's generic point shape, from this Block's `percent`-named one. */
+declare function toPoints(points: readonly CurvePoint[]): SeriesPoint[];
+/**
+ * The reading on a given day: what was planned, what was reached, and the gap.
+ *
+ * Both sides carry the last report forward — a day nobody reported is not a day of no progress, and
+ * drawing it as zero would say the work went backwards. A plan states its shape at the points it
+ * states them, so it is read the same way.
+ */
+declare function readingOn(planned: readonly CurvePoint[], actual: readonly CurvePoint[], day: string): CurveReading;
+/** Every day either series reports, with both values and the gap — what a screen reader is given. */
+declare function curveRows(planned: readonly CurvePoint[], actual: readonly CurvePoint[]): {
+    day: string;
+    plannedPercent: number | null;
+    actualPercent: number | null;
+    gap: number | null;
+}[];
+
+interface ProgressCurveProps {
+    /** What the plan said would be complete, by day. */
+    planned: CurvePoint[];
+    /** What was actually reported complete, by day. */
+    actual: CurvePoint[];
+    /** Accessible name. It is the chart's title as a screen reader announces it, so name the job. */
+    label: string;
+    /**
+     * `YYYY-MM-DD`. The day the reading above the plot is taken on — both series carry their last value
+     * at or before it forward. Without it the reading is taken on the last day anything was reported.
+     *
+     * It is deliberately not drawn on the plot: a mark attaches to a data point, and today is usually not
+     * one. What is marked is the last report (see `lastReportLabel`).
+     */
+    today?: string;
+    height?: number;
+    plannedLabel?: string;
+    actualLabel?: string;
+    /** Text on the mark sitting at the last reported day. */
+    lastReportLabel?: string;
+    /** Shown in place of the chart when neither series has a single usable day. */
+    emptyLabel?: string;
+    /** The table a screen reader reads, and what a forced-colors viewer sees instead of the canvas. */
+    tableLabel?: string;
+    aheadLabel?: string;
+    behindLabel?: string;
+    onTrackLabel?: string;
+    loading?: boolean;
+    className?: string;
+}
+interface ProgressCurveSkeletonProps {
+    height?: number;
+    label?: string;
+    className?: string;
+}
+
+/** Holds the chart's geometry while the readings load, so the page does not jump when they land. */
+declare function ProgressCurveSkeleton({ height, label, className, }: ProgressCurveSkeletonProps): react.JSX.Element;
+
+/**
+ * An S-curve: what the plan said would be done by each day, against what was.
+ *
+ * The canvas, the Token reading, the forced-colors path and the accessible table all belong to
+ * `TimeSeriesChart`. What is here is the part that is about *progress*: a scale pinned to 0–100%,
+ * because autoscale stretches a job at 30% to the full height of the plot and reads as "nearly
+ * there"; and the reading in words above it, which is the one number somebody opened this to find.
+ */
+declare function ProgressCurveRoot({ planned, actual, label, today, height, plannedLabel, actualLabel, lastReportLabel, emptyLabel, tableLabel, aheadLabel, behindLabel, onTrackLabel, loading, className, }: ProgressCurveProps): react.JSX.Element;
+/** The Composition and its Skeleton, so a loading page keeps the chart's geometry. */
+declare const ProgressCurve: typeof ProgressCurveRoot & {
+    Skeleton: typeof ProgressCurveSkeleton;
+};
+
 interface DiagramSkeletonProps {
     label?: string;
 }
@@ -467,4 +913,4 @@ declare const DiagramEditor: typeof DiagramEditorRoot & {
     Skeleton: typeof DiagramSkeleton;
 };
 
-export { type CeebeeAntStyleCache, CeebeeAntStyleProvider, type CeebeeAntStyleProviderProps, Checklist, type ChecklistProps, type ChecklistTask, type Command, CommandPalette, type CommandPaletteProps, DEFAULT_LABELS, Diagram, type DiagramEdge, DiagramEditor, type DiagramEditorProps, type DiagramNode, type DiagramPosition, type DiagramProps, type DiagramRemoval, type DiagramRenameTarget, type DiagramShape, type DiagramSkeletonProps, type DurationToken, type Labels, LabelsProvider, type LabelsProviderProps, Modal, type ModalProps, type MotionHelpers, MotionProvider, type MotionProviderProps, type MotionSettings, type NavItem, type NavSection, type PaletteCommand, PanZoomCanvas, type PanZoomCanvasProps, type PanZoomCanvasSkeletonProps, type RankedCommand, Reveal, type RevealProps, Sidebar, type SidebarProps, type SpringPreset, Stagger, type StaggerProps, StickerGroup, type StickerGroupProps, type StickerGroupSkeletonProps, type StickerItem, ThemeBridge, type ThemeBridgeProps, type ThemeChoice, ThemeProvider, type ThemeProviderProps, type ToastOptions, type ToastPosition, ToastProvider, type ToastProviderProps, TopBar, type TopBarProps, createCeebeeAntStyleCache, extractCeebeeAntStyles, filterCommands, groupCommands, rankCommand, useLabels, useMotionSettings, useTheme, useToast };
+export { BalanceCurve, type BalanceCurveProps, BalanceCurveSkeleton, type BalanceCurveSkeletonProps, type BalanceReading, type Baseline, Board, type BoardCard, type BoardColumn, type BoardLabels, type BoardMove, type BoardMoveResult, type BoardPosition, type BoardProps, type BoardShape, type BoardSkeletonProps, type CeebeeAntStyleCache, CeebeeAntStyleProvider, type CeebeeAntStyleProviderProps, type ChartPalette, Checklist, type ChecklistProps, type ChecklistTask, type Command, CommandPalette, type CommandPaletteProps, type CurvePoint, type CurveReading, DEFAULT_LABELS, Diagram, type DiagramEdge, DiagramEditor, type DiagramEditorProps, type DiagramNode, type DiagramPosition, type DiagramProps, type DiagramRemoval, type DiagramRenameTarget, type DiagramShape, type DiagramSkeletonProps, type DurationToken, type Labels, LabelsProvider, type LabelsProviderProps, Modal, type ModalProps, type MotionHelpers, MotionProvider, type MotionProviderProps, type MotionSettings, type NavItem, type NavSection, type PaletteCommand, PanZoomCanvas, type PanZoomCanvasProps, type PanZoomCanvasSkeletonProps, ProgressCurve, type ProgressCurveProps, ProgressCurveSkeleton, type ProgressCurveSkeletonProps, type RankedCommand, Reveal, type RevealProps, type SeriesEmphasis, type SeriesPoint, type SeriesSpec, Sidebar, type SidebarProps, type SpringPreset, Stagger, type StaggerProps, StickerGroup, type StickerGroupProps, type StickerGroupSkeletonProps, type StickerItem, ThemeBridge, type ThemeBridgeProps, type ThemeChoice, ThemeProvider, type ThemeProviderProps, TimeSeriesChart, type TimeSeriesChartProps, TimeSeriesChartSkeleton, type TimeSeriesChartSkeletonProps, type ToastOptions, type ToastPosition, ToastProvider, type ToastProviderProps, TopBar, type TopBarProps, type ValueRange, alignRows, asDay, balanceReading, createCeebeeAntStyleCache, curveRows, extractCeebeeAntStyles, filterCommands, groupCommands, nearestDay, rankCommand, readingOn, round1, seriesPoints, seriesSpan, toPoints, useLabels, useMotionSettings, useTheme, useToast, valueOn };