studio-engine 0.22.0 → 0.24.0

data/app/views/layouts/studio/_smooth_load.html.erb

@@ -0,0 +1,15 @@
+<%# Smooth-load convention (opt-in via Studio.smooth_load) — the next page
+    materializes behind the current one, then presents itself. Turbo 8 sees the
+    view-transition meta and wraps its body swap in document.startViewTransition;
+    browsers without support get the instant swap. no-preview stops application
+    visits from painting a stale cache snapshot before the fresh response — the
+    current page holds until the new one is ready, so navigation renders exactly
+    once. Restoration visits (back/forward) still restore instantly from cache.
+    Transition styling ships in engine.css ("Smooth-load convention" block);
+    pin an app's sticky header with the .vt-pinned-header utility (exactly one
+    element per page — a duplicate view-transition-name silently disables the
+    whole transition). %>
+<% if Studio.smooth_load %>
+  <meta name="view-transition" content="same-origin">
+  <meta name="turbo-cache-control" content="no-preview">
+<% end %>

data/app/views/studio/_board_assets.html.erb

@@ -0,0 +1,341 @@
+<%#
+  studioBoard factory — the Alpine data behind the engine board primitive
+  (studio/board/_board). Ships here at PAGE level on purpose: a <script> inside the
+  board component template would be cloned/re-parsed and never run, so a consumer
+  renders THIS once in its layout (like studio/_leveling_activity_assets homes
+  levelingActionModal and studio/_age_verify_assets homes ageVerifyModal), and the
+  board anywhere below just references window.studioBoard. SortableJS is loaded
+  globally by layouts/studio/_head (vendored, no CDN); this factory drives it.
+
+  ONE factory drives BOTH board shapes — it reads its selectors and behavior from
+  opts, so the kanban cross-column board (group + move PATCH + toasts + counts) and
+  the within-lane depth chart (group:false, a drag handle, reorder-only) are the
+  same code with different opts. See studio/board/_board for the full opts contract.
+
+  CRITICAL BOUNDARY — this factory is UI ONLY. It PATCHes an app-supplied move_url,
+  POSTs an app-supplied reorder_url, and reacts to a neutral JSON contract; it holds
+  ZERO domain logic. Custom behavior attaches by LISTENING to the dispatched
+  window events (studio:board-moved / :board-reordered / :card-added), and heavier
+  animation is delegated OPAQUELY to a window[fx] module + window[hook] fns the
+  engine never inspects.
+%>
+<script>
+  (function () {
+    if (window.studioBoard) return;
+
+    window.studioBoard = function (opts) {
+      opts = opts || {};
+      return {
+        // --- config (from opts) --------------------------------------------
+        zoneSelector:   opts.zoneSelector || ".kanban-dropzone",
+        cardSelector:   opts.draggable || ".kanban-card",
+        emptySelector:  opts.emptySelector || null,
+        groupName:      (opts.group === false ? null : (opts.group || "studio-board")),
+        handle:         opts.handle || null,
+        sortFilter:     opts.filter || ".kanban-empty",
+        idAttr:         opts.idAttr || "slug",
+        zoneAttr:       opts.zoneAttr || "stage",
+        domIdPrefix:    opts.domIdPrefix || "card-",
+        moveUrl:        opts.moveUrl || null,
+        moveParam:      opts.moveParam || null,
+        reorderUrl:     opts.reorderUrl || "",
+        reorderPayload: opts.reorderPayload || "slugs",
+        optimistic:     opts.optimistic !== false,
+        toastsEnabled:  opts.toasts !== false,
+        live:           !!opts.live,
+        demo:           !!opts.demo,
+        fxName:         opts.fx || null,
+        onMoveHook:     opts.onMoveHook || null,
+        onDropHook:     opts.onDropHook || null,
+        labels:         opts.labels || {},
+
+        // --- state ---------------------------------------------------------
+        toasts: [],
+
+        // --- init ----------------------------------------------------------
+        init: function () {
+          // Set data-alpine-ready in $nextTick, NOT synchronously: x-init runs while
+          // Alpine is still walking this subtree, so inner @click handlers are not
+          // bound yet. $nextTick fires after the directive walk, so the flag then
+          // means "the board is fully wired and interactive" — the documented init
+          // flake fix carried over from the MS kanbanBoard.
+          var self = this;
+          this.$nextTick(function () {
+            self.$el.dataset.alpineReady = "true";
+            self.initSortables();
+            if (self.live) {
+              self.observeLive();
+              if (!self.fx()) self.installExitStreamFallback();
+            }
+          });
+        },
+
+        fx: function () { return this.fxName ? window[this.fxName] : null; },
+        cardId: function (el) { return el ? el.getAttribute("data-" + this.idAttr) : null; },
+        zoneKey: function (el) { return el ? el.getAttribute("data-" + this.zoneAttr) : null; },
+        label: function (zone) { return this.labels[zone] || zone; },
+
+        // --- SortableJS wiring ---------------------------------------------
+        initSortables: function () {
+          if (typeof Sortable === "undefined") return;
+          var self = this;
+          document.querySelectorAll(this.zoneSelector).forEach(function (zone) {
+            var cfg = {
+              animation: 150,
+              ghostClass: "opacity-30",
+              draggable: self.cardSelector,
+              filter: self.sortFilter,
+              onStart: function () { window.__studioBoardDragging = true; },
+              onEnd: function (evt) {
+                self.handleSortEnd(evt);
+                requestAnimationFrame(function () { window.__studioBoardDragging = false; });
+              }
+            };
+            if (self.groupName) cfg.group = self.groupName; // omit ⇒ within-zone only
+            if (self.handle) cfg.handle = self.handle;
+            Sortable.create(zone, cfg);
+          });
+        },
+
+        // A cross-column drop moves the card (PATCH); a same-zone drop is a pure
+        // reorder and must NEVER PATCH the zone. Source the from/to from the
+        // DROPZONES (evt.from / evt.to), never the card, so an in-place reorder
+        // can't mismove.
+        handleSortEnd: function (evt) {
+          var self = this;
+          var card = evt.item;
+          var fromZone = evt.from;
+          var toZone = evt.to;
+          var id = this.cardId(card);
+          var moved = fromZone !== toZone;
+
+          var afterMove = function (ok) {
+            if (moved && !ok) return; // reverted — leave the order alone
+            self.saveOrder(toZone);
+            self.updateCounts();
+          };
+
+          if (moved) {
+            Promise.resolve(this.applyMove(card, fromZone, toZone, id)).then(afterMove);
+          } else {
+            afterMove(true);
+          }
+        },
+
+        // Cross-column move: PATCH the zone attr; optimistic revert on failure.
+        applyMove: function (card, fromZone, toZone, id) {
+          var self = this;
+          var newZone = this.zoneKey(toZone);
+          var fromKey = this.zoneKey(fromZone);
+
+          // Moves not configured (or a within-zone board): a cross-zone drop is
+          // disallowed — snap back so a stray drag can't silently mismove. In demo
+          // mode with no move endpoint, still reflect the move locally.
+          if (!this.moveUrl || !this.moveParam) {
+            if (this.demo) {
+              this.setCardZone(card, newZone);
+              this.emit("board-moved", id, fromKey, newZone);
+              return true;
+            }
+            this.revert(card, fromZone);
+            return false;
+          }
+
+          if (this.demo) {
+            this.setCardZone(card, newZone);
+            this.toast("Moved to " + this.label(newZone), "success");
+            this.emit("board-moved", id, fromKey, newZone);
+            this.hook(this.onMoveHook, { record: id, from: fromKey, to: newZone });
+            return true;
+          }
+
+          var url = this.moveUrl.replace(":id", encodeURIComponent(id));
+          var body = {};
+          body[this.moveParam.resource] = {};
+          body[this.moveParam.resource][this.moveParam.attr] = newZone;
+
+          return this.request(url, "PATCH", body).then(function (resp) {
+            if (!resp.ok) {
+              return resp.json().catch(function () { return {}; }).then(function (err) {
+                throw new Error(err.error || ("Failed (" + resp.status + ")"));
+              });
+            }
+            self.setCardZone(card, newZone);
+            self.toast("Moved to " + self.label(newZone), "success");
+            self.emit("board-moved", id, fromKey, newZone);
+            self.hook(self.onMoveHook, { record: id, from: fromKey, to: newZone });
+            return true;
+          }).catch(function (e) {
+            if (self.optimistic) self.revert(card, fromZone);
+            self.toast((e && e.message) || "Move failed", "error");
+            self.updateCounts();
+            return false;
+          });
+        },
+
+        // Save the destination column's order. Reads the ordered id list and POSTs
+        // it under the neutral payload key (`slugs` | `ids`) plus the advisory zone.
+        saveOrder: function (toZone) {
+          var self = this;
+          var ids = Array.prototype.slice
+            .call(toZone.querySelectorAll(this.cardSelector))
+            .map(function (c) { return self.cardId(c); });
+          var zone = this.zoneKey(toZone);
+          this.emit("board-reordered", null, zone, zone, { ids: ids, zone: zone });
+          this.hook(this.onDropHook, { ids: ids, zone: zone });
+          if (this.demo || !this.reorderUrl) return;
+          var payload = {};
+          payload[this.reorderPayload] = ids;
+          payload.zone = zone;
+          this.request(this.reorderUrl, "POST", payload).catch(function () {
+            // Order save failed — positions are stale but the board stays functional.
+          });
+        },
+
+        setCardZone: function (card, zone) { card.setAttribute("data-" + this.zoneAttr, zone); },
+
+        // Revert a failed move: drop the card back into its SOURCE zone (which
+        // always exists) above the empty state, and flash a red ring.
+        revert: function (card, fromZone) {
+          var anchor = this.emptySelector ? fromZone.querySelector(this.emptySelector) : null;
+          fromZone.insertBefore(card, anchor);
+          card.classList.add("ring-2", "ring-red-500");
+          setTimeout(function () { card.classList.remove("ring-2", "ring-red-500"); }, 1500);
+        },
+
+        updateCounts: function () {
+          var self = this;
+          document.querySelectorAll("[data-board-count]").forEach(function (badge) {
+            var key = badge.getAttribute("data-board-count");
+            var zone = document.getElementById("dropzone-" + key);
+            if (!zone) return;
+            var count = zone.querySelectorAll(self.cardSelector).length;
+            badge.textContent = count;
+            if (self.emptySelector) {
+              var empty = zone.querySelector(self.emptySelector);
+              if (empty) empty.style.display = count === 0 ? "flex" : "none";
+            }
+          });
+        },
+
+        // --- live updates (Turbo Streams) ----------------------------------
+        // The board subscribes via turbo_stream_from(live_channel); Turbo patches the
+        // DOM on every broadcast. This observer adds the flourish Turbo doesn't: a
+        // fade/scale-in on each patched-in card (deferred to window[fx] when present)
+        // and a count refresh after any column change.
+        observeLive: function () {
+          var self = this;
+          var onChange = function (mutations) {
+            for (var i = 0; i < mutations.length; i++) {
+              mutations[i].addedNodes.forEach(function (node) {
+                if (node.nodeType === 1 && node.matches && node.matches(self.cardSelector)) {
+                  var fx = self.fx();
+                  if (fx && fx.onAdd) { fx.onAdd(node); } else { self.animateIn(node); }
+                  self.emit("card-added", self.cardId(node), null, self.zoneKey(node.parentElement));
+                }
+              });
+            }
+            self.updateCounts();
+          };
+          document.querySelectorAll(this.zoneSelector).forEach(function (zone) {
+            new MutationObserver(onChange).observe(zone, { childList: true });
+          });
+        },
+
+        animateIn: function (el) {
+          el.style.opacity = "0";
+          el.style.transform = "scale(0.96)";
+          el.classList.add("ring-2", "ring-primary");
+          requestAnimationFrame(function () {
+            el.style.transition = "opacity 300ms ease, transform 300ms ease";
+            el.style.opacity = "";
+            el.style.transform = "";
+          });
+          setTimeout(function () { el.classList.remove("ring-2", "ring-primary"); el.style.transition = ""; }, 900);
+        },
+
+        // Archive re-parent / delete exit animation via a Turbo `remove` stream
+        // carrying data-exit-action. Installed only when no fx module owns exits.
+        installExitStreamFallback: function () {
+          if (window.__studioBoardExitFallback) return;
+          window.__studioBoardExitFallback = true;
+          var self = this;
+          document.addEventListener("turbo:before-stream-render", function (event) {
+            var stream = event.target;
+            if (stream.getAttribute("action") !== "remove") return;
+            var target = stream.getAttribute("target") || "";
+            var exitAction = stream.dataset.exitAction;
+            if (target.indexOf(self.domIdPrefix) !== 0 || !exitAction) return;
+            var renderNow = event.detail.render;
+            event.detail.render = function (el) {
+              var card = document.getElementById(target);
+              if (!card) { renderNow(el); return; }
+              self.animateCardExit(card, exitAction).then(function () {
+                renderNow(el);
+                self.updateCounts();
+              });
+            };
+          });
+        },
+
+        animateCardExit: function (card, kind) {
+          if (!card || window.matchMedia("(prefers-reduced-motion: reduce)").matches) return Promise.resolve();
+          card.style.pointerEvents = "none";
+          var frames = kind === "archive"
+            ? [{ opacity: 1, transform: "translateY(0) scale(1)" }, { opacity: 0, transform: "translateY(18px) scale(0.86)" }]
+            : [{ opacity: 1, transform: "scale(1)" }, { opacity: 0, transform: "scale(0.6)" }];
+          var anim = card.animate(frames, {
+            duration: kind === "archive" ? 500 : 420,
+            easing: "cubic-bezier(.35,0,.2,1)",
+            fill: "forwards"
+          });
+          return anim.finished.catch(function () {});
+        },
+
+        // --- toasts --------------------------------------------------------
+        toast: function (message, type) {
+          if (!this.toastsEnabled) {
+            if (type === "error" && typeof window.alert === "function") window.alert(message);
+            return;
+          }
+          var self = this;
+          var id = Date.now() + Math.random();
+          this.toasts.push({ id: id, message: message, type: type, visible: true });
+          setTimeout(function () {
+            var t = self.toasts.find(function (x) { return x.id === id; });
+            if (t) t.visible = false;
+            setTimeout(function () {
+              self.toasts = self.toasts.filter(function (x) { return x.id !== id; });
+            }, 300);
+          }, 3000);
+        },
+
+        // --- helpers -------------------------------------------------------
+        request: function (url, method, body) {
+          var csrf = (document.querySelector('meta[name="csrf-token"]') || {}).content || "";
+          var fetcher = window.authedFetch || window.fetch;
+          return fetcher(url, {
+            method: method,
+            headers: { "Content-Type": "application/json", "X-CSRF-Token": csrf, "Accept": "application/json" },
+            body: JSON.stringify(body || {})
+          });
+        },
+
+        // The primary extension seam — apps LISTEN for these on window and attach
+        // confetti / swipe / cart / analytics, never patching this factory.
+        emit: function (name, record, from, to, extra) {
+          try {
+            var detail = Object.assign({ record: record, from: from, to: to }, extra || {});
+            window.dispatchEvent(new CustomEvent("studio:" + name, { detail: detail }));
+          } catch (e) {}
+        },
+
+        hook: function (hookName, detail) {
+          if (!hookName) return;
+          var fn = window[hookName];
+          if (typeof fn === "function") { try { fn(detail); } catch (e) {} }
+        }
+      };
+    };
+  })();
+</script>

