@skdx/react 0.26.0 → 0.28.0

package/dist/floating-panel/FloatingPanelTrigger.d.cts

@@ -1,10 +1,8 @@
 import * as React from 'react';
 import type { FloatingPanelTriggerProps } from './types.cjs';
 /**
- * Button that opens the panel, and the element focus returns to when the panel
- * closes. Sets `aria-haspopup="dialog"`, `aria-expanded`, `aria-controls`, and
- * `data-state` (`open`/`closed`). Clicking it while the panel is open closes
- * it again.
+ * Button that opens the panel and receives focus when it closes.
+ * Sets `aria-haspopup="dialog"`, `aria-expanded`, `aria-controls`, and `data-state`.
  *
  * @example
  * ```tsx

package/dist/floating-panel/FloatingPanelTrigger.d.ts

@@ -1,10 +1,8 @@
 import * as React from 'react';
 import type { FloatingPanelTriggerProps } from './types.js';
 /**
- * Button that opens the panel, and the element focus returns to when the panel
- * closes. Sets `aria-haspopup="dialog"`, `aria-expanded`, `aria-controls`, and
- * `data-state` (`open`/`closed`). Clicking it while the panel is open closes
- * it again.
+ * Button that opens the panel and receives focus when it closes.
+ * Sets `aria-haspopup="dialog"`, `aria-expanded`, `aria-controls`, and `data-state`.
  *
  * @example
  * ```tsx

package/dist/floating-panel/index.d.cts

@@ -1,10 +1,2 @@
-export * from './FloatingPanel.cjs';
-export { FloatingPanelTrigger } from './FloatingPanelTrigger.cjs';
-export { FloatingPanelPortal } from './FloatingPanelPortal.cjs';
-export { FloatingPanelContent } from './FloatingPanelContent.cjs';
-export { FloatingPanelHeader } from './FloatingPanelHeader.cjs';
-export { FloatingPanelTitle } from './FloatingPanelTitle.cjs';
-export { FloatingPanelCloseTrigger } from './FloatingPanelCloseTrigger.cjs';
-export { FloatingPanelResizeTrigger } from './FloatingPanelResizeTrigger.cjs';
-export { FloatingPanelStageTrigger } from './FloatingPanelStageTrigger.cjs';
-export type { FloatingPanelPosition, FloatingPanelSize, FloatingPanelGeometry, FloatingPanelStage, FloatingPanelResizeDirection, FloatingPanelProps, FloatingPanelTriggerProps, FloatingPanelPortalProps, FloatingPanelContentProps, FloatingPanelHeaderProps, FloatingPanelTitleProps, FloatingPanelCloseTriggerProps, FloatingPanelResizeTriggerProps, FloatingPanelStageTriggerProps, } from './types.cjs';
+export { FloatingPanel, gestureAnnouncement } from './FloatingPanel.cjs';
+export type { FloatingPanelProps, FloatingPanelPosition, FloatingPanelSize, FloatingPanelGeometry, FloatingPanelStage, FloatingPanelResizeDirection, } from './types.cjs';

package/dist/floating-panel/index.d.ts

@@ -1,10 +1,2 @@
-export * from './FloatingPanel.js';
-export { FloatingPanelTrigger } from './FloatingPanelTrigger.js';
-export { FloatingPanelPortal } from './FloatingPanelPortal.js';
-export { FloatingPanelContent } from './FloatingPanelContent.js';
-export { FloatingPanelHeader } from './FloatingPanelHeader.js';
-export { FloatingPanelTitle } from './FloatingPanelTitle.js';
-export { FloatingPanelCloseTrigger } from './FloatingPanelCloseTrigger.js';
-export { FloatingPanelResizeTrigger } from './FloatingPanelResizeTrigger.js';
-export { FloatingPanelStageTrigger } from './FloatingPanelStageTrigger.js';
-export type { FloatingPanelPosition, FloatingPanelSize, FloatingPanelGeometry, FloatingPanelStage, FloatingPanelResizeDirection, FloatingPanelProps, FloatingPanelTriggerProps, FloatingPanelPortalProps, FloatingPanelContentProps, FloatingPanelHeaderProps, FloatingPanelTitleProps, FloatingPanelCloseTriggerProps, FloatingPanelResizeTriggerProps, FloatingPanelStageTriggerProps, } from './types.js';
+export { FloatingPanel, gestureAnnouncement } from './FloatingPanel.js';
+export type { FloatingPanelProps, FloatingPanelPosition, FloatingPanelSize, FloatingPanelGeometry, FloatingPanelStage, FloatingPanelResizeDirection, } from './types.js';

package/dist/floating-panel/primitives.d.cts

@@ -0,0 +1,37 @@
+/**
+ * Advanced primitives for `FloatingPanel` — the parts the recipe composes.
+ *
+ * Reach for these for full manual composition — a panel the derived anatomy
+ * cannot express, or one opened by its own `FloatingPanelTrigger`.
+ *
+ * @example
+ * ```tsx
+ * import { FloatingPanelCloseTrigger, FloatingPanelContent, FloatingPanelHeader, FloatingPanelPortal, FloatingPanelResizeTrigger, FloatingPanelRoot, FloatingPanelStageTrigger, FloatingPanelTitle, FloatingPanelTrigger } from '@skdx/react/primitives/floating-panel';
+ *
+ * <FloatingPanelRoot>
+ *   <FloatingPanelTrigger>Open panel</FloatingPanelTrigger>
+ *   <FloatingPanelPortal>
+ *     <FloatingPanelContent>
+ *       <FloatingPanelHeader aria-label="Drag to move panel">
+ *         <FloatingPanelTitle>Inspector</FloatingPanelTitle>
+ *         <FloatingPanelStageTrigger stage="minimized">Minimize</FloatingPanelStageTrigger>
+ *         <FloatingPanelCloseTrigger>Close</FloatingPanelCloseTrigger>
+ *       </FloatingPanelHeader>
+ *       <p>Panel body.</p>
+ *       <FloatingPanelResizeTrigger direction="se" aria-label="Resize panel" />
+ *     </FloatingPanelContent>
+ *   </FloatingPanelPortal>
+ * </FloatingPanelRoot>
+ * ```
+ */
+export { FloatingPanelRoot } from './FloatingPanel.cjs';
+export { FloatingPanelTrigger } from './FloatingPanelTrigger.cjs';
+export { FloatingPanelPortal } from './FloatingPanelPortal.cjs';
+export { FloatingPanelContent } from './FloatingPanelContent.cjs';
+export { FloatingPanelHeader } from './FloatingPanelHeader.cjs';
+export { FloatingPanelTitle } from './FloatingPanelTitle.cjs';
+export { FloatingPanelCloseTrigger } from './FloatingPanelCloseTrigger.cjs';
+export { FloatingPanelResizeTrigger } from './FloatingPanelResizeTrigger.cjs';
+export { FloatingPanelStageTrigger } from './FloatingPanelStageTrigger.cjs';
+export type { FloatingPanelRootProps } from './FloatingPanel.cjs';
+export type { FloatingPanelTriggerProps, FloatingPanelPortalProps, FloatingPanelContentProps, FloatingPanelHeaderProps, FloatingPanelTitleProps, FloatingPanelCloseTriggerProps, FloatingPanelResizeTriggerProps, FloatingPanelStageTriggerProps, } from './types.cjs';

