@voxgig/build 4.3.0 → 4.11.0

package/tm/web/web/src/cmp/app.md.frag

@@ -0,0 +1,28 @@
+# Component: vg-app (`cmp/app.js`)
+
+The root router component: mounts the public site or the authenticated
+shell depending on auth state, and re-routes when that state changes.
+
+## Structure
+
+```mermaid
+flowchart TB
+  app[vg-app] -->|signed out| pub[vg-public]
+  app -->|signed in| shell[vg-shell]
+  pub --> auth[vg-auth]
+```
+
+## Messages
+
+| Message | Direction | Purpose |
+|---|---|---|
+| `cmp:auth,load:state` | post | Trigger initial auth load on mount |
+| `cmp:evt,name:auth` (event `auth`) | sub via `onEvent` | Re-route on sign-in / sign-out |
+
+## Notes
+
+- Mounted once from `index.html`; everything else hangs off it.
+- Re-routing replaces `innerHTML`, tearing down the previous subtree —
+  long-lived components must tolerate re-mounts (see the `isConnected`
+  guard convention in shell/admin).
+

package/tm/web/web/src/cmp/auth.js.frag

@@ -1,8 +1,10 @@
-// Auth: a seneca plugin holding the signed-in principal, and the
-// <vg-auth> web component (sign-in form / signed-in bar) driving it
-// purely through bus messages.
+// Auth: a seneca plugin holding the signed-in principal (state), and the
+// <vg-auth> login form used on the public site. The signed-in UI lives in
+// the app shell's user menu, not here.
 
 import { bus, emit } from '../bus.js'
