@skdx/web-components 0.26.0

package/dist/collapsible/CollapsibleContent.d.cts

@@ -0,0 +1,24 @@
+import { LitElement } from 'lit';
+/**
+ * `<skdx-collapsible-content>` — panel controlled by a `<skdx-collapsible>`.
+ * Sets the `id` referenced by the trigger's `aria-controls`, `data-state`,
+ * `data-disabled`, and the `hidden` attribute while closed. Unlike a JS
+ * framework's conditional rendering, a `<skdx-collapsible-content>` written in
+ * markup is never unmounted by this element — it is always present in the
+ * DOM and only ever toggled via the `hidden` attribute (see `<skdx-tabs-content>`
+ * for the same convention). Must be used inside `<skdx-collapsible>`.
+ */
+export declare class SkdxCollapsibleContent extends LitElement {
+    static styles: import("lit").CSSResult;
+    private rootEl;
+    private readonly observer;
+    connectedCallback(): void;
+    disconnectedCallback(): void;
+    private _sync;
+    render(): import("lit").TemplateResult<1>;
+}
+declare global {
+    interface HTMLElementTagNameMap {
+        'skdx-collapsible-content': SkdxCollapsibleContent;
+    }
+}

package/dist/collapsible/CollapsibleContent.d.ts

@@ -0,0 +1,24 @@
+import { LitElement } from 'lit';
+/**
+ * `<skdx-collapsible-content>` — panel controlled by a `<skdx-collapsible>`.
+ * Sets the `id` referenced by the trigger's `aria-controls`, `data-state`,
+ * `data-disabled`, and the `hidden` attribute while closed. Unlike a JS
+ * framework's conditional rendering, a `<skdx-collapsible-content>` written in
+ * markup is never unmounted by this element — it is always present in the
+ * DOM and only ever toggled via the `hidden` attribute (see `<skdx-tabs-content>`
+ * for the same convention). Must be used inside `<skdx-collapsible>`.
+ */
+export declare class SkdxCollapsibleContent extends LitElement {
+    static styles: import("lit").CSSResult;
+    private rootEl;
+    private readonly observer;
+    connectedCallback(): void;
+    disconnectedCallback(): void;
+    private _sync;
+    render(): import("lit").TemplateResult<1>;
+}
+declare global {
+    interface HTMLElementTagNameMap {
+        'skdx-collapsible-content': SkdxCollapsibleContent;
+    }
+}

package/dist/collapsible/CollapsibleContent.js

@@ -0,0 +1,8 @@
+var a=Object.defineProperty;var c=Object.getOwnPropertyDescriptor;var n=(l,s,e,o)=>{for(var t=o>1?void 0:o?c(s,e):s,r=l.length-1,d;r>=0;r--)(d=l[r])&&(t=(o?d(s,e,t):d(t))||t);return o&&t&&a(s,e,t),t};import{css as b,html as h,LitElement as p}from"lit";import{customElement as v}from"../internal/define.js";var i=class extends p{constructor(){super(...arguments);this.rootEl=null;this.observer=new MutationObserver(()=>this._sync())}connectedCallback(){if(super.connectedCallback(),this.rootEl=this.closest("skdx-collapsible"),!this.rootEl)throw new Error("<skdx-collapsible-content> must be used inside <skdx-collapsible>.");this.observer.observe(this.rootEl,{attributeFilter:["open","disabled"]}),this._sync()}disconnectedCallback(){this.observer.disconnect(),super.disconnectedCallback()}_sync(){let e=this.rootEl;e&&(this.id||(this.id=e.contentId),this.setAttribute("data-state",e.open?"open":"closed"),e.disabled?this.setAttribute("data-disabled",""):this.removeAttribute("data-disabled"),e.open?this.removeAttribute("hidden"):this.setAttribute("hidden",""))}render(){return h`<slot></slot>`}};i.styles=b`
+    :host {
+      display: block;
+    }
+    :host([hidden]) {
+      display: none;
+    }
+  `,i=n([v("skdx-collapsible-content","collapsible","content")],i);export{i as SkdxCollapsibleContent};

package/dist/collapsible/CollapsibleTrigger.cjs

@@ -0,0 +1,18 @@
+"use strict";var d=Object.defineProperty;var p=Object.getOwnPropertyDescriptor;var v=Object.getOwnPropertyNames;var m=Object.prototype.hasOwnProperty;var E=(s,t)=>{for(var e in t)d(s,e,{get:t[e],enumerable:!0})},f=(s,t,e,l)=>{if(t&&typeof t=="object"||typeof t=="function")for(let o of v(t))!m.call(s,o)&&o!==e&&d(s,o,{get:()=>t[o],enumerable:!(l=p(t,o))||l.enumerable});return s};var k=s=>f(d({},"__esModule",{value:!0}),s),b=(s,t,e,l)=>{for(var o=l>1?void 0:l?p(t,e):t,n=s.length-1,c;n>=0;n--)(c=s[n])&&(o=(l?c(t,e,o):c(o))||o);return l&&o&&d(t,e,o),o};var x={};E(x,{SkdxCollapsibleTrigger:()=>i});module.exports=k(x);var r=require("lit"),h=require("../internal/define.cjs"),u=require("../internal/part.cjs"),a=require("../internal/styles.cjs");var i=class extends r.LitElement{constructor(){super(...arguments);this.rootEl=null;this.observer=new MutationObserver(()=>this.requestUpdate());this.handleClick=()=>{let e=this.rootEl;!e||e.disabled||e.setOpen(!e.open)}}connectedCallback(){if(super.connectedCallback(),this.rootEl=this.closest("skdx-collapsible"),!this.rootEl)throw new Error("<skdx-collapsible-trigger> must be used inside <skdx-collapsible>.");this.observer.observe(this.rootEl,{attributeFilter:["open","disabled"]})}disconnectedCallback(){this.observer.disconnect(),super.disconnectedCallback()}updated(){(0,u.reflectHostState)(this,{"data-state":this.rootEl?.open??!1?"open":"closed","data-disabled":this.rootEl?.disabled?"":null})}render(){let e=this.rootEl?.open??!1,l=this.rootEl?.disabled??!1;return r.html`
+      <button
+        part="trigger"
+        type="button"
+        aria-controls=${this.rootEl?.contentId??r.nothing}
+        aria-expanded=${e}
+        data-state=${e?"open":"closed"}
+        data-disabled=${l?"":r.nothing}
+        ?disabled=${l}
+        @click=${this.handleClick}
+      >
+        <slot></slot>
+      </button>
+    `}};i.shadowRootOptions=a.delegatesFocusShadowRootOptions,i.styles=[a.resetNativeControl,r.css`
+      :host {
+        display: inline-block;
+      }
+    `,a.controlBoxOnHost],i=b([(0,h.customElement)("skdx-collapsible-trigger","collapsible","trigger")],i);0&&(module.exports={SkdxCollapsibleTrigger});

