@k2b/ui 0.1.0-rc.0 → 0.1.0

package/dist/types/actions/Button.d.ts

@@ -0,0 +1,38 @@
+import { type LinkNavigateEvent, type NavigationScrollMode } from "@k2b/ssr/nav";
+import { type JSX } from "solid-js";
+import { type TooltipPlacement } from "../feedback/Tooltip";
+export type ButtonVariant = "primary" | "secondary" | "ghost" | "text" | "subtle" | "input" | "warning" | "danger" | "success" | "ai";
+export type ButtonSize = "xs" | "sm" | "md" | "lg";
+export type ButtonProps = JSX.ButtonHTMLAttributes<HTMLButtonElement> & {
+    loading?: boolean;
+    loadingLabel?: string;
+    size?: ButtonSize;
+    variant?: ButtonVariant;
+    tooltip?: JSX.Element | false;
+    tooltipDelay?: number;
+    tooltipPlacement?: TooltipPlacement;
+};
+export type ButtonLinkProps = Omit<JSX.AnchorHTMLAttributes<HTMLAnchorElement>, "onClick"> & {
+    navigation?: "document" | "enhanced";
+    onClick?: JSX.EventHandlerUnion<HTMLAnchorElement, MouseEvent>;
+    onNavigate?: (event: LinkNavigateEvent) => void | Promise<void>;
+    replace?: boolean;
+    scroll?: NavigationScrollMode;
+    size?: ButtonSize;
+    variant?: ButtonVariant;
+    tooltip?: JSX.Element | false;
+    tooltipDelay?: number;
+    tooltipPlacement?: TooltipPlacement;
+};
+export declare function Button(props: ButtonProps): JSX.Element;
+export declare function ButtonLink(props: ButtonLinkProps): JSX.Element;
+export type IconButtonProps = Omit<ButtonProps, "children"> & {
+    children: JSX.Element;
+    label: string;
+};
+export type IconButtonLinkProps = Omit<ButtonLinkProps, "children"> & {
+    children: JSX.Element;
+    label: string;
+};
+export declare function IconButton(props: IconButtonProps): JSX.Element;
+export declare function IconButtonLink(props: IconButtonLinkProps): JSX.Element;

package/dist/types/actions/ContextMenu.d.ts

@@ -0,0 +1,17 @@
+import { type JSX } from "solid-js";
+import { type DropdownItem } from "./Dropdown";
+export type ContextMenuProps = {
+    items: readonly DropdownItem[];
+    children: JSX.Element;
+    class?: string | ((isOpen: boolean) => string);
+    /** Tab order of the context-menu host. Descendant-focused composite widgets use -1. */
+    tabIndex?: number;
+    disabled?: boolean;
+    onClose?: () => void;
+    onOpen?: () => void;
+    id?: string;
+    label?: string;
+};
+/** Right-click menu with keyboard invocation, one-open-at-a-time behavior, and viewport clamping. */
+export declare function ContextMenu(props: ContextMenuProps): JSX.Element;
+export default ContextMenu;

package/dist/types/actions/CopyButton.d.ts

@@ -0,0 +1,20 @@
+import { type JSX } from "solid-js";
+import { type ButtonProps } from "./Button";
+export type CopyButtonValue = {
+    text: string;
+    value?: string;
+} | {
+    text?: string;
+    value: string;
+};
+export type CopyButtonProps = CopyButtonValue & Omit<ButtonProps, "children" | "onClick"> & {
+    label?: string;
+    copiedLabel?: string;
+    iconOnly?: boolean;
+    onCopied?: () => void;
+    onCopyError?: (error: unknown) => void;
+    resetAfter?: number;
+};
+export declare function copyText(text: string, onCopyError?: (error: unknown) => void, copy?: (text: string) => Promise<void>): Promise<void>;
+export declare function CopyButton(props: CopyButtonProps): JSX.Element;
+export default CopyButton;

package/dist/types/actions/Disclosure.d.ts

