@k2b/ui 0.48.0 → 0.50.0

package/dist/types/content/chart-snapshot.d.ts

@@ -1,26 +1 @@
-import { type ChartDatum } from "@k2b/stdlib";
-import { type ChartKind, type ChartRenderOptions } from "./Chart";
-import { type ChartSelection, type ChartTooltip, type ChartTooltipFormatter } from "./chart-inspection-core";
-/** Trusted output of prepareChartSnapshot; never accept arbitrary user SVG. */
-export type ChartSnapshot = {
-    kind: ChartKind;
-    svg: string;
-    width: number;
-    height: number;
-    stretch: boolean;
-    marks: readonly {
-        key: string;
-        rowKey: string;
-        datum: ChartDatum;
-        tooltip: ChartTooltip;
-        reference?: boolean;
-    }[];
-};
-/** Pure SVG preparation for server or browser. Transfer only this output across SSR boundaries. */
-export declare function prepareChartSnapshot(options: ChartRenderOptions, inspection: {
-    key: (selection: ChartSelection) => string;
-    /** Defaults to the mark key for one-to-one charts. */
-    rowKey?: (selection: ChartSelection) => string;
-    tooltip: ChartTooltipFormatter;
-    reference?: (selection: ChartSelection) => boolean;
-}): ChartSnapshot;
+export { type ChartSnapshot, prepareChartSnapshot } from "../charts/core/snapshot";

package/dist/types/content/chart-svg.d.ts

@@ -1,4 +1,4 @@
-import type { MapViewport } from "@k2b/stdlib";
+import type { MapViewport } from "../charts/core/svg";
 /** Give maps a CSS-sized viewport while retaining the renderer's projection.
  * The outer SVG uses pixels for headers/legend; the nested geographic viewport
  * keeps one fitted scale across zoom levels and clips only at the plot edges.

package/dist/types/content/chart-time-axis.d.ts

@@ -0,0 +1,26 @@
+/**
+ * A line chart whose X values are instants (Unix milliseconds). Its axis ticks land on round times in `timeZone`:
+ * minutes, hours, days, weeks, months, or years, whichever step keeps the requested number of ticks.
+ */
+export type ChartTimeAxis = {
+    /** IANA zone whose wall clock the ticks follow, such as the zone the data's buckets use. */
+    timeZone: string;
+    /** Locale of the default tick labels; `xAxis.format` replaces them. Defaults to `en`. */
+    locale?: string;
+};
+export type ChartTimeUnit = "minute" | "hour" | "day" | "week" | "month" | "year";
+export type ChartTimeStep = {
+    unit: ChartTimeUnit;
+    size: number;
+};
+/** The round step for a time span: the finest one that keeps at most `maxTicks` ticks. */
+export declare const chartTimeStep: (span: number, maxTicks: number) => ChartTimeStep;
+/** Tick instants inside `domain` that fall on round wall times of `step` in `timeZone`. */
+export declare const chartTimeTicks: (domain: readonly [number, number], timeZone: string, step: ChartTimeStep) => number[];
+/** Default label of a tick: the clock time, the day at local midnight, the month or the year. */
+export declare const chartTimeLabel: (tick: number, step: ChartTimeStep, axis: ChartTimeAxis) => string;
+/**
+ * Replaces the renderer's X tick labels, which sit on decimal millisecond steps, with labels on round times. The
+ * renderer drew the X axis over the explicit `domain`, so its horizontal axis line gives the pixel scale.
+ */
+export declare function timeAxisSvg(svg: string, domain: readonly [number, number], axis: ChartTimeAxis, maxTicks: number, format?: (value: number) => string): string;

package/dist/types/content/data-table-columns.d.ts

