@skdx/react 0.26.0 → 0.28.0

package/dist/pin-input/PinInput.cjs

@@ -1 +1 @@
-"use strict";var Y=Object.create;var v=Object.defineProperty;var Z=Object.getOwnPropertyDescriptor;var ee=Object.getOwnPropertyNames;var te=Object.getPrototypeOf,ne=Object.prototype.hasOwnProperty;var re=(t,n)=>{for(var i in n)v(t,i,{get:n[i],enumerable:!0})},V=(t,n,i,e)=>{if(n&&typeof n=="object"||typeof n=="function")for(let s of ee(n))!ne.call(t,s)&&s!==i&&v(t,s,{get:()=>n[s],enumerable:!(e=Z(n,s))||e.enumerable});return t};var T=(t,n,i)=>(i=t!=null?Y(te(t)):{},V(n||!t||!t.__esModule?v(i,"default",{value:t,enumerable:!0}):i,t)),ae=t=>V(v({},"__esModule",{value:!0}),t);var ie={};re(ie,{PinInput:()=>$,PinInputField:()=>w,PinInputProvider:()=>S,usePinInputContext:()=>D});module.exports=ae(ie);var o=T(require("react"),1),O=require("../utils/createContext.cjs"),g=require("../utils/formControl.cjs"),A=require("../utils/hiddenInput.cjs"),N=require("../utils/part.cjs"),z=require("../utils/primitive.cjs"),K=require("../utils/useCallbackRef.cjs"),q=require("../utils/useControllableState.cjs"),I=require("react/jsx-runtime"),[S,D]=(0,O.createSafeContext)("PinInput"),$=o.forwardRef(({value:t,defaultValue:n="",onValueChange:i,length:e=6,disabled:s=!1,invalid:R=!1,readOnly:c=!1,type:b="text",mask:d=!1,onValueComplete:r,autoSubmit:a=!1,sanitize:u,name:m,required:P=!1,...f},G)=>{let[y="",k]=(0,q.useControllableState)({prop:t,defaultProp:n,onChange:i}),F=o.useRef([]),h=o.useRef(null),M=o.useRef(null);(0,g.useFormValidityHandle)(G,h,M),(0,g.useFormReset)(h,()=>k(n));let x=(0,K.useCallbackRef)(r),E=o.useRef(y);E.current=y;let L=o.useRef(u);L.current=u;let J=o.useCallback(l=>L.current?.(l)??l,[]),Q=o.useCallback(l=>{let H=E.current.length===e;k(l),!(l.length!==e||H)&&(x(l),a&&h.current?.closest("form")?.requestSubmit())},[e,k,x,a]),W=o.useCallback((l,H)=>{F.current[l]=H},[]),X=o.useCallback(l=>{F.current[l]?.focus()},[]);return(0,I.jsxs)(S,{value:y,length:e,type:b,mask:d,disabled:s,invalid:R,readOnly:c,setValue:Q,focusIndex:X,registerRef:W,sanitizePaste:J,children:[(0,I.jsx)(z.Primitive.div,{"data-disabled":s?"":void 0,"data-invalid":R?"":void 0,"data-readonly":c?"":void 0,...f,...(0,N.skdxPart)("pin-input","root",f.className),ref:h}),m&&(0,I.jsx)(A.HiddenInput,{ref:M,type:"text",name:m,value:y,required:P,disabled:s,pattern:P?`.{${e}}`:void 0})]})});$.displayName="PinInput";var j=T(require("react"),1),B=require("../utils/composeRefs.cjs"),C=require("../utils/direction.cjs"),U=require("../utils/part.cjs"),p=require("../utils/primitive.cjs");var _=require("react/jsx-runtime"),oe=/^[0-9]$/,w=j.forwardRef(({index:t,...n},i)=>{let e=D("PinInputField"),s=(0,C.useDirection)(),R=(0,B.useComposedRefs)(i,r=>e.registerRef(t,r)),c=e.value[t]??"",b=c!=="",d=r=>{let a=e.value.split("");a[t]=r,e.setValue(a.join("").slice(0,e.length))};return(0,_.jsx)(p.Primitive.input,{inputMode:e.type==="numeric"?"numeric":"text",autoComplete:t===0?"one-time-code":"off",type:e.mask&&b?"password":"text",maxLength:1,disabled:e.disabled,readOnly:e.readOnly,"aria-invalid":e.invalid?!0:void 0,"aria-readonly":e.readOnly?!0:void 0,"data-disabled":e.disabled?"":void 0,"data-invalid":e.invalid?"":void 0,"data-readonly":e.readOnly?"":void 0,...n,value:c,...(0,U.skdxPart)("pin-input","field",n.className),ref:R,onChange:(0,p.composeEventHandlers)(n.onChange,r=>{if(e.disabled)return;let a=r.target.value;if(a===""){d("");return}e.type==="numeric"&&!oe.test(a)||(d(a),t<e.length-1&&e.focusIndex(t+1))}),onKeyDown:(0,p.composeEventHandlers)(n.onKeyDown,r=>{if(e.disabled)return;let a=(0,C.directionalKey)(r.key,r.currentTarget,s);if(a==="Backspace"){if(e.readOnly)return;if(r.preventDefault(),c)d("");else if(t>0){let u=e.value.split("");u[t-1]="",e.setValue(u.join("").slice(0,e.length)),e.focusIndex(t-1)}}else a==="ArrowLeft"?t>0&&(r.preventDefault(),e.focusIndex(t-1)):a==="ArrowRight"&&t<e.length-1&&(r.preventDefault(),e.focusIndex(t+1))}),onPaste:(0,p.composeEventHandlers)(n.onPaste,r=>{if(e.disabled||e.readOnly)return;r.preventDefault();let a=e.sanitizePaste(r.clipboardData.getData("text")),u=e.type==="numeric"?a.replace(/[^0-9]/g,""):a;if(!u)return;let m=e.value.split(""),P=t-1;for(let f=0;f<u.length&&t+f<e.length;f++)m[t+f]=u[f],P=t+f;e.setValue(m.join("").slice(0,e.length)),e.focusIndex(Math.min(P+1,e.length-1))})})});w.displayName="PinInputField";0&&(module.exports={PinInput,PinInputField,PinInputProvider,usePinInputContext});
+"use strict";var De=Object.create;var A=Object.defineProperty;var Te=Object.getOwnPropertyDescriptor;var Ee=Object.getOwnPropertyNames;var He=Object.getPrototypeOf,Le=Object.prototype.hasOwnProperty;var Me=(t,r)=>{for(var i in r)A(t,i,{get:r[i],enumerable:!0})},ee=(t,r,i,e)=>{if(r&&typeof r=="object"||typeof r=="function")for(let l of Ee(r))!Le.call(t,l)&&l!==i&&A(t,l,{get:()=>r[l],enumerable:!(e=Te(r,l))||e.enumerable});return t};var te=(t,r,i)=>(i=t!=null?De(He(t)):{},ee(r||!t||!t.__esModule?A(i,"default",{value:t,enumerable:!0}):i,t)),Oe=t=>ee(A({},"__esModule",{value:!0}),t);var Se={};Me(Se,{PinInput:()=>B,PinInputField:()=>E,PinInputProvider:()=>me,pinInputDigitLabel:()=>D,usePinInputContext:()=>S});module.exports=Oe(Se);var o=te(require("react"),1),le=require("../utils/createContext.cjs"),H=require("../utils/formControl.cjs"),ue=require("../utils/hiddenInput.cjs"),ce=require("../utils/is-dev-mode.cjs"),fe=require("../utils/part.cjs"),pe=require("../utils/primitive.cjs"),N=require("../utils/useCallbackRef.cjs"),de=require("../utils/useControllableState.cjs");var $e={text:null,numeric:/^[0-9]$/,alphanumeric:/^[a-zA-Z0-9]$/,alphabetic:/^[a-zA-Z]$/};function ne(t,r){if(r){let e=new RegExp(r);return l=>e.test(l)}let i=$e[t]??null;return i?e=>i.test(e):()=>!0}function D(t,r){return`Digit ${t} of ${r}`}var re=te(require("react"),1),oe=require("../utils/composeRefs.cjs"),T=require("../utils/direction.cjs"),ae=require("../utils/part.cjs"),d=require("../utils/primitive.cjs");var ie=require("react/jsx-runtime"),E=re.forwardRef(({index:t,...r},i)=>{let e=S("PinInputField"),l=(0,T.useDirection)(),h=(0,oe.useComposedRefs)(i,a=>e.registerRef(t,a)),c=e.charAt(t),g=c!=="",p=a=>e.setCharAt(t,a);return(0,ie.jsx)(d.Primitive.input,{inputMode:e.type==="numeric"?"numeric":"text",autoComplete:e.otp&&t===0?"one-time-code":"off",type:e.mask&&g?"password":"text",placeholder:e.placeholder,maxLength:1,disabled:e.disabled,readOnly:e.readOnly,"aria-label":e.digitLabel(t+1,e.length),"aria-readonly":e.readOnly?!0:void 0,"data-disabled":e.disabled?"":void 0,"data-invalid":e.invalid?"":void 0,"data-readonly":e.readOnly?"":void 0,...r,value:c,...(0,ae.skdxPart)("pin-input","field",r.className),ref:h,onChange:(0,d.composeEventHandlers)(r.onChange,a=>{if(e.disabled)return;let u=a.target.value;if(u===""){p("");return}if(!e.accepts(u)){a.target.value=c,e.reportInvalid(u,t);return}p(u),t<e.length-1&&e.focusIndex(t+1)}),onFocus:(0,d.composeEventHandlers)(r.onFocus,a=>{e.selectOnFocus&&a.currentTarget.select()}),onKeyDown:(0,d.composeEventHandlers)(r.onKeyDown,a=>{if(e.disabled)return;let u=(0,T.directionalKey)(a.key,a.currentTarget,l);if(u==="Backspace"){if(e.readOnly)return;a.preventDefault(),c?p(""):t>0&&(e.setCharAt(t-1,""),e.focusIndex(t-1))}else if(u==="Delete"){if(e.readOnly)return;a.preventDefault(),c&&p("")}else u==="ArrowLeft"?t>0&&(a.preventDefault(),e.focusIndex(t-1)):u==="ArrowRight"&&t<e.length-1&&(a.preventDefault(),e.focusIndex(t+1))}),onPaste:(0,d.composeEventHandlers)(r.onPaste,a=>{if(e.disabled||e.readOnly)return;a.preventDefault();let u=e.sanitizePaste(a.clipboardData.getData("text")),m="";for(let y of u)e.accepts(y)?m+=y:e.reportInvalid(y,Math.min(t+m.length,e.length-1));if(!m)return;let k=e.fillFrom(t,m);e.focusIndex(Math.min(k+1,e.length-1))})})});E.displayName="PinInputField";var x=require("react/jsx-runtime");function se({length:t}){return(0,x.jsx)(x.Fragment,{children:Array.from({length:t},(r,i)=>(0,x.jsx)(E,{index:i},i))})}function V(t,r){return Array.from({length:r},(i,e)=>t[e]??"")}function z(t){return t.join("")}var R=require("react/jsx-runtime"),[me,S]=(0,le.createSafeContext)("PinInput"),B=o.forwardRef(({value:t,defaultValue:r="",onValueChange:i,length:e=6,disabled:l=!1,invalid:h=!1,readOnly:c=!1,type:g="text",pattern:p,placeholder:a,otp:u=!0,autoFocus:m=!1,blurOnComplete:k=!1,selectOnFocus:y=!1,mask:Pe=!1,onValueComplete:Ie,onValueInvalid:be,autoSubmit:K=!1,sanitize:_,name:j,form:q,required:Z=!1,digitLabel:U=D,children:Re,...Y},he)=>{let[f="",L]=(0,de.useControllableState)({prop:t,defaultProp:r,onChange:i}),v=o.useRef([]),P=o.useRef(null),M=o.useRef(null);(0,H.useFormReset)(P,()=>L(r),q);let G=(0,N.useCallbackRef)(Ie),J=(0,N.useCallbackRef)(be??(()=>{})),ge=o.useMemo(()=>ne(g,p),[g,p]),ye=o.useCallback((n,s)=>J({value:n,index:s}),[J]),Q=o.useRef(f);Q.current=f;let W=o.useRef(_);W.current=_;let X=o.useRef(U);X.current=U;let ve=o.useCallback(n=>W.current?.(n)??n,[]),Ce=o.useCallback((n,s)=>X.current(n,s),[]),O=o.useCallback(n=>{let s=Q.current.length===e;L(n),!(n.length!==e||s)&&(G(n),k&&(v.current.find($=>$===document.activeElement)??v.current[e-1])?.blur(),K&&(M.current?.form??P.current?.closest("form"))?.requestSubmit())},[e,L,G,k,K]),I=o.useRef(V(f,e));(I.current.length!==e||z(I.current)!==f)&&(I.current=V(f,e));let xe=o.useCallback(n=>I.current[n]??"",[]),w=o.useCallback(n=>{let s=[...I.current];n(s),I.current=s,O(z(s))},[O]),ke=o.useCallback((n,s)=>{w(C=>{C[n]=s})},[w]),we=o.useCallback((n,s)=>{let C=n-1;return w($=>{for(let b=0;b<s.length&&n+b<e;b++)$[n+b]=s[b],C=n+b}),C},[w,e]),Fe=o.useCallback((n,s)=>{v.current[n]=s},[]);o.useEffect(()=>{if(!(0,ce.isDevMode)())return;let n=v.current.filter(Boolean).length;n!==0&&n!==e&&console.warn(`PinInput: ${n} PinInputField${n===1?"":"s"} rendered but length is ${e}. Render exactly one field per position, with contiguous \`index\` values from 0 to ${e-1} \u2014 otherwise the value can never complete and value-complete never fires.`)},[e,f]);let F=o.useCallback(n=>{v.current[n]?.focus()},[]),Ae=o.useRef(m);return o.useEffect(()=>{Ae.current&&F(0)},[F]),o.useImperativeHandle(he,()=>{let n={...(0,H.formValidityHandle)(M),clear:()=>O(""),focus:()=>F(0)};return P.current?(Object.defineProperties(P.current,Object.getOwnPropertyDescriptors(n)),P.current):n}),(0,R.jsxs)(me,{value:f,length:e,type:g,mask:Pe,disabled:l,invalid:h,readOnly:c,placeholder:a,otp:u,selectOnFocus:y,accepts:ge,reportInvalid:ye,charAt:xe,setCharAt:ke,fillFrom:we,focusIndex:F,registerRef:Fe,sanitizePaste:ve,digitLabel:Ce,children:[(0,R.jsx)(pe.Primitive.div,{role:"group","aria-invalid":h?!0:void 0,"data-disabled":l?"":void 0,"data-invalid":h?"":void 0,"data-readonly":c?"":void 0,...Y,...(0,fe.skdxPart)("pin-input","root",Y.className),ref:P,children:Re??(0,R.jsx)(se,{length:e})}),j&&(0,R.jsx)(ue.HiddenInput,{ref:M,type:"text",name:j,value:f,required:Z,disabled:l,form:q,pattern:Z?`.{${e}}`:void 0})]})});B.displayName="PinInput";0&&(module.exports={PinInput,PinInputField,PinInputProvider,pinInputDigitLabel,usePinInputContext});

