@formicoidea/labre-framework-edgy 0.32.0 → 0.33.0

package/dist/roles.js

@@ -0,0 +1,182 @@
+import { EDGY_DYNAMIC_NODES, EDGY_DYNAMIC_RELATIONS, edgyElementLabel, } from './metamodel.js';
+import { NODE_LABEL } from './node/consts.js';
+/** Role ids, keyed by the name used at the creation sites. */
+export const EDGY_ROLE = {
+    element: 'edgy:element',
+    // The four persisted kinds (`EdgyNodeKind`).
+    people: 'edgy:people',
+    outcome: 'edgy:outcome',
+    object: 'edgy:object',
+    activity: 'edgy:activity',
+    // The twelve official elements.
+    purpose: 'edgy:purpose',
+    capability: 'edgy:capability',
+    task: 'edgy:task',
+    story: 'edgy:story',
+    process: 'edgy:process',
+    journey: 'edgy:journey',
+    content: 'edgy:content',
+    asset: 'edgy:asset',
+    channel: 'edgy:channel',
+    organisation: 'edgy:organisation',
+    product: 'edgy:product',
+    brand: 'edgy:brand',
+    // The two frames.
+    background: 'edgy:background',
+    facets: 'edgy:facets',
+    board: 'edgy:board',
+    // The parent of the 22 verbs.
+    relation: 'edgy:relation',
+};
+/**
+ * A canonical verb, as a role id: `is part of` → `edgy:is-part-of`.
+ *
+ * The verb IS the identifier, so a relation added to the metamodel gets its
+ * role for free and nobody has to remember to name it. No collision with the
+ * element roles above is possible in the metamodel as it stands, and a future
+ * verb colliding with an element name would be caught by the unit spec, which
+ * counts the vocabulary.
+ */
+function verbRoleId(verb) {
+    return `edgy:${verb.replace(/\s+/g, '-')}`;
+}
+/**
+ * Role id per canonical verb, DERIVED from {@link EDGY_DYNAMIC_RELATIONS}.
+ *
+ * Derived rather than restated: the metamodel is written once (`./metamodel.ts`)
+ * and the template that draws it, the vocabulary that names it and the rule that
+ * checks it all read the same table. `requires` appears on three rows and gets
+ * ONE role — a verb is a verb wherever it is spoken, and the three sentences it
+ * belongs to are three triplets, not three roles.
+ */
+export const EDGY_VERB_ROLE = Object.assign(Object.create(null), Object.fromEntries(EDGY_DYNAMIC_RELATIONS.map(([, , verb]) => [verb, verbRoleId(verb)])));
+/**
+ * Key of an ORDERED pair of element roles: `edgy:process edgy:capability`.
+ *
+ * A SPACE separates them, and not `-`, `:` or `>`: a role id already contains a
+ * colon and may contain a dash (`edgy:is-part-of`), and a separator that can
+ * occur inside a value is a lookup table with collisions waiting in it. No role
+ * id has ever contained whitespace — `verbRoleId` above replaces it on the one
+ * family that could.
+ */
+export const edgyPairKey = (source, target) => `${source} ${target}`;
+/**
+ * Ordered pair of ELEMENT roles → the canonical verb the metamodel gives it,
+ * DERIVED from {@link EDGY_DYNAMIC_RELATIONS}.
+ *
+ * The metamodel's 24 rows are 24 DISTINCT ordered pairs, so the verb of a
+ * relation is entirely determined by which two elements it runs between: there
+ * is never a choice to offer. That is what lets the toolbox ship ONE "Relation"
+ * entry instead of twenty-two, and what `./relation.ts` reads to name a
+ * hand-drawn link after the pair the user attached it to.
+ *
+ * Derived, never restated — same contract as {@link EDGY_VERB_ROLE}: a relation
+ * added to `./metamodel.ts` becomes nameable by hand without anybody editing
+ * this file.
+ */
+export const EDGY_PAIR_TO_VERB = Object.assign(Object.create(null), Object.fromEntries(EDGY_DYNAMIC_RELATIONS.map(([source, target, verb]) => [
+    edgyPairKey(EDGY_ROLE[source], EDGY_ROLE[target]),
+    verb,
+])));
+/** i18n key stem of a role id: `edgy:is-part-of` → `com.labre.edgy.role.is-part-of`. */
+const roleKey = (id) => `com.labre.edgy.role.${id.slice('edgy:'.length)}`;
+const ELEMENT_DEFS = [
+    // The root of every artefact a board is made of. A rule written here covers
+    // the four kinds and the twelve elements at once — which is exactly what
+    // `edgy.overlapping-artefacts` needs and why the root exists.
+    {
+        id: EDGY_ROLE.element,
+        kind: 'node',
+        labelKey: roleKey(EDGY_ROLE.element),
+        labelFallback: 'Element',
+    },
+    // The four PERSISTED kinds. They are the base shapes the toolbox offers, so
+    // they are what an element created from the palette carries: somebody
+    // dropping an "Object" on the board has said "object" and nothing more, and
+    // the role says exactly that much.
+    //
+    // The fallback is the wording the palette itself writes inside the shape
+    // (`node/consts.ts`), so a reader who meets the role in a legend or a
+    // direction reveal meets the word they dropped on the board.
+    ...['people', 'outcome', 'object', 'activity'].map(kind => ({
+        id: EDGY_ROLE[kind],
+        parent: EDGY_ROLE.element,
+        kind: 'node',
+        labelKey: roleKey(EDGY_ROLE[kind]),
+        labelFallback: NODE_LABEL[kind],
+    })),
+    // The twelve official elements, each under the kind the metamodel draws it
+    // with — Purpose is an outcome, Story an activity, Channel an object. The
+    // parent is READ from `EDGY_DYNAMIC_NODES` rather than restated: the diagram
+    // and the vocabulary cannot drift apart if there is only one table. So is the
+    // fallback wording, from the same table's own names.
+    ...Object.entries(EDGY_DYNAMIC_NODES).map(([name, { kind }]) => ({
+        id: EDGY_ROLE[name],
+        parent: EDGY_ROLE[kind],
+        kind: 'node',
+        labelKey: roleKey(EDGY_ROLE[name]),
+        labelFallback: edgyElementLabel(name),
+    })),
+];
+const BACKGROUND_DEFS = [
+    // The frame, and deliberately NOT a child of `edgy:element`: a rule written
+    // on the artefacts must never match the board they are drawn on. Two frames
+    // specialise it — the facets diagram and the blank board — so a rule
+    // attributes its findings to whichever one the user is working on without
+    // naming either.
+    {
+        id: EDGY_ROLE.background,
+        kind: 'node',
+        labelKey: roleKey(EDGY_ROLE.background),
+    },
+    {
+        id: EDGY_ROLE.facets,
+        parent: EDGY_ROLE.background,
+        kind: 'node',
+        labelKey: roleKey(EDGY_ROLE.facets),
+    },
+    {
+        id: EDGY_ROLE.board,
+        parent: EDGY_ROLE.background,
+        kind: 'node',
+        labelKey: roleKey(EDGY_ROLE.board),
+    },
+];
+/**
+ * The relations: the parent, then one child per canonical verb.
+ *
+ * The parent carries no `direction` — it names no verb, so it has no sentence
+ * to state. Every child does, and the gesture hint is derived from the verb for
+ * the same reason the id is: "drag from the X to the Y" is the same sentence
+ * with the same two holes for all 22 of them, and writing it out 22 times would
+ * be 22 chances to write it out wrong.
+ */
+const RELATION_DEFS = [
+    {
+        id: EDGY_ROLE.relation,
+        kind: 'edge',
+        labelKey: roleKey(EDGY_ROLE.relation),
+        labelFallback: 'Relation',
+    },
+    ...Object.entries(EDGY_VERB_ROLE).map(([verb, id]) => ({
+        id,
+        parent: EDGY_ROLE.relation,
+        kind: 'edge',
+        labelKey: roleKey(id),
+        labelFallback: verb.charAt(0).toUpperCase() + verb.slice(1),
+        direction: {
+            verbKey: `${roleKey(id)}.verb`,
+            verbFallback: verb,
+            gestureHintKey: `${roleKey(id)}.gesture`,
+            gestureHintFallback: `Drag from the element that is the subject of "${verb}" to its object.`,
+        },
+    })),
+];
+const DEFS = [
+    ...ELEMENT_DEFS,
+    ...BACKGROUND_DEFS,
+    ...RELATION_DEFS,
+];
+// Null prototype: this is a lookup table keyed by ids that may one day come
+// from host-supplied packs, so `defs['toString']` must not resolve.
+export const EDGY_ROLES = Object.assign(Object.create(null), Object.fromEntries(DEFS.map(def => [def.id, def])));

