chati-dev 4.3.0 → 4.4.0

package/framework/scaffold/saas-dashboard/components/shell/Sidebar.tsx.template

@@ -0,0 +1,378 @@
+/*
+ * Sidebar.tsx -- Application Sidebar Navigation
+ * ============================================================
+ * WHY THIS FILE EXISTS
+ * --------------------
+ * The sidebar is the primary navigation surface for the
+ * dashboard. It must satisfy four competing demands:
+ *
+ *   1. Legibility: wide enough to show labels, icons, and
+ *      section groupings without crowding.
+ *
+ *   2. Density: collapsible to a 64px icon-only rail so the
+ *      content area can expand for data-heavy views.
+ *
+ *   3. Accessibility: keyboard navigation, focus management,
+ *      tooltip labels when collapsed, aria landmarks.
+ *
+ *   4. Responsiveness: on mobile the sidebar becomes a fixed
+ *      overlay drawer triggered by the Topbar hamburger.
+ *
+ * COLLAPSE ANIMATION APPROACH
+ * ---------------------------
+ * The sidebar does NOT animate its own width. The AppShell CSS
+ * Grid column handles width via the --shell-sidebar-w custom
+ * property. What the sidebar DOES animate:
+ *
+ *   - Label opacity: 0 when collapsed, 1 when expanded.
+ *     (opacity + visibility to keep labels out of tab order
+ *     when hidden.)
+ *   - Label max-width: 0 to 200px, controlling the visual
+ *     collapse without animating width (which is expensive).
+ *     We animate max-width only here because it is on a small
+ *     inline element (label text span) not the outer container,
+ *     so the layout shift is contained and acceptable.
+ *     NOTE: max-width IS animated here as an exception because
+ *     the element is a text-only span inside a flex row and
+ *     cannot be handled by opacity alone (hidden text still
+ *     occupies space). transform: scaleX(0) was evaluated but
+ *     causes subpixel blurring on retina. This is the pragmatic
+ *     trade-off.
+ *
+ * NAV STRUCTURE
+ * -------------
+ * The nav tree is defined as a static array of NavSection[].
+ * In a real product this would be constructed from the user's
+ * permissions and the application's route config. The static
+ * definition is intentional for the preset: it shows the
+ * structure without introducing a dependency on any specific
+ * auth or routing abstraction.
+ *
+ * ACTIVE STATE DETECTION
+ * ----------------------
+ * We use Next.js usePathname() to detect the active route and
+ * compare it against each item's href. Exact match is used for
+ * root routes; prefix match (startsWith) is used for section
+ * roots so that nested routes highlight the parent item.
+ *
+ * ACCESSIBILITY
+ * -------------
+ * - The sidebar is a <nav> element with aria-label="Main"
+ * - When collapsed, text labels are aria-hidden and visually
+ *   hidden; tooltips (title attr) provide the label
+ * - When a nav item is active, aria-current="page" is set
+ * - Keyboard: Tab moves between focusable items; no roving
+ *   tabindex (the nav is not a composite widget)
+ * - Section headings use <p role="heading" aria-level="2">
+ *   (not <h2>) to avoid polluting the document heading hierarchy
+ */
+
+'use client'
+
+import React from 'react';
+import { usePathname } from 'next/navigation'
+import Link from 'next/link'
+import {
+  LayoutDashboard,
+  Users,
+  BarChart3,
+  FileText,
+  Settings,
+  CreditCard,
+  Bell,
+  HelpCircle,
+  ChevronLeft,
+  type LucideIcon,
+} from 'lucide-react'
+import { useSidebar } from './SidebarContext'
+import { ThemeToggle } from './ThemeToggle'
+
+// ---------------------------------------------------------------------------
+// Nav data model
+// ---------------------------------------------------------------------------
+
+interface NavItem {
+  label: string
+  href: string
+  icon: LucideIcon
+  badge?: number
+  /** Exact match required for active detection (e.g. for root '/') */
+  exact?: boolean
+}
+
+interface NavSection {
+  id: string
+  heading?: string
+  items: NavItem[]
+}
+
+// Static nav structure. In production this would be derived from
+// permissions and the application route manifest.
+const NAV_SECTIONS: NavSection[] = [
+  {
+    id: 'main',
+    items: [
+      { label: 'Dashboard', href: '/dashboard', icon: LayoutDashboard, exact: true },
+      { label: 'Analytics', href: '/analytics', icon: BarChart3 },
+      { label: 'Customers', href: '/customers', icon: Users, badge: 4 },
+      { label: 'Documents', href: '/documents', icon: FileText },
+    ],
+  },
+  {
+    id: 'account',
+    heading: 'Account',
+    items: [
+      { label: 'Billing', href: '/billing', icon: CreditCard },
+      { label: 'Notifications', href: '/notifications', icon: Bell, badge: 12 },
+      { label: 'Settings', href: '/settings', icon: Settings },
+    ],
+  },
+  {
+    id: 'support',
+    heading: 'Support',
+    items: [
+      { label: 'Help & Docs', href: '/help', icon: HelpCircle },
+    ],
+  },
+]
+
+// ---------------------------------------------------------------------------
+// Helper: is this nav item active?
+// ---------------------------------------------------------------------------
+
+function isActive(href: string, pathname: string, exact?: boolean): boolean {
+  if (exact) return pathname === href
+  return pathname === href || pathname.startsWith(href + '/')
+}
+
+// ---------------------------------------------------------------------------
+// NavItemRow sub-component
+// ---------------------------------------------------------------------------
+// Extracted to keep the main component readable. This is NOT exported
+// as the public NavItem component (that lives in NavItem.tsx); this is
+// an internal render helper specific to Sidebar's layout.
+
+interface NavItemRowProps {
+  item: NavItem
+  isCollapsed: boolean
+  active: boolean
+}
+
+function NavItemRow({ item, isCollapsed, active }: NavItemRowProps) {
+  const Icon = item.icon
+
+  return (
+    <Link
+      href={item.href}
+      aria-current={active ? 'page' : undefined}
+      // When collapsed, the visible label is hidden; provide a title
+      // for the browser's native tooltip as a fallback. The accessible
+      // label is still provided by the sr-only span below.
+      title={isCollapsed ? item.label : undefined}
+      className={[
+        'sidebar-nav-item',
+        active ? 'sidebar-nav-item--active' : '',
+      ]
+        .filter(Boolean)
+        .join(' ')}
+    >
+      {/*
+       * Icon: always visible. aria-hidden because the text label
+       * (or sr-only label when collapsed) provides the accessible name.
+       */}
+      <span className="sidebar-nav-icon" aria-hidden="true">
+        <Icon size={18} strokeWidth={1.75} />
+      </span>
+
+      {/*
+       * Label: visible when expanded, clipped when collapsed.
+       * aria-hidden when collapsed because the title attribute
+       * provides the tooltip. A sr-only span is always present
+       * so the accessible name is available regardless of state.
+       */}
+      <span
+        className="sidebar-nav-label"
+        aria-hidden={isCollapsed}
+      >
+        {item.label}
+      </span>
+
+      {/* Always-available SR label (visible or hidden, SR always reads it) */}
+      {isCollapsed && (
+        <span className="sr-only">{item.label}</span>
+      )}
+
+      {/*
+       * Badge: unread count. Hidden when collapsed (tooltip cannot
+       * show it; that is acceptable for counts -- the content itself
+       * will surface the unread state on click).
+       */}
+      {item.badge !== undefined && !isCollapsed && (
+        <span className="sidebar-nav-badge" aria-label={`${item.badge} unread`}>
+          {item.badge > 99 ? '99+' : item.badge}
+        </span>
+      )}
+      {item.badge !== undefined && isCollapsed && (
+        <span className="sidebar-nav-badge-dot" aria-hidden="true" />
+      )}
+    </Link>
+  )
+}
+
+// ---------------------------------------------------------------------------
+// Main Sidebar component
+// ---------------------------------------------------------------------------
+
+export function Sidebar() {
+  const { isCollapsed, isMobileOpen, toggle, closeMobile } = useSidebar()
+  const pathname = usePathname()
+
+  return (
+    /*
+     * Overlay: on mobile, a separate backdrop is rendered by AppShell.
+     * The sidebar itself uses position:fixed on mobile and translateX
+     * to slide in/out. On desktop it is in the normal grid flow.
+     *
+     * class "sidebar" handles desktop grid-column layout.
+     * class "sidebar--collapsed" shrinks labels.
+     * class "sidebar--mobile-open" triggers mobile slide-in.
+     */
+    <>
+      <aside
+        className={[
+          'sidebar',
+          isCollapsed ? 'sidebar--collapsed' : '',
+          isMobileOpen ? 'sidebar--mobile-open' : '',
+        ]
+          .filter(Boolean)
+          .join(' ')}
+        aria-label="Main"
+      >
+        {/* ----------------------------------------------------------------
+         * Header: logo / wordmark + collapse toggle
+         * ---------------------------------------------------------------- */}
+        <div className="sidebar-header">
+          {/* Logo mark: always visible */}
+          <div className="sidebar-logo" aria-hidden="true">
+            <span className="sidebar-logo-mark" />
+          </div>
+
+          {/* Wordmark: visible only when expanded */}
+          <span className="sidebar-wordmark" aria-hidden={isCollapsed}>
+            Acme
+          </span>
+
+          {/*
+           * Collapse toggle: desktop only (hidden on mobile via CSS).
+           * aria-expanded reflects the current state.
+           * aria-controls references the nav element below.
+           */}
+          <button
+            type="button"
+            onClick={toggle}
+            aria-expanded={!isCollapsed}
+            aria-controls="sidebar-nav"
+            aria-label={isCollapsed ? 'Expand sidebar' : 'Collapse sidebar'}
+            className="sidebar-collapse-btn"
+          >
+            <span
+              className={[
+                'sidebar-collapse-icon',
+                isCollapsed ? 'sidebar-collapse-icon--flipped' : '',
+              ]
+                .filter(Boolean)
+                .join(' ')}
+              aria-hidden="true"
+            >
+              <ChevronLeft size={16} strokeWidth={2} />
+            </span>
+          </button>
+
+          {/* Mobile close button: visible only on mobile when drawer is open */}
+          <button
+            type="button"
+            onClick={closeMobile}
+            aria-label="Close navigation"
+            className="sidebar-mobile-close-btn"
+          >
+            <span aria-hidden="true">&times;</span>
+          </button>
+        </div>
+
+        {/* ----------------------------------------------------------------
+         * Nav sections
+         * ---------------------------------------------------------------- */}
+        <nav
+          id="sidebar-nav"
+          className="sidebar-nav"
+          aria-label="Main navigation"
+        >
+          {NAV_SECTIONS.map((section, sectionIndex) => (
+            <div
+              key={section.id}
+              className="sidebar-section"
+              // Stagger animation delay: each section appears 40ms after
+              // the previous. Implemented via CSS nth-child + animation-delay.
+              // The CSS variable is read by the sidebar-section animation rule.
+              style={{ '--section-index': sectionIndex } as React.CSSProperties}
+            >
+              {/* Section heading: hidden when sidebar is collapsed */}
+              {section.heading && (
+                <p
+                  role="heading"
+                  aria-level={2}
+                  className="sidebar-section-heading"
+                  aria-hidden={isCollapsed}
+                >
+                  {section.heading}
+                </p>
+              )}
+
+              <ul role="list" className="sidebar-section-list">
+                {section.items.map((item) => (
+                  <li key={item.href}>
+                    <NavItemRow
+                      item={item}
+                      isCollapsed={isCollapsed}
+                      active={isActive(item.href, pathname, item.exact)}
+                    />
+                  </li>
+                ))}
+              </ul>
+            </div>
+          ))}
+        </nav>
+
+        {/* ----------------------------------------------------------------
+         * Sidebar footer: user identity + theme toggle + settings
+         * ---------------------------------------------------------------- */}
+        <div className="sidebar-footer">
+          {!isCollapsed && (
+            <div className="sidebar-user">
+              {/* Avatar */}
+              <div className="sidebar-user-avatar" aria-hidden="true">
+                <span className="sidebar-user-initials">GA</span>
+              </div>
+              <div className="sidebar-user-info">
+                <p className="sidebar-user-name">Gabriel A.</p>
+                <p className="sidebar-user-email">gabriel@example.com</p>
+              </div>
+            </div>
+          )}
+
+          {isCollapsed && (
+            <div
+              className="sidebar-user-avatar sidebar-user-avatar--collapsed"
+              title="Gabriel A."
+              aria-label="User: Gabriel A."
+            >
+              <span className="sidebar-user-initials" aria-hidden="true">GA</span>
+            </div>
+          )}
+
+          <ThemeToggle />
+        </div>
+      </aside>
+    </>
+  )
+}

