vowel 0.6.4 → 0.7.0-beta.0

package/plugins/html/editor/ingest.js

@@ -0,0 +1,339 @@
+// HTML -> Svedit document.
+//
+// #content is the source of truth: this walks the rendered DOM and builds
+// the Svedit node graph from it. Nothing here parses markdown.
+//
+// The tag table is a closed allowlist. An element it does not recognise
+// fails the whole ingest rather than being guessed at, because a wrong
+// guess round-trips to markdown that silently replaces the author's
+// content on save.
+
+import { globParams, globDirective } from "./directives.js"
+
+const TEXT_NODE = 3
+const ELEMENT_NODE = 1
+
+// Inline elements that become marks. Marks are ranges over a plain string,
+// so everything below collapses to offsets during the inline walk.
+const MARK_TYPES = {
+  STRONG: "strong",
+  B: "strong",
+  EM: "emphasis",
+  I: "emphasis",
+  CODE: "inline_code",
+  MARK: "highlight",
+  DEL: "strikethrough",
+  S: "strikethrough",
+  A: "link"
+}
+
+const HEADING_LEVELS = {
+  H1: 1,
+  H2: 2,
+  H3: 3,
+  H4: 4,
+  H5: 5,
+  H6: 6
+}
+
+/** @param {Element} element */
+function classList(element) {
+  return [...element.classList]
+}
+
+/**
+ * A block whose subtree was expanded from a compact directive. Its
+ * parameters live in the class attribute (see directives.js); its
+ * children are generated and must not be edited as prose.
+ * @param {Element} element
+ */
+function expansionDirective(element) {
+  const classes = classList(element)
+
+  // A glob list is a <ul>, or a <table> in its ?view=table form; the
+  // parameters are in the classes either way.
+  if ((element.tagName === "UL" || element.tagName === "TABLE") && classes.some(name => name.startsWith("_"))) {
+    const params = globParams(classes)
+    return params && globDirective(params)
+  }
+
+  if (element.tagName === "ARTICLE" && classes.includes("reference")) {
+    const link = element.querySelector("a[href]")
+    return link && link.getAttribute("href")
+  }
+
+  // Two transforms produce a bare-URL card: the rich a.link-preview built
+  // from url metadata, and the plainer <article> fallback.
+  if (element.tagName === "A" && classes.includes("link-preview")) {
+    return element.getAttribute("href")
+  }
+
+  if (element.tagName === "ARTICLE" && classes.includes("link-preview")) {
+    const link = element.querySelector("a[href]")
+    return link && link.getAttribute("href")
+  }
+
+  return null
+}
+
+/**
+ * Flattens inline DOM into Svedit's { content, marks } shape.
+ *
+ * Marks are mutually exclusive within a property, so nested inline
+ * formatting cannot be represented faithfully. Outermost wins: once inside
+ * a mark, descendants contribute their text but no further marks.
+ *
+ * @param {Node} domNode
+ * @param {{createMark: (type: string, element: Element) => string}} context
+ * @param {boolean} insideMark
+ */
+function inlineFrom(domNode, context, insideMark) {
+  if (domNode.nodeType === TEXT_NODE) {
+    return { content: domNode.nodeValue, marks: [] }
+  }
+
+  if (domNode.nodeType !== ELEMENT_NODE) {
+    return { content: "", marks: [] }
+  }
+
+  if (domNode.tagName === "BR") {
+    return { content: "\n", marks: [] }
+  }
+
+  const markType = insideMark ? null : MARK_TYPES[domNode.tagName]
+  const children = [...domNode.childNodes].map(child => {
+    return inlineFrom(child, context, insideMark || Boolean(markType))
+  })
+
+  const combined = children.reduce((accumulated, result) => {
+    const shifted = result.marks.map(mark => ({
+      ...mark,
+      start_offset: mark.start_offset + accumulated.content.length,
+      end_offset: mark.end_offset + accumulated.content.length
+    }))
+    return {
+      content: accumulated.content + result.content,
+      marks: [...accumulated.marks, ...shifted]
+    }
+  }, { content: "", marks: [] })
+
+  if (!markType) return combined
+
+  const markId = context.createMark(markType, domNode)
+  return {
+    content: combined.content,
+    marks: [{ start_offset: 0, end_offset: combined.content.length, node_id: markId }]
+  }
+}
+
+/**
+ * Whitespace at a block's edges is layout, not content: the hast
+ * conversion leaves a trailing newline inside <li> and <p>, which would
+ * serialize back as a blank line and grow the file on every save. Marks
+ * are clamped into the trimmed range and dropped if they collapse.
+ * @param {{content: string, marks: object[]}} value
+ */
+function trimValue({ content, marks }) {
+  const leading = content.length - content.trimStart().length
+  const trimmed = content.trim()
+
+  const clamped = marks
+    .map(mark => ({
+      ...mark,
+      start_offset: Math.max(0, Math.min(mark.start_offset - leading, trimmed.length)),
+      end_offset: Math.max(0, Math.min(mark.end_offset - leading, trimmed.length))
+    }))
+    .filter(mark => mark.end_offset > mark.start_offset)
+
+  return { content: trimmed, marks: clamped, annotations: [] }
+}
+
+/** @param {Element} element */
+function textValue(element, context) {
+  return trimValue(inlineFrom(element, context, false))
+}
+
+/** @param {Element} element */
+function pictureIn(element) {
+  if (element.tagName === "PICTURE") return element
+  return element.querySelector("picture")
+}
+
+/**
+ * @param {Element} element
+ * @param {object} context
+ * @returns {string|null} the created node's id, or null if unrecognised
+ */
+function blockFrom(element, context) {
+  const directive = expansionDirective(element)
+  if (directive) {
+    return context.create({
+      type: "embed",
+      directive,
+      html: element.outerHTML
+    })
+  }
+
+  const tag = element.tagName
+
+  if (tag === "P") {
+    // The image transform replaces an <img> in place, so a paragraph whose
+    // only element is a <picture> is an image block, not prose.
+    const picture = pictureIn(element)
+    if (picture && !element.textContent.trim()) return imageFrom(picture, null, element, context)
+
+    return context.create({
+      type: "paragraph",
+      content: textValue(element, context)
+    })
+  }
+
+  if (HEADING_LEVELS[tag]) {
+    return context.create({
+      type: "heading",
+      level: HEADING_LEVELS[tag],
+      content: textValue(element, context)
+    })
+  }
+
+  if (tag === "UL" || tag === "OL") {
+    const items = [...element.children].map(child => {
+      if (child.tagName !== "LI") return null
+      return context.create({
+        type: "list_item",
+        content: textValue(child, context)
+      })
+    })
+
+    if (items.some(id => !id)) return null
+
+    return context.create({
+      type: "list",
+      ordered: tag === "OL",
+      items: { nodes: items, marks: [], annotations: [] }
+    })
+  }
+
+  if (tag === "ASIDE" && classList(element).includes("alert")) {
+    // > [!NOTE] became <aside class="alert note">, with the marker line
+    // replaced by an injected <h2>. The variant is the class; the injected
+    // heading is dropped and regenerated on the way out.
+    const variant = classList(element).find(name => name !== "alert")
+    const body = [...element.children]
+      .filter(child => child.tagName !== "H2")
+      .map(child => blockFrom(child, context))
+
+    if (body.some(id => !id)) return null
+
+    return context.create({
+      type: "alert",
+      variant: variant || "note",
+      body: { nodes: body, marks: [], annotations: [] }
+    })
+  }
+
+  if (tag === "BLOCKQUOTE") {
+    const body = [...element.children].map(child => blockFrom(child, context))
+    if (body.some(id => !id)) return null
+
+    return context.create({
+      type: "blockquote",
+      body: { nodes: body, marks: [], annotations: [] }
+    })
+  }
+
+  if (tag === "PRE") {
+    const code = element.querySelector("code")
+    const language = code
+      ? (classList(code).find(name => name.startsWith("language-")) || "").slice("language-".length)
+      : ""
+
+    // textContent strips the highlighter's span tree, which is presentation.
+    // The fence supplies its own trailing newline on the way out.
+    return context.create({
+      type: "code_block",
+      language,
+      code: (code || element).textContent.replace(/\n+$/, "")
+    })
+  }
+
+  if (tag === "HR") {
+    return context.create({ type: "thematic_break" })
+  }
+
+  if (tag === "FIGURE") {
+    const picture = pictureIn(element)
+    const caption = element.querySelector("figcaption")
+    if (picture) return imageFrom(picture, caption, element, context)
+  }
+
+  if (tag === "PICTURE") {
+    return imageFrom(element, null, element, context)
+  }
+
+  context.unrecognised.push(tag.toLowerCase() + (element.className ? `.${element.className}` : ""))
+  return null
+}
+
+/**
+ * @param {Element} picture
+ * @param {Element|null} caption
+ * @param {Element} outer the element whose markup is kept for rendering
+ */
+function imageFrom(picture, caption, outer, context) {
+  const img = picture.querySelector("img")
+  const source = picture.getAttribute("data-original")
+
+  if (!source) {
+    context.unrecognised.push("picture (no data-original)")
+    return null
+  }
+
+  return context.create({
+    type: "image",
+    source,
+    alt: img ? (img.getAttribute("alt") || "") : "",
+    caption: caption ? caption.textContent : "",
+    html: outer.outerHTML
+  })
+}
+
+/**
+ * Builds a Svedit document from a rendered #content element.
+ *
+ * @param {Element} contentElement
+ * @param {() => string} generateId
+ * @returns {{doc: object|null, unrecognised: string[]}}
+ */
+export default function ingest(contentElement, generateId) {
+  const nodes = {}
+  const unrecognised = []
+
+  const context = {
+    unrecognised,
+    create(node) {
+      const id = generateId()
+      nodes[id] = { ...node, id }
+      return id
+    },
+    createMark(type, element) {
+      const properties = type === "link"
+        ? { href: element.getAttribute("href") || "" }
+        : {}
+      return context.create({ type, ...properties })
+    }
+  }
+
+  const body = [...contentElement.children].map(child => blockFrom(child, context))
+
+  if (unrecognised.length) return { doc: null, unrecognised }
+
+  const pageId = generateId()
+  nodes[pageId] = {
+    id: pageId,
+    type: "page",
+    body: { nodes: body.filter(Boolean), marks: [], annotations: [] }
+  }
+
+  return { doc: { document_id: pageId, nodes }, unrecognised: [] }
+}

