xertica-ui 2.1.2 → 2.1.3

package/dist/components/ui/chart/chart.d.ts

@@ -34,6 +34,8 @@ export type ChartPeriod = {
     label: string;
 };
 export type ChartBarSize = "sm" | "md" | "lg" | "xl" | number;
+/** Curve interpolation type for line and area charts */
+export type ChartCurveType = "monotone" | "linear" | "step" | "stepBefore" | "stepAfter" | "natural" | "basis";
 type ChartValueFormatter = (value: number | string) => string;
 export type ChartErrorState = boolean | string | Error | React.ReactNode;
 export type ChartStateProps = {
@@ -113,9 +115,11 @@ export interface DashboardLineChartProps extends Omit<React.ComponentProps<typeo
     showDots?: boolean;
     showGrid?: boolean;
     showLegend?: boolean;
+    curveType?: ChartCurveType;
+    strokeWidth?: number;
     valueFormatter?: ChartValueFormatter;
 }
-declare function DashboardLineChart({ data, config, indexKey, series, colors, showDots, showGrid, showLegend, valueFormatter, isLoading, error, onRetry, retryLabel, emptyTitle, emptyDescription, errorTitle, errorDescription, loadingLabel, stateClassName, className, ...props }: DashboardLineChartProps): import("react/jsx-runtime").JSX.Element;
+declare function DashboardLineChart({ data, config, indexKey, series, colors, showDots, showGrid, showLegend, curveType, strokeWidth, valueFormatter, isLoading, error, onRetry, retryLabel, emptyTitle, emptyDescription, errorTitle, errorDescription, loadingLabel, stateClassName, className, ...props }: DashboardLineChartProps): import("react/jsx-runtime").JSX.Element;
 export interface HorizontalBarChartProps extends Omit<React.ComponentProps<typeof ChartContainer>, "children">, ChartStateProps {
     data: DashboardChartDatum[];
     indexKey?: string;
@@ -140,9 +144,13 @@ export interface InteractiveTimeSeriesChartProps extends Omit<React.ComponentPro
     filterData?: (data: DashboardChartDatum[], period: string) => DashboardChartDatum[];
     showGrid?: boolean;
     showLegend?: boolean;
+    showDots?: boolean;
+    gradientFill?: boolean;
+    curveType?: ChartCurveType;
+    strokeWidth?: number;
     valueFormatter?: ChartValueFormatter;
 }
-declare function InteractiveTimeSeriesChart({ data, config, indexKey, series, colors, periods, defaultPeriod, defaultSeries, filterData, showGrid, showLegend, valueFormatter, isLoading, error, onRetry, retryLabel, emptyTitle, emptyDescription, errorTitle, errorDescription, loadingLabel, stateClassName, className, ...props }: InteractiveTimeSeriesChartProps): import("react/jsx-runtime").JSX.Element;
+declare function InteractiveTimeSeriesChart({ data, config, indexKey, series, colors, periods, defaultPeriod, defaultSeries, filterData, showGrid, showLegend, showDots, gradientFill, curveType, strokeWidth, valueFormatter, isLoading, error, onRetry, retryLabel, emptyTitle, emptyDescription, errorTitle, errorDescription, loadingLabel, stateClassName, className, ...props }: InteractiveTimeSeriesChartProps): import("react/jsx-runtime").JSX.Element;
 export interface ComboMetricChartProps extends Omit<React.ComponentProps<typeof ChartContainer>, "children">, ChartStateProps {
     data: DashboardChartDatum[];
     indexKey?: string;
@@ -151,9 +159,11 @@ export interface ComboMetricChartProps extends Omit<React.ComponentProps<typeof
     barSize?: ChartBarSize;
     showGrid?: boolean;
     showLegend?: boolean;
+    gradientFill?: boolean;
+    curveType?: ChartCurveType;
     valueFormatter?: ChartValueFormatter;
 }
