@skdx/docs-kit 0.35.0

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

@@ -0,0 +1,102 @@
+/** A physical edge of the anchor. */
+export type PhysicalSide = 'top' | 'right' | 'bottom' | 'left';
+/** Side the floating content is placed against; `start`/`end` are logical and resolve under `dir`. */
+export type Side = PhysicalSide | 'start' | 'end';
+/** Alignment of the floating element along the chosen {@link Side}. */
+export type Align = 'start' | 'center' | 'end';
+/** Minimum distance from the collision boundary, for every side or per side. */
+export type CollisionPadding = number | Partial<Record<PhysicalSide, number>>;
+/** The floating-ui placement string for a resolved side and alignment. */
+export declare function toPlacement(side: PhysicalSide, align: Align): string;
+/** The side and alignment a floating-ui placement string resolved to. */
+export declare function placementParts(placement: string): [PhysicalSide, Align];
+/**
+ * Writes the four `--skdx-<component>-*` measurement properties onto the floating element after a reposition, with the transform origin derived from the resolved side/alignment so a flipped panel grows from the edge it actually sits on.
+ */
+export declare function setMeasurementProperties(floating: HTMLElement, component: string, measurements: {
+    availableWidth: number;
+    availableHeight: number;
+    triggerWidth: number;
+    side: PhysicalSide;
+    align: Align;
+}): void;
+/** The edge an arrow sits on: opposite the side the panel was placed against. */
+export declare const OPPOSITE_SIDE: Record<PhysicalSide, PhysicalSide>;
+/** Inline style for an arrow element given floating-ui's arrow offsets and the resolved side. */
+export declare function arrowStyle(offsets: {
+    x?: number | undefined;
+    y?: number | undefined;
+} | undefined, side: PhysicalSide): {
+    position: 'absolute';
+    left: string;
+    top: string;
+    right: string;
+    bottom: string;
+    transform: string;
+};
+/** Applies {@link arrowStyle} to an arrow element in place. */
+export declare function styleArrow(el: HTMLElement, offsets: {
+    x?: number | undefined;
+    y?: number | undefined;
+} | undefined, side: PhysicalSide): void;
+/** What the `size` middleware reports after flip/shift settled. */
+export interface SizeState {
+    availableWidth: number;
+    availableHeight: number;
+    elements: {
+        floating: HTMLElement;
+    };
+    rects: {
+        reference: {
+            width: number;
+        };
+    };
+    placement: string;
+}
+/** The floating-ui middleware factories an adapter injects — `M` is its `Middleware`, `L` its shift limiter, `E` what its `arrow` accepts as the element. */
+export interface FloatingMiddleware<M, L, E> {
+    offset(options: {
+        mainAxis: number;
+        alignmentAxis: number;
+    }): M;
+    flip(options: {
+        padding: CollisionPadding;
+        boundary?: Element | Element[];
+    }): M;
+    shift(options: {
+        padding: CollisionPadding;
+        limiter: L;
+        boundary?: Element | Element[];
+    }): M;
+    limitShift(): L;
+    size(options: {
+        padding: CollisionPadding;
+        boundary?: Element | Element[];
+        apply(state: SizeState): void;
+    }): M;
+    arrow(options: {
+        element: E;
+        padding: number;
+    }): M;
+    hide(options: {
+        strategy: 'referenceHidden';
+        boundary?: Element | Element[];
+    }): M;
+}
+/** The options {@link positioningMiddleware} turns into a middleware list. */
+export interface PositioningOptions<E> {
+    sideOffset?: number | undefined;
+    alignOffset?: number | undefined;
+    avoidCollisions?: boolean | undefined;
+    collisionPadding?: CollisionPadding | undefined;
+    collisionBoundary?: Element | Element[] | null | undefined;
+    /** Kebab-case component name the measurement properties are written under; omitted, none are written. */
+    component?: string | undefined;
+    arrow?: E | null | undefined;
+    arrowPadding?: number | undefined;
+    hideWhenDetached?: boolean | undefined;
+}
+/**
+ * The one middleware order every panel uses: offset, then flip/shift when collisions are avoided, then `size` (so it measures the placement the content landed on), the arrow, and `hide` last so visibility is judged against the settled placement.
+ */
+export declare function positioningMiddleware<M, L, E>(fu: FloatingMiddleware<M, L, E>, options: PositioningOptions<E>): M[];

package/dist/shared/core/placement.js

