grid-rules

// Rules as data for a grid: which cells to color, which rows to show, and the order, as plain objects
// a desk's support staff can write without a build, compiled here into the functions the grid runs.
//
// A rule names a column by its key and reads a row through that column's own accessor. A value typed
// into a rule is read in the column's own format through its `parse`, so a price rule on a 32nds
// column is written the way the column prints, "99-16+"; a numeric column without one reads a plain
// number with commas only between thousands. Tones are token names, never a literal
// color, and an applied rule carries its meaning in a channel besides the color: `data-rule` names
// the rule on the element and the rule's words go in the element's accessible description (contract
// rule 15). Nothing here decides a value; it only compares what the row says with what the rule says.
import { stripGrouping } from "@/lib/format"

export type RuleOp = "eq" | "ne" | "gt" | "gte" | "lt" | "lte" | "between" | "in" | "contains" | "startsWith" | "isNull" | "notNull"

/** What a rule compares against, as typed. A string is read in the column's format; a number or boolean is used as it is. */
export type RuleValue = string | number | boolean | null

/** A token name. The soft variant, or a 12% tint for primary and destructive, tints the background; the text on it is the foreground. */
export type RuleTone = "up" | "down" | "flat" | "stale" | "expiring" | "primary" | "destructive"

export interface RuleCondition {
  op: RuleOp
  /** For eq, ne, gt, gte, lt, lte, contains, and startsWith. */
  value?: RuleValue
  /** For between (two: low, then high, both inclusive) and in (any number). Each is read as `value` is. */
  values?: RuleValue[]
}

export interface ColumnRule {
  id: string
  /** The column whose value the rule reads, by key. */
  column: string
  when: RuleCondition
  tone: RuleTone
  /** The rule in words: the accessible description of what it paints. `describeRule` writes one when it is left out. */
  label?: string
  /** What the tone paints: the cell in `column` (default), or the whole row. */
  target?: "cell" | "row"
}

export interface FilterRule extends RuleCondition {
  column: string
}

export interface SortRule {
  key: string
  dir: "asc" | "desc"
}

export interface GridRules {
  /** Cells and rows to color. The first rule in the list that matches a cell decides it. */
  columns?: ColumnRule[]
  /** Every rule has to hold for a row to show. */
  filter?: FilterRule[]
  /** The first rule that tells two rows apart decides their order. */
  sort?: SortRule[]
}

// The types above are rules as you write them. Rules read from saved data are looser: any field can be missing but
// a sort key's direction, which reads as ascending unless it says descending, and an op or a tone can be text this version doesn't know, for `ruleProblem` to name. The readers return these,
// and every helper, the grid, and the editor take them, so code that reads a rule's fields checks them first.

/** A condition as read from saved data: its op can be missing or unknown text. */
export interface ReadCondition extends Omit<RuleCondition, "op"> {
  op?: string
}

/** A highlight as read from saved data: any field can be missing, and its tone can be unknown text. */
export interface ReadColumnRule extends Omit<ColumnRule, "id" | "column" | "when" | "tone"> {
  id?: string
  column?: string
  when?: ReadCondition
  tone?: string
}

/** A filter rule as read from saved data: its column and op can be missing, and its op unknown text. */
export interface ReadFilterRule extends ReadCondition {
  column?: string
}

/** A sort key as read from saved data: its key can be missing. */
export interface ReadSortRule extends Omit<SortRule, "key"> {
  key?: string
}

/** Rules as read from saved data. A set of rules you wrote is one of these too. */
export interface ReadGridRules {
  columns?: ReadColumnRule[]
  filter?: ReadFilterRule[]
  sort?: ReadSortRule[]
}

/** Which list a rule comes from, for the helpers that judge or describe one rule. */
export type RuleKind = "highlight" | "filter"

/** What a rule needs of a column. The grid's `ColumnDef` satisfies it. */
export interface RuleColumn<T> {
  key: string
  /** Named in a rule's words when it is a string, unless `title` names it; the key otherwise. */
  header?: unknown
  /** The column's name in words, before its header. */
  title?: string
  accessor: (row: T) => unknown
  numeric?: boolean
  /** Reads a value typed into a rule in this column's own format. Default: a number for a numeric column, the text itself for the rest. */
  parse?: (text: string) => unknown
  /** Prints a parsed rule value in the rule's words, so a description says what the rule compares — a data-grid column's `format` fits when it reads only the value, since no row exists here. */
  format?: (value: unknown, ...rest: never[]) => string
}

export const RULE_OPS: readonly RuleOp[] = ["eq", "ne", "gt", "gte", "lt", "lte", "between", "in", "contains", "startsWith", "isNull", "notNull"]
export const NUMBER_OPS: readonly RuleOp[] = ["eq", "ne", "gt", "gte", "lt", "lte", "between", "in", "isNull", "notNull"]
export const TEXT_OPS: readonly RuleOp[] = ["eq", "ne", "contains", "startsWith", "in", "isNull", "notNull"]

/** The word for each op, as a rule reads aloud: "Price above 99-16+". */
export const RULE_OP_LABELS: Record<RuleOp, string> = {
  eq: "is",
  ne: "is not",
  gt: "above",
  gte: "at or above",
  lt: "below",
  lte: "at or below",
  between: "between",
  in: "one of",
  contains: "contains",
  startsWith: "starts with",
  isNull: "is empty",
  notNull: "is not empty",
}

/** The words a rule and its problems are written in. Templates fill `{name}`, `{op}`, `{value}`, `{column}`, `{tone}`, `{low}`, and `{high}`. */
export interface RuleWords {
  ops: Record<RuleOp, string>
  tones: Record<RuleTone, string>
  /** The two ends of a range, `{low}` and `{high}`. */
  range: string
  needsColumn: string
  noColumn: string
  needsComparison: string
  noComparison: string
  needsValue: string
  unreadable: string
  rangeNeedsEnds: string
  rangeOrder: string
  setNeedsValue: string
  needsTone: string
  noTone: string
}

/** Words to replace: any of them, a partial map of comparisons or tones included. */
export type RuleWordsInput = Partial<Omit<RuleWords, "ops" | "tones">> & { ops?: Partial<Record<RuleOp, string>>; tones?: Partial<Record<RuleTone, string>> }

export const DEFAULT_RULE_WORDS: RuleWords = {
  ops: RULE_OP_LABELS,
  tones: { up: "up", down: "down", flat: "flat", stale: "stale", expiring: "expiring", primary: "primary", destructive: "destructive" },
  range: "{low} and {high}",
  needsColumn: "The rule needs a column.",
  noColumn: 'No column is named "{name}".',
  needsComparison: "The rule needs a comparison.",
  noComparison: 'No comparison is named "{op}".',
  needsValue: "{op} needs a value.",
  unreadable: '"{value}" is not a value {column} reads.',
  rangeNeedsEnds: "{op} needs a low value and a high value.",
  rangeOrder: "{op} needs a low value at or below the high value.",
  setNeedsValue: "{op} needs at least one value.",
  needsTone: "The rule needs a tone.",
  noTone: 'No tone is named "{tone}".',
}

