@formicoidea/labre-core 0.31.0 → 0.33.0

package/dist/_pkgs/affine-shared/services/toolbar-service/registry.d.ts

@@ -8,7 +8,19 @@ import type { ToolbarModule } from './module.js';
 export declare const ToolbarModuleIdentifier: import("../../../global/di/types.js").ServiceIdentifier<ToolbarModule> & (<U extends ToolbarModule = ToolbarModule>(variant: import("../../../global/di/types.js").ServiceVariant) => import("../../../global/di/types.js").ServiceIdentifier<U>);
 export declare const ToolbarRegistryIdentifier: import("../../../global/di/types.js").ServiceIdentifier<ToolbarRegistryExtension> & (<U extends ToolbarRegistryExtension = ToolbarRegistryExtension>(variant: import("../../../global/di/types.js").ServiceVariant) => import("../../../global/di/types.js").ServiceIdentifier<U>);
 export declare function ToolbarModuleExtension(module: ToolbarModule): ExtensionType;
+/** The flavour a DI variant speaks for, owner suffix and all. */
+export declare function toolbarModuleFlavour(variant: string): string;
+/**
+ * A second (or third) module on one flavour, named by who contributes it.
+ *
+ * The owner is never shown and never parsed back — it exists so two
+ * contributors cannot claim one DI variant. Use a stable, framework-scoped
+ * name (`c4-morph`), because it is the identity the container refuses
+ * duplicates on.
+ */
+export declare function toolbarModuleKey(flavour: string, owner: string): string;
 export declare class ToolbarRegistryExtension extends Extension {
+    #private;
     readonly std: BlockStdScope;
     flavour$: import("@preact/signals-core").Signal<string>;
     elementsMap$: import("@preact/signals-core").Signal<Map<string, GfxModel[]>>;
@@ -20,8 +32,40 @@ export declare class ToolbarRegistryExtension extends Extension {
     placement$: import("@preact/signals-core").Signal<ToolbarPlacement>;
     flags: Flags;
     constructor(std: BlockStdScope);
+    /**
+     * Every module of every flavour, keyed by the DI variant it was registered
+     * under — which for a shared flavour carries an owner suffix. Read
+     * {@link modulesFor} instead unless the variant itself is the question.
+     */
     get modules(): Map<string, ToolbarModule>;
+    /**
+     * Every module contributing to one flavour's row — the bare-key module
+     * first, then the owner-suffixed ones in registration order.
+     */
+    modulesFor(flavour: string): readonly ToolbarModule[];
+    /**
+     * The config registered under the flavour ITSELF, or `null`.
+     *
+     * Deliberately not "the first module of this flavour". The callers of this
+     * method ask a question about one identified registration — does this block
+     * flavour have a toolbar of its own, where does that toolbar sit — and an
+     * owner-suffixed contributor is an ADDITION to a row, not a stand-in for the
+     * module that defines it. Answering with a contributor would make the reply
+     * depend on which frameworks a host happened to switch on: with `wardley`
+     * off and `c4` on, `custom:affine:surface:group` has no bare module at all,
+     * and returning C4's morph there would let a placement (or a `has`-style
+     * probe) be decided by a menu that only some builds ship.
+     */
     getModuleBy(flavour: string): import("./config.js").ToolbarModuleConfig | null;
+    /**
+     * Where a flavour's row sits: the first module of it that actually SAYS.
+     *
+     * A row is one row however many modules contribute to it, so the placement
+     * is a property of the flavour and not of a registration — and a contributor
+     * that declares none must not be read as declaring the default. Scanning for
+     * the first module with a `placement` keeps the answer the same whether the
+     * framework that states it is registered first, last, or under an owner.
+     */
     getModulePlacement(flavour: string, fallback?: ToolbarPlacement): ToolbarPlacement;
     static setup(di: Container): void;
 }

package/dist/_pkgs/affine-shared/services/toolbar-service/registry.js

@@ -12,6 +12,61 @@ export function ToolbarModuleExtension(module) {
         },
     };
 }
