@stacksjs/defaults 0.75.22 → 0.75.24

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

@@ -1,6 +1,6 @@
 ---
 name: stacks-dashboard
-description: Use when building or customizing the Stacks admin dashboard, including dashboard pages, model management views, analytics widgets, commerce dashboards, content management, settings panels, deployment monitoring, job/queue management, or the 401 built-in dashboard components. Covers the dashboard system at storage/framework/defaults/.
+description: Use when building or customizing the Stacks admin dashboard, including dashboard pages, model management views, analytics widgets, commerce dashboards, content management, settings panels, deployment monitoring, job/queue management, or the 405 built-in dashboard components. Covers the dashboard system at storage/framework/defaults/.
 license: MIT
 compatibility: Bun >= 1.3.0, TypeScript
 allowed-tools: Read Edit Write Bash Grep Glob
@@ -8,7 +8,7 @@ allowed-tools: Read Edit Write Bash Grep Glob
 
 # Stacks Dashboard
 
-The Stacks admin dashboard provides a full-featured admin panel with 100+ route views, 401 components, and a multi-section layout.
+The Stacks admin dashboard provides a full-featured admin panel with 100+ route views, 405 components, and a multi-section layout.
 
 ## Key Paths
 - Dashboard components: `storage/framework/defaults/resources/components/Dashboard/`

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

@@ -122,15 +122,43 @@ supported web APIs provide fallback behavior outside a native host.
 - `<NativeNetworkBanner>` reflects native connectivity changes and announces offline state accessibly.
 - `<NativePermissionButton>` wraps permission status, requests, haptics, and the native Settings escape hatch.
 - `<NativeHealthButton>` requests the minimal Apple Health or Android Health Connect grants.
+- `<NativeNavBar>` is the iOS navigation bar: a large title that collapses into
+  the bar as the page scrolls, a back button (`back="/parent"`) that goes back
+  through history when the app pushed the screen, and `leading` / `actions`
+  slots. Pass `:large="false"` on a pushed screen; `title` is reactive.
+- `<NativePullToRefresh @refresh="reload">` refreshes the page when pulled from
+  its top. The event carries `done()`: call it when the new data is in.
+- `<NativeSegmentedControl :options="[...]" v-model:value="range">` switches
+  between views of one screen, with selection haptics.
+- `<NativeSheet v-model:open="editing" title="…">` raises a bottom sheet for a
+  task that belongs to the screen, above the tab bar.
+
+`<NativeTabItem match="/m/workout">` keeps a tab lit on the detail screens
+opened from it. A tab bar is a `<nav>`, where a link is otherwise current only
+on its own page.
 
 Use Iconify classes for tab icons. Keep native operations inside reusable
 components or TypeScript composables, never through `window.*` in an STX
 script.
 
+## Appearance and navigation
+
+`ios.appearance: 'system'` follows the phone's Light/Dark setting (and the
+page's `prefers-color-scheme` with it), with a status bar that reads on either;
+`'light'` and `'dark'` pin one. `ios.backgroundColorDark` colours the launch
+screen and webview in Dark Mode. `ios.swipeNavigation: true` lets an edge swipe
+go back through the page's history, pushed routes included.
+
+Decide native-only chrome with `await whenNativeMobile()`, not
+`isNativeMobile()` at setup: Craft installs its bridge after the page starts.
+
 ## Health and watch surfaces
 
 Enable `healthKit` on iOS or `healthConnect` on Android, then use the shared
-`health` service to request only the record types the product needs. Completed
+`health` service to request only the record types the product needs. On iOS,
+`health.getWorkouts()` lists Apple Health workouts (keyed on HealthKit's UUID)
+and `health.getDailyStatistics(type)` returns one value per day for steps,
+energy, distance, heart rate, resting heart rate, HRV, weight and sleep. Completed
 recordings can be written back with `health.saveWorkout(...)`; treat permission
 revocation as a normal runtime state and never block saving the application's
 own activity when a health write fails.

package/ide/vscode/package.json

@@ -2,7 +2,7 @@
   "publisher": "Stacks",
   "name": "vscode-stacks",
   "displayName": "Stacks",
-  "version": "0.75.22",
+  "version": "0.75.24",
   "description": "A modern Stacks development environment.",
   "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.22",
+  "version": "0.75.24",
   "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.27",
-    "@stacksjs/mobile": "^0.75.22",
+    "@stacksjs/mobile": "^0.75.24",
     "@stacksjs/sanitizer": "^0.2.113",
     "ts-qr-codes": "^0.1.8"
   }