package/dist/collapsible/CollapsibleTrigger.d.cts

@@ -0,0 +1,24 @@
+import { LitElement } from 'lit';
+/**
+ * `<skdx-collapsible-trigger>` — button that toggles the content open/closed
+ * when clicked. Sets `aria-controls`, `aria-expanded`, `data-state` and
+ * `data-disabled`. Must be used inside `<skdx-collapsible>`.
+ *
+ * @csspart trigger - The native `<button>` element inside the shadow root.
+ */
+export declare class SkdxCollapsibleTrigger extends LitElement {
+    static shadowRootOptions: ShadowRootInit;
+    static styles: import("lit").CSSResult[];
+    private rootEl;
+    private readonly observer;
+    connectedCallback(): void;
+    disconnectedCallback(): void;
+    private readonly handleClick;
+    protected updated(): void;
+    render(): import("lit").TemplateResult<1>;
+}
+declare global {
+    interface HTMLElementTagNameMap {
+        'skdx-collapsible-trigger': SkdxCollapsibleTrigger;
+    }
+}

package/dist/collapsible/CollapsibleTrigger.d.ts

@@ -0,0 +1,24 @@
+import { LitElement } from 'lit';
+/**
+ * `<skdx-collapsible-trigger>` — button that toggles the content open/closed
+ * when clicked. Sets `aria-controls`, `aria-expanded`, `data-state` and
+ * `data-disabled`. Must be used inside `<skdx-collapsible>`.
+ *
+ * @csspart trigger - The native `<button>` element inside the shadow root.
+ */
+export declare class SkdxCollapsibleTrigger extends LitElement {
+    static shadowRootOptions: ShadowRootInit;
+    static styles: import("lit").CSSResult[];
+    private rootEl;
+    private readonly observer;
+    connectedCallback(): void;
+    disconnectedCallback(): void;
+    private readonly handleClick;
+    protected updated(): void;
+    render(): import("lit").TemplateResult<1>;
+}
+declare global {
+    interface HTMLElementTagNameMap {
+        'skdx-collapsible-trigger': SkdxCollapsibleTrigger;
+    }
+}

package/dist/collapsible/CollapsibleTrigger.js

@@ -0,0 +1,18 @@
+var c=Object.defineProperty;var p=Object.getOwnPropertyDescriptor;var d=(r,l,e,t)=>{for(var o=t>1?void 0:t?p(l,e):l,i=r.length-1,a;i>=0;i--)(a=r[i])&&(o=(t?a(l,e,o):a(o))||o);return t&&o&&c(l,e,o),o};import{css as b,html as h,LitElement as u,nothing as n}from"lit";import{customElement as v}from"../internal/define.js";import{reflectHostState as m}from"../internal/part.js";import{controlBoxOnHost as E,delegatesFocusShadowRootOptions as f,resetNativeControl as k}from"../internal/styles.js";var s=class extends u{constructor(){super(...arguments);this.rootEl=null;this.observer=new MutationObserver(()=>this.requestUpdate());this.handleClick=()=>{let e=this.rootEl;!e||e.disabled||e.setOpen(!e.open)}}connectedCallback(){if(super.connectedCallback(),this.rootEl=this.closest("skdx-collapsible"),!this.rootEl)throw new Error("<skdx-collapsible-trigger> must be used inside <skdx-collapsible>.");this.observer.observe(this.rootEl,{attributeFilter:["open","disabled"]})}disconnectedCallback(){this.observer.disconnect(),super.disconnectedCallback()}updated(){m(this,{"data-state":this.rootEl?.open??!1?"open":"closed","data-disabled":this.rootEl?.disabled?"":null})}render(){let e=this.rootEl?.open??!1,t=this.rootEl?.disabled??!1;return h`
+      <button
+        part="trigger"
+        type="button"
+        aria-controls=${this.rootEl?.contentId??n}
+        aria-expanded=${e}
+        data-state=${e?"open":"closed"}
+        data-disabled=${t?"":n}
+        ?disabled=${t}
+        @click=${this.handleClick}
+      >
+        <slot></slot>
+      </button>
+    `}};s.shadowRootOptions=f,s.styles=[k,b`
+      :host {
+        display: inline-block;
+      }
+    `,E],s=d([v("skdx-collapsible-trigger","collapsible","trigger")],s);export{s as SkdxCollapsibleTrigger};

package/dist/collapsible/index.cjs

@@ -0,0 +1 @@
+"use strict";var p=Object.defineProperty;var a=Object.getOwnPropertyDescriptor;var b=Object.getOwnPropertyNames;var d=Object.prototype.hasOwnProperty;var f=(l,o)=>{for(var r in o)p(l,r,{get:o[r],enumerable:!0})},k=(l,o,r,x)=>{if(o&&typeof o=="object"||typeof o=="function")for(let e of b(o))!d.call(l,e)&&e!==r&&p(l,e,{get:()=>o[e],enumerable:!(x=a(o,e))||x.enumerable});return l};var m=l=>k(p({},"__esModule",{value:!0}),l);var s={};f(s,{SkdxCollapsible:()=>t.SkdxCollapsible,SkdxCollapsibleContent:()=>C.SkdxCollapsibleContent,SkdxCollapsibleTrigger:()=>i.SkdxCollapsibleTrigger});module.exports=m(s);var t=require("./Collapsible.cjs"),i=require("./CollapsibleTrigger.cjs"),C=require("./CollapsibleContent.cjs");0&&(module.exports={SkdxCollapsible,SkdxCollapsibleContent,SkdxCollapsibleTrigger});

