@formicoidea/labre-core 0.36.0 → 0.37.0

package/dist/_pkgs/affine-block-surface/extensions/reading-toolbar.js

@@ -58,18 +58,18 @@ const READ_LABEL_FALLBACK = 'Read this component';
  * Drawn inline like its neighbours: this package does not depend on
  * `@blocksuite/icons` and one glyph is not worth a new dependency.
  */
-const ReadIcon = html `<svg
-  width="20"
-  height="20"
-  viewBox="0 0 24 24"
-  fill="none"
-  stroke="currentColor"
-  stroke-width="2"
-  stroke-linecap="round"
-  stroke-linejoin="round"
->
-  <path d="M2 12s3.5-6 10-6 10 6 10 6-3.5 6-10 6-10-6-10-6z" />
-  <circle cx="12" cy="12" r="3" />
+const ReadIcon = html `<svg
+  width="20"
+  height="20"
+  viewBox="0 0 24 24"
+  fill="none"
+  stroke="currentColor"
+  stroke-width="2"
+  stroke-linecap="round"
+  stroke-linejoin="round"
+>
+  <path d="M2 12s3.5-6 10-6 10 6 10 6-3.5 6-10 6-10-6-10-6z" />
+  <circle cx="12" cy="12" r="3" />
 </svg>`;
 /** The command this module drives. Spelled once. */
 const ELEMENT_READ_ID = 'element.read';

package/dist/_pkgs/affine-block-surface/extensions/reading-widget.d.ts

@@ -1,19 +1,6 @@
 import { nothing, type TemplateResult } from 'lit';
 import { EditorAnchoredPanel } from './editor-anchored-panel.js';
 export declare const READING_PROPOSAL_WIDGET = "affine-reading-proposal-widget";
-/**
- * How the panel names each side of a parent-child relation, keyed under
- * `com.labre.reading.relations.`. Chrome, and only chrome.
- *
- * Exported because it is DATA: the translation-key manifest walks it rather
- * than restating the two wordings, which a source scan could not check — the
- * key is built as a template literal and the fallback reaches `translateKey`
- * through a local helper.
- */
-export declare const RELATION_SIDE_FALLBACK: {
-    readonly consumers: "Consumers (above)";
-    readonly suppliers: "Suppliers (below)";
-};
 /**
  * **The proposal panel** — what the tool reads of one component, offered for
  * confirmation (MF3).
@@ -94,6 +81,14 @@ export declare class ReadingProposalWidget extends EditorAnchoredPanel {
      * host's word into the document.
      */
     private _renderNature;
+    /**
+     * The typed edges touching the subject, grouped by side and named with the
+     * FRAMEWORK's own two words (`ReadingRelationDef.sides`).
+     *
+     * The `data-testid` keeps the shape it shipped with — `reading-consumers`,
+     * `reading-suppliers` — because it names the SIDE, which is generic, and not
+     * the wording, which is now the framework's.
+     */
     private _renderRelations;
     /**
      * **Value flow** — the same typed edges as the relations above, said the way
@@ -110,8 +105,25 @@ export declare class ReadingProposalWidget extends EditorAnchoredPanel {
      * "Value flows up from X to Y"; a host that translates
      * `com.labre.reading.value-flow` gets the same two slots in its own order via
      * the `.to` suffix key.
+     *
+     * ## Why it is gated on the framework's `geometry`
+     *
+     * "Up" is a claim about the board, not about the edge: it is only true where
+     * the framework said the vertical axis carries the order
+     * (`ReadingRelationDef.geometry`). Wardley says it, and this section is the
+     * value chain read from the bottom. Nobody else does, and "value flows up
+     * from Receive order to Check stock" would be a sentence BPMN never said.
      */
     private _renderValueFlow;
+    /**
+     * Where the subject sits along the frame's phase axis.
+     *
+     * Absent ENTIRELY — not "no phase to read" — for a framework that declares no
+     * frame. The empty state below is about a component that could have been on a
+     * map and is not; telling the author of a BPMN task that it is "not on a
+     * framework background" would be answering a question their notation never
+     * asks.
+     */
     private _renderPhase;
     private _renderNaming;
     /**

package/dist/_pkgs/affine-block-surface/extensions/reading-widget.js

@@ -46,18 +46,16 @@ export const READING_PROPOSAL_WIDGET = 'affine-reading-proposal-widget';
 const TAG_SET_ID = 'tag.set';
 const PIVOT_BIND_ID = 'pivot.bind';
 /**
- * How the panel names each side of a parent-child relation, keyed under
- * `com.labre.reading.relations.`. Chrome, and only chrome.
+ * The two sides of a relation, in the order the panel lists them: what needs
+ * the subject first, then what the subject needs.
  *
- * Exported because it is DATA: the translation-key manifest walks it rather
- * than restating the two wordings, which a source scan could not check — the
- * key is built as a template literal and the fallback reaches `translateKey`
- * through a local helper.
+ * The WORDINGS are no longer here. They used to be a chrome table
+ * (`Consumers (above)` / `Suppliers (below)`), which was Wardley's sentence
+ * written into the engine — a BPMN sequence flow has no "above". Each framework
+ * now names its own two sides on its {@link ReadingProfile}, Wardley included,
+ * and restates those very keys and wordings so nothing on a Wardley map moved.
  */
-export const RELATION_SIDE_FALLBACK = {
-    consumers: 'Consumers (above)',
-    suppliers: 'Suppliers (below)',
-};
+const RELATION_SIDES = ['consumer', 'supplier'];
 /**
  * **The proposal panel** — what the tool reads of one component, offered for
  * confirmation (MF3).
@@ -411,24 +409,38 @@ let ReadingProposalWidget = (() => {
           </div>`
                 : nothing}`);
         }
-        _renderRelations(reading) {
-            const consumers = reading.relations.filter(r => r.side === 'consumer');
-            const suppliers = reading.relations.filter(r => r.side === 'supplier');
-            const line = (relations, key) => relations.length
-                ? html `<div class="reading-value" data-testid=${`reading-${key}`}>
-            ${translateKey(this.std, `com.labre.reading.relations.${key}`, RELATION_SIDE_FALLBACK[key])}:
-            ${relations
+        /**
+         * The typed edges touching the subject, grouped by side and named with the
+         * FRAMEWORK's own two words (`ReadingRelationDef.sides`).
+         *
+         * The `data-testid` keeps the shape it shipped with — `reading-consumers`,
+         * `reading-suppliers` — because it names the SIDE, which is generic, and not
+         * the wording, which is now the framework's.
+         */
+        _renderRelations(reading, profile) {
+            const sides = profile.relation?.sides;
+            const line = (side) => {
+                const relations = reading.relations.filter(r => r.side === side);
+                const wording = sides?.[side];
+                // No wording means the framework declared no relation at all, in which
+                // case there is nothing to list either. Silence rather than a heading
+                // this library would have had to invent.
+                if (!relations.length || !wording)
+                    return nothing;
+                return html `<div class="reading-value" data-testid=${`reading-${side}s`}>
+        ${translateKey(this.std, wording.labelKey, wording.labelFallback)}:
+        ${relations
                     .map(relation => relation.otherName || relation.otherId)
                     .join(', ')}
-          </div>`
-                : nothing;
+      </div>`;
+            };
             const contradictions = reading.relations.filter(r => r.contradictsGeometry);
             return this._field('reading-relations', translateKey(this.std, 'com.labre.reading.field.relations', 'Parent-child relations'), html `${reading.relations.length === 0
                 ? html `<div class="reading-empty">
             ${translateKey(this.std, 'com.labre.reading.relations.none', 'No typed link touches this component.')}
           </div>`
                 : nothing}
-      ${line(consumers, 'consumers')} ${line(suppliers, 'suppliers')}
+      ${RELATION_SIDES.map(line)}
       ${contradictions.length
                 ? html `<div class="reading-note" data-testid="reading-contradiction">
             ${translateKey(this.std, 'com.labre.reading.relations.contradiction', 'A link states the opposite of what the positions show')}:
@@ -453,8 +465,18 @@ let ReadingProposalWidget = (() => {
          * "Value flows up from X to Y"; a host that translates
          * `com.labre.reading.value-flow` gets the same two slots in its own order via
          * the `.to` suffix key.
+         *
+         * ## Why it is gated on the framework's `geometry`
+         *
+         * "Up" is a claim about the board, not about the edge: it is only true where
+         * the framework said the vertical axis carries the order
+         * (`ReadingRelationDef.geometry`). Wardley says it, and this section is the
+         * value chain read from the bottom. Nobody else does, and "value flows up
+         * from Receive order to Check stock" would be a sentence BPMN never said.
          */
-        _renderValueFlow(reading) {
+        _renderValueFlow(reading, profile) {
+            if (profile.relation?.geometry !== 'vertical')
+                return nothing;
             const flows = readValueFlows(reading);
             if (flows.length === 0)
                 return nothing;
@@ -468,7 +490,18 @@ let ReadingProposalWidget = (() => {
             ${from} ${flow.from} ${to} ${flow.to}
           </div>`)}`);
         }
-        _renderPhase(reading) {
+        /**
+         * Where the subject sits along the frame's phase axis.
+         *
+         * Absent ENTIRELY — not "no phase to read" — for a framework that declares no
+         * frame. The empty state below is about a component that could have been on a
+         * map and is not; telling the author of a BPMN task that it is "not on a
+         * framework background" would be answering a question their notation never
+         * asks.
+         */
+        _renderPhase(reading, profile) {
+            if (!profile.frame)
+                return nothing;
             const { phase } = reading;
             return this._field('reading-phase', translateKey(this.std, 'com.labre.reading.field.phase', 'Evolution phase'), phase
                 ? html `<div class="reading-value" data-zone-id=${phase.zoneId}>
@@ -600,8 +633,9 @@ let ReadingProposalWidget = (() => {
         ${translateKey(this.std, 'com.labre.reading.panel.title', 'What this map says about this component')}
       </div>`, html `${this._renderNodeType(reading, profile)}
       ${this._renderNature(reading, profile, record, writable)}
-      ${this._renderRelations(reading)} ${this._renderValueFlow(reading)}
-      ${this._renderPhase(reading)} ${this._renderNaming(reading)}
+      ${this._renderRelations(reading, profile)}
+      ${this._renderValueFlow(reading, profile)}
+      ${this._renderPhase(reading, profile)} ${this._renderNaming(reading)}
       ${this._renderRecord(reading, writable)}
       ${writable ? this._renderDrift(reading) : nothing}`);
         }

package/dist/_pkgs/affine-block-surface/extensions/reading.d.ts

@@ -80,6 +80,53 @@ export interface ReadingNamingConvention {
     /** English default, for a host that ships no catalogue. */
     hintFallback: string;
 }
+/**
+ * How a framework names ONE end of its typed relation, in the panel.
+ *
+ * Key plus the framework's own wording, exactly like a role's label or a rule's
+ * message: the host localises it, and a host with no catalogue still reads a
+ * real phrase.
+ */
+export interface ReadingRelationSideLabel {
+    labelKey: string;
+    /** The framework's own English wording, for a host that ships no catalogue. */
+    labelFallback: string;
+}
+/**
+ * The typed edge a reading walks, and the two words the framework reads it
+ * with.
+ *
+ * The wordings live HERE rather than in the panel because they are the
+ * framework's own sentence and nobody else's: "Consumers (above)" is a Wardley
+ * value chain, "Followed by" is a BPMN sequence, "Upstream" is a context map.
+ * The panel used to hard-code the first pair, which is exactly what made the
+ * reading a Wardley feature wearing a generic coat.
+ */
+export interface ReadingRelationDef {
+    edgeRole: RoleId;
+    /**
+     * One wording per side, keyed by what the OTHER end is to the subject — the
+     * same convention {@link ReadingRelation.side} carries. `supplier` labels the
+     * edges LEAVING the subject (the subject is the `source`, i.e. the subject of
+     * the role's verb), `consumer` the edges arriving at it.
+     */
+    sides: Record<ReadingRelationSide, ReadingRelationSideLabel>;
+    /**
+     * The framework claims its board has a VERTICAL reading — that the axis the
+     * elements are drawn along IS the statement of order, so a link and the two
+     * positions can contradict each other.
+     *
+     * Opt-in, and only Wardley opts in: on a value chain a consumer is drawn
+     * above what it needs (ADR 0010 § 5), so an edge pointing the other way is a
+     * disagreement worth reporting. On a BPMN pool, a context map or a storming
+     * roll, "above" means nothing — two tasks side by side are not in conflict —
+     * and a contradiction note there would be a complaint about a drawing that is
+     * perfectly correct. Absent, {@link ReadingRelation.contradictsGeometry} is
+     * always `false`, and the panel also drops the VALUE FLOW section: "value
+     * flows up from X to Y" is the same vertical claim said the other way round.
+     */
+    geometry?: 'vertical';
+}
 /**
  * One framework's reading contract. Every section is optional: a framework that
  * declares only `appliesTo` gets the node-type line and nothing else, which is
@@ -109,9 +156,7 @@ export interface ReadingProfile {
         conventions: readonly ReadingNamingConvention[];
     };
     /** The typed edge whose two ends the relation reading walks. */
-    relation?: {
-        edgeRole: RoleId;
-    };
+    relation?: ReadingRelationDef;
     /** The frame the phase is read from. */
     frame?: {
         backgroundRole: RoleId;
@@ -159,6 +204,10 @@ export interface ReadingRelation {
      * says one thing and the two positions say the other, the reading says so
      * rather than picking a winner: that is W4 seen from the record's side, and
      * the user is the one who decides which of the two was the mistake.
+     *
+     * Always `false` unless the framework declared
+     * {@link ReadingRelationDef.geometry} — a board whose axis carries no order
+     * has nothing to contradict.
      */
     contradictsGeometry: boolean;
 }
@@ -279,6 +328,15 @@ export interface ReadingValueFlow {
 export declare function readValueFlows(reading: ElementReading): ReadingValueFlow[];
 /** The profile governing an element, or `null` — the first match wins. */
 export declare function readingProfileFor(element: GfxPrimitiveElementModel, profiles: readonly ReadingProfile[]): ReadingProfile | null;
+/**
+ * How the engine asks the HOST for a wording — `translateKey`, curried with the
+ * `std` its caller owns.
+ *
+ * A function rather than a scope, so every comparison below stays a pure
+ * function of its arguments and one caller ({@link ReadingManager}) owns the
+ * single `std` read.
+ */
+export type ReadingTranslate = (key: string, fallback: string) => string;
 /**
  * What the LINKED RECORD says about the two fields a reading can compare
  * itself against. Bounded by construction: the profile names at most two host
@@ -341,6 +399,16 @@ export interface ResolvedRecordNature {
  *   its words would be inventing it;
  * - **`values: 'open'`** — the def says any string is a value of this tag, so
  *   everything resolves. That is the def's own claim, not ours.
+ *
+ * ## Why there is no `translate` here, unlike {@link compareReading}
+ *
+ * There is nothing to translate. `TagValueDef.label` is documented as "already
+ * localized by the host" (ADR 0007): a pack is SEEDED with the wording of the
+ * deployment that seeded it, so the label this resolver already matches against
+ * IS the localized one. Adding a resolver would be a parameter that could never
+ * change an answer. The zone labels are the opposite case — they are declared
+ * in the library, in English, with an i18n key beside them — which is why the
+ * phase comparison takes one.
  */
 export declare function resolveRecordNature(def: TagDef | undefined, values: readonly string[]): ResolvedRecordNature;
 /** One field on which the drawing and the record disagree. */
@@ -389,11 +457,19 @@ export declare function readRecord(std: BlockStdScope, element: GfxPrimitiveElem
  * side. `readRecord` has already resolved what CAN be compared; what could not
  * is not a difference of opinion, it is a difference of alphabet.
  *
- * The phase comparison accepts either the zone id or the zone's own wording,
- * because a host is free to store "Product" where the declaration says
- * `product`, and neither spelling is more correct than the other.
+ * The phase comparison accepts the zone id, the zone's own English wording, and
+ * — when a `translate` is handed in — the wording the HOST's catalogue gives
+ * that zone. A French deployment stores "Produit" in its record and reads
+ * `product` off the board; without the third spelling the panel would report a
+ * permanent, false disagreement on a component nobody had moved. Same shape as
+ * the value-id resolution above: a difference of alphabet is not a difference
+ * of opinion.
+ *
+ * `translate` is a PARAMETER rather than a `std` read, so this stays a pure
+ * function of its arguments; {@link ReadingManager} owns the single `std` the
+ * closure is built from.
  */
-export declare function compareReading(reading: ElementReading, record: RecordReading): ReadingDriftField[];
+export declare function compareReading(reading: ElementReading, record: RecordReading, translate?: ReadingTranslate): ReadingDriftField[];
 /** A framework registers its reading profile here; nothing else registers one. */
 export declare const ReadingProfileIdentifier: import("../../global/di/types.js").ServiceIdentifier<ReadingProfile> & (<U extends ReadingProfile = ReadingProfile>(variant: import("../../global/di/types.js").ServiceVariant) => import("../../global/di/types.js").ServiceIdentifier<U>);
 /**

package/dist/_pkgs/affine-block-surface/extensions/reading.js

@@ -1,4 +1,4 @@
-import { getUniverseRegistry, hostLanguage, queryPivotProperties, } from '../../affine-shared/services/index.js';
+import { getUniverseRegistry, hostLanguage, queryPivotProperties, translateKey, } from '../../affine-shared/services/index.js';
 import { createIdentifier } from '../../global/di/index.js';
 import { LifeCycleWatcher, } from '../../std/index.js';
 import { GfxControllerIdentifier, GfxPrimitiveElementModel, readElementTags, resolvePivotBinding, roleIsA, } from '../../std/gfx/index.js';
@@ -270,10 +270,14 @@ function readRelations(element, elements, profile) {
         const side = isSource ? 'supplier' : 'consumer';
         const [, otherY] = centreOf(other.elementBound);
         // `y` grows downwards, so "higher on the map" is a SMALLER y. A supplier is
-        // expected below the subject, a consumer above it.
-        const contradictsGeometry = side === 'supplier'
-            ? otherY < subjectY - GEOMETRY_EPSILON
-            : otherY > subjectY + GEOMETRY_EPSILON;
+        // expected below the subject, a consumer above it — but only on a board
+        // whose framework CLAIMED that axis says something (`geometry`). Two BPMN
+        // tasks side by side contradict nothing.
+        const contradictsGeometry = relation.geometry !== 'vertical'
+            ? false
+            : side === 'supplier'
+                ? otherY < subjectY - GEOMETRY_EPSILON
+                : otherY > subjectY + GEOMETRY_EPSILON;
         relations.push({
             edgeId: edge.id,
             otherId,
@@ -399,6 +403,16 @@ export function readingProfileFor(element, profiles) {
  *   its words would be inventing it;
  * - **`values: 'open'`** — the def says any string is a value of this tag, so
  *   everything resolves. That is the def's own claim, not ours.
+ *
+ * ## Why there is no `translate` here, unlike {@link compareReading}
+ *
+ * There is nothing to translate. `TagValueDef.label` is documented as "already
+ * localized by the host" (ADR 0007): a pack is SEEDED with the wording of the
+ * deployment that seeded it, so the label this resolver already matches against
+ * IS the localized one. Adding a resolver would be a parameter that could never
+ * change an answer. The zone labels are the opposite case — they are declared
+ * in the library, in English, with an i18n key beside them — which is why the
+ * phase comparison takes one.
  */
 export function resolveRecordNature(def, values) {
     const resolved = [];
@@ -512,11 +526,19 @@ export function readRecord(std, element, profile) {
  * side. `readRecord` has already resolved what CAN be compared; what could not
  * is not a difference of opinion, it is a difference of alphabet.
  *
- * The phase comparison accepts either the zone id or the zone's own wording,
- * because a host is free to store "Product" where the declaration says
- * `product`, and neither spelling is more correct than the other.
+ * The phase comparison accepts the zone id, the zone's own English wording, and
+ * — when a `translate` is handed in — the wording the HOST's catalogue gives
+ * that zone. A French deployment stores "Produit" in its record and reads
+ * `product` off the board; without the third spelling the panel would report a
+ * permanent, false disagreement on a component nobody had moved. Same shape as
+ * the value-id resolution above: a difference of alphabet is not a difference
+ * of opinion.
+ *
+ * `translate` is a PARAMETER rather than a `std` read, so this stays a pure
+ * function of its arguments; {@link ReadingManager} owns the single `std` the
+ * closure is built from.
  */
-export function compareReading(reading, record) {
+export function compareReading(reading, record, translate) {
     const fields = [];
     const recorded = record.nature ?? [];
     if (recorded.length) {
@@ -532,10 +554,11 @@ export function compareReading(reading, record) {
         }
     }
     if (record.phase && reading.phase) {
-        const spellings = [
-            reading.phase.zoneId,
-            reading.phase.labelFallback ?? '',
-        ].map(value => value.toLowerCase());
+        const { zoneId, labelKey, labelFallback } = reading.phase;
+        const localized = translate && labelKey !== undefined
+            ? translate(labelKey, labelFallback ?? zoneId)
+            : '';
+        const spellings = [zoneId, labelFallback ?? '', localized].map(value => value.toLowerCase());
         if (!spellings.includes(record.phase.toLowerCase())) {
             fields.push({
                 field: 'phase',
@@ -763,7 +786,11 @@ export class ReadingManager extends LifeCycleWatcher {
                 this.drift$.value = null;
             return;
         }
-        const fields = compareReading(reading, record);
+        // The one `std` read the comparison needs, curried into a resolver so
+        // `compareReading` stays pure: a host serving French stores "Produit" in
+        // its record and would otherwise be told, for ever, that its board says
+        // `product` instead.
+        const fields = compareReading(reading, record, (key, fallback) => translateKey(this.std, key, fallback));
         if (fields.length === 0) {
             if (this.drift$.value?.elementId === elementId)
                 this.drift$.value = null;

package/dist/_pkgs/affine-components/highlight-dropdown-menu/highlight-duotone-icon.js

@@ -1,14 +1,14 @@
 import { HighLightDuotoneIcon } from '@blocksuite/icons/lit';
 import { css, LitElement } from 'lit';
 export class HighlightDuotoneIcon extends LitElement {
-    static { this.styles = css `
-    svg {
-      display: flex;
-      font-size: 20px;
-    }
-    svg > path:nth-child(1) {
-      fill: var(--color, unset);
-    }
+    static { this.styles = css `
+    svg {
+      display: flex;
+      font-size: 20px;
+    }
+    svg > path:nth-child(1) {
+      fill: var(--color, unset);
+    }
   `; }
     render() {
         return HighLightDuotoneIcon();

package/dist/_pkgs/affine-components/highlight-dropdown-menu/text-duotone-icon.js

@@ -1,17 +1,17 @@
 import { TextBackgroundDuotoneIcon } from '@blocksuite/icons/lit';
 import { css, LitElement } from 'lit';
 export class TextDuotoneIcon extends LitElement {
-    static { this.styles = css `
-    svg {
-      display: flex;
-      font-size: 20px;
-    }
-    svg > path:nth-child(1) {
-      fill: var(--background, unset);
-    }
-    svg > path:nth-child(3) {
-      fill: var(--color, unset);
-    }
+    static { this.styles = css `
+    svg {
+      display: flex;
+      font-size: 20px;
+    }
+    svg > path:nth-child(1) {
+      fill: var(--background, unset);
+    }
+    svg > path:nth-child(3) {
+      fill: var(--color, unset);
+    }
   `; }
     render() {
         return TextBackgroundDuotoneIcon();