@skdx/web-components 0.27.0 → 0.28.0

package/dist/popover/PopoverContent.d.ts

@@ -1,29 +1,21 @@
 import { LitElement } from 'lit';
 import { type PositionOptions } from '../internal/positioning.js';
 /**
- * `<skdx-popover-content>` — the popover's floating panel for the closest
- * ancestor `<skdx-popover>`, positioned relative to the trigger via
- * `@floating-ui/dom` (`strategy: 'fixed'`, so no portal is needed — unlike
- * React's `PopoverPortal`, this content renders in normal document flow).
- * `role`, `id`, and `data-state` are set directly on this host element (not
- * inside shadow DOM) so `aria-controls` on the trigger can target this
- * element's id and arbitrary light-DOM content can be slotted in.
+ * Floating panel positioned via `@floating-ui/dom` (`strategy: 'fixed'`, no
+ * portal) against trigger or anchor. Sets `role`, `id`, `data-state` on host
+ * for `aria-controls` targeting.
  *
- * Closes on Escape or on an outside interaction — pointer-down outside, or
- * focus moving outside — each announced first as `interact-outside` and then
- * as the specific event, so one `preventDefault()` vetoes either path.
- * Escape returns focus to the trigger, announced as `close-auto-focus`.
- * Traps Tab/Shift+Tab within its own focusable descendants while the
- * ancestor popover is `modal`, and announces the initial focus move it makes
- * on open as `open-auto-focus`.
+ * Must be named: `<skdx-popover-title>` wires `aria-labelledby`,
+ * `<skdx-popover-description>` wires `aria-describedby` (only while mounted);
+ * otherwise set `aria-label`.
  *
- * `data-side`/`data-align` start out as the *configured* `side`/`align` and
- * are rewritten by `positioning.ts`'s `positionFloating` with floating-ui's
- * resolved (post-flip/shift) placement on every reposition, as React's
- * `PopperContent` does. The same layer writes the measurement custom
- * properties `--skdx-popover-available-width` / `-available-height` /
- * `-trigger-width` / `-transform-origin` onto this element, so the panel can
- * be sized and animated from CSS without measuring anything by hand.
+ * Closes on Escape or outside interaction, each announced first as
+ * `interact-outside` then specific event so one `preventDefault()` vetoes both.
+ * Traps Tab/Shift+Tab within focusable descendants while `modal`, marking
+ * outside elements `inert`—for screen-reader users, not just keyboard ones.
+ *
+ * `data-side`/`data-align` update on reposition; `hide-when-detached` hides
+ * when anchor scrolls out of view.
  *
  * @fires escape-key-down - Escape was pressed while open. Preventable.
  * @fires pointer-down-outside - A pointer-down landed outside this content while open. Preventable.
@@ -44,41 +36,76 @@ export declare class SkdxPopoverContent extends LitElement {
     alignOffset: number;
     /** Flip/shift to stay within the viewport instead of overflowing it. */
     avoidCollisions: boolean;
+    /** Minimum pixel distance from the collision boundary; the attribute takes one number, the per-side `{ top, right, bottom, left }` form is property-only. */
+    collisionPadding: NonNullable<PositionOptions['collisionPadding']>;
+    /** Element(s) collisions are measured against instead of this panel's clipping ancestors — keeps it inside a scroll container, say. Property-only. */
+    collisionBoundary?: PositionOptions['collisionBoundary'];
     /**
-     * Minimum pixel distance to keep from the collision boundary when avoiding
-     * collisions. The `collision-padding` attribute sets a single number for
-     * every side; the per-side `{ top, right, bottom, left }` form is
-     * property-only, since an attribute cannot carry an object.
+     * Clearance in pixels between the arrow and each end of the panel's edge,
+     * so the arrow cannot ride over a rounded corner.
+     * @default 8
      */
-    collisionPadding: NonNullable<PositionOptions['collisionPadding']>;
+    arrowPadding: number;
     /**
-     * Element (or elements) collisions are measured against instead of this
-     * panel's clipping ancestors — keeps it inside a scroll container or one
-     * pane of a split layout rather than the whole viewport. Property-only: an
-     * `Element` cannot come from an attribute string.
+     * Hides the panel while its anchor is scrolled fully out of view inside a
+     * clipping ancestor, without unmounting it — unmounting would tear down the
+     * focus trap and move focus unasked.
+     * @default false
      */
-    collisionBoundary?: PositionOptions['collisionBoundary'];
+    hideWhenDetached: boolean;
+    /**
+     * CSS selector for the element to focus when the popover opens; live only
+     * while `modal` contains focus, and only when `open-auto-focus` was not
+     * vetoed. Falls back to the first focusable element.
+     * @default undefined — the panel's first focusable element, then the panel itself.
+     */
+    initialFocus?: string;
+    /**
+     * CSS selector for the element to focus when the popover closes, resolved
+     * at document level. Live in every modality, unlike `initialFocus`; applies
+     * only when `close-auto-focus` was not vetoed.
+     * @default undefined — the trigger, or whatever was focused before opening.
+     */
+    finalFocus?: string;
     private root;
     private readonly onRootUpdate;
     private cleanupPosition?;
+    /** Whether this panel currently holds a body-scroll lock, so it releases exactly one. */
+    private scrollLocked;
     connectedCallback(): void;
     disconnectedCallback(): void;
     /**
-     * The trigger registers the element to anchor against in its own
-     * `firstUpdated()`, which has not run yet when this panel's
-     * `connectedCallback` does — so a panel that mounts already open finds no
-     * anchor and, with no open-state change to follow, never positions itself at
-     * all. This is the first tick where the anchor exists; `activate()` is
-     * guarded, so an already-positioned panel is untouched.
+     * The trigger registers its anchor in its own `firstUpdated()`, which
+     * hasn't run yet when this panel's `connectedCallback` does — so a panel
+     * that mounts already open would never position itself without this.
+     * `activate()` is guarded, so an already-positioned panel is untouched.
      */
     protected firstUpdated(): void;
     private syncHostState;
