@formicoidea/labre-core 0.31.0 → 0.32.0

package/dist/_pkgs/affine-block-surface/framework-background/labels.js

@@ -0,0 +1,117 @@
+import { backgroundPlot, backgroundPoint } from './def.js';
+/**
+ * The words a label actually says.
+ *
+ * The user's own text wins over the vocabulary, and the vocabulary over the
+ * shipped default — so a framework can be fully i18n'd while still letting the
+ * user rename an axis on the canvas.
+ *
+ * i18n goes through the house seam (`TranslationProvider` /
+ * {@link translateKey}), which the host injects and the library never bundles.
+ * A key the catalogue does not know falls back to the wording the declaration
+ * ships, and a declaration that ships none shows the RAW KEY — ugly on purpose,
+ * exactly as everywhere else in the library: a dangling key is a bug the host
+ * must see, not an excuse for us to invent somebody else's wording.
+ */
+export function backgroundLabelText(source, model, translation) {
+    if (source.prop !== undefined) {
+        const value = model[source.prop];
+        if (value !== undefined && value !== null)
+            return String(value);
+    }
+    if (source.labelKey !== undefined) {
+        const resolved = translation?.t(source.labelKey);
+        if (resolved !== undefined && resolved !== '')
+            return resolved;
+        return source.fallback ?? source.labelKey;
+    }
+    return source.fallback ?? '';
+}
+/** Whether a `visibleProp` gate is open. No gate means always drawn. */
+export function backgroundVisible(visibleProp, model) {
+    return visibleProp === undefined ? true : Boolean(model[visibleProp]);
+}
+/** Rough per-character advance — only used to size generous hit boxes. */
+const approxTextWidth = (text, fontSize) => Math.max(fontSize, text.length * fontSize * 0.6);
+/** Padding so double-clicking a label is forgiving. */
+const HIT_PAD = 6;
+/**
+ * Every text of a declaration, in PAINTING ORDER: zone labels, then each axis'
+ * title followed by its end labels.
+ *
+ * One walk, used by both the renderer and the hit tester, so a label can never
+ * be drawn in one place and clicked in another.
+ */
+export function backgroundTexts(def) {
+    const texts = [];
+    for (const zone of def.zones ?? []) {
+        if (zone.label)
+            texts.push(zone.label);
+    }
+    for (const axis of def.axes ?? []) {
+        // The title shares the axis' visibility; the end labels have their own.
+        if (axis.title) {
+            texts.push(axis.visibleProp === undefined
+                ? axis.title
+                : { ...axis.title, visibleProp: axis.visibleProp });
+        }
+        texts.push(...(axis.endLabels ?? []));
+    }
+    return texts;
+}
+/**
+ * Clickable boxes of every VISIBLE, EDITABLE label — those the declaration
+ * binds to a model prop; a label that only names an i18n key is vocabulary,
+ * not user text, and is not offered for editing.
+ *
+ * Positions come from the same declaration the renderer paints from, so the
+ * boxes track the drawn text by construction.
+ */
+export function backgroundLabelHits(def, model, w, h, translation) {
+    const plot = backgroundPlot(def, w, h);
+    const hits = [];
+    for (const text of backgroundTexts(def)) {
+        if (text.prop === undefined)
+            continue;
+        if (!backgroundVisible(text.visibleProp, model))
+            continue;
+        const words = backgroundLabelText(text, model, translation);
+        const size = text.style.size;
+        const tw = approxTextWidth(words, size);
+        const [ax, ay] = backgroundPoint(text.anchor, plot);
+        if (text.vertical) {
+            hits.push({
+                id: text.id,
+                prop: text.prop,
+                text: words,
+                minX: ax - size - HIT_PAD,
+                maxX: ax + size * 0.4 + HIT_PAD,
+                minY: ay - tw / 2 - HIT_PAD,
+                maxY: ay + tw / 2 + HIT_PAD,
+            });
+            continue;
+        }
+        const align = text.align ?? 'left';
+        const minX = align === 'right' ? ax - tw : align === 'center' ? ax - tw / 2 : ax;
+        const maxX = align === 'right' ? ax : align === 'center' ? ax + tw / 2 : ax + tw;
+        hits.push({
+            id: text.id,
+            prop: text.prop,
+            text: words,
+            minX: minX - HIT_PAD,
+            maxX: maxX + HIT_PAD,
+            minY: ay - size - HIT_PAD,
+            maxY: ay + size * 0.3 + HIT_PAD,
+        });
+    }
+    return hits;
+}
+/** First label whose padded box contains the element-local point, or null. */
+export function hitTestBackgroundLabel(hits, lx, ly) {
+    for (const hit of hits) {
+        if (lx >= hit.minX && lx <= hit.maxX && ly >= hit.minY && ly <= hit.maxY) {
+            return hit;
+        }
+    }
+    return null;
+}

