@mithrl/design-system 0.2.0 → 0.4.0

package/dist/internal/useStaggerBatch.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Highest stagger step any one batch may reach.
+ *
+ * A stagger only helps while the eye can still count the arrivals. Past a
+ * handful of steps it stops reading as "several things arrived" and starts
+ * reading as "this list is slow", so every item beyond the cap shares the last
+ * delay instead of extending the tail. Twelve rows land within
+ * `--motion-stagger-tight * 5` of each other, not half a second apart.
+ */
+export declare const STAGGER_BATCH_MAX_STEPS = 5;
+/**
+ * Returns the stagger step for each id that arrived in *this* batch.
+ *
+ * Only items that appeared together are staggered. An item added on its own
+ * later gets step 0 and enters immediately, because a lone arrival has no
+ * group for the eye to order — delaying it would be latency with nothing to
+ * show for it.
+ *
+ * The first render counts as a batch, so a list that mounts already populated
+ * still staggers.
+ */
+export declare function useStaggerBatch(ids: readonly string[], maxSteps?: number): ReadonlyMap<string, number>;

package/dist/patterns/notifications/Notifications.d.ts

@@ -0,0 +1,159 @@
+import { Toast } from "@base-ui/react/toast";
+import { type LucideIcon } from "lucide-react";
+import { type ComponentPropsWithoutRef, type HTMLAttributes, type ReactNode } from "react";
+import { DialogPortal } from "../../components/dialog/Dialog";
+import { type IconButtonProps } from "../../components/icon-button/IconButton";
+
+export type NotificationTone = "success" | "failure" | "information" | "neutral" | "needs-you";
+export type NotificationFilter = "all" | "needs-you";
+export type NotificationItemPreviewState = "default" | "hover" | "focus";
+export type NotificationRecord = {
+    id: string;
+    title: string;
+    metadata: string;
+    tone: NotificationTone;
+    glyph?: LucideIcon;
+    unread: boolean;
+};
+export type NotificationStatusIconProps = Omit<HTMLAttributes<HTMLSpanElement>, "children"> & {
+    tone: NotificationTone;
+    glyph?: LucideIcon;
+};
+/** Decorative semantic signal. The notification title carries the meaning. */
+export declare const NotificationStatusIcon: import("react").ForwardRefExoticComponent<Omit<HTMLAttributes<HTMLSpanElement>, "children"> & {
+    tone: NotificationTone;
+    glyph?: LucideIcon;
+} & import("react").RefAttributes<HTMLSpanElement>>;
+export type NotificationItemProps = Omit<HTMLAttributes<HTMLLIElement>, "children" | "onSelect"> & {
+    notification: NotificationRecord;
+    onSelect?: (notification: NotificationRecord) => void;
+    onMarkRead?: (notification: NotificationRecord) => void;
+    onArchive?: (notification: NotificationRecord) => void;
+    previewState?: NotificationItemPreviewState;
+};
+/** Controlled inbox row. It never mutates read or archive state internally. */
+export declare const NotificationItem: import("react").ForwardRefExoticComponent<Omit<HTMLAttributes<HTMLLIElement>, "children" | "onSelect"> & {
+    notification: NotificationRecord;
+    onSelect?: (notification: NotificationRecord) => void;
+    onMarkRead?: (notification: NotificationRecord) => void;
+    onArchive?: (notification: NotificationRecord) => void;
+    previewState?: NotificationItemPreviewState;
+} & import("react").RefAttributes<HTMLLIElement>>;
+export type NotificationTriggerProps = Omit<IconButtonProps, "icon" | "aria-label" | "children"> & {
+    unreadCount?: number;
+    label?: string;
+};
+/** Bell trigger with an accessible unread count and DS Tooltip. */
+export declare const NotificationTrigger: import("react").ForwardRefExoticComponent<Omit<IconButtonProps, "aria-label" | "children" | "icon"> & {
+    unreadCount?: number;
+    label?: string;
+} & import("react").RefAttributes<HTMLButtonElement>>;
+export type NotificationCenterProps = Omit<HTMLAttributes<HTMLDivElement>, "children" | "onSelect"> & {
+    notifications: readonly NotificationRecord[];
+    filter?: NotificationFilter;
+    defaultFilter?: NotificationFilter;
+    onFilterChange?: (filter: NotificationFilter) => void;
+    onItemSelect?: (notification: NotificationRecord) => void;
+    onMarkRead?: (notification: NotificationRecord) => void;
+    onArchive?: (notification: NotificationRecord) => void;
+    onMarkAllRead?: () => void;
+    onClearRead?: () => void;
+    onOpenSettings?: () => void;
+    onClose?: () => void;
+    closeAction?: ReactNode;
+    emptyContent?: ReactNode;
+    titleId?: string;
+};
+/** Global, controlled inbox surface. */
+export declare const NotificationCenter: import("react").ForwardRefExoticComponent<Omit<HTMLAttributes<HTMLDivElement>, "children" | "onSelect"> & {
+    notifications: readonly NotificationRecord[];
+    filter?: NotificationFilter;
+    defaultFilter?: NotificationFilter;
+    onFilterChange?: (filter: NotificationFilter) => void;
+    onItemSelect?: (notification: NotificationRecord) => void;
+    onMarkRead?: (notification: NotificationRecord) => void;
+    onArchive?: (notification: NotificationRecord) => void;
+    onMarkAllRead?: () => void;
+    onClearRead?: () => void;
+    onOpenSettings?: () => void;
+    onClose?: () => void;
+    closeAction?: ReactNode;
+    emptyContent?: ReactNode;
+    titleId?: string;
+} & import("react").RefAttributes<HTMLDivElement>>;
+export type NotificationsDrawerProps = {
+    notifications: readonly NotificationRecord[];
+    unreadCount?: number;
+    open?: boolean;
+    defaultOpen?: boolean;
+    onOpenChange?: (open: boolean) => void;
+    dir?: "ltr" | "rtl";
+    portalContainer?: ComponentPropsWithoutRef<typeof DialogPortal>["container"];
+    triggerProps?: Omit<NotificationTriggerProps, "unreadCount">;
+    centerProps?: Omit<NotificationCenterProps, "notifications" | "closeAction" | "titleId">;
+};
+/** Trigger + modal floating drawer behavior for the global inbox. */
+export declare function NotificationsDrawer({ notifications, unreadCount, open, defaultOpen, onOpenChange, dir, portalContainer, triggerProps, centerProps, }: NotificationsDrawerProps): import("react/jsx-runtime").JSX.Element;
+export type NotificationToastProps = Omit<HTMLAttributes<HTMLDivElement>, "title" | "children"> & {
+    tone: NotificationTone;
+    glyph?: LucideIcon;
+    heading: ReactNode;
+    description?: ReactNode;
+    action?: ReactNode;
+    onDismiss?: () => void;
+    dismissLabel?: string;
+    closeAction?: ReactNode;
+};
+/** Visual toast surface. Lifecycle and announcements belong to the provider. */
+export declare const NotificationToast: import("react").ForwardRefExoticComponent<Omit<HTMLAttributes<HTMLDivElement>, "children" | "title"> & {
+    tone: NotificationTone;
+    glyph?: LucideIcon;
+    heading: ReactNode;
+    description?: ReactNode;
+    action?: ReactNode;
+    onDismiss?: () => void;
+    dismissLabel?: string;
+    closeAction?: ReactNode;
+} & import("react").RefAttributes<HTMLDivElement>>;
+export type NotificationToastData = {
+    tone: NotificationTone;
+    glyph?: LucideIcon;
+    dismissLabel?: string;
+    actionAriaLabel?: string;
+};
+export type NotificationToastOptions = {
+    id?: string;
+    tone: NotificationTone;
+    glyph?: LucideIcon;
+    dismissLabel?: string;
+    actionAriaLabel?: string;
+    title: ReactNode;
+    description?: ReactNode;
+    actionLabel?: ReactNode;
+    onAction?: () => void;
+    timeout?: number;
+    priority?: "low" | "high";
+    onClose?: () => void;
+    onRemove?: () => void;
+};
+export type NotificationToastProviderProps = {
+    children: ReactNode;
+    timeout?: number;
+    limit?: number;
+    toastManager?: ComponentPropsWithoutRef<typeof Toast.Provider>["toastManager"];
+};
+export declare function NotificationToastProvider({ children, timeout, limit, toastManager, }: NotificationToastProviderProps): import("react/jsx-runtime").JSX.Element;
+export declare function useNotificationToast(): {
+    add: ({ tone, glyph, dismissLabel, actionAriaLabel, title, description, actionLabel, onAction, timeout, priority, ...options }: NotificationToastOptions) => string;
+    close: (toastId?: string) => void;
+    update: <T extends NotificationToastData = NotificationToastData>(toastId: string, options: import("@base-ui/react").ToastManagerUpdateOptions<T>) => void;
+    toasts: import("@base-ui/react").ToastObject<NotificationToastData>[];
+};
+export type NotificationToastViewportProps = Omit<ComponentPropsWithoutRef<typeof Toast.Viewport>, "children" | "className"> & {
+    portalContainer?: ComponentPropsWithoutRef<typeof Toast.Portal>["container"];
+    className?: string;
+};
+export declare const NotificationToastViewport: import("react").ForwardRefExoticComponent<Omit<Omit<Omit<import("@base-ui/react").ToastViewportProps, "ref"> & import("react").RefAttributes<HTMLDivElement>, "ref">, "children" | "className"> & {
+    portalContainer?: ComponentPropsWithoutRef<typeof Toast.Portal>["container"];
+    className?: string;
+} & import("react").RefAttributes<HTMLDivElement>>;

