@apotech-os/ui-sdk 1.0.0 → 2.0.0

package/dist/index.d.cts

@@ -1,5 +1,6 @@
 import { ClassValue } from 'clsx';
 import * as React from 'react';
+import { ReactNode } from 'react';
 import { AppErrorCode, AppRunRecord, AppRunStatus } from '@apotech-os/app-kit';
 export { AppRunRecord, AppRunStatus } from '@apotech-os/app-kit';
 import * as class_variance_authority_types from 'class-variance-authority/types';
@@ -159,7 +160,9 @@ declare function Badge({ className, variant, dot, children, ...props }: BadgePro
 declare function Card({ className, ...props }: React.HTMLAttributes<HTMLDivElement>): React.JSX.Element;
 declare function CardHeader({ className, ...props }: React.HTMLAttributes<HTMLDivElement>): React.JSX.Element;
 declare function CardTitle({ className, ...props }: React.HTMLAttributes<HTMLHeadingElement>): React.JSX.Element;
+declare function CardDescription({ className, ...props }: React.HTMLAttributes<HTMLParagraphElement>): React.JSX.Element;
 declare function CardContent({ className, ...props }: React.HTMLAttributes<HTMLDivElement>): React.JSX.Element;
+declare function CardFooter({ className, ...props }: React.HTMLAttributes<HTMLDivElement>): React.JSX.Element;
 declare const Input: React.ForwardRefExoticComponent<React.InputHTMLAttributes<HTMLInputElement> & React.RefAttributes<HTMLInputElement>>;
 declare function Table({ className, ...props }: React.HTMLAttributes<HTMLTableElement>): React.JSX.Element;
 declare function TableHeader({ className, ...props }: React.HTMLAttributes<HTMLTableSectionElement>): React.JSX.Element;
@@ -167,9 +170,34 @@ declare function TableBody({ className, ...props }: React.HTMLAttributes<HTMLTab
 declare function TableRow({ className, ...props }: React.HTMLAttributes<HTMLTableRowElement>): React.JSX.Element;
 declare function TableHead({ className, ...props }: React.ThHTMLAttributes<HTMLTableCellElement>): React.JSX.Element;
 declare function TableCell({ className, ...props }: React.TdHTMLAttributes<HTMLTableCellElement>): React.JSX.Element;
-interface SelectProps extends React.SelectHTMLAttributes<HTMLSelectElement> {
+interface SelectOption {
+    value: string;
+    label: React.ReactNode;
+    disabled?: boolean;
 }
-declare const Select: React.ForwardRefExoticComponent<SelectProps & React.RefAttributes<HTMLSelectElement>>;
+interface SelectProps {
+    /** Controlled value. Pair with `onValueChange`. */
+    value?: string;
+    defaultValue?: string;
+    onValueChange?: (value: string) => void;
+    items: SelectOption[];
+    /** Shown when nothing is chosen. */
+    placeholder?: React.ReactNode;
+    disabled?: boolean;
+    /** Submitted with a surrounding form, through a hidden native input. */
+    name?: string;
+    className?: string;
+    'aria-label'?: string;
+}
+/**
+ * Listbox select.
+ *
+ * Contract 2: this used to be a native `<select>` taking `<option>` children.
+ * The popup is ours now — themed, positioned and keyboard-driven like every
+ * other floating surface — which a native select cannot be. `items` replaces the
+ * children, and the ref is gone: there is no `HTMLSelectElement` behind it.
+ */
+declare function Select({ value, defaultValue, onValueChange, items, placeholder, disabled, name, className, ...props }: SelectProps): React.JSX.Element;
 interface TabsProps {
     defaultValue?: string;
     value?: string;
@@ -191,7 +219,7 @@ declare function TabsContent({ value, className, children, }: {
     value: string;
     className?: string;
     children: React.ReactNode;
-}): React.JSX.Element | null;
+}): React.JSX.Element;
 interface ModalProps {
     open: boolean;
     onClose: () => void;
@@ -199,7 +227,8 @@ interface ModalProps {
     children: React.ReactNode;
     className?: string;
 }
-declare function Modal({ open, onClose, title, children, className }: ModalProps): React.JSX.Element | null;
+/** Centred blocking dialog. Base UI owns the focus trap, focus restore and Escape. */
+declare function Modal({ open, onClose, title, children, className }: ModalProps): React.JSX.Element;
 interface SpinnerProps {
     className?: string;
     size?: 'sm' | 'md' | 'lg';
@@ -209,6 +238,10 @@ interface LinkProps extends React.AnchorHTMLAttributes<HTMLAnchorElement> {
     variant?: 'default' | 'muted';
 }
 declare const Link: React.ForwardRefExoticComponent<LinkProps & React.RefAttributes<HTMLAnchorElement>>;
+/**
+ * Do not pass `aria-label` when the switch sits inside a `<label>`: the label
+ * already names it, and the two naming sources cancel out into no name at all.
+ */
 interface SwitchProps {
     checked?: boolean;
     onCheckedChange?: (checked: boolean) => void;
@@ -217,27 +250,29 @@ interface SwitchProps {
     'aria-label'?: string;
 }
 declare function Switch({ checked, onCheckedChange, disabled, className, ...props }: SwitchProps): React.JSX.Element;
-interface DateRange {
-    from: string;
-    to: string;
-}
-interface DateRangePickerProps {
-    value: DateRange;
-    onChange: (range: DateRange) => void;
-    className?: string;
-    disabled?: boolean;
-}
-/** Minimal controlled date-range picker using two native date inputs. */
-declare function DateRangePicker({ value, onChange, className, disabled }: DateRangePickerProps): React.JSX.Element;
 type TextareaProps = React.TextareaHTMLAttributes<HTMLTextAreaElement>;
 declare const Textarea: React.ForwardRefExoticComponent<TextareaProps & React.RefAttributes<HTMLTextAreaElement>>;
-interface CheckboxProps extends Omit<React.InputHTMLAttributes<HTMLInputElement>, 'type' | 'onChange'> {
+interface CheckboxProps {
     checked?: boolean;
-    /** Preferred over onChange — receives the boolean directly. */
+    defaultChecked?: boolean;
+    /** Receives the boolean directly. */
     onCheckedChange?: (checked: boolean) => void;
+    disabled?: boolean;
     label?: React.ReactNode;
+    /** Submitted with a surrounding form, through a hidden native input. */
+    name?: string;
+    className?: string;
+    'aria-label'?: string;
 }
-declare const Checkbox: React.ForwardRefExoticComponent<CheckboxProps & React.RefAttributes<HTMLInputElement>>;
+/**
+ * Checkbox.
+ *
+ * Contract 2: this used to be a native `<input type="checkbox">` forwarding an
+ * `HTMLInputElement` ref and taking every input attribute. Base UI renders a
+ * button with the role and a hidden input for form submission, so neither could
+ * survive — `onChange` and the ref are gone, `onCheckedChange` is the way in.
+ */
+declare function Checkbox({ checked, defaultChecked, onCheckedChange, disabled, label, name, className, ...props }: CheckboxProps): React.JSX.Element;
 interface SidePanelProps {
     open: boolean;
     onClose: () => void;
@@ -254,9 +289,10 @@ interface SidePanelProps {
  * Children are laid out in a flex column filling the panel: put the scrollable
  * region in a `min-h-0 flex-1 overflow-y-auto` child and the footer after it.
  *
- * NOTE: no focus management. Autofocus the primary action yourself.
+ * Focus is trapped inside while open and restored to the opener on close — Base
+ * UI's dialog does both, which is what the hand-rolled version never did.
  */
-declare function SidePanel({ open, onClose, title, description, children, className, }: SidePanelProps): React.JSX.Element | null;
+declare function SidePanel({ open, onClose, title, description, children, className, }: SidePanelProps): React.JSX.Element;
 interface CopyButtonProps {
     value: string;
     label?: string;
@@ -294,9 +330,302 @@ interface DropdownMenuProps {
     align?: 'start' | 'end';
     className?: string;
 }
-/** Uncontrolled menu built on Popover. Selecting an item closes it. */
+/** Uncontrolled menu. Selecting an item closes it; arrow keys move between them. */
 declare function DropdownMenu({ trigger, items, align, className }: DropdownMenuProps): React.JSX.Element;
 
+interface DataTableColumn<Row> {
+    /** Stable identifier — also the key used for sorting and hiding. */
+    key: string;
+    header: React.ReactNode;
+    /** Defaults to `String(row[key])`. */
+    cell?: (row: Row) => React.ReactNode;
+    /** Raw value used for client-side sorting and faceting. */
+    value?: (row: Row) => unknown;
+    sortable?: boolean;
+    align?: 'left' | 'right';
+    /** Starting width in pixels; the user can drag from there. */
+    width?: number;
+}
+/**
+ * The operators a filter can use — the same ten names the app manifest declares
+ * and the records endpoint implements.
+ *
+ * The names match; the edges do not, so do not assume a filter composed here and
+ * a `views[]` filter agree on every row. Two known differences: `neq` keeps rows
+ * whose value is absent here and drops them server-side, and the server compares
+ * `gt`/`lt`/`gte`/`lte` on the raw JSON text where this compares numbers and
+ * dates as such. And the endpoint's operator map takes one value per operator
+ * with no `in`, so a server-side facet should offer single-value operators —
+ * multi-select is a client-side affordance.
+ */
+type DataTableFilterOperator = 'eq' | 'neq' | 'contains' | 'ncontains' | 'gt' | 'lt' | 'gte' | 'lte' | 'empty' | 'nempty';
+interface DataTableFacet {
+    key: string;
+    label: string;
+    /** Values to choose from. Without them the facet takes a typed value instead. */
+    options?: Array<{
+        value: string;
+        label?: string;
+    }>;
+    /** Offered operators, first one default. Equality alone if omitted. */
+    operators?: DataTableFilterOperator[];
+}
+interface DataTableFilter {
+    operator: DataTableFilterOperator;
+    /** Empty for `empty`/`nempty`; one entry for a comparison; several for a set. */
+    values: string[];
+}
+interface DataTableSort {
+    key: string;
+    direction: 'asc' | 'desc';
+}
+interface DataTableState {
+    search: string;
+    sort: DataTableSort | null;
+    /** Faceted filters, by facet key. An absent key means "no constraint". */
+    filters: Record<string, DataTableFilter>;
+    hidden: string[];
+    selected: string[];
+}
+interface DataTablePagination {
+    hasNext: boolean;
+    hasPrevious: boolean;
+    onNext: () => void;
+    onPrevious: () => void;
+}
+interface DataTableProps<Row> {
+    columns: Array<DataTableColumn<Row>>;
+    rows: Row[];
+    rowId: (row: Row) => string;
+    /** Controlled state. Anything left out falls back to `defaultState`. */
+    state?: Partial<DataTableState>;
+    defaultState?: Partial<DataTableState>;
+    onStateChange?: (state: DataTableState) => void;
+    facets?: DataTableFacet[];
+    searchPlaceholder?: string;
+    selectable?: boolean;
+    onRowClick?: (row: Row) => void;
+    pagination?: DataTablePagination;
+    /** Server does the sorting, filtering and searching; render `rows` as given. */
+    manual?: boolean;
+    loading?: boolean;
+    error?: React.ReactNode;
+    empty?: React.ReactNode;
+    /** Beyond this many rows the body is virtualised. */
+    virtualizeFrom?: number;
+    className?: string;
+}
+declare function DataTable<Row>({ columns, rows, rowId, state: controlled, defaultState, onStateChange, facets, searchPlaceholder, selectable, onRowClick, pagination, manual, loading, error, empty, virtualizeFrom, className, }: DataTableProps<Row>): React.JSX.Element;
+
+type PeriodPresetKey = 'today' | 'yesterday' | 'last7' | 'last30' | 'last90' | 'thisMonth' | 'lastMonth' | 'thisQuarter' | 'last12Months' | 'thisYear' | 'all' | 'custom';
+interface PeriodRange {
+    /**
+     * Absent means unbounded — only the `all` preset produces it. The spec's
+     * `PeriodValue` sketch types `from` as required, which cannot express the
+     * "all time" entry its own preset rail asks for; a filter with no lower bound
+     * is a different query, so the type says so rather than encoding it as a
+     * sentinel date the caller would have to recognise.
+     */
+    from?: string;
+    to: string;
+}
+type PeriodCompareMode = 'none' | 'previous_period' | 'previous_year' | 'custom';
+interface PeriodValue {
+    preset: PeriodPresetKey;
+    range: PeriodRange;
+    compare: PeriodCompareMode;
+    /** The window `compare` resolves to. Absent when comparing to nothing. */
+    compareRange?: PeriodRange;
+}
+interface PeriodPreset {
+    key: PeriodPresetKey;
+    label: string;
+}
+/** The rail, in the order it is offered. `custom` is reached by picking days. */
+declare const PERIOD_PRESETS: readonly PeriodPreset[];
+declare const COMPARE_LABELS: Record<PeriodCompareMode, string>;
+/**
+ * The window a comparison mode resolves to, or undefined when there is nothing
+ * to compare against — `none`, an unbounded period, or `custom`, whose range the
+ * user picks and which therefore cannot be derived.
+ */
+declare function comparisonRange(preset: PeriodPresetKey, range: PeriodRange, compare: PeriodCompareMode): PeriodRange | undefined;
+/** A period with its comparison window resolved — the only way to build one. */
+declare function makePeriod(preset: PeriodPresetKey, range: PeriodRange, compare: PeriodCompareMode, customCompareRange?: PeriodRange): PeriodValue;
+/** The period a preset resolves to, relative to `today`. */
+declare function periodFromPreset(preset: PeriodPresetKey, today: Date, compare?: PeriodCompareMode): PeriodValue;
+/** A range as a person reads it, collapsing the parts both ends share. */
+declare function formatRange(range: PeriodRange): string;
+/**
+ * What the trigger shows: the preset's name, or the days a custom range spans.
+ *
+ * A range can arrive incomplete — the picker it replaced accepted `{from: '',
+ * to: ''}` as "nothing chosen yet" — and formatting one would print an Invalid
+ * Date rather than say there is nothing to show.
+ */
+declare function formatPeriod(value: PeriodValue): string;
+
+interface DateRangeCompareProps {
+    value: PeriodValue;
+    onChange: (value: PeriodValue) => void;
+    /** Offer the comparison section. */
+    comparable?: boolean;
+    /** Override the rail — a subset, or presets in another order. */
+    presets?: readonly PeriodPreset[];
+    align?: 'start' | 'end';
+    disabled?: boolean;
+    className?: string;
+}
+declare function DateRangeCompare({ value, onChange, comparable, presets, align, disabled, className, }: DateRangeCompareProps): React.JSX.Element;
+/** A day range with both ends — what the pre-contract-2 picker spoke. */
+interface DateRange {
+    from: string;
+    to: string;
+}
+interface DateRangePickerProps {
+    value: DateRange;
+    onChange: (range: DateRange) => void;
+    className?: string;
+    disabled?: boolean;
+}
+/**
+ * The plain range picker, now a view of `DateRangeCompare` with the preset rail
+ * and the comparison section it does not need.
+ *
+ * It stays because removing an export breaks the contract, and its signature is
+ * unchanged: a caller that only ever wanted two days keeps passing two days.
+ */
+declare function DateRangePicker({ value, onChange, className, disabled }: DateRangePickerProps): React.JSX.Element;
+
+/**
+ * The pieces every chart in the kit is built from — the shadcn/chart blocks,
+ * adapted to this SDK.
+ *
+ * Two deliberate departures from the upstream blocks:
+ *
+ * Upstream lets a series carry any CSS colour and injects a per-chart `<style>`
+ * to declare it. Here a series names a `--chart-*` token instead, so there is
+ * nothing to inject: the theme already defines those variables for both colour
+ * schemes, and a chart cannot end up holding a colour the theme does not know.
+ *
+ * Nothing in this file is exported from the package. Recharts is an
+ * implementation detail, and these compose only with Recharts elements, so
+ * exporting them would put the engine in the public API through the back door.
+ */
+
+interface ChartSeries {
+    /** The key this series reads from each row. */
+    key: string;
+    label: string;
+    /** Palette slot. Defaults to the series' position. */
+    colorIndex?: number;
+}
+type ValueFormatter = (value: number) => string;
+
+/**
+ * ChartKit — the charts an app is allowed to draw.
+ *
+ * Each one is a finished block with a narrow, typed surface: rows, the field on
+ * the category axis, and the series to plot. Recharts is never re-exported and
+ * none of its elements appear in a prop type, so the engine stays replaceable
+ * and an app cannot assemble a chart that steps outside the design system.
+ *
+ * Colours come only from the `--chart-*` tokens, which the theme defines for
+ * both colour schemes. That is the whole reason charts belong in the SDK: a
+ * hand-drawn SVG with a hex literal is invisible in dark mode, and every app
+ * that drew its own got that wrong.
+ */
+
+/** A row is whatever an app has; the chart only reads the keys it was given. */
+type ChartRow = Record<string, string | number | null | undefined>;
+interface CartesianChartProps {
+    data: ChartRow[];
+    /** The field on the category axis. */
+    x: string;
+    series: ChartSeries[];
+    /** The same measure over an earlier period, drawn dashed and faded. */
+    compareSeries?: ChartSeries;
+    formatValue?: ValueFormatter;
+    height?: number;
+    /** Read out in place of the graphic. Defaults to the series names. */
+    label?: string;
+    hideLegend?: boolean;
+    className?: string;
+}
+declare function BarChart(props: CartesianChartProps): React.JSX.Element;
+declare function StackedBarChart(props: CartesianChartProps): React.JSX.Element;
+declare function LineChart(props: CartesianChartProps): React.JSX.Element;
+declare function AreaChart(props: CartesianChartProps): React.JSX.Element;
+interface FunnelStep {
+    label: string;
+    value: number;
+}
+interface FunnelChartProps {
+    data: FunnelStep[];
+    formatValue?: ValueFormatter;
+    height?: number;
+    label?: string;
+    className?: string;
+}
+/**
+ * The one chart with no shadcn block, so it is assembled from Recharts' own
+ * funnel elements. Steps keep their palette slot in the order they are given —
+ * a funnel is read top to bottom, and a colour that moved between renders would
+ * read as a different step.
+ */
+declare function FunnelChart({ data, formatValue, height, label, className, }: FunnelChartProps): React.JSX.Element;
+interface KpiCardProps {
+    label: string;
+    value: number;
+    /** The same measure over the compared period. Drives the delta. */
+    compareValue?: number;
+    formatValue?: ValueFormatter;
+    /** For measures that are better when lower — cost, churn, delay. */
+    lowerIsBetter?: boolean;
+    /** A bare trend line under the figure. */
+    sparkline?: number[];
+    className?: string;
+}
+/** The signed change, or null when there is no baseline to divide by. */
+declare function relativeDelta(value: number, compareValue: number | undefined): number | null;
+declare function KpiCard({ label, value, compareValue, formatValue, lowerIsBetter, sparkline, className, }: KpiCardProps): React.JSX.Element;
+
+interface ToastInput {
+    title: string;
+    description?: string;
+    /** `info` exists because Pilotage's own stack had it — a neutral outcome is not a success. */
+    variant?: 'success' | 'error' | 'info';
+}
+/** Returns a `toast({ title, description?, variant? })` function. */
+declare function useToast(): (toast: ToastInput) => void;
+/** Fixed bottom-right stack, auto-dismissing. */
+declare function ToastProvider({ children }: {
+    children: ReactNode;
+}): React.JSX.Element;
+
+/**
+ * Hover tooltip, lifted from the shell.
+ *
+ * Deliberately CSS-only (`group-hover`) rather than another Base UI surface: it
+ * carries no focus, no dismissal and no state, so a portal and a positioner would
+ * be weight for nothing. If a tooltip ever needs to be keyboard-reachable or to
+ * survive a scroll container, that is the moment to move it onto Base UI's.
+ */
+
+declare const SIDES: {
+    readonly top: "bottom-full left-1/2 -translate-x-1/2 mb-1.5";
+    readonly right: "left-full top-1/2 -translate-y-1/2 ml-1.5";
+    readonly bottom: "top-full left-1/2 -translate-x-1/2 mt-1.5";
+    readonly left: "right-full top-1/2 -translate-y-1/2 mr-1.5";
+};
+interface TooltipProps {
+    label: React.ReactNode;
+    children: React.ReactNode;
+    side?: keyof typeof SIDES;
+    className?: string;
+}
+declare function Tooltip({ label, children, side, className }: TooltipProps): React.JSX.Element;
+
 /**
  * Browser helpers for app pages.
  *
@@ -326,4 +655,4 @@ declare function toCsv(rows: string[][]): string;
  */
 declare function downloadCsv(rows: string[][], filename: string): void;
 
-export { type AppApiClient, AppApiProvider, AppContextProvider, type AppContextValue, AppInvokeError, Badge, type BadgeProps, Button, type ButtonProps, Card, CardContent, CardHeader, CardTitle, Checkbox, type CheckboxProps, CopyButton, type CopyButtonProps, type DateRange, DateRangePicker, type DateRangePickerProps, DropdownMenu, type DropdownMenuItem, type DropdownMenuProps, Input, Link, type LinkProps, Modal, type ModalProps, Popover, type PopoverProps, Select, type SelectProps, SidePanel, type SidePanelProps, Spinner, type SpinnerProps, Switch, type SwitchProps, Table, TableBody, TableCell, TableHead, TableHeader, TableRow, Tabs, TabsContent, TabsList, type TabsProps, TabsTrigger, Textarea, type TextareaProps, cn, copyToClipboard, downloadBlob, downloadCsv, toCsv, useAppApi, useAppContext, useAppRun, useAppRuns, useAppSettings };
+export { type AppApiClient, AppApiProvider, AppContextProvider, type AppContextValue, AppInvokeError, AreaChart, Badge, type BadgeProps, BarChart, Button, type ButtonProps, COMPARE_LABELS, Card, CardContent, CardDescription, CardFooter, CardHeader, CardTitle, type CartesianChartProps, type ChartRow, type ChartSeries, Checkbox, type CheckboxProps, CopyButton, type CopyButtonProps, DataTable, type DataTableColumn, type DataTableFacet, type DataTableFilter, type DataTableFilterOperator, type DataTablePagination, type DataTableProps, type DataTableSort, type DataTableState, type DateRange, DateRangeCompare, type DateRangeCompareProps, DateRangePicker, type DateRangePickerProps, DropdownMenu, type DropdownMenuItem, type DropdownMenuProps, FunnelChart, type FunnelChartProps, type FunnelStep, Input, KpiCard, type KpiCardProps, LineChart, Link, type LinkProps, Modal, type ModalProps, PERIOD_PRESETS, type PeriodCompareMode, type PeriodPreset, type PeriodPresetKey, type PeriodRange, type PeriodValue, Popover, type PopoverProps, Select, type SelectOption, type SelectProps, SidePanel, type SidePanelProps, Spinner, type SpinnerProps, StackedBarChart, Switch, type SwitchProps, Table, TableBody, TableCell, TableHead, TableHeader, TableRow, Tabs, TabsContent, TabsList, type TabsProps, TabsTrigger, Textarea, type TextareaProps, type ToastInput, ToastProvider, Tooltip, type TooltipProps, type ValueFormatter, badgeVariants, buttonVariants, cn, comparisonRange, copyToClipboard, downloadBlob, downloadCsv, formatPeriod, formatRange, makePeriod, periodFromPreset, relativeDelta, toCsv, useAppApi, useAppContext, useAppRun, useAppRuns, useAppSettings, useToast };