package/dist/_pkgs/affine-block-surface/framework-background/renderer.d.ts

@@ -0,0 +1,8 @@
+import type { GfxPrimitiveElementModel } from '../../std/gfx/index.js';
+import type { ElementRenderer } from '../renderer/elements/index.js';
+import type { FrameworkBackgroundDef } from './def.js';
+/**
+ * Build the canvas renderer of one declaration. Pure: the same declaration
+ * always paints the same picture for the same model and size.
+ */
+export declare function createFrameworkBackgroundRenderer<T extends GfxPrimitiveElementModel>(def: FrameworkBackgroundDef): ElementRenderer<T>;

package/dist/_pkgs/affine-block-surface/framework-background/renderer.js

@@ -0,0 +1,238 @@
+import { TranslationProvider } from '../../affine-shared/services/index.js';
+import { backgroundColor, backgroundPlot, backgroundPoint, BROKEN_BACKGROUND_COLOR, DEFAULT_BACKGROUND_SURFACE, warnBrokenBackgroundColor, } from './def.js';
+import { backgroundLabelText, backgroundTexts, backgroundVisible, } from './labels.js';
+/**
+ * The framework-background PRIMITIVE (PF2.1): one renderer, driven entirely by
+ * a {@link FrameworkBackgroundDef}. A framework gets its background by
+ * declaring it — not one line of drawing code per framework.
+ *
+ * ## The painting pipeline
+ *
+ * Fixed, and the whole of it. Order is the only thing a declaration cannot
+ * change, because order is what makes two backgrounds look like the same
+ * product rather than two drawings:
+ *
+ * 1. the card — the element rectangle;
+ * 2. the washes, over the plot;
+ * 3. the zone tints;
+ * 4. the graduations of every axis;
+ * 5. the axis lines and their arrowheads;
+ * 6. every text — zone names, then per axis its title and its end labels.
+ *
+ * A declaration that says nothing but its size therefore paints a plain white
+ * rectangle: no axis, no zone, no decoration.
+ *
+ * ## Units
+ *
+ * Ratios scale with the element; everything beside them — margins, font sizes,
+ * stroke widths, label offsets — is FIXED model units, so the furniture stays
+ * legible however large the background is stretched. Only the plot interior
+ * moves.
+ */
+function roundRectPath(ctx, x, y, w, h, r) {
+    const rr = Math.min(r, w / 2, h / 2);
+    ctx.beginPath();
+    ctx.moveTo(x + rr, y);
+    ctx.arcTo(x + w, y, x + w, y + h, rr);
+    ctx.arcTo(x + w, y + h, x, y + h, rr);
+    ctx.arcTo(x, y + h, x, y, rr);
+    ctx.arcTo(x, y, x + w, y, rr);
+    ctx.closePath();
+}
+const HEX6 = /^#[0-9a-fA-F]{6}$/;
+/**
+ * A wash stop, as `rgba(...)`.
+ *
+ * Only `#rrggbb` can carry an alpha this way. Anything else — a named CSS
+ * colour, a short hex, a palette entry that did not resolve — used to reach
+ * `parseInt` and produce `rgba(NaN,NaN,NaN,0.4)`, which paints nothing at all
+ * and says nothing about why. It now warns and paints
+ * {@link BROKEN_BACKGROUND_COLOR}.
+ */
+function rgba(hex, alpha) {
+    if (!HEX6.test(hex)) {
+        warnBrokenBackgroundColor(`wash colour "${hex}" is not a #rrggbb literal, so it cannot take an alpha`);
+        hex = BROKEN_BACKGROUND_COLOR;
+    }
+    const r = parseInt(hex.slice(1, 3), 16);
+    const g = parseInt(hex.slice(3, 5), 16);
+    const b = parseInt(hex.slice(5, 7), 16);
+    return `rgba(${r},${g},${b},${alpha})`;
+}
+function fontOf(style, fallbackFamily) {
+    const italic = style.italic ? 'italic ' : '';
+    const weight = style.weight ? `${style.weight} ` : '';
+    return `${italic}${weight}${style.size}px ${style.family ?? fallbackFamily}`;
+}
+/** The family a declaration that names none falls back to. */
+const DEFAULT_FONT_FAMILY = 'Inter, sans-serif';
+/**
+ * Build the canvas renderer of one declaration. Pure: the same declaration
+ * always paints the same picture for the same model and size.
+ */
+export function createFrameworkBackgroundRenderer(def) {
+    const palette = def.chrome?.palette;
+    const family = def.chrome?.fontFamily ?? DEFAULT_FONT_FAMILY;
+    const surface = def.chrome?.surface ?? DEFAULT_BACKGROUND_SURFACE;
+    const color = (c) => backgroundColor(c, palette);
+    const texts = backgroundTexts(def);
+    return (model, ctx, matrix, renderer) => {
+        const props = model;
+        const visible = (prop) => backgroundVisible(prop, props);
+        // The host's catalogue, resolved once per paint. Absent in a bare unit
+        // test (the renderer is called with three arguments) and absent in a host
+        // that ships no locale pack — both fall back to the declared wording.
+        const translation = renderer?.std.getOptional(TranslationProvider) ?? null;
+        const [, , w, h] = model.deserializedXYWH;
+        const cx = w / 2;
+        const cy = h / 2;
+        ctx.setTransform(matrix
+            .translateSelf(cx, cy)
+            .rotateSelf(model.rotate)
+            .translateSelf(-cx, -cy));
+        const plot = backgroundPlot(def, w, h);
+        const { x0, y0, x1, y1 } = plot;
+        const pw = plot.width;
+        const ph = plot.height;
+        const line = (ax, ay, bx, by) => {
+            ctx.beginPath();
+            ctx.moveTo(ax, ay);
+            ctx.lineTo(bx, by);
+            ctx.stroke();
+        };
+        const drawText = (words, ax, ay, style, align, vertical) => {
+            if (!words)
+                return;
+            if (vertical) {
+                ctx.save();
+                ctx.translate(ax, ay);
+                ctx.rotate(-Math.PI / 2);
+                ctx.font = fontOf(style, family);
+                ctx.fillStyle = color(style.color);
+                ctx.textAlign = align ?? 'center';
+                ctx.textBaseline = 'alphabetic';
+                ctx.fillText(words, 0, 0);
+                ctx.restore();
+                return;
+            }
+            ctx.font = fontOf(style, family);
+            ctx.fillStyle = color(style.color);
+            ctx.textAlign = align ?? 'left';
+            ctx.textBaseline = 'alphabetic';
+            ctx.fillText(words, ax, ay);
+        };
+        // ── 1. The card ─────────────────────────────────────────────────────
+        const border = surface.border;
+        const inset = border ? border.width / 2 : 0;
+        roundRectPath(ctx, inset, inset, w - inset * 2, h - inset * 2, border?.radius ?? 0);
+        if (surface.fill) {
+            ctx.fillStyle = color(surface.fill);
+            ctx.fill();
+        }
+        if (border) {
+            ctx.strokeStyle = color(border.color);
+            ctx.lineWidth = border.width;
+            ctx.stroke();
+        }
+        // ── 2. Washes over the plot ─────────────────────────────────────────
+        const washes = def.chrome?.washes;
+        if (washes?.length) {
+            const variant = def.variantProp === undefined ? undefined : props[def.variantProp];
+            for (const wash of washes) {
+                if (wash.variants && !wash.variants.includes(String(variant)))
+                    continue;
+                if (!visible(wash.visibleProp))
+                    continue;
+                const gradient = ctx.createLinearGradient(x0, 0, x1, 0);
+                const hex = color(wash.color);
+                for (const [offset, alpha] of wash.stops) {
+                    gradient.addColorStop(offset, rgba(hex, alpha));
+                }
+                ctx.fillStyle = gradient;
+                ctx.fillRect(x0, y0, pw, ph);
+            }
+        }
+        // ── 3. Zone tints ───────────────────────────────────────────────────
+        for (const zone of def.zones ?? []) {
+            if (!zone.fill)
+                continue;
+            if (!visible(zone.fillVisibleProp))
+                continue;
+            ctx.fillStyle = color(zone.fill);
+            ctx.fillRect(x0 + zone.rect.x * pw, y0 + zone.rect.y * ph, zone.rect.w * pw, zone.rect.h * ph);
+        }
+        // ── 4. Graduations ──────────────────────────────────────────────────
+        for (const axis of def.axes ?? []) {
+            const graduations = axis.ticks;
+            if (!graduations || !visible(graduations.visibleProp))
+                continue;
+            ctx.strokeStyle = color(graduations.stroke.color);
+            ctx.lineWidth = graduations.stroke.width;
+            ctx.setLineDash(graduations.stroke.dash ? [...graduations.stroke.dash] : []);
+            for (const tick of graduations.ticks) {
+                if (axis.orientation === 'horizontal') {
+                    const tx = x0 + tick.at * pw;
+                    line(tx, y0, tx, y1);
+                }
+                else {
+                    // A vertical axis is graduated from the BOTTOM up: `at: 0` is the
+                    // origin of the value it measures, not the top of the screen.
+                    const ty = y1 - tick.at * ph;
+                    line(x0, ty, x1, ty);
+                }
+            }
+            ctx.setLineDash([]);
+        }
+        // ── 5. Axis lines and arrowheads ────────────────────────────────────
+        for (const axis of def.axes ?? []) {
+            if (!visible(axis.visibleProp))
+                continue;
+            drawAxis(ctx, axis, plot, color, line);
+        }
+        // ── 6. Every text, in declaration order ─────────────────────────────
+        for (const text of texts) {
+            if (!visible(text.visibleProp))
+                continue;
+            const [tx, ty] = backgroundPoint(text.anchor, plot);
+            drawText(backgroundLabelText(text, props, translation), tx, ty, text.style, text.align, text.vertical === true);
+        }
+    };
+}
+/**
+ * One axis: its line, stopping one unit inside the base of each arrowhead so
+ * the stroke never pokes past the tip at any zoom, then the filled triangles.
+ */
+function drawAxis(ctx, axis, plot, color, line) {
+    const { x0, y0, x1, y1 } = plot;
+    const arrow = axis.arrow ?? 'none';
+    const a = axis.arrowSize ?? 10;
+    const forward = arrow === 'forward' || arrow === 'both';
+    const backward = arrow === 'backward' || arrow === 'both';
+    ctx.strokeStyle = color(axis.stroke.color);
+    ctx.lineWidth = axis.stroke.width;
+    ctx.fillStyle = color(axis.stroke.color);
+    const triangle = (tipX, tipY, baseX, baseY, spreadX, spreadY) => {
+        ctx.beginPath();
+        ctx.moveTo(tipX, tipY);
+        ctx.lineTo(baseX - spreadX, baseY - spreadY);
+        ctx.lineTo(baseX + spreadX, baseY + spreadY);
+        ctx.closePath();
+        ctx.fill();
+    };
+    if (axis.orientation === 'horizontal') {
+        const y = y0 + axis.at * plot.height;
+        line(backward ? x0 + a - 1 : x0, y, forward ? x1 - a + 1 : x1, y);
+        if (forward)
+            triangle(x1, y, x1 - a, y, 0, a / 2);
+        if (backward)
+            triangle(x0, y, x0 + a, y, 0, a / 2);
+        return;
+    }
+    // Vertical: `forward` points UP — where a reader expects "more" to be.
+    const x = x0 + axis.at * plot.width;
+    line(x, backward ? y1 - a + 1 : y1, x, forward ? y0 + a - 1 : y0);
+    if (forward)
+        triangle(x, y0, x, y0 + a, a / 2, 0);
+    if (backward)
+        triangle(x, y1, x, y1 - a, a / 2, 0);
+}

