@skdx/react 0.26.0 → 0.28.0

package/dist/drawer/DrawerOverlay.d.ts

@@ -1,14 +1,10 @@
 import * as React from 'react';
 import type { DrawerOverlayProps } from './types.js';
 /**
- * Scrim rendered behind `DrawerContent`, typically styled to dim the page.
- * A real element rather than a `::backdrop` pseudo-element (see
- * `drawerContract`'s note on why Drawer is not a native `<dialog>`), so it
- * carries `data-state` and can fade on its own timeline while the panel
- * slides. Mounts only while open unless `forceMount` is set.
- *
- * Rendered whether or not the drawer is modal — a non-modal drawer usually
- * styles it `pointer-events: none` or leaves it out entirely.
+ * Scrim rendered behind `DrawerContent` with independent `data-state`. Allows
+ * the overlay to fade on its own timeline while the panel slides. Mounts only
+ * while open unless `forceMount` is set. Rendered whether modal or not — a
+ * non-modal drawer typically uses `pointer-events: none` or omits it.
  *
  * @example
  * ```tsx

package/dist/drawer/DrawerPortal.d.cts

@@ -1,10 +1,8 @@
 import type { DrawerPortalProps } from './types.cjs';
 /**
- * Teleports `DrawerOverlay` and `DrawerContent` to `document.body` (or a
- * custom `container`), so the drawer escapes any clipping/`overflow`
- * ancestors — including one with a `transform`/`filter`/`contain`, which
- * `position: fixed` alone cannot escape. Mounts only while open unless
- * `forceMount` is set.
+ * Teleports `DrawerOverlay` and `DrawerContent` to `document.body` or `container`,
+ * escaping clipping/overflow, including `transform`/`filter`/`contain`.
+ * Mounts only while open unless `forceMount` is set.
  *
  * @example
  * ```tsx

package/dist/drawer/DrawerPortal.d.ts

@@ -1,10 +1,8 @@
 import type { DrawerPortalProps } from './types.js';
 /**
- * Teleports `DrawerOverlay` and `DrawerContent` to `document.body` (or a
- * custom `container`), so the drawer escapes any clipping/`overflow`
- * ancestors — including one with a `transform`/`filter`/`contain`, which
- * `position: fixed` alone cannot escape. Mounts only while open unless
- * `forceMount` is set.
+ * Teleports `DrawerOverlay` and `DrawerContent` to `document.body` or `container`,
+ * escaping clipping/overflow, including `transform`/`filter`/`contain`.
+ * Mounts only while open unless `forceMount` is set.
  *
  * @example
  * ```tsx

package/dist/drawer/DrawerTrigger.d.cts

@@ -1,8 +1,7 @@
 import * as React from 'react';
 import type { DrawerTriggerProps } from './types.cjs';
 /**
- * Button that opens the drawer when clicked. Sets `aria-haspopup="dialog"`,
- * `aria-expanded`, `aria-controls`, and `data-state` (`open`/`closed`).
+ * Button that opens the drawer. Sets `aria-haspopup="dialog"`, `aria-expanded`, `aria-controls`, and `data-state`.
  *
  * @example
  * ```tsx

package/dist/drawer/DrawerTrigger.d.ts

@@ -1,8 +1,7 @@
 import * as React from 'react';
 import type { DrawerTriggerProps } from './types.js';
 /**
- * Button that opens the drawer when clicked. Sets `aria-haspopup="dialog"`,
- * `aria-expanded`, `aria-controls`, and `data-state` (`open`/`closed`).
+ * Button that opens the drawer. Sets `aria-haspopup="dialog"`, `aria-expanded`, `aria-controls`, and `data-state`.
  *
  * @example
  * ```tsx

package/dist/drawer/focusTargets.d.cts

@@ -0,0 +1,8 @@
+/**
+ * Resolves focus-target selector against scope, or returns null and warns once if unmatched.
+ * @param scope Content for `initialFocus`, document for `finalFocus`.
+ * @param selector the raw prop value, or `undefined` if consumer gave none
+ * @param prop which prop is being resolved, for the message
+ * @internal
+ */
+export declare function resolveFocusTarget(scope: ParentNode, selector: string | undefined, prop: 'initialFocus' | 'finalFocus'): HTMLElement | null;

