@yewdiel21/motion-kit 0.10.0 → 0.15.0

package/src/components/voice-dots/voice-dots.css

@@ -0,0 +1,69 @@
+/* voice-dots — round dots in the text colour (or the chart colours) that stretch into pills with the voice.
+   The row is tall enough for the tallest pill, so the layout around it never moves. */
+.mk-voice-dots,
+mk-voice-dots {
+  --mk-voice-size: 12px;
+  --mk-voice-dot: var(--mk-text);
+  display: inline-grid;
+  place-items: center;
+  min-width: calc(var(--mk-voice-size) * 8);
+  height: calc(var(--mk-voice-size) * 4.6);
+}
+
+[data-mk-voice-row] {
+  display: inline-flex;
+  align-items: center;
+  gap: calc(var(--mk-voice-size) * 0.9);
+  height: 100%;
+}
+
+[data-mk-voice-dot] {
+  display: block;
+  width: var(--mk-voice-size);
+  height: var(--mk-voice-size);
+  border-radius: var(--mk-radius-full);
+  background: var(--mk-voice-dot);
+  transition:
+    background-color 0.3s ease,
+    opacity 0.3s ease;
+  will-change: transform, height;
+}
+
+:is(.mk-voice-dots, mk-voice-dots)[data-mk-state='idle'] [data-mk-voice-dot] {
+  opacity: 0.55;
+}
+
+:is(.mk-voice-dots, mk-voice-dots)[data-mk-colorful] [data-mk-voice-dot='1'] {
+  --mk-voice-dot: var(--mk-chart-1, #2a78d6);
+}
+:is(.mk-voice-dots, mk-voice-dots)[data-mk-colorful] [data-mk-voice-dot='2'] {
+  --mk-voice-dot: var(--mk-chart-8, #e34948);
+}
+:is(.mk-voice-dots, mk-voice-dots)[data-mk-colorful] [data-mk-voice-dot='3'] {
+  --mk-voice-dot: var(--mk-chart-4, #eda100);
+}
+:is(.mk-voice-dots, mk-voice-dots)[data-mk-colorful] [data-mk-voice-dot='4'] {
+  --mk-voice-dot: var(--mk-chart-3, #1baf7a);
+}
+:is(.mk-voice-dots, mk-voice-dots)[data-mk-colorful] [data-mk-voice-dot='5'] {
+  --mk-voice-dot: var(--mk-chart-7, #6250d6);
+}
+:is(.mk-voice-dots, mk-voice-dots)[data-mk-colorful] [data-mk-voice-dot='6'] {
+  --mk-voice-dot: var(--mk-chart-2, #eb6834);
+}
+
+/* Without motion the state shows in the dots' colour. */
+@media (prefers-reduced-motion: reduce) {
+  :is(.mk-voice-dots, mk-voice-dots)[data-mk-state='listening'] [data-mk-voice-dot] {
+    --mk-voice-dot: var(--mk-accent);
+  }
+  :is(.mk-voice-dots, mk-voice-dots)[data-mk-state='thinking'] [data-mk-voice-dot] {
+    opacity: 0.75;
+  }
+}
+
+@media (forced-colors: active) {
+  [data-mk-voice-dot] {
+    background: CanvasText;
+  }
+}

package/src/core/chips.ts

@@ -0,0 +1,196 @@
+import { gsap, EASE, Flip, registerMotion } from './gsap';
+import { reduced } from './reduced';
+import { createScope } from './scope';
+import { TIMING } from './timing';
+import { ringPulse, shake } from '../motion/micro';
+
+/*
+ * Chips (multi-select, tag-input): removable chips in a list. A chip that
+ * arrives pops in (scale .6 → 1, blur 6 → 0, pop curve) while the others glide
+ * to make room (Flip, layout spring); one that leaves folds away (its width,
+ * padding and margin to 0 out of a blur, .22 s) and the rest close the gap.
+ * Keyboard: from the field, ← reaches the last chip; ← / → move between chips,
+ * Delete or Backspace removes the focused one, → past the last returns to the
+ * field. arm() rings a chip that the next Backspace will remove; flash()
+ * shakes and rings one (a duplicate, a value already chosen).
+ */
+
+export interface ChipItem {
+  value: string;
+  label: string;
+}
+
+export interface ChipsOptions {
+  /** A chip's remove button wants out. */
+  onRemove: (value: string) => void;
+  /** The keyboard left the chips towards the field. */
+  onExit?: () => void;
+  /** Accessible name of a chip's remove button (default 'Quitar <label>'). */
+  removeLabel?: (item: ChipItem) => string;
+  disabled?: boolean;
+}
+
+export interface Chips {
+  readonly element: HTMLUListElement;
+  /** Show these chips in this order; arrivals pop in and departures fold away when `animate`. */
+  set(items: ChipItem[], animate?: boolean): void;
+  /** Ring a chip as the next to go (null: none). */
+  arm(value: string | null): void;
+  readonly armed: string | null;
+  /** Shake and ring a chip. */
+  flash(value: string): void;
+  /** Focus the last chip (from the field). False when there are none. */
+  focusLast(): boolean;
+  destroy(): void;
+}
+
+const CLOSE = '<svg aria-hidden="true" width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2.4" stroke-linecap="round"><path d="M7 7l10 10M17 7L7 17"/></svg>';
+
+export function createChips(options: ChipsOptions): Chips {
+  registerMotion();
+  const scope = createScope();
+  const list = document.createElement('ul');
+  list.dataset.mkChips = '';
+  list.setAttribute('role', 'list');
+  const effects = new Set<gsap.core.Animation>();
+  const keep = (animation: gsap.core.Animation | null) => {
+    if (!animation) return;
+    effects.add(animation);
+    // Finished ones leave as new ones arrive: the animation's own onComplete stays untouched.
+    for (const effect of effects) if (effect.totalProgress() === 1) effects.delete(effect);
+  };
+  scope.add(() => {
+    for (const effect of effects) effect.kill();
+    effects.clear();
+    list.remove();
+  });
+  let armed: string | null = null;
+
+  const chipOf = (value: string) => [...list.querySelectorAll<HTMLElement>('[data-mk-chip]')].find((chip) => chip.dataset.value === value && !chip.hasAttribute('data-mk-leaving')) ?? null;
+  const present = () => [...list.querySelectorAll<HTMLElement>('[data-mk-chip]:not([data-mk-leaving])')];
+
+  const make = (item: ChipItem) => {
+    const chip = document.createElement('li');
+    chip.dataset.mkChip = '';
+    chip.dataset.value = item.value;
+    chip.tabIndex = -1;
+    const label = document.createElement('span');
+    label.dataset.mkChipLabel = '';
+    label.textContent = item.label;
+    chip.append(label);
+    if (!options.disabled) {
+      const remove = document.createElement('button');
+      remove.type = 'button';
+      remove.tabIndex = -1;
+      remove.dataset.mkChipRemove = '';
+      remove.setAttribute('aria-label', options.removeLabel ? options.removeLabel(item) : `Quitar ${item.label}`);
+      remove.innerHTML = CLOSE;
+      chip.append(remove);
+    }
+    return chip;
+  };
+
+  const leave = (chip: HTMLElement, animate: boolean) => {
+    chip.setAttribute('data-mk-leaving', '');
+    if (!animate || reduced()) return chip.remove();
+    gsap.killTweensOf(chip);
+    keep(
+      gsap.to(chip, {
+        width: 0,
+        paddingLeft: 0,
+        paddingRight: 0,
+        marginLeft: 0,
+        marginRight: 0,
+        opacity: 0,
+        scale: 0.8,
+        filter: 'blur(6px)',
+        duration: 0.22,
+        ease: 'power2.in',
+        onComplete: () => chip.remove(),
+      }),
+    );
+  };
+
+  const set = (items: ChipItem[], animate = true) => {
+    const wanted = new Set(items.map((item) => item.value));
+    const staying = present().filter((chip) => wanted.has(chip.dataset.value!));
+    const state = animate && !reduced() && staying.length ? Flip.getState(staying) : null;
+    for (const chip of present()) if (!wanted.has(chip.dataset.value!)) leave(chip, animate);
+    const arriving: HTMLElement[] = [];
+    let previous: HTMLElement | null = null;
+    for (const item of items) {
+      let chip = chipOf(item.value);
+      if (!chip) {
+        chip = make(item);
+        arriving.push(chip);
+      } else chip.querySelector<HTMLElement>('[data-mk-chip-label]')!.textContent = item.label;
+      // Keep the given order; leaving chips stay where they were while they fold.
+      if (previous) previous.after(chip);
+      else list.prepend(chip);
+      previous = chip;
+    }
+    if (armed && !wanted.has(armed)) armed = null;
+    if (state) keep(Flip.from(state, { targets: staying, duration: TIMING.layoutTravel, ease: EASE.layoutReflow }));
+    if (animate && arriving.length && !reduced()) {
+      keep(gsap.fromTo(arriving, { scale: 0.6, opacity: 0, filter: 'blur(6px)' }, { scale: 1, opacity: 1, filter: 'blur(0px)', duration: 0.3, stagger: 0.04, ease: EASE.pop, clearProps: 'scale,opacity,filter,transform' }));
+    }
+  };
+
+  const arm = (value: string | null) => {
+    armed = value;
+    for (const chip of present()) chip.toggleAttribute('data-mk-armed', chip.dataset.value === value);
+    const chip = value ? chipOf(value) : null;
+    if (chip && !reduced()) keep(gsap.fromTo(chip, { scale: 1.08 }, { scale: 1, duration: 0.3, ease: EASE.click, clearProps: 'scale' }));
+  };
+
+  scope.on(list, 'click', (event) => {
+    const remove = (event.target as Element | null)?.closest('[data-mk-chip-remove]');
+    const chip = remove?.closest<HTMLElement>('[data-mk-chip]');
+    if (chip && !chip.hasAttribute('data-mk-leaving')) options.onRemove(chip.dataset.value!);
+  });
+  scope.on(list, 'keydown', (event) => {
+    const key = event as KeyboardEvent;
+    const chip = (key.target as Element | null)?.closest<HTMLElement>('[data-mk-chip]');
+    if (!chip) return;
+    const chips = present();
+    const index = chips.indexOf(chip);
+    if (key.key === 'ArrowLeft') {
+      key.preventDefault();
+      chips[Math.max(0, index - 1)]?.focus();
+    } else if (key.key === 'ArrowRight') {
+      key.preventDefault();
+      if (index >= chips.length - 1) options.onExit?.();
+      else chips[index + 1]?.focus();
+    } else if ((key.key === 'Delete' || key.key === 'Backspace') && !options.disabled) {
+      key.preventDefault();
+      const next = chips[index + 1] ?? chips[index - 1] ?? null;
+      options.onRemove(chip.dataset.value!);
+      if (next && next !== chip && next.isConnected && !next.hasAttribute('data-mk-leaving')) next.focus();
+      else options.onExit?.();
+    } else if (key.key === 'Escape' || key.key === 'Tab') {
+      if (key.key === 'Escape') key.preventDefault();
+      if (key.key === 'Escape') options.onExit?.();
+    }
+  });
+
+  return {
+    element: list,
+    set,
+    arm,
+    get armed() {
+      return armed;
+    },
+    flash(value) {
+      const chip = chipOf(value);
+      if (!chip) return;
+      keep(shake(chip, 3));
+      keep(ringPulse(chip));
+    },
+    focusLast() {
+      const chips = present();
+      chips[chips.length - 1]?.focus();
+      return chips.length > 0;
+    },
+    destroy: () => scope.dispose(),
+  };
+}

package/src/core/color.ts

@@ -0,0 +1,304 @@
+/*
+ * Colour model for the colour components. HSVA is the working space (h 0–360,
+ * s and v 0–100, a 0–1): the saturation × brightness area and the hue slider
+ * map onto it directly. Parses #rgb, #rgba, #rrggbb, #rrggbbaa, rgb()/rgba()
+ * and hsl()/hsla() (comma or space syntax, optional "/ alpha"); formats hex,
+ * rgb or hsl (alpha only when below 1). A grey keeps the hue it is given, so
+ * dragging through grey never resets the hue.
+ */
+
+export interface Hsva {
+  /** 0–360. */
+  h: number;
+  /** 0–100. */
+  s: number;
+  /** 0–100. */
+  v: number;
+  /** 0–1. */
+  a: number;
+}
+
+export interface Rgba {
+  /** 0–255. */
+  r: number;
+  g: number;
+  b: number;
+  a: number;
+}
+
+export interface Hsla {
+  h: number;
+  /** 0–100. */
+  s: number;
+  l: number;
+  a: number;
+}
+
+export type ColorFormat = 'hex' | 'rgb' | 'hsl';
+export type ColorChannel = 'hue' | 'saturation' | 'brightness' | 'lightness' | 'red' | 'green' | 'blue' | 'alpha';
+
+export const CHANNEL_LABELS: Record<ColorChannel, string> = {
+  hue: 'Tono',
+  saturation: 'Saturación',
+  brightness: 'Brillo',
+  lightness: 'Luminosidad',
+  red: 'Rojo',
+  green: 'Verde',
+  blue: 'Azul',
+  alpha: 'Opacidad',
+};
+
+export const CHANNEL_RANGE: Record<ColorChannel, [number, number]> = {
+  hue: [0, 360],
+  saturation: [0, 100],
+  brightness: [0, 100],
+  lightness: [0, 100],
+  red: [0, 255],
+  green: [0, 255],
+  blue: [0, 255],
+  alpha: [0, 1],
+};
+
+const clamp = (n: number, min: number, max: number) => Math.min(max, Math.max(min, Number.isFinite(n) ? n : min));
+/** Two decimals: enough for a lossless 8-bit round trip, without float noise (31.999…). */
+const tidy = (n: number) => Math.round(n * 100) / 100;
+const wrapHue = (h: number) => {
+  const hue = ((h % 360) + 360) % 360;
+  return hue === 0 && h > 0 ? 360 : hue;
+};
+
+const hsva = (h: number, s: number, v: number, a: number): Hsva => ({
+  h: tidy(clamp(h, 0, 360)),
+  s: tidy(clamp(s, 0, 100)),
+  v: tidy(clamp(v, 0, 100)),
+  a: Math.round(clamp(a, 0, 1) * 1000) / 1000,
+});
+
+/** HSVA → RGBA (channels 0–255, unrounded). */
+export function hsvToRgb({ h, s, v, a }: Hsva): Rgba {
+  const sat = s / 100;
+  const val = v / 100;
+  const f = (n: number) => {
+    const k = (n + (h % 360) / 60) % 6;
+    return val - val * sat * Math.max(0, Math.min(k, 4 - k, 1));
+  };
+  return { r: f(5) * 255, g: f(3) * 255, b: f(1) * 255, a };
+}
+
+/** RGBA → HSVA; a grey keeps `hue` (and black keeps `saturation`) when given. */
+export function rgbToHsv({ r, g, b, a }: Rgba, hue?: number, saturation?: number): Hsva {
+  const [red, green, blue] = [r / 255, g / 255, b / 255];
+  const max = Math.max(red, green, blue);
+  const min = Math.min(red, green, blue);
+  const delta = max - min;
+  let h = hue ?? 0;
+  if (delta > 0) {
+    if (max === red) h = 60 * (((green - blue) / delta) % 6);
+    else if (max === green) h = 60 * ((blue - red) / delta + 2);
+    else h = 60 * ((red - green) / delta + 4);
+    if (h < 0) h += 360;
+  }
+  const s = max === 0 ? (saturation ?? 0) : (delta / max) * 100;
+  return hsva(h, s, max * 100, a);
+}
+
+export function hsvToHsl({ h, s, v, a }: Hsva): Hsla {
+  const sat = s / 100;
+  const val = v / 100;
+  const l = val * (1 - sat / 2);
+  const sl = l === 0 || l === 1 ? 0 : (val - l) / Math.min(l, 1 - l);
+  return { h, s: sl * 100, l: l * 100, a };
+}
+
+export function hslToHsv({ h, s, l, a }: Hsla, saturation?: number): Hsva {
+  const sat = s / 100;
+  const light = l / 100;
+  const v = light + sat * Math.min(light, 1 - light);
+  const sv = v === 0 ? (saturation ?? 0) / 100 : 2 * (1 - light / v);
+  return hsva(h, sv * 100, v * 100, a);
+}
+
+const number = (text: string, scale: number) => {
+  const value = Number.parseFloat(text);
+  if (!Number.isFinite(value)) return Number.NaN;
+  return text.trim().endsWith('%') ? (value / 100) * scale : value;
+};
+
+const alphaOf = (text: string | undefined) => (text === undefined ? 1 : clamp(number(text, 1), 0, 1));
+
+const angle = (text: string) => {
+  const value = Number.parseFloat(text);
+  if (!Number.isFinite(value)) return Number.NaN;
+  if (/turn$/i.test(text)) return value * 360;
+  if (/grad$/i.test(text)) return value * 0.9;
+  if (/rad$/i.test(text)) return (value * 180) / Math.PI;
+  return value;
+};
+
+/** "rgb(1, 2, 3)", "rgb(1 2 3 / 50%)" → its parts, or null. */
+function args(text: string, name: string): string[] | null {
+  const match = new RegExp(`^${name}a?\\(\\s*([^)]*)\\)$`, 'i').exec(text);
+  if (!match) return null;
+  const body = match[1]!.trim();
+  const [main, slash] = body.split('/');
+  const parts = main!.includes(',') ? main!.split(',').map((part) => part.trim()) : main!.trim().split(/\s+/);
+  if (slash !== undefined) {
+    if (main!.includes(',') || parts.length !== 3) return null;
+    parts.push(slash.trim());
+  }
+  if (parts.length < 3 || parts.length > 4 || parts.some((part) => !part)) return null;
+  return parts;
+}
+
+/**
+ * Any colour the components accept, as HSVA; null when the text is not one.
+ * `hue` is kept for greys (no hue of their own).
+ */
+export function parseColor(input: string | null | undefined, hue?: number): Hsva | null {
+  const text = (input ?? '').trim().toLowerCase();
+  if (!text) return null;
+  const hex = /^#?([0-9a-f]{3,4}|[0-9a-f]{6}|[0-9a-f]{8})$/.exec(text);
+  if (hex) {
+    let digits = hex[1]!;
+    if (digits.length <= 4) digits = [...digits].map((c) => c + c).join('');
+    const channel = (i: number) => Number.parseInt(digits.slice(i, i + 2), 16);
+    return rgbToHsv({ r: channel(0), g: channel(2), b: channel(4), a: digits.length === 8 ? channel(6) / 255 : 1 }, hue);
+  }
+  const rgb = args(text, 'rgb');
+  if (rgb) {
+    const [r, g, b] = rgb.slice(0, 3).map((part) => number(part, 255));
+    const a = alphaOf(rgb[3]);
+    if (![r, g, b, a].every(Number.isFinite)) return null;
+    return rgbToHsv({ r: clamp(r!, 0, 255), g: clamp(g!, 0, 255), b: clamp(b!, 0, 255), a }, hue);
+  }
+  const hsl = args(text, 'hsl');
+  if (hsl) {
+    const h = angle(hsl[0]!);
+    const s = Number.parseFloat(hsl[1]!);
+    const l = Number.parseFloat(hsl[2]!);
+    const a = alphaOf(hsl[3]);
+    if (![h, s, l, a].every(Number.isFinite)) return null;
+    const color = hslToHsv({ h: wrapHue(h), s: clamp(s, 0, 100), l: clamp(l, 0, 100), a });
+    return color.s === 0 && hue !== undefined ? { ...color, h: hue } : color;
+  }
+  return null;
+}
+
+const DEFAULT: Hsva = { h: 0, s: 100, v: 100, a: 1 };
+
+/** A colour option (text or HSVA) as HSVA; `fallback` (default red) when it cannot be read. */
+export function toHsva(input: string | Hsva | null | undefined, fallback: Hsva = DEFAULT): Hsva {
+  if (input && typeof input === 'object') return hsva(input.h, input.s, input.v, input.a ?? 1);
+  return parseColor(input, fallback.h) ?? { ...fallback };
+}
+
+const byte = (n: number) => Math.round(clamp(n, 0, 255));
+const hex2 = (n: number) => byte(n).toString(16).padStart(2, '0');
+const short = (n: number) => String(Math.round(n * 100) / 100);
+
+/** #rrggbb, or #rrggbbaa when translucent. */
+export function toHex(color: Hsva): string {
+  const { r, g, b, a } = hsvToRgb(color);
+  const alpha = byte(a * 255);
+  return `#${hex2(r)}${hex2(g)}${hex2(b)}${alpha < 255 ? hex2(alpha) : ''}`;
+}
+
+/** The colour as CSS text: hex, "rgb(255 136 0 / 0.5)" or "hsl(32 100% 50%)". */
+export function formatColor(color: Hsva, format: ColorFormat = 'hex'): string {
+  if (format === 'rgb') {
+    const { r, g, b, a } = hsvToRgb(color);
+    return `rgb(${byte(r)} ${byte(g)} ${byte(b)}${a < 1 ? ` / ${short(a)}` : ''})`;
+  }
+  if (format === 'hsl') {
+    const { h, s, l, a } = hsvToHsl(color);
+    return `hsl(${Math.round(h) % 360} ${Math.round(s)}% ${Math.round(l)}%${a < 1 ? ` / ${short(a)}` : ''})`;
+  }
+  return toHex(color);
+}
+
+/** Same colour on screen (same 8-bit hex). */
+export const sameColor = (a: Hsva, b: Hsva) => toHex(a) === toHex(b);
+
+/** Relative luminance (WCAG), 0–1, ignoring alpha. */
+export function luminance(color: Hsva): number {
+  const { r, g, b } = hsvToRgb(color);
+  const linear = (n: number) => {
+    const c = n / 255;
+    return c <= 0.03928 ? c / 12.92 : ((c + 0.055) / 1.055) ** 2.4;
+  };
+  return 0.2126 * linear(r) + 0.7152 * linear(g) + 0.0722 * linear(b);
+}
+
+/** One channel's value in its own range (CHANNEL_RANGE). */
+export function getChannel(color: Hsva, channel: ColorChannel): number {
+  switch (channel) {
+    case 'hue':
+      return color.h;
+    case 'saturation':
+      return color.s;
+    case 'brightness':
+      return color.v;
+    case 'alpha':
+      return color.a;
+    case 'lightness':
+      return tidy(hsvToHsl(color).l);
+    default: {
+      const rgb = hsvToRgb(color);
+      return byte(channel === 'red' ? rgb.r : channel === 'green' ? rgb.g : rgb.b);
+    }
+  }
+}
+
+/** A copy with one channel changed (clamped to its range); the hue survives greys. */
+export function setChannel(color: Hsva, channel: ColorChannel, value: number): Hsva {
+  const [min, max] = CHANNEL_RANGE[channel];
+  const next = clamp(value, min, max);
+  switch (channel) {
+    case 'hue':
+      return hsva(next, color.s, color.v, color.a);
+    case 'saturation':
+      return hsva(color.h, next, color.v, color.a);
+    case 'brightness':
+      return hsva(color.h, color.s, next, color.a);
+    case 'alpha':
+      return hsva(color.h, color.s, color.v, next);
+    case 'lightness': {
+      const hsl = hsvToHsl(color);
+      return { ...hslToHsv({ ...hsl, l: next }, color.s), h: color.h };
+    }
+    default: {
+      const rgb = hsvToRgb(color);
+      const key = channel === 'red' ? 'r' : channel === 'green' ? 'g' : 'b';
+      return rgbToHsv({ ...rgb, [key]: next }, color.h, color.s);
+    }
+  }
+}
+
+/** What a channel's value reads as: "210°", "64 %", "136". */
+export function channelText(channel: ColorChannel, value: number, format?: Intl.NumberFormat): string {
+  const shown = (n: number) => (format ? format.format(n) : String(Math.round(n)));
+  if (channel === 'hue') return `${shown(value)}°`;
+  if (channel === 'alpha') return `${shown(value * 100)} %`;
+  if (channel === 'red' || channel === 'green' || channel === 'blue') return shown(value);
+  return `${shown(value)} %`;
+}
+
+const rgbText = (color: Hsva) => formatColor(color, 'rgb');
+
+/** A slider track for `channel` at `color`: the channel's whole range, the other channels fixed. */
+export function channelGradient(color: Hsva, channel: ColorChannel, direction = 'to right'): string {
+  const opaque = { ...color, a: 1 };
+  let stops: string[];
+  if (channel === 'hue') stops = [0, 60, 120, 180, 240, 300, 360].map((h) => rgbText({ h, s: 100, v: 100, a: 1 }));
+  else if (channel === 'alpha') stops = [rgbText({ ...opaque, a: 0 }), rgbText(opaque)];
+  else if (channel === 'lightness') stops = [0, 50, 100].map((l) => rgbText(setChannel(opaque, 'lightness', l)));
+  else {
+    const [min, max] = CHANNEL_RANGE[channel];
+    stops = [setChannel(opaque, channel, min), setChannel(opaque, channel, max)].map(rgbText);
+  }
+  return `linear-gradient(${direction}, ${stops.join(', ')})`;
+}
+
+/** The saturation (x) × brightness (y) square at hue `h`. */
+export const areaBackground = (h: number) =>
+  `linear-gradient(to top, #000, transparent), linear-gradient(to right, #fff, hsl(${Math.round(h) % 360} 100% 50%))`;

package/src/core/date-range.ts

@@ -0,0 +1,67 @@
+import { addDays, dayKey, sameDay, toDate, type DateInput } from './dates';
+
+/*
+ * Date ranges on local days (range-calendar, date-range-picker): reading a
+ * {start, end} option, the day rules (min, max, unavailable days) and the
+ * two-click pick — the first click fixes an anchor, the second closes the
+ * range in either direction; crossing an unavailable day restarts at the
+ * clicked day.
+ */
+
+export interface DateRange {
+  start: Date;
+  end: Date;
+}
+
+export interface DayRules {
+  min?: Date | null;
+  max?: Date | null;
+  isUnavailable?: (day: Date) => boolean;
+}
+
+const valid = (input: DateInput | null | undefined) => {
+  if (input === null || input === undefined || input === '') return null;
+  const date = toDate(input, new Date(Number.NaN));
+  return Number.isNaN(date.getTime()) ? null : date;
+};
+
+/** An ordered range from {start, end} (Dates or 'YYYY-MM-DD'); null when either end is missing or unreadable. */
+export function toRange(value: { start?: DateInput | null; end?: DateInput | null } | null | undefined): DateRange | null {
+  if (!value) return null;
+  const start = valid(value.start);
+  const end = valid(value.end);
+  if (!start || !end) return null;
+  return start <= end ? { start, end } : { start: end, end: start };
+}
+
+export const rangeKeys = (range: DateRange) => ({ start: dayKey(range.start), end: dayKey(range.end) });
+
+export const inRange = (day: Date, range: DateRange | null | undefined) => !!range && day >= range.start && day <= range.end;
+
+/** Days from start to end, both included. */
+export const rangeLength = (range: DateRange) =>
+  Math.round((Date.UTC(range.end.getFullYear(), range.end.getMonth(), range.end.getDate()) - Date.UTC(range.start.getFullYear(), range.start.getMonth(), range.start.getDate())) / 86400000) + 1;
+
+export function isPickable(day: Date, rules: DayRules = {}): boolean {
+  if (rules.min && day < rules.min) return false;
+  if (rules.max && day > rules.max) return false;
+  return !rules.isUnavailable?.(day);
+}
+
+/** Every day of the range can be picked. */
+export function rangeIsPickable(range: DateRange, rules: DayRules = {}): boolean {
+  for (let day = range.start; day <= range.end; day = addDays(day, 1)) if (!isPickable(day, rules)) return false;
+  return true;
+}
+
+/**
+ * One click. Without an anchor, `day` becomes it. With one, the range closes
+ * (ordered); if it would cross a day that cannot be picked, `day` becomes the
+ * new anchor instead. Clicking the anchor again makes a one-day range.
+ */
+export function pickDay(anchor: Date | null, day: Date, rules: DayRules = {}): { anchor: Date | null; range: DateRange | null } {
+  if (!anchor) return { anchor: day, range: null };
+  const range = anchor <= day ? { start: anchor, end: day } : { start: day, end: anchor };
+  if (!sameDay(anchor, day) && !rangeIsPickable(range, rules)) return { anchor: day, range: null };
+  return { anchor: null, range };
+}

package/src/core/dates.ts

@@ -83,7 +83,17 @@ export function safeFormat(locale: string | undefined, options: Intl.DateTimeFor
   }
 }
 
-export const capitalize = (text: string) => text.charAt(0).toLocaleUpperCase() + text.slice(1);
+/** Numbers in the language of the page around `element`: "4,6" and "1204" on a Spanish page, "4.6" and "1,204" in English. */
+export function numberFormat(element: Element, options: Intl.NumberFormatOptions = {}): Intl.NumberFormat {
+  const locale = element.closest('[lang]')?.getAttribute('lang') || undefined;
+  try {
+    return new Intl.NumberFormat(locale, options);
+  } catch {
+    return new Intl.NumberFormat(undefined, options);
+  }
+}
+
+export const capitalize =(text: string) => text.charAt(0).toLocaleUpperCase() + text.slice(1);
 
 /** Options given as JSON text (data-mk-* attributes through autoInit) become values. */
 export function fromJson<T>(value: T | string | undefined): T | undefined {