@skdx/react 0.26.0

package/dist/tree-select/types.d.ts

@@ -0,0 +1,360 @@
+import type * as React from 'react';
+import type { TreeCheckedState } from '../tree/types.js';
+import type { PopperContentProps } from '../utils/popper.js';
+import type { PortalProps } from '../utils/portal.js';
+import type { PrimitivePropsWithRef } from '../utils/primitive.js';
+import type { InteractOutsideEvent } from '../utils/useDismiss.js';
+import type { TreeSelectFlatNode, TreeSelectIndex } from './collection.js';
+/**
+ * One node of a {@link TreeSelect}'s `collection`. Plain data, not elements:
+ * cascading check state, `valueStrategy` projection, and filtering all need to
+ * see branches that are collapsed (and therefore unmounted), which a
+ * children-based tree cannot offer.
+ */
+export interface TreeSelectNode {
+    /** Unique identifier across the whole collection — what lands in `value`, and what every callback names. */
+    value: string;
+    /**
+     * Human-readable text: rendered as the node's content, matched by `filter`, and shown by `TreeSelectValue`.
+     * @default undefined — falls back to `value`.
+     */
+    label?: string;
+    /**
+     * Excludes this node from checking, cascade propagation, keyboard
+     * navigation, and its parent's checked-ness calculation. Inherited by the
+     * whole subtree — a disabled branch cannot be toggled through its children.
+     * @default false
+     */
+    disabled?: boolean;
+    /**
+     * Child nodes. A node with an empty (or absent) `children` is a leaf: it is
+     * not expandable and reports no `aria-expanded`.
+     * @default undefined — a leaf.
+     */
+    children?: TreeSelectNode[];
+}
+/**
+ * Whether checking a node propagates through its subtree. `'cascade'` makes
+ * the tree a tri-state checkbox tree: checking a parent checks every enabled
+ * descendant, and a partially-checked parent reports `aria-checked="mixed"`.
+ * `'independent'` disables propagation entirely — each node stands alone.
+ *
+ * Only meaningful while `multiple` is set; a single-select tree has one
+ * checked node by definition and never cascades.
+ */
+export type TreeSelectCheckStrategy = 'cascade' | 'independent';
+/**
+ * Which of the checked nodes are actually emitted in `value`.
+ *
+ * - `'all'` — every checked node, parents and descendants alike.
+ * - `'leaf'` — only checked leaves; branches are dropped.
+ * - `'shallowest'` — only the topmost fully-checked node of each branch,
+ *   collapsing a fully-checked subtree to the single node that implies it.
+ *
+ * Ignored (treated as `'all'`) under `checkStrategy="independent"`, where no
+ * node implies any other and dropping one would silently lose a selection.
+ */
+export type TreeSelectValueStrategy = 'all' | 'leaf' | 'shallowest';
+/** Predicate deciding whether a node matches the current filter text. */
+export type TreeSelectFilter = (node: TreeSelectNode, inputValue: string) => boolean;
+/** @internal Shared state distributed from {@link TreeSelect} to its parts via context. Not part of the public API. */
+export interface TreeSelectContextValue {
+    collection: readonly TreeSelectNode[];
+    index: TreeSelectIndex;
+    /** Every node value in collection pre-order. */
+    order: readonly string[];
+    /** The emitted value: the checked set projected through `valueStrategy`. */
+    value: readonly string[];
+    multiple: boolean;
+    /** Whether checking actually propagates: `checkStrategy === 'cascade'` *and* `multiple`. */
+    cascade: boolean;
+    disabled: boolean;
+    readOnly: boolean;
+    /** A node's tri-state value, derived from its enabled leaf descendants under `cascade`. */
+    checkStateOf: (value: string) => TreeCheckedState;
+    /** Toggles a node (respecting `checkStrategy`), emits the projected value, and closes when `closeOnSelect`. */
+    commit: (value: string) => void;
+    open: boolean;
+    onOpenChange: (open: boolean) => void;
+    /** Effective expanded ids — the caller's expansion plus, while filtering, the ancestors of every match. */
+    expandedIds: string[];
+    expanded: ReadonlySet<string>;
+    setExpanded: (value: string, expand: boolean) => void;
+    /** Adapter turning the composed `Tree`'s whole-array expansion callback back into a single-node change. */
+    onTreeExpandedIdsChange: (ids: string[]) => void;
+    /** Values whose check state is fully `true`, handed to the composed `Tree` as its `selectedIds`. */
+    selectedIds: string[];
+    /** Whether a node survives the current filter (always `true` when not filtering). */
+    isVisible: (value: string) => boolean;
+    /** Visible, expanded nodes in navigation order. */
+    flat: readonly TreeSelectFlatNode[];
+    flatMap: ReadonlyMap<string, TreeSelectFlatNode>;
+    activeValue: string | null;
+    setActiveValue: (value: string | null) => void;
+    /** DOM id of a node's `treeitem`, for `aria-activedescendant`. */
+    itemId: (value: string) => string;
+    treeId: string;
+    contentId: string;
+    triggerRef: React.RefObject<HTMLButtonElement | null>;
+    contentRef: React.RefObject<HTMLDivElement | null>;
+    inputRef: React.RefObject<HTMLInputElement | null>;
+    /** Whether a `TreeSelectInput` is mounted — it takes DOM focus, and with it `aria-activedescendant`, off the trigger. */
+    hasInput: boolean;
+    setHasInput: (hasInput: boolean) => void;
+    inputValue: string;
+    onInputValueChange: (value: string) => void;
+    /** A node's `label`, or its `value` when it has none. */
+    getLabel: (value: string) => string;
+    /** The shared keydown handler both `TreeSelectTrigger` and `TreeSelectInput` delegate to. */
+    onNavigationKeyDown: (event: React.KeyboardEvent<HTMLElement>, options: {
+        typeahead: boolean;
+        selectOnSpace: boolean;
+    }) => void;
+}
+/** @internal Per-node state distributed from {@link TreeSelectItem} to `TreeSelectItemIndicator` via context. Not part of the public API. */
+export interface TreeSelectItemContextValue {
+    value: string;
+    checkState: TreeCheckedState;
+    disabled: boolean;
+    expanded: boolean;
+    hasChildren: boolean;
+    /** Whether this node is the virtually-focused one named by `aria-activedescendant`. */
+    active: boolean;
+}
+/** Props for the {@link TreeSelect} root. */
+export interface TreeSelectProps {
+    /**
+     * The `TreeSelectTrigger`/`TreeSelectPortal` parts, rendered as children — `TreeSelect` itself renders no DOM.
+     * @default undefined — renders nothing without children.
+     */
+    children?: React.ReactNode;
+    /**
+     * The hierarchical data the popup's tree is built from. Node `value`s must be
+     * unique across the whole collection — every callback, `value` entry and DOM
+     * id is keyed by them.
+     */
+    collection: readonly TreeSelectNode[];
+    /**
+     * Checked node values, for controlled usage — always an array, whether or not
+     * `multiple`, and always in the shape `valueStrategy` describes. Pair with
+     * `onValueChange`.
+     * @default undefined — uncontrolled, tracks its own checked set internally.
+     */
+    value?: string[];
+    /**
+     * Initially checked node values, for uncontrolled usage. Same shape as `value`.
+     * @default [] — nothing checked.
+     */
+    defaultValue?: string[];
+    /**
+     * Fires with the whole new value whenever the checked set changes, controlled
+     * or not — projected through `valueStrategy`, not the node that was toggled.
+     * @default undefined — no-op if omitted.
+     */
+    onValueChange?: (value: string[]) => void;
+    /**
+     * Allows more than one node to be checked: the tree gets
+     * `aria-multiselectable`, activating a node toggles it rather than replacing
+     * the selection, and `checkStrategy` starts to mean something.
+     * @default false
+     */
+    multiple?: boolean;
+    /**
+     * Whether checking a node propagates through its subtree — see
+     * {@link TreeSelectCheckStrategy}. Ignored unless `multiple`.
+     * @default 'cascade' — checking a parent checks its whole enabled subtree, and a partially-checked parent reports `aria-checked="mixed"`.
+     */
+    checkStrategy?: TreeSelectCheckStrategy;
+    /**
+     * Which checked nodes appear in the emitted `value` — see
+     * {@link TreeSelectValueStrategy}. Ignored under
+     * `checkStrategy="independent"`.
+     * @default 'all' — every checked node, which is the most faithful round-trip but the most verbose payload; `'shallowest'` is usually what an API wants.
+     */
+    valueStrategy?: TreeSelectValueStrategy;
+    /**
+     * Expanded node values, for controlled usage. Pair with `onExpandedChange`.
+     * While filtering, the ancestors of every match are expanded *on top of* this
+     * value without being written back to it.
+     * @default undefined — uncontrolled, tracks its own expanded set internally.
+     */
+    expandedValue?: string[];
+    /**
+     * Initially expanded node values, for uncontrolled usage.
+     * @default [] — every branch collapsed.
+     */
+    defaultExpandedValue?: string[];
+    /**
+     * Fires with the new expanded set whenever a branch is expanded or collapsed,
+     * controlled or not. Never fires for the transient expansion filtering adds.
+     * @default undefined — no-op if omitted.
+     */
+    onExpandedChange?: (expandedValue: string[]) => void;
+    /**
+     * Whether the popup is open, for controlled usage. Pair with `onOpenChange`.
+     * @default undefined — uncontrolled, tracks its own open state internally.
+     */
+    open?: boolean;
+    /**
+     * Initial open state, for uncontrolled usage.
+     * @default false
+     */
+    defaultOpen?: boolean;
+    /**
+     * Fires with the new open state whenever it changes, controlled or not.
+     * @default undefined — no-op if omitted.
+     */
+    onOpenChange?: (open: boolean) => void;
+    /**
+     * Fires with the new open state once the change has finished on screen —
+     * after `TreeSelectContent`'s enter or exit animation ends, or as soon as it
+     * has settled when the popup declares no animation. Use it for work that must
+     * not race the transition; use `onOpenChange` for work that must not wait for it.
+     * @default undefined — no-op if omitted.
+     */
+    onOpenChangeComplete?: (open: boolean) => void;
+    /**
+     * The `TreeSelectInput`'s filter text, for controlled usage. Pair with `onInputValueChange`.
+     * @default undefined — uncontrolled, tracks its own filter text internally.
+     */
+    inputValue?: string;
+    /**
+     * Initial filter text, for uncontrolled usage.
+     * @default '' — unfiltered.
+     */
+    defaultInputValue?: string;
+    /**
+     * Fires with the new filter text as the user types, controlled or not.
+     * @default undefined — no-op if omitted.
+     */
+    onInputValueChange?: (inputValue: string) => void;
+    /**
+     * Decides whether a node matches the filter text. A match keeps its whole
+     * ancestor chain visible (a matched leaf under a hidden parent would be
+     * unreachable) and its whole subtree visible.
+     * @default defaultTreeSelectFilter — case-insensitive substring match on `label ?? value`.
+     */
+    filter?: TreeSelectFilter;
+    /**
+     * Blocks the whole control: the trigger is a disabled `<button>`, the popup
+     * cannot open, and no key changes anything.
+     * @default false
+     */
+    disabled?: boolean;
+    /**
+     * Lets the user open, navigate and read the tree but never change the value —
+     * unlike `disabled`, which also removes it from the tab order.
+     * @default false
+     */
+    readOnly?: boolean;
+    /**
+     * Closes the popup as soon as a node is checked, returning focus to the trigger.
+     * @default !multiple — a single-select answer is complete on the first pick; a multi-select one is not.
+     */
+    closeOnSelect?: boolean;
+    /**
+     * Formats the message announced (through the shared `LiveAnnouncer`) each
+     * time the number of filter matches changes while the popup is open —
+     * filtering is silent for screen-reader users otherwise. Return an empty
+     * string to announce nothing.
+     * @default defaultGetMatchCountLabel — e.g. `"3 matches available"`
+     */
+    getMatchCountLabel?: (count: number) => string;
+}
+/** Props for {@link TreeSelectTrigger}, the `role="combobox"` button that opens the popup. */
+export interface TreeSelectTriggerProps extends PrimitivePropsWithRef<'button'> {
+}
+/** Props for {@link TreeSelectValue}, the trigger's read-out of the current selection. */
+export interface TreeSelectValueProps extends PrimitivePropsWithRef<'span'> {
+    /**
+     * Stand-in content rendered while nothing at all is checked.
+     * @default undefined — renders nothing when empty.
+     */
+    placeholder?: React.ReactNode;
+}
+/** Props for {@link TreeSelectPortal}, which teleports the popup to `document.body` while open. */
+export interface TreeSelectPortalProps extends PortalProps {
+    /**
+     * Render (and mount `TreeSelectContent`) even while closed, instead of
+     * unmounting. Useful for animation libraries that need the outgoing content
+     * present in the DOM during an exit transition.
+     * @default false
+     */
+    forceMount?: boolean;
+}
+/**
+ * Props for {@link TreeSelectContent}, the popup panel. Extends
+ * {@link PopperContentProps} (`side`, `align`, `sideOffset`, `alignOffset`,
+ * `avoidCollisions`, `collisionPadding`) for floating-ui positioning relative
+ * to the trigger — note `TreeSelectContent` defaults `side` to `'bottom'`,
+ * `align` to `'start'`, and `sideOffset` to `4`, instead of the popper base
+ * defaults (`'bottom'` / `'center'` / `0`).
+ */
+export interface TreeSelectContentProps extends PopperContentProps {
+    /**
+     * Keep this popup mounted even while closed, instead of unmounting it.
+     * @default false
+     */
+    forceMount?: boolean;
+    /**
+     * Fires on Escape while the popup is open, before it closes. Call
+     * `event.preventDefault()` to keep it open.
+     * @default undefined — no-op if omitted.
+     */
+    onEscapeKeyDown?: (event: KeyboardEvent) => void;
+    /**
+     * Fires on a pointer-down outside the popup and trigger. `preventDefault()` keeps it open.
+     * @default undefined — no-op if omitted.
+     */
+    onPointerDownOutside?: (event: PointerEvent) => void;
+    /**
+     * Fires when focus moves outside the popup and trigger, carrying a
+     * cancelable stand-in for the uncancelable `focusin`. `preventDefault()`
+     * keeps it open.
+     * @default undefined — no-op if omitted.
+     */
+    onFocusOutside?: (event: CustomEvent<FocusEvent>) => void;
+    /**
+     * Fires for *either* kind of outside interaction, immediately before the
+     * specific handler and with the same event — so one `preventDefault()`
+     * vetoes both paths.
+     * @default undefined — no-op if omitted.
+     */
+    onInteractOutside?: (event: InteractOutsideEvent) => void;
+}
+/** Props for {@link TreeSelectTree}, the `role="tree"` inside the popup. */
+export interface TreeSelectTreeProps extends Omit<PrimitivePropsWithRef<'div'>, 'children' | 'defaultValue'> {
+    /**
+     * Renders a node's content — the label, and anything beside it such as a
+     * `TreeItemIndicator` chevron or a `TreeSelectItemIndicator` checkmark. The
+     * returned nodes render *inside* the node's `treeitem`, so both indicators
+     * find their context there.
+     * @default undefined — renders the node's `label ?? value` as plain text.
+     */
+    renderLabel?: (node: TreeSelectNode) => React.ReactNode;
+}
+/** Props for a single {@link TreeSelectItem} node. Normally rendered for you by `TreeSelectTree`. */
+export interface TreeSelectItemProps extends Omit<PrimitivePropsWithRef<'div'>, 'children'> {
+    /** The collection node this row stands for. */
+    node: TreeSelectNode;
+    /**
+     * The row's content — the label, plus any indicators.
+     * @default undefined — renders an empty row.
+     */
+    children?: React.ReactNode;
+}
+/** Props for {@link TreeSelectItemIndicator}, the checkmark shown on a checked (or partially checked) node. */
+export interface TreeSelectItemIndicatorProps extends PrimitivePropsWithRef<'span'> {
+    /**
+     * Render even while the node is unchecked, instead of returning `null` —
+     * for animating the check in and out, or for reserving its space.
+     * @default false
+     */
+    forceMount?: boolean;
+}
+/** Props for {@link TreeSelectEmpty}, shown in place of the tree when the filter matches nothing. */
+export interface TreeSelectEmptyProps extends PrimitivePropsWithRef<'div'> {
+}
+/** Props for {@link TreeSelectInput}, the optional filter text field inside the popup. */
+export interface TreeSelectInputProps extends Omit<PrimitivePropsWithRef<'input'>, 'value' | 'defaultValue'> {
+}

