@sigmela/router 0.4.0 → 0.5.0

package/CHANGELOG.md

@@ -4,6 +4,21 @@ All notable changes to this package are documented here. The format follows
 [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and the project uses
 [semantic versioning](https://semver.org/).
 
+## 0.5.0
+
+### Added
+
+- `Sheet` accepts `presentation="fullscreen"`, turning a bottom sheet into a
+  full-height surface (header switches to the modal shape, dismissal measures
+  the viewport). Sheets stay content-sized by default.
+
+- Public exports for the overlay surface: `Sheet`, `SheetFrame`,
+  `useModalSwipeTarget`, `useSheetDragEngine`, `sheetDragStartsInInteractiveControl`,
+  `sheetScrollAtTop` and `SheetDragUpdate`. Previously only `Modal`/`ModalFrame`
+  were reachable, so apps could route to a sheet but not build its body.
+- `example/`: a Vite sandbox covering stacks, overlays, tab bar, drawer,
+  split view and guards (`npm run example`).
+
 ## 0.1.0
 
 First standalone release, extracted from the Sigmela merchant web app.

package/README.md

@@ -42,15 +42,24 @@ Styles ship with the bundle: `dist/index.js` imports `router.css`, so bundlers
 that handle CSS from dependencies (Vite, webpack, Next, Parcel) pick it up
 automatically — no extra import needed.
 
-Environments without a CSS loader — plain Node, `vitest` with the `node`
-environment, some SSR pipelines — cannot resolve that import. Alias or stub
-`@sigmela/router/router.css` there, and load the stylesheet explicitly on the
-client:
+Environments without a CSS loader — plain Node, some SSR pipelines — cannot
+resolve that import. Load the stylesheet explicitly there:
 
 ```ts
 import '@sigmela/router/router.css';
 ```
 
+For Vitest with the `node` environment, inline the package so Vite handles the
+CSS import instead of Node:
+
+```ts
+// vitest.config.ts
+test: {
+  environment: 'node',
+  server: { deps: { inline: [/@sigmela\/router/] } },
+}
+```
+
 ## Route primitives
 
 | Element | Purpose |
@@ -60,7 +69,7 @@ import '@sigmela/router/router.css';
 | `Router.Redirect` | Declarative redirect |
 | `Router.Modal` | Full-cover or content-sized overlay above the current screen |
 | `Router.Sheet` | Bottom sheet, content-sized or fullscreen |
-| `Router.TabBar` / `Router.TabBarItem` | Tab navigation with per-tab stacks |
+| `Router.TabBar` / `Router.TabBarItem` | Tab navigation; selecting a tab routes to its root path |
 | `Router.Drawer` / `Router.DrawerGroup` / `Router.DrawerSection` / `Router.DrawerItem` | Persistent side navigation |
 | `Router.SplitView` | Primary/secondary panes above a width breakpoint |
 | `Router.Protected` | Guarded subtree with a redirect target |
@@ -150,6 +159,23 @@ The router owns navigation, overlay surfaces and their gestures. It never
 imports application features, i18n, data layers or design-system components —
 screens and layouts are supplied by the host app as JSX.
 
+## Sandbox
+
+`example/` is a Vite playground that exercises every primitive against the
+router source, with hot reload:
+
+```bash
+npm install
+npm run example        # http://localhost:5180
+```
+
+It has three shells you can switch between: **Stack & overlays** (pushes,
+params, search params, fullscreen and content-sized modals, a sheet, and a
+modal owning its own three-step stack), **Tab bar** (per-tab routes, history
+state), and **Drawer & split** (drawer groups and sections, a split view, and a
+guarded route). `example/src/theme.css` shows the `--router-*` tokens driving
+the whole look.
+
 ## Development
 
 ```bash
@@ -158,6 +184,7 @@ npm run typecheck
 npm test          # 58 contract tests
 npm run lint
 npm run build     # dist/index.js + dist/router.css + type declarations
+npm run example   # Vite sandbox on the source
 ```
 
 `ROUTER_CONTRACT.md` documents the invariants the contract tests protect.

package/dist/components/Sheet.d.ts

@@ -1,11 +1,14 @@
 import { type CSSProperties, type ReactNode } from 'react';
 import type { RouterShellMode } from '../types';
 type SheetVariant = 'attached' | 'detached';
+type SheetPresentation = 'content' | 'fullscreen';
 interface SheetProps {
     children: ReactNode;
     disableDismiss?: boolean;
     onRequestClose?: () => void;
     variant?: SheetVariant;
+    /** 'fullscreen' turns the sheet into a full-height surface. */
+    presentation?: SheetPresentation;
 }
 interface SheetFrameProps {
     children: ReactNode;
@@ -17,7 +20,7 @@ interface SheetFrameProps {
     activeContentKey?: string;
 }
 export declare function SheetFrame({ children, open, onRequestClose, onExitComplete, zIndex, shell, activeContentKey, }: SheetFrameProps): import("react/jsx-runtime").JSX.Element;
-declare function SheetRoot({ children, disableDismiss, onRequestClose, variant, }: SheetProps): import("react/jsx-runtime").JSX.Element;
+declare function SheetRoot({ children, disableDismiss, onRequestClose, variant, presentation, }: SheetProps): import("react/jsx-runtime").JSX.Element;
 interface SheetHeaderProps {
     title?: string;
     leftAction?: ReactNode;

package/dist/components/Sheet.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Sheet.d.ts","sourceRoot":"","sources":["../../src/components/Sheet.tsx"],"names":[],"mappings":"AAAA,OAAO,EAOL,KAAK,aAAa,EAClB,KAAK,SAAS,EACf,MAAM,OAAO,CAAC;AAOf,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,UAAU,CAAC;AAEhD,KAAK,YAAY,GAAG,UAAU,GAAG,UAAU,CAAC;AA0B5C,UAAU,UAAU;IAClB,QAAQ,EAAE,SAAS,CAAC;IACpB,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,cAAc,CAAC,EAAE,MAAM,IAAI,CAAC;IAC5B,OAAO,CAAC,EAAE,YAAY,CAAC;CACxB;AAOD,UAAU,eAAe;IACvB,QAAQ,EAAE,SAAS,CAAC;IACpB,IAAI,EAAE,OAAO,CAAC;IACd,cAAc,EAAE,MAAM,IAAI,CAAC;IAC3B,cAAc,EAAE,MAAM,IAAI,CAAC;IAC3B,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,CAAC,EAAE,eAAe,CAAC;IACxB,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC3B;AAED,wBAAgB,UAAU,CAAC,EACzB,QAAQ,EACR,IAAI,EACJ,cAAc,EACd,cAAc,EACd,MAAM,EACN,KAA0B,EAC1B,gBAA8C,GAC/C,EAAE,eAAe,2CAkJjB;AAED,iBAAS,SAAS,CAAC,EACjB,QAAQ,EACR,cAAc,EACd,cAAc,EACd,OAAoB,GACrB,EAAE,UAAU,2CAUZ;AAED,UAAU,gBAAgB;IACxB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,UAAU,CAAC,EAAE,SAAS,CAAC;IACvB,WAAW,CAAC,EAAE,SAAS,CAAC;IACxB,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,KAAK,CAAC,EAAE,OAAO,GAAG,QAAQ,CAAC;CAC5B;AAED,iBAAS,WAAW,CAAC,EACnB,KAAK,EACL,UAAU,EACV,WAAW,EACX,eAAe,EACf,MAAa,EACb,KAAe,GAChB,EAAE,gBAAgB,2CAuBlB;AAED,UAAU,iBAAiB;IACzB,QAAQ,EAAE,SAAS,CAAC;IACpB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,iBAAS,YAAY,CAAC,EAAE,QAAQ,EAAE,SAAS,EAAE,EAAE,iBAAiB,2CAE/D;AAED,UAAU,oBAAoB;IAC5B,QAAQ,EAAE,SAAS,CAAC;IACpB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,KAAK,CAAC,EAAE,aAAa,CAAC;CACvB;AAED,iBAAS,eAAe,CAAC,EAAE,QAAQ,EAAE,SAAS,EAAE,KAAK,EAAE,EAAE,oBAAoB,2CAgB5E;AAED,UAAU,gBAAgB;IACxB,QAAQ,EAAE,SAAS,CAAC;IACpB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,iBAAS,WAAW,CAAC,EAAE,QAAQ,EAAE,SAAS,EAAE,EAAE,gBAAgB,2CAa7D;AAED,eAAO,MAAM,KAAK;;;;;CAKhB,CAAC"}
+{"version":3,"file":"Sheet.d.ts","sourceRoot":"","sources":["../../src/components/Sheet.tsx"],"names":[],"mappings":"AAAA,OAAO,EAOL,KAAK,aAAa,EAClB,KAAK,SAAS,EACf,MAAM,OAAO,CAAC;AAOf,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,UAAU,CAAC;AAEhD,KAAK,YAAY,GAAG,UAAU,GAAG,UAAU,CAAC;AAC5C,KAAK,iBAAiB,GAAG,SAAS,GAAG,YAAY,CAAC;AA4BlD,UAAU,UAAU;IAClB,QAAQ,EAAE,SAAS,CAAC;IACpB,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,cAAc,CAAC,EAAE,MAAM,IAAI,CAAC;IAC5B,OAAO,CAAC,EAAE,YAAY,CAAC;IACvB,+DAA+D;IAC/D,YAAY,CAAC,EAAE,iBAAiB,CAAC;CAClC;AAOD,UAAU,eAAe;IACvB,QAAQ,EAAE,SAAS,CAAC;IACpB,IAAI,EAAE,OAAO,CAAC;IACd,cAAc,EAAE,MAAM,IAAI,CAAC;IAC3B,cAAc,EAAE,MAAM,IAAI,CAAC;IAC3B,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,CAAC,EAAE,eAAe,CAAC;IACxB,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC3B;AAED,wBAAgB,UAAU,CAAC,EACzB,QAAQ,EACR,IAAI,EACJ,cAAc,EACd,cAAc,EACd,MAAM,EACN,KAA0B,EAC1B,gBAA8C,GAC/C,EAAE,eAAe,2CA+KjB;AAED,iBAAS,SAAS,CAAC,EACjB,QAAQ,EACR,cAAc,EACd,cAAc,EACd,OAAoB,EACpB,YAAwB,GACzB,EAAE,UAAU,2CAsBZ;AAED,UAAU,gBAAgB;IACxB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,UAAU,CAAC,EAAE,SAAS,CAAC;IACvB,WAAW,CAAC,EAAE,SAAS,CAAC;IACxB,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,KAAK,CAAC,EAAE,OAAO,GAAG,QAAQ,CAAC;CAC5B;AAED,iBAAS,WAAW,CAAC,EACnB,KAAK,EACL,UAAU,EACV,WAAW,EACX,eAAe,EACf,MAAa,EACb,KAAe,GAChB,EAAE,gBAAgB,2CA2BlB;AAED,UAAU,iBAAiB;IACzB,QAAQ,EAAE,SAAS,CAAC;IACpB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,iBAAS,YAAY,CAAC,EAAE,QAAQ,EAAE,SAAS,EAAE,EAAE,iBAAiB,2CAE/D;AAED,UAAU,oBAAoB;IAC5B,QAAQ,EAAE,SAAS,CAAC;IACpB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,KAAK,CAAC,EAAE,aAAa,CAAC;CACvB;AAED,iBAAS,eAAe,CAAC,EAAE,QAAQ,EAAE,SAAS,EAAE,KAAK,EAAE,EAAE,oBAAoB,2CAgB5E;AAED,UAAU,gBAAgB;IACxB,QAAQ,EAAE,SAAS,CAAC;IACpB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,iBAAS,WAAW,CAAC,EAAE,QAAQ,EAAE,SAAS,EAAE,EAAE,gBAAgB,2CAa7D;AAED,eAAO,MAAM,KAAK;;;;;CAKhB,CAAC"}

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 export { Router, useCurrentModal, useCurrentRoute, useDrawer, useHistoryState, useParams, useRoute, useRouter, useSearchParams, type CurrentModalApi, type RouterDrawerApi, type RouterDrawerGroup, type RouterDrawerGroupProps, type RouterDrawerItem, type RouterDrawerItemProps, type RouterDrawerNode, type RouterDrawerSection, type RouterDrawerSectionProps, type RouterDrawerProps, type RouterApi, type RouterNavigateFunction, type RouterReplaceFunction, type RouterRedirectProps, type RouterRouteContextValue, type RouterRouteLayoutProps, type RouterProtectedProps, type RouterRouteRenderProps, type RouterScreenAnimation, type RouterSplitPane, type RouterSplitViewProps, type RouterSplitViewSlotProps, type RouterTabBarTab, } from './Router';
 export type { RouterShellMode } from './types';
 export type { RouterOverlayLayout } from './types';
-export { Modal, ModalFrame } from './components';
+export { Modal, ModalFrame, Sheet, SheetFrame, useModalSwipeTarget, useSheetDragEngine, sheetDragStartsInInteractiveControl, sheetScrollAtTop, type SheetDragUpdate, } from './components';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,MAAM,EACN,eAAe,EACf,eAAe,EACf,SAAS,EACT,eAAe,EACf,SAAS,EACT,QAAQ,EACR,SAAS,EACT,eAAe,EACf,KAAK,eAAe,EACpB,KAAK,eAAe,EACpB,KAAK,iBAAiB,EACtB,KAAK,sBAAsB,EAC3B,KAAK,gBAAgB,EACrB,KAAK,qBAAqB,EAC1B,KAAK,gBAAgB,EACrB,KAAK,mBAAmB,EACxB,KAAK,wBAAwB,EAC7B,KAAK,iBAAiB,EACtB,KAAK,SAAS,EACd,KAAK,sBAAsB,EAC3B,KAAK,qBAAqB,EAC1B,KAAK,mBAAmB,EACxB,KAAK,uBAAuB,EAC5B,KAAK,sBAAsB,EAC3B,KAAK,oBAAoB,EACzB,KAAK,sBAAsB,EAC3B,KAAK,qBAAqB,EAC1B,KAAK,eAAe,EACpB,KAAK,oBAAoB,EACzB,KAAK,wBAAwB,EAC7B,KAAK,eAAe,GACrB,MAAM,UAAU,CAAC;AAClB,YAAY,EAAE,eAAe,EAAE,MAAM,SAAS,CAAC;AAC/C,YAAY,EAAE,mBAAmB,EAAE,MAAM,SAAS,CAAC;AACnD,OAAO,EAAE,KAAK,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,MAAM,EACN,eAAe,EACf,eAAe,EACf,SAAS,EACT,eAAe,EACf,SAAS,EACT,QAAQ,EACR,SAAS,EACT,eAAe,EACf,KAAK,eAAe,EACpB,KAAK,eAAe,EACpB,KAAK,iBAAiB,EACtB,KAAK,sBAAsB,EAC3B,KAAK,gBAAgB,EACrB,KAAK,qBAAqB,EAC1B,KAAK,gBAAgB,EACrB,KAAK,mBAAmB,EACxB,KAAK,wBAAwB,EAC7B,KAAK,iBAAiB,EACtB,KAAK,SAAS,EACd,KAAK,sBAAsB,EAC3B,KAAK,qBAAqB,EAC1B,KAAK,mBAAmB,EACxB,KAAK,uBAAuB,EAC5B,KAAK,sBAAsB,EAC3B,KAAK,oBAAoB,EACzB,KAAK,sBAAsB,EAC3B,KAAK,qBAAqB,EAC1B,KAAK,eAAe,EACpB,KAAK,oBAAoB,EACzB,KAAK,wBAAwB,EAC7B,KAAK,eAAe,GACrB,MAAM,UAAU,CAAC;AAClB,YAAY,EAAE,eAAe,EAAE,MAAM,SAAS,CAAC;AAC/C,YAAY,EAAE,mBAAmB,EAAE,MAAM,SAAS,CAAC;AACnD,OAAO,EACL,KAAK,EACL,UAAU,EACV,KAAK,EACL,UAAU,EACV,mBAAmB,EACnB,kBAAkB,EAClB,mCAAmC,EACnC,gBAAgB,EAChB,KAAK,eAAe,GACrB,MAAM,cAAc,CAAC"}

package/dist/index.js

@@ -35,6 +35,14 @@ var SHEET_DRAG_START_DISTANCE = 2;
 function sheetScrollAtTop(el) {
   return !el || el.scrollTop <= SHEET_DRAG_EPS;
 }
+function sheetDragStartsInInteractiveControl(target) {
+  if (!(target instanceof Element)) return false;
+  return Boolean(
+    target.closest(
+      'button,a,input,textarea,select,[role="button"],[data-sheet-drag-ignore="true"]'
+    )
+  );
+}
 function sheetDragStartsInTextInput(target) {
   if (!(target instanceof Element)) return false;
   return Boolean(
@@ -643,6 +651,8 @@ function SheetFrame({
   const disableDismiss = options?.disableDismiss ?? false;
   const customRequestClose = options?.onRequestClose;
   const variant = options?.variant ?? "detached";
+  const presentation = options?.presentation ?? "content";
+  const fullscreen = presentation === "fullscreen";
   const requestClose = useCallback(() => {
     if (disableDismiss) return;
     if (customRequestClose) {
@@ -657,12 +667,34 @@ function SheetFrame({
       close: requestClose,
       canClose: !disableDismiss,
       variant,
+      presentation,
       setOptions
     }),
-    [requestClose, disableDismiss, setScrollElement, setOptions, variant]
+    [
+      requestClose,
+      disableDismiss,
+      presentation,
+      setScrollElement,
+      setOptions,
+      variant
+    ]
   );
   const surfaceStyle = useMemo(
-    () => variant === "detached" ? {
+    () => fullscreen ? {
+      backgroundColor: "var(--router-bg)",
+      borderRadius: "33px 33px 0 0",
+      boxShadow: "var(--router-card-shadow)",
+      color: "var(--router-text)",
+      overflow: "hidden",
+      bottom: 0,
+      left: 0,
+      right: 0,
+      width: "100%",
+      maxWidth: "var(--router-container)",
+      height: "calc(100dvh - env(safe-area-inset-top, 0px))",
+      maxHeight: "none",
+      marginInline: "auto"
+    } : variant === "detached" ? {
       backgroundColor: "var(--router-bg)",
       borderRadius: "28px 28px 32px 32px",
       boxShadow: "var(--router-card-shadow)",
@@ -690,7 +722,7 @@ function SheetFrame({
       bottom: 0,
       maxHeight: "calc(100dvh - env(safe-area-inset-top, 0px))"
     },
-    [variant]
+    [fullscreen, variant]
   );
   const backdropStyle = useMemo(
     () => shell === "desktop-fullscreen" ? {
@@ -721,11 +753,12 @@ function SheetFrame({
       surfaceClassName: "router-sheet-surface",
       surfaceStyle,
       scrollElement,
+      closeTarget: fullscreen ? "viewport" : "surface",
       children: /* @__PURE__ */ jsx(
         "div",
         {
           ref: setFrameScrollElement,
-          className: "router-scroll router-sheet-frame-scroll",
+          className: `router-scroll router-sheet-frame-scroll${fullscreen ? " router-sheet-frame-scroll--fullscreen" : ""}`,
           children
         }
       )
@@ -736,14 +769,27 @@ function SheetRoot({
   children,
   disableDismiss,
   onRequestClose,
-  variant = "detached"
+  variant = "detached",
+  presentation = "content"
 }) {
   const { setOptions } = useSheetContext();
   const contentKey = useOverlayContentKey();
   useLayoutEffect(() => {
-    setOptions(contentKey, { disableDismiss, onRequestClose, variant });
+    setOptions(contentKey, {
+      disableDismiss,
+      onRequestClose,
+      variant,
+      presentation
+    });
     return () => setOptions(contentKey, null);
-  }, [contentKey, disableDismiss, onRequestClose, setOptions, variant]);
+  }, [
+    contentKey,
+    disableDismiss,
+    onRequestClose,
+    presentation,
+    setOptions,
+    variant
+  ]);
   return /* @__PURE__ */ jsx(Fragment, { children });
 }
 function SheetHeader({
@@ -754,8 +800,9 @@ function SheetHeader({
   sticky = true,
   align = "start"
 }) {
-  const { close, canClose } = useSheetContext();
-  const headerClassName = `router-sheet-header${sticky ? " router-sheet-header--sticky" : ""}`;
+  const { close, canClose, presentation } = useSheetContext();
+  const headerBaseClassName = presentation === "fullscreen" ? "router-modal-header" : "router-sheet-header";
+  const headerClassName = `${headerBaseClassName}${sticky ? ` ${headerBaseClassName}--sticky` : ""}`;
   const titleClassName = `router-sheet-title${align === "center" ? " router-sheet-title--center" : ""}`;
   return /* @__PURE__ */ jsxs("div", { className: headerClassName, children: [
     leftAction != null && /* @__PURE__ */ jsx("div", { className: "router-sheet-header-side", children: leftAction }),
@@ -795,7 +842,7 @@ function SheetFooter({ children, className }) {
     }
   );
 }
-Object.assign(SheetRoot, {
+var Sheet = Object.assign(SheetRoot, {
   Header: SheetHeader,
   Content: SheetContent,
   ScrollView: SheetScrollView,
@@ -3644,6 +3691,6 @@ var Router = Object.assign(RouterRoot, {
   Protected: RouterProtected
 });
 
-export { Modal, ModalFrame, Router, useCurrentModal, useCurrentRoute, useDrawer, useHistoryState, useParams, useRoute, useRouter, useSearchParams };
+export { Modal, ModalFrame, Router, Sheet, SheetFrame, sheetDragStartsInInteractiveControl, sheetScrollAtTop, useCurrentModal, useCurrentRoute, useDrawer, useHistoryState, useModalSwipeTarget, useParams, useRoute, useRouter, useSearchParams, useSheetDragEngine };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map