@heyramzi/ui 2.11.1 → 2.11.2

package/dist/canvas/headless/fit-viewport.js

@@ -1,82 +1,99 @@
+/** What a node occupies when the saved data does not say. */
 const FALLBACK_NODE = {
-    width: 240,
-    height: 80
+	width: 240,
+	height: 80
 };
 function num(value) {
-    return typeof value === "number" && Number.isFinite(value) ? value : null;
+	return typeof value === "number" && Number.isFinite(value) ? value : null;
 }
 function cssDim(css, prop) {
-    const found = css.match(new RegExp(`(?:^|[;\\s])${prop}:\\s*(\\d+(?:\\.\\d+)?)px`))?.[1];
-    return found ? Number(found) : null;
+	const found = css.match(new RegExp(`(?:^|[;\\s])${prop}:\\s*(\\d+(?:\\.\\d+)?)px`))?.[1];
+	return found ? Number(found) : null;
 }
+/** A stored node often has a width and no height (the DOM measures it), so each side is read alone. */
 function styleDim(style, prop) {
-    if (typeof style === "string") return cssDim(style, prop);
-    if (!style || typeof style !== "object") return null;
-    return num(style[prop]);
+	if (typeof style === "string") return cssDim(style, prop);
+	if (!style || typeof style !== "object") return null;
+	return num(style[prop]);
 }
 function readSize(node) {
-    return {
-        width: num(node.width) ?? styleDim(node.style, "width") ?? FALLBACK_NODE.width,
-        height: num(node.height) ?? styleDim(node.style, "height") ?? FALLBACK_NODE.height
-    };
+	return {
+		width: num(node.width) ?? styleDim(node.style, "width") ?? FALLBACK_NODE.width,
+		height: num(node.height) ?? styleDim(node.style, "height") ?? FALLBACK_NODE.height
+	};
 }
+/**
+* The box every top-level node sits in. Children are parent-relative, so
+* counting them would push the bounds out and shrink the drawing.
+*/
 export function diagramBounds(nodes) {
-    const boxes = nodes.filter((node)=>!node.parentId).map((node)=>({
-            ...readSize(node),
-            x: node.position.x,
-            y: node.position.y
-        }));
-    if (boxes.length === 0) return null;
-    const minX = Math.min(...boxes.map((box)=>box.x));
-    const minY = Math.min(...boxes.map((box)=>box.y));
-    const maxX = Math.max(...boxes.map((box)=>box.x + box.width));
-    const maxY = Math.max(...boxes.map((box)=>box.y + box.height));
-    return {
-        x: minX,
-        y: minY,
-        width: maxX - minX,
-        height: maxY - minY
-    };
+	const boxes = nodes.filter((node) => !node.parentId).map((node) => ({
+		...readSize(node),
+		x: node.position.x,
+		y: node.position.y
+	}));
+	if (boxes.length === 0) return null;
+	const minX = Math.min(...boxes.map((box) => box.x));
+	const minY = Math.min(...boxes.map((box) => box.y));
+	const maxX = Math.max(...boxes.map((box) => box.x + box.width));
+	const maxY = Math.max(...boxes.map((box) => box.y + box.height));
+	return {
+		x: minX,
+		y: minY,
+		width: maxX - minX,
+		height: maxY - minY
+	};
 }
