@formicoidea/labre-core 0.41.0 → 0.43.1

package/dist/_pkgs/affine-components/color-picker/framework-palette.d.ts

@@ -0,0 +1,106 @@
+/**
+ * The framework palettes a colour picker offers as a CAROUSEL, and the rule
+ * that decides which page it opens on (`docs/adr/0027`).
+ *
+ * Three pieces, in dependency order:
+ *
+ * 1. **The seam** — {@link FrameworkPaletteExtension}, registered from a
+ *    framework's FLAG-GATED view extension. Offering hues is TOOLING, so a
+ *    framework switched off disappears from the carousel while every colour it
+ *    ever wrote stays exactly where it is (`docs/adr/0009`).
+ * 2. **The resolver** — {@link frameworkOfElement}: which framework a selected
+ *    element belongs to, from what the document already says.
+ * 3. **The builder** — {@link frameworkPaletteGroups}: the carousel a toolbar
+ *    hands the picker, base palette first and never hidden (DESIGN.md, "The
+ *    Coexisting Palettes Rule").
+ *
+ * Nothing here is written to a document: a picked swatch is still a plain
+ * stored colour value, and `packages/affine/model` is untouched.
+ */
+import { type Palette } from '../../affine-model/index.js';
+import { type ChromeWording } from '../../affine-shared/services/index.js';
+import { type BlockStdScope, type FrameworkId } from '../../std/index.js';
+import { type GfxController, type GfxModel } from '../../std/gfx/index.js';
+import type { ExtensionType } from '../../store/index.js';
+import type { NamedPalette } from './types.js';
+/**
+ * A framework's contribution to the carousel: its own name and its own hues.
+ *
+ * `palettes` is the framework's existing `*_PALETTE_LIST` — the same array its
+ * node toolbar already seeds its picker with — so registering one is a
+ * one-liner in the view extension and no palette is restated.
+ */
+export type FrameworkPalette = {
+    framework: FrameworkId;
+    /** The framework's own name, as the carousel prints it. */
+    labelWording: ChromeWording;
+    palettes: NamedPalette[];
+};
+/**
+ * A framework registers its palette here, and nothing else registers one.
+ * Multi-instance, keyed by {@link FrameworkPalette.framework}, exactly like
+ * `TemplateCategoryIdentifier` (`gfx/template/src/contribute.ts`): two
+ * extensions claiming the same framework collide at set-up
+ * (`DuplicateServiceDefinitionError`) rather than showing the page twice.
+ */
+export declare const FrameworkPaletteIdentifier: import("../../global/di/types.js").ServiceIdentifier<FrameworkPalette> & (<U extends FrameworkPalette = FrameworkPalette>(variant: import("../../global/di/types.js").ServiceVariant) => import("../../global/di/types.js").ServiceIdentifier<U>);
+/**
+ * Register a framework's palette. Call it from `setup()` of the FLAG-GATED
+ * view extension, beside the senior tool:
+ *
+ * ```ts
+ * context.register(FrameworkPaletteExtension(WARDLEY_FRAMEWORK_PALETTE));
+ * ```
+ */
+export declare function FrameworkPaletteExtension(...palettes: FrameworkPalette[]): ExtensionType;
+/** One page of the carousel. */
+export type PaletteGroup = {
+    /** {@link BASE_PALETTE_KEY} for the editor's own palette, else a `FrameworkId`. */
+    key: string;
+    /** Already resolved through the host's catalogue — ready to print. */
+    label: string;
+    palettes: readonly Palette[];
+};
+/** The whole carousel, plus the page it opens on. */
+export type PaletteCarousel = {
+    groups: PaletteGroup[];
+    activeKey: string;
+};
+/** The key of the page that is never a framework's and never hidden. */
+export declare const BASE_PALETTE_KEY = "default";
+/**
+ * Which framework this element belongs to, read off the document.
+ *
+ * Three tiers, checked in order:
+ *
+ * 1. **Its own role's namespace.** A role id is `<framework>:<role>`, so a
+ *    Wardley component says `wardley` and a Wardley map says it too — boards
+ *    carry roles like everything else.
+ * 2. **For a connector, its ends.** A link is drawn between artefacts and
+ *    belongs to what it links; a plain connector stamps no role of its own.
+ *    Both ends must agree, otherwise the link crosses two notations and the
+ *    board below gets the last word.
+ * 3. **The smallest board that contains it.** A native shape dropped on a
+ *    Wardley map is being used as part of that map, whatever it stamps.
+ *
+ * `undefined` — a neutral element on the bare canvas — means "no framework",
+ * and the carousel then simply opens on the base palette.
+ */
+export declare function frameworkOfElement(gfx: GfxController, model: GfxModel): FrameworkId | undefined;
+/**
+ * The framework a whole selection belongs to — the one they all share, or
+ * `undefined` as soon as two of them disagree. A picker serving a mixed
+ * selection has no framework of origin to open on, so it opens on the base
+ * palette, which is true of every element in it.
+ */
+export declare function frameworkOfSelection(gfx: GfxController, models: readonly GfxModel[]): FrameworkId | undefined;
+/**
+ * The carousel a contextual toolbar hands its colour picker.
+ *
+ * The base palette is page one and is ALWAYS there (DESIGN.md, "The Coexisting
+ * Palettes Rule"); the frameworks whose tooling is on follow, in
+ * {@link FRAMEWORK_IDS} order so the pages read the same way on every board.
+ * `activeKey` is the framework of the selection when that framework is on the
+ * carousel, else the base palette.
+ */
+export declare function frameworkPaletteGroups(std: BlockStdScope, models: readonly GfxModel[], basePalettes: readonly Palette[]): PaletteCarousel;

