basalt-ui 1.23.0 → 1.24.0

package/src/cli/tokens-css.test.ts

@@ -14,6 +14,7 @@ import { existsSync, mkdtempSync, readFileSync, readdirSync, rmSync, writeFileSy
 import { tmpdir } from 'node:os'
 import { join, resolve } from 'node:path'
 
+import { DEFAULT_GUARD_CONFIG, GENERATED_HEADER_LINE, checkSource } from '../guard'
 import { buildPaletteCss } from '../tokens'
 import { normalizeColorFunctions, run, tokensCss } from './index'
 
@@ -118,3 +119,131 @@ describe('tokens:css', () => {
     expect(readdirSync(dir)).toEqual(['package.json'])
   })
 })
+
+/**
+ * `--check` gates the token VALUES and the provenance INVOCATION — only the version token is free.
+ *
+ * Line 2 of the generated header carries the emitting version, and `--check` used to compare the
+ * whole file byte for byte, so every basalt-ui release forced a mandatory no-op commit in every
+ * consumer that commits a generated sheet. 1.23.1 fixed that by blanking the whole of line 2 —
+ * which is also the line carrying the exact invocation line 1 tells the reader to regenerate with.
+ * rollhook's header was rewritten from `--only core --no-legacy-aliases` to `--only all
+ * --with-legacy-aliases` and `--check` passed clean.
+ *
+ * Three-way contract, one test each below: a version-only change passes, a line-2 flag change
+ * fails, a token drift fails.
+ */
+describe('tokens:css --check and the provenance line', () => {
+  /** Capture stdout/stderr so the check's own sentence can be asserted. */
+  function check(out: string): { code: number; log: string } {
+    const originalLog = console.log
+    const originalError = console.error
+    let log = ''
+    const sink = (...args: unknown[]) => {
+      log += `${args.join(' ')}\n`
+    }
+    console.log = sink
+    console.error = sink
+    try {
+      return { code: tokensCss(['--check', '--out', out], dir), log }
+    } finally {
+      console.log = originalLog
+      console.error = originalError
+    }
+  }
+
+  it('passes when only the emitting VERSION on line 2 differs', () => {
+    const emitted = emit([])
+    const lines = emitted.split('\n')
+    lines[1] = (lines[1] as string).replace(/basalt-ui [\d.]+/, 'basalt-ui 0.0.1')
+    writeFileSync(resolve(dir, 'out.css'), lines.join('\n'))
+
+    const { code, log } = check('out.css')
+    expect(code).toBe(0)
+    expect(log).toContain('is up to date')
+    // Parsed, not asserted: the old sentence claimed "an older basalt-ui" without ever reading
+    // the token, so `0.0.1-nonsense` got the same claim. Both versions are named now.
+    expect(log).toContain('names basalt-ui 0.0.1, an older release than the')
+  })
+
+  it('calls a NEWER on-disk version newer — the old sentence said "older" either way', () => {
+    const lines = emit([]).split('\n')
+    lines[1] = (lines[1] as string).replace(/basalt-ui [\d.]+ —/, 'basalt-ui 999.0.0 —')
+    writeFileSync(resolve(dir, 'out.css'), lines.join('\n'))
+
+    const { code, log } = check('out.css')
+    expect(code).toBe(0)
+    expect(log).toContain('names basalt-ui 999.0.0, a newer release than the')
+    expect(log).not.toContain('an older release')
+  })
+
+  it('calls a same-triple prerelease merely different rather than ordering it', () => {
+    const lines = emit([]).split('\n')
+    const current = /basalt-ui (\d+\.\d+\.\d+)/.exec(lines[1] as string)?.[1] as string
+    lines[1] = (lines[1] as string).replace(`basalt-ui ${current} —`, `basalt-ui ${current}-rc.1 —`)
+    writeFileSync(resolve(dir, 'out.css'), lines.join('\n'))
+
+    const { code, log } = check('out.css')
+    expect(code).toBe(0)
+    expect(log).toContain(`names basalt-ui ${current}-rc.1, a different release than the`)
+  })
+
+  it('FAILS when line 2 names different flags — the invocation line 1 points at is gated', () => {
+    const emitted = emit([])
+    const lines = emitted.split('\n')
+    lines[1] = (lines[1] as string).replace(
+      '`basalt-ui tokens:css --out out.css`',
+      '`basalt-ui tokens:css --only all --with-legacy-aliases --out out.css`',
+    )
+    writeFileSync(resolve(dir, 'out.css'), lines.join('\n'))
+
+    const { code, log } = check('out.css')
+    expect(code).toBe(1)
+    expect(log).toContain('provenance line does not match the command that produced this content')
+    expect(log).toContain('--only all --with-legacy-aliases')
+  })
+
+  it('FAILS when the provenance line is deleted outright — a blank line is not a free pass', () => {
+    const lines = emit([]).split('\n')
+    lines[1] = ''
+    writeFileSync(resolve(dir, 'out.css'), lines.join('\n'))
+
+    expect(check('out.css').code).toBe(1)
+  })
+
+  it('says nothing about provenance when the file is byte-identical', () => {
+    emit([])
+    const { code, log } = check('out.css')
+    expect(code).toBe(0)
+    expect(log).not.toContain('provenance line')
+  })
+
+  it('STILL fails when a token value actually moved', () => {
+    const emitted = emit([])
+    writeFileSync(resolve(dir, 'out.css'), emitted.replace('--vx-neutral', '--vx-neutrall'))
+    const { code, log } = check('out.css')
+    expect(code).toBe(1)
+    expect(log).toContain('differs from what')
+  })
+
+  it('STILL fails on token drift even when the version token ALSO differs', () => {
+    const lines = emit([]).replace('--vx-neutral', '--vx-neutrall').split('\n')
+    lines[1] = (lines[1] as string).replace(/basalt-ui [\d.]+ —/, 'basalt-ui 0.0.1 —')
+    writeFileSync(resolve(dir, 'out.css'), lines.join('\n'))
+    expect(check('out.css').code).toBe(1)
+  })
+
+  it('the header itself is unchanged — the `@generated` exemption needs both lines verbatim', () => {
+    const lines = emit([]).split('\n')
+    expect(lines[0]).toBe(GENERATED_HEADER_LINE)
+    expect(lines[1]).toMatch(/^\/\* basalt-ui [\d.]+ — `basalt-ui tokens:css --out out\.css` \*\/$/)
+  })
+
+  it('the emitted header is still guard-exempt — checkSource reports nothing in it', () => {
+    // The exemption requires line 1 verbatim AND line 2 parsing as the provenance line. `--check`
+    // now reads line 2 too, so the two shapes have to keep agreeing; this is the assertion that
+    // notices if the emitter drifts to satisfy the gate.
+    const emitted = emit([])
+    expect(checkSource(emitted, 'src/tokens.css', DEFAULT_GUARD_CONFIG)).toEqual([])
+  })
+})

