@talelk/newui-templates 1.0.0 → 1.1.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@talelk/newui-templates",
-  "version": "1.0.0",
+  "version": "1.1.1",
   "type": "module",
   "description": "The three page templates: AppShell, PaneLayout and AuthLayout.",
   "exports": {
@@ -11,12 +11,13 @@
     }
   },
   "files": [
-    "src"
+    "src",
+    "skills/newui-templates"
   ],
   "dependencies": {
-    "@talelk/newui-atoms": "1.0.0",
-    "@talelk/newui-molecules": "1.0.0",
-    "@talelk/newui-organisms": "1.0.0"
+    "@talelk/newui-atoms": "1.1.0",
+    "@talelk/newui-molecules": "2.1.0",
+    "@talelk/newui-organisms": "2.1.0"
   },
   "peerDependencies": {
     "solid-js": "^1.9.0"
@@ -34,6 +35,9 @@
     "url": "git+https://github.com/talelk/newui.git",
     "directory": "packages/templates"
   },
+  "keywords": [
+    "tanstack-intent"
+  ],
   "scripts": {
     "typecheck": "tsc --noEmit -p tsconfig.json"
   }

package/skills/newui-templates/SKILL.md

@@ -0,0 +1,92 @@
+---
+name: newui-templates
+description: >
+  Use when composing application frames with @talelk/newui-templates — AppShell
+  (responsive sidebar + drawer, brand/tenant/navigation/settings/ account slots,
+  collapse), PaneLayout (resizable split panes), AuthLayout (sign-in/sign-up
+  canvas). Use when the user asks for an app shell, a split layout or an auth
+  page in newui, or mentions @talelk/newui-templates.
+metadata:
+  type: core
+  domain: ui
+  library: '@talelk/newui-templates'
+  library_version: '1.1.1'
+sources:
+  - talelk/newui:packages/templates/src/templates/AppShell.tsx
+  - talelk/newui:packages/templates/src/templates/PaneLayout/PaneLayout.tsx
+  - talelk/newui:packages/templates/src/templates/AuthLayout.tsx
+  - talelk/newui:spec/app-shell.md
+  - talelk/newui:spec/pane-layout.md
+  - talelk/newui:spec/auth-layout.md
+  - talelk/newui:spec/adr/0013-atomic-packages-and-app-shell.md
+---
+
+# newui templates
+
+Exactly three application frames. Read the `newui` skill for the vocabulary;
+the organisms skill covers `AppSidebar`, which AppShell renders for you.
+
+## Setup
+
+```tsx no-check
+import { AppShell } from '@talelk/newui-templates'
+import { SidebarItem } from '@talelk/newui-organisms'
+
+export function Frame() {
+  return (
+    <AppShell
+      title="Projects"
+      brand={<span>Acme</span>}
+      navigation={[
+        {
+          label: 'Workspace',
+          items: [
+            { label: 'Projects', icon: 'lucide-folders', route: '/', active: true },
+          ],
+        },
+      ]}
+      settings={<SidebarItem label="Settings" icon="lucide-settings" />}
+      account={<SidebarItem label="Rhea Kapoor" icon="lucide-user-round" />}
+    >
+      <p>Page content — the template owns the h1 from `title`.</p>
+    </AppShell>
+  )
+}
+```
+
+## Core patterns
+
+**AppShell owns the responsive sidebar.** Desktop docks it; narrow viewports
+open the same navigation as a modal drawer. There is no separate mobile shell
+and no rail — never mount `Sidebar` or `MobileNav` inside it.
+
+**Collapse is controllable.** Pass `collapsed` + `onCollapsedChange` when the
+app owns persistence (P2); without them the shell owns the state. The fold
+lives in the sidebar's identity row (`⌘B`/`Ctrl+B` also toggles).
+
+**Split content with PaneLayout inside AppShell.** Mail-style records need
+`PaneLayout`'s resizable start/end panes; `active` collapses to one pane on
+compact widths. Split panes do not replace the shell.
+
+**AuthLayout is a canvas, not an auth backend.** It centers the flow and
+offers the desktop-only `aside` context panel; the card and session logic
+stay app-owned (`AuthCard` is an organism).
+
+## Common mistakes
+
+**One `h1` per page.** AppShell renders it from `title`; do not add a second
+heading for the page name. `mobileTitle` changes only the compact bar (a
+`span`, not a heading).
+
+**Don't pass a rail or second navigation.** The old `SidebarRail`/
+`DesktopShell` APIs were removed; their props fail typecheck.
+
+**Don't put page content outside the children.** `footer` renders inside the
+page scroller below the body — a fixed footer is app chrome, not this
+template's slot.
+
+## Completion
+
+The starter app (`apps/starter`) composes all three templates against the
+published packages; its e2e suite (`e2e/starter.spec.ts`) is the reference
+for expected behavior.