package/plugins/html/editor/main.js

@@ -0,0 +1,94 @@
+import { mount, unmount } from "svelte"
+import Editor from "./Editor.svelte"
+import EditButton from "./EditButton.svelte"
+import SettingsPanel from "./SettingsPanel.svelte"
+import createSession from "./create-session.js"
+import readFrontmatter from "./frontmatter.js"
+import openSocket from "./socket.js"
+import { getSource } from "./source.js"
+
+openSocket()
+
+// section#content holds the rendered markdown body and nothing else - the
+// header, nav, aside and footer around it are generated, so the editable
+// region is exactly this element. The editor ingests its HTML as the
+// document's source of truth (see ingest.js).
+const content = document.getElementById("content")
+
+const noFrontmatter = { title: null, properties: {} }
+
+/**
+ * Swaps the server-rendered body for the editor. A previewed page runs
+ * none of this until the button is pressed, so what a reader loads is the
+ * page plus one button.
+ *
+ * The order here is the contract. Ingest reads the rendered DOM, so it
+ * runs before anything clears it; the clear runs before mount(), because
+ * mount() appends its render anchor *into* the target. Clearing a mount
+ * target after mounting detaches that anchor, and every later render then
+ * lands in a detached fragment - which leaves section#content empty with
+ * no error anywhere.
+ *
+ * @returns {string[]} the elements ingest did not recognise - empty when
+ *   the editor started. A page holding one stays read-only rather than
+ *   being guessed at, because a wrong guess round trips to markdown that
+ *   silently replaces the author's content on save.
+ */
+function startEditing() {
+  const { session, unrecognised } = createSession(content)
+
+  if (!session) {
+    console.warn(
+      "[vowel] editor stayed read-only: #content holds elements the ingest allowlist " +
+      "does not recognise:", unrecognised
+    )
+    return unrecognised
+  }
+
+  // The title and frontmatter live in <main>, alongside section#content
+  // rather than inside it. They round trip unchanged for now - reading
+  // them is what lets a save reproduce the whole file.
+  const main = content.closest("main")
+  const frontmatter = main ? readFrontmatter(main) : noFrontmatter
+
+  // Svedit renders the document itself rather than hydrating over the
+  // server output, so the original children go before it mounts.
+  content.replaceChildren()
+  mount(Editor, { target: content, props: { session, frontmatter } })
+
+  // Tells the live-reload patch (socket.js) to leave <main> alone: the
+  // editor's own content is the newer of the two, and a rebuild it
+  // triggered by saving must not replace it under the cursor.
+  document.documentElement.dataset.vowelEditing = "true"
+
+  return []
+}
+
+// The panel is mounted and unmounted rather than hidden: it reads
+// settings.md when it appears, so reopening it picks up an edit made
+// elsewhere in the meantime and there is nothing to invalidate.
+const settings = { panel: null }
+
+function closeSettings() {
+  if (!settings.panel) return
+  unmount(settings.panel)
+  settings.panel = null
+}
+
+function toggleSettings() {
+  if (settings.panel) return closeSettings()
+  settings.panel = mount(SettingsPanel, {
+    target: document.body,
+    props: { onclose: closeSettings }
+  })
+}
+
+// Gated: the editor is not part of 1.0, and mounts only when the dev
+// server was started with `vowel --editor`. The socket above is the
+// live-reload client and runs regardless.
+if (content && getSource().editor) {
+  mount(EditButton, {
+    target: document.body,
+    props: { onedit: startEditing, onsettings: toggleSettings }
+  })
+}