@@ -0,0 +1 @@
+function O(e,i){return i==="center"?e:`${e}-${i}`}function x(e){let[i,t="center"]=e.split("-");return[i,t]}var P={start:"0%",center:"50%",end:"100%"};function E(e,i,t){let{availableWidth:n,availableHeight:s,triggerWidth:o,side:r,align:d}=t,a=P[d],g=r==="top"||r==="bottom"?`${a} ${r==="top"?"100%":"0%"}`:`${r==="left"?"100%":"0%"} ${a}`;e.style.setProperty(`--skdx-${i}-available-width`,`${n}px`),e.style.setProperty(`--skdx-${i}-available-height`,`${s}px`),e.style.setProperty(`--skdx-${i}-trigger-width`,`${o}px`),e.style.setProperty(`--skdx-${i}-transform-origin`,g)}var S={top:"bottom",right:"left",bottom:"top",left:"right"};function M(e,i){let t=S[i],n={position:"absolute",left:e?.x!=null?`${e.x}px`:"",top:e?.y!=null?`${e.y}px`:"",right:"",bottom:"",transform:""};return t==="top"&&Object.assign(n,{top:"0px",transform:"translateY(-100%)"}),t==="bottom"&&Object.assign(n,{bottom:"0px",transform:"translateY(100%)"}),t==="left"&&Object.assign(n,{left:"0px",transform:"translateX(-100%)"}),t==="right"&&Object.assign(n,{right:"0px",transform:"translateX(100%)"}),n}function w(e,i,t){Object.assign(e.style,M(i,t))}function $(e,i){let{sideOffset:t=0,alignOffset:n=0,avoidCollisions:s=!0,collisionPadding:o=8,collisionBoundary:r,component:d,arrow:a,arrowPadding:g=0,hideWhenDetached:p=!1}=i,l=r?{boundary:r}:{};return[e.offset({mainAxis:t,alignmentAxis:n}),...s?[e.flip({padding:o,...l}),e.shift({padding:o,limiter:e.limitShift(),...l})]:[],e.size({padding:o,...l,apply({availableWidth:m,availableHeight:c,elements:f,rects:u,placement:b}){if(!d)return;let[h,y]=x(b);E(f.floating,d,{availableWidth:m,availableHeight:c,triggerWidth:u.reference.width,side:h,align:y})}}),...a?[e.arrow({element:a,padding:g})]:[],...p?[e.hide({strategy:"referenceHidden",...l})]:[]]}export{S as OPPOSITE_SIDE,M as arrowStyle,x as placementParts,$ as positioningMiddleware,E as setMeasurementProperties,w as styleArrow,O as toPlacement};

package/dist/shared/core/qr-encoder.d.ts

@@ -0,0 +1,33 @@
+/**
+ * QR Code encoder from ISO/IEC 18004: byte mode only (UTF-8), versions 1–40, all four error-correction levels.
+ *
+ * @module
+ */
+/** Error-correction level, in ascending order of redundancy: `L` ≈ 7%, `M` ≈ 15%, `Q` ≈ 25%, `H` ≈ 30%. */
+export type ErrorCorrectionLevel = 'L' | 'M' | 'Q' | 'H';
+export declare const MIN_VERSION = 1;
+export declare const MAX_VERSION = 40;
+/** Module count along one edge for `version`: `4 × version + 17`, so 21 at v1 and 177 at v40. */
+export declare function moduleCount(version: number): number;
+/** Total codewords (data + EC) a version holds, independent of level. */
+export declare function totalCodewords(version: number): number;
+/** Bits available for the data segment (mode indicator, character count, payload, padding) at this version and level. */
+export declare function dataCapacityBits(version: number, level: ErrorCorrectionLevel): number;
+/** Centre coordinates of alignment patterns for `version`, ascending, per ISO/IEC 18004 Table E.1. */
+export declare function alignmentPatternPositions(version: number): number[];
+/** Reed–Solomon generator polynomial `(x − α^0)(x − α^1)…(x − α^(degree−1))`, returned monic-implicit (leading 1 omitted). */
+export declare function reedSolomonGeneratorPoly(degree: number): Uint8Array;
+/** 15-bit format-information word: BCH(15, 5) over `level | mask`, XOR-masked to avoid all-zero output. */
+export declare function formatInfoBits(level: ErrorCorrectionLevel, mask: number): number;
+/** 18-bit version-information word: BCH(18, 6), used only for version 7 and up. */
+export declare function versionInfoBits(version: number): number;
+/**
+ * Encodes `value` as a QR Code matrix.
+ *
+ * @param value - The payload, encoded as UTF-8 bytes (byte mode).
+ * @param level - Error-correction level. Use `'H'` whenever a logo covers the centre.
+ * @param version - Force a symbol version 1–40. Omit to pick the smallest that fits.
+ * @returns A square `boolean[][]` indexed `[row][column]`, `true` meaning a dark
+ * module — or `null` when the payload exceeds capacity or `version` is invalid. Never throws.
+ */
+export declare function encodeQr(value: string, level: ErrorCorrectionLevel, version?: number): boolean[][] | null;

package/dist/shared/core/qr-encoder.js

