@orvain/utils 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,64 @@
+Orvain UI Free Components Licence
+Version 1.0
+
+Copyright (c) 2026 Oussema Ajmi, trading as Orvain UI ("Orvain UI", "we").
+
+This licence covers @orvain/react, @orvain/vue, @orvain/tokens, @orvain/utils,
+@orvain/icons and @orvain/assets: their source code, compiled files, design
+tokens, icons and documentation (the "Software").
+
+1. What you may do
+   You may install and use the Software free of charge, in personal and
+   commercial projects, including client work and products you sell. You may
+   modify it for your own projects. The products you build with it are yours.
+
+2. What you may not do
+   - Sell, rent, sublicense or give away the Software, or any part of it, on its
+     own, whether modified or not.
+   - Publish the Software, or a modified copy, as your own UI kit, component
+     library, template or package.
+   - Use it in a product whose main purpose is to let other people build designs
+     or interfaces with it.
+   - Remove or change the copyright notices in it.
+
+3. Paid products
+   The Software is the free part of Orvain UI. The Orvain Library (more
+   components and blocks, the MCP server and the CLI) and the Orvain Figma
+   library are separate products under the Orvain UI Licence at
+   https://orvain.dev/license. This licence gives you no rights to them.
+
+4. Third-party material
+   The Software includes material that belongs to others and has its own terms:
+   - Country flags are derived from circle-flags (MIT). See NOTICE.
+   - Brand names and logos in @orvain/assets belong to their owners. They are
+     included for illustration. You receive no rights to them.
+   - The components are designed for the Satoshi typeface. It is not included in
+     the Software. It is licensed by its foundry (Fontshare), not by Orvain UI,
+     and your use of it is governed by the foundry's licence.
+
+5. Ownership
+   Orvain UI keeps ownership of the Software and the Orvain UI name and brand.
+   This licence gives you the right to use the Software. It does not transfer
+   ownership.
+
+6. No warranty
+   The Software is provided "as is", without warranty of any kind, express or
+   implied, including fitness for a particular purpose and non-infringement.
+
+7. Limit of liability
+   To the extent the law allows, Orvain UI is not liable for any claim, damages
+   or other liability arising from the Software or its use, including indirect
+   or consequential loss. Nothing in this licence limits liability that the law
+   does not allow to be limited.
+
+8. Ending
+   This licence ends automatically if you break it. You must then stop using the
+   Software and delete your copies. Products you have already delivered may stay
+   in use.
+
+9. Governing law
+   Tunisian law applies. Mandatory consumer protections in your own country still
+   apply.
+
+10. Contact
+   Questions about permitted use: hello@contactoussema.uk

package/README.md

@@ -1,3 +1,49 @@
-# Temporary Holding Version
+# @orvain/utils
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Small shared helpers and types used across the Orvain Design System packages.
+
+> Commercial software. See [LICENSE](./LICENSE) — use is governed by your
+> agreement with Orvain Labs.
+
+This is an internal support package, published because `@orvain/react` and
+`@orvain/vue` depend on it. It is not a general-purpose utility library and its
+surface may change between minors. Prefer a dedicated library for anything you
+need in application code.
+
+## Install
+
+```bash
+npm install @orvain/utils
+```
+
+## Exports
+
+```ts
+import { clamp, cx, omit, typedEntries, generateId, announce, trapFocus } from '@orvain/utils';
+```
+
+| Export | Signature | Notes |
+|---|---|---|
+| `clamp` | `(value, min, max) => number` | inclusive |
+| `cx` | `(...classes) => string` | joins truthy class strings |
+| `omit` | `(obj, keys) => Omit<T, K>` | for prop forwarding |
+| `typedEntries` | `(obj) => [keyof T, T[keyof T]][]` | `Object.entries` with inferred keys |
+| `generateId` | `(prefix?) => string` | module-scoped counter — see *Caveats* |
+| `getFocusableElements` | `(container) => HTMLElement[]` | |
+| `trapFocus` | `(container) => cleanup` | cycles Tab within `container` |
+| `announce` | `(message, politeness?) => void` | writes to a shared `aria-live` region |
+| `Size`, `Variant`, `Intent`, `ColorScheme` | type aliases | shared prop vocabularies |
+
+## Caveats
+
+- **`generateId` is not SSR-safe.** It increments a module-level counter, so
+  server and client can disagree and hydration will mismatch. Use React's
+  `useId` or Vue's `useId` instead; `generateId` is for non-component code.
+- **`trapFocus` does not restore focus** when it tears down, and does not move
+  focus into the container on setup. You need to handle both yourself.
+- **`announce` and `trapFocus` touch `document`** and must only run in the
+  browser.
+
+## Related packages
+
+- [`@orvain/react`](../react), [`@orvain/vue`](../vue) — the component libraries

