@logicplanes/kaeso-ui 0.2.2 → 0.3.1

package/dist/types/components/kaeso/provider-picker.d.ts

@@ -0,0 +1,42 @@
+import { type ReactNode } from "react";
+import { type CommandListGroup } from "../command-list/command-list.js";
+import { type FieldWrapProps } from "../field/field.js";
+export declare const KAESO_PROVIDER_PICKER_VARIANTS: {
+    readonly appearance: {
+        readonly list: {
+            readonly classes: "";
+            readonly description: "A search field over every provider, always open: a dialog step (default)";
+        };
+        readonly select: {
+            readonly classes: "";
+            readonly description: "A pill that opens the searchable list: forms and toolbars";
+        };
+    };
+};
+export declare const KAESO_PROVIDER_PICKER_DEFAULT_VARIANTS: {
+    readonly appearance: "list";
+};
+export interface ProviderPickerOption {
+    id: string;
+    name?: string | undefined;
+    connected?: boolean | undefined;
+    hint?: ReactNode | undefined;
+    keywords?: readonly string[] | undefined;
+    disabled?: boolean | undefined;
+}
+export interface ProviderPickerProps extends FieldWrapProps {
+    providers: ProviderPickerOption[];
+    value?: string | null | undefined;
+    onValueChange?: ((id: string | null) => void) | undefined;
+    appearance?: keyof typeof KAESO_PROVIDER_PICKER_VARIANTS.appearance | undefined;
+    allLabel?: string | undefined;
+    placeholder?: string | undefined;
+    size?: "sm" | "md" | undefined;
+    disabled?: boolean | undefined;
+    autoFocus?: boolean | undefined;
+    "aria-label"?: string | undefined;
+    className?: string | undefined;
+    "data-force"?: string | undefined;
+}
+export declare function useProviderGroups(providers: ProviderPickerOption[], allLabel?: string | undefined): CommandListGroup[];
+export declare const ProviderPicker: import("react").ForwardRefExoticComponent<ProviderPickerProps & import("react").RefAttributes<HTMLElement>>;

package/dist/types/components/list/docs.d.ts

@@ -33,6 +33,7 @@ export declare const docs: {
             selected: string;
             selectionActions: string;
             selectionBar: string;
+            wrapSubtitle: string;
             virtualizeAbove: string;
         };
     };