data/app/views/studio/board/_board.html.erb

@@ -0,0 +1,151 @@
+<%#
+  studio/board — the shared kanban / depth-chart board shell. An ADDITIVE engine
+  primitive (Phase D): the SortableJS drag-reorder, optimistic cross-column move →
+  revert → toast, and count/live wiring that the three near-identical McRitchie
+  Studio boards (tasks / news / content) and the depth chart each hand-rolled,
+  lifted into one place. Renders a horizontal row of columns, each a drop zone the
+  vendored SortableJS + window.studioBoard factory (studio/_board_assets, rendered
+  once at layout level — a <script> inside this component template would never run)
+  wires.
+
+  UI ONLY and NEUTRAL: no model, no routes, no domain. The app supplies its columns,
+  its card partial, and its endpoints. Custom behavior attaches by LISTENING to the
+  DOM events the factory dispatches on window — `studio:board-moved`,
+  `studio:board-reordered`, `studio:card-added` (detail `{ record, from, to }`) —
+  never by patching the factory. Heavier per-app animation defers OPAQUELY to a
+  `fx:` module (window[<name>]) and to `on_move_hook:` / `on_drop_hook:` fns.
+
+  The identity contract every card + zone must satisfy is emitted by
+  studio/board/_column (the `.kanban-dropzone`) and studio/board/_card_shell (the
+  `.kanban-card`) — an app may hand-roll a bespoke card as long as it matches.
+
+  locals:
+    columns:          (req) [{ key:, label:, cards:, count:, badge_class:,
+                      collapsible:, hidden:, header_extra: }]. `cards` are records
+                      passed to `card_partial`; `count` defaults to cards.size.
+    card_partial:     (req) partial rendered per card (e.g. "tasks/task_card").
+    card_as:          local the record binds to in card_partial. Default :card.
+    card_locals:      per-card extra locals — a Proc ->(record){ Hash } or a Hash.
+    reorder_url:      POST endpoint the drag-reorder saves the new order to.
+    reorder_payload:  :slugs | :ids — the key the ordered id list POSTs under.
+                      Default :slugs.
+    move_url:         PATCH template for a cross-column move, ":id" → the card's id
+                      (e.g. "/tasks/:id.json"). nil disallows moves (reorder only).
+    move_param:       { resource:, attr: } → PATCH body { resource => { attr => zone } }.
+                      nil disallows moves.
+    group:            SortableJS group — a shared string allows cross-column drags;
+                      false keeps drags within a zone (the depth-chart shape).
+                      Default "studio-board".
+    id_attr:          card id data-attr + dom-id suffix. Default "slug".
+    zone_attr:        column/zone data-attr. Default "stage".
+    handle:           drag-handle selector (nil = whole card draggable).
+    filter:           SortableJS filter (undraggable els). Default ".kanban-empty".
+    zone_selector:    the drop-zone selector. Default ".kanban-dropzone".
+    draggable:        the card selector. Default ".kanban-card".
+    empty_selector:   the empty-state selector (revert anchor + count toggle).
+                      Default ".kanban-empty"; nil for a board with no empty state.
+    live_channel:     Turbo Stream channel for live updates (nil = static board).
+    optimistic:       revert + red-ring flash a failed move. Default true.
+    toasts:           show the toast host (false = window.alert on error). Default true.
+    empty_label:      empty-zone text. Default "Drop here".
+    header_slot:      raw HTML rendered above the columns (pass html_safe content).
+    above_board_slot: raw HTML rendered between the header and the columns.
+    fx:               window[<name>] module the factory defers add/exit anims to.
+    on_move_hook:     window[<name>] opaque fn, called with { record, from, to }.
+    on_drop_hook:     window[<name>] opaque fn, called with { ids, zone }.
+    demo:             style-guide preview — drag works locally, no network POST.
+%>
+<%
+  columns          = local_assigns.fetch(:columns)
+  card_partial     = local_assigns.fetch(:card_partial)
+  card_as          = local_assigns.fetch(:card_as, :card)
+  card_locals      = local_assigns.fetch(:card_locals, nil)
+  reorder_url      = local_assigns.fetch(:reorder_url, "")
+  reorder_payload  = local_assigns.fetch(:reorder_payload, :slugs).to_s
+  move_url         = local_assigns.fetch(:move_url, nil)
+  move_param       = local_assigns.fetch(:move_param, nil)
+  group            = local_assigns.fetch(:group, "studio-board")
+  id_attr          = local_assigns.fetch(:id_attr, "slug").to_s
+  zone_attr        = local_assigns.fetch(:zone_attr, "stage").to_s
+  handle           = local_assigns.fetch(:handle, nil)
+  sort_filter      = local_assigns.fetch(:filter, ".kanban-empty")
+  zone_selector    = local_assigns.fetch(:zone_selector, ".kanban-dropzone")
+  draggable_sel    = local_assigns.fetch(:draggable, ".kanban-card")
+  empty_selector   = local_assigns.fetch(:empty_selector, ".kanban-empty")
+  dom_id_prefix    = local_assigns.fetch(:dom_id_prefix, "card-")
+  live_channel     = local_assigns.fetch(:live_channel, nil)
+  optimistic       = local_assigns.fetch(:optimistic, true)
+  toasts           = local_assigns.fetch(:toasts, true)
+  empty_label      = local_assigns.fetch(:empty_label, "Drop here")
+  header_slot      = local_assigns.fetch(:header_slot, nil)
+  above_board_slot = local_assigns.fetch(:above_board_slot, nil)
+  fx               = local_assigns.fetch(:fx, nil)
+  on_move_hook     = local_assigns.fetch(:on_move_hook, nil)
+  on_drop_hook     = local_assigns.fetch(:on_drop_hook, nil)
+  demo             = local_assigns.fetch(:demo, false)
+
+  board_opts = {
+    zoneSelector:   zone_selector,
+    draggable:      draggable_sel,
+    emptySelector:  empty_selector,
+    group:          (group == false ? false : group.to_s),
+    handle:         handle,
+    filter:         sort_filter,
+    idAttr:         id_attr,
+    zoneAttr:       zone_attr,
+    domIdPrefix:    dom_id_prefix,
+    moveUrl:        move_url,
+    moveParam:      (move_param ? { resource: move_param[:resource].to_s, attr: move_param[:attr].to_s } : nil),
+    reorderUrl:     reorder_url,
+    reorderPayload: reorder_payload,
+    optimistic:     !!optimistic,
+    toasts:         !!toasts,
+    live:           live_channel.present?,
+    demo:           !!demo,
+    fx:             fx,
+    onMoveHook:     on_move_hook,
+    onDropHook:     on_drop_hook,
+    labels:         columns.each_with_object({}) { |c, h| h[c[:key].to_s] = (c[:label] || c[:key]).to_s if c[:key] }
+  }
+%>
+<section class="studio-board" data-test="studio-board" x-data="studioBoard(<%= board_opts.to_json %>)">
+  <% if live_channel.present? %><%= turbo_stream_from live_channel %><% end %>
+
+  <% if header_slot %><div class="studio-board-header mb-4"><%= header_slot %></div><% end %>
+  <% if above_board_slot %><%= above_board_slot %><% end %>
+
+  <div class="flex flex-col gap-4 overflow-x-visible pb-4 sm:flex-row sm:overflow-x-auto">
+    <% columns.each do |column| %>
+      <%= render "studio/board/column",
+            column: column,
+            zone_attr: zone_attr,
+            dom_id_prefix: dom_id_prefix,
+            zone_selector_class: zone_selector.delete_prefix("."),
+            empty_selector_class: (empty_selector || "kanban-empty").delete_prefix("."),
+            empty_label: empty_label,
+            card_partial: card_partial,
+            card_as: card_as,
+            card_locals: card_locals %>
+    <% end %>
+  </div>
+
+  <% if toasts %>
+    <div class="studio-board-toasts fixed top-4 right-4 z-50 space-y-2" data-test="studio-board-toasts">
+      <template x-for="toast in toasts" :key="toast.id">
+        <div x-show="toast.visible"
+             x-transition:enter="transition ease-out duration-300"
+             x-transition:enter-start="opacity-0 translate-x-8"
+             x-transition:enter-end="opacity-100 translate-x-0"
+             x-transition:leave="transition ease-in duration-200"
+             x-transition:leave-start="opacity-100 translate-x-0"
+             x-transition:leave-end="opacity-0 translate-x-8"
+             class="bg-surface border rounded-lg px-4 py-2.5 text-sm font-medium shadow-lg backdrop-blur-sm"
+             :style="toast.type === 'success'
+                       ? 'border-color: var(--color-success); color: var(--color-success)'
+                       : 'border-color: var(--color-danger); color: var(--color-danger)'">
+          <span x-text="toast.message"></span>
+        </div>
+      </template>
+    </div>
+  <% end %>
+</section>

