@skdx/react 0.26.0 → 0.28.0

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

@@ -1,18 +1,43 @@
-import type { FormValidityHandle } from '../utils/formControl.js';
 import type { PrimitivePropsWithRef } from '../utils/primitive.js';
+import type { PinInputType } from './charFilter.js';
+/** 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. */

package/dist/popover/Popover.cjs

@@ -1 +1 @@
-"use strict";var Z=Object.create;var c=Object.defineProperty;var _=Object.getOwnPropertyDescriptor;var $=Object.getOwnPropertyNames;var j=Object.getPrototypeOf,oo=Object.prototype.hasOwnProperty;var eo=(o,e)=>{for(var r in e)c(o,r,{get:e[r],enumerable:!0})},E=(o,e,r,p)=>{if(e&&typeof e=="object"||typeof e=="function")for(let n of $(e))!oo.call(o,n)&&n!==r&&c(o,n,{get:()=>e[n],enumerable:!(p=_(e,n))||p.enumerable});return o};var v=(o,e,r)=>(r=o!=null?Z(j(o)):{},E(e||!o||!o.__esModule?c(r,"default",{value:o,enumerable:!0}):r,o)),ro=o=>E(c({},"__esModule",{value:!0}),o);var po={};eo(po,{Popover:()=>L,PopoverAnchor:()=>to,PopoverArrow:()=>M,PopoverClose:()=>w,PopoverContent:()=>O,PopoverPortal:()=>T,PopoverProvider:()=>A,PopoverTrigger:()=>h,usePopoverContext:()=>s});module.exports=ro(po);var m=v(require("react"),1),N=require("../utils/createContext.cjs"),k=require("../utils/part.cjs"),P=require("../utils/popper.cjs"),H=require("../utils/useControllableState.cjs"),b=require("../utils/useOpenChangeComplete.cjs"),d=require("react/jsx-runtime"),[A,s]=(0,N.createSafeContext)("Popover");function L({children:o,open:e,defaultOpen:r=!1,onOpenChange:p,onOpenChangeComplete:n,modal:R=!1}){let f=m.useRef(null),l=m.useRef(null),[i=!1,x]=(0,H.useControllableState)({prop:e,defaultProp:r,onChange:p});return(0,b.useOpenChangeComplete)(i,l,n),(0,d.jsx)(P.PopperRoot,{children:(0,d.jsx)(A,{triggerRef:f,contentRef:l,contentId:m.useId(),open:i,onOpenChange:x,modal:R,children:o})})}L.displayName="Popover";var to=P.PopperAnchor,M=m.forwardRef((o,e)=>(0,d.jsx)(P.PopperArrow,{...o,...(0,k.skdxPart)("popover","arrow",o.className),ref:e}));M.displayName="PopoverArrow";var D=v(require("react"),1),I=require("../utils/composeRefs.cjs"),B=require("../utils/part.cjs"),S=require("../utils/popper.cjs"),u=require("../utils/primitive.cjs");var y=require("react/jsx-runtime"),h=D.forwardRef((o,e)=>{let r=s("PopoverTrigger"),p=(0,I.useComposedRefs)(e,r.triggerRef);return(0,y.jsx)(S.PopperAnchor,{asChild:!0,children:(0,y.jsx)(u.Primitive.button,{type:"button","aria-haspopup":"dialog","aria-expanded":r.open,"aria-controls":r.contentId,"data-state":r.open?"open":"closed",...o,...(0,B.skdxPart)("popover","trigger",o.className),ref:p,onClick:(0,u.composeEventHandlers)(o.onClick,()=>r.onOpenChange(!r.open))})})});h.displayName="PopoverTrigger";var F=require("../utils/portal.cjs");var V=require("react/jsx-runtime"),T=({forceMount:o,children:e,...r})=>{let p=s("PopoverPortal");return o||p.open?(0,V.jsx)(F.Portal,{...r,children:e}):null};T.displayName="PopoverPortal";var W=v(require("react"),1),K=require("../utils/composeRefs.cjs"),q=require("../utils/part.cjs"),z=require("../utils/popper.cjs"),G=require("../utils/useDismiss.cjs"),C=require("../utils/useFocusTrap.cjs");var J=require("react/jsx-runtime"),O=W.forwardRef(({forceMount:o,onEscapeKeyDown:e,onPointerDownOutside:r,onFocusOutside:p,onInteractOutside:n,onOpenAutoFocus:R,onCloseAutoFocus:f,sideOffset:l=4,...i},x)=>{let t=s("PopoverContent"),Y=(0,K.useComposedRefs)(x,t.contentRef);return(0,C.useFocusTrap)(t.contentRef,t.open&&t.modal,{onOpenAutoFocus:R,onCloseAutoFocus:f}),(0,G.useDismiss)({enabled:t.open,onEscapeKeyDown:a=>{e?.(a),!a.defaultPrevented&&(t.onOpenChange(!1),(t.modal||(0,C.autoFocusEvent)("close-auto-focus",f))&&t.triggerRef.current?.focus())},onInteractOutside:n,onPointerDownOutside:a=>{r?.(a),a.defaultPrevented||t.onOpenChange(!1)},onFocusOutside:a=>{p?.(a),a.defaultPrevented||t.onOpenChange(!1)}},[t.contentRef,t.triggerRef]),o||t.open?(0,J.jsx)(z.PopperContent,{component:"popover",role:"dialog",id:t.contentId,"data-state":t.open?"open":"closed",sideOffset:l,...i,...(0,q.skdxPart)("popover","content",i.className),ref:Y}):null});O.displayName="PopoverContent";var Q=v(require("react"),1),U=require("../utils/part.cjs"),g=require("../utils/primitive.cjs");var X=require("react/jsx-runtime"),w=Q.forwardRef((o,e)=>{let r=s("PopoverClose");return(0,X.jsx)(g.Primitive.button,{type:"button",...o,...(0,U.skdxPart)("popover","close",o.className),ref:e,onClick:(0,g.composeEventHandlers)(o.onClick,()=>r.onOpenChange(!1))})});w.displayName="PopoverClose";0&&(module.exports={Popover,PopoverAnchor,PopoverArrow,PopoverClose,PopoverContent,PopoverPortal,PopoverProvider,PopoverTrigger,usePopoverContext});
+"use strict";var wo=Object.create;var b=Object.defineProperty;var bo=Object.getOwnPropertyDescriptor;var Eo=Object.getOwnPropertyNames;var ko=Object.getPrototypeOf,Do=Object.prototype.hasOwnProperty;var Ho=(o,e)=>{for(var t in e)b(o,t,{get:e[t],enumerable:!0})},K=(o,e,t,n)=>{if(e&&typeof e=="object"||typeof e=="function")for(let a of Eo(e))!Do.call(o,a)&&a!==t&&b(o,a,{get:()=>e[a],enumerable:!(n=bo(e,a))||n.enumerable});return o};var R=(o,e,t)=>(t=o!=null?wo(ko(o)):{},K(e||!o||!o.__esModule?b(t,"default",{value:o,enumerable:!0}):t,o)),Ao=o=>K(b({},"__esModule",{value:!0}),o);var Mo={};Ho(Mo,{Popover:()=>xo,PopoverAnchor:()=>Lo,PopoverArrow:()=>B,PopoverClose:()=>k,PopoverContent:()=>A,PopoverDescription:()=>F,PopoverPortal:()=>S,PopoverProvider:()=>yo,PopoverRoot:()=>_,PopoverTitle:()=>M,PopoverTrigger:()=>I,usePopoverContext:()=>l});module.exports=Ao(Mo);var i=R(require("react"),1),go=require("../utils/createContext.cjs"),Ro=require("../utils/part.cjs"),C=require("../utils/popper.cjs"),ho=require("../utils/useControllableState.cjs"),Co=require("../utils/useOpenChangeComplete.cjs");var z=R(require("react"),1),G=require("../utils/part.cjs"),E=require("../utils/primitive.cjs");var J=require("react/jsx-runtime"),k=z.forwardRef((o,e)=>{let t=l("PopoverClose");return(0,J.jsx)(E.Primitive.button,{type:"button",...o,...(0,G.skdxPart)("popover","close",o.className),ref:e,onClick:(0,E.composeEventHandlers)(o.onClick,()=>t.onOpenChange(!1))})});k.displayName="PopoverClose";var D=R(require("react"),1),Q=require("../utils/composeRefs.cjs"),U=require("../utils/is-dev-mode.cjs"),X=require("../utils/part.cjs"),Y=require("../utils/popper.cjs"),Z=require("../utils/tabbable.cjs"),j=require("../utils/useBodyScrollLock.cjs"),oo=require("../utils/useDismiss.cjs"),H=require("../utils/useFocusTrap.cjs"),eo=require("../utils/useOutsideInert.cjs");var W=require("../utils/is-dev-mode.cjs");function q(o,e,t){if(!e)return null;let n;try{n=o.querySelector(e)}catch{return(0,W.isDevMode)()&&console.warn(`[skdx] Popover: ${t}="${e}" is not a valid CSS selector. Falling back to the default focus target.`),null}return!n&&(0,W.isDevMode)()&&console.warn(Oo(t,e)),n}function Oo(o,e){return o==="initialFocus"?`[skdx] Popover: initialFocus="${e}" matched no element inside the popover panel. Falling back to the first tabbable element, then the panel itself.`:`[skdx] Popover: finalFocus="${e}" matched no element in the document. Falling back to the trigger.`}var to=require("react/jsx-runtime");function Fo(o,e){D.useEffect(()=>{if(!(0,U.isDevMode)()||!e)return;let t=o.current;!t||t.querySelector(".skdx-popover__close")||console.warn("[skdx] Popover: `modal` contains focus inside PopoverContent, but no PopoverClose was rendered inside it. A user who cannot press Escape \u2014 a touch screen-reader user has no Escape key \u2014 has no way out of the panel. Render a PopoverClose, or set `modal={false}`.")},[o,e])}var A=D.forwardRef(({forceMount:o,onEscapeKeyDown:e,onPointerDownOutside:t,onFocusOutside:n,onInteractOutside:a,onOpenAutoFocus:m,onCloseAutoFocus:f,sideOffset:c=4,arrowPadding:y=8,initialFocus:u,finalFocus:d,...P},v)=>{let r=l("PopoverContent"),x=(0,Q.useComposedRefs)(v,r.contentRef),T=()=>{let p=q(document,d,"finalFocus");return p?(p.focus({preventScroll:!0}),!0):!1},w=r.modal!==!1,To=r.modal===!0;return(0,j.useBodyScrollLock)(r.open&&To),(0,eo.useOutsideInert)(r.contentRef,r.open&&w),(0,H.useFocusTrap)(r.contentRef,r.open&&w,{onOpenAutoFocus:p=>{if(m?.(p),p.defaultPrevented||!u)return;let g=r.contentRef.current;if(!g)return;let V=q(g,u,"initialFocus")??g.querySelector(Z.TABBABLE_SELECTOR)??g;p.preventDefault(),V===g&&g.setAttribute("tabindex","-1"),V.focus({preventScroll:!0})},onCloseAutoFocus:p=>{f?.(p),!(p.defaultPrevented||!d)&&T()&&p.preventDefault()}}),Fo(r.contentRef,r.open&&w),(0,oo.useDismiss)({enabled:r.open,onEscapeKeyDown:p=>{e?.(p),!p.defaultPrevented&&(r.onOpenChange(!1),w?r.triggerRef.current?.focus():(0,H.autoFocusEvent)("close-auto-focus",f)&&(T()||r.triggerRef.current?.focus()))},onInteractOutside:a,onPointerDownOutside:p=>{t?.(p),p.defaultPrevented||r.onOpenChange(!1)},onFocusOutside:p=>{n?.(p),p.defaultPrevented||r.onOpenChange(!1)}},[r.contentRef,r.triggerRef]),o||r.open?(0,to.jsx)(Y.PopperContent,{component:"popover",role:"dialog","aria-labelledby":r.hasTitle?r.titleId:void 0,"aria-describedby":r.hasDescription?r.descriptionId:void 0,id:r.contentId,"data-state":r.open?"open":"closed",sideOffset:c,arrowPadding:y,...P,...(0,X.skdxPart)("popover","content",P.className),ref:x}):null});A.displayName="PopoverContent";var O=R(require("react"),1),ro=require("../utils/part.cjs"),no=require("../utils/primitive.cjs");var po=require("react/jsx-runtime"),F=O.forwardRef((o,e)=>{let t=l("PopoverDescription"),{setHasDescription:n}=t;return O.useEffect(()=>(n(!0),()=>n(!1)),[n]),(0,po.jsx)(no.Primitive.p,{id:t.descriptionId,...o,...(0,ro.skdxPart)("popover","description",o.className),ref:e})});F.displayName="PopoverDescription";var so=require("../utils/portal.cjs");var io=require("react/jsx-runtime"),S=({forceMount:o,children:e,...t})=>{let n=l("PopoverPortal");return o||n.open?(0,io.jsx)(so.Portal,{...t,children:e}):null};S.displayName="PopoverPortal";var L=R(require("react"),1),ao=require("../utils/part.cjs"),lo=require("../utils/primitive.cjs");var co=require("react/jsx-runtime"),M=L.forwardRef((o,e)=>{let t=l("PopoverTitle"),{setHasTitle:n}=t;return L.useEffect(()=>(n(!0),()=>n(!1)),[n]),(0,co.jsx)(lo.Primitive.h2,{id:t.titleId,...o,...(0,ao.skdxPart)("popover","title",o.className),ref:e})});M.displayName="PopoverTitle";var fo=R(require("react"),1),mo=require("../utils/composeRefs.cjs"),uo=require("../utils/part.cjs"),Po=require("../utils/popper.cjs"),N=require("../utils/primitive.cjs");var $=require("react/jsx-runtime"),I=fo.forwardRef((o,e)=>{let t=l("PopoverTrigger"),n=(0,mo.useComposedRefs)(e,t.triggerRef);return(0,$.jsx)(Po.PopperAnchor,{asChild:!0,children:(0,$.jsx)(N.Primitive.button,{type:"button","aria-haspopup":"dialog","aria-expanded":t.open,"aria-controls":t.contentId,"data-state":t.open?"open":"closed",...o,...(0,uo.skdxPart)("popover","trigger",o.className),ref:n,onClick:(0,N.composeEventHandlers)(o.onClick,()=>t.onOpenChange(!t.open))})})});I.displayName="PopoverTrigger";var s=require("react/jsx-runtime"),So=()=>(0,s.jsx)("svg",{viewBox:"0 0 16 16",width:"1em",height:"1em",fill:"none","aria-hidden":"true",focusable:"false",children:(0,s.jsx)("path",{d:"M4 4l8 8M12 4l-8 8",stroke:"currentColor",strokeWidth:"1.5",strokeLinecap:"round"})}),vo=({trigger:o,title:e,description:t,side:n,align:a,showArrow:m,children:f,passThrough:c})=>(0,s.jsxs)(s.Fragment,{children:[o?(0,s.jsx)(I,{asChild:!0,...c?.id?{"aria-controls":c.id}:{},children:o}):null,(0,s.jsx)(S,{children:(0,s.jsxs)(A,{...c,side:n,align:a,children:[e?(0,s.jsx)(M,{children:e}):null,t?(0,s.jsx)(F,{children:t}):null,f,m?(0,s.jsx)(B,{}):null,(0,s.jsx)(k,{"aria-label":"Close",children:(0,s.jsx)(So,{})})]})})]});var h=require("react/jsx-runtime"),[yo,l]=(0,go.createSafeContext)("Popover");function _({children:o,open:e,defaultOpen:t=!1,onOpenChange:n,onOpenChangeComplete:a,modal:m=!1}){let f=i.useRef(null),c=i.useRef(null),[y,u]=i.useState(!1),[d,P]=i.useState(!1),[v=!1,r]=(0,ho.useControllableState)({prop:e,defaultProp:t,onChange:n});(0,Co.useOpenChangeComplete)(v,c,a);let x=i.useRef(null),T=i.useCallback(()=>{x.current?.()},[]);return(0,h.jsx)(C.PopperRoot,{updateRef:x,children:(0,h.jsx)(yo,{triggerRef:f,contentRef:c,contentId:i.useId(),titleId:i.useId(),descriptionId:i.useId(),hasTitle:y,setHasTitle:u,hasDescription:d,setHasDescription:P,open:v,onOpenChange:r,modal:m,reposition:T,children:o})})}_.displayName="PopoverRoot";function xo({children:o,open:e,defaultOpen:t,onOpenChange:n,onOpenChangeComplete:a,modal:m,trigger:f,title:c,description:y,side:u,align:d,showArrow:P=!1,...v}){return(0,h.jsx)(_,{open:e,defaultOpen:t,onOpenChange:n,onOpenChangeComplete:a,modal:m,children:(0,h.jsx)(vo,{trigger:f,title:c,description:y,side:u,align:d,showArrow:P,passThrough:v,children:o})})}xo.displayName="Popover";var Lo=C.PopperAnchor,B=i.forwardRef((o,e)=>(0,h.jsx)(C.PopperArrow,{...o,...(0,Ro.skdxPart)("popover","arrow",o.className),ref:e}));B.displayName="PopoverArrow";0&&(module.exports={Popover,PopoverAnchor,PopoverArrow,PopoverClose,PopoverContent,PopoverDescription,PopoverPortal,PopoverProvider,PopoverRoot,PopoverTitle,PopoverTrigger,usePopoverContext});