-declare function ComboMetricChart({ data, config, indexKey, series, colors, barSize, showGrid, showLegend, valueFormatter, isLoading, error, onRetry, retryLabel, emptyTitle, emptyDescription, errorTitle, errorDescription, loadingLabel, stateClassName, className, ...props }: ComboMetricChartProps): import("react/jsx-runtime").JSX.Element;
+declare function ComboMetricChart({ data, config, indexKey, series, colors, barSize, showGrid, showLegend, gradientFill, curveType, valueFormatter, isLoading, error, onRetry, retryLabel, emptyTitle, emptyDescription, errorTitle, errorDescription, loadingLabel, stateClassName, className, ...props }: ComboMetricChartProps): import("react/jsx-runtime").JSX.Element;
 export interface DonutBreakdownChartProps extends Omit<React.ComponentProps<typeof ChartContainer>, "children">, ChartStateProps {
     data: DashboardChartDatum[];
     nameKey?: string;
@@ -162,6 +172,153 @@ export interface DonutBreakdownChartProps extends Omit<React.ComponentProps<type
     centerLabel?: React.ReactNode;
     centerValue?: React.ReactNode;
     showLegend?: boolean;
+    /** Inner radius as percentage string (e.g. "58%") or number */
+    innerRadius?: string | number;
+    /** Outer radius as percentage string (e.g. "82%") or number */
+    outerRadius?: string | number;
+}
+declare function DonutBreakdownChart({ data, config, nameKey, valueKey, colors, centerLabel, centerValue, showLegend, innerRadius, outerRadius, isLoading, error, onRetry, retryLabel, emptyTitle, emptyDescription, errorTitle, errorDescription, loadingLabel, stateClassName, className, ...props }: DonutBreakdownChartProps): import("react/jsx-runtime").JSX.Element;
+export interface SparklineChartProps {
+    /** Data array — each item must have the `dataKey` field */
+    data: DashboardChartDatum[];
+    /** Key to plot on the Y axis */
+    dataKey: string;
+    /** Color for the line/area — defaults to `var(--chart-1)` */
+    color?: string;
+    /** Show filled area under the line */
+    filled?: boolean;
+    /** Show the last data point as a dot */
+    showEndDot?: boolean;
+    /** Curve interpolation type */
+    curveType?: ChartCurveType;
+    /** Stroke width */
+    strokeWidth?: number;
+    className?: string;
+}
+/**
+ * Minimal inline sparkline chart — no axes, no grid, no tooltip.
+ * Ideal for embedding inside stat cards or table cells.
+ *
+ * @ai-rules
+ * - Use `filled` for area-style sparklines.
+ * - Keep `className` height small (e.g. `h-12` or `h-16`).
+ * - Do NOT wrap in `ChartCard` — it is designed to be inline.
+ */
+declare function SparklineChart({ data, dataKey, color, filled, showEndDot, curveType, strokeWidth, className, }: SparklineChartProps): import("react/jsx-runtime").JSX.Element;
+export interface RadarMetricChartProps extends ChartStateProps {
+    /** Data array — each item is one axis point on the radar */
+    data: DashboardChartDatum[];
+    /** Key in each datum used as the axis label */
+    labelKey: string;
+    /**
+     * Series to render. Each entry maps to one `<Radar>` element.
+     * Use a single entry for a simple radar, multiple for comparison.
+     */
+    series: DashboardChartSeries[];
+    /** Override colors per series key or as an ordered array */
+    colors?: DashboardChartColors;
+    /** Fill the radar polygon (default: true) */
+    filled?: boolean;
+    /** Fill opacity when `filled` is true (default: 0.25) */
+    fillOpacity?: number;
+    /** Show dots on each axis point (default: false) */
+    showDots?: boolean;
+    /** Show the polar grid lines (default: true) */
+    showGrid?: boolean;
+    /** Show the legend (default: true when multiple series) */
+    showLegend?: boolean;
+    /** Format axis tick values */
+    valueFormatter?: ChartValueFormatter;
+    className?: string;
+}
+declare function RadarMetricChart({ data, labelKey, series, colors, filled, fillOpacity, showDots, showGrid, showLegend, valueFormatter, isLoading, error, onRetry, retryLabel, emptyTitle, emptyDescription, errorTitle, errorDescription, loadingLabel, stateClassName, className, }: RadarMetricChartProps): import("react/jsx-runtime").JSX.Element;
+export interface PieMetricChartProps extends ChartStateProps {
+    /** Data array — each item is one slice */
+    data: DashboardChartDatum[];
+    /** Key in each datum used as the slice name/label */
+    nameKey: string;
+    /** Key in each datum used as the slice value */
+    valueKey: string;
+    /** Override colors as an ordered array or per-name map */
+    colors?: DashboardChartColors;
+    /** Outer radius of the pie (default: "80%") */
+    outerRadius?: number | string;
+    /** Inner radius — set > 0 to make a donut (default: 0) */
+    innerRadius?: number | string;
+    /** Show percentage labels inside/outside each slice (default: false) */
+    showLabels?: boolean;
+    /** Show the legend (default: true) */
+    showLegend?: boolean;
+    /**
+     * Index of the slice to "explode" (offset outward).
+     * Pass -1 or undefined to disable.
+     */
+    explodeIndex?: number;
+    /** Offset distance for the exploded slice in px (default: 12) */
+    explodeOffset?: number;
+    /** Format tooltip values */
+    valueFormatter?: ChartValueFormatter;
+    className?: string;
+}
+declare function PieMetricChart({ data, nameKey, valueKey, colors, outerRadius, innerRadius, showLabels, showLegend, explodeIndex, explodeOffset, valueFormatter, isLoading, error, onRetry, retryLabel, emptyTitle, emptyDescription, errorTitle, errorDescription, loadingLabel, stateClassName, className, }: PieMetricChartProps): import("react/jsx-runtime").JSX.Element;
+export interface RadialBarMetricChartProps extends ChartStateProps {
+    /**
+     * Data array. Each item should have a `name` field (for labels) and
+     * the `dataKey` field (for values, 0–100 for percentage-based display).
+     */
+    data: DashboardChartDatum[];
+    /** Key in each datum used as the bar value (default: "value") */
+    dataKey?: string;
+    /** Key in each datum used as the bar label (default: "name") */
+    nameKey?: string;
+    /** Override colors as an ordered array or per-name map */
+    colors?: DashboardChartColors;
+    /** Inner radius of the radial bar (default: "30%") */
+    innerRadius?: number | string;
+    /** Outer radius of the radial bar (default: "100%") */
+    outerRadius?: number | string;
+    /** Start angle in degrees (default: 90 — top) */
+    startAngle?: number;
+    /** End angle in degrees (default: -270 — full circle) */
+    endAngle?: number;
+    /** Show background track behind each bar (default: true) */
+    showBackground?: boolean;
+    /** Show the legend (default: true) */
+    showLegend?: boolean;
+    /** Format tooltip values */
+    valueFormatter?: ChartValueFormatter;
+    className?: string;
+}
+declare function RadialBarMetricChart({ data, dataKey, nameKey, colors, innerRadius, outerRadius, startAngle, endAngle, showBackground, showLegend, valueFormatter, isLoading, error, onRetry, retryLabel, emptyTitle, emptyDescription, errorTitle, errorDescription, loadingLabel, stateClassName, className, }: RadialBarMetricChartProps): import("react/jsx-runtime").JSX.Element;
+export interface GaugeChartThreshold {
+    /** Upper bound of this zone (0–100) */
+    value: number;
+    /** Color for this zone */
+    color: string;
+    /** Optional label for this zone */
+    label?: string;
+}
+export interface GaugeChartProps {
+    /** Current value (must be within [min, max]) */
+    value: number;
+    /** Minimum value (default: 0) */
+    min?: number;
+    /** Maximum value (default: 100) */
+    max?: number;
+    /**
+     * Color zones. Each threshold defines the upper bound of a zone.
+     * Zones are evaluated in order; the first zone whose `value >= current %`
+     * determines the active color.
+     * If omitted, uses `--chart-1`.
+     */
+    thresholds?: GaugeChartThreshold[];
+    /** Label shown below the value (e.g. "CPU Usage") */
+    label?: React.ReactNode;
+    /** Format the center value text (default: shows percentage) */
+    valueFormatter?: (value: number, percent: number) => string;
+    /** Show the needle indicator (default: true) */
+    showNeedle?: boolean;
+    className?: string;
 }
