@skdx/docs-kit 0.35.0

package/dist/shared/contracts/types.d.ts

@@ -0,0 +1,230 @@
+/** Component contract mapping for all frameworks. */
+/** One prop a component accepts. */
+export type PropContract = FrameworkScopedContract & {
+    name: string;
+    type: string;
+    defaultValue?: string;
+    required: boolean;
+    description: string;
+};
+/** One event a component emits. */
+export type EventContract = FrameworkScopedContract & {
+    name: string;
+    description: string;
+    /** The payload as source text; `'void'` where the event carries nothing. */
+    detail: string;
+};
+/** One keyboard key and its binding behavior. */
+export interface KeyboardInteraction {
+    key: string;
+    behavior: string;
+}
+/** Accessibility guarantees for a component. */
+export interface AccessibilityContract {
+    role: string;
+    keyboard: readonly KeyboardInteraction[];
+    ariaAttributes: readonly string[];
+    focusManagement: string;
+    namingRequirement?: string;
+}
+/** One data attribute a component emits, with the same frameworks/frameworksReason opt-out props get. */
+export type DataAttributeContract = FrameworkScopedContract & {
+    name: DataAttr;
+    /** Which element carries the attribute and when, for the docs site to render beside the name. */
+    description?: string;
+};
+/** Styling hooks: parts, data-attributes, and custom properties. */
+export interface StylingHooksContract {
+    cssParts: readonly string[];
+    dataAttributes: readonly (DataAttr | DataAttributeContract)[];
+    cssCustomProperties: readonly CssVar[];
+    partsCaveat?: string;
+    stateAttribute?: string;
+}
+/** One skin-level appearance axis: a `data-*` attribute `@skdx/skins` styles, settable as the matching prop or written directly in markup. */
+export interface AppearanceAxisContract {
+    attribute: string;
+    values: readonly string[];
+    stylesheet: string;
+}
+/** One imperative method a component exposes on its element or instance (e.g. `focus`, `open`). */
+export type PublicMethodContract = FrameworkScopedContract & {
+    /** Method name. */
+    name: string;
+    /** Call signature as source text (parameters and return type). */
+    signature: string;
+    /** Human-readable explanation of what the method does. */
+    description: string;
+};
+/**
+ * The sanctioned accessor for one context-reached member, per framework;
+ * Web Components has no cross-shadow-root context mechanism, so it belongs
+ * in {@link ComponentContract.publicMethods} instead.
+ */
+export interface ContextApiAccessors {
+    react?: string;
+    vue?: string;
+    svelte?: string;
+    angular?: string;
+    webComponents?: string;
+}
+/** One of the five framework identifiers the parity tooling names. */
+export type FrameworkKey = keyof ContextApiAccessors;
+/** A `data-*` attribute name as written in markup. */
+export type DataAttr = `data-${string}`;
+/**
+ * Every state name a contract may list, spelled exactly as the `data-state`
+ * value a skin selector matches. Closed set so a second spelling of an
+ * existing state (`readOnly` beside `readonly`) fails to compile.
+ */
+export type ComponentState = 'active' | 'assertive' | 'checked' | 'closed' | 'collapsed' | 'complete' | 'completed' | 'copied' | 'current' | 'default' | 'delayed-open' | 'dirty' | 'disabled' | 'dragging' | 'edit' | 'empty' | 'error' | 'expanded' | 'filled' | 'focus' | 'focus-visible' | 'full-screen' | 'half' | 'hidden' | 'highlighted' | 'horizontal' | 'hover' | 'idle' | 'inactive' | 'incomplete' | 'indeterminate' | 'instant-open' | 'invalid' | 'loaded' | 'loading' | 'maximized' | 'minimized' | 'mixed' | 'multiple' | 'off' | 'on' | 'open' | 'optimum' | 'outside-month' | 'over-limit' | 'paused' | 'pending' | 'placeholder' | 'playing' | 'polite' | 'poor' | 'preview' | 'queued' | 'range-end' | 'range-middle' | 'range-start' | 'readonly' | 'required' | 'resizing' | 'selected' | 'static' | 'suboptimal' | 'suspended' | 'today' | 'touched' | 'unavailable' | 'unchecked' | 'unselected' | 'uploading' | 'valid' | 'vertical' | 'visible'
+/** Tour namespaces its states by the part that carries them. */
+ | `${'content' | 'next-trigger' | 'prev-trigger'}:${string}`;
+/** A custom property in the `--skdx-` namespace. */
+export type CssVar = `--skdx-${string}`;
+/** Narrows a member to the frameworks that can express it, with a documented architectural reason for the rest; the two fields come together or not at all. */
+/** Copies a scoped member with its framework scope removed. */
+export declare function withoutScope<T extends FrameworkScopedContract>(member: T): Omit<T, 'frameworks' | 'frameworksReason' | 'exception'>;
+/**
+ * The kind of capability equivalence a framework-scoped member records — the
+ * native channel the frameworks outside its scope reach the same capability
+ * through, never a feature they still owe.
+ */
+export type ExceptionCategory = 
+/** Function-valued prop the other frameworks deliver as a slot, template or projected child. */
+'render-prop'
+/** Mount switch that only means something where the part actually unmounts. */
+ | 'force-mount'
+/** Teleporting the content out of its position in the tree. */
+ | 'portal'
+/** Uncontrolled seed the Web Components property already is on its own. */
+ | 'wc-default'
+/** Cross-part id and internals wiring the declarative frameworks do while rendering. */
+ | 'wc-internals'
+/** Instance method the controlled-props frameworks answer from state instead. */
+ | 'imperative'
+/** Data attribute marking a node the custom element generated for itself. */
+ | 'wc-marker'
+/** Element polymorphism the other frameworks spell as an attribute directive. */
+ | 'as-directive'
+/** Light-DOM rendering the platform forces on form controls and labels. */
+ | 'light-dom'
+/** DOM-cased event handler prop that Svelte alone spells lowercase. */
+ | 'svelte-dom-event'
+/** Element the other frameworks hand out directly rather than wrap in a method. */
+ | 'element-handoff'
+/** Plain HTML attribute the other frameworks take through passthrough. */
+ | 'attribute-passthrough'
+/** Event the framework splits, renames or leaves to the platform's own. */
+ | 'event-shape'
+/** Presence of content that Svelte cannot detect behind an opaque snippet. */
+ | 'snippet-opaque'
+/** Recipe-level switch for a part the other frameworks expose for the consumer to compose by hand. */
+ | 'derived-anatomy'
+/** Attribute on an extra host element only one framework renders around the part. */
+ | 'framework-host'
+/** Per-part switch the other frameworks set on the root, which reaches the part through context. */
+ | 'root-prop';
+export type FrameworkScopedContract = {
+    frameworks?: undefined;
+    frameworksReason?: undefined;
+    exception?: undefined;
+} | {
+    /** The frameworks that ship this member; omit for the normal case where every framework ships it. */
+    frameworks: readonly FrameworkKey[];
+    /** Why the frameworks left out of `frameworks` have no counterpart, in terms of their architecture rather than their backlog. */
+    frameworksReason: string;
+    /**
+     * Which recorded equivalence this narrowing is; the docs render one canonical sentence per category.
+     * `| undefined` so a contract can spread a scoped member and re-narrow its `frameworks` under
+     * `exactOptionalPropertyTypes`; `contract-props.mjs` is what rejects a narrowing that has none.
+     */
+    exception?: ExceptionCategory | undefined;
+};
+/** One member reached through context (or DI/factory), not as an element method. */
+export interface ContextApiContract {
+    /** Member name — matches its {@link PublicMethodContract.name} when the member is also an element method. */
+    name: string;
+    /** Call signature as source text (parameters and return type). */
+    signature: string;
+    /** What the member does, and why context is the access path. */
+    description: string;
+    /** Default as source text, same spelling rules as PropContract.defaultValue (for readonly members with fixed values). */
+    defaultValue?: string;
+    /** How to reach it in each framework that exposes it this way. */
+    accessors: ContextApiAccessors;
+}
+/** One member one framework ships that adapts an ecosystem the other four do not have, not an undeclared gap. */
+export interface FrameworkExtensionContract {
+    /** Which framework ships it; the keys are {@link ContextApiAccessors}'s. */
+    framework: keyof ContextApiAccessors;
+    /** Part the member lives on, framework-neutral, or omitted for the component root. */
+    part?: string;
+    /** Member name as that framework spells it. */
+    name: string;
+    /** TypeScript-style type expression, as source text. */
+    type: string;
+    /** What it does, which ecosystem it adapts, and why the other four have no counterpart. */
+    description: string;
+}
+/** One content slot, with the same frameworks/frameworksReason opt-out props get: a render prop in one framework is a named slot in another. */
+export type SlotContract = FrameworkScopedContract & {
+    /** Slot name as consumers spell it; `default` for unnamed projection. */
+    name: string;
+    /** What belongs in the slot, and what renders when nothing is passed. */
+    description: string;
+};
+/** A part name some frameworks spell differently from the contract's, with a documented design reason. */
+export interface PartAliasContract {
+    /** The part name those frameworks use instead of the contract's (`Option` for `Item`). */
+    name: string;
+    /** The frameworks that spell it that way. */
+    frameworks: readonly FrameworkKey[];
+    /** Why the rename is the design rather than drift, in terms of what the part does there. */
+    frameworksReason: string;
+}
+/** One compound part of a component, named framework-neutrally (e.g. `Content`, not `PopoverContent`). */
+export type PartContract = FrameworkScopedContract & {
+    /** Framework-neutral part name, PascalCase and without the component prefix (e.g. `Content`, `ClearButton`). */
+    name: string;
+    /** What the part is for and where it sits relative to the root. */
+    description: string;
+    /** Set when the Web Components element renders into the light DOM, so its `part=` names are unreachable from `::part()` and skins target it by class instead. */
+    lightDom?: true;
+    /** Other names this part goes by. See {@link PartAliasContract}. */
+    aliases?: readonly PartAliasContract[];
+    /** Props this part accepts, in addition to whatever the framework's base element props are. */
+    props?: readonly PropContract[];
+    /** Events this part emits. Same lowercase-kebab-case rule as {@link EventContract.name}. */
+    events?: readonly EventContract[];
+    /** Content this part projects (React children, Angular projection, Vue/Svelte/Web Components slots). Root slots stay on ComponentContract.slots. */
+    slots?: readonly SlotContract[];
+    /** Imperative methods this part publishes on its own element or instance (e.g. Fieldset's `validate()`), separate from root methods. */
+    methods?: readonly PublicMethodContract[];
+};
+/** The full shared contract for one component; slots cover each framework's native content projection. */
+export interface ComponentContract {
+    name: string;
+    purpose: string;
+    props: readonly PropContract[];
+    events: readonly EventContract[];
+    /** The compound parts this component is composed of; absent on single-element components. */
+    parts?: readonly PartContract[];
+    /** Set when the Web Components root element renders into the light DOM, so its `part=` names are unreachable from `::part()` and skins target it by class instead. */
+    lightDom?: true;
+    slots: readonly SlotContract[];
+    /** Skin-level appearance vocabulary: `data-*` attributes the skin reads; where the contract declares the matching prop, either path renders the same. */
+    appearance?: readonly AppearanceAxisContract[];
+    /** The `data-state` values this component emits, from the {@link ComponentState} vocabulary. */
+    states: readonly ComponentState[];
+    controlledUncontrolled: string;
+    formBehavior: string;
+    validationBehavior: string;
+    accessibility: AccessibilityContract;
+    styling: StylingHooksContract;
+    publicMethods: readonly PublicMethodContract[];
+    /** Members reached through context (or DI/factory), absent on most components. */
+    contextApi?: readonly ContextApiContract[];
+    /** Members one framework ships that adapt its ecosystem, absent on most components. */
+    frameworkExtensions?: readonly FrameworkExtensionContract[];
+}

