foldkit-primitives 0.2.0 → 0.2.1

package/README.md

@@ -1,6 +1,6 @@
 # `foldkit-primitives`
 
-Ready-made [`foldkit-bundle`](./bundle) primitives: media queries, breakpoints,
+Ready-made [`foldkit-bundle`](../bundle) primitives: media queries, breakpoints,
 presence, timers, intervals, debounce, tweens, springs, pagination, history,
 locales, selections, ranges, geolocation, cameras, permissions, sockets,
 broadcasts, observers, and clipboard. Most are ordinary bundles — Model,
@@ -33,6 +33,15 @@ package depends on `foldkit-bundle` and nothing else (besides peers).
 | One-shot actions | Command, not a bundle | clipboard copy, share, script load |
 | Derived data | pure function, not a bundle | range, relative time, platform |
 
+Choose by what you need to own. State that outlives the moment — a match,
+a count, a page, a position — wants a bundle: the Model keeps it, replay
+sees it. A stream you only react to wants an entry: map it into the
+parent's Message and keep nothing. Work bound to one element wants a
+Mount. Work that runs once and reports back wants a Command. A value
+computed from data you already have wants a pure function. When in doubt,
+start with the lighter form; promote to a bundle the day the state needs
+a name in the Model.
+
 A bundle holds no state and performs no I/O by itself. The parent Model owns
 the placed slice; the browser (or server, or clock) only reports facts as
 Messages. The same rule as everywhere else: observation is not ownership.
@@ -69,6 +78,20 @@ pnpm add foldkit-primitives foldkit-bundle effect foldkit
 `foldkit-primitives/events`, `foldkit-primitives/observers`, `foldkit-primitives/dom` —
 so bundlers drop the primitives you never import.
 
+## Map of the package
+
+Each subpath is one concern, one import:
+
+- `media` — environment facts: MediaQuery (+presets), Breakpoints, platform
+- `net` — remote facts: Online, WebSocket, SSE, BroadcastChannel
+- `time` — clock facts: Timer, Interval, Debounce, Throttle, relative time
+- `state` — owned UI state: Pagination, History, Locale, SelectionSet, Virtual, range
+- `motion` — animation state: Tween, Spring, Presence
+- `device` — hardware: Geolocation, MediaDevices, MediaStream, Permissions, Fullscreen
+- `events` — raw browser events: Visibility, WindowSize, Idle, keyboard, pointer, scroll, focus
+- `observers` — element Mounts: Resize, Intersection, Mutation, Bounds
+- `dom` — element Mounts and one-shot Commands: Autofocus, InputMask, clipboard, share, script loading
+
 ## Sixty seconds: follow the color scheme
 
 **Declare where it lives.** A declaration names the Model field and the
