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

package/Editor.jsx

@@ -0,0 +1,148 @@
+import * as Popover from '@radix-ui/react-popover'
+import * as Switch from '@radix-ui/react-switch'
+import { Command } from 'cmdk'
+import { useRef, useState } from 'react'
+import './editor.css'
+
+const post = async (fqn, key, value) => {
+  const response = await fetch('/__model/metadata', { method: 'POST', body: JSON.stringify({ fqn, key, value }) })
+  if (!response.ok) throw new Error(await response.text())
+}
+
+const listOf = (value) => [value].flat().filter(Boolean)
+const same = (a, b) => a.length === b.length && a.every((value) => b.includes(value))
+
+function Options({ type, options, chosen, onChoose, onClear }) {
+  const [query, setQuery] = useState('')
+  const typed = query.trim()
+
+  return (
+    <Command className="em-command" loop>
+      <Command.Input
+        className="em-input"
+        value={query}
+        onValueChange={setQuery}
+        placeholder={type === 'text' ? 'Search or add a value…' : 'Search…'}
+      />
+      <Command.List className="em-list">
+        <Command.Empty className="em-empty">No options</Command.Empty>
+        {options.map((option) => (
+          <Command.Item key={option} value={option} className="em-item" onSelect={() => onChoose(option)}>
+            <span className="em-check">{chosen.includes(option) ? '✓' : ''}</span>
+            {option}
+          </Command.Item>
+        ))}
+        {type === 'text' && typed && !options.includes(typed) && (
+          <Command.Item value={typed} className="em-item" onSelect={() => (setQuery(''), onChoose(typed))}>
+            <span className="em-check">+</span>
+            Add “{typed}”
+          </Command.Item>
+        )}
+      </Command.List>
+      {type !== 'multiselect' && chosen.length > 0 && (
+        <button type="button" className="em-item em-muted em-clear" onClick={onClear}>
+          <span className="em-check" />
+          Clear
+        </button>
+      )}
+    </Command>
+  )
+}
+
+export default function Editor({ fqn, name, type, values: initial, options: listed }) {
+  const [values, setValues] = useState(initial)
+  const [open, setOpen] = useState(false)
+  const [draft, setDraft] = useState(initial)
+  const [error, setError] = useState('')
+  const cancelled = useRef(false)
+  const options = [...new Set([...listed, ...draft])]
+  const listedType = ['select', 'multiselect', 'text'].includes(type)
+
+  const save = (value) => {
+    setOpen(false)
+    const next = listOf(value)
+    if (same(next, values)) return
+    const previous = values
+    setValues(next)
+    setError('')
+    post(fqn, name, value).catch((failure) => {
+      setValues(previous)
+      setError(failure.message)
+    })
+  }
+
+  // A multiselect and the plain inputs keep a draft and save it on close, unless Escape closed them.
+  // A multiselect can't save per toggle because every save reloads the page.
+  const onOpenChange = (next) => {
+    if (next) {
+      cancelled.current = false
+      setDraft(values)
+      return setOpen(true)
+    }
+    if (!cancelled.current && (type === 'multiselect' || !listedType)) return save(type === 'multiselect' ? draft : draft[0] ?? '')
+    setOpen(false)
+  }
+  const onChoose = (option) => {
+    if (type !== 'multiselect') return save(option)
+    setDraft(draft.includes(option) ? draft.filter((value) => value !== option) : [...draft, option])
+  }
+
+  const label = `${name}: ${values.join(', ') || 'not set'}`
+  const problem = error && (
+    <span className="em-error" role="alert" title={error}>
+      {' '}
+      not saved
+    </span>
+  )
+
+  if (type === 'boolean') {
+    return (
+      <>
+        <Switch.Root
+          className="em-switch"
+          checked={values[0] === 'true'}
+          onCheckedChange={(checked) => save(String(checked))}
+          aria-label={name}
+        >
+          <Switch.Thumb className="em-thumb" />
+        </Switch.Root>
+        {problem}
+      </>
+    )
+  }
+
+  return (
+    <>
+      <Popover.Root open={open} onOpenChange={onOpenChange}>
+        <Popover.Trigger className="em-value" aria-label={`Edit ${label}`}>
+          {values.join(', ') || '—'}
+        </Popover.Trigger>
+        <Popover.Portal>
+          <Popover.Content
+            className="em-popover"
+            align="start"
+            sideOffset={6}
+            onEscapeKeyDown={() => (cancelled.current = true)}
+          >
+            {listedType ? (
+              <Options type={type} options={options} chosen={draft} onChoose={onChoose} onClear={() => save('')} />
+            ) : (
+              <div className="em-command">
+                <input
+                  className="em-input"
+                  type={type}
+                  value={draft[0] ?? ''}
+                  onChange={(event) => setDraft([event.target.value])}
+                  onKeyDown={(event) => event.key === 'Enter' && (event.preventDefault(), save(draft[0]?.trim() ?? ''))}
+                  autoFocus
+                />
+                <p className="em-hint">Enter or a click outside saves. Escape cancels. Empty removes the key.</p>
+              </div>
+            )}
+          </Popover.Content>
+        </Popover.Portal>
+      </Popover.Root>
+      {problem}
+    </>
+  )
+}

