@talelk/newui-organisms 0.0.0-stage → 2.0.0

package/src/organisms/Sidebar/index.ts

@@ -0,0 +1,22 @@
+export {
+  Sidebar,
+  SidebarCard,
+  type SidebarCardAction,
+  type SidebarCardProps,
+  SidebarCollapseToggle,
+  type SidebarCollapseToggleProps,
+  SidebarHeader,
+  type SidebarHeaderProps,
+  SidebarItem,
+  type SidebarItemProps,
+  SidebarLabel,
+  type SidebarLabelProps,
+  type SidebarProps,
+  SidebarSearch,
+  type SidebarSearchProps,
+  SidebarSection,
+  type SidebarSectionProps,
+  SidebarTrigger,
+  type SidebarTriggerProps,
+  useSidebar,
+} from './Sidebar'

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

@@ -0,0 +1,40 @@
+import { render } from '@solidjs/testing-library'
+import axe, { type AxeResults } from 'axe-core'
+import { describe, expect, it } from 'vitest'
+import { type Stat, StatGrid } from './StatGrid'
+
+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),
+  }))
+}
+
+const STATS: Stat[] = [
+  {
+    label: 'Revenue',
+    value: '$4.2m',
+    delta: { value: '+5.1%', direction: 'up', good: true },
+  },
+  {
+    label: 'Open deals',
+    value: '38',
+    hint: 'vs 42 last quarter',
+    delta: { value: '-0.4 pts', direction: 'down', good: false },
+  },
+]
+
+describe('StatGrid accessibility', () => {
+  it('has no axe violations for a KPI row', async () => {
+    const { container } = render(() => <StatGrid stats={STATS} columns={2} />)
+    expect(summarize(await axe.run(container, AXE_OPTIONS))).toEqual([])
+  })
+})

package/src/organisms/StatGrid/StatGrid.test.tsx

@@ -0,0 +1,95 @@
+import { render, screen } from '@solidjs/testing-library'
+import userEvent from '@testing-library/user-event'
+import { describe, expect, it, vi } from 'vitest'
+import { StatGrid } from './StatGrid'
+
+describe('StatGrid', () => {
+  it('renders a label, a value and a hint per stat', () => {
+    render(() => (
+      <StatGrid
+        stats={[
+          {
+            label: 'Net revenue',
+            value: '$220.2K',
+            hint: 'vs last month',
+            delta: { value: '5.1%', direction: 'up' },
+          },
+        ]}
+      />
+    ))
+    expect(screen.getByText('Net revenue')).toBeTruthy()
+    expect(screen.getByText('$220.2K')).toBeTruthy()
+    expect(screen.getByText('vs last month')).toBeTruthy()
+  })
+
+  it('tones a fall by whether it is good, not by its direction', () => {
+    const down = render(() => (
+      <StatGrid
+        stats={[
+          {
+            label: 'Monthly churn',
+            value: '2.1%',
+            delta: { value: '0.4 pts', direction: 'down', good: true },
+          },
+        ]}
+      />
+    ))
+    // The pill pairing is the contrast contract's ink-*-8 on surface-*-2.
+    expect(screen.getByText('0.4 pts').className).toContain('text-ink-green-8')
+    expect(screen.getByText('0.4 pts').className).toContain(
+      'bg-surface-green-2',
+    )
+    expect(screen.getByText('0.4 pts').className).toContain('rounded-full')
+    down.unmount()
+
+    render(() => (
+      <StatGrid
+        stats={[
+          {
+            label: 'Revenue',
+            value: '$1',
+            delta: { value: '2%', direction: 'down' },
+          },
+        ]}
+      />
+    ))
+    expect(screen.getByText('2%').className).toContain('text-ink-red-8')
+    expect(screen.getByText('2%').className).toContain('bg-surface-red-2')
+  })
+
+  it('is a button when it navigates, a card when it does not', async () => {
+    const onClick = vi.fn()
+    const plain = render(() => (
+      <StatGrid stats={[{ label: 'Static', value: '1' }]} />
+    ))
+    expect(plain.container.querySelector('button')).toBeNull()
+    plain.unmount()
+
+    render(() => <StatGrid stats={[{ label: 'Live', value: '2', onClick }]} />)
+    await userEvent.click(screen.getByRole('button', { name: /Live/ }))
+    expect(onClick).toHaveBeenCalled()
+  })
+
+  it('uses literal grid classes so Tailwind can see them', () => {
+    const { container } = render(() => (
+      <StatGrid stats={[{ label: 'One', value: '1' }]} columns={3} />
+    ))
+    const className = container.querySelector(
+      '[data-slot="stat-grid"]',
+    )?.className
+    expect(className).toContain('min-[360px]:grid-cols-2')
+    expect(className).toContain('xl:grid-cols-3')
+  })
+
+  it('compact cards use the tight padding and omit the icon tile', () => {
+    const { container } = render(() => (
+      <StatGrid
+        compact
+        stats={[{ label: 'One', value: '1', icon: 'lucide-house' }]}
+      />
+    ))
+    const card = container.querySelector('[data-slot="stat"]')
+    expect(card?.className).toContain('p-2.5')
+    expect(card?.querySelector('.bg-surface-gray-2')).toBeNull()
+  })
+})

