@zoneflow/renderer-dom 0.0.11 → 0.0.13

package/dist/engines/componentLayoutEngine.d.ts

@@ -1,2 +1,26 @@
-import type { ComponentLayoutEngine } from "../types";
+import type { Zone } from "@zoneflow/core";
+import type { BuiltInZoneSlotName, ComponentLayoutEngine, DensityLevel } from "../types";
 export declare const defaultComponentLayoutEngine: ComponentLayoutEngine;
+export type ZoneSlotPlacement = {
+    kind: "top";
+    height: number;
+    widthCap?: number;
+} | {
+    kind: "bottom";
+    height: number;
+};
+export type ZoneSlotDensityRule = (params: {
+    density: DensityLevel;
+    zone: Zone;
+}) => boolean;
+export type ExtensibleZoneSlot = {
+    name: string;
+    placement: ZoneSlotPlacement;
+    shouldRender?: ZoneSlotDensityRule;
+};
+export type ExtensibleComponentLayoutConfig = {
+    extraSlots?: ExtensibleZoneSlot[];
+    disabledBuiltIns?: BuiltInZoneSlotName[];
+    builtInDensityOverride?: Partial<Record<BuiltInZoneSlotName, ZoneSlotDensityRule>>;
+};
+export declare function createExtensibleComponentLayoutEngine(config?: ExtensibleComponentLayoutConfig): ComponentLayoutEngine;

package/dist/engines/componentLayoutEngine.js

@@ -198,3 +198,147 @@ export const defaultComponentLayoutEngine = {
         };
     },
 };
+const DEFAULT_BUILT_IN_DENSITY = {
+    title: ({ density }) => density === "mid" || density === "near" || density === "detail",
+    type: ({ density }) => density === "near" || density === "detail",
+    badge: ({ density }) => density === "near" || density === "detail",
+    body: ({ density }) => density === "detail",
+    footer: ({ density }) => density === "detail",
+};
+const DEFAULT_EXTRA_DENSITY = ({ density }) => density === "near" || density === "detail";
+function buildBuiltInDescriptor(name, base, disabled, overrides) {
+    if (disabled.has(name))
+        return null;
+    return {
+        name,
+        height: base.height,
+        widthCap: base.widthCap,
+        shouldRender: overrides[name] ?? DEFAULT_BUILT_IN_DENSITY[name],
+    };
+}
+function computeExtensibleZoneSlots(params) {
+    const { rect, density, zone, config } = params;
+    const slots = {};
+    const disabled = new Set(config.disabledBuiltIns ?? []);
+    const overrides = config.builtInDensityOverride ?? {};
+    const titleDesc = buildBuiltInDescriptor("title", { height: ZONE_TITLE_HEIGHT }, disabled, overrides);
+    const typeDesc = buildBuiltInDescriptor("type", { height: ZONE_TYPE_HEIGHT }, disabled, overrides);
+    const badgeDesc = buildBuiltInDescriptor("badge", { height: ZONE_BADGE_HEIGHT, widthCap: 96 }, disabled, overrides);
+    const footerDesc = buildBuiltInDescriptor("footer", { height: ZONE_FOOTER_HEIGHT }, disabled, overrides);
+    const bodyDesc = buildBuiltInDescriptor("body", { height: ZONE_BODY_MIN_HEIGHT }, disabled, overrides);
+    const extraTops = [];
+    const extraBottoms = [];
+    for (const slot of config.extraSlots ?? []) {
+        const desc = {
+            name: slot.name,
+            height: slot.placement.height,
+            widthCap: slot.placement.kind === "top" ? slot.placement.widthCap : undefined,
+            shouldRender: slot.shouldRender ?? DEFAULT_EXTRA_DENSITY,
+        };
+        if (slot.placement.kind === "top")
+            extraTops.push(desc);
+        else
+            extraBottoms.push(desc);
+    }
+    let content = insetRect(rect, ZONE_PADDING_X, ZONE_PADDING_Y);
+    const topQueue = [
+        ...(titleDesc ? [titleDesc] : []),
+        ...(typeDesc ? [typeDesc] : []),
+        ...(badgeDesc ? [badgeDesc] : []),
+        ...extraTops,
+    ];
+    for (const desc of topQueue) {
+        if (content.height <= 0)
+            break;
+        if (!desc.shouldRender({ density, zone }))
+            continue;
+        if (desc.widthCap !== undefined) {
+            const slotWidth = Math.min(desc.widthCap, content.width);
+            const slotHeight = Math.min(desc.height, content.height);
+            slots[desc.name] = {
+                x: content.x,
+                y: content.y,
+                width: slotWidth,
+                height: slotHeight,
+            };
+            content = addTopGap({
+                x: content.x,
+                y: content.y + slotHeight,
+                width: content.width,
+                height: Math.max(0, content.height - desc.height),
+            }, ZONE_GAP_Y);
+        }
+        else {
+            const { slot, rest } = takeTop(content, desc.height);
+            slots[desc.name] = slot;
+            content = addTopGap(rest, ZONE_GAP_Y);
+        }
+    }
+    const bottomQueue = [
+        ...(footerDesc ? [footerDesc] : []),
+        ...extraBottoms,
+    ];
+    for (const desc of bottomQueue) {
+        if (content.height <= 0)
+            break;
+        if (!desc.shouldRender({ density, zone }))
+            continue;
+        const { slot, rest } = takeBottom(content, desc.height);
+        slots[desc.name] = slot;
+        content = rest;
+    }
+    if (bodyDesc &&
+        bodyDesc.shouldRender({ density, zone }) &&
+        content.width > 0 &&
+        content.height >= bodyDesc.height) {
+        slots[bodyDesc.name] = content;
+    }
+    return slots;
+}
+export function createExtensibleComponentLayoutEngine(config = {}) {
+    return {
+        compute(input) {
+            const { graphLayout, density, visibility } = input;
+            const zonesById = Object.fromEntries(Object.values(graphLayout.zonesById).map((zoneVisual) => {
+                const zoneVisibility = visibility.zoneVisibilityById[zoneVisual.zoneId];
+                const zoneDensity = density.zoneDensityById[zoneVisual.zoneId];
+                const slots = zoneVisibility?.shouldRenderBody !== false
+                    ? computeExtensibleZoneSlots({
+                        rect: zoneVisual.rect,
+                        density: zoneDensity,
+                        zone: zoneVisual.zone,
+                        config,
+                    })
+                    : {};
+                return [
+                    zoneVisual.zoneId,
+                    {
+                        zoneId: zoneVisual.zoneId,
+                        slots,
+                    },
+                ];
+            }));
+            const pathsById = Object.fromEntries(Object.values(graphLayout.pathsById).map((path) => {
+                const pathVisibility = visibility.pathVisibilityById[path.pathId];
+                const pathDensity = density.pathDensityById[path.pathId];
+                const slots = path.rect && pathVisibility?.shouldRenderNode
+                    ? computePathSlots({
+                        rect: path.rect,
+                        density: pathDensity,
+                    })
+                    : {};
+                return [
+                    path.pathId,
+                    {
+                        pathId: path.pathId,
+                        slots,
+                    },
+                ];
+            }));
+            return {
+                zonesById,
+                pathsById,
+            };
+        },
+    };
+}