/** The defaults with yours over them, maps merged key by key. */
// An undefined word keeps its default, as DataGrid's labels do.
const defined = <W extends object>(words: W | undefined): Partial<W> => Object.fromEntries(Object.entries(words ?? {}).filter(([, word]) => word !== undefined)) as Partial<W>

export function ruleWords(words?: RuleWordsInput): RuleWords {
  return { ...DEFAULT_RULE_WORDS, ...defined(words), ops: { ...DEFAULT_RULE_WORDS.ops, ...defined(words?.ops) }, tones: { ...DEFAULT_RULE_WORDS.tones, ...defined(words?.tones) } }
}

const fillWords = (template: string, values: Record<string, string>) => template.replace(/\{(\w+)\}/g, (match, key: string) => values[key] ?? match)

export const RULE_TONES: readonly RuleTone[] = ["up", "down", "flat", "stale", "expiring", "primary", "destructive"]

/**
 * The text on a tint: the foreground, with any up, down, flat, stale, expiring, destructive, or primary text inside
 * taking it too. A state color on a tint can drop below 4.5 to 1 in the light themes, and every state the library
 * colors also says itself another way, by a sign, a word, or a description. Put it beside every tint behind text.
 */
export const ON_TINT_CLASS = "text-foreground [&_.text-up]:text-inherit [&_.text-down]:text-inherit [&_.text-flat]:text-inherit [&_.text-stale]:text-inherit [&_.text-expiring]:text-inherit [&_.text-destructive]:text-inherit [&_.text-primary]:text-inherit [&_.text-muted-foreground]:text-inherit"

// A tone is a tint of the token's soft variant, painted as a background image rather than a background
// color so it layers over whatever color the element already has: a frozen cell keeps its opaque
// `bg-background` under the tint and stays opaque as rows scroll beneath it. Literal strings, so Tailwind finds them.
const ON_TINT = ON_TINT_CLASS
export const RULE_TONE_CLASS: Record<RuleTone, string> = {
  up: `${ON_TINT} bg-[linear-gradient(var(--up-soft),var(--up-soft))]`,
  down: `${ON_TINT} bg-[linear-gradient(var(--down-soft),var(--down-soft))]`,
  flat: `${ON_TINT} bg-[linear-gradient(var(--flat-soft),var(--flat-soft))]`,
  stale: `${ON_TINT} bg-[linear-gradient(var(--stale-soft),var(--stale-soft))]`,
  expiring: `${ON_TINT} bg-[linear-gradient(var(--expiring-soft),var(--expiring-soft))]`,
  primary: `${ON_TINT} bg-[linear-gradient(color-mix(in_oklab,var(--primary)_12%,transparent),color-mix(in_oklab,var(--primary)_12%,transparent))]`,
  destructive: `${ON_TINT} bg-[linear-gradient(color-mix(in_oklab,var(--destructive)_12%,transparent),color-mix(in_oklab,var(--destructive)_12%,transparent))]`,
}

/** What an applied rule puts on a cell or a row. */
export interface RuleDecoration {
  "data-rule": string
  /** The rule's tone as text, absent when the rule has none: one outside RULE_TONES paints nothing. */
  "data-tone"?: string
  "aria-description": string
  className: string
}

/** The ops a column offers: comparisons and ranges for a numeric column, text matching for the rest. */
export function opsFor(column: { numeric?: boolean } | undefined): readonly RuleOp[] {
  return column?.numeric ? NUMBER_OPS : TEXT_OPS
}

/** The column's name in words: its title, else its header when that is a string, else its key. */
export function columnName<T>(column: RuleColumn<T> | undefined, key?: string): string {
  if (column && typeof column.title === "string" && column.title.trim()) return column.title
  if (column && typeof column.header === "string" && column.header.trim()) return column.header
  return column?.key ?? textOf(key) ?? ""
}

/** Null for null, undefined, NaN, and the infinities; the value otherwise. */
export function normalizeValue(value: unknown): unknown {
  if (value === null || value === undefined) return null
  if (typeof value === "number" && !Number.isFinite(value)) return null
  return value
}

/** Nulls last, numbers numerically, everything else as text. */
export function compareValues(a: unknown, b: unknown): number {
  const an = normalizeValue(a) === null
  const bn = normalizeValue(b) === null
  if (an && bn) return 0
  if (an) return 1
  if (bn) return -1
  if (typeof a === "number" && typeof b === "number") return a - b
  return String(a).localeCompare(String(b))
}

/** `compareValues` in a direction, with a null last whichever way the list runs: a missing price never leads a list sorted high to low. */
export function compareDirected(a: unknown, b: unknown, dir: "asc" | "desc"): number {
  const an = normalizeValue(a) === null
  const bn = normalizeValue(b) === null
  if (an || bn) return compareValues(a, b)
  const c = compareValues(a, b)
  return dir === "desc" ? -c : c
}

/**
 * A value as typed into a rule, read for a column: a string goes through the column's `parse`, or for
 * a numeric column through `stripGrouping` and `Number`, and stays text otherwise; a number or boolean is used as it is.
 * Null when there is nothing to read, and null never matches anything but `isNull`.
 */
export function readRuleValue<T>(column: RuleColumn<T> | undefined, raw: RuleValue | undefined): unknown {
  if (raw === undefined || raw === null) return null
  if (typeof raw === "number" || typeof raw === "boolean") return normalizeValue(raw)
  // Anything else that is not text (an object or a list in a rule's JSON) has nothing to read.
  if (typeof raw !== "string") return null
  if (column?.parse) return normalizeValue(column.parse(raw))
  if (column?.numeric) {
    // The column's notation is unknown here, so a comma reads only as a thousands separator and one comma with no
    // point after it, which reads either way, is no number: "1,5" is never 15, and "4,253" never 4253.
    if (raw.trim() === "") return null
    const text = stripGrouping(raw, { decimals: true })
    return text === null ? null : normalizeValue(Number(text))
  }
  return raw
}

function same(a: unknown, b: unknown): boolean {
  if (typeof a === "string" && typeof b === "string") return a.toLowerCase() === b.toLowerCase()
  if (typeof a === "number" && typeof b === "string") return a === Number(b)
  if (typeof a === "string" && typeof b === "number") return Number(a) === b
  return a === b
}

const needsValue = new Set<RuleOp>(["eq", "ne", "gt", "gte", "lt", "lte", "contains", "startsWith"])

/** True for an op this module compares with. Other text, inherited names such as `toString` included, is not one. */
function isRuleOp(op: unknown): op is RuleOp {
  return typeof op === "string" && (RULE_OPS as readonly string[]).includes(op)
}

/** True for a tone this module paints with. */
function isRuleTone(tone: unknown): tone is RuleTone {
  return typeof tone === "string" && (RULE_TONES as readonly string[]).includes(tone)
}

function isCondition(condition: unknown): condition is RuleCondition {
  return typeof condition === "object" && condition !== null && isRuleOp((condition as RuleCondition).op)
}

