@ankhorage/zora 0.16.2 → 1.0.0

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');
-  });
-});

package/src/internal/color/scales.ts

@@ -1,194 +0,0 @@
-import type { ZoraHexColor } from '../../theme/types';
-import type { ZoraColorToneRecipe } from './colorToneRecipes';
-import { getZoraColorToneRoleChromaFactor } from './colorToneRecipes';
-import { clampOklchToGamut, formatOklchAsHex, parseHexToOklch } from './oklch';
-import { type ZoraColorScale, type ZoraColorScaleStep } from './types';
-
-export interface CreateZoraColorScaleOptions {
-  seed: ZoraHexColor;
-  role?: 'primary' | 'neutral';
-}
-
-export type ZoraHueScaleRoleId = 'primary' | 'secondary' | 'accent' | 'highlight' | 'surfaceTint';
-
-export interface CreateZoraHueScaleOptions {
-  hue: number;
-  seedChroma: number;
-  role: ZoraHueScaleRoleId;
-  colorToneRecipe: ZoraColorToneRecipe;
-}
-
-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 resolveRoleScaleChroma(options: {
-  seedChroma: number;
-  step: ZoraColorScaleStep;
-  maxChroma: number;
-  minMidChroma: number;
-}): number {
-  const cappedSeedChroma = clampNumber(options.seedChroma, 0, options.maxChroma);
-  const multiplier = PRIMARY_CHROMA_MULTIPLIER_BY_STEP[options.step];
-  const scaled = cappedSeedChroma * multiplier;
-  const bounded = clampNumber(scaled, 0, options.maxChroma);
-  const shouldEnforceMin =
-    options.step >= 300 && options.step <= 700 && options.seedChroma >= options.minMidChroma;
-
-  return shouldEnforceMin ? Math.max(bounded, options.minMidChroma) : bounded;
-}
-
-function resolveHueScaleChroma(
-  options: CreateZoraHueScaleOptions,
-  step: ZoraColorScaleStep,
-): number {
-  const factor = getZoraColorToneRoleChromaFactor(options.colorToneRecipe, options.role);
-
-  return resolveRoleScaleChroma({
-    seedChroma: options.seedChroma * factor,
-    step,
-    maxChroma: options.colorToneRecipe.maxChroma,
-    minMidChroma: options.colorToneRecipe.minMidChroma,
-  });
-}
-
-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' });
-}
-
-export function createZoraHueScale(options: CreateZoraHueScaleOptions): ZoraColorScale {
-  return createScaleFromRamp({
-    hue: options.hue,
-    chromaByStep: (step) => resolveHueScaleChroma(options, step),
-    lightnessByStep: PRIMARY_LIGHTNESS_BY_STEP,
-  });
-}

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

