@talelk/newui-templates 1.1.0 → 1.1.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@talelk/newui-templates",
-  "version": "1.1.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.1",
-    "@talelk/newui-molecules": "2.0.0",
-    "@talelk/newui-organisms": "2.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/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')
+  })
 })