@orvain/utils 0.0.0-stage → 0.1.1

package/dist/floating.d.cts

@@ -0,0 +1,137 @@
+/**
+ * Positioning for floating surfaces (menus, listboxes, popovers, tooltips):
+ * one engine for every component, framework-free. The React hook and the Vue
+ * composable (`internal/useFloating`) wrap it.
+ *
+ * The panel is promoted to the browser's top layer (`popover="manual"`), so no
+ * `overflow: hidden`, transformed or lower-stacked ancestor can clip or cover
+ * it, and it is placed with `position: fixed` viewport coordinates. It stays a
+ * DOM child of its component, which keeps Tab order, inherited styles (theme,
+ * `dir`, custom properties), event bubbling and light-dismiss containment
+ * exactly as they were inline. Without the Popover API it falls back to
+ * `position: fixed` on the `--orvain-z-index-*` scale.
+ *
+ * `computeFloatingLayout` is the pure geometry (placement, offset, flip,
+ * shift, arrow, RTL); `placeFloating` measures the DOM and applies it;
+ * `autoUpdate` re-places on scroll (any scroll parent), resize and size changes.
+ */
+export type FloatingSide = 'top' | 'right' | 'bottom' | 'left';
+/** Logical alignment along the anchor edge: `start` is the left edge in LTR
+ *  and the right edge in RTL on the top / bottom sides; the top edge on the
+ *  left / right sides. */
+export type FloatingAlign = 'start' | 'center' | 'end';
+export interface FloatingRect {
+    left: number;
+    top: number;
+    width: number;
+    height: number;
+}
+export interface FloatingLayoutOptions {
+    /** Side of the anchor the panel opens on. Default `bottom`. */
+    side?: FloatingSide | undefined;
+    /** Edge of the anchor the panel lines up with. Default `start`. */
+    align?: FloatingAlign | undefined;
+    /** Gap between the anchor and the panel (px). Default 0. */
+    offset?: number | undefined;
+    /** Extra move along the anchor edge (px, towards the right / bottom). Default 0. */
+    crossOffset?: number | undefined;
+    /**
+     * Try other sides when the panel doesn't fit on `side`. `true` (default)
+     * tries the opposite side, and for left / right then below and above; an
+     * array lists the fallbacks in order. When no side fits, the one with the
+     * most room wins.
+     */
+    flip?: boolean | readonly FloatingSide[] | undefined;
+    /** On the top / bottom sides, swap to the alignment that overflows least
+     *  when the requested one runs past the viewport. Default false. */
+    flipAlign?: boolean | undefined;
+    /**
+     * Shift the panel back inside the boundary: `true` (default) along the
+     * anchor edge only, `'both'` also on the main axis (a panel taller than the
+     * room left may then cover its anchor, as a context menu does), `false` never.
+     */
+    shift?: boolean | 'both' | undefined;
+    /** Distance kept from the boundary edges (px). Default 8. */
+    padding?: number | undefined;
+    /** Right-to-left: swaps `start` / `end` on the top / bottom sides. */
+    rtl?: boolean | undefined;
+    /**
+     * With `start` / `end` alignment, line this point of the panel (px in from
+     * its aligned edge) up with the anchor's centre instead of aligning the
+     * edges, e.g. the tip of a tooltip tail.
+     */
+    anchorPoint?: number | undefined;
+    /** Keep the arrow centre at least this far from the panel's ends (px).
+     *  When set, the layout reports where the arrow points at the anchor. */
+    arrowInset?: number | undefined;
+}
+export interface FloatingLayout {
+    /** Panel top-left, viewport coordinates. */
+    x: number;
+    y: number;
+    /** Resolved side and alignment (after flip / flipAlign). */
+    side: FloatingSide;
+    align: FloatingAlign;
+    /** The side differs from the requested one. */
+    flipped: boolean;
+    /** The shift moved the panel along the anchor edge. */
+    shifted: boolean;
+    /** Arrow centre from the panel's left (top / bottom) or top (left / right)
+     *  edge, pointing at the anchor centre; null without `arrowInset`. */
+    arrow: number | null;
+}
+/** Pure placement maths. All rects are viewport coordinates. */
+export declare function computeFloatingLayout(anchor: FloatingRect, floating: {
+    width: number;
+    height: number;
+}, boundary: FloatingRect, options?: FloatingLayoutOptions): FloatingLayout;
+/** A point or box to anchor to that isn't an element (a context-menu click). */
+export interface VirtualAnchor {
+    getBoundingClientRect(): FloatingRect;
+    /** Element whose direction and scroll parents apply. */
+    contextElement?: Element | null;
+}
+export type FloatingAnchor = Element | VirtualAnchor;
+/** A side, or one named by the reading direction: `inline-end` is the right
+ *  side in LTR and the left side in RTL (a submenu next to its menu). */
+export type FloatingLogicalSide = FloatingSide | 'inline-start' | 'inline-end';
+export interface PlaceFloatingOptions extends Omit<FloatingLayoutOptions, 'side' | 'flip'> {
+    side?: FloatingLogicalSide | undefined;
+    flip?: boolean | readonly FloatingLogicalSide[] | undefined;
+    /** What the panel must stay inside: the viewport (default), or the part of
+     *  it the anchor's clipping (scroll / overflow) ancestors leave visible. */
+    boundary?: 'viewport' | 'clippingAncestors' | undefined;
+}
+/** Ancestors that clip their content (overflow other than visible). */
+export declare function getClippingAncestors(el: Element | null): Element[];
+/**
+ * Measures the anchor and the panel and moves the panel: inline `left` / `top`,
+ * `--ods-anchor-width` (the anchor's width, for panels as wide as their
+ * trigger) and `data-side` for CSS that follows a flip (transform origins,
+ * enter direction). The panel's sizes are its layout sizes (offsetWidth /
+ * offsetHeight), so an entrance scale animation doesn't skew them.
+ */
+export declare function placeFloating(anchor: FloatingAnchor, floating: HTMLElement, options?: PlaceFloatingOptions): FloatingLayout;
+/**
+ * Re-places every open floating panel now. For an anchor that moved without
+ * a scroll, resize or size change (e.g. an OnboardingTour spotlight box that
+ * follows its target), which `autoUpdate` cannot see on its own.
+ */
+export declare function requestFloatingUpdate(): void;
+/**
+ * Calls `update` now and whenever the layout may have moved the anchor or
+ * resized either element: any scroll (captured, so every scroll parent
+ * counts), window resize, element resize, the web fonts loading and
+ * `requestFloatingUpdate()`. Returns the cleanup.
+ */
+export declare function autoUpdate(anchor: FloatingAnchor, floating: HTMLElement, update: () => void): () => void;
+/** True when the element is shown in the top layer. */
+export declare function isInTopLayer(el: Element): boolean;
+/**
+ * Promotes the panel to the top layer (`popover="manual"`: no light dismiss of
+ * its own; `useDismiss` handles that). Returns false where the Popover API is
+ * missing; the panel then stays `position: fixed` on the z-index scale.
+ */
+export declare function showInTopLayer(el: HTMLElement): boolean;
+/** Takes the panel out of the top layer again (a panel that stays mounted while closed). */
+export declare function hideFromTopLayer(el: HTMLElement): void;

