@opensaas/stack-ui 0.1.7 → 0.4.0

package/src/components/Navigation.tsx

@@ -1,24 +1,27 @@
 import Link from 'next/link.js'
 import { formatListName } from '../lib/utils.js'
-import { AccessContext, getUrlKey, OpenSaasConfig } from '@opensaas/stack-core'
+import { type AccessContext, getUrlKey, OpenSaasConfig } from '@opensaas/stack-core'
+import { UserMenu } from './UserMenu.js'
 
-export interface NavigationProps<TPrisma> {
-  context: AccessContext<TPrisma>
+export interface NavigationProps {
+  context: AccessContext<unknown>
   config: OpenSaasConfig
   basePath?: string
   currentPath?: string
+  onSignOut?: () => Promise<void>
 }
 
 /**
  * Navigation sidebar showing all lists
  * Server Component
  */
-export function Navigation<TPrisma>({
+export function Navigation({
   context,
   config,
   basePath = '/admin',
   currentPath = '',
-}: NavigationProps<TPrisma>) {
+  onSignOut,
+}: NavigationProps) {
   const lists = Object.keys(config.lists || {})
 
   return (
@@ -90,27 +93,13 @@ export function Navigation<TPrisma>({
         </div>
       </div>
 
-      {/* Footer */}
+      {/* Footer - User Menu */}
       {context.session && (
-        <div className="p-4 border-t border-border bg-gradient-to-br from-primary/5 to-accent/5">
-          <div className="flex items-center space-x-3">
-            <div className="h-9 w-9 rounded-full bg-gradient-to-br from-primary to-accent flex items-center justify-center shadow-lg shadow-primary/25">
-              <span className="text-sm font-bold text-primary-foreground">
-                {String(
-                  (context.session.data as Record<string, unknown>)?.name,
-                )?.[0]?.toUpperCase() || '?'}
-              </span>
-            </div>
-            <div className="flex-1 min-w-0">
-              <p className="text-sm font-medium truncate">
-                {String((context.session.data as Record<string, unknown>)?.name) || 'User'}
-              </p>
-              <p className="text-xs text-muted-foreground truncate">
-                {String((context.session.data as Record<string, unknown>)?.email) || ''}
-              </p>
-            </div>
-          </div>
-        </div>
+        <UserMenu
+          userName={String((context.session.data as Record<string, unknown>)?.name) || 'User'}
+          userEmail={String((context.session.data as Record<string, unknown>)?.email) || ''}
+          onSignOut={onSignOut}
+        />
       )}
     </nav>
   )

package/src/components/UserMenu.tsx

@@ -0,0 +1,44 @@
+'use client'
+
+import { useRouter } from 'next/navigation.js'
+import { Button } from '../primitives/button.js'
+
+export interface UserMenuProps {
+  userName?: string
+  userEmail?: string
+  onSignOut?: () => Promise<void>
+}
+
+/**
+ * User menu component with sign-out button
+ * Client Component
+ */
+export function UserMenu({ userName, userEmail, onSignOut }: UserMenuProps) {
+  const router = useRouter()
+
+  const handleSignOut = async () => {
+    if (onSignOut) {
+      await onSignOut()
+    }
+    router.push('/sign-in')
+  }
+
+  return (
+    <div className="p-4 border-t border-border bg-gradient-to-br from-primary/5 to-accent/5">
+      <div className="flex items-center space-x-3 mb-3">
+        <div className="h-9 w-9 rounded-full bg-gradient-to-br from-primary to-accent flex items-center justify-center shadow-lg shadow-primary/25">
+          <span className="text-sm font-bold text-primary-foreground">
+            {userName?.[0]?.toUpperCase() || '?'}
+          </span>
+        </div>
+        <div className="flex-1 min-w-0">
+          <p className="text-sm font-medium truncate">{userName || 'User'}</p>
+          <p className="text-xs text-muted-foreground truncate">{userEmail || ''}</p>
+        </div>
+      </div>
+      <Button onClick={handleSignOut} variant="outline" size="sm" className="w-full text-sm">
+        Sign Out
+      </Button>
+    </div>
+  )
+}

package/src/components/fields/TextField.tsx

@@ -1,6 +1,7 @@
 'use client'
 
 import { Input } from '../../primitives/input.js'
+import { Textarea } from '../../primitives/textarea.js'
 import { Label } from '../../primitives/label.js'
 import { cn } from '../../lib/utils.js'
 
@@ -14,6 +15,7 @@ export interface TextFieldProps {
   disabled?: boolean
   required?: boolean
   mode?: 'read' | 'edit'
+  displayMode?: 'input' | 'textarea'
 }
 
 export function TextField({
@@ -26,6 +28,7 @@ export function TextField({
   disabled,
   required,
   mode = 'edit',
+  displayMode = 'input',
 }: TextFieldProps) {
   if (mode === 'read') {
     return (
@@ -36,16 +39,18 @@ export function TextField({
     )
   }
 
+  const InputComponent = displayMode === 'textarea' ? Textarea : Input
+
   return (
     <div className="space-y-2">
       <Label htmlFor={name}>
         {label}
         {required && <span className="text-destructive ml-1">*</span>}
       </Label>
-      <Input
+      <InputComponent
         id={name}
         name={name}
-        type="text"
+        type={displayMode === 'input' ? 'text' : undefined}
         value={value || ''}
         onChange={(e) => onChange(e.target.value)}
         placeholder={placeholder}

package/src/index.ts

@@ -2,6 +2,7 @@
 export { AdminUI } from './components/AdminUI.js'
 export { Dashboard } from './components/Dashboard.js'
 export { Navigation } from './components/Navigation.js'
+export { UserMenu } from './components/UserMenu.js'
 export { ListView } from './components/ListView.js'
 export { ListViewClient } from './components/ListViewClient.js'
 export { ItemForm } from './components/ItemForm.js'
@@ -29,6 +30,7 @@ export {
 export type { AdminUIProps } from './components/AdminUI.js'
 export type { DashboardProps } from './components/Dashboard.js'
 export type { NavigationProps } from './components/Navigation.js'
+export type { UserMenuProps } from './components/UserMenu.js'
 export type { ListViewProps } from './components/ListView.js'
 export type { ListViewClientProps } from './components/ListViewClient.js'
 export type { ItemFormProps } from './components/ItemForm.js'

package/src/primitives/button.tsx

@@ -31,8 +31,7 @@ const buttonVariants = cva(
 )
 
 export interface ButtonProps
-  extends React.ButtonHTMLAttributes<HTMLButtonElement>,
-    VariantProps<typeof buttonVariants> {
+  extends React.ButtonHTMLAttributes<HTMLButtonElement>, VariantProps<typeof buttonVariants> {
   asChild?: boolean
 }
 

package/tests/browser/README.md

@@ -0,0 +1,154 @@
+# Browser Tests
+
+This directory contains UI tests that run in a real browser environment using Vitest Browser Mode with Playwright.
+
+## Overview
+
+Browser tests provide more realistic testing by running tests in actual browser environments (Chromium, Firefox, or WebKit). These tests can verify:
+
+- Real browser interactions (clicks, keyboard input, focus management)
+- Visual rendering and CSS behavior
+- Accessibility features
+- Browser-specific bugs
+
+## Running Browser Tests
+
+### Prerequisites
+
+1. Install Playwright browsers:
+
+   ```bash
+   npx playwright install chromium
+   ```
+
+2. Ensure you have a display server available (for headless: false mode)
+
+### Commands
+
+```bash
+# Run browser tests in headless mode
+pnpm test:browser
+
+# Run browser tests with UI
+pnpm test:browser:ui
+```
+
+### Configuration
+
+Browser tests are configured in `vitest.config.ts`:
+
+- **Enabled**: Only when `BROWSER_TEST=true` environment variable is set
+- **Browser**: Chromium (via Playwright)
+- **Headless**: true (can be set to false for debugging)
+- **Screenshot on failure**: Enabled
+
+## Test Structure
+
+Browser tests follow this structure:
+
+```typescript
+import { describe, it, expect } from 'vitest'
+import { render, screen } from '@testing-library/react'
+import { userEvent } from 'vitest/browser'
+import { MyComponent } from '../../../src/components/MyComponent.js'
+
+describe('MyComponent (Browser)', () => {
+  it('should handle real browser interactions', async () => {
+    render(<MyComponent />)
+
+    const button = screen.getByRole('button')
+    await userEvent.click(button)
+
+    expect(button).toHaveAttribute('aria-pressed', 'true')
+  })
+})
+```
+
+## Test Categories
+
+### Primitives
+
+- **Button.browser.test.tsx**: Tests button variants, keyboard navigation, focus states
+- **Dialog.browser.test.tsx**: Tests modal dialogs, focus trapping, keyboard shortcuts (Escape)
+
+### Fields
+
+- **TextField.browser.test.tsx**: Tests text input, paste, special characters, focus/blur
+- **CheckboxField.browser.test.tsx**: Tests checkbox toggling, keyboard (Space), label clicks
+- **SelectField.browser.test.tsx**: Tests dropdown behavior, keyboard navigation (arrows)
+
+## Browser vs Regular Tests
+
+| Aspect                | Regular Tests (Happy DOM) | Browser Tests  |
+| --------------------- | ------------------------- | -------------- |
+| **Speed**             | Fast (~500ms)             | Slower (~5s)   |
+| **Environment**       | Simulated DOM             | Real browser   |
+| **User Interactions** | Simulated                 | Real events    |
+| **Visual Testing**    | No                        | Yes            |
+| **CI/CD**             | Easy                      | Requires setup |
+
+## When to Use Browser Tests
+
+Use browser tests for:
+
+- Complex user interactions (drag-drop, keyboard navigation)
+- Focus management and accessibility
+- Browser-specific features
+- Visual regression testing
+- Issues that only reproduce in real browsers
+
+Use regular tests (Happy DOM) for:
+
+- Unit testing components
+- Testing props and state
+- Fast feedback during development
+- Most UI logic
+
+## CI/CD Setup
+
+For CI/CD environments, ensure:
+
+1. **Display Server**: Use `xvfb` or run in headless mode
+2. **Playwright Installation**: Include `npx playwright install --with-deps` in CI setup
+3. **Browser Binaries**: Ensure chromium/firefox/webkit are available
+
+Example GitHub Actions:
+
+```yaml
+- name: Install Playwright
+  run: npx playwright install --with-deps chromium
+
+- name: Run browser tests
+  run: pnpm test:browser
+```
+
+## Troubleshooting
+
+### "Browser connection was closed"
+
+- **Cause**: No display server available
+- **Solution**: Run in headless mode or use xvfb
+
+### "vitest/browser can be imported only inside Browser Mode"
+
+- **Cause**: Browser tests running in regular test mode
+- **Solution**: Ensure tests are in `tests/browser/` directory and use `pnpm test:browser`
+
+### Playwright installation errors
+
+- **Cause**: Missing system dependencies
+- **Solution**: Run `npx playwright install --with-deps chromium`
+
+## Development Tips
+
+1. **Debugging**: Set `headless: false` in vitest.config.ts to see the browser
+2. **Screenshots**: Failed tests automatically capture screenshots
+3. **Slow Tests**: Use `{ timeout: 10000 }` for tests that need more time
+4. **Browser DevTools**: Set `slowMo: 100` to slow down interactions for debugging
+
+## Future Enhancements
+
+- [ ] Add visual regression testing with screenshots
+- [ ] Test in multiple browsers (Firefox, WebKit)
+- [ ] Add E2E tests for complete user flows
+- [ ] Integrate with Percy or similar visual testing service

package/tests/browser/fields/CheckboxField.browser.test.tsx

@@ -0,0 +1,245 @@
+import { describe, it, expect } from 'vitest'
+import { render, screen, act } from '@testing-library/react'
+import { userEvent } from 'vitest/browser'
+import React from 'react'
+import { CheckboxField } from '../../../src/components/fields/CheckboxField.js'
+
+describe('CheckboxField (Browser)', () => {
+  describe('edit mode', () => {
+    it('should render checkbox with label', async () => {
+      render(<CheckboxField name="active" value={false} onChange={() => {}} label="Is Active" />)
+
+      expect(screen.getByLabelText('Is Active')).toBeInTheDocument()
+      expect(screen.getByRole('checkbox')).toBeInTheDocument()
+    })
+
+    it('should display checked state when value is true', async () => {
+      render(<CheckboxField name="active" value={true} onChange={() => {}} label="Is Active" />)
+
+      const checkbox = screen.getByRole('checkbox')
+      expect(checkbox).toBeChecked()
+    })
+
+    it('should display unchecked state when value is false', async () => {
+      render(<CheckboxField name="active" value={false} onChange={() => {}} label="Is Active" />)
+
+      const checkbox = screen.getByRole('checkbox')
+      expect(checkbox).not.toBeChecked()
+    })
+
+    it('should call onChange with true when clicked', async () => {
+      let currentValue = false
+      const handleChange = (value: boolean) => {
+        currentValue = value
+      }
+
+      render(
+        <CheckboxField
+          name="active"
+          value={currentValue}
+          onChange={handleChange}
+          label="Is Active"
+        />,
+      )
+
+      const checkbox = screen.getByRole('checkbox')
+      await userEvent.click(checkbox)
+
+      expect(currentValue).toBe(true)
+    })
+
+    it('should call onChange with false when unchecked', async () => {
+      let currentValue = true
+      const handleChange = (value: boolean) => {
+        currentValue = value
+      }
+
+      render(
+        <CheckboxField
+          name="active"
+          value={currentValue}
+          onChange={handleChange}
+          label="Is Active"
+        />,
+      )
+
+      const checkbox = screen.getByRole('checkbox')
+      await userEvent.click(checkbox)
+
+      expect(currentValue).toBe(false)
+    })
+
+    it('should toggle state with multiple clicks', async () => {
+      function TestComponent() {
+        const [value, setValue] = React.useState(false)
+        return (
+          <CheckboxField
+            name="active"
+            value={value}
+            onChange={setValue}
+            label="Is Active"
+            data-testid="checkbox-field"
+          />
+        )
+      }
+
+      await act(async () => {
+        render(<TestComponent />)
+      })
+
+      const checkbox = screen.getByRole('checkbox')
+
+      // First click - check
+      expect(checkbox).not.toBeChecked()
+      await act(async () => {
+        await userEvent.click(checkbox)
+      })
+      expect(checkbox).toBeChecked()
+
+      // Second click - uncheck
+      await act(async () => {
+        await userEvent.click(checkbox)
+      })
+      expect(checkbox).not.toBeChecked()
+
+      // Third click - check again
+      await act(async () => {
+        await userEvent.click(checkbox)
+      })
+      expect(checkbox).toBeChecked()
+    })
+
+    it('should display error message', async () => {
+      render(
+        <CheckboxField
+          name="terms"
+          value={false}
+          onChange={() => {}}
+          label="Accept Terms"
+          error="You must accept the terms"
+        />,
+      )
+
+      expect(screen.getByText('You must accept the terms')).toBeInTheDocument()
+    })
+
+    it('should be disabled when disabled prop is true', async () => {
+      render(
+        <CheckboxField
+          name="active"
+          value={false}
+          onChange={() => {}}
+          label="Is Active"
+          disabled
+        />,
+      )
+
+      const checkbox = screen.getByRole('checkbox')
+      expect(checkbox).toBeDisabled()
+    })
+
+    it('should not be clickable when disabled', async () => {
+      let currentValue = false
+      const handleChange = (value: boolean) => {
+        currentValue = value
+      }
+
+      render(
+        <CheckboxField
+          name="active"
+          value={currentValue}
+          onChange={handleChange}
+          label="Is Active"
+          disabled
+        />,
+      )
+
+      const checkbox = screen.getByRole('checkbox')
+
+      // Verify checkbox is disabled - browsers prevent clicking disabled checkboxes
+      expect(checkbox).toBeDisabled()
+
+      // In real browsers, disabled checkboxes cannot be clicked
+      expect(currentValue).toBe(false)
+    })
+
+    it('should support keyboard interaction with Space', async () => {
+      let currentValue = false
+      const handleChange = (value: boolean) => {
+        currentValue = value
+      }
+
+      render(
+        <CheckboxField
+          name="active"
+          value={currentValue}
+          onChange={handleChange}
+          label="Is Active"
+        />,
+      )
+
+      const checkbox = screen.getByRole('checkbox')
+      checkbox.focus()
+      expect(document.activeElement).toBe(checkbox)
+
+      await userEvent.keyboard(' ')
+
+      expect(currentValue).toBe(true)
+    })
+
+    it('should support clicking on label to toggle', async () => {
+      let currentValue = false
+      const handleChange = (value: boolean) => {
+        currentValue = value
+      }
+
+      render(
+        <CheckboxField
+          name="active"
+          value={currentValue}
+          onChange={handleChange}
+          label="Is Active"
+        />,
+      )
+
+      const label = screen.getByText('Is Active')
+      await userEvent.click(label)
+
+      expect(currentValue).toBe(true)
+    })
+  })
+
+  describe('read mode', () => {
+    it('should render "Yes" when value is true', async () => {
+      render(
+        <CheckboxField
+          name="active"
+          value={true}
+          onChange={() => {}}
+          label="Is Active"
+          mode="read"
+        />,
+      )
+
+      expect(screen.getByText('Is Active')).toBeInTheDocument()
+      expect(screen.getByText('Yes')).toBeInTheDocument()
+      expect(screen.queryByRole('checkbox')).not.toBeInTheDocument()
+    })
+
+    it('should render "No" when value is false', async () => {
+      render(
+        <CheckboxField
+          name="active"
+          value={false}
+          onChange={() => {}}
+          label="Is Active"
+          mode="read"
+        />,
+      )
+
+      expect(screen.getByText('Is Active')).toBeInTheDocument()
+      expect(screen.getByText('No')).toBeInTheDocument()
+      expect(screen.queryByRole('checkbox')).not.toBeInTheDocument()
+    })
+  })
+})