package/dist/shared/contracts/types.js

@@ -0,0 +1 @@
+function a(e){let{frameworks:r,frameworksReason:n,exception:o,...t}=e;return t}export{a as withoutScope};

package/dist/shared/contracts/usage-card.d.ts

@@ -0,0 +1,3 @@
+import type { ComponentContract } from './types.js';
+/** Contract for the UsageCard block: a quota tile composing Progress and Text. */
+export declare const usageCardContract: ComponentContract;

package/dist/shared/contracts/usage-card.js

@@ -0,0 +1 @@
+import{ROOT_DATA_ATTRIBUTES as e}from"./styling-hooks.js";var a={name:"UsageCard",purpose:"A quota / consumption tile block composing Progress and Text. Renders a labelled group holding the amount used against a limit, a derived meter and a status colour, handling a finite, zero, unlimited or unknown limit without division errors. Ships in the blocks package of each framework, not the core package.",props:[{name:"label",type:"string",required:!0,description:"Name of the quota, rendered into the label that names the group through aria-labelledby."},{name:"used",type:"number",required:!0,description:"The current amount consumed, formatted by formatValue for the value region and the meter."},{name:"limit",type:"number | null",required:!1,description:"The finite cap used is measured against; null renders unlimitedLabel instead of a number. No meter or limit text renders when omitted."},{name:"unit",type:"string",required:!1,description:'Unit label rendered after the limit text, such as "GB" or "seats".'},{name:"formatValue",type:"(value: number) => string",defaultValue:"String",required:!1,description:"Formats used and limit for the consumer's own locale and precision, in the value region and the meter's readout."},{name:"unlimitedLabel",type:"string",defaultValue:"'Unlimited'",required:!1,description:"Text rendered in place of a limit number when limit is null."},{name:"description",type:"string",required:!1,description:"Supporting copy rendered below the meter, in the skin's muted tone."},{name:"actions",type:"unknown",required:!1,frameworks:["react","svelte","angular"],exception:"render-prop",frameworksReason:"Vue and Web Components take this as a named slot rather than a prop \u2014 Vue because a renderable region is a slot in Vue's own idiom, Web Components because a custom element attribute carries a string and cannot carry a node. Both slot spellings are declared under `slots`.",description:"Controls rendered at the end of the header, such as a manage-plan link. A prop in React, Svelte, and Angular; Vue and Web Components use the `actions` slot."},{name:"footer",type:"unknown",required:!1,frameworks:["react","svelte","angular"],exception:"render-prop",frameworksReason:"Vue and Web Components take this as a named slot rather than a prop \u2014 Vue because a renderable region is a slot in Vue's own idiom, Web Components because a custom element attribute carries a string and cannot carry a node. Both slot spellings are declared under `slots`.",description:"Content rendered in a footer region below the card, such as renewal or reset metadata. A prop in React, Svelte, and Angular; Vue and Web Components use the `footer` slot."},{name:"status",type:"'info' | 'success' | 'warning' | 'danger' | (string & {})",required:!1,description:"Colour role written to data-status, tinting the meter fill and the used amount. Over-limit is derived, not set through this prop."}],events:[],slots:[{name:"actions",description:"Controls placed at the end of the header."},{name:"footer",description:"Content placed in a footer region below the card."}],appearance:[{attribute:"data-status",values:["info","success","warning","danger"],stylesheet:"usage-card.css"}],states:["default","over-limit"],controlledUncontrolled:"Stateless \u2014 UsageCard holds no internal state.",formBehavior:"Not applicable \u2014 UsageCard participates in no form.",validationBehavior:"Not applicable \u2014 UsageCard renders a reading rather than participating in any validation.",accessibility:{role:'group (native <div role="group"> named by its label; the derived Progress is role="meter" named by the same label)',keyboard:[],ariaAttributes:["aria-labelledby on the group points at the label, so the tile is announced by its quota name","aria-labelledby on the derived meter points at the same label, so the reading and the tile share one name"],focusManagement:"Nothing inside the block is focusable except the controls the consumer supplies through actions and footer."},styling:{cssParts:["usage-card","header","label","actions","value","used","limit","unit","progress","description","footer"],dataAttributes:[...e,"data-state","data-status",{name:"data-skdx-usage-card-generated",frameworks:["webComponents"],exception:"wc-marker",frameworksReason:'Marks a node the element generated for itself rather than one the consumer authored. React, Vue, Svelte and Angular re-render their derived anatomy declaratively, so "mine or theirs" is answered by the framework and no marker is needed.'}],cssCustomProperties:[]},publicMethods:[]};export{a as usageCardContract};