package/src/organisms/StatGrid/StatGrid.tsx

@@ -0,0 +1,151 @@
+import { cn, Icon, type IconProp, Skeleton } from '@talelk/newui-atoms'
+import { For, type JSX, Show } from 'solid-js'
+import { Dynamic } from 'solid-js/web'
+
+export interface Stat {
+  label: string
+  value: JSX.Element
+  /** One line of context: the comparison, the period, the owner. */
+  hint?: JSX.Element
+  /** Signed change, rendered in a tone. `+5.1%` / `-0.4 pts`. */
+  delta?: { value: string; direction: 'up' | 'down' | 'flat'; good?: boolean }
+  icon?: IconProp
+  onClick?: () => void
+}
+
+export interface StatGridProps {
+  stats: Stat[]
+  /** Columns at the widest breakpoint. Defaults to the number of stats, capped. */
+  columns?: 2 | 3 | 4
+  /** Tighter cards without the icon tile; for table-led screens. */
+  compact?: boolean
+  /** Replaces the cards with the shared skeleton geometry. */
+  loading?: boolean
+  class?: string
+}
+
+/**
+ * A row of KPI cards.
+ *
+ * The delta is deliberately not coloured by direction but by *whether it is
+ * good*: churn going down is good, revenue going down is not, and a grid that
+ * paints every minus red gets that wrong on half the dashboards it is used on.
+ * `good` defaults to the intuitive reading and can be overridden per stat.
+ */
+/**
+ * Literal classes, not a template string: Tailwind scans for whole class names,
+ * so `sm:grid-cols-${n}` would compile to nothing and `css:check` would be right
+ * to fail it.
+ */
+const COLUMNS: Record<2 | 3 | 4, string> = {
+  2: 'min-[360px]:grid-cols-2',
+  3: 'min-[360px]:grid-cols-2 xl:grid-cols-3',
+  4: 'min-[360px]:grid-cols-2 xl:grid-cols-4',
+}
+
+/** Compact table-led screens earn a four-up row on tablets. */
+const COMPACT_COLUMNS: Record<2 | 3 | 4, string> = {
+  2: 'min-[360px]:grid-cols-2',
+  3: 'min-[360px]:grid-cols-2 md:grid-cols-3',
+  4: 'min-[360px]:grid-cols-2 md:grid-cols-4',
+}
+
+export function StatGrid(props: StatGridProps): JSX.Element {
+  const columns = (): 2 | 3 | 4 =>
+    props.columns ?? (Math.min(4, Math.max(2, props.stats.length)) as 2 | 3 | 4)
+
+  return (
+    <Show
+      when={!props.loading}
+      fallback={
+        <div
+          data-slot="stat-grid"
+          data-loading
+          class={`grid gap-card-gap ${props.compact ? COMPACT_COLUMNS[columns()] : COLUMNS[columns()]} ${props.class ?? ''}`}
+        >
+          <For each={Array.from({ length: columns() })}>
+            {() => <Skeleton lines={3} class="h-24" />}
+          </For>
+        </div>
+      }
+    >
+      <div
+        data-slot="stat-grid"
+        class={`grid gap-card-gap ${props.compact ? COMPACT_COLUMNS[columns()] : COLUMNS[columns()]} ${props.class ?? ''}`}
+      >
+        <For each={props.stats}>
+          {(stat) => (
+            // A stat that navigates is a button, not a div with a click handler:
+            // it has to be reachable by keyboard and announced as interactive.
+            <Dynamic
+              component={stat.onClick ? 'button' : 'div'}
+              {...(stat.onClick ? { type: 'button' as const } : {})}
+              data-slot="stat"
+              onClick={stat.onClick}
+              class={cn(
+                'flex flex-col rounded-card border border-outline-gray-1 bg-surface-elevation-1 text-start',
+                props.compact ? 'gap-1 p-2.5' : 'gap-control-gap p-card-pad',
+                stat.onClick &&
+                  'cursor-pointer transition-[border-color,box-shadow] hover:border-outline-gray-3 hover:shadow-sm focus-visible:focus-ring motion-reduce:transition-none',
+              )}
+            >
+              <div class="flex items-start gap-2">
+                <Show when={props.compact ? undefined : stat.icon}>
+                  {(icon) => (
+                    <span class="grid size-8 shrink-0 place-items-center rounded-4 bg-surface-gray-2">
+                      <Icon icon={icon()} class="size-4 text-ink-gray-7" />
+                    </span>
+                  )}
+                </Show>
+                <span class="min-w-0 flex-1 text-sm-medium [overflow-wrap:anywhere] text-ink-gray-7">
+                  {stat.label}
+                </span>
+                <Show when={stat.delta}>
+                  {(delta) => (
+                    <span
+                      class="inline-flex shrink-0 items-center gap-0.5 rounded-full px-1.5 py-0.5 text-xs-medium tabular-nums"
+                      classList={{
+                        'bg-surface-green-2 text-ink-green-8':
+                          delta().direction !== 'flat' && isGood(delta()),
+                        'bg-surface-red-2 text-ink-red-8':
+                          delta().direction !== 'flat' && !isGood(delta()),
+                        'bg-surface-gray-2 text-ink-gray-7':
+                          delta().direction === 'flat',
+                      }}
+                    >
+                      <Icon
+                        icon={
+                          delta().direction === 'up'
+                            ? 'lucide-arrow-up'
+                            : delta().direction === 'down'
+                              ? 'lucide-arrow-down'
+                              : 'lucide-minus'
+                        }
+                        class="size-3"
+                      />
+                      {delta().value}
+                    </span>
+                  )}
+                </Show>
+              </div>
+              <span class="text-metric tabular-nums [overflow-wrap:anywhere] text-ink-gray-9">
+                {stat.value}
+              </span>
+              <Show when={stat.hint}>
+                <span class="text-xs [overflow-wrap:anywhere] text-ink-gray-7">
+                  {stat.hint}
+                </span>
+              </Show>
+            </Dynamic>
+          )}
+        </For>
+      </div>
+    </Show>
+  )
+}
+
+/** A flat delta is neutral; otherwise the direction is good unless overridden. */
+function isGood(delta: NonNullable<Stat['delta']>): boolean {
+  if (delta.good !== undefined) return delta.good
+  return delta.direction !== 'down'
+}