@@ -1,170 +0,0 @@
-import { describe, expect, test } from 'bun:test';
-
-import type { ZoraColorTone, ZoraHexColor } from '../../theme/types';
-import {
-  assignZoraHarmonyRoleHues,
-  computeZoraHarmony,
-  createZoraRoleColorScales,
-  createZoraSemanticColorTokens,
-  getReadableTextColor,
-  type ZoraComputedRoleColorScales,
-  type ZoraSemanticColorTokens,
-} from './index';
-
-function isSixDigitLowercaseHex(value: string): value is ZoraHexColor {
-  return /^#[0-9a-f]{6}$/.test(value);
-}
-
-function getLightness(hex: ZoraHexColor): number {
-  // Intentionally a simple RGB average rather than OKLCH — serves as a
-  // perceptual proxy for test assertions only. The production implementation
-  // in getReadableTextColor uses OKLCH lightness via parseHexToOklch.
-  const r = parseInt(hex.slice(1, 3), 16) / 255;
-  const g = parseInt(hex.slice(3, 5), 16) / 255;
-  const b = parseInt(hex.slice(5, 7), 16) / 255;
-  return (r + g + b) / 3;
-}
-
-function buildRoleScales(colorTone: ZoraColorTone = 'jewel'): ZoraComputedRoleColorScales {
-  const seed: ZoraHexColor = '#0f766e';
-  const harmony = computeZoraHarmony(seed, 'tetradic');
-  const hueRoles = assignZoraHarmonyRoleHues(harmony);
-  return createZoraRoleColorScales({ colorTone, hueRoles, seed });
-}
-
-function buildLight(colorTone: ZoraColorTone = 'jewel'): ZoraSemanticColorTokens {
-  return createZoraSemanticColorTokens({
-    roleScales: buildRoleScales(colorTone),
-    mode: 'light',
-    colorTone,
-  });
-}
-
-function buildDark(colorTone: ZoraColorTone = 'jewel'): ZoraSemanticColorTokens {
-  return createZoraSemanticColorTokens({
-    roleScales: buildRoleScales(colorTone),
-    mode: 'dark',
-    colorTone,
-  });
-}
-
-describe('createZoraSemanticColorTokens', () => {
-  test('all output values are lowercase 6-digit hex', () => {
-    const light = buildLight();
-    const dark = buildDark();
-
-    for (const tokens of [light, dark]) {
-      for (const key of Object.keys(tokens) as (keyof ZoraSemanticColorTokens)[]) {
-        const value = tokens[key];
-        expect(isSixDigitLowercaseHex(value), `${key} must be lowercase 6-digit hex`).toBe(true);
-      }
-    }
-  });
-
-  test('light mode background is lighter than dark mode background', () => {
-    const light = buildLight();
-    const dark = buildDark();
-
-    expect(getLightness(light.background)).toBeGreaterThan(getLightness(dark.background));
-  });
-
-  test('text has opposite lightness direction from background (light mode)', () => {
-    const light = buildLight();
-
-    expect(getLightness(light.text)).toBeLessThan(getLightness(light.background));
-  });
-
-  test('text has opposite lightness direction from background (dark mode)', () => {
-    const dark = buildDark();
-
-    expect(getLightness(dark.text)).toBeGreaterThan(getLightness(dark.background));
-  });
-
-  test('primary, accent, and highlight are distinct from background and surface (light)', () => {
-    const light = buildLight();
-
-    for (const token of [light.primary, light.accent, light.highlight] as const) {
-      expect(token).not.toBe(light.background);
-      expect(token).not.toBe(light.surface);
-    }
-  });
-
-  test('primary, accent, and highlight are distinct from background and surface (dark)', () => {
-    const dark = buildDark();
-
-    for (const token of [dark.primary, dark.accent, dark.highlight] as const) {
-      expect(token).not.toBe(dark.background);
-      expect(token).not.toBe(dark.surface);
-    }
-  });
-
-  test('onPrimary is readable against primary (light mode)', () => {
-    const light = buildLight();
-    const primaryL = getLightness(light.primary);
-    const onPrimaryL = getLightness(light.onPrimary);
-
-    expect(Math.abs(primaryL - onPrimaryL)).toBeGreaterThan(0.3);
-  });
-
-  test('onPrimary is readable against primary (dark mode)', () => {
-    const dark = buildDark();
-    const primaryL = getLightness(dark.primary);
-    const onPrimaryL = getLightness(dark.onPrimary);
-
-    expect(Math.abs(primaryL - onPrimaryL)).toBeGreaterThan(0.3);
-  });
-
-  test('onAccent is readable against accent (light mode)', () => {
-    const light = buildLight();
-    const accentL = getLightness(light.accent);
-    const onAccentL = getLightness(light.onAccent);
-
-    expect(Math.abs(accentL - onAccentL)).toBeGreaterThan(0.3);
-  });
-
-  test('colorTone changes at least one output token between neutral and fluorescent', () => {
-    const lightNeutral = buildLight('neutral');
-    const lightFluorescent = buildLight('fluorescent');
-
-    const tokens: (keyof ZoraSemanticColorTokens)[] = [
-      'primary',
-      'secondary',
-      'accent',
-      'highlight',
-    ];
-
-    const anyChanged = tokens.some((k) => lightNeutral[k] !== lightFluorescent[k]);
-    expect(anyChanged).toBe(true);
-  });
-
-  test('output is deterministic for same input', () => {
-    const first = buildLight();
-    const second = buildLight();
-
-    expect(first).toEqual(second);
-  });
-
-  test('surface is distinct from surfaceRaised in dark mode', () => {
-    const dark = buildDark();
-
-    expect(dark.surface).not.toBe(dark.surfaceRaised);
-  });
-});
-
-describe('getReadableTextColor', () => {
-  test('returns the candidate with greater lightness difference from background', () => {
-    const background: ZoraHexColor = '#ffffff';
-    const dark: ZoraHexColor = '#111111';
-    const light: ZoraHexColor = '#eeeeee';
-
-    expect(getReadableTextColor(background, [dark, light])).toBe(dark);
-  });
-
-  test('returns the lighter candidate when background is dark', () => {
-    const background: ZoraHexColor = '#111111';
-    const dark: ZoraHexColor = '#333333';
-    const light: ZoraHexColor = '#eeeeee';
-
-    expect(getReadableTextColor(background, [dark, light])).toBe(light);
-  });
-});