package/resources/components/NativeAppShell.stx

@@ -2,16 +2,49 @@
 interface NativeAppShellProps {
   class?: string
   tabBar?: boolean
+  /** Open the app's deep links (`myapp://path`, or a universal link) at their path. */
+  deepLinks?: boolean
 }
 
 const { tabBar = false } = defineProps<NativeAppShellProps>()
 </script>
 
 <script client>
+import { deepLinks as deepLinkService, device, followDeepLinks, isNativeMobile, whenNativeMobile } from '@stacksjs/mobile'
+
 const className = useReactiveProp<string>('class', '')
+// A bare attribute arrives as an empty string.
+const deepLinkProp = useReactiveProp<unknown>('deepLinks', false)
+let stopDeepLinks: (() => void) | null = null
+onMount(() => {
+  const on = deepLinkProp()
+  if (on === true || on === '' || on === 'true')
+    stopDeepLinks = followDeepLinks(path => navigate(path), deepLinkService)
+})
+onDestroy(() => stopDeepLinks?.())
+
+// Asked twice on purpose. Craft installs its bridge after the document starts,
+// so on a phone the answer at setup is often `false`, and every rule hanging
+// off `.native-mobile` would never apply. whenNativeMobile() answers once the
+// host is recognisable or the bridge is ready.
+const nativeMobile = state(isNativeMobile())
+const platform = state('')
+void whenNativeMobile().then((native) => {
+  nativeMobile.set(native)
+  if (native) platform.set(device.isIOS() ? 'ios' : device.isAndroid() ? 'android' : '')
+})
+
+// One class binding: a second binding on the same element overwrites the
+// first's classes whenever it runs.
+const shellClass = derived(() => `${nativeMobile() ? 'native-mobile ' : ''}${className()}`.trim())
 </script>
 
-<div data-native-app-shell class="native-app-shell" :class="className()">
+<div
+  data-native-app-shell
+  class="native-app-shell"
+  :class="shellClass()"
+  :data-native-platform="platform()"
+>
   <!-- The application layout owns the single <main> landmark. This shell is
        structural chrome; making it another <main> creates invalid nested
        landmarks and gives both elements the router's stx-content view-
@@ -32,6 +65,8 @@ const className = useReactiveProp<string>('class', '')
     --native-safe-area-right: env(safe-area-inset-right, 0px);
     --native-safe-area-bottom: env(safe-area-inset-bottom, 0px);
     --native-safe-area-left: env(safe-area-inset-left, 0px);
+    /* The height a fixed tab bar takes, which content and sticky footers clear. */
+    --native-tab-bar-height: 0px;
 
     min-height: 100dvh;
     color: inherit;
@@ -68,27 +103,41 @@ const className = useReactiveProp<string>('class', '')
    * footer that a visitor could scroll into, which reads as a broken page.
    *
    * Scoped to below `md` (768px, the framework's own breakpoint and where
-   * NativeTabBar stops being shown) so the clearance exists exactly when the
-   * thing it is clearing does.
+   * NativeTabBar stops being shown) — or to the phone app at any width — so
+   * the clearance exists exactly when the thing it is clearing does.
    */
   @media (max-width: 767.98px) {
+    .native-app-shell:has(.native-app-tab-slot) { --native-tab-bar-height: 4.5rem; }
     .native-app-shell:has(.native-app-tab-slot) .native-app-content {
       padding-bottom: calc(5rem + var(--native-safe-area-bottom));
     }
   }
 
+  .native-app-shell.native-mobile:has(.native-app-tab-slot) { --native-tab-bar-height: 4.5rem; }
+  .native-app-shell.native-mobile:has(.native-app-tab-slot) .native-app-content {
+    padding-bottom: calc(5rem + var(--native-safe-area-bottom));
+  }
+
   .native-app-sticky-top {
     top: var(--native-safe-area-top);
   }
 
