studio-engine 0.28.0 → 0.29.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 79aac649d7403deadeaa9f055762802f111b7082865398432753dfdd93b998e0
-  data.tar.gz: 80307a1b7077886c9853ad5a6ab7f2dc79a9d7bf6d4db7aa883f5eb6162a77bb
+  metadata.gz: b93ed19a9ea116acfe2d15bfcdd7cabc9abcf6ae2de9a63bfdcfc6d412d60e73
+  data.tar.gz: 9a98b2c22d817cddc642df050e1f9ecc34dfd87d9d87e4730b735774fec579b1
 SHA512:
-  metadata.gz: 8fb8f96918656e88d2d8cc3379716d544afd461bdaa19205c480e273ab71199c25cede8c7b729f9b6cf3400388a7976ac34f4135d96fd60b3e8e4083969f360e
-  data.tar.gz: 2f329ab8c0c240cf56e11e2e9d7bc1c3c6711e24dcb52ee82a2de2785c1697cf333e3bcc17f056db22400e4e606d6c30108565502bd8a6119e2d7b50e18a1a64
+  metadata.gz: 6d6cc744ebba89724d9811785d79a954d43b9cd9827d8fc5f86780cd465312668215b31a989cbb1a57c973ad74507600d7b4ae9179c912780c5beffa073c2f76
+  data.tar.gz: 39cace3ee05070698a8f06cf1c4463e03cf8bd8fdc97d2ad6b1b5d158a87fc23425e8618f09335034e5dfb04a70a5529b00c9a9743cedd001d6e9f6fe57204a4

data/CHANGELOG.md

@@ -2,6 +2,43 @@
 
 The format is [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). This project follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html) — `MAJOR.MINOR.PATCH`. Consumer Rails apps install the released RubyGems package with `gem "studio-engine", "~> 0.6"`; bumping the gem version and updating consumer lockfiles is a release.
 
+## 0.29.0 — 2026-07-29
+
+**The four depth-chart gaps folded into the `studio/board` primitive (Phase D), so
+the MS depth chart can rebase onto it like `/tasks`, news, and content did.** The
+0.28.0 primitive fit the near-identical kanban boards; the depth chart is more
+custom — it ranks by a `depth` column (1 = starter) while its `position` column
+holds a lane-code string, lays its lanes out in a two-level side→position grid, and
+pins locked starters. Each capability is **additive and opt-in — every hook omitted
+renders and ranks exactly as 0.28.0**, so `/tasks`, news, and content are untouched.
+
+### Added
+
+- **DG1 — configurable rank column + sort direction** (`Studio::Board::Rankable`):
+  `board_rank_attr` (default `:position`) and `board_rank_order` (default `:desc`)
+  thread through `board_ordered`, `board_next_position`, `set_initial_position`, and
+  `reposition!`. A depth chart sets `board_rank_attr = :depth`, `board_rank_order =
+  :asc` (depth 1 on top). The order fragment quotes the column and whitelists the
+  ASC/DESC literal — never user input.
+- **DG2 — sequential 1..N ranks**: `reposition!(ids, gap: 1, direction: :asc)` stamps
+  `1, 2, 3, … N` (the depth numbers) instead of the 100-gapped default.
+- **DG3 — two-level side→position grid**: `studio/board/_board` accepts `groups:`
+  (`[{ key:, label:, cols_class:, columns: [...] }]`) and renders each group as a
+  labelled section whose lanes lay out in a responsive grid; `studio/board/_column`
+  gains `layout: "grid"` (drops the flex-row width utilities so the grid cell sizes
+  the column). Omit `groups:` for the unchanged flat row.
+- **DG4 — per-card lock/pin**: `reposition!(skip_locked: true, lock_attr: :locked)`
+  leaves a pinned entry's rank untouched; `Studio::Board::Reorderable` gains the
+  matching `board_reorderable(rank_attr:, skip_locked:, lock_attr:)` config plus a
+  `board_toggle_lock` action (config-gated, `rescue_and_log(target:)` discipline,
+  `{ ok:, locked: }`); `studio/board/_card_shell` accepts `locked: true` (adds
+  `.kanban-locked` + `data-locked`); the `studioBoard` factory takes a
+  `lockedSelector` opt that filters locked cards from dragging and refuses a move
+  that would cross one, so a pinned starter keeps its slot while the rest reflow.
+- **`/admin/style`** gains a third live board specimen — the depth-chart shape:
+  Offense/Defense sections, position lanes in a grid, within-lane reorder, and 🔒
+  pinned starters.
+
 ## 0.27.0 — 2026-07-28
 
 **Two coordinated modal flows on the `/admin/style` Design System page — a walked

