studio-engine 0.70.0 → 0.71.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f1c217135776ee0fcd67dd4ed2e9a72f1aedf5260ac23cfc23615ab83754133a
-  data.tar.gz: 42878ae8f85ed0c911b99c940e3c5094ca7329fed4bbb727ebfa4466bba99dfb
+  metadata.gz: b84ed97df94f71d6135899621e982649f6c80b41d5821b12842ab5c0e6d47ce7
+  data.tar.gz: 2b1af46db99092b30d9049d2afbbefa9cc810878bcbc376d9e04f780cc6e7a05
 SHA512:
-  metadata.gz: d72745a5c54559b745fc0fefe1ac1c45b3921efeccbe5769f3b1da5ceaa1e11463c317984847fc1300fb0387610c33c4f0c7504e279871630f5535db563c935e
-  data.tar.gz: 16be22a876c99c848169a2dcd551593ff4b8c377427acd9d84c04bf732847d261422c79d9b7f30397bf8b04c2d13a894999cc542a95bb1037f9deeaea0c5c32a
+  metadata.gz: 294aa380598143d9f79592e2b0e62bab038dbb886b374ce765ff9fdf0da349e460049ae284e397f234647f3b9dfdea24263cd8ed31bf74bbe00d1e14e1bbf49f
+  data.tar.gz: d119392c02adb20753485b0b6efcaf01e3c3f3ea0aa26f9b5e36fe1f3de3fb4df77ede836f0a79ec937bd556ad14a9317078fa25f028d890e27f531e74ad8f37

data/CHANGELOG.md

@@ -6,6 +6,39 @@ The format is [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). This pro
 
 ### Added
 
+- **The living style guide grows a HOST SECTION seam.** `/admin/style` rendered
+  four hard-coded engine sections (Theme, Modals, Tricks, Tasks) with no way for
+  a consuming app to contribute one of its own. An app now defines
+  **`app/views/style/host/_modals.html.erb`** and the guide grows a fifth
+  section for that app's own modals, between Modals and Tricks, plus its pill in
+  the sticky section nav. Found by the same three-term
+  `lookup_context.exists?("modals", ["style/host"], true)` the modal host uses
+  for `modals/_host_extras` — one convention in this codebase, not two — so
+  defining the file IS the registration: no initializer, no locals, no list to
+  append to.
+
+  **The gem keeps dictating the structure.** `style/_host.html.erb` renders the
+  section element, the `#host-modals` anchor, the heading (`Studio.app_name`),
+  the intro line and the Alpine scope; the app supplies specimens only. An app
+  that ships no such partial gets **nothing** — no pill, no heading, no
+  container — and that is asserted as a whole-document comparison rather than a
+  handful of refutes: the page an app WITH a section gets, minus that section
+  and its pill, must equal the page a base app gets. Five of the six apps
+  mounting this engine will ship no host section, and their page is unchanged.
+
+  **A host specimen drives `$store.modals`, not `dsModals`, and the distinction
+  is the whole point.** The guide's own Modals section needs a page-scoped store
+  because its specimens are the ENGINE's ids, which an app's layout host has no
+  registration for — pushing one there paints an empty card behind the specimen.
+  An app's own ids ARE registered in its layout host, so a host section opens
+  the **real** production card with no mirror, no second registration list and
+  no iframe. The doc comment on `style/_host.html.erb` is the consumer contract
+  and says so outright, because a reader who assumes `dsModals` builds that
+  mirror instead — a second copy of every card, free to drift from the one the
+  app ships, which is the opposite of what a living style guide is for.
+
+  **The seam ships no host section itself.** The first consumer is
+  turf-monster's own `style/host/_modals`, which lands as its own task.
 - **A `required` mode on the shared first-name card.**
   `studio/modals/onboarding/_first_name` grows one local. `required: true`
   renders the card with BOTH skip affordances gone — the "Skip for now" button

data/README.md

@@ -449,6 +449,48 @@ than assuming drop-in equivalence:
   the replacement lands after the 220ms slide-out (previously an immediate
   top-of-stack assignment).
 
+### Style guide — your app's own section
+
+`/admin/style` is the engine's living style guide, and every section on it is
+the engine's: Theme, Modals, Tricks, Tasks. An app grows a **fifth section, its
+own**, by defining one partial:
+
+```erb
+<%# app/views/style/host/_modals.html.erb %>
+<div class="card p-4 space-y-3">
+  <p class="label-upper">Wallet setup</p>
+  <button type="button" class="btn btn-primary btn-sm"
+          @click="$store.modals.open('wallet-setup', { returnUrl: window.location.href })">
+    Open
+  </button>
+</div>
+```
+
+That is the whole registration — the same optional-partial convention as
+`modals/_host_extras`, resolved by the same three-term `lookup_context.exists?`.
+An app that ships no such file gets no section, no heading, and no nav pill; its
+page is byte-for-byte what it was.
+
+**The gem keeps dictating the structure.** It renders the section element, the
+`#host-modals` anchor, the heading (your `Studio.app_name`), the intro line, and
+the sticky nav pill, and it places the section between Modals and Tricks. Your
+partial supplies specimens only — no `<section>`, no `<h2>`, nothing to register
+in a nav.
+
+**Drive `$store.modals`, not `dsModals`.** The guide's own Modals section stands
+up a page-scoped store because its specimens are the *engine's* ids, and pushing
+an id your layout host has never registered opens that host onto an empty card.
+Your own ids are already registered there, so
+`$store.modals.open(id, props)` renders the **real** card, in production chrome,
+with production behavior. There is nothing to mirror and no second registration
+list to keep in sync — building one is the mistake this note exists to prevent.
+This assumes your layout mounts the shared host. Not every consuming app does
+(see "Page-scoped hosts" above); where none is mounted `$store.modals` is
+undefined, so mount `studio/modals/host` before writing a trigger.
+
+Full contract, including what the partial may assume: the doc comment at the top
+of `app/views/style/_host.html.erb`.
+
 ### User nav slots
 
 `components/_user_nav.html.erb` renders the right-side navbar user section.

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

