basalt-ui 1.23.1 → 1.24.0

package/src/data/data-table.tsx

@@ -42,6 +42,7 @@ import {
   Text,
   TextInput,
 } from '@mantine/core'
+import type { MantineSpacing } from '@mantine/core'
 import type {
   Column,
   ColumnDef,
@@ -49,6 +50,7 @@ import type {
   ColumnPinningState,
   FilterFn,
   PaginationState,
+  RowData,
   SortingState,
   Table as TanstackTable,
   Updater,
@@ -65,6 +67,50 @@ import type { CSSProperties, ReactNode } from 'react'
 import { useCallback, useMemo, useState } from 'react'
 import { alpha, VX } from '../tokens'
 
+// ── Column alignment ──────────────────────────────────────────────────────────
+
+/** Horizontal alignment of a column's header AND its cells. */
+export type DataTableAlign = 'left' | 'center' | 'right'
+
+/**
+ * Alignment lives on the column def's `meta`, not on a parallel prop array, so it travels with the
+ * column it describes and survives reordering.
+ *
+ * Declared as a module augmentation of TanStack's own `ColumnMeta` so `meta: { aling: 'right' }` is
+ * a TYPE error (excess-property check on the object literal) rather than a silently ignored key —
+ * and a wrong VALUE (`'end'`, `'centre'`) throws at render. A misspelled alignment that quietly
+ * left-aligns a money column is the class of defect that looks correct in review.
+ */
+declare module '@tanstack/react-table' {
+  // TData/TValue are TanStack's own parameters — required to match its declaration, unused here.
+  // oxlint-disable-next-line no-unused-vars
+  interface ColumnMeta<TData extends RowData, TValue> {
+    align?: DataTableAlign
+    /**
+     * Opt OUT of the automatic mono-numeral cell style. The table applies it whenever the cell's
+     * raw value is a number — which is right for a plain figure and wrong for a numeric accessor
+     * whose `cell` renders its own chrome (a coloured `Text`, a `Badge`, a sparkline), because the
+     * `<td>`'s mono font then overrides what the cell asked for.
+     */
+    numeral?: boolean
+  }
+}
+
+const ALIGNMENTS: ReadonlySet<string> = new Set<DataTableAlign>(['left', 'center', 'right'])
+
+/** Reads `meta.align` off a column, throwing on a value that is not one of the three. */
+function resolveAlign<T>(column: Column<T, unknown>): DataTableAlign | undefined {
+  const align = column.columnDef.meta?.align
+  if (align === undefined) return undefined
+  if (!ALIGNMENTS.has(align)) {
+    throw new Error(
+      `BasaltDataTable: column "${column.id}" has meta.align=${JSON.stringify(align)} — ` +
+        "expected 'left' | 'center' | 'right'.",
+    )
+  }
+  return align
+}
+
 // ── Facets ────────────────────────────────────────────────────────────────────
 
 /** A single selectable option inside a {@link DataTableFacet}'s Select/MultiSelect. */
@@ -129,8 +175,8 @@ export type BasaltDataTableProps<T> = {
    * @default true
    */
   enableSorting?: boolean
-  /** Stripe alternate rows. Forwarded to Mantine `Table`. */
-  striped?: boolean
+  /** Stripe alternate rows. Forwarded to Mantine `Table` — `'odd'`/`'even'` pick the phase. */
+  striped?: boolean | 'odd' | 'even'
   /** Highlight hovered rows. Forwarded to Mantine `Table`. */
   highlightOnHover?: boolean
   /** Rendered when `data` is empty. Falls back to a simple message when omitted. */
@@ -257,6 +303,42 @@ export type BasaltDataTableProps<T> = {
   enablePinning?: boolean
   /** Initial column-pinning state — which column ids stick to the left/right edge. */
   initialColumnPinning?: ColumnPinningState
+
+  // ── Body chrome ─────────────────────────────────────────────────────────────
+
+  /**
+   * Caps the scrolling body (px number or CSS length) so a long table cannot blow a card out
+   * vertically — the header stays put and the rows scroll under it. Renders Mantine's
+   * `Table.ScrollContainer type="native"`, which is the same node the docs sanction as the raw
+   * escape for a bespoke table: the blessed lane and the escape hatch produce identical DOM, so
+   * adopting one does not contradict the other.
+   *
+   * `type="native"` is required rather than preferred: `ScrollArea`'s custom viewport is the
+   * positioning context a sticky `<thead>` resolves against, so the default `'scrollarea'` type
+   * pins the header to the page viewport instead of the table's box.
+   */
+  maxHeight?: number | string
+  /**
+   * `min-width` below which the body scrolls horizontally. Setting either this or `maxHeight`
+   * turns on the scroll container; `maxHeight` alone implies `minWidth: 0`.
+   */
+  minWidth?: number | string
+  /** Sticky header row. Pair with `maxHeight` to stick within the table rather than the page. */
+  stickyHeader?: boolean
+  /** Offset for a sticky header sitting under a fixed app header (px number or CSS length). */
+  stickyHeaderOffset?: number | string
+  /** Vertical cell padding. Forwarded to Mantine `Table`. */
+  verticalSpacing?: MantineSpacing
+  /** Horizontal cell padding. Forwarded to Mantine `Table`. */
+  horizontalSpacing?: MantineSpacing
+  /** Row separators. Forwarded to Mantine `Table`. @default true (Mantine's own default) */
+  withRowBorders?: boolean
+  /**
+   * Outer table border. Turn it OFF for a table that already sits inside a `Card`/`ChartCard`,
+   * where the card owns the frame and a second one reads as a nested box.
+   * @default true
+   */
+  withTableBorder?: boolean
 }
 
 // ── Sort indicator ────────────────────────────────────────────────────────────
@@ -390,6 +472,14 @@ export function BasaltDataTable<T>({
   pageCount,
   enablePinning = false,
   initialColumnPinning,
+  maxHeight,
+  minWidth,
+  stickyHeader,
+  stickyHeaderOffset,
+  verticalSpacing,
+  horizontalSpacing,
+  withRowBorders,
+  withTableBorder = true,
 }: BasaltDataTableProps<T>) {
   const [sorting, setSorting] = useState<SortingState>(initialSorting ?? [])
   const [globalFilter, setGlobalFilter] = useState(initialGlobalFilter ?? '')
@@ -496,7 +586,12 @@ export function BasaltDataTable<T>({
     <Table
       {...(striped !== undefined && { striped })}
       {...(highlightOnHover !== undefined && { highlightOnHover })}
-      withTableBorder
+      {...(stickyHeader !== undefined && { stickyHeader })}
+      {...(stickyHeaderOffset !== undefined && { stickyHeaderOffset })}
+      {...(verticalSpacing !== undefined && { verticalSpacing })}
+      {...(horizontalSpacing !== undefined && { horizontalSpacing })}
+      {...(withRowBorders !== undefined && { withRowBorders })}
+      withTableBorder={withTableBorder}
     >
       <Table.Thead>
         {headerGroups.map((headerGroup) => (
@@ -508,6 +603,7 @@ export function BasaltDataTable<T>({
               const pinnedStyle = enablePinning
                 ? getPinnedCellStyle(table, header.column)
                 : undefined
+              const align = resolveAlign(header.column)
               return (
                 <Table.Th
                   key={header.id}
@@ -533,6 +629,7 @@ export function BasaltDataTable<T>({
                   }
                   style={{
                     ...(canSort ? { cursor: 'pointer', userSelect: 'none' } : undefined),
+                    ...(align !== undefined && { textAlign: align }),
                     ...pinnedStyle,
                   }}
                 >
@@ -582,11 +679,16 @@ export function BasaltDataTable<T>({
                   const pinnedStyle = enablePinning
                     ? getPinnedCellStyle(table, cell.column)
                     : undefined
+                  const align = resolveAlign(cell.column)
                   return (
                     <Table.Td
                       key={cell.id}
                       style={{
-                        ...(typeof cell.getValue() === 'number' ? NUMERIC_CELL_STYLE : undefined),
+                        ...(typeof cell.getValue() === 'number' &&
+                        cell.column.columnDef.meta?.numeral !== false
+                          ? NUMERIC_CELL_STYLE
+                          : undefined),
+                        ...(align !== undefined && { textAlign: align }),
                         ...pinnedStyle,
                       }}
                     >
@@ -602,6 +704,10 @@ export function BasaltDataTable<T>({
     </Table>
   )
 
+  // A capped body or a horizontal floor both need the same native scroll node; pinning keeps its
+  // simpler overflow-x Box when neither is set.
+  const scrolls = maxHeight !== undefined || minWidth !== undefined
+
   const paginationState = table.getState().pagination
   const total = table.getRowCount()
   const rangeStart = total === 0 ? 0 : paginationState.pageIndex * paginationState.pageSize + 1
@@ -661,7 +767,19 @@ export function BasaltDataTable<T>({
           {toolbarActions}
         </Group>
       )}
-      {enablePinning ? <Box style={{ overflowX: 'auto' }}>{tableNode}</Box> : tableNode}
+      {scrolls ? (
+        <Table.ScrollContainer
+          type="native"
+          minWidth={minWidth ?? 0}
+          {...(maxHeight !== undefined && { maxHeight })}
+        >
+          {tableNode}
+        </Table.ScrollContainer>
+      ) : enablePinning ? (
+        <Box style={{ overflowX: 'auto' }}>{tableNode}</Box>
+      ) : (
+        tableNode
+      )}
       {enablePagination && (
         <Group justify="space-between" mt="xs" wrap="wrap" gap="xs" align="center">
           <Text style={RANGE_LABEL_STYLE}>

package/src/data/table.ts

@@ -21,7 +21,12 @@
 
 // ── BasaltDataTable ───────────────────────────────────────────────────────────
 export { BasaltDataTable } from './data-table'
-export type { BasaltDataTableProps, DataTableFacet, DataTableFacetOption } from './data-table'
+export type {
+  BasaltDataTableProps,
+  DataTableAlign,
+  DataTableFacet,
+  DataTableFacetOption,
+} from './data-table'
 
 // ── @tanstack/react-table convenience re-exports ──────────────────────────────
 // These are the handful of table primitives a consumer needs at the call site;

package/src/guard/check-source.test.ts

@@ -66,6 +66,58 @@ describe('raw-hex', () => {
     const f = find(`// use #ff0000 from the palette`)
     expect(kinds(f)).not.toContain('raw-hex')
   })
+
+  /**
+   * Round 9, rollhook: `{` / `}` — the escaped braces an Astro template writes to show a
+   * literal `${…}` in prose — were read as the hex colors `#123` / `#125`, and 4 findings blocked a
+   * release on a page with no color in it at all. The hole was in the KIND, not in the extension:
+   * the same string produced the same two findings in `.html`, `.tsx`, `.css` and `.vue`.
+   */
+  describe('HTML numeric character references', () => {
+    const ENTITIES = `<p>image: $&#123;IMAGE_TAG&#125;</p>`
+
+    for (const rel of [
+      'index.html',
+      'src/App.tsx',
+      'src/a.css',
+      'src/Hero.vue',
+      'src/pages/index.astro',
+    ]) {
+      it(`does NOT read &#123;/&#125; as a hex color in ${rel}`, () => {
+        expect(kinds(find(ENTITIES, rel))).not.toContain('raw-hex')
+      })
+    }
+
+    // The exemption is the ENTITY, never the file type — a template that hardcodes a color is
+    // exactly what making `.astro`/`.vue` scannable was for.
+    it('still flags a real hex in an .astro file', () => {
+      const f = find(`<div style="color: #ff0000">x</div>`, 'src/pages/index.astro')
+      expect(kinds(f)).toContain('raw-hex')
+      expect(f.find((x) => x.kind === 'raw-hex')?.token).toBe('#ff0000')
+    })
+
+    it('still flags a real hex in a .vue file', () => {
+      const f = find(`<style>\n  .hero { color: #ff0000; }\n</style>`, 'src/Hero.vue')
+      expect(kinds(f)).toContain('raw-hex')
+      expect(f.find((x) => x.kind === 'raw-hex')?.token).toBe('#ff0000')
+    })
+
+    it('flags a hex after a bare & — an entity needs its terminating semicolon', () => {
+      expect(kinds(find(`<p>a&#fff b</p>`, 'index.html'))).toContain('raw-hex')
+    })
+
+    it('flags a plain #123 with no entity around it', () => {
+      expect(kinds(find(`const c = '#123'`))).toContain('raw-hex')
+    })
+
+    // The neighbouring raw-text kinds were checked for the same blind spot and do NOT share it: a
+    // character reference contains no `(`, so `raw-color-fn`'s `rgba?|hsla?\(` anchor cannot occur
+    // inside one, and every other raw-text kind anchors on a property name, `var(`, or a JSX `=`.
+    it('leaves the sibling color kinds unchanged — nothing else fires inside an entity', () => {
+      const src = `<p>&amp; &mdash; &nbsp; &#8212; &hellip; &#x1F600; &copy;</p>`
+      expect(find(src, 'index.html')).toHaveLength(0)
+    })
+  })
 })
 
 // ── 2. raw-color-fn ──────────────────────────────────────────────────────────
@@ -2580,6 +2632,95 @@ describe('markup files (index.html / *.webmanifest)', () => {
   })
 })
 
+// ── 29b. single-file components (.astro / .vue) ───────────────────────────────
+
+/**
+ * Round 9: `.astro` and `.vue` became scannable and fell through to the `ts` dialect, so `<!-- … -->`
+ * was never stripped — a `theme-allow` written in an HTML comment waived nothing there, and a color
+ * inside a commented-out block still reported. They resolve as `sfc` now: BOTH comment dialects,
+ * and the full 25-kind set (not `MARKUP_KINDS` — an `.astro` template is JSX-shaped and a `.vue`
+ * `<script setup>` is real TS).
+ */
+describe('single-file components (.astro / .vue)', () => {
+  const ASTRO = 'src/pages/index.astro'
+  const VUE = 'src/Hero.vue'
+
+  for (const rel of [ASTRO, VUE]) {
+    it(`strips an HTML comment in ${rel}`, () => {
+      expect(kinds(find(`<!-- <div style="color: #ff0000" /> -->`, rel))).not.toContain('raw-hex')
+    })
+
+    it(`honours a theme-allow inside an HTML comment in ${rel}`, () => {
+      const f = find(
+        `<!-- theme-allow raw-hex — brand asset -->\n<div style="color: #ff0000" />`,
+        rel,
+      )
+      expect(kinds(f)).not.toContain('raw-hex')
+    })
+
+    it(`honours a theme-allow-file inside an HTML comment in ${rel}`, () => {
+      const f = find(
+        `<!-- theme-allow-file raw-hex — brand asset -->\n<b style="color: #ff0000" />`,
+        rel,
+      )
+      expect(kinds(f)).not.toContain('raw-hex')
+    })
+
+    it(`honours a multi-line HTML comment annotation in ${rel}`, () => {
+      const f = find(
+        `<!--\n  theme-allow raw-hex — brand asset\n-->\n<b style="color: #ff0000" />`,
+        rel,
+      )
+      expect(kinds(f)).not.toContain('raw-hex')
+    })
+
+    it(`still strips the JS dialect in ${rel} — an SFC carries both`, () => {
+      expect(kinds(find(`// const c = '#ff0000'`, rel))).not.toContain('raw-hex')
+      expect(kinds(find(`/* const c = '#ff0000' */`, rel))).not.toContain('raw-hex')
+    })
+
+    it(`honours a theme-allow in the script fence of ${rel}`, () => {
+      const f = find(`// theme-allow raw-hex — brand asset\nconst c = '#ff0000'`, rel)
+      expect(kinds(f)).not.toContain('raw-hex')
+    })
+
+    it(`keeps the non-markup kinds — an SFC is not MARKUP_KINDS-restricted in ${rel}`, () => {
+      expect(kinds(find(`const s = { border: '1px solid #ccc' }`, rel))).toContain('raw-surface')
+      expect(kinds(find(`<div style={{ padding: 18 }} />`, rel))).toContain('inline-spacing')
+    })
+  }
+
+  it('does not let an HTML comment open a runaway JS block comment', () => {
+    const f = find(`<!-- a /* unclosed -->\n<div style="color: #ff0000" />`, ASTRO)
+    expect(kinds(f)).toContain('raw-hex')
+  })
+
+  /**
+   * Asserted LIMITS, so "unsupported" and "silently broken" don't read the same. Both are
+   * false-negative-only — the direction a release-blocking false positive says to take.
+   */
+  describe('known limits', () => {
+    it('does not fire the kebab-CSS surface kinds inside a <style> fence', () => {
+      const src = `<style>\n  .card { border-radius: 8px; }\n</style>`
+      expect(kinds(find(src, ASTRO))).not.toContain('css-raw-surface')
+      // The same text in a real .css file still reports — the limit is the SFC dialect, not the rule.
+      expect(kinds(find(src.replace(/<\/?style>/g, ''), 'src/a.css'))).toContain('css-raw-surface')
+    })
+
+    it('over-strips a `<!--` that lives inside a script string', () => {
+      expect(
+        kinds(find(`const s = '<!--'\nconst c = '#ff0000'\nconst e = '-->'`, ASTRO)),
+      ).not.toContain('raw-hex')
+    })
+
+    it('over-strips after an unquoted `https://` in template prose', () => {
+      expect(
+        kinds(find(`<p>see https://x.test <b style="color: #ff0000" /></p>`, ASTRO)),
+      ).not.toContain('raw-hex')
+    })
+  })
+})
+
 // ── 30. tokens-only profile ──────────────────────────────────────────────────
 
 describe("profile: 'tokens-only'", () => {

package/src/guard/index.ts

@@ -10,7 +10,32 @@ export type { Finding, GuardConfig, GuardKind, GuardSeverity }
 
 // ── Static regex consts ──────────────────────────────────────────────────────────────────────────
 
-const HEX = /#[0-9a-fA-F]{3,8}\b/g
+/**
+ * A raw hex color literal.
+ *
+ * The `(?!(?<=&#)\d+;)` guard drops an HTML NUMERIC CHARACTER REFERENCE. `&#123;` is the escaped
+ * `{` and `&#125;` the escaped `}` — the two an Astro/JSX template writes to show a literal brace
+ * in prose — and their `#123` / `#125` read as three-digit hex. It is not markup-specific: the same
+ * string produced the same two findings in `.html`, `.tsx`, `.css` and `.vue`, so this was a hole
+ * in the kind itself that `.astro` merely walked into first (rollhook, round 9).
+ *
+ * The lookahead is deliberately the FULL reference — `&#`, digits, `;` — not a bare `(?<!&)`. Only
+ * the decimal form can collide at all (`&#x1F600;` never matches: `x` is not a hex digit), and a
+ * `#` that follows an `&` without terminating in `;` is not an entity, so `color: red&#fff` still
+ * flags. Nothing is exempted by file type; a real `#ff0000` in an `.astro` file fires exactly as it
+ * does in a `.tsx` one.
+ *
+ * The sibling raw-text kinds do NOT share this blind spot, and the reason is structural rather than
+ * lucky: a character reference contains no `(`, so `raw-color-fn`'s `rgba?|hsla?\(` anchor cannot
+ * occur inside one, and every other raw-text kind is anchored on a property name, `var(`, or a JSX
+ * `=`. Probed across `.html`/`.astro`/`.tsx` over 20 entity shapes — `raw-hex` was the only kind
+ * that fired.
+ *
+ * Known and NOT covered, because the fix would cost real findings: an all-hex URL fragment or SVG
+ * reference (`href="#cafe"`, `fill="url(#abcdef)"`) is indistinguishable from a color by text
+ * alone, and both still report. `theme-allow` is the escape there.
+ */
+const HEX = /#(?!(?<=&#)\d+;)[0-9a-fA-F]{3,8}\b/g
 
 /**
  * A raw `rgb()`/`rgba()`/`hsl()`/`hsla()` color function.
@@ -531,6 +556,21 @@ export const DEFAULT_GUARD_CONFIG: GuardConfig = {
  * into an unplanned refactor, which is exactly what the grace minor exists to prevent. The five
  * entries below all landed together in the round-4 guard minor and all promote one minor later.
  *
+ * **A `SCANNABLE_EXT` widening cannot be expressed here, and 1.23.2's was deliberately not.**
+ * Adding `.astro`/`.jsx`/`.vue` widens the FILE SET for all 25 kinds at once — there is no kind to
+ * key an entry on, and the nearest one (`raw-hex`, which is what actually fired) is keyed per KIND,
+ * not per extension: an entry for it would demote basalt's most load-bearing kind to `warn` in
+ * every `.tsx` and `.css` in every consumer for a minor, to buy runway on a file type only one
+ * consumer has. `css-raw-surface` is the shape that DOES fit — the new dialect got its own kind
+ * because kebab CSS is a distinct pattern set; more files running the same patterns is not.
+ *
+ * The measurement agreed with the structure. Once the two defects the widening exposed were fixed
+ * (`&#123;` read as a hex; `<!-- … -->` never stripped in an SFC), rollhook's marketing site scans
+ * 6 files with 0 findings, and no other consumer has a single `.astro`, `.vue` or `.jsx` file — so
+ * grace would have covered zero incumbent violations. The doctrine protects code that "passed every
+ * previous release"; a violation in a newly-scanned file type is code the consumer is writing now,
+ * with `theme-allow`, `basalt.severity` and `exemptRules` all still available.
+ *
  * @example
  * const GRACE: Partial<Record<GuardKind, string>> = {
  *   'raw-font-family': 'introduced 1.4.0 — promote to error in 1.5.0',
@@ -846,10 +886,13 @@ function commentBlockEnd(
   syntax: GuardSyntax,
 ): number {
   const line = lines[index] ?? ''
+  // An SFC carries both dialects, so the closer is resolved from the opener the token actually sits
+  // behind rather than from the extension: whichever of `<!--` / `/*` is NEAREST on its left wins.
+  const markup = syntax === 'markup' || (syntax === 'sfc' && opensMarkupComment(line, tokenAt))
   // A line comment closes at its own end of line. CSS has no `//`, so the test is TS-only: there,
   // a `//`-looking sequence is text and the conservative same-line answer is the right one anyway.
-  if (syntax === 'ts' && /\/\/\s*$/.test(line.slice(0, tokenAt))) return index
-  const closer = syntax === 'markup' ? '-->' : '*/'
+  if (!markup && syntax !== 'css' && /\/\/\s*$/.test(line.slice(0, tokenAt))) return index
+  const closer = markup ? '-->' : '*/'
   if (line.slice(tokenAt).includes(closer)) return index
   for (let ahead = index + 1; ahead < lines.length; ahead++) {
     if ((lines[ahead] ?? '').includes(closer)) return ahead
@@ -857,6 +900,18 @@ function commentBlockEnd(
   return index
 }
 
+/**
+ * In an `sfc` file, is the comment the token sits in an HTML one?
+ *
+ * Both dialects are legal in the same file, so the extension cannot answer it — the nearest opener
+ * on the token's left does. A tie (neither present) reads as the JS dialect, which is what an
+ * annotation on a bare frontmatter line is.
+ */
+function opensMarkupComment(line: string, tokenAt: number): boolean {
+  const before = line.slice(0, tokenAt)
+  return before.lastIndexOf('<!--') > before.lastIndexOf('/*')
+}
+
 /**
  * A comment opener sitting immediately before the annotation token.
  *
@@ -1132,8 +1187,8 @@ function annotationsCover(annotations: AllowAnnotation[] | undefined, kind: Guar
   return (annotations ?? []).some((a) => annotationCovers(a, kind))
 }
 
-/** The 3 comment dialects the stripper understands, resolved from the file's own extension. */
-type GuardSyntax = 'ts' | 'css' | 'markup'
+/** The 4 comment dialects the stripper understands, resolved from the file's own extension. */
+type GuardSyntax = 'ts' | 'css' | 'markup' | 'sfc'
 
 /**
  * CSS (including `.module.css`) has no `//` line-comment syntax at all — an unquoted `//`, e.g.
@@ -1143,13 +1198,50 @@ type GuardSyntax = 'ts' | 'css' | 'markup'
  * `markup` covers the two files whose colors nothing re-derives on a theme change and which the
  * scan never reached — `index.html` and `*.webmanifest` (plus plain `.json`, which a webmanifest
  * often is). Only the color/typography kinds apply there; see `MARKUP_KINDS`.
+ *
+ * `sfc` is the single-file-component dialect — `.astro` and `.vue`, which carry BOTH regions:
+ * `<!-- … -->` in the template and `//` / `/* … *\/` in the frontmatter/`<script>` fence. They used
+ * to fall through to `ts`, so an HTML comment was never stripped: a `theme-allow` written in one
+ * waived nothing, and a color inside a commented-out block still reported (rollhook, round 9 —
+ * `.astro` became scannable in the same minor that exposed it). They are NOT `markup`: an `.astro`
+ * template is JSX-shaped and a `.vue` `<script setup>` is real TS, so restricting them to
+ * {@link MARKUP_KINDS} would drop 22 of the 25 kinds on a file type that can violate all of them.
+ *
+ * `.jsx` needs no entry — it is TS syntax with no HTML-comment region.
+ *
+ * **Two asserted limits, both false-NEGATIVE-only** (pinned in `check-source.test.ts`):
+ *
+ * 1. The kebab-CSS kinds (`css-raw-surface`) do not fire inside a `<style>` fence — that branch
+ *    keys on `syntax === 'css'`, and an SFC is one file with three dialects, not three files. The
+ *    color kinds, which are what an unguarded template layer actually leaks, do fire there.
+ * 2. Stripping is region-BLIND: `<!-- … -->` is blanked anywhere in the file, and `//` anywhere
+ *    outside a string. A `<!--` inside a script string, or an unquoted `https://` in template
+ *    prose, over-strips the rest of that construct. Both directions lose findings rather than
+ *    inventing them, which is the side of the trade a release-blocking false positive says to take.
  */
 function guardSyntaxFor(relPath: string): GuardSyntax {
   if (relPath.endsWith('.css')) return 'css'
   if (/\.(?:html?|webmanifest|json)$/.test(relPath)) return 'markup'
+  if (/\.(?:astro|vue)$/.test(relPath)) return 'sfc'
   return 'ts'
 }
 
+/**
+ * The comment-stripped twin of `text`, same length and same newline positions, for any dialect.
+ *
+ * One place rather than the two call sites (`checkSource` and `findAllowAnnotations`) that used to
+ * spell the `markup ? … : …` ternary out independently — adding `sfc` to one and not the other is
+ * exactly how the scan and `--audit-allows` drift apart on what counts as a comment.
+ *
+ * The SFC order is markup-first: an HTML comment may legally contain `//` or an unterminated `/*`,
+ * and blanking it before the TS pass keeps that text from opening a comment that runs to EOF.
+ */
+function stripGuardComments(text: string, syntax: GuardSyntax): string {
+  if (syntax === 'markup') return stripMarkupComments(text)
+  if (syntax === 'sfc') return stripComments(stripMarkupComments(text), 'ts')
+  return stripComments(text, syntax)
+}
+
 /** The only kinds meaningful in an HTML document or a JSON manifest — no JSX, no CSS-in-JS. */
 const MARKUP_KINDS: ReadonlySet<GuardKind> = new Set(['raw-hex', 'raw-color-fn', 'raw-font-family'])
 
@@ -1840,7 +1932,7 @@ export function checkSource(text: string, relPath: string, cfg: GuardConfig): Fi
   // stripped text has already blanked out. Same length / same newline positions as `text`, so line
   // numbers computed off either one agree.
   const syntax = guardSyntaxFor(relPath)
-  const codeText = syntax === 'markup' ? stripMarkupComments(text) : stripComments(text, syntax)
+  const codeText = stripGuardComments(text, syntax)
   const codeLines = codeText.split('\n')
   const { waivers, fileScoped, declared } = collectAllowAnnotations(
     lines,
@@ -2020,7 +2112,9 @@ export function checkSource(text: string, relPath: string, cfg: GuardConfig): Fi
         if (syntax === 'css' && isSubScaleCssSpacing(line, m.index)) continue
         const hasUnit = /^[a-z%]/.test(line.slice(m.index + m[0].length))
         if (
-          syntax === 'ts' &&
+          // An SFC's script fence IS TS, so it takes the same gate — without it a unitless
+          // `padding: 8` in `.astro`/`.vue` frontmatter reports with no style-object behind it.
+          (syntax === 'ts' || syntax === 'sfc') &&
           !hasUnit &&
           !isStyleObjectContext(codeText, lineStarts[i]! + m.index, styleIdentifiers)
         )
@@ -2256,7 +2350,7 @@ export function findAllowAnnotations(
 ): AllowAnnotationSite[] {
   const lines = text.split('\n')
   const syntax = guardSyntaxFor(relPath)
-  const codeText = syntax === 'markup' ? stripMarkupComments(text) : stripComments(text, syntax)
+  const codeText = stripGuardComments(text, syntax)
   const { declared } = collectAllowAnnotations(
     lines,
     codeText.split('\n'),

package/src/index.ts

@@ -95,6 +95,15 @@ export {
   type SettingsRowProps,
   DangerZone,
   type DangerZoneProps,
+  QueryState,
+  type QueryStateProps,
+  type QueryStateLike,
+  type QueryStateVariant,
+  type QueryEmptyCopy,
+  LoadingState,
+  type LoadingStateProps,
+  ErrorState,
+  type ErrorStateProps,
 } from './dashboard'
 
 // ── Connectivity (auto-mounted by BasaltProvider) ────────────────────────────────────────────────

package/src/query/error-message.test.ts

@@ -0,0 +1,67 @@
+/**
+ * `toErrorMessage`'s job is to never hand a human a string that says nothing. The decode ladder
+ * was already right; what was missing is the floor under it — an opaque envelope decoded to the
+ * literal `"{}"`, and `toErrorMessage(undefined)` returned `JSON.stringify(undefined)`, which is
+ * not a string at all despite the `string` return type. Both are the shape a page renders straight
+ * into an Alert, so both are asserted here.
+ */
+import { describe, expect, test } from 'bun:test'
+import { errorStatus, toErrorMessage } from './error-message'
+
+describe('toErrorMessage — decode ladder', () => {
+  test('Error instance → message', () => {
+    expect(toErrorMessage(new Error('slug already in use'))).toBe('slug already in use')
+  })
+
+  test('{ message } → message', () => {
+    expect(toErrorMessage({ message: 'recursive is rejected' })).toBe('recursive is rejected')
+  })
+
+  test('Eden { status, value } envelope → one level down', () => {
+    expect(toErrorMessage({ status: 409, value: { message: 'slug taken' } })).toBe('slug taken')
+  })
+
+  test('plain string → itself', () => {
+    expect(toErrorMessage('boom')).toBe('boom')
+  })
+})
+
+describe('toErrorMessage — the unusable floor', () => {
+  test('an opaque object falls back instead of rendering "{}"', () => {
+    expect(toErrorMessage({}, 'Could not create share')).toBe('Could not create share')
+  })
+
+  test('undefined returns a real string, not the undefined value', () => {
+    const message = toErrorMessage(undefined)
+    expect(typeof message).toBe('string')
+    expect(message).toBe('The request failed.')
+  })
+
+  test('an opaque envelope WITH a status folds the status into the fallback', () => {
+    expect(toErrorMessage({ status: 502, value: {} }, 'Could not load images')).toBe(
+      'Could not load images (HTTP 502)',
+    )
+  })
+
+  test('a readable body wins over the status — the server message is never replaced', () => {
+    expect(toErrorMessage({ status: 403, value: { message: 'forbidden' } }, 'Nope')).toBe(
+      'forbidden',
+    )
+  })
+
+  test('whitespace-only decodes as unusable', () => {
+    expect(toErrorMessage({ message: '   ' }, 'Fallback')).toBe('Fallback')
+  })
+})
+
+describe('errorStatus', () => {
+  test('reads a numeric status off an envelope', () => {
+    expect(errorStatus({ status: 404, value: null })).toBe(404)
+  })
+
+  test('is undefined for anything else', () => {
+    expect(errorStatus(new Error('x'))).toBeUndefined()
+    expect(errorStatus(null)).toBeUndefined()
+    expect(errorStatus({ status: '404' })).toBeUndefined()
+  })
+})