stylegallery 0.1.4 → 0.1.7

package/design-engineering/state-management/patterns/derived-state.md

@@ -0,0 +1,85 @@
+---
+type: Domain Guide
+title: Derived State From Authoritative Inputs
+description: Prevent totals, filtered lists, and dirty flags from drifting away from their inputs.
+domain: design-engineering
+lifecycle: experimental
+provenance_kind: local
+---
+
+# Derived State From Authoritative Inputs
+
+## Repository Boundary
+
+Prevent totals, filtered lists, and dirty flags from drifting away from their inputs. This pattern belongs to Design Engineering and adds no Layout CSS or shared store implementation.
+
+## Reusable Method
+
+Use when a value is a deterministic projection of current inputs. Store historical snapshots when the task explicitly needs what was true at a previous event; those are not redundant current projections.
+
+### State Model And Ownership
+
+Only source items and filter are writable. Visible items and total are computed. Memoization is optional and must include every dependency; its lifetime cannot change meaning.
+
+### Transitions
+
+| Event and precondition | Next state | Effect or invariant |
+| --- | --- | --- |
+| Items change | New items | Recompute projection from current inputs |
+| Filter changes | New filter | Project without mutating items |
+| No matching items | Empty projection | Total is zero, not a separate empty flag |
+
+### Minimal Executable Example
+
+Run this standalone JavaScript block with Node.js 22 or newer, or run all pattern examples from a repository checkout with `npm run test:state-management`. The assertions exercise the local model, not a browser or backend.
+
+```js
+import assert from "node:assert/strict";
+let items = [{ id: "a", price: 5 }, { id: "b", price: 12 }];
+let minimum = 10;
+const visible = () => items.filter(item => item.price >= minimum);
+const total = () => visible().reduce((sum, item) => sum + item.price, 0);
+assert.equal(total(), 12);
+items = items.map(item => item.id === "b" ? { ...item, price: 7 } : item);
+assert.deepEqual(visible(), []);
+assert.equal(total(), 0);
+minimum = 0;
+assert.equal(total(), 12);
+```
+
+### What Breaks If Removed
+
+An independently updated total can miss a deletion, filter change, or remote refresh. A memo keyed only by items stays stale after changing the filter.
+
+### Composition And Substitution
+
+Combine with [ID selection](id-selection.md); derive the selected object from the current collection. Keep [submitted snapshots](submitted-snapshot.md) because they represent a past event.
+
+## Opinionated Guidance
+
+Write down the projection before introducing another writable field. Define domain equality explicitly for dirty checks involving normalized dates, numbers, or nested data.
+
+## Platform-Specific Guidance
+
+Framework memo and selector APIs have different invalidation rules. Verify dependency coverage and immutable update assumptions in the chosen adapter.
+
+## Unsupported Absolutes
+
+Recomputing every projection is not always cheap; storing a cache can be valid if its invalidation contract is explicit.
+
+## Verification Contract
+
+- Change each dependency independently and inspect the projection.
+- Delete the final matching item and verify the empty result and zero total.
+- If memoized, repeat with unchanged references and changed filter inputs.
+
+Record actual outcomes separately using the [verification matrix](../verification.md).
+
+## Source, License, And Attribution
+
+Locally authored synthesis and examples. No upstream implementation is copied. These experimental contracts describe consumer-owned behavior; review when a failure, ownership change, or platform change invalidates an assumption.
+
+## IA Navigation
+
+Parent: [State Management](../index.md).
+Next: [Continue the state management route](../recipes/index.md).

package/design-engineering/state-management/patterns/draft-and-baseline.md