package/dist/collapsible/index.d.cts

@@ -0,0 +1,3 @@
+export { SkdxCollapsible } from './Collapsible.cjs';
+export { SkdxCollapsibleTrigger } from './CollapsibleTrigger.cjs';
+export { SkdxCollapsibleContent } from './CollapsibleContent.cjs';

package/dist/collapsible/index.d.ts

@@ -0,0 +1,3 @@
+export { SkdxCollapsible } from './Collapsible.js';
+export { SkdxCollapsibleTrigger } from './CollapsibleTrigger.js';
+export { SkdxCollapsibleContent } from './CollapsibleContent.js';

package/dist/collapsible/index.js

@@ -0,0 +1 @@
+import{SkdxCollapsible as e}from"./Collapsible.js";import{SkdxCollapsibleTrigger as p}from"./CollapsibleTrigger.js";import{SkdxCollapsibleContent as t}from"./CollapsibleContent.js";export{e as SkdxCollapsible,t as SkdxCollapsibleContent,p as SkdxCollapsibleTrigger};

package/dist/color-picker/ColorPicker.cjs

@@ -0,0 +1,5 @@
+"use strict";var n=Object.defineProperty;var m=Object.getOwnPropertyDescriptor;var y=Object.getOwnPropertyNames;var k=Object.prototype.hasOwnProperty;var g=(a,o)=>{for(var t in o)n(a,t,{get:o[t],enumerable:!0})},E=(a,o,t,e)=>{if(o&&typeof o=="object"||typeof o=="function")for(let r of y(o))!k.call(a,r)&&r!==t&&n(a,r,{get:()=>o[r],enumerable:!(e=m(o,r))||e.enumerable});return a};var w=a=>E(n({},"__esModule",{value:!0}),a),i=(a,o,t,e)=>{for(var r=e>1?void 0:e?m(o,t):o,p=a.length-1,d;p>=0;p--)(d=a[p])&&(r=(e?d(o,t,r):d(r))||r);return e&&r&&n(o,t,r),r};var C={};g(C,{SkdxColorPicker:()=>s});module.exports=w(C);var h=require("lit"),l=require("lit/decorators.js"),u=require("../internal/color.cjs"),b=require("../internal/define.cjs"),f=require("../internal/positioning.cjs"),v=require("../utils/live-announcer.cjs");var x=["skdx-color-picker-area","skdx-color-picker-area-thumb","skdx-color-picker-hue-slider","skdx-color-picker-hue-slider-thumb","skdx-color-picker-alpha-slider","skdx-color-picker-alpha-slider-thumb","skdx-color-picker-swatch-group","skdx-color-picker-swatch","skdx-color-picker-input","skdx-color-picker-format-select","skdx-color-picker-eye-dropper"].join(", "),A={h:0,s:0,b:0,a:1};function c(a){return Math.round(a*1e3)/1e3}var s=class extends h.LitElement{constructor(){super(...arguments);this.value="#000000";this.defaultValue="#000000";this.format="hex";this.defaultFormat="hex";this.alpha=!0;this.step=1;this.disabled=!1;this.readOnly=!1;this.color=A;this.ownValue=""}get interactive(){return!this.disabled&&!this.readOnly}connectedCallback(){super.connectedCallback(),this.hasAttribute("value")||(this.value=this.defaultValue),this.hasAttribute("format")||(this.format=this.defaultFormat)}willUpdate(t){if(t.has("value")&&this.value!==this.ownValue){this.ownValue=this.value;let e=(0,u.parseColor)(this.value);e&&(this.color=e)}}updated(){this.syncHostAttributes();for(let t of Array.from(this.querySelectorAll(x)))t.syncFromRoot?.()}syncHostAttributes(){let t=this.color;this.setAttribute("data-value",this.value),this.setAttribute("data-format",this.format),this.toggleAttribute("data-disabled",this.disabled),this.toggleAttribute("data-readonly",this.readOnly),this.style.setProperty("--skdx-color-picker-hue",`${c(t.h)}deg`),this.style.setProperty("--skdx-color-picker-hue-position",`${c(t.h/360*100)}%`),this.style.setProperty("--skdx-color-picker-saturation",`${c(t.s)}%`),this.style.setProperty("--skdx-color-picker-brightness",`${c(t.b)}%`),this.style.setProperty("--skdx-color-picker-alpha",String(c(t.a))),this.style.setProperty("--skdx-color-picker-alpha-position",`${c(t.a*100)}%`),this.style.setProperty("--skdx-color-picker-value",(0,u.formatColor)(t,"hex",this.alpha))}describe(t){let e=(0,u.formatColor)(t,"hex",!1);return this.alpha&&t.a<1?`${e}, ${Math.round(t.a*100)}% opaque`:e}setColor(t,e){if(!this.interactive)return;let r=(0,u.formatColor)(t,this.format,this.alpha);this.color=t,this.ownValue=r,r!==this.value&&(this.value=r,this.dispatchEvent(new CustomEvent("value-change",{detail:r,bubbles:!0,composed:!0}))),e?.announce&&(0,v.announce)(this.describe(t))}setFormat(t){if(!this.interactive||t===this.format)return;this.format=t,this.dispatchEvent(new CustomEvent("format-change",{detail:t,bubbles:!0,composed:!0}));let e=(0,u.formatColor)(this.color,t,this.alpha);this.ownValue=e,e!==this.value&&(this.value=e,this.dispatchEvent(new CustomEvent("value-change",{detail:e,bubbles:!0,composed:!0})))}commit(){this.dispatchEvent(new CustomEvent("value-commit",{detail:this.value,bubbles:!0,composed:!0}))}render(){return h.html`<slot></slot>`}};s.styles=h.css`
+    :host {
+      display: block;
+    }
+  `,i([(0,l.property)({type:String,reflect:!0})],s.prototype,"value",2),i([(0,l.property)({type:String,attribute:"default-value"})],s.prototype,"defaultValue",2),i([(0,l.property)({type:String,reflect:!0})],s.prototype,"format",2),i([(0,l.property)({type:String,attribute:"default-format"})],s.prototype,"defaultFormat",2),i([(0,l.property)({converter:f.optOutBoolean})],s.prototype,"alpha",2),i([(0,l.property)({type:Number,reflect:!0})],s.prototype,"step",2),i([(0,l.property)({type:Boolean,reflect:!0})],s.prototype,"disabled",2),i([(0,l.property)({type:Boolean,reflect:!0,attribute:"read-only"})],s.prototype,"readOnly",2),i([(0,l.state)()],s.prototype,"color",2),s=i([(0,b.customElement)("skdx-color-picker","color-picker","root")],s);0&&(module.exports={SkdxColorPicker});

