q5 2.17.0 → 2.18.1

package/deno.json

@@ -1,6 +1,6 @@
 {
 	"name": "@q5/q5",
-	"version": "2.17.0",
+	"version": "2.18.1",
 	"license": "LGPL-3.0",
 	"description": "A sequel to p5.js that's optimized for interactive art",
 	"author": "quinton-ashley",

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "q5",
-	"version": "2.17.0",
+	"version": "2.18.1",
 	"description": "A sequel to p5.js that's optimized for interactive art",
 	"author": "quinton-ashley",
 	"contributors": [
@@ -11,7 +11,7 @@
 	"homepage": "https://q5js.org/home",
 	"main": "q5-server.js",
 	"scripts": {
-		"bundle": "cat src/q5-core.js src/q5-canvas.js src/q5-c2d-canvas.js src/q5-c2d-drawing.js src/q5-c2d-image.js src/q5-c2d-soft-filters.js src/q5-c2d-text.js src/q5-ai.js src/q5-color.js src/q5-display.js src/q5-dom.js src/q5-input.js src/q5-math.js src/q5-sound.js src/q5-util.js src/q5-vector.js src/q5-webgpu-canvas.js src/q5-webgpu-drawing.js src/q5-webgpu-image.js src/q5-webgpu-text.js > q5.js",
+		"bundle": "cat src/q5-core.js src/q5-canvas.js src/q5-c2d-canvas.js src/q5-c2d-drawing.js src/q5-c2d-image.js src/q5-c2d-soft-filters.js src/q5-c2d-text.js src/q5-ai.js src/q5-color.js src/q5-display.js src/q5-dom.js src/q5-input.js src/q5-math.js src/q5-record.js src/q5-sound.js src/q5-util.js src/q5-vector.js src/q5-webgpu-canvas.js src/q5-webgpu-drawing.js src/q5-webgpu-image.js src/q5-webgpu-text.js > q5.js",
 		"min": "terser q5.js --compress ecma=2024 --mangle > q5.min.js",
 		"dist": "bun bundle && bun min",
 		"dist-p5play": "bun dist && cp q5.js ../../web/p5play-web/v3/q5.js && cp q5.min.js ../../web/p5play-web/v3/q5.min.js",

package/q5.d.ts

@@ -7,6 +7,20 @@
 declare global {
 	// ⭐️ core
 
+	/** ⭐️
+	 * Welcome to q5's documentation! ☺️
+	 * 
+	 * First time coding? Check out the [q5 Beginner's Guide to JavaScript](https://github.com/q5js/q5.js/wiki/q5-Beginner's-Guide-to-JavaScript).
+	 * 
+	 * On these Learn pages you'll find concise descriptions for
+	 * q5's functions and variables. Scroll through entire topics without
+	 * needing to click between separate pages.
+	 * 
+	 * Experiment with editing the code in the interactive mini examples,
+	 * which are often only 8 lines of code or less. They automatically
+	 * update as you type, so you can see results right away.
+	 */
+
 	/** ⭐️
 	 * The draw function is run 60 times per second by default.
 	 * @example
@@ -480,6 +494,8 @@ square(80, 80, 80);
 	 * Like the [`color`](https://q5js.org/learn/#color) function, this function
 	 * can accept colors in a wide range of formats: as a CSS color string,
 	 * a `Color` object, grayscale value, or color component values.
+	 * 
+	 * Not available in q5 WebGPU.
 	 * @param {Color} color shadow color
 	 * @example
 createCanvas(200);
@@ -524,12 +540,14 @@ rect(104, 104, 80, 80);
 	 * @param {number} blur blur radius of the shadow, defaults to 0
 	 * @example
 createCanvas(200);
-background(200);
 noStroke();
-shadow('red');
+shadow(50);
 
-shadowBox(-20, -8, 50);
-circle(100, 100, 80, 80);
+function draw() {
+  background(200);
+	shadowBox(-20, mouseY, 10);
+	circle(100, 100, 80, 80);
+}
 	 * @example
 createCanvas(200);
 background(200);
@@ -767,6 +785,8 @@ square(0, 0, 50);
 	/** ⬜️
 	 * Any position coordinates or dimensions you use will be scaled based
 	 * on the unit provided to this function.
+	 * 
+	 * Not available in q5 WebGPU.
 	 * @param {number} unit unit to scale by
 	 * @example
 createCanvas(200);
@@ -778,6 +798,8 @@ rect(20, 20, 60, 60);
 
 	/** ⬜️
 	 * Creates a graphics buffer.
+	 * 
+	 * Not available in q5 WebGPU.
 	 * @param {number} w width
 	 * @param {number} h height
 	 * @param {Object} [opt] options
@@ -786,7 +808,8 @@ rect(20, 20, 60, 60);
 	function createGraphics(w: number, h: number, opt?: any): Q5;
 
 	/** ⬜️
-	 * The 2D rendering context for the canvas.
+	 * The 2D rendering context for the canvas, if using the Canvas2D
+	 * renderer.
 	 */
 	var ctx: CanvasRenderingContext2D;
 
@@ -798,7 +821,7 @@ rect(20, 20, 60, 60);
 	// 💻 display
 
 	/** 💻
-	 * The `displayMode` function lets you customize how your canvas is presented.
+	 * Customize how your canvas is presented.
 	 * @param {string} mode
 	 *   - "normal": (default) no styling to canvas or its parent element
 	 *   - "centered": canvas will be centered horizontally and vertically within its parent and if the window is smaller than the canvas, the canvas will be resized to avoid clipping
@@ -830,7 +853,7 @@ createCanvas(200, 100);
 background('crimson');
 	 * @example
 function draw() {
-	background(128, 20);
+	background(128, 100);
 	circle(mouseX, mouseY, 20);
 }
 	 */
@@ -1109,22 +1132,34 @@ point(125, 50);
 	// 📑 dom
 
 	/** 📑
-	 * Creates a new HTML element.
+	 * Creates a new HTML element and adds it to the page. `createEl` is
+	 * an alias.
 	 * 
-	 * q5 adds functions like `position` and `size` to the element
-	 * that make it easy to position elements above the canvas.
+	 * The element is part of the DOM (Document Object Model), an interface for
+	 * creating and editing web pages with JavaScript.
 	 * 
 	 * Modify the element's CSS [`style`](https://developer.mozilla.org/docs/Web/API/HTMLElement/style) to change its appearance.
 	 * 
-	 * `createEl` is an alias for this function.
+	 * Use [`addEventListener`](https://developer.mozilla.org/docs/Web/API/EventTarget/addEventListener) to respond to events such as:
+	 * - "click": when the element is clicked
+	 * - "mouseover": when the mouse hovers over the element
+	 * - "mouseout": when the mouse stops hovering over the element
+	 * - "input": when a form element's value changes
+	 * 
+	 * q5 adds some extra functionality to the elements it creates:
+	 * 
+	 * - the `position` function makes it easy to place the element
+	 * relative to the canvas
+	 * - the `size` function sets the width and height of the element
+	 * - alternatively, use the element's `x`, `y`, `width`, and `height` properties
 	 * @param {string} tag tag name of the element
 	 * @param {string} [content] content of the element
-	 * @returns {HTMLElement} created DOM element
+	 * @returns {HTMLElement} element
 	 * @example
 createCanvas(200);
 
 let el = createEl('div', '*');
-el.position(0, 0);
+el.position(50, 50);
 el.size(100, 100);
 el.style.fontSize = '136px';
 el.style.textAlign = 'center';
@@ -1139,18 +1174,20 @@ el.style.color = 'white';
 	 * @param {string} [text] text content
 	 * @param {boolean} [newTab] whether to open the link in a new tab
 	 * @example
-createCanvas(200, 100);
+createCanvas(200);
 
 let link = createA('https://q5js.org', 'q5.js');
-link.position(0, 0);
+link.position(16, 42);
 link.style.fontSize = '80px';
+
+link.addEventListener('mouseover', () => {
+	background('blue');
+});
 	 */
 	function createA(href: string, text?: string): HTMLAnchorElement;
 
 	/** 📑
 	 * Creates a button element.
-	 * 
-	 * Use [`addEventListener`](https://developer.mozilla.org/docs/Web/API/EventTarget/addEventListener) to respond to button click events.
 	 * @param {string} [content] text content
 	 * @example
 createCanvas(200, 100);
@@ -1177,7 +1214,7 @@ createCanvas(200, 100);
 let box = createCheckbox('Check me!');
 box.label.style.color = 'lime';
 
-box.addEventListener('change', () => {
+box.addEventListener('input', () => {
 	if (box.checked) background('lime');
 	else background('black');
 });
@@ -1202,7 +1239,7 @@ function draw() {
 	function createColorPicker(value?: string): HTMLInputElement;
 
 	/** 📑
-	 * Creates an img element.
+	 * Creates an image element.
 	 * @param {string} src url of the image
 	 * @example
 createCanvas(200, 100);
@@ -1280,10 +1317,12 @@ function draw() {
 	 * 
 	 * Set `multiple` to `true` to allow multiple options to be selected.
 	 * 
-	 * Use the `value` property to get or set the selected option.
+	 * Use the `value` property to get or set the selected option value.
 	 * 
-	 * Use the `selected` property to get the selected option or options.
-	 * @param {boolean} [placeholder] optional placeholder text that appears when no option is selected
+	 * Use the `selected` property get the labels of the selected 
+	 * options or set the selected options by label. Can be a single 
+	 * string or an array of strings.
+	 * @param {string} [placeholder] optional placeholder text that appears before an option is selected
 	 * @example
 createCanvas(200, 100);
 
@@ -1326,12 +1365,27 @@ function draw() {
 	 * @example
 createCanvas(200, 100);
 
+// example coming soon
 // let vid = createVideo('/assets/q5js_video.mp4');
 // vid.controls = true;
 // vid.loop = true;
 	 */
 	function createVideo(src: string): HTMLVideoElement;
 
+	/** 📑
+	 * Finds the first element in the DOM that matches the given [CSS selector](https://developer.mozilla.org/docs/Learn_web_development/Core/Styling_basics/Basic_selectors).
+	 * @param {string} selector
+	 * @returns {HTMLElement} element
+	 */
+	function findElement(selector: string): HTMLElement;
+
+	/** 📑
+	 * Finds all elements in the DOM that match the given [CSS selector](https://developer.mozilla.org/docs/Learn_web_development/Core/Styling_basics/Basic_selectors).
+	 * @param {string} selector
+	 * @returns {HTMLElement[]} elements
+	 */
+	function findElements(selector: string): HTMLElement[];
+
 	// 🌆 image
 
 	/** 🌆
@@ -1679,8 +1733,8 @@ function setup() {
 
 	/** 🌆
 	 * Creates a new image.
-	 * @param {number} [w] character limit per line
-	 * @param {number} [h] line limit
+	 * @param {number} w width
+	 * @param {number} h height
 	 * @param {any} [opt] optional settings for the image
 	 * @returns {Image}
 	 */
@@ -1710,6 +1764,7 @@ textSize(20);
 let info = "q5.js is a JavaScript library for creative coding. It's a sequel to p5.js that's optimized for interactive art.";
 
 text(info, 12, 30, 20, 6);
+//
 //
 	 */
 	function text(str: string, x: number, y: number, wrapWidth?: number, lineLimit?: number): void;
@@ -1991,20 +2046,22 @@ createCanvas(200);
 	 * @returns {Color} a new `Color` object
 	 * @example
 createCanvas(200);
-//                (gray, alpha)
-let darkGray = color(55, 100);
-background(darkGray);
-//	                  (r, g,   b,  a)
-let blueBottle = color(0, 0, 200, 20);
-fill(blueBottle);
-circle(100, 50, 50);
+rect(0, 0, 100, 200);
+
+//                ( r,   g,   b,   a)
+let bottle = color(90, 100, 255, 100);
+fill(bottle);
+stroke(bottle);
+strokeWeight(30);
+circle(100, 100, 155);
 	 * @example
 createCanvas(200);
-
-let c = color('gray');
+//          (gray, alpha)
+let c = color(200, 50);
 
 function draw() {
 	background(c);
+	circle(mouseX, mouseY, 50);
 	c.g = (c.g + 1) % 255;
 }
 	 */
@@ -2037,6 +2094,7 @@ colorMode(OKLCH);
 
 fill(0.25, 0.15, 0);
 rect(0, 0, 100, 200);
+
 fill(0.75, 0.15, 0)
 rect(100, 0, 100, 200);
 	 */
@@ -2405,6 +2463,75 @@ noCursor();
 	 */
 	const TAU: number;
 
+	// 🎞️ record
+
+	/** 🎞️
+	 * Creates a recorder. Simply hit record to start recording!
+	 * 
+	 * Recording large canvases is an intensive process, so your
+	 * computer may not be able to do it in real time. That's okay,
+	 * the resulting video will playback at your sketch's target 
+	 * frame rate.
+	 * 
+	 * In cases where real time interaction is a priority, consider 
+	 * reducing the canvas' size, frame rate, and/or recording
+	 * quality.
+	 * 
+	 * `format` and `quality` properties are set 
+	 * automatically based on the height of the canvas. They can be
+	 * changed via the UI or programmatically.
+	 * 
+	 * The recorder uses the [`MediaRecorder`](https://developer.mozilla.org/docs/Web/API/MediaRecorder/MediaRecorder) API, which 
+	 * unfortunately can't encode HDR video.
+	 * @returns {HTMLElement} a recorder, q5 DOM element
+	 * @example
+createCanvas(200);
+
+createRecorder();
+
+function draw() {
+	circle(mouseX, random(canvas.h), 10);
+}
+	 */
+	function createRecorder(): HTMLElement;
+
+	/** 🎞️
+	 * Starts recording the canvas or resumes recording if it was paused.
+	 * 
+	 * If no recorder exists, one is created but not displayed.
+	 */
+	function record(): void;
+
+	/** 🎞️
+	 * Pauses the canvas recording, if one is in progress.
+	 */
+	function pauseRecording(): void;
+
+	/** 🎞️
+	 * Discards the current recording.
+	 */
+	function deleteRecording(): void;
+
+	/** 🎞️
+	 * Saves the current recording as a video file.
+	 * @param {string} fileName
+	 * @example
+function draw() {
+	square(mouseX, random(canvas.h), 10);
+}
+
+function mousePressed() {
+	if (!recording) record();
+	else saveRecording('squares');
+}
+	 */
+	function saveRecording(fileName): void;
+
+	/** 🎞️
+	 * True if the canvas is currently being recorded.
+	 */
+	var recording: boolean;
+
 	// 🔊 sound
 
 	/** 🔊