@openpowershift/logic-diagram-language 0.1.0

package/docs/user-guide.adoc

@@ -0,0 +1,318 @@
+= LDL User Guide
+:toc: macro
+:toclevels: 3
+:sectnums:
+:sectlinks:
+
+_A practical guide to writing Logic Diagram Language (LDL) source. It covers the
+language as implemented by this renderer. For the full formal grammar and the
+rendering contract, see the link:../spec/spec.adoc[LDL Specification]._
+
+toc::[]
+
+== Introduction
+
+LDL is a small text language for describing logic/protection schematics. You write
+boolean equations; the renderer draws the gates, routes the wires, and lays the
+diagram out automatically. There are no coordinates to place by hand — the layout
+engine positions everything and minimises wire crossings for you.
+
+The quickest way to try it is the in-browser playground (`npm run dev`): type LDL on
+the left, see the SVG update live on the right. Pick any built-in example from the
+dropdown to see a feature in action — every construct below appears in one.
+
+A minimal document is a single assignment:
+
+[source]
+----
+OUT = A AND B
+----
+
+This draws two boundary inputs `A` and `B`, an AND gate, and a boundary output `OUT`.
+
+== Expressions
+
+An assignment `NAME = EXPRESSION` is the core statement. The left-hand side names a
+signal; the right-hand side is a boolean expression built from **identifiers** and the
+operators `AND`, `OR`, and `NOT`.
+
+[source]
+----
+TRIP = OVERCURRENT AND NOT BLOCK
+----
+
+=== Operator precedence
+
+From highest to lowest: `NOT` (unary), then `AND`, then `OR`. Use parentheses to
+override precedence.
+
+[source]
+----
+CBFPS = AB AND DC OR (NOT DC AND GF)
+// parses as:  (AB AND DC) OR ((NOT DC) AND GF)
+----
+
+Only `AND`, `OR` and `NOT` are available as operators. A NAND / NOR is written with an
+explicit `NOT` around the group:
+
+[source]
+----
+NAND_RESULT = NOT (A AND B)
+NOR_RESULT  = NOT (A OR B)
+----
+
+=== Multi-line expressions
+
+A long expression may be broken across lines. A continuation line simply begins with
+whitespace; the leading operator joins it to the expression above.
+
+[source]
+----
+TRIP = PHASE AND ENABLE
+    OR (EARTH AND NOT BLOCK)
+    OR MANUAL
+----
+
+=== Nested / double negation
+
+`NOT NOT X` cancels to `X`. An odd number of `NOT` s reduces to a single inversion.
+
+== Inputs, outputs and intermediate signals
+
+Any bare identifier that is never assigned becomes a **boundary input** on the left.
+Any assigned name that is *not referenced anywhere else* becomes a **boundary output**
+on the right.
+
+A name that *is* referenced inside another assignment is a **consumed intermediate**:
+its driving gate fans out to the consumers, and it is **not** drawn as an output.
+
+[source]
+----
+TRIP      = OVERCURRENT OR NOT EARTH_FAULT   // consumed below -> internal, not an output
+MAIN_TRIP = TRIP AND (MANUAL OR REMOTE)      // not consumed  -> drawn as an output
+----
+
+=== Forcing an intermediate to an output
+
+To draw a consumed intermediate as an output *as well* as feeding its consumers, set
+`.OUT = TRUE`:
+
+[source]
+----
+B.OUT = TRUE     // B now appears as an output and still fans out to its consumers
+----
+
+=== Feedback / seal-in
+
+A name that references *itself* is a feedback loop (a seal-in), not a consumer, so it is
+always drawn. The renderer routes the self-reference as a loop-back wire.
+
+[source]
+----
+BFT = BFI OR BFT AND ((CB52A AND CB52ABFY) OR (I1I2 AND INOM))
+----
+
+== Labels
+
+Every input, output and named gate can carry a `.Name` (primary label) and a
+`.Description` (smaller secondary line). When the *labels* layer is on, the `.Name`
+replaces the bare identifier on the diagram.
+
+[source]
+----
+I1.Name        = "Close Switch"
+I1.Description = "(BI 3.20)"
+O1.Name        = "Launch Command"
+----
+
+=== TeX math in labels
+
+`.Name` and `.Description` support inline TeX math between dollar signs, rendered with
+MathJax:
+
+[source]
+----
+I1.Name        = "$I_a$"
+I1.Description = "Phase A current"
+O1.Name        = "$I > I_{set}$"
+O2.Name        = "$\overline{A \cdot B}$"
+----
+
+Subscripts (`I_{set}`), superscripts (`I^2`), Greek (`\Delta`, `\omega`), operators
+(`\cdot`, `\geq`, `\leq`), and the overline/negation bar (`\overline{A}`) are supported.
+Plain text and math may be mixed: `"Phase $I_a$ + $I_b$"`.
+
+== Naming gates
+
+A gate can be labelled. There are two ways.
+
+**Pass-through intermediate** — name the gate by assigning it to an intermediate, then
+label that name. The label is drawn at the gate's output and wires route around it.
+
+[source]
+----
+PH   = O51 OR O50 OR NEGSEQ      // this OR gate is now called "PH"
+PH.Name        = "Phase OC"
+PH.Description = "51/50/46"
+TRIP = PH AND ENABLE             // PH is consumed, so it stays internal and labelled
+----
+
+**Direct gate id** — give the gate an instance id inline with `AND#ID(...)` /
+`OR#ID(...)`, then attach a name/description to the id. No pass-through needed.
+
+[source]
+----
+OC = OR#OC1(I51, I50, I46)
+OC1.Name        = "Overcurrent"
+OC1.Description = "51/50N"
+----
+
+== Function blocks
+
+Beyond plain gates, expressions may call *function-block primitives* modelled on SEL
+SELogic elements. Each returns a logic signal, so it nests and composes like any
+sub-expression.
+
+[cols="1m,3m,4"]
+|===
+| Block | Call | Meaning
+
+| Timer | `TIMER(in, pu, do)`
+| Pickup/dropout timer. `pu` delays the rising edge, `do` delays the falling edge.
+  Settings are positional or named (`PU=`, `DO=`); a bare number is cycles; `0` = no
+  delay. Units: `cyc`, `ms`, `s`, `m`.
+
+| SR latch | `SR(set, reset)`
+| Set/reset latch. `.Q` (default) is the output, `.NQ` the inverted output Q̄.
+  Reset-dominant unless `DOMINANT=SET`. Only referenced outputs are drawn.
+
+| Rising edge | `RISING(in)`
+| One-interval pulse on each 0→1 transition of `in`.
+
+| Falling edge | `FALLING(in)`
+| One-interval pulse on each 1→0 transition of `in`.
+
+| Comparator | `COMPARE(plus, minus)`
+| Asserts when the first (analog) input ≥ the second. Drawn as a comparator triangle.
+
+| Generic block | `FB#id(a, NAME=b, ...).PORT`
+| A user-defined box with whatever inputs/outputs you need. Bare or `NAME=`-labelled
+  arguments are input ports; each `.PORT` you reference is an output port.
+|===
+
+Blocks nest and chain freely, and a named intermediate threaded into a block taps the
+same source (a fan-out) rather than being duplicated:
+
+[source]
+----
+A    = SR(COMPARE(IA, IPICKUP), RESET)
+TRIP = TIMER(A, 0, 30cyc)          // the SR latch feeds the timer; A is not duplicated
+----
+
+=== Block instance ids and settings
+
+A block may carry an explicit instance id (`BLOCK#id`) so it can be named or reused. The
+id then takes a name/description like any object. Referencing the same id twice reuses
+one block (e.g. an SR latch drawn with both `.Q` and `.NQ`):
+
+[source]
+----
+PERMIT  = SR#L1(START, STOP, DOMINANT=SET).Q
+BLOCKED = SR#L1(START, STOP).NQ
+L1.Name = "Enable Latch"
+----
+
+For a generic `FB`, the instance is de-duplicated by id, so multiple outputs bind to one
+box:
+
+[source]
+----
+TRIP  = FB#PROT(PHASE=IA, EARTH=IN, EN=ENABLE).TRIP
+ALARM = FB#PROT.ALARM
+PROT.Name        = "Feeder Protection"
+PROT.Description = "SEL-751A"
+----
+
+== Options
+
+Document-level directives, written `OPTION NAME = VALUE`, control rendering. Set each at
+most once; place them before the logic. Combine freely.
+
+[cols="1m,2m,4"]
+|===
+| Option | Values | Effect
+
+| `INVERSION` | `GATES` (default), `BUBBLES`
+| Draw `NOT` as separate NOT gates, or as inversion bubbles on the downstream port.
+
+| `GATE_INPUT_STYLE` | `EXPAND` (default), `BARS`
+| Grow multi-input gates vertically, or keep them 2-input-sized with input bars.
+
+| `PORT_STYLE` | `CIRCLE` (default), `SQUARE`
+| Port marker shape.
+
+| `OUTPUT_ORDER` | `AUTO` (default), `DECLARATION`
+| Reorder outputs by their driver to reduce crossings, or keep them in declared order.
+
+| `INPUT_ORDER` | `AUTO` (default), `DECLARATION`
+| Reorder gate inputs to minimise crossings, or keep declared order.
+
+| `COMPACTNESS` | `NORMAL`, `COMPACT_V`, `COMPACT_H`, `COMPACT`, `SPACIOUS`, or factors
+| Spacing preset, or explicit `vertical,horizontal` factors (e.g. `70,70` or `[60,60]`).
+
+| `COLUMN_SPACING` | `ADAPTIVE` (default), `UNIFORM`
+| Size each column gap to its content for a narrower diagram, or use a fixed column pitch.
+
+| `MARGIN` | integer px (default `8`)
+| Blank border around the diagram content in the rendered/exported SVG.
+
+| `WIRE_LABEL_LEADER` | `TRUE` (default), `FALSE`
+| Draw a dashed leader line from each consumed-intermediate net label to the wire it names, so the
+  label reads unambiguously even when placed in nearby clear space.
+
+| `HIDE_JUNCTIONS` | `TRUE`, `FALSE`
+| Hide every junction (fan-out) dot.
+|===
+
+NOTE: `INPUT_ORDER`, `OUTPUT_ORDER` and `COLUMN_SPACING` default to the crossing-minimising /
+content-sized behaviour. Set them to `DECLARATION` / `UNIFORM` on a diagram to opt back out.
+
+[source]
+----
+OPTION INVERSION = BUBBLES
+OPTION GATE_INPUT_STYLE = BARS
+OPTION COLUMN_SPACING = ADAPTIVE
+----
+
+== Styling
+
+Declare an object with an id and target it from a `STYLE` block of raw CSS. Every symbol
+also carries stable classes (`ldl-gate-and`, `ldl-port`, `ldl-wire`, …) for broad rules.
+
+[source]
+----
+STYLE
+  #G1 { stroke: #c0392b; stroke-width: 2; }
+  .ldl-gate-or { fill: #eef; }
+END STYLE
+
+AND#G1
+TRIP = A AND B
+----
+
+== Comments
+
+[source]
+----
+// line comment
+/* block comment,
+   which may /* nest */ */
+----
+
+== Not covered here
+
+The link:../spec/spec.adoc[specification] also describes constructs that are reserved or
+planned but **not yet implemented** by this renderer: the `NAND`/`NOR`/`XOR`/`XNOR`
+operators, `CONNECT` statements, custom `SYMBOL` definitions, `IMPORT`/`STYLESHEET`,
+hyperlinks (`.LINK`), and bidirectional ports. Use the equivalent working forms above
+(e.g. `NOT (A AND B)` for NAND).

package/package.json

@@ -0,0 +1,78 @@
+{
+  "name": "@openpowershift/logic-diagram-language",
+  "version": "0.1.0",
+  "description": "Render SEL-style protection-relay logic diagrams from a compact text language (LDL) to SVG, PNG, or PDF.",
+  "keywords": [
+    "logic-diagram",
+    "protection-relay",
+    "sel",
+    "svg",
+    "schematic",
+    "ladder-logic",
+    "diagram"
+  ],
+  "license": "MIT",
+  "author": "Daniel Mulholland",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/openpowershift/logic-diagram-language.git"
+  },
+  "homepage": "https://github.com/openpowershift/logic-diagram-language#readme",
+  "type": "module",
+  "engines": {
+    "node": ">=20"
+  },
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "sideEffects": false,
+  "files": [
+    "dist",
+    "docs",
+    "spec",
+    "README.md",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "dev": "vite",
+    "build": "tsc && vite build",
+    "build:lib": "tsc -p tsconfig.lib.json",
+    "prepublishOnly": "npm run build:lib",
+    "preview": "vite preview",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:visual": "playwright test",
+    "typecheck": "tsc --noEmit",
+    "lint": "eslint src/"
+  },
+  "dependencies": {
+    "@mathjax/src": "^4.1.2",
+    "jspdf": "^4.2.1"
+  },
+  "devDependencies": {
+    "@codemirror/commands": "^6.8.0",
+    "@codemirror/language": "^6.11.0",
+    "@codemirror/state": "^6.5.0",
+    "@codemirror/view": "^6.36.0",
+    "@playwright/test": "^1.52.0",
+    "@types/node": "^26.0.0",
+    "codemirror": "^6.0.0",
+    "eslint": "^9.0.0",
+    "jsdom": "^29.1.1",
+    "lit": "^3.2.0",
+    "typescript": "^5.7.0",
+    "typescript-eslint": "^8.62.0",
+    "vite": "^6.3.0",
+    "vitest": "^3.2.0"
+  }
+}

