domma-cms 0.25.15 → 0.30.0

package/admin/js/templates/docs/api-users.html

@@ -0,0 +1,189 @@
+<div class="view-header">
+  <h1><span data-icon="code"></span> API · Users</h1>
+  <a href="#/api-reference" class="btn btn-ghost btn-sm"><span data-icon="arrow-left"></span> API overview</a>
+</div>
+<style>
+    .method-badge {
+        display: inline-block;
+        font-size: 11px;
+        font-weight: 700;
+        letter-spacing: 0.5px;
+        padding: 2px 7px;
+        border-radius: 4px;
+        font-family: var(--dm-font-mono, monospace);
+        margin-right: 6px;
+        vertical-align: middle;
+    }
+
+    .method-get {
+        background: #d1fae5;
+        color: #065f46;
+    }
+
+    .method-post {
+        background: #dbeafe;
+        color: #1e40af;
+    }
+
+    .method-put {
+        background: #fef3c7;
+        color: #92400e;
+    }
+
+    .method-patch {
+        background: #ccfbf1;
+        color: #134e4a;
+    }
+
+    .method-delete {
+        background: #fee2e2;
+        color: #991b1b;
+    }
+
+    .endpoint-path {
+        font-family: var(--dm-font-mono, monospace);
+        font-size: 14px;
+    }
+
+    .auth-note {
+        font-size: 12px;
+        color: var(--dm-color-text-muted, #6b7280);
+        margin: 4px 0 12px;
+    }
+
+    .auth-note code {
+        font-size: 11px;
+    }
+
+    .docs-body h3 {
+        margin-top: 24px;
+        margin-bottom: 8px;
+    }
+
+    .docs-body h3:first-child {
+        margin-top: 0;
+    }
+</style>
+
+<div class="row">
+  <div class="col-12">
+    <div class="docs-body">
+
+<p>Role hierarchy governs which users can manage other users. A manager cannot create, edit, or delete
+                      an admin.
+                      Self-deletion is always blocked.</p>
+
+                  <h3><span class="method-badge method-get">GET</span><span class="endpoint-path">/api/users</span></h3>
+                  <p class="auth-note">Requires Bearer token + <code>users</code> permission (admin or manager).</p>
+                  <p>Return all users. Passwords are stripped from the response.</p>
+                  <pre class="code-block"><code>// Response 200
+[ { "id": "uuid", "name": "Alice", "email": "alice@example.com", "role": "admin", "isActive": true } ]</code></pre>
+
+                  <h3><span class="method-badge method-get">GET</span><span class="endpoint-path">/api/users/:id</span>
+                  </h3>
+                  <p class="auth-note">Requires Bearer token. Accessible to the user themselves, or a user with <code>users</code>
+                      permission.</p>
+                  <p>Return a single user by ID.</p>
+                  <pre class="code-block"><code>// Response 200
+{ "id": "uuid", "name": "Alice", "email": "alice@example.com", "role": "admin", "isActive": true }
+
+// Error 404
+{ "error": "User not found" }</code></pre>
+
+                  <h3><span class="method-badge method-post">POST</span><span class="endpoint-path">/api/users</span>
+                  </h3>
+                  <p class="auth-note">Requires Bearer token + <code>users</code> permission.</p>
+                  <p>Create a new user. The actor cannot assign a role higher than their own level.</p>
+                  <table class="table table-sm">
+                      <thead>
+                      <tr>
+                          <th>Field</th>
+                          <th>Type</th>
+                          <th>Description</th>
+                      </tr>
+                      </thead>
+                      <tbody>
+                      <tr>
+                          <td><code>name</code></td>
+                          <td>string</td>
+                          <td>Display name</td>
+                      </tr>
+                      <tr>
+                          <td><code>email</code></td>
+                          <td>string</td>
+                          <td>Unique email address</td>
+                      </tr>
+                      <tr>
+                          <td><code>password</code></td>
+                          <td>string</td>
+                          <td>Minimum 8 characters</td>
+                      </tr>
+                      <tr>
+                          <td><code>role</code></td>
+                          <td>string</td>
+                          <td>Optional. Defaults to <code>editor</code>.</td>
+                      </tr>
+                      </tbody>
+                  </table>
+                  <pre class="code-block"><code>// Response 201
+{ "id": "uuid", "name": "Bob", "email": "bob@example.com", "role": "editor", "isActive": true }
+
+// Error 409
+{ "error": "Email already in use" }</code></pre>
+
+                  <h3><span class="method-badge method-put">PUT</span><span class="endpoint-path">/api/users/:id</span>
+                  </h3>
+                  <p class="auth-note">Requires Bearer token + <code>users</code> permission.</p>
+                  <p>Update a user's details. Managers cannot edit admins. Role escalation beyond the actor's own level
+                      is blocked.</p>
+                  <table class="table table-sm">
+                      <thead>
+                      <tr>
+                          <th>Field</th>
+                          <th>Type</th>
+                          <th>Description</th>
+                      </tr>
+                      </thead>
+                      <tbody>
+                      <tr>
+                          <td><code>name</code></td>
+                          <td>string</td>
+                          <td>New display name</td>
+                      </tr>
+                      <tr>
+                          <td><code>email</code></td>
+                          <td>string</td>
+                          <td>New email address</td>
+                      </tr>
+                      <tr>
+                          <td><code>password</code></td>
+                          <td>string</td>
+                          <td>New password (min 8 chars)</td>
+                      </tr>
+                      <tr>
+                          <td><code>role</code></td>
+                          <td>string</td>
+                          <td>New role</td>
+                      </tr>
+                      <tr>
+                          <td><code>isActive</code></td>
+                          <td>boolean</td>
+                          <td>Enable or disable the account</td>
+                      </tr>
+                      </tbody>
+                  </table>
+                  <pre class="code-block"><code>// Response 200 — returns the updated user object</code></pre>
+
+                  <h3><span class="method-badge method-delete">DELETE</span><span
+                          class="endpoint-path">/api/users/:id</span></h3>
+                  <p class="auth-note">Requires Bearer token + <code>users</code> permission.</p>
+                  <p>Delete a user. Cannot delete your own account or a user with a higher role level.</p>
+                  <pre class="code-block"><code>// Response 200
+{ "success": true }
+
+// Error 403
+{ "error": "You cannot delete your own account" }</code></pre>
+
+    </div>
+  </div>
+</div>

package/admin/js/templates/docs/api-views.html

@@ -0,0 +1,142 @@
+<div class="view-header">
+  <h1><span data-icon="code"></span> API · Views API</h1>
+  <a href="#/api-reference" class="btn btn-ghost btn-sm"><span data-icon="arrow-left"></span> API overview</a>
+</div>
+<style>
+    .method-badge {
+        display: inline-block;
+        font-size: 11px;
+        font-weight: 700;
+        letter-spacing: 0.5px;
+        padding: 2px 7px;
+        border-radius: 4px;
+        font-family: var(--dm-font-mono, monospace);
+        margin-right: 6px;
+        vertical-align: middle;
+    }
+
+    .method-get {
+        background: #d1fae5;
+        color: #065f46;
+    }
+
+    .method-post {
+        background: #dbeafe;
+        color: #1e40af;
+    }
+
+    .method-put {
+        background: #fef3c7;
+        color: #92400e;
+    }
+
+    .method-patch {
+        background: #ccfbf1;
+        color: #134e4a;
+    }
+
+    .method-delete {
+        background: #fee2e2;
+        color: #991b1b;
+    }
+
+    .endpoint-path {
+        font-family: var(--dm-font-mono, monospace);
+        font-size: 14px;
+    }
+
+    .auth-note {
+        font-size: 12px;
+        color: var(--dm-color-text-muted, #6b7280);
+        margin: 4px 0 12px;
+    }
+
+    .auth-note code {
+        font-size: 11px;
+    }
+
+    .docs-body h3 {
+        margin-top: 24px;
+        margin-bottom: 8px;
+    }
+
+    .docs-body h3:first-child {
+        margin-top: 0;
+    }
+</style>
+
+<div class="row">
+  <div class="col-12">
+    <div class="docs-body">
+
+<p>Views require a MongoDB connection. All admin endpoints require authentication and the
+                      <code>views</code> permission. View configs are stored in the <code>cms__views</code> MongoDB
+                      collection.</p>
+
+                  <h3 style="margin-top:16px;font-size:15px;text-transform:uppercase;letter-spacing:.5px;opacity:.6">
+                      Admin Endpoints</h3>
+
+                  <h3><span class="method-badge method-get">GET</span><span class="endpoint-path">/api/views</span></h3>
+                  <p class="auth-note">Requires: <code>views</code> permission</p>
+                  <p>List all view configs, sorted by creation date descending.</p>
+
+                  <h3><span class="method-badge method-post">POST</span><span class="endpoint-path">/api/views</span>
+                  </h3>
+                  <p class="auth-note">Requires: <code>views</code> permission</p>
+                  <p>Create a new view config. Returns <code>201</code> on success.</p>
+                  <pre class="code-block"><code>{
+  "title": "Active Premium Users",
+  "slug": "active-premium-users",
+  "connection": "default",
+  "pipeline": {
+    "source": "users",
+    "stages": [
+      { "type": "$match",   "config": { "data.status": "active" } },
+      { "type": "$sort",    "config": { "meta.createdAt": -1 } },
+      { "type": "$project", "config": { "data.name": 1, "data.email": 1 } }
+    ]
+  },
+  "display": { "mode": "table", "columns": [ { "key": "data.name", "label": "Name" } ], "pageSize": 25 },
+  "access": { "roles": ["admin", "manager"], "public": false }
+}</code></pre>
+
+                  <h3><span class="method-badge method-get">GET</span><span
+                          class="endpoint-path">/api/views/:slug</span></h3>
+                  <p class="auth-note">Requires: <code>views</code> permission</p>
+                  <p>Return a single view config by slug.</p>
+
+                  <h3><span class="method-badge method-put">PUT</span><span
+                          class="endpoint-path">/api/views/:slug</span></h3>
+                  <p class="auth-note">Requires: <code>views</code> permission</p>
+                  <p>Update a view config. Accepts the same body shape as POST; all fields are optional.</p>
+
+                  <h3><span class="method-badge method-delete">DELETE</span><span
+                          class="endpoint-path">/api/views/:slug</span></h3>
+                  <p class="auth-note">Requires: <code>views</code> permission</p>
+                  <p>Delete a view config.</p>
+
+                  <h3><span class="method-badge method-get">GET</span><span class="endpoint-path">/api/views/:slug/execute</span>
+                  </h3>
+                  <p class="auth-note">Requires: <code>views</code> permission</p>
+                  <p>Execute the view's aggregation pipeline and return paginated results. Query params:
+                      <code>page</code> (default 1), <code>limit</code> (default 25).</p>
+                  <pre class="code-block"><code>// Response
+{ "results": [ ... ], "total": 142, "page": 1, "limit": 25 }</code></pre>
+
+                  <h3><span class="method-badge method-get">GET</span><span class="endpoint-path">/api/views/collection/:slug</span>
+                  </h3>
+                  <p class="auth-note">Requires: <code>views</code> permission</p>
+                  <p>List all view configs whose <code>pipeline.source</code> matches the given collection slug.</p>
+
+                  <h3 style="margin-top:24px;font-size:15px;text-transform:uppercase;letter-spacing:.5px;opacity:.6">
+                      Public Endpoint</h3>
+
+                  <h3><span class="method-badge method-get">GET</span><span class="endpoint-path">/api/views/:slug/public</span>
+                  </h3>
+                  <p class="auth-note">Access level: per view <code>access</code> config</p>
+                  <p>Execute the view publicly. If <code>access.public</code> is <code>false</code>, a valid JWT and a
+                      role listed in <code>access.roles</code> is required.</p>
+
+    </div>
+  </div>
+</div>

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

@@ -0,0 +1,175 @@
+<div class="view-header">
+  <h1><span data-icon="component"></span> Components — How-To</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">Short, copy-paste recipes for the things you'll actually do. For a guided
+        build-from-scratch see the <a href="#/docs/components-walkthrough">Walkthrough</a>; for the full
+        API see the <a href="#/docs/components">Reference</a>.</p>
+
+      <hr>
+
+      <h2>Create a component</h2>
+      <ol>
+        <li>Open <a href="#/components">Data → Components</a> → <strong>New Component</strong>.</li>
+        <li>Name it in lowercase-with-hyphens (e.g. <code>price-tag</code>). The name is permanent and
+          becomes the tag <code>&lt;dm-price-tag&gt;</code>.</li>
+        <li>Fill the <code>&lt;template&gt;</code>, <code>&lt;props&gt;</code> and <code>&lt;script&gt;</code>
+          tabs (the editor watches the live preview as you type).</li>
+        <li><strong>Save</strong>. It compiles first — fix any reported errors and it lands on disk.</li>
+      </ol>
+
+      <hr>
+
+      <h2>Render a value</h2>
+      <p>Interpolate a prop or state value with double braces:</p>
+      <pre class="code-block"><code>&lt;template&gt;&lt;span class="dm-price"&gt;{{currency}}{{amount}}&lt;/span&gt;&lt;/template&gt;
+&lt;props&gt;
+{
+  "currency": { "type": "string", "default": "£" },
+  "amount":   { "type": "number", "default": 0 }
+}
+&lt;/props&gt;
+&lt;script&gt;export default {};&lt;/script&gt;</code></pre>
+      <p>Use it: <code>[component name="price-tag" currency="$" amount="49" /]</code></p>
+
+      <hr>
+
+      <h2>Add state and respond to a click</h2>
+      <p>Render the markup with <code>data-action</code> hooks, then attach <strong>one</strong> delegated
+        listener to the shadow root in <code>onMount</code>. Mutate state with <code>this.set()</code> — the
+        template re-renders automatically.</p>
+      <pre class="code-block"><code>&lt;template&gt;
+&lt;div class="dm-counter"&gt;
+  &lt;strong&gt;{{count}}&lt;/strong&gt;
+  &lt;button data-action="inc"&gt;+&lt;/button&gt;
+&lt;/div&gt;
+&lt;/template&gt;
+&lt;props&gt;{ "step": { "type": "number", "default": 1 } }&lt;/props&gt;
+&lt;script&gt;
+export default {
+  data() { return { count: 0 }; },
+  methods: {
+    inc() { this.set({ count: this.data.count + this.props.step }); }
+  },
+  onMount() {
+    this.el.shadowRoot.addEventListener('click', (e) =&gt; {
+      if (e.target.dataset.action === 'inc') this.inc();
+    });
+  }
+};
+&lt;/script&gt;</code></pre>
+
+      <hr>
+
+      <h2>Initialise state from a prop</h2>
+      <p><code>data()</code> runs without a <code>this</code> binding, so it can't read props. Seed the value
+        in <code>onMount()</code> instead:</p>
+      <pre class="code-block"><code>data() { return { count: 0 }; },
+onMount() { this.set({ count: this.props.initial }); }</code></pre>
+
+      <hr>
+
+      <h2>Show something conditionally</h2>
+      <pre class="code-block"><code>{{#if showReset}}&lt;button data-action="reset"&gt;Reset&lt;/button&gt;{{/if}}
+{{#unless soldOut}}&lt;button&gt;Buy&lt;/button&gt;{{/unless}}</code></pre>
+
+      <hr>
+
+      <h2>Loop over a list</h2>
+      <p>Pass an array prop (attribute value is JSON) and iterate with <code>{{#each}}</code>:</p>
+      <pre class="code-block"><code>&lt;template&gt;
+&lt;ul&gt;{{#each items}}&lt;li&gt;{{@index}}. {{.}}&lt;/li&gt;{{/each}}&lt;/ul&gt;
+&lt;/template&gt;
+&lt;props&gt;{ "items": { "type": "array", "default": [] } }&lt;/props&gt;
+&lt;script&gt;export default {};&lt;/script&gt;</code></pre>
+      <pre class="code-block"><code>&lt;dm-my-list items='["Alpha","Beta","Gamma"]'&gt;&lt;/dm-my-list&gt;</code></pre>
+
+      <hr>
+
+      <h2>Accept arbitrary inner content (slot)</h2>
+      <pre class="code-block"><code>&lt;template&gt;
+&lt;div class="dm-callout"&gt;&lt;slot&gt;&lt;/slot&gt;&lt;/div&gt;
+&lt;/template&gt;</code></pre>
+      <pre class="code-block"><code>&lt;dm-callout&gt;&lt;p&gt;Anything here is projected into the slot.&lt;/p&gt;&lt;/dm-callout&gt;</code></pre>
+
+      <hr>
+
+      <h2>Fetch data from the API</h2>
+      <p>Domma's HTTP helper <code>H</code> is available inside the script. Fetch in <code>onMount</code> and
+        push results into state:</p>
+      <pre class="code-block"><code>export default {
+  data() { return { entries: [] }; },
+  async onMount() {
+    const res = await H.get('/api/v1/announcements');
+    this.set({ entries: res.entries || [] });
+  }
+};</code></pre>
+
+      <hr>
+
+      <h2>Run something on a timer (and clean up)</h2>
+      <p>Start the interval in <code>onMount</code>; always tear it down in <code>onUnmount</code> so it
+        doesn't leak when the element is removed:</p>
+      <pre class="code-block"><code>export default {
+  data() { return { now: '' }; },
+  _timer: null,
+  methods: { tick() { this.set({ now: new Date().toLocaleTimeString() }); } },
+  onMount()   { this.tick(); this._timer = setInterval(() =&gt; this.tick(), 1000); },
+  onUnmount() { if (this._timer) clearInterval(this._timer); }
+};</code></pre>
+
+      <hr>
+
+      <h2>Style it without leaking</h2>
+      <p>Anything in <code>&lt;style&gt;</code> is scoped to the component, so you can use short class names
+        freely:</p>
+      <pre class="code-block"><code>&lt;style&gt;
+.dm-callout { padding: 1rem; border-left: 3px solid var(--dm-primary, #5aa8ff); }
+&lt;/style&gt;</code></pre>
+
+      <hr>
+
+      <h2>Use it on a page</h2>
+      <p>Either form works and auto-loads the component's module:</p>
+      <pre class="code-block"><code>[component name="counter" step="2" /]
+
+&lt;dm-counter step="2"&gt;&lt;/dm-counter&gt;</code></pre>
+
+      <hr>
+
+      <h2>Move a component between sites</h2>
+      <ol>
+        <li>On <a href="#/components">Components</a>, click <span data-icon="download"></span> Export on the
+          row — you'll download <code>name.dmcomponent.json</code>.</li>
+        <li>On the other site, click <strong>Import</strong> and pick that file. On a name clash you'll be
+          asked to confirm an overwrite.</li>
+      </ol>
+
+      <hr>
+
+      <h2>File it under a project</h2>
+      <p>In the editor, set the <strong>Project</strong> dropdown. That writes <code>meta.project</code> to
+        the sidecar so the component shows under that project's filtered list and is scoped accordingly.</p>
+
+      <hr>
+      <p class="text-muted" style="font-size:.9rem;">
+        Next: <a href="#/docs/components-walkthrough">Walkthrough →</a> &nbsp;·&nbsp;
+        <a href="#/docs/components-rules">Rules &amp; gotchas</a>
+      </p>
+
+    </div>
+  </div>
+</div>