@skdx/react 0.26.0 → 0.28.0

package/dist/popover/PopoverPortal.d.ts

@@ -1,17 +1,13 @@
 import type { PopoverPortalProps } from './types.js';
 /**
- * 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: {

package/dist/popover/PopoverTitle.d.cts

@@ -0,0 +1,17 @@
+import * as React from 'react';
+import type { PopoverTitleProps } from './types.cjs';
+/**
+ * The popover's accessible name: an `<h2>` whose id `PopoverContent` points to
+ * via `aria-labelledby` while mounted. Without it, `role="dialog"` announces as
+ * bare "dialog" (useless when multiple are on a page), forcing consumers to add
+ * `aria-label`. A visible Title names it correctly by construction.
+ *
+ * @example
+ * ```tsx
+ * <PopoverContent>
+ *   <PopoverTitle>Share this page</PopoverTitle>
+ *   <PopoverDescription>Anyone with the link can view it.</PopoverDescription>
+ * </PopoverContent>
+ * ```
+ */
+export declare const PopoverTitle: React.ForwardRefExoticComponent<Omit<PopoverTitleProps, "ref"> & React.RefAttributes<HTMLHeadingElement>>;

package/dist/popover/PopoverTitle.d.ts

@@ -0,0 +1,17 @@
+import * as React from 'react';
+import type { PopoverTitleProps } from './types.js';
+/**
+ * The popover's accessible name: an `<h2>` whose id `PopoverContent` points to
+ * via `aria-labelledby` while mounted. Without it, `role="dialog"` announces as
+ * bare "dialog" (useless when multiple are on a page), forcing consumers to add
+ * `aria-label`. A visible Title names it correctly by construction.
+ *
+ * @example
+ * ```tsx
+ * <PopoverContent>
+ *   <PopoverTitle>Share this page</PopoverTitle>
+ *   <PopoverDescription>Anyone with the link can view it.</PopoverDescription>
+ * </PopoverContent>
+ * ```
+ */
+export declare const PopoverTitle: React.ForwardRefExoticComponent<Omit<PopoverTitleProps, "ref"> & React.RefAttributes<HTMLHeadingElement>>;

package/dist/popover/PopoverTrigger.d.cts

@@ -1,9 +1,8 @@
 import * as React from 'react';
 import type { PopoverTriggerProps } from './types.cjs';
 /**
- * Button that opens the popover when clicked and doubles as the default
- * positioning anchor for `PopoverContent`. Sets `aria-haspopup="dialog"`,
- * `aria-expanded`, `aria-controls`, and `data-state` (`open`/`closed`).
+ * Button that opens the popover and serves as its positioning anchor.
+ * Sets `aria-haspopup`, `aria-expanded`, `aria-controls`, and `data-state`.
  *
  * @example
  * ```tsx

package/dist/popover/PopoverTrigger.d.ts

@@ -1,9 +1,8 @@
 import * as React from 'react';
 import type { PopoverTriggerProps } from './types.js';
 /**
- * Button that opens the popover when clicked and doubles as the default
- * positioning anchor for `PopoverContent`. Sets `aria-haspopup="dialog"`,
- * `aria-expanded`, `aria-controls`, and `data-state` (`open`/`closed`).
+ * Button that opens the popover and serves as its positioning anchor.
+ * Sets `aria-haspopup`, `aria-expanded`, `aria-controls`, and `data-state`.
  *
  * @example
  * ```tsx

package/dist/popover/focusTargets.d.cts

@@ -0,0 +1,9 @@
+/**
+ * Resolution of `PopoverContent`'s `initialFocus` / `finalFocus` CSS selector strings.
+ * Strings survive as attributes on `<skdx-popover-content>`; handles are impossible there.
+ * Unmatched selectors fall back to automatic targets (first tabbable on open, trigger on close);
+ * never throws.
+ *
+ * @internal
+ */
+export declare function resolveFocusSelector(root: ParentNode, selector: string | undefined, prop: 'initialFocus' | 'finalFocus'): HTMLElement | null;

package/dist/popover/focusTargets.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Resolution of `PopoverContent`'s `initialFocus` / `finalFocus` CSS selector strings.
+ * Strings survive as attributes on `<skdx-popover-content>`; handles are impossible there.
+ * Unmatched selectors fall back to automatic targets (first tabbable on open, trigger on close);
+ * never throws.
+ *
+ * @internal
+ */
+export declare function resolveFocusSelector(root: ParentNode, selector: string | undefined, prop: 'initialFocus' | 'finalFocus'): HTMLElement | null;

package/dist/popover/index.d.cts

@@ -1,6 +1,2 @@
 export * from './Popover.cjs';