+    /**
+     * Points `aria-labelledby`/`aria-describedby` at the Title/Description parts,
+     * only while they are rendered — a dangling IDREF is worse than none, since
+     * the platform stops there instead of falling through to `aria-label`.
+     */
+    private syncAriaParts;
     private activate;
+    /**
+     * Warns when a focus-containing popover renders without a
+     * `<skdx-popover-close>` inside it.
+     *
+     * A trap with no in-panel exit strands a user who cannot press Escape (a
+     * touch screen-reader user has none, and the trigger is now behind `inert`).
+     * Checked against the DOM rather than the root, since Close is a light-DOM
+     * descendant; mirrors `useRequireCloseWhenTrapping` in the React package.
+     */
+    private warnWhenTrappingWithoutClose;
     private deactivate;
     private readonly handleOutsidePointerDown;
     private readonly handleOutsideFocus;
     private trapFocus;
     private readonly handleKeyDown;
+    /** A Title or Description appearing or disappearing changes what the panel is named by. */
+    private readonly handleSlotChange;
     render(): import("lit").TemplateResult<1>;
 }
 declare global {

package/dist/popover/PopoverContent.js

@@ -1,5 +1,5 @@
-var m=Object.defineProperty;var v=Object.getOwnPropertyDescriptor;var s=(d,n,t,i)=>{for(var o=i>1?void 0:i?v(n,t):n,a=d.length-1,l;a>=0;a--)(l=d[a])&&(o=(i?l(n,t,o):l(o))||o);return i&&o&&m(n,t,o),o};import{css as g,html as y,LitElement as b}from"lit";import{property as r}from"lit/decorators.js";import{closestThroughPortal as E}from"../internal/closest.js";import{customElement as O}from"../internal/define.js";import{dispatchAutoFocus as c,dispatchEscapeKeyDown as w,dispatchOutside as u,focusOnOpen as L,focusOutsideTarget as P,triggerContains as h}from"../internal/dismiss.js";import{optOutBoolean as F,positionFloating as A}from"../internal/positioning.js";import{hiddenHostStyles as D}from"../internal/styles.js";var p='a[href], button:not([disabled]), input:not([disabled]), select:not([disabled]), textarea:not([disabled]), [tabindex]:not([tabindex="-1"])';function f(d){return Array.from(d.querySelectorAll("*")).filter(n=>n.matches(p)||!!n.shadowRoot?.querySelector(p))}var e=class extends b{constructor(){super(...arguments);this.side="bottom";this.align="center";this.sideOffset=4;this.alignOffset=0;this.avoidCollisions=!0;this.collisionPadding=8;this.root=null;this.onRootUpdate=()=>this.syncHostState();this.handleOutsidePointerDown=t=>{if(!this.root?.open)return;let i=t.target;this.contains(i)||h(this.root.triggerEl,i)||u(this,"pointer-down-outside",t)&&this.root.setOpen(!1)};this.handleOutsideFocus=t=>{if(!this.root?.open)return;let i=P(t);!i||this.contains(i)||h(this.root.triggerEl,i)||u(this,"focus-outside",t)&&this.root.setOpen(!1)};this.handleKeyDown=t=>{if(t.key==="Escape"){t.preventDefault(),w(this,t)&&(this.root?.setOpen(!1),c(this,"close-auto-focus")&&this.root?.focusTrigger());return}t.key==="Tab"&&this.root?.modal&&this.trapFocus(t)}}connectedCallback(){super.connectedCallback(),this.setAttribute("role","dialog"),this.tabIndex=-1,this.root=E(this,"skdx-popover"),this.root?.addEventListener("skdx-popover-internal-update",this.onRootUpdate),this.addEventListener("keydown",this.handleKeyDown),document.addEventListener("pointerdown",this.handleOutsidePointerDown),document.addEventListener("focusin",this.handleOutsideFocus),this.root&&(this.id=this.root.contentId),this.syncHostState()}disconnectedCallback(){this.root?.removeEventListener("skdx-popover-internal-update",this.onRootUpdate),document.removeEventListener("pointerdown",this.handleOutsidePointerDown),document.removeEventListener("focusin",this.handleOutsideFocus),this.cleanupPosition?.(),super.disconnectedCallback()}firstUpdated(){this.root?.open&&this.activate()}syncHostState(){let t=this.root?.open??!1;this.setAttribute("data-state",t?"open":"closed"),this.setAttribute("data-side",this.side??"bottom"),this.setAttribute("data-align",this.align??"center"),this.hidden=!t,t?this.activate():this.deactivate(),this.requestUpdate()}activate(){this.cleanupPosition||!this.root?.triggerEl||(this.cleanupPosition=A(this.root.triggerEl,this,{side:this.side,align:this.align,sideOffset:this.sideOffset,alignOffset:this.alignOffset,avoidCollisions:this.avoidCollisions,collisionPadding:this.collisionPadding,collisionBoundary:this.collisionBoundary,component:"popover",arrow:()=>this.querySelector("skdx-popover-arrow")}),this.root.modal&&requestAnimationFrame(()=>L(()=>{if(!c(this,"open-auto-focus"))return;(f(this)[0]??this).focus()})))}deactivate(){this.cleanupPosition?.(),this.cleanupPosition=void 0}trapFocus(t){let i=f(this);if(i.length===0)return;let o=i[0],a=i[i.length-1];t.shiftKey&&document.activeElement===o?(t.preventDefault(),a.focus()):!t.shiftKey&&document.activeElement===a&&(t.preventDefault(),o.focus())}render(){return y`<slot></slot>`}};e.styles=[D,g`
+var g=Object.defineProperty;var b=Object.getOwnPropertyDescriptor;var s=(l,n,t,e)=>{for(var i=e>1?void 0:e?b(n,t):n,a=l.length-1,d;a>=0;a--)(d=l[a])&&(i=(e?d(n,t,i):d(i))||i);return e&&i&&g(n,t,i),i};import{css as E,html as O,LitElement as k}from"lit";import{property as r}from"lit/decorators.js";import{syncPartIdRef as c}from"../internal/aria-part.js";import{lockBodyScroll as P,unlockBodyScroll as h}from"../internal/body-scroll-lock.js";import{closestThroughPortal as w}from"../internal/closest.js";import{customElement as F}from"../internal/define.js";import{dispatchAutoFocus as p,dispatchEscapeKeyDown as L,dispatchOutside as u,focusOnOpen as A,focusOutsideTarget as D,triggerContains as f}from"../internal/dismiss.js";import{applyFinalFocus as T,initialFocusTarget as B}from"../internal/focus-targets.js";import{setOutsideInert as m}from"../internal/outsideInert.js";import{optOutBoolean as R,positionFloating as x}from"../internal/positioning.js";import{hiddenHostStyles as H}from"../internal/styles.js";import{TABBABLE_SELECTOR as v}from"../internal/tabbable.js";import{isDevMode as q}from"../utils/is-dev-mode.js";function y(l){return Array.from(l.querySelectorAll("*")).filter(n=>n.matches(v)||!!n.shadowRoot?.querySelector(v))}var o=class extends k{constructor(){super(...arguments);this.side="bottom";this.align="center";this.sideOffset=4;this.alignOffset=0;this.avoidCollisions=!0;this.collisionPadding=8;this.arrowPadding=8;this.hideWhenDetached=!1;this.root=null;this.onRootUpdate=()=>this.syncHostState();this.scrollLocked=!1;this.handleOutsidePointerDown=t=>{if(!this.root?.open)return;let e=t.target;this.contains(e)||f(this.root.triggerEl,e)||u(this,"pointer-down-outside",t)&&this.root.setOpen(!1)};this.handleOutsideFocus=t=>{if(!this.root?.open)return;let e=D(t);!e||this.contains(e)||f(this.root.triggerEl,e)||u(this,"focus-outside",t)&&this.root.setOpen(!1)};this.handleKeyDown=t=>{if(t.key==="Escape"){t.preventDefault(),L(this,t)&&(this.root?.setOpen(!1),p(this,"close-auto-focus")&&!T(this.finalFocus,"Popover")&&this.root?.focusTrigger());return}t.key==="Tab"&&(this.root?.modal??!1)!==!1&&this.trapFocus(t)};this.handleSlotChange=()=>this.syncAriaParts()}connectedCallback(){super.connectedCallback(),this.setAttribute("role","dialog"),this.tabIndex=-1,this.root=w(this,"skdx-popover, skdx-popover-root"),this.root?.addEventListener("skdx-popover-internal-update",this.onRootUpdate),this.addEventListener("keydown",this.handleKeyDown),document.addEventListener("pointerdown",this.handleOutsidePointerDown),document.addEventListener("focusin",this.handleOutsideFocus),this.root&&(this.id?this.root.contentId=this.id:this.id=this.root.contentId),this.syncHostState()}disconnectedCallback(){this.root?.removeEventListener("skdx-popover-internal-update",this.onRootUpdate),document.removeEventListener("pointerdown",this.handleOutsidePointerDown),document.removeEventListener("focusin",this.handleOutsideFocus),this.cleanupPosition?.(),m(this,!1),this.scrollLocked&&(this.scrollLocked=!1,h()),super.disconnectedCallback()}firstUpdated(){this.root?.open&&this.activate()}syncHostState(){let t=this.root?.open??!1;this.setAttribute("data-state",t?"open":"closed"),this.setAttribute("data-side",this.side??"bottom"),this.setAttribute("data-align",this.align??"center"),this.syncAriaParts();let e=(this.root?.modal??!1)!==!1;m(this,t&&e);let i=t&&this.root?.modal===!0;i&&!this.scrollLocked?(this.scrollLocked=!0,P()):!i&&this.scrollLocked&&(this.scrollLocked=!1,h()),this.hidden=!t,t?this.activate():this.deactivate(),this.requestUpdate()}syncAriaParts(){c(this,"aria-labelledby",this.querySelector("skdx-popover-title"),"skdx-popover-content","title"),c(this,"aria-describedby",this.querySelector("skdx-popover-description"),"skdx-popover-content","description")}activate(){let t=this.root,e=t?.anchorEl??t?.triggerEl;this.cleanupPosition||!t||!e||(this.cleanupPosition=x(e,this,{side:this.side,align:this.align,sideOffset:this.sideOffset,alignOffset:this.alignOffset,avoidCollisions:this.avoidCollisions,collisionPadding:this.collisionPadding,collisionBoundary:this.collisionBoundary,component:"popover",arrowPadding:this.arrowPadding,hideWhenDetached:this.hideWhenDetached,arrow:()=>this.querySelector("skdx-popover-arrow")}),t.repositionFn=this.cleanupPosition.update,t.modal!==!1&&(this.warnWhenTrappingWithoutClose(),requestAnimationFrame(()=>A(()=>{if(!p(this,"open-auto-focus"))return;(this.initialFocus?B(this,this.initialFocus,"Popover"):y(this)[0]??this).focus()}))))}warnWhenTrappingWithoutClose(){this.querySelector(".skdx-popover__close, skdx-popover-close")||q()&&console.warn("[skdx] Popover: `modal` contains focus inside <skdx-popover-content>, but no <skdx-popover-close> 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 <skdx-popover-close>, or set `modal` to false.")}deactivate(){this.cleanupPosition?.(),this.root&&this.cleanupPosition&&this.root.repositionFn===this.cleanupPosition.update&&(this.root.repositionFn=null),this.cleanupPosition=void 0}trapFocus(t){let e=y(this);if(e.length===0)return;let i=e[0],a=e[e.length-1];t.shiftKey&&document.activeElement===i?(t.preventDefault(),a.focus()):!t.shiftKey&&document.activeElement===a&&(t.preventDefault(),i.focus())}render(){return O`<slot @slotchange=${this.handleSlotChange}></slot>`}};o.styles=[H,E`
       :host {
         display: block;
       }
-    `],s([r({type:String})],e.prototype,"side",2),s([r({type:String})],e.prototype,"align",2),s([r({type:Number,attribute:"side-offset"})],e.prototype,"sideOffset",2),s([r({type:Number,attribute:"align-offset"})],e.prototype,"alignOffset",2),s([r({converter:F,attribute:"avoid-collisions"})],e.prototype,"avoidCollisions",2),s([r({type:Number,attribute:"collision-padding"})],e.prototype,"collisionPadding",2),s([r({attribute:!1})],e.prototype,"collisionBoundary",2),e=s([O("skdx-popover-content","popover","content")],e);export{e as SkdxPopoverContent};
+    `],s([r({type:String})],o.prototype,"side",2),s([r({type:String})],o.prototype,"align",2),s([r({type:Number,attribute:"side-offset"})],o.prototype,"sideOffset",2),s([r({type:Number,attribute:"align-offset"})],o.prototype,"alignOffset",2),s([r({converter:R,attribute:"avoid-collisions"})],o.prototype,"avoidCollisions",2),s([r({type:Number,attribute:"collision-padding"})],o.prototype,"collisionPadding",2),s([r({attribute:!1})],o.prototype,"collisionBoundary",2),s([r({type:Number,attribute:"arrow-padding"})],o.prototype,"arrowPadding",2),s([r({type:Boolean,attribute:"hide-when-detached"})],o.prototype,"hideWhenDetached",2),s([r({type:String,attribute:"initial-focus"})],o.prototype,"initialFocus",2),s([r({type:String,attribute:"final-focus"})],o.prototype,"finalFocus",2),o=s([F("skdx-popover-content","popover","content")],o);export{o as SkdxPopoverContent};

package/dist/popover/PopoverDescription.cjs

@@ -0,0 +1,5 @@
+"use strict";var a=Object.defineProperty;var d=Object.getOwnPropertyDescriptor;var f=Object.getOwnPropertyNames;var E=Object.prototype.hasOwnProperty;var b=(r,e)=>{for(var s in e)a(r,s,{get:e[s],enumerable:!0})},g=(r,e,s,o)=>{if(e&&typeof e=="object"||typeof e=="function")for(let t of f(e))!E.call(r,t)&&t!==s&&a(r,t,{get:()=>e[t],enumerable:!(o=d(e,t))||o.enumerable});return r};var h=r=>g(a({},"__esModule",{value:!0}),r),c=(r,e,s,o)=>{for(var t=o>1?void 0:o?d(e,s):e,i=r.length-1,m;i>=0;i--)(m=r[i])&&(t=(o?m(e,s,t):m(t))||t);return o&&t&&a(e,s,t),t};var u={};b(u,{SkdxPopoverDescription:()=>l});module.exports=h(u);var p=require("lit"),n=require("../internal/define.cjs");var l=class extends p.LitElement{render(){return p.html`<p part="description"><slot></slot></p>`}};l.styles=p.css`
+    :host {
+      display: block;
+    }
+  `,l=c([(0,n.customElement)("skdx-popover-description","popover","description")],l);0&&(module.exports={SkdxPopoverDescription});

package/dist/popover/PopoverDescription.d.cts

@@ -0,0 +1,25 @@
+import { LitElement } from 'lit';
+/**
+ * Supporting text for the panel: wires `aria-describedby` only while rendered,
+ * preventing dangling IDREFs. Genuinely optional unlike `<skdx-popover-title>`.
+ * ID lands on host, not shadow `<p>`, because IDREFs never cross boundaries.
+ *
+ * @example
+ * ```html
+ * <skdx-popover-content>
+ *   <skdx-popover-title>Share this page</skdx-popover-title>
+ *   <skdx-popover-description>Anyone with the link can view it.</skdx-popover-description>
+ * </skdx-popover-content>
+ * ```
+ *
+ * @csspart description - The `<p>` element inside the shadow root.
+ */
+export declare class SkdxPopoverDescription extends LitElement {
+    static styles: import("lit").CSSResult;
+    render(): import("lit").TemplateResult<1>;
+}
+declare global {
+    interface HTMLElementTagNameMap {
+        'skdx-popover-description': SkdxPopoverDescription;
+    }
+}

package/dist/popover/PopoverDescription.d.ts

@@ -0,0 +1,25 @@
+import { LitElement } from 'lit';
+/**
+ * Supporting text for the panel: wires `aria-describedby` only while rendered,
+ * preventing dangling IDREFs. Genuinely optional unlike `<skdx-popover-title>`.
+ * ID lands on host, not shadow `<p>`, because IDREFs never cross boundaries.
+ *
+ * @example
+ * ```html
+ * <skdx-popover-content>
+ *   <skdx-popover-title>Share this page</skdx-popover-title>
+ *   <skdx-popover-description>Anyone with the link can view it.</skdx-popover-description>
+ * </skdx-popover-content>
+ * ```
+ *
+ * @csspart description - The `<p>` element inside the shadow root.
+ */
+export declare class SkdxPopoverDescription extends LitElement {
+    static styles: import("lit").CSSResult;
+    render(): import("lit").TemplateResult<1>;
+}
+declare global {
+    interface HTMLElementTagNameMap {
+        'skdx-popover-description': SkdxPopoverDescription;
+    }
+}

package/dist/popover/PopoverDescription.js

@@ -0,0 +1,5 @@
+var m=Object.defineProperty;var d=Object.getOwnPropertyDescriptor;var i=(o,r,l,s)=>{for(var e=s>1?void 0:s?d(r,l):r,p=o.length-1,a;p>=0;p--)(a=o[p])&&(e=(s?a(r,l,e):a(e))||e);return s&&e&&m(r,l,e),e};import{css as c,html as n,LitElement as f}from"lit";import{customElement as E}from"../internal/define.js";var t=class extends f{render(){return n`<p part="description"><slot></slot></p>`}};t.styles=c`
+    :host {
+      display: block;
+    }
+  `,t=i([E("skdx-popover-description","popover","description")],t);export{t as SkdxPopoverDescription};

package/dist/popover/PopoverPortal.d.cts

@@ -1,18 +1,9 @@
 import { SkdxPortal } from '../utils/portal.cjs';
 /**
- * `<skdx-popover-portal>` — teleports `<skdx-popover-content>` to
- * `document.body` (or a custom `container`), so the popover escapes any
- * clipping or `overflow` ancestor of its trigger.
- *
- * The **host element stays where you wrote it** and the *children* are the
- * things that move, into a `<div data-skdx-portal>` — so removing the family
- * root removes the portalled content with it, and the parts inside still
- * resolve that root through `closestThroughPortal()`.
- *
- * Adds nothing to `<skdx-portal>` but its tag name. Unlike React's
- * `PopoverPortal` it takes no `force-mount` and does not unmount on close: the
- * parts here never unmount, they hide via `hidden`, so there is nothing to
- * force and nothing to keep alive for an exit animation.
+ * Teleports `<skdx-popover-content>` to `document.body` (or custom container),
+ * escaping clipping/overflow ancestors. Host element stays in place; children
+ * move into `<div data-skdx-portal>`. Unlike React's PopoverPortal, takes no
+ * `force-mount` and never unmounts—parts hide via `hidden` instead.
  *
  * @example
  * ```html

package/dist/popover/PopoverPortal.d.ts

@@ -1,18 +1,9 @@
 import { SkdxPortal } from '../utils/portal.js';
 /**
- * `<skdx-popover-portal>` — teleports `<skdx-popover-content>` to
- * `document.body` (or a custom `container`), so the popover escapes any
- * clipping or `overflow` ancestor of its trigger.
- *
- * The **host element stays where you wrote it** and the *children* are the
- * things that move, into a `<div data-skdx-portal>` — so removing the family
- * root removes the portalled content with it, and the parts inside still
- * resolve that root through `closestThroughPortal()`.
- *
- * Adds nothing to `<skdx-portal>` but its tag name. Unlike React's
- * `PopoverPortal` it takes no `force-mount` and does not unmount on close: the
- * parts here never unmount, they hide via `hidden`, so there is nothing to
- * force and nothing to keep alive for an exit animation.
+ * Teleports `<skdx-popover-content>` to `document.body` (or custom container),
+ * escaping clipping/overflow ancestors. Host element stays in place; children
+ * move into `<div data-skdx-portal>`. Unlike React's PopoverPortal, takes no
+ * `force-mount` and never unmounts—parts hide via `hidden` instead.
  *
  * @example
  * ```html

package/dist/popover/PopoverRoot.cjs

@@ -0,0 +1,5 @@
+"use strict";var p=Object.defineProperty;var u=Object.getOwnPropertyDescriptor;var b=Object.getOwnPropertyNames;var C=Object.prototype.hasOwnProperty;var g=(e,o)=>{for(var t in o)p(e,t,{get:o[t],enumerable:!0})},y=(e,o,t,r)=>{if(o&&typeof o=="object"||typeof o=="function")for(let n of b(o))!C.call(e,n)&&n!==t&&p(e,n,{get:()=>o[n],enumerable:!(r=u(o,n))||r.enumerable});return e};var E=e=>y(p({},"__esModule",{value:!0}),e),l=(e,o,t,r)=>{for(var n=r>1?void 0:r?u(o,t):o,d=e.length-1,c;d>=0;d--)(c=e[d])&&(n=(r?c(o,t,n):c(n))||n);return r&&n&&p(o,t,n),n};var M={};g(M,{SkdxPopoverRoot:()=>i});module.exports=E(M);var s=require("lit"),a=require("lit/decorators.js"),h=require("../internal/define.cjs"),f=require("../internal/ids.cjs"),m=require("../internal/open-change-complete.cjs"),v=require("../internal/styles.cjs"),k=require("./PopoverPortal.cjs");var O={fromAttribute(e){return e===null?!1:e==="trap-focus"?"trap-focus":e===""||e==="true"},toAttribute(e){return e==="trap-focus"?"trap-focus":e?"":null}},i=class extends s.LitElement{constructor(){super(...arguments);this.open=!1;this.defaultOpen=!1;this.modal=!1;this.contentId=(0,f.nextId)("skdx-popover-content");this.triggerEl=null;this.anchorEl=null;this.repositionFn=null;this.hasUpdatedOnce=!1}connectedCallback(){super.connectedCallback(),this.defaultOpen&&!this.hasAttribute("open")&&(this.open=!0);let t=this.querySelector("skdx-popover-content")?.id;t&&(this.contentId=t)}disconnectedCallback(){this.teardownOpenChangeComplete?.(),super.disconnectedCallback()}updated(t){let r=!this.hasUpdatedOnce;this.hasUpdatedOnce=!0,t.has("open")&&!r&&this.dispatchEvent(new CustomEvent("open-change",{detail:this.open,bubbles:!0,composed:!0})),t.size>0&&this.dispatchEvent(new CustomEvent("skdx-popover-internal-update")),t.has("open")&&!r&&(this.teardownOpenChangeComplete?.(),this.teardownOpenChangeComplete=(0,m.notifyOpenChangeComplete)(()=>this.querySelector("skdx-popover-content"),this.open,n=>this.dispatchEvent(new CustomEvent("open-change-complete",{detail:n,bubbles:!0,composed:!0}))))}setOpen(t){this.open!==t&&(this.open=t)}focusTrigger(){this.triggerEl?.focus()}reposition(){this.repositionFn?.()}render(){return s.html`<slot></slot>`}};i.styles=[v.hiddenHostStyles,s.css`
+      :host {
+        display: contents;
+      }
+    `],l([(0,a.property)({type:Boolean,reflect:!0})],i.prototype,"open",2),l([(0,a.property)({type:Boolean,attribute:"default-open"})],i.prototype,"defaultOpen",2),l([(0,a.property)({converter:O,reflect:!0})],i.prototype,"modal",2),i=l([(0,h.customElement)("skdx-popover-root")],i);0&&(module.exports={SkdxPopoverRoot});

package/dist/popover/PopoverRoot.d.cts

@@ -0,0 +1,107 @@
+import { LitElement } from 'lit';
+import './PopoverPortal.cjs';
+/**
+ * The three points on Popover's modality axis — see `popoverContract`'s
+ * `modal` prop. `'trap-focus'` is one of three things the word carries here,
+ * distinct from what `modal` means on Dialog, AlertDialog and Drawer.
+ */
+export type PopoverModality = boolean | 'trap-focus';
+/**
+ * Popover's state primitive: owns `open`/`modal`, renders children verbatim
+ * through `<slot>`. Descendants find it via `closest('skdx-popover, skdx-popover-root')`
+ * and re-render on `skdx-popover-internal-update` events—the shared-state pattern
+ * Web Components need since there's no built-in context.
+ *
+ * Non-modal by default; content floats against trigger via `positionFloating()`
+ * with no portal. For manual composition, use this via
+ * `@skdx/web-components/primitives/popover`; `<skdx-popover>` is the derived recipe.
+ *
+ * @example
+ * ```html
+ * <skdx-popover-root>
+ *   <skdx-popover-trigger>Share</skdx-popover-trigger>
+ *   <skdx-popover-content>
+ *     <skdx-popover-title>Share this page</skdx-popover-title>
+ *     <skdx-popover-close>Close</skdx-popover-close>
+ *   </skdx-popover-content>
+ * </skdx-popover-root>
+ * ```
+ *
+ * @fires open-change - Fired with the new open state whenever it changes, controlled or not.
+ * @fires open-change-complete - Fired with the new open state after `<skdx-popover-content>`'s enter or exit animation has finished — as soon as the content has settled, when it declares no animation at all. Not cancelable: the change has already happened.
+ */
+export declare class SkdxPopoverRoot extends LitElement {
+    static styles: import("lit").CSSResult[];
+    /**
+     * Whether the popover is currently open. Listen for `open-change` to observe or override changes.
+     * @default false
+     */
+    open: boolean;
+    /**
+     * Initial open state, for uncontrolled usage. Applied once, on connect,
+     * and only if `open` wasn't already set.
+     * @default false
+     */
+    defaultOpen: boolean;
+    /**
+     * How much of the page the open popover takes over. Three points, because
+     * modality is three independent things: `false` (the default) contains
+     * nothing; `'trap-focus'` cycles Tab inside the panel and marks the rest of
+     * the document `inert`, leaving page scroll alone; `true` adds the
+     * body-scroll lock on top, which is what `modal` means on `<skdx-dialog>`,
+     * `<skdx-alert-dialog>` and `<skdx-drawer>`.
+     * Any value but `false` requires an `<skdx-popover-close>` inside the panel.
+     *
+     * A custom converter rather than `{ type: Boolean }`: Lit's boolean converter
+     * reads *attribute presence*, so `modal="trap-focus"` would arrive as `true`
+     * — the one mistake this widening exists to make impossible. The bare
+     * attribute and `"true"` map to `true`, `"trap-focus"` to itself, everything
+     * else to `false`; and the value reflects back as the empty attribute, the
+     * literal `trap-focus`, or nothing at all.
+     * @default false
+     */
+    modal: PopoverModality;
+    /** @internal Rewritten to a recipe host's own `id` when one is forwarded onto the derived Content — see `host-attributes.ts`. */
+    contentId: string;
+    /** @internal Set by `<skdx-popover-trigger>` once its native button mounts. */
+    triggerEl: HTMLElement | null;
+    /**
+     * @internal Set by `<skdx-popover-anchor>` while it is connected, and
+     * cleared when it disconnects. `<skdx-popover-content>` positions against
+     * this when present, else falls back to {@link triggerEl} — see that
+     * element's TSDoc.
+     */
+    anchorEl: HTMLElement | null;
+    /**
+     * @internal Published by `<skdx-popover-content>` while it is positioning and
+     * cleared when it stops, so {@link SkdxPopoverRoot.reposition} needs no lookup.
+     */
+    repositionFn: (() => void) | null;
+    private hasUpdatedOnce;
+    private teardownOpenChangeComplete?;
+    connectedCallback(): void;
+    disconnectedCallback(): void;
+    protected updated(changed: Map<string, unknown>): void;
+    /** @internal */
+    setOpen(next: boolean): void;
+    /** @internal */
+    focusTrigger(): void;
+    /**
+     * Recomputes the open panel's position immediately. The floating layer
+     * already re-runs on scroll, on resize and on an observed size change of
+     * either element; what it cannot see is the anchor *moving* for a reason the
+     * DOM never reports — a CSS transform finishing, a virtual list re-flowing
+     * its rows, a parent repositioned without changing size.
+     *
+     * A no-op while the popover is closed or the panel has not positioned yet:
+     * there is nothing to place, and a method a consumer has to guard would be
+     * worse than one that does nothing.
+     */
+    reposition(): void;
+    render(): import("lit").TemplateResult<1>;
+}
+declare global {
+    interface HTMLElementTagNameMap {
+        'skdx-popover-root': SkdxPopoverRoot;
+    }
+}

package/dist/popover/PopoverRoot.d.ts

@@ -0,0 +1,107 @@
+import { LitElement } from 'lit';
+import './PopoverPortal.js';
+/**
+ * The three points on Popover's modality axis — see `popoverContract`'s
+ * `modal` prop. `'trap-focus'` is one of three things the word carries here,
+ * distinct from what `modal` means on Dialog, AlertDialog and Drawer.
+ */
+export type PopoverModality = boolean | 'trap-focus';
+/**
+ * Popover's state primitive: owns `open`/`modal`, renders children verbatim
+ * through `<slot>`. Descendants find it via `closest('skdx-popover, skdx-popover-root')`
+ * and re-render on `skdx-popover-internal-update` events—the shared-state pattern
+ * Web Components need since there's no built-in context.
+ *
+ * Non-modal by default; content floats against trigger via `positionFloating()`
+ * with no portal. For manual composition, use this via
+ * `@skdx/web-components/primitives/popover`; `<skdx-popover>` is the derived recipe.
+ *
+ * @example
+ * ```html
+ * <skdx-popover-root>
+ *   <skdx-popover-trigger>Share</skdx-popover-trigger>
+ *   <skdx-popover-content>
+ *     <skdx-popover-title>Share this page</skdx-popover-title>
+ *     <skdx-popover-close>Close</skdx-popover-close>
+ *   </skdx-popover-content>
+ * </skdx-popover-root>
+ * ```
+ *
+ * @fires open-change - Fired with the new open state whenever it changes, controlled or not.
+ * @fires open-change-complete - Fired with the new open state after `<skdx-popover-content>`'s enter or exit animation has finished — as soon as the content has settled, when it declares no animation at all. Not cancelable: the change has already happened.
+ */
+export declare class SkdxPopoverRoot extends LitElement {
+    static styles: import("lit").CSSResult[];
+    /**
+     * Whether the popover is currently open. Listen for `open-change` to observe or override changes.
+     * @default false
+     */
+    open: boolean;
+    /**
+     * Initial open state, for uncontrolled usage. Applied once, on connect,
+     * and only if `open` wasn't already set.
+     * @default false
+     */
+    defaultOpen: boolean;
+    /**
+     * How much of the page the open popover takes over. Three points, because
+     * modality is three independent things: `false` (the default) contains
+     * nothing; `'trap-focus'` cycles Tab inside the panel and marks the rest of
+     * the document `inert`, leaving page scroll alone; `true` adds the
+     * body-scroll lock on top, which is what `modal` means on `<skdx-dialog>`,
+     * `<skdx-alert-dialog>` and `<skdx-drawer>`.
+     * Any value but `false` requires an `<skdx-popover-close>` inside the panel.
+     *
+     * A custom converter rather than `{ type: Boolean }`: Lit's boolean converter
+     * reads *attribute presence*, so `modal="trap-focus"` would arrive as `true`
+     * — the one mistake this widening exists to make impossible. The bare
+     * attribute and `"true"` map to `true`, `"trap-focus"` to itself, everything
+     * else to `false`; and the value reflects back as the empty attribute, the
+     * literal `trap-focus`, or nothing at all.
+     * @default false
+     */
+    modal: PopoverModality;
+    /** @internal Rewritten to a recipe host's own `id` when one is forwarded onto the derived Content — see `host-attributes.ts`. */
+    contentId: string;
+    /** @internal Set by `<skdx-popover-trigger>` once its native button mounts. */
+    triggerEl: HTMLElement | null;
+    /**
+     * @internal Set by `<skdx-popover-anchor>` while it is connected, and
+     * cleared when it disconnects. `<skdx-popover-content>` positions against
+     * this when present, else falls back to {@link triggerEl} — see that
+     * element's TSDoc.
+     */
+    anchorEl: HTMLElement | null;
+    /**
+     * @internal Published by `<skdx-popover-content>` while it is positioning and
+     * cleared when it stops, so {@link SkdxPopoverRoot.reposition} needs no lookup.
+     */
+    repositionFn: (() => void) | null;
+    private hasUpdatedOnce;
+    private teardownOpenChangeComplete?;
+    connectedCallback(): void;
+    disconnectedCallback(): void;
+    protected updated(changed: Map<string, unknown>): void;
+    /** @internal */
+    setOpen(next: boolean): void;
+    /** @internal */
+    focusTrigger(): void;
+    /**
+     * Recomputes the open panel's position immediately. The floating layer
+     * already re-runs on scroll, on resize and on an observed size change of
+     * either element; what it cannot see is the anchor *moving* for a reason the
+     * DOM never reports — a CSS transform finishing, a virtual list re-flowing
+     * its rows, a parent repositioned without changing size.
+     *
+     * A no-op while the popover is closed or the panel has not positioned yet:
+     * there is nothing to place, and a method a consumer has to guard would be
+     * worse than one that does nothing.
+     */
+    reposition(): void;
+    render(): import("lit").TemplateResult<1>;
+}
+declare global {
+    interface HTMLElementTagNameMap {
+        'skdx-popover-root': SkdxPopoverRoot;
+    }
+}

package/dist/popover/PopoverRoot.js

@@ -0,0 +1,5 @@
+var d=Object.defineProperty;var c=Object.getOwnPropertyDescriptor;var s=(t,i,e,r)=>{for(var o=r>1?void 0:r?c(i,e):i,l=t.length-1,p;l>=0;l--)(p=t[l])&&(o=(r?p(i,e,o):p(o))||o);return r&&o&&d(i,e,o),o};import{css as u,html as h,LitElement as f}from"lit";import{property as a}from"lit/decorators.js";import{customElement as m}from"../internal/define.js";import{nextId as v}from"../internal/ids.js";import{notifyOpenChangeComplete as b}from"../internal/open-change-complete.js";import{hiddenHostStyles as C}from"../internal/styles.js";import"./PopoverPortal.js";var g={fromAttribute(t){return t===null?!1:t==="trap-focus"?"trap-focus":t===""||t==="true"},toAttribute(t){return t==="trap-focus"?"trap-focus":t?"":null}},n=class extends f{constructor(){super(...arguments);this.open=!1;this.defaultOpen=!1;this.modal=!1;this.contentId=v("skdx-popover-content");this.triggerEl=null;this.anchorEl=null;this.repositionFn=null;this.hasUpdatedOnce=!1}connectedCallback(){super.connectedCallback(),this.defaultOpen&&!this.hasAttribute("open")&&(this.open=!0);let e=this.querySelector("skdx-popover-content")?.id;e&&(this.contentId=e)}disconnectedCallback(){this.teardownOpenChangeComplete?.(),super.disconnectedCallback()}updated(e){let r=!this.hasUpdatedOnce;this.hasUpdatedOnce=!0,e.has("open")&&!r&&this.dispatchEvent(new CustomEvent("open-change",{detail:this.open,bubbles:!0,composed:!0})),e.size>0&&this.dispatchEvent(new CustomEvent("skdx-popover-internal-update")),e.has("open")&&!r&&(this.teardownOpenChangeComplete?.(),this.teardownOpenChangeComplete=b(()=>this.querySelector("skdx-popover-content"),this.open,o=>this.dispatchEvent(new CustomEvent("open-change-complete",{detail:o,bubbles:!0,composed:!0}))))}setOpen(e){this.open!==e&&(this.open=e)}focusTrigger(){this.triggerEl?.focus()}reposition(){this.repositionFn?.()}render(){return h`<slot></slot>`}};n.styles=[C,u`
+      :host {
+        display: contents;
+      }
+    `],s([a({type:Boolean,reflect:!0})],n.prototype,"open",2),s([a({type:Boolean,attribute:"default-open"})],n.prototype,"defaultOpen",2),s([a({converter:g,reflect:!0})],n.prototype,"modal",2),n=s([m("skdx-popover-root")],n);export{n as SkdxPopoverRoot};

package/dist/popover/PopoverTitle.cjs

@@ -0,0 +1,5 @@
+"use strict";var m=Object.defineProperty;var c=Object.getOwnPropertyDescriptor;var h=Object.getOwnPropertyNames;var f=Object.prototype.hasOwnProperty;var E=(r,t)=>{for(var s in t)m(r,s,{get:t[s],enumerable:!0})},b=(r,t,s,l)=>{if(t&&typeof t=="object"||typeof t=="function")for(let e of h(t))!f.call(r,e)&&e!==s&&m(r,e,{get:()=>t[e],enumerable:!(l=c(t,e))||l.enumerable});return r};var g=r=>b(m({},"__esModule",{value:!0}),r),n=(r,t,s,l)=>{for(var e=l>1?void 0:l?c(t,s):t,i=r.length-1,p;i>=0;i--)(p=r[i])&&(e=(l?p(t,s,e):p(e))||e);return l&&e&&m(t,s,e),e};var u={};E(u,{SkdxPopoverTitle:()=>o});module.exports=g(u);var a=require("lit"),d=require("../internal/define.cjs");var o=class extends a.LitElement{render(){return a.html`<h2 part="title"><slot></slot></h2>`}};o.styles=a.css`
+    :host {
+      display: block;
+    }
+  `,o=n([(0,d.customElement)("skdx-popover-title","popover","title")],o);0&&(module.exports={SkdxPopoverTitle});

package/dist/popover/PopoverTitle.d.cts

@@ -0,0 +1,27 @@
+import { LitElement } from 'lit';
+/**
+ * Popover's accessible name: an `<h2>` that wires `aria-labelledby` to Content.
+ * Dialogs announce as bare "dialog" without a name, so rendering Title fixes
+ * naming by construction. Alternative: explicit `aria-label` on Content.
+ *
+ * ID lands on host, not shadow `<h2>`, because IDREFs never cross boundaries.
+ *
+ * @example
+ * ```html
+ * <skdx-popover-content>
+ *   <skdx-popover-title>Share this page</skdx-popover-title>
+ *   <skdx-popover-description>Anyone with the link can view it.</skdx-popover-description>
+ * </skdx-popover-content>
+ * ```
+ *
+ * @csspart title - The `<h2>` element inside the shadow root.
+ */
+export declare class SkdxPopoverTitle extends LitElement {
+    static styles: import("lit").CSSResult;
+    render(): import("lit").TemplateResult<1>;
+}
+declare global {
+    interface HTMLElementTagNameMap {
+        'skdx-popover-title': SkdxPopoverTitle;
+    }
+}

package/dist/popover/PopoverTitle.d.ts

@@ -0,0 +1,27 @@
+import { LitElement } from 'lit';
+/**
+ * Popover's accessible name: an `<h2>` that wires `aria-labelledby` to Content.
+ * Dialogs announce as bare "dialog" without a name, so rendering Title fixes
+ * naming by construction. Alternative: explicit `aria-label` on Content.
+ *
+ * ID lands on host, not shadow `<h2>`, because IDREFs never cross boundaries.
+ *
+ * @example
+ * ```html
+ * <skdx-popover-content>
+ *   <skdx-popover-title>Share this page</skdx-popover-title>
+ *   <skdx-popover-description>Anyone with the link can view it.</skdx-popover-description>
+ * </skdx-popover-content>
+ * ```
+ *
+ * @csspart title - The `<h2>` element inside the shadow root.
+ */
+export declare class SkdxPopoverTitle extends LitElement {
+    static styles: import("lit").CSSResult;
+    render(): import("lit").TemplateResult<1>;
+}
+declare global {
+    interface HTMLElementTagNameMap {
+        'skdx-popover-title': SkdxPopoverTitle;
+    }
+}

package/dist/popover/PopoverTitle.js

@@ -0,0 +1,5 @@
+var p=Object.defineProperty;var c=Object.getOwnPropertyDescriptor;var i=(l,r,o,s)=>{for(var t=s>1?void 0:s?c(r,o):r,a=l.length-1,m;a>=0;a--)(m=l[a])&&(t=(s?m(r,o,t):m(t))||t);return s&&t&&p(r,o,t),t};import{css as n,html as d,LitElement as h}from"lit";import{customElement as f}from"../internal/define.js";var e=class extends h{render(){return d`<h2 part="title"><slot></slot></h2>`}};e.styles=n`
+    :host {
+      display: block;
+    }
+  `,e=i([f("skdx-popover-title","popover","title")],e);export{e as SkdxPopoverTitle};