package/dist/color-picker/ColorPicker.d.cts

@@ -0,0 +1,192 @@
+import { LitElement, type PropertyValues } from 'lit';
+import { type ColorFormat, type HsbColor } from '../internal/color.cjs';
+/**
+ * `<skdx-color-picker>` — the Web Components implementation of the shared
+ * ColorPicker contract (see `@skdx/shared`'s `colorPickerContract`). Owns the
+ * colour, owns the notation it is spelled in, and publishes both to every part
+ * and to CSS through custom properties. The host carries **no role of its
+ * own** — each interactive part carries its own semantics, so a role here would
+ * only add an unnamed group between the user and them. Wrap it in a labelled
+ * `role="group"` yourself if the picker needs introducing as a unit.
+ *
+ * **The colour is stored as HSB, not as the string.** RGB and hex cannot
+ * represent the hue of a black, so a picker that re-parsed its own string on
+ * every change would lose the user's hue the moment they dragged brightness to
+ * zero and hand them red on the way back up. `value` is the *serialisation*;
+ * the canonical colour lives beside it and only re-syncs when a string arrives
+ * that this picker did not produce. An unparseable `value` keeps the last good
+ * colour rather than blanking the picker — `#ab` is one keystroke from valid.
+ *
+ * Positioning is entirely CSS. The host publishes:
+ *
+ * | Property | Example | For |
+ * | --- | --- | --- |
+ * | `--skdx-color-picker-hue` | `210deg` | the area's hue backdrop, `hsl(var(--…-hue) 100% 50%)` |
+ * | `--skdx-color-picker-hue-position` | `58.333%` | the hue thumb's offset along its track |
+ * | `--skdx-color-picker-saturation` | `65%` | the area thumb's horizontal offset |
+ * | `--skdx-color-picker-brightness` | `85%` | the area thumb's vertical offset |
+ * | `--skdx-color-picker-alpha` | `0.5` | an opacity, directly |
+ * | `--skdx-color-picker-alpha-position` | `50%` | the alpha thumb's offset along its track |
+ * | `--skdx-color-picker-value` | `#d94c4c` | the current colour as a swatch fill |
+ *
+ * `--skdx-color-picker-value` is **always hex**, never the active format:
+ * `hsb()` is this library's own notation and not a CSS colour, so publishing
+ * the raw `value` would silently break every
+ * `background: var(--skdx-color-picker-value)` the moment a user switched
+ * format.
+ *
+ * Descendant parts find this root with `closest('skdx-color-picker')` — custom
+ * elements have no context API — and the root pushes its state onto them after
+ * every update, so no part duplicates it.
+ *
+ * Not a form control in itself: the colour is submitted by the consumer,
+ * typically through a hidden input carrying the emitted string.
+ *
+ * **An overlay picker composes `<skdx-popover>`** rather than growing a trigger
+ * and a content part of its own — there is nothing about positioning a colour
+ * picker that differs from positioning anything else.
+ *
+ * @example
+ * ```html
+ * <skdx-color-picker default-value="#3b82f6">
+ *   <skdx-color-picker-area>
+ *     <skdx-color-picker-area-thumb></skdx-color-picker-area-thumb>
+ *   </skdx-color-picker-area>
+ *   <skdx-color-picker-hue-slider>
+ *     <skdx-color-picker-hue-slider-thumb></skdx-color-picker-hue-slider-thumb>
+ *   </skdx-color-picker-hue-slider>
+ *   <skdx-color-picker-alpha-slider>
+ *     <skdx-color-picker-alpha-slider-thumb></skdx-color-picker-alpha-slider-thumb>
+ *   </skdx-color-picker-alpha-slider>
+ *   <skdx-color-picker-format-select></skdx-color-picker-format-select>
+ *   <skdx-color-picker-input></skdx-color-picker-input>
+ *   <skdx-color-picker-eye-dropper>🔍</skdx-color-picker-eye-dropper>
+ * </skdx-color-picker>
+ * ```
+ *
+ * @fires value-change - Fires with the new colour string on every change: each arrow key, each frame of a drag that moves the colour, each swatch click — and also on a format change, because the string genuinely changed even though the colour did not. Suppressed when the new string equals the one already reported.
+ * @fires value-commit - Fires once with the final colour string (string) when a pointer drag ends, by release or cancel. This is the event to hang an expensive effect on: a drag emits `value-change` per frame and this one exactly once. Keyboard and click changes do not fire it — each is already a discrete commit reported by `value-change`.
+ * @fires format-change - Fires with the new notation (`'hex' | 'rgb' | 'hsl' | 'hsb'`) whenever it changes. `value-change` fires alongside it with the re-spelled string.
+ */
+export declare class SkdxColorPicker extends LitElement {
+    static styles: import("lit").CSSResult;
+    /**
+     * Current colour as a string in the active `format`. The property is the
+     * single source of truth, like a native `<input>`'s `value`: a consumer that
+     * wants controlled behaviour listens for `value-change` and writes it back.
+     * Anything {@link parseColor} understands is accepted regardless of `format`.
+     * @default '#000000' — opaque black, the one colour every format agrees on.
+     * An unparseable string is ignored and the last good colour kept, because a
+     * half-typed `#ab` should not blank the picker.
+     */
+    value: string;
+    /**
+     * Initial colour, for uncontrolled usage. Applied once, on connect, and only
+     * if the `value` attribute wasn't already set.
+     * @default '#000000' — the picker starts on opaque black.
+     */
+    defaultValue: string;
+    /**
+     * Notation `value` is written in. The colour itself is stored as HSB whatever
+     * this says; the format only decides how it is spelled on the way out.
+     * @default 'hex' — the notation people paste, type and recognise.
+     */
+    format: ColorFormat;
+    /**
+     * Initial notation, for uncontrolled usage. Applied once, on connect, and
+     * only if the `format` attribute wasn't already set.
+     * @default 'hex' — the picker starts spelling its colour as hex.
+     */
+    defaultFormat: ColorFormat;
+    /**
+     * Whether the picker has an alpha channel. With it off,
+     * `<skdx-color-picker-alpha-slider>` hides itself and every emitted string is
+     * fully opaque — so a consumer that cannot handle transparency never receives
+     * an `rgba()` it must strip.
+     *
+     * Uses the `optOutBoolean` converter rather than Lit's stock `Boolean`, which
+     * reads attribute *presence*: a prop that defaults to `true` can only be
+     * switched off by value, so `alpha="false"` is the way to opt out.
+     * @default true — the picker offers transparency.
+     */
+    alpha: boolean;
+    /**
+     * Keyboard increment, in the units of whichever channel is being stepped:
+     * percentage points for saturation, brightness and alpha, degrees for hue.
+     * Shift multiplies it by ten, so a 1-unit picker still has a coarse gear.
+     * @default 1 — every whole unit is reachable without a pointer. `0` makes
+     * pointer input continuous, while the arrows keep falling back to one unit so
+     * every value stays reachable by keyboard.
+     */
+    step: number;
+    /**
+     * Blocks pointer and keyboard interaction across every part, and takes the
+     * focusable parts out of the tab order.
+     * @default false — the picker is interactive and in the tab order.
+     */
+    disabled: boolean;
+    /**
+     * Displays the colour but blocks changes, while every part stays focusable
+     * and in the tab order — unlike `disabled`, a read-only picker can still be
+     * reached and read by a keyboard user. It also refuses a format switch,
+     * because switching format changes `value`.
+     * @default false — changes are accepted.
+     */
+    readOnly: boolean;
+    /**
+     * @internal The canonical colour. HSB, so hue survives a trip to black.
+     * Read by every part through `closest('skdx-color-picker')`; written only by
+     * {@link setColor}.
+     */
+    color: HsbColor;
+    /** @internal The last string this picker produced itself; anything else in `value` arrived from outside. */
+    private ownValue;
+    /** `!disabled && !readOnly` — the single condition every part gates input on. @internal */
+    get interactive(): boolean;
+    connectedCallback(): void;
+    protected willUpdate(changed: PropertyValues): void;
+    protected updated(): void;
+    private syncHostAttributes;
+    /**
+     * What a change to this colour sounds like. Hex rather than the active
+     * format, because `hsb(210, 60%, 85%)` read aloud is three numbers and a unit
+     * nobody asked for, while a hex string is the one spelling a user is likely
+     * to recognise and repeat.
+     *
+     * @internal Used both as `aria-valuetext` on the channel sliders and as the
+     * body of the live announcement the swatch, eyedropper and input make.
+     */
+    describe(target: HsbColor): string;
+    /**
+     * @internal Applies a new colour and dispatches `value-change`. Called by
+     * every part. `announce` is for controls whose own role does not already
+     * speak the result — a swatch, the eyedropper, a committed input; the parts
+     * that carry `role="slider"` stay silent, because their own `aria-valuetext`
+     * already re-announces on every change and speaking again would say the
+     * colour twice per arrow key.
+     */
+    setColor(next: HsbColor, options?: {
+        announce?: boolean;
+    }): void;
+    /**
+     * @internal Switches the notation. The colour has not changed, but its
+     * spelling has — and `value` is a string, so a format switch is a value
+     * change to every consumer of it, and `value-change` fires alongside
+     * `format-change`. A read-only picker refuses, for exactly that reason.
+     */
+    setFormat(next: ColorFormat): void;
+    /**
+     * @internal Dispatches `value-commit` with the value as it currently stands.
+     * Called once by the area and the two tracks at the end of a pointer drag —
+     * never suppressed, because a commit is an action, not a state change: a
+     * consumer waiting for the end of a drag must hear about it even when the
+     * drag put the colour back where it started.
+     */
+    commit(): void;
+    render(): import("lit").TemplateResult<1>;
+}
+declare global {
+    interface HTMLElementTagNameMap {
+        'skdx-color-picker': SkdxColorPicker;
+    }
+}