// A value that is not text is quoted as its JSON, so an object in a rule reads as `{}`, not [object Object]. One JSON
// cannot print reads through `String`, so a bigint prints its digits, and by its tag when even that throws (an object
// whose own `toString` is not a function), so this never throws.
function shown(raw: unknown): string {
  if (typeof raw === "string") return raw
  if (typeof raw === "number") return String(raw)
  try {
    return JSON.stringify(raw) ?? String(raw)
  } catch {
    try {
      return String(raw)
    } catch {
      return Object.prototype.toString.call(raw)
    }
  }
}

// A name or a word from saved data: text as it is, anything else as its JSON, nothing for null or undefined.
const textOf = (value: unknown): string | undefined => (value === undefined || value === null ? undefined : shown(value))

// A value to compare with: text, a number, a boolean, or null as they are; anything else as its JSON text, so the
// value the editor shows is the value compared and `ruleProblem` can name it.
const valueOf = (value: unknown): RuleValue | undefined =>
  value === undefined ? undefined : value === null || typeof value === "string" || typeof value === "number" || typeof value === "boolean" ? value : shown(value)

// An object that is not a list: what a rule, a condition, or a set of rules is saved as.
const isEntry = (value: unknown): value is object => typeof value === "object" && value !== null && !Array.isArray(value)

// The saved object with the fields this module reads replaced by their readings, or removed when a reading is
// nothing. Every other field an app keeps on a rule (an owner, a flag, an id on a filter) passes through, so an edit
// made from a read rule never loses it.
function keep<R>(saved: Record<string, unknown>, read: Record<string, unknown>): R {
  const rule: Record<string, unknown> = { ...saved }
  for (const [key, value] of Object.entries(read)) {
    if (value === undefined) delete rule[key]
    else rule[key] = value
  }
  return rule as R
}

/**
 * A condition as a desk saved it, read: its op as text (one this module does not know stays as its text, for
 * `ruleProblem` to name), its value as `valueOf` reads it, and its values only from a list; any other field passes
 * through. Undefined when the condition is not an object.
 */
export function readCondition(value: unknown): ReadCondition | undefined {
  if (!isEntry(value)) return undefined
  const saved = value as Record<string, unknown>
  return keep<ReadCondition>(saved, {
    op: textOf(saved.op),
    value: valueOf(saved.value),
    values: Array.isArray(saved.values) ? saved.values.flatMap((item) => (item === undefined ? [] : [valueOf(item)!])) : undefined,
  })
}

/**
 * A highlight as a desk saved it, read: names and words as text, its condition read, a label only when it is text,
 * and the row as its target only when it says so; a field it reads to nothing is left out, and any other field
 * passes through. Null when it is not an object.
 */
export function readColumnRule(value: unknown): ReadColumnRule | null {
  if (!isEntry(value)) return null
  const saved = value as Record<string, unknown>
  return keep<ReadColumnRule>(saved, {
    id: textOf(saved.id),
    column: textOf(saved.column),
    when: readCondition(saved.when),
    tone: textOf(saved.tone),
    label: typeof saved.label === "string" ? saved.label : undefined,
    target: saved.target === "row" || saved.target === "cell" ? saved.target : undefined,
  })
}

/** A filter rule as a desk saved it, read as a condition on its column; any other field passes through. Null when it is not an object. */
export function readFilterRule(value: unknown): ReadFilterRule | null {
  if (!isEntry(value)) return null
  return keep<ReadFilterRule>(readCondition(value) as unknown as Record<string, unknown>, { column: textOf((value as Record<string, unknown>).column) })
}

/** A sort key as a desk saved it, read: its key as text, descending only when it says so; any other field passes through. Null when it is not an object. */
export function readSortRule(value: unknown): ReadSortRule | null {
  if (!isEntry(value)) return null
  const saved = value as Record<string, unknown>
  return keep<ReadSortRule>(saved, { key: textOf(saved.key), dir: saved.dir === "desc" ? "desc" : "asc" })
}

/**
 * Rules a desk saved or shared, read into the shape the grid and the editor take: a list that is not a list is
 * left out, an entry that is not an object is dropped, and each rule is read as `readColumnRule`, `readFilterRule`,
 * and `readSortRule` read it; any other field passes through. Nothing is decided here: a rule that cannot apply
 * still reads, for `ruleProblem` to name.
 */
export function readRules(value: unknown): ReadGridRules {
  if (!isEntry(value)) return {}
  const saved = value as Record<string, unknown>
  const list = <R,>(items: unknown, read: (item: unknown) => R | null): R[] | undefined =>
    Array.isArray(items) ? items.flatMap((item) => { const rule = read(item); return rule ? [rule] : [] }) : undefined
  return keep<ReadGridRules>(saved, { columns: list(saved.columns, readColumnRule), filter: list(saved.filter, readFilterRule), sort: list(saved.sort, readSortRule) })
}

// A highlight carries its condition in `when` and has a tone; a filter rule carries its condition flat and has no tone.
const isHighlightShape = (rule: object) => "when" in rule || "tone" in rule

// A list that is not a list reads as none.
const listOf = (value: unknown): readonly unknown[] => (Array.isArray(value) ? value : [])

// A list of values that is not a list reads as none.
const valuesOf = (condition: { values?: unknown }): readonly RuleValue[] => (Array.isArray(condition.values) ? condition.values : [])

/**
 * One condition compiled against one column: the typed values are read once, and the function that
 * comes back only compares. A row whose value is null answers only `isNull` and `notNull`. Rules are
 * data a desk edits, so a condition that is missing or names no op this module knows matches nothing
 * rather than throwing, as do `in` and `between` when their `values` are not a list; `ruleProblem` says
 * what is wrong with it.
 */
export function compileCondition<T>(saved: ReadCondition | undefined, column: RuleColumn<T>): (row: T) => boolean {
  const condition = readCondition(saved)
  if (!isCondition(condition)) return () => false
  const { op } = condition
  const want = readRuleValue(column, condition.value)
  const list = valuesOf(condition).map((v) => readRuleValue(column, v)).filter((v) => v !== null)
  const read = (row: T) => normalizeValue(column.accessor(row))
  switch (op) {
    case "isNull":
      return (row) => read(row) === null
    case "notNull":
      return (row) => read(row) !== null
    case "eq":
      return want === null ? () => false : (row) => same(read(row), want)
    case "ne":
      return want === null
        ? () => false
        : (row) => {
            const v = read(row)
            return v !== null && !same(v, want)
          }
    case "gt":
    case "gte":
    case "lt":
    case "lte": {
      if (want === null) return () => false
      return (row) => {
        const v = read(row)
        if (v === null) return false
        const c = compareValues(v, want)
        return op === "gt" ? c > 0 : op === "gte" ? c >= 0 : op === "lt" ? c < 0 : c <= 0
      }
    }
    case "between": {
      const [lo, hi] = list
      if (lo === undefined || hi === undefined) return () => false
      return (row) => {
        const v = read(row)
        return v !== null && compareValues(v, lo) >= 0 && compareValues(v, hi) <= 0
      }
    }
    case "in":
      return list.length === 0 ? () => false : (row) => list.some((item) => same(read(row), item))
    case "contains":
    case "startsWith": {
      if (want === null) return () => false
      const needle = String(want).toLowerCase()
      return (row) => {
        const v = read(row)
        if (v === null) return false
        const text = String(v).toLowerCase()
        return op === "contains" ? text.includes(needle) : text.startsWith(needle)
      }
    }
  }
}