@@ -105,13 +128,29 @@ const config = placements.complete({
 
 `update` routes `GotDarkMessage` to the bundle; `subscriptions` runs the
 `matchMedia` stream; `initial` starts `matches` at `false` and the stream
-corrects it on subscribe. The Solid equivalent this replaces:
+corrects it on subscribe. None of the placement calls perform I/O:
+`declare` names a slot, `at` binds config to it, `assemble` derives the
+folding and the streams — the browser is touched only when the runtime
+subscribes. The Solid equivalent this replaces:
 
 ```ts
 // solid-primitives: const dark = createMediaQuery('(prefers-color-scheme: dark)')
 // Here the fact lives in the Model: replay, DevTools, and time travel see it.
 ```
 
+## Composing placements
+
+One assembly holds every placement: spread its update, init,
+subscriptions, and resources once per application, as above. Two
+placements of one bundle observe twice — share the field instead, so one
+stream feeds every reader. One assembly holds one socket, stream, or
+watch: resource tags are per module, and `assemble` refuses the second.
+Bundles whose settled value is the whole point (`Debounce`, `Throttle`)
+surface it as an OutMessage the placement handles with `onOut`, so the
+signal can never be dropped by omission. Entries lift with
+`Subscription.persistent`, mapping into the parent's Message; Mounts
+attach in views with `h.OnMount`.
+
 ## Media: `foldkit-primitives/media`
 
 > Reference: [`./media/README.md`](./media/README.md)
@@ -403,15 +442,6 @@ browser), restored through a `MirrorRestored` Message the application
 reduces. Nothing here duplicates it — reach for the mirror when a slice
 should survive reload, and keep this package's bundles for live facts.
 
-## With Surface and Mirror
-
-Placed state is ordinary Model, so the surrounding tools apply unchanged —
-no bundle-specific Surface or Mirror API exists, by design. 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. The field refs and wrapper Messages are the same ones the rest of the
-application uses.
-
 ## Motion: `foldkit-primitives/motion`
 
 > Reference: [`./motion/README.md`](./motion/README.md)
@@ -455,6 +485,15 @@ forking before the first `TestClock.adjust`, or dispatched events hit
 unregistered listeners. Each ingredient is demonstrated in this package's
 `test/` directory, named after its primitive.
 
+## With Surface and Mirror
+
+Placed state is ordinary Model, so the surrounding tools apply unchanged —
+no bundle-specific Surface or Mirror API exists, by design. 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. The field refs and wrapper Messages are the same ones the rest of the
+application uses.
+
 ## Failure and recovery
 
 | Failure | Behaviour |

package/dist/device/index.d.mts

@@ -59,7 +59,7 @@ export declare const GeolocationMessage: import("foldkit/message").MessageUnion<
 }>;
 export type GeolocationMessage = typeof GeolocationMessage.Type;
 export declare const Geolocation: Bundle.Bundle<"Geolocation", void, {
-  readonly status: "unknown" | "denied" | "ready";
+  readonly status: "unknown" | "ready" | "denied";
   readonly coords: {
     readonly latitude: number;
     readonly longitude: number;
@@ -67,6 +67,8 @@ export declare const Geolocation: Bundle.Bundle<"Geolocation", void, {
   } | null;
   readonly lastError: string | null;
 }, {
+  readonly _tag: "Denied";
+} | {
   readonly _tag: "Failed";
   readonly message: string;
 } | {
@@ -74,8 +76,6 @@ export declare const Geolocation: Bundle.Bundle<"Geolocation", void, {
   readonly latitude: number;
   readonly longitude: number;
   readonly accuracy: number;
-} | {
-  readonly _tag: "Denied";
 }, never, never, never, void, {}, {}>;
 //#endregion
 //#region src/device/media-devices.d.ts
@@ -130,7 +130,7 @@ export declare const mediaDevices: <const Name extends string>(config: {
   /** Read lazily so tests can substitute a double, like the SSE bundle. */
   readonly create?: ((navigator: Navigator) => MediaDevicesHandle | null) | undefined;
 }) => Bundle.Bundle<Name, void, {
-  readonly status: "unknown" | "denied" | "ready";
+  readonly status: "unknown" | "ready" | "denied";
   readonly devices: readonly {
     readonly deviceId: string;
     readonly groupId: string;
@@ -139,8 +139,6 @@ export declare const mediaDevices: <const Name extends string>(config: {
   }[];
   readonly lastError: string | null;
 }, {
-  readonly _tag: "Denied";
-} | {
   readonly _tag: "Failed";
   readonly message: string;
 } | {
@@ -155,6 +153,8 @@ export declare const mediaDevices: <const Name extends string>(config: {
     readonly kind: "audioinput" | "audiooutput" | "videoinput";
     readonly label: string;
   }[];
+} | {
+  readonly _tag: "Denied";
 }, never, never, never, void, {}, {}>;
 //#endregion
 //#region src/device/media-stream.d.ts
@@ -288,20 +288,20 @@ export declare const permissions: <const Name extends string>(config: {
   readonly names: ReadonlyArray<string>;
 }, {
   readonly states: {
-    readonly [x: string]: "granted" | "denied" | "prompt";
+    readonly [x: string]: "denied" | "granted" | "prompt";
   };
   readonly lastError: string | null;
 }, {
   readonly _tag: "Changed";
   readonly name: string;
-  readonly state: "granted" | "denied" | "prompt";
+  readonly state: "denied" | "granted" | "prompt";
 } | {
   readonly _tag: "Failed";
   readonly message: string;
 } | {
   readonly _tag: "Snapshot";
   readonly states: {
-    readonly [x: string]: "granted" | "denied" | "prompt";
+    readonly [x: string]: "denied" | "granted" | "prompt";
   };
 } | {
   readonly _tag: "Cleared";

package/dist/net/index.d.mts

@@ -106,14 +106,14 @@ export declare const sse: <const Name extends string>(config: {
   readonly status: "closed" | "connecting" | "open";
   readonly lastError: string | null;
 }, {
-  readonly _tag: "Received";
-  readonly data: string;
-} | {
   readonly _tag: "Connecting";
 } | {
   readonly _tag: "Opened";
 } | {
   readonly _tag: "Closed";
+} | {
+  readonly _tag: "Received";
+  readonly data: string;
 } | {
   readonly _tag: "Failed";
   readonly message: string;
@@ -179,11 +179,11 @@ export declare const websocket: <const Name extends string>(config: {
   readonly _tag: "Connecting";
 } | {
   readonly _tag: "Opened";
-} | {
-  readonly _tag: "Closed";
 } | {
   readonly _tag: "Received";
   readonly data: string;
+} | {
+  readonly _tag: "Closed";
 } | {
   readonly _tag: "Failed";
   readonly message: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "foldkit-primitives",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "description": "Ready-made primitives for the Elm architecture, packaged with foldkit-bundle: media queries, presence, timers, pagination, history, sockets, observers, and clipboard.",
   "keywords": [
     "foldkit",