@clhaas/palette-kit 0.3.0 → 0.4.0

package/dist/engine/usage/strategy.d.ts

@@ -0,0 +1,56 @@
+import type { IntentDefinition } from '../../core/intent-registry.js';
+export declare const USAGES: readonly ["fill", "visualVocabulary", "lines", "overlays"];
+export type Usage = (typeof USAGES)[number];
+export type UsageStrategyInput = Readonly<{
+    intent: Readonly<IntentDefinition>;
+}>;
+export type UsageStrategyResult<U extends Usage = Usage> = Readonly<{
+    usage: U;
+    intent: Readonly<IntentDefinition>;
+}>;
+export type UsageStrategy<U extends Usage = Usage> = Readonly<{
+    usage: U;
+    resolve(input: UsageStrategyInput): UsageStrategyResult<U>;
+}>;
+export declare function isUsage(value: unknown): value is Usage;
+export declare function assertUsage(value: unknown): asserts value is Usage;
+export declare const usageStrategies: Readonly<{
+    fill: Readonly<{
+        resolve(input: Readonly<{
+            intent: Readonly<IntentDefinition>;
+        }>): Readonly<{
+            intent: Readonly<IntentDefinition>;
+            usage: "fill";
+        }>;
+        usage: "fill";
+    }>;
+    lines: Readonly<{
+        resolve(input: Readonly<{
+            intent: Readonly<IntentDefinition>;
+        }>): Readonly<{
+            intent: Readonly<IntentDefinition>;
+            usage: "lines";
+        }>;
+        usage: "lines";
+    }>;
+    overlays: Readonly<{
+        resolve(input: Readonly<{
+            intent: Readonly<IntentDefinition>;
+        }>): Readonly<{
+            intent: Readonly<IntentDefinition>;
+            usage: "overlays";
+        }>;
+        usage: "overlays";
+    }>;
+    visualVocabulary: Readonly<{
+        resolve(input: Readonly<{
+            intent: Readonly<IntentDefinition>;
+        }>): Readonly<{
+            intent: Readonly<IntentDefinition>;
+            usage: "visualVocabulary";
+        }>;
+        usage: "visualVocabulary";
+    }>;
+}>;
+export declare function getUsageStrategy<U extends Usage>(usage: U): UsageStrategy<U>;
+export declare function getUsageStrategy(usage: unknown): UsageStrategy;

package/dist/engine/usage/strategy.js

@@ -0,0 +1,30 @@
+import { fillUsageStrategy } from './fill.js';
+import { linesUsageStrategy } from './lines.js';
+import { overlaysUsageStrategy } from './overlays.js';
+import { visualVocabularyUsageStrategy } from './visualVocabulary.js';
+export const USAGES = Object.freeze([
+    'fill',
+    'visualVocabulary',
+    'lines',
+    'overlays',
+]);
+const usageList = USAGES.join(', ');
+const formatUnknownUsageError = (value) => `Unknown usage "${String(value)}". Expected one of: ${usageList}.`;
+export function isUsage(value) {
+    return (typeof value === 'string' && USAGES.includes(value));
+}
+export function assertUsage(value) {
+    if (!isUsage(value)) {
+        throw new Error(formatUnknownUsageError(value));
+    }
+}
+export const usageStrategies = Object.freeze({
+    fill: fillUsageStrategy,
+    lines: linesUsageStrategy,
+    overlays: overlaysUsageStrategy,
+    visualVocabulary: visualVocabularyUsageStrategy,
+});
+export function getUsageStrategy(usage) {
+    assertUsage(usage);
+    return usageStrategies[usage];
+}

package/dist/engine/usage/visualVocabulary.d.ts

@@ -0,0 +1,9 @@
+export declare const visualVocabularyUsageStrategy: Readonly<{
+    resolve(input: Readonly<{
+        intent: Readonly<import("../../core/intent-registry.js").IntentDefinition>;
+    }>): Readonly<{
+        intent: Readonly<import("../../core/intent-registry.js").IntentDefinition>;
+        usage: "visualVocabulary";
+    }>;
+    usage: "visualVocabulary";
+}>;