@@ -0,0 +1,15 @@
+import { type JSX } from "solid-js";
+import type { MaybeAccessor } from "../inputs/field-contract";
+export type DisclosureProps = {
+    summary: JSX.Element;
+    children: JSX.Element;
+    value?: MaybeAccessor<boolean>;
+    defaultValue?: boolean;
+    onValueChange?: (value: boolean) => void;
+    icon?: string;
+    disabled?: boolean;
+    class?: string;
+};
+/** Native disclosure with the same value/onValueChange vocabulary as other controls. */
+export declare function Disclosure(props: DisclosureProps): JSX.Element;
+export default Disclosure;

package/dist/types/actions/Dropdown.d.ts

@@ -0,0 +1,100 @@
+import { type JSX } from "solid-js";
+import { type TooltipPlacement } from "../feedback/Tooltip";
+import { type ButtonProps, type ButtonSize, type ButtonVariant } from "./Button";
+export type DropdownPosition = "bottom-right" | "bottom-left" | "top-right" | "top-left" | "right-start";
+export type DropdownActionBase = {
+    class?: string;
+    disabled?: boolean;
+    icon?: string;
+    image?: string;
+    label: string;
+    description?: string;
+    variant?: "danger";
+};
+export type DropdownAction = (DropdownActionBase & {
+    action: () => void;
+    href?: never;
+    external?: never;
+}) | (DropdownActionBase & {
+    href: string;
+    external?: boolean;
+    action?: never;
+}) | (DropdownActionBase & {
+    disabled: true;
+    action?: never;
+    href?: never;
+    external?: never;
+});
+/** Declarative radio or checkbox row for compact action menus. */
+export type DropdownChoice = DropdownActionBase & {
+    action: () => void;
+    checked: boolean | (() => boolean);
+    choice: "checkbox" | "radio";
+    closeOnSelect?: boolean;
+    color?: string;
+};
+export type DropdownSection = {
+    sectionLabel?: string;
+    items: readonly (DropdownAction | DropdownChoice)[];
+};
+export type DropdownItem = DropdownAction | DropdownChoice | DropdownSection;
+export type DropdownProps = {
+    items: readonly DropdownItem[];
+    children: JSX.Element;
+    position?: DropdownPosition | (() => DropdownPosition);
+    /** Menu width as a CSS length. Defaults to `12rem`. */
+    width?: string;
+    class?: string;
+    menuClass?: string;
+    onClose?: () => void;
+    open?: boolean;
+    onOpenChange?: (open: boolean) => void;
+    disabled?: boolean;
+    label?: string;
+    align?: "start" | "end";
+};
+export type DropdownTriggerProps = Omit<ButtonProps, "aria-controls" | "aria-expanded" | "aria-haspopup" | "children" | "disabled" | "onClick" | "onKeyDown"> & {
+    children: JSX.Element;
+    /** Use `plain` when a specialized component class owns the complete visual treatment. */
+    appearance?: "button" | "plain";
+    disabled?: boolean;
+    iconOnly?: boolean;
+    label?: string;
+    size?: ButtonSize;
+    tooltip?: JSX.Element | false;
+    tooltipDelay?: number;
+    tooltipPlacement?: TooltipPlacement;
+    variant?: ButtonVariant;
+};
+export type DropdownItemProps = {
+    children: JSX.Element;
+    icon?: string;
+    image?: string;
+    description?: string;
+    disabled?: boolean;
+    danger?: boolean;
+    variant?: "danger";
+    href?: string;
+    external?: boolean;
+    onSelect?: () => void;
+    class?: string;
+};
+export declare const dropdownPosition: (trigger: DOMRect, menu: Pick<DOMRect, "width" | "height">, position: DropdownPosition, viewport: {
+    width: number;
+    height: number;
+}, gap?: number) => {
+    left: number;
+    top: number;
+};
+export declare function DropdownItem(props: DropdownItemProps): JSX.Element;
+export declare function DropdownItems(props: {
+    items: readonly DropdownItem[];
+    close: (restoreFocus?: boolean) => void;
+}): JSX.Element;
+type DropdownComponent = ((props: DropdownProps) => JSX.Element) & {
+    Root: (props: DropdownProps) => JSX.Element;
+    Trigger: (props: DropdownTriggerProps) => JSX.Element;
+    Item: (props: DropdownItemProps) => JSX.Element;
+};
+export declare const Dropdown: DropdownComponent;
+export default Dropdown;

package/dist/types/actions/FilterChip.d.ts