@@ -0,0 +1,111 @@
+<%#  The HOST section of the living style guide (admin/style).
+
+     THE ONE SEAM a consuming app has for growing its own specimens onto this
+     page. Every other section on this page is the gem's. This one is the app's,
+     and the gem still dictates its structure: the section element, the anchor,
+     the heading, the intro line, and the nav pill above are all rendered HERE,
+     from the engine. The app supplies content only.
+
+     "Host" means the CONSUMING APP, the same sense it carries in the modal
+     host's own seam (modals/_host_extras). It does NOT mean the modal-host
+     shell, which is studio/modals/_host - a different file and a different
+     meaning of the word.
+
+
+     THE CONTRACT - what a consuming app writes
+     ------------------------------------------
+     Define ONE partial in the app:
+
+         app/views/style/host/_modals.html.erb
+
+     That is the whole registration. There is no initializer, no locals, no
+     list to append to, and nothing to render from the app's own layout. The
+     guide finds the partial by CONVENTION, exactly the way the modal host
+     finds modals/_host_extras:
+
+         lookup_context.exists?("modals", ["style/host"], true)
+
+     - the same three-term form: name, prefixes, partial. That call lives in
+     style/index.html.erb, which owns it because the sticky section nav needs
+     the same answer the render does. An app that ships no such partial gets no
+     pill, no heading, no container, and no bytes: the guide is unchanged.
+
+     WHY THIS PATH. A directory (style/host/) rather than a flat name in the
+     gem's own style/ prefix, because the gem already ships style/_modals,
+     style/_theme, style/_tricks and style/_tasks - an app file dropped beside
+     them shadows a section by name, and the failure is silent. Nothing of the
+     gem's lives under style/host/, so an app cannot collide with the engine
+     there. Naming the partial for the SECTION it contributes (modals) rather
+     than for the seam leaves room for a later style/host/_tricks without
+     renaming what is already shipped.
+
+
+     WHAT THE PARTIAL MAY ASSUME
+     ---------------------------
+     - It renders INSIDE this section element, already anchored, spaced and
+       headed. So it supplies cards and prose only: no section tag of its own,
+       no h2, no scroll-margin, no nav entry.
+     - The engine component layer (engine.css) and motion layer
+       (engine-motion.css) are loaded, so card, btn, badge, label-upper, the
+       role tokens and the motion/effect primitives all style for real.
+     - Alpine is running and this section carries an x-data scope, so a
+       specimen can use x-on / at-click bindings directly. A plain onclick
+       calling Alpine.store works too.
+     - NOT that a shared modal host exists. Only an app whose layout renders
+       studio/modals/host has Alpine.store("modals") at all: mcritchie-studio
+       and turf-monster mount it; acquisition-studio, mcritchie-industries and
+       moms-app render none (the same split README's "Page-scoped hosts" and
+       studio/emails/index.html.erb already name). On an app with no shared
+       host $store.modals is UNDEFINED and a trigger throws on click, so mount
+       studio/modals/host in the layout first - or give the page its own host
+       with studio/modals/scoped_host and drive that instead.
+
+
+     WHICH STORE IT DRIVES - read this before writing a trigger
+     ----------------------------------------------------------
+     Drive the app's REAL store:
+
+         $store.modals.open(id, props)
+
+     NOT dsModals. dsModals is the page-scoped host that the gem's own Modals
+     section above stands up, and copying it here is the one wrong turn this
+     seam invites.
+
+     The gem's section needs dsModals for a reason that does NOT apply to an
+     app's own modals. Its specimens are the ENGINE's ids, and an app's layout
+     host registers only that app's ids under an unconditional template x-if on
+     the current modal. Pushing a NOVEL id onto the app's store would open that
+     host onto a card it has no registration for, painting an EMPTY panel behind
+     the specimen. So the gem's section owns a private store and registers all
+     of its specimen content itself.
+
+     An app's own modal ids are already registered in that app's layout host.
+     Push one onto $store.modals and the real host renders the real card - the
+     production card, in production chrome, with production behaviour. There is
+     nothing to mirror, no second registration list to keep in sync, and no
+     iframe. Turf Monster's /admin/modals gallery has driven the real store from
+     a plain button this way since it was built; this seam is that same move,
+     given a home on the guide.
+
+     A reader who assumes dsModals will build a mirror instead: a second copy of
+     every card, free to drift from the one the app actually ships, which is the
+     opposite of what a living style guide is for. %>
+<section id="host-modals" class="space-y-8" x-data="{}"
+         style="scroll-margin-top: calc(var(--nav-h, 0px) + 5rem)">
+  <div class="space-y-1">
+    <h2 class="text-2xl font-bold text-heading"><%= Studio.app_name %></h2>
+    <p class="text-muted text-sm max-w-2xl">
+      This app&rsquo;s own modals, contributed by
+      <code class="font-mono text-2xs bg-inset px-1.5 py-0.5 rounded">app/views/style/host/_modals.html.erb</code>.
+      Every section above belongs to the engine and is inherited; everything
+      here belongs to <%= Studio.app_name %> and ships with it. These specimens
+      drive the app&rsquo;s <strong>real</strong>
+      <code class="font-mono text-2xs bg-inset px-1.5 py-0.5 rounded">$store.modals</code>
+      host, so the card that opens here is the card that opens in production.
+    </p>
+  </div>
+
+  <%# The app's content. Reached only when it resolves - style/index.html.erb
+      owns that guard, because the section nav needs the same answer. %>
+  <%= render "style/host/modals" %>
+</section>

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