+import { remindPass } from '../api.js'
+import * as Hooks from '../hooks.js'
 
 
 bus.use(function auth_cmp() {
@@ -16,7 +18,7 @@ bus.use(function auth_cmp() {
 
   // Resolve current auth from the backend (cookie session).
   seneca.add('cmp:auth,load:state', function (msg, reply) {
-    this.act('aim:req,on:auth,load:auth', function (err, out) {
+    this.act('aim:web,on:auth,load:auth', function (err, out) {
       user = (!err && out.ok && 'signedin' === out.state) ? out.user : null
       emit('auth', { user })
       reply({ ok: true, user })
@@ -24,7 +26,7 @@ bus.use(function auth_cmp() {
   })
 
   seneca.add('cmp:auth,signin:user', function (msg, reply) {
-    this.act('aim:req,on:auth,signin:user', {
+    this.act('aim:web,on:auth,signin:user', {
       email: msg.email,
       password: msg.password,
     }, function (err, out) {
@@ -38,7 +40,7 @@ bus.use(function auth_cmp() {
   })
 
   seneca.add('cmp:auth,signout:user', function (msg, reply) {
-    this.act('aim:req,on:auth,signout:user', function () {
+    this.act('aim:web,on:auth,signout:user', function () {
       user = null
       emit('auth', { user })
       reply({ ok: true })
@@ -47,51 +49,77 @@ bus.use(function auth_cmp() {
 })
 
 
+// The public login form (+ a forgot-password flow that never actually
+// emails — the backend logs the reset code).
 class VgAuth extends HTMLElement {
   connectedCallback() {
+    this.mode = 'signin'
     this.render()
   }
 
-  async render() {
-    const state = await bus.post('cmp:auth,get:state')
-
-    if (state.user) {
-      this.innerHTML = `
-        <div class="vg-auth-bar">
-          <span>Signed in: <b>${state.user.email}</b></span>
-          <button id="vg-signout">Sign out</button>
-        </div>`
-      this.querySelector('#vg-signout').onclick = async () => {
-        await bus.post('cmp:auth,signout:user')
-        this.render()
-      }
+  render() {
+    if ('forgot' === this.mode) {
+      this.renderForgot()
     }
     else {
-      this.innerHTML = `
-        <form class="vg-auth-form">
-          <h2>Sign in</h2>
-          <label>Email <input name="email" type="email" required /></label>
-          <label>Password <input name="password" type="password" required /></label>
-          <button type="submit">Sign in</button>
-          <div class="vg-auth-err" id="vg-auth-err"></div>
-        </form>`
-      this.querySelector('form').onsubmit = async (ev) => {
-        ev.preventDefault()
-        const fd = new FormData(ev.target)
-        const res = await bus.post('cmp:auth,signin:user', {
-          email: fd.get('email'),
-          password: fd.get('password'),
-        })
-        if (!res.ok) {
-          this.querySelector('#vg-auth-err').textContent =
-            'Sign in failed: ' + res.why
-        }
-        else {
-          this.render()
-        }
+      this.renderSignin()
+    }
+  }
+
+  renderSignin() {
+    this.innerHTML = `
+      <form class="vg-auth-form">
+        <h2>Sign in</h2>
+        <label>Email <input name="email" type="email" required /></label>
+        <label>Password <input name="password" type="password" required /></label>
+        <button type="submit">Sign in</button>
+        <a href="#" class="vg-link" id="vg-forgot">Forgot password?</a>
+        ${Hooks.html('auth:form:footer', {})}
+        <div class="vg-auth-err" id="vg-auth-err"></div>
+      </form>`
+    this.querySelector('#vg-forgot').onclick = (ev) => {
+      ev.preventDefault()
+      this.mode = 'forgot'
+      this.render()
+    }
+    this.querySelector('form').onsubmit = async (ev) => {
+      ev.preventDefault()
+      const fd = new FormData(ev.target)
+      const res = await bus.post('cmp:auth,signin:user', {
+        email: fd.get('email'),
+        password: fd.get('password'),
+      })
+      if (!res.ok) {
+        this.querySelector('#vg-auth-err').textContent = 'Sign in failed: ' + res.why
       }
     }
   }
+
+  renderForgot() {
+    this.innerHTML = `
+      <form class="vg-auth-form">
+        <h2>Reset password</h2>
+        <p class="vg-hint">Enter your email and we'll send a reset link.</p>
+        <label>Email <input name="email" type="email" required /></label>
+        <button type="submit">Send reset link</button>
+        <a href="#" class="vg-link" id="vg-back">Back to sign in</a>
+        <div class="vg-auth-msg" id="vg-auth-msg"></div>
+      </form>`
+    this.querySelector('#vg-back').onclick = (ev) => {
+      ev.preventDefault()
+      this.mode = 'signin'
+      this.render()
+    }
+    this.querySelector('form').onsubmit = async (ev) => {
+      ev.preventDefault()
+      const fd = new FormData(ev.target)
+      await remindPass(fd.get('email'))
+      // Always the same message (no user enumeration; nothing is actually sent).
+      this.querySelector('#vg-auth-msg').textContent =
+        'If that email is registered, a reset link has been sent.'
+    }
+  }
 }
 
 customElements.define('vg-auth', VgAuth)
+

package/tm/web/web/src/cmp/auth.md.frag

@@ -0,0 +1,36 @@
+# Component: vg-auth (`cmp/auth.js`)
+
+The sign-in form (with forgot-password), and the client-side `cmp:auth`
+state service other components query.
+
+## Message flow
+
+```mermaid
+sequenceDiagram
+  participant U as User
+  participant A as vg-auth
+  participant G as gateway (backend)
+  U->>A: submit email + password
+  A->>G: aim:req,on:auth,signin:user
+  G-->>A: { ok, user }
+  A->>A: emit 'auth' event (cmp:evt,name:auth)
+  Note over A: vg-app re-routes to the shell
+```
+
+## Messages
+
+| Message | Direction | Purpose |
+|---|---|---|
+| `cmp:auth,load:state` | answers | Load the session (`aim:req,on:auth,load:auth`) |
+| `cmp:auth,get:state` | answers | Current `{ user }` for other components |
+| `cmp:auth,signin:user` | answers | Sign in, then emit `auth` |
+| `cmp:auth,signout:user` | answers | Sign out, then emit `auth` |
+| `aim:req,on:auth,remind:pass` | post | Forgot-password (server stub; no email sent) |
+| event `auth` | emit | Auth state changed (the store cache also clears on this) |
+
+## Customisation
+
+| Hook point | Kind | Effect |
+|---|---|---|
+| `auth:form:footer` | html | Extra links/markup under the form |
+

package/tm/web/web/src/cmp/public.js.frag

@@ -0,0 +1,58 @@
+// The public content site (marketing pages) shown to signed-out visitors,
+// with the login form. Static content — the app itself is behind auth.
+
+import * as Hooks from '../hooks.js'
+
+class VgPublic extends HTMLElement {
+  connectedCallback() {
+    this.innerHTML = `
+      <div class="vg-public">
+        <header class="vg-public-nav">
+          <span class="vg-brand">📋 Todo</span>
+          <nav>
+            <a href="#features">Features</a>
+            <a href="#about">About</a>
+          </nav>
+        </header>
+
+        <section class="vg-hero">
+          <div class="vg-hero-copy">
+            <h1>Plan together. Ship faster.</h1>
+            <p>Organise work into projects, invite your team, and track every
+              todo — a simple, collaborative workspace.</p>
+          </div>
+          <div class="vg-hero-auth">
+            <vg-auth></vg-auth>
+          </div>
+        </section>
+
+        <section id="features" class="vg-features">
+          <h2>Features</h2>
+          <div class="vg-feature-grid">
+            <div class="vg-feature"><h3>Projects</h3>
+              <p>Group work into projects and assign collaborators.</p></div>
+            <div class="vg-feature"><h3>Todo lists</h3>
+              <p>Break projects into lists and items, done when done.</p></div>
+            <div class="vg-feature"><h3>Collaboration</h3>
+              <p>Everyone assigned to a project sees and edits its work.</p></div>
+          </div>
+        </section>
+
+        <section id="about" class="vg-about">
+          <h2>About</h2>
+          <p>A demonstration of a model-driven enterprise app: the entire UI
+            — navigation, forms and entity relationships — is generated from
+            the data model.</p>
+        </section>
+
+        ${Hooks.html('public:sections', {})}
+
+        <footer class="vg-public-footer">
+          <span>&copy; Todo. A Voxgig demo.</span>
+        </footer>
+      </div>`
+  }
+}
+
+customElements.define('vg-public', VgPublic)
+

package/tm/web/web/src/cmp/public.md.frag

@@ -0,0 +1,26 @@
+# Component: vg-public (`cmp/public.js`)
+
+The public content site shown to signed-out visitors: marketing sections
+(hero, features, about) plus the sign-in form.
+
+## Structure
+
+```mermaid
+flowchart TB
+  pub[vg-public] --> hero[hero / features / about sections]
+  pub --> auth[vg-auth - the login form]
+```
+
+## Customisation
+
+| Hook point | Kind | Effect |
+|---|---|---|
+| `public:sections` | html | Append extra marketing sections |
+
+Static content is meant to be edited directly — this component is
+create-once and project-owned; replace the copy with your product's.
+
+## Messages
+
+None of its own — sign-in flows through the embedded `vg-auth`.
+

package/tm/web/web/src/cmp/settings.js.frag

@@ -0,0 +1,178 @@
+// User settings & security: update profile and change password. Backed by
+// the auth service wrappers (aim:req,on:auth,{update:user,change:pass}).
+
+import { bus } from '../bus.js'
+import * as Api from '../api.js'
+import * as Hooks from '../hooks.js'
+
+
+class VgSettings extends HTMLElement {
+  async connectedCallback() {
+    const state = await bus.post('cmp:auth,get:state')
+    this.user = state.user || {}
+    this.apikeys = []
+    this.newKey = null
+    this.render()
+    this.loadKeys()
+  }
+
+  async loadKeys() {
+    const res = await Api.listApikeys()
+    this.apikeys = (res.ok && res.items) || []
+    if (this.isConnected) {
+      this.renderKeys()
+    }
+  }
+
+  render() {
+    this.innerHTML = `
+      <div class="vg-entity vg-settings">
+        <h2>Settings &amp; security</h2>
+
+        <section class="vg-card">
+          <h3>Profile</h3>
+          <form class="vg-entity-form" id="vg-profile">
+            <label>Name <input name="name" type="text" value="${esc(this.user.name)}" /></label>
+            <label>Email <input type="email" value="${esc(this.user.email)}" disabled /></label>
+            <div class="vg-form-actions"><button type="submit" class="vg-primary">Save profile</button></div>
+            <div class="vg-form-msg" id="vg-profile-msg"></div>
+          </form>
+        </section>
+
+        <section class="vg-card">
+          <h3>Change password</h3>
+          <form class="vg-entity-form" id="vg-pass">
+            <label>New password <input name="password" type="password" required minlength="8" /></label>
+            <label>Confirm <input name="confirm" type="password" required minlength="8" /></label>
+            <div class="vg-form-actions"><button type="submit" class="vg-primary">Change password</button></div>
+            <div class="vg-form-msg" id="vg-pass-msg"></div>
+          </form>
+        </section>
+
+        <section class="vg-card">
+          <h3>API keys</h3>
+          <p class="vg-muted">Access the REST API (<code>/api/v1/…</code>) with
+            <code>Authorization: Bearer &lt;key&gt;</code>. A key is shown
+            only once, at creation.</p>
+          <form class="vg-entity-form vg-apikey-form" id="vg-apikey-create">
+            <label>Name <input name="name" type="text" required placeholder="e.g. ci-deploy" /></label>
+            <div class="vg-form-actions"><button type="submit" class="vg-primary">Create key</button></div>
+            <div class="vg-form-msg" id="vg-apikey-msg"></div>
+          </form>
+          <div id="vg-apikey-new"></div>
+          <div id="vg-apikey-list"></div>
+        </section>
+
+        ${Hooks.html('settings:sections', { user: this.user })}
+      </div>`
+
+    this.querySelector('#vg-profile').onsubmit = async (ev) => {
+      ev.preventDefault()
+      const name = ev.target.querySelector('[name=name]').value
+      const res = await Api.updateUser({ name })
+      const msg = this.querySelector('#vg-profile-msg')
+      if (res.ok) {
+        this.user.name = res.user ? res.user.name : name
+        msg.textContent = 'Profile saved.'
+        msg.className = 'vg-form-msg vg-ok'
+      }
+      else {
+        msg.textContent = 'Save failed: ' + (res.why || '')
+        msg.className = 'vg-form-msg vg-err'
+      }
+    }
+
+    this.querySelector('#vg-apikey-create').onsubmit = async (ev) => {
+      ev.preventDefault()
+      const name = ev.target.querySelector('[name=name]').value.trim()
+      const msg = this.querySelector('#vg-apikey-msg')
+      const res = await Api.createApikey(name)
+      if (res.ok) {
+        ev.target.reset()
+        this.newKey = res.key
+        msg.textContent = ''
+        await this.loadKeys()
+      }
+      else {
+        msg.textContent = 'Create failed: ' + (res.why || '')
+        msg.className = 'vg-form-msg vg-err'
+      }
+    }
+    this.renderKeys()
+
+    this.querySelector('#vg-pass').onsubmit = async (ev) => {
+      ev.preventDefault()
+      const pw = ev.target.querySelector('[name=password]').value
+      const confirm = ev.target.querySelector('[name=confirm]').value
+      const msg = this.querySelector('#vg-pass-msg')
+      if (pw !== confirm) {
+        msg.textContent = 'Passwords do not match.'
+        msg.className = 'vg-form-msg vg-err'
+        return
+      }
+      const res = await Api.changePass(pw)
+      if (res.ok) {
+        ev.target.reset()
+        msg.textContent = 'Password changed.'
+        msg.className = 'vg-form-msg vg-ok'
+      }
+      else {
+        msg.textContent = 'Change failed: ' + (res.why || '')
+        msg.className = 'vg-form-msg vg-err'
+      }
+    }
+  }
+
+  // The API-keys list (re-rendered after create/revoke). The freshly
+  // created key is shown ONCE (it is never retrievable again).
+  renderKeys() {
+    const fresh = this.querySelector('#vg-apikey-new')
+    if (fresh) {
+      fresh.innerHTML = this.newKey ? `
+        <div class="vg-apikey-once">
+          <strong>Copy your new key now — it will not be shown again:</strong>
+          <code class="vg-apikey-value">${esc(this.newKey)}</code>
+        </div>` : ''
+    }
+
+    const list = this.querySelector('#vg-apikey-list')
+    if (!list) {
+      return
+    }
+    list.innerHTML = this.apikeys.length ? `
+      <table class="vg-table vg-apikey-table">
+        <thead><tr><th>Name</th><th>Key</th><th>Created</th><th>Status</th><th></th></tr></thead>
+        <tbody>
+          ${this.apikeys.map((k) => `
+            <tr data-id="${esc(k.id)}">
+              <td>${esc(k.name)}</td>
+              <td><code>${esc(k.prefix)}…</code></td>
+              <td>${k.t_c ? new Date(k.t_c).toISOString().slice(0, 10) : ''}</td>
+              <td>${k.revoked ? 'revoked' : 'active'}</td>
+              <td>${k.revoked ? '' :
+                `<button type="button" class="vg-apikey-revoke" data-id="${esc(k.id)}">Revoke</button>`}</td>
+            </tr>`).join('')}
+        </tbody>
+      </table>` : '<p class="vg-muted">No API keys yet.</p>'
+
+    for (const btn of list.querySelectorAll('.vg-apikey-revoke')) {
+      btn.onclick = async () => {
+        const res = await Api.revokeApikey(btn.dataset.id)
+        if (res.ok) {
+          this.newKey = null
+          await this.loadKeys()
+        }
+      }
+    }
+  }
+}
+
+
+function esc(s) {
+  return String(null == s ? '' : s).replace(/[&<>"]/g, (c) =>
+    ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;' }[c]))
+}
+
+
+customElements.define('vg-settings', VgSettings)
+

package/tm/web/web/src/cmp/settings.md.frag

@@ -0,0 +1,30 @@
+# Component: vg-settings (`cmp/settings.js`)
+
+User settings & security: profile (name/email) and change-password.
+Mounted in the shell's main area from the user menu.
+
+## Message flow
+
+```mermaid
+sequenceDiagram
+  participant S as vg-settings
+  participant G as gateway (backend)
+  S->>G: aim:req,on:auth,update:user (profile save)
+  S->>G: aim:req,on:auth,change:pass (old + new password)
+  G-->>S: { ok } | { ok:false, why }
+```
+
+## Messages
+
+| Message | Direction | Purpose |
+|---|---|---|
+| `cmp:auth,get:state` | post | Current user to populate the form |
+| `aim:req,on:auth,update:user` | post (via `api.js`) | Save profile |
+| `aim:req,on:auth,change:pass` | post (via `api.js`) | Change password (min length 8) |
+
+## Customisation
+
+| Hook point | Kind | Effect |
+|---|---|---|
+| `settings:sections` | html | Extra settings sections |
+