@@ -0,0 +1,86 @@
+---
+type: Domain Guide
+title: Draft And Persisted Baseline
+description: Preserve editable work while distinguishing it from the last acknowledged saved value.
+domain: design-engineering
+lifecycle: experimental
+provenance_kind: local
+---
+
+# Draft And Persisted Baseline
+
+## Repository Boundary
+
+Preserve editable work while distinguishing it from the last acknowledged saved value. This pattern belongs to Design Engineering and adds no Layout CSS or shared store implementation.
+
+## Reusable Method
+
+Use for explicit Save/Cancel forms. For immediate committed toggles, use an operation contract instead of inventing a long-lived draft.
+
+### State Model And Ownership
+
+The form owns a draft, persistence supplies the baseline, and dirty is derived using domain equality. This example uses a single string. A remote update while dirty needs merge, conflict, or reload policy; never silently replace the draft.
+
+### Transitions
+
+| Event and precondition | Next state | Effect or invariant |
+| --- | --- | --- |
+| Edit | Draft changes | Baseline stays acknowledged |
+| Discard | Draft becomes baseline | No persistence request |
+| Remote update while dirty | Conflict retained | Keep draft until the user resolves it |
+
+### Minimal Executable Example
+
+Run this standalone JavaScript block with Node.js 22 or newer, or run all pattern examples from a repository checkout with `npm run test:state-management`. The assertions exercise the local model, not a browser or backend.
+
+```js
+import assert from "node:assert/strict";
+let baseline = "Original";
+let draft = baseline;
+const dirty = () => draft !== baseline;
+draft = "Edited";
+assert.equal(dirty(), true);
+const remote = "Remote edit";
+const conflict = dirty() && remote !== baseline;
+assert.equal(conflict, true);
+assert.equal(draft, "Edited");
+draft = baseline; // Explicit discard, not an automatic refresh.
+assert.equal(dirty(), false);
+```
+
+### What Breaks If Removed
+
+Binding fields directly to the cached saved object makes Cancel impossible and may tell other readers that unsaved edits are persisted. An independent dirty boolean can remain true after editing back to the baseline.
+
+### Composition And Substitution
+
+[Submitted snapshot](submitted-snapshot.md) owns save acknowledgement. [Unsaved navigation](unsaved-navigation.md) uses dirty as an input. Do not let the router own a second draft.
+
+## Opinionated Guidance
+
+Choose baseline equality and server normalization rules before wiring a generic deep comparison. For nested drafts, prevent shared mutable references to the baseline.
+
+## Platform-Specific Guidance
+
+Use native form labels and validation relationships. Route-level forms may outlive individual fields; unmounting a field should not implicitly discard the form.
+
+## Unsupported Absolutes
+
+A baseline is an acknowledged observation, not a guarantee that nobody else edited the server since then.
+
+## Verification Contract
+
+- Edit then restore the original value; dirty must become false.
+- Receive a remote update while dirty; preserve entered values.
+- Discard explicitly; restore the acknowledged baseline without sending a save.
+
+Record actual outcomes separately using the [verification matrix](../verification.md).
+
+## Source, License, And Attribution
+
+Locally authored synthesis and examples. No upstream implementation is copied. These experimental contracts describe consumer-owned behavior; review when a failure, ownership change, or platform change invalidates an assumption.
+
+## IA Navigation
+
+Parent: [State Management](../index.md).
+Next: [Continue the state management route](../recipes/index.md).

package/design-engineering/state-management/patterns/id-selection.md

