@architecture-model/editable-metadata 0.0.0-stage → 0.1.0

package/Metadata.astro

@@ -0,0 +1,157 @@
+---
+import { existsSync, readFileSync } from 'node:fs'
+import config from 'virtual:editable-metadata/config'
+import { model } from './model.js'
+
+interface Props {
+  of: string
+  name: string
+}
+
+const types = ['text', 'number', 'date', 'url', 'boolean', 'select', 'multiselect']
+
+const { of, name } = Astro.props
+const fields = existsSync(config.fieldsFile) ? JSON.parse(readFileSync(config.fieldsFile, 'utf8')) : {}
+const field: { type: string; options?: string[] } = fields[name] ?? { type: 'text' }
+if (!types.includes(field.type)) {
+  throw new Error(`Unknown type "${field.type}" for metadata "${name}". Known types: ${types.join(', ')}`)
+}
+
+const valuesOf = (fqn: string) => [model.element(fqn).getMetadata(name) ?? []].flat()
+const values = valuesOf(of)
+const inUse = [...model.elements()].flatMap((element) => valuesOf(element.id))
+const options = [...new Set([...(field.options ?? []), ...inUse])]
+
+const text = field.type === 'boolean' && values.length ? (values[0] === 'true' ? 'Yes' : 'No') : values.join(', ')
+---
+
+{
+  import.meta.env.DEV ? (
+    <span
+      class="model-metadata not-content"
+      tabindex="0"
+      data-fqn={of}
+      data-key={name}
+      data-type={field.type}
+      data-values={JSON.stringify(values)}
+      data-options={JSON.stringify(options)}
+    >{text}</span>
+  ) : field.type === 'url' && text ? (
+    <a href={text}>{text}</a>
+  ) : (
+    text
+  )
+}
+
+<style is:global>
+  .model-metadata {
+    border-bottom: 1px dashed currentColor;
+    cursor: pointer;
+  }
+  .model-metadata:empty::before {
+    content: '—';
+  }
+  .model-metadata.editing {
+    border-bottom: none;
+    cursor: auto;
+  }
+  .model-metadata label {
+    margin-inline-end: 0.75em;
+  }
+</style>
+
+<script>
+  if (import.meta.env.DEV) {
+    const create = <K extends keyof HTMLElementTagNameMap>(tag: K, props: Partial<HTMLElementTagNameMap[K]> = {}) =>
+      Object.assign(document.createElement(tag), props)
+
+    const edit = (el: HTMLElement) => {
+      const type = el.dataset.type!
+      const values: string[] = JSON.parse(el.dataset.values!)
+      const options: string[] = JSON.parse(el.dataset.options!)
+      const display = el.textContent
+      const controls: HTMLElement[] = []
+      let read: () => string | string[]
+
+      if (type === 'multiselect') {
+        const boxes = options.map((option) =>
+          create('input', { type: 'checkbox', value: option, checked: values.includes(option) }),
+        )
+        for (const box of boxes) {
+          const label = create('label')
+          label.append(box, ` ${box.value}`)
+          controls.push(label)
+        }
+        read = () => boxes.filter((box) => box.checked).map((box) => box.value)
+      } else if (type === 'select') {
+        const select = create('select')
+        for (const option of ['', ...options]) select.append(create('option', { value: option, textContent: option }))
+        select.value = values[0] ?? ''
+        controls.push(select)
+        read = () => select.value
+      } else if (type === 'boolean') {
+        const box = create('input', { type: 'checkbox', checked: values[0] === 'true' })
+        controls.push(box)
+        read = () => String(box.checked)
+      } else {
+        const input = create('input', { type, value: values[0] ?? '' })
+        controls.push(input)
+        if (type === 'text') {
+          const list = create('datalist', { id: `model-metadata-${el.dataset.key}` })
+          for (const option of options) list.append(create('option', { value: option }))
+          input.setAttribute('list', list.id)
+          controls.push(list)
+        }
+        read = () => input.value.trim()
+      }
+
+      let dirty = false
+      let closed = false
+      // Checkboxes and labels don't reliably take focus on click, so leaving is detected by where the pointer goes.
+      const outside = (event: Event) => el.contains(event.target as Node) || close(true)
+      const close = async (save: boolean) => {
+        if (closed) return
+        closed = true
+        document.removeEventListener('pointerdown', outside)
+        const value = read()
+        el.classList.remove('editing')
+        el.textContent = display
+        if (!save || !dirty) return
+        const response = await fetch('/__model/metadata', {
+          method: 'POST',
+          body: JSON.stringify({ fqn: el.dataset.fqn, key: el.dataset.key, value }),
+        })
+        // On success the dev server sees the model change and reloads the page with the new value.
+        if (response.ok) el.textContent = [value].flat().join(', ')
+        else console.error(await response.text())
+      }
+
+      el.classList.add('editing')
+      el.replaceChildren(...controls)
+      el.querySelector<HTMLElement>('input, select')!.focus()
+      el.oninput = () => (dirty = true)
+      el.onchange = () => {
+        dirty = true
+        if (type === 'select' || type === 'boolean') close(true)
+      }
+      el.onkeydown = (event) => {
+        if (event.key === 'Enter') close(true)
+        if (event.key === 'Escape') close(false)
+      }
+      el.onfocusout = (event) => {
+        const next = event.relatedTarget as Node | null
+        if (next && !el.contains(next)) close(true)
+      }
+      document.addEventListener('pointerdown', outside)
+    }
+
+    const start = (event: Event) => {
+      const el = (event.target as HTMLElement).closest<HTMLElement>('.model-metadata:not(.editing)')
+      if (!el || (event instanceof KeyboardEvent && event.key !== 'Enter')) return
+      event.preventDefault()
+      edit(el)
+    }
+    document.addEventListener('click', start)
+    document.addEventListener('keydown', start)
+  }
+</script>