package/dist/_pkgs/affine-block-surface/index.d.ts

@@ -11,6 +11,7 @@ export { ToolOverlay } from './renderer/tool-overlay.js';
 import { getFontFacesByFontFamily, wrapFontFamily } from './utils/font.js';
 export * from './adapters/index.js';
 export * from './extensions/index.js';
+export * from './framework-background/index.js';
 export type { SurfaceContext } from './surface-block.js';
 export { SurfaceBlockComponent } from './surface-block.js';
 export { SurfaceBlockModel, SurfaceBlockSchema, SurfaceBlockSchemaExtension, } from './surface-model.js';

package/dist/_pkgs/affine-block-surface/index.js

@@ -12,6 +12,7 @@ export { ToolOverlay } from './renderer/tool-overlay.js';
 import { getFontFaces, getFontFacesByFontFamily, isSameFontFamily, wrapFontFamily, } from './utils/font.js';
 export * from './adapters/index.js';
 export * from './extensions/index.js';
+export * from './framework-background/index.js';
 export { SurfaceBlockComponent } from './surface-block.js';
 export { SurfaceBlockModel, SurfaceBlockSchema, SurfaceBlockSchemaExtension, } from './surface-model.js';
 export { SurfaceBlockTransformer } from './surface-transformer.js';