package/dist/popover/Popover.d.cts

@@ -7,30 +7,66 @@ export declare const PopoverProvider: {
     }): React.JSX.Element;
     displayName: string;
 }, usePopoverContext: (consumerName: string) => PopoverContextValue;
+/** Props for {@link PopoverRoot}: {@link PopoverProps} minus the derived-anatomy-only props. */
+export type PopoverRootProps = Omit<PopoverProps, 'trigger' | 'title' | 'description' | 'side' | 'align' | 'showArrow'>;
 /**
- * Root of a non-modal-by-default popover: owns open state and hands it down
- * to `PopoverTrigger` / `PopoverAnchor` / `PopoverPortal` / `PopoverContent` /
- * `PopoverArrow` / `PopoverClose` via context. Wraps children in the shared
- * popper positioning root, so `PopoverContent` can float relative to the
- * trigger (or a custom `PopoverAnchor`). Renders no DOM element itself.
+ * State/context primitive that owns open state and hands it down to all popover
+ * parts via context, wrapping in the popper positioning root with no DOM
+ * element rendered. The `Popover` recipe (below) wraps this with
+ * `PopoverAnatomy`, adding the derived anatomy. For full manual part
+ * composition, use `PopoverRoot` from `@skdx/react/primitives/popover`.
  *
- * Works controlled (`open` + `onOpenChange`) or uncontrolled (`defaultOpen`).
+ * `reposition()` — the cross-framework positioning method for an anchor that
+ * moved without the floating layer noticing — is accessed via context:
+ * `usePopoverContext().reposition`, not a ref.
+ */
+export declare function PopoverRoot({ children, open: openProp, defaultOpen, onOpenChange, onOpenChangeComplete, modal, }: PopoverRootProps): React.JSX.Element;
+export declare namespace PopoverRoot {
+    var displayName: string;
+}
+/**
+ * Recipe for a non-modal-by-default popover: owns open state and passes it to
+ * all parts via context, rendering no DOM element itself. Derives the entire
+ * anatomy from `trigger`/`title`/`description`: trigger (merged via `asChild`,
+ * no wrapping), portal, and the panel with derived title, description, and
+ * close button. `children` is the panel's body; the component reads only
+ * whether it exists. Works controlled (`open` + `onOpenChange`) or uncontrolled
+ * (`defaultOpen`).
+ *
+ * `PopoverContent` is `role="dialog"` and must have an accessible name: either
+ * via `title` or, under manual composition without a visible heading, via
+ * `aria-label` on `PopoverContent` itself.
+ *
+ * `reposition()` — the cross-framework positioning method for an anchor that
+ * moved without the floating layer noticing — is accessed via context:
+ * `usePopoverContext().reposition`, not a ref. For full manual composition,
+ * use `PopoverRoot` from `@skdx/react/primitives/popover`.
  *
  * @example
  * ```tsx
- * <Popover>
- *   <PopoverTrigger>Open</PopoverTrigger>
+ * <Popover trigger={<Button>Share</Button>} title="Share this page">
+ *   <p>Anyone with the link can view it.</p>
+ * </Popover>
+ * ```
+ *
+ * @example Full manual composition — `@skdx/react/primitives/popover`.
+ * ```tsx
+ * import { PopoverArrow, PopoverClose, PopoverContent, PopoverDescription, PopoverPortal, PopoverRoot, PopoverTitle, PopoverTrigger } from '@skdx/react/primitives/popover';
+ *
+ * <PopoverRoot>
+ *   <PopoverTrigger>Share</PopoverTrigger>
  *   <PopoverPortal>
  *     <PopoverContent side="bottom" align="start">
- *       <p>Popover content.</p>
+ *       <PopoverTitle>Share this page</PopoverTitle>
+ *       <PopoverDescription>Anyone with the link can view it.</PopoverDescription>
  *       <PopoverArrow />
  *       <PopoverClose>Close</PopoverClose>
  *     </PopoverContent>
  *   </PopoverPortal>
- * </Popover>
+ * </PopoverRoot>
  * ```
  */
