@ai-matrx/design-system 0.1.0 → 0.2.0

package/dist/index.d.cts

@@ -0,0 +1,415 @@
+import * as class_variance_authority_types from 'class-variance-authority/types';
+import { VariantProps } from 'class-variance-authority';
+import * as React from 'react';
+import React__default, { ComponentType, ReactNode } from 'react';
+import { ClassValue } from 'clsx';
+import * as LabelPrimitive from '@radix-ui/react-label';
+import * as PopoverPrimitive from '@radix-ui/react-popover';
+import * as SeparatorPrimitive from '@radix-ui/react-separator';
+import * as SheetPrimitive from '@radix-ui/react-dialog';
+
+declare const badgeVariants: (props?: ({
+    variant?: "default" | "secondary" | "destructive" | "outline" | "success" | "warning" | "info" | "error" | "neutral" | null | undefined;
+} & class_variance_authority_types.ClassProp) | undefined) => string;
+interface BadgeProps extends React.HTMLAttributes<HTMLSpanElement>, VariantProps<typeof badgeVariants> {
+}
+declare function Badge({ className, variant, ...props }: BadgeProps): React.JSX.Element;
+
+interface BottomSheetProps {
+    open: boolean;
+    onOpenChange: (open: boolean) => void;
+    title?: string;
+    /**
+     * `adaptive` (default) — the sheet sizes to its content between 60dvh and
+     * 90dvh. Correct for a single short list.
+     *
+     * `full` — ONE fixed height (92dvh) that never changes as content changes.
+     * Use it for any sheet whose body varies (multi-level navigation, tabs,
+     * search results): an adaptive sheet there resizes under the user's thumb
+     * on every keystroke and every drill-in, which reads as the panel jumping.
+     */
+    size?: "adaptive" | "full";
+    /** Visual treatment for the panel. Solid is intended for dense, long-lived surfaces. */
+    surface?: "glass" | "solid";
+    /** Merged onto the sheet panel. */
+    contentClassName?: string;
+    children: React.ReactNode;
+}
+declare function BottomSheet({ open, onOpenChange, title, size, surface, contentClassName, children, }: BottomSheetProps): React.JSX.Element;
+interface BottomSheetHeaderProps {
+    title: string;
+    showBack?: boolean;
+    onBack?: () => void;
+    trailing?: React.ReactNode;
+}
+declare function BottomSheetHeader({ title, showBack, onBack, trailing, }: BottomSheetHeaderProps): React.JSX.Element;
+interface BottomSheetBodyProps {
+    children: React.ReactNode;
+    className?: string;
+}
+declare function BottomSheetBody({ children, className }: BottomSheetBodyProps): React.JSX.Element;
+interface BottomSheetFooterProps {
+    children: React.ReactNode;
+    className?: string;
+}
+declare function BottomSheetFooter({ children, className, }: BottomSheetFooterProps): React.JSX.Element;
+
+declare const buttonVariants: (props?: ({
+    variant?: "default" | "secondary" | "destructive" | "outline" | "link" | "ghost" | "subtle" | null | undefined;
+    size?: "default" | "sm" | "lg" | "icon" | "icon-sm" | null | undefined;
+} & class_variance_authority_types.ClassProp) | undefined) => string;
+interface ButtonProps extends React.ButtonHTMLAttributes<HTMLButtonElement>, VariantProps<typeof buttonVariants> {
+    asChild?: boolean;
+}
+declare const Button: React.ForwardRefExoticComponent<ButtonProps & React.RefAttributes<HTMLButtonElement>>;
+
+declare function cn(...inputs: ClassValue[]): string;
+
+type EditableLabelCommitMode = "optimistic" | "await";
+type EditableLabelActivation = "click" | "doubleClick" | "controlled";
+interface EditableLabelProps {
+    value: string;
+    /**
+     * Commit handler. optimistic (default): edit mode exits immediately, the
+     * promise is fire-and-forget (owners do optimistic update + revert + toast).
+     * await: input disables with a spinner until the promise resolves; a
+     * rejection keeps edit mode open to retry.
+     */
+    onCommit: (next: string) => void | Promise<void>;
+    commitMode?: EditableLabelCommitMode;
+    /** Return an error message to block the commit (shown under the input). */
+    validate?: (next: string) => string | null;
+    /** Used when the trimmed draft is empty. Undefined → empty cancels. */
+    emptyFallback?: string;
+    maxLength?: number;
+    /**
+     * "click"/"doubleClick" — internal edit state (headers). "controlled" — host
+     * owns `editing`; EditableLabel renders ONLY the input when editing.
+     */
+    activation?: EditableLabelActivation;
+    editing?: boolean;
+    /** Edit-state notifications. Controlled mode: the ONLY state channel.
+     *  Uncontrolled modes: fired as a notification (layout hooks etc.). */
+    onEditingChange?: (editing: boolean) => void;
+    selectOnEdit?: boolean;
+    placeholder?: string;
+    /** Accessible name, e.g. "Session title". Default "Name". */
+    ariaLabel?: string;
+    truncate?: boolean;
+    className?: string;
+    displayClassName?: string;
+    inputClassName?: string;
+}
+declare function EditableLabel({ value, onCommit, commitMode, validate, emptyFallback, maxLength, activation, editing: editingProp, onEditingChange, selectOnEdit, placeholder, ariaLabel, truncate, className, displayClassName, inputClassName, }: EditableLabelProps): React.JSX.Element | null;
+
+/**
+ * Input family — ported verbatim from matrx-frontend `components/ui/input.tsx`.
+ *
+ * Seam inversions:
+ * - `MatrxVariant` (host `components/ui/types`) becomes the structural
+ *   `InputVariant` union with the identical members, so host call sites are
+ *   drop-in compatible.
+ * - The host file's `CopyInput` / `FancyInput` / `DeleteInput` are
+ *   deliberately NOT absorbed (C8 split-out law): they carry a `motion/react`
+ *   dependency (and clipboard behavior) that plain-Input consumers must not
+ *   pay for. They stay host-owned until sanctioned separately.
+ */
+
+type InputVariant = "default" | "destructive" | "success" | "outline" | "secondary" | "ghost" | "link" | "primary";
+interface InputProps extends React.InputHTMLAttributes<HTMLInputElement> {
+    variant?: InputVariant;
+}
+declare const Input: React.ForwardRefExoticComponent<InputProps & React.RefAttributes<HTMLInputElement>>;
+interface EnterInputProps extends InputProps {
+    onEnter?: () => void;
+}
+declare const EnterInput: React.ForwardRefExoticComponent<EnterInputProps & React.RefAttributes<HTMLInputElement>>;
+declare const BasicInput: React.ForwardRefExoticComponent<InputProps & React.RefAttributes<HTMLInputElement>>;
+interface InputWithPrefixProps extends Omit<InputProps, "prefix"> {
+    prefix?: React.ReactNode;
+    wrapperClassName?: string;
+}
+declare const InputWithPrefix: React.ForwardRefExoticComponent<InputWithPrefixProps & React.RefAttributes<HTMLInputElement>>;
+
+declare const Label: React.ForwardRefExoticComponent<Omit<LabelPrimitive.LabelProps & React.RefAttributes<HTMLLabelElement>, "ref"> & React.RefAttributes<HTMLLabelElement>>;
+
+/**
+ * OverflowToolbar — a horizontal row of consistent, compact action buttons
+ * that collapses the buttons that don't fit into a single "more" (…) menu.
+ * Ported verbatim from matrx-frontend
+ * `components/official/toolbar/OverflowToolbar.tsx` (S20).
+ *
+ *   ┌───────────────────────────────────────────────┐
+ *   │ [leading]  [Btn] [Btn] [Btn]            [ … ]  │
+ *   └───────────────────────────────────────────────┘
+ *
+ * Design rules (the primitive enforces them so callers can't drift):
+ *   - Every button is the same height (h-7), padding, text size, icon size.
+ *   - `hideLabel` renders an icon-only button with a tooltip — use it for
+ *     "obvious" actions (Find, Source, …).
+ *   - `tone: "primary"` colors a button without changing its size, so the
+ *     primary action is NOT visually larger than the rest.
+ *   - When the row is too narrow, the LAST actions collapse into the overflow
+ *     menu first. Order your actions most-important-first.
+ *
+ * Measurement is done with a hidden "ghost" row (always renders every action
+ * + the kebab) read via a ResizeObserver, so the visible row never reflows
+ * mid-frame.
+ *
+ * Seam inversions (host-shaped chrome becomes injected):
+ * - `icon: LucideIcon` → the structural `ToolbarIcon`
+ *   (`ComponentType<{ className?: string }>`) — any SVG component fits.
+ * - The host Tooltip wrapper → `renderTooltip` prop. Without it, icon-only
+ *   buttons render bare (they always carry `aria-label`); hosts inject their
+ *   tooltip system for the original hover behavior.
+ * - The host ItemMenu overflow menu → `renderOverflowMenu` prop (required):
+ *   the host receives the collapsed actions plus the ready-made kebab trigger
+ *   and renders them with its own menu system.
+ */
+
+type ToolbarActionTone = "default" | "primary" | "destructive";
+/** Structural icon contract (a lucide icon satisfies it, so does any SVG component). */
+type ToolbarIcon = React__default.ComponentType<{
+    className?: string;
+}>;
+interface ToolbarAction {
+    id: string;
+    label: string;
+    icon: ToolbarIcon;
+    /** Click handler. Ignored when `href` is set. */
+    onSelect?: () => void;
+    /** Renders an anchor instead of a button. */
+    href?: string;
+    target?: "_blank";
+    disabled?: boolean;
+    /** Swaps the icon for a spinner and (optionally) shows `runningLabel`. */
+    running?: boolean;
+    runningLabel?: string;
+    tone?: ToolbarActionTone;
+    /** Icon-only button (tooltip carries the label). For obvious actions. */
+    hideLabel?: boolean;
+    /** Drop the action entirely. */
+    hidden?: boolean;
+}
+interface OverflowToolbarProps {
+    actions: ToolbarAction[];
+    /**
+     * Optional element pinned at the start of the row — never collapsed, never
+     * measured into the action budget except as a fixed prefix (e.g. a surface
+     * switcher / context chip cluster).
+     */
+    leading?: React__default.ReactNode;
+    /** Accessible label for the overflow trigger. */
+    overflowAriaLabel?: string;
+    className?: string;
+    /**
+     * Injected overflow-menu seam: render the collapsed actions with the host's
+     * menu system, using `trigger` (the ready-made kebab button) as the menu
+     * trigger element.
+     */
+    renderOverflowMenu: (args: {
+        actions: ToolbarAction[];
+        trigger: React__default.ReactNode;
+    }) => React__default.ReactNode;
+    /**
+     * Injected tooltip seam for icon-only buttons (their label lives nowhere
+     * else on screen). Omitted → the bare control renders (aria-label intact).
+     */
+    renderTooltip?: (control: React__default.ReactElement, label: string) => React__default.ReactNode;
+}
+declare function OverflowToolbar({ actions, leading, overflowAriaLabel, className, renderOverflowMenu, renderTooltip, }: OverflowToolbarProps): React__default.JSX.Element;
+
+/**
+ * Popover — ported verbatim from matrx-frontend `components/ui/popover.tsx`.
+ *
+ * Seam inversion: the host's `useNestedPortalContainer` (dialog/popout aware)
+ * becomes the injected `PortalContainerProvider` seam (`portal-container.tsx`);
+ * the explicit `container` prop keeps top priority, exactly as before.
+ *
+ * THE ROOT RENDERS UNCONDITIONALLY — no mount gate. This wrapper used to defer
+ * rendering until after hydration ("Radix generates dynamic aria-controls ids
+ * that differ between SSR and client"), and that justification was false:
+ * Radix ids come from React's SSR-stable `useId` (verified against
+ * @radix-ui/react-popover 1.1.17 / react-id 1.1.2). The gate was actively
+ * harmful — the Trigger wraps ALWAYS-VISIBLE content, so `return null`
+ * deleted it from SSR and the first client paint.
+ */
+
+declare const Popover: React.FC<PopoverPrimitive.PopoverProps>;
+declare const PopoverTrigger: React.ForwardRefExoticComponent<PopoverPrimitive.PopoverTriggerProps & React.RefAttributes<HTMLButtonElement>>;
+declare const PopoverAnchor: React.ForwardRefExoticComponent<PopoverPrimitive.PopoverAnchorProps & React.RefAttributes<HTMLDivElement>>;
+declare const PopoverContent: React.ForwardRefExoticComponent<Omit<PopoverPrimitive.PopoverContentProps & React.RefAttributes<HTMLDivElement>, "ref"> & {
+    container?: HTMLElement | null;
+} & React.RefAttributes<HTMLDivElement>>;
+
+/**
+ * Injected portal-container seam.
+ *
+ * The matrx-frontend original resolved nested portal targets through
+ * `useNestedPortalContainer` (explicit prop > dialog content > popout body >
+ * document.body) — a host-shaped hook wired to that app's dialog and
+ * window-panel systems. The package inverts the seam: hosts provide the
+ * resolved container through `PortalContainerProvider`; an explicit
+ * `container` prop on a component still wins, and with neither the portal
+ * falls through to `document.body` (Radix default). Priority semantics are
+ * unchanged from the original.
+ */
+
+interface PortalContainerProviderProps {
+    /** Where nested Radix portals (Popover, etc.) should mount. `null`/`undefined` → document.body. */
+    container: HTMLElement | null | undefined;
+    children: React.ReactNode;
+}
+declare function PortalContainerProvider({ container, children, }: PortalContainerProviderProps): React.JSX.Element;
+/**
+ * Resolve a portal target: explicit prop (including an explicit `null`,
+ * meaning "the default body") beats the injected container.
+ */
+declare function usePortalContainer(explicit?: HTMLElement | null): HTMLElement | undefined;
+
+/**
+ * Ported verbatim from matrx-frontend `components/ui/radix-dialog-modal-context.tsx`.
+ * Shared by the Sheet and BottomSheet families (and available to hosts that
+ * compose their own Radix Dialog-derived wrappers around these primitives).
+ */
+
+interface RadixDialogModalProviderProps {
+    children: React.ReactNode;
+    modal: boolean;
+}
+/**
+ * Keeps our Radix-based content wrappers aligned with the owning Root's
+ * modality so ARIA semantics cannot drift from focus/pointer behavior.
+ */
+declare function RadixDialogModalProvider({ children, modal, }: RadixDialogModalProviderProps): React.JSX.Element;
+/** Returns whether the nearest Radix Dialog-derived root is modal. */
+declare function useRadixDialogModal(): boolean;
+
+/**
+ * ScoreRing — SVG progress ring + the shared score→color threshold semantics.
+ * Ported verbatim from matrx-frontend `components/official/ScoreRing.tsx`
+ * (S18). The thresholds ARE the product: green at/above `good`, orange
+ * at/above `warning`, red below, muted for null. No seams.
+ */
+
+interface ScoreThresholds {
+    /** Scores at or above this value are green. */
+    good: number;
+    /** Scores at or above this value (but below good) are orange. */
+    warning: number;
+}
+declare const DEFAULT_SCORE_THRESHOLDS: ScoreThresholds;
+/** Semantic score color shared by ring and accent consumers. */
+declare function scoreRingColorClasses(pct: number | null, thresholds?: ScoreThresholds): string;
+/** Solid-background twin of `scoreRingColorClasses`. */
+declare function scoreAccentBgClasses(pct: number | null, thresholds?: ScoreThresholds): string;
+interface ScoreRingProps {
+    pct: number | null;
+    size?: number;
+    strokeWidth?: number;
+    label?: string;
+    valueClassName?: string;
+    className?: string;
+    thresholds?: ScoreThresholds;
+    /** Visible suffix; study keeps `%`, while Lighthouse convention omits it. */
+    suffix?: string;
+}
+/**
+ * Shared SVG score ring. `pct` is 0–100; threshold semantics are supplied by
+ * the domain (for example Lighthouse uses 90/50 while study uses 75/50).
+ */
+declare function ScoreRing({ pct, size, strokeWidth, label, valueClassName, className, thresholds, suffix, }: ScoreRingProps): React.JSX.Element;
+
+/**
+ * SegmentedControl — sized accessible segmented toggle.
+ * Ported verbatim from matrx-frontend `components/ui/segmented-control.tsx`
+ * (S17). No seams: pure markup over host semantic tokens. The option/prop
+ * interfaces are exported here (the original kept them file-local).
+ */
+
+interface SegmentOption {
+    value: string;
+    label: React.ReactNode;
+    disabled?: boolean;
+}
+interface SegmentedControlProps {
+    value: string;
+    onValueChange: (value: string) => void;
+    data: SegmentOption[];
+    name?: string;
+    className?: string;
+    fullWidth?: boolean;
+    size?: "sm" | "md" | "lg";
+}
+declare function SegmentedControl({ value, onValueChange, data, name: _name, className, fullWidth, size, }: SegmentedControlProps): React.JSX.Element;
+
+declare const Separator: React.ForwardRefExoticComponent<Omit<SeparatorPrimitive.SeparatorProps & React.RefAttributes<HTMLDivElement>, "ref"> & React.RefAttributes<HTMLDivElement>>;
+
+declare const Sheet: React.ForwardRefExoticComponent<SheetPrimitive.DialogProps & React.RefAttributes<never>>;
+declare const SheetTrigger: React.ForwardRefExoticComponent<SheetPrimitive.DialogTriggerProps & React.RefAttributes<HTMLButtonElement>>;
+declare const SheetClose: React.ForwardRefExoticComponent<SheetPrimitive.DialogCloseProps & React.RefAttributes<HTMLButtonElement>>;
+declare const SheetPortal: React.FC<SheetPrimitive.DialogPortalProps>;
+declare const SheetOverlay: React.ForwardRefExoticComponent<Omit<SheetPrimitive.DialogOverlayProps & React.RefAttributes<HTMLDivElement>, "ref"> & React.RefAttributes<HTMLDivElement>>;
+declare const sheetVariants: (props?: ({
+    side?: "center" | "bottom" | "left" | "right" | "top" | null | undefined;
+} & class_variance_authority_types.ClassProp) | undefined) => string;
+interface SheetContentProps extends React.ComponentPropsWithoutRef<typeof SheetPrimitive.Content>, VariantProps<typeof sheetVariants> {
+    hideCloseButton?: boolean;
+    /** Skip the dimming overlay — for non-modal side panels (e.g. chat canvas). */
+    hideOverlay?: boolean;
+    /** Optional className for the overlay when shown. */
+    overlayClassName?: string;
+}
+declare const SheetDescription: React.ForwardRefExoticComponent<Omit<SheetPrimitive.DialogDescriptionProps & React.RefAttributes<HTMLParagraphElement>, "ref"> & React.RefAttributes<HTMLParagraphElement>>;
+declare const SheetContent: React.ForwardRefExoticComponent<SheetContentProps & React.RefAttributes<HTMLDivElement>>;
+declare const SheetHeader: {
+    ({ className, ...props }: React.HTMLAttributes<HTMLDivElement>): React.JSX.Element;
+    displayName: string;
+};
+declare const SheetFooter: {
+    ({ className, ...props }: React.HTMLAttributes<HTMLDivElement>): React.JSX.Element;
+    displayName: string;
+};
+declare const SheetTitle: React.ForwardRefExoticComponent<Omit<SheetPrimitive.DialogTitleProps & React.RefAttributes<HTMLHeadingElement>, "ref"> & React.RefAttributes<HTMLHeadingElement>>;
+
+/**
+ * Skeleton — ported verbatim from matrx-frontend `components/ui/skeleton.tsx`.
+ * No seams: pure markup over host semantic tokens.
+ */
+
+declare function Skeleton({ className, ...props }: React.HTMLAttributes<HTMLDivElement>): React.JSX.Element;
+
+interface TabbedBottomSheetTab {
+    id: string;
+    label: string;
+    icon?: ComponentType<{
+        className?: string;
+    }>;
+    /** Optional trailing badge / dot shown on the index row. */
+    trailing?: ReactNode;
+    content: ReactNode;
+}
+interface TabbedBottomSheetProps {
+    open: boolean;
+    onOpenChange: (open: boolean) => void;
+    title: string;
+    tabs: TabbedBottomSheetTab[];
+}
+declare function TabbedBottomSheet({ open, onOpenChange, title, tabs, }: TabbedBottomSheetProps): React.JSX.Element;
+
+interface ScrollFadeState {
+    top: boolean;
+    bottom: boolean;
+}
+interface UseScrollFadeResult {
+    ref: (node: HTMLElement | null) => void;
+    fadeProps: {
+        "data-fade-top": "" | undefined;
+        "data-fade-bottom": "" | undefined;
+        className: string;
+    };
+    state: ScrollFadeState;
+}
+declare function useScrollFade(): UseScrollFadeResult;
+
+export { Badge, type BadgeProps, BasicInput, BottomSheet, BottomSheetBody, type BottomSheetBodyProps, BottomSheetFooter, type BottomSheetFooterProps, BottomSheetHeader, type BottomSheetHeaderProps, type BottomSheetProps, Button, type ButtonProps, DEFAULT_SCORE_THRESHOLDS, EditableLabel, type EditableLabelActivation, type EditableLabelCommitMode, type EditableLabelProps, EnterInput, type EnterInputProps, Input, type InputProps, type InputVariant, InputWithPrefix, type InputWithPrefixProps, Label, OverflowToolbar, type OverflowToolbarProps, Popover, PopoverAnchor, PopoverContent, PopoverTrigger, PortalContainerProvider, type PortalContainerProviderProps, RadixDialogModalProvider, type RadixDialogModalProviderProps, ScoreRing, type ScoreRingProps, type ScoreThresholds, type ScrollFadeState, type SegmentOption, SegmentedControl, type SegmentedControlProps, Separator, Sheet, SheetClose, SheetContent, type SheetContentProps, SheetDescription, SheetFooter, SheetHeader, SheetOverlay, SheetPortal, SheetTitle, SheetTrigger, Skeleton, TabbedBottomSheet, type TabbedBottomSheetProps, type TabbedBottomSheetTab, type ToolbarAction, type ToolbarActionTone, type ToolbarIcon, type UseScrollFadeResult, badgeVariants, buttonVariants, cn, scoreAccentBgClasses, scoreRingColorClasses, sheetVariants, usePortalContainer, useRadixDialogModal, useScrollFade };