package/dist/engine/usage/visualVocabulary.js

@@ -0,0 +1,9 @@
+export const visualVocabularyUsageStrategy = Object.freeze({
+    resolve(input) {
+        return Object.freeze({
+            intent: input.intent,
+            usage: 'visualVocabulary',
+        });
+    },
+    usage: 'visualVocabulary',
+});

package/dist/export/serialize.d.ts

@@ -0,0 +1,14 @@
+import { normalizeOklch, type OklchInput } from '../core/oklch.js';
+import { oklchToOklab } from '../operators/convert.js';
+import type { ColorOutput, RgbaColor, RgbColor } from './types.js';
+export type GamutStrategy = 'clip';
+export type SerializationOptions = Readonly<{
+    gamutStrategy?: GamutStrategy;
+}>;
+export type ColorSerializer<T> = (color: OklchInput, options?: SerializationOptions) => T;
+export declare const serializeOklchToRgba: ColorSerializer<RgbaColor>;
+export declare const serializeOklchToOklab: ColorSerializer<ReturnType<typeof oklchToOklab>>;
+export declare const serializeOklchToSrgb: ColorSerializer<RgbColor>;
+export declare const serializeOklchToP3: ColorSerializer<RgbColor>;
+export declare const serializeOklchToHex: ColorSerializer<string>;
+export declare function serializeColor(color: OklchInput, output: ColorOutput, options?: SerializationOptions): ReturnType<typeof normalizeOklch | typeof serializeOklchToOklab | typeof serializeOklchToSrgb | typeof serializeOklchToP3 | typeof serializeOklchToHex | typeof serializeOklchToRgba>;

package/dist/export/serialize.js

@@ -0,0 +1,89 @@
+import { normalizeOklch } from '../core/oklch.js';
+import { oklabToLinearRgb, oklchToOklab } from '../operators/convert.js';
+import { createUnsupportedOutputError } from '../utils/errors/errors.js';
+const DEFAULT_GAMUT_STRATEGY = 'clip';
+const clampUnit = (value) => Math.min(1, Math.max(0, value));
+const toSrgbChannel = (linearChannel) => {
+    const encoded = linearChannel <= 0.0031308
+        ? 12.92 * linearChannel
+        : 1.055 * linearChannel ** (1 / 2.4) - 0.055;
+    return Math.round(clampUnit(encoded) * 255);
+};
+const toEncodedRgbColor = (linearRgb) => Object.freeze({
+    alpha: linearRgb.alpha,
+    b: toSrgbChannel(linearRgb.b),
+    g: toSrgbChannel(linearRgb.g),
+    r: toSrgbChannel(linearRgb.r),
+});
+const oklabToLinearDisplayP3 = (oklab) => {
+    const lPrime = oklab.l + 0.3963377774 * oklab.a + 0.2158037573 * oklab.b;
+    const mPrime = oklab.l - 0.1055613458 * oklab.a - 0.0638541728 * oklab.b;
+    const sPrime = oklab.l - 0.0894841775 * oklab.a - 1.291485548 * oklab.b;
+    const l = lPrime ** 3;
+    const m = mPrime ** 3;
+    const s = sPrime ** 3;
+    const x = 1.2270138511 * l - 0.5577999807 * m + 0.281256149 * s;
+    const y = -0.0405801784 * l + 1.1122568696 * m - 0.0716766787 * s;
+    const z = -0.0763812845 * l - 0.4214819784 * m + 1.5861632204 * s;
+    return {
+        alpha: oklab.alpha,
+        b: 0.0358458302 * x - 0.0761723893 * y + 0.956884524 * z,
+        g: -0.8294889696 * x + 1.7626640603 * y + 0.0236246858 * z,
+        r: 2.4934969119 * x - 0.9313836179 * y - 0.4027107845 * z,
+    };
+};
+const toHexChannel = (channel) => channel.toString(16).padStart(2, '0');
+const resolveGamutStrategy = (options) => {
+    const strategy = options?.gamutStrategy ?? DEFAULT_GAMUT_STRATEGY;
+    if (strategy !== 'clip') {
+        throw new Error(`Unsupported gamut strategy "${String(strategy)}". Expected "clip".`);
+    }
+    return strategy;
+};
+export const serializeOklchToRgba = (input, options) => {
+    const srgb = serializeOklchToSrgb(input, options);
+    return Object.freeze({
+        a: srgb.alpha,
+        b: srgb.b,
+        g: srgb.g,
+        r: srgb.r,
+    });
+};
+export const serializeOklchToOklab = (input) => oklchToOklab(input);
+export const serializeOklchToSrgb = (input, options) => {
+    resolveGamutStrategy(options);
+    const color = normalizeOklch(input);
+    const linearRgb = oklabToLinearRgb(oklchToOklab(color));
+    return toEncodedRgbColor(linearRgb);
+};
+export const serializeOklchToP3 = (input, options) => {
+    resolveGamutStrategy(options);
+    const color = normalizeOklch(input);
+    const linearP3 = oklabToLinearDisplayP3(oklchToOklab(color));
+    return toEncodedRgbColor(linearP3);
+};
+export const serializeOklchToHex = (input, options) => {
+    const rgba = serializeOklchToRgba(input, options);
+    return `#${toHexChannel(rgba.r)}${toHexChannel(rgba.g)}${toHexChannel(rgba.b)}`;
+};
+export function serializeColor(color, output, options) {
+    if (output === 'oklch') {
+        return normalizeOklch(color);
+    }
+    if (output === 'oklab') {
+        return serializeOklchToOklab(color);
+    }
+    if (output === 'srgb') {
+        return serializeOklchToSrgb(color, options);
+    }
+    if (output === 'p3') {
+        return serializeOklchToP3(color, options);
+    }
+    if (output === 'hex') {
+        return serializeOklchToHex(color, options);
+    }
+    if (output === 'rgba') {
+        return serializeOklchToRgba(color, options);
+    }
+    throw createUnsupportedOutputError(output);
+}