package/dist/_pkgs/affine-block-surface/renderer/canvas-renderer.d.ts

@@ -1,7 +1,7 @@
 import { type Color, ColorScheme } from '../../affine-model/index.js';
-import type { IBound } from '../../global/gfx/index.js';
+import { type IBound } from '../../global/gfx/index.js';
 import type { BlockStdScope } from '../../std/index.js';
-import type { GridManager, LayerManager, SurfaceBlockModel, Viewport } from '../../std/gfx/index.js';
+import type { GfxLocalElementModel, GridManager, LayerManager, SurfaceBlockModel, Viewport } from '../../std/gfx/index.js';
 import { Subject } from 'rxjs';
 import type { SurfaceElementModel } from '../element-model/base.js';
 import type { Overlay } from './overlay.js';
@@ -22,13 +22,66 @@ type RendererOptions = {
     gridManager: GridManager;
     surfaceModel: SurfaceBlockModel;
 };
+export type CanvasRenderPassMetrics = {
+    overlayCount: number;
+    placeholderElementCount: number;
+    renderByBoundCallCount: number;
+    renderedElementCount: number;
+    visibleElementCount: number;
+};
+export type CanvasMemorySnapshot = {
+    bytes: number;
+    datasetLayerId: string | null;
+    height: number;
+    kind: 'main' | 'stacking';
+    width: number;
+    zIndex: string;
+};
+export type CanvasRendererDebugMetrics = {
+    canvasLayerCount: number;
+    canvasMemoryBytes: number;
+    canvasMemorySnapshots: CanvasMemorySnapshot[];
+    canvasMemoryMegabytes: number;
+    canvasPixelCount: number;
+    coalescedRefreshCount: number;
+    dirtyLayerRenderCount: number;
+    fallbackElementCount: number;
+    lastRenderDurationMs: number;
+    lastRenderMetrics: CanvasRenderPassMetrics;
+    maxRenderDurationMs: number;
+    pooledStackingCanvasCount: number;
+    refreshCount: number;
+    renderCount: number;
+    stackingCanvasCount: number;
+    totalLayerCount: number;
+    totalRenderDurationMs: number;
+    visibleStackingCanvasCount: number;
+};
+type RefreshTarget = {
+    type: 'all';
+} | {
+    type: 'main';
+} | {
+    type: 'element';
+    element: SurfaceElementModel | GfxLocalElementModel;
+} | {
+    type: 'elements';
+    elements: Array<SurfaceElementModel | GfxLocalElementModel>;
+};
 export declare class CanvasRenderer {
     private _container;
     private readonly _disposables;
+    private readonly _gfx;
     private readonly _turboEnabled;
     private readonly _overlays;
     private _refreshRafId;
     private _stackingCanvas;
+    private readonly _stackingCanvasPool;
+    private readonly _stackingCanvasState;
+    private readonly _dirtyStackingCanvasIndexes;
+    private _mainCanvasDirty;
+    private _needsFullRender;
+    private _debugMetrics;
     canvas: HTMLCanvasElement;
     ctx: CanvasRenderingContext2D;
     std: BlockStdScope;
@@ -52,9 +105,20 @@ export declare class CanvasRenderer {
      * It is not recommended to set width and height to 100%.
      */
     private _canvasSizeUpdater;
+    private _applyStackingCanvasLayout;
+    private _clampBoundToViewport;
+    private _createCanvasForLayer;
+    private _findLayerIndexByElement;
+    private _getLayerRenderBound;
+    private _getResolvedStackingCanvasBound;
+    private _invalidate;
+    private _resetPooledCanvas;
     private _initStackingCanvas;
     private _initViewport;
+    private _createRenderPassStats;
+    private _getCanvasMemorySnapshots;
     private _render;
+    private _lastDebugSnapshot;
     private _renderByBound;
     private _resetSize;
     private _watchSurface;
@@ -70,7 +134,9 @@ export declare class CanvasRenderer {
     getColorScheme(): ColorScheme;
     getColorValue(color: Color, fallback?: Color, real?: boolean): string;
     getPropertyValue(property: string): string;
-    refresh(): void;
+    getDebugMetrics(): CanvasRendererDebugMetrics;
+    resetDebugMetrics(): void;
+    refresh(target?: RefreshTarget): void;
     removeOverlay(overlay: Overlay): void;
 }
 export {};