package/dist/rules.d.ts

@@ -0,0 +1,43 @@
+import type { EndpointTriplet, ValidationRule } from '@formicoidea/labre-core/blocks/surface';
+/**
+ * EDGY validation rules (WS1).
+ *
+ * DATA owned by the framework, versioned per rule: the engine
+ * (`@labre/affine-block-surface`) knows how to evaluate a FAMILY, never a
+ * concrete rule. Adding an EDGY rule is adding an entry to this array.
+ *
+ * Registered from the flag-gated `EdgyViewExtension`, so switching the EDGY
+ * flag off removes the rules with the rest of the tooling — boards already
+ * drawn keep rendering, they simply stop being checked (`docs/adr/0009`).
+ *
+ * ## Two rules, and the ones deliberately left out
+ *
+ * The PO arbitration of 26/08/2026 put EDGY's two JUDGEMENT controls — "every
+ * intersection element is linked to both its parent facets" and "every element
+ * wears its facet's colour" — in `./nudges.ts` rather than here. Neither is
+ * decidable: the first would have to guess which circle an element belongs to
+ * from where somebody dropped it, and the second would indict a board whose
+ * author uses their own palette. A checklist can ask them; an algorithm cannot
+ * answer them.
+ *
+ * ## Debt: `tree-mixed-kinds`
+ *
+ * EDGY's own notation has TREES — a capability tree, an organisation tree —
+ * whose levels must all be the same kind of element. There is no tree on this
+ * canvas yet: nothing draws one, nothing stores one, and no role names one. The
+ * rule is therefore deferred rather than written against an artefact that does
+ * not exist. When a tree lands, it comes with its own role and this is where its
+ * rule goes.
+ */
+/**
+ * The 24 sanctioned sentences, DERIVED from the metamodel.
+ *
+ * One triplet per row of `EDGY_DYNAMIC_RELATIONS`, read exactly as
+ * `docs/adr/0010` reads a typed edge: source is the subject, target the object.
+ * The matrix is never restated — a relation added to the metamodel is drawn by
+ * the template, gets a role from `roles.ts` and becomes legal here, all from the
+ * one table. `requires` contributes three triplets under one role, which is what
+ * it means for a verb to be spoken of three different pairs.
+ */
+export declare const EDGY_ALLOWED_RELATIONS: readonly EndpointTriplet[];
+export declare const EDGY_RULES: readonly ValidationRule[];