-declare function DonutBreakdownChart({ data, config, nameKey, valueKey, colors, centerLabel, centerValue, showLegend, isLoading, error, onRetry, retryLabel, emptyTitle, emptyDescription, errorTitle, errorDescription, loadingLabel, stateClassName, className, ...props }: DonutBreakdownChartProps): import("react/jsx-runtime").JSX.Element;
-export { ChartContainer, ChartTooltip, ChartTooltipContent, ChartLegend, ChartLegendContent, ChartStyle, ChartCard, DashboardBarChart, DashboardLineChart, HorizontalBarChart, InteractiveTimeSeriesChart, ComboMetricChart, DonutBreakdownChart, };
+declare function GaugeChart({ value, min, max, thresholds, label, valueFormatter, showNeedle, className, }: GaugeChartProps): import("react/jsx-runtime").JSX.Element;
+export { ChartContainer, ChartTooltip, ChartTooltipContent, ChartLegend, ChartLegendContent, ChartStyle, ChartCard, DashboardBarChart, DashboardLineChart, HorizontalBarChart, InteractiveTimeSeriesChart, ComboMetricChart, DonutBreakdownChart, SparklineChart, RadarMetricChart, PieMetricChart, RadialBarMetricChart, GaugeChart, };

package/dist/components/ui/file-upload/file-upload.d.ts

