@swiftbrowser/web 0.3.1 → 0.5.0

package/src/pointerEffects.ts

@@ -0,0 +1,182 @@
+/**
+ * What a page with a mouse adds to a phone's UI: `hover` events (`.onHover`),
+ * tooltips (`.help`), cursors (`.pointerStyle`), and SF Symbols' effects
+ * (`.symbolEffect`) drawn with CSS. The Swift shim draws an iPhone and sends
+ * none of these; producers in the page (@swiftbrowser/react) do.
+ */
+
+import type { ElementId, Style, SymbolEffectStyle } from './protocol';
+
+// ---------------------------------------------------------------------------
+// Hover
+// ---------------------------------------------------------------------------
+
+const HOVER_ATTR = 'sbHover';
+
+/** Sends `hover` as a mouse enters and leaves the boxes marked `data-sb-hover` under `root`. */
+export class HoverTracker {
+  private readonly hovered = new Set<HTMLElement>();
+
+  constructor(
+    private readonly root: HTMLElement,
+    private readonly send: (id: ElementId, value: boolean) => void,
+  ) {
+    root.addEventListener('pointerover', this.onOver);
+    root.addEventListener('pointerout', this.onOut);
+  }
+
+  dispose(): void {
+    this.root.removeEventListener('pointerover', this.onOver);
+    this.root.removeEventListener('pointerout', this.onOut);
+    this.hovered.clear();
+  }
+
+  private readonly onOver = (event: PointerEvent): void => {
+    if (event.pointerType === 'touch') return;
+    for (let el = event.target as HTMLElement | null; el && el !== this.root; el = el.parentElement) {
+      if (el.dataset[HOVER_ATTR] === undefined || this.hovered.has(el)) continue;
+      this.hovered.add(el);
+      this.report(el, true);
+    }
+  };
+
+  private readonly onOut = (event: PointerEvent): void => {
+    if (event.pointerType === 'touch') return;
+    const next = event.relatedTarget as Node | null;
+    for (const el of [...this.hovered]) {
+      if (next && el.contains(next)) continue;
+      this.hovered.delete(el);
+      this.report(el, false);
+    }
+  };
+
+  private report(el: HTMLElement, value: boolean): void {
+    const id = Number(el.dataset['sbId']);
+    if (Number.isInteger(id) && el.isConnected) this.send(id, value);
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Style fields
+// ---------------------------------------------------------------------------
+
+/** One run of each effect at speed 1 (seconds) and its keyframes on the CSS `scale`, `rotate`, `translate` and `opacity` properties. */
+const EFFECTS: Record<string, { duration: number; frames: Keyframe[] }> = {
+  bounce: {
+    duration: 0.5,
+    frames: [
+      { scale: '1', translate: '0 0', offset: 0 },
+      { scale: '1.18', translate: '0 -12%', offset: 0.35 },
+      { scale: '0.94', translate: '0 0', offset: 0.7 },
+      { scale: '1', translate: '0 0', offset: 1 },
+    ],
+  },
+  pulse: { duration: 1.2, frames: [{ opacity: '1' }, { opacity: '0.35' }, { opacity: '1' }] },
+  variableColor: { duration: 1.2, frames: [{ opacity: '1' }, { opacity: '0.5', offset: 0.33 }, { opacity: '0.75', offset: 0.66 }, { opacity: '1' }] },
+  rotate: { duration: 1, frames: [{ rotate: '0deg' }, { rotate: '360deg' }] },
+  wiggle: {
+    duration: 0.6,
+    frames: [{ rotate: '0deg' }, { rotate: '-14deg', offset: 0.25 }, { rotate: '14deg', offset: 0.6 }, { rotate: '0deg' }],
+  },
+  breathe: { duration: 2, frames: [{ scale: '1', opacity: '1' }, { scale: '1.1', opacity: '0.7' }, { scale: '1', opacity: '1' }] },
+};
+
+const playing = new WeakMap<HTMLElement, { key: string; animation: globalThis.Animation }>();
+const triggers = new WeakMap<HTMLElement, number>();
+
+/** Apply the pointer and effect fields of a `styled` element's style (called on create and update). */
+export function applyPointerAndEffects(el: HTMLElement, style: Style): void {
+  if (style.hover) el.dataset[HOVER_ATTR] = '';
+  if (style.help) {
+    el.title = style.help;
+    el.dataset['sbHelp'] = '';
+  } else if (el.hasAttribute('title') && el.classList.contains('sb-styled')) {
+    el.removeAttribute('title');
+  }
+  if (style.pointerStyle) el.style.cursor = style.pointerStyle;
+  applySymbolEffect(el, style.symbolEffect);
+  if (style.matchedGeometry) el.dataset['sbMatched'] = style.matchedGeometry;
+  if (style.contentTransition) {
+    el.dataset['sbContentTransition'] = style.contentTransition.kind;
+    const { countsDown } = style.contentTransition;
+    if (countsDown === undefined) delete el.dataset['sbCountsDown'];
+    else el.dataset['sbCountsDown'] = String(countsDown);
+  }
+}
+
+function applySymbolEffect(el: HTMLElement, effect: SymbolEffectStyle | undefined): void {
+  const s = el.style;
+  if (!effect) {
+    stopEffect(el);
+    return;
+  }
+  el.dataset['sbSymbolEffect'] = effect.effect;
+  // State effects: a look kept while the style carries them.
+  if (effect.effect === 'scale') {
+    s.transition = 'scale 0.25s';
+    s.scale = effect.direction === 'down' ? '0.85' : '1.2';
+    return;
+  }
+  if (effect.effect === 'appear' || effect.effect === 'disappear') {
+    s.transition = 'opacity 0.25s, scale 0.25s';
+    const shown = effect.effect === 'appear';
+    s.opacity = shown ? '1' : '0';
+    s.scale = shown ? '1' : '0.6';
+    return;
+  }
+  const spec = EFFECTS[effect.effect];
+  if (!spec || typeof el.animate !== 'function') return;
+  const duration = (spec.duration / Math.max(effect.speed ?? 1, 0.01)) * 1000;
+  const repeat = effect.repeat === 'forever' ? Infinity : Math.max(1, effect.repeat ?? 1);
+  if (effect.trigger !== undefined) {
+    // A discrete effect plays once per new trigger (never for the first value).
+    const last = triggers.get(el);
+    triggers.set(el, effect.trigger);
+    if (last === undefined || last === effect.trigger) return;
+    playing.get(el)?.animation.cancel();
+    playing.set(el, { key: `once:${effect.trigger}`, animation: el.animate(spec.frames, { duration, iterations: repeat, easing: 'ease-in-out' }) });
+    return;
+  }
+  // An indefinite effect keeps running across updates that leave it alone.
+  const key = `${effect.effect}:${duration}:${repeat === Infinity ? 'forever' : repeat}`;
+  const current = playing.get(el);
+  if (current && current.key === key && current.animation.playState !== 'finished') return;
+  current?.animation.cancel();
+  const iterations = effect.repeat === undefined ? Infinity : repeat;
+  playing.set(el, { key, animation: el.animate(spec.frames, { duration, iterations, easing: 'ease-in-out' }) });
+}
+
+function stopEffect(el: HTMLElement): void {
+  const current = playing.get(el);
+  if (current && !current.key.startsWith('once:')) {
+    current.animation.cancel();
+    playing.delete(el);
+  }
+  triggers.delete(el);
+}
+
+// ---------------------------------------------------------------------------
+// Geometry readers that report their frame
+// ---------------------------------------------------------------------------
+
+export interface SafeAreaInsets {
+  top: number;
+  leading: number;
+  bottom: number;
+  trailing: number;
+}
+
+/** How far the device's safe area reaches into a box at `rect` in a root of `size`. */
+export function safeAreaOverlap(
+  rect: { x: number; y: number; width: number; height: number },
+  size: { width: number; height: number },
+  safeArea: SafeAreaInsets,
+): SafeAreaInsets {
+  const clamp = (value: number, max: number): number => Math.round(Math.min(Math.max(value, 0), max));
+  return {
+    top: clamp(safeArea.top - rect.y, rect.height),
+    bottom: clamp(rect.y + rect.height - (size.height - safeArea.bottom), rect.height),
+    leading: clamp(safeArea.leading - rect.x, rect.width),
+    trailing: clamp(rect.x + rect.width - (size.width - safeArea.trailing), rect.width),
+  };
+}

package/src/protocol.ts

@@ -719,7 +719,15 @@ export interface PickerProps {
  * `GeometryReader`: fills its proposal and reports its size through a
  * `geometry` event whenever it changes. Exactly one child.
  */
-export type GeometryProps = Record<string, never>;
+export interface GeometryProps {
+  /**
+   * Report the reader's frame on screen too (`x`, `y` and `safeArea` in its
+   * `geometry` events, kept current as its ancestors scroll), for
+   * `GeometryProxy.frame(in: .global)` and `safeAreaInsets`. Absent: the size
+   * only, as before.
+   */
+  reportsFrame?: boolean;
+}
 
 // Phase 6 kinds (docs/phase6/layout-containers.md).
 
@@ -795,6 +803,16 @@ export interface LazyVGridProps {
   spacing: number | null;
   alignment: FrameAlignment;
 }
+/**
+ * `LazyHGrid`: `LazyVGrid` turned on its side. The `rows` share the height
+ * the grid is proposed; the cells fill them column by column, `spacing`
+ * (default 8) apart. Children are the cells (flattened). Nothing is lazy.
+ */
+export interface LazyHGridProps {
+  rows: GridItem[];
+  spacing: number | null;
+  alignment: FrameAlignment;
+}
 export type GaugeStyle =
   | 'automatic'
   | 'linearCapacity'
@@ -851,6 +869,12 @@ export type ToolbarPlacement = 'trailing' | 'leading' | 'principal' | 'bottom';
  */
 export interface ToolbarProps {
   placement: ToolbarPlacement;
+  /**
+   * A `ToolbarSpacer` (no children): it separates glass groups, and in a
+   * bottom bar flexible ones share the room left over and push the groups
+   * apart; fixed ones are 8 wide.
+   */
+  spacer?: 'flexible' | 'fixed';
 }
 /**
  * `.searchable(text:)`, an extra child of a `navscreen`: a 36pt rounded
@@ -870,6 +894,19 @@ export interface TapGestureProps {
   location?: boolean;
 }
 
+/**
+ * A box the page fills with its own DOM (src/hostContent.ts): `content` is
+ * the key the page registered its element under. `sizing: "fill"` takes the
+ * proposal, the content's own size on an unconstrained axis; `"content"`
+ * takes the content's size, its width capped by the proposal and its height
+ * measured at that width, like text. Only page-side producers (such as
+ * @swiftbrowser/react) emit it; the Swift core never does.
+ */
+export interface HostProps {
+  content: string;
+  sizing: 'fill' | 'content';
+}
+
 export interface ElementPropsByKind {
   text: TextProps;
   vstack: VStackProps;
@@ -899,12 +936,14 @@ export interface ElementPropsByKind {
   grid: GridProps;
   gridrow: GridRowProps;
   lazyvgrid: LazyVGridProps;
+  lazyhgrid: LazyHGridProps;
   gauge: GaugeProps;
   decorated: DecoratedProps;
   menu: MenuProps;
   toolbar: ToolbarProps;
   searchfield: SearchFieldProps;
   tapgesture: TapGestureProps;
+  host: HostProps;
 }
 
 export type ElementKind = keyof ElementPropsByKind;
@@ -1289,6 +1328,16 @@ export interface GeometryEvent {
   id: ElementId;
   width: number;
   height: number;
+  /** With `reportsFrame`: the box's origin in the root's coordinates, scrolling included (whole px). */
+  x?: number;
+  y?: number;
+  /** With `reportsFrame`: how far the device's safe area reaches into the box on each edge. */
+  safeArea?: { top: number; leading: number; bottom: number; trailing: number };
+  /**
+   * With `reportsFrame`, inside a scroll view or list: its visible rectangle
+   * in the root's coordinates (whole px) and the axis it scrolls along.
+   */
+  scrollView?: { x: number; y: number; width: number; height: number; axis: 'horizontal' | 'vertical' };
 }
 
 /** Host measurements of one subview of a `layout` element (points, 2 decimals; `"infinity"` for an unbounded axis). */
@@ -1333,7 +1382,8 @@ export type RendererEvent =
   // A `video` element's playback (src/video.ts)
   | VideoEvent
   | LazyEvent
-  | MenuEvent;
+  | MenuEvent
+  | HoverEvent;
 
 /**
  * Phase 13: the page's answer to the `request` op with this `id`: `value`
@@ -1451,7 +1501,10 @@ export function isOp(value: unknown): value is Op {
 // ---------------------------------------------------------------------------
 
 /** `NavigationSplitView` in the regular size class: children are `[sidebar, detail]`, each a `navstack`. */
-export type NavSplitProps = Record<string, never>;
+export interface NavSplitProps {
+  /** iPadOS: false hides the sidebar (`NavigationSplitViewVisibility.detailOnly`); absent or true shows it. */
+  sidebarVisible?: boolean;
+}
 
 export type ViewThatFitsAxes = 'horizontal' | 'vertical' | 'both';
 /**
@@ -1466,6 +1519,17 @@ export interface ViewThatFitsProps {
 export interface ElementPropsByKind {
   navsplit: NavSplitProps;
   viewthatfits: ViewThatFitsProps;
+  inspector: InspectorProps;
+  inspectorpanel: Record<string, never>;
+}
+
+/**
+ * `.inspector(isPresented:)` in the regular size class: the children are the
+ * content, then an `inspectorpanel` (the trailing column's content).
+ */
+export interface InspectorProps {
+  /** Whether the panel is shown; false slides it off the trailing edge. */
+  presented: boolean;
 }
 
 export interface Style {
@@ -1688,14 +1752,40 @@ export interface ContextMenuProps {
 }
 
 /**
- * A `List` row that can be selected (`selectable`, `selected`) or deleted
- * (`deletable`, from `ForEach.onDelete`). A tap on a selectable row sends
- * `tap` with the row id; swipe-to-delete or the edit-mode minus sends `delete`.
+ * A `List` row that can be selected (`selectable`, `selected`), deleted
+ * (`deletable`, from `ForEach.onDelete`) or moved (`movable`, from
+ * `ForEach.onMove`; absent means false). A tap on a selectable row sends
+ * `tap` with the row id; swipe-to-delete or the edit-mode minus sends
+ * `delete`. A movable row shows a grip at its trailing edge while the list
+ * is editing, and a long press lifts it otherwise; dragging it among its
+ * neighbours and letting go sends `move` (src/dragDrop.ts).
  */
 export interface ListRowProps {
   selectable?: boolean;
   selected?: boolean;
   deletable?: boolean;
+  movable?: boolean;
+}
+
+/**
+ * `.draggable` / `.onDrag`: exactly one child, the child's size. A long
+ * press (touch) or a 10 px drag (mouse) lifts a copy of the content, which
+ * follows the pointer; `dragstart` goes out as it lifts and `dragend` once
+ * it is dropped or let go (src/dragDrop.ts).
+ */
+export type DraggableProps = Record<string, never>;
+
+/**
+ * `.dropDestination` / `.onDrop`: exactly one child, the child's size. A
+ * lifted `draggable` over it sends `drop` with the phase `entered` /
+ * `exited`, and `performed` with the source when released over it. Text,
+ * links and files dragged in from outside the page (the browser's own drag
+ * and drop) are offered when their MIME type matches one of `accepts`
+ * (`text/plain`, `image/*`, or a star over a star for anything); they
+ * arrive as `items`.
+ */
+export interface DropDestinationProps {
+  accepts?: string[];
 }
 
 export interface ElementPropsByKind {
@@ -1703,12 +1793,14 @@ export interface ElementPropsByKind {
   swipeactions: SwipeActionsProps;
   contextmenu: ContextMenuProps;
   listrow: ListRowProps;
+  draggable: DraggableProps;
+  dropdestination: DropDestinationProps;
 }
 
-export const INTERACTION_KINDS: readonly ElementKind[] = ['gesture', 'swipeactions', 'contextmenu', 'listrow'];
+export const INTERACTION_KINDS: readonly ElementKind[] = ['gesture', 'swipeactions', 'contextmenu', 'listrow', 'draggable', 'dropdestination'];
 
 export interface ListProps {
-  /** `EditButton` / `editMode`: every `listrow` gains a 44 pt leading control and its content shifts right 44. */
+  /** `EditButton` / `editMode`: a selectable or deletable `listrow` gains a 44 pt leading control and its content shifts right 40; a movable one a trailing grip. */
   editing?: boolean;
   /** `.refreshable`: a pull past 60 pt at the top sends `refresh`. */
   refreshable?: boolean;
@@ -1772,9 +1864,52 @@ export interface RefreshEvent {
   type: 'refresh';
   id: ElementId;
 }
+/**
+ * A movable `listrow` was dragged to a new place: `to` is the index among
+ * its container's children (the `list`'s, or its `section`'s) before which
+ * it goes, counted before it leaves (0 ... the child count), as
+ * `move(fromOffsets:toOffset:)` takes its destination.
+ */
+export interface MoveEvent {
+  type: 'move';
+  id: ElementId;
+  to: number;
+}
+/** A `draggable` was lifted: its payload is made now and kept until `dragend`. */
+export interface DragStartEvent {
+  type: 'dragstart';
+  id: ElementId;
+}
+/** The lifted `draggable` was dropped or let go. */
+export interface DragEndEvent {
+  type: 'dragend';
+  id: ElementId;
+}
+/** One thing dragged in from outside the page: text (or a link, `text/uri-list`), or a file's bytes in base64. */
+export interface DropItem {
+  type: string;
+  text?: string;
+  name?: string;
+  data?: string;
+}
+/**
+ * A drag over a `dropdestination`: it `entered`, `exited`, or `performed`
+ * (was released over it). `source` is the lifted `draggable`'s id for a drag
+ * that started in the app; `items` what came from outside the page. The
+ * point is in the destination's own coordinates (0, 0 while entering and leaving).
+ */
+export interface DropEvent {
+  type: 'drop';
+  id: ElementId;
+  phase: 'entered' | 'exited' | 'performed';
+  source?: ElementId;
+  items?: DropItem[];
+  x: number;
+  y: number;
+}
 
 /** The Phase 8 events (merged into `RendererEvent` above). */
-export type InteractionEvent = DragEvent | LongPressEvent | DeleteEvent | RefreshEvent;
+export type InteractionEvent = DragEvent | LongPressEvent | DeleteEvent | RefreshEvent | MoveEvent | DragStartEvent | DragEndEvent | DropEvent;
 // Phase 8: alerts, controls, effects
 // (docs/ops-protocol.md, "Phase 8: interaction"; gestures, swipe actions,
 // context menus, list rows and refresh live in their own block)
@@ -1970,11 +2105,24 @@ export interface ListProps {
   background?: 'hidden';
   /** `.scrollDismissesKeyboard(.immediately | .interactively)`: scrolling blurs the text input being edited inside. */
   dismissesKeyboard?: boolean;
+  /**
+   * `.scrollEdgeEffectStyle(_:for:)` / `.scrollEdgeEffectHidden(_:for:)`: the
+   * scroll edge effect where the list runs under its screen's bar (`top`) or
+   * a bar covering the bottom (`bottom`); an absent edge is automatic (soft).
+   */
+  edgeEffect?: EdgeEffectProps;
+}
+
+export interface EdgeEffectProps {
+  top?: 'hard' | 'soft' | 'hidden';
+  bottom?: 'hard' | 'soft' | 'hidden';
 }
 
 export interface ScrollViewProps {
   /** As for `list`. */
   dismissesKeyboard?: boolean;
+  /** As for `list`. */
+  edgeEffect?: EdgeEffectProps;
 }
 
 /**
@@ -1992,6 +2140,68 @@ export interface ElementPropsByKind {
 }
 
 /** `ScrollViewProxy.scrollTo(_:anchor:)`: where the target should end up (null: as little scrolling as shows it). */
+/**
+ * SF Symbols' effects (`.symbolEffect`), drawn with CSS on the styled box:
+ * `bounce`, `pulse`, `variableColor` (as a pulse), `scale` (up while
+ * active; `down` shrinks), `rotate`, `wiggle`, `breathe`, `appear` /
+ * `disappear` (shown / hidden while active). Without `trigger` the effect
+ * runs while the style carries it (`repeat` times, or forever); with one, it
+ * plays once (`repeat` times) whenever `trigger` changes, like
+ * `.symbolEffect(_:value:)`.
+ */
+export interface SymbolEffectStyle {
+  effect: 'bounce' | 'pulse' | 'variableColor' | 'scale' | 'rotate' | 'wiggle' | 'breathe' | 'appear' | 'disappear';
+  direction?: 'up' | 'down';
+  /** Seconds per run at speed 1 is the effect's own; `speed` divides it. */
+  speed?: number;
+  repeat?: number | 'forever';
+  trigger?: number;
+}
+
+export interface Style {
+  /** The page sends `hover` events as a mouse enters and leaves the box (`.onHover`). */
+  hover?: boolean;
+  /** `.help(_:)`: a tooltip on the box. */
+  help?: string;
+  /** `.pointerStyle(_:)`: the CSS cursor over the box (`pointer`, `text`, `grab`…). */
+  pointerStyle?: string;
+  symbolEffect?: SymbolEffectStyle;
+  /**
+   * `.matchedGeometryEffect(id:in:)`: when an animated pass removes a box
+   * with this id and inserts another with it, the inserted one starts from
+   * the removed one's frame and the removed one's exit travels to the new
+   * frame. The namespace is part of the id.
+   */
+  matchedGeometry?: string;
+  /**
+   * `.contentTransition(_:)`: how a text under the box changes in a pass that
+   * animates. `numericText` rolls the old text out upward and the new one in
+   * from below, or the other way when the new text reads as a smaller number
+   * (`countsDown` fixes the direction); `opacity` and `interpolate` crossfade
+   * them.
+   */
+  contentTransition?: { kind: 'numericText' | 'opacity' | 'interpolate'; countsDown?: boolean };
+}
+
+export interface Style {
+  /**
+   * `.containerRelativeFrame(_:…)`: on the marked axes the box is
+   * `a × container + b` long, the container being the nearest scroll view's
+   * visible area (or the screen), and its content is aligned in that frame.
+   */
+  containerRelativeFrame?: { horizontal?: boolean; vertical?: boolean; a: number; b: number; alignment: FrameAlignment };
+}
+
+/**
+ * A mouse (or pen) entered (`value: true`) or left a box whose style has
+ * `hover`. Touch never hovers.
+ */
+export interface HoverEvent {
+  type: 'hover';
+  id: ElementId;
+  value: boolean;
+}
+
 export interface ScrollToCommand {
   anchor: UnitPoint | null;
   /** Increases with every request (across readers); the page carries out each serial once. */