package/dist/export/types.d.ts

@@ -0,0 +1,37 @@
+import type { OklchColor } from '../core/oklch.js';
+import type { OklabColor } from '../operators/convert.js';
+export declare const OUTPUTS: readonly ["oklch", "oklab", "srgb", "p3", "hex", "rgba"];
+export type ColorOutput = (typeof OUTPUTS)[number];
+export type RgbColor = Readonly<{
+    r: number;
+    g: number;
+    b: number;
+    alpha: number;
+}>;
+export type RgbaColor = Readonly<{
+    r: number;
+    g: number;
+    b: number;
+    a: number;
+}>;
+export type OutputMap = Readonly<{
+    oklch: OklchColor;
+    oklab: OklabColor;
+    srgb: RgbColor;
+    p3: RgbColor;
+    hex: string;
+    rgba: RgbaColor;
+}>;
+export type ResolveOutput<O extends ColorOutput> = OutputMap[O];
+export type ResolveOptionsWithOutput<O extends ColorOutput> = Readonly<{
+    output?: O;
+}>;
+export type TypedResolver<O extends ColorOutput> = (options: ResolveOptionsWithOutput<O>) => ResolveOutput<O>;
+export type OutputResolutionInput = Readonly<{
+    resolverOutput?: unknown;
+    paletteOutput?: unknown;
+    systemDefaultOutput?: unknown;
+}>;
+export declare function isColorOutput(value: unknown): value is ColorOutput;
+export declare function assertColorOutput(value: unknown): asserts value is ColorOutput;
+export declare function resolveOutput({ resolverOutput, paletteOutput, systemDefaultOutput, }: OutputResolutionInput): ColorOutput;

package/dist/export/types.js

