vowel 0.6.4 → 0.7.0-beta.0

package/plugins/html/editor/create-session.js

@@ -0,0 +1,250 @@
+import {
+  Session,
+  SelectAllCommand,
+  InsertDefaultNodeCommand,
+  AddNewLineCommand,
+  BreakTextNodeCommand,
+  UndoCommand,
+  RedoCommand,
+  SelectParentCommand,
+  ToggleMarkCommand,
+  define_document_schema,
+  fill_document_defaults,
+  define_keymap
+} from "svedit"
+
+import Overlays from "./Overlays.svelte"
+import ingest from "./ingest.js"
+import {
+  Page,
+  Paragraph,
+  Heading,
+  List,
+  ListItem,
+  Blockquote,
+  Alert,
+  CodeBlock,
+  ThematicBreak,
+  Image,
+  Embed,
+  Strong,
+  Emphasis,
+  InlineCode,
+  Highlight,
+  Strikethrough,
+  Link
+} from "./nodes/index.js"
+
+// The faithful subset of vowel's generated HTML - everything the MD -> HTML
+// conversion emits as distinct semantic markup, plus the two node kinds that
+// stand in for content it generates rather than renders (image, embed).
+const INLINE_MARKS = ["strong", "emphasis", "inline_code", "highlight", "strikethrough", "link"]
+
+const BLOCK_TYPES = [
+  "paragraph",
+  "heading",
+  "list",
+  "blockquote",
+  "alert",
+  "code_block",
+  "thematic_break",
+  "image",
+  "embed"
+]
+
+const document_schema = define_document_schema({
+  page: {
+    kind: "document",
+    properties: {
+      body: {
+        type: "node_array",
+        node_types: BLOCK_TYPES,
+        default_node_type: "paragraph"
+      }
+    }
+  },
+  paragraph: {
+    kind: "text",
+    properties: {
+      content: { type: "text", mark_types: INLINE_MARKS, allow_newlines: true }
+    }
+  },
+  heading: {
+    kind: "text",
+    properties: {
+      content: { type: "text", mark_types: INLINE_MARKS, allow_newlines: false },
+      level: { type: "integer", min: 1, max: 6, default: 2 }
+    }
+  },
+  list: {
+    kind: "block",
+    properties: {
+      items: { type: "node_array", node_types: ["list_item"], default_node_type: "list_item" },
+      ordered: { type: "boolean", default: false }
+    }
+  },
+  list_item: {
+    kind: "text",
+    properties: {
+      content: { type: "text", mark_types: INLINE_MARKS, allow_newlines: false }
+    }
+  },
+  blockquote: {
+    kind: "block",
+    properties: {
+      body: { type: "node_array", node_types: BLOCK_TYPES, default_node_type: "paragraph" }
+    }
+  },
+  // > [!NOTE] - the variant is what the html plugin encodes in the class.
+  alert: {
+    kind: "block",
+    properties: {
+      variant: { type: "string", default: "note" },
+      body: { type: "node_array", node_types: BLOCK_TYPES, default_node_type: "paragraph" }
+    }
+  },
+  code_block: {
+    kind: "block",
+    properties: {
+      code: { type: "string", default: "" },
+      language: { type: "string", default: "" }
+    }
+  },
+  thematic_break: {
+    kind: "block",
+    properties: {}
+  },
+  // source is the canonical asset path from the <picture>; html is the
+  // served markup, kept so edit mode looks identical to the page.
+  image: {
+    kind: "block",
+    properties: {
+      source: { type: "string", default: "" },
+      alt: { type: "string", default: "" },
+      caption: { type: "string", default: "" },
+      html: { type: "string", default: "" }
+    }
+  },
+  // A directive that expanded into generated content. Opaque by design.
+  embed: {
+    kind: "block",
+    properties: {
+      directive: { type: "string", default: "" },
+      html: { type: "string", default: "" }
+    }
+  },
+  strong: { kind: "mark", properties: {} },
+  emphasis: { kind: "mark", properties: {} },
+  inline_code: { kind: "mark", properties: {} },
+  highlight: { kind: "mark", properties: {} },
+  strikethrough: { kind: "mark", properties: {} },
+  link: { kind: "mark", properties: { href: { type: "string", default: "" } } }
+})
+
+// Only non-numeric ids are valid in Svedit because document paths are built
+// from mixed string and number segments.
+function generate_id(length = 16) {
+  const id_alphabet = "abcdefghijklmnopqrstuvwxyz"
+  const random_values = crypto.getRandomValues(new Uint8Array(length))
+  return [...random_values].map(value => id_alphabet[value % id_alphabet.length]).join("")
+}
+
+const session_config = {
+  generate_id,
+  system_components: {
+    overlays: Overlays
+  },
+  node_components: {
+    page: Page,
+    paragraph: Paragraph,
+    heading: Heading,
+    list: List,
+    list_item: ListItem,
+    blockquote: Blockquote,
+    alert: Alert,
+    code_block: CodeBlock,
+    thematic_break: ThematicBreak,
+    image: Image,
+    embed: Embed,
+    strong: Strong,
+    emphasis: Emphasis,
+    inline_code: InlineCode,
+    highlight: Highlight,
+    strikethrough: Strikethrough,
+    link: Link
+  },
+
+  /**
+   * @param {object} context - The svedit context with session, editable, canvas.
+   * @returns {{ commands: object, keymap: object }}
+   */
+  create_commands_and_keymap: (context) => {
+    const commands = {
+      select_all: new SelectAllCommand(context),
+      insert_default_node: new InsertDefaultNodeCommand(context),
+      add_new_line: new AddNewLineCommand(context),
+      break_text_node: new BreakTextNodeCommand(context),
+      undo: new UndoCommand(context),
+      redo: new RedoCommand(context),
+      select_parent: new SelectParentCommand(context),
+      toggle_strong: new ToggleMarkCommand("strong", context),
+      toggle_emphasis: new ToggleMarkCommand("emphasis", context),
+      toggle_inline_code: new ToggleMarkCommand("inline_code", context),
+      toggle_highlight: new ToggleMarkCommand("highlight", context),
+      toggle_strikethrough: new ToggleMarkCommand("strikethrough", context)
+    }
+
+    const keymap = define_keymap({
+      "meta+a,ctrl+a": [commands.select_all],
+      enter: [commands.break_text_node, commands.insert_default_node],
+      // In case of a node cursor, fall back to inserting a default node. This
+      // is needed because on iOS selecting a node cursor triggers auto
+      // capitalization (shift pressed)
+      "shift+enter": [commands.add_new_line, commands.insert_default_node],
+      "meta+z,ctrl+z": [commands.undo],
+      "meta+shift+z,ctrl+shift+z": [commands.redo],
+      escape: [commands.select_parent],
+      "meta+b,ctrl+b": [commands.toggle_strong],
+      "meta+i,ctrl+i": [commands.toggle_emphasis]
+    })
+
+    return { commands, keymap }
+  },
+
+  inserters: {
+    paragraph: function (tr, content = { content: "", marks: [], annotations: [] }) {
+      const new_paragraph = {
+        id: session_config.generate_id(),
+        type: "paragraph",
+        content
+      }
+      tr.create(new_paragraph)
+      tr.insert_nodes([new_paragraph.id])
+      // NOTE: Relies on insert_nodes selecting the newly inserted node(s)
+      tr.set_selection({
+        type: "text",
+        path: [...tr.selection.path, tr.selection.focus_offset - 1, "content"],
+        anchor_offset: 0,
+        focus_offset: 0
+      })
+    }
+  }
+}
+
+/**
+ * Builds a session from the rendered page. #content is the source of truth;
+ * an element the allowlist does not recognise fails the whole ingest rather
+ * than being guessed at, so the editor stays read-only instead of silently
+ * rewriting content it did not understand.
+ *
+ * @param {Element} element the #content section of the previewed page
+ * @returns {{session: Session|null, unrecognised: string[]}}
+ */
+export default function create_session(element) {
+  const { doc, unrecognised } = ingest(element, generate_id)
+
+  if (!doc) return { session: null, unrecognised }
+
+  const filled = fill_document_defaults(doc, document_schema)
+  return { session: new Session(document_schema, filled, session_config), unrecognised: [] }
+}

