domma-cms 0.25.14 → 0.25.16

package/admin/js/templates/docs/components-reference.html

@@ -0,0 +1,259 @@
+<div class="view-header">
+  <h1><span data-icon="component"></span> Components — Reference</h1>
+  <a href="#/components" class="btn btn-ghost btn-sm"><span data-icon="component"></span> Manage Components</a>
+</div>
+
+<div class="row">
+  <div class="col-12">
+    <div class="docs-body">
+
+      <nav class="alert alert-info" style="display:flex;gap:1rem;flex-wrap:wrap;align-items:center;">
+        <strong>Components docs:</strong>
+        <a href="#/docs/components">Reference</a>
+        <a href="#/docs/components-howto">How-To</a>
+        <a href="#/docs/components-walkthrough">Walkthrough</a>
+        <a href="#/docs/components-rules">Rules</a>
+      </nav>
+
+      <p class="lead">
+        Components are small, reusable custom elements you author in one file and drop into any page.
+        Each one is a single <code>.dmc</code> file with up to four sections — <code>&lt;template&gt;</code>,
+        <code>&lt;props&gt;</code>, <code>&lt;script&gt;</code> and <code>&lt;style&gt;</code> — and the CMS
+        compiles it to a self-contained browser module that registers a
+        <code>&lt;dm-<em>name</em>&gt;</code> custom element. No build step, no framework wiring.
+      </p>
+
+      <p>Manage them under <a href="#/components">Data → Components</a>. This page is the complete
+        reference; for guided learning start with the
+        <a href="#/docs/components-walkthrough">Walkthrough</a> or the
+        <a href="#/docs/components-howto">How-To</a> recipes.</p>
+
+      <hr>
+
+      <h2>The <code>.dmc</code> file format</h2>
+
+      <p>A component is a single file made of named blocks, much like a single-file component in other
+        frameworks. Three blocks are <strong>required</strong> (<code>&lt;template&gt;</code>,
+        <code>&lt;props&gt;</code>, <code>&lt;script&gt;</code>); <code>&lt;style&gt;</code> is optional.
+        Block order does not matter.</p>
+
+      <pre class="code-block"><code>&lt;template&gt;
+&lt;div class="dm-greeting"&gt;Hello, {{name}}!&lt;/div&gt;
+&lt;/template&gt;
+
+&lt;props&gt;
+{
+  "name": { "type": "string", "default": "world", "label": "Name to greet" }
+}
+&lt;/props&gt;
+
+&lt;script&gt;
+export default {};
+&lt;/script&gt;
+
+&lt;style&gt;
+.dm-greeting { font-weight: 600; }
+&lt;/style&gt;</code></pre>
+
+      <p>Saving compiles the source <em>before</em> it is written to disk — a malformed component never
+        reaches the filesystem. The compiler reports precise, per-block errors (see
+        <a href="#/docs/components-rules">Rules</a> for every error code).</p>
+
+      <hr>
+
+      <h2><code>&lt;template&gt;</code> — markup</h2>
+
+      <p>Plain HTML plus a Handlebars-style expression syntax. Data comes from the component's
+        <code>props</code> and reactive <code>data()</code> state. Supported syntax:</p>
+
+      <table class="table table-sm">
+        <thead>
+        <tr><th>Syntax</th><th>Purpose</th></tr>
+        </thead>
+        <tbody>
+        <tr><td><code>{{ value }}</code></td><td>Interpolate a prop or state value (HTML-escaped).</td></tr>
+        <tr><td><code>{{#if cond}}…{{/if}}</code></td><td>Render the block only when <code>cond</code> is truthy.</td></tr>
+        <tr><td><code>{{#unless cond}}…{{/unless}}</code></td><td>Render the block only when <code>cond</code> is falsy.</td></tr>
+        <tr><td><code>{{#each list}}…{{/each}}</code></td><td>Repeat the block for each item. Inside, <code>{{.}}</code> is the item (for primitives), <code>{{@index}}</code>, <code>{{@first}}</code> and <code>{{@last}}</code> are available; object items expose their own keys.</td></tr>
+        <tr><td><code>{{#with obj}}…{{/with}}</code></td><td>Scope the block to an object's keys.</td></tr>
+        <tr><td><code>&lt;slot&gt;&lt;/slot&gt;</code></td><td>Project the light-DOM content placed between the element's tags.</td></tr>
+        </tbody>
+      </table>
+
+      <pre class="code-block"><code>&lt;template&gt;
+&lt;ul class="dm-list"&gt;
+  {{#each items}}
+    &lt;li class="{{#if @first}}first{{/if}}"&gt;{{@index}}. {{.}}&lt;/li&gt;
+  {{/each}}
+&lt;/ul&gt;
+{{#if title}}&lt;h4&gt;{{title}}&lt;/h4&gt;{{/if}}
+&lt;slot&gt;&lt;/slot&gt;
+&lt;/template&gt;</code></pre>
+
+      <hr>
+
+      <h2><code>&lt;props&gt;</code> — typed inputs</h2>
+
+      <p>A JSON <strong>object</strong> (not an array). Each key is a prop name; each value declares a
+        <code>type</code> and may add a <code>default</code> and a <code>label</code> (shown in the editor's
+        preview panel). The type is validated at compile time.</p>
+
+      <p>Valid types: <code>string</code>, <code>number</code>, <code>boolean</code>, <code>array</code>,
+        <code>object</code>.</p>
+
+      <pre class="code-block"><code>{
+  "initial":   { "type": "number",  "default": 0,     "label": "Initial value" },
+  "step":      { "type": "number",  "default": 1,     "label": "Step size" },
+  "showReset": { "type": "boolean", "default": false, "label": "Show reset button" },
+  "tags":      { "type": "array",   "default": [],    "label": "Tag list" }
+}</code></pre>
+
+      <p>Props are passed as HTML attributes where the value is always a string; the runtime coerces it to
+        the declared type (so <code>step="2"</code> arrives as the number <code>2</code>). Read props inside
+        <code>onMount()</code> and methods via <code>this.props</code> — see the script API below.</p>
+
+      <hr>
+
+      <h2><code>&lt;script&gt;</code> — behaviour</h2>
+
+      <p>An ES module with a single <code>export default { … }</code> object describing the component. The
+        export is the only requirement; every key inside it is optional.</p>
+
+      <pre class="code-block"><code>export default {
+  // Reactive state. Called WITHOUT `this` — do not read props here.
+  data() { return { count: 0 }; },
+
+  // Methods are bound to the component context (`this`).
+  methods: {
+    inc() { this.set({ count: this.data.count + this.props.step }); }
+  },
+
+  // Lifecycle — bound to `this`; props and the element are available here.
+  onMount()   { this.set({ count: this.props.initial }); },
+  onUnmount() { /* clean up timers, listeners, etc. */ }
+};</code></pre>
+
+      <table class="table table-sm">
+        <thead>
+        <tr><th>Key</th><th>What it is</th></tr>
+        </thead>
+        <tbody>
+        <tr><td><code>data()</code></td><td>Returns the initial reactive state object. Called with no <code>this</code> binding — <strong>props are not available here</strong>; initialise from props in <code>onMount()</code>.</td></tr>
+        <tr><td><code>methods</code></td><td>Object of functions bound to the component context.</td></tr>
+        <tr><td><code>onMount()</code></td><td>Lifecycle hook fired when the element is attached to the DOM. Props and the element node are available.</td></tr>
+        <tr><td><code>onUnmount()</code></td><td>Lifecycle hook fired when the element is removed — clear intervals/listeners here.</td></tr>
+        </tbody>
+      </table>
+
+      <p><strong>Inside methods and lifecycle hooks</strong>, <code>this</code> exposes:</p>
+
+      <table class="table table-sm">
+        <thead>
+        <tr><th>Member</th><th>Description</th></tr>
+        </thead>
+        <tbody>
+        <tr><td><code>this.props</code></td><td>The (type-coerced) props the element was used with.</td></tr>
+        <tr><td><code>this.data</code></td><td>The current reactive state snapshot.</td></tr>
+        <tr><td><code>this.set({ … })</code></td><td>Patch reactive state; the template re-renders with the new values.</td></tr>
+        <tr><td><code>this.el</code></td><td>The custom-element DOM node. Its rendered markup lives in <code>this.el.shadowRoot</code> — attach event listeners there.</td></tr>
+        </tbody>
+      </table>
+
+      <p>Domma's browser globals (<code>$</code>, <code>H</code>, <code>S</code>, <code>E</code>, <code>D</code>,
+        <code>_</code>, …) are available inside the script just as on any page, so a component can fetch data,
+        read storage, or pop a toast.</p>
+
+      <hr>
+
+      <h2><code>&lt;style&gt;</code> — scoped CSS</h2>
+
+      <p>Optional. CSS here is scoped to the component's shadow DOM, so selectors can't leak out and the
+        page's styles can't leak in. By convention components prefix their root class with
+        <code>dm-<em>name</em></code> for clarity, but scoping is automatic either way.</p>
+
+      <pre class="code-block"><code>&lt;style&gt;
+.dm-counter { text-align: center; padding: 1rem; }
+.dm-counter .value { font-size: 2.5rem; font-weight: 700; }
+&lt;/style&gt;</code></pre>
+
+      <hr>
+
+      <h2>Using a component on a page</h2>
+
+      <p>Two equivalent ways, both server-rendered into the page so the right component module is auto-injected:</p>
+
+      <h3>Shortcode (Markdown)</h3>
+      <pre class="code-block"><code>[component name="counter" initial="10" step="2" showReset="true" /]</code></pre>
+
+      <h3>Custom element (HTML)</h3>
+      <pre class="code-block"><code>&lt;dm-counter initial="10" step="2" show-reset="true"&gt;&lt;/dm-counter&gt;</code></pre>
+
+      <p>Both pass <code>{initial, step, showReset}</code> to the component. Note the attribute casing:
+        camelCase props map to <code>kebab-case</code> attributes on the raw tag
+        (<code>showReset</code> → <code>show-reset</code>); the shortcode accepts the prop name as written.
+        When the page is rendered the server collects every <code>dm-*</code> tag used and injects one
+        <code>&lt;script type="module" src="/api/components/<em>name</em>.js"&gt;</code> at the end of the
+        body, which registers the element via <code>Domma.component()</code>.</p>
+
+      <p>To project content into a component's <code>&lt;slot&gt;</code>, use the custom-element form with
+        children:</p>
+      <pre class="code-block"><code>&lt;dm-reveal-panel heading="Click to reveal"&gt;
+  &lt;p&gt;Hidden content appears here when toggled.&lt;/p&gt;
+&lt;/dm-reveal-panel&gt;</code></pre>
+
+      <hr>
+
+      <h2>Storage, REST API &amp; bundles</h2>
+
+      <p>Source files live in <code>content/components/<em>name</em>.dmc</code>, with an optional sidecar
+        <code>content/components/<em>name</em>.meta.json</code> holding the <code>bundled</code> flag and
+        <code>project</code> tag. The REST surface (all under <code>/api/components</code>):</p>
+
+      <table class="table table-sm">
+        <thead>
+        <tr><th>Method &amp; path</th><th>Auth</th><th>Purpose</th></tr>
+        </thead>
+        <tbody>
+        <tr><td><code>GET /api/components</code></td><td>read</td><td>List components with metadata + parsed props.</td></tr>
+        <tr><td><code>GET /api/components/:name</code></td><td>read</td><td>Raw <code>.dmc</code> source + parsed props.</td></tr>
+        <tr><td><code>GET /api/components/:name.js</code></td><td>public</td><td>Compiled browser module (what pages load).</td></tr>
+        <tr><td><code>POST /api/components/compile</code></td><td>update</td><td>Transient compile for the live preview (nothing written).</td></tr>
+        <tr><td><code>PUT /api/components/:name</code></td><td>update</td><td>Create or update (compiles first; errors returned, file untouched on failure).</td></tr>
+        <tr><td><code>DELETE /api/components/:name</code></td><td>delete</td><td>Delete source + sidecar.</td></tr>
+        <tr><td><code>GET /api/components/:name/export</code></td><td>read</td><td>Download a <code>.dmcomponent.json</code> bundle.</td></tr>
+        <tr><td><code>POST /api/components/import</code></td><td>update</td><td>Import a bundle (<code>?overwrite=true</code> to replace).</td></tr>
+        </tbody>
+      </table>
+
+      <p>A bundle is a small JSON envelope you can move between sites (Export / Import buttons on the
+        <a href="#/components">Components</a> page):</p>
+      <pre class="code-block"><code>{ "format": 1, "name": "counter", "source": "&lt;template&gt;…", "bundled": false }</code></pre>
+
+      <h3>Bundled &amp; plugin components</h3>
+      <p>The <code>bundled</code> flag marks a component as part of fresh-install seed data. Plugins may
+        also contribute components via the <code>registerComponent()</code> hook — these appear in the list
+        with a <span class="badge badge-secondary">plugin</span> badge, are served from memory, and are
+        <strong>read-only</strong> from the admin (you can't edit or delete them, and you can't save a
+        component whose name a plugin already owns).</p>
+
+      <hr>
+
+      <h2>The five seeded starter components</h2>
+      <p>Fresh installs ship with these (never overwritten if you've edited them) — open any in
+        <a href="#/components">Components</a> to read the full source:</p>
+      <ul>
+        <li><code>counter</code> — state, methods and lifecycle in one small example</li>
+        <li><code>copy-button</code> — an async method using the clipboard API</li>
+        <li><code>reveal-panel</code> — conditional rendering plus a <code>&lt;slot&gt;</code></li>
+        <li><code>testimonial-card</code> — presentational only (empty <code>export default {}</code>)</li>
+        <li><code>countdown-timer</code> — an interval started in <code>onMount</code> and cleared in <code>onUnmount</code></li>
+      </ul>
+
+      <hr>
+      <p class="text-muted" style="font-size:.9rem;">
+        Next: <a href="#/docs/components-howto">How-To recipes →</a>
+      </p>
+
+    </div>
+  </div>
+</div>

package/admin/js/templates/docs/components-rules.html

@@ -0,0 +1,167 @@
+<div class="view-header">
+  <h1><span data-icon="component"></span> Components — Rules</h1>
+  <a href="#/docs/components" class="btn btn-ghost btn-sm"><span data-icon="arrow-left"></span> Reference</a>
+</div>
+
+<div class="row">
+  <div class="col-12">
+    <div class="docs-body">
+
+      <nav class="alert alert-info" style="display:flex;gap:1rem;flex-wrap:wrap;align-items:center;">
+        <strong>Components docs:</strong>
+        <a href="#/docs/components">Reference</a>
+        <a href="#/docs/components-howto">How-To</a>
+        <a href="#/docs/components-walkthrough">Walkthrough</a>
+        <a href="#/docs/components-rules">Rules</a>
+      </nav>
+
+      <p class="lead">The constraints the compiler enforces, and the handful of behaviours that commonly
+        trip people up. Everything here is validated at save time — a component that breaks a rule never
+        reaches disk.</p>
+
+      <hr>
+
+      <h2>Naming</h2>
+      <ul>
+        <li>Names must match <code>^[a-z][a-z0-9-]*$</code> — start with a lowercase letter, then lowercase
+          letters, digits and hyphens.</li>
+        <li>Valid: <code>counter</code>, <code>copy-button</code>, <code>price-tag-2</code>. Invalid:
+          <code>Counter</code>, <code>1counter</code>, <code>my_component</code>, <code>../etc/passwd</code>.</li>
+        <li>The name becomes the element tag <code>&lt;dm-<em>name</em>&gt;</code> and is <strong>permanent</strong> —
+          it can't be changed after creation. To rename, create a new component and delete the old one.</li>
+      </ul>
+
+      <hr>
+
+      <h2>Required blocks</h2>
+      <ul>
+        <li><code>&lt;template&gt;</code>, <code>&lt;props&gt;</code> and <code>&lt;script&gt;</code> are
+          required. A missing one fails with <code>MISSING_BLOCK</code>.</li>
+        <li><code>&lt;style&gt;</code> is optional and defaults to empty.</li>
+        <li>Blocks are matched by their tags and may appear in any order.</li>
+      </ul>
+
+      <hr>
+
+      <h2>Props must be a typed JSON object</h2>
+      <ul>
+        <li>The <code>&lt;props&gt;</code> body must be valid JSON and an <strong>object</strong> (not an
+          array, not a bare value) — otherwise <code>INVALID_PROPS_JSON</code>.</li>
+        <li>Every prop must declare a <code>type</code> that is one of <code>string</code>,
+          <code>number</code>, <code>boolean</code>, <code>array</code>, <code>object</code>. Anything else
+          (or a missing type) fails validation.</li>
+        <li><code>default</code> and <code>label</code> are optional. <code>label</code> only affects the
+          editor's preview panel.</li>
+      </ul>
+
+      <hr>
+
+      <h2>The script must <code>export default</code> an object</h2>
+      <ul>
+        <li>The <code>&lt;script&gt;</code> body must be exactly one <code>export default { … };</code>
+          statement — the compiler strips that prefix and embeds the object. No <code>export default</code>
+          means <code>SCRIPT_MISSING_EXPORT</code>.</li>
+        <li>Use an object expression — not a class, not multiple exports. An empty
+          <code>export default {};</code> is valid for a purely presentational component.</li>
+      </ul>
+
+      <hr>
+
+      <h2>Gotchas worth memorising</h2>
+
+      <div class="alert alert-warning">
+        <strong>1. <code>data()</code> can't see props.</strong> It's called with no <code>this</code>
+        binding, so <code>this.props</code> is unavailable there. Initialise prop-derived state inside
+        <code>onMount()</code> (which <em>is</em> bound) using <code>this.set(...)</code>.
+      </div>
+
+      <div class="alert alert-warning">
+        <strong>2. Boolean coercion is string-based.</strong> Attribute values are strings. A boolean prop
+        is true only for the string <code>"true"</code>; <code>showReset="false"</code> is still a non-empty
+        string and coerces to <code>true</code>. To switch a boolean off, set it to <code>"true"</code> or
+        omit the attribute entirely.
+      </div>
+
+      <div class="alert alert-warning">
+        <strong>3. Attribute casing.</strong> On the raw custom element, camelCase props are written as
+        <code>kebab-case</code> attributes — <code>showReset</code> becomes <code>show-reset</code>. The
+        <code>[component]</code> shortcode accepts the prop name as written.
+      </div>
+
+      <div class="alert alert-warning">
+        <strong>4. Array / object props are JSON in the attribute.</strong> Pass them as a JSON string —
+        e.g. <code>items='["a","b"]'</code> — and the runtime parses them to the declared type.
+      </div>
+
+      <div class="alert alert-warning">
+        <strong>5. Listen on the shadow root.</strong> A component's rendered markup lives in
+        <code>this.el.shadowRoot</code>. Attach delegated listeners there (one listener, switch on
+        <code>data-action</code>) rather than to <code>document</code>.
+      </div>
+
+      <div class="alert alert-warning">
+        <strong>6. Clean up in <code>onUnmount()</code>.</strong> Anything you start in <code>onMount</code>
+        — intervals, timeouts, external listeners — must be torn down in <code>onUnmount</code> so it
+        doesn't leak when the element is removed.
+      </div>
+
+      <hr>
+
+      <h2>Plugin-owned components are read-only</h2>
+      <ul>
+        <li>Components contributed by a plugin show a <span class="badge badge-secondary">plugin</span>
+          badge, are served from memory, and <strong>cannot be edited or deleted</strong> from the admin
+          (attempting it returns <code>PLUGIN_OWNED</code>).</li>
+        <li>You also can't save a disk component whose name a plugin already owns — pick a different name.</li>
+      </ul>
+
+      <hr>
+
+      <h2>Import / export constraints</h2>
+      <ul>
+        <li>A bundle must have a numeric <code>format</code> no newer than the CMS supports, plus
+          <code>name</code> and <code>source</code> strings — otherwise <code>INVALID_BUNDLE</code>.</li>
+        <li>Importing over an existing name returns <code>CONFLICT</code> unless you confirm the overwrite
+          (the Import button prompts you).</li>
+        <li>Imported source is compiled like any save, so a broken bundle is rejected with the same errors.</li>
+      </ul>
+
+      <hr>
+
+      <h2>Rendering &amp; safety notes</h2>
+      <ul>
+        <li><code>{{ }}</code> interpolation is HTML-escaped, so prop values can't inject markup.</li>
+        <li>The markdown sanitiser keeps a live allowlist of <code>dm-*</code> tags, refreshed whenever you
+          save or delete a component — a component you just created is immediately usable in page content.
+          <code>on*</code> handler attributes and <code>javascript:</code> URLs are still stripped globally.</li>
+        <li>Saving recompiles and invalidates the cached module, so edits take effect on the next page load
+          without a server restart.</li>
+      </ul>
+
+      <hr>
+
+      <h2>Compiler error codes at a glance</h2>
+      <table class="table table-sm">
+        <thead>
+        <tr><th>Code</th><th>Meaning</th></tr>
+        </thead>
+        <tbody>
+        <tr><td><code>INVALID_NAME</code></td><td>Name doesn't match the naming rule.</td></tr>
+        <tr><td><code>MISSING_BLOCK</code></td><td>A required <code>&lt;template&gt;</code> / <code>&lt;props&gt;</code> / <code>&lt;script&gt;</code> block is absent.</td></tr>
+        <tr><td><code>INVALID_PROPS_JSON</code></td><td>Props aren't a JSON object, or a prop has an invalid/missing type.</td></tr>
+        <tr><td><code>SCRIPT_MISSING_EXPORT</code></td><td>The script has no <code>export default</code> object.</td></tr>
+        <tr><td><code>PLUGIN_OWNED</code></td><td>Tried to edit/delete (or shadow) a plugin-contributed component.</td></tr>
+        <tr><td><code>INVALID_BUNDLE</code> / <code>CONFLICT</code></td><td>Import bundle malformed, or a name collision needs overwrite confirmation.</td></tr>
+        </tbody>
+      </table>
+
+      <hr>
+      <p class="text-muted" style="font-size:.9rem;">
+        Back to <a href="#/docs/components">Reference</a> &nbsp;·&nbsp;
+        <a href="#/docs/components-howto">How-To</a> &nbsp;·&nbsp;
+        <a href="#/docs/components-walkthrough">Walkthrough</a>
+      </p>
+
+    </div>
+  </div>
+</div>

package/admin/js/templates/docs/components-walkthrough.html

@@ -0,0 +1,167 @@
+<div class="view-header">
+  <h1><span data-icon="component"></span> Components — Walkthrough</h1>
+  <a href="#/components/new" class="btn btn-primary btn-sm"><span data-icon="plus"></span> New Component</a>
+</div>
+
+<div class="row">
+  <div class="col-12">
+    <div class="docs-body">
+
+      <nav class="alert alert-info" style="display:flex;gap:1rem;flex-wrap:wrap;align-items:center;">
+        <strong>Components docs:</strong>
+        <a href="#/docs/components">Reference</a>
+        <a href="#/docs/components-howto">How-To</a>
+        <a href="#/docs/components-walkthrough">Walkthrough</a>
+        <a href="#/docs/components-rules">Rules</a>
+      </nav>
+
+      <p class="lead">
+        We'll build one component end-to-end: a <strong>star rating</strong> widget you can drop onto any
+        page with <code>[component name="star-rating" max="5" value="3" /]</code>. By the end you'll have
+        used every section of a <code>.dmc</code> file, reactive state, an event listener, a custom event,
+        and the live preview. Follow along in a real <strong>New Component</strong> editor.
+      </p>
+
+      <hr>
+
+      <h2>Step 1 — Create the component</h2>
+      <p>Open <a href="#/components">Data → Components</a> → <strong>New Component</strong> and name it
+        <code>star-rating</code>. Remember: lowercase + hyphens, and the name is permanent because it
+        becomes the element tag <code>&lt;dm-star-rating&gt;</code>. The four source tabs
+        (<code>&lt;template&gt;</code>, <code>&lt;props&gt;</code>, <code>&lt;script&gt;</code>,
+        <code>&lt;style&gt;</code>) are on the left; a live preview is on the right.</p>
+
+      <hr>
+
+      <h2>Step 2 — Declare the props</h2>
+      <p>Start with the inputs, because they shape everything else. A rating needs a maximum number of
+        stars and a current value. Put this in the <code>&lt;props&gt;</code> tab:</p>
+      <pre class="code-block"><code>{
+  "max":      { "type": "number",  "default": 5,    "label": "Number of stars" },
+  "value":    { "type": "number",  "default": 0,    "label": "Current rating" },
+  "readonly": { "type": "boolean", "default": false, "label": "Read-only (display only)" }
+}</code></pre>
+      <p>These appear in the preview's <em>Preview props</em> panel, so you can poke values as you build.</p>
+
+      <hr>
+
+      <h2>Step 3 — Write the template</h2>
+      <p>We render <code>max</code> stars and mark each as filled if its index is below the current rating.
+        Because <code>{{#each}}</code> needs a list, we'll build a <code>stars</code> array in state
+        (next step) where each item knows whether it's <code>on</code>. For now, the markup:</p>
+      <pre class="code-block"><code>&lt;template&gt;
+&lt;div class="dm-stars" role="img" aria-label="{{value}} of {{max}}"&gt;
+  {{#each stars}}
+    &lt;button class="star {{#if on}}on{{/if}}" data-action="rate" data-index="{{n}}"&gt;★&lt;/button&gt;
+  {{/each}}
+&lt;/div&gt;
+&lt;/template&gt;</code></pre>
+      <p>Each star is a button carrying its 1-based position in <code>data-index</code>, so a single click
+        handler can read which star was pressed.</p>
+
+      <hr>
+
+      <h2>Step 4 — Add the script (state + behaviour)</h2>
+      <p>Three jobs: build the <code>stars</code> array from <code>value</code>, rebuild it whenever the
+        rating changes, and handle clicks. Remember <code>data()</code> can't see props, so we seed state
+        in <code>onMount()</code>.</p>
+      <pre class="code-block"><code>&lt;script&gt;
+export default {
+  data() { return { stars: [], value: 0 }; },
+
+  methods: {
+    // Build the star list for a given rating.
+    render(value) {
+      const max = this.props.max;
+      const stars = [];
+      for (let n = 1; n &lt;= max; n++) stars.push({ n, on: n &lt;= value });
+      this.set({ stars, value });
+    },
+    rate(n) {
+      if (this.props.readonly) return;
+      this.render(n);
+      // Tell the outside world the rating changed.
+      this.el.dispatchEvent(new CustomEvent('rating-change', {
+        detail: { value: n }, bubbles: true
+      }));
+    }
+  },
+
+  onMount() {
+    this.render(this.props.value);
+    this.el.shadowRoot.addEventListener('click', (e) =&gt; {
+      const btn = e.target.closest('[data-action="rate"]');
+      if (btn) this.rate(Number(btn.dataset.index));
+    });
+  }
+};
+&lt;/script&gt;</code></pre>
+      <p>Note the patterns from the <a href="#/docs/components">Reference</a>: one delegated listener on
+        <code>shadowRoot</code>, <code>this.set()</code> to re-render, <code>this.props</code> for inputs,
+        and a bubbling <code>CustomEvent</code> so a page can react to the chosen rating.</p>
+
+      <hr>
+
+      <h2>Step 5 — Style it (scoped)</h2>
+      <pre class="code-block"><code>&lt;style&gt;
+.dm-stars { display: inline-flex; gap: .15rem; }
+.dm-stars .star {
+  background: none; border: 0; cursor: pointer;
+  font-size: 1.5rem; line-height: 1; color: #d0d0d0; padding: 0;
+}
+.dm-stars .star.on { color: #f5b301; }
+&lt;/style&gt;</code></pre>
+      <p>These selectors are scoped to the component, so <code>.star</code> won't collide with anything else
+        on the page.</p>
+
+      <hr>
+
+      <h2>Step 6 — Watch the preview, then save</h2>
+      <p>As you typed, the editor recompiled and re-mounted the component in the preview iframe. Toggle
+        <code>readonly</code> and change <code>value</code> in the <em>Preview props</em> panel to sanity-check
+        both modes. When it looks right, hit <strong>Save Component</strong> — the source compiles before it
+        is written, so a typo surfaces as a clear error rather than a broken page.</p>
+
+      <hr>
+
+      <h2>Step 7 — Use it on a page</h2>
+      <p>Display-only, in any Markdown page:</p>
+      <pre class="code-block"><code>[component name="star-rating" max="5" value="4" readonly="true" /]</code></pre>
+      <p>Interactive, reacting to the custom event with a little page script:</p>
+      <pre class="code-block"><code>&lt;dm-star-rating max="5" value="0" id="r1"&gt;&lt;/dm-star-rating&gt;
+&lt;script&gt;
+document.getElementById('r1').addEventListener('rating-change', (e) =&gt; {
+  console.log('User picked', e.detail.value);
+});
+&lt;/script&gt;</code></pre>
+
+      <hr>
+
+      <h2>Step 8 — Share it</h2>
+      <p>Back on <a href="#/components">Components</a>, the <span data-icon="download"></span> Export button
+        gives you <code>star-rating.dmcomponent.json</code> — import that on another Domma site to reuse the
+        widget verbatim.</p>
+
+      <hr>
+
+      <h2>What you used</h2>
+      <ul>
+        <li><strong>Props</strong> with types + defaults, coerced from attributes</li>
+        <li><strong>Template</strong> interpolation, <code>{{#each}}</code> and <code>{{#if}}</code></li>
+        <li><strong>State</strong> via <code>data()</code> + <code>this.set()</code>, seeded from props in <code>onMount()</code></li>
+        <li>A single delegated <strong>shadow-root listener</strong> and <code>data-*</code> dispatch</li>
+        <li>A bubbling <strong>CustomEvent</strong> for page-level integration</li>
+        <li><strong>Scoped CSS</strong>, the live preview, and export/import</li>
+      </ul>
+
+      <p>For the rules that keep components well-behaved — naming, the <code>data()</code>-can't-see-props
+        gotcha, boolean coercion, plugin-owned names — read <a href="#/docs/components-rules">Rules</a>.</p>
+
+      <hr>
+      <p class="text-muted" style="font-size:.9rem;">
+        Next: <a href="#/docs/components-rules">Rules &amp; gotchas →</a>
+      </p>
+
+    </div>
+  </div>
+</div>