@ankhorage/zora 0.16.2 → 1.0.1

package/src/internal/color/roleHues.ts

@@ -1,142 +0,0 @@
-import type { ZoraColorHarmony } from '../../theme/types';
-import type { ZoraComputedHarmony, ZoraHarmonySlot, ZoraHarmonySlotId } from './harmony';
-import { normalizeHueDegrees } from './hue';
-
-export type ZoraHueRoleId = 'primary' | 'secondary' | 'accent' | 'highlight' | 'surfaceTint';
-
-export interface ZoraHueRoleAssignment {
-  role: ZoraHueRoleId;
-  hue: number;
-  sourceSlotId: ZoraHarmonySlotId;
-}
-
-export interface ZoraComputedHueRoles {
-  harmony: ZoraColorHarmony;
-  assignments: readonly ZoraHueRoleAssignment[];
-}
-
-function findSlot(
-  harmony: ZoraComputedHarmony,
-  id: ZoraHarmonySlotId,
-): ZoraHarmonySlot | undefined {
-  return harmony.orderedSlots.find((slot) => slot.id === id);
-}
-
-function requireBaseSlot(harmony: ZoraComputedHarmony): ZoraHarmonySlot {
-  const base = findSlot(harmony, 'base');
-  if (!base) {
-    throw new Error(`[zora] Expected harmony to include a base slot (kind: ${harmony.kind}).`);
-  }
-  return base;
-}
-
-function assignRole(
-  role: ZoraHueRoleId,
-  harmony: ZoraComputedHarmony,
-  preferred: ZoraHarmonySlotId,
-  fallback: ZoraHarmonySlotId = 'base',
-): ZoraHueRoleAssignment {
-  const base = requireBaseSlot(harmony);
-  const preferredSlot = findSlot(harmony, preferred);
-  const fallbackSlot = findSlot(harmony, fallback);
-  const chosenSlot = preferredSlot ?? fallbackSlot ?? base;
-
-  return {
-    role,
-    hue: normalizeHueDegrees(chosenSlot.hue),
-    sourceSlotId: chosenSlot.id,
-  };
-}
-
-export function assignZoraHarmonyRoleHues(harmony: ZoraComputedHarmony): ZoraComputedHueRoles {
-  const { kind } = harmony;
-
-  if (kind === 'monochromatic') {
-    return {
-      harmony: kind,
-      assignments: [
-        assignRole('primary', harmony, 'base'),
-        assignRole('secondary', harmony, 'base'),
-        assignRole('accent', harmony, 'base'),
-        assignRole('highlight', harmony, 'base'),
-        assignRole('surfaceTint', harmony, 'base'),
-      ],
-    };
-  }
-
-  if (kind === 'complementary') {
-    return {
-      harmony: kind,
-      assignments: [
-        assignRole('primary', harmony, 'base'),
-        assignRole('secondary', harmony, 'base'),
-        assignRole('accent', harmony, 'a'),
-        assignRole('highlight', harmony, 'a'),
-        assignRole('surfaceTint', harmony, 'base'),
-      ],
-    };
-  }
-
-  if (kind === 'analogous') {
-    return {
-      harmony: kind,
-      assignments: [
-        assignRole('primary', harmony, 'base'),
-        assignRole('secondary', harmony, 'a'),
-        assignRole('accent', harmony, 'b', 'a'),
-        assignRole('highlight', harmony, 'b', 'a'),
-        assignRole('surfaceTint', harmony, 'a'),
-      ],
-    };
-  }
-
-  if (kind === 'splitComplementary') {
-    return {
-      harmony: kind,
-      assignments: [
-        assignRole('primary', harmony, 'base'),
-        assignRole('secondary', harmony, 'a'),
-        assignRole('accent', harmony, 'b', 'a'),
-        assignRole('highlight', harmony, 'b', 'a'),
-        assignRole('surfaceTint', harmony, 'base'),
-      ],
-    };
-  }
-
-  if (kind === 'triadic') {
-    return {
-      harmony: kind,
-      assignments: [
-        assignRole('primary', harmony, 'base'),
-        assignRole('secondary', harmony, 'a'),
-        assignRole('accent', harmony, 'b', 'a'),
-        assignRole('highlight', harmony, 'b', 'a'),
-        assignRole('surfaceTint', harmony, 'base'),
-      ],
-    };
-  }
-
-  return {
-    harmony: kind,
-    assignments: [
-      assignRole('primary', harmony, 'base'),
-      assignRole('secondary', harmony, 'a'),
-      assignRole('accent', harmony, 'b', 'a'),
-      assignRole('highlight', harmony, 'c', 'b'),
-      assignRole('surfaceTint', harmony, 'base'),
-    ],
-  };
-}
-
-export function getZoraHueRoleAssignment(
-  roles: ZoraComputedHueRoles,
-  role: ZoraHueRoleId,
-): ZoraHueRoleAssignment {
-  const found = roles.assignments.find((assignment) => assignment.role === role);
-  if (!found) {
-    throw new Error(
-      `[zora] Expected a hue-role assignment for "${role}" (harmony: ${roles.harmony}).`,
-    );
-  }
-  return found;
-}

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