data/app/controllers/concerns/studio/board/reorderable.rb

@@ -28,21 +28,31 @@ module Studio
       extend ActiveSupport::Concern
 
       included do
-        class_attribute :board_reorder_model,     instance_accessor: false
-        class_attribute :board_reorder_id_attr,   instance_accessor: false, default: :slug
-        class_attribute :board_reorder_param,     instance_accessor: false, default: :slugs
-        class_attribute :board_reorder_gap,       instance_accessor: false, default: 100
-        class_attribute :board_reorder_direction, instance_accessor: false, default: :desc
+        class_attribute :board_reorder_model,       instance_accessor: false
+        class_attribute :board_reorder_id_attr,     instance_accessor: false, default: :slug
+        class_attribute :board_reorder_param,       instance_accessor: false, default: :slugs
+        class_attribute :board_reorder_gap,         instance_accessor: false, default: 100
+        class_attribute :board_reorder_direction,   instance_accessor: false, default: :desc
+        # DG1/DG2/DG4 — optional column + lock config. Defaults keep the exact 0.28.0
+        # kanban reorder: rank by the model's board_rank_attr, no lock skip. A depth
+        # chart passes gap: 1, direction: :asc (1..N depths) + skip_locked: true.
+        class_attribute :board_reorder_rank_attr,   instance_accessor: false, default: nil
+        class_attribute :board_reorder_skip_locked, instance_accessor: false, default: false
+        class_attribute :board_reorder_lock_attr,   instance_accessor: false, default: :locked
       end
 
       class_methods do
         # Configure the reorder action for this controller's board.
-        def board_reorderable(model:, id_attr: :slug, param: :slugs, gap: 100, direction: :desc)
-          self.board_reorder_model     = model
-          self.board_reorder_id_attr   = id_attr
-          self.board_reorder_param     = param
-          self.board_reorder_gap       = gap
-          self.board_reorder_direction = direction
+        def board_reorderable(model:, id_attr: :slug, param: :slugs, gap: 100, direction: :desc,
+                              rank_attr: nil, skip_locked: false, lock_attr: :locked)
+          self.board_reorder_model       = model
+          self.board_reorder_id_attr     = id_attr
+          self.board_reorder_param       = param
+          self.board_reorder_gap         = gap
+          self.board_reorder_direction   = direction
+          self.board_reorder_rank_attr   = rank_attr
+          self.board_reorder_skip_locked = skip_locked
+          self.board_reorder_lock_attr   = lock_attr
         end
       end
 
@@ -72,23 +82,59 @@ module Studio
         render json: { error: e.message }, status: :unprocessable_entity
       end
 
+      # POST — flip a card's lock flag (DG4). A locked entry is a pinned card the
+      # reorder skips (a confirmed depth-chart starter). Config-gated on the
+      # board_reorderable model + lock_attr; mirrors the MS depth-chart toggle_lock,
+      # INCLUDING its rescue_and_log(target: record) backend-write discipline, and
+      # the same respond_to? degrade the reorder action uses. Route it however the
+      # app names the endpoint (e.g. `post "…/:id/toggle_lock"`).
+      def board_toggle_lock
+        model = self.class.board_reorder_model
+        raise "board_reorderable model not configured" unless model
+
+        id_attr   = self.class.board_reorder_id_attr
+        lock_attr = self.class.board_reorder_lock_attr
+        record    = model.find_by(id_attr => params[:id])
+        return render(json: { error: "not found" }, status: :not_found) unless record
+
+        flip = -> { record.update!(lock_attr => !record.public_send(lock_attr)) }
+        if respond_to?(:rescue_and_log)
+          rescue_and_log(target: record) { flip.call }
+        else
+          flip.call
+        end
+        render json: { ok: true, locked: record.public_send(lock_attr) }
+      rescue StandardError => e
+        render json: { error: e.message }, status: :unprocessable_entity
+      end
+
       private
 
       # Delegate to the model's Rankable#reposition! when available (the shared
