@swiftbrowser/web 0.17.7 → 0.18.0

package/src/protocol.ts

@@ -455,6 +455,8 @@ export interface TextRun {
   italic?: boolean;
   /** A ShapeStyle JSON object (as `styled` `foreground`). */
   foreground?: unknown;
+  /** A Color JSON object behind the run's glyphs (`AttributedString`'s `backgroundColor`). */
+  background?: unknown;
   /** A line through or under the run; `color` defaults to the run's own. */
   strikethrough?: { color?: unknown };
   underline?: { color?: unknown };
@@ -479,7 +481,8 @@ export interface HStackProps {
 export interface SpacerProps {
   minLength: number | null;
 }
-export type ButtonStyle = 'automatic' | 'plain' | 'bordered' | 'borderedProminent' | 'glass';
+/** `borderless` is `.borderless`: text-only in the tint, as `automatic`, and SwiftUI's own natively. */
+export type ButtonStyle = 'automatic' | 'plain' | 'borderless' | 'bordered' | 'borderedProminent' | 'glass';
 /** Phase 8: `cancel` is the role an `alert` draws apart (bold, or in its own card). */
 export type ButtonRole = 'destructive' | 'cancel' | null;
 /**
@@ -623,10 +626,22 @@ export interface TextFieldProps {
   placeholder: string;
   style: TextFieldStyle;
   secure: boolean;
-  /** Phase 12 `.focused(...)`: whether the field should have focus; present only on bound fields, which report `focus` events. */
+  /**
+   * Phase 12 `.focused(...)`: whether the field should have focus; present
+   * only on bound fields, which report `focus` events. The value the app's
+   * pass for a `submit` leaves (true again, or another field's turned true)
+   * wins over the platform's dismissal of the keyboard, and a field turning
+   * true is scrolled into view ("Focus across a submit").
+   */
   focused?: boolean;
   /** Phase 12 `.onSubmit`: the Enter key sends a `submit` event. */
   submit?: boolean;
+  /**
+   * `onDeleteBackward`: Backspace with the caret at the start of the text (an
+   * empty text included) sends `deletebackward` instead of deleting nothing
+   * (docs/ops-protocol.md, "The delete key at the start of a field").
+   */
+  deleteBackward?: boolean;
   /** Phase 12 `.submitLabel`: the return key's label (`enterkeyhint`). */
   submitLabel?: string;
   /** `.keyboardType(_:)`: a `UIKeyboardType` case name (`emailAddress`, `URL`, `numberPad`…), the on-screen keyboard (`inputmode`). */
@@ -638,8 +653,12 @@ export interface TextFieldProps {
   /** `.autocorrectionDisabled()` (`autocorrect="off"`). */
   autocorrectionDisabled?: boolean;
 }
+/** `.toggleStyle`: the switch (`automatic`, `switch`) or `button`, a button tinted while on. */
+export type ToggleStyle = 'automatic' | 'switch' | 'button';
 export interface ToggleProps {
   isOn: boolean;
+  /** `.toggleStyle(_:)`; absent is `automatic` (the switch). */
+  style?: ToggleStyle;
 }
 export type NavStackProps = Record<string, never>;
 export type NavDisplayMode = 'automatic' | 'large' | 'inline';
@@ -918,9 +937,12 @@ export interface MenuProps {
  * `largeTitle` (iOS 26 `.largeTitle`): the items take the large title row in
  * place of the title's text, scrolling with the content as the title does;
  * the bar shows the title once the row has gone under it. Hidden while the
- * screen's title is inline.
+ * screen's title is inline. `keyboard` (`.keyboard`): a 44 bar across the
+ * screen above the on-screen keyboard while a text input of the screen is
+ * focused (the input accessory view), its items in a row from the leading
+ * edge, a `spacer` child flexible; hidden otherwise.
  */
-export type ToolbarPlacement = 'trailing' | 'leading' | 'principal' | 'bottom' | 'secondary' | 'largeTitle';
+export type ToolbarPlacement = 'trailing' | 'leading' | 'principal' | 'bottom' | 'secondary' | 'largeTitle' | 'keyboard';
 /**
  * `.toolbar { ToolbarItem(placement:) { ... } }`, an extra child of a
  * `navscreen` after its content. The children are the items, laid out at
@@ -958,6 +980,15 @@ export interface SearchFieldProps {
  */
 export interface TapGestureProps {
   location?: boolean;
+  /**
+   * `.onTapGesture(count:)`: the taps required, 1 when absent. With 2 the
+   * element sends one `tap` for two clicks within the double-tap interval
+   * (300 ms); a `tapgesture` of one tap around or inside it waits that
+   * interval before sending its own, as iOS delays a single tap while a
+   * double tap could still land (docs/ops-protocol.md, "Gesture spaces and
+   * composition").
+   */
+  count?: number;
 }
 
 /**
@@ -1076,7 +1107,7 @@ export interface DefaultsOp {
 export interface RequestOp {
   op: 'request';
   id: number;
-  kind: 'fetch' | 'image' | 'share' | 'pickFiles' | 'notification' | 'scanner' | 'websocket' | 'openURL' | 'webAuth' | 'media' | 'download' | 'clipboard' | 'translate' | 'pickColor' | 'mediaSession';
+  kind: 'fetch' | 'image' | 'share' | 'pickFiles' | 'notification' | 'scanner' | 'websocket' | 'openURL' | 'webAuth' | 'media' | 'download' | 'clipboard' | 'translate' | 'pickColor' | 'mediaSession' | 'undo';
   params:
     | FetchRequestParams
     | ImageRequestParams
@@ -1092,7 +1123,21 @@ export interface RequestOp {
     | ClipboardRequestParams
     | TranslateRequestParams
     | PickColorRequestParams
-    | MediaSessionRequestParams;
+    | MediaSessionRequestParams
+    | UndoRequestParams;
+}
+/**
+ * `undo` (docs/ops-protocol.md, "Undo"): what the Swift app's `UndoManager`
+ * can do, after a turn that changed it, for the page's undo host
+ * (src/undo.ts). Answered `{}`; the app does not wait for it. The page's
+ * ⌘Z and ⇧⌘Z come back as `UndoEvent`s.
+ */
+export interface UndoRequestParams {
+  canUndo: boolean;
+  canRedo: boolean;
+  /** The name of what undo takes back, '' for none. */
+  undoActionName: string;
+  redoActionName: string;
 }
 /**
  * `translate` (Translation; src/translation.ts): `availability` of a pair
@@ -1229,7 +1274,7 @@ export interface PickFilesRequestParams {
  * response value is a `NotificationResult`.
  */
 export interface NotificationRequestParams {
-  action: 'status' | 'request' | 'show' | 'close' | 'badge';
+  action: 'status' | 'request' | 'show' | 'close' | 'badge' | 'pushSubscribe' | 'pushUnsubscribe' | 'receive';
   /** `show`: the request's identifier, the notification's `tag`. */
   id?: string;
   title?: string;
@@ -1240,6 +1285,8 @@ export interface NotificationRequestParams {
   badge?: number;
   /** `close`: the identifiers to close. */
   ids?: string[];
+  /** `pushSubscribe`: the Web Push application server key (a VAPID public key, base64url). */
+  applicationServerKey?: string;
 }
 
 /**
@@ -1450,7 +1497,12 @@ export type RendererEvent =
   | VideoEvent
   | LazyEvent
   | MenuEvent
-  | HoverEvent;
+  | HoverEvent
+  // Scroll geometry and animation completion (the block at the end of this file)
+  | ScrollGeometryEvent
+  | AnimationCompleteEvent
+  // The page's undo and redo keys, for the app's undo manager (src/undo.ts)
+  | UndoEvent;
 
 /**
  * Phase 13: the page's answer to the `request` op with this `id`: `value`
@@ -1808,8 +1860,28 @@ export interface GestureProps {
   rotate?: boolean;
   minimumScaleDelta?: number;
   minimumAngleDelta?: number;
+  /**
+   * `DragGesture(coordinateSpace:)`: the space of a `drag` event's `location`
+   * and `startLocation`. `local` (the default) is the element's own box;
+   * `global` the root's coordinates, scrolling included, the same a
+   * `reportsFrame` geometry event reports, so a named space is the global
+   * point less that space's reported origin.
+   */
+  coordinateSpace?: GestureCoordinateSpace;
+  /**
+   * How the gesture composes with the others on the pointer's way to the
+   * root (src/interaction.ts). Absent, `.gesture`: the innermost gesture
+   * whose motion matches wins. `highPriority` (`.highPriorityGesture`): asked
+   * before the gestures of the views inside it. `simultaneous`
+   * (`.simultaneousGesture`): begins when its own distance is met and runs
+   * beside whatever else owns the pointer, never claiming it from them.
+   */
+  mode?: GestureMode;
 }
 
+export type GestureCoordinateSpace = 'local' | 'global';
+export type GestureMode = 'simultaneous' | 'highPriority';
+
 /**
  * `.swipeActions`: children are `[content, ...trailing actions, ...leading
  * actions]` (`trailing` and `leading` count them); the actions are `button`s
@@ -1893,6 +1965,11 @@ export interface ListProps {
 export interface ScrollViewProps {
   refreshable?: boolean;
   refreshing?: boolean;
+  /**
+   * `.scrollIndicators(.hidden)` (or `ScrollView(showsIndicators: false)`):
+   * false hides the scroll bars natively; the page draws none either way.
+   */
+  showsIndicators?: boolean;
   /** Phase 12 `.scrollTargetBehavior`: CSS scroll snapping on the axis. */
   snap?: 'viewAligned' | 'paging';
   /**
@@ -1914,6 +1991,13 @@ export interface ScrollViewProps {
 export interface Style {
   /** `.allowsHitTesting(false)`: `pointer-events: none` on the subtree. */
   hitTesting?: boolean;
+  /**
+   * `.contentShape(Rectangle())`: the whole box takes taps and gestures,
+   * whatever is drawn in it (a clear fill, a stroke, the gaps between
+   * views). Natively the modifier itself; the page's boxes already take
+   * input across their area, so it only marks the box (`data-sb-content-shape`).
+   */
+  contentShape?: 'rectangle';
 }
 
 export interface Style {
@@ -1926,6 +2010,54 @@ export interface Style {
   scrollVisibility?: { threshold: number };
 }
 
+/**
+ * The effects a scroll transition draws in one phase: the visual-effect
+ * fields of a `Style` (none of them changes the layout).
+ */
+export type ScrollTransitionEffect = Pick<
+  Style,
+  | 'offset'
+  | 'scale'
+  | 'scaleAnchor'
+  | 'rotation'
+  | 'rotationAnchor'
+  | 'rotation3D'
+  | 'opacity'
+  | 'blur'
+  | 'brightness'
+  | 'contrast'
+  | 'saturation'
+  | 'grayscale'
+  | 'hueRotation'
+>;
+
+/**
+ * `.scrollTransition(_:axis:transition:)`: the transition's effects in its
+ * three phases (its closure called once for each), which the renderer draws
+ * as the box moves through its scroll view, without a round trip.
+ */
+export interface ScrollTransition {
+  /**
+   * `interactive`: between phases as the box crosses the scroll view's edge,
+   * by how far it is out (0 wholly in view, 1 wholly out); `animated`: the
+   * phase's effects, animated, once the box is partly out; `identity`: the
+   * identity phase's always.
+   */
+  configuration: 'interactive' | 'animated' | 'identity';
+  /** The axis it follows; the scroll view's own when absent. */
+  axis?: 'horizontal' | 'vertical';
+  identity: ScrollTransitionEffect;
+  /** Going out past the top or leading edge. */
+  topLeading: ScrollTransitionEffect;
+  /** Going out past the bottom or trailing edge. */
+  bottomTrailing: ScrollTransitionEffect;
+}
+
+export interface Style {
+  /** `.scrollTransition`: effects drawn as the box scrolls in and out of view (scrollTransition.ts). */
+  scrollTransition?: ScrollTransition;
+}
+
 export interface Style {
   /** `.blendMode`: the CSS `mix-blend-mode` the box is composited with. */
   blendMode?: string;
@@ -1943,8 +2075,9 @@ export type DragPhase = 'began' | 'changed' | 'ended' | 'cancelled';
 
 /**
  * A `gesture` with `drag`: coalesced to one per animation frame while
- * `changed`. Coordinates are points relative to the element's box;
- * `velocity` is in points per second (`ended` only, else 0).
+ * `changed`. Coordinates are points relative to the element's box (the
+ * root's with `coordinateSpace: "global"`); `velocity` is in points per
+ * second (`ended` only, else 0).
  */
 export interface DragEvent {
   type: 'drag';
@@ -1962,7 +2095,10 @@ export interface DragEvent {
  * `rotation` the turn of the line between them, in degrees, clockwise
  * positive; the velocities are per second. `startLocation` is where the
  * fingers' midpoint began, in points from the element's top leading corner;
- * `startAnchor` the same as a fraction of the element's size.
+ * `startAnchor` the same as a fraction of the element's size. `location` is
+ * where the midpoint is now (a SwiftBrowser addition: SwiftUI's values stop
+ * at the start), so two fingers can pan as they zoom; a trackpad pinch keeps
+ * its start. A renderer that cannot tell leaves it out.
  */
 export interface PinchEvent {
   type: 'pinch';
@@ -1974,6 +2110,7 @@ export interface PinchEvent {
   rotationVelocity: number;
   startLocation: Point;
   startAnchor: Point;
+  location?: Point;
 }
 /** A `gesture` with `longPress` was held `minimumDuration` without moving 10 px. */
 export interface LongPressEvent {
@@ -2065,7 +2202,9 @@ export type AlertStyle = 'alert' | 'dialog';
  * A root-level element (child of id 0) placed after the tree, like `sheet`.
  * The children are the `button`s in order; a `cancel` role is drawn apart.
  * With no button children the renderer draws an "OK" that sends `tap` with
- * the alert's own id; so does a tap on a dialog's scrim.
+ * the alert's own id; so does a tap on a dialog's scrim. `textfield`
+ * children (`.alert { TextField(...); Button(...) }`) are drawn in the card
+ * between the message and the buttons, in their order.
  */
 export interface AlertProps {
   title: string;
@@ -2113,8 +2252,48 @@ export interface DatePickerProps {
 /** A `<textarea>` filling the proposal; input sends `text` like a `textfield`. */
 export interface TextEditorProps {
   text: string;
-  /** Bound focus (UIKit's `becomeFirstResponder`): the editor takes or gives up focus; `focus` events report changes. */
+  /** Bound focus (UIKit's `becomeFirstResponder`): the editor takes or gives up focus (scrolled into view as it does); `focus` events report changes. */
   focused?: boolean;
+  /** As a `textfield`'s: Backspace at the start of the text sends `deletebackward`. */
+  deleteBackward?: boolean;
+  /**
+   * Attributed text (`TextEditor(text: $attributedString)`): the runs `text`
+   * is made of, drawn with each run's weight, slant, lines and color. An
+   * editor with runs (an empty array included) is the rich editor for its
+   * life; it still reports plain `text`, and the app keeps the runs.
+   */
+  runs?: TextRun[];
+  /**
+   * A bound selection (`selection:`), on a plain editor or a rich one: the
+   * editor reports the viewer's with `selection` events, and moves to one
+   * the app sets (when the app focuses the editor, if it is not focused).
+   */
+  selection?: TextSelectionRange;
+}
+
+/** A range of an editor's text in UTF-16 offsets; `start === end` is the caret. */
+export interface TextSelectionRange {
+  start: number;
+  end: number;
+}
+
+/** A `texteditor` with `selection` in its props: the viewer moved the caret or selected. */
+export interface SelectionEvent {
+  type: 'selection';
+  id: ElementId;
+  value: TextSelectionRange;
+}
+
+/**
+ * A rich `texteditor`'s runs after an edit of their attributes alone (the
+ * native editor's own Bold, Italic and Underline, iOS 26's edit menu): the
+ * text unchanged, `value` its runs as the editor now shows them, each run's
+ * other attributes (a color, a link) as the app sent them.
+ */
+export interface RunsEvent {
+  type: 'runs';
+  id: ElementId;
+  value: TextRun[];
 }
 
 /** A `stepper` half was tapped: +1 or −1. */
@@ -2137,7 +2316,18 @@ export interface DateEvent {
   id: ElementId;
   value: number;
 }
-export type Phase8ControlEvent = StepEvent | SlideEvent | DateEvent | FocusEvent | SubmitEvent;
+export type Phase8ControlEvent = StepEvent | SlideEvent | DateEvent | FocusEvent | SubmitEvent | SelectionEvent | RunsEvent | DeleteBackwardEvent;
+
+/**
+ * Backspace in a `textfield` or `texteditor` with `deleteBackward`, with
+ * nothing selected and the caret at offset 0 (so nothing to delete): the
+ * app merges the field into what comes before it, say. The key deletes
+ * nothing of its own.
+ */
+export interface DeleteBackwardEvent {
+  type: 'deletebackward';
+  id: ElementId;
+}
 
 /** Phase 12: a bound `textfield` (one with `focused` in its props) gained or lost focus. */
 export interface FocusEvent {
@@ -2209,6 +2399,12 @@ export interface Style {
   strikethrough?: boolean;
   /** View `.italic(_:)`: slants the texts below (false turns it off). */
   italic?: boolean;
+  /**
+   * `.scrollDisabled(_:)`, inherited: the views below do not scroll; a
+   * `texteditor` is then as tall as its lines (a text view that does not
+   * scroll), whatever the proposal. False turns an ancestor's off.
+   */
+  scrollDisabled?: boolean;
   /**
    * `.ignoresSafeArea(edges:)`: the engine extends the box to the screen
    * edge on each listed side when the box touches that safe-area edge. The
@@ -2590,3 +2786,100 @@ export interface MediaRequestParams {
   /** `file`: a resource's path inside the app's bundle, in place of `data`: the page answers the URL it serves the resource at. */
   path?: string;
 }
+
+// ---------------------------------------------------------------------------
+// Scroll geometry, settable offsets, pinned views, animation completion
+// (docs/ops-protocol.md, "Scroll geometry, pinned views and animation completion")
+// ---------------------------------------------------------------------------
+
+export interface ScrollViewProps {
+  /**
+   * `.onScrollGeometryChange(for:of:action:)`: the page sends `scrollgeometry`
+   * to the view after each layout pass and, while it scrolls, once per
+   * animation frame, whenever a field changed (src/scrollGeometry.ts).
+   */
+  reportsGeometry?: boolean;
+  /**
+   * `ScrollPosition.scrollTo(x:y:)` (a `.scrollPosition` bound to a point):
+   * the content offset to scroll to, carried out once per `serial` after the
+   * pass's layout, smoothly when the commit is animated. An axis left out
+   * keeps its offset; the browser clamps the ends.
+   */
+  scrollOffset?: ScrollOffsetCommand;
+}
+
+export interface ScrollOffsetCommand {
+  x?: number;
+  y?: number;
+  /** Increases with every request; the page carries out each serial once. */
+  serial: number;
+}
+
+/**
+ * SwiftUI's `ScrollGeometry` for a `scrollview` with `reportsGeometry`:
+ * where its visible area is in its content and how big both are, in points
+ * (2 decimals). Sent after a layout pass and, while the view scrolls, once
+ * per animation frame, when any field changed since the last report.
+ */
+export interface ScrollGeometryEvent {
+  type: 'scrollgeometry';
+  id: ElementId;
+  /** The visible area's origin in the content (`scrollLeft`, `scrollTop`). */
+  offset: { x: number; y: number };
+  /** The content's laid-out size. */
+  contentSize: { width: number; height: number };
+  /** The scroll view's own size. */
+  containerSize: { width: number; height: number };
+  /** Space the view scrolls into past its content (under a bar covering its bottom); zeros on the web otherwise. */
+  contentInsets: { top: number; leading: number; bottom: number; trailing: number };
+}
+
+/** `PinnedScrollableViews`: what a lazy stack or grid keeps in view as its sections scroll. */
+export type PinnedView = 'sectionHeaders' | 'sectionFooters';
+
+export interface VStackProps {
+  /**
+   * `LazyVStack(pinnedViews:)`: the `sectionheader` (`sectionfooter`) of each
+   * `section` child stays at the scroll view's edge while its section
+   * passes, pushed out by the next section's (src/pinnedViews.ts).
+   */
+  pinned?: PinnedView[];
+}
+export interface HStackProps {
+  /** `LazyHStack(pinnedViews:)`: as for `vstack`, along the leading edge. */
+  pinned?: PinnedView[];
+}
+export interface LazyVGridProps {
+  /** `LazyVGrid(pinnedViews:)`: as for `vstack`. */
+  pinned?: PinnedView[];
+}
+export interface LazyHGridProps {
+  /** `LazyHGrid(pinnedViews:)`: as for `hstack`. */
+  pinned?: PinnedView[];
+}
+
+export interface CommitOp {
+  /**
+   * `withAnimation(_:completionCriteria:_:completion:)`: the page answers
+   * `animationcomplete` with this serial once the pass's animations have
+   * ended (at once, after the pass, when nothing animated).
+   */
+  completion?: number;
+  /** `logicallyComplete` (the default) ends with the animation's duration; `removed` once every effect is gone. */
+  completionCriteria?: 'logicallyComplete' | 'removed';
+}
+
+/** The pass whose `commit` carried `completion` has finished animating. Not addressed to an element. */
+export interface AnimationCompleteEvent {
+  type: 'animationcomplete';
+  serial: number;
+}
+
+/**
+ * The system's undo or redo (⌘Z, ⇧⌘Z outside a text input; src/undo.ts),
+ * for the app's `UndoManager`, which takes a step back or forward. Not
+ * addressed to an element; sent once the app has reported an `undo` request.
+ */
+export interface UndoEvent {
+  type: 'undo' | 'redo';
+}