package/dist/drawer/focusTargets.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Resolves focus-target selector against scope, or returns null and warns once if unmatched.
+ * @param scope Content for `initialFocus`, document for `finalFocus`.
+ * @param selector the raw prop value, or `undefined` if consumer gave none
+ * @param prop which prop is being resolved, for the message
+ * @internal
+ */
+export declare function resolveFocusTarget(scope: ParentNode, selector: string | undefined, prop: 'initialFocus' | 'finalFocus'): HTMLElement | null;

package/dist/drawer/index.d.cts

@@ -1,9 +1,2 @@
 export * from './Drawer.cjs';
-export { DrawerTrigger } from './DrawerTrigger.cjs';
-export { DrawerPortal } from './DrawerPortal.cjs';
-export { DrawerOverlay } from './DrawerOverlay.cjs';
-export { DrawerContent } from './DrawerContent.cjs';
-export { DrawerTitle } from './DrawerTitle.cjs';
-export { DrawerDescription } from './DrawerDescription.cjs';
-export { DrawerClose } from './DrawerClose.cjs';
-export type { DrawerPlacement, DrawerProps, DrawerTriggerProps, DrawerPortalProps, DrawerOverlayProps, DrawerContentProps, DrawerTitleProps, DrawerDescriptionProps, DrawerCloseProps, } from './types.cjs';
+export type { DrawerPlacement, DrawerDismiss, DrawerProps } from './types.cjs';

package/dist/drawer/index.d.ts

@@ -1,9 +1,2 @@
 export * from './Drawer.js';
-export { DrawerTrigger } from './DrawerTrigger.js';
-export { DrawerPortal } from './DrawerPortal.js';
-export { DrawerOverlay } from './DrawerOverlay.js';
-export { DrawerContent } from './DrawerContent.js';
-export { DrawerTitle } from './DrawerTitle.js';
-export { DrawerDescription } from './DrawerDescription.js';
-export { DrawerClose } from './DrawerClose.js';
-export type { DrawerPlacement, DrawerProps, DrawerTriggerProps, DrawerPortalProps, DrawerOverlayProps, DrawerContentProps, DrawerTitleProps, DrawerDescriptionProps, DrawerCloseProps, } from './types.js';
+export type { DrawerPlacement, DrawerDismiss, DrawerProps } from './types.js';

package/dist/drawer/primitives.d.cts

@@ -0,0 +1,30 @@
+/**
+ * Primitives for `Drawer` — manual composition escape hatch.
+ *
+ * @example
+ * ```tsx
+ * import { DrawerRoot, DrawerTrigger, DrawerPortal, DrawerOverlay, DrawerContent, DrawerTitle, DrawerDescription, DrawerClose } from '@skdx/react/primitives/drawer';
+ *
+ * <DrawerRoot placement="start">
+ *   <DrawerTrigger>Menu</DrawerTrigger>
+ *   <DrawerPortal>
+ *     <DrawerOverlay />
+ *     <DrawerContent>
+ *       <DrawerTitle>Navigation</DrawerTitle>
+ *       <DrawerDescription>Jump to a section.</DrawerDescription>
+ *       <DrawerClose>Close</DrawerClose>
+ *     </DrawerContent>
+ *   </DrawerPortal>
+ * </DrawerRoot>
+ * ```
+ */
+export { DrawerRoot } from './Drawer.cjs';
+export { DrawerTrigger } from './DrawerTrigger.cjs';
+export { DrawerPortal } from './DrawerPortal.cjs';
+export { DrawerOverlay } from './DrawerOverlay.cjs';
+export { DrawerContent } from './DrawerContent.cjs';
+export { DrawerTitle } from './DrawerTitle.cjs';
+export { DrawerDescription } from './DrawerDescription.cjs';
+export { DrawerClose } from './DrawerClose.cjs';
+export type { DrawerRootProps } from './Drawer.cjs';
+export type { DrawerPlacement, DrawerDismiss, DrawerTriggerProps, DrawerPortalProps, DrawerOverlayProps, DrawerContentProps, DrawerTitleProps, DrawerDescriptionProps, DrawerCloseProps, } from './types.cjs';