package/dist/patterns/workspace-app-shell/WorkspaceAppShell.d.ts

@@ -1,21 +1,39 @@
 import { type HTMLAttributes, type ReactNode } from "react";
 import { type GlobalAppBarProjectSelector, type GlobalAppBarProps } from "../../components/global-app-bar/GlobalAppBar";
 import { type ResizablePanelGroupProps, type ResizablePanelMinimum } from "../../components/resizable-panels/ResizablePanels";
-import { type WorkspaceNavigationProps } from "../../components/workspace-navigation/WorkspaceNavigation";
+import { type WorkspaceNavigationPresentation, type WorkspaceNavigationProps } from "../../components/workspace-navigation/WorkspaceNavigation";
 import type { ThemeMode } from "../../components/switch/Switch";
 
 export type WorkspaceAppShellLayout = "expanded" | "condensed" | "single";
 type NativeWorkspaceAppShellProps = Omit<HTMLAttributes<HTMLDivElement>, "children">;
 type WorkspaceAppBarConfiguration = Omit<GlobalAppBarProps, "defaultTheme" | "onThemeChange" | "theme" | "workspaceControls">;
-type WorkspaceNavigationConfiguration = Omit<WorkspaceNavigationProps, "presentation">;
+export type WorkspaceNavigationConfiguration = Omit<WorkspaceNavigationProps, "presentation">;
 type WorkspaceProjectSelectorConfiguration = Omit<GlobalAppBarProjectSelector, "presentation">;