package/dist/utils/clamp.cjs

@@ -0,0 +1 @@
+"use strict";var t=Object.defineProperty;var a=Object.getOwnPropertyDescriptor;var b=Object.getOwnPropertyNames;var c=Object.prototype.hasOwnProperty;var h=(m,n)=>{for(var r in n)t(m,r,{get:n[r],enumerable:!0})},i=(m,n,r,u)=>{if(n&&typeof n=="object"||typeof n=="function")for(let e of b(n))!c.call(m,e)&&e!==r&&t(m,e,{get:()=>n[e],enumerable:!(u=a(n,e))||u.enumerable});return m};var o=m=>i(t({},"__esModule",{value:!0}),m);var x={};h(x,{clamp:()=>p});module.exports=o(x);function p(m,n,r){return Math.min(Math.max(m,n),r)}0&&(module.exports={clamp});

package/dist/utils/clamp.d.cts

@@ -0,0 +1 @@
+export declare function clamp(value: number, min: number, max: number): number;

package/dist/utils/clamp.d.ts

@@ -0,0 +1 @@
+export declare function clamp(value: number, min: number, max: number): number;

package/dist/utils/clamp.js

@@ -0,0 +1 @@
+function e(n,m,r){return Math.min(Math.max(n,m),r)}export{e as clamp};