package/dist/rules.js

@@ -0,0 +1,153 @@
+import { EDGY_DYNAMIC_RELATIONS } from './metamodel.js';
+import { EDGY_ROLE, EDGY_ROLES, EDGY_VERB_ROLE, } from './roles.js';
+/**
+ * EDGY validation rules (WS1).
+ *
+ * DATA owned by the framework, versioned per rule: the engine
+ * (`@labre/affine-block-surface`) knows how to evaluate a FAMILY, never a
+ * concrete rule. Adding an EDGY rule is adding an entry to this array.
+ *
+ * Registered from the flag-gated `EdgyViewExtension`, so switching the EDGY
+ * flag off removes the rules with the rest of the tooling — boards already
+ * drawn keep rendering, they simply stop being checked (`docs/adr/0009`).
+ *
+ * ## Two rules, and the ones deliberately left out
+ *
+ * The PO arbitration of 26/08/2026 put EDGY's two JUDGEMENT controls — "every
+ * intersection element is linked to both its parent facets" and "every element
+ * wears its facet's colour" — in `./nudges.ts` rather than here. Neither is
+ * decidable: the first would have to guess which circle an element belongs to
+ * from where somebody dropped it, and the second would indict a board whose
+ * author uses their own palette. A checklist can ask them; an algorithm cannot
+ * answer them.
+ *
+ * ## Debt: `tree-mixed-kinds`
+ *
+ * EDGY's own notation has TREES — a capability tree, an organisation tree —
+ * whose levels must all be the same kind of element. There is no tree on this
+ * canvas yet: nothing draws one, nothing stores one, and no role names one. The
+ * rule is therefore deferred rather than written against an artefact that does
+ * not exist. When a tree lands, it comes with its own role and this is where its
+ * rule goes.
+ */
+/**
+ * The 24 sanctioned sentences, DERIVED from the metamodel.
+ *
+ * One triplet per row of `EDGY_DYNAMIC_RELATIONS`, read exactly as
+ * `docs/adr/0010` reads a typed edge: source is the subject, target the object.
+ * The matrix is never restated — a relation added to the metamodel is drawn by
+ * the template, gets a role from `roles.ts` and becomes legal here, all from the
+ * one table. `requires` contributes three triplets under one role, which is what
+ * it means for a verb to be spoken of three different pairs.
+ */
+export const EDGY_ALLOWED_RELATIONS = EDGY_DYNAMIC_RELATIONS.map(([source, target, verb]) => ({
+    source: EDGY_ROLE[source],
+    edge: EDGY_VERB_ROLE[verb],
+    target: EDGY_ROLE[target],
+}));
+/**
+ * **E1** — a relation says something the EDGY metamodel does not.
+ *
+ * EDGY is a language before it is a diagram: its 24 relations are the sentences
+ * the method sanctions, and a link drawn between the wrong two elements — or
+ * drawn the right way round between the right two but carrying the wrong verb —
+ * is a modelling mistake no amount of dragging fixes. "A journey traverses a
+ * channel" is EDGY; "a channel traverses a journey" is a sentence nobody can
+ * act on.
+ *
+ * ## What stays silent
+ *
+ * Everything the `relation-endpoints` family already keeps quiet about, and one
+ * of them matters more here than anywhere: **a plain connector carries no role
+ * and is never judged**. Free links are how an EDGY workshop actually runs —
+ * somebody draws an arrow to say "these two have something to do with each
+ * other" and names it later — and the day the tool starts indicting that
+ * gesture is the day it gets switched off. Only the typed relations the toolbox
+ * and the templates stamp are read, and only when BOTH ends are official
+ * elements: a relation onto a bare sticky, onto a People node or onto an
+ * element of another framework is outside the alphabet, hence outside the
+ * conversation.
+ *
+ * Severity `warning` and not `blocking-overridable`: nothing in this library
+ * refuses a gesture, so declaring the blocking level would be data claiming an
+ * effect that does not exist (the note `wardley/rules.ts` carries at length).
+ * The profiles demote it to `audit` on a sketch.
+ */
+const nonCanonicalLink = {
+    id: 'edgy.non-canonical-link',
+    framework: 'edgy',
+    family: 'relation-endpoints',
+    severity: 'warning',
+    // No `appliesTo`: the subject is a RELATION, and the role that names it is
+    // declared where the family reads it — naming one of the three indicted
+    // elements here would be data that lies.
+    roles: EDGY_ROLES,
+    messageKey: 'com.labre.edgy.validation.non-canonical-link',
+    messageFallback: 'This relation is not one the EDGY metamodel declares between these two elements.',
+    suggestionKey: 'com.labre.edgy.validation.non-canonical-link.suggestion',
+    suggestionFallback: 'Read the link out loud — source, verb, target. Reverse it, re-point an end, or use the verb EDGY gives these two elements.',
+    version: 1,
+    provenance: {
+        source: 'recommendation',
+        reference: 'EDGY (Enterprise Design) — the 24 relations its metamodel sanctions',
+    },
+    // Not a frame the rule measures against — a sentence is right or wrong
+    // wherever it is written — but the facets diagram or board a finding is
+    // ATTRIBUTED to, so the arbitration "ignore this rule on the whole board" has
+    // somewhere to live (the `no-overlap` pattern).
+    backgroundRole: EDGY_ROLE.background,
+    endpoints: {
+        // The PARENT role: every verb specialises it, so the rule reads all 22 of
+        // them and no free connector.
+        edgeRole: EDGY_ROLE.relation,
+        allowed: EDGY_ALLOWED_RELATIONS,
+    },
+};
+/**
+ * **E2** — two artefacts must not sit on top of each other.
+ *
+ * A readability rule, the same one Wardley ships and for the same reason: a
+ * board you cannot read is useless, while a momentary overlap during a drag is
+ * not a mistake. It matters more on an EDGY facets diagram than almost
+ * anywhere, because WHERE an element sits is what says which facet it belongs
+ * to: an artefact hidden under another has lost its meaning, not just its
+ * legibility.
+ *
+ * ONE declared pair, `element × element`, because `roleIsA` covers the whole
+ * subtree — the four kinds and the twelve official elements — from the root.
+ * Backgrounds are outside that subtree by construction, so an element sitting on
+ * the diagram it belongs to is never a collision.
+ *
+ * `minPenetration: 4` model units, the calibration Wardley's W3 arrived at on
+ * the recette of 01/08/2026: under a twentieth of an EDGY node's 80-unit height
+ * and about twice a connector's stroke, so two boxes whose corners share a hair
+ * are silent while a box genuinely covering another is not. Verified against
+ * every layout this package ships: the twelve nodes of the EDGY dynamic
+ * template — the only stamped layout, hence the only one this rule can see —
+ * clear each other by 80 model units at the closest, twenty times the
+ * threshold.
+ */
+const overlappingArtefacts = {
+    id: 'edgy.overlapping-artefacts',
+    framework: 'edgy',
+    family: 'no-overlap',
+    severity: 'warning',
+    // No `appliesTo`: the subjects of a `no-overlap` rule are the pairs below.
+    roles: EDGY_ROLES,
+    messageKey: 'com.labre.edgy.validation.overlapping-artefacts',
+    messageFallback: 'These two overlap and make the board harder to read.',
+    suggestionKey: 'com.labre.edgy.validation.overlapping-artefacts.suggestion',
+    suggestionFallback: 'Move one of them aside — on a facets diagram, where an element sits is what says which facet it belongs to.',
+    version: 1,
+    provenance: {
+        source: 'labre-convention',
+        reference: 'Labre readability convention — no EDGY rule speaks of overlapping ink',
+    },
+    backgroundRole: EDGY_ROLE.background,
+    overlap: [[EDGY_ROLE.element, EDGY_ROLE.element]],
+    minPenetration: 4,
+};
+export const EDGY_RULES = [
+    nonCanonicalLink,
+    overlappingArtefacts,
+];