@@ -1,220 +0,0 @@
-import { describe, expect, test } from 'bun:test';
-
-import type { ZoraColorTone, ZoraHexColor } from '../../theme/types';
-import {
-  assignZoraHarmonyRoleHues,
-  computeZoraHarmony,
-  createZoraRoleColorScales,
-  getZoraRoleColorScale,
-  parseHexToOklch,
-  ZORA_COLOR_SCALE_ROLE_ORDER,
-  ZORA_COLOR_SCALE_STEPS,
-  type ZoraColorScale,
-  type ZoraColorScaleStep,
-  type ZoraComputedHueRoles,
-  type ZoraRoleColorScale,
-} from './index';
-
-function isSixDigitLowercaseHexColor(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);
-}
-
-function getStepValues(scale: ZoraColorScale): { step: ZoraColorScaleStep; hex: ZoraHexColor }[] {
-  return ZORA_COLOR_SCALE_STEPS.map((step) => ({ step, hex: scale[step] }));
-}
-
-function assertScaleKeys(scale: ZoraColorScale) {
-  const keys = Object.keys(scale)
-    .map((key) => Number(key))
-    .sort((a, b) => a - b);
-
-  expect(keys).toEqual([...ZORA_COLOR_SCALE_STEPS]);
-}
-
-function assertNoPureBlackOrWhite(scale: ZoraColorScale) {
-  const values = getStepValues(scale).map(({ hex }) => hex);
-  expect(values).not.toContain('#000000');
-  expect(values).not.toContain('#ffffff');
-}
-
-function buildHueRoles(assignments: ZoraComputedHueRoles['assignments']): ZoraComputedHueRoles {
-  return {
-    harmony: 'tetradic',
-    assignments,
-  };
-}
-
-function createCompleteHueRoles(): ZoraComputedHueRoles {
-  return buildHueRoles([
-    { role: 'primary', hue: 120, sourceSlotId: 'base' },
-    { role: 'secondary', hue: 200, sourceSlotId: 'a' },
-    { role: 'accent', hue: 280, sourceSlotId: 'b' },
-    { role: 'highlight', hue: 20, sourceSlotId: 'c' },
-    { role: 'surfaceTint', hue: 160, sourceSlotId: 'a' },
-  ]);
-}
-
-function createScales(colorTone: ZoraColorTone = 'jewel') {
-  return createZoraRoleColorScales({
-    colorTone,
-    hueRoles: createCompleteHueRoles(),
-    seed: '#0f766e',
-  });
-}
-
-function requireHueBackedSourceHue(role: ZoraRoleColorScale): number {
-  if (typeof role.sourceHue !== 'number') {
-    throw new Error(`[zora] Expected "${role.role}" role scale to include a sourceHue.`);
-  }
-  return role.sourceHue;
-}
-
-describe('createZoraRoleColorScales', () => {
-  test('returns all roles exactly once in deterministic order', () => {
-    const scales = createScales();
-
-    expect(scales.roles).toHaveLength(ZORA_COLOR_SCALE_ROLE_ORDER.length);
-    expect(scales.roles.map((entry) => entry.role)).toEqual([...ZORA_COLOR_SCALE_ROLE_ORDER]);
-    expect(new Set(scales.roles.map((entry) => entry.role)).size).toBe(
-      ZORA_COLOR_SCALE_ROLE_ORDER.length,
-    );
-  });
-
-  test('every scale contains exactly all 50–950 keys and valid lowercase 6-digit hex values', () => {
-    const scales = createScales();
-
-    for (const role of scales.roles) {
-      assertScaleKeys(role.scale);
-      for (const { hex } of getStepValues(role.scale)) {
-        expect(isSixDigitLowercaseHexColor(hex)).toBe(true);
-      }
-    }
-  });
-
-  test('output is deterministic for the same input', () => {
-    expect(createScales()).toEqual(createScales());
-  });
-
-  test('role hue is preserved approximately for mid steps', () => {
-    const scales = createZoraRoleColorScales({
-      colorTone: 'jewel',
-      hueRoles: buildHueRoles([
-        { role: 'primary', hue: 115, sourceSlotId: 'base' },
-        { role: 'secondary', hue: 210, sourceSlotId: 'a' },
-        { role: 'accent', hue: 300, sourceSlotId: 'b' },
-        { role: 'highlight', hue: 25, sourceSlotId: 'c' },
-        { role: 'surfaceTint', hue: 165, sourceSlotId: 'a' },
-      ]),
-      seed: '#0f766e',
-    });
-
-    const midSteps: ZoraColorScaleStep[] = [400, 500, 600, 700];
-    for (const roleId of ['primary', 'secondary', 'accent', 'highlight', 'surfaceTint'] as const) {
-      const role = getZoraRoleColorScale(scales, roleId);
-      const expectedHue = requireHueBackedSourceHue(role);
-
-      for (const step of midSteps) {
-        const oklch = parseHexToOklch(role.scale[step]);
-        expect(hueDeltaDegrees(expectedHue, oklch.h)).toBeLessThan(25);
-      }
-    }
-  });
-
-  test('surfaceTint scale has lower chroma than primary/accent/highlight for mid steps', () => {
-    const scales = createScales('jewel');
-    const surfaceTint = getZoraRoleColorScale(scales, 'surfaceTint').scale;
-    const primary = getZoraRoleColorScale(scales, 'primary').scale;
-    const accent = getZoraRoleColorScale(scales, 'accent').scale;
-    const highlight = getZoraRoleColorScale(scales, 'highlight').scale;
-    const step: ZoraColorScaleStep = 500;
-    const surfaceTintChroma = parseHexToOklch(surfaceTint[step]).c;
-
-    expect(surfaceTintChroma).toBeLessThan(parseHexToOklch(primary[step]).c);
-    expect(surfaceTintChroma).toBeLessThan(parseHexToOklch(accent[step]).c);
-    expect(surfaceTintChroma).toBeLessThan(parseHexToOklch(highlight[step]).c);
-  });
-
-  test('colorTone changes role chroma behavior internally', () => {
-    const neutral = createScales('neutral');
-    const fluorescent = createScales('fluorescent');
-    const step: ZoraColorScaleStep = 500;
-
-    const neutralPrimary = parseHexToOklch(getZoraRoleColorScale(neutral, 'primary').scale[step]).c;
-    const fluorescentPrimary = parseHexToOklch(
-      getZoraRoleColorScale(fluorescent, 'primary').scale[step],
-    ).c;
-
-    expect(fluorescentPrimary).toBeGreaterThan(neutralPrimary);
-  });
-
-  test('pastel keeps surfaceTint lower chroma than fluorescent foreground roles', () => {
-    const pastel = createScales('pastel');
-    const fluorescent = createScales('fluorescent');
-    const step: ZoraColorScaleStep = 500;
-
-    const pastelSurfaceTint = parseHexToOklch(
-      getZoraRoleColorScale(pastel, 'surfaceTint').scale[step],
-    ).c;
-    const fluorescentAccent = parseHexToOklch(
-      getZoraRoleColorScale(fluorescent, 'accent').scale[step],
-    ).c;
-
-    expect(pastelSurfaceTint).toBeLessThan(fluorescentAccent);
-  });
-
-  test('neutral scale has low chroma', () => {
-    const neutral = getZoraRoleColorScale(createScales(), 'neutral').scale;
-
-    for (const { hex } of getStepValues(neutral)) {
-      expect(parseHexToOklch(hex).c).toBeLessThanOrEqual(0.03);
-    }
-  });
-
-  test('missing required hue role throws a clear error', () => {
-    const hueRoles = buildHueRoles([
-      { role: 'primary', hue: 120, sourceSlotId: 'base' },
-      { role: 'secondary', hue: 200, sourceSlotId: 'a' },
-      { role: 'accent', hue: 280, sourceSlotId: 'b' },
-      { role: 'surfaceTint', hue: 160, sourceSlotId: 'a' },
-    ]);
-
-    expect(() =>
-      createZoraRoleColorScales({ colorTone: 'jewel', hueRoles, seed: '#0f766e' }),
-    ).toThrow('highlight');
-  });
-
-  test('no role scale contains pure black/white by default', () => {
-    const scales = createScales();
-
-    for (const role of scales.roles) {
-      assertNoPureBlackOrWhite(role.scale);
-    }
-  });
-
-  test('does not mutate input hueRoles', () => {
-    const hueRoles = createCompleteHueRoles();
-    const snapshot = JSON.stringify(hueRoles);
-
-    createZoraRoleColorScales({ colorTone: 'jewel', hueRoles, seed: '#0f766e' });
-
-    expect(JSON.stringify(hueRoles)).toBe(snapshot);
-  });
-
-  test('integration: harmony -> role hues -> role scales pipeline connects', () => {
-    const seed: ZoraHexColor = '#0f766e';
-    const harmony = computeZoraHarmony(seed, 'tetradic');
-    const hueRoles = assignZoraHarmonyRoleHues(harmony);
-
-    const scales = createZoraRoleColorScales({ colorTone: 'jewel', hueRoles, seed });
-
-    expect(scales.roles.map((entry) => entry.role)).toEqual([...ZORA_COLOR_SCALE_ROLE_ORDER]);
-    for (const role of scales.roles) {
-      assertScaleKeys(role.scale);
-    }
-  });
-});

