@boxcustodia/library 2.0.0-alpha.3 → 2.0.0-alpha.30

package/dist/src/hooks/use-range-pagination/use-range-pagination.d.ts

@@ -0,0 +1,28 @@
+import { UsePaginationProps } from '../../hooks';
+export declare const DOTS = "...";
+export type UseRangePaginationProps = {
+    /**
+     * Visible siblings on each side of the current page.
+     */
+    siblingCount?: number;
+} & UsePaginationProps;
+export declare const useRangePagination: ({ siblingCount, ...paginationProps }: UseRangePaginationProps) => {
+    paginationRange: (string | number)[];
+    page: number;
+    pageSize: number;
+    pageCount: number;
+    isFirstPage: boolean;
+    isLastPage: boolean;
+    hasPrevPage: boolean;
+    hasNextPage: boolean;
+    range: {
+        start: number;
+        end: number;
+    };
+    next: () => void;
+    prev: () => void;
+    firstPage: () => void;
+    lastPage: () => void;
+    goTo: (page: number) => void;
+    setPageSize: (size: number) => void;
+};

package/dist/src/hooks/use-range-pagination/use-range-pagination.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/src/hooks/use-selection/index.d.ts

@@ -0,0 +1 @@
+export * from './use-selection';

package/dist/src/hooks/use-selection/use-selection.d.ts

@@ -0,0 +1,48 @@
+/** Stable identity projected from an item. */
+export type Key = string | number | symbol;
+export interface UseSelectionOptions<T> {
+    /**
+     * Projects a stable key from an item. Frozen on mount.
+     * When omitted, the item itself is used as its key (reference identity for
+     * objects, value identity for primitives). Pass this for object lists that
+     * are re-created across renders (e.g. after a fetch) so selection survives.
+     */
+    keyFn?: (item: T) => Key;
+    /** Initial selection. Frozen on mount — never re-applied on re-render. */
+    defaultSelected?: T[];
+    /** Called after every selection change. NOT called on initial mount. */
+    onChange?: (selected: T[]) => void;
+}
+export interface UseSelectionReturn<T> {
+    /** Currently-selected items present in `items`. Stable reference. */
+    selected: T[];
+    /** All selected keys, including keys whose item is absent (sticky). */
+    selectedKeys: ReadonlySet<Key>;
+    /** True when every item in `items` is selected (false when empty). */
+    isAllSelected: boolean;
+    /** True when at least one — but not all — items are selected. */
+    isSomeSelected: boolean;
+    /** True when nothing is selected. */
+    isNoneSelected: boolean;
+    /** Stable fn ref: true if `item` is selected. */
+    isSelected: (item: T) => boolean;
+    /** Selects one item. No-op if already selected. */
+    select: (item: T) => void;
+    /** Unselects one item. No-op if not selected. */
+    unselect: (item: T) => void;
+    /** Toggles one item's selection. */
+    toggle: (item: T) => void;
+    /** Replaces the entire selection with `items`. */
+    setSelected: (items: T[]) => void;
+    /** Selects every item currently in `items` (additive). */
+    selectAll: () => void;
+    /** Selects all if not all selected, otherwise clears. */
+    toggleAll: () => void;
+    /** Clears the entire selection (including sticky orphaned keys). */
+    clear: () => void;
+    /** Inverts selection relative to current `items`. */
+    invert: () => void;
+    /** Selects items in the inclusive index range [from, to] of `items` (additive). */
+    selectRange: (from: number, to: number) => void;
+}
+export declare function useSelection<T>(items: T[], options?: UseSelectionOptions<T>): UseSelectionReturn<T>;

package/dist/src/hooks/use-selection/use-selection.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/src/hooks/use-session-storage/index.d.ts

@@ -0,0 +1 @@
+export * from './use-session-storage';

package/dist/src/hooks/use-session-storage/use-session-storage.d.ts

@@ -0,0 +1,11 @@
+import { Serializer } from '../internal';
+export type { Serializer };
+export interface UseSessionStorageOptions<T> {
+    serializer?: Serializer<T>;
+}
+export declare function useSessionStorage<T>(key: string): [
+    T | undefined,
+    (value: T | ((prev: T | undefined) => T)) => void,
+    () => void
+];
+export declare function useSessionStorage<T>(key: string, initialValue: T, options?: UseSessionStorageOptions<T>): [T, (value: T | ((prev: T) => T)) => void, () => void];

package/dist/src/hooks/use-session-storage/use-session-storage.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/src/hooks/use-step/index.d.ts

@@ -0,0 +1 @@
+export * from './use-step';

package/dist/src/hooks/use-step/use-step.d.ts

