@furystack/shades-common-components 10.0.35 → 12.0.0

package/src/components/page-container/page-header.spec.tsx

@@ -0,0 +1,308 @@
+import { Injector } from '@furystack/inject'
+import { createComponent, initializeShadeRoot } from '@furystack/shades'
+import { sleepAsync, usingAsync } from '@furystack/utils'
+import { afterEach, beforeEach, describe, expect, it } from 'vitest'
+import { PageHeader } from './page-header.js'
+
+describe('PageHeader component', () => {
+  beforeEach(() => {
+    document.body.innerHTML = '<div id="root"></div>'
+  })
+
+  afterEach(() => {
+    document.body.innerHTML = ''
+  })
+
+  describe('rendering', () => {
+    it('should render the shade-page-header custom element', async () => {
+      await usingAsync(new Injector(), async (injector) => {
+        const rootElement = document.getElementById('root') as HTMLDivElement
+
+        initializeShadeRoot({
+          injector,
+          rootElement,
+          jsxElement: <PageHeader title="Test Title" />,
+        })
+
+        await sleepAsync(50)
+        const element = document.querySelector('shade-page-header')
+        expect(element).not.toBeNull()
+        expect(element?.tagName.toLowerCase()).toBe('shade-page-header')
+      })
+    })
+
+    it('should render the title', async () => {
+      await usingAsync(new Injector(), async (injector) => {
+        const rootElement = document.getElementById('root') as HTMLDivElement
+
+        initializeShadeRoot({
+          injector,
+          rootElement,
+          jsxElement: <PageHeader title="Users" />,
+        })
+
+        await sleepAsync(50)
+        const title = document.querySelector('[data-testid="page-header-title"]')
+        expect(title).not.toBeNull()
+        expect(title?.textContent).toBe('Users')
+      })
+    })
+
+    it('should render the title as h2', async () => {
+      await usingAsync(new Injector(), async (injector) => {
+        const rootElement = document.getElementById('root') as HTMLDivElement
+
+        initializeShadeRoot({
+          injector,
+          rootElement,
+          jsxElement: <PageHeader title="Dashboard" />,
+        })
+
+        await sleepAsync(50)
+        const title = document.querySelector('[data-testid="page-header-title"]')
+        expect(title?.tagName.toLowerCase()).toBe('h2')
+      })
+    })
+  })
+
+  describe('icon', () => {
+    it('should render icon when provided', async () => {
+      await usingAsync(new Injector(), async (injector) => {
+        const rootElement = document.getElementById('root') as HTMLDivElement
+
+        initializeShadeRoot({
+          injector,
+          rootElement,
+          jsxElement: <PageHeader icon="👥" title="Users" />,
+        })
+
+        await sleepAsync(50)
+        const icon = document.querySelector('.page-header-icon')
+        expect(icon).not.toBeNull()
+        expect(icon?.textContent).toBe('👥')
+      })
+    })
+
+    it('should not render icon element when not provided', async () => {
+      await usingAsync(new Injector(), async (injector) => {
+        const rootElement = document.getElementById('root') as HTMLDivElement
+
+        initializeShadeRoot({
+          injector,
+          rootElement,
+          jsxElement: <PageHeader title="Users" />,
+        })
+
+        await sleepAsync(50)
+        const icon = document.querySelector('.page-header-icon')
+        expect(icon).toBeNull()
+      })
+    })
+
+    it('should include icon in title text', async () => {
+      await usingAsync(new Injector(), async (injector) => {
+        const rootElement = document.getElementById('root') as HTMLDivElement
+
+        initializeShadeRoot({
+          injector,
+          rootElement,
+          jsxElement: <PageHeader icon="📁" title="Projects" />,
+        })
+
+        await sleepAsync(50)
+        const title = document.querySelector('[data-testid="page-header-title"]')
+        expect(title?.textContent).toContain('📁')
+        expect(title?.textContent).toContain('Projects')
+      })
+    })
+  })
+
+  describe('description', () => {
+    it('should render description when provided', async () => {
+      await usingAsync(new Injector(), async (injector) => {
+        const rootElement = document.getElementById('root') as HTMLDivElement
+
+        initializeShadeRoot({
+          injector,
+          rootElement,
+          jsxElement: <PageHeader title="Users" description="Manage user accounts." />,
+        })
+
+        await sleepAsync(50)
+        const description = document.querySelector('[data-testid="page-header-description"]')
+        expect(description).not.toBeNull()
+        expect(description?.textContent).toBe('Manage user accounts.')
+      })
+    })
+
+    it('should not render description element when not provided', async () => {
+      await usingAsync(new Injector(), async (injector) => {
+        const rootElement = document.getElementById('root') as HTMLDivElement
+
+        initializeShadeRoot({
+          injector,
+          rootElement,
+          jsxElement: <PageHeader title="Users" />,
+        })
+
+        await sleepAsync(50)
+        const description = document.querySelector('[data-testid="page-header-description"]')
+        expect(description).toBeNull()
+      })
+    })
+
+    it('should render description as p element', async () => {
+      await usingAsync(new Injector(), async (injector) => {
+        const rootElement = document.getElementById('root') as HTMLDivElement
+
+        initializeShadeRoot({
+          injector,
+          rootElement,
+          jsxElement: <PageHeader title="Dashboard" description="Overview of your data." />,
+        })
+
+        await sleepAsync(50)
+        const description = document.querySelector('[data-testid="page-header-description"]')
+        expect(description?.tagName.toLowerCase()).toBe('p')
+      })
+    })
+  })
+
+  describe('actions', () => {
+    it('should render actions when provided', async () => {
+      await usingAsync(new Injector(), async (injector) => {
+        const rootElement = document.getElementById('root') as HTMLDivElement
+
+        initializeShadeRoot({
+          injector,
+          rootElement,
+          jsxElement: (
+            <PageHeader
+              title="Users"
+              actions={
+                <button type="button" data-testid="action-button">
+                  Add User
+                </button>
+              }
+            />
+          ),
+        })
+
+        await sleepAsync(50)
+        const actionsContainer = document.querySelector('[data-testid="page-header-actions"]')
+        expect(actionsContainer).not.toBeNull()
+
+        const actionButton = document.querySelector('[data-testid="action-button"]')
+        expect(actionButton).not.toBeNull()
+        expect(actionButton?.textContent).toBe('Add User')
+      })
+    })
+
+    it('should not render actions element when not provided', async () => {
+      await usingAsync(new Injector(), async (injector) => {
+        const rootElement = document.getElementById('root') as HTMLDivElement
+
+        initializeShadeRoot({
+          injector,
+          rootElement,
+          jsxElement: <PageHeader title="Users" />,
+        })
+
+        await sleepAsync(50)
+        const actionsContainer = document.querySelector('[data-testid="page-header-actions"]')
+        expect(actionsContainer).toBeNull()
+      })
+    })
+
+    it('should render multiple action elements', async () => {
+      await usingAsync(new Injector(), async (injector) => {
+        const rootElement = document.getElementById('root') as HTMLDivElement
+
+        initializeShadeRoot({
+          injector,
+          rootElement,
+          jsxElement: (
+            <PageHeader
+              title="Users"
+              actions={
+                <>
+                  <button type="button">Export</button>
+                  <button type="button">Add User</button>
+                </>
+              }
+            />
+          ),
+        })
+
+        await sleepAsync(50)
+        const actionsContainer = document.querySelector('[data-testid="page-header-actions"]')
+        const buttons = actionsContainer?.querySelectorAll('button')
+        expect(buttons?.length).toBe(2)
+      })
+    })
+  })
+
+  describe('combined props', () => {
+    it('should render all props together', async () => {
+      await usingAsync(new Injector(), async (injector) => {
+        const rootElement = document.getElementById('root') as HTMLDivElement
+
+        initializeShadeRoot({
+          injector,
+          rootElement,
+          jsxElement: (
+            <PageHeader
+              icon="👥"
+              title="Users"
+              description="Manage user accounts and their roles."
+              actions={<button type="button">Add User</button>}
+            />
+          ),
+        })
+
+        await sleepAsync(50)
+
+        const icon = document.querySelector('.page-header-icon')
+        expect(icon?.textContent).toBe('👥')
+
+        const title = document.querySelector('[data-testid="page-header-title"]')
+        expect(title?.textContent).toContain('Users')
+
+        const description = document.querySelector('[data-testid="page-header-description"]')
+        expect(description?.textContent).toBe('Manage user accounts and their roles.')
+
+        const actionsContainer = document.querySelector('[data-testid="page-header-actions"]')
+        expect(actionsContainer?.querySelector('button')).not.toBeNull()
+      })
+    })
+
+    it('should work with PageContainer integration', async () => {
+      await usingAsync(new Injector(), async (injector) => {
+        const rootElement = document.getElementById('root') as HTMLDivElement
+        const { PageContainer } = await import('./index.js')
+
+        initializeShadeRoot({
+          injector,
+          rootElement,
+          jsxElement: (
+            <PageContainer maxWidth="800px" centered>
+              <PageHeader icon="📊" title="Dashboard" description="Your data overview." />
+              <div>Content area</div>
+            </PageContainer>
+          ),
+        })
+
+        await sleepAsync(50)
+
+        const container = document.querySelector('div[is="shade-page-container"]')
+        expect(container).not.toBeNull()
+
+        const header = document.querySelector('shade-page-header')
+        expect(header).not.toBeNull()
+
+        const title = document.querySelector('[data-testid="page-header-title"]')
+        expect(title?.textContent).toContain('Dashboard')
+      })
+    })
+  })
+})