@@ -15,6 +15,8 @@ interface FileUploadProps extends Omit<React.InputHTMLAttributes<HTMLInputElemen
  * for file uploads. Supports click-to-browse and drag-and-drop. Shows a preview
  * list of selected files with per-file remove buttons.
  *
+ * Headless logic is available via `useFileUpload` for custom drop-zone UIs.
+ *
  * @ai-rules
  * 1. Use `onFilesChange` to capture the selected files array in your form state.
  * 2. `maxFiles` defaults to 1 (single file). Set to a higher number for multi-upload.

package/dist/components/ui/file-upload/index.d.ts

@@ -1 +1,2 @@
 export * from './file-upload';
+export * from './use-file-upload';

package/dist/components/ui/file-upload/use-file-upload.d.ts

@@ -0,0 +1,49 @@
+export interface UseFileUploadProps {
+    /** Maximum number of files allowed. @default 1 */
+    maxFiles?: number;
+    /** Maximum file size in bytes. @default 5MB */
+    maxSize?: number;
+    /** Called with the current accepted file list whenever it changes. */
+    onFilesChange?: (files: File[]) => void;
+    /** Called when files are rejected due to size or count limits. */
+    onError?: (rejectedFiles: File[], reason: 'size' | 'count') => void;
+    /** Whether the upload area is disabled. */
+    disabled?: boolean;
+}
+export interface UseFileUploadReturn {
+    /** Currently accepted files. */
+    files: File[];
+    /** Whether a drag operation is currently active over the drop zone. */
+    dragActive: boolean;
+    /** Inline error message, or `null` when there is no error. */
+    errorMessage: string | null;
+    /** Attach to the hidden `<input type="file">` element. */
+    inputRef: React.RefObject<HTMLInputElement>;
+    /** Process a `FileList` from any source (input change, drop, paste, etc.). */
+    handleFiles: (newFiles: FileList | null) => void;
+    /** Drag enter / over / leave handler — attach to all three events. */
+    handleDrag: (e: React.DragEvent) => void;
+    /** Drop handler — attach to the drop zone element. */
+    handleDrop: (e: React.DragEvent) => void;
+    /** Input `onChange` handler — attach to the hidden `<input>`. */
+    handleChange: (e: React.ChangeEvent<HTMLInputElement>) => void;
+    /** Remove a file by its index in the `files` array. */
+    removeFile: (index: number) => void;
+    /** Programmatically open the native file picker dialog. */
+    openFileDialog: () => void;
+}
+/**
+ * Headless hook for drag-and-drop file upload logic.
+ *
+ * @description
+ * Encapsulates all stateful behaviour for a file upload area: file validation
+ * (size and count limits), drag-active tracking, error messaging, and the
+ * hidden-input ref. Pair with any custom drop-zone UI.
+ *
+ * @example
+ * ```tsx
+ * const { files, dragActive, errorMessage, inputRef, handleDrag, handleDrop, handleChange, removeFile, openFileDialog } =
+ *   useFileUpload({ maxFiles: 3, maxSize: 10 * 1024 * 1024 });
+ * ```
+ */
+export declare function useFileUpload({ maxFiles, maxSize, onFilesChange, onError, disabled, }?: UseFileUploadProps): UseFileUploadReturn;

