@playfast/reform 1.0.1 → 1.2.0

package/src/compose/structure.ts

@@ -1,125 +1,161 @@
-import { Struct } from 'effect'
+import { Option, Struct } from 'effect'
+import { reuse } from '../internal/reuse'
 import type { SlotProps } from './slot'
 import type { EventsOf, UiContract } from './ui'
 
-/**
- * Structure-as-data (the headless-structure keystone). A composition's logic
- * body returns this *value* instead of a React node: pure, serializable data that
- * describes — for this frame — the composition's own props and, per declared slot,
- * how that slot is filled (a list / a singleton / absent). The engine, the wire
- * server, and the proof harness consume this directly, so none of them needs to
- * evaluate a view or import React to discover structure. Presentation (React)
- * resolves a contract's markup separately, by name, on a host.
- *
- * `live` accepts BOTH a `Node` (legacy view body) and a `Structure` during the
- * migration; hosts discriminate at runtime via {@link isStructure}.
- */
-
-/** A list slot fill: one keyed entry per item. `key` is the SINGLE source of both
- *  the wire `key` and the per-item `StateFamily` key — they can no longer drift. */
 export interface EachFill<P> {
   readonly _tag: 'Each'
   readonly items: ReadonlyArray<{ readonly key: string; readonly props: P }>
 }
 
-/** A singleton slot fill — the slot renders exactly one child with these props. */
 export interface OneFill<P> {
   readonly _tag: 'One'
   readonly props: P
 }
 
-/** A slot that renders nothing this frame (the data-driven analog of `cond && …`). */
 export interface AbsentFill {
   readonly _tag: 'Absent'
 }
 
-/** How one declared slot is filled this frame, typed by the child's external props. */
 export type SlotFill<P> = EachFill<P> | OneFill<P> | AbsentFill
 
-/** The per-slot fill map a contract's structure carries — one fill per declared slot,
- *  each typed by that child composition's external props (`SlotProps`). Empty when the
- *  contract declares no slots. */
 export type StructureSlots<C extends UiContract> = C extends {
   slots: infer S
 }
   ? { readonly [K in keyof S]: SlotFill<SlotProps<S[K]>> }