package/dist/shared/contracts/user-menu.d.ts

@@ -0,0 +1,3 @@
+import type { ComponentContract } from './types.js';
+/** Contract for the UserMenu block: an avatar-and-identity trigger opening a menu with a repeated identity header. */
+export declare const userMenuContract: ComponentContract;

package/dist/shared/contracts/user-menu.js

@@ -0,0 +1 @@
+import{closeAutoFocusEvent as e,dismissalEvents as t,openChangeCompleteEvent as r}from"./overlay-parts.js";import{ROOT_DATA_ATTRIBUTES as n}from"./styling-hooks.js";var i={name:"UserMenu",purpose:"The signed-in user's menu, composing MenuRoot, MenuTrigger, MenuPortal, MenuContent, MenuLabel, MenuSeparator and Avatar. A derived trigger shows the avatar, name and description; the panel repeats the identity in a header above the application's own entries. Ships in the blocks package of each framework, not the core package.",props:[{name:"name",type:"string",required:!0,description:"The signed-in user's name, rendered in the trigger and repeated in the menu header."},{name:"description",type:"string",required:!1,description:"Secondary text such as an email or role, rendered below the name in the trigger and the header. Neither region renders it when omitted."},{name:"avatarSrc",type:"string",required:!1,description:"Source of the identity image, passed straight through to the derived Avatar. The Avatar renders its initials fallback when omitted."},{name:"status",type:"unknown",required:!1,frameworks:["react","svelte","angular"],exception:"render-prop",frameworksReason:"Vue and Web Components take this as a named slot rather than a prop \u2014 Vue because a renderable region is a slot in Vue's own idiom, Web Components because a custom element attribute carries a string and cannot carry a node. Both slot spellings are declared under `slots`.",description:"Extra indicator, such as a status dot or Badge, rendered after the identity in the trigger. No indicator renders when omitted. A prop in React, Svelte, and Angular; Vue and Web Components use the `status` slot."},{name:"trigger",type:"unknown",required:!1,frameworks:["react","svelte","angular"],exception:"render-prop",frameworksReason:"Vue and Web Components take this as a named slot rather than a prop \u2014 Vue because a renderable region is a slot in Vue's own idiom, Web Components because a custom element attribute carries a string and cannot carry a node. Both slot spellings are declared under `slots`.",description:"Element that replaces the derived avatar-and-identity trigger entirely, merged with the menu's open behaviour. The derived trigger renders when omitted. A prop in React, Svelte, and Angular; Vue and Web Components use the `trigger` slot."},{name:"variant",type:"'compact' | (string & {})",required:!1,description:"Visual rung written to data-variant on the derived trigger; 'compact' visually hides the identity text while keeping it as the accessible name."},{name:"open",type:"boolean",required:!1,description:"Whether the menu is open, for controlled usage. Pair with an open-change event."},{name:"defaultOpen",type:"boolean",defaultValue:"false",required:!1,description:"Whether the menu starts open, for uncontrolled usage."},{name:"side",type:"'top' | 'right' | 'bottom' | 'left'",defaultValue:"'bottom'",required:!1,description:"Which side of the trigger the menu panel opens on."},{name:"align",type:"'start' | 'center' | 'end'",defaultValue:"'end'",required:!1,description:"Alignment of the menu panel relative to the side it opens on."}],events:[...t("menu"),e("menu"),r("menu"),{name:"open-change",description:"Fires with the new open state whenever the trigger opens or closes the menu.",detail:"boolean"}],slots:[{name:"default",description:"The application's own menu entries, rendered below the repeated identity header."},{name:"trigger",description:"Content that replaces the derived avatar-and-identity trigger entirely."},{name:"status",description:"An extra indicator rendered after the identity in the trigger."}],appearance:[{attribute:"data-variant",values:["compact"],stylesheet:"user-menu.css"}],states:["default"],controlledUncontrolled:"Open state is controlled when open is set, paired with onOpenChange; otherwise uncontrolled, seeded from defaultOpen.",formBehavior:"Not applicable \u2014 UserMenu participates in no form.",validationBehavior:"Not applicable \u2014 UserMenu carries no value and participates in no validation.",accessibility:{role:'button (the derived trigger is a native <button> with aria-haspopup="menu" and aria-expanded from the core MenuTrigger; the popup is role="menu")',keyboard:[{key:"Enter/Space/ArrowDown",behavior:"Opens the menu, focusing its first item."},{key:"ArrowUp",behavior:"Opens the menu, focusing its last item."},{key:"ArrowDown/ArrowUp",behavior:"Moves focus between entries once the menu is open."},{key:"Escape",behavior:"Closes the menu and returns focus to the trigger."},{key:"A\u2013Z",behavior:"Typeahead: moves focus to the next entry whose text starts with the typed character."}],ariaAttributes:['aria-haspopup="menu" and aria-expanded on the trigger, from the core MenuTrigger','the panel carries role="menu" and aria-labelledby pointing at the trigger, from the core MenuContent'],focusManagement:"Opening the menu moves focus to its first (or, from ArrowUp, last) entry; closing returns focus to the trigger."},styling:{cssParts:["user-menu","avatar","identity","name","description","content","header"],dataAttributes:[...n,"data-variant",{name:"data-skdx-user-menu-generated",frameworks:["webComponents"],exception:"wc-marker",frameworksReason:'Marks a node the element generated for itself rather than one the consumer authored. React, Vue, Svelte and Angular re-render their derived anatomy declaratively, so "mine or theirs" is answered by the framework and no marker is needed.'}],cssCustomProperties:[]},publicMethods:[]};export{i as userMenuContract};

