@svgrid/grid 2.1.21 → 2.1.23

package/src/conditional-formatting.ts

@@ -10,15 +10,59 @@
  * component just paints the result and the logic is unit-testable.
  */
 
+/** A single gradient stop along the normalized 0..1 domain. */
+export type ColorScaleStop = { offset: number; color: string }
+
+/**
+ * How `minValue`/`maxValue` (and the derived column extremes) are read:
+ * - `absolute` (default): literal data values.
+ * - `percent`: 0..100 positions along the column's own min..max span, so you
+ *   can say "tint the top 20%" without knowing the numbers up front.
+ */
+export type ScaleBounds = 'absolute' | 'percent'
+
 export type ColorScaleFormat = {
   type: 'colorScale'
   /** 2-stop (min/max) or 3-stop (min/mid/max) gradient. Hex colors. */
-  min: string
+  min?: string
   mid?: string
-  max: string
+  max?: string
+  /**
+   * N-stop gradient along the normalized domain (offsets 0..1). When present
+   * this overrides `min`/`mid`/`max`, enabling banded / traffic-light scales.
+   */
+  stops?: ReadonlyArray<ColorScaleStop>
+  /**
+   * `hue` (default): interpolate between stop colors into an opaque fill.
+   * `alpha`: keep a single `base` color and interpolate its *opacity*, so the
+   * tint composites over zebra striping, selection, and pinned backgrounds
+   * instead of painting over them - Adaptable's "live heat map" look.
+   */
+  mode?: 'hue' | 'alpha'
+  /** Base color for `alpha` mode. Default `#2563eb`. */
+  base?: string
+  /** [min, max] opacity for `alpha` mode. Default [0.05, 0.85]. */
+  alphaBounds?: readonly [number, number]
   /** Fix the scale; otherwise derived from the column's data. */
   minValue?: number
   maxValue?: number
+  /** Interpret `minValue`/`maxValue` as absolute values or 0..100 percents. */
+  bounds?: ScaleBounds
+  /**
+   * Diverging scale pinned at 0: negatives and positives shade outward from a
+   * neutral midpoint, symmetric around zero. Ideal for P&L / price deltas.
+   */
+  zeroCentred?: boolean
+  /** Flip the ramp so the lowest values attract the most attention. */
+  reverse?: boolean
+  /**
+   * Tint by this cell's value as a proportion of another column's value on the
+   * SAME row (a field key on the row object), instead of the column extremes.
+   * Column comparison - e.g. filled vs target, open vs total.
+   */
+  compareColumn?: string
+  /** Attach a tooltip showing the raw value or its % position on the ramp. */
+  tooltip?: 'value' | 'percent'
 }
 
 export type DataBarFormat = {
@@ -27,6 +71,15 @@ export type DataBarFormat = {
   negativeColor?: string
   minValue?: number
   maxValue?: number
+  /** Interpret `minValue`/`maxValue` as absolute values or 0..100 percents. */
+  bounds?: ScaleBounds
+  /**
+   * Size the bar by this cell's value as a proportion of another column's
+   * value on the same row (a field key), instead of the column extremes.
+   */
+  compareColumn?: string
+  /** Fill the bar with a left-to-right gradient rather than a flat color. */
+  gradient?: boolean
   /** Show the cell's text on top of the bar. Default true. */
   showValue?: boolean
 }
@@ -66,9 +119,11 @@ export type ResolvedCellFormat = {
   background?: string
   color?: string
   fontWeight?: string | number
-  dataBar?: { percent: number; color: string; fromRight: boolean }
+  dataBar?: { percent: number; color: string; fromRight: boolean; gradient?: boolean }
   icon?: string
   iconOnly?: boolean
+  /** Tooltip text (value / percentile), when a format requests one. */
+  title?: string
 }
 
 export type ColumnStat = { min: number; max: number }
@@ -158,13 +213,85 @@ export function lerpColor(a: string, b: string, t: number): string {
   ])
 }
 
