@clhaas/palette-kit 0.1.8 → 0.4.0

package/dist/create-palette-kit.js

@@ -0,0 +1,67 @@
+import { createIntentRegistry, } from './core/intent-registry.js';
+import { assertContext } from './engine/context/context.js';
+import { resolveColor } from './engine/resolve/resolve.js';
+import { serializeColor } from './export/serialize.js';
+import { assertColorOutput, resolveOutput, } from './export/types.js';
+import { defaultResolverConfig, getResolverPresetConfig, mergeResolverConfig, } from './presets/presets.js';
+function resolveSerializedOutput(color, output) {
+    if (output === 'oklch') {
+        return color;
+    }
+    return serializeColor(color, output);
+}
+function validateOptionalContext(context) {
+    if (context !== undefined) {
+        assertContext(context);
+    }
+}
+function validateOptionalOutput(output) {
+    if (output !== undefined) {
+        assertColorOutput(output);
+    }
+}
+function createResolveFunction(intentRegistry, paletteContext, systemDefaultContext, paletteOutput, systemDefaultOutput, resolverConfig) {
+    return (options) => {
+        const output = resolveOutput({
+            paletteOutput,
+            resolverOutput: options.output,
+            systemDefaultOutput,
+        });
+        const resolved = resolveColor({
+            intent: options.intent,
+            intentRegistry,
+            level: options.level,
+            on: options.on,
+            over: options.over,
+            paletteContext,
+            resolverConfig,
+            resolverContext: options.context,
+            state: options.state,
+            stateDirection: options.stateDirection,
+            systemDefaultContext,
+            under: options.under,
+            usage: options.usage,
+        });
+        return resolveSerializedOutput(resolved.color, output);
+    };
+}
+/**
+ * Creates an immutable Palette Kit resolver instance.
+ *
+ * The factory normalizes the provided intent registry once, keeps context and
+ * output defaults explicit, and never reads ambient platform state.
+ */
+export function createPaletteKit(config) {
+    validateOptionalContext(config.context);
+    validateOptionalContext(config.systemDefaultContext);
+    validateOptionalOutput(config.output);
+    validateOptionalOutput(config.systemDefaultOutput);
+    const presetConfig = config.preset === undefined
+        ? defaultResolverConfig
+        : getResolverPresetConfig(config.preset);
+    const resolverConfig = mergeResolverConfig(presetConfig, config.resolverConfig);
+    const intentRegistry = createIntentRegistry(config.intents);
+    return Object.freeze({
+        resolve: createResolveFunction(intentRegistry, config.context, config.systemDefaultContext, config.output, config.systemDefaultOutput, resolverConfig),
+    });
+}

package/dist/engine/context/context.d.ts

@@ -0,0 +1,13 @@
+export declare const CONTEXTS: readonly ["light", "dark"];
+export type Context = (typeof CONTEXTS)[number];
+export type ContextResolutionInput = Readonly<{
+    resolverContext?: unknown;
+    paletteContext?: unknown;
+    systemDefaultContext?: unknown;
+}>;
+export type ContextCurveValues<T> = Readonly<Record<Context, T>>;
+export type ContextCurveHook<T> = (context: Context) => T;
+export declare function isContext(value: unknown): value is Context;
+export declare function assertContext(value: unknown): asserts value is Context;
+export declare function resolveContext({ resolverContext, paletteContext, systemDefaultContext, }: ContextResolutionInput): Context;
+export declare function createContextCurveHook<T>(values: ContextCurveValues<T>): ContextCurveHook<T>;

package/dist/engine/context/context.js

@@ -0,0 +1,37 @@
+import { createUnresolvedContextError } from '../../utils/errors/errors.js';
+export const CONTEXTS = Object.freeze(['light', 'dark']);
+const contextList = CONTEXTS.join(', ');
+const formatInvalidContextError = (value) => `Invalid context "${String(value)}". Expected one of: ${contextList}.`;
+export function isContext(value) {
+    return (typeof value === 'string' && CONTEXTS.includes(value));
+}
+export function assertContext(value) {
+    if (!isContext(value)) {
+        throw new Error(formatInvalidContextError(value));
+    }
+}
+export function resolveContext({ resolverContext, paletteContext, systemDefaultContext, }) {
+    if (resolverContext !== undefined) {
+        assertContext(resolverContext);
+        return resolverContext;
+    }
+    if (paletteContext !== undefined) {
+        assertContext(paletteContext);
+        return paletteContext;
+    }
+    if (systemDefaultContext !== undefined) {
+        assertContext(systemDefaultContext);
+        return systemDefaultContext;
+    }
+    throw createUnresolvedContextError();
+}
+export function createContextCurveHook(values) {
+    const frozenValues = Object.freeze({
+        dark: values.dark,
+        light: values.light,
+    });
+    return Object.freeze((context) => {
+        assertContext(context);
+        return frozenValues[context];
+    });
+}

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

@@ -0,0 +1,17 @@
+import type { Context } from '../context/context.js';
+import type { Usage } from '../usage/strategy.js';
+import { type Level } from './level.js';
+export type LevelDrivenUsage = Exclude<Usage, 'visualVocabulary'>;
+export type LevelCurve<T> = (level: Level, context: Context) => T;
+export type FillLevelCurve = LevelCurve<number>;
+export type LinesLevelCurve = LevelCurve<number>;
+export type OverlayLevelResult = Readonly<{
+    luminanceDelta: number;
+}>;
+export type OverlaysLevelCurve = LevelCurve<OverlayLevelResult>;
+export type LevelCurveConfig = Readonly<{
+    fill: FillLevelCurve;
+    lines: LinesLevelCurve;
+    overlays: OverlaysLevelCurve;
+}>;
+export declare const defaultLevelCurves: LevelCurveConfig;

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;