package/README.md

@@ -1,3 +1,87 @@
-# Temporary Holding Version
+# @architecture-model/editable-metadata
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Shows the metadata of [LikeC4](https://likec4.dev/) elements in [Astro](https://astro.build/) pages. In the dev server the values are click-to-edit and save back to the model; in the built site they are plain text.
+
+Made for repositories created with `npm create @architecture-model`, and works in any Astro site that has a LikeC4 model.
+
+## Install
+
+```bash
+npx astro add @architecture-model/editable-metadata
+```
+
+or by hand:
+
+```bash
+npm install @architecture-model/editable-metadata
+```
+
+```js
+// astro.config.mjs
+import editableMetadata from '@architecture-model/editable-metadata'
+
+export default defineConfig({
+  integrations: [editableMetadata()],
+})
+```
+
+## Use
+
+Give an element metadata in the model:
+
+```
+system = system 'Shop' {
+  metadata {
+    owner 'igor'
+  }
+}
+```
+
+and show it in a page:
+
+```mdx
+import Metadata from '@architecture-model/editable-metadata/Metadata.astro'
+
+Owner: <Metadata of="system" name="owner" />
+```
+
+`of` is the element's fully qualified name, `name` is the metadata key. Keep the component on the same line as its label.
+
+Run `npm run dev` and click the value to edit it. Enter or a click elsewhere saves, Escape cancels, and an empty value removes the key from the model.
+
+## Field types
+
+Without configuration every key is text. To give keys other types, create `model/metadata.json`:
+
+```json
+{
+  "lifecycle": { "type": "select", "options": ["experimental", "production", "deprecated"] },
+  "languages": { "type": "multiselect", "options": ["TypeScript", "Go", "Python"] },
+  "launched": { "type": "date" }
+}
+```
+
+| Type | Editor | Stored in the model as |
+| --- | --- | --- |
+| `text` | text input that suggests values already used for the key | string |
+| `number`, `date`, `url` | the browser's input for that type | string |
+| `boolean` | checkbox | `'true'` or `'false'`, shown as Yes or No |
+| `select` | dropdown | string |
+| `multiselect` | a checkbox per option | list of strings |
+
+The options of `select` and `multiselect` are the ones listed plus every value already in use in the model. A `url` is a link in the built site.
+
+## Options
+
+```js
+editableMetadata({
+  model: 'model', // folder with the .c4 files
+  fields: 'model/metadata.json', // field types
+})
+```
+
+Both paths are relative to the Astro project root.
+
+## How it saves
+
+The dev server gets an endpoint that rewrites the element's `metadata` block with [likec4-mutator](https://github.com/rebaseandpanic/likec4-mutator), leaving the rest of the file as it was. It only accepts requests from the page itself, and it does not exist in the built site.

package/editor.js

@@ -0,0 +1,52 @@
+import { globSync, readFileSync, writeFileSync } from 'node:fs'
+import { join } from 'node:path'
+
+export async function setMetadata(dir, { fqn, key, value }) {
+  const values = [value].flat().map((item) => (typeof item === 'string' ? item.trim() : item))
+  if (typeof fqn !== 'string' || !/^[A-Za-z_][\w-]*$/.test(key) || values.some((item) => typeof item !== 'string')) {
+    throw new Error('Expected { fqn, key, value } with an identifier as the key and a string or list of strings as the value')
+  }
+  const present = values.filter(Boolean)
+  const stored = present.length ? (Array.isArray(value) ? present : present[0]) : null
+
+  const sources = Object.fromEntries(
+    globSync('**/*.c4', { cwd: dir }).map((file) => [file, readFileSync(join(dir, file), 'utf8')]),
+  )
+  const { LikeC4Mutator } = await import('likec4-mutator')
+  const mutator = LikeC4Mutator.fromFiles(sources)
+  const { changedFiles } = mutator.updateElement(fqn, { metadata: { [key]: stored } })
+  const updated = mutator.serialize()
+  for (const file of changedFiles) writeFileSync(join(dir, file), updated[file])
+}
+
+export const editor = ({ modelDir, fieldsFile }) => ({
+  name: 'editable-metadata-editor',
+  apply: 'serve',
+  configureServer(server) {
+    // Pages load the model once per module evaluation, so a changed model has to evict what was evaluated.
+    server.watcher.add([modelDir, fieldsFile])
+    server.watcher.on('change', (file) => {
+      if (!file.endsWith('.c4') && file !== fieldsFile) return
+      for (const environment of Object.values(server.environments)) environment.moduleGraph.invalidateAll()
+      server.ws.send({ type: 'full-reload' })
+    })
+
+    server.middlewares.use('/__model/metadata', async (req, res) => {
+      // The endpoint writes to disk, so a page from another site must not be able to call it.
+      if (req.method !== 'POST' || req.headers['sec-fetch-site'] !== 'same-origin') {
+        res.statusCode = 403
+        return res.end()
+      }
+      try {
+        let body = ''
+        for await (const chunk of req) body += chunk
+        await setMetadata(modelDir, JSON.parse(body))
+        res.statusCode = 204
+        res.end()
+      } catch (error) {
+        res.statusCode = 400
+        res.end(error.message)
+      }
+    })
+  },
+})

package/index.js

@@ -0,0 +1,31 @@
+import { resolve } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { editor } from './editor.js'
+
+const name = '@architecture-model/editable-metadata'
+const virtual = 'virtual:editable-metadata/config'
+
+export default function editableMetadata({ model = 'model', fields = 'model/metadata.json' } = {}) {
+  return {
+    name,
+    hooks: {
+      'astro:config:setup': ({ config, updateConfig }) => {
+        const root = fileURLToPath(config.root)
+        const paths = { modelDir: resolve(root, model), fieldsFile: resolve(root, fields) }
+        updateConfig({
+          vite: {
+            ssr: { noExternal: [name] },
+            plugins: [
+              {
+                name: 'editable-metadata-config',
+                resolveId: (id) => (id === virtual ? `\0${virtual}` : undefined),
+                load: (id) => (id === `\0${virtual}` ? `export default ${JSON.stringify(paths)}` : undefined),
+              },
+              editor(paths),
+            ],
+          },
+        })
+      },
+    },
+  }
+}

package/model.js

@@ -0,0 +1,6 @@
+import { LikeC4 } from 'likec4'
+import config from 'virtual:editable-metadata/config'
+
+const likec4 = await LikeC4.fromWorkspace(config.modelDir, { throwIfInvalid: true })
+
+export const model = await likec4.computedModel()

package/package.json

@@ -1,6 +1,43 @@
 {
   "name": "@architecture-model/editable-metadata",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Show LikeC4 element metadata in Astro pages and edit it in place in the dev server",
+  "keywords": [
+    "astro-integration",
+    "astro-component",
+    "likec4"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Morozzzko/architecture-model-template.git",
+    "directory": "addons/editable-metadata"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "exports": {
+    ".": "./index.js",
+    "./Metadata.astro": "./Metadata.astro"
+  },
+  "files": [
+    "index.js",
+    "editor.js",
+    "model.js",
+    "Metadata.astro"
+  ],
+  "engines": {
+    "node": ">=22.22.3"
+  },
+  "scripts": {
+    "test": "node --test"
+  },
+  "peerDependencies": {
+    "astro": ">=7",
+    "likec4": "^1.59.4"
+  },
+  "dependencies": {
+    "likec4-mutator": "0.9.0"
+  }
+}