+/** Build an `rgba()` string from a hex color + opacity. Falls back to the hex. */
+export function rgba(hex: string, alpha: number): string {
+  const rgb = parseHex(hex)
+  if (!rgb) return hex
+  return `rgba(${rgb[0]}, ${rgb[1]}, ${rgb[2]}, ${clamp01(alpha).toFixed(3)})`
+}
+
+/** Color of an N-stop ramp at normalized position `t`. Stops sorted by offset. */
+function stopsColorAt(stops: ReadonlyArray<ColorScaleStop>, t: number): string {
+  const sorted = [...stops].sort((a, b) => a.offset - b.offset)
+  if (sorted.length === 0) return '#000000'
+  if (t <= sorted[0]!.offset) return sorted[0]!.color
+  const last = sorted[sorted.length - 1]!
+  if (t >= last.offset) return last.color
+  for (let i = 0; i < sorted.length - 1; i += 1) {
+    const a = sorted[i]!
+    const b = sorted[i + 1]!
+    if (t >= a.offset && t <= b.offset) {
+      const span = b.offset - a.offset || 1
+      return lerpColor(a.color, b.color, (t - a.offset) / span)
+    }
+  }
+  return last.color
+}
+
+/** The interpolated color for a color-scale at normalized position `t`. */
 function colorScaleAt(fmt: ColorScaleFormat, t: number): string {
+  if (fmt.stops && fmt.stops.length >= 2) return stopsColorAt(fmt.stops, t)
+  const min = fmt.min ?? '#ffffff'
+  const max = fmt.max ?? '#000000'
   if (fmt.mid) {
     return t <= 0.5
-      ? lerpColor(fmt.min, fmt.mid, t / 0.5)
-      : lerpColor(fmt.mid, fmt.max, (t - 0.5) / 0.5)
+      ? lerpColor(min, fmt.mid, t / 0.5)
+      : lerpColor(fmt.mid, max, (t - 0.5) / 0.5)
   }
-  return lerpColor(fmt.min, fmt.max, t)
+  return lerpColor(min, max, t)
+}
+
+/**
+ * Normalized position (0..1) of `n` within a format's domain, honoring
+ * absolute/percent bounds, zero-centred diverging scales, cross-column
+ * comparison, and reverse. Returns null when the domain can't be resolved
+ * (e.g. compareColumn missing / zero on the row).
+ */
+function domainT(
+  fmt: ColorScaleFormat | DataBarFormat,
+  n: number,
+  row: unknown,
+  stat: ColumnStat | null,
+): number | null {
+  let t: number
+
+  if (fmt.compareColumn) {
+    const other = Number((row as Record<string, unknown> | null)?.[fmt.compareColumn])
+    if (!Number.isFinite(other) || other === 0) return null
+    t = clamp01(n / other)
+  } else if (fmt.type === 'colorScale' && fmt.zeroCentred) {
+    const dMin = fmt.minValue ?? stat?.min ?? n
+    const dMax = fmt.maxValue ?? stat?.max ?? n
+    const bound = Math.max(Math.abs(dMin), Math.abs(dMax)) || 1
+    t = clamp01(0.5 + n / bound / 2)
+  } else {
+    const dMin = stat?.min ?? n
+    const dMax = stat?.max ?? n
+    let lo: number
+    let hi: number
+    if (fmt.bounds === 'percent') {
+      const span = dMax - dMin
+      lo = dMin + ((fmt.minValue ?? 0) / 100) * span
+      hi = dMin + ((fmt.maxValue ?? 100) / 100) * span
+    } else {
+      lo = fmt.minValue ?? dMin
+      hi = fmt.maxValue ?? dMax
+    }
+    t = hi === lo ? 0.5 : clamp01((n - lo) / (hi - lo))
+  }
+
+  if (fmt.type === 'colorScale' && fmt.reverse) t = 1 - t
+  return t
 }
 
 /**
@@ -203,23 +330,42 @@ export function resolveCellFormat<TData = unknown>(
     if (value == null || value === '' || !Number.isFinite(n)) continue
 
     if (fmt.type === 'colorScale') {
-      const lo = fmt.minValue ?? stat?.min ?? n
-      const hi = fmt.maxValue ?? stat?.max ?? n
-      const t = hi === lo ? 0.5 : clamp01((n - lo) / (hi - lo))
-      out.background = colorScaleAt(fmt, t)
-      // The scale fills the whole cell, so keep the text legible against it.
-      const c = contrastText(out.background)
-      if (c) out.color = c
+      const t = domainT(fmt, n, row, stat)
+      if (t == null) continue
+      if (fmt.mode === 'alpha') {
+        const [alo, ahi] = fmt.alphaBounds ?? [0.05, 0.85]
+        out.background = rgba(fmt.base ?? '#2563eb', alo + (ahi - alo) * t)
+        // Translucent tint composites over the row bg; leave text color alone.
+      } else {
+        out.background = colorScaleAt(fmt, t)
+        // The scale fills the whole cell, so keep the text legible against it.
+        const c = contrastText(out.background)
+        if (c) out.color = c
+      }
+      if (fmt.tooltip === 'value') out.title = String(value)
+      else if (fmt.tooltip === 'percent') out.title = `${Math.round(t * 100)}%`
     } else if (fmt.type === 'dataBar') {
-      const lo = fmt.minValue ?? Math.min(0, stat?.min ?? 0)
-      const hi = fmt.maxValue ?? stat?.max ?? n
-      const span = hi - lo || 1
-      const percent = clamp01((n - lo) / span) * 100
+      let percent: number
+      if (fmt.compareColumn) {
+        const t = domainT(fmt, n, row, stat)
+        if (t == null) continue
+        percent = t * 100
+      } else if (fmt.bounds === 'percent') {
+        const t = domainT(fmt, n, row, stat)
+        if (t == null) continue
+        percent = t * 100
+      } else {
+        const lo = fmt.minValue ?? Math.min(0, stat?.min ?? 0)
+        const hi = fmt.maxValue ?? stat?.max ?? n
+        const span = hi - lo || 1
+        percent = clamp01((n - lo) / span) * 100
+      }
       const negative = n < 0
       out.dataBar = {
         percent,
         color: negative ? (fmt.negativeColor ?? '#ef4444') : fmt.color,
         fromRight: false,
+        gradient: fmt.gradient,
       }
       if (fmt.showValue === false) out.color = 'transparent'
     } else if (fmt.type === 'iconSet') {
@@ -231,9 +377,20 @@ export function resolveCellFormat<TData = unknown>(
   return out
 }
 
-/** Column ids that need a numeric min/max precomputed (colorScale/dataBar). */
+/**
+ * Whether any format needs a numeric min/max precomputed. Color-scale and
+ * data-bar formats do, EXCEPT when they derive their range from another column
+ * on the same row (`compareColumn`) - those read the row, not column stats.
+ */
+export function formatNeedsStats(f: ConditionalFormat<any>): boolean {
+  return (
+    (f.type === 'colorScale' || f.type === 'dataBar') &&
+    !('compareColumn' in f && f.compareColumn)
+  )
+}
+
 export function formatsNeedingStats(
   formats: ReadonlyArray<ConditionalFormat<any>>,
 ): boolean {
-  return formats.some((f) => f.type === 'colorScale' || f.type === 'dataBar')
+  return formats.some(formatNeedsStats)
 }

