@thebuoyant-tsdev/mui-ts-library 3.12.0 → 3.13.0

package/dist/components/color-picker/ColorPicker.types.d.ts

@@ -0,0 +1,65 @@
+export type ColorPickerFormat = "hex" | "rgb" | "hsl";
+/** Clean payload passed to `onChange` alongside the primary hex string — no internal HSV state exposed. */
+export type ColorPickerColorInfo = {
+    hex: string;
+    rgb: {
+        r: number;
+        g: number;
+        b: number;
+        a: number;
+    };
+    hsl: {
+        h: number;
+        s: number;
+        l: number;
+        a: number;
+    };
+};
+export type ColorPickerTranslation = {
+    formatLabel: string;
+    hexFieldLabel: string;
+    redLabel: string;
+    greenLabel: string;
+    blueLabel: string;
+    hueFieldLabel: string;
+    saturationFieldLabel: string;
+    lightnessFieldLabel: string;
+    alphaFieldLabel: string;
+    eyeDropperLabel: string;
+    savedColorsLabel: string;
+    gradientAreaLabel: string;
+    hueSliderLabel: string;
+};
+export declare const DEFAULT_COLOR_PICKER_TRANSLATION: Required<ColorPickerTranslation>;
+export type ColorPickerProps = {
+    /** Current color — accepts hex (#rgb, #rgba, #rrggbb, #rrggbbaa), rgb()/rgba(), or hsl()/hsla(). */
+    value: string;
+    /** Fires on every change — live while dragging, on every valid keystroke, and on swatch/eyedropper picks — with a normalized hex string plus a clean rgb/hsl breakdown. */
+    onChange: (hex: string, info: ColorPickerColorInfo) => void;
+    /** Fires once per "gesture" instead of continuously: on pointer-up after a drag, on blur after typing, or immediately for atomic actions (swatch click, eyedropper). Same dual-callback pattern as MUI's own `Slider` — use this instead of debouncing `onChange` yourself for expensive side effects (persisting to a backend, etc.). */
+    onChangeCommitted?: (hex: string, info: ColorPickerColorInfo) => void;
+    /** Initial display format for the value field — uncontrolled after mount (default: 'hex'). */
+    defaultFormat?: ColorPickerFormat;
+    /** Fires when the user switches the display format via the dropdown. */
+    onFormatChange?: (format: ColorPickerFormat) => void;
+    /** Shows the alpha slider and opacity field (default: true). */
+    showAlpha?: boolean;
+    /** Shows the eyedropper tool — auto-hidden when the browser doesn't support the EyeDropper API regardless of this prop (default: true). */
+    showEyeDropper?: boolean;
+    /** Shows the eyedropper button + hue/alpha slider row (default: true). Set `false` for a minimal gradient-area-only picker. */
+    showSliderSection?: boolean;
+    /** Shows the format dropdown + hex/RGB/HSL/alpha value fields row (default: true). Set `false` for a slider-only picker. */
+    showInputSection?: boolean;
+    /** Swatches shown below the picker — click to select. Purely a display list; the caller owns persistence. */
+    savedColors?: string[];
+    disabled?: boolean;
+    /** Scales the gradient area, slider thickness, and swatch size (default: 'medium'). */
+    colorGradientSize?: "small" | "medium";
+    /** Size of the format dropdown and value/alpha input fields, independent of `colorGradientSize` (default: 'medium'). */
+    inputSize?: "small" | "medium";
+    /** Overall panel width in px (default: 280). */
+    width?: number;
+    /** Form-integration: renders a hidden input so the value participates in native/React Hook Form/Formik form submission. */
+    name?: string;
+    translation?: Partial<ColorPickerTranslation>;
+};

package/dist/components/color-picker/ColorPicker.types.js

@@ -0,0 +1,18 @@
+//#region src/components/color-picker/ColorPicker.types.ts
+var e = {
+	formatLabel: "Color format",
+	hexFieldLabel: "Hex value",
+	redLabel: "Red",
+	greenLabel: "Green",
+	blueLabel: "Blue",
+	hueFieldLabel: "Hue",
+	saturationFieldLabel: "Saturation",
+	lightnessFieldLabel: "Lightness",
+	alphaFieldLabel: "Alpha",
+	eyeDropperLabel: "Pick color from screen",
+	savedColorsLabel: "Saved colors",
+	gradientAreaLabel: "Saturation and brightness",
+	hueSliderLabel: "Hue"
+};
+//#endregion
+export { e as DEFAULT_COLOR_PICKER_TRANSLATION };