-export { PopoverTrigger } from './PopoverTrigger.cjs';
-export { PopoverPortal } from './PopoverPortal.cjs';
-export { PopoverContent } from './PopoverContent.cjs';
-export { PopoverClose } from './PopoverClose.cjs';
-export type { PopoverProps, PopoverTriggerProps, PopoverPortalProps, PopoverContentProps, PopoverCloseProps, } from './types.cjs';
+export type { PopoverProps } from './types.cjs';

package/dist/popover/index.d.ts

@@ -1,6 +1,2 @@
 export * from './Popover.js';
-export { PopoverTrigger } from './PopoverTrigger.js';
-export { PopoverPortal } from './PopoverPortal.js';
-export { PopoverContent } from './PopoverContent.js';
-export { PopoverClose } from './PopoverClose.js';
-export type { PopoverProps, PopoverTriggerProps, PopoverPortalProps, PopoverContentProps, PopoverCloseProps, } from './types.js';
+export type { PopoverProps } from './types.js';

package/dist/popover/primitives.d.cts

@@ -0,0 +1,29 @@
+/**
+ * Primitives for `Popover` — manual composition escape hatch.
+ *
+ * @example
+ * ```tsx
+ * import { PopoverRoot, PopoverTrigger, PopoverPortal, PopoverContent, PopoverTitle, PopoverDescription, PopoverArrow, PopoverClose } from '@skdx/react/primitives/popover';
+ *
+ * <PopoverRoot>
+ *   <PopoverTrigger>Share</PopoverTrigger>
+ *   <PopoverPortal>
+ *     <PopoverContent side="bottom" align="start">
+ *       <PopoverTitle>Share this page</PopoverTitle>
+ *       <PopoverDescription>Anyone with the link can view it.</PopoverDescription>
+ *       <PopoverArrow />
+ *       <PopoverClose>Close</PopoverClose>
+ *     </PopoverContent>
+ *   </PopoverPortal>
+ * </PopoverRoot>
+ * ```
+ */
+export { PopoverRoot, PopoverAnchor, PopoverArrow } from './Popover.cjs';
+export { PopoverTrigger } from './PopoverTrigger.cjs';
+export { PopoverPortal } from './PopoverPortal.cjs';
+export { PopoverContent } from './PopoverContent.cjs';
+export { PopoverTitle } from './PopoverTitle.cjs';
+export { PopoverDescription } from './PopoverDescription.cjs';
+export { PopoverClose } from './PopoverClose.cjs';
+export type { PopoverRootProps } from './Popover.cjs';
+export type { PopoverTriggerProps, PopoverPortalProps, PopoverContentProps, PopoverTitleProps, PopoverDescriptionProps, PopoverCloseProps, } from './types.cjs';

package/dist/popover/primitives.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Primitives for `Popover` — manual composition escape hatch.
+ *
+ * @example
+ * ```tsx
+ * import { PopoverRoot, PopoverTrigger, PopoverPortal, PopoverContent, PopoverTitle, PopoverDescription, PopoverArrow, PopoverClose } from '@skdx/react/primitives/popover';
+ *
+ * <PopoverRoot>
+ *   <PopoverTrigger>Share</PopoverTrigger>
+ *   <PopoverPortal>
+ *     <PopoverContent side="bottom" align="start">
+ *       <PopoverTitle>Share this page</PopoverTitle>
+ *       <PopoverDescription>Anyone with the link can view it.</PopoverDescription>
+ *       <PopoverArrow />
+ *       <PopoverClose>Close</PopoverClose>
+ *     </PopoverContent>
+ *   </PopoverPortal>
+ * </PopoverRoot>
+ * ```
+ */
+export { PopoverRoot, PopoverAnchor, PopoverArrow } from './Popover.js';
+export { PopoverTrigger } from './PopoverTrigger.js';
+export { PopoverPortal } from './PopoverPortal.js';
+export { PopoverContent } from './PopoverContent.js';
+export { PopoverTitle } from './PopoverTitle.js';
+export { PopoverDescription } from './PopoverDescription.js';
+export { PopoverClose } from './PopoverClose.js';
+export type { PopoverRootProps } from './Popover.js';
+export type { PopoverTriggerProps, PopoverPortalProps, PopoverContentProps, PopoverTitleProps, PopoverDescriptionProps, PopoverCloseProps, } from './types.js';

package/dist/popover/types.d.cts

@@ -1,5 +1,6 @@
 import type * as React from 'react';
-import type { PopperContentProps } from '../utils/popper.cjs';
+import type { PassThroughProps } from '../utils/passThrough.cjs';
+import type { Align, PopperContentProps, Side } from '../utils/popper.cjs';
 import type { PortalProps } from '../utils/portal.cjs';
 import type { PrimitivePropsWithRef } from '../utils/primitive.cjs';
 import type { FocusOutsideEvent, InteractOutsideEvent } from '../utils/useDismiss.cjs';
