@lovett/ui 0.0.10 → 0.1.0

package/src/lib/remark-underline.ts

@@ -0,0 +1,443 @@
+/**
+ * remark-underline — `++text++` renders as `<u>` (ADR-148 D13).
+ *
+ * Markdown has no underline. The rich composer serialises TipTap's
+ * `underline` mark as `++text++` — a dialect several Markdown flavours use
+ * for insert/underline, and one CommonMark cannot misread because `+` has no
+ * inline meaning. This is the RENDERER half: a micromark text construct that
+ * tokenizes `++` runs, a resolver that pairs openers with closers, and an
+ * mdast handler that emits an `underline` node carrying `data.hName = 'u'`,
+ * which `remark-rehype` turns into a `<u>` element for the component map in
+ * `markdown.tsx` to style.
+ *
+ * ZERO DEPENDENCIES, ON PURPOSE. `remark-gfm` already pulls every utility this
+ * would want into the lockfile (`micromark-util-classify-character`,
+ * `micromark-util-resolve-all`, `micromark-util-chunked`,
+ * `mdast-util-from-markdown`, `micromark-util-types`) — but pnpm's strict
+ * layout keeps transitives out of `packages/ui/node_modules`, so none of them
+ * is importable here without becoming a direct dependency, which D13 forbids.
+ * The three helpers are re-derived below (each is under fifteen lines in the
+ * original) and the types are local structural mirrors of
+ * `micromark-util-types` / `mdast-util-from-markdown`. The runtime contract is
+ * plain objects and functions that micromark calls by shape, so a mirror is
+ * exactly as safe as the import would be. The construct is modelled line for
+ * line on `micromark-extension-gfm-strikethrough` (`~~` → `<del>`), its
+ * closest cousin.
+ *
+ * THE RULES — agreed with the composer's serializer (ADR-148 D13):
+ *
+ *   • A `++` run may OPEN / CLOSE by exactly GFM strikethrough's flanking
+ *     rule (`micromark-extension-gfm-strikethrough`, which is CommonMark's
+ *     `*` rule without the underscore exception): classify the character on
+ *     each side as whitespace, punctuation, or other, then
+ *
+ *         open  = after is not whitespace and (after is not punctuation or before is whitespace/punctuation)
+ *         close = before is not whitespace and (before is not punctuation or after is whitespace/punctuation)
+ *
+ *     So `++text++` behaves the way `~~text~~` and `**text**` already do:
+ *     `i++; j++;` and `C++` stay literal (a run before punctuation after a
+ *     letter cannot open), `word++x++word` DOES underline (intraword, like
+ *     `~~`), `see ++(note)++ here` underlines but `a++(note)++b` does not.
+ *     Whitespace = end of input, line endings, tabs, spaces, Unicode
+ *     whitespace; punctuation = Unicode P and S. micromark hands over UTF-16
+ *     code units, so an astral character (an emoji) arrives as two surrogates
+ *     and classifies as "other", exactly as it does for `~~`.
+ *   • Exactly two markers. A lone `+`, a `+++` run, an unclosed `++text`, a
+ *     closer with no opener, spaces just inside the markers — all stay
+ *     literal text. Nothing is dropped and nothing throws (D3 rule 3).
+ *   • Code spans and fences are untouched: micromark never runs text
+ *     constructs inside them, so `` `++x++` `` shows the plus signs.
+ *   • `\++` is an ordinary character escape and stays literal.
+ *   • Registered as an `insideSpan` resolver AND an attention marker — the
+ *     same two hooks strikethrough uses — so `**++x++**`, `++**x**++`,
+ *     `~~++x++~~` and the intraword `a**++x++**b` all nest correctly.
+ *   • Two pairs CAN nest structurally (`++a ++b++ c++` → `<u>a <u>b</u> c</u>`),
+ *     exactly as `~~` does. The composer never emits that (a mark cannot
+ *     nest in ProseMirror) and it renders as one underline, so it is pinned
+ *     rather than prevented.
+ */
+
+// ---------------------------------------------------------------------------
+// Local structural types — mirrors of `micromark-util-types` (see header).
+// Only the members this construct touches are declared.
+// ---------------------------------------------------------------------------
+
+/**
+ * A character code. `null` is end of input; negative values are micromark's
+ * virtual characters (line endings, tab expansion); everything else is a
+ * Unicode code point.
+ */
+type Code = number | null
+
+interface Point {
+  line: number
+  column: number
+  offset: number
+  _index: number
+  _bufferIndex: number
+}
+
+interface Token {
+  type: string
+  start: Point
+  end: Point
+  _open?: boolean
+  _close?: boolean
+}
+
+interface Resolvable {
+  readonly resolveAll?: Resolver | undefined
+}
+
+interface TokenizeContext {
+  readonly previous: Code
+  readonly events: Event[]
+  readonly parser: {
+    readonly constructs: {
+      readonly insideSpan: { readonly null?: readonly Resolvable[] | undefined }
+    }
+  }
+}
+
+type Event = ['enter' | 'exit', Token, TokenizeContext]
+type State = (code: Code) => State | undefined
+type Resolver = (events: Event[], context: TokenizeContext) => Event[]
+type Tokenizer = (this: TokenizeContext, effects: Effects, ok: State, nok: State) => State
+
+interface Effects {
+  enter(type: string): Token
+  exit(type: string): Token
+  consume(code: Code): undefined
+}
+
+interface Construct extends Resolvable {
+  readonly name: string
+  readonly tokenize: Tokenizer
+  readonly resolveAll: Resolver
+}
+
+/** The three hooks a micromark syntax extension may register for an inline construct. */
+interface MicromarkExtension {
+  readonly text: Readonly<Record<number, Construct>>
+  readonly insideSpan: { readonly null: readonly Construct[] }
+  readonly attentionMarkers: { readonly null: readonly Code[] }
+}
+
+// Mirrors of `mdast-util-from-markdown` — the compile side.
+
+/**
+ * The mdast node. `data.hName` is the documented `mdast-util-to-hast` hook:
+ * an unknown node type with an `hName` becomes an element of that name, so
+ * no rehype plugin of any kind is involved and the raw-HTML ban is untouched.
+ */
+interface UnderlineNode {
+  type: 'underline'
+  children: unknown[]
+  data: { hName: 'u' }
+}
+
+interface CompileContext {
+  enter(node: UnderlineNode, token: Token): undefined
+  exit(token: Token): undefined
+}
+
+type Handle = (this: CompileContext, token: Token) => undefined
+
+interface FromMarkdownExtension {
+  readonly canContainEols: readonly string[]
+  readonly enter: Readonly<Record<string, Handle>>
+  readonly exit: Readonly<Record<string, Handle>>
+}
+
+// The slice of a unified processor the plugin touches. `settings` is listed
+// so the type is not "weak" (all-optional) and unified's `Data` — which has
+// `settings` — is assignable to it whether or not remark-parse's augmentation
+// (`micromarkExtensions` / `fromMarkdownExtensions`) is loaded in a consumer.
+interface RemarkData {
+  settings?: unknown
+  micromarkExtensions?: unknown[]
+  fromMarkdownExtensions?: unknown[]
+}
+
+interface RemarkProcessorLike {
+  data(): RemarkData
+}
+
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+
+/** U+002B PLUS SIGN. */
+const PLUS = 43
+/** U+0020 SPACE. */
+const SPACE = 32
+
+const SEQUENCE_TEMPORARY = 'underlineSequenceTemporary'
+const SEQUENCE = 'underlineSequence'
+const UNDERLINE = 'underline'
+const UNDERLINE_TEXT = 'underlineText'
+/** micromark's own token types this construct reads. */
+const CHARACTER_ESCAPE = 'characterEscape'
+const DATA = 'data'
+
+/** `Array#splice` spreads its items as arguments; past this many V8 overflows the stack. */
+const SPLICE_CHUNK = 10_000
+
+/** `micromark-util-character`'s `unicodeWhitespace` / `unicodePunctuation`. */
+const UNICODE_WHITESPACE = /\s/
+const UNICODE_PUNCTUATION = /\p{P}|\p{S}/u
+
+/** `micromark-util-symbol`'s character groups. */
+const GROUP_WHITESPACE = 1
+const GROUP_PUNCTUATION = 2
+type CharacterGroup = typeof GROUP_WHITESPACE | typeof GROUP_PUNCTUATION | undefined
+
+// ---------------------------------------------------------------------------
+// Re-derived helpers (see header for why these are not imports)
+// ---------------------------------------------------------------------------
+
+/**
+ * `micromark-util-classify-character`: whitespace (end of input, any virtual
+ * character — all line endings and tab parts are negative codes — the space,
+ * Unicode whitespace), punctuation (Unicode P and S), or other. Codes are
+ * UTF-16 units and are stringified with `fromCharCode` exactly as micromark's
+ * `regexCheck` does, so surrogate halves classify as "other" here too.
+ */
+function classifyCharacter(code: Code): CharacterGroup {
+  if (code === null || code < 0 || code === SPACE) return GROUP_WHITESPACE
+  const character = String.fromCharCode(code)
+  if (UNICODE_WHITESPACE.test(character)) return GROUP_WHITESPACE
+  if (UNICODE_PUNCTUATION.test(character)) return GROUP_PUNCTUATION
+  return undefined
+}
+
+/** `micromark-util-chunked`'s `splice`: `Array#splice` that survives huge item lists. */
+function spliceChunked<T>(list: T[], start: number, remove: number, items: readonly T[]): void {
+  const end = list.length
+  let at = start < 0 ? (-start > end ? 0 : end + start) : start > end ? end : start
+  const count = remove > 0 ? remove : 0
+
+  if (items.length < SPLICE_CHUNK) {
+    list.splice(at, count, ...items)
+    return
+  }
+
+  if (count > 0) list.splice(at, count)
+  let from = 0
+  while (from < items.length) {
+    list.splice(at, 0, ...items.slice(from, from + SPLICE_CHUNK))
+    from += SPLICE_CHUNK
+    at += SPLICE_CHUNK
+  }
+}
+
+/** `micromark-util-resolve-all`: run each distinct `resolveAll` once, in order. */
+function resolveAll(
+  constructs: readonly Resolvable[],
+  events: Event[],
+  context: TokenizeContext,
+): Event[] {
+  const called: Resolver[] = []
+  let result = events
+  for (const construct of constructs) {
+    const resolve = construct.resolveAll
+    if (resolve !== undefined && !called.includes(resolve)) {
+      result = resolve(result, context)
+      called.push(resolve)
+    }
+  }
+  return result
+}
+
+// ---------------------------------------------------------------------------
+// The micromark construct
+// ---------------------------------------------------------------------------
+
+/**
+ * Tokenize one `++` run. Runs whenever the text tokenizer meets a `+`.
+ * Emits a temporary sequence token flagged with whether it may open and/or
+ * close; the resolver pairs them afterwards.
+ */
+function tokenizeUnderline(
+  this: TokenizeContext,
+  effects: Effects,
+  ok: State,
+  nok: State,
+): State {
+  const previous = this.previous
+  const events = this.events
+  let size = 0
+
+  return start
+
+  function start(code: Code): State | undefined {
+    // A `+` directly after another `+` that was not an escape means we are
+    // inside a run an earlier attempt already rejected (`+++`): stay literal.
+    if (previous === PLUS && events[events.length - 1]?.[1].type !== CHARACTER_ESCAPE) {
+      return nok(code)
+    }
+    effects.enter(SEQUENCE_TEMPORARY)
+    return more(code)
+  }
+
+  function more(code: Code): State | undefined {
+    if (code === PLUS) {
+      // A third marker is not this syntax.
+      if (size > 1) return nok(code)
+      effects.consume(code)
+      size++
+      return more
+    }
+    if (size < 2) return nok(code)
+
+    const token = effects.exit(SEQUENCE_TEMPORARY)
+    // GFM strikethrough's flanking rule, verbatim (see header).
+    const before = classifyCharacter(previous)
+    const after = classifyCharacter(code)
+    token._open = after === undefined || (after === GROUP_PUNCTUATION && before !== undefined)
+    token._close = before === undefined || (before === GROUP_PUNCTUATION && after !== undefined)
+    return ok(code)
+  }
+}
+
+/**
+ * Pair closers with the nearest earlier opener, wrapping the events between
+ * in `underline` / `underlineText`, and demote every sequence that did not
+ * pair to plain `data` so its characters render as typed.
+ */
+function resolveAllUnderline(events: Event[], context: TokenizeContext): Event[] {
+  let index = -1
+
+  while (++index < events.length) {
+    const closer = events[index]
+    if (
+      closer === undefined ||
+      closer[0] !== 'enter' ||
+      closer[1].type !== SEQUENCE_TEMPORARY ||
+      closer[1]._close !== true
+    ) {
+      continue
+    }
+
+    let open = index
+    while (open--) {
+      const opener = events[open]
+      if (
+        opener === undefined ||
+        opener[0] !== 'exit' ||
+        opener[1].type !== SEQUENCE_TEMPORARY ||
+        opener[1]._open !== true ||
+        // Sizes must match — always two here, kept for parity with the model.
+        closer[1].end.offset - closer[1].start.offset !==
+          opener[1].end.offset - opener[1].start.offset
+      ) {
+        continue
+      }
+
+      closer[1].type = SEQUENCE
+      opener[1].type = SEQUENCE
+
+      const underline: Token = {
+        type: UNDERLINE,
+        start: { ...opener[1].start },
+        end: { ...closer[1].end },
+      }
+      const text: Token = {
+        type: UNDERLINE_TEXT,
+        start: { ...opener[1].end },
+        end: { ...closer[1].start },
+      }
+
+      // Opening.
+      const next: Event[] = [
+        ['enter', underline, context],
+        ['enter', opener[1], context],
+        ['exit', opener[1], context],
+        ['enter', text, context],
+      ]
+
+      // Between — let every other span construct (emphasis, strong,
+      // strikethrough, this one again) resolve inside the pair.
+      const insideSpan = context.parser.constructs.insideSpan.null
+      if (insideSpan !== undefined) {
+        spliceChunked(
+          next,
+          next.length,
+          0,
+          resolveAll(insideSpan, events.slice(open + 1, index), context),
+        )
+      }
+
+      // Closing.
+      spliceChunked(next, next.length, 0, [
+        ['exit', text, context],
+        ['enter', closer[1], context],
+        ['exit', closer[1], context],
+        ['exit', underline, context],
+      ])
+
+      spliceChunked(events, open - 1, index - open + 3, next)
+      index = open + next.length - 2
+      break
+    }
+  }
+
+  // Whatever did not pair is text. Never dropped, never thrown (D3 rule 3).
+  for (const event of events) {
+    if (event[1].type === SEQUENCE_TEMPORARY) event[1].type = DATA
+  }
+
+  return events
+}
+
+function underlineSyntax(): MicromarkExtension {
+  const construct: Construct = {
+    name: 'underline',
+    tokenize: tokenizeUnderline,
+    resolveAll: resolveAllUnderline,
+  }
+  return {
+    text: { [PLUS]: construct },
+    insideSpan: { null: [construct] },
+    attentionMarkers: { null: [PLUS] },
+  }
+}
+
+// ---------------------------------------------------------------------------
+// The mdast compile extension
+// ---------------------------------------------------------------------------
+
+function enterUnderline(this: CompileContext, token: Token): undefined {
+  this.enter({ type: UNDERLINE, children: [], data: { hName: 'u' } }, token)
+}
+
+function exitUnderline(this: CompileContext, token: Token): undefined {
+  this.exit(token)
+}
+
+function underlineFromMarkdown(): FromMarkdownExtension {
+  return {
+    // A soft line break inside `++a\nb++` is kept as text, like `delete`.
+    canContainEols: [UNDERLINE],
+    enter: { [UNDERLINE]: enterUnderline },
+    exit: { [UNDERLINE]: exitUnderline },
+  }
+}
+
+// ---------------------------------------------------------------------------
+// The remark plugin
+// ---------------------------------------------------------------------------
+
+/**
+ * remark plugin: `++text++` → `<u>`. Register after `remarkGfm` in a
+ * `remarkPlugins` list. Same shape as `remark-gfm` itself — it appends one
+ * micromark syntax extension and one mdast compile extension to the
+ * processor's data and returns nothing.
+ */
+export function remarkUnderline(this: RemarkProcessorLike): undefined {
+  const data = this.data()
+  const micromark = data.micromarkExtensions ?? (data.micromarkExtensions = [])
+  const fromMarkdown = data.fromMarkdownExtensions ?? (data.fromMarkdownExtensions = [])
+  micromark.push(underlineSyntax())
+  fromMarkdown.push(underlineFromMarkdown())
+}