package/dist/a11y.d.cts

@@ -0,0 +1,102 @@
+/**
+ * Generates a stable, unique ID for associating form labels with inputs.
+ * In React 18+ prefer useId(); use this in Vue or outside React.
+ */
+export declare function generateId(prefix?: string): string;
+export declare function getFocusableElements(container: HTMLElement): HTMLElement[];
+/** Where a dialog puts focus when it opens: an element, or a CSS selector resolved inside the dialog. */
+export type DialogInitialFocus = HTMLElement | string | null | undefined;
+/**
+ * Moves focus into a dialog that has just opened, per the APG dialog pattern:
+ *
+ * 1. `initialFocus`, when given;
+ * 2. an element marked `data-autofocus` (an alert dialog's least destructive
+ *    action, e.g. ConfirmModal's Cancel);
+ * 3. the first form field;
+ * 4. the first other control, skipping the close (×) button, which is the
+ *    one action a user rarely wants first;
+ * 5. the dialog itself (made programmatically focusable), so a screen reader
+ *    starts at its name.
+ *
+ * Returns the element that received focus.
+ */
+export declare function focusDialogInitial(dialog: HTMLElement, initialFocus?: DialogInitialFocus): HTMLElement;
+/**
+ * Traps keyboard focus within `container`.
+ * Returns a cleanup function to remove the listener.
+ */
+export declare function trapFocus(container: HTMLElement): () => void;
+/** Announce a message to screen readers via an aria-live region. */
+export declare function announce(message: string, politeness?: 'polite' | 'assertive'): void;
+/** Selector for the enabled items of one `role="menu"` list. */
+export declare const MENU_ITEM_SELECTOR = "[role=\"menuitem\"]:not([aria-disabled=\"true\"]):not(:disabled), [role=\"menuitemcheckbox\"]:not([aria-disabled=\"true\"]):not(:disabled), [role=\"menuitemradio\"]:not([aria-disabled=\"true\"]):not(:disabled)";
+/** The items that belong to `menu` itself (items of nested menus are skipped). */
+export declare function getMenuItems(menu: HTMLElement): HTMLElement[];
+/** Roving tabindex: `target` (or the current stop, or the first item) gets 0, the rest −1. */
+export declare function setMenuRovingItem(menu: HTMLElement, target?: HTMLElement | null): HTMLElement | undefined;
+/** Move focus to an item of `menu` (index wraps; `'first'` / `'last'` accepted). */
+export declare function focusMenuItem(menu: HTMLElement, index: number | 'first' | 'last'): HTMLElement | undefined;
+/**
+ * Handles the APG menu keys inside one `role="menu"`: ArrowDown / ArrowUp
+ * (wrapping), Home / End, and single-character typeahead on the item text
+ * (or `aria-label`). Returns true when the key was consumed. Submenu keys
+ * (ArrowRight / ArrowLeft / Enter / Escape) are left to the caller.
+ */
+export declare function handleMenuKeydown(event: KeyboardEvent, menu: HTMLElement): boolean;
+export interface SubmenuHoverIntentOptions {
+    /** Rect of the open submenu panel, or null when none is open. */
+    getSubmenuRect: () => {
+        left: number;
+        right: number;
+        top: number;
+        bottom: number;
+    } | null;
+    /** Called with the row key to activate (null = a row without a submenu). */
+    onActivate: (key: string | null) => void;
+    /** Delay before the hovered row takes over (ms). */
+    delay?: number;
+    /** Longer delay while the pointer is heading for the open submenu (ms). */
+    aimDelay?: number;
+}
+export interface SubmenuHoverIntent {
+    /** Pointer moved over the menu (records the path). */
+    move: (event: {
+        clientX: number;
+        clientY: number;
+    }) => void;
+    /** Pointer entered a row (`key` = row with a submenu, null = plain row). */
+    enter: (key: string | null) => void;
+    /** Pointer reached the submenu: cancel any pending switch. */
+    enterSubmenu: () => void;
+    /** Cancel pending timers (unmount). */
+    cancel: () => void;
+}
+/**
+ * Hover-to-open for side submenus. A row takes over after `delay`; while the
+ * pointer moves inside the triangle between where it was and the near edge of
+ * the open submenu (it is "aiming" at it), the switch waits for `aimDelay` and
+ * re-checks, so crossing other rows on the way does not close the submenu.
+ * Framework-agnostic: React and Vue feed it pointer events.
+ */
+export declare function createSubmenuHoverIntent({ getSubmenuRect, onActivate, delay, aimDelay, }: SubmenuHoverIntentOptions): SubmenuHoverIntent;
+/**
+ * Sideways-scrolling strip with a hidden scrollbar: a vertical mouse wheel
+ * scrolls it horizontally, and `data-scroll-end` is set while it cannot
+ * scroll further right (so a right-edge fade can drop away). Returns cleanup.
+ */
+export declare function bindHorizontalStrip(strip: HTMLElement): () => void;
+/**
+ * Marks which ends of a sideways-scrolling element still hide content:
+ * `data-more-start` / `data-more-end` are set while it can scroll further
+ * that way (direction-aware, so they follow `dir="rtl"`), and
+ * `--scrollbar-size` holds the height of its scrollbar (0px for overlay
+ * scrollbars), so an edge fade can leave the scrollbar alone. Returns cleanup.
+ */
+export declare function bindScrollEdges(el: HTMLElement): () => void;
+/**
+ * Arrow-key movement between the columns of a panel of links (e.g. a mega
+ * menu). `columns` are the column containers in reading order; Up / Down move
+ * within the focused column, Left / Right jump to the neighbouring column's
+ * link nearest in height. Tab is untouched. Returns true when it moved focus.
+ */
+export declare function handleColumnArrowKeys(event: KeyboardEvent, columns: HTMLElement[]): boolean;

