@capgo/capacitor-sheets 8.0.11 → 8.0.12

package/README.md

@@ -183,6 +183,20 @@ Create the Capgo app once before the first upload. GitHub Actions also include a
 
 ## Installation
 
+You can use our AI-Assisted Setup to install the plugin. Add the Capgo skills to your AI tool using the following command:
+
+```bash
+npx skills add https://github.com/cap-go/capacitor-skills --skill capacitor-plugins
+```
+
+Then use the following prompt:
+
+```text
+Use the `capacitor-plugins` skill from `cap-go/capacitor-skills` to install the `@capgo/capacitor-sheets` plugin in my project.
+```
+
+If you prefer Manual Setup, install the plugin by running the following commands and follow the platform-specific instructions below:
+
 ```bash
 npm install @capgo/capacitor-sheets
 npx cap sync
@@ -196,13 +210,27 @@ Add `viewport-fit=cover` so iOS exposes safe-area insets to CSS:
 <meta name="viewport" content="width=device-width, initial-scale=1.0, viewport-fit=cover" />
 ```
 
-Safe areas are enabled by default. `cap-sheet-view` reads standard `env(safe-area-inset-*)` values and Capacitor SystemBars fallback variables such as `--safe-area-inset-bottom`, then applies them to the sheet viewport in `em`-based layout. You can opt out or choose edges per sheet:
+Safe areas are enabled by default. In `auto`, edge-attached sheets protect the attached edge and side edges while leaving the opposite edge available for fullscreen detents. `cap-sheet-view` reads standard `env(safe-area-inset-*)` values and Capacitor SystemBars fallback variables such as `--safe-area-inset-bottom`, then applies them to the sheet viewport in `em`-based layout. You can opt out or choose edges per sheet:
 
 ```text
 <cap-sheet safe-area="none"></cap-sheet>
 <cap-sheet safe-area="bottom left right"></cap-sheet>
 ```
 