@@ -0,0 +1,72 @@
+import type { StatusTone } from "../surfaces/StatusBadge";
+/**
+ * What a column holds. It decides alignment, wrapping, the shown text, search and sort:
+ * text wraps; number, amount, bar, flow and delta read right-aligned with equal-width digits; date reads in the
+ * reader's language; status shows a badge from `states`.
+ */
+export type DataTableColumnType = "text" | "number" | "date" | "status" | "bar" | "amount" | "flow" | "delta";
+/** A number format by name, as a portable description stores it. `decimals` fixes the fraction digits. */
+export type DataTableNumberFormat = {
+    style?: "number" | "percent" | "currency";
+    /** ISO 4217 code; required for `style: "currency"`, `amount` and `flow`. */
+    currency?: string;
+    decimals?: number;
+    compact?: boolean;
+};
+/** The label and tone of one stored status value. */
+export type DataTableStatusState = {
+    label: string;
+    tone: StatusTone;
+};
+/** The typed part of a column, independent of how the row stores its values. */
+export type DataTableTypedColumn = {
+    type?: DataTableColumnType;
+    format?: DataTableNumberFormat;
+    /** Labels and tones of a status column, by stored value. */
+    states?: Readonly<Record<string, DataTableStatusState>>;
+    /** The value a bar column fills its track at; defaults to the largest value in the rows. */
+    max?: number;
+    /** The IANA zone a date column with a time reads in, such as the zone of the data's owner; defaults to the reader's. */
+    timeZone?: string;
+    /** How a delta column reads its change: `ratio` (default) `0.082` as `+8.2 %`, `points` `0.031` as `+3.1 pts`; `better` rates it. */
+    delta?: {
+        unit?: "ratio" | "points";
+        better?: "up" | "down";
+    };
+};
+export declare const isNumericColumnType: (type?: DataTableColumnType) => boolean;
+/** Formats a number the way a typed column shows it: in the reader's language, by the column's format. */
+export declare const formatTableNumber: (value: number, column: DataTableTypedColumn, locale: string) => string;
+/** A date column reads ISO text, a timestamp or a Date; a day without a time stays that day in every zone. */
+export declare const formatTableDate: (value: unknown, locale: string, timeZone?: string) => string | null;
+/** True when the value is missing: such a cell shows a dash, sorts last and never counts as zero. */
+export declare const isEmptyCell: (value: unknown) => boolean;
+/**
+ * The text a typed cell shows, for search, grouping and copied rows. A flow is the amount without its sign, as the
+ * arrow says the direction; a delta is its signed change.
+ */
+export declare const tableCellText: (value: unknown, column: DataTableTypedColumn, locale: string) => string;
+/** The value a typed column sorts by: numbers by value, dates by time, a status by its label, the rest as text. */
+export declare const tableSortValue: (value: unknown, column: DataTableTypedColumn, locale: string) => number | string | null;
+type Readable<T> = DataTableTypedColumn & {
+    id: string;
+    value?: keyof T | ((row: T) => unknown);
+};
+export declare const readTableValue: <T>(row: T, column: Readable<T>) => unknown;
+/**
+ * The rows any of whose shown values contains the query, ignoring case and accents. An empty query keeps every row.
+ * Matches the text a reader sees, so a status matches by its label and an amount as it is formatted.
+ */
+export declare const filterRows: <T>(rows: readonly T[], columns: readonly Readable<T>[], query: string, locale: string) => T[];
+/** Rows in the order of one column: values first, missing values last in both directions. */
+export declare const sortRows: <T>(rows: readonly T[], columns: readonly Readable<T>[], sort: {
+    key: string;
+    direction: "asc" | "desc";
+} | null | undefined, locale: string) => T[];
+/** Rows split by one column, in the order each group first appears; the label is the group's shown value. */
+export declare const groupRows: <T>(rows: readonly T[], column: Readable<T>, locale: string) => {
+    key: string;
+    label: string;
+    rows: T[];
+}[];
+export {};

package/dist/types/content/data-table-messages.d.ts

@@ -3,6 +3,24 @@ declare const dataTableMessages: import("@k2b/stdlib").Catalog<{
     noColumns: string;
     noRecords: string;
     loadingRows: string;
+    noMatch: ({ query }: {
+        query: string;
+    }) => string;
+    clearSearch: string;
+    details: string;
+    showDetails: string;
+    rowCount: ({ count }: {
+        count: number;
+    }) => string;
+    search: string;
+    searchTable: ({ label }: {
+        label: string;
+    }) => string;
+    groupRows: string;
+    notGrouped: string;
+    groupedBy: ({ label }: {
+        label: string;
+    }) => string;
 }>;
 export type DataTableMessages = ReturnType<(typeof dataTableMessages)["resolve"]>["t"];
 /** Resolved from the inherited render locale. */

package/dist/types/content/flow-amount-messages.d.ts

@@ -0,0 +1,11 @@
+declare const flowAmountMessages: import("@k2b/stdlib").Catalog<{
+    in: string;
+    out: string;
+    none: string;
+    invalid: string;
+}>;
+export type FlowAmountMessages = ReturnType<(typeof flowAmountMessages)["resolve"]>["t"];
+/** Resolved from an explicit locale override, else the inherited render locale. */
+export declare const useFlowAmountMessages: (override?: () => string | undefined) => (() => FlowAmountMessages);
+export declare const checkFlowAmountMessages: () => import("@k2b/stdlib").CatalogIssue[];
+export {};

package/dist/types/content/index.d.ts

