color-elements 0.0.1 → 0.0.3

package/src/color-slider/color-slider.js

@@ -0,0 +1,320 @@
+import ColorElement from "../common/color-element.js";
+import { getStep } from "../common/util.js";
+
+let supports = {
+	inSpace: CSS?.supports("background", "linear-gradient(in oklab, red, tan)"),
+	fieldSizing: CSS?.supports("field-sizing", "content"),
+};
+
+const Self = class ColorSlider extends ColorElement {
+	static tagName = "color-slider";
+	static url = import.meta.url;
+	static shadowStyle = true;
+	static shadowTemplate = `
+		<input type="range" class="color-slider" part="slider" min="0" max="1" step="0.01" />
+			<slot name="tooltip" class="slider-tooltip">
+				<input type="number" part="spinner" min="0" max="1" step="0.01" />
+			</slot>
+		<slot></slot>`;
+
+	constructor () {
+		super();
+
+		this._el = {
+			slider: this.shadowRoot.querySelector(".color-slider"),
+			spinner: this.shadowRoot.querySelector("input[type=number]"),
+		};
+	}
+
+	connectedCallback () {
+		super.connectedCallback?.();
+
+		this._el.slider.addEventListener("input", this);
+		this._el.spinner.addEventListener("input", this);
+	}
+
+	disconnectedCallback () {
+		this._el.slider.removeEventListener("input", this);
+		this._el.spinner.removeEventListener("input", this);
+	}
+
+	handleEvent (event) {
+		if (event.type === "input") {
+			if (this.tooltip === "progress" && event.target === this._el.spinner) {
+				// Convert to value
+				let value = this._el.spinner.value;
+				this.value = this.valueAt(value / 100);
+			}
+			else {
+				this.value = event.target.value;
+			}
+
+			this.dispatchEvent(new event.constructor(event.type, {...event}));
+		}
+	}
+
+	propChangedCallback ({name, prop, detail: change}) {
+		if (["min", "max", "step", "value", "defaultValue"].includes(name)) {
+			prop.applyChange(this._el.slider, change);
+
+			let value = change.value;
+			if (this.tooltip === "progress") {
+				if (name === "value" || name === "defaultValue") {
+					value = +(this.progress * 100).toPrecision(4);
+				}
+				else {
+					// Spinner values when tooltip is "progress"
+					value = ({ min: 1, max: 100, step: 1 })[name];
+				}
+			}
+			prop.applyChange(this._el.spinner, {...change, value: +(+value).toPrecision(4)});
+		}
+
+		if (name === "stops") {
+			// FIXME will fail if there are none values
+			let stops = this.stops;
+			let supported = stops.every(color => CSS.supports("color", color));
+
+			// CSS does not support (yet?) a raw hue interpolation,
+			// so we need to fake it with tessellateStops() in cases of polar space and far-apart stops.
+			let farApart = false;
+			let space = this.space;
+			if (space.isPolar) {
+				for (let i = 1; i < stops.length; i++) {
+					// Even though space is polar, color stops might be in non-polar spaces
+					let first = stops[i - 1].to(space);
+					let second = stops[i].to(space);
+
+					let firstHue = first.get("h");
+					let secondHue = second.get("h");
+
+					if (Math.abs(firstHue - secondHue) >= 180) {
+						farApart = true;
+						break;
+					}
+				}
+			}
+
+			if (!supported || farApart) {
+				stops = this.tessellateStops({ steps: 3 });
+			}
+
+			stops = stops.map(color => color.display()).join(", ");
+
+			this.style.setProperty("--slider-color-stops", stops);
+		}
+		else if (name === "space" && supports.inSpace) {
+			let space = this.space;
+			let spaceId = space.id;
+			let supported = CSS.supports("background", `linear-gradient(in ${ spaceId }, red, tan)`);
+
+			if (!supported) {
+				spaceId = this.space.isPolar ? "oklch" : "oklab";
+			}
+
+			this.style.setProperty("--color-space", spaceId);
+		}
+		else if (name === "color" || name === "defaultColor") {
+			let color = this.color;
+
+			if (color) {
+				let displayedColor = color.display();
+				this.style.setProperty("--color", displayedColor);
+			}
+		}
+		else if (name === "value" || name === "min" || name === "max") {
+			this.style.setProperty("--progress", this.progress);
+
+			if (name === "value" && !supports.fieldSizing) {
+				let valueStr = this.value + "";
+				this._el.spinner.style.setProperty("--value-length", valueStr.length);
+			}
+		}
+		else if (name === "tooltip") {
+			if (change.value !== undefined) {
+				let values = this;
+				if (change.value === "progress") {
+					values = {
+						min: 1, max: 100, step: 1,
+						value: +(this.progress * 100).toPrecision(4),
+					};
+				}
+
+				["min", "max", "step", "value"].forEach(name => {
+					this._el.spinner[name] = values[name];
+				});
+			}
+		}
+	}
+
+	tessellateStops (options = {}) {
+		let stops = this.stops;
+		let tessellated = [];
+
+		for (let i = 1; i < stops.length; i++) {
+			let start = stops[i - 1];
+			let end = stops[i];
+			let steps = start.steps(end, { space: this.space, ...options });
+			tessellated.push(...steps);
+
+			if (i < stops.length - 1) {
+				tessellated.pop();
+			}
+		}
+
+		return tessellated;
+	}
+
+	get progress () {
+		return this.progressAt(this.value);
+	}
+
+	progressAt (value) {
+		return (value - this.min) / (this.max - this.min);
+	}
+
+	valueAt (progress) {
+		return this.min + progress * (this.max - this.min);
+	}
+
+	colorAt (value) {
+		let progress = this.progressAt(value);
+		return this.colorAtProgress(progress);
+	}
+
+	colorAtProgress (progress) {
+		let bands = this.scales?.length;
+
+		if (bands <= 0) {
+			return null;
+		}
+
+		// FIXME the values outside of [0, 1] should be scaled
+		if (progress >= 1) {
+			return this.scales.at(-1)(progress);
+		}
+		else if (progress <= 0) {
+			return this.scales[0](progress);
+		}
+
+		let band = 1 / bands;
+		let scaleIndex = Math.max(0, Math.min(Math.floor(progress / band), bands - 1));
+		let scale = this.scales[scaleIndex];
+		let color = scale((progress % band) * bands);
+
+		return color;
+	}
+
+	static props = {
+		min: {
+			type: Number,
+			default: 0,
+		},
+		max: {
+			type: Number,
+			default: 1,
+		},
+		step: {
+			type: Number,
+			default () {
+				return getStep(this.max, this.min, { minSteps: 100 });
+			},
+		},
+		stops: {
+			type: {
+				is: Array,
+				get values () {
+					return Self.Color;
+				},
+			},
+			default: el => [],
+		},
+		defaultValue: {
+			type: Number,
+			default () {
+				return (this.min + this.max) / 2;
+			},
+			reflect: {
+				from: "value",
+			},
+		},
+		value: {
+			type: Number,
+			defaultProp: "defaultValue",
+			reflect: false,
+		},
+
+		space: {
+			default () {
+				return this.stops[0]?.space ?? "oklab";
+			},
+			parse (value) {
+				if (value instanceof Self.Color.Space || value === null || value === undefined) {
+					return value;
+				}
+
+				value += "";
+
+				return Self.Color.Space.get(value);
+			},
+			stringify (value) {
+				return value?.id;
+			},
+		},
+
+		color: {
+			get type () {
+				return Self.Color;
+			},
+			get () {
+				return this.colorAt(this.value);
+			},
+			dependencies: ["scales", "value"],
+		},
+		scales: {
+			get () {
+				let stops = this.stops;
+				let scales = [];
+
+				for (let i = 1; i < stops.length; i++) {
+					let start = stops[i - 1];
+					let end = stops[i];
+					let range = start.range(end, { space: this.space });
+					scales.push(range);
+				}
+
+				return scales;
+			},
+			dependencies: ["stops", "space"],
+		},
+
+		tooltip: {
+			type: String,
+		},
+	};
+
+	static events = {
+		change: {
+			from () {
+				return this._el.slider;
+			},
+		},
+		valuechange: {
+			propchange: "value",
+		},
+		colorchange: {
+			propchange: "color",
+		},
+	};
+
+	static formAssociated = {
+		like: el => el._el.slider,
+		role: "slider",
+		valueProp: "value",
+		changeEvent: "valuechange",
+	};
+};
+
+Self.define();
+
+export default Self;