function findColumn<T>(columns: readonly RuleColumn<T>[], key: string | undefined): RuleColumn<T> | undefined {
  return key === undefined ? undefined : columns.find((column) => column.key === key)
}


/**
 * Why a rule cannot apply, in a sentence, or null when it can: a column the grid does not have, a
 * value the column cannot read, a range without its two ends, a set with nothing in it, a missing or
 * unknown comparison or tone. `kind` says which list the rule is in; without it, a `when` or a `tone`
 * key makes the rule a highlight.
 */
export function ruleProblem<T>(rule: ReadColumnRule & ReadFilterRule, columns: readonly RuleColumn<T>[], kind?: RuleKind, words?: RuleWordsInput): string | null {
  const w = ruleWords(words)
  if (typeof rule !== "object" || rule === null) return w.needsColumn
  const named = textOf(rule.column)
  if (named === undefined) return w.needsColumn
  const column = findColumn(columns, named)
  if (!column) return fillWords(w.noColumn, { name: named })
  const highlight = kind ? kind === "highlight" : isHighlightShape(rule)
  // The condition as the grid reads it: one saved as anything but an object that is not a list is none.
  const read = readCondition(highlight ? rule.when : rule)
  const op = read?.op
  if (op === undefined || op === "") return w.needsComparison
  if (!isRuleOp(op)) return fillWords(w.noComparison, { op })
  // The op is one this module knows, from here on.
  const condition = read as RuleCondition
  const name = columnName(column)
  const unreadable = (raw: RuleValue | undefined) => raw !== undefined && raw !== null && raw !== "" && readRuleValue(column, raw) === null
  if (needsValue.has(condition.op)) {
    if (condition.value === undefined || condition.value === null || condition.value === "") return fillWords(w.needsValue, { op: w.ops[condition.op] })
    if (unreadable(condition.value)) return fillWords(w.unreadable, { value: shown(condition.value), column: name })
  }
  if (condition.op === "between") {
    const values = valuesOf(condition)
    if (values.length !== 2) return fillWords(w.rangeNeedsEnds, { op: w.ops.between })
    for (const raw of values) if (unreadable(raw) || raw === "" || raw === null) return fillWords(w.unreadable, { value: raw === null ? "" : shown(raw), column: name })
    if (compareValues(readRuleValue(column, values[0]), readRuleValue(column, values[1])) > 0) return fillWords(w.rangeOrder, { op: w.ops.between })
  }
  if (condition.op === "in") {
    const values = valuesOf(condition).filter((raw) => raw !== null && raw !== "")
    if (!values.length) return fillWords(w.setNeedsValue, { op: w.ops.in })
    for (const raw of values) if (unreadable(raw)) return fillWords(w.unreadable, { value: shown(raw), column: name })
  }
  // A highlight named as one always needs a tone; one only inferred from its keys is judged by the tone it carries.
  const tone = textOf(rule.tone)
  if (highlight && (kind || "tone" in rule) && !isRuleTone(tone)) return tone === undefined || tone === "" ? w.needsTone : fillWords(w.noTone, { tone })
  return null
}

/** The rule in words: "Price above 99-16+", "Client one of ALPHA, BETA", "Status is empty". `kind` reads as for `ruleProblem`. */
export function describeRule<T>(rule: ReadColumnRule & ReadFilterRule, columns: readonly RuleColumn<T>[], kind?: RuleKind, words?: RuleWordsInput): string {
  if (typeof rule !== "object" || rule === null) return ""
  const w = ruleWords(words)
  const column = findColumn(columns, textOf(rule.column))
  const highlight = kind ? kind === "highlight" : isHighlightShape(rule)
  const condition: Partial<ReadCondition> = readCondition(highlight ? rule.when : rule) ?? {}
  const name = columnName(column, rule.column)
  const word = isRuleOp(condition.op) ? w.ops[condition.op] : (condition.op ?? "")
  // A string threshold reads through the column's parse, so the words print what the rule
  // compares: a decimal typed into a fraction column describes, as it matches, on the grid.
  const text = (raw: RuleValue | undefined) => {
    if (raw === undefined || raw === null) return ""
    if (typeof raw === "string" && column?.parse && column.format) {
      // Normalized like the comparison: a parser's NaN matches nothing, so its words must not
      // print a formatted non-value. A parser's throw propagates here as it does everywhere.
      const parsed = normalizeValue(column.parse(raw))
      if (parsed !== null && parsed !== undefined) {
        try {
          const printed = column.format(parsed)
          if (typeof printed === "string" && printed !== "") return printed
        } catch {
          // A format that needs its row has no row here; the typed text stands.
        }
      }
    }
    return shown(raw)
  }
  if (condition.op === "isNull" || condition.op === "notNull") return `${name} ${word}`
  if (condition.op === "between") {
    const [lo, hi] = valuesOf(condition)
    return `${name} ${word} ${fillWords(w.range, { low: text(lo), high: text(hi) })}`
  }
  if (condition.op === "in") return `${name} ${word} ${valuesOf(condition).map(text).join(", ")}`
  return `${name} ${word} ${text(condition.value)}`.trim()
}

/**
 * Every rule has to hold. A rule that can't apply is skipped, so it hides nothing: one on a column the grid does not
 * have, and one `ruleProblem` names, with a comparison it doesn't know or a value its column can't read.
 */
export function compileFilter<T>(rules: readonly ReadFilterRule[], columns: readonly RuleColumn<T>[]): (row: T) => boolean {
  const tests: ((row: T) => boolean)[] = []
  for (const entry of listOf(rules)) {
    const rule = readFilterRule(entry)
    const column = rule ? findColumn(columns, rule.column) : undefined
    if (rule && column && ruleProblem(rule as ReadColumnRule & ReadFilterRule, columns, "filter") === null) tests.push(compileCondition(rule, column))
  }
  if (!tests.length) return () => true
  if (tests.length === 1) return tests[0]!
  return (row) => tests.every((test) => test(row))
}

/** The first rule that tells two rows apart decides, nulls last either way. Undefined when no rule names a column the grid has. */
export function compileComparator<T>(rules: readonly ReadSortRule[], columns: readonly RuleColumn<T>[]): ((a: T, b: T) => number) | undefined {
  const keys: { accessor: (row: T) => unknown; dir: "asc" | "desc" }[] = []
  for (const entry of listOf(rules)) {
    const rule = readSortRule(entry)
    const column = rule ? findColumn(columns, rule.key) : undefined
    if (rule && column) keys.push({ accessor: column.accessor, dir: rule.dir })
  }
  if (!keys.length) return undefined
  return (a, b) => {
    for (const { accessor, dir } of keys) {
      const c = compareDirected(accessor(a), accessor(b), dir)
      if (c !== 0) return c
    }
    return 0
  }
}