package/src/internal/color/roleScales.ts

@@ -1,127 +0,0 @@
-import type { ZoraColorTone, ZoraHexColor } from '../../theme/types';
-import { getZoraColorToneRecipe } from './colorToneRecipes';
-import { parseHexToOklch } from './oklch';
-import {
-  getZoraHueRoleAssignment,
-  type ZoraComputedHueRoles,
-  type ZoraHueRoleId,
-} from './roleHues';
-import {
-  createZoraHueScale,
-  type CreateZoraHueScaleOptions,
-  createZoraNeutralScale,
-  type ZoraHueScaleRoleId,
-} from './scales';
-import type { ZoraColorScale } from './types';
-
-export type ZoraColorScaleRoleId =
-  | 'primary'
-  | 'secondary'
-  | 'accent'
-  | 'highlight'
-  | 'surfaceTint'
-  | 'neutral';
-
-export const ZORA_COLOR_SCALE_ROLE_ORDER: readonly ZoraColorScaleRoleId[] = [
-  'primary',
-  'secondary',
-  'accent',
-  'highlight',
-  'surfaceTint',
-  'neutral',
-];
-
-export interface ZoraRoleColorScale {
-  role: ZoraColorScaleRoleId;
-  sourceHue?: number;
-  scale: ZoraColorScale;
-}
-
-export interface ZoraComputedRoleColorScales {
-  roles: readonly ZoraRoleColorScale[];
-}
-
-export function getZoraRoleColorScale(
-  scales: ZoraComputedRoleColorScales,
-  role: ZoraColorScaleRoleId,
-): ZoraRoleColorScale {
-  const found = scales.roles.find((entry) => entry.role === role);
-  if (!found) {
-    throw new Error(`[zora] Expected role color scales to include "${role}".`);
-  }
-  return found;
-}
-
-function resolveSeedChroma(seed: ZoraHexColor): number {
-  return parseHexToOklch(seed).c;
-}
-
-function createHueBackedRoleScale(options: {
-  colorTone: ZoraColorTone;
-  hueRoles: ZoraComputedHueRoles;
-  seedChroma: number;
-  role: ZoraHueRoleId;
-}): ZoraRoleColorScale {
-  const assignment = getZoraHueRoleAssignment(options.hueRoles, options.role);
-  const colorToneRecipe = getZoraColorToneRecipe(options.colorTone);
-  const hueScaleRole: ZoraHueScaleRoleId = options.role;
-  const hueScaleOptions: CreateZoraHueScaleOptions = {
-    hue: assignment.hue,
-    seedChroma: options.seedChroma,
-    role: hueScaleRole,
-    colorToneRecipe,
-  };
-
-  return {
-    role: options.role,
-    sourceHue: assignment.hue,
-    scale: createZoraHueScale(hueScaleOptions),
-  };
-}
-
-export function createZoraRoleColorScales(options: {
-  hueRoles: ZoraComputedHueRoles;
-  seed: ZoraHexColor;
-  colorTone: ZoraColorTone;
-}): ZoraComputedRoleColorScales {
-  const seedChroma = resolveSeedChroma(options.seed);
-
-  const roles: ZoraRoleColorScale[] = [
-    createHueBackedRoleScale({
-      colorTone: options.colorTone,
-      hueRoles: options.hueRoles,
-      seedChroma,
-      role: 'primary',
-    }),
-    createHueBackedRoleScale({
-      colorTone: options.colorTone,
-      hueRoles: options.hueRoles,
-      seedChroma,
-      role: 'secondary',
-    }),
-    createHueBackedRoleScale({
-      colorTone: options.colorTone,
-      hueRoles: options.hueRoles,
-      seedChroma,
-      role: 'accent',
-    }),
-    createHueBackedRoleScale({
-      colorTone: options.colorTone,
-      hueRoles: options.hueRoles,
-      seedChroma,
-      role: 'highlight',
-    }),
-    createHueBackedRoleScale({
-      colorTone: options.colorTone,
-      hueRoles: options.hueRoles,
-      seedChroma,
-      role: 'surfaceTint',
-    }),
-    {
-      role: 'neutral',
-      scale: createZoraNeutralScale(options.seed),
-    },
-  ];
-
-  return { roles };
-}

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

