@talelk/newui-data 0.0.0-stage → 1.1.0

package/src/dashboard.test.tsx

@@ -0,0 +1,285 @@
+import { render, screen } from '@solidjs/testing-library'
+import { createRoot, type JSX } from 'solid-js'
+import { describe, expect, it, vi } from 'vitest'
+import {
+  createDashboardState,
+  DashboardProvider,
+  type DashboardState,
+  type DashboardStateOptions,
+  useDashboardState,
+} from './dashboard'
+import type { UrlStateAdapter } from './url-state'
+
+/** A fixed clock: Sunday 15 March 2026, 14:30 local — Q1, a leap year. */
+const NOW = new Date(2026, 2, 15, 14, 30)
+
+function setup(options: DashboardStateOptions = {}) {
+  let dispose!: () => void
+  let state!: DashboardState
+  createRoot((d) => {
+    dispose = d
+    state = createDashboardState({ now: () => NOW, ...options })
+  })
+  return { state, dispose }
+}
+
+function adapter(
+  search = '',
+): UrlStateAdapter & { last: () => URLSearchParams } {
+  let last = new URLSearchParams(search)
+  return {
+    search: () => search,
+    replace: vi.fn((params: URLSearchParams) => {
+      last = params
+    }),
+    last: () => last,
+  }
+}
+
+/** Let queued microtasks (the per-tick `replace`) run. */
+async function flushMicrotasks(): Promise<void> {
+  await Promise.resolve()
+  await Promise.resolve()
+}
+
+const endOfToday = new Date(2026, 2, 15, 23, 59, 59, 999)
+
+describe('createDashboardState — time range', () => {
+  it('defaults to the current 7 days, ending at today', () => {
+    const { state, dispose } = setup()
+    const range = state.timeRange()
+    expect(range.preset).toBe('7d')
+    expect(range.from).toEqual(new Date(2026, 2, 9))
+    expect(range.to).toEqual(endOfToday)
+    dispose()
+  })
+
+  it('computes 30d, qtd and ytd from the same clock', () => {
+    const { state, dispose } = setup()
+
+    state.setTimeRange('30d')
+    expect(state.timeRange()).toEqual({
+      preset: '30d',
+      from: new Date(2026, 1, 14),
+      to: endOfToday,
+    })
+
+    state.setTimeRange('qtd')
+    expect(state.timeRange()).toEqual({
+      preset: 'qtd',
+      from: new Date(2026, 0, 1),
+      to: endOfToday,
+    })
+
+    state.setTimeRange('ytd')
+    expect(state.timeRange()).toEqual({
+      preset: 'ytd',
+      from: new Date(2026, 0, 1),
+      to: endOfToday,
+    })
+    dispose()
+  })
+
+  it('floors qtd to the quarter, not the year', () => {
+    let dispose!: () => void
+    let state!: DashboardState
+    createRoot((d) => {
+      dispose = d
+      state = createDashboardState({
+        now: () => new Date(2026, 6, 11, 9, 0),
+      })
+    })
+    state.setTimeRange('qtd')
+    expect(state.timeRange().from).toEqual(new Date(2026, 6, 1))
+    dispose()
+  })
+
+  it('marks set dates as custom, and a preset as not', () => {
+    const { state, dispose } = setup()
+    state.setTimeRange({
+      from: new Date(2026, 4, 1),
+      to: new Date(2026, 4, 8),
+    })
+    expect(state.timeRange()).toEqual({
+      preset: 'custom',
+      from: new Date(2026, 4, 1),
+      to: new Date(2026, 4, 8),
+    })
+
+    state.setTimeRange('30d')
+    expect(state.timeRange().preset).toBe('30d')
+    dispose()
+  })
+
+  it('keeps the other bound when a custom range sets only one', () => {
+    const { state, dispose } = setup()
+    const to = state.timeRange().to
+    state.setTimeRange({ from: new Date(2026, 1, 1) })
+    expect(state.timeRange()).toEqual({
+      preset: 'custom',
+      from: new Date(2026, 1, 1),
+      to,
+    })
+    dispose()
+  })
+
+  it('ignores an unknown preset', () => {
+    const { state, dispose } = setup()
+    const warn = vi.spyOn(console, 'warn').mockImplementation(() => {})
+    state.setTimeRange('fortnight' as '7d')
+    expect(state.timeRange().preset).toBe('7d')
+    expect(warn).toHaveBeenCalled()
+    warn.mockRestore()
+    dispose()
+  })
+})
+
+describe('createDashboardState — cross filter', () => {
+  it('holds one slot: a new value replaces, the same value clears', () => {
+    const { state, dispose } = setup()
+    expect(state.cross()).toBeNull()
+
+    state.setCross({ column: 'region', value: 'EMEA' })
+    expect(state.cross()).toEqual({ column: 'region', value: 'EMEA' })
+
+    state.setCross({ column: 'region', value: 'APAC' })
+    expect(state.cross()).toEqual({ column: 'region', value: 'APAC' })
+
+    // The same click twice is a toggle, not a second filter.
+    state.setCross({ column: 'region', value: 'APAC' })
+    expect(state.cross()).toBeNull()
+
+    state.setCross({ column: 'stage', value: 2 })
+    state.setCross(null)
+    expect(state.cross()).toBeNull()
+    dispose()
+  })
+})
+
+describe('createDashboardState — filters', () => {
+  it('reads declared filters, keeps defaults, and takes ad hoc keys', () => {
+    const { state, dispose } = setup({
+      filters: { region: 'EMEA', period: undefined },
+    })
+    expect(state.filters()).toEqual({ region: 'EMEA', period: undefined })
+
+    state.setFilter('period', 30)
+    expect(state.filters()['period']).toBe(30)
+
+    // An undeclared key still works and still serializes.
+    state.setFilter('source', 'web')
+    expect(state.filters()['source']).toBe('web')
+    expect(state.params().get('f:source')).toBe('web')
+
+    // `undefined` returns a declared key to its default, not to nothing.
+    state.setFilter('region', undefined)
+    expect(state.filters()['region']).toBe('EMEA')
+    dispose()
+  })
+
+  it('applies setFilters as a merge', () => {
+    const { state, dispose } = setup({ filters: { region: 'EMEA' } })
+    state.setFilters({ region: 'APAC', stage: 'won' })
+    expect(state.filters()).toEqual({ region: 'APAC', stage: 'won' })
+    dispose()
+  })
+})
+
+describe('createDashboardState — URL sync', () => {
+  it('deep-links: the URL seeds the state on creation', () => {
+    const { state, dispose } = setup({
+      adapter: adapter(
+        '?range=30d&f:region=EMEA&cross=%7B%22column%22%3A%22region%22%2C%22value%22%3A%22EMEA%22%7D',
+      ),
+      filters: { region: '' },
+    })
+    expect(state.timeRange().preset).toBe('30d')
+    expect(state.filters()['region']).toBe('EMEA')
+    expect(state.cross()).toEqual({ column: 'region', value: 'EMEA' })
+    dispose()
+  })
+
+  it('writes state back and prunes what is only the default', async () => {
+    const bridge = adapter()
+    const { state, dispose } = setup({
+      adapter: bridge,
+      filters: { region: '' },
+    })
+
+    state.setTimeRange('30d')
+    state.setFilter('region', 'EMEA')
+    state.setCross({ column: 'stage', value: 'won' })
+    await flushMicrotasks()
+
+    const params = bridge.last()
+    expect(params.get('range')).toBe('30d')
+    expect(params.get('f:region')).toBe('EMEA')
+    expect(JSON.parse(params.get('cross') ?? '')).toEqual({
+      column: 'stage',
+      value: 'won',
+    })
+
+    // Back to the default preset: the param goes away rather than say nothing.
+    state.setTimeRange('7d')
+    await flushMicrotasks()
+    expect(bridge.last().get('range')).toBeNull()
+    dispose()
+  })
+
+  it('clears the custom dates when a preset returns', async () => {
+    const bridge = adapter()
+    const { state, dispose } = setup({ adapter: bridge })
+
+    state.setTimeRange({ from: new Date(2026, 3, 1), to: new Date(2026, 3, 5) })
+    await flushMicrotasks()
+    expect(bridge.last().get('from')).toBe(new Date(2026, 3, 1).toISOString())
+
+    state.setTimeRange('qtd')
+    await flushMicrotasks()
+    expect(bridge.last().get('from')).toBeNull()
+    expect(bridge.last().get('to')).toBeNull()
+    dispose()
+  })
+
+  it('touches no URL when sync is off, but still serializes params', async () => {
+    const bridge = adapter()
+    const { state, dispose } = setup({ adapter: bridge, sync: false })
+    state.setTimeRange('30d')
+    await flushMicrotasks()
+    expect(bridge.replace).not.toHaveBeenCalled()
+    expect(state.params().get('range')).toBe('30d')
+    dispose()
+  })
+
+  it('treats a custom range whose dates no longer parse as a reset', () => {
+    const { state, dispose } = setup({
+      adapter: adapter('?range=custom&from=not-a-date&to=also-no'),
+    })
+    expect(state.timeRange().preset).toBe('custom')
+    expect(state.timeRange().from).toEqual(new Date(2026, 2, 9))
+    dispose()
+  })
+})
+
+describe('useDashboardState', () => {
+  function Widget(): JSX.Element {
+    const dashboard = useDashboardState()
+    return <p>{dashboard.timeRange().preset}</p>
+  }
+
+  it('reads the state published by the provider', () => {
+    const { state, dispose } = setup()
+    state.setTimeRange('ytd')
+    render(() => (
+      <DashboardProvider state={state}>
+        <Widget />
+      </DashboardProvider>
+    ))
+    expect(screen.getByText('ytd')).toBeTruthy()
+    dispose()
+  })
+
+  it('names the provider when used outside one', () => {
+    expect(() => render(() => <Widget />)).toThrow(/DashboardProvider/)
+  })
+})