package/dist/shared/contracts/verification-page.d.ts

@@ -0,0 +1,3 @@
+import type { ComponentContract } from './types.js';
+/** Contract for the VerificationPage block: a one-time-code pin input with a submit and a consumer-driven resend. */
+export declare const verificationPageContract: ComponentContract;

package/dist/shared/contracts/verification-page.js

@@ -0,0 +1 @@
+import{changeDetail as e}from"./change-reason.js";import{ROOT_DATA_ATTRIBUTES as t}from"./styling-hooks.js";var o={name:"VerificationPage",purpose:"A one-time-code block composing Heading, Text, Alert, Form, Field, PinInput and Button. It collects a code of a fixed length, reports it through a verify event once it is complete, and offers a resend control whose cooldown the consumer owns. Ships in the blocks package of each framework, not the core package.",props:[{name:"title",type:"string",defaultValue:"'Enter your verification code'",required:!1,description:"Heading text, rendered into a derived <h1> that names the section."},{name:"description",type:"string",required:!1,description:"Supporting copy rendered into a derived Text below the title, naming where the code was sent. No description region renders when omitted."},{name:"error",type:"string",required:!1,description:"Message rendered into a derived error Alert above the form. The block never clears it: set it from the verify handler and reset it when the next attempt starts."},{name:"pending",type:"boolean",defaultValue:"false",required:!1,description:"Marks the request in flight, making the submit button busy and unusable while the code boxes stay editable, so the user can still correct a digit."},{name:"codeLabel",type:"string",defaultValue:"'Verification code'",required:!1,description:"Field label and accessible name of the derived pin input holding the code, so the group of boxes is announced as one control."},{name:"length",type:"number",defaultValue:"6",required:!1,description:"How many character boxes the code is entered into, and how long a complete code is before it may be submitted."},{name:"value",type:"string",required:!1,description:"Current code, for controlled usage; pair it with the value-change event. Uncontrolled, the pin input tracks the code itself."},{name:"defaultValue",type:"string",required:!1,description:"Initial code, for uncontrolled usage \u2014 seeds the boxes on first render and leaves the rest empty."},{name:"submitLabel",type:"string",defaultValue:"'Verify'",required:!1,description:"Text of the form submit button."},{name:"resendLabel",type:"string",defaultValue:"'Resend code'",required:!1,description:"Text of the resend button, which renders only alongside a resend event handler."},{name:"resendDisabled",type:"boolean",defaultValue:"false",required:!1,description:"Makes the resend button unusable, for a consumer running its own cooldown between requests."},{name:"resendHint",type:"string",required:!1,description:"Note rendered beside the resend button, such as how long the cooldown has left. The block runs no timer of its own."},{name:"footer",type:"unknown",required:!1,frameworks:["react","svelte","angular"],exception:"render-prop",frameworksReason:"Vue and Web Components take this as a named slot rather than a prop \u2014 Vue because a renderable region is a slot in Vue's own idiom, Web Components because a custom element attribute carries a string and cannot carry a node. Both slot spellings are declared under `slots`.",description:"Navigation rendered below the resend region, such as a link back to the sign-in page. No footer region renders when omitted. A prop in React, Svelte, and Angular; Vue and Web Components use the `footer` slot."}],events:[{name:"verify",detail:"{ code: string }",description:"Fires when the form is submitted with a code of exactly the declared length, carrying that code. The native submit is prevented, so the consumer performs the check and sets error on failure."},{name:"resend",detail:"void",description:"Fires when the resend button is activated. Handling it is what renders the resend region at all; the cooldown between requests belongs to the consumer."},{name:"value-change",detail:e("string"),description:"Fires with the new code whenever any box changes, controlled or not, so a consumer can mirror the code or clear a stale error."}],slots:[{name:"default",description:"Extra fields rendered inside the form, above the submit button."},{name:"footer",description:"Navigation below the resend region, such as a link back to the sign-in page."}],states:["default"],controlledUncontrolled:"The code is controllable through value with the value-change event, or seeded with defaultValue and tracked by the pin input; error and pending are always controlled by the consumer.",formBehavior:"The form is a core Form root whose pin input submits the joined code as one required entry with a length pattern, so a short code is refused by constraint validation and emits nothing.",validationBehavior:"The code is required and only satisfies its constraint once every box is filled; the block adds no validators and never times the resend cooldown.",accessibility:{role:"region (native <section> named by its heading through aria-labelledby)",keyboard:[{key:"ArrowLeft/ArrowRight",behavior:"Moves between the code boxes, which the pin input wires itself."},{key:"Enter",behavior:"Submits the form while a code box has focus (native form submission)."}],ariaAttributes:["aria-labelledby on the <section> points at the derived heading","the pin input group carries aria-label from codeLabel, so the boxes are announced as one named control","the derived error Alert is a live region, so a new error is announced without moving focus"],focusManagement:"Focus follows the code boxes as the pin input advances them; a refused submit reports through constraint validation rather than a jump of the block's own."},styling:{cssParts:["verification-page","panel","title","description","error","form","field","code","submit","resend","resend-hint","footer"],dataAttributes:[...t,{name:"data-skdx-verification-page-generated",frameworks:["webComponents"],exception:"wc-marker",frameworksReason:'Marks a node the element generated for itself rather than one the consumer authored. React, Vue, Svelte and Angular re-render their derived anatomy declaratively, so "mine or theirs" is answered by the framework and no marker is needed.'},{name:"data-skdx-verification-page-content",frameworks:["webComponents"],exception:"wc-marker",frameworksReason:'Marks a node the element generated for itself rather than one the consumer authored. React, Vue, Svelte and Angular re-render their derived anatomy declaratively, so "mine or theirs" is answered by the framework and no marker is needed.'}],cssCustomProperties:[]},publicMethods:[]};export{o as verificationPageContract};

package/dist/shared/contracts/workspace-switcher.d.ts

@@ -0,0 +1,3 @@
+import type { ComponentContract } from './types.js';
+/** Contract for the WorkspaceSwitcher block: a searchable list that switches the active context. */
+export declare const workspaceSwitcherContract: ComponentContract;

package/dist/shared/contracts/workspace-switcher.js

