@howells/stacksheet 1.0.0 → 1.1.0

package/dist/index.d.ts

@@ -5,28 +5,16 @@ import * as react_jsx_runtime from 'react/jsx-runtime';
 /**
  * Spring presets inspired by iOS animation feel.
  *
- * - `soft` — Very gentle, slow settle. Loaders, radial pickers.
  * - `subtle` — Barely noticeable bounce, professional.
- * - `natural` — Balanced, general-purpose default.
  * - `snappy` — Quick, responsive for interactions.
  * - `stiff` — Very quick, controlled. Panels, drawers. **(default)**
  */
 declare const springs: {
-    readonly soft: {
-        readonly stiffness: 120;
-        readonly damping: 18;
-        readonly mass: 1;
-    };
     readonly subtle: {
         readonly stiffness: 300;
         readonly damping: 30;
         readonly mass: 1;
     };
-    readonly natural: {
-        readonly stiffness: 200;
-        readonly damping: 20;
-        readonly mass: 1;
-    };
     readonly snappy: {
         readonly stiffness: 400;
         readonly damping: 28;
@@ -40,6 +28,15 @@ declare const springs: {
 };
 type SpringPreset = keyof typeof springs;
 
+/** Why the sheet stack was closed or popped */
+type CloseReason = "escape" | "backdrop" | "swipe" | "programmatic";
+/**
+ * A snap point for bottom sheets.
+ * - `number` 0-1: fraction of viewport height (e.g. 0.5 = 50vh)
+ * - `number` > 1: pixel value (e.g. 300 = 300px)
+ * - `string`: CSS length (e.g. "148px", "30rem")
+ */
+type SnapPoint = number | string;
 interface StacksheetClassNames {
     /** Applied to backdrop overlay */
     backdrop?: string;
@@ -75,13 +72,13 @@ type SideConfig = Side | ResponsiveSide;
 interface StackingConfig {
     /** Scale reduction per depth level (default: 0.04) */
     scaleStep: number;
-    /** Horizontal/vertical offset per depth level in px (default: 24) */
+    /** Pixel offset per depth level — shifts panels away from the stack edge (default: 16) */
     offsetStep: number;
     /** Opacity reduction per depth level (default: 0) */
     opacityStep: number;
     /** Border radius applied to stacked panels in px (default: 12) */
     radius: number;
-    /** Max depth before content stops rendering (default: 5) */
+    /** Max depth before content stops rendering (default: 3) */
     renderThreshold: number;
 }
 interface SpringConfig {
@@ -122,7 +119,15 @@ interface StacksheetConfig {
     /** Called when the top panel's entrance animation completes */
     onOpenComplete?: () => void;
     /** Called when the last panel's exit animation completes (stack fully closed) */
-    onCloseComplete?: () => void;
+    onCloseComplete?: (reason: CloseReason) => void;
+    /** Snap positions for bottom sheets. Numbers 0-1 = viewport fraction, >1 = px, strings = CSS lengths. */
+    snapPoints?: SnapPoint[];
+    /** Currently active snap point index (controlled). */
+    snapPointIndex?: number;
+    /** Called when the active snap point changes. */
+    onSnapPointChange?: (index: number) => void;
+    /** When true, velocity can't skip intermediate snap points. Default: false */
+    snapToSequentialPoints?: boolean;
     /** Enable drag-to-dismiss. Default: true */
     drag?: boolean;
     /** Fraction of panel dimension to trigger close (0-1). Default: 0.25 */
@@ -154,7 +159,11 @@ interface ResolvedConfig {
     zIndex: number;
     ariaLabel: string;
     onOpenComplete?: () => void;
-    onCloseComplete?: () => void;
+    onCloseComplete?: (reason: CloseReason) => void;
+    snapPoints: SnapPoint[];
+    snapPointIndex?: number;
+    onSnapPointChange?: (index: number) => void;
+    snapToSequentialPoints: boolean;
     drag: boolean;
     closeThreshold: number;
     velocityThreshold: number;
@@ -166,16 +175,16 @@ interface ResolvedConfig {
 /** Component rendered inside a sheet panel — receives data as spread props */
 type SheetContentComponent<TData = unknown> = ComponentType<TData extends Record<string, unknown> ? TData : Record<string, unknown>>;
 /** Map of sheet type → content component */
-type ContentMap<TMap extends Record<string, unknown>> = {
+type ContentMap<TMap extends object> = {
     [K in keyof TMap]: SheetContentComponent<TMap[K]>;
 };
-interface StacksheetSnapshot<TMap extends Record<string, unknown>> {
+interface StacksheetSnapshot<TMap extends object> {
     /** Current sheet stack, ordered bottom to top */
     stack: SheetItem<Extract<keyof TMap, string>>[];
     /** Whether any sheets are currently visible */
     isOpen: boolean;
 }
-interface SheetActions<TMap extends Record<string, unknown>> {
+interface SheetActions<TMap extends object> {
     /** Replace stack with a single item */
     open<K extends Extract<keyof TMap, string>>(type: K, id: string, data: TMap[K]): void;
     /** Replace stack with an ad-hoc component */
@@ -215,7 +224,7 @@ interface SheetActions<TMap extends Record<string, unknown>> {
     /** Clear entire stack */
     close(): void;
 }
-interface StacksheetProviderProps<TMap extends Record<string, unknown>> {
+interface StacksheetProviderProps<TMap extends object> {
     /** Map of sheet type keys to content components (optional — only needed for type registry pattern) */
     sheets?: ContentMap<TMap>;
     /** Your application content */
@@ -230,7 +239,7 @@ interface StacksheetProviderProps<TMap extends Record<string, unknown>> {
      */
     renderHeader?: false | ((props: HeaderRenderProps) => ReactNode);
 }
-interface StacksheetInstance<TMap extends Record<string, unknown>> {
+interface StacksheetInstance<TMap extends object> {
     /** Provider component — wrap your app, pass sheets map */
     StacksheetProvider: ComponentType<StacksheetProviderProps<TMap>>;
     /** Hook returning sheet actions */
@@ -241,19 +250,40 @@ interface StacksheetInstance<TMap extends Record<string, unknown>> {
     store: zustand.StoreApi<StacksheetSnapshot<TMap> & SheetActions<TMap>>;
 }
 
+/** Merge user-provided config with defaults. Resolves union types (side, spring) to concrete values. */
 declare function resolveConfig(config?: StacksheetConfig): ResolvedConfig;
 
 /**
  * Create an isolated sheet stack instance with typed store, hooks, and provider.
  *
+ * Works with both `interface` and `type` definitions:
+ *
  * ```ts
- * const { StacksheetProvider, useSheet, useStacksheetState } = createStacksheet<{
+ * // Using an interface
+ * interface SheetDataMap {
+ *   "bucket-create": { onCreated?: (b: Bucket) => void };
+ *   "bucket-edit": { bucket: Bucket };
+ * }
+ *
+ * // Using a type alias
+ * type SheetDataMap = {
  *   "bucket-create": { onCreated?: (b: Bucket) => void };
  *   "bucket-edit": { bucket: Bucket };
- * }>();
+ * };
+ *
+ * const { StacksheetProvider, useSheet, useStacksheetState } =
+ *   createStacksheet<SheetDataMap>();
  * ```
+ *
+ * Sheet content components receive their data as **spread props**:
+ * ```ts
+ * // Data map defines: "bucket-edit": { bucket: Bucket }
+ * // Component receives:  ({ bucket }: { bucket: Bucket }) => JSX.Element
+ * ```
+ *
+ * Use `useSheetPanel()` inside content components to access `close()` and `back()`.
  */
-declare function createStacksheet<TMap extends Record<string, unknown>>(config?: StacksheetConfig): StacksheetInstance<TMap>;
+declare function createStacksheet<TMap extends object>(config?: StacksheetConfig): StacksheetInstance<TMap>;
 
 /**
  * Returns true when viewport width is at or below the breakpoint.
@@ -344,6 +374,16 @@ interface SheetBackProps {
     children?: ReactNode;
 }
 declare function SheetBack({ asChild, className, style, children }: SheetBackProps): react_jsx_runtime.JSX.Element | null;
+/**
+ * Composable sheet parts for building custom panel layouts.
+ *
+ * Use with `renderHeader={false}` on the provider to opt into
+ * composable mode — no auto header or scroll wrapper, full control
+ * over the panel's structure.
+ *
+ * `Sheet.Title` and `Sheet.Description` are linked to the panel's
+ * `aria-labelledby` and `aria-describedby` via matching IDs.
+ */
 declare const Sheet: {
     readonly Handle: typeof SheetHandle;
     readonly Header: typeof SheetHeader;
@@ -378,4 +418,4 @@ declare function getSlideFrom(side: Side): SlideValues;
  */
 declare function getPanelStyles(side: Side, config: ResolvedConfig, _depth: number, index: number): CSSProperties;
 
-export { type ContentMap, type HeaderRenderProps, type ResolvedConfig, type ResponsiveSide, Sheet, type SheetActions, type SheetBackProps, type SheetBodyProps, type SheetCloseProps, type SheetContentComponent, type SheetDescriptionProps, type SheetFooterProps, type SheetHandleProps, type SheetHeaderProps, type SheetItem, type SheetPanelContextValue, type SheetTitleProps, type Side, type SideConfig, type SpringConfig, type SpringPreset, type StackingConfig, type StacksheetClassNames, type StacksheetConfig, type StacksheetInstance, type StacksheetProviderProps, type StacksheetSnapshot, createStacksheet, getPanelStyles, getSlideFrom, getStackTransform, resolveConfig, springs, useIsMobile, useResolvedSide, useSheetPanel };
+export { type CloseReason, type ContentMap, type HeaderRenderProps, type ResolvedConfig, type ResponsiveSide, Sheet, type SheetActions, type SheetBackProps, type SheetBodyProps, type SheetCloseProps, type SheetContentComponent, type SheetDescriptionProps, type SheetFooterProps, type SheetHandleProps, type SheetHeaderProps, type SheetItem, type SheetPanelContextValue, type SheetTitleProps, type Side, type SideConfig, type SnapPoint, type SpringConfig, type SpringPreset, type StackingConfig, type StacksheetClassNames, type StacksheetConfig, type StacksheetInstance, type StacksheetProviderProps, type StacksheetSnapshot, createStacksheet, getPanelStyles, getSlideFrom, getStackTransform, resolveConfig, springs, useIsMobile, useResolvedSide, useSheetPanel };