-  : Record<never, never>
-
-/**
- * The data a composition's logic returns for one frame: its computed props plus,
- * for every declared slot, a fill description. Strict against the contract — props
- * must match, and every declared slot must be filled (use {@link when} for
- * conditional presence). Carries the child's contract per slot (via `SlotProps`),
- * so consumers can select and descend into sub-compositions type-safely.
- *
- * `events` rides ON the structure: because a `mount(...)`-returning body never
- * calls its view, the event triggers it acquired (`yield* Event.trigger(X)`) are
- * no longer captured by a view's `CaptureSink` record — they must travel with the
- * frame so hosts can register them (proof `actions`, the wire `TriggerRegistry`,
- * the react presentation `events` arg). Triggers are functions, so `events` is NOT
- * serializable and is intentionally excluded from {@link structureEquals}. Typed to
- * the contract's event map; omit it (defaults to `{}`) when the contract has none.
- */
-export interface Structure<C extends UiContract> {
+  : Readonly<Record<PropertyKey, never>>
+
+interface SerializableFrame<C extends UiContract> {
   readonly props: C['props']
   readonly slots: StructureSlots<C>
-  // oxlint-disable-next-line reform-rules/no-optional-fields -- serializable frame shape; triggers ride optionally and the field is intentionally omitted from structureEquals
-  readonly events?: EventsOf<C>
 }
 
-/** Runtime brand distinguishing a `Structure` value from a React `Node` (added by
- *  {@link mount}; the authoring TYPE intentionally omits it so structure literals stay
- *  plain). */
+interface TriggeredFrame<C extends UiContract> extends SerializableFrame<C> {
+  readonly events: EventsOf<C>
+}
+
+type MountFrame<C extends UiContract> = SerializableFrame<C> | TriggeredFrame<C>
+
 export const StructureTypeId: unique symbol = Symbol.for('reform/Structure')
 export type StructureTypeId = typeof StructureTypeId
 
-/**
- * Assemble a frame's structure, checked against the contract `C`. Identity at
- * runtime apart from stamping the {@link StructureTypeId} brand; its real job is
- * the compile-time contract check. `C` is recovered from the surrounding `live`
- * body's return type (contextual typing), so call sites read `mount({ props, slots })`.
- * A leaf composition (no declared slots) passes `slots: {}`. `events` defaults to an
- * empty map when omitted, so a frame always carries an `events` record for hosts.
- */
-export const mount = <C extends UiContract>(structure: Structure<C>): Structure<C> =>
-  // oxlint-disable-next-line reform-rules/no-object-assign -- merge infers the empty `events` default as EventsOf<C>; a spread would force an `as` cast instead
-  Object.assign({ [StructureTypeId]: StructureTypeId, events: {} }, structure)
-
-/**
- * A list slot fill. `key` derives the stable identity for BOTH the wire node and
- * the per-item state family — passing the same id source to both is no longer
- * possible to get wrong. `props` maps each item to the child's external props.
- */
+export interface Structure<C extends UiContract> {
+  readonly [StructureTypeId]: StructureTypeId
+  readonly props: C['props']
+  readonly slots: StructureSlots<C>
+  readonly events: EventsOf<C> | undefined
+}
+
+const frameEvents = <C extends UiContract>(frame: MountFrame<C>): Option.Option<EventsOf<C>> =>
+  'events' in frame ? Option.some(frame.events) : Option.none<EventsOf<C>>()
+
+export const mount = <C extends UiContract>(frame: MountFrame<C>): Structure<C> => ({
+  events: Option.getOrUndefined(frameEvents(frame)),
+  props: frame.props,
+  slots: frame.slots,
+  [StructureTypeId]: StructureTypeId,
+})
+
 export interface EachOptions<T, P> {
   readonly key: (item: T) => string
   readonly props: (item: T) => P
 }
 
-export const each = <T, P>(collection: Iterable<T>, options: EachOptions<T, P>): EachFill<P> => ({
+interface EachRetention {
+  readonly elements: ReadonlyArray<unknown>
+  readonly fill: unknown
+}
+
+interface CollectionRetentions {
+  readonly byProps: WeakMap<object, WeakMap<object, EachRetention>>
+}
+
+// Stable collection and callback identities retain unchanged fills by reference.
+const eachRetentions = new WeakMap<object, CollectionRetentions>()
+const latestEachRetentions = new WeakMap<object, EachRetention>()
+
+const hasIdentity = (candidate: unknown): candidate is object =>
+  (typeof candidate === 'object' && candidate !== null) || typeof candidate === 'function'
+
+const collectionRetentionsFor = (collection: unknown): CollectionRetentions | undefined => {
+  if (!hasIdentity(collection)) {
+    return undefined
+  }
+  return (
+    eachRetentions.get(collection) ?? {
+      byProps: new WeakMap<object, WeakMap<object, EachRetention>>(),
+    }
+  )
+}
+
+const sameElements = (previous: ReadonlyArray<unknown>, next: ReadonlyArray<unknown>): boolean =>
+  previous.length === next.length &&
+  previous.every((element, index) => Object.is(element, next[index]))
+
+const isEachFill = <P>(candidate: unknown): candidate is EachFill<P> =>
+  isRecord(candidate) &&
+  candidate['_tag'] === 'Each' &&
+  Array.isArray(candidate['items']) &&
+  candidate['items'].every(
+    (entry) => isRecord(entry) && typeof entry['key'] === 'string' && 'props' in entry,
+  )
+
+const materializeEach = <T, P>(
+  elements: ReadonlyArray<T>,
+  options: EachOptions<T, P>,
+): EachFill<P> => ({
   _tag: 'Each',
-  items: Array.from(collection, (element) => ({
+  items: elements.map((element) => ({
     key: options.key(element),
     props: options.props(element),
   })),
 })
 
-/** A singleton slot fill — render one child with these external props. */
+const retainEach = <P>(previous: unknown, next: EachFill<P>): EachFill<P> => {
+  if (!isEachFill<P>(previous)) {
+    return next
+  }
+  if (deepEquals({ left: previous, right: next })) {
+    return previous
+  }
+  return reuse(previous, next)
+}
+
+export const each = <T, P>(collection: Iterable<T>, options: EachOptions<T, P>): EachFill<P> => {
+  const elements = Array.from(collection)
+  const collectionRetentions = collectionRetentionsFor(collection)
+  const retained = collectionRetentions?.byProps.get(options.props)?.get(options.key)
+  const latest = hasIdentity(collection) ? latestEachRetentions.get(collection) : undefined
+  if (
+    retained !== undefined &&
+    sameElements(retained.elements, elements) &&
+    isEachFill<P>(retained.fill)
+  ) {
+    return retained.fill
+  }
+  const fill = retainEach(retained?.fill ?? latest?.fill, materializeEach(elements, options))
+  if (hasIdentity(collection) && collectionRetentions !== undefined) {
+    const byKey =
+      collectionRetentions.byProps.get(options.props) ?? new WeakMap<object, EachRetention>()
+    const retention = { elements, fill }
+    byKey.set(options.key, retention)
+    collectionRetentions.byProps.set(options.props, byKey)
+    eachRetentions.set(collection, collectionRetentions)
+    latestEachRetentions.set(collection, retention)
+  }
+  return fill
+}
+
 export const one = <P>(props: P): OneFill<P> => ({ _tag: 'One', props })
 
-/** The shared empty fill — a slot that renders nothing this frame. */
 export const absent: AbsentFill = { _tag: 'Absent' }
 
-/** Conditional presence: the fill when `cond`, otherwise {@link absent}. */
 export const when = <F extends SlotFill<unknown>>(cond: boolean, fill: F): F | AbsentFill =>
   cond ? fill : absent
 
-/** Whether a frame value is a `Structure` (vs a legacy React `Node`). The runtime
- *  discriminator hosts use during the migration, replacing React's `isValidElement`. */
 export const isStructure = (frame: unknown): frame is Structure<UiContract> =>
   typeof frame === 'object' && frame !== null && StructureTypeId in frame
 
-/** Whether a value is a plain record (not an array) — narrows for the deep compare
- *  below without a cast. */
 const isRecord = (candidate: unknown): candidate is Record<string, unknown> =>
   typeof candidate === 'object' && candidate !== null && !Array.isArray(candidate)
 
@@ -128,8 +164,6 @@ interface ValuePair {
   readonly right: unknown
 }
 
-/** Minimal structural deep-equality for serializable shapes (plain JSON — the
- *  UI-contract guarantee). Avoids a heavyweight dep for the settle comparison. */
 const deepEquals = ({ left, right }: ValuePair): boolean => {
   if (Object.is(left, right)) {
     return true
@@ -155,15 +189,10 @@ const deepEquals = ({ left, right }: ValuePair): boolean => {
   return false
 }
 
-/** Structural equality over two structures — props and every slot fill compared by
- *  value. `events` is intentionally excluded: triggers are functions, freshly
- *  acquired each render, so comparing them by identity would never match and would
- *  break the settle fixpoint. The `StructureTypeId` brand is a symbol key, so
- *  `Object.keys` skips it. Used by the proof/server settle loop to detect a
- *  two-frame fixpoint. */
 export const structureEquals = (
   left: Structure<UiContract>,
   right: Structure<UiContract>,
 ): boolean =>
+  // Events are fresh trigger functions, so equality covers serializable frame data only.
   deepEquals({ left: left.props, right: right.props }) &&
   deepEquals({ left: left.slots, right: right.slots })

package/src/compose/ui.test.ts

@@ -1,10 +1,6 @@
-import { expect, test } from 'vitest'
-import { Schema as S } from 'effect'
-import { isUi, ui } from '../index'
-
-// `ui` has two authoring forms with one source of truth each: the type-only form
-// (local, no schema) and the schema form (wired, the type is *derived*). Both are
-// the same contract at runtime; only the wired form carries reflectable schemas.
+import { expect, it, test } from '@effect/vitest'
+import { Effect, Layer, Schema as S } from 'effect'
+import { isUi, provide, Ui, ui } from '../index'
 
 test('type-only `ui` carries no wire schema', () => {
   class CounterUi extends ui('Counter')<{ props: { count: number } }>() {}
@@ -32,3 +28,19 @@ test('schema `ui` with no events omits the events schema', () => {
   expect(S.isSchema(TitleUi.manifest.props)).toBe(true)
   expect(TitleUi.manifest.events).toBeUndefined()
 })
+
+it.live('same-shaped UI definitions resolve their own views', () => {
+  class FirstUi extends ui('UiNominalFirst')<{ props: { label: string } }>() {}
+  class SecondUi extends ui('UiNominalSecond')<{ props: { label: string } }>() {}
+  const FirstView = Ui.make(FirstUi, ({ label }) => `first:${label}`)
+  const SecondView = Ui.make(SecondUi, ({ label }) => `second:${label}`)
+  const Live = Layer.mergeAll(provide(FirstUi, FirstView), provide(SecondUi, SecondView))
+
+  return Effect.gen(function* () {
+    const first = yield* FirstUi.impl
+    const second = yield* SecondUi.impl
+
+    expect(first({ label: 'value' }, {}, {})).toBe('first:value')
+    expect(second({ label: 'value' }, {}, {})).toBe('second:value')
+  }).pipe(Effect.provide(Live))
+})