@xex/ui 0.0.0-stage → 0.1.1

package/dist/index.d.ts

@@ -0,0 +1,390 @@
+import * as react from 'react';
+import { ButtonHTMLAttributes, ReactNode, SelectHTMLAttributes, InputHTMLAttributes, KeyboardEvent, RefObject, ComponentType, SVGProps } from 'react';
+import { Theme, FontChoice } from '@xex/tokens';
+
+type ButtonVariant = 'primary' | 'secondary' | 'ghost' | 'danger' | 'outline';
+type ButtonSize = 'xs' | 'sm' | 'md' | 'lg';
+interface ButtonProps extends ButtonHTMLAttributes<HTMLButtonElement> {
+    variant?: ButtonVariant;
+    size?: ButtonSize;
+    loading?: boolean;
+    icon?: ReactNode;
+    iconRight?: ReactNode;
+}
+declare function Button({ variant, size, loading, icon, iconRight, disabled, className, children, type, ...rest }: ButtonProps): react.JSX.Element;
+
+type BadgeVariant = 'default' | 'success' | 'warning' | 'danger' | 'info' | 'purple' | 'gray';
+interface BadgeProps {
+    variant?: BadgeVariant;
+    dot?: boolean;
+    className?: string;
+    children: ReactNode;
+}
+declare function Badge({ variant, dot, className, children }: BadgeProps): react.JSX.Element;
+
+type ModalSize = 'sm' | 'md' | 'lg' | 'xl';
+interface ModalProps {
+    open: boolean;
+    onClose: () => void;
+    title?: ReactNode;
+    footer?: ReactNode;
+    size?: ModalSize;
+    /** Accessible name when there is no visible `title`. */
+    ariaLabel?: string;
+    children: ReactNode;
+}
+declare function Modal({ open, onClose, title, footer, size, ariaLabel, children }: ModalProps): react.JSX.Element | null;
+
+interface ConfirmDialogProps {
+    open: boolean;
+    title: string;
+    message: string;
+    confirmLabel?: string;
+    cancelLabel?: string;
+    loading?: boolean;
+    onConfirm: () => void;
+    onCancel: () => void;
+}
+declare function ConfirmDialog({ open, title, message, confirmLabel, cancelLabel, loading, onConfirm, onCancel, }: ConfirmDialogProps): react.JSX.Element;
+
+interface SelectOption {
+    value: string | number;
+    label: string;
+}
+interface SelectProps extends Omit<SelectHTMLAttributes<HTMLSelectElement>, 'children'> {
+    label?: string;
+    options: SelectOption[];
+    /** Renders a blank first option with this text. */
+    placeholder?: string;
+    error?: string;
+    hint?: string;
+}
+declare function Select({ label, options, placeholder, error, hint, className, id, disabled, ...rest }: SelectProps): react.JSX.Element;
+
+interface InputProps extends InputHTMLAttributes<HTMLInputElement> {
+    label?: string;
+    error?: string;
+    hint?: string;
+    /** Leading icon, absolutely positioned inside the field. */
+    icon?: ReactNode;
+}
+declare function Input({ label, error, hint, icon, className, id, ...rest }: InputProps): react.JSX.Element;
+
+type AvatarSize = 'xs' | 'sm' | 'md' | 'lg' | 'xl';
+/** Rotating palette, deliberately independent of the brand theme. */
+declare const AVATAR_COLORS: string[];
+declare function initialsOf(name: string): string;
+declare function colorFor(seed: string): string;
+interface AvatarProps {
+    name: string;
+    size?: AvatarSize;
+    /** Any hex; defaults to a stable color derived from the name. */
+    color?: string;
+    className?: string;
+}
+declare function Avatar({ name, size, color, className }: AvatarProps): react.JSX.Element;
+
+interface PaginationBarProps {
+    page: number;
+    totalPages: number;
+    total: number;
+    pageSize: number;
+    onPageChange: (page: number) => void;
+    pageSizeOptions?: number[];
+    onPageSizeChange?: (size: number) => void;
+    /**
+     * Where the bar sits relative to its table: 'above' / 'below' draw only the edge facing the
+     * table (so two bars can share one table); the default draws both edges.
+     */
+    placement?: 'above' | 'below';
+    /** Extra controls on the right (e.g. a density toggle), divided by a "|". */
+    right?: ReactNode;
+}
+/** 1 … 4 5 [6] 7 8 … 20 — null entries are ellipses. */
+declare function pageWindow(page: number, totalPages: number): (number | null)[];
+declare function PaginationBar({ page, totalPages, total, pageSize, onPageChange, pageSizeOptions, onPageSizeChange, right, placement, }: PaginationBarProps): react.JSX.Element;
+
+/** Three staggered fading dots; inherits currentColor. Animation lives in index.css. */
+declare function LoadingDots({ className }: {
+    className?: string;
+}): react.JSX.Element;
+
+interface SegmentedOption<T extends string> {
+    value: T;
+    label: string;
+}
+interface SegmentedControlProps<T extends string> {
+    options: SegmentedOption<T>[];
+    value: T;
+    onChange: (value: T) => void;
+    /** Accessible name for the group, e.g. "Row density". */
+    label: string;
+    className?: string;
+}
+/** Mutually exclusive options shown side by side, with the active one raised. Arrow keys move the choice. */
+declare function SegmentedControl<T extends string>({ options, value, onChange, label, className }: SegmentedControlProps<T>): react.JSX.Element;
+
+interface DataTableColumn<T> {
+    id: string;
+    header: string;
+    /** Plain value used for sorting, searching and filtering. */
+    accessor: (row: T) => string | number;
+    /** Custom cell content; defaults to the accessor's value. `dense` mirrors the density toggle. */
+    cell?: (row: T, ctx: {
+        dense: boolean;
+    }) => ReactNode;
+    /** Click-to-sort header. Default: true. */
+    sortable?: boolean;
+    /** Adds a multi-select dropdown listing this column's distinct values (OR within a column, AND across columns). Default: false. */
+    filter?: boolean;
+    /** Placeholder for that dropdown, e.g. "All roles". */
+    filterLabel?: string;
+    align?: 'left' | 'right';
+    /** Default width as a relative weight (a column with 2 starts twice as wide as one with 1). Default: 1. */
+    width?: number;
+}
+interface DataTableProps<T> {
+    columns: DataTableColumn<T>[];
+    rows: T[];
+    rowKey: (row: T) => string | number;
+    /** Accessible name for the table. */
+    label: string;
+    /** Search box (matches any column). Default: true. */
+    searchable?: boolean;
+    searchPlaceholder?: string;
+    pageSizeOptions?: number[];
+    defaultPageSize?: number;
+    initialSort?: {
+        columnId: string;
+        direction: 'asc' | 'desc';
+    };
+    emptyMessage?: string;
+}
+/**
+ * Standard table: click-to-sort headers, global search, per-column dropdown filters,
+ * pagination (above and below) and a density toggle. Switch parts off per column or via props.
+ */
+declare function DataTable<T>({ columns, rows, rowKey, label, searchable, searchPlaceholder, pageSizeOptions, defaultPageSize, initialSort, emptyMessage, }: DataTableProps<T>): react.JSX.Element;
+
+interface MultiSelectOption {
+    value: string;
+    label: string;
+    /** Optional count shown beside the label. */
+    count?: number;
+}
+interface MultiSelectProps {
+    options: MultiSelectOption[];
+    value: string[];
+    onChange: (value: string[]) => void;
+    /** Text shown (and used as the accessible name) when nothing is selected, e.g. "All roles". */
+    label: string;
+    className?: string;
+}
+/** Dropdown with a checkbox per option. Esc / outside click / tabbing away closes it. */
+declare function MultiSelect({ options, value, onChange, label, className }: MultiSelectProps): react.JSX.Element;
+
+type SpinnerSize = 'xs' | 'sm' | 'md' | 'lg' | 'xl';
+interface SpinnerProps {
+    size?: SpinnerSize;
+    /** Accessible name; ignored when `decorative`. */
+    label?: string;
+    /** Hide from assistive tech (use when the surrounding text already says "loading"). */
+    decorative?: boolean;
+    className?: string;
+}
+/** Rotating ring. Inherits currentColor, so colour it with a text-* class. */
+declare function Spinner({ size, label, decorative, className }: SpinnerProps): react.JSX.Element;
+
+type ProgressTone = 'brand' | 'success' | 'warning' | 'danger';
+declare const heights: {
+    sm: string;
+    md: string;
+    lg: string;
+};
+interface ProgressBarProps {
+    /** 0–100. Omit for an indeterminate ("working, no idea how long") bar. */
+    value?: number;
+    /** Accessible name (also shown above the bar when `showLabel`). */
+    label: string;
+    showLabel?: boolean;
+    tone?: ProgressTone;
+    size?: keyof typeof heights;
+    className?: string;
+}
+declare function ProgressBar({ value, label, showLabel, tone, size, className }: ProgressBarProps): react.JSX.Element;
+interface ProgressRingProps {
+    /** 0–100. Omit for an indeterminate spinning arc. */
+    value?: number;
+    label: string;
+    /** Diameter in px. */
+    size?: number;
+    tone?: ProgressTone;
+    /** Show the percentage in the middle (determinate only). */
+    showValue?: boolean;
+}
+declare function ProgressRing({ value, label, size, tone, showValue }: ProgressRingProps): react.JSX.Element;
+
+interface SkeletonProps {
+    shape?: 'text' | 'circle' | 'rect';
+    /** Size via Tailwind classes, e.g. "h-10 w-10". Text defaults to a full-width line. */
+    className?: string;
+}
+/** Grey placeholder block that pulses. Decorative: put `aria-busy` on the region being loaded. */
+declare function Skeleton({ shape, className }: SkeletonProps): react.JSX.Element;
+/** A paragraph of skeleton lines; the last one is shorter. */
+declare function SkeletonText({ lines, className }: {
+    lines?: number;
+    className?: string;
+}): react.JSX.Element;
+
+interface LoadingOverlayProps {
+    loading: boolean;
+    /** Shown beside the spinner and used as its accessible name. */
+    label?: string;
+    children: ReactNode;
+    className?: string;
+}
+/** Dims and blocks its content while loading, with a centred spinner. Content stays mounted. */
+declare function LoadingOverlay({ loading, label, children, className }: LoadingOverlayProps): react.JSX.Element;
+
+type FetchState = 'idle' | 'loading' | 'success' | 'error';
+interface FetchStatusProps {
+    state: FetchState;
+    /** Override the default message for any state. */
+    messages?: Partial<Record<FetchState, string>>;
+    onRetry?: () => void;
+}
+/** One-line status for a data request: idle → loading → success | error (with retry). Announced politely. */
+declare function FetchStatus({ state, messages, onRetry }: FetchStatusProps): react.JSX.Element;
+
+interface TabItem {
+    id: string;
+    label: ReactNode;
+    icon?: ReactNode;
+    /** Small trailing count or tag, e.g. 12. */
+    badge?: ReactNode;
+    disabled?: boolean;
+    /** Panel content. Omit if you render panels yourself and only use the tab strip. */
+    content?: ReactNode;
+}
+interface TabsProps {
+    items: TabItem[];
+    /** Controlled selection. Pair with `onChange`. */
+    value?: string;
+    /** Initial selection when uncontrolled. Defaults to the first enabled tab. */
+    defaultValue?: string;
+    onChange?: (id: string) => void;
+    /** `underline` (default) slides a line under the active tab; `pills` fills it. */
+    variant?: 'underline' | 'pills';
+    size?: 'sm' | 'md';
+    /** `auto`: arrow keys select as they move focus. `manual`: arrows only move focus; Enter/Space select. */
+    activation?: 'auto' | 'manual';
+    /** Keep inactive panels mounted (hidden) so their state survives switching. Default: unmount. */
+    keepMounted?: boolean;
+    /** Stretch tabs to share the full width. */
+    fullWidth?: boolean;
+    /** Accessible name for the tab list. */
+    label: string;
+    className?: string;
+}
+declare function Tabs({ items, value, defaultValue, onChange, variant, size, activation, keepMounted, fullWidth, label, className, }: TabsProps): react.JSX.Element;
+
+declare const focusablesIn: (root: HTMLElement) => HTMLElement[];
+/**
+ * Keyboard handling for a `role="radiogroup"` container: arrows (and Home/End)
+ * move focus AND selection, wrapping at the ends. Pair with roving tabindex on
+ * the items (`tabIndex={selected ? 0 : -1}`) so the group is a single Tab stop.
+ */
+declare function radioGroupKeyDown(e: KeyboardEvent<HTMLElement>): void;
+/**
+ * Dialog focus management: scroll lock, move focus in on open, restore it to the
+ * opener on close, and a Tab trap. Spread the returned handler on the panel.
+ */
+declare function useDialogFocus(open: boolean, panelRef: RefObject<HTMLElement | null>, options?: {
+    initialFocus?: () => HTMLElement | null | undefined;
+    lockScroll?: boolean;
+}): (e: KeyboardEvent<HTMLElement>) => void;
+
+interface HeaderProps {
+    title: string;
+    subtitle?: string;
+    actions?: ReactNode;
+    /** Opens the navigation drawer; the button only shows below lg. */
+    onMenu?: () => void;
+}
+declare function Header({ title, subtitle, actions, onMenu }: HeaderProps): react.JSX.Element;
+
+/** One entry in a page's "On this page" guide. */
+interface PageSection {
+    id: string;
+    label: string;
+}
+declare function Section({ id, title, description, children }: {
+    id: string;
+    title: string;
+    description?: string;
+    children: ReactNode;
+}): react.JSX.Element;
+
+/**
+ * Floating "On this page" guide (xl+ only). The marker's position is a continuous function of
+ * the page's scroll position, so it glides with the page instead of hopping between items.
+ * The rail itself is a pointer scrubber: press or drag it to scroll the page. It is hidden from
+ * assistive tech and the tab order; the links below it are the keyboard / screen-reader route.
+ */
+declare function PageGuide({ sections }: {
+    sections: PageSection[];
+}): react.JSX.Element;
+
+interface NavEntry {
+    id: string;
+    label: string;
+    icon: ComponentType<SVGProps<SVGSVGElement>>;
+}
+interface SidebarProps {
+    items: NavEntry[];
+    active: string;
+    onSelect: (id: string) => void;
+    /** Mobile drawer state; ignored at lg+, where the sidebar is always visible. */
+    open: boolean;
+    onClose: () => void;
+}
+/** App navigation: persistent at lg+, slide-over drawer below. */
+declare function Sidebar({ items, active, onSelect, open, onClose }: SidebarProps): react.JSX.Element;
+
+type ColorMode = 'light' | 'dark';
+interface ThemeContextValue {
+    theme: Theme;
+    themes: Theme[];
+    setThemeId: (id: string) => void;
+    mode: ColorMode;
+    setMode: (mode: ColorMode) => void;
+    toggleMode: () => void;
+    font: FontChoice;
+    /** Most recently used fonts, newest first (max 5). */
+    recentFonts: FontChoice[];
+    setFont: (font: FontChoice) => void;
+}
+interface ThemeProviderProps {
+    children: ReactNode;
+    /**
+     * Prefix for the localStorage keys (`<prefix>-theme`, `<prefix>-mode`, `<prefix>-font`, …).
+     * Give every app its own prefix: apps on one domain would otherwise overwrite each other's choices.
+     */
+    storagePrefix?: string;
+    /** Themes to offer. Defaults to the built-in XeX presets. */
+    themes?: Theme[];
+    /** Theme used until the user picks one. */
+    defaultThemeId?: string;
+    /** Font used until the user picks one. */
+    defaultFont?: FontChoice;
+}
+declare function ThemeProvider({ children, storagePrefix, themes, defaultThemeId, defaultFont, }: ThemeProviderProps): react.JSX.Element;
+declare function useTheme(): ThemeContextValue;
+
+/** Swatch per theme + light/dark toggle. */
+declare function ThemeSwitcher({ showLabels }: {
+    showLabels?: boolean;
+}): react.JSX.Element;
+
+export { AVATAR_COLORS, Avatar, type AvatarProps, type AvatarSize, Badge, type BadgeProps, type BadgeVariant, Button, type ButtonProps, type ButtonSize, type ButtonVariant, type ColorMode, ConfirmDialog, type ConfirmDialogProps, DataTable, type DataTableColumn, type DataTableProps, type FetchState, FetchStatus, type FetchStatusProps, Header, Input, type InputProps, LoadingDots, LoadingOverlay, type LoadingOverlayProps, Modal, type ModalProps, type ModalSize, MultiSelect, type MultiSelectOption, type MultiSelectProps, type NavEntry, PageGuide, type PageSection, PaginationBar, type PaginationBarProps, ProgressBar, type ProgressBarProps, ProgressRing, type ProgressRingProps, type ProgressTone, Section, SegmentedControl, type SegmentedControlProps, type SegmentedOption, Select, type SelectOption, type SelectProps, Sidebar, Skeleton, type SkeletonProps, SkeletonText, Spinner, type SpinnerProps, type SpinnerSize, type TabItem, Tabs, type TabsProps, type ThemeContextValue, ThemeProvider, type ThemeProviderProps, ThemeSwitcher, colorFor, focusablesIn, initialsOf, pageWindow, radioGroupKeyDown, useDialogFocus, useTheme };