@@ -0,0 +1,21 @@
+export interface UseStepActions {
+    /** Advance one step. No-op at the last step. Stable reference. */
+    next: () => void;
+    /** Go back one step. No-op at the first step. Stable reference. */
+    back: () => void;
+    /** Jump to an index, clamped to [0, count - 1]. Stable reference. */
+    goTo: (index: number) => void;
+    /** Return to index 0. Stable reference. */
+    reset: () => void;
+    /** True when there is a next step to advance to. */
+    canGoNext: boolean;
+    /** True when there is a previous step to go back to. */
+    canGoBack: boolean;
+    /** True when the current index is the first step. */
+    isFirstStep: boolean;
+    /** True when the current index is the last step. */
+    isLastStep: boolean;
+    /** Ratio of progress in [0, 1]. 0 when count <= 1. */
+    progress: number;
+}
+export declare function useStep(count: number): [number, UseStepActions];

package/dist/src/hooks/use-step/use-step.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/src/index.d.ts

@@ -0,0 +1,6 @@
+export * from './components';
+export * from './hooks';
+export * from './lib';
+export * from './models';
+export * from './providers';
+export * from './utils';

package/dist/src/lib/cn.d.ts

@@ -0,0 +1,3 @@
+import { ClassValue } from 'clsx';
+export declare const twMerge: (...classLists: import('tailwind-merge').ClassNameValue[]) => string;
+export declare function cn(...args: ClassValue[]): string;

package/dist/src/lib/index.d.ts

@@ -0,0 +1 @@
+export * from './cn';

package/dist/src/models/Generic.model.d.ts

@@ -0,0 +1,37 @@
+import { Dispatch, HTMLProps, MutableRefObject, ReactElement, ReactNode, SetStateAction } from 'react';
+export interface Option<TValue = string> {
+    label: string;
+    value: TValue;
+    disabled?: boolean;
+}
+export type ClassName = string | undefined;
+export type ClickEvent = React.MouseEvent<HTMLButtonElement, MouseEvent>;
+export type ControllableState<T> = {
+    value?: T;
+    defaultValue?: T;
+    onChange?: (state: T) => void;
+};
+export type Controllable<C, T extends NonNullable<unknown>> = OverrideProps<HTMLProps<C>, ControllableState<T>>;
+export type MaybeRef<T> = T | MutableRefObject<T>;
+export type ArrayUnion<V, T extends ReadonlyArray<V>> = T[number];
+export type ValuesUnion<T extends Record<string, any>> = T[keyof T];
+export type GenericObject<T = any> = {
+    [key: string]: T;
+};
+export type Nullable<T> = T | null;
+export type Maybe<T> = T | undefined | null;
+export type SetState<T> = Dispatch<SetStateAction<T>>;
+export type State<T> = [T, SetState<T>];
+export type ID = string | number;
+export type OverrideProps<T, TOverridden> = Omit<T, keyof TOverridden> & TOverridden;
+export type SafeOmit<T, K extends keyof T> = Pick<T, Exclude<keyof T, K>>;
+export type AtLeastOne<T> = [T, ...T[]];
+export type Loose<T> = T | (string & {});
+export type Renderable<T> = ReactNode | ((props: T) => ReactElement);
+export type BaseEntity = {
+    id: string;
+    createdAt: Date;
+};
+export type Entity<T> = {
+    [K in keyof T]: T[K];
+} & BaseEntity;

package/dist/src/models/index.d.ts

@@ -0,0 +1 @@
+export * from './Generic.model';

package/dist/src/providers/index.d.ts

@@ -0,0 +1,2 @@
+export * from './library-provider';
+export * from './theme';

package/dist/src/providers/library-provider.d.ts

@@ -0,0 +1,28 @@
+import { Tooltip as TooltipBase } from '@base-ui/react/tooltip';
+import { ComponentPropsWithoutRef, ReactNode } from 'react';
+import { ToastProviderProps } from '../components/toast/toast';
+export type LibraryProviderProps = {
+    children: ReactNode;
+    /**
+     * Delay in ms before a tooltip opens when no other tooltip is already visible.
+     * Once a tooltip is open, subsequent ones open instantly until the cursor leaves.
+     * @default 600
+     */
+    tooltipDelay?: ComponentPropsWithoutRef<typeof TooltipBase.Provider>["delay"];
+} & Omit<ToastProviderProps, "children">;
+/**
+ * Single provider that wires up all library infrastructure.
+ * Wrap your app once — no other providers needed.
+ *
+ * Includes:
+ * - `TooltipProvider` — shared hover intent and delay grouping across all tooltips
+ * - `ToastProvider` — enables `toast.*` imperative API from anywhere
+ *
+ * @example
+ * ```tsx
+ * <LibraryProvider tooltipDelay={400}>
+ *   <App />
+ * </LibraryProvider>
+ * ```
+ */
+export declare function LibraryProvider({ children, tooltipDelay, ...toastProps }: LibraryProviderProps): import("react/jsx-runtime").JSX.Element;