@@ -0,0 +1 @@
+import{changeDetail as e}from"./change-reason.js";import{autoFocusEvents as t,dismissalEvents as a,openChangeCompleteEvent as r}from"./overlay-parts.js";import{ROOT_DATA_ATTRIBUTES as n}from"./styling-hooks.js";var l={name:"WorkspaceSwitcher",purpose:"Switches the active context \u2014 workspace, organisation, team, account or project \u2014 from a searchable list with groups, disabled entries, loading and empty states, and a footer for create or manage actions. Composes the Popover parts (PopoverRoot, PopoverTrigger, PopoverPortal, PopoverContent) around the Command parts (Command, CommandInput, CommandList, CommandEmpty, CommandLoading, CommandGroup, CommandItem); the leading glyph is a consumer-supplied node such as an Avatar. Terminology is the consumer's, and the block performs no routing and no persistence. Ships in the blocks package of each framework, not the core package.",props:[{name:"items",type:"ReadonlyArray<{ id: string; label: string; description?: string; group?: string; disabled?: boolean }>",required:!0,description:"Every context the user may switch to, rendered in the order given; items sharing a group are listed under that heading, ungrouped ones first."},{name:"value",type:"string",required:!1,description:"Id of the active context, for controlled usage; pair it with the value-change event."},{name:"defaultValue",type:"string",defaultValue:"''",required:!1,description:"Id of the context active on first render, for uncontrolled usage; the trigger shows the placeholder until one is picked."},{name:"placeholder",type:"string",defaultValue:"'Select'",required:!1,description:"Trigger text shown while no item in the list is the active one."},{name:"label",type:"string",required:!1,description:"Accessible name for the trigger and the result list, for when the visible trigger text is not enough on its own."},{name:"searchLabel",type:"string",defaultValue:"'Search'",required:!1,description:"Accessible name of the search field inside the open panel."},{name:"searchPlaceholder",type:"string",required:!1,description:"Placeholder text shown inside the empty search field; the field renders none when omitted."},{name:"emptyMessage",type:"string",defaultValue:"'No results'",required:!1,description:"Message shown beside the list when the search matches nothing."},{name:"loadingMessage",type:"string",defaultValue:"'Loading'",required:!1,description:"Message announced through a live region while the results are still in flight."},{name:"loading",type:"boolean",defaultValue:"false",required:!1,description:"Marks the results as in flight, showing the loading message and withholding the empty one."},{name:"selectedLabel",type:"string",defaultValue:"'Current'",required:!1,description:"Visually hidden text appended to the active item, naming it for screen reader users."},{name:"leading",type:"Snippet<[WorkspaceSwitcherItem]>",required:!1,frameworks:["svelte"],exception:"render-prop",frameworksReason:"Svelte spells a per-item render hook as a snippet prop, which is both a prop and a slot in that framework's own idiom; the other frameworks take it through renderLeading or the `leading` scoped slot.",description:"The Svelte snippet form of `renderLeading`, rendered once per item with that item as its argument."},{name:"renderLeading",type:"unknown",required:!1,frameworks:["react","angular","webComponents"],exception:"render-prop",frameworksReason:"Vue takes this as a scoped slot and Svelte as a snippet of the same name rather than a prop, because a per-item render hook is a slot with slot props in their own idioms; React, Angular and Web Components take the function, since one markup slot cannot render once per item.",description:"Renders a decorative glyph, such as an avatar or a logo, for one item and for the trigger. No leading region renders when omitted. A prop in React and Angular; Vue uses the `leading` scoped slot and Svelte the `leading` snippet; Web Components set the function as a property."},{name:"actions",type:"unknown",required:!1,frameworks:["react","svelte","angular"],exception:"render-prop",frameworksReason:"Vue and Web Components take this as a named slot rather than a prop \u2014 Vue because a renderable region is a slot in Vue's own idiom, Web Components because a custom element attribute carries a string and cannot carry a node. Both slot spellings are declared under `slots`.",description:"Controls placed in the panel's footer, such as create and manage buttons. No footer region renders when omitted. A prop in React, Svelte, and Angular; Vue and Web Components use the `actions` slot."},{name:"trigger",type:"unknown",required:!1,frameworks:["react","svelte","angular"],exception:"render-prop",frameworksReason:"Vue and Web Components take this as a named slot rather than a prop \u2014 Vue because a renderable region is a slot in Vue's own idiom, Web Components because a custom element attribute carries a string and cannot carry a node. Both slot spellings are declared under `slots`.",description:"Replaces the derived trigger button with the consumer's own element, which still receives the popover wiring. A prop in React, Svelte, and Angular; Vue and Web Components use the `trigger` slot."},{name:"open",type:"boolean",required:!1,description:"Whether the panel is open, for controlled usage; pair it with the open-change event."},{name:"defaultOpen",type:"boolean",defaultValue:"false",required:!1,description:"Whether the panel is open on first render, for uncontrolled usage."}],events:[...a("panel"),...t("panel"),r("panel"),{name:"value-change",detail:e("string"),description:"Fires with the id of the item the user picked, immediately before the panel closes."},{name:"open-change",detail:"boolean",description:"Fires with the new open state whenever the panel opens or closes, controlled or not."}],slots:[{name:"trigger",description:"The trigger prop's element, replacing the derived trigger button entirely."},{name:"leading",frameworks:["vue","svelte"],exception:"render-prop",frameworksReason:"Vue spells a per-item render hook as a scoped slot and Svelte as a snippet; React, Angular and Web Components take the equivalent function through the prop of the same purpose.",description:"The renderLeading prop's glyph, scoped to the item it decorates and to the trigger."},{name:"actions",description:"The actions prop's content \u2014 the footer's create and manage controls."}],states:["default"],controlledUncontrolled:"Both the active id and the open state are controlled when their prop is set and tracked internally otherwise; each reports every change through its event either way.",formBehavior:"Not applicable \u2014 WorkspaceSwitcher submits nothing and participates in no form.",validationBehavior:"Not applicable \u2014 the active id is always one of the items and carries no validation.",accessibility:{role:'button (derived trigger with aria-haspopup="dialog" and aria-expanded from the core PopoverTrigger; the popup is a non-modal Popover holding a Command listbox with a search input, so Tab and outside interaction leave it without an Escape key)',keyboard:[{key:"ArrowDown/ArrowUp",behavior:"Moves the highlight between the listed items."},{key:"Enter",behavior:"Selects the highlighted item and closes the panel."},{key:"Escape",behavior:"Closes the panel and returns focus to the trigger."},{key:"Character keys",behavior:"Type into the search field to filter the list down to matching items."}],ariaAttributes:['aria-haspopup="dialog" and aria-expanded on the trigger come from the core PopoverTrigger','the panel is a role="dialog" whose search input owns real focus and points aria-activedescendant at the highlighted option',"the result listbox is named by the label prop, falling back to the placeholder","the leading glyph regions are aria-hidden, so the item label alone carries the meaning","the active item ends with visually hidden text naming it as the current context"],focusManagement:"Opening moves focus into the panel and onto the search field, which keeps it while the arrow keys move a virtual highlight; closing returns focus to the trigger."},styling:{cssParts:["workspace-switcher","leading","current","description","content","search","list","loading","empty","group","item","item-leading","item-label","item-description","footer"],dataAttributes:[...n,"data-selected",{name:"data-skdx-workspace-switcher-generated",frameworks:["webComponents"],exception:"wc-marker",frameworksReason:'Marks a node the element generated for itself rather than one the consumer authored. React, Vue, Svelte and Angular re-render their derived anatomy declaratively, so "mine or theirs" is answered by the framework and no marker is needed.'}],cssCustomProperties:[]},publicMethods:[]};export{l as workspaceSwitcherContract};

