haze-ui 1.29.0 → 1.30.0

package/dist/types/components/Tree/sortable-tree-utils.d.ts

@@ -0,0 +1,40 @@
+import type { TreeNodeData } from './types';
+/**
+ * Pure move math for SortableTree — no React, no dnd, fully unit-testable.
+ * The drag runtime reports a target row; these functions turn that into the
+ * `onMove` payload and back into a controlled treeData update.
+ */
+/** Payload `SortableTree` reports after a completed drag. */
+export type SortableTreeMoveInfo = {
+    /** The dragged node's key. */
+    key: string;
+    /** The new parent's key — `null` for the root level. */
+    parentKey: string | null;
+    /**
+     * Insertion index among the **new** parent's children, computed after
+     * removing the dragged node from the tree — `splice(index, 0, node)`
+     * lands exactly.
+     */
+    index: number;
+};
+/** Every key in the node's own subtree, including itself. */
+export declare function subtreeKeys(node: TreeNodeData): Set<string>;
+/**
+ * Resolve a completed drag into the `onMove` payload. Dropping onto a row
+ * inserts the dragged node **right after it** — as the target's next
+ * sibling at the target's level — so a drop on a same-level row reorders
+ * and a drop on a child of another parent reparents. Returns `null` when
+ * nothing should happen: drop on itself, on one of its own descendants
+ * (the subtree travels as one block and cannot move into itself), back
+ * onto its own current position, or an unknown key.
+ */
+export declare function resolveTreeMove(data: TreeNodeData[], dragKey: string, overKey: string): SortableTreeMoveInfo | null;
+/**
+ * Apply a reported move to a tree array — the controlled `treeData`
+ * update a consumer makes in `onMove`: detach the node with its whole
+ * subtree, then splice it into the new parent's children. Returns fresh
+ * arrays on every changed path (originals untouched). A parent key that
+ * no longer resolves falls back to appending at the root level rather
+ * than dropping the node.
+ */
+export declare function applyTreeMove(data: TreeNodeData[], info: SortableTreeMoveInfo): TreeNodeData[];

package/dist/types/components/Upload/Upload.d.ts

@@ -1,9 +1,11 @@
 import type { ReactNode, Ref } from 'react';
 import type { ControlOrValue } from 'react-use-control';
