@howells/stacksheet 0.1.0 → 1.0.0

package/README.md

@@ -0,0 +1,61 @@
+# Stacksheet
+
+A typed, animated sheet stack for React. Powered by Zustand and Motion.
+
+```
+npm install @howells/stacksheet
+```
+
+Peer dependencies: `react >= 18`, `react-dom >= 18`.
+
+## Quick start
+
+```tsx
+import { createStacksheet } from "@howells/stacksheet";
+
+const { StacksheetProvider, useSheet } = createStacksheet();
+
+function UserProfile({ userId }: { userId: string }) {
+  const { close } = useSheet();
+  return (
+    <div>
+      <h2>User {userId}</h2>
+      <button onClick={close}>Done</button>
+    </div>
+  );
+}
+
+function App() {
+  return (
+    <StacksheetProvider>
+      <YourApp />
+    </StacksheetProvider>
+  );
+}
+```
+
+Open a sheet from any component:
+
+```tsx
+const { open } = useSheet();
+open(UserProfile, { userId: "u_abc" });
+```
+
+No registration, no type map, no config. The sheet slides in from the right on desktop, bottom on mobile, with focus trapping, scroll lock, drag-to-dismiss, and keyboard navigation built in.
+
+## Documentation
+
+Full docs, interactive playground, and API reference:
+
+**[stacksheet.danielhowells.com](https://stacksheet.danielhowells.com)**
+
+- [Getting Started](https://stacksheet.danielhowells.com/docs)
+- [Configuration](https://stacksheet.danielhowells.com/docs/config)
+- [Composable Parts](https://stacksheet.danielhowells.com/docs/composable-parts)
+- [Drag to Dismiss](https://stacksheet.danielhowells.com/docs/drag-to-dismiss)
+- [Styling](https://stacksheet.danielhowells.com/docs/styling)
+- [Type Registry](https://stacksheet.danielhowells.com/docs/type-registry)
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -1,6 +1,381 @@
-export { createSheetStack } from "./create.js";
-export { resolveConfig } from "./config.js";
-export { getStackTransform, getSlideFrom, getPanelStyles } from "./stacking.js";
-export { useIsMobile, useResolvedSide } from "./media.js";
-export type { SheetItem, Side, ResponsiveSide, SideConfig, StackingConfig, SpringConfig, SheetStackConfig, ResolvedConfig, SheetContentComponent, ContentMap, SheetSnapshot, SheetActions, SheetStackInstance, } from "./types.js";
-//# sourceMappingURL=index.d.ts.map
+import * as zustand from 'zustand';
+import { ComponentType, ReactNode, CSSProperties } from 'react';
+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;
+        readonly mass: 0.8;
+    };
+    readonly stiff: {
+        readonly stiffness: 400;
+        readonly damping: 40;
+        readonly mass: 1;
+    };
+};
+type SpringPreset = keyof typeof springs;
+
+interface StacksheetClassNames {
+    /** Applied to backdrop overlay */
+    backdrop?: string;
+    /** Applied to each panel container */
+    panel?: string;
+    /** Applied to the header bar */
+    header?: string;
+}
+interface HeaderRenderProps {
+    /** `true` when the stack has more than one sheet */
+    isNested: boolean;
+    /** Pop the top sheet (go back one level) */
+    onBack: () => void;
+    /** Close the entire sheet stack */
+    onClose: () => void;
+    /** Current resolved side (left/right/bottom) */
+    side: Side;
+}
+interface SheetItem<TType extends string = string> {
+    /** Unique identifier for this sheet instance */
+    id: string;
+    /** Sheet type key from the TMap */
+    type: TType;
+    /** Data payload passed when opening the sheet */
+    data: Record<string, unknown>;
+}
+type Side = "left" | "right" | "bottom";
+interface ResponsiveSide {
+    desktop: Side;
+    mobile: Side;
+}
+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) */
+    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) */
+    renderThreshold: number;
+}
+interface SpringConfig {
+    /** Damping — higher = less oscillation (default: 30) */
+    damping: number;
+    /** Stiffness — higher = snappier (default: 170) */
+    stiffness: number;
+    /** Mass — higher = more momentum (default: 0.8) */
+    mass: number;
+}
+interface StacksheetConfig {
+    /** Maximum stack depth. Default: Infinity (unlimited) */
+    maxDepth?: number;
+    /** Close on ESC key. Default: true */
+    closeOnEscape?: boolean;
+    /** Close on backdrop click. Default: true */
+    closeOnBackdrop?: boolean;
+    /** Show backdrop overlay when open. Default: true */
+    showOverlay?: boolean;
+    /** Lock body scroll when open. Default: true */
+    lockScroll?: boolean;
+    /** Panel width in px. Default: 420 */
+    width?: number;
+    /** Maximum panel width as CSS value. Default: "90vw" */
+    maxWidth?: string;
+    /** Mobile breakpoint in px. Default: 768 */
+    breakpoint?: number;
+    /** Sheet slide-from side. Default: { desktop: "right", mobile: "bottom" } */
+    side?: SideConfig;
+    /** Stacking visual parameters */
+    stacking?: Partial<StackingConfig>;
+    /** Spring animation parameters — preset name or custom config */
+    spring?: SpringPreset | Partial<SpringConfig>;
+    /** Base z-index. Default: 100 */
+    zIndex?: number;
+    /** Default aria-label for dialog panels. Default: "Sheet dialog" */
+    ariaLabel?: string;
+    /** 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;
+    /** Enable drag-to-dismiss. Default: true */
+    drag?: boolean;
+    /** Fraction of panel dimension to trigger close (0-1). Default: 0.25 */
+    closeThreshold?: number;
+    /** Velocity threshold (px/ms) to trigger close. Default: 0.5 */
+    velocityThreshold?: number;
+    /** Allow any form of dismissal (drag, backdrop, escape). Default: true */
+    dismissible?: boolean;
+    /** Modal mode — overlay + scroll lock + focus trap. Default: true */
+    modal?: boolean;
+    /** Scale down [data-stacksheet-wrapper] when sheets open. Default: false */
+    shouldScaleBackground?: boolean;
+    /** Scale factor applied to background (0-1). Default: 0.97 */
+    scaleBackgroundAmount?: number;
+}
+/** Fully resolved config — all fields required */
+interface ResolvedConfig {
+    maxDepth: number;
+    closeOnEscape: boolean;
+    closeOnBackdrop: boolean;
+    showOverlay: boolean;
+    lockScroll: boolean;
+    width: number;
+    maxWidth: string;
+    breakpoint: number;
+    side: ResponsiveSide;
+    stacking: StackingConfig;
+    spring: SpringConfig;
+    zIndex: number;
+    ariaLabel: string;
+    onOpenComplete?: () => void;
+    onCloseComplete?: () => void;
+    drag: boolean;
+    closeThreshold: number;
+    velocityThreshold: number;
+    dismissible: boolean;
+    modal: boolean;
+    shouldScaleBackground: boolean;
+    scaleBackgroundAmount: number;
+}
+/** 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>> = {
+    [K in keyof TMap]: SheetContentComponent<TMap[K]>;
+};
+interface StacksheetSnapshot<TMap extends Record<string, unknown>> {
+    /** 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>> {
+    /** 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 */
+    open<TData extends Record<string, unknown>>(component: ComponentType<TData>, data: TData): void;
+    /** Replace stack with an ad-hoc component (explicit id) */
+    open<TData extends Record<string, unknown>>(component: ComponentType<TData>, id: string, data: TData): void;
+    /** Push onto stack (replaces top at maxDepth) */
+    push<K extends Extract<keyof TMap, string>>(type: K, id: string, data: TMap[K]): void;
+    /** Push an ad-hoc component onto the stack */
+    push<TData extends Record<string, unknown>>(component: ComponentType<TData>, data: TData): void;
+    /** Push an ad-hoc component onto the stack (explicit id) */
+    push<TData extends Record<string, unknown>>(component: ComponentType<TData>, id: string, data: TData): void;
+    /** Swap the top item */
+    replace<K extends Extract<keyof TMap, string>>(type: K, id: string, data: TMap[K]): void;
+    /** Swap the top item with an ad-hoc component */
+    replace<TData extends Record<string, unknown>>(component: ComponentType<TData>, data: TData): void;
+    /** Swap the top item with an ad-hoc component (explicit id) */
+    replace<TData extends Record<string, unknown>>(component: ComponentType<TData>, id: string, data: TData): void;
+    /** Swap the top item's content in place (no animation) */
+    swap<K extends Extract<keyof TMap, string>>(type: K, data: TMap[K]): void;
+    /** Swap the top item's content with an ad-hoc component (no animation) */
+    swap<TData extends Record<string, unknown>>(component: ComponentType<TData>, data: TData): void;
+    /** Smart: empty→open, same type on top→replace, different→push */
+    navigate<K extends Extract<keyof TMap, string>>(type: K, id: string, data: TMap[K]): void;
+    /** Smart navigate with an ad-hoc component */
+    navigate<TData extends Record<string, unknown>>(component: ComponentType<TData>, data: TData): void;
+    /** Smart navigate with an ad-hoc component (explicit id) */
+    navigate<TData extends Record<string, unknown>>(component: ComponentType<TData>, id: string, data: TData): void;
+    /** Update data on a sheet by id (no animation) */
+    setData<K extends Extract<keyof TMap, string>>(type: K, id: string, data: TMap[K]): void;
+    /** Update data on an ad-hoc sheet by id */
+    setData<TData extends Record<string, unknown>>(component: ComponentType<TData>, id: string, data: TData): void;
+    /** Remove a specific sheet by id; close if last */
+    remove(id: string): void;
+    /** Pop top item; close if last */
+    pop(): void;
+    /** Clear entire stack */
+    close(): void;
+}
+interface StacksheetProviderProps<TMap extends Record<string, unknown>> {
+    /** Map of sheet type keys to content components (optional — only needed for type registry pattern) */
+    sheets?: ContentMap<TMap>;
+    /** Your application content */
+    children: ReactNode;
+    /** CSS class overrides for backdrop, panel, and header */
+    classNames?: StacksheetClassNames;
+    /**
+     * Controls the panel header rendering mode.
+     * - `undefined` — renders the default close/back header (classic mode)
+     * - `function` — custom header renderer (classic mode with custom header)
+     * - `false` — no auto header, no auto scroll wrapper (composable mode — use Sheet.* parts)
+     */
+    renderHeader?: false | ((props: HeaderRenderProps) => ReactNode);
+}
+interface StacksheetInstance<TMap extends Record<string, unknown>> {
+    /** Provider component — wrap your app, pass sheets map */
+    StacksheetProvider: ComponentType<StacksheetProviderProps<TMap>>;
+    /** Hook returning sheet actions */
+    useSheet: () => SheetActions<TMap>;
+    /** Hook returning sheet state (stack, isOpen) */
+    useStacksheetState: () => StacksheetSnapshot<TMap>;
+    /** Raw Zustand store for advanced use */
+    store: zustand.StoreApi<StacksheetSnapshot<TMap> & SheetActions<TMap>>;
+}
+
+declare function resolveConfig(config?: StacksheetConfig): ResolvedConfig;
+
+/**
+ * Create an isolated sheet stack instance with typed store, hooks, and provider.
+ *
+ * ```ts
+ * const { StacksheetProvider, useSheet, useStacksheetState } = createStacksheet<{
+ *   "bucket-create": { onCreated?: (b: Bucket) => void };
+ *   "bucket-edit": { bucket: Bucket };
+ * }>();
+ * ```
+ */
+declare function createStacksheet<TMap extends Record<string, unknown>>(config?: StacksheetConfig): StacksheetInstance<TMap>;
+
+/**
+ * Returns true when viewport width is at or below the breakpoint.
+ * SSR-safe: defaults to false (desktop).
+ */
+declare function useIsMobile(breakpoint: number): boolean;
+/** Resolve the current side from config + viewport. */
+declare function useResolvedSide(config: ResolvedConfig): Side;
+
+interface SheetPanelContextValue {
+    /** Close the entire sheet stack */
+    close: () => void;
+    /** Pop the top sheet (go back one level) */
+    back: () => void;
+    /** Whether the stack has more than one sheet */
+    isNested: boolean;
+    /** Whether this is the top (active) sheet */
+    isTop: boolean;
+    /** Unique ID prefix for this panel (for aria-labelledby linking) */
+    panelId: string;
+    /** Current resolved side (left/right/bottom) */
+    side: Side;
+}
+/**
+ * Access the current sheet panel's context.
+ * Must be called inside a component rendered by the sheet stack.
+ */
+declare function useSheetPanel(): SheetPanelContextValue;
+
+interface SheetHandleProps {
+    /** Render as child element, merging props */
+    asChild?: boolean;
+    className?: string;
+    style?: CSSProperties;
+    /** Custom handle content. Defaults to a centered grab bar. */
+    children?: ReactNode;
+}
+declare function SheetHandle({ asChild, className, style, children, }: SheetHandleProps): react_jsx_runtime.JSX.Element;
+interface SheetHeaderProps {
+    asChild?: boolean;
+    className?: string;
+    style?: CSSProperties;
+    children: ReactNode;
+}
+declare function SheetHeader({ asChild, className, style, children, }: SheetHeaderProps): react_jsx_runtime.JSX.Element;
+interface SheetTitleProps {
+    asChild?: boolean;
+    className?: string;
+    style?: CSSProperties;
+    children: ReactNode;
+}
+declare function SheetTitle({ asChild, className, style, children }: SheetTitleProps): react_jsx_runtime.JSX.Element;
+interface SheetDescriptionProps {
+    asChild?: boolean;
+    className?: string;
+    style?: CSSProperties;
+    children: ReactNode;
+}
+declare function SheetDescription({ asChild, className, style, children, }: SheetDescriptionProps): react_jsx_runtime.JSX.Element;
+interface SheetBodyProps {
+    /** When true, renders child element directly instead of ScrollArea */
+    asChild?: boolean;
+    className?: string;
+    style?: CSSProperties;
+    children: ReactNode;
+}
+declare function SheetBody({ asChild, className, style, children }: SheetBodyProps): react_jsx_runtime.JSX.Element;
+interface SheetFooterProps {
+    asChild?: boolean;
+    className?: string;
+    style?: CSSProperties;
+    children: ReactNode;
+}
+declare function SheetFooter({ asChild, className, style, children, }: SheetFooterProps): react_jsx_runtime.JSX.Element;
+interface SheetCloseProps {
+    asChild?: boolean;
+    className?: string;
+    style?: CSSProperties;
+    /** Custom content. Defaults to an X icon. */
+    children?: ReactNode;
+}
+declare function SheetClose({ asChild, className, style, children }: SheetCloseProps): react_jsx_runtime.JSX.Element;
+interface SheetBackProps {
+    asChild?: boolean;
+    className?: string;
+    style?: CSSProperties;
+    /** Custom content. Defaults to an arrow-left icon. */
+    children?: ReactNode;
+}
+declare function SheetBack({ asChild, className, style, children }: SheetBackProps): react_jsx_runtime.JSX.Element | null;
+declare const Sheet: {
+    readonly Handle: typeof SheetHandle;
+    readonly Header: typeof SheetHeader;
+    readonly Title: typeof SheetTitle;
+    readonly Description: typeof SheetDescription;
+    readonly Body: typeof SheetBody;
+    readonly Footer: typeof SheetFooter;
+    readonly Close: typeof SheetClose;
+    readonly Back: typeof SheetBack;
+};
+
+interface StackTransform {
+    scale: number;
+    offset: number;
+    opacity: number;
+    borderRadius: number;
+}
+/**
+ * Compute visual transforms for a panel at a given depth.
+ * depth=0 is the top (foreground) panel.
+ * Panels beyond renderThreshold are clamped to the edge position and faded out.
+ */
+declare function getStackTransform(depth: number, stacking: StackingConfig): StackTransform;
+interface SlideValues {
+    x?: string | number;
+    y?: string | number;
+}
+/** Motion initial/exit values for sliding from the given side. */
+declare function getSlideFrom(side: Side): SlideValues;
+/**
+ * Fixed-position styles for a panel, accounting for side, width, and depth.
+ */
+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 };