@@ -0,0 +1 @@
+var O={L:1,M:0,Q:3,H:2},_={L:0,M:1,Q:2,H:3},B=[[-1,7,10,15,20,26,18,20,24,30,18,20,24,26,30,22,24,28,30,28,28,28,28,30,30,26,28,30,30,30,30,30,30,30,30,30,30,30,30,30,30],[-1,10,16,26,18,24,16,18,22,22,26,30,22,22,24,24,28,28,26,26,26,26,28,28,28,28,28,28,28,28,28,28,28,28,28,28,28,28,28,28,28],[-1,13,22,18,26,18,24,18,22,20,24,28,26,24,20,30,24,28,28,26,30,28,30,30,30,30,28,30,30,30,30,30,30,30,30,30,30,30,30,30,30],[-1,17,28,22,16,22,28,26,26,24,28,24,28,22,24,24,30,28,28,26,28,30,24,30,30,30,30,30,30,30,30,30,30,30,30,30,30,30,30,30,30]],P=[[-1,1,1,1,1,1,2,2,2,2,4,4,4,4,4,6,6,6,6,7,8,8,9,9,10,12,12,12,13,14,15,16,17,18,19,19,20,21,22,24,25],[-1,1,1,1,2,2,4,4,4,5,5,5,8,9,9,10,10,11,13,14,16,17,17,18,20,21,23,25,26,28,29,31,33,35,37,38,40,43,45,47,49],[-1,1,1,2,2,4,4,6,6,8,8,8,10,12,16,12,17,16,18,21,20,23,23,25,27,29,34,34,35,38,40,43,45,48,51,53,56,59,62,65,68],[-1,1,1,2,4,4,4,5,6,8,8,11,11,16,16,18,16,19,21,25,25,25,34,30,32,35,37,40,42,45,48,51,54,57,60,63,66,70,74,77,81]],N=1,z=40,D=3,T=3,V=40,Q=10;function S(n){return n*4+17}function Y(n){let t=(16*n+128)*n+64;if(n>=2){let e=Math.floor(n/7)+2;t-=(25*e-10)*e-55,n>=7&&(t-=36)}return t}function F(n){return Math.floor(Y(n)/8)}function M(n,t){let e=_[t],r=B[e][n]*P[e][n];return(F(n)-r)*8}function j(n){if(n===1)return[];let t=Math.floor(n/7)+2,e=n===32?26:Math.ceil((n*4+4)/(t*2-2))*2,r=[6];for(let o=S(n)-7;r.length<t;o-=e)r.splice(1,0,o);return r}var h=new Uint8Array(512),A=new Uint8Array(256);{let n=1;for(let t=0;t<255;t++)h[t]=n,A[n]=t,n<<=1,n&256&&(n^=285);for(let t=255;t<512;t++)h[t]=h[t-255]}function E(n,t){return n===0||t===0?0:h[A[n]+A[t]]}function H(n){let t=new Uint8Array(n);t[n-1]=1;let e=1;for(let r=0;r<n;r++){for(let o=0;o<n;o++){let u=E(t[o]??0,e);t[o]=o+1<n?u^(t[o+1]??0):u}e=E(e,2)}return t}function K(n,t){let e=new Uint8Array(t.length);for(let r of n){let o=r^(e[0]??0);e.copyWithin(0,1),e[e.length-1]=0;for(let u=0;u<e.length;u++)e[u]=(e[u]??0)^E(t[u]??0,o)}return e}function R(n,t,e){let r=n;for(let o=0;o<e;o++)r=r<<1^(r>>>e-1)*t;return r}function X(n,t){let e=O[n]<<3|t;return((e<<10|R(e,1335,10))^21522)&32767}function W(n){return(n<<12|R(n,7973,12))&262143}function C(n){return n<=9?8:16}function d(n,t,e){for(let r=e-1;r>=0;r--)n.push(t>>>r&1)}function q(n,t,e){let r=M(t,e),o=[];d(o,4,4),d(o,n.length,C(t));for(let c of n)d(o,c,8);d(o,0,Math.min(4,r-o.length)),d(o,0,(8-o.length%8)%8);for(let c=236;o.length<r;c^=253)d(o,c,8);let u=new Uint8Array(o.length/8);for(let c=0;c<o.length;c++){let l=c>>>3;u[l]=(u[l]??0)|o[c]<<7-(c&7)}return u}function J(n,t,e){let r=_[e],o=P[r][t],u=B[r][t],c=F(t),l=o-c%o,f=Math.floor(c/o)-u,m=H(u),y=[];for(let i=0,b=0;i<o;i++){let U=f+(i<l?0:1),k=n.subarray(b,b+U);b+=U,y.push({data:k,ecc:K(k,m)})}let p=new Uint8Array(c),G=0;for(let i=0;i<=f;i++)for(let b of y)i<b.data.length&&(p[G++]=b.data[i]);for(let i=0;i<u;i++)for(let b of y)p[G++]=b.ecc[i];return p}var I=[(n,t)=>(n+t)%2===0,(n,t)=>t%2===0,n=>n%3===0,(n,t)=>(n+t)%3===0,(n,t)=>(Math.floor(t/2)+Math.floor(n/3))%2===0,(n,t)=>n*t%2+n*t%3===0,(n,t)=>(n*t%2+n*t%3)%2===0,(n,t)=>((n+t)%2+n*t%3)%2===0];function Z(n){let t=S(n),e=()=>Array.from({length:t},()=>new Array(t).fill(!1));return{size:t,modules:e(),isFunction:e()}}function s(n,t,e,r){n.modules[e][t]=r,n.isFunction[e][t]=!0}var a=(n,t)=>(n>>>t&1)!==0;function x(n,t,e){for(let r=-4;r<=4;r++)for(let o=-4;o<=4;o++){let u=t+o,c=e+r;if(u<0||u>=n.size||c<0||c>=n.size)continue;let l=Math.max(Math.abs(o),Math.abs(r));s(n,u,c,l!==2&&l!==4)}}function $(n,t,e){for(let r=-2;r<=2;r++)for(let o=-2;o<=2;o++)s(n,t+o,e+r,Math.max(Math.abs(o),Math.abs(r))!==1)}function L(n,t,e){let r=X(t,e),{size:o}=n;for(let u=0;u<=5;u++)s(n,8,u,a(r,u));s(n,8,7,a(r,6)),s(n,8,8,a(r,7)),s(n,7,8,a(r,8));for(let u=9;u<15;u++)s(n,14-u,8,a(r,u));for(let u=0;u<8;u++)s(n,o-1-u,8,a(r,u));for(let u=8;u<15;u++)s(n,8,o-15+u,a(r,u));s(n,8,o-8,!0)}function v(n,t){if(t<7)return;let e=W(t);for(let r=0;r<18;r++){let o=a(e,r),u=n.size-11+r%3,c=Math.floor(r/3);s(n,u,c,o),s(n,c,u,o)}}function g(n,t,e){let{size:r}=n;for(let c=0;c<r;c++)s(n,6,c,c%2===0),s(n,c,6,c%2===0);x(n,3,3),x(n,r-4,3),x(n,3,r-4);let o=j(t),u=o.length-1;for(let c=0;c<=u;c++)for(let l=0;l<=u;l++)c===0&&l===0||c===0&&l===u||c===u&&l===0||$(n,o[c],o[l]);L(n,e,0),v(n,t)}function nn(n,t){let{size:e}=n,r=0;for(let o=e-1;o>=1;o-=2){o===6&&(o=5);for(let u=0;u<e;u++)for(let c=0;c<2;c++){let l=o-c,m=(o+1&2)===0?e-1-u:u;n.isFunction[m][l]||r>=t.length*8||(n.modules[m][l]=a(t[r>>>3],7-(r&7)),r++)}}}function w(n,t){let e=I[t];for(let r=0;r<n.size;r++)for(let o=0;o<n.size;o++)!n.isFunction[r][o]&&e(o,r)&&(n.modules[r][o]=!n.modules[r][o])}function tn(n,t){let e=0,r=n(0),o=1;for(let u=1;u<t;u++)n(u)===r?(o++,o===5?e+=D:o>5&&(e+=1)):(r=n(u),o=1);return e}function on(n,t){let e=0;for(let r=0;r+10<t;r++){let o=0,u=0;for(let c=0;c<11;c++){let l=n(r+c)?1:0;o=o<<1|l,u|=l<<c}(o===1488||u===1488)&&(e+=V)}return e}function rn(n){let{size:t,modules:e}=n,r=0;for(let o=0;o+1<t;o++)for(let u=0;u+1<t;u++){let c=e[o][u];c===e[o][u+1]&&c===e[o+1][u]&&c===e[o+1][u+1]&&(r+=T)}return r}function en(n){let{size:t,modules:e}=n,r=0;for(let u of e)for(let c of u)c&&r++;let o=t*t;return Math.floor(Math.abs(r*2-o)*10/o)*Q}function un(n){let{size:t,modules:e}=n,r=0;for(let o of[!0,!1])for(let u=0;u<t;u++){let c=l=>o?e[u][l]:e[l][u];r+=tn(c,t),r+=on(c,t)}return r+rn(n)+en(n)}function cn(n,t){for(let e=N;e<=z;e++)if(4+C(e)+n*8<=M(e,t))return e;return null}function ln(n,t,e){let r=new TextEncoder().encode(n),o;if(e===void 0?o=cn(r.length,t):!Number.isInteger(e)||e<N||e>z?o=null:o=4+C(e)+r.length*8<=M(e,t)?e:null,o===null)return null;let u=Z(o);g(u,o,t),nn(u,J(q(r,o,t),o,t));let c=0,l=1/0;for(let f=0;f<I.length;f++){w(u,f),L(u,t,f);let m=un(u);m<l&&(l=m,c=f),w(u,f)}return w(u,c),L(u,t,c),u.modules}export{z as MAX_VERSION,N as MIN_VERSION,j as alignmentPatternPositions,M as dataCapacityBits,ln as encodeQr,X as formatInfoBits,S as moduleCount,H as reedSolomonGeneratorPoly,F as totalCodewords,W as versionInfoBits};

