@fragments-sdk/ui 0.3.0 → 0.4.0

package/src/components/Header/Header.fragment.tsx

@@ -0,0 +1,192 @@
+import React from 'react';
+import { defineSegment } from '@fragments/core';
+import { Header } from './index.js';
+import { ThemeToggle, ThemeProvider } from '../Theme/index.js';
+import { Button } from '../Button/index.js';
+import { Input } from '../Input/index.js';
+
+function SearchIcon() {
+  return (
+    <svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" viewBox="0 0 256 256" fill="currentColor">
+      <path d="M229.66,218.34l-50.07-50.06a88.11,88.11,0,1,0-11.31,11.31l50.06,50.07a8,8,0,0,0,11.32-11.32ZM40,112a72,72,0,1,1,72,72A72.08,72.08,0,0,1,40,112Z" />
+    </svg>
+  );
+}
+
+export default defineSegment({
+  component: Header,
+
+  meta: {
+    name: 'Header',
+    description: 'Composable header with slots for brand, navigation, search, and actions. Designed for use within AppShell with responsive mobile support.',
+    category: 'navigation',
+    status: 'stable',
+    tags: ['header', 'navigation', 'navbar', 'brand', 'layout'],
+    since: '0.5.0',
+  },
+
+  usage: {
+    when: [
+      'Primary site or app header inside AppShell',
+      'Navigation bar with branding (stacked layout)',
+      'Search and actions bar (sidebar-inset layout)',
+      'Header with responsive mobile menu trigger',
+    ],
+    whenNot: [
+      'Simple page titles (use heading elements)',
+      'Footer navigation (use Footer component)',
+      'Standalone sidebar navigation (use Sidebar directly)',
+    ],
+    guidelines: [
+      'Use Header.SkipLink for accessibility (skip to main content)',
+      'In stacked layout: include Header.Brand for logo',
+      'In sidebar-inset layout: omit Header.Brand (logo in sidebar)',
+      'Header.Trigger integrates with SidebarProvider for mobile menus',
+      'Header.Nav is hidden on mobile; use sidebar for mobile navigation',
+      'Use Header.Spacer to push items apart',
+    ],
+    accessibility: [
+      'Include Header.SkipLink for keyboard users',
+      'Navigation has aria-label for screen readers',
+      'Active nav items use aria-current="page"',
+      'Mobile trigger has aria-expanded state',
+    ],
+  },
+
+  props: {
+    children: {
+      type: 'node',
+      description: 'Header content (use Header.Brand, Header.Nav, etc.)',
+      required: true,
+    },
+    height: {
+      type: 'string',
+      description: 'Header height',
+      default: '56px',
+    },
+    position: {
+      type: 'enum',
+      description: 'Position behavior (usually controlled by AppShell)',
+      values: ['static', 'fixed', 'sticky'],
+      default: 'static',
+    },
+  },
+
+  relations: [
+    { component: 'AppShell', relationship: 'parent', note: 'Header is typically used inside AppShell.Header' },
+    { component: 'Sidebar', relationship: 'sibling', note: 'Header.Trigger toggles Sidebar on mobile' },
+    { component: 'ThemeToggle', relationship: 'child', note: 'ThemeToggle is commonly placed in Header.Actions' },
+  ],
+
+  ai: {
+    compositionPattern: 'compound',
+    subComponents: ['SkipLink', 'Trigger', 'Brand', 'Nav', 'NavItem', 'Search', 'Spacer', 'Actions'],
+    commonPatterns: [
+      '<Header><Header.Brand href="/">{appName}</Header.Brand><Header.Nav><Header.NavItem href="/home" active>Home</Header.NavItem></Header.Nav><Header.Spacer /><Header.Actions>{actions}</Header.Actions></Header>',
+    ],
+  },
+
+  variants: [
+    {
+      name: 'For Stacked Layout',
+      description: 'Header with brand, nav, and actions. Use with AppShell layout="stacked".',
+      render: () => (
+        <ThemeProvider defaultMode="light">
+          <Header>
+            <Header.SkipLink />
+            <Header.Trigger />
+            <Header.Brand href="/">MyApp</Header.Brand>
+            <Header.Nav>
+              <Header.NavItem href="/dashboard" active>Dashboard</Header.NavItem>
+              <Header.NavItem href="/projects">Projects</Header.NavItem>
+              <Header.NavItem href="/settings">Settings</Header.NavItem>
+            </Header.Nav>
+            <Header.Spacer />
+            <Header.Actions>
+              <ThemeToggle size="md" />
+              <Button variant="secondary" size="sm">Sign In</Button>
+            </Header.Actions>
+          </Header>
+        </ThemeProvider>
+      ),
+    },
+    {
+      name: 'For Sidebar Inset Layout',
+      description: 'Header without brand (logo is in sidebar). Use with AppShell layout="sidebar-inset".',
+      render: () => (
+        <ThemeProvider defaultMode="light">
+          <Header>
+            <Header.SkipLink />
+            <Header.Trigger />
+            <Header.Search>
+              <Input placeholder="Search..." style={{ width: '240px' }} />
+            </Header.Search>
+            <Header.Spacer />
+            <Header.Actions>
+              <ThemeToggle size="md" />
+            </Header.Actions>
+          </Header>
+        </ThemeProvider>
+      ),
+    },
+    {
+      name: 'Minimal',
+      description: 'Clean header with just trigger and actions',
+      render: () => (
+        <ThemeProvider defaultMode="light">
+          <Header>
+            <Header.Trigger />
+            <Header.Spacer />
+            <Header.Actions>
+              <ThemeToggle size="md" />
+            </Header.Actions>
+          </Header>
+        </ThemeProvider>
+      ),
+    },
+    {
+      name: 'With Search',
+      description: 'Header featuring a prominent search input',
+      render: () => (
+        <ThemeProvider defaultMode="light">
+          <Header>
+            <Header.Brand>Docs</Header.Brand>
+            <Header.Search>
+              <div style={{
+                display: 'flex',
+                alignItems: 'center',
+                gap: '8px',
+                padding: '8px 12px',
+                background: 'var(--fui-bg-secondary)',
+                borderRadius: '6px',
+                color: 'var(--fui-text-tertiary)',
+                fontSize: '14px',
+                width: '280px'
+              }}>
+                <SearchIcon /> Search documentation...
+              </div>
+            </Header.Search>
+            <Header.Spacer />
+            <Header.Actions>
+              <ThemeToggle size="md" />
+            </Header.Actions>
+          </Header>
+        </ThemeProvider>
+      ),
+    },
+    {
+      name: 'With Skip Link',
+      description: 'Accessible header with skip link for keyboard navigation',
+      render: () => (
+        <Header>
+          <Header.SkipLink href="#main-content">Skip to content</Header.SkipLink>
+          <Header.Brand>Accessible App</Header.Brand>
+          <Header.Nav>
+            <Header.NavItem href="/" active>Home</Header.NavItem>
+            <Header.NavItem href="/about">About</Header.NavItem>
+          </Header.Nav>
+        </Header>
+      ),
+    },
+  ],
+});

