chati-dev 4.3.0 → 4.4.0

package/framework/scaffold/saas-dashboard/components/primitives/Input.tsx.template

@@ -0,0 +1,310 @@
+/**
+ * components/primitives/Input.tsx -- saas-dashboard preset v1.0.0
+ *
+ * WHY FIELD WRAPS INPUT
+ * ---------------------
+ * A bare <input> has no label, no hint, no error affordance, and no
+ * icon slots. Developers who use bare inputs inevitably re-invent
+ * these around them, producing inconsistent patterns: one uses a
+ * <div> with a floating label, another uses a placeholder, a third
+ * uses a <p> beneath with a class that varies per form.
+ *
+ * The Field primitive is the contract: an accessible input group
+ * that ALWAYS has a real <label> element, MAY have a hint, and
+ * COMMUNICATES errors accessibly (role=alert, aria-invalid).
+ *
+ * PLACEHOLDER RULE (non-negotiable)
+ * ----------------------------------
+ * Placeholder text is NOT a label. It disappears when the user types,
+ * is not read by all screen readers in all modes, and fails WCAG
+ * 1.3.1 (Info and Relationships). The Field primitive structurally
+ * enforces this by requiring the `label` prop and rendering it as a
+ * real <label> element.
+ *
+ * If the visual design calls for a label-free input (search box in
+ * a toolbar), pass `labelHidden` to visually hide the label while
+ * keeping it in the DOM for screen readers.
+ *
+ * STATE MODEL
+ * -----------
+ *   resting:  border-default background
+ *   focus:    border-emphasis + shadow-focus ring (2px, 2px offset)
+ *   error:    border-danger + error message with role=alert
+ *   disabled: opacity-50 + cursor-not-allowed on the input
+ *   (focus-visible ring is also applied via globals.css :focus-visible
+ *    on the input element itself for keyboard navigation)
+ *
+ * ICON SLOTS
+ * ----------
+ * Icons are absolutely positioned inside a relative wrapper.
+ * The input's padding-left/padding-right is extended via CSS
+ * custom property --input-pl when iconLeft is present (36px).
+ * This avoids the icon overlapping text on very short inputs.
+ *
+ * TRANSITION RULES
+ * ----------------
+ * Border colour change on focus: --duration-normal, --ease-in-out.
+ * Only `border-color` and `box-shadow` are transitioned.
+ * Never transition `padding`, `width`, or `height`.
+ *
+ * TEXTAREA AND SELECT VARIANTS
+ * ----------------------------
+ * The `as` prop renders a <textarea> or <select> instead of <input>.
+ * Both variants share the same visual treatment as the text input.
+ * Textarea has a min-height and resizes vertically only (resize:vertical).
+ */
+
+import {
+  type InputHTMLAttributes,
+  type TextareaHTMLAttributes,
+  type SelectHTMLAttributes,
+  type ReactNode,
+  forwardRef,
+  useId,
+} from 'react';
+
+/* ----------------------------------------------------------------
+   FIELD
+   ---------------------------------------------------------------- */
+
+export interface FieldProps {
+  /** REQUIRED: always rendered as <label>, never omitted */
+  label: string;
+  /** Hint text below input, linked via aria-describedby */
+  hint?: string;
+  /** Error message: overrides hint, sets aria-invalid on input */
+  error?: string;
+  /** Visually hides label but keeps it for screen readers */
+  labelHidden?: boolean;
+  /** Lucide icon inside input, left side */
+  iconLeft?: ReactNode;
+  /** Lucide icon or button inside input, right side */
+  iconRight?: ReactNode;
+  /** Adds asterisk to label and aria-required to input */
+  required?: boolean;
+  /** Input element type; textarea renders a <textarea> */
+  as?: 'input' | 'textarea' | 'select';
+  /** Passed to the underlying input element */
+  inputProps?: InputHTMLAttributes<HTMLInputElement> &
+    TextareaHTMLAttributes<HTMLTextAreaElement> &
+    SelectHTMLAttributes<HTMLSelectElement>;
+  /** Child elements for <select> variant (options) */
+  children?: ReactNode;
+  /** Additional class on the root Field wrapper */
+  className?: string;
+}
+
+export function Field({
+  label,
+  hint,
+  error,
+  labelHidden = false,
+  iconLeft,
+  iconRight,
+  required = false,
+  as: InputAs = 'input',
+  inputProps,
+  children,
+  className,
+}: FieldProps) {
+  const id = useId();
+  const hintId = `${id}-hint`;
+  const errorId = `${id}-error`;
+  const hasError = Boolean(error);
+  const descBy = [hint ? hintId : '', hasError ? errorId : '']
+    .filter(Boolean)
+    .join(' ') || undefined;
+
+  /* ---- shared input classes ---- */
+  const inputClasses = [
+    'w-full rounded-[var(--input-radius)]',
+    'bg-[var(--color-bg-sunken)]',
+    'text-[var(--type-body)] text-[var(--color-text-primary)]',
+    'placeholder:text-[var(--color-text-muted)]',
+    'border border-[var(--color-border-default)]',
+    'py-[var(--spacing-input-pad-v)]',
+    /* Horizontal padding adjusts based on icon presence */
+    iconLeft
+      ? 'pl-10 pr-[var(--spacing-input-pad-h)]'
+      : iconRight
+      ? 'pl-[var(--spacing-input-pad-h)] pr-10'
+      : 'px-[var(--spacing-input-pad-h)]',
+    /* Transitions: only border-color and box-shadow */
+    'transition-[border-color,box-shadow]',
+    '[transition-duration:var(--duration-normal)]',
+    '[transition-timing-function:var(--ease-in-out)]',
+    /* Focus state */
+    'focus:outline-none',
+    'focus:border-[var(--color-border-emphasis)]',
+    'focus:shadow-[var(--shadow-focus)]',
+    /* Error state */
+    hasError
+      ? 'border-[var(--color-danger)] focus:border-[var(--color-danger)]'
+      : '',
+    /* Disabled state */
+    'disabled:opacity-50 disabled:cursor-not-allowed',
+    /* Textarea specific */
+    InputAs === 'textarea'
+      ? 'resize-vertical min-h-[var(--space-32)] leading-[var(--type-body-lh)]'
+      : 'h-[var(--input-h)]',
+    /* Select specific */
+    InputAs === 'select' ? 'cursor-pointer appearance-none' : '',
+  ]
+    .filter(Boolean)
+    .join(' ');
+
+  return (
+    <div className={['flex flex-col gap-[var(--space-2)]', className].filter(Boolean).join(' ')}>
+      {/* Label -- always present in DOM, never replaced by placeholder */}
+      <label
+        htmlFor={id}
+        className={[
+          'text-[var(--type-small)] font-[var(--font-weight-medium)]',
+          'text-[var(--color-text-primary)]',
+          'leading-[var(--type-small-lh)]',
+          labelHidden ? 'sr-only' : '',
+        ]
+          .filter(Boolean)
+          .join(' ')}
+      >
+        {label}
+        {required && (
+          <span
+            aria-hidden="true"
+            className="ml-[var(--space-1)] text-[var(--color-danger)]"
+          >
+            *
+          </span>
+        )}
+      </label>
+
+      {/* Input wrapper: relative for icon absolute positioning */}
+      <div className="relative">
+        {iconLeft && (
+          <span
+            aria-hidden="true"
+            className={[
+              'absolute left-[var(--space-3)] top-1/2 -translate-y-1/2',
+              'text-[var(--color-text-muted)] pointer-events-none',
+              'flex items-center justify-center w-4 h-4',
+            ].join(' ')}
+          >
+            {iconLeft}
+          </span>
+        )}
+
+        {InputAs === 'textarea' ? (
+          <textarea
+            id={id}
+            aria-invalid={hasError || undefined}
+            aria-describedby={descBy}
+            aria-required={required || undefined}
+            className={inputClasses}
+            {...(inputProps as TextareaHTMLAttributes<HTMLTextAreaElement>)}
+          />
+        ) : InputAs === 'select' ? (
+          <select
+            id={id}
+            aria-invalid={hasError || undefined}
+            aria-describedby={descBy}
+            aria-required={required || undefined}
+            className={inputClasses}
+            {...(inputProps as SelectHTMLAttributes<HTMLSelectElement>)}
+          >
+            {children}
+          </select>
+        ) : (
+          <input
+            id={id}
+            aria-invalid={hasError || undefined}
+            aria-describedby={descBy}
+            aria-required={required || undefined}
+            className={inputClasses}
+            {...(inputProps as InputHTMLAttributes<HTMLInputElement>)}
+          />
+        )}
+
+        {iconRight && (
+          <span
+            aria-hidden="true"
+            className={[
+              'absolute right-[var(--space-3)] top-1/2 -translate-y-1/2',
+              'text-[var(--color-text-muted)]',
+              'flex items-center justify-center w-4 h-4',
+            ].join(' ')}
+          >
+            {iconRight}
+          </span>
+        )}
+      </div>
+
+      {/* Error message: role=alert ensures SR announces immediately */}
+      {hasError && (
+        <p
+          id={errorId}
+          role="alert"
+          className={[
+            'text-[var(--type-caption)] leading-[var(--type-caption-lh)]',
+            'text-[var(--color-danger)]',
+          ].join(' ')}
+        >
+          {error}
+        </p>
+      )}
+
+      {/* Hint text: only shown when no error (error takes priority) */}
+      {hint && !hasError && (
+        <p
+          id={hintId}
+          className={[
+            'text-[var(--type-caption)] leading-[var(--type-caption-lh)]',
+            'text-[var(--color-text-muted)]',
+          ].join(' ')}
+        >
+          {hint}
+        </p>
+      )}
+    </div>
+  );
+}
+
+/* ----------------------------------------------------------------
+   INPUT (bare, for use outside Field context when Field is overkill)
+   Forwards a ref for form library integration (react-hook-form).
+   ---------------------------------------------------------------- */
+
+export interface InputProps extends InputHTMLAttributes<HTMLInputElement> {
+  /** Applies error styling without full Field wrapper */
+  hasError?: boolean;
+}
+
+export const Input = forwardRef<HTMLInputElement, InputProps>(
+  ({ hasError, className, ...rest }, ref) => (
+    <input
+      ref={ref}
+      aria-invalid={hasError || undefined}
+      className={[
+        'w-full h-[var(--input-h)] rounded-[var(--input-radius)]',
+        'bg-[var(--color-bg-sunken)]',
+        'text-[var(--type-body)] text-[var(--color-text-primary)]',
+        'placeholder:text-[var(--color-text-muted)]',
+        'border border-[var(--color-border-default)]',
+        'px-[var(--spacing-input-pad-h)]',
+        'transition-[border-color,box-shadow]',
+        '[transition-duration:var(--duration-normal)]',
+        '[transition-timing-function:var(--ease-in-out)]',
+        'focus:outline-none',
+        'focus:border-[var(--color-border-emphasis)]',
+        'focus:shadow-[var(--shadow-focus)]',
+        hasError ? 'border-[var(--color-danger)]' : '',
+        'disabled:opacity-50 disabled:cursor-not-allowed',
+        className,
+      ]
+        .filter(Boolean)
+        .join(' ')}
+      {...rest}
+    />
+  ),
+);
+
+Input.displayName = 'Input';