package/dist/engines/drawEngine.js

@@ -3,6 +3,7 @@ import { getZoneDepth, isZoneInputEnabled, isZoneOutputEnabled, } from "@zoneflo
 import { appendEdgeFlowStyle, resolveCollapsedEdgeStroke, resolveDrawableEdgeSegments, resolveEdgeFlowMotion, } from "./edgeFlow";
 const SCENE_PADDING = 64;
 const RENDER_Z_INDEX = {
+    backgroundLayer: 0,
     zoneBase: 1,
     pathNode: 1,
     pathStatusBadge: 2,
@@ -21,11 +22,56 @@ function createEmptyMountRegistry() {
     return {
         zones: [],
         paths: [],
+        background: null,
     };
 }
 function clearHost(host) {
     host.innerHTML = "";
 }
+function positiveModulo(value, divisor) {
+    return ((value % divisor) + divisor) % divisor;
+}
+function createGridLayer(params) {
+    const { options, camera, theme } = params;
+    const worldSize = Math.max(options.size ?? 16, 2);
+    const majorEvery = Math.max(options.majorEvery ?? 4, 2);
+    const minorSize = worldSize * camera.zoom;
+    const majorSize = minorSize * majorEvery;
+    if (minorSize < 2)
+        return null;
+    const minorOffsetX = positiveModulo(camera.x, minorSize);
+    const minorOffsetY = positiveModulo(camera.y, minorSize);
+    const majorOffsetX = positiveModulo(camera.x, majorSize);
+    const majorOffsetY = positiveModulo(camera.y, majorSize);
+    const minorColor = options.color ?? "rgba(148, 163, 184, 0.10)";
+    const majorColor = options.majorColor ?? "rgba(148, 163, 184, 0.18)";
+    const grid = document.createElement("div");
+    applyStyles(grid, {
+        position: "absolute",
+        inset: "0",
+        pointerEvents: "none",
+        backgroundColor: options.backgroundColor ?? "transparent",
+        backgroundImage: [
+            `linear-gradient(to right, ${minorColor} 1px, transparent 1px)`,
+            `linear-gradient(to bottom, ${minorColor} 1px, transparent 1px)`,
+            `linear-gradient(to right, ${majorColor} 1px, transparent 1px)`,
+            `linear-gradient(to bottom, ${majorColor} 1px, transparent 1px)`,
+        ].join(", "),
+        backgroundSize: [
+            `${minorSize}px ${minorSize}px`,
+            `${minorSize}px ${minorSize}px`,
+            `${majorSize}px ${majorSize}px`,
+            `${majorSize}px ${majorSize}px`,
+        ].join(", "),
+        backgroundPosition: [
+            `${minorOffsetX}px ${minorOffsetY}px`,
+            `${minorOffsetX}px ${minorOffsetY}px`,
+            `${majorOffsetX}px ${majorOffsetY}px`,
+            `${majorOffsetX}px ${majorOffsetY}px`,
+        ].join(", "),
+    });
+    return grid;
+}
 function createIdSet(ids) {
     return new Set(ids ?? []);
 }
@@ -623,7 +669,9 @@ export const domDrawEngine = {
         });
         const sceneBounds = computeSceneBounds(input);
         const viewportRoot = document.createElement("div");
