@formicoidea/labre-framework-c4 0.33.0

package/dist/type-line.js

@@ -0,0 +1,244 @@
+/**
+ * The middle tier of a C4 element's label — `[Person]`, `[Software System]`,
+ * `[Container: Java]` — SEMI-DERIVED: the word comes from the kind, the
+ * technology from the author.
+ *
+ * ## Semi-derived, and where the line actually lives
+ *
+ * The line is a real canvas TEXT element now (PO recette, 28/08/2026): a C4
+ * component is the shape and its own words, grouped, and every tier is edited in
+ * place like any other text on the canvas rather than typed into a form. So the
+ * string IS stored — but only half of it is the author's. The bracketed word is
+ * the notation's and comes from `kind`, which is what the renderer paints and
+ * what the exporter maps; letting an author retype it would be letting the words
+ * disagree with the picture.
+ *
+ * {@link normalizeC4TypeLine} is what keeps the halves apart. It runs when an
+ * edit COMMITS, reads whatever was typed for the one thing the notation leaves
+ * to the author — the technology — and writes the canonical line back. Type
+ * `Java` and the line becomes `[Container: Java]`; type `[Database: Java]` on a
+ * cylinder and it becomes `[Container: Java]`, because a database IS a container
+ * and the stencil says so.
+ */
+/**
+ * The base word each kind is announced by, verbatim from the stencil's own
+ * `<desc>` strings (`C4Model_default.svg`, the PO's reference model).
+ *
+ * Two readings are worth spelling out, because both look like mistakes:
+ *
+ * - `database` says **Container**, not "Database". The stencil labels the
+ *   cylinder `[Container: technology]` exactly as it labels the plain box: a
+ *   database is a CONTAINER, and the cylinder is a picture of one, not a fourth
+ *   level. (The mermaid export still emits `ContainerDb` — that is the one
+ *   specialisation mermaid's own grammar draws, and it is a different question
+ *   from what the box says on the canvas.)
+ * - an `-ext` variant says the same word as the kind it is external to. What
+ *   "external" changes is the COLOUR — grey — and the stencil's gray sheet
+ *   carries the identical `[Person]` / `[Software System]` wording.
+ *
+ * `Record<C4NodeKind, …>` and therefore compile-total: a kind added to the model
+ * without a word to announce it fails the build here.
+ */
+export const C4_TYPE_WORD = {
+    person: 'Person',
+    'person-ext': 'Person',
+    system: 'Software System',
+    'system-ext': 'Software System',
+    container: 'Container',
+    database: 'Container',
+    mobile: 'Container',
+    browser: 'Container',
+    component: 'Component',
+};
+/**
+ * The type line as it is drawn, brackets included.
+ *
+ * The technology is appended only when the author actually set one — an empty
+ * box, or one holding nothing but spaces, is not a technology and must not
+ * produce a dangling `[Container: ]`. Whitespace runs collapse for the same
+ * reason they do in the mermaid sanitizer: the line is one line.
+ *
+ * Pure, total and `std`-free, so the renderer, the exporter and a test can all
+ * ask the same question and get the same answer.
+ */
+export function c4TypeLine(kind, technology) {
+    const word = C4_TYPE_WORD[kind];
+    const techn = (technology ?? '').replaceAll(/\s+/g, ' ').trim();
+    return techn ? `[${word}: ${techn}]` : `[${word}]`;
+}
+/* ── Reading the line back ─────────────────────────────────────────────── */
+/**
+ * The type words, lowercased — the vocabulary a `<word>:` prefix is recognised
+ * against, and the whole reason {@link technologyOfTypeLine} does not simply cut
+ * at the first colon.
+ *
+ * Derived from {@link C4_TYPE_WORD} rather than restated, so a word added to the
+ * notation is understood on the way back in the moment it can be written out.
+ *
+ * Cutting at the first colon unconditionally was the obvious implementation and
+ * it is wrong on the one input an architect is most likely to paste: a URL. `an
+ * author typing "https://internal/docs" as their technology would have it read
+ * as the prefix `https` and keep `//internal/docs`. Matching the VOCABULARY
+ * instead can only ever strip a word the notation itself writes.
+ */
+const KNOWN_TYPE_WORDS = new Set(Object.values(C4_TYPE_WORD).map(word => word.toLowerCase()));
+/**
+ * The technology an author stated in a type line, whatever shape they left it
+ * in — `''` when they stated none.
+ *
+ * Total over every string, which is what it has to be: this reads a canvas TEXT
+ * element somebody edited in place, so its input is not a field with a grammar,
+ * it is whatever was typed. Every one of these is a line this has met:
+ *
+ * ```
+ * [Container: Java]  →  Java      the canonical form
+ * Container: Java    →  Java      brackets deleted while editing
+ * Java               →  Java      the whole line selected and retyped
+ * [Container]        →  ''        the word alone: no technology stated
+ * [Container: ]      →  ''        the technology deleted, brackets kept
+ * https://x/docs     →  https://x/docs   a colon that is NOT a prefix
+ * ```
+ *
+ * Pure and `std`-free, so the commit hook, the exporter and a test all read the
+ * same line the same way.
+ *
+ * It deliberately does NOT know about the creation placeholder: a node created
+ * and never touched carries `[Container: technology]`, and reading that as "no
+ * technology" here would make a focus-and-blur silently rewrite it to
+ * `[Container]` — the normalizer would eat the stencil's own prompt. The
+ * placeholder is a question for whoever asks what the element STATES, which is
+ * the exporter, and it is answered there.
+ */
+export function technologyOfTypeLine(text) {
+    const flat = (text ?? '')
+        .replaceAll(/[[\]]/g, ' ')
+        .replaceAll(/\s+/g, ' ')
+        .trim();
+    const colon = flat.indexOf(':');
+    // No colon at all: the line is either the bare notation word — which states no
+    // technology — or it is the technology, typed on its own.
+    if (colon < 0)
+        return KNOWN_TYPE_WORDS.has(flat.toLowerCase()) ? '' : flat;
+    const head = flat.slice(0, colon).trim().toLowerCase();
+    if (!KNOWN_TYPE_WORDS.has(head))
+        return flat;
+    return flat.slice(colon + 1).trim();
+}
+/**
+ * A type line as it must be STORED, whatever was typed into it.
+ *
+ * The semi-derived rule of the PO's recette, in one function: read the one half
+ * the author owns, write the whole line back from the kind. `[Person: Java]`
+ * typed on a container becomes `[Container: Java]`, a bare `Java` becomes
+ * `[Container: Java]`, and an emptied line becomes `[Container]`.
+ *
+ * Idempotent by construction — `normalize(normalize(x)) === normalize(x)` —
+ * which is what lets it run on every commit without a guard.
+ */
+export function normalizeC4TypeLine(kind, rawText) {
+    return c4TypeLine(kind, technologyOfTypeLine(rawText));
+}
+/* ── What a fresh element says before anybody writes on it ─────────────── */
+/**
+ * The word a fresh type line prompts the author with, in the technology's slot.
+ *
+ * The stencil's own: its container reads `[Container: technology]` before
+ * anybody fills it in. A prompt rather than a value — see
+ * {@link C4_TYPE_PLACEHOLDER}.
+ */
+export const TYPE_TECHNOLOGY_PLACEHOLDER = 'technology';
+/**
+ * Which kinds announce a technology in their type line AT ALL.
+ *
+ * The notation's own division and not mermaid's, though the two agree: a person
+ * is not built with a technology and a software system's is a level down, so
+ * both are written `[Person]` / `[Software System]` full stop. Every container
+ * — the cylinder, the phone and the browser window included — and every
+ * component carries `[Word: technology]`, because at those two levels "what is
+ * it built with" is the question the diagram exists to answer.
+ *
+ * This decides the PLACEHOLDER only. An author who types a technology onto a
+ * person gets it drawn, exactly as `c4TypeLine` has always drawn it: the
+ * notation is a prompt here, not a validator.
+ */
+export const C4_TYPE_TAKES_TECHNOLOGY = {
+    person: false,
+    'person-ext': false,
+    system: false,
+    'system-ext': false,
+    container: true,
+    database: true,
+    mobile: true,
+    browser: true,
+    component: true,
+};
+/**
+ * The type line a freshly created element is born carrying, per kind.
+ *
+ * Every tier of a C4 component exists from the moment it is drawn (PO
+ * arbitration, 28/08/2026), so the author meets three lines of stencil rather
+ * than a box and two invisible slots they have to be told about. What they meet
+ * is what the official stencil shows: `[Person]`, `[Software System]`,
+ * `[Container: technology]`, `[Component: technology]`.
+ *
+ * A PROMPT, not a value: {@link C4_TYPE_PLACEHOLDER} is what the exporter
+ * compares against to decide the author has stated nothing yet, so an untouched
+ * element exports as `Container(alias, "Container")` rather than as one built
+ * with a technology literally called "technology".
+ */
+export const C4_TYPE_PLACEHOLDER = Object.fromEntries(Object.keys(C4_TYPE_WORD).map(kind => [
+    kind,
+    c4TypeLine(kind, C4_TYPE_TAKES_TECHNOLOGY[kind] ? TYPE_TECHNOLOGY_PLACEHOLDER : undefined),
+]));
+/* ── What the line becomes when the shape becomes something else ───────── */
+/**
+ * The type line a component should carry once its shape has morphed from `from`
+ * to `to` — or `null` when the line is the AUTHOR's and must not be touched.
+ *
+ * ## Why a morph has to ask this at all
+ *
+ * The bracketed word is derived from `kind` (see the head of this file), so a
+ * shape that becomes a component while its caption still reads `[Container]` is
+ * a picture contradicting its own words. But the caption is a canvas TEXT
+ * element an architect may have typed anything into, and rewriting that would
+ * be the morph taking away something nobody asked it to touch. So the rule is
+ * the narrowest one that fixes the contradiction:
+ *
+ * - the SOURCE kind's untouched prompt (`[Container: technology]`) becomes the
+ *   TARGET's own prompt — `[Person]` on the way to a person, not `[Person:
+ *   technology]`, because a person is not built with a technology
+ *   ({@link C4_TYPE_TAKES_TECHNOLOGY});
+ * - a line that is exactly what the source kind DERIVES — `[Container: React]`,
+ *   the form {@link normalizeC4TypeLine} leaves behind after every edit — is
+ *   re-derived for the target, technology and all: `[Component: React]`;
+ * - anything else is the author's and comes back `null`. A line reading
+ *   `see ADR 0042`, or one mid-edit, survives the morph verbatim.
+ *
+ * The placeholder is tested FIRST and not folded into the second branch, which
+ * would find it too: `technologyOfTypeLine('[Container: technology]')` is the
+ * literal word `technology`, and carrying it across would hand a person the
+ * `[Person: technology]` no stencil ever draws.
+ *
+ * ## Inert on today's families, and kept anyway
+ *
+ * Every family declared in `./morph.ts` shares one {@link C4_TYPE_WORD} — all
+ * four containers say `Container`, both people say `Person`, both systems say
+ * `Software System` — and shares its {@link C4_TYPE_TAKES_TECHNOLOGY} answer
+ * too, so on the shipped table this function returns the line it was given and
+ * nothing visibly happens. That is a property of the FAMILIES, which are data
+ * and grow by declaration, not of the notation: the moment a family gains a
+ * member that announces itself differently, the caption follows the shape
+ * without anyone being prompted to remember it should.
+ *
+ * Pure, total and `std`-free, like everything else in this file.
+ */
+export function c4MorphedTypeLine(from, to, rawText) {
+    const text = (rawText ?? '').trim();
+    if (!text)
+        return null;
+    if (text === C4_TYPE_PLACEHOLDER[from])
+        return C4_TYPE_PLACEHOLDER[to];
+    if (text !== normalizeC4TypeLine(from, text))
+        return null;
+    return c4TypeLine(to, technologyOfTypeLine(text));
+}

