@swiftbrowser/web 0.3.0 → 0.4.0

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).
 
@@ -870,6 +878,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;
@@ -905,6 +926,7 @@ export interface ElementPropsByKind {
   toolbar: ToolbarProps;
   searchfield: SearchFieldProps;
   tapgesture: TapGestureProps;
+  host: HostProps;
 }
 
 export type ElementKind = keyof ElementPropsByKind;
@@ -1289,6 +1311,11 @@ 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 };
 }
 
 /** Host measurements of one subview of a `layout` element (points, 2 decimals; `"infinity"` for an unbounded axis). */
@@ -1333,7 +1360,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 +1479,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 +1497,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 +1730,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 +1771,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 +1842,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 +2083,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 +2118,59 @@ 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 };
+}
+
+/**
+ * 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. */