@stacksjs/defaults 0.75.182 → 0.75.183

package/ai/skills/stacks-mobile/SKILL.md

@@ -452,7 +452,14 @@ option the original metres heuristic remains for unlabelled inputs.
 - `<NativeSheet v-model:open="editing" title="…">` raises a bottom sheet for a
   task that belongs to the screen: dragged down from its grabber or header to
   dismiss, the page behind inert. `detents="medium large"` makes it full
-  height with detents, the page pressed into a card at large.
+  height with detents, the page pressed into a card at large. An open sheet is
+  a layer on stx's overlay stack (`window.stx.overlays`) with Dialog, Drawer,
+  stxConfirm and the HTML alerts: the stack locks the page, makes it inert,
+  gives Escape and Tab to the top layer and returns focus, so a confirm opened
+  from a sheet closes alone. `lockBackground` and `trapFocus` no longer exist;
+  an app's own overlay uses `openOverlay` / `closeOverlay` from
+  `@stacksjs/components/overlays` (in `<script client>`), passing `root` for
+  an element lifted into `<body>` and `zIndex` to stack by opening order.
 - `<NativeContextMenu :items="[...]" @select="…">` opens a menu on a
   half-second press: UIMenu in the shell, an HTML menu elsewhere.
 - `<NativeActionSheet v-model:open="choosing" :actions="[...]" @select="…">`

package/ide/vscode/package.json

@@ -2,7 +2,7 @@
   "publisher": "Stacks",
   "name": "vscode-stacks",
   "displayName": "Stacks",
-  "version": "0.75.182",
+  "version": "0.75.183",
   "description": "Stacks, built into VS Code: stx templates, pickier linting and formatting, encrypted env files, the dev server preview and every buddy command. No other extensions required.",
   "license": "MIT",
   "funding": "https://github.com/sponsors/chrisbbreuer",

package/package.json

@@ -2,7 +2,7 @@
   "name": "@stacksjs/defaults",
   "type": "module",
   "sideEffects": false,