@@ -0,0 +1,27 @@
+import { type JSX } from "solid-js";
+export type FilterChipOption = {
+    value: string;
+    label: string;
+    icon?: string;
+    color?: string;
+};
+export type FilterChipSection = {
+    label?: string;
+    options: readonly FilterChipOption[];
+    multiple?: boolean;
+};
+export type FilterChipProps = {
+    label: string;
+    icon: string;
+    options: readonly FilterChipSection[];
+    value: readonly string[];
+    onValueChange: (value: string[]) => void;
+    isActive?: boolean;
+    position?: "bottom-left" | "bottom-right";
+    defaultValue?: readonly string[];
+    iconOnly?: boolean;
+    class?: string;
+};
+/** Section-aware controlled filter with immediate single- and multi-select commits. */
+export declare function FilterChip(props: FilterChipProps): JSX.Element;
+export default FilterChip;

package/dist/types/actions/RemoveButton.d.ts

@@ -0,0 +1,7 @@
+import { type JSX } from "solid-js";
+export type RemoveButtonProps = Omit<JSX.ButtonHTMLAttributes<HTMLButtonElement>, "aria-label" | "children"> & {
+    ariaLabel: string;
+    loading?: boolean;
+};
+export declare function RemoveButton(props: RemoveButtonProps): JSX.Element;
+export default RemoveButton;

package/dist/types/actions/SegmentedControl.d.ts

@@ -0,0 +1,20 @@
+import { type JSX } from "solid-js";
+export type SegmentOption<T extends string = string> = {
+    value: T;
+    label: JSX.Element;
+    icon?: string;
+    disabled?: boolean;
+};
+export type SegmentedControlProps<T extends string = string> = {
+    options: readonly SegmentOption<T>[];
+    value: T | (() => T);
+    onValueChange: (value: T) => void;
+    disabled?: boolean;
+    ariaLabel?: string;
+    label?: string;
+    size?: "sm" | "md";
+    class?: string;
+};
+/** Controlled radio group with automatic selection during arrow-key navigation. */
+export declare function SegmentedControl<T extends string = string>(props: SegmentedControlProps<T>): JSX.Element;
+export default SegmentedControl;

package/dist/types/actions/SplitButton.d.ts

@@ -0,0 +1,13 @@
+import { type JSX } from "solid-js";
+import { type ButtonProps } from "./Button";
+import { type DropdownItem, type DropdownPosition } from "./Dropdown";
+export type SplitButtonProps = ButtonProps & {
+    /** Actions shown from the secondary menu trigger. */
+    items: readonly DropdownItem[];
+    /** Accessible name and title for the icon-only menu trigger. */
+    menuLabel: string;
+    menuPosition?: DropdownPosition | (() => DropdownPosition);
+    menuWidth?: string;
+};
+/** One primary button action with a separate menu of related alternatives. */
+export declare function SplitButton(props: SplitButtonProps): JSX.Element;

package/dist/types/actions/SpotlightSearch.d.ts

@@ -0,0 +1,25 @@
+import type { JSX } from "solid-js";
+import type { PromptSearchInput, PromptSearchItem, PromptSearchOptions } from "../feedback/prompts";
+export declare const SPOTLIGHT_SHORTCUT = "mod+shift+k";
+export declare const SPOTLIGHT_SHORTCUT_LABEL = "\u21E7\u2318K";
+export declare const SPOTLIGHT_SHORTCUT_TITLE = "Mod+Shift+K";
+export type SpotlightSearchResolver<T = unknown> = (input: PromptSearchInput) => Promise<PromptSearchItem<T>[]> | PromptSearchItem<T>[];
+export type SpotlightSearchOptions<T = unknown> = PromptSearchOptions & {
+    resolve: SpotlightSearchResolver<T>;
+};
+export type SpotlightButtonVariant = "default" | "compact" | "chip" | "sidebar" | "sidebar-mobile" | "icon";
+export type SpotlightButtonProps = {
+    variant?: SpotlightButtonVariant;
+    label?: string;
+    title?: string;
+    icon?: string;
+    shortcutLabel?: string | false;
+    ariaLabel?: string;
+    disabled?: boolean;
+    class?: string;
+    onClick: () => void | Promise<void>;
+};
+export declare const isSpotlightShortcut: (event: KeyboardEvent) => boolean;
+export declare const openSpotlightSearch: <T = unknown>(options: SpotlightSearchOptions<T>) => Promise<PromptSearchItem<T> | undefined>;
+export declare function SpotlightButton(props: SpotlightButtonProps): JSX.Element;
+export default SpotlightButton;