package/dist/floating.d.ts

@@ -0,0 +1,138 @@
+/**
+ * Positioning for floating surfaces (menus, listboxes, popovers, tooltips):
+ * one engine for every component, framework-free. The React hook and the Vue
+ * composable (`internal/useFloating`) wrap it.
+ *
+ * The panel is promoted to the browser's top layer (`popover="manual"`), so no
+ * `overflow: hidden`, transformed or lower-stacked ancestor can clip or cover
+ * it, and it is placed with `position: fixed` viewport coordinates. It stays a
+ * DOM child of its component, which keeps Tab order, inherited styles (theme,
+ * `dir`, custom properties), event bubbling and light-dismiss containment
+ * exactly as they were inline. Without the Popover API it falls back to
+ * `position: fixed` on the `--orvain-z-index-*` scale.
+ *
+ * `computeFloatingLayout` is the pure geometry (placement, offset, flip,
+ * shift, arrow, RTL); `placeFloating` measures the DOM and applies it;
+ * `autoUpdate` re-places on scroll (any scroll parent), resize and size changes.
+ */
+export type FloatingSide = 'top' | 'right' | 'bottom' | 'left';
+/** Logical alignment along the anchor edge: `start` is the left edge in LTR
+ *  and the right edge in RTL on the top / bottom sides; the top edge on the
+ *  left / right sides. */
+export type FloatingAlign = 'start' | 'center' | 'end';
+export interface FloatingRect {
+    left: number;
+    top: number;
+    width: number;
+    height: number;
+}
+export interface FloatingLayoutOptions {
+    /** Side of the anchor the panel opens on. Default `bottom`. */
+    side?: FloatingSide | undefined;
+    /** Edge of the anchor the panel lines up with. Default `start`. */
+    align?: FloatingAlign | undefined;
+    /** Gap between the anchor and the panel (px). Default 0. */
+    offset?: number | undefined;
+    /** Extra move along the anchor edge (px, towards the right / bottom). Default 0. */
+    crossOffset?: number | undefined;
+    /**
+     * Try other sides when the panel doesn't fit on `side`. `true` (default)
+     * tries the opposite side, and for left / right then below and above; an
+     * array lists the fallbacks in order. When no side fits, the one with the
+     * most room wins.
+     */
+    flip?: boolean | readonly FloatingSide[] | undefined;
+    /** On the top / bottom sides, swap to the alignment that overflows least
+     *  when the requested one runs past the viewport. Default false. */
+    flipAlign?: boolean | undefined;
+    /**
+     * Shift the panel back inside the boundary: `true` (default) along the
+     * anchor edge only, `'both'` also on the main axis (a panel taller than the
+     * room left may then cover its anchor, as a context menu does), `false` never.
+     */
+    shift?: boolean | 'both' | undefined;
+    /** Distance kept from the boundary edges (px). Default 8. */
+    padding?: number | undefined;
+    /** Right-to-left: swaps `start` / `end` on the top / bottom sides. */
+    rtl?: boolean | undefined;
+    /**
+     * With `start` / `end` alignment, line this point of the panel (px in from
+     * its aligned edge) up with the anchor's centre instead of aligning the
+     * edges, e.g. the tip of a tooltip tail.
+     */
+    anchorPoint?: number | undefined;
+    /** Keep the arrow centre at least this far from the panel's ends (px).
+     *  When set, the layout reports where the arrow points at the anchor. */
+    arrowInset?: number | undefined;
+}
+export interface FloatingLayout {
+    /** Panel top-left, viewport coordinates. */
+    x: number;
+    y: number;
+    /** Resolved side and alignment (after flip / flipAlign). */
+    side: FloatingSide;
+    align: FloatingAlign;
+    /** The side differs from the requested one. */
+    flipped: boolean;
+    /** The shift moved the panel along the anchor edge. */
+    shifted: boolean;
+    /** Arrow centre from the panel's left (top / bottom) or top (left / right)
+     *  edge, pointing at the anchor centre; null without `arrowInset`. */
+    arrow: number | null;
+}
+/** Pure placement maths. All rects are viewport coordinates. */
+export declare function computeFloatingLayout(anchor: FloatingRect, floating: {
+    width: number;
+    height: number;
+}, boundary: FloatingRect, options?: FloatingLayoutOptions): FloatingLayout;
+/** A point or box to anchor to that isn't an element (a context-menu click). */
+export interface VirtualAnchor {
+    getBoundingClientRect(): FloatingRect;
+    /** Element whose direction and scroll parents apply. */
+    contextElement?: Element | null;
+}
+export type FloatingAnchor = Element | VirtualAnchor;
+/** A side, or one named by the reading direction: `inline-end` is the right
+ *  side in LTR and the left side in RTL (a submenu next to its menu). */
+export type FloatingLogicalSide = FloatingSide | 'inline-start' | 'inline-end';
+export interface PlaceFloatingOptions extends Omit<FloatingLayoutOptions, 'side' | 'flip'> {
+    side?: FloatingLogicalSide | undefined;
+    flip?: boolean | readonly FloatingLogicalSide[] | undefined;
+    /** What the panel must stay inside: the viewport (default), or the part of
+     *  it the anchor's clipping (scroll / overflow) ancestors leave visible. */
+    boundary?: 'viewport' | 'clippingAncestors' | undefined;
+}
+/** Ancestors that clip their content (overflow other than visible). */
+export declare function getClippingAncestors(el: Element | null): Element[];
+/**
+ * Measures the anchor and the panel and moves the panel: inline `left` / `top`,
+ * `--ods-anchor-width` (the anchor's width, for panels as wide as their
+ * trigger) and `data-side` for CSS that follows a flip (transform origins,
+ * enter direction). The panel's sizes are its layout sizes (offsetWidth /
+ * offsetHeight), so an entrance scale animation doesn't skew them.
+ */
+export declare function placeFloating(anchor: FloatingAnchor, floating: HTMLElement, options?: PlaceFloatingOptions): FloatingLayout;
+/**
+ * Re-places every open floating panel now. For an anchor that moved without
+ * a scroll, resize or size change (e.g. an OnboardingTour spotlight box that
+ * follows its target), which `autoUpdate` cannot see on its own.
+ */
+export declare function requestFloatingUpdate(): void;
+/**
+ * Calls `update` now and whenever the layout may have moved the anchor or
+ * resized either element: any scroll (captured, so every scroll parent
+ * counts), window resize, element resize, the web fonts loading and
+ * `requestFloatingUpdate()`. Returns the cleanup.
+ */
+export declare function autoUpdate(anchor: FloatingAnchor, floating: HTMLElement, update: () => void): () => void;
+/** True when the element is shown in the top layer. */
+export declare function isInTopLayer(el: Element): boolean;
+/**
+ * Promotes the panel to the top layer (`popover="manual"`: no light dismiss of
+ * its own; `useDismiss` handles that). Returns false where the Popover API is
+ * missing; the panel then stays `position: fixed` on the z-index scale.
+ */
+export declare function showInTopLayer(el: HTMLElement): boolean;
+/** Takes the panel out of the top layer again (a panel that stays mounted while closed). */
+export declare function hideFromTopLayer(el: HTMLElement): void;
+//# sourceMappingURL=floating.d.ts.map

