@ankhorage/zora 0.16.2 → 1.0.0

package/src/internal/color/harmony.test.ts

@@ -1,145 +0,0 @@
-import { describe, expect, test } from 'bun:test';
-
-import type { ZoraHexColor } from '../../theme/types';
-import { normalizeHueDegrees } from './hue';
-import {
-  computeZoraHarmony,
-  parseHexToOklch,
-  type ZoraComputedHarmony,
-  type ZoraHarmonySlot,
-  type ZoraHarmonySlotId,
-} from './index';
-
-function hueDeltaDegrees(a: number, b: number): number {
-  const raw = Math.abs(a - b) % 360;
-  return Math.min(raw, 360 - raw);
-}
-
-function expectNormalizedHue(hue: number) {
-  expect(hue).toBeGreaterThanOrEqual(0);
-  expect(hue).toBeLessThan(360);
-}
-
-function getSlotIds(slots: readonly ZoraHarmonySlot[]): ZoraHarmonySlotId[] {
-  return slots.map((slot) => slot.id);
-}
-
-describe('computeZoraHarmony', () => {
-  test('monochromatic returns 1 slot', () => {
-    const seed: ZoraHexColor = '#0f766e';
-    const harmony: ZoraComputedHarmony = computeZoraHarmony(seed, 'monochromatic');
-
-    expect(harmony.orderedSlots).toHaveLength(1);
-    expect(harmony.orderedSlots[0].id).toBe('base');
-  });
-
-  test('complementary returns 2 slots', () => {
-    const seed: ZoraHexColor = '#0f766e';
-    const harmony: ZoraComputedHarmony = computeZoraHarmony(seed, 'complementary');
-
-    expect(harmony.orderedSlots).toHaveLength(2);
-    expect(harmony.orderedSlots[0].id).toBe('base');
-    expect(harmony.orderedSlots[1].id).toBe('a');
-  });
-
-  test('analogous returns 3 slots', () => {
-    const seed: ZoraHexColor = '#0f766e';
-    const harmony: ZoraComputedHarmony = computeZoraHarmony(seed, 'analogous');
-
-    expect(harmony.orderedSlots).toHaveLength(3);
-    expect(getSlotIds(harmony.orderedSlots)).toEqual(['base', 'a', 'b']);
-  });
-
-  test('splitComplementary returns 3 slots', () => {
-    const seed: ZoraHexColor = '#0f766e';
-    const harmony: ZoraComputedHarmony = computeZoraHarmony(seed, 'splitComplementary');
-
-    expect(harmony.orderedSlots).toHaveLength(3);
-    expect(getSlotIds(harmony.orderedSlots)).toEqual(['base', 'a', 'b']);
-  });
-
-  test('triadic returns 3 slots', () => {
-    const seed: ZoraHexColor = '#0f766e';
-    const harmony: ZoraComputedHarmony = computeZoraHarmony(seed, 'triadic');
-
-    expect(harmony.orderedSlots).toHaveLength(3);
-    expect(getSlotIds(harmony.orderedSlots)).toEqual(['base', 'a', 'b']);
-  });
-
-  test('tetradic returns 4 slots', () => {
-    const seed: ZoraHexColor = '#0f766e';
-    const harmony: ZoraComputedHarmony = computeZoraHarmony(seed, 'tetradic');
-
-    expect(harmony.orderedSlots).toHaveLength(4);
-    expect(getSlotIds(harmony.orderedSlots)).toEqual(['base', 'a', 'b', 'c']);
-  });
-
-  test('every computed hue is normalized to [0, 360)', () => {
-    const seed: ZoraHexColor = '#0f766e';
-    const harmonies = [
-      'monochromatic',
-      'complementary',
-      'analogous',
-      'splitComplementary',
-      'triadic',
-      'tetradic',
-    ] as const;
-
-    for (const kind of harmonies) {
-      const computed = computeZoraHarmony(seed, kind);
-      for (const slot of computed.orderedSlots) {
-        expectNormalizedHue(slot.hue);
-      }
-    }
-  });
-
-  test('base slot approximately matches parsed seed hue for a non-neutral seed', () => {
-    const seed: ZoraHexColor = '#ff00ff';
-    const seedOklch = parseHexToOklch(seed);
-
-    const computed = computeZoraHarmony(seed, 'complementary');
-    const [base] = computed.orderedSlots;
-
-    expect(base).toBeDefined();
-    if (!base) {
-      throw new Error('Expected a base harmony slot.');
-    }
-
-    expect(base.id).toBe('base');
-    expect(hueDeltaDegrees(seedOklch.h, base.hue)).toBeLessThan(0.5);
-  });
-
-  test('neutral/low-chroma seed uses a stable fallback hue', () => {
-    const seed: ZoraHexColor = '#808080';
-    const computed = computeZoraHarmony(seed, 'monochromatic');
-
-    expect(computed.orderedSlots).toHaveLength(1);
-    expect(computed.orderedSlots[0].hue).toBe(260);
-  });
-
-  test('is deterministic for the same seed/harmony', () => {
-    const seed: ZoraHexColor = '#0f766e';
-
-    expect(computeZoraHarmony(seed, 'triadic')).toEqual(computeZoraHarmony(seed, 'triadic'));
-  });
-
-  test('complementary slots are based on base hue + 180', () => {
-    const seed: ZoraHexColor = '#0f766e';
-    const computed = computeZoraHarmony(seed, 'complementary');
-    const [base, a] = computed.orderedSlots;
-
-    expect(base).toBeDefined();
-    expect(a).toBeDefined();
-    if (!base || !a) {
-      throw new Error('Expected complementary harmony slots.');
-    }
-
-    expect(hueDeltaDegrees(a.hue, normalizeHueDegrees(base.hue + 180))).toBeLessThan(0.0001);
-  });
-
-  test('throws on invalid seed in test/development', () => {
-    const invalid: ZoraHexColor = '#nope';
-
-    expect(() => computeZoraHarmony(invalid, 'triadic')).toThrow();
-  });
-});

