studio-engine 0.131.0 → 0.133.0

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

@@ -17,22 +17,15 @@
 <%
   media_style = "background-image: repeating-linear-gradient(135deg, var(--color-primary) 0 18px, var(--color-accent) 18px 36px, var(--color-warning) 36px 54px, var(--color-success) 54px 72px)"
 
+  # Each specimen names its trick (config/studio_tricks.yml): Scrim, Tint, Shade, and
+  # the Scrim's soft and strong variants, which each keep a stage of their own so the
+  # lab can grade every wash on its own panel.
   specimens = [
-    { key: "theme",  tone: nil,           scrim: "scrim",
-      klass: ".scrim",
-      note:  "Theme-aware: a tint in light mode, a shade in dark." },
-    { key: "tint",   tone: "scrim-tint",  scrim: "scrim",
-      klass: ".scrim-tint .scrim",
-      note:  "Forced tint, in either theme. Dark ink." },
-    { key: "shade",  tone: "scrim-shade", scrim: "scrim",
-      klass: ".scrim-shade .scrim",
-      note:  "Forced shade, in either theme. Light ink." },
-    { key: "soft",   tone: nil,           scrim: "scrim scrim-soft",
-      klass: ".scrim .scrim-soft",
-      note:  "A lighter wash: more of the media shows." },
-    { key: "strong", tone: nil,           scrim: "scrim scrim-strong",
-      klass: ".scrim .scrim-strong",
-      note:  "A heavier wash, for long or small text." }
+    { key: "theme",  tone: nil,           scrim: "scrim",              trick: "scrim" },
+    { key: "tint",   tone: "scrim-tint",  scrim: "scrim",              trick: "tint" },
+    { key: "shade",  tone: "scrim-shade", scrim: "scrim",              trick: "shade" },
+    { key: "soft",   tone: nil,           scrim: "scrim scrim-soft",   trick: "scrim", variant: "soft" },
+    { key: "strong", tone: nil,           scrim: "scrim scrim-strong", trick: "scrim", variant: "strong" }
   ]
 %>
 <section id="scrims" class="space-y-5" data-scrim-group>
@@ -42,16 +35,13 @@
   </div>
   <div class="grid gap-4 sm:grid-cols-2 lg:grid-cols-3">
     <% specimens.each do |s| %>