-export declare function Popover({ children, open: openProp, defaultOpen, onOpenChange, onOpenChangeComplete, modal, }: PopoverProps): React.JSX.Element;
+export declare function Popover({ children, open, defaultOpen, onOpenChange, onOpenChangeComplete, modal, trigger, title, description, side, align, showArrow, ...rest }: PopoverProps): React.JSX.Element;
 export declare namespace Popover {
     var displayName: string;
 }

package/dist/popover/Popover.d.ts

@@ -7,30 +7,66 @@ export declare const PopoverProvider: {
     }): React.JSX.Element;
     displayName: string;
 }, usePopoverContext: (consumerName: string) => PopoverContextValue;
+/** Props for {@link PopoverRoot}: {@link PopoverProps} minus the derived-anatomy-only props. */
+export type PopoverRootProps = Omit<PopoverProps, 'trigger' | 'title' | 'description' | 'side' | 'align' | 'showArrow'>;
 /**
- * Root of a non-modal-by-default popover: owns open state and hands it down
- * to `PopoverTrigger` / `PopoverAnchor` / `PopoverPortal` / `PopoverContent` /
- * `PopoverArrow` / `PopoverClose` via context. Wraps children in the shared
- * popper positioning root, so `PopoverContent` can float relative to the
- * trigger (or a custom `PopoverAnchor`). Renders no DOM element itself.
+ * State/context primitive that owns open state and hands it down to all popover
+ * parts via context, wrapping in the popper positioning root with no DOM
+ * element rendered. The `Popover` recipe (below) wraps this with
+ * `PopoverAnatomy`, adding the derived anatomy. For full manual part
+ * composition, use `PopoverRoot` from `@skdx/react/primitives/popover`.
  *
- * Works controlled (`open` + `onOpenChange`) or uncontrolled (`defaultOpen`).
+ * `reposition()` — the cross-framework positioning method for an anchor that
+ * moved without the floating layer noticing — is accessed via context:
+ * `usePopoverContext().reposition`, not a ref.
+ */
+export declare function PopoverRoot({ children, open: openProp, defaultOpen, onOpenChange, onOpenChangeComplete, modal, }: PopoverRootProps): React.JSX.Element;
+export declare namespace PopoverRoot {
+    var displayName: string;
+}
+/**
+ * Recipe for a non-modal-by-default popover: owns open state and passes it to
+ * all parts via context, rendering no DOM element itself. Derives the entire
+ * anatomy from `trigger`/`title`/`description`: trigger (merged via `asChild`,
+ * no wrapping), portal, and the panel with derived title, description, and
+ * close button. `children` is the panel's body; the component reads only
+ * whether it exists. Works controlled (`open` + `onOpenChange`) or uncontrolled
+ * (`defaultOpen`).
+ *
+ * `PopoverContent` is `role="dialog"` and must have an accessible name: either
+ * via `title` or, under manual composition without a visible heading, via
+ * `aria-label` on `PopoverContent` itself.
+ *
+ * `reposition()` — the cross-framework positioning method for an anchor that
+ * moved without the floating layer noticing — is accessed via context:
+ * `usePopoverContext().reposition`, not a ref. For full manual composition,
+ * use `PopoverRoot` from `@skdx/react/primitives/popover`.
  *
  * @example
  * ```tsx
- * <Popover>
- *   <PopoverTrigger>Open</PopoverTrigger>
+ * <Popover trigger={<Button>Share</Button>} title="Share this page">
+ *   <p>Anyone with the link can view it.</p>
+ * </Popover>
+ * ```
+ *
+ * @example Full manual composition — `@skdx/react/primitives/popover`.
+ * ```tsx
+ * import { PopoverArrow, PopoverClose, PopoverContent, PopoverDescription, PopoverPortal, PopoverRoot, PopoverTitle, PopoverTrigger } from '@skdx/react/primitives/popover';
+ *
+ * <PopoverRoot>
+ *   <PopoverTrigger>Share</PopoverTrigger>
  *   <PopoverPortal>
  *     <PopoverContent side="bottom" align="start">
- *       <p>Popover content.</p>
+ *       <PopoverTitle>Share this page</PopoverTitle>
+ *       <PopoverDescription>Anyone with the link can view it.</PopoverDescription>
  *       <PopoverArrow />
  *       <PopoverClose>Close</PopoverClose>
  *     </PopoverContent>
  *   </PopoverPortal>
- * </Popover>
+ * </PopoverRoot>
  * ```
  */
