lispgram 0.10.0

package/README.md

@@ -0,0 +1,326 @@
+# lispgram
+
+`lispgram` is a small JavaScript package that gives you:
+
+- a user-facing lispy surface language
+- a compiler from that surface language into NCF
+- a lightweight SVG visualizer backed by the constraint layout engine that can render either Lispgram source or raw NCF
+
+The public compiler now has three explicit syntaxes:
+
+```text
+Lispgram surface   human-friendly input
+Semantic core      official tiny fact language: node, arrow, contains
+NCF                visualization-oriented graph syntax
+```
+
+It also exposes optional interpretations of the semantic core. The first is the normalized tree interpretation, which derives a single-owner containment tree using a generated root and least-common-ancestor ownership for arrows.
+
+NCF remains the rendering representation. Author-facing source compiles through the semantic core into:
+
+```lisp
+(cy
+  (nodes ...)
+  (edges ...))
+```
+
+## Public npm surface
+
+The published package intentionally exposes only the author-facing API:
+
+```js
+import lispgram from "lispgram";
+import { parseDocument, compileLispgram, toNCF, toNCFDoc, toLayerSexp } from "lispgram/surface";
+import { render, initialize, createDiagramSvg } from "lispgram/layout";
+import { diagram, registerDiagram } from "lispgram/interaction";
+```
+
+The package export map is limited to:
+
+```text
+lispgram
+lispgram/surface
+lispgram/layout
+lispgram/interaction
+lispgram/package.json
+```
+
+Internal layer modules are not public API and are not exported as package subpaths. The npm package still exposes normal runtime functionality through the public surface, layout, and interaction entry points, including layer translation output for devtools via `toLayerSexp()`.
+
+JavaScript packages cannot fully prevent reverse engineering of code that runs on the client or is installed locally. The package boundary therefore focuses on minimizing the supported import surface, excluding examples/tests/devtools and maintainer docs from npm, and shipping only the grammar/layout authoring docs needed by package consumers.
+
+## Supported surface forms
+
+```lispgram
+; initialize a node
+(P)
+
+; initialize a node with a label
+(P{hi})
+
+; initialize a node with label plus fields
+(P{Person { color blue rank 2 }})
+
+; fully explicit data field map
+(P{{ label Person color blue rank 2 }})
+
+; parent/child relationships
+(X Y Z)
+(X Y (Z P))
+(X (Y (Z P)))
+
+; arrows
+(-> e A B)
+(-> e{hi} A B)
+(-> e{maps { color purple weight 2 }} A B)
+
+; fan-out
+(-> e A [B C D])
+
+; fan-in
+(-> e [A B C] D)
+```
+
+## What this starter implements
+
+- nodes and arrows with optional `{label}` suffixes and richer `{label { key value ... }}` / `{{ key value ... }}` field maps
+- parent/child trees compiled to `(@parent X)`
+- arrows compiled as NCF arrow carrier nodes with:
+  - `(@class "arrow")`
+  - `(@class "arrowFrom")`
+  - `(@class "arrowTo")`
+- fan-in / fan-out expansion into multiple arrows that keep the same visible label
+- an official semantic core grammar with only `node`, `arrow`, and `contains`
+- semantic core parsing/emitting for external rule or constraint systems
+- a normalized tree interpretation for derived ownership/layout
+- containment of arrows as well as object nodes in the semantic core
+- raw NCF passthrough
+- browser auto-initialization for `<pre class="lispgram">...</pre>` blocks
+- heuristic SVG routing for parallel, anti-parallel, and higher-order arrows
+- compound/container labels rendered only in the header band
+
+## Install
+
+```bash
+npm install lispgram
+```
+
+## Browser usage
+
+```html
+<pre class="lispgram">
+(Y X)
+(-> f A B)
+(-> g B A)
+(-> h X Y)
+</pre>
+
+<script type="module">
+  import lispgram from "lispgram";
+  lispgram.initialize({
+  startOnLoad: true,
+  showArrowGlyphs: true,
+  clickToFocus: true
+});
+</script>
+```
+
+## Library usage
+
+```js
+import lispgram from "lispgram";
+
+const source = `
+  (Y X)
+  (-> f A B)
+  (-> g B A)
+  (-> h X Y)
+`;
+
+const ncfString = lispgram.toNCF(source);
+const ncfDoc = lispgram.toNCFDoc(source);
+```
+
+Render into a DOM node:
+
+```js
+import { render } from "lispgram";
+
+render(document.querySelector("#app"), `
+  (P A B)
+  (-> left A B)
+  (-> right B A)
+`);
+```
+
+
+## Interactive diagrams
+
+Interactivity is attached from JavaScript, not from Lispgram syntax. Give a render a stable `diagramId`, or set `data-lispgram-diagram` on an auto-rendered `<pre>`, then select semantic elements by their normalized `data` fields.
+
+```js
+import { render, diagram } from "lispgram";
+
+render(document.querySelector("#app"), `
+(lg-core
+  (node (A (@data clickable true info "Node A")))
+  (node B)
+  (arrow (f (@data clickable true info "A to B")) A B))
+`, { diagramId: "P" });
+
+diagram("P")
+  .select((elem) => elem.data.clickable === true)
+  .addonclick((elem) => alert(elem.data.info));
+```
+
+Each selected `elem` describes the semantic cell rather than the raw SVG node:
+
+```js
+{
+  id: "f",
+  type: "arrow",        // or "node"
+  kind: "arrow",
+  data: { info: "A to B" },
+  source: "A",
+  target: "B",
+  parent: null,
+  elements: [/* generated SVG path/label/glyph elements */]
+}
+```
+
+You can also select with a small object matcher:
+
+```js
+diagram("P")
+  .select({ type: "arrow", data: { clickable: true } })
+  .addOnClick((elem) => console.log(elem.source, elem.target));
+```
+
+For auto-rendered diagrams:
+
+```html
+<pre class="lispgram" data-lispgram-diagram="P">
+(A{{ clickable true info "Node A" }} B)
+</pre>
+```
+
+Interaction behavior is available through `lispgram/interaction` and through the default click-to-focus SVG renderer.
+
+## API
+
+The public API is intentionally small but includes the normal runtime features needed by the standalone devtool. Internal solver and layer implementation modules are not exported by the package.
+
+### Surface entry point
+
+```js
+import { parseDocument, compileLispgram, toNCFDoc, toNCF, sourceToSemanticCore, toLayerSexp } from "lispgram/surface";
+```
+
+`parseDocument(source)` parses Lispgram surface syntax. `compileLispgram(source)` returns the parsed AST, surface facts, semantic core, and normalized NCF document. `toNCFDoc(source)` accepts Lispgram surface, wrapped semantic core, or raw NCF and returns the normalized document object. `toNCF(source)` emits textual NCF. `sourceToSemanticCore(source)` returns the tiny semantic-core fact model for Lispgram or wrapped semantic-core input. `toLayerSexp(source)` returns author/devtool layer text including Surface AST, Surface Facts, Semantic Core, Normalized Tree, NCF Model, and NCF Text when those layers are available for the input form.
+
+### Layout entry point
+
+```js
+import { render, renderElement, initialize, createDiagramSvg } from "lispgram/layout";
+```
+
+`render(target, source, options?)` renders Lispgram or NCF into a DOM target. `renderElement(sourceElement, options?)` renders one source element. `initialize(options?)` auto-renders matching elements such as `<pre class="lispgram">`. `createDiagramSvg(doc, options?)` renders an already-normalized NCF document into an SVG element.
+
+### Interaction entry point
+
+```js
+import { diagram, registerDiagram, unregisterDiagram, listDiagrams } from "lispgram/interaction";
+```
+
+`diagram(id?)` returns an interactive diagram controller. Controllers support `.select(predicateOrMatcher)`, `.selectAll()`, `.get(id)`, `.on(eventName, selector, handler)`, `.addOnClick(selector, handler)`, and `.clearInteractions()`. `registerDiagram()` registers an already-rendered document/SVG pair; `render()` and `initialize()` call it automatically.
+
+### Root entry point
+
+```js
+import lispgram, { render, toNCF } from "lispgram";
+```
+
+The root entry point re-exports the public surface, layout, and interaction APIs only. It does not export internal layer emitters, solver internals, or devtool diagnostic helpers.
+
+## Notes
+
+This package is intentionally small and readable. It is a good base for:
+
+- improving the layout engine
+- extending the surface language
+- integrating external rule/constraint systems over the semantic core
+- adding richer styling directives
+- expanding support for higher-order arrows and editor UX
+
+
+## Dev visualizer
+
+The repository includes a browser-based dev tool with Lispgram + raw NCF input, compiled/normalized NCF output, orthogonal routing, wiring overlay, arrow-node glyphs, click focus, zoom, and fit-to-view.
+
+Run it from the repo with:
+
+```bash
+npm run dev:visualizer
+```
+
+Then open:
+
+```
+http://localhost:4173/examples/devtool.html
+```
+
+The dev tool accepts Lispgram surface syntax, wrapped semantic core `(lg-core ...)`, or raw NCF. When the input is Lispgram, it compiles it through the semantic core first and shows both the semantic core and normalized NCF in the side panel.
+
+The repo devtool can use source-only helpers during development, while the standalone devtool uses the public `toLayerSexp()` API from the npm package.
+
+## Development
+
+```bash
+npm test
+```
+
+
+## Focus behavior
+
+When `clickToFocus` is enabled, clicking a node, compound/container, or arrow focuses that element within its own diagram. The focused element, its incident arrows, and immediate source/target nodes or arrows stay prominent while unrelated elements dim. This includes arrow-between-arrow routes, where the source and target arrows are treated as immediate endpoints. `clickToFocus` defaults to `true`; set `data-lispgram-click-focus="false"` or pass `clickToFocus: false` to disable it.
+
+Click hit-testing uses a transparent interaction layer above the rendered diagram. Ordinary nodes are given priority over arrows, arrows over container interiors, and deeper containers over their ancestors. This keeps large ancestor containers clickable without letting them steal clicks from nested containers such as `BuildSystem`, `ExternalDependencies`, or `GuileBinding`.
+
+## Demo
+
+go to repo root directory
+
+```bash
+python -m http.server
+```
+
+navigate to examples/basic.html in browser
+
+## Browser script Drop-in use
+
+```html
+
+<pre class="lispgram">
+  (lispgram
+    (A)
+    (-> e X Y)
+  )
+</pre>
+<script type="module">
+  import lispgram from "https://unpkg.com/lispgram@latest/dist/index.js";
+    lispgram.initialize({
+    startOnLoad: true,
+    showArrowGlyphs: true,
+    clickToFocus: true,
+    arrowGlyphRadius: 5.75
+  });
+</script>
+```
+
+The standalone devtool at `examples/devtool-standalone.html` is static-site friendly: it dynamically imports `https://unpkg.com/lispgram@latest/dist/index.js` and uses public APIs, including `toLayerSexp()`, so you can host that single HTML file independently after publishing the package to npm.
+
+## Constraint layout foundation
+
+This version uses the constraint-layout engine in `src/layers/08-constraint-layout` as the main SVG layout backend. The default small-core inference now projects arrows through containment, so arrows from leaves in one subtree to leaves in another subtree can compact their ancestor containers into readable columns instead of long vertical stacks. The small Lispgram core remains the preferred authoring surface: tree forms and ordinary arrows are inferred into containment scopes, self-loops, parallel/anti-parallel lanes, arrow-to-arrow route strata, and fallback rank constraints. The engine models nodes and containers as boxes, islands as first-class layout views, relative constraints as compiler output, and arrows as addressable routes with anchors. Boundary attachments place external source subtrees outside the selected side and then draw rounded orthogonal routes through side-ports. Template `:container` declarations are active visual shells for the template core members. This enables autodetected self loops, arrows between arrows, route dependency strata, curved cone legs, distinct route-to-node anchors, and categorical templates such as product, coproduct, equalizer, pullback, pushout, exponential, and Hasse-style ranked diagrams.
+
+Open `examples/constraint-layout-foundation.html` from a source checkout for a browser demo. See `LAYOUT_LANGUAGE.md` for the `$layout` surface syntax. The repository also contains maintainer-oriented layout-engine notes for contributors; those internal docs are not part of the minimal npm runtime surface.