+  /* No inset padding here: the bar inside pads itself, so its background runs
+     under the home indicator instead of leaving a see-through strip there. */
   .native-app-tab-slot {
     position: fixed;
     right: 0;
     bottom: 0;
     left: 0;
     z-index: 30;
-    padding-right: var(--native-safe-area-right);
-    padding-bottom: var(--native-safe-area-bottom);
-    padding-left: var(--native-safe-area-left);
+  }
+
+  /* A phone app does not select its chrome on a long press, or flash it grey
+     on a tap. Text inside the content is left selectable. */
+  .native-app-shell.native-mobile .native-app-tab-slot,
+  .native-app-shell.native-mobile [data-native-nav-bar] {
+    -webkit-user-select: none;
+    user-select: none;
+    -webkit-tap-highlight-color: transparent;
   }
 </style>

package/resources/components/NativeComponents.test.ts

@@ -0,0 +1,53 @@
+import { describe, expect, it } from 'bun:test'
+import { readFileSync } from 'node:fs'
+import { join } from 'node:path'
+
+const read = (name: string) => readFileSync(join(import.meta.dir, `${name}.stx`), 'utf8')
+
+describe('Native components', () => {
+  it('decides native-only chrome once the bridge can answer', () => {
+    const shell = read('NativeAppShell')
+    expect(shell).toContain('whenNativeMobile()')
+    // One class binding: a second one would overwrite the first.
+    expect(shell.match(/:class=/g)?.length).toBe(1)
+    // Deep links are opt-in, and open at their path through the router.
+    expect(shell).toContain('followDeepLinks(path => navigate(path), deepLinkService)')
+  })
+
+  it('keeps a tab lit on the paths it names, and never drags a tab', () => {
+    const item = read('NativeTabItem')
+    expect(item).toContain('activeMatch="{{ match }}"')
+    expect(item).toContain('draggable="false"')
+  })
+
+  it('shows the offline banner by class, so it can come back', () => {
+    const banner = read('NativeNetworkBanner')
+    expect(banner).not.toContain(':if="!connected()"')
+    expect(banner).toContain('native-network-banner--quiet')
+  })
+
+  it('backs out through history, and sticks within the page rather than its wrapper', () => {
+    const bar = read('NativeNavBar')
+    expect(bar).toContain('if (goBack()) event.preventDefault()')
+    expect(bar).toContain('[data-stx-scope]:has(> .native-nav) { display: contents; }')
+    expect(bar).toContain("useReactiveProp<string>('title', '')")
+  })
+
+  it('lifts an open sheet 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'")
+  })
+
+  it('refreshes through the shared gesture and hands the page done()', () => {
+    const refresh = read('NativePullToRefresh')
+    expect(refresh).toContain('observePullToRefresh(')
+    expect(refresh).toContain("emit('refresh', { done: finish })")
+  })
+
+  it('reports a segment change with a selection haptic', () => {
+    const control = read('NativeSegmentedControl')
+    expect(control).toContain('haptics.selection()')
+    expect(control).toContain("emit('change', value)")
+  })
+})

package/resources/components/NativeNavBar.stx