-export declare function Popover({ children, open: openProp, defaultOpen, onOpenChange, onOpenChangeComplete, modal, }: PopoverProps): React.JSX.Element;
+export declare function Popover({ children, open, defaultOpen, onOpenChange, onOpenChangeComplete, modal, trigger, title, description, side, align, showArrow, ...rest }: PopoverProps): React.JSX.Element;
 export declare namespace Popover {
     var displayName: string;
 }

package/dist/popover/Popover.js

@@ -1 +1 @@
-import*as a from"react";import{createSafeContext as O}from"../utils/createContext.js";import{skdxPart as w}from"../utils/part.js";import{PopperAnchor as E,PopperArrow as N,PopperRoot as k}from"../utils/popper.js";import{useControllableState as H}from"../utils/useControllableState.js";import{useOpenChangeComplete as b}from"../utils/useOpenChangeComplete.js";import{jsx as v}from"react/jsx-runtime";var[A,n]=O("Popover");function L({children:o,open:t,defaultOpen:r=!1,onOpenChange:s,onOpenChangeComplete:f,modal:l=!1}){let P=a.useRef(null),i=a.useRef(null),[m=!1,c]=H({prop:t,defaultProp:r,onChange:s});return b(m,i,f),v(k,{children:v(A,{triggerRef:P,contentRef:i,contentId:a.useId(),open:m,onOpenChange:c,modal:l,children:o})})}L.displayName="Popover";var to=E,M=a.forwardRef((o,t)=>v(N,{...o,...w("popover","arrow",o.className),ref:t}));M.displayName="PopoverArrow";import*as u from"react";import{useComposedRefs as D}from"../utils/composeRefs.js";import{skdxPart as I}from"../utils/part.js";import{PopperAnchor as B}from"../utils/popper.js";import{composeEventHandlers as S,Primitive as F}from"../utils/primitive.js";import{jsx as d}from"react/jsx-runtime";var C=u.forwardRef((o,t)=>{let r=n("PopoverTrigger"),s=D(t,r.triggerRef);return d(B,{asChild:!0,children:d(F.button,{type:"button","aria-haspopup":"dialog","aria-expanded":r.open,"aria-controls":r.contentId,"data-state":r.open?"open":"closed",...o,...I("popover","trigger",o.className),ref:s,onClick:S(o.onClick,()=>r.onOpenChange(!r.open))})})});C.displayName="PopoverTrigger";import{Portal as V}from"../utils/portal.js";import{jsx as W}from"react/jsx-runtime";var g=({forceMount:o,children:t,...r})=>{let s=n("PopoverPortal");return o||s.open?W(V,{...r,children:t}):null};g.displayName="PopoverPortal";import*as R from"react";import{useComposedRefs as K}from"../utils/composeRefs.js";import{skdxPart as q}from"../utils/part.js";import{PopperContent as z}from"../utils/popper.js";import{useDismiss as G}from"../utils/useDismiss.js";import{autoFocusEvent as J,useFocusTrap as Q}from"../utils/useFocusTrap.js";import{jsx as U}from"react/jsx-runtime";var x=R.forwardRef(({forceMount:o,onEscapeKeyDown:t,onPointerDownOutside:r,onFocusOutside:s,onInteractOutside:f,onOpenAutoFocus:l,onCloseAutoFocus:P,sideOffset:i=4,...m},c)=>{let e=n("PopoverContent"),T=K(c,e.contentRef);return Q(e.contentRef,e.open&&e.modal,{onOpenAutoFocus:l,onCloseAutoFocus:P}),G({enabled:e.open,onEscapeKeyDown:p=>{t?.(p),!p.defaultPrevented&&(e.onOpenChange(!1),(e.modal||J("close-auto-focus",P))&&e.triggerRef.current?.focus())},onInteractOutside:f,onPointerDownOutside:p=>{r?.(p),p.defaultPrevented||e.onOpenChange(!1)},onFocusOutside:p=>{s?.(p),p.defaultPrevented||e.onOpenChange(!1)}},[e.contentRef,e.triggerRef]),o||e.open?U(z,{component:"popover",role:"dialog",id:e.contentId,"data-state":e.open?"open":"closed",sideOffset:i,...m,...q("popover","content",m.className),ref:T}):null});x.displayName="PopoverContent";import*as y from"react";import{skdxPart as X}from"../utils/part.js";import{composeEventHandlers as Y,Primitive as Z}from"../utils/primitive.js";import{jsx as _}from"react/jsx-runtime";var h=y.forwardRef((o,t)=>{let r=n("PopoverClose");return _(Z.button,{type:"button",...o,...X("popover","close",o.className),ref:t,onClick:Y(o.onClick,()=>r.onOpenChange(!1))})});h.displayName="PopoverClose";export{L as Popover,to as PopoverAnchor,M as PopoverArrow,h as PopoverClose,x as PopoverContent,g as PopoverPortal,A as PopoverProvider,C as PopoverTrigger,n as usePopoverContext};
+import*as s from"react";import{createSafeContext as xo}from"../utils/createContext.js";import{skdxPart as To}from"../utils/part.js";import{PopperAnchor as wo,PopperArrow as bo,PopperRoot as Eo}from"../utils/popper.js";import{useControllableState as ko}from"../utils/useControllableState.js";import{useOpenChangeComplete as Do}from"../utils/useOpenChangeComplete.js";import*as M from"react";import{skdxPart as V}from"../utils/part.js";import{composeEventHandlers as K,Primitive as z}from"../utils/primitive.js";import{jsx as G}from"react/jsx-runtime";var E=M.forwardRef((o,e)=>{let t=i("PopoverClose");return G(z.button,{type:"button",...o,...V("popover","close",o.className),ref:e,onClick:K(o.onClick,()=>t.onOpenChange(!1))})});E.displayName="PopoverClose";import*as T from"react";import{useComposedRefs as Q}from"../utils/composeRefs.js";import{isDevMode as U}from"../utils/is-dev-mode.js";import{skdxPart as X}from"../utils/part.js";import{PopperContent as Y}from"../utils/popper.js";import{TABBABLE_SELECTOR as Z}from"../utils/tabbable.js";import{useBodyScrollLock as j}from"../utils/useBodyScrollLock.js";import{useDismiss as oo}from"../utils/useDismiss.js";import{autoFocusEvent as eo,useFocusTrap as to}from"../utils/useFocusTrap.js";import{useOutsideInert as ro}from"../utils/useOutsideInert.js";import{isDevMode as N}from"../utils/is-dev-mode.js";function k(o,e,t){if(!e)return null;let n;try{n=o.querySelector(e)}catch{return N()&&console.warn(`[skdx] Popover: ${t}="${e}" is not a valid CSS selector. Falling back to the default focus target.`),null}return!n&&N()&&console.warn(J(t,e)),n}function J(o,e){return o==="initialFocus"?`[skdx] Popover: initialFocus="${e}" matched no element inside the popover panel. Falling back to the first tabbable element, then the panel itself.`:`[skdx] Popover: finalFocus="${e}" matched no element in the document. Falling back to the trigger.`}import{jsx as po}from"react/jsx-runtime";function no(o,e){T.useEffect(()=>{if(!U()||!e)return;let t=o.current;!t||t.querySelector(".skdx-popover__close")||console.warn("[skdx] Popover: `modal` contains focus inside PopoverContent, but no PopoverClose was rendered inside it. A user who cannot press Escape \u2014 a touch screen-reader user has no Escape key \u2014 has no way out of the panel. Render a PopoverClose, or set `modal={false}`.")},[o,e])}var D=T.forwardRef(({forceMount:o,onEscapeKeyDown:e,onPointerDownOutside:t,onFocusOutside:n,onInteractOutside:f,onOpenAutoFocus:m,onCloseAutoFocus:c,sideOffset:a=4,arrowPadding:R=8,initialFocus:u,finalFocus:d,...P},v)=>{let r=i("PopoverContent"),C=Q(v,r.contentRef),y=()=>{let p=k(document,d,"finalFocus");return p?(p.focus({preventScroll:!0}),!0):!1},x=r.modal!==!1,_=r.modal===!0;return j(r.open&&_),ro(r.contentRef,r.open&&x),to(r.contentRef,r.open&&x,{onOpenAutoFocus:p=>{if(m?.(p),p.defaultPrevented||!u)return;let g=r.contentRef.current;if(!g)return;let L=k(g,u,"initialFocus")??g.querySelector(Z)??g;p.preventDefault(),L===g&&g.setAttribute("tabindex","-1"),L.focus({preventScroll:!0})},onCloseAutoFocus:p=>{c?.(p),!(p.defaultPrevented||!d)&&y()&&p.preventDefault()}}),no(r.contentRef,r.open&&x),oo({enabled:r.open,onEscapeKeyDown:p=>{e?.(p),!p.defaultPrevented&&(r.onOpenChange(!1),x?r.triggerRef.current?.focus():eo("close-auto-focus",c)&&(y()||r.triggerRef.current?.focus()))},onInteractOutside:f,onPointerDownOutside:p=>{t?.(p),p.defaultPrevented||r.onOpenChange(!1)},onFocusOutside:p=>{n?.(p),p.defaultPrevented||r.onOpenChange(!1)}},[r.contentRef,r.triggerRef]),o||r.open?po(Y,{component:"popover",role:"dialog","aria-labelledby":r.hasTitle?r.titleId:void 0,"aria-describedby":r.hasDescription?r.descriptionId:void 0,id:r.contentId,"data-state":r.open?"open":"closed",sideOffset:a,arrowPadding:R,...P,...X("popover","content",P.className),ref:C}):null});D.displayName="PopoverContent";import*as w from"react";import{skdxPart as so}from"../utils/part.js";import{Primitive as io}from"../utils/primitive.js";import{jsx as ao}from"react/jsx-runtime";var H=w.forwardRef((o,e)=>{let t=i("PopoverDescription"),{setHasDescription:n}=t;return w.useEffect(()=>(n(!0),()=>n(!1)),[n]),ao(io.p,{id:t.descriptionId,...o,...so("popover","description",o.className),ref:e})});H.displayName="PopoverDescription";import{Portal as lo}from"../utils/portal.js";import{jsx as co}from"react/jsx-runtime";var A=({forceMount:o,children:e,...t})=>{let n=i("PopoverPortal");return o||n.open?co(lo,{...t,children:e}):null};A.displayName="PopoverPortal";import*as b from"react";import{skdxPart as fo}from"../utils/part.js";import{Primitive as mo}from"../utils/primitive.js";import{jsx as uo}from"react/jsx-runtime";var O=b.forwardRef((o,e)=>{let t=i("PopoverTitle"),{setHasTitle:n}=t;return b.useEffect(()=>(n(!0),()=>n(!1)),[n]),uo(mo.h2,{id:t.titleId,...o,...fo("popover","title",o.className),ref:e})});O.displayName="PopoverTitle";import*as B from"react";import{useComposedRefs as Po}from"../utils/composeRefs.js";import{skdxPart as vo}from"../utils/part.js";import{PopperAnchor as go}from"../utils/popper.js";import{composeEventHandlers as Ro,Primitive as ho}from"../utils/primitive.js";import{jsx as I}from"react/jsx-runtime";var F=B.forwardRef((o,e)=>{let t=i("PopoverTrigger"),n=Po(e,t.triggerRef);return I(go,{asChild:!0,children:I(ho.button,{type:"button","aria-haspopup":"dialog","aria-expanded":t.open,"aria-controls":t.contentId,"data-state":t.open?"open":"closed",...o,...vo("popover","trigger",o.className),ref:n,onClick:Ro(o.onClick,()=>t.onOpenChange(!t.open))})})});F.displayName="PopoverTrigger";import{Fragment as yo,jsx as l,jsxs as W}from"react/jsx-runtime";var Co=()=>l("svg",{viewBox:"0 0 16 16",width:"1em",height:"1em",fill:"none","aria-hidden":"true",focusable:"false",children:l("path",{d:"M4 4l8 8M12 4l-8 8",stroke:"currentColor",strokeWidth:"1.5",strokeLinecap:"round"})}),q=({trigger:o,title:e,description:t,side:n,align:f,showArrow:m,children:c,passThrough:a})=>W(yo,{children:[o?l(F,{asChild:!0,...a?.id?{"aria-controls":a.id}:{},children:o}):null,l(A,{children:W(D,{...a,side:n,align:f,children:[e?l(O,{children:e}):null,t?l(H,{children:t}):null,c,m?l(S,{}):null,l(E,{"aria-label":"Close",children:l(Co,{})})]})})]});import{jsx as h}from"react/jsx-runtime";var[Ho,i]=xo("Popover");function $({children:o,open:e,defaultOpen:t=!1,onOpenChange:n,onOpenChangeComplete:f,modal:m=!1}){let c=s.useRef(null),a=s.useRef(null),[R,u]=s.useState(!1),[d,P]=s.useState(!1),[v=!1,r]=ko({prop:e,defaultProp:t,onChange:n});Do(v,a,f);let C=s.useRef(null),y=s.useCallback(()=>{C.current?.()},[]);return h(Eo,{updateRef:C,children:h(Ho,{triggerRef:c,contentRef:a,contentId:s.useId(),titleId:s.useId(),descriptionId:s.useId(),hasTitle:R,setHasTitle:u,hasDescription:d,setHasDescription:P,open:v,onOpenChange:r,modal:m,reposition:y,children:o})})}$.displayName="PopoverRoot";function Ao({children:o,open:e,defaultOpen:t,onOpenChange:n,onOpenChangeComplete:f,modal:m,trigger:c,title:a,description:R,side:u,align:d,showArrow:P=!1,...v}){return h($,{open:e,defaultOpen:t,onOpenChange:n,onOpenChangeComplete:f,modal:m,children:h(q,{trigger:c,title:a,description:R,side:u,align:d,showArrow:P,passThrough:v,children:o})})}Ao.displayName="Popover";var Se=wo,S=s.forwardRef((o,e)=>h(bo,{...o,...To("popover","arrow",o.className),ref:e}));S.displayName="PopoverArrow";export{Ao as Popover,Se as PopoverAnchor,S as PopoverArrow,E as PopoverClose,D as PopoverContent,H as PopoverDescription,A as PopoverPortal,Ho as PopoverProvider,$ as PopoverRoot,O as PopoverTitle,F as PopoverTrigger,i as usePopoverContext};

