@talelk/newui-organisms 1.0.0 → 2.1.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@talelk/newui-organisms",
-  "version": "1.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.0",
-    "@talelk/newui-molecules": "1.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/AppSidebar/AppSidebar.test.tsx

@@ -69,6 +69,42 @@ describe('AppSidebar', () => {
     expect(screen.getByRole('button', { name: /Rhea Kapoor/ })).toBeTruthy()
   })
 
+  it('keeps a compact utility slot and an expand control in the rail', () => {
+    render(() => (
+      <AppSidebar
+        brand={<span>Acme</span>}
+        collapsed
+        utilities={<span>Preferences</span>}
+        utilitiesCollapsed={<button type="button">Theme</button>}
+        groups={[{ items: [] }]}
+      />
+    ))
+    expect(screen.queryByText('Preferences')).toBeNull()
+    expect(screen.getByRole('button', { name: 'Theme' })).toBeTruthy()
+    expect(screen.getByRole('button', { name: /Expand sidebar/ })).toBeTruthy()
+    expect(
+      screen.queryByRole('button', { name: /Collapse sidebar/ }),
+    ).toBeNull()
+  })
+
+  it('has no fold or compact utilities when it cannot collapse', () => {
+    render(() => (
+      <AppSidebar
+        brand={<span>Acme</span>}
+        collapsible={false}
+        utilities={<span>Preferences</span>}
+        utilitiesCollapsed={<button type="button">Theme</button>}
+        groups={[{ items: [] }]}
+      />
+    ))
+    expect(screen.getByText('Preferences')).toBeTruthy()
+    expect(screen.queryByRole('button', { name: 'Theme' })).toBeNull()
+    expect(screen.queryByRole('button', { name: /Expand sidebar/ })).toBeNull()
+    expect(
+      screen.queryByRole('button', { name: /Collapse sidebar/ }),
+    ).toBeNull()
+  })
+
   it('collapses labels, preserves a compact tenant control and reports the state', async () => {
     const onCollapsedChange = vi.fn()
     sidebar(onCollapsedChange)

package/src/organisms/AppSidebar/AppSidebar.tsx

@@ -2,10 +2,10 @@ import { type IconProp, ScrollArea } from '@talelk/newui-atoms'
 import { For, type JSX, Show } from 'solid-js'
 import {
   Sidebar,
-  SidebarCollapseToggle,
   SidebarItem,
   SidebarLabel,
   type SidebarProps,
+  SidebarTrigger,
   useSidebar,
 } from '../Sidebar'
 
@@ -44,6 +44,10 @@ export interface AppSidebarProps {
   groups?: AppSidebarGroup[]
   /** Advanced navigation composition, still inside this single sidebar. */
   children?: JSX.Element | (() => JSX.Element)
+  /** Global utilities rendered above Settings while the sidebar is expanded. */
+  utilities?: JSX.Element
+  /** Compact icon form of `utilities`, shown while the sidebar is collapsed. */
+  utilitiesCollapsed?: JSX.Element
   settings?: JSX.Element
   account?: JSX.Element
   accountCollapsed?: JSX.Element
@@ -78,13 +82,29 @@ function AppSidebarIdentity(props: {
   brandCollapsed?: JSX.Element
   tenant?: JSX.Element
   tenantCollapsed?: JSX.Element
+  collapsible: boolean
 }): JSX.Element {
   const { collapsed } = useSidebar()
   return (
     <>
-      <div data-slot="app-sidebar-brand" class="shrink-0 px-2 pt-3 pb-2">
-        <Show when={collapsed()} fallback={props.brand}>
-          {props.brandCollapsed ?? props.brand}
+      <div
+        data-slot="app-sidebar-brand"
+        class="flex h-12 shrink-0 items-center gap-1 ps-2 pe-1"
+        classList={{ 'justify-center px-1': collapsed() }}
+      >
+        <div
+          class="flex min-w-0 flex-1 items-center"
+          classList={{ 'justify-center': collapsed() }}
+        >
+          <Show when={collapsed()} fallback={props.brand}>
+            {props.brandCollapsed ?? props.brand}
+          </Show>
+        </div>
+        {/* The fold is chrome, not a destination: keeping it in the identity
+            row keeps it out of the menu in the expanded state; the rail
+            repeats the same control under the tenant. */}
+        <Show when={!collapsed() && props.collapsible}>
+          <SidebarTrigger />
         </Show>
       </div>
       <Show when={props.tenant}>
@@ -92,30 +112,50 @@ function AppSidebarIdentity(props: {
           data-slot="app-sidebar-tenant"
           data-keep-drawer
           class="shrink-0 px-2 pb-2"
+          classList={{ 'flex justify-center': collapsed() }}
         >
           <Show when={collapsed()} fallback={props.tenant}>
             {props.tenantCollapsed}
           </Show>
         </div>
       </Show>
+      <Show when={collapsed() && props.collapsible}>
+        <div
+          data-slot="app-sidebar-expand"
+          class="flex shrink-0 justify-center border-b border-outline-gray-1 px-2 pt-1 pb-2"
+        >
+          <SidebarTrigger />
+        </div>
+      </Show>
     </>
   )
 }
 
 function AppSidebarFooter(props: {
+  utilities?: JSX.Element
+  utilitiesCollapsed?: JSX.Element
   settings?: JSX.Element
   account?: JSX.Element
   accountCollapsed?: JSX.Element
-  collapsible: boolean
 }): JSX.Element {
   const { collapsed } = useSidebar()
   return (
     <div
       data-slot="app-sidebar-footer"
-      class="mt-auto flex shrink-0 flex-col gap-1 px-2 pt-2 pb-2"
+      class="mt-auto flex shrink-0 flex-col gap-1 border-t border-outline-gray-1 px-2 pt-2 pb-2"
     >
-      <Show when={props.collapsible}>
-        <SidebarCollapseToggle />
+      <Show when={!collapsed() && props.utilities}>
+        <div data-slot="app-sidebar-utilities" class="pb-1">
+          {props.utilities}
+        </div>
+      </Show>
+      <Show when={collapsed() && props.utilitiesCollapsed}>
+        <div
+          data-slot="app-sidebar-utilities"
+          class="flex justify-center pb-0.5"
+        >
+          {props.utilitiesCollapsed}
+        </div>
       </Show>
       <Show when={props.settings}>{props.settings}</Show>
       <Show
@@ -136,7 +176,6 @@ export function AppSidebar(props: AppSidebarProps): JSX.Element {
       collapsed={props.collapsed}
       onCollapsedChange={props.onCollapsedChange}
       collapsible={props.collapsible}
-      shortcut={false}
       ariaLabel={props.ariaLabel ?? 'Application navigation'}
       class={props.class}
     >
@@ -145,6 +184,7 @@ export function AppSidebar(props: AppSidebarProps): JSX.Element {
         brandCollapsed={props.brandCollapsed}
         tenant={props.tenant}
         tenantCollapsed={props.tenantCollapsed}
+        collapsible={props.collapsible !== false}
       />
 
       <Show when={props.search}>
@@ -174,14 +214,18 @@ export function AppSidebar(props: AppSidebarProps): JSX.Element {
                         {(item) => (
                           <SidebarItem
                             active={item.active}
-                            label={item.label}
+                            label={
+                              item.count
+                                ? `${item.label}, ${item.count}`
+                                : item.label
+                            }
                             icon={item.icon}
                             route={item.route}
                             href={item.href}
                             onClick={() => item.onClick?.()}
                             suffix={
                               item.count ? (
-                                <span class="rounded-full bg-surface-gray-2 px-1.5 py-px text-caption tabular-nums text-ink-gray-7">
+                                <span class="rounded-full bg-surface-gray-2 px-1.5 py-px text-caption tabular-nums text-ink-gray-7 group-data-[active]:bg-surface-blue-2 group-data-[active]:text-ink-blue-8">
                                   {item.count}
                                 </span>
                               ) : undefined
@@ -204,10 +248,11 @@ export function AppSidebar(props: AppSidebarProps): JSX.Element {
       </ScrollArea.Root>
 
       <AppSidebarFooter
+        utilities={props.utilities}
+        utilitiesCollapsed={props.utilitiesCollapsed}
         settings={props.settings}
         account={props.account}
         accountCollapsed={props.accountCollapsed}
-        collapsible={props.collapsible !== false}
       />
     </Sidebar>
   )

package/src/organisms/AuthCard/AuthCard.tsx

@@ -13,6 +13,8 @@ export interface AuthCardProps {
   description?: JSX.Element
   /** The form itself — fields and the submit button. */
   children: JSX.Element
+  /** Form-level failure summary, above the fields. */
+  error?: JSX.Element
   /** Social sign-in buttons, in order. */
   providers?: AuthProvider[]
   /** The line under the form: "Don't have an account? Sign up". */
@@ -38,43 +40,50 @@ export function AuthCard(props: AuthCardProps): JSX.Element {
   return (
     <div
       data-slot="auth-card"
-      class={`flex min-h-screen items-center justify-center bg-surface-base px-4 py-12 ${props.class ?? ''}`}
+      class={`flex w-full max-w-sm flex-col gap-section-gap rounded-card border border-outline-gray-1 bg-surface-elevation-1 p-card-pad-wide ${props.class ?? ''}`}
     >
-      <div class="flex w-full max-w-sm flex-col gap-section-gap rounded-card border border-outline-gray-1 bg-surface-elevation-1 p-card-pad-wide shadow-sm">
-        <div class="flex flex-col items-center gap-3 text-center">
-          <Show when={props.logo}>{props.logo}</Show>
-          <div class="flex flex-col gap-1">
-            <h1 class="text-metric text-ink-gray-9">{props.title}</h1>
-            <Show when={props.description}>
-              <p class="text-base text-ink-gray-7">{props.description}</p>
-            </Show>
-          </div>
+      <div class="flex flex-col items-center gap-3 text-center">
+        <Show when={props.logo}>{props.logo}</Show>
+        <div class="flex flex-col gap-1">
+          <h1 class="text-heading text-ink-gray-9">{props.title}</h1>
+          <Show when={props.description}>
+            <p class="text-base text-ink-gray-7">{props.description}</p>
+          </Show>
         </div>
+      </div>
 
-        <div class="flex flex-col gap-4">{props.children}</div>
+      <Show when={props.error}>
+        <div
+          role="alert"
+          class="rounded-control border border-outline-red-3 bg-surface-red-1 px-3 py-2 text-interface text-ink-red-8"
+        >
+          {props.error}
+        </div>
+      </Show>
 
-        <Show when={hasProviders()}>
-          <Divider label="or" />
-          <div class="flex flex-col gap-2">
-            <For each={props.providers}>
-              {(provider) => (
-                <Button
-                  variant="outline"
-                  theme="gray"
-                  onClick={provider.onClick}
-                  iconLeft={provider.icon}
-                >
-                  {provider.label}
-                </Button>
-              )}
-            </For>
-          </div>
-        </Show>
+      <div class="flex flex-col gap-4">{props.children}</div>
 
-        <Show when={props.footer}>
-          <p class="text-center text-base text-ink-gray-7">{props.footer}</p>
-        </Show>
-      </div>
+      <Show when={hasProviders()}>
+        <Divider label="or" />
+        <div class="flex flex-col gap-2">
+          <For each={props.providers}>
+            {(provider) => (
+              <Button
+                variant="outline"
+                theme="gray"
+                onClick={provider.onClick}
+                iconLeft={provider.icon}
+              >
+                {provider.label}
+              </Button>
+            )}
+          </For>
+        </div>
+      </Show>
+
+      <Show when={props.footer}>
+        <p class="text-center text-base text-ink-gray-7">{props.footer}</p>
+      </Show>
     </div>
   )
 }

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/CommandPalette/CommandPalette.tsx

@@ -121,6 +121,8 @@ export interface CommandPaletteProps {
   size?: 'sm' | 'md' | 'lg' | 'xl'
   /** Rendered when nothing matches. */
   empty?: JSX.Element
+  /** Replaces the list with a loading row while commands register. */
+  loading?: boolean
   class?: string
   children: JSX.Element
 }
@@ -306,8 +308,17 @@ export function CommandPalette(props: CommandPaletteProps): JSX.Element {
                 so hiding the list until the registry is non-empty deadlocks —
                 no items, so no registry, so the empty state, forever.
               */}
-              {props.children}
-              <Show when={isEmpty()}>
+              <Show when={!props.loading}>{props.children}</Show>
+              <Show when={props.loading}>
+                <div
+                  role="option"
+                  aria-disabled="true"
+                  class="px-2 py-6 text-center text-base text-ink-gray-6"
+                >
+                  Loading commands…
+                </div>
+              </Show>
+              <Show when={!props.loading && isEmpty()}>
                 {/* A listbox may only contain options/groups: the empty
                     message is a disabled option, the one shape a screen
                     reader can address inside the list. */}

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([])
+  })
+})