@@ -1,8 +1,10 @@
+export type { ChartDateFormat, ChartDatum, ChartDatumRole, ChartFormat, ChartNumberFormat } from "../charts/core";
+export { BalanceSummary, type BalanceSummaryProps } from "./BalanceSummary";
 export type { CalendarAttendee, CalendarCommand, CalendarController, CalendarCustomView, CalendarDayBadge, CalendarEvent, CalendarEventColor, CalendarEventLink, CalendarEventRenderContext, CalendarEventTimeChange, CalendarExternalDrag, CalendarLabels, CalendarProps, CalendarQuickCreateControls, CalendarRange, CalendarRecurrence, CalendarResource, CalendarSelectionControls, CalendarView, } from "./Calendar";
 export { default as Calendar } from "./Calendar";
-export type { ChartKind, ChartLabels, ChartProps, ChartRenderOptions } from "./Chart";
+export type { ChartKind, ChartKindProps, ChartLabels, ChartProps, ChartRenderOptions } from "./Chart";
 export { default as Chart } from "./Chart";
-export type { ChartExplorerColumn, ChartExplorerProps, ChartLegendEntry } from "./ChartExplorer";
+export type { ChartExplorerColumn, ChartExplorerProps, ChartFrameRequest, ChartLegendEntry } from "./ChartExplorer";
 export { ChartExplorer } from "./ChartExplorer";
 export type { ChartExplorerControlsProps } from "./ChartExplorerControls";
 export { ChartExplorerControls } from "./ChartExplorerControls";