package/src/organisms/StatGrid/index.ts

@@ -0,0 +1 @@
+export * from './StatGrid'

package/src/organisms/VirtualList/VirtualList.test.tsx

@@ -0,0 +1,80 @@
+import { render, screen } from '@solidjs/testing-library'
+import { afterEach, describe, expect, it, vi } from 'vitest'
+import { VirtualList } from './VirtualList'
+
+const ROWS = Array.from({ length: 1000 }, (_, index) => ({
+  id: `ROW-${index + 1}`,
+  title: `Row ${index + 1}`,
+}))
+
+/**
+ * jsdom has no layout, so the viewport reports a zero rect and the virtualiser
+ * renders nothing. The tests give every element a 440px box, which is the only
+ * measurement the list needs.
+ */
+class MeasuredObserver {
+  constructor(private readonly callback: ResizeObserverCallback) {}
+  observe(target: Element) {
+    const rect = target.getBoundingClientRect()
+    this.callback(
+      [
+        {
+          target,
+          contentRect: rect,
+          borderBoxSize: [{ inlineSize: rect.width, blockSize: rect.height }],
+          contentBoxSize: [{ inlineSize: rect.width, blockSize: rect.height }],
+        } as unknown as ResizeObserverEntry,
+      ],
+      this as unknown as ResizeObserver,
+    )
+  }
+  unobserve() {}
+  disconnect() {}
+}
+
+function withLayout() {
+  const rect = {
+    width: 600,
+    height: 440,
+    top: 0,
+    left: 0,
+    right: 600,
+    bottom: 440,
+    x: 0,
+    y: 0,
+    toJSON: () => ({}),
+  } as DOMRect
+  const spy = vi
+    .spyOn(HTMLElement.prototype, 'getBoundingClientRect')
+    .mockReturnValue(rect)
+  // The jsdom shim observes nothing; the virtualiser needs one measurement.
+  vi.stubGlobal('ResizeObserver', MeasuredObserver)
+  return spy
+}
+
+afterEach(() => {
+  vi.unstubAllGlobals()
+  vi.restoreAllMocks()
+})
+
+describe('VirtualList', () => {
+  it('keeps a bounded DOM, with row positions declared for assistive tech', () => {
+    const spy = withLayout()
+    render(() => (
+      <VirtualList label="Rows" items={ROWS} itemSize={72} height="440px">
+        {(row) => <span>{row.title}</span>}
+      </VirtualList>
+    ))
+    const viewport = screen.getByRole('region', { name: 'Rows' })
+    expect(viewport.getAttribute('data-slot')).toBe('virtual-list')
+    expect(viewport.getAttribute('tabindex')).toBe('0')
+
+    const rows = viewport.querySelectorAll('li')
+    expect(rows.length).toBeGreaterThan(0)
+    expect(rows.length).toBeLessThan(30)
+    const first = rows[0] as HTMLLIElement
+    expect(first.getAttribute('aria-posinset')).toBe('1')
+    expect(first.getAttribute('aria-setsize')).toBe('1000')
+    spy.mockRestore()
+  })
+})