package/dist/components/ui/pagination/index.d.ts

@@ -1 +1,3 @@
 export * from './pagination';
+export { usePagination } from './use-pagination';
+export type { PaginationPageItem, UsePaginationProps, UsePaginationReturn } from './use-pagination';

package/dist/components/ui/pagination/use-pagination.d.ts

@@ -0,0 +1,78 @@
+/** A page item rendered in the pagination bar. */
+export type PaginationPageItem = {
+    type: 'page';
+    page: number;
+} | {
+    type: 'ellipsis';
+    key: string;
+};
+export interface UsePaginationProps {
+    /** Total number of items in the data set. */
+    totalItems: number;
+    /** Number of items per page. @default 10 */
+    pageSize?: number;
+    /** Initial page (1-indexed). @default 1 */
+    initialPage?: number;
+    /**
+     * Controlled current page (1-indexed).
+     * When provided, page state is managed externally via `onPageChange`.
+     */
+    page?: number;
+    /** Called whenever the page changes. */
+    onPageChange?: (page: number) => void;
+    /**
+     * Number of page buttons to show on each side of the current page.
+     * @default 1
+     */
+    siblingCount?: number;
+}
+export interface UsePaginationReturn {
+    /** The currently active page (1-indexed). */
+    currentPage: number;
+    /** Total number of pages. */
+    totalPages: number;
+    /** Index of the first item on the current page (0-indexed, useful for slicing). */
+    startIndex: number;
+    /** Index of the last item on the current page (exclusive, useful for slicing). */
+    endIndex: number;
+    /** Whether there is a previous page available. */
+    canGoPrev: boolean;
+    /** Whether there is a next page available. */
+    canGoNext: boolean;
+    /** Whether the current page is the first page. */
+    isFirstPage: boolean;
+    /** Whether the current page is the last page. */
+    isLastPage: boolean;
+    /**
+     * Ordered list of items to render in the pagination bar.
+     * Each item is either a `{ type: 'page', page: number }` or
+     * `{ type: 'ellipsis', key: string }`.
+     */
+    items: PaginationPageItem[];
+    /** Navigate to a specific page (1-indexed, clamped to valid range). */
+    goTo: (page: number) => void;
+    /** Navigate to the next page (no-op if already on the last page). */
+    next: () => void;
+    /** Navigate to the previous page (no-op if already on the first page). */
+    prev: () => void;
+    /** Navigate to the first page. */
+    first: () => void;
+    /** Navigate to the last page. */
+    last: () => void;
+}
+/**
+ * Headless hook for pagination logic.
+ *
+ * @description
+ * Computes the current page, total pages, slice indices, and the ordered list
+ * of page items (numbers + ellipses) to render. Supports both controlled and
+ * uncontrolled modes. Pair with any custom pagination UI or with the
+ * `<Pagination>` visual components.
+ *
+ * @example
+ * ```tsx
+ * const { currentPage, totalPages, items, next, prev, goTo, canGoPrev, canGoNext } =
+ *   usePagination({ totalItems: 200, pageSize: 20 });
+ * ```
+ */
+export declare function usePagination({ totalItems, pageSize, initialPage, page: controlledPage, onPageChange, siblingCount, }: UsePaginationProps): UsePaginationReturn;

package/dist/components/ui/rich-text-editor/index.d.ts

@@ -1 +1,3 @@
 export * from './rich-text-editor';