@@ -3,22 +3,48 @@
      application.html.erb, inheriting that app's navbar and theme, so every
      specimen restyles per app and in dark or light automatically.
 
-     Four sections, reached by the sticky section nav below and rendered as
-     sibling partials: Theme is the landing section (the color foundation - it
+     Four ENGINE sections, reached by the sticky section nav below and rendered
+     as sibling partials: Theme is the landing section (the color foundation - it
      owns the role tokens/swatches, the folded-in /admin/theme editor, and the
      live preview), then Modals (the shared host + engine card blocks), Tricks
      (the button/surface/motion/effect/leveling primitives, framed as a board of
      copy-paste-for-an-agent snippets), and Tasks (the shared board primitive).
 
+     A FIFTH section is the host app's own, and appears only on an app that asks
+     for it: define app/views/style/host/_modals.html.erb in the consuming app
+     and the guide grows a section (and a nav pill) for that app's own modals,
+     between Modals and Tricks. The gem still renders the section chrome; the app
+     supplies the specimens. Full contract, including which modal store a host
+     specimen drives and why it is not the one the Modals section uses:
+     app/views/style/_host.html.erb.
+
      Specimens use ONLY the engine's own classes (engine.css component layer plus
      engine-motion.css motion/effect/leveling layer), so a consumer that bundles
      engine.css and imports engine-motion.css styles them for real. The primitive
      CSS is NOT inlined here - the consumer's Tailwind build provides it. Page
      chrome uses the engine's own .card / .label-upper / theme tokens. %>
 <%
+  # THE HOST SECTION SEAM. A consuming app grows its OWN modal specimens onto
+  # this page by defining app/views/style/host/_modals.html.erb. Found by the
+  # same three-term lookup_context.exists?(name, prefixes, partial) the modal
+  # host uses for modals/_host_extras (studio/modals/_host.html.erb) - one
+  # convention in this codebase, not two.
+  #
+  # Resolved ONCE, here, because two places need the same answer: the sticky
+  # section nav below and the render further down. An app that ships no such
+  # partial gets no pill, no heading and no container - the page is what it was.
+  # The section chrome and the consumer contract live in style/_host.html.erb.
+  host_modals = lookup_context.exists?("modals", ["style/host"], true)
+
   sections = [
     ["theme",  "Theme"],
-    ["modals", "Modals"],
+    ["modals", "Modals"]
+  ]
+  # Adjacent to Modals, not appended: this page groups by SUBJECT, and a host's
+  # own modals are the same subject as the engine's. Labelled with the app's own
+  # name, so the pill says whose section it is.
+  sections << ["host-modals", Studio.app_name] if host_modals
+  sections += [
     ["tricks", "Tricks"],
     ["tasks",  "Tasks"]
   ]
@@ -54,6 +80,9 @@
   <div class="space-y-16 pt-10">
     <%= render "style/theme" %>
     <%= render "style/modals" %>
+    <% if host_modals %>
+      <%= render "style/host" %>
+    <% end %>
     <%= render "style/tricks" %>
     <%= render "style/tasks" %>
   </div>

data/lib/studio/version.rb

@@ -1,3 +1,3 @@
 module Studio
-  VERSION = "0.70.0"
+  VERSION = "0.71.0"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: studio-engine
 version: !ruby/object:Gem::Version
-  version: 0.70.0
+  version: 0.71.0
 platform: ruby
 authors:
 - Alex McRitchie
@@ -509,6 +509,7 @@ files:
 - app/views/studio/profiles/_save_controls.html.erb
 - app/views/studio/profiles/edit.html.erb
 - app/views/studio/profiles/show.html.erb
+- app/views/style/_host.html.erb
 - app/views/style/_modal_specimen.html.erb
 - app/views/style/_modals.html.erb
 - app/views/style/_specimen.html.erb