@@ -0,0 +1,151 @@
+<script>
+interface NativeNavBarProps {
+  /** The screen's name: display-sized under the bar, then in the bar once scrolled. */
+  title?: string
+  /** A parent to go back to. History is used when the app pushed this screen. */
+  back?: string
+  backLabel?: string
+  /** `false` for a pushed screen: the title sits in the bar from the start. */
+  large?: boolean
+}
+
+const { title = '', back = '', backLabel = 'Back', large = true } = defineProps<NativeNavBarProps>()
+</script>
+
+<script client>
+import { goBack, haptics, observePageScroll } from '@stacksjs/mobile'
+
+const isLarge = useReactiveProp<boolean>('large', true)
+// Reactive, so a screen whose name arrives with its data can pass it in.
+const navTitle = useReactiveProp<string>('title', '')
+const scrolled = state(false)
+let stopScroll: (() => void) | null = null
+
+onMount(() => {
+  // The large title is about 44px tall; past it, its name belongs in the bar.
+  stopScroll = observePageScroll(offset => scrolled.set(offset > 40))
+})
+onDestroy(() => stopScroll?.())
+
+const barClass = derived(() => {
+  const collapsed = !isLarge() || scrolled()
+  return `native-nav-bar${collapsed ? ' is-collapsed' : ''}${scrolled() ? ' is-scrolled' : ''}`
+})
+
+function tapBack(event: MouseEvent): void {
+  void haptics.selection()
+  if (goBack()) event.preventDefault()
+}
+</script>
+
+<!-- `display: contents` on this box and on stx's own wrapper: a sticky element
+     sticks within its parent, and either box would give the bar no room. -->
+<div class="native-nav" data-native-nav-bar>
+  <header :class="barClass()">
+    <div class="native-nav-side">
+      @if(back)
+        <a href="{{ back }}" class="native-nav-back" aria-label="{{ backLabel }}" draggable="false" @click="tapBack">
+          <i aria-hidden="true" class="i-lucide-chevron-left native-nav-back-icon"></i>
+          <span>{{ backLabel }}</span>
+        </a>
+      @endif
+      <slot name="leading" />
+    </div>
+    <p class="native-nav-title" aria-hidden="{{ large ? 'true' : 'false' }}">{{ navTitle() }}</p>
+    <div class="native-nav-side native-nav-actions">
+      <slot name="actions" />
+    </div>
+  </header>
+  @if(large)
+    <h1 class="native-nav-large-title" :class="navTitle() ? '' : 'is-empty'">{{ navTitle() }}</h1>
+  @endif
+  <slot />
+</div>
+
+<style>
+  /* The element stx wraps each component in is a box too, as tall as the bar
+     and its title; the bar stuck inside it and scrolled away with the title.
+     Both boxes step aside so the bar sticks to the page. */
+  .native-nav,
+  [data-stx-scope]:has(> .native-nav) { display: contents; }
+
+  .native-nav-bar {
+    position: sticky;
+    top: env(safe-area-inset-top, 0px);
+    z-index: 30;
+    display: grid;
+    grid-template-columns: minmax(0, 1fr) auto minmax(0, 1fr);
+    gap: 0.5rem;
+    align-items: center;
+    min-height: 2.75rem;
+    padding: 0 0.75rem;
+    border-bottom: 1px solid transparent;
+    transition: background-color 180ms ease, border-color 180ms ease;
+  }
+
+  .native-nav-bar.is-scrolled {
+    border-color: var(--native-bar-border, rgb(148 163 184 / 0.25));
+    background: var(--native-bar-background, rgb(248 250 252 / 0.86));
+    backdrop-filter: blur(20px) saturate(180%);
+    -webkit-backdrop-filter: blur(20px) saturate(180%);
+  }
+
+  .dark .native-nav-bar.is-scrolled {
+    border-color: var(--native-bar-border-dark, rgb(51 65 85 / 0.6));
+    background: var(--native-bar-background-dark, rgb(2 6 23 / 0.86));
+  }
+
+  .native-nav-side { display: flex; gap: 0.25rem; align-items: center; min-width: 0; }
+  .native-nav-actions { justify-content: flex-end; }
+
+  .native-nav-title {
+    max-width: 60vw;
+    overflow: hidden;
+    font-size: 1.0625rem;
+    font-weight: 600;
+    text-overflow: ellipsis;
+    white-space: nowrap;
+    opacity: 0;
+    transform: translateY(4px);
+    transition: opacity 180ms ease, transform 180ms ease;
+  }
+
+  .native-nav-bar.is-collapsed .native-nav-title { opacity: 1; transform: none; }
+
+  .native-nav-back {
+    display: inline-flex;
+    gap: 0.1rem;
+    align-items: center;
+    min-height: 2.75rem;
+    margin-left: -0.4rem;
+    padding-right: 0.5rem;
+    color: var(--native-accent, rgb(37 99 235));
+    font-size: 1.0625rem;
+    text-decoration: none;
+    -webkit-touch-callout: none;
+  }
+
+  .dark .native-nav-back { color: var(--native-accent-dark, rgb(96 165 250)); }
+  .native-nav-back:active { opacity: 0.55; }
+  .native-nav-back-icon { width: 1.6rem; height: 1.6rem; }
+
+  .native-nav-large-title.is-empty { display: none; }
+
+  .native-nav-large-title {
+    margin: 0.125rem 0 0.5rem;
+    padding: 0 1rem;
+    font-size: 2.125rem;
+    font-weight: 700;
+    line-height: 1.15;
+    letter-spacing: -0.02em;
+  }
+
+  @media (prefers-reduced-motion: reduce) {
+    .native-nav-bar, .native-nav-title { transition: none; }
+  }
+
+  @media (prefers-reduced-transparency: reduce) {
+    .native-nav-bar.is-scrolled { backdrop-filter: none; -webkit-backdrop-filter: none; background: var(--native-bar-solid, rgb(248 250 252)); }
+    .dark .native-nav-bar.is-scrolled { background: var(--native-bar-solid-dark, rgb(2 6 23)); }
+  }
+</style>