package/dist/shared/core/roving-tab-stop.d.ts

@@ -0,0 +1,37 @@
+/** Matches an item excluded from the roving order — the contract names `data-disabled`, and native controls also carry `disabled`. */
+export declare const DISABLED_ITEM_SELECTOR = "[disabled], [data-disabled]";
+/** Whether an item is out of the roving order, testing both attribute spellings. */
+export declare function isRovingItemDisabled(item: Element): boolean;
+/**
+ * The group's items in document order, minus the disabled ones and minus any that belong to a nested group.
+ *
+ * @param root the group element owning the items, or `null` before it mounts
+ * @param itemSelector selector matching one item
+ * @param scopeSelector selector naming an item's owning group, so a nested group's items are left to it
+ * @returns the enabled items, empty when `root` is not mounted yet
+ */
+export declare function enabledRovingItems(root: ParentNode | null | undefined, itemSelector: string, scopeSelector?: string): HTMLElement[];
+/**
+ * The id that should hold the tab stop after the items or the selection changed.
+ *
+ * Active items win, and the stop stays put while it is still on one of them; with
+ * nothing active it stays on whichever item still claims it, else falls to the first.
+ * An active id that is not in `ids` — disabled, or unmounted since it was selected —
+ * cannot hold the stop, so the group stays reachable by Tab.
+ *
+ * @param ids every enabled item's id, in document order
+ * @param activeIds the ids of the selected/pressed/active items, in document order
+ * @param currentId the id holding the stop now, or `null` before one is resolved
+ * @returns the id to give the stop to, or `null` when the group has no enabled item
+ */
+export declare function resolveTabStopId(ids: readonly string[], activeIds: readonly string[], currentId: string | null): string | null;
+/** Every enabled item's id, skipping items that carry no id — they cannot hold a stop that survives a re-render. */
+export declare function rovingItemIds(items: readonly Element[], idAttribute: string): string[];
+/**
+ * The `tabindex` for one item: before the group resolves its stop — which only happens in a layout effect, so never during SSR — every enabled item is a stop rather than none.
+ *
+ * @param resolved whether the group has settled which item holds the stop
+ * @param isTabStop whether this item is that one
+ * @param disabled whether this item is disabled, in which case it never claims a stop
+ */
+export declare function rovingTabIndex(resolved: boolean, isTabStop: boolean, disabled?: boolean): 0 | -1;

package/dist/shared/core/roving-tab-stop.js

