phlex-reactive 0.11.6 → 0.12.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5c5d8ca344fdd9583bd79ad6e9b162c7a1888d48055dfb36474a3cbc6caf10fe
-  data.tar.gz: c903ed3e437da570c06924055d0e1ad1c9c611c0086431ae8c7d38fc000f8337
+  metadata.gz: 27841384eb24e3e9d66f404b495705b2db4c30fec683ad21ae0f2b2c258c6a00
+  data.tar.gz: 14990c96dd4dfafefd56794531cc116f8a17a9bc6aa76d8caf50679fb95abc1b
 SHA512:
-  metadata.gz: 749fdfd67d453f51c527eb8e058e5b062d04431d3f099aa35a8b9135a38bd2fdc7baa7251eb0ed7d25775bcb6be7f3370958301a0838d89d7893a37f6dd1306b
-  data.tar.gz: 6322de1f369d12c6aff0f187749d4a2f6f090939cce2fb4f4389c9b1a6b7ff1cce3de7d90b4b969706c0997c5d481d8816f45d728dded107445a7455a337f640
+  metadata.gz: c36de342a6909b7cbd04f58a9d6da9b77497acfe5f6777c200932a54af5251872ec91b2a5d624f14f1cb5b3faed8fe60e5a169e4363cb6d32bf7d24418fd88ac
+  data.tar.gz: 45c811958371300f558d57f41e8ead04e607cc07cd43a9915aa2534fa15b650d1c284ca92b871734b755791b730fdb325f7e28e7f8372616aff383887873f340

data/CHANGELOG.md

@@ -8,6 +8,80 @@ adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ### Added
 