package/dist/shared/core/announcer.d.ts

@@ -0,0 +1,17 @@
+/** Which of the two singleton live regions a message is routed to. */
+export type AnnouncePoliteness = 'polite' | 'assertive';
+/** How long successive announcements keep merging into one write before the region updates. */
+export declare const ANNOUNCE_DEBOUNCE_MS = 150;
+/** Owns the `aria-live` regions and their debounced writes; one instance per process (or per Angular injector). */
+export declare class Announcer {
+    private readonly regions;
+    /**
+     * Schedules `message` for the region; a burst inside one debounce window collapses to its last message, and a repeat of the text already shown is re-announced.
+     */
+    announce(message: string, politeness?: AnnouncePoliteness): void;
+    /** Empties the region(s) and drops anything still pending; pass a politeness to clear just one. */
+    clear(politeness?: AnnouncePoliteness): void;
+    /** Clears and removes the regions from the document. */
+    destroy(): void;
+    private regionFor;
+}

package/dist/shared/core/announcer.js

@@ -0,0 +1 @@
+var d=150,r="position:absolute;border:0;width:1px;height:1px;padding:0;margin:-1px;overflow:hidden;clip:rect(0, 0, 0, 0);white-space:nowrap;word-wrap:normal;",o=class{constructor(){this.regions=new Map}announce(n,i="polite"){if(typeof document>"u")return;let e=n.trim();if(!e)return;let t=this.regionFor(i);t.pending=e,t.node.textContent="",clearTimeout(t.timer),t.timer=setTimeout(()=>{t.timer=void 0,t.node.textContent=t.pending},150)}clear(n){for(let[i,e]of this.regions)n!==void 0&&i!==n||(clearTimeout(e.timer),e.timer=void 0,e.node.textContent="")}destroy(){this.clear();for(let n of this.regions.values())n.node.remove();this.regions.clear()}regionFor(n){let i=this.regions.get(n);if(i?.node.isConnected)return i;let e=document.createElement("div");e.setAttribute("aria-live",n),e.setAttribute("aria-atomic","true"),e.setAttribute("data-skdx-live-announcer",n),e.style.cssText=r,document.body.appendChild(e);let t={node:e,pending:"",timer:void 0};return this.regions.set(n,t),t}};export{d as ANNOUNCE_DEBOUNCE_MS,o as Announcer};

package/dist/shared/core/appearance.d.ts

@@ -0,0 +1,14 @@
+/** One appearance axis value as a consumer may pass it: a rung name, a presence flag, or nothing. */
+export type AppearanceValue = string | boolean | null | undefined;
+/**
+ * Resolves appearance axes to the `data-*` attributes the skin reads, so a
+ * consumer may set either the prop (`size="lg"`) or the attribute
+ * (`data-size="lg"`) and both render the same. The prop wins when both are
+ * given; `false`, `null` and `undefined` leave the attribute off; `true`
+ * writes a bare presence attribute.
+ *
+ * @param values - Axis name to prop value, e.g. `{ size, iconOnly }`; camelCase keys map to kebab-case attributes.
+ * @param attrs - The pass-through attributes the consumer supplied, read for `data-<axis>` fallbacks.
+ * @returns A `data-<axis>` record to spread after the pass-through attributes.
+ */
+export declare function appearanceAttrs(values: Record<string, AppearanceValue>, attrs?: Record<string, unknown>): Record<string, string | undefined>;

package/dist/shared/core/appearance.js

@@ -0,0 +1 @@
+function i(r,o={}){let n={};for(let a of Object.keys(r)){let t=`data-${a.replace(/[A-Z]/g,s=>`-${s.toLowerCase()}`)}`,e=r[a]??o[t];e==null||e===!1?n[t]=void 0:n[t]=e===!0?"":String(e)}return n}export{i as appearanceAttrs};

package/dist/shared/core/arrow-keys.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Whether the carousel root should ignore this Arrow keypress, leaving it to whatever inside the carousel owns it.
+ *
+ * @param target the event's target
+ * @param root the carousel root the handler is attached to
+ */
+export declare function arrowKeyBelongsToDescendant(target: EventTarget | null, root: Element): boolean;

package/dist/shared/core/arrow-keys.js

@@ -0,0 +1 @@
+var r=new Set(["textbox","searchbox","listbox","slider","spinbutton","menu","menubar","tablist","grid","treegrid","tree","combobox","radiogroup"]),o=new Set(["INPUT","SELECT","TEXTAREA","AUDIO","VIDEO"]);function l(e){if(o.has(e.tagName)||e.isContentEditable)return!0;let n=e.getAttribute("role");return n!==null&&r.has(n)}function u(e,n){if(!(e instanceof Element))return!1;let t=e;for(;t!==null&&t!==n;){if(l(t))return!0;t=t.parentElement}return!1}export{u as arrowKeyBelongsToDescendant};

package/dist/shared/core/calendar-locale.d.ts

@@ -0,0 +1,35 @@
+/** How much of a name to render — the `Intl.DateTimeFormat` `month`/`weekday` widths. */
+export type NameWidth = 'narrow' | 'short' | 'long';
+/** The runtime's own locale, used whenever `locale` is omitted — matches what `toLocaleDateString()` would pick. */
+export declare function resolveLocale(locale?: string): string;
+/**
+ * The twelve month names of `locale`, January first, at the requested width.
+ *
+ * @example
+ * ```ts
+ * getMonthNames('fr-FR')[0]; // 'janvier'
+ * ```
+ */
+export declare function getMonthNames(locale?: string, width?: NameWidth): string[];
+/**
+ * The seven weekday names of `locale` at the requested width, rotated so index
+ * `0` is `weekStartsOn` (`0` = Sunday … `6` = Saturday).
+ *
+ * @example
+ * ```ts
+ * getWeekDayNames('en-GB', 1, 'short'); // ['Mon', 'Tue', … 'Sun']
+ * ```
+ */
+export declare function getWeekDayNames(locale?: string, weekStartsOn?: number, width?: NameWidth): string[];
+/** The first day of the week `locale` uses (`0` = Sunday … `6` = Saturday), read from `Intl.Locale`'s week info, falling back to `0` on engines without it. */
+export declare function getLocaleWeekStartsOn(locale?: string): 0 | 1 | 2 | 3 | 4 | 5 | 6;
+/** The month heading label for `month` (e.g. `'janvier 2026'`), formatted for `locale`. */
+export declare function formatMonthLabel(month: Date, locale?: string): string;
+/** A bare year formatted for `locale` (e.g. `'2026'`, `'٢٠٢٦'` in `ar-EG`) using `Intl.NumberFormat` with grouping off, since a grouped `2,026` is not a year. */
+export declare function formatYear(year: number, locale?: string): string;
+/** A year page label (e.g. `'2020 – 2039'`), the year view's heading and grid name. */
+export declare function formatYearRange(start: number, end: number, locale?: string): string;
+/** A full, spoken-friendly date label (e.g. `'Monday, January 5, 2026'`) for live-region announcements. */
+export declare function formatDateLabel(date: Date, locale?: string): string;
+/** @internal Drops every memoized name list. */
+export declare function clearLocaleNameCache(): void;

