@startsimpli/ui 0.4.92 → 0.4.94

package/src/components/ui/card.tsx

@@ -1,6 +1,8 @@
 import * as React from "react"
 
 import { cn } from "../../lib/utils"
+import { Caveat } from "../states/Caveat"
+import { Footnote } from "../states/Footnote"
 
 const Card = React.forwardRef<
   HTMLDivElement,
@@ -17,12 +19,41 @@ const Card = React.forwardRef<
 ))
 Card.displayName = "Card"
 
-const CardHeader = React.forwardRef<
-  HTMLDivElement,
-  React.HTMLAttributes<HTMLDivElement>
->(({ className, ...props }, ref) => (
-  <div ref={ref} className={cn("flex flex-col space-y-1.5 p-6", className)} {...props} />
-))
+export interface CardHeaderProps extends React.HTMLAttributes<HTMLDivElement> {
+  /**
+   * A qualification of what this card shows. Collapses to a marker at the end
+   * of the header and expands on demand — the card's canonical caveat slot, so
+   * apps stop putting the caveat in the body at the weight of the data.
+   */
+  caveat?: React.ReactNode
+  /**
+   * A caveat that belongs to the whole section. Inside a `FootnoteScope` it is
+   * printed once beneath the section rather than once per card.
+   */
+  note?: string
+}
+
+const CardHeader = React.forwardRef<HTMLDivElement, CardHeaderProps>(
+  ({ className, caveat, note, children, ...props }, ref) => {
+    const hasCaveat = Boolean(caveat || note)
+
+    return (
+      <div ref={ref} className={cn("flex flex-col space-y-1.5 p-6", className)} {...props}>
+        {hasCaveat ? (
+          <div className="flex items-start justify-between gap-2">
+            <div className="flex min-w-0 flex-col space-y-1.5">{children}</div>
+            <span className="flex shrink-0 items-center">
+              {caveat ? <Caveat>{caveat}</Caveat> : null}
+              {note ? <Footnote note={note} /> : null}
+            </span>
+          </div>
+        ) : (
+          children
+        )}
+      </div>
+    )
+  }
+)
 CardHeader.displayName = "CardHeader"
 
 const CardTitle = React.forwardRef<

package/src/components/unified-table/__tests__/components/TablePagination.test.tsx

@@ -316,18 +316,75 @@ describe('TablePagination', () => {
     })
   })
 