package/dist/components/color-picker/util/colorConversion.util.d.ts

@@ -0,0 +1,51 @@
+export type RgbaColor = {
+    r: number;
+    g: number;
+    b: number;
+    a: number;
+};
+export type HsvaColor = {
+    h: number;
+    s: number;
+    v: number;
+    a: number;
+};
+export type HslaColor = {
+    h: number;
+    s: number;
+    l: number;
+    a: number;
+};
+export declare function clamp(value: number, min: number, max: number): number;
+export declare function rgbaToHex({ r, g, b, a }: RgbaColor): string;
+export declare function hexToRgba(hex: string): RgbaColor | null;
+export declare function hsvToRgb(h: number, s: number, v: number): {
+    r: number;
+    g: number;
+    b: number;
+};
+export declare function rgbToHsv(r: number, g: number, b: number): {
+    h: number;
+    s: number;
+    v: number;
+};
+export declare function hslToRgb(h: number, s: number, l: number): {
+    r: number;
+    g: number;
+    b: number;
+};
+export declare function rgbToHsl(r: number, g: number, b: number): {
+    h: number;
+    s: number;
+    l: number;
+};
+export declare function hsvaToRgba({ h, s, v, a }: HsvaColor): RgbaColor;
+export declare function rgbaToHsva({ r, g, b, a }: RgbaColor): HsvaColor;
+export declare function hsvaToHsla({ h, s, v, a }: HsvaColor): HslaColor;
+export declare function hslaToHsva({ h, s, l, a }: HslaColor): HsvaColor;
+/** Accepts #hex (3/4/6/8 digits), rgb()/rgba(), and hsl()/hsla() — returns null when unparseable. */
+export declare function parseColorString(input: string): RgbaColor | null;
+export declare function formatRgbString({ r, g, b, a }: RgbaColor): string;
+export declare function formatHslString({ h, s, l, a }: HslaColor): string;
+/** WCAG-style luminance heuristic — picks black or white text for readable contrast on a given background. */
+export declare function getContrastTextColor(r: number, g: number, b: number): "#000000" | "#ffffff";

package/dist/components/color-picker/util/colorConversion.util.js