package/dist/formField.d.cts

@@ -0,0 +1,58 @@
+/**
+ * Native-form plumbing shared by the picker fields (Select, Combobox, TagInput,
+ * OtpInput, DatePickerInput…), whose value lives in component state rather
+ * than in a native control.
+ */
+/**
+ * True when a `focusout` on `root` moves focus outside it (or nowhere), i.e.
+ * the whole widget lost focus. Moving between the widget's own parts (input →
+ * chevron, cell → cell, field → its popover) returns false.
+ */
+export declare function focusLeftWidget(event: Pick<FocusEvent, 'relatedTarget'>, root: Element): boolean;
+/**
+ * Reports focus leaving a whole widget, once per visit, with the `FocusEvent`
+ * that took it away. Three ways focus leaves without a plain focusout to an
+ * outside element are covered:
+ *  - a press on a non-focusable part (an option row, a cell's padding) first
+ *    blurs to nowhere, then the widget refocuses its control in the click
+ *    handler: a focusout to nowhere is checked once the press is over;
+ *  - focus to nowhere for other reasons (window switch): checked on the next
+ *    task, and only reported if focus is really gone from the widget;
+ *  - the focused part is removed (a popover closing on an outside press):
+ *    browsers fire no focusout then, so while the widget has focus a
+ *    document-level focusin / pointerdown outside it reports the leave.
+ *
+ * Bind `focusIn`, `focusOut` and `pointerDown` (capture) on the root and call
+ * `dispose` on unmount.
+ */
+export declare function createFocusOut(onLeave: (event: FocusEvent) => void): {
+    focusIn(el: Element): void;
+    focusOut(event: FocusEvent, el: Element): void;
+    pointerDown(el: Element): void;
+    dispose(): void;
+};
+/**
+ * The form a widget belongs to: the one its `form` attribute names, else its
+ * nearest ancestor `<form>`, as for a native control.
+ */
+export declare function ownerForm(el: Element, formId?: string | null): HTMLFormElement | null;
+/**
+ * Listens for `reset` on the widget's form, so `form.reset()` can return an
+ * uncontrolled picker to its default value like a native input. Returns the
+ * cleanup.
+ */
+export declare function onFormReset(el: Element, formId: string | null | undefined, handler: () => void): () => void;
+/**
+ * The strings a picker submits: a single value always submits (an empty
+ * string when nothing is picked, as a native `<input>` does); a list submits
+ * one entry per item and nothing when empty, as `<select multiple>` does.
+ */
+export declare function formEntries(value: string | readonly string[] | null | undefined): string[];
+/** Whether a picker value counts as filled for `required`. */
+export declare function formValueFilled(value: string | readonly string[] | null | undefined): boolean;
+/** A date as the `yyyy-mm-dd` string an `<input type="date">` submits (local calendar day). */
+export declare function toISODate(date: Date | null | undefined): string;
+/** A time as the 24-hour `HH:mm` / `HH:mm:ss` string an `<input type="time">` submits. */
+export declare function toISOTime(hours: number, minutes: number, seconds?: number): string;
+/** Same items in the same order (a reset that changes nothing reports nothing). */
+export declare function sameList<T>(a: readonly T[], b: readonly T[]): boolean;

