@rafters/color-utils 0.2.3

package/src/naming/index.ts

@@ -0,0 +1,50 @@
+/**
+ * Deterministic Color Naming Module
+ *
+ * Generates unique, semantically meaningful color names from OKLCH values
+ * using temperature and perceptual weight for word selection.
+ *
+ * @example
+ * ```ts
+ * import { generateColorName } from '@rafters/color-utils';
+ *
+ * const name = generateColorName({ l: 0.65, c: 0.12, h: 230, alpha: 1 });
+ * // Returns: "luminous-true-cobalt"
+ * ```
+ */
+
+export { generateColorName, generateColorNameWithMetadata } from './generator.js';
+export {
+  BLUE_HUB,
+  type ChromaBand,
+  GREEN_HUB,
+  getChromaBand,
+  getExpandedMaterialWord,
+  getLightnessBand,
+  getSubIndex,
+  HUE_HUBS,
+  type HueCell,
+  type HueHub,
+  type HueMatrix,
+  hasExpandedHub,
+  type LightnessBand,
+  RED_HUB,
+} from './hue-hubs.js';
+export {
+  C_BUCKET_COUNT,
+  getAllBuckets,
+  getCBucket,
+  getHBucket,
+  getLBucket,
+  H_BUCKET_COUNT,
+  L_BUCKET_COUNT,
+  TOTAL_COMBINATIONS,
+} from './quantize.js';
+export {
+  INTENSITY_WORDS,
+  type IntensityWord,
+  LUMINOSITY_WORDS,
+  type LuminosityWord,
+  MATERIAL_WORDS,
+  type MaterialWord,
+} from './word-banks.js';

package/src/naming/quantize.ts

@@ -0,0 +1,85 @@
+/**
+ * Quantization functions for OKLCH to bucket mapping
+ *
+ * These functions map continuous OKLCH values to discrete bucket indices
+ * for deterministic word selection from the word banks.
+ */
+
+import { clamp, clamp01, MAX_CHROMA, normalizeHue } from '../internal/math.js';
+
+/**
+ * Get luminosity bucket index (0-9) from lightness value (0-1)
+ * 10 buckets of 0.1 each
+ */
+export function getLBucket(l: number): number {
+  // Clamp to valid range
+  const clamped = clamp01(l);
+  // Map to 0-9 bucket index
+  const bucket = Math.floor(clamped * 10);
+  // Handle edge case where l === 1.0
+  return Math.min(bucket, 9);
+}
+
+/**
+ * Get chroma bucket index (0-7) from chroma value (0-0.37+)
+ * 8 buckets with non-linear spacing for perceptual uniformity
+ */
+export function getCBucket(c: number): number {
+  // Clamp to valid range (OKLCH chroma rarely exceeds 0.37)
+  const clamped = clamp(c, 0, MAX_CHROMA);
+
+  // Non-linear bucket boundaries optimized for perceptual differences
+  // Lower chroma values get finer granularity
+  if (clamped < 0.03) return 0; // achromatic
+  if (clamped < 0.06) return 1; // very muted
+  if (clamped < 0.1) return 2; // muted
+  if (clamped < 0.15) return 3; // moderate
+  if (clamped < 0.2) return 4; // saturated
+  if (clamped < 0.25) return 5; // vivid
+  if (clamped < 0.3) return 6; // very vivid
+  return 7; // maximum saturation
+}
+
+/**
+ * Get hue bucket index (0-17) from hue angle (0-360)
+ * 18 buckets of 20 degrees each
+ */
+export function getHBucket(h: number): number {
+  // Normalize hue to 0-360 range (handle negative and > 360)
+  const normalized = normalizeHue(h);
+  // Map to 0-17 bucket index
+  const bucket = Math.floor(normalized / 20);
+  // Handle edge case where h === 360
+  return Math.min(bucket, 17);
+}
+
+/**
+ * Get all bucket indices for an OKLCH color
+ * Useful for debugging and testing
+ */
+export function getAllBuckets(
+  l: number,
+  c: number,
+  h: number,
+): {
+  lBucket: number;
+  cBucket: number;
+  hBucket: number;
+} {
+  return {
+    lBucket: getLBucket(l),
+    cBucket: getCBucket(c),
+    hBucket: getHBucket(h),
+  };
+}
+
+// Constants for bucket counts
+export const L_BUCKET_COUNT = 10;
+export const C_BUCKET_COUNT = 8;
+export const H_BUCKET_COUNT = 18;
+
+// Total possible unique combinations
+export const TOTAL_COMBINATIONS = L_BUCKET_COUNT * C_BUCKET_COUNT * H_BUCKET_COUNT;
+// = 10 * 8 * 18 = 1,440 unique chromatic names
+// + 10 * 8 = 80 achromatic names (no hue word)
+// = 1,520 total unique names minimum (without temperature/density variants)