package/src/lib/series.ts

@@ -0,0 +1,169 @@
+/**
+ * series.ts — the categorical chart palette, resolved by a frozen literal
+ * lookup and nothing else.
+ *
+ * Promoted in ADR-146 D8. Canonical home for the palette so `ChartLegend`,
+ * `ChartTooltip` and every chart primitive resolve a hue the same way.
+ * Re-exported from `chart-legend.tsx` for the barrel.
+ *
+ * CONSUMERS — measured 2026-09-06, real imports inside `@lovett/ui` (7):
+ * `chart-legend.tsx`, `chart-tooltip.tsx`, `line-chart.tsx`,
+ * `bar-chart.tsx`, `donut-chart.tsx`, `ranked-bars.tsx`, `sparkline.tsx`.
+ * `ChartFrame` does NOT import it — it renders chrome and takes an
+ * already-coloured legend node — so the earlier claim naming it was wrong.
+ *
+ * WHY A FROZEN ARRAY AND NOT A CONSTRUCTED NAME
+ * ----------------------------------------------
+ * `ENGINEERING-AXES.md:186` records the exact defect this shape exists to
+ * prevent. A constructed custom-property name (`--folder-${key}`) produced
+ * `--folder-folder-violet`, which is undefined, which makes the enclosing
+ * `rgb()` invalid, which the browser **silently discards**. Typecheck, lint,
+ * tests, build and the token gate were all green while white-on-white tiles
+ * shipped. There is no gate that reads source and can see it, because the
+ * source is syntactically perfect.
+ *
+ * So no primitive in this package ever composes `` `--series-${i}` ``. The
+ * mapping is the literal array below, the same shape as `metric-card.tsx`'s
+ * `TONE_COLOR`, and `__tests__/chart-series.test.ts` asserts — with a
+ * mutation proof that the guard fails in the failing direction — that every
+ * entry names a custom property that `tokens.css` actually declares.
+ *
+ * Token discipline: this module produces `rgb(var(--token))` strings only. It
+ * contains no colour literal, and every token it names is a **bare RGB
+ * triple** in `tokens.css`, so a call site may legally apply its own alpha —
+ * `rgb(var(--series-1) / 0.12)` for the area fill under a line. That is
+ * asserted too: a series token that grew a baked-in alpha would make every
+ * such call site invalid CSS.
+ *
+ * CALLERS PASS A SLOT INDEX, NEVER A COLOUR AND NEVER A TOKEN NAME.
+ */
+
+/**
+ * The eight categorical series colours, in ADR-146 D2's **measured** order —
+ * blue, green, violet, olive, pink, amber, teal, red.
+ *
+ * The order is load-bearing, not cosmetic:
+ *
+ *   • **Blue is slot 1, not red.** Slot 1 is the single-series default, so a
+ *     red slot 1 would paint every one-series chart in the product accent and
+ *     destroy accent scarcity.
+ *   • **Red is slot 8.** Red belongs to `--accent` and `--destructive`. It
+ *     enters a chart only at eight series.
+ *   • **Green (slot 2) and red (slot 8) sit far apart**, so a two-series
+ *     chart never accidentally reads as pass/fail.
+ *
+ * Worst adjacent pair is ΔE 13.2 (deutan) / 21.0 (normal), identical in both
+ * themes — the palette is theme-independent by construction.
+ */
+export const SERIES = [
+  'rgb(var(--series-1))',
+  'rgb(var(--series-2))',
+  'rgb(var(--series-3))',
+  'rgb(var(--series-4))',
+  'rgb(var(--series-5))',
+  'rgb(var(--series-6))',
+  'rgb(var(--series-7))',
+  'rgb(var(--series-8))',
+] as const
+
+/**
+ * The all-pairs palette, capped at three (ADR-146 D2).
+ *
+ * Scatter, bubble, choropleth and small-multiples let any two marks touch, so
+ * they take the harder all-pairs colour-blindness test instead of the
+ * adjacent-pairs one. **Our eight hues cannot pass it — no ordering can.**
+ * These three (`--series-1` blue, `--series-6` amber, `--series-7` teal) do,
+ * at worst ΔE 14.8 in both modes.
+ *
+ * A scatter-family chart with more than three series folds the remainder into
+ * "Other" or facets into small multiples. It never generates a ninth hue.
+ */
+export const SERIES_SCATTER = [SERIES[0], SERIES[5], SERIES[6]] as const
+
+/** How many slots the default palette has. */
+export const SERIES_SLOT_COUNT = SERIES.length
+
+/** How many slots the all-pairs (`scatter`) palette has. */
+export const SCATTER_SLOT_COUNT = SERIES_SCATTER.length
+
+/**
+ * A legal slot in the default palette.
+ *
+ * Typed as a union rather than `number` so an out-of-range slot is a **type
+ * error at the boundary** (ADR-146 D8) rather than a runtime `undefined` that
+ * becomes invalid CSS. Callers holding a plain `number` narrow with
+ * `isSeriesSlot` and decide explicitly what a ninth series does.
+ */
+export type SeriesSlot = 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7
+
+/** A legal slot in the `scatter` palette. */
+export type ScatterSlot = 0 | 1 | 2
+
+/** Which palette a chart draws from. `scatter` is the all-pairs, 3-slot one. */
+export type SeriesPalette = 'default' | 'scatter'
+
+/** Narrow a plain number to a default-palette slot. */
+export function isSeriesSlot(value: number): value is SeriesSlot {
+  return Number.isInteger(value) && value >= 0 && value < SERIES_SLOT_COUNT
+}
+
+/** Narrow a plain number to a `scatter`-palette slot. */
+export function isScatterSlot(value: number): value is ScatterSlot {
+  return Number.isInteger(value) && value >= 0 && value < SCATTER_SLOT_COUNT
+}
+
+/** The default-palette colour for a slot. Total — the union type guarantees it. */
+export function seriesColor(slot: SeriesSlot): string {
+  return SERIES[slot]
+}
+
+/** The `scatter`-palette colour for a slot. Total. */
+export function scatterColor(slot: ScatterSlot): string {
+  return SERIES_SCATTER[slot]
+}
+
+/**
+ * The colour for `slot` in `palette`, or `undefined` when the slot is outside
+ * that palette's cap.
+ *
+ * `undefined` is the deliberate answer rather than a wrap-around or a clamp:
+ * ADR-146 D2 says a fourth scatter series folds into "Other", and silently
+ * reusing slot 1's blue for slot 4 would draw two different entities in one
+ * hue — a wrong chart that no gate can see. Consumers render the "Other"
+ * treatment (a neutral swatch) when this returns `undefined`.
+ */
+export function paletteColor(
+  palette: SeriesPalette,
+  slot: number,
+): string | undefined {
+  if (palette === 'scatter') {
+    return isScatterSlot(slot) ? scatterColor(slot) : undefined
+  }
+  return isSeriesSlot(slot) ? seriesColor(slot) : undefined
+}
+
+/**
+ * A palette slot, or the explicit `'other'` fold.
+ *
+ * `'other'` is how a chart says "this mark is the remainder". ADR-146 D2 caps
+ * the palette at eight slots (three for `scatter`) and folds the rest rather
+ * than generating a ninth hue, so the fold has to be representable in the
+ * data — not improvised at render time.
+ */
+export type ChartSlot = SeriesSlot | 'other'
+
+/** The neutral swatch for the `'other'` fold — a grey, never a hue. */
+export const OTHER_SLOT_COLOR = 'rgb(var(--text-muted))'
+
+/**
+ * The rendered colour for a `ChartSlot`. Total: anything the palette cannot
+ * legally colour — the `'other'` fold, or a slot past a palette's cap — comes
+ * back as the neutral swatch rather than wrapping onto a hue already in use.
+ *
+ * Shared by `ChartLegend` and `ChartTooltip` so a series cannot be one colour
+ * in the legend and another in the readout.
+ */
+export function slotColor(slot: ChartSlot, palette: SeriesPalette): string {
+  if (slot === 'other') return OTHER_SLOT_COLOR
+  return paletteColor(palette, slot) ?? OTHER_SLOT_COLOR
+}