package/dist/_pkgs/affine-components/color-picker/framework-palette.js

@@ -0,0 +1,177 @@
+/**
+ * The framework palettes a colour picker offers as a CAROUSEL, and the rule
+ * that decides which page it opens on (`docs/adr/0027`).
+ *
+ * Three pieces, in dependency order:
+ *
+ * 1. **The seam** — {@link FrameworkPaletteExtension}, registered from a
+ *    framework's FLAG-GATED view extension. Offering hues is TOOLING, so a
+ *    framework switched off disappears from the carousel while every colour it
+ *    ever wrote stays exactly where it is (`docs/adr/0009`).
+ * 2. **The resolver** — {@link frameworkOfElement}: which framework a selected
+ *    element belongs to, from what the document already says.
+ * 3. **The builder** — {@link frameworkPaletteGroups}: the carousel a toolbar
+ *    hands the picker, base palette first and never hidden (DESIGN.md, "The
+ *    Coexisting Palettes Rule").
+ *
+ * Nothing here is written to a document: a picked swatch is still a plain
+ * stored colour value, and `packages/affine/model` is untouched.
+ */
+import { ConnectorElementModel, FrameworkBackgroundElementModel, } from '../../affine-model/index.js';
+import { translateKey, } from '../../affine-shared/services/index.js';
+import { createIdentifier } from '../../global/di/index.js';
+import { FRAMEWORK_IDS, frameworkOfRole, } from '../../std/index.js';
+import { GfxControllerIdentifier, } from '../../std/gfx/index.js';
+import { PALETTE_GROUP_DEFAULT } from '../translations.js';
+/**
+ * A framework registers its palette here, and nothing else registers one.
+ * Multi-instance, keyed by {@link FrameworkPalette.framework}, exactly like
+ * `TemplateCategoryIdentifier` (`gfx/template/src/contribute.ts`): two
+ * extensions claiming the same framework collide at set-up
+ * (`DuplicateServiceDefinitionError`) rather than showing the page twice.
+ */
+export const FrameworkPaletteIdentifier = createIdentifier('FrameworkPalette');
+/**
+ * Register a framework's palette. Call it from `setup()` of the FLAG-GATED
+ * view extension, beside the senior tool:
+ *
+ * ```ts
+ * context.register(FrameworkPaletteExtension(WARDLEY_FRAMEWORK_PALETTE));
+ * ```
+ */
+export function FrameworkPaletteExtension(...palettes) {
+    return {
+        setup: di => {
+            for (const palette of palettes) {
+                di.addImpl(FrameworkPaletteIdentifier(palette.framework), () => palette);
+            }
+        },
+    };
+}
+/** The key of the page that is never a framework's and never hidden. */
+export const BASE_PALETTE_KEY = 'default';
+/** The role an element carries, for the models that can carry one. */
+function roleOf(model) {
+    return model.role;
+}
+/** Width × height of an element's bound — how "smallest board" is measured. */
+function area(model) {
+    const { w, h } = model.elementBound;
+    return w * h;
+}
+/**
+ * The smallest framework board whose bound CONTAINS this element's.
+ *
+ * Smallest, so a C4 container boundary drawn inside a C4 board — or any board
+ * nested in another — wins over the sheet it sits on: the nearer frame is the
+ * one an author is working in. A board never answers about itself.
+ */
+function containingBoard(gfx, model) {
+    const bound = model.elementBound;
+    let best;
+    for (const element of gfx.surface?.elementModels ?? []) {
+        if (!(element instanceof FrameworkBackgroundElementModel))
+            continue;
+        if (element.id === model.id)
+            continue;
+        if (!element.elementBound.contains(bound))
+            continue;
+        if (!best || area(element) < area(best))
+            best = element;
+    }
+    return best;
+}
+/**
+ * A node's framework: what it says about itself, else what it was dropped on.
+ *
+ * Kept apart from {@link frameworkOfElement} so a connector's endpoints are
+ * resolved without recursing back into the connector branch.
+ */
+function frameworkOfNode(gfx, model) {
+    const own = frameworkOfRole(roleOf(model));
+    if (own)
+        return own;
+    const board = containingBoard(gfx, model);
+    return board ? frameworkOfRole(roleOf(board)) : undefined;
+}
+/** The single value shared by every item, or `undefined` if they disagree. */
+function unanimous(values) {
+    return new Set(values).size === 1 ? values[0] : undefined;
+}
+/**
+ * Which framework this element belongs to, read off the document.
+ *
+ * Three tiers, checked in order:
+ *
+ * 1. **Its own role's namespace.** A role id is `<framework>:<role>`, so a
+ *    Wardley component says `wardley` and a Wardley map says it too — boards
+ *    carry roles like everything else.
+ * 2. **For a connector, its ends.** A link is drawn between artefacts and
+ *    belongs to what it links; a plain connector stamps no role of its own.
+ *    Both ends must agree, otherwise the link crosses two notations and the
+ *    board below gets the last word.
+ * 3. **The smallest board that contains it.** A native shape dropped on a
+ *    Wardley map is being used as part of that map, whatever it stamps.
+ *
+ * `undefined` — a neutral element on the bare canvas — means "no framework",
+ * and the carousel then simply opens on the base palette.
+ */
+export function frameworkOfElement(gfx, model) {
+    const own = frameworkOfRole(roleOf(model));
+    if (own)
+        return own;
+    if (model instanceof ConnectorElementModel) {
+        const ends = [model.source?.id, model.target?.id]
+            .map(id => (id ? gfx.getElementById(id) : null))
+            .filter((end) => !!end)
+            .map(end => frameworkOfNode(gfx, end))
+            .filter((id) => !!id);
+        const fromEnds = unanimous(ends);
+        if (fromEnds)
+            return fromEnds;
+    }
+    const board = containingBoard(gfx, model);
+    return board ? frameworkOfRole(roleOf(board)) : undefined;
+}
+/**
+ * The framework a whole selection belongs to — the one they all share, or
+ * `undefined` as soon as two of them disagree. A picker serving a mixed
+ * selection has no framework of origin to open on, so it opens on the base
+ * palette, which is true of every element in it.
+ */
+export function frameworkOfSelection(gfx, models) {
+    if (!models.length)
+        return undefined;
+    return unanimous(models.map(model => frameworkOfElement(gfx, model)));
+}
+/**
+ * The carousel a contextual toolbar hands its colour picker.
+ *
+ * The base palette is page one and is ALWAYS there (DESIGN.md, "The Coexisting
+ * Palettes Rule"); the frameworks whose tooling is on follow, in
+ * {@link FRAMEWORK_IDS} order so the pages read the same way on every board.
+ * `activeKey` is the framework of the selection when that framework is on the
+ * carousel, else the base palette.
+ */
+export function frameworkPaletteGroups(std, models, basePalettes) {
+    const contributed = [
+        ...std.provider.getAll(FrameworkPaletteIdentifier).values(),
+    ].sort((a, b) => FRAMEWORK_IDS.indexOf(a.framework) - FRAMEWORK_IDS.indexOf(b.framework));
+    const groups = [
+        {
+            key: BASE_PALETTE_KEY,
+            label: translateKey(std, ...PALETTE_GROUP_DEFAULT),
+            palettes: basePalettes,
+        },
+        ...contributed.map(palette => ({
+            key: palette.framework,
+            label: translateKey(std, ...palette.labelWording),
+            palettes: palette.palettes,
+        })),
+    ];
+    const origin = frameworkOfSelection(std.get(GfxControllerIdentifier), models);
+    const activeKey = groups.some(group => group.key === origin)
+        ? origin
+        : BASE_PALETTE_KEY;
+    return { groups, activeKey };
+}

