@offorte/show-doc 0.0.4 → 0.0.6

package/dist/types/components/shw-doc.d.ts

@@ -1,4 +1,4 @@
-import { LitElement } from "lit";
+import { LitElement, type PropertyValues } from "lit";
 /**
  * Provides the page and document canvas for a ShowDoc artifact.
  *
@@ -6,7 +6,16 @@ import { LitElement } from "lit";
  * @slot - The complete visible document.
  */
 export declare class ShwDoc extends LitElement {
+    #private;
+    static properties: {
+        nav: {
+            type: StringConstructor;
+        };
+    };
     static styles: import("lit").CSSResult[];
+    /** Section menu mode. `auto` shows it for four or more main sections. `off` hides it. */
+    nav: "auto" | "off";
+    protected willUpdate(changed: PropertyValues<this>): void;
     protected render(): import("lit").TemplateResult<1>;
 }
 declare global {

package/dist/types/components/shw-mermaid.d.ts

@@ -10,10 +10,16 @@ export declare class ShwMermaid extends LitElement {
         label: {
             type: StringConstructor;
         };
+        page: {
+            type: BooleanConstructor;
+            reflect: boolean;
+        };
     };
     static styles: import("lit").CSSResult[];
     /** Accessible name for the rendered diagram. */
     label: string;
+    /** Fills the browser window with this one diagram. Use it without `shw-doc`. */
+    page: boolean;
     connectedCallback(): void;
     disconnectedCallback(): void;
     protected render(): import("lit").TemplateResult<1>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@offorte/show-doc",
-  "version": "0.0.4",
+  "version": "0.0.6",
   "description": "Agent skill and web components for polished, human-readable HTML documents.",
   "keywords": [
     "documentation",
@@ -73,7 +73,7 @@
     "fallow:check": "fallow --format compact --fail-on-issues --summary",
     "verify:source": "pnpm format:check && pnpm lint && pnpm typecheck",
     "verify:build": "pnpm test:browser && pnpm manifest:check && pnpm check:build && pnpm check:package && pnpm fallow:check",
-    "agent:verify": "pnpm verify:source && pnpm build && pnpm verify:build",
+    "agent:check": "pnpm verify:source && pnpm build && pnpm verify:build",
     "prepack": "pnpm build && pnpm manifest:check && pnpm check:build && pnpm check:package"
   },
   "dependencies": {
@@ -86,8 +86,12 @@
     "@tailwindcss/vite": "4.3.3",
     "@types/node": "26.3.0",
     "@types/prismjs": "1.26.6",
+    "@types/react": "19.3.0",
+    "@types/react-dom": "19.3.0",
     "@web/test-runner": "1.0.0",
     "@web/test-runner-playwright": "1.0.0",
+    "@xyflow/react": "12.12.0",
+    "elkjs": "0.12.1",
     "fallow": "3.18.0",
     "mermaid": "11.17.2",
     "micromark": "4.0.2",
@@ -97,6 +101,8 @@
     "oxlint": "1.80.0",
     "playwright": "1.62.1",
     "prismjs": "1.30.0",
+    "react": "19.3.1",
+    "react-dom": "19.3.1",
     "tailwindcss": "4.3.3",
     "typescript": "7.0.2",
     "vite": "8.2.2"

package/skills/show-doc/SKILL.md

@@ -1,13 +1,13 @@
 ---
 name: show-doc
-description: Create compact, readable standalone HTML documents with Offorte ShowDoc components and Markdown when a human-facing artifact needs more visual structure than normal prose.
+description: Create compact, readable standalone HTML documents with Offorte ShowDoc components and Markdown when a human-facing artifact needs more visual structure than normal prose, or one full-page Mermaid diagram when the user asks for a Mermaid diagram.
 metadata:
-  version: "0.0.4" # x-release-please-version
+  version: "0.0.6" # x-release-please-version
 ---
 
 # ShowDoc
 
-Use ShowDoc when the user asks for a ShowDoc or HTML document. Otherwise, use it for reports, plans,
+Use ShowDoc when the user asks for a ShowDoc, an HTML document, or a Mermaid diagram. Otherwise, use it for reports, plans,
 reviews, decisions, and explanations that need a durable file or more visual structure than normal
 chat Markdown. Do not use it for dashboards, forms, or application-like tools.
 
@@ -74,12 +74,12 @@ available. Return the exact file path.
 
 | Element           | Compact API                                                             | Use                                              |
 | ----------------- | ----------------------------------------------------------------------- | ------------------------------------------------ |
-| `shw-doc`         | -                                                                       | The one page canvas.                             |
+| `shw-doc`         | `nav?`                                                                  | The one page canvas.                             |
 | `shw-header`      | `heading`, `eyebrow?`                                                   | The one title and short Markdown lead.           |
 | `shw-summary`     | `heading?`                                                              | The answer before the evidence.                  |
 | `shw-section`     | `heading?`, `intro?`, `level?`                                          | A topic with an automatic divider.               |
 | `shw-markdown`    | -                                                                       | Normal prose, lists, links, tasks, and headings. |
-| `shw-mermaid`     | `label?`                                                                | A diagram from Mermaid source.                   |
+| `shw-mermaid`     | `label?`, `page?`                                                       | A diagram from Mermaid source.                   |
 | `shw-grid`        | `columns?`                                                              | Two to four sibling blocks to compare.           |
 | `shw-card`        | `heading?`, `label?`, `tone?`                                           | One grouped idea, choice, or status.             |
 | `shw-badge`       | `tone?`                                                                 | A short standalone state or category.            |
@@ -95,6 +95,10 @@ Defaults reduce source. A summary heading is `Summary`. A section level is `2`.
 `2`. A collapsible summary is `Details`, and its content mode is `markdown`. Default tone is
 `neutral`, except callouts use `info`.
 
+A document with four or more direct `shw-section` children that have a `heading` and no `level="3"`
+gets a floating section menu automatically. Do not add a table of contents to these documents. Use
+`nav="off"` only when the menu would distract, such as on a page made for embedding.
+
 Tones are `info`, `success`, `warning`, `danger`, and `neutral`. Use them only when the meaning helps
 the reader.
 
@@ -218,4 +222,53 @@ Raw HTML inside Markdown is disabled. Write `&lt;` for a literal `<`, including
 Write Mermaid diagram text directly inside `shw-mermaid`. Set `label` to its short accessible name.
 The Mermaid bundle supports the full Mermaid package and makes no extra runtime request.
 
+## Mermaid diagrams
+
+ShowDoc draws flowcharts, state diagrams, and sequence diagrams itself. Mermaid draws every other
+diagram type, and any diagram with `click` links, icons, images, or half arrows.
+
+The page is HTML, so write `&lt;` for each `<` in the source. For example, write
+`state check &lt;&lt;choice&gt;&gt;`. Write a second line in a label as `\n`, not `<br/>`. The second
+line appears as small code text.
+
+- A `subgraph` in a flowchart becomes a lane, a column with an uppercase title. Name each lane after
+  what its parts do. A nested subgraph, a line from a node to itself, or a line to a subgraph gives a
+  normal group layout instead of lanes.
+- `:::new`, `:::changed`, and `:::removed` add a status pill. Use them only when the diagram compares
+  two states.
+- `:::icon-code`, `window`, `box`, `play`, `queue`, `service`, `db`, `file`, `user`, `cloud`, or
+  `decision` (each with the `icon-` prefix) adds an icon. `[( )]` adds the database icon. In a lane,
+  every card has an icon.
+- A frontmatter title appears in a chip above the diagram. Text after `|` appears as grey code:
+  `title: Container view | architecture-overview · hero`.
+
+## Only a diagram
+
+When the user asks only for a Mermaid diagram, do not build a document. Write this page with one
+`shw-mermaid` that has the `page` attribute and no `shw-doc`.
+
+<!-- prettier-ignore -->
+```html
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <script
+      type="module"
+      src="https://cdn.jsdelivr.net/npm/@offorte/show-doc@latest/dist/showdoc-mermaid.js"
+    ></script>
+    <title>Save flow</title>
+  </head>
+  <body>
+    <shw-mermaid page label="Saving a draft">
+      flowchart LR
+        A[Save draft] --> B{Save succeeds?}
+        B -->|Yes| C[Clear draft]
+        B -->|No| D[Keep draft]
+    </shw-mermaid>
+  </body>
+</html>
+```
+
 Do not run a generic HTML formatter over the result. It can remove meaningful Markdown line breaks.