package/dist/types/actions/Tabs.d.ts

@@ -0,0 +1,27 @@
+import { type JSX } from "solid-js";
+import type { MaybeAccessor } from "../inputs/field-contract";
+export type TabOption<T extends string = string> = {
+    value: T;
+    label: JSX.Element;
+    icon?: string;
+    disabled?: boolean;
+    panel?: JSX.Element;
+};
+export type TabsItemProps<T extends string = string> = Omit<TabOption<T>, "panel"> & {
+    children?: JSX.Element;
+};
+export type TabsProps<T extends string = string> = {
+    value: MaybeAccessor<T>;
+    onValueChange: (value: T) => void;
+    ariaLabel: string;
+    orientation?: "horizontal" | "vertical";
+    class?: string;
+    /** Data-driven alternative to colocated `Tabs.Item` children. */
+    options?: readonly TabOption<T>[];
+    children?: JSX.Element;
+};
+type TabsComponent = (<T extends string = string>(props: TabsProps<T>) => JSX.Element) & {
+    Item: <T extends string = string>(props: TabsItemProps<T>) => JSX.Element;
+};
+export declare const Tabs: TabsComponent;
+export default Tabs;

package/dist/types/actions/Toolbar.d.ts

@@ -0,0 +1,23 @@
+import { type JSX } from "solid-js";
+export type ToolbarProps = {
+    children: JSX.Element;
+    label: string;
+    orientation?: "horizontal" | "vertical";
+    wrap?: boolean;
+    class?: string;
+};
+export type ToolbarGroupProps = {
+    children: JSX.Element;
+    label?: string;
+    class?: string;
+};
+export type ToolbarSeparatorProps = {
+    class?: string;
+};
+type ToolbarComponent = ((props: ToolbarProps) => JSX.Element) & {
+    Group: (props: ToolbarGroupProps) => JSX.Element;
+    Separator: (props: ToolbarSeparatorProps) => JSX.Element;
+    Spacer: () => JSX.Element;
+};
+export declare const Toolbar: ToolbarComponent;
+export default Toolbar;

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

@@ -0,0 +1,24 @@
+export type { ButtonLinkProps, ButtonProps, ButtonSize, ButtonVariant, IconButtonLinkProps, IconButtonProps } from "./Button";
+export { Button, ButtonLink, IconButton, IconButtonLink } from "./Button";
+export type { CopyButtonProps, CopyButtonValue } from "./CopyButton";
+export { CopyButton } from "./CopyButton";
+export type { DisclosureProps } from "./Disclosure";
+export { Disclosure } from "./Disclosure";
+export type { DropdownAction, DropdownActionBase, DropdownChoice, DropdownItemProps, DropdownPosition, DropdownProps, DropdownSection, DropdownTriggerProps, } from "./Dropdown";
+export { Dropdown, DropdownItem, dropdownPosition } from "./Dropdown";
+export type { FilterChipOption, FilterChipProps, FilterChipSection } from "./FilterChip";
+export { FilterChip } from "./FilterChip";
+export type { ContextMenuProps } from "./ContextMenu";
+export { ContextMenu } from "./ContextMenu";
+export type { RemoveButtonProps } from "./RemoveButton";
+export { RemoveButton } from "./RemoveButton";
+export type { SpotlightButtonProps, SpotlightButtonVariant, SpotlightSearchOptions, SpotlightSearchResolver, } from "./SpotlightSearch";
+export { isSpotlightShortcut, openSpotlightSearch, SPOTLIGHT_SHORTCUT, SPOTLIGHT_SHORTCUT_LABEL, SPOTLIGHT_SHORTCUT_TITLE, SpotlightButton, } from "./SpotlightSearch";
+export type { SegmentedControlProps, SegmentOption } from "./SegmentedControl";
+export { SegmentedControl } from "./SegmentedControl";
+export type { SplitButtonProps } from "./SplitButton";
+export { SplitButton } from "./SplitButton";
+export type { TabOption, TabsItemProps, TabsProps } from "./Tabs";
+export { Tabs } from "./Tabs";
+export type { ToolbarGroupProps, ToolbarProps, ToolbarSeparatorProps } from "./Toolbar";
+export { Toolbar } from "./Toolbar";

