@threadlabs/looma 0.29.12 → 0.29.13

package/EXPRESSIVE-MARKDOWN.md

@@ -0,0 +1,90 @@
+# Expressive Markdown
+
+Convert a saved LoomaEditor document into readable Markdown or an independent
+JSON AST. The adapter runs in browsers and on servers without creating an editor
+or loading a DOM.
+
+```ts
+import { editorDocumentToMarkdown, markdownToEditorDocument } from "@threadlabs/looma/editor/expressmark";
+
+const markdown = editorDocumentToMarkdown(savedEditorJson);
+const restoredEditorJson = markdownToEditorDocument(markdown);
+```
+
+Use the AST when attaching a document title or building another renderer:
+
+```ts
+import {
+  editorDocumentToExpressmark,
+  expressmarkToEditorDocument,
+} from "@threadlabs/looma/editor/expressmark";
+import { parse, stringify } from "expressmark";
+
+const ast = editorDocumentToExpressmark(savedEditorJson);
+const markdown = stringify(ast);
+const restoredEditorJson = expressmarkToEditorDocument(parse(markdown));
+```
+
+The editor continues to save Tiptap JSON. Expressive Markdown is an interchange
+format; it does not replace your saved document, history or application metadata.
+See the [proposal and syntax](https://nextwebwg.org/expressive-markdown/) and
+[document AST](https://nextwebwg.org/expressive-markdown/ast).
+
+## Conversion behavior
+
+Headings, text formatting, links, images, lists, tasks, quotes, code, callouts,
+disclosures, figures, tabs, chips, mentions and tables map to their semantic AST
+nodes. Mention targets become `ref`; chips keep their `tone`; merged table cells
+keep numeric spans and block bodies.
+
+Table cell presentation uses string attributes: `textAlign`, `backgroundColor`
+and the adapter profile's `columnWidths` (comma-separated pixel widths, such as
+`"100,120"`). Image dimensions use string `width`/`height`; `responsive` is a
+boolean. Tabs preserve `group`, `default`, `queryString`, `lazy` and each tab's
+selection `value`. A tab's label is independent of that value.
+
+Saved code fence titles, highlighted ranges and line-number choices become the
+shared `title`, `highlight` and `showLineNumbers` fields. Ranges remain strings;
+unknown fence metadata stays in `meta`. Code notation comments remain literal,
+including escaped markers, as they do in the default editor.
+
+Automatic tables of contents receive readable heading links on export. Headings
+that need an anchor receive one in the exported AST; saved editor JSON is not
+changed. Authored IDs remain unchanged, including duplicates. Pass
+`{ onDiagnostic }` as the optional second argument to receive duplicate-ID warnings. Imported
+TOC bodies remain authored navigation; edits to document headings do not replace
+them. TOCs created with the editor's existing command continue to update from
+headings automatically.
+
+## Handle unsupported content
+
+```ts
+import { EditorMarkdownConversionError } from "@threadlabs/looma/editor/expressmark";
+
+try {
+  const ast = editorDocumentToExpressmark(savedEditorJson);
+} catch (error) {
+  if (error instanceof EditorMarkdownConversionError) {
+    console.error(error.path, error.feature);
+  } else {
+    throw error;
+  }
+}
+```
+
+Unsupported nodes, marks, attributes and meanings stop conversion with their
+location. Keep the original saved JSON when preparing portable exports. The
+adapter never mutates it or claims an unknown extension has been preserved in
+Markdown. Native URLs and table background colors must pass the shared safe HTML
+profile before the editor interprets them; unsupported values raise an error.
+
+The editor content model has no document-level title or arbitrary metadata.
+Store those fields alongside the editor JSON; importing a root that contains
+them directly into editor content raises an error. Likewise, custom semantic
+types, IDs on nodes other than headings, formatted callout/tab titles and
+unsupported presentation must be handled by your application rather than
+silently flattened.
+
+The existing `loomaMarkdownFromDoc` and `loomaMarkdownToHtml` APIs retain their
+Looma Markdown syntax. Choose the Expressive adapter explicitly for new portable
+Markdown export.

package/README.md

@@ -28,6 +28,12 @@ import { getDefaultEditorExtensions } from "@threadlabs/looma/editor/extensions"
 The editor components' event and geometry types, without Tiptap, are in
 `@threadlabs/looma/editor/ui`.
 
+## Expressive Markdown
+
+Convert saved editor JSON with the SSR-safe `@threadlabs/looma/editor/expressmark`
+adapter. It preserves supported semantic content and reports unsupported data
+instead of silently flattening it. See [conversion examples and coverage](EXPRESSIVE-MARKDOWN.md).
+
 ## HTML
 
 ```html

package/components/ui-tabs/ui-tabs.html

@@ -5,7 +5,7 @@
     <prop name="label" type="string" default="Tabs"
     >The tab list's accessible name, announced when focus enters the list. Name what the tabs switch between.</prop>
     <prop name="value" type="string" default=""
-    >The id of the selected panel, initially or when set externally; empty selects the first panel. Choosing a tab updates it from there and reports a select
+    >The id or authored data-value of the selected panel, initially or when set externally; empty selects the first panel. Choosing a tab updates it from there and reports a select
       event. A panel without an id is given a generated one.</prop>
     <prop name="orientation" type="keyword" values="horizontal, vertical" default="horizontal"
     >horizontal puts the tabs in a row above the panels, moved between with the Left and Right arrow keys; vertical puts them in a column beside the panels,
@@ -15,7 +15,7 @@
       displaying a panel takes time.</prop>
     <prop name="stretch" type="boolean" default="false">Share the full width of the tab list equally between tabs instead of sizing each to its label.</prop>
     <prop name="group" type="string" default=""
-    >Tabs with the same nonempty group share one selection: choosing a tab selects the tab with the same label in every other Tabs of that group in the
+    >Tabs with the same nonempty group share one selection: choosing a tab selects the tab with the same data-value (or label when no value is authored) in every other Tabs of that group in the
       document, and the choice is remembered for the next visit. Use it for alternatives a reader picks once, such as a package manager or language.</prop>
     <state type="string" name="internalValue" value=""></state>
     <state name="tabs" type="list(object({ id: string, label: string }))" value="[]"></state>

package/components/ui-tabs/ui-tabs.js

@@ -17,6 +17,10 @@ function connect(host) {
   const { list, panels: container } = host.refs;
   const [trigger, stopTracking] = trackTrigger(host);
   const panels = () => Array.from(container.children).filter((child) => child instanceof HTMLElement);
+  const panelKey = (panel) => panel?.getAttribute("data-value")
+    ?? (panel?.getAttribute("aria-label") || host.state.tabs.find(tab => tab.id === panel?.id)?.label);
+  const resolveValue = (value) => panels().find(panel => panel.id === value)?.id
+    ?? panels().find(panel => panel.getAttribute("data-value") === value)?.id;
   const tabButtons = () => Array.from(list.querySelectorAll("button"));
   const focusTab = (button) => {
     for (const tab of tabButtons()) tab.tabIndex = tab === button ? 0 : -1;
@@ -33,7 +37,7 @@ function connect(host) {
       return { id: panel.id, label: panel.getAttribute("aria-label") || `Tab ${index + 1}` };
     });
     if (!items.some((panel) => panel.id === host.state.internalValue)) {
-      host.state.internalValue = external || items[0]?.id || "";
+      host.state.internalValue = resolveValue(external) || items[0]?.id || "";
     }
     syncButtons();
   };
@@ -58,7 +62,7 @@ function connect(host) {
     const value = String(host.props.value.value || "");
     if (value !== external) {
       external = value;
-      host.state.internalValue = value;
+      host.state.internalValue = resolveValue(value) || panels()[0]?.id || "";
     }
     const selected = host.state.internalValue;
     for (const panel of panels()) panel.hidden = panel.id !== selected;
@@ -68,11 +72,11 @@ function connect(host) {
 
   const group = () => String(host.props.group.value || "");
   const document = host.element.ownerDocument;
-  // A group shares a selection by tab label, since panel ids are unique in a document.
-  const selectLabel = (label) => {
-    const tab = host.state.tabs.find((candidate) => candidate.label === label);
-    if (!tab || tab.id === host.state.internalValue) return false;
-    host.state.internalValue = tab.id;
+  // Authored selection values cross groups; labels remain the fallback for existing panels.
+  const selectGroupValue = (label) => {
+    const panel = panels().find(candidate => panelKey(candidate) === label);
+    if (!panel || panel.id === host.state.internalValue) return false;
+    host.state.internalValue = panel.id;
     return true;
   };
   const select = (button, how) => {
@@ -80,7 +84,7 @@ function connect(host) {
     host.state.internalValue = button.value;
     host.dispatch("select", { value: button.value, previousValue, trigger: how });
     const name = group();
-    const label = host.state.tabs.find((tab) => tab.id === button.value)?.label;
+    const label = panelKey(panels().find(panel => panel.id === button.value));
     if (!name || label === undefined) return;
     writeStored(name, label);
     document.dispatchEvent(new CustomEvent(GROUP_EVENT, { detail: { group: name, label, source: host.element } }));
@@ -89,7 +93,7 @@ function connect(host) {
     const { group: name, label, source } = event.detail;
     if (source === host.element || name !== group()) return;
     const previousValue = host.state.internalValue || undefined;
-    if (selectLabel(label)) host.dispatch("select", { value: host.state.internalValue, previousValue, trigger: "programmatic" });
+    if (selectGroupValue(label)) host.dispatch("select", { value: host.state.internalValue, previousValue, trigger: "programmatic" });
   };
   const onClick = (event) => {
     const button = event.target.closest?.('[role="tab"]');
@@ -138,7 +142,7 @@ function connect(host) {
   // A remembered choice applies when the page does not choose a panel itself.
   if (group() && !external) {
     const stored = readStored(group());
-    if (stored !== null) selectLabel(stored);
+    if (stored !== null) selectGroupValue(stored);
   }
   return () => {
     document.removeEventListener(GROUP_EVENT, onGroupSelect);