+        const worldBgRoot = document.createElement("div");
         const worldRoot = document.createElement("div");
+        const backgroundLayer = document.createElement("div");
         const edgeSvg = createSvgElement("svg");
         const zoneLayer = document.createElement("div");
         const pathLayer = document.createElement("div");
@@ -641,13 +689,25 @@ export const domDrawEngine = {
                 interactionHandlers?.onBackgroundClick?.();
             }
         });
+        const worldTransform = `translate(${camera.x - viewportInfo.effective.x}px, ${camera.y - viewportInfo.effective.y}px) scale(${camera.zoom})`;
+        applyStyles(worldBgRoot, {
+            position: "absolute",
+            left: "0",
+            top: "0",
+            width: `${sceneBounds.width}px`,
+            height: `${sceneBounds.height}px`,
+            transform: worldTransform,
+            transformOrigin: "0 0",
+            willChange: "transform",
+            pointerEvents: "none",
+        });
         applyStyles(worldRoot, {
             position: "absolute",
             left: "0",
             top: "0",
             width: `${sceneBounds.width}px`,
             height: `${sceneBounds.height}px`,
-            transform: `translate(${camera.x - viewportInfo.effective.x}px, ${camera.y - viewportInfo.effective.y}px) scale(${camera.zoom})`,
+            transform: worldTransform,
             transformOrigin: "0 0",
             willChange: "transform",
         });
@@ -664,6 +724,15 @@ export const domDrawEngine = {
             pointerEvents: "none",
             zIndex: RENDER_Z_INDEX.edgeLayer,
         });