@@ -0,0 +1 @@
+var i="[disabled], [data-disabled]";function o(e){return e.matches(i)}function s(e,t,n){return Array.from(e?.querySelectorAll(t)??[]).filter(r=>!o(r)&&(!n||r.closest(n)===e))}function a(e,t,n){let l=t.filter(r=>e.includes(r));return l.length>0?n!==null&&l.includes(n)?n:l[0]:n!==null&&e.includes(n)?n:e[0]??null}function u(e,t){return e.map(n=>n.getAttribute(t)).filter(n=>n!==null&&n!=="")}function g(e,t,n=!1){return e||n?t?0:-1:0}export{i as DISABLED_ITEM_SELECTOR,s as enabledRovingItems,o as isRovingItemDisabled,a as resolveTabStopId,u as rovingItemIds,g as rovingTabIndex};

package/dist/shared/core/select-keyboard.d.ts

@@ -0,0 +1,80 @@
+/** Where the listbox should put the active option when a key opens it. */
+export type SelectOpenIntent = 'selected' | 'first' | 'last';
+/** Ten is the normative page jump for a listbox — a headless package has no rendered row height to divide by. */
+export declare const SELECT_PAGE_SIZE = 10;
+/** What a keydown on a closed trigger asks for. Every action but `'ignore'` wants `preventDefault()`. */
+export type SelectClosedAction = 
+/** Open the listbox with the active option placed as `intent` says. */
+{
+    kind: 'open';
+    intent: SelectOpenIntent;
+}
+/** A letter arrived on a multiple-select: open the listbox and search there, since a closed multi-select has no single "current" option to walk from. */
+ | {
+    kind: 'open-for-typeahead';
+}
+/** A letter arrived on a single-select: match it against the options and select the hit without opening, as a native `<select>` does. */
+ | {
+    kind: 'typeahead';
+}
+/** Not a key this trigger claims. */
+ | {
+    kind: 'ignore';
+};
+/** What a keydown on an open listbox asks for; `index` is already clamped into range. */
+export type SelectOpenAction = 
+/** Move the active option to `index`. */
+{
+    kind: 'activate';
+    index: number;
+}
+/** Select the active option, and close unless `closeOnSelect` is off. */
+ | {
+    kind: 'commit';
+}
+/** Alt+ArrowUp: select the active option and close, the keyboard equivalent of clicking it. */
+ | {
+    kind: 'commit-and-close';
+}
+/** Tab: add the active option to the selection without ever removing it, then close and let the browser's own Tab run. */
+ | {
+    kind: 'commit-on-exit';
+}
+/** A letter arrived: run the typeahead and activate its hit. */
+ | {
+    kind: 'typeahead';
+}
+/** Alt+ArrowDown, the open key: claimed so it cannot move focus, but nothing else happens. */
+ | {
+    kind: 'claim';
+}
+/** Not a key the listbox claims. */
+ | {
+    kind: 'ignore';
+};
+/** A keydown, reduced to what the decision needs. */
+export interface SelectKeyEvent {
+    key: string;
+    altKey: boolean;
+    ctrlKey: boolean;
+    metaKey: boolean;
+}
+/** Whether the adapter should call `preventDefault()` for this action; Tab is the exception, because focus is not trapped and the browser's own Tab has to carry focus onward. */
+export declare function selectKeyPrevented(action: SelectClosedAction | SelectOpenAction): boolean;
+/**
+ * The action for a keydown on a closed trigger.
+ *
+ * @param event the keydown
+ * @param multiple whether the Select holds more than one value
+ * @returns what the adapter should do; see {@link SelectClosedAction}
+ */
+export declare function selectClosedAction(event: SelectKeyEvent, multiple: boolean): SelectClosedAction;
+/**
+ * The action for a keydown while the listbox is open, over virtual focus: DOM focus stays on the trigger, so these move the active option, not the focused element.
+ *
+ * @param event the keydown
+ * @param currentIndex the active option's index, or `-1` when none is active
+ * @param optionCount how many options the listbox renders
+ * @returns what the adapter should do; see {@link SelectOpenAction}
+ */
+export declare function selectOpenAction(event: SelectKeyEvent, currentIndex: number, optionCount: number): SelectOpenAction;

package/dist/shared/core/select-keyboard.js

@@ -0,0 +1 @@
+import{isTypeaheadKey as c}from"./typeahead.js";var o=10,a={ArrowDown:"first",Home:"first",ArrowUp:"last",End:"last",Enter:"selected"," ":"selected"};function k(e){return e.kind!=="ignore"&&e.kind!=="commit-on-exit"}function r(e,t,n){return Math.min(n-1,Math.max(0,e+t))}function m(e,t){if(e.altKey&&e.key==="ArrowUp")return{kind:"ignore"};let n=a[e.key];return n!==void 0?{kind:"open",intent:e.altKey&&e.key==="ArrowDown"?"selected":n}:c(e)?t?{kind:"open-for-typeahead"}:{kind:"typeahead"}:{kind:"ignore"}}function s(e,t,n){if(e.altKey&&(e.key==="ArrowUp"||e.key==="ArrowDown"))return e.key==="ArrowUp"?{kind:"commit-and-close"}:{kind:"claim"};let i=d(e.key,t,n);return i!==null?n===0?{kind:"claim"}:{kind:"activate",index:i}:e.key==="Enter"||e.key===" "?{kind:"commit"}:e.key==="Tab"?{kind:"commit-on-exit"}:c(e)?{kind:"typeahead"}:{kind:"ignore"}}function d(e,t,n){switch(e){case"ArrowDown":return r(t,1,n);case"ArrowUp":return r(t,-1,n);case"PageDown":return r(t,o,n);case"PageUp":return r(t,-o,n);case"Home":return 0;case"End":return n-1;default:return null}}export{o as SELECT_PAGE_SIZE,m as selectClosedAction,k as selectKeyPrevented,s as selectOpenAction};

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

