@zovaris/sephiro 0.6.0 → 0.7.0

package/dist/index.d.ts

@@ -1,8 +1,20 @@
 import * as react from 'react';
-import { HTMLAttributes, ButtonHTMLAttributes, InputHTMLAttributes, TextareaHTMLAttributes, TableHTMLAttributes } from 'react';
+import { HTMLAttributes, ButtonHTMLAttributes, InputHTMLAttributes, TextareaHTMLAttributes, RefObject, TableHTMLAttributes } from 'react';
 import { ExternalToast, ToasterProps } from 'sonner';
 export { toast } from 'sonner';
 
+type ControlSize = "sm" | "md" | "lg";
+
+type AvatarStatus = "online" | "offline" | "busy" | "away";
+type AvatarProps = Omit<HTMLAttributes<HTMLSpanElement>, "children"> & {
+    /** Image URL. Falls back to `name` initials when it fails to load. */
+    src?: string;
+    name?: string;
+    size?: ControlSize;
+    status?: AvatarStatus;
+};
+declare function Avatar({ src, name, size, status, className, ...props }: AvatarProps): react.JSX.Element;
+
 type RenderableElement = {
     type: any;
     props: any;
@@ -10,8 +22,6 @@ type RenderableElement = {
 };
 type Renderable = string | number | boolean | null | undefined | Iterable<Renderable> | RenderableElement;
 
-type ControlSize = "sm" | "md" | "lg";
-
 type BadgeProps = Omit<HTMLAttributes<HTMLSpanElement>, "children"> & {
     variant?: "neutral" | "accent" | "success" | "warning" | "danger";
     size?: ControlSize;
@@ -49,6 +59,30 @@ type InputProps = Omit<InputHTMLAttributes<HTMLInputElement>, "size"> & {
 };
 declare function Input({ invalid, size, className, "aria-invalid": ariaInvalid, ...props }: InputProps): react.JSX.Element;
 
+type KbdProps = {
+    /**
+     * Key caps to render. An array draws one cap per entry (`["⌘", "K"]`);
+     * a single value draws one cap (`"Esc"`).
+     */
+    keys: Renderable;
+    className?: string;
+};
+declare function Kbd({ keys, className }: KbdProps): react.JSX.Element;
+
+type ProgressProps = Omit<HTMLAttributes<HTMLDivElement>, "children"> & {
+    /** Completion from 0 to 100. Omit it for the indeterminate sweep. */
+    value?: number;
+    label?: string;
+    size?: ControlSize;
+};
+declare function Progress({ value, label, size, className, ...props }: ProgressProps): react.JSX.Element;
+
+type ScrollAreaProps = Omit<HTMLAttributes<HTMLDivElement>, "children"> & {
+    orientation?: "vertical" | "horizontal" | "both";
+    children?: Renderable;
+};
+declare function ScrollArea({ orientation, className, children, ...props }: ScrollAreaProps): react.JSX.Element;
+
 type SeparatorProps = Omit<HTMLAttributes<HTMLHRElement>, "children"> & {
     orientation?: "horizontal" | "vertical";
     decorative?: boolean;
@@ -104,6 +138,38 @@ type ToggleProps = Omit<ButtonHTMLAttributes<HTMLButtonElement>, "onChange" | "o
 };
 declare function Toggle({ checked, onCheckedChange, label, className, disabled, onClick, size, "aria-checked": ariaChecked, "aria-label": ariaLabel, ...props }: ToggleProps): react.JSX.Element;
 
+type MotionSpeed = "fast" | "normal" | "slow";
+/** Parses a CSS time string ("180ms", "0.18s", "0ms") into milliseconds. */
+declare function parseDurationMs(value: string): number;
+/**
+ * Reads the motion token in effect for an element, honouring theme
+ * overrides, `prefers-reduced-motion`, and `data-sephiro-motion="off"`.
+ * Returns 0 when there is nothing to wait for.
+ */
+declare function motionDurationMs(element: HTMLElement | null, speed: MotionSpeed): number;
+type Presence<E extends HTMLElement = HTMLElement> = {
+    /** Keep rendering the overlay while its exit animation plays. */
+    present: boolean;
+    /** True once the overlay has begun leaving; drive exit styles with it. */
+    leaving: boolean;
+    /** `open` while settled, `closed` once leaving. */
+    state: "open" | "closed";
+    /** Attach to the overlay element so its exit duration can be measured. */
+    ref: RefObject<E | null>;
+};
+/**
+ * Holds an overlay mounted for exactly as long as its exit animation runs.
+ *
+ * Enter animations replay on mount, so the component only needs to render
+ * while `present` and style itself with `state`:
+ *
+ * ```tsx
+ * const { present, state, ref } = usePresence(open, "fast");
+ * return present ? <div ref={ref} data-state={state} /> : null;
+ * ```
+ */
+declare function usePresence<E extends HTMLElement = HTMLElement>(open: boolean, speed?: MotionSpeed): Presence<E>;
+
 type AlertProps = Omit<HTMLAttributes<HTMLDivElement>, "children" | "title"> & {
     variant?: "info" | "success" | "warning" | "danger";
     title?: Renderable;
@@ -115,6 +181,15 @@ declare function Alert({ variant, title, children, dismissible, onDismiss, class
 declare const Notice: typeof Alert;
 type NoticeProps = AlertProps;
 
+type AvatarGroupItem = Pick<AvatarProps, "src" | "name" | "status">;
+type AvatarGroupProps = Omit<HTMLAttributes<HTMLSpanElement>, "children"> & {
+    avatars: AvatarGroupItem[];
+    /** Avatars shown before collapsing the rest into a `+N` chip. */
+    max?: number;
+    size?: ControlSize;
+};
+declare function AvatarGroup({ avatars, max, size, className, ...props }: AvatarGroupProps): react.JSX.Element;
+
 type CardProps = Omit<HTMLAttributes<HTMLElement>, "children" | "title"> & {
     title?: Renderable;
     description?: Renderable;
@@ -126,6 +201,44 @@ type CardProps = Omit<HTMLAttributes<HTMLElement>, "children" | "title"> & {
 };
 declare function Card({ title, description, header, footer, children, interactive, selected, className, ...props }: CardProps): react.JSX.Element;
 
+type CollapsibleProps = Omit<HTMLAttributes<HTMLDivElement>, "children"> & {
+    trigger: Renderable;
+    children?: Renderable;
+    open?: boolean;
+    defaultOpen?: boolean;
+    onOpenChange?: (open: boolean) => void;
+    disabled?: boolean;
+};
+declare function Collapsible({ trigger, children, open, defaultOpen, onOpenChange, disabled, className, ...props }: CollapsibleProps): react.JSX.Element;
+
+type ComboboxOption = {
+    value: string;
+    label: Renderable;
+    disabled?: boolean;
+    /** Groups options under a heading; ungrouped options come first. */
+    group?: string;
+    /** Extra terms matched by the filter but never highlighted. */
+    keywords?: string;
+};
+type ComboboxProps = {
+    options: ComboboxOption[];
+    /** Single-select value. Omit it and pass `values` for multi-select. */
+    value?: string;
+    /** Multi-select values; selecting keeps the popup open. */
+    values?: string[];
+    onValueChange?: (value: string) => void;
+    onValuesChange?: (values: string[]) => void;
+    placeholder?: Renderable;
+    searchPlaceholder?: string;
+    emptyMessage?: Renderable;
+    disabled?: boolean;
+    size?: ControlSize;
+    id?: string;
+    ariaLabel?: string;
+    className?: string;
+};
+declare function Combobox({ options, value, values, onValueChange, onValuesChange, placeholder, searchPlaceholder, emptyMessage, disabled, size, id, ariaLabel, className, }: ComboboxProps): react.JSX.Element;
+
 type DialogProps = {
     open: boolean;
     onClose: () => void;
@@ -139,6 +252,22 @@ type DialogProps = {
 };
 declare function Dialog({ open, onClose, title, description, children, footer, closeLabel, closeOnOverlayClick, className, }: DialogProps): react.JSX.Element | null;
 
+type DrawerSide = "left" | "right" | "bottom";
+type DrawerProps = {
+    open: boolean;
+    onClose: () => void;
+    title: Renderable;
+    description?: Renderable;
+    children?: Renderable;
+    footer?: Renderable;
+    side?: DrawerSide;
+    size?: "sm" | "md" | "lg";
+    closeLabel?: string;
+    closeOnOverlayClick?: boolean;
+    className?: string;
+};
+declare function Drawer({ open, onClose, title, description, children, footer, side, size, closeLabel, closeOnOverlayClick, className, }: DrawerProps): react.JSX.Element | null;
+
 type FieldMessageProps = Omit<HTMLAttributes<HTMLParagraphElement>, "children"> & {
     variant?: "hint" | "error" | "success";
     children?: Renderable;
@@ -157,6 +286,21 @@ type FieldProps = {
 };
 declare function Field({ label, htmlFor, description, message, messageType, required, className, children, }: FieldProps): react.JSX.Element;
 
+type OverlaySide = "top" | "bottom" | "left" | "right";
+
+type HoverCardProps = {
+    trigger: Renderable;
+    children: Renderable;
+    /** Grace before opening, so passing the trigger never flickers. */
+    openDelay?: number;
+    /** Grace before closing, so the pointer can travel into the card. */
+    closeDelay?: number;
+    placement?: OverlaySide;
+    ariaLabel?: string;
+    className?: string;
+};
+declare function HoverCard({ trigger, children, openDelay, closeDelay, placement, ariaLabel, className, }: HoverCardProps): react.JSX.Element;
+
 type MenuItem = {
     value?: string;
     label?: Renderable;
@@ -286,6 +430,40 @@ type TooltipProps = {
 };
 declare function Tooltip({ content, children, side, delay, disabled, className, }: TooltipProps): react.JSX.Element;
 
+type CommandItem = {
+    id?: string;
+    label: Renderable;
+    /** Value reported to `onSelect` when omitted (falls back to the label). */
+    value?: string;
+    icon?: Renderable;
+    /** Groups options under a heading; ungrouped options always come first. */
+    group?: string;
+    /** Muted text trailing the option (chevrons are drawn for parents). */
+    hint?: Renderable;
+    badge?: Renderable;
+    shortcut?: string[];
+    /** Extra terms matched by the filter but never highlighted. */
+    keywords?: string;
+    disabled?: boolean;
+    /** Sub-options: activating this option drills into a new level. */
+    children?: CommandItem[];
+};
+type CommandPaletteProps = {
+    open: boolean;
+    onOpenChange: (open: boolean) => void;
+    items: CommandItem[];
+    onSelect?: (item: CommandItem) => void;
+    placeholder?: string;
+    emptyMessage?: Renderable;
+    /** Label of the breadcrumb that returns to the root level. */
+    homeLabel?: string;
+    ariaLabel?: string;
+    /** Bind Cmd/Ctrl+K to toggle the palette. Default: true. */
+    hotkey?: boolean;
+    className?: string;
+};
+declare function CommandPalette({ open, onOpenChange, items, onSelect, placeholder, emptyMessage, homeLabel, ariaLabel, hotkey, className, }: CommandPaletteProps): react.ReactPortal | null;
+
 type EmptyStateProps = Omit<HTMLAttributes<HTMLElement>, "children" | "title"> & {
     title: Renderable;
     description?: Renderable;
@@ -295,6 +473,98 @@ type EmptyStateProps = Omit<HTMLAttributes<HTMLElement>, "children" | "title"> &
 };
 declare function EmptyState({ title, description, icon, action, compact, className, ...props }: EmptyStateProps): react.JSX.Element;
 
+type MagneticDropzoneProps = Omit<React.HTMLAttributes<HTMLDivElement>, "onDrop" | "onDragOver" | "children"> & {
+    /** Idle content: an icon, instructions, a choose-file button. */
+    children?: Renderable;
+    /** Replaces `children` while files hover over the zone. */
+    activeContent?: Renderable;
+    onFiles?: (files: File[]) => void;
+    /** Forwarded to the hidden file input, e.g. "image/*,.pdf". */
+    accept?: string;
+    multiple?: boolean;
+    disabled?: boolean;
+    className?: string;
+};
+/**
+ * A drop zone whose content leans toward the pointer while files hover —
+ * the pull is a CSS variable updated on dragover, so the attraction stays
+ * cheap and collapses with the motion tokens.
+ */
+declare function MagneticDropzone({ children, activeContent, onFiles, accept, multiple, disabled, className, ...props }: MagneticDropzoneProps): react.JSX.Element;
+
+type ReasoningStep = {
+    id?: string;
+    title: Renderable;
+    detail?: Renderable;
+    status?: "pending" | "active" | "done";
+};
+type ReasoningStepsProps = {
+    steps: ReasoningStep[];
+    /** Header label. Default: "Reasoning". */
+    label?: Renderable;
+    open?: boolean;
+    defaultOpen?: boolean;
+    onOpenChange?: (open: boolean) => void;
+    className?: string;
+};
+declare function ReasoningSteps({ steps, label, open, defaultOpen, onOpenChange, className, }: ReasoningStepsProps): react.JSX.Element;
+
+type ResizableProps = Omit<HTMLAttributes<HTMLDivElement>, "children"> & {
+    /** The panes, in visual order. A handle is rendered between each pair. */
+    panes: Renderable[];
+    direction?: "horizontal" | "vertical";
+    /** Controlled pane sizes in percent; they should sum to 100. */
+    sizes?: number[];
+    defaultSizes?: number[];
+    onSizesChange?: (sizes: number[]) => void;
+    /** Smallest share a pane may keep, in percent. Default: 10. */
+    min?: number;
+    handleLabel?: string;
+};
+declare function Resizable({ panes, direction, sizes, defaultSizes, onSizesChange, min, handleLabel, className, ...props }: ResizableProps): react.JSX.Element;
+
+type SidebarItem = {
+    value: string;
+    label: Renderable;
+    icon?: Renderable;
+    badge?: Renderable;
+    disabled?: boolean;
+};
+type SidebarSection = {
+    title?: string;
+    items: SidebarItem[];
+};
+type SidebarProps = Omit<HTMLAttributes<HTMLElement>, "children" | "onSelect"> & {
+    sections: SidebarSection[];
+    /** Controlled active item. */
+    value?: string;
+    defaultValue?: string;
+    onSelect?: (value: string) => void;
+    header?: Renderable;
+    footer?: Renderable;
+    /** Show the collapse toggle. Default: false. */
+    collapsible?: boolean;
+    collapsed?: boolean;
+    defaultCollapsed?: boolean;
+    onCollapsedChange?: (collapsed: boolean) => void;
+    ariaLabel?: string;
+};
+declare function Sidebar({ sections, value, defaultValue, onSelect, header, footer, collapsible, collapsed, defaultCollapsed, onCollapsedChange, ariaLabel, className, ...props }: SidebarProps): react.JSX.Element;
+
+type StreamingTextProps = Omit<HTMLAttributes<HTMLDivElement>, "children"> & {
+    text: string;
+    /** Delay between word entrances, in ms. Default: 30. */
+    speed?: number;
+    /** Reveal words progressively. Default: true. */
+    animated?: boolean;
+};
+/**
+ * Words arrive one at a time — and because each word animates only when it
+ * mounts, appending to `text` streams naturally without any JS timing: the
+ * new words cascade in while finished ones stay put.
+ */
+declare function StreamingText({ text, speed, animated, className, ...props }: StreamingTextProps): react.JSX.Element;
+
 type TableColumn<Row extends Record<string, unknown> = Record<string, unknown>> = {
     key: string;
     label: Renderable;
@@ -315,4 +585,4 @@ type TableProps<Row extends Record<string, unknown> = Record<string, unknown>> =
 };
 declare function Table<Row extends Record<string, unknown> = Record<string, unknown>>({ columns, rows, caption, emptyMessage, rowKey, density, striped, stickyHeader, className, ...props }: TableProps<Row>): react.JSX.Element;
 
-export { Alert, type AlertProps, Badge, type BadgeProps, Button, type ButtonProps, Card, type CardProps, Checkbox, type CheckboxProps, type ControlSize, Dialog, type DialogProps, EmptyState, type EmptyStateProps, Field, FieldMessage, type FieldMessageProps, type FieldProps, IconButton, type IconButtonProps, Input, type InputProps, Menu, type MenuItem, type MenuProps, Notice, type NoticeProps, Popover, type PopoverProps, RadioGroup, type RadioGroupProps, type RadioOption, type Renderable, type RenderableElement, Select, type SelectOption, type SelectProps, Separator, type SeparatorProps, Skeleton, type SkeletonProps, Slider, type SliderProps, Spinner, type SpinnerProps, Surface, type SurfaceProps, type TabItem, Table, type TableColumn, type TableProps, Tabs, type TabsProps, Textarea, type TextareaProps, Toast, type ToastProps, ToastViewport, type ToastViewportProps, Toggle, type ToggleProps, Toolbar, type ToolbarProps, Tooltip, type TooltipProps };
+export { Alert, type AlertProps, Avatar, AvatarGroup, type AvatarGroupItem, type AvatarGroupProps, type AvatarProps, type AvatarStatus, Badge, type BadgeProps, Button, type ButtonProps, Card, type CardProps, Checkbox, type CheckboxProps, Collapsible, type CollapsibleProps, Combobox, type ComboboxOption, type ComboboxProps, type CommandItem, CommandPalette, type CommandPaletteProps, type ControlSize, Dialog, type DialogProps, Drawer, type DrawerProps, type DrawerSide, EmptyState, type EmptyStateProps, Field, FieldMessage, type FieldMessageProps, type FieldProps, HoverCard, type HoverCardProps, IconButton, type IconButtonProps, Input, type InputProps, Kbd, type KbdProps, MagneticDropzone, type MagneticDropzoneProps, Menu, type MenuItem, type MenuProps, type MotionSpeed, Notice, type NoticeProps, Popover, type PopoverProps, type Presence, Progress, type ProgressProps, RadioGroup, type RadioGroupProps, type RadioOption, type ReasoningStep, ReasoningSteps, type ReasoningStepsProps, type Renderable, type RenderableElement, Resizable, type ResizableProps, ScrollArea, type ScrollAreaProps, Select, type SelectOption, type SelectProps, Separator, type SeparatorProps, Sidebar, type SidebarItem, type SidebarProps, type SidebarSection, Skeleton, type SkeletonProps, Slider, type SliderProps, Spinner, type SpinnerProps, StreamingText, type StreamingTextProps, Surface, type SurfaceProps, type TabItem, Table, type TableColumn, type TableProps, Tabs, type TabsProps, Textarea, type TextareaProps, Toast, type ToastProps, ToastViewport, type ToastViewportProps, Toggle, type ToggleProps, Toolbar, type ToolbarProps, Tooltip, type TooltipProps, motionDurationMs, parseDurationMs, usePresence };