package/dist/shared/core/calendar-locale.js

@@ -0,0 +1 @@
+var s=new Date(2024,0,7),c=new Map;function m(t,e){let n=c.get(t);if(n)return n;let r=e();return c.set(t,r),r}function o(t){return t??new Intl.DateTimeFormat().resolvedOptions().locale}function D(t,e="long"){let n=o(t);return m(`m|${n}|${e}`,()=>{let r=new Intl.DateTimeFormat(n,{month:e,timeZone:"UTC"});return Array.from({length:12},(i,a)=>r.format(Date.UTC(2024,a,15)))})}function h(t,e=0,n="short"){let r=o(t),i=m(`w|${r}|${n}`,()=>{let u=new Intl.DateTimeFormat(r,{weekday:n});return Array.from({length:7},(f,l)=>u.format(new Date(s.getFullYear(),s.getMonth(),s.getDate()+l)))}),a=(e%7+7)%7;return i.slice(a).concat(i.slice(0,a))}function p(t){try{let e=new Intl.Locale(o(t)),n=(e.getWeekInfo?.()??e.weekInfo)?.firstDay;if(typeof n=="number")return n%7}catch{}return 0}function y(t,e){return t.toLocaleDateString(o(e),{month:"long",year:"numeric"})}function g(t,e){return new Intl.NumberFormat(o(e),{useGrouping:!1}).format(t)}function d(t,e,n){return`${g(t,n)} \u2013 ${g(e,n)}`}function w(t,e){return t.toLocaleDateString(o(e),{weekday:"long",year:"numeric",month:"long",day:"numeric"})}function b(){c.clear()}export{b as clearLocaleNameCache,w as formatDateLabel,y as formatMonthLabel,g as formatYear,d as formatYearRange,p as getLocaleWeekStartsOn,D as getMonthNames,h as getWeekDayNames,o as resolveLocale};

package/dist/shared/core/color.d.ts