-export function fitViewport(nodes, container, padding = 0.04) {
-    const bounds = diagramBounds(nodes);
-    if (!bounds || bounds.width <= 0 || bounds.height <= 0) return null;
-    if (container.width <= 0 || container.height <= 0) return null;
-    const usableWidth = container.width * (1 - padding * 2);
-    const usableHeight = container.height * (1 - padding * 2);
-    const zoom = Math.min(usableWidth / bounds.width, usableHeight / bounds.height);
-    return {
-        x: (container.width - bounds.width * zoom) / 2 - bounds.x * zoom,
-        y: (container.height - bounds.height * zoom) / 2 - bounds.y * zoom,
-        zoom
-    };
+/**
+* The viewport that centres `nodes` inside a `container` of the given size.
+* `padding` is a fraction of the container, matching fitView's own meaning.
+*/
+export function fitViewport(nodes, container, padding = .04) {
+	const bounds = diagramBounds(nodes);
+	if (!bounds || bounds.width <= 0 || bounds.height <= 0) return null;
+	if (container.width <= 0 || container.height <= 0) return null;
+	const usableWidth = container.width * (1 - padding * 2);
+	const usableHeight = container.height * (1 - padding * 2);
+	const zoom = Math.min(usableWidth / bounds.width, usableHeight / bounds.height);
+	return {
+		x: (container.width - bounds.width * zoom) / 2 - bounds.x * zoom,
+		y: (container.height - bounds.height * zoom) / 2 - bounds.y * zoom,
+		zoom
+	};
 }
-const MIN_READABLE_ZOOM = 0.3;
-export function openingViewport(nodes, container, padding = 0.04, gutter = 0) {
-    const whole = fitViewport(nodes, container, padding);
-    if (!whole || whole.zoom >= MIN_READABLE_ZOOM) return whole;
-    const bounds = diagramBounds(nodes);
-    if (!bounds) return null;
-    const inset = container.width * padding;
-    const left = inset + gutter;
-    const zoom = Math.min((container.width - left - inset) / bounds.width, 1);
-    return {
-        x: left - bounds.x * zoom,
-        y: inset - bounds.y * zoom,
-        zoom
-    };
+/** Below this a whole-board fit is too small to read a card's text. */
+const MIN_READABLE_ZOOM = .3;
+/*
+* Where a board with no view opens: a board that fits reads whole, but a tall
+* wall fits at 8%, so it fits its width and starts at the top.
+*/
+export function openingViewport(nodes, container, padding = .04, gutter = 0) {
+	const whole = fitViewport(nodes, container, padding);
+	if (!whole || whole.zoom >= MIN_READABLE_ZOOM) return whole;
+	const bounds = diagramBounds(nodes);
+	if (!bounds) return null;
+	const inset = container.width * padding;
+	const left = inset + gutter;
+	const zoom = Math.min((container.width - left - inset) / bounds.width, 1);
+	return {
+		x: left - bounds.x * zoom,
+		y: inset - bounds.y * zoom,
+		zoom
+	};
 }
-export function viewShowsContent(nodes, viewport, container, inset = {
-    left: 0
-}) {
-    const bounds = diagramBounds(nodes);
-    if (!bounds || viewport.zoom <= 0) return true;
-    const left = (inset.left - viewport.x) / viewport.zoom;
-    const right = (container.width - viewport.x) / viewport.zoom;
-    const top = -viewport.y / viewport.zoom;
-    const bottom = (container.height - viewport.y) / viewport.zoom;
-    const onScreen = bounds.x < right && bounds.x + bounds.width > left && bounds.y < bottom && bounds.y + bounds.height > top;
-    if (!onScreen) return false;
-    const fits = bounds.width * viewport.zoom <= container.width - inset.left;
-    return !(fits && bounds.x < left - 4 / viewport.zoom);
+/**
+* Whether a saved view still shows the board: a card is on screen, and a fitting board isn't
+* pushed off the left. `inset` is the tool rail's strip.
+*/
+export function viewShowsContent(nodes, viewport, container, inset = { left: 0 }) {
+	const bounds = diagramBounds(nodes);
+	if (!bounds || viewport.zoom <= 0) return true;
+	const left = (inset.left - viewport.x) / viewport.zoom;
+	const right = (container.width - viewport.x) / viewport.zoom;
+	const top = -viewport.y / viewport.zoom;
+	const bottom = (container.height - viewport.y) / viewport.zoom;
+	const onScreen = bounds.x < right && bounds.x + bounds.width > left && bounds.y < bottom && bounds.y + bounds.height > top;
+	if (!onScreen) return false;
+	const fits = bounds.width * viewport.zoom <= container.width - inset.left;
+	return !(fits && bounds.x < left - 4 / viewport.zoom);
 }

package/dist/canvas/headless/grid.js

@@ -1,96 +1,98 @@
+// The magnets: the grid the editor snaps cards to. A write that isn't a drag snaps through here.
 import { STROKE_NODE } from "../pen/types.js";
+/** Flow units between two dots at the finest level. */
 export const GRID_SIZE = 20;
-export const SNAP_GRID = [
-    GRID_SIZE,
-    GRID_SIZE
-];
-export const FREEHAND_NODE_TYPES = new Set([
-    STROKE_NODE
-]);
+/** The value xyflow's `snapGrid` prop takes. */
+export const SNAP_GRID = [GRID_SIZE, GRID_SIZE];
+/** Node types that keep their exact points. A stroke's origin is its bounding box, so moving it shifts the drawing. */
+export const FREEHAND_NODE_TYPES = new Set([STROKE_NODE]);
+/** The nearest dot on one axis, rounded the way xyflow rounds a drag. */
 export function snapToGrid(value) {
-    return GRID_SIZE * Math.round(value / GRID_SIZE);
+	return GRID_SIZE * Math.round(value / GRID_SIZE);
 }
 function pointOf(value) {
-    if (typeof value !== "object" || value === null) return null;
-    const { x, y } = value;
-    return typeof x === "number" && typeof y === "number" && Number.isFinite(x) && Number.isFinite(y) ? {
-        x,
-        y
-    } : null;
+	if (typeof value !== "object" || value === null) return null;
+	const { x, y } = value;
+	return typeof x === "number" && typeof y === "number" && Number.isFinite(x) && Number.isFinite(y) ? {
+		x,
+		y
+	} : null;
 }
 function stringOf(value) {
-    return typeof value === "string" ? value : undefined;
+	return typeof value === "string" ? value : undefined;
 }
+/** Snaps the nodes a write created or moved and leaves the rest. A child snaps on the page, then goes back to relative. */
 export function snapWrittenNodes(before, after, exempt = FREEHAND_NODE_TYPES) {
-    const prior = new Map();
-    for (const node of before){
-        const id = stringOf(node.id);
-        if (id) prior.set(id, {
-            at: pointOf(node.position),
-            parent: stringOf(node.parentId)
-        });
-    }
-    const byId = new Map();
-    for (const node of after){
-        const id = stringOf(node.id);
-        if (id) byId.set(id, node);
-    }
-    const written = (node)=>{
-        const was = prior.get(String(node.id));
-        const at = pointOf(node.position);
-        const type = stringOf(node.type);
-        if (!at || type !== undefined && exempt.has(type)) return false;
-        if (!was?.at) return true;
-        return was.at.x !== at.x || was.at.y !== at.y || was.parent !== stringOf(node.parentId);
-    };
-    const settled = new Map();
-    const visiting = new Set();
-    const settle = (node)=>{
-        const id = String(node.id);
-        const done = settled.get(id);
-        if (done) return done;
-        const local = pointOf(node.position) ?? {
-            x: 0,
-            y: 0
-        };
-        const parentId = stringOf(node.parentId);
-        const parent = parentId ? byId.get(parentId) : undefined;
-        let origin = {
-            x: 0,
-            y: 0
-        };
-        if (parent && !visiting.has(id)) {
-            visiting.add(id);
-            origin = settle(parent).page;
-            visiting.delete(id);
-        }
-        const page = {
-            x: origin.x + local.x,
-            y: origin.y + local.y
-        };
-        const result = written(node) ? {
-            local: {
-                x: snapToGrid(page.x) - origin.x,
-                y: snapToGrid(page.y) - origin.y
-            },
-            page: {
-                x: snapToGrid(page.x),
-                y: snapToGrid(page.y)
-            }
-        } : {
-            local,
-            page
-        };
-        settled.set(id, result);
-        return result;
-    };
-    return after.map((node)=>{
-        if (!stringOf(node.id)) return node;
-        const at = pointOf(node.position);
-        const next = settle(node).local;
-        return at && (next.x !== at.x || next.y !== at.y) ? {
-            ...node,
-            position: next
-        } : node;
-    });
+	const prior = new Map();
+	for (const node of before) {
+		const id = stringOf(node.id);
+		if (id) prior.set(id, {
+			at: pointOf(node.position),
+			parent: stringOf(node.parentId)
+		});
+	}
+	const byId = new Map();
+	for (const node of after) {
+		const id = stringOf(node.id);
+		if (id) byId.set(id, node);
+	}
+	const written = (node) => {
+		const was = prior.get(String(node.id));
+		const at = pointOf(node.position);
+		const type = stringOf(node.type);
+		if (!at || type !== undefined && exempt.has(type)) return false;
+		if (!was?.at) return true;
+		return was.at.x !== at.x || was.at.y !== at.y || was.parent !== stringOf(node.parentId);
+	};
+	// Parents settle first, because a child's page position rides on its parent's.
+	const settled = new Map();
+	const visiting = new Set();
+	const settle = (node) => {
+		const id = String(node.id);
+		const done = settled.get(id);
+		if (done) return done;
+		const local = pointOf(node.position) ?? {
+			x: 0,
+			y: 0
+		};
+		const parentId = stringOf(node.parentId);
+		const parent = parentId ? byId.get(parentId) : undefined;
+		let origin = {
+			x: 0,
+			y: 0
+		};
+		if (parent && !visiting.has(id)) {
+			visiting.add(id);
+			origin = settle(parent).page;
+			visiting.delete(id);
+		}
+		const page = {
+			x: origin.x + local.x,
+			y: origin.y + local.y
+		};
+		const result = written(node) ? {
+			local: {
+				x: snapToGrid(page.x) - origin.x,
+				y: snapToGrid(page.y) - origin.y
+			},
+			page: {
+				x: snapToGrid(page.x),
+				y: snapToGrid(page.y)
+			}
+		} : {
+			local,
+			page
+		};
+		settled.set(id, result);
+		return result;
+	};
+	return after.map((node) => {
+		if (!stringOf(node.id)) return node;
+		const at = pointOf(node.position);
+		const next = settle(node).local;
+		return at && (next.x !== at.x || next.y !== at.y) ? {
+			...node,
+			position: next
+		} : node;
+	});
 }

package/dist/canvas/headless/icon-node.js

@@ -1,45 +1,53 @@
 export const ICON_SIZE = 56;
 export const ICON_W = 120;
+/** Gap between the mark and its label, either side. */
 export const ICON_LABEL_GAP = 12;
 export const ICON_LABEL_H = 22;
 export const ICON_LINE_H = 20;
+/** A right-hand label is set larger: it names an area, not a tool. */
 export const ICON_SIDE_LABEL_H = 28;
+/** Space between the port line and the first line under it. */
 export const ICON_PORT_GAP = 6;
+/**
+* A label below centres the mark and hands off at its edges. A right label starts it
+* at x 0 and leaves from the box's right edge.
+*/
 export function iconGeometry(icon, width = ICON_W) {
-    const size = icon.size ?? ICON_SIZE;
-    const lines = icon.lines?.length ?? 0;
-    const mid = size / 2;
-    if (icon.labelSide === "right") {
-        const top = Math.max(0, (icon.label ? ICON_SIDE_LABEL_H : 0) - mid);
-        return {
-            size,
-            markX: 0,
-            markY: top,
-            height: Math.max(top + size, top + mid + ICON_PORT_GAP + lines * ICON_LINE_H),
-            left: {
-                x: 0,
-                y: top + mid
-            },
-            right: {
-                x: Math.max(width, size),
-                y: top + mid
-            }
-        };
-    }
-    const markX = (Math.max(width, size) - size) / 2;
-    const text = (icon.label ? ICON_LABEL_H : 0) + lines * ICON_LINE_H;
-    return {
-        size,
-        markX,
-        markY: 0,
-        height: size + (text ? ICON_LABEL_GAP + text : 0),
-        left: {
-            x: markX,
-            y: mid
-        },
-        right: {
-            x: markX + size,
-            y: mid
-        }
-    };
+	const size = icon.size ?? ICON_SIZE;
+	const lines = icon.lines?.length ?? 0;
+	const mid = size / 2;
+	if (icon.labelSide === "right") {
+		// The label sits across the port line: name above it, lines below.
+		const top = Math.max(0, (icon.label ? ICON_SIDE_LABEL_H : 0) - mid);
+		return {
+			size,
+			markX: 0,
+			markY: top,
+			height: Math.max(top + size, top + mid + ICON_PORT_GAP + lines * ICON_LINE_H),
+			left: {
+				x: 0,
+				y: top + mid
+			},
+			right: {
+				x: Math.max(width, size),
+				y: top + mid
+			}
+		};
+	}
+	const markX = (Math.max(width, size) - size) / 2;
+	const text = (icon.label ? ICON_LABEL_H : 0) + lines * ICON_LINE_H;
+	return {
+		size,
+		markX,
+		markY: 0,
+		height: size + (text ? ICON_LABEL_GAP + text : 0),
+		left: {
+			x: markX,
+			y: mid
+		},
+		right: {
+			x: markX + size,
+			y: mid
+		}
+	};
 }

package/dist/canvas/headless/index.js

@@ -1 +1,2 @@
+// What a CLI or a server needs to build a board without a browser.
 export { compilePenMark, penMarkSchema, placeInFrame } from "./pen-marks.js";

package/dist/canvas/headless/linkify.js

@@ -1,25 +1,23 @@
 const URL_RE = /https?:\/\/[^\s<>"]+/g;
+/** Sentence punctuation that follows a link without belonging to it. */
 const TRAILING = /[.,;:!?)\]'”]+$/;
+/** Splits a line so each http(s) link is its own part, minus the punctuation after it. */
 export function linkify(text) {
-    const parts = [];
-    let last = 0;
-    for (const match of text.matchAll(URL_RE)){
-        const start = match.index ?? 0;
-        const href = match[0].replace(TRAILING, "");
-        if (start > last) parts.push({
-            text: text.slice(last, start)
-        });
-        parts.push({
-            text: href,
-            href
-        });
-        last = start + href.length;
-    }
-    if (last < text.length) parts.push({
-        text: text.slice(last)
-    });
-    return parts;
+	const parts = [];
+	let last = 0;
+	for (const match of text.matchAll(URL_RE)) {
+		const start = match.index ?? 0;
+		const href = match[0].replace(TRAILING, "");
+		if (start > last) parts.push({ text: text.slice(last, start) });
+		parts.push({
+			text: href,
+			href
+		});
+		last = start + href.length;
+	}
+	if (last < text.length) parts.push({ text: text.slice(last) });
+	return parts;
 }
 export function hasLink(text) {
-    return /https?:\/\//.test(text);
+	return /https?:\/\//.test(text);
 }