+Detached sheets can use Gorhom-style container spacing without CSS margins. Use `detached` for full edge rounding, `top-inset` / `bottom-inset` / `left-inset` / `right-inset` for one-off offsets, or `containerOffset` from framework setup helpers for per-edge offsets:
+
+```html
+<cap-sheet detached bottom-inset="1rem" detents="18em" content-placement="bottom"></cap-sheet>
+```
+
+```ts
+setupSheet(sheet, {
+  detached: true,
+  bottomInset: '1rem',
+  containerOffset: { left: '1rem', right: '1rem' },
+});
+```
+
 For Capacitor apps with overlay status/system bars, keep the platform plugins responsible for exposing correct insets:
 
 ```ts

package/dist/angular/index.d.mts

@@ -5,7 +5,11 @@ type SheetTrack = Exclude<SheetPlacement, 'center'>;
 /** Viewport edges protected by safe-area insets. */
 type SheetSafeAreaEdge = 'top' | 'bottom' | 'left' | 'right';
 /** Safe-area behavior for Capacitor WebViews and mobile browsers. */
-type SheetSafeAreaMode = boolean | 'auto' | 'none' | SheetSafeAreaEdge[];
+type SheetSafeAreaMode = boolean | 'auto' | 'all' | 'none' | SheetSafeAreaEdge[];
+/** CSS length or pixel number used for sheet container insets. */
+type SheetInsetValue = string | number;
+/** Extra container offsets applied around the sheet viewport. */
+type SheetContainerOffset = Partial<Record<SheetSafeAreaEdge, SheetInsetValue>>;
 /** Runtime travel state emitted by sheet lifecycle events. */
 type SheetTravelStatus = 'idle' | 'entering' | 'exiting' | 'dragging' | 'settling';
 /** Built-in animation presets tuned for mobile WebViews. */
@@ -49,6 +53,18 @@ interface SheetOptions {
     contentPlacement?: SheetPlacement;
     /** Safe-area edges protected by the sheet viewport. Defaults to `auto`. */
     safeArea?: SheetSafeAreaMode;
+    /** Render as a floating sheet with detached edge rounding. */
+    detached?: boolean;
+    /** Extra top inset added to the sheet viewport, equivalent to Gorhom `topInset`. */
+    topInset?: SheetInsetValue;
+    /** Extra bottom inset added to the sheet viewport, equivalent to Gorhom `bottomInset`. */
+    bottomInset?: SheetInsetValue;
+    /** Extra left inset added to the sheet viewport. */
+    leftInset?: SheetInsetValue;
+    /** Extra right inset added to the sheet viewport. */
+    rightInset?: SheetInsetValue;
+    /** Extra per-edge container offsets, equivalent to Gorhom `containerOffset`. */
+    containerOffset?: SheetContainerOffset;
     /** Edge tracks that can dismiss the sheet. */
     tracks?: SheetTrack | SheetTrack[];
     /** Enables pointer, touch, trackpad, and wheel travel gestures. */
@@ -111,4 +127,4 @@ declare function setupSheet(element: HTMLElement, options?: Partial<SheetOptions
     onTravel?: (event: SheetTravelEvent) => void;
 }): () => void;
 
-export { type SheetActiveDetentChangeEvent, type SheetOptions, type SheetPresentedChangeEvent, type SheetSafeAreaEdge, type SheetSafeAreaMode, type SheetTravelEvent, setupSheet };
+export { type SheetActiveDetentChangeEvent, type SheetContainerOffset, type SheetInsetValue, type SheetOptions, type SheetPresentedChangeEvent, type SheetSafeAreaEdge, type SheetSafeAreaMode, type SheetTravelEvent, setupSheet };

package/dist/angular/index.d.ts

@@ -5,7 +5,11 @@ type SheetTrack = Exclude<SheetPlacement, 'center'>;
 /** Viewport edges protected by safe-area insets. */
 type SheetSafeAreaEdge = 'top' | 'bottom' | 'left' | 'right';
 /** Safe-area behavior for Capacitor WebViews and mobile browsers. */
-type SheetSafeAreaMode = boolean | 'auto' | 'none' | SheetSafeAreaEdge[];
+type SheetSafeAreaMode = boolean | 'auto' | 'all' | 'none' | SheetSafeAreaEdge[];
+/** CSS length or pixel number used for sheet container insets. */
+type SheetInsetValue = string | number;
+/** Extra container offsets applied around the sheet viewport. */
+type SheetContainerOffset = Partial<Record<SheetSafeAreaEdge, SheetInsetValue>>;
 /** Runtime travel state emitted by sheet lifecycle events. */
 type SheetTravelStatus = 'idle' | 'entering' | 'exiting' | 'dragging' | 'settling';
 /** Built-in animation presets tuned for mobile WebViews. */
@@ -49,6 +53,18 @@ interface SheetOptions {
     contentPlacement?: SheetPlacement;
     /** Safe-area edges protected by the sheet viewport. Defaults to `auto`. */
     safeArea?: SheetSafeAreaMode;
+    /** Render as a floating sheet with detached edge rounding. */
+    detached?: boolean;
+    /** Extra top inset added to the sheet viewport, equivalent to Gorhom `topInset`. */
+    topInset?: SheetInsetValue;
+    /** Extra bottom inset added to the sheet viewport, equivalent to Gorhom `bottomInset`. */
+    bottomInset?: SheetInsetValue;
+    /** Extra left inset added to the sheet viewport. */
+    leftInset?: SheetInsetValue;
+    /** Extra right inset added to the sheet viewport. */
+    rightInset?: SheetInsetValue;
+    /** Extra per-edge container offsets, equivalent to Gorhom `containerOffset`. */
+    containerOffset?: SheetContainerOffset;
     /** Edge tracks that can dismiss the sheet. */
     tracks?: SheetTrack | SheetTrack[];
     /** Enables pointer, touch, trackpad, and wheel travel gestures. */
@@ -111,4 +127,4 @@ declare function setupSheet(element: HTMLElement, options?: Partial<SheetOptions
     onTravel?: (event: SheetTravelEvent) => void;
 }): () => void;
 
-export { type SheetActiveDetentChangeEvent, type SheetOptions, type SheetPresentedChangeEvent, type SheetSafeAreaEdge, type SheetSafeAreaMode, type SheetTravelEvent, setupSheet };
+export { type SheetActiveDetentChangeEvent, type SheetContainerOffset, type SheetInsetValue, type SheetOptions, type SheetPresentedChangeEvent, type SheetSafeAreaEdge, type SheetSafeAreaMode, type SheetTravelEvent, setupSheet };

package/dist/angular/index.js

@@ -147,6 +147,11 @@ var CSS = `
   --cap-sheet-applied-safe-area-bottom: var(--cap-sheet-safe-area-bottom);
   --cap-sheet-applied-safe-area-left: var(--cap-sheet-safe-area-left);
   --cap-sheet-applied-safe-area-right: var(--cap-sheet-safe-area-right);
