@clhaas/palette-kit 0.3.0 → 0.4.0

package/dist/engine/level/curves.js

@@ -0,0 +1,49 @@
+import { assertLevel } from './level.js';
+const fillLevelTargets = Object.freeze({
+    1: 98,
+    2: 96,
+    3: 94,
+    4: 91,
+    5: 88,
+    6: 84,
+    7: 79,
+    8: 73,
+    9: 66,
+});
+const linesLevelTargets = Object.freeze({
+    1: 96,
+    2: 95,
+    3: 94,
+    4: 92,
+    5: 90,
+    6: 88,
+    7: 86,
+    8: 84,
+    9: 82,
+});
+const overlayLevelTargets = Object.freeze({
+    1: Object.freeze({ luminanceDelta: 1 }),
+    2: Object.freeze({ luminanceDelta: 2 }),
+    3: Object.freeze({ luminanceDelta: 3 }),
+    4: Object.freeze({ luminanceDelta: 4 }),
+    5: Object.freeze({ luminanceDelta: 5 }),
+    6: Object.freeze({ luminanceDelta: 6 }),
+    7: Object.freeze({ luminanceDelta: 7 }),
+    8: Object.freeze({ luminanceDelta: 8 }),
+    9: Object.freeze({ luminanceDelta: 9 }),
+});
+const resolveContextualLightness = (lightness, context) => context === 'dark' ? 100 - lightness : lightness;
+export const defaultLevelCurves = Object.freeze({
+    fill(level, context) {
+        assertLevel(level);
+        return resolveContextualLightness(fillLevelTargets[level], context);
+    },
+    lines(level, context) {
+        assertLevel(level);
+        return resolveContextualLightness(linesLevelTargets[level], context);
+    },
+    overlays(level, _context) {
+        assertLevel(level);
+        return overlayLevelTargets[level];
+    },
+});

package/dist/engine/level/level.d.ts

@@ -0,0 +1,4 @@
+export declare const LEVELS: readonly [1, 2, 3, 4, 5, 6, 7, 8, 9];
+export type Level = (typeof LEVELS)[number];
+export declare function isLevel(value: unknown): value is Level;
+export declare function assertLevel(value: unknown): asserts value is Level;

package/dist/engine/level/level.js

@@ -0,0 +1,13 @@
+export const LEVELS = Object.freeze([1, 2, 3, 4, 5, 6, 7, 8, 9]);
+const formatInvalidLevelError = (value) => `Invalid level "${String(value)}". Expected an integer from 1 to 9.`;
+export function isLevel(value) {
+    return (typeof value === 'number' &&
+        Number.isInteger(value) &&
+        value >= 1 &&
+        value <= 9);
+}
+export function assertLevel(value) {
+    if (!isLevel(value)) {
+        throw new Error(formatInvalidLevelError(value));
+    }
+}

package/dist/engine/relation/relation.d.ts