package/framework/scaffold/saas-dashboard/components/shell/SidebarContext.tsx.template

@@ -0,0 +1,169 @@
+/*
+ * SidebarContext.tsx -- Sidebar Collapse State Context
+ * ============================================================
+ * WHY THIS FILE EXISTS
+ * --------------------
+ * Multiple components in the shell need to read and react to the
+ * sidebar's collapsed state:
+ *
+ *   - AppShell: adjusts the CSS grid column width
+ *   - Sidebar: controls its own visual width and label visibility
+ *   - NavItem: hides text labels, shows tooltips when collapsed
+ *   - Topbar: adjusts the hamburger icon aria-expanded state
+ *
+ * Rather than threading a `collapsed` prop through three levels of
+ * components (which would create brittle coupling), we use a
+ * React context with a provider at the AppShell boundary. Any
+ * consumer can read or mutate the state without knowing about the
+ * others.
+ *
+ * PERSISTENCE STRATEGY
+ * --------------------
+ * We persist the collapsed preference to localStorage under the
+ * key 'sidebar-collapsed'. This means the sidebar renders in the
+ * user's last-chosen state on the next session. The initial state
+ * is read synchronously from localStorage during the provider's
+ * useState initializer (a function passed to useState runs once,
+ * on mount, in the browser). On the server there is no
+ * localStorage, so we default to expanded (false).
+ *
+ * MOBILE BEHAVIOR
+ * ---------------
+ * On mobile viewports the sidebar is hidden off-screen regardless
+ * of the collapsed preference. A separate `isMobileOpen` boolean
+ * controls whether the mobile overlay drawer is visible. These
+ * two states are intentionally separate:
+ *   - isCollapsed: user's icon-only preference on desktop
+ *   - isMobileOpen: whether the drawer is open on mobile
+ *
+ * TYPESCRIPT
+ * ----------
+ * The context value is fully typed with a default of null so
+ * consumers that call useContext outside the provider boundary
+ * receive a helpful error via the useSidebar() hook guard.
+ */
+
+'use client'
+
+import {
+  createContext,
+  useContext,
+  useState,
+  useCallback,
+  useEffect,
+  type ReactNode,
+} from 'react'
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+export interface SidebarContextValue {
+  /** Whether the desktop sidebar is in icon-only collapsed mode */
+  isCollapsed: boolean
+  /** Whether the mobile overlay drawer is open */
+  isMobileOpen: boolean
+  /** Toggle collapsed state (desktop) */
+  toggle: () => void
+  /** Force collapsed state to true */
+  collapse: () => void
+  /** Force collapsed state to false */
+  expand: () => void
+  /** Open the mobile overlay drawer */
+  openMobile: () => void
+  /** Close the mobile overlay drawer */
+  closeMobile: () => void
+}
+
+// ---------------------------------------------------------------------------
+// Context
+// ---------------------------------------------------------------------------
+
+const SidebarContext = createContext<SidebarContextValue | null>(null)
+
+// ---------------------------------------------------------------------------
+// Hook
+// ---------------------------------------------------------------------------
+
+/**
+ * useSidebar -- access sidebar context from any child component.
+ *
+ * Throws a descriptive error if called outside a SidebarProvider,
+ * which makes debugging layout issues much easier during development.
+ */
+export function useSidebar(): SidebarContextValue {
+  const ctx = useContext(SidebarContext)
+  if (ctx === null) {
+    throw new Error(
+      'useSidebar must be called inside a <SidebarProvider>. ' +
+        'Wrap your AppShell (or root layout) with <SidebarProvider>.'
+    )
+  }
+  return ctx
+}
+
+// ---------------------------------------------------------------------------
+// Provider
+// ---------------------------------------------------------------------------
+
+const STORAGE_KEY = 'sidebar-collapsed'
+
+export function SidebarProvider({ children }: { children: ReactNode }) {
+  // Read the persisted preference synchronously. The initializer function
+  // runs only once (on mount) so this does not cause repeated localStorage
+  // reads on re-renders.
+  const [isCollapsed, setIsCollapsed] = useState<boolean>(() => {
+    if (typeof window === 'undefined') return false
+    try {
+      const stored = window.localStorage.getItem(STORAGE_KEY)
+      return stored === 'true'
+    } catch {
+      return false
+    }
+  })
+
+  const [isMobileOpen, setIsMobileOpen] = useState(false)
+
+  // Persist every change to localStorage. useEffect is the right place
+  // because localStorage is a side effect and not part of render.
+  useEffect(() => {
+    try {
+      window.localStorage.setItem(STORAGE_KEY, String(isCollapsed))
+    } catch {
+      // localStorage may be unavailable in private browsing; fail silently.
+    }
+  }, [isCollapsed])
+
+  // Close mobile drawer on resize above the mobile breakpoint so the
+  // drawer does not linger open when the viewport expands.
+  useEffect(() => {
+    const mq = window.matchMedia('(min-width: 768px)')
+    const handler = (e: MediaQueryListEvent) => {
+      if (e.matches) setIsMobileOpen(false)
+    }
+    mq.addEventListener('change', handler)
+    return () => mq.removeEventListener('change', handler)
+  }, [])
+
+  const toggle = useCallback(() => setIsCollapsed((v) => !v), [])
+  const collapse = useCallback(() => setIsCollapsed(true), [])
+  const expand = useCallback(() => setIsCollapsed(false), [])
+  const openMobile = useCallback(() => setIsMobileOpen(true), [])
+  const closeMobile = useCallback(() => setIsMobileOpen(false), [])
+
+  return (
+    <SidebarContext.Provider
+      value={{
+        isCollapsed,
+        isMobileOpen,
+        toggle,
+        collapse,
+        expand,
+        openMobile,
+        closeMobile,
+      }}
+    >
+      {children}
+    </SidebarContext.Provider>
+  )
+}