package/dist/a11y.d.ts

@@ -0,0 +1,103 @@
+/**
+ * Generates a stable, unique ID for associating form labels with inputs.
+ * In React 18+ prefer useId(); use this in Vue or outside React.
+ */
+export declare function generateId(prefix?: string): string;
+export declare function getFocusableElements(container: HTMLElement): HTMLElement[];
+/** Where a dialog puts focus when it opens: an element, or a CSS selector resolved inside the dialog. */
+export type DialogInitialFocus = HTMLElement | string | null | undefined;
+/**
+ * Moves focus into a dialog that has just opened, per the APG dialog pattern:
+ *
+ * 1. `initialFocus`, when given;
+ * 2. an element marked `data-autofocus` (an alert dialog's least destructive
+ *    action, e.g. ConfirmModal's Cancel);
+ * 3. the first form field;
+ * 4. the first other control, skipping the close (×) button, which is the
+ *    one action a user rarely wants first;
+ * 5. the dialog itself (made programmatically focusable), so a screen reader
+ *    starts at its name.
+ *
+ * Returns the element that received focus.
+ */
+export declare function focusDialogInitial(dialog: HTMLElement, initialFocus?: DialogInitialFocus): HTMLElement;
+/**
+ * Traps keyboard focus within `container`.
+ * Returns a cleanup function to remove the listener.
+ */
+export declare function trapFocus(container: HTMLElement): () => void;
+/** Announce a message to screen readers via an aria-live region. */
+export declare function announce(message: string, politeness?: 'polite' | 'assertive'): void;
+/** Selector for the enabled items of one `role="menu"` list. */
+export declare const MENU_ITEM_SELECTOR = "[role=\"menuitem\"]:not([aria-disabled=\"true\"]):not(:disabled), [role=\"menuitemcheckbox\"]:not([aria-disabled=\"true\"]):not(:disabled), [role=\"menuitemradio\"]:not([aria-disabled=\"true\"]):not(:disabled)";
+/** The items that belong to `menu` itself (items of nested menus are skipped). */
+export declare function getMenuItems(menu: HTMLElement): HTMLElement[];
+/** Roving tabindex: `target` (or the current stop, or the first item) gets 0, the rest −1. */
+export declare function setMenuRovingItem(menu: HTMLElement, target?: HTMLElement | null): HTMLElement | undefined;
+/** Move focus to an item of `menu` (index wraps; `'first'` / `'last'` accepted). */
+export declare function focusMenuItem(menu: HTMLElement, index: number | 'first' | 'last'): HTMLElement | undefined;
+/**
+ * Handles the APG menu keys inside one `role="menu"`: ArrowDown / ArrowUp
+ * (wrapping), Home / End, and single-character typeahead on the item text
+ * (or `aria-label`). Returns true when the key was consumed. Submenu keys
+ * (ArrowRight / ArrowLeft / Enter / Escape) are left to the caller.
+ */
+export declare function handleMenuKeydown(event: KeyboardEvent, menu: HTMLElement): boolean;
+export interface SubmenuHoverIntentOptions {
+    /** Rect of the open submenu panel, or null when none is open. */
+    getSubmenuRect: () => {
+        left: number;
+        right: number;
+        top: number;
+        bottom: number;
+    } | null;
+    /** Called with the row key to activate (null = a row without a submenu). */
+    onActivate: (key: string | null) => void;
+    /** Delay before the hovered row takes over (ms). */
+    delay?: number;
+    /** Longer delay while the pointer is heading for the open submenu (ms). */
+    aimDelay?: number;
+}
+export interface SubmenuHoverIntent {
+    /** Pointer moved over the menu (records the path). */
+    move: (event: {
+        clientX: number;
+        clientY: number;
+    }) => void;
+    /** Pointer entered a row (`key` = row with a submenu, null = plain row). */
+    enter: (key: string | null) => void;
+    /** Pointer reached the submenu: cancel any pending switch. */
+    enterSubmenu: () => void;
+    /** Cancel pending timers (unmount). */
+    cancel: () => void;
+}
+/**
+ * Hover-to-open for side submenus. A row takes over after `delay`; while the
+ * pointer moves inside the triangle between where it was and the near edge of
+ * the open submenu (it is "aiming" at it), the switch waits for `aimDelay` and
+ * re-checks, so crossing other rows on the way does not close the submenu.
+ * Framework-agnostic: React and Vue feed it pointer events.
+ */
+export declare function createSubmenuHoverIntent({ getSubmenuRect, onActivate, delay, aimDelay, }: SubmenuHoverIntentOptions): SubmenuHoverIntent;
+/**
+ * Sideways-scrolling strip with a hidden scrollbar: a vertical mouse wheel
+ * scrolls it horizontally, and `data-scroll-end` is set while it cannot
+ * scroll further right (so a right-edge fade can drop away). Returns cleanup.
+ */
+export declare function bindHorizontalStrip(strip: HTMLElement): () => void;
+/**
+ * Marks which ends of a sideways-scrolling element still hide content:
+ * `data-more-start` / `data-more-end` are set while it can scroll further
+ * that way (direction-aware, so they follow `dir="rtl"`), and
+ * `--scrollbar-size` holds the height of its scrollbar (0px for overlay
+ * scrollbars), so an edge fade can leave the scrollbar alone. Returns cleanup.
+ */
+export declare function bindScrollEdges(el: HTMLElement): () => void;
+/**
+ * Arrow-key movement between the columns of a panel of links (e.g. a mega
+ * menu). `columns` are the column containers in reading order; Up / Down move
+ * within the focused column, Left / Right jump to the neighbouring column's
+ * link nearest in height. Tab is untouched. Returns true when it moved focus.
+ */
+export declare function handleColumnArrowKeys(event: KeyboardEvent, columns: HTMLElement[]): boolean;
+//# sourceMappingURL=a11y.d.ts.map

