@nimblebrain/synapse 0.14.1 → 0.16.0

package/dist/ui/index.d.cts

@@ -11,13 +11,25 @@ interface AvatarProps extends Omit<HTMLAttributes<HTMLSpanElement>, "children">
 }
 declare function Avatar({ name, src, size, style, ...rest }: AvatarProps): react_jsx_runtime.JSX.Element;
 
-type BadgeTone = "neutral" | "accent" | "success" | "warning" | "danger" | "processing" | "warm";
+type BadgeTone = "neutral" | "accent" | "success" | "warning" | "danger" | "processing";
 interface BadgeProps extends HTMLAttributes<HTMLSpanElement> {
     tone?: BadgeTone;
     children?: ReactNode;
 }
 declare function Badge({ tone, style, children, ...rest }: BadgeProps): react_jsx_runtime.JSX.Element;
 
+interface Crumb {
+    label: string;
+    /** Omit on the current step. A crumb with no handler renders as plain text. */
+    onClick?: () => void;
+}
+interface BreadcrumbProps extends Omit<HTMLAttributes<HTMLElement>, "children"> {
+    crumbs: Crumb[];
+    /** The glyph between steps. */
+    separator?: string;
+}
+declare function Breadcrumb({ crumbs, separator, style, ...rest }: BreadcrumbProps): react_jsx_runtime.JSX.Element;
+
 type Variant = "primary" | "secondary" | "ghost";
 type Size = "sm" | "md";
 interface ButtonProps extends ButtonHTMLAttributes<HTMLButtonElement> {
@@ -102,6 +114,20 @@ interface ListRowProps extends Omit<HTMLAttributes<HTMLDivElement>, "title"> {
 }
 declare function ListRow({ title, meta, leading, trailing, interactive, style, className, ...rest }: ListRowProps): react_jsx_runtime.JSX.Element;
 
+interface PageHeaderProps extends Omit<HTMLAttributes<HTMLElement>, "title"> {
+    /** The trail. Omit on a top-level page, which has nothing above it to name. */
+    crumbs?: Crumb[];
+    title: ReactNode;
+    /** Sits beside the title — typically a `Badge`. */
+    status?: ReactNode;
+    /** Sits at the far end of the title's row. Buttons, a menu. */
+    actions?: ReactNode;
+    description?: ReactNode;
+    /** Lines the description is clamped to before ellipsis. `0` removes the clamp. */
+    descriptionLines?: number;
+}
+declare function PageHeader({ crumbs, title, status, actions, description, descriptionLines, style, ...rest }: PageHeaderProps): react_jsx_runtime.JSX.Element;
+
 interface PaginationProps extends Omit<HTMLAttributes<HTMLDivElement>, "onChange"> {
     /** Current page, 1-based. */
     page: number;
@@ -160,6 +186,12 @@ interface Column<T> {
     /** Cell content for a row. */
     render: (row: T, index: number) => ReactNode;
     align?: Align$1;
+    /**
+     * Column width (`"40%"`, `220`, `"12rem"`). Declaring one on any column switches
+     * the table to `table-layout: fixed`, and columns without a width then divide the
+     * remainder equally. Required on any column whose cell truncates — see the note on
+     * the module above.
+     */
     width?: number | string;
 }
 interface TableProps<T> extends Omit<HTMLAttributes<HTMLTableElement>, "children"> {
@@ -170,8 +202,39 @@ interface TableProps<T> extends Omit<HTMLAttributes<HTMLTableElement>, "children
     onRowClick?: (row: T, index: number) => void;
     /** Shown when `data` is empty. */
     empty?: ReactNode;
+    /**
+     * The narrowest this table stays readable, and the switch that turns scrolling on.
+     *
+     * A fixed-layout table has no lower bound of its own, so seven columns in a 400px pane
+     * become seven clipped headers and a badge overflowing its cell. Below this width the
+     * table scrolls inside its own container instead of crushing — and setting the floor is
+     * the only way to ask for that, because a scroller with no floor has no defined moment to
+     * engage: under fixed layout the table always fits its container, and under auto layout it
+     * engages at whatever width the content happens to reach.
+     *
+     * The cost is the sticky header. An `overflow-x` container captures the stickiness
+     * `position: sticky` resolves against the page's own scroller, and CSS gives no way to
+     * scroll one axis while leaving the other visible — so a table without a floor keeps its
+     * sticky header, and one with a floor trades it.
+     */
+    minWidth?: number | string;
+}
+declare function Table<T>({ data, columns, rowKey, onRowClick, empty, minWidth, style, className, ...rest }: TableProps<T>): react_jsx_runtime.JSX.Element;
+
+interface Tab<T extends string> {
+    label: string;
+    value: T;
+    /** A small trailing count. Rendered muted, and omitted entirely when undefined. */
+    count?: number;
+}
+interface TabsProps<T extends string> extends Omit<HTMLAttributes<HTMLDivElement>, "onChange"> {
+    tabs: Tab<T>[];
+    value: T;
+    onChange: (value: T) => void;
+    /** Accessible name for the tab set — what these are facets OF. */
+    label?: string;
 }
-declare function Table<T>({ data, columns, rowKey, onRowClick, empty, style, className, ...rest }: TableProps<T>): react_jsx_runtime.JSX.Element;
+declare function Tabs<T extends string>({ tabs, value, onChange, label, style, className, onKeyDown: callerKeyDown, ...rest }: TabsProps<T>): react_jsx_runtime.JSX.Element;
 
 type ContentWidth = "reading" | "full";
 interface AppFrameProps extends HTMLAttributes<HTMLDivElement> {
@@ -233,6 +296,38 @@ declare const ListDetailLayout: typeof ListDetailLayoutRoot & {
     Back: typeof Back;
 };
 
+interface PageLayoutProps extends Omit<HTMLAttributes<HTMLDivElement>, "title"> {
+    /** The trail. Omit at the top level, which has nothing above it to name. */
+    crumbs?: Crumb[];
+    title: ReactNode;
+    /** Beside the title — typically a `Badge`. */
+    status?: ReactNode;
+    /** The far end of the title's row. */
+    actions?: ReactNode;
+    description?: ReactNode;
+    /** Lines the description is clamped to. `0` removes the clamp. */
+    descriptionLines?: number;
+    /**
+     * ONE tab bar, of the facets of whatever the title names. A `Tabs`.
+     *
+     * A slot rather than typed props because `Tabs` already has an API worth having, and
+     * wrapping it here would mean maintaining a second copy of it that drifts. What the layout
+     * owns is the bar's POSITION — under the header, above the content — which is the part
+     * apps get wrong.
+     */
+    tabs?: ReactNode;
+    /**
+     * Controls that narrow the content below: a search field, a status filter, a view toggle.
+     *
+     * Distinct from `tabs` on purpose. A tab changes which facet of one entity is shown; a
+     * toolbar reshapes a set within that facet. Rendering them as one row is how an app ends up
+     * with two identical-looking control strips whose difference nobody can see.
+     */
+    toolbar?: ReactNode;
+    children?: ReactNode;
+}
+declare function PageLayout({ crumbs, title, status, actions, description, descriptionLines, tabs, toolbar, children, style, ...rest }: PageLayoutProps): react_jsx_runtime.JSX.Element;
+
 type CollapseMode = "reflow" | "drawer";
 type Side = "left" | "right";
 interface SidebarState {
@@ -325,10 +420,13 @@ declare function Divider({ orientation, style, ...rest }: DividerProps): react_j
  * with no React re-render: the host swaps the `:root` vars and every `var()`
  * re-resolves.
  *
- * The fallbacks are deliberately **neutral** (system fonts, neutral grays, a
- * generic blue) — NOT NimbleBrain brand. Brand arrives by injection when the
- * app runs inside the NimbleBrain host; standalone/static renders get a sane
+ * The fallbacks are deliberately **unbranded** — system fonts, neutral grays, a
+ * generic blue, and generic semantic hues for the status channels. NOT
+ * NimbleBrain brand. Brand arrives by injection when the app runs inside the
+ * NimbleBrain host; standalone/static renders get a sane
  * unbranded default. This keeps the library host-agnostic.
+ * `__tests__/ui/tokens.test.ts` holds the line: every hex in these fallbacks
+ * must be in the sanctioned set, same as `theme-defaults.ts`.
  *
  * Components import the static `tokens` object and style with CSS `var()`, so
  * theming (incl. light/dark) resolves in CSS with no re-render.
@@ -350,14 +448,12 @@ declare const tokens: {
     readonly danger: "var(--nb-color-danger, #dc2626)";
     readonly success: "var(--nb-color-success, #059669)";
     readonly warning: "var(--nb-color-warning, #f59e0b)";
-    readonly warm: "var(--nb-color-warm, #d4620a)";
-    readonly warmLight: "var(--nb-color-warm-light, #fef5ee)";
     readonly processing: "var(--nb-color-processing, #7c3aed)";
     readonly processingLight: "var(--nb-color-processing-light, #f3eeff)";
     readonly infoLight: "var(--nb-color-info-light, #eef4ff)";
     readonly fontSans: "var(--font-sans, system-ui, -apple-system, BlinkMacSystemFont, sans-serif)";
     readonly fontMono: "var(--font-mono, ui-monospace, SFMono-Regular, Menlo, monospace)";
-    readonly fontHeading: "var(--nb-font-heading, Georgia, 'Times New Roman', serif)";
+    readonly fontHeading: "var(--nb-font-heading, system-ui, -apple-system, BlinkMacSystemFont, sans-serif)";
     readonly weightNormal: "var(--font-weight-normal, 400)";
     readonly weightMedium: "var(--font-weight-medium, 500)";
     readonly weightSemibold: "var(--font-weight-semibold, 600)";
@@ -404,7 +500,24 @@ interface TextProps extends Omit<HTMLAttributes<HTMLElement>, "color"> {
     weight?: Weight;
     tone?: Tone;
     mono?: boolean;
-    /** Single-line ellipsis truncation. */
+    /**
+     * Single-line ellipsis truncation.
+     *
+     * Sets `display: block` alongside the ellipsis rules, and that is load-bearing rather
+     * than incidental: `overflow` and `text-overflow` do not apply to a non-replaced INLINE
+     * box, so on the default `<span>` the only declaration that survived was
+     * `white-space: nowrap` — and the prop did the exact opposite of its name, making text
+     * unwrappable instead of clipping it. Inside an auto-layout `<table>` that widened the
+     * column to the full string and pushed every later column off the pane.
+     *
+     * `min-width: 0` comes with it so the box can actually shrink as a flex item; without it
+     * a truncating `Text` inside `Inline`/`Stack` refuses to go below its content width and
+     * pushes its container instead, which is the same bug one layer out.
+     *
+     * A truncating cell in a `Table` also needs its column to declare a `width` — see
+     * `Column.width`. Auto table layout sizes to content, so the ellipsis has nothing to
+     * clip against until some column is pinned.
+     */
     truncate?: boolean;
     as?: ElementType;
     children?: ReactNode;
@@ -421,4 +534,4 @@ interface HeadingProps extends Omit<HTMLAttributes<HTMLHeadingElement>, "color">
 /** Display heading using the heading font slot. Defaults to md, semibold. */
 declare function Heading({ size, weight, tone, as: As, style, children, ...rest }: HeadingProps): react_jsx_runtime.JSX.Element;
 
-export { AppFrame, Avatar, Badge, type BadgeTone, Button, Card, type Column, Divider, Drawer, EmptyState, Heading, type HeadingSize, Inline, ListDetailLayout, ListRow, Pagination, Prose, SearchField, SegmentedControl, SidebarLayout, Spacer, Spinner, Stack, type Status, StatusDot, Table, Text, TextLink, type TextSize, type Tokens, headingStyle, textStyle, tokens, useBreakpoint, useListDetail, useSidebar };
+export { AppFrame, Avatar, Badge, type BadgeTone, Breadcrumb, Button, Card, type Column, type Crumb, Divider, Drawer, EmptyState, Heading, type HeadingSize, Inline, ListDetailLayout, ListRow, PageHeader, PageLayout, Pagination, Prose, SearchField, SegmentedControl, SidebarLayout, Spacer, Spinner, Stack, type Status, StatusDot, Table, Tabs, Text, TextLink, type TextSize, type Tokens, headingStyle, textStyle, tokens, useBreakpoint, useListDetail, useSidebar };

package/dist/ui/index.d.ts

@@ -11,13 +11,25 @@ interface AvatarProps extends Omit<HTMLAttributes<HTMLSpanElement>, "children">
 }
 declare function Avatar({ name, src, size, style, ...rest }: AvatarProps): react_jsx_runtime.JSX.Element;
 
-type BadgeTone = "neutral" | "accent" | "success" | "warning" | "danger" | "processing" | "warm";
+type BadgeTone = "neutral" | "accent" | "success" | "warning" | "danger" | "processing";
 interface BadgeProps extends HTMLAttributes<HTMLSpanElement> {
     tone?: BadgeTone;
     children?: ReactNode;
 }
 declare function Badge({ tone, style, children, ...rest }: BadgeProps): react_jsx_runtime.JSX.Element;
 
+interface Crumb {
+    label: string;
+    /** Omit on the current step. A crumb with no handler renders as plain text. */
+    onClick?: () => void;
+}
+interface BreadcrumbProps extends Omit<HTMLAttributes<HTMLElement>, "children"> {
+    crumbs: Crumb[];
+    /** The glyph between steps. */
+    separator?: string;
+}
+declare function Breadcrumb({ crumbs, separator, style, ...rest }: BreadcrumbProps): react_jsx_runtime.JSX.Element;
+
 type Variant = "primary" | "secondary" | "ghost";
 type Size = "sm" | "md";
 interface ButtonProps extends ButtonHTMLAttributes<HTMLButtonElement> {
@@ -102,6 +114,20 @@ interface ListRowProps extends Omit<HTMLAttributes<HTMLDivElement>, "title"> {
 }
 declare function ListRow({ title, meta, leading, trailing, interactive, style, className, ...rest }: ListRowProps): react_jsx_runtime.JSX.Element;
 
+interface PageHeaderProps extends Omit<HTMLAttributes<HTMLElement>, "title"> {
+    /** The trail. Omit on a top-level page, which has nothing above it to name. */
+    crumbs?: Crumb[];
+    title: ReactNode;
+    /** Sits beside the title — typically a `Badge`. */
+    status?: ReactNode;
+    /** Sits at the far end of the title's row. Buttons, a menu. */
+    actions?: ReactNode;
+    description?: ReactNode;
+    /** Lines the description is clamped to before ellipsis. `0` removes the clamp. */
+    descriptionLines?: number;
+}
+declare function PageHeader({ crumbs, title, status, actions, description, descriptionLines, style, ...rest }: PageHeaderProps): react_jsx_runtime.JSX.Element;
+
 interface PaginationProps extends Omit<HTMLAttributes<HTMLDivElement>, "onChange"> {
     /** Current page, 1-based. */
     page: number;
@@ -160,6 +186,12 @@ interface Column<T> {
     /** Cell content for a row. */
     render: (row: T, index: number) => ReactNode;
     align?: Align$1;
+    /**
+     * Column width (`"40%"`, `220`, `"12rem"`). Declaring one on any column switches
+     * the table to `table-layout: fixed`, and columns without a width then divide the
+     * remainder equally. Required on any column whose cell truncates — see the note on
+     * the module above.
+     */
     width?: number | string;
 }
 interface TableProps<T> extends Omit<HTMLAttributes<HTMLTableElement>, "children"> {
@@ -170,8 +202,39 @@ interface TableProps<T> extends Omit<HTMLAttributes<HTMLTableElement>, "children
     onRowClick?: (row: T, index: number) => void;
     /** Shown when `data` is empty. */
     empty?: ReactNode;
+    /**
+     * The narrowest this table stays readable, and the switch that turns scrolling on.
+     *
+     * A fixed-layout table has no lower bound of its own, so seven columns in a 400px pane
+     * become seven clipped headers and a badge overflowing its cell. Below this width the
+     * table scrolls inside its own container instead of crushing — and setting the floor is
+     * the only way to ask for that, because a scroller with no floor has no defined moment to
+     * engage: under fixed layout the table always fits its container, and under auto layout it
+     * engages at whatever width the content happens to reach.
+     *
+     * The cost is the sticky header. An `overflow-x` container captures the stickiness
+     * `position: sticky` resolves against the page's own scroller, and CSS gives no way to
+     * scroll one axis while leaving the other visible — so a table without a floor keeps its
+     * sticky header, and one with a floor trades it.
+     */
+    minWidth?: number | string;
+}
+declare function Table<T>({ data, columns, rowKey, onRowClick, empty, minWidth, style, className, ...rest }: TableProps<T>): react_jsx_runtime.JSX.Element;
+
+interface Tab<T extends string> {
+    label: string;
+    value: T;
+    /** A small trailing count. Rendered muted, and omitted entirely when undefined. */
+    count?: number;
+}
+interface TabsProps<T extends string> extends Omit<HTMLAttributes<HTMLDivElement>, "onChange"> {
+    tabs: Tab<T>[];
+    value: T;
+    onChange: (value: T) => void;
+    /** Accessible name for the tab set — what these are facets OF. */
+    label?: string;
 }
-declare function Table<T>({ data, columns, rowKey, onRowClick, empty, style, className, ...rest }: TableProps<T>): react_jsx_runtime.JSX.Element;
+declare function Tabs<T extends string>({ tabs, value, onChange, label, style, className, onKeyDown: callerKeyDown, ...rest }: TabsProps<T>): react_jsx_runtime.JSX.Element;
 
 type ContentWidth = "reading" | "full";
 interface AppFrameProps extends HTMLAttributes<HTMLDivElement> {
@@ -233,6 +296,38 @@ declare const ListDetailLayout: typeof ListDetailLayoutRoot & {
     Back: typeof Back;
 };
 
+interface PageLayoutProps extends Omit<HTMLAttributes<HTMLDivElement>, "title"> {
+    /** The trail. Omit at the top level, which has nothing above it to name. */
+    crumbs?: Crumb[];
+    title: ReactNode;
+    /** Beside the title — typically a `Badge`. */
+    status?: ReactNode;
+    /** The far end of the title's row. */
+    actions?: ReactNode;
+    description?: ReactNode;
+    /** Lines the description is clamped to. `0` removes the clamp. */
+    descriptionLines?: number;
+    /**
+     * ONE tab bar, of the facets of whatever the title names. A `Tabs`.
+     *
+     * A slot rather than typed props because `Tabs` already has an API worth having, and
+     * wrapping it here would mean maintaining a second copy of it that drifts. What the layout
+     * owns is the bar's POSITION — under the header, above the content — which is the part
+     * apps get wrong.
+     */
+    tabs?: ReactNode;
+    /**
+     * Controls that narrow the content below: a search field, a status filter, a view toggle.
+     *
+     * Distinct from `tabs` on purpose. A tab changes which facet of one entity is shown; a
+     * toolbar reshapes a set within that facet. Rendering them as one row is how an app ends up
+     * with two identical-looking control strips whose difference nobody can see.
+     */
+    toolbar?: ReactNode;
+    children?: ReactNode;
+}
+declare function PageLayout({ crumbs, title, status, actions, description, descriptionLines, tabs, toolbar, children, style, ...rest }: PageLayoutProps): react_jsx_runtime.JSX.Element;
+
 type CollapseMode = "reflow" | "drawer";
 type Side = "left" | "right";
 interface SidebarState {
@@ -325,10 +420,13 @@ declare function Divider({ orientation, style, ...rest }: DividerProps): react_j
  * with no React re-render: the host swaps the `:root` vars and every `var()`
  * re-resolves.
  *
- * The fallbacks are deliberately **neutral** (system fonts, neutral grays, a
- * generic blue) — NOT NimbleBrain brand. Brand arrives by injection when the
- * app runs inside the NimbleBrain host; standalone/static renders get a sane
+ * The fallbacks are deliberately **unbranded** — system fonts, neutral grays, a
+ * generic blue, and generic semantic hues for the status channels. NOT
+ * NimbleBrain brand. Brand arrives by injection when the app runs inside the
+ * NimbleBrain host; standalone/static renders get a sane
  * unbranded default. This keeps the library host-agnostic.
+ * `__tests__/ui/tokens.test.ts` holds the line: every hex in these fallbacks
+ * must be in the sanctioned set, same as `theme-defaults.ts`.
  *
  * Components import the static `tokens` object and style with CSS `var()`, so
  * theming (incl. light/dark) resolves in CSS with no re-render.
@@ -350,14 +448,12 @@ declare const tokens: {
     readonly danger: "var(--nb-color-danger, #dc2626)";
     readonly success: "var(--nb-color-success, #059669)";
     readonly warning: "var(--nb-color-warning, #f59e0b)";
-    readonly warm: "var(--nb-color-warm, #d4620a)";
-    readonly warmLight: "var(--nb-color-warm-light, #fef5ee)";
     readonly processing: "var(--nb-color-processing, #7c3aed)";
     readonly processingLight: "var(--nb-color-processing-light, #f3eeff)";
     readonly infoLight: "var(--nb-color-info-light, #eef4ff)";
     readonly fontSans: "var(--font-sans, system-ui, -apple-system, BlinkMacSystemFont, sans-serif)";
     readonly fontMono: "var(--font-mono, ui-monospace, SFMono-Regular, Menlo, monospace)";
-    readonly fontHeading: "var(--nb-font-heading, Georgia, 'Times New Roman', serif)";
+    readonly fontHeading: "var(--nb-font-heading, system-ui, -apple-system, BlinkMacSystemFont, sans-serif)";
     readonly weightNormal: "var(--font-weight-normal, 400)";
     readonly weightMedium: "var(--font-weight-medium, 500)";
     readonly weightSemibold: "var(--font-weight-semibold, 600)";
@@ -404,7 +500,24 @@ interface TextProps extends Omit<HTMLAttributes<HTMLElement>, "color"> {
     weight?: Weight;
     tone?: Tone;
     mono?: boolean;
-    /** Single-line ellipsis truncation. */
+    /**
+     * Single-line ellipsis truncation.
+     *
+     * Sets `display: block` alongside the ellipsis rules, and that is load-bearing rather
+     * than incidental: `overflow` and `text-overflow` do not apply to a non-replaced INLINE
+     * box, so on the default `<span>` the only declaration that survived was
+     * `white-space: nowrap` — and the prop did the exact opposite of its name, making text
+     * unwrappable instead of clipping it. Inside an auto-layout `<table>` that widened the
+     * column to the full string and pushed every later column off the pane.
+     *
+     * `min-width: 0` comes with it so the box can actually shrink as a flex item; without it
+     * a truncating `Text` inside `Inline`/`Stack` refuses to go below its content width and
+     * pushes its container instead, which is the same bug one layer out.
+     *
+     * A truncating cell in a `Table` also needs its column to declare a `width` — see
+     * `Column.width`. Auto table layout sizes to content, so the ellipsis has nothing to
+     * clip against until some column is pinned.
+     */
     truncate?: boolean;
     as?: ElementType;
     children?: ReactNode;
@@ -421,4 +534,4 @@ interface HeadingProps extends Omit<HTMLAttributes<HTMLHeadingElement>, "color">
 /** Display heading using the heading font slot. Defaults to md, semibold. */
 declare function Heading({ size, weight, tone, as: As, style, children, ...rest }: HeadingProps): react_jsx_runtime.JSX.Element;
 
-export { AppFrame, Avatar, Badge, type BadgeTone, Button, Card, type Column, Divider, Drawer, EmptyState, Heading, type HeadingSize, Inline, ListDetailLayout, ListRow, Pagination, Prose, SearchField, SegmentedControl, SidebarLayout, Spacer, Spinner, Stack, type Status, StatusDot, Table, Text, TextLink, type TextSize, type Tokens, headingStyle, textStyle, tokens, useBreakpoint, useListDetail, useSidebar };
+export { AppFrame, Avatar, Badge, type BadgeTone, Breadcrumb, Button, Card, type Column, type Crumb, Divider, Drawer, EmptyState, Heading, type HeadingSize, Inline, ListDetailLayout, ListRow, PageHeader, PageLayout, Pagination, Prose, SearchField, SegmentedControl, SidebarLayout, Spacer, Spinner, Stack, type Status, StatusDot, Table, Tabs, Text, TextLink, type TextSize, type Tokens, headingStyle, textStyle, tokens, useBreakpoint, useListDetail, useSidebar };