package/dist/floating-panel/primitives.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Advanced primitives for `FloatingPanel` — the parts the recipe composes.
+ *
+ * Reach for these for full manual composition — a panel the derived anatomy
+ * cannot express, or one opened by its own `FloatingPanelTrigger`.
+ *
+ * @example
+ * ```tsx
+ * import { FloatingPanelCloseTrigger, FloatingPanelContent, FloatingPanelHeader, FloatingPanelPortal, FloatingPanelResizeTrigger, FloatingPanelRoot, FloatingPanelStageTrigger, FloatingPanelTitle, FloatingPanelTrigger } from '@skdx/react/primitives/floating-panel';
+ *
+ * <FloatingPanelRoot>
+ *   <FloatingPanelTrigger>Open panel</FloatingPanelTrigger>
+ *   <FloatingPanelPortal>
+ *     <FloatingPanelContent>
+ *       <FloatingPanelHeader aria-label="Drag to move panel">
+ *         <FloatingPanelTitle>Inspector</FloatingPanelTitle>
+ *         <FloatingPanelStageTrigger stage="minimized">Minimize</FloatingPanelStageTrigger>
+ *         <FloatingPanelCloseTrigger>Close</FloatingPanelCloseTrigger>
+ *       </FloatingPanelHeader>
+ *       <p>Panel body.</p>
+ *       <FloatingPanelResizeTrigger direction="se" aria-label="Resize panel" />
+ *     </FloatingPanelContent>
+ *   </FloatingPanelPortal>
+ * </FloatingPanelRoot>
+ * ```
+ */
+export { FloatingPanelRoot } from './FloatingPanel.js';
+export { FloatingPanelTrigger } from './FloatingPanelTrigger.js';
+export { FloatingPanelPortal } from './FloatingPanelPortal.js';
+export { FloatingPanelContent } from './FloatingPanelContent.js';
+export { FloatingPanelHeader } from './FloatingPanelHeader.js';
+export { FloatingPanelTitle } from './FloatingPanelTitle.js';
+export { FloatingPanelCloseTrigger } from './FloatingPanelCloseTrigger.js';
+export { FloatingPanelResizeTrigger } from './FloatingPanelResizeTrigger.js';
+export { FloatingPanelStageTrigger } from './FloatingPanelStageTrigger.js';
+export type { FloatingPanelRootProps } from './FloatingPanel.js';
+export type { FloatingPanelTriggerProps, FloatingPanelPortalProps, FloatingPanelContentProps, FloatingPanelHeaderProps, FloatingPanelTitleProps, FloatingPanelCloseTriggerProps, FloatingPanelResizeTriggerProps, FloatingPanelStageTriggerProps, } from './types.js';

package/dist/floating-panel/types.d.cts

@@ -1,4 +1,5 @@
 import type * as React from 'react';
+import type { PassThroughProps } from '../utils/passThrough.cjs';
 import type { PortalProps } from '../utils/portal.cjs';
 import type { PrimitivePropsWithRef } from '../utils/primitive.cjs';
 import type { FocusOutsideEvent, InteractOutsideEvent } from '../utils/useDismiss.cjs';
@@ -13,43 +14,35 @@ export interface FloatingPanelSize {
     height: number;
 }
 /**
- * The panel's window state. `default` uses the stored `position`/`size`;
- * `maximized` fills the boundary; `minimized` collapses to whatever height its
- * header needs. Only `default` is directly draggable/resizable in a way the
- * user will see, since the other two override the published geometry.
+ * Panel window state. `default`: uses position/size; `maximized`: fills boundary;
+ * `minimized`: collapses to header height. Only `default` is draggable/resizable.
  */
 export type FloatingPanelStage = 'default' | 'minimized' | 'maximized';
 /** Which edge or corner a {@link FloatingPanelResizeTrigger} pulls. */
 export type FloatingPanelResizeDirection = 'n' | 's' | 'e' | 'w' | 'ne' | 'nw' | 'se' | 'sw';
 /**
- * Which of a floating panel's two gestures a release announcement is
- * describing — a header drag (`'move'`) or an edge/corner pull (`'resize'`).
- * Both gestures hand {@link FloatingPanelProps.getGestureAnnouncement} the same
- * {@link FloatingPanelGeometry}, so this is the only thing telling the wording
- * which half of it matters: a move reads out the position, a resize the size.
- * It reaches the live region once, when the gesture settles — a drag publishes
- * a new position on every pointer frame and every arrow-key nudge, and voicing
- * each one would flood the region.
- *
+ * Gesture type for release announcements: `'move'` (header drag) or `'resize'` (edge/corner pull).
+ * Announced once per gesture settlement (not per frame).
  * @internal
  */
 export type FloatingPanelGesture = 'move' | 'resize';