+  --cap-sheet-container-offset-top: 0em;
+  --cap-sheet-container-offset-bottom: 0em;
+  --cap-sheet-container-offset-left: 0em;
+  --cap-sheet-container-offset-right: 0em;
+  --cap-sheet-keyboard-offset: 0em;
 }
 
 @supports (height: 1dvh) {
@@ -175,10 +180,13 @@ cap-sheet-view {
   overscroll-behavior: none;
   contain: layout style;
   box-sizing: border-box;
-  padding-block-start: var(--cap-sheet-applied-safe-area-top, 0em);
-  padding-block-end: calc(var(--cap-sheet-applied-safe-area-bottom, 0em) + var(--cap-sheet-keyboard-offset, 0em));
-  padding-inline-start: var(--cap-sheet-applied-safe-area-left, 0em);
-  padding-inline-end: var(--cap-sheet-applied-safe-area-right, 0em);
+  padding-top: calc(var(--cap-sheet-applied-safe-area-top, 0em) + var(--cap-sheet-container-offset-top, 0em));
+  padding-bottom: calc(
+    var(--cap-sheet-applied-safe-area-bottom, 0em) + var(--cap-sheet-container-offset-bottom, 0em) +
+      var(--cap-sheet-keyboard-offset, 0em)
+  );
+  padding-left: calc(var(--cap-sheet-applied-safe-area-left, 0em) + var(--cap-sheet-container-offset-left, 0em));
+  padding-right: calc(var(--cap-sheet-applied-safe-area-right, 0em) + var(--cap-sheet-container-offset-right, 0em));
 }
 
 cap-sheet-view[hidden] {
@@ -223,6 +231,7 @@ cap-sheet-backdrop {
 }
 
 cap-sheet-content {
+  --cap-sheet-content-border-radius: var(--cap-sheet-radius) var(--cap-sheet-radius) 0 0;
   box-sizing: border-box;
   position: relative;
   display: block;
@@ -230,7 +239,7 @@ cap-sheet-content {
   max-height: 100%;
   color: CanvasText;
   background: var(--cap-sheet-surface);
-  border-radius: var(--cap-sheet-radius) var(--cap-sheet-radius) 0 0;
+  border-radius: var(--cap-sheet-content-border-radius);
   box-shadow: var(--cap-sheet-shadow), var(--cap-sheet-edge-bleed-shadow, 0 0 0 0 transparent);
   overflow: auto;
   overscroll-behavior: contain;
@@ -241,27 +250,35 @@ cap-sheet-content {
 }
 
 cap-sheet-view[content-placement="top"] cap-sheet-content {
-  border-radius: 0 0 var(--cap-sheet-radius) var(--cap-sheet-radius);
+  --cap-sheet-content-border-radius: 0 0 var(--cap-sheet-radius) var(--cap-sheet-radius);
 }
 
 cap-sheet-view[content-placement="left"] cap-sheet-content {
   width: min(88%, 28em);
   height: 100%;
   max-height: 100%;
-  border-radius: 0 var(--cap-sheet-radius) var(--cap-sheet-radius) 0;
+  --cap-sheet-content-border-radius: 0 var(--cap-sheet-radius) var(--cap-sheet-radius) 0;
 }
 
 cap-sheet-view[content-placement="right"] cap-sheet-content {
   width: min(88%, 28em);
   height: 100%;
   max-height: 100%;
-  border-radius: var(--cap-sheet-radius) 0 0 var(--cap-sheet-radius);
+  --cap-sheet-content-border-radius: var(--cap-sheet-radius) 0 0 var(--cap-sheet-radius);
 }
 
 cap-sheet-view[content-placement="center"] cap-sheet-content {
   width: min(90%, 30em);
   max-height: min(90%, 42em);
-  border-radius: var(--cap-sheet-radius);
+  --cap-sheet-content-border-radius: var(--cap-sheet-radius);
+}
+
+cap-sheet-view[data-detached="true"] cap-sheet-content {
+  --cap-sheet-content-border-radius: var(--cap-sheet-detached-radius, var(--cap-sheet-radius));
+}
+
+cap-sheet-view[data-detached="true"] cap-sheet-content[data-cap-sheet-bleeds] {
+  --cap-sheet-edge-bleed-shadow: 0 0 0 0 transparent;
 }
 
 cap-sheet-bleeding-background {
@@ -515,6 +532,7 @@ function releaseThemeColorDimmer(documentRef) {
 var defaultOptions = {
   contentPlacement: "bottom",
   sheetRole: "dialog",
+  detached: false,
   safeArea: "auto",
   swipe: true,
   swipeDismissal: true,
@@ -545,21 +563,74 @@ function normalizeDetents(value) {
   if (Array.isArray(value)) return value.filter(Boolean);
   return parseList(value || null);
 }
+var unitlessInsetPattern = /^-?(?:\d+(?:\.\d+)?|\.\d+)$/;
+function normalizeInsetValue(value) {
+  return unitlessInsetPattern.test(value) ? `${value}px` : value;
+}
+function parseInset(value) {
+  const normalized = value?.trim();
+  return normalized ? normalizeInsetValue(normalized) : void 0;
+}
+function formatInsetValue(value) {
+  if (typeof value === "number") return Number.isFinite(value) ? `${value}px` : "0em";
+  const normalized = value?.trim();
+  return normalized ? normalizeInsetValue(normalized) : "0em";
+}
+function explicitInsetForEdge(options, edge) {
+  switch (edge) {
+    case "top":
+      return options.topInset;
+    case "bottom":
+      return options.bottomInset;
+    case "left":
+      return options.leftInset;
+    case "right":
+      return options.rightInset;
+  }
+}
+function containerInsetForEdge(options, edge) {
+  const values = [options.containerOffset?.[edge], explicitInsetForEdge(options, edge)].map(formatInsetValue).filter((value) => value !== "0em");
+  if (values.length === 0) return "0em";
+  if (values.length === 1) return values[0];
+  return `calc(${values.join(" + ")})`;
+}
+function hasOwnOption(options, key) {
+  return Object.prototype.hasOwnProperty.call(options, key);
+}
+function affectsDismissedOffset(options) {
+  return hasOwnOption(options, "contentPlacement") || hasOwnOption(options, "tracks") || hasOwnOption(options, "detents") || hasOwnOption(options, "safeArea") || hasOwnOption(options, "topInset") || hasOwnOption(options, "bottomInset") || hasOwnOption(options, "leftInset") || hasOwnOption(options, "rightInset") || hasOwnOption(options, "containerOffset");
+}
 var safeAreaEdges = ["top", "bottom", "left", "right"];
 function parseSafeArea(value) {
   if (value === null) return void 0;
   const normalized = value.trim().toLowerCase();
-  if (!normalized || normalized === "true" || normalized === "auto" || normalized === "all") return "auto";
+  if (!normalized || normalized === "auto") return "auto";
+  if (normalized === "true" || normalized === "all") return "all";
   if (normalized === "false" || normalized === "none" || normalized === "off") return "none";
   const edges = parseList(normalized).filter(
     (edge) => safeAreaEdges.includes(edge)
   );
   return edges.length > 0 ? edges : "auto";
 }
-function resolveSafeAreaEdges(value) {
+function resolveAutoSafeAreaEdges(placement) {
+  switch (placement) {
+    case "bottom":
+      return ["bottom", "left", "right"];
+    case "top":
+      return ["top", "left", "right"];
+    case "left":
+      return ["top", "bottom", "left"];
+    case "right":
+      return ["top", "bottom", "right"];
+    case "center":
+      return safeAreaEdges;
+  }
+}
+function resolveSafeAreaEdges(value, placement) {
   if (value === false || value === "none") return [];
+  if (value === true || value === "all") return safeAreaEdges;
   if (Array.isArray(value)) return value.filter((edge) => safeAreaEdges.includes(edge));
-  return safeAreaEdges;
+  return resolveAutoSafeAreaEdges(placement);
 }
 function readOptionsFromElement(root) {
   const placement = parsePlacement(root.getAttribute("content-placement"));
@@ -576,6 +647,11 @@ function readOptionsFromElement(root) {
     sheetRole: root.getAttribute("sheet-role") || defaultOptions.sheetRole,
     contentPlacement: placement,
     safeArea: parseSafeArea(root.getAttribute("safe-area")),
+    detached: parseBoolean(root.getAttribute("detached"), defaultOptions.detached),
+    topInset: parseInset(root.getAttribute("top-inset")),
+    bottomInset: parseInset(root.getAttribute("bottom-inset")),
+    leftInset: parseInset(root.getAttribute("left-inset")),
+    rightInset: parseInset(root.getAttribute("right-inset")),
     tracks: parseTracks(root.getAttribute("tracks"), placement === "center" ? "bottom" : placement),
     swipe: parseBoolean(root.getAttribute("swipe"), defaultOptions.swipe),
     swipeDismissal: parseBoolean(root.getAttribute("swipe-dismissal"), defaultOptions.swipeDismissal),
@@ -812,6 +888,11 @@ var SheetController = class {
       this.parts.content.setAttribute("aria-modal", attributeBoolean(this.options.inertOutside !== false));
     }
     this.linkAccessibleNames();
+    if (this.connected && !this.presented && this.parts.content && affectsDismissedOffset(options)) {
+      this.remeasure();
+      this.applyOffset(this.detentOffsetsPx[0] || this.hiddenOffsetPx, this.status);
+      this.updateDomState(false);
+    }
     this.registerStack();
   }
   /** Register a view, backdrop, content, or semantic part. */
@@ -966,12 +1047,29 @@ var SheetController = class {
       const sign = trackSign(track);
       const axis = isVerticalTrack(track) ? "y" : "x";
       const rect = content.getBoundingClientRect();
+      const viewRect = view?.getBoundingClientRect();
       const size = axis === "y" ? rect.height : rect.width;
-      this.hiddenOffsetPx = Math.max(size, 1) * sign;
+      const transformedX = axis === "x" ? this.currentOffsetPx : 0;
+      const transformedY = axis === "y" ? this.currentOffsetPx : 0;
+      const contentRect = {
+        top: rect.top - transformedY,
+        right: rect.right - transformedX,
+        bottom: rect.bottom - transformedY,
+        left: rect.left - transformedX
+      };
+      let hiddenOffsetPx = Math.max(size, 1) * sign;
+      if (viewRect) {
+        if (track === "top") hiddenOffsetPx = viewRect.top - contentRect.bottom;
+        if (track === "bottom") hiddenOffsetPx = viewRect.bottom - contentRect.top;
+        if (track === "left") hiddenOffsetPx = viewRect.left - contentRect.right;
+        if (track === "right") hiddenOffsetPx = viewRect.right - contentRect.left;
+      }
+      this.hiddenOffsetPx = Math.abs(hiddenOffsetPx) > 1 ? hiddenOffsetPx : sign;
       const detents = normalizeDetents(this.options.detents);
       const offsets = [this.hiddenOffsetPx];
+      const measureContext = content;
       for (const detent of detents) {
-        const visible = measureCssLength(detent, content, axis);
+        const visible = measureCssLength(detent, measureContext, axis);
         const offset = Math.max(Math.abs(this.hiddenOffsetPx) - visible, 0) * sign;
         offsets.push(offset);
       }
@@ -1141,13 +1239,17 @@ var SheetController = class {
   applySafeArea() {
     const view = this.parts.view;
     if (!view) return;
-    const edges = new Set(resolveSafeAreaEdges(this.options.safeArea));
+    const edges = new Set(
+      resolveSafeAreaEdges(this.options.safeArea, this.options.contentPlacement || defaultOptions.contentPlacement)
+    );
     view.dataset.safeArea = edges.size > 0 ? Array.from(edges).join(" ") : "none";
+    view.dataset.detached = this.options.detached ? "true" : "false";
     for (const edge of safeAreaEdges) {
       view.style.setProperty(
         `--cap-sheet-applied-safe-area-${edge}`,
         edges.has(edge) ? `var(--cap-sheet-safe-area-${edge})` : "0em"
       );
+      view.style.setProperty(`--cap-sheet-container-offset-${edge}`, containerInsetForEdge(this.options, edge));
     }
   }
   addGlobalListeners() {
@@ -1445,12 +1547,17 @@ var observed = [
   "default-active-detent",
   "default-presented",
   "detents",
+  "detached",
   "focus-trap",
   "inert-outside",
   "native-edge-swipe-prevention",
   "native-focus-scroll-prevention",
   "presented",
   "restore-focus",
+  "top-inset",
+  "bottom-inset",
+  "left-inset",
+  "right-inset",
   "safe-area",
   "sheet-role",
   "stack",
@@ -1565,12 +1672,17 @@ function readChangedOptionsFromElement(element, name) {
     "default-active-detent": ["defaultActiveDetent"],
     "default-presented": ["defaultPresented"],
     detents: ["detents"],
+    detached: ["detached"],
     "focus-trap": ["focusTrap"],
     "inert-outside": ["inertOutside"],
     "native-edge-swipe-prevention": ["nativeEdgeSwipePrevention"],
     "native-focus-scroll-prevention": ["nativeFocusScrollPrevention"],
     presented: ["presented"],
     "restore-focus": ["restoreFocus"],
+    "top-inset": ["topInset"],
+    "bottom-inset": ["bottomInset"],
+    "left-inset": ["leftInset"],
+    "right-inset": ["rightInset"],
     "safe-area": ["safeArea"],
     "sheet-role": ["sheetRole"],
     stack: ["stack"],
@@ -1587,6 +1699,19 @@ function readChangedOptionsFromElement(element, name) {
   }
   return changed;
 }
+function formatInsetAttribute(value) {
+  if (typeof value === "number") return Number.isFinite(value) ? `${value}px` : void 0;
+  const normalized = value.trim();
+  return normalized || void 0;
+}
+function combineInsetAttributes(...values) {
+  const parts = values.flatMap((value) => {
+    const attributeValue = value === void 0 ? void 0 : formatInsetAttribute(value);
+    return attributeValue ? [attributeValue] : [];
+  });
+  if (parts.length === 0) return void 0;
+  return parts.length === 1 ? parts[0] : `calc(${parts.join(" + ")})`;
+}
 function applySheetOptions(element, options) {
   if (options.contentPlacement) element.setAttribute("content-placement", options.contentPlacement);
   if (options.detents !== void 0) {
@@ -1598,7 +1723,6 @@ function applySheetOptions(element, options) {
   }
   if (options.defaultPresented !== void 0)
     element.setAttribute("default-presented", String(options.defaultPresented));
-  if (options.presented !== void 0) element.toggleAttribute("presented", options.presented);
   if (options.sheetRole) element.setAttribute("sheet-role", options.sheetRole);
   if (options.safeArea !== void 0) {
     element.setAttribute(
@@ -1609,7 +1733,23 @@ function applySheetOptions(element, options) {
   if (options.stack) element.setAttribute("stack", options.stack);
   if (options.tracks)
     element.setAttribute("tracks", Array.isArray(options.tracks) ? options.tracks.join(" ") : options.tracks);
+  for (const [key, attr, edge] of [
+    ["topInset", "top-inset", "top"],
+    ["bottomInset", "bottom-inset", "bottom"],
+    ["leftInset", "left-inset", "left"],
+    ["rightInset", "right-inset", "right"]
+  ]) {
+    const hasEdgeInset = Object.prototype.hasOwnProperty.call(options, key);
+    const hasContainerOffset = Object.prototype.hasOwnProperty.call(options, "containerOffset");
+    const attributeValue = combineInsetAttributes(options[key], options.containerOffset?.[edge]);
+    if (attributeValue !== void 0) {
+      element.setAttribute(attr, attributeValue);
+    } else if (hasEdgeInset || hasContainerOffset) {
+      element.removeAttribute(attr);
+    }
+  }
   for (const [key, attr] of [
+    ["detached", "detached"],
     ["swipe", "swipe"],
     ["swipeDismissal", "swipe-dismissal"],
     ["swipeOvershoot", "swipe-overshoot"],
@@ -1628,6 +1768,7 @@ function applySheetOptions(element, options) {
   if (options.themeColorDimming !== void 0) {
     element.setAttribute("theme-color-dimming", options.themeColorDimming === false ? "false" : "auto");
   }
+  if (options.presented !== void 0) element.toggleAttribute("presented", options.presented);
 }
 
 // src/components/sheet-actions.ts