basalt-ui 1.27.0 → 1.28.0

package/src/router-tanstack/multi-search-param-store.test.ts

@@ -1,124 +0,0 @@
-/**
- * The deprecated multi wrapper's contract, unchanged across the rewrite onto
- * `createSearchStore` — plus the storage path two of these tests used to claim was unreachable.
- *
- * `bun test` runs under happy-dom (root `bunfig.toml` preload), so `localStorage` has always been
- * REAL here: "no localStorage in this environment" was false, and it meant the fallback-to-storage
- * half of `validateSearch` — the entire reason the store exists — was asserted only in the
- * single-value store's tests (D12).
- */
-import { beforeEach, describe, expect, test } from 'bun:test'
-import { createMultiSearchParamStore } from './multi-search-param-store'
-
-const VALUES = ['api', 'design', 'guide'] as const
-
-/** Writes the wrapper's single-value envelope — the layout it has used since 1.0.0. */
-function persist(key: string, value: readonly string[], version = 1): void {
-  localStorage.setItem(`basalt:${key}`, JSON.stringify({ v: version, value }))
-}
-
-beforeEach(() => {
-  localStorage.clear()
-})
-
-describe('createMultiSearchParamStore', () => {
-  describe('validateSearch', () => {
-    test('URL value wins when it decodes to a non-empty array', () => {
-      const store = createMultiSearchParamStore({ key: 'tags-a', param: 'tags', values: VALUES })
-      expect(store.validateSearch({ tags: ['api'] })).toEqual({ tags: ['api'] })
-    })
-
-    test('an allowlist rejects unknown/tampered values', () => {
-      const store = createMultiSearchParamStore({ key: 'tags-b', param: 'tags', values: VALUES })
-      expect(store.validateSearch({ tags: ['api', 'not-a-real-tag'] })).toEqual({ tags: ['api'] })
-    })
-
-    test('dedupes repeated entries', () => {
-      const store = createMultiSearchParamStore({ key: 'tags-c', param: 'tags', values: VALUES })
-      expect(store.validateSearch({ tags: ['api', 'api', 'design'] })).toEqual({
-        tags: ['api', 'design'],
-      })
-    })
-
-    test('canonically re-orders into the values declaration order', () => {
-      const store = createMultiSearchParamStore({ key: 'tags-d', param: 'tags', values: VALUES })
-      const a = store.validateSearch({ tags: ['design', 'api'] })
-      const b = store.validateSearch({ tags: ['api', 'design'] })
-      expect(a).toEqual(b)
-      expect(a.tags).toEqual(['api', 'design'])
-    })
-
-    test('a non-array URL value falls through to storage, then to the fallback', () => {
-      const store = createMultiSearchParamStore({ key: 'tags-e', param: 'tags', values: VALUES })
-      expect(store.validateSearch({ tags: 'api' })).toEqual({ tags: [] })
-      expect(store.validateSearch({})).toEqual({ tags: [] })
-
-      persist('tags-e', ['guide', 'api'])
-      // Storage is read, and normalized on the way out like any other source.
-      expect(store.validateSearch({ tags: 'api' })).toEqual({ tags: ['api', 'guide'] })
-      expect(store.validateSearch({})).toEqual({ tags: ['api', 'guide'] })
-      // A valid URL array still wins over it.
-      expect(store.validateSearch({ tags: ['design'] })).toEqual({ tags: ['design'] })
-    })
-
-    test('an empty URL array falls through to the fallback', () => {
-      const store = createMultiSearchParamStore({
-        key: 'tags-f',
-        param: 'tags',
-        values: VALUES,
-        fallback: ['guide'],
-      })
-      expect(store.validateSearch({ tags: [] })).toEqual({ tags: ['guide'] })
-    })
-  })
-
-  describe('readStored', () => {
-    test('returns null when nothing is persisted', () => {
-      const store = createMultiSearchParamStore({ key: 'tags-g', param: 'tags', values: VALUES })
-      expect(store.readStored()).toBeNull()
-    })
-
-    test('returns the normalized stored selection, and null for a stale envelope version', () => {
-      const store = createMultiSearchParamStore({ key: 'tags-h', param: 'tags', values: VALUES })
-      persist('tags-h', ['guide', 'nope', 'api'])
-      expect(store.readStored()).toEqual(['api', 'guide'])
-
-      const versioned = createMultiSearchParamStore({
-        key: 'tags-i',
-        param: 'tags',
-        values: VALUES,
-        version: 1,
-      })
-      persist('tags-i', ['api'], 2)
-      expect(versioned.readStored()).toBeNull()
-    })
-
-    test('a stored EMPTY selection reads back as empty — a cleared filter stays cleared', () => {
-      // `{ v: 1, value: [] }` is exactly what `useStore()`'s setter writes when a user clears every
-      // filter. The empty-array-means-absent rule is a URL rule; applying it to storage too would
-      // resurrect the fallback on upgrade, which is not what "byte-compatible" means.
-      const store = createMultiSearchParamStore({
-        key: 'tags-empty',
-        param: 'tags',
-        values: VALUES,
-        fallback: ['guide'],
-      })
-      persist('tags-empty', [])
-
-      expect(store.readStored()).toEqual([])
-      expect(store.validateSearch({})).toEqual({ tags: [] })
-      expect(store.linkSearch()).toEqual({ tags: [] })
-      // …while an empty URL array still falls through to storage, as it always has.
-      persist('tags-empty', ['api'])
-      expect(store.validateSearch({ tags: [] })).toEqual({ tags: ['api'] })
-    })
-
-    test('linkSearch carries the stored selection at CALL time', () => {
-      const store = createMultiSearchParamStore({ key: 'tags-j', param: 'tags', values: VALUES })
-      expect(store.linkSearch()).toEqual({ tags: [] })
-
-      persist('tags-j', ['design'])
-      expect(store.linkSearch()).toEqual({ tags: ['design'] })
-    })
-  })
-})

