chati-dev 4.3.0 → 4.4.0

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

@@ -0,0 +1,186 @@
+/*
+ * Breadcrumb.tsx -- Breadcrumb Navigation
+ * ============================================================
+ * WHY THIS FILE EXISTS
+ * --------------------
+ * The breadcrumb provides orientation within the application
+ * hierarchy. It answers the question "where am I?" for both
+ * sighted users and screen reader users, and provides one-click
+ * navigation to parent routes.
+ *
+ * DERIVATION FROM PATHNAME
+ * ------------------------
+ * Crumbs are derived from Next.js usePathname() by splitting
+ * the path segments and capitalizing them. This is a reasonable
+ * default for a preset; real applications would provide a route
+ * label map (e.g., '/customers/acme-corp' -> 'Acme Corp') for
+ * human-readable crumb labels.
+ *
+ * A static routeLabels map is provided for the preset's known
+ * routes. Unmapped segments fall back to title-cased segment.
+ *
+ * TRUNCATION
+ * ----------
+ * Long paths are truncated in the middle on narrow viewports.
+ * Only the first and last crumbs are always shown; middle crumbs
+ * are replaced by an ellipsis on viewports < 480px. This is done
+ * via CSS (the middle <li> elements receive a responsive display
+ * class) so no JavaScript is involved in the truncation logic.
+ *
+ * ACCESSIBILITY
+ * -------------
+ * - Wrapped in <nav aria-label="Breadcrumb"> (navigation landmark)
+ * - Ordered list <ol> communicates the hierarchy to SR
+ * - Separators are aria-hidden spans (not bullet characters)
+ * - Current page item has aria-current="page" and no link
+ * - The home crumb has a distinct aria-label ("Home")
+ *
+ * SEPARATOR CHOICE
+ * ----------------
+ * We use a forward slash (/) as the separator, styled as a
+ * muted text-muted span. This is preferable to CSS-generated
+ * content (::before) because it is predictably positioned
+ * within the flex row without z-index or overflow concerns.
+ */
+
+'use client'
+
+import Link from 'next/link'
+import { usePathname } from 'next/navigation'
+import { useMemo } from 'react'
+
+// ---------------------------------------------------------------------------
+// Route label map
+// ---------------------------------------------------------------------------
+// Maps path segments to human-readable labels for the preset's known routes.
+// Add entries here for any route whose segment slug is not human-readable.
+const ROUTE_LABELS: Record<string, string> = {
+  dashboard: 'Dashboard',
+  analytics: 'Analytics',
+  customers: 'Customers',
+  documents: 'Documents',
+  billing: 'Billing',
+  notifications: 'Notifications',
+  settings: 'Settings',
+  help: 'Help & Docs',
+  profile: 'Profile',
+}
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+interface CrumbItem {
+  label: string
+  href: string
+  isCurrent: boolean
+}
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+function segmentToLabel(segment: string): string {
+  if (ROUTE_LABELS[segment]) return ROUTE_LABELS[segment]
+  // Title-case the segment, replacing hyphens with spaces.
+  return segment
+    .replace(/-/g, ' ')
+    .replace(/\b\w/g, (c) => c.toUpperCase())
+}
+
+function buildCrumbs(pathname: string): CrumbItem[] {
+  const segments = pathname.split('/').filter(Boolean)
+
+  if (segments.length === 0) {
+    return [{ label: 'Home', href: '/', isCurrent: true }]
+  }
+
+  const crumbs: CrumbItem[] = []
+  let cumulativePath = ''
+
+  segments.forEach((segment, index) => {
+    cumulativePath += '/' + segment
+    crumbs.push({
+      label: segmentToLabel(segment),
+      href: cumulativePath,
+      isCurrent: index === segments.length - 1,
+    })
+  })
+
+  return crumbs
+}
+
+// ---------------------------------------------------------------------------
+// Component
+// ---------------------------------------------------------------------------
+
+export function Breadcrumb() {
+  const pathname = usePathname()
+
+  const crumbs = useMemo(() => buildCrumbs(pathname), [pathname])
+
+  // Single crumb (root): show nothing or just the page title.
+  // Breadcrumbs only provide value when there is more than one level.
+  if (crumbs.length <= 1) {
+    return (
+      <nav aria-label="Breadcrumb" className="breadcrumb">
+        <ol role="list" className="breadcrumb-list">
+          <li className="breadcrumb-item breadcrumb-item--current">
+            <span aria-current="page" className="breadcrumb-current">
+              {crumbs[0]?.label ?? 'Dashboard'}
+            </span>
+          </li>
+        </ol>
+      </nav>
+    )
+  }
+
+  return (
+    <nav aria-label="Breadcrumb" className="breadcrumb">
+      <ol role="list" className="breadcrumb-list">
+        {crumbs.map((crumb, index) => {
+          const isFirst = index === 0
+          const isLast = crumb.isCurrent
+          // Middle crumbs (not first, not last) are hidden on very narrow viewports.
+          const isMiddle = !isFirst && !isLast
+
+          return (
+            <li
+              key={crumb.href}
+              className={[
+                'breadcrumb-item',
+                isMiddle ? 'breadcrumb-item--middle' : '',
+                isLast ? 'breadcrumb-item--current' : '',
+              ]
+                .filter(Boolean)
+                .join(' ')}
+            >
+              {/* Separator before every item except the first */}
+              {!isFirst && (
+                <span
+                  className="breadcrumb-separator"
+                  aria-hidden="true"
+                >
+                  /
+                </span>
+              )}
+
+              {isLast ? (
+                <span
+                  aria-current="page"
+                  className="breadcrumb-current"
+                >
+                  {crumb.label}
+                </span>
+              ) : (
+                <Link href={crumb.href} className="breadcrumb-link">
+                  {crumb.label}
+                </Link>
+              )}
+            </li>
+          )
+        })}
+      </ol>
+    </nav>
+  )
+}

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