package/framework/scaffold/saas-dashboard/components/shell/ThemeToggle.tsx.template

@@ -0,0 +1,128 @@
+/*
+ * ThemeToggle.tsx -- Dark/Light Theme Toggle
+ * ============================================================
+ * WHY THIS FILE EXISTS
+ * --------------------
+ * The application ships with a designed dark palette as the
+ * default. Some users prefer a light theme. ThemeToggle allows
+ * in-app switching without reloading the page.
+ *
+ * MECHANISM
+ * ---------
+ * Theme switching is implemented by toggling data-theme='light'
+ * on the <html> element. The root layout.tsx sets data-theme='dark'
+ * by default. globals.css declares [data-theme='light'] { ... }
+ * overrides for all semantic tokens. This approach:
+ *
+ *   1. Requires no CSS framework changes (Tailwind dark: prefix
+ *      would require knowing the toggle state at build time).
+ *   2. Is instantaneous (no class re-computation, just a DOM
+ *      attribute change that triggers a CSS cascade update).
+ *   3. Works with server-rendered initial HTML (no FOUC for dark).
+ *
+ * PERSISTENCE
+ * -----------
+ * The preference is stored in localStorage under 'color-theme'.
+ * On mount (useEffect), the saved preference is read and applied.
+ * Because layout.tsx sets data-theme='dark' and suppresses the
+ * hydration warning, there is a brief flash only on light-theme
+ * users' first paint. This is the standard trade-off for
+ * server-rendered apps with client-side theme preferences.
+ *
+ * ANIMATION
+ * ---------
+ * The Sun and Moon icons cross-fade via opacity transition at
+ * --duration-normal (200ms) with --ease-in-out. Both icons are
+ * rendered at all times; the inactive one has opacity:0. This
+ * avoids layout shift from conditional rendering and produces a
+ * smooth cross-dissolve effect.
+ *
+ * ACCESSIBILITY
+ * -------------
+ * - The button has an sr-only label that reflects the current
+ *   action: 'Switch to light theme' or 'Switch to dark theme'.
+ * - The icons are aria-hidden (decorative).
+ * - The button uses the topbar-icon-btn class which includes the
+ *   global focus ring from globals.css.
+ */
+
+'use client'
+
+import { useState, useEffect } from 'react'
+import { Sun, Moon } from 'lucide-react'
+
+// ---------------------------------------------------------------------------
+// Types + constants
+// ---------------------------------------------------------------------------
+
+type Theme = 'dark' | 'light'
+const STORAGE_KEY = 'color-theme'
+
+// ---------------------------------------------------------------------------
+// Component
+// ---------------------------------------------------------------------------
+
+export function ThemeToggle() {
+  const [theme, setTheme] = useState<Theme>('dark')
+
+  // Read the persisted preference on mount and apply it.
+  useEffect(() => {
+    try {
+      const stored = window.localStorage.getItem(STORAGE_KEY) as Theme | null
+      if (stored === 'light' || stored === 'dark') {
+        setTheme(stored)
+        document.documentElement.setAttribute('data-theme', stored)
+      }
+    } catch {
+      // Fail silently if localStorage is unavailable.
+    }
+  }, [])
+
+  function handleToggle() {
+    const next: Theme = theme === 'dark' ? 'light' : 'dark'
+    setTheme(next)
+    document.documentElement.setAttribute('data-theme', next)
+    try {
+      window.localStorage.setItem(STORAGE_KEY, next)
+    } catch {
+      // Fail silently.
+    }
+  }
+
+  const isDark = theme === 'dark'
+
+  return (
+    <button
+      type="button"
+      onClick={handleToggle}
+      // aria-pressed communicates the current state (dark = pressed).
+      // Users can infer: pressed = dark mode is ON.
+      aria-pressed={isDark}
+      className="theme-toggle topbar-icon-btn"
+    >
+      {/*
+       * Both icons are always in the DOM. Transitions are on opacity
+       * only, so no layout shift occurs when switching themes.
+       */}
+      <span
+        className="theme-toggle-icon"
+        style={{ opacity: isDark ? 0 : 1 }}
+        aria-hidden="true"
+      >
+        <Sun size={18} strokeWidth={1.75} />
+      </span>
+      <span
+        className="theme-toggle-icon theme-toggle-icon--overlay"
+        style={{ opacity: isDark ? 1 : 0 }}
+        aria-hidden="true"
+      >
+        <Moon size={18} strokeWidth={1.75} />
+      </span>
+
+      {/* SR label: states the action (what will happen next). */}
+      <span className="sr-only">
+        {isDark ? 'Switch to light theme' : 'Switch to dark theme'}
+      </span>
+    </button>
+  )
+}