@formicoidea/labre-framework-c4 0.36.0 → 0.37.0

package/dist/index.d.ts

@@ -14,3 +14,4 @@ export { C4_ELEMENT_MATRIX, C4_RELATIONSHIP_MATRIX, C4_RULES, } from './rules.js
 export { c4CommandIcons, c4Commands } from './commands.js';
 export { c4TranslationEntries } from './translations.js';
 export { C4_AUTO_LEGEND } from './legend.js';
+export { C4_COMPONENT_READING, C4_CONTAINER_READING, C4_PERSON_READING, C4_READINGS, C4_SYSTEM_READING, } from './reading.js';

package/dist/index.js

@@ -54,3 +54,4 @@ export { c4TranslationEntries } from './translations.js';
 // the same reason the two background declarations are: it answers "what does
 // this framework document about itself" without a canvas.
 export { C4_AUTO_LEGEND } from './legend.js';
+export { C4_COMPONENT_READING, C4_CONTAINER_READING, C4_PERSON_READING, C4_READINGS, C4_SYSTEM_READING, } from './reading.js';

package/dist/reading.d.ts

@@ -0,0 +1,8 @@
+import type { ReadingProfile } from '@formicoidea/labre-core/blocks/surface';
+export declare const C4_PERSON_READING: ReadingProfile;
+export declare const C4_SYSTEM_READING: ReadingProfile;
+/** Covers `c4:database`, the one specialisation in the pack. */
+export declare const C4_CONTAINER_READING: ReadingProfile;
+export declare const C4_COMPONENT_READING: ReadingProfile;
+/** Every C4 profile, in the order the view extension registers them. */
+export declare const C4_READINGS: readonly ReadingProfile[];

package/dist/reading.js

@@ -0,0 +1,85 @@
+import { C4_ROLE, C4_ROLES } from './roles.js';
+/**
+ * What a C4 diagram lets the tool read of an element (MF3, the reversed
+ * reading).
+ *
+ * DATA, like the rules and the profiles beside it: the engine
+ * (`@labre/affine-block-surface`) knows how to read a role and a typed edge — it
+ * knows nothing about C4. Everything below is already stated in `roles.ts` and
+ * is merely POINTED AT here.
+ *
+ * Registered from the FLAG-GATED view extension: reading a diagram is tooling,
+ * so a board whose C4 flag is off keeps every element it has and simply stops
+ * being read (ADR 0009).
+ *
+ * ## FOUR profiles, because the four levels are deliberately FLAT
+ *
+ * `roles.ts` argues it at length: the relation between the levels is
+ * COMPOSITION ("a container is part of a system"), not specialisation, and
+ * `roleIsA` means the second. Filing them in a chain to get one `appliesTo`
+ * would make "every rule about a system also falls on every container" true —
+ * the opposite of what C4 says — and minting a `c4:element` parent would be
+ * inventing an id the notation does not have (ADR 0007: an id is forever).
+ *
+ * So there is one profile per level, each with an id of its own (the DI keys on
+ * it and throws on a duplicate). `c4:database` needs none: it is the one real
+ * specialisation in the pack, a kind of container, and is read through the
+ * container's profile for free.
+ *
+ * The BOARD and the BOUNDARY (and its two children) are frames and are not read.
+ *
+ * ## The name lives on a separate element
+ *
+ * A C4 element is a composite — a shape, and three tiers of canvas text grouped
+ * with it — so every profile points `labelRole` at `c4:title`. Without it the
+ * panel would print an id at a human, and the relation lines would name the
+ * other end by id too.
+ *
+ * ## No nature, no phase
+ *
+ * C4 ships no type-3 tag pack: the levels ARE the roles, and the middle tier of
+ * the label (`c4:type-line`) already says the technology in the author's own
+ * words. And a board declares which of the three diagrams it draws, not a set of
+ * zones a position could be read against.
+ */
+/**
+ * The two words a relationship is read with, from the subject's end.
+ *
+ * ADR 0010 tier 1 and this role's own `direction`: the verb is "uses", so the
+ * SOURCE is the user. An edge leaving the subject names what it uses; one
+ * arriving names what uses it.
+ */
+const RELATIONSHIP = {
+    edgeRole: C4_ROLE.relationship,
+    sides: {
+        consumer: {
+            labelKey: 'com.labre.c4.reading.relations.consumer',
+            labelFallback: 'Used by',
+        },
+        supplier: {
+            labelKey: 'com.labre.c4.reading.relations.supplier',
+            labelFallback: 'Uses',
+        },
+    },
+};
+/** One level, as a profile. The four below differ by `id` and `appliesTo` only. */
+const level = (id, appliesTo) => ({
+    id,
+    framework: 'c4',
+    roles: C4_ROLES,
+    appliesTo,
+    labelRole: C4_ROLE.title,
+    relation: RELATIONSHIP,
+});
+export const C4_PERSON_READING = level('c4-person', C4_ROLE.person);
+export const C4_SYSTEM_READING = level('c4-system', C4_ROLE.system);
+/** Covers `c4:database`, the one specialisation in the pack. */
+export const C4_CONTAINER_READING = level('c4-container', C4_ROLE.container);
+export const C4_COMPONENT_READING = level('c4-component', C4_ROLE.component);
+/** Every C4 profile, in the order the view extension registers them. */
+export const C4_READINGS = [
+    C4_PERSON_READING,
+    C4_SYSTEM_READING,
+    C4_CONTAINER_READING,
+    C4_COMPONENT_READING,
+];

