@talelk/newui-organisms 2.0.0 → 2.1.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@talelk/newui-organisms",
-  "version": "2.0.0",
+  "version": "2.1.0",
   "type": "module",
   "description": "Application regions, sidebars, tables and widgets built from atoms and molecules.",
   "exports": {
@@ -11,11 +11,12 @@
     }
   },
   "files": [
-    "src"
+    "src",
+    "skills/newui-organisms"
   ],
   "dependencies": {
-    "@talelk/newui-atoms": "1.0.1",
-    "@talelk/newui-molecules": "2.0.0",
+    "@talelk/newui-atoms": "1.1.0",
+    "@talelk/newui-molecules": "2.1.0",
     "@tanstack/solid-table": "^9.3.1",
     "@tanstack/solid-virtual": "^3.13.47"
   },
@@ -35,6 +36,9 @@
     "url": "git+https://github.com/talelk/newui.git",
     "directory": "packages/organisms"
   },
+  "keywords": [
+    "tanstack-intent"
+  ],
   "scripts": {
     "typecheck": "tsc --noEmit -p tsconfig.json"
   }

package/skills/newui-organisms/SKILL.md

@@ -0,0 +1,91 @@
+---
+name: newui-organisms
+description: >
+  Use when composing page regions with @talelk/newui-organisms — DataTable
+  (search, sort, pagination, selection, column pinning, inline editing),
+  AppSidebar, Sidebar, FilterBar, StatGrid, KanbanBoard, VirtualList,
+  CommandPalette, DetailHeader, Section, SelectionBar, DataState, MobileNav,
+  AuthCard, SettingsDialog. Use when the user asks for a data table, app
+  sidebar, board, KPI grid or command palette in newui.
+metadata:
+  type: core
+  domain: ui
+  library: '@talelk/newui-organisms'
+  library_version: '2.1.0'
+sources:
+  - talelk/newui:packages/organisms/src/organisms/DataTable/DataTable.tsx
+  - talelk/newui:packages/organisms/src/organisms/AppSidebar/AppSidebar.tsx
+  - talelk/newui:packages/organisms/src/organisms/DataState/DataState.tsx
+  - talelk/newui:packages/organisms/src/organisms/SelectionBar/SelectionBar.tsx
+  - talelk/newui:spec/data-table.md
+  - talelk/newui:spec/sidebar.md
+---
+
+# newui organisms
+
+Page regions composed from the molecules and atoms. Read the `newui` skill
+for the token vocabulary first.
+
+## Setup
+
+```tsx no-check
+import { DataTable } from '@talelk/newui-organisms'
+import { createSignal } from 'solid-js'
+
+interface Row { id: string; title: string; amount: number }
+
+export function Ledger(props: { rows: Row[] }) {
+  return (
+    <DataTable
+      title="Ledger"
+      rows={props.rows}
+      columns={[
+        { accessorKey: 'id', header: 'Ref' },
+        { accessorKey: 'title', header: 'Title' },
+        { accessorKey: 'amount', header: 'Amount', meta: { align: 'end' } },
+      ]}
+      actionLabel="Export selected"
+      onRowsAction={(ids) => exportRows(ids)}
+    />
+  )
+}
+```
+
+## Core patterns
+
+**Selection exists to feed the bulk action.** Checkboxes render only when
+`onRowsAction` is set; a read table sets `selectable={false}` (or omits the
+action).
+
+**App-owned states: pinning, edits, data.** `pinnedStart`/`pinnedEnd` freeze
+one column per scroll edge; pinning changes go through
+`onPinnedColumnsChange` — the table never mutates it. With `editable` +
+`onCellChange`, columns marked `meta.editable` render click-to-edit cells;
+edits commit through the callback and the table shows whatever the next
+`rows` carry. The table never mutates data itself.
+
+**Loading, empty and error come from `DataState`, not ad-hoc markup.** Pass
+`loading`, `error` + `onRetry` to `DataTable` (or wrap custom regions in
+`DataState`); the shared surfaces keep the sweep's contracts.
+
+**One sidebar model.** `AppShell` (templates) renders `AppSidebar` for you —
+do not mount `Sidebar` beside it. Compose `Sidebar` directly only in pages
+that are not `AppShell`-shaped.
+
+## Common mistakes
+
+**Don't nest AppShell and Sidebar.** Two navigation regions fail the a11y
+sweep's `no-duplicate-controls` rule.
+
+**Don't format values in editable columns' raw fields.** `meta.editable`
+edits the row's raw field; the formatted `cell` render returns after commit.
+Editing a formatted string would corrupt it.
+
+**Don't build sticky columns by hand.** Pinning already carries the sticky
+chrome, divider and hover/selected tint; a hand-rolled `sticky` cell will
+miss the row tint and fail the visual contract.
+
+## Completion
+
+`pnpm verify:affected` covers the organisms suites; `spec/data-table.md` and
+`spec/sidebar.md` are the contracts for the two largest regions.