package/dist/breakpoints.d.cts

@@ -0,0 +1,36 @@
+/**
+ * Figma "Responsive Tokens" breakpoints for JS (matchMedia, resize logic).
+ * Same values as `breakpoint.*` in `@orvain/tokens` (src/breakpoints.json):
+ * mobile 320–767, tablet 768–1023, desktop ≥ 1024. CSS Modules use literal
+ * media queries with a token comment instead (see docs/responsive.md).
+ */
+export declare const BREAKPOINTS: {
+    readonly mobile: {
+        readonly min: 320;
+        readonly max: 767;
+    };
+    readonly tablet: {
+        readonly min: 768;
+        readonly max: 1023;
+    };
+    readonly desktop: {
+        readonly min: 1024;
+        readonly max: 3200;
+    };
+};
+export type Breakpoint = keyof typeof BREAKPOINTS;
+/** Media query strings matching the CSS convention (mobile-first). */
+export declare const MEDIA: {
+    /** below tablet: 0–767 */
+    readonly mobile: "(max-width: 767px)";
+    /** tablet only: 768–1023 */
+    readonly tablet: "(min-width: 768px) and (max-width: 1023px)";
+    /** tablet and up: ≥ 768 */
+    readonly tabletUp: "(min-width: 768px)";
+    /** below desktop: 0–1023 */
+    readonly belowDesktop: "(max-width: 1023px)";
+    /** desktop: ≥ 1024 */
+    readonly desktop: "(min-width: 1024px)";
+};
+/** Which Figma breakpoint a viewport width falls in. */
+export declare function breakpointFor(width: number): Breakpoint;