@@ -0,0 +1,105 @@
+import { type OklchColor } from '../../core/oklch.js';
+import { type ResolverConfig } from '../../presets/presets.js';
+import type { Context } from '../context/context.js';
+import type { Level } from '../level/level.js';
+import { type Usage } from '../usage/strategy.js';
+export declare const RELATIONS: readonly ["on", "over", "under"];
+export type Relation = (typeof RELATIONS)[number];
+export type RelationAvailability = 'required' | 'optional' | 'forbidden';
+export type RelationTarget = Readonly<OklchColor>;
+export type RelationOptions = Readonly<{
+    on?: RelationTarget;
+    over?: RelationTarget;
+    under?: RelationTarget;
+}>;
+export type ResolvedRelation<R extends Relation = Relation> = Readonly<{
+    relation: R;
+    target: RelationTarget;
+}>;
+export type RelationApplicationInput = Readonly<{
+    usage: Usage;
+    color: RelationTarget;
+    context?: Context;
+    level?: Level;
+    resolverConfig?: ResolverConfig;
+    relations?: RelationOptions;
+}>;
+export type RelationApplicationResult = Readonly<{
+    color: RelationTarget;
+    relation?: ResolvedRelation;
+}>;
+export type RelationApplicationHookInput = Readonly<{
+    color: RelationTarget;
+    context: Context;
+    relation: ResolvedRelation;
+    level?: Level;
+    resolverConfig: ResolverConfig;
+}>;
+export type RelationApplicationHook = (input: RelationApplicationHookInput) => RelationApplicationResult;
+export declare const relationCompatibility: Readonly<{
+    fill: Readonly<{
+        on: "optional";
+        over: "forbidden";
+        under: "forbidden";
+    }>;
+    lines: Readonly<{
+        on: "optional";
+        over: "forbidden";
+        under: "forbidden";
+    }>;
+    overlays: Readonly<{
+        on: "forbidden";
+        over: "optional";
+        under: "optional";
+    }>;
+    visualVocabulary: Readonly<{
+        on: "required";
+        over: "forbidden";
+        under: "forbidden";
+    }>;
+}>;
+export declare function isRelation(value: unknown): value is Relation;
+export declare function assertRelation(value: unknown): asserts value is Relation;
+export declare function validateRelationOptions(usage: Usage, relations?: RelationOptions): ResolvedRelation | undefined;
+export declare const relationApplicationHooks: Readonly<{
+    on(input: Readonly<{
+        color: RelationTarget;
+        context: Context;
+        relation: ResolvedRelation;
+        level?: Level;
+        resolverConfig: ResolverConfig;
+    }>): Readonly<{
+        color: OklchColor;
+        relation: Readonly<{
+            relation: "on" | "over" | "under";
+            target: RelationTarget;
+        }>;
+    }>;
+    over(input: Readonly<{
+        color: RelationTarget;
+        context: Context;
+        relation: ResolvedRelation;
+        level?: Level;
+        resolverConfig: ResolverConfig;
+    }>): Readonly<{
+        color: OklchColor;
+        relation: Readonly<{
+            relation: "on" | "over" | "under";
+            target: RelationTarget;
+        }>;
+    }>;
+    under(input: Readonly<{
+        color: RelationTarget;
+        context: Context;
+        relation: ResolvedRelation;
+        level?: Level;
+        resolverConfig: ResolverConfig;
+    }>): Readonly<{
+        color: OklchColor;
+        relation: Readonly<{
+            relation: "on" | "over" | "under";
+            target: RelationTarget;
+        }>;
+    }>;
+}>;
+export declare function applyRelation(input: RelationApplicationInput): RelationApplicationResult;

package/dist/engine/relation/relation.js