package/dist/popover/PopoverAnatomy.d.cts

@@ -0,0 +1,21 @@
+import type * as React from 'react';
+import type { PassThroughProps } from '../utils/passThrough.cjs';
+import type { Align, Side } from '../utils/popper.cjs';
+/**
+ * The anatomy a {@link Popover} draws for plain body content: trigger (via
+ * `asChild`, when given), portal, panel with derived title/description, body,
+ * arrow (if `showArrow`), and close button. A focus-trapping modal must
+ * always offer an exit.
+ *
+ * @internal
+ */
+export declare const PopoverAnatomy: ({ trigger, title, description, side, align, showArrow, children, passThrough, }: {
+    trigger?: React.ReactElement;
+    title?: string;
+    description?: string;
+    side?: Side;
+    align?: Align;
+    showArrow: boolean;
+    children?: React.ReactNode;
+    passThrough?: PassThroughProps;
+}) => React.JSX.Element;

package/dist/popover/PopoverAnatomy.d.ts

@@ -0,0 +1,21 @@
+import type * as React from 'react';
+import type { PassThroughProps } from '../utils/passThrough.js';
+import type { Align, Side } from '../utils/popper.js';
+/**
+ * The anatomy a {@link Popover} draws for plain body content: trigger (via
+ * `asChild`, when given), portal, panel with derived title/description, body,
+ * arrow (if `showArrow`), and close button. A focus-trapping modal must
+ * always offer an exit.
+ *
+ * @internal
+ */
+export declare const PopoverAnatomy: ({ trigger, title, description, side, align, showArrow, children, passThrough, }: {
+    trigger?: React.ReactElement;
+    title?: string;
+    description?: string;
+    side?: Side;
+    align?: Align;
+    showArrow: boolean;
+    children?: React.ReactNode;
+    passThrough?: PassThroughProps;
+}) => React.JSX.Element;