@@ -0,0 +1,58 @@
+/** Why a selection change happened: user-driven (keyboard or pointer) or set by the application. */
+export type SelectionChangeReason = 'keyboard' | 'pointer' | 'programmatic';
+/** The payload every single-or-many control's change event carries — the strict-out shape. */
+export interface SelectionChangeDetail {
+    /** The whole selection, always an array, in single and multiple mode alike. */
+    value: string[];
+    /** The first selected value, or `null` when nothing is selected. */
+    selectedValue: string | null;
+    /** The selection this change replaced, in the same array shape as `value`. */
+    previousValue?: string[];
+    /** What drove the change — see {@link SelectionChangeReason}. */
+    reason?: SelectionChangeReason;
+}
+/** Options {@link toSelectionValues} needs to apply the single-selection rule. */
+export interface SelectionValueOptions {
+    /** Whether the control may hold more than one value at once — `multiple`, or `type === 'multiple'` on the families that spell it that way. */
+    multiple: boolean;
+    /** The component and member named in the development error, e.g. `Select value`, so the message says which of a page's selects is wrong. */
+    label: string;
+}
+/** Every selected value as an array, whatever shape was passed; `''` and `undefined` mean nothing selected. */
+export declare function toValues(value: string | string[] | undefined): string[];
+/**
+ * Normalizes every selection value to `string[]`, enforcing the single-selection rule; called once at the boundary, never again downstream.
+ *
+ * @param input the value the consumer supplied, in any accepted shape
+ * @param options cardinality and label for errors — see {@link SelectionValueOptions}
+ * @returns the selection as an array; at most one element unless `multiple`
+ * @throws RangeError in development when an entry is not a string or a single-select gets multiple values
+ */
+export declare function toSelectionValues(input: string | readonly string[] | null | undefined, { multiple, label }: SelectionValueOptions): string[];
+/**
+ * The `selectedValue` half of the rule's output: the first selected value, or `null` (never `undefined` or `''`).
+ *
+ * @param values the normalized selection, as {@link toSelectionValues} returns it
+ * @returns the first selected value, or `null` when nothing is selected
+ */
+export declare function selectedValueOf(values: readonly string[]): string | null;
+/**
+ * The selection after choosing `value`: replaces it, or toggles it within the set when `multiple`.
+ *
+ * @param selected the current selection, already normalized
+ * @param value the option value the user committed
+ * @param multiple whether choosing toggles within a set rather than replacing
+ * @param deselectable whether re-choosing the only selected value clears it (single-select only)
+ * @returns the new selection as an array in both cardinalities
+ */
+export declare function nextSelection(selected: readonly string[], value: string, multiple: boolean, deselectable?: boolean): string[];
+/** Whether two selections are indistinguishable to a consumer: same values in the same order. */
+export declare function sameSelection(a: readonly string[], b: readonly string[]): boolean;
+/**
+ * Parses the attribute form — one comma-separated list under both cardinalities — with {@link toSelectionValues} enforcing the rule.
+ *
+ * @param attribute the raw attribute string, or `null` when absent
+ * @param options cardinality and label for errors
+ * @returns the selection as an array
+ */
+export declare function parseSelectionAttribute(attribute: string | null | undefined, options: SelectionValueOptions): string[];

package/dist/shared/core/selection.js

@@ -0,0 +1 @@
+import{isDevMode as s}from"./dev-mode.js";function g(e){return Array.isArray(e)?e:e?[e]:[]}function l(e){if(s())throw new RangeError(e);console.error(e)}function a(e,{multiple:n,label:t}){let i;Array.isArray(e)?i=e:i=e==null?[]:[e];let r=[];for(let o of i){if(typeof o!="string"){l(`[skdx] ${t}: a selection value must be a string, got ${o===null?"null":typeof o} (${JSON.stringify(o)}). If this is a change payload, read its \`value\` \u2014 the event carries { value, selectedValue } and only \`value\` goes back in.`);continue}o!==""&&r.push(o)}return n||r.length<=1?r:(l(`[skdx] ${t}: a single-selection control was given ${r.length} values (${r.join(", ")}). Only one can be held \u2014 pass a single value, or turn the control multiple. Set multiple (or type="multiple") to keep them all.`),[r[0]])}function c(e){return e.length>0?e[0]:null}function f(e,n,t,i=!1){return t?e.includes(n)?e.filter(r=>r!==n):[...e,n]:i&&e.length===1&&e[0]===n?[]:[n]}function p(e,n){return e.length===n.length&&e.every((t,i)=>t===n[i])}function d(e,n){return e==null?[]:a(e.split(",").map(t=>t.trim()),n)}export{f as nextSelection,d as parseSelectionAttribute,p as sameSelection,c as selectedValueOf,a as toSelectionValues,g as toValues};

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

@@ -0,0 +1,8 @@
+/** The elements a `Tab` press can land on — this package's one definition of "tabbable", for components that have to walk the tab order by hand. */
+export declare const TABBABLE_SELECTOR: string;
+/**
+ * Every tabbable element inside `container`, in document order. Uses only the
+ * selector without visibility checks (unlike focus traps) because overlays are
+ * small subtrees only in the DOM while open.
+ */
+export declare function tabbablesWithin(container: Element): HTMLElement[];

package/dist/shared/core/tabbable.js