@@ -1,151 +0,0 @@
-import { describe, expect, test } from 'bun:test';
-
-import type { ZoraHexColor } from '../../theme/types';
-import {
-  createZoraColorScale,
-  type CreateZoraColorScaleOptions,
-  createZoraNeutralScale,
-  createZoraPrimaryScale,
-  parseHexToOklch,
-  ZORA_COLOR_SCALE_STEPS,
-  type ZoraColorScale,
-  type ZoraColorScaleStep,
-} from './index';
-
-function isSixDigitLowercaseHexColor(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);
-}
-
-function getStepValues(scale: ZoraColorScale): { step: ZoraColorScaleStep; hex: ZoraHexColor }[] {
-  return ZORA_COLOR_SCALE_STEPS.map((step) => ({ step, hex: scale[step] }));
-}
-
-function assertScaleKeys(scale: ZoraColorScale) {
-  const keys = Object.keys(scale)
-    .map((key) => Number(key))
-    .sort((a, b) => a - b);
-
-  expect(keys).toEqual([...ZORA_COLOR_SCALE_STEPS]);
-}
-
-function assertDecreasingLightness(scale: ZoraColorScale) {
-  const lightness = getStepValues(scale).map(({ hex }) => parseHexToOklch(hex).l);
-
-  for (let index = 0; index < lightness.length - 1; index += 1) {
-    expect(lightness[index]).toBeGreaterThan(lightness[index + 1]);
-  }
-}
-
-describe('createZoraPrimaryScale', () => {
-  test('matches createZoraColorScale({ role: primary })', () => {
-    const seed: ZoraHexColor = '#0f766e';
-    const options: CreateZoraColorScaleOptions = { seed, role: 'primary' };
-
-    expect(createZoraPrimaryScale(seed)).toEqual(createZoraColorScale(options));
-  });
-
-  test('returns all 50–950 keys and valid lowercase 6-digit hex values', () => {
-    const seed: ZoraHexColor = '#0f766e';
-    const scale = createZoraPrimaryScale(seed);
-
-    assertScaleKeys(scale);
-
-    for (const { hex } of getStepValues(scale)) {
-      expect(isSixDigitLowercaseHexColor(hex)).toBe(true);
-    }
-  });
-
-  test('is deterministic for the same seed', () => {
-    const seed: ZoraHexColor = '#0f766e';
-
-    expect(createZoraPrimaryScale(seed)).toEqual(createZoraPrimaryScale(seed));
-  });
-
-  test('lightness decreases from 50 to 950', () => {
-    const seed: ZoraHexColor = '#0f766e';
-    const scale = createZoraPrimaryScale(seed);
-
-    assertDecreasingLightness(scale);
-  });
-
-  test('preserves hue approximately for mid steps', () => {
-    const seed: ZoraHexColor = '#0f766e';
-    const seedOklch = parseHexToOklch(seed);
-    const scale = createZoraPrimaryScale(seed);
-
-    const midSteps: ZoraColorScaleStep[] = [400, 500, 600, 700];
-    for (const step of midSteps) {
-      const oklch = parseHexToOklch(scale[step]);
-      expect(hueDeltaDegrees(seedOklch.h, oklch.h)).toBeLessThan(20);
-    }
-  });
-
-  test('mid steps have higher chroma than extremes for a saturated seed', () => {
-    const seed: ZoraHexColor = '#ff00ff';
-    const scale = createZoraPrimaryScale(seed);
-
-    const chroma50 = parseHexToOklch(scale[50]).c;
-    const chroma950 = parseHexToOklch(scale[950]).c;
-    const chroma500 = parseHexToOklch(scale[500]).c;
-    const chroma600 = parseHexToOklch(scale[600]).c;
-
-    const extremes = Math.max(chroma50, chroma950);
-    const mid = Math.max(chroma500, chroma600);
-
-    expect(mid).toBeGreaterThan(extremes);
-  });
-
-  test('bounds saturated inputs to stay in gamut', () => {
-    const seed: ZoraHexColor = '#ff00ff';
-    const scale = createZoraPrimaryScale(seed);
-
-    for (const { hex } of getStepValues(scale)) {
-      expect(isSixDigitLowercaseHexColor(hex)).toBe(true);
-      expect(() => parseHexToOklch(hex)).not.toThrow();
-    }
-  });
-
-  test('throws on invalid seed in test/development', () => {
-    const invalid: ZoraHexColor = '#nope';
-
-    expect(() => createZoraPrimaryScale(invalid)).toThrow();
-  });
-});
-
-describe('createZoraNeutralScale', () => {
-  test('works with and without a seed', () => {
-    const seeded = createZoraNeutralScale('#0f766e');
-    const unseeded = createZoraNeutralScale();
-
-    assertScaleKeys(seeded);
-    assertScaleKeys(unseeded);
-  });
-
-  test('returns low-chroma neutrals', () => {
-    const scale = createZoraNeutralScale('#0f766e');
-
-    for (const { hex } of getStepValues(scale)) {
-      const oklch = parseHexToOklch(hex);
-      expect(oklch.c).toBeLessThanOrEqual(0.03);
-    }
-  });
-
-  test('lightness decreases from 50 to 950', () => {
-    const scale = createZoraNeutralScale('#0f766e');
-
-    assertDecreasingLightness(scale);
-  });
-
-  test('avoids pure black/white in the generated steps', () => {
-    const scale = createZoraNeutralScale('#0f766e');
-    const values = getStepValues(scale).map(({ hex }) => hex);
-
-    expect(values).not.toContain('#000000');
-    expect(values).not.toContain('#ffffff');
-  });
-});