package/dist/src/providers/theme/ThemeProvider.d.ts

@@ -0,0 +1,11 @@
+import { ReactNode } from 'react';
+import { Theme } from './types';
+export declare const useTheme: () => {
+    theme: Theme;
+};
+type ThemeProviderProps = {
+    children: ReactNode;
+    theme?: Theme;
+};
+export declare const ThemeProvider: ({ children, theme, }: ThemeProviderProps) => import("react/jsx-runtime").JSX.Element;
+export {};

package/dist/src/providers/theme/index.d.ts

@@ -0,0 +1,3 @@
+export * from './ThemeProvider';
+export * from './types';
+export * from './useThemeProps';

package/dist/src/providers/theme/types.d.ts

@@ -0,0 +1,10 @@
+import { ComponentProps } from 'react';
+import { Button } from '../../components/button/button';
+import { Input } from '../../components/input/input';
+type ThemeProps<T, TOverridden> = Partial<Omit<T, keyof TOverridden>>;
+type PropsWithoutValue<T> = Omit<T, "value" | "onChange" | "defaultValue">;
+export type Theme = {
+    Button?: ThemeProps<ComponentProps<typeof Button>, "asChild" | "loading">;
+    Input?: Partial<PropsWithoutValue<ComponentProps<typeof Input>>>;
+};
+export {};

package/dist/src/providers/theme/useThemeProps.d.ts

@@ -0,0 +1,10 @@
+import { Theme } from '../../providers/theme/types';
+/**
+ * Hook que permite obtener y combinar las propiedades de un componente con las del tema.
+ *
+ * El orden de prioridad de las propiedades es:
+ * 1. Props pasadas directamente al componente
+ * 2. Props definidas en el ThemeProvider
+ * 3. Props por defecto del componente
+ */
+export declare const useThemeProps: <TComponent extends keyof Theme, TProps>(componentName: TComponent, props: TProps, defaultProps?: Partial<TProps>) => TProps;

package/dist/src/stores/theme.store.d.ts

@@ -0,0 +1,10 @@
+import { StoreApi } from 'zustand';
+import { Theme } from '../providers/theme/types';
+interface ThemeStore {
+    theme: Theme;
+    setTheme: (theme: Theme) => void;
+    getComponentProps: <TComponent extends keyof Theme, TProps>(componentName: TComponent, props: TProps, defaultProps?: Partial<TProps>) => TProps;
+}
+export type ThemeStoreApi = StoreApi<ThemeStore>;
+declare const createThemeStore: (initTheme?: Theme) => StoreApi<ThemeStore>;
+export { createThemeStore };

package/dist/src/utils/dates/parseDateRange.utility.d.ts

@@ -0,0 +1,14 @@
+import { DateRange } from '../../components';
+/**
+ * @typedef {Object} DateRange
+ * @property {Date} start - The start date of the range.
+ * @property {Date} end - The end date of the range.
+ */
+/**
+ * Parses a date range string in the format "DD/MM/YYYY - DD/MM/YYYY" and returns an object with start and end dates.
+ *
+ * @param {string} dateRange - The date range string to parse.
+ * @returns {DateRange} An object containing the start and end dates.
+ * @throws Will throw an error if the input string is not in the expected format or the dates are invalid.
+ */
+export declare const parseDateRange: (dateRange: string) => DateRange;

package/dist/src/utils/form.d.ts