package/src/naming/word-banks.ts

@@ -0,0 +1,154 @@
+/**
+ * Word Banks for Deterministic Color Naming
+ *
+ * Three independent word banks map to OKLCH dimensions:
+ * - Luminosity (L): brightness-based words describing light levels
+ * - Intensity (C): chroma-descriptive words describing saturation level
+ * - Material (H): objects/places/nature describing hue
+ *
+ * Each bank is organized by bucket index. Temperature and perceptual
+ * density select which variant of a word to use for semantic meaning.
+ *
+ * RESERVED SEGMENTS (#1637): no bank word may be 'to', 'via', or 'from',
+ * nor start/end with one as a hyphen segment. Generated names join bank
+ * words with single hyphens, and the fill signature parser splits on
+ * '-to-' -- a violating word would make a family name unparseable as a
+ * fill. Enforced by the reservation test in test/naming.test.ts.
+ */
+
+/**
+ * Luminosity words by lightness bucket (0-1 in 10 steps)
+ * Index 0 = darkest (0.0-0.1), Index 9 = lightest (0.9-1.0)
+ *
+ * Uses brightness-based words that describe luminance without implying
+ * grayscale materials, allowing natural composition with chromatic hues.
+ */
+export const LUMINOSITY_WORDS: readonly string[] = [
+  'shadow', // 0.0-0.1: darkest
+  'dark', // 0.1-0.2
+  'deep', // 0.2-0.3
+  'dim', // 0.3-0.4
+  'mid', // 0.4-0.5
+  'balanced', // 0.5-0.6
+  'luminous', // 0.6-0.7
+  'pale', // 0.7-0.8
+  'faint', // 0.8-0.9
+  'brilliant', // 0.9-1.0: lightest
+] as const;
+
+/**
+ * Intensity words by chroma bucket, split by perceptual density
+ * Each density level has words for 8 chroma buckets (0-0.37+)
+ *
+ * Words describe saturation/chroma level, not personality.
+ */
+export const INTENSITY_WORDS: Record<'light' | 'medium' | 'heavy', readonly string[]> = {
+  light: [
+    'dust', // 0.00-0.03: near-achromatic (achromatic threshold is 0.02, not 0.03)
+    'wash', // 0.03-0.06
+    'soft', // 0.06-0.10
+    'clean', // 0.10-0.15
+    'clear', // 0.15-0.20
+    'pure', // 0.20-0.25
+    'vivid', // 0.25-0.30
+    'bright', // 0.30+
+  ],
+  medium: [
+    'ash', // 0.00-0.03
+    'faded', // 0.03-0.06
+    'quiet', // 0.06-0.10
+    'true', // 0.10-0.15
+    'firm', // 0.15-0.20
+    'bold', // 0.20-0.25
+    'sharp', // 0.25-0.30
+    'neon', // 0.30+
+  ],
+  heavy: [
+    'smoke', // 0.00-0.03
+    'muted', // 0.03-0.06
+    'worn', // 0.06-0.10
+    'rich', // 0.10-0.15
+    'strong', // 0.15-0.20
+    'dense', // 0.20-0.25 ("deep" excluded: already in LUMINOSITY_WORDS)
+    'full', // 0.25-0.30
+    'hot', // 0.30+
+  ],
+} as const;
+
+/**
+ * Material words by hue bucket (18 buckets at 20 each), split by temperature
+ * Temperature influences word choice for more semantic meaning
+ */
+export const MATERIAL_WORDS: Record<'warm' | 'cool' | 'neutral', readonly string[]> = {
+  warm: [
+    'ember', // 0-20: red
+    'copper', // 20-40: orange-red
+    'amber', // 40-60: orange
+    'honey', // 60-80: yellow-orange
+    'citrine', // 80-100: yellow
+    'chartreuse', // 100-120: yellow-green
+    'fern', // 120-140: green
+    'sage', // 140-160: green-cyan
+    'lagoon', // 160-180: cyan
+    'azure', // 180-200: cyan-blue
+    'cerulean', // 200-220: light blue
+    'cobalt', // 220-240: blue
+    'indigo', // 240-260: blue-violet
+    'iris', // 260-280: violet
+    'orchid', // 280-300: purple
+    'fuchsia', // 300-320: magenta
+    'rose', // 320-340: pink
+    'crimson', // 340-360: red-pink
+  ],
+  cool: [
+    'rust', // 0-20
+    'terracotta', // 20-40
+    'sienna', // 40-60
+    'flax', // 60-80
+    'canary', // 80-100
+    'lime', // 100-120
+    'moss', // 120-140
+    'mint', // 140-160
+    'teal', // 160-180
+    'glacier', // 180-200
+    'sky', // 200-220
+    'sapphire', // 220-240
+    'navy', // 240-260
+    'violet', // 260-280
+    'plum', // 280-300
+    'magenta', // 300-320
+    'raspberry', // 320-340
+    'scarlet', // 340-360
+  ],
+  neutral: [
+    'clay', // 0-20
+    'cinnamon', // 20-40
+    'marigold', // 40-60
+    'buttercup', // 60-80
+    'pear', // 80-100
+    'olive', // 100-120
+    'spruce', // 120-140
+    'seafoam', // 140-160
+    'aqua', // 160-180
+    'arctic', // 180-200
+    'pacific', // 200-220
+    'denim', // 220-240
+    'midnight', // 240-260
+    'lavender', // 260-280
+    'amethyst', // 280-300
+    'peony', // 300-320
+    'cherry', // 320-340
+    'poppy', // 340-360
+  ],
+} as const;
+
+// Type exports for external use
+export type LuminosityWord = (typeof LUMINOSITY_WORDS)[number];
+export type IntensityWord =
+  | (typeof INTENSITY_WORDS.light)[number]
+  | (typeof INTENSITY_WORDS.medium)[number]
+  | (typeof INTENSITY_WORDS.heavy)[number];
+export type MaterialWord =
+  | (typeof MATERIAL_WORDS.warm)[number]
+  | (typeof MATERIAL_WORDS.cool)[number]
+  | (typeof MATERIAL_WORDS.neutral)[number];

package/src/scale-positions.ts

@@ -0,0 +1,31 @@
+/**
+ * Standard 11-position color scale conventions.
+ *
+ * SCALE_POSITIONS maps array indices 0-10 to the canonical Tailwind-style
+ * position labels (50, 100, 200, ..., 950). POSITION_TO_INDEX is the inverse.
+ *
+ * Selection logic (foreground pairs, state ladders, dark counterparts) lives
+ * in semantic.ts — this module is scale vocabulary only.
+ */
+
+export const SCALE_POSITIONS = [
+  '50',
+  '100',
+  '200',
+  '300',
+  '400',
+  '500',
+  '600',
+  '700',
+  '800',
+  '900',
+  '950',
+] as const;
+
+export const POSITION_TO_INDEX: Record<string, number> = SCALE_POSITIONS.reduce(
+  (acc, position, index) => {
+    acc[position] = index;
+    return acc;
+  },
+  {} as Record<string, number>,
+);