package/plugins/html/editor/nodes/Alert.svelte

@@ -0,0 +1,21 @@
+<script>
+  import { getContext } from "svelte"
+  import { Node, NodeArrayProperty } from "svedit"
+
+  const svedit = getContext("svedit")
+
+  let { path } = $props()
+
+  const node = $derived(svedit.session.get(path))
+  const variant = $derived(node.variant || "note")
+  const label = $derived(variant.charAt(0).toUpperCase() + variant.slice(1))
+</script>
+
+<!-- Mirrors the html plugin's alert markup, including the heading it
+     injects in place of the consumed [!NOTE] marker. -->
+<Node {path}>
+  <aside class="alert {variant}">
+    <h2 contenteditable="false">{label}</h2>
+    <NodeArrayProperty path={[...path, "body"]} />
+  </aside>
+</Node>

package/plugins/html/editor/nodes/Blockquote.svelte

@@ -0,0 +1,9 @@
+<script>
+  import { Node, NodeArrayProperty } from "svedit"
+
+  let { path } = $props()
+</script>
+
+<Node {path}>
+  <NodeArrayProperty tag="blockquote" path={[...path, "body"]} />
+</Node>

package/plugins/html/editor/nodes/CodeBlock.svelte

@@ -0,0 +1,19 @@
+<script>
+  import { getContext } from "svelte"
+  import { Node, CustomProperty } from "svedit"
+
+  const svedit = getContext("svedit")
+
+  let { path } = $props()
+
+  const node = $derived(svedit.session.get(path))
+</script>
+
+<!-- Read-only for now: the code is a string property, not a text
+     property, so it has no inline editing surface yet. -->
+<Node {path}>
+  <CustomProperty tag="pre" path={[...path, "code"]}>
+    <code contenteditable="false" class={node.language ? `language-${node.language}` : ""}
+      >{node.code}</code>
+  </CustomProperty>
+</Node>