package/dist/breakpoints.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Figma "Responsive Tokens" breakpoints for JS (matchMedia, resize logic).
+ * Same values as `breakpoint.*` in `@orvain/tokens` (src/breakpoints.json):
+ * mobile 320–767, tablet 768–1023, desktop ≥ 1024. CSS Modules use literal
+ * media queries with a token comment instead (see docs/responsive.md).
+ */
+export declare const BREAKPOINTS: {
+    readonly mobile: {
+        readonly min: 320;
+        readonly max: 767;
+    };
+    readonly tablet: {
+        readonly min: 768;
+        readonly max: 1023;
+    };
+    readonly desktop: {
+        readonly min: 1024;
+        readonly max: 3200;
+    };
+};
+export type Breakpoint = keyof typeof BREAKPOINTS;
+/** Media query strings matching the CSS convention (mobile-first). */
+export declare const MEDIA: {
+    /** below tablet: 0–767 */
+    readonly mobile: "(max-width: 767px)";
+    /** tablet only: 768–1023 */
+    readonly tablet: "(min-width: 768px) and (max-width: 1023px)";
+    /** tablet and up: ≥ 768 */
+    readonly tabletUp: "(min-width: 768px)";
+    /** below desktop: 0–1023 */
+    readonly belowDesktop: "(max-width: 1023px)";
+    /** desktop: ≥ 1024 */
+    readonly desktop: "(min-width: 1024px)";
+};
+/** Which Figma breakpoint a viewport width falls in. */
+export declare function breakpointFor(width: number): Breakpoint;
+//# sourceMappingURL=breakpoints.d.ts.map

package/dist/calendar.d.cts