package/dist/formField.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Native-form plumbing shared by the picker fields (Select, Combobox, TagInput,
+ * OtpInput, DatePickerInput…), whose value lives in component state rather
+ * than in a native control.
+ */
+/**
+ * True when a `focusout` on `root` moves focus outside it (or nowhere), i.e.
+ * the whole widget lost focus. Moving between the widget's own parts (input →
+ * chevron, cell → cell, field → its popover) returns false.
+ */
+export declare function focusLeftWidget(event: Pick<FocusEvent, 'relatedTarget'>, root: Element): boolean;
+/**
+ * Reports focus leaving a whole widget, once per visit, with the `FocusEvent`
+ * that took it away. Three ways focus leaves without a plain focusout to an
+ * outside element are covered:
+ *  - a press on a non-focusable part (an option row, a cell's padding) first
+ *    blurs to nowhere, then the widget refocuses its control in the click
+ *    handler: a focusout to nowhere is checked once the press is over;
+ *  - focus to nowhere for other reasons (window switch): checked on the next
+ *    task, and only reported if focus is really gone from the widget;
+ *  - the focused part is removed (a popover closing on an outside press):
+ *    browsers fire no focusout then, so while the widget has focus a
+ *    document-level focusin / pointerdown outside it reports the leave.
+ *
+ * Bind `focusIn`, `focusOut` and `pointerDown` (capture) on the root and call
+ * `dispose` on unmount.
+ */
+export declare function createFocusOut(onLeave: (event: FocusEvent) => void): {
+    focusIn(el: Element): void;
+    focusOut(event: FocusEvent, el: Element): void;
+    pointerDown(el: Element): void;
+    dispose(): void;
+};
+/**
+ * The form a widget belongs to: the one its `form` attribute names, else its
+ * nearest ancestor `<form>`, as for a native control.
+ */
+export declare function ownerForm(el: Element, formId?: string | null): HTMLFormElement | null;
+/**
+ * Listens for `reset` on the widget's form, so `form.reset()` can return an
+ * uncontrolled picker to its default value like a native input. Returns the
+ * cleanup.
+ */
+export declare function onFormReset(el: Element, formId: string | null | undefined, handler: () => void): () => void;
+/**
+ * The strings a picker submits: a single value always submits (an empty
+ * string when nothing is picked, as a native `<input>` does); a list submits
+ * one entry per item and nothing when empty, as `<select multiple>` does.
+ */
+export declare function formEntries(value: string | readonly string[] | null | undefined): string[];
+/** Whether a picker value counts as filled for `required`. */
+export declare function formValueFilled(value: string | readonly string[] | null | undefined): boolean;
+/** A date as the `yyyy-mm-dd` string an `<input type="date">` submits (local calendar day). */
+export declare function toISODate(date: Date | null | undefined): string;
+/** A time as the 24-hour `HH:mm` / `HH:mm:ss` string an `<input type="time">` submits. */
+export declare function toISOTime(hours: number, minutes: number, seconds?: number): string;
+/** Same items in the same order (a reset that changes nothing reports nothing). */
+export declare function sameList<T>(a: readonly T[], b: readonly T[]): boolean;
+//# sourceMappingURL=formField.d.ts.map