package/dist/color-picker/ColorPicker.d.ts

@@ -0,0 +1,192 @@
+import { LitElement, type PropertyValues } from 'lit';
+import { type ColorFormat, type HsbColor } from '../internal/color.js';
+/**
+ * `<skdx-color-picker>` — the Web Components implementation of the shared
+ * ColorPicker contract (see `@skdx/shared`'s `colorPickerContract`). Owns the
+ * colour, owns the notation it is spelled in, and publishes both to every part
+ * and to CSS through custom properties. The host carries **no role of its
+ * own** — each interactive part carries its own semantics, so a role here would
+ * only add an unnamed group between the user and them. Wrap it in a labelled
+ * `role="group"` yourself if the picker needs introducing as a unit.
+ *
+ * **The colour is stored as HSB, not as the string.** RGB and hex cannot
+ * represent the hue of a black, so a picker that re-parsed its own string on
+ * every change would lose the user's hue the moment they dragged brightness to
+ * zero and hand them red on the way back up. `value` is the *serialisation*;
+ * the canonical colour lives beside it and only re-syncs when a string arrives
+ * that this picker did not produce. An unparseable `value` keeps the last good
+ * colour rather than blanking the picker — `#ab` is one keystroke from valid.
+ *
+ * Positioning is entirely CSS. The host publishes:
+ *
+ * | Property | Example | For |
+ * | --- | --- | --- |
+ * | `--skdx-color-picker-hue` | `210deg` | the area's hue backdrop, `hsl(var(--…-hue) 100% 50%)` |
+ * | `--skdx-color-picker-hue-position` | `58.333%` | the hue thumb's offset along its track |
+ * | `--skdx-color-picker-saturation` | `65%` | the area thumb's horizontal offset |
+ * | `--skdx-color-picker-brightness` | `85%` | the area thumb's vertical offset |
+ * | `--skdx-color-picker-alpha` | `0.5` | an opacity, directly |
+ * | `--skdx-color-picker-alpha-position` | `50%` | the alpha thumb's offset along its track |
+ * | `--skdx-color-picker-value` | `#d94c4c` | the current colour as a swatch fill |
+ *
+ * `--skdx-color-picker-value` is **always hex**, never the active format:
+ * `hsb()` is this library's own notation and not a CSS colour, so publishing
+ * the raw `value` would silently break every
+ * `background: var(--skdx-color-picker-value)` the moment a user switched
+ * format.
+ *
+ * Descendant parts find this root with `closest('skdx-color-picker')` — custom
+ * elements have no context API — and the root pushes its state onto them after
+ * every update, so no part duplicates it.
+ *
+ * Not a form control in itself: the colour is submitted by the consumer,
+ * typically through a hidden input carrying the emitted string.
+ *
+ * **An overlay picker composes `<skdx-popover>`** rather than growing a trigger
+ * and a content part of its own — there is nothing about positioning a colour
+ * picker that differs from positioning anything else.
+ *
+ * @example
+ * ```html
+ * <skdx-color-picker default-value="#3b82f6">
+ *   <skdx-color-picker-area>
+ *     <skdx-color-picker-area-thumb></skdx-color-picker-area-thumb>
+ *   </skdx-color-picker-area>
+ *   <skdx-color-picker-hue-slider>
+ *     <skdx-color-picker-hue-slider-thumb></skdx-color-picker-hue-slider-thumb>
+ *   </skdx-color-picker-hue-slider>
+ *   <skdx-color-picker-alpha-slider>
+ *     <skdx-color-picker-alpha-slider-thumb></skdx-color-picker-alpha-slider-thumb>
+ *   </skdx-color-picker-alpha-slider>
+ *   <skdx-color-picker-format-select></skdx-color-picker-format-select>
+ *   <skdx-color-picker-input></skdx-color-picker-input>
+ *   <skdx-color-picker-eye-dropper>🔍</skdx-color-picker-eye-dropper>
+ * </skdx-color-picker>
+ * ```
+ *
+ * @fires value-change - Fires with the new colour string on every change: each arrow key, each frame of a drag that moves the colour, each swatch click — and also on a format change, because the string genuinely changed even though the colour did not. Suppressed when the new string equals the one already reported.
+ * @fires value-commit - Fires once with the final colour string (string) when a pointer drag ends, by release or cancel. This is the event to hang an expensive effect on: a drag emits `value-change` per frame and this one exactly once. Keyboard and click changes do not fire it — each is already a discrete commit reported by `value-change`.
+ * @fires format-change - Fires with the new notation (`'hex' | 'rgb' | 'hsl' | 'hsb'`) whenever it changes. `value-change` fires alongside it with the re-spelled string.
+ */
+export declare class SkdxColorPicker extends LitElement {
+    static styles: import("lit").CSSResult;
+    /**
+     * Current colour as a string in the active `format`. The property is the
+     * single source of truth, like a native `<input>`'s `value`: a consumer that
+     * wants controlled behaviour listens for `value-change` and writes it back.
+     * Anything {@link parseColor} understands is accepted regardless of `format`.
+     * @default '#000000' — opaque black, the one colour every format agrees on.
+     * An unparseable string is ignored and the last good colour kept, because a
+     * half-typed `#ab` should not blank the picker.
+     */
+    value: string;
+    /**
+     * Initial colour, for uncontrolled usage. Applied once, on connect, and only
+     * if the `value` attribute wasn't already set.
+     * @default '#000000' — the picker starts on opaque black.
+     */
+    defaultValue: string;
+    /**
+     * Notation `value` is written in. The colour itself is stored as HSB whatever
+     * this says; the format only decides how it is spelled on the way out.
+     * @default 'hex' — the notation people paste, type and recognise.
+     */
+    format: ColorFormat;
+    /**
+     * Initial notation, for uncontrolled usage. Applied once, on connect, and
+     * only if the `format` attribute wasn't already set.
+     * @default 'hex' — the picker starts spelling its colour as hex.
+     */
+    defaultFormat: ColorFormat;
+    /**
+     * Whether the picker has an alpha channel. With it off,
+     * `<skdx-color-picker-alpha-slider>` hides itself and every emitted string is
+     * fully opaque — so a consumer that cannot handle transparency never receives
+     * an `rgba()` it must strip.
+     *
+     * Uses the `optOutBoolean` converter rather than Lit's stock `Boolean`, which
+     * reads attribute *presence*: a prop that defaults to `true` can only be
+     * switched off by value, so `alpha="false"` is the way to opt out.
+     * @default true — the picker offers transparency.
+     */
+    alpha: boolean;
+    /**
+     * Keyboard increment, in the units of whichever channel is being stepped:
+     * percentage points for saturation, brightness and alpha, degrees for hue.
+     * Shift multiplies it by ten, so a 1-unit picker still has a coarse gear.
+     * @default 1 — every whole unit is reachable without a pointer. `0` makes
+     * pointer input continuous, while the arrows keep falling back to one unit so
+     * every value stays reachable by keyboard.
+     */
+    step: number;
+    /**
+     * Blocks pointer and keyboard interaction across every part, and takes the
+     * focusable parts out of the tab order.
+     * @default false — the picker is interactive and in the tab order.
+     */
+    disabled: boolean;
+    /**
+     * Displays the colour but blocks changes, while every part stays focusable
+     * and in the tab order — unlike `disabled`, a read-only picker can still be
+     * reached and read by a keyboard user. It also refuses a format switch,
+     * because switching format changes `value`.
+     * @default false — changes are accepted.
+     */
+    readOnly: boolean;
+    /**
+     * @internal The canonical colour. HSB, so hue survives a trip to black.
+     * Read by every part through `closest('skdx-color-picker')`; written only by
+     * {@link setColor}.
+     */
+    color: HsbColor;
+    /** @internal The last string this picker produced itself; anything else in `value` arrived from outside. */
+    private ownValue;
+    /** `!disabled && !readOnly` — the single condition every part gates input on. @internal */
+    get interactive(): boolean;
+    connectedCallback(): void;
+    protected willUpdate(changed: PropertyValues): void;
+    protected updated(): void;
+    private syncHostAttributes;
+    /**
+     * What a change to this colour sounds like. Hex rather than the active
+     * format, because `hsb(210, 60%, 85%)` read aloud is three numbers and a unit
+     * nobody asked for, while a hex string is the one spelling a user is likely
+     * to recognise and repeat.
+     *
+     * @internal Used both as `aria-valuetext` on the channel sliders and as the
+     * body of the live announcement the swatch, eyedropper and input make.
+     */
+    describe(target: HsbColor): string;
+    /**
+     * @internal Applies a new colour and dispatches `value-change`. Called by
+     * every part. `announce` is for controls whose own role does not already
+     * speak the result — a swatch, the eyedropper, a committed input; the parts
+     * that carry `role="slider"` stay silent, because their own `aria-valuetext`
+     * already re-announces on every change and speaking again would say the
+     * colour twice per arrow key.
+     */
+    setColor(next: HsbColor, options?: {
+        announce?: boolean;
+    }): void;
+    /**
+     * @internal Switches the notation. The colour has not changed, but its
+     * spelling has — and `value` is a string, so a format switch is a value
+     * change to every consumer of it, and `value-change` fires alongside
+     * `format-change`. A read-only picker refuses, for exactly that reason.
+     */
+    setFormat(next: ColorFormat): void;
+    /**
+     * @internal Dispatches `value-commit` with the value as it currently stands.
+     * Called once by the area and the two tracks at the end of a pointer drag —
+     * never suppressed, because a commit is an action, not a state change: a
+     * consumer waiting for the end of a drag must hear about it even when the
+     * drag put the colour back where it started.
+     */
+    commit(): void;
+    render(): import("lit").TemplateResult<1>;
+}
+declare global {
+    interface HTMLElementTagNameMap {
+        'skdx-color-picker': SkdxColorPicker;
+    }
+}

