@talelk/newui-organisms 0.0.0-stage → 2.0.0

package/src/organisms/AppSidebar/AppSidebar.tsx

@@ -0,0 +1,259 @@
+import { type IconProp, ScrollArea } from '@talelk/newui-atoms'
+import { For, type JSX, Show } from 'solid-js'
+import {
+  Sidebar,
+  SidebarItem,
+  SidebarLabel,
+  type SidebarProps,
+  SidebarTrigger,
+  useSidebar,
+} from '../Sidebar'
+
+export interface AppSidebarItem {
+  label: string
+  icon?: IconProp
+  count?: number
+  active?: boolean
+  route?: string
+  href?: string
+  onClick?: () => void
+}
+
+export interface AppSidebarGroup {
+  label?: JSX.Element
+  action?: JSX.Element
+  items: AppSidebarItem[]
+}
+
+/**
+ * The one navigation organism an application shell needs: identity and tenant
+ * at the top, one grouped menu, then utilities and the account at the bottom.
+ *
+ * The shell controls `collapsed`; every item, including the two bottom slots,
+ * stays in the same sidebar context and gets the icon tooltip behavior from
+ * `SidebarItem`. `brandCollapsed` and `tenantCollapsed` let the app choose a
+ * compact mark; if absent, the expanded slot itself is retained.
+ */
+export interface AppSidebarProps {
+  brand: JSX.Element
+  brandCollapsed?: JSX.Element
+  tenant?: JSX.Element
+  tenantCollapsed?: JSX.Element
+  /** Optional fixed control below the tenant and above the scrolling groups. */
+  search?: JSX.Element
+  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
+  width?: SidebarProps['width']
+  collapsedWidth?: SidebarProps['collapsedWidth']
+  collapsed?: SidebarProps['collapsed']
+  onCollapsedChange?: SidebarProps['onCollapsedChange']
+  collapsible?: SidebarProps['collapsible']
+  ariaLabel?: string
+  class?: string
+}
+
+/**
+ * Calls a render-function navigation slot *inside* the Sidebar provider.
+ *
+ * A JSX element created by the caller has already run its component functions
+ * in the caller's context, so a custom menu that reads `useSidebar()` would
+ * capture the default expanded value and never react to the shell collapse.
+ * The function form defers evaluation until this component renders under the
+ * provider.
+ */
+function AppSidebarContent(props: {
+  content?: JSX.Element | (() => JSX.Element)
+}): JSX.Element {
+  return (
+    <>{typeof props.content === 'function' ? props.content() : props.content}</>
+  )
+}
+
+function AppSidebarIdentity(props: {
+  brand: JSX.Element
+  brandCollapsed?: JSX.Element
+  tenant?: JSX.Element
+  tenantCollapsed?: JSX.Element
+  collapsible: boolean
+}): JSX.Element {
+  const { collapsed } = useSidebar()
+  return (
+    <>
+      <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}>
+        <div
+          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
+}): JSX.Element {
+  const { collapsed } = useSidebar()
+  return (
+    <div
+      data-slot="app-sidebar-footer"
+      class="mt-auto flex shrink-0 flex-col gap-1 border-t border-outline-gray-1 px-2 pt-2 pb-2"
+    >
+      <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
+        when={collapsed() && props.accountCollapsed}
+        fallback={props.account}
+      >
+        {props.accountCollapsed}
+      </Show>
+    </div>
+  )
+}
+
+export function AppSidebar(props: AppSidebarProps): JSX.Element {
+  return (
+    <Sidebar
+      width={props.width ?? '16rem'}
+      collapsedWidth={props.collapsedWidth ?? '3.5rem'}
+      collapsed={props.collapsed}
+      onCollapsedChange={props.onCollapsedChange}
+      collapsible={props.collapsible}
+      ariaLabel={props.ariaLabel ?? 'Application navigation'}
+      class={props.class}
+    >
+      <AppSidebarIdentity
+        brand={props.brand}
+        brandCollapsed={props.brandCollapsed}
+        tenant={props.tenant}
+        tenantCollapsed={props.tenantCollapsed}
+        collapsible={props.collapsible !== false}
+      />
+
+      <Show when={props.search}>
+        <div data-slot="app-sidebar-search" class="shrink-0 px-2 pb-2">
+          {props.search}
+        </div>
+      </Show>
+
+      <ScrollArea.Root class="min-h-0 flex-1">
+        <ScrollArea.Viewport class="px-2 pt-1 pb-3">
+          <Show
+            when={props.children}
+            fallback={
+              <For each={props.groups ?? []}>
+                {(group, index) => (
+                  <section
+                    data-slot="app-sidebar-group"
+                    class={index() === 0 ? undefined : 'mt-4'}
+                  >
+                    <Show when={group.label || group.action}>
+                      <SidebarLabel divider action={group.action}>
+                        {group.label}
+                      </SidebarLabel>
+                    </Show>
+                    <div class="flex flex-col gap-0.5">
+                      <For each={group.items}>
+                        {(item) => (
+                          <SidebarItem
+                            active={item.active}
+                            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 group-data-[active]:bg-surface-blue-2 group-data-[active]:text-ink-blue-8">
+                                  {item.count}
+                                </span>
+                              ) : undefined
+                            }
+                          >
+                            {item.label}
+                          </SidebarItem>
+                        )}
+                      </For>
+                    </div>
+                  </section>
+                )}
+              </For>
+            }
+          >
+            <AppSidebarContent content={props.children} />
+          </Show>
+        </ScrollArea.Viewport>
+        <ScrollArea.Scrollbar />
+      </ScrollArea.Root>
+
+      <AppSidebarFooter
+        utilities={props.utilities}
+        utilitiesCollapsed={props.utilitiesCollapsed}
+        settings={props.settings}
+        account={props.account}
+        accountCollapsed={props.accountCollapsed}
+      />
+    </Sidebar>
+  )
+}