+export type WorkspaceAppShellNavigationRenderContext = {
+    /** Active structural layout selected from the shell's rendered width. */
+    layout: WorkspaceAppShellLayout;
+    /** Inline on persistent layouts and Overlay in the single-region layout. */
+    presentation: WorkspaceNavigationPresentation;
+    /** Current controlled or uncontrolled Navigation visibility. */
+    open: boolean;
+    /** Stable App Bar toggle identity for focus return from compact overlays. */
+    navigationToggleId: string;
+    /** Requests dismissal after safely relocating focus through the shell. */
+    requestClose: () => void;
+};
+export type WorkspaceAppShellNavigationRenderer = (context: WorkspaceAppShellNavigationRenderContext) => ReactNode;
 export type WorkspaceAppShellProps = NativeWorkspaceAppShellProps & {
     /** Global App Bar account, brand, and native attributes. */
     appBar: WorkspaceAppBarConfiguration;
     /** Project context rendered by the approved Global App Bar selector. */
     projectSelector: WorkspaceProjectSelectorConfiguration;
     /** Workspace Navigation content; App Shell selects Inline or Overlay. */
-    navigation: WorkspaceNavigationConfiguration;
+    navigation?: WorkspaceNavigationConfiguration;
+    /**
+     * Product-navigation adapter for domain-specific status and nested artifacts.
+     * Use instead of `navigation`; the shell still owns visibility and focus.
+     */
+    renderNavigation?: WorkspaceAppShellNavigationRenderer;
     /** Product-owned Primary Panel content. */
     primary: ReactNode;
     /** Product-owned Secondary Panel content. */
@@ -46,12 +64,45 @@ export type WorkspaceAppShellProps = NativeWorkspaceAppShellProps & {
     onSplitChange?: ResizablePanelGroupProps["onValueChange"];
     /** Reports the final pointer value or each committed keyboard step. */
     onSplitCommit?: ResizablePanelGroupProps["onValueCommit"];
+    /** Controlled Secondary width in pixels. Use for product `rightWidth`. */
+    secondaryWidth?: number;
+    /** Initial Secondary width for uncontrolled pixel-based persistence. */
+    defaultSecondaryWidth?: number;
+    /** Reports every resize in Secondary pixels. */
+    onSecondaryWidthChange?: ResizablePanelGroupProps["onSecondarySizeChange"];
+    /** Reports the final pointer value or each keyboard step in pixels. */
+    onSecondaryWidthCommit?: ResizablePanelGroupProps["onSecondarySizeCommit"];
     /** Primary minimum-size policy. Defaults to Standard. */
     primaryMinSize?: ResizablePanelMinimum;
     /** Secondary minimum in pixels. Defaults to 280px. */
     secondaryMinSize?: number;
     /** Accessible splitter label when the Primary region has no visible label. */
     resizeLabel?: string;
+    /** Controlled Navigation width in pixels on the expanded layout. */
+    navigationWidth?: number;
+    /** Initial Navigation width for uncontrolled pixel-based persistence. */
+    defaultNavigationWidth?: number;
+    /** Reports every pointer or keyboard Navigation resize in pixels. */
+    onNavigationWidthChange?: (width: number) => void;
+    /** Reports the final pointer width or each committed keyboard step. */
+    onNavigationWidthCommit?: (width: number) => void;
+    /** Navigation minimum width in pixels. Defaults to 200px. */
+    navigationMinWidth?: number;
+    /** Navigation maximum width in pixels. Defaults to 320px. */
+    navigationMaxWidth?: number;
+    /** Accessible label for the Navigation splitter. */
+    navigationResizeLabel?: string;
+    /**
+     * Share of a panel minimum the pointer must cross before a drag dismisses
+     * that panel. Defaults to 0.5, i.e. half the minimum width.
+     */
+    dragDismissThreshold?: number;
+    /**
+     * Enables the transient left-edge hover peek that reveals Navigation as a
+     * floating overlay while it is closed on a persistent layout. The peek never
+     * changes `navigationOpen`. Defaults to enabled.
+     */
+    navigationPeek?: boolean;
 };
 /**
  * Complete Workspace layout pattern. It composes the approved Global App Bar,
@@ -64,7 +115,12 @@ export declare const WorkspaceAppShell: import("react").ForwardRefExoticComponen
     /** Project context rendered by the approved Global App Bar selector. */
     projectSelector: WorkspaceProjectSelectorConfiguration;
     /** Workspace Navigation content; App Shell selects Inline or Overlay. */
-    navigation: WorkspaceNavigationConfiguration;
+    navigation?: WorkspaceNavigationConfiguration;
+    /**
+     * Product-navigation adapter for domain-specific status and nested artifacts.
+     * Use instead of `navigation`; the shell still owns visibility and focus.
+     */
+    renderNavigation?: WorkspaceAppShellNavigationRenderer;
     /** Product-owned Primary Panel content. */
     primary: ReactNode;
     /** Product-owned Secondary Panel content. */
@@ -95,11 +151,44 @@ export declare const WorkspaceAppShell: import("react").ForwardRefExoticComponen
     onSplitChange?: ResizablePanelGroupProps["onValueChange"];
     /** Reports the final pointer value or each committed keyboard step. */
     onSplitCommit?: ResizablePanelGroupProps["onValueCommit"];
+    /** Controlled Secondary width in pixels. Use for product `rightWidth`. */
+    secondaryWidth?: number;
+    /** Initial Secondary width for uncontrolled pixel-based persistence. */
+    defaultSecondaryWidth?: number;
+    /** Reports every resize in Secondary pixels. */
+    onSecondaryWidthChange?: ResizablePanelGroupProps["onSecondarySizeChange"];
+    /** Reports the final pointer value or each keyboard step in pixels. */
+    onSecondaryWidthCommit?: ResizablePanelGroupProps["onSecondarySizeCommit"];
     /** Primary minimum-size policy. Defaults to Standard. */
     primaryMinSize?: ResizablePanelMinimum;
     /** Secondary minimum in pixels. Defaults to 280px. */
     secondaryMinSize?: number;
     /** Accessible splitter label when the Primary region has no visible label. */
     resizeLabel?: string;
+    /** Controlled Navigation width in pixels on the expanded layout. */
+    navigationWidth?: number;
+    /** Initial Navigation width for uncontrolled pixel-based persistence. */
+    defaultNavigationWidth?: number;
+    /** Reports every pointer or keyboard Navigation resize in pixels. */
+    onNavigationWidthChange?: (width: number) => void;
+    /** Reports the final pointer width or each committed keyboard step. */
+    onNavigationWidthCommit?: (width: number) => void;
+    /** Navigation minimum width in pixels. Defaults to 200px. */
+    navigationMinWidth?: number;
+    /** Navigation maximum width in pixels. Defaults to 320px. */
+    navigationMaxWidth?: number;
+    /** Accessible label for the Navigation splitter. */
+    navigationResizeLabel?: string;
+    /**
+     * Share of a panel minimum the pointer must cross before a drag dismisses
+     * that panel. Defaults to 0.5, i.e. half the minimum width.
+     */
+    dragDismissThreshold?: number;
+    /**
+     * Enables the transient left-edge hover peek that reveals Navigation as a
+     * floating overlay while it is closed on a persistent layout. The peek never
+     * changes `navigationOpen`. Defaults to enabled.
+     */
+    navigationPeek?: boolean;
 } & import("react").RefAttributes<HTMLDivElement>>;
 export {};