@@ -0,0 +1,31 @@
+import { createUnsupportedOutputError } from '../utils/errors/errors.js';
+export const OUTPUTS = Object.freeze([
+    'oklch',
+    'oklab',
+    'srgb',
+    'p3',
+    'hex',
+    'rgba',
+]);
+const outputList = OUTPUTS.join(', ');
+const formatInvalidOutputError = (value) => `Invalid output "${String(value)}". Expected one of: ${outputList}.`;
+export function isColorOutput(value) {
+    return (typeof value === 'string' && OUTPUTS.includes(value));
+}
+export function assertColorOutput(value) {
+    if (!isColorOutput(value)) {
+        throw createUnsupportedOutputError(String(value), formatInvalidOutputError(value));
+    }
+}
+export function resolveOutput({ resolverOutput, paletteOutput, systemDefaultOutput, }) {
+    if (resolverOutput !== undefined) {
+        assertColorOutput(resolverOutput);
+    }
+    if (paletteOutput !== undefined) {
+        assertColorOutput(paletteOutput);
+    }
+    if (systemDefaultOutput !== undefined) {
+        assertColorOutput(systemDefaultOutput);
+    }
+    return resolverOutput ?? paletteOutput ?? systemDefaultOutput ?? 'oklch';
+}

package/dist/index.d.ts

@@ -1,3 +1,3 @@
-export type { PaletteConfig, TokenPresetName } from "./cli/config.js";
-export * from "./core/index.js";
-export * from "./types/index.js";
+export { createPaletteKit } from './create-palette-kit.js';
+export { defaultResolverConfig, neutralResolverConfig, softResolverConfig, strongResolverConfig, } from './presets/presets.js';
+export type { ChromaConfig, ColorOutput, Context, IntentDefinition, Level, OklchColor, PaletteKit, PaletteKitConfig, PaletteResolveOptions, PaletteResolveOutput, RelationParamsConfig, ResolverConfig, ResolverConfigOverrides, ResolverPresetName, RgbaColor, RgbColor, State, StateDeltaDirection, Usage, } from './types/index.js';

package/dist/index.js

@@ -1,2 +1,2 @@
-export * from "./core/index.js";
-export * from "./types/index.js";
+export { createPaletteKit } from './create-palette-kit.js';
+export { defaultResolverConfig, neutralResolverConfig, softResolverConfig, strongResolverConfig, } from './presets/presets.js';

package/dist/operators/convert.d.ts

@@ -0,0 +1,32 @@
+import { normalizeOklch, type OklchInput } from '../core/oklch.js';
+export declare const CONVERSION_EPSILON = 1e-10;
+export type OklabColor = {
+    space: 'oklab';
+    l: number;
+    a: number;
+    b: number;
+    alpha: number;
+};
+export type LinearRgbColor = {
+    space: 'linear-rgb';
+    r: number;
+    g: number;
+    b: number;
+    alpha: number;
+};
+export type OklabInput = {
+    l: number;
+    a: number;
+    b: number;
+    alpha?: number;
+};
+export type LinearRgbInput = {
+    r: number;
+    g: number;
+    b: number;
+    alpha?: number;
+};
+export declare function oklchToOklab(input: OklchInput): OklabColor;
+export declare function oklabToOklch(input: OklabInput): ReturnType<typeof normalizeOklch>;
+export declare function oklabToLinearRgb(input: OklabInput): LinearRgbColor;
+export declare function linearRgbToOklab(input: LinearRgbInput): OklabColor;

package/dist/operators/convert.js

