@voxgig/build 4.4.0 → 4.11.0

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

@@ -0,0 +1,231 @@
+// The authenticated enterprise app shell: a traditional layout with a top
+// bar (brand, project selector, user menu top-right) and a collapsible left
+// menu listing the model's entities. The main area hosts the generic entity
+// admin (or settings). Everything is driven by the model — the entity menu
+// and relationships come from /model.json, so it scales to any graph.
+
+import { bus, onEvent } from '../bus.js'
+import * as Model from '../model.js'
+import * as Api from '../api.js'
+import * as Hooks from '../hooks.js'
+import * as Theme from '../theme.js'
+
+
+class VgShell extends HTMLElement {
+  async connectedCallback() {
+    await Model.loadModel()
+    const state = await bus.post('cmp:auth,get:state')
+    this.user = state.user
+    this.projects = []
+    this.currentProjectId = null
+    this.currentCanon = null
+    this.view = 'entity'
+    this.collapsed = false
+
+    this.renderFrame()
+    await this.loadProjects()
+
+    // Land on projects if present, else the first entity.
+    const ents = Model.entities()
+    const start = ents.find((e) => 'proj/project' === e.canon) || ents[0]
+    if (start) {
+      this.openEntity(start.canon)
+    }
+
+    // The project selector refreshes when projects change (e.g. a new one is
+    // created). Guard with isConnected: bus.sub has no auto-unsubscribe, so a
+    // torn-down shell (sign-out→in re-mounts it) must not act on stale events.
+    onEvent('projects-changed', () => {
+      if (this.isConnected) {
+        this.loadProjects()
+      }
+    })
+  }
+
+  // ---- data ----
+
+  async loadProjects() {
+    this.projects = await Api.list('proj/project')
+    if (!this.currentProjectId && this.projects.length) {
+      this.currentProjectId = this.projects[0].id
+    }
+    this.renderProjectSelect()
+    // A project-scoped view may need re-listing once projects are known.
+    if ('entity' === this.view && this.admin && Model.isProjectScoped(this.currentCanon)) {
+      this.admin.projectId = this.currentProjectId
+      this.admin.reload()
+    }
+  }
+
+  // ---- navigation ----
+
+  openEntity(canon, detailId) {
+    // Opening a project's detail makes it the current project, so children
+    // created within it inherit the right project context.
+    if ('proj/project' === canon && detailId) {
+      this.currentProjectId = detailId
+      this.renderProjectSelect()
+    }
+    this.currentCanon = canon
+    this.view = 'entity'
+    this.setActiveNav()
+    this.mountAdmin(canon, detailId || null)
+  }
+
+  openSettings() {
+    this.view = 'settings'
+    this.setActiveNav()
+    const main = this.querySelector('#vg-main')
+    main.innerHTML = '<vg-settings></vg-settings>'
+  }
+
+  mountAdmin(canon, detailId) {
+    const main = this.querySelector('#vg-main')
+    // A custom view (ux:{view:'custom'}) replaces the generic admin.
+    const tag = Model.customViewTag(canon) || 'vg-entity-admin'
+    if (!this.admin || this.admin.parentNode !== main || this.admin.localName !== tag) {
+      main.innerHTML = ''
+      this.admin = document.createElement(tag)
+      this.admin.onNavigate = (c, id) => this.openEntity(c, id)
+      main.appendChild(this.admin)
+    }
+    this.admin.canon = canon
+    this.admin.projectId = Model.isProjectScoped(canon) ? this.currentProjectId : null
+    this.admin.detailId = detailId
+    this.admin.reload()
+  }
+
+  // ---- render ----
+
+  renderFrame() {
+    this.innerHTML = `
+      <div class="vg-shell${this.collapsed ? ' vg-collapsed' : ''}">
+        <header class="vg-topbar">
+          <button class="vg-icon-btn" id="vg-toggle" title="Menu">☰</button>
+          <span class="vg-brand">📋 $$Name$$</span>
+          <div class="vg-project-picker">
+            <label>Project</label>
+            <select id="vg-project"></select>
+          </div>
+          <div class="vg-spacer"></div>
+          ${Hooks.html('shell:topbar:right', { user: this.user })}
+          <div class="vg-usermenu" id="vg-usermenu">
+            <button class="vg-user-btn" id="vg-user-btn">
+              <span>${this.user ? this.user.email : ''}</span> <span class="vg-caret">▾</span>
+            </button>
+            <div class="vg-user-dropdown" id="vg-user-dropdown" hidden>
+              ${Theme.modes().length > 1
+                ? `<a href="#" id="vg-theme-toggle">Theme: ${esc(Theme.current())}</a>` : ''}
+              <a href="#" id="vg-nav-settings">Settings &amp; security</a>
+              <a href="#" id="vg-signout">Sign out</a>
+            </div>
+          </div>
+        </header>
+        <div class="vg-body">
+          <aside class="vg-sidebar">
+            ${Hooks.html('shell:sidebar:top', { user: this.user })}
+            <input class="vg-ent-filter" id="vg-ent-filter" placeholder="Filter…" />
+            <nav id="vg-entnav"></nav>
+          </aside>
+          <main class="vg-main" id="vg-main"></main>
+        </div>
+      </div>`
+
+    this.querySelector('#vg-toggle').onclick = () => {
+      this.collapsed = !this.collapsed
+      this.querySelector('.vg-shell').classList.toggle('vg-collapsed', this.collapsed)
+    }
+
+    const userBtn = this.querySelector('#vg-user-btn')
+    const dropdown = this.querySelector('#vg-user-dropdown')
+    userBtn.onclick = (ev) => {
+      ev.stopPropagation()
+      dropdown.hidden = !dropdown.hidden
+    }
+    document.addEventListener('click', () => { dropdown.hidden = true })
+
+    const themeToggle = this.querySelector('#vg-theme-toggle')
+    if (themeToggle) {
+      themeToggle.onclick = (ev) => {
+        ev.preventDefault()
+        ev.stopPropagation()
+        themeToggle.textContent = 'Theme: ' + Theme.nextMode()
+      }
+    }
+    this.querySelector('#vg-nav-settings').onclick = (ev) => {
+      ev.preventDefault()
+      dropdown.hidden = true
+      this.openSettings()
+    }
+    this.querySelector('#vg-signout').onclick = async (ev) => {
+      ev.preventDefault()
+      await bus.post('cmp:auth,signout:user')
+    }
+
+    this.querySelector('#vg-project').onchange = (ev) => {
+      this.currentProjectId = ev.target.value
+      if ('entity' === this.view && Model.isProjectScoped(this.currentCanon)) {
+        this.admin.projectId = this.currentProjectId
+        this.admin.reload()
+      }
+    }
+
+    const filter = this.querySelector('#vg-ent-filter')
+    filter.oninput = () => this.renderNav(filter.value)
+
+    this.renderNav('')
+  }
+
+  renderProjectSelect() {
+    const sel = this.querySelector('#vg-project')
+    if (!sel) {
+      return
+    }
+    sel.innerHTML = this.projects.length
+      ? this.projects.map((p) =>
+          `<option value="${p.id}"${p.id === this.currentProjectId ? ' selected' : ''}>${esc(p.name)}</option>`).join('')
+      : '<option value="">(no projects)</option>'
+  }
+
+  // The entity menu, grouped by zone, filterable (scales to many entities).
+  renderNav(filter) {
+    const nav = this.querySelector('#vg-entnav')
+    const f = (filter || '').toLowerCase()
+    // Hook: reorder/filter/relabel the entity menu.
+    const all = Hooks.filter('shell:nav:items', Model.entities(), {})
+    const ents = all.filter((e) => e.canon.toLowerCase().indexOf(f) >= 0)
+    const byZone = {}
+    for (const e of ents) {
+      (byZone[e.zone] = byZone[e.zone] || []).push(e)
+    }
+    nav.innerHTML = Object.keys(byZone).sort().map((zone) => `
+      <div class="vg-navgroup">
+        <div class="vg-navgroup-title">${esc(Model.titleize(zone))}</div>
+        ${byZone[zone].map((e) =>
+          `<a href="#" class="vg-navlink${e.canon === this.currentCanon ? ' vg-sel' : ''}"
+             data-canon="${e.canon}">${esc(e.label)}</a>`).join('')}
+      </div>`).join('')
+    for (const a of nav.querySelectorAll('.vg-navlink')) {
+      a.onclick = (ev) => {
+        ev.preventDefault()
+        this.openEntity(a.dataset.canon)
+      }
+    }
+  }
+
+  setActiveNav() {
+    for (const a of this.querySelectorAll('.vg-navlink')) {
+      a.classList.toggle('vg-sel', 'entity' === this.view && a.dataset.canon === this.currentCanon)
+    }
+  }
+}
+
+
+function esc(s) {
+  return String(null == s ? '' : s).replace(/[&<>"]/g, (c) =>
+    ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;' }[c]))
+}
+
+
+customElements.define('vg-shell', VgShell)
+

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

@@ -0,0 +1,49 @@
+# Component: vg-shell (`cmp/shell.js`)
+
+The authenticated enterprise app shell: top bar (brand, project
+selector, user menu), collapsible left entity menu, and the main area
+hosting the entity admin (generic or custom view) or settings. Entirely
+model-driven — the entity menu and view routing come from `model.js`.
+
+## Structure
+
+```mermaid
+flowchart TB
+  shell[vg-shell]
+  shell --> topbar[topbar: collapse, brand, project select, user menu]
+  shell --> sidebar[sidebar: filter + entity nav by zone]
+  shell --> main[main area]
+  main -->|generic entity| admin[vg-entity-admin]
+  main -->|ux view custom| custom[vg-view-zone-name]
+  main -->|settings| settings[vg-settings]
+```
+
+## Behaviour
+
+- **Navigation**: `openEntity(canon, detailId?)` mounts the right
+  component for the entity (`Model.customViewTag(canon)` or the generic
+  admin), sets props (`canon`, `projectId`, `detailId`, `onNavigate`)
+  and calls `reload()`.
+- **Project context**: the project `select` (or opening a project's
+  detail) sets `currentProjectId`; project-scoped entities re-list when
+  it changes.
+- **Theme**: the user menu shows a mode toggle when the model declares
+  more than one theme mode (`theme.js`).
+
+## Messages
+
+| Message | Direction | Purpose |
+|---|---|---|
+| `cmp:auth,get:state` | post | Current user for the user menu |
+| `cmp:auth,signout:user` | post | Sign out |
+| `aim:ent,cmd:list` (via `api.js`) | post | Project list for the selector |
+| event `projects-changed` | sub | Refresh the project selector (guarded with `isConnected`) |
+
+## Customisation
+
+| Hook point | Kind | Effect |
+|---|---|---|
+| `shell:topbar:right` | html | Markup before the user menu |
+| `shell:sidebar:top` | html | Markup above the entity filter |
+| `shell:nav:items` | filter | Reorder/filter/relabel the entity menu |
+

package/tm/web/web/src/cmp/view/custom-view.js.frag

@@ -0,0 +1,47 @@
+// CUSTOM VIEW for $$canon$$ (the model declares ux:{ view: 'custom' } for
+// this entity). This file is HAND-CODED and CREATE-ONCE — regeneration will
+// NOT overwrite it, so edit it freely. It replaces the generic entity admin
+// for this entity.
+//
+// The app shell sets these properties before calling reload():
+//   - canon       : this entity's canon ('$$canon$$')
+//   - projectId   : the currently selected project (if project-scoped)
+//   - detailId    : a specific row id when opened from elsewhere, else null
+//   - onNavigate(canon, id) : ask the shell to open another entity/detail
+// Build your UI with the generic helpers in ../../api.js and ../../model.js.
+
+import * as Api from '../../api.js'
+import * as Model from '../../model.js'
+
+
+class $$className$$ extends HTMLElement {
+  navigate(canon, id) {
+    if (this.onNavigate) {
+      this.onNavigate(canon, id)
+    }
+  }
+
+  async reload() {
+    const canon = '$$canon$$'
+    const q = {}
+    const pf = Model.projectRefField(canon)
+    if (pf && this.projectId) {
+      q[pf] = this.projectId
+    }
+    const items = await Api.list(canon, q)
+    const labelField = Model.labelField(canon)
+
+    // Starter UI: a simple list. Replace this with your custom view.
+    this.innerHTML = `
+      <div class="vg-entity">
+        <div class="vg-entity-head"><h2>$$Label$$</h2></div>
+        <ul>${items.map((it) =>
+          `<li>${String(null == it[labelField] ? it.id : it[labelField])}</li>`).join('')
+          || '<li class="vg-muted">Nothing yet.</li>'}</ul>
+        <p class="vg-hint">Hand-coded custom view — edit
+          web/src/cmp/view/$$zone$$_$$name$$.js to build it out.</p>
+      </div>`
+  }
+}
+
+customElements.define('$$tag$$', $$className$$)

package/tm/web/web/src/cmp/view/custom-view.md.frag

@@ -0,0 +1,31 @@
+# Component: $$tag$$ (`cmp/view/$$zone$$_$$name$$.js`)
+
+Hand-coded custom view for the `$$canon$$` entity — mounted by the shell
+INSTEAD of the generic `vg-entity-admin`, because the model declares
+`ux: { view: 'custom' }` on this entity. The component file is
+create-once and developer-owned; document your design decisions here.
+
+## Contract
+
+```mermaid
+flowchart LR
+  shell[vg-shell] -->|props: canon, projectId, detailId, onNavigate| view[$$tag$$]
+  shell -->|method| reload[view.reload]
+  view -->|Api.list / load / save / remove| ent[aim:ent messages]
+  view -->|onNavigate canon,id| shell
+```
+
+| Member | Meaning |
+|---|---|
+| `canon` | `'$$canon$$'` |
+| `projectId` | Current project id when project-scoped, else `null` |
+| `detailId` | Entity id to open in detail, or `null` |
+| `onNavigate(canon, id)` | Navigate elsewhere in the app |
+| `reload()` | Re-fetch and re-render |
+
+## Data
+
+Use `Api` (`../../api.js`) — data flows through the generic
+`aim:ent,cmd:*` messages, so membership scoping and validation apply
+unchanged. Use `Model` (`../../model.js`) for labels, fields, and the
+relationship graph.

package/tm/web/web/src/custom.css.frag

@@ -0,0 +1,8 @@
+/* Project CSS customisation (CREATE-ONCE — never overwritten). Override the
+   theme variables (defined in style.css) to restyle the whole app, and add
+   any rules you like. */
+
+:root {
+  /* e.g. --vg-primary: #7c3aed; --vg-topbar-bg: #111827; */
+}
+

package/tm/web/web/src/customise.js.frag

@@ -0,0 +1,30 @@
+// Project customisations (CREATE-ONCE — never overwritten by regeneration).
+// Your entry point for tailoring the generated app WITHOUT editing the
+// generated components. Register HTML / filter / action hooks here, and put
+// any CSS in ./custom.css (imported below).
+//
+// See src/hooks.js for the API. Hook points exposed by the components include:
+//   shell:topbar:right, shell:sidebar:top, shell:nav:items
+//   admin:list:toolbar, admin:list:items, admin:list:columns, admin:row:actions,
+//   admin:list:after, admin:form:fields, admin:form:extra, admin:form:after,
+//   admin:save:data, admin:save:after
+//   public:sections, auth:form:footer, settings:sections
+
+import './custom.css'
+import * as Hooks from './hooks.js'
+
+
+// Examples (uncomment and adapt to your model):
+//
+// Hooks.addHtml('shell:topbar:right', () => '<span class="vg-badge">Beta</span>')
+//
+// Hooks.addFilter('admin:list:items', (items, { canon }) =>
+//   'my/entity' === canon ? items.slice().reverse() : items)
+//
+// Hooks.addHtml('admin:row:actions', ({ canon, item }) =>
+//   'my/entity' === canon ? `<button data-do="${item.id}">Do</button>` : '')
+//
+// Hooks.addAction('admin:list:after', ({ root, canon }) => {
+//   // wire up any custom markup you injected above
+// })
+

package/tm/web/web/src/hooks.js.frag

@@ -0,0 +1,79 @@
+// Frontend customisation hooks. The backend lets you override ACTIONS with
+// Seneca message priors; this is the analogue for the generated components —
+// hooks for HTML, JS behaviour, and (via CSS variables + custom.css) styling.
+//
+// Register hooks from customise.js (a create-once file, so your changes are
+// never overwritten). Every generated component exposes named hook points; a
+// point is `<component>:<region>` (e.g. 'admin:row:actions', 'shell:topbar:right').
+//
+// Three kinds of hook:
+//   addHtml(point, ctx => 'markup')          inject/append HTML at a region
+//   addFilter(point, (value, ctx) => value)  transform a value (items, fields, actions)
+//   addAction(point, ctx => {...})           run side effects at a lifecycle point
+//
+// Components call html()/filter()/action() at their hook points. All are
+// synchronous and failure-isolated (a throwing hook can't break a render).
+
+const _html = {}
+const _filter = {}
+const _action = {}
+
+function addHtml(point, fn) {
+  (_html[point] = _html[point] || []).push(fn)
+}
+
+function addFilter(point, fn) {
+  (_filter[point] = _filter[point] || []).push(fn)
+}
+
+function addAction(point, fn) {
+  (_action[point] = _action[point] || []).push(fn)
+}
+
+// Concatenate the HTML contributed by every hook at `point`.
+function html(point, ctx) {
+  return (_html[point] || []).map((fn) => {
+    try {
+      return fn(ctx) || ''
+    }
+    catch (e) {
+      console.error('hook html failed:', point, e)
+      return ''
+    }
+  }).join('')
+}
+
+// Run `value` through every filter at `point`, in registration order.
+function filter(point, value, ctx) {
+  return (_filter[point] || []).reduce((v, fn) => {
+    try {
+      return fn(v, ctx)
+    }
+    catch (e) {
+      console.error('hook filter failed:', point, e)
+      return v
+    }
+  }, value)
+}
+
+// Fire every action hook at `point` (side effects only).
+function action(point, ctx) {
+  for (const fn of (_action[point] || [])) {
+    try {
+      fn(ctx)
+    }
+    catch (e) {
+      console.error('hook action failed:', point, e)
+    }
+  }
+}
+
+export {
+  addHtml,
+  addFilter,
+  addAction,
+  html,
+  filter,
+  action,
+}
+

package/tm/web/web/src/main.js.frag

@@ -1,10 +1,23 @@
-// Todo SPA entry: web components on a Seneca service bus (experimental).
-// No framework: each component is a custom element backed by a seneca
-// plugin (state), and all data flows are bus messages - aim:* messages
-// travel to the backend gateway via the seneca-browser fetch transport.
+// Todo SPA entry: web components on a Seneca service bus. No framework —
+// each component is a custom element; all data flows are bus messages, with
+// aim:* travelling to the backend gateway via the seneca-browser transport.
+// The UI is model-driven (see model.js): navigation, forms and entity
+// relationships are generated from /model.json.
 
+import './theme.css'
 import './style.css'
+import './theme.js'
 import './bus.js'
 import './cmp/auth.js'
+import './cmp/public.js'
 import './cmp/admin.js'
+import './cmp/settings.js'
+import './cmp/shell.js'
 import './cmp/app.js'
+
+// Custom entity views (ux:{view:'custom'}) — generated index of hand-coded views.
+import './views.js'
+
+// Project customisations: hook registrations + custom.css (create-once).
+import './customise.js'
+

package/tm/web/web/src/model.js.frag

@@ -0,0 +1,162 @@
+// Client-side model helpers. The compiled model (/model.json) drives the
+// entire UI: the entity menu, forms, and — via reference fields
+// (kind:String + a `ref` target canon) — the relationship graph. Nothing
+// here is entity-specific, so it works for any model.
+
+let _model = null
+let _loading = null
+
+const SYS_FIELDS = ['id', 'owner_id', 't_c', 't_m', 't_mh', 't_ch']
+
+async function loadModel() {
+  if (_model) {
+    return _model
+  }
+  if (!_loading) {
+    _loading = fetch('/model.json').then((r) => r.json()).then((m) => {
+      _model = m
+      return m
+    })
+  }
+  return _loading
+}
+
+function ent() {
+  return (_model && _model.main && _model.main.ent) || {}
+}
+
+function titleize(s) {
+  return String(s).charAt(0).toUpperCase() + String(s).slice(1).replace(/_/g, ' ')
+}
+
+// Browsable entities (the sys zone is internal — users are only reached via
+// reference pickers, never the entity menu).
+function entities() {
+  const out = []
+  const e = ent()
+  for (const zone of Object.keys(e)) {
+    if ('sys' === zone) {
+      continue
+    }
+    for (const name of Object.keys(e[zone])) {
+      // ux:{hide:true} keeps an entity out of the navigation entirely.
+      if (e[zone][name] && e[zone][name].ux && e[zone][name].ux.hide) {
+        continue
+      }
+      out.push({
+        zone,
+        name,
+        canon: zone + '/' + name,
+        label: titleize(name),
+        fields: e[zone][name].field || {},
+      })
+    }
+  }
+  return out
+}
+
+function fieldsOf(canon) {
+  const [z, n] = String(canon).split('/')
+  return (ent()[z] && ent()[z][n] && ent()[z][n].field) || {}
+}
+
+function labelOf(canon) {
+  return titleize(String(canon).split('/')[1] || canon)
+}
+
+// Reference fields on an entity: [{ field, target, label }].
+function refsOf(canon) {
+  const f = fieldsOf(canon)
+  return Object.keys(f)
+    .filter((k) => f[k] && f[k].ref)
+    .map((k) => ({ field: k, target: f[k].ref, label: f[k].label || titleize(k) }))
+}
+
+// Entities that reference `canon` (inverse / has-many): [{ canon, field, label }].
+function inverseRefs(canon) {
+  const out = []
+  const e = ent()
+  for (const zone of Object.keys(e)) {
+    if ('sys' === zone) {
+      continue
+    }
+    for (const name of Object.keys(e[zone])) {
+      const fc = zone + '/' + name
+      const f = e[zone][name].field || {}
+      for (const k of Object.keys(f)) {
+        if (f[k] && f[k].ref === canon) {
+          out.push({ canon: fc, field: k, label: titleize(name) })
+        }
+      }
+    }
+  }
+  return out
+}
+
+// The reference field pointing at proj/project (project scoping), or null.
+function projectRefField(canon) {
+  const f = fieldsOf(canon)
+  for (const k of Object.keys(f)) {
+    if (f[k] && 'proj/project' === f[k].ref) {
+      return k
+    }
+  }
+  return null
+}
+
+function isProjectScoped(canon) {
+  return 'proj/project' === canon || null != projectRefField(canon)
+}
+
+// The field to show as an entity's human label (name/title, else first
+// plain string field, else id).
+function labelField(canon) {
+  const f = fieldsOf(canon)
+  if (f.name) {
+    return 'name'
+  }
+  if (f.title) {
+    return 'title'
+  }
+  for (const k of Object.keys(f)) {
+    if (SYS_FIELDS.indexOf(k) < 0 && !f[k].ref && 'String' === f[k].kind) {
+      return k
+    }
+  }
+  return 'id'
+}
+
+// Visible (editable/listed) fields: exclude system bookkeeping fields.
+function displayFields(canon) {
+  const f = fieldsOf(canon)
+  return Object.keys(f).filter((k) => SYS_FIELDS.indexOf(k) < 0)
+}
+
+// Custom view: an entity may declare ux:{view:'custom'} to replace the
+// generic entity admin with a hand-coded component. Returns that component's
+// custom-element tag (vg-view-<zone>-<name>) or null for the generic admin.
+function customViewTag(canon) {
+  const [z, n] = String(canon).split('/')
+  const def = ent()[z] && ent()[z][n]
+  if (def && def.ux && 'custom' === def.ux.view) {
+    return 'vg-view-' + z + '-' + n
+  }
+  return null
+}
+
+export {
+  loadModel,
+  entities,
+  fieldsOf,
+  refsOf,
+  inverseRefs,
+  projectRefField,
+  isProjectScoped,
+  labelField,
+  labelOf,
+  displayFields,
+  customViewTag,
+  titleize,
+  SYS_FIELDS,
+}
+