-  "version": "0.75.182",
+  "version": "0.75.183",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/stacksjs/stacks.git",
@@ -55,7 +55,7 @@
   "dependencies": {
     "@iconify-json/f7": "^1.2.2",
     "@iconify-json/hugeicons": "^1.2.35",
-    "@stacksjs/mobile": "0.75.182",
+    "@stacksjs/mobile": "0.75.183",
     "@stacksjs/sanitizer": "^0.2.483",
     "@xterm/addon-fit": "^0.11.0",
     "@xterm/xterm": "^6.0.0",

package/resources/components/NativeComponents.test.ts

@@ -118,10 +118,15 @@ describe('Native components', () => {
     expect(bar).toContain("useReactiveProp<boolean>('titleOnScroll', false)")
   })
 
-  it('lifts an open sheet out of the router\'s stacking context', () => {
+  it('lifts a sheet into the body when it mounts, out of the router\'s stacking context', () => {
     const sheet = read('NativeSheet')
-    expect(sheet).toContain('main:has(.native-sheet.is-open) { view-transition-name: none; }')
     expect(sheet).toContain("useModel('open'")
+    // Lifted before it can open, so it never draws inside <main>, which the
+    // router makes a stacking context; <main> no longer has to give up its
+    // view-transition name while a sheet is up.
+    const mounted = sheet.slice(sheet.indexOf('onMount(() => {'))
+    expect(mounted.indexOf('putBack ??= liftToBody(element)')).toBeLessThan(mounted.indexOf('if (open()) present()'))
+    expect(sheet).not.toContain('main:has(')
   })
 
   it('hides the native tab bar under a shell that has none, like a sign-in screen', () => {
@@ -272,12 +277,32 @@ describe('Native components feel native', () => {
     expect(html).toContain('data-stx-ref="nativeSheetHeader"')
   })
 
-  it('opens a sheet without a haptic, holds the page behind it, and keeps focus inside', () => {
+  it('opens a sheet without a haptic, as a layer on the stx overlay stack', () => {
     const sheet = read('NativeSheet')
     expect(sheet).not.toContain('haptics')
-    expect(sheet).toContain('releaseBackground = lockBackground(element)')
-    expect(sheet).toContain('trapFocus(panel.current as HTMLElement, event)')
     expect(sheet).toContain('putBack ??= liftToBody(element)')
+    // The stack holds the page, traps Tab, answers Escape for the top layer
+    // and hands focus back, shared with Dialog, Drawer and stxConfirm. The
+    // sheet's own Escape listener, Tab trap, background lock and focus
+    // restore each fought the stack when one overlay opened over another.
+    expect(sheet).toContain("import { closeOverlay, openOverlay } from '@stacksjs/components/overlays'")
+    expect(sheet).toContain('openOverlay(overlayId, {')
+    expect(sheet).toContain('root: element,')
+    expect(sheet).toContain('zIndex: SHEET_LAYER,')
+    expect(sheet).toContain('onEscape: close,')
+    expect(sheet).toContain('initialFocus: sheetPanel,')
+    for (const gone of ['lockBackground', 'trapFocus', 'previousFocus', "useEventListener('keydown'", 'releaseBackground'])
+      expect(sheet).not.toContain(gone)
+  })
+
+  it('leaves the overlay stack when it closes, and when it is removed while up', () => {
+    const sheet = read('NativeSheet')
+    const dismissed = sheet.slice(sheet.indexOf('function dismissed(): void {'), sheet.indexOf('let wasOpen = false'))
+    expect(dismissed).toContain('closeOverlay(overlayId)')
+    const destroyed = sheet.slice(sheet.indexOf('onDestroy(() => {'), sheet.indexOf("useEventListener('stx:navigate'"))
+    expect(destroyed).toContain('closeOverlay(overlayId)')
+    // Each sheet gives back only its own hold on the card.
+    expect(destroyed).toContain('presentPageAsCard(element.ownerDocument, false)')
   })
 
   it('slides a sheet up from where it was lifted to, rather than appearing up', () => {
@@ -285,8 +310,8 @@ describe('Native components feel native', () => {
     // is-open follows `shown`, which present() sets only after the lifted
     // sheet's closed style is worked out in the body.
     expect(sheet).toContain("const sheetClass = derived(() => `${shown() ? 'is-open' : ''}")
-    expect(sheet).toContain('sheetPanel.getBoundingClientRect()')
-    expect(sheet.indexOf('sheetPanel.getBoundingClientRect()')).toBeLessThan(sheet.indexOf('shown.set(true)'))
+    expect(sheet).toContain('sheetPanel()?.getBoundingClientRect()')
+    expect(sheet.indexOf('sheetPanel()?.getBoundingClientRect()')).toBeLessThan(sheet.indexOf('shown.set(true)'))
     expect(sheet.indexOf('putBack ??= liftToBody(element)')).toBeLessThan(sheet.indexOf('shown.set(true)'))
   })
 

package/resources/components/NativeSheet.stx

@@ -1,6 +1,7 @@
 <script client>
 import type { SheetDetent } from '@stacksjs/mobile'
-import { coverTabBar, liftToBody, lockBackground, observeSheetDrag, presentPageAsCard, trapFocus } from '@stacksjs/mobile'
+import { closeOverlay, openOverlay } from '@stacksjs/components/overlays'
+import { coverTabBar, liftToBody, observeSheetDrag, presentPageAsCard } from '@stacksjs/mobile'
 
 /**
  * A bottom sheet: a task that belongs to this screen, raised over it.
@@ -19,6 +20,15 @@ import { coverTabBar, liftToBody, lockBackground, observeSheetDrag, presentPageA
  * it is up. It belongs to the screen it was opened on, so leaving that screen
  * (a link from outside, a tab switch) closes it rather than carrying it over
  * the next one.
+ *
+ * An open sheet is a layer on the page's overlay stack (stx's
+ * `window.stx.overlays`), shared with Dialog, Drawer, stxConfirm, the web
+ * stand-ins for native alerts and the app's own overlays. The stack holds the
+ * page still from the first layer to the last, makes the rest of the page
+ * inert, gives Escape and Tab to whichever layer is on top, and hands focus
+ * back to whatever opened each one. A confirmation opened from a sheet, or a
+ * sheet opened over a drawer, closes with one Escape and leaves the layer
+ * under it up, locked and in charge of the keyboard.
  */
 const emit = defineEmits()
 const open = useModel('open', { default: false })
@@ -44,9 +54,15 @@ const panel = useRef('nativeSheetPanel')
 const grabber = useRef('nativeSheetGrabber')
 const header = useRef('nativeSheetHeader')
 
-let releaseBackground: (() => void) | null = null
+// This sheet's id on the overlay stack.
+const overlayId = useId('native-sheet')
+// Sheets stack above the page at 70 (the stylesheet's z-index); the stack
+// adds each open sheet's place to it, so a sheet opened over another draws
+// above it wherever the two were lifted into the body.
+const SHEET_LAYER = 70
+
+let presented = false
 let putBack: (() => void) | null = null
-let previousFocus: HTMLElement | null = null
 let carded = false
 let stopDrag: (() => void) | null = null
 let openedOn = ''
@@ -59,35 +75,47 @@ function root(): HTMLElement | null {
   return sheetRoot.current as HTMLElement | null
 }
 
+function sheetPanel(): HTMLElement | null {
+  return panel.current as HTMLElement | null
+}
+
 function present(): void {
   const element = root()
-  if (!element || releaseBackground) return
+  if (!element || presented) return
+  presented = true
   detent.set(detents()[0] ?? 'large')
-  previousFocus = element.ownerDocument.activeElement as HTMLElement | null
   // Out of the page's stacking contexts and transforms (the card below
-  // scales the page), and everything else made inert behind it.
+  // scales the page). A child of the body, it is what the overlay stack keeps
+  // usable while everything else goes inert.
   putBack ??= liftToBody(element)
-  releaseBackground = lockBackground(element)
   openedOn = currentPath()
   coverTabBar(element, true)
   // A node moved in the document starts over with no style to transition
   // from, so a sheet lifted and marked open in one go appears already up.
   // Work its closed style out where it now is, then open it: the panel
   // slides from there.
-  const sheetPanel = panel.current as HTMLElement | null
-  if (sheetPanel) void sheetPanel.getBoundingClientRect()
+  void sheetPanel()?.getBoundingClientRect()
   shown.set(true)
-  void nextTick(() => (panel.current as HTMLElement | null)?.focus())
+  // Focus goes to the panel itself, not its first control: on a phone a
+  // focused field raises the keyboard over the sheet before it is up.
+  openOverlay(overlayId, {
+    panel: sheetPanel,
+    root: element,
+    zIndex: SHEET_LAYER,
+    initialFocus: sheetPanel,
+    onEscape: close,
+  })
 }
 
 function dismissed(): void {
+  if (!presented) return
+  presented = false
   shown.set(false)
   const element = root()
   if (element) coverTabBar(element, false)
-  releaseBackground?.()
-  releaseBackground = null
-  previousFocus?.focus?.()
-  previousFocus = null
+  // Off the stack: the layer underneath (or the page) gets the keyboard back,
+  // and focus returns to whatever opened the sheet.
+  closeOverlay(overlayId)
 }
 
 let wasOpen = false
@@ -98,9 +126,9 @@ effect(() => {
   wasOpen = isOpen
 })
 
-// The page behind becomes a card while a full-height sheet is at large. Only
-// this sheet's own change is applied, so a closed sheet never undoes an open
-// one's card.
+// The page behind becomes a card while a full-height sheet is at large. Each
+// sheet hands back only its own hold, so a sheet closing over another never
+// undoes the card the other still wants.
 effect(() => {
   const element = root()
   const want = open() && hasDetents() && detent() === 'large'
@@ -117,13 +145,15 @@ function close(): void {
 onMount(() => {
   // Give the sheet its permanent presentation parent before its slot loads
   // media. Reparenting an already loading iframe or video interrupts playback.
+  // A closed sheet waits in the body like this, so one nested in another's
+  // content can open over it without leaving the document mid-transition.
   const element = root()
   if (element) putBack ??= liftToBody(element)
-  const sheetPanel = panel.current as HTMLElement | null
-  if (!sheetPanel) return
+  const dragPanel = sheetPanel()
+  if (!dragPanel) return
   const handles = [grabber.current, header.current].filter(Boolean) as HTMLElement[]
   stopDrag = observeSheetDrag({
-    panel: sheetPanel,
+    panel: dragPanel,
     handles,
     detents: () => detents(),
     detent: () => detent(),
@@ -137,10 +167,16 @@ onMount(() => {
 
 onDestroy(() => {
   stopDrag?.()
-  releaseBackground?.()
   const element = root()
-  if (element && open()) coverTabBar(element, false)
-  if (carded && element) presentPageAsCard(element.ownerDocument, false)
+  if (element && presented) coverTabBar(element, false)
+  // Removed while up: off the stack, so the page is not left locked under a
+  // sheet that is gone.
+  presented = false
+  closeOverlay(overlayId)
+  if (carded && element) {
+    carded = false
+    presentPageAsCard(element.ownerDocument, false)
+  }
   putBack?.()
 })
 
@@ -153,12 +189,6 @@ useEventListener('stx:navigate', (event: Event) => {
   if (to !== openedOn) close()
 })
 
-useEventListener('keydown', (event: KeyboardEvent) => {
-  if (!open()) return
-  if (event.key === 'Escape') close()
-  else if (panel.current) trapFocus(panel.current as HTMLElement, event)
-})
-
 const sheetClass = derived(() => `${shown() ? 'is-open' : ''}${hasDetents() ? ' has-detents' : ''}${detent() === 'medium' ? ' is-medium' : ''}`.trim())
 </script>
 
@@ -308,9 +338,4 @@ const sheetClass = derived(() => `${shown() ? 'is-open' : ''}${hasDetents() ? '
   :root[data-native-reduce-motion] .native-sheet-panel { transition: none; }
   :root[data-native-reduce-motion][data-native-sheet-card] .native-app-content { transform: none; border-radius: 0; }
 
-  /* The router names the page's <main> for view transitions, which makes it a
-     stacking context: a sheet inside it stacked under the tab bar whatever its
-     z-index. While a sheet is open <main> gives the name up. Nothing navigates
-     with a sheet open, so no transition is lost. */
-  main:has(.native-sheet.is-open) { view-transition-name: none; }
 </style>