@stacksjs/defaults 0.75.97 → 0.75.99

package/resources/components/NativeSheet.stx

@@ -1,40 +1,167 @@
 <script client>
-import { haptics } from '@stacksjs/mobile'
+import type { SheetDetent } from '@stacksjs/mobile'
+import { coverTabBar, liftToBody, lockBackground, observeSheetDrag, presentPageAsCard, trapFocus } from '@stacksjs/mobile'
 
 /**
  * A bottom sheet: a task that belongs to this screen, raised over it.
  *
- * Bind it with `v-model:open`. It opens with a light haptic tap, closes from
- * its backdrop, its Done button or Escape, and keeps its content clear of the
- * home indicator.
+ * Bind it with `v-model:open`. It closes from its backdrop, its Done button,
+ * Escape, or a drag down from its grabber or header (a flick, or past half
+ * way; a shorter drag springs back). While it is up the page behind it is
+ * inert and still, and focus stays inside it.
+ *
+ * `detents="medium large"` makes it a full-height sheet that rests at half
+ * the screen or all of it and is dragged between them, the first named being
+ * where it opens. At large the page behind shrinks back into a card, as iOS
+ * presents a page sheet. Without `detents` it is as tall as its content.
+ *
+ * As on iOS it covers the tab bar: in the app the native bar steps aside while
+ * 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.
  */
 const emit = defineEmits()
 const open = useModel('open', { default: false })
 const title = useReactiveProp<string>('title', '')
 const doneLabel = useReactiveProp<string>('doneLabel', 'Done')
