@startsimpli/ui 0.4.103 → 0.4.105

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@startsimpli/ui",
-  "version": "0.4.103",
+  "version": "0.4.105",
   "description": "Shared UI components package for StartSimpli applications",
   "main": "./src/index.ts",
   "types": "./src/index.ts",
@@ -8,6 +8,7 @@
     ".": "./src/index.ts",
     "./catalog": "./src/catalog/index.ts",
     "./table": "./src/components/unified-table/index.ts",
+    "./foundry": "./src/foundry/index.ts",
     "./gantt": "./src/components/gantt/index.ts",
     "./gantt/styles": "./src/components/gantt/gantt.css",
     "./components": "./src/components/index.ts",
@@ -44,9 +45,9 @@
     "next": "^14.0.0 || ^15.0.0 || ^16.0.0",
     "react": "^18.0.0 || ^19.0.0",
     "react-dom": "^18.0.0 || ^19.0.0",
-    "@startsimpli/api": "^0.5.56",
     "@startsimpli/auth": "^0.4.35",
-    "@startsimpli/i18n": "^0.1.3"
+    "@startsimpli/i18n": "^0.1.3",
+    "@startsimpli/api": "^0.5.56"
   },
   "peerDependenciesMeta": {
     "@startsimpli/api": {
@@ -120,8 +121,8 @@
     "tailwindcss": "^3.4.19",
     "tsup": "^8.5.1",
     "typescript": "^6.0.3",
-    "@startsimpli/realtime": "0.0.2",
-    "@startsimpli/i18n": "0.1.3"
+    "@startsimpli/i18n": "0.1.3",
+    "@startsimpli/realtime": "0.0.2"
   },
   "keywords": [
     "ui",

package/src/components/document-editor/DocumentEditor.tsx

@@ -12,6 +12,7 @@
  */
 import * as React from 'react';
 import { Columns2, Eye, Pencil, Plus, Trash2, Loader2, Check, AlertCircle } from 'lucide-react';
+import { wordCount } from '../validation/checks';
 
 import { cn } from '../../lib/utils';
 import { MarkdownRenderer } from '../blog/MarkdownRenderer';
@@ -34,9 +35,17 @@ export interface DocumentEditorProps {
   className?: string;
 }
 
+/**
+ * ONE word counter in this package, not two (bd startsim-wn2p.28).
+ *
+ * This file had its own `split(/\s+/)` copy, so after the validation rail
+ * learned to count Chinese the editor still did not: the same Chinese draft
+ * showed "Blog word count 524 words" in the rail and "16 words" on the tab
+ * heading directly above it. A reader cannot tell which number to believe, and
+ * the honest answer was that only one of them was counting.
+ */
 function countWords(s: string): number {
-  const t = s.trim();
-  return t ? t.split(/\s+/).length : 0;
+  return wordCount(s);
 }
 
 function asString(v: unknown): string {

package/src/components/navigation/__tests__/breadcrumbs.test.tsx

@@ -0,0 +1,16 @@
+import { render, screen } from '@testing-library/react'
+import { Breadcrumbs } from '../breadcrumbs'
+
+describe('Breadcrumbs', () => {
+  it('renders nothing rather than an empty nav', () => {
+    const { container } = render(<Breadcrumbs crumbs={[]} />)
+    expect(container.firstChild).toBeNull()
+  })
+
+  it('links every crumb but the one you are on', () => {
+    render(<Breadcrumbs crumbs={[{ label: 'Home', href: '/' }, { label: 'Products' }]} />)
+    expect(screen.getByRole('link', { name: 'Home' })).toHaveAttribute('href', '/')
+    expect(screen.queryByRole('link', { name: 'Products' })).not.toBeInTheDocument()
+    expect(screen.getByText('Products')).toHaveAttribute('aria-current', 'page')
+  })
+})

package/src/components/navigation/breadcrumbs.tsx

@@ -0,0 +1,39 @@
+import Link from 'next/link';
+
+export interface Crumb {
+  label: string;
+  /** Omitted on the last crumb — the page you are already on is not a link. */
+  href?: string;
+}
+
+/**
+ * Where you are, one line above the heading.
+ *
+ * DELIBERATELY FLAT. A breadcrumb generated from a menu config goes BLANK on
+ * every route the menu has no entry for — a trail that disappears exactly where
+ * a trail is most useful. This renders the crumbs it is handed, in order, and
+ * has no opinion about where they came from.
+ */
+export function Breadcrumbs({ crumbs }: { crumbs: Crumb[] }) {
+  if (crumbs.length === 0) return null;
+  return (
+    <nav aria-label="Breadcrumb">
+      <ol className="flex flex-wrap items-center gap-1.5 text-xs text-gray-500">
+        {crumbs.map((crumb, i) => (
+          <li key={`${crumb.label}-${i}`} className="flex items-center gap-1.5">
+            {i > 0 ? <span aria-hidden>/</span> : null}
+            {crumb.href ? (
+              <Link href={crumb.href} className="hover:text-gray-900 hover:underline">
+                {crumb.label}
+              </Link>
+            ) : (
+              <span className="text-gray-700" aria-current="page">
+                {crumb.label}
+              </span>
+            )}
+          </li>
+        ))}
+      </ol>
+    </nav>
+  );
+}

package/src/components/navigation/index.ts

@@ -4,3 +4,4 @@ export * from './sidebar'
 export * from './app-shell'
 export * from './grouped-nav'
 export * from './entity-switcher'
+export * from './breadcrumbs'

package/src/components/unified-table/UnifiedTable.tsx

@@ -306,6 +306,12 @@ export function UnifiedTable<TData>({
   useEffect(() => {
     if (!searchConfig?.enabled || !searchConfig.preserveFocus) return
     if (!shouldRestoreFocusRef.current) return
+    // Already focused means the user never lost it — re-focusing would only move
+    // the caret to the end, which with a debounced search happens mid-word.
+    if (searchInputRef.current && document.activeElement === searchInputRef.current) {
+      shouldRestoreFocusRef.current = false
+      return
+    }
     if (searchInputRef.current) {
       searchInputRef.current.focus()
       const len = searchConfig.value?.length ?? 0
@@ -400,8 +406,28 @@ export function UnifiedTable<TData>({
     )
   }
 
-  // Empty state
-  if (!loading && sortedData.length === 0 && emptyState) {
+  // IS THE LIST EMPTY BECAUSE THE USER NARROWED IT?
+  //
+  // `'all'` is TableFilters' own "no filter" sentinel, so a section sitting on it
+  // is not narrowing anything.
+  const hasNarrowingFilter = Object.values(filters.filters ?? {}).some((value) => {
+    if (value == null || value === '') return false
+    if (typeof value === 'string' && value.toLowerCase() === 'all') return false
+    if (Array.isArray(value)) return value.length > 0
+    return true
+  })
+  const isNarrowed = (searchConfig?.value ?? '').trim() !== '' || hasNarrowingFilter
+
+  // Empty state.
+  //
+  // REPLACING THE WHOLE TABLE IS ONLY RIGHT WHEN THERE IS NOTHING TO UNDO. A list
+  // emptied BY a search or a filter used to lose the toolbar as well — including
+  // the search box the user needs to widen it again — which turns "search for
+  // something that is not there" into a dead end with no way back but a reload.
+  // So the full replacement is kept for a genuinely empty list (unchanged for
+  // every consumer), and a narrowed empty list keeps its toolbar and filters and
+  // renders the same `emptyState` node where the rows would be.
+  if (!loading && sortedData.length === 0 && emptyState && !isNarrowed) {
     return <div className={className}>{emptyState}</div>
   }
 
@@ -421,6 +447,7 @@ export function UnifiedTable<TData>({
         }}
         searchInputRef={searchInputRef}
         searchAutoFocus={searchConfig?.autoFocus}
+        searchDebounceMs={searchConfig?.debounceMs}
         columnVisibilityEnabled={columnVisibilityConfig?.enabled}
         hideableColumns={hideableColumns}
         columnVisibility={columnVisibility}
@@ -543,6 +570,7 @@ export function UnifiedTable<TData>({
         rowActions={rowActions}
         onRowClick={onRowClick}
         loadingRows={loadingRows}
+        emptyState={emptyState}
       />
 
       {/* Pagination */}

package/src/components/unified-table/__tests__/integration/search-and-empty-state.test.tsx

@@ -0,0 +1,210 @@
+/**
+ * The two defects every foundry fork silently inherited (bd startsim-jugjd).
+ *
+ * Neither errored; both quietly produced a worse product than the consumer
+ * thought they had configured, so both are pinned here rather than left to a
+ * reviewer's eye.
+ */
+import { render, screen, fireEvent, act } from '@testing-library/react'
+import { useState } from 'react'
+import { UnifiedTable } from '../../index'
+import { ColumnConfig } from '../../types'
+
+interface Row {
+  id: string
+  name: string
+}
+
+const columns: ColumnConfig<Row>[] = [{ id: 'name', header: 'Name', accessorKey: 'name' }]
+
+const rows: Row[] = [
+  { id: '1', name: 'Alpha' },
+  { id: '2', name: 'Beta' },
+]
+
+describe('SearchConfig.debounceMs', () => {
+  beforeEach(() => jest.useFakeTimers())
+  afterEach(() => jest.useRealTimers())
+
+  function Harness({ debounceMs, onSearch }: { debounceMs?: number; onSearch: (v: string) => void }) {
+    const [value, setValue] = useState('')
+    return (
+      <UnifiedTable<Row>
+        data={rows}
+        columns={columns}
+        tableId="t"
+        getRowId={(r) => r.id}
+        search={{
+          enabled: true,
+          placeholder: 'Search…',
+          value,
+          onChange: (next) => {
+            setValue(next)
+            onSearch(next)
+          },
+          debounceMs,
+        }}
+      />
+    )
+  }
+
+  it('reports once after the pause, not once per keystroke', () => {
+    const onSearch = jest.fn()
+    render(<Harness debounceMs={200} onSearch={onSearch} />)
+    const input = screen.getByPlaceholderText('Search…') as HTMLInputElement
+
+    fireEvent.change(input, { target: { value: 'a' } })
+    fireEvent.change(input, { target: { value: 'al' } })
+    fireEvent.change(input, { target: { value: 'alp' } })
+
+    // The letters are on screen immediately — the debounce delays the REPORT,
+    // never the typing.
+    expect(input.value).toBe('alp')
+    expect(onSearch).not.toHaveBeenCalled()
+
+    act(() => { jest.advanceTimersByTime(200) })
+
+    expect(onSearch).toHaveBeenCalledTimes(1)
+    expect(onSearch).toHaveBeenCalledWith('alp')
+  })
+
+  it('does not rewind the box when the owner echoes an earlier value back', () => {
+    const onSearch = jest.fn()
+    render(<Harness debounceMs={200} onSearch={onSearch} />)
+    const input = screen.getByPlaceholderText('Search…') as HTMLInputElement
+
+    fireEvent.change(input, { target: { value: 'al' } })
+    act(() => { jest.advanceTimersByTime(200) })
+    // Keep typing while the owner's re-render for "al" lands.
+    fireEvent.change(input, { target: { value: 'alpha' } })
+    act(() => { jest.advanceTimersByTime(50) })
+
+    expect(input.value).toBe('alpha')
+  })
+
+  it('accepts a value the owner changed itself', () => {
+    function Reset() {
+      const [value, setValue] = useState('beta')
+      return (
+        <>
+          <button onClick={() => setValue('')}>clear</button>
+          <UnifiedTable<Row>
+            data={rows}
+            columns={columns}
+            tableId="t"
+            getRowId={(r) => r.id}
+            search={{
+              enabled: true,
+              placeholder: 'Search…',
+              value,
+              onChange: setValue,
+              debounceMs: 200,
+            }}
+          />
+        </>
+      )
+    }
+    render(<Reset />)
+    const input = screen.getByPlaceholderText('Search…') as HTMLInputElement
+    expect(input.value).toBe('beta')
+
+    fireEvent.click(screen.getByText('clear'))
+    expect(input.value).toBe('')
+  })
+
+  it('without debounceMs reports every keystroke, exactly as before', () => {
+    const onSearch = jest.fn()
+    render(<Harness onSearch={onSearch} />)
+    const input = screen.getByPlaceholderText('Search…') as HTMLInputElement
+
+    fireEvent.change(input, { target: { value: 'a' } })
+    fireEvent.change(input, { target: { value: 'al' } })
+
+    expect(onSearch).toHaveBeenCalledTimes(2)
+    expect(onSearch).toHaveBeenLastCalledWith('al')
+  })
+})
+
+describe('emptyState keeps the way back', () => {
+  const empty: Row[] = []
+
+  it('replaces the whole table when nothing is narrowing the list', () => {
+    render(
+      <UnifiedTable<Row>
+        data={empty}
+        columns={columns}
+        tableId="t"
+        getRowId={(r) => r.id}
+        search={{ enabled: true, placeholder: 'Search…', value: '', onChange: () => {} }}
+        emptyState={<div>Nothing here yet</div>}
+      />
+    )
+    expect(screen.getByText('Nothing here yet')).toBeInTheDocument()
+    // The unchanged behaviour: no toolbar, because there is nothing to undo.
+    expect(screen.queryByPlaceholderText('Search…')).not.toBeInTheDocument()
+  })
+
+  it('keeps the search box when the search is what emptied the list', () => {
+    render(
+      <UnifiedTable<Row>
+        data={empty}
+        columns={columns}
+        tableId="t"
+        getRowId={(r) => r.id}
+        search={{ enabled: true, placeholder: 'Search…', value: 'zzz', onChange: () => {} }}
+        emptyState={<div>No matches</div>}
+      />
+    )
+    const input = screen.getByPlaceholderText('Search…') as HTMLInputElement
+    expect(input).toBeInTheDocument()
+    expect(input.value).toBe('zzz')
+    // and the consumer's own copy is still what is shown, in the rows' place.
+    expect(screen.getByText('No matches')).toBeInTheDocument()
+  })
+
+  it('keeps the toolbar when a filter is what emptied the list', () => {
+    render(
+      <UnifiedTable<Row>
+        data={empty}
+        columns={columns}
+        tableId="t"
+        getRowId={(r) => r.id}
+        search={{ enabled: true, placeholder: 'Search…', value: '', onChange: () => {} }}
+        filters={{
+          enabled: true,
+          position: 'top',
+          collapsible: false,
+          config: { filters: [{ id: 'status', label: 'Status', type: 'select', options: ['active'] }] },
+          value: { status: 'active' },
+          onChange: () => {},
+        }}
+        emptyState={<div>No matches</div>}
+      />
+    )
+    expect(screen.getByPlaceholderText('Search…')).toBeInTheDocument()
+    expect(screen.getByText('No matches')).toBeInTheDocument()
+  })
+
+  it("treats TableFilters' own 'all' sentinel as no filter at all", () => {
+    render(
+      <UnifiedTable<Row>
+        data={empty}
+        columns={columns}
+        tableId="t"
+        getRowId={(r) => r.id}
+        search={{ enabled: true, placeholder: 'Search…', value: '', onChange: () => {} }}
+        filters={{
+          enabled: true,
+          position: 'top',
+          collapsible: false,
+          config: { filters: [{ id: 'status', label: 'Status', type: 'select', options: ['active'] }] },
+          value: { status: 'all' },
+          onChange: () => {},
+        }}
+        emptyState={<div>Nothing here yet</div>}
+      />
+    )
+    expect(screen.queryByPlaceholderText('Search…')).not.toBeInTheDocument()
+    expect(screen.getByText('Nothing here yet')).toBeInTheDocument()
+  })
+})

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

@@ -1,6 +1,6 @@
 'use client'
 
-import { useState, useCallback } from 'react'
+import { ReactNode, useState, useCallback } from 'react'
 import { Table, TableBody, TableCell, TableHead, TableHeader, TableRow } from '../../../ui/table'
 import { Checkbox } from '../../../ui/checkbox'
 import { Button } from '../../../ui/button'
@@ -51,6 +51,9 @@ interface DataTableCoreProps<TData> {
   // Loading
   loadingRows?: Set<string>
 
+  /** Shown in place of the rows when there are none. Defaults to "No results found." */
+  emptyState?: ReactNode
+
   className?: string
 }
 
@@ -78,6 +81,7 @@ export function DataTableCore<TData>({
   onCellEdit,
   rowActions,
   onRowClick,
+  emptyState,
   loadingRows = new Set(),
   className,
 }: DataTableCoreProps<TData>) {
@@ -341,7 +345,7 @@ export function DataTableCore<TData>({
                 colSpan={columns.length + (selectionEnabled ? 1 : 0) + (rowActions ? 1 : 0)}
                 className="h-24 text-center"
               >
-                No results found.
+                {emptyState ?? 'No results found.'}
               </TableCell>
             </TableRow>
           ) : (

package/src/components/unified-table/components/Toolbar/StandardTableToolbar.tsx

@@ -13,7 +13,7 @@ import { cn } from '../../../../lib/utils'
 import { ExportButton, ExportButtonProps } from './ExportButton'
 import { SavedViewsDropdown, SavedViewsDropdownProps } from './SavedViewsDropdown'
 import { ColumnConfig, ColumnVisibilityState, SavedView } from '../../types'
-import { RefObject } from 'react'
+import { RefObject, useEffect, useRef, useState } from 'react'
 
 export interface StandardTableToolbarProps<TData> {
   // Search
@@ -23,6 +23,13 @@ export interface StandardTableToolbarProps<TData> {
   onSearchChange?: (value: string) => void
   searchInputRef?: RefObject<HTMLInputElement | null>
   searchAutoFocus?: boolean
+  /**
+   * Wait this long after the last keystroke before calling `onSearchChange`.
+   * Omitted or 0 keeps the input fully controlled and reports every keystroke,
+   * which is what every consumer got before `SearchConfig.debounceMs` was wired
+   * up (it was accepted and ignored).
+   */
+  searchDebounceMs?: number
 
   // Column visibility
   columnVisibilityEnabled?: boolean
@@ -60,6 +67,7 @@ export function StandardTableToolbar<TData>({
   onSearchChange,
   searchInputRef,
   searchAutoFocus,
+  searchDebounceMs = 0,
   columnVisibilityEnabled,
   hideableColumns = [],
   columnVisibility = {},
@@ -76,6 +84,48 @@ export function StandardTableToolbar<TData>({
 }: StandardTableToolbarProps<TData>) {
   const hasRightSideButtons = exportEnabled || columnVisibilityEnabled || savedViewsEnabled
 
+  // DEBOUNCED SEARCH.
+  //
+  // A debounce cannot sit in front of `onSearchChange` alone: the input's value
+  // comes from `searchValue`, so delaying the call would also delay the letter
+  // appearing and the box would swallow keystrokes. So the input holds a DRAFT
+  // that echoes every keystroke immediately, and only the report upward waits.
+  //
+  // The draft has to yield to a value the OWNER changed (clearing a search,
+  // loading a saved view) but must NOT yield to the owner echoing back what we
+  // just sent — that echo arrives a render after the user has typed more, and
+  // accepting it would rewind the box mid-word. `emittedRef` is the difference:
+  // a prop equal to what we last emitted is our own echo and is ignored.
+  const debouncing = searchDebounceMs > 0
+  const [draft, setDraft] = useState(searchValue)
+  const emittedRef = useRef(searchValue)
+  const timerRef = useRef<ReturnType<typeof setTimeout> | null>(null)
+
+  useEffect(() => {
+    if (searchValue === emittedRef.current) return
+    emittedRef.current = searchValue
+    setDraft(searchValue)
+  }, [searchValue])
+
+  // A pending keystroke must not fire into an unmounted tree.
+  useEffect(() => () => {
+    if (timerRef.current) clearTimeout(timerRef.current)
+  }, [])
+
+  const handleSearchInput = (value: string) => {
+    if (!debouncing) {
+      onSearchChange?.(value)
+      return
+    }
+    setDraft(value)
+    if (timerRef.current) clearTimeout(timerRef.current)
+    timerRef.current = setTimeout(() => {
+      timerRef.current = null
+      emittedRef.current = value
+      onSearchChange?.(value)
+    }, searchDebounceMs)
+  }
+
   return (
     <div className={cn('flex items-center justify-between gap-4', className)}>
       {/* Left side: Search */}
@@ -84,8 +134,8 @@ export function StandardTableToolbar<TData>({
           <Input
             type="text"
             placeholder={searchPlaceholder}
-            value={searchValue}
-            onChange={(e) => onSearchChange?.(e.target.value)}
+            value={debouncing ? draft : searchValue}
+            onChange={(e) => handleSearchInput(e.target.value)}
             ref={searchInputRef}
             autoFocus={searchAutoFocus}
             className="max-w-xl w-full"

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

@@ -1,5 +1,6 @@
 import * as XLSX from 'xlsx'
 import { ColumnConfig } from '../types'
+import { csvFromRows, downloadBlob, downloadCsv } from '../../../utils/csv'
 
 export type ExportFormat = 'csv' | 'excel'
 
@@ -91,40 +92,8 @@ function prepareExportData<TData>(
   return rows
 }
 
-/**
- * Converts array data to CSV string
- */
-function arrayToCSV(data: string[][]): string {
-  return data
-    .map(row =>
-      row
-        .map(cell => {
-          // Escape quotes and wrap in quotes if contains comma, quote, or newline
-          const needsQuotes = /[,"\n\r]/.test(cell)
-          if (needsQuotes) {
-            return `"${cell.replace(/"/g, '""')}"`
-          }
-          return cell
-        })
-        .join(',')
-    )
-    .join('\n')
-}
-
-/**
- * Triggers a download of the given content
- */
-function downloadFile(content: string | Blob, filename: string, mimeType: string): void {
-  const blob = content instanceof Blob ? content : new Blob([content], { type: mimeType })
-  const url = URL.createObjectURL(blob)
-  const link = document.createElement('a')
-  link.href = url
-  link.download = filename
-  document.body.appendChild(link)
-  link.click()
-  document.body.removeChild(link)
-  URL.revokeObjectURL(url)
-}
+// Quoting, the formula guard and the line ending all live in one place now —
+// see ../../../utils/csv. A second copy here is how the two drift.
 
 /**
  * Exports data to CSV format
@@ -148,9 +117,8 @@ export function exportToCSV<TData>(
   }
 
   const exportData = prepareExportData(data, columns, includeHeaders)
-  const csv = arrayToCSV(exportData)
 
-  downloadFile(csv, `${filename}.csv`, 'text/csv;charset=utf-8;')
+  downloadCsv(`${filename}.csv`, csvFromRows(exportData))
 }
 
 /**
@@ -198,7 +166,7 @@ export function exportToExcel<TData>(
     type: 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet'
   })
 
-  downloadFile(blob, `${filename}.xlsx`, blob.type)
+  downloadBlob(`${filename}.xlsx`, blob)
 }
 
 /**