-      # 100-gap rule), else fall back to the same per-id update_all loop inline so
-      # a model that only carries a `position` column still reorders.
+      # rank rule), else fall back to the same per-id update_all loop inline so a
+      # model that only carries a rank column still reorders. Threads the DG1 rank
+      # column and DG4 lock-skip config through both paths.
       def board_reorder_apply(model, ids)
-        id_attr   = self.class.board_reorder_id_attr
-        gap       = self.class.board_reorder_gap
-        direction = self.class.board_reorder_direction
+        id_attr     = self.class.board_reorder_id_attr
+        gap         = self.class.board_reorder_gap
+        direction   = self.class.board_reorder_direction
+        rank_attr   = self.class.board_reorder_rank_attr
+        skip_locked = self.class.board_reorder_skip_locked
+        lock_attr   = self.class.board_reorder_lock_attr
 
         if model.respond_to?(:reposition!)
-          model.reposition!(ids, gap: gap, direction: direction, id_attr: id_attr)
+          kwargs = { gap: gap, direction: direction, id_attr: id_attr,
+                     skip_locked: skip_locked, lock_attr: lock_attr }
+          kwargs[:rank_attr] = rank_attr if rank_attr
+          model.reposition!(ids, **kwargs)
         else
+          rank_col = rank_attr || :position
           length = ids.length
           ids.each_with_index do |id, index|
             rank = direction.to_sym == :asc ? (index + 1) * gap : (length - index) * gap
-            model.where(id_attr => id).update_all(position: rank)
+            rel  = model.where(id_attr => id)
+            rel  = rel.where.not(lock_attr => true) if skip_locked
+            rel.update_all(rank_col => rank)
           end
         end
       end

data/app/models/concerns/studio/board/rankable.rb

@@ -21,7 +21,9 @@ module Studio
     #
     #   class DepthChartEntry < ApplicationRecord
     #     include Studio::Board::Rankable
-    #     self.board_zone_attr = :position_group   # a lane, not a kanban stage
+    #     self.board_zone_attr = :position     # a lane (QB/RB/…), not a kanban stage
+    #     self.board_rank_attr = :depth        # rank by depth; `position` is a string
+    #     self.board_rank_order = :asc         # depth 1 (the starter) sits on top
     #   end
     module Rankable
       extend ActiveSupport::Concern
@@ -31,19 +33,37 @@ module Studio
         # boards (stage); a within-lane board overrides it, and `nil` ranks globally.
         class_attribute :board_zone_attr, instance_accessor: false, default: :stage
 
-        # Board order: highest `position` first (freshest/top card wins), NULLS last,
-        # then newest by created_at as a stable tiebreak. Arel.sql: the fragment is a
-        # fixed literal, not user input.
-        scope :board_ordered, -> { order(Arel.sql("position DESC NULLS LAST, created_at DESC")) }
+        # The column the board RANKS BY. Default :position — the three MS kanban
+        # boards and the 100-gap read-model. A board whose rank lives in another
+        # column overrides it: the depth chart ranks by `depth` while its `position`
+        # column holds a lane-code STRING, so every ranking read/write below follows
+        # `board_rank_attr` rather than a hardcoded `position`.
+        class_attribute :board_rank_attr, instance_accessor: false, default: :position
+
+        # The board_ordered sort direction for the rank column. :desc (default) puts
+        # the HIGHEST rank on top — the kanban freshest-first shape; :asc puts the
+        # LOWEST on top so depth 1 (the starter) sits at the top of its lane.
+        class_attribute :board_rank_order, instance_accessor: false, default: :desc
+
+        # Board order: the rank column first (direction per board_rank_order), NULLS
+        # last, then newest by created_at as a stable tiebreak. The column name is a
+        # quoted identifier and the direction a whitelisted ASC/DESC literal — never
+        # user input — so the Arel.sql fragment is injection-safe.
+        scope :board_ordered, lambda {
+          dir = board_rank_order.to_s.casecmp("asc").zero? ? "ASC" : "DESC"
+          col = connection.quote_column_name(board_rank_attr)
+          order(Arel.sql("#{col} #{dir} NULLS LAST, created_at DESC"))
+        }
       end
 
