Search

Turn user intent into a stable, query-ready target. The search helpers convert names, curated palette picks, image-extracted colors, and gradient selections into normalized OKLab payloads.

Material preset

Using Textiles colors like bright deep orange, muted dark orange, muted deep orange.

Tolerance mapping

0.111

Targetpalette

#2d1a06

#634d36

#211612

Label

3 colors

Preview count

Anchor L

0.238

Anchor a

0.019

Anchor b

0.040

Threshold

0.111

Query payload

{
  "type": "palette",
  "label": "3 colors",
  "threshold": 0.111,
  "previewColors": [
    "#2d1a06",
    "#634d36",
    "#211612"
  ],
  "anchor": {
    "L": 0.238,
    "a": 0.019,
    "b": 0.04
  }
}

import {
  computeColorTarget,
  computeGradientTarget,
  computeImageTarget,
  computeNameTarget,
  computePaletteTarget,
  computeSearchTarget,
} from "colorscope/search";
import { toleranceToThreshold } from "colorscope/tolerance";

Functions

computeSearchTarget

Route one workflow state object into the correct search target.

function computeSearchTarget(input: ComputeSearchTargetInput): SearchTarget

Use this when your UI supports multiple search modes but your backend expects one normalized target shape.

const target = computeSearchTarget({
  state: {
    mode: "palette",
    paletteColors: ["#c2704a", "#335f99", "#7f8f6a"],
    paletteLogic: "all",
    searchName: null,
    colorHex: null,
    moodPreset: null,
    gradientStart: null,
    gradientEnd: null,
    temperature: 0,
    lightness: 0.5,
  },
});

computeNameTarget

function computeNameTarget(state: SearchTargetState): OklabTarget | NoSelectionTarget

Resolve a typed color name like "terracotta" or "sage" into the nearest curated ColourGroup.

computePaletteTarget

function computePaletteTarget(state: SearchTargetState): PaletteTarget | NoSelectionTarget

Convert selected palette hex values into a multi-color target. The first valid color becomes the anchor point and all valid colors are preserved in colors.

computeImageTarget

function computeImageTarget(
  imageColors: readonly ExtractedColor[],
  selectedImageIndices?: readonly number[]
): PaletteTarget | NoSelectionTarget

Use image extraction output directly. Colors with missing oklab values are ignored, and the most dominant five selected colors are kept.

computeGradientTarget

function computeGradientTarget(state: SearchTargetState): GradientTarget | NoSelectionTarget

Turn two chosen endpoints into a gradient target with a midpoint anchor.

computeColorTarget

function computeColorTarget(state: SearchTargetState): OklabTarget | NoSelectionTarget

Convert a single picked hex color into an OKLab target.

Types

SearchTargetState

interface SearchTargetState {
  mode: "search" | "mood" | "color" | "palette" | "gradient" | "image";
  searchName: string | null;
  colorHex: string | null;
  paletteColors: string[];
  paletteLogic: "all" | "any";
  gradientStart: string | null;
  gradientEnd: string | null;
  moodPreset: string | null;
  temperature: number;
  lightness: number;
}

SearchTarget

type SearchTarget =
  | NoSelectionTarget
  | OklabTarget
  | PaletteTarget
  | ImageTarget
  | GradientTarget

Every active target carries:

type for routing
previewColors for UI
anchor L, a, b coordinates for perceptual matching

Pairing With Tolerance

The search module intentionally does not decide how tight a match should be. Pair it with colorscope/tolerance:

import { toleranceToThreshold } from "colorscope/tolerance";

const threshold = toleranceToThreshold(0.45);
// 0.089...