package/dist/drawer/primitives.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Primitives for `Drawer` — manual composition escape hatch.
+ *
+ * @example
+ * ```tsx
+ * import { DrawerRoot, DrawerTrigger, DrawerPortal, DrawerOverlay, DrawerContent, DrawerTitle, DrawerDescription, DrawerClose } from '@skdx/react/primitives/drawer';
+ *
+ * <DrawerRoot placement="start">
+ *   <DrawerTrigger>Menu</DrawerTrigger>
+ *   <DrawerPortal>
+ *     <DrawerOverlay />
+ *     <DrawerContent>
+ *       <DrawerTitle>Navigation</DrawerTitle>
+ *       <DrawerDescription>Jump to a section.</DrawerDescription>
+ *       <DrawerClose>Close</DrawerClose>
+ *     </DrawerContent>
+ *   </DrawerPortal>
+ * </DrawerRoot>
+ * ```
+ */
+export { DrawerRoot } from './Drawer.js';
+export { DrawerTrigger } from './DrawerTrigger.js';
+export { DrawerPortal } from './DrawerPortal.js';
+export { DrawerOverlay } from './DrawerOverlay.js';
+export { DrawerContent } from './DrawerContent.js';
+export { DrawerTitle } from './DrawerTitle.js';
+export { DrawerDescription } from './DrawerDescription.js';
+export { DrawerClose } from './DrawerClose.js';
+export type { DrawerRootProps } from './Drawer.js';
+export type { DrawerPlacement, DrawerDismiss, DrawerTriggerProps, DrawerPortalProps, DrawerOverlayProps, DrawerContentProps, DrawerTitleProps, DrawerDescriptionProps, DrawerCloseProps, } from './types.js';

package/dist/drawer/types.d.cts

@@ -1,15 +1,18 @@
 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';
 import type { AutoFocusEvent } from '../utils/useFocusTrap.cjs';
 /**
- * Which viewport edge the drawer is anchored to, expressed **logically**:
- * `start`/`end` follow the writing direction (start is the left edge under
- * `dir="ltr"` and the right edge under `dir="rtl"`), `top`/`bottom` are
- * physical. `bottom` is the bottom-sheet case.
+ * Viewport edge (logical: `start`/`end` mirror under `dir="rtl"`; `top`/`bottom` physical).
  */
 export type DrawerPlacement = 'start' | 'end' | 'top' | 'bottom';