package/resources/components/NativeNetworkBanner.stx

@@ -19,12 +19,18 @@ onMount(() => {
 onDestroy(() => removeListener?.())
 </script>
 
+<!--
+  Visibility is a class, not `:if`. The banner starts connected, and a
+  component's `:if` that removed it on the first pass did not bring it back
+  inside Craft's WebView when the signal changed, so the app never said it had
+  gone offline. Both states go through the one `:class`: a second class
+  binding on the element would overwrite the first.
+-->
 <div
-  :if="!connected()"
   role="status"
   aria-live="polite"
   class="native-network-banner"
-  :class="className()"
+  :class="(connected() ? 'native-network-banner--quiet ' : '') + className()"
 >
   <i aria-hidden="true" class="h-4 w-4 i-hugeicons-wifi-disconnected-01"></i>
   <span>{{ offlineLabel() }}</span>
@@ -47,6 +53,9 @@ onDestroy(() => removeListener?.())
     font-weight: 600;
   }
 
+  /* After the base rule and doubled up, so it wins over `display: flex`. */
+  .native-network-banner.native-network-banner--quiet { display: none; }
+
   @media (prefers-color-scheme: dark) {
     .native-network-banner { color: rgb(254 243 199); background: rgb(120 53 15 / 0.96); }
   }

package/resources/components/NativePullToRefresh.stx

@@ -0,0 +1,99 @@
+<script client>
+import { observePullToRefresh } from '@stacksjs/mobile'
+
+/**
+ * Pull the page down from its top to refresh it.
+ *
+ * On iOS the pull rides the system's own rubber band, so it feels like a
+ * native list; elsewhere the finger's travel drives it. Crossing the threshold
+ * taps the haptic engine once. The `refresh` event carries `done()`: call it
+ * when the new data is in, and the spinner goes away. A handler that never
+ * calls it is let go after 15 seconds.
+ */
+const emit = defineEmits()
+const threshold = useReactiveProp<number>('threshold', 72)
+const label = useReactiveProp<string>('label', 'Refreshing')
+const distance = state(0)
+const armed = state(false)
+const refreshing = state(false)
+let stop: (() => void) | null = null
+
+onMount(() => {
+  stop = observePullToRefresh({
+    threshold: threshold(),
+    onPull: (pulled, isArmed) => {
+      distance.set(pulled)
+      armed.set(isArmed)
+    },
+    onRefresh: () => new Promise<void>((resolve) => {
+      refreshing.set(true)
+      const finish = (): void => {
+        clearTimeout(timer)
+        refreshing.set(false)
+        resolve()
+      }
+      const timer = setTimeout(finish, 15000)
+      emit('refresh', { done: finish })
+    }),
+  })
+})
+onDestroy(() => stop?.())
+
+const indicatorClass = derived(() => {
+  const visible = refreshing() || distance() > 8
+  return `native-ptr-indicator${visible ? ' is-visible' : ''}${refreshing() ? ' is-refreshing' : ''}${armed() ? ' is-armed' : ''}`
+})
+const indicatorStyle = derived(() => {
+  if (refreshing()) return ''
+  const progress = Math.min(1, distance() / threshold())
+  return `opacity:${progress};transform:translateX(-50%) rotate(${Math.round(progress * 270)}deg) scale(${0.6 + progress * 0.4})`
+})
+</script>
+
+<div class="native-ptr">
+  <div :class="indicatorClass()" :style="indicatorStyle()" role="status" :aria-label="refreshing() ? label() : ''">
+    <i aria-hidden="true" class="i-lucide-loader-circle native-ptr-icon"></i>
+  </div>
+  <slot />
+</div>
+
+<style>
+  .native-ptr { position: relative; }
+
+  .native-ptr-indicator {
+    position: fixed;
+    top: calc(env(safe-area-inset-top, 0px) + 3.25rem);
+    left: 50%;
+    z-index: 25;
+    display: flex;
+    align-items: center;
+    justify-content: center;
+    width: 2.25rem;
+    height: 2.25rem;
+    border-radius: 999px;
+    color: var(--native-accent, rgb(37 99 235));
+    background: var(--native-ptr-background, white);
+    box-shadow: 0 4px 14px rgb(15 23 42 / 0.14);
+    opacity: 0;
+    pointer-events: none;
+    transform: translateX(-50%) scale(0.6);
+  }
+
+  .dark .native-ptr-indicator { color: var(--native-accent-dark, rgb(96 165 250)); background: var(--native-ptr-background-dark, rgb(30 41 59)); }
+  .native-ptr-indicator.is-visible { opacity: 1; }
+  .native-ptr-icon { width: 1.25rem; height: 1.25rem; }
+
+  .native-ptr-indicator.is-refreshing {
+    opacity: 1;
+    transform: translateX(-50%);
+    transition: opacity 150ms ease;
+  }
+
+  .native-ptr-indicator.is-refreshing .native-ptr-icon { animation: native-ptr-spin 800ms linear infinite; }
+
+  @keyframes native-ptr-spin { to { transform: rotate(360deg); } }
+
+  @media (prefers-reduced-motion: reduce) {
+    .native-ptr-indicator.is-refreshing .native-ptr-icon { animation-duration: 2400ms; }
+  }
+</style>

package/resources/components/NativeSegmentedControl.stx

@@ -0,0 +1,95 @@
+<script client>
+import { haptics } from '@stacksjs/mobile'
+
+/**
+ * An iOS segmented control: two to five mutually exclusive views of one screen.
+ *
+ * `options` is a list of strings or `{ label, value }`. Bind the choice with
+ * `v-model:value` or listen for `change`. A selection taps the haptic engine
+ * the way UISegmentedControl does.
+ */
+interface SegmentOption { label: string, value: string }
+
+const emit = defineEmits()
+const rawOptions = useReactiveProp<Array<string | SegmentOption>>('options', [])
+const ariaLabel = useReactiveProp<string>('label', 'View')
+const className = useReactiveProp<string>('class', '')
+const selected = useModel('value', { default: '' })
+
+const options = derived<SegmentOption[]>(() => rawOptions().map(option =>
+  typeof option === 'string' ? { label: option, value: option } : option))
+
+const activeIndex = derived(() => Math.max(0, options().findIndex(option => option.value === (selected() || options()[0]?.value))))
+const thumbStyle = derived(() => {
+  const count = Math.max(1, options().length)
+  return `width:calc((100% - 4px) / ${count});transform:translateX(${activeIndex() * 100}%)`
+})
+
+function choose(value: string): void {
+  if (value === selected()) return
+  selected.set(value)
+  void haptics.selection()
+  emit('change', value)
+}
+</script>
+
+<div role="tablist" :aria-label="ariaLabel()" class="native-segmented" :class="className()">
+  <span aria-hidden="true" class="native-segmented-thumb" :style="thumbStyle()"></span>
+  <button
+    :for="(option, index) in options()"
+    :key="option.value"
+    type="button"
+    role="tab"
+    class="native-segmented-option"
+    :aria-selected="index === activeIndex() ? 'true' : 'false'"
+    @click="choose(option.value)"
+  >{{ option.label }}</button>
+</div>
+
+<style>
+  .native-segmented {
+    position: relative;
+    display: grid;
+    grid-auto-columns: 1fr;
+    grid-auto-flow: column;
+    padding: 2px;
+    border-radius: 0.6rem;
+    background: var(--native-segmented-track, rgb(118 118 128 / 0.12));
+    -webkit-user-select: none;
+    user-select: none;
+  }
+
+  .dark .native-segmented { background: var(--native-segmented-track-dark, rgb(118 118 128 / 0.24)); }
+
+  .native-segmented-thumb {
+    position: absolute;
+    top: 2px;
+    bottom: 2px;
+    left: 2px;
+    border-radius: 0.45rem;
+    background: var(--native-segmented-thumb, white);
+    box-shadow: 0 3px 8px rgb(0 0 0 / 0.12), 0 3px 1px rgb(0 0 0 / 0.04);
+    transition: transform 220ms cubic-bezier(0.3, 0.7, 0.4, 1);
+  }
+
+  .dark .native-segmented-thumb { background: var(--native-segmented-thumb-dark, rgb(99 99 102)); }
+
+  .native-segmented-option {
+    position: relative;
+    z-index: 1;
+    min-height: 2rem;
+    padding: 0 0.75rem;
+    border: 0;
+    color: inherit;
+    background: transparent;
+    font-size: 0.8125rem;
+    font-weight: 500;
+    -webkit-tap-highlight-color: transparent;
+  }
+
+  .native-segmented-option[aria-selected="true"] { font-weight: 600; }
+
+  @media (prefers-reduced-motion: reduce) {
+    .native-segmented-thumb { transition: none; }
+  }
+</style>

package/resources/components/NativeSheet.stx

@@ -0,0 +1,132 @@
+<script client>
+import { haptics } 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.
+ */
+const emit = defineEmits()
+const open = useModel('open', { default: false })
+const title = useReactiveProp<string>('title', '')
+const doneLabel = useReactiveProp<string>('doneLabel', 'Done')
+
+let wasOpen = false
+effect(() => {
+  const isOpen = open()
+  if (isOpen && !wasOpen) void haptics.impact('light')
+  wasOpen = isOpen
+})
+
+function close(): void {
+  open.set(false)
+  emit('close')
+}
+
+useEventListener('keydown', (event: KeyboardEvent) => {
+  if (event.key === 'Escape' && open()) close()
+})
+</script>
+
+<div class="native-sheet" :class="open() ? 'is-open' : ''" :aria-hidden="open() ? 'false' : 'true'">
+  <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">
+      <h2 class="native-sheet-title">{{ title() }}</h2>
+      <button type="button" class="native-sheet-done" @click="close()">{{ doneLabel() }}</button>
+    </header>
+    <div class="native-sheet-body">
+      <slot />
+    </div>
+  </section>
+</div>
+
+<style>
+  .native-sheet {
+    position: fixed;
+    inset: 0;
+    z-index: 70;
+    visibility: hidden;
+    pointer-events: none;
+  }
+
+  .native-sheet.is-open { visibility: visible; pointer-events: auto; }
+
+  .native-sheet-backdrop {
+    position: absolute;
+    inset: 0;
+    background: rgb(2 6 23 / 0.38);
+    opacity: 0;
+    transition: opacity 240ms ease;
+  }
+
+  .native-sheet.is-open .native-sheet-backdrop { opacity: 1; }
+
+  .native-sheet-panel {
+    position: absolute;
+    right: 0;
+    bottom: 0;
+    left: 0;
+    display: flex;
+    flex-direction: column;
+    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;
+    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);
+  }
+
+  .dark .native-sheet-panel { background: var(--native-sheet-background-dark, rgb(15 23 42)); }
+  .native-sheet.is-open .native-sheet-panel { transform: none; }
+
+  .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);
+  }
+
+  .native-sheet-header {
+    display: flex;
+    gap: 0.75rem;
+    align-items: center;
+    justify-content: space-between;
+    padding: 0.5rem 1rem 0.25rem;
+  }
+
+  .native-sheet-title { font-size: 1.0625rem; 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-weight: 600;
+  }
+
+  .dark .native-sheet-done { color: var(--native-accent-dark, rgb(96 165 250)); }
+
+  .native-sheet-body {
+    overflow-y: auto;
+    padding: 0.5rem 1rem 1rem;
+    overscroll-behavior: contain;
+  }
+
+  @media (prefers-reduced-motion: reduce) {
+    .native-sheet-backdrop, .native-sheet-panel { transition: none; }
+  }
+
+  /* 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>

package/resources/components/NativeTabBar.stx

@@ -23,7 +23,8 @@ function selectTab(): void {
     display: grid;
     grid-auto-flow: column;
     grid-auto-columns: 1fr;
-    min-height: 4.5rem;
+    min-height: calc(4.5rem + env(safe-area-inset-bottom, 0px));
+    padding: 0 env(safe-area-inset-right, 0px) env(safe-area-inset-bottom, 0px) env(safe-area-inset-left, 0px);
     border-top: 1px solid rgb(148 163 184 / 0.22);
     background: rgb(255 255 255 / 0.9);
     backdrop-filter: blur(24px) saturate(160%);
@@ -44,10 +45,28 @@ function selectTab(): void {
     text-decoration: none;
     transition: color 150ms ease, transform 150ms ease;
     -webkit-tap-highlight-color: transparent;
+    /* No link preview or callout on a long press: a tab is not a link to share. */
+    -webkit-touch-callout: none;
+  }
+
+  .native-tab-glyph { position: relative; display: inline-flex; }
+
+  .native-tab-badge {
+    position: absolute;
+    top: -0.3rem;
+    right: -0.55rem;
+    min-width: 1rem;
+    padding: 0 0.25rem;
+    border-radius: 999px;
+    color: white;
+    background: rgb(225 29 72);
+    font-size: 0.625rem;
+    line-height: 1rem;
+    text-align: center;
   }
 
   .native-tab-item:active { transform: scale(0.96); }