package/dist/patterns/workspace-app-shell/WorkspaceNewQuestionDialog.d.ts

@@ -0,0 +1,24 @@
+import { type ReactNode } from "react";
+import { type DialogContentProps } from "../../components/dialog/Dialog";
+
+export type WorkspaceNewQuestionDraft = {
+    question: string;
+};
+export type WorkspaceNewQuestionDialogProps = {
+    open?: boolean;
+    defaultOpen?: boolean;
+    onOpenChange?: (open: boolean) => void;
+    /** Associates the controlled Dialog with the Navigation action. */
+    triggerId?: string;
+    initialQuestion?: string;
+    onStart: (draft: WorkspaceNewQuestionDraft) => void | Promise<void>;
+    submitting?: boolean;
+    submitError?: ReactNode;
+    portalContainer?: DialogContentProps["portalContainer"];
+    className?: string;
+};
+/**
+ * Controlled Workspace entry pattern. Session creation, routing, persistence,
+ * authorization, and analytics remain owned by the product.
+ */
+export declare function WorkspaceNewQuestionDialog({ open, defaultOpen, onOpenChange, triggerId, initialQuestion, onStart, submitting, submitError, portalContainer, className, }: WorkspaceNewQuestionDialogProps): import("react/jsx-runtime").JSX.Element;