-      # Seed the genesis rank on create: max(position) within this record's zone plus
-      # a 100 gap. A no-op when `position` is already set, so an explicit rank is
+      # Seed the genesis rank on create: max(rank column) within this record's zone
+      # plus a 100 gap. A no-op when the rank is already set, so an explicit rank is
       # never clobbered. Wire from the host via `before_create :set_initial_position`.
       def set_initial_position
-        return if position.present?
+        rank_attr = self.class.board_rank_attr
+        return if public_send(rank_attr).present?
 
-        self.position = self.class.board_next_position(zone_value_for_rank)
+        public_send("#{rank_attr}=", self.class.board_next_position(zone_value_for_rank))
       end
 
       # This record's zone value (nil when the model ranks globally).
@@ -58,7 +78,7 @@ module Studio
         # from here, so the 100-gap rule lives in one place.
         def board_next_position(zone_value = nil, gap: 100)
           scope = board_zone_attr && zone_value ? where(board_zone_attr => zone_value) : all
-          (scope.maximum(:position) || 0) + gap
+          (scope.maximum(board_rank_attr) || 0) + gap
         end
 
         # Restamp a column top-to-bottom in ONE pass. `ids` arrive in DOM order (top
@@ -69,12 +89,23 @@ module Studio
         # (first id smallest) for an ascending board. This is exactly the per-id
         # `update_all(position: ...)` loop the MS tasks/news/content reorder actions
         # each ran by hand, lifted into the model. Returns the ids it stamped.
-        def reposition!(ids, gap: 100, direction: :desc, id_attr: primary_key)
+        #
+        # DG2 — SEQUENTIAL 1..N RANKS: `gap: 1, direction: :asc` stamps 1, 2, 3, … N
+        # (the depth chart's depth numbers, 1 = starter), not the 100-gapped default.
+        # DG1 — a board that ranks by another column passes `rank_attr:` (defaults to
+        # the model's `board_rank_attr`, so a configured model needs nothing here).
+        # DG4 — `skip_locked: true` leaves a PINNED entry untouched: its rank column is
+        # not written, so a locked starter keeps its depth while the others reflow
+        # around it. The lock flag column is `lock_attr` (default :locked).
+        def reposition!(ids, gap: 100, direction: :desc, id_attr: primary_key,
+                        rank_attr: board_rank_attr, skip_locked: false, lock_attr: :locked)
           ids = Array(ids)
           length = ids.length
           ids.each_with_index do |id, index|
             rank = direction.to_sym == :asc ? (index + 1) * gap : (length - index) * gap
-            where(id_attr => id).update_all(position: rank)
+            rel  = where(id_attr => id)
+            rel  = rel.where.not(lock_attr => true) if skip_locked
+            rel.update_all(rank_attr => rank)
           end
           ids
         end

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

@@ -51,6 +51,10 @@
         // gap 3: the column key a data-exit-action="archive" remove re-parents INTO
         // (its #dropzone-<key>) rather than deleting the card. null ⇒ 0.27.0 removal.
         archiveZone:    opts.archiveZone || null,
+        // DG4: selector for PINNED cards (a locked depth-chart starter). When set,
+        // locked cards are filtered from dragging AND a drag can't cross one, so a
+        // pinned card keeps its slot while the rest reflow. null ⇒ every card drags.
+        lockedSelector: opts.lockedSelector || null,
 
         // --- state ---------------------------------------------------------
         toasts: [],
@@ -104,7 +108,9 @@
               animation: 150,
               ghostClass: "opacity-30",
               draggable: self.cardSelector,
-              filter: self.sortFilter,
+              // DG4: locked cards join the undraggable filter so a pinned entry
+              // can't be picked up (empty state was already filtered).
+              filter: self.lockedSelector ? (self.sortFilter + ", " + self.lockedSelector) : self.sortFilter,
               onStart: function () { window.__studioBoardDragging = true; },
               onEnd: function (evt) {
                 self.handleSortEnd(evt);
@@ -113,6 +119,13 @@
             };
             if (self.groupName) cfg.group = self.groupName; // omit ⇒ within-zone only
             if (self.handle) cfg.handle = self.handle;
+            if (self.lockedSelector) {
+              // DG4: pin locked cards — refuse a move that would cross a locked
+              // sibling, so a dragged card can't leapfrog a pinned starter.
+              cfg.onMove = function (evt) {
+                return !(evt.related && evt.related.matches && evt.related.matches(self.lockedSelector));
+              };
+            }
             Sortable.create(zone, cfg);
           });
         },

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