package/src/color-swatch/README.md

@@ -0,0 +1,359 @@
+# `<color-swatch>`
+
+## Examples
+
+### Basic usage
+
+<table>
+<thead>
+	<tr>
+		<th></th>
+		<th>Default</th>
+		<th>Large</th>
+	</tr>
+</thead>
+<tbody>
+<tr>
+<th>Static</th>
+<td>
+
+```html
+<color-swatch>oklch(70% 0.25 138)</color-swatch>
+```
+</td>
+<td>
+
+```html
+<color-swatch size="large">oklch(70% 0.25 138)</color-swatch>
+```
+</td>
+</tr>
+<tr>
+<th>Editable</th>
+<td>
+
+```html
+<color-swatch>
+	<input value="oklch(70% 0.25 138)" />
+</color-swatch>
+```
+</td>
+<td>
+
+```html
+<color-swatch size="large">
+	<input value="oklch(70% 0.25 138)" />
+</color-swatch>
+```
+</td>
+</tr>
+</tbody>
+</table>
+
+You can use a `--details-style: compact` CSS property to only show the details on user interaction:
+
+```html
+<color-swatch style="--details-style: compact">oklch(70% 0.25 138)</color-swatch>
+<color-swatch size="large" style="--details-style: compact">oklch(70% 0.25 138)</color-swatch>
+```
+
+Warning: This is not keyboard accessible by default.
+To make the element focusable and also show the popup when it is focused, you need to add `tabindex="0"` to your element:
+
+```html
+<color-swatch size="large" style="--details-style: compact" tabindex="0">oklch(70% 0.25 138)</color-swatch>
+```
+
+By default, the popup will be shown when the element is hovered, focused, `:active`, or the target of the URL hash.
+To circumvent user interaction and force the popup to be open use the `open` attribute.
+You can also use `open="false"` to force it to be closed regardless of interaction:
+
+```html
+<div style="--details-style: compact">
+	<color-swatch size="large">oklch(70% 0.25 138)</color-swatch>
+	<color-swatch size="large" open>oklch(70% 0.25 138)</color-swatch>
+	<color-swatch size="large" open="false">oklch(70% 0.25 138)</color-swatch>
+</div>
+```
+
+### The `value` attribute
+
+You can provide the color via the `value` attribute,
+which can be more convenient when you have slotted content.
+
+In that case, the content of the element is merely presentational
+(unless it’s an `<input>`).
+If you don’t specify any content, no text will be shown.
+
+<table>
+<thead>
+	<tr>
+		<th>Static</th>
+		<th>Editable</th>
+	</tr>
+</thead>
+<tbody>
+<tr>
+
+<td>
+
+```html
+<color-swatch value="oklch(70% 0.25 138)" size="large">red</color-swatch>
+```
+
+</td>
+<td>
+
+```html
+<color-swatch value="oklch(70% 0.25 138)" size="large">
+	<input />
+</color-swatch>
+```
+</td>
+
+</tr>
+</tbody>
+</table>
+
+You can also use this as a property when creating color swatches dynamically:
+
+```html
+<div id="future_swatch_container"></div>
+<script>
+let swatch = document.createElement("color-swatch");
+swatch.value = "oklch(65% 0.15 210)";
+swatch.setAttribute("size", "large");
+swatch.textContent = "Turquoise";
+future_swatch_container.append(swatch);
+</script>
+```
+
+### The `label` attribute
+
+You can provide the color label via the `label` attribute.
+
+<table>
+<thead>
+	<tr>
+		<th></th>
+		<th>Default</th>
+		<th>Large</th>
+	</tr>
+</thead>
+<tbody>
+<tr>
+<th>Static</th>
+<td>
+
+```html
+<color-swatch label="Turquoise">oklch(65% 0.15 210)</color-swatch>
+```
+</td>
+<td>
+
+```html
+<color-swatch label="Turquoise" size="large">oklch(65% 0.15 210)</color-swatch>
+```
+</td>
+</tr>
+<tr>
+<th>Editable</th>
+<td>
+
+```html
+<color-swatch label="Turquoise">
+	<input value="oklch(65% 0.15 210)" />
+</color-swatch>
+```
+</td>
+<td>
+
+```html
+<color-swatch label="Turquoise" size="large">
+	<input value="oklch(65% 0.15 210)" />
+</color-swatch>
+```
+</td>
+</tr>
+</tbody>
+</table>
+
+If the attribute's value matches the element's content, no additional text with the label will be shown.
+
+```html
+<color-swatch label="Turquoise" value="oklch(65% 0.15 210)" size="large">Turquoise</color-swatch>
+```
+
+If used as a property and is not defined via the `label` attribute, its value is that of the element text content.
+
+### The `info` attribute
+
+You can use the `info` attribute to show information about the color.
+Currently, the only type of information supported is color coords (in any color space), but more will be added in the future.
+
+```html
+<color-swatch info="oklch.l, oklch.c, oklch.h" size="large">
+	oklch(70% 0.25 138)
+</color-swatch>
+```
+
+By default, the label for each value will be determined automatically from the type of information (e.g. the full coord name if a coord),
+but you can customize this by adding a label before the description of the data:
+
+```html
+<color-swatch info="L: oklch.l, C: oklch.c, H: oklch.h" size="large">
+	oklch(70% 0.25 138)
+</color-swatch>
+```
+
+
+The `info` attribute plays quite nicely with the `--details-style: compact` style:
+
+```html
+<color-swatch size="large" info="oklch.l, oklch.c, oklch.h" style="--details-style: compact">oklch(70% 0.25 138)</color-swatch>
+```
+
+### With slot content
+
+Before and after:
+
+```html
+<color-swatch>
+	<label slot="before" for=c1>Accent color:</label>
+	<input value="oklch(70% 0.25 138)" id=c1 />
+</color-swatch>
+```
+
+```html
+<color-swatch>
+	<label slot="before" for=c1>Accent color:</label>
+	oklch(70% 0.25 138)
+</color-swatch>
+```
+
+```html
+<color-swatch size="large">
+	<label slot="before" for=c2>Accent color:</label>
+	<input value="oklch(70% 0.25 138)" id=c2 />
+	<small slot="after">Tip: Pick a bright medium color.</small>
+</color-swatch>
+```
+
+Adding text within the default swatch:
+
+```html
+<color-swatch size="large">
+	<div slot="swatch-content">Some text</div>
+	<input value="oklch(70% 0.25 138)" id=c1 />
+</color-swatch>
+```
+
+Note that the text color will automatically switch from black to white to remain readable (using [this technique](https://lea.verou.me/blog/2024/contrast-color/)).
+
+----
+
+Replacing the whole swatch with a custom element:
+
+```html
+<color-swatch size="large">
+	<div slot="swatch">Some text</div>
+	<input value="oklch(70% 0.25 138)" id=c1 />
+</color-swatch>
+```
+
+<!--
+### Bound to CSS property
+
+You can automatically bind the color swatch to a CSS property by setting the `property` attribute.
+Then you don’t need to provide an initial value, it will be read from the CSS property,
+and updating the color will update the CSS property.
+
+```html
+<color-swatch size="large" property="--color-red">
+	<input />
+</color-swatch>
+```
+
+You can use `scope` to select the closest ancestor (via a CSS selector) on which the CSS property will be read from and written to.
+If you don’t, the `<html>` element will be used.
+-->
+
+### Events
+
+```html
+<color-swatch size="large" oncolorchange="this.nextElementSibling.textContent = this.color">
+	<input value="oklch(70% 0.25 138)" />
+</color-swatch>
+<color-inline></color-inline>
+```
+
+### Update via JS
+
+#### Static
+
+```html
+<color-swatch id="dynamic_static">oklch(70% 0.25 138)</color-swatch>
+<button onclick='dynamic_static.color = "oklch(60% 0.15 0)"'>Change color</button>
+```
+
+### Editable
+
+```html
+<color-swatch id="dynamic_editable">
+	<input value="oklch(70% 0.25 138)" />
+</color-swatch>
+<button onclick='dynamic_editable.color = "oklch(60% 0.15 0)"'>Change color</button>
+```
+
+## Reference
+
+### Attributes & Properties
+
+| Attribute | Property | Property type | Default value | Description |
+|-----------|----------|---------------|---------------|-------------|
+| `color` | `color` | `Color` &#124; `string` | - | The current color value. |
+| `info` | `info` | `string` | - | Comma-separated list of coords of the current color to be shown. |
+| `value` | `value` | `string` | - | The current value of the swatch. |
+| `label` | `label` | `string` | - | The label of the swatch (e.g., color name). Defaults to the element text content. |
+| `size` | - | `large` | - | The size of the swatch. Currently, it is used only to make a large swatch. |
+| `property` | `property` | `string` | - | CSS property to bind to. |
+| `scope` | `scope` | `string` | `:root` | CSS selector to use as the scope for the specified CSS property. |
+| `gamuts` | `gamuts` | `string` | `srgb, p3, rec2020: P3+, prophoto: PP` | Comma-separated list of gamuts to be used by the gamut indicator. |
+| `open` | `open` | | `null` | Force the details popup open or closed. |
+
+### Getters
+
+These properties are read-only.
+
+| Name | Type | Description |
+|----------|------|-------------|
+| `gamut` | `string` | The id of the current gamut (e.g. `srgb`). |
+
+### CSS variables
+
+| Name | Type | Description |
+|----------|---------------|-------------|
+| `--details-style` | `compact` &#124; `normal` (default) | |
+| `--transparency-grid` | `<image>` | Gradient used as a background for transparent parts of the swatch. |
+| `--transparency-cell-size` | `<length>` | The size of the cells of the transparency gradient. |
+| `--transparcency-background` | `<color>` | The background color of the transparency gradient. |
+| `--transparency-darkness` | `<percentage>` | The opacity of the black color used for dark parts of the transparency gradient. |
+
+### Parts
+
+| Name | Description |
+|------|-------------|
+| `swatch` | The swatch used to render the color. |
+| `details` | Wrapper around all non-swatch content (color name, info, etc) |
+| `label` | The label of the swatch |
+| `color-wrapper` | Wrapper around the color name itself |
+| `gamut` | Gamut indicator |
+| `info` | Any info generateed by the `info` attribute |
+
+### Events
+
+| Name | Description |
+|------|-------------|
+| `valuechange` | Fired when the value changes for any reason, and once during initialization. |
+| `colorchange` | Fired when the color changes for any reason, and once during initialization. |
+| `gamutchange` | Fired when the gamut changes for any reason, and once during initialization. |