@@ -0,0 +1 @@
+var e=["a[href]","button:not([disabled])",'input:not([disabled]):not([type="hidden"])',"select:not([disabled])","textarea:not([disabled])",'[tabindex]:not([tabindex="-1"])'].join(", ");function n(t){return Array.from(t.querySelectorAll(e))}export{e as TABBABLE_SELECTOR,n as tabbablesWithin};

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

@@ -0,0 +1,82 @@
+/** Where the clock stands: never started, running, held by a pause, or finished. */
+export type TimerPhase = 'idle' | 'running' | 'paused' | 'complete';
+/** The clock as a consumer renders it, computed fresh on every read. */
+export interface TimerState {
+    /** Where the clock stands right now, as one of the four phases. */
+    phase: TimerPhase;
+    /** Milliseconds the clock has actually run, never counting paused time. */
+    elapsed: number;
+    /** Milliseconds left before completion, or `Infinity` when counting up. */
+    remaining: number;
+    /** The countdown length in force, `Infinity` for an open-ended count-up. */
+    duration: number;
+}
+/** How one clock is configured; every field has a working default. */
+export interface TimerOptions {
+    /**
+     * Countdown length in milliseconds; leave it out to count up with no end.
+     *
+     * @default Infinity
+     */
+    duration?: number | undefined;
+    /**
+     * Milliseconds between `onTick` calls while running; `0` reports no ticks.
+     *
+     * @default 0
+     */
+    tickMs?: number | undefined;
+    /**
+     * Whether a hidden or unloading page pauses the clock and a returning page resumes it.
+     *
+     * @default true
+     */
+    pauseWhenHidden?: boolean | undefined;
+    /**
+     * Called on every tick and once more at completion, for rendering the clock only.
+     *
+     * Ticks are far too frequent to announce: write them to a progress bar or a
+     * `<time>`, never to a live region.
+     */
+    onTick?: ((state: TimerState) => void) | undefined;
+    /**
+     * Called when the phase changes, and only on an actual change, so it is the one place announcements belong.
+     */
+    onPhaseChange?: ((state: TimerState) => void) | undefined;
+}
+/** A framework-neutral countdown or count-up: `start`, `pause`, `resume`, `reset`, and a completion phase. */
+export declare class Timer {
+    private readonly options;
+    private readonly tickMs;
+    private duration;
+    private phase;
+    private accrued;
+    private startedAt;
+    private completion;
+    private ticker;
+    private pausedByPage;
+    constructor(options?: TimerOptions);
+    /** The phase, elapsed, remaining and duration as they read at this instant. */
+    get state(): TimerState;
+    /**
+     * Runs the clock from zero, replacing whatever it was doing.
+     *
+     * @param duration a new countdown length to adopt, in milliseconds
+     */
+    start(duration?: number): void;
+    /** Holds the clock where it stands; a second call while already paused changes nothing. */
+    pause(): void;
+    /** Runs the clock on from where a pause left it; ignored unless it is paused. */
+    resume(): void;
+    /** Stops the clock and returns it to zero, as it was before the first `start`. */
+    reset(): void;
+    /** Stops the clock and releases every listener and handle it holds. */
+    destroy(): void;
+    private measure;
+    private run;
+    private complete;
+    private setPhase;
+    private clearHandles;
+    private readonly onVisibilityChange;
+    private readonly onPageHide;
+    private pauseForPage;
+}

package/dist/shared/core/timer.js

@@ -0,0 +1 @@
+var i=class{constructor(e={}){this.phase="idle";this.accrued=0;this.startedAt=0;this.pausedByPage=!1;this.onVisibilityChange=()=>{document.hidden?this.pauseForPage():this.pausedByPage&&this.resume()};this.onPageHide=()=>{this.pauseForPage()};this.options=e,this.duration=e.duration??Number.POSITIVE_INFINITY,this.tickMs=e.tickMs??0,!(e.pauseWhenHidden===!1||typeof document>"u")&&(document.addEventListener("visibilitychange",this.onVisibilityChange),window.addEventListener("pagehide",this.onPageHide))}get state(){let e=this.measure();return{phase:this.phase,elapsed:e,remaining:this.duration-e,duration:this.duration}}start(e){e!==void 0&&(this.duration=e),this.clearHandles(),this.accrued=0,this.pausedByPage=!1,this.run()}pause(){this.pausedByPage=!1,this.phase==="running"&&(this.accrued=this.measure(),this.clearHandles(),this.setPhase("paused"))}resume(){this.pausedByPage=!1,this.phase==="paused"&&this.run()}reset(){this.clearHandles(),this.accrued=0,this.startedAt=0,this.pausedByPage=!1,this.setPhase("idle")}destroy(){this.clearHandles(),!(this.options.pauseWhenHidden===!1||typeof document>"u")&&(document.removeEventListener("visibilitychange",this.onVisibilityChange),window.removeEventListener("pagehide",this.onPageHide))}measure(){let e=this.phase==="running"?Date.now()-this.startedAt:0;return Math.min(this.accrued+e,this.duration)}run(){this.startedAt=Date.now();let e=this.duration-this.accrued;Number.isFinite(e)&&(this.completion=setTimeout(()=>this.complete(),Math.max(e,0))),this.tickMs>0&&(this.ticker=setInterval(()=>this.options.onTick?.(this.state),this.tickMs)),this.setPhase("running")}complete(){this.clearHandles(),this.accrued=this.duration,this.setPhase("complete"),this.tickMs>0&&this.options.onTick?.(this.state)}setPhase(e){this.phase!==e&&(this.phase=e,this.options.onPhaseChange?.(this.state))}clearHandles(){clearTimeout(this.completion),clearInterval(this.ticker),this.completion=void 0,this.ticker=void 0}pauseForPage(){this.phase==="running"&&(this.pause(),this.pausedByPage=!0)}};export{i as Timer};