+const detentsProp = useReactiveProp<SheetDetent[] | string>('detents', '')
+
+const detents = derived<SheetDetent[]>(() => {
+  const raw = detentsProp()
+  const list = Array.isArray(raw) ? raw : String(raw || '').split(/[\s,]+/)
+  const valid = list.filter((value): value is SheetDetent => value === 'medium' || value === 'large')
+  return valid.length ? valid : ['large']
+})
+const hasDetents = derived(() => Boolean(detentsProp()) && detentsProp().length > 0)
+const detent = state<SheetDetent>('large')
+
+const sheetRoot = useRef('nativeSheet')
+const panel = useRef('nativeSheetPanel')
+const grabber = useRef('nativeSheetGrabber')
+const header = useRef('nativeSheetHeader')
+
+let releaseBackground: (() => void) | null = null
+let putBack: (() => void) | null = null
+let putBackTimer: ReturnType<typeof setTimeout> | null = null
+let previousFocus: HTMLElement | null = null
+let carded = false
+let stopDrag: (() => void) | null = null
+let openedOn = ''
+
+function currentPath(): string {
+  return root()?.ownerDocument.defaultView?.location.pathname ?? ''
+}
+
+function root(): HTMLElement | null {
+  return sheetRoot.current as HTMLElement | null
+}
+
+function present(): void {
+  const element = root()
+  if (!element || releaseBackground) return
+  if (putBackTimer) clearTimeout(putBackTimer)
+  putBackTimer = null
+  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.
+  putBack ??= liftToBody(element)
+  releaseBackground = lockBackground(element)
+  openedOn = currentPath()
+  coverTabBar(element, true)
+  void nextTick(() => (panel.current as HTMLElement | null)?.focus())
+}
+
+function dismissed(): void {
+  const element = root()
+  if (element) coverTabBar(element, false)
+  releaseBackground?.()
+  releaseBackground = null
+  previousFocus?.focus?.()
+  previousFocus = null
+  // Back where it was written once it has slid away.
+  putBackTimer = setTimeout(() => {
+    putBackTimer = null
+    putBack?.()
+    putBack = null
+  }, 420)
+}
 
 let wasOpen = false
 effect(() => {
   const isOpen = open()
-  if (isOpen && !wasOpen) void haptics.impact('light')
+  if (isOpen && !wasOpen) present()
+  else if (!isOpen && wasOpen) dismissed()
   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.
+effect(() => {
+  const element = root()
+  const want = open() && hasDetents() && detent() === 'large'
+  if (!element || want === carded) return
+  carded = want
+  presentPageAsCard(element.ownerDocument, want)
+})
+
 function close(): void {
   open.set(false)
   emit('close')
 }
 
+onMount(() => {
+  const sheetPanel = panel.current as HTMLElement | null
+  if (!sheetPanel) return
+  const handles = [grabber.current, header.current].filter(Boolean) as HTMLElement[]
+  stopDrag = observeSheetDrag({
+    panel: sheetPanel,
+    handles,
+    detents: () => detents(),
+    detent: () => detent(),
+    onSettle: (to) => {
+      if (to === 'dismiss') close()
+      else detent.set(to)
+    },
+  })
+  if (open()) present()
+})
+
+onDestroy(() => {
+  stopDrag?.()
+  releaseBackground?.()
+  const element = root()
+  if (element && open()) coverTabBar(element, false)
+  if (carded && element) presentPageAsCard(element.ownerDocument, false)
+  if (putBackTimer) clearTimeout(putBackTimer)
+  putBack?.()
+})
+
+// The router moved to another screen while this one's sheet was up.
+useEventListener('stx:navigate', (event: CustomEvent<{ url?: string }>) => {
+  if (!open()) return
+  const location = root()?.ownerDocument.defaultView?.location
+  const to = event.detail?.url ? new URL(event.detail.url, location?.href).pathname : currentPath()
+  if (to !== openedOn) close()
+})
+
 useEventListener('keydown', (event: KeyboardEvent) => {
-  if (event.key === 'Escape' && open()) close()
+  if (!open()) return
+  if (event.key === 'Escape') close()
+  else if (panel.current) trapFocus(panel.current as HTMLElement, event)
 })
+
+const sheetClass = derived(() => `${open() ? 'is-open' : ''}${hasDetents() ? ' has-detents' : ''}${detent() === 'medium' ? ' is-medium' : ''}`.trim())
 </script>
 
-<div class="native-sheet" :class="open() ? 'is-open' : ''" :aria-hidden="open() ? 'false' : 'true'">
+<div ref="nativeSheet" class="native-sheet" :class="sheetClass()" :aria-hidden="open() ? 'false' : 'true'" data-native-sheet>
   <div class="native-sheet-backdrop" @click="close()"></div>
-  <section class="native-sheet-panel" role="dialog" aria-modal="true" :aria-label="title()">
-    <span aria-hidden="true" class="native-sheet-grabber"></span>
-    <header class="native-sheet-header">
+  <section ref="nativeSheetPanel" class="native-sheet-panel" role="dialog" aria-modal="true" :aria-label="title()" tabindex="-1">
+    <div ref="nativeSheetGrabber" class="native-sheet-grabber-area">
+      <span aria-hidden="true" class="native-sheet-grabber"></span>
+    </div>
+    <header ref="nativeSheetHeader" class="native-sheet-header">
       <h2 class="native-sheet-title">{{ title() }}</h2>
       <button type="button" class="native-sheet-done" @click="close()">{{ doneLabel() }}</button>
     </header>
@@ -51,6 +178,8 @@ useEventListener('keydown', (event: KeyboardEvent) => {
     z-index: 70;
     visibility: hidden;
     pointer-events: none;
+    font-size: var(--native-font-size, 17px);
+    -webkit-tap-highlight-color: transparent;
   }
 
   .native-sheet.is-open { visibility: visible; pointer-events: auto; }
@@ -63,7 +192,8 @@ useEventListener('keydown', (event: KeyboardEvent) => {
     transition: opacity 240ms ease;
   }
 
-  .native-sheet.is-open .native-sheet-backdrop { opacity: 1; }
+  /* Dragged, the dimming follows the panel (--native-sheet-presence, 1 to 0). */
+  .native-sheet.is-open .native-sheet-backdrop { opacity: var(--native-sheet-presence, 1); }
 
   .native-sheet-panel {
     position: absolute;
@@ -75,20 +205,41 @@ useEventListener('keydown', (event: KeyboardEvent) => {
     max-height: calc(100dvh - env(safe-area-inset-top, 0px) - 1rem);
     padding-bottom: env(safe-area-inset-bottom, 0px);
     border-radius: 1.25rem 1.25rem 0 0;
+    outline: none;
     background: var(--native-sheet-background, rgb(248 250 252));
     box-shadow: 0 -12px 40px rgb(2 6 23 / 0.18);
     transform: translateY(105%);
-    transition: transform 320ms cubic-bezier(0.32, 0.72, 0, 1);
+    transition: transform 380ms cubic-bezier(0.32, 0.72, 0, 1);
+    touch-action: pan-y;
   }
 
   .dark .native-sheet-panel { background: var(--native-sheet-background-dark, rgb(15 23 42)); }
   .native-sheet.is-open .native-sheet-panel { transform: none; }
 
+  /* Following the finger: no easing between where it was and where it is. */
+  .native-sheet-panel.is-dragging { transition: none; }
+
+  /* A sheet with detents is full height, and rests with half the screen's
+     worth showing at medium. */
+  .native-sheet.has-detents .native-sheet-panel {
+    height: calc(100dvh - env(safe-area-inset-top, 0px) - 0.625rem);
+    max-height: none;
+  }
+
+  .native-sheet.is-open.is-medium .native-sheet-panel { transform: translateY(calc(100% - 50dvh)); }
+
+  /* The grabber's area is a handle, generous for a thumb. */
+  .native-sheet-grabber-area {
+    display: flex;
+    justify-content: center;
+    padding: 0.4rem 0 0.15rem;
+    touch-action: none;
+    cursor: grab;
+  }
+
   .native-sheet-grabber {
-    align-self: center;
     width: 2.25rem;
     height: 0.3rem;
-    margin-top: 0.4rem;
     border-radius: 999px;
     background: rgb(148 163 184 / 0.55);
   }
@@ -99,17 +250,19 @@ useEventListener('keydown', (event: KeyboardEvent) => {
     align-items: center;
     justify-content: space-between;
     padding: 0.5rem 1rem 0.25rem;
+    touch-action: none;
   }
 
-  .native-sheet-title { font-size: 1.0625rem; font-weight: 600; }
+  .native-sheet-title { font-size: 1em; font-weight: 600; }
 
   .native-sheet-done {
     min-height: 2.75rem;
     border: 0;
     color: var(--native-accent, rgb(37 99 235));
     background: transparent;
-    font-size: 1.0625rem;
+    font-size: 1em;
     font-weight: 600;
+    touch-action: manipulation;
   }
 
   .dark .native-sheet-done { color: var(--native-accent-dark, rgb(96 165 250)); }
@@ -120,10 +273,33 @@ useEventListener('keydown', (event: KeyboardEvent) => {
     overscroll-behavior: contain;
   }
 
+  .native-sheet.has-detents .native-sheet-body { flex: 1; }
+
+  /* The page behind a full-height sheet at large: pressed back into a card
+     with rounded corners, centred on what was in view, on black. The
+     content scales rather than the shell, whose fixed tab bar a transform
+     would unpin. */
+  .native-app-content {
+    transition: transform 380ms cubic-bezier(0.32, 0.72, 0, 1), border-radius 380ms cubic-bezier(0.32, 0.72, 0, 1);
+  }
+
+  :root[data-native-sheet-card] body { background: #000; }
+
+  :root[data-native-sheet-card] .native-app-content {
+    overflow: hidden;
+    border-radius: 0.75rem;
+    transform: scale(0.93);
+    transform-origin: 50% var(--native-sheet-card-origin, 50vh);
+  }
+
   @media (prefers-reduced-motion: reduce) {
-    .native-sheet-backdrop, .native-sheet-panel { transition: none; }
+    .native-sheet-backdrop, .native-sheet-panel, .native-app-content { transition: none; }
+    :root[data-native-sheet-card] .native-app-content { transform: none; border-radius: 0; }
   }
 
+  :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

package/resources/components/NativeSymbol.stx

@@ -0,0 +1,121 @@
+<script server>
+interface NativeSymbolProps {
+  /** The SF Symbol, e.g. `chevron.backward`. */
+  name: string
+  /** The Iconify class drawn where there are no SF Symbols (a browser, an older shell). */
+  icon?: string
+  /** The point size; the surrounding text's size when left out. */
+  size?: number
+  weight?: 'ultralight' | 'thin' | 'light' | 'regular' | 'medium' | 'semibold' | 'bold' | 'heavy' | 'black'
+  /** What the symbol says, for a symbol that stands alone. Decorative when left out. */
+  label?: string
+  class?: string
+}
+
+// The caller's classes are rendered here too, so the symbol has its size
+// from the first paint rather than once the page has run.
+const { name = '', icon = '', label = '', class: extraClass = '' } = defineProps<NativeSymbolProps>()
+
+// The common symbols' Iconify stand-ins, written out here so the stylesheet
+// generator sees every class. Anything else names its own with `icon`.
+const standIns: Record<string, string> = {
+  'chevron.backward': 'i-lucide-chevron-left',
+  'chevron.left': 'i-lucide-chevron-left',
+  'chevron.forward': 'i-lucide-chevron-right',
+  'chevron.right': 'i-lucide-chevron-right',
+  'chevron.down': 'i-lucide-chevron-down',
+  'chevron.up': 'i-lucide-chevron-up',
+  'xmark': 'i-lucide-x',
+  'plus': 'i-lucide-plus',
+  'minus': 'i-lucide-minus',
+  'checkmark': 'i-lucide-check',
+  'ellipsis': 'i-lucide-ellipsis',
+  'ellipsis.circle': 'i-lucide-circle-ellipsis',
+  'square.and.arrow.up': 'i-lucide-share',
+  'trash': 'i-lucide-trash-2',
+  'pencil': 'i-lucide-pencil',
+  'doc.on.doc': 'i-lucide-copy',
+  'link': 'i-lucide-link',
+  'magnifyingglass': 'i-lucide-search',
+  'gearshape': 'i-lucide-settings',
+  'person.crop.circle': 'i-lucide-circle-user',
+  'bell': 'i-lucide-bell',
+  'heart': 'i-lucide-heart',
+  'star': 'i-lucide-star',
+  'bookmark': 'i-lucide-bookmark',
+  'calendar': 'i-lucide-calendar',
+  'house': 'i-lucide-house',
+  'info.circle': 'i-lucide-info',
+  'arrow.clockwise': 'i-lucide-rotate-cw',
+  'play.fill': 'i-lucide-play',
+  'pause.fill': 'i-lucide-pause',
+}
+const standIn = icon || standIns[name] || 'i-lucide-circle'
+const classes = ['native-symbol', standIn, extraClass].filter(Boolean).join(' ')
+</script>
+
+<script client>
+import type { SymbolOptions } from '@stacksjs/mobile'
+import { symbols } from '@stacksjs/mobile'
+
+/**
+ * An SF Symbol, drawn by the phone (`craft.symbols.image`) and painted in the
+ * text colour like any icon, so it follows the theme and the tint. Until the
+ * shell has drawn it, and wherever it cannot, the Iconify stand-in shows.
+ * Drawn symbols are kept in memory, so the next screen's bar has its chevron
+ * from the first frame.
+ */
+const symbolName = useReactiveProp<string>('name', '')
+const size = useReactiveProp<number>('size', 0)
+const weight = useReactiveProp<SymbolOptions['weight']>('weight', 'regular')
+const className = useReactiveProp<string>('class', '')
+const image = state<string | null>(null)
+
+effect(() => {
+  const name = symbolName()
+  if (!name) return
+  const options: SymbolOptions = { pointSize: Number(size()) || 17, weight: weight() }
+  const known = symbols.cached(name, options)
+  if (known !== undefined) {
+    image.set(known)
+    return
+  }
+  void symbols.image(name, options).then((url) => {
+    if (symbolName() === name) image.set(url)
+  })
+})
+
+// One class binding: the drawn symbol and the caller's classes together.
+const symbolClass = derived(() => `${image() ? 'is-symbol ' : ''}${className()}`.trim())
+const symbolStyle = derived(() => {
+  const px = Number(size()) || 0
+  return `${image() ? `--native-symbol:url("${image()}");` : ''}${px ? `font-size:${px}px;` : ''}`
+})
+</script>
+
+@if(label)
+  <i class="{{ classes }}" :class="symbolClass()" :style="symbolStyle()" role="img" aria-label="{{ label }}" data-native-symbol="{{ name }}"></i>
+@else
+  <i class="{{ classes }}" :class="symbolClass()" :style="symbolStyle()" aria-hidden="true" data-native-symbol="{{ name }}"></i>
+@endif
+
+<style>
+  /* stx's box around the component steps aside, so the symbol sits in the
+     line (or the flex row) it was written in. */
+  [data-stx-scope]:has(> .native-symbol) { display: contents; }
+
+  .native-symbol {
+    display: inline-block;
+    flex-shrink: 0;
+    width: 1em;
+    height: 1em;
+    vertical-align: -0.125em;
+  }
+
+  /* The drawn symbol as a mask over the text colour, in place of the stand-in. */
+  .native-symbol.is-symbol {
+    background-color: currentColor;
+    -webkit-mask: var(--native-symbol) center / contain no-repeat;
+    mask: var(--native-symbol) center / contain no-repeat;
+  }
+</style>

package/resources/components/NativeTabBar.stx

@@ -7,24 +7,36 @@ const { label = 'App navigation' } = defineProps<NativeTabBarProps>()
 </script>
 
 <script client>
-import { haptics, mirrorTabBar } from '@stacksjs/mobile'
+import { handleTabReselect, haptics, mirrorTabBar } from '@stacksjs/mobile'
 
 // Inside Craft's iOS shell the phone draws this bar natively (Liquid Glass on
 // iOS 26 and later) and these links stay as its model: the router keeps the
 // current one marked, and a native tap comes back as a click on one of them.
+//
+// The tabs are the stx router's (`data-stx-nav="tab"` on each link): each
+// keeps its own screens and history, a switch adds no back entry, and
+// choosing the current tab again scrolls it to the top, then pops it to its
+// root, announcing `stx:tabreselect`. A native tap reaches the router's
+// selectTab(). handleTabReselect covers a router that predates tabs.
 const bar = useRef('nativeTabBar')
 let mirrored = false
 let stopMirror: (() => void) | null = null
+let stopReselect: (() => void) | null = null
 onMount(() => {
   const nav = bar.current as HTMLElement | null
   if (!nav) return
   stopMirror = mirrorTabBar(nav)
   mirrored = stopMirror !== null
+  stopReselect = handleTabReselect(nav)
+})
+onDestroy(() => {
+  stopMirror?.()
+  stopReselect?.()
 })
-onDestroy(() => stopMirror?.())
 
 function selectTab(): void {
-  // The native bar has already played its own.
+  // Only the page's own bar: the phone's native bar plays its own haptic,
+  // and a tap on it comes back without one.
   if (!mirrored) void haptics.selection()
 }
 </script>

package/resources/components/NativeTabItem.stx

@@ -32,7 +32,10 @@ const hasBadge = badge !== '' && badge !== 0 && badge !== '0'
      swapped without the router's cross-fade, which iOS never draws between
      tabs (it read as a quarter-second lag on every tap). `data-native-tab`
      and `data-native-tab-symbol` describe the tab to the phone's native bar
-     (@stacksjs/mobile mirrorTabBar). -->
+     (@stacksjs/mobile mirrorTabBar). `data-stx-nav="tab"`: the stx router
+     treats it as a tab, with its own retained screens and history, no back
+     entry for a switch, and re-selection scrolling to the top, then popping
+     to the tab's root. -->
 <StxLink
   to="{{ href }}"
   aria-label="{{ label }}"
@@ -42,6 +45,7 @@ const hasBadge = badge !== '' && badge !== 0 && badge !== '0'
   draggable="false"
   data-stx-prefetch="eager"
   data-stx-transition="none"
+  data-stx-nav="tab"
   data-native-tab="{{ label }}"
   data-native-tab-symbol="{{ symbol }}"
 >

package/resources/components/index.ts

@@ -12,7 +12,9 @@ export { default as DashboardNavbar } from './Dashboard/Navbar.stx'
 export * from './Dashboard'
 export { default as Audio } from './Audio.stx'
 export { default as Image } from './Image.stx'
+export { default as NativeActionSheet } from './NativeActionSheet.stx'
 export { default as NativeAppShell } from './NativeAppShell.stx'
+export { default as NativeContextMenu } from './NativeContextMenu.stx'
 export { default as NativeHealthButton } from './NativeHealthButton.stx'
 export { default as NativeNavBar } from './NativeNavBar.stx'
 export { default as NativeNetworkBanner } from './NativeNetworkBanner.stx'
@@ -22,6 +24,7 @@ export { default as NativePullToRefresh } from './NativePullToRefresh.stx'
 export { default as NativeSegmentedControl } from './NativeSegmentedControl.stx'
 export { default as NativeShareButton } from './NativeShareButton.stx'
 export { default as NativeSheet } from './NativeSheet.stx'
+export { default as NativeSymbol } from './NativeSymbol.stx'
 export { default as NativeTabBar } from './NativeTabBar.stx'
 export { default as NativeTabItem } from './NativeTabItem.stx'
 export { default as Video } from './Video.stx'