@openpowershift/logic-diagram-language 0.1.0

package/spec/sections/options.adoc

@@ -0,0 +1,146 @@
+== Options
+
+*Options* are document-level directives that control rendering behaviour.
+They MUST appear before any expressions, object declarations, or style blocks.
+
+=== Syntax
+
+[source]
+OPTION NAME = VALUE
+
+Options are set once per document. If the same option appears multiple times,
+the last occurrence wins.
+
+=== Available Options
+
+[cols="1m,2m,2m,1m"]
+|===
+| Option | Values | Description | Default
+
+| INVERSION
+| GATES
+| NOT operations render as separate NOT gate symbols (current behaviour)
+| GATES
+
+| INVERSION
+| BUBBLES
+| NOT operations render as inversion circles (bubbles) on the input port of the downstream gate
+| --
+
+| PORT_STYLE
+| CIRCLE
+| Port markers are rendered as circles (r=3)
+| CIRCLE
+
+| PORT_STYLE
+| SQUARE
+| Port markers are rendered as squares (5×5)
+| --
+
+| GATE_INPUT_STYLE
+| EXPAND
+| Multi-input gates expand vertically to accommodate all input ports with even spacing
+| EXPAND
+
+| GATE_INPUT_STYLE
+| BARS
+| Multi-input gates remain at base size (2-input height). Inputs beyond the first two connect via vertical input bars on the left side of the gate body
+| --
+
+| LABEL_STYLE
+| SIDE
+| Input labels appear to the left of the input port; output labels to the right (current behaviour)
+| SIDE
+
+| LABEL_STYLE
+| ABOVE_BELOW
+| Input labels appear above/below the port, closer to the gate body
+| --
+
+| OUTPUT_ORDER
+| AUTO
+| Output ports are reordered vertically by the position of the gate that drives them, so output wires fan out without crossing (the barycentre method already used for inputs)
+| AUTO
+
+| OUTPUT_ORDER
+| DECLARATION
+| Output ports are stacked top-to-bottom in the order the outputs are declared (O1, O2, …), each aligned to its source where possible
+| --
+
+| INPUT_ORDER
+| AUTO
+| Input ports are reordered vertically using the Sugiyama barycentre method to minimise wire crossings
+| AUTO
+
+| INPUT_ORDER
+| DECLARATION
+| Input ports keep their declared (natural-sorted) order; gate rows still follow from that fixed order
+| --
+
+| COMPACTNESS
+| NORMAL
+| Standard spacing on both axes
+| NORMAL
+
+| COMPACTNESS
+| COMPACT_V
+| Tighter vertical (row) spacing for a denser diagram (still respects minimum gaps, so wires never overlap)
+| --
+
+| COMPACTNESS
+| COMPACT_H
+| Tighter horizontal (column) spacing
+| --
+
+| COMPACTNESS
+| COMPACT
+| Tighter spacing on both axes (COMPACT_V + COMPACT_H)
+| --
+
+| COMPACTNESS
+| SPACIOUS
+| Looser vertical spacing for an airier diagram
+| --
+
+| COMPACTNESS
+| _factors_
+| Explicit spacing factors `vertical,horizontal` (e.g. `70,70` or `[60,60]`); a value > 3 is a percentage (70 → 0.70), otherwise a raw factor. A single value applies to both axes.
+| --
+
+| COLUMN_SPACING
+| ADAPTIVE
+| Size each inter-column gap to its content (gate widths + the fan-in channels that column needs), so simple columns pack tighter and the diagram is materially narrower. Never wider than UNIFORM, and validated so it introduces no dogleg, entrance violation, overlap or crossing.
+| ADAPTIVE
+
+| COLUMN_SPACING
+| UNIFORM
+| Fixed column pitch — every inter-column gap is the same width.
+| --
+
+| MARGIN
+| _integer px_
+| Blank border (in pixels) drawn around the diagram content in the rendered/exported SVG. Labels are already inside the content bounds, so this is a pure outer frame.
+| 8
+
+| WIRE_LABEL_LEADER
+| TRUE / FALSE
+| Draw a dashed leader line (with an endpoint dot on the wire) from each consumed-intermediate net label to the net it names. The label is seated a readable distance off the wire so the connector is visible; useful where a wide label cannot sit directly on a congested fan-out junction.
+| TRUE
+|===
+
+=== Examples
+
+[source]
+OPTION INVERSION = BUBBLES
+OPTION PORT_STYLE = SQUARE
+OPTION GATE_INPUT_STYLE = BARS
+
+An LDL file may combine options freely:
+
+[source]
+OPTION INVERSION = BUBBLES
+OPTION GATE_INPUT_STYLE = BARS
+I1.Name = "Start"
+I2.Name = "Stop"
+I3.Name = "Reset"
+O1 = I1 AND I2 AND NOT I3