package/src/organisms/VirtualList/VirtualList.tsx

@@ -0,0 +1,113 @@
+import { createVirtualizer } from '@tanstack/solid-virtual'
+import { For, type JSX, Show, untrack } from 'solid-js'
+import { DataState } from '../DataState'
+
+/**
+ * A bounded DOM for a long list.
+ *
+ * A feed of a thousand rows does not need a thousand nodes: this keeps about a
+ * viewport's worth mounted and positions them, which is what makes the task
+ * activity stream scroll to the end with fewer than thirty `li`s in the document.
+ *
+ * The scroll region is focusable on purpose — a region that scrolls and cannot
+ * be reached from the keyboard cannot be read past its first screen (WCAG
+ * 2.1.1), and that is the same contract `ScrollArea` documents. `Home`/`End`/
+ * arrows scroll it natively once it has focus.
+ *
+ * Rows are fixed-height by design: a virtualiser that has to measure every row
+ * to know where the next one starts defeats the point on the lists this is for.
+ */
+export interface VirtualListProps<T> {
+  items: readonly T[]
+  /** Accessible name of the scroll region. */
+  label: string
+  /** Row height in pixels. Fixed, so the total height is known up front. */
+  itemSize: number
+  /** The viewport's height as a CSS length. Default `24rem`. */
+  height?: string
+  /** Rows rendered beyond the viewport. Default `6`. */
+  overscan?: number
+  /** Replaces the list with the shared loading skeleton. */
+  loading?: boolean
+  /** Replaces the list with the shared error state. */
+  error?: JSX.Element
+  onRetry?: () => void
+  emptyTitle?: JSX.Element
+  emptyDescription?: JSX.Element
+  emptyAction?: JSX.Element
+  /** One row's content; the `li` and its position belong to the list. */
+  children: (item: T, index: number) => JSX.Element
+}
+
+export function VirtualList<T>(props: VirtualListProps<T>): JSX.Element {
+  let viewport: HTMLElement | undefined
+  const virtualizer = createVirtualizer<HTMLElement, HTMLLIElement>({
+    get count() {
+      return props.items.length
+    },
+    getScrollElement: () => viewport ?? null,
+    estimateSize: () => props.itemSize,
+    // The virtualiser is created once; a changing overscan is not a supported
+    // dynamic input, and reading it untracked says so.
+    overscan: untrack(() => props.overscan) ?? 6,
+  })
+
+  const status = () =>
+    props.loading
+      ? ('loading' as const)
+      : props.error
+        ? ('error' as const)
+        : props.items.length === 0
+          ? ('empty' as const)
+          : ('ready' as const)
+
+  return (
+    <section
+      ref={viewport}
+      aria-label={props.label}
+      tabindex="0"
+      style={{ height: props.height ?? '24rem' }}
+      class="relative overflow-auto rounded-3 focus-visible:focus-ring"
+      data-slot="virtual-list"
+    >
+      <Show
+        when={status() === 'ready'}
+        fallback={
+          <DataState
+            status={status()}
+            skeleton="rows"
+            rows={5}
+            title={props.emptyTitle}
+            description={props.emptyDescription}
+            action={props.emptyAction}
+            error={props.error}
+            onRetry={props.onRetry}
+          />
+        }
+      >
+        <ul
+          class="relative m-0 list-none p-0"
+          style={{ height: `${virtualizer.getTotalSize()}px` }}
+        >
+          <For each={virtualizer.getVirtualItems()}>
+            {(row) => (
+              <li
+                class="absolute inset-x-0 top-0"
+                style={{
+                  height: `${props.itemSize}px`,
+                  transform: `translateY(${row.start}px)`,
+                }}
+                aria-posinset={row.index + 1}
+                aria-setsize={props.items.length}
+              >
+                {/* The virtualiser's count is the array's length, so the index
+                    is a valid key for the mapped row. */}
+                {props.children(props.items[row.index] as T, row.index)}
+              </li>
+            )}
+          </For>
+        </ul>
+      </Show>
+    </section>
+  )
+}

package/src/organisms/VirtualList/index.ts

@@ -0,0 +1 @@
+export * from './VirtualList'

package/src/organisms/index.ts

@@ -0,0 +1,16 @@
+export * from './AppSidebar'
+export * from './AuthCard'
+export * from './CommandPalette'
+export * from './DataState'
+export * from './DataTable'
+export * from './DetailHeader'
+export * from './FilterBar'
+export * from './KanbanBoard'
+export * from './MobileNav'
+export * from './PageToolbar'
+export * from './Section'
+export * from './SelectionBar'
+export * from './SettingsDialog'
+export * from './Sidebar'
+export * from './StatGrid'
+export * from './VirtualList'