package/dist/color-picker/ColorPicker.js

@@ -0,0 +1,5 @@
+var p=Object.defineProperty;var d=Object.getOwnPropertyDescriptor;var s=(l,u,t,e)=>{for(var o=e>1?void 0:e?d(u,t):u,h=l.length-1,n;h>=0;h--)(n=l[h])&&(o=(e?n(u,t,o):n(o))||o);return e&&o&&p(u,t,o),o};import{css as m,html as b,LitElement as f}from"lit";import{property as a,state as v}from"lit/decorators.js";import{formatColor as c,parseColor as y}from"../internal/color.js";import{customElement as k}from"../internal/define.js";import{optOutBoolean as g}from"../internal/positioning.js";import{announce as E}from"../utils/live-announcer.js";var w=["skdx-color-picker-area","skdx-color-picker-area-thumb","skdx-color-picker-hue-slider","skdx-color-picker-hue-slider-thumb","skdx-color-picker-alpha-slider","skdx-color-picker-alpha-slider-thumb","skdx-color-picker-swatch-group","skdx-color-picker-swatch","skdx-color-picker-input","skdx-color-picker-format-select","skdx-color-picker-eye-dropper"].join(", "),x={h:0,s:0,b:0,a:1};function i(l){return Math.round(l*1e3)/1e3}var r=class extends f{constructor(){super(...arguments);this.value="#000000";this.defaultValue="#000000";this.format="hex";this.defaultFormat="hex";this.alpha=!0;this.step=1;this.disabled=!1;this.readOnly=!1;this.color=x;this.ownValue=""}get interactive(){return!this.disabled&&!this.readOnly}connectedCallback(){super.connectedCallback(),this.hasAttribute("value")||(this.value=this.defaultValue),this.hasAttribute("format")||(this.format=this.defaultFormat)}willUpdate(t){if(t.has("value")&&this.value!==this.ownValue){this.ownValue=this.value;let e=y(this.value);e&&(this.color=e)}}updated(){this.syncHostAttributes();for(let t of Array.from(this.querySelectorAll(w)))t.syncFromRoot?.()}syncHostAttributes(){let t=this.color;this.setAttribute("data-value",this.value),this.setAttribute("data-format",this.format),this.toggleAttribute("data-disabled",this.disabled),this.toggleAttribute("data-readonly",this.readOnly),this.style.setProperty("--skdx-color-picker-hue",`${i(t.h)}deg`),this.style.setProperty("--skdx-color-picker-hue-position",`${i(t.h/360*100)}%`),this.style.setProperty("--skdx-color-picker-saturation",`${i(t.s)}%`),this.style.setProperty("--skdx-color-picker-brightness",`${i(t.b)}%`),this.style.setProperty("--skdx-color-picker-alpha",String(i(t.a))),this.style.setProperty("--skdx-color-picker-alpha-position",`${i(t.a*100)}%`),this.style.setProperty("--skdx-color-picker-value",c(t,"hex",this.alpha))}describe(t){let e=c(t,"hex",!1);return this.alpha&&t.a<1?`${e}, ${Math.round(t.a*100)}% opaque`:e}setColor(t,e){if(!this.interactive)return;let o=c(t,this.format,this.alpha);this.color=t,this.ownValue=o,o!==this.value&&(this.value=o,this.dispatchEvent(new CustomEvent("value-change",{detail:o,bubbles:!0,composed:!0}))),e?.announce&&E(this.describe(t))}setFormat(t){if(!this.interactive||t===this.format)return;this.format=t,this.dispatchEvent(new CustomEvent("format-change",{detail:t,bubbles:!0,composed:!0}));let e=c(this.color,t,this.alpha);this.ownValue=e,e!==this.value&&(this.value=e,this.dispatchEvent(new CustomEvent("value-change",{detail:e,bubbles:!0,composed:!0})))}commit(){this.dispatchEvent(new CustomEvent("value-commit",{detail:this.value,bubbles:!0,composed:!0}))}render(){return b`<slot></slot>`}};r.styles=m`
+    :host {
+      display: block;
+    }
+  `,s([a({type:String,reflect:!0})],r.prototype,"value",2),s([a({type:String,attribute:"default-value"})],r.prototype,"defaultValue",2),s([a({type:String,reflect:!0})],r.prototype,"format",2),s([a({type:String,attribute:"default-format"})],r.prototype,"defaultFormat",2),s([a({converter:g})],r.prototype,"alpha",2),s([a({type:Number,reflect:!0})],r.prototype,"step",2),s([a({type:Boolean,reflect:!0})],r.prototype,"disabled",2),s([a({type:Boolean,reflect:!0,attribute:"read-only"})],r.prototype,"readOnly",2),s([v()],r.prototype,"color",2),r=s([k("skdx-color-picker","color-picker","root")],r);export{r as SkdxColorPicker};