@@ -9,17 +10,94 @@ export interface PopoverContextValue {
     triggerRef: React.RefObject<HTMLButtonElement | null>;
     contentRef: React.RefObject<HTMLDivElement | null>;
     contentId: string;
+    titleId: string;
+    descriptionId: string;
+    /** Whether a {@link PopoverTitle} is mounted, so Content can withhold a dangling `aria-labelledby`. */
+    hasTitle: boolean;
+    setHasTitle: (present: boolean) => void;
+    /** Whether a {@link PopoverDescription} is mounted, gating `aria-describedby` the same way. */
+    hasDescription: boolean;
+    setHasDescription: (present: boolean) => void;
     open: boolean;
     onOpenChange: (open: boolean) => void;
-    modal: boolean;
+    modal: PopoverModality;
+    /**
+     * Recomputes the panel's position immediately. React's binding of the
+     * cross-framework `reposition()` method: the root forwards no imperative
+     * handle, so the popover context is where this member lives here, exactly as
+     * `useCarouselContext` is React's binding of Carousel's movement methods.
+     *
+     * A no-op while the panel is closed or unmounted — there is nothing to place.
+     */
+    reposition: () => void;
 }
-/** Props for the {@link Popover} root. */
-export interface PopoverProps {
+/**
+ * The three points on the modality axis: modality is three independent
+ * things — focus containment, outside-interaction blocking, and the
+ * page-scroll lock — which collide when collapsed into a single boolean the
+ * way `modal` normally works on every other overlay in this system.
+ *
+ * - `false` — the default. Nothing is contained: focus, scroll and pointer all
+ *   reach the page behind the panel.
+ * - `'trap-focus'` — focus containment and outside-interaction blocking, page
+ *   scroll left alone.
+ * - `true` — all three: focus containment, outside-interaction blocking, and
+ *   the body-scroll lock Dialog, AlertDialog and Drawer already take. This is
+ *   what the word means everywhere else in the system.
+ */
+export type PopoverModality = boolean | 'trap-focus';
+/**
+ * Props for the {@link Popover} root. Standard attributes ({@link
+ * PassThroughProps}) land on the derived `PopoverContent` panel.
+ */
+export interface PopoverProps extends PassThroughProps {
     /**
-     * The trigger, portal, and content parts, distributed open state via context.
+     * Plain body content, or a hand-composed `PopoverTrigger`/`PopoverPortal` tree
+     * — these never mix. A tree replaces the derived anatomy and all
+     * `trigger`/`title`/`description`/`side`/`align`/`showArrow` props.
      * @default undefined
      */
     children?: React.ReactNode;
+    /**
+     * The trigger element for the derived anatomy, decorated with the popover's
+     * open/close behaviour and `aria-*` attributes via `asChild` — merged onto
+     * this element directly rather than wrapped in an extra `<button>`. A
+     * single element, e.g. `<Button>Share</Button>`. Ignored under full manual
+     * composition.
+     * @default undefined — no derived trigger renders.
+     */
+    trigger?: React.ReactElement;
+    /**
+     * The derived panel's title, rendered as a `PopoverTitle`. Only read when
+     * `children` is plain body content.
+     * @default undefined — no derived title.
+     */
+    title?: string;
+    /**
+     * The derived panel's description, rendered as a `PopoverDescription`.
+     * Only read when `children` is plain body content.
+     * @default undefined — no derived description.
+     */
+    description?: string;
+    /**
+     * Which side of the trigger the derived panel opens on. Only read when
+     * `children` is plain body content — set it on `PopoverContent` directly
+     * under full manual composition.
+     * @default 'bottom'
+     */
+    side?: Side;
+    /**
+     * Alignment of the derived panel along `side`. Only read when `children`
+     * is plain body content.
+     * @default 'center'
+     */
+    align?: Align;
+    /**
+     * Whether the derived panel renders a `PopoverArrow` pointing back at the
+     * trigger. Only read when `children` is plain body content.
+     * @default false
+     */
+    showArrow?: boolean;
     /**
      * Whether the popover is open, for controlled usage. Pair with `onOpenChange`.
      * @default undefined — uncontrolled, tracks its own open state internally.
@@ -44,11 +122,27 @@ export interface PopoverProps {
      */
     onOpenChangeComplete?: (open: boolean) => void;
     /**
-     * Whether `PopoverContent` traps focus while open. Non-modal (the default)
-     * lets the rest of the page stay interactive.
+     * How much of the page the open popover takes over. Three points, not two,
+     * because modality is three independent things, not one:
+     *
+     * - `false` (the default) — focus is not contained, the page keeps scrolling,
+     *   and everything behind the panel stays interactive. What a popover is for.
+     * - `'trap-focus'` — Tab cycles inside `PopoverContent` and the rest of the
+     *   document is marked `inert`, so pointer and assistive-technology access are
+     *   blocked too. Page scroll is untouched — reach for this value for the
+     *   focus and outside-interaction guarantees of `modal` without its
+     *   page-scroll lock.
+     * - `true` — all of the above *plus* the body-scroll lock, which is what
+     *   `modal` means on Dialog, AlertDialog and Drawer. Reach for it when the
+     *   panel must hold the user the way a dialog does.
+     *
+     * Any value other than `false` requires a `PopoverClose` inside Content: a
+     * trapped touch screen-reader user has no Escape key, and a panel with no
+     * in-panel exit is one they cannot leave. Development builds warn when it is
+     * missing.
      * @default false
      */
-    modal?: boolean;
+    modal?: PopoverModality;
 }
 /** Props for {@link PopoverTrigger}, the button that opens the popover and anchors its position. */
 export interface PopoverTriggerProps extends PrimitivePropsWithRef<'button'> {
@@ -76,6 +170,58 @@ export interface PopoverContentProps extends PopperContentProps {
      * @default false
      */
     forceMount?: boolean;
+    /**
+     * Clearance in pixels between the arrow and each end of the panel's edge, so
+     * the arrow cannot ride over a rounded corner. The arrow's *size* stays in
+     * CSS (`.skdx-popover__arrow`), which is where a shape belongs; only the
+     * clearance depends on the panel's radius, which the positioner is the only
+     * thing that can honour.
+     * @default 8
+     */
+    arrowPadding?: number;
+    /**
+     * Hide the panel while its anchor has been scrolled fully out of view inside
+     * a clipping ancestor, instead of leaving it floating over unrelated content.
+     *
+     * The panel is hidden (`visibility: hidden`, `pointer-events: none`), not
+     * unmounted and not closed: the popover is still open, and unmounting it on a
+     * scroll would tear down the focus trap and move the user's focus for a
+     * reason they did not ask for. Scrolling the anchor back into view shows it
+     * again.
+     * @default false
+     */
+    hideWhenDetached?: boolean;
+    /**
+     * CSS selector for the element that should receive focus when the popover
+     * opens, resolved with `querySelector` *inside* `PopoverContent` — so a
+     * selector may be as loose as `"input"` without reaching into the page
+     * behind. A selector rather than an element or a ref, because a handle has no
+     * spelling as a Web Components attribute (`initial-focus`) and the five ports
+     * take the same value.
+     *
+     * Live only where the popover moves focus in at all — that is, when `modal`
+     * contains focus (`'trap-focus'` or `true`). A non-modal popover leaves focus
+     * in the page on purpose, and this prop must not resurrect a move that
+     * deliberately does not happen. Applies only when `onOpenAutoFocus` was not
+     * prevented, and falls back to the first tabbable element (then the panel
+     * itself) when the selector matches nothing.
+     * @default undefined — the panel's first tabbable element, then the panel itself.
+     */
+    initialFocus?: string;
+    /**
+     * CSS selector for the element focus should be sent to when the popover
+     * closes, resolved at *document* level rather than inside the panel — by
+     * close time the panel is going away, and the point of naming a return target
+     * is that the trigger may no longer be the right place, or may no longer
+     * exist.
+     *
+     * Live whether or not the popover contains focus, because the return happens
+     * in both modes. Applies only when `onCloseAutoFocus` was not prevented, and
+     * falls back to the trigger (or, under a focus trap, to whatever was focused
+     * before the popover opened) when the selector matches nothing.
+     * @default undefined — the trigger, or whatever was focused before opening.
+     */
+    finalFocus?: string;
     /**
      * Fires when Escape is pressed while the popover is open. Call `event.preventDefault()` to stop it from closing.
      * @default undefined — no-op if omitted.
@@ -107,6 +253,12 @@ export interface PopoverContentProps extends PopperContentProps {
      */
     onCloseAutoFocus?: (event: AutoFocusEvent) => void;
 }
+/** Props for {@link PopoverTitle}, the popover's accessible name. */
+export interface PopoverTitleProps extends PrimitivePropsWithRef<'h2'> {
+}
+/** Props for {@link PopoverDescription}, the popover's accessible description. */
+export interface PopoverDescriptionProps extends PrimitivePropsWithRef<'p'> {
+}
 /** Props for {@link PopoverClose}, a button that closes the popover. */
 export interface PopoverCloseProps extends PrimitivePropsWithRef<'button'> {
 }

package/dist/popover/types.d.ts

@@ -1,5 +1,6 @@
 import type * as React from 'react';
-import type { PopperContentProps } from '../utils/popper.js';
+import type { PassThroughProps } from '../utils/passThrough.js';
+import type { Align, PopperContentProps, Side } from '../utils/popper.js';
 import type { PortalProps } from '../utils/portal.js';
 import type { PrimitivePropsWithRef } from '../utils/primitive.js';
 import type { FocusOutsideEvent, InteractOutsideEvent } from '../utils/useDismiss.js';
@@ -9,17 +10,94 @@ export interface PopoverContextValue {
     triggerRef: React.RefObject<HTMLButtonElement | null>;
     contentRef: React.RefObject<HTMLDivElement | null>;
     contentId: string;
+    titleId: string;
+    descriptionId: string;
+    /** Whether a {@link PopoverTitle} is mounted, so Content can withhold a dangling `aria-labelledby`. */
+    hasTitle: boolean;
+    setHasTitle: (present: boolean) => void;
+    /** Whether a {@link PopoverDescription} is mounted, gating `aria-describedby` the same way. */
+    hasDescription: boolean;
+    setHasDescription: (present: boolean) => void;
     open: boolean;
     onOpenChange: (open: boolean) => void;
-    modal: boolean;
+    modal: PopoverModality;
+    /**
+     * Recomputes the panel's position immediately. React's binding of the
+     * cross-framework `reposition()` method: the root forwards no imperative
+     * handle, so the popover context is where this member lives here, exactly as
+     * `useCarouselContext` is React's binding of Carousel's movement methods.
+     *
+     * A no-op while the panel is closed or unmounted — there is nothing to place.
+     */
+    reposition: () => void;
 }
-/** Props for the {@link Popover} root. */
-export interface PopoverProps {
+/**
+ * The three points on the modality axis: modality is three independent
+ * things — focus containment, outside-interaction blocking, and the
+ * page-scroll lock — which collide when collapsed into a single boolean the
+ * way `modal` normally works on every other overlay in this system.
+ *
+ * - `false` — the default. Nothing is contained: focus, scroll and pointer all
+ *   reach the page behind the panel.
+ * - `'trap-focus'` — focus containment and outside-interaction blocking, page
+ *   scroll left alone.
+ * - `true` — all three: focus containment, outside-interaction blocking, and
+ *   the body-scroll lock Dialog, AlertDialog and Drawer already take. This is
+ *   what the word means everywhere else in the system.
+ */
+export type PopoverModality = boolean | 'trap-focus';
+/**
+ * Props for the {@link Popover} root. Standard attributes ({@link
+ * PassThroughProps}) land on the derived `PopoverContent` panel.
+ */
+export interface PopoverProps extends PassThroughProps {
     /**
-     * The trigger, portal, and content parts, distributed open state via context.
+     * Plain body content, or a hand-composed `PopoverTrigger`/`PopoverPortal` tree
+     * — these never mix. A tree replaces the derived anatomy and all
+     * `trigger`/`title`/`description`/`side`/`align`/`showArrow` props.
      * @default undefined
      */
     children?: React.ReactNode;
+    /**
+     * The trigger element for the derived anatomy, decorated with the popover's
+     * open/close behaviour and `aria-*` attributes via `asChild` — merged onto
+     * this element directly rather than wrapped in an extra `<button>`. A
+     * single element, e.g. `<Button>Share</Button>`. Ignored under full manual
+     * composition.
+     * @default undefined — no derived trigger renders.
+     */
+    trigger?: React.ReactElement;
+    /**
+     * The derived panel's title, rendered as a `PopoverTitle`. Only read when
+     * `children` is plain body content.
+     * @default undefined — no derived title.
+     */
+    title?: string;
+    /**
+     * The derived panel's description, rendered as a `PopoverDescription`.
+     * Only read when `children` is plain body content.
+     * @default undefined — no derived description.
+     */
+    description?: string;
+    /**
+     * Which side of the trigger the derived panel opens on. Only read when
+     * `children` is plain body content — set it on `PopoverContent` directly
+     * under full manual composition.
+     * @default 'bottom'
+     */
+    side?: Side;
+    /**
+     * Alignment of the derived panel along `side`. Only read when `children`
+     * is plain body content.
+     * @default 'center'
+     */
+    align?: Align;
+    /**
+     * Whether the derived panel renders a `PopoverArrow` pointing back at the
+     * trigger. Only read when `children` is plain body content.
+     * @default false
+     */
+    showArrow?: boolean;
     /**
      * Whether the popover is open, for controlled usage. Pair with `onOpenChange`.
      * @default undefined — uncontrolled, tracks its own open state internally.
@@ -44,11 +122,27 @@ export interface PopoverProps {
      */
     onOpenChangeComplete?: (open: boolean) => void;
     /**
-     * Whether `PopoverContent` traps focus while open. Non-modal (the default)
-     * lets the rest of the page stay interactive.
+     * How much of the page the open popover takes over. Three points, not two,
+     * because modality is three independent things, not one:
+     *
+     * - `false` (the default) — focus is not contained, the page keeps scrolling,
+     *   and everything behind the panel stays interactive. What a popover is for.
+     * - `'trap-focus'` — Tab cycles inside `PopoverContent` and the rest of the
+     *   document is marked `inert`, so pointer and assistive-technology access are
+     *   blocked too. Page scroll is untouched — reach for this value for the
+     *   focus and outside-interaction guarantees of `modal` without its
+     *   page-scroll lock.
+     * - `true` — all of the above *plus* the body-scroll lock, which is what
+     *   `modal` means on Dialog, AlertDialog and Drawer. Reach for it when the
+     *   panel must hold the user the way a dialog does.
+     *
+     * Any value other than `false` requires a `PopoverClose` inside Content: a
+     * trapped touch screen-reader user has no Escape key, and a panel with no
+     * in-panel exit is one they cannot leave. Development builds warn when it is
+     * missing.
      * @default false
      */
-    modal?: boolean;
+    modal?: PopoverModality;
 }
 /** Props for {@link PopoverTrigger}, the button that opens the popover and anchors its position. */
 export interface PopoverTriggerProps extends PrimitivePropsWithRef<'button'> {
@@ -76,6 +170,58 @@ export interface PopoverContentProps extends PopperContentProps {
      * @default false
      */
     forceMount?: boolean;
+    /**
+     * Clearance in pixels between the arrow and each end of the panel's edge, so
+     * the arrow cannot ride over a rounded corner. The arrow's *size* stays in
+     * CSS (`.skdx-popover__arrow`), which is where a shape belongs; only the
+     * clearance depends on the panel's radius, which the positioner is the only
+     * thing that can honour.
+     * @default 8
+     */
+    arrowPadding?: number;
+    /**
+     * Hide the panel while its anchor has been scrolled fully out of view inside
+     * a clipping ancestor, instead of leaving it floating over unrelated content.
+     *
+     * The panel is hidden (`visibility: hidden`, `pointer-events: none`), not
+     * unmounted and not closed: the popover is still open, and unmounting it on a
+     * scroll would tear down the focus trap and move the user's focus for a
+     * reason they did not ask for. Scrolling the anchor back into view shows it
+     * again.
+     * @default false
+     */
+    hideWhenDetached?: boolean;
+    /**
+     * CSS selector for the element that should receive focus when the popover
+     * opens, resolved with `querySelector` *inside* `PopoverContent` — so a
+     * selector may be as loose as `"input"` without reaching into the page
+     * behind. A selector rather than an element or a ref, because a handle has no
+     * spelling as a Web Components attribute (`initial-focus`) and the five ports
+     * take the same value.
+     *
+     * Live only where the popover moves focus in at all — that is, when `modal`
+     * contains focus (`'trap-focus'` or `true`). A non-modal popover leaves focus
+     * in the page on purpose, and this prop must not resurrect a move that
+     * deliberately does not happen. Applies only when `onOpenAutoFocus` was not
+     * prevented, and falls back to the first tabbable element (then the panel
+     * itself) when the selector matches nothing.
+     * @default undefined — the panel's first tabbable element, then the panel itself.
+     */
+    initialFocus?: string;
+    /**
+     * CSS selector for the element focus should be sent to when the popover
+     * closes, resolved at *document* level rather than inside the panel — by
+     * close time the panel is going away, and the point of naming a return target
+     * is that the trigger may no longer be the right place, or may no longer
+     * exist.
+     *
+     * Live whether or not the popover contains focus, because the return happens
+     * in both modes. Applies only when `onCloseAutoFocus` was not prevented, and
+     * falls back to the trigger (or, under a focus trap, to whatever was focused
+     * before the popover opened) when the selector matches nothing.
+     * @default undefined — the trigger, or whatever was focused before opening.
+     */
+    finalFocus?: string;
     /**
      * Fires when Escape is pressed while the popover is open. Call `event.preventDefault()` to stop it from closing.
      * @default undefined — no-op if omitted.
@@ -107,6 +253,12 @@ export interface PopoverContentProps extends PopperContentProps {
      */
     onCloseAutoFocus?: (event: AutoFocusEvent) => void;
 }
+/** Props for {@link PopoverTitle}, the popover's accessible name. */
+export interface PopoverTitleProps extends PrimitivePropsWithRef<'h2'> {
+}
+/** Props for {@link PopoverDescription}, the popover's accessible description. */
+export interface PopoverDescriptionProps extends PrimitivePropsWithRef<'p'> {
+}
 /** Props for {@link PopoverClose}, a button that closes the popover. */
 export interface PopoverCloseProps extends PrimitivePropsWithRef<'button'> {
 }

package/dist/primitives/accordion.cjs

@@ -0,0 +1 @@
+"use strict";var n=Object.defineProperty;var s=Object.getOwnPropertyDescriptor;var x=Object.getOwnPropertyNames;var P=Object.prototype.hasOwnProperty;var a=(r,o)=>{for(var e in o)n(r,e,{get:o[e],enumerable:!0})},g=(r,o,e,t)=>{if(o&&typeof o=="object"||typeof o=="function")for(let c of x(o))!P.call(r,c)&&c!==e&&n(r,c,{get:()=>o[c],enumerable:!(t=s(o,c))||t.enumerable});return r};var I=r=>g(n({},"__esModule",{value:!0}),r);var y={};a(y,{Accordion:()=>d.Accordion,AccordionContent:()=>f.AccordionContent,AccordionHeader:()=>p.AccordionHeader,AccordionIndicator:()=>m.AccordionIndicator,AccordionItem:()=>i.AccordionItem,AccordionTrigger:()=>A.AccordionTrigger});module.exports=I(y);var d=require("../accordion/Accordion.cjs"),i=require("../accordion/Accordion.cjs"),p=require("../accordion/Accordion.cjs"),A=require("../accordion/Accordion.cjs"),m=require("../accordion/Accordion.cjs"),f=require("../accordion/Accordion.cjs");0&&(module.exports={Accordion,AccordionContent,AccordionHeader,AccordionIndicator,AccordionItem,AccordionTrigger});

package/dist/primitives/accordion.js

@@ -0,0 +1 @@
+import{Accordion as c}from"../accordion/Accordion.js";import{AccordionItem as n}from"../accordion/Accordion.js";import{AccordionHeader as d}from"../accordion/Accordion.js";import{AccordionTrigger as p}from"../accordion/Accordion.js";import{AccordionIndicator as m}from"../accordion/Accordion.js";import{AccordionContent as s}from"../accordion/Accordion.js";export{c as Accordion,s as AccordionContent,d as AccordionHeader,m as AccordionIndicator,n as AccordionItem,p as AccordionTrigger};

package/dist/primitives/alert-dialog.cjs

@@ -0,0 +1 @@
+"use strict";var t=Object.defineProperty;var f=Object.getOwnPropertyDescriptor;var x=Object.getOwnPropertyNames;var c=Object.prototype.hasOwnProperty;var T=(o,r)=>{for(var e in r)t(o,e,{get:r[e],enumerable:!0})},y=(o,r,e,i)=>{if(r&&typeof r=="object"||typeof r=="function")for(let l of x(r))!c.call(o,l)&&l!==e&&t(o,l,{get:()=>r[l],enumerable:!(i=f(r,l))||i.enumerable});return o};var C=o=>y(t({},"__esModule",{value:!0}),o);var v={};T(v,{AlertDialog:()=>a.AlertDialog,AlertDialogAction:()=>n.AlertDialogAction,AlertDialogCancel:()=>P.AlertDialogCancel,AlertDialogContent:()=>A.AlertDialogContent,AlertDialogDescription:()=>m.AlertDialogDescription,AlertDialogOverlay:()=>D.AlertDialogOverlay,AlertDialogPortal:()=>p.AlertDialogPortal,AlertDialogTitle:()=>s.AlertDialogTitle,AlertDialogTrigger:()=>g.AlertDialogTrigger});module.exports=C(v);var a=require("../alert-dialog/AlertDialog.cjs"),g=require("../alert-dialog/AlertDialog.cjs"),p=require("../alert-dialog/AlertDialog.cjs"),D=require("../alert-dialog/AlertDialog.cjs"),A=require("../alert-dialog/AlertDialog.cjs"),s=require("../alert-dialog/AlertDialog.cjs"),m=require("../alert-dialog/AlertDialog.cjs"),n=require("../alert-dialog/AlertDialog.cjs"),P=require("../alert-dialog/AlertDialog.cjs");0&&(module.exports={AlertDialog,AlertDialogAction,AlertDialogCancel,AlertDialogContent,AlertDialogDescription,AlertDialogOverlay,AlertDialogPortal,AlertDialogTitle,AlertDialogTrigger});

package/dist/primitives/alert-dialog.js

@@ -0,0 +1 @@
+import{AlertDialog as l}from"../alert-dialog/AlertDialog.js";import{AlertDialogTrigger as t}from"../alert-dialog/AlertDialog.js";import{AlertDialogPortal as a}from"../alert-dialog/AlertDialog.js";import{AlertDialogOverlay as p}from"../alert-dialog/AlertDialog.js";import{AlertDialogContent as A}from"../alert-dialog/AlertDialog.js";import{AlertDialogTitle as m}from"../alert-dialog/AlertDialog.js";import{AlertDialogDescription as P}from"../alert-dialog/AlertDialog.js";import{AlertDialogAction as x}from"../alert-dialog/AlertDialog.js";import{AlertDialogCancel as T}from"../alert-dialog/AlertDialog.js";export{l as AlertDialog,x as AlertDialogAction,T as AlertDialogCancel,A as AlertDialogContent,P as AlertDialogDescription,p as AlertDialogOverlay,a as AlertDialogPortal,m as AlertDialogTitle,t as AlertDialogTrigger};

package/dist/primitives/alert.cjs

@@ -0,0 +1 @@
+"use strict";var p=Object.defineProperty;var c=Object.getOwnPropertyDescriptor;var n=Object.getOwnPropertyNames;var P=Object.prototype.hasOwnProperty;var y=(o,r)=>{for(var e in r)p(o,e,{get:r[e],enumerable:!0})},C=(o,r,e,l)=>{if(r&&typeof r=="object"||typeof r=="function")for(let t of n(r))!P.call(o,t)&&t!==e&&p(o,t,{get:()=>r[t],enumerable:!(l=c(r,t))||l.enumerable});return o};var D=o=>C(p({},"__esModule",{value:!0}),o);var I={};y(I,{AlertAction:()=>x.AlertAction,AlertClose:()=>m.AlertClose,AlertDescription:()=>i.AlertDescription,AlertIcon:()=>f.AlertIcon,AlertRoot:()=>A.AlertRoot,AlertTitle:()=>s.AlertTitle});module.exports=D(I);var A=require("../alert/Alert.cjs"),s=require("../alert/Alert.cjs"),i=require("../alert/Alert.cjs"),f=require("../alert/Alert.cjs"),m=require("../alert/Alert.cjs"),x=require("../alert/Alert.cjs");0&&(module.exports={AlertAction,AlertClose,AlertDescription,AlertIcon,AlertRoot,AlertTitle});

package/dist/primitives/alert.js

@@ -0,0 +1 @@
+import{AlertRoot as t}from"../alert/Alert.js";import{AlertTitle as p}from"../alert/Alert.js";import{AlertDescription as A}from"../alert/Alert.js";import{AlertIcon as i}from"../alert/Alert.js";import{AlertClose as m}from"../alert/Alert.js";import{AlertAction as c}from"../alert/Alert.js";export{c as AlertAction,m as AlertClose,A as AlertDescription,i as AlertIcon,t as AlertRoot,p as AlertTitle};

package/dist/primitives/angle-slider.cjs

@@ -0,0 +1 @@
+"use strict";var p=Object.defineProperty;var S=Object.getOwnPropertyDescriptor;var m=Object.getOwnPropertyNames;var s=Object.prototype.hasOwnProperty;var t=(e,r)=>{for(var o in r)p(e,o,{get:r[o],enumerable:!0})},f=(e,r,o,d)=>{if(r&&typeof r=="object"||typeof r=="function")for(let l of m(r))!s.call(e,l)&&l!==o&&p(e,l,{get:()=>r[l],enumerable:!(d=S(r,l))||d.enumerable});return e};var x=e=>f(p({},"__esModule",{value:!0}),e);var a={};t(a,{AngleSlider:()=>g.AngleSlider,AngleSliderMark:()=>A.AngleSliderMark,AngleSliderMarks:()=>n.AngleSliderMarks,AngleSliderThumb:()=>i.AngleSliderThumb});module.exports=x(a);var g=require("../angle-slider/AngleSlider.cjs"),i=require("../angle-slider/AngleSlider.cjs"),n=require("../angle-slider/AngleSlider.cjs"),A=require("../angle-slider/AngleSlider.cjs");0&&(module.exports={AngleSlider,AngleSliderMark,AngleSliderMarks,AngleSliderThumb});

package/dist/primitives/angle-slider.js

@@ -0,0 +1 @@
+import{AngleSlider as l}from"../angle-slider/AngleSlider.js";import{AngleSliderThumb as p}from"../angle-slider/AngleSlider.js";import{AngleSliderMarks as g}from"../angle-slider/AngleSlider.js";import{AngleSliderMark as n}from"../angle-slider/AngleSlider.js";export{l as AngleSlider,n as AngleSliderMark,g as AngleSliderMarks,p as AngleSliderThumb};