@p10node/diagram 0.0.0-stage → 0.9.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 p10node
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,78 @@
-# Temporary Holding Version
+# @p10node/diagram
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Mermaid, PlantUML and Graphviz DOT text → SVG. No DOM needed (browser, Web Worker, Node, Bun), no server, no WebAssembly, no dependency.
+
+Part of [office-engine](https://github.com/p10node/office-engine); single-language packages: [`@p10node/mermaid`](../mermaid), [`@p10node/plantuml`](../plantuml), [`@p10node/graphviz`](../graphviz). Markdown with diagrams: [`@p10node/markdown`](../markdown).
+
+## Install
+
+```sh
+npm i @p10node/diagram
+```
+
+## Use
+
+```ts
+import { detect, render, renderEach, renderPage, renderTo, toPng } from '@p10node/diagram'
+
+const { svg, width, height } = render('graph LR\n  A --> B') // language detected
+render('A -> B : hi', 'plantuml')                              // or given
+renderEach(pumlFileText)                                       // every @startuml block, every DOT graph
+detect('digraph { a -> b }')                                   // 'graphviz'
+
+renderTo(document.getElementById('out')!, source)               // into an element
+renderPage()                                                   // every diagram block of the page
+const png = await toPng(svg, 2)                                // PNG Blob, 2× size (browser)
+```
+
+`renderPage(root = document)` draws `<pre class="mermaid">`, `<div class="plantuml">`, `<pre class="graphviz">`, `<pre><code class="language-mermaid | plantuml | puml | dot | graphviz">` and `<pre class="diagram">` (language detected). Each becomes `<figure class="diagram diagram-<lang>">`; a block that cannot be drawn stays, with a `data-diagram-error` attribute. It returns how many it drew.
+
+From a CDN, no build step:
+
+```html
+<pre class="mermaid">sequenceDiagram
+  Alice->>Bob: Hello</pre>
+<script type="module">
+  import { renderPage } from 'https://cdn.jsdelivr.net/npm/@p10node/diagram/dist/index.js'
+  renderPage()
+</script>
+```
+
+## API
+
+| Function                           | Returns               | Notes                                                              |
+|------------------------------------|-----------------------|--------------------------------------------------------------------|
+| `render(source, lang?)`            | `Diagram`             | The first drawing; `lang`: `'mermaid' \| 'plantuml' \| 'graphviz'` |
+| `renderEach(source, lang?)`        | `Diagram[]`           | Every drawing of the source                                        |
+| `detect(source)`                   | `DiagramLang \| null` | From `@startuml`, `digraph {`, a Mermaid header                    |
+| `renderTo(element, source, lang?)` | `Diagram[]`           | Replaces the element's content (browser)                           |
+| `renderPage(root?)`                | `number`              | Draws the page's diagram blocks (browser)                          |
+| `toPng(svg, scale = 2)`            | `Promise<Blob>`       | PNG of a drawing (browser)                                         |
+
+`Diagram` is `{ svg: string; width: number; height: number }` (CSS pixels). A source that cannot be drawn throws a `DiagramError` with the reason.
+
+## What is drawn
+
+| Language | Diagrams                                                                                                |
+|----------|---------------------------------------------------------------------------------------------------------|
+| Mermaid  | flowchart / graph (subgraphs, `classDef`, `style`), sequence, class, state, ER, pie, Gantt, mind map    |
+| PlantUML | sequence, class / object, use case, component / deployment, state, activity, mind map, WBS, `@startdot` |
+| Graphviz | graph / digraph, clusters, default attributes, edge chains, `rank=same`, record and HTML labels (text)  |
+
+Laid out by a built-in layered layout (like Mermaid's and Graphviz's `dot`), so drawings look close to, not exactly like, the originals. Not drawn: other Mermaid kinds (git graph, journey, timeline, C4…), other PlantUML kinds (Gantt, JSON / YAML, salt, timing), Graphviz engines other than `dot`.
+
+## Showing the SVG
+
+The SVG has a fixed `width` / `height`; to fit a column:
+
+```css
+figure.diagram svg { max-width: 100%; height: auto; }
+```
+
+## Safety
+
+Text from the source is escaped; only plain colors are kept from styles; the SVG has no scripts, links, `<foreignObject>` or external references. `renderTo` / `renderPage` only ever insert SVG built this way.
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,28 @@
+export type DiagramLang = 'mermaid' | 'plantuml' | 'graphviz';
+/** A drawing: a self-contained SVG document and its size in CSS pixels. */
+export interface Diagram {
+    svg: string;
+    width: number;
+    height: number;
+}
+/** The source cannot be drawn (unknown or unsupported diagram kind, syntax the reader does not follow). */
+export declare class DiagramError extends Error {
+    constructor(message: string);
+}
+/** The language of a diagram source: `@startuml`, `digraph {`, a Mermaid header (`graph TD`, `sequenceDiagram`…), or null. */
+export declare function detect(source: string): DiagramLang | null;
+/** Every drawing of a source (a PlantUML file or a DOT file may hold several). `lang`: detected when left out. */
+export declare function renderEach(source: string, lang?: DiagramLang): Diagram[];
+/** The (first) drawing of a source. */
+export declare function render(source: string, lang?: DiagramLang): Diagram;
+/** Draws a source into an element (its content is replaced). */
+export declare function renderTo(target: Element, source: string, lang?: DiagramLang): Diagram[];
+/**
+ * Draws the diagram blocks of a page: `<pre class="mermaid">`, `<div class="plantuml">`, `<pre><code
+ * class="language-dot">`, `<pre class="diagram">` (language detected)… Each becomes a
+ * `<figure class="diagram diagram-<lang>">`; a block that cannot be drawn stays and gets a `data-diagram-error`
+ * attribute with the reason. Returns how many were drawn. Browser only.
+ */
+export declare function renderPage(root?: ParentNode): number;
+/** A PNG of a drawing's SVG, `scale` times its size. Browser only. */
+export declare function toPng(svg: string, scale?: number): Promise<Blob>;