package/dist/popover/PopoverContent.d.cts

@@ -2,15 +2,25 @@ import * as React from 'react';
 import type { PopoverContentProps } from './types.cjs';
 /**
  * The popover's floating panel: `role="dialog"` with `data-state`
- * (`open`/`closed`), positioned via the shared popper layer against the
+ * (`open`/`closed`), named by `PopoverTitle` and described by
+ * `PopoverDescription` through `aria-labelledby`/`aria-describedby` — each
+ * emitted only while that part is mounted, so an omitted part leaves no
+ * reference behind rather than one pointing at nothing. Positioned via the
+ * shared popper layer against the
  * trigger (or `PopoverAnchor`) using `side`/`align`/`sideOffset` (defaults
  * to `4`, overriding the popper default of `0`)/`alignOffset` and flipping/
  * shifting to avoid viewport collisions unless `avoidCollisions` is `false`.
+ * `arrowPadding` keeps the arrow clear of the panel's rounded corners, and
+ * `hideWhenDetached` hides the panel — without closing or unmounting it — while
+ * its anchor is scrolled out of view inside a clipping ancestor.
  * Also exposes `data-side`/`data-align` reflecting the resolved placement, and
  * the measurement custom properties `--skdx-popover-available-width` /
  * `-available-height` / `-trigger-width` / `-transform-origin`, so the panel
  * can be sized and animated from CSS without measuring anything by hand.
- * Traps focus when the popover is `modal`. Closes on Escape (returning focus
+ * Contains the page according to the root's `modal`: `'trap-focus'` traps Tab
+ * inside the panel and marks the rest of the document `inert`, `true` adds the
+ * body-scroll lock on top of that, and `false` (the default) does neither.
+ * Closes on Escape (returning focus
  * to the trigger) or on an outside interaction: pointer-down outside or focus
  * moving outside, each reported to `onPointerDownOutside`/`onFocusOutside`
  * and, just before them and with the same event, to `onInteractOutside`. Any
@@ -18,13 +28,15 @@ import type { PopoverContentProps } from './types.cjs';
  * open. Both focus moves the popover makes on the consumer's behalf are
  * announced first as cancelable `onOpenAutoFocus`/`onCloseAutoFocus` — the
  * latter also covers the manual return to the trigger a non-modal popover
- * does on Escape, where there is no trap to do it. Mounts only while open
+ * does on Escape, where there is no trap to do it — and can be aimed with
+ * `initialFocus`/`finalFocus` without a handler at all. Mounts only while open
  * unless `forceMount` is set.
  *
  * @example
  * ```tsx
  * <PopoverPortal>
  *   <PopoverContent side="right" align="start" sideOffset={8}>
+ *     <PopoverTitle>Share this page</PopoverTitle>
  *     <p>Popover content.</p>
  *     <PopoverArrow />
  *   </PopoverContent>

package/dist/popover/PopoverContent.d.ts

@@ -2,15 +2,25 @@ import * as React from 'react';
 import type { PopoverContentProps } from './types.js';
 /**
  * The popover's floating panel: `role="dialog"` with `data-state`
- * (`open`/`closed`), positioned via the shared popper layer against the
+ * (`open`/`closed`), named by `PopoverTitle` and described by
+ * `PopoverDescription` through `aria-labelledby`/`aria-describedby` — each
+ * emitted only while that part is mounted, so an omitted part leaves no
+ * reference behind rather than one pointing at nothing. Positioned via the
+ * shared popper layer against the
  * trigger (or `PopoverAnchor`) using `side`/`align`/`sideOffset` (defaults
  * to `4`, overriding the popper default of `0`)/`alignOffset` and flipping/
  * shifting to avoid viewport collisions unless `avoidCollisions` is `false`.
+ * `arrowPadding` keeps the arrow clear of the panel's rounded corners, and
+ * `hideWhenDetached` hides the panel — without closing or unmounting it — while
+ * its anchor is scrolled out of view inside a clipping ancestor.
  * Also exposes `data-side`/`data-align` reflecting the resolved placement, and
  * the measurement custom properties `--skdx-popover-available-width` /
  * `-available-height` / `-trigger-width` / `-transform-origin`, so the panel
  * can be sized and animated from CSS without measuring anything by hand.
- * Traps focus when the popover is `modal`. Closes on Escape (returning focus
+ * Contains the page according to the root's `modal`: `'trap-focus'` traps Tab
+ * inside the panel and marks the rest of the document `inert`, `true` adds the
+ * body-scroll lock on top of that, and `false` (the default) does neither.
+ * Closes on Escape (returning focus
  * to the trigger) or on an outside interaction: pointer-down outside or focus
  * moving outside, each reported to `onPointerDownOutside`/`onFocusOutside`
  * and, just before them and with the same event, to `onInteractOutside`. Any
@@ -18,13 +28,15 @@ import type { PopoverContentProps } from './types.js';
  * open. Both focus moves the popover makes on the consumer's behalf are
  * announced first as cancelable `onOpenAutoFocus`/`onCloseAutoFocus` — the
  * latter also covers the manual return to the trigger a non-modal popover
- * does on Escape, where there is no trap to do it. Mounts only while open
+ * does on Escape, where there is no trap to do it — and can be aimed with
+ * `initialFocus`/`finalFocus` without a handler at all. Mounts only while open
  * unless `forceMount` is set.
  *
  * @example
  * ```tsx
  * <PopoverPortal>
  *   <PopoverContent side="right" align="start" sideOffset={8}>
+ *     <PopoverTitle>Share this page</PopoverTitle>
  *     <p>Popover content.</p>
  *     <PopoverArrow />
  *   </PopoverContent>

package/dist/popover/PopoverDescription.d.cts

@@ -0,0 +1,18 @@
+import * as React from 'react';
+import type { PopoverDescriptionProps } from './types.cjs';
+/**
+ * The popover's accessible description: a `<p>` with an id that
+ * `PopoverContent` points to via `aria-describedby` while mounted. Optional
+ * (unlike `PopoverTitle` — a panel needs a name but may not need description),
+ * but the wiring is required: the attribute appears only while this element
+ * does, avoiding dangling references.
+ *
+ * @example
+ * ```tsx
+ * <PopoverContent>
+ *   <PopoverTitle>Share this page</PopoverTitle>
+ *   <PopoverDescription>Anyone with the link can view it.</PopoverDescription>
+ * </PopoverContent>
+ * ```
+ */
+export declare const PopoverDescription: React.ForwardRefExoticComponent<Omit<PopoverDescriptionProps, "ref"> & React.RefAttributes<HTMLParagraphElement>>;