@@ -0,0 +1,80 @@
+/** 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`/`b` in `0–100` percent, `a` in `0–1`; `b` is brightness, not blue. */
+export interface HsbColor {
+    h: number;
+    s: number;
+    b: number;
+    a: number;
+}
+/** Serialisation targets for {@link formatColor}; `'hsb'` is this library's own notation, not CSS, so it round-trips through {@link parseColor} but must not go in a stylesheet. */
+export type ColorFormat = 'hex' | 'rgb' | 'hsl' | 'hsb';
+/**
+ * Serialises an sRGB colour as `#rrggbb`, or `#rrggbbaa` when `includeAlpha` is set, clamping and rounding channels so a computed colour with `r: 255.4` still produces valid hex.
+ *
+ * @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` into sRGB, returning `null` for anything else, including 5- and 7-digit strings that look like hex but aren't 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. */
+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, since the detour would quantise to 8 bits and flatten near-black hues. */
+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 (hex, `rgb()`, `hsl()`, or this library's own `hsb()`) into the canonical {@link HsbColor}, returning `null` rather than throwing for anything unrecognized, including named colours.
+ *
+ * @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`, omitting alpha only when it equals 1 unless `alpha: false` forces it off; round-trips through {@link parseColor} to the precision `format` can carry.
+ *
+ * @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/shared/core/color.js

@@ -0,0 +1 @@
+function s(n,r,t){return Math.min(Math.max(n,r),t)}function b(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 s(Math.round(n),0,255).toString(16).padStart(2,"0")}function $(n,r,t,e,o){if(!o)return 0;let u;return e===n?u=(r-t)/o:e===r?u=(t-n)/o+2:u=(n-r)/o+4,i(u*60)}function d(n,r,t,e,o){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,a,x]=l[u]??[0,0,0];return{r:b((c+e)*255),g:b((a+e)*255),b:b((x+e)*255),a:o}}function M(n,r=!1){let t=`#${m(n.r)}${m(n.g)}${m(n.b)}`;return r?`${t}${m(s(n.a,0,1)*255)}`:t}var R=/^#?([\da-f]{3,8})$/i;function T(n){let r=R.exec(n.trim());if(!r)return null;let t=r[1];if((t.length===3||t.length===4)&&(t=t.split("").map(o=>o+o).join("")),t.length!==6&&t.length!==8)return null;let e=o=>parseInt(t.slice(o,o+2),16);return{r:e(0),g:e(2),b:e(4),a:t.length===8?b(e(6)/255,3):1}}function H(n){let r=s(n.r,0,255)/255,t=s(n.g,0,255)/255,e=s(n.b,0,255)/255,o=Math.max(r,t,e),u=o-Math.min(r,t,e);return{h:$(r,t,e,o,u),s:o?u/o*100:0,b:o*100,a:s(n.a,0,1)}}function C(n){let r=i(n.h),t=s(n.s,0,100)/100,e=s(n.b,0,100)/100,o=e*t,u=o*(1-Math.abs(r/60%2-1));return d(r,o,u,e-o,s(n.a,0,1))}function A(n){let r=s(n.r,0,255)/255,t=s(n.g,0,255)/255,e=s(n.b,0,255)/255,o=Math.max(r,t,e),u=Math.min(r,t,e),l=o-u,c=(o+u)/2,a=l?l/(1-Math.abs(2*c-1)):0;return{h:$(r,t,e,o,l),s:s(a*100,0,100),l:c*100,a:s(n.a,0,1)}}function E(n){let r=i(n.h),t=s(n.s,0,100)/100,e=s(n.l,0,100)/100,o=(1-Math.abs(2*e-1))*t,u=o*(1-Math.abs(r/60%2-1));return d(r,o,u,e-o/2,s(n.a,0,1))}function v(n){let r=s(n.s,0,100)/100,t=s(n.b,0,100)/100,e=t*(1-r/2),o=Math.min(e,1-e);return{h:i(n.h),s:o?(t-e)/o*100:0,l:e*100,a:s(n.a,0,1)}}function F(n){let r=s(n.s,0,100)/100,t=s(n.l,0,100)/100,e=t+r*Math.min(t,1-t);return{h:i(n.h),s:e?2*(1-t/e)*100:0,b:e*100,a:s(n.a,0,1)}}var N=/^(rgba?|hsla?|hsba?|hsva?)\(([^()]*)\)$/;function p(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 e=Number(t);return Number.isFinite(e)?{value:e,percent:r}:null}function h(n){let r=p(n);return r&&(r.percent?r.value/100*255:r.value)}function g(n){let r=p(n);return r&&r.value}function y(n){if(n===void 0)return 1;let r=p(n);return r&&(r.percent?r.value/100:r.value)}function f(n){return{h:b(i(n.h),2),s:b(s(n.s,0,100),2),b:b(s(n.b,0,100),2),a:b(s(n.a,0,1),3)}}function P(n){if(typeof n!="string")return null;let r=n.trim().toLowerCase();if(!r)return null;let t=N.exec(r);if(!t){let u=T(r);return u?f(H(u)):null}let e=t[1].replace(/a$/,""),o=t[2].replace(/\//g," ").split(/[\s,]+/).filter(Boolean);return o.length!==3&&o.length!==4?null:O(e,o)}function O(n,r){let t=y(r[3]);if(t===null)return null;if(n==="rgb"){let l=h(r[0]),c=h(r[1]),a=h(r[2]);return l===null||c===null||a===null?null:f(H({r:l,g:c,b:a,a:t}))}let e=g(r[0]),o=g(r[1]),u=g(r[2]);return e===null||o===null||u===null?null:f(n==="hsl"?F({h:e,s:o,l:u,a:t}):{h:e,s:o,b:u,a:t})}function w(n,r,t=!0){let e=b(s(n.a,0,1),3),o=t&&e<1;if(r==="rgb"){let{r:u,g:l,b:c}=C(n);return o?`rgba(${u}, ${l}, ${c}, ${e})`:`rgb(${u}, ${l}, ${c})`}if(r==="hsl"){let u=v(n),l=b(u.h),c=b(u.s),a=b(u.l);return o?`hsla(${l}, ${c}%, ${a}%, ${e})`:`hsl(${l}, ${c}%, ${a}%)`}if(r==="hsb"){let u=b(i(n.h)),l=b(s(n.s,0,100)),c=b(s(n.b,0,100));return o?`hsba(${u}, ${l}%, ${c}%, ${e})`:`hsb(${u}, ${l}%, ${c}%)`}return M(C(n),o)}export{w as formatColor,T as hexToRgb,v as hsbToHsl,C as hsbToRgb,F as hslToHsb,E as hslToRgb,P as parseColor,M as rgbToHex,H as rgbToHsb,A as rgbToHsl};

package/dist/shared/core/controllable.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Whether two values are indistinguishable to a consumer, so no event is owed: `Object.is` for scalars, element-wise for the string arrays a selection carries.
+ *
+ * @param a the value now
+ * @param b the value proposed
+ */
+export declare function sameControlledValue(a: unknown, b: unknown): boolean;
+/** What the adapter currently holds on both sides of the controlled/uncontrolled split. */
+export interface ControllableState<T> {
+    /** The consumer's controlled value; `undefined` means the control owns its own value. */
+    controlled: T | undefined;
+    /** The value the adapter holds while uncontrolled; ignored once `controlled` is defined. */
+    uncontrolled: T | undefined;
+}
+/** What the adapter should do about a proposed change. */
+export interface ControllableDecision<T> {
+    /** The value in force after this decision — the proposal, or the current value when nothing changed. */
+    value: T | undefined;
+    /** Whether the adapter writes its own state; always `false` while controlled, since the consumer owns the value. */
+    write: boolean;
+    /** Whether the change event fires; only on an actual change, in both modes. */
+    emit: boolean;
+}
+/** The value in force: the controlled one when there is one, the adapter's own otherwise. */
+export declare function controllableValue<T>({ controlled, uncontrolled, }: ControllableState<T>): T | undefined;
+/** Whether the consumer owns the value, which is exactly "a controlled value was supplied". */
+export declare function isControlled<T>({ controlled }: ControllableState<T>): boolean;
+/**
+ * The decision for one proposed change.
+ *
+ * @param state what the adapter holds on both sides
+ * @param next the proposed value
+ * @returns the value in force, whether to write it, and whether to emit
+ */
+export declare function decideControllable<T>(state: ControllableState<T>, next: T | undefined): ControllableDecision<T>;
+/**
+ * The decision for a form reset, which restores `defaultValue` as it reads *now* — a consumer that changed the prop after mount expects the new default back, not the one the control was born with.
+ *
+ * @param state what the adapter holds on both sides
+ * @param liveDefault the `defaultValue` prop read at reset time
+ */
+export declare function decideReset<T>(state: ControllableState<T>, liveDefault: T | undefined): ControllableDecision<T>;

package/dist/shared/core/controllable.js

@@ -0,0 +1 @@
+import{sameSelection as t}from"./selection.js";function o(e,n){return Object.is(e,n)?!0:!Array.isArray(e)||!Array.isArray(n)||!e.every(r=>typeof r=="string")||!n.every(r=>typeof r=="string")?!1:t(e,n)}function l({controlled:e,uncontrolled:n}){return e!==void 0?e:n}function i({controlled:e}){return e!==void 0}function u(e,n){let r=l(e);return o(r,n)?{value:r,write:!1,emit:!1}:{value:n,write:!i(e),emit:!0}}function f(e,n){return u(e,n)}export{l as controllableValue,u as decideControllable,f as decideReset,i as isControlled,o as sameControlledValue};

package/dist/shared/core/csv.d.ts

@@ -0,0 +1,43 @@
+/** One output column: the row key to read and, optionally, the header text to print instead of the key. */
+export interface CsvColumn<Row> {
+    /** Property of each row whose value fills this column. */
+    key: keyof Row & string;
+    /**
+     * Header cell text.
+     *
+     * @default the key itself
+     */
+    label?: string | undefined;
+}
+/** Output options for {@link toCsv}; every field has a working default. */
+export interface CsvOptions<Row> {
+    /**
+     * Columns to emit, in order; omit to emit every key of the first row.
+     *
+     * @default Object.keys(rows[0])
+     */
+    columns?: readonly (CsvColumn<Row> | (keyof Row & string))[] | undefined;
+    /**
+     * Field separator.
+     *
+     * @default ','
+     */
+    delimiter?: string | undefined;
+    /**
+     * Whether the first line is the header row.
+     *
+     * @default true
+     */
+    header?: boolean | undefined;
+}
+/**
+ * Serialises rows to RFC 4180 CSV text — CRLF line ends, fields quoted only when
+ * they contain the delimiter, a quote or a line break — ready for a Blob or a
+ * data: URL. Dates print as ISO 8601; null and undefined print as empty fields.
+ *
+ * @example
+ * ```ts
+ * toCsv(rows, { columns: [{ key: 'name', label: 'Name' }, 'amount'] });
+ * ```
+ */
+export declare function toCsv<Row extends object>(rows: readonly Row[], options?: CsvOptions<Row>): string;

package/dist/shared/core/csv.js

@@ -0,0 +1,2 @@
+function g(n){return n==null?"":n instanceof Date?n.toISOString():typeof n=="string"?n:typeof n=="number"||typeof n=="boolean"||typeof n=="bigint"?String(n):JSON.stringify(n)??""}function f(n,o){let e=g(n);return/["\r\n]/.test(e)||e.includes(o)?`"${e.replace(/"/g,'""')}"`:e}function c(n,o={}){let e=o.delimiter??",",s=n[0],r=(o.columns??(s?Object.keys(s):[])).map(t=>typeof t=="string"?{key:t}:t),i=[];o.header!==!1&&r.length&&i.push(r.map(t=>f(t.label??t.key,e)).join(e));for(let t of n)i.push(r.map(d=>f(t[d.key],e)).join(e));return i.join(`\r
+`)}export{c as toCsv};