package/dist/types/chat/ChatComposer.d.ts

@@ -0,0 +1,57 @@
+import { type JSX } from "solid-js";
+import type { ChatAction, ChatAttachment, ChatComposerState, ChatContextUsageData, ChatModelOption, ChatSubmitInput } from "./types";
+export type ChatCommandContext = {
+    setValue: (value: string) => void;
+    submit: () => void;
+    focus: () => void;
+};
+export type ChatCommand = {
+    name: string;
+    description: string;
+    icon?: string;
+    action: (context: ChatCommandContext) => void | Promise<void>;
+};
+export type ChatFileSelection = {
+    onSelect: (files: readonly File[]) => void | Promise<void>;
+    onError?: (error: unknown) => void;
+    accept?: string;
+    multiple?: boolean;
+    disabled?: boolean;
+    label?: string;
+};
+export type ChatPasteHandler = (event: ClipboardEvent & {
+    currentTarget: HTMLTextAreaElement;
+    target: Element;
+}) => void;
+export type ChatComposerProps = {
+    value: string;
+    onValueChange: (value: string) => void;
+    onSubmit: (input: ChatSubmitInput) => boolean | void | Promise<boolean | void>;
+    /** Submit intent used for drafts entered while a response is running. Defaults to `steer`. */
+    runningSubmitIntent?: "steer" | "queue";
+    onStop?: () => void | Promise<void>;
+    onError?: (error: unknown) => void;
+    state?: ChatComposerState;
+    attachments?: readonly ChatAttachment[];
+    onAttachmentsChange?: (attachments: readonly ChatAttachment[]) => void;
+    fileSelection?: ChatFileSelection;
+    /** Handle non-file clipboard content. Pasted files already use `fileSelection`. */
+    onPaste?: ChatPasteHandler;
+    menuActions?: readonly ChatAction[];
+    models?: readonly ChatModelOption[];
+    selectedModelId?: string | null;
+    onModelChange?: (modelId: string) => void;
+    commands?: readonly ChatCommand[];
+    contextUsage?: ChatContextUsageData;
+    contextActions?: readonly ChatAction[];
+    /** Additional compact controls rendered with the add/model controls. */
+    footerTools?: JSX.Element;
+    placeholder?: string;
+    label?: string;
+    inputLabel?: string;
+    disabled?: boolean;
+    error?: string;
+    focusToken?: unknown;
+    class?: string;
+};
+export declare function ChatComposer(props: ChatComposerProps): JSX.Element;

package/dist/types/chat/ChatPrimitives.d.ts

@@ -0,0 +1,48 @@
+import { type JSX } from "solid-js";
+import type { ChatAction, ChatActivityTone, ChatAttachment, ChatContextUsageData, ChatMessageStatus, ChatRole } from "./types";
+export type ChatMessageProps = {
+    role: ChatRole;
+    children?: JSX.Element;
+    label?: string;
+    createdAt?: string | Date;
+    timeLabel?: string;
+    status?: ChatMessageStatus;
+    attachments?: readonly ChatAttachment[];
+    actions?: readonly ChatAction[];
+    actionDisplay?: "auto" | "inline" | "menu";
+    anchorId?: string | number;
+    onActionError?: (error: unknown) => void;
+    class?: string;
+};
+export type ChatActivityProps = {
+    label: string;
+    description?: string;
+    icon?: string;
+    /** Optional host-owned leading visual rendered instead of the icon. */
+    leading?: JSX.Element;
+    /** Optional identity accent for the leading visual. Semantic tones still take precedence. */
+    accent?: string;
+    tone?: ChatActivityTone;
+    /** Marks the activity as running with the shared accent sweep. */
+    busy?: boolean;
+    trailing?: JSX.Element;
+    /** Controlled disclosure state. Omit to keep native details behavior. */
+    open?: boolean;
+    /** Reports disclosure changes when `open` is controlled by the host. */
+    onOpenChange?: (open: boolean) => void;
+    defaultOpen?: boolean;
+    /** Set to false when the body is a peer list that should align with the activity row. */
+    bodyInset?: boolean;
+    anchorId?: string | number;
+    children?: JSX.Element;
+    class?: string;
+};
+export type ChatContextUsageProps = ChatContextUsageData & {
+    /** Host-owned number formatting. The default is locale-independent and SSR-stable. */
+    formatNumber?: (value: number) => string;
+    class?: string;
+};
+export declare const formatChatTokens: (tokens: number) => string;
+export declare function ChatMessage(props: ChatMessageProps): JSX.Element;
+export declare function ChatActivity(props: ChatActivityProps): JSX.Element;
+export declare function ChatContextUsage(props: ChatContextUsageProps): JSX.Element;