package/dist/translations.js

@@ -3,6 +3,7 @@ import { C4_BOARD_BACKGROUND, C4_BOUNDARY_BACKGROUND } from './background.js';
 import { c4Commands } from './commands.js';
 import { C4_BOARD_LEVEL_MENU } from './levels.js';
 import { C4_PROFILES } from './profiles.js';
+import { C4_READINGS } from './reading.js';
 import { C4_ROLES } from './roles.js';
 import { C4_RULES } from './rules.js';
 /**
@@ -45,4 +46,8 @@ commandCategoryTranslationEntries(c4Commands), collectTranslationKeys('role', C4
 // declaration, so walking the rules reaches keys those two lists already
 // named. `mergeTranslationEntries` keeps the FIRST occurrence, which is what
 // makes each key report the source it actually comes from.
-collectTranslationKeys('rule', C4_RULES), collectTranslationKeys('profile', C4_PROFILES));
+collectTranslationKeys('rule', C4_RULES), collectTranslationKeys('profile', C4_PROFILES), 
+// LAST, for the reason the rules are placed after the roles: a reading
+// profile carries the framework's own `roles` too, so walking it reaches
+// keys the lists above already named, and the first occurrence wins.
+collectTranslationKeys('reading', C4_READINGS));

package/dist/view.js

@@ -1,4 +1,4 @@
-import { FrameworkBackgroundInteractionExtension, InterchangeExtension, morphToolbarConfig, ValidationProfileExtension, ValidationRuleExtension, } from '@formicoidea/labre-core/blocks/surface';
+import { FrameworkBackgroundInteractionExtension, InterchangeExtension, morphToolbarConfig, ReadingProfileExtension, 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';
@@ -14,6 +14,7 @@ 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_READINGS } from './reading.js';
 import { C4_ROLES } from './roles.js';
 import { C4_RULES } from './rules.js';
 import { c4BoardToolbarExtension, c4BoardToolingToolbarExtension, } from './toolbar/config.js';
@@ -99,6 +100,14 @@ export class C4ViewExtension extends ViewExtensionProvider {
             // 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));
+            // The reversed reading (MF3): what the diagram says about an element, on
+            // demand. Four profiles because the four levels are deliberately FLAT —
+            // composition is not specialisation, and `reading.ts` says why a common
+            // parent would be a lie. The CLICK that triggers it is registered once by
+            // the surface and gated by the presence of a profile.
+            for (const reading of C4_READINGS) {
+                context.register(ReadingProfileExtension(reading));
+            }
             context.register(c4SeniorTool);
             context.register(CommandExtension(c4Commands, c4CommandIcons));
             // The flag-gated half of the selected BOARD's row, through the `custom:`

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@formicoidea/labre-framework-c4",
   "description": "Labre c4 framework for @formicoidea/labre-core.",
-  "version": "0.36.0",
+  "version": "0.37.0",
   "type": "module",
   "sideEffects": false,
   "author": "lajola",
@@ -31,8 +31,8 @@
     "dist"
   ],
   "dependencies": {
-    "@formicoidea/labre-core": "0.36.0",
-    "@formicoidea/labre-ddd-shared": "0.36.0",
+    "@formicoidea/labre-core": "0.37.0",
+    "@formicoidea/labre-ddd-shared": "0.37.0",
     "lit": "^3.2.0"
   }
 }