@@ -33,13 +33,29 @@
     4. An Archived column that a stage→archived broadcast should re-parent INTO
        (not delete) is named by the board's `archive_zone:`.
 
+  TWO-LEVEL GRID (DG3, the depth-chart shape) — a board whose columns group into
+  labelled SECTIONS laid out as a grid (offense/defense/special_teams, each a grid
+  of position lanes) passes `groups:` instead of a flat `columns:` row. Each group
+  renders a header + a responsive grid of its columns (the same studio/board/column,
+  layout: "grid"). Omit `groups:` and the board renders the 0.28.0 flat row unchanged.
+
   locals:
-    columns:          (req) [{ key:, label:, cards:, count:, badge_class:,
-                      count_class:, collapsible:, hidden:, show_expr:, min_width:,
-                      kickoff:, header_extra: }]. `cards` are records passed to
-                      `card_partial`; `count` defaults to cards.size. See
+    columns:          (req unless `groups:`) [{ key:, label:, cards:, count:,
+                      badge_class:, count_class:, collapsible:, hidden:, show_expr:,
+                      min_width:, kickoff:, header_extra: }]. `cards` are records
+                      passed to `card_partial`; `count` defaults to cards.size. See
                       studio/board/_column for the additive per-column hooks
                       (count_class / show_expr / min_width / kickoff).
+    groups:           DG3 — [{ key:, label:, cols_class:, columns: [<column hash>] }]
+                      renders a two-level side→position GRID: each group is a labelled
+                      section whose `columns` lay out in a grid (`cols_class` overrides
+                      the responsive default). Takes precedence over the flat `columns`
+                      row; the factory's labels merge across every group's columns.
+    locked_selector:  DG4 — CSS selector for PINNED cards (default ".kanban-locked",
+                      emitted by studio/board/_card_shell `locked: true`). When set,
+                      the studioBoard factory filters those cards from dragging and
+                      won't let a drag cross them, so a locked starter stays put. nil
+                      keeps every card draggable (0.28.0).
     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.
@@ -78,7 +94,11 @@
     demo:             style-guide preview — drag works locally, no network POST.
 %>
 <%
-  columns          = local_assigns.fetch(:columns)
+  groups           = local_assigns.fetch(:groups, nil)   # DG3: two-level side→position grid
+  columns          = local_assigns.fetch(:columns, nil)
+  # The factory's label map + the flat fallback both need every column; a grouped
+  # board flattens its groups' columns, a flat board uses `columns` directly.
+  all_columns      = groups ? groups.flat_map { |g| Array(g[:columns]) } : (columns || [])
   card_partial     = local_assigns.fetch(:card_partial)
   card_as          = local_assigns.fetch(:card_as, :card)
   card_locals      = local_assigns.fetch(:card_locals, nil)
@@ -103,6 +123,7 @@
   above_board_slot = local_assigns.fetch(:above_board_slot, nil)
   board_state      = local_assigns.fetch(:board_state, nil)   # gap 1: chrome-state home
   archive_zone     = local_assigns.fetch(:archive_zone, nil)  # gap 3: exit re-parent target
+  locked_selector  = local_assigns.fetch(:locked_selector, nil) # DG4: pinned-card selector
   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)
@@ -128,10 +149,11 @@
     demo:           !!demo,
     state:          (board_state.is_a?(Hash) ? board_state : nil),
     archiveZone:    (archive_zone ? archive_zone.to_s : nil),
+    lockedSelector: (locked_selector ? locked_selector.to_s : nil),
     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] }
+    labels:         all_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 %>)">
@@ -140,20 +162,49 @@
   <% 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 groups %>
+    <%# DG3: two-level side→position grid — each group a labelled section, its
+        columns in a responsive grid (the same studio/board/column, layout: grid). %>
+    <div class="studio-board-grid space-y-8">
+      <% groups.each do |group| %>
+        <section class="studio-board-group" data-board-group="<%= group[:key] %>">
+          <% if group[:label] %>
+            <h2 class="mb-3 text-xs font-bold uppercase tracking-widest text-secondary"><%= group[:label] %></h2>
+          <% end %>
+          <div class="grid gap-4 <%= group[:cols_class] || "grid-cols-2 sm:grid-cols-3 lg:grid-cols-4" %>">
+            <% Array(group[:columns]).each do |column| %>
+              <%= render "studio/board/column",
+                    column: column,
+                    layout: "grid",
+                    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>
+        </section>
+      <% end %>
+    </div>
+  <% else %>
+    <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>
+  <% end %>
 
   <% if toasts %>
     <div class="studio-board-toasts fixed top-4 right-4 z-50 space-y-2" data-test="studio-board-toasts">

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