package/src/router-tanstack/nav.test.ts

@@ -1,111 +0,0 @@
-import { describe, expect, test } from 'bun:test'
-import { defineNav, flattenNav, navGroup, navTarget } from './nav'
-
-/**
- * The definition below is deliberately built with the real builders (not object literals) so the
- * runtime-identity assertions below prove the builders are erased at runtime — every bit of value
- * they add is compile-time. The type-level half of the contract lives in the playground's
- * `nav.type-guard.ts` fixture, which is where a registered router exists to validate `to` against.
- */
-const NAV = defineNav({
-  groups: [
-    navGroup({ id: 'main', label: 'Main' }, [
-      { id: 'dash', label: 'Dashboard', short: 'Home', mobile: 'tab', link: { to: '/dashboard' } },
-      {
-        id: 'reports',
-        label: 'Reports',
-        link: { to: '/reports' },
-        children: [
-          { id: 'reports-daily', label: 'Daily', link: { to: '/reports/daily' } },
-          { id: 'reports-weekly', label: 'Weekly', link: { to: '/reports/weekly' } },
-        ],
-      },
-    ]),
-    navGroup({ id: 'system', label: 'System', collapsible: true }, [
-      { id: 'usage', label: 'Usage', disabled: true, link: { to: '/usage', search: { r: '30d' } } },
-    ]),
-  ],
-})
-
-describe('defineNav / navGroup', () => {
-  test('defineNav is runtime identity — it returns the very object it was given', () => {
-    const config = { groups: [] } as const
-    expect(defineNav(config)).toBe(config)
-  })
-
-  test('navGroup merges meta and items into one plain object, preserving item order', () => {
-    const group = navGroup({ id: 'g', label: 'G', collapsible: true }, [
-      { id: 'a', label: 'A', link: { to: '/a' } },
-      { id: 'b', label: 'B', link: { to: '/b' } },
-    ])
-    expect(group).toEqual({
-      id: 'g',
-      label: 'G',
-      collapsible: true,
-      items: [
-        { id: 'a', label: 'A', link: { to: '/a' } },
-        { id: 'b', label: 'B', link: { to: '/b' } },
-      ],
-    })
-  })
-
-  test('navGroup does not mutate the meta object it was handed', () => {
-    const meta = { id: 'g', label: 'G' }
-    navGroup(meta, [{ id: 'a', label: 'A', link: { to: '/a' } }])
-    expect(meta).toEqual({ id: 'g', label: 'G' })
-  })
-})
-
-describe('flattenNav', () => {
-  test('walks depth-first — parent immediately before its own children', () => {
-    expect(flattenNav(NAV).map((d) => d.id)).toEqual([
-      'dash',
-      'reports',
-      'reports-daily',
-      'reports-weekly',
-      'usage',
-    ])
-  })
-
-  test('tags every destination — including nested children — with its declaring group', () => {
-    const byId = new Map(flattenNav(NAV).map((d) => [d.id, d]))
-    expect(byId.get('dash')).toMatchObject({ groupId: 'main', groupLabel: 'Main' })
-    expect(byId.get('reports-weekly')).toMatchObject({ groupId: 'main', groupLabel: 'Main' })
-    expect(byId.get('usage')).toMatchObject({ groupId: 'system', groupLabel: 'System' })
-  })
-
-  test('carries the authored metadata through untouched', () => {
-    const dash = flattenNav(NAV)[0]
-    expect(dash).toMatchObject({
-      label: 'Dashboard',
-      short: 'Home',
-      mobile: 'tab',
-      link: { to: '/dashboard' },
-    })
-  })
-
-  test('an empty definition flattens to an empty list', () => {
-    expect(flattenNav({ groups: [] })).toEqual([])
-  })
-})
-
-describe('navTarget', () => {
-  test('returns the destination link options by id', () => {
-    expect(navTarget(NAV, 'dash')).toEqual({ to: '/dashboard' })
-    expect(navTarget(NAV, 'usage')).toEqual({ to: '/usage', search: { r: '30d' } })
-  })
-
-  test('returns the SAME object the definition holds — spreadable with no copy', () => {
-    expect(navTarget(NAV, 'dash')).toBe(NAV.groups[0].items[0].link)
-  })
-
-  test('resolves ids nested under a parent destination', () => {
-    expect(navTarget(NAV, 'reports-weekly')).toEqual({ to: '/reports/weekly' })
-  })
-
-  test('throws a named error on an unknown id', () => {
-    // The id union makes this a compile error for a consumer; the throw is the runtime backstop
-    // for the untyped edge (a dynamic id, or an unregistered router degrading `NavItemId` away).
-    expect(() => navTarget(NAV, 'zzz' as 'dash')).toThrow('navTarget: no nav item with id "zzz"')
-  })
-})