@@ -0,0 +1,85 @@
+---
+type: Domain Guide
+title: Selection By Stable Identity
+description: Keep selection attached to an entity while a collection reorders or refreshes.
+domain: design-engineering
+lifecycle: experimental
+provenance_kind: local
+---
+
+# Selection By Stable Identity
+
+## Repository Boundary
+
+Keep selection attached to an entity while a collection reorders or refreshes. This pattern belongs to Design Engineering and adds no Layout CSS or shared store implementation.
+
+## Reusable Method
+
+Use for lists, tables, and detail views with stable IDs. Index selection is sufficient only for immutable position-based options whose identity truly is their position.
+
+### State Model And Ownership
+
+The screen owns `selectedId`; the data owner supplies current entities. Detail is derived by ID. Missing from a filtered page does not imply deletion: choose a retained-detail fetch or an unavailable state based on actual knowledge.
+
+### Transitions
+
+| Event and precondition | Next state | Effect or invariant |
+| --- | --- | --- |
+| Select an available ID | ID selected | Resolve current entity by identity |
+| Collection reorders | Same ID | Detail still belongs to the same entity |
+| Authoritative deletion removes ID | Null or unavailable | Apply the declared fallback and recover focus |
+
+### Minimal Executable Example
+
+Run this standalone JavaScript block with Node.js 22 or newer, or run all pattern examples from a repository checkout with `npm run test:state-management`. The assertions exercise the local model, not a browser or backend.
+
+```js
+import assert from "node:assert/strict";
+let rows = [{ id: "a", name: "Alpha" }, { id: "b", name: "Beta" }];
+let selectedId = "b";
+const selected = () => rows.find(row => row.id === selectedId) ?? null;
+rows = [...rows].reverse();
+assert.equal(selected().name, "Beta");
+rows = rows.map(row => row.id === "b" ? { ...row, name: "Updated" } : row);
+assert.equal(selected().name, "Updated");
+rows = rows.filter(row => row.id !== "b");
+if (!selected()) selectedId = null; // This collection is authoritative and complete.
+assert.equal(selected(), null);
+```
+
+### What Breaks If Removed
+
+Keep row index 1, reverse the array, and the detail silently changes to another entity. Keep a copied selected object and a refresh can leave its fields stale.
+
+### Composition And Substitution
+
+Use [URL state](url-state.md) when selection should survive links and history. Use [latest request wins](latest-request-wins.md) for separately fetched detail; key requests by selected ID.
+
+## Opinionated Guidance
+
+Choose an explicit missing-item policy. Never infer remote deletion solely from pagination or filtering.
+
+## Platform-Specific Guidance
+
+After deleting a focused row, move focus to a logical neighbor or heading. A selected state and keyboard focus are separate responsibilities.
+
+## Unsupported Absolutes
+
+Stable keys do not prove stable identity if the server recycles identifiers across tenants or revisions.
+
+## Verification Contract
+
+- Reorder and update the selected row; detail must preserve ID and refresh fields.
+- Filter it out without deleting it; apply the declared retained-detail policy.
+- Delete the final item; verify empty detail and focus recovery in the UI.
+
+Record actual outcomes separately using the [verification matrix](../verification.md).
+
+## Source, License, And Attribution
+
+Locally authored synthesis and examples. No upstream implementation is copied. These experimental contracts describe consumer-owned behavior; review when a failure, ownership change, or platform change invalidates an assumption.
+
+## IA Navigation
+
+Parent: [State Management](../index.md).
+Next: [Continue the state management route](../recipes/index.md).

package/design-engineering/state-management/patterns/identity-reset.md

@@ -0,0 +1,89 @@
+---
+type: Domain Guide
+title: Identity Boundary And Reset
+description: Prevent temporary state and pending outcomes from leaking across entity or account changes.
+domain: design-engineering
+lifecycle: experimental
+provenance_kind: local
+---
+
+# Identity Boundary And Reset
+
+## Repository Boundary
+
+Prevent temporary state and pending outcomes from leaking across entity or account changes. This pattern belongs to Design Engineering and adds no Layout CSS or shared store implementation.
+
+## Reusable Method
+
+Use when a mounted editor is reused for a different document, tenant, or account. Preserve drafts per identity only when that is an explicit product feature.
+
+### State Model And Ownership
+
+The screen owner stores identity and generation. Entering a new identity clears identity-local values and invalidates previous operations. Generation matters even when the user goes A → B → A.
+
+### Transitions
+
+| Event and precondition | Next state | Effect or invariant |
+| --- | --- | --- |
+| Enter identity | Fresh generation and local state | Invalidate earlier callbacks |
+| Matching-generation completion | Apply within current identity | Accept only live work |
+| Old-generation completion | Unchanged | Reject even if the entity ID matches again |
+
+### Minimal Executable Example
+
+Run this standalone JavaScript block with Node.js 22 or newer, or run all pattern examples from a repository checkout with `npm run test:state-management`. The assertions exercise the local model, not a browser or backend.
+
+```js
+import assert from "node:assert/strict";
+let generation = 0, identity = null, draft = "";
+function enter(id) { identity = id; generation++; draft = ""; }
+function ticket() { return { identity, generation }; }
+function receive(t, value) {
+  if (t.identity === identity && t.generation === generation) draft = value;
+}
+enter("A");
+const oldA = ticket();
+enter("B");
+enter("A");
+receive(oldA, "stale A");
+assert.equal(draft, "");
+receive(ticket(), "current A");
+assert.equal(draft, "current A");
+```
+
+### What Breaks If Removed
+
+Checking entity ID alone accepts the old A request after returning from B to A. Resetting the draft without invalidating requests lets a late response repopulate it.
+
+### Composition And Substitution
+
+Combine [latest request wins](latest-request-wins.md) within each generation and [versioned restore](versioned-restore.md) for explicit per-identity persistence. Apply [unsaved navigation](unsaved-navigation.md) before abandoning dirty work.
+
+## Opinionated Guidance
+
+Define the identity tuple, including tenant when needed. Clear sensitive caches at the session boundary rather than relying solely on component unmount.
+
+## Platform-Specific Guidance
+
+Framework keys can recreate components, but external listeners, caches, timers, and requests still need explicit cleanup. Router reuse may preserve component instances.
+
+## Unsupported Absolutes
+
+A UI reset is not an authorization or secure data-erasure mechanism.
+
+## Verification Contract
+
+- Switch A → B while a read is pending; no A result appears in B.
+- Switch A → B → A; reject the first generation's callback.
+- Inspect focus, local errors, draft, and subscriptions after switching.
+
+Record actual outcomes separately using the [verification matrix](../verification.md).
+
+## Source, License, And Attribution
+
+Locally authored synthesis and examples. No upstream implementation is copied. These experimental contracts describe consumer-owned behavior; review when a failure, ownership change, or platform change invalidates an assumption.
+
+## IA Navigation
+
+Parent: [State Management](../index.md).
+Next: [Continue the state management route](../recipes/index.md).