package/framework/scaffold/saas-dashboard/components/primitives/Spinner.tsx.template

@@ -0,0 +1,135 @@
+import React from 'react';
+/**
+ * components/primitives/Spinner.tsx -- saas-dashboard preset v1.0.0
+ *
+ * WHY SVG AND NOT A BORDER-BASED SPINNER
+ * ---------------------------------------
+ * CSS border-based spinners (border-t-transparent trick) are common but
+ * have two problems in a design-system context:
+ *   1. They rely on a border on the element itself, which conflicts with
+ *      Button's own border (secondary/destructive variants).
+ *   2. They cannot easily inherit the parent's text color at different
+ *      opacities for the track vs. indicator.
+ *
+ * An SVG circle with stroke-dasharray/stroke-dashoffset animation:
+ *   - Is fully isolated from the surrounding layout
+ *   - Inherits currentColor for both track and indicator (different opacities)
+ *   - Renders at exactly the declared size (no border-box inconsistencies)
+ *   - Is composable: Spinner renders inline, needs no wrapper
+ *
+ * REDUCED MOTION
+ * --------------
+ * When prefers-reduced-motion is active, the rotating animation is
+ * replaced with a gentle opacity pulse. This preserves the loading
+ * feedback without vestibular-triggering rotation.
+ * The globals.css @media block collapses animation-duration to 0.01ms
+ * which effectively freezes the spinner. We supplement with a CSS
+ * class that triggers the static pulse fallback.
+ *
+ * SIZE SYSTEM
+ * -----------
+ * sm:  16px -- inside sm/md Button, inline with body text
+ * md:  20px -- inside lg Button, standalone inline indicators
+ * lg:  32px -- full-page Suspense boundaries, large empty states
+ *
+ * COLOR
+ * -----
+ * The spinner inherits currentColor from its parent. Inside a
+ * primary Button (white text) it renders white. Inside a secondary
+ * Button (text-primary) it renders text-primary. No explicit color
+ * prop needed; the variant system handles this via text color.
+ */
+
+const SIZES: Record<string, number> = {
+  sm: 16,
+  md: 20,
+  lg: 32,
+};
+
+const STROKE_WIDTH: Record<string, number> = {
+  sm: 2,
+  md: 2,
+  lg: 2.5,
+};
+
+export interface SpinnerProps {
+  /** Visual size */
+  size?: 'sm' | 'md' | 'lg';
+  /** Additional class names */
+  className?: string;
+  /** Aria label for standalone loading indicators */
+  'aria-label'?: string;
+  /** Explicitly suppress aria for decorative usage inside Button */
+  'aria-hidden'?: boolean | 'true' | 'false';
+}
+
+export function Spinner({
+  size = 'md',
+  className,
+  'aria-label': ariaLabel,
+  'aria-hidden': ariaHidden,
+}: SpinnerProps) {
+  const px = SIZES[size] ?? SIZES.md;
+  const stroke = STROKE_WIDTH[size] ?? 2;
+  const r = (px - stroke * 2) / 2;
+  const circumference = 2 * Math.PI * r;
+  /* Show ~25% of circumference as the visible arc */
+  const dasharray = `${circumference * 0.25} ${circumference * 0.75}`;
+
+  return (
+    <svg
+      width={px}
+      height={px}
+      viewBox={`0 0 ${px} ${px}`}
+      fill="none"
+      aria-hidden={ariaHidden}
+      aria-label={ariaLabel}
+      role={ariaLabel ? 'status' : undefined}
+      className={['shrink-0', 'spinner-svg', className].filter(Boolean).join(' ')}
+      style={
+        {
+          /* Rotation animation: composited on GPU (transform only) */
+          animation:
+            'spinner-rotate 0.75s linear infinite',
+        } as React.CSSProperties
+      }
+    >
+      <style>{`
+        @keyframes spinner-rotate {
+          from { transform: rotate(0deg); transform-origin: center; }
+          to   { transform: rotate(360deg); transform-origin: center; }
+        }
+        @keyframes spinner-pulse {
+          0%, 100% { opacity: 1; }
+          50% { opacity: 0.3; }
+        }
+        @media (prefers-reduced-motion: reduce) {
+          .spinner-svg { animation: spinner-pulse 1.4s ease-in-out infinite !important; }
+        }
+      `}</style>
+
+      {/* Track: full circle at low opacity for visual context */}
+      <circle
+        cx={px / 2}
+        cy={px / 2}
+        r={r}
+        stroke="currentColor"
+        strokeWidth={stroke}
+        opacity={0.15}
+      />
+
+      {/* Indicator: 25% arc, full opacity */}
+      <circle
+        cx={px / 2}
+        cy={px / 2}
+        r={r}
+        stroke="currentColor"
+        strokeWidth={stroke}
+        strokeDasharray={dasharray}
+        strokeLinecap="round"
+        opacity={0.9}
+      />
+    </svg>
+  );
+}
+