@@ -0,0 +1,80 @@
+import { normalizeOklch } from '../core/oklch.js';
+export const CONVERSION_EPSILON = 1e-10;
+const isFiniteNumber = (value) => typeof value === 'number' && Number.isFinite(value);
+const normalizePrecision = (value) => Math.abs(value) <= CONVERSION_EPSILON ? 0 : value;
+const normalizeHue = (hue) => {
+    const normalized = ((hue % 360) + 360) % 360;
+    return normalizePrecision(normalized);
+};
+const validateFiniteChannel = (space, name, value) => {
+    if (!isFiniteNumber(value)) {
+        throw new Error(`${space} ${name} must be a finite number.`);
+    }
+};
+const normalizeAlpha = (space, alphaInput) => {
+    const alpha = alphaInput ?? 1;
+    validateFiniteChannel(space, 'alpha', alpha);
+    return normalizePrecision(alpha);
+};
+export function oklchToOklab(input) {
+    const color = normalizeOklch(input);
+    const hueRadians = (color.h * Math.PI) / 180;
+    return {
+        a: normalizePrecision(color.c * Math.cos(hueRadians)),
+        alpha: normalizePrecision(color.alpha),
+        b: normalizePrecision(color.c * Math.sin(hueRadians)),
+        l: normalizePrecision(color.l / 100),
+        space: 'oklab',
+    };
+}
+export function oklabToOklch(input) {
+    validateFiniteChannel('OKLab', 'l', input.l);
+    validateFiniteChannel('OKLab', 'a', input.a);
+    validateFiniteChannel('OKLab', 'b', input.b);
+    const alpha = normalizeAlpha('OKLab', input.alpha);
+    const c = Math.hypot(input.a, input.b);
+    const hue = c <= CONVERSION_EPSILON
+        ? 0
+        : (Math.atan2(input.b, input.a) * 180) / Math.PI;
+    return normalizeOklch({
+        alpha,
+        c: normalizePrecision(c),
+        h: normalizeHue(hue),
+        l: normalizePrecision(input.l * 100),
+    });
+}
+export function oklabToLinearRgb(input) {
+    validateFiniteChannel('OKLab', 'l', input.l);
+    validateFiniteChannel('OKLab', 'a', input.a);
+    validateFiniteChannel('OKLab', 'b', input.b);
+    const alpha = normalizeAlpha('OKLab', input.alpha);
+    const lPrime = input.l + 0.3963377774 * input.a + 0.2158037573 * input.b;
+    const mPrime = input.l - 0.1055613458 * input.a - 0.0638541728 * input.b;
+    const sPrime = input.l - 0.0894841775 * input.a - 1.291485548 * input.b;
+    const l = lPrime ** 3;
+    const m = mPrime ** 3;
+    const s = sPrime ** 3;
+    return {
+        alpha,
+        b: normalizePrecision(-0.0041960863 * l - 0.7034186147 * m + 1.707614701 * s),
+        g: normalizePrecision(-1.2684380046 * l + 2.6097574011 * m - 0.3413193965 * s),
+        r: normalizePrecision(4.0767416621 * l - 3.3077115913 * m + 0.2309699292 * s),
+        space: 'linear-rgb',
+    };
+}
+export function linearRgbToOklab(input) {
+    validateFiniteChannel('linear RGB', 'r', input.r);
+    validateFiniteChannel('linear RGB', 'g', input.g);
+    validateFiniteChannel('linear RGB', 'b', input.b);
+    const alpha = normalizeAlpha('linear RGB', input.alpha);
+    const l = Math.cbrt(0.4122214708 * input.r + 0.5363325363 * input.g + 0.0514459929 * input.b);
+    const m = Math.cbrt(0.2119034982 * input.r + 0.6806995451 * input.g + 0.1073969566 * input.b);
+    const s = Math.cbrt(0.0883024619 * input.r + 0.2817188376 * input.g + 0.6299787005 * input.b);
+    return {
+        a: normalizePrecision(1.9779984951 * l - 2.428592205 * m + 0.4505937099 * s),
+        alpha,
+        b: normalizePrecision(0.0259040371 * l + 0.7827717662 * m - 0.808675766 * s),
+        l: normalizePrecision(0.2104542553 * l + 0.793617785 * m - 0.0040720468 * s),
+        space: 'oklab',
+    };
+}

package/dist/presets/presets.d.ts