package/src/organisms/AppSidebar/index.ts

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

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

@@ -0,0 +1,36 @@
+import { render } from '@solidjs/testing-library'
+import { Button, TextInput } from '@talelk/newui-atoms'
+import axe, { type AxeResults } from 'axe-core'
+import { describe, expect, it } from 'vitest'
+import { AuthCard } from './AuthCard'
+
+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('AuthCard accessibility', () => {
+  it('has no axe violations for a sign-in card', async () => {
+    const { container } = render(() => (
+      <AuthCard
+        title="Sign in"
+        description="Welcome back. Enter your work account."
+        footer={<a href="/sign-up">Create an account</a>}
+      >
+        <TextInput label="Email" type="email" />
+        <Button variant="solid">Continue</Button>
+      </AuthCard>
+    ))
+    expect(summarize(await axe.run(container, AXE_OPTIONS))).toEqual([])
+  })
+})

package/src/organisms/AuthCard/AuthCard.test.tsx

@@ -0,0 +1,56 @@
+import { render, screen } from '@solidjs/testing-library'
+import { describe, expect, it } from 'vitest'
+import { AuthCard } from './AuthCard'
+
+describe('AuthCard', () => {
+  it('gives the page exactly one h1', () => {
+    render(() => (
+      <AuthCard title="Sign in" description="Welcome back">
+        <div>form</div>
+      </AuthCard>
+    ))
+    expect(screen.getAllByRole('heading', { level: 1 })).toHaveLength(1)
+    expect(screen.getByText('Welcome back')).toBeTruthy()
+  })
+
+  it('renders the form as given', () => {
+    render(() => (
+      <AuthCard title="Sign in">
+        <label for="email">Email</label>
+        <input id="email" />
+      </AuthCard>
+    ))
+    expect(screen.getByLabelText('Email')).toBeTruthy()
+  })
+
+  it('labels the divider only when both a form and providers are present', () => {
+    const without = render(() => (
+      <AuthCard title="Sign in">
+        <div>form</div>
+      </AuthCard>
+    ))
+    expect(without.container.querySelector('[data-slot="divider"]')).toBeNull()
+    without.unmount()
+
+    render(() => (
+      <AuthCard title="Sign in" providers={[{ label: 'Continue with GitHub' }]}>
+        <div>form</div>
+      </AuthCard>
+    ))
+    expect(
+      document.querySelectorAll('[data-slot="divider"]').length,
+    ).toBeGreaterThan(0)
+    expect(
+      screen.getByRole('button', { name: /Continue with GitHub/ }),
+    ).toBeTruthy()
+  })
+
+  it('renders a footer when given one', () => {
+    render(() => (
+      <AuthCard title="Sign in" footer="Don't have an account?">
+        <div>form</div>
+      </AuthCard>
+    ))
+    expect(screen.getByText("Don't have an account?")).toBeTruthy()
+  })
+})

package/src/organisms/AuthCard/AuthCard.tsx