package/framework/scaffold/saas-dashboard/components/primitives/index.ts.template

@@ -0,0 +1,60 @@
+/**
+ * components/primitives/index.ts -- saas-dashboard preset v1.0.0
+ *
+ * WHY A BARREL EXPORT
+ * --------------------
+ * Without a barrel, consumers must know the exact file path for each
+ * primitive, leading to divergence:
+ *   import { Button } from '@/components/primitives/Button'
+ *   import { Card } from '@/components/primitives/card'       // different casing
+ *   import { Badge } from '../../primitives/Badge'            // relative path
+ *
+ * The barrel enforces a single import path:
+ *   import { Button, Card, CardHeader, Field, Badge } from '@/components/primitives'
+ *
+ * This means:
+ *   1. Renaming a primitive file only requires updating this file.
+ *   2. IDE autocomplete surfaces all available primitives from one location.
+ *   3. Tree-shaking works correctly -- unused primitives are eliminated.
+ *
+ * WHAT BELONGS HERE
+ * -----------------
+ * Only true primitives: components with no dependencies on other local
+ * components (only design tokens and external packages).
+ * Composite components (DataTable, StatCard, CommandPalette) have their
+ * own barrel exports in their respective directories.
+ */
+
+/* Button + types */
+export { Button } from './Button';
+export type { ButtonProps } from './Button';
+
+/* Card compound component + all sub-component types */
+export {
+  Card,
+  CardHeader,
+  CardTitle,
+  CardDescription,
+  CardContent,
+  CardFooter,
+} from './Card';
+export type {
+  CardProps,
+  CardHeaderProps,
+  CardTitleProps,
+  CardDescriptionProps,
+  CardContentProps,
+  CardFooterProps,
+} from './Card';
+
+/* Input + Field + types */
+export { Input, Field } from './Input';
+export type { InputProps, FieldProps } from './Input';
+
+/* Badge + types */
+export { Badge } from './Badge';
+export type { BadgeProps } from './Badge';
+
+/* Spinner + types */
+export { Spinner } from './Spinner';
+export type { SpinnerProps } from './Spinner';

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

