@getdom/studio 0.1.0

package/src/pages/components/tree-view/treeSchemas.js

@@ -0,0 +1,129 @@
+function treeItemActionSchema() {
+	return {
+		type: 'DomForm',
+		properties: {
+			value: {
+				type: 'string',
+				label: 'Value',
+				placeholder: 'open',
+			},
+			label: {
+				type: 'string',
+				label: 'Label',
+				placeholder: 'Open',
+			},
+			icon: {
+				type: 'string',
+				label: 'Icon path',
+				placeholder: 'SVG path data',
+			},
+			disabled: {
+				type: 'boolean',
+				label: 'Disabled',
+			},
+		},
+	};
+}
+
+function treeItemSchema(depth = 3) {
+	return {
+		type: 'DomForm',
+		properties: {
+			id: {
+				type: 'string',
+				label: 'ID',
+				placeholder: 'node-id',
+			},
+			value: {
+				type: 'string',
+				label: 'Value',
+				placeholder: 'node-value',
+			},
+			label: {
+				type: 'string',
+				label: 'Label',
+				placeholder: 'Node label',
+			},
+			name: {
+				type: 'string',
+				label: 'Name',
+				placeholder: 'Fallback label',
+			},
+			type: {
+				type: 'string',
+				label: 'Node type',
+				placeholder: 'file',
+			},
+			icon: {
+				type: 'string',
+				label: 'Icon path',
+				placeholder: 'SVG path data',
+			},
+			rightIcon: {
+				type: 'string',
+				label: 'Right icon',
+				placeholder: 'SVG path data',
+			},
+			rightIconAction: {
+				type: 'string',
+				label: 'Right icon action',
+			},
+			rightIconLabel: {
+				type: 'string',
+				label: 'Right icon label',
+			},
+			open: {
+				type: 'boolean',
+				label: 'Open',
+			},
+			lazy: {
+				type: 'boolean',
+				label: 'Lazy',
+			},
+			loading: {
+				type: 'boolean',
+				label: 'Loading',
+			},
+			disabled: {
+				type: 'boolean',
+				label: 'Disabled',
+			},
+			draggable: {
+				type: 'boolean',
+				label: 'Draggable',
+			},
+			acceptsChildren: {
+				type: 'boolean',
+				label: 'Accept drops',
+				default: true,
+			},
+			slot: {
+				type: 'string',
+				label: 'Slot',
+				placeholder: 'custom-node',
+			},
+			actions: {
+				type: 'array',
+				label: 'Actions',
+				items: treeItemActionSchema(),
+			},
+			children: depth > 0
+				? {
+					type: 'array',
+					label: 'Children',
+					items: treeItemSchema(depth - 1),
+				}
+				: {
+					type: 'json',
+					label: 'Children',
+					default: [],
+				},
+		},
+	};
+}
+
+export const treeItemsFormSchema = {
+	type: 'array',
+	label: 'Tree items',
+	items: treeItemSchema(),
+};

package/src/pages/components/tree-view/treeUtils.js