package/src/internal/color/harmony.ts

@@ -1,96 +0,0 @@
-import type { ZoraColorHarmony, ZoraHexColor } from '../../theme/types';
-import { normalizeHueDegrees, rotateHueDegrees } from './hue';
-import { parseHexToOklch } from './oklch';
-
-export type ZoraHarmonySlotId = 'base' | 'a' | 'b' | 'c';
-
-export interface ZoraHarmonySlot {
-  id: ZoraHarmonySlotId;
-  hue: number;
-}
-
-export interface ZoraComputedHarmony {
-  kind: ZoraColorHarmony;
-  orderedSlots: readonly ZoraHarmonySlot[];
-}
-
-const DEFAULT_HARMONY_HUE_DEGREES = 260;
-const MIN_SEED_CHROMA_FOR_HARMONY_HUE = 0.03;
-
-function createSlot(id: ZoraHarmonySlotId, hue: number): ZoraHarmonySlot {
-  return { id, hue: normalizeHueDegrees(hue) };
-}
-
-function resolveSeedHueDegrees(seed: ZoraHexColor): number {
-  const parsed = parseHexToOklch(seed);
-
-  if (!Number.isFinite(parsed.h) || parsed.c < MIN_SEED_CHROMA_FOR_HARMONY_HUE) {
-    return DEFAULT_HARMONY_HUE_DEGREES;
-  }
-
-  return normalizeHueDegrees(parsed.h);
-}
-
-export function computeZoraHarmony(
-  seed: ZoraHexColor,
-  harmony: ZoraColorHarmony,
-): ZoraComputedHarmony {
-  const baseHue = resolveSeedHueDegrees(seed);
-
-  if (harmony === 'monochromatic') {
-    return {
-      kind: harmony,
-      orderedSlots: [createSlot('base', baseHue)],
-    };
-  }
-
-  if (harmony === 'complementary') {
-    return {
-      kind: harmony,
-      orderedSlots: [createSlot('base', baseHue), createSlot('a', rotateHueDegrees(baseHue, 180))],
-    };
-  }
-
-  if (harmony === 'analogous') {
-    return {
-      kind: harmony,
-      orderedSlots: [
-        createSlot('base', baseHue),
-        createSlot('a', rotateHueDegrees(baseHue, -30)),
-        createSlot('b', rotateHueDegrees(baseHue, 30)),
-      ],
-    };
-  }
-
-  if (harmony === 'splitComplementary') {
-    return {
-      kind: harmony,
-      orderedSlots: [
-        createSlot('base', baseHue),
-        createSlot('a', rotateHueDegrees(baseHue, 150)),
-        createSlot('b', rotateHueDegrees(baseHue, 210)),
-      ],
-    };
-  }
-
-  if (harmony === 'triadic') {
-    return {
-      kind: harmony,
-      orderedSlots: [
-        createSlot('base', baseHue),
-        createSlot('a', rotateHueDegrees(baseHue, 120)),
-        createSlot('b', rotateHueDegrees(baseHue, 240)),
-      ],
-    };
-  }
-
-  return {
-    kind: harmony,
-    orderedSlots: [
-      createSlot('base', baseHue),
-      createSlot('a', rotateHueDegrees(baseHue, 90)),
-      createSlot('b', rotateHueDegrees(baseHue, 180)),
-      createSlot('c', rotateHueDegrees(baseHue, 270)),
-    ],
-  };
-}

