@boxcustodia/library 2.0.0-alpha.22 → 2.0.0-alpha.23

package/src/components/date-picker/date-input.tsx

@@ -3,7 +3,7 @@
 import { useControllableState } from "@radix-ui/react-use-controllable-state";
 import { format, isDate } from "date-fns";
 import { CalendarIcon } from "lucide-react";
-import { KeyboardEvent } from "react";
+import { KeyboardEvent, useState } from "react";
 import {
   Calendar,
   FieldControl,
@@ -15,6 +15,7 @@ import {
 } from "../../components";
 import { cn } from "../../lib";
 import type { DateInputProps } from "./date-picker.model";
+import { parseInputToDate } from "./date-picker.utils";
 import { useDateInput } from "./use-date-input";
 import { useDateInputPopover } from "./use-date-input-popover";
 import { useHiddenFieldValue } from "./use-hidden-field-value";
@@ -67,6 +68,20 @@ export const DateInput = (props: DateInputProps) => {
     inputRef,
   } = useDateInputPopover({ disabled });
 
+  // Month shown by the calendar. Controlled so opening the popover can jump to
+  // the date currently typed in the input — even before it's committed.
+  const [calendarMonth, setCalendarMonth] = useState<Date | undefined>(
+    undefined,
+  );
+
+  const handleOpenChange = (next: boolean) => {
+    if (next) {
+      const typed = parseInputToDate(inputValue);
+      setCalendarMonth(typed ?? selectedDate ?? undefined);
+    }
+    setOpen(next);
+  };
+
   const handleKeyDown = (event: KeyboardEvent<HTMLInputElement>) => {
     handleInputKeyDown(event);
     handlePopoverKeyDown(event);
@@ -95,7 +110,11 @@ export const DateInput = (props: DateInputProps) => {
   });
 
   return (
-    <PopoverRoot data-slot="date-input" open={open} onOpenChange={setOpen}>
+    <PopoverRoot
+      data-slot="date-input"
+      open={open}
+      onOpenChange={handleOpenChange}
+    >
       <div
         className={cn(
           inputBaseClasses,
@@ -173,6 +192,8 @@ export const DateInput = (props: DateInputProps) => {
           <Calendar
             className="border-none"
             mode="single"
+            month={calendarMonth}
+            onMonthChange={setCalendarMonth}
             selected={selectedDate ?? undefined}
             onSelect={(next) => {
               if (!next || !isDate(next)) {

package/src/components/form/form.tsx

@@ -3,8 +3,9 @@
 import { Form as FormPrimitive } from "@base-ui/react/form";
 import type React from "react";
 
-export type FormProps<TValues extends Record<string, any> = Record<string, any>> =
-  FormPrimitive.Props<TValues>;
+export type FormProps<
+  TValues extends Record<string, any> = Record<string, any>,
+> = FormPrimitive.Props<TValues>;
 
 export function Form<TValues extends Record<string, any> = Record<string, any>>(
   props: FormProps<TValues>,

package/src/components/pagination/pagination.tsx

@@ -130,9 +130,9 @@ export function PaginationRoot({
   const pagination = useRangePagination({
     totalItems,
     pageSize,
-    currentPage,
-    defaultCurrentPage,
-    onCurrentPageChange,
+    page: currentPage,
+    defaultPage: defaultCurrentPage,
+    onPageChange: onCurrentPageChange,
     siblingCount,
   });
 
@@ -144,6 +144,8 @@ export function PaginationRoot({
   const value = useMemo<PaginationContextValue>(
     () => ({
       ...pagination,
+      currentPage: pagination.page,
+      maxPage: pagination.pageCount,
       pageSize,
       totalItems,
       setPageSize,

package/src/components/scroll-area/scroll-area.tsx

@@ -16,12 +16,12 @@ export function ScrollArea({
 }): React.ReactElement {
   return (
     <ScrollAreaPrimitive.Root
-      className={cn("size-full min-h-0", className)}
+      className={cn("flex min-h-0 size-full flex-col", className)}
       {...props}
     >
       <ScrollAreaPrimitive.Viewport
         className={cn(
-          "h-full rounded-[inherit] outline-none transition-shadows focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-1 focus-visible:ring-offset-background data-has-overflow-y:overscroll-y-contain data-has-overflow-x:overscroll-x-contain",
+          "min-h-0 flex-1 rounded-[inherit] outline-none transition-shadows focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-1 focus-visible:ring-offset-background data-has-overflow-y:overscroll-y-contain data-has-overflow-x:overscroll-x-contain",
           scrollFade &&
             "mask-t-from-[calc(100%-min(var(--fade-size),var(--scroll-area-overflow-y-start)))] mask-b-from-[calc(100%-min(var(--fade-size),var(--scroll-area-overflow-y-end)))] mask-l-from-[calc(100%-min(var(--fade-size),var(--scroll-area-overflow-x-start)))] mask-r-from-[calc(100%-min(var(--fade-size),var(--scroll-area-overflow-x-end)))] [--fade-size:1.5rem]",
           scrollbarGutter &&

package/src/components/select/select.tsx

@@ -38,8 +38,12 @@ export function SelectRoot<
 export function SelectTrigger({
   className,
   children,
+  icon,
   ...props
-}: SelectPrimitive.Trigger.Props): React.ReactElement {
+}: SelectPrimitive.Trigger.Props & {
+  /** Icon rendered inside the trigger. Defaults to a chevrons-up-down glyph. */
+  icon?: React.ReactNode;
+}): React.ReactElement {
   return (
     <SelectPrimitive.Trigger
       className={cn(selectTriggerClasses, className)}
@@ -51,7 +55,7 @@ export function SelectTrigger({
         data-slot="select-icon"
         className="text-muted-foreground hover:text-foreground transition-colors"
       >
-        <ChevronsUpDownIcon className={selectTriggerIconClassName} />
+        {icon ?? <ChevronsUpDownIcon className={selectTriggerIconClassName} />}
       </SelectPrimitive.Icon>
     </SelectPrimitive.Trigger>
   );
@@ -59,12 +63,15 @@ export function SelectTrigger({
 
 export type SelectButtonProps = useRender.ComponentProps<"button"> & {
   ref?: React.Ref<HTMLButtonElement>;
+  /** Icon rendered inside the button. Defaults to a chevrons-up-down glyph. */
+  icon?: React.ReactNode;
 };
 
 export function SelectButton({
   className,
   render,
   children,
+  icon,
   ...props
 }: SelectButtonProps): React.ReactElement {
   const typeValue: React.ButtonHTMLAttributes<HTMLButtonElement>["type"] =
@@ -76,7 +83,7 @@ export function SelectButton({
         <span className="flex-1 truncate in-data-placeholder:text-muted-foreground/72">
           {children}
         </span>
-        <ChevronsUpDownIcon className={selectTriggerIconClassName} />
+        {icon ?? <ChevronsUpDownIcon className={selectTriggerIconClassName} />}
       </>
     ),
     className: cn(selectTriggerClasses, "min-w-0", className),
@@ -302,6 +309,8 @@ type SelectBaseProps<TItem = unknown> = Omit<
   renderItem?: (item: TItem) => React.ReactNode;
   placeholder?: string;
   className?: string;
+  /** Icon rendered inside the trigger. Defaults to a chevrons-up-down glyph. */
+  icon?: React.ReactNode;
   /** Styles applied to each internal slot. */
   classNames?: {
     /** Popup panel containing the item list. */
@@ -353,6 +362,7 @@ export function Select<TItem = unknown>(
     multiple,
     className,
     classNames,
+    icon,
     "aria-invalid": ariaInvalid,
     ...rest
   } = allProps as SelectBaseProps<TItem> & {
@@ -414,6 +424,7 @@ export function Select<TItem = unknown>(
     >
       <SelectTrigger
         className={className}
+        icon={icon}
         // Only forward `aria-invalid` when explicitly set. Base UI's Field
         // integration already sets it from validity state; passing `undefined`
         // here would clobber that value during prop merge and drop the error border.

package/src/hooks/index.ts

@@ -1,6 +1,6 @@
 export { useControllableState } from "@radix-ui/react-use-controllable-state";
+export * from "./use-action";
 export * from "./use-array";
-export * from "./use-async";
 export * from "./use-boolean";
 export * from "./use-click-outside";
 export * from "./use-clipboard";
@@ -9,14 +9,12 @@ export * from "./use-debounce-value";
 export * from "./use-disclosure";
 export * from "./use-document-title";
 export * from "./use-event-listener";
-export * from "./use-focus-trap";
 export * from "./use-hotkey";
 export * from "./use-hover";
 export * from "./use-is-visible";
 export * from "./use-local-storage";
 export * from "./use-media-query";
 export * from "./use-memoized-fn";
-export * from "./use-mutation";
 export * from "./use-object";
 export * from "./use-on-mount";
 export * from "./use-pagination";
@@ -24,4 +22,5 @@ export * from "./use-portal";
 export * from "./use-prevent-page-close";
 export * from "./use-range-pagination";
 export * from "./use-selection";
+export * from "./use-session-storage";
 export * from "./use-step";

package/src/hooks/internal/index.ts

@@ -1,4 +1,5 @@
 export { isAppleDevice } from "./is-apple-device";
 export { isBrowser } from "./is-browser";
+export type { Serializer } from "./serializer";
 export { useIsomorphicLayoutEffect } from "./use-isomorphic-layout-effect";
 export { useLatestRef } from "./use-latest-ref";

package/src/hooks/internal/serializer.ts

@@ -0,0 +1,4 @@
+export interface Serializer<T> {
+  read: (raw: string) => T;
+  write: (value: T) => string;
+}

package/src/hooks/use-action/index.ts

@@ -0,0 +1 @@
+export * from "./use-action";

package/src/hooks/{use-mutation/use-mutation.stories.tsx → use-action/use-action.stories.tsx}

@@ -1,7 +1,7 @@
 import type { Meta, StoryObj } from "@storybook/react-vite";
 import { useState } from "react";
 import { Button } from "../../components";
-import { type UseMutationOptions, useMutation } from "./use-mutation";
+import { type UseActionOptions, useAction } from "./use-action";
 
 // ─── Demo component ──────────────────────────────────────────────────────────
 
@@ -14,21 +14,21 @@ interface DemoData {
   timestamp: number;
 }
 
-type MutationDemoProps = UseMutationOptions<DemoVariables, DemoData> & {
+type ActionDemoProps = UseActionOptions<DemoVariables, DemoData> & {
   /** Simulated async delay in ms */
   delay?: number;
   /** When true the mutation will reject with an error */
   shouldFail?: boolean;
 };
 
-const MutationDemo = ({
+const ActionDemo = ({
   delay = 800,
   shouldFail = false,
-  onMutate,
+  onExecute,
   onSuccess,
   onError,
   onSettled,
-}: MutationDemoProps) => {
+}: ActionDemoProps) => {
   const [log, setLog] = useState<string[]>([]);
 
   const addLog = (msg: string) =>
@@ -37,7 +37,7 @@ const MutationDemo = ({
       ...prev,
     ]);
 
-  const mutation = useMutation<DemoVariables, DemoData>({
+  const action = useAction<DemoVariables, DemoData>({
     fn: async (vars) => {
       await new Promise((res, rej) =>
         setTimeout(
@@ -48,9 +48,9 @@ const MutationDemo = ({
       );
       return { message: `Created: ${vars.value}`, timestamp: Date.now() };
     },
-    onMutate: (vars) => {
-      addLog(`onMutate — vars: ${JSON.stringify(vars)}`);
-      onMutate?.(vars);
+    onExecute: (vars) => {
+      addLog(`onExecute — vars: ${JSON.stringify(vars)}`);
+      onExecute?.(vars);
     },
     onSuccess: (data, vars) => {
       addLog(`onSuccess — data: ${data.message}`);
@@ -72,15 +72,15 @@ const MutationDemo = ({
     <div className="flex flex-col gap-4 max-w-sm">
       <div className="flex gap-2">
         <Button
-          onClick={() => mutation.mutate({ value: "item-1" })}
-          disabled={mutation.isPending}
+          onClick={() => action.execute({ value: "item-1" })}
+          disabled={action.isPending}
         >
-          {mutation.isPending ? "Running…" : "Mutate"}
+          {action.isPending ? "Running…" : "Execute"}
         </Button>
         <Button
           variant="outline"
-          onClick={() => mutation.reset()}
-          disabled={mutation.isPending}
+          onClick={() => action.reset()}
+          disabled={action.isPending}
         >
           Reset
         </Button>
@@ -89,9 +89,9 @@ const MutationDemo = ({
       <pre className="rounded-md bg-slate-950 p-3 text-xs text-white leading-relaxed">
         {JSON.stringify(
           {
-            status: mutation.status,
-            data: mutation.data,
-            error: mutation.error?.message ?? null,
+            status: action.status,
+            data: action.data,
+            error: action.error?.message ?? null,
           },
           null,
           2,
@@ -111,31 +111,31 @@ const MutationDemo = ({
 
 // ─── Meta ─────────────────────────────────────────────────────────────────────
 
-const meta: Meta<typeof MutationDemo> = {
-  title: "hooks/useMutation",
-  component: MutationDemo,
+const meta: Meta<typeof ActionDemo> = {
+  title: "hooks/useAction",
+  component: ActionDemo,
   parameters: {
     docs: {
       description: {
         component: `
-\`useMutation\` manages async mutation lifecycle with stable callback identity.
+\`useAction\` manages async mutation lifecycle with stable callback identity.
 
 **API summary**
 
 \`\`\`ts
-const { mutate, mutateAsync, reset, status, data, error, isPending, isSuccess, isError, isIdle } =
-  useMutation({ fn, onMutate?, onSuccess?, onError?, onSettled? });
+const { execute, executeAsync, reset, status, data, error, isPending, isSuccess, isError, isIdle } =
+  useAction({ fn, onExecute?, onSuccess?, onError?, onSettled? });
 \`\`\`
 
-**Lifecycle order (success):** \`onMutate\` → \`fn\` → \`onSuccess\` → \`onSettled\`
+**Lifecycle order (success):** \`onExecute\` → \`fn\` → \`onSuccess\` → \`onSettled\`
 
-**Lifecycle order (error):** \`onMutate\` → \`fn\` throws → \`onError\` → \`onSettled\`
+**Lifecycle order (error):** \`onExecute\` → \`fn\` throws → \`onError\` → \`onSettled\`
 
 **Key guarantees**
-- \`mutate\` is fire-and-forget: returns \`void\`, never throws.
-- \`mutateAsync\` returns a \`Promise\` that re-throws on failure.
+- \`execute\` is fire-and-forget: returns \`void\`, never throws.
+- \`executeAsync\` returns a \`Promise\` that re-throws on failure.
 - \`onSettled\` is always called — even if \`onError\` throws.
-- All callbacks read through \`useLatestRef\`, so inline functions never recreate \`mutate\`.
+- All callbacks read through \`useLatestRef\`, so inline functions never recreate \`execute\`.
         `.trim(),
       },
     },
@@ -153,8 +153,8 @@ const { mutate, mutateAsync, reset, status, data, error, isPending, isSuccess, i
         "When true the demo's fn rejects — simulates an API error. Demo control only, not a hook option.",
       table: { category: "Demo controls" },
     },
-    onMutate: {
-      action: "onMutate",
+    onExecute: {
+      action: "onExecute",
       description:
         "Called synchronously with `variables` before `fn` is awaited. Use for optimistic updates.",
       table: {
@@ -192,11 +192,11 @@ const { mutate, mutateAsync, reset, status, data, error, isPending, isSuccess, i
       },
     },
   },
-  render: (args) => <MutationDemo {...args} />,
+  render: (args) => <ActionDemo {...args} />,
 };
 
 export default meta;
-type Story = StoryObj<typeof MutationDemo>;
+type Story = StoryObj<typeof ActionDemo>;
 
 // ─── Stories ──────────────────────────────────────────────────────────────────
 
@@ -224,7 +224,7 @@ export const Pending: Story = {
     docs: {
       description: {
         story:
-          "Click **Mutate** to see `isPending=true` while the operation runs. The button disables until the promise settles.",
+          "Click **Execute** to see `isPending=true` while the operation runs. The button disables until the promise settles.",
       },
     },
   },
@@ -255,7 +255,7 @@ export const ErrorState: Story = {
     docs: {
       description: {
         story:
-          "Toggle **shouldFail** in controls to simulate a failing API call. `status` becomes `'error'`, `error` is set, and `data` stays null. `mutate` swallows the rejection silently — use `mutateAsync` if you need to catch it.",
+          "Toggle **shouldFail** in controls to simulate a failing API call. `status` becomes `'error'`, `error` is set, and `data` stays null. `execute` swallows the rejection silently — use `executeAsync` if you need to catch it.",
       },
     },
   },