@dooc-dev/dooc 0.0.0-stage → 0.0.1

package/dist/core/schema-graph.d.ts

@@ -0,0 +1,254 @@
+/** Closed set of scalar types (anything else is a validation error). */
+export declare const SCHEMA_SCALAR_TYPES: readonly ["string", "number", "bool", "json", "timestamp"];
+export type SchemaScalarType = (typeof SCHEMA_SCALAR_TYPES)[number];
+/** A single field. kind = pk / fk / fkList (fk[]) / scalar. */
+export interface SchemaField {
+    name: string;
+    kind: "pk" | "fk" | "fkList" | "scalar";
+    /**
+     * Scalar only. `kind: "scalar"` has two origins: a plain scalar = one of the closed set
+     * `SCHEMA_SCALAR_TYPES`; from `enum("a"|"b")` = the display label itself, the written values
+     * joined with `|` (e.g. `"a"|"b"`).
+     */
+    type?: string;
+    /** fk / fkList only. A union (`fk(a|b)`) yields several. */
+    targets?: string[];
+}
+export interface SchemaTable {
+    name: string;
+    fields: SchemaField[];
+    /** Lines without a value (= descriptions). */
+    notes: string[];
+    /**
+     * Field names in the composite primary key (`pk(<field>, <field>, ...)`), in declaration
+     * order. A single pk stays as `kind: "pk"` on the field (it can't coexist with this array =
+     * validation error). Absent = no composite pk. The fields' own `kind` is unchanged (an fk
+     * stays an fk = edges are unaffected).
+     */
+    pk?: string[];
+    /**
+     * Field names of each unique constraint (`unique(<field>, ...)`), in declaration order. One
+     * element per constraint; a table may declare several uniques (= array of arrays;
+     * `unique(a)` alongside `unique(b, c)` is valid). A unique over the same column set as the pk
+     * is rejected as a validation error (the pk is already unique), so only column sets that
+     * differ from the pk end up here. The fields' own `kind` is unchanged (= no extra edges).
+     */
+    unique?: string[][];
+}
+/** A group delimited by `###`. A frame + heading is drawn on the graph only when it has a label. */
+export interface SchemaGroup {
+    label?: string;
+    /** Member table names (declaration order). groups partition all tables (none is ungrouped). */
+    tables: string[];
+}
+/** One fk reference = one edge (a union yields one per target). */
+export interface SchemaEdge {
+    from: string;
+    /** Field index within the from table (key for hover linkage). */
+    fieldIndex: number;
+    field: string;
+    to: string;
+    /** Whether it's fk[] (1:N). */
+    list: boolean;
+}
+export interface SchemaModel {
+    groups: SchemaGroup[];
+    tables: SchemaTable[];
+    edges: SchemaEdge[];
+}
+/** Error with a DSL line number (0-indexed, relative to the DSL). */
+export interface SchemaParseError {
+    line: number;
+    message: string;
+}
+export interface SchemaParseResult {
+    model: SchemaModel;
+    errors: SchemaParseError[];
+}
+/**
+ * table DSL → graph model + errors. Even with errors, a partial model is returned
+ * (so preview can show "validation errors + as much as can be drawn" at the same time).
+ */
+export declare const parseSchemaSource: (source: string) => SchemaParseResult;
+/**
+ * Short id derived deterministically from the model contents. Used as the namespace for SVG
+ * markers / classes (no id collisions when one page has several graphs; no randomness / time =
+ * reproducible builds).
+ */
+export declare const schemaGraphUid: (model: SchemaModel) => string;
+/**
+ * One row in a table box (field or note). All coordinates are absolute px (= the renderer holds
+ * no geometry). y = row center, baseline = text baseline, x = left edge of the name,
+ * typeX = right edge of the type label.
+ */
+export interface SchemaLayoutRow {
+    kind: SchemaField["kind"] | "note";
+    name: string;
+    /** Type label (`pk` / `fk` / `fk[]` / scalar type name; empty for notes). */
+    type: string;
+    y: number;
+    baseline: number;
+    x: number;
+    typeX: number;
+    /** Field rows only (undefined for notes). Key for hover linkage. */
+    fieldIndex?: number;
+}
+export interface SchemaLayoutTable {
+    name: string;
+    index: number;
+    x: number;
+    y: number;
+    w: number;
+    h: number;
+    headerH: number;
+    /** Text baseline y of the header (table name). */
+    headerBaseline: number;
+    /** Corner radius of the box. */
+    radius: number;
+    rows: SchemaLayoutRow[];
+}
+export interface SchemaLayoutGroup {
+    label: string;
+    x: number;
+    y: number;
+    w: number;
+    h: number;
+    /**
+     * Member table names (declaration order). Column reordering (independent groups pushed left)
+     * makes the order of `layout.groups` diverge from the declaration order of `model.groups`, so
+     * this lets the mapping be looked up without relying on index matching (used by
+     * `schemaGraphClientData`).
+     */
+    members: string[];
+}
+/**
+ * Minimal box shape read by edge routing (`SchemaLayoutTable` satisfies it structurally). The
+ * client passes data of this shape, embedded in the SVG, to the same `routeSchemaEdges` (= the
+ * routing rules aren't implemented twice).
+ */
+export interface SchemaRouteBox {
+    name: string;
+    index: number;
+    x: number;
+    y: number;
+    w: number;
+    h: number;
+    headerH: number;
+    /** Used to look up fk rows' y (no fieldIndex = note row). */
+    rows: readonly {
+        y: number;
+        fieldIndex?: number;
+    }[];
+}
+/** One interactive-UI (React Flow) node = a table box, with the static SVG's position / content. */
+export interface SchemaFlowNode {
+    name: string;
+    index: number;
+    x: number;
+    y: number;
+    w: number;
+    h: number;
+    headerH: number;
+    /** Rows (field / note). dy = center y from the box top (vertical position of the handle). */
+    rows: {
+        kind: SchemaField["kind"] | "note";
+        label: string;
+        type: string;
+        dy: number;
+        fieldIndex?: number;
+    }[];
+}
+/**
+ * Client data embedded in the SVG (`data-sg-layout`). The interactive UI (React Flow) reads only
+ * this and starts from the same picture as the static SVG (= no parse or layout on the client).
+ */
+export interface SchemaGraphClientData {
+    uid: string;
+    width: number;
+    height: number;
+    nodes: SchemaFlowNode[];
+    edges: SchemaEdge[];
+    /** Group frames (labeled only). members = member table names (to refit frames after drag). */
+    groups: {
+        label: string;
+        x: number;
+        y: number;
+        w: number;
+        h: number;
+        members: string[];
+    }[];
+    /**
+     * Source text of the table DSL as written (the `schemath` body itself). The interactive UI's
+     * source viewer shows it as-is. Not derived from the model, since rebuilding it from the model
+     * would lose notes / blank lines / ordering. When absent, the viewer button isn't shown.
+     */
+    source?: string;
+}
+/** One interactive-UI edge, with its exit and entry sides decided (independent of the UI lib). */
+export interface SchemaFlowEdge {
+    id: string;
+    from: string;
+    to: string;
+    fieldIndex: number;
+    list: boolean;
+    /** Exit side / entry side (l = left, r = right). Recomputed when a box moves. */
+    sourceSide: "l" | "r";
+    targetSide: "l" | "r";
+}
+/**
+ * Decides each edge's connecting sides from the current box positions (a pure function meant to
+ * be re-called on every drag). Target to the right: exit right, enter left; to the left: the
+ * reverse; overlapping: rightward.
+ */
+export declare const schemaFlowEdges: (nodes: readonly {
+    name: string;
+    x: number;
+    w: number;
+}[], edges: readonly SchemaEdge[]) => SchemaFlowEdge[];
+export interface SchemaLayoutEdge {
+    /** Table index (index into SchemaLayout.tables). */
+    from: number;
+    to: number;
+    fieldIndex: number;
+    list: boolean;
+    /** SVG path d: orthogonal, 3 segments up close, 5 below the tables between distant columns. */
+    d: string;
+}
+export interface SchemaLayout {
+    width: number;
+    height: number;
+    groups: SchemaLayoutGroup[];
+    tables: SchemaLayoutTable[];
+    edges: SchemaLayoutEdge[];
+    /** Baseline y of the legend (only when fk[] exists). */
+    legendY?: number;
+}
+/** Left edge of the legend / group labels (used by the renderer). */
+export declare const SCHEMA_LAYOUT_MARGIN: 16;
+/** Minimum gap between groups stacked in one band (tests use it to verify non-overlap). */
+export declare const SCHEMA_GAP_GROUP_Y: 40;
+/** Group frame label-area height / padding (tests use them to derive the "label top"). */
+export declare const SCHEMA_FRAME_LABEL_H: 22;
+export declare const SCHEMA_FRAME_PAD: 14;
+/**
+ * graph model → deterministic layout. Column bands are decided by the depth (level) of
+ * inter-group references: groups that reference no other group (including groups that are only
+ * referenced) are level 0; a referencing group is one level deeper than the group it references
+ * (= referenced groups land in bands to the left, referencing groups to the right). Reference
+ * cycles are cut deterministically by excluding back-edges to an ancestor on the search path
+ * from the level computation (see depthLevels).
+ * Bands run left → right in ascending level; groups in the same band stack top → bottom in
+ * declaration order (a band may hold several groups; independent groups land in the level-0
+ * band).
+ * Within a group (one group in a band), splitColumns may split the tables, in declaration order,
+ * into several internal columns.
+ * Edges leave from the fk field's row and enter the target box's header. Routes are bundled:
+ * edges that "enter the same target from the same column" share a trunk (vertical line) in the
+ * gutter next to that column and an entry point, so they merge into short exit stubs + one trunk
+ * + one crossing (the number of lines depends on target × column, not on the reference count).
+ * The same input always yields the same coordinates.
+ */
+export declare const layoutSchemaGraph: (model: SchemaModel) => SchemaLayout;
+export declare const routeSchemaEdges: (boxes: readonly SchemaRouteBox[], edges: readonly SchemaEdge[]) => SchemaLayoutEdge[];
+/** layout → interactive-UI data (payload embedded in the static SVG; same positions / content). */
+export declare const schemaGraphClientData: (uid: string, model: SchemaModel, layout: SchemaLayout, source?: string) => SchemaGraphClientData;