Primitives / foldkit-primitives

Rules every primitive keeps

These hold across the package, so the subpath pages do not repeat them.

  • A fact that changed nothing returns the Model it was given. A repeated resize, Started while running, a total already held: the placement then returns the parent unchanged, Foldkit renders nothing, and a createLazy view over the slice is skipped.
  • Init is a safe default, not a read. matches: false, online: true, a count of zero. A server render shows these; the subscription corrects them on the client. Do not infer readiness from the default.
  • Without the platform API, nothing throws. A stream is empty and the slice keeps its default; a Command yields its failure Message (CopyFailed, ShareFailed); a Mount emits nothing.
  • One placement observes once. Two placements of one query open two listeners; share the field. One assembly holds one socket, stream, camera, or permission watch: their resource tags are per module, and assemble refuses the second.
  • An OutMessage cannot be dropped by omission. debounce, Throttle, Press, DismissLayer, and the rest that surface a settled value require onOut at placement. Bundle.ignore drops one on purpose.
  • Everything timed runs on Effect's clock. Timers, tweens, debounces, presence, idle, typeahead. Tests advance them with TestClock.adjust instead of waiting.
  • Reduced motion is a service. Provide Motion.live through the assembly's resources, or Motion.reduced and Motion.full in a test; absent, motion is full.
  • Elements never cross into the Model. A focus report is { tag, id }, a mutation names nodes, a target is its marked id.

Testing a placement

Three ingredients, each shown in this package's test/ directory under the primitive's name:

  1. Substitute the environment. Factories take a create (streams, devices, permissions, sockets) or request (camera) double, so a test passes a fake instead of stubbing a global.
  2. Advance time instead of waiting. Anything on Effect's clock runs under TestClock.adjust. Yield after forking before the first adjust, or dispatched events reach listeners not yet registered.
  3. Never hang on a quiet stream. Collect with a bounded take that fails fast naming the stall.

With Surface and Mirror

Placed state is ordinary Model, so nothing here has a Surface or Mirror API of its own. Declare a Surface over the placed fields to render them or expose them to an agent; point Mirror.url at them to link them; spread the bundle's cases into the same unions. A slice that must survive a reload persists through Mirror.kv; this package owns live facts only.

Limits

  • Presets cover the common media queries; anything else passes args.
  • Virtual windows one axis of a list; windowed grids stay out by design.
  • Sync.lww-style merging, collaborative text, and other replicated state are foldkit-sync's, not a primitive.