package/dist/view.d.ts

@@ -0,0 +1,33 @@
+import { type ViewExtensionContext, ViewExtensionProvider } from '@formicoidea/labre-core/ext-loader';
+/**
+ * C4 rendering — ALWAYS registered, independent of any flag. Boards, boundaries
+ * and nodes already drawn must paint, stay selectable, stay editable and keep
+ * their resize gating whatever the tooling flag says. See `docs/adr/0009`.
+ *
+ * This is the RENDER half. The creation tooling — the senior button, its menu
+ * and its commands — is {@link C4ViewExtension} below, exactly as
+ * `BpmnViewExtension` is separate from `BpmnRenderViewExtension`. Nothing in
+ * this class may become flag-gated: a stored document needs every one of these
+ * registrations to load and paint.
+ */
+export declare class C4RenderViewExtension extends ViewExtensionProvider {
+    name: string;
+    setup(context: ViewExtensionContext): void;
+}
+/**
+ * C4 creation tooling — flag-gated (`c4`): the senior toolbar button, its
+ * sub-menu, the thirteen commands behind them, the board's legend button, the
+ * component's "Change type" dropdown, and the validation rules and profiles.
+ *
+ * All of it is tooling in the sense `docs/adr/0009` means: a diagram drawn while
+ * the flag was on keeps painting, stays selectable and keeps its contextual
+ * toolbar when it goes off — only the ways to add new elements go away, the
+ * legend included since generating one CREATES elements, and the checking stops.
+ * The profile a board was put on stays written, unread, until the flag comes
+ * back.
+ */
+export declare class C4ViewExtension extends ViewExtensionProvider {
+    name: string;
+    effect(): void;
+    setup(context: ViewExtensionContext): void;
+}