package/dist/utils/color.cjs

@@ -0,0 +1 @@
+"use strict";var g=Object.defineProperty;var O=Object.getOwnPropertyDescriptor;var A=Object.getOwnPropertyNames;var E=Object.prototype.hasOwnProperty;var w=(n,r)=>{for(var t in r)g(n,t,{get:r[t],enumerable:!0})},z=(n,r,t,o)=>{if(r&&typeof r=="object"||typeof r=="function")for(let e of A(r))!E.call(n,e)&&e!==t&&g(n,e,{get:()=>r[e],enumerable:!(o=O(r,e))||o.enumerable});return n};var I=n=>z(g({},"__esModule",{value:!0}),n);var W={};w(W,{formatColor:()=>U,hexToRgb:()=>N,hsbToHsl:()=>y,hsbToRgb:()=>d,hslToHsb:()=>F,hslToRgb:()=>S,parseColor:()=>B,rgbToHex:()=>v,rgbToHsb:()=>C,rgbToHsl:()=>P});module.exports=I(W);var s=require("./clamp.cjs");function a(n,r=0){let t=10**r;return Math.round(n*t)/t}function i(n){return(n%360+360)%360}function m(n){return(0,s.clamp)(Math.round(n),0,255).toString(16).padStart(2,"0")}function R(n,r,t,o,e){if(!e)return 0;let u=o===n?(r-t)/e:o===r?(t-n)/e+2:(n-r)/e+4;return i(u*60)}function T(n,r,t,o,e){let u=Math.floor(i(n)/60)%6,l=[[r,t,0],[t,r,0],[0,r,t],[0,t,r],[t,0,r],[r,0,t]],[c,b,f]=l[u]??[0,0,0];return{r:a((c+o)*255),g:a((b+o)*255),b:a((f+o)*255),a:e}}function v(n,r=!1){let t=`#${m(n.r)}${m(n.g)}${m(n.b)}`;return r?`${t}${m((0,s.clamp)(n.a,0,1)*255)}`:t}var L=/^#?([\da-f]{3,8})$/i;function N(n){let r=L.exec(n.trim());if(!r)return null;let t=r[1];if((t.length===3||t.length===4)&&(t=t.split("").map(e=>e+e).join("")),t.length!==6&&t.length!==8)return null;let o=e=>parseInt(t.slice(e,e+2),16);return{r:o(0),g:o(2),b:o(4),a:t.length===8?a(o(6)/255,3):1}}function C(n){let r=(0,s.clamp)(n.r,0,255)/255,t=(0,s.clamp)(n.g,0,255)/255,o=(0,s.clamp)(n.b,0,255)/255,e=Math.max(r,t,o),u=e-Math.min(r,t,o);return{h:R(r,t,o,e,u),s:e?u/e*100:0,b:e*100,a:(0,s.clamp)(n.a,0,1)}}function d(n){let r=i(n.h),t=(0,s.clamp)(n.s,0,100)/100,o=(0,s.clamp)(n.b,0,100)/100,e=o*t,u=e*(1-Math.abs(r/60%2-1));return T(r,e,u,o-e,(0,s.clamp)(n.a,0,1))}function P(n){let r=(0,s.clamp)(n.r,0,255)/255,t=(0,s.clamp)(n.g,0,255)/255,o=(0,s.clamp)(n.b,0,255)/255,e=Math.max(r,t,o),u=Math.min(r,t,o),l=e-u,c=(e+u)/2,b=l?l/(1-Math.abs(2*c-1)):0;return{h:R(r,t,o,e,l),s:(0,s.clamp)(b*100,0,100),l:c*100,a:(0,s.clamp)(n.a,0,1)}}function S(n){let r=i(n.h),t=(0,s.clamp)(n.s,0,100)/100,o=(0,s.clamp)(n.l,0,100)/100,e=(1-Math.abs(2*o-1))*t,u=e*(1-Math.abs(r/60%2-1));return T(r,e,u,o-e/2,(0,s.clamp)(n.a,0,1))}function y(n){let r=(0,s.clamp)(n.s,0,100)/100,t=(0,s.clamp)(n.b,0,100)/100,o=t*(1-r/2),e=Math.min(o,1-o);return{h:i(n.h),s:e?(t-o)/e*100:0,l:o*100,a:(0,s.clamp)(n.a,0,1)}}function F(n){let r=(0,s.clamp)(n.s,0,100)/100,t=(0,s.clamp)(n.l,0,100)/100,o=t+r*Math.min(t,1-t);return{h:i(n.h),s:o?2*(1-t/o)*100:0,b:o*100,a:(0,s.clamp)(n.a,0,1)}}var _=/^(rgba?|hsla?|hsba?|hsva?)\(([^()]*)\)$/;function H(n){if(n===void 0)return null;let r=n.endsWith("%"),t=r?n.slice(0,-1):n.replace(/deg$/,"");if(t.trim()==="")return null;let o=Number(t);return Number.isFinite(o)?{value:o,percent:r}:null}function p(n){let r=H(n);return r&&(r.percent?r.value/100*255:r.value)}function $(n){let r=H(n);return r&&r.value}function j(n){if(n===void 0)return 1;let r=H(n);return r&&(r.percent?r.value/100:r.value)}function h(n){return{h:a(i(n.h),2),s:a((0,s.clamp)(n.s,0,100),2),b:a((0,s.clamp)(n.b,0,100),2),a:a((0,s.clamp)(n.a,0,1),3)}}function B(n){if(typeof n!="string")return null;let r=n.trim().toLowerCase();if(!r)return null;let t=_.exec(r);if(!t){let f=N(r);return f?h(C(f)):null}let o=t[1].replace(/a$/,""),e=t[2].replace(/\//g," ").split(/[\s,]+/).filter(Boolean);if(e.length!==3&&e.length!==4)return null;let u=j(e[3]);if(u===null)return null;if(o==="rgb"){let f=p(e[0]),x=p(e[1]),M=p(e[2]);return f===null||x===null||M===null?null:h(C({r:f,g:x,b:M,a:u}))}let l=$(e[0]),c=$(e[1]),b=$(e[2]);return l===null||c===null||b===null?null:h(o==="hsl"?F({h:l,s:c,l:b,a:u}):{h:l,s:c,b,a:u})}function U(n,r,t=!0){let o=a((0,s.clamp)(n.a,0,1),3),e=t&&o<1;if(r==="rgb"){let{r:u,g:l,b:c}=d(n);return e?`rgba(${u}, ${l}, ${c}, ${o})`:`rgb(${u}, ${l}, ${c})`}if(r==="hsl"){let u=y(n),l=a(u.h),c=a(u.s),b=a(u.l);return e?`hsla(${l}, ${c}%, ${b}%, ${o})`:`hsl(${l}, ${c}%, ${b}%)`}if(r==="hsb"){let u=a(i(n.h)),l=a((0,s.clamp)(n.s,0,100)),c=a((0,s.clamp)(n.b,0,100));return e?`hsba(${u}, ${l}%, ${c}%, ${o})`:`hsb(${u}, ${l}%, ${c}%)`}return v(d(n),e)}0&&(module.exports={formatColor,hexToRgb,hsbToHsl,hsbToRgb,hslToHsb,hslToRgb,parseColor,rgbToHex,rgbToHsb,rgbToHsl});