package/spec/sections/ports.adoc

@@ -0,0 +1,77 @@
+== Ports
+
+A *port* is a named connection point on an object. Ports are either inputs, outputs, or bidirectional.
+
+=== Port Types
+
+[cols="1m,3m,3m"]
+|===
+| Keyword | Direction | Semantics
+| `INPUT` | Inward | Receives a signal
+| `OUTPUT` | Outward | Emits a signal
+| `BIDI` | Both | Bidirectional (for Bus or analog)
+|===
+
+=== Port Declarations
+
+Ports are declared within a symbol definition (see <<symbol-definitions>>) or explicitly on an object:
+
+[literal]
+....
+SVT#1.INPUT = A OR B
+SVT#1.OUTPUT = C
+....
+
+The dot notation `OBJECT.PORT` references a specific port.
+
+=== Port Metadata
+
+Ports may carry human-readable metadata using `.Name` and `.Description` attributes:
+
+[literal]
+....
+I1.Name = "CBQ 00 Open"
+I1.Description = "(BI 3.1)"
+O1.Name = "Output"
+O1.Description = "(BO 3.2)"
+....
+
+* `.Name` -- A human-readable label for the port. Displayed as the primary label on the diagram when the labels layer is active.
+* `.Description` -- Supplementary text (e.g. a signal reference). Displayed as a secondary annotation when the labels layer is active.
+
+When labels are **not** shown, the bare identifier (e.g. `I1`, `O1`) is used as a compact reference. When labels **are** shown, the `.Name` replaces the identifier on the diagram, and `.Description` is shown in a smaller font below it.
+
+=== Implicit Ports
+
+For built-in gate symbols, ports are implicit based on position:
+
+* **AND**, **NAND**, **OR**, **NOR**, **XOR**, **XNOR**: Left-side inputs, right-side output.
+* **NOT**: Left-side input, right-side output.
+
+The number of inputs on gate symbols is determined by the expression arity.
+
+=== Port Naming Convention
+
+When the expression `CBFPS = A AND B` is given, the renderer creates an AND gate with two implicit inputs labeled `A` and `B` and one implicit output labeled `CBFPS`.
+
+When a port has a `.Name` attribute, that name replaces the identifier as the display label:
+
+[literal]
+....
+I1.Name = "Close Switch"
+O1 = I1 AND I2
+....
+
+In this case the input port is shown as "Close Switch" rather than `I1`.
+
+=== Port Style Attribute
+
+An individual port's marker shape can be overridden from the document default set by `OPTION PORT_STYLE`:
+
+[literal]
+....
+I1.Style = SQUARE
+O1.Style = CIRCLE
+....
+
+When set, this overrides the `OPTION PORT_STYLE` for that specific port. Valid values are `CIRCLE` and `SQUARE`.

package/spec/sections/rendering-contract.adoc

@@ -0,0 +1,11 @@
+== Rendering Contract
+
+The renderer (TypeScript toolchain) is responsible for:
+
+. Parsing LDL source.
+. Instantiating objects and resolving expressions into gate networks.
+. Loading SVG symbols and performing attribute substitution.
+. Routing wires between ports.
+. Emitting SVG and PDF output.
+
+The renderer is NOT specified by this document; only the language it consumes.

package/spec/sections/revision-history.adoc

@@ -0,0 +1,9 @@
+== Revision History
+
+[cols="1m,3m,5m"]
+|===
+| Version | Date | Description
+| 0.1.0-draft | 2026-06-13 | Initial specification
+| 0.2.0-draft | 2026-06-13 | Added port metadata (.Name, .Description), layout rules, layer visibility
+| 0.3.0-draft | 2026-06-14 | Added OPTION directives, inversion bubbles, input bars, port styles, minimum dogleg height, wire-wire crossing avoidance
+|===