@@ -0,0 +1,174 @@
+/*
+ * AppShell.tsx -- Application Shell Composition
+ * ============================================================
+ * WHY THIS FILE EXISTS
+ * --------------------
+ * The app shell is the outermost spatial container for every
+ * authenticated page. It establishes the two-dimensional layout
+ * that all page content lives within:
+ *
+ *   [sidebar column | main column]
+ *    Sidebar           Topbar (sticky)
+ *                      <main> (scrolls)
+ *                        Container
+ *                          {children}
+ *
+ * LAYOUT APPROACH: CSS GRID + CSS VARIABLE COLUMN WIDTH
+ * ------------------------------------------------------
+ * We use CSS Grid with a single-row, two-column layout. The
+ * sidebar column width is driven by a CSS custom property
+ * (--shell-sidebar-w) that is updated by SidebarContext when
+ * the user collapses or expands. This means:
+ *
+ *   - The grid reacts to state changes without any JavaScript
+ *     calculating pixel positions.
+ *   - The transition is applied to grid-template-columns via a
+ *     CSS transition. Modern browsers animate this correctly
+ *     when the value is a length.
+ *   - No absolute positioning or transform-based sliding is
+ *     needed on the sidebar element itself for desktop layout.
+ *
+ * RESPONSIVE BEHAVIOR
+ * -------------------
+ * Three breakpoint tiers:
+ *
+ *   Mobile (<768px):
+ *     - Grid collapses to a single column (sidebar column = 0).
+ *     - Sidebar is removed from flow (position: fixed, off-screen
+ *       via translateX(-100%)).
+ *     - A backdrop overlay appears when isMobileOpen is true.
+ *     - The Topbar's hamburger button calls openMobile().
+ *
+ *   Tablet (768px-1023px):
+ *     - Grid sidebar column exists but defaults to collapsed
+ *       width (64px). User can expand.
+ *
+ *   Desktop (>=1024px):
+ *     - Full sidebar visible; collapse is optional.
+ *
+ * FOCUS MANAGEMENT ON ROUTE CHANGE
+ * ----------------------------------
+ * When Next.js navigates to a new route, focus is moved to the
+ * <main> element via a ref. This ensures screen reader users
+ * hear the new page content without manually navigating there.
+ * The main element receives tabIndex={-1} so it can be focused
+ * programmatically without appearing in the natural tab order.
+ *
+ * Z-INDEX SCALE (defined in globals.css)
+ * ---------------------------------------
+ * --z-sidebar:  30  (desktop: in normal flow; mobile: fixed overlay)
+ * --z-topbar:   40
+ * --z-dropdown: 50
+ * --z-tooltip:  60
+ * --z-modal:    70
+ * --z-toast:    80
+ * --z-command:  90
+ *
+ * PERFORMANCE
+ * -----------
+ * We animate only the CSS custom property change that drives
+ * grid-template-columns width. No width, height, or position
+ * properties are transitioned on individual elements.
+ */
+
+'use client'
+
+import React, { useRef, useEffect, useCallback } from 'react'
+import { usePathname } from 'next/navigation'
+import { useSidebar } from './SidebarContext'
+import { Sidebar } from './Sidebar'
+import { Topbar } from './Topbar'
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+interface AppShellProps {
+  children: React.ReactNode
+}
+
+// ---------------------------------------------------------------------------
+// Component
+// ---------------------------------------------------------------------------
+
+export function AppShell({ children }: AppShellProps) {
+  const { isCollapsed, isMobileOpen, closeMobile } = useSidebar()
+  const mainRef = useRef<HTMLElement>(null)
+  const pathname = usePathname()
+
+  // Focus management: when the route changes, move focus to <main>.
+  // This is a11y-critical for keyboard and screen reader navigation.
+  useEffect(() => {
+    mainRef.current?.focus({ preventScroll: true })
+  }, [pathname])
+
+  // Close mobile drawer when Escape is pressed.
+  const handleKeyDown = useCallback(
+    (e: React.KeyboardEvent) => {
+      if (e.key === 'Escape' && isMobileOpen) {
+        closeMobile()
+      }
+    },
+    [isMobileOpen, closeMobile]
+  )
+
+  return (
+    /*
+     * The shell-root div uses CSS custom properties to drive the
+     * grid column width. The inline style sets the --shell-sidebar-w
+     * variable so the CSS transition in globals.css picks it up.
+     * Using an inline style for a single token change is intentional:
+     * it avoids className string manipulation while keeping the
+     * transition on the CSS side (not JS-driven).
+     */
+    <div
+      className="shell-root"
+      style={{
+        // This CSS variable feeds grid-template-columns in globals.css.
+        // The transition is declared on the .shell-root rule there.
+        '--shell-sidebar-w': isCollapsed
+          ? 'var(--spacing-sidebar-w-col)'
+          : 'var(--spacing-sidebar-w)',
+      } as React.CSSProperties}
+      onKeyDown={handleKeyDown}
+    >
+      {/*
+       * Mobile backdrop overlay. Visible only when isMobileOpen.
+       * Clicking it closes the drawer. It sits below the sidebar
+       * (z-index 29) so it does not intercept sidebar interactions.
+       * The backdrop uses opacity transition (not visibility) so
+       * reduced-motion users still see it fade correctly (opacity
+       * transitions at 80ms are preserved under reduced-motion).
+       */}
+      {isMobileOpen && (
+        <div
+          className="shell-backdrop"
+          aria-hidden="true"
+          onClick={closeMobile}
+        />
+      )}
+
+      {/* Sidebar: fixed on mobile, in-flow grid column on desktop */}
+      <Sidebar />
+
+      {/*
+       * Main column: contains the sticky Topbar and the scrollable
+       * page content. overflow-y: auto here (not on <body>) so the
+       * sidebar never scrolls with the page content.
+       */}
+      <div className="shell-main">
+        <Topbar />
+        <main
+          ref={mainRef}
+          id="main-content"
+          // tabIndex={-1} allows programmatic focus (route change)
+          // without placing <main> in the natural tab order.
+          tabIndex={-1}
+          className="shell-content"
+        >
+          {children}
+        </main>
+      </div>
+    </div>
+  )
+}