package/src/createCarousel.svelte.ts

@@ -0,0 +1,104 @@
+/**
+ * createCarousel - the HEADLESS core behind <SvCarousel>: slide navigation
+ * (with optional looping), autoplay that pauses on hover/focus and via a
+ * persistent stop toggle (WCAG 2.2.2), and rtl-aware arrow wiring - as
+ * prop-getters you spread onto your own markup. The component keeps only the
+ * visual track + swipe. Runes-based, like `createListbox`.
+ */
+import { type EditorDir } from './editor-contract'
+
+export type CarouselConfig = {
+  count: () => number
+  /** Active slide index (the component owns the state; core calls onChange). */
+  current: () => number
+  onChange?: (index: number) => void
+  loop?: () => boolean
+  /** Autoplay interval in ms; 0 = off. */
+  autoplay?: () => number
+  dir?: () => EditorDir | undefined
+}
+
+export function createCarousel(config: CarouselConfig) {
+  const count = () => config.count()
+  const current = () => config.current()
+  const loop = () => config.loop?.() ?? true
+  const rtl = () => config.dir?.() === 'rtl'
+
+  let paused = $state(false) // hover/focus
+  let userPaused = $state(false) // explicit stop toggle
+
+  function go(i: number) {
+    const n = count()
+    if (n === 0) return
+    const target = loop() ? ((i % n) + n) % n : Math.max(0, Math.min(i, n - 1))
+    config.onChange?.(target)
+  }
+  const next = () => go(current() + 1)
+  const prev = () => go(current() - 1)
+  const canGoPrev = () => loop() || current() > 0
+  const canGoNext = () => loop() || current() < count() - 1
+
+  // Autoplay, paused while hovered/focused or explicitly stopped (WCAG 2.2.2).
+  $effect(() => {
+    const ms = config.autoplay?.() ?? 0
+    if (!ms || paused || userPaused || count() < 2) return
+    const t = setInterval(() => next(), ms)
+    return () => clearInterval(t)
+  })
+
+  return {
+    get paused() { return paused },
+    get userPaused() { return userPaused },
+    rtl,
+    isActive: (i: number) => i === current(),
+    go,
+    next,
+    prev,
+    canGoPrev,
+    canGoNext,
+    /** Spread onto the carousel container. Pauses autoplay on hover/focus. */
+    rootProps: (ariaLabel = 'Carousel') => ({
+      role: 'group' as const,
+      'aria-roledescription': 'carousel',
+      'aria-label': ariaLabel,
+      onpointerenter: () => { paused = true },
+      onpointerleave: () => { paused = false },
+      onfocusin: () => { paused = true },
+      onfocusout: () => { paused = false },
+    }),
+    /** Spread onto each slide element. */
+    slideProps: (i: number) => ({
+      role: 'group' as const,
+      'aria-roledescription': 'slide',
+      'aria-label': `${i + 1} of ${count()}`,
+      'aria-hidden': i !== current(),
+      inert: i !== current(),
+    }),
+    /** The visually-leading (inline-start) arrow: logical prev in ltr, next in rtl. */
+    prevArrowProps: () => ({
+      'aria-label': rtl() ? 'Next slide' : 'Previous slide',
+      onclick: rtl() ? next : prev,
+      disabled: rtl() ? !canGoNext() : !canGoPrev(),
+    }),
+    /** The visually-trailing (inline-end) arrow: logical next in ltr, prev in rtl. */
+    nextArrowProps: () => ({
+      'aria-label': rtl() ? 'Previous slide' : 'Next slide',
+      onclick: rtl() ? prev : next,
+      disabled: rtl() ? !canGoPrev() : !canGoNext(),
+    }),
+    /** Spread onto a dot indicator. */
+    dotProps: (i: number) => ({
+      'aria-label': `Go to slide ${i + 1}`,
+      'aria-current': (i === current() ? 'true' : undefined) as 'true' | undefined,
+      onclick: () => go(i),
+    }),
+    /** Spread onto the persistent play/pause toggle (render only when autoplay > 0). */
+    playPauseProps: () => ({
+      'aria-label': userPaused ? 'Play autoplay' : 'Pause autoplay',
+      'aria-pressed': userPaused,
+      onclick: () => { userPaused = !userPaused },
+    }),
+  }
+}
+
+export type Carousel = ReturnType<typeof createCarousel>