@@ -17,17 +19,23 @@ export type { ChartDatumRef, ChartSelection, ChartTooltip, ChartTooltipFormatter
 export type { ChartSnapshot } from "./chart-snapshot";
 export { prepareChartSnapshot } from "./chart-snapshot";
 export type { StateTimelineChartOptions, StateTimelineDomain, StateTimelineInterval, StateTimelineRow, StateTimelineState, } from "./chart-state-timeline";
+export type { ChartTimeAxis } from "./chart-time-axis";
 export { highlightSql } from "./code-highlight";
 export { type CollectionSelection, createCollectionSelection, type SelectionModifiers } from "./collection-selection";
 export type { DataTableColumn, DataTableControlsProps, DataTableFooter, DataTableHeaderProps, DataTablePanelFooterProps, DataTablePanelProps, DataTableProps, DataTableRenderCell, DataTableRenderHeader, DataTableSort, } from "./DataTable";
 export { default as DataTable } from "./DataTable";
+export type { DataTableToolsProps, DataTableView, DataTableViewOptions } from "./DataTableTools";
+export { createDataTableView, DataTableTools } from "./DataTableTools";
 export type { DocCodeHighlighter, DocCodeProps, DocConcept, DocNoteVariant, DocRow } from "./Docs";
 export { DocCode, DocConceptGrid, DocInlineCode, DocLead, DocNote, DocPage, DocRows, DocSection } from "./Docs";
+export type { DataTableColumnType, DataTableNumberFormat, DataTableStatusState, DataTableTypedColumn, } from "./data-table-columns";
+export { filterRows, sortRows } from "./data-table-columns";
 export { FileBrowserPanel, type FileBrowserPanelProps, type FileSource, openFileBrowser } from "./FileBrowser";
 export { FileGrid, type FileGridGroup, type FileGridOpenProps, type FileGridProps, type FileGridSelectableProps } from "./FileGrid";
 export { default as FileTree, type FileTreeActions, type FileTreeEntry, type FileTreeProps } from "./FileTree";
 export { type FileType, FileTypeIcon, type FileTypeIconProps, fileKindLabel, fileTypeOf } from "./FileTypeIcon";
 export { canPreviewFile, default as FileView, type FileViewContent, type FileViewFile, type FileViewPreviewKind, type FileViewProps, type FileViewRenderer, type FileViewRendererProps, formatFileViewSize, getFileViewPreviewKind, } from "./FileView";
+export { FlowAmount, type FlowAmountDirection, type FlowAmountProps, flowDirection } from "./FlowAmount";
 export type { KbdProps } from "./Kbd";
 export { Kbd } from "./Kbd";
 export type { LabelChipProps } from "./LabelChip";

package/dist/types/feedback/prompt-confirm.d.ts

@@ -2,8 +2,10 @@ import { type JSX } from "solid-js";
 import { type DialogTone } from "./dialog-tone";
 import type { ConfirmOptions, DialogOptions } from "./prompts";
 export type PromptContent = string | HTMLElement | JSX.Element;
-/** A prompt's `variant` is its tone too: a success or danger prompt carries the dialog tone of that name. */
+/** A prompt's `variant` is its tone too: a success, warning or danger prompt carries the dialog tone of that name. */
 export declare const promptTone: (variant: DialogOptions["variant"]) => DialogTone | undefined;
+/** A warning asks for care, not for a destructive act: its confirm button stays primary. */
+export declare const promptButtonVariant: (variant: DialogOptions["variant"]) => "danger" | "primary" | "success";
 export declare const DialogHeader: (props: {
     close: () => void;
     title?: string;

package/dist/types/feedback/prompts.d.ts

@@ -9,7 +9,7 @@ export interface DialogOptions {
     icon?: string;
     confirmText?: string;
     cancelText?: string | false;
-    variant?: "danger" | "primary" | "success";
+    variant?: "danger" | "primary" | "success" | "warning";
     /** `full` fills the available viewport and becomes edge-to-edge on narrow screens. */
     size?: "small" | "medium" | "large" | "wide" | "full";
     surface?: "default" | "bare";
@@ -143,7 +143,7 @@ type PromptFormOptions<T extends Record<string, FieldSchema>> = {
     fields: T;
     confirmText?: string;
     cancelText?: string | false;
-    variant?: "danger" | "primary" | "success";
+    variant?: "danger" | "primary" | "success" | "warning";
     size?: DialogOptions["size"];
     cancelBehavior?: DialogOptions["cancelBehavior"];
 };

package/dist/types/inputs/NumberInput.d.ts

@@ -6,7 +6,7 @@ export type NumberInputProps = Omit<JSX.InputHTMLAttributes<HTMLInputElement>, "
     min?: number;
     /** Stepper increment and commit grid; defaults to `1`. A fractional step also sets the default `decimalPlaces`. */
     step?: number;
-    /** Accepted fraction digits. Defaults to the fraction digits of `step` (`0.01` → `2`, `1` → `0`); an explicit value wins. */
+    /** Accepted and displayed fraction digits. Defaults to the fraction digits of `step` (`0.01` → `2`, `1` → `0`); an explicit value wins. */
     decimalPlaces?: number;
     allowNegative?: boolean;
     clearable?: boolean;

package/dist/types/inputs/SelectChip.d.ts

@@ -27,6 +27,8 @@ export type SelectChipProps<T extends string | number = string> = ValueFieldProp
     loading?: boolean;
     open?: boolean;
     onOpenChange?: (open: boolean) => void;
+    /** Keeps the width of the longest option label, so a new choice never moves what sits beside the chip. */
+    stableWidth?: boolean;
 };
 export declare function SelectChip<T extends string | number = string>(props: SelectChipProps<T>): JSX.Element;
 export default SelectChip;

package/dist/types/inputs/date-picker.d.ts

@@ -42,6 +42,12 @@ export declare const splitDateTime: (value: string | null | undefined, context?:
 };
 export declare const isCompleteTime: (value: string) => boolean;
 export declare const toDateTimeValue: (date: string, time: string, context?: DateContext) => string | null;
+/**
+ * The value an applied draft commits. An untouched draft keeps the exact value: the panel shows minutes in the
+ * picker's zone, and a wall time that a daylight-saving change repeats names two instants, so rebuilding it could
+ * move the value by an hour or drop its seconds.
+ */
+export declare const draftDateTimeValue: (value: string | null | undefined, date: string, time: string, context?: DateContext) => string | null;
 export declare const formatDateTimeValue: (value: string | null | undefined, context?: DateContext) => string;
 export declare const normalizeTimeInput: (value: string) => string;
 export declare const filterTimeInput: (value: string) => string;

package/dist/types/intl/Format.d.ts

@@ -31,6 +31,11 @@ export type FormatCurrencyProps = SpanProps & LocaleProp & FallbackProp & {
     currency: string;
     /** Fixed fraction digits. Defaults to the currency's standard digits. */
     decimals?: number;
+    /**
+     * When the sign shows, as in `Intl.NumberFormat`: `"exceptZero"` writes `+1.234,50 €` and `-80,00 €` for a
+     * balance change or net amount, `"never"` drops it. Defaults to `"auto"` (only negative amounts carry a sign).
+     */
+    signDisplay?: Intl.NumberFormatOptions["signDisplay"];
 };
 export type FormatBytesProps = SpanProps & LocaleProp & FallbackProp & {
     value: number | null | undefined;

package/dist/types/layout/AppWorkspace.d.ts

@@ -2,6 +2,7 @@ import { type AppWorkspaceSidebarItemStatusProps } from "./AppWorkspaceSidebarIt
 export type { AppWorkspaceSidebarItemStatusProps } from "./AppWorkspaceSidebarItemStatus";
 import { type LinkNavigateEvent, type NavigationScrollMode } from "@k2b/ssr/nav";
 import { type JSX } from "solid-js";
+import { type DropdownItem, type DropdownSearch } from "../actions/Dropdown";
 import { type AppWorkspaceLayoutState } from "./app-workspace-state";
 import { type AppWorkspaceWidthShare } from "./app-workspace-width";
 import type { ScrollAreaProps } from "./ScrollArea";
@@ -118,6 +119,12 @@ export type AppWorkspaceMainPaneProps = {
     };
     /** Controls at the end of the level head. */
     actions?: JSX.Element;
+    /**
+     * Levels mode: the title opens a menu of places to switch to, such as the person's work and each Space; on a phone
+     * it opens as a sheet. The title stays the level's heading and gains a chevron; the server HTML already says that
+     * it opens a menu.
+     */
+    switcher?: AppWorkspaceLevelSwitcher;
     /**
      * Levels mode: `"page"` marks the level that holds the page itself, such as a settings form or the list of an
      * area, rather than a column that leads there or a detail beside it. Its title takes the page step of the type
@@ -141,6 +148,13 @@ export type AppWorkspaceMainPaneProps = {
     scrollFade?: boolean;
     children: JSX.Element;
 };
+/** The places a level title switches between; `label` names the menu, such as "Switch Space". */
+export type AppWorkspaceLevelSwitcher = {
+    label: string;
+    items: readonly DropdownItem[];
+    /** A search field above the places, for a long list. */
+    search?: DropdownSearch;
+};
 export type AppWorkspaceDetailWidth = "sm" | "md" | "lg" | "xl";
 export type AppWorkspaceDetailProps = {
     children: JSX.Element;
@@ -292,10 +306,16 @@ export type AppWorkspaceSidebarItemProps = {
     scroll?: NavigationScrollMode;
     onNavigate?: (event: LinkNavigateEvent) => void | Promise<void>;
     onClick?: (event: MouseEvent) => void;
+    /**
+     * Makes a row without `href` a disclosure: it shows or hides the rows after
+     * it, and assistive technology hears whether they are shown.
+     */
+    expanded?: boolean;
     /**
      * Marks the current page (`aria-current="page"`). On a page deeper than the
      * sidebar lists, pass `"ancestor"` for the item that contains it: it keeps
-     * the highlight, and the page keeps its back link.
+     * the highlight and, while the sidebar shows, is the way up, so the head
+     * drops its back link as beside the current page.
      */
     active?: boolean | "ancestor";
     activeClass?: string;

package/dist/types/layout/MobileShell.d.ts

@@ -43,6 +43,11 @@ export type MobileShellHeaderProps = {
     /** Controls after the title, such as a menu. */
     actions?: JSX.Element;
 };
+/**
+ * The height the on-screen keyboard covers at the bottom of the layout viewport, from the visual viewport; zero
+ * without a keyboard or without `visualViewport`.
+ */
+export declare const keyboardInset: (view: Pick<Window, "innerHeight" | "visualViewport">) => number;
 /**
  * Marks the shell around `from` as showing a screen of its own, or not, after the first paint; the server renders
  * the first state with the `screen` prop. Does nothing outside a shell.

package/dist/types/layout/index.d.ts

@@ -1,7 +1,7 @@
 export { AnchoredPopover, type AnchoredPopoverProps } from "./AnchoredPopover";
 export type { AppOverviewCardsProps, AppOverviewEmptyStateProps, AppOverviewPanelProps, AppOverviewProps, } from "./AppOverview";
 export { default as AppOverview } from "./AppOverview";
-export type { AppWorkspaceBottomDrawerHeight, AppWorkspaceBottomDrawerProps, AppWorkspaceContentProps, AppWorkspaceDetailProps, AppWorkspaceDetailWidth, AppWorkspaceHeadProps, AppWorkspaceMainPaneProps, AppWorkspaceMainProps, AppWorkspaceNavTreeItemProps, AppWorkspaceNavTreeMove, AppWorkspaceNavTreeProps, AppWorkspaceProps, AppWorkspaceSidebarAccessoryVisibility, AppWorkspaceSidebarBodyProps, AppWorkspaceSidebarIconActionProps, AppWorkspaceSidebarIconActionTone, AppWorkspaceSidebarIconGridProps, AppWorkspaceSidebarItemActionProps, AppWorkspaceSidebarItemActionsProps, AppWorkspaceSidebarItemIconProps, AppWorkspaceSidebarItemLabelProps, AppWorkspaceSidebarItemMetaProps, AppWorkspaceSidebarItemProps, AppWorkspaceSidebarItemStatusProps, AppWorkspaceSidebarItemTone, AppWorkspaceSidebarProps, AppWorkspaceSidebarSectionProps, AppWorkspaceSidebarVisibility, AppWorkspaceWidthShare, } from "./AppWorkspace";
+export type { AppWorkspaceBottomDrawerHeight, AppWorkspaceBottomDrawerProps, AppWorkspaceContentProps, AppWorkspaceDetailProps, AppWorkspaceDetailWidth, AppWorkspaceHeadProps, AppWorkspaceLevelSwitcher, AppWorkspaceMainPaneProps, AppWorkspaceMainProps, AppWorkspaceNavTreeItemProps, AppWorkspaceNavTreeMove, AppWorkspaceNavTreeProps, AppWorkspaceProps, AppWorkspaceSidebarAccessoryVisibility, AppWorkspaceSidebarBodyProps, AppWorkspaceSidebarIconActionProps, AppWorkspaceSidebarIconActionTone, AppWorkspaceSidebarIconGridProps, AppWorkspaceSidebarItemActionProps, AppWorkspaceSidebarItemActionsProps, AppWorkspaceSidebarItemIconProps, AppWorkspaceSidebarItemLabelProps, AppWorkspaceSidebarItemMetaProps, AppWorkspaceSidebarItemProps, AppWorkspaceSidebarItemStatusProps, AppWorkspaceSidebarItemTone, AppWorkspaceSidebarProps, AppWorkspaceSidebarSectionProps, AppWorkspaceSidebarVisibility, AppWorkspaceWidthShare, } from "./AppWorkspace";
 export { appWorkspaceDetailElementId, default as AppWorkspace } from "./AppWorkspace";
 export { AppWorkspaceSidebarItemStatus } from "./AppWorkspaceSidebarItemStatus";
 export { watchAppHostWidth } from "./app-host-width";
@@ -50,6 +50,7 @@ export type { SettingsModalFooterProps, SettingsModalGroupProps, SettingsModalPr
 export { default as SettingsModal } from "./SettingsModal";
 export { APP_WORKSPACE_SWITCHER_SEARCH_FROM, type AppWorkspaceSidebarSwitcherProps, type AppWorkspaceSwitcherAction, type AppWorkspaceSwitcherOption, } from "./SidebarSwitcher";
 export { measureScrollFade } from "./scroll-fade";
+export { attachSheetHandle, type SheetHandleOptions } from "./sheet-handle";
 export type { TabBarItem, TabBarProps } from "./TabBar";
 export { default as TabBar } from "./TabBar";
 export type { TableOfContentsItem, TableOfContentsProps } from "./TableOfContents";

package/dist/types/layout/sheet-handle.d.ts

@@ -0,0 +1,21 @@
+export type SheetHandleOptions = {
+    /** The sheet the handle sits on. It carries the current detent in `data-sheet-detent`. */
+    sheet: HTMLElement;
+    /** The detents' names, lowest first. The stylesheet gives each `[data-sheet-detent="…"]` its height. */
+    detents: readonly string[];
+    /** The detent the stylesheet draws while the sheet has no `data-sheet-detent`, such as in the server's markup. */
+    initial: string;
+    /** After a drag or a press moved the sheet to another detent, for example to rename the handle. */
+    onChange?: (detent: string) => void;
+    /** Without it, a drag stops at the lowest detent; with it, a drag well below that detent asks to close. */
+    onDismiss?: () => void;
+};
+/**
+ * Lets a sheet's handle drag it between detents. The handle stays a button: a press, by pointer, Enter or Space,
+ * moves the sheet to the next detent up, and from the highest back to the lowest. A drag follows the pointer with an
+ * inline height and, on release, snaps to the detent nearest to where the pointer's speed would carry it. The snap
+ * animates with the sheet's own height transition, so reduced motion makes it instant. The stylesheet owns every
+ * resting height, which keeps the server's first frame and a rotation correct without script; the handle measures
+ * them when a drag starts.
+ */
+export declare function attachSheetHandle(handle: HTMLElement, options: SheetHandleOptions): () => void;

package/dist/types/surfaces/BudgetList.d.ts

@@ -0,0 +1,42 @@
+import { type JSX } from "solid-js";
+/** One budget: `used` is booked, `expected` comes on top; over the budget is `used + expected - limit`. */
+export type BudgetItem = {
+    id?: string;
+    label: string;
+    used: number;
+    expected?: number;
+    limit: number;
+};
+export type BudgetListProps = {
+    items: readonly BudgetItem[];
+    /** ISO 4217 currency code, e.g. `"EUR"`. */
+    currency: string;
+    /** Explicit locale override; defaults to the inherited render locale. */
+    locale?: string;
+    /** Fixed fraction digits. Defaults to 0. */
+    decimals?: number;
+    /** The sentence shown when there is no budget. */
+    empty?: string;
+    /** Hides the legend under the rows when the host explains the colours elsewhere. */
+    legend?: boolean;
+    class?: string;
+};
+/** "near" from 80 % of the budget, "over" beyond it. */
+export type BudgetLevel = "ok" | "near" | "over";
+/** The figures of one budget row; the share counts booked and expected together. */
+export declare const budgetState: (item: Pick<BudgetItem, "used" | "expected" | "limit">) => {
+    used: number;
+    expected: number;
+    limit: number;
+    total: number;
+    over: number;
+    free: number;
+    ratio: number;
+    level: BudgetLevel;
+};
+/**
+ * Budgets as rows: label and "spent of budget", a bar with booked (solid), expected (hatched) and over the budget
+ * (red, with a mark at the limit), and a hint that turns amber from 80 % and red beyond the budget.
+ */
+export declare function BudgetList(props: BudgetListProps): JSX.Element;
+export default BudgetList;

package/dist/types/surfaces/NoticeCard.d.ts

@@ -14,8 +14,11 @@ type NoticeCardContentProps = {
 };
 export type NoticeCardProps = Omit<JSX.HTMLAttributes<HTMLElement>, "children" | "class" | "title"> & NoticeCardContentProps & {
     tone?: NoticeTone;
-    /** A Tabler icon class. Turns the notice into a compact status line whose icon and text take the tone colour. */
-    icon?: string;
+    /**
+     * A Tabler icon class. Turns the notice into a compact status line whose icon and text take the tone colour. `true`
+     * takes the tone's own icon, the one a toned dialog shows, and names the tone for screen readers.
+     */
+    icon?: string | true;
     class?: string;
     bodyClass?: string;
 };

package/dist/types/surfaces/ProgressBar.d.ts

@@ -1,13 +1,49 @@
-import type { JSX } from "solid-js";
+import { type JSX } from "solid-js";
 import type { IntentTone } from "../semantics";
 export type ProgressBarTone = Extract<IntentTone, "info" | "success" | "warning" | "danger">;
-export type ProgressBarProps = {
+/** One part of a segmented bar, in the unit of `limit`. `"hatched"` marks an expected, not yet booked part. */
+export type ProgressBarSegment = {
     value: number;
+    pattern?: "solid" | "hatched";
+};
+export type ProgressBarProps = {
+    /** Percent from 0 to 100. With `segments`, the share of `limit` the segments fill. */
+    value?: number;
     size?: "xs" | "sm" | "md";
     tone?: ProgressBarTone;
     showValue?: boolean;
     label: string;
+    /** Parts drawn in order, such as booked and expected spending. Negative and non-finite values count as 0. */
+    segments?: readonly ProgressBarSegment[];
+    /** The budget the segments fill. What goes beyond it is drawn red, with a mark at the limit. */
+    limit?: number;
+    /** Spoken value, such as "1,240 € of 1,500 €"; defaults to the percent. */
+    valueText?: string;
     class?: string;
 };
+export type ProgressBarPart = {
+    pattern: "solid" | "hatched" | "over";
+    width: number;
+};
+/**
+ * Sum minus limit, without float residue: `0.1 + 0.2` against `0.3` is not over. Amounts within a billionth of the
+ * larger of both count as equal.
+ */
+export declare const budgetOverrun: (total: number, limit: number) => number;
+/** Sum over limit; an empty budget with spending is infinitely full. */
+export declare const budgetRatio: (total: number, limit: number) => number;
+/**
+ * The drawn parts of a segmented bar, each as a percent of the track. The track spans the larger of the limit and the
+ * sum, so an overrun stays visible: segments fill up to the limit in order, the rest is one "over" part, and `mark`
+ * places the limit line (only when the sum goes beyond it). Without `limit` the segments fill the track; a limit of 0,
+ * below 0 or not finite is an empty budget, so any spending is over it.
+ */
+export declare const progressBarParts: (segments: readonly ProgressBarSegment[], limit?: number) => {
+    parts: ProgressBarPart[];
+    total: number;
+    over: number;
+    mark: number | null;
+    ratio: number;
+};
 export declare function ProgressBar(props: ProgressBarProps): JSX.Element;
 export default ProgressBar;

package/dist/types/surfaces/StatCell.d.ts

@@ -8,12 +8,35 @@ export type StatCellAccent = {
     icon: string;
     text?: string;
 };
+/**
+ * The change against a comparison period. `unit: "ratio"` (default) reads `0.082` as `+8.2 %`; `"points"` is the
+ * difference of two shares in ratio units, so `0.031` reads `+3.1 pts`. Only with `better` does the badge carry a tone
+ * and say "better" or "worse"; without it the change stays unrated.
+ */
+export type StatCellDelta = {
+    value: number;
+    unit?: "ratio" | "points";
+    better?: "up" | "down";
+};
+/** The value the change compares against, shown under the figure, such as "Last month 44,560". */
+export type StatCellCompare = {
+    label: string;
+    value: string | number;
+};
+export type StatCellSize = StatGridSize;
 export type StatCellProps = {
     label: string;
-    value: string | number | JSX.Element;
+    /** The figure. `null` shows the empty dash; `sub` then says why. */
+    value: string | number | JSX.Element | null;
     sub?: string;
     valueClass?: string;
+    /** An icon in a chip before the label, in `tone`. `"in"` and `"out"` are the money colours of `FlowAmount`. */
+    icon?: string;
+    /** The chip colour of `icon`. Defaults to zinc. */
+    tone?: StatCellTone | "in" | "out";
     accent?: StatCellAccent;
+    delta?: StatCellDelta;
+    compare?: StatCellCompare;
     href?: string;
     title?: string;
     trend?: readonly number[];
@@ -22,12 +45,22 @@ export type StatCellProps = {
      * `selection.datum.index` is the source index into `trend`.
      */
     trendTooltip?: ChartTooltipFormatter;
-    size?: StatGridSize;
+    size?: StatCellSize;
     /**
      * Wraps the label, value and support line instead of truncating them. Use it for a cell whose height nothing
      * reserves, such as one figure on its own; cells compared in a row keep one line each.
      */
     wrap?: boolean;
+    /** `"loading"` keeps the tile's size with placeholders; `"error"` says the figure did not load. */
+    status?: "loading" | "error";
+    /** Offers "Try again" after an error and "Reload" beside `stale`. */
+    onRetry?: () => void;
+    /** The figure is not current: a short note such as "As of 09:12 · not current" replaces the support line. */
+    stale?: string;
 };
+/**
+ * One key figure as a framed tile: icon and label, the figure with its change, and a support line with the comparison
+ * and the trend. Each state (loading, error, stale, empty) keeps the tile's place and size.
+ */
 export declare function StatCell(props: StatCellProps): JSX.Element;
 export default StatCell;

package/dist/types/surfaces/StatGrid.d.ts

@@ -1,5 +1,5 @@
 import { type JSX } from "solid-js";
-export type StatGridSize = "md" | "sm";
+export type StatGridSize = "lg" | "md" | "sm";
 export type StatGridSurface = "white" | "muted";
 export type StatGridColumns = 1 | 2 | 3 | 4 | 5 | 6;
 export type StatGridAction = {
@@ -10,6 +10,7 @@ export type StatGridProps = {
     children: JSX.Element;
     title?: string;
     action?: StatGridAction;
+    /** Tiles per row on a wide container. Defaults to 4; at 600 px or less two share a row, and five or six take three up to 900 px. */
     columns?: StatGridColumns;
     size?: StatGridSize;
     surface?: StatGridSurface;
@@ -17,5 +18,6 @@ export type StatGridProps = {
 };
 export declare const useStatGridSize: () => StatGridSize;
 export declare const useStatGridSurface: () => StatGridSurface;
+/** A row of key figures, each a framed tile of its own; the optional title and action sit above the row. */
 export declare function StatGrid(props: StatGridProps): JSX.Element;
 export default StatGrid;

package/dist/types/surfaces/budget-messages.d.ts

@@ -0,0 +1,30 @@
+declare const budgetMessages: import("@k2b/stdlib").Catalog<{
+    of: ({ limit }: {
+        limit: string;
+    }) => string;
+    free: ({ amount }: {
+        amount: string;
+    }) => string;
+    near: ({ amount }: {
+        amount: string;
+    }) => string;
+    over: ({ amount }: {
+        amount: string;
+    }) => string;
+    used: string;
+    expected: string;
+    overLegend: string;
+    budget: string;
+    left: string;
+    overBy: string;
+    valueText: ({ used, expected, limit }: {
+        used: string;
+        expected?: string;
+        limit: string;
+    }) => string;
+}>;
+export type BudgetMessages = ReturnType<(typeof budgetMessages)["resolve"]>["t"];
+/** Resolved from an explicit locale override, else the inherited render locale. */
+export declare const useBudgetMessages: (override?: () => string | undefined) => (() => BudgetMessages);
+export declare const checkBudgetMessages: () => import("@k2b/stdlib").CatalogIssue[];
+export {};

package/dist/types/surfaces/delta-badge.d.ts

@@ -0,0 +1,10 @@
+import type { JSX } from "solid-js";
+import type { StatCellCompare, StatCellDelta } from "./StatCell";
+import { type StatCellMessages } from "./stat-cell-messages";
+/** Signed with a true minus sign (U+2212), as figures are typeset. */
+export declare const deltaText: (delta: StatCellDelta, locale: string, t: StatCellMessages) => string;
+/** A change badge: arrow, signed text, and a spoken label that names the comparison and, with `better`, the rating. */
+export declare function DeltaBadge(props: {
+    delta: StatCellDelta;
+    compare?: StatCellCompare;
+}): JSX.Element;