package/src/exports.test.ts

@@ -5,6 +5,7 @@ const PUBLIC = [
   'AppSidebar',
   'AuthCard',
   'CommandPalette',
+  'DataState',
   'DataTable',
   'DetailHeader',
   'FilterBar',
@@ -12,6 +13,8 @@ const PUBLIC = [
   'MobileNav',
   'PageToolbar',
   'SettingsDialog',
+  'Section',
+  'SelectionBar',
   'Sidebar',
   'StatGrid',
   'VirtualList',

package/src/organisms/AppSidebar/AppSidebar.a11y.test.tsx

@@ -0,0 +1,75 @@
+import { render } from '@solidjs/testing-library'
+import axe, { type AxeResults } from 'axe-core'
+import { describe, expect, it } from 'vitest'
+import { SidebarItem } from '../Sidebar'
+import { AppSidebar } from './AppSidebar'
+
+const AXE_OPTIONS = {
+  rules: {
+    'color-contrast': { enabled: false },
+    region: { enabled: false },
+  },
+}
+
+function summarize(results: AxeResults) {
+  return results.violations.map((violation) => ({
+    id: violation.id,
+    impact: violation.impact,
+    targets: violation.nodes.map((node) => node.target),
+  }))
+}
+
+function workspace(props: { collapsed?: boolean } = {}) {
+  return (
+    <AppSidebar
+      brand={<span>Acme workspace</span>}
+      brandCollapsed={
+        <span>
+          <span class="sr-only">Acme home</span>A
+        </span>
+      }
+      tenant={<button type="button">Acme · Production</button>}
+      tenantCollapsed={
+        <button type="button" aria-label="Switch tenant">
+          A
+        </button>
+      }
+      collapsed={props.collapsed}
+      groups={[
+        {
+          label: 'Workspace',
+          items: [
+            { label: 'Projects', icon: 'lucide-folder-kanban', active: true },
+            { label: 'Customers', icon: 'lucide-users', count: 4 },
+          ],
+        },
+        {
+          label: 'Reports',
+          items: [{ label: 'Revenue', icon: 'lucide-chart-no-axes-combined' }],
+        },
+      ]}
+      settings={
+        <SidebarItem label="Settings" icon="lucide-settings">
+          Settings
+        </SidebarItem>
+      }
+      account={
+        <SidebarItem label="Rhea Kapoor" icon="lucide-user-round">
+          Rhea Kapoor
+        </SidebarItem>
+      }
+    />
+  )
+}
+
+describe('AppSidebar accessibility', () => {
+  it('has no axe violations for the expanded navigation', async () => {
+    const { container } = render(() => workspace())
+    expect(summarize(await axe.run(container, AXE_OPTIONS))).toEqual([])
+  })
+
+  it('has no axe violations for the collapsed rail', async () => {
+    const { container } = render(() => workspace({ collapsed: true }))
+    expect(summarize(await axe.run(container, AXE_OPTIONS))).toEqual([])
+  })
+})

package/src/organisms/CommandPalette/CommandPalette.a11y.test.tsx

@@ -0,0 +1,58 @@
+import { render } from '@solidjs/testing-library'
+import axe, { type AxeResults } from 'axe-core'
+import { describe, expect, it } from 'vitest'
+import { CommandGroup, CommandItem, CommandPalette } from './CommandPalette'
+
+const AXE_OPTIONS = {
+  rules: {
+    'color-contrast': { enabled: false },
+    region: { enabled: false },
+  },
+}
+
+function summarize(results: AxeResults) {
+  return results.violations.map((violation) => ({
+    id: violation.id,
+    impact: violation.impact,
+    targets: violation.nodes.map((node) => node.target),
+  }))
+}
+
+describe('CommandPalette accessibility', () => {
+  it('has no axe violations for an open palette of grouped commands', async () => {
+    // The dialog portals to the body, so the audit runs there — the same
+    // shape the SettingsDialog a11y test uses.
+    render(() => (
+      <CommandPalette defaultOpen label="Commands">
+        <CommandGroup label="Pages">
+          <CommandItem value="intro" icon="lucide-house">
+            Introduction
+          </CommandItem>
+          <CommandItem value="blocks" keywords="patterns sections">
+            Blocks
+          </CommandItem>
+        </CommandGroup>
+        <CommandGroup label="Actions">
+          <CommandItem value="theme" shortcut="⌘B">
+            Toggle theme
+          </CommandItem>
+          <CommandItem value="soon" disabled>
+            Coming soon
+          </CommandItem>
+        </CommandGroup>
+      </CommandPalette>
+    ))
+    expect(summarize(await axe.run(document.body, AXE_OPTIONS))).toEqual([])
+  })
+
+  it('has no axe violations while commands are loading', async () => {
+    render(() => (
+      <CommandPalette defaultOpen label="Commands" loading>
+        <CommandGroup label="Pages">
+          <CommandItem value="intro">Introduction</CommandItem>
+        </CommandGroup>
+      </CommandPalette>
+    ))
+    expect(summarize(await axe.run(document.body, AXE_OPTIONS))).toEqual([])
+  })
+})

package/src/organisms/DataState/DataState.a11y.test.tsx

@@ -0,0 +1,59 @@
+import { render } from '@solidjs/testing-library'
+import axe, { type AxeResults } from 'axe-core'
+import { describe, expect, it } from 'vitest'
+import { DataState } from './DataState'
+
+const AXE_OPTIONS = {
+  rules: {
+    'color-contrast': { enabled: false },
+    region: { enabled: false },
+  },
+}
+
+function summarize(results: AxeResults) {
+  return results.violations.map((violation) => ({
+    id: violation.id,
+    impact: violation.impact,
+    targets: violation.nodes.map((node) => node.target),
+  }))
+}
+
+describe('DataState accessibility', () => {
+  it('has no axe violations while loading', async () => {
+    const { container } = render(() => (
+      <DataState status="loading" skeleton="cards" />
+    ))
+    expect(summarize(await axe.run(container, AXE_OPTIONS))).toEqual([])
+  })
+
+  it('has no axe violations for the empty state', async () => {
+    const { container } = render(() => (
+      <DataState
+        status="empty"
+        title="No expenses"
+        description="Try a different month."
+        action={<button type="button">Clear filters</button>}
+      />
+    ))
+    expect(summarize(await axe.run(container, AXE_OPTIONS))).toEqual([])
+  })
+
+  it('has no axe violations for the error state', async () => {
+    const { container } = render(() => (
+      <DataState status="error" error="The request failed" onRetry={() => {}} />
+    ))
+    expect(summarize(await axe.run(container, AXE_OPTIONS))).toEqual([])
+  })
+
+  it('has no axe violations when ready', async () => {
+    const { container } = render(() => (
+      <DataState status="ready">
+        <ul>
+          <li>Alpha</li>
+          <li>Beta</li>
+        </ul>
+      </DataState>
+    ))
+    expect(summarize(await axe.run(container, AXE_OPTIONS))).toEqual([])
+  })
+})

package/src/organisms/DataState/DataState.browser.test.tsx

@@ -0,0 +1,52 @@
+import { render } from '@solidjs/testing-library'
+import { describe, expect, it } from 'vitest'
+import { DataState } from './DataState'
+
+function nextFrame() {
+  return new Promise((resolve) => requestAnimationFrame(() => resolve(null)))
+}
+
+describe('DataState (browser, real CSS)', () => {
+  it('renders loading skeletons as real painted rows', async () => {
+    const { container } = render(() => (
+      <DataState status="loading" skeleton="rows" rows={3} />
+    ))
+    await nextFrame()
+    const rows = container.querySelectorAll(
+      '[data-slot="skeleton"]',
+    ) as unknown as HTMLElement[]
+    expect(rows.length).toBe(3)
+    const row = rows[0] as HTMLElement
+    // `h-9` per row — a dropped height utility collapses the placeholder.
+    expect(row.getBoundingClientRect().height).toBeGreaterThanOrEqual(32)
+    // The paint lives on the shimmering line inside the row wrapper.
+    const line = row.querySelector('[data-slot="skeleton-line"]') as HTMLElement
+    expect(line).toBeTruthy()
+    expect(getComputedStyle(line).backgroundColor).not.toBe('rgba(0, 0, 0, 0)')
+  })
+
+  it('paints the empty state icon tile', () => {
+    const { container } = render(() => (
+      <DataState status="empty" title="No expenses" />
+    ))
+    const tile = container.querySelector(
+      '[data-slot="empty-state-icon"]',
+    ) as HTMLElement
+    expect(tile.getBoundingClientRect().width).toBeGreaterThan(0)
+    expect(getComputedStyle(tile).backgroundColor).not.toBe('rgba(0, 0, 0, 0)')
+  })
+
+  it('keeps the retry button a real target', async () => {
+    const { container } = render(() => (
+      <DataState status="error" error="The request failed" onRetry={() => {}} />
+    ))
+    await nextFrame()
+    const button = Array.from(container.querySelectorAll('button')).find(
+      (node) => node.textContent === 'Try again',
+    ) as HTMLElement
+    expect(button.getBoundingClientRect().height).toBeGreaterThanOrEqual(24)
+    expect(getComputedStyle(button).backgroundColor).not.toBe(
+      'rgba(0, 0, 0, 0)',
+    )
+  })
+})

package/src/organisms/DataTable/DataTable.a11y.test.tsx

@@ -0,0 +1,71 @@
+import { render } from '@solidjs/testing-library'
+import axe, { type AxeResults } from 'axe-core'
+import { describe, expect, it } from 'vitest'
+import { DataTable, type DataTableColumn } from './DataTable'
+
+const AXE_OPTIONS = {
+  rules: {
+    'color-contrast': { enabled: false },
+    region: { enabled: false },
+  },
+}
+
+function summarize(results: AxeResults) {
+  return results.violations.map((violation) => ({
+    id: violation.id,
+    impact: violation.impact,
+    targets: violation.nodes.map((node) => node.target),
+  }))
+}
+
+interface Row {
+  id: string
+  name: string
+  amount: number
+}
+
+const ROWS: Row[] = [
+  { id: '1', name: 'Alpha', amount: 10 },
+  { id: '2', name: 'Beta', amount: 20 },
+  { id: '3', name: 'Gamma', amount: 30 },
+]
+
+const COLUMNS: DataTableColumn<Row>[] = [
+  { accessorKey: 'name', header: 'Name' },
+  {
+    accessorKey: 'amount',
+    header: 'Amount',
+    cell: (context) => `$${context.getValue()}`,
+    meta: { align: 'end' },
+  },
+]
+
+describe('DataTable accessibility', () => {
+  it('has no axe violations for a selectable table', async () => {
+    const { container } = render(() => (
+      <DataTable
+        title="Expenses"
+        rows={ROWS}
+        columns={COLUMNS}
+        pageSize={10}
+        actionLabel="Approve"
+        onRowsAction={() => {}}
+        recordsLabel="expenses"
+      />
+    ))
+    expect(summarize(await axe.run(container, AXE_OPTIONS))).toEqual([])
+  })
+
+  it('has no axe violations for a read-only table', async () => {
+    const { container } = render(() => (
+      <DataTable
+        title="Expenses"
+        rows={ROWS}
+        columns={COLUMNS}
+        pageSize={10}
+        selectable={false}
+      />
+    ))
+    expect(summarize(await axe.run(container, AXE_OPTIONS))).toEqual([])
+  })
+})

package/src/organisms/DataTable/DataTable.features.test.tsx

@@ -0,0 +1,191 @@
+import { render, screen } from '@solidjs/testing-library'
+import userEvent from '@testing-library/user-event'
+import { createSignal } from 'solid-js'
+import { describe, expect, it, vi } from 'vitest'
+import { DataTable, type DataTableColumn } from './DataTable'
+
+interface Row {
+  id: string
+  name: string
+  amount: number
+}
+
+const ROWS: Row[] = [
+  { id: '1', name: 'Alpha', amount: 10 },
+  { id: '2', name: 'Beta', amount: 20 },
+]
+
+const COLUMNS: DataTableColumn<Row>[] = [
+  { accessorKey: 'name', header: 'Name' },
+  {
+    accessorKey: 'amount',
+    header: 'Amount',
+    meta: { align: 'end', editable: true, editInput: 'number' },
+  },
+]
+
+describe('DataTable pinning', () => {
+  it('freezes the named columns to each scroll edge', () => {
+    const { container } = render(() => (
+      <DataTable
+        title="Rows"
+        rows={ROWS}
+        columns={COLUMNS}
+        pageSize={10}
+        selectable={false}
+        pinnedStart="name"
+        pinnedEnd="amount"
+      />
+    ))
+    const head = container.querySelector('thead') as HTMLElement
+    const startTh = head.querySelector('th[scope="col"]') as HTMLElement
+    expect(startTh.className).toContain('sticky')
+    expect(startTh.className).toContain('start-0')
+    const endTh = head.querySelectorAll('th[scope="col"]')[1] as HTMLElement
+    expect(endTh.className).toContain('end-0')
+    // Body cells carry the same stickiness as their header.
+    const firstTd = container.querySelector('tbody td') as HTMLElement
+    expect(firstTd.className).toContain('sticky')
+  })
+
+  it('leaves unpinned tables in plain flow', () => {
+    const { container } = render(() => (
+      <DataTable
+        title="Rows"
+        rows={ROWS}
+        columns={COLUMNS}
+        pageSize={10}
+        selectable={false}
+      />
+    ))
+    const th = container.querySelector('th[scope="col"]') as HTMLElement
+    expect(th.className).not.toContain('sticky')
+  })
+
+  it('answers onPinnedColumnsChange only from the app (no in-table UI mutates pinning)', () => {
+    const onPinnedColumnsChange = vi.fn()
+    render(() => (
+      <DataTable
+        title="Rows"
+        rows={ROWS}
+        columns={COLUMNS}
+        pageSize={10}
+        selectable={false}
+        pinnedStart="name"
+        onPinnedColumnsChange={onPinnedColumnsChange}
+      />
+    ))
+    // Sorting (the only in-table toggle) does not move pinning.
+    const sortButton = screen.getByRole('button', { name: /Name/ })
+    userEvent.click(sortButton)
+    expect(onPinnedColumnsChange).not.toHaveBeenCalled()
+  })
+})
+
+describe('DataTable inline editing', () => {
+  it('renders a click-to-edit cell that reports the raw value', async () => {
+    const onCellChange = vi.fn()
+    const { container } = render(() => (
+      <DataTable
+        title="Rows"
+        rows={ROWS}
+        columns={COLUMNS}
+        pageSize={10}
+        selectable={false}
+        editable
+        onCellChange={onCellChange}
+      />
+    ))
+    const trigger = screen.getByRole('button', {
+      name: /— edit Amount of 1$/,
+    })
+    expect(trigger.textContent).toBe('10')
+    await userEvent.click(trigger)
+    const input = screen.getByRole('spinbutton', {
+      name: 'Edit Amount of 1',
+    }) as HTMLInputElement
+    expect(document.activeElement).toBe(input)
+    await userEvent.clear(input)
+    await userEvent.type(input, '15{Enter}')
+    expect(onCellChange).toHaveBeenCalledWith('1', 'amount', '15')
+    // The edit trigger is gone once editing closes.
+    expect(
+      container.querySelector('[data-slot="data-table-edit-trigger"]'),
+    ).toBeTruthy()
+  })
+
+  it('escapes an edit without reporting', async () => {
+    const onCellChange = vi.fn()
+    render(() => (
+      <DataTable
+        title="Rows"
+        rows={ROWS}
+        columns={COLUMNS}
+        pageSize={10}
+        selectable={false}
+        editable
+        onCellChange={onCellChange}
+      />
+    ))
+    await userEvent.click(
+      screen.getByRole('button', { name: /— edit Amount of 1$/ }),
+    )
+    await userEvent.keyboard('999{Escape}')
+    expect(onCellChange).not.toHaveBeenCalled()
+    // The cell shows the untouched value again.
+    expect(
+      screen.getByRole('button', { name: /— edit Amount of 1$/ }).textContent,
+    ).toBe('10')
+  })
+
+  it('renders the updated value when the app owns the mutation', async () => {
+    const [rows, setRows] = createSignal<Row[]>(ROWS)
+    const { container } = render(() => (
+      <DataTable
+        title="Rows"
+        rows={rows()}
+        columns={COLUMNS}
+        pageSize={10}
+        selectable={false}
+        editable
+        onCellChange={(id, columnId, value) =>
+          setRows((current) =>
+            current.map((row) =>
+              row.id === id ? { ...row, [columnId]: Number(value) } : row,
+            ),
+          )
+        }
+      />
+    ))
+    await userEvent.click(
+      screen.getByRole('button', { name: /— edit Amount of 2$/ }),
+    )
+    const input = screen.getByRole('spinbutton', {
+      name: 'Edit Amount of 2',
+    }) as HTMLInputElement
+    await userEvent.clear(input)
+    await userEvent.type(input, '25{Enter}')
+    await new Promise((resolve) => setTimeout(resolve, 0))
+    // The editor closed onto the app-owned new value.
+    const body = container.querySelector('tbody') as HTMLElement
+    expect(body.textContent).toContain('25')
+    expect(
+      screen.queryByRole('spinbutton', { name: 'Edit Amount of 2' }),
+    ).toBeNull()
+  })
+
+  it('renders plain cells when not editable', () => {
+    render(() => (
+      <DataTable
+        title="Rows"
+        rows={ROWS}
+        columns={COLUMNS}
+        pageSize={10}
+        selectable={false}
+      />
+    ))
+    expect(
+      screen.queryByRole('button', { name: /— edit Amount of 1$/ }),
+    ).toBeNull()
+  })
+})