@@ -0,0 +1,228 @@
+/**
+ * Return the stable value used to address a tree item.
+ *
+ * The component supports `id`, `value`, or `label` so small examples can stay
+ * terse, but production trees should provide stable ids.
+ *
+ * @param {object} item
+ * @returns {string|number|undefined}
+ */
+export function treeItemValue(item) {
+	return item?.id ?? item?.value ?? item?.label;
+}
+
+/**
+ * Return the human-readable label for a tree item.
+ *
+ * @param {object} item
+ * @returns {string|number|undefined}
+ */
+export function treeItemLabel(item) {
+	return item?.label ?? item?.name ?? treeItemValue(item);
+}
+
+/**
+ * Return children for a nested tree item.
+ *
+ * @param {object} item
+ * @returns {Array}
+ */
+export function treeItemChildren(item) {
+	return Array.isArray(item?.children) ? item.children : [];
+}
+
+/**
+ * Walk every item in a nested tree.
+ *
+ * @param {Array} items
+ * @param {(item: object) => void} callback
+ */
+export function visitTreeItems(items, callback) {
+	for (const item of items || []) {
+		callback(item);
+		if (Array.isArray(item?.children)) visitTreeItems(item.children, callback);
+	}
+}
+
+/**
+ * Build the initial open set from a controlled open array, item.open flags,
+ * and any previous local open state.
+ *
+ * @param {Array} items
+ * @param {Array<string|number>} controlled
+ * @param {Set<string>} previous
+ * @returns {Array<string>}
+ */
+export function seedTreeOpenValues(items, controlled = [], previous = new Set()) {
+	if (controlled?.length) return controlled.map(String);
+	const values = new Set(previous);
+	visitTreeItems(items, (item) => {
+		if (item?.open) values.add(String(treeItemValue(item)));
+	});
+	return [...values];
+}
+
+/**
+ * Does the item display as a branch?
+ *
+ * Lazy items are treated as expandable before their children have loaded.
+ *
+ * @param {object} item
+ * @returns {boolean}
+ */
+export function treeItemHasChildren(item) {
+	return treeItemChildren(item).length > 0 || item?.lazy;
+}
+
+/**
+ * Can this item accept drops as children?
+ *
+ * `acceptsChildren` can explicitly opt in or out. Without it, only visible
+ * branches accept child drops.
+ *
+ * @param {object} item
+ * @returns {boolean}
+ */
+export function treeItemCanAcceptChildren(item) {
+	if (item?.acceptsChildren !== undefined) return item.acceptsChildren !== false;
+	return treeItemHasChildren(item);
+}
+
+/**
+ * Flatten a nested tree into visible row records.
+ *
+ * This is intentionally pure so a store can derive its visible rows without
+ * mounting the TreeView component.
+ *
+ * @param {Array} items
+ * @param {Set<string>} openValues
+ * @param {number} depth
+ * @param {object|null} parent
+ * @param {Array<number>} path
+ * @returns {Array<object>}
+ */
+export function flattenTreeItems(items, openValues, depth = 1, parent = null, path = []) {
+	const out = [];
+	(items || []).forEach((item, index) => {
+		const value = treeItemValue(item);
+		const node = {
+			item,
+			value,
+			label: treeItemLabel(item),
+			depth,
+			parent,
+			path: [...path, index],
+			open: openValues.has(String(value)),
+			loading: Boolean(item?.loading),
+			expandable: treeItemHasChildren(item),
+		};
+		out.push(node);
+		if (node.open && treeItemChildren(item).length) {
+			out.push(...flattenTreeItems(treeItemChildren(item), openValues, depth + 1, node, node.path));
+		}
+	});
+	return out;
+}
+
+/**
+ * Build an id lookup for nested tree data.
+ *
+ * This is useful for Pinia stores that keep nested data but need fast lookup
+ * by id for selection, stage highlighting, or permissions.
+ *
+ * @param {Array} items
+ * @returns {Map<string, { item: object, path: Array<number>, parent: object|null }>}
+ */
+export function indexTreeItems(items) {
+	const index = new Map();
+	function visit(children, parent = null, path = []) {
+		(children || []).forEach((item, itemIndex) => {
+			const nextPath = [...path, itemIndex];
+			index.set(String(treeItemValue(item)), { item, path: nextPath, parent });
+			visit(treeItemChildren(item), item, nextPath);
+		});
+	}
+	visit(items);
+	return index;
+}
+
+/**
+ * Clone nested tree items while preserving item payload properties.
+ *
+ * @param {Array} items
+ * @returns {Array}
+ */
+export function cloneTreeItems(items) {
+	return (items || []).map((item) => ({
+		...item,
+		children: Array.isArray(item.children) ? cloneTreeItems(item.children) : item.children,
+	}));
+}
+
+/**
+ * Move a nested tree item before, after, or inside another item.
+ *
+ * The original array is not mutated. Stores can call this from their own drop
+ * handlers, then decide whether to commit the returned tree.
+ *
+ * @param {Array} items
+ * @param {string|number} sourceValue
+ * @param {string|number} targetValue
+ * @param {'before'|'inside'|'after'} position
+ * @returns {{ items: Array, item: object } | null}
+ */
+export function moveTreeItem(items, sourceValue, targetValue, position) {
+	const sourceIndex = indexTreeItems(items).get(String(sourceValue));
+	const targetIndex = indexTreeItems(items).get(String(targetValue));
+	if (!sourceIndex || !targetIndex) return null;
+	if (isSameOrDescendantPath(targetIndex.path, sourceIndex.path)) return null;
+
+	const next = cloneTreeItems(items);
+	const item = removeTreeItemByValue(next, sourceValue);
+	if (!item) return null;
+	if (!insertTreeItemByValue(next, targetValue, position, item)) return null;
+	return { items: next, item };
+}
+
+/**
+ * Is path inside possibleParentPath, or exactly the same item?
+ *
+ * @param {Array<number>} path
+ * @param {Array<number>} possibleParentPath
+ * @returns {boolean}
+ */
+export function isSameOrDescendantPath(path, possibleParentPath) {
+	if (path.length < possibleParentPath.length) return false;
+	return possibleParentPath.every((part, index) => path[index] === part);
+}
+
+function removeTreeItemByValue(items, value) {
+	for (let index = 0; index < items.length; index += 1) {
+		if (String(treeItemValue(items[index])) === String(value)) {
+			return items.splice(index, 1)[0];
+		}
+		const children = treeItemChildren(items[index]);
+		if (children.length) {
+			const removed = removeTreeItemByValue(children, value);
+			if (removed) return removed;
+		}
+	}
+	return null;
+}
+
+function insertTreeItemByValue(items, targetValue, position, item) {
+	for (let index = 0; index < items.length; index += 1) {
+		if (String(treeItemValue(items[index])) === String(targetValue)) {
+			if (position === 'inside') {
+				if (!Array.isArray(items[index].children)) items[index].children = [];
+				items[index].children.push(item);
+			} else {
+				items.splice(position === 'before' ? index : index + 1, 0, item);
+			}
+			return true;
+		}
+		const children = treeItemChildren(items[index]);
+		if (children.length && insertTreeItemByValue(children, targetValue, position, item)) return true;
+	}
+	return false;
+}