@@ -0,0 +1,86 @@
+/*
+ * Container.tsx -- Page Content Width Authority
+ * ============================================================
+ * WHY THIS FILE EXISTS
+ * --------------------
+ * The Container component is the SOLE authority for two
+ * layout concerns that must be consistent across every page:
+ *
+ *   1. Max-width: 1280px. This keeps content readable on wide
+ *      monitors without requiring the user to pan left-right.
+ *      1280px is chosen because, at the typical dashboard
+ *      sidebar-expanded width (240px), the content area is
+ *      1040px -- a comfortable width for a two-column data
+ *      layout without feeling too spacious.
+ *
+ *   2. Horizontal padding: --spacing-page-edge
+ *      (clamp(1.5rem, 4vw, 2.5rem) = 24px to 40px).
+ *      Fluid padding scales with viewport so narrow viewports
+ *      get a compact 24px margin and wide viewports get a
+ *      comfortable 40px. The asymmetric widening at large sizes
+ *      gives the content breathing room without a hard jump.
+ *
+ * WHAT CONTAINER DOES NOT DO
+ * --------------------------
+ * - It does not set vertical spacing (callers use className).
+ * - It does not impose a grid or flex layout on its children.
+ * - It does not know about the sidebar or topbar.
+ *
+ * USAGE PATTERN
+ * -------------
+ * Every page should wrap its primary content in a Container.
+ * The AppShell's <main> element intentionally has no padding
+ * of its own: Container applies it. This separation means
+ * full-bleed sections (hero images, full-width tables) can be
+ * placed outside Container and still sit within <main>.
+ *
+ * Example:
+ *   <main className="shell-content">
+ *     <Container className="py-8">
+ *       <StatCardGrid>...</StatCardGrid>
+ *       <AreaChart ... />
+ *     </Container>
+ *   </main>
+ */
+
+import React, { type HTMLAttributes, forwardRef } from 'react'
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+export interface ContainerProps extends HTMLAttributes<HTMLDivElement> {
+  /**
+   * Additional class names for vertical spacing and other
+   * layout overrides. Horizontal padding and max-width are
+   * managed internally and cannot be overridden via className.
+   */
+  className?: string
+  children: React.ReactNode
+  /**
+   * Render as a different HTML element. Useful for <section>
+   * or <article> when semantic correctness is needed.
+   * Defaults to 'div'.
+   */
+  as?: 'div' | 'section' | 'article'
+}
+
+// ---------------------------------------------------------------------------
+// Component
+// ---------------------------------------------------------------------------
+
+export const Container = forwardRef<HTMLDivElement, ContainerProps>(
+  function Container({ className, children, as: Tag = 'div', ...rest }, ref) {
+    return (
+      <Tag
+        ref={ref as React.Ref<HTMLDivElement>}
+        className={['container', className].filter(Boolean).join(' ')}
+        {...rest}
+      >
+        {children}
+      </Tag>
+    )
+  }
+)
+
+Container.displayName = 'Container'

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