package/LICENSE

@@ -0,0 +1,7 @@
+Copyright 2020 Igor S. Morozov <igor@morozov.is>
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/Metadata.astro

@@ -0,0 +1,37 @@
+---
+import { existsSync, readFileSync } from 'node:fs'
+import config from 'virtual:editable-metadata/config'
+import Editor from './Editor.jsx'
+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 ? (
+    <Editor client:load fqn={of} name={name} type={field.type} values={values} options={options} />
+  ) : field.type === 'url' && text ? (
+    <a href={text}>{text}</a>
+  ) : (
+    text
+  )
+}

package/NoEditor.jsx

@@ -0,0 +1,3 @@
+export default function NoEditor() {
+  return null
+}

package/README.md

@@ -1,3 +1,89 @@
-# 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 @astrojs/react react react-dom
+```
+
+```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. A select saves the option you choose, text saves the value you choose or add, and a multiselect, number, date or url saves when its editor closes. Escape closes without saving, and Clear or an empty value removes the key from the model.
+
+The editors are React components built on [Radix](https://www.radix-ui.com/) and [cmdk](https://cmdk.paco.me/). The addon adds Astro's React integration if the site doesn't have it, and the built site contains none of the editor code.
+
+## 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` | searchable list of the values already used for the key, and adds what you type | string |
+| `number`, `date`, `url` | the browser's input for that type | string |
+| `boolean` | switch | `'true'` or `'false'`, shown as Yes or No |
+| `select` | searchable list of the options | string |
+| `multiselect` | searchable list of the options, several can be checked | 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.css

@@ -0,0 +1,131 @@
+.em-value {
+  all: unset;
+  cursor: pointer;
+  border-bottom: 1px dashed currentColor;
+}
+.em-value:focus-visible {
+  outline: 2px solid var(--sl-color-accent, Highlight);
+  outline-offset: 2px;
+  border-radius: 2px;
+}
+
+.em-popover {
+  --em-bg: var(--sl-color-bg, Canvas);
+  --em-border: var(--sl-color-hairline-light, #d4d4d8);
+  --em-hover: var(--sl-color-gray-6, #f4f4f5);
+  --em-muted: var(--sl-color-gray-3, #71717a);
+  z-index: 100;
+  min-width: 14rem;
+  max-width: 20rem;
+  padding: 0.25rem;
+  border: 1px solid var(--em-border);
+  border-radius: 0.5rem;
+  background: var(--em-bg);
+  color: var(--sl-color-text, CanvasText);
+  box-shadow: 0 10px 30px -10px rgb(0 0 0 / 0.25);
+  font-family: var(--sl-font, system-ui, sans-serif);
+  font-size: var(--sl-text-sm, 0.875rem);
+  line-height: 1.4;
+}
+
+.em-command {
+  display: flex;
+  flex-direction: column;
+  margin: 0;
+}
+
+.em-input {
+  font: inherit;
+  color: inherit;
+  background: transparent;
+  border: none;
+  border-bottom: 1px solid var(--em-border);
+  padding: 0.5rem 0.5rem 0.6rem;
+  outline: none;
+}
+.em-input::placeholder {
+  color: var(--em-muted);
+}
+
+.em-list {
+  max-height: 16rem;
+  overflow-y: auto;
+  padding-top: 0.25rem;
+}
+
+.em-item {
+  display: flex;
+  align-items: center;
+  gap: 0.5rem;
+  padding: 0.375rem 0.5rem;
+  border-radius: 0.25rem;
+  cursor: pointer;
+  user-select: none;
+}
+.em-item[data-selected='true'],
+.em-clear:hover,
+.em-clear:focus-visible {
+  background: var(--em-hover);
+}
+.em-clear {
+  all: unset;
+  display: flex;
+  align-items: center;
+  gap: 0.5rem;
+  margin-top: 0.25rem;
+  padding: 0.375rem 0.5rem;
+  border-top: 1px solid var(--em-border);
+  border-radius: 0 0 0.25rem 0.25rem;
+  cursor: pointer;
+}
+.em-error {
+  color: var(--sl-color-red, #dc2626);
+  font-size: 0.85em;
+}
+.em-muted,
+.em-empty,
+.em-hint {
+  color: var(--em-muted);
+}
+.em-empty,
+.em-hint {
+  margin: 0;
+  padding: 0.5rem;
+}
+
+.em-check {
+  width: 1rem;
+  text-align: center;
+  color: var(--sl-color-accent, currentColor);
+}
+
+.em-switch {
+  all: unset;
+  position: relative;
+  display: inline-block;
+  vertical-align: middle;
+  width: 2.25rem;
+  height: 1.25rem;
+  border-radius: 999px;
+  background: var(--sl-color-gray-5, #d4d4d8);
+  cursor: pointer;
+}
+.em-switch[data-state='checked'] {
+  background: var(--sl-color-accent, #2563eb);
+}
+.em-switch:focus-visible {
+  outline: 2px solid var(--sl-color-accent, Highlight);
+  outline-offset: 2px;
+}
+.em-thumb {
+  display: block;
+  width: 1rem;
+  height: 1rem;
+  margin: 0.125rem;
+  border-radius: 999px;
+  background: white;
+  transition: transform 100ms;
+}
+.em-thumb[data-state='checked'] {
+  transform: translateX(1rem);
+}

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,48 @@
+import react from '@astrojs/react'
+import { dirname, 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'
+const here = dirname(fileURLToPath(import.meta.url))
+const editorFile = resolve(here, 'Editor.jsx')
+
+// The editor only runs in the dev server, so the build gets an empty component instead of Radix and cmdk.
+const withoutEditor = {
+  name: 'editable-metadata-no-editor',
+  enforce: 'pre',
+  resolveId: (id, importer) => {
+    const path = id.split('?')[0]
+    const absolute = path.startsWith('.') && importer ? resolve(dirname(importer.split('?')[0]), path) : path
+    return absolute === editorFile ? resolve(here, 'NoEditor.jsx') : undefined
+  },
+}
+
+export default function editableMetadata({ model = 'model', fields = 'model/metadata.json' } = {}) {
+  return {
+    name,
+    hooks: {
+      'astro:config:setup': ({ config, command, updateConfig }) => {
+        const root = fileURLToPath(config.root)
+        const paths = { modelDir: resolve(root, model), fieldsFile: resolve(root, fields) }
+        const hasReact = config.integrations.some((integration) => integration.name === '@astrojs/react')
+        updateConfig({
+          integrations: hasReact ? [] : [react()],
+          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),
+              command === 'build' && withoutEditor,
+            ],
+          },
+        })
+      },
+    },
+  }
+}

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,52 @@
 {
   "name": "@architecture-model/editable-metadata",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.2.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",
+    "Editor.jsx",
+    "NoEditor.jsx",
+    "editor.css"
+  ],
+  "engines": {
+    "node": ">=22.22.3"
+  },
+  "peerDependencies": {
+    "@astrojs/react": ">=7",
+    "astro": ">=7",
+    "likec4": "^1.59.4",
+    "react": ">=19",
+    "react-dom": ">=19"
+  },
+  "dependencies": {
+    "@radix-ui/react-popover": "^1.3.1",
+    "@radix-ui/react-switch": "^1.4.1",
+    "cmdk": "^1.1.1",
+    "likec4-mutator": "0.9.0"
+  },
+  "scripts": {
+    "test": "node --test"
+  }
 }