package/plugins/html/editor/nodes/Embed.svelte

@@ -0,0 +1,19 @@
+<script>
+  import { getContext } from "svelte"
+  import { Node, CustomProperty } from "svedit"
+
+  const svedit = getContext("svedit")
+
+  let { path } = $props()
+
+  const node = $derived(svedit.session.get(path))
+</script>
+
+<!-- An expansion of a compact directive. Its children were generated from
+     other targets, so it is selectable and deletable as a unit but never
+     editable as prose - it collapses back to node.directive on save. -->
+<Node {path}>
+  <CustomProperty path={[...path, "directive"]}>
+    <div contenteditable="false" class="embed" title={node.directive}>{@html node.html}</div>
+  </CustomProperty>
+</Node>

package/plugins/html/editor/nodes/Emphasis.svelte

@@ -0,0 +1,11 @@
+<script>
+  import { getContext } from "svelte"
+
+  const svedit = getContext("svedit")
+
+  let { path, content } = $props()
+
+  const node = $derived(svedit.session.get(path))
+</script>
+
+<em id={node.id} data-node-id={node.id}>{content}</em>

package/plugins/html/editor/nodes/Heading.svelte

@@ -0,0 +1,15 @@
+<script>
+  import { getContext } from "svelte"
+  import { Node, TextProperty } from "svedit"
+
+  const svedit = getContext("svedit")
+
+  let { path } = $props()
+
+  const node = $derived(svedit.session.get(path))
+  const tag = $derived(`h${node.level || 2}`)
+</script>
+
+<Node {path}>
+  <TextProperty {tag} path={[...path, "content"]} placeholder="Heading" />
+</Node>

package/plugins/html/editor/nodes/Highlight.svelte