package/src/components/Header/Header.module.scss

@@ -0,0 +1,209 @@
+@use '../../tokens/variables' as *;
+@use '../../tokens/mixins' as *;
+
+// ============================================
+// Header Root
+// ============================================
+
+.header {
+  display: flex;
+  align-items: center;
+  height: var(--header-height, 56px);
+  min-height: var(--header-height, 56px);
+  background-color: var(--fui-bg-primary, $fui-bg-primary);
+  padding: 0 var(--fui-space-4, $fui-space-4);
+  z-index: var(--fui-header-z-index, 40);
+}
+
+.fixed {
+  position: fixed;
+  top: 0;
+  left: 0;
+  right: 0;
+}
+
+.sticky {
+  position: sticky;
+  top: 0;
+}
+
+.container {
+  display: flex;
+  align-items: center;
+  gap: var(--fui-space-4, $fui-space-4);
+  width: 100%;
+  max-width: 100%;
+}
+
+// ============================================
+// Brand
+// ============================================
+
+.brand {
+  display: flex;
+  align-items: center;
+  gap: var(--fui-space-2, $fui-space-2);
+  text-decoration: none;
+  color: var(--fui-text-primary, $fui-text-primary);
+  font-weight: var(--fui-font-weight-semibold, $fui-font-weight-semibold);
+  font-size: var(--fui-font-size-base, $fui-font-size-base);
+  flex-shrink: 0;
+
+  &:hover {
+    color: var(--fui-text-primary, $fui-text-primary);
+  }
+
+  img,
+  svg {
+    height: 32px;
+    width: auto;
+  }
+}
+
+// ============================================
+// Navigation
+// ============================================
+
+.nav {
+  display: none;
+
+  @include breakpoint-md {
+    display: flex;
+    align-items: center;
+  }
+}
+
+.navList {
+  display: flex;
+  align-items: center;
+  gap: var(--fui-space-1, $fui-space-1);
+  list-style: none;
+  margin: 0;
+  padding: 0;
+}
+
+.navItem {
+  @include button-reset;
+  @include interactive-base;
+  @include text-base;
+
+  display: flex;
+  align-items: center;
+  padding: var(--fui-space-1, $fui-space-1) var(--fui-space-3, $fui-space-3);
+  border-radius: var(--fui-radius-md, $fui-radius-md);
+  color: var(--fui-text-secondary, $fui-text-secondary);
+  text-decoration: none;
+  white-space: nowrap;
+  min-height: 36px;
+
+  &:hover {
+    background-color: var(--fui-bg-hover, $fui-bg-hover);
+    color: var(--fui-text-primary, $fui-text-primary);
+  }
+
+  &:active {
+    background-color: var(--fui-bg-active, $fui-bg-active);
+  }
+}
+
+.navItemActive {
+  color: var(--fui-text-primary, $fui-text-primary);
+  font-weight: var(--fui-font-weight-medium, $fui-font-weight-medium);
+  background-color: var(--fui-bg-hover, $fui-bg-hover);
+}
+
+// ============================================
+// Search
+// ============================================
+
+.search {
+  display: none;
+
+  @include breakpoint-md {
+    display: flex;
+    align-items: center;
+  }
+}
+
+.searchExpandable {
+  display: flex;
+}
+
+// ============================================
+// Actions
+// ============================================
+
+.actions {
+  display: flex;
+  align-items: center;
+  gap: var(--fui-space-2, $fui-space-2);
+  margin-left: auto;
+}
+
+// ============================================
+// Trigger (Mobile menu button)
+// ============================================
+
+.trigger {
+  @include button-reset;
+  @include interactive-base;
+
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  width: 44px;
+  height: 44px;
+  border-radius: var(--fui-radius-md, $fui-radius-md);
+  color: var(--fui-text-primary, $fui-text-primary);
+  flex-shrink: 0;
+
+  &:hover {
+    background-color: var(--fui-bg-hover, $fui-bg-hover);
+  }
+
+  svg {
+    width: 24px;
+    height: 24px;
+  }
+}
+
+// ============================================
+// Spacer
+// ============================================
+
+.spacer {
+  flex: 1;
+}
+
+// ============================================
+// Skip Link (Accessibility)
+// ============================================
+
+.skipLink {
+  @include visually-hidden;
+
+  position: absolute;
+  top: var(--fui-space-2, $fui-space-2);
+  left: var(--fui-space-2, $fui-space-2);
+  z-index: 100;
+  padding: var(--fui-space-2, $fui-space-2) var(--fui-space-4, $fui-space-4);
+  background-color: var(--fui-bg-primary, $fui-bg-primary);
+  color: var(--fui-text-primary, $fui-text-primary);
+  border: 2px solid var(--fui-color-accent, $fui-color-accent);
+  border-radius: var(--fui-radius-md, $fui-radius-md);
+  text-decoration: none;
+  font-weight: var(--fui-font-weight-medium, $fui-font-weight-medium);
+
+  &:focus {
+    position: absolute;
+    width: auto;
+    height: auto;
+    clip: auto;
+    white-space: normal;
+    margin: 0;
+    padding: var(--fui-space-2, $fui-space-2) var(--fui-space-4, $fui-space-4);
+    overflow: visible;
+
+    @include focus-ring;
+  }
+}