@@ -0,0 +1,127 @@
+/**
+ * Calendar (scheduler) helpers, shared by the React and Vue `Calendar`.
+ *
+ * Calendar, DatePicker and RangePicker share this day/month arithmetic
+ * (local time, weeks starting on `weekStartsOn`), so they agree on which
+ * days a month grid shows.
+ */
+export type CalendarView = 'day' | 'week' | 'month';
+export type CalendarWeekStart = 0 | 1 | 2 | 3 | 4 | 5 | 6;
+/** Figma "Application" axis of the Calendar Items sets. */
+export type CalendarApplication = 'neutral' | 'brand' | 'purple' | 'success' | 'warning' | 'error';
+/** One scheduled event. `start`/`end` are local `Date`s; `end` is exclusive. */
+export interface CalendarEventData {
+    id: string;
+    title: string;
+    /** Shorter title for narrow chips (e.g. "Standup" for "Engineering standup"). Month chips always use it. */
+    shortTitle?: string;
+    start: Date;
+    end: Date;
+    /** Colour family (Figma "Application"). Default `brand`. */
+    application?: CalendarApplication;
+    /** Second line (Figma "Sub Title"). */
+    description?: string;
+    /** Short trailing label (Figma "Caption", e.g. "Cap."). */
+    caption?: string;
+    /** Location tag + map (Calendar Items v1 Type=v4). */
+    location?: string;
+    /** Image behind the location tag (Calendar Items v1 Type=v4). */
+    imageSrc?: string;
+    /** Glyph of the event's icon container: an `@orvain/icons` name or icon
+     *  definition (`IconSource`; typed loosely here because utils does not depend
+     *  on the icon package). Omitted, the chip keeps Figma's default `car-01`. */
+    icon?: string | object;
+    disabled?: boolean;
+}
+/** A timed event placed on the day/week grid. Units: hours and day columns. */
+export interface CalendarPlacedEvent {
+    event: CalendarEventData;
+    /** First day column (0-based) the event covers in the visible range. */
+    dayIndex: number;
+    /** Number of day columns it spans (≥ 1). */
+    daySpan: number;
+    /** Start, in hours from the grid's `startHour` (clamped to the grid). */
+    top: number;
+    /** Length in hours (clamped to the grid). */
+    height: number;
+    /** Lane among events that overlap it (0-based) and total lanes in its cluster. */
+    lane: number;
+    lanes: number;
+}
+export declare function startOfDay(date: Date): Date;
+export declare function addDays(date: Date, delta: number): Date;
+export declare function startOfMonth(date: Date): Date;
+/** First day of the month `delta` months away (month navigation). */
+export declare function shiftMonth(date: Date, delta: number): Date;
+/** Number of days in `date`'s month. */
+export declare function daysInMonth(date: Date): number;
+/** Same day-of-month `delta` months away, clamped to that month's last day (Jan 31 + 1 → Feb 28/29). */
+export declare function addMonthsClamped(date: Date, delta: number): Date;
+export declare function isSameDay(a: Date, b: Date): boolean;
+export declare function isSameMonth(a: Date, b: Date): boolean;
+export declare function startOfWeek(date: Date, weekStartsOn?: CalendarWeekStart): Date;
+/** Local midnight of `date` in epoch ms: a numeric day key that also orders days. */
+export declare function dayStamp(date: Date): number;
+/** `a` is an earlier calendar day than `b` (times of day ignored). */
+export declare function isBeforeDay(a: Date, b: Date): boolean;
+/** `date` falls before `min` or after `max` (whole days; either bound optional). */
+export declare function isDayOutOfRange(date: Date, min?: Date | null, max?: Date | null): boolean;
+/** `date` moved inside `[min, max]` (whole days; a clamped result is that bound's midnight). */
+export declare function clampDay(date: Date, min?: Date | null, max?: Date | null): Date;
+/** Stable `YYYY-M-D` key for a local day. */
+export declare function dayKey(date: Date): string;
+/** Days shown by a view: 1 (day), 7 (week) or the full weeks of the month grid. */
+export declare function visibleDays(date: Date, view: CalendarView, weekStartsOn?: CalendarWeekStart): Date[];
+/**
+ * Month grid as weeks of 7 days, leading/trailing days from the adjacent
+ * months included. `fixedWeeks` always returns 6 weeks, so a picker keeps
+ * its height from month to month.
+ */
+export declare function buildMonthGrid(month: Date, weekStartsOn?: CalendarWeekStart, fixedWeeks?: boolean): Date[][];
+/** One day of a month grid. */
+export interface MonthGridCell {
+    date: Date;
+    /** Day of the month (1–31). */
+    day: number;
+    /** In the grid's own month (not a leading or trailing day). */
+    inMonth: boolean;
+    /** A day of the following month (after the last day). */
+    trailing: boolean;
+}
+/** `buildMonthGrid` with each day's place in the month, for pickers that style leading and trailing days. */
+export declare function monthGridCells(month: Date, weekStartsOn?: CalendarWeekStart, fixedWeeks?: boolean): MonthGridCell[][];
+/** Moves `date` one period of `view` forward (`delta` = 1) or back (-1). */
+export declare function shiftCalendarDate(date: Date, view: CalendarView, delta: number): Date;
+/** Weekday labels starting on `weekStartsOn` (e.g. "Sun", "Mon"…). */
+export declare function weekdayLabels(weekStartsOn?: CalendarWeekStart, locale?: string, weekday?: 'short' | 'long'): string[];
+/** "February 2026": month and year, first letter capitalised (fr-FR writes "février 2026"). */
+export declare function formatMonthLabel(date: Date, locale?: string): string;
+/** "Aug 03, 2025": a range endpoint in pickers and their fields. */
+export declare function formatShortDate(date: Date, locale?: string): string;
+/** "Aug 03, 2025 – Aug 09, 2025", one endpoint alone, or `empty` when neither is set. */
+export declare function formatDateRange(start: Date | null | undefined, end: Date | null | undefined, locale?: string, empty?: string): string;
+/** Nav bar title per view: "April 26, 2026" · "Apr 20 - 26, 2026" · "April 2026". */
+export declare function formatCalendarTitle(date: Date, view: CalendarView, locale?: string, weekStartsOn?: CalendarWeekStart): string;
+/** Hour-gutter label: "7am", "12pm" (Figma Time Item text). */
+export declare function formatHourLabel(hour: number, locale?: string): string;
+/** Clock label: "11:32 AM". */
+export declare function formatTimeLabel(date: Date, locale?: string): string;
+/** "9:00 AM – 10:30 AM" for an event (same-day), with dates when it spans days. */
+export declare function formatEventTimeRange(event: Pick<CalendarEventData, 'start' | 'end'>, locale?: string): string;
+/** Events that touch the local day `day` (end exclusive), in start order. */
+export declare function eventsOnDay(events: readonly CalendarEventData[], day: Date): CalendarEventData[];
+/**
+ * Places timed events on a day/week grid of `days`, from `startHour` to
+ * `endHour`. An event that crosses midnight inside the range spans several
+ * day columns (one chip, as the Figma weekly view draws it) and keeps its
+ * start time as its row. Overlapping events (same columns and times) share
+ * the width in lanes.
+ */
+export declare function layoutTimedEvents(events: readonly CalendarEventData[], days: readonly Date[], startHour?: number, endHour?: number, minHours?: number): CalendarPlacedEvent[];
+/**
+ * Day view rows: events whose times overlap the first event of a row share that row
+ * (side by side, anchored at the row's start); the rest start new rows. Input in any order.
+ */
+export declare function groupEventRows(placed: readonly CalendarPlacedEvent[]): CalendarPlacedEvent[][];
+/** True when `now` falls inside the period `view` shows around `date` (day, week or month). */
+export declare function isCurrentPeriod(date: Date, now: Date, view: CalendarView, weekStartsOn?: CalendarWeekStart): boolean;