package/dist/shared/core/tree-columns.d.ts

@@ -0,0 +1,48 @@
+/** The minimal node shape the projection reads; the adapters' own node types are supersets of it. */
+export interface TreeColumnNode {
+    value: string;
+    disabled?: boolean | undefined;
+    /** Declares a branch whose children have not loaded yet, so its column exists while still empty. */
+    hasChildren?: boolean | undefined;
+    children?: readonly TreeColumnNode[] | undefined;
+}
+/** One rendered column: the sibling set at a single depth. */
+export interface TreeColumn {
+    /** The branch whose children this column lists, or `null` for the root column. */
+    parent: string | null;
+    /** The column's nodes in collection order; empty while a lazy branch is still loading. */
+    nodes: readonly TreeColumnNode[];
+}
+/**
+ * The columns showing for an expanded set: the roots, then one column per expanded branch along a single open path.
+ *
+ * Columns are a chain, so at most one branch per depth can be open. An
+ * `expanded` set naming two branches at the same depth is not an error: the
+ * first in collection order wins and the rest are ignored, which keeps the
+ * projection total and lets a consumer hand the same `expanded` array to
+ * either layout.
+ *
+ * @param collection the root nodes, each carrying its own children
+ * @param expanded every expanded node's value, in any order
+ * @returns the columns left to right; always at least the root column
+ */
+export declare function treeColumns(collection: readonly TreeColumnNode[], expanded: Iterable<string>): TreeColumn[];
+/**
+ * The chain of values from the root down to `value`, inclusive, or empty when the collection does not hold it.
+ *
+ * This is the expanded set that opens `value`'s own column: passing it to
+ * {@link treeColumns} shows every ancestor's column and closes every branch off
+ * the path. Dropping its last entry is the set that closes `value`'s column
+ * instead, which is what moving back a column needs.
+ *
+ * @param collection the root nodes, each carrying its own children
+ * @param value the node to reach
+ */
+export declare function pathTo(collection: readonly TreeColumnNode[], value: string): string[];
+/**
+ * The index of the column holding `value`, or `-1` when no showing column does.
+ *
+ * @param columns the projection {@link treeColumns} returned
+ * @param value the node to locate
+ */
+export declare function columnIndexOf(columns: readonly TreeColumn[], value: string): number;

package/dist/shared/core/tree-columns.js

@@ -0,0 +1 @@
+function a(o,u){let l=new Set(u),t=[{parent:null,nodes:o}],d=new Set,e=o;for(;;){let n=e.find(r=>l.has(r.value)&&!d.has(r.value)&&((r.children?.length??0)>0||r.hasChildren===!0));if(!n)return t;d.add(n.value),e=n.children??[],t.push({parent:n.value,nodes:e})}}function i(o,u){let l=(t,d)=>{for(let e of t){let n=[...d,e.value];if(e.value===u)return n;let r=e.children?l(e.children,n):null;if(r)return r}return null};return l(o,[])??[]}function s(o,u){return o.findIndex(l=>l.nodes.some(t=>t.value===u))}export{s as columnIndexOf,i as pathTo,a as treeColumns};

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

@@ -0,0 +1,27 @@
+/** How long successive keys keep merging into one search before the buffer resets. */
+export declare const TYPEAHEAD_TIMEOUT_MS = 1000;
+/** Plain printable character, not a shortcut or named key. */
+export declare function isTypeaheadKey(event: {
+    key: string;
+    ctrlKey: boolean;
+    metaKey: boolean;
+    altKey: boolean;
+}): boolean;
+/**
+ * Text typeahead matches: explicit `data-text-value`, else rendered text, since raw `textContent` fails for items rendering beyond their label.
+ * @internal
+ */
+export declare function itemText(el: Element): string;
+/** Letter-key search like native `<select>` (accumulating buffer and timer), shared by every collection and menu family. */
+export declare class Typeahead {
+    private buffer;
+    private timer?;
+    /**
+     * Matches `key` against the label collection, accumulating a 1s buffer (`"s"` + `"a"` = `"sa"`); repeating one letter cycles through matches.
+     *
+     * @returns the index to move to, or `-1` for no match.
+     */
+    match(key: string, labels: string[], currentIndex: number): number;
+    /** Drops the pending buffer and its timer. Call when the owner unmounts or closes. */
+    clear(): void;
+}

package/dist/shared/core/typeahead.js

@@ -0,0 +1 @@
+var h=1e3;function c(t){return t.key.length===1&&!t.ctrlKey&&!t.metaKey&&!t.altKey}function l(t){return t.getAttribute("data-text-value")??t.textContent??""}var f=class{constructor(){this.buffer=""}match(o,i,n){if(o===" "&&this.buffer==="")return-1;clearTimeout(this.timer),this.buffer+=o.toLowerCase(),this.timer=setTimeout(()=>this.buffer="",1e3);let e=this.buffer,s=e.length>1&&[...e].every(r=>r===e[0]),u=s?e[0]:e,m=s||e.length===1?n+1:n;for(let r=0;r<i.length;r++){let a=(Math.max(m,0)+r)%i.length;if(i[a].trim().toLowerCase().startsWith(u))return a}return-1}clear(){clearTimeout(this.timer),this.buffer=""}};export{h as TYPEAHEAD_TIMEOUT_MS,f as Typeahead,c as isTypeaheadKey,l as itemText};