/** The decoration a matched rule puts on its cell or row. */
export function ruleDecoration<T>(saved: ReadColumnRule, columns: readonly RuleColumn<T>[]): RuleDecoration {
  const rule = readColumnRule(saved) ?? {}
  return {
    "data-rule": rule.id ?? "",
    "data-tone": rule.tone,
    "aria-description": (typeof rule.label === "string" ? rule.label.trim() : "") || describeRule(rule, columns, "highlight"),
    className: isRuleTone(rule.tone) ? RULE_TONE_CLASS[rule.tone] : "",
  }
}

export interface AppliedRules<T> {
  /** The first cell rule on this column that the row matches, or undefined. */
  cell: (columnKey: string, row: T) => RuleDecoration | undefined
  /** The first row rule the row matches, or undefined. Shaped for the grid's `getRowProps`. */
  getRowProps: (row: T) => RuleDecoration | undefined
  /** The rules that name a column the grid has, by column key, in the order they apply. */
  byColumn: ReadonlyMap<string, readonly ReadColumnRule[]>
}

/**
 * Column rules compiled once: each against its column, its decoration made ahead of time, and the
 * grid's two hooks, `cell` and `getRowProps`, answering per row with a matched rule's decoration. A
 * rule naming a column the grid does not have is skipped.
 */
export function applyRules<T>(rules: readonly ReadColumnRule[], columns: readonly RuleColumn<T>[]): AppliedRules<T> {
  const cells = new Map<string, { test: (row: T) => boolean; decoration: RuleDecoration }[]>()
  const rows: { test: (row: T) => boolean; decoration: RuleDecoration }[] = []
  const byColumn = new Map<string, ReadColumnRule[]>()
  for (const entry of listOf(rules)) {
    const rule = readColumnRule(entry)
    const column = rule ? findColumn(columns, rule.column) : undefined
    if (!rule || !column) continue
    const compiled = { test: compileCondition(rule.when, column), decoration: ruleDecoration(rule, columns) }
    byColumn.set(column.key, [...(byColumn.get(column.key) ?? []), rule])
    if (rule.target === "row") rows.push(compiled)
    else cells.set(column.key, [...(cells.get(column.key) ?? []), compiled])
  }
  return {
    cell(columnKey, row) {
      const list = cells.get(columnKey)
      if (!list) return undefined
      for (const { test, decoration } of list) if (test(row)) return decoration
      return undefined
    },
    getRowProps(row) {
      for (const { test, decoration } of rows) if (test(row)) return decoration
      return undefined
    },
    byColumn,
  }
}

// Number formatting for trading screens. Pure functions, no React, no dependencies.
// Every formatter returns NULL_TOKEN for null, undefined, NaN, and infinities, so a grid
// never prints "NaN" or "undefined" while a feed is warming up.

export const NULL_TOKEN = "–"
const MINUS = "−"

export type Nullable = number | null | undefined

export interface Locale {
  /** BCP 47 tag; defaults to en-US. */
  locale?: string
}

export type PriceConvention =
  /** Fixed decimals, e.g. equities at 2. */
  | { kind: "decimal"; decimals: number }
  /** Decimals derived from the instrument's tick size, e.g. 0.001 gives 3. */
  | { kind: "tick"; tick: number }
  /**
   * Fractional quoting. `denominator` 32 or 64; `half` renders a half tick as "+" (99-16+) or "5" (99-165);
   * `eighths` renders eighths of a tick as a trailing digit (99-162 is 99 and 16 2/8 thirty-seconds).
   */
  | { kind: "fraction"; denominator: 32 | 64; half: "+" | "5"; eighths?: boolean }

/** What a quote is typed and read in. Bills quote on discount, most bonds on price, some on yield, credit often on a spread in basis points. */
export type QuoteBasis = "price" | "yield" | "discount" | "spread"

export interface InstrumentConvention {
  price: PriceConvention
  /** Smallest price increment, used for stepping and rounding. */
  tick: number
  yieldDecimals?: number
  quantityUnit?: "notional" | "contracts"
  /** Default price. */
  quoteBasis?: QuoteBasis
  /** What a quote steps by in its basis. Default: the tick for price, 0.001 for yield and discount, 0.1 for spread. */
  quoteStep?: number
  /** Decimals for a yield, discount, or spread quote. Default 3, 3, and 1. Price quotes follow their convention. */
  quoteDecimals?: number
  /** Whether a higher quote means a lower price, so a normal market quotes the bid above the offer. Defaults by basis: yield and discount invert; price and spread do not, since a CDS spread quotes bid below offer while cash credit quotes the other way — declare it for the instrument when the default reads wrong. */
  quoteInverted?: boolean
}

function isNil(v: Nullable): v is null | undefined {
  return v === null || v === undefined || !Number.isFinite(v)
}

// One Intl.NumberFormat per locale and option set; construction is the expensive part.
const formatters = new Map<string, Intl.NumberFormat>()

/** True for a time a `Date` can hold: a finite number of milliseconds within 8.64e15 of the epoch either way. */
export const isInstant = (ms: unknown): ms is number => Number.isFinite(ms) && Math.abs(ms as number) <= 8.64e15

export function numberFormat(locale: string | undefined, options: Intl.NumberFormatOptions): Intl.NumberFormat {
  const key = `${locale ?? "en-US"}|${JSON.stringify(options)}`
  let nf = formatters.get(key)
  if (!nf) {
    nf = new Intl.NumberFormat(locale ?? "en-US", options)
    formatters.set(key, nf)
  }
  return nf
}

function fixed(v: number, decimals: number, locale?: string, extra: Intl.NumberFormatOptions = {}): string {
  return numberFormat(locale, { minimumFractionDigits: decimals, maximumFractionDigits: decimals, ...extra }).format(v)
}

function typographicMinus(s: string): string {
  return s.replace(/-/g, MINUS)
}

/** Decimal places needed to show a price on this tick grid. 0.001 gives 3, 1/32 gives 5, 1 gives 0. Capped at `max`. */
export function decimalsFromTick(tick: number, max = 8): number {
  if (!Number.isFinite(tick) || tick <= 0) return 0
  for (let d = 0; d <= max; d++) {
    const scaled = tick * 10 ** d
    if (Math.abs(scaled - Math.round(scaled)) < 1e-9 * Math.max(1, scaled)) return d
  }
  return max
}

/** Nearest price on the tick grid, cleaned of float noise. */
export function roundToTick(v: number, tick: number): number {
  if (!Number.isFinite(v) || !Number.isFinite(tick) || tick <= 0) return v
  return Number((Math.round(v / tick) * tick).toFixed(decimalsFromTick(tick)))
}

/** Move `steps` ticks (negative allowed) from the nearest grid price. */
export function stepByTick(v: number, tick: number, steps: number): number {
  return roundToTick(roundToTick(v, tick) + steps * tick, tick)
}

/** Whole-number and sub-tick decomposition on an integer grid so 32nds never drift. */
function decomposeFraction(v: number, c: Extract<PriceConvention, { kind: "fraction" }>) {
  const sub = c.eighths ? 8 : 2
  const unitsPerWhole = c.denominator * sub
  const total = Math.round(Math.abs(v) * unitsPerWhole)
  const whole = Math.floor(total / unitsPerWhole)
  const rem = total - whole * unitsPerWhole
  const ticks = Math.floor(rem / sub)
  const subticks = rem - ticks * sub
  return { negative: v < 0 && total > 0, whole, ticks, subticks, sub }
}