package/dist/calendar.d.ts

@@ -0,0 +1,128 @@
+/**
+ * Calendar (scheduler) helpers, shared by the React and Vue `Calendar`.
+ *
+ * Calendar, DatePicker and RangePicker share this day/month arithmetic
+ * (local time, weeks starting on `weekStartsOn`), so they agree on which
+ * days a month grid shows.
+ */
+export type CalendarView = 'day' | 'week' | 'month';
+export type CalendarWeekStart = 0 | 1 | 2 | 3 | 4 | 5 | 6;
+/** Figma "Application" axis of the Calendar Items sets. */
+export type CalendarApplication = 'neutral' | 'brand' | 'purple' | 'success' | 'warning' | 'error';
+/** One scheduled event. `start`/`end` are local `Date`s; `end` is exclusive. */
+export interface CalendarEventData {
+    id: string;
+    title: string;
+    /** Shorter title for narrow chips (e.g. "Standup" for "Engineering standup"). Month chips always use it. */
+    shortTitle?: string;
+    start: Date;
+    end: Date;
+    /** Colour family (Figma "Application"). Default `brand`. */
+    application?: CalendarApplication;
+    /** Second line (Figma "Sub Title"). */
+    description?: string;
+    /** Short trailing label (Figma "Caption", e.g. "Cap."). */
+    caption?: string;
+    /** Location tag + map (Calendar Items v1 Type=v4). */
+    location?: string;
+    /** Image behind the location tag (Calendar Items v1 Type=v4). */
+    imageSrc?: string;
+    /** Glyph of the event's icon container: an `@orvain/icons` name or icon
+     *  definition (`IconSource`; typed loosely here because utils does not depend
+     *  on the icon package). Omitted, the chip keeps Figma's default `car-01`. */
+    icon?: string | object;
+    disabled?: boolean;
+}
+/** A timed event placed on the day/week grid. Units: hours and day columns. */
+export interface CalendarPlacedEvent {
+    event: CalendarEventData;
+    /** First day column (0-based) the event covers in the visible range. */
+    dayIndex: number;
+    /** Number of day columns it spans (≥ 1). */
+    daySpan: number;
+    /** Start, in hours from the grid's `startHour` (clamped to the grid). */
+    top: number;
+    /** Length in hours (clamped to the grid). */
+    height: number;
+    /** Lane among events that overlap it (0-based) and total lanes in its cluster. */
+    lane: number;
+    lanes: number;
+}
+export declare function startOfDay(date: Date): Date;
+export declare function addDays(date: Date, delta: number): Date;
+export declare function startOfMonth(date: Date): Date;
+/** First day of the month `delta` months away (month navigation). */
+export declare function shiftMonth(date: Date, delta: number): Date;
+/** Number of days in `date`'s month. */
+export declare function daysInMonth(date: Date): number;
+/** Same day-of-month `delta` months away, clamped to that month's last day (Jan 31 + 1 → Feb 28/29). */
+export declare function addMonthsClamped(date: Date, delta: number): Date;
+export declare function isSameDay(a: Date, b: Date): boolean;
+export declare function isSameMonth(a: Date, b: Date): boolean;
+export declare function startOfWeek(date: Date, weekStartsOn?: CalendarWeekStart): Date;
+/** Local midnight of `date` in epoch ms: a numeric day key that also orders days. */
+export declare function dayStamp(date: Date): number;
+/** `a` is an earlier calendar day than `b` (times of day ignored). */
+export declare function isBeforeDay(a: Date, b: Date): boolean;
+/** `date` falls before `min` or after `max` (whole days; either bound optional). */
+export declare function isDayOutOfRange(date: Date, min?: Date | null, max?: Date | null): boolean;
+/** `date` moved inside `[min, max]` (whole days; a clamped result is that bound's midnight). */
+export declare function clampDay(date: Date, min?: Date | null, max?: Date | null): Date;
+/** Stable `YYYY-M-D` key for a local day. */
+export declare function dayKey(date: Date): string;
+/** Days shown by a view: 1 (day), 7 (week) or the full weeks of the month grid. */
+export declare function visibleDays(date: Date, view: CalendarView, weekStartsOn?: CalendarWeekStart): Date[];
+/**
+ * Month grid as weeks of 7 days, leading/trailing days from the adjacent
+ * months included. `fixedWeeks` always returns 6 weeks, so a picker keeps
+ * its height from month to month.
+ */
+export declare function buildMonthGrid(month: Date, weekStartsOn?: CalendarWeekStart, fixedWeeks?: boolean): Date[][];
+/** One day of a month grid. */
+export interface MonthGridCell {
+    date: Date;
+    /** Day of the month (1–31). */
+    day: number;
+    /** In the grid's own month (not a leading or trailing day). */
+    inMonth: boolean;
+    /** A day of the following month (after the last day). */
+    trailing: boolean;
+}
+/** `buildMonthGrid` with each day's place in the month, for pickers that style leading and trailing days. */
+export declare function monthGridCells(month: Date, weekStartsOn?: CalendarWeekStart, fixedWeeks?: boolean): MonthGridCell[][];
+/** Moves `date` one period of `view` forward (`delta` = 1) or back (-1). */
+export declare function shiftCalendarDate(date: Date, view: CalendarView, delta: number): Date;
+/** Weekday labels starting on `weekStartsOn` (e.g. "Sun", "Mon"…). */
+export declare function weekdayLabels(weekStartsOn?: CalendarWeekStart, locale?: string, weekday?: 'short' | 'long'): string[];
+/** "February 2026": month and year, first letter capitalised (fr-FR writes "février 2026"). */
+export declare function formatMonthLabel(date: Date, locale?: string): string;
+/** "Aug 03, 2025": a range endpoint in pickers and their fields. */
+export declare function formatShortDate(date: Date, locale?: string): string;
+/** "Aug 03, 2025 – Aug 09, 2025", one endpoint alone, or `empty` when neither is set. */
+export declare function formatDateRange(start: Date | null | undefined, end: Date | null | undefined, locale?: string, empty?: string): string;
+/** Nav bar title per view: "April 26, 2026" · "Apr 20 - 26, 2026" · "April 2026". */
+export declare function formatCalendarTitle(date: Date, view: CalendarView, locale?: string, weekStartsOn?: CalendarWeekStart): string;
+/** Hour-gutter label: "7am", "12pm" (Figma Time Item text). */
+export declare function formatHourLabel(hour: number, locale?: string): string;
+/** Clock label: "11:32 AM". */
+export declare function formatTimeLabel(date: Date, locale?: string): string;
+/** "9:00 AM – 10:30 AM" for an event (same-day), with dates when it spans days. */
+export declare function formatEventTimeRange(event: Pick<CalendarEventData, 'start' | 'end'>, locale?: string): string;
+/** Events that touch the local day `day` (end exclusive), in start order. */
+export declare function eventsOnDay(events: readonly CalendarEventData[], day: Date): CalendarEventData[];
+/**
+ * Places timed events on a day/week grid of `days`, from `startHour` to
+ * `endHour`. An event that crosses midnight inside the range spans several
+ * day columns (one chip, as the Figma weekly view draws it) and keeps its
+ * start time as its row. Overlapping events (same columns and times) share
+ * the width in lanes.
+ */
+export declare function layoutTimedEvents(events: readonly CalendarEventData[], days: readonly Date[], startHour?: number, endHour?: number, minHours?: number): CalendarPlacedEvent[];
+/**
+ * Day view rows: events whose times overlap the first event of a row share that row
+ * (side by side, anchored at the row's start); the rest start new rows. Input in any order.
+ */
+export declare function groupEventRows(placed: readonly CalendarPlacedEvent[]): CalendarPlacedEvent[][];
+/** True when `now` falls inside the period `view` shows around `date` (day, week or month). */
+export declare function isCurrentPeriod(date: Date, now: Date, view: CalendarView, weekStartsOn?: CalendarWeekStart): boolean;
+//# sourceMappingURL=calendar.d.ts.map