@@ -0,0 +1,42 @@
+import { ComponentProps, ReactNode } from 'react';
+import { ControllerRenderProps, FieldPath, FieldValues, RegisterOptions, SubmitHandler, UseFormProps, UseFormReturn } from 'react-hook-form';
+import { z } from 'zod';
+import { FieldProps, Form as LibraryForm } from '../components';
+/**
+ * Validates `formValues` from `Form.onFormSubmit` against a Zod schema and
+ * returns `{ data, errors }` ready to wire back into `Form`'s `errors` prop.
+ *
+ * - `data` is the typed, parsed value, or `null` when validation fails.
+ * - `errors` is the flattened `fieldErrors` object (empty on success).
+ *
+ * Value conventions worth knowing when writing the schema (these hold whether
+ * or not you use Zod):
+ * - `DateInput` and `DatePicker` submit an **ISO date string** (`yyyy-MM-dd`),
+ *   or `""` when empty. The format is locale-agnostic, sortable, and parseable
+ *   by `new Date()` or any backend without a custom parser. The displayed text
+ *   stays `dd/MM/yyyy` — display and value are different layers. To reformat,
+ *   it is a plain split: `iso.split("-").reverse().join("-")` → `dd-MM-yyyy`.
+ *   Avoid round-tripping through `new Date(iso)` + local getters (timezone
+ *   shift); split the string or use `parseISO`.
+ */
+export declare function parseFormValues<T extends z.ZodType>(schema: T, values: Record<string, unknown>): {
+    data: z.infer<T> | null;
+    errors: Record<string, string[]>;
+};
+export declare function useHookForm<T extends FieldValues = FieldValues>(schema: z.ZodType<T>, options?: Partial<UseFormProps<T>>): UseFormReturn<T>;
+type HookFormProps<T extends FieldValues> = Omit<ComponentProps<typeof LibraryForm>, "onSubmit" | "onFormSubmit" | "children"> & {
+    form: UseFormReturn<T>;
+    onFormSubmit: SubmitHandler<T>;
+    children: ReactNode;
+};
+export declare function HookForm<T extends FieldValues>({ form, onFormSubmit, children, ...props }: HookFormProps<T>): import("react/jsx-runtime").JSX.Element;
+export type HookFieldRenderProps<T extends FieldValues = FieldValues, TName extends FieldPath<T> = FieldPath<T>> = ControllerRenderProps<T, TName> & {
+    invalid: boolean;
+};
+type HookFieldProps<T extends FieldValues = FieldValues, TName extends FieldPath<T> = FieldPath<T>> = Omit<FieldProps, "children" | "error" | "render" | "name"> & {
+    name: TName;
+    rules?: RegisterOptions<T, TName>;
+    render: (field: HookFieldRenderProps<T, TName>) => ReactNode;
+};
+export declare function HookField<T extends FieldValues = FieldValues, TName extends FieldPath<T> = FieldPath<T>>({ name, rules, render, ...fieldProps }: HookFieldProps<T, TName>): import("react/jsx-runtime").JSX.Element;
+export {};

package/dist/src/utils/form.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/src/utils/functions/createSafeContext.d.ts

@@ -0,0 +1,2 @@
+import { default as React } from 'react';
+export declare const createSafeContext: <T>() => readonly [() => T & ({} | undefined), React.Provider<T | null>];

package/dist/src/utils/functions/createSafeContext.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/src/utils/functions/ensureReactElement.d.ts

@@ -0,0 +1,9 @@
+import { default as React, ReactElement } from 'react';
+import { Renderable } from '../../models';
+type EnsureReactElementProps<P = {}> = {
+    children: Renderable<P>;
+    as?: React.ElementType;
+    props?: P;
+};
+export declare const ensureReactElement: <P>({ children, as: Wrapper, props, }: EnsureReactElementProps<P>) => ReactElement;
+export {};

package/dist/src/utils/functions/ensureReactElement.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/src/utils/functions/getFormData.d.ts

@@ -0,0 +1,2 @@
+import { FormEvent } from 'react';
+export declare const getFormData: (event: FormEvent<HTMLFormElement>) => Record<string, string>;

package/dist/src/utils/functions/getFormData.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/src/utils/functions/index.d.ts

@@ -0,0 +1,4 @@
+export * from './createSafeContext';
+export * from './ensureReactElement';
+export * from './getFormData';
+export * from './mergeRefs';

package/dist/src/utils/functions/mergeRefs.d.ts

@@ -0,0 +1,2 @@
+import type * as React from "react";
+export declare function mergeRefs<T = any>(refs: Array<React.MutableRefObject<T> | React.LegacyRef<T> | undefined | null>): React.RefCallback<T>;

package/dist/src/utils/functions/mergeRefs.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/src/utils/index.d.ts

@@ -0,0 +1,3 @@
+export * from './form';
+export * from './functions';
+export * from './strings';

package/dist/src/utils/strings/extractInitials.utility.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Extracts the initials from a string.
+ * @param {string} string - The input string.
+ * @returns {string} The initials extracted from the input string.
+ */
+export declare const extractInitials: (string: string) => string;

package/dist/src/utils/strings/index.d.ts

@@ -0,0 +1 @@
+export * from './extractInitials.utility';

package/dist/src/utils/tests/click.d.ts

@@ -0,0 +1 @@
+export declare const click: (element: HTMLElement) => void;

package/dist/src/utils/tests/index.d.ts

@@ -0,0 +1,2 @@
+export * from './click';
+export * from './type';

package/dist/src/utils/tests/keyboard.d.ts

@@ -0,0 +1,10 @@
+type KeyboardEventOptions = {
+    key?: string;
+    ctrlKey?: boolean;
+    shiftKey?: boolean;
+    altKey?: boolean;
+    metaKey?: boolean;
+    [key: string]: any;
+};
+export declare const keyboard: (element?: EventTarget, options?: KeyboardEventOptions, eventName?: "keydown" | "keypress" | "keyup") => void;
+export {};

package/dist/src/utils/tests/type.d.ts

@@ -0,0 +1 @@
+export declare const type: (element: HTMLElement, value: string) => void;