package/dist/popover/PopoverDescription.d.ts

@@ -0,0 +1,18 @@
+import * as React from 'react';
+import type { PopoverDescriptionProps } from './types.js';
+/**
+ * The popover's accessible description: a `<p>` with an id that
+ * `PopoverContent` points to via `aria-describedby` while mounted. Optional
+ * (unlike `PopoverTitle` — a panel needs a name but may not need description),
+ * but the wiring is required: the attribute appears only while this element
+ * does, avoiding dangling references.
+ *
+ * @example
+ * ```tsx
+ * <PopoverContent>
+ *   <PopoverTitle>Share this page</PopoverTitle>
+ *   <PopoverDescription>Anyone with the link can view it.</PopoverDescription>
+ * </PopoverContent>
+ * ```
+ */
+export declare const PopoverDescription: React.ForwardRefExoticComponent<Omit<PopoverDescriptionProps, "ref"> & React.RefAttributes<HTMLParagraphElement>>;

package/dist/popover/PopoverPortal.d.cts

@@ -1,17 +1,13 @@
 import type { PopoverPortalProps } from './types.cjs';
 /**
- * Teleports `PopoverContent` to `document.body` (or a custom `container`),
- * so the popover escapes any clipping/`overflow` ancestors. Mounts only
- * while open unless `forceMount` is set.
+ * Teleports content to `document.body` or custom `container` to escape
+ * clipping ancestors. Mounts only while open unless `forceMount` is set.
  *
  * @example
  * ```tsx
- * <Popover>
- *   <PopoverTrigger>Open</PopoverTrigger>
- *   <PopoverPortal>
- *     <PopoverContent>…</PopoverContent>
- *   </PopoverPortal>
- * </Popover>
+ * <PopoverPortal>
+ *   <PopoverContent>…</PopoverContent>
+ * </PopoverPortal>
  * ```
  */
 export declare const PopoverPortal: {