package/src/internal/color/hue.test.ts

@@ -1,28 +0,0 @@
-import { describe, expect, test } from 'bun:test';
-
-import { normalizeHueDegrees, rotateHueDegrees } from './hue';
-
-describe('normalizeHueDegrees', () => {
-  test('normalizes negative hues into [0, 360)', () => {
-    expect(normalizeHueDegrees(-30)).toBe(330);
-    expect(normalizeHueDegrees(-390)).toBe(330);
-  });
-
-  test('normalizes hues >= 360 into [0, 360)', () => {
-    expect(normalizeHueDegrees(390)).toBe(30);
-    expect(normalizeHueDegrees(720)).toBe(0);
-  });
-
-  test('preserves in-range hues', () => {
-    expect(normalizeHueDegrees(0)).toBe(0);
-    expect(normalizeHueDegrees(12.5)).toBe(12.5);
-    expect(normalizeHueDegrees(359.99)).toBe(359.99);
-  });
-});
-
-describe('rotateHueDegrees', () => {
-  test('rotates and normalizes', () => {
-    expect(rotateHueDegrees(350, 30)).toBe(20);
-    expect(rotateHueDegrees(10, -30)).toBe(340);
-  });
-});

package/src/internal/color/hue.ts

@@ -1,7 +0,0 @@
-export function normalizeHueDegrees(hue: number): number {
-  return ((hue % 360) + 360) % 360;
-}
-
-export function rotateHueDegrees(hue: number, delta: number): number {
-  return normalizeHueDegrees(hue + delta);
-}

package/src/internal/color/index.ts

@@ -1,44 +0,0 @@
-export {
-  getZoraColorToneRecipe,
-  getZoraColorToneRoleChromaFactor,
-  type ZoraColorToneLaneRecipe,
-  type ZoraColorToneRecipe,
-  type ZoraColorToneRoleChromaFactors,
-} from './colorToneRecipes';
-export {
-  computeZoraHarmony,
-  type ZoraComputedHarmony,
-  type ZoraHarmonySlot,
-  type ZoraHarmonySlotId,
-} from './harmony';
-export { parseHexToOklch } from './oklch';
-export { resolveModePrimaryColor } from './primary';
-export {
-  assignZoraHarmonyRoleHues,
-  getZoraHueRoleAssignment,
-  type ZoraComputedHueRoles,
-  type ZoraHueRoleAssignment,
-  type ZoraHueRoleId,
-} from './roleHues';
-export {
-  createZoraRoleColorScales,
-  getZoraRoleColorScale,
-  ZORA_COLOR_SCALE_ROLE_ORDER,
-  type ZoraColorScaleRoleId,
-  type ZoraComputedRoleColorScales,
-  type ZoraRoleColorScale,
-} from './roleScales';
-export {
-  createZoraColorScale,
-  type CreateZoraColorScaleOptions,
-  type CreateZoraHueScaleOptions,
-  createZoraNeutralScale,
-  createZoraPrimaryScale,
-  type ZoraHueScaleRoleId,
-} from './scales';
-export {
-  createZoraSemanticColorTokens,
-  getReadableTextColor,
-  type ZoraSemanticColorTokens,
-} from './semanticTokens';
-export { ZORA_COLOR_SCALE_STEPS, type ZoraColorScale, type ZoraColorScaleStep } from './types';

package/src/internal/color/oklch.ts

