@ankhorage/zora 0.12.0 → 0.12.2

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

@@ -0,0 +1,151 @@
+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');
+  });
+});

package/src/internal/color/scales.ts

@@ -0,0 +1,145 @@
+import type { ZoraHexColor } from '../../theme/types';
+import { clampOklchToGamut, formatOklchAsHex, parseHexToOklch } from './oklch';
+import { type ZoraColorScale, type ZoraColorScaleStep } from './types';
+
+export interface CreateZoraColorScaleOptions {
+  seed: ZoraHexColor;
+  role?: 'primary' | 'neutral';
+}
+
+const PRIMARY_LIGHTNESS_BY_STEP: Record<ZoraColorScaleStep, number> = {
+  50: 0.97,
+  100: 0.93,
+  200: 0.86,
+  300: 0.78,
+  400: 0.68,
+  500: 0.58,
+  600: 0.5,
+  700: 0.42,
+  800: 0.34,
+  900: 0.27,
+  950: 0.2,
+};
+
+const NEUTRAL_LIGHTNESS_BY_STEP: Record<ZoraColorScaleStep, number> = {
+  50: 0.98,
+  100: 0.95,
+  200: 0.89,
+  300: 0.8,
+  400: 0.68,
+  500: 0.55,
+  600: 0.44,
+  700: 0.34,
+  800: 0.25,
+  900: 0.18,
+  950: 0.12,
+};
+
+const PRIMARY_CHROMA_MULTIPLIER_BY_STEP: Record<ZoraColorScaleStep, number> = {
+  50: 0.2,
+  100: 0.3,
+  200: 0.45,
+  300: 0.7,
+  400: 0.95,
+  500: 1,
+  600: 0.95,
+  700: 0.85,
+  800: 0.65,
+  900: 0.45,
+  950: 0.3,
+};
+
+const MAX_PRIMARY_SCALE_CHROMA = 0.2;
+const MIN_PRIMARY_SCALE_CHROMA = 0.04;
+const NEUTRAL_CHROMA = 0.012;
+const DEFAULT_NEUTRAL_HUE_DEGREES = 260;
+
+function clampNumber(value: number, min: number, max: number): number {
+  return Math.max(min, Math.min(value, max));
+}
+
+function resolvePrimaryScaleChroma(seedChroma: number, step: ZoraColorScaleStep): number {
+  const cappedSeedChroma = clampNumber(seedChroma, 0, MAX_PRIMARY_SCALE_CHROMA);
+  const multiplier = PRIMARY_CHROMA_MULTIPLIER_BY_STEP[step];
+  const scaled = cappedSeedChroma * multiplier;
+
+  const bounded = clampNumber(scaled, 0, MAX_PRIMARY_SCALE_CHROMA);
+  const shouldEnforceMin = step >= 300 && step <= 700 && seedChroma >= MIN_PRIMARY_SCALE_CHROMA;
+
+  return shouldEnforceMin ? Math.max(bounded, MIN_PRIMARY_SCALE_CHROMA) : bounded;
+}
+
+function createScaleEntries(options: CreateZoraColorScaleOptions): ZoraColorScale {
+  const seed = parseHexToOklch(options.seed);
+
+  if (options.role === 'neutral') {
+    const hue = typeof seed.h === 'number' ? seed.h : DEFAULT_NEUTRAL_HUE_DEGREES;
+
+    return createScaleFromRamp({
+      hue,
+      chroma: NEUTRAL_CHROMA,
+      lightnessByStep: NEUTRAL_LIGHTNESS_BY_STEP,
+    });
+  }
+
+  return createScaleFromRamp({
+    hue: seed.h,
+    chromaByStep: (step) => resolvePrimaryScaleChroma(seed.c, step),
+    lightnessByStep: PRIMARY_LIGHTNESS_BY_STEP,
+  });
+}
+
+interface CreateScaleFromRampOptions {
+  hue: number;
+  chroma?: number;
+  chromaByStep?: (step: ZoraColorScaleStep) => number;
+  lightnessByStep: Record<ZoraColorScaleStep, number>;
+}
+
+function createScaleColor(
+  options: CreateScaleFromRampOptions,
+  step: ZoraColorScaleStep,
+): ZoraHexColor {
+  const lightness = options.lightnessByStep[step];
+  const chroma =
+    typeof options.chromaByStep === 'function' ? options.chromaByStep(step) : (options.chroma ?? 0);
+
+  const clamped = clampOklchToGamut({
+    l: clampNumber(lightness, 0, 1),
+    c: clampNumber(chroma, 0, 1),
+    h: options.hue,
+  });
+
+  return formatOklchAsHex(clamped);
+}
+
+function createScaleFromRamp(options: CreateScaleFromRampOptions): ZoraColorScale {
+  return {
+    50: createScaleColor(options, 50),
+    100: createScaleColor(options, 100),
+    200: createScaleColor(options, 200),
+    300: createScaleColor(options, 300),
+    400: createScaleColor(options, 400),
+    500: createScaleColor(options, 500),
+    600: createScaleColor(options, 600),
+    700: createScaleColor(options, 700),
+    800: createScaleColor(options, 800),
+    900: createScaleColor(options, 900),
+    950: createScaleColor(options, 950),
+  };
+}
+
+export function createZoraColorScale(options: CreateZoraColorScaleOptions): ZoraColorScale {
+  return createScaleEntries({
+    seed: options.seed,
+    role: options.role,
+  });
+}
+
+export function createZoraPrimaryScale(seed: ZoraHexColor): ZoraColorScale {
+  return createZoraColorScale({ seed, role: 'primary' });
+}
+
+export function createZoraNeutralScale(seed: ZoraHexColor = '#94a3b8'): ZoraColorScale {
+  return createZoraColorScale({ seed, role: 'neutral' });
+}

package/src/internal/color/types.ts

@@ -1,5 +1,15 @@
+import type { ZoraHexColor } from '../../theme/types';
+
 export interface ZoraOklchColor {
   l: number;
   c: number;
   h: number;
 }
+
+export const ZORA_COLOR_SCALE_STEPS = [
+  50, 100, 200, 300, 400, 500, 600, 700, 800, 900, 950,
+] as const;
+
+export type ZoraColorScaleStep = (typeof ZORA_COLOR_SCALE_STEPS)[number];
+
+export type ZoraColorScale = Record<ZoraColorScaleStep, ZoraHexColor>;