@@ -0,0 +1,89 @@
+import { Button, Divider } from '@talelk/newui-atoms'
+import { For, type JSX, Show } from 'solid-js'
+
+export interface AuthProvider {
+  label: string
+  /** A `lucide-*` string or a component (P11). */
+  icon?: string
+  onClick?: () => void
+}
+
+export interface AuthCardProps {
+  title: JSX.Element
+  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". */
+  footer?: JSX.Element
+  /** Brand mark above the title. */
+  logo?: JSX.Element
+  class?: string
+}
+
+/**
+ * The centred card a sign-in, sign-up or reset screen is.
+ *
+ * One block rather than three screens, because the three are the same layout
+ * with different fields — and because the details that make it look
+ * intentional are the ones that get skipped when it is written inline: a capped
+ * measure so the fields do not stretch on a wide display, the divider labelled
+ * "or" only when both a form and providers are present, and the title as an
+ * `h1` so the page has exactly one.
+ */
+export function AuthCard(props: AuthCardProps): JSX.Element {
+  const hasProviders = () => (props.providers?.length ?? 0) > 0
+
+  return (
+    <div
+      data-slot="auth-card"
+      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 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>
+
+      <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>
+
+      <div class="flex flex-col gap-4">{props.children}</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/AuthCard/index.ts

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

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

@@ -0,0 +1,196 @@
+import { render, screen } from '@solidjs/testing-library'
+import userEvent from '@testing-library/user-event'
+import { describe, expect, it, vi } from 'vitest'
+import { CommandGroup, CommandItem, CommandPalette } from './CommandPalette'
+
+const noop = () => {}
+
+function palette(
+  props: {
+    onSelect?: (value: string) => void
+    shortcut?: boolean
+    defaultOpen?: boolean
+  } = {},
+) {
+  return render(() => (
+    <CommandPalette
+      defaultOpen={props.defaultOpen ?? true}
+      shortcut={props.shortcut}
+      label="Commands"
+    >
+      <CommandGroup label="Pages">
+        <CommandItem
+          value="intro"
+          icon="lucide-house"
+          onSelect={props.onSelect}
+        >
+          Introduction
+        </CommandItem>
+        <CommandItem
+          value="blocks"
+          keywords="patterns sections"
+          onSelect={props.onSelect}
+        >
+          Blocks
+        </CommandItem>
+      </CommandGroup>
+      <CommandGroup label="Actions">
+        <CommandItem value="theme" shortcut="⌘B" onSelect={props.onSelect}>
+          Toggle theme
+        </CommandItem>
+        <CommandItem value="soon" disabled onSelect={props.onSelect}>
+          Coming soon
+        </CommandItem>
+      </CommandGroup>
+    </CommandPalette>
+  ))
+}
+
+const field = () => screen.getByRole('combobox', { name: 'Commands' })
+const options = () => screen.queryAllByRole('option')
+const activeId = () => field().getAttribute('aria-activedescendant')
+
+describe('CommandPalette', () => {
+  it('renders its groups and items, and focuses the field', () => {
+    palette()
+    expect(screen.getByRole('listbox', { name: 'Commands' })).toBeTruthy()
+    expect(screen.getByText('Pages')).toBeTruthy()
+    expect(screen.getByText('Actions')).toBeTruthy()
+    expect(options()).toHaveLength(4)
+    expect(document.activeElement).toBe(field())
+  })
+
+  it('highlights the first usable item, not the first item', () => {
+    palette()
+    // `soon` is last and disabled; the first item is the one highlighted.
+    expect(activeId()).toBe(options()[0]?.id)
+    expect(options()[0]?.getAttribute('aria-selected')).toBe('true')
+  })
+
+  it('narrows the list as you type, across every group', async () => {
+    palette()
+    await userEvent.type(field(), 'toggle')
+
+    expect(options()).toHaveLength(1)
+    expect(options()[0]?.textContent).toContain('Toggle theme')
+    // While searching, the heading is noise: relevance is the order.
+    expect(screen.queryByText('Pages')).toBeNull()
+  })
+
+  it('matches a keyword the label does not contain', async () => {
+    palette()
+    await userEvent.type(field(), 'patterns')
+    expect(screen.getByText('Blocks')).toBeTruthy()
+  })
+
+  it('drops the heading while filtering and restores it when cleared', async () => {
+    palette()
+    await userEvent.type(field(), 'toggle')
+    expect(screen.queryByText('Actions')).toBeNull()
+
+    await userEvent.clear(field())
+    expect(screen.getByText('Actions')).toBeTruthy()
+  })
+
+  it('says so when nothing matches', async () => {
+    palette()
+    await userEvent.type(field(), 'zzzz')
+    // The message is the list's only child, and it is a disabled option: a
+    // listbox may not contain bare text (axe: aria-required-children).
+    const remaining = options()
+    expect(remaining).toHaveLength(1)
+    expect(remaining[0]).toHaveAttribute('aria-disabled', 'true')
+    expect(screen.getByText('Nothing matches.')).toBeTruthy()
+  })
+
+  it('moves the highlight with the arrows, stepping over disabled items', async () => {
+    palette()
+    const items = options()
+
+    await userEvent.keyboard('{ArrowDown}')
+    expect(activeId()).toBe(items[1]?.id)
+    await userEvent.keyboard('{ArrowDown}')
+    expect(activeId()).toBe(items[2]?.id)
+    // The disabled item is skipped rather than landed on.
+    await userEvent.keyboard('{ArrowDown}')
+    expect(activeId()).toBe(items[0]?.id)
+    await userEvent.keyboard('{ArrowUp}')
+    expect(activeId()).toBe(items[2]?.id)
+  })
+
+  it('selects the highlighted item on Enter and closes', async () => {
+    const onSelect = vi.fn()
+    palette({ onSelect })
+
+    await userEvent.keyboard('{ArrowDown}')
+    await userEvent.keyboard('{Enter}')
+
+    expect(onSelect).toHaveBeenCalledWith('blocks')
+    expect(screen.queryByRole('listbox')).toBeNull()
+  })
+
+  it('selects on click, and re-points the highlight on hover', async () => {
+    const onSelect = vi.fn()
+    palette({ onSelect })
+
+    const items = options()
+    await userEvent.hover(items[2] as HTMLElement)
+    expect(activeId()).toBe(items[2]?.id)
+    await userEvent.click(items[2] as HTMLElement)
+    expect(onSelect).toHaveBeenCalledWith('theme')
+  })
+
+  it('does nothing on a disabled item', async () => {
+    const onSelect = vi.fn()
+    palette({ onSelect })
+    await userEvent.click(screen.getByText('Coming soon'))
+    expect(onSelect).not.toHaveBeenCalled()
+  })
+
+  it('closes on Escape', async () => {
+    palette()
+    await userEvent.keyboard('{Escape}')
+    expect(screen.queryByRole('listbox')).toBeNull()
+  })
+
+  it('opens on ⌘K, and again after a close', async () => {
+    palette({ defaultOpen: false, onSelect: noop })
+    expect(screen.queryByRole('listbox')).toBeNull()
+
+    await userEvent.keyboard('{Meta>}k{/Meta}')
+    expect(screen.getByRole('listbox', { name: 'Commands' })).toBeTruthy()
+
+    await userEvent.keyboard('{Escape}')
+    await userEvent.keyboard('{Meta>}k{/Meta}')
+    expect(screen.getByRole('listbox', { name: 'Commands' })).toBeTruthy()
+  })
+
+  it('folds case and separators, so a compound name is found however it is typed', async () => {
+    palette()
+    // `Introduction` is one word, `Blocks` two — the fold is what makes a
+    // hyphen or a space equivalent to the case boundary.
+    await userEvent.type(field(), 'intro-duction')
+    expect(options()).toHaveLength(1)
+    expect(options()[0]?.textContent).toContain('Introduction')
+    await userEvent.clear(field())
+    await userEvent.type(field(), 'TOGGLE THEME')
+    expect(options()).toHaveLength(1)
+    expect(options()[0]?.textContent).toContain('Toggle theme')
+  })
+
+  it('starts a fresh search each time it opens', async () => {
+    palette()
+    await userEvent.type(field(), 'toggle')
+    await userEvent.keyboard('{Escape}')
+    await userEvent.keyboard('{Meta>}k{/Meta}')
+
+    expect((field() as HTMLInputElement).value).toBe('')
+    expect(options()).toHaveLength(4)
+  })
+
+  it('leaves ⌘K to the app when the shortcut is off', async () => {
+    palette({ defaultOpen: false, shortcut: false })
+    await userEvent.keyboard('{Meta>}k{/Meta}')
+    expect(screen.queryByRole('listbox')).toBeNull()
+  })
+})