package/src/createCommand.svelte.ts

@@ -0,0 +1,125 @@
+/**
+ * createCommand - the HEADLESS core behind <SvCommand> (the ⌘K palette): the
+ * fuzzy-filtered result list, roving active index, run/close, the global toggle
+ * hotkey, and the WAI-ARIA combobox wiring (activedescendant) - as prop-getters
+ * you spread onto your own input/list/option markup. The overlay lifecycle
+ * (focus-trap + scroll-lock + dismissal) is a separate concern; pair this with
+ * `createOverlay`. Runes-based, like `createListbox`.
+ */
+import type { CommandItem } from './ui-app.types'
+import { fuzzyScore } from './fuzzy'
+import { nextEditorId } from './editor-contract'
+
+export type CommandConfig = {
+  commands: () => ReadonlyArray<CommandItem>
+  /** Whether the palette is open (used to reset query/active on open). */
+  open: () => boolean
+  onRun?: (cmd: CommandItem) => void
+  /** Close the palette (a command ran, or requested by the input). */
+  onClose?: () => void
+  /** Toggle open/closed - fired by the global hotkey. */
+  onToggleOpen?: () => void
+  /** Global toggle hotkey (Cmd/Ctrl + key). `false` disables it. Default 'mod+k'. */
+  hotkey?: () => 'mod+k' | 'mod+p' | false
+  /** DOM hook to scroll the newly-active option into view. */
+  scrollActiveIntoView?: (index: number) => void
+}
+
+export function createCommand(config: CommandConfig) {
+  const id = nextEditorId('sv-cmd')
+  const listId = `${id}-list`
+  const optionId = (i: number) => `${id}-opt-${i}`
+
+  let query = $state('')
+  let active = $state(0)
+
+  const results = $derived.by(() => {
+    const q = query.trim()
+    const list = config.commands().filter((c) => !c.disabled)
+    if (!q) return list
+    return list
+      .map((c) => ({ c, s: fuzzyScore(`${c.label} ${c.keywords ?? ''} ${c.group ?? ''}`, q) }))
+      .filter((x) => x.s !== null)
+      .sort((a, b) => (b.s as number) - (a.s as number))
+      .map((x) => x.c)
+  })
+
+  function run(cmd: CommandItem | undefined) {
+    if (!cmd || cmd.disabled) return
+    config.onClose?.()
+    config.onRun?.(cmd)
+    cmd.onRun?.()
+  }
+  function move(delta: number) {
+    const n = results.length
+    if (!n) return
+    active = (active + delta + n) % n
+    config.scrollActiveIntoView?.(active)
+  }
+  function onInputKeydown(e: KeyboardEvent) {
+    if (e.key === 'ArrowDown') { e.preventDefault(); move(1) }
+    else if (e.key === 'ArrowUp') { e.preventDefault(); move(-1) }
+    else if (e.key === 'Enter') { e.preventDefault(); run(results[active]) }
+    // Escape + outside-click are owned by the overlay/dismissable layer.
+  }
+
+  // Reset the active row as the query changes.
+  $effect(() => { void query; active = 0 })
+  // Reset query + active each time the palette opens.
+  $effect(() => { if (config.open()) { query = ''; active = 0 } })
+  // Global toggle hotkey.
+  $effect(() => {
+    const hk = config.hotkey?.() ?? 'mod+k'
+    if (!hk) return
+    const key = hk === 'mod+p' ? 'p' : 'k'
+    const onKey = (e: KeyboardEvent) => {
+      if ((e.metaKey || e.ctrlKey) && e.key.toLowerCase() === key) {
+        e.preventDefault()
+        config.onToggleOpen?.()
+      }
+    }
+    window.addEventListener('keydown', onKey)
+    return () => window.removeEventListener('keydown', onKey)
+  })
+
+  return {
+    get query() { return query },
+    set query(v: string) { query = v },
+    get active() { return active },
+    get results() { return results },
+    isActive: (i: number) => i === active,
+    move,
+    run,
+    /** Arrow/Enter handler - attach to the panel (catches events bubbled from the
+     *  input) so keys work whether dispatched on the input or the dialog. */
+    onKeydown: onInputKeydown,
+    /** Id of the list element (for aria-controls). */
+    listId,
+    /** Id of the option at `i` (for aria-activedescendant + item id). */
+    optionId,
+    /** Spread onto the search `<input>`. */
+    inputProps: () => ({
+      role: 'combobox' as const,
+      'aria-expanded': true as const,
+      'aria-controls': listId,
+      'aria-activedescendant': results[active] ? optionId(active) : undefined,
+      value: query,
+      oninput: (e: Event) => { query = (e.currentTarget as HTMLInputElement).value },
+      // Arrow/Enter is handled on the panel (see `onKeydown`) via bubbling, so it
+      // works for both input-dispatched and panel-dispatched key events.
+    }),
+    /** Spread onto the `<ul>` list. */
+    listProps: () => ({ id: listId, role: 'listbox' as const }),
+    /** Spread onto the option element at `i`. */
+    optionProps: (i: number) => ({
+      id: optionId(i),
+      'data-idx': i,
+      role: 'option' as const,
+      'aria-selected': i === active,
+      onpointermove: () => { active = i },
+      onclick: () => run(results[i]),
+    }),
+  }
+}
+
+export type Command = ReturnType<typeof createCommand>