-  .native-tab-item.is-active { color: rgb(5 150 105); }
+  .native-tab-item.is-active { color: var(--native-tab-active, rgb(5 150 105)); }
   .native-tab-icon { width: 1.35rem; height: 1.35rem; }
 
   .dark .native-tab-bar {
@@ -56,7 +75,7 @@ function selectTab(): void {
   }
 
   .dark .native-tab-item { color: rgb(148 163 184); }
-  .dark .native-tab-item.is-active { color: rgb(52 211 153); }
+  .dark .native-tab-item.is-active { color: var(--native-tab-active-dark, rgb(52 211 153)); }
 
   @media (prefers-reduced-transparency: reduce) {
     .native-tab-bar {

package/resources/components/NativeTabItem.stx

@@ -3,17 +3,36 @@ interface NativeTabItemProps {
   label: string
   href: string
   icon: string
+  /** A count on the icon. Zero and empty draw nothing. */
+  badge?: string | number
+  /**
+   * More paths that belong to this tab, space-separated: a workout opened from
+   * the calendar keeps the Calendar tab lit. A tab bar is a <nav>, where a
+   * link is otherwise current only on its own page.
+   */
+  match?: string
 }
 
-const { href, icon, label } = defineProps<NativeTabItemProps>()
+const { href, icon, label, badge = '', match = '' } = defineProps<NativeTabItemProps>()
+const hasBadge = badge !== '' && badge !== 0 && badge !== '0'
 </script>
 
+<!-- `draggable="false"`: a slow tap on a busy page reaches the WebView as a
+     long press, and a draggable link starts a native drag instead of
+     navigating. -->
 <StxLink
   to="{{ href }}"
   aria-label="{{ label }}"
   activeClass="is-active"
+  activeMatch="{{ match }}"
   class="native-tab-item"
+  draggable="false"
 >
-  <i aria-hidden="true" class="{{ icon }} native-tab-icon"></i>
+  <span class="native-tab-glyph">
+    <i aria-hidden="true" class="{{ icon }} native-tab-icon"></i>
+    @if(hasBadge)
+      <span class="native-tab-badge">{{ badge }}</span>
+    @endif
+  </span>
   <span>{{ label }}</span>
 </StxLink>

package/resources/components/index.ts

@@ -14,9 +14,13 @@ export { default as Audio } from './Audio.stx'
 export { default as Image } from './Image.stx'
 export { default as NativeAppShell } from './NativeAppShell.stx'
 export { default as NativeHealthButton } from './NativeHealthButton.stx'
+export { default as NativeNavBar } from './NativeNavBar.stx'
 export { default as NativeNetworkBanner } from './NativeNetworkBanner.stx'
 export { default as NativePermissionButton } from './NativePermissionButton.stx'
+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 NativeTabBar } from './NativeTabBar.stx'
 export { default as NativeTabItem } from './NativeTabItem.stx'
 export { default as Video } from './Video.stx'