-      <% tone_attr = s[:tone] ? %( class="#{s[:tone]} relative ...") : %( class="relative ...") %>
-      <%= render layout: "style/specimen",
-            locals: { klass: s[:klass],
-                      usage: %(<section#{tone_attr}>\n  <img class="absolute inset-0 ..." src="...">\n  <div class="#{s[:scrim]} absolute inset-0"></div>\n  <div class="relative z-10">\n    <h2 class="scrim-ink">Headline</h2>\n    <p class="scrim-ink-muted">Subtitle</p>\n  </div>\n</section>) } do %>
+      <%= render layout: "style/specimen", locals: { trick: s[:trick], variant: s[:variant] } do %>
         <div class="relative w-full max-w-xs h-36 rounded-lg overflow-hidden <%= s[:tone] %>" data-scrim-specimen="<%= s[:key] %>">
           <div class="absolute inset-0" style="<%= media_style %>" aria-hidden="true"></div>
           <div class="<%= s[:scrim] %> absolute inset-0" data-scrim-wash></div>
           <div class="relative z-10 h-full flex flex-col items-center justify-center gap-1 px-4 text-center">
             <p class="scrim-ink text-lg font-extrabold" data-scrim-ink>Solutions For Business</p>
-            <p class="scrim-ink-muted text-sm" data-scrim-ink-muted><%= s[:note] %></p>
+            <p class="scrim-ink-muted text-sm" data-scrim-ink-muted><%= Studio::Tricks.fetch(s[:trick], s[:variant]).note %></p>
           </div>
         </div>
       <% end %>

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

@@ -2,13 +2,13 @@
      The primitives a public site ends with: the footer, its map, and the Google
      Calendar booking frame, popup and link (docs/SITE_FOOTER.md,
      docs/BOOKING.md). Each card
-     gives the helper to call; the preview below them is the real footer partial,
+     names its trick and the helper to call; the preview below them is the real footer partial,
      rendered with THIS app's facts when it has declared any and with a sample
      when it has not, so the group is never empty.
 
      The booking frame is DRAWN, not embedded: a style guide should not ask
      Google for a calendar every time an admin scrolls past. Its two states, whole
-     and cropped, are quarter-scale drawings of a made-up schedule (a 720px page
+     and cropped, share the Booking Frame card: quarter-scale drawings of a made-up schedule (a 720px page
      whose box runs from 200 to 600), cropped by the same arithmetic the real
      wrapper uses (Studio::Booking.crop). No real schedule's numbers are here. %>
 <%
@@ -47,16 +47,12 @@
   </div>
 
   <div class="grid gap-4 sm:grid-cols-2 lg:grid-cols-3">
-    <%= render layout: "style/specimen",
-          locals: { klass: "studio_site_footer",
-                    usage: %(studio_site_footer   # one line, at the end of the layout body) } do %>
+    <%= render layout: "style/specimen", locals: { trick: "site_footer" } do %>
       <p class="text-sm text-secondary text-center">Previewed below.</p>
     <% end %>
 
     <%= render layout: "style/specimen",
-          locals: { klass: "studio_booking_link",
-                    disabled: !booking, disabled_label: "no booking_url",
-                    usage: %(studio_booking_link "Schedule a call", class: "btn btn-primary") } do %>
+          locals: { trick: "booking_link", disabled: !booking, disabled_label: "no booking_url" } do %>
       <% if booking %>
         <%= studio_booking_link "Schedule a call", class: "btn btn-primary" %>
       <% else %>
@@ -64,16 +60,12 @@
       <% end %>
     <% end %>
 
-    <% [ [ "studio_booking_frame", nil, "whole",
-           %(studio_booking_frame   # whole at rest: the default, and crop: false),
-           "Whole at rest, the default." ],
-         [ "config.booking_crop", sample_crop, "cropped",
-           %(config.booking_crop = { top: 200, bottom: 600, frame_height: 720 }   # bin/booking-crop-measure prints yours),
-           "Cropped to the slot picker at rest." ]
-       ].each do |klass, crop, state, usage, caption| %>
-      <%= render layout: "style/specimen",
-            locals: { klass: klass, disabled: !booking, disabled_label: "no booking_url", usage: usage } do %>
-        <div class="w-full space-y-3" data-booking-specimen="<%= state %>">
+    <%= render layout: "style/specimen",
+          locals: { trick: "booking_frame", disabled: !booking, disabled_label: "no booking_url" } do %>
+      <% [ [ nil, "whole", "Whole at rest, the default." ],
+           [ sample_crop, "cropped", "Cropped to the slot picker at rest." ]
+         ].each do |crop, state, caption| %>
+        <div class="space-y-3" data-booking-specimen="<%= state %>">
           <div style="margin-inline: auto; width: 11rem; overflow: hidden; background: #fff; border-radius: .5rem; border: 1px solid rgb(127 127 127 / .35); height: <%= ((crop ? crop[:window] : 720) * scale).round %>px;">
             <div style="margin-top: -<%= ((crop ? crop[:offset] : 0) * scale).round %>px;">
               <% sample_page.each do |label, from, to, box| %>

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

@@ -1,13 +1,15 @@
 <%#  Specimen card for the living style guide (admin/style).
-     Reusable chrome around ONE primitive, framed for copy-paste-for-an-agent:
-       stage - the rendered primitive (yielded from the caller block)
-       meta  - its class name and a copyable usage snippet; one Copy per card (the
-               snippet's, else the class name's)
+     Reusable chrome around ONE primitive, named so Alex McRitchie can say it to an
+     agent ("add a Sheen"):
+       stage - the rendered primitive (yielded from the caller block), with its
+               variants side by side when the card folds them in
+       label - the trick's name, a one-line note and its class or helper, read from
+               config/studio_tricks.yml by key (style/_trick_label), with one Copy
+               that copies the agent line, never a markup snippet
      locals:
-       klass          (String, required) - the class label, shown prominently with a
-                       copy button so an agent can grab the exact class list.
-       usage          (String, optional) - a copyable usage snippet.
-       note           (String, optional) - one short sentence on what it does.
+       trick          (String, required) - the registry key (config/studio_tricks.yml).
+       variant        (String, optional) - a variant with a card of its own
+                       ("Loader · orbit"); the card is then named for the variant.
        disabled       (Boolean, optional) - render "disabled but present": the
                        primitive stays visible + previewable but is muted/greyed
                        and flagged, for a capability the host app has turned off
@@ -30,7 +32,7 @@
   # utilities and lift the opacity a touch so the trigger reads as tappable.
   inner_cls = openable ? "opacity-60 grayscale" : "opacity-40 grayscale select-none pointer-events-none"
 %>
-<article class="card overflow-hidden flex flex-col h-full<%= " opacity-95" if disabled %>" <%= 'aria-disabled="true"'.html_safe if disabled %>>
+<article class="card overflow-hidden flex flex-col h-full<%= " opacity-95" if disabled %>" <%= tag.attributes(data: { trick: local_assigns.fetch(:trick), trick_variant: local_assigns[:variant] }, aria: { disabled: ("true" if disabled) }) %>>
   <div class="relative flex flex-1 flex-wrap items-center justify-center gap-4 p-6 bg-surface-alt min-h-32">
     <% if disabled %>
       <span class="absolute top-2 right-2 badge z-10" style="color: var(--color-warning); border-color: var(--color-warning)"><%= disabled_label %></span>
@@ -39,37 +41,7 @@
       <%= yield %>
     <% end %>
   </div>
-  <div class="border-t border-subtle p-3 space-y-2">
-    <% if local_assigns[:note].present? %>
-      <p class="text-sm text-body"><%= local_assigns[:note] %></p>
-    <% end %>
-    <%# ONE Copy per card. With a usage snippet, the snippet's Copy is the one: it holds
-        the class too. Without one, the class name carries the Copy. %>
-    <% snippet = local_assigns[:usage] %>
-    <div class="flex items-start justify-between gap-2" x-data="{ copied: false }">
-      <code x-ref="klass" class="font-mono text-xs font-bold text-heading break-all leading-relaxed flex-1 min-w-0"><%= local_assigns[:klass] %></code>
-      <% unless snippet.present? %>
-        <button type="button"
-                class="btn btn-neutral btn-sm shrink-0"
-                aria-label="Copy class name"
-                @click="navigator.clipboard?.writeText($refs.klass.innerText); copied = true; setTimeout(() => copied = false, 1200)">
-          <span x-text="copied ? 'Copied' : 'Copy'">Copy</span>
-        </button>
-      <% end %>
-    </div>
-    <% if snippet.present? %>
-      <%# The code wraps inside its box, and pr-24 keeps every line clear of the Copy
-          button, "Copied" included: 74px with its inset on macOS, 3px wider in CI's
-          Linux fonts, so pr-20 was not enough. %>
-      <div class="relative" x-data="{ copied: false }">
-        <pre class="bg-inset text-body text-2xs rounded-lg px-3 py-2 pr-24 whitespace-pre-wrap break-words"><code x-ref="snippet"><%= snippet %></code></pre>
-        <button type="button"
-                class="btn btn-neutral btn-sm absolute top-2 right-2"
-                aria-label="Copy usage snippet"
-                @click="navigator.clipboard?.writeText($refs.snippet.innerText); copied = true; setTimeout(() => copied = false, 1200)">
-          <span x-text="copied ? 'Copied' : 'Copy'">Copy</span>
-        </button>
-      </div>
-    <% end %>
+  <div class="border-t border-subtle p-3">
+    <%= render "style/trick_label", trick: local_assigns.fetch(:trick), variant: local_assigns[:variant] %>
   </div>
 </article>

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

@@ -28,20 +28,6 @@
       cards: [{ id: "ses-email-backend", zone: "shipped", title: "SES email backend", repo: "mcritchie", who: "ST" }] }
   ]
 
-  # Copy-paste-for-an-agent usage. Built by array-join, NOT a heredoc: a heredoc as
-  # the last expression of an ERB scriptlet trips Erubi, and literal ERB tags in the
-  # body would close the tag. Plain render() calls read clearly for an agent.
-  board_usage_snippet = [
-    "# the board; it needs nothing else on the page:",
-    'render "studio/board/board",',
-    "  columns: @columns,            # [{ key:, label:, cards:, badge_class: }]",
-    '  card_partial: "tasks/task_card",',
-    "  reorder_url: tasks_reorder_path,        # POST { slugs: [...], zone: }",
-    '  move_url: "/tasks/:id.json",            # PATCH { task: { stage: } }',
-    '  move_param: { resource: "task", attr: "stage" },',
-    '  live_channel: "deployments"'
-  ].join("\n")
-
   # The static reference palette below (unchanged): each column maps to a stage-*
   # badge scheme.
   board_columns = [
@@ -84,14 +70,10 @@
           move_param: { resource: "task", attr: "stage" },
           group: "studio-board-demo",
           empty_label: "Drop tasks here" %>
-    <div class="relative" x-data="{ copied: false }">
-      <pre class="bg-inset text-body text-2xs rounded-lg px-3 py-2 pr-16 overflow-x-auto"><code x-ref="boardUsage"><%= board_usage_snippet %></code></pre>
-      <button type="button"
-              class="btn btn-neutral btn-sm absolute top-2 right-2"
-              aria-label="Copy usage snippet"
-              @click="navigator.clipboard?.writeText($refs.boardUsage.innerText); copied = true; setTimeout(() => copied = false, 1200)">
-        <span x-text="copied ? 'Copied' : 'Copy'">Copy</span>
-      </button>
+    <%# Its name, not a snippet (config/studio_tricks.yml): an agent reads the locals
+        from studio/board/_board's header. %>
+    <div class="card p-3" data-trick="board">
+      <%= render "style/trick_label", trick: "board" %>
     </div>
   </div>
 

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

@@ -0,0 +1,33 @@
+<%#  A trick's name, note and token, with one Copy (config/studio_tricks.yml).
+     The name is the heading because it is what a person says to an agent ("add a
+     Sheen"); the token is what the agent writes, so it sits under it, small and
+     muted. Copy puts the agent line on the clipboard: the name and the token,
+     variants included (Studio::Tricks.agent_line). No markup snippet: an agent can
+     read the markup from the engine, and only the name has to travel by word.
+     locals:
+       trick   (String, required) - the registry key.
+       variant (String, optional) - one variant's own label. %>
+<% t = Studio::Tricks.fetch(trick, local_assigns[:variant]) %>
+<div class="flex items-start justify-between gap-3" x-data="{ copied: false }">
+  <div class="min-w-0 flex-1 space-y-1">
+    <h4 class="type-h4 text-heading" data-trick-name><%= t.name %></h4>
+    <p class="text-sm text-body" data-trick-note><%= t.note %></p>
+    <code class="block font-mono text-2xs text-muted break-words" data-trick-token><%= t.token %></code>
+    <% if t.variants.any? %>
+      <%# The variants by name, so "Sheen · loop" is on the card and not only on the
+          clipboard. %>
+      <ul class="space-y-0.5" data-trick-variants>
+        <% t.variants.each do |v| %>
+          <li class="text-2xs leading-snug"><span class="text-body font-semibold" data-trick-variant-name><%= v.name %></span> <code class="font-mono text-muted break-words"><%= v.token %></code></li>
+        <% end %>
+      </ul>
+    <% end %>
+  </div>
+  <button type="button"
+          class="btn btn-neutral btn-sm shrink-0"
+          aria-label="Copy the name for an agent"
+          data-trick-copy="<%= Studio::Tricks.agent_line(trick, local_assigns[:variant]) %>"
+          @click="navigator.clipboard?.writeText($el.dataset.trickCopy); copied = true; setTimeout(() => copied = false, 1200)">
+    <span x-text="copied ? 'Copied' : 'Copy'">Copy</span>
+  </button>
+</div>