package/src/dashboard.tsx

@@ -0,0 +1,381 @@
+import {
+  type Accessor,
+  createContext,
+  createMemo,
+  createSignal,
+  type JSX,
+  untrack,
+  useContext,
+} from 'solid-js'
+import {
+  defaultsFor,
+  encodeValue,
+  pruneDefaults,
+  withPruning,
+} from './url-serialize'
+import {
+  createUrlState,
+  type UrlStateAdapter,
+  type UrlStateValue,
+} from './url-state'
+
+/**
+ * The connective tissue of an analytics dashboard: one shared time range,
+ * one shared filter record, and one cross-filter slot that every widget
+ * reads and writes.
+ *
+ * `createDashboardState` owns the signals; `DashboardProvider` and
+ * `useDashboardState` keep charts, KPI cards and tables from prop-drilling
+ * them through the widget grid. What is reproducible by link — the preset,
+ * the custom dates, the cross-filter, every declared filter — round-trips
+ * through `createUrlState` when the app supplies an adapter, and stays a
+ * plain signal without one, so tests and SSR stay clean.
+ */
+
+/** The named ranges the kit ships. `'custom'` means the user set the dates. */
+export type TimeRangePreset = '7d' | '30d' | 'qtd' | 'ytd' | 'custom'
+
+/** The shared time window every widget filters by. */
+export interface TimeRange {
+  /** Which preset produced this range; `'custom'` means set dates. */
+  preset: TimeRangePreset
+  /** Inclusive start — local midnight of the first day. */
+  from: Date
+  /** Inclusive end — local end-of-day of the last day. */
+  to: Date
+}
+
+/** The one widget click other widgets filter by. */
+export interface CrossFilter {
+  /** The column the click came from. */
+  column: string
+  /** The clicked value. */
+  value: string | number | boolean
+}
+
+/** Options for {@link createDashboardState}. */
+export interface DashboardStateOptions {
+  /** Initial range. Defaults to the current 7 days. */
+  timeRange?: { preset?: TimeRangePreset; from?: Date; to?: Date }
+  /**
+   * The shared filter record. Declared keys get their own URL params
+   * (`f:<key>`); the empty string means unset.
+   */
+  filters?: Record<string, UrlStateValue | undefined>
+  /** Router bridge. Present (and `sync` not false), state round-trips to the URL. */
+  adapter?: UrlStateAdapter
+  /** Turn URL writing off while still reading the adapter for deep links. */
+  sync?: boolean
+  /** Clock seam for tests. Defaults to `() => new Date()`. */
+  now?: () => Date
+}
+
+/** The handle {@link createDashboardState} returns. */
+export interface DashboardState {
+  /** The current window. Preset ranges are computed from `now()` on read. */
+  timeRange(): TimeRange
+  /**
+   * `'7d' | '30d' | 'qtd' | 'ytd'` recomputes the window; a partial with
+   * dates marks the range `'custom'`. An unknown preset is ignored.
+   */
+  setTimeRange(next: TimeRangePreset | Partial<TimeRange>): void
+  /** The shared filters, declared and ad hoc. Unset keys read `undefined`. */
+  filters(): Record<string, UrlStateValue | undefined>
+  /** One filter. `undefined` returns it to its declared default. */
+  setFilter(key: string, value: UrlStateValue | undefined): void
+  /** Apply several filters at once — a merge, not a replacement. */
+  setFilters(next: Record<string, UrlStateValue | undefined>): void
+  /** The active cross-filter, or `null`. One slot, one value. */
+  cross(): CrossFilter | null
+  /**
+   * Set the cross-filter, replacing whatever held the slot. Setting the same
+   * column and value again clears it — the chip the widget's own click
+   * toggles — and `null` clears it outright.
+   */
+  setCross(next: CrossFilter | null): void
+  /** The params this state serializes to right now (for "copy link"). */
+  params(): URLSearchParams
+}
+
+const PRESET_NAMES: readonly TimeRangePreset[] = [
+  '7d',
+  '30d',
+  'qtd',
+  'ytd',
+  'custom',
+]
+
+function startOfDay(date: Date): Date {
+  return new Date(date.getFullYear(), date.getMonth(), date.getDate())
+}
+
+function endOfDay(date: Date): Date {
+  return new Date(
+    date.getFullYear(),
+    date.getMonth(),
+    date.getDate(),
+    23,
+    59,
+    59,
+    999,
+  )
+}
+
+/** The window a named preset stands for, ending with today. */
+function presetRange(
+  preset: Exclude<TimeRangePreset, 'custom'>,
+  now: Date,
+): { from: Date; to: Date } {
+  const to = endOfDay(now)
+  switch (preset) {
+    case '7d':
+      return {
+        from: startOfDay(
+          new Date(now.getFullYear(), now.getMonth(), now.getDate() - 6),
+        ),
+        to,
+      }
+    case '30d':
+      return {
+        from: startOfDay(
+          new Date(now.getFullYear(), now.getMonth(), now.getDate() - 29),
+        ),
+        to,
+      }
+    case 'qtd':
+      return {
+        from: startOfDay(
+          new Date(now.getFullYear(), Math.floor(now.getMonth() / 3) * 3, 1),
+        ),
+        to,
+      }
+    case 'ytd':
+      return { from: startOfDay(new Date(now.getFullYear(), 0, 1)), to }
+  }
+}
+
+function isPreset(value: unknown): value is TimeRangePreset {
+  return (
+    typeof value === 'string' &&
+    (PRESET_NAMES as readonly string[]).includes(value)
+  )
+}
+
+function isCrossFilter(value: unknown): value is CrossFilter {
+  if (value === null || typeof value !== 'object') return false
+  const candidate = value as Partial<CrossFilter>
+  return (
+    typeof candidate.column === 'string' &&
+    (typeof candidate.value === 'string' ||
+      typeof candidate.value === 'number' ||
+      typeof candidate.value === 'boolean')
+  )
+}
+
+/**
+ * Create the shared dashboard state. Call it once, at the root of the
+ * dashboard, and hand the result to `DashboardProvider`; widgets read it
+ * through `useDashboardState`.
+ */
+export function createDashboardState(
+  options: DashboardStateOptions = {},
+): DashboardState {
+  const now = options.now ?? (() => new Date())
+  const sync = options.sync ?? options.adapter !== undefined
+  const adapter = sync ? options.adapter : undefined
+
+  // A `'custom'` seed without both dates is not a range; fall back to 7d
+  // rather than invent one.
+  const seededFrom = options.timeRange?.from
+  const seededTo = options.timeRange?.to
+  const seededCustom =
+    options.timeRange?.preset === 'custom' &&
+    seededFrom !== undefined &&
+    seededTo !== undefined
+  const seedPreset: TimeRangePreset =
+    options.timeRange?.preset === 'custom' && !seededCustom
+      ? '7d'
+      : (options.timeRange?.preset ?? '7d')
+
+  const declared = Object.keys(options.filters ?? {})
+  const urlInitial: Record<string, UrlStateValue> = {
+    range: seedPreset,
+    from: seededCustom && seededFrom ? seededFrom.toISOString() : '',
+    to: seededCustom && seededTo ? seededTo.toISOString() : '',
+    cross: '',
+  }
+  for (const key of declared) {
+    urlInitial[`f:${key}`] = options.filters?.[key] ?? ''
+  }
+  const defaults = defaultsFor(urlInitial)
+
+  const url = createUrlState(urlInitial, {
+    ...(adapter ? { adapter: withPruning(adapter, defaults) } : {}),
+  })
+
+  // Reading `createUrlState`'s record by key runs into the
+  // `noUncheckedIndexedAccess` wall; this keeps every accessor honest.
+  const read = (key: string): UrlStateValue => {
+    const accessor = (
+      url as unknown as Record<string, Accessor<UrlStateValue> | undefined>
+    )[key]
+    return accessor ? accessor() : ''
+  }
+
+  // Undeclared filter keys arrive at runtime (a cross-filter writing a new
+  // column, say). They live in one signal of their own and still serialize.
+  const [extraFilters, setExtraFilters] = createSignal<
+    Record<string, UrlStateValue>
+  >({})
+
+  const timeRange = createMemo<TimeRange>(() => {
+    const preset = read('range')
+    if (isPreset(preset) && preset !== 'custom') {
+      return { preset, ...presetRange(preset, now()) }
+    }
+    const from = Date.parse(String(read('from')))
+    const to = Date.parse(String(read('to')))
+    if (!Number.isNaN(from) && !Number.isNaN(to)) {
+      return { preset: 'custom', from: new Date(from), to: new Date(to) }
+    }
+    // A custom range whose dates no longer parse is a stale link: reset the
+    // window, keep the label, do not crash.
+    return { preset: 'custom', ...presetRange('7d', now()) }
+  })
+
+  function setTimeRange(next: TimeRangePreset | Partial<TimeRange>): void {
+    if (typeof next === 'string') {
+      if (!isPreset(next)) {
+        console.warn(
+          `[newui-data] createDashboardState: "${next}" is not a time-range preset; ignored.`,
+        )
+        return
+      }
+      url.set('range', next)
+      if (next !== 'custom') {
+        url.set('from', undefined)
+        url.set('to', undefined)
+      }
+      return
+    }
+    const preset = next.preset ?? 'custom'
+    if (isPreset(preset) && preset !== 'custom') {
+      url.set('range', preset)
+      url.set('from', undefined)
+      url.set('to', undefined)
+      return
+    }
+    const current = untrack(timeRange)
+    const from = next.from ?? current.from
+    const to = next.to ?? current.to
+    url.set('range', 'custom')
+    url.set('from', from.toISOString())
+    url.set('to', to.toISOString())
+  }
+
+  const cross = createMemo<CrossFilter | null>(() => {
+    const raw = String(read('cross'))
+    if (raw === '') return null
+    try {
+      const parsed = JSON.parse(raw) as unknown
+      return isCrossFilter(parsed) ? parsed : null
+    } catch {
+      return null
+    }
+  })
+
+  function setCross(next: CrossFilter | null): void {
+    if (next === null) {
+      url.set('cross', undefined)
+      return
+    }
+    const current = untrack(cross)
+    // One slot: the same click twice is a toggle, not a second filter.
+    if (
+      current !== null &&
+      current.column === next.column &&
+      current.value === next.value
+    ) {
+      url.set('cross', undefined)
+      return
+    }
+    url.set('cross', JSON.stringify(next))
+  }
+
+  function filterValue(key: string): UrlStateValue | undefined {
+    const raw = declared.includes(key)
+      ? read(`f:${key}`)
+      : (extraFilters()[key] ?? '')
+    return raw === '' ? undefined : raw
+  }
+
+  const filters = createMemo(() => {
+    const out: Record<string, UrlStateValue | undefined> = {}
+    for (const key of declared) out[key] = filterValue(key)
+    for (const key of Object.keys(extraFilters())) {
+      if (!declared.includes(key)) out[key] = filterValue(key)
+    }
+    return out
+  })
+
+  function setFilter(key: string, value: UrlStateValue | undefined): void {
+    if (declared.includes(key)) {
+      url.set(`f:${key}`, value)
+      return
+    }
+    setExtraFilters((extras) => ({ ...extras, [key]: value ?? '' }))
+  }
+
+  function setFilters(next: Record<string, UrlStateValue | undefined>): void {
+    for (const [key, value] of Object.entries(next)) setFilter(key, value)
+  }
+
+  function params(): URLSearchParams {
+    const out = url.params()
+    for (const [key, value] of Object.entries(extraFilters())) {
+      if (value === undefined || value === '') out.delete(`f:${key}`)
+      else out.set(`f:${key}`, encodeValue(value))
+    }
+    return pruneDefaults(out, defaults)
+  }
+
+  return {
+    timeRange,
+    setTimeRange,
+    filters,
+    setFilter,
+    setFilters,
+    cross,
+    setCross,
+    params,
+  }
+}
+
+const DashboardContext = createContext<Accessor<DashboardState>>()
+
+/**
+ * Publish one `createDashboardState` to the widget grid, so a chart three
+ * levels down reads the same time range without a prop on every card.
+ */
+export function DashboardProvider(props: {
+  state: DashboardState
+  children: JSX.Element
+}): JSX.Element {
+  const state = createMemo(() => props.state)
+  return (
+    <DashboardContext.Provider value={state}>
+      {props.children}
+    </DashboardContext.Provider>
+  )
+}
+
+/** The dashboard state published by the enclosing `DashboardProvider`. */
+export function useDashboardState(): DashboardState {
+  const state = useContext(DashboardContext)
+  if (!state) {
+    throw new Error(
+      'useDashboardState must be used within <DashboardProvider> (create the state with createDashboardState)',
+    )
+  }
+  return state()
+}

package/src/download.test.ts

@@ -0,0 +1,14 @@
+import { describe, expect, it } from 'vitest'
+import { csvText } from './download'
+
+describe('download', () => {
+  it('quotes every cell and doubles inner quotes', () => {
+    expect(
+      csvText([
+        ['Name', 'Note'],
+        ['Acme, Inc', 'Said "yes"'],
+        ['Globex', 42],
+      ]),
+    ).toBe('"Name","Note"\r\n"Acme, Inc","Said ""yes"""\r\n"Globex","42"')
+  })
+})