package/src/components/page-container/page-header.tsx

@@ -0,0 +1,127 @@
+import { Shade, createComponent } from '@furystack/shades'
+import { cssVariableTheme } from '../../services/css-variable-theme.js'
+import { Paper } from '../paper.js'
+
+/**
+ * Props for the PageHeader component.
+ */
+export type PageHeaderProps = {
+  /** Optional icon (emoji or single character) displayed before the title */
+  icon?: string
+  /** The page title */
+  title: string
+  /** Optional description text displayed below the title */
+  description?: string
+  /** Optional action elements (buttons, etc.) aligned to the right */
+  actions?: JSX.Element
+}
+
+/**
+ * PageHeader component for consistent page titles and descriptions.
+ *
+ * Provides a standardized header with:
+ * - Optional icon before the title
+ * - Main title with primary text styling
+ * - Optional description with secondary text styling
+ * - Optional action buttons aligned to the right
+ *
+ * @example
+ * ```tsx
+ * // Simple header with icon and description
+ * <PageHeader
+ *   icon="👥"
+ *   title="Users"
+ *   description="Manage user accounts and their roles."
+ * />
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Header with action buttons
+ * <PageHeader
+ *   icon="📁"
+ *   title="Projects"
+ *   description="View and manage your projects."
+ *   actions={
+ *     <Button variant="contained">Create Project</Button>
+ *   }
+ * />
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Minimal header (title only)
+ * <PageHeader title="Dashboard" />
+ * ```
+ */
+export const PageHeader = Shade<PageHeaderProps>({
+  shadowDomName: 'shade-page-header',
+  css: {
+    display: 'block',
+    position: 'sticky',
+    top: '0',
+    zIndex: `calc(${cssVariableTheme.zIndex.drawer} - 1)`,
+
+    '& .page-header-container': {
+      display: 'flex',
+      alignItems: 'center',
+      justifyContent: 'space-between',
+      gap: cssVariableTheme.spacing.md,
+    },
+
+    '& .page-header-content': {
+      flex: '1',
+      minWidth: '0',
+    },
+
+    '& .page-header-title': {
+      margin: '0',
+      fontSize: cssVariableTheme.typography.fontSize.xl,
+      fontWeight: cssVariableTheme.typography.fontWeight.semibold,
+      lineHeight: cssVariableTheme.typography.lineHeight.tight,
+      color: cssVariableTheme.text.primary,
+    },
+
+    '& .page-header-icon': {
+      marginRight: cssVariableTheme.spacing.sm,
+    },
+
+    '& .page-header-description': {
+      margin: `${cssVariableTheme.spacing.sm} 0 0 0`,
+      fontSize: cssVariableTheme.typography.fontSize.md,
+      lineHeight: cssVariableTheme.typography.lineHeight.normal,
+      color: cssVariableTheme.text.secondary,
+    },
+
+    '& .page-header-actions': {
+      display: 'flex',
+      alignItems: 'center',
+      gap: cssVariableTheme.spacing.sm,
+      flexShrink: '0',
+    },
+  },
+  render: ({ props }) => {
+    const { icon, title, description, actions } = props
+
+    return (
+      <Paper elevation={2} className="page-header-container">
+        <div className="page-header-content">
+          <h2 className="page-header-title" data-testid="page-header-title">
+            {icon && <span className="page-header-icon">{icon}</span>}
+            {title}
+          </h2>
+          {description && (
+            <p className="page-header-description" data-testid="page-header-description">
+              {description}
+            </p>
+          )}
+        </div>
+        {actions && (
+          <div className="page-header-actions" data-testid="page-header-actions">
+            {actions}
+          </div>
+        )}
+      </Paper>
+    )
+  },
+})