@surdeddd/bottom-sheet 0.2.0 → 0.4.0

package/README.md

@@ -2,8 +2,8 @@
 
 > Universal, headless bottom-sheet engine. **One core, eight adapters, GPU-accelerated, fully tested.**
 
-![bundle](https://img.shields.io/badge/core-15.8%20KB%20gzip-1a1614?style=flat-square)
-![tests](https://img.shields.io/badge/tests-327%20unit-2ea44f?style=flat-square)
+![bundle](https://img.shields.io/badge/core-16.8%20KB%20gzip-1a1614?style=flat-square)
+![tests](https://img.shields.io/badge/tests-392%20unit-2ea44f?style=flat-square)
 ![ts](https://img.shields.io/badge/TypeScript-strict-3178c6?style=flat-square&logo=typescript&logoColor=white)
 ![license](https://img.shields.io/badge/license-MIT-dc3522?style=flat-square)
 
@@ -47,7 +47,7 @@ stacking — and the exact same engine behind every adapter.
 | WCAG 2.1 AA keyboard slider          | partial |         —         |     **✓**     |
 | Multi-sheet stacking                 |    —    |         —         |     **✓**     |
 | Sheet-manager registry (typed)       |    —    |         —         |     **✓**     |
-| Tests (unit + e2e)                   | partial |      partial      | **253 + 32**  |
+| Tests (unit + e2e)                   | partial |      partial      | **392 + 164**  |
 
 ## Install
 
@@ -170,7 +170,7 @@ Drop-in usage from a static HTML page. The IIFE bundle registers
   rel="stylesheet"
   href="https://unpkg.com/@surdeddd/bottom-sheet/dist/styles.css"
 />
-<script src="https://unpkg.com/@surdeddd/bottom-sheet/dist/element.iife.js"></script>
+<script src="https://unpkg.com/@surdeddd/bottom-sheet/dist/element.iife.global.js"></script>
 <bottom-sheet
   snap-points='[{"id":"min","size":96},{"id":"full","size":"85%"}]'
   initial="min"
@@ -217,23 +217,53 @@ type SnapPoint =
 
 ### Engine options
 
-| Option           | Default       | What it does                                       |
-| ---------------- | ------------- | -------------------------------------------------- |
-| `snapPoints`     | required      | Ordered list of `{ id, size }`                     |
-| `allowed`        | all ids       | Subset the sheet may settle on right now           |
-| `initial`        | first allowed | Snap id to start at                                |
-| `mode`           | `"bottom"`    | `bottom \| top \| left \| right`                   |
-| `animation`      | `"spring"`    | `spring \| tween`                                  |
-| `spring`         | snappy        | `{ stiffness, damping, mass }`                     |
-| `flickVelocity`  | `0.65 px/ms`  | Mobile flick threshold                             |
-| `dragThreshold`  | `18 px`       | Below this, drag snaps back                        |
-| `rubberBand`     | `true`        | iOS-style soft over-drag                           |
-| `backdropRange`  | `[0, 1]`      | Progress range over which backdrop fades           |
-| `focusTrap`      | `false`       | Trap Tab focus inside the sheet when open          |
-| `closeOnEscape`  | `true`        | Listen for Escape and close                        |
-| `closeOnBack`    | `false`       | Intercept Android back button (history.popstate)   |
-| `lockBodyScroll` | `true`        | iOS-safe body lock (`position: fixed`)             |
-| `inertSiblings`  | `false`       | Mark page siblings `inert` while open (full modal) |
+| Option           | Default       | What it does                                                           |
+| ---------------- | ------------- | ---------------------------------------------------------------------- |
+| `snapPoints`     | required      | Ordered list of `{ id, size }`                                         |
+| `allowed`        | all ids       | Subset the sheet may settle on right now                               |
+| `initial`        | first allowed | Snap id to start at                                                    |
+| `mode`           | `"bottom"`    | `bottom`, `top`, `left`, `right`                                       |
+| `animation`      | `"spring"`    | `spring`, `tween`, `ios-spring`, `material-bounce`, `linear`, `snappy` |
+| `spring`         | snappy        | `{ stiffness, damping, mass }`                                         |
+| `flickVelocity`  | `0.65 px/ms`  | Mobile flick threshold                                                 |
+| `dragThreshold`  | `18 px`       | Below this, drag snaps back                                            |
+| `rubberBand`     | `true`        | iOS-style soft over-drag                                               |
+| `backdropRange`  | `[0, 1]`      | Progress range over which backdrop fades                               |
+| `focusTrap`      | `false`       | Trap Tab focus inside the sheet when open                              |
+| `closeOnEscape`  | `true`        | Listen for Escape and close                                            |
+| `closeOnBack`    | `false`       | Intercept Android back button (history.popstate)                       |
+| `lockBodyScroll` | `true`        | iOS-safe body lock (`position: fixed`)                                 |
+| `stackEffect`    | `false`       | iOS card-stack: back sheets scale down per depth                       |
+| `inertSiblings`  | `false`       | Mark page siblings `inert` while open (full modal)                     |
+
+### Anchored elements, docked bars & scrim stages
+
+Pin UI around the sheet — it rides the motion on the compositor (zero JS per
+frame) and shows/hides per state with configurable animations:
+
+```ts
+engine.addAnchor({
+  element: closeBtn,
+  position: 'sheet-top-right', // rides the sheet edge; 9 screen positions too
+  showOn: ['half', 'full'],    // snap ids or a predicate
+  animation: 'pop',            // fade | scale | slide | pop | custom keyframes
+});
+
+engine.addAnchor({
+  element: tabBar,
+  position: 'dock-bottom',     // full-width bar; the sheet slides under it
+});
+
+engine.setScrimStages({
+  stages: [
+    { for: 'peek', element: teaser },
+    { forRange: [0.5, 1], element: expanded },
+  ],
+  animation: 'fade',
+});
+```
+
+[Full anchors & stages docs →](docs/anchors.md)
 
 ### Events
 

package/dist/{BottomSheetEngine-CIT9Htti.d.cts → BottomSheetEngine-BJrH7qY3.d.cts}

@@ -1,6 +1,6 @@
 import { T as TransformAxis } from './transform-jVfAikE9.cjs';
 
-type SnapPoint = number | `${number}%` | "fit" | "full" | (string & {});
+type SnapPoint = number | `${number}%` | "fit" | "content" | "full" | (string & {});
 type SnapPointDef<Id extends string = string> = {
     id: Id;
     size: SnapPoint;
@@ -43,9 +43,14 @@ type SheetEventMap = {
         cancel: () => void;
         previousId: string;
     };
+    "before-close": {
+        reason: "programmatic" | "backdrop" | "escape" | "back";
+        cancel: () => void;
+    };
     snap: {
         id: string;
         size: number;
+        progress: number;
     };
     progress: {
         value: number;
@@ -66,7 +71,12 @@ type SheetEventMap = {
     open: {
         id: string;
     };
+    opened: {
+        id: string;
+    };
+    closed: undefined;
 };
+type CloseReason = "programmatic" | "backdrop" | "escape" | "back";
 type EngineOptions = {
     element: HTMLElement;
     handle?: HTMLElement;
@@ -105,10 +115,18 @@ type EngineOptions = {
     closeOnBack?: boolean;
     routedTo?: string;
     inertSiblings?: boolean;
+    persistent?: boolean;
+    disableClose?: boolean;
+    disableDrag?: boolean;
+    closeOnRouteChange?: boolean;
+    radius?: string | number;
+    maxHeight?: string | number;
+    returnFocusTo?: HTMLElement | string | (() => HTMLElement | null);
     persistKey?: string;
     autoCollapseAfter?: number;
     linkedSheets?: BottomSheetEngineLike[];
     viewTransitions?: boolean;
+    stackEffect?: boolean;
 };
 
 type BottomSheetEngineLike = BottomSheetEngine;
@@ -127,6 +145,60 @@ type EngineState = {
     progress: number;
 };
 
+type AnchorAnimationPreset = "fade" | "scale" | "slide" | "pop" | "none";
+type AnchorAnimationSpec = AnchorAnimationPreset | {
+    preset?: AnchorAnimationPreset;
+    enter?: Keyframe[];
+    exit?: Keyframe[];
+    duration?: number;
+    easing?: string;
+    respectReducedMotion?: boolean;
+};
+type AnchorTransitionHandle = {
+    finished: Promise<void>;
+    cancel: () => void;
+};
+declare function runAnchorTransition(el: HTMLElement, spec: AnchorAnimationSpec | undefined, phase: "enter" | "exit"): AnchorTransitionHandle;
+
+type AnchorState = {
+    activeId: string;
+    size: number;
+    progress: number;
+};
+type AnchorPosition = ScrimOverlayPosition | "dock-bottom" | "dock-top";
+type AnchorOptions = {
+    element: HTMLElement;
+    position?: AnchorPosition;
+    inset?: string;
+    showOn?: string[] | ((state: AnchorState) => boolean);
+    fadeRange?: [number, number];
+    interactive?: boolean;
+    animation?: AnchorAnimationSpec;
+};
+type AnchorHandle = {
+    wrapper: HTMLElement;
+    detach: () => void;
+    syncZ: (z: number) => void;
+};
+
+type ScrimStageDef = {
+    id?: string;
+    for?: string | string[];
+    forRange?: [number, number];
+    element: HTMLElement;
+    position?: ScrimOverlayPosition;
+    inset?: string;
+    interactive?: boolean;
+    animation?: AnchorAnimationSpec;
+};
+type ScrimStagesOptions = {
+    stages: ScrimStageDef[];
+    position?: ScrimOverlayPosition;
+    inset?: string;
+    interactive?: boolean;
+    animation?: AnchorAnimationSpec;
+};
+
 type Listener<K extends keyof SheetEventMap> = (payload: SheetEventMap[K]) => void;
 declare class BottomSheetEngine {
     private id;
@@ -146,6 +218,11 @@ declare class BottomSheetEngine {
     private lifecycle;
     private closeOnBack;
     private routedTo;
+    private persistent;
+    private disableCloseFlag;
+    private disableDragFlag;
+    private closeOnRouteChange;
+    private maxHeightCap;
     private snapPointsRaw;
     private snaps;
     private activeId;
@@ -158,6 +235,7 @@ declare class BottomSheetEngine {
     private sizeWriteSentinel;
     private progressWriteSentinel;
     private isTopSheet;
+    private opening;
     private progressPayload;
     private dragContextBuf;
     private bus;
@@ -165,6 +243,12 @@ declare class BottomSheetEngine {
     private linkedSheets;
     private scrollCache;
     private teardowns;
+    private anchors;
+    private anchorHost;
+    private stackZ;
+    private detachScrimStages;
+    private stackEffectEnabled;
+    private stackEffectPrimed;
     private transformTemplate;
     constructor(opts: EngineOptions);
     get state(): EngineState;
@@ -181,7 +265,15 @@ declare class BottomSheetEngine {
         signal?: AbortSignal;
     }): Promise<void>;
     open(id?: string): Promise<void>;
-    close(): Promise<void>;
+    close(reason?: CloseReason): Promise<void>;
+    canDismiss(): boolean;
+    isTop(): boolean;
+    depth(): number;
+    expand(): Promise<void>;
+    collapse(): Promise<void>;
+    setRadius(r: string | number): void;
+    setMaxHeight(h: string | number): void;
+    private clampToMaxHeight;
     setAllowed(ids: string[], snap?: string): void;
     setBackdropRange(range: [number, number]): void;
     setScreenRange(range: [number, number]): void;
@@ -193,19 +285,28 @@ declare class BottomSheetEngine {
     setScrimTapToClose(enabled: boolean): void;
     setScrimEnabled(enabled: boolean): void;
     setScrimOverlay(opts: ScrimOverlayOptions): () => void;
+    addAnchor(opts: AnchorOptions): () => void;
+    setScrimStages(opts: ScrimStagesOptions | null): () => void;
     getScrimState(): {
         mode: "full" | "above-sheet" | "off";
         enabled: boolean;
     };
     setSnapPoints(points: EngineOptions["snapPoints"], allowed?: string[]): void;
+    recompute(): void;
+    private measureFitSize;
+    private installFitObserver;
     destroy(): void;
     private emit;
     private newCycle;
     private emitBeforeSnap;
+    private emitBeforeClose;
+    private applyAutoAriaLabelledBy;
     private recomputeSnaps;
     private getAllowedRange;
+    private allowedIdsBySize;
     private updateAriaSlider;
     private registerInStack;
+    private applyStackDepth;
     private attach;
     private attachFeatures;
     private settleAfterDrag;
@@ -213,7 +314,8 @@ declare class BottomSheetEngine {
     private applySize;
     private computeProgress;
     private handleOpen;
+    private resyncAfterResize;
     private handleClose;
 }
 
-export { BottomSheetEngine as B, type EngineState as E, type Plugin as P, type SnapPointDef as S, type TeardownScope as T, type SheetMode as a, type EngineOptions as b, type SnapPoint as c, type SheetEventMap as d, SCRIM_PRESETS as e, type ScrimOverlayOptions as f, type ScrimOverlayPosition as g, type ScrimPreset as h, type ScrimPresetConfig as i, type ScrimUpdate as j, type SnapId as k };
+export { type AnchorOptions as A, BottomSheetEngine as B, type CloseReason as C, type EngineState as E, type Plugin as P, type ScrimStagesOptions as S, type TeardownScope as T, type SnapPointDef as a, type SheetMode as b, type EngineOptions as c, type SnapPoint as d, type SheetEventMap as e, type ScrimOverlayPosition as f, type AnchorAnimationPreset as g, type AnchorAnimationSpec as h, type AnchorHandle as i, type AnchorPosition as j, type AnchorState as k, SCRIM_PRESETS as l, type ScrimOverlayOptions as m, type ScrimPreset as n, type ScrimPresetConfig as o, type ScrimStageDef as p, type ScrimUpdate as q, type SnapId as r, runAnchorTransition as s };

package/dist/{BottomSheetEngine-Df9MwBbm.d.ts → BottomSheetEngine-L05jGZvU.d.ts}

@@ -1,6 +1,6 @@
 import { T as TransformAxis } from './transform-jVfAikE9.js';
 
-type SnapPoint = number | `${number}%` | "fit" | "full" | (string & {});
+type SnapPoint = number | `${number}%` | "fit" | "content" | "full" | (string & {});
 type SnapPointDef<Id extends string = string> = {
     id: Id;
     size: SnapPoint;
@@ -43,9 +43,14 @@ type SheetEventMap = {
         cancel: () => void;
         previousId: string;
     };
+    "before-close": {
+        reason: "programmatic" | "backdrop" | "escape" | "back";
+        cancel: () => void;
+    };
     snap: {
         id: string;
         size: number;
+        progress: number;
     };
     progress: {
         value: number;
@@ -66,7 +71,12 @@ type SheetEventMap = {
     open: {
         id: string;
     };
+    opened: {
+        id: string;
+    };
+    closed: undefined;
 };
+type CloseReason = "programmatic" | "backdrop" | "escape" | "back";
 type EngineOptions = {
     element: HTMLElement;
     handle?: HTMLElement;
@@ -105,10 +115,18 @@ type EngineOptions = {
     closeOnBack?: boolean;
     routedTo?: string;
     inertSiblings?: boolean;
+    persistent?: boolean;
+    disableClose?: boolean;
+    disableDrag?: boolean;
+    closeOnRouteChange?: boolean;
+    radius?: string | number;
+    maxHeight?: string | number;
+    returnFocusTo?: HTMLElement | string | (() => HTMLElement | null);
     persistKey?: string;
     autoCollapseAfter?: number;
     linkedSheets?: BottomSheetEngineLike[];
     viewTransitions?: boolean;
+    stackEffect?: boolean;
 };
 
 type BottomSheetEngineLike = BottomSheetEngine;
@@ -127,6 +145,60 @@ type EngineState = {
     progress: number;
 };
 
+type AnchorAnimationPreset = "fade" | "scale" | "slide" | "pop" | "none";
+type AnchorAnimationSpec = AnchorAnimationPreset | {
+    preset?: AnchorAnimationPreset;
+    enter?: Keyframe[];
+    exit?: Keyframe[];
+    duration?: number;
+    easing?: string;
+    respectReducedMotion?: boolean;
+};
+type AnchorTransitionHandle = {
+    finished: Promise<void>;
+    cancel: () => void;
+};
+declare function runAnchorTransition(el: HTMLElement, spec: AnchorAnimationSpec | undefined, phase: "enter" | "exit"): AnchorTransitionHandle;
+
+type AnchorState = {
+    activeId: string;
+    size: number;
+    progress: number;
+};
+type AnchorPosition = ScrimOverlayPosition | "dock-bottom" | "dock-top";
+type AnchorOptions = {
+    element: HTMLElement;
+    position?: AnchorPosition;
+    inset?: string;
+    showOn?: string[] | ((state: AnchorState) => boolean);
+    fadeRange?: [number, number];
+    interactive?: boolean;
+    animation?: AnchorAnimationSpec;
+};
+type AnchorHandle = {
+    wrapper: HTMLElement;
+    detach: () => void;
+    syncZ: (z: number) => void;
+};
+
+type ScrimStageDef = {
+    id?: string;
+    for?: string | string[];
+    forRange?: [number, number];
+    element: HTMLElement;
+    position?: ScrimOverlayPosition;
+    inset?: string;
+    interactive?: boolean;
+    animation?: AnchorAnimationSpec;
+};
+type ScrimStagesOptions = {
+    stages: ScrimStageDef[];
+    position?: ScrimOverlayPosition;
+    inset?: string;
+    interactive?: boolean;
+    animation?: AnchorAnimationSpec;
+};
+
 type Listener<K extends keyof SheetEventMap> = (payload: SheetEventMap[K]) => void;
 declare class BottomSheetEngine {
     private id;
@@ -146,6 +218,11 @@ declare class BottomSheetEngine {
     private lifecycle;
     private closeOnBack;
     private routedTo;
+    private persistent;
+    private disableCloseFlag;
+    private disableDragFlag;
+    private closeOnRouteChange;
+    private maxHeightCap;
     private snapPointsRaw;
     private snaps;
     private activeId;
@@ -158,6 +235,7 @@ declare class BottomSheetEngine {
     private sizeWriteSentinel;
     private progressWriteSentinel;
     private isTopSheet;
+    private opening;
     private progressPayload;
     private dragContextBuf;
     private bus;
@@ -165,6 +243,12 @@ declare class BottomSheetEngine {
     private linkedSheets;
     private scrollCache;
     private teardowns;
+    private anchors;
+    private anchorHost;
+    private stackZ;
+    private detachScrimStages;
+    private stackEffectEnabled;
+    private stackEffectPrimed;
     private transformTemplate;
     constructor(opts: EngineOptions);
     get state(): EngineState;
@@ -181,7 +265,15 @@ declare class BottomSheetEngine {
         signal?: AbortSignal;
     }): Promise<void>;
     open(id?: string): Promise<void>;
-    close(): Promise<void>;
+    close(reason?: CloseReason): Promise<void>;
+    canDismiss(): boolean;
+    isTop(): boolean;
+    depth(): number;
+    expand(): Promise<void>;
+    collapse(): Promise<void>;
+    setRadius(r: string | number): void;
+    setMaxHeight(h: string | number): void;
+    private clampToMaxHeight;
     setAllowed(ids: string[], snap?: string): void;
     setBackdropRange(range: [number, number]): void;
     setScreenRange(range: [number, number]): void;
@@ -193,19 +285,28 @@ declare class BottomSheetEngine {
     setScrimTapToClose(enabled: boolean): void;
     setScrimEnabled(enabled: boolean): void;
     setScrimOverlay(opts: ScrimOverlayOptions): () => void;
+    addAnchor(opts: AnchorOptions): () => void;
+    setScrimStages(opts: ScrimStagesOptions | null): () => void;
     getScrimState(): {
         mode: "full" | "above-sheet" | "off";
         enabled: boolean;
     };
     setSnapPoints(points: EngineOptions["snapPoints"], allowed?: string[]): void;
+    recompute(): void;
+    private measureFitSize;
+    private installFitObserver;
     destroy(): void;
     private emit;
     private newCycle;
     private emitBeforeSnap;
+    private emitBeforeClose;
+    private applyAutoAriaLabelledBy;
     private recomputeSnaps;
     private getAllowedRange;
+    private allowedIdsBySize;
     private updateAriaSlider;
     private registerInStack;
+    private applyStackDepth;
     private attach;
     private attachFeatures;
     private settleAfterDrag;
@@ -213,7 +314,8 @@ declare class BottomSheetEngine {
     private applySize;
     private computeProgress;
     private handleOpen;
+    private resyncAfterResize;
     private handleClose;
 }
 
-export { BottomSheetEngine as B, type EngineState as E, type Plugin as P, type SnapPointDef as S, type TeardownScope as T, type SheetMode as a, type EngineOptions as b, type SnapPoint as c, type SheetEventMap as d, SCRIM_PRESETS as e, type ScrimOverlayOptions as f, type ScrimOverlayPosition as g, type ScrimPreset as h, type ScrimPresetConfig as i, type ScrimUpdate as j, type SnapId as k };
+export { type AnchorOptions as A, BottomSheetEngine as B, type CloseReason as C, type EngineState as E, type Plugin as P, type ScrimStagesOptions as S, type TeardownScope as T, type SnapPointDef as a, type SheetMode as b, type EngineOptions as c, type SnapPoint as d, type SheetEventMap as e, type ScrimOverlayPosition as f, type AnchorAnimationPreset as g, type AnchorAnimationSpec as h, type AnchorHandle as i, type AnchorPosition as j, type AnchorState as k, SCRIM_PRESETS as l, type ScrimOverlayOptions as m, type ScrimPreset as n, type ScrimPresetConfig as o, type ScrimStageDef as p, type ScrimUpdate as q, type SnapId as r, runAnchorTransition as s };