-  describe('Edge Cases', () => {
-    it('should handle zero total count', () => {
-      const pagination = createMockPagination({
+  // An empty table has nothing to count. Every number on this line is either
+  // wrong or noise, so the line becomes a sentence instead of arithmetic.
+  describe('Empty result set', () => {
+    const emptyPagination = (overrides?: Partial<UsePaginationReturn>) =>
+      createMockPagination({
         totalCount: 0,
         totalPages: 1,
+        canGoNext: false,
+        canGoPrevious: false,
         getDisplayRange: jest.fn(() => ({ start: 0, end: 0 })),
+        ...overrides,
       })
-      render(<TablePagination pagination={pagination} />)
 
-      expect(screen.getByText(/0-0/)).toBeInTheDocument()
+    it('states that there is nothing rather than printing a range', () => {
+      const { container } = render(
+        <TablePagination pagination={emptyPagination()} totalFilteredCount={0} />
+      )
+
+      const countLine = container.querySelector('.text-muted-foreground')
+      expect(countLine?.textContent).toBe('No items')
+    })
+
+    it('never prints a range whose start is past its end', () => {
+      const { container } = render(
+        <TablePagination
+          pagination={emptyPagination({
+            // What the unfixed hook hands the component on an empty table.
+            getDisplayRange: jest.fn(() => ({ start: 1, end: 0 })),
+          })}
+        />
+      )
+
+      expect(container.textContent).not.toContain('1-0')
+    })
+
+    it('does not leak a stray 0 out of the filtered-count guard', () => {
+      // `{count && <span/>}` renders the NUMBER 0 when count is 0 — that is the
+      // second 0 in "of 00".
+      const { container } = render(
+        <TablePagination pagination={emptyPagination()} totalFilteredCount={0} />
+      )
+
+      expect(container.textContent).not.toMatch(/00/)
+      expect(container.textContent).toBe('No items')
+    })
+
+    it('does not leak a stray 0 out of the select-all guard', () => {
+      const { container } = render(
+        <TablePagination
+          pagination={emptyPagination()}
+          showSelectAllPrompt
+          onSelectAllPages={jest.fn()}
+          totalFilteredCount={0}
+        />
+      )
+
+      expect(container.textContent).toBe('No items')
+      expect(screen.queryByText(/Select all/)).not.toBeInTheDocument()
     })
 
+    it('hides page controls when there is nothing to page through', () => {
+      render(<TablePagination pagination={emptyPagination()} />)
+
+      expect(screen.queryByTitle('First page')).not.toBeInTheDocument()
+      expect(screen.queryByTitle('Next page')).not.toBeInTheDocument()
+    })
+  })
+
+  describe('Edge Cases', () => {
     it('should handle single item', () => {
       const pagination = createMockPagination({
         totalCount: 1,

package/src/components/unified-table/__tests__/hooks/usePagination.test.ts

@@ -341,6 +341,28 @@ describe('usePagination', () => {
       const range = result.current.getDisplayRange()
       expect(range).toEqual({ start: 51, end: 75 })
     })
+
+    it('should report an empty range when there are no rows at all', () => {
+      const { result } = renderHook(() =>
+        usePagination({ ...defaultProps, totalCount: 0 })
+      )
+
+      // A range that begins at 1 and ends at 0 describes nothing; it is the
+      // arithmetic leaking out. Nothing shown means nothing on both ends.
+      const range = result.current.getDisplayRange()
+      expect(range).toEqual({ start: 0, end: 0 })
+      expect(range.start).not.toBeGreaterThan(range.end)
+    })
+
+    it('should report an empty range when the page sits past the last row', () => {
+      // Server-side counts shrink under a page that is already open (rule 8:
+      // the count comes from the server, the client never recounts).
+      const { result } = renderHook(() =>
+        usePagination({ ...defaultProps, totalCount: 10, initialPage: 2 })
+      )
+
+      expect(result.current.getDisplayRange()).toEqual({ start: 0, end: 0 })
+    })
   })
 
   describe('Server-Side Pagination', () => {

package/src/components/unified-table/__tests__/utils/border-tokens.test.ts

@@ -0,0 +1,61 @@
+/**
+ * Every border in the table names its colour (startsim-768w.35.2.4).
+ *
+ * In Tailwind v4 a bare `border` / `border-b` sets a width and leaves the
+ * colour at `currentColor`, so the rule is painted in the TEXT colour of
+ * whatever it sits in. It is quiet on a white page — the rows just look heavier
+ * than intended — and loud on a dark tenant, where every row separator turns
+ * near-white. Browser-confirmed on both surfaces before this guard existed.
+ *
+ * The fix is always the same: say `border-border` (or a token shade like
+ * `border-border/50`) next to the width utility.
+ */
+
+import * as fs from 'fs'
+import * as path from 'path'
+
+const TABLE_SRC = path.resolve(__dirname, '../..')
+
+/** `border`, `border-t`, `border-x` — width with no colour. */
+const BARE_BORDER = /^border(-[trblxy])?$/
+/** Anything that names a colour: `border-border`, `border-primary`, `border-[#fff]`. */
+const NAMED_COLOR = /^([a-z-]+:)*border-(?!\d|[trblxy]$)/
+
+function sourceFiles(dir: string, acc: string[] = []): string[] {
+  for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+    const full = path.join(dir, entry.name)
+    if (entry.isDirectory()) {
+      if (entry.name === '__tests__' || entry.name === 'node_modules') continue
+      sourceFiles(full, acc)
+    } else if (/\.tsx?$/.test(entry.name)) {
+      acc.push(full)
+    }
+  }
+  return acc
+}
+
+function offenders(): string[] {
+  const found: string[] = []
+  for (const file of sourceFiles(TABLE_SRC)) {
+    fs.readFileSync(file, 'utf8')
+      .split('\n')
+      .forEach((rawLine, i) => {
+        // Prose in a doc comment may legitimately name the banned class.
+        const line = rawLine.replace(/^\s*(\/\/|\/\*|\*).*$/, '')
+        for (const quoted of line.match(/'[^']*'|"[^"]*"|`[^`]*`/g) ?? []) {
+          const tokens = quoted.slice(1, -1).split(/\s+/)
+          const bare = tokens.filter((t) => BARE_BORDER.test(t))
+          if (!bare.length) continue
+          if (tokens.some((t) => NAMED_COLOR.test(t))) continue
+          found.push(`${path.relative(TABLE_SRC, file)}:${i + 1} ${bare.join(' ')}`)
+        }
+      })
+  }
+  return found
+}
+
+describe('unified-table borders are theme-coloured, not currentColor', () => {
+  it('no border utility ships without a colour token beside it', () => {
+    expect(offenders()).toEqual([])
+  })
+})

package/src/components/unified-table/components/BulkActionBar/index.tsx

@@ -54,7 +54,7 @@ export function BulkActionBar({
       )}
       aria-hidden={!isVisible}
     >
-      <div className="flex items-center gap-2 p-3 bg-muted/50 rounded-lg border">
+      <div className="flex items-center gap-2 p-3 bg-muted/50 rounded-lg border border-border">
         {/* Selection summary */}
         <div className="flex items-center gap-2 text-sm font-medium">
           {selectAllPages ? (

package/src/components/unified-table/components/DataTableCore/index.tsx

@@ -330,7 +330,7 @@ export function DataTableCore<TData>({
   return (
     // overflow-x-auto: a wide table scrolls horizontally inside its own border
     // instead of overflowing the page to the right (startsim column-overflow).
-    <div className={cn('rounded-md border overflow-x-auto', className)}>
+    <div className={cn('rounded-md border border-border overflow-x-auto', className)}>
       <Table>
         {renderColumnHeaders()}
 

package/src/components/unified-table/components/MobileView/Card.tsx

@@ -186,7 +186,7 @@ export function Card<TData = any>({
             )}
 
             {secondaryFields && secondaryFields.length > 0 && (
-              <div className="border-t pt-3">
+              <div className="border-t border-border pt-3">
                 <div className="grid grid-cols-2 gap-3">
                   {secondaryFields.map((field) => (
                     <div

package/src/components/unified-table/components/TableFilters/index.tsx

@@ -157,7 +157,7 @@ export function TableFilters({ config, filters, className, defaultExpanded = fal
     const isExpanded = expandedSections.has(section.id)
 
     return (
-      <div key={section.id} className="border rounded-lg p-3">
+      <div key={section.id} className="border border-border rounded-lg p-3">
         <Button
           variant="ghost"
           size="sm"
@@ -214,7 +214,7 @@ export function TableFilters({ config, filters, className, defaultExpanded = fal
   const activeFilterCount = filters.getActiveFilterCount()
 
   return (
-    <div className={cn('rounded-lg border bg-muted/30', className)}>
+    <div className={cn('rounded-lg border border-border bg-muted/30', className)}>
       {/* Collapsible Header */}
       <button
         type="button"

package/src/components/unified-table/components/TablePagination/index.tsx

@@ -37,15 +37,29 @@ export function TablePagination({
   const { start, end } = getDisplayRange()
   const pageNumbers = getPageNumbers()
 
+  // Nothing to count: a range would read "1-0 of 0". Say it in words instead.
+  const isEmpty = totalCount <= 0 || end < start || end <= 0
+  // `count && <jsx/>` renders the NUMBER 0 when count is 0 — compare explicitly.
+  const showFilteredNote =
+    totalFilteredCount != null && totalFilteredCount !== totalCount
+  const showSelectAll =
+    Boolean(showSelectAllPrompt) &&
+    Boolean(onSelectAllPages) &&
+    (totalFilteredCount ?? 0) > end
+
   return (
     <div className={className}>
       <div className="flex flex-col sm:flex-row sm:items-center sm:justify-between gap-4">
         {/* Item count display */}
         <div className="text-sm text-muted-foreground">
-          Showing <span className="font-medium">{start}-{end}</span> of{' '}
-          <span className="font-medium">{totalCount}</span>
-          {totalFilteredCount && totalFilteredCount !== totalCount && (
-            <span> filtered items</span>
+          {isEmpty ? (
+            'No items'
+          ) : (
+            <>
+              Showing <span className="font-medium">{start}-{end}</span> of{' '}
+              <span className="font-medium">{totalCount}</span>
+              {showFilteredNote && <span> filtered items</span>}
+            </>
           )}
         </div>
 
@@ -137,7 +151,7 @@ export function TablePagination({
       </div>
 
       {/* Select all pages prompt */}
-      {showSelectAllPrompt && onSelectAllPages && totalFilteredCount && totalFilteredCount > end && (
+      {showSelectAll && (
         <div className="mt-3 flex items-center justify-center p-3 bg-blue-50 border border-blue-200 rounded-lg">
           <span className="text-sm text-blue-900 mr-2">
             Select all <span className="font-semibold">{totalFilteredCount}</span> items?

package/src/components/unified-table/hooks/usePagination.ts

@@ -97,9 +97,21 @@ export function usePagination({
     return pages
   }, [currentPage, totalPages])
 
+  /**
+   * The 1-based span of rows on screen, or `{ start: 0, end: 0 }` when there is
+   * no span to describe. `totalCount` is whatever the server reported, so it can
+   * legitimately be 0, or drop below the page the user already has open — both
+   * cases used to produce a backwards range like `1-0`.
+   */
   const getDisplayRange = useCallback(() => {
+    if (totalCount <= 0) return { start: 0, end: 0 }
+
     const start = (currentPage - 1) * pageSize + 1
     const end = Math.min(currentPage * pageSize, totalCount)
+
+    // The page begins past the last row: nothing is shown here.
+    if (start > end) return { start: 0, end: 0 }
+
     return { start, end }
   }, [currentPage, pageSize, totalCount])
 

package/src/components/unified-table/utils/themes.ts

@@ -15,19 +15,22 @@ export interface TableTheme {
   mobileCardContent: string
 }
 
+// Every rule here names its border colour. A bare `border` / `border-b` takes
+// currentColor in Tailwind v4, which paints table rules in the TEXT colour —
+// near-black rows on a light page, glaring pale rows on a dark tenant.
 export const defaultTheme: TableTheme = {
   name: 'default',
   container: 'w-full',
   header: 'bg-muted/50',
   headerCell: 'px-4 py-3 text-left text-sm font-medium text-muted-foreground',
   body: '',
-  row: 'border-b transition-colors',
+  row: 'border-b border-border transition-colors',
   rowHover: 'hover:bg-muted/50',
   rowSelected: 'bg-primary/10 border-primary',
   cell: 'px-4 py-3 text-sm',
-  pagination: 'flex items-center justify-between px-4 py-3 border-t',
+  pagination: 'flex items-center justify-between px-4 py-3 border-t border-border',
   emptyState: 'flex items-center justify-center py-12 text-muted-foreground',
-  mobileCard: 'rounded-lg border bg-card shadow-sm',
+  mobileCard: 'rounded-lg border border-border bg-card shadow-sm',
   mobileCardHeader: 'p-4 pb-2',
   mobileCardContent: 'p-4 pt-2',
 }
@@ -37,7 +40,7 @@ export const compactTheme: TableTheme = {
   name: 'compact',
   headerCell: 'px-2 py-2 text-left text-xs font-medium text-muted-foreground',
   cell: 'px-2 py-2 text-xs',
-  pagination: 'flex items-center justify-between px-2 py-2 border-t',
+  pagination: 'flex items-center justify-between px-2 py-2 border-t border-border',
   mobileCardHeader: 'p-3 pb-1',
   mobileCardContent: 'p-3 pt-1',
 }
@@ -47,7 +50,7 @@ export const spaciousTheme: TableTheme = {
   name: 'spacious',
   headerCell: 'px-6 py-4 text-left text-sm font-medium text-muted-foreground',
   cell: 'px-6 py-4 text-sm',
-  pagination: 'flex items-center justify-between px-6 py-4 border-t',
+  pagination: 'flex items-center justify-between px-6 py-4 border-t border-border',
   mobileCardHeader: 'p-6 pb-3',
   mobileCardContent: 'p-6 pt-3',
 }

package/src/theme/__tests__/type-scale.test.tsx

@@ -0,0 +1,145 @@
+/**
+ * The type scale is a contract, so it gets tested like one (startsim-768w.35.2.4).
+ *
+ * Two things went wrong without it:
+ *   1. Every consumer picked sizes by hand. 77% of one app's text landed on
+ *      `text-sm` or `text-xs` — two ADJACENT steps — so a card title and its
+ *      body were 1.5px apart and the hierarchy read as flat.
+ *   2. DashboardSection hard-coded `text-gray-900` / `text-gray-600`, which is
+ *      invisible-adjacent on a dark tenant. Apps hand-rolled their own headings
+ *      rather than use it, which is how you end up with nineteen loose <h2>s.
+ */
+
+import * as fs from 'fs'
+import * as path from 'path'
+import { render, screen } from '@testing-library/react'
+import {
+  TYPE_SCALE,
+  TYPE_SCALE_ORDER,
+  TYPE_SCALE_DEFAULTS,
+  TYPE_SCALE_TOKENS,
+  typeClass,
+} from '../type-scale'
+import { THEME_TOKENS } from '../contract'
+import { DashboardSection } from '../../components/dashboard/DashboardSection'
+
+const CONTRACT_CSS = fs.readFileSync(
+  path.resolve(__dirname, '../../../theme/contract.css'),
+  'utf8',
+)
+
+describe('the type scale is a real contract', () => {
+  it('names every role in packages/ui/theme/contract.css', () => {
+    const missing = TYPE_SCALE_TOKENS.filter(
+      (token) => !new RegExp(`${token}\\s*:`).test(CONTRACT_CSS),
+    )
+    expect(missing).toEqual([])
+  })
+
+  it('is listed in THEME_TOKENS so apps can enumerate what they must define', () => {
+    expect(THEME_TOKENS.typeScale).toEqual(TYPE_SCALE_TOKENS)
+  })
+
+  it('drives every role off a CSS variable, so one override reshapes the estate', () => {
+    for (const role of TYPE_SCALE_ORDER) {
+      expect(TYPE_SCALE[role]).toMatch(/text-\[length:var\(--text-[a-z-]+-size,/)
+      expect(TYPE_SCALE[role]).toMatch(/leading-\[var\(--text-[a-z-]+-leading,/)
+    }
+  })
+
+  it('carries a fallback in every variable, so a component still renders in an app that has not adopted the contract', () => {
+    for (const role of TYPE_SCALE_ORDER) {
+      // var(--x) with no comma is the failure mode: the utility computes to
+      // nothing and the text falls back to the browser default.
+      expect(TYPE_SCALE[role]).not.toMatch(/var\(--text-[a-z-]+-(size|leading)\)/)
+    }
+  })
+
+  it('gives every role its own size — no two steps land on the same number', () => {
+    const sizes = TYPE_SCALE_ORDER.map((role) => TYPE_SCALE_DEFAULTS[role])
+    expect(new Set(sizes).size).toBe(sizes.length)
+  })
+
+  it('keeps adjacent steps far enough apart to be seen as different', () => {
+    const sizes = TYPE_SCALE_ORDER.map((role) => TYPE_SCALE_DEFAULTS[role])
+    for (let i = 1; i < sizes.length; i++) {
+      expect(sizes[i]).toBeLessThan(sizes[i - 1])
+      // The original defect was a card title 1.5px larger than its own body —
+      // a difference nobody can see. 0.125rem (2px) is the floor.
+      expect(sizes[i - 1] - sizes[i]).toBeGreaterThanOrEqual(0.125)
+    }
+  })
+
+  it('spans a wide enough range that a headline cannot be mistaken for body copy', () => {
+    expect(TYPE_SCALE_DEFAULTS.display / TYPE_SCALE_DEFAULTS.body).toBeGreaterThanOrEqual(3)
+  })
+
+  it('sets size and weight only — colour stays a theme decision', () => {
+    for (const role of TYPE_SCALE_ORDER) {
+      expect(TYPE_SCALE[role]).not.toMatch(/(^|\s)text-(gray|slate|zinc|neutral|stone|foreground)/)
+    }
+  })
+
+  it('exposes the roles through a helper for dynamic call sites', () => {
+    expect(typeClass('heading')).toBe(TYPE_SCALE.heading)
+  })
+})
+
+describe('DashboardSection is theme-driven, not light-locked', () => {
+  const classesOf = (el: Element | null | undefined) =>
+    (el?.getAttribute('class') ?? '').split(/\s+/)
+
+  it('renders the title on the heading step of the scale', () => {
+    render(<DashboardSection title="Overview"><div /></DashboardSection>)
+    const heading = screen.getByRole('heading', { level: 2, name: 'Overview' })
+
+    for (const cls of TYPE_SCALE.heading.split(/\s+/)) {
+      expect(heading).toHaveClass(cls)
+    }
+  })
+
+  it('renders the description on the muted step of the scale', () => {
+    render(
+      <DashboardSection title="Overview" description="Last 28 days">
+        <div />
+      </DashboardSection>,
+    )
+    const description = screen.getByText('Last 28 days')
+
+    for (const cls of TYPE_SCALE.muted.split(/\s+/)) {
+      expect(description).toHaveClass(cls)
+    }
+  })
+
+  it('colours text with theme tokens so it reads on a dark tenant', () => {
+    const { container } = render(
+      <DashboardSection title="Overview" description="Last 28 days">
+        <div />
+      </DashboardSection>,
+    )
+
+    expect(screen.getByRole('heading', { level: 2 })).toHaveClass('text-foreground')
+    expect(screen.getByText('Last 28 days')).toHaveClass('text-muted-foreground')
+
+    // No `gray-*` / `bg-white` anywhere in the subtree — those ignore the theme.
+    const offenders = Array.from(container.querySelectorAll('*'))
+      .flatMap((el) => classesOf(el))
+      .filter((cls) => /^(bg|text|border|divide|ring)-(gray|slate|zinc|neutral|stone)-\d{2,3}$|^bg-white$/.test(cls))
+    expect(offenders).toEqual([])
+  })
+
+  it('never draws a bare `border`, which is currentColor in Tailwind v4', () => {
+    const { container } = render(
+      <DashboardSection title="Overview" action={<button>Export</button>}>
+        <div />
+      </DashboardSection>,
+    )
+
+    for (const el of Array.from(container.querySelectorAll('*'))) {
+      const classes = classesOf(el)
+      const bare = classes.filter((c) => /^border(-[trblxy])?$/.test(c))
+      if (!bare.length) continue
+      expect(classes.some((c) => c.startsWith('border-') && !/^border-[trblxy]$/.test(c))).toBe(true)
+    }
+  })
+})

package/src/theme/contract.ts

@@ -1,3 +1,5 @@
+import { TYPE_SCALE_TOKENS } from './type-scale'
+
 /** All CSS custom property names that apps must define in their theme */
 export const THEME_TOKENS = {
   colors: [
@@ -33,6 +35,8 @@ export const THEME_TOKENS = {
   ],
   shadows: ['--shadow-sm', '--shadow-md', '--shadow-lg', '--shadow-xl'],
   typography: ['--font-sans', '--font-mono', '--font-heading'],
+  // The type scale — see ./type-scale.ts for the roles these size.
+  typeScale: TYPE_SCALE_TOKENS,
   animation: ['--duration-fast', '--duration-normal', '--duration-slow', '--easing-default'],
   borders: ['--border-width'],
 } as const
@@ -44,5 +48,6 @@ export type ThemeToken =
   | ThemeShapeTokens
   | (typeof THEME_TOKENS.shadows)[number]
   | (typeof THEME_TOKENS.typography)[number]
+  | (typeof THEME_TOKENS.typeScale)[number]
   | (typeof THEME_TOKENS.animation)[number]
   | (typeof THEME_TOKENS.borders)[number]

package/src/theme/index.ts

@@ -7,3 +7,13 @@ export { default as tailwindPreset } from './tailwind.preset'
 // Design token contract — all CSS variables apps must define
 export { THEME_TOKENS } from './contract'
 export type { ThemeColorTokens, ThemeShapeTokens, ThemeToken } from './contract'
+
+// Type scale — the named roles every text size in the estate comes from
+export {
+  TYPE_SCALE,
+  TYPE_SCALE_ORDER,
+  TYPE_SCALE_DEFAULTS,
+  TYPE_SCALE_TOKENS,
+  typeClass,
+} from './type-scale'
+export type { TypeScaleRole, TypeScaleToken } from './type-scale'