@@ -0,0 +1,11 @@
+<script>
+  import { getContext } from "svelte"
+
+  const svedit = getContext("svedit")
+
+  let { path, content } = $props()
+
+  const node = $derived(svedit.session.get(path))
+</script>
+
+<mark id={node.id} data-node-id={node.id}>{content}</mark>

package/plugins/html/editor/nodes/Image.svelte

@@ -0,0 +1,18 @@
+<script>
+  import { getContext } from "svelte"
+  import { Node, CustomProperty } from "svedit"
+
+  const svedit = getContext("svedit")
+
+  let { path } = $props()
+
+  const node = $derived(svedit.session.get(path))
+</script>
+
+<!-- The served <picture> markup is kept verbatim so edit mode matches the
+     page: the responsive derivatives cannot be rebuilt from source + alt. -->
+<Node {path}>
+  <CustomProperty path={[...path, "source"]}>
+    <div contenteditable="false">{@html node.html}</div>
+  </CustomProperty>
+</Node>

package/plugins/html/editor/nodes/InlineCode.svelte

@@ -0,0 +1,11 @@
+<script>
+  import { getContext } from "svelte"
+
+  const svedit = getContext("svedit")
+
+  let { path, content } = $props()
+
+  const node = $derived(svedit.session.get(path))
+</script>
+
+<code id={node.id} data-node-id={node.id}>{content}</code>

package/plugins/html/editor/nodes/Link.svelte

@@ -0,0 +1,17 @@
+<script>
+  import { getContext } from "svelte"
+
+  const svedit = getContext("svedit")
+
+  let { path, content } = $props()
+
+  const node = $derived(svedit.session.get(path))
+</script>
+
+<!-- A div while editing: an <a> inside contenteditable causes unexpected
+     selection behaviour (see svedit's README). -->
+{#if svedit.editable}
+  <div class="link" data-node-id={node.id} data-href={node.href}>{content}</div>
+{:else}
+  <a id={node.id} data-node-id={node.id} href={node.href}>{content}</a>
+{/if}

package/plugins/html/editor/nodes/List.svelte

@@ -0,0 +1,15 @@
+<script>
+  import { getContext } from "svelte"
+  import { Node, NodeArrayProperty } from "svedit"
+
+  const svedit = getContext("svedit")
+
+  let { path } = $props()
+
+  const node = $derived(svedit.session.get(path))
+  const tag = $derived(node.ordered ? "ol" : "ul")
+</script>
+
+<Node {path}>
+  <NodeArrayProperty {tag} path={[...path, "items"]} />
+</Node>

package/plugins/html/editor/nodes/ListItem.svelte

@@ -0,0 +1,9 @@
+<script>
+  import { Node, TextProperty } from "svedit"
+
+  let { path } = $props()
+</script>
+
+<Node {path}>
+  <TextProperty tag="li" path={[...path, "content"]} placeholder="List item" />
+</Node>

package/plugins/html/editor/nodes/Page.svelte

@@ -0,0 +1,21 @@
+<script>
+	import { Node, NodeArrayProperty } from 'svedit';
+
+	let { path } = $props();
+</script>
+
+<Node {path}>
+	<div class="page">
+		<NodeArrayProperty class="body-node-array" path={[...path, 'body']} />
+	</div>
+</Node>
+
+<style>
+	:global {
+		.body-node-array {
+			display: grid;
+			grid-template-columns: 1fr;
+			--row: 0;
+		}
+	}
+</style>

package/plugins/html/editor/nodes/Paragraph.svelte

@@ -0,0 +1,9 @@
+<script>
+  import { Node, TextProperty } from "svedit"
+
+  let { path } = $props()
+</script>
+
+<Node {path}>
+  <TextProperty tag="p" path={[...path, "content"]} placeholder="Paragraph" />
+</Node>

package/plugins/html/editor/nodes/Strikethrough.svelte

@@ -0,0 +1,11 @@
+<script>
+  import { getContext } from "svelte"
+
+  const svedit = getContext("svedit")
+
+  let { path, content } = $props()
+
+  const node = $derived(svedit.session.get(path))
+</script>
+
+<del id={node.id} data-node-id={node.id}>{content}</del>

package/plugins/html/editor/nodes/Strong.svelte

@@ -0,0 +1,11 @@
+<script>
+  import { getContext } from "svelte"
+
+  const svedit = getContext("svedit")
+
+  let { path, content } = $props()
+
+  const node = $derived(svedit.session.get(path))
+</script>
+
+<strong id={node.id} data-node-id={node.id}>{content}</strong>