package/dist/templates/index.d.ts

@@ -6,20 +6,12 @@ import { type Template, type TemplateCategory } from '@formicoidea/labre-core/gf
  */
 export declare const DYN_SCALE = 4.8;
 /**
- * The 24 canonical EDGY relations (source, target, verb, label position along
- * the link) — exported for the unit tests. 7 per facet + 3 between the
- * intersections. The optional 4th member mirrors the reference diagram's
- * placements: verbs of intersection-outgoing links sit near the far element
- * (`labelOffset.distance` ≈ .75), short peer links keep the middle.
+ * The metamodel itself — the 12 elements and the 24 relations — now lives in
+ * `../metamodel.ts`, so the role vocabulary can DERIVE from it without this
+ * module and that one importing each other. Re-exported here under the names
+ * they have always had: nothing that reads them had to change.
  */
-export declare const EDGY_DYNAMIC_RELATIONS: [string, string, string, number?][];
-export declare const EDGY_DYNAMIC_NODES: Record<string, {
-    kind: 'outcome' | 'object' | 'activity';
-    cx: number;
-    cy: number;
-    w?: number;
-    fill: string;
-}>;
+export { EDGY_DYNAMIC_NODES, EDGY_DYNAMIC_RELATIONS, type EdgyElementName, } from '../metamodel.js';
 /**
  * Reference coords → template model coords: the background element sits at
  * (0,0) and renders the cropped circles box, so a reference point maps to