@nimblebrain/synapse 0.8.0 → 0.10.0

package/dist/ui/index.d.cts

@@ -0,0 +1,424 @@
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import { HTMLAttributes, ReactNode, ButtonHTMLAttributes, DialogHTMLAttributes, InputHTMLAttributes, RefObject, CSSProperties, ElementType } from 'react';
+
+interface AvatarProps extends Omit<HTMLAttributes<HTMLSpanElement>, "children"> {
+    /** Name used for initials and the image alt text. */
+    name: string;
+    /** Optional image URL; falls back to initials when absent or on error. */
+    src?: string;
+    /** Diameter in px. Default 28. */
+    size?: number;
+}
+declare function Avatar({ name, src, size, style, ...rest }: AvatarProps): react_jsx_runtime.JSX.Element;
+
+type BadgeTone = "neutral" | "accent" | "success" | "warning" | "danger" | "processing" | "warm";
+interface BadgeProps extends HTMLAttributes<HTMLSpanElement> {
+    tone?: BadgeTone;
+    children?: ReactNode;
+}
+declare function Badge({ tone, style, children, ...rest }: BadgeProps): react_jsx_runtime.JSX.Element;
+
+type Variant = "primary" | "secondary" | "ghost";
+type Size = "sm" | "md";
+interface ButtonProps extends ButtonHTMLAttributes<HTMLButtonElement> {
+    variant?: Variant;
+    size?: Size;
+    children?: ReactNode;
+}
+declare function Button({ variant, size, style, className, children, ...rest }: ButtonProps): react_jsx_runtime.JSX.Element;
+interface TextLinkProps extends ButtonHTMLAttributes<HTMLButtonElement> {
+    /** Resting tone. Hover always moves toward `accent` (or `danger`). */
+    tone?: "muted" | "default" | "danger";
+    children?: ReactNode;
+}
+/** A chrome-less text button — for back / delete / retry affordances. */
+declare function TextLink({ tone, style, className, children, ...rest }: TextLinkProps): react_jsx_runtime.JSX.Element;
+
+interface CardProps extends HTMLAttributes<HTMLDivElement> {
+    /** Inner padding (CSS length or px number). Default `0.875rem`. */
+    padding?: number | string;
+    /** Lift on hover — for clickable cards. */
+    interactive?: boolean;
+    children?: ReactNode;
+}
+declare function Card({ padding, interactive, style, className, children, ...rest }: CardProps): react_jsx_runtime.JSX.Element;
+
+type Side$1 = "left" | "right" | "bottom";
+interface DrawerProps extends Omit<DialogHTMLAttributes<HTMLDialogElement>, "title" | "onCancel" | "onClick"> {
+    open: boolean;
+    /** Called by the backdrop and the Header close button. */
+    onClose: () => void;
+    /** Called on Escape. Defaults to `onClose` — override to do something else
+     * (e.g. pop one level of a panel stack before closing). */
+    onEscape?: () => void;
+    side?: Side$1;
+    /** Panel width (ignored for `side="bottom"`, which is full width). Default 480. */
+    width?: number | string;
+    children?: ReactNode;
+}
+declare function DrawerRoot({ open, onClose, onEscape, side, width, style, children, ...rest }: DrawerProps): react_jsx_runtime.JSX.Element;
+interface HeaderProps extends Omit<HTMLAttributes<HTMLElement>, "title"> {
+    /**
+     * Heading text — rendered as an `<h2>` and wired as the drawer's accessible
+     * name. Renders **instead of** `children` (pass one or the other, not both).
+     */
+    title?: ReactNode;
+    /** Show a leading back button (e.g. pop one level of a panel stack). */
+    onBack?: () => void;
+    /** Trailing controls placed before the close button. */
+    actions?: ReactNode;
+    /** Show a close button that calls this. */
+    onClose?: () => void;
+    children?: ReactNode;
+}
+declare function Header$1({ title, onBack, actions, onClose, style, children, ...rest }: HeaderProps): react_jsx_runtime.JSX.Element;
+declare function Body$1({ style, children, ...rest }: HTMLAttributes<HTMLDivElement>): react_jsx_runtime.JSX.Element;
+declare function Footer$1({ style, children, ...rest }: HTMLAttributes<HTMLElement>): react_jsx_runtime.JSX.Element;
+/** `Drawer` with `.Header`, `.Body`, `.Footer` slots. */
+declare const Drawer: typeof DrawerRoot & {
+    Header: typeof Header$1;
+    Body: typeof Body$1;
+    Footer: typeof Footer$1;
+};
+
+interface EmptyStateProps extends Omit<HTMLAttributes<HTMLDivElement>, "title"> {
+    icon?: ReactNode;
+    title?: ReactNode;
+    description?: ReactNode;
+    action?: ReactNode;
+}
+declare function EmptyState({ icon, title, description, action, style, ...rest }: EmptyStateProps): react_jsx_runtime.JSX.Element;
+
+interface ListRowProps extends Omit<HTMLAttributes<HTMLDivElement>, "title"> {
+    title: ReactNode;
+    /** Secondary line under the title. */
+    meta?: ReactNode;
+    /** Leading slot — e.g. a StatusDot or Avatar. */
+    leading?: ReactNode;
+    /** Trailing slot — e.g. a timestamp or actions. */
+    trailing?: ReactNode;
+    /** Enables pointer cursor + hover tint. */
+    interactive?: boolean;
+}
+declare function ListRow({ title, meta, leading, trailing, interactive, style, className, ...rest }: ListRowProps): react_jsx_runtime.JSX.Element;
+
+interface PaginationProps extends Omit<HTMLAttributes<HTMLDivElement>, "onChange"> {
+    /** Current page, 1-based. */
+    page: number;
+    /** Total number of pages. */
+    pageCount: number;
+    onChange: (page: number) => void;
+}
+declare function Pagination({ page, pageCount, onChange, style, ...rest }: PaginationProps): react_jsx_runtime.JSX.Element;
+
+interface ProseProps extends Omit<HTMLAttributes<HTMLDivElement>, "children" | "dangerouslySetInnerHTML"> {
+    /** Trusted, pre-sanitized HTML string. */
+    html?: string;
+    children?: ReactNode;
+}
+declare function Prose({ html, children, className, ...rest }: ProseProps): react_jsx_runtime.JSX.Element;
+
+interface SearchFieldProps extends InputHTMLAttributes<HTMLInputElement> {
+    variant?: "underline" | "boxed";
+}
+declare function SearchField({ variant, style, className, type, ...rest }: SearchFieldProps): react_jsx_runtime.JSX.Element;
+
+interface Option<T extends string> {
+    label: string;
+    value: T;
+}
+interface SegmentedControlProps<T extends string> extends Omit<HTMLAttributes<HTMLDivElement>, "onChange"> {
+    options: Option<T>[];
+    value: T;
+    onChange: (value: T) => void;
+}
+declare function SegmentedControl<T extends string>({ options, value, onChange, style, className, ...rest }: SegmentedControlProps<T>): react_jsx_runtime.JSX.Element;
+
+interface SpinnerProps extends HTMLAttributes<HTMLSpanElement> {
+    /** Diameter in px. Default 16. */
+    size?: number;
+    /** Arc color. Defaults to the accent token. */
+    color?: string;
+}
+declare function Spinner({ size, color, style, className, ...rest }: SpinnerProps): react_jsx_runtime.JSX.Element;
+
+type Status = "working" | "completed" | "failed" | "idle";
+interface StatusDotProps extends Omit<HTMLAttributes<HTMLSpanElement>, "color"> {
+    status?: Status;
+    /** Override the dot color (any CSS color / token). */
+    color?: string;
+    /** Diameter in px. Default 8. */
+    size?: number;
+}
+declare function StatusDot({ status, color, size, style, className, ...rest }: StatusDotProps): react_jsx_runtime.JSX.Element;
+
+type Align$1 = "left" | "right" | "center";
+interface Column<T> {
+    /** Stable column id. */
+    key: string;
+    header: ReactNode;
+    /** Cell content for a row. */
+    render: (row: T, index: number) => ReactNode;
+    align?: Align$1;
+    width?: number | string;
+}
+interface TableProps<T> extends Omit<HTMLAttributes<HTMLTableElement>, "children"> {
+    data: T[];
+    columns: Column<T>[];
+    /** Stable key per row. */
+    rowKey: (row: T, index: number) => string | number;
+    onRowClick?: (row: T, index: number) => void;
+    /** Shown when `data` is empty. */
+    empty?: ReactNode;
+}
+declare function Table<T>({ data, columns, rowKey, onRowClick, empty, style, className, ...rest }: TableProps<T>): react_jsx_runtime.JSX.Element;
+
+type ContentWidth = "reading" | "full";
+interface AppFrameProps extends HTMLAttributes<HTMLDivElement> {
+    contentWidth?: ContentWidth;
+    children?: ReactNode;
+}
+declare function AppFrameRoot({ contentWidth, style, children, ...rest }: AppFrameProps): react_jsx_runtime.JSX.Element;
+declare function Header({ style, children, ...rest }: HTMLAttributes<HTMLElement>): react_jsx_runtime.JSX.Element;
+interface BodyProps extends HTMLAttributes<HTMLDivElement> {
+    /**
+     * Host a full-bleed body layout (SidebarLayout, BoardLayout) edge-to-edge:
+     * no padding, no reading column, and the body itself doesn't scroll — the
+     * layout's panes manage their own scroll. Leave off for plain content
+     * (lists, forms), which get the padded reading/full column.
+     */
+    bleed?: boolean;
+}
+declare function Body({ bleed, style, children, ...rest }: BodyProps): react_jsx_runtime.JSX.Element;
+declare function Footer({ style, children, ...rest }: HTMLAttributes<HTMLElement>): react_jsx_runtime.JSX.Element;
+/** `AppFrame` with `.Header`, `.Body`, `.Footer` slots. */
+declare const AppFrame: typeof AppFrameRoot & {
+    Header: typeof Header;
+    Body: typeof Body;
+    Footer: typeof Footer;
+};
+
+interface ListDetailState {
+    collapsed: boolean;
+    selected: boolean;
+    listWidth: number | string;
+    onBack?: () => void;
+}
+/** Read the list/detail responsive state — for custom back affordances. */
+declare function useListDetail(): ListDetailState;
+interface ListDetailLayoutProps extends HTMLAttributes<HTMLDivElement> {
+    /** Is a detail open? Drives which pane shows on a narrow layout. */
+    selected?: boolean;
+    /** Called by `Back` (and custom triggers) to return to the list when narrow. */
+    onBack?: () => void;
+    /** Master list width when side-by-side. Default 320. */
+    listWidth?: number | string;
+    /** Collapse to one-at-a-time below this layout width (px). Default 720. */
+    breakpoint?: number;
+    children?: ReactNode;
+}
+declare function ListDetailLayoutRoot({ selected, onBack, listWidth, breakpoint, style, children, ...rest }: ListDetailLayoutProps): react_jsx_runtime.JSX.Element;
+declare function List({ style, children, ...rest }: HTMLAttributes<HTMLElement>): react_jsx_runtime.JSX.Element | null;
+declare function Detail({ style, children, ...rest }: HTMLAttributes<HTMLDivElement>): react_jsx_runtime.JSX.Element | null;
+interface BackProps {
+    children?: ReactNode;
+    style?: React.CSSProperties;
+}
+/** "← Back" affordance — renders only on a narrow pane with a detail open. */
+declare function Back({ children, style }: BackProps): react_jsx_runtime.JSX.Element | null;
+/** `ListDetailLayout` with `.List`, `.Detail`, and `.Back` slots. */
+declare const ListDetailLayout: typeof ListDetailLayoutRoot & {
+    List: typeof List;
+    Detail: typeof Detail;
+    Back: typeof Back;
+};
+
+type CollapseMode = "reflow" | "drawer";
+type Side = "left" | "right";
+interface SidebarState {
+    collapsed: boolean;
+    mode: CollapseMode;
+    side: Side;
+    width: number | string;
+    open: boolean;
+    setOpen: (open: boolean) => void;
+}
+/** Read the sidebar's responsive state — for custom triggers or nav re-orientation. */
+declare function useSidebar(): SidebarState;
+interface SidebarLayoutProps extends HTMLAttributes<HTMLDivElement> {
+    side?: Side;
+    /** Expanded rail / drawer width. Default 240. */
+    width?: number | string;
+    /** Collapse below this pane width (px). Default 640. */
+    breakpoint?: number;
+    collapseMode?: CollapseMode;
+    children?: ReactNode;
+}
+declare function SidebarLayoutRoot({ side, width, breakpoint, collapseMode, style, children, ...rest }: SidebarLayoutProps): react_jsx_runtime.JSX.Element;
+declare function Sidebar({ style, children, ...rest }: HTMLAttributes<HTMLElement>): react_jsx_runtime.JSX.Element;
+declare function Main({ style, children, ...rest }: HTMLAttributes<HTMLDivElement>): react_jsx_runtime.JSX.Element;
+interface TriggerProps extends ButtonHTMLAttributes<HTMLButtonElement> {
+    /** Override the default hamburger glyph. */
+    children?: ReactNode;
+}
+/**
+ * Hamburger that opens the drawer. Renders only when collapsed in `drawer`
+ * mode, and only when it can see a `SidebarLayout` context — so it's safe to
+ * place anywhere inside the layout subtree (it no-ops elsewhere). Note: in v1
+ * the context lives on `SidebarLayout` itself, so the trigger must sit inside
+ * it (e.g. a toolbar in `Main`), not in a sibling `AppFrame.Header`.
+ */
+declare function Trigger({ children, style, onClick, ...rest }: TriggerProps): react_jsx_runtime.JSX.Element | null;
+/** `SidebarLayout` with `.Sidebar`, `.Main`, and `.Trigger` slots. */
+declare const SidebarLayout: typeof SidebarLayoutRoot & {
+    Sidebar: typeof Sidebar;
+    Main: typeof Main;
+    Trigger: typeof Trigger;
+};
+
+/**
+ * `useBreakpoint` — responsive hook keyed to an element's OWN width, not the
+ * device viewport. Synapse apps render in an iframe pane whose width the host
+ * controls (fullscreen, split, or a narrow sidebar), so layouts must react to
+ * the space they're actually given.
+ *
+ * Attach the returned `ref` to the element whose width drives the decision.
+ * Width is measured synchronously on mount (no first-frame flash) and kept live
+ * via `ResizeObserver`. SSR/test-safe: without a DOM/`ResizeObserver` it simply
+ * reports `isNarrow: false`.
+ */
+
+declare function useBreakpoint<T extends HTMLElement = HTMLDivElement>(breakpoint: number): {
+    ref: RefObject<T | null>;
+    isNarrow: boolean;
+};
+
+type Align = "start" | "center" | "end" | "stretch" | "baseline";
+type Justify = "start" | "center" | "end" | "between" | "around";
+interface FlexProps extends HTMLAttributes<HTMLDivElement> {
+    gap?: number | string;
+    align?: Align;
+    justify?: Justify;
+    wrap?: boolean;
+    children?: ReactNode;
+}
+/** Vertical flex container with `gap`. Defaults to `align: stretch`. */
+declare function Stack({ gap, align, justify, wrap, style, children, ...rest }: FlexProps): react_jsx_runtime.JSX.Element;
+/** Horizontal flex container with `gap`. Defaults to `align: center`. */
+declare function Inline({ gap, align, justify, wrap, style, children, ...rest }: FlexProps): react_jsx_runtime.JSX.Element;
+/** Flexible gap that pushes siblings apart inside a `Stack`/`Inline`. */
+declare function Spacer({ style, ...rest }: HTMLAttributes<HTMLDivElement>): react_jsx_runtime.JSX.Element;
+interface DividerProps extends HTMLAttributes<HTMLDivElement> {
+    orientation?: "horizontal" | "vertical";
+}
+/** A hairline rule using the border token. Horizontal by default. Decorative
+ * (`aria-hidden`) — it's a visual divider, not a focusable/valued separator. */
+declare function Divider({ orientation, style, ...rest }: DividerProps): react_jsx_runtime.JSX.Element;
+
+/**
+ * The token contract for `@nimblebrain/synapse/ui`.
+ *
+ * Values are NOT brand hexes — they are `var(--token, fallback)` references to
+ * the CSS custom properties the host injects into the app iframe (the MCP
+ * ext-apps `hostContext.styles.variables`). Because styling resolves through
+ * CSS variables, theme changes (including light↔dark) reflect automatically
+ * 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
+ * unbranded default. This keeps the library host-agnostic.
+ *
+ * Components import the static `tokens` object and style with CSS `var()`, so
+ * theming (incl. light/dark) resolves in CSS with no re-render.
+ */
+
+/** Resolved design tokens as CSS `var()` references with neutral fallbacks. */
+declare const tokens: {
+    readonly bg: "var(--color-background-primary, #ffffff)";
+    readonly bgRaised: "var(--color-background-secondary, #fafafa)";
+    readonly bgSubtle: "var(--color-background-tertiary, #f3f4f6)";
+    readonly fg: "var(--color-text-primary, #111827)";
+    readonly fgMuted: "var(--color-text-secondary, #6b7280)";
+    readonly fgFaint: "var(--color-text-tertiary, #9ca3af)";
+    readonly accent: "var(--color-text-accent, #2563eb)";
+    readonly accentFg: "var(--nb-color-accent-foreground, #ffffff)";
+    readonly border: "var(--color-border-primary, #e5e7eb)";
+    readonly borderStrong: "var(--color-border-secondary, #d1d5db)";
+    readonly ring: "var(--color-ring-primary, #2563eb)";
+    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 weightNormal: "var(--font-weight-normal, 400)";
+    readonly weightMedium: "var(--font-weight-medium, 500)";
+    readonly weightSemibold: "var(--font-weight-semibold, 600)";
+    readonly weightBold: "var(--font-weight-bold, 700)";
+    readonly textXsSize: "var(--font-text-xs-size, 0.75rem)";
+    readonly textXsLine: "var(--font-text-xs-line-height, 1rem)";
+    readonly textSmSize: "var(--font-text-sm-size, 0.875rem)";
+    readonly textSmLine: "var(--font-text-sm-line-height, 1.25rem)";
+    readonly textBaseSize: "var(--font-text-base-size, 1rem)";
+    readonly textBaseLine: "var(--font-text-base-line-height, 1.5rem)";
+    readonly textLgSize: "var(--font-text-lg-size, 1.125rem)";
+    readonly textLgLine: "var(--font-text-lg-line-height, 1.75rem)";
+    readonly headingSmSize: "var(--font-heading-sm-size, 1.25rem)";
+    readonly headingSmLine: "var(--font-heading-sm-line-height, 1.75rem)";
+    readonly headingMdSize: "var(--font-heading-md-size, 1.5rem)";
+    readonly headingMdLine: "var(--font-heading-md-line-height, 2rem)";
+    readonly headingLgSize: "var(--font-heading-lg-size, 2rem)";
+    readonly headingLgLine: "var(--font-heading-lg-line-height, 2.5rem)";
+    readonly radiusXs: "var(--border-radius-xs, 0.25rem)";
+    readonly radiusSm: "var(--border-radius-sm, 0.5rem)";
+    readonly radiusMd: "var(--border-radius-md, 0.75rem)";
+    readonly radiusLg: "var(--border-radius-lg, 1rem)";
+    readonly radiusXl: "var(--border-radius-xl, 1.5rem)";
+    readonly borderWidth: "var(--border-width-regular, 1px)";
+    readonly shadowHairline: "var(--shadow-hairline, 0 0 0 1px rgba(0,0,0,0.06))";
+    readonly shadowSm: "var(--shadow-sm, 0 1px 2px rgba(0,0,0,0.05))";
+    readonly shadowMd: "var(--shadow-md, 0 4px 6px -1px rgba(0,0,0,0.1))";
+    readonly shadowLg: "var(--shadow-lg, 0 10px 15px -3px rgba(0,0,0,0.1))";
+};
+type Tokens = typeof tokens;
+/** Body text sizes. */
+type TextSize = "xs" | "sm" | "base" | "lg";
+/** Heading sizes. */
+type HeadingSize = "sm" | "md" | "lg";
+/** `{ fontSize, lineHeight }` for a body-text level. */
+declare function textStyle(size: TextSize): CSSProperties;
+/** `{ fontSize, lineHeight }` for a heading level. */
+declare function headingStyle(size: HeadingSize): CSSProperties;
+
+type Tone = "default" | "muted" | "faint" | "accent" | "danger" | "success";
+type Weight = "normal" | "medium" | "semibold" | "bold";
+interface TextProps extends Omit<HTMLAttributes<HTMLElement>, "color"> {
+    size?: TextSize;
+    weight?: Weight;
+    tone?: Tone;
+    mono?: boolean;
+    /** Single-line ellipsis truncation. */
+    truncate?: boolean;
+    as?: ElementType;
+    children?: ReactNode;
+}
+/** Body text. Defaults to base size, normal weight, primary tone, sans font. */
+declare function Text({ size, weight, tone, mono, truncate, as: As, style, children, ...rest }: TextProps): react_jsx_runtime.JSX.Element;
+interface HeadingProps extends Omit<HTMLAttributes<HTMLHeadingElement>, "color"> {
+    size?: HeadingSize;
+    weight?: Weight;
+    tone?: Tone;
+    as?: ElementType;
+    children?: ReactNode;
+}
+/** 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 };