@@ -24,6 +24,11 @@
     card_class:    the required base class. Default "kanban-card".
     class:         extra classes appended after card_class.
     style:         inline style string.
+    locked:        DG4 — a PINNED card the reorder skips (a confirmed depth-chart
+                   starter). Adds the `.kanban-locked` class the studioBoard factory
+                   filters from dragging + the `data-locked="true"` marker; false
+                   (default) renders identically to before. Purely a hook — the lock
+                   glyph/visual lives in the app's card body.
     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.
@@ -37,11 +42,14 @@
   card_class    = local_assigns.fetch(:card_class, "kanban-card")
   extra_class   = local_assigns.fetch(:class, nil)
   inline_style  = local_assigns.fetch(:style, nil)
+  locked        = local_assigns.fetch(:locked, false)
   root_attrs    = local_assigns.fetch(:attrs, {}) || {}
+  classes       = [card_class, ("kanban-locked" if locked), extra_class].compact.join(" ")
 %>
 <div id="<%= dom_id_prefix %><%= id %>"
-     class="<%= [card_class, extra_class].compact.join(" ") %>"
+     class="<%= classes %>"
      data-<%= id_attr %>="<%= id %>"
      data-<%= zone_attr %>="<%= zone %>"
+     <% if locked %>data-locked="true"<% end %>
      <% 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

@@ -31,6 +31,10 @@
                             kickoff:     raw HTML rendered in a fixed-height slot
                               under the header row (a per-column kickoff chip);
                               nil renders nothing.
+    layout:               DG3 — "row" (default) sizes the column for the horizontal
+                          flex row (flex-1 + min_width); "grid" drops those so a
+                          two-level side→position GRID cell owns the sizing. Any
+                          other value behaves as "row".
     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".
@@ -42,6 +46,7 @@
 %>
 <%
   column               = local_assigns.fetch(:column)
+  layout               = local_assigns.fetch(:layout, "row").to_s
   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")
@@ -70,6 +75,9 @@
   # The neutral count chip's colour classes: an opt-in raw class, else the 0.27.0
   # neutral default. The layout classes are shared; only the colour band varies.
   count_color  = count_class || "bg-surface-alt text-secondary border border-subtle"
+  # DG3: in a grid the cell owns the sizing, so drop the flex-row width utilities;
+  # "row" (default) keeps the exact 0.28.0 flex-1 + min-width column.
+  width_class  = layout == "grid" ? "w-full" : "w-full flex-none sm:flex-1 #{min_width}"
 
   # Merge the per-card hook (Proc or Hash) with the record binding.
   resolve_locals = lambda do |record|
@@ -77,7 +85,7 @@
     { card_as => record }.merge(extra || {})
   end
 %>
-<div class="studio-board-column w-full flex-none sm:flex-1 <%= min_width %>"
+<div class="studio-board-column <%= width_class %>"
      data-board-column="<%= key %>"
      <% if collapsible %>data-board-collapsible="true"<% end %>
      <% if show_expr %>x-show="<%= show_expr %>" x-cloak<% end %>

data/app/views/style/_tasks.html.erb

@@ -172,6 +172,54 @@
           empty_label: "Drop tasks here" %>
   </div>
 