package/dist/helpers.d.cts

@@ -0,0 +1,17 @@
+/**
+ * Merges class strings, filtering out falsy values.
+ * Thin wrapper kept here so consumers don't need to import clsx separately.
+ */
+export declare function cx(...classes: (string | undefined | null | false)[]): string;
+/**
+ * Type-safe Object.entries with inferred key types.
+ */
+export declare function typedEntries<T extends object>(obj: T): [keyof T, T[keyof T]][];
+/**
+ * Omits specified keys from an object (useful for prop forwarding).
+ */
+export declare function omit<T extends object, K extends keyof T>(obj: T, keys: K[]): Omit<T, K>;
+/**
+ * Clamps a number between min and max (inclusive).
+ */
+export declare function clamp(value: number, min: number, max: number): number;

package/dist/helpers.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Merges class strings, filtering out falsy values.
+ * Thin wrapper kept here so consumers don't need to import clsx separately.
+ */
+export declare function cx(...classes: (string | undefined | null | false)[]): string;
+/**
+ * Type-safe Object.entries with inferred key types.
+ */
+export declare function typedEntries<T extends object>(obj: T): [keyof T, T[keyof T]][];
+/**
+ * Omits specified keys from an object (useful for prop forwarding).
+ */
+export declare function omit<T extends object, K extends keyof T>(obj: T, keys: K[]): Omit<T, K>;
+/**
+ * Clamps a number between min and max (inclusive).
+ */
+export declare function clamp(value: number, min: number, max: number): number;
+//# sourceMappingURL=helpers.d.ts.map