@graphlearning/graphl-flow 0.0.0-stage → 0.2.0

package/dist/styles.css

@@ -0,0 +1,189 @@
+@import '@fontsource/ibm-plex-sans/400.css';
+@import '@fontsource/ibm-plex-sans/600.css';
+@import '@fontsource/ibm-plex-mono/400.css';
+@import '@fontsource/ibm-plex-mono/600.css';
+
+/* Colours come from theme.ts as --gf-* variables on .gf-scene; tones override
+   --gf-accent / --gf-tint on a node and every descendant inherits them. */
+
+.gf-scene {
+  position: relative; width: 100%; height: 100%; overflow: hidden;
+  font: 16px/1.35 'IBM Plex Sans', system-ui, sans-serif;
+  background: var(--gf-bg); color: var(--gf-ink); user-select: text;
+}
+/* The natural box: laid out at max-content, then scaled by the fit (transform-origin 0 0). */
+.gf-content { position: absolute; left: 0; top: 0; width: max-content; transform-origin: 0 0; }
+.gf-scene *, .gf-scene *::before, .gf-scene *::after { box-sizing: border-box; }
+.gf-scene-title { font-size: 32px; font-weight: 600; }
+.gf-scene-sub { font-size: 20px; color: var(--gf-muted); margin-bottom: 16px; }
+
+.gf-body { display: grid; align-items: stretch; }
+
+/* A top-level group is a tinted column; a nested one is a card on it. */
+.gf-group { border: 1px solid color-mix(in srgb, var(--gf-accent) 35%, transparent); border-radius: 8px; padding: 10px; background: var(--gf-tint); }
+.gf-group .gf-group { background: var(--gf-surface); border-color: var(--gf-line); }
+/* spread: the body takes the group's full (stretched) height and spaces its rows evenly over it. */
+.gf-group[data-spread] { display: flex; flex-direction: column; }
+.gf-group[data-spread] > .gf-body { flex: 1; align-content: space-evenly; }
+/* ...unless it names its OWN tone: then it is a coloured column again (Spark's four columns). */
+.gf-group .gf-group[data-toned] { background: var(--gf-tint); border-color: color-mix(in srgb, var(--gf-accent) 35%, transparent); }
+/* A bare group only arranges: no frame, fill or padding, at any depth. */
+.gf-group[data-bare], .gf-group .gf-group[data-bare] { border: 0; padding: 0; background: none; border-radius: 0; }
+.gf-group-head { margin-bottom: 10px; }
+.gf-group-title { display: flex; align-items: center; gap: 8px; font-size: 18px; font-weight: 600; }
+.gf-group-sub { margin-top: 2px; font-size: 14px; color: var(--gf-muted); }
+.gf-badge {
+  display: inline-grid; place-items: center; flex: none; width: 26px; height: 26px; border-radius: 50%;
+  background: var(--gf-accent); color: var(--gf-bg); font-size: 14px;
+}
+
+/* An item HUGS its content (no stretch): its box is what edges anchor to, and an unframed leaf
+   whose box ran to the cell edge would end every arrow short of nothing. Groups do stretch. */
+.gf-item { display: flex; align-items: flex-start; gap: 10px; padding: 5px 2px; justify-self: start; align-self: start; }
+.gf-icon { flex: none; color: var(--gf-accent); }
+.gf-vendor { display: inline-flex; line-height: 0; }
+.gf-aws { border-radius: 6px; overflow: hidden; }
+/* A chip: a thing counted, not described — a small framed pill. */
+.gf-item[data-chip] {
+  justify-self: stretch; justify-content: center; align-items: center; gap: 6px; padding: 4px 10px; border-radius: 6px;
+  border: 1px solid color-mix(in srgb, var(--gf-accent) 45%, var(--gf-line)); background: var(--gf-surface);
+}
+.gf-item[data-chip] .gf-item-title { font-weight: 500; font-size: 15px; }
+.gf-item[data-stack] { flex-direction: column; align-items: center; text-align: center; justify-self: center; }
+.gf-item-title { font-weight: 600; }
+/* The reading measure: an item's text WRAPS here instead of widening its column. The fit is set by
+   the scene's width, so an unwrapped subtitle shrinks every word in the frame (Barclays: 20px body
+   text at 4K before this). */
+.gf-item > div { max-width: 15em; }
+.gf-item-sub { font-size: 15px; color: var(--gf-muted); }
+.gf-bullets { margin: 4px 0 0; padding-left: 18px; font-size: 15px; }
+
+/* Edges live inside .gf-content, so they scale with it; pointer-events off keeps text selectable. */
+.gf-edges { position: absolute; left: 0; top: 0; overflow: visible; pointer-events: none; }
+.gf-edge { fill: none; stroke: var(--gf-edge); stroke-width: 2; stroke-linejoin: round; }
+.gf-arrowhead { fill: var(--gf-edge); }
+.gf-pulse { fill: var(--gf-pulse); opacity: 0.9; }
+.gf-edge-label {
+  position: absolute; white-space: nowrap; pointer-events: none;
+  padding: 1px 6px; border: 1px solid var(--gf-line); border-radius: 4px;
+  background: var(--gf-bg); color: var(--gf-muted); font-size: 14px;
+}
+
+/* A table hugs its content like an item: its box, and each row's, is what an edge anchors to. */
+.gf-table {
+  justify-self: start; align-self: start; overflow: hidden;
+  border: 1px solid color-mix(in srgb, var(--gf-accent) 45%, var(--gf-line)); border-radius: 6px;
+  background: var(--gf-surface);
+}
+.gf-table-title {
+  padding: 5px 10px; font-weight: 600; font-size: 15px;
+  background: color-mix(in srgb, var(--gf-accent) 14%, var(--gf-surface));
+  border-bottom: 1px solid color-mix(in srgb, var(--gf-accent) 45%, var(--gf-line));
+}
+/* The inner table fills its frame: a title wider than the cells must not leave the rows — whose
+   faces edges anchor to — short of the border. */
+.gf-table table { width: 100%; border-collapse: collapse; font: 15px/1.4 'IBM Plex Mono', ui-monospace, monospace; }
+.gf-table th {
+  padding: 4px 10px; text-align: left; font: 600 12px/1.4 'IBM Plex Sans', system-ui, sans-serif;
+  letter-spacing: 0.04em; text-transform: uppercase; color: var(--gf-muted);
+  border-bottom: 1px solid var(--gf-line);
+}
+.gf-table td { padding: 4px 10px; white-space: nowrap; }
+.gf-table tbody tr + tr td { border-top: 1px solid var(--gf-line); }
+.gf-table tr[data-tone] td { background: var(--gf-tint); }
+.gf-table td.gf-tag-cell { padding-right: 0; width: 1px; }
+.gf-tag {
+  display: inline-block; padding: 0 5px; border-radius: 4px; font: 600 11px/1.6 'IBM Plex Sans', system-ui, sans-serif;
+  color: var(--gf-accent); border: 1px solid color-mix(in srgb, var(--gf-accent) 50%, transparent);
+}
+
+/* Code hugs its content like an item. Lines are BLOCKS spanning the full width: a line's box is
+   what an edge anchors to, and its faces must reach the frame (the table lesson). */
+.gf-code {
+  justify-self: start; align-self: start; overflow: hidden; border-radius: 8px;
+  border: 1px solid color-mix(in srgb, var(--gf-accent) 35%, var(--gf-line));
+  background: var(--gf-code-bg); font: 15px/1.6 'IBM Plex Mono', ui-monospace, monospace;
+}
+.gf-code-bar {
+  display: flex; align-items: center; gap: 10px; padding: 6px 12px; background: var(--gf-code-bar);
+  border-bottom: 1px solid var(--gf-line); font: 13px/1.5 'IBM Plex Mono', ui-monospace, monospace; color: var(--gf-muted);
+}
+.gf-code[data-terminal] .gf-code-name { font: 600 12px/1.5 'IBM Plex Sans', system-ui, sans-serif; letter-spacing: 0.08em; text-transform: uppercase; }
+.gf-dots { display: inline-flex; gap: 6px; }
+.gf-dots i { width: 10px; height: 10px; border-radius: 50%; background: #ff5f56; }
+.gf-dots i + i { background: #ffbd2e; }
+.gf-dots i + i + i { background: #27c93f; }
+.gf-code-body { padding-block: 8px; }
+.gf-line { display: flex; white-space: pre; padding-right: 16px; color: var(--gf-code-var); }
+.gf-code[data-terminal] .gf-line { padding-left: 14px; }
+.gf-ln { flex: none; box-sizing: content-box; min-width: 3ch; padding: 0 12px 0 10px; text-align: right; color: var(--gf-code-gutter); user-select: none; }
+.gf-line[data-lit] { background: color-mix(in srgb, var(--gf-accent) 16%, transparent); box-shadow: inset 3px 0 0 var(--gf-accent); }
+.gf-line[data-lit] .gf-ln { color: var(--gf-accent); }
+.gf-fold { color: var(--gf-code-gutter); font-style: italic; background: color-mix(in srgb, var(--gf-code-gutter) 10%, transparent); user-select: none; }
+.gf-prompt { color: var(--gf-ok); user-select: none; }
+.gf-line[data-kind='out'] { color: var(--gf-muted); }
+.gf-line[data-kind='err'] { color: var(--gf-err); }
+.tok-var { color: var(--gf-code-var); }
+.tok-method { color: var(--gf-code-method); }
+.tok-keyword { color: var(--gf-code-keyword); }
+.tok-string { color: var(--gf-code-string); }
+.tok-number { color: var(--gf-code-number); }
+.tok-punct { color: var(--gf-code-punct); }
+.tok-comment { color: var(--gf-code-comment); font-style: italic; }
+
+/* A plot hugs its fixed-size SVG; it shares the table's title strip. */
+.gf-plot {
+  justify-self: start; align-self: start; overflow: hidden; border-radius: 8px;
+  border: 1px solid color-mix(in srgb, var(--gf-accent) 35%, var(--gf-line)); background: var(--gf-surface);
+}
+.gf-plot svg { display: block; overflow: hidden; }
+.gf-plot text { font: 15px 'IBM Plex Mono', ui-monospace, monospace; }
+.gf-plot-grid line { stroke: var(--gf-line); stroke-width: 1; }
+.gf-plot-axis line { stroke: var(--gf-muted); stroke-width: 1.5; }
+.gf-plot-ticks text { fill: var(--gf-muted); }
+.gf-plot-ticks .gf-plot-label { fill: var(--gf-ink); }
+.gf-plot-labels text { font-weight: 600; }
+
+/* A file explorer: the IDE's left pane. */
+.gf-tree {
+  justify-self: start; align-self: start; overflow: hidden; border-radius: 8px;
+  border: 1px solid color-mix(in srgb, var(--gf-accent) 35%, var(--gf-line)); background: var(--gf-surface);
+}
+.gf-tree-title {
+  padding: 7px 12px; font: 600 12px/1.5 'IBM Plex Sans', system-ui, sans-serif; letter-spacing: 0.08em;
+  text-transform: uppercase; color: var(--gf-muted); border-bottom: 1px solid var(--gf-line); background: var(--gf-code-bar);
+}
+.gf-tree-body { padding-block: 6px; }
+.gf-tree-row {
+  display: flex; align-items: center; gap: 6px; padding-right: 14px; white-space: nowrap;
+  font: 15px/1.75 'IBM Plex Sans', system-ui, sans-serif; color: var(--gf-ink);
+}
+.gf-tree-row svg { flex: none; color: var(--gf-muted); }
+.gf-tree-chev { flex: none; width: 0.9em; }
+.gf-tree-row[data-state='active'] { background: color-mix(in srgb, var(--gf-accent) 18%, transparent); box-shadow: inset 2px 0 0 var(--gf-accent); }
+.gf-tree-row[data-state='active'] svg { color: var(--gf-accent); }
+.gf-tree-row[data-state='new'] .gf-tree-name { color: var(--gf-ok); }
+.gf-tree-row[data-state='muted'] { opacity: 0.5; }
+.gf-tree-note { margin-left: auto; padding-left: 14px; font: 13px 'IBM Plex Mono', ui-monospace, monospace; color: var(--gf-muted); }
+.gf-tree-row[data-state='new'] .gf-tree-note { color: var(--gf-ok); }
+.gf-tree-row[data-state='muted'] .gf-tree-note { margin-left: 0; font: italic 14px 'IBM Plex Sans', system-ui, sans-serif; }
+.gf-tree-icon { display: inline-flex; flex: none; line-height: 0; }
+
+/* A note fills its column and wraps; capped so a note in an unbounded row stays a paragraph. */
+.gf-note {
+  justify-self: stretch; align-self: start; max-width: 34em; padding: 12px 16px; border-radius: 8px;
+  border: 1.5px dashed var(--gf-accent); background: color-mix(in srgb, var(--gf-accent) 8%, transparent);
+  font: 17px/1.5 'IBM Plex Sans', system-ui, sans-serif; text-align: center; color: var(--gf-ink);
+}
+/* A plot never scales: in a narrow column use `compact`, the second fixed size. Too wide is overflow,
+   which check fails — scaling down silently shrank the text past reading in a 560px side pane. */
+
+/* Focus: a ring and a glow in the node's own accent, by box-shadow — NO layout effect, so moving the
+   focus between sections never moves the scene. An unframed item gains a frame while focused. */
+[data-focus] {
+  box-shadow: 0 0 0 2px var(--gf-accent), 0 0 24px 2px color-mix(in srgb, var(--gf-accent) 45%, transparent);
+  border-radius: 8px;
+}
+.gf-item[data-focus] { background: color-mix(in srgb, var(--gf-accent) 12%, var(--gf-surface)); }
+tr[data-focus] td, .gf-line[data-focus], .gf-tree-row[data-focus] { background: color-mix(in srgb, var(--gf-accent) 18%, transparent); }
+tr[data-focus], .gf-line[data-focus], .gf-tree-row[data-focus] { box-shadow: inset 3px 0 0 var(--gf-accent); border-radius: 0; }

package/dist/theme.d.ts

@@ -0,0 +1,30 @@
+import type { ThemeKey, Tone } from './types';
+export interface ToneColors {
+    accent: string;
+    tint: string;
+}
+/** The code surface and its seven token colours — one set per theme, shared by every language. */
+export interface CodeColors {
+    bg: string;
+    bar: string;
+    gutter: string;
+    var: string;
+    method: string;
+    keyword: string;
+    string: string;
+    number: string;
+    punct: string;
+    comment: string;
+}
+export interface Theme {
+    bg: string;
+    surface: string;
+    line: string;
+    ink: string;
+    muted: string;
+    edge: string;
+    pulse: string;
+    tones: Record<Tone, ToneColors>;
+    code: CodeColors;
+}
+export declare const THEMES: Record<ThemeKey, Theme>;

package/dist/types.d.ts

@@ -0,0 +1,184 @@
+/** The scene model — the whole authoring contract. Scenes never carry x/y or sizes. */
+export type ThemeKey = 'dark' | 'light';
+/** What a box MEANS. A theme picks the shade; the tone picks the hue family. */
+export type Tone = 'source' | 'ingest' | 'store' | 'serve' | 'consume' | 'infra' | 'neutral';
+interface Base {
+    id: string;
+    /** Inherited: unset takes the nearest ancestor's tone. */
+    tone?: Tone;
+    /** Take a whole row of the parent (a rail under a row of columns). */
+    span?: 'all';
+    /**
+     * FLOORS in the scene's own pixels, applied after the natural size: a box never shrinks below
+     * them and content still grows it. Their job is consistency — frames whose boxes match get the same
+     * zoom, so a pane sits at the same pixels in every frame of a video.
+     */
+    minW?: number;
+    minH?: number;
+    /**
+     * CAPS: a box never grows past them. Content that does not fit overflows, and `check` fails it —
+     * a cap holds a column FIXED so nothing placed in it can move the rest of the frame.
+     */
+    maxW?: number;
+    maxH?: number;
+    /** Exact size: shorthand for min = max. A fixed column — the IDE's side pane, empty or not. */
+    w?: number;
+    h?: number;
+    /** A leaf stretches to fill its grid cell instead of hugging its content (IDE panes). */
+    fill?: boolean;
+}
+/** A leaf: one card. Every field is optional except `title`. */
+export interface Item extends Base {
+    type: 'item';
+    title: string;
+    sub?: string;
+    /** An icon key — generic (`database`), Azure (`datafactory`), AWS (`s3`) or brand (`kafka`). */
+    icon?: string;
+    bullets?: string[];
+    /** Icon on top, text centred under it — a card in a column of peers. Default: icon left. */
+    stack?: boolean;
+    /** A small framed pill — a thing COUNTED, not described (`Task 1`, `Local disk`). */
+    chip?: boolean;
+}
+/** A container: lays its children out in a row, a column or a grid. */
+export interface Group extends Base {
+    type: 'group';
+    title?: string;
+    /** A step number drawn as a badge before the title. */
+    badge?: number;
+    /** A line under the title: what the group is for. */
+    sub?: string;
+    /** An icon key drawn before the title. */
+    icon?: string;
+    dir?: 'row' | 'col' | 'grid';
+    /** Column count for `dir: 'grid'`. */
+    cols?: number;
+    /** No frame, fill or padding — a group that only arranges its children. */
+    bare?: boolean;
+    /** Distribute the children over the group's full height when it is stretched taller than them. */
+    spread?: boolean;
+    children: SceneNode[];
+}
+/** One table row: its cells, plus an optional id, a short tag in a leading gutter, and a tone. */
+export interface TableRow {
+    /** Overrides the row's address. Default: its first cell, when that is a plain word. */
+    id?: string;
+    cells: (string | number)[];
+    /** A short marker drawn as a pill before the row: `PK`, `FK`, `sp`, `top`… */
+    tag?: string;
+    /** Tints the row — the changed value, the active frame. */
+    tone?: Tone;
+}
+/**
+ * A grid of cells — a DB table, a stack frame, a heap object, an array, a hash map's buckets.
+ * Each row is addressable by edges as `<table id>.<row id>`, which is how a pointer is drawn.
+ */
+export interface Table extends Base {
+    type: 'table';
+    title?: string;
+    /** Header cells. Omit for a headerless table (a stack frame, a heap object). */
+    columns?: string[];
+    rows: ((string | number)[] | TableRow)[];
+}
+/**
+ * Source code or a terminal session. Lines are addressable by edges as `<code id>.L<n>` (the FILE's
+ * line number), which is how an arrow points from a line into a diagram.
+ */
+export interface Code extends Base {
+    type: 'code';
+    /** The source. A template literal's common indent and outer blank lines are dropped. */
+    code: string;
+    lang?: 'python' | 'sql' | 'scala' | 'java' | 'js' | 'ts' | 'shell' | 'text';
+    /** The tab label; for a terminal, its title. */
+    filename?: string;
+    /** Only these 1-based, inclusive line ranges; each skipped run folds to `··· N lines`. */
+    show?: [number, number][];
+    /** Line numbers (the file's) to tint. */
+    highlight?: number[];
+    /** A terminal: `$ cmd` lines are commands, `! text` errors, the rest output. No line numbers. */
+    terminal?: boolean;
+}
+/** An axis in DATA units. `labels` makes it categorical: one slot per label (bar charts). */
+export interface PlotAxis {
+    min?: number;
+    max?: number;
+    /** Tick spacing; default a "nice" step giving ~8 ticks. */
+    step?: number;
+    label?: string;
+    labels?: string[];
+}
+export interface PlotSeries {
+    kind: 'line' | 'scatter' | 'area' | 'bar' | 'segment';
+    /** Data points (line, scatter, area, bar). Curves are sampled in the scene file. */
+    points?: [number, number][];
+    /** A segment's two ends. */
+    from?: [number, number];
+    to?: [number, number];
+    /** Drawn at the last point, a segment's midpoint, or an arrow's tip. */
+    label?: string;
+    /** Default: the next colour of the plot ramp. */
+    tone?: Tone;
+    /** A line drawn dashed. A segment is dashed UNLESS `dashed: false`. */
+    dashed?: boolean;
+    /** A segment with a head at `to` — a vector. */
+    arrow?: boolean;
+}
+/** A chart. Every plot's drawing area is the same fixed size, whatever its data. */
+export interface Plot extends Base {
+    type: 'plot';
+    title?: string;
+    x: PlotAxis;
+    y: PlotAxis;
+    series: PlotSeries[];
+    /** Default: through the origin when both numeric ranges span zero, else along the corner. */
+    axes?: 'origin' | 'corner';
+    /** Gridlines at the ticks. Default true. */
+    grid?: boolean;
+    /** The second fixed size (420×280 drawing area) — a chart in a side pane, at full text size. */
+    compact?: boolean;
+}
+export interface TreeEntry {
+    name: string;
+    children?: TreeEntry[];
+    /** Draw as a folder even with no children listed. */
+    folder?: boolean;
+    /** `active` — the open file; `new` — added in this step; `muted` — not relevant here. */
+    state?: 'active' | 'new' | 'muted';
+    /** A short note after the name (`M`, `U`); on a `muted` entry it reads as an italic aside. */
+    note?: string;
+    /** An icon key. Default: by extension (`.py` → the Python mark), else a plain file or folder. */
+    icon?: string;
+}
+/** A file explorer. Each entry is addressable by edges as `<tree id>.<path>` (`ide.src/jobs/orders.py`). */
+export interface Tree extends Base {
+    type: 'tree';
+    /** The panel heading. Default `Explorer`. */
+    title?: string;
+    entries: TreeEntry[];
+}
+/** A callout: wrapping prose in a dashed frame of its tone. Fills its column's width. */
+export interface Note extends Base {
+    type: 'note';
+    text: string;
+}
+export type SceneNode = Item | Group | Table | Code | Plot | Tree | Note;
+export interface Edge {
+    /** A node id, or a table row as `<table>.<row>`. */
+    from: string;
+    to: string;
+    label?: string;
+    dashed?: boolean;
+    /** A head at both ends (and a pulse each way) — a read/write, a request/response. */
+    bidirectional?: boolean;
+}
+export interface Scene {
+    title?: string;
+    sub?: string;
+    /** Direction of the top-level nodes. Default `'col'`. */
+    dir?: 'row' | 'col';
+    nodes: SceneNode[];
+    edges?: Edge[];
+    /** A dot travels every edge once per 2.4 s (the recorder's loop). Default true. */
+    pulse?: boolean;
+}
+export {};

package/package.json

@@ -1,6 +1,58 @@
 {
   "name": "@graphlearning/graphl-flow",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.2.0",
+  "description": "Declarative diagram engine — authors describe groups, items and edges; the browser lays them out and the engine draws the edges.",
+  "license": "UNLICENSED",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/schemabotview/graphl-flow.git"
+  },
+  "type": "module",
+  "sideEffects": [
+    "**/*.css"
+  ],
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./styles.css": "./dist/styles.css"
+  },
+  "scripts": {
+    "dev": "vite",
+    "build": "vite build && tsc --emitDeclarationOnly && cp src/styles.css dist/styles.css",
+    "watch": "vite build --watch",
+    "prepublishOnly": "npm run build",
+    "capture": "node scripts/capture.mjs",
+    "check": "node scripts/check.mjs"
+  },
+  "peerDependencies": {
+    "lucide-react": "^1.28.0",
+    "react": "^19.2.0",
+    "react-dom": "^19.2.0"
+  },
+  "devDependencies": {
+    "@types/react": "^19.2.0",
+    "@types/react-dom": "^19.2.0",
+    "@vitejs/plugin-react": "^4.3.4",
+    "lucide-react": "^1.28.0",
+    "playwright": "1.63.0",
+    "react": "^19.2.0",
+    "react-dom": "^19.2.0",
+    "typescript": "~5.7.2",
+    "vite": "^6.0.5"
+  },
+  "dependencies": {
+    "@fontsource/ibm-plex-mono": "^5.3.0",
+    "@fontsource/ibm-plex-sans": "^5.3.0",
+    "@threeveloper/azure-react-icons": "^1.1.1",
+    "aws-react-icons": "^3.3.0",
+    "simple-icons": "^16.36.0"
+  }
+}