+  <%# ---- The DEPTH-CHART shape (0.29.0 / DG) ----------------------------- %>
+  <%# The two-level side→position GRID + per-card lock the depth chart needs, all
+      additive: groups: renders labelled sections (Offense/Defense) whose position
+      lanes lay out in a grid (not the flat row); group: false keeps a drag WITHIN
+      its lane; zone_attr "position" is the lane; 🔒 starters carry `locked: true`
+      so the factory filters them from dragging (locked_selector) and a drag can't
+      cross them. reorder is 1..N (depth) — demonstrated statically here (demo). %>
+  <%
+    dc_groups = [
+      { key: "offense", label: "Offense", cols_class: "grid-cols-2 sm:grid-cols-3",
+        columns: [
+          { key: "QB", label: "QB", cards: [
+            { id: "dc-qb1", zone: "QB", title: "Starter QB", repo: "depth 1", who: "1", locked: true },
+            { id: "dc-qb2", zone: "QB", title: "Backup QB",  repo: "depth 2", who: "2" },
+            { id: "dc-qb3", zone: "QB", title: "3rd string", repo: "depth 3", who: "3" } ] },
+          { key: "RB", label: "RB", cards: [
+            { id: "dc-rb1", zone: "RB", title: "RB1", repo: "depth 1", who: "1" },
+            { id: "dc-rb2", zone: "RB", title: "RB2", repo: "depth 2", who: "2" } ] },
+          { key: "WR", label: "WR", cards: [
+            { id: "dc-wr1", zone: "WR", title: "WR1", repo: "depth 1", who: "1" } ] } ] },
+      { key: "defense", label: "Defense", cols_class: "grid-cols-2 sm:grid-cols-3",
+        columns: [
+          { key: "EDGE", label: "EDGE", cards: [
+            { id: "dc-edge1", zone: "EDGE", title: "EDGE1", repo: "depth 1", who: "1" },
+            { id: "dc-edge2", zone: "EDGE", title: "EDGE2", repo: "depth 2", who: "2" } ] },
+          { key: "CB", label: "CB", cards: [
+            { id: "dc-cb1", zone: "CB", title: "Starter CB", repo: "depth 1", who: "1", locked: true },
+            { id: "dc-cb2", zone: "CB", title: "CB2",        repo: "depth 2", who: "2" } ] } ] }
+    ]
+  %>
+  <div class="space-y-3">
+    <div class="flex items-center gap-2">
+      <span class="badge" style="color: var(--color-warning); border-color: var(--color-warning)">Grid + Lock</span>
+      <p class="label-upper"><code class="font-mono text-2xs">studio/board/board</code> &middot; DG (0.29.0) &mdash; two-level side&rarr;position grid, reorder within a lane, &#128274; pinned starters stay put</p>
+    </div>
+    <%= render "studio/board/board",
+          demo: true,
+          groups: dc_groups,
+          card_partial: "style/board/demo_card",
+          card_as: :card,
+          reorder_url: "#",
+          group: false,
+          zone_attr: "position",
+          locked_selector: ".kanban-locked",
+          card_locals: { zone_attr: "position" },
+          empty_label: "&mdash;".html_safe %>
+  </div>
+
   <%# ---- The static reference sketch ------------------------------------- %>
   <div class="fade-edge-x overflow-x-auto pb-2">
     <div class="flex gap-4 min-w-max">

data/app/views/style/board/_demo_card.html.erb

@@ -7,11 +7,15 @@
   id_attr / zone_attr flow through from the board so the same partial demonstrates
   the primitive under both the default and a custom attribute naming.
 %>
+<%# A locked card (DG4) flows `locked: true` to the card-shell — it gains the
+    .kanban-locked class the factory filters from dragging, and shows a 🔒 in place
+    of the drag glyph so the pinned state reads at a glance. %>
 <%= render layout: "studio/board/card_shell",
       locals: { id: card[:id], zone: card[:zone], id_attr: id_attr, zone_attr: zone_attr,
-                class: "card p-3 space-y-2 cursor-grab active:cursor-grabbing" } do %>
+                locked: card[:locked],
+                class: "card p-3 space-y-2 #{card[:locked] ? "cursor-default opacity-90" : "cursor-grab active:cursor-grabbing"}" } do %>
   <div class="flex items-start gap-2">
-    <span class="text-muted select-none leading-none" aria-hidden="true">⠿</span>
+    <span class="text-muted select-none leading-none" aria-hidden="true"><%= card[:locked] ? "🔒" : "⠿" %></span>
     <p class="text-sm font-semibold text-heading leading-snug flex-1"><%= card[:title] %></p>
   </div>
   <div class="flex items-center justify-between gap-2">

data/lib/studio/version.rb

@@ -1,3 +1,3 @@
 module Studio
-  VERSION = "0.28.0"
+  VERSION = "0.29.0"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: studio-engine
 version: !ruby/object:Gem::Version
-  version: 0.28.0
+  version: 0.29.0
 platform: ruby
 authors:
 - Alex McRitchie