@@ -0,0 +1,166 @@
+//#region src/components/color-picker/util/colorConversion.util.ts
+function e(e, t, n) {
+	return Math.min(n, Math.max(t, e));
+}
+function t(t) {
+	return e(Math.round(t), 0, 255).toString(16).padStart(2, "0");
+}
+function n({ r: e, g: n, b: r, a: i }) {
+	let a = `#${t(e)}${t(n)}${t(r)}`;
+	return i < 1 ? `${a}${t(i * 255)}` : a;
+}
+function r(e) {
+	let t = e.trim().replace(/^#/, ""), n, r, i, a = 1;
+	if (t.length === 3 || t.length === 4) n = parseInt(t[0] + t[0], 16), r = parseInt(t[1] + t[1], 16), i = parseInt(t[2] + t[2], 16), t.length === 4 && (a = parseInt(t[3] + t[3], 16) / 255);
+	else if (t.length === 6 || t.length === 8) n = parseInt(t.slice(0, 2), 16), r = parseInt(t.slice(2, 4), 16), i = parseInt(t.slice(4, 6), 16), t.length === 8 && (a = parseInt(t.slice(6, 8), 16) / 255);
+	else return null;
+	return [
+		n,
+		r,
+		i,
+		a
+	].some((e) => Number.isNaN(e)) ? null : {
+		r: n,
+		g: r,
+		b: i,
+		a
+	};
+}
+function i(e, t, n) {
+	let r = t / 100, i = n / 100, a = i * r, o = a * (1 - Math.abs(e / 60 % 2 - 1)), s = i - a, [c, l, u] = e < 60 ? [
+		a,
+		o,
+		0
+	] : e < 120 ? [
+		o,
+		a,
+		0
+	] : e < 180 ? [
+		0,
+		a,
+		o
+	] : e < 240 ? [
+		0,
+		o,
+		a
+	] : e < 300 ? [
+		o,
+		0,
+		a
+	] : [
+		a,
+		0,
+		o
+	];
+	return {
+		r: (c + s) * 255,
+		g: (l + s) * 255,
+		b: (u + s) * 255
+	};
+}
+function a(e, t, n) {
+	let r = e / 255, i = t / 255, a = n / 255, o = Math.max(r, i, a), s = o - Math.min(r, i, a), c = 0;
+	s !== 0 && (c = o === r ? 60 * ((i - a) / s % 6) : o === i ? 60 * ((a - r) / s + 2) : 60 * ((r - i) / s + 4)), c < 0 && (c += 360);
+	let l = o === 0 ? 0 : s / o;
+	return {
+		h: c,
+		s: l * 100,
+		v: o * 100
+	};
+}
+function o(e, t, n) {
+	let r = t / 100, i = n / 100, a = (1 - Math.abs(2 * i - 1)) * r, o = a * (1 - Math.abs(e / 60 % 2 - 1)), s = i - a / 2, [c, l, u] = e < 60 ? [
+		a,
+		o,
+		0
+	] : e < 120 ? [
+		o,
+		a,
+		0
+	] : e < 180 ? [
+		0,
+		a,
+		o
+	] : e < 240 ? [
+		0,
+		o,
+		a
+	] : e < 300 ? [
+		o,
+		0,
+		a
+	] : [
+		a,
+		0,
+		o
+	];
+	return {
+		r: (c + s) * 255,
+		g: (l + s) * 255,
+		b: (u + s) * 255
+	};
+}
+function s(e, t, n) {
+	let r = e / 255, i = t / 255, a = n / 255, o = Math.max(r, i, a), s = Math.min(r, i, a), c = (o + s) / 2, l = o - s, u = 0, d = 0;
+	return l !== 0 && (d = c > .5 ? l / (2 - o - s) : l / (o + s), u = o === r ? 60 * ((i - a) / l % 6) : o === i ? 60 * ((a - r) / l + 2) : 60 * ((r - i) / l + 4)), u < 0 && (u += 360), {
+		h: u,
+		s: d * 100,
+		l: c * 100
+	};
+}
+function c({ h: e, s: t, v: n, a: r }) {
+	let { r: a, g: o, b: s } = i(e, t, n);
+	return {
+		r: a,
+		g: o,
+		b: s,
+		a: r
+	};
+}
+function l({ r: e, g: t, b: n, a: r }) {
+	let { h: i, s: o, v: s } = a(e, t, n);
+	return {
+		h: i,
+		s: o,
+		v: s,
+		a: r
+	};
+}
+function u({ h: e, s: t, v: n, a: r }) {
+	let { r: a, g: o, b: c } = i(e, t, n);
+	return {
+		...s(a, o, c),
+		a: r
+	};
+}
+function d({ h: e, s: t, l: n, a: r }) {
+	let { r: i, g: s, b: c } = o(e, t, n);
+	return {
+		...a(i, s, c),
+		a: r
+	};
+}
+function f(e) {
+	let t = e.trim();
+	if (t.startsWith("#")) return r(t);
+	let n = t.match(/^rgba?\(\s*(\d+)\s*,\s*(\d+)\s*,\s*(\d+)\s*(?:,\s*([\d.]+)\s*)?\)$/i);
+	if (n) return {
+		r: Number(n[1]),
+		g: Number(n[2]),
+		b: Number(n[3]),
+		a: n[4] === void 0 ? 1 : Number(n[4])
+	};
+	let i = t.match(/^hsla?\(\s*([\d.]+)\s*,\s*([\d.]+)%\s*,\s*([\d.]+)%\s*(?:,\s*([\d.]+)\s*)?\)$/i);
+	if (i) {
+		let { r: e, g: t, b: n } = o(Number(i[1]), Number(i[2]), Number(i[3]));
+		return {
+			r: e,
+			g: t,
+			b: n,
+			a: i[4] === void 0 ? 1 : Number(i[4])
+		};
+	}
+	return null;
+}
+//#endregion
+export { e as clamp, r as hexToRgba, d as hslaToHsva, u as hsvaToHsla, c as hsvaToRgba, f as parseColorString, n as rgbaToHex, l as rgbaToHsva };