package/dist/color-picker/ColorPickerAlphaSlider.cjs

@@ -0,0 +1 @@
+"use strict";var n=Object.defineProperty;var c=Object.getOwnPropertyDescriptor;var m=Object.getOwnPropertyNames;var f=Object.prototype.hasOwnProperty;var v=(a,e)=>{for(var o in e)n(a,o,{get:e[o],enumerable:!0})},b=(a,e,o,r)=>{if(e&&typeof e=="object"||typeof e=="function")for(let t of m(e))!f.call(a,t)&&t!==o&&n(a,t,{get:()=>e[t],enumerable:!(r=c(e,t))||r.enumerable});return a};var x=a=>b(n({},"__esModule",{value:!0}),a),p=(a,e,o,r)=>{for(var t=r>1?void 0:r?c(e,o):e,d=a.length-1,i;d>=0;d--)(i=a[d])&&(t=(r?i(e,o,t):i(t))||t);return r&&t&&n(e,o,t),t};var g={};v(g,{SkdxColorPickerAlphaSlider:()=>l});module.exports=x(g);var s=require("../internal/color.cjs"),u=require("../internal/define.cjs"),h=require("./channel-slider.cjs");var l=class extends h.SkdxColorPickerChannelSlider{constructor(){super(...arguments);this.channel="alpha";this.max=100;this.defaultLabel="Opacity"}get hiddenByRoot(){return!(this.root?.alpha??!0)}get channelValue(){return(this.root?.color.a??1)*100}valueTextFor(o){let r=this.root;return r?`${Math.round(o)}% opaque, ${(0,s.formatColor)(r.color,"hex",!1)}`:`${Math.round(o)}% opaque`}writeChannel(o){let r=this.root;r&&r.setColor({...r.color,a:o/100})}};l=p([(0,u.customElement)("skdx-color-picker-alpha-slider","color-picker","alpha-slider")],l);0&&(module.exports={SkdxColorPickerAlphaSlider});