+- **Project board — the kanban flagship demo (#216).** A live three-lane board
+  on the docs site (`/docs/example-project-board`, `/demos/project-board`)
+  composing the toolkit end to end: each card is its own nested reactive root
+  (record + signed style state) whose move is ONE reply — the row's remove
+  (its exit effect animates before the element leaves), a fresh-token append
+  into the new lane (wearing its enter effect), and a `reactive:js` text-op
+  stream repainting all three count badges — with the same delta broadcast to
+  peers, actor echo excluded. Inline rename morphs in place, archive is
+  confirm-gated + optimistic, per-lane composers flash on a blank title, and
+  the effect-style picker (including `random`) rides signed state to drive
+  per-call `effect:` overrides. Peer count badges stay live everywhere via
+  `broadcast_to(js:)` — closing the stale-badge gap the team-inbox flagship
+  documents — and empty lanes are pure CSS `:empty`, so the 0↔1 boundary
+  needs no bookkeeping on either delivery path. Docs-app only; no gem code
+  changes.
+
+- **Reactive effects — animate enter/exit/update on every stream render (#215).**
+  Opt-in at three levels, most specific wins: `Phlex::Reactive.effects = true`
+  (or a `{ enter:/exit:/update: }` hash) is the global switch AND the app-wide
+  default set; `reactive_effects enter: :slide, update: false` refines per
+  component (`false` opts out entirely; declaring on a component also works
+  standalone with no global switch); `effect:` on every stream builder, reply
+  verb, and `broadcast_to` overrides one stream (`effect: false` suppresses a
+  declared effect for that call). Five built-ins ship as an engine stylesheet —
+  `stylesheet_link_tag "phlex/reactive/effects"` — fade/slide/scale/highlight/
+  shake, all inside `prefers-reduced-motion: no-preference` and tunable via
+  `--reactive-fx-*` custom properties; `:random` picks a built-in per
+  application; custom effects take the `{ during:, from:, to: }` class-legs
+  vocabulary (issue #186), Tailwind-friendly and stylesheet-free. On the wire
+  the resolved hooks ride the component root as `data-reactive-effect-<hook>`
+  attributes (omitted entirely when off — byte-identical to previous releases)
+  and per-call overrides ride the `<turbo-stream>` element itself; ONE
+  document-level `turbo:before-stream-render` interceptor animates replies AND
+  broadcasts identically on Action Cable and pgbus. `remove` is special: the
+  exit animation runs BEFORE the element leaves the DOM, awaited via
+  `animationend`/`transitionend` with a computed-duration fallback hard-capped
+  at 1s — and a zero computed duration (no effects CSS loaded) skips the wait
+  entirely, so a missing stylesheet can never freeze a removal. Unknown names
+  raise at class load server-side and warn-and-skip client-side (two-sided
+  default-deny). Zero additional allocations per render with effects on (the
+  resolved fragment is a per-class memo keyed on the config + registry
+  generations); the render/token hot paths hold flat with effects off.
+
+- **Confirm on the draft-row remove — `reactive_nested_remove(confirm:)` (#218).**
+  `reactive_nested_remove` now accepts the SAME `confirm:` the other triggers
+  (`on`/`on_client`) do — a static message String, or the conditional Hash form
+  (`{ when: …, message: }` / `{ predicate: …, message: }`, #179) — routed through
+  the shared `apply_confirm!` and gated client-side behind the same overridable
+  `confirmResolver` (the styled-modal seam, #52/#55/#178). On accept it does the
+  existing remove (a draft row leaves the DOM; a persisted row is `_destroy`-marked
+  + hidden) and the existing JSON/attributes re-sync; on cancel, nothing. Per-row
+  messages come for free — the confirm is a per-render string. Works in BOTH wire
+  modes (`:attributes` and `as: :json`). No confirm: → the immediate-remove fast
+  path, unchanged.
+
+- **Fill-then-add for draft nested rows — `reactive_nested_add(:assoc, from:, clear:)` (#208).**
+  The draft-rows primitive's add is *inline-edit* — it clones the template and
+  focuses the new row's first field, so you type INTO the row. A common
+  alternative puts the add controls OUTSIDE the row (a preset `<select>`, a
+  typeahead, plain inputs) and "Add" **snapshots** those values into a new row,
+  then clears them for the next entry. `from: { row_field => "#source-selector" }`
+  seeds each cloned-row field from its source control's current value (matching
+  the field by the same trailing-bracket-segment key inference JSON mode uses),
+  keeps focus on the sources rather than stealing it into the row, and `clear:
+  true` resets the sources (each via the set-value + dispatch contract, so dirty
+  tracking and compute observe the reset). `from:` values are raw CSS selectors
+  resolved within the reactive root (#15 ownership); an unresolved source or an
+  unmatched row-field key is silently skipped (the row still adds). It composes
+  with BOTH wire modes: the seeded values ride the renumbered `_attributes` names
+  on submit (`:attributes`) and the end-of-add JSON sync serializes them
+  (`as: :json`), with no extra wiring. The no-`from:` inline-edit default is
+  unchanged. See the "Draft rows for a new parent" README section and the
+  `/docs/example-draft-rows` page.
+
 - **Multi-field cross-root targets — `reactive_show_targets` speaks the full
   conditions language (#209).** A `"#id"` KEY now takes an `if:`/`if_any:`/
   `unless:` conditions Hash, so an OUTSIDE element can show/hide from a

data/README.md

@@ -332,11 +332,13 @@ The [inline edit example](https://phlex-reactive.zoolutions.llc/docs/example-inl
 | [Client-only ops](https://phlex-reactive.zoolutions.llc/docs/example-client-ops) | `on_client` tabs / outside-close menu / accessible drawer — zero fetches, zero custom JS |
 | [Failure surface](https://phlex-reactive.zoolutions.llc/docs/example-failure) | `error_flash` + `data-reactive-error` + `dismiss_after:` — what you get for free when an action fails |
 | [Team inbox (flagship)](https://phlex-reactive.zoolutions.llc/docs/example-team-inbox) | The whole toolkit in one UI: collection rows, optimistic archive that **reverts on failure**, cross-tab broadcast, an `on_client` kebab, error flashes |
+| [Project board (flagship)](https://phlex-reactive.zoolutions.llc/docs/example-project-board) | The kanban: cards move across lanes with **enter/exit effects** (per-visitor style picker incl. `random`), live count badges in every tab via `broadcast_to(js:)`, nested reactive rows with inline rename, confirm-gated archive |
 
 Every page renders its **real** reactive component inline (source read straight
 off the file), so the demo and the code can never drift. The
-[Team inbox](https://phlex-reactive.zoolutions.llc/docs/example-team-inbox) is the
-flagship — every feature composed into one believable UI.
+[Team inbox](https://phlex-reactive.zoolutions.llc/docs/example-team-inbox) and the
+[Project board](https://phlex-reactive.zoolutions.llc/docs/example-project-board) are the
+flagships — every feature composed into believable UIs.
 
 ---
 
@@ -397,7 +399,7 @@ Use in controllers: `render turbo_stream: Counter.replace(counter)`.
 | `reactive_dirty` / `reactive_dirty warn_unsaved: true` / `reactive_dirty only: %i[...]` | **Dirty tracking**, declared once at the class level, against the DOM's own `defaultValue`/`defaultChecked`/`defaultSelected` — no client state. Marks changed fields + the root `data-reactive-dirty`; `warn_unsaved:` arms a `beforeunload`/`turbo:before-visit` guard; `only:` scopes tracking to named fields. Style with `[data-reactive-dirty]`. See [Dirty-field tracking](#dirty-field-tracking-reactive_dirty). |
 | `nested_update!(:assoc, attrs)` | Map a nested param onto `<assoc>_attributes` with id preservation; update the record. |
 | `reactive_nested_list(:assoc, as: :attributes \| :json)` / `reactive_nested_template(:assoc)` / `reactive_nested_row` | **Draft nested-attribute rows** (the "new parent + child rows" form): the container rows land in, the `<template>` holding ONE row's markup, and the row wrapper marker — all **client-only** form state, keyed by association (several collections per root). `as: :json` (default `:attributes`) serializes the rows into ONE hidden JSON field instead of posting `accepts_nested_attributes_for` names — for an app whose controller `JSON.parse`s a serialized param. See [Draft rows for a new parent](#draft-rows-for-a-new-parent-reactive_nested_). |
-| `reactive_nested_add(:assoc)` / `reactive_nested_remove` | The row triggers, client-only (zero round trips): add clones the template and renumbers its placeholder index; remove deletes a draft row from the DOM, or `_destroy`-marks + hides a persisted row (a hidden `[_destroy]` input present). |
+| `reactive_nested_add(:assoc, from:, clear:)` / `reactive_nested_remove(confirm:)` | The row triggers, client-only (zero round trips): add clones the template and renumbers its placeholder index; remove deletes a draft row from the DOM, or `_destroy`-marks + hides a persisted row (a hidden `[_destroy]` input present). **Fill-then-add**: `from: { row_field => "#source-selector" }` seeds the new row from add controls that live OUTSIDE it (a preset select, a typeahead), and `clear: true` resets them — composes with `as: :attributes` AND `as: :json`. **Confirm on remove**: `reactive_nested_remove(confirm: "Really delete this row?")` gates the remove behind the same overridable `confirmResolver` as `on`/`on_client` (a per-row string, or the conditional `{ when:, message: }` Hash). See [Draft rows for a new parent](#draft-rows-for-a-new-parent-reactive_nested_). |
 | `nested_field_name(:assoc, :field, index: nil)` | The Rails `accepts_nested_attributes_for` wire name for one row field — `order[line_items_attributes][NEW_ROW][quantity]` (the template placeholder) by default, a real index when given. Scope-aware under `reactive_scope`. |
 | `reactive_collection :name, item:, container:, count:, empty:, size:` | Declare an add/remove-row list once; actions call `reply.append`/`prepend`/`remove`. See [Reactive collections](#reactive-collections-addremove-rows--count--empty-state). |
 | `reply.replace` / `.morph` / `.update` / `.remove` / `.redirect(url)` / `.with(*)` / `.js(ops)` | Return from an action to control the reply (flash, remove, redirect, multi-stream, server-pushed client ops). See [Controlling the action's reply](#reply--controlling-the-actions-reply). |
@@ -1381,6 +1383,35 @@ marker — an absent row *is* the removal). The per-row `_attributes` names stil
 render but are ignored by a controller that doesn't permit them; the JSON field
 is the single source of truth.
 
+**Fill-then-add — snapshot add controls that live OUTSIDE the row.** The default
+`reactive_nested_add` is *inline-edit*: it clones the template and focuses the
+new row's first field, so you type INTO the row. A common alternative puts the
+add controls outside the row — a preset `<select>`, a typeahead, plain inputs —
+and "Add" **snapshots** those values into a new row, then clears them for the
+next entry. Pass `from:` (a map of row-field → source-control selector) and
+optionally `clear:`:
+
+```ruby
+input(id: "item-name",  type: "text")     # the add controls, OUTSIDE the row
+input(id: "item-qty",   type: "number")
+
+button(**reactive_nested_add(:line_items,
+  from: { name: "#item-name", quantity: "#item-qty" },  # row field => source selector
+  clear: true)) { "Add item" }
+```
+
+On click the client clones the template, fills each cloned-row field from its
+source control's current value (matching the field by the **same** trailing
+bracket-segment key inference JSON mode uses), keeps focus on the sources (so
+you keep entering the next item — it does *not* steal focus into the row), and,
+with `clear: true`, resets the sources (each via the set-value + dispatch
+contract, so dirty tracking and compute see it). The `from:` values are raw CSS
+selectors resolved within this root (`#15` ownership); a selector that resolves
+nothing, or a row-field key with no matching cloned field, is skipped (the row
+still adds — never a throw). It composes with **both** wire modes: the seeded
+values ride the renumbered `_attributes` names on submit (`:attributes`) and the
+end-of-add JSON sync serializes them (`as: :json`), with no extra wiring.
+
 Relatedly, a **draft parent can now run real server actions too** (issue #208):
 an unsaved record signs a gid-less `{c, state}` token, and the endpoint rebuilds
 the component through the record kwarg's **initialize default** —
@@ -2104,6 +2135,66 @@ end
   `reactive_collection` is the per-actor add/remove + count + empty-state wrapper,
   not a replacement for the broadcast.
 
+### Effects — animate enter/exit/update (opt-in)
+
+Reactive updates land instantly and invisibly: a removed row pops out of
+existence, an appended row pops in, a cross-tab change gives no cue. Effects
+make the reactivity *visible* — rows fade/slide in and out, updates flash —
+with zero app JS. Strictly **opt-in at three levels**, most specific wins:
+
+```ruby
+# 1. GLOBAL — setting it is the opt-in AND the app-wide default set:
+Phlex::Reactive.effects = true   # { enter: :fade, exit: :fade, update: :highlight }
+Phlex::Reactive.effects = { enter: :slide, exit: :fade, update: :highlight }
+
+# 2. PER COMPONENT — refine or opt out (works standalone too; declaring on a
+#    component opts it in even without the global switch):
+class Notifications::Row < ApplicationComponent
+  reactive_effects enter: :slide, exit: :fade   # built-ins (shipped CSS)
+  # reactive_effects update: false              # disable one hook
+  # reactive_effects false                      # opt this component out entirely
+  # reactive_effects enter: :random             # a random built-in per application
+end
+
+# 3. PER CALL — the escape hatch for one stream:
+reply.remove(effect: :shake)                    # a dramatic one-off exit
+reply.append(item, to: :items, effect: :scale)  # this row only
+Item.replace(@todo, effect: false)              # suppress a declared effect once
+Row.broadcast_to(@list, :todos, append: todo, target: "rows", effect: :slide)
+```
+
+The hooks map to stream actions: **enter** (`append`/`prepend`) animates the
+arriving element, **exit** (`remove`) runs *before* the element leaves the DOM
+(the removal waits for the animation, capped at 1s so a missing stylesheet can
+never wedge it), **update** (`replace`/`update`, plain or morph) flashes the
+fresh render. Effects fire for the actor's own reply AND for broadcasts alike
+— if a debounced-save grid flashes too much, declare `reactive_effects
+update: false` on that component.
+
+Link the shipped stylesheet once (five built-ins — `:fade`, `:slide`,
+`:scale`, `:highlight`, `:shake` — wrapped in `prefers-reduced-motion:
+no-preference`, tunable via `--reactive-fx-*` CSS custom properties):
+
+```erb
+<%= stylesheet_link_tag "phlex/reactive/effects" %>
+```
+
+Custom effects skip the stylesheet entirely: pass named class legs (the same
+`{ during:, from:, to: }` vocabulary `js.toggle(transition:)` uses), perfect
+for Tailwind utilities:
+
+```ruby
+reactive_effects enter: { during: %w[transition-all duration-300],
+                          from: %w[opacity-0 translate-y-2],
+                          to: %w[opacity-100 translate-y-0] }
+```
+
+Unknown effect names raise at class load (server) and warn-and-skip on the
+client (default-deny, two-sided). With effects off (the default) the wire is
+byte-identical to previous releases; with them on, the resolved hooks ride the
+component root as `data-reactive-effect-*` attributes — identity, never state,
+and identical on Action Cable and pgbus.
+
 ### Configuration (`config/initializers/phlex_reactive.rb`)
 
 ```ruby
@@ -2151,6 +2242,10 @@ Phlex::Reactive.error_flash = ->(kind) do
   end
 end
 
+# Effects (issue #215): opt in globally + set the app-wide default hooks; see
+# "Effects" above. Off (nil) by default — byte-identical wire when off.
+Phlex::Reactive.effects = { enter: :fade, exit: :fade, update: :highlight }
+
 # Turnkey APM integration. Names each action Component#action in AppSignal/Sentry/
 # Datadog and reports action-body crashes with component/action tags. SDK is
 # runtime-detected (no gem dependency); a custom object responding to

data/app/assets/stylesheets/phlex/reactive/effects.css

@@ -0,0 +1,106 @@
+/* phlex-reactive effects (issue #215) — the shipped built-in animations.
+ *
+ * Opt in from your layout:
+ *
+ *   <%= stylesheet_link_tag "phlex/reactive/effects" %>
+ *
+ * The client applies these classes transiently around stream renders:
+ * reactive-fx--<name>-<hook>, where <name> is fade/slide/scale/highlight/
+ * shake and <hook> is enter (append/prepend), exit (remove), or update
+ * (replace/update). Every class is removed again on animationend, so nothing
+ * here leaks into steady-state styling.
+ *
+ * Everything is wrapped in prefers-reduced-motion: no-preference — the client
+ * ALSO skips effects entirely under reduced motion (defense in depth; a zero
+ * computed duration short-circuits the exit wait, so removals never stall).
+ *
+ * Tune globally (or per component root) by overriding the custom properties:
+ *
+ *   :root { --reactive-fx-duration: 200ms; --reactive-fx-highlight-color: #bae6fd80; }
+ *
+ * Keep durations comfortably under 1s — the client hard-caps any effect wait
+ * at 1000ms (an exit past the cap is removed mid-animation).
+ */
+@media (prefers-reduced-motion: no-preference) {
+  :root {
+    --reactive-fx-duration: 300ms;
+    --reactive-fx-highlight-duration: 700ms;
+    --reactive-fx-highlight-color: rgba(250, 204, 21, 0.5);
+  }
+
+  /* fade — opacity in/out. The update variant re-fades the fresh render in. */
+  @keyframes reactive-fx-fade-in {
+    from { opacity: 0; }
+    to { opacity: 1; }
+  }
+  @keyframes reactive-fx-fade-out {
+    from { opacity: 1; }
+    to { opacity: 0; }
+  }
+  .reactive-fx--fade-enter,
+  .reactive-fx--fade-update {
+    animation: reactive-fx-fade-in var(--reactive-fx-duration) ease-out both;
+  }
+  .reactive-fx--fade-exit {
+    animation: reactive-fx-fade-out var(--reactive-fx-duration) ease-in both;
+  }
+
+  /* slide — a short vertical travel + fade. */
+  @keyframes reactive-fx-slide-in {
+    from { opacity: 0; transform: translateY(0.5rem); }
+    to { opacity: 1; transform: none; }
+  }
+  @keyframes reactive-fx-slide-out {
+    from { opacity: 1; transform: none; }
+    to { opacity: 0; transform: translateY(0.5rem); }
+  }
+  .reactive-fx--slide-enter,
+  .reactive-fx--slide-update {
+    animation: reactive-fx-slide-in var(--reactive-fx-duration) ease-out both;
+  }
+  .reactive-fx--slide-exit {
+    animation: reactive-fx-slide-out var(--reactive-fx-duration) ease-in both;
+  }
+
+  /* scale — grow in / shrink out around the element's center. */
+  @keyframes reactive-fx-scale-in {
+    from { opacity: 0; transform: scale(0.92); }
+    to { opacity: 1; transform: none; }
+  }
+  @keyframes reactive-fx-scale-out {
+    from { opacity: 1; transform: none; }
+    to { opacity: 0; transform: scale(0.92); }
+  }
+  .reactive-fx--scale-enter,
+  .reactive-fx--scale-update {
+    animation: reactive-fx-scale-in var(--reactive-fx-duration) ease-out both;
+  }
+  .reactive-fx--scale-exit {
+    animation: reactive-fx-scale-out var(--reactive-fx-duration) ease-in both;
+  }
+
+  /* highlight — the classic background flash that fades to the element's own
+   * background. One animation for every hook: flash on arrival, on change,
+   * and as a last flare before a removal. */
+  @keyframes reactive-fx-highlight {
+    from { background-color: var(--reactive-fx-highlight-color); }
+  }
+  .reactive-fx--highlight-enter,
+  .reactive-fx--highlight-update,
+  .reactive-fx--highlight-exit {
+    animation: reactive-fx-highlight var(--reactive-fx-highlight-duration) ease-out both;
+  }
+
+  /* shake — a quick horizontal oscillation (attention / destructive cue). */
+  @keyframes reactive-fx-shake {
+    10%, 90% { transform: translateX(-1px); }
+    20%, 80% { transform: translateX(2px); }
+    30%, 50%, 70% { transform: translateX(-3px); }
+    40%, 60% { transform: translateX(3px); }
+  }
+  .reactive-fx--shake-enter,
+  .reactive-fx--shake-update,
+  .reactive-fx--shake-exit {
+    animation: reactive-fx-shake 400ms cubic-bezier(0.36, 0.07, 0.19, 0.97) both;
+  }
+}