package/src/templates/AppShell.test.tsx

@@ -1,51 +1,80 @@
 import { render, screen, waitFor } from '@solidjs/testing-library'
 import { SidebarItem } from '@talelk/newui-organisms'
 import userEvent from '@testing-library/user-event'
-import { describe, expect, it } from 'vitest'
+import { describe, expect, it, vi } from 'vitest'
 import { AppShell } from './AppShell'
 
+/**
+ * jsdom's matchMedia stub always answers `false`, which puts every shell in
+ * the mobile layout. The desktop contract (one docked sidebar, fold) needs the
+ * wide answer, so these tests stub the query for the duration of a render.
+ */
+function withDesktop(run: () => void | Promise<void>): Promise<void> {
+  const original = window.matchMedia
+  window.matchMedia = ((query: string) => ({
+    matches: query.includes('min-width'),
+    media: query,
+    onchange: null,
+    addEventListener() {},
+    removeEventListener() {},
+    addListener() {},
+    removeListener() {},
+    dispatchEvent: () => false,
+  })) as unknown as typeof window.matchMedia
+  return Promise.resolve()
+    .then(run)
+    .finally(() => {
+      window.matchMedia = original
+    })
+}
+
+const NAVIGATION = [
+  {
+    label: 'Workspace',
+    items: [
+      { label: 'Projects', icon: 'lucide-folders', active: true },
+      { label: 'People', icon: 'lucide-users' },
+    ],
+  },
+  {
+    label: 'Reports',
+    items: [{ label: 'Revenue', icon: 'lucide-chart-no-axes-combined' }],
+  },
+]
+
+function renderShell(overrides?: Partial<Parameters<typeof AppShell>[0]>) {
+  return render(() => (
+    <AppShell
+      title="Projects"
+      brand={<span>Acme</span>}
+      brandCollapsed={<span>AC</span>}
+      tenant={<button type="button">Acme · Production</button>}
+      tenantCollapsed={
+        <button type="button" aria-label="Choose tenant">
+          AC
+        </button>
+      }
+      navigation={NAVIGATION}
+      settings={
+        <SidebarItem label="Settings" icon="lucide-settings">
+          Settings
+        </SidebarItem>
+      }
+      account={
+        <SidebarItem label="Rhea Kapoor" icon="lucide-user-round">
+          Rhea Kapoor
+        </SidebarItem>
+      }
+      {...overrides}
+    >
+      <p>Content</p>
+    </AppShell>
+  ))
+}
+
 describe('AppShell', () => {
   it('uses one sidebar model for the mobile drawer, including tenant and bottom actions', async () => {
-    render(() => (
-      <AppShell
-        title="Projects"
-        brand={<span>Acme</span>}
-        brandCollapsed={<span>AC</span>}
-        tenant={<button type="button">Acme · Production</button>}
-        tenantCollapsed={
-          <button type="button" aria-label="Choose tenant">
-            AC
-          </button>
-        }
-        navigation={[
-          {
-            label: 'Workspace',
-            items: [
-              { label: 'Projects', icon: 'lucide-folders', active: true },
-              { label: 'People', icon: 'lucide-users' },
-            ],
-          },
-          {
-            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>
-        }
-      >
-        <p>Content</p>
-      </AppShell>
-    ))
+    renderShell()
 
     expect(
       screen.getByRole('heading', { name: 'Projects', level: 1 }),
@@ -71,4 +100,90 @@ describe('AppShell', () => {
     await userEvent.click(screen.getByRole('button', { name: 'People' }))
     await waitFor(() => expect(drawer).not.toBeVisible())
   })
+
+  it('closes the drawer from its own close control', async () => {
+    renderShell()
+    await userEvent.click(
+      screen.getByRole('button', { name: 'Open application navigation' }),
+    )
+    // Focus returns to the trigger through the native `close` event, which the
+    // engine owns — the browser harness asserts that half.
+    await userEvent.click(
+      screen.getByRole('button', { name: 'Close navigation' }),
+    )
+    await waitFor(() => expect(screen.queryByRole('dialog')).toBeNull())
+  })
+
+  it('renders exactly one h1 and keeps the mobile bar title a span', () => {
+    renderShell({ mobileTitle: <span>Projects</span> })
+    const headings = document.querySelectorAll('h1')
+    expect(headings.length).toBe(1)
+    expect(headings[0]?.textContent).toBe('Projects')
+  })
+
+  it('renders the page footer after the content inside the scroller', () => {
+    renderShell({ footer: <p>Quarterly summary</p> })
+    const content = screen.getByText('Content')
+    const footer = screen.getByText('Quarterly summary')
+    expect(
+      footer.compareDocumentPosition(content) &
+        Node.DOCUMENT_POSITION_PRECEDING,
+    ).toBeTruthy()
+  })
+
+  describe('desktop', () => {
+    it('docks the sidebar and folds it through the one fold control', async () => {
+      await withDesktop(async () => {
+        renderShell()
+        const dock = document.querySelector(
+          '[data-slot="app-shell-sidebar"]',
+        ) as HTMLElement
+        expect(dock.className).toContain('w-64')
+
+        // The Sidebar keeps inactive slot copies mounted and hides them with
+        // CSS, so the fold control's name and the dock width are the jsdom-
+        // visible contract; the compact-slot swap is the browser harness's.
+        userEvent.click(
+          screen.getByRole('button', { name: 'Collapse sidebar' }),
+        )
+        await waitFor(() => expect(dock.className).toContain('w-14'))
+        expect(
+          screen.queryByRole('button', { name: 'Collapse sidebar' }),
+        ).toBeNull()
+
+        userEvent.click(screen.getByRole('button', { name: 'Expand sidebar' }))
+        await waitFor(() => expect(dock.className).toContain('w-64'))
+        expect(
+          screen.queryByRole('button', { name: 'Expand sidebar' }),
+        ).toBeNull()
+      })
+    })
+
+    it('stays owned by the app when `collapsed` is controlled', async () => {
+      await withDesktop(async () => {
+        const onCollapsedChange = vi.fn()
+        renderShell({ collapsed: false, onCollapsedChange })
+        const dock = document.querySelector(
+          '[data-slot="app-shell-sidebar"]',
+        ) as HTMLElement
+        userEvent.click(
+          screen.getByRole('button', { name: 'Collapse sidebar' }),
+        )
+        await waitFor(() =>
+          expect(onCollapsedChange).toHaveBeenCalledWith(true),
+        )
+        // Controlled: the shell does not move until the app moves it.
+        expect(dock.className).toContain('w-64')
+      })
+    })
+
+    it('renders header actions in the shell header', async () => {
+      await withDesktop(async () => {
+        renderShell({
+          headerActions: <button type="button">Invite</button>,
+        })
+        expect(screen.getByRole('button', { name: 'Invite' })).toBeTruthy()
+      })
+    })
+  })
 })

package/src/templates/AppShell.tsx

@@ -1,9 +1,4 @@
-import {
-  Button,
-  createMediaQuery,
-  UIProvider,
-  useUI,
-} from '@talelk/newui-atoms'
+import { createMediaQuery, UIProvider, useUI } from '@talelk/newui-atoms'
 import { closeDialog, showDialog } from '@talelk/newui-atoms/internal'
 import { type BreadcrumbItem, Breadcrumbs } from '@talelk/newui-molecules'
 import { AppSidebar, type AppSidebarGroup } from '@talelk/newui-organisms'
@@ -41,6 +36,10 @@ export interface AppShellProps {
   navigation?: AppSidebarGroup[]
   /** Advanced navigation content, rendered inside the same sidebar. */
   navigationContent?: JSX.Element | (() => JSX.Element)
+  /** Global utilities pinned 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 action pinned to the bottom of the sidebar. */
   settings?: JSX.Element
   /** User/account control pinned below settings. */
@@ -116,6 +115,8 @@ export function AppShell(props: AppShellProps): JSX.Element {
     search: props.sidebarSearch,
     groups: props.navigation,
     children: props.navigationContent,
+    utilities: props.utilities,
+    utilitiesCollapsed: props.utilitiesCollapsed,
     settings: props.settings,
     account: props.account,
     accountCollapsed: props.accountCollapsed,
@@ -159,7 +160,7 @@ export function AppShell(props: AppShellProps): JSX.Element {
                   aria-haspopup="dialog"
                   aria-expanded={drawerOpen()}
                   onClick={openDrawer}
-                  class="grid size-9 shrink-0 place-items-center rounded-3 hover:bg-surface-gray-2 focus-visible:focus-ring"
+                  class="grid size-10 shrink-0 place-items-center rounded-3 hover:bg-surface-gray-2 focus-visible:focus-ring"
                 >
                   <span aria-hidden="true" class="lucide-menu size-4" />
                 </button>
@@ -180,24 +181,26 @@ export function AppShell(props: AppShellProps): JSX.Element {
           <a href="#app-shell-content" class="sr-only focus:not-sr-only">
             Skip to workspace
           </a>
-          <div class="mx-auto flex w-full max-w-[1440px] flex-col gap-section-gap p-page-gutter-compact pb-8 md:p-page-gutter">
-            <div class="flex flex-wrap items-end justify-between gap-4">
-              <div class="min-w-0">
-                <Show when={props.breadcrumbs}>
-                  {(items) => <Breadcrumbs items={items()} />}
-                </Show>
-                <h1 class="mt-1 text-heading">{props.title}</h1>
-                <Show when={props.description}>
-                  <p class="mt-2 max-w-2xl text-ink-gray-7">
-                    {props.description}
-                  </p>
+          <div class="mx-auto flex w-full max-w-[1440px] flex-col gap-4 p-page-gutter-compact pb-8 md:p-page-gutter">
+            <div class="flex flex-col gap-2">
+              <Show when={props.breadcrumbs}>
+                {(items) => <Breadcrumbs items={items()} />}
+              </Show>
+              <div class="flex flex-wrap items-start justify-between gap-4">
+                <div class="min-w-0">
+                  <h1 class="mt-1 text-heading">{props.title}</h1>
+                  <Show when={props.description}>
+                    <p class="mt-1 max-w-2xl text-ink-gray-7">
+                      {props.description}
+                    </p>
+                  </Show>
+                </div>
+                <Show when={props.actions}>
+                  <div class="flex flex-wrap items-center gap-2">
+                    {props.actions}
+                  </div>
                 </Show>
               </div>
-              <Show when={props.actions}>
-                <div class="flex flex-wrap items-center gap-2">
-                  {props.actions}
-                </div>
-              </Show>
             </div>
             {props.children}
             <Show when={props.footer}>{props.footer}</Show>
@@ -219,21 +222,29 @@ export function AppShell(props: AppShellProps): JSX.Element {
           const control = target.closest('a, button, [data-navigates]')
           if (control && !control.closest('[data-keep-drawer]')) closeDrawer()
         }}
-        class="open:flex m-0 h-dvh max-h-none w-72 max-w-[calc(100vw-2rem)] flex-col overflow-y-auto border-e border-outline-gray-1 bg-surface-sidebar p-0 text-ink-gray-9 backdrop:bg-black-overlay-200"
+        class="open:flex m-0 h-dvh max-h-none w-72 max-w-[calc(100vw-2rem)] flex-col overflow-hidden border-e border-outline-gray-1 bg-surface-gray-1 p-0 text-ink-gray-9 shadow-xl backdrop:bg-black-overlay-200"
       >
-        <div class="flex shrink-0 justify-end border-b border-outline-gray-1 p-2">
-          <Button variant="ghost" size="sm" onClick={closeDrawer}>
-            Close navigation
-          </Button>
+        <div class="flex h-10 shrink-0 items-center justify-between border-b border-outline-gray-1 ps-3 pe-2">
+          <span class="text-xs font-medium text-ink-gray-7">Navigation</span>
+          <button
+            type="button"
+            aria-label="Close navigation"
+            onClick={closeDrawer}
+            class="grid size-10 shrink-0 place-items-center rounded-control text-ink-gray-6 transition-colors hover:bg-surface-gray-2 hover:text-ink-gray-9 focus-visible:focus-ring motion-reduce:transition-none"
+          >
+            <span aria-hidden="true" class="lucide-x size-4" />
+          </button>
         </div>
         <UIProvider dir={ui?.dir()} portalTarget={drawerPortal}>
-          <AppSidebar
-            {...sidebarProps()}
-            width="100%"
-            collapsedWidth="100%"
-            collapsed={false}
-            collapsible={false}
-          />
+          <div class="flex min-h-0 flex-1 flex-col">
+            <AppSidebar
+              {...sidebarProps()}
+              width="100%"
+              collapsedWidth="100%"
+              collapsed={false}
+              collapsible={false}
+            />
+          </div>
         </UIProvider>
       </dialog>
     </div>

package/src/templates/AuthLayout.test.tsx

@@ -2,19 +2,66 @@ import { render, screen } from '@solidjs/testing-library'
 import { describe, expect, it } from 'vitest'
 import { AuthLayout } from './AuthLayout'
 
+function renderAuth(overrides?: Partial<Parameters<typeof AuthLayout>[0]>) {
+  return render(() => (
+    <AuthLayout brand={<span>Acme</span>} {...overrides}>
+      <form aria-label="Sign in">
+        <button type="submit">Continue</button>
+      </form>
+    </AuthLayout>
+  ))
+}
+
 describe('AuthLayout', () => {
   it('centers public access content and allows an optional context panel', () => {
-    const { container } = render(() => (
-      <AuthLayout aside={<p>Welcome to Acme</p>} brand={<span>Acme</span>}>
-        <form aria-label="Sign in">
-          <button type="submit">Continue</button>
-        </form>
-      </AuthLayout>
-    ))
+    const { container } = renderAuth({ aside: <p>Welcome to Acme</p> })
 
     expect(screen.getByText('Welcome to Acme')).toBeVisible()
     expect(screen.getByText('Acme')).toBeVisible()
     expect(screen.getByRole('form', { name: 'Sign in' })).toBeVisible()
     expect(container.querySelectorAll('main')).toHaveLength(1)
   })
+
+  it('renders the context panel as an aside and splits the canvas in two', () => {
+    const { container } = renderAuth({ aside: <p>Welcome to Acme</p> })
+    const aside = container.querySelector('aside')
+    expect(aside).not.toBeNull()
+    expect(aside?.textContent).toBe('Welcome to Acme')
+    expect((container.firstElementChild as HTMLElement).className).toContain(
+      'lg:grid-cols-2',
+    )
+  })
+
+  it('omits the panel and the split without `aside`', () => {
+    const { container } = renderAuth()
+    expect(container.querySelector('aside')).toBeNull()
+    expect(
+      (container.firstElementChild as HTMLElement).className,
+    ).not.toContain('lg:grid-cols-2')
+  })
+
+  it('renders the header row only when `header` is given', () => {
+    const { container, unmount } = renderAuth()
+    expect(container.querySelector('[class*="absolute inset-x-0"]')).toBeNull()
+    unmount()
+
+    renderAuth({ header: <a href="/">Back to home</a> })
+    expect(screen.getByRole('link', { name: 'Back to home' })).toBeVisible()
+  })
+
+  it('stacks the brand above the flow inside the centered column', () => {
+    const { container } = renderAuth()
+    const column = container.querySelector('main')?.firstElementChild
+    const brand = column?.children[0]
+    const form = column?.children[1]
+    expect(brand?.textContent).toBe('Acme')
+    expect(form?.querySelector('button')?.textContent).toBe('Continue')
+  })
+
+  it('marks the root with the auth-layout slot', () => {
+    const { container } = renderAuth()
+    expect(
+      (container.firstElementChild as HTMLElement).getAttribute('data-slot'),
+    ).toBe('auth-layout')
+  })
 })