fragment-tools 0.2.12 → 0.2.13

package/src/client/app/utils/canvas.utils.js

@@ -10,7 +10,63 @@ import { exportCanvas } from '../lib/canvas-recorder/utils';
 import { map } from './math.utils';
 import { createDataURLFromBlob, saveFiles } from './file.utils';
 
-function getFilenameParams() {
+/**
+ * @typedef {Object} FilenameParams
+ * @property {string} year - Four-digit year
+ * @property {string} month - Two-digit month
+ * @property {string} day - Two-digit day
+ * @property {string} hours - Two-digit hours
+ * @property {string} minutes - Two-digit minutes
+ * @property {string} seconds - Two-digit seconds
+ * @property {string} timestamp - Full timestamp string
+ */
+
+/**
+ * @typedef {Object} ScreenshotOptions
+ * @property {string} [filename='Screenshot'] - Base filename
+ * @property {number} [index] - Optional frame index
+ * @property {FilenamePattern} [pattern] - Filename pattern function
+ * @property {string} [exportDir] - Export directory path
+ * @property {Record<string, any>} [params={}] - Additional parameters for pattern
+ * @property {string} [encoding='png'] - Image encoding format
+ * @property {number} [quality=100] - Image quality (1-100)
+ * @property {number} [pixelsPerInch=72] - Image DPI
+ */
+
+/**
+ * @typedef {Object} RecordCanvasOptions
+ * @property {string} [filename='output'] - Base filename for output
+ * @property {string} [format='mp4'] - Output format
+ * @property {number} [framerate=25] - Frames per second
+ * @property {number} [duration=Infinity] - Recording duration in seconds
+ * @property {number} [quality=100] - Recording quality (1-100)
+ * @property {FilenamePattern} [pattern] - Filename pattern function
+ * @property {import('../lib/canvas-recorder/MediaBunnyRecorder').VideoCodec} [codec] - Video codec
+ * @property {string} [exportDir] - Export directory path
+ * @property {string} [imageEncoding] - Image encoding for frame exports
+ * @property {import('../lib/canvas-recorder/CanvasRecorder').CanvasRecorderStartCallback} [onStart] - Callback when recording starts
+ * @property {import('../lib/canvas-recorder/CanvasRecorder').CanvasRecorderTickCallback} [onTick] - Callback on each frame
+ * @property {import('../lib/canvas-recorder/CanvasRecorder').CanvasRecorderCompleteCallback} [onComplete] - Callback when recording completes
+ * @property {Record<string, any>} [params={}] - Additional parameters
+ */
+/**
+ * @typedef {Object} PatternParams
+ * @property {number} [index] - Frame or sequence index
+ * @property {string} filename - Base filename
+ * @property {string} timestamp - Timestamp string
+ */
+
+/**
+ * @callback FilenamePattern
+ * @param {PatternParams & Record<string, any>} params - Pattern parameters
+ * @returns {string} Generated filename
+ */
+
+/**
+ * Get current date/time parameters for filename generation
+ * @returns {FilenameParams}
+ */
+export function getFilenameParams() {
 	const now = new Date();
 
 	const year = now.toLocaleString('default', { year: 'numeric' });
@@ -43,10 +99,14 @@ function getFilenameParams() {
 	};
 }
 
+/**
+ * Default filename pattern generator
+ * @type {FilenamePattern}
+ */
 export const defaultFilenamePattern = ({ index, filename, timestamp }) => {
 	let name = `${filename}.${timestamp}`;
 
-	if (!isNaN(index)) {
+	if (typeof index === 'number' && !isNaN(index)) {
 		name += `-${index}`;
 	}
 
@@ -54,14 +114,12 @@ export const defaultFilenamePattern = ({ index, filename, timestamp }) => {
 };
 
 /**
- *
- * @param {HTMLCanvasElement} canvas
- * @param {string} sketchKey
- * @param {Sketch} sketch
- * @param {number} [index]
- * @param {Promise<string[]>}
+ * Capture and save a screenshot of a canvas
+ * @param {HTMLCanvasElement} canvas - The canvas to capture
+ * @param {ScreenshotOptions} [options={}] - Screenshot options
+ * @returns {{ filename: string, exportDir: string | undefined, data: string, encoding: string }}
  */
-export async function screenshotCanvas(
+export function screenshotCanvas(
 	canvas,
 	{
 		filename = 'Screenshot',
@@ -83,23 +141,20 @@ export async function screenshotCanvas(
 	let patternParams = getFilenameParams();
 	let name = pattern({ filename, index, ...params, ...patternParams });
 
-	const files = [
-		{
-			filename: `${name}${extension}`,
-			exportDir,
-			data: dataURL,
-			encoding: 'base64',
-		},
-	];
-
-	try {
-		await saveFiles(files);
-	} catch (error) {
-		console.error(`[fragment] Error while saving screenshot.`);
-		console.log(error);
-	}
+	return {
+		filename: `${name}${extension}`,
+		exportDir,
+		data: dataURL,
+		encoding: 'base64',
+	};
 }
 
+/**
+ * Record video using MediaBunny recorder
+ * @param {HTMLCanvasElement} canvas - The canvas to record
+ * @param {import('../lib/canvas-recorder/MediaBunnyRecorder').MediaBunnyRecorderOptions} options - Recording options
+ * @returns {MediaBunnyRecorder}
+ */
 function record(canvas, options) {
 	let recorder = new MediaBunnyRecorder(canvas, options);
 	recorder.start();
@@ -107,6 +162,12 @@ function record(canvas, options) {
 	return recorder;
 }
 
+/**
+ * Record GIF animation
+ * @param {HTMLCanvasElement} canvas - The canvas to record
+ * @param {import('../lib/canvas-recorder/CanvasRecorder').CanvasRecorderOptions} options - Recording options
+ * @returns {GIFRecorder}
+ */
 function recordGIF(canvas, options) {
 	let recorder = new GIFRecorder(canvas, options);
 	recorder.start();
@@ -114,6 +175,12 @@ function recordGIF(canvas, options) {
 	return recorder;
 }
 
+/**
+ * Record individual frames
+ * @param {HTMLCanvasElement} canvas - The canvas to record
+ * @param {import('../lib/canvas-recorder/FrameRecorder').FrameRecorderOptions} options - Recording options
+ * @returns {FrameRecorder}
+ */
 function recordFrames(canvas, options) {
 	let recorder = new FrameRecorder(canvas, options);
 	recorder.start();
@@ -121,6 +188,12 @@ function recordFrames(canvas, options) {
 	return recorder;
 }
 
+/**
+ * Start recording canvas output
+ * @param {HTMLCanvasElement} canvas - The canvas to record
+ * @param {RecordCanvasOptions} [options={}] - Recording options
+ * @returns {MediaBunnyRecorder | GIFRecorder | FrameRecorder | undefined}
+ */
 export function recordCanvas(
 	canvas,
 	{
@@ -130,18 +203,22 @@ export function recordCanvas(
 		duration = Infinity,
 		quality = 100,
 		pattern = defaultFilenamePattern,
-		codec,
+		codec = 'avc',
 		exportDir,
 		imageEncoding,
 		onStart = () => {},
 		onTick = () => {},
 		onComplete = () => {},
-		params = {},
 	} = {},
 ) {
 	let patternParams = getFilenameParams();
 	let name = pattern({ filename, ...patternParams });
 
+	/**
+	 * Handle recording completion
+	 * @param {Blob | Blob[] | null} result - Recording result (blob or array of blobs)
+	 * @returns {Promise<void>}
+	 */
 	async function complete(result) {
 		const files = [];
 
@@ -163,7 +240,7 @@ export function recordCanvas(
 					encoding: 'base64',
 				});
 			}
-		} else {
+		} else if (result) {
 			const blob = result;
 			const data = await createDataURLFromBlob(blob);
 
@@ -177,7 +254,7 @@ export function recordCanvas(
 		}
 
 		await saveFiles(files);
-		onComplete();
+		onComplete(result);
 	}
 
 	const options = {

package/src/client/app/utils/color.utils.js

@@ -5,7 +5,9 @@ export const FORMATS = {
 	HSL_STRING: 'hsl-string',
 	HSLA_STRING: 'hsla-string',
 	RGB_OBJECT: 'rgb-object',
+	RGB_OBJECT_STRING: 'rgb-object-string',
 	RGBA_OBJECT: 'rgba-object',
+	RGBA_OBJECT_STRING: 'rgba-object-string',
 	VEC3_STRING: 'vec3-string',
 	VEC4_STRING: 'vec4-string',
 	VEC3_ARRAY: 'vec3-array',
@@ -32,6 +34,11 @@ export function toHex(color, format = getColorFormat(color)) {
 	if (format === FORMATS.VEC3_ARRAY || format === FORMATS.VEC4_ARRAY)
 		return vecArrayToHex(color);
 	if (format === FORMATS.CSS_COLOR) return nameToHex(color);
+	if (
+		format === FORMATS.RGB_OBJECT_STRING ||
+		format === FORMATS.RGBA_OBJECT_STRING
+	)
+		return objectStringToHex(color);
 }
 
 export function toComponents(color, format = getColorFormat(color)) {
@@ -50,6 +57,11 @@ export function toComponents(color, format = getColorFormat(color)) {
 	if (format === FORMATS.VEC3_STRING || format === FORMATS.VEC4_STRING)
 		return vecStringToComponents(color);
 	if (format === FORMATS.CSS_COLOR) return nameToComponents(color);
+	if (
+		format === FORMATS.RGB_OBJECT_STRING ||
+		format === FORMATS.RGBA_OBJECT_STRING
+	)
+		return objectStringToComponents(color);
 }
 
 export function toString(color, format = getColorFormat(color)) {
@@ -61,6 +73,8 @@ export function toString(color, format = getColorFormat(color)) {
 		format === FORMATS.HEX_STRING ||
 		format === FORMATS.RGB_STRING ||
 		format === FORMATS.RGBA_STRING ||
+		format === FORMATS.RGB_OBJECT_STRING ||
+		format === FORMATS.RGBA_OBJECT_STRING ||
 		format === FORMATS.HSL_STRING ||
 		format === FORMATS.HSLA_STRING ||
 		format === FORMATS.VEC3_STRING ||
@@ -74,9 +88,9 @@ export function toString(color, format = getColorFormat(color)) {
 		return componentsToRGBAString(vecArrayToComponents(color));
 	if (format === FORMATS.THREE) return threeToHex(color);
 	if (format === FORMATS.RGB_OBJECT)
-		return componentsToRGBStringObject([color.r, color.g, color.b]);
+		return componentsToRGBObjectString([color.r, color.g, color.b]);
 	if (format === FORMATS.RGBA_OBJECT)
-		return componentsToRGBAStringObject([
+		return componentsToRGBAObjectString([
 			color.r,
 			color.g,
 			color.b,
@@ -278,12 +292,12 @@ export function toVec3String(color) {
 	return componentsToVec3String(toComponents(color));
 }
 
-export function toRGBStringObject(color) {
-	return componentsToRGBStringObject(toComponents(color));
+export function toRGBObjectString(color) {
+	return componentsToRGBObjectString(toComponents(color));
 }
 
-export function toRGBAStringObject(color) {
-	return componentsToRGBAStringObject(toComponents(color));
+export function toRGBAObjectString(color) {
+	return componentsToRGBAObjectString(toComponents(color));
 }
 
 export function toVec4String(color) {
@@ -312,7 +326,19 @@ export function componentsToVec3String(components = []) {
 	return `vec3(${rn}, ${gn}, ${bn})`;
 }
 
-export function componentsToRGBStringObject(components) {
+export function componentsToRGBObject(components) {
+	const [r = 0, g = 0, b = 0] = components;
+
+	return { r, g, b };
+}
+
+export function componentsToRGBAObject(components) {
+	const [r = 0, g = 0, b = 0, a = 1] = components;
+
+	return { r, g, b, a };
+}
+
+export function componentsToRGBObjectString(components) {
 	const [r = 0, g = 0, b = 0] = components;
 
 	let rn = `${Math.round(r * 1000) / 1000}`;
@@ -322,14 +348,15 @@ export function componentsToRGBStringObject(components) {
 	return `{ r: ${rn}, g: ${gn}, b: ${bn} }`;
 }
 
-export function componentsToRGBAStringObject(components) {
+export function componentsToRGBAObjectString(components) {
 	const [r = 0, g = 0, b = 0, a = 1] = components;
 
 	let rn = `${Math.round(r * 1000) / 1000}`;
 	let gn = `${Math.round(g * 1000) / 1000}`;
 	let bn = `${Math.round(b * 1000) / 1000}`;
+	let an = `${Math.round(a * 1000) / 1000}`;
 
-	return `{ r: ${rn}, g: ${gn}, b: ${bn}, a: ${a} }`;
+	return `{ r: ${rn}, g: ${gn}, b: ${bn}, a: ${an} }`;
 }
 
 export function componentsToVec4String(components = []) {
@@ -450,6 +477,14 @@ export function componentsToHex(components = []) {
 	return `#${hex}`;
 }
 
+export function objectStringToComponents(value) {
+	const parsable = value.replace(/([{,]\s*)([a-z]+)(\s*:)/g, '$1"$2"$3');
+
+	const { r, g, b, a = 1 } = JSON.parse(parsable);
+
+	return [r, g, b, a];
+}
+
 export function isHexString(value, isString = typeof value === 'string') {
 	return isString && /^#([a-f0-9]{3,4}){1,2}$/i.test(value);
 }
@@ -470,19 +505,19 @@ export function isRGBString(value, isString = typeof value === 'string') {
 }
 
 export function isHSLAString(value, isString = typeof value === 'string') {
-	return isString && value.includes('hsla');
+	return isString && value.startsWith('hsla');
 }
 
 export function isHSLString(value, isString = typeof value === 'string') {
-	return isString && value.includes('hsl');
+	return isString && value.startsWith('hsl');
 }
 
 export function isVec3String(value, isString = typeof value === 'string') {
-	return isString && value.includes('vec3(');
+	return isString && value.startsWith('vec3(');
 }
 
 export function isVec4String(value, isString = typeof value === 'string') {
-	return isString && value.includes('vec4(');
+	return isString && value.startsWith('vec4(');
 }
 
 export function isRGBAObject(value) {
@@ -516,6 +551,16 @@ export function isRGBObject(value) {
 	return false;
 }
 
+export function isRGBObjectString(value) {
+	const parsable = value.replace(/([{,]\s*)([a-z]+)(\s*:)/g, '$1"$2"$3');
+	return typeof value === 'string' && isRGBObject(JSON.parse(parsable));
+}
+
+export function isRGBAObjectString(value) {
+	const parsable = value.replace(/([{,]\s*)([a-z]+)(\s*:)/g, '$1"$2"$3');
+	return typeof value === 'string' && isRGBAObject(JSON.parse(parsable));
+}
+
 export function isVec3Array(value) {
 	if (Array.isArray(value)) {
 		return value.length == 3 && value.every((c) => c >= 0 && c <= 1);
@@ -575,6 +620,8 @@ export function getColorFormat(value) {
 	if (isRGBString(value)) return FORMATS.RGB_STRING;
 	if (isRGBObject(value)) return FORMATS.RGB_OBJECT;
 	if (isRGBAObject(value)) return FORMATS.RGBA_OBJECT;
+	if (isRGBObjectString(value)) return FORMATS.RGB_OBJECT_STRING;
+	if (isRGBAObjectString(value)) return FORMATS.RGBA_OBJECT_STRING;
 	if (isVec3String(value)) return FORMATS.VEC3_STRING;
 	if (isVec4String(value)) return FORMATS.VEC4_STRING;
 	if (isVec3Array(value)) return FORMATS.VEC3_ARRAY;
@@ -585,16 +632,26 @@ export function getColorFormat(value) {
 }
 
 export function componentsToFormat(components, format) {
-	const [r, g, b, a] = components;
+	const [r, g, b, a = 1] = components;
 
 	switch (format) {
+		case FORMATS.HEX_STRING:
+			return componentsToHex([r, g, b, a]);
 		case FORMATS.RGB_STRING:
-			return componentsToRGBString(components);
+			return componentsToRGBString([r, g, b, a]);
 		case FORMATS.RGBA_STRING:
 			return componentsToRGBAString([r, g, b, a]);
 		case FORMATS.VEC3_STRING:
-			return componentsToVec3String(components);
+			return componentsToVec3String([r, g, b, a]);
 		case FORMATS.VEC4_STRING:
-			return componentsToVec4String(components);
+			return componentsToVec4String([r, g, b, a]);
+		case FORMATS.RGB_OBJECT:
+			return componentsToRGBObject([r, g, b, a]);
+		case FORMATS.RGBA_OBJECT:
+			return componentsToRGBAObject([r, g, b, a]);
+		case FORMATS.RGB_OBJECT_STRING:
+			return componentsToRGBObjectString([r, g, b, a]);
+		case FORMATS.RGBA_OBJECT_STRING:
+			return componentsToRGBAObjectString([r, g, b, a]);
 	}
 }

package/src/client/app/utils/fields.utils.js

@@ -14,17 +14,48 @@ export const fieldTypes = {
 	IMPORT: 'import',
 	IMAGE: 'image',
 	INTERVAL: 'interval',
+	WRAPPER: 'wrapper',
+	PALETTE: 'palette',
+	GRADIENT: 'gradient',
 };
 
 /** @type string[] */
 const types = Object.values(fieldTypes);
 
+/**
+ * @param {string} url
+ * @returns {boolean}
+ */
 function isImageURL(url) {
-	return url.match(/\.(jpeg|jpg|gif|png|webp)$/) !== null;
+	return (
+		url.match(/\.(jpeg|jpg|gif|png|webp)$/) !== null ||
+		url.startsWith('data:image')
+	);
 }
 
+/**
+ * @param {any} value
+ * @returns {boolean}
+ */
 function isImage(value) {
-	return typeof value === HTMLImageElement || isImageURL(value);
+	return (
+		typeof value === HTMLImageElement ||
+		(typeof value === 'string' && isImageURL(value))
+	);
+}
+
+/**
+ *
+ * @param {any[]} value
+ * @returns {boolean}
+ */
+function isGradient(value) {
+	return value.every(
+		(v) =>
+			typeof v === 'object' &&
+			typeof v.position === 'number' &&
+			isColor(v.color),
+	);
 }
 
 export function inferFieldType({ type, value, params, key }) {
@@ -82,6 +113,10 @@ export function inferFieldType({ type, value, params, key }) {
 			typeof params.max === 'number'
 		) {
 			return fieldTypes.INTERVAL;
+		} else if (isArray && isGradient(value)) {
+			return fieldTypes.GRADIENT;
+		} else if (isArray && values.every((v) => isColor(v))) {
+			return fieldTypes.PALETTE;
 		} else if (isColor(value)) {
 			return fieldTypes.COLOR;
 		} else if (typeof value === 'number') {
@@ -115,34 +150,41 @@ export function inferFieldType({ type, value, params, key }) {
  * @param {string} folder
  */
 export function parseFolder(folder) {
-	const regex = /(?<name>[\w ]+)(?:\[(?<attributes>[^\]]+)\])?/g;
-	const matches = [...folder.matchAll(regex)];
-
-	const results = matches.map((match) => {
-		return {
-			name: match.groups.name,
-			attributes: match.groups.attributes
-				? Object.fromEntries(
-						match.groups.attributes
-							.split(', ')
-							.map((attr) =>
-								attr
-									.split('=')
-									.map((v) =>
-										v === 'false'
-											? false
-											: v === 'true'
-												? true
-												: v,
+	const segments = folder.split('.');
+	const regex = /(?<name>[^\[]+)(?:\[(?<attributes>[^\]]+)\])?/;
+
+	const results = segments
+		.map((segment) => {
+			const match = segment.match(regex);
+
+			if (match) {
+				return {
+					name: match.groups?.name,
+					attributes: match.groups?.attributes
+						? Object.fromEntries(
+								match.groups.attributes
+									.split(', ')
+									.map((attr) =>
+										attr
+											.split('=')
+											.map((v) =>
+												v === 'false'
+													? false
+													: v === 'true'
+														? true
+														: v,
+											),
 									),
-							),
-					)
-				: {},
-		};
-	});
+							)
+						: {},
+				};
+			}
+		})
+		.filter((result) => result !== undefined);
 
 	let names = results.map((match) => match.name);
 
+	/** @type {string|undefined} */
 	let rootId;
 
 	results.forEach((match, index) => {