@stacksjs/mobile 0.75.97 → 0.75.98

package/README.md

@@ -14,6 +14,30 @@ if (isNativeMobile())
 const position = await location.getCurrentPosition()
 ```
 
+## Waiting for the bridge
+
+Craft's newer iOS shell injects `window.craft` at document start; an older
+one installs it once the page has loaded. A call made inside a native host
+before the bridge exists now waits for it (up to `BRIDGE_WAIT_MS`, 2.5s)
+instead of quietly taking the web path, and a browser takes the fallback at
+once. `callNative(path, args, fallback)` and `afterBridge(run)` are the
+building blocks, for a bridge API this package does not wrap yet.
+
+## Beyond the core services
+
+Each with a web fallback, and none throwing for being unsupported:
+`dialog` (alert, confirm, actionSheet; HTML stand-ins in a browser),
+`confirmAction`, `useActionSheet`, `contextMenu`, `browser.open` (in-app
+Safari or an auth session), `symbols.image` (SF Symbols, cached), `statusBar`,
+`chrome`, `refresh` and `observeNativeRefresh` (the native refresh control),
+`background`, `clipboard`, `db`, `files`, `shortcuts`, `widgets`,
+`orientation`, `auth.signInWithApple` and `storeKit`; the phone's events
+`onAppearance`, `onResume`, `onMemoryWarning`, `onSilentPush` and
+`onBackgroundRefresh`; and `haptics.prepare()`. The gesture logic behind the
+Native components (sheet detents, the large title, long press, segment
+scrubbing, pressables, the chrome sync) is exported too. See the
+[Mobile Apps guide](https://stacksjs.org/guide/mobile).
+
 ## Native bridge availability
 
 `mobile` is a typed service collection (`MobileApi`), available in both browsers

package/dist/bridge.d.ts

@@ -0,0 +1,90 @@
+/** The page's window, when there is one. */
+export declare function craftHost(): CraftHost | undefined;
+/** `window.craft`, the bridge object, once installed. */
+export declare function craftRoot(): Record<string, any> | undefined;
+/**
+ * Whether this page runs inside Craft's phone shell, before the bridge exists.
+ *
+ * Craft installs `window.craft` once the page has finished loading on an older
+ * shell — images and all — so a bridge check answers `false` during setup on
+ * a phone, and a layout that decides then renders the website's chrome in the
+ * app. The transports are there from the start: Android's `CraftAndroid`
+ * interface, and on iOS the `craft` message handler. Craft's macOS windows
+ * carry that handler too, so on iOS an iPhone or iPad user agent is what makes
+ * it the phone app.
+ */
+export declare function hasNativeMobileHost(): boolean;
+/** A native host whose bridge object is not installed yet: worth waiting for. */
+export declare function bridgePending(): boolean;
+/**
+ * Resolves once the bridge object (`window.craft`) is installed: `true` then,
+ * `false` in a browser at once, or after `timeoutMs` in a host that never
+ * installs it.
+ *
+ * Not whenNativeMobile(), which answers `true` as soon as the phone shell is
+ * recognisable, before the bridge exists and before anything can be asked of it.
+ */
+export declare function whenBridgeReady(timeoutMs?: unknown): Promise<boolean>;
+/**
+ * The bridge function at `path` (`'dialog.confirm'`), or null when this host
+ * has none. Synchronous: no waiting for a bridge still on its way.
+ */
+export declare function nativeFunctionNow(path: string): ((...args: any[]) => unknown) | null;
+/**
+ * The bridge function at `path`, waiting for a native host's bridge to arrive
+ * first. Null in a browser, on a shell that predates the API, or when the
+ * bridge did not come within `timeoutMs`.
+ */
+export declare function nativeFunction(path: string, timeoutMs?: unknown): Promise<((...args: any[]) => unknown) | null>;
+/**
+ * Calls the bridge function at `path`, or `fallback` where there is none.
+ *
+ * Inside a native host whose bridge is still loading, the call is held until
+ * it arrives, so an early call reaches the native implementation rather than
+ * the web one.
+ */
+export declare function callNative<T>(path: string, args: unknown[], fallback: () => T | Promise<T>, options?: CallNativeOptions): Promise<T>;
+/**
+ * Runs `run` once a native host's bridge is installed: at once when it is
+ * there or in a browser, after it arrives (or `BRIDGE_WAIT_MS` passes) in a
+ * host still loading it.
+ *
+ * craft-native's services read `window.craft` at call time and take their web
+ * path when it is missing, which during an older shell's launch it is. The
+ * services this package exports call through here, as plain object literals
+ * rather than wrapped at import: a bundler drops an object literal nobody
+ * imports, and could not drop a call made at module scope once minified.
+ */
+export declare function afterBridge<T>(run: () => T | Promise<T>, timeoutMs?: unknown): Promise<T>;
+/**
+ * Subscribes once the bridge can take the subscription: at once when it is
+ * there or in a browser, otherwise when it arrives. The returned function
+ * unsubscribes either way, including before the subscription was made.
+ */
+export declare function subscribeWhenReady(subscribe: () => (() => void) | void, timeoutMs?: unknown): () => void;
+/** Listens for a Craft DOM event on the window; the detail is passed through. */
+export declare function onCraftEvent<T = Record<string, unknown>>(name: string, callback: (detail: T) => void): () => void;
+/**
+ * Reaching Craft's bridge at the right moment.
+ *
+ * Craft's iOS shell injects `window.craft` at document start, but an older
+ * shell installs it once the page has finished loading. A call made before
+ * then used to find no bridge and quietly take the web path: a secure-storage
+ * read answered from localStorage, a confirm drew the browser's own dialog.
+ * Inside a native host, a call now waits for the bridge (briefly: a host that
+ * never installs one gets the web fallback after `BRIDGE_WAIT_MS`), and only a
+ * browser takes the fallback at once.
+ */
+/** How long a call waits for a native host's bridge before using the web fallback. */
+export declare const BRIDGE_WAIT_MS: 2500;
+export declare interface CraftHost extends EventTarget {
+  craft?: unknown
+  CraftAndroid?: unknown
+  webkit?: { messageHandlers?: Record<string, unknown> }
+  document?: Document
+  navigator?: Navigator
+}
+export declare interface CallNativeOptions {
+  fallbackOnError?: boolean
+  timeoutMs?: number
+}

package/dist/controls.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Calls `onLongPress` when a finger (or mouse) stays on `element` for
+ * `delay`. The click that follows a long press is swallowed, so a long press
+ * on a link opens its menu without also following it, and the browser's own
+ * callout menu is kept out of the way.
+ */
+export declare function observeLongPress(element: HTMLElement, options: LongPressOptions): () => void;
+/** Which of `count` equal segments across `rect` the x coordinate is over, clamped to the ends. */
+export declare function segmentAt(x: number, rect: { left: number, width: number }, count: number): number;
+/**
+ * Scrubbing a segmented control: a finger that lands on the chosen segment and
+ * slides drags the thumb across, and lifting chooses where it stopped. A tap
+ * elsewhere stays the button's own click.
+ */
+export declare function observeSegmentScrub(track: HTMLElement, options: SegmentScrubOptions): () => void;
+/** The segment an arrow, Home or End key moves to from `index`, or null for any other key. */
+export declare function segmentForKey(key: string, index: number, count: number): number | null;
+/** Moves focus to the `index`th tab of a segmented control, as arrow keys do in a tab list. */
+export declare function focusSegment(track: HTMLElement, index: number): void;
+/**
+ * Wakes the Taptic Engine as a finger lands on anything marked
+ * `data-native-pressable`, so the tap that follows its press plays at once.
+ *
+ * Listening for touchstart at all is also what makes iOS apply `:active`, the
+ * pressed state the shell's stylesheet draws.
+ */
+export declare function installPressables(root: EventTarget): () => void;
+export declare interface LongPressOptions {
+  delay?: number
+  tolerance?: number
+  onPressStart?: () => void
+  onPressEnd?: () => void
+  onLongPress: (event: { x: number, y: number }) => void
+}
+export declare interface SegmentScrubOptions {
+  count: () => number
+  selected: () => number
+  onPress?: (pressed: boolean) => void
+  onScrub: (index: number) => void
+  onCommit: (index: number) => void
+}

package/dist/events.d.ts

@@ -0,0 +1,28 @@
+/**
+ * The appearance as it stands. The shell writes `--craft-font-scale` and
+ * `data-craft-reduce-*` on the root element before the page runs, so this is
+ * right at setup too; elsewhere it reads the media queries.
+ */
+export declare function currentAppearance(): NativeAppearance;
+/** A `craftAppearance` detail, made whole. */
+export declare function normalizeAppearance(detail: Partial<NativeAppearance> | null | undefined): NativeAppearance;
+/**
+ * Calls `callback` with the appearance now and whenever the phone's settings
+ * change (Dynamic Type, Reduce Motion, Reduce Transparency, Light/Dark).
+ */
+export declare function onAppearance(callback: (appearance: NativeAppearance) => void, options?: { immediate?: boolean }): () => void;
+/** The app came back to the front after `backgroundedMs` away. */
+export declare function onResume(callback: (detail: { backgroundedMs: number }) => void): () => void;
+/** iOS is short of memory: drop caches that can be rebuilt. */
+export declare function onMemoryWarning(callback: () => void): () => void;
+/** A content-available push arrived. The handler's settling completes it. */
+export declare function onSilentPush(handler: (payload: Record<string, unknown>) => unknown): () => void;
+/** iOS woke the app to refresh (BGAppRefreshTask). The handler's settling completes it. */
+export declare function onBackgroundRefresh(handler: () => unknown): () => void;
+export declare interface NativeAppearance {
+  contentSizeCategory?: string
+  fontScale: number
+  reduceMotion: boolean
+  reduceTransparency: boolean
+  colorScheme: 'light' | 'dark'
+}

package/dist/gestures.d.ts

@@ -25,14 +25,50 @@ export declare function pullDistance(scrollTop: number, fingerTravel: number): n
  * it disarms. Letting go while armed runs `onRefresh`.
  */
 export declare function observePullToRefresh(options: PullToRefreshOptions): () => void;
-/** Where a page scrolls: the window, or a stand-in with the same shape. */
+/**
+ * Where a large-title navigation bar is for a scroll offset.
+ *
+ * The title collapses over its own height. Pulled past the top (iOS's rubber
+ * band, a negative offset) it grows a little, at most 10%, anchored at its
+ * leading edge.
+ */
+export declare function largeTitleMetrics(offset: number, height?: number): LargeTitleMetrics;
+/**
+ * Links a navigation bar to the page's scroll, a frame at a time.
+ *
+ * Writes `--native-nav-progress` (0 to 1) and `--native-nav-stretch` on
+ * `element`, so its CSS can fade the material in, move the small title into
+ * the bar and stretch the large one, all on the compositor. Nothing re-renders.
+ */
+export declare function observeLargeTitle(element: HTMLElement, options?: LargeTitleOptions): () => void;
+/**
+ * The element a selector names, as a scroll host: for a screen whose content
+ * scrolls inside a container rather than the page. Undefined (the window)
+ * when nothing matches.
+ */
+export declare function resolveScrollHost(selector: string | null | undefined): ScrollHost | undefined;
+/**
+ * Where a page scrolls: the window, a scrolling element (a screen that scrolls
+ * inside its own container), or a stand-in with the same shape.
+ */
 export declare interface ScrollHost extends EventTarget {
   scrollY?: number
+  scrollTop?: number
   document?: { scrollingElement?: { scrollTop: number } | null }
 }
 export declare interface PullToRefreshOptions {
   threshold?: number
-  onPull?: (distance: number, armed: boolean) => void
+  onPull?: (distance: number, armed: boolean, pull: { bounce: number }) => void
   onRefresh: () => unknown | Promise<unknown>
   host?: ScrollHost
 }
+export declare interface LargeTitleMetrics {
+  progress: number
+  stretch: number
+}
+export declare interface LargeTitleOptions {
+  height?: number
+  title?: HTMLElement | null
+  host?: ScrollHost
+  onChange?: (metrics: LargeTitleMetrics) => void
+}