-import type { UploadFileStatus, UploadHandle, UploadListItemRender, UploadRequest } from './types';
+import type { UploadFileStatus, UploadHandle, UploadListItemRender, UploadRequest, UploadValueItem } from './types';
 type UploadProps = {
-    /** Selected files; uncontrolled (accumulating internally) when omitted. */
-    value?: ControlOrValue<File[]>;
+    /** Selected files — local `File` picks mixed freely with `UploadFile`
+     * echo entries (files already on the server); uncontrolled
+     * (accumulating internally) when omitted. */
+    value?: ControlOrValue<UploadValueItem[]>;
     accept?: string;
     /** Renders the drag-and-drop drop area (default) or a plain
      * click-only picker area — see `UploadCoreProps.droppable`. */
@@ -35,9 +37,13 @@ type UploadProps = {
     showUploadList?: boolean | {
         itemRender?: UploadListItemRender;
     };
-    /** Rendering style of the built-in list (`text` rows or a
-     * `picture-card` thumbnail grid) — see `UploadCoreProps.listType`. */
-    listType?: 'text' | 'picture-card';
+    /** Rendering style of the built-in list (`text` rows, a `picture`
+     * row with a 32px inline thumbnail, or a `picture-card` thumbnail
+     * grid) — see `UploadCoreProps.listType`. */
+    listType?: 'text' | 'picture' | 'picture-card';
+    /** Click handler for `picture` / `picture-card` thumbnails (e.g. a
+     * lightbox) — see `UploadCoreProps.onPreview`. */
+    onPreview?: (file: UploadValueItem) => void;
     /** Overrides the built-in remove-button label — see
      * `UploadCoreProps.removeLabel`. */
     removeLabel?: string;
@@ -47,13 +53,14 @@ type UploadProps = {
     /** Status-machine snapshot callback — see
      * `UploadCoreProps.onStatusChange`. */
     onStatusChange?: (files: UploadFileStatus[]) => void;
-    /** Fires with the freshly picked files only — the accumulated list is
-     * the `value` channel (or internal state when uncontrolled).
-     * Removals and `clear()` do not fire this (they are not picks). */
+    /** Fires with the freshly picked files only (always local `File`s)
+     * — the accumulated list is the `value` channel (or internal state
+     * when uncontrolled). Removals and `clear()` do not fire this (they
+     * are not picks). */
     onChange?: (files: File[]) => void;
     className?: string;
     children?: ReactNode;
     ref?: Ref<UploadHandle>;
 };
-export default function Upload({ value: valueControl, accept, droppable, beforeUpload, maxCount, multiple, request, action, method, headers, name, data, manual, showUploadList, listType, removeLabel, directory, onStatusChange, onChange, className, children, ref, }: UploadProps): import("react").JSX.Element;
+export default function Upload({ value: valueControl, accept, droppable, beforeUpload, maxCount, multiple, request, action, method, headers, name, data, manual, showUploadList, listType, onPreview, removeLabel, directory, onStatusChange, onChange, className, children, ref, }: UploadProps): import("react").JSX.Element;
 export type { UploadProps };

package/dist/types/components/Upload/UploadCore.d.ts

@@ -1,13 +1,17 @@
 import type { ComponentPropsWithoutRef, ReactNode, Ref } from 'react';
-import type { UploadFileStatus, UploadHandle, UploadListItemRender, UploadRequest } from './types';
+import type { UploadFileStatus, UploadHandle, UploadListItemRender, UploadRequest, UploadValueItem } from './types';
 type UploadCoreProps = {
     /** The selected files — the field value, emitted verbatim (as the
-     * complete next list) by `onChange`. */
-    value: File[];
+     * complete next list) by `onChange`. Local `File` picks mix freely
+     * with `UploadFile` echo entries describing files already on the
+     * server; echo entries only render (and stay removable), they never
+     * enter the upload pipeline. */
+    value: UploadValueItem[];
     /** Emits the next file list: a single pick replaces `value`, a
      * `multiple` pick appends to it. Removals from the built-in list
-     * (and `clear()`) also flow through here. */
-    onChange: (files: File[]) => void;
+     * (and `clear()`) also flow through here — echo entries come back
+     * as the very objects the consumer passed in. */
+    onChange: (files: UploadValueItem[]) => void;
     /** Comma-separated accept tokens (`.txt`, `image/*`, `text/plain`) —
      * the same grammar the native picker uses. Dropped files that do not
      * match are discarded silently (the native dialog already enforces
@@ -74,12 +78,21 @@ type UploadCoreProps = {
     };
     /**
      * Rendering style of the built-in list (default `text`): `text`
-     * rows, or a `picture-card` grid of square thumbnail cards —
-     * object-URL previews for image files (revoked once the card leaves),
-     * a type-icon fallback for the rest, an upload mask with the live
-     * percent, and a danger border + retry on error.
+     * rows; `picture` — a text row with a 32px inline thumbnail before
+     * the name (a `url` image for `UploadFile` echoes, an object-URL
+     * preview for image files, a type-icon fallback otherwise); or a
+     * `picture-card` grid of square thumbnail cards with the upload
+     * mask, danger border + retry on error, and corner remove button.
      */
-    listType?: 'text' | 'picture-card';
+    listType?: 'text' | 'picture' | 'picture-card';
+    /**
+     * Click handler for the thumbnails of `picture` / `picture-card`
+     * lists — the natural spot to open a lightbox (wire it to
+     * `Image`/`ImagePreview`). Receives the value item the thumbnail
+     * describes. The remove/retry/cancel buttons sit outside the hit
+     * area and keep working.
+     */
+    onPreview?: (file: UploadValueItem) => void;
     /**
      * Overrides the built-in remove-button label (list rows and
      * picture-card corners); defaults to the locale string.
@@ -95,12 +108,13 @@ type UploadCoreProps = {
     /**
      * Fires whenever the tracked entries change (added, removed, status
      * or percent) with the complete snapshot in value order. Only tracks
-     * while `request`/`action` or `showUploadList` is in play.
+     * while `request`/`action` or `showUploadList` is in play. `UploadFile`
+     * echoes report their terminal `status`/`percent` like any row.
      */
     onStatusChange?: (files: UploadFileStatus[]) => void;
     className?: string;
     children?: ReactNode;
     ref?: Ref<UploadHandle>;
 } & Omit<ComponentPropsWithoutRef<'div'>, 'value' | 'onChange' | 'children' | 'onClick' | 'onDrop' | 'onDragOver' | 'onDragEnter' | 'onDragLeave' | 'onKeyDown' | 'role' | 'tabIndex'>;
-export default function UploadCore({ value, onChange, accept, droppable, beforeUpload, maxCount, multiple, request, action, method, headers, name, data, manual, showUploadList, listType, removeLabel, directory, onStatusChange, className, children, ref, ...rest }: UploadCoreProps): import("react").JSX.Element;
+export default function UploadCore({ value, onChange, accept, droppable, beforeUpload, maxCount, multiple, request, action, method, headers, name, data, manual, showUploadList, listType, onPreview, removeLabel, directory, onStatusChange, className, children, ref, ...rest }: UploadCoreProps): import("react").JSX.Element;
 export type { UploadCoreProps };

package/dist/types/components/Upload/UploadList.d.ts

@@ -1,18 +1,21 @@
-import type { UploadEntry, UploadListItemRender } from './types';
+import type { UploadEntry, UploadListItemRender, UploadValueItem } from './types';
 type UploadListProps = {
     /** Tracked rows, in value order. */
     entries: UploadEntry[];
-    /** Rendering style of the built-in list: `text` rows (default) or a
+    /** Rendering style of the built-in list: `text` rows (default), a
+     * `picture` text row with a 32px inline thumbnail, or a
      * `picture-card` grid of square thumbnail cards. */
-    listType?: 'text' | 'picture-card';
+    listType?: 'text' | 'picture' | 'picture-card';
     /** Overrides the remove-button label (text rows and picture-card
      * corners alike); defaults to the locale string. */
     removeLabel?: string;
     /** Replaces the default row/cell rendering entirely. */
     itemRender?: UploadListItemRender;
-    onRemove: (file: File) => void;
-    onRetry: (file: File) => void;
-    onCancel: (file: File) => void;
+    /** Click handler for `picture` / `picture-card` thumbnails. */
+    onPreview?: (file: UploadValueItem) => void;
+    onRemove: (file: UploadValueItem) => void;
+    onRetry: (file: UploadValueItem) => void;
+    onCancel: (file: UploadValueItem) => void;
 };
-export default function UploadList({ entries, listType, removeLabel, itemRender, onRemove, onRetry, onCancel, }: UploadListProps): import("react").JSX.Element;
+export default function UploadList({ entries, listType, removeLabel, itemRender, onPreview, onRemove, onRetry, onCancel, }: UploadListProps): import("react").JSX.Element;
 export type { UploadListProps };

package/dist/types/components/Upload/index.d.ts

@@ -2,4 +2,4 @@ export { default as Upload } from './Upload';
 export type { UploadProps } from './Upload';
 export { default as UploadCore } from './UploadCore';
 export type { UploadCoreProps } from './UploadCore';
-export type { UploadHandle, UploadStatus, UploadFileStatus, UploadRequest, UploadRequestOptions, UploadListItemActions, UploadListItemRender, } from './types';
+export type { UploadHandle, UploadStatus, UploadFile, UploadValueItem, UploadFileStatus, UploadRequest, UploadRequestOptions, UploadListItemActions, UploadListItemRender, } from './types';

package/dist/types/components/Upload/types.d.ts

@@ -2,10 +2,33 @@ import type { ReactNode } from 'react';
 /** Lifecycle of one tracked file while an upload executor (`request`
  * or `action`) is armed. */
 type UploadStatus = 'idle' | 'uploading' | 'success' | 'error';
-/** Status snapshot for one tracked file — the shape surfaced through
- * `onStatusChange` and `showUploadList.itemRender`. */
+/** A file that already lives on the server: described by metadata
+ * instead of a local `File` object. Passed through `value` to echo an
+ * existing upload — rendered in the built-in list (a `url` thumbnail
+ * for the picture list types), removable, but never re-entering the
+ * upload pipeline (`beforeUpload`/`request`/`action` only ever see
+ * real `File` objects). */
+type UploadFile = {
+    /** Stable identity for list keys. When omitted, one is generated per
+     * object instance and reused across renders. */
+    uid?: string;
+    name: string;
+    /** Remote source rendered as the thumbnail in picture list types. */
+    url?: string;
+    /** Bytes, when the server reports them. */
+    size?: number;
+    /** Terminal state of the echoed upload — defaults to `success`. */
+    status?: 'success' | 'error';
+    /** 0–100, clamped; purely informational for echo entries. */
+    percent?: number;
+};
+/** One item of the value channel: a picked local `File` (enters the
+ * upload pipeline) or an `UploadFile` echo (terminal). */
+type UploadValueItem = File | UploadFile;
+/** Status snapshot for one tracked value item — the shape surfaced
+ * through `onStatusChange` and `showUploadList.itemRender`. */
 type UploadFileStatus = {
-    file: File;
+    file: UploadValueItem;
     status: UploadStatus;
     /** 0–100, clamped; forced to 100 when the upload succeeds. */
     percent: number;
@@ -32,8 +55,9 @@ type UploadListItemActions = {
     /** Abort the in-flight upload and drop the file (uploading state). */
     cancel: () => void;
 };
-/** Custom renderer replacing a built-in list row. */
-type UploadListItemRender = (file: File, status: UploadStatus, percent: number, actions: UploadListItemActions) => ReactNode;
+/** Custom renderer replacing a built-in list row. Echo entries
+ * (`UploadFile` items) reach it the same way local files do. */
+type UploadListItemRender = (file: UploadValueItem, status: UploadStatus, percent: number, actions: UploadListItemActions) => ReactNode;
 /**
  * Imperative surface (`ref.current?.…`) — the same React 19
  * ref-as-prop channel `DialogHandle` uses:
@@ -53,8 +77,10 @@ type UploadHandle = {
     clear: () => void;
 };
 /** Internal tracked row: public status snapshot plus the stable uid the
- * list keys on (File objects have no serializable identity). */
+ * list keys on (value items carry no serializable identity). Echo
+ * entries hold their terminal `status`/`percent` from the
+ * `UploadFile` description. */
 type UploadEntry = UploadFileStatus & {
     uid: string;
 };
-export type { UploadStatus, UploadFileStatus, UploadRequestOptions, UploadRequest, UploadListItemActions, UploadListItemRender, UploadHandle, UploadEntry, };
+export type { UploadStatus, UploadFile, UploadValueItem, UploadFileStatus, UploadRequestOptions, UploadRequest, UploadListItemActions, UploadListItemRender, UploadHandle, UploadEntry, };

package/dist/types/components/VirtualList/VirtualList.d.ts

@@ -1,4 +1,6 @@
 import type { ComponentPropsWithoutRef, ReactNode, Ref } from 'react';
+/** Orientation of the scroll axis. */
+type VirtualListOrientation = 'vertical' | 'horizontal';
 /** Alignment of a row after an imperative `scrollToIndex` call. */
 type VirtualListAlign = 'start' | 'center' | 'end' | 'auto';
 /**
@@ -16,6 +18,11 @@ type VirtualListHandle = {
      * a no-op when the row is already fully visible; rows entering from
      * above align to `'end'` (keeps preceding context on screen), rows
      * entering from below align to `'start'`.
+     *
+     * In grid mode (`columns > 1`) `index` is the item index and maps to
+     * its row/column cell: the row axis honors `align`, the column axis is
+     * brought into view minimally. In horizontal orientation the same
+     * semantics apply along the x axis.
      */
     scrollToIndex: (index: number, align?: VirtualListAlign) => void;
 };
@@ -30,50 +37,96 @@ type VirtualListGroup = {
 };
 type VirtualListProps<T> = {
     items: T[];
-    /** Scrollport height in px. */
+    /**
+     * Scrollport height in px (the cross-axis size when
+     * `orientation='horizontal'`).
+     */
     height: number;
     /**
-     * Row height in px. Exact in fixed mode; in dynamic mode only the
+     * Scrollport width in px — only used with `orientation='horizontal'`:
+     * fixes the port width and serves as the main-axis extent until the
+     * real `clientWidth` is measured. Ignored in vertical orientation.
+     */
+    width?: number;
+    /**
+     * Extent of one item along the scroll axis: row height in vertical
+     * lists, item width with `orientation='horizontal'`, and row height in
+     * grid mode. Exact in fixed mode; in dynamic mode only the
      * pre-measurement estimate (pass `estimatedItemHeight` to opt in).
      */
     itemHeight: number;
     /**
-     * Provide to enable dynamic row heights: every mounted row is measured
-     * with a ResizeObserver and cached by index. Row offsets come from a
-     * prefix sum over measured heights (never-rendered rows fall back to
-     * this estimate), so layout stays correct as rows resize. Cached
-     * heights survive `items` updates and are truncated when the list
+     * Provide to enable dynamic heights along the scroll axis: every
+     * mounted unit (row — in grid mode the whole row wrapper) is measured
+     * with a ResizeObserver and cached by index. Unit offsets come from a
+     * prefix sum over measured sizes (never-rendered units fall back to
+     * this estimate), so layout stays correct as units resize. Cached
+     * sizes survive `items` updates and are truncated when the list
      * shrinks.
      */
     estimatedItemHeight?: number;
     /**
-     * Optional sticky group headers. A header pins to the scrollport top
-     * while its group spans the viewport and slides away when the next
-     * header reaches it. Header positions derive from the same offset
-     * system as rows, so fixed and dynamic modes are both supported.
-     * Headers overlay rows — they occupy no layout space in the list.
+     * Grid mode: lay items out in a row-major grid with this many columns
+     * and virtualize both axes — rows are windowed along the scroll axis
+     * exactly like a vertical list, columns are windowed against the
+     * rendered `clientWidth`. Item `index` maps to row
+     * `Math.floor(index / columns)`, column `index % columns`. Only
+     * supported in the (default) vertical orientation; combining it with
+     * `orientation='horizontal'` logs a dev error and renders a plain
+     * horizontal list.
+     */
+    columns?: number;
+    /**
+     * Column width in px (grid mode only); defaults to `itemHeight`.
+     * Columns are not dynamically measured.
+     */
+    columnWidth?: number;
+    /**
+     * Scroll axis of the list. `'vertical'` (default) keeps the existing
+     * behavior byte-for-byte. `'horizontal'` mirrors the whole windowing
+     * system — prefix sums, dynamic measurement, `scrollToIndex`, reverse
+     * and sticky group headers — onto the x axis: items are sized by
+     * `itemHeight` along it, headers pin to the inline-start edge, and
+     * offsets stay *logical* so RTL keeps item 0 at the inline-start edge
+     * (the physical right edge): RTL `scrollLeft` reads 0 at the start and
+     * goes negative toward the end, which the internal offset scale
+     * normalizes.
+     */
+    orientation?: VirtualListOrientation;
+    /**
+     * Optional sticky group headers. A header pins to the scrollport's
+     * inline-start (vertical: top) while its group spans the viewport and
+     * slides away when the next header reaches it. Header positions derive
+     * from the same offset system as rows, so fixed and dynamic modes are
+     * both supported; in grid mode a header aligns with the row containing
+     * its first item (row granularity). Headers overlay rows — they occupy
+     * no layout space in the list.
      */
     groups?: VirtualListGroup[];
     renderItem: (item: T, index: number) => ReactNode;
-    /** Extra rows kept mounted above/below the visible window. */
+    /**
+     * Extra units kept mounted on either side of the visible window —
+     * rows along the scroll axis, and columns in grid mode.
+     */
     overscan?: number;
     /**
-     * Chat orientation (opt-in): rows anchor to the scrollport bottom with
-     * index 0 at the bottom edge and later indices stacking upward — the
-     * natural geometry for a newest-at-bottom log where new items are
-     * prepended. The viewport parks at the bottom on mount and stays glued
-     * there across appends while the user is parked at the bottom; a
-     * reader who scrolled up keeps their position (rows keep their
-     * top-origin coordinates as content grows upward, so nothing jumps).
+     * Chat orientation (opt-in): units anchor to the scrollport's end edge
+     * (vertical: bottom; horizontal: inline-end) with index 0 at that edge
+     * and later indices stacking toward the start — the natural geometry
+     * for a newest-at-the-edge log where new items are prepended. The
+     * viewport parks at the end on mount and stays glued there across
+     * appends while the user is parked there; a reader who scrolled back
+     * keeps their position (units keep their start-origin coordinates as
+     * content grows toward the start, so nothing jumps).
      *
-     * `scrollToIndex` keeps its signature; alignments mirror vertically —
-     * `'start'` pins the row's bottom edge to the viewport bottom,
-     * `'end'` its top edge to the viewport top. The `VirtualListHandle`
-     * API is unchanged.
+     * `scrollToIndex` keeps its signature; alignments mirror along the
+     * scroll axis — `'start'` pins the unit's end edge to the viewport's
+     * end edge, `'end'` its start edge to the viewport's start edge. The
+     * `VirtualListHandle` API is unchanged.
      */
     reverse?: boolean;
     className?: string;
     ref?: Ref<VirtualListHandle>;
 } & Omit<ComponentPropsWithoutRef<'div'>, 'children'>;
-export default function VirtualList<T>({ items, height, itemHeight, estimatedItemHeight, groups, renderItem, overscan, reverse, className, style, ref, ...rest }: VirtualListProps<T>): import("react").JSX.Element;
-export type { VirtualListProps, VirtualListHandle, VirtualListGroup, VirtualListAlign, };
+export default function VirtualList<T>({ items, height, width, itemHeight, estimatedItemHeight, columns, columnWidth, orientation, groups, renderItem, overscan, reverse, className, style, ref, ...rest }: VirtualListProps<T>): import("react").JSX.Element;
+export type { VirtualListProps, VirtualListHandle, VirtualListGroup, VirtualListAlign, VirtualListOrientation, };

package/dist/types/components/VirtualList/index.d.ts

@@ -1,2 +1,2 @@
 export { default as VirtualList } from './VirtualList';
-export type { VirtualListProps, VirtualListHandle, VirtualListGroup, VirtualListAlign } from './VirtualList';
+export type { VirtualListProps, VirtualListHandle, VirtualListGroup, VirtualListAlign, VirtualListOrientation } from './VirtualList';

package/dist/types/dates/adapter.d.ts

@@ -0,0 +1,74 @@
+/**
+ * Calendar-agnostic date adapter contract.
+ *
+ * `src/lib/components/Calendar/date.ts` owns the complete Gregorian math
+ * (month lengths, view shifts, ISO weeks, value parsing); this module is
+ * the adapter layer above it that lets consumers reason about *any*
+ * calendar's civil dates. The contract is deliberately shaped after the
+ * operations Calendar actually performs on dates — month lengths for grid
+ * building, month shifts for view navigation, name lists for headers —
+ * nothing more.
+ *
+ * Semantics (inherited from date.ts): every `(year, month, day)` triple is
+ * a civil calendar date realized as a *local* Date at midnight. DST
+ * transitions never move midnight, so `toGregorian` output always
+ * round-trips through `fromGregorian` exactly, and internal conversion
+ * arithmetic rides the UTC civil timeline (whole-day millisecond spans
+ * with no DST drift) before materializing the local-midnight result.
+ */
+/** Civil date parts in a specific calendar. `month` is 0-based — the
+ * same `Date#getMonth` convention every date.ts function uses (0 = the
+ * calendar's first month, 11 = its last) — while `day` is 1-based. */
+export type CivilDateParts = {
+    year: number;
+    month: number;
+    day: number;
+};
+/** Calendars with a built-in adapter. `islamic-umalqura` is the
+ * Umm al-Qura tabulation Node and browsers ship in full ICU; valid there
+ * roughly 1300–1600 AH (Gregorian ~1882–2174), beyond which ICU falls
+ * back to computed approximations (still self-consistent through this
+ * adapter, which routes every conversion through Intl). */
+export type HazeCalendarIdentifier = 'gregory' | 'islamic-umalqura';
+/** Month-name width, mirroring Intl's `month` option values. */
+export type MonthNameStyle = 'long' | 'short' | 'narrow';
+/**
+ * Operations on a calendar's civil dates. All members are pure: no
+ * internal state, no mutation of arguments.
+ */
+export type HazeDateAdapter = {
+    /** Which calendar this adapter speaks; matches the `calendar` string
+     * Intl accepts. */
+    readonly identifier: HazeCalendarIdentifier;
+    /** Hijri/lunar-equivalent parts of a Date's **local civil date** (the
+     * date.ts midnight semantics — never the UTC reading of the
+     * instant). */
+    fromGregorian(date: Date): CivilDateParts;
+    /** Local-midnight Date of a civil date in this calendar. Out-of-range
+     * month indices normalize with carry (month 12 → next January,
+     * mirroring date.ts); a `day` that exists in no month of the calendar
+     * throws `RangeError` — never the silent `new Date` rollover. */
+    toGregorian(parts: CivilDateParts): Date;
+    /** Number of days in a month. Out-of-range months normalize with
+     * carry, like date.ts's Gregorian helper. */
+    getDaysInMonth(year: number, month: number): number;
+    /** Shift by whole calendar months with year carry, truncating the day
+     * to the target month's length (1430-12-30 + 1 → next year's month 1
+     * day 29 when that month has 29 days). Pure integer arithmetic on the
+     * month index — no Date rollover hazards. */
+    addMonths(parts: CivilDateParts, delta: number): CivilDateParts;
+    /** Twelve month names, index 0 = first month of the calendar year.
+     * `locale` defaults to the adapter's base presentation locale ('en'
+     * for the built-ins, matching Intl's calendar-extended locales). */
+    monthNames(locale?: string, style?: MonthNameStyle): string[];
+    /** Era abbreviation for a year ("AH" for Hijri, "AD"/"BC" for
+     * Gregorian), via Intl. Optional: consumers that render no era skip
+     * it. */
+    era?(year: number, locale?: string): string;
+};
+/**
+ * Era part of a UTC-civil date in `calendar` via Intl's `era` piece —
+ * the shared implementation behind both built-in adapters' `era` members
+ * (internal helper; not part of the public dates surface).
+ */
+export declare function eraOfDate(date: Date, calendar: HazeCalendarIdentifier, locale: string): string;

package/dist/types/dates/gregory.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Gregorian adapter — a thin shim over the calendar math Calendar already
+ * uses (`src/lib/components/Calendar/date.ts`, imported here, never
+ * duplicated). `fromGregorian`/`toGregorian` are identity mappings
+ * between local-civil Dates and their parts; month-length and view-shift
+ * semantics are date.ts's own, so a Calendar wired to this adapter
+ * behaves exactly like today's hard-wired Gregorian code paths.
+ */
+import type { HazeDateAdapter } from './adapter';
+export declare const gregoryAdapter: HazeDateAdapter;

package/dist/types/dates/index.d.ts

@@ -0,0 +1,6 @@
+export { gregoryAdapter } from './gregory';
+export { islamicUmalquraAdapter } from './islamic';
+export { getAdapter } from './registry';
+export type { CivilDateParts, HazeDateAdapter, HazeCalendarIdentifier, MonthNameStyle, } from './adapter';
+export { formatInTimeZone, getZonedParts } from './timezone';
+export type { ZonedParts } from './timezone';

package/dist/types/dates/islamic.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Islamic (Hijri) adapter for the Umm al-Qura tabulation — the calendar
+ * Node 20+ and every modern browser ship in full ICU
+ * (`islamic-umalqura`). There is no `new HijriDate()`, so both
+ * conversion directions route through Intl: forward via
+ * `formatToParts` on the UTC civil timeline, backward via a seeded
+ * linear search that refines against the forward conversion until the
+ * round-trip matches exactly. All arithmetic is whole-day UTC
+ * milliseconds (no DST drift); results materialize as local-midnight
+ * Dates per the date.ts civil semantics.
+ *
+ * ICU's Umm al-Qura data covers roughly 1300–1600 AH; outside that span
+ * ICU falls back to computed months, which this adapter stays
+ * self-consistent with (every conversion still passes through Intl).
+ */
+import type { HazeDateAdapter } from './adapter';
+export declare const islamicUmalquraAdapter: HazeDateAdapter;

package/dist/types/dates/registry.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Adapter registry — resolves calendar identifiers to the shared
+ * adapter singletons. Lives in its own module so the adapter modules
+ * only depend on the contract (`./adapter`), keeping the module graph
+ * acyclic.
+ */
+import type { HazeCalendarIdentifier, HazeDateAdapter } from './adapter';
+/**
+ * Adapter lookup by calendar identifier. Returns the shared singleton
+ * adapters (`gregoryAdapter`, `islamicUmalquraAdapter`); throws
+ * `RangeError` for identifiers with no built-in adapter.
+ */
+export declare function getAdapter(identifier: HazeCalendarIdentifier): HazeDateAdapter;

package/dist/types/dates/timezone.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Time-zone formatting utilities on top of `Intl.DateTimeFormat`.
+ *
+ * Both functions construct their formatter per call — correct and
+ * dependency-free; callers on hot paths should hoist their own
+ * `Intl.DateTimeFormat` instead.
+ */
+/** Wall-clock parts of an instant inside a time zone. `month` is 0-based
+ * (the same `Date#getMonth` convention as the dates adapters and
+ * Calendar's date.ts), `hour` runs 0–23 (`h23` cycle). */
+export type ZonedParts = {
+    year: number;
+    month: number;
+    day: number;
+    hour: number;
+    minute: number;
+};
+/**
+ * Format an instant in a named IANA time zone.
+ *
+ * `options` are passed through to `Intl.DateTimeFormat` (any locale or
+ * calendar preferences come from the runtime's default locale), with one
+ * override: an explicit `timeZone` inside `options` loses to the
+ * `timeZone` parameter. Throws the `RangeError` Intl emits for an
+ * unknown zone (or an invalid Date) — callers validate zones they do
+ * not control.
+ */
+export declare function formatInTimeZone(date: Date, timeZone: string, options: Intl.DateTimeFormatOptions): string;
+/**
+ * Zoned wall-clock parts (`year`/`month`/`day`/`hour`/`minute`) of an
+ * instant — the pieces a zoned date picker or scheduler compares. The
+ * formatter pins `en-US` (gregorian digits) and `h23` so the numbers are
+ * deterministic; localization is `formatInTimeZone`'s job. Throws the
+ * `RangeError` Intl emits for an unknown zone.
+ */
+export declare function getZonedParts(date: Date, timeZone: string): ZonedParts;

package/dist/types/form/FormItem.d.ts

@@ -110,6 +110,29 @@ export type FormItemOwnProps<TValues extends Record<string, any> = any, P extend
     form?: FormInstance<TValues>;
     name: P;
     label?: ReactNode;
+    /**
+     * Layout mode of the item. `'vertical'` (default) stacks the label
+     * above the control — the exact historical rendering. `'horizontal'`
+     * puts the label in a left column and the control in a right one,
+     * with the error message placed under the control column so sibling
+     * items keep their controls vertically aligned. `'inline'` flows
+     * label + control + error on a single row and adds a trailing
+     * `margin-inline-end` so consecutive inline items space themselves.
+     */
+    layout?: 'vertical' | 'horizontal' | 'inline';
+    /**
+     * Width of the label column in the `'horizontal'` layout: a number is
+     * treated as pixels, a string is used verbatim as a CSS width (e.g.
+     * `'8em'`). Omit for `auto` (content-driven). Ignored in the other
+     * layouts.
+     */
+    labelWidth?: number | string;
+    /**
+     * Text alignment inside the label column in the `'horizontal'`
+     * layout: `'right'` (default — the AntD convention, labels hugging
+     * their controls) or `'left'`. Ignored in the other layouts.
+     */
+    labelAlign?: 'left' | 'right';
     /** Field-level validator, registered through react-f0rm's own
      * `useField` channel — validated per the form's `mode` and on submit.
      * With a typed form the value argument is `PathValueOf<TValues, P>`. */
@@ -308,6 +331,13 @@ export type FormItemProps<TValues extends Record<string, any> = any, P extends F
  * When the field has errors, the first error's message is rendered into a
  * `<span id={errorId} role='alert'>` next to the control; with no errors
  * no extra element is rendered.
+ *
+ * Layout: the default `layout='vertical'` stacks label above control;
+ * `layout='horizontal'` pairs a fixed label column (`labelWidth`,
+ * `labelAlign='right'` by default) with the control, the error slotting
+ * under the control column; `layout='inline'` flows label + control +
+ * error on one row with an automatic inter-item `margin-inline-end`.
+ * The id/label/aria wiring is identical in all three layouts.
  */
-export default function FormItem<TValues extends Record<string, any> = any, P extends FieldPath<TValues> | Name = Name, TInputProps extends Record<string, any> = Record<never, never>, TRawElement extends FormItemRawElement = never>({ form, name, label, validate, mode, validateDebounce, delayError, rules, className, renderError, as: As, asProps, input: Input, eventToValue, valueToProps, children, ...inputProps }: FormItemProps<TValues, P, TInputProps, TRawElement>): import("react").JSX.Element;
+export default function FormItem<TValues extends Record<string, any> = any, P extends FieldPath<TValues> | Name = Name, TInputProps extends Record<string, any> = Record<never, never>, TRawElement extends FormItemRawElement = never>({ form, name, label, layout, labelWidth, labelAlign, validate, mode, validateDebounce, delayError, rules, className, renderError, as: As, asProps, input: Input, eventToValue, valueToProps, children, ...inputProps }: FormItemProps<TValues, P, TInputProps, TRawElement>): import("react").JSX.Element;
 export {};