package/spec/sections/styling.adoc

@@ -0,0 +1,83 @@
+== Styling
+
+=== ID-Based Selection
+
+Every object declared with `#ID` can be styled via CSS:
+
+[literal]
+....
+AND#G1 { stroke: red; }
+SVT#1  { fill: yellow; }
+....
+
+=== CSS Injection
+
+Style rules are provided in the LDL source:
+
+[literal]
+....
+STYLE
+  #G1 { stroke: red; stroke-width: 3; }
+  #T2 { fill: #ffffcc; }
+END STYLE
+....
+
+Or loaded from an external stylesheet:
+
+[literal]
+....
+STYLESHEET "path/to/styles.css"
+....
+
+=== Default CSS Classes
+
+The renderer MUST apply the following CSS classes:
+
+[cols="1m,3m"]
+|===
+| Class | Applied to
+| `ldl-symbol` | Every symbol `<g>` element
+| `ldl-port` | Every port marker
+| `ldl-input` | Input port markers
+| `ldl-output` | Output port markers
+| `ldl-attribute` | Attribute text elements
+| `ldl-id` | ID/identifier label text elements (ids layer)
+| `ldl-label` | `.Name` and `.Description` text elements (labels layer)
+| `ldl-name` | Port `.Name` text elements
+| `ldl-description` | Port `.Description` text elements
+| `ldl-wire` | Wire/connection path elements
+| `ldl-gate-and` | AND gate symbols
+| `ldl-gate-or` | OR gate symbols
+| `ldl-gate-not` | NOT gate symbols
+| `ldl-bubble` | Inversion circle on a gate input port (BUBBLES mode)
+| `ldl-input-bar` | Vertical input bar on a multi-input gate (BARS mode)
+| `ldl-bar-stub` | Horizontal stub connecting a bar tap to the gate body (BARS mode)
+| `ldl-port-circle` | Circular port marker (PORT_STYLE = CIRCLE)
+| `ldl-port-square` | Square port marker (PORT_STYLE = SQUARE)
+| `ldl-math` | Inline TeX math `<g>` group within a label
+|===
+
+Selectors combining these classes with `#ID` provide fine-grained control:
+
+[source,css]
+----
+.ldl-gate-and#G1 { fill: blue; }
+.ldl-port.ldl-output { fill: green; }
+----
+
+=== Layer Visibility
+
+Layers are toggled via CSS on the root `<svg>` element:
+
+[source,css]
+----
+/* Show labels, hide bare IDs */
+svg.ldl-layer-labels .ldl-label { display: block; }
+svg.ldl-layer-labels .ldl-id { display: none; }
+
+/* Hide labels, show bare IDs */
+svg:not(.ldl-layer-labels) .ldl-label { display: none; }
+svg:not(.ldl-layer-labels) .ldl-id { display: block; }
+----
+
+The renderer provides UI controls to toggle these layers.

package/spec/sections/svg-symbol-specification.adoc

