chati-dev 4.3.1 → 4.4.0

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

@@ -0,0 +1,301 @@
+/*
+ * Topbar.tsx -- Application Topbar
+ * ============================================================
+ * WHY THIS FILE EXISTS
+ * --------------------
+ * The topbar is the sticky horizontal bar that sits at the top
+ * of the main content column (not the full viewport width).
+ * It serves four roles:
+ *
+ *   1. Navigation context: the breadcrumb trail tells the user
+ *      where they are in the application hierarchy.
+ *
+ *   2. Sidebar control: the hamburger/collapse button is the
+ *      only interactive element that controls sidebar state.
+ *      On mobile it opens the overlay drawer; on desktop it
+ *      toggles icon-only mode.
+ *
+ *   3. Global search: the search button opens the CommandPalette
+ *      (Cmd+K shortcut). The button is keyboard-accessible and
+ *      shows the keyboard shortcut hint.
+ *
+ *   4. User affordances: notification bell (with unread count
+ *      badge) and a user menu trigger (avatar + chevron).
+ *
+ * POSITIONING
+ * -----------
+ * The Topbar uses position:sticky with top:0. It sits in the
+ * second grid column (shell-main) alongside the scrollable
+ * <main>. This means it scrolls with the sidebar but stays
+ * fixed relative to the main content viewport. z-index is
+ * --z-topbar (40) so it appears above content but below modals.
+ *
+ * BACKDROP BLUR
+ * -------------
+ * backdrop-filter: blur(8px) creates a frosted-glass effect
+ * when content scrolls behind the topbar. We also set a
+ * semi-transparent bg-overlay background (NOT full opacity)
+ * to let the blur be visible. This is intentional: full-opacity
+ * backgrounds would make the blur invisible.
+ *
+ * BREADCRUMB
+ * ----------
+ * The Breadcrumb component is imported from its own file where
+ * it derives crumbs from the Next.js pathname. Topbar owns the
+ * placement but not the logic.
+ *
+ * SEARCH KEYBOARD SHORTCUT
+ * -------------------------
+ * A useEffect registers the Cmd+K (Mac) / Ctrl+K (Windows/Linux)
+ * shortcut globally. The shortcut state is lifted to this
+ * component because Topbar is always mounted, making it the
+ * right place for global keyboard shortcuts that do not belong
+ * to a specific page.
+ *
+ * ARIA
+ * ----
+ * The topbar is a <header> element (banner landmark). The
+ * hamburger button has aria-expanded and aria-controls tied
+ * to the sidebar nav. The notification button uses aria-label
+ * that includes the count ("12 unread notifications") so
+ * screen readers announce the count without the user needing
+ * to read the visual badge.
+ */
+
+'use client'
+
+import React, { useState, useEffect, useCallback, useRef } from 'react'
+import { useCommandPalette } from '../interaction/CommandPalette';
+import Link from 'next/link'
+import {
+  Menu,
+  Search,
+  Bell,
+  ChevronDown,
+  Settings,
+  LogOut,
+  User,
+  Command,
+  type LucideIcon,
+} from 'lucide-react'
+import { useSidebar } from './SidebarContext'
+import { Breadcrumb } from './Breadcrumb'
+import { ThemeToggle } from './ThemeToggle'
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+// Notification count: in a real app this would come from a server action
+// or a real-time subscription. Static for the preset.
+const NOTIFICATION_COUNT = 4
+
+// ---------------------------------------------------------------------------
+// User menu items
+// ---------------------------------------------------------------------------
+
+type UserMenuItem = { label: string; href: string; icon: LucideIcon; destructive?: boolean };
+
+const USER_MENU_ITEMS: UserMenuItem[] = [
+  { label: 'Your Profile', href: '/settings/profile', icon: User },
+  { label: 'Settings', href: '/settings', icon: Settings },
+  { label: 'Sign out', href: '/auth/sign-out', icon: LogOut, destructive: true },
+]
+
+// ---------------------------------------------------------------------------
+// Component
+// ---------------------------------------------------------------------------
+
+export function Topbar() {
+  const { toggle, openMobile, isCollapsed } = useSidebar()
+  const [userMenuOpen, setUserMenuOpen] = useState(false)
+  const userMenuRef = useRef<HTMLDivElement>(null)
+
+  // The CommandPaletteProvider (mounted in layout) owns the palette open state
+  // and the global Cmd+K / Ctrl+K shortcut. The top bar just opens it.
+  const { open: openCommandPalette } = useCommandPalette()
+
+  // ---- Close user menu on click-outside -----------------------------------
+  useEffect(() => {
+    function handleClickOutside(e: MouseEvent) {
+      if (userMenuRef.current && !userMenuRef.current.contains(e.target as Node)) {
+        setUserMenuOpen(false)
+      }
+    }
+    if (userMenuOpen) {
+      document.addEventListener('mousedown', handleClickOutside)
+      return () => document.removeEventListener('mousedown', handleClickOutside)
+    }
+  }, [userMenuOpen])
+
+  // ---- Close user menu on Escape ------------------------------------------
+  const handleUserMenuKeyDown = useCallback(
+    (e: React.KeyboardEvent) => {
+      if (e.key === 'Escape') {
+        setUserMenuOpen(false)
+      }
+    },
+    []
+  )
+
+  // ---- Determine if we are on mobile (client-only) ------------------------
+  // We detect mobile by CSS media query rather than viewport width JS so
+  // the hamburger behavior (openMobile vs toggle) is correct on resize.
+  const handleSidebarTrigger = useCallback(() => {
+    if (window.matchMedia('(max-width: 767px)').matches) {
+      openMobile()
+    } else {
+      toggle()
+    }
+  }, [toggle, openMobile])
+
+  return (
+    <header className="topbar" role="banner">
+      <div className="topbar-inner">
+        {/* ---- Left: sidebar trigger + breadcrumb ---- */}
+        <div className="topbar-left">
+          {/*
+           * Sidebar toggle button. On mobile: opens the overlay drawer.
+           * On desktop: toggles icon-only collapse.
+           * aria-expanded reflects sidebar state (desktop only).
+           * aria-controls links to the sidebar nav element.
+           */}
+          <button
+            type="button"
+            onClick={handleSidebarTrigger}
+            aria-label="Toggle navigation"
+            aria-expanded={!isCollapsed}
+            aria-controls="sidebar-nav"
+            className="topbar-icon-btn"
+          >
+            <Menu size={20} aria-hidden="true" />
+          </button>
+
+          {/* Breadcrumb trail: derives crumbs from Next.js pathname */}
+          <Breadcrumb />
+        </div>
+
+        {/* ---- Right: search + notifications + user menu ---- */}
+        <div className="topbar-right">
+          {/*
+           * Search / command palette trigger.
+           * Shows Cmd+K hint on desktop (hidden on mobile via CSS).
+           */}
+          <button
+            type="button"
+            onClick={openCommandPalette}
+            aria-label="Open command palette"
+            aria-keyshortcuts="Control+k Meta+k"
+            className="topbar-search-btn"
+          >
+            <Search size={16} aria-hidden="true" className="topbar-search-icon" />
+            <span className="topbar-search-label">Search...</span>
+            <kbd className="topbar-search-kbd" aria-hidden="true">
+              <Command size={10} />
+              K
+            </kbd>
+          </button>
+
+          {/*
+           * Notification bell.
+           * aria-label includes the count so SR users hear it.
+           * The visual badge is aria-hidden (count is in the label).
+           */}
+          <button
+            type="button"
+            aria-label={
+              NOTIFICATION_COUNT > 0
+                ? `${NOTIFICATION_COUNT} unread notifications`
+                : 'Notifications, none unread'
+            }
+            className="topbar-icon-btn topbar-icon-btn--relative"
+          >
+            <Bell size={20} aria-hidden="true" />
+            {NOTIFICATION_COUNT > 0 && (
+              <span className="topbar-notif-badge" aria-hidden="true">
+                {NOTIFICATION_COUNT > 9 ? '9+' : NOTIFICATION_COUNT}
+              </span>
+            )}
+          </button>
+
+          {/*
+           * User menu: avatar + name + dropdown.
+           * role="button" + aria-haspopup + aria-expanded for the trigger.
+           * The dropdown is a role="menu" with role="menuitem" children.
+           */}
+          <div
+            ref={userMenuRef}
+            className="topbar-user-menu"
+            onKeyDown={handleUserMenuKeyDown}
+          >
+            <button
+              type="button"
+              id="user-menu-trigger"
+              aria-haspopup="menu"
+              aria-expanded={userMenuOpen}
+              aria-controls="user-menu-dropdown"
+              onClick={() => setUserMenuOpen((v) => !v)}
+              className="topbar-user-trigger"
+            >
+              {/* Avatar */}
+              <span className="topbar-avatar" aria-hidden="true">
+                GA
+              </span>
+              {/* Name: hidden on mobile */}
+              <span className="topbar-user-name">Gabriel A.</span>
+              <ChevronDown
+                size={14}
+                aria-hidden="true"
+                className={[
+                  'topbar-chevron',
+                  userMenuOpen ? 'topbar-chevron--open' : '',
+                ]
+                  .filter(Boolean)
+                  .join(' ')}
+              />
+            </button>
+
+            {/* Dropdown menu */}
+            {userMenuOpen && (
+              <div
+                id="user-menu-dropdown"
+                role="menu"
+                aria-labelledby="user-menu-trigger"
+                className="topbar-dropdown"
+              >
+                {USER_MENU_ITEMS.map((item) => {
+                  const Icon = item.icon
+                  return (
+                    <Link
+                      key={item.href}
+                      href={item.href}
+                      role="menuitem"
+                      onClick={() => setUserMenuOpen(false)}
+                      className={[
+                        'topbar-dropdown-item',
+                        item.destructive ? 'topbar-dropdown-item--destructive' : '',
+                      ]
+                        .filter(Boolean)
+                        .join(' ')}
+                    >
+                      <Icon size={15} aria-hidden="true" />
+                      <span>{item.label}</span>
+                    </Link>
+                  )
+                })}
+              </div>
+            )}
+          </div>
+        </div>
+      </div>
+
+      {/*
+       * CommandPalette portal slot: rendered here so it is inside the
+       * <header> DOM subtree for correct ARIA ownership. In production
+       * this would use Next.js dynamic import for code splitting.
+       * The actual CommandPalette component (D_interaction builder) is
+       * imported here; for this preset it is a placeholder trigger slot.
+       */}
+    </header>
+  )
+}