package/src/pages/data/_shared/calculateVirtualWindow.js

@@ -0,0 +1,101 @@
+/**
+ * Calculates a fixed-size virtual render window for either axis.
+ *
+ * The returned end index is exclusive so it can be passed directly to
+ * `Array.prototype.slice()`. Callers can translate spacer item counts into
+ * pixels for rows, columns, weeks, or any other fixed-size collection.
+ *
+ * @param {object} options Virtual-window inputs.
+ * @param {number} options.itemCount Total number of available items.
+ * @param {number} options.itemSize Fixed pixel size of one item.
+ * @param {number} options.scrollOffset Current scroll offset on the virtualized axis.
+ * @param {number} options.viewportSize Visible viewport size on the virtualized axis.
+ * @param {number} [options.overscan] Extra items rendered before and after the visible window.
+ * @returns {{
+ *	startIndex: number,
+ *	endIndex: number,
+ *	firstVisibleIndex: number,
+ *	lastVisibleIndex: number,
+ *	renderedItems: number,
+ *	totalItems: number,
+ *	itemSize: number,
+ *	overscan: number,
+ *	viewportItems: number,
+ *	beforeSpacerSize: number,
+ *	afterSpacerSize: number,
+ * }} Normalized render window and spacer measurements.
+ */
+export function calculateVirtualWindow({
+	itemCount,
+	itemSize,
+	scrollOffset,
+	viewportSize,
+	overscan = 0,
+}) {
+	const totalItems = normalizeNonNegativeInteger(itemCount);
+	const safeItemSize = normalizePositiveNumber(itemSize, 1);
+	const safeScrollOffset = Math.max(0, normalizeFiniteNumber(scrollOffset, 0));
+	const safeViewportSize = Math.max(0, normalizeFiniteNumber(viewportSize, 0));
+	const safeOverscan = normalizeNonNegativeInteger(overscan);
+	const viewportItems = Math.max(1, Math.ceil(safeViewportSize / safeItemSize));
+	const firstVisibleIndex = Math.min(
+		Math.max(0, totalItems - 1),
+		Math.floor(safeScrollOffset / safeItemSize),
+	);
+	const lastVisibleIndex = totalItems
+		? Math.min(totalItems - 1, firstVisibleIndex + viewportItems - 1)
+		: -1;
+	const startIndex = totalItems ? Math.max(0, firstVisibleIndex - safeOverscan) : 0;
+	const endIndex = totalItems
+		? Math.min(totalItems, firstVisibleIndex + viewportItems + safeOverscan)
+		: 0;
+
+	return {
+		startIndex,
+		endIndex,
+		firstVisibleIndex: totalItems ? firstVisibleIndex : 0,
+		lastVisibleIndex,
+		renderedItems: Math.max(0, endIndex - startIndex),
+		totalItems,
+		itemSize: safeItemSize,
+		overscan: safeOverscan,
+		viewportItems,
+		beforeSpacerSize: startIndex * safeItemSize,
+		afterSpacerSize: Math.max(0, totalItems - endIndex) * safeItemSize,
+	};
+}
+
+/**
+ * Normalizes a value as a finite number.
+ *
+ * @param {unknown} value Candidate numeric value.
+ * @param {number} fallback Value returned when the candidate is not finite.
+ * @returns {number} Finite numeric value.
+ */
+function normalizeFiniteNumber(value, fallback) {
+	const number = Number(value);
+	return Number.isFinite(number) ? number : fallback;
+}
+
+/**
+ * Normalizes a value as a positive finite number.
+ *
+ * @param {unknown} value Candidate numeric value.
+ * @param {number} fallback Value returned when the candidate is not positive.
+ * @returns {number} Positive finite numeric value.
+ */
+function normalizePositiveNumber(value, fallback) {
+	const number = normalizeFiniteNumber(value, fallback);
+	return number > 0 ? number : fallback;
+}
+
+/**
+ * Normalizes a value as a non-negative integer.
+ *
+ * @param {unknown} value Candidate numeric value.
+ * @returns {number} Non-negative integer.
+ */
+function normalizeNonNegativeInteger(value) {
+	const number = Math.floor(normalizeFiniteNumber(value, 0));
+	return Math.max(0, number);
+}

package/src/pages/data/_shared/resourceRecord.js

@@ -0,0 +1,29 @@
+/**
+ * Resolves a value from an application-owned resource row.
+ *
+ * Data components use the same string-or-function contract so applications can
+ * pass ActiveRecord logical field names directly while retaining an escape hatch
+ * for computed presentation values.
+ *
+ * @param {Record<string, unknown>} row Resource row to inspect.
+ * @param {string|Function} field Logical field name or custom resolver.
+ * @param {number} index Source row index supplied to custom resolvers.
+ * @returns {unknown} Resolved row value.
+ */
+export function resolveResourceValue(row, field, index = 0) {
+	if (typeof field === 'function') return field(row, index);
+	if (!field || typeof field !== 'string') return undefined;
+	return row?.[field];
+}
+
+/**
+ * Resolves a stable resource-row key with an index fallback.
+ *
+ * @param {Record<string, unknown>} row Resource row to identify.
+ * @param {string|Function} rowKey Logical key field or custom resolver.
+ * @param {number} index Source row index used when no key is available.
+ * @returns {string|number} Stable key or the supplied fallback index.
+ */
+export function resolveResourceKey(row, rowKey = 'id', index = 0) {
+	return resolveResourceValue(row, rowKey, index) ?? index;
+}