@@ -1,65 +0,0 @@
-import { converter, formatHex, parse, toGamut } from 'culori';
-
-import type { ZoraHexColor } from '../../theme/types';
-import { normalizeHueDegrees } from './hue';
-import type { ZoraOklchColor } from './types';
-
-const toOklch = converter('oklch');
-const gamutMapToSrgb = toGamut('rgb', 'oklch');
-
-function isSixDigitHexColor(value: string): value is ZoraHexColor {
-  return /^#[0-9a-fA-F]{6}$/.test(value);
-}
-
-export function parseHexToOklch(hex: ZoraHexColor): ZoraOklchColor {
-  if (!isSixDigitHexColor(hex)) {
-    throw new Error(`Expected a 6-digit hex color like '#0f766e', got '${String(hex)}'.`);
-  }
-
-  const parsed = parse(hex);
-  if (!parsed) {
-    throw new Error(`Unable to parse hex color '${String(hex)}'.`);
-  }
-
-  const oklch = toOklch(parsed);
-  if (typeof oklch.l !== 'number' || typeof oklch.c !== 'number') {
-    throw new Error(`Unable to convert hex color '${String(hex)}' to OKLCH.`);
-  }
-
-  return {
-    l: oklch.l,
-    c: oklch.c,
-    h: normalizeHueDegrees(typeof oklch.h === 'number' ? oklch.h : 0),
-  };
-}
-
-export function formatOklchAsHex(color: ZoraOklchColor): ZoraHexColor {
-  const mapped = gamutMapToSrgb({ mode: 'oklch', l: color.l, c: color.c, h: color.h });
-  const hex = formatHex(mapped);
-
-  if (!hex || !isSixDigitHexColor(hex)) {
-    throw new Error('Unable to format OKLCH color as a 6-digit hex value.');
-  }
-
-  const normalized = hex.toLowerCase();
-  if (!isSixDigitHexColor(normalized)) {
-    throw new Error('Unable to format OKLCH color as a 6-digit hex value.');
-  }
-
-  return normalized;
-}
-
-export function clampOklchToGamut(color: ZoraOklchColor): ZoraOklchColor {
-  const mapped = gamutMapToSrgb({ mode: 'oklch', l: color.l, c: color.c, h: color.h });
-  const clamped = toOklch(mapped);
-
-  if (typeof clamped.l !== 'number' || typeof clamped.c !== 'number') {
-    throw new Error('Unable to clamp OKLCH color to sRGB gamut.');
-  }
-
-  return {
-    l: clamped.l,
-    c: clamped.c,
-    h: normalizeHueDegrees(typeof clamped.h === 'number' ? clamped.h : 0),
-  };
-}

package/src/internal/color/primary.test.ts

@@ -1,105 +0,0 @@
-import { describe, expect, test } from 'bun:test';
-
-import type { ZoraHexColor } from '../../theme/types';
-import { parseHexToOklch } from './oklch';
-import { resolveModePrimaryColor } from './primary';
-
-function isSixDigitHexColor(value: string): value is ZoraHexColor {
-  return /^#[0-9a-f]{6}$/.test(value);
-}
-
-function hueDeltaDegrees(a: number, b: number): number {
-  const raw = Math.abs(a - b) % 360;
-  return Math.min(raw, 360 - raw);
-}
-
-describe('resolveModePrimaryColor', () => {
-  test('returns valid hex for light and dark mode', () => {
-    const seed: ZoraHexColor = '#0f766e';
-
-    const light = resolveModePrimaryColor(seed, 'light');
-    const dark = resolveModePrimaryColor(seed, 'dark');
-
-    expect(isSixDigitHexColor(light)).toBe(true);
-    expect(isSixDigitHexColor(dark)).toBe(true);
-  });
-
-  test('derives different colors for light vs dark for a typical saturated seed', () => {
-    const seed: ZoraHexColor = '#0f766e';
-
-    const light = resolveModePrimaryColor(seed, 'light');
-    const dark = resolveModePrimaryColor(seed, 'dark');
-
-    expect(light).not.toBe(dark);
-  });
-
-  test('dark derived primary has higher OKLCH lightness than the light derived primary', () => {
-    const seed: ZoraHexColor = '#0f766e';
-
-    const light = resolveModePrimaryColor(seed, 'light');
-    const dark = resolveModePrimaryColor(seed, 'dark');
-
-    const lightOklch = parseHexToOklch(light);
-    const darkOklch = parseHexToOklch(dark);
-
-    expect(darkOklch.l).toBeGreaterThan(lightOklch.l);
-  });
-
-  test('preserves hue approximately for a non-neutral seed', () => {
-    const seed: ZoraHexColor = '#0f766e';
-    const seedOklch = parseHexToOklch(seed);
-
-    const light = resolveModePrimaryColor(seed, 'light');
-    const dark = resolveModePrimaryColor(seed, 'dark');
-
-    const lightOklch = parseHexToOklch(light);
-    const darkOklch = parseHexToOklch(dark);
-
-    expect(hueDeltaDegrees(seedOklch.h, lightOklch.h)).toBeLessThan(20);
-    expect(hueDeltaDegrees(seedOklch.h, darkOklch.h)).toBeLessThan(20);
-  });
-
-  test('bounds chroma', () => {
-    const seed: ZoraHexColor = '#ff00ff';
-
-    const light = resolveModePrimaryColor(seed, 'light');
-    const dark = resolveModePrimaryColor(seed, 'dark');
-
-    const lightOklch = parseHexToOklch(light);
-    const darkOklch = parseHexToOklch(dark);
-
-    expect(lightOklch.c).toBeLessThanOrEqual(0.18 + 0.01);
-    expect(darkOklch.c).toBeLessThanOrEqual(0.2 + 0.01);
-  });
-
-  test('handles low-chroma colors without crashing', () => {
-    const seed: ZoraHexColor = '#808080';
-
-    const light = resolveModePrimaryColor(seed, 'light');
-    const dark = resolveModePrimaryColor(seed, 'dark');
-
-    expect(isSixDigitHexColor(light)).toBe(true);
-    expect(isSixDigitHexColor(dark)).toBe(true);
-  });
-
-  test('throws on invalid hex in test/development', () => {
-    const invalid: ZoraHexColor = '#nope';
-
-    expect(() => resolveModePrimaryColor(invalid, 'light')).toThrow();
-  });
-
-  test('falls back in production when input is invalid', () => {
-    const invalid: ZoraHexColor = '#nope';
-
-    const originalEnv = process.env.NODE_ENV;
-    process.env.NODE_ENV = 'production';
-
-    try {
-      const resolved = resolveModePrimaryColor(invalid, 'light');
-      expect(resolved).not.toBe('#0f766e');
-      expect(resolved).toBe(resolveModePrimaryColor('#0f766e', 'light'));
-    } finally {
-      process.env.NODE_ENV = originalEnv;
-    }
-  });
-});