@@ -53,6 +54,7 @@ export declare const docs: {
             selectable: string;
             selected: string;
             selecting: string;
+            wrapSubtitle: string;
         };
     };
     SelectionAction: {

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

@@ -49,6 +49,7 @@ export interface ListProps {
     onSelectedChange?: ((selected: Set<string>) => void) | undefined;
     idWidth?: 48 | 64 | 80 | 96 | 120 | undefined;
     density?: keyof typeof KAESO_LIST_VARIANTS.density | undefined;
+    wrapSubtitle?: boolean | undefined;
     virtualizeAbove?: number | undefined;
     selectionActions?: ReactNode | undefined;
     selectionBar?: boolean | undefined;
@@ -73,6 +74,7 @@ export interface ListRowProps {
     lastChild?: boolean | undefined;
     idWidth?: keyof typeof ID_W | undefined;
     density?: keyof typeof KAESO_LIST_VARIANTS.density | undefined;
+    wrapSubtitle?: boolean | undefined;
     narrow?: boolean | undefined;
     active?: boolean | undefined;
     selected?: boolean | undefined;

package/dist/types/components/menu/styles.d.ts

@@ -4,4 +4,4 @@ export declare const MENU_ICON = "text-fg-secondary group-data-highlighted/item:
 export declare const MENU_DANGER = "text-danger-text highlighted:bg-danger-tint";
 export declare const MENU_LABEL = "flex h-28 items-center px-10 text-caption font-medium text-fg-secondary";
 export declare const MENU_SEPARATOR = "mx-10 my-4 h-1 shrink-0 bg-line-subtle";
-export declare const MENU_HINT = "ml-auto flex shrink-0 items-center gap-4 pl-16 text-caption font-medium text-fg-tertiary tabular";
+export declare const MENU_HINT = "ml-auto flex shrink-0 items-center gap-4 pl-16 text-caption font-medium text-fg-tertiary tabular group-data-highlighted/item:text-fg-secondary";

package/dist/types/components/playground/docs.d.ts

@@ -39,17 +39,33 @@ export declare const docs: {
     ModelPicker: {
         description: string;
         props: {
+            description: string;
+            label: string;
+            layout: string;
+            optional: string;
+            required: string;
+            allLabel: string;
             appearance: string;
             "aria-label": string;
             defaultValue: string;
             disabled: string;
+            fullWidth: string;
             groupByProvider: string;
+            invalid: string;
+            multiple: string;
+            onOpenChange: string;
             onValueChange: string;
+            open: string;
             options: string;
             placeholder: string;
+            providers: string;
+            recent: string;
             size: string;
             value: string;
         };
+        deprecated: {
+            error: string;
+        };
     };
     ParameterPanel: {
         description: string;
@@ -94,6 +110,20 @@ export declare const docs: {
             suggestions: string;
         };
     };
+    Reasoning: {
+        description: string;
+        props: {
+            children: string;
+            defaultOpen: string;
+            duration: string;
+            hint: string;
+            live: string;
+            onOpenChange: string;
+            open: string;
+            text: string;
+            title: string;
+        };
+    };
     ResponseMetrics: {
         description: string;
         props: {
@@ -114,7 +144,9 @@ export declare const docs: {
         props: {
             "aria-label": string;
             defaultReasoningOpen: string;
+            error: string;
             footer: string;
+            incompleteReason: string;
             onReasoningOpenChange: string;
             onRetry: string;
             reasoning: string;

package/dist/types/components/playground/index.d.ts

@@ -1,6 +1,7 @@
 export * from "./composer.js";
 export * from "./compare-grid.js";
 export * from "./response-view.js";
+export * from "./reasoning.js";
 export * from "./response-metrics.js";
 export * from "./parameter-panel.js";
 export * from "./model-picker.js";

package/dist/types/components/playground/model-picker.d.ts

@@ -1,3 +1,6 @@
+import { type CommandListGroup } from "../command-list/command-list.js";
+import { type FieldWrapProps } from "../field/field.js";
+import { type Capability } from "../kaeso/identity.js";
 export declare const KAESO_MODEL_PICKER_VARIANTS: {
     readonly appearance: {
         readonly ghost: {
@@ -18,20 +21,52 @@ export interface ModelPickerOption {
     provider: string;
     model?: string | undefined;
     name?: string | undefined;
+    capabilities?: Capability[] | undefined;
+    context?: number | undefined;
+    price?: string | undefined;
+    note?: string | undefined;
+    deprecated?: boolean | undefined;
     disabled?: boolean | undefined;
 }
-export interface ModelPickerProps {
+export interface ModelPickerProvider {
+    id: string;
+    name?: string | undefined;
+    connected?: boolean | undefined;
+}
+interface BaseProps extends FieldWrapProps {
     options: ModelPickerOption[];
-    value?: string | null | undefined;
-    defaultValue?: string | null | undefined;
-    onValueChange?: ((value: string) => void) | undefined;
+    providers?: ModelPickerProvider[] | undefined;
+    recent?: readonly string[] | undefined;
     groupByProvider?: boolean | undefined;
     placeholder?: string | undefined;
     "aria-label"?: string | undefined;
     appearance?: keyof typeof KAESO_MODEL_PICKER_VARIANTS.appearance | undefined;
     size?: "sm" | "md" | undefined;
+    fullWidth?: boolean | undefined;
     disabled?: boolean | undefined;
+    invalid?: boolean | undefined;
+    open?: boolean | undefined;
+    onOpenChange?: ((open: boolean) => void) | undefined;
     "data-force"?: string | undefined;
     className?: string | undefined;
 }
+export interface SingleModelPickerProps extends BaseProps {
+    multiple?: false | undefined;
+    allLabel?: string | undefined;
+    value?: string | null | undefined;
+    defaultValue?: string | null | undefined;
+    onValueChange?: ((value: string) => void) | undefined;
+}
+export interface MultiModelPickerProps extends BaseProps {
+    multiple: true;
+    value?: string[] | undefined;
+    defaultValue?: string[] | undefined;
+    onValueChange?: ((value: string[]) => void) | undefined;
+}
+export type ModelPickerProps = SingleModelPickerProps | MultiModelPickerProps;
+export declare function useModelGroups(options: ModelPickerOption[], { providers, groupByProvider }?: {
+    providers?: ModelPickerProvider[] | undefined;
+    groupByProvider?: boolean | undefined;
+}): CommandListGroup[];
 export declare const ModelPicker: import("react").ForwardRefExoticComponent<ModelPickerProps & import("react").RefAttributes<HTMLButtonElement>>;
+export {};

package/dist/types/components/playground/reasoning.d.ts

@@ -0,0 +1,29 @@
+import { type ReactNode } from "react";
+export declare const KAESO_REASONING_VARIANTS: {
+    readonly state: {
+        readonly done: {
+            readonly classes: "";
+            readonly description: "Finished: “Thought for 4.2 s”, closed until opened (default)";
+        };
+        readonly live: {
+            readonly classes: "";
+            readonly description: "Still reasoning: “Thinking” pulses quietly and the latest line shows beside it";
+        };
+    };
+};
+export declare const KAESO_REASONING_DEFAULT_VARIANTS: {
+    readonly state: "done";
+};
+export interface ReasoningProps {
+    text?: string | undefined;
+    live?: boolean | undefined;
+    duration?: number | undefined;
+    title?: ReactNode | undefined;
+    hint?: ReactNode | undefined;
+    open?: boolean | undefined;
+    defaultOpen?: boolean | undefined;
+    onOpenChange?: ((open: boolean) => void) | undefined;
+    children?: ReactNode | undefined;
+    className?: string | undefined;
+}
+export declare const Reasoning: import("react").ForwardRefExoticComponent<ReasoningProps & import("react").RefAttributes<HTMLDivElement>>;

package/dist/types/components/playground/response-view.d.ts

@@ -17,9 +17,13 @@ export declare const KAESO_RESPONSE_VIEW_VARIANTS: {
             readonly classes: "";
             readonly description: "Stopped by the person: the text so far and “Stopped”";
         };
+        readonly incomplete: {
+            readonly classes: "";
+            readonly description: "Cut off by the model: the text so far and why, such as “Stopped at the output limit”";
+        };
         readonly error: {
             readonly classes: "";
-            readonly description: "Failed: “No response” and Retry. The error itself is a toast";
+            readonly description: "Failed: the error in place of the response, and Retry";
         };
     };
 };
@@ -35,6 +39,8 @@ export interface ResponseViewProps {
     reasoningOpen?: boolean | undefined;
     defaultReasoningOpen?: boolean | undefined;
     onReasoningOpenChange?: ((open: boolean) => void) | undefined;
+    incompleteReason?: string | undefined;
+    error?: string | undefined;
     onRetry?: (() => void) | undefined;
     footer?: ReactNode | undefined;
     "aria-label"?: string | undefined;

package/dist/types/components/release-art/docs.d.ts

@@ -4,6 +4,7 @@ export declare const docs: {
         props: {
             seed: string;
             art: string;
+            src: string;
             label: string;
             title: string;
             eyebrow: string;

package/dist/types/components/release-art/release-art.d.ts

@@ -20,6 +20,7 @@ export interface ReleaseArtProps {
     seed: string;
     label: string;
     art?: ReleaseArtSpec | undefined;
+    src?: string | undefined;
     title?: ReactNode | undefined;
     eyebrow?: ReactNode | undefined;
     shape?: keyof typeof KAESO_RELEASE_ART_VARIANTS.shape | undefined;

package/dist/types/components/select/docs.d.ts

@@ -24,8 +24,6 @@ export declare const docs: {
             required: string;
             size: string;
             value: string;
-        };
-        deprecated: {
             error: string;
         };
     };

package/dist/types/components/select/option-checkbox.d.ts

@@ -0,0 +1 @@
+export declare function OptionCheckbox(): import("react/jsx-runtime").JSX.Element;

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

@@ -47,6 +47,7 @@ interface SidebarCtx {
     setPeeking: (v: boolean) => void;
     width: number;
     setWidth: (v: number) => void;
+    previewWidth: (v: number | null) => void;
     storageKey: string | undefined;
 }
 export declare const useSidebar: () => SidebarCtx;

package/dist/types/components/stat/docs.d.ts

@@ -27,6 +27,7 @@ export declare const docs: {
             change: string;
             detail: string;
             label: string;
+            loading: string;
             trend: string;
             trendColor: string;
             value: string;

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

@@ -39,6 +39,7 @@ export interface StatTileProps {
     detail?: ReactNode | undefined;
     trend?: number[] | undefined;
     trendColor?: string | undefined;
+    loading?: boolean | undefined;
     className?: string | undefined;
 }
 export declare const STAT_VALUE_STEPS: readonly [{

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

@@ -4,16 +4,22 @@ export declare function setFormatTimeZone(timeZone: string | undefined): void;
 export declare function formatTimeZone(): string | undefined;
 export declare function formatNumber(value: number, options?: Intl.NumberFormatOptions): string;
 export declare function formatTokens(value: number): string;
+/** A model's context or output limit as models are named: a multiple of 1,024 in binary thousands ("128K" for 131,072, "1M" for 1,048,576), anything else in decimal ones ("128K" for 128,000, "200K"). */
+export declare function formatContext(tokens: number): string;
 export declare function formatBytes(bytes: number): string;
 export declare function formatPercent(ratio: number, digits?: number): string;
 export declare function formatUSD(amount: string, options?: {
     significant?: number;
     decimals?: number;
 }): string;
+/** A price per million tokens, exactly as set: at least two decimals and up to six ("$0.075", "$4.00", "$1.25"). */
+export declare function formatPrice(amount: string): string;
 export declare function formatDuration(ms: number, options?: {
     precise?: boolean | undefined;
 }): string;
 type DateInput = Date | string | number;
+/** A cached date formatter in the format locale. English writes the day first with three-letter months ("20 Sep 2026", "Mon 21 Sep"), the console's English everywhere. */
+export declare function dateFormatter(options: Intl.DateTimeFormatOptions, locale?: string): (value: DateInput) => string;
 export declare function formatDate(value: DateInput, options?: {
     time?: boolean;
     utc?: boolean;

package/dist/types/index.d.ts

@@ -50,6 +50,7 @@ export * from "./components/display-options/index.js";
 export * from "./components/dialog/index.js";
 export * from "./components/sheet/index.js";
 export * from "./components/command-palette/index.js";
+export * from "./components/command-list/index.js";
 export * from "./components/toast/index.js";
 export * from "./components/pagination/index.js";
 export * from "./components/toc/index.js";

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

@@ -4,5 +4,5 @@ export { devWarn, warnStylingClassName, warnMissingName, warnControlled } from "
 export { LinkProvider, useLinkComponent, isExternalHref, type LinkComponent, type LinkComponentProps } from "./link-provider.js";
 export { useControllable } from "./use-controllable.js";
 export { PortalContainer, usePortalContainer, pageBoundary } from "./portal-context.js";
-export { InsetContent, useInset } from "./inset.js";
+export { GutterContent, InsetContent, useGutterPadded, useInset } from "./inset.js";
 export type { StatusTone } from "./tone.js";

package/dist/types/utils/inset.d.ts

@@ -4,3 +4,8 @@ export declare function InsetContent({ children, inset }: {
     inset?: boolean | undefined;
 }): import("react/jsx-runtime").JSX.Element;
 export declare function useInset(): boolean;
+export declare function GutterContent({ children, padded }: {
+    children: ReactNode;
+    padded?: boolean | undefined;
+}): import("react/jsx-runtime").JSX.Element;
+export declare function useGutterPadded(): boolean;

package/dist/types/utils/over-sheet.d.ts

@@ -0,0 +1 @@
+export declare const OverNonModalSheet: import("react").Context<boolean>;

package/dist/types/utils/restore-focus.d.ts

@@ -1,4 +1,4 @@
 export declare function useRestoreFocus(open: boolean | undefined, first?: () => HTMLElement | boolean): {
     initialFocus: () => boolean | HTMLElement;
-    finalFocus: () => true | HTMLElement;
+    finalFocus: () => boolean | HTMLElement;
 };

package/dist/utils.js

@@ -1,9 +1,9 @@
 "use client";
-import { t as e } from "./chunks/cn-CidVUKMm.js";
+import { t as e } from "./chunks/cn-DUDmdLpZ.js";
 import { t } from "./chunks/utils-CdH72WEp.js";
 import { i as n, n as r, r as i, t as a } from "./chunks/dev-CR1p7gCm.js";
-import { n as o, r as s, t as c } from "./chunks/link-provider---9JdxTg.js";
+import { n as o, r as s, t as c } from "./chunks/link-provider-BsUxhZKG.js";
 import { t as l } from "./chunks/use-controllable-B5Fd12Bx.js";
 import { n as u, r as d, t as f } from "./chunks/portal-context-BBbzDKmY.js";
-import { n as p, t as m } from "./chunks/inset-BLMdxX4I.js";
-export { m as InsetContent, c as LinkProvider, f as PortalContainer, e as cn, a as devWarn, o as isExternalHref, u as pageBoundary, t as resolveVariant, l as useControllable, p as useInset, s as useLinkComponent, d as usePortalContainer, r as warnControlled, i as warnMissingName, n as warnStylingClassName };
+import { i as p, n as m, r as h, t as g } from "./chunks/inset-BnBj8NJV.js";
+export { g as GutterContent, m as InsetContent, c as LinkProvider, f as PortalContainer, e as cn, a as devWarn, o as isExternalHref, u as pageBoundary, t as resolveVariant, l as useControllable, h as useGutterPadded, p as useInset, s as useLinkComponent, d as usePortalContainer, r as warnControlled, i as warnMissingName, n as warnStylingClassName };

package/foundations/layout.md

@@ -0,0 +1,45 @@
+# Layout
+
+One edge per page. The components bring their own insets, so a page composed of them lines up without a margin of its own. Values: `../ai/tokens.md`.
+
+## The gutter
+
+| Where                                         | Gutter                                                                                   |
+| --------------------------------------------- | ---------------------------------------------------------------------------------------- |
+| The content panel, at every width             | 24px: page header, toolbar, page body, lists, tables, dialogs, sheets and the phone bar  |
+| The sidebar                                   | 16px; its items pad their content 12px, so icons and the wordmark sit 28px in            |
+| Settings groups, inset lists and inset tables | 20px inside the group                                                                    |
+| Menus, selects and the command palette        | Their own inset (6px), with rows padded 10px; a popup is a surface, not part of the page |
+
+## Boxes sit on the gutter
+
+Every box starts and ends on the gutter. A box is anything whose edge you can see, at rest or under the pointer: a button, an input, a chip, a segmented track, a pill tab (the selected one is filled), the hover and selected fill of a list row or a table row, the hover fill of a group header or a disclosure, a settings group. Nothing bleeds into the gutter: it stays empty at every width, no fill touches the panel's edge, and no focus ring is cut off by a scroller.
+
+Text inside a box is padded by the box: 12px in list rows, table cells, pill tabs, chips, group headers and disclosures. A page so has two vertical lines and no others:
+
+- **The gutter**, where every box and every piece of plain text starts: the page title, headings, labels, descriptions, chart axes.
+- **The gutter plus 12px**, where the text inside boxes starts: a row's title, a tab's label, a column's values.
+
+A surface that already pads its content by the gutter, such as a dialog, a sheet, a content page (`AppFrame.Body padding="page"`) or a settings column, is the gutter: a list or a table inside it puts its rows on that padding instead of adding 24px of its own.
+
+The same holds at the right edge: the last box ends on the gutter, the last column's text 12px inside it.
+
+## Exceptions
+
+- **Text in running text.** A link or an inline copyable value inside a sentence keeps its 2 to 4px of hit padding around the text. It is part of the line, not a box.
+- **Controls inside a box on the gutter.** Inside a box that already sits on the gutter, such as a table's header cell, a settings group's header or a banner, a control may use that box's own padding and keep its label on the box's text line: a column's sort button keeps its label on the column's edge.
+- **Pane dividers.** Hairlines that split the panel into panes, such as the playground's columns, run from edge to edge; each pane keeps the 24px gutter inside it.
+- **The wordmark** sits 28px in and 28px down in the sidebar and on sign-in screens, on the sidebar's content line. On the phone bar it sits on the page's 24px gutter, and on a sign-in screen narrower than 640px on the form's 16px gutter, like everything under it.
+
+## Vertical rhythm
+
+- The page header is 52px and the toolbar under it 48px; neither draws a line.
+- A list or table starts 8px under the toolbar (`AppFrame.Body padding="list"`); a content page 16px under the header (`padding="page"`).
+- List rows are 44px (36px compact, 56px with a second line); table rows 40px; group headers 36px, with 16px above every one after the first.
+- A row's height never depends on its content: badges, pills and avatars fit inside it.
+
+## Numbers and truncation
+
+- Numeric columns are right-aligned and use tabular figures, so digits line up from row to row.
+- A column is wide enough for its header in every language, and for the values people compare: a provider's name, a status, a cost. Truncate only what is long by nature (ids, messages, user agents), and show the whole value on hover.
+- On a phone, drop columns before truncating the ones that stay.

package/foundations/writing.md

@@ -9,6 +9,7 @@ Clear enough to act on, exact enough to trust, and calm enough to stay out of th
 - **No exclamation points, no emoji**, no jokes, no congratulations.
 - **Errors say what did not happen and what to do next**: "Couldn't reach the provider. Check the provider key, then try again."
 - **Name the object**: "Key copied", not "Copied to clipboard".
+- **Toasts are one sentence.** A confirmation, a warning or progress reads as a phrase without a final period: "Key revoked", "Password changed; sign in with the new one". An error ends with a period, like the gateway's messages: "The email or password is wrong."
 - **Use Kaeso's terms**: key, provider key, project, organization, model, alias, limit, budget, request log.
 - **Realistic data in examples**, never lorem ipsum.
 - **Straight apostrophes** in English: "Couldn't load these rows", "the key's name", never `’`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@logicplanes/kaeso-ui",
-  "version": "0.2.2",
+  "version": "0.3.1",
   "description": "Kaeso's UI library: React components on Base UI, Tailwind CSS v4 and the Kaeso tokens.",
   "license": "MIT",
   "author": "Devin Oldenburg",
@@ -102,7 +102,7 @@
     "shiki": "4.4.3",
     "tailwind-merge": "3.7.0",
     "uqr": "0.1.3",
-    "@logicplanes/kaeso-tokens": "0.2.2"
+    "@logicplanes/kaeso-tokens": "0.3.1"
   },
   "devDependencies": {
     "@hugeicons/core-free-icons": "4.3.5",