@@ -0,0 +1,149 @@
+== SVG Symbol Specification
+
+=== Structure
+
+Each SVG symbol file MUST contain:
+
+. A `<g>` element with class `ldl-symbol`.
+. One `<circle>` or `<rect>` per port, with class `ldl-port` and a `data-port` attribute matching the port name.
+. Optional `<text>` elements with `{{PLACEHOLDER}}` for attribute substitution.
+. A `<text>` element with `{{ID}}` to show the object's identifier label.
+
+=== Port Markers
+
+Port markers indicate where connections attach:
+
+[literal]
+....
+<circle class="ldl-port ldl-input" data-port="in" cx="0" cy="20" r="3"/>
+<circle class="ldl-port ldl-output" data-port="out" cx="80" cy="20" r="3"/>
+....
+
+=== Attribute Placeholders
+
+[literal]
+....
+<text class="ldl-attribute" x="40" y="30">{{PICKUP}}</text>
+<text class="ldl-attribute" x="40" y="45">{{DROPOUT}}</text>
+....
+
+=== ID Label Placeholder
+
+[literal]
+....
+<text class="ldl-id" x="40" y="10">{{ID}}</text>
+....
+
+=== Name and Description Labels
+
+For input and output ports, the renderer generates labels from `.Name` and `.Description` attributes:
+
+[literal]
+....
+<text class="ldl-label ldl-name" x="0" y="-5">{{NAME}}</text>
+<text class="ldl-label ldl-description" x="0" y="12" font-size="9">{{DESCRIPTION}}</text>
+....
+
+Elements with class `ldl-label` are part of the *labels layer* and controlled by the `ldl-layer-labels` CSS class.
+Elements with class `ldl-id` are part of the *ids layer* and controlled by the `ldl-layer-ids` CSS class.
+
+=== SVG File Example
+
+A minimal AND gate symbol (`symbols/and.svg`):
+
+[source,xml]
+----
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 100 60">
+  <g class="ldl-symbol">
+    <path d="M0,0 L40,0 A30,30 0 0,1 40,60 L0,60 Z"
+          fill="white" stroke="black" stroke-width="2"/>
+    <text class="ldl-id" x="20" y="-5">{{ID}}</text>
+    <circle class="ldl-port ldl-input" data-port="in1" cx="0" cy="15" r="3"/>
+    <circle class="ldl-port ldl-input" data-port="in2" cx="0" cy="45" r="3"/>
+    <circle class="ldl-port ldl-output" data-port="out" cx="100" cy="30" r="3"/>
+  </g>
+</svg>
+----
+
+=== Inversion Bubble Rendering
+
+When `OPTION INVERSION = BUBBLES` is set, each bubbled port renders as an open circle with radius `BUBBLE_R` (4px).
+
+==== Input-Side Bubble
+
+An input-side bubble (on a gate input port or output node's input port) renders as:
+
+. An open circle (stroke, no fill) with radius `BUBBLE_R`.
+. Position: centered on the port Y, offset left of the gate body edge. The bubbled input port shifts left by `BUBBLE_R * 2` so that the bubble sits between the wire endpoint and the gate body.
+. The wire connects to the left edge of the bubble.
+. The bubble's right edge touches the gate body edge.
+
+SVG example (input-side bubble on a gate):
+
+[source,xml]
+----
+<circle class="ldl-bubble ldl-input" data-port="in_1"
+        cx="-8" cy="30" r="4"
+        fill="none" stroke="#2c3e50" stroke-width="1.5"/>
+----
+
+==== Output-Side Bubble
+
+An output-side bubble (on a gate output port) renders as:
+
+. An open circle (stroke, no fill) with radius `BUBBLE_R`.
+. Position: centered on the port Y, offset right of the gate body edge. The bubbled output port shifts right by `BUBBLE_R * 2` so that the bubble sits between the gate body and the wire start point.
+. The gate body's right edge connects to the bubble's left edge (conceptually; the wire starts from the bubble's right edge).
+. The wire starts from the right edge of the bubble.
+
+SVG example (output-side bubble on a gate):
+
+[source,xml]
+----
+<circle class="ldl-bubble ldl-output" data-port="out"
+        cx="108" cy="30" r="4"
+        fill="none" stroke="#2c3e50" stroke-width="1.5"/>
+----
+
+The wire from a bubbled output port starts at the bubble's right edge (`cx + BUBBLE_R`), not at the gate body edge.
+
+=== Input Bar Rendering
+
+When `OPTION GATE_INPUT_STYLE = BARS` is set, multi-input gates (3+ inputs) render a vertical input bar:
+
+. A vertical line from `(barX, gateTop)` to `(barX, gateBottom)`, where `barX = gateX - 12`.
+. Stroke-width: 2.5, stroke: `#2c3e50`.
+. Horizontal stubs at each bar tap Y position, from `barX` to `gateX - 6`.
+. Input wires connect at the left end of each stub (`barX`, tapY).
+
+SVG example:
+
+[source,xml]
+----
+<!-- Vertical input bar -->
+<line class="ldl-input-bar" x1="-12" y1="0" x2="-12" y2="60"
+      stroke="#2c3e50" stroke-width="2.5"/>
+<!-- Horizontal stub for 3rd input -->
+<line class="ldl-bar-stub" x1="-12" y1="30" x2="-6" y2="30"
+      stroke="#34495e" stroke-width="2.5"/>
+----
+
+=== Port Style Rendering
+
+When `OPTION PORT_STYLE = CIRCLE` (default), ports render as circles with `r=3`:
+
+[source,xml]
+----
+<circle class="ldl-port ldl-input ldl-port-circle" cx="0" cy="30" r="3"
+        fill="#2c3e50"/>
+----
+
+When `OPTION PORT_STYLE = SQUARE`, ports render as 5×5 squares:
+
+[source,xml]
+----
+<rect class="ldl-port ldl-input ldl-port-square" x="-2.5" y="27.5" width="5" height="5"
+      fill="#2c3e50"/>
+----
+
+Individual ports can override the document default via `.Style = SQUARE` or `.Style = CIRCLE`.

package/spec/sections/symbol-definitions.adoc

@@ -0,0 +1,143 @@
+[[symbol-definitions]]
+== Symbol Definitions
+
+=== Overview
+
+A symbol definition describes a reusable SVG component. It specifies the SVG asset, its ports, its default attributes, and any logic it encapsulates.
+
+=== Symbol Definition Syntax
+
+[literal]
+....
+SYMBOL SYMBOL_NAME
+  SVG = "path/to/symbol.svg"
+  PORT INPUT name1
+  PORT INPUT name2
+  PORT OUTPUT name3
+  ATTRIBUTE name1 = default_value1
+  ATTRIBUTE name2 = default_value2
+  LOGIC = boolean_expression
+END SYMBOL
+....
+
+=== Fields
+
+[cols="1m,4m,3m"]
+|===
+| Field | Description | Required
+| `SVG` | Path to the SVG file for this symbol | Yes
+| `PORT` | A port declaration with direction and name | Yes (at least one)
+| `ATTRIBUTE` | A default attribute with name and value | No
+| `LOGIC` | An embedded boolean expression defining the symbol's internal logic | No
+|===
+
+=== Port Declaration in Symbol
+
+[literal]
+....
+PORT DIRECTION NAME [: POSITION]
+....
+
+Where:
+
+* `DIRECTION` is `INPUT`, `OUTPUT`, or `BIDI`.
+* `NAME` is the port identifier.
+* `POSITION` is an optional side descriptor: `LEFT`, `RIGHT`, `TOP`, `BOTTOM`. Default is `LEFT` for inputs, `RIGHT` for outputs.
+
+=== Built-in Symbols
+
+The following symbols do not require explicit definition; they are always available.
+
+==== AND Gate
+
+[literal]
+....
+SYMBOL AND
+  SVG = "builtin:and"
+  PORT INPUT in
+  PORT OUTPUT out
+  LOGIC = out = in_0 AND in_1 AND ... AND in_n
+END SYMBOL
+....
+
+The AND symbol supports variable fan-in. The SVG is scaled accordingly.
+
+==== OR Gate
+
+[literal]
+....
+SYMBOL OR
+  SVG = "builtin:or"
+  PORT INPUT in
+  PORT OUTPUT out
+  LOGIC = out = in_0 OR in_1 OR ... OR in_n
+END SYMBOL
+....
+
+==== NOT Gate
+
+[literal]
+....
+SYMBOL NOT
+  SVG = "builtin:not"
+  PORT INPUT in
+  PORT OUTPUT out
+  LOGIC = out = NOT in
+END SYMBOL
+....
+
+==== NAND, NOR, XOR, XNOR Gates
+
+Each has the same port convention as AND/OR, with the corresponding logic.
+
+=== Inversion Bubbles
+
+When `OPTION INVERSION = BUBBLES` is set, `NOT` operations are rendered as inversion bubbles instead of separate NOT gate symbols. Bubbles may appear on **input ports** or **output ports** depending on where the inversion occurs in the expression.
+
+==== Input-Side Bubbles
+
+Any input port that receives the output of a `NOT` operation is marked with an inversion circle (bubble). The bubble is drawn at the input port position with a radius of `BUBBLE_R` (4px). The NOT gate symbol is not rendered; instead, the wire from the NOT's source connects directly to the bubbled input.
+
+For AND and OR gates with bubbled inputs, the gate body remains unchanged. The bubble is rendered as an open circle (stroke only, no fill) overlapping the input port position on the left side of the gate.
+
+==== Output-Side Bubbles
+
+When a `NOT` operation wraps a gate's output (e.g., `O1 = NOT (I1 AND I2)`), the bubble appears on the gate's output port. The bubble is drawn at the output port position with radius `BUBBLE_R` (4px), offset to the right of the gate body edge. The wire from the bubbled output connects directly to the downstream port.
+
+Similarly, when a `NOT` operation feeds directly into an output (e.g., `O1 = NOT I1`), the bubble appears on the output node's input port.
+
+The bubble on an output port is rendered as an open circle (stroke only, no fill) to the right of the gate body.
+
+==== Double-Inversion Cancellation
+
+Consecutive `NOT` operations are simplified before rendering:
+
+* An even number of `NOT` operations cancels out entirely (no bubble rendered).
+* An odd number of `NOT` operations reduces to a single inversion (one bubble rendered).
+
+=== Input Bars
+
+When `OPTION GATE_INPUT_STYLE = BARS` is set, gates with more than two inputs render as follows:
+
+. The gate body stays at the 2-input base height (44px for AND/OR).
+. The first two inputs render as normal input ports on the left side of the gate.
+. Additional inputs connect via a *vertical input bar* drawn along the left edge of the gate body.
+. The vertical bar extends from the top of the gate body to the bottom.
+. Additional input wires tap into the bar at evenly-spaced Y positions along the bar.
+. The bar is drawn as a vertical line segment (stroke-width 2.5) with short horizontal stubs connecting it to the gate body edge.
+
+The vertical bar is a visual convenience: it allows multi-input logic without expanding the gate symbol. The logical wiring is unchanged -- each input still connects to its source signal.
+
+=== Custom Symbol Example
+
+[literal]
+....
+SYMBOL SVT
+  SVG = "symbols/svt.svg"
+  PORT INPUT in
+  PORT OUTPUT out
+  ATTRIBUTE PICKUP = "0 s"
+  ATTRIBUTE DROPOUT = "0 s"
+  LOGIC = out = TIMER(in, PICKUP, DROPOUT)
+END SYMBOL
+....

package/spec/sections/templates.adoc

@@ -0,0 +1,31 @@
+== Templates
+
+A *template* is a pre-packaged symbol definition bundled with an SVG asset. Templates allow common patterns to be reused across projects.
+
+=== Template Declaration
+
+[literal]
+....
+IMPORT TEMPLATE "path/to/template.ldlt" AS name
+....
+
+This loads a template file which contains one or more symbol definitions.
+
+=== Template File Format
+
+A template file (`.ldlt`) contains symbol definitions:
+
+[literal]
+....
+SYMBOL TIMER
+  SVG = "timer.svg"
+  PORT INPUT in
+  PORT OUTPUT out
+  ATTRIBUTE PICKUP = "0 s"
+  ATTRIBUTE DROPOUT = "0 s"
+END SYMBOL
+....
+
+=== Template Resolution
+
+The renderer resolves SVG paths relative to the template's directory. Built-in symbols (`builtin:*`) are resolved by the renderer itself.

package/spec/spec.adoc

@@ -0,0 +1,49 @@
+= Logic Diagram Language (LDL) Specification
+:toc: macro
+:toclevels: 4
+:sectnums:
+:sectlinks
+:version: 0.3.0-draft
+:revdate: 2026-06-14
+
+toc::[]
+
+include::sections/introduction.adoc[]
+
+include::sections/lexical-conventions.adoc[]
+
+include::sections/options.adoc[]
+
+include::sections/expressions.adoc[]
+
+include::sections/function-blocks.adoc[]
+
+include::sections/objects.adoc[]
+
+include::sections/ports.adoc[]
+
+include::sections/attributes.adoc[]
+
+include::sections/symbol-definitions.adoc[]
+
+include::sections/templates.adoc[]
+
+include::sections/svg-symbol-specification.adoc[]
+
+include::sections/styling.adoc[]
+
+include::sections/layout-rules.adoc[]
+
+include::sections/hyperlinks.adoc[]
+
+include::sections/connections.adoc[]
+
+include::sections/examples.adoc[]
+
+include::sections/grammar.adoc[]
+
+include::sections/file-extension.adoc[]
+
+include::sections/rendering-contract.adoc[]
+
+include::sections/revision-history.adoc[]