@howells/stacksheet 1.0.1 → 1.1.1

package/README.md

@@ -12,6 +12,7 @@ Peer dependencies: `react >= 18`, `react-dom >= 18`.
 
 ```tsx
 import { createStacksheet } from "@howells/stacksheet";
+import "@howells/stacksheet/styles.css";
 
 const { StacksheetProvider, useSheet } = createStacksheet();
 

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;
@@ -241,6 +250,7 @@ interface StacksheetInstance<TMap extends object> {
     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;
 
 /**
@@ -364,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;
@@ -398,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 };