package/dist/patterns/workspace-app-shell/WorkspaceQuestionSurface.d.ts

@@ -0,0 +1,49 @@
+import { type HTMLAttributes, type ReactNode } from "react";
+
+export type WorkspaceQuestionSurfacePanel = "primary" | "secondary";
+export type WorkspaceQuestionSurfaceScroll = "consumer" | "surface";
+type NativeWorkspaceQuestionSurfaceProps = Omit<HTMLAttributes<HTMLElement>, "children" | "title">;
+export type WorkspaceQuestionSurfaceProps = NativeWorkspaceQuestionSurfaceProps & {
+    /** Panel that owns this mounted Question. Ownership remains product state. */
+    panel: WorkspaceQuestionSurfacePanel;
+    /** Full Question name used by the Primary header and region label. */
+    questionTitle: string;
+    /** Product-owned Question content inside the approved panel containment. */
+    children: ReactNode;
+    /** Product-owned Composer or ComposerViewTransition for this session. */
+    composer: ReactNode;
+    /**
+     * Scroll owner. Defaults to the consumer so existing Chat viewport logic,
+     * streaming follow, and minimaps remain unchanged.
+     */
+    contentScroll?: WorkspaceQuestionSurfaceScroll;
+    /** Product actions shown beside the Primary Question title. */
+    headerActions?: ReactNode;
+    /** Shows the contextual header. Defaults to true only in Primary. */
+    showHeader?: boolean;
+};
+/**
+ * Session-bound Question layout for either Workspace owner panel. The product
+ * supplies Chat and Composer behavior; this pattern owns the approved header,
+ * scroll containment, bottom anchoring, and adaptive fade.
+ */
+export declare const WorkspaceQuestionSurface: import("react").ForwardRefExoticComponent<NativeWorkspaceQuestionSurfaceProps & {
+    /** Panel that owns this mounted Question. Ownership remains product state. */
+    panel: WorkspaceQuestionSurfacePanel;
+    /** Full Question name used by the Primary header and region label. */
+    questionTitle: string;
+    /** Product-owned Question content inside the approved panel containment. */
+    children: ReactNode;
+    /** Product-owned Composer or ComposerViewTransition for this session. */
+    composer: ReactNode;
+    /**
+     * Scroll owner. Defaults to the consumer so existing Chat viewport logic,
+     * streaming follow, and minimaps remain unchanged.
+     */
+    contentScroll?: WorkspaceQuestionSurfaceScroll;
+    /** Product actions shown beside the Primary Question title. */
+    headerActions?: ReactNode;
+    /** Shows the contextual header. Defaults to true only in Primary. */
+    showHeader?: boolean;
+} & import("react").RefAttributes<HTMLElement>>;
+export {};