package/design-engineering/state-management/patterns/latest-request-wins.md

@@ -0,0 +1,94 @@
+---
+type: Domain Guide
+title: Latest Request Wins
+description: Prevent an older read response from replacing the result of a newer user intent.
+domain: design-engineering
+lifecycle: experimental
+provenance_kind: local
+---
+
+# Latest Request Wins
+
+## Repository Boundary
+
+Prevent an older read response from replacing the result of a newer user intent. This pattern belongs to Design Engineering and adds no Layout CSS or shared store implementation.
+
+## Reusable Method
+
+Use for replaceable reads such as search and selected-item detail. Do not use this policy to discard the outcomes of independent writes that all matter.
+
+### State Model And Ownership
+
+The read owner stores a monotonically increasing identity, status, and last accepted result. Both success and failure must match the current request. Cancellation is an optional resource optimization; identity decides acceptance.
+
+### Transitions
+
+| Event and precondition | Next state | Effect or invariant |
+| --- | --- | --- |
+| Start read | Pending with new ID | Previous IDs lose authority |
+| Matching success | Ready with results | Accept only current intent |
+| Matching failure | Error | Preserve or clear old results under explicit policy |
+| Stale success or failure | Unchanged | No status, result, or error mutation |
+| Dispose | Disposed and invalidated | Ignore all pending outcomes |
+
+### Minimal Executable Example
+
+Run this standalone JavaScript block with Node.js 22 or newer, or run all pattern examples from a repository checkout with `npm run test:state-management`. The assertions exercise the local model, not a browser or backend.
+
+```js
+import assert from "node:assert/strict";
+let serial = 0, active = 0, status = "idle", result = null;
+const begin = () => { active = ++serial; status = "pending"; return active; };
+function settle(id, ok, value) {
+  if (id !== active) return;
+  status = ok ? "ready" : "error";
+  if (ok) result = value;
+}
+const a = begin(), b = begin();
+settle(b, true, "B");
+settle(a, true, "A");
+settle(a, false, "old failure");
+assert.equal(result, "B");
+assert.equal(status, "ready");
+const c = begin();
+active = ++serial; status = "disposed";
+settle(c, true, "C");
+assert.equal(status, "disposed");
+```
+
+### What Breaks If Removed
+
+Remove the ID check: resolve B then A and the screen displays A under B's query. Guarding success only still allows A's error or finally handler to clear B's pending status.
+
+### Composition And Substitution
+
+Combine [URL state](url-state.md) for committed query inputs and [ID selection](id-selection.md) for detail. Use [single flight](single-flight.md) for duplicate writes rather than silently discarding their acknowledgements.
+
+## Opinionated Guidance
+
+Choose whether old results stay visible while refreshing and label their query identity. Debouncing reduces starts but does not establish response ordering.
+
+## Platform-Specific Guidance
+
+Check identity after each awaited stage, including body decoding or transformations. Dispose invalidation and listener cleanup belong to the framework adapter.
+
+## Unsupported Absolutes
+
+Latest-wins prevents this local overwrite; it does not guarantee fresh server data, cache coherence, or distributed consistency.
+
+## Verification Contract
+
+- Start A then B; resolve B then A, including an A failure.
+- Start B while A is pending; A completion must not clear B's pending indicator.
+- Dispose before completion; no displayed state may update.
+
+Record actual outcomes separately using the [verification matrix](../verification.md).
+
+## Source, License, And Attribution
+
+Locally authored synthesis and examples. No upstream implementation is copied. These experimental contracts describe consumer-owned behavior; review when a failure, ownership change, or platform change invalidates an assumption.
+
+## IA Navigation
+
+Parent: [State Management](../index.md).
+Next: [Continue the state management route](../recipes/index.md).