package/src/internal/color/semanticTokens.ts

@@ -1,114 +0,0 @@
-import type { ZoraColorTone, ZoraHexColor, ZoraThemeMode } from '../../theme/types';
-import { parseHexToOklch } from './oklch';
-import { getZoraRoleColorScale, type ZoraComputedRoleColorScales } from './roleScales';
-
-export interface ZoraSemanticColorTokens {
-  background: ZoraHexColor;
-  surface: ZoraHexColor;
-  surfaceRaised: ZoraHexColor;
-  surfaceTint: ZoraHexColor;
-  border: ZoraHexColor;
-  text: ZoraHexColor;
-  textMuted: ZoraHexColor;
-  primary: ZoraHexColor;
-  secondary: ZoraHexColor;
-  accent: ZoraHexColor;
-  highlight: ZoraHexColor;
-  onPrimary: ZoraHexColor;
-  onAccent: ZoraHexColor;
-}
-
-/**
- * Selects the more readable of two candidate hex colors against a given background,
- * using OKLCH lightness as a simple contrast proxy.
- */
-export function getReadableTextColor(
-  background: ZoraHexColor,
-  candidates: readonly [ZoraHexColor, ZoraHexColor],
-): ZoraHexColor {
-  const bgL = parseHexToOklch(background).l;
-  const [a, b] = candidates;
-  const diffA = Math.abs(parseHexToOklch(a).l - bgL);
-  const diffB = Math.abs(parseHexToOklch(b).l - bgL);
-  return diffA >= diffB ? a : b;
-}
-
-export function createZoraSemanticColorTokens(options: {
-  roleScales: ZoraComputedRoleColorScales;
-  mode: ZoraThemeMode;
-  colorTone: ZoraColorTone;
-}): ZoraSemanticColorTokens {
-  // colorTone is accepted now and reserved for future per-tone step overrides
-  // (e.g. obsidian/pastel may shift surface selections differently).
-  const { roleScales, mode } = options;
-
-  const neutral = getZoraRoleColorScale(roleScales, 'neutral').scale;
-  const surfaceTintScale = getZoraRoleColorScale(roleScales, 'surfaceTint').scale;
-  const primaryScale = getZoraRoleColorScale(roleScales, 'primary').scale;
-  const secondaryScale = getZoraRoleColorScale(roleScales, 'secondary').scale;
-  const accentScale = getZoraRoleColorScale(roleScales, 'accent').scale;
-  const highlightScale = getZoraRoleColorScale(roleScales, 'highlight').scale;
-
-  if (mode === 'light') {
-    const background = neutral[50];
-    const surface = neutral[100];
-    const surfaceRaised = neutral[50];
-    const surfaceTint = surfaceTintScale[100];
-    const border = neutral[200];
-    const text = neutral[900];
-    const textMuted = neutral[700];
-    const primary = primaryScale[600];
-    const secondary = secondaryScale[600];
-    const accent = accentScale[600];
-    const highlight = highlightScale[600];
-    const onPrimary = getReadableTextColor(primary, [neutral[50], neutral[950]]);
-    const onAccent = getReadableTextColor(accent, [neutral[50], neutral[950]]);
-
-    return {
-      background,
-      surface,
-      surfaceRaised,
-      surfaceTint,
-      border,
-      text,
-      textMuted,
-      primary,
-      secondary,
-      accent,
-      highlight,
-      onPrimary,
-      onAccent,
-    };
-  }
-
-  // dark mode
-  const background = neutral[950];
-  const surface = neutral[900];
-  const surfaceRaised = neutral[800];
-  const surfaceTint = surfaceTintScale[900];
-  const border = neutral[700];
-  const text = neutral[50];
-  const textMuted = neutral[300];
-  const primary = primaryScale[400];
-  const secondary = secondaryScale[400];
-  const accent = accentScale[400];
-  const highlight = highlightScale[400];
-  const onPrimary = getReadableTextColor(primary, [neutral[50], neutral[950]]);
-  const onAccent = getReadableTextColor(accent, [neutral[50], neutral[950]]);
-
-  return {
-    background,
-    surface,
-    surfaceRaised,
-    surfaceTint,
-    border,
-    text,
-    textMuted,
-    primary,
-    secondary,
-    accent,
-    highlight,
-    onPrimary,
-    onAccent,
-  };
-}

package/src/internal/color/types.ts

@@ -1,15 +0,0 @@
-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>;