package/dist/pin-input/PinInput.d.cts

@@ -1,5 +1,5 @@
 import * as React from 'react';
-import type { PinInputContextValue, PinInputProps } from './types.cjs';
+import type { PinInputContextValue, PinInputHandle, PinInputProps } from './types.cjs';
 export declare const PinInputProvider: {
     (props: PinInputContextValue & {
         children: React.ReactNode;
@@ -7,31 +7,28 @@ export declare const PinInputProvider: {
     displayName: string;
 }, usePinInputContext: (consumerName: string) => PinInputContextValue;
 /**
- * Root of a one-time-passcode input: owns the joined string value and hands
- * it down to `length` `PinInputField` boxes via context. Renders a plain
- * `<div data-disabled data-invalid data-readonly>` — layout of the boxes is
- * entirely up to your CSS. Built as N real `<input maxLength=1>` elements
- * behaving as a single logical string value — the standard, most robust
- * implementation approach (vs. one hidden input + painted boxes).
+ * A one-time-passcode input: owns the joined string value, passes it to
+ * `length` `PinInputField` boxes via context. Renders `<div role="group">`
+ * with boxes as N real `<input maxLength=1>` elements (most robust approach).
  *
- * Works controlled (`value` + `onValueChange`) or uncontrolled (`defaultValue`).
+ * `role="group"` makes the boxes read as one value, not N fields, and holds
+ * `aria-invalid`. It auto-wires an enclosing {@link Field}: the root precedes
+ * its boxes, so Field discovers it and writes `aria-describedby` here. Name it
+ * with `aria-label` / `aria-labelledby`, or use `FieldLabel`.
  *
- * Fires `onValueComplete` once the last box is filled — with `autoSubmit`, it
- * also calls `requestSubmit()` on the surrounding form, which is what a
- * one-time-passcode screen usually wants.
+ * Fires `onValueComplete` when the last box fills; with `autoSubmit`,
+ * calls `requestSubmit()` on the enclosing form. Works controlled or uncontrolled.
  *
- * With a `name` a visually-hidden native input submits the joined value as one
- * entry, a form reset restores `defaultValue`, and the ref carries
- * `checkValidity()`/`reportValidity()` — with `required`, an incomplete pin
- * reports `valueMissing`.
+ * With `name`, a hidden input submits the joined value, form reset restores
+ * `defaultValue`, and the ref carries `checkValidity()` / `reportValidity()`.
+ * With `required`, an incomplete pin reports `valueMissing`.
+ *
+ * Renders derived `PinInputField` boxes by default, or children for manual
+ * composition (use `@skdx/react/primitives/pin-input` for that).
  *
  * @example
  * ```tsx
- * <PinInput length={6} type="numeric">
- *   {Array.from({ length: 6 }, (_, i) => (
- *     <PinInputField key={i} index={i} />
- *   ))}
- * </PinInput>
+ * <PinInput length={6} type="numeric" />
  * ```
  */
-export declare const PinInput: React.ForwardRefExoticComponent<Omit<PinInputProps, "ref"> & React.RefAttributes<HTMLDivElement>>;
+export declare const PinInput: React.ForwardRefExoticComponent<Omit<PinInputProps, "ref"> & React.RefAttributes<PinInputHandle>>;

package/dist/pin-input/PinInput.d.ts

@@ -1,5 +1,5 @@
 import * as React from 'react';
-import type { PinInputContextValue, PinInputProps } from './types.js';
+import type { PinInputContextValue, PinInputHandle, PinInputProps } from './types.js';
 export declare const PinInputProvider: {
     (props: PinInputContextValue & {
         children: React.ReactNode;
@@ -7,31 +7,28 @@ export declare const PinInputProvider: {
     displayName: string;
 }, usePinInputContext: (consumerName: string) => PinInputContextValue;
 /**
- * Root of a one-time-passcode input: owns the joined string value and hands
- * it down to `length` `PinInputField` boxes via context. Renders a plain
- * `<div data-disabled data-invalid data-readonly>` — layout of the boxes is
- * entirely up to your CSS. Built as N real `<input maxLength=1>` elements
- * behaving as a single logical string value — the standard, most robust
- * implementation approach (vs. one hidden input + painted boxes).
+ * A one-time-passcode input: owns the joined string value, passes it to
+ * `length` `PinInputField` boxes via context. Renders `<div role="group">`
+ * with boxes as N real `<input maxLength=1>` elements (most robust approach).
  *
- * Works controlled (`value` + `onValueChange`) or uncontrolled (`defaultValue`).
+ * `role="group"` makes the boxes read as one value, not N fields, and holds
+ * `aria-invalid`. It auto-wires an enclosing {@link Field}: the root precedes
+ * its boxes, so Field discovers it and writes `aria-describedby` here. Name it
+ * with `aria-label` / `aria-labelledby`, or use `FieldLabel`.
  *
- * Fires `onValueComplete` once the last box is filled — with `autoSubmit`, it
- * also calls `requestSubmit()` on the surrounding form, which is what a
- * one-time-passcode screen usually wants.
+ * Fires `onValueComplete` when the last box fills; with `autoSubmit`,
+ * calls `requestSubmit()` on the enclosing form. Works controlled or uncontrolled.
  *
- * With a `name` a visually-hidden native input submits the joined value as one
- * entry, a form reset restores `defaultValue`, and the ref carries
- * `checkValidity()`/`reportValidity()` — with `required`, an incomplete pin
- * reports `valueMissing`.
+ * With `name`, a hidden input submits the joined value, form reset restores
+ * `defaultValue`, and the ref carries `checkValidity()` / `reportValidity()`.
+ * With `required`, an incomplete pin reports `valueMissing`.
+ *
+ * Renders derived `PinInputField` boxes by default, or children for manual
+ * composition (use `@skdx/react/primitives/pin-input` for that).
  *
  * @example
  * ```tsx
- * <PinInput length={6} type="numeric">
- *   {Array.from({ length: 6 }, (_, i) => (
- *     <PinInputField key={i} index={i} />
- *   ))}
- * </PinInput>
+ * <PinInput length={6} type="numeric" />
  * ```
  */
-export declare const PinInput: React.ForwardRefExoticComponent<Omit<PinInputProps, "ref"> & React.RefAttributes<HTMLDivElement>>;
+export declare const PinInput: React.ForwardRefExoticComponent<Omit<PinInputProps, "ref"> & React.RefAttributes<PinInputHandle>>;

package/dist/pin-input/PinInput.js

@@ -1 +1 @@
-import*as a from"react";import{createSafeContext as A}from"../utils/createContext.js";import{useFormReset as N,useFormValidityHandle as z}from"../utils/formControl.js";import{HiddenInput as K}from"../utils/hiddenInput.js";import{skdxPart as q}from"../utils/part.js";import{Primitive as S}from"../utils/primitive.js";import{useCallbackRef as $}from"../utils/useCallbackRef.js";import{useControllableState as j}from"../utils/useControllableState.js";import{jsx as w,jsxs as _}from"react/jsx-runtime";var[B,F]=A("PinInput"),U=a.forwardRef(({value:t,defaultValue:l="",onValueChange:R,length:e=6,disabled:f=!1,invalid:m=!1,readOnly:u=!1,type:y="text",mask:c=!1,onValueComplete:n,autoSubmit:r=!1,sanitize:i,name:p,required:d=!1,...s},E)=>{let[P="",h]=j({prop:t,defaultProp:l,onChange:R}),C=a.useRef([]),I=a.useRef(null),b=a.useRef(null);z(E,I,b),N(I,()=>h(l));let k=$(n),H=a.useRef(P);H.current=P;let D=a.useRef(i);D.current=i;let L=a.useCallback(o=>D.current?.(o)??o,[]),V=a.useCallback(o=>{let v=H.current.length===e;h(o),!(o.length!==e||v)&&(k(o),r&&I.current?.closest("form")?.requestSubmit())},[e,h,k,r]),T=a.useCallback((o,v)=>{C.current[o]=v},[]),O=a.useCallback(o=>{C.current[o]?.focus()},[]);return _(B,{value:P,length:e,type:y,mask:c,disabled:f,invalid:m,readOnly:u,setValue:V,focusIndex:O,registerRef:T,sanitizePaste:L,children:[w(S.div,{"data-disabled":f?"":void 0,"data-invalid":m?"":void 0,"data-readonly":u?"":void 0,...s,...q("pin-input","root",s.className),ref:I}),p&&w(K,{ref:b,type:"text",name:p,value:P,required:d,disabled:f,pattern:d?`.{${e}}`:void 0})]})});U.displayName="PinInput";import*as M from"react";import{useComposedRefs as G}from"../utils/composeRefs.js";import{directionalKey as J,useDirection as Q}from"../utils/direction.js";import{skdxPart as W}from"../utils/part.js";import{composeEventHandlers as g,Primitive as X}from"../utils/primitive.js";import{jsx as Z}from"react/jsx-runtime";var Y=/^[0-9]$/,x=M.forwardRef(({index:t,...l},R)=>{let e=F("PinInputField"),f=Q(),m=G(R,n=>e.registerRef(t,n)),u=e.value[t]??"",y=u!=="",c=n=>{let r=e.value.split("");r[t]=n,e.setValue(r.join("").slice(0,e.length))};return Z(X.input,{inputMode:e.type==="numeric"?"numeric":"text",autoComplete:t===0?"one-time-code":"off",type:e.mask&&y?"password":"text",maxLength:1,disabled:e.disabled,readOnly:e.readOnly,"aria-invalid":e.invalid?!0:void 0,"aria-readonly":e.readOnly?!0:void 0,"data-disabled":e.disabled?"":void 0,"data-invalid":e.invalid?"":void 0,"data-readonly":e.readOnly?"":void 0,...l,value:u,...W("pin-input","field",l.className),ref:m,onChange:g(l.onChange,n=>{if(e.disabled)return;let r=n.target.value;if(r===""){c("");return}e.type==="numeric"&&!Y.test(r)||(c(r),t<e.length-1&&e.focusIndex(t+1))}),onKeyDown:g(l.onKeyDown,n=>{if(e.disabled)return;let r=J(n.key,n.currentTarget,f);if(r==="Backspace"){if(e.readOnly)return;if(n.preventDefault(),u)c("");else if(t>0){let i=e.value.split("");i[t-1]="",e.setValue(i.join("").slice(0,e.length)),e.focusIndex(t-1)}}else r==="ArrowLeft"?t>0&&(n.preventDefault(),e.focusIndex(t-1)):r==="ArrowRight"&&t<e.length-1&&(n.preventDefault(),e.focusIndex(t+1))}),onPaste:g(l.onPaste,n=>{if(e.disabled||e.readOnly)return;n.preventDefault();let r=e.sanitizePaste(n.clipboardData.getData("text")),i=e.type==="numeric"?r.replace(/[^0-9]/g,""):r;if(!i)return;let p=e.value.split(""),d=t-1;for(let s=0;s<i.length&&t+s<e.length;s++)p[t+s]=i[s],d=t+s;e.setValue(p.join("").slice(0,e.length)),e.focusIndex(Math.min(d+1,e.length-1))})})});x.displayName="PinInputField";export{U as PinInput,x as PinInputField,B as PinInputProvider,F as usePinInputContext};
+import*as r from"react";import{createSafeContext as ve}from"../utils/createContext.js";import{formValidityHandle as Ce,useFormReset as xe}from"../utils/formControl.js";import{HiddenInput as ke}from"../utils/hiddenInput.js";import{isDevMode as we}from"../utils/is-dev-mode.js";import{skdxPart as Fe}from"../utils/part.js";import{Primitive as Ae}from"../utils/primitive.js";import{useCallbackRef as W}from"../utils/useCallbackRef.js";import{useControllableState as De}from"../utils/useControllableState.js";var me={text:null,numeric:/^[0-9]$/,alphanumeric:/^[a-zA-Z0-9]$/,alphabetic:/^[a-zA-Z]$/};function U(n,a){if(a){let e=new RegExp(a);return f=>e.test(f)}let l=me[n]??null;return l?e=>l.test(e):()=>!0}function T(n,a){return`Digit ${n} of ${a}`}import*as Y from"react";import{useComposedRefs as Pe}from"../utils/composeRefs.js";import{directionalKey as Ie,useDirection as be}from"../utils/direction.js";import{skdxPart as Re}from"../utils/part.js";import{composeEventHandlers as k,Primitive as he}from"../utils/primitive.js";import{jsx as ge}from"react/jsx-runtime";var E=Y.forwardRef(({index:n,...a},l)=>{let e=G("PinInputField"),f=be(),b=Pe(l,o=>e.registerRef(n,o)),u=e.charAt(n),R=u!=="",p=o=>e.setCharAt(n,o);return ge(he.input,{inputMode:e.type==="numeric"?"numeric":"text",autoComplete:e.otp&&n===0?"one-time-code":"off",type:e.mask&&R?"password":"text",placeholder:e.placeholder,maxLength:1,disabled:e.disabled,readOnly:e.readOnly,"aria-label":e.digitLabel(n+1,e.length),"aria-readonly":e.readOnly?!0:void 0,"data-disabled":e.disabled?"":void 0,"data-invalid":e.invalid?"":void 0,"data-readonly":e.readOnly?"":void 0,...a,value:u,...Re("pin-input","field",a.className),ref:b,onChange:k(a.onChange,o=>{if(e.disabled)return;let s=o.target.value;if(s===""){p("");return}if(!e.accepts(s)){o.target.value=u,e.reportInvalid(s,n);return}p(s),n<e.length-1&&e.focusIndex(n+1)}),onFocus:k(a.onFocus,o=>{e.selectOnFocus&&o.currentTarget.select()}),onKeyDown:k(a.onKeyDown,o=>{if(e.disabled)return;let s=Ie(o.key,o.currentTarget,f);if(s==="Backspace"){if(e.readOnly)return;o.preventDefault(),u?p(""):n>0&&(e.setCharAt(n-1,""),e.focusIndex(n-1))}else if(s==="Delete"){if(e.readOnly)return;o.preventDefault(),u&&p("")}else s==="ArrowLeft"?n>0&&(o.preventDefault(),e.focusIndex(n-1)):s==="ArrowRight"&&n<e.length-1&&(o.preventDefault(),e.focusIndex(n+1))}),onPaste:k(a.onPaste,o=>{if(e.disabled||e.readOnly)return;o.preventDefault();let s=e.sanitizePaste(o.clipboardData.getData("text")),d="";for(let h of s)e.accepts(h)?d+=h:e.reportInvalid(h,Math.min(n+d.length,e.length-1));if(!d)return;let v=e.fillFrom(n,d);e.focusIndex(Math.min(v+1,e.length-1))})})});E.displayName="PinInputField";import{Fragment as ye,jsx as J}from"react/jsx-runtime";function Q({length:n}){return J(ye,{children:Array.from({length:n},(a,l)=>J(E,{index:l},l))})}function H(n,a){return Array.from({length:a},(l,e)=>n[e]??"")}function L(n){return n.join("")}import{jsx as M,jsxs as Ee}from"react/jsx-runtime";var[Te,G]=ve("PinInput"),X=r.forwardRef(({value:n,defaultValue:a="",onValueChange:l,length:e=6,disabled:f=!1,invalid:b=!1,readOnly:u=!1,type:R="text",pattern:p,placeholder:o,otp:s=!0,autoFocus:d=!1,blurOnComplete:v=!1,selectOnFocus:h=!1,mask:ee=!1,onValueComplete:te,onValueInvalid:ne,autoSubmit:O=!1,sanitize:$,name:S,form:V,required:z=!1,digitLabel:N=T,children:re,...B},oe)=>{let[c="",w]=De({prop:n,defaultProp:a,onChange:l}),g=r.useRef([]),m=r.useRef(null),F=r.useRef(null);xe(m,()=>w(a),V);let K=W(te),_=W(ne??(()=>{})),ae=r.useMemo(()=>U(R,p),[R,p]),ie=r.useCallback((t,i)=>_({value:t,index:i}),[_]),j=r.useRef(c);j.current=c;let q=r.useRef($);q.current=$;let Z=r.useRef(N);Z.current=N;let se=r.useCallback(t=>q.current?.(t)??t,[]),le=r.useCallback((t,i)=>Z.current(t,i),[]),A=r.useCallback(t=>{let i=j.current.length===e;w(t),!(t.length!==e||i)&&(K(t),v&&(g.current.find(D=>D===document.activeElement)??g.current[e-1])?.blur(),O&&(F.current?.form??m.current?.closest("form"))?.requestSubmit())},[e,w,K,v,O]),P=r.useRef(H(c,e));(P.current.length!==e||L(P.current)!==c)&&(P.current=H(c,e));let ue=r.useCallback(t=>P.current[t]??"",[]),C=r.useCallback(t=>{let i=[...P.current];t(i),P.current=i,A(L(i))},[A]),ce=r.useCallback((t,i)=>{C(y=>{y[t]=i})},[C]),fe=r.useCallback((t,i)=>{let y=t-1;return C(D=>{for(let I=0;I<i.length&&t+I<e;I++)D[t+I]=i[I],y=t+I}),y},[C,e]),pe=r.useCallback((t,i)=>{g.current[t]=i},[]);r.useEffect(()=>{if(!we())return;let t=g.current.filter(Boolean).length;t!==0&&t!==e&&console.warn(`PinInput: ${t} PinInputField${t===1?"":"s"} rendered but length is ${e}. Render exactly one field per position, with contiguous \`index\` values from 0 to ${e-1} \u2014 otherwise the value can never complete and value-complete never fires.`)},[e,c]);let x=r.useCallback(t=>{g.current[t]?.focus()},[]),de=r.useRef(d);return r.useEffect(()=>{de.current&&x(0)},[x]),r.useImperativeHandle(oe,()=>{let t={...Ce(F),clear:()=>A(""),focus:()=>x(0)};return m.current?(Object.defineProperties(m.current,Object.getOwnPropertyDescriptors(t)),m.current):t}),Ee(Te,{value:c,length:e,type:R,mask:ee,disabled:f,invalid:b,readOnly:u,placeholder:o,otp:s,selectOnFocus:h,accepts:ae,reportInvalid:ie,charAt:ue,setCharAt:ce,fillFrom:fe,focusIndex:x,registerRef:pe,sanitizePaste:se,digitLabel:le,children:[M(Ae.div,{role:"group","aria-invalid":b?!0:void 0,"data-disabled":f?"":void 0,"data-invalid":b?"":void 0,"data-readonly":u?"":void 0,...B,...Fe("pin-input","root",B.className),ref:m,children:re??M(Q,{length:e})}),S&&M(ke,{ref:F,type:"text",name:S,value:c,required:z,disabled:f,form:V,pattern:z?`.{${e}}`:void 0})]})});X.displayName="PinInput";export{X as PinInput,E as PinInputField,Te as PinInputProvider,T as pinInputDigitLabel,G as usePinInputContext};

package/dist/pin-input/PinInputAnatomy.d.cts

@@ -0,0 +1,9 @@
+/**
+ * The anatomy a {@link PinInput} draws when given no children: `length`
+ * boxes, one `PinInputField` per position.
+ *
+ * @internal
+ */
+export declare function PinInputAnatomy({ length }: {
+    length: number;
+}): import("react").JSX.Element;

package/dist/pin-input/PinInputAnatomy.d.ts

@@ -0,0 +1,9 @@
+/**
+ * The anatomy a {@link PinInput} draws when given no children: `length`
+ * boxes, one `PinInputField` per position.
+ *
+ * @internal
+ */
+export declare function PinInputAnatomy({ length }: {
+    length: number;
+}): import("react").JSX.Element;

package/dist/pin-input/PinInputField.d.cts

@@ -1,16 +1,14 @@
 import * as React from 'react';
 import type { PinInputFieldProps } from './types.cjs';
 /**
- * A single character box of a {@link PinInput}. Reads/writes its character
- * at `index` in the shared value via context. Sets `maxLength={1}`,
- * `inputMode` from the pin's `type`, `autoComplete="one-time-code"` on the
- * first box, renders `type="password"` once filled when `mask` is set, and
- * carries `aria-invalid`/`data-invalid` plus the native `readOnly` attribute
- * with `aria-readonly`/`data-readonly` from the root's `invalid`/`readOnly`
- * props. Typing or pasting auto-advances focus to the next box; Backspace on
- * an empty box clears and focuses the previous one; Arrow Left/Right move
- * focus between boxes; pasting a multi-character string fills consecutive
- * boxes from `index` onward.
+ * A single character box of a {@link PinInput}. Reads/writes its character at `index` via context. Sets
+ * `maxLength={1}`, `inputMode` from the pin's `type`, `autoComplete="one-time-code"` on the first box, and
+ * renders `type="password"` once filled when `mask` is set.
+ *
+ * Named "Digit 3 of 6" by the root's `digitLabel`, since an `<input>` has no content to take a name from.
+ * Pass your own `aria-label` to override it. No `aria-invalid` here on purpose — it belongs once on the
+ * `role="group"` root. Typing/pasting auto-advances focus; Backspace on an empty box clears and focuses the
+ * previous one; Arrow Left/Right move focus between boxes; a multi-character paste fills consecutive boxes.
  *
  * @example
  * ```tsx

package/dist/pin-input/PinInputField.d.ts

@@ -1,16 +1,14 @@
 import * as React from 'react';
 import type { PinInputFieldProps } from './types.js';
 /**
- * A single character box of a {@link PinInput}. Reads/writes its character
- * at `index` in the shared value via context. Sets `maxLength={1}`,
- * `inputMode` from the pin's `type`, `autoComplete="one-time-code"` on the
- * first box, renders `type="password"` once filled when `mask` is set, and
- * carries `aria-invalid`/`data-invalid` plus the native `readOnly` attribute
- * with `aria-readonly`/`data-readonly` from the root's `invalid`/`readOnly`
- * props. Typing or pasting auto-advances focus to the next box; Backspace on
- * an empty box clears and focuses the previous one; Arrow Left/Right move
- * focus between boxes; pasting a multi-character string fills consecutive
- * boxes from `index` onward.
+ * A single character box of a {@link PinInput}. Reads/writes its character at `index` via context. Sets
+ * `maxLength={1}`, `inputMode` from the pin's `type`, `autoComplete="one-time-code"` on the first box, and
+ * renders `type="password"` once filled when `mask` is set.
+ *
+ * Named "Digit 3 of 6" by the root's `digitLabel`, since an `<input>` has no content to take a name from.
+ * Pass your own `aria-label` to override it. No `aria-invalid` here on purpose — it belongs once on the
+ * `role="group"` root. Typing/pasting auto-advances focus; Backspace on an empty box clears and focuses the
+ * previous one; Arrow Left/Right move focus between boxes; a multi-character paste fills consecutive boxes.
  *
  * @example
  * ```tsx

package/dist/pin-input/charFilter.d.cts

@@ -0,0 +1,19 @@
+/** The character sets `type` names, in the spelling the contract declares. */
+export type PinInputType = 'text' | 'numeric' | 'alphanumeric' | 'alphabetic';
+/**
+ * Builds the per-character predicate from `type` and `pattern`.
+ *
+ * `pattern` replaces `type` rather than narrowing it: two filters that both had
+ * to pass would make `pattern` unable to *widen* anything, and widening is what
+ * a hex code (`[A-Fa-f0-9]`) needs from a component whose built-in sets are
+ * letters, digits, or both.
+ */
+export declare function pinCharAcceptor(type: PinInputType, pattern?: string): (char: string) => boolean;
+/**
+ * The source of the expression {@link pinCharAcceptor} actually applies, for
+ * reporting rather than for matching — Angular's `NG_VALIDATORS` puts it in the
+ * `{ pattern: { requiredPattern } }` payload, where a consumer renders it.
+ * `'.'` for `'text'`, which accepts everything and so has no expression of its
+ * own to name.
+ */
+export declare function pinCharPattern(type: PinInputType, pattern?: string): string;

package/dist/pin-input/charFilter.d.ts

@@ -0,0 +1,19 @@
+/** The character sets `type` names, in the spelling the contract declares. */
+export type PinInputType = 'text' | 'numeric' | 'alphanumeric' | 'alphabetic';
+/**
+ * Builds the per-character predicate from `type` and `pattern`.
+ *
+ * `pattern` replaces `type` rather than narrowing it: two filters that both had
+ * to pass would make `pattern` unable to *widen* anything, and widening is what
+ * a hex code (`[A-Fa-f0-9]`) needs from a component whose built-in sets are
+ * letters, digits, or both.
+ */
+export declare function pinCharAcceptor(type: PinInputType, pattern?: string): (char: string) => boolean;
+/**
+ * The source of the expression {@link pinCharAcceptor} actually applies, for
+ * reporting rather than for matching — Angular's `NG_VALIDATORS` puts it in the
+ * `{ pattern: { requiredPattern } }` payload, where a consumer renders it.
+ * `'.'` for `'text'`, which accepts everything and so has no expression of its
+ * own to name.
+ */
+export declare function pinCharPattern(type: PinInputType, pattern?: string): string;

package/dist/pin-input/digitLabel.d.cts

@@ -0,0 +1,7 @@
+/**
+ * The default accessible name for a pin box. `index` is 1-based (read aloud).
+ *
+ * @param index the box's position, counting from 1
+ * @param length how many boxes the code has
+ */
+export declare function pinInputDigitLabel(index: number, length: number): string;

package/dist/pin-input/digitLabel.d.ts

@@ -0,0 +1,7 @@
+/**
+ * The default accessible name for a pin box. `index` is 1-based (read aloud).
+ *
+ * @param index the box's position, counting from 1
+ * @param length how many boxes the code has
+ */
+export declare function pinInputDigitLabel(index: number, length: number): string;

package/dist/pin-input/index.d.cts

@@ -1,3 +1,4 @@
-export * from './PinInput.cjs';
-export { PinInputField } from './PinInputField.cjs';
-export type { PinInputProps, PinInputHandle, PinInputFieldProps } from './types.cjs';
+export { PinInput } from './PinInput.cjs';
+export { pinInputDigitLabel } from './digitLabel.cjs';
+export type { PinInputType } from './charFilter.cjs';
+export type { PinInputProps, PinInputHandle, PinInputInvalidDetail } from './types.cjs';

package/dist/pin-input/index.d.ts

@@ -1,3 +1,4 @@
-export * from './PinInput.js';
-export { PinInputField } from './PinInputField.js';
-export type { PinInputProps, PinInputHandle, PinInputFieldProps } from './types.js';
+export { PinInput } from './PinInput.js';
+export { pinInputDigitLabel } from './digitLabel.js';
+export type { PinInputType } from './charFilter.js';
+export type { PinInputProps, PinInputHandle, PinInputInvalidDetail } from './types.js';

package/dist/pin-input/primitives.d.cts

@@ -0,0 +1,18 @@
+/**
+ * `PinInput` and `PinInputField` primitives.
+ *
+ * @example
+ * ```tsx
+ * import { PinInput, PinInputField } from '@skdx/react/primitives/pin-input';
+ *
+ * <PinInput length={4}>
+ *   <PinInputField index={0} />
+ *   <PinInputField index={1} />
+ *   <PinInputField index={2} />
+ *   <PinInputField index={3} />
+ * </PinInput>
+ * ```
+ */
+export { PinInput } from './PinInput.cjs';
+export { PinInputField } from './PinInputField.cjs';
+export type { PinInputProps, PinInputHandle, PinInputFieldProps } from './types.cjs';

package/dist/pin-input/primitives.d.ts

@@ -0,0 +1,18 @@
+/**
+ * `PinInput` and `PinInputField` primitives.
+ *
+ * @example
+ * ```tsx
+ * import { PinInput, PinInputField } from '@skdx/react/primitives/pin-input';
+ *
+ * <PinInput length={4}>
+ *   <PinInputField index={0} />
+ *   <PinInputField index={1} />
+ *   <PinInputField index={2} />
+ *   <PinInputField index={3} />
+ * </PinInput>
+ * ```
+ */
+export { PinInput } from './PinInput.js';
+export { PinInputField } from './PinInputField.js';
+export type { PinInputProps, PinInputHandle, PinInputFieldProps } from './types.js';

package/dist/pin-input/slots.d.cts

@@ -0,0 +1,11 @@
+/**
+ * Pin input data model: fixed-length array of single characters, not a string.
+ *
+ * A string cannot hold empty positions (holes); an array can, so box 3 stays box 3 whether filled or not.
+ *
+ * @internal
+ */
+/** Split value into slots (left-packed for external values, holes from skipped boxes). */
+export declare function toPinSlots(value: string, length: number): string[];
+/** Join slots back into string, omitting holes. */
+export declare function joinPinSlots(slots: readonly string[]): string;

package/dist/pin-input/slots.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Pin input data model: fixed-length array of single characters, not a string.
+ *
+ * A string cannot hold empty positions (holes); an array can, so box 3 stays box 3 whether filled or not.
+ *
+ * @internal
+ */
+/** Split value into slots (left-packed for external values, holes from skipped boxes). */
+export declare function toPinSlots(value: string, length: number): string[];
+/** Join slots back into string, omitting holes. */
+export declare function joinPinSlots(slots: readonly string[]): string;

package/dist/pin-input/types.d.cts

@@ -1,18 +1,43 @@
-import type { FormValidityHandle } from '../utils/formControl.cjs';
 import type { PrimitivePropsWithRef } from '../utils/primitive.cjs';
+import type { PinInputType } from './charFilter.cjs';
+/** What a rejected character reports: the character, and the box it was aimed at. */
+export interface PinInputInvalidDetail {
+    /** The character the `type`/`pattern` filter refused. */
+    value: string;
+    /** The 0-based index of the box it was typed or pasted into. */
+    index: number;
+}
 /** @internal Shared state distributed from {@link PinInput} to its `PinInputField`s via context. Not part of the public API. */
 export interface PinInputContextValue {
+    /** The joined value. Boxes read {@link charAt} instead; this is what changes identity to re-render them. */
     value: string;
     length: number;
-    type: 'text' | 'numeric';
+    type: PinInputType;
     mask: boolean;
     disabled: boolean;
     invalid: boolean;
     readOnly: boolean;
-    setValue: (next: string) => void;
+    /** A single character drawn in every empty box, or `undefined` for none. */
+    placeholder?: string;
+    /** Whether box 0 advertises `autocomplete="one-time-code"`. */
+    otp: boolean;
+    /** Whether a box selects the character it already holds when focus lands in it. */
+    selectOnFocus: boolean;
+    /** Whether this character passes the root's `type`/`pattern` filter, so a keystroke and a paste are judged alike. */
+    accepts: (char: string) => boolean;
+    /** Publishes `value-invalid` for a character the filter refused. */
+    reportInvalid: (char: string, index: number) => void;
+    /** The character in the box at `index`, read from the fixed-length slot array so boxes never shift left. */
+    charAt: (index: number) => string;
+    /** Writes one box's character (`''` clears it) and publishes the joined value. */
+    setCharAt: (index: number, char: string) => void;
+    /** Writes consecutive boxes from `index` onward, truncating at the last, returning the last index written. */
+    fillFrom: (index: number, chars: string) => number;
     focusIndex: (index: number) => void;
     registerRef: (index: number, node: HTMLInputElement | null) => void;
     sanitizePaste: (pasted: string) => string;
+    /** Words a box's `aria-label` from its 1-based position and the pin's length. */
+    digitLabel: (index: number, length: number) => string;
 }
 /** Props for the {@link PinInput} root. */
 export interface PinInputProps extends Omit<PrimitivePropsWithRef<'div'>, 'defaultValue' | 'onChange'> {
@@ -42,18 +67,53 @@ export interface PinInputProps extends Omit<PrimitivePropsWithRef<'div'>, 'defau
      */
     disabled?: boolean;
     /**
-     * `'numeric'` restricts each box to digits 0-9 and sets `inputMode="numeric"`.
+     * Which characters a box accepts; `pattern` overrides it entirely.
      * @default 'text'
      */
-    type?: 'text' | 'numeric';
+    type?: PinInputType;
+    /**
+     * A regular-expression source tested against **one character at a time**, replacing whatever set `type` names.
+     * @default undefined — `type` decides.
+     */
+    pattern?: string;
+    /**
+     * A single character drawn in every empty box, so the boxes read as slots waiting for a code.
+     * @default undefined — empty boxes are blank.
+     */
+    placeholder?: string;
+    /**
+     * Advertises `autocomplete="one-time-code"` on the first box only — a second such field suppresses both.
+     * @default true
+     */
+    otp?: boolean;
+    /**
+     * Focuses the first box on mount.
+     * @default false
+     */
+    autoFocus?: boolean;
+    /**
+     * Blurs the focused box the moment the code completes, running after `onValueComplete`.
+     * @default false
+     */
+    blurOnComplete?: boolean;
+    /**
+     * Selects a box's existing character when focus lands in it, on click, Tab and auto-advance alike.
+     * @default false
+     */
+    selectOnFocus?: boolean;
+    /**
+     * Fires once per character the `type`/`pattern` filter refused, with the index of the box it was aimed at.
+     * @default undefined — no-op if omitted.
+     */
+    onValueInvalid?: (detail: PinInputInvalidDetail) => void;
     /**
      * Renders filled boxes as `type="password"` (dots) instead of plain text.
      * @default false
      */
     mask?: boolean;
     /**
-     * Marks the field as invalid, exposed as `data-invalid` on the root and
-     * `aria-invalid`/`data-invalid` on every `PinInputField`.
+     * Marks the field as invalid: `aria-invalid` on the `role="group"` root,
+     * `data-invalid` on the root and every field.
      * @default false
      */
     invalid?: boolean;
@@ -64,9 +124,7 @@ export interface PinInputProps extends Omit<PrimitivePropsWithRef<'div'>, 'defau
      */
     readOnly?: boolean;
     /**
-     * Fires with the full value the moment the last box is filled — the point a
-     * one-time-passcode UI verifies the code. Fires once per completion, not on
-     * every keystroke that keeps it complete.
+     * Fires with the full value once per completion, not on every keystroke that keeps it complete.
      * @default undefined — no-op if omitted.
      */
     onValueComplete?: (value: string) => void;
@@ -77,33 +135,55 @@ export interface PinInputProps extends Omit<PrimitivePropsWithRef<'div'>, 'defau
      */
     autoSubmit?: boolean;
     /**
-     * Cleans pasted text before it is distributed across the boxes — strip the
-     * spaces and dashes an authenticator app copies along with the code. Runs
-     * before the `type="numeric"` digit filter.
+     * Cleans pasted text before it is distributed across the boxes, running before the `type` filter.
      * @default undefined — pasted text is used as-is.
      */
     sanitize?: (pasted: string) => string;
     /**
-     * Form field name. With it, a visually-hidden native input submits the
-     * joined value as a single entry — one `name=123456`, not one entry per box
-     * — matching what `<skdx-pin-input>` publishes through ElementInternals. A
-     * form reset restores `defaultValue`.
+     * Form field name; a hidden input submits the joined value as one entry, matching what `<skdx-pin-input>` publishes.
      * @default undefined — submits nothing.
      */
     name?: string;
+    /**
+     * Id of the `<form>` this pin submits into, for a pin rendered outside it (a portalled Dialog).
+     * @default undefined — the pin belongs to its nearest ancestor `<form>`, if any.
+     */
+    form?: string;
     /**
      * Marks the pin required: with `name`, native `valueMissing` until every box
      * is filled, reported through `checkValidity()`/`reportValidity()`.
      * @default false
      */
     required?: boolean;
+    /**
+     * Words each `PinInputField`'s `aria-label` from the box's **1-based** position and the pin's `length`.
+     *
+     * A consumer's own `aria-label` on a `PinInputField` still wins over it.
+     * @default {@link pinInputDigitLabel} — `` `Digit ${index} of ${length}` ``
+     */
+    digitLabel?: (index: number, length: number) => string;
 }
 /**
- * What {@link PinInput}'s forwarded ref carries: the root `<div>` plus the two
- * constraint-validation methods. Type your ref as this to call them —
- * `React.useRef<PinInputHandle>(null)`.
+ * What {@link PinInput}'s forwarded ref carries: the root `<div>` with the constraint-validation methods, `clear()` and `focus()` assigned onto it.
  */
-export type PinInputHandle = HTMLDivElement & FormValidityHandle;
+export interface PinInputHandle extends HTMLDivElement {
+    /** Returns whether the current code satisfies its constraints, firing `invalid` if not. */
+    checkValidity(): boolean;
+    /** Like {@link PinInputHandle.checkValidity}, but also shows the browser's validation message. */
+    reportValidity(): boolean;
+    /**
+     * Pushes an externally-computed error in, exactly like `HTMLInputElement.setCustomValidity()`; `''` clears it.
+     */
+    setCustomValidity(message: string): void;
+    /**
+     * Empties every box and publishes the empty value — the only imperative writer, since `value` is already controllable.
+     */
+    clear(): void;
+    /**
+     * Moves DOM focus into the first box, shadowing the root `<div>`'s own no-op `focus()`.
+     */
+    focus(): void;
+}
 /** Props for a single {@link PinInputField} character box. */
 export interface PinInputFieldProps extends Omit<PrimitivePropsWithRef<'input'>, 'value' | 'defaultValue' | 'type'> {
     /** This box's 0-indexed position within the pin's value. */