package/plugins/html/editor/directives.js

@@ -0,0 +1,128 @@
+// Shared encoding for directive parameters carried in class attributes.
+//
+// The generated HTML is the source of truth for the editor, so a directive
+// that expanded into a subtree (a glob list, a reference card) has to be
+// reconstructible from attributes that are visible and worth styling - not
+// from the original markdown stamped into a data attribute.
+//
+// This module is imported by both plugins/html/index.js (node, emit side)
+// and the browser bundle (ingest side), so it must stay free of node
+// builtins.
+
+// Folder segments are joined with "_", so "_" inside a segment is escaped
+// to "--". A literal "--" in a folder name therefore collides with an
+// escaped "_"; that is rarer than a single hyphen, and single hyphens pass
+// through untouched, which keeps the common case ("my-blog" -> "_my-blog")
+// clean and styleable. Emit warns on the collision rather than mangling it.
+const SEGMENT_SEPARATOR = "_"
+const ESCAPED_UNDERSCORE = "--"
+
+/** @param {string} segment */
+export function escapeSegment(segment) {
+  return segment.replaceAll(SEGMENT_SEPARATOR, ESCAPED_UNDERSCORE)
+}
+
+/** @param {string} segment */
+export function unescapeSegment(segment) {
+  return segment.replaceAll(ESCAPED_UNDERSCORE, SEGMENT_SEPARATOR)
+}
+
+/** @param {string} segment */
+export function segmentIsAmbiguous(segment) {
+  return segment.includes(ESCAPED_UNDERSCORE)
+}
+
+/**
+ * Cumulative ancestor classes for a folder, so a stylesheet can target any
+ * level: "a/b/c" -> ["_", "_a", "_a_b", "_a_b_c"].
+ * @param {string} folder
+ */
+export function dirClasses(folder) {
+  const segments = folder.split(/[\\/]/).filter(Boolean).map(escapeSegment)
+  const cumulative = segments.map((_, index) => {
+    return SEGMENT_SEPARATOR + segments.slice(0, index + 1).join(SEGMENT_SEPARATOR)
+  })
+  return [SEGMENT_SEPARATOR, ...cumulative]
+}
+
+/** @param {string[]} classList */
+export function folderFromClasses(classList) {
+  const dirClassList = classList.filter(name => name.startsWith(SEGMENT_SEPARATOR))
+  if (!dirClassList.length) return null
+
+  const deepest = dirClassList.reduce((longest, name) => {
+    return name.length > longest.length ? name : longest
+  }, "")
+
+  const segments = deepest.slice(1).split(SEGMENT_SEPARATOR).filter(Boolean)
+  return segments.map(unescapeSegment).join("/")
+}
+
+// Values become part of a class token, so anything that would need CSS
+// escaping is rejected rather than emitted. The caller decides whether to
+// warn or drop the parameter.
+/** @param {string} value */
+export function valueIsSafe(value) {
+  return /^[A-Za-z0-9][A-Za-z0-9-]*$/.test(value)
+}
+
+/**
+ * `view` and `properties` are the table view's parameters
+ * (`?view=table&properties=title,description`): one `view-<name>` token
+ * and one `property-<name>` token per column, in column order - class
+ * order is document order, so the list round-trips without a separator
+ * that a property name could contain.
+ * @param {{folder: string, recursive?: boolean, limit?: number|string, tag?: string, view?: string|null, properties?: string[]}} params
+ */
+export function globClasses({ folder, recursive, limit, tag, view, properties = [] }) {
+  const classes = dirClasses(folder)
+  const recursiveClass = recursive ? ["recursive"] : []
+  const limitClass = limit ? [`limit-${limit}`] : []
+  const tagClass = tag && valueIsSafe(tag) ? [`tag-${tag}`] : []
+  const viewClass = view && valueIsSafe(view) ? [`view-${view}`] : []
+  const propertyClasses = properties.filter(valueIsSafe).map(name => `property-${name}`)
+  return [...classes, ...recursiveClass, ...limitClass, ...tagClass, ...viewClass, ...propertyClasses]
+}
+
+/**
+ * Inverse of globClasses. "limit" is the class spelling of the directive's
+ * ?count= parameter.
+ * @param {string[]} classList
+ */
+export function globParams(classList) {
+  const folder = folderFromClasses(classList)
+  if (folder === null) return null
+
+  const limitClass = classList.find(name => name.startsWith("limit-"))
+  const tagClass = classList.find(name => name.startsWith("tag-"))
+  const viewClass = classList.find(name => name.startsWith("view-"))
+  const properties = classList
+    .filter(name => name.startsWith("property-"))
+    .map(name => name.slice("property-".length))
+
+  return {
+    folder,
+    recursive: classList.includes("recursive"),
+    limit: limitClass ? limitClass.slice("limit-".length) : null,
+    tag: tagClass ? tagClass.slice("tag-".length) : null,
+    view: viewClass ? viewClass.slice("view-".length) : null,
+    properties
+  }
+}
+
+/**
+ * Rebuilds the markdown directive a glob list expanded from.
+ * @param {{folder: string, recursive: boolean, limit: string|null, tag: string|null}} params
+ */
+export function globDirective({ folder, recursive, limit, tag, view = null, properties = [] }) {
+  // Built with the URL constructor and searchParams, not by hand - the
+  // convention for anything url-shaped. `thismessage://` is a base that
+  // parses without a real domain (RFC 2557); only the pathname and search
+  // are taken back out.
+  const url = new URL("/" + [folder, recursive ? "**" : "*"].filter(Boolean).join("/"), "thismessage://")
+  if (limit) url.searchParams.set("count", limit)
+  if (tag) url.searchParams.set("tag", tag)
+  if (view) url.searchParams.set("view", view)
+  if (properties.length) url.searchParams.set("properties", properties.join(","))
+  return decodeURIComponent(url.pathname + url.search)
+}