package/design-engineering/state-management/patterns/optimistic-overlay.md

@@ -0,0 +1,98 @@
+---
+type: Domain Guide
+title: Optimistic Overlay And Recovery
+description: Show a speculative change while preserving an authoritative base for recovery.
+domain: design-engineering
+lifecycle: experimental
+provenance_kind: local
+---
+
+# Optimistic Overlay And Recovery
+
+## Repository Boundary
+
+Show a speculative change while preserving an authoritative base for recovery. This pattern belongs to Design Engineering and adds no Layout CSS or shared store implementation.
+
+## Reusable Method
+
+Use for a bounded reversible presentation change when failure is recoverable. Prefer pending-until-confirmed behavior for irreversible or high-consequence actions.
+
+### State Model And Ownership
+
+The cache owns base; the operation owns an overlay and ID. The displayed value is base plus overlay. This minimal example permits one edit at a time; concurrent mutations require ordered overlays or per-entity serialization.
+
+### Transitions
+
+| Event and precondition | Next state | Effect or invariant |
+| --- | --- | --- |
+| Begin mutation while idle | Overlay pending | Display prediction without rewriting base |
+| Matching rejection | Overlay removed | Reveal current base, not an old whole-cache snapshot |
+| Matching acknowledgement | Base becomes server value | Remove overlay atomically |
+| Uncertain outcome | Reconciliation required | Do not announce rollback of the server |
+
+### Minimal Executable Example
+
+Run this standalone JavaScript block with Node.js 22 or newer, or run all pattern examples from a repository checkout with `npm run test:state-management`. The assertions exercise the local model, not a browser or backend.
+
+```js
+import assert from "node:assert/strict";
+let base = { name: "Before", revision: 1 }, overlay = null, serial = 0;
+const view = () => overlay ? { ...base, name: overlay.name } : base;
+function begin(name) {
+  if (overlay) return null;
+  overlay = { id: ++serial, name };
+  return overlay.id;
+}
+function settle(id, accepted) {
+  if (overlay?.id !== id) return;
+  if (accepted) base = accepted;
+  overlay = null;
+}
+const a = begin("Predicted");
+assert.equal(view().name, "Predicted");
+base = { name: "Remote", revision: 2 }; // A newer authoritative observation.
+settle(a, null); // Definitive rejection, not an ambiguous timeout.
+assert.equal(view().name, "Remote");
+const b = begin("Next");
+settle(a, null);
+assert.equal(view().name, "Next");
+settle(b, { name: "Normalized", revision: 3 });
+assert.equal(view().name, "Normalized");
+```
+
+### What Breaks If Removed
+
+Restoring a whole-cache snapshot on failure can erase unrelated or newer remote changes. Without correlation, an old failure can remove a newer optimistic operation.
+
+### Composition And Substitution
+
+Compose with [single flight](single-flight.md) for this serialized model. Use [ID selection](id-selection.md) for row mutations. Define version ordering before admitting concurrent acknowledgements into a shared cache.
+
+## Opinionated Guidance
+
+Separate a definitive rejection from a lost response: a timeout may have committed remotely. Reconcile uncertain results before promising the change was undone.
+
+## Platform-Specific Guidance
+
+Keep pending and error information available beyond color or animation. A disappearance animation must not decide whether the underlying entity exists.
+
+## Unsupported Absolutes
+
+An inverse UI patch is not a backend undo protocol. The sample does not implement concurrent multi-writer revision arbitration.
+
+## Verification Contract
+
+- Reject a speculative edit after a newer base arrives; preserve the newer base.
+- Deliver an old failure during a new edit; retain the new overlay.
+- Return a normalized server value and verify it replaces the prediction.
+
+Record actual outcomes separately using the [verification matrix](../verification.md).
+
+## Source, License, And Attribution
+
+Locally authored synthesis and examples. No upstream implementation is copied. These experimental contracts describe consumer-owned behavior; review when a failure, ownership change, or platform change invalidates an assumption.
+
+## IA Navigation
+
+Parent: [State Management](../index.md).
+Next: [Continue the state management route](../recipes/index.md).