/** 99.515625 as "99-16+" (32nds, half "+"), "99-165" (half "5"), or "99-164" with eighths. */
export function formatFraction(v: Nullable, c: Extract<PriceConvention, { kind: "fraction" }>): string {
  if (isNil(v)) return NULL_TOKEN
  const { negative, whole, ticks, subticks, sub } = decomposeFraction(v, c)
  // From 1e21 a whole part prints in exponent form, and further up the scaling overflows: neither is the notation,
  // and parsePrice refuses the same range.
  if (!(whole < 1e21)) return NULL_TOKEN
  let tail = ""
  if (subticks !== 0) {
    if (c.eighths) tail = String(subticks)
    else tail = c.half
  }
  void sub
  return `${negative ? MINUS : ""}${whole}-${String(ticks).padStart(2, "0")}${tail}`
}

export function formatPrice(v: Nullable, c: PriceConvention, l?: Locale): string {
  if (isNil(v)) return NULL_TOKEN
  switch (c.kind) {
    case "decimal":
      return typographicMinus(fixed(v, c.decimals, l?.locale))
    case "tick":
      return typographicMinus(fixed(roundToTick(v, c.tick), decimalsFromTick(c.tick), l?.locale))
    case "fraction":
      return formatFraction(v, c)
  }
}

/**
 * Numeric text, trimmed and with either minus sign read as "-", with its thousands separators removed, or null when a
 * comma in it isn't one. A comma groups
 * thousands in the whole part only: a first group of one to three digits with no leading zero, then groups of three,
 * and none after the point or among the 32nds, so "99,5" from a decimal-comma keyboard is no number, never 995. With
 * `decimals`, for text whose notation prints digits after the point, one comma with nothing after the whole part is
 * no number either, since "4,253" reads as 4253 grouped or as 4.253 typed with a decimal comma; two or more groups,
 * or a point or a fraction's dash after them, can only be grouping. Text without a comma comes back trimmed with the minus
 * read, and the rest of any text is left to the caller's own pattern, which decides what is a number.
 */
export function stripGrouping(input: string, options: { decimals: boolean }): string | null {
  const text = input.trim().replace(/−/g, "-")
  if (!text.includes(",")) return text
  const m = /^([+-]?)([1-9]\d{0,2}(?:,\d{3})+)((?:[.-].*)?)$/.exec(text)
  if (!m || m[3]!.includes(",")) return null
  const whole = m[2]!
  if (options.decimals && !m[3] && whole.indexOf(",") === whole.lastIndexOf(",")) return null
  return m[1]! + whole.replace(/,/g, "") + m[3]!
}

// Whether a convention's own text carries digits after the point, or a fraction's ticks.
const printsDecimals = (c: PriceConvention) => (c.kind === "fraction" ? true : c.kind === "decimal" ? c.decimals > 0 : decimalsFromTick(c.tick) > 0)

/**
 * Inverse of formatPrice for ticket entry. Accepts the convention's own notation and a plain decimal.
 * Returns null when the text is not a price. Fraction input: "99-16+", "99-165", "99-162", "99-16", "99".
 */
export function parsePrice(s: string, c: PriceConvention): number | null {
  const text = stripGrouping(s, { decimals: printsDecimals(c) })
  if (!text) return null
  if (c.kind === "fraction") {
    const m = /^([+-]?)(\d+)(?:-(\d{1,2})([+0-9])?)?$/.exec(text)
    if (m) {
      const [, sign, wholeText, ticksText, tail] = m
      const ticks = ticksText ? Number(ticksText) : 0
      if (ticks >= c.denominator) return null
      let subFraction = 0
      if (tail === "+") subFraction = 0.5
      else if (tail !== undefined) {
        const digit = Number(tail)
        if (c.eighths) {
          if (digit > 7) return null
          subFraction = digit / 8
        } else if (c.half === "5" && digit === 5) subFraction = 0.5
        else if (digit === 0) subFraction = 0
        else return null
      }
      const value = Number(wholeText) + (ticks + subFraction) / c.denominator
      // What cannot print back in the notation is refused: unit scaling must stay finite, the
      // whole part must stay out of exponent form (1e21 up), and "-0" stays plain zero.
      if (value >= 1e21 || !Number.isFinite(value * c.denominator * (c.eighths ? 8 : 2))) return null
      return value === 0 ? 0 : sign === "-" ? -value : value
    }
  }
  if (!/^[+-]?(\d+\.?\d*|\.\d+)$/.test(text)) return null
  const n = Number(text)
  if (!Number.isFinite(n)) return null
  // Every convention keeps the promise the reference row makes: what parses can print back.
  // Intl prints tick and decimal prices in full digits at any finite size, so only fraction
  // notation carries the 1e21 bound; tick scaling must stay finite, and zero stays plain zero.
  if (c.kind === "tick") {
    const rounded = roundToTick(n, c.tick)
    return Number.isFinite(rounded) ? (rounded === 0 ? 0 : rounded) : null
  }
  if (c.kind === "decimal") {
    const fixed = Number(n.toFixed(c.decimals))
    return fixed === 0 ? 0 : fixed
  }
  // A decimal typed into a fraction convention snaps to the printable grid, so the value a field
  // reports is the price its formatted text shows. The magnitude rounds, as the formatter rounds,
  // so a negative tie snaps away from zero the way it prints.
  const unitsPerWhole = c.denominator * (c.eighths ? 8 : 2)
  const units = Math.round(Math.abs(n) * unitsPerWhole)
  // Scaling can overflow a finite input, a magnitude from 1e21 up prints in exponent form the
  // notation cannot parse back, and a sub-half-unit negative would make negative zero.
  if (!Number.isFinite(units) || units / unitsPerWhole >= 1e21) return null
  return units === 0 ? 0 : (n < 0 ? -units : units) / unitsPerWhole
}

/** 4.2531 as "4.253%". */
export function formatYield(v: Nullable, o: { decimals?: number; suffix?: "%" | "" } & Locale = {}): string {
  if (isNil(v)) return NULL_TOKEN
  return typographicMinus(fixed(v, o.decimals ?? 3, o.locale)) + (o.suffix ?? "%")
}

/** 12.5 as "12.5 bp"; signed gives "+12.5 bp". */
export function formatBps(v: Nullable, o: { decimals?: number; signed?: boolean; unit?: "bp" | "bps" | "" } & Locale = {}): string {
  if (isNil(v)) return NULL_TOKEN
  const unit = o.unit ?? "bp"
  const body = o.signed ? formatSigned(v, { decimals: o.decimals ?? 1, locale: o.locale }) : typographicMinus(fixed(v, o.decimals ?? 1, o.locale))
  return unit ? `${body} ${unit}` : body
}