+/**
+ * Dismissal policy: `any` (Escape + outside), `escape`, `outside`, or `none`.
+ * Events fire regardless; this only decides if un-prevented ones close the drawer.
+ */
+export type DrawerDismiss = 'any' | 'escape' | 'outside' | 'none';
 /** @internal Shared state distributed from {@link Drawer} to its parts via context. Not part of the public API. */
 export interface DrawerContextValue {
     triggerRef: React.RefObject<HTMLButtonElement | null>;
@@ -17,17 +20,27 @@ export interface DrawerContextValue {
     contentId: string;
     titleId: string;
     descriptionId: string;
+    /** Title mounted; used to gate `aria-labelledby`. */
+    hasTitle: boolean;
+    setHasTitle: (present: boolean) => void;
+    /** Description mounted; used to gate `aria-describedby`. */
+    hasDescription: boolean;
+    setHasDescription: (present: boolean) => void;
     open: boolean;
     onOpenChange: (open: boolean) => void;
     placement: DrawerPlacement;
     modal: boolean;
+    /** Dismissal policy (resolved); reflected as `data-dismiss` on Content. */
+    dismiss: DrawerDismiss;
 }
-/** Props for the {@link Drawer} root. */
-export interface DrawerProps {
+/**
+ * Props for the {@link Drawer} root. Standard attributes ({@link
+ * PassThroughProps}) land on the derived `DrawerContent` panel.
+ */
+export interface DrawerProps extends PassThroughProps {
     /**
-     * The trigger and portal, typically — the drawer's own DOM (overlay,
-     * content, title, description) is rendered by {@link DrawerPortal} elsewhere.
-     * @default undefined — renders nothing if omitted.
+     * Trigger and portal (typically). Drawer DOM rendered via {@link DrawerPortal}.
+     * @default undefined
      */
     children?: React.ReactNode;
     /**
@@ -46,29 +59,55 @@ export interface DrawerProps {
      */
     onOpenChange?: (open: boolean) => void;
     /**
-     * Fires with the new open state once the change has finished on screen —
-     * after `DrawerContent`'s enter or exit animation ends, or as soon as it has
-     * settled when the panel declares no animation. Use it for work that must not race
-     * the transition; use `onOpenChange` for work that must not wait for it.
-     * @default undefined — no-op if omitted.
+     * Fires once animation settles (after enter/exit, or immediately if none).
+     * For work that must not race the transition; use `onOpenChange` if you must not wait.
+     * @default undefined
      */
     onOpenChangeComplete?: (open: boolean) => void;
     /**
-     * Which viewport edge the drawer slides in from, expressed logically so it
-     * mirrors under `dir="rtl"`. Surfaces verbatim as `data-placement` on
-     * `DrawerContent` — the component never resolves it to a physical side, so
-     * position the panel with logical CSS (`inset-inline-start`, …).
+     * Viewport edge (logical, mirrors under `dir="rtl"`). Surfaces as `data-placement`.
+     * Position via logical CSS (`inset-inline-start`, …).
      * @default 'end'
      */
     placement?: DrawerPlacement;
     /**
-     * Whether the drawer traps focus, locks body scroll, and blocks interaction
-     * with the rest of the page. `false` gives a non-modal drawer that leaves
-     * the page interactive but keeps Escape, outside-interaction dismissal, and
-     * its place in the overlay stack.
+     * Trap focus, lock scroll, block page interaction. `false`: non-modal, page stays interactive,
+     * Escape/outside dismissal and overlay stack placement still apply.
      * @default true
      */
     modal?: boolean;
+    /**
+     * Dismissal policy: `'any'` (both), `'escape'`, `'outside'`, or `'none'`.
+     * Events still fire; handlers can answer refused attempts or veto allowed ones.
+     * Drawer dismisses on outside interaction whether modal or not; this is the only way to disable it.
+     * Reflected as `data-dismiss` on Content.
+     * @default 'any'
+     */
+    dismiss?: DrawerDismiss;
+    /**
+     * The derived panel's title, rendered as a `DrawerTitle`. Only read when
+     * `children` is plain body content — ignored under full manual composition.
+     * @default undefined — no derived title.
+     */
+    title?: string;
+    /**
+     * The derived panel's description, rendered as a `DrawerDescription`.
+     * Only read when `children` is plain body content.
+     * @default undefined — no derived description.
+     */
+    description?: string;
+    /**
+     * Content rendered after the body in the derived panel — typically the
+     * action buttons. Only read when `children` is plain body content.
+     * @default undefined — no footer.
+     */
+    footer?: React.ReactNode;
+    /**
+     * `false` forces `dismiss="none"` and withholds close button.
+     * Finer-grained `dismiss` prop applies when `true`.
+     * @default true
+     */
+    dismissible?: boolean;
 }
 /** Props for {@link DrawerTrigger}, the button that opens the drawer. */
 export interface DrawerTriggerProps extends PrimitivePropsWithRef<'button'> {
@@ -76,9 +115,7 @@ export interface DrawerTriggerProps extends PrimitivePropsWithRef<'button'> {
 /** Props for {@link DrawerPortal}, which teleports its children to `document.body`. */
 export interface DrawerPortalProps extends PortalProps {
     /**
-     * Render the portal even while the drawer is closed, instead of unmounting
-     * it. Useful for animation libraries that need the outgoing content present
-     * in the DOM during an exit transition.
+     * Keep portal mounted while closed (useful for exit animation libraries).
      * @default false
      */
     forceMount?: boolean;
@@ -86,9 +123,7 @@ export interface DrawerPortalProps extends PortalProps {
 /** Props for {@link DrawerOverlay}, the scrim rendered behind `DrawerContent`. */
 export interface DrawerOverlayProps extends PrimitivePropsWithRef<'div'> {
     /**
-     * Keep this overlay mounted even while the drawer is closed. Useful for
-     * animation libraries that need the outgoing overlay present in the DOM
-     * during an exit transition.
+     * Keep overlay mounted while closed (useful for exit animation libraries).
      * @default false
      */
     forceMount?: boolean;
@@ -96,42 +131,57 @@ export interface DrawerOverlayProps extends PrimitivePropsWithRef<'div'> {
 /** Props for {@link DrawerContent}, the drawer's sliding panel. */
 export interface DrawerContentProps extends PrimitivePropsWithRef<'div'> {
     /**
-     * Keep this panel mounted even while the drawer is closed. Useful for
-     * animation libraries that need the outgoing panel present in the DOM
-     * during an exit transition.
+     * Keep panel mounted while closed (useful for exit animation libraries).
      * @default false
      */
     forceMount?: boolean;
     /**
-     * Fires when Escape is pressed while the drawer is open, modal or not. Call `event.preventDefault()` to stop the drawer from closing.
-     * @default undefined — no-op if omitted.
+     * Fires on Escape (modal or non-modal). Call `event.preventDefault()` to prevent close.
+     * @default undefined
      */
     onEscapeKeyDown?: (event: KeyboardEvent) => void;
     /**
-     * Fires on pointer-down outside the content. Call `event.preventDefault()` to stop the drawer from closing.
-     * @default undefined — no-op if omitted.
+     * Fires on pointer-down outside. Call `event.preventDefault()` to prevent close.
+     * @default undefined
      */
     onPointerDownOutside?: (event: PointerEvent) => void;
     /**
-     * Fires when focus moves to an element outside the content. Call `event.preventDefault()` to stop the drawer from closing. Receives a cancelable stand-in carrying the original `focusin` as its `detail`, since `focusin` itself cannot be canceled.
-     * @default undefined — no-op if omitted.
+     * Fires when focus moves outside (cancelable stand-in for `focusin`).
+     * Call `event.preventDefault()` to prevent close.
+     * @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;
     /**
-     * Fires before focus moves into the content on open. Call `event.preventDefault()` to keep focus where it is and place it yourself. Modal drawers only — a non-modal drawer never moves focus.
-     * @default undefined — focus moves to the first tabbable element.
+     * Fires before focus enters on open (modal only). Call `event.preventDefault()` to place focus yourself.
+     * @default focus moves to first tabbable element.
      */
     onOpenAutoFocus?: (event: AutoFocusEvent) => void;
     /**
-     * Fires before focus returns to the previously focused element on close. Call `event.preventDefault()` to suppress the return — useful when the trigger no longer exists. Modal drawers only.
-     * @default undefined — focus returns to the element focused before the drawer opened.
+     * Fires before focus returns on close. Call `event.preventDefault()` to suppress return.
+     * Modal: always fires, returns to pre-open focus. Non-modal: fires only if user entered and would strand focus.
+     * @default focus returns to pre-open focus or Trigger.
      */
     onCloseAutoFocus?: (event: AutoFocusEvent) => void;
+    /**
+     * CSS selector (resolved inside panel) for element to focus on open.
+     * Applies only when `onOpenAutoFocus` not vetoed. Falls back to first tabbable element.
+     * Inert on non-modal drawer. Selector string, not ref (web-component compatibility).
+     * @default first tabbable element.
+     */
+    initialFocus?: string;
+    /**
+     * CSS selector (resolved at document level) for element to focus on close.
+     * Applies when `onCloseAutoFocus` not vetoed. Falls back to pre-open focus.
+     * On non-modal drawer, Escape return lands here instead of Trigger.
+     * @default pre-open focus.
+     */
+    finalFocus?: string;
 }
 /** Props for {@link DrawerTitle}, the drawer's accessible name. */
 export interface DrawerTitleProps extends PrimitivePropsWithRef<'h2'> {

package/dist/drawer/types.d.ts

@@ -1,15 +1,18 @@
 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';
 import type { AutoFocusEvent } from '../utils/useFocusTrap.js';
 /**
- * Which viewport edge the drawer is anchored to, expressed **logically**:
- * `start`/`end` follow the writing direction (start is the left edge under
- * `dir="ltr"` and the right edge under `dir="rtl"`), `top`/`bottom` are
- * physical. `bottom` is the bottom-sheet case.
+ * Viewport edge (logical: `start`/`end` mirror under `dir="rtl"`; `top`/`bottom` physical).
  */
 export type DrawerPlacement = 'start' | 'end' | 'top' | 'bottom';
+/**
+ * Dismissal policy: `any` (Escape + outside), `escape`, `outside`, or `none`.
+ * Events fire regardless; this only decides if un-prevented ones close the drawer.
+ */
+export type DrawerDismiss = 'any' | 'escape' | 'outside' | 'none';
 /** @internal Shared state distributed from {@link Drawer} to its parts via context. Not part of the public API. */
 export interface DrawerContextValue {
     triggerRef: React.RefObject<HTMLButtonElement | null>;
@@ -17,17 +20,27 @@ export interface DrawerContextValue {
     contentId: string;
     titleId: string;
     descriptionId: string;
+    /** Title mounted; used to gate `aria-labelledby`. */
+    hasTitle: boolean;
+    setHasTitle: (present: boolean) => void;
+    /** Description mounted; used to gate `aria-describedby`. */
+    hasDescription: boolean;
+    setHasDescription: (present: boolean) => void;
     open: boolean;
     onOpenChange: (open: boolean) => void;
     placement: DrawerPlacement;
     modal: boolean;
+    /** Dismissal policy (resolved); reflected as `data-dismiss` on Content. */
+    dismiss: DrawerDismiss;
 }
-/** Props for the {@link Drawer} root. */
-export interface DrawerProps {
+/**
+ * Props for the {@link Drawer} root. Standard attributes ({@link
+ * PassThroughProps}) land on the derived `DrawerContent` panel.
+ */
+export interface DrawerProps extends PassThroughProps {
     /**
-     * The trigger and portal, typically — the drawer's own DOM (overlay,
-     * content, title, description) is rendered by {@link DrawerPortal} elsewhere.
-     * @default undefined — renders nothing if omitted.
+     * Trigger and portal (typically). Drawer DOM rendered via {@link DrawerPortal}.
+     * @default undefined
      */
     children?: React.ReactNode;
     /**
@@ -46,29 +59,55 @@ export interface DrawerProps {
      */
     onOpenChange?: (open: boolean) => void;
     /**
-     * Fires with the new open state once the change has finished on screen —
-     * after `DrawerContent`'s enter or exit animation ends, or as soon as it has
-     * settled when the panel declares no animation. Use it for work that must not race
-     * the transition; use `onOpenChange` for work that must not wait for it.
-     * @default undefined — no-op if omitted.
+     * Fires once animation settles (after enter/exit, or immediately if none).
+     * For work that must not race the transition; use `onOpenChange` if you must not wait.
+     * @default undefined
      */
     onOpenChangeComplete?: (open: boolean) => void;
     /**
-     * Which viewport edge the drawer slides in from, expressed logically so it
-     * mirrors under `dir="rtl"`. Surfaces verbatim as `data-placement` on
-     * `DrawerContent` — the component never resolves it to a physical side, so
-     * position the panel with logical CSS (`inset-inline-start`, …).
+     * Viewport edge (logical, mirrors under `dir="rtl"`). Surfaces as `data-placement`.
+     * Position via logical CSS (`inset-inline-start`, …).
      * @default 'end'
      */
     placement?: DrawerPlacement;
     /**
-     * Whether the drawer traps focus, locks body scroll, and blocks interaction
-     * with the rest of the page. `false` gives a non-modal drawer that leaves
-     * the page interactive but keeps Escape, outside-interaction dismissal, and
-     * its place in the overlay stack.
+     * Trap focus, lock scroll, block page interaction. `false`: non-modal, page stays interactive,
+     * Escape/outside dismissal and overlay stack placement still apply.
      * @default true
      */
     modal?: boolean;
+    /**
+     * Dismissal policy: `'any'` (both), `'escape'`, `'outside'`, or `'none'`.
+     * Events still fire; handlers can answer refused attempts or veto allowed ones.
+     * Drawer dismisses on outside interaction whether modal or not; this is the only way to disable it.
+     * Reflected as `data-dismiss` on Content.
+     * @default 'any'
+     */
+    dismiss?: DrawerDismiss;
+    /**
+     * The derived panel's title, rendered as a `DrawerTitle`. Only read when
+     * `children` is plain body content — ignored under full manual composition.
+     * @default undefined — no derived title.
+     */
+    title?: string;
+    /**
+     * The derived panel's description, rendered as a `DrawerDescription`.
+     * Only read when `children` is plain body content.
+     * @default undefined — no derived description.
+     */
+    description?: string;
+    /**
+     * Content rendered after the body in the derived panel — typically the
+     * action buttons. Only read when `children` is plain body content.
+     * @default undefined — no footer.
+     */
+    footer?: React.ReactNode;
+    /**
+     * `false` forces `dismiss="none"` and withholds close button.
+     * Finer-grained `dismiss` prop applies when `true`.
+     * @default true
+     */
+    dismissible?: boolean;
 }
 /** Props for {@link DrawerTrigger}, the button that opens the drawer. */
 export interface DrawerTriggerProps extends PrimitivePropsWithRef<'button'> {
@@ -76,9 +115,7 @@ export interface DrawerTriggerProps extends PrimitivePropsWithRef<'button'> {
 /** Props for {@link DrawerPortal}, which teleports its children to `document.body`. */
 export interface DrawerPortalProps extends PortalProps {
     /**
-     * Render the portal even while the drawer is closed, instead of unmounting
-     * it. Useful for animation libraries that need the outgoing content present
-     * in the DOM during an exit transition.
+     * Keep portal mounted while closed (useful for exit animation libraries).
      * @default false
      */
     forceMount?: boolean;
@@ -86,9 +123,7 @@ export interface DrawerPortalProps extends PortalProps {
 /** Props for {@link DrawerOverlay}, the scrim rendered behind `DrawerContent`. */
 export interface DrawerOverlayProps extends PrimitivePropsWithRef<'div'> {
     /**
-     * Keep this overlay mounted even while the drawer is closed. Useful for
-     * animation libraries that need the outgoing overlay present in the DOM
-     * during an exit transition.
+     * Keep overlay mounted while closed (useful for exit animation libraries).
      * @default false
      */
     forceMount?: boolean;
@@ -96,42 +131,57 @@ export interface DrawerOverlayProps extends PrimitivePropsWithRef<'div'> {
 /** Props for {@link DrawerContent}, the drawer's sliding panel. */
 export interface DrawerContentProps extends PrimitivePropsWithRef<'div'> {
     /**
-     * Keep this panel mounted even while the drawer is closed. Useful for
-     * animation libraries that need the outgoing panel present in the DOM
-     * during an exit transition.
+     * Keep panel mounted while closed (useful for exit animation libraries).
      * @default false
      */
     forceMount?: boolean;
     /**
-     * Fires when Escape is pressed while the drawer is open, modal or not. Call `event.preventDefault()` to stop the drawer from closing.
-     * @default undefined — no-op if omitted.
+     * Fires on Escape (modal or non-modal). Call `event.preventDefault()` to prevent close.
+     * @default undefined
      */
     onEscapeKeyDown?: (event: KeyboardEvent) => void;
     /**
-     * Fires on pointer-down outside the content. Call `event.preventDefault()` to stop the drawer from closing.
-     * @default undefined — no-op if omitted.
+     * Fires on pointer-down outside. Call `event.preventDefault()` to prevent close.
+     * @default undefined
      */
     onPointerDownOutside?: (event: PointerEvent) => void;
     /**
-     * Fires when focus moves to an element outside the content. Call `event.preventDefault()` to stop the drawer from closing. Receives a cancelable stand-in carrying the original `focusin` as its `detail`, since `focusin` itself cannot be canceled.
-     * @default undefined — no-op if omitted.
+     * Fires when focus moves outside (cancelable stand-in for `focusin`).
+     * Call `event.preventDefault()` to prevent close.
+     * @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;
     /**
-     * Fires before focus moves into the content on open. Call `event.preventDefault()` to keep focus where it is and place it yourself. Modal drawers only — a non-modal drawer never moves focus.
-     * @default undefined — focus moves to the first tabbable element.
+     * Fires before focus enters on open (modal only). Call `event.preventDefault()` to place focus yourself.
+     * @default focus moves to first tabbable element.
      */
     onOpenAutoFocus?: (event: AutoFocusEvent) => void;
     /**
-     * Fires before focus returns to the previously focused element on close. Call `event.preventDefault()` to suppress the return — useful when the trigger no longer exists. Modal drawers only.
-     * @default undefined — focus returns to the element focused before the drawer opened.
+     * Fires before focus returns on close. Call `event.preventDefault()` to suppress return.
+     * Modal: always fires, returns to pre-open focus. Non-modal: fires only if user entered and would strand focus.
+     * @default focus returns to pre-open focus or Trigger.
      */
     onCloseAutoFocus?: (event: AutoFocusEvent) => void;
+    /**
+     * CSS selector (resolved inside panel) for element to focus on open.
+     * Applies only when `onOpenAutoFocus` not vetoed. Falls back to first tabbable element.
+     * Inert on non-modal drawer. Selector string, not ref (web-component compatibility).
+     * @default first tabbable element.
+     */
+    initialFocus?: string;
+    /**
+     * CSS selector (resolved at document level) for element to focus on close.
+     * Applies when `onCloseAutoFocus` not vetoed. Falls back to pre-open focus.
+     * On non-modal drawer, Escape return lands here instead of Trigger.
+     * @default pre-open focus.
+     */
+    finalFocus?: string;
 }
 /** Props for {@link DrawerTitle}, the drawer's accessible name. */
 export interface DrawerTitleProps extends PrimitivePropsWithRef<'h2'> {