@swiftbrowser/react 0.0.0-stage → 0.4.0

package/README.md

@@ -1,3 +1,436 @@
-# Temporary Holding Version
+# @swiftbrowser/react
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+SwiftUI's components for React. A pure React/TypeScript web app writes its
+screens with `List`, `NavigationStack`, `Toggle`, `Picker` and the rest, and
+gets the same iOS UI a SwiftUI app gets in SwiftBrowser: the components emit
+the [render ops](../../docs/ops-protocol.md) the Swift shim emits, and the
+[web renderer](../../Web/README.md) draws them with its iOS layout engine,
+typography, animations, navigation bars, tab bars, sheets and alerts. No
+Swift, no WebAssembly: the package is React components and a renderer host.
+
+It works in both directions with ordinary React, and the two nest: a
+SwiftUI tree can live inside a `react-dom` page, and ordinary React DOM can
+live inside a SwiftUI element (see [Mixing with ordinary React](#mixing-with-ordinary-react)).
+
+The package is experimental.
+
+```sh
+npm install @swiftbrowser/react @swiftbrowser/web react react-dom
+```
+
+It is built for a bundler (Vite, or any that compiles TypeScript in
+dependencies): the renderer it drives comes from `@swiftbrowser/web`'s
+TypeScript sources, as does the stylesheet the page imports.
+
+## Getting started
+
+### A whole page
+
+The simplest app is a page whose root is a SwiftUI tree. The page provides
+the renderer's stylesheet and a root element, and `mount` draws the tree in
+it. In the device frame (the markup of `index.html` here, with the iPhone
+bezel, status bar and the theme controls) the root is the `#screen` element;
+on a phone the renderer can also draw full screen.
+
+```tsx
+import '@swiftbrowser/web/src/styles.css';
+import { useState } from 'react';
+import { mount, Label, List, NavigationLink, NavigationStack, Section, Text, Toggle } from '@swiftbrowser/react';
+
+function Library() {
+  const [downloads, setDownloads] = useState(true);
+  return (
+    <List navigationTitle="Library">
+      <Section header="Reading">
+        <NavigationLink destination={<Text>Detail</Text>}>
+          <Text>The Swift Programming Language</Text>
+        </NavigationLink>
+      </Section>
+      <Section header="Settings">
+        <Toggle isOn={[downloads, setDownloads]}>
+          <Label title="Automatic Downloads" systemImage="arrow.down.circle" />
+        </Toggle>
+      </Section>
+    </List>
+  );
+}
+
+mount(document.getElementById('screen')!, <NavigationStack><Library /></NavigationStack>);
+```
+
+`mount` returns the root and the renderer; `setEnvironment({ colorScheme,
+dynamicTypeSize })` on it switches dark mode and the Dynamic Type size, as
+the demo page's controls do.
+
+### Inside an existing React app
+
+In a `react-dom` app, `SwiftUIView` is a normal component that draws its
+children with the renderer in a box of the page's own layout, with the
+device's design tokens and none of its frame:
+
+```tsx
+import '@swiftbrowser/web/src/styles.css';
+import { SwiftUIView, List, Section, Toggle } from '@swiftbrowser/react';
+
+function Settings({ dark, setDark }) {
+  return (
+    <SwiftUIView fit="content" colorScheme={dark ? 'dark' : 'light'} className="settings">
+      <List>
+        <Section header="Appearance">
+          <Toggle title="Dark Mode" isOn={[dark, setDark]} />
+        </Section>
+      </List>
+    </SwiftUIView>
+  );
+}
+```
+
+`fit="content"` makes the island as tall as its content, like a block in
+the page's flow; `fit="fill"` (the default) draws in the box the page sizes
+with CSS, which is what navigation stacks and tab views want, since they fill
+their screen. `colorScheme` and `dynamicTypeSize` are props. The island is
+a React root of its own: the page's React state reaches it through props as
+usual, and its contexts through `contexts={[…]}` (see
+[Contexts across roots](#contexts-across-roots)).
+
+### Try the demos
+
+```sh
+npm install
+cd packages/react
+npm run dev            # http://localhost:5174/ — Examples/Fidelity, in React
+                       # http://localhost:5174/island.html — islands in a react-dom page
+                       # http://localhost:5174/wide.html — a regular-width app: split view, table, inspector
+npm run test:unit      # the React Fidelity tabs emit the same tree as the Swift app
+```
+
+`?screen=<name>` on the first page opens one of the Fidelity screens alone
+(`list`, `detail`, `form`, `controls`, `typography`, `shapes`, `layout`,
+`tabs`, `sheet`, `alert`, `search`, `post`, `settings`, `reorder`), like the
+Swift app's `-screen` argument; `extras`, `more` and `web` show the
+components beyond it.
+
+## Writing views
+
+### Components
+
+The components are named as in SwiftUI and take the same arguments as
+props: `<VStack alignment="leading" spacing={8}>`, `<Text font="headline">`,
+`<Image systemName="heart.fill" />`, `<Button title="Save" action={save} />`,
+`<Picker label="Plan" selection={[plan, setPlan]} options={plans} />`,
+`<Section header="Reading" footer="…">`. Children are the content closure.
+`ForEach` takes `data` and a render function, with `id`, `onDelete` and
+`onMove` as in SwiftUI; `Group` applies its modifiers to each child.
+
+Text is plain strings and numbers inside `<Text>`; nested `<Text>`s and
+inline `<Image>`s make a rich text (`Text + Text`), and `italic`,
+`underline`, `strikethrough` and `tracking` are its own props.
+
+### Modifiers as props
+
+Every component takes SwiftUI's modifiers as props, and applies them **in
+the order they are written, innermost first**, so a chain reads the same:
+
+```tsx
+<Image
+  systemName="swift"
+  font={system(17, 'semibold')}
+  foregroundStyle="white"
+  frame={{ width: 32, height: 32 }}
+  background={{ fill: 'orange', in: <RoundedRectangle cornerRadius={8} /> }}
+/>
+```
+
+is `Image(systemName: "swift").font(.system(size: 17, weight: .semibold))
+.foregroundStyle(.white).frame(width: 32, height: 32).background(.orange, in:
+RoundedRectangle(cornerRadius: 8))`. Each modifier wraps the view in the same
+`styled` element the Swift shim emits, so the renderer lays it out
+identically. A modifier that must apply twice goes in `modifiers={[…]}`, an
+ordered list. The environment modifiers (`buttonStyle`, `controlSize`,
+`pickerStyle`, `labelsHidden`) are React contexts the views below read, and
+`navigationTitle`, `toolbar`, `searchable`, `sheet`, `alert`,
+`presentationDetents` and `preferredColorScheme` attach to the enclosing
+screen, sheet or page, as the SwiftUI preferences do. Effects (`blur`,
+`grayscale`, `saturation`, `brightness`, `contrast`, `hueRotation`,
+`colorInvert`, `colorMultiply`, `blendMode`, `mask`, `rotation3DEffect`),
+layout hints (`aspectRatio`, `scaledToFit`, `position`, `zIndex`,
+`alignmentGuide`, `ignoresSafeArea`, `allowsHitTesting`, `lineLimit` ranges)
+and the lifecycle (`onAppear`, `task` with an `AbortSignal` for
+cancellation, `onChangeOf`) are modifiers too, as are `draggable` and
+`dropDestination`.
+
+Values are plain data: colors by name (`"red"`, `"secondary"`,
+`"secondarySystemBackground"`) or through `Color` (`Color.opacity('black',
+0.2)`, `Color.gradient('teal')`, `Color.hex('#336699')`); fonts by text
+style (`"title2"`) or `{ textStyle: 'title2', weight: 'bold' }` and
+`system(size, weight, design)`; frames as `{ width, height, maxWidth:
+Infinity, alignment }`; padding as `true`, a number, `['vertical', 6]` or
+insets; gradients through `LinearGradient`, `RadialGradient` and
+`AngularGradient`.
+
+### Bindings
+
+A binding is a `useState` pair, so `isOn={[downloads, setDownloads]}` reads
+like `isOn: $downloads`. Everything that takes one (`Toggle`, `Picker`,
+`Slider`, `Stepper`, `TextField`, `TextEditor`, `DatePicker`, `TabView`'s
+`selection`, `List`'s `selection` and `editing`, `NavigationStack`'s `path`,
+the `sheet` and `alert` modifiers' `isPresented`) also takes a plain value
+with an `onChange` handler. The setter can be anything with that signature.
+
+When the renderer sends an event (a tap, a switch, a selection), the
+handler's state updates render synchronously and the renderer gets the next
+pass inside the event, the way the Swift core answers one.
+
+### Navigation and presentation
+
+`NavigationStack` holds the pushed values (or takes a `path` binding).
+`NavigationLink` pushes a `value`, which the enclosing screen's
+`navigationDestination` builds a screen for, or a `destination` view
+directly. `TabView` holds `Tab`s. `.sheet` and `.alert` are modifiers whose
+content and actions render as root-level elements while presented;
+`presentationDetents` inside a sheet sets its detents. `useDismiss()` inside
+a pushed screen or a sheet pops or dismisses it.
+
+### Lists
+
+`List` and `Form` hold `Section`s and rows. `selection={[…]}` makes rows with
+a `tag` (or a `NavigationLink` value) selectable, one value or a `Set`;
+`editing` is the edit mode, which `EditButton` flips. `ForEach`'s `onDelete`
+makes its rows deletable (a swipe, or edit mode's minus) and `onMove` makes
+them reorder with a grip, with `moveItems` to apply the move to an array.
+`swipeActions` and `contextMenu` are modifiers on a row.
+
+### Size classes
+
+`useHorizontalSizeClass()` is `compact` below 700 points of width (a phone)
+and `regular` from it (a tablet, a desktop window); `mount` and
+`SwiftUIView` follow the root's width as it changes. The views that adapt do
+it as on iOS: `NavigationSplitView` is two columns when regular (the
+sidebar's toggle button hides and shows the sidebar) and one stack when
+compact, which pushes the detail while the sidebar's `List(selection:)` has
+a selection and clears it on back; `.inspector` is a trailing panel when
+regular and a sheet when compact; `Table` shows every column under sortable
+titles when regular and the first column when compact.
+
+```tsx
+<NavigationSplitView
+  sidebar={<List selection={[team, setTeam]}>{/* rows with a tag */}</List>}
+  detail={<Table data={people} columns={columns} sortOrder={[order, setOrder]} />}
+/>
+```
+
+### Scrolling
+
+`List`, `LazyVStack` and `LazyHStack` build a long `ForEach` a batch of
+rows at a time as they scroll into view. `ScrollViewReader` hands a proxy
+whose `scrollTo(id, anchor)` scrolls to the view marked `scrollID={id}`,
+building lazy rows up to it first. `refreshable` (on a `List` or
+`ScrollView`, or above one) runs an async action on a pull, with the
+spinner while it runs. `scrollTargetBehavior="paging"` or `"viewAligned"` on
+a `ScrollView` snaps, with `scrollTargetLayout` on the stack inside.
+Name a coordinate space with `coordinateSpace="page"` on the `ScrollView`
+(or any view), and a `GeometryReader` inside reads its frame there with
+`proxy.frame({ named: 'page' })`, updated as the page scrolls.
+
+### Drawing and media
+
+`Shape` takes a `path` function of the rectangle it is laid out in and
+draws a `Path` (`move`, `addLine`, `addCurve`, `addArc`, `addRoundedRect`…);
+`UnevenRoundedRectangle` and `ContainerRelativeShape` are built on it.
+`Canvas` hands its renderer a `GraphicsContext` (fill, stroke, text, images,
+transforms, opacity, clips, filters, gradients in its own coordinates), and
+`TimelineView` re-renders on a schedule, so a clock is a `TimelineView`
+around a `Canvas`. Views passed in the `symbols` prop (`{ star: <Image
+systemName="star.fill" /> }`) come back from `resolveSymbol` and draw with
+`drawSymbol` at a point, under the context's transform and opacity; they are
+real views laid over the canvas, so they draw above its other commands. `useAVPlayer(url)` is an `AVPlayer` (play, pause, seek,
+mute, volume, rate) that `VideoPlayer` shows in the page's `<video>`; the
+position is read or observed without re-rendering.
+
+### Mouse, keyboard and effects
+
+A web app may have a mouse and a keyboard, so the modifiers SwiftUI keeps
+for iPad and Mac work here: `onHover` (a mouse entering and leaving the
+view's frame), `help` (a tooltip), `pointerStyle` (`link`, `text`,
+`grabIdle`… or any CSS cursor), `keyboardShortcut` on a `Button` (`⌘` is
+Ctrl off Apple platforms) and `onKeyPress` (keys pressed while no text field
+has the focus). `symbolEffect` draws SF Symbols' effects (`bounce`, `pulse`,
+`variableColor`, `rotate`, `wiggle`, `breathe`, `scale`, `appear`), running
+while active or once per change of a value. `matchedGeometryEffect` with a
+namespace from `useNamespace()` moves a view into the frame of the one it
+replaces in an animated change. `contentTransition="numericText"` rolls a
+text's old value out and the new one in when it changes in an animated pass,
+upward or downward as the number grows or shrinks (`{ numericText: {
+countsDown } }` fixes the direction); the whole text rolls, not each digit.
+`opacity` and `interpolate` crossfade. `sensoryFeedback` vibrates where the
+device can.
+
+### Animation
+
+`withAnimation(animation, () => …)` animates the pass a state change makes,
+and the `animation` modifier a view's changes when a value changes.
+`PhaseAnimator` moves its content through phases, each change animated;
+`KeyframeAnimator` plays tracks of keyframes (`linear`, `cubic`, `spring`,
+`move`) and renders its content with the values each frame.
+
+### Charts
+
+`Chart` takes `BarMark`, `LineMark`, `AreaMark`, `PointMark` and `RuleMark`
+with their values in `x` and `y`: categories, numbers or dates. The
+component builds the scales and ticks the Swift Charts module builds
+(bands, nice numeric domains that include zero, calendar strides), groups
+lines and areas by series, colors `foregroundStyleBy` series from the chart
+palette with a legend, and places `annotation`s.
+
+## Mixing with ordinary React
+
+Both directions work, and they nest: a `react-dom` page can hold a SwiftUI
+island, and the island can hold ordinary React DOM inside one of its rows.
+The island page of the demo (`island.html`) does exactly that.
+
+### A SwiftUI tree inside a react-dom app
+
+`SwiftUIView`, shown in [Getting started](#inside-an-existing-react-app):
+a component whose children are a SwiftUI tree, drawn in a box of the page.
+
+### React DOM inside a SwiftUI element
+
+`Host` puts ordinary React DOM, with its own components, stylesheets and
+event handlers, inside a SwiftUI tree. Its children render with `react-dom`
+in a `host` element the layout engine sizes, so the DOM sits inside list
+rows, stacks and screens like any other view:
+
+```tsx
+function Composer() {
+  const [notes, setNotes] = useState('');
+  return (
+    <List>
+      <Section header="Appearance">
+        <LabeledContent label="Notes" value={`${notes.length} characters`} />
+      </Section>
+      <Section header="Composer" footer="A textarea and a counter, rendered by react-dom inside the list row.">
+        <Host className="composer">
+          <textarea value={notes} placeholder="Write something…" onChange={(e) => setNotes(e.target.value)} />
+          <div className="count">{280 - notes.length}</div>
+        </Host>
+      </Section>
+      <Section header="Map">
+        <Host sizing="fill" frame={{ height: 160 }}>
+          <MapView />
+        </Host>
+      </Section>
+    </List>
+  );
+}
+```
+
+Typing in the textarea updates `notes` in the React component above, the
+SwiftUI row shows the count, and the row grows with the text.
+
+- **Sizing.** `sizing="content"` (the default) measures the DOM like text:
+  as wide as the content wants, up to the width the parent proposes, and as
+  tall as it is at that width. Whenever the content changes size (more
+  lines, an image that loaded, a state change), the tree is laid out again
+  around it. `sizing="fill"` takes the proposal, so a `frame` (or the
+  parent's size) decides the box and the content fills it; `height: 100%`
+  in the content reaches the box.
+- **Styling.** The content inherits the device's font and text color, and
+  the iOS tokens are CSS custom properties it can use:
+  `var(--sb-color-secondary)`, `var(--sb-color-accent)`,
+  `var(--sb-color-separator)`, the Dynamic Type sizes, and so on; they
+  follow dark mode. `className` and `style` land on the wrapper the
+  children render in.
+- **Events.** The DOM handles its own events. Pointer downs inside a host
+  never start the renderer's gestures (no swipe, no drag), so text
+  selection, scrolling inside the host and native controls work; the row
+  around it still swipes when the pan starts outside the host.
+- **Hooks.** The content can use this package's hooks: `useDismiss()` from a
+  sheet or a pushed screen, `useNavigation()` to push, `useColorScheme()`.
+
+A host is a React root of its own, so it needs the `react-dom` peer
+dependency, and React context does not cross into it by itself; see below.
+
+### Contexts across roots
+
+`SwiftUIView` and `Host` each start a React root, and React context stops at
+a root boundary. This package's own contexts (the environment, navigation,
+dismiss, the view environment) are bridged automatically. For the page's
+own contexts, name them on the component and they are read on the outer
+side and provided again inside:
+
+```tsx
+<SwiftUIView contexts={[ThemeContext, RouterContext]}>…</SwiftUIView>
+<Host contexts={[ThemeContext]}>…</Host>
+```
+
+The list must be the same on every render of that component (each entry is
+read with a hook). Props, callbacks and external stores need no bridging.
+
+## How it works
+
+- `src/host/`: a [react-reconciler](https://www.npmjs.com/package/react-reconciler)
+  host whose instances are protocol elements. After each React commit,
+  `HostTree.flush` resolves two virtual kinds (a *preference* merges props
+  into the enclosing `navscreen` or `sheet`; a *hoist* moves children to the
+  enclosing screen or to the root, as `.toolbar`, `.sheet` and `.alert` do),
+  diffs the result against the last pass and emits one render pass: creates,
+  updates, inserts (parents before children), removes, `commit`. Events from
+  the renderer reach the element's handlers and flush synchronously.
+- `createSwiftUIRoot(sink)` renders a tree into any ops sink; `mount(screen,
+  element)` pairs a root with a `Renderer` from `@swiftbrowser/web/src/renderer`.
+  `withAnimation(() => setCount(1))` stamps the pass's `commit` with the
+  animation, as `withAnimation { }` does.
+- `src/modifiers.tsx` applies the modifier props; `src/components/` holds the
+  components; `src/components/host.tsx` and `src/island.tsx` the two mixing
+  components, over the renderer's `host` element kind and its island layout
+  mode ([docs/ops-protocol.md](../../docs/ops-protocol.md#host-elements-the-pages-own-dom)).
+- `test/fidelity.test.tsx` renders `Examples/Fidelity`'s tab view through the
+  host and compares the element tree with `Examples/Fidelity/__snapshots__/fidelity.jsonl`,
+  the ops the Swift app emits for the same screens; `test/extras.test.tsx`
+  covers the components beyond the Swift app.
+
+## What is covered
+
+- **Layout**: stacks, `LazyVStack`, `LazyHStack`, `Spacer`, `Divider`,
+  `ScrollView`, `ScrollViewReader`, `Group`, `ForEach` (with `onDelete` and
+  `onMove`), `Grid`, `LazyVGrid`, `ViewThatFits`, `GeometryReader` (its size,
+  its frame on screen or in a `coordinateSpace` named on an ancestor, and its
+  safe-area insets), custom `Layout` (with `layoutValue`s, priorities, view
+  spacing, explicit alignment guides and a cache), `safeAreaInset`.
+- **Content**: `Text` (with `Text + Text` runs, inline images, italic,
+  underline, strikethrough, tracking), `Image` (symbols, catalog images
+  with the `assets` option, remote images and `AsyncImage`), `Label` and its
+  styles, `LabeledContent`, `Link`, `Color` as a view, shapes (built-in,
+  custom paths, `UnevenRoundedRectangle`, `ContainerRelativeShape`) with
+  fills, strokes and gradients, `Canvas`, `TimelineView`, `VideoPlayer`,
+  `Gauge`, `ProgressView`, Swift Charts.
+- **Controls**: `Button` (styles, roles, sizes), `Toggle`, `Picker`,
+  `Slider`, `Stepper`, `TextField` and `SecureField` (focus bindings, submit
+  labels), `TextEditor`, `DatePicker`, `ColorPicker`, `ShareLink`, `Menu`,
+  `EditButton`.
+- **Containers**: `List` (selection, edit mode, swipe actions, deletion,
+  reordering, pull to refresh), `Form`, `Section`, `Table`, `GroupBox`,
+  `DisclosureGroup`, `ControlGroup`, `ContentUnavailableView`.
+- **Navigation and presentation**: `NavigationStack` (value and destination
+  links, a `path` binding, nested stacks flattened), `NavigationSplitView`,
+  `TabView`/`Tab`, toolbars, search fields, sheets with detents, popovers
+  (as sheets), alerts and dialogs, inspectors.
+- **Interaction**: `onTapGesture`, `dragGesture`, `onLongPressGesture`,
+  `contextMenu`, `draggable` and `dropDestination` (in the app, and text or
+  files from outside the page), `onHover`, `help`, `pointerStyle`,
+  `keyboardShortcut`, `onKeyPress`, `sensoryFeedback`.
+- **Animation and effects**: `withAnimation`, `animation`, transitions,
+  `PhaseAnimator`, `KeyframeAnimator`, `matchedGeometryEffect`,
+  `symbolEffect`, `contentTransition`, `redacted` placeholders, `textCase`.
+- **Mixing**: `Host` and `SwiftUIView`.
+
+## Not yet
+
+- `contentTransition="numericText"` rolls the whole text rather than only
+  the digits that changed, and `Canvas` symbols always draw above the
+  canvas's other commands.
+- The Swift-only bridges (SwiftData, URLSession, notifications, Core ML,
+  StoreKit) have no React counterpart, by design: a web app uses the
+  platform's own.
+- The ops protocol is the contract with the renderer and is versioned with it:
+  this package imports the renderer's sources from `@swiftbrowser/web/src/*`.

package/dist/binding.d.ts

@@ -0,0 +1,9 @@
+/**
+ * A `Binding<T>`: a `useState` pair, so `isOn={[downloads, setDownloads]}`
+ * reads like `isOn: $downloads`. A plain value with an `onChange` handler is
+ * accepted everywhere a binding is.
+ */
+export type Binding<T> = readonly [T, (value: T) => void];
+export type BindingValue<T> = Binding<T> | T;
+export declare function readBinding<T>(value: BindingValue<T>, onChange?: (value: T) => void): [T, (next: T) => void];
+//# sourceMappingURL=binding.d.ts.map

package/dist/binding.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"binding.d.ts","sourceRoot":"","sources":["../src/binding.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,MAAM,MAAM,OAAO,CAAC,CAAC,IAAI,SAAS,CAAC,CAAC,EAAE,CAAC,KAAK,EAAE,CAAC,KAAK,IAAI,CAAC,CAAC;AAE1D,MAAM,MAAM,YAAY,CAAC,CAAC,IAAI,OAAO,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC;AAE7C,wBAAgB,WAAW,CAAC,CAAC,EAAE,KAAK,EAAE,YAAY,CAAC,CAAC,CAAC,EAAE,QAAQ,CAAC,EAAE,CAAC,KAAK,EAAE,CAAC,KAAK,IAAI,GAAG,CAAC,CAAC,EAAE,CAAC,IAAI,EAAE,CAAC,KAAK,IAAI,CAAC,CAM5G"}

package/dist/bridge.d.ts

@@ -0,0 +1,17 @@
+/**
+ * React context does not cross a root boundary, and a `Host` (a react-dom
+ * root inside the SwiftUI tree) or a `SwiftUIView` (a SwiftUI root inside a
+ * react-dom tree) is one. The bridge reads the contexts on the outer side and
+ * provides them again on the inner side. This package's own contexts always
+ * travel; a component names any others it needs.
+ */
+import { type Context, type ReactNode } from 'react';
+/**
+ * Returns a function that wraps `children` in providers of the current
+ * values of this package's contexts and of `contexts`. The list of contexts
+ * must not change between renders (each is read with a hook).
+ */
+export declare function useContextBridge(contexts?: readonly Context<unknown>[], options?: {
+    environment?: boolean;
+}): (children: ReactNode) => ReactNode;
+//# sourceMappingURL=bridge.d.ts.map

package/dist/bridge.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bridge.d.ts","sourceRoot":"","sources":["../src/bridge.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAA6B,KAAK,OAAO,EAAE,KAAK,SAAS,EAAE,MAAM,OAAO,CAAC;AAWhF;;;;GAIG;AACH,wBAAgB,gBAAgB,CAC9B,QAAQ,GAAE,SAAS,OAAO,CAAC,OAAO,CAAC,EAAO,EAC1C,OAAO,GAAE;IAAE,WAAW,CAAC,EAAE,OAAO,CAAA;CAAO,GACtC,CAAC,QAAQ,EAAE,SAAS,KAAK,SAAS,CASpC"}

package/dist/components/animators.d.ts

@@ -0,0 +1,40 @@
+/**
+ * `PhaseAnimator` and `KeyframeAnimator`. A phase animator moves its content
+ * through phases, each change in one animated pass that the renderer tweens
+ * (as the shim does); a keyframe animator computes its values frame by frame
+ * along tracks of keyframes and renders them, as SwiftUI evaluates its
+ * content per frame.
+ */
+import type { Animation } from '@swiftbrowser/web/src/protocol';
+import { type ReactNode } from 'react';
+export interface PhaseAnimatorProps<Phase> {
+    phases: readonly Phase[];
+    /** Each change runs through the phases once, back to the first; without one the phases cycle while shown. */
+    trigger?: unknown;
+    /** The animation into a phase (`default` by default). */
+    animation?: (phase: Phase) => Animation;
+    children: (phase: Phase) => ReactNode;
+}
+export declare function PhaseAnimator<Phase>({ phases, trigger, animation, children }: PhaseAnimatorProps<Phase>): ReactNode;
+export type KeyframeCurve = 'linear' | 'cubic' | 'spring' | 'move';
+/** One keyframe of a track: the value it reaches, in how long (seconds), along which curve. */
+export interface Keyframe {
+    to: number;
+    duration: number;
+    curve?: KeyframeCurve;
+}
+export type KeyframeTracks<Value extends Record<string, number>> = {
+    [K in keyof Value]?: readonly Keyframe[];
+};
+export interface KeyframeAnimatorProps<Value extends Record<string, number>> {
+    initialValue: Value;
+    keyframes: KeyframeTracks<Value>;
+    /** Each change plays the keyframes once; without one they repeat while shown (`repeating`). */
+    trigger?: unknown;
+    repeating?: boolean;
+    children: (value: Value) => ReactNode;
+}
+/** The tracks' values `elapsed` seconds in (each track from the initial value through its keyframes). */
+export declare function keyframeValues<Value extends Record<string, number>>(initial: Value, tracks: KeyframeTracks<Value>, elapsed: number): Value;
+export declare function KeyframeAnimator<Value extends Record<string, number>>({ initialValue, keyframes, trigger, repeating, children, }: KeyframeAnimatorProps<Value>): ReactNode;
+//# sourceMappingURL=animators.d.ts.map

package/dist/components/animators.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"animators.d.ts","sourceRoot":"","sources":["../../src/components/animators.tsx"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,gCAAgC,CAAC;AAEhE,OAAO,EAA+B,KAAK,SAAS,EAAE,MAAM,OAAO,CAAC;AAOpE,MAAM,WAAW,kBAAkB,CAAC,KAAK;IACvC,MAAM,EAAE,SAAS,KAAK,EAAE,CAAC;IACzB,6GAA6G;IAC7G,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,yDAAyD;IACzD,SAAS,CAAC,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,SAAS,CAAC;IACxC,QAAQ,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,SAAS,CAAC;CACvC;AAED,wBAAgB,aAAa,CAAC,KAAK,EAAE,EAAE,MAAM,EAAE,OAAO,EAAE,SAAS,EAAE,QAAQ,EAAE,EAAE,kBAAkB,CAAC,KAAK,CAAC,GAAG,SAAS,CAuCnH;AAMD,MAAM,MAAM,aAAa,GAAG,QAAQ,GAAG,OAAO,GAAG,QAAQ,GAAG,MAAM,CAAC;AAEnE,+FAA+F;AAC/F,MAAM,WAAW,QAAQ;IACvB,EAAE,EAAE,MAAM,CAAC;IACX,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,CAAC,EAAE,aAAa,CAAC;CACvB;AAED,MAAM,MAAM,cAAc,CAAC,KAAK,SAAS,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,IAAI;KAAG,CAAC,IAAI,MAAM,KAAK,CAAC,CAAC,EAAE,SAAS,QAAQ,EAAE;CAAE,CAAC;AAEhH,MAAM,WAAW,qBAAqB,CAAC,KAAK,SAAS,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC;IACzE,YAAY,EAAE,KAAK,CAAC;IACpB,SAAS,EAAE,cAAc,CAAC,KAAK,CAAC,CAAC;IACjC,+FAA+F;IAC/F,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,QAAQ,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,SAAS,CAAC;CACvC;AAkBD,yGAAyG;AACzG,wBAAgB,cAAc,CAAC,KAAK,SAAS,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,EAAE,cAAc,CAAC,KAAK,CAAC,EAAE,OAAO,EAAE,MAAM,GAAG,KAAK,CAsB1I;AAMD,wBAAgB,gBAAgB,CAAC,KAAK,SAAS,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EAAE,EACrE,YAAY,EACZ,SAAS,EACT,OAAO,EACP,SAAS,EACT,QAAQ,GACT,EAAE,qBAAqB,CAAC,KAAK,CAAC,GAAG,SAAS,CA+B1C"}

package/dist/components/canvas.d.ts

@@ -0,0 +1,138 @@
+/**
+ * `Canvas`: a `GeometryReader` whose content, at the reported size, is a
+ * `canvas` element. The renderer function draws into a `GraphicsContext`
+ * that records commands, as Sources/SwiftUI/API/Canvas.swift does; the page
+ * draws them as SVG.
+ */
+import type { CanvasCommand, CanvasFilter } from '@swiftbrowser/web/src/protocol';
+import { type ReactNode } from 'react';
+import { type ViewModifiers } from '../modifiers';
+import type { Path, Point } from '../path';
+import { type ColorValue, type FontValue, type StyleValue, type UnitPointValue } from '../values';
+type Matrix = [number, number, number, number, number, number];
+/** A shading in the drawing's coordinates: a style, or a gradient between two points. */
+export type Shading = StyleValue | {
+    linearGradient: {
+        colors?: ColorValue[];
+        stops?: {
+            color: ColorValue;
+            location: number;
+        }[];
+        start: Point;
+        end: Point;
+    };
+} | {
+    radialGradient: {
+        colors?: ColorValue[];
+        stops?: {
+            color: ColorValue;
+            location: number;
+        }[];
+        center: Point;
+        startRadius: number;
+        endRadius: number;
+    };
+};
+export interface StrokeOptions {
+    lineWidth?: number;
+    lineCap?: 'butt' | 'round' | 'square';
+    lineJoin?: 'miter' | 'round' | 'bevel';
+    miterLimit?: number;
+    dash?: number[];
+    dashPhase?: number;
+}
+/** What a canvas image is: a symbol, a catalog image, or a remote image of a known size. */
+export type CanvasImage = {
+    systemName: string;
+} | {
+    name: string;
+} | {
+    url: string;
+    width: number;
+    height: number;
+};
+/** A view passed in `Canvas`'s `symbols`, resolved by its id. */
+export interface ResolvedSymbol {
+    symbol: string;
+}
+/** Where a symbol was drawn: the point (the context's transform applied) and the look at that moment. */
+export interface SymbolDraw {
+    id: string;
+    x: number;
+    y: number;
+    rotation: number;
+    scale: {
+        x: number;
+        y: number;
+    };
+    opacity: number;
+}
+/** `GraphicsContext`: what `Canvas`'s renderer draws with. Methods return the context for chaining. */
+export declare class GraphicsContext {
+    readonly size: {
+        width: number;
+        height: number;
+    };
+    readonly commands: CanvasCommand[];
+    readonly symbolDraws: SymbolDraw[];
+    private symbolIds;
+    /** @internal The ids `symbols` gave the canvas. */
+    setSymbols(ids: Iterable<string>): void;
+    /** `resolveSymbol(id:)`: the view the canvas was given under `id`, or null. */
+    resolveSymbol(id: string): ResolvedSymbol | null;
+    /**
+     * `draw(symbol, at:)`: the symbol's view centered on the point. Symbols are
+     * views laid over the drawing, so they draw above its other commands.
+     */
+    drawSymbol(symbol: ResolvedSymbol, at: Point): this;
+    private state;
+    constructor(size: {
+        width: number;
+        height: number;
+    });
+    get opacity(): number;
+    set opacity(value: number);
+    get blendMode(): string | undefined;
+    set blendMode(value: string | undefined);
+    translateBy(x: number, y: number): this;
+    scaleBy(x: number, y?: number): this;
+    /** Degrees, clockwise on screen. */
+    rotate(degrees: number): this;
+    concatenate(matrix: Matrix): this;
+    clip(to: Path): this;
+    addFilter(filter: CanvasFilter): this;
+    /** `drawLayer { }`: draws with a copy of the state, restored after. */
+    drawLayer(body: (context: GraphicsContext) => void): this;
+    fill(path: Path, with_: Shading, options?: {
+        eoFill?: boolean;
+    }): this;
+    stroke(path: Path, with_: Shading, options?: StrokeOptions | number): this;
+    /** `draw(Text(...), at:anchor:)` */
+    drawText(text: string, at: Point, options?: {
+        anchor?: UnitPointValue;
+        font?: FontValue;
+        color?: StyleValue;
+    }): this;
+    /** `draw(Image(...), at:anchor:)` or `draw(_:in:)` with `size`. */
+    drawImage(image: CanvasImage, at: Point, options?: {
+        anchor?: UnitPointValue;
+        size?: {
+            width: number;
+            height: number;
+        };
+        color?: StyleValue;
+    }): this;
+    private push;
+}
+export interface CanvasProps extends ViewModifiers {
+    /** `Canvas { context, size in }` */
+    renderer: (context: GraphicsContext, size: {
+        width: number;
+        height: number;
+    }) => void;
+    /** `Canvas(renderer:symbols:)`: views the renderer draws by id (`resolveSymbol`, `drawSymbol`). */
+    symbols?: Record<string, ReactNode>;
+}
+export declare function Canvas(props: CanvasProps): ReactNode;
+export {};
+//# sourceMappingURL=canvas.d.ts.map

package/dist/components/canvas.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"canvas.d.ts","sourceRoot":"","sources":["../../src/components/canvas.tsx"],"names":[],"mappings":"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"}