@clhaas/palette-kit 0.4.0 → 0.4.1

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

@@ -1,4 +1,5 @@
 import { type OklchColor } from '../../core/oklch.js';
+import type { ColorOutput, ResolveOutput } from '../../export/types.js';
 import { type ResolverConfig } from '../../presets/presets.js';
 import type { Context } from '../context/context.js';
 import type { Level } from '../level/level.js';
@@ -6,11 +7,12 @@ 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 RelationInputTarget = ResolveOutput<ColorOutput>;
 export type RelationTarget = Readonly<OklchColor>;
 export type RelationOptions = Readonly<{
-    on?: RelationTarget;
-    over?: RelationTarget;
-    under?: RelationTarget;
+    on?: RelationInputTarget;
+    over?: RelationInputTarget;
+    under?: RelationInputTarget;
 }>;
 export type ResolvedRelation<R extends Relation = Relation> = Readonly<{
     relation: R;

package/dist/engine/relation/relation.js

@@ -1,5 +1,6 @@
 import { resolveOnContrast } from '../../contrast/contrast.js';
 import { isOklchColor, normalizeOklch, } from '../../core/oklch.js';
+import { linearRgbToOklab, oklabToOklch } from '../../operators/convert.js';
 import { defaultResolverConfig, } from '../../presets/presets.js';
 import { createForbiddenAxisCombinationError, createInvalidRelationTargetError, createMissingRequiredAxisError, createMultipleRelationsError, } from '../../utils/errors/errors.js';
 import { assertUsage } from '../usage/strategy.js';
@@ -32,6 +33,57 @@ export const relationCompatibility = Object.freeze({
 });
 const relationList = RELATIONS.join(', ');
 const formatInvalidRelationError = (value) => `Invalid relation "${String(value)}". Expected one of: ${relationList}.`;
+const isFiniteNumber = (value) => typeof value === 'number' && Number.isFinite(value);
+const isEncodedRgbChannel = (value) => typeof value === 'number' &&
+    Number.isInteger(value) &&
+    value >= 0 &&
+    value <= 255;
+const isAlphaChannel = (value) => isFiniteNumber(value) && value >= 0 && value <= 1;
+const isRecord = (value) => typeof value === 'object' && value !== null;
+const isOklabRelationTarget = (value) => {
+    if (!isRecord(value)) {
+        return false;
+    }
+    return (value.space === 'oklab' &&
+        isFiniteNumber(value.l) &&
+        value.l >= 0 &&
+        value.l <= 1 &&
+        isFiniteNumber(value.a) &&
+        isFiniteNumber(value.b) &&
+        isAlphaChannel(value.alpha));
+};
+const isRgbRelationTarget = (value) => {
+    if (!isRecord(value)) {
+        return false;
+    }
+    return (isEncodedRgbChannel(value.r) &&
+        isEncodedRgbChannel(value.g) &&
+        isEncodedRgbChannel(value.b) &&
+        isAlphaChannel(value.alpha));
+};
+const isRgbaRelationTarget = (value) => {
+    if (!isRecord(value)) {
+        return false;
+    }
+    return (isEncodedRgbChannel(value.r) &&
+        isEncodedRgbChannel(value.g) &&
+        isEncodedRgbChannel(value.b) &&
+        isAlphaChannel(value.a));
+};
+const isHexRelationTarget = (value) => typeof value === 'string' && /^#[0-9a-f]{6}$/.test(value);
+const parseHexChannel = (hex, start) => Number.parseInt(hex.slice(start, start + 2), 16);
+const decodeSrgbChannel = (channel) => {
+    const encoded = channel / 255;
+    return encoded <= 0.04045
+        ? encoded / 12.92
+        : ((encoded + 0.055) / 1.055) ** 2.4;
+};
+const rgbTargetToOklch = (target) => oklabToOklch(linearRgbToOklab({
+    alpha: target.alpha,
+    b: decodeSrgbChannel(target.b),
+    g: decodeSrgbChannel(target.g),
+    r: decodeSrgbChannel(target.r),
+}));
 export function isRelation(value) {
     return (typeof value === 'string' &&
         RELATIONS.includes(value));
@@ -41,10 +93,33 @@ export function assertRelation(value) {
         throw new Error(formatInvalidRelationError(value));
     }
 }
-function assertRelationTarget(relation, target) {
-    if (!isOklchColor(target)) {
-        throw createInvalidRelationTargetError(relation);
+function normalizeRelationTarget(relation, target) {
+    if (isOklchColor(target)) {
+        return target;
+    }
+    if (isOklabRelationTarget(target)) {
+        return oklabToOklch(target);
+    }
+    if (isHexRelationTarget(target)) {
+        return rgbTargetToOklch({
+            alpha: 1,
+            b: parseHexChannel(target, 5),
+            g: parseHexChannel(target, 3),
+            r: parseHexChannel(target, 1),
+        });
+    }
+    if (isRgbaRelationTarget(target)) {
+        return rgbTargetToOklch({
+            alpha: target.a,
+            b: target.b,
+            g: target.g,
+            r: target.r,
+        });
+    }
+    if (isRgbRelationTarget(target)) {
+        return rgbTargetToOklch(target);
     }
+    throw createInvalidRelationTargetError(relation);
 }
 const getProvidedRelations = (relations) => RELATIONS.filter((relation) => relations[relation] !== undefined);
 export function validateRelationOptions(usage, relations = {}) {
@@ -69,10 +144,10 @@ export function validateRelationOptions(usage, relations = {}) {
         throw createForbiddenAxisCombinationError(`Relation "${relation}"`, usage);
     }
     const target = relations[relation];
-    assertRelationTarget(relation, target);
+    const normalizedTarget = normalizeRelationTarget(relation, target);
     return Object.freeze({
         relation,
-        target,
+        target: normalizedTarget,
     });
 }
 export const relationApplicationHooks = Object.freeze({

package/dist/types/index.d.ts

@@ -47,7 +47,7 @@ export type PaletteKitConfig<I extends string = string, PaletteOutput extends Co
     resolverConfig?: ResolverConfigOverrides;
 }>;
 export type PaletteDefaultOutput<PaletteOutput extends ColorOutput | undefined, SystemDefaultOutput extends ColorOutput | undefined> = PaletteOutput extends ColorOutput ? PaletteOutput : SystemDefaultOutput extends ColorOutput ? SystemDefaultOutput : 'oklch';
-type RelationTarget = OklchColor;
+type RelationTarget = PaletteResolveOutput<ColorOutput>;
 type DefaultStateOptions = Readonly<{
     state?: 'default';
     stateDirection?: StateDeltaDirection;

package/dist/utils/errors/errors.js

@@ -15,7 +15,7 @@ export const createUnknownIntentError = (intent) => new PaletteKitError('UNKNOWN
 export const createMissingRequiredAxisError = (axis, usage, message) => new PaletteKitError('MISSING_REQUIRED_AXIS', 'resolver-input', message ?? `${axis} is required for usage "${usage}".`, { axis, usage });
 export const createForbiddenAxisCombinationError = (axis, usage, message) => new PaletteKitError('FORBIDDEN_AXIS_COMBINATION', 'resolver-input', message ?? `${axis} is not allowed for usage "${usage}".`, { axis, usage });
 export const createInvalidRelationTargetError = (relation, message) => new PaletteKitError('INVALID_RELATION_TARGET', 'resolver-input', message ??
-    `Relation "${relation}" target must be a normalized OKLCH color.`, { relation });
+    `Relation "${relation}" target must be a normalized OKLCH color or a serialized Palette Kit color output.`, { relation });
 export const createMultipleRelationsError = (relations) => new PaletteKitError('MULTIPLE_RELATIONS', 'resolver-input', `Only one relation may be provided. Received: ${relations.join(', ')}.`, { relations: [...relations] });
 export const createUnresolvedContextError = () => new PaletteKitError('UNRESOLVED_CONTEXT', 'resolver-input', 'Context could not be resolved. Provide resolverContext, paletteContext, or systemDefaultContext.');
 export const createUnsupportedOutputError = (output, message) => new PaletteKitError('UNSUPPORTED_OUTPUT', 'serialization', message ?? `Unsupported color output "${output}" in Phase 10 serializer.`, { output });

package/docs/API.md

@@ -80,6 +80,11 @@ const text = palette.resolve({
 meet the target after the configured luminance shift and chroma reduction, it
 throws.
 
+Relation targets may be any color returned by Palette Kit outputs: `oklch`,
+`oklab`, `srgb`, `p3`, `hex`, or `rgba`. Serialized targets are normalized back
+to OKLCH internally before contrast or layering logic runs. CSS/RN strings such
+as `rgba(...)` are not relation targets.
+
 ## State Rules
 
 `state` defaults to `"default"`.

package/docs/Text.md

@@ -28,6 +28,10 @@ const text = palette.resolve({
 });
 ```
 
+`on` may receive any color returned by Palette Kit outputs. This supports
+palettes configured with `output: "rgba"` while keeping contrast resolution
+internal to OKLCH.
+
 ## Current Behavior
 
 `on` enforces APCA contrast. The default target is Lc 60. APCA is the primary

package/docs/Usage-ReactNative.md

@@ -43,6 +43,17 @@ Convert it to a React Native string if needed:
 const rnColor = `rgba(${background.r}, ${background.g}, ${background.b}, ${background.a})`;
 ```
 
+Use the Palette Kit RGBA object itself for relation targets before converting it
+to a React Native string:
+
+```ts
+const text = palette.resolve({
+  usage: "visualVocabulary",
+  intent: "brand",
+  on: background,
+});
+```
+
 ## Resolver Override
 
 You can override output per call:

package/docs/Validation.md

@@ -53,7 +53,9 @@ Relation rules:
 - `overlays` forbids `on`.
 - `fill` and `lines` allow `on`.
 
-Relation targets must be normalized OKLCH colors.
+Relation targets may be normalized OKLCH colors or serialized Palette Kit
+outputs: `oklab`, `srgb`, `p3`, `hex`, or `rgba`. CSS/RN strings such as
+`rgba(...)` are not accepted.
 
 ## State
 

package/docs/spec.md

@@ -81,6 +81,8 @@ and the current explicit clip gamut strategy.
 - Forbidden axis combinations throw.
 - `on` enforces APCA contrast with a default Lc 60 target and exposes WCAG as a
   fallback diagnostic.
+- Relation targets accept normalized OKLCH or any serialized Palette Kit output
+  and are normalized back to OKLCH before relation logic runs.
 - `over` applies configured alpha by level.
 - `under` applies configured alpha and luminance reduction by level.
 - State alpha deltas apply only where alpha is allowed, currently `overlays`.

package/package.json

@@ -56,7 +56,7 @@
 	},
 	"repository": {
 		"type": "git",
-		"url": "https://github.com/claushaas/palette-kit"
+		"url": "git+https://github.com/claushaas/palette-kit.git"
 	},
 	"scripts": {
 		"build": "tsc -p tsconfig.build.json",
@@ -72,5 +72,5 @@
 	},
 	"type": "module",
 	"types": "dist/index.d.ts",
-	"version": "0.4.0"
+	"version": "0.4.1"
 }