@architecture-model/editable-metadata 0.2.0 → 0.3.0

package/Derived.astro

@@ -0,0 +1,17 @@
+---
+import type { LikeC4Model } from 'likec4/model'
+import { model } from './model.js'
+
+type Value = string | number | boolean | null | undefined | Array<string | number>
+
+interface Props {
+  of: string
+  value: (element: LikeC4Model.Element, model: LikeC4Model) => Value
+}
+
+const { of, value } = Astro.props
+const result = value(model.element(of), model)
+const text = typeof result === 'boolean' ? (result ? 'Yes' : 'No') : [result ?? []].flat().join(', ')
+---
+
+{text}

package/Editor.jsx

@@ -4,17 +4,25 @@ 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 }) })
+const post = async (change) => {
+  const response = await fetch('/__model/element', { method: 'POST', body: JSON.stringify(change) })
   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))
+const linksOf = (links) =>
+  links
+    .map(({ url, label }) => ({ url: url.trim(), label: label?.trim() }))
+    .filter((link) => link.url)
+    .map(({ url, label }) => (label ? { url, label } : { url }))
+const keyOf = (list) => JSON.stringify(list.map((item) => JSON.stringify(item)).sort())
+const shown = (type, values, labelOf) =>
+  type === 'links' ? values.map((link) => link.label || link.url).join(', ') : values.map(labelOf).join(', ')
 
 function Options({ type, options, chosen, onChoose, onClear }) {
   const [query, setQuery] = useState('')
   const typed = query.trim()
+  const known = options.some((option) => option.value === typed || option.label === typed)
 
   return (
     <Command className="em-command" loop>
@@ -27,12 +35,18 @@ function Options({ type, options, chosen, onChoose, onClear }) {
       <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
+            key={option.value}
+            value={option.value}
+            keywords={[option.label]}
+            className="em-item"
+            onSelect={() => onChoose(option.value)}
+          >
+            <span className="em-check">{chosen.includes(option.value) ? '✓' : ''}</span>
+            {option.label}
           </Command.Item>
         ))}