package/src/internal/color/primary.ts

@@ -1,64 +0,0 @@
-import type { ZoraHexColor, ZoraThemeMode } from '../../theme/types';
-import { clampOklchToGamut, formatOklchAsHex, parseHexToOklch } from './oklch';
-import type { ZoraOklchColor } from './types';
-
-const FALLBACK_PRIMARY_COLOR: ZoraHexColor = '#0f766e';
-
-const LIGHT_PRIMARY_LIGHTNESS_TARGET = 0.52;
-const DARK_PRIMARY_LIGHTNESS_TARGET = 0.72;
-
-const MIN_PRIMARY_CHROMA = 0.04;
-const MAX_LIGHT_PRIMARY_CHROMA = 0.18;
-const MAX_DARK_PRIMARY_CHROMA = 0.2;
-
-const LIGHTNESS_BLEND = 0.85;
-
-function clampNumber(value: number, min: number, max: number): number {
-  return Math.max(min, Math.min(value, max));
-}
-
-function resolveModePrimaryTargetLightness(mode: ZoraThemeMode): number {
-  return mode === 'dark' ? DARK_PRIMARY_LIGHTNESS_TARGET : LIGHT_PRIMARY_LIGHTNESS_TARGET;
-}
-
-function resolveModePrimaryMaxChroma(mode: ZoraThemeMode): number {
-  return mode === 'dark' ? MAX_DARK_PRIMARY_CHROMA : MAX_LIGHT_PRIMARY_CHROMA;
-}
-
-export function resolveModePrimaryColor(
-  primaryColor: ZoraHexColor,
-  mode: ZoraThemeMode,
-): ZoraHexColor {
-  let seed: ZoraOklchColor;
-
-  try {
-    seed = parseHexToOklch(primaryColor);
-  } catch (error) {
-    const message = error instanceof Error ? error.message : String(error);
-
-    if (process.env.NODE_ENV === 'production') {
-      console.warn(`Invalid ZORA primaryColor '${primaryColor}'. Falling back. ${message}`);
-      return resolveModePrimaryColor(FALLBACK_PRIMARY_COLOR, mode);
-    }
-
-    throw error instanceof Error ? error : new Error(message);
-  }
-
-  const targetLightness = resolveModePrimaryTargetLightness(mode);
-  const maxChroma = resolveModePrimaryMaxChroma(mode);
-
-  const blendedLightness = seed.l + (targetLightness - seed.l) * LIGHTNESS_BLEND;
-  const boundedLightness = clampNumber(blendedLightness, 0.12, 0.92);
-
-  const cappedChroma = clampNumber(seed.c, 0, maxChroma);
-  const boundedChroma =
-    seed.c < MIN_PRIMARY_CHROMA ? cappedChroma : Math.max(cappedChroma, MIN_PRIMARY_CHROMA);
-
-  const derived = clampOklchToGamut({
-    l: boundedLightness,
-    c: boundedChroma,
-    h: seed.h,
-  });
-
-  return formatOklchAsHex(derived);
-}