@@ -0,0 +1,147 @@
+/*
+ * NavItem.tsx -- Sidebar Navigation Item
+ * ============================================================
+ * WHY THIS FILE EXISTS
+ * --------------------
+ * The sidebar NavItem is the atomic interactive unit within
+ * the navigation. It is extracted from Sidebar.tsx into its
+ * own file for two reasons:
+ *
+ *   1. Testability: isolated props make the component trivially
+ *      unit-testable without mounting the entire Sidebar.
+ *
+ *   2. Reuse: the same item pattern (icon + label + badge +
+ *      active state) could appear in a mobile bottom nav or a
+ *      settings sidebar, both of which would import NavItem.
+ *
+ * ACTIVE STATE
+ * ------------
+ * The active state is communicated in three ways:
+ *   - Visually: bg-highlight background + text-accent color +
+ *     3px accent-colored left border.
+ *   - Semantically: aria-current="page" on the link element.
+ *   - Structurally: the CSS class sidebar-nav-item--active.
+ *
+ * COLLAPSE BEHAVIOR
+ * -----------------
+ * When isCollapsed is true:
+ *   - The label text span opacity transitions to 0 and
+ *     max-width transitions to 0 (see note in Sidebar.tsx about
+ *     this max-width exception).
+ *   - A browser-native tooltip (title attribute) provides the
+ *     label on hover for mouse users.
+ *   - A sr-only span is present for keyboard/SR users.
+ *   - Badges collapse to a dot indicator (no number shown).
+ *
+ * MOTION
+ * ------
+ * We use framer-motion's `layout` prop on the container to
+ * animate the width change smoothly when the sidebar
+ * transitions between collapsed and expanded. The label uses
+ * an AnimatePresence for opacity-based exit/enter.
+ *
+ * FOCUS RING
+ * ----------
+ * The global :focus-visible rule in globals.css provides the
+ * focus ring. NavItem does not add its own outline; it relies
+ * on the global rule so focus rings are consistent across all
+ * interactive elements.
+ */
+
+import Link from 'next/link'
+import { type LucideIcon } from 'lucide-react'
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+export interface NavItemProps {
+  /** Navigation target */
+  href: string
+  /** Human-readable label; shown when expanded, sr-only when collapsed */
+  label: string
+  /** Lucide icon component */
+  icon: LucideIcon
+  /** Unread count badge; shows as dot when sidebar is collapsed */
+  badge?: number
+  /** Whether this item matches the current route */
+  isActive?: boolean
+  /** Whether the sidebar is in icon-only mode */
+  isCollapsed?: boolean
+  /** Called when the item is clicked (for closing mobile drawer) */
+  onClick?: () => void
+}
+
+// ---------------------------------------------------------------------------
+// Component
+// ---------------------------------------------------------------------------
+
+export function NavItem({
+  href,
+  label,
+  icon: Icon,
+  badge,
+  isActive = false,
+  isCollapsed = false,
+  onClick,
+}: NavItemProps) {
+  return (
+    <Link
+      href={href}
+      onClick={onClick}
+      aria-current={isActive ? 'page' : undefined}
+      title={isCollapsed ? label : undefined}
+      className={[
+        'sidebar-nav-item',
+        isActive ? 'sidebar-nav-item--active' : '',
+      ]
+        .filter(Boolean)
+        .join(' ')}
+    >
+      {/* Icon: always visible, always decorative (label provides the name) */}
+      <span className="sidebar-nav-icon" aria-hidden="true">
+        <Icon size={18} strokeWidth={1.75} />
+      </span>
+
+      {/*
+       * Label: visible text when expanded.
+       * aria-hidden when collapsed because the title attribute
+       * and the sr-only span provide the accessible name.
+       */}
+      <span
+        className={[
+          'sidebar-nav-label',
+          isCollapsed ? 'sidebar-nav-label--hidden' : '',
+        ]
+          .filter(Boolean)
+          .join(' ')}
+        aria-hidden={isCollapsed}
+      >
+        {label}
+      </span>
+
+      {/* Always-readable SR label (collapsed state only) */}
+      {isCollapsed && <span className="sr-only">{label}</span>}
+
+      {/* Badge: numeric count when expanded, dot when collapsed */}
+      {badge !== undefined && (
+        <>
+          {!isCollapsed && (
+            <span
+              className="sidebar-nav-badge"
+              aria-label={`${badge} unread`}
+            >
+              {badge > 99 ? '99+' : badge}
+            </span>
+          )}
+          {isCollapsed && (
+            <span
+              className="sidebar-nav-badge-dot"
+              aria-hidden="true"
+            />
+          )}
+        </>
+      )}
+    </Link>
+  )
+}