package/dist/types/chat/ChatRoot.d.ts

@@ -0,0 +1,7 @@
+import type { JSX } from "solid-js";
+export type ChatRootProps = {
+    children: JSX.Element;
+    class?: string;
+    label?: string;
+};
+export declare function ChatRoot(props: ChatRootProps): JSX.Element;

package/dist/types/chat/ChatTimeline.d.ts

@@ -0,0 +1,52 @@
+import { type JSX } from "solid-js";
+import type { ChatAction, ChatActivityTone, ChatAttachment, ChatMessageStatus, ChatRole } from "./types";
+export type ChatMessageItem = {
+    kind: "message";
+    id: string;
+    role: ChatRole;
+    content?: JSX.Element;
+    label?: string;
+    createdAt?: string | Date;
+    timeLabel?: string;
+    status?: ChatMessageStatus;
+    attachments?: readonly ChatAttachment[];
+    actions?: readonly ChatAction[];
+    actionDisplay?: "auto" | "inline" | "menu";
+    anchorId?: string | number;
+    class?: string;
+};
+export type ChatActivityItem = {
+    kind: "activity";
+    id: string;
+    label: string;
+    description?: string;
+    icon?: string;
+    leading?: JSX.Element;
+    accent?: string;
+    tone?: ChatActivityTone;
+    busy?: boolean;
+    trailing?: JSX.Element;
+    defaultOpen?: boolean;
+    anchorId?: string | number;
+    content?: JSX.Element;
+    class?: string;
+};
+export type ChatTimelineItem = ChatMessageItem | ChatActivityItem;
+export type ChatTimelineProps = {
+    items: readonly ChatTimelineItem[];
+    conversationKey?: string | null;
+    loading?: boolean;
+    hasMore?: boolean;
+    loadingOlder?: boolean;
+    onLoadOlder?: () => boolean | void | Promise<boolean | void>;
+    emptyTitle?: string;
+    emptyDescription?: string;
+    navigation?: JSX.Element;
+    onActionError?: (error: unknown) => void;
+    viewportRef?: (element: HTMLDivElement) => void;
+    contentRef?: (element: HTMLDivElement) => void;
+    label?: string;
+    followThreshold?: number;
+    class?: string;
+};
+export declare function ChatTimeline(props: ChatTimelineProps): JSX.Element;

package/dist/types/chat/chat-behavior.d.ts

@@ -0,0 +1,29 @@
+import type { ChatAction } from "./types";
+export declare const filterChatCommands: <T extends {
+    name: string;
+}>(value: string, commands: readonly T[]) => T[];
+export declare const nextChatCommandIndex: (index: number, length: number, direction: 1 | -1) => number;
+export declare const isChatNearBottom: (scrollHeight: number, scrollTop: number, clientHeight: number, threshold?: number) => boolean;
+export declare const restoredChatScrollTop: (previousScrollTop: number, previousScrollHeight: number, nextScrollHeight: number) => number;
+export type ChatSubmissionRun = {
+    /** Clears the controlled draft (and attachments) before the handler runs. */
+    clear: () => void;
+    /**
+     * The application handler. A synchronous throw, a rejected promise, and a
+     * `false` result all count as a rejected submission.
+     */
+    perform: () => boolean | void | Promise<boolean | void>;
+    /** Restores the cleared draft (and attachments) after a rejected submission. */
+    restore: () => void;
+    onError?: (error: unknown) => void;
+};
+/**
+ * Runs one composer submission with optimistic clearing. Resolves to `true`
+ * when the handler accepted the submission. A synchronous throw is handled
+ * exactly like a rejected promise so a controlled draft is never lost.
+ */
+export declare const runChatSubmission: (run: ChatSubmissionRun) => Promise<boolean>;
+/** Reports a handler failure without letting a synchronous throw escape. */
+export declare const reportChatFailure: (perform: () => unknown, onError?: (error: unknown) => void) => void;
+/** Executes the one behavior guaranteed by the ChatAction contract. */
+export declare const executeChatAction: (action: ChatAction) => Promise<void>;

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

