@graphlearning/graphl-flow 0.0.0-stage → 0.2.0

package/README.md

@@ -1,3 +1,165 @@
-# Temporary Holding Version
+# @graphlearning/graphl-flow
 
-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.
+Declarative architecture diagrams for React. Describe **groups**, **items** and **edges**; the
+browser lays them out and the engine draws the arrows. Scenes never contain x/y.
+
+> 0.1.0 — seven node types (`group`, `item`, `table`, `code`, `plot`, `tree`, `note`), edges,
+> two themes, fit-to-frame for 4K recording. Content repos pin a version and upgrade deliberately.
+
+## Install
+
+```bash
+npm i @graphlearning/graphl-flow react react-dom lucide-react
+```
+
+```tsx
+import '@graphlearning/graphl-flow/styles.css' // once, at the app root
+import { Scene, type SceneModel } from '@graphlearning/graphl-flow'
+
+const scene: SceneModel = {
+  title: 'Batch & Real-Time',
+  dir: 'row',
+  nodes: [
+    { type: 'group', id: 'src', title: 'Data Sources', tone: 'source', children: [
+      { type: 'item', id: 'crm', title: 'CRM' },
+    ] },
+    { type: 'group', id: 'ing', title: 'Ingestion', badge: 1, tone: 'ingest', children: [
+      { type: 'item', id: 'adf', title: 'Azure Data Factory', sub: 'Scheduled pipelines' },
+    ] },
+  ],
+  edges: [{ from: 'src', to: 'ing' }],
+}
+
+<div style={{ width: 3840, height: 2160 }}>  {/* the Scene fills its parent — give it a size */}
+  <Scene scene={scene} theme="dark" />
+</div>
+```
+
+**Edges** connect any two nodes by id — items or groups, at any depth — as right-angle arrows.
+An edge leaves across the larger gap between the two columns (or rows) it connects, so it stays in
+the gaps rather than cutting through a neighbour; ends that face each other connect straight. A face with several edges gives each its
+own port, and their labels move off the line (above/below) so they don't collide. The gap an edge
+runs through widens automatically, to fit its label when it has one. An edge between a node and its
+own ancestor is not drawn. `bidirectional: true` puts a head at both ends.
+
+**Pulse.** A dot travels every edge once per **2.4 s**, linear — both ways on a bidirectional edge.
+That period is the recorder's loop (`PULSE_S` in `@graphlearning/shell`'s recorders), so a looped
+video has no jump at the join. `pulse: false` on a scene turns it off. `npm run capture` freezes the
+animation at t = 0, so stills are reproducible.
+
+**`spread: true`** on a group spaces its children evenly over its full height when the group is
+stretched taller than them (a short column beside a tall one).
+
+**Tables and memory.** A `table` is a DB schema, a stack frame, a heap object, an array or a hash
+map's buckets. Every row is addressable as `<table id>.<first cell>` (or `.<id>` when you set one), so
+a pointer is just an edge: `{ from: 'main.nums', to: 'list' }`. There is no memory node type —
+stack and heap are groups of tables:
+
+```ts
+{ type: 'group', id: 'stack', title: 'Stack', children: [
+  { type: 'table', id: 'main', title: '<module>', rows: [['nums', '●'], ['total', 3]] },
+] },
+{ type: 'table', id: 'list', title: 'list', columns: ['index', 'ref'], rows: [['0', '●'], ['1', '●']] },
+// edges: [{ from: 'main.nums', to: 'list' }]
+```
+
+A row connects through its left or right end only. Lay a pointer's target BESIDE its row (the next
+column), not below it — an edge is routed in the gap between two siblings, never around a third.
+`tag` draws a short pill before a row (`PK`, `FK`, `sp`); `tone` on a row tints it.
+
+**Code.** `code` takes the source as a (template-literal) string; its common indent is dropped.
+`lang` is `python | sql | scala | java | js | ts | shell | text` — one small highlighter with seven
+token colours per theme. `show` keeps only those line ranges and folds each skipped run into
+`··· N lines`; `show` and `highlight` use the FILE's line numbers, and so do edges: `src.L17`.
+`terminal: true` draws a terminal — `$ ` lines are commands, `! ` lines errors, the rest output.
+
+**IDE frames.** Three columns: `tree` | (editor `code` over terminal `code`, in a `bare` group) |
+a SIDE PANE — a `bare` group with a fixed width `w`. The IDE alone is narrower than 16:9; the side
+pane fills the frame and holds whatever the moment needs (a `note`, a `compact` plot, a small memory
+diagram) or nothing. See `dev/fixtures/studies/ide-frame.ts`.
+
+`minW`/`minH` are FLOORS and `maxW`/`maxH` CAPS, in the scene's own pixels; `w`/`h` set both. Give
+every frame of a video the same floors and a fixed side pane, and they get the same zoom: no pane
+moves between cuts, whatever the side pane holds. Prose wraps to the pane; tables and code do not,
+so keep them narrow. A plot never scales — use `compact: true` (a 420×280 area) in a side pane.
+Don't draw an edge between the IDE's columns: an arrow widens the gap it crosses and moves every
+pane. Point at code with `highlight` and the narration; edges INSIDE the side pane are fine.
+
+**Charts.** A `plot`'s x/y values are DATA in the axes' own units — sample curves in the scene
+file. A series is `line | scatter | area | bar | segment`. Every plot's drawing area is the same
+fixed size, so charts line up across a deck. Series take the next colour of a fixed ramp
+(blue, orange, violet, green) unless given a `tone`. A `segment` is a dashed construction or threshold
+line — muted grey unless toned, solid with `dashed: false`, a vector with `arrow: true`. Bars label
+themselves in a legend; other series label their last point.
+
+An edge to an id the scene doesn't have logs a console error naming it.
+
+**Legibility on video.** The fit scales the whole scene to the frame, so what decides how big text
+looks is how WIDE the scene is for the text it holds — not the font size. Item text wraps at a
+reading measure (15em) instead of widening its column; icons are sized in em, so they keep their
+ratio to the text; a small scene stops growing at 4×. Keep scenes legible: the engine's own check
+fails any fixture whose smallest body text renders under 24px in the 4K frame (12px at 1080p). If a
+diagram hits that, split the slide or trim bullets — a denser scene can only get smaller.
+
+**Focus.** `<Scene scene={…} focus="driver" />` singles out one node — any id, a table row or a code
+line included — with a ring and a glow in its own tone. It is drawn with box-shadow, so it moves
+nothing: every section of a course can focus a different node on the same scene without a jump.
+
+**Fit.** `Scene` fills its parent and scales the scene to fit, centred, with a 4% margin. The scale
+depends only on the parent's size and the scene's natural size, so the same scene in the same frame
+always lands on the same pixels. The view is locked (no zoom/pan); page scroll passes through and text
+stays selectable. The root carries `data-fit="ready"` once fonts have loaded, edges are routed and the fit is applied —
+wait on it before recording.
+
+**Recording at 4K.** Give the Scene a 3840×2160 box and record at device scale 1 — the frame
+`@graphlearning/shell`'s recorders use. In this repo: `npm run capture -- <fixtureId> --theme dark`
+writes `captures/<id>-<theme>.png`.
+
+## Model
+
+| Type    | Fields |
+|---------|--------|
+| `item`  | `id`, `title`, `sub?`, `icon?`, `bullets?`, `stack?`, `chip?`, `tone?`, `span?` |
+| `group` | `id`, `children`, `title?`, `sub?`, `icon?`, `badge?`, `dir?: 'row' \| 'col' \| 'grid'`, `cols?`, `bare?`, `spread?`, `tone?`, `span?` |
+| `table` | `id`, `rows`, `columns?`, `title?`, `tone?`, `span?` — a row is `[cells…]` or `{ cells, id?, tag?, tone? }` |
+| `code`  | `id`, `code`, `lang?`, `filename?`, `show?: [from, to][]`, `highlight?: number[]`, `terminal?`, `tone?`, `span?` |
+| `plot`  | `id`, `x`, `y` (axes: `min`, `max`, `step?`, `label?`, or `labels` for categories), `series`, `title?`, `axes?`, `grid?` |
+| `tree`  | `id`, `entries` (`name`, `children?`, `folder?`, `state?: active \| new \| muted`, `note?`, `icon?`), `title?` |
+| `note`  | `id`, `text`, `tone?` — a dashed callout of wrapping prose |
+| any node | `minW?`/`minH?` (floors), `maxW?`/`maxH?` (caps), `w?`/`h?` (exact), `fill?`, `span?`, `tone?`; groups also `bare?` |
+| `Edge`  | `from`, `to` (a node id; a table row `table.row`; a code line `code.L12`; a tree entry `tree.src/a.py`), `label?`, `dashed?`, `bidirectional?` |
+| `Scene` | `nodes`, `edges?`, `title?`, `sub?`, `dir?`, `pulse?` |
+
+**Layout.** A group lays its children out as `dir: 'col'` (default), `'row'` (one column per child)
+or `'grid'` (`cols`, default 2). `span: 'all'` gives a child a full row — a rail under columns.
+Siblings in a row stretch to equal height.
+
+**Tone** sets what a box means and is inherited by everything inside it:
+
+| tone | hue | | tone | hue |
+|---|---|---|---|---|
+| `neutral` | grey | | `serve` | violet |
+| `source` | slate | | `consume` | red |
+| `ingest` | blue | | `infra` | orange |
+| `store` | green | | | |
+
+The theme (`dark` | `light`) picks the shade; repos cannot recolour.
+
+**Icons** share one key space across four sets; an unknown key draws no icon. Keys match
+`@graphlearning/flow`'s where both have the icon, so scenes port without renaming.
+
+| set | drawn in | keys |
+|---|---|---|
+| generic (lucide) | the tone accent | `activity admin bell box branch building card chart check clock cloud code cpu database disk factory file filter fingerprint folder globe key layers lock network package pie screen search server settings shield stream table terminal user users workflow zap` |
+| Azure | its own colours | `adls aks analysisservices azuresql cosmos databricks datafactory defender devops eventhubs functions keyvault loganalytics monitor powerbi purview servicebus storage streamanalytics synapse vm` |
+| AWS | its own tile | `apigateway athena aurora cloudformation cloudwatch dms dynamodb ec2 eks elasticache emr eventbridge firehose glue iam kinesis kms lakeformation lambda msk mwaa rds redshift s3 sagemaker secretsmanager sns sqs stepfunctions vpc` |
+| brand | its own colour (ink if it would vanish) | `airflow docker duckdb flink git github githubactions grafana jupyter kafka kubernetes mongodb pandas postgresql prometheus python snowflakedb spark terraform` |
+
+**`chip: true`** draws an item as a small framed pill — a thing counted, not described (`Task 1`,
+`Local disk`); chips fill their grid cell, so a row of them lines up.
+
+A nested group is a plain card, unless it names its OWN `tone` — then it is a coloured column again
+(the Spark study's four columns, and its green worker nodes inside the orange Worker column).
+
+**`stack: true`** puts an item's icon on top with the text centred under it — a card in a column of
+peers (the Business Consumers column).

package/dist/Code.d.ts

@@ -0,0 +1,20 @@
+import type { CSSProperties } from 'react';
+import type { Code } from './types';
+type Row = {
+    n: number;
+    text: string;
+} | {
+    fold: number;
+};
+/**
+ * The lines a `code` node draws: every line, or only the `show` ranges with each skipped run
+ * folded into one `··· N lines` row. Line numbers are the FILE's. Shared with the edge planner via
+ * `codeLineIds`, so a line edges can address is a line that is drawn.
+ */
+export declare function codeRows(node: Code): Row[];
+export declare const codeLineIds: (node: Code) => string[];
+export declare function CodeView({ node, style }: {
+    node: Code;
+    style?: CSSProperties;
+}): import("react").JSX.Element;
+export {};

package/dist/Edges.d.ts

@@ -0,0 +1,14 @@
+import type { Routed } from './routing';
+import type { Size } from './fit';
+/**
+ * The pulse period, in seconds. A RECORDER CONTRACT: ui-shell's record-course.mjs / record-reels.mjs
+ * loop every video on PULSE_S = 2.4. Change it here alone and every loop join in every recorded video
+ * shows a jump. Same value, same linear motion as @graphlearning/flow's FlowEdge.
+ */
+export declare const PULSE_S = 2.4;
+/** Draws routed edges over the content, in the content's own (unscaled) coordinates. */
+export declare function Edges({ routed, size, pulse }: {
+    routed: Routed[];
+    size: Size;
+    pulse: boolean;
+}): import("react").JSX.Element;

package/dist/Plot.d.ts

@@ -0,0 +1,12 @@
+import type { Theme } from './theme';
+import type { Plot } from './types';
+export declare const PLOT_W = 720;
+export declare const PLOT_H = 400;
+/** The second fixed size: a plot for a side pane, readable at full text size in ~560px. */
+export declare const COMPACT_W = 420;
+export declare const COMPACT_H = 280;
+export declare function PlotView({ node, theme, style }: {
+    node: Plot;
+    theme: Theme;
+    style?: React.CSSProperties;
+}): import("react").JSX.Element;

package/dist/Scene.d.ts

@@ -0,0 +1,15 @@
+import type { Scene as SceneModel, ThemeKey } from './types';
+/**
+ * `focus` names one node (any id, a table row or a code line included) to single out: it gets a
+ * ring and a glow, drawn with box-shadow so the layout — and therefore the fit — never moves. That is
+ * what lets every section of a course focus a different node on the same scene without a jump.
+ *
+ * Fills its parent (give the parent a size) and scales the scene's natural box to fit, centred.
+ * The viewport is locked: no wheel or drag handlers, so page scroll passes through and text stays
+ * selectable. `data-fit="ready"` marks the first fit after fonts load with edges routed — what a recorder waits on.
+ */
+export declare function Scene({ scene, theme: key, focus }: {
+    scene: SceneModel;
+    theme?: ThemeKey;
+    focus?: string;
+}): import("react").JSX.Element;

package/dist/Table.d.ts

@@ -0,0 +1,16 @@
+import type { CSSProperties } from 'react';
+import type { Theme } from './theme';
+import type { Table, TableRow } from './types';
+/**
+ * Normalised rows with their ADDRESS: explicit `id`, else the first cell when it is a plain word
+ * and unique in the table. Shared by the renderer (data-id) and the edge planner (parent links),
+ * so the two cannot disagree about which rows exist.
+ */
+export declare function tableRows(table: Table): (TableRow & {
+    address?: string;
+})[];
+export declare function TableView({ node, theme, style }: {
+    node: Table;
+    theme: Theme;
+    style?: CSSProperties;
+}): import("react").JSX.Element;

package/dist/Tree.d.ts

@@ -0,0 +1,9 @@
+import type { CSSProperties } from 'react';
+import type { Theme } from './theme';
+import type { Tree } from './types';
+export declare const treeEntryIds: (node: Tree) => string[];
+export declare function TreeView({ node, theme, style }: {
+    node: Tree;
+    theme: Theme;
+    style?: CSSProperties;
+}): import("react").JSX.Element;

package/dist/fit.d.ts

@@ -0,0 +1,20 @@
+export interface Size {
+    w: number;
+    h: number;
+}
+export interface Fit {
+    scale: number;
+    x: number;
+    y: number;
+}
+/** Margin on each side, as a fraction of the pane's own axis. */
+export declare const FIT_PADDING = 0.04;
+export declare const MIN_SCALE = 0.05;
+/** A small scene stops growing here, so it still reads as a diagram, not a poster. */
+export declare const MAX_SCALE = 4;
+/**
+ * The fit is a PURE function of the pane and the content's natural size — no async, no history.
+ * That is what makes recordings reproducible: two frames whose scenes have the same natural box get
+ * the same scale and put every panel at the same pixels.
+ */
+export declare function fitTransform(pane: Size, content: Size): Fit;

package/dist/highlight.d.ts

@@ -0,0 +1,9 @@
+export type TokClass = 'var' | 'method' | 'keyword' | 'string' | 'number' | 'punct' | 'ws' | 'comment';
+export interface Tok {
+    cls: TokClass;
+    text: string;
+}
+export type Lang = 'python' | 'sql' | 'scala' | 'java' | 'js' | 'ts' | 'shell' | 'text';
+export declare function tokenize(src: string, lang: Lang): Tok[];
+/** Drop a leading/trailing blank line and the common indent, so scenes can use indented template literals. */
+export declare function dedent(src: string): string[];

package/dist/icons.d.ts

@@ -0,0 +1,25 @@
+import type { ComponentType, ReactElement } from 'react';
+import { type LucideIcon } from 'lucide-react';
+/** Generic glyphs, drawn in the node's tone accent. */
+export declare const LUCIDE: Record<string, LucideIcon>;
+/** Azure service tiles, in their own colours. The package ships no viewBox; 0 0 18 18 fits all. */
+export declare const AZURE: Record<string, ComponentType<{
+    size?: string;
+    viewBox?: string;
+}>>;
+/** AWS architecture icons, in their own colours on their own rounded tile. */
+export declare const AWS: Record<string, ComponentType<{
+    size?: number | string;
+}>>;
+/** Open-source / product marks (simple-icons), in the brand's colour unless it would vanish. */
+export declare const BRAND: Record<string, {
+    title: string;
+    hex: string;
+    path: string;
+}>;
+/** `size` is a CSS length — in em, so an icon scales WITH its text and the ratio stays designed. */
+type Draw = (size: string, surface: string, ink: string) => ReactElement;
+/** A brand mark under this contrast against the surface draws in ink (Kafka's black on dark). */
+export declare const BRAND_MIN_CONTRAST = 2.2;
+export declare const ICONS: Record<string, Draw>;
+export {};

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export { Scene } from './Scene';
+export type { Scene as SceneModel, SceneNode, Group, Item, Table, TableRow, Code, Plot, PlotAxis, PlotSeries, Tree, TreeEntry, Note, Edge, Tone, ThemeKey } from './types';