+export { useRichTextEditor } from './use-rich-text-editor';
+export type { UseRichTextEditorProps, UseRichTextEditorReturn, ActiveFormats } from './use-rich-text-editor';

package/dist/components/ui/rich-text-editor/use-rich-text-editor.d.ts

@@ -0,0 +1,107 @@
+export interface ActiveFormats {
+    bold: boolean;
+    italic: boolean;
+    underline: boolean;
+    justifyLeft: boolean;
+    justifyCenter: boolean;
+    justifyRight: boolean;
+    insertUnorderedList: boolean;
+    insertOrderedList: boolean;
+    link: boolean;
+    h1: boolean;
+    h2: boolean;
+    h3: boolean;
+    p: boolean;
+}
+export interface UseRichTextEditorProps {
+    /** Current HTML value of the editor */
+    value: string;
+    /** Called whenever the editor content changes */
+    onChange?: (value: string) => void;
+}
+export interface UseRichTextEditorReturn {
+    /** Attach to the `contenteditable` div */
+    editorRef: React.RefObject<HTMLDivElement>;
+    /** Attach to the search `<input>` */
+    searchInputRef: React.RefObject<HTMLInputElement>;
+    /** Attach to the link URL `<input>` */
+    linkInputRef: React.RefObject<HTMLInputElement>;
+    /** Map of currently active formatting commands */
+    activeFormats: ActiveFormats;
+    /** Whether the inline search bar is open */
+    isSearchOpen: boolean;
+    setIsSearchOpen: (open: boolean) => void;
+    /** Current search query string */
+    searchQuery: string;
+    setSearchQuery: (query: string) => void;
+    /** Current link URL being edited */
+    linkUrl: string;
+    setLinkUrl: (url: string) => void;
+    /** Whether the link popover is open */
+    isLinkOpen: boolean;
+    /**
+     * True when the popover was opened with a non-collapsed text selection
+     * (or with the cursor inside an existing link). Use this to decide whether
+     * to show the link-insert form vs. the "select text first" hint.
+     */
+    hasSavedSelection: boolean;
+    /** Word count of the editor content */
+    wordCount: number;
+    /** Character count of the editor content */
+    characterCount: number;
+    /** Re-read the current selection and update `activeFormats` */
+    updateActiveFormats: () => void;
+    /** Execute a `document.execCommand` and sync state */
+    execCommand: (command: string, value?: string) => void;
+    /** Called on every `input` event of the editor */
+    handleInput: () => void;
+    /** Search forward or backward for `searchQuery` */
+    performSearch: (text: string, backward?: boolean) => void;
+    /** Create or update a hyperlink at the current selection */
+    handleCreateLink: () => void;
+    /** Remove the hyperlink at the current cursor position */
+    handleUnlink: () => void;
+    /** Handle link popover open/close (saves selection, pre-fills URL) */
+    onLinkPopoverOpenChange: (open: boolean) => void;
+}
+/**
+ * `useRichTextEditor` — Headless hook for the RichTextEditor component.
+ *
+ * Encapsulates all state, refs, and DOM-manipulation logic for a
+ * `contenteditable`-based rich text editor. Use this hook when you need to
+ * build a fully custom editor UI while reusing the same formatting logic as
+ * the default `RichTextEditor` component.
+ *
+ * @example
+ * ```tsx
+ * import { useRichTextEditor } from 'xertica-ui/ui';
+ *
+ * function MyEditor({ value, onChange }) {
+ *   const {
+ *     editorRef,
+ *     activeFormats,
+ *     execCommand,
+ *     handleInput,
+ *     wordCount,
+ *   } = useRichTextEditor({ value, onChange });
+ *
+ *   return (
+ *     <div>
+ *       <button
+ *         onClick={() => execCommand('bold')}
+ *         style={{ fontWeight: activeFormats.bold ? 'bold' : 'normal' }}
+ *       >
+ *         B
+ *       </button>
+ *       <div
+ *         ref={editorRef}
+ *         contentEditable
+ *         onInput={handleInput}
+ *       />
+ *       <span>{wordCount} words</span>
+ *     </div>
+ *   );
+ * }
+ * ```
+ */
+export declare function useRichTextEditor({ value, onChange, }: UseRichTextEditorProps): UseRichTextEditorReturn;