+/**
+ * What separates a flavour from the OWNER of one of its modules.
+ *
+ * A module is registered under one DI variant, and until now that variant WAS
+ * the flavour — so a flavour held at most two modules, its own key and its
+ * `custom:` twin, and a third contributor got a `DuplicateServiceDefinitionError`
+ * at setup rather than a menu entry. That ceiling was invisible until two
+ * frameworks needed the same element: `affine:surface:group` carries the native
+ * group operations, `custom:affine:surface:group` carries Wardley's
+ * qualification dropdown, and a C4 component IS a group — so C4's morph had
+ * nowhere at all to be registered.
+ *
+ * {@link toolbarModuleKey} gives it one. `custom:affine:surface:group#c4-morph`
+ * is a DISTINCT DI variant and therefore never collides, while
+ * {@link ToolbarRegistryExtension.modulesFor} still hands it to the row drawn
+ * for `custom:affine:surface:group`. Nothing about the existing keys changes:
+ * a module registered under a bare flavour is that flavour's first module, and
+ * every registration in the library before this one stays exactly as it was.
+ */
+const MODULE_OWNER_SEPARATOR = '#';
+/** The flavour a DI variant speaks for, owner suffix and all. */
+export function toolbarModuleFlavour(variant) {
+    const at = variant.indexOf(MODULE_OWNER_SEPARATOR);
+    return at < 0 ? variant : variant.slice(0, at);
+}
+/**
+ * A second (or third) module on one flavour, named by who contributes it.
+ *
+ * The owner is never shown and never parsed back — it exists so two
+ * contributors cannot claim one DI variant. Use a stable, framework-scoped
+ * name (`c4-morph`), because it is the identity the container refuses
+ * duplicates on.
+ */
+export function toolbarModuleKey(flavour, owner) {
+    // Checked ALWAYS, and deliberately not behind a `process.env.NODE_ENV` dev
+    // guard. This library is published SOURCE-FIRST, so a `process` reference is
+    // not erased by anybody's build: a host consuming raw ESM would meet
+    // `ReferenceError: process is not defined` the moment a framework registered
+    // a shared toolbar module — i.e. at editor setup, on every document. The
+    // check costs one falsy test and one `includes` on a short string, run a
+    // handful of times per editor, which is nothing next to being the only
+    // `process` reference in the shipped source.
+    //
+    // What it prevents is silent: an empty owner produces `flavour#`, which is a
+    // DIFFERENT variant from `flavour` and would therefore register a second
+    // module the bare-key lookups below never see, and an owner carrying the
+    // separator makes `toolbarModuleFlavour` cut in the wrong place, filing the
+    // module under a flavour nobody draws.
+    if (!owner || owner.includes(MODULE_OWNER_SEPARATOR)) {
+        throw new Error(`toolbarModuleKey: owner must be non-empty and free of "${MODULE_OWNER_SEPARATOR}" (got ${JSON.stringify(owner)})`);
+    }
+    return `${flavour}${MODULE_OWNER_SEPARATOR}${owner}`;
+}
+/** One shared empty answer, so a miss allocates nothing and can be frozen. */
+const NO_MODULES = Object.freeze([]);
 export class ToolbarRegistryExtension extends Extension {
     constructor(std) {
         super();
@@ -21,18 +76,121 @@ export class ToolbarRegistryExtension extends Extension {
         this.message$ = signal(null);
         this.placement$ = signal('top');
         this.flags = new Flags();
+        /**
+         * The modules grouped by the FLAVOUR they speak for, computed once.
+         *
+         * Once, because the registrations are fixed for the life of a container —
+         * they are DI impls, added at setup and never afterwards — while
+         * {@link modulesFor} is asked six times per toolbar render, and a toolbar
+         * re-renders on every selection change, every drag frame and every zoom
+         * notch.
+         *
+         * A module registered under the BARE flavour leads its group, and the rest
+         * follow in registration order. The order is what decides nothing much —
+         * `renderToolbar` sorts the merged actions by `placement`, `id` and `score`
+         * — and it is pinned all the same, because "which module answers a bare-key
+         * question" must not depend on which framework happened to be registered
+         * first.
+         *
+         * Each group is FROZEN: it is handed out by {@link modulesFor} on every
+         * render, and a caller that sorted or spliced the answer in place would
+         * silently rewrite the registry for every later render.
+         */
+        this.#grouped = null;
     }
+    /**
+     * Every module of every flavour, keyed by the DI variant it was registered
+     * under — which for a shared flavour carries an owner suffix. Read
+     * {@link modulesFor} instead unless the variant itself is the question.
+     */
     get modules() {
         return this.std.provider.getAll(ToolbarModuleIdentifier);
     }
+    /**
+     * The modules grouped by the FLAVOUR they speak for, computed once.
+     *
+     * Once, because the registrations are fixed for the life of a container —
+     * they are DI impls, added at setup and never afterwards — while
+     * {@link modulesFor} is asked six times per toolbar render, and a toolbar
+     * re-renders on every selection change, every drag frame and every zoom
+     * notch.
+     *
+     * A module registered under the BARE flavour leads its group, and the rest
+     * follow in registration order. The order is what decides nothing much —
+     * `renderToolbar` sorts the merged actions by `placement`, `id` and `score`
+     * — and it is pinned all the same, because "which module answers a bare-key
+     * question" must not depend on which framework happened to be registered
+     * first.
+     *
+     * Each group is FROZEN: it is handed out by {@link modulesFor} on every
+     * render, and a caller that sorted or spliced the answer in place would
+     * silently rewrite the registry for every later render.
+     */
+    #grouped;
+    get #groups() {
+        if (!this.#grouped) {
+            const groups = new Map();
+            for (const [variant, module] of this.modules) {
+                const flavour = toolbarModuleFlavour(variant);
+                const group = groups.get(flavour);
+                if (!group)
+                    groups.set(flavour, [module]);
+                else if (variant === flavour)
+                    group.unshift(module);
+                else
+                    group.push(module);
+            }
+            for (const group of groups.values())
+                Object.freeze(group);
+            this.#grouped = groups;
+        }
+        return this.#grouped;
+    }
+    /**
+     * Every module contributing to one flavour's row — the bare-key module
+     * first, then the owner-suffixed ones in registration order.
+     */
+    modulesFor(flavour) {
+        return this.#groups.get(flavour) ?? NO_MODULES;
+    }
+    /**
+     * The config registered under the flavour ITSELF, or `null`.
+     *
+     * Deliberately not "the first module of this flavour". The callers of this
+     * method ask a question about one identified registration — does this block
+     * flavour have a toolbar of its own, where does that toolbar sit — and an
+     * owner-suffixed contributor is an ADDITION to a row, not a stand-in for the
+     * module that defines it. Answering with a contributor would make the reply
+     * depend on which frameworks a host happened to switch on: with `wardley`
+     * off and `c4` on, `custom:affine:surface:group` has no bare module at all,
+     * and returning C4's morph there would let a placement (or a `has`-style
+     * probe) be decided by a menu that only some builds ship.
+     */
     getModuleBy(flavour) {
-        return this.modules.get(flavour)?.config ?? null;
+        return (this.modulesFor(flavour).find(module => module.id.variant === flavour)
+            ?.config ?? null);
     }
+    /**
+     * Where a flavour's row sits: the first module of it that actually SAYS.
+     *
+     * A row is one row however many modules contribute to it, so the placement
+     * is a property of the flavour and not of a registration — and a contributor
+     * that declares none must not be read as declaring the default. Scanning for
+     * the first module with a `placement` keeps the answer the same whether the
+     * framework that states it is registered first, last, or under an owner.
+     */
     getModulePlacement(flavour, fallback = 'top') {
-        return (this.getModuleBy(`custom:${flavour}`)?.placement ??
-            this.getModuleBy(flavour)?.placement ??
+        return (this.#placementOf(`custom:${flavour}`) ??
+            this.#placementOf(flavour) ??
             fallback);
     }
+    #placementOf(flavour) {
+        for (const module of this.modulesFor(flavour)) {
+            if (module.config.placement)
+                return module.config.placement;
+        }
+        return undefined;
+    }
     static setup(di) {
         di.addImpl(ToolbarRegistryIdentifier, this, [StdIdentifier]);
     }

package/dist/_pkgs/affine-shared/services/translation-service/index.d.ts

@@ -0,0 +1,68 @@
+import type { BlockStdScope } from '../../../std/index.js';
+import type { ExtensionType } from '../../../store/index.js';
+/**
+ * The library holds no prose: every human-readable string it produces —
+ * shortcut labels, role names, validation messages — is an i18n KEY
+ * (`com.labre.wardley.validation.change-arrow-against-evolution`). Historically those
+ * keys never had to be rendered here: `getShortcutManifest` hands them to the
+ * host, which owns the catalogue and the settings panel.
+ *
+ * PF7 is the first library UI that has to SHOW one — a violation bubble names
+ * the rule it reports. This is the seam for it, and nothing more: the host
+ * injects a catalogue, the library asks it for a key. There is no bundled
+ * catalogue, no locale negotiation and no pluralisation. Those belong to the
+ * host, which already runs an i18n stack.
+ *
+ * Mirrors `TelemetryExtension` / `KeymapOverrideExtension`: an optional
+ * host-injected service, absent by default, with a graceful fallback at every
+ * call site (see {@link translateKey}).
+ *
+ * A host builds its catalogue from `getTranslationKeyManifest()`
+ * (`@labre/affine/translations`) — every key the library can ask for, with its
+ * English fallback — rather than chasing call sites. See `./README.md`.
+ */
+export interface TranslationService {
+    /**
+     * Resolve an i18n key. Return `undefined` when the catalogue has no entry,
+     * so the caller can fall back rather than render an empty bubble.
+     */
+    t(key: string): string | undefined;
+    /**
+     * The language the catalogue is currently serving, as a BCP-47 tag
+     * (`'fr'`, `'en-GB'`). Optional, and NOT locale negotiation — the library
+     * still holds no catalogue and still chooses nothing.
+     *
+     * It exists for the one kind of statement the library cannot make without
+     * knowing the language: a suggestion ABOUT WORDS. A naming convention is a
+     * motif in one language (see `ReadingNamingConvention.lang`), and applying an
+     * English motif to a board named in French produces a confident wrong answer
+     * in both directions. The host that owns the catalogue is the only thing here
+     * that knows which language the user is working in; a host that does not say
+     * gets silence rather than a guess.
+     */
+    language?: string;
+}
+/**
+ * The primary subtag of the host's language, lower-cased — `'fr'` for
+ * `'fr-CA'` — or `undefined` when no host said.
+ *
+ * Primary subtag only: a naming motif is a property of a LANGUAGE, and no
+ * framework has a convention that holds in `en-GB` and not in `en-US`.
+ */
+export declare function hostLanguage(std: BlockStdScope): string | undefined;
+export declare const TranslationProvider: import("../../../global/di/types.js").ServiceIdentifier<TranslationService> & (<U extends TranslationService = TranslationService>(variant: import("../../../global/di/types.js").ServiceVariant) => import("../../../global/di/types.js").ServiceIdentifier<U>);
+export declare const TranslationExtension: (service: TranslationService) => ExtensionType;
+/**
+ * Resolve `key`, falling back to `fallback` — which defaults to the key itself.
+ *
+ * Two deliberate cases:
+ *
+ * - **Framework prose** (a rule message, a role name) passes NO fallback. With
+ *   no catalogue registered the raw key is shown. It is ugly, and that is the
+ *   point: the library must never invent the wording of somebody else's rule,
+ *   and a dangling key is a bug the host has to see rather than a sentence we
+ *   made up.
+ * - **Chrome** (the word "Warning" on a severity chip) passes an English
+ *   default, so a standalone playground reads correctly without a catalogue.
+ */
+export declare function translateKey(std: BlockStdScope, key: string, fallback?: string): string;

package/dist/_pkgs/affine-shared/services/translation-service/index.js

@@ -0,0 +1,39 @@
+import { createIdentifier } from '../../../global/di/index.js';
+/**
+ * The primary subtag of the host's language, lower-cased — `'fr'` for
+ * `'fr-CA'` — or `undefined` when no host said.
+ *
+ * Primary subtag only: a naming motif is a property of a LANGUAGE, and no
+ * framework has a convention that holds in `en-GB` and not in `en-US`.
+ */
+export function hostLanguage(std) {
+    const tag = std.getOptional(TranslationProvider)?.language;
+    if (typeof tag !== 'string' || tag.length === 0)
+        return undefined;
+    return tag.split('-')[0].toLowerCase();
+}
+export const TranslationProvider = createIdentifier('AffineTranslationService');
+export const TranslationExtension = (service) => {
+    return {
+        setup: di => {
+            di.override(TranslationProvider, () => service);
+        },
+    };
+};
+/**
+ * Resolve `key`, falling back to `fallback` — which defaults to the key itself.
+ *
+ * Two deliberate cases:
+ *
+ * - **Framework prose** (a rule message, a role name) passes NO fallback. With
+ *   no catalogue registered the raw key is shown. It is ugly, and that is the
+ *   point: the library must never invent the wording of somebody else's rule,
+ *   and a dangling key is a bug the host has to see rather than a sentence we
+ *   made up.
+ * - **Chrome** (the word "Warning" on a severity chip) passes an English
+ *   default, so a standalone playground reads correctly without a catalogue.
+ */
+export function translateKey(std, key, fallback = key) {
+    const resolved = std.getOptional(TranslationProvider)?.t(key);
+    return resolved !== undefined && resolved !== '' ? resolved : fallback;
+}

package/dist/_pkgs/affine-shared/services/universe-tag-defs-service.d.ts

@@ -0,0 +1,155 @@
+import type { BlockStdScope, FrameworkId } from '../../std/index.js';
+import type { RoleDefs, RoleId } from '../../std/gfx/index.js';
+import type { ExtensionType } from '../../store/index.js';
+/**
+ * `'<framework>:<local>'` — e.g. `'wardley:component'`, `'wardley:nature'`.
+ *
+ * A **seed-time** validation aid only. Persisted values are plain `string`s and
+ * are never narrowed to this, because a document may legitimately carry an id
+ * whose def was removed, renamed or never seeded in this deployment — and it
+ * must still open.
+ */
+export type QualifiedId = `${string}:${string}`;
+/** `'<tagId>/<local>'` — e.g. `'wardley:nature/data'`. */
+export type TagValueId = string;
+export type TagValueDef = {
+    /** `'<tagId>/<local>'`, e.g. `'wardley:nature/data'`. */
+    id: TagValueId;
+    /** Display label, already localized by the host. */
+    label: string;
+    description?: string;
+    /** Advisory colour token. The library may ignore it; it never affects layout. */
+    color?: string;
+    /** Hidden from pickers; still displayed when already present on an element. */
+    deprecated?: boolean;
+};
+export type TagDef = {
+    /** `'<framework>:<local>'`, e.g. `'wardley:nature'`. */
+    id: QualifiedId;
+    label: string;
+    description?: string;
+    /** How many values an element may carry for this tag. */
+    cardinality: 'single' | 'multi';
+    /** A closed list, or `'open'` for free-text values. */
+    values: TagValueDef[] | 'open';
+    /**
+     * Role ids this tag qualifies. `'*'` = every role of this framework.
+     * Specialisation applies: a tag on `'wardley:component'` also applies to
+     * every role whose `parent` chain reaches it — resolved with `roleIsA`
+     * against the framework's own `RoleDefs`, which the CALLER supplies.
+     */
+    appliesTo: RoleId[] | '*';
+    /**
+     * Advisory only. A missing "required" tag is reported by the rules engine; it
+     * NEVER blocks a gesture, a save, or a document load.
+     */
+    required?: boolean;
+    /** Ascending display order. Ties broken by seed order, then by id. */
+    order?: number;
+    deprecated?: boolean;
+};
+/**
+ * One pack of tag definitions. Plain data — no functions, no classes, no
+ * `Symbol` — so the TS type IS the JSON schema and a pack can ship as a `.json`
+ * asset.
+ *
+ * `roles` is deliberately absent: roles are lib-side data modules shipped by
+ * the framework that renders them (`WARDLEY_ROLES`), not app-seeded, and never
+ * pass through this registry (ADR 0007 § 2bis).
+ */
+export type UniverseTagDefs = {
+    /** Bumped only on a breaking change to THIS format. Currently 1. */
+    formatVersion: 1;
+    /**
+     * Unique id of this *pack*, not of the framework: several packs may extend
+     * the same framework (a base Wardley pack + a client's private extension).
+     * Doubles as the DI variant.
+     */
+    packId: string;
+    framework: FrameworkId;
+    label: string;
+    tags: TagDef[];
+};
+/** A seed-time problem, for a host diagnostics panel. Never thrown. */
+export type UniverseDefIssue = {
+    severity: 'warning' | 'error';
+    code: 'invalid-id' | 'cross-framework-id' | 'duplicate-conflict' | 'unsupported-format-version';
+    id?: string;
+    message: string;
+};
+/**
+ * Merged, validated, read-only view over the registered packs. **TAGS ONLY.**
+ */
+export interface UniverseRegistry {
+    frameworks(): FrameworkId[];
+    /**
+     * Tags applying to a role, ordered. Role specialisation is resolved with
+     * `roleIsA` against the framework's own `RoleDefs`, which the caller supplies
+     * — the registry holds no role vocabulary of its own.
+     */
+    tagsForRole(roleId: RoleId, defs: RoleDefs): TagDef[];
+    tag(id: string): TagDef | undefined;
+    /** Every merged tag, ordered. */
+    tags(): TagDef[];
+    /** Seed-time problems. Never thrown. */
+    issues(): UniverseDefIssue[];
+}
+/**
+ * Variant-parameterized: **one registration per pack, keyed by `packId`** —
+ * the same mechanism as `SpotlightHostExtension(elementType)` and
+ * `ExternalGroupByConfigProvider(config.name)`.
+ */
+export declare const UniverseTagDefsProvider: import("../../global/di/types.js").ServiceIdentifier<UniverseTagDefs> & (<U extends UniverseTagDefs = UniverseTagDefs>(variant: import("../../global/di/types.js").ServiceVariant) => import("../../global/di/types.js").ServiceIdentifier<U>);
+/**
+ * Seed one or more packs.
+ *
+ * `di.override`, **not** `di.addImpl`: `addImpl` throws
+ * `DuplicateServiceDefinitionError` when the same `[scope, identifier, variant]`
+ * is registered twice, while `override` works whether or not a prior
+ * registration exists. That is exactly the idempotency this needs — **distinct
+ * `packId`s accumulate, identical `packId`s replace** — so a host that
+ * re-registers on every render never throws and never grows the registry.
+ *
+ * Order stability is load-bearing and non-obvious: `getAll` returns a
+ * `Map<ServiceVariant, T>`, and `Map.set` on an EXISTING key keeps that key's
+ * original insertion position. Re-seeding a pack therefore updates it in place
+ * rather than moving it to the end, so a re-registration cannot silently flip
+ * which pack wins a cosmetic field.
+ *
+ * **All packs MUST be registered in the same DI scope.** `getAllRaw` falls back
+ * to the parent scope only when the current scope has no registration for the
+ * identifier AT ALL; it never merges across scopes. Seeding one pack from a
+ * `StoreExtension` and another from a `ViewExtension` would silently hide the
+ * first behind the second. The library cannot enforce this, so it is stated
+ * here and belongs in the host integration checklist.
+ */
+export declare function UniverseTagDefsExtension(defs: UniverseTagDefs | UniverseTagDefs[]): ExtensionType;
+/**
+ * Merge every registered pack into one read-only view.
+ *
+ * Pure, so it is testable with literals and no container. The merge rules, in
+ * full:
+ *
+ * - **Union by id.** Several packs may extend the same universe.
+ * - **Additive fields merge:** `values` are unioned by value id, `appliesTo`
+ *   arrays are unioned, and `'*'` absorbs any list.
+ * - **Cosmetic fields — last pack wins:** `label`, `description`, `color`,
+ *   `order`, `required`, `deprecated`.
+ * - **Structural fields — first pack wins, conflict recorded:** `cardinality`,
+ *   and `values: 'open'` vs a closed list. The conflict becomes a
+ *   `duplicate-conflict` error issue and does NOT throw. A host that needs a
+ *   deterministic winner should not define the same structural field twice; the
+ *   registry reports the collision rather than guessing.
+ * - **Idempotent by value.** Activating a universe twice yields the same
+ *   registry.
+ */
+export declare function buildUniverseRegistry(packs: readonly UniverseTagDefs[]): UniverseRegistry;
+/**
+ * Whether a tag qualifies a role, following specialisation: a tag declared on
+ * `'wardley:component'` also applies to `'wardley:market'`, which specialises
+ * it. `'*'` matches every role of the tag's own framework and nothing else —
+ * a wildcard that crossed framework boundaries would make two taxonomies
+ * qualify each other's elements.
+ */
+export declare function tagAppliesToRole(def: TagDef, roleId: RoleId | undefined, defs: RoleDefs): boolean;
+export declare function getUniverseRegistry(std: BlockStdScope): UniverseRegistry;