/** Dollar value of a basis point as whole currency; compact gives "$1.23K". */
export function formatDv01(v: Nullable, o: { currency?: string; compact?: boolean } & Locale = {}): string {
  if (isNil(v)) return NULL_TOKEN
  const currency = o.currency ?? "USD"
  if (o.compact) {
    const symbol = numberFormat(o.locale, { style: "currency", currency, currencyDisplay: "narrowSymbol", maximumFractionDigits: 0 })
      .formatToParts(0)
      .find((p) => p.type === "currency")?.value ?? ""
    return `${v < 0 ? MINUS : ""}${symbol}${formatNotional(Math.abs(v), { compact: true, locale: o.locale })}`
  }
  return typographicMinus(numberFormat(o.locale, { style: "currency", currency, currencyDisplay: "narrowSymbol", maximumFractionDigits: 0 }).format(v))
}

/** 1250000 as "1.25M" (compact), "1.25mm" (unit "mm", the desk's word for millions, never scaled further), or "1,250,000.00". Compact suffixes K, M, B, T. */
export function formatNotional(v: Nullable, o: { compact?: boolean; decimals?: number; unit?: "mm" } & Locale = {}): string {
  if (isNil(v)) return NULL_TOKEN
  const decimals = o.decimals ?? 2
  if (o.unit === "mm") return typographicMinus(numberFormat(o.locale, { minimumFractionDigits: 0, maximumFractionDigits: decimals }).format(v / 1e6)) + "mm"
  if (!o.compact) return typographicMinus(fixed(v, decimals, o.locale))
  const abs = Math.abs(v)
  const [divisor, suffix] = abs >= 1e12 ? [1e12, "T"] : abs >= 1e9 ? [1e9, "B"] : abs >= 1e6 ? [1e6, "M"] : abs >= 1e3 ? [1e3, "K"] : [1, ""]
  return typographicMinus(fixed(v / divisor, suffix ? decimals : 0, o.locale)) + suffix
}

/** "+0.12", "−0.12" (U+2212), and "0.00" for zero: flat carries no sign. */
export function formatSigned(v: Nullable, o: { decimals?: number } & Locale = {}): string {
  if (isNil(v)) return NULL_TOKEN
  return typographicMinus(fixed(v, o.decimals ?? 2, o.locale, { signDisplay: "exceptZero" }))
}

/** 1.234 as "1.23%"; signed gives "+1.23%". */
export function formatPercent(v: Nullable, o: { decimals?: number; signed?: boolean } & Locale = {}): string {
  if (isNil(v)) return NULL_TOKEN
  const decimals = o.decimals ?? 2
  return (o.signed ? formatSigned(v, { decimals, locale: o.locale }) : typographicMinus(fixed(v, decimals, o.locale))) + "%"
}

/** Whole quantities with grouping: 1000000 as "1,000,000". */
export function formatQuantity(v: Nullable, l?: Locale): string {
  if (isNil(v)) return NULL_TOKEN
  return typographicMinus(fixed(Math.round(v), 0, l?.locale))
}

/**
 * A coupon the way a run prints it: 4.125 as "4 1/8", 4.5 as "4 1/2", 4 as "4", 0 as "0" (coupons step in eighths).
 * One off the eighths grid prints as a plain decimal, "4.1". `style: "decimal"` prints "4.125%".
 */
export function formatCoupon(v: Nullable, o: { style?: "fraction" | "decimal"; decimals?: number } & Locale = {}): string {
  if (isNil(v)) return NULL_TOKEN
  if (o.style === "decimal") return typographicMinus(fixed(v, o.decimals ?? 3, o.locale)) + "%"
  const eighths = Math.round(Math.abs(v) * 8)
  if (Math.abs(eighths / 8 - Math.abs(v)) > 1e-9) return typographicMinus(numberFormat(o.locale, { minimumFractionDigits: 0, maximumFractionDigits: o.decimals ?? 3 }).format(v))
  const whole = Math.floor(eighths / 8)
  const rem = eighths % 8
  const fraction = rem === 0 ? "" : rem % 4 === 0 ? "1/2" : rem % 2 === 0 ? `${rem / 2}/4` : `${rem}/8`
  const body = fraction ? (whole ? `${whole} ${fraction}` : fraction) : String(whole)
  return `${v < 0 && eighths > 0 ? MINUS : ""}${body}`
}

/** A date as an instant, a millisecond count, or a string `Date` can read. A date-only string ("2034-05-15") is that day in UTC. */
export type DateLike = Date | number | string

function toDate(d: DateLike | null | undefined): Date | null {
  if (d === null || d === undefined) return null
  const date = d instanceof Date ? d : new Date(d)
  return Number.isNaN(date.getTime()) ? null : date
}

const dateFormatters = new Map<string, Intl.DateTimeFormat>()

/**
 * A maturity as a run prints it: "05/15/34", or "05/15/2034" with `year: "numeric"`. Read in UTC, so a
 * date-only string prints as that day wherever the screen is.
 */
export function formatMaturity(d: DateLike | null | undefined, o: { year?: "2-digit" | "numeric" } & Locale = {}): string {
  const date = toDate(d)
  if (!date) return NULL_TOKEN
  const key = `${o.locale ?? "en-US"}|${o.year ?? "2-digit"}`
  let f = dateFormatters.get(key)
  if (!f) {
    f = new Intl.DateTimeFormat(o.locale ?? "en-US", { month: "2-digit", day: "2-digit", year: o.year ?? "2-digit", timeZone: "UTC" })
    dateFormatters.set(key, f)
  }
  return f.format(date)
}

/** Whole UTC days from `now` (the moment, by default) to a maturity. Negative once it has passed; null when the date does not read. */
export function daysToMaturity(d: DateLike | null | undefined, now: DateLike = Date.now()): number | null {
  const maturity = toDate(d)
  const from = toDate(now)
  if (!maturity || !from) return null
  const day = (x: Date) => Date.UTC(x.getUTCFullYear(), x.getUTCMonth(), x.getUTCDate())
  return Math.round((day(maturity) - day(from)) / 86_400_000)
}

/** How many ticks `a` is from `b`, signed, to the nearest eighth of a tick: 99-17 against 99-16+ on a 1/64 tick is 1. NaN when a side is not a number or the tick is not positive. */
export function ticksBetween(a: number, b: number, tick: number): number {
  if (!Number.isFinite(a) || !Number.isFinite(b) || !(tick > 0)) return NaN
  return Math.round(((a - b) / tick) * 8) / 8
}

/** A count of ticks: "+1", "−0.5", "0", up to three decimals and no trailing zeros. Signed unless told otherwise; `unit` adds a word; `grouping: false` drops the thousands separators, for an editor's text. */
export function formatTicks(v: Nullable, o: { signed?: boolean; unit?: string; grouping?: boolean } & Locale = {}): string {
  if (isNil(v)) return NULL_TOKEN
  const body = typographicMinus(numberFormat(o.locale, { minimumFractionDigits: 0, maximumFractionDigits: 3, signDisplay: o.signed === false ? "auto" : "exceptZero", ...(o.grouping === false ? { useGrouping: false } : {}) }).format(v))
  return o.unit ? `${body} ${o.unit}` : body
}

/**
 * The class a number wears (contract rule 14): lining, tabular figures whatever the font, in the numeric family.
 * `--tradecn-font-numeric` is the sans by default, so letters stay proportional and only the digits take one
 * width, which is what a column of prices wants. docs/typography.md has the reasoning and the tokens.
 */