package/src/cli/toolchain-wiring.test.ts

@@ -1210,3 +1210,149 @@ describe('DESIGN.md carries no version, and sync heals the ones already written'
     expect(read('DESIGN.md')).toBe(owned)
   })
 })
+
+// ── The ascend direction ──────────────────────────────────────────────────────
+// Round 9, basalt-ui-obsidian: from `apps/demo` — a package with no `basalt` key of its own —
+// `check-theme` invented `roots: ["src"]`, scanned 22 of the repo's 44 guarded files, printed
+// `✓ no off-palette colors`, and reported the invention back as `basalt.roots (src)`. Its
+// `--audit-allows` then reported `0 live` for a repo carrying one live waiver: a clean slate from
+// the one command whose entire job is to deny one. `doctor`, standing in the same directory,
+// already resolved the parent. The descend direction announced itself; only ascend was silent.
+describe('check-theme / doctor — ascend to the parent config instead of fabricating one', () => {
+  /** Repo root owns the config and names TWO roots; neither package declares anything. */
+  function twoRootRepo(): void {
+    write('.git/HEAD', 'ref: refs/heads/master\n')
+    write(
+      'package.json',
+      JSON.stringify({
+        name: 'fixture',
+        workspaces: ['packages/*', 'apps/*'],
+        basalt: { roots: ['packages/lib/src', 'apps/demo/src'] },
+      }),
+    )
+    write('packages/lib/package.json', JSON.stringify({ name: 'lib' }))
+    write('apps/demo/package.json', JSON.stringify({ name: 'demo' }))
+    write('apps/demo/src/App.tsx', 'export const App = () => null\n')
+  }
+
+  it('scans the WHOLE declared surface from a package that declares nothing, and says so', () => {
+    twoRootRepo()
+    // The violation sits in the sibling root — the half the fabricated `src` default never read.
+    write('packages/lib/src/Card.tsx', `export const C = () => <div style={{ borderRadius: 8 }} />`)
+
+    const { code, log } = capture(() => checkTheme(join(dir, 'apps/demo')))
+    expect(log).toContain('running in ../.., where it lives')
+    expect(code).toBe(1)
+    expect(log).toContain('raw-surface')
+  })
+
+  it('--audit-allows reports the repo’s real waiver count, not zero', () => {
+    twoRootRepo()
+    write(
+      'packages/lib/src/Card.tsx',
+      'export const C = () => <div style={{ borderRadius: 8 }} /> // theme-allow: legacy widget\n',
+    )
+
+    const { code, log } = capture(() => checkTheme(join(dir, 'apps/demo'), ['--audit-allows']))
+    expect(code).toBe(0)
+    expect(log).toContain('1 live, 0 dead')
+    expect(log).toContain('basalt.roots (packages/lib/src, apps/demo/src)')
+  })
+
+  it('doctor and check-theme now answer with the SAME project dir', () => {
+    twoRootRepo()
+    write('packages/lib/src/Card.tsx', 'export const C = () => null\n')
+    write(MANIFEST_PATH, JSON.stringify({ version: 1, files: {}, basaltVersion: CLI_VERSION }))
+    write('.oxlintrc.json', '{ "extends": ["./node_modules/basalt-ui/configs/oxlint.json"] }')
+    installBasalt()
+
+    const { log } = capture(() => doctor(join(dir, 'apps/demo')))
+    expect(log).toContain('reporting on ../.., where it lives')
+    expect(log).toContain(`basalt-ui doctor — ${dir}`)
+  })
+
+  it('never ascends out of the repo — no .git above cwd means no ancestor to read', () => {
+    // No `.git` anywhere: the walk has no bound, so it refuses to walk at all and the built-in
+    // defaults apply exactly as they did before. A standalone consumer is untouched by this.
+    write('package.json', JSON.stringify({ name: 'root', basalt: { roots: ['packages/lib/src'] } }))
+    write('packages/lib/package.json', JSON.stringify({ name: 'lib' }))
+    write('packages/lib/src/App.tsx', 'export const App = () => null\n')
+
+    const { code, log } = capture(() => checkTheme(join(dir, 'packages/lib')))
+    expect(log).not.toContain('where it lives')
+    expect(code).toBe(0)
+  })
+
+  it('BASALT_CWD still wins over the ascend', () => {
+    twoRootRepo()
+    write('packages/lib/src/Card.tsx', 'export const C = () => null\n')
+    write('apps/demo/package.json', JSON.stringify({ name: 'demo', basalt: { roots: ['src'] } }))
+    process.env['BASALT_CWD'] = join(dir, 'apps/demo')
+    try {
+      const { code, log } = capture(() => checkTheme(dir, ['--audit-allows']))
+      expect(code).toBe(0)
+      expect(log).toContain('basalt.roots (src)')
+    } finally {
+      delete process.env['BASALT_CWD']
+    }
+  })
+})
+
+// ── The icons check, reachable wherever doctor runs ───────────────────────────
+// Round 9, rb and argo: the root run — the ONLY invocation that can exit 0 on a monorepo layout —
+// omitted the icons check entirely, with no `⊘ SKIPPED` line. It read `cwd/public` and `cwd`'s
+// vite config, and in a monorepo both live in the app package. A check that vanishes without a
+// word is indistinguishable from one that passed.
+describe('doctor — the icons check is reachable from the root, or says why not', () => {
+  /** A monorepo whose app package owns the vite config, the public/ tree and nothing else. */
+  function appPackageRepo(viteConfig: string): void {
+    write('.git/HEAD', 'ref: refs/heads/master\n')
+    write('package.json', JSON.stringify({ name: 'fixture', basalt: { roots: ['apps/web/src'] } }))
+    write('apps/web/src/app.tsx', 'export const App = () => null\n')
+    write('apps/web/vite.config.ts', viteConfig)
+    write('.oxlintrc.json', '{ "extends": ["./node_modules/basalt-ui/configs/oxlint.json"] }')
+    write(MANIFEST_PATH, JSON.stringify({ version: 1, files: {}, basaltVersion: CLI_VERSION }))
+    installBasalt()
+  }
+
+  it('reads the app package’s `icons` array from a ROOT-invoked run', () => {
+    appPackageRepo("export default basaltAppPlugin({ icons: [{ src: '/favicon.svg' }] })\n")
+    write('apps/web/public/favicon.svg', '<svg/>')
+
+    const { log } = capture(() => doctor(dir))
+    expect(log).toContain("apps/web/public/ has all 1 icon file(s) basaltAppPlugin's `icons`")
+  })
+
+  it('reports a missing icon from the root too — it is not just reachable, it judges', () => {
+    appPackageRepo("export default basaltAppPlugin({ icons: [{ src: '/favicon.svg' }] })\n")
+    write('apps/web/public/.keep', '')
+
+    const { log } = capture(() => doctor(dir))
+    expect(log).toContain('basaltAppPlugin declares icon(s) that are not in ./apps/web/public/')
+  })
+
+  it('SKIPS loudly when the plugin is configured but has no public/ beside it', () => {
+    appPackageRepo("export default basaltAppPlugin({ icons: [{ src: '/favicon.svg' }] })\n")
+
+    const { code, log } = capture(() => doctor(dir))
+    expect(log).toContain('⊘ SKIPPED — app icons — ./apps/web configures basaltAppPlugin')
+    expect(code).toBe(1)
+  })
+
+  it('states the absence rather than omitting the line when nothing uses the plugin', () => {
+    write('.git/HEAD', 'ref: refs/heads/master\n')
+    healthyFixture()
+
+    const { code, log } = capture(() => doctor(dir))
+    expect(log).toContain('no `basaltAppPlugin(` under this project')
+    expect(code).toBe(0)
+  })
+
+  it('`icons: false` is nothing to check, from the root as from the package', () => {
+    appPackageRepo('export default basaltAppPlugin({ icons: false })\n')
+
+    const { code, log } = capture(() => doctor(dir))
+    expect(log).toContain('basaltAppPlugin is configured with no icons')
+    expect(code).toBe(0)
+  })
+})