package/dist/color-picker/ColorPickerAlphaSlider.d.cts

@@ -0,0 +1,54 @@
+import { SkdxColorPickerChannelSlider } from './channel-slider.cjs';
+/**
+ * `<skdx-color-picker-alpha-slider>` — the opacity track: a linear
+ * `role="slider"` over 0–100%, reported and stepped in whole percentage points
+ * even though the colour stores alpha as `0–1` — "50%" is what a user reads and
+ * types, `0.5` is what CSS wants, and only one of those belongs in an
+ * announcement. Must be used inside `<skdx-color-picker>`, which it finds with
+ * `closest()`.
+ *
+ * **It hides itself while the root has `alpha="false"`.** A picker that cannot
+ * express transparency should not show a control that appears to set it; the
+ * element stays in the tree (`hidden`, so `display: none`) rather than
+ * unmounting, so a layout does not have to be authored twice.
+ *
+ * It ships no CSS beyond `position: relative` and `touch-action: none`. The
+ * checkerboard behind the gradient and the gradient itself are yours, and
+ * `--skdx-color-picker-value` gives you the current colour to fade out to:
+ *
+ * ```css
+ * .my-alpha {
+ *   background:
+ *     linear-gradient(to right, transparent, var(--skdx-color-picker-value)),
+ *     var(--my-checkerboard);
+ * }
+ * skdx-color-picker-alpha-slider-thumb {
+ *   position: absolute;
+ *   inset-inline-start: var(--skdx-color-picker-alpha-position);
+ * }
+ * ```
+ *
+ * Named "Opacity" by default; write your own `aria-label` for a localised UI
+ * and it wins.
+ *
+ * @example
+ * ```html
+ * <skdx-color-picker-alpha-slider class="my-alpha">
+ *   <skdx-color-picker-alpha-slider-thumb></skdx-color-picker-alpha-slider-thumb>
+ * </skdx-color-picker-alpha-slider>
+ * ```
+ */
+export declare class SkdxColorPickerAlphaSlider extends SkdxColorPickerChannelSlider {
+    protected readonly channel = "alpha";
+    protected readonly max = 100;
+    protected readonly defaultLabel = "Opacity";
+    protected get hiddenByRoot(): boolean;
+    protected get channelValue(): number;
+    protected valueTextFor(value: number): string;
+    protected writeChannel(percent: number): void;
+}
+declare global {
+    interface HTMLElementTagNameMap {
+        'skdx-color-picker-alpha-slider': SkdxColorPickerAlphaSlider;
+    }
+}