@@ -0,0 +1,137 @@
+import { resolveOnContrast } from '../../contrast/contrast.js';
+import { isOklchColor, normalizeOklch, } from '../../core/oklch.js';
+import { defaultResolverConfig, } from '../../presets/presets.js';
+import { createForbiddenAxisCombinationError, createInvalidRelationTargetError, createMissingRequiredAxisError, createMultipleRelationsError, } from '../../utils/errors/errors.js';
+import { assertUsage } from '../usage/strategy.js';
+export const RELATIONS = Object.freeze(['on', 'over', 'under']);
+const fillRelationCompatibility = Object.freeze({
+    on: 'optional',
+    over: 'forbidden',
+    under: 'forbidden',
+});
+const visualVocabularyRelationCompatibility = Object.freeze({
+    on: 'required',
+    over: 'forbidden',
+    under: 'forbidden',
+});
+const linesRelationCompatibility = Object.freeze({
+    on: 'optional',
+    over: 'forbidden',
+    under: 'forbidden',
+});
+const overlaysRelationCompatibility = Object.freeze({
+    on: 'forbidden',
+    over: 'optional',
+    under: 'optional',
+});
+export const relationCompatibility = Object.freeze({
+    fill: fillRelationCompatibility,
+    lines: linesRelationCompatibility,
+    overlays: overlaysRelationCompatibility,
+    visualVocabulary: visualVocabularyRelationCompatibility,
+});
+const relationList = RELATIONS.join(', ');
+const formatInvalidRelationError = (value) => `Invalid relation "${String(value)}". Expected one of: ${relationList}.`;
+export function isRelation(value) {
+    return (typeof value === 'string' &&
+        RELATIONS.includes(value));
+}
+export function assertRelation(value) {
+    if (!isRelation(value)) {
+        throw new Error(formatInvalidRelationError(value));
+    }
+}
+function assertRelationTarget(relation, target) {
+    if (!isOklchColor(target)) {
+        throw createInvalidRelationTargetError(relation);
+    }
+}
+const getProvidedRelations = (relations) => RELATIONS.filter((relation) => relations[relation] !== undefined);
+export function validateRelationOptions(usage, relations = {}) {
+    assertUsage(usage);
+    const providedRelations = getProvidedRelations(relations);
+    if (providedRelations.length > 1) {
+        throw createMultipleRelationsError(providedRelations);
+    }
+    const requiredRelation = RELATIONS.find((relation) => relationCompatibility[usage][relation] === 'required');
+    if (providedRelations.length === 0) {
+        if (requiredRelation !== undefined) {
+            throw createMissingRequiredAxisError(`Relation "${requiredRelation}"`, usage);
+        }
+        return undefined;
+    }
+    const relation = providedRelations[0];
+    if (relation === undefined) {
+        return undefined;
+    }
+    const availability = relationCompatibility[usage][relation];
+    if (availability === 'forbidden') {
+        throw createForbiddenAxisCombinationError(`Relation "${relation}"`, usage);
+    }
+    const target = relations[relation];
+    assertRelationTarget(relation, target);
+    return Object.freeze({
+        relation,
+        target,
+    });
+}
+export const relationApplicationHooks = Object.freeze({
+    on(input) {
+        return Object.freeze({
+            color: resolveOnContrast({
+                color: input.color,
+                config: {
+                    chromaLimits: input.resolverConfig.chromaLimits,
+                    on: input.resolverConfig.relationParams.on,
+                },
+                context: input.context,
+                target: input.relation.target,
+            }),
+            relation: input.relation,
+        });
+    },
+    over(input) {
+        const alpha = input.level === undefined
+            ? input.color.alpha
+            : input.resolverConfig.relationParams.over.baseAlphaByLevel[input.level];
+        return Object.freeze({
+            color: normalizeOklch({
+                ...input.color,
+                alpha,
+            }),
+            relation: input.relation,
+        });
+    },
+    under(input) {
+        const alpha = input.level === undefined
+            ? input.color.alpha
+            : input.resolverConfig.relationParams.under.baseAlphaByLevel[input.level];
+        const luminanceReduction = input.resolverConfig.relationParams.under.luminanceReduction;
+        return Object.freeze({
+            color: normalizeOklch({
+                ...input.color,
+                alpha,
+                l: Math.max(0, input.color.l - luminanceReduction),
+            }),
+            relation: input.relation,
+        });
+    },
+});
+export function applyRelation(input) {
+    if (!isOklchColor(input.color)) {
+        throw createInvalidRelationTargetError('input', 'Relation input color must be a normalized OKLCH color.');
+    }
+    const relation = validateRelationOptions(input.usage, input.relations);
+    if (relation === undefined) {
+        return Object.freeze({
+            color: input.color,
+        });
+    }
+    return relationApplicationHooks[relation.relation]({
+        color: input.color,
+        context: input.context ?? 'light',
+        level: input.level,
+        relation,
+        resolverConfig: input.resolverConfig ?? defaultResolverConfig,
+    });
+}

package/dist/engine/resolve/resolve.d.ts

@@ -0,0 +1,36 @@
+import { type IntentName, type IntentRegistry } from '../../core/intent-registry.js';
+import { type OklchColor } from '../../core/oklch.js';
+import { type ResolverConfig } from '../../presets/presets.js';
+import { type Context } from '../context/context.js';
+import { type Level } from '../level/level.js';
+import { type RelationOptions, type ResolvedRelation } from '../relation/relation.js';
+import { type State, type StateDeltaDirection } from '../state/state.js';
+import { type Usage } from '../usage/strategy.js';
+export type ResolveColorOptions = Readonly<{
+    intentRegistry: IntentRegistry;
+    usage: unknown;
+    intent: IntentName;
+    level?: unknown;
+    on?: RelationOptions['on'];
+    over?: RelationOptions['over'];
+    under?: RelationOptions['under'];
+    state?: unknown;
+    stateDirection?: StateDeltaDirection;
+    resolverContext?: unknown;
+    paletteContext?: unknown;
+    systemDefaultContext?: unknown;
+    resolverConfig?: ResolverConfig;
+}>;
+export type ResolvedColorAxes = Readonly<{
+    usage: Usage;
+    intent: IntentName;
+    context: Context;
+    level?: Level;
+    state: State;
+    relation?: ResolvedRelation;
+}>;
+export type ResolvedColor = Readonly<{
+    color: OklchColor;
+    axes: ResolvedColorAxes;
+}>;
+export declare function resolveColor(options: ResolveColorOptions): ResolvedColor;