@@ -0,0 +1,21 @@
+import { ChatComposer } from "./ChatComposer";
+import { ChatActivity, ChatContextUsage, ChatMessage } from "./ChatPrimitives";
+import { ChatRoot } from "./ChatRoot";
+import { ChatTimeline } from "./ChatTimeline";
+export type { ChatCommand, ChatCommandContext, ChatComposerProps, ChatFileSelection, ChatPasteHandler } from "./ChatComposer";
+export type { ChatActivityProps, ChatContextUsageProps, ChatMessageProps } from "./ChatPrimitives";
+export { formatChatTokens } from "./ChatPrimitives";
+export type { ChatRootProps } from "./ChatRoot";
+export type { ChatActivityItem, ChatMessageItem, ChatTimelineItem, ChatTimelineProps } from "./ChatTimeline";
+export type { ChatAction, ChatActivityTone, ChatAttachment, ChatComposerState, ChatContextUsageData, ChatMessageStatus, ChatModelOption, ChatRole, ChatSubmitInput, ChatSubmitIntent, ChatUsage, } from "./types";
+/**
+ * Portable, controlled chat surface. Applications own storage, streaming,
+ * authorization, rich message rendering, and domain actions.
+ */
+export declare const Chat: typeof ChatRoot & {
+    Timeline: typeof ChatTimeline;
+    Message: typeof ChatMessage;
+    Activity: typeof ChatActivity;
+    Composer: typeof ChatComposer;
+    ContextUsage: typeof ChatContextUsage;
+};

package/dist/types/chat/types.d.ts

@@ -0,0 +1,62 @@
+export type ChatRole = "user" | "assistant" | "system" | "tool";
+export type ChatMessageStatus = "pending" | "streaming" | "complete" | "error";
+export type ChatActivityTone = "neutral" | "ai" | "success" | "danger";
+type ChatActionBase = {
+    id: string;
+    label: string;
+    icon?: string;
+    variant?: "danger";
+    disabled?: boolean;
+    /** Toggle state for persistent message actions such as feedback. */
+    pressed?: boolean;
+};
+/** Exactly one executable behavior for every chat action. */
+export type ChatAction = ChatActionBase & ({
+    onSelect: () => void | Promise<void>;
+    copyText?: never;
+} | {
+    copyText: string;
+    onSelect?: never;
+});
+export type ChatAttachment = {
+    id: string;
+    name: string;
+    size?: number;
+    kind?: "file" | "image" | "resource";
+    icon?: string;
+    previewUrl?: string;
+    alt?: string;
+    /** Optional destination represented by this attachment. */
+    href?: string;
+    /** Opaque application-owned payload returned unchanged with ChatSubmitInput. */
+    data?: unknown;
+    /** Optional application-owned action presented below the attachment label. */
+    action?: ChatAction;
+};
+export type ChatUsage = {
+    input?: number;
+    output?: number;
+    total?: number;
+};
+export type ChatContextUsageData = {
+    usage?: ChatUsage | null;
+    loopUsage?: ChatUsage | null;
+    contextWindow?: number;
+    modelLabel?: string;
+};
+export type ChatModelOption = {
+    id: string;
+    label: string;
+    description?: string;
+    image?: string;
+    icon?: string;
+    capabilities?: readonly string[];
+};
+export type ChatComposerState = "idle" | "submitting" | "running" | "stopping";
+export type ChatSubmitIntent = "send" | "steer" | "queue";
+export type ChatSubmitInput = {
+    intent: ChatSubmitIntent;
+    text: string;
+    attachments: readonly ChatAttachment[];
+};
+export {};