@formicoidea/labre-core 0.41.0 → 0.42.0

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

@@ -2,12 +2,12 @@ import type { ExtensionType } from '../../../store/index.js';
 import type { CitationEvents } from './citation.js';
 import type { CodeBlockEvents } from './code-block.js';
 import type { OutDatabaseAllEvents } from './database.js';
-import type { AuditEvents, BlockLifecycleEvents, FrameworkDiagramEvents, ValidationEvents } from './lifecycle.js';
+import type { AuditEvents, BlockLifecycleEvents, DocumentHealthEvents, FrameworkDiagramEvents, ValidationEvents } from './lifecycle.js';
 import type { LinkToolbarEvents } from './link.js';
 import type { NoteEvents } from './note.js';
 import type { SlashMenuEvents } from './slash-menu.js';
 import type { AttachmentReloadedEvent, AttachmentReloadedEventInToolbar, AttachmentUpgradedEvent, AttachmentUploadedEvent, BlockCreationEvent, DocCreatedEvent, EdgelessToolPickedEvent, ElementCreationEvent, ElementLockEvent, ElementUpdatedEvent, LatexEvent, LinkedDocCreatedEvent, LinkEvent, MindMapCollapseEvent, TelemetryEvent } from './types.js';
-export type TelemetryEventMap = OutDatabaseAllEvents & LinkToolbarEvents & SlashMenuEvents & CodeBlockEvents & NoteEvents & CitationEvents & BlockLifecycleEvents & FrameworkDiagramEvents & ValidationEvents & AuditEvents & {
+export type TelemetryEventMap = OutDatabaseAllEvents & LinkToolbarEvents & SlashMenuEvents & CodeBlockEvents & NoteEvents & CitationEvents & BlockLifecycleEvents & FrameworkDiagramEvents & ValidationEvents & AuditEvents & DocumentHealthEvents & {
     DocCreated: DocCreatedEvent;
     Link: TelemetryEvent;
     LinkedDocCreated: LinkedDocCreatedEvent;

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

@@ -0,0 +1,34 @@
+import type { TemplateResult } from 'lit';
+import { type ToolbarActionGenerator } from './action.js';
+/**
+ * A "⋮" entry that INVOKES a registered command instead of restating what it
+ * does — the shape `docs/adr/0010` M3 introduced, and the reason an export has
+ * one behaviour, one availability rule and one telemetry emission whether it is
+ * reached from here, from the catalogue, from the palette, from
+ * Settings › Shortcuts or from the agent.
+ *
+ * Two things the widget imposes: a menu line is drawn from `label` (a tooltip
+ * on a line that is already words would be a second copy of them), and
+ * `placement: ActionPlacement.More` is what partitions it out of the row in the
+ * first place — `renderToolbar` splits on exactly that flag, and the entries it
+ * collects come from every module contributing to the element, so a framework
+ * can add to the "⋮" without owning it.
+ *
+ * `generate` rather than a static entry because the i18n seam needs `std`:
+ * `translateKey` is what reaches the host's catalogue, and a hard-coded English
+ * label would be the one wording a host could not override.
+ *
+ * ## Why it lives here
+ *
+ * It was written three times — BPMN's pool row, C4's board row and Wardley's
+ * map row — each copy a few words of comment apart from the others, because a
+ * framework's toolbar has no layer below it to share with. The generic SVG
+ * export (`export.svg`, ADR 0025) is the fourth caller and the first that is
+ * not a framework at all, which is what settles the question: the shape belongs
+ * to the toolbar service, beside the module registry it plugs into, not to
+ * whichever framework happened to need it first.
+ *
+ * `translateKey` lives in this same package, and `@labre/std` is already a
+ * dependency of it, so nothing here closes an import cycle.
+ */
+export declare function commandMoreAction(id: string, commandId: string, labelKey: string, labelFallback: string, icon: TemplateResult): ToolbarActionGenerator;

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

@@ -0,0 +1,63 @@
+import { getRegisteredCommands, runCommand } from '../../../std/index.js';
+import { translateKey } from '../translation-service/index.js';
+import { ActionPlacement } from './action.js';
+/** The registered command an entry drives, or `undefined` when it is not. */
+const findCommand = (ctx, id) => getRegisteredCommands(ctx.std).find(candidate => candidate.id === id);
+/**
+ * A "⋮" entry that INVOKES a registered command instead of restating what it
+ * does — the shape `docs/adr/0010` M3 introduced, and the reason an export has
+ * one behaviour, one availability rule and one telemetry emission whether it is
+ * reached from here, from the catalogue, from the palette, from
+ * Settings › Shortcuts or from the agent.
+ *
+ * Two things the widget imposes: a menu line is drawn from `label` (a tooltip
+ * on a line that is already words would be a second copy of them), and
+ * `placement: ActionPlacement.More` is what partitions it out of the row in the
+ * first place — `renderToolbar` splits on exactly that flag, and the entries it
+ * collects come from every module contributing to the element, so a framework
+ * can add to the "⋮" without owning it.
+ *
+ * `generate` rather than a static entry because the i18n seam needs `std`:
+ * `translateKey` is what reaches the host's catalogue, and a hard-coded English
+ * label would be the one wording a host could not override.
+ *
+ * ## Why it lives here
+ *
+ * It was written three times — BPMN's pool row, C4's board row and Wardley's
+ * map row — each copy a few words of comment apart from the others, because a
+ * framework's toolbar has no layer below it to share with. The generic SVG
+ * export (`export.svg`, ADR 0025) is the fourth caller and the first that is
+ * not a framework at all, which is what settles the question: the shape belongs
+ * to the toolbar service, beside the module registry it plugs into, not to
+ * whichever framework happened to need it first.
+ *
+ * `translateKey` lives in this same package, and `@labre/std` is already a
+ * dependency of it, so nothing here closes an import cycle.
+ */
+export function commandMoreAction(id, commandId, labelKey, labelFallback, icon) {
+    return {
+        id,
+        placement: ActionPlacement.More,
+        when: (ctx) => {
+            const command = findCommand(ctx, commandId);
+            return command !== undefined && (command.when?.(ctx.std) ?? true);
+        },
+        generate: (ctx) => ({
+            icon,
+            label: translateKey(ctx.std, labelKey, labelFallback),
+            run: (runCtx) => {
+                const command = findCommand(runCtx, commandId);
+                if (!command)
+                    return;
+                // The same `source` the row's own entries report: the "⋮" is a
+                // degradation of the row, not a surface of its own, and the
+                // `ElementCreationSource` union deliberately names places rather than
+                // widths (`docs/adr/0008`).
+                runCommand(runCtx.std, command, {
+                    surface: 'contextual-toolbar',
+                    source: 'toolbar:general',
+                });
+            },
+        }),
+    };
+}

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

@@ -1,4 +1,5 @@
 export * from './action.js';
+export * from './command-action.js';
 export * from './config.js';
 export * from './context.js';
 export { Flag as ToolbarFlag } from './flags.js';

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

@@ -1,4 +1,5 @@
 export * from './action.js';
+export * from './command-action.js';
 export * from './config.js';
 export * from './context.js';
 export { Flag as ToolbarFlag } from './flags.js';

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

@@ -93,6 +93,35 @@ export declare const SYNCED_DOC_EMPTY_PREVIEW: ChromeWording;
  * copies of it in eight manifests would be eight keys for one tooltip.
  */
 export declare const BOARD_RESIZE_TOGGLE: ChromeWording;
+/**
+ * The orientation toggle a BANDED background carries: the one gesture that
+ * turns a frame drawn in columns into the same frame drawn in rows.
+ *
+ * Declared beside the resize toggle for the same reason and with the same
+ * scope: it names a behaviour of the frame primitive — where the name band
+ * sits and which way the bands run — rather than anything a notation calls its
+ * own. A UML activity partition is the first frame to use it (§15.6.4 draws
+ * swimlanes either way and says the choice means nothing); a BPMN pool is the
+ * obvious second, and a second key for it would be a second tooltip for one
+ * word.
+ */
+export declare const BOARD_ORIENTATION_TOGGLE: ChromeWording;
+/**
+ * The gesture that divides a banded background one band further — the button a
+ * frame carrying zones offers next to the two above.
+ *
+ * Declared here with them, and for the third time for the same reason: it names
+ * a behaviour of the generic frame primitive (a background whose `instanceZones`
+ * are a list the author grows) rather than anything a notation calls its own. A
+ * UML combined fragment is the first frame to use it — §17.6.4's second operand
+ * is a band added to a box that has one — and a BPMN pool's lane is the obvious
+ * second the day it stops reaching this through a command of its own.
+ *
+ * "Band" and not "operand" or "lane": the word has to be true of every frame
+ * that offers the button, and each notation's own noun is already written on
+ * the element the button is attached to.
+ */
+export declare const BOARD_ADD_BAND: ChromeWording;
 /**
  * The legend button, in the two wordings the boards actually use: the notation
  * boards say "notation", Wardley says "components".
@@ -103,6 +132,19 @@ export declare const BOARD_RESIZE_TOGGLE: ChromeWording;
  */
 export declare const BOARD_LEGEND_NOTATION: ChromeWording;
 export declare const BOARD_LEGEND_COMPONENTS: ChromeWording;
+/**
+ * The two END labels a connector can carry beside its caption — where UML
+ * writes a multiplicity and a role name (`docs/adr/0018` phase 2).
+ *
+ * Declared here and not in the UML pack for the same reason the resize toggle
+ * is: they name a part of the generic CONNECTOR, which every framework draws,
+ * and a stored connector keeps its end labels with the UML tooling switched off
+ * (`docs/adr/0009`). "Source" and "target" are the connector's own words for
+ * its two ends, already the vocabulary of `frontEndpointStyle` /
+ * `rearEndpointStyle` and of the direction commands.
+ */
+export declare const CONNECTOR_SOURCE_LABEL: ChromeWording;
+export declare const CONNECTOR_TARGET_LABEL: ChromeWording;
 export declare const NOTE_SHADOW_NONE: ChromeWording;
 export declare const NOTE_SHADOW_BOX: ChromeWording;
 export declare const NOTE_SHADOW_STICKER: ChromeWording;
@@ -136,14 +178,19 @@ export declare const TEXT_FORMAT_ITALIC: ChromeWording;
 export declare const TEXT_FORMAT_UNDERLINE: ChromeWording;
 export declare const TEXT_FORMAT_STRIKETHROUGH: ChromeWording;
 /**
- * The three font weights and the one non-default font style a text toolbar
- * offers — said identically by the toolbar's own "current selection" label
- * (`gfx/text`) and by the popup menu that picks them
- * (`widgets/edgeless-toolbar`).
+ * The font weights and the one non-default font style a text toolbar offers —
+ * said identically by the toolbar's own "current selection" label (`gfx/text`)
+ * and by the popup menu that picks them (`widgets/edgeless-toolbar`).
  */
 export declare const FONT_WEIGHT_LIGHT: ChromeWording;
 export declare const FONT_WEIGHT_REGULAR: ChromeWording;
 export declare const FONT_WEIGHT_SEMIBOLD: ChromeWording;
+/**
+ * An alias (L7 dedupe): the heaviest canvas weight is said with the same word
+ * as the prose toolbar's {@link TEXT_FORMAT_BOLD}, so it shares its one key —
+ * exactly as {@link FONT_STYLE_ITALIC} does below.
+ */
+export declare const FONT_WEIGHT_BOLD: ChromeWording;
 /**
  * An alias (L7 dedupe): the same word as {@link TEXT_FORMAT_ITALIC}, one key.
  */
@@ -236,13 +283,36 @@ export declare const BLOCK_TYPE_QUOTE_DESCRIPTION: ChromeWording;
 export declare const BLOCK_TYPE_DIVIDER: ChromeWording;
 export declare const BLOCK_TYPE_DIVIDER_DESCRIPTION: ChromeWording;
 /**
- * The auto-legend BOX title every framework's `createAutoLegend` draws
- * (`AutoLegendSpec.title`, `@labre/affine-gfx-ddd-shared`) — "Legend" itself,
+ * The automatic legend BOX title the shared engine draws
+ * (`createBoardLegend`, `@labre/affine-block-surface`) — "Legend" itself,
  * distinct from the {@link BOARD_LEGEND_NOTATION} / {@link BOARD_LEGEND_COMPONENTS}
  * toolbar BUTTONS that create it. Declared here because it is the same word on
- * every board that has one: the three DDD tools, EDGY and C4 alike.
+ * every board that has one, and a board's own command may override it
+ * (`CommandLegendBox.titleWording`).
  */
 export declare const BOARD_LEGEND_TITLE: ChromeWording;
+/**
+ * The group's own seed: the default title a newly created group is stamped
+ * with (`Group 2`), written into the document at creation. Resolved at
+ * PLACEMENT and never again — a group renamed by its author keeps its name,
+ * and a group created before this key existed keeps the plain text it was
+ * given.
+ *
+ * `{{n}}` is the group's 1-based ordinal among the groups already on the doc;
+ * see this service's README on why a count carries a param rather than its own
+ * key.
+ *
+ * ## Why it sits here rather than with the group package
+ *
+ * Two packages group elements and neither may import the other's translations:
+ * `@labre/affine-gfx-group`, which owns the gesture, and
+ * `@labre/affine-block-surface`, whose legend groups the box it just drew and
+ * which `gfx-group` DEPENDS ON. This layer is below both. It is deliberately
+ * NOT listed in {@link CHROME_WORDINGS}: the key stays declared by the group
+ * package under source `seed` (`GROUP_WORDINGS`), so the manifest is
+ * byte-identical to what it was — one key, one source.
+ */
+export declare const GROUP_SEED_NAME: ChromeWording;
 /**
  * "Undo" said by the link package's quick-tool button (dense + full) and by
  * the generic notification's own undo action

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

@@ -161,6 +161,41 @@ export const BOARD_RESIZE_TOGGLE = [
     'com.labre.board.toolbar.resize-toggle',
     'Enable / lock resizing',
 ];
+/**
+ * The orientation toggle a BANDED background carries: the one gesture that
+ * turns a frame drawn in columns into the same frame drawn in rows.
+ *
+ * Declared beside the resize toggle for the same reason and with the same
+ * scope: it names a behaviour of the frame primitive — where the name band
+ * sits and which way the bands run — rather than anything a notation calls its
+ * own. A UML activity partition is the first frame to use it (§15.6.4 draws
+ * swimlanes either way and says the choice means nothing); a BPMN pool is the
+ * obvious second, and a second key for it would be a second tooltip for one
+ * word.
+ */
+export const BOARD_ORIENTATION_TOGGLE = [
+    'com.labre.board.toolbar.orientation-toggle',
+    'Vertical / horizontal bands',
+];
+/**
+ * The gesture that divides a banded background one band further — the button a
+ * frame carrying zones offers next to the two above.
+ *
+ * Declared here with them, and for the third time for the same reason: it names
+ * a behaviour of the generic frame primitive (a background whose `instanceZones`
+ * are a list the author grows) rather than anything a notation calls its own. A
+ * UML combined fragment is the first frame to use it — §17.6.4's second operand
+ * is a band added to a box that has one — and a BPMN pool's lane is the obvious
+ * second the day it stops reaching this through a command of its own.
+ *
+ * "Band" and not "operand" or "lane": the word has to be true of every frame
+ * that offers the button, and each notation's own noun is already written on
+ * the element the button is attached to.
+ */
+export const BOARD_ADD_BAND = [
+    'com.labre.board.toolbar.add-band',
+    'Add a band',
+];
 /**
  * The legend button, in the two wordings the boards actually use: the notation
  * boards say "notation", Wardley says "components".
@@ -177,6 +212,26 @@ export const BOARD_LEGEND_COMPONENTS = [
     'com.labre.board.toolbar.legend.components',
     'Generate the legend (components present)',
 ];
+/* ── The connector's own labels ───────────────────────────────────────── */
+/**
+ * The two END labels a connector can carry beside its caption — where UML
+ * writes a multiplicity and a role name (`docs/adr/0018` phase 2).
+ *
+ * Declared here and not in the UML pack for the same reason the resize toggle
+ * is: they name a part of the generic CONNECTOR, which every framework draws,
+ * and a stored connector keeps its end labels with the UML tooling switched off
+ * (`docs/adr/0009`). "Source" and "target" are the connector's own words for
+ * its two ends, already the vocabulary of `frontEndpointStyle` /
+ * `rearEndpointStyle` and of the direction commands.
+ */
+export const CONNECTOR_SOURCE_LABEL = [
+    'com.labre.connector.toolbar.source-label',
+    'Source label',
+];
+export const CONNECTOR_TARGET_LABEL = [
+    'com.labre.connector.toolbar.target-label',
+    'Target label',
+];
 /* ── Note shadow styles ────────────────────────────────────────────────
  * The note block's own shadow options, shared verbatim between the surface
  * toolbar's style panel (blocks/note) and the edgeless senior menu's shadow
@@ -271,10 +326,9 @@ export const TEXT_FORMAT_STRIKETHROUGH = [
 ];
 /* ── Font weight / style ────────────────────────────────────────────────── */
 /**
- * The three font weights and the one non-default font style a text toolbar
- * offers — said identically by the toolbar's own "current selection" label
- * (`gfx/text`) and by the popup menu that picks them
- * (`widgets/edgeless-toolbar`).
+ * The font weights and the one non-default font style a text toolbar offers —
+ * said identically by the toolbar's own "current selection" label (`gfx/text`)
+ * and by the popup menu that picks them (`widgets/edgeless-toolbar`).
  */
 export const FONT_WEIGHT_LIGHT = [
     'com.labre.font.weight.light',
@@ -288,6 +342,12 @@ export const FONT_WEIGHT_SEMIBOLD = [
     'com.labre.font.weight.semibold',
     'Semibold',
 ];
+/**
+ * An alias (L7 dedupe): the heaviest canvas weight is said with the same word
+ * as the prose toolbar's {@link TEXT_FORMAT_BOLD}, so it shares its one key —
+ * exactly as {@link FONT_STYLE_ITALIC} does below.
+ */
+export const FONT_WEIGHT_BOLD = TEXT_FORMAT_BOLD;
 /**
  * An alias (L7 dedupe): the same word as {@link TEXT_FORMAT_ITALIC}, one key.
  */
@@ -472,16 +532,42 @@ export const BLOCK_TYPE_DIVIDER_DESCRIPTION = [
     'Visually separate content.',
 ];
 /**
- * The auto-legend BOX title every framework's `createAutoLegend` draws
- * (`AutoLegendSpec.title`, `@labre/affine-gfx-ddd-shared`) — "Legend" itself,
+ * The automatic legend BOX title the shared engine draws
+ * (`createBoardLegend`, `@labre/affine-block-surface`) — "Legend" itself,
  * distinct from the {@link BOARD_LEGEND_NOTATION} / {@link BOARD_LEGEND_COMPONENTS}
  * toolbar BUTTONS that create it. Declared here because it is the same word on
- * every board that has one: the three DDD tools, EDGY and C4 alike.
+ * every board that has one, and a board's own command may override it
+ * (`CommandLegendBox.titleWording`).
  */
 export const BOARD_LEGEND_TITLE = [
     'com.labre.board.legend.title',
     'Legend',
 ];
+/**
+ * The group's own seed: the default title a newly created group is stamped
+ * with (`Group 2`), written into the document at creation. Resolved at
+ * PLACEMENT and never again — a group renamed by its author keeps its name,
+ * and a group created before this key existed keeps the plain text it was
+ * given.
+ *
+ * `{{n}}` is the group's 1-based ordinal among the groups already on the doc;
+ * see this service's README on why a count carries a param rather than its own
+ * key.
+ *
+ * ## Why it sits here rather than with the group package
+ *
+ * Two packages group elements and neither may import the other's translations:
+ * `@labre/affine-gfx-group`, which owns the gesture, and
+ * `@labre/affine-block-surface`, whose legend groups the box it just drew and
+ * which `gfx-group` DEPENDS ON. This layer is below both. It is deliberately
+ * NOT listed in {@link CHROME_WORDINGS}: the key stays declared by the group
+ * package under source `seed` (`GROUP_WORDINGS`), so the manifest is
+ * byte-identical to what it was — one key, one source.
+ */
+export const GROUP_SEED_NAME = [
+    'com.labre.group.seed.name',
+    'Group {{n}}',
+];
 /* ── Undo, wherever a quick-tool or a notification offers it ──────────── */
 /**
  * "Undo" said by the link package's quick-tool button (dense + full) and by
@@ -1024,8 +1110,12 @@ export const CHROME_WORDINGS = [
     LINKED_DOC_EMPTY_PREVIEW,
     SYNCED_DOC_EMPTY_PREVIEW,
     BOARD_RESIZE_TOGGLE,
+    BOARD_ORIENTATION_TOGGLE,
+    BOARD_ADD_BAND,
     BOARD_LEGEND_NOTATION,
     BOARD_LEGEND_COMPONENTS,
+    CONNECTOR_SOURCE_LABEL,
+    CONNECTOR_TARGET_LABEL,
     NOTE_SHADOW_NONE,
     NOTE_SHADOW_BOX,
     NOTE_SHADOW_STICKER,

package/dist/_pkgs/affine-shared/styles/index.d.ts

@@ -1,4 +1,5 @@
 export { fontBaseStyle, fontSMStyle, fontXSStyle } from './font.js';
+export { reducedMotionStyle, SPRING_DURATION_MS, SPRING_EASING, springDuration, springEasing, } from './motion.js';
 export { panelBaseColorsStyle, panelBaseStyle } from './panel.js';
 export { scrollbarStyle } from './scrollbar-style.js';
 export { affineTextStyles } from './text.js';

package/dist/_pkgs/affine-shared/styles/index.js

@@ -1,4 +1,5 @@
 export { fontBaseStyle, fontSMStyle, fontXSStyle } from './font.js';
+export { reducedMotionStyle, SPRING_DURATION_MS, SPRING_EASING, springDuration, springEasing, } from './motion.js';
 export { panelBaseColorsStyle, panelBaseStyle } from './panel.js';
 export { scrollbarStyle } from './scrollbar-style.js';
 export { affineTextStyles } from './text.js';

package/dist/_pkgs/affine-shared/styles/motion.d.ts

@@ -0,0 +1,14 @@
+/** easeOutBack: travel, overshoot a little, settle. */
+export declare const SPRING_EASING = "cubic-bezier(0.34, 1.56, 0.64, 1)";
+/** The house tempo of the edgeless chrome, in milliseconds. */
+export declare const SPRING_DURATION_MS = 240;
+/** {@link SPRING_EASING} for a `css` template. */
+export declare const springEasing: import("lit").CSSResult;
+/** {@link SPRING_DURATION_MS} for a `css` template. */
+export declare const springDuration: import("lit").CSSResult;
+/**
+ * Every animation and transition inside `container` off when the reader asked
+ * the OS for less motion. The end state is the resting state in each case, so
+ * dropping the animation loses nothing but the travel.
+ */
+export declare const reducedMotionStyle: (container: string) => import("lit").CSSResult;

package/dist/_pkgs/affine-shared/styles/motion.js

@@ -0,0 +1,38 @@
+/**
+ * The chrome's motion tokens — the first of them, and deliberately only the
+ * values the library had already converged on by hand.
+ *
+ * The edgeless chrome has been animating at ~0.23-0.24s since upstream
+ * (`edgeless-toolbar.ts`, `create-popper.ts`, `date-picker/style.ts`, `toast`),
+ * and the fork's one overshoot curve is the senior toolbar's "pop upright"
+ * (`gfx/mindmap/src/toolbar/senior-tool.ts`): `cubic-bezier(0.34, 1.56, 0.64, 1)`,
+ * the standard easeOutBack. Nothing exported it, so the second component that
+ * wanted a springy settle would have invented a third easing. This module is
+ * where it stops being a literal.
+ *
+ * `springEasing` overshoots by design — only use it on a transform that has
+ * room to overshoot (a slide, a scale, a rotation), never on a colour or on
+ * anything whose end value must never be passed.
+ */
+import { css, unsafeCSS } from 'lit';
+/** easeOutBack: travel, overshoot a little, settle. */
+export const SPRING_EASING = 'cubic-bezier(0.34, 1.56, 0.64, 1)';
+/** The house tempo of the edgeless chrome, in milliseconds. */
+export const SPRING_DURATION_MS = 240;
+/** {@link SPRING_EASING} for a `css` template. */
+export const springEasing = unsafeCSS(SPRING_EASING);
+/** {@link SPRING_DURATION_MS} for a `css` template. */
+export const springDuration = unsafeCSS(`${SPRING_DURATION_MS}ms`);
+/**
+ * Every animation and transition inside `container` off when the reader asked
+ * the OS for less motion. The end state is the resting state in each case, so
+ * dropping the animation loses nothing but the travel.
+ */
+export const reducedMotionStyle = (container) => css `
+  @media (prefers-reduced-motion: reduce) {
+    ${unsafeCSS(container)}, ${unsafeCSS(container)} * {
+      animation: none !important;
+      transition: none !important;
+    }
+  }
+`;

package/dist/_pkgs/affine-shared/utils/event.d.ts

@@ -19,6 +19,16 @@ export declare function isMiddleButtonPressed(e: MouseEvent): boolean;
 export declare function isRightButtonPressed(e: MouseEvent): boolean;
 export declare function stopPropagation(event: Event): void;
 export declare function isControlledKeyboardEvent(e: KeyboardEvent): boolean;
+/**
+ * The editor swallows Tab, Shift-Tab and Enter so that indentation and block
+ * splitting stay under the control of the block-scoped handlers. That would
+ * however trap the focus on the native controls the editor renders (the
+ * collapse button of headings and lists, for instance), which then could
+ * neither be reached, left nor activated with the keyboard. When the event
+ * originates from such a control — and not from editable text — the native
+ * behaviour is let through.
+ */
+export declare function isNativeFocusableTarget(target: EventTarget | null): boolean;
 export declare function isNewTabTrigger(event?: MouseEvent): boolean;
 export declare function isNewViewTrigger(event?: MouseEvent): boolean;
 export declare function on<T extends HTMLElement, K extends keyof M, M = HTMLElementEventMap>(element: T, event: K, handler: (ev: M[K]) => void, options?: boolean | AddEventListenerOptions): () => void;

package/dist/_pkgs/affine-shared/utils/event.js

@@ -37,6 +37,26 @@ export function stopPropagation(event) {
 export function isControlledKeyboardEvent(e) {
     return e.ctrlKey || e.metaKey || e.altKey;
 }
+// The editor host itself carries `tabindex="0"` so that it can receive the
+// keystrokes aimed at a block selection; it is the editing surface, not a
+// control, hence the exclusion.
+const NATIVE_FOCUSABLE_SELECTOR = 'button, a[href], input, select, textarea, [tabindex]:not([tabindex="-1"]):not(editor-host)';
+/**
+ * The editor swallows Tab, Shift-Tab and Enter so that indentation and block
+ * splitting stay under the control of the block-scoped handlers. That would
+ * however trap the focus on the native controls the editor renders (the
+ * collapse button of headings and lists, for instance), which then could
+ * neither be reached, left nor activated with the keyboard. When the event
+ * originates from such a control — and not from editable text — the native
+ * behaviour is let through.
+ */
+export function isNativeFocusableTarget(target) {
+    if (!(target instanceof Element))
+        return false;
+    if (target instanceof HTMLElement && target.isContentEditable)
+        return false;
+    return !!target.closest(NATIVE_FOCUSABLE_SELECTOR);
+}
 export function isNewTabTrigger(event) {
     return event
         ? (event.ctrlKey || event.metaKey || event.button === 1) && !event.altKey

package/dist/_pkgs/affine-shared/utils/file/filesys.d.ts

@@ -52,6 +52,22 @@ export declare function openSingleFileWith(acceptType?: AcceptTypes): Promise<Fi
  */
 export declare function openSingleFileWithSpec(spec: FilePickerSpec): Promise<File | null>;
 export declare function getImageFilesFromLocal(): Promise<File[]>;
+/**
+ * A name a file system will accept, minus the extension.
+ *
+ * The sanitiser the framework exports each wrote for themselves
+ * (`wardleySafeFilename`, `c4SafeFilename`, BPMN's) — same five steps, same
+ * 120-character ceiling — lifted here for the callers that belong to no
+ * framework at all. The generic SVG export (ADR 0025) is the first of them: it
+ * writes a file for ELEVEN kinds of board, so it has no framework's fallback to
+ * borrow and takes one as a parameter instead.
+ *
+ * The three framework copies stay where they are: each is part of an
+ * interchange capability with its own format id and its own declared fallback
+ * (`map`, `board`, `process`), and rewriting them to call this one would touch
+ * three exported APIs for no behaviour change.
+ */
+export declare function safeFilename(raw: string | undefined, fallback: string): string;
 export declare function downloadBlob(blob: Blob, name: string): void;
 /**
  * Because the image block and attachment block have different props.

package/dist/_pkgs/affine-shared/utils/file/filesys.js

@@ -188,6 +188,31 @@ export async function getImageFilesFromLocal() {
     const files = await openFilesWith('Images');
     return files ?? [];
 }
+/**
+ * A name a file system will accept, minus the extension.
+ *
+ * The sanitiser the framework exports each wrote for themselves
+ * (`wardleySafeFilename`, `c4SafeFilename`, BPMN's) — same five steps, same
+ * 120-character ceiling — lifted here for the callers that belong to no
+ * framework at all. The generic SVG export (ADR 0025) is the first of them: it
+ * writes a file for ELEVEN kinds of board, so it has no framework's fallback to
+ * borrow and takes one as a parameter instead.
+ *
+ * The three framework copies stay where they are: each is part of an
+ * interchange capability with its own format id and its own declared fallback
+ * (`map`, `board`, `process`), and rewriting them to call this one would touch
+ * three exported APIs for no behaviour change.
+ */
+export function safeFilename(raw, fallback) {
+    const safe = (raw ?? '')
+        .trim()
+        .replaceAll(/[\\/:*?"<>|]/g, '-')
+        .replaceAll(/\s+/g, ' ')
+        .trim()
+        .slice(0, 120)
+        .replace(/[. ]+$/, '');
+    return safe || fallback;
+}
 export function downloadBlob(blob, name) {
     const dataURL = URL.createObjectURL(blob);
     const tmpLink = document.createElement('a');

package/dist/_pkgs/affine-shared/utils/index.d.ts

@@ -13,6 +13,7 @@ export * from './fractional-indexing.js';
 export * from './image.js';
 export * from './insert.js';
 export * from './is-abort-error.js';
+export * from './link-preview-refresh.js';
 export * from './math.js';
 export * from './model/index.js';
 export * from './popper-position.js';

package/dist/_pkgs/affine-shared/utils/index.js

@@ -13,6 +13,7 @@ export * from './fractional-indexing.js';
 export * from './image.js';
 export * from './insert.js';
 export * from './is-abort-error.js';
+export * from './link-preview-refresh.js';
 export * from './math.js';
 export * from './model/index.js';
 export * from './popper-position.js';

package/dist/_pkgs/affine-shared/utils/link-preview-refresh.d.ts

@@ -0,0 +1,12 @@
+import type { Store } from '../../store/index.js';
+/**
+ * Whether a bookmark or embed card must refetch its link preview after a props
+ * change.
+ *
+ * `BlockModel.propsUpdated` carries the key only, so a subscriber cannot tell a
+ * local edit from an update that arrived from another peer. A readonly peer
+ * receives the change like everyone else; the author is the one who refetches
+ * and syncs the result. Without this guard every reader of the document races
+ * the author to rewrite the same title, description and image.
+ */
+export declare function shouldRefreshOnPropsUpdate(store: Store, key: string): boolean;

package/dist/_pkgs/affine-shared/utils/link-preview-refresh.js

@@ -0,0 +1,13 @@
+/**
+ * Whether a bookmark or embed card must refetch its link preview after a props
+ * change.
+ *
+ * `BlockModel.propsUpdated` carries the key only, so a subscriber cannot tell a
+ * local edit from an update that arrived from another peer. A readonly peer
+ * receives the change like everyone else; the author is the one who refetches
+ * and syncs the result. Without this guard every reader of the document races
+ * the author to rewrite the same title, description and image.
+ */
+export function shouldRefreshOnPropsUpdate(store, key) {
+    return key === 'url' && !store.readonly;
+}

package/dist/_pkgs/affine-widget-edgeless-toolbar/catalogue/artefact-catalogue-widget.d.ts

@@ -138,11 +138,19 @@ export declare class EdgelessArtefactCatalogueWidget extends WidgetComponent<Roo
      */
     private _chord;
     /**
-     * Run the command. The panel STAYS OPEN.
+     * Arm an artefact, run anything else. The panel STAYS OPEN either way.
      *
-     * `runCommand` is the one bottleneck (ADR 0008): the telemetry and the usage
-     * measure are emitted there, and `surface: 'catalogue'` is what makes this
-     * panel distinguishable from the sub-menu in the numbers.
+     * An artefact row arms the placement tool exactly as the senior menu's does
+     * (PO decision, 2026-09-16): the ghost goes under the cursor and the click on
+     * the canvas says where. The panel is one gesture away from the board, so it
+     * can stay open behind the ghost.
+     *
+     * For everything else `runCommand` is the one bottleneck (ADR 0008): the
+     * telemetry and the usage measure are emitted there, and `surface:
+     * 'catalogue'` is what makes this panel distinguishable from the sub-menu in
+     * the numbers. An armed artefact reports at PLACEMENT instead, through the
+     * tool, so its `surface` reads `'senior-menu'` — the row it belongs to,
+     * whichever surface offered it.
      *
      * Staying open is the PO's call (recette, 27/08/2026), reversing the first
      * default: a catalogue is where a user furnishes a diagram, and furnishing is