package/dist/utils/color.d.cts

@@ -0,0 +1,145 @@
+/**
+ * Colour maths for pickers, swatches and contrast checks — parsing, the four
+ * model conversions, and serialisation back to a string.
+ *
+ * Deliberately dependency-free and React-free: it is imported by
+ * `ColorPicker`, but nothing here knows what a component is, so it can be
+ * unit-tested as plain arithmetic and reused by a Node-side token pipeline.
+ *
+ * **HSB is the canonical model** for anything that stores a colour over time.
+ * RGB and hex cannot represent the hue of a black or a white — every fully
+ * dark colour is `#000000` regardless of which hue it came from — so a picker
+ * that round-trips through RGB on every drag loses the user's hue the moment
+ * they drag brightness to zero. Convert to RGB/hex at the edges, not in the
+ * middle.
+ */
+/** sRGB colour: `r`/`g`/`b` in `0–255`, `a` in `0–1`. */
+export interface RgbColor {
+    r: number;
+    g: number;
+    b: number;
+    a: number;
+}
+/** HSL colour: `h` in `0–360` degrees, `s`/`l` in `0–100` percent, `a` in `0–1`. */
+export interface HslColor {
+    h: number;
+    s: number;
+    l: number;
+    a: number;
+}
+/**
+ * HSB (a.k.a. HSV) colour: `h` in `0–360` degrees, `s` (saturation) and `b`
+ * (brightness) in `0–100` percent, `a` in `0–1`.
+ *
+ * Note `b` is **brightness**, not blue — the field names follow the model's
+ * own initials, the way `RgbColor.b` follows RGB's.
+ */
+export interface HsbColor {
+    h: number;
+    s: number;
+    b: number;
+    a: number;
+}
+/**
+ * Serialisation targets for {@link formatColor}. `'hsb'` is this library's own
+ * notation (`hsb(210, 60%, 85%)`) rather than a CSS colour — CSS has no HSB
+ * function — so it round-trips through {@link parseColor} but must not be
+ * dropped into a stylesheet.
+ */
+export type ColorFormat = 'hex' | 'rgb' | 'hsl' | 'hsb';
+/**
+ * Serialises an sRGB colour as `#rrggbb`, or `#rrggbbaa` when `includeAlpha`
+ * is set. Channels are clamped and rounded, so a computed colour with
+ * `r: 255.4` still produces valid hex rather than `#ff.6…`.
+ *
+ * @example
+ * ```ts
+ * rgbToHex({ r: 217, g: 76, b: 76, a: 0.5 });       // '#d94c4c'
+ * rgbToHex({ r: 217, g: 76, b: 76, a: 0.5 }, true); // '#d94c4c80'
+ * ```
+ */
+export declare function rgbToHex(rgb: RgbColor, includeAlpha?: boolean): string;
+/**
+ * Parses `#rgb`, `#rgba`, `#rrggbb` or `#rrggbbaa` (leading `#` optional,
+ * case-insensitive) into sRGB. Returns `null` for anything else — including
+ * 5- and 7-digit strings, which look like hex but are not a colour.
+ *
+ * @example
+ * ```ts
+ * hexToRgb('#f00');       // { r: 255, g: 0, b: 0, a: 1 }
+ * hexToRgb('#ff000080');  // { r: 255, g: 0, b: 0, a: 0.502 }
+ * hexToRgb('nope');       // null
+ * ```
+ */
+export declare function hexToRgb(hex: string): RgbColor | null;
+/**
+ * sRGB → HSB. A greyscale colour reports hue `0`, because it genuinely has
+ * none — see the module note on why that makes HSB, not RGB, the model to
+ * store.
+ */
+export declare function rgbToHsb(rgb: RgbColor): HsbColor;
+/** HSB → sRGB. */
+export declare function hsbToRgb(hsb: HsbColor): RgbColor;
+/** sRGB → HSL. */
+export declare function rgbToHsl(rgb: RgbColor): HslColor;
+/** HSL → sRGB. */
+export declare function hslToRgb(hsl: HslColor): RgbColor;
+/**
+ * HSB → HSL, computed directly rather than via RGB. The detour would quantise
+ * to 8 bits and flatten the hue of any near-black colour, which is exactly the
+ * loss this module exists to avoid.
+ */
+export declare function hsbToHsl(hsb: HsbColor): HslColor;
+/** HSL → HSB, the exact inverse of {@link hsbToHsl}, also without an RGB detour. */
+export declare function hslToHsb(hsl: HslColor): HsbColor;
+/**
+ * Parses a colour string into the canonical {@link HsbColor}, returning
+ * **`null` rather than throwing** for anything it does not understand — this
+ * is fed by user-typed text and by whatever a consumer passes as `value`, so
+ * "unparseable" is a normal outcome, not an exception.
+ *
+ * Tolerant about *formatting*, not about vocabulary. It accepts:
+ *
+ * - hex, with or without `#`, in 3/4/6/8 digits;
+ * - `rgb()` / `rgba()`, with numeric or `%` channels;
+ * - `hsl()` / `hsla()`, with or without the `%` on saturation/lightness and
+ *   with or without `deg` on the hue;
+ * - `hsb()` / `hsba()` / `hsv()` / `hsva()`, this library's own notation;
+ * - comma-separated *or* space-separated arguments, with the modern
+ *   `rgb(255 0 0 / 50%)` slash-alpha form.
+ *
+ * It does **not** know named colours (`red`, `transparent`), `color()`,
+ * `lab()`/`oklch()`, or `turn`/`rad` hue units. Those all return `null`; a
+ * 148-entry name table is a dependency's job, not a picker's.
+ *
+ * @example
+ * ```ts
+ * parseColor('#d94c4c');                 // { h: 0, s: 64.98, b: 85.1, a: 1 }
+ * parseColor('rgb(255 0 0 / 50%)');      // { h: 0, s: 100, b: 100, a: 0.5 }
+ * parseColor('hsl(210, 60%, 85%)');      // { h: 210, s: 19.15, b: 94, a: 1 }
+ * parseColor('rebeccapurple');           // null
+ * ```
+ */
+export declare function parseColor(input: string): HsbColor | null;
+/**
+ * Serialises the canonical {@link HsbColor} back to a string in `format`.
+ *
+ * Alpha appears **only when it is not 1** — `#ff0000` rather than `#ff0000ff`,
+ * `rgb(…)` rather than `rgba(…, 1)` — because that is what every consumer's
+ * stylesheet, design tool and clipboard expects, and appending a redundant
+ * `ff` to every hex is the fastest way to make a picker's output look wrong.
+ * Pass `alpha: false` to drop it unconditionally, for a picker that does not
+ * offer transparency at all.
+ *
+ * `parseColor(formatColor(c, f))` returns `c` to within the precision `f` can
+ * carry: exact for `'hsb'`, and 8-bit-quantised for `'hex'` and `'rgb'`.
+ *
+ * @example
+ * ```ts
+ * formatColor({ h: 0, s: 100, b: 100, a: 1 }, 'hex');          // '#ff0000'
+ * formatColor({ h: 0, s: 100, b: 100, a: 0.5 }, 'hex');        // '#ff000080'
+ * formatColor({ h: 0, s: 100, b: 100, a: 0.5 }, 'rgb');        // 'rgba(255, 0, 0, 0.5)'
+ * formatColor({ h: 0, s: 100, b: 100, a: 0.5 }, 'hex', false); // '#ff0000'
+ * ```
+ */
+export declare function formatColor(color: HsbColor, format: ColorFormat, alpha?: boolean): string;