package/src/router-tanstack/search-param-store.test.ts

@@ -1,135 +0,0 @@
-/**
- * `createSearchParamStore`'s persistence seam — the half that was invisible.
- *
- * The reference consumer adopted the store in three features, hand-rolled the persistence in all
- * three, and the reader had ZERO call sites: "remember my window" had never once worked, and
- * nothing in the type, the runtime or the tests said so. The 5-step recipe in the JSDoc was
- * present the whole time. So the fix is API-shaped (`linkSearch`) plus a dev warning that fires in
- * exactly the broken state — and these tests are what keep both honest.
- */
-import { afterEach, beforeEach, describe, expect, it, spyOn } from 'bun:test'
-import { createSearchParamStore } from './search-param-store'
-
-const VALUES = ['1d', '7d', '30d'] as const
-
-function makeStore(key: string) {
-  return createSearchParamStore({ key, param: 'range', values: VALUES, fallback: '30d' })
-}
-
-/** Writes the `createPersistedState` envelope directly — the shape `readStored` parses. */
-function persist(key: string, value: string, version = 1): void {
-  localStorage.setItem(`basalt:${key}`, JSON.stringify({ v: version, value }))
-}
-
-let warn: ReturnType<typeof spyOn<Console, 'warn'>>
-
-beforeEach(() => {
-  localStorage.clear()
-  warn = spyOn(console, 'warn').mockImplementation(() => {})
-})
-
-afterEach(() => {
-  warn.mockRestore()
-})
-
-describe('linkSearch', () => {
-  it('is the click-time thunk — it reads storage at CALL time, not at creation', () => {
-    const store = makeStore('link-thunk')
-    expect(store.linkSearch()).toEqual({ range: '30d' })
-
-    persist('link-thunk', '7d')
-    // A value captured at module scope would still say 30d here. That is the bug it prevents.
-    expect(store.linkSearch()).toEqual({ range: '7d' })
-  })
-
-  it('falls back when nothing valid is stored', () => {
-    persist('link-fallback', 'not-a-range')
-    expect(makeStore('link-fallback').linkSearch()).toEqual({ range: '30d' })
-  })
-
-  it('returns the param under the store’s own param name', () => {
-    const store = createSearchParamStore({
-      key: 'link-param',
-      param: 'window',
-      values: VALUES,
-      fallback: '1d',
-    })
-    persist('link-param', '7d')
-    expect(store.linkSearch()).toEqual({ window: '7d' })
-  })
-})
-
-describe('the unwired-reader warning', () => {
-  it('fires when a link pins the fallback over a different stored value', () => {
-    const store = makeStore('warn-pinned')
-    persist('warn-pinned', '7d')
-
-    expect(store.validateSearch({ range: '30d' })).toEqual({ range: '30d' })
-    expect(warn).toHaveBeenCalledTimes(1)
-    expect(String(warn.mock.calls[0]?.[0])).toContain('linkSearch')
-  })
-
-  it('fires at most once per store, so a nav-heavy app is not spammed', () => {
-    const store = makeStore('warn-once')
-    persist('warn-once', '7d')
-
-    store.validateSearch({ range: '30d' })
-    store.validateSearch({ range: '30d' })
-    store.validateSearch({ range: '30d' })
-    expect(warn).toHaveBeenCalledTimes(1)
-  })
-
-  it('stays silent once a reader is wired — that is the whole point', () => {
-    const store = makeStore('warn-wired')
-    persist('warn-wired', '7d')
-
-    store.linkSearch()
-    store.validateSearch({ range: '30d' })
-    expect(warn).not.toHaveBeenCalled()
-  })
-
-  it('stays silent for a deliberate deep link to a non-fallback value', () => {
-    const store = makeStore('warn-deeplink')
-    persist('warn-deeplink', '30d')
-
-    store.validateSearch({ range: '7d' })
-    expect(warn).not.toHaveBeenCalled()
-  })
-
-  it('stays silent when nothing is stored yet', () => {
-    makeStore('warn-empty').validateSearch({ range: '30d' })
-    expect(warn).not.toHaveBeenCalled()
-  })
-
-  it('never fires from validateSearch’s own internal read', () => {
-    // validateSearch reads the store on every navigation; that must not count as "wired", and it
-    // must not itself trigger the warning when the URL carries no param at all.
-    const store = makeStore('warn-internal')
-    persist('warn-internal', '7d')
-
-    expect(store.validateSearch({})).toEqual({ range: '7d' })
-    expect(warn).not.toHaveBeenCalled()
-    // Still unwired, so the pinned-link case is still detectable afterwards.
-    store.validateSearch({ range: '30d' })
-    expect(warn).toHaveBeenCalledTimes(1)
-  })
-})
-
-describe('validateSearch (unchanged behaviour)', () => {
-  it('prefers a valid URL param, then storage, then the fallback', () => {
-    const store = makeStore('validate')
-    expect(store.validateSearch({ range: '7d' })).toEqual({ range: '7d' })
-
-    persist('validate', '1d')
-    expect(store.validateSearch({})).toEqual({ range: '1d' })
-    expect(store.validateSearch({ range: 'bogus' })).toEqual({ range: '1d' })
-
-    localStorage.clear()
-    expect(store.validateSearch({})).toEqual({ range: '30d' })
-  })
-
-  it('discards an envelope written under a different version', () => {
-    persist('validate-version', '7d', 2)
-    expect(makeStore('validate-version').readStored()).toBeNull()
-  })
-})