-        {type === 'text' && typed && !options.includes(typed) && (
+        {type === 'text' && typed && !known && (
           <Command.Item value={typed} className="em-item" onSelect={() => (setQuery(''), onChoose(typed))}>
             <span className="em-check">+</span>
             Add “{typed}”
@@ -49,37 +63,85 @@ function Options({ type, options, chosen, onChoose, onClear }) {
   )
 }
 
-export default function Editor({ fqn, name, type, values: initial, options: listed }) {
+function Links({ links, onChange, onSave }) {
+  const set = (index, field) => (event) =>
+    onChange(links.map((link, at) => (at === index ? { ...link, [field]: event.target.value } : link)))
+  const onKeyDown = (event) => event.key === 'Enter' && (event.preventDefault(), onSave())
+
+  return (
+    <div className="em-command">
+      {links.map((link, index) => (
+        <div className="em-link" key={index}>
+          <input
+            className="em-input"
+            type="url"
+            placeholder="https://…"
+            aria-label="URL"
+            value={link.url}
+            onChange={set(index, 'url')}
+            onKeyDown={onKeyDown}
+            autoFocus={index === links.length - 1}
+          />
+          <input
+            className="em-input"
+            placeholder="Label"
+            aria-label="Label"
+            value={link.label ?? ''}
+            onChange={set(index, 'label')}
+            onKeyDown={onKeyDown}
+          />
+          <button
+            type="button"
+            className="em-remove"
+            aria-label={`Remove ${link.url || 'link'}`}
+            onClick={() => onChange(links.filter((_, at) => at !== index))}
+          >
+            ×
+          </button>
+        </div>
+      ))}
+      <button type="button" className="em-item em-muted em-clear" onClick={() => onChange([...links, { url: '', label: '' }])}>
+        <span className="em-check">+</span>
+        Add link
+      </button>
+    </div>
+  )
+}
+
+export default function Editor({ fqn, name, property = false, 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 labels = new Map(listed.map((option) => [option.value, option.label]))
+  const labelOf = (value) => labels.get(value) ?? value
+  const options = [...listed, ...draft.filter((value) => !labels.has(value)).map((value) => ({ value, label: value }))]
   const listedType = ['select', 'multiselect', 'text'].includes(type)
 
   const save = (value) => {
     setOpen(false)
-    const next = listOf(value)
-    if (same(next, values)) return
+    const next = type === 'links' ? linksOf(value) : listOf(value)
+    if (keyOf(next) === keyOf(values)) return
     const previous = values
     setValues(next)
     setError('')
-    post(fqn, name, value).catch((failure) => {
+    post({ fqn, [property ? 'property' : 'key']: name, value: type === 'links' ? next : value }).catch((failure) => {
       setValues(previous)
       setError(failure.message)
     })
   }
+  const saveDraft = () => save(type === 'multiselect' || type === 'links' ? draft : (draft[0] ?? '').trim())
 
-  // A multiselect and the plain inputs keep a draft and save it on close, unless Escape closed them.
+  // Everything but a select and text keeps a draft and saves it on close, unless Escape closed it.
   // A multiselect can't save per toggle because every save reloads the page.
   const onOpenChange = (next) => {
     if (next) {
       cancelled.current = false
-      setDraft(values)
+      setDraft(type === 'links' && !values.length ? [{ url: '', label: '' }] : values)
       return setOpen(true)
     }
-    if (!cancelled.current && (type === 'multiselect' || !listedType)) return save(type === 'multiselect' ? draft : draft[0] ?? '')
+    if (!cancelled.current && (type === 'multiselect' || !listedType)) return saveDraft()
     setOpen(false)
   }
   const onChoose = (option) => {
@@ -87,7 +149,7 @@ export default function Editor({ fqn, name, type, values: initial, options: list
     setDraft(draft.includes(option) ? draft.filter((value) => value !== option) : [...draft, option])
   }
 
-  const label = `${name}: ${values.join(', ') || 'not set'}`
+  const text = shown(type, values, labelOf)
   const problem = error && (
     <span className="em-error" role="alert" title={error}>
       {' '}
@@ -111,34 +173,51 @@ export default function Editor({ fqn, name, type, values: initial, options: list
     )
   }
 
+  const editor = listedType ? (
+    <Options type={type} options={options} chosen={draft} onChoose={onChoose} onClear={() => save('')} />
+  ) : type === 'links' ? (
+    <Links links={draft} onChange={setDraft} onSave={saveDraft} />
+  ) : type === 'textarea' ? (
+    <div className="em-command">
+      <textarea
+        className="em-input em-textarea"
+        aria-label={name}
+        value={draft[0] ?? ''}
+        onChange={(event) => setDraft([event.target.value])}
+        onKeyDown={(event) => event.key === 'Enter' && (event.metaKey || event.ctrlKey) && saveDraft()}
+        autoFocus
+      />
+      <p className="em-hint">⌘ or Ctrl + Enter or a click outside saves. Escape cancels. Markdown works.</p>
+    </div>
+  ) : (
+    <div className="em-command">
+      <input
+        className="em-input"
+        type={type === 'line' ? 'text' : type}
+        aria-label={name}
+        value={draft[0] ?? ''}
+        onChange={(event) => setDraft([event.target.value])}
+        onKeyDown={(event) => event.key === 'Enter' && (event.preventDefault(), saveDraft())}
+        autoFocus
+      />
+      <p className="em-hint">Enter or a click outside saves. Escape cancels.{name === 'title' ? '' : ' Empty clears it.'}</p>
+    </div>
+  )
+
   return (
     <>
       <Popover.Root open={open} onOpenChange={onOpenChange}>
-        <Popover.Trigger className="em-value" aria-label={`Edit ${label}`}>
-          {values.join(', ') || '—'}
+        <Popover.Trigger className={type === 'textarea' ? 'em-value em-multiline' : 'em-value'} aria-label={`Edit ${name}: ${text || 'not set'}`}>
+          {text || '—'}
         </Popover.Trigger>
         <Popover.Portal>
           <Popover.Content
-            className="em-popover"
+            className={type === 'textarea' || type === 'links' ? 'em-popover em-wide' : '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>
-            )}
+            {editor}
           </Popover.Content>
         </Popover.Portal>
       </Popover.Root>

package/Metadata.astro

@@ -9,21 +9,32 @@ interface Props {
   name: string
 }
 
+type Option = string | { value: string; label?: 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' }
+const field: { type: string; options?: Option[] } = 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 listed = (field.options ?? []).map((option) =>
+  typeof option === 'string' ? { value: option, label: option } : { value: option.value, label: option.label ?? option.value },
+)
+const labels = new Map(listed.map((option) => [option.value, option.label]))
+const inUse = [...new Set([...model.elements()].flatMap((element) => valuesOf(element.id)))]
+const options = [...listed, ...inUse.filter((value) => !labels.has(value)).map((value) => ({ value, label: value }))]
 
-const text = field.type === 'boolean' && values.length ? (values[0] === 'true' ? 'Yes' : 'No') : values.join(', ')
+const text =
+  field.type === 'boolean' && values.length
+    ? values[0] === 'true'
+      ? 'Yes'
+      : 'No'
+    : values.map((value) => labels.get(value) ?? value).join(', ')
 ---
 
 {

package/Property.astro

@@ -0,0 +1,38 @@
+---
+import Editor from './Editor.jsx'
+import { model } from './model.js'
+
+interface Props {
+  of: string
+  name: 'title' | 'summary' | 'description' | 'technology' | 'links'
+}
+
+const types = { title: 'line', technology: 'line', summary: 'textarea', description: 'textarea', links: 'links' }
+
+const { of, name } = Astro.props
+const type = types[name]
+if (!type) throw new Error(`Unknown property "${name}". Known properties: ${Object.keys(types).join(', ')}`)
+
+const element = model.element(of)
+const rich = name === 'summary' || name === 'description' ? element[name] : null
+const links = element.links.map(({ url, title }) => (title ? { url, label: title } : { url }))
+const values =
+  name === 'links' ? links : [rich ? (rich.$source?.md ?? rich.$source?.txt ?? '') : (element[name] ?? '')].filter(Boolean)
+---
+
+{
+  import.meta.env.DEV ? (
+    <Editor client:load fqn={of} name={name} property type={type} values={values} />
+  ) : name === 'links' ? (
+    links.map((link, index) => (
+      <>
+        {index > 0 && ', '}
+        <a href={link.url}>{link.label ?? link.url}</a>
+      </>
+    ))
+  ) : rich?.isMarkdown ? (
+    <Fragment set:html={rich.html} />
+  ) : (
+    values.join('')
+  )
+}

package/README.md

@@ -1,6 +1,6 @@
 # @architecture-model/editable-metadata
 
-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.
+Shows the metadata and properties 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.
 
@@ -73,6 +73,47 @@ Without configuration every key is text. To give keys other types, create `model
 
 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.
 
+An option can have a label that pages and editors show in place of the stored value:
+
+```json
+{
+  "owners": { "type": "multiselect", "options": [{ "value": "igor", "label": "Igor Morozov" }, "platform-team"] }
+}
+```
+
+## Derived values
+
+A value that follows from the model, such as whether an external system calls you back, is asked in the page instead of stored in the model. Define a function of the [element](https://likec4.dev/tooling/model-api/) and the model, and show its answer with `Derived`:
+
+```mdx
+import Derived from '@architecture-model/editable-metadata/Derived.astro'
+
+export const ours = (element, model) => element.id === 'shop' || element.isDescendantOf(model.element('shop'))
+export const callsBack = (element, model) => [...element.outgoing()].some(({ target }) => ours(target, model))
+
+Payments calls us back: <Derived of="payments" value={callsBack} />
+```
+
+A function returns a string, a number, a list, or a boolean, shown as Yes or No. A derived value is never editable.
+
+## Properties
+
+`Property` shows and edits an element's own `title`, `summary`, `description`, `technology` or `links`:
+
+```mdx
+import Property from '@architecture-model/editable-metadata/Property.astro'
+
+<Property of="system" name="description" />
+```
+
+| Property | Editor | In the built site |
+| --- | --- | --- |
+| `title`, `technology` | one-line input | text |
+| `summary`, `description` | text area; ⌘ or Ctrl + Enter saves, line breaks are saved as a Markdown string | Markdown rendered as HTML |
+| `links` | a URL and a label per row | links |
+
+A title can't be emptied. Links replace the element's own links, and a row without a URL is dropped.
+
 ## Options
 
 ```js
@@ -86,4 +127,4 @@ 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.
+The dev server gets an endpoint that rewrites the edited metadata key or property of the element 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

@@ -3,6 +3,9 @@
   cursor: pointer;
   border-bottom: 1px dashed currentColor;
 }
+.em-multiline {
+  white-space: pre-line;
+}
 .em-value:focus-visible {
   outline: 2px solid var(--sl-color-accent, Highlight);
   outline-offset: 2px;
@@ -28,6 +31,35 @@
   line-height: 1.4;
 }
 
+.em-wide {
+  width: min(32rem, calc(100vw - 2rem));
+  max-width: none;
+}
+
+.em-textarea {
+  min-height: 8rem;
+  resize: vertical;
+}
+
+.em-link {
+  display: grid;
+  grid-template-columns: 3fr 2fr auto;
+  align-items: center;
+}
+.em-link .em-input {
+  min-width: 0;
+}
+.em-remove {
+  all: unset;
+  padding: 0 0.5rem;
+  cursor: pointer;
+  color: var(--em-muted);
+}
+.em-remove:hover,
+.em-remove:focus-visible {
+  color: inherit;
+}
+
 .em-command {
   display: flex;
   flex-direction: column;

package/editor.js

@@ -1,6 +1,20 @@
+import { randomUUID } from 'node:crypto'
 import { globSync, readFileSync, writeFileSync } from 'node:fs'
 import { join } from 'node:path'
 
+export const properties = ['title', 'summary', 'description', 'technology', 'links']
+
+const update = async (dir, fqn, patch, rewrite = (text) => text) => {
+  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, patch)
+  const updated = mutator.serialize()
+  for (const file of changedFiles) writeFileSync(join(dir, file), rewrite(updated[file]))
+}
+
 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')) {
@@ -8,15 +22,31 @@ export async function setMetadata(dir, { fqn, key, value }) {
   }
   const present = values.filter(Boolean)
   const stored = present.length ? (Array.isArray(value) ? present : present[0]) : null
+  await update(dir, fqn, { metadata: { [key]: stored } })
+}
 
-  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])
+// likec4-mutator writes a summary or description on one line, so a multi-line one goes in as a token and is swapped for a Markdown string.
+const asMarkdown = (token, value) => (text) =>
+  text.replace(new RegExp(`^([ \\t]*)(.*)'${token}'`, 'm'), (_, indent, before) => {
+    const lines = value.split(/\r?\n/).map((line) => line && `${indent}  ${line.replace(/\\/g, '\\\\').replace(/'(?=')/g, "\\'")}`)
+    return `${indent}${before}'''\n${lines.join('\n')}\n${indent}'''`
+  })
+
+export async function setProperty(dir, { fqn, property, value }) {
+  if (typeof fqn !== 'string' || !properties.includes(property)) {
+    throw new Error(`Expected { fqn, property, value } with one of ${properties.join(', ')} as the property`)
+  }
+  if (property === 'links') {
+    const valid = Array.isArray(value) && value.every((link) => /^\S+$/.test(link?.url) && ['string', 'undefined'].includes(typeof link.label))
+    if (!valid) throw new Error('Expected links as a list of { url, label } with no spaces in the url')
+    return update(dir, fqn, { links: value.map(({ url, label }) => (label?.trim() ? { url, label: label.trim() } : { url })) })
+  }
+  if (typeof value !== 'string') throw new Error(`Expected ${property} as a string`)
+  const text = value.trim()
+  if (property === 'title' && !text) throw new Error('An element needs a title')
+  if (!/\n/.test(text) || ['title', 'technology'].includes(property)) return update(dir, fqn, { [property]: text })
+  const token = `editable${randomUUID().replaceAll('-', '')}`
+  await update(dir, fqn, { [property]: token }, asMarkdown(token, text))
 }
 
 export const editor = ({ modelDir, fieldsFile }) => ({
@@ -31,7 +61,7 @@ export const editor = ({ modelDir, fieldsFile }) => ({
       server.ws.send({ type: 'full-reload' })
     })
 
-    server.middlewares.use('/__model/metadata', async (req, res) => {
+    server.middlewares.use('/__model/element', 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
@@ -40,7 +70,8 @@ export const editor = ({ modelDir, fieldsFile }) => ({
       try {
         let body = ''
         for await (const chunk of req) body += chunk
-        await setMetadata(modelDir, JSON.parse(body))
+        const change = JSON.parse(body)
+        await ('property' in change ? setProperty : setMetadata)(modelDir, change)
         res.statusCode = 204
         res.end()
       } catch (error) {

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@architecture-model/editable-metadata",
-  "version": "0.2.0",
-  "description": "Show LikeC4 element metadata in Astro pages and edit it in place in the dev server",
+  "version": "0.3.0",
+  "description": "Show LikeC4 element metadata and properties in Astro pages and edit them in place in the dev server",
   "keywords": [
     "astro-integration",
     "astro-component",
@@ -19,13 +19,17 @@
   "type": "module",
   "exports": {
     ".": "./index.js",
-    "./Metadata.astro": "./Metadata.astro"
+    "./Metadata.astro": "./Metadata.astro",
+    "./Property.astro": "./Property.astro",
+    "./Derived.astro": "./Derived.astro"
   },
   "files": [
     "index.js",
     "editor.js",
     "model.js",
     "Metadata.astro",
+    "Property.astro",
+    "Derived.astro",
     "Editor.jsx",
     "NoEditor.jsx",
     "editor.css"