data/app/views/studio/board/_card_shell.html.erb

@@ -0,0 +1,47 @@
+<%#
+  studio/board/card_shell — OPTIONAL chrome that emits the board CARD half of the
+  identity contract, so a card partial can `render layout: "studio/board/card_shell"`
+  around its own body instead of hand-rolling the wrapper. It emits:
+
+    id="<dom_id_prefix><id>"      (default id="card-<id>")
+    data-<id_attr>="<id>"         (default data-slug — window.studioBoard reads this)
+    data-<zone_attr>="<zone>"     (default data-stage — the card's current column)
+    class="kanban-card <extra>"   (the SortableJS draggable + live-observe hook)
+
+  Apps may SKIP this and hand-roll a bespoke card, as long as it satisfies the same
+  contract (that is the point of the primitive — the contract, not this exact
+  markup). UI only; no domain, no persistence.
+
+  Checks local_assigns (never block_given?) for its locals, but always yields the
+  caller block — it is only ever used as a `render layout:` wrapper.
+
+  locals:
+    id:            (req) the card id value (a slug / record id).
+    zone:          (req) the card's current column/zone key.
+    id_attr:       data-attr name for the id. Default "slug".
+    zone_attr:     data-attr name for the zone. Default "stage".
+    dom_id_prefix: dom-id prefix. Default "card-".
+    card_class:    the required base class. Default "kanban-card".
+    class:         extra classes appended after card_class.
+    style:         inline style string.
+    attrs:         Hash of extra root attributes ({ "x-data" => "…", "data-foo" => 1 }),
+                   values are HTML-escaped — the rebase seam for a card that carries
+                   its own Alpine/data-* on the root.
+%>
+<%
+  id            = local_assigns.fetch(:id)
+  zone          = local_assigns.fetch(:zone)
+  id_attr       = local_assigns.fetch(:id_attr, "slug")
+  zone_attr     = local_assigns.fetch(:zone_attr, "stage")
+  dom_id_prefix = local_assigns.fetch(:dom_id_prefix, "card-")
+  card_class    = local_assigns.fetch(:card_class, "kanban-card")
+  extra_class   = local_assigns.fetch(:class, nil)
+  inline_style  = local_assigns.fetch(:style, nil)
+  root_attrs    = local_assigns.fetch(:attrs, {}) || {}
+%>
+<div id="<%= dom_id_prefix %><%= id %>"
+     class="<%= [card_class, extra_class].compact.join(" ") %>"
+     data-<%= id_attr %>="<%= id %>"
+     data-<%= zone_attr %>="<%= zone %>"
+     <% root_attrs.each do |name, value| %><%= name %>="<%= value %>" <% end %>
+     <% if inline_style %>style="<%= inline_style %>"<% end %>><%= yield %></div>

data/app/views/studio/board/_column.html.erb

@@ -0,0 +1,80 @@
+<%#
+  studio/board/column — ONE board column: the header (label + count), the drop
+  zone (the SortableJS target), its cards, and the empty state. Emits the ZONE half
+  of the board identity contract:
+
+    id="dropzone-<key>"           (window.studioBoard.updateCounts reads this)
+    class="kanban-dropzone …"     (the SortableJS + live-observe target)
+    data-<zone_attr>="<key>"      (the column key a dropped card moves TO)
+
+  Cards emit the other half (see studio/board/_card_shell). Rendered by
+  studio/board/_board; not usually rendered directly.
+
+  locals:
+    column:               (req) { key:, label:, cards:, count:, badge_class:,
+                          collapsible:, hidden:, header_extra: }. `cards` are the
+                          records passed to the card partial; `count` defaults to
+                          cards.size; `badge_class` picks a components/_badge scheme
+                          for the count (else a plain neutral count chip).
+    zone_attr:            data-attr name for the zone. Default "stage".
+    dom_id_prefix:        card dom-id prefix, forwarded to the cards. Default "card-".
+    zone_selector_class:  the drop-zone class. Default "kanban-dropzone".
+    empty_selector_class: the empty-state class. Default "kanban-empty".
+    empty_label:          empty-zone text. Default "Drop here".
+    card_partial:         (req) partial rendered per card.
+    card_as:              local the record binds to in card_partial. Default :card.
+    card_locals:          per-card extra locals — a Proc ->(record){ Hash } or Hash.
+%>
+<%
+  column               = local_assigns.fetch(:column)
+  zone_attr            = local_assigns.fetch(:zone_attr, "stage")
+  dom_id_prefix        = local_assigns.fetch(:dom_id_prefix, "card-")
+  zone_selector_class  = local_assigns.fetch(:zone_selector_class, "kanban-dropzone")
+  empty_selector_class = local_assigns.fetch(:empty_selector_class, "kanban-empty")
+  empty_label          = local_assigns.fetch(:empty_label, "Drop here")
+  card_partial         = local_assigns.fetch(:card_partial)
+  card_as              = local_assigns.fetch(:card_as, :card)
+  card_locals          = local_assigns.fetch(:card_locals, nil)
+
+  key          = column[:key].to_s
+  label        = column[:label] || key
+  cards        = column[:cards] || []
+  count        = column.fetch(:count) { cards.size }
+  badge_class  = column[:badge_class]
+  collapsible  = column[:collapsible]
+  hidden       = column[:hidden]
+  header_extra = column[:header_extra]
+
+  # Merge the per-card hook (Proc or Hash) with the record binding.
+  resolve_locals = lambda do |record|
+    extra = card_locals.respond_to?(:call) ? card_locals.call(record) : (card_locals || {})
+    { card_as => record }.merge(extra || {})
+  end
+%>
+<div class="studio-board-column w-full flex-none sm:flex-1 sm:min-w-[190px]"
+     data-board-column="<%= key %>"
+     <% if collapsible %>data-board-collapsible="true"<% end %>
+     <% if hidden %>x-cloak style="display:none"<% end %>>
+  <div class="mb-3 px-1 flex items-center gap-2">
+    <h3 class="text-sm font-bold text-heading uppercase tracking-wider"><%= label %></h3>
+    <% if badge_class %>
+      <%= render "components/badge", text: count.to_s, scheme: badge_class, data_board_count: key %>
+    <% else %>
+      <span class="stage-count inline-flex items-center justify-center min-w-[20px] h-5 px-1.5 rounded-full text-xs font-bold bg-surface-alt text-secondary border border-subtle"
+            data-board-count="<%= key %>"><%= count %></span>
+    <% end %>
+    <% if header_extra %><%= header_extra %><% end %>
+  </div>
+
+  <div id="dropzone-<%= key %>"
+       data-<%= zone_attr %>="<%= key %>"
+       class="<%= zone_selector_class %> rounded-xl border-2 border-dashed border-subtle min-h-40 p-2 space-y-2 transition-colors duration-150 sm:min-h-[calc(100vh-220px)]">
+    <% cards.each do |record| %>
+      <%= render partial: card_partial, locals: resolve_locals.call(record) %>
+    <% end %>
+    <div class="<%= empty_selector_class %> flex items-center justify-center h-24 text-muted text-sm"
+         <% if cards.any? %>style="display: none"<% end %>>
+      <%= empty_label %>
+    </div>
+  </div>
+</div>