package/src/dashboard/empty-state.tsx

@@ -24,8 +24,12 @@ export type EmptyStateProps = {
   icon?: ReactNode
   /** Head-font title (18px, weight 550, ink). */
   title: string
-  /** Muted 15px description, capped at ~360px so it reads as a short explanation. */
-  description: string
+  /**
+   * Muted 15px description, capped at ~360px so it reads as a short explanation. Optional: a
+   * compact panel ("No data yet") should not have to invent a second sentence, and five argo
+   * features wrapped this component solely to avoid doing so.
+   */
+  description?: string
   /** Optional call-to-action rendered below the description. */
   action?: ReactNode
   /** `'page'` (default) = generous padding for a full-page state; `'section'` = compact. */
@@ -60,7 +64,9 @@ export function EmptyState({
       >
         {title}
       </span>
-      <span style={{ fontSize: VX.text.md, color: VX.muted, maxWidth: 360 }}>{description}</span>
+      {description !== undefined && (
+        <span style={{ fontSize: VX.text.md, color: VX.muted, maxWidth: 360 }}>{description}</span>
+      )}
       {action}
     </Stack>
   )

package/src/dashboard/index.ts

@@ -9,3 +9,14 @@ export {
   DangerZone,
   type DangerZoneProps,
 } from './settings-section'
+export {
+  QueryState,
+  type QueryStateProps,
+  type QueryStateLike,
+  type QueryStateVariant,
+  type QueryEmptyCopy,
+  LoadingState,
+  type LoadingStateProps,
+  ErrorState,
+  type ErrorStateProps,
+} from './query-state'

package/src/dashboard/query-state.test.tsx

@@ -0,0 +1,152 @@
+/**
+ * `QueryState` exists because shipping only `EmptyState` produced a correctness bug in a real
+ * consumer: a 500 rendered "No images", a dropped connection rendered "Share not found — it may
+ * have been deleted". Every assertion here is aimed at that failure mode rather than at chrome.
+ *
+ *  1. A FAILED query never renders the empty copy. This is the bug, stated as a test.
+ *  2. A failed query WITH cached data keeps the page and adds a banner — a background refetch
+ *     failing must not blank a screen that already works.
+ *  3. `fetchStatus: 'idle'` with no data is EMPTY, not loading (the `enabled: false` case);
+ *     `'fetching'` with no data is loading.
+ *  4. A result missing a branch flag THROWS. `QueryStateLike` is a structural subset on purpose,
+ *     so the compiler stops policing it — and every field it can lose fails silently in the
+ *     direction of a false claim about the data.
+ */
+import { MantineProvider } from '@mantine/core'
+import { render, screen } from '@testing-library/react'
+import { describe, expect, test } from 'bun:test'
+import type { ReactNode } from 'react'
+import { QueryState } from './query-state'
+import type { QueryStateLike } from './query-state'
+
+type Row = { id: number }
+
+function result(over: Partial<QueryStateLike<Row[]>>): QueryStateLike<Row[]> {
+  return {
+    data: undefined,
+    isError: false,
+    error: null,
+    fetchStatus: 'idle',
+    refetch: () => undefined,
+    ...over,
+  }
+}
+
+const EMPTY = { title: 'No images match', description: 'Widen the capture dates.' }
+
+function renderState(query: QueryStateLike<Row[]>, extra?: ReactNode): HTMLElement {
+  const { container } = render(
+    <MantineProvider>
+      <QueryState query={query} empty={EMPTY} errorTitle="Could not load images">
+        {(rows) => <div data-testid="body">{rows.length} rows</div>}
+      </QueryState>
+      {extra}
+    </MantineProvider>,
+  )
+  return container
+}
+
+describe('the branch a 500 must not take', () => {
+  test('an errored query renders the server message, never the empty copy', () => {
+    renderState(
+      result({ isError: true, error: { status: 500, value: { message: 'index is rebuilding' } } }),
+    )
+    expect(screen.getByText('index is rebuilding')).toBeTruthy()
+    expect(screen.queryByText('No images match')).toBeNull()
+    expect(screen.getByRole('button', { name: 'Retry' })).toBeTruthy()
+  })
+
+  test('an opaque 500 envelope falls back to the errorTitle copy plus the status', () => {
+    render(
+      <MantineProvider>
+        <QueryState
+          query={result({ isError: true, error: { status: 500, value: {} } })}
+          errorTitle="Could not load images"
+          errorFallback="The library did not answer."
+        >
+          {() => null}
+        </QueryState>
+      </MantineProvider>,
+    )
+    expect(screen.getByText('The library did not answer. (HTTP 500)')).toBeTruthy()
+  })
+
+  test('retry calls refetch', () => {
+    let calls = 0
+    renderState(result({ isError: true, error: new Error('down'), refetch: () => ++calls }))
+    ;(screen.getByRole('button', { name: 'Retry' }) as HTMLButtonElement).click()
+    expect(calls).toBe(1)
+  })
+})
+
+describe('cached data survives a failed refresh', () => {
+  test('error WITH data renders the body plus a banner, not the error page', () => {
+    renderState(result({ data: [{ id: 1 }], isError: true, error: new Error('refresh failed') }))
+    expect(screen.getByTestId('body').textContent).toBe('1 rows')
+    expect(screen.getByText('Showing cached data')).toBeTruthy()
+  })
+})
+
+describe('empty vs loading', () => {
+  test('no data + idle is EMPTY (the enabled:false case)', () => {
+    renderState(result({ fetchStatus: 'idle' }))
+    expect(screen.getByText('No images match')).toBeTruthy()
+  })
+
+  test('no data + fetching is LOADING', () => {
+    renderState(result({ fetchStatus: 'fetching' }))
+    expect(screen.queryByText('No images match')).toBeNull()
+    expect(screen.getByLabelText('Loading')).toBeTruthy()
+  })
+
+  test('an empty array is empty; a populated one renders children', () => {
+    renderState(result({ data: [] }))
+    expect(screen.getByText('No images match')).toBeTruthy()
+  })
+
+  test('isEmpty overrides the default test', () => {
+    render(
+      <MantineProvider>
+        <QueryState query={result({ data: [] })} empty={EMPTY} isEmpty={() => false}>
+          {(rows) => <div data-testid="body">{rows.length} rows</div>}
+        </QueryState>
+      </MantineProvider>,
+    )
+    expect(screen.getByTestId('body').textContent).toBe('0 rows')
+  })
+
+  test('omitting `empty` renders nothing rather than inventing copy', () => {
+    render(
+      <MantineProvider>
+        <QueryState query={result({ data: [] })}>{() => <div>rows</div>}</QueryState>
+      </MantineProvider>,
+    )
+    expect(screen.queryByText('rows')).toBeNull()
+  })
+})
+
+describe('a malformed result throws instead of asserting absence', () => {
+  const cases: [string, unknown][] = [
+    ['missing isError', { data: undefined, error: null, fetchStatus: 'idle', refetch: () => 0 }],
+    [
+      'misspelled fetchStatus',
+      { data: undefined, isError: false, error: null, fetchStatus: 'pending', refetch: () => 0 },
+    ],
+    ['missing refetch', { data: undefined, isError: false, error: null, fetchStatus: 'idle' }],
+    ['not an object at all', ['a', 'b']],
+  ]
+
+  for (const [name, bad] of cases) {
+    test(name, () => {
+      expect(() =>
+        render(
+          <MantineProvider>
+            <QueryState query={bad as QueryStateLike<Row[]>} empty={EMPTY}>
+              {() => null}
+            </QueryState>
+          </MantineProvider>,
+        ),
+      ).toThrow(/QueryState: `query`/)
+    })
+  }
+})