package/dist/_pkgs/affine-components/color-picker/index.d.ts

@@ -5,6 +5,8 @@ import { EdgelessColorCustomButton } from './custom-button.js';
 export * from './button.js';
 export * from './color-panel.js';
 export * from './color-picker.js';
+export * from './framework-palette.js';
+export * from './palette-carousel.js';
 export * from './types.js';
 export * from './utils.js';
 export declare function effects(): void;

package/dist/_pkgs/affine-components/color-picker/index.js

@@ -5,6 +5,8 @@ import { EdgelessColorCustomButton } from './custom-button.js';
 export * from './button.js';
 export * from './color-panel.js';
 export * from './color-picker.js';
+export * from './framework-palette.js';
+export * from './palette-carousel.js';
 export * from './types.js';
 export * from './utils.js';
 export function effects() {

package/dist/_pkgs/affine-components/color-picker/palette-carousel.d.ts

@@ -0,0 +1,85 @@
+/**
+ * The palette header a colour picker draws above its swatch grid when more than
+ * one palette is on offer (`docs/adr/0027`): the page's name, opening an inline
+ * list of every page IN PLACE of the grid, and a wheel over the panel paging
+ * like a carousel.
+ *
+ * A render helper and a stylesheet rather than a custom element: the two
+ * pickers that show it (`edgeless-color-picker-button` and
+ * `edgeless-shape-color-picker`) live in different shadow roots and already own
+ * their own `render()`, and a third element registered in `effects()` would buy
+ * nothing but a tag name.
+ *
+ * Everything here is driven by `click`, never by a default action.
+ * `editor-toolbar` cancels every `pointerdown` in its subtree — popper menus
+ * included — to keep the canvas selection and the focus where they are
+ * (`toolbar/toolbar.ts`), and a cancelled `pointerdown` suppresses the
+ * compatibility `mousedown` whose default action is the only thing that opens a
+ * native `<select>`. `click` survives that policy untouched, which is why the
+ * list is ours and not the platform's.
+ *
+ * The header is the PANEL'S TITLE, not a bar bolted on top of it: a compact,
+ * content-width trigger whose name starts on the very x the section labels
+ * ("Fill color", "Border color") and the swatch grid start on. Its hit area
+ * comes from padding cancelled by an equal negative margin, so the hover pill
+ * bleeds outward while the text itself stays on the panel's left grid line.
+ */
+import { ColorScheme } from '../../affine-model/index.js';
+import type { BlockStdScope } from '../../std/index.js';
+import { nothing, type TemplateResult } from 'lit';
+import type { PaletteGroup } from './framework-palette.js';
+/** Include in the host component's `static styles`. */
+export declare const paletteCarouselStyles: import("lit").CSSResult;
+/**
+ * Where the new page comes FROM. `settle` is "from nowhere in particular": the
+ * first paint of a panel, and the list closing on the page it opened on.
+ */
+export type PaletteCarouselDirection = 'next' | 'prev' | 'settle';
+type CarouselOptions = {
+    groups: readonly PaletteGroup[];
+    index: number;
+    onPage: (index: number, direction: PaletteCarouselDirection) => void;
+    /** Whether the inline list of pages is showing instead of the swatch grid. */
+    open?: boolean;
+    /** Where the page on screen came from, for the entry animation. */
+    direction?: PaletteCarouselDirection;
+};
+/**
+ * The wheel handler each host binds on its own PANEL container — the header and
+ * the swatch grids alike, because "the mouse has to be on the name" was the
+ * second half of the recette's failure.
+ *
+ * Wrap-around in both directions: the pages are a ring, not a list, and the
+ * base palette is always one of them. The direction is the wheel's own sign,
+ * never the index delta, so wrapping from the last page to the first still
+ * comes in from the right.
+ */
+export declare function paletteCarouselWheel(options: CarouselOptions): (e: WheelEvent) => void;
+/**
+ * The swatches of the page on screen, wrapped so that paging slides them in.
+ * The host passes its own grid (both of them, in the shape picker, each in its
+ * own wrapper — same key, same timing, so the two move together).
+ *
+ * `keyed` is the whole mechanism: the wrapper is torn down and rebuilt on a
+ * page change, which restarts the CSS animation and, by the same token, cancels
+ * the one in flight. No JS animation, nothing to queue, and the swatches stay
+ * clickable throughout (a CSS animation never takes the pointer).
+ */
+export declare function paletteCarouselPage(options: {
+    groups: readonly PaletteGroup[];
+    index: number;
+    direction?: PaletteCarouselDirection;
+}, content: TemplateResult): import("lit-html/directive.js").DirectiveResult<typeof import("lit-html/directives/keyed.js").Keyed>;
+/**
+ * The header row — and, when {@link CarouselOptions.open} is set, the list of
+ * pages the host draws INSTEAD of its swatch grid. `nothing` when there is
+ * nothing to page through, which is what every call site that passes no groups
+ * at all gets, so a picker with one palette renders exactly as it did before
+ * this existed.
+ */
+export declare function renderPaletteCarousel(options: CarouselOptions & {
+    onToggle: (open: boolean) => void;
+    std?: BlockStdScope;
+    theme?: ColorScheme;
+}): TemplateResult | typeof nothing;
+export {};