+        applyStyles(backgroundLayer, {
+            position: "absolute",
+            left: "0",
+            top: "0",
+            width: `${sceneBounds.width}px`,
+            height: `${sceneBounds.height}px`,
+            zIndex: RENDER_Z_INDEX.backgroundLayer,
+            pointerEvents: "none",
+        });
         applyStyles(zoneLayer, {
             position: "absolute",
             left: "0",
@@ -671,6 +740,7 @@ export const domDrawEngine = {
             width: `${sceneBounds.width}px`,
             height: `${sceneBounds.height}px`,
             zIndex: RENDER_Z_INDEX.zoneLayer,
+            pointerEvents: "none",
         });
         applyStyles(pathLayer, {
             position: "absolute",
@@ -679,10 +749,35 @@ export const domDrawEngine = {
             width: `${sceneBounds.width}px`,
             height: `${sceneBounds.height}px`,
             zIndex: RENDER_Z_INDEX.pathLayer,
+            pointerEvents: "none",
         });
+        const backgroundContext = {
+            sceneBounds,
+            camera,
+            viewportInfo,
+            theme,
+        };
+        if (input.backgroundRenderer) {
+            input.backgroundRenderer(backgroundLayer, backgroundContext);
+        }
+        mounts.background = {
+            host: backgroundLayer,
+            context: backgroundContext,
+        };
+        worldBgRoot.appendChild(backgroundLayer);
         worldRoot.appendChild(edgeSvg);
         worldRoot.appendChild(zoneLayer);
         worldRoot.appendChild(pathLayer);
+        viewportRoot.appendChild(worldBgRoot);
+        if (input.gridOptions?.enabled) {
+            const gridLayer = createGridLayer({
+                options: input.gridOptions,
+                camera,
+                theme,
+            });
+            if (gridLayer)
+                viewportRoot.appendChild(gridLayer);
+        }
         viewportRoot.appendChild(worldRoot);
         host.appendChild(viewportRoot);
         drawEdges({

package/dist/renderer.js

@@ -69,7 +69,7 @@ export function createRenderer() {
         update(input) {
             if (!host)
                 return;
-            const { model, layoutModel, theme, textScale = "md", camera = DEFAULT_CAMERA, graphLayoutEngine = defaultGraphLayoutEngine, densityEngine = defaultDensityEngine, visibilityEngine = defaultVisibilityEngine, componentLayoutEngine = defaultComponentLayoutEngine, drawEngine = domDrawEngine, zoneComponentRenderers, pathComponentRenderers, interactionHandlers, exclusionState, debug, } = input;
+            const { model, layoutModel, theme, textScale = "md", camera = DEFAULT_CAMERA, graphLayoutEngine = defaultGraphLayoutEngine, densityEngine = defaultDensityEngine, visibilityEngine = defaultVisibilityEngine, componentLayoutEngine = defaultComponentLayoutEngine, drawEngine = domDrawEngine, zoneComponentRenderers, pathComponentRenderers, backgroundRenderer, gridOptions, interactionHandlers, exclusionState, debug, } = input;
             const mergedTheme = resolveTheme(theme);
             const viewportInfo = resolveViewportInfo(host, camera, input);
             const pipeline = runRenderPipeline({
@@ -104,6 +104,7 @@ export function createRenderer() {
                     mounts: {
                         zones: [],
                         paths: [],
+                        background: null,
                     },
                 };
             }
@@ -118,6 +119,8 @@ export function createRenderer() {
                 pipeline,
                 zoneComponentRenderers,
                 pathComponentRenderers,
+                backgroundRenderer,
+                gridOptions,
                 interactionHandlers,
                 exclusionState,
             });

package/dist/types.d.ts

@@ -84,8 +84,10 @@ export type VisibilityResult = {
     zoneVisibilityById: Record<ZoneId, ZoneVisibility>;
     pathVisibilityById: Record<PathId, PathVisibility>;
 };
-export type ZoneComponentSlotName = "title" | "type" | "badge" | "body" | "footer";
-export type PathComponentSlotName = "label" | "rule" | "target" | "body";
+export type BuiltInZoneSlotName = "title" | "type" | "badge" | "body" | "footer";
+export type ZoneComponentSlotName = BuiltInZoneSlotName | (string & {});
+export type BuiltInPathSlotName = "label" | "rule" | "target" | "body";
+export type PathComponentSlotName = BuiltInPathSlotName | (string & {});
 export type ZoneComponentLayout = {
     zoneId: ZoneId;
     slots: Partial<Record<ZoneComponentSlotName, Rect>>;
@@ -142,9 +144,29 @@ export type PathComponentMount = {
     rect: Rect;
     context: PathComponentRendererContext;
 };
+export type BackgroundRendererContext = {
+    sceneBounds: Rect;
+    camera: CameraState;
+    viewportInfo: RenderViewportInfo;
+    theme: ZoneflowTheme;
+};
+export type GridOptions = {
+    enabled?: boolean;
+    size?: number;
+    color?: string;
+    majorEvery?: number;
+    majorColor?: string;
+    backgroundColor?: string;
+};
+export type BackgroundRenderer = (host: HTMLElement, context: BackgroundRendererContext) => void;
+export type BackgroundMount = {
+    host: HTMLElement;
+    context: BackgroundRendererContext;
+};
 export type RenderMountRegistry = {
     zones: ZoneComponentMount[];
     paths: PathComponentMount[];
+    background: BackgroundMount | null;
 };
 export type RendererInteractionHandlers = {
     onZoneClick?: (zoneId: ZoneId) => void;
@@ -181,6 +203,8 @@ export type RendererDrawInput = {
     pipeline: RenderPipelineResult;
     zoneComponentRenderers?: ZoneComponentRendererMap;
     pathComponentRenderers?: PathComponentRendererMap;
+    backgroundRenderer?: BackgroundRenderer;
+    gridOptions?: GridOptions;
     interactionHandlers?: RendererInteractionHandlers;
     exclusionState?: RendererExclusionState;
 };
@@ -242,6 +266,8 @@ export type RendererInput = {
     drawEngine?: DrawEngine;
     zoneComponentRenderers?: ZoneComponentRendererMap;
     pathComponentRenderers?: PathComponentRendererMap;
+    backgroundRenderer?: BackgroundRenderer;
+    gridOptions?: GridOptions;
     interactionHandlers?: RendererInteractionHandlers;
     exclusionState?: RendererExclusionState;
     debug?: RendererDebugOptions;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zoneflow/renderer-dom",
-  "version": "0.0.11",
+  "version": "0.0.13",
   "license": "MIT",
   "description": "Low-level DOM renderer engines for Zoneflow.",
   "type": "module",
@@ -19,7 +19,7 @@
     "dist"
   ],
   "dependencies": {
-    "@zoneflow/core": "0.0.11"
+    "@zoneflow/core": "0.0.13"
   },
   "scripts": {
     "build": "tsc -p tsconfig.json",