package/plugins/html/editor/frontmatter.js

@@ -0,0 +1,97 @@
+// <main>'s children -> the page's frontmatter.
+//
+// The inverse of makeFrontmatter in plugins/html/index.js. Each property
+// is its own single-item <dl>, except the ones vowel handles specially,
+// which get their own element identified by itemprop. The title is main's
+// first <h1> - the one piece of data hoisted out of the content - and is
+// written back as a "#" heading rather than a frontmatter key.
+
+/** @param {Element} element */
+function scalarFrom(element) {
+  const text = element.textContent.trim()
+
+  if (text === "true") return true
+  if (text === "false") return false
+  if (text === "null") return null
+
+  // Number() accepts "" and whitespace, so the emptiness check has to come
+  // first or a blank value becomes 0.
+  if (text && !Number.isNaN(Number(text))) return Number(text)
+
+  return text
+}
+
+/**
+ * A date rendered as <time> carries an ISO datetime, but the author most
+ * likely wrote a plain date. Midnight UTC comes back as a date only, so
+ * "date: 2026-03-04" stays stable across saves.
+ * @param {Element} element
+ */
+function dateFrom(element) {
+  const datetime = element.getAttribute("datetime")
+  if (!datetime) return element.textContent.trim()
+  if (datetime.endsWith("T00:00:00.000Z")) return datetime.slice(0, "0000-00-00".length)
+  return datetime
+}
+
+/** @param {Element} element the <dd> or <li> holding one value */
+function valueFrom(element) {
+  const list = element.querySelector(":scope > ul")
+  if (list) return [...list.children].map(item => valueFrom(item))
+
+  const nested = element.querySelector(":scope > dl")
+  if (nested) return objectFrom(nested)
+
+  const time = element.querySelector(":scope > time")
+  if (time) return dateFrom(time)
+
+  const link = element.querySelector(":scope > a[href]")
+  if (link) return link.getAttribute("href")
+
+  return scalarFrom(element)
+}
+
+/** @param {Element} list a <dl> of dt/dd pairs */
+function objectFrom(list) {
+  const terms = [...list.children]
+
+  return terms.reduce((accumulated, node, index) => {
+    if (node.tagName !== "DT") return accumulated
+
+    const value = terms[index + 1]
+    if (!value || value.tagName !== "DD") return accumulated
+
+    return { ...accumulated, [node.textContent.trim()]: valueFrom(value) }
+  }, {})
+}
+
+/**
+ * @param {Element} main
+ * @returns {{title: string|null, properties: object}}
+ */
+export default function readFrontmatter(main) {
+  const children = [...main.children]
+
+  const heading = children.find(child => child.tagName === "H1")
+  const date = children.find(child => child.matches('time[itemprop="date"]'))
+  const image = children.find(child => child.matches('picture[itemprop="image"]'))
+  const description = children.find(child => child.matches('p[itemprop="description"]'))
+
+  const known = {
+    ...(date ? { date: dateFrom(date) } : {}),
+    ...(image ? { image: image.getAttribute("data-original") } : {}),
+    ...(description ? { description: description.textContent.trim() } : {})
+  }
+
+  // Every remaining single-item <dl> is one generic property. The
+  // breadcrumb and contents navs and section#content are skipped by not
+  // matching.
+  const generic = children
+    .filter(child => child.tagName === "DL")
+    .reduce((accumulated, list) => ({ ...accumulated, ...objectFrom(list) }), {})
+
+  return {
+    title: heading ? heading.textContent.trim() : null,
+    properties: { ...known, ...generic }
+  }
+}