package/dist/components/ui/stepper/index.d.ts

@@ -1 +1,3 @@
-export * from './stepper';
+export { Stepper, Step, useStepperContext } from './stepper';
+export { useStepper } from './use-stepper';
+export type { UseStepperProps, UseStepperReturn } from './use-stepper';

package/dist/components/ui/stepper/stepper.d.ts

@@ -4,7 +4,7 @@ interface StepperContextValue {
     totalSteps: number;
     orientation: 'horizontal' | 'vertical';
 }
-declare const useStepper: () => StepperContextValue;
+declare const useStepperContext: () => StepperContextValue;
 interface StepperProps extends React.HTMLAttributes<HTMLDivElement> {
     currentStep: number;
     /** Layout direction. @default "horizontal" */
@@ -33,4 +33,4 @@ interface StepProps extends React.HTMLAttributes<HTMLDivElement> {
     error?: boolean;
 }
 declare const Step: React.ForwardRefExoticComponent<StepProps & React.RefAttributes<HTMLDivElement>>;
-export { Stepper, Step, useStepper };
+export { Stepper, Step, useStepperContext };

package/dist/components/ui/stepper/use-stepper.d.ts

@@ -0,0 +1,60 @@
+export interface UseStepperProps {
+    /** Total number of steps. */
+    totalSteps: number;
+    /** Initial active step (1-indexed). @default 1 */
+    initialStep?: number;
+    /**
+     * Controlled current step (1-indexed).
+     * When provided, step state is managed externally via `onStepChange`.
+     */
+    step?: number;
+    /** Called whenever the active step changes. */
+    onStepChange?: (step: number) => void;
+    /**
+     * Optional async guard called before advancing to the next step.
+     * Return `true` to allow the transition, `false` to block it.
+     * Useful for running form validation before moving forward.
+     */
+    onBeforeNext?: (currentStep: number) => boolean | Promise<boolean>;
+}
+export interface UseStepperReturn {
+    /** The currently active step (1-indexed). */
+    currentStep: number;
+    /** Total number of steps. */
+    totalSteps: number;
+    /** Whether the current step is the first step. */
+    isFirstStep: boolean;
+    /** Whether the current step is the last step. */
+    isLastStep: boolean;
+    /** Whether navigation to the previous step is possible. */
+    canGoPrev: boolean;
+    /** Whether navigation to the next step is possible. */
+    canGoNext: boolean;
+    /**
+     * Advance to the next step.
+     * If `onBeforeNext` is provided, it is awaited first; the step only
+     * advances when the guard returns `true`.
+     */
+    next: () => Promise<void>;
+    /** Go back to the previous step (no-op if already on step 1). */
+    prev: () => void;
+    /** Jump directly to a specific step (1-indexed, clamped to valid range). */
+    goTo: (step: number) => void;
+    /** Jump to the first step. */
+    reset: () => void;
+}
+/**
+ * Headless hook for multi-step wizard / stepper logic.
+ *
+ * @description
+ * Manages the active step state, navigation guards, and derived flags for
+ * multi-step flows. Supports both controlled and uncontrolled modes.
+ * Pair with the `<Stepper>` / `<Step>` visual components or any custom UI.
+ *
+ * @example
+ * ```tsx
+ * const { currentStep, totalSteps, next, prev, isFirstStep, isLastStep } =
+ *   useStepper({ totalSteps: 3, onBeforeNext: () => form.trigger() });
+ * ```
+ */
+export declare function useStepper({ totalSteps, initialStep, step: controlledStep, onStepChange, onBeforeNext, }: UseStepperProps): UseStepperReturn;

package/dist/components/ui/tree-view/index.d.ts

@@ -1 +1,4 @@
-export * from './tree-view';
+export { TreeView } from './tree-view';
+export type { TreeViewProps } from './tree-view';
+export { useTreeView } from './use-tree-view';
+export type { TreeNode, UseTreeViewProps, UseTreeViewReturn } from './use-tree-view';

package/dist/components/ui/tree-view/tree-view.d.ts

@@ -1,10 +1,5 @@
 import * as React from "react";
-export interface TreeNode {
-    id: string;
-    label: string;
-    icon?: React.ReactNode;
-    children?: TreeNode[];
-}
+import { type TreeNode } from "./use-tree-view";
 interface TreeViewProps extends React.HTMLAttributes<HTMLDivElement> {
     data: TreeNode[];
     /** Called when a node is clicked or activated via keyboard. */
@@ -24,6 +19,8 @@ interface TreeViewProps extends React.HTMLAttributes<HTMLDivElement> {
  * and collapsed independently. Supports custom icons per node, controlled
  * selection, and full WAI-ARIA keyboard navigation.
  *
+ * Headless logic is available via `useTreeView` for custom tree UIs.
+ *
  * @ai-rules
  * 1. Each `TreeNode` must have a unique `id`.
  * 2. Leaf nodes (no `children`) do not render expand arrows.
@@ -34,3 +31,4 @@ interface TreeViewProps extends React.HTMLAttributes<HTMLDivElement> {
 declare const TreeView: React.ForwardRefExoticComponent<TreeViewProps & React.RefAttributes<HTMLDivElement>>;
 export { TreeView };
 export type { TreeViewProps };
+export type { TreeNode } from './use-tree-view';

package/dist/components/ui/tree-view/use-tree-view.d.ts

@@ -0,0 +1,60 @@
+export interface TreeNode {
+    id: string;
+    label: string;
+    icon?: React.ReactNode;
+    children?: TreeNode[];
+}
+export interface UseTreeViewProps {
+    /** The tree data to manage. */
+    data: TreeNode[];
+    /** Node IDs that are expanded by default (uncontrolled). */
+    defaultExpanded?: string[];
+    /**
+     * Controlled selected node ID.
+     * When provided, selection state is managed externally.
+     */
+    selectedNodeId?: string;
+    /** Called when a node is clicked or activated via keyboard. */
+    onNodeClick?: (node: TreeNode) => void;
+    /** Called when a node becomes the selected item. */
+    onNodeSelect?: (node: TreeNode) => void;
+}
+export interface UseTreeViewReturn {
+    /** Set of currently expanded node IDs. */
+    expanded: Set<string>;
+    /** The currently selected node ID (controlled or internal). */
+    effectiveSelectedId: string | undefined;
+    /**
+     * Map of node ID → button element.
+     * Attach via the `setRef` helper returned by `getNodeRef`.
+     */
+    nodeRefs: React.MutableRefObject<Map<string, HTMLButtonElement>>;
+    /** Returns a ref-setter callback for a given node ID. */
+    getNodeRef: (nodeId: string) => (el: HTMLButtonElement | null) => void;
+    /** Toggle the expanded state of a node. */
+    toggleExpand: (nodeId: string) => void;
+    /** Select a node (updates internal state if uncontrolled, fires callbacks). */
+    handleSelect: (node: TreeNode) => void;
+    /**
+     * Full WAI-ARIA keyboard handler.
+     * Attach to `onKeyDown` of each tree-item button.
+     */
+    handleKeyDown: (e: React.KeyboardEvent, node: TreeNode) => void;
+    /** Returns the ordered list of all currently visible nodes (respects expand state). */
+    getVisibleNodes: () => TreeNode[];
+}
+/**
+ * Headless hook for hierarchical tree-view logic.
+ *
+ * @description
+ * Manages expand/collapse state, selection (controlled or uncontrolled),
+ * WAI-ARIA keyboard navigation (Arrow keys, Home, End, Enter/Space),
+ * and focus management via node refs. Pair with any custom tree UI.
+ *
+ * @example
+ * ```tsx
+ * const { expanded, effectiveSelectedId, toggleExpand, handleSelect, handleKeyDown, getNodeRef } =
+ *   useTreeView({ data, onNodeSelect });
+ * ```
+ */
+export declare function useTreeView({ data, defaultExpanded, selectedNodeId, onNodeClick, onNodeSelect, }: UseTreeViewProps): UseTreeViewReturn;