export const NUMERIC_CLASS = "font-(family-name:--tradecn-font-numeric) lining-nums tabular-nums"
/** The same figures in the mono stack, `--tradecn-font-mono`: for a fraction quote, so digits and the dash take one width; tails still lengthen a quote. */
export const MONO_NUMERIC_CLASS = "font-(family-name:--tradecn-font-mono) lining-nums tabular-nums"

/**
 * The class for a number printed under a convention: a fraction price (99-16+) sets in the mono stack, so
 * digits and the dash take one width down a column; a tailed quote still runs longer than an untailed one.
 * Every other price, and every quote in another basis, keeps the numeric family.
 */
export function numericFontClass(c?: PriceConvention | InstrumentConvention | null): string {
  const price = c && "price" in c ? (quoteBasisOf(c) === "price" ? c.price : null) : c
  return price?.kind === "fraction" ? MONO_NUMERIC_CLASS : NUMERIC_CLASS
}

/** The word for a quote field's label, per basis. */
export const QUOTE_BASIS_LABELS: Record<QuoteBasis, string> = { price: "Price", yield: "Yield", discount: "Discount", spread: "Spread" }

const QUOTE_DEFAULTS: Record<Exclude<QuoteBasis, "price">, { step: number; decimals: number }> = {
  yield: { step: 0.001, decimals: 3 },
  discount: { step: 0.001, decimals: 3 },
  spread: { step: 0.1, decimals: 1 },
}

export function quoteBasisOf(c: InstrumentConvention): QuoteBasis {
  return c.quoteBasis ?? "price"
}

/** Whether a higher quote means a lower price for this instrument: declared, else by basis — yield and discount invert, price and spread do not. */
export function quoteInvertedOf(c: InstrumentConvention): boolean {
  if (c.quoteInverted !== undefined) return c.quoteInverted
  const basis = quoteBasisOf(c)
  return basis === "yield" || basis === "discount"
}

/** What a quote steps by in its basis: the tick for a price, else `quoteStep` or the basis default. */
export function quoteStepOf(c: InstrumentConvention): number {
  const basis = quoteBasisOf(c)
  return basis === "price" ? c.tick : (c.quoteStep ?? QUOTE_DEFAULTS[basis].step)
}

function quoteDecimalsOf(c: InstrumentConvention): number {
  const basis = quoteBasisOf(c)
  return basis === "price" ? 0 : (c.quoteDecimals ?? QUOTE_DEFAULTS[basis].decimals)
}

/** A quote in the instrument's basis: a price by its convention, else a fixed decimal with the basis's decimals and no unit, since the field's label says the basis. */
export function formatQuote(v: Nullable, c: InstrumentConvention, l?: Locale): string {
  if (isNil(v)) return NULL_TOKEN
  if (quoteBasisOf(c) === "price") return formatPrice(v, c.price, l)
  return typographicMinus(fixed(roundToTick(v, quoteStepOf(c)), quoteDecimalsOf(c), l?.locale))
}

/** Inverse of formatQuote for a quote field. A price takes its notation or a decimal; the others take a decimal and snap to the quote step. Null when the text is not a quote. */
export function parseQuote(s: string, c: InstrumentConvention): number | null {
  if (quoteBasisOf(c) === "price") return parsePrice(s, c.price)
  const text = stripGrouping(s, { decimals: quoteDecimalsOf(c) > 0 })
  if (text === null || !/^[+-]?(\d+\.?\d*|\.\d+)$/.test(text)) return null
  const n = Number(text)
  if (!Number.isFinite(n)) return null
  // Snapping divides by the step, which can overflow where the raw number does not; what
  // cannot print back is not a quote.
  const snapped = roundToTick(n, quoteStepOf(c))
  return Number.isFinite(snapped) ? snapped : null
}

/** Move a quote by `steps` of its step, from the nearest grid value. */
export function stepQuote(v: number, c: InstrumentConvention, steps: number): number {
  return stepByTick(v, quoteStepOf(c), steps)
}

/** Bind a convention once per instrument; a grid column calls `formatters[row.instrumentId].price(v)`, a quote field its `quote`, `parseQuote`, and `stepQuote`. */
export function createInstrumentFormatter(c: InstrumentConvention, l?: Locale) {
  return {
    tick: c.tick,
    basis: quoteBasisOf(c),
    quoteStep: quoteStepOf(c),
    price: (v: Nullable) => formatPrice(v, c.price, l),
    yield: (v: Nullable) => formatYield(v, { decimals: c.yieldDecimals ?? 3, locale: l?.locale }),
    step: (v: number, steps: number) => stepByTick(v, c.tick, steps),
    parsePrice: (s: string) => parsePrice(s, c.price),
    quantity: (v: Nullable) => formatQuantity(v, l),
    quote: (v: Nullable) => formatQuote(v, c, l),
    parseQuote: (s: string) => parseQuote(s, c),
    stepQuote: (v: number, steps: number) => stepQuote(v, c, steps),
  }
}

:root {
  --down-soft: oklch(0.46 0.19 40 / 18%);
  --expiring-soft: oklch(0.53 0.2 350 / 18%);
  --flat-soft: oklch(0.55 0 0 / 14%);
  --stale-soft: oklch(0.52 0.13 75 / 16%);
  --tradecn-font-accessible: 'Atkinson Hyperlegible Next', 'Atkinson Hyperlegible', ui-sans-serif, system-ui, sans-serif;
  --tradecn-font-accessible-mono: 'Atkinson Hyperlegible Mono', ui-monospace, SFMono-Regular, Menlo, Consolas, monospace;
  --tradecn-font-mono: 'JetBrains Mono', ui-monospace, SFMono-Regular, Menlo, Consolas, monospace;
  --tradecn-font-numeric: var(--tradecn-font-sans);
  --tradecn-font-sans: 'Inter', ui-sans-serif, system-ui, sans-serif;
  --up-soft: oklch(0.52 0.13 165 / 18%);
}

.dark {
  --down-soft: oklch(0.66 0.19 40 / 18%);
  --expiring-soft: oklch(0.74 0.17 350 / 18%);
  --flat-soft: oklch(0.7 0 0 / 14%);
  --stale-soft: oklch(0.8 0.15 80 / 16%);
  --tradecn-font-accessible: 'Atkinson Hyperlegible Next', 'Atkinson Hyperlegible', ui-sans-serif, system-ui, sans-serif;
  --tradecn-font-accessible-mono: 'Atkinson Hyperlegible Mono', ui-monospace, SFMono-Regular, Menlo, Consolas, monospace;
  --tradecn-font-mono: 'JetBrains Mono', ui-monospace, SFMono-Regular, Menlo, Consolas, monospace;
  --tradecn-font-numeric: var(--tradecn-font-sans);
  --tradecn-font-sans: 'Inter', ui-sans-serif, system-ui, sans-serif;
  --up-soft: oklch(0.74 0.15 165 / 18%);
}

:root[data-accessibility="hyperlegible"], [data-accessibility="hyperlegible"] {
  --tradecn-font-sans: var(--tradecn-font-accessible);
  --tradecn-font-mono: var(--tradecn-font-accessible-mono);
}