package/spec/render.sh

@@ -0,0 +1,22 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+OUTPUT_DIR="${SCRIPT_DIR}/build"
+
+command -v asciidoctor >/dev/null 2>&1 || {
+  echo "Error: asciidoctor is required. Install with: gem install asciidoctor"
+  exit 1
+}
+
+mkdir -p "$OUTPUT_DIR"
+
+echo "Rendering spec.adoc -> HTML"
+asciidoctor \
+  --attribute sectnums \
+  --attribute sectlinks \
+  --attribute toclevels=4 \
+  --destination-dir "$OUTPUT_DIR" \
+  "${SCRIPT_DIR}/spec.adoc"
+
+echo "Output: ${OUTPUT_DIR}/spec.html"

package/spec/sections/attributes.adoc

@@ -0,0 +1,80 @@
+== Attributes
+
+Attributes are named values associated with an object or port. They are rendered inside the symbol's SVG using placeholder substitution.
+
+=== Attribute Declaration
+
+[literal]
+....
+OBJECT.ATTRIBUTE_NAME = VALUE
+....
+
+=== Name and Description Attributes
+
+Ports and expression outputs may carry `.Name` and `.Description` metadata:
+
+[literal]
+....
+I1.Name = "CBQ 00 Open"
+I1.Description = "(BI 3.1)"
+O1.Name = "Output"
+O1.Description = "(BO 3.2)"
+....
+
+* `.Name` -- A human-readable label. Replaces the bare identifier on the diagram when the labels layer is active.
+* `.Description` -- Supplementary annotation text, shown in a smaller font below the name.
+
+These attributes are rendered as `ldl-label` class elements within the SVG and are controlled by the labels layer (see <<layout-rules>>).
+
+=== TeX in Labels
+
+Both `.Name` and `.Description` values support inline TeX math notation enclosed in dollar signs:
+
+[literal]
+....
+I1.Name = "$I_a$"
+I1.Description = "Phase A current"
+O1.Name = "$I > I_{set}$"
+O1.Description = "Overcurrent trip"
+....
+
+* Inline math is delimited by `$...$` within the attribute value string.
+* A literal `$` outside math delimiters may be produced via `\` `$` in LDL source (the parser passes all `\` sequences through to the segment parser except `\"`).
+* Supported TeX constructs (via MathJax v4 with `base` and `ams` packages):
+  ** Subscripts: `$I_{set}$`
+  ** Superscripts: `$I^2$`
+  ** Greek letters: `$\Delta$`, `$\Theta$`, `$\alpha$`, `$\omega$`, etc.
+  ** Mathematical operators: `$\cdot$` (·), `$\geq$` (≥), `$\leq$` (≤), `$\neq$` (≠), etc.
+  ** Overline (negation bar): `$\overline{A}$`
+  ** Mixed content: `"Phase $I_a$ + $I_b$"` → plain text interspersed with math
+
+* Rendering:
+  ** Input port labels are right-aligned (text-anchor: end).
+  ** Output port labels are left-aligned (text-anchor: start).
+  ** Math content is rendered via MathJax as standalone `<svg>` elements, embedded inline within the label `<g>`. Each math SVG is positioned relative to the text baseline using a `transform` attribute, with the baseline offset derived from the MathJax `viewBox`.
+  ** The math height is computed from the SVG's intrinsic dimensions and contributes to the overall label height, which may cause the containing gate to expand.
+
+=== Other Attribute Examples
+
+[literal]
+....
+SVT#1.PICKUP = 30 s
+SVT#1.DROPOUT = 10 s
+TIMER#T2.SETPOINT = 1.5 s
+RELAY#R5.NAME = "Main Trip"
+....
+
+=== Substitution in Symbols
+
+Inside an SVG symbol definition, attribute placeholders use double-brace syntax:
+
+[literal]
+....
+<text>{{PICKUP}}</text>
+....
+
+When the object is instantiated, `{{PICKUP}}` is replaced with the attribute value `30 s`.
+
+If an attribute is declared but no placeholder exists in the symbol SVG, the value is discarded silently.
+
+If a placeholder exists in the symbol SVG but no attribute is provided, the placeholder is replaced with an empty string.

package/spec/sections/connections.adoc

@@ -0,0 +1,39 @@
+== Connections
+
+=== Implicit Connections
+
+When an expression assigns an output, the connections are implied:
+
+[literal]
+....
+CBFPS = A AND B
+....
+
+Creates:
+
+* Input port `A` on the diagram boundary.
+* Input port `B` on the diagram boundary.
+* An AND gate with inputs connected to `A` and `B`.
+* Output port `CBFPS` on the diagram boundary, connected to the AND gate output.
+
+=== Explicit Connections
+
+A `CONNECT` statement creates a wire between two ports:
+
+[literal]
+....
+CONNECT AND#G1.out AND#G2.in1
+....
+
+Or using simplified dot notation:
+
+[literal]
+....
+CONNECT G1.out G2.in1
+....
+
+When the object symbol is unambiguous, the symbol type may be omitted.
+
+=== Output Fan-Out
+
+A single output port may connect to multiple input ports. The renderer handles wire routing automatically.