@@ -0,0 +1,95 @@
+import { type LevelCurveConfig } from '../engine/level/curves.js';
+import { type Level } from '../engine/level/level.js';
+import { type StateDeltaConfig, type StateDeltaTable } from '../engine/state/state.js';
+export declare const RESOLVER_PRESETS: readonly ["soft", "neutral", "strong"];
+export type ResolverPresetName = (typeof RESOLVER_PRESETS)[number];
+export type RelationLevelAlphaTable = Readonly<Record<Level, number>>;
+export type RelationParamsConfig = Readonly<{
+    on: Readonly<{
+        contrastTarget: number;
+        maxLuminanceShift: number;
+    }>;
+    over: Readonly<{
+        baseAlphaByLevel: RelationLevelAlphaTable;
+    }>;
+    under: Readonly<{
+        baseAlphaByLevel: RelationLevelAlphaTable;
+        luminanceReduction: number;
+    }>;
+}>;
+export type ChromaConfig = Readonly<{
+    maxReduction: number;
+    reductionStep: number;
+}>;
+export type ResolverConfig = Readonly<{
+    levelCurves: LevelCurveConfig;
+    stateDeltas: StateDeltaConfig;
+    relationParams: RelationParamsConfig;
+    chromaLimits: ChromaConfig;
+}>;
+export type ResolverConfigOverrides = Readonly<{
+    levelCurves?: Partial<LevelCurveConfig>;
+    stateDeltas?: Readonly<{
+        luminance?: Partial<StateDeltaTable>;
+        alpha?: Partial<StateDeltaTable>;
+    }>;
+    relationParams?: Readonly<{
+        on?: Partial<RelationParamsConfig['on']>;
+        over?: Readonly<{
+            baseAlphaByLevel?: Partial<RelationLevelAlphaTable>;
+        }>;
+        under?: Readonly<{
+            baseAlphaByLevel?: Partial<RelationLevelAlphaTable>;
+            luminanceReduction?: number;
+        }>;
+    }>;
+    chromaLimits?: Partial<ChromaConfig>;
+}>;
+export declare const softResolverConfig: Readonly<{
+    levelCurves: LevelCurveConfig;
+    stateDeltas: StateDeltaConfig;
+    relationParams: RelationParamsConfig;
+    chromaLimits: ChromaConfig;
+}>;
+export declare const neutralResolverConfig: Readonly<{
+    levelCurves: LevelCurveConfig;
+    stateDeltas: StateDeltaConfig;
+    relationParams: RelationParamsConfig;
+    chromaLimits: ChromaConfig;
+}>;
+export declare const strongResolverConfig: Readonly<{
+    levelCurves: LevelCurveConfig;
+    stateDeltas: StateDeltaConfig;
+    relationParams: RelationParamsConfig;
+    chromaLimits: ChromaConfig;
+}>;
+export declare const defaultResolverConfig: Readonly<{
+    levelCurves: LevelCurveConfig;
+    stateDeltas: StateDeltaConfig;
+    relationParams: RelationParamsConfig;
+    chromaLimits: ChromaConfig;
+}>;
+export declare const resolverPresetConfigs: Readonly<{
+    neutral: Readonly<{
+        levelCurves: LevelCurveConfig;
+        stateDeltas: StateDeltaConfig;
+        relationParams: RelationParamsConfig;
+        chromaLimits: ChromaConfig;
+    }>;
+    soft: Readonly<{
+        levelCurves: LevelCurveConfig;
+        stateDeltas: StateDeltaConfig;
+        relationParams: RelationParamsConfig;
+        chromaLimits: ChromaConfig;
+    }>;
+    strong: Readonly<{
+        levelCurves: LevelCurveConfig;
+        stateDeltas: StateDeltaConfig;
+        relationParams: RelationParamsConfig;
+        chromaLimits: ChromaConfig;
+    }>;
+}>;
+export declare function isResolverPresetName(value: unknown): value is ResolverPresetName;
+export declare function assertResolverPresetName(value: unknown): asserts value is ResolverPresetName;
+export declare function getResolverPresetConfig(preset: unknown): ResolverConfig;
+export declare function mergeResolverConfig(base: ResolverConfig, overrides: ResolverConfigOverrides | undefined): ResolverConfig;