package/dist/engine/resolve/resolve.js

@@ -0,0 +1,116 @@
+import { getIntent, } from '../../core/intent-registry.js';
+import { normalizeOklch } from '../../core/oklch.js';
+import { defaultResolverConfig, } from '../../presets/presets.js';
+import { createForbiddenAxisCombinationError, createMissingRequiredAxisError, } from '../../utils/errors/errors.js';
+import { createContextCurveHook, resolveContext, } from '../context/context.js';
+import { assertLevel } from '../level/level.js';
+import { applyRelation, } from '../relation/relation.js';
+import { applyStateAlphaDelta, applyStateDelta, assertState, } from '../state/state.js';
+import { assertUsage, getUsageStrategy, } from '../usage/strategy.js';
+const contextCurve = createContextCurveHook({
+    dark: 0,
+    light: 0,
+});
+function assertStateDeltaDirection(value) {
+    if (value !== 'increase' && value !== 'decrease') {
+        throw new Error(`Invalid stateDirection "${String(value)}". Expected one of: increase, decrease.`);
+    }
+}
+const resolveLevel = (usage, level) => {
+    if (usage === 'visualVocabulary') {
+        if (level !== undefined) {
+            throw createForbiddenAxisCombinationError('Level', 'visualVocabulary');
+        }
+        return undefined;
+    }
+    if (level === undefined) {
+        throw createMissingRequiredAxisError('Level', usage);
+    }
+    assertLevel(level);
+    return level;
+};
+const resolveBaseLightness = (usage, level, context, resolverConfig) => {
+    if (usage === 'fill') {
+        return resolverConfig.levelCurves.fill(level, context);
+    }
+    if (usage === 'lines') {
+        return resolverConfig.levelCurves.lines(level, context);
+    }
+    if (usage === 'overlays') {
+        return (50 +
+            resolverConfig.levelCurves.overlays(level, context)
+                .luminanceDelta);
+    }
+    return 50;
+};
+const resolveStateDirection = (state, stateDirection) => {
+    if (state === 'default') {
+        if (stateDirection !== undefined) {
+            assertStateDeltaDirection(stateDirection);
+        }
+        return stateDirection ?? 'increase';
+    }
+    if (stateDirection === undefined) {
+        throw createMissingRequiredAxisError('stateDirection', 'state', 'stateDirection is required when state is not "default".');
+    }
+    assertStateDeltaDirection(stateDirection);
+    return stateDirection;
+};
+export function resolveColor(options) {
+    assertUsage(options.usage);
+    const resolverConfig = options.resolverConfig ?? defaultResolverConfig;
+    const stateInput = options.state ?? 'default';
+    assertState(stateInput);
+    const context = resolveContext({
+        paletteContext: options.paletteContext,
+        resolverContext: options.resolverContext,
+        systemDefaultContext: options.systemDefaultContext,
+    });
+    const level = resolveLevel(options.usage, options.level);
+    const intent = getIntent(options.intentRegistry, options.intent);
+    const usageResult = getUsageStrategy(options.usage).resolve({ intent });
+    const baseLightness = resolveBaseLightness(options.usage, level, context, resolverConfig);
+    const baseColor = normalizeOklch({
+        alpha: 1,
+        c: usageResult.intent.chroma,
+        h: usageResult.intent.hue,
+        l: baseLightness,
+    });
+    const relationResult = applyRelation({
+        color: baseColor,
+        context,
+        level,
+        relations: {
+            on: options.on,
+            over: options.over,
+            under: options.under,
+        },
+        resolverConfig,
+        usage: options.usage,
+    });
+    const stateDirection = resolveStateDirection(stateInput, options.stateDirection);
+    const stateLightness = applyStateDelta(relationResult.color.l, stateInput, stateDirection, resolverConfig.stateDeltas.luminance);
+    const contextDelta = contextCurve(context);
+    const alpha = options.usage === 'overlays'
+        ? applyStateAlphaDelta(relationResult.color.alpha, stateInput, stateDirection, resolverConfig.stateDeltas.alpha)
+        : relationResult.color.alpha;
+    const color = Object.freeze(normalizeOklch({
+        ...relationResult.color,
+        alpha,
+        l: stateLightness + contextDelta,
+    }));
+    const axes = Object.freeze({
+        context,
+        intent: options.intent,
+        usage: options.usage,
+        ...(level === undefined ? {} : { level }),
+        state: stateInput,
+        ...(relationResult.relation === undefined
+            ? {}
+            : { relation: relationResult.relation }),
+    });
+    return Object.freeze({
+        axes,
+        color,
+    });
+}