-/**
- * Shared state distributed from {@link FloatingPanel} to its parts via context. Not part of the public API.
- *
- * @internal
- */
+/** Shared state distributed from {@link FloatingPanel} to its parts via context. @internal */
 export interface FloatingPanelContextValue {
     triggerRef: React.RefObject<HTMLButtonElement | null>;
     contentRef: React.RefObject<HTMLDivElement | null>;
     contentId: string;
     titleId: string;
+    /** Whether title is mounted; Content uses this to withhold `aria-labelledby`. */
+    hasTitle: boolean;
+    setHasTitle: (present: boolean) => void;
     open: boolean;
     onOpenChange: (open: boolean) => void;
     position: FloatingPanelPosition;
     size: FloatingPanelSize;
     minSize: FloatingPanelSize;
     maxSize: FloatingPanelSize;
+    /** Measured boundary box (null before first measurement). ResizeTrigger uses it for `aria-valuemax`. */
+    bounds: FloatingPanelSize | null;
     stage: FloatingPanelStage;
     onStageChange: (stage: FloatingPanelStage) => void;
     moveBy: (dx: number, dy: number) => void;
@@ -66,15 +59,42 @@ export interface FloatingPanelContextValue {
     contentPresent: boolean;
     setContentPresent: (present: boolean) => void;
 }
-/** Props for the {@link FloatingPanel} root. */
-export interface FloatingPanelProps {
+/**
+ * Props for the {@link FloatingPanel} recipe. Pass-through attributes (`id`,
+ * `className`, `style`, `data-*`, `aria-*` — see {@link PassThroughProps}) land
+ * on the derived `FloatingPanelContent` surface.
+ */
+export interface FloatingPanelProps extends PassThroughProps {
     /**
-     * The trigger and portal, typically — the panel's own DOM (content, header,
-     * title, resize and stage triggers) is rendered by {@link FloatingPanelPortal}
-     * elsewhere.
-     * @default undefined — renders nothing if omitted.
+     * The panel's body, rendered inside the derived `FloatingPanelContent` below
+     * the derived header. Never inspected — the anatomy is always derived.
+     * @default undefined — an empty panel body.
      */
     children?: React.ReactNode;
+    /**
+     * The panel's heading, rendered as the derived title inside the derived
+     * header. Omitting it derives no title at all and withholds Content's
+     * `aria-labelledby` with it, so name a title-less panel with `aria-label`.
+     * @default undefined — no title renders.
+     */
+    title?: string;
+    /**
+     * Window controls (stage triggers). The `label` is provided, not derived from stage name
+     * (avoids baking English into headless library).
+     * @default []
+     */
+    stages?: ReadonlyArray<{
+        /** The window state this control switches the panel to. */
+        stage: FloatingPanelStage;
+        /** The control's visible text, and its accessible name. */
+        label: string;
+    }>;
+    /**
+     * Whether the derived header renders a close button. `false` withholds it,
+     * for a panel whose only exit is your own control or a programmatic close.
+     * @default true
+     */
+    dismissible?: boolean;
     /**
      * Whether the panel is open, for controlled usage. Pair with `onOpenChange`.
      * @default undefined — uncontrolled, tracks its own open state internally.
@@ -90,6 +110,12 @@ export interface FloatingPanelProps {
      * @default undefined — no-op if omitted.
      */
     onOpenChange?: (open: boolean) => void;
+    /**
+     * Fires once animation settles (settled counterpart to `onOpenChange`).
+     * Only on open transition; drag/resize have their own settled callbacks.
+     * @default undefined
+     */
+    onOpenChangeComplete?: (open: boolean) => void;
     /**
      * The panel's top-left corner, for controlled usage. Pair with `onPositionChange`
      * or the panel will refuse to move.
@@ -107,6 +133,12 @@ export interface FloatingPanelProps {
      * @default undefined — no-op if omitted.
      */
     onPositionChange?: (position: FloatingPanelPosition) => void;
+    /**
+     * Fires once when drag/arrow-key gesture settles (position to persist).
+     * Also fires after resize, since pulling west/north edge relocates origin.
+     * @default undefined
+     */
+    onPositionCommit?: (position: FloatingPanelPosition) => void;
     /**
      * The panel's box, for controlled usage. Pair with `onSizeChange` or the
      * panel will refuse to resize.
@@ -124,6 +156,12 @@ export interface FloatingPanelProps {
      * @default undefined — no-op if omitted.
      */
     onSizeChange?: (size: FloatingPanelSize) => void;
+    /**
+     * Fires once when resize gesture settles (size to persist).
+     * Move never fires it.
+     * @default undefined
+     */
+    onSizeCommit?: (size: FloatingPanelSize) => void;
     /**
      * Smallest box the panel can be resized to. Every resize is clamped to it,
      * so a consumer never has to defend against a zero-height panel.
@@ -230,13 +268,14 @@ export interface FloatingPanelContentProps extends PrimitivePropsWithRef<'div'>
      */
     onPointerDownOutside?: (event: PointerEvent) => void;
     /**
-     * Fires when focus moves to an element outside the panel and its trigger. Receives a cancelable stand-in carrying the original `focusin` as its `detail`, since `focusin` itself cannot be canceled. A non-modal panel does **not** close on this — it is reported so you can, if you want to.
-     * @default undefined — no-op if omitted.
+     * Fires when focus moves outside panel and trigger (cancelable, unlike `focusin`).
+     * Non-modal panels don't auto-close on this event.
+     * @default undefined
      */
     onFocusOutside?: (event: FocusOutsideEvent) => void;
     /**
-     * Fires for either kind of outside interaction — pointer-down or focus — immediately before the specific handler above and with the same event, so one `event.preventDefault()` here vetoes the dismissal whichever way it was triggered.
-     * @default undefined — no-op if omitted.
+     * Fires for pointer-down or focus outside, before specific handlers. One `preventDefault()` vetoes either.
+     * @default undefined
      */
     onInteractOutside?: (event: InteractOutsideEvent) => void;
 }

package/dist/floating-panel/types.d.ts

@@ -1,4 +1,5 @@
 import type * as React from 'react';
+import type { PassThroughProps } from '../utils/passThrough.js';
 import type { PortalProps } from '../utils/portal.js';
 import type { PrimitivePropsWithRef } from '../utils/primitive.js';
 import type { FocusOutsideEvent, InteractOutsideEvent } from '../utils/useDismiss.js';
@@ -13,43 +14,35 @@ export interface FloatingPanelSize {
     height: number;
 }
 /**
- * The panel's window state. `default` uses the stored `position`/`size`;
- * `maximized` fills the boundary; `minimized` collapses to whatever height its
- * header needs. Only `default` is directly draggable/resizable in a way the
- * user will see, since the other two override the published geometry.
+ * Panel window state. `default`: uses position/size; `maximized`: fills boundary;
+ * `minimized`: collapses to header height. Only `default` is draggable/resizable.
  */
 export type FloatingPanelStage = 'default' | 'minimized' | 'maximized';
 /** Which edge or corner a {@link FloatingPanelResizeTrigger} pulls. */
 export type FloatingPanelResizeDirection = 'n' | 's' | 'e' | 'w' | 'ne' | 'nw' | 'se' | 'sw';
 /**
- * Which of a floating panel's two gestures a release announcement is
- * describing — a header drag (`'move'`) or an edge/corner pull (`'resize'`).
- * Both gestures hand {@link FloatingPanelProps.getGestureAnnouncement} the same
- * {@link FloatingPanelGeometry}, so this is the only thing telling the wording
- * which half of it matters: a move reads out the position, a resize the size.
- * It reaches the live region once, when the gesture settles — a drag publishes
- * a new position on every pointer frame and every arrow-key nudge, and voicing
- * each one would flood the region.
- *
+ * Gesture type for release announcements: `'move'` (header drag) or `'resize'` (edge/corner pull).
+ * Announced once per gesture settlement (not per frame).
  * @internal
  */
 export type FloatingPanelGesture = 'move' | 'resize';
-/**
- * Shared state distributed from {@link FloatingPanel} to its parts via context. Not part of the public API.
- *
- * @internal
- */
+/** Shared state distributed from {@link FloatingPanel} to its parts via context. @internal */
 export interface FloatingPanelContextValue {
     triggerRef: React.RefObject<HTMLButtonElement | null>;
     contentRef: React.RefObject<HTMLDivElement | null>;
     contentId: string;
     titleId: string;
+    /** Whether title is mounted; Content uses this to withhold `aria-labelledby`. */
+    hasTitle: boolean;
+    setHasTitle: (present: boolean) => void;
     open: boolean;
     onOpenChange: (open: boolean) => void;
     position: FloatingPanelPosition;
     size: FloatingPanelSize;
     minSize: FloatingPanelSize;
     maxSize: FloatingPanelSize;
+    /** Measured boundary box (null before first measurement). ResizeTrigger uses it for `aria-valuemax`. */
+    bounds: FloatingPanelSize | null;
     stage: FloatingPanelStage;
     onStageChange: (stage: FloatingPanelStage) => void;
     moveBy: (dx: number, dy: number) => void;
@@ -66,15 +59,42 @@ export interface FloatingPanelContextValue {
     contentPresent: boolean;
     setContentPresent: (present: boolean) => void;
 }
-/** Props for the {@link FloatingPanel} root. */
-export interface FloatingPanelProps {
+/**
+ * Props for the {@link FloatingPanel} recipe. Pass-through attributes (`id`,
+ * `className`, `style`, `data-*`, `aria-*` — see {@link PassThroughProps}) land
+ * on the derived `FloatingPanelContent` surface.
+ */
+export interface FloatingPanelProps extends PassThroughProps {
     /**
-     * The trigger and portal, typically — the panel's own DOM (content, header,
-     * title, resize and stage triggers) is rendered by {@link FloatingPanelPortal}
-     * elsewhere.
-     * @default undefined — renders nothing if omitted.
+     * The panel's body, rendered inside the derived `FloatingPanelContent` below
+     * the derived header. Never inspected — the anatomy is always derived.
+     * @default undefined — an empty panel body.
      */
     children?: React.ReactNode;
+    /**
+     * The panel's heading, rendered as the derived title inside the derived
+     * header. Omitting it derives no title at all and withholds Content's
+     * `aria-labelledby` with it, so name a title-less panel with `aria-label`.
+     * @default undefined — no title renders.
+     */
+    title?: string;
+    /**
+     * Window controls (stage triggers). The `label` is provided, not derived from stage name
+     * (avoids baking English into headless library).
+     * @default []
+     */
+    stages?: ReadonlyArray<{
+        /** The window state this control switches the panel to. */
+        stage: FloatingPanelStage;
+        /** The control's visible text, and its accessible name. */
+        label: string;
+    }>;
+    /**
+     * Whether the derived header renders a close button. `false` withholds it,
+     * for a panel whose only exit is your own control or a programmatic close.
+     * @default true
+     */
+    dismissible?: boolean;
     /**
      * Whether the panel is open, for controlled usage. Pair with `onOpenChange`.
      * @default undefined — uncontrolled, tracks its own open state internally.
@@ -90,6 +110,12 @@ export interface FloatingPanelProps {
      * @default undefined — no-op if omitted.
      */
     onOpenChange?: (open: boolean) => void;
+    /**
+     * Fires once animation settles (settled counterpart to `onOpenChange`).
+     * Only on open transition; drag/resize have their own settled callbacks.
+     * @default undefined
+     */
+    onOpenChangeComplete?: (open: boolean) => void;
     /**
      * The panel's top-left corner, for controlled usage. Pair with `onPositionChange`
      * or the panel will refuse to move.
@@ -107,6 +133,12 @@ export interface FloatingPanelProps {
      * @default undefined — no-op if omitted.
      */
     onPositionChange?: (position: FloatingPanelPosition) => void;
+    /**
+     * Fires once when drag/arrow-key gesture settles (position to persist).
+     * Also fires after resize, since pulling west/north edge relocates origin.
+     * @default undefined
+     */
+    onPositionCommit?: (position: FloatingPanelPosition) => void;
     /**
      * The panel's box, for controlled usage. Pair with `onSizeChange` or the
      * panel will refuse to resize.
@@ -124,6 +156,12 @@ export interface FloatingPanelProps {
      * @default undefined — no-op if omitted.
      */
     onSizeChange?: (size: FloatingPanelSize) => void;
+    /**
+     * Fires once when resize gesture settles (size to persist).
+     * Move never fires it.
+     * @default undefined
+     */
+    onSizeCommit?: (size: FloatingPanelSize) => void;
     /**
      * Smallest box the panel can be resized to. Every resize is clamped to it,
      * so a consumer never has to defend against a zero-height panel.
@@ -230,13 +268,14 @@ export interface FloatingPanelContentProps extends PrimitivePropsWithRef<'div'>
      */
     onPointerDownOutside?: (event: PointerEvent) => void;
     /**
-     * Fires when focus moves to an element outside the panel and its trigger. Receives a cancelable stand-in carrying the original `focusin` as its `detail`, since `focusin` itself cannot be canceled. A non-modal panel does **not** close on this — it is reported so you can, if you want to.
-     * @default undefined — no-op if omitted.
+     * Fires when focus moves outside panel and trigger (cancelable, unlike `focusin`).
+     * Non-modal panels don't auto-close on this event.
+     * @default undefined
      */
     onFocusOutside?: (event: FocusOutsideEvent) => void;
     /**
-     * Fires for either kind of outside interaction — pointer-down or focus — immediately before the specific handler above and with the same event, so one `event.preventDefault()` here vetoes the dismissal whichever way it was triggered.
-     * @default undefined — no-op if omitted.
+     * Fires for pointer-down or focus outside, before specific handlers. One `preventDefault()` vetoes either.
+     * @default undefined
      */
     onInteractOutside?: (event: InteractOutsideEvent) => void;
 }

package/dist/form/Form.cjs

@@ -1 +1 @@
-"use strict";var ne=Object.create;var h=Object.defineProperty;var le=Object.getOwnPropertyDescriptor;var fe=Object.getOwnPropertyNames;var de=Object.getPrototypeOf,pe=Object.prototype.hasOwnProperty;var ue=(e,r)=>{for(var o in r)h(e,o,{get:r[o],enumerable:!0})},I=(e,r,o,s)=>{if(r&&typeof r=="object"||typeof r=="function")for(let t of fe(r))!pe.call(e,t)&&t!==o&&h(e,t,{get:()=>r[t],enumerable:!(s=le(r,t))||s.enumerable});return e};var R=(e,r,o)=>(o=e!=null?ne(de(e)):{},I(r||!e||!e.__esModule?h(o,"default",{value:e,enumerable:!0}):o,e)),ce=e=>I(h({},"__esModule",{value:!0}),e);var ve={};ue(ve,{Form:()=>O,FormControl:()=>C,FormErrorSummary:()=>T,FormField:()=>L,FormLabel:()=>M,FormMessage:()=>N,FormProvider:()=>A,FormSubmit:()=>V,useFormContext:()=>P});module.exports=ce(ve);var l=R(require("react"),1),w=require("../utils/composeRefs.cjs"),H=require("../utils/createContext.cjs"),D=require("../utils/part.cjs"),_=require("../utils/primitive.cjs"),g=require("react/jsx-runtime");function Fe(e){return{badInput:e.badInput,customError:e.customError,patternMismatch:e.patternMismatch,rangeOverflow:e.rangeOverflow,rangeUnderflow:e.rangeUnderflow,stepMismatch:e.stepMismatch,tooLong:e.tooLong,tooShort:e.tooShort,typeMismatch:e.typeMismatch,valueMissing:e.valueMissing,valid:e.valid}}var[A,P]=(0,H.createSafeContext)("Form"),O=l.forwardRef(({onSubmit:e,...r},o)=>{let s=l.useRef(null),t=(0,w.useComposedRefs)(o,s),[F,f]=l.useState({}),d=l.useCallback(m=>{if(!m||!("validity"in m)||!("name"in m))return;let i=m;i.name&&f(u=>({...u,[i.name]:Fe(i.validity)}))},[]);return l.useEffect(()=>{let m=s.current;if(!m)return;let i=c=>{c.preventDefault(),d(c.target)},u=c=>d(c.target);return m.addEventListener("invalid",i,!0),m.addEventListener("blur",u,!0),m.addEventListener("change",u,!0),()=>{m.removeEventListener("invalid",i,!0),m.removeEventListener("blur",u,!0),m.removeEventListener("change",u,!0)}},[d]),(0,g.jsx)(A,{validities:F,children:(0,g.jsx)(_.Primitive.form,{...r,...(0,D.skdxPart)("form","root",r.className),ref:t,onSubmit:m=>{if(m.defaultPrevented)return;let i=s.current;if(i){if(!i.checkValidity()){m.preventDefault();return}e?.(m)}}})})});O.displayName="Form";var b=R(require("react"),1),U=require("../utils/createContext.cjs"),B=require("../utils/part.cjs"),G=require("../utils/primitive.cjs"),x=require("react/jsx-runtime"),[Re,v]=(0,U.createSafeContext)("FormField"),L=b.forwardRef(({name:e,...r},o)=>{let s=b.useId(),t=b.useId();return(0,x.jsx)(Re,{name:e,id:s,messageId:t,children:(0,x.jsx)(G.Primitive.div,{...r,...(0,B.skdxPart)("form","field",r.className),ref:o})})});L.displayName="FormField";var Y=R(require("react"),1),$=require("../utils/part.cjs"),q=require("../utils/primitive.cjs");var z=require("react/jsx-runtime"),M=Y.forwardRef((e,r)=>{let o=v("FormLabel");return(0,z.jsx)(q.Primitive.label,{htmlFor:o.id,...e,...(0,$.skdxPart)("form","label",e.className),ref:r})});M.displayName="FormLabel";var J=R(require("react"),1),K=require("../utils/part.cjs"),Q=require("../utils/slot.cjs");var W=require("react/jsx-runtime"),C=J.forwardRef((e,r)=>{let o=v("FormControl"),t=P("FormControl").validities[o.name],F=t?!t.valid:!1,f={id:o.id,name:o.name,"aria-invalid":F||void 0,"aria-describedby":F?o.messageId:void 0};return(0,W.jsx)(Q.Slot,{...f,...e,...(0,K.skdxPart)("form","control",e.className),ref:r})});C.displayName="FormControl";var X=R(require("react"),1),Z=require("../utils/part.cjs"),j=require("../utils/primitive.cjs");var ee=require("react/jsx-runtime"),N=X.forwardRef(({match:e,forceMatch:r,...o},s)=>{let t=v("FormMessage"),f=P("FormMessage").validities[t.name],d=r??!1;return!d&&f&&(d=e?f[e]===!0:!f.valid),d?(0,ee.jsx)(j.Primitive.span,{id:t.messageId,...o,...(0,Z.skdxPart)("form","message",o.className),ref:s}):null});N.displayName="FormMessage";var re=R(require("react"),1),oe=require("../utils/part.cjs"),te=require("../utils/primitive.cjs"),me=require("react/jsx-runtime"),V=re.forwardRef((e,r)=>(0,me.jsx)(te.Primitive.button,{type:"submit",...e,...(0,oe.skdxPart)("form","submit",e.className),ref:r}));V.displayName="FormSubmit";var a=R(require("react"),1),p=require("../field/Field.cjs"),se=require("../utils/composeRefs.cjs"),S=require("../utils/part.cjs"),ae=require("../utils/primitive.cjs"),E=require("react/jsx-runtime"),T=a.forwardRef(({autoFocus:e=!0,children:r,...o},s)=>{let[t,F]=a.useState([]),[f,d]=a.useState(0),m=a.useRef(null),i=a.useRef(null),u=(0,se.useComposedRefs)(s,m),c=a.useRef(!1);return a.useEffect(()=>{let n=m.current;if(!n)return;let y=(0,p.errorSummaryScope)(n);i.current=y;let k=()=>d(ie=>ie+1);return y.addEventListener(p.FIELD_VALIDITY_CHANGE_EVENT,k),()=>y.removeEventListener(p.FIELD_VALIDITY_CHANGE_EVENT,k)},[]),a.useEffect(()=>{let n=i.current;n&&F((0,p.collectFieldErrors)(n))},[f]),a.useEffect(()=>{if(t.length===0){c.current=!1;return}c.current||(c.current=!0,e&&m.current?.focus())},[t,e]),(0,E.jsxs)(ae.Primitive.div,{role:"alert",tabIndex:-1,"data-skdx-error-summary":"",hidden:t.length===0||void 0,...o,...(0,S.skdxPart)("form","error-summary",o.className),ref:u,children:[t.length>0?r:null,(0,E.jsx)("ul",{...(0,S.skdxPart)("form","error-summary-list"),children:t.map(n=>(0,E.jsx)("li",{children:(0,E.jsx)("a",{...(0,S.skdxPart)("form","error-summary-link"),href:`#${n.id}`,onClick:y=>{y.preventDefault(),(0,p.focusFieldTarget)(n.id)},children:n.message})},n.id))})]})});T.displayName="FormErrorSummary";0&&(module.exports={Form,FormControl,FormErrorSummary,FormField,FormLabel,FormMessage,FormProvider,FormSubmit,useFormContext});
+"use strict";var De=Object.create;var _=Object.defineProperty;var _e=Object.getOwnPropertyDescriptor;var Be=Object.getOwnPropertyNames;var Oe=Object.getPrototypeOf,Ue=Object.prototype.hasOwnProperty;var qe=(e,r)=>{for(var t in r)_(e,t,{get:r[t],enumerable:!0})},me=(e,r,t,s)=>{if(r&&typeof r=="object"||typeof r=="function")for(let n of Be(r))!Ue.call(e,n)&&n!==t&&_(e,n,{get:()=>r[n],enumerable:!(s=_e(r,n))||s.enumerable});return e};var x=(e,r,t)=>(t=e!=null?De(Oe(e)):{},me(r||!e||!e.__esModule?_(t,"default",{value:e,enumerable:!0}):t,e)),ze=e=>me(_({},"__esModule",{value:!0}),e);var Ye={};qe(Ye,{Form:()=>Z,FormControl:()=>O,FormErrorSummary:()=>q,FormField:()=>K,FormFieldProvider:()=>de,FormFieldRoot:()=>J,FormLabel:()=>z,FormMessage:()=>G,FormProvider:()=>Ie,FormRoot:()=>X,FormSubmit:()=>Y,useFormContext:()=>w,useFormFieldContext:()=>P});module.exports=ze(Ye);var m=x(require("react"),1),$=require("../field/Field.cjs"),Ve=require("../utils/createContext.cjs"),He=require("../utils/part.cjs"),we=require("../utils/primitive.cjs"),W=require("../utils/useCallbackRef.cjs");var T=x(require("react"),1),ue=require("../utils/part.cjs"),pe=require("../utils/slot.cjs");function ae(...e){let r=[];for(let t of e)for(let s of(t??"").split(/\s+/))s&&!r.includes(s)&&r.push(s);return r.length>0?r.join(" "):void 0}var L=x(require("react"),1),B=require("../field/Field.cjs"),ie=require("../utils/createContext.cjs"),le=require("../utils/part.cjs"),ce=require("../utils/primitive.cjs");var H=require("react/jsx-runtime"),[de,P]=(0,ie.createSafeContext)("FormField"),J=L.forwardRef(({name:e,...r},t)=>{let s=L.useId(),n=L.useId();return(0,H.jsx)(de,{name:e,id:s,messageId:n,children:(0,H.jsx)(ce.Primitive.div,{[B.FORM_FIELD_ATTRIBUTE]:"",[B.FIELD_NAME_ATTRIBUTE]:e,...r,...(0,le.skdxPart)("form","field",r.className),ref:t})})});J.displayName="FormFieldRoot";var K=L.forwardRef(({label:e,message:r,children:t,...s},n)=>(0,H.jsx)(J,{...s,ref:n,children:(0,H.jsx)(fe,{label:e,message:r,children:t})}));K.displayName="FormField";var Fe=require("react/jsx-runtime"),O=T.forwardRef(({children:e,...r},t)=>{let s=P("FormControl"),n=w("FormControl"),d=n.validities[s.name],u=(d?!d.valid:!1)||n.serverErrors(s.name).length>0,p=T.isValidElement(e)?e:null,a=ae(r["aria-describedby"],p?.props["aria-describedby"],u?s.messageId:void 0),E={id:s.id,name:s.name,"aria-invalid":u||void 0};return(0,Fe.jsx)(pe.Slot,{...E,...r,"aria-describedby":a,...(0,ue.skdxPart)("form","control",r.className),ref:t,children:p?T.cloneElement(p,{"aria-describedby":a}):e})});O.displayName="FormControl";var l=x(require("react"),1),g=require("../field/Field.cjs"),Re=require("../utils/composeRefs.cjs"),U=require("../utils/part.cjs"),Ee=require("../utils/primitive.cjs"),R=require("react/jsx-runtime"),q=l.forwardRef(({autoFocus:e=!0,children:r,...t},s)=>{let[n,d]=l.useState([]),[u,p]=l.useState(0),a=l.useRef(null),E=l.useRef(null),M=(0,Re.useComposedRefs)(s,a),v=l.useRef(!1);l.useEffect(()=>{let c=a.current;if(!c)return;let b=(0,g.errorSummaryScope)(c);E.current=b;let V=()=>p(h=>h+1);for(let h of g.ERROR_SUMMARY_RESCAN_EVENTS)b.addEventListener(h,V,!0);return()=>{for(let h of g.ERROR_SUMMARY_RESCAN_EVENTS)b.removeEventListener(h,V,!0)}},[]),l.useEffect(()=>{let c=E.current;c&&d((0,g.collectFieldErrors)(c))},[u]),l.useEffect(()=>{if(n.length===0){v.current=!1;return}v.current||(v.current=!0,e&&a.current?.focus())},[n,e]);let k=(0,U.skdxPart)("form","error-summary",t.className),N=(0,R.jsx)("ul",{role:"list",...(0,U.skdxPart)("form","error-summary-list"),children:n.map(c=>(0,R.jsx)("li",{children:(0,R.jsx)("a",{...(0,U.skdxPart)("form","error-summary-link"),href:`#${c.id}`,onClick:b=>{b.preventDefault(),(0,g.focusFieldTarget)(c.id)},children:c.message})},c.id))}),S=t.asChild&&l.isValidElement(r)?l.cloneElement(r,void 0,(0,R.jsxs)(R.Fragment,{children:[n.length>0?r.props.children:null,N]})):(0,R.jsxs)(R.Fragment,{children:[n.length>0?r:null,N]});return(0,R.jsx)(Ee.Primitive.div,{role:"alert",tabIndex:-1,"data-skdx-error-summary":"",hidden:n.length===0||void 0,...t,...k,ref:M,children:S})});q.displayName="FormErrorSummary";var ye=x(require("react"),1),ge=require("../utils/part.cjs"),be=require("../utils/primitive.cjs");var ve=require("react/jsx-runtime"),z=ye.forwardRef((e,r)=>{let t=P("FormLabel");return(0,ve.jsx)(be.Primitive.label,{htmlFor:t.id,...e,...(0,ge.skdxPart)("form","label",e.className),ref:r})});z.displayName="FormLabel";var C=x(require("react"),1),xe=require("../field/Field.cjs"),Pe=require("../utils/part.cjs"),Me=require("../utils/primitive.cjs");function he(e){return e===void 0?[]:(Array.isArray(e)?e:[e]).filter(t=>typeof t=="string"&&t.trim()!=="")}function Q(e){return e.join(" ")}var Se=require("react/jsx-runtime"),G=C.forwardRef(({match:e,forceMatch:r,children:t,...s},n)=>{let d=P("FormMessage"),u=w("FormMessage"),p=u.validities[d.name],a=e?[]:u.serverErrors(d.name),E=r??a.length>0;!E&&p&&(E=e?p[e]===!0:!p.valid);let M=a.length===0?t:s.asChild&&C.isValidElement(t)?C.cloneElement(t,void 0,Q(a)):Q(a);return(0,Se.jsx)(Me.Primitive.span,{id:d.messageId,hidden:!E||void 0,[xe.FORM_MESSAGE_ATTRIBUTE]:"",...s,...(0,Pe.skdxPart)("form","message",s.className),ref:n,children:M})});G.displayName="FormMessage";var Le=x(require("react"),1),Te=require("../utils/part.cjs"),Ce=require("../utils/primitive.cjs"),ke=require("react/jsx-runtime"),Y=Le.forwardRef((e,r)=>(0,ke.jsx)(Ce.Primitive.button,{type:"submit",...e,...(0,Te.skdxPart)("form","submit",e.className),ref:r}));Y.displayName="FormSubmit";var f=require("react/jsx-runtime"),Ne=({errorSummary:e,submitLabel:r,children:t})=>(0,f.jsxs)(f.Fragment,{children:[e?(0,f.jsx)(q,{children:(0,f.jsx)("h2",{className:"skdx-form__error-summary-title",children:e})}):null,t,r?(0,f.jsx)(Y,{children:r}):null]}),fe=({label:e,message:r,children:t})=>(0,f.jsxs)(f.Fragment,{children:[e?(0,f.jsx)(z,{children:e}):null,(0,f.jsx)(O,{children:t}),(0,f.jsx)(G,{children:r})]});var I=require("react/jsx-runtime");function Ge(e){return{badInput:e.badInput,customError:e.customError,patternMismatch:e.patternMismatch,rangeOverflow:e.rangeOverflow,rangeUnderflow:e.rangeUnderflow,stepMismatch:e.stepMismatch,tooLong:e.tooLong,tooShort:e.tooShort,typeMismatch:e.typeMismatch,valueMissing:e.valueMissing,valid:e.valid}}var[Ie,w]=(0,Ve.createSafeContext)("Form"),X=m.forwardRef(({errors:e,onSubmit:r,onReset:t,onFieldInvalid:s,validationMode:n="change",validationBehavior:d="native",...u},p)=>{let a=m.useRef(null),[E,M]=m.useState({}),[v,k]=m.useState([]),N=m.useRef(e);N.current!==e&&(N.current=e,v.length>0&&k([]));let S=m.useRef({validationMode:n,validationBehavior:d});S.current={validationMode:n,validationBehavior:d};let c=m.useRef(!1),b=(0,W.useCallbackRef)(s),V=(0,W.useCallbackRef)(t),h=m.useCallback(o=>v.includes(o)?[]:he(e?.[o]),[e,v]),A=m.useCallback(o=>{if(!o||!("validity"in o)||!("name"in o))return;let i=o;i.name&&M(y=>({...y,[i.name]:Ge(i.validity)}))},[]),j=m.useCallback(o=>{let i=o?.name;i&&k(y=>y.includes(i)?y:[...y,i])},[]);m.useEffect(()=>{let o=a.current;if(!o)return;let i=null,y=F=>{F.preventDefault(),A(F.target);let D=F.target;if(D?.name&&D.validity&&b({name:D.name,validity:D.validity}),i)return;i=F.target;let Ae=c.current||S.current.validationBehavior==="aria";queueMicrotask(()=>{let se=i;if(i=null,!se||Ae)return;let ne=o.querySelector("[data-skdx-error-summary]");ne&&!ne.hasAttribute("hidden")||se.focus()})},re=F=>{S.current.validationMode!=="submit"&&A(F.target)},te=F=>{S.current.validationMode==="change"&&A(F.target),j(F.target)},oe=F=>{M({}),k([]),(0,$.resetFields)(o),V(F)};return o.addEventListener("invalid",y,!0),o.addEventListener("blur",re,!0),o.addEventListener("change",te,!0),o.addEventListener("reset",oe),()=>{o.removeEventListener("invalid",y,!0),o.removeEventListener("blur",re,!0),o.removeEventListener("change",te,!0),o.removeEventListener("reset",oe)}},[A,j,b,V]);let ee=m.useCallback(async()=>{let o=a.current;if(!o)return!0;c.current=!0;let i=o.checkValidity();c.current=!1;let y=await(0,$.validateFields)(o);return i&&y},[]);return m.useImperativeHandle(p,()=>a.current?Object.assign(a.current,{validate:ee}):{validate:ee}),(0,I.jsx)(Ie,{validities:E,serverErrors:h,children:(0,I.jsx)(we.Primitive.form,{...u,...(0,He.skdxPart)("form","root",u.className),ref:a,noValidate:d==="aria"?!0:u.noValidate,onSubmit:o=>{if(o.defaultPrevented)return;let i=a.current;if(i){if(d==="aria"){i.checkValidity(),r?.(o);return}if(!i.checkValidity()){o.preventDefault();return}r?.(o)}}})})});X.displayName="FormRoot";var Z=m.forwardRef(({errorSummary:e,submitLabel:r,children:t,...s},n)=>(0,I.jsx)(X,{...s,ref:n,children:(0,I.jsx)(Ne,{errorSummary:e,submitLabel:r,children:t})}));Z.displayName="Form";0&&(module.exports={Form,FormControl,FormErrorSummary,FormField,FormFieldProvider,FormFieldRoot,FormLabel,FormMessage,FormProvider,FormRoot,FormSubmit,useFormContext,useFormFieldContext});

package/dist/form/Form.d.cts

@@ -1,5 +1,5 @@
 import * as React from 'react';
-import type { FormContextValue, FormProps } from './types.cjs';
+import type { FormContextValue, FormProps, FormRootProps } from './types.cjs';
 export declare const FormProvider: {
     (props: FormContextValue & {
         children: React.ReactNode;
@@ -7,31 +7,53 @@ export declare const FormProvider: {
     displayName: string;
 }, useFormContext: (consumerName: string) => FormContextValue;
 /**
- * Root of a form: wires the browser's native Constraint Validation API into
- * a headless error-message system and hands per-field `ValidityState`
- * snapshots down to `FormField`/`FormControl`/`FormMessage` via context.
- * Renders a plain `<form>`.
+ * Wires native Constraint Validation API into headless error-message system.
+ * Hands per-field `ValidityState` snapshots to `FormField`/`FormControl`/`FormMessage` via context.
+ * Uses native validators (`required`, `pattern`, `type="email"`, etc); no custom validators.
+ * On submit, `checkValidity()` captures native `invalid` events (suppressing bubbles),
+ * fires `onFieldInvalid` per failure, prevents submit if any field fails.
  *
- * No custom validators — `required`/`pattern`/`min`/`type="email"` etc. on
- * the consumer's own input (rendered through `FormControl`) do the
- * validating. On submit, `checkValidity()` runs across every field; if any
- * fail, the native `invalid` event is captured (suppressing the browser's
- * validation-bubble UI) to snapshot that field's validity, the submit is
- * prevented, and `onSubmit` is not called. Fields are also re-validated on
- * `blur` and `change`.
+ * Wrap with `FormAnatomy` for derived error summary/submit button.
+ * Use directly via `@skdx/react/primitives/form`'s `FormRoot` for full manual composition.
  *
  * @example
  * ```tsx
- * <Form onSubmit={(e) => console.log('submitted')}>
- *   <FormField name="email">
+ * import { FormControl, FormFieldRoot, FormLabel, FormMessage, FormRoot, FormSubmit } from '@skdx/react/primitives/form';
+ *
+ * <FormRoot onSubmit={(e) => console.log('submitted')}>
+ *   <FormFieldRoot name="email">
  *     <FormLabel>Email</FormLabel>
  *     <FormControl>
  *       <input type="email" required />
  *     </FormControl>
  *     <FormMessage match="valueMissing">Email is required.</FormMessage>
  *     <FormMessage match="typeMismatch">Enter a valid email.</FormMessage>
- *   </FormField>
+ *   </FormFieldRoot>
  *   <FormSubmit>Submit</FormSubmit>
+ * </FormRoot>
+ * ```
+ */
+export declare const FormRoot: React.ForwardRefExoticComponent<Omit<FormRootProps, "ref"> & React.RefAttributes<HTMLFormElement>>;
+/**
+ * A form: native constraint validation wired into a headless error-message
+ * system, with per-field `ValidityState` snapshots handed to every descendant
+ * `FormField`.
+ *
+ * Draws the derived anatomy from `errorSummary`/`submitLabel`: the error
+ * summary ahead of the fields, the fields (`children`), and the submit button
+ * after them. Both are opt-in **by presence of their copy** — a heading and a
+ * button label are the consumer's own words, so with neither prop set the
+ * form derives nothing at all. `children` is the form's own content, never a
+ * switch. `FormField` stays public — placing one is a real semantic decision
+ * — while `FormLabel`, `FormControl`, `FormMessage`, `FormSubmit` and `FormErrorSummary` are
+ * primitives.
+ *
+ * @example
+ * ```tsx
+ * <Form onSubmit={save} errorSummary="There is a problem" submitLabel="Save">
+ *   <FormField name="email" label="Email" message="Enter a valid email.">
+ *     <input type="email" required />
+ *   </FormField>
  * </Form>
  * ```
  */