xertica-ui 2.1.2 → 2.1.4

package/dist/components/media/audio-player/use-audio-player.d.ts

@@ -0,0 +1,72 @@
+export interface UseAudioPlayerProps {
+    /** Source URL of the audio file */
+    src?: string;
+    /** Whether to play automatically on mount */
+    autoPlay?: boolean;
+    /** Initial playback time in seconds */
+    initialTime?: number;
+    /** Total duration in seconds (optional — loaded from metadata if not provided) */
+    initialDuration?: number;
+    /** Display variant: 'card' (standard floating) or 'bar' (global fixed bar) */
+    variant?: 'card' | 'bar';
+    /** Whether the player is currently visible and open (only for 'bar' variant) */
+    isOpen?: boolean;
+    /** Whether the player should automatically float when scrolled out of view */
+    enableAutoFloat?: boolean;
+    /** Callback fired when user manually closes the floating player */
+    onCloseFloating?: () => void;
+}
+export interface UseAudioPlayerReturn {
+    audioRef: React.RefObject<HTMLAudioElement>;
+    containerRef: React.RefObject<HTMLDivElement>;
+    isPlaying: boolean;
+    currentTime: number;
+    duration: number;
+    volume: number;
+    isMuted: boolean;
+    playbackSpeed: number;
+    isFloating: boolean;
+    isManualFloating: boolean;
+    isVisible: boolean;
+    isMobile: boolean;
+    enableAutoFloatLocal: boolean;
+    sidebarExpanded: boolean;
+    sidebarWidth: number;
+    assistenteExpanded: boolean;
+    togglePlay: () => void;
+    toggleMute: () => void;
+    handleSeek: (value: number[]) => void;
+    handleVolumeChange: (value: number[]) => void;
+    handleSetFloating: (floating: boolean) => void;
+    handleEnableManualFloat: () => void;
+    setPlaybackSpeed: (speed: number) => void;
+    resetAudio: () => void;
+    onPlay: () => void;
+    onPause: () => void;
+    onEnded: () => void;
+    onTimeUpdate: (e: React.SyntheticEvent<HTMLAudioElement>) => void;
+    onLoadedMetadata: (e: React.SyntheticEvent<HTMLAudioElement>) => void;
+    formatTime: (time: number) => string;
+}
+/**
+ * `useAudioPlayer` — Headless hook for the AudioPlayer component.
+ *
+ * Encapsulates all state management and side effects for audio playback,
+ * including auto-float on scroll, mobile detection, and layout context integration.
+ *
+ * @example
+ * ```tsx
+ * import { useAudioPlayer } from './use-audio-player';
+ *
+ * function MyCustomPlayer({ src }: { src: string }) {
+ *   const { isPlaying, togglePlay, formatTime, currentTime, duration } = useAudioPlayer({ src });
+ *   return (
+ *     <div>
+ *       <button onClick={togglePlay}>{isPlaying ? 'Pause' : 'Play'}</button>
+ *       <span>{formatTime(currentTime)} / {formatTime(duration)}</span>
+ *     </div>
+ *   );
+ * }
+ * ```
+ */
+export declare function useAudioPlayer({ src, autoPlay, initialTime, initialDuration, variant, isOpen, enableAutoFloat, onCloseFloating, }?: UseAudioPlayerProps): UseAudioPlayerReturn;

package/dist/components/shared/CustomTooltipContent.d.ts

@@ -0,0 +1,20 @@
+import React from 'react';
+import * as TooltipPrimitive from '@radix-ui/react-tooltip';
+/**
+ * CustomTooltipContent — Tooltip com portal e seta estilo sidebar/assistente.
+ *
+ * Substitui os componentes `SidebarTooltipContent` e `AssistantTooltipContent`
+ * que eram definidos inline em `sidebar.tsx` e `xertica-assistant.tsx`.
+ *
+ * @example
+ * ```tsx
+ * import { Tooltip, TooltipTrigger } from '../ui/tooltip';
+ * import { CustomTooltipContent } from '../shared/CustomTooltipContent';
+ *
+ * <Tooltip>
+ *   <TooltipTrigger asChild><Button>Hover me</Button></TooltipTrigger>
+ *   <CustomTooltipContent side="right">Minha dica</CustomTooltipContent>
+ * </Tooltip>
+ * ```
+ */
+export declare function CustomTooltipContent({ className, sideOffset, children, ...props }: React.ComponentProps<typeof TooltipPrimitive.Content>): import("react/jsx-runtime").JSX.Element;

package/dist/components/shared/layout-constants.d.ts

@@ -1,5 +1,5 @@
 /** Width of the sidebar when expanded (Desktop) */
-export declare const SIDEBAR_EXPANDED_WIDTH = 256;
+export declare const SIDEBAR_EXPANDED_WIDTH = 280;
 /** Width of the sidebar when collapsed (Desktop) */
 export declare const SIDEBAR_COLLAPSED_WIDTH = 80;
 /** Width of the assistant panel when expanded (Desktop) */

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

@@ -1,7 +1,7 @@
 import * as React from "react";
 import { type VariantProps } from "class-variance-authority";
 declare const alertVariants: (props?: ({
-    variant?: "default" | "success" | "info" | "warning" | "destructive" | null | undefined;
+    variant?: "default" | "destructive" | "success" | "info" | "warning" | null | undefined;
 } & import("class-variance-authority/types").ClassProp) | undefined) => string;
 export interface AlertProps extends React.ComponentProps<"div">, VariantProps<typeof alertVariants> {
     /** Custom icon. If not provided, a default semantic icon for the variant is used. Set to null to hide. */

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

@@ -1,7 +1,7 @@
 import * as React from "react";
 import { type VariantProps } from "class-variance-authority";
 declare const badgeVariants: (props?: ({
-    variant?: "default" | "success" | "info" | "warning" | "destructive" | "outline" | "secondary" | null | undefined;
+    variant?: "default" | "destructive" | "outline" | "secondary" | "success" | "info" | "warning" | null | undefined;
 } & import("class-variance-authority/types").ClassProp) | undefined) => string;
 /**
  * Informational status label for tables, lists, and counts.

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

@@ -1,8 +1,8 @@
 import * as React from "react";
 import { type VariantProps } from "class-variance-authority";
 declare const buttonVariants: (props?: ({
-    variant?: "default" | "success" | "info" | "warning" | "destructive" | "link" | "outline" | "secondary" | "ghost" | null | undefined;
-    size?: "default" | "icon" | "sm" | "lg" | null | undefined;
+    variant?: "link" | "default" | "destructive" | "outline" | "secondary" | "ghost" | "success" | "info" | "warning" | null | undefined;
+    size?: "default" | "sm" | "lg" | "icon" | null | undefined;
 } & import("class-variance-authority/types").ClassProp) | undefined) => string;
 /**
  * Props for the Button component.

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 };