package/dist/engine/state/state.d.ts

@@ -0,0 +1,46 @@
+export declare const STATES: readonly ["default", "hover", "active", "focus", "selected", "disabled"];
+export type State = (typeof STATES)[number];
+export type StateDeltaDirection = 'increase' | 'decrease';
+export type StateDeltaTable = Readonly<Record<State, number>>;
+export type StateDeltaConfig = Readonly<{
+    luminance: StateDeltaTable;
+    alpha: StateDeltaTable;
+}>;
+export declare const defaultStateLuminanceDeltas: Readonly<{
+    active: number;
+    default: number;
+    disabled: number;
+    focus: number;
+    hover: number;
+    selected: number;
+}>;
+export declare const defaultStateAlphaDeltas: Readonly<{
+    active: number;
+    default: number;
+    disabled: number;
+    focus: number;
+    hover: number;
+    selected: number;
+}>;
+export declare const defaultStateDeltas: Readonly<{
+    alpha: Readonly<{
+        active: number;
+        default: number;
+        disabled: number;
+        focus: number;
+        hover: number;
+        selected: number;
+    }>;
+    luminance: Readonly<{
+        active: number;
+        default: number;
+        disabled: number;
+        focus: number;
+        hover: number;
+        selected: number;
+    }>;
+}>;
+export declare function isState(value: unknown): value is State;
+export declare function assertState(value: unknown): asserts value is State;
+export declare function applyStateDelta(value: number, state: State, direction: StateDeltaDirection, deltas?: StateDeltaTable): number;
+export declare function applyStateAlphaDelta(value: number, state: State, direction: StateDeltaDirection, deltas?: StateDeltaTable): number;

package/dist/engine/state/state.js

@@ -0,0 +1,68 @@
+export const STATES = Object.freeze([
+    'default',
+    'hover',
+    'active',
+    'focus',
+    'selected',
+    'disabled',
+]);
+export const defaultStateLuminanceDeltas = Object.freeze({
+    active: 6,
+    default: 0,
+    disabled: 10,
+    focus: 4,
+    hover: 3,
+    selected: 5,
+});
+export const defaultStateAlphaDeltas = Object.freeze({
+    active: 0,
+    default: 0,
+    disabled: 0,
+    focus: 0,
+    hover: 0,
+    selected: 0,
+});
+export const defaultStateDeltas = Object.freeze({
+    alpha: defaultStateAlphaDeltas,
+    luminance: defaultStateLuminanceDeltas,
+});
+const stateList = STATES.join(', ');
+const formatInvalidStateError = (value) => `Invalid state "${String(value)}". Expected one of: ${stateList}.`;
+const clampPercentage = (value) => Math.min(100, Math.max(0, value));
+const clampAlpha = (value) => Number(Math.min(1, Math.max(0, value)).toFixed(12));
+export function isState(value) {
+    return (typeof value === 'string' && STATES.includes(value));
+}
+export function assertState(value) {
+    if (!isState(value)) {
+        throw new Error(formatInvalidStateError(value));
+    }
+}
+export function applyStateDelta(value, state, direction, deltas = defaultStateDeltas.luminance) {
+    if (!Number.isFinite(value)) {
+        throw new Error('State delta value must be a finite number.');
+    }
+    assertState(state);
+    const delta = deltas[state];
+    if (state === 'default') {
+        return clampPercentage(value);
+    }
+    if (direction === 'increase') {
+        return clampPercentage(value + delta);
+    }
+    return clampPercentage(value - delta);
+}
+export function applyStateAlphaDelta(value, state, direction, deltas = defaultStateDeltas.alpha) {
+    if (!Number.isFinite(value)) {
+        throw new Error('State alpha delta value must be a finite number.');
+    }
+    assertState(state);
+    const delta = deltas[state];
+    if (state === 'default') {
+        return clampAlpha(value);
+    }
+    if (direction === 'increase') {
+        return clampAlpha(value + delta);
+    }
+    return clampAlpha(value - delta);
+}

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

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

package/dist/engine/usage/fill.js

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

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

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

package/dist/engine/usage/lines.js

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

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

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

package/dist/engine/usage/overlays.js

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