color-elements 0.0.2 → 0.0.4

package/src/common/util.js

@@ -1,104 +1,64 @@
-/**
- * Defines instance properties by defining an accessor that automatically replaces itself with a writable property when accessed.
- * @param {Function} Class
- * @param {string} name
- * @param {function} getValue
- */
-export function defineInstanceProperty (
-	Class, name, getValue,
-	{writable = true, configurable = true, enumerable = false} = {}) {
-	let setter = function (value) {
-		Object.defineProperty(this, name, { value, writable, configurable, enumerable });
+export async function wait (ms) {
+	if (ms === undefined) {
+		return new Promise(resolve => requestAnimationFrame(resolve));
 	}
-	Object.defineProperty(Class.prototype, name, {
-		get () {
-			let value = getValue.call(this, this);
-			setter.call(this, value);
-			return value;
-		},
-		set (value) { // Blind set
-			setter.call(this, value);
-		},
-		configurable: true,
-	});
+
+	return new Promise(resolve => setTimeout(resolve, ms));
 }
 
-export function defineLazyProperty (object, name, options) {
-	if (typeof options === "function") {
-		options = { get: options };
-	}
+export function defer (executor) {
+	let res, rej;
 
-	let {get, writable = true, configurable = true, enumerable = false} = options;
+	let promise = new Promise((resolve, reject) => {
+		res = resolve;
+		rej = reject;
 
-	let setter = function (value) {
-		Object.defineProperty(this, name, { value, writable, configurable, enumerable });
-	}
-	Object.defineProperty(object, name, {
-		get () {
-			let value = get.call(this);
-			setter.call(this, value);
-			return value;
-		},
-		set (value) { // Blind set
-			setter.call(this, value);
-		},
-		configurable: true,
+		executor?.(res, rej);
 	});
-}
 
-export function defineComputed (Class, computed = Class.computed) {
-	let dependencies = new Map();
+	promise.resolve = res;
+	promise.reject = rej;
 
-	for (let name in computed) {
-		let spec = computed[name];
-		defineInstanceProperty(Class, name, spec.get);
+	return promise;
+}
 
-		if (spec.dependencies) {
-			for (let prop of spec.dependencies) {
-				let deps = dependencies.get(prop) ?? [];
-				deps.push(name);
-				dependencies.set(prop, deps);
-			}
+/**
+ * Wait for all promises to resolve. Supports dynamically adding promises to the list after the initial call.
+ * @param {Promise[] | Set<Promise>} promises
+ * @returns {Promise}
+ */
+export async function dynamicAll (promises) {
+	let all = new Set([...promises]);
+	let unresolved = new Set();
+
+	for (let promise of promises) {
+		if (promise?.then) {
+			unresolved.add(promise);
+			promise.then(() => {
+				// Remove the promise from the list
+				unresolved.delete(promise);
+			});
 		}
 	}
 
-	if (dependencies.size > 0) {
-		let _propChangedCallback = Class.prototype.propChangedCallback;
+	return Promise.all(unresolved).then(resolved => {
+		// Check if the array has new items
+		for (let promise of promises) {
+			if (!all.has(promise)) {
+				all.add(promise);
 
-		Class.prototype.propChangedCallback = function(name, change) {
-			if (dependencies.has(name)) {
-				for (let prop of dependencies.get(name)) {
-					this[prop] = computed[prop].get.call(this, this);
+				if (promise?.then) {
+					unresolved.add(promise);
 				}
 			}
-
-			_propChangedCallback?.call(this, name, change);
 		}
-	}
-}
-
-export function inferDependencies (fn) {
-	if (!fn || typeof fn !== "function") {
-		return [];
-	}
 
-	let code = fn.toString();
-
-	return [...code.matchAll(/\bthis\.([$\w]+)\b/g)].map(match => match[1]);
-}
-
-export async function wait (ms) {
-	return new Promise(resolve => setTimeout(resolve, ms));
-}
-
-export async function nextTick (refreshRate = 20) {
-	let now = performance.now();
-	let remainder = now % refreshRate;
-	let delay = refreshRate - remainder;
-	let nextAt = now + delay;
-	nextTick.start ??= now - remainder;
+		if (unresolved.size > 0) {
+			return dynamicAll(unresolved).then(r => [...resolved, ...r]);
+		}
 
-	return new Promise(resolve => setTimeout(() => resolve(nextAt - nextTick.start), delay));
+		return resolved;
+	});
 }
 
 /**
@@ -139,4 +99,22 @@ export function pick (obj, properties) {
 	}
 
 	return Object.fromEntries(Object.entries(obj).filter(([key]) => properties.includes(key)));
-}
+}
+
+export function getType (value) {
+	if (value === null || value === undefined) {
+		return value + "";
+	}
+
+	return Object.prototype.toString.call(value).slice(8, -1);
+}
+
+/**
+ * Template tag that does nothing. Useful for importing under different names (e.g. `css`) for syntax highlighting.
+ * @param {string[]} strings
+ * @param {...any} values
+ * @returns {string}
+ */
+export function noOpTemplateTag (strings, ...values) {
+	return strings.reduce((acc, string, i) => acc + string + (values[i] ?? ""), "");
+}

package/src/gamut-badge/README.md

@@ -0,0 +1,145 @@
+<script src="gamut-badge.js" type="module"></script>
+# &lt;gamut-badge>
+
+Gamut indicator. Used internally by `<color-swatch>`
+
+## Usage
+
+Static (only read once):
+```html
+<gamut-badge color="red"></gamut-badge>
+```
+
+Invalid color:
+```html
+<gamut-badge color="poop"></gamut-badge>
+```
+Missing color:
+```html
+<gamut-badge></gamut-badge>
+```
+
+Dynamic:
+```html
+<gamut-badge id="cg_1" color="red"></gamut-badge>
+<script>cg_1.color = "oklch(50% 0.5 180)";</script>
+```
+
+## Demo
+<style>
+	#params {
+		background: linear-gradient(to right, var(--start-color), var(--end-color)) no-repeat top / 100% 1em;
+		padding-top: 1.5em;
+	}
+
+	#colors_container_h {
+		display: flex;
+		height: 1em;
+		margin-bottom: 1em;
+
+		gamut-badge {
+			flex: 1;
+			border-radius: 0;
+
+			&::part(label) {
+				display: none;
+			}
+		}
+	}
+</style>
+<form id=params>
+<code>oklch(<input type=number id=l value=50>% <input type=number id=min_c value=30>&ndash;<input type=number id=max_c value=40>% <input type=number id=h value=50>)</code>
+<p><label>Chroma increments: <input type=number id=c_step value="0.2" min="0">%</label>
+</form>
+
+<script type=module>
+params.addEventListener("input", e => {
+	let c_range = {min: Number(min_c.value), max: Number(max_c.value)};
+	let step = Number(c_step.value);
+	if (step <= 0) {
+		step = 1;
+	}
+	let colors = [];
+	let start = `oklch(${l.value}% ${c_range.min.toLocaleString("en")}% ${h.value})`;
+	let end = `oklch(${l.value}% ${c_range.max.toLocaleString("en")}% ${h.value})`;
+
+	params.style.setProperty("--start-color", start);
+	params.style.setProperty("--end-color", end);
+
+	for (let c = c_range.min; c<= c_range.max; c+=step) {
+		colors.push(`oklch(${l.value}% ${c.toLocaleString("en")}% ${h.value})`);
+	}
+
+	let html = colors.map(color => `
+		<gamut-badge title="${color}" color="${color}"></gamut-badge>`).join("\n");
+	colors_container_h.innerHTML = html;
+	colors_container.innerHTML = html;
+});
+params.dispatchEvent(new Event("input"));
+</script>
+
+No label:
+
+<div id=colors_container_h></div>
+
+Default display:
+<div id=colors_container></div>
+
+## Reference
+
+### Attributes & Properties
+
+| Attribute | Property | Property type | Default value | Description |
+|-----------|----------|---------------|---------------|-------------|
+| `gamuts` | `gamuts` | `string` &#124; `Array<string>` &#124; `object` | `["srgb", "p3", "rec2020", "prophoto"]` | A list of gamuts to use. |
+| `color` | `color` | `Color` &#124; `string` | - | The current color value. |
+
+### Getters
+
+These properties are read-only.
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `gamut` | `string` | The id of the current gamut (e.g. `srgb`). |
+| `gamutLabel` | `string` | The label of the current gamut (e.g. `sRGB`). |
+| `gamutInfo` | `object` | Metadata about the current gamut (label, id, level). |
+
+### Events
+
+| Name | Description |
+|------|-------------|
+| `gamutchange` | Fired when the gamut changes for any reason, and once during initialization. |
+
+### Slots
+
+| Slot | Description |
+|------|-------------|
+| _(default)_ | Custom content |
+
+### CSS variables
+
+| Variable | Type | Default value | Description |
+|----------|------|---------------|-------------|
+| `--color-green` | `<color>` | | Starting color of the background color scale. Used when the color is within the first gamut. |
+| `--color-yellow` | `<color>` | | Yellow color to be used at around 33.3% of the color scale Will be used for the second gamut if there are four total. |
+| `--color-orange` | `<color>` | | Orange color to be used at around 66.6% of the color scale. Will be used for the third gamut if there are four total. |
+| `--color-red` | `<color>` | | Red color to be used as the last stop of the color scale. Used when the color is within the last gamut. |
+| `--color-red-dark` | `<color>` | | Dark red background color of gamut indicator. Used when the provided color fits none of the specified gamuts. |
+| `--color-invalid` | `<color>` | | Background color of gamut indicator when the provided color is invalid. |
+
+#### Output-only CSS variables
+
+These variables are set by the component.
+You can write CSS that reacts to them, but you should not set them yourself unless you *really* know what you’re doing.
+
+| Variable | Type | Default value | Description |
+|----------|------|---------------|-------------|
+| `--gamut-color` | `<color>` | | Background color of gamut indicator. Will override the color that depends on the actual gamut, so you should rarely use this directly. |
+| `--gamut-level` | `<integer>` | - | The index of the gamut the current color fits in, starting from 0. You can use this in styling, but don’t overwrite it. |
+
+### CSS Parts
+
+| Part | Description |
+|------|-------------|
+| `label` | The label of the gamut indicator. Does not apply if the element has content. |
+

package/src/gamut-badge/gamut-badge.css

@@ -0,0 +1,78 @@
+:host {
+	--_color-green: var(--color-green, yellowgreen);
+	--_color-yellow: var(--color-yellow, gold);
+	--_color-orange: var(--color-orange, orange);
+	--_color-red: var(--color-red, red);
+	--_color-red-dark: var(--color-red-dark, #a00);
+	--_color-invalid: var(--color-invalid, hsl(220 10% 60%));
+
+	/* Low-level scales, i.e. between pairs of our core colors */
+	--color-scale-1: color-mix(in oklch, var(--_color-green), var(--_color-yellow) var(--progress-1));
+	--color-scale-2: color-mix(in oklch, var(--_color-yellow), var(--_color-orange) var(--progress-2));
+	--color-scale-3: color-mix(in oklch, var(--_color-orange), var(--_color-red) var(--progress-3));
+
+	/* Recursive scales: their only purpose is to select one of the low-level scales, and will only ever have 0%/100% positions
+	   For N colors there are N-2 + N-3 + ... + 1 = (N-1)(N-2) / 2 of these
+	*/
+	--color-scale-12: color-mix(in oklch, var(--color-scale-1), var(--color-scale-2) var(--progress-12));
+	--color-scale-23: color-mix(in oklch, var(--color-scale-2), var(--color-scale-3) var(--progress-23));
+	--color-scale-123: color-mix(in oklch, var(--color-scale-12), var(--color-scale-23) var(--progress-123));
+
+	--gamut-progress: calc(var(--gamut-level) / (var(--gamut-count) - 1));
+	--progress-ext: calc(var(--gamut-progress) * 300%);
+
+	--progress-123: clamp(0%, (var(--progress-ext) - 150%)       * infinity, 100%);
+	--progress-12:  clamp(0%, (var(--progress-ext) - 150% + 75%) *  infinity, 100%);
+	--progress-23:  clamp(0%, (var(--progress-ext) - 150% - 75%) * infinity, 100%);
+
+	--progress-1:   clamp(0%, var(--progress-ext), 100%);
+	--progress-2:   calc(clamp(100%, var(--progress-ext), 200%) - 100%);
+	--progress-3:   calc(clamp(200%, var(--progress-ext), 300%) - 200%);
+
+	--color-level-infinity: var(--_color-red-dark);
+	--color: var(--color-scale-123, var(--_color-invalid));
+
+	display: inline-flex;
+	align-items: center;
+	justify-content: center;
+	border-radius: .2em;
+	color: white;
+	background-color: var(--color);
+	font-weight: bold;
+	padding-inline: .4em;
+	line-height: 1.4;
+
+	/* See https://lea.verou.me/blog/2024/contrast-color/ */
+	--l: clamp(0, (l / var(--l-threshold, 0.7) - 1) * -infinity, 1);
+	color: oklch(from var(--color) var(--l) 0 h);
+}
+
+:host([gamut="none"]) {
+	background-color: var(--color-level-infinity);
+}
+
+#label {
+	&::before {
+		content: var(--gamut-label, "N/A");
+	}
+
+	@supports not (color: color(from red xyz-d65 y y y)) {
+		/* https://miunau.com/posts/dynamic-text-contrast-in-css/ */
+		filter: invert(1) grayscale(1) brightness(1.3) contrast(9000);
+		mix-blend-mode: luminosity;
+	}
+
+	@supports (color: color(from red xyz-d65 y y y)) {
+		/* https://lea.verou.me/blog/2024/contrast-color/ */
+		--y-threshold: 0.36;
+		--y: clamp(0, (var(--y-threshold) - y) * infinity, 1);
+
+		color: color(from var(--color) xyz-d65 var(--y) var(--y) var(--y));
+	}
+}
+
+@property --color {
+	syntax: "<color>";
+	inherits: true;
+	initial-value: transparent;
+}

package/src/gamut-badge/gamut-badge.js

@@ -0,0 +1,121 @@
+import ColorElement from "../common/color-element.js";
+
+const Self = class GamutBadge extends ColorElement {
+	static tagName = "gamut-badge";
+	static url = import.meta.url;
+	static styles = "./gamut-badge.css";
+	static shadowTemplate = `
+		<slot>
+			<span id="label" part="label"></span>
+		</slot>`;
+
+	#label;
+
+	constructor () {
+		super();
+
+		if (!this.#label) {
+			this.#label = this.shadowRoot.querySelector("#label");
+		}
+	}
+
+	get gamutLabel () {
+		return this.gamutInfo?.label ?? "";
+	}
+
+	propChangedCallback ({name, prop, detail: change}) {
+		if (name === "gamuts") {
+			this.style.setProperty("--gamut-count", this.gamuts.length - 1);
+		}
+
+		if (name === "gamutInfo") {
+			if (this.gamutInfo) {
+				this.style.setProperty("--gamut-level", this.gamutInfo.level);
+				this.style.setProperty("--gamut-label", `"${ this.gamutInfo.label }"`);
+				this.style.setProperty("--gamut-id", `"${ this.gamutInfo.id }"`);
+			}
+			else {
+				this.style.removeProperty("--gamut-level");
+				this.style.removeProperty("--gamut-label");
+				this.style.removeProperty("--gamut-id");
+			}
+		}
+	}
+
+	static props = {
+		color: {
+			get type () {
+				return Self.Color;
+			},
+		},
+		gamuts: {
+			type: Array,
+			default: "srgb, p3, rec2020, prophoto",
+			parse (gamuts) {
+				if (!gamuts) {
+					return [];
+				}
+
+				if (typeof gamuts === "string") {
+					gamuts = gamuts.trim().split(/\s*,\s*/);
+				}
+				else if (!Array.isArray(gamuts) && typeof gamuts === "object") {
+					// Object
+					return Object.entries(gamuts).map(([id, label]) => ({id, label}));
+				}
+
+				let ret = gamuts.map((gamut, level) => {
+					if (gamut?.id && "label" in gamut) {
+						// Already in the correct format
+						return gamut;
+					}
+
+					gamut = gamut.trim().split(/\s*:\s*/);
+					let id = gamut[0];
+					let label = gamut[1] ?? Self.Color.spaces[id]?.name ?? id;
+					return {id, label, level};
+				});
+
+				if (!ret.find(gamut => gamut.id === "none")) {
+					ret.push({
+						id: "none",
+						get label () {
+							return ret[this.level - 1].label + "+";
+						},
+						level: ret.length,
+					});
+				}
+
+				return ret;
+			},
+			stringify (gamuts) {
+				return gamuts.map(({id, label}) => `${ id }: ${ label }`).join(", ");
+			},
+		},
+		gamutInfo: {
+			get () {
+				if (!this.color) {
+					return null;
+				}
+
+				return this.gamuts?.find(gamut => gamut.id === "none" || this.color?.inGamut(gamut.id));
+			},
+		},
+		gamut: {
+			type: String,
+			get () {
+				return this.gamutInfo?.id;
+			},
+		},
+	};
+
+	static events = {
+		gamutchange: {
+			propchange: "gamut",
+		},
+	};
+};
+
+Self.define();
+
+export default Self;

package/src/index.js.njk

@@ -2,6 +2,6 @@
 permalink: "index.js"
 layout: null
 ---
-{% for name in components -%}
+{% for name, description in components -%}
 export { default as {{ name | tag_to_class }} } from "./src/{{ name }}/{{ name }}.js";
 {% endfor %}

package/src/space-picker/README.md

@@ -0,0 +1,121 @@
+# `<space-picker>`
+
+## Usage
+
+### Basic usage
+
+```html
+<space-picker value="oklab"></space-picker>
+```
+
+If no color space is provided (via the `value` attribute/property),
+the first one will be used:
+
+```html
+<space-picker></space-picker>
+```
+
+You can specify what color spaces to use:
+```html
+<space-picker spaces="oklch, p3, srgb" value="p3"></space-picker>
+```
+
+Unknown color spaces also work:
+```html
+<space-picker spaces="bar, oklch, p3, srgb, foo" value="foo"></space-picker>
+```
+
+### Custom labels
+
+Do you need the picker to show something other than the default color space names, such as color space ids?
+Simply define the `getSpaceLabel()` method on the picker instance, and you are done.
+The method takes a color space object as an argument and returns a string that will be used as the space label.
+
+```html
+<space-picker id="custom_labels"></space-picker>
+
+<script>
+    custom_labels.getSpaceLabel = space => space.id;
+</script>
+```
+
+### Grouping the color spaces
+
+You can group the color spaces the way you like by specifying the `groupBy` property. Its value is a function
+accepting a color space as an argument and returning the name of a group the color space should be added to:
+
+```html
+<space-picker id="space_picker" spaces="oklch, p3, srgb" value="p3"></space-picker>
+<script>
+    space_picker.groupBy = (space) => {
+        let isPolar = space.coords.h?.type === "angle";
+        return isPolar ? "Polar" : "Rectangular";
+    };
+</script>
+```
+
+### Events
+
+You can listen to the `spacechange` event to get either the id of the current color space (the `value` property)
+or the color space object itself (the `selectedSpace` property):
+
+```html
+<space-picker onspacechange="this.nextElementSibling.textContent = this.value"></space-picker>
+<output></output>
+```
+
+### Dynamic
+
+All properties are reactive and can be set programmatically:
+```html
+<button onclick="this.nextElementSibling.value = 'oklch'">Switch to OKLCh</button>
+<space-picker value="p3"></space-picker>
+```
+
+`<space-picker>` plays nicely with other color elements:
+```html
+<label style="display: block; margin-block-end: .5em">
+    Space:
+    <space-picker value="oklch" oninput="this.parentElement.nextElementSibling.space = this.selectedSpace"></space-picker>
+</label>
+<color-slider space="oklch"
+              stops="oklch(80% 50% 70), oklch(65% 50% 180)"
+              oncolorchange="this.nextElementSibling.textContent = this.color"></color-slider>
+<color-inline></color-inline>
+```
+
+## Reference
+
+### Attributes & Properties
+
+| Attribute | Property  | Property type                       | Default value                           | Description                                                                                               |
+|-----------|-----------|-------------------------------------|-----------------------------------------|-----------------------------------------------------------------------------------------------------------|
+| `value`   | `value`   | `string`                            | The first color space in `this.spaces`. | The current value of the picker.                                                                          |
+| `spaces`  | `spaces`  | `string` &#124; `Array<ColorSpace>` | All known color spaces.                 | Comma-separated list of color spaces to use.                                                              |
+| —         | `groupBy` | `Function`                          | —                                       | Function to group the color spaces. Takes a color space object as an argument and returns the group name. |
+| – | `getSpaceLabel` | `Function` | `space => space.name` | Function to get the label for a color space. Takes a color space object as an argument and returns its label. |
+
+### Getters
+
+These properties are read-only.
+
+| Property        | Type         | Description                                                                                                                                                                                |
+|-----------------|--------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| `selectedSpace` | `ColorSpace` | Color space object corresponding to the picker current value.                                                                                                                              |
+| `groups`        | `Object`     | Object containing the color spaces grouped by the `groupBy()` function. Keys are group names, values are objects with space ids as keys, and corresponding color space objects are values. |
+
+
+### Events
+
+| Name          | Description                                                                  |
+|---------------|------------------------------------------------------------------------------|
+| `input`       | Fired when the space changes due to user action.                             |
+| `change`      | Fired when the space changes due to user action.                             |
+| `valuechange` | Fired when the value changes for any reason, and once during initialization. |
+| `spacechange` | Fired when the space changes for any reason, and once during initialization. |
+
+### Parts
+
+| Name     | Description                      |
+|----------|----------------------------------|
+| `base` | The internal `<select>` element. |

package/src/space-picker/space-picker.css

@@ -0,0 +1,23 @@
+:host {
+	--border-width: 1px;
+	--border-color: rgb(0 0 0 / .2);
+	--border-radius: .2em;
+
+	padding: .3em .5em;
+
+	border-radius: var(--border-radius);
+	border: var(--border-width) solid var(--border-color);
+}
+
+#picker {
+	font: inherit;
+	color: inherit;
+	background: inherit;
+	border: none;
+	field-sizing: content;
+	cursor: pointer;
+
+	&:focus:not(:focus-visible) {
+		outline: none;
+	}
+}