package/dist/utils/color.d.ts

@@ -0,0 +1,145 @@
+/**
+ * Colour maths for pickers, swatches and contrast checks — parsing, the four
+ * model conversions, and serialisation back to a string.
+ *
+ * Deliberately dependency-free and React-free: it is imported by
+ * `ColorPicker`, but nothing here knows what a component is, so it can be
+ * unit-tested as plain arithmetic and reused by a Node-side token pipeline.
+ *
+ * **HSB is the canonical model** for anything that stores a colour over time.
+ * RGB and hex cannot represent the hue of a black or a white — every fully
+ * dark colour is `#000000` regardless of which hue it came from — so a picker
+ * that round-trips through RGB on every drag loses the user's hue the moment
+ * they drag brightness to zero. Convert to RGB/hex at the edges, not in the
+ * middle.
+ */
+/** sRGB colour: `r`/`g`/`b` in `0–255`, `a` in `0–1`. */
+export interface RgbColor {
+    r: number;
+    g: number;
+    b: number;
+    a: number;
+}
+/** HSL colour: `h` in `0–360` degrees, `s`/`l` in `0–100` percent, `a` in `0–1`. */
+export interface HslColor {
+    h: number;
+    s: number;
+    l: number;
+    a: number;
+}
+/**
+ * HSB (a.k.a. HSV) colour: `h` in `0–360` degrees, `s` (saturation) and `b`
+ * (brightness) in `0–100` percent, `a` in `0–1`.
+ *
+ * Note `b` is **brightness**, not blue — the field names follow the model's
+ * own initials, the way `RgbColor.b` follows RGB's.
+ */
+export interface HsbColor {
+    h: number;
+    s: number;
+    b: number;
+    a: number;
+}
+/**
+ * Serialisation targets for {@link formatColor}. `'hsb'` is this library's own
+ * notation (`hsb(210, 60%, 85%)`) rather than a CSS colour — CSS has no HSB
+ * function — so it round-trips through {@link parseColor} but must not be
+ * dropped into a stylesheet.
+ */
+export type ColorFormat = 'hex' | 'rgb' | 'hsl' | 'hsb';
+/**
+ * Serialises an sRGB colour as `#rrggbb`, or `#rrggbbaa` when `includeAlpha`
+ * is set. Channels are clamped and rounded, so a computed colour with
+ * `r: 255.4` still produces valid hex rather than `#ff.6…`.
+ *
+ * @example
+ * ```ts
+ * rgbToHex({ r: 217, g: 76, b: 76, a: 0.5 });       // '#d94c4c'
+ * rgbToHex({ r: 217, g: 76, b: 76, a: 0.5 }, true); // '#d94c4c80'
+ * ```
+ */
+export declare function rgbToHex(rgb: RgbColor, includeAlpha?: boolean): string;
+/**
+ * Parses `#rgb`, `#rgba`, `#rrggbb` or `#rrggbbaa` (leading `#` optional,
+ * case-insensitive) into sRGB. Returns `null` for anything else — including
+ * 5- and 7-digit strings, which look like hex but are not a colour.
+ *
+ * @example
+ * ```ts
+ * hexToRgb('#f00');       // { r: 255, g: 0, b: 0, a: 1 }
+ * hexToRgb('#ff000080');  // { r: 255, g: 0, b: 0, a: 0.502 }
+ * hexToRgb('nope');       // null
+ * ```
+ */
+export declare function hexToRgb(hex: string): RgbColor | null;
+/**
+ * sRGB → HSB. A greyscale colour reports hue `0`, because it genuinely has
+ * none — see the module note on why that makes HSB, not RGB, the model to
+ * store.
+ */
+export declare function rgbToHsb(rgb: RgbColor): HsbColor;
+/** HSB → sRGB. */
+export declare function hsbToRgb(hsb: HsbColor): RgbColor;
+/** sRGB → HSL. */
+export declare function rgbToHsl(rgb: RgbColor): HslColor;
+/** HSL → sRGB. */
+export declare function hslToRgb(hsl: HslColor): RgbColor;
+/**
+ * HSB → HSL, computed directly rather than via RGB. The detour would quantise
+ * to 8 bits and flatten the hue of any near-black colour, which is exactly the
+ * loss this module exists to avoid.
+ */
+export declare function hsbToHsl(hsb: HsbColor): HslColor;
+/** HSL → HSB, the exact inverse of {@link hsbToHsl}, also without an RGB detour. */
+export declare function hslToHsb(hsl: HslColor): HsbColor;
+/**
+ * Parses a colour string into the canonical {@link HsbColor}, returning
+ * **`null` rather than throwing** for anything it does not understand — this
+ * is fed by user-typed text and by whatever a consumer passes as `value`, so
+ * "unparseable" is a normal outcome, not an exception.
+ *
+ * Tolerant about *formatting*, not about vocabulary. It accepts:
+ *
+ * - hex, with or without `#`, in 3/4/6/8 digits;
+ * - `rgb()` / `rgba()`, with numeric or `%` channels;
+ * - `hsl()` / `hsla()`, with or without the `%` on saturation/lightness and
+ *   with or without `deg` on the hue;
+ * - `hsb()` / `hsba()` / `hsv()` / `hsva()`, this library's own notation;
+ * - comma-separated *or* space-separated arguments, with the modern
+ *   `rgb(255 0 0 / 50%)` slash-alpha form.
+ *
+ * It does **not** know named colours (`red`, `transparent`), `color()`,
+ * `lab()`/`oklch()`, or `turn`/`rad` hue units. Those all return `null`; a
+ * 148-entry name table is a dependency's job, not a picker's.
+ *
+ * @example
+ * ```ts
+ * parseColor('#d94c4c');                 // { h: 0, s: 64.98, b: 85.1, a: 1 }
+ * parseColor('rgb(255 0 0 / 50%)');      // { h: 0, s: 100, b: 100, a: 0.5 }
+ * parseColor('hsl(210, 60%, 85%)');      // { h: 210, s: 19.15, b: 94, a: 1 }
+ * parseColor('rebeccapurple');           // null
+ * ```
+ */
+export declare function parseColor(input: string): HsbColor | null;
+/**
+ * Serialises the canonical {@link HsbColor} back to a string in `format`.
+ *
+ * Alpha appears **only when it is not 1** — `#ff0000` rather than `#ff0000ff`,
+ * `rgb(…)` rather than `rgba(…, 1)` — because that is what every consumer's
+ * stylesheet, design tool and clipboard expects, and appending a redundant
+ * `ff` to every hex is the fastest way to make a picker's output look wrong.
+ * Pass `alpha: false` to drop it unconditionally, for a picker that does not
+ * offer transparency at all.
+ *
+ * `parseColor(formatColor(c, f))` returns `c` to within the precision `f` can
+ * carry: exact for `'hsb'`, and 8-bit-quantised for `'hex'` and `'rgb'`.
+ *
+ * @example
+ * ```ts
+ * formatColor({ h: 0, s: 100, b: 100, a: 1 }, 'hex');          // '#ff0000'
+ * formatColor({ h: 0, s: 100, b: 100, a: 0.5 }, 'hex');        // '#ff000080'
+ * formatColor({ h: 0, s: 100, b: 100, a: 0.5 }, 'rgb');        // 'rgba(255, 0, 0, 0.5)'
+ * formatColor({ h: 0, s: 100, b: 100, a: 0.5 }, 'hex', false); // '#ff0000'
+ * ```
+ */
+export declare function formatColor(color: HsbColor, format: ColorFormat, alpha?: boolean): string;