@miragon/team-topologies-schema-model 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,628 @@
+import { z } from 'zod';
+
+/**
+ * Pure (DOM-free) domain types for the Team Topologies model.
+ *
+ * This module is the canonical representation of a diagram and must never
+ * import from the rendering layer (`@xyflow/react`) or touch the DOM, so it
+ * can be unit-tested in isolation and reused across views / exporters.
+ */
+/** MIME type used when dragging a team type from the palette onto the canvas. */
+declare const DND_MIME = "application/x-tt-team-type";
+/** The four fundamental team types in Team Topologies. */
+type TeamType = "stream-aligned" | "enabling" | "complicated-subsystem" | "platform";
+declare const TEAM_TYPES: readonly TeamType[];
+/** The three core team interaction modes in Team Topologies. */
+type InteractionMode = "collaboration" | "x-as-a-service" | "facilitating";
+declare const INTERACTION_MODES: readonly InteractionMode[];
+/** Geometric size of a node in canvas units (px). Encodes cognitive load. */
+interface Size {
+    width: number;
+    height: number;
+}
+/** Position of a node on the canvas in canvas units (px). */
+interface Position {
+    x: number;
+    y: number;
+}
+/** A team node in the canonical document model. */
+interface TeamNode {
+    id: string;
+    type: TeamType;
+    label: string;
+    description?: string;
+    position: Position;
+    size: Size;
+    fill?: string;
+    stroke?: string;
+}
+/**
+ * An interaction in the canonical document model.
+ *
+ * Per the official Team Topologies notation, an interaction is a placed,
+ * resizable SHAPE (parallelogram / triangle / circle) overlaid on the boundary
+ * between the teams it relates to — not a connecting line. The relationship is
+ * therefore spatial (overlap), so there is no source/target reference.
+ */
+interface InteractionShape {
+    id: string;
+    mode: InteractionMode;
+    label?: string;
+    position: Position;
+    size: Size;
+    fill?: string;
+    stroke?: string;
+}
+/**
+ * A "flow of change" guide: a placed, resizable arrow element. Lets you anchor
+ * the implied left-to-right flow, and visualise several team groupings on one
+ * canvas.
+ */
+interface FlowShape {
+    id: string;
+    label?: string;
+    position: Position;
+    size: Size;
+}
+/** Current document schema version. Bump + add a migration when shape changes. */
+declare const DOCUMENT_VERSION: 2;
+/**
+ * A complete Team Topologies diagram. This is what gets serialised to JSON,
+ * embedded into exported images, and encoded into share URLs.
+ */
+interface TtDocument {
+    version: typeof DOCUMENT_VERSION;
+    title: string;
+    nodes: TeamNode[];
+    interactions: InteractionShape[];
+    flows: FlowShape[];
+}
+
+/**
+ * The Team Topologies visual notation, encoded as data.
+ *
+ * Colours, shapes and stroke styles follow the official
+ * "Team-Shape-Templates" specification published by Team Topologies
+ * (https://github.com/TeamTopologies/Team-Shape-Templates):
+ *
+ *  - Team shapes are SOLID outlines (long-lived structures).
+ *  - Interaction-mode shapes are 50% transparent with DASHED outlines
+ *    (short-lived interactions).
+ *  - Each element is distinguished by SHAPE as well as colour, so the
+ *    notation stays readable for people with colour-vision deficiency.
+ *
+ * This module is pure data — it must not import the rendering layer.
+ */
+
+type TeamShape = "rounded-rect-horizontal" | "rounded-rect-vertical" | "octagon" | "rect";
+type InteractionGlyph = "parallelogram" | "triangle" | "circle";
+type StrokeStyle = "solid" | "dashed" | "dotted";
+interface TeamTypeSpec {
+    type: TeamType;
+    /** Short display name. */
+    label: string;
+    /** One-line purpose, shown in the palette and inspector. */
+    description: string;
+    shape: TeamShape;
+    fill: string;
+    stroke: string;
+    strokeStyle: StrokeStyle;
+    strokeWidth: number;
+    /** Default size when a node of this type is created. */
+    defaultSize: Size;
+    /** Minimum size enforced by the resizer. */
+    minSize: Size;
+}
+interface InteractionModeSpec {
+    mode: InteractionMode;
+    label: string;
+    description: string;
+    shape: InteractionGlyph;
+    fill: string;
+    stroke: string;
+    strokeStyle: StrokeStyle;
+    strokeWidth: number;
+    /** Opacity for the interaction shape (short-lived → translucent). */
+    opacity: number;
+    /** Whether direction is semantically meaningful (the X-as-a-Service triangle). */
+    directional: boolean;
+    /** Default size when a shape of this mode is created. */
+    defaultSize: Size;
+    /** Minimum size enforced by the resizer. */
+    minSize: Size;
+}
+/** The left-to-right "flow of change" guide, a placeable annotation element. */
+interface FlowSpec {
+    label: string;
+    fill: string;
+    stroke: string;
+    strokeStyle: StrokeStyle;
+    strokeWidth: number;
+    defaultSize: Size;
+    minSize: Size;
+}
+declare const TEAM_TYPE_SPECS: Record<TeamType, TeamTypeSpec>;
+declare const INTERACTION_MODE_SPECS: Record<InteractionMode, InteractionModeSpec>;
+/**
+ * The "flow of change" guide — a placeable dashed arrow (left-to-right).
+ * Not a team or interaction: a standalone annotation element.
+ */
+declare const FLOW_SPEC: FlowSpec;
+/** Maps a stroke style to an SVG/CSS dash array (empty string = solid). */
+declare function dashArray(style: StrokeStyle, strokeWidth?: number): string;
+declare const ALL_TEAM_SPECS: readonly TeamTypeSpec[];
+declare const ALL_INTERACTION_SPECS: readonly InteractionModeSpec[];
+
+/**
+ * Runtime validation for the document model using Zod.
+ *
+ * Anything entering the app from the outside world (imported files, share
+ * URLs, localStorage) is parsed through {@link parseDocument} so malformed or
+ * tampered data can never corrupt the editor state.
+ */
+
+declare const teamNodeSchema: z.ZodObject<{
+    id: z.ZodString;
+    type: z.ZodEnum<[string, ...string[]]>;
+    label: z.ZodString;
+    description: z.ZodOptional<z.ZodString>;
+    position: z.ZodObject<{
+        x: z.ZodNumber;
+        y: z.ZodNumber;
+    }, "strip", z.ZodTypeAny, {
+        x: number;
+        y: number;
+    }, {
+        x: number;
+        y: number;
+    }>;
+    size: z.ZodObject<{
+        width: z.ZodNumber;
+        height: z.ZodNumber;
+    }, "strip", z.ZodTypeAny, {
+        width: number;
+        height: number;
+    }, {
+        width: number;
+        height: number;
+    }>;
+    fill: z.ZodOptional<z.ZodString>;
+    stroke: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    type: string;
+    id: string;
+    label: string;
+    position: {
+        x: number;
+        y: number;
+    };
+    size: {
+        width: number;
+        height: number;
+    };
+    fill?: string | undefined;
+    description?: string | undefined;
+    stroke?: string | undefined;
+}, {
+    type: string;
+    id: string;
+    label: string;
+    position: {
+        x: number;
+        y: number;
+    };
+    size: {
+        width: number;
+        height: number;
+    };
+    fill?: string | undefined;
+    description?: string | undefined;
+    stroke?: string | undefined;
+}>;
+declare const interactionSchema: z.ZodObject<{
+    id: z.ZodString;
+    mode: z.ZodEnum<[string, ...string[]]>;
+    label: z.ZodOptional<z.ZodString>;
+    position: z.ZodObject<{
+        x: z.ZodNumber;
+        y: z.ZodNumber;
+    }, "strip", z.ZodTypeAny, {
+        x: number;
+        y: number;
+    }, {
+        x: number;
+        y: number;
+    }>;
+    size: z.ZodObject<{
+        width: z.ZodNumber;
+        height: z.ZodNumber;
+    }, "strip", z.ZodTypeAny, {
+        width: number;
+        height: number;
+    }, {
+        width: number;
+        height: number;
+    }>;
+    fill: z.ZodOptional<z.ZodString>;
+    stroke: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    id: string;
+    position: {
+        x: number;
+        y: number;
+    };
+    size: {
+        width: number;
+        height: number;
+    };
+    mode: string;
+    fill?: string | undefined;
+    label?: string | undefined;
+    stroke?: string | undefined;
+}, {
+    id: string;
+    position: {
+        x: number;
+        y: number;
+    };
+    size: {
+        width: number;
+        height: number;
+    };
+    mode: string;
+    fill?: string | undefined;
+    label?: string | undefined;
+    stroke?: string | undefined;
+}>;
+declare const flowSchema: z.ZodObject<{
+    id: z.ZodString;
+    label: z.ZodOptional<z.ZodString>;
+    position: z.ZodObject<{
+        x: z.ZodNumber;
+        y: z.ZodNumber;
+    }, "strip", z.ZodTypeAny, {
+        x: number;
+        y: number;
+    }, {
+        x: number;
+        y: number;
+    }>;
+    size: z.ZodObject<{
+        width: z.ZodNumber;
+        height: z.ZodNumber;
+    }, "strip", z.ZodTypeAny, {
+        width: number;
+        height: number;
+    }, {
+        width: number;
+        height: number;
+    }>;
+}, "strip", z.ZodTypeAny, {
+    id: string;
+    position: {
+        x: number;
+        y: number;
+    };
+    size: {
+        width: number;
+        height: number;
+    };
+    label?: string | undefined;
+}, {
+    id: string;
+    position: {
+        x: number;
+        y: number;
+    };
+    size: {
+        width: number;
+        height: number;
+    };
+    label?: string | undefined;
+}>;
+declare const documentSchema: z.ZodObject<{
+    version: z.ZodLiteral<2>;
+    title: z.ZodString;
+    nodes: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        type: z.ZodEnum<[string, ...string[]]>;
+        label: z.ZodString;
+        description: z.ZodOptional<z.ZodString>;
+        position: z.ZodObject<{
+            x: z.ZodNumber;
+            y: z.ZodNumber;
+        }, "strip", z.ZodTypeAny, {
+            x: number;
+            y: number;
+        }, {
+            x: number;
+            y: number;
+        }>;
+        size: z.ZodObject<{
+            width: z.ZodNumber;
+            height: z.ZodNumber;
+        }, "strip", z.ZodTypeAny, {
+            width: number;
+            height: number;
+        }, {
+            width: number;
+            height: number;
+        }>;
+        fill: z.ZodOptional<z.ZodString>;
+        stroke: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        type: string;
+        id: string;
+        label: string;
+        position: {
+            x: number;
+            y: number;
+        };
+        size: {
+            width: number;
+            height: number;
+        };
+        fill?: string | undefined;
+        description?: string | undefined;
+        stroke?: string | undefined;
+    }, {
+        type: string;
+        id: string;
+        label: string;
+        position: {
+            x: number;
+            y: number;
+        };
+        size: {
+            width: number;
+            height: number;
+        };
+        fill?: string | undefined;
+        description?: string | undefined;
+        stroke?: string | undefined;
+    }>, "many">;
+    interactions: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        mode: z.ZodEnum<[string, ...string[]]>;
+        label: z.ZodOptional<z.ZodString>;
+        position: z.ZodObject<{
+            x: z.ZodNumber;
+            y: z.ZodNumber;
+        }, "strip", z.ZodTypeAny, {
+            x: number;
+            y: number;
+        }, {
+            x: number;
+            y: number;
+        }>;
+        size: z.ZodObject<{
+            width: z.ZodNumber;
+            height: z.ZodNumber;
+        }, "strip", z.ZodTypeAny, {
+            width: number;
+            height: number;
+        }, {
+            width: number;
+            height: number;
+        }>;
+        fill: z.ZodOptional<z.ZodString>;
+        stroke: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        id: string;
+        position: {
+            x: number;
+            y: number;
+        };
+        size: {
+            width: number;
+            height: number;
+        };
+        mode: string;
+        fill?: string | undefined;
+        label?: string | undefined;
+        stroke?: string | undefined;
+    }, {
+        id: string;
+        position: {
+            x: number;
+            y: number;
+        };
+        size: {
+            width: number;
+            height: number;
+        };
+        mode: string;
+        fill?: string | undefined;
+        label?: string | undefined;
+        stroke?: string | undefined;
+    }>, "many">;
+    flows: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        label: z.ZodOptional<z.ZodString>;
+        position: z.ZodObject<{
+            x: z.ZodNumber;
+            y: z.ZodNumber;
+        }, "strip", z.ZodTypeAny, {
+            x: number;
+            y: number;
+        }, {
+            x: number;
+            y: number;
+        }>;
+        size: z.ZodObject<{
+            width: z.ZodNumber;
+            height: z.ZodNumber;
+        }, "strip", z.ZodTypeAny, {
+            width: number;
+            height: number;
+        }, {
+            width: number;
+            height: number;
+        }>;
+    }, "strip", z.ZodTypeAny, {
+        id: string;
+        position: {
+            x: number;
+            y: number;
+        };
+        size: {
+            width: number;
+            height: number;
+        };
+        label?: string | undefined;
+    }, {
+        id: string;
+        position: {
+            x: number;
+            y: number;
+        };
+        size: {
+            width: number;
+            height: number;
+        };
+        label?: string | undefined;
+    }>, "many">;
+}, "strip", z.ZodTypeAny, {
+    version: 2;
+    title: string;
+    nodes: {
+        type: string;
+        id: string;
+        label: string;
+        position: {
+            x: number;
+            y: number;
+        };
+        size: {
+            width: number;
+            height: number;
+        };
+        fill?: string | undefined;
+        description?: string | undefined;
+        stroke?: string | undefined;
+    }[];
+    interactions: {
+        id: string;
+        position: {
+            x: number;
+            y: number;
+        };
+        size: {
+            width: number;
+            height: number;
+        };
+        mode: string;
+        fill?: string | undefined;
+        label?: string | undefined;
+        stroke?: string | undefined;
+    }[];
+    flows: {
+        id: string;
+        position: {
+            x: number;
+            y: number;
+        };
+        size: {
+            width: number;
+            height: number;
+        };
+        label?: string | undefined;
+    }[];
+}, {
+    version: 2;
+    title: string;
+    nodes: {
+        type: string;
+        id: string;
+        label: string;
+        position: {
+            x: number;
+            y: number;
+        };
+        size: {
+            width: number;
+            height: number;
+        };
+        fill?: string | undefined;
+        description?: string | undefined;
+        stroke?: string | undefined;
+    }[];
+    interactions: {
+        id: string;
+        position: {
+            x: number;
+            y: number;
+        };
+        size: {
+            width: number;
+            height: number;
+        };
+        mode: string;
+        fill?: string | undefined;
+        label?: string | undefined;
+        stroke?: string | undefined;
+    }[];
+    flows: {
+        id: string;
+        position: {
+            x: number;
+            y: number;
+        };
+        size: {
+            width: number;
+            height: number;
+        };
+        label?: string | undefined;
+    }[];
+}>;
+type ParseResult = {
+    ok: true;
+    document: TtDocument;
+} | {
+    ok: false;
+    error: string;
+};
+/**
+ * Validates and (if necessary) migrates unknown data into a {@link TtDocument}.
+ * Returns a discriminated result rather than throwing so callers can show a
+ * friendly message.
+ */
+declare function parseDocument(input: unknown): ParseResult;
+
+/**
+ * Deterministic serialisation of the document model.
+ *
+ * Producing byte-stable JSON (sorted arrays, fixed key order, rounded
+ * coordinates) makes diagrams diff-friendly in version control and gives
+ * stable share URLs / embedded payloads.
+ */
+
+/** Returns a canonicalised copy of a document (sorted, rounded, version-stamped). */
+declare function canonicalize(doc: TtDocument): TtDocument;
+/** Serialises a document to deterministic, pretty-printed JSON. */
+declare function serializeDocument(doc: TtDocument, pretty?: boolean): string;
+
+/**
+ * Factory helpers for constructing well-formed model objects with the correct
+ * notation defaults (sizes, labels). Kept DOM-free.
+ */
+
+declare function newId(prefix: string): string;
+/** Creates a team node of the given type at a position, with notation defaults. */
+declare function createTeamNode(type: TeamType, position: Position, overrides?: Partial<Omit<TeamNode, "id" | "type">>): TeamNode;
+/** Creates a placed interaction shape of the given mode, with notation defaults. */
+declare function createInteractionShape(mode: InteractionMode, position: Position, overrides?: Partial<Omit<InteractionShape, "id" | "mode" | "position">>): InteractionShape;
+/** Creates a placed "flow of change" arrow, with notation defaults. */
+declare function createFlowShape(position: Position, overrides?: Partial<Omit<FlowShape, "id" | "position">>): FlowShape;
+/** An empty document with sensible defaults. */
+declare function emptyDocument(title?: string): TtDocument;
+
+/**
+ * A small but complete example diagram exercising all four team types, all three
+ * interaction modes (as placed shapes overlaying the team boundaries) and a
+ * flow-of-change element. Ids are fixed so the fixture serialises stably.
+ */
+
+declare const SAMPLE_DOCUMENT: TtDocument;
+
+export { ALL_INTERACTION_SPECS, ALL_TEAM_SPECS, DND_MIME, DOCUMENT_VERSION, FLOW_SPEC, type FlowShape, type FlowSpec, INTERACTION_MODES, INTERACTION_MODE_SPECS, type InteractionGlyph, type InteractionMode, type InteractionModeSpec, type InteractionShape, type ParseResult, type Position, SAMPLE_DOCUMENT, type Size, type StrokeStyle, TEAM_TYPES, TEAM_TYPE_SPECS, type TeamNode, type TeamShape, type TeamType, type TeamTypeSpec, type TtDocument, canonicalize, createFlowShape, createInteractionShape, createTeamNode, dashArray, documentSchema, emptyDocument, flowSchema, interactionSchema, newId, parseDocument, serializeDocument, teamNodeSchema };