package/dist/view.js

@@ -0,0 +1,148 @@
+import { FrameworkBackgroundInteractionExtension, InterchangeExtension, morphToolbarConfig, ValidationProfileExtension, ValidationRuleExtension, } from '@formicoidea/labre-core/blocks/surface';
+import { ViewExtensionProvider, } from '@formicoidea/labre-core/ext-loader';
+import { ToolbarModuleExtension, toolbarModuleKey, } from '@formicoidea/labre-core/shared/services';
+import { BlockFlavourIdentifier, CommandExtension } from '@formicoidea/labre-core/std';
+import { RoleVocabularyExtension } from '@formicoidea/labre-core/std/gfx';
+import { C4_BOARD_BACKGROUND, C4_BOUNDARY_BACKGROUND } from './background.js';
+import { c4CommandIcons, c4Commands } from './commands.js';
+import { effects } from './effects.js';
+import { C4BoardRendererExtension, C4BoundaryRendererExtension, } from './element-renderer.js';
+import { C4BoardView, C4BoundaryView } from './element-view.js';
+import { C4_INTERCHANGE } from './interchange.js';
+import { C4_MORPH_SPEC } from './morph.js';
+import { C4NodeRendererExtension } from './node/node-renderer.js';
+import { C4NodeView } from './node/node-view.js';
+import { C4TypeLineWatcher } from './node/type-line-watcher.js';
+import { C4_PROFILES } from './profiles.js';
+import { C4_ROLES } from './roles.js';
+import { C4_RULES } from './rules.js';
+import { c4BoardToolbarExtension, c4BoardToolingToolbarExtension, } from './toolbar/config.js';
+import { c4SeniorTool } from './toolbar/senior-tool.js';
+/**
+ * C4 rendering — ALWAYS registered, independent of any flag. Boards, boundaries
+ * and nodes already drawn must paint, stay selectable, stay editable and keep
+ * their resize gating whatever the tooling flag says. See `docs/adr/0009`.
+ *
+ * This is the RENDER half. The creation tooling — the senior button, its menu
+ * and its commands — is {@link C4ViewExtension} below, exactly as
+ * `BpmnViewExtension` is separate from `BpmnRenderViewExtension`. Nothing in
+ * this class may become flag-gated: a stored document needs every one of these
+ * registrations to load and paint.
+ */
+export class C4RenderViewExtension extends ViewExtensionProvider {
+    constructor() {
+        super(...arguments);
+        this.name = 'affine-c4-render-gfx';
+    }
+    setup(context) {
+        super.setup(context);
+        context.register(C4BoardView);
+        context.register(C4BoardRendererExtension);
+        context.register(C4BoundaryView);
+        context.register(C4BoundaryRendererExtension);
+        context.register(C4NodeView);
+        context.register(C4NodeRendererExtension);
+        // The role VOCABULARY, always on. A role is written in the document, not in
+        // the tooling: the direction reveal of the relationship, the inversion
+        // command and the toolbar entry that must not lie about a typed edge all
+        // read this, and they have to keep working on a diagram drawn while the flag
+        // was on and opened while it is off (`docs/adr/0009`, `docs/adr/0010`).
+        context.register(RoleVocabularyExtension(C4_ROLES));
+        if (this.isEdgeless(context.scope)) {
+            // Resize gating, driven by the declarations like every other framework
+            // background: the handles follow `resizeEnabled`, which both declarations
+            // seed to `true` — a diagram and a boundary are both stretched to fit.
+            context.register(FrameworkBackgroundInteractionExtension(C4_BOARD_BACKGROUND));
+            context.register(FrameworkBackgroundInteractionExtension(C4_BOUNDARY_BACKGROUND));
+            // The selected board's own row — the resize toggle half of it. Always-on
+            // for the reason `docs/adr/0009` gives: a stored board must keep its
+            // handles usable with the C4 button switched off. The legend button is a
+            // second module, registered by the flag-gated half below.
+            context.register(c4BoardToolbarExtension);
+            // Keeps a component's type line semi-derived while its author types into
+            // it: the word from the kind, the technology from them. Always-on for the
+            // reason `docs/adr/0009` gives — it authors nothing, it keeps an element
+            // already in the document readable, and a diagram drawn while the C4
+            // button was on must stay editable when it goes off.
+            context.register(C4TypeLineWatcher);
+        }
+    }
+}
+/**
+ * C4 creation tooling — flag-gated (`c4`): the senior toolbar button, its
+ * sub-menu, the thirteen commands behind them, the board's legend button, the
+ * component's "Change type" dropdown, and the validation rules and profiles.
+ *
+ * All of it is tooling in the sense `docs/adr/0009` means: a diagram drawn while
+ * the flag was on keeps painting, stays selectable and keeps its contextual
+ * toolbar when it goes off — only the ways to add new elements go away, the
+ * legend included since generating one CREATES elements, and the checking stops.
+ * The profile a board was put on stays written, unread, until the flag comes
+ * back.
+ */
+export class C4ViewExtension extends ViewExtensionProvider {
+    constructor() {
+        super(...arguments);
+        this.name = 'affine-c4-gfx';
+    }
+    effect() {
+        super.effect();
+        // Defines the senior button and its menu — tooling-only custom elements.
+        effects();
+    }
+    setup(context) {
+        super.setup(context);
+        if (this.isEdgeless(context.scope)) {
+            context.register(ValidationRuleExtension(C4_RULES));
+            context.register(ValidationProfileExtension(C4_PROFILES));
+            // Writing mermaid files, declared rather than assumed (`docs/adr/0012`).
+            // Tooling like the rest of this class: with the flag off there is nothing
+            // to export WITH, while a stored diagram keeps painting (`docs/adr/0009`).
+            context.register(InterchangeExtension(C4_INTERCHANGE));
+            context.register(c4SeniorTool);
+            context.register(CommandExtension(c4Commands, c4CommandIcons));
+            // The flag-gated half of the selected BOARD's row, through the `custom:`
+            // flavour slot — the shape wardley, bpmn and the context map all use to
+            // hang flag-gated entries off a row whose base is always-on. One module,
+            // carrying the legend button AND the Validation dropdown, because the two
+            // halves are gated by this one flag and there is no reason to spend a
+            // second registration on them (`toolbarModuleKey`, used further down for
+            // the group's row, is what a THIRD contributor to one element needs).
+            //
+            // There is no boundary module, and no rule of this pack goes unarbitrated
+            // for want of one: the board alone arbitrates the checklist (PO,
+            // 28/08/2026), and a boundary inherits its board's choice in the engine
+            // (`inheritChosenProfiles`), so the two boundary-anchored rules harden
+            // with the rest. See `toolbar/config.ts`, where every flavour claim of
+            // this framework lives.
+            context.register(c4BoardToolingToolbarExtension);
+            // The "Change type" dropdown on a selected COMPONENT's contextual
+            // toolbar — the generic module, parameterized by C4's own families.
+            //
+            // ## Why the key carries an owner
+            //
+            // A C4 component is a native `group`, so the row the toolbar draws for it
+            // is the GROUP's row, merged from `affine:surface:group`,
+            // `custom:affine:surface:group` and the two surface wildcards. Both group
+            // keys were already claimed — the first by the native group operations
+            // (rename, ungroup), the second by Wardley's qualification dropdown,
+            // which is on the group for the very same reason this is — and a second
+            // module on either would have thrown `DuplicateServiceDefinitionError`
+            // before the editor finished setting up. That ceiling of two contributors
+            // per element is what `toolbarModuleKey` lifts: the module is registered
+            // under the DISTINCT variant `custom:affine:surface:group#c4-morph` and
+            // the registry hands it to the same row (`toolbar-service/registry.ts`).
+            //
+            // ## Why here
+            //
+            // In the flag-gated half, because a morph is TOOLING: a component drawn
+            // while the flag was on keeps its kind, its role, its colours, its words
+            // and its place in every rule when the flag goes off — it just stops
+            // being something the toolbar offers to say differently (`docs/adr/0009`).
+            context.register(ToolbarModuleExtension({
+                id: BlockFlavourIdentifier(toolbarModuleKey('custom:affine:surface:group', 'c4-morph')),
+                config: morphToolbarConfig(C4_MORPH_SPEC),
+            }));
+        }
+    }
+}

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "@formicoidea/labre-framework-c4",
+  "description": "Labre c4 framework for @formicoidea/labre-core.",
+  "version": "0.33.0",
+  "type": "module",
+  "sideEffects": false,
+  "author": "lajola",
+  "contributors": [
+    "toeverything"
+  ],
+  "license": "MPL-2.0",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./view": {
+      "types": "./dist/view.d.ts",
+      "import": "./dist/view.js"
+    },
+    "./descriptor": {
+      "types": "./dist/descriptor.d.ts",
+      "import": "./dist/descriptor.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "dependencies": {
+    "@formicoidea/labre-core": "0.33.0",
+    "@formicoidea/labre-ddd-shared": "0.33.0",
+    "lit": "^3.2.0"
+  }
+}