package/framework/scaffold/saas-dashboard/lib/brand.ts.template

@@ -0,0 +1,324 @@
+/**
+ * lib/brand.ts -- saas-dashboard preset v1.0.0
+ *
+ * WHY THIS FILE EXISTS
+ * --------------------
+ * CSS custom properties are excellent for theming but opaque to TypeScript.
+ * When a Recharts component needs the violet series color, it cannot read
+ * a CSS variable at the component author's type-check time. This module
+ * provides the same values as typed constants so charting libraries,
+ * framer-motion animation objects, and utility functions can consume them
+ * with full IDE autocomplete and compile-time safety.
+ *
+ * CONTRACT: mirror, never diverge
+ * --------------------------------
+ * Every constant here mirrors a CSS custom property in globals.css.
+ * They must always match. If you add a token to globals.css, add it here too.
+ * The authoritative source is globals.css (rendered in the browser);
+ * this file is its TypeScript shadow.
+ *
+ * IMMUTABILITY
+ * ------------
+ * All exports use "as const" to produce literal types. This allows
+ * TypeScript to infer exact string/number values instead of widening
+ * to `string` or `number`, enabling exhaustiveness checks in components.
+ *
+ * USAGE EXAMPLES
+ * --------------
+ *   // Recharts area chart series:
+ *   import { COLORS } from '@/lib/brand'
+ *   <Area stroke={COLORS.viz[0]} fill={COLORS.viz[0]} />
+ *
+ *   // Framer-motion duration:
+ *   import { DURATION, EASING } from '@/lib/brand'
+ *   animate={{ opacity: 1 }}
+ *   transition={{ duration: DURATION.normal / 1000, ease: EASING.out }}
+ *
+ *   // Stagger children:
+ *   import { staggerChildren } from '@/lib/brand'
+ *   const childVariants = staggerChildren(6)  // 6 items, 40ms apart
+ */
+
+/* ================================================================
+   COLOR TOKENS
+   ================================================================ */
+
+/**
+ * Raw neutral scale values.
+ * Components should prefer semantic tokens (SEMANTIC_COLORS) over
+ * these. The raw scale is exported for design tooling and token
+ * documentation generation only.
+ */
+export const NEUTRAL = {
+  0:    '#ffffff',
+  50:   '#f7f8fa',
+  100:  '#eef0f4',
+  200:  '#dde1e9',
+  300:  '#c4cad6',
+  400:  '#9aa3b4',
+  500:  '#6b7689',
+  600:  '#4e5769',
+  700:  '#343d4f',
+  800:  '#1f2635',
+  850:  '#171d2b',
+  900:  '#0f1420',
+  950:  '#080c14',
+  1000: '#000000',
+} as const;
+
+export type NeutralStep = keyof typeof NEUTRAL;
+
+/**
+ * Accent (violet 258deg) values.
+ * Role 1: interactive affordance (buttons, links, active states).
+ * Role 2: brand emphasis (tinted backgrounds, selected rows).
+ */
+export const ACCENT = {
+  base:   '#7c5af8',
+  hover:  '#9070ff',
+  active: '#6644e8',
+  subtle: '#1e1640',
+  muted:  '#4a3490',
+} as const;
+
+/**
+ * Status palette: success, warning, danger, info.
+ * Each status has a full-saturation value (text/icons) and
+ * a subtle value (background tints).
+ */
+export const STATUS = {
+  success:        '#22c55e',
+  successSubtle:  '#052e16',
+  warning:        '#f59e0b',
+  warningSubtle:  '#27200a',
+  danger:         '#ef4444',
+  dangerSubtle:   '#2a0a0a',
+  info:           '#38bdf8',
+  infoSubtle:     '#082030',
+} as const;
+
+/**
+ * Data visualisation series: 6 perceptually-spaced hues.
+ * The array order matters: series[0] is always the primary (violet/accent),
+ * which creates visual brand coherence in charts. Subsequent hues are
+ * ordered to maximise distinguishability at 4px line weight.
+ */
+export const VIZ_SERIES = [
+  '#7c5af8',  // 0: violet  (accent, brand-tied)
+  '#38bdf8',  // 1: sky
+  '#22c55e',  // 2: emerald
+  '#f59e0b',  // 3: amber
+  '#f472b6',  // 4: pink
+  '#fb923c',  // 5: orange
+] as const;
+
+export type VizSeriesIndex = 0 | 1 | 2 | 3 | 4 | 5;
+
+/**
+ * Semantic color map for use in JS contexts.
+ * Keys mirror the CSS custom property names (without the --color- prefix).
+ */
+export const COLORS = {
+  /* Surface layers (dark mode defaults) */
+  bgBase:       NEUTRAL[900],
+  bgRaised:     NEUTRAL[800],
+  bgOverlay:    NEUTRAL[850],
+  bgSunken:     NEUTRAL[950],
+  bgHighlight:  ACCENT.subtle,
+
+  /* Text */
+  textPrimary:   NEUTRAL[50],
+  textSecondary: NEUTRAL[400],
+  textMuted:     NEUTRAL[500],
+  textInverse:   NEUTRAL[950],
+  textAccent:    ACCENT.hover,
+
+  /* Borders */
+  borderDefault:  NEUTRAL[700],
+  borderEmphasis: NEUTRAL[600],
+  borderAccent:   ACCENT.muted,
+
+  /* Status */
+  ...STATUS,
+
+  /* Data viz */
+  viz: VIZ_SERIES,
+
+  /* Focus */
+  focusRing: ACCENT.base,
+} as const;
+
+export type ColorKey = keyof typeof COLORS;
+
+/* ================================================================
+   MOTION TOKENS
+   ================================================================ */
+
+/**
+ * Duration values in MILLISECONDS.
+ * Divide by 1000 when passing to framer-motion (which uses seconds).
+ *
+ * Usage with framer-motion:
+ *   transition={{ duration: DURATION.normal / 1000, ease: EASING.out }}
+ */
+export const DURATION = {
+  instant:  80,
+  fast:     120,
+  normal:   200,
+  medium:   300,
+  slow:     400,
+  layout:   500,
+} as const;
+
+export type DurationKey = keyof typeof DURATION;
+
+/**
+ * Easing curves as cubic-bezier arrays for framer-motion.
+ * Framer-motion accepts [x1, y1, x2, y2] tuples directly.
+ * The string form is also exported for CSS transition declarations.
+ */
+export const EASING = {
+  /** Entering: spring-like deceleration. Use for elements appearing on screen. */
+  out:     [0.16, 1, 0.3, 1]     as [number, number, number, number],
+  /** Leaving: builds momentum. Use for elements leaving the screen. */
+  in:      [0.4, 0, 1, 1]        as [number, number, number, number],
+  /** Toggling: symmetric. Use for accordions, sliders, state flips. */
+  inOut:   [0.4, 0, 0.2, 1]      as [number, number, number, number],
+  /** Delight: slight overshoot. Use for badge appear, success pop. */
+  spring:  [0.34, 1.56, 0.64, 1] as [number, number, number, number],
+  /** Subtle: minimal energy. Use for low-profile hover fades. */
+  subtle:  [0.25, 0, 0, 1]       as [number, number, number, number],
+} as const;
+
+/** CSS string form of easing curves for direct use in style attributes */
+export const EASING_CSS = {
+  out:     'cubic-bezier(0.16, 1, 0.3, 1)',
+  in:      'cubic-bezier(0.4, 0, 1, 1)',
+  inOut:   'cubic-bezier(0.4, 0, 0.2, 1)',
+  spring:  'cubic-bezier(0.34, 1.56, 0.64, 1)',
+  subtle:  'cubic-bezier(0.25, 0, 0, 1)',
+} as const;
+
+export type EasingKey = keyof typeof EASING;
+
+/**
+ * Stagger delay: 40ms between list items.
+ * Below 30ms items appear simultaneous; above 60ms feels mechanical.
+ */
+export const STAGGER_BASE = 40; // milliseconds
+
+/**
+ * Returns a framer-motion staggerChildren configuration for N items.
+ * Delay starts at 0 and increments by STAGGER_BASE for each child.
+ *
+ * Usage:
+ *   const container = {
+ *     animate: staggerChildren(items.length),
+ *   }
+ *   <motion.ul variants={container} animate="animate">
+ *     {items.map((item, i) => (
+ *       <motion.li key={i} variants={itemVariant}>{item}</motion.li>
+ *     ))}
+ *   </motion.ul>
+ */
+export function staggerChildren(count: number) {
+  return {
+    staggerChildren: STAGGER_BASE / 1000,
+    delayChildren: 0,
+  };
+}
+
+/* ================================================================
+   SPACING TOKENS
+   ================================================================ */
+
+/**
+ * Spacing values in pixels, mirroring the --space-* CSS tokens.
+ * Use these in JS contexts: canvas drawing, Recharts margins,
+ * programmatic layout calculations.
+ */
+export const SPACING = {
+  px:  1,
+  0:   0,
+  1:   4,
+  2:   8,
+  3:   12,
+  4:   16,
+  5:   20,
+  6:   24,
+  7:   28,
+  8:   32,
+  9:   36,
+  10:  40,
+  11:  44,
+  12:  48,
+  14:  56,
+  16:  64,
+  20:  80,
+  24:  96,
+  32:  128,
+  40:  160,
+  48:  192,
+  56:  224,
+  64:  256,
+} as const;
+
+export type SpacingStep = keyof typeof SPACING;
+
+/** Semantic spacing aliases */
+export const SPACING_SEMANTIC = {
+  cardPad:      SPACING[6],   // 24px
+  cardGap:      SPACING[5],   // 20px
+  sectionGap:   SPACING[8],   // 32px
+  topbarH:      SPACING[12],  // 48px
+  sidebarW:     240,          // expanded
+  sidebarWCol:  SPACING[16],  // 64px collapsed
+} as const;
+
+/* ================================================================
+   BREAKPOINTS
+   ================================================================ */
+
+/**
+ * Breakpoint values in pixels, mirroring Tailwind v4 defaults
+ * except xl which is overridden to 1200px (75rem).
+ *
+ * Use these in JS contexts: ResizeObserver thresholds,
+ * matchMedia queries, chart responsive adjustments.
+ *
+ * Note: xl is 1200px not 1280px -- see globals.css @theme block.
+ */
+export const BREAKPOINTS = {
+  sm:  640,
+  md:  768,
+  lg:  1024,
+  xl:  1200,  /* overridden from Tailwind default 1280 */
+  '2xl': 1536,
+} as const;
+
+export type BreakpointKey = keyof typeof BREAKPOINTS;
+
+/* ================================================================
+   CHART HELPERS
+   ================================================================ */
+
+/**
+ * Default Recharts chart margins using spacing tokens.
+ * Ensures consistent chart padding across all AreaChart/BarChart instances.
+ */
+export const CHART_MARGINS = {
+  top:    SPACING[2],   // 8px
+  right:  SPACING[3],  // 12px
+  bottom: SPACING[2],   // 8px
+  left:   SPACING[2],   // 8px -- adjusted by formatY label width at runtime
+} as const;
+
+/**
+ * Recharts axis tick style using type and color tokens.
+ * Pass to <XAxis tickStyle={AXIS_TICK_STYLE}> etc.
+ */
+export const AXIS_TICK_STYLE = {
+  fill:     COLORS.textMuted,
+  fontSize: 12,           // matches --type-caption: 0.75rem
+  fontFamily: 'Inter Variable, system-ui, sans-serif',
+} as const;