package/design-engineering/state-management/patterns/single-flight.md

@@ -0,0 +1,92 @@
+---
+type: Domain Guide
+title: Single Flight And Duplicate Submission
+description: Apply an explicit policy to repeated activation of one pending operation.
+domain: design-engineering
+lifecycle: experimental
+provenance_kind: local
+---
+
+# Single Flight And Duplicate Submission
+
+## Repository Boundary
+
+Apply an explicit policy to repeated activation of one pending operation. This pattern belongs to Design Engineering and adds no Layout CSS or shared store implementation.
+
+## Reusable Method
+
+Use when a duplicate Save or Delete should share or ignore the active attempt. Independent entities may need separate flight keys. A queue is preferable when every intent must execute.
+
+### State Model And Ownership
+
+The operation owner holds one pending promise per declared scope. This example shares it. The guard is set before the effect begins and clears on success or failure.
+
+### Transitions
+
+| Event and precondition | Next state | Effect or invariant |
+| --- | --- | --- |
+| Activate while idle | One pending operation | Run effect once |
+| Activate while pending | Same pending operation | Return same promise |
+| Settle | Idle | Release guard on success and failure |
+
+### Minimal Executable Example
+
+Run this standalone JavaScript block with Node.js 22 or newer, or run all pattern examples from a repository checkout with `npm run test:state-management`. The assertions exercise the local model, not a browser or backend.
+
+```js
+import assert from "node:assert/strict";
+let pending = null, calls = 0;
+function run(effect) {
+  if (pending) return pending;
+  pending = Promise.resolve().then(effect).finally(() => { pending = null; });
+  return pending;
+}
+let release;
+const effect = () => { calls++; return new Promise(resolve => { release = resolve; }); };
+const a = run(effect), b = run(effect);
+assert.equal(a, b);
+await Promise.resolve();
+assert.equal(calls, 1);
+release("saved");
+await a;
+await assert.rejects(run(() => { throw new Error("offline"); }));
+assert.equal(pending, null);
+assert.equal(await run(() => "retry"), "retry");
+```
+
+### What Breaks If Removed
+
+Disabling only the visible button misses keyboard submission or another caller. Setting pending after awaiting the effect permits two operations. Clearing only on success locks the action after a failure.
+
+### Composition And Substitution
+
+Use with [submitted snapshot](submitted-snapshot.md); duplicate activation must not silently replace the captured snapshot. For separate rows, scope the guard by stable entity ID.
+
+## Opinionated Guidance
+
+Pick ignore, share, queue, or replace deliberately. This example shares a result and does not implement queuing. After an ambiguous write failure, reconcile or use server-supported idempotency before retrying.
+
+## Platform-Specific Guidance
+
+Handle every caller's rejection and expose progress through accessible status. UI disabled semantics do not replace the operation guard.
+
+## Unsupported Absolutes
+
+One client promise cannot prevent another tab, device, or retry from executing the same server command.
+
+## Verification Contract
+
+- Activate from two entry points in the same turn; effect count remains one.
+- Fail the operation; a subsequent explicit attempt can start.
+- For per-entity scope, verify different entities do not block each other.
+
+Record actual outcomes separately using the [verification matrix](../verification.md).
+
+## Source, License, And Attribution
+
+Locally authored synthesis and examples. No upstream implementation is copied. These experimental contracts describe consumer-owned behavior; review when a failure, ownership change, or platform change invalidates an assumption.
+
+## IA Navigation
+
+Parent: [State Management](../index.md).
+Next: [Continue the state management route](../recipes/index.md).