chati-dev 4.3.0 → 4.4.0

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

@@ -0,0 +1,261 @@
+/**
+ * components/primitives/Button.tsx -- saas-dashboard preset v1.0.0
+ *
+ * WHY THIS IS A PRIMITIVE
+ * -----------------------
+ * Every interactive affordance in the UI eventually traces back to a
+ * button: form submission, navigation, dialog open, action trigger.
+ * If each feature builds its own button-shaped element, subtle
+ * inconsistencies accumulate: slightly different padding here, missing
+ * active state there, focus ring forgotten on a ghost variant.
+ *
+ * The Button primitive is the shared language. All interactive affordances
+ * that are not links inside prose use this component. Features that need
+ * a custom shape (icon-only circular button) extend this via the 'icon'
+ * size variant.
+ *
+ * STATE MODEL
+ * -----------
+ * Every variant has exactly 5 states:
+ *   resting:  default appearance
+ *   hover:    one perceptible property change (background, border, or shadow)
+ *   active:   scale(0.97) + slightly darker background -- physical press feel
+ *   disabled: opacity-50 + pointer-events:none + aria-disabled
+ *   loading:  spinner replaces iconLeft, text persists, min-width locked
+ *   (focus is handled globally via :focus-visible in globals.css)
+ *
+ * TRANSITION RULES (enforced here, no exceptions)
+ * ------------------------------------------------
+ *   - Never use `transition-all` or `transition: all`.
+ *   - Each transition names exactly the property being transitioned.
+ *   - Duration tokens from --duration-*; easing from --ease-*.
+ *   - Active scale: --duration-instant (80ms) --ease-spring for tactile feel.
+ *   - Background/color changes: --duration-normal (200ms) --ease-in-out.
+ *
+ * VARIANT PHILOSOPHY
+ * ------------------
+ *   primary:     High-emphasis CTA. Accent background. One per view, maximum.
+ *   secondary:   Medium-emphasis. Raised surface with border. Multiple OK.
+ *   ghost:       Low-emphasis. Transparent. Used for icon buttons, toolbars.
+ *   destructive: For irreversible actions. Danger tint; text danger color.
+ *   link:        Prose-inline or navigation. No background, no border.
+ *
+ * SIZE PHILOSOPHY
+ * ---------------
+ *   sm:   32px height. Tight contexts: table action cells, compact toolbars.
+ *   md:   40px height. Default. Most UI buttons.
+ *   lg:   48px height. Hero CTAs, prominent forms.
+ *   icon: Square. Width = height of the selected size. Icon-only buttons.
+ *         MUST include a <span className="sr-only">label</span> child for
+ *         screen reader accessibility.
+ *
+ * HREF PROP
+ * ---------
+ * When href is provided, the component renders as a Next.js <Link>
+ * instead of a <button>. All variants are supported. The semantics
+ * are correct: navigation actions should be anchors, not buttons.
+ *
+ * LOADING STATE
+ * -------------
+ * The loading prop:
+ *   1. Replaces iconLeft with a Spinner component.
+ *   2. Adds aria-busy="true" and aria-disabled="true".
+ *   3. Adds a min-width equal to the button's natural width to prevent
+ *      the button from collapsing when text width changes. This is
+ *      implemented via inline style measuring the rendered width on mount.
+ *      Simpler approach: the parent should give the button a fixed width
+ *      when the loading state is predictable (form submit buttons).
+ */
+
+import { type ButtonHTMLAttributes, type ReactNode, forwardRef } from 'react';
+import Link from 'next/link';
+import { Spinner } from './Spinner';
+
+export interface ButtonProps extends ButtonHTMLAttributes<HTMLButtonElement> {
+  /** Visual style variant */
+  variant?: 'primary' | 'secondary' | 'ghost' | 'destructive' | 'link';
+  /** Height, padding, and font-size tier */
+  size?: 'sm' | 'md' | 'lg' | 'icon';
+  /** Replaces iconLeft with a spinner; keeps width stable via min-width */
+  loading?: boolean;
+  /** Lucide icon rendered before children */
+  iconLeft?: ReactNode;
+  /** Lucide icon rendered after children */
+  iconRight?: ReactNode;
+  /** Stretches to container width */
+  fullWidth?: boolean;
+  /** Renders as Next.js Link instead of button */
+  href?: string;
+  /** External link target (only relevant with href) */
+  target?: string;
+}
+
+/* ----------------------------------------------------------------
+   CLASS MAP
+   All Tailwind classes are defined in this map, not inline in JSX.
+   This makes the variant contract explicit and auditable.
+   ---------------------------------------------------------------- */
+
+const BASE = [
+  'relative inline-flex items-center justify-center gap-2',
+  'rounded-[var(--btn-radius)] font-medium',
+  'select-none whitespace-nowrap',
+  'transition-[background-color,box-shadow,transform,border-color,opacity]',
+  '[transition-duration:var(--duration-normal)]',
+  '[transition-timing-function:var(--ease-in-out)]',
+  'focus-visible:outline-none focus-visible:ring-2',
+  'focus-visible:ring-[var(--color-focus-ring)] focus-visible:ring-offset-2',
+  'focus-visible:ring-offset-[var(--color-bg-base)]',
+  'disabled:pointer-events-none disabled:opacity-50',
+  'aria-disabled:pointer-events-none aria-disabled:opacity-50',
+  'active:[transition-duration:var(--duration-instant)]',
+  'active:[transition-timing-function:var(--ease-spring)]',
+  'active:scale-[0.97]',
+].join(' ');
+
+const VARIANT_CLASSES: Record<NonNullable<ButtonProps['variant']>, string> = {
+  primary: [
+    'bg-[var(--color-accent)] text-white',
+    'shadow-[var(--shadow-1)]',
+    'hover:bg-[var(--color-accent-hover)]',
+    'hover:shadow-[var(--shadow-2)]',
+    'active:bg-[var(--color-accent-active)]',
+  ].join(' '),
+
+  secondary: [
+    'bg-[var(--color-bg-raised)] text-[var(--color-text-primary)]',
+    'border border-[var(--color-border-default)]',
+    'shadow-[var(--shadow-1)]',
+    'hover:border-[var(--color-border-emphasis)]',
+    'hover:bg-[var(--color-bg-raised-hover)]',
+    'active:bg-[var(--color-bg-raised-active)]',
+  ].join(' '),
+
+  ghost: [
+    'bg-transparent text-[var(--color-text-secondary)]',
+    'hover:bg-[var(--color-bg-highlight)] hover:text-[var(--color-text-primary)]',
+    'active:bg-[var(--color-accent-subtle)]',
+  ].join(' '),
+
+  destructive: [
+    'bg-[var(--color-danger-subtle)] text-[var(--color-danger)]',
+    'border border-[var(--color-danger-subtle)]',
+    'hover:bg-[var(--color-danger-hover-bg)] hover:border-[var(--color-danger)]',
+    'active:bg-[var(--color-danger-active-bg)]',
+  ].join(' '),
+
+  link: [
+    'bg-transparent text-[var(--color-text-accent)]',
+    'underline-offset-4 hover:underline',
+    'active:opacity-70',
+    'h-auto! px-0! py-0!',
+  ].join(' '),
+};
+
+const SIZE_CLASSES: Record<NonNullable<ButtonProps['size']>, string> = {
+  sm:   'h-[var(--btn-h-sm)] px-[var(--btn-px-sm)] text-[var(--type-small)]',
+  md:   'h-[var(--btn-h-md)] px-[var(--btn-px-md)] text-[var(--type-small)]',
+  lg:   'h-[var(--btn-h-lg)] px-[var(--btn-px-lg)] text-[var(--type-body)]',
+  icon: 'h-[var(--btn-h-md)] w-[var(--btn-h-md)] px-0',
+};
+
+const SIZE_ICON_SIZE: Record<NonNullable<ButtonProps['size']>, number> = {
+  sm:   14,
+  md:   16,
+  lg:   18,
+  icon: 16,
+};
+
+/* ----------------------------------------------------------------
+   COMPONENT
+   ---------------------------------------------------------------- */
+
+export const Button = forwardRef<HTMLButtonElement, ButtonProps>(
+  (
+    {
+      variant = 'primary',
+      size = 'md',
+      loading = false,
+      iconLeft,
+      iconRight,
+      fullWidth = false,
+      href,
+      target,
+      disabled,
+      children,
+      className,
+      ...rest
+    },
+    ref,
+  ) => {
+    const isDisabled = disabled || loading;
+    const iconSize = SIZE_ICON_SIZE[size];
+
+    const classes = [
+      BASE,
+      VARIANT_CLASSES[variant],
+      SIZE_CLASSES[size],
+      fullWidth ? 'w-full' : '',
+      className,
+    ]
+      .filter(Boolean)
+      .join(' ');
+
+    const content = (
+      <>
+        {/* Loading spinner replaces iconLeft, preserving layout */}
+        {loading ? (
+          <Spinner size={size === 'lg' ? 'md' : 'sm'} aria-hidden="true" />
+        ) : iconLeft ? (
+          <span aria-hidden="true" className="shrink-0">
+            {iconLeft}
+          </span>
+        ) : null}
+
+        {/* Children: hidden from SR during loading for clean state */}
+        {children && (
+          <span className={loading ? 'opacity-0 select-none' : undefined}>
+            {children}
+          </span>
+        )}
+
+        {iconRight && !loading && (
+          <span aria-hidden="true" className="shrink-0">
+            {iconRight}
+          </span>
+        )}
+      </>
+    );
+
+    /* Render as Next.js Link for navigation actions */
+    if (href) {
+      return (
+        <Link
+          href={href}
+          target={target}
+          className={classes}
+          aria-disabled={isDisabled || undefined}
+          tabIndex={isDisabled ? -1 : undefined}
+        >
+          {content}
+        </Link>
+      );
+    }
+
+    return (
+      <button
+        ref={ref}
+        type="button"
+        disabled={isDisabled}
+        aria-disabled={isDisabled || undefined}
+        aria-busy={loading || undefined}
+        className={classes}
+        {...rest}
+      >
+        {content}
+      </button>
+    );
+  },
+);
+
+Button.displayName = 'Button';

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

@@ -0,0 +1,287 @@
+/**
+ * components/primitives/Card.tsx -- saas-dashboard preset v1.0.0
+ *
+ * WHY A COMPOUND COMPONENT
+ * ------------------------
+ * A single <Card> component with a content slot is flexible but
+ * loses structural meaning: every usage would re-invent its own
+ * header/footer layout, producing inconsistent internal spacing.
+ *
+ * The compound component pattern (<Card>, <CardHeader>, <CardTitle>,
+ * etc.) gives consumers a shared grammar:
+ *   - CardHeader has a defined height, flex-row layout, and icon slot
+ *   - CardTitle and CardDescription have defined type scale tokens
+ *   - CardContent handles the padding relationship with CardHeader
+ *   - CardFooter has a border-top and consistent action layout
+ *
+ * This means QA can verify the card pattern in one place, and any
+ * change to spacing or typography propagates to every usage.
+ *
+ * ELEVATION SYSTEM
+ * ----------------
+ * Elevation 1 (default): --shadow-1
+ *   Use for: standard cards, stat cards, panels.
+ *   The inset top border simulates a light source from above.
+ *
+ * Elevation 2: --shadow-2
+ *   Use for: dropdowns, popovers, hover-elevated cards.
+ *   More ambient shadow; adds a 1px outer ring.
+ *
+ * VARIANT MODIFIERS
+ * -----------------
+ *   featured:     2px accent-color top border.
+ *                 Use for: primary plan in a pricing grid, pinned items.
+ *                 ONE featured card per visible group maximum.
+ *
+ *   interactive:  hover translateY(-2px) + shadow-2.
+ *                 Use for: clickable resource cards, navigation tiles.
+ *                 Add onRowClick or an onClick handler alongside this prop.
+ *
+ *   noPadding:    Removes CardContent internal padding.
+ *                 Use for: DataTable, full-bleed images, embedded charts.
+ *                 Sub-components are still padded unless also given noPadding.
+ *
+ *   stretch:      height: 100% for use inside flex/grid containers.
+ *
+ * TRANSITION RULES
+ * ----------------
+ * Interactive card hover:
+ *   transform: translateY(-2px) -- duration-normal ease-out (entering)
+ *   box-shadow: from shadow-1 to shadow-2 -- duration-normal ease-out
+ * Hover exit:
+ *   transform: translateY(0) -- duration-normal ease-in
+ *   box-shadow: back to shadow-1 -- duration-normal ease-in
+ * Both transitions name exactly the properties being transitioned.
+ */
+
+import React, { type HTMLAttributes, forwardRef } from 'react';
+
+/* ----------------------------------------------------------------
+   CARD ROOT
+   ---------------------------------------------------------------- */
+
+export interface CardProps extends HTMLAttributes<HTMLDivElement> {
+  /** Shadow elevation level */
+  elevation?: 1 | 2;
+  /** Adds 2px accent top border for featured/primary cards */
+  featured?: boolean;
+  /** Removes internal padding for full-bleed content */
+  noPadding?: boolean;
+  /** Adds hover lift (translateY -2px, shadow-2) for clickable cards */
+  interactive?: boolean;
+  /** Fills height of flex/grid container */
+  stretch?: boolean;
+}
+
+export const Card = forwardRef<HTMLDivElement, CardProps>(
+  (
+    {
+      elevation = 1,
+      featured = false,
+      noPadding = false,
+      interactive = false,
+      stretch = false,
+      children,
+      className,
+      style,
+      ...rest
+    },
+    ref,
+  ) => {
+    const shadowVar =
+      elevation === 2
+        ? 'var(--shadow-2)'
+        : 'var(--shadow-1)';
+
+    const classes = [
+      /* Surface */
+      'relative rounded-[var(--radius-lg)] overflow-hidden',
+      'bg-[var(--color-bg-raised)]',
+      'border border-[var(--color-border-default)]',
+      /* Featured: accent border replaces top edge */
+      featured
+        ? 'border-t-2 border-t-[var(--color-accent)]'
+        : '',
+      /* Padding */
+      noPadding ? '' : 'p-[var(--spacing-card-pad)]',
+      /* Interactive hover */
+      interactive
+        ? [
+            'cursor-pointer',
+            'transition-[transform,box-shadow]',
+            '[transition-duration:var(--duration-normal)]',
+            '[transition-timing-function:var(--ease-out)]',
+            'hover:-translate-y-0.5',
+            'hover:shadow-[var(--shadow-2)]',
+            'active:translate-y-0 active:shadow-[var(--shadow-1)]',
+            'active:[transition-timing-function:var(--ease-in)]',
+            'active:[transition-duration:var(--duration-instant)]',
+          ].join(' ')
+        : '',
+      /* Stretch */
+      stretch ? 'h-full' : '',
+      className,
+    ]
+      .filter(Boolean)
+      .join(' ');
+
+    return (
+      <div
+        ref={ref}
+        style={{ boxShadow: shadowVar, ...style }}
+        className={classes}
+        {...rest}
+      >
+        {children}
+      </div>
+    );
+  },
+);
+
+Card.displayName = 'Card';
+
+/* ----------------------------------------------------------------
+   CARD HEADER
+   flex row, space-between, consistent vertical padding.
+   ---------------------------------------------------------------- */
+
+export interface CardHeaderProps extends HTMLAttributes<HTMLDivElement> {}
+
+export const CardHeader = forwardRef<HTMLDivElement, CardHeaderProps>(
+  ({ children, className, ...rest }, ref) => (
+    <div
+      ref={ref}
+      className={[
+        'flex flex-row items-center justify-between',
+        'px-[var(--spacing-card-pad)] pt-[var(--spacing-card-pad)]',
+        'pb-[var(--space-4)]',
+        className,
+      ]
+        .filter(Boolean)
+        .join(' ')}
+      {...rest}
+    >
+      {children}
+    </div>
+  ),
+);
+
+CardHeader.displayName = 'CardHeader';
+
+/* ----------------------------------------------------------------
+   CARD TITLE
+   h4-level type scale; semibold; primary text color.
+   ---------------------------------------------------------------- */
+
+export interface CardTitleProps extends HTMLAttributes<HTMLHeadingElement> {
+  /** Heading level -- defaults to h3 for document outline. Override
+   *  only when the card is inside an existing h2 section. */
+  as?: 'h2' | 'h3' | 'h4';
+}
+
+export const CardTitle = forwardRef<HTMLHeadingElement, CardTitleProps>(
+  ({ as: Tag = 'h3', children, className, ...rest }, ref) => (
+    <Tag
+      ref={ref as React.Ref<HTMLHeadingElement>}
+      className={[
+        'text-[var(--type-h4)] leading-[var(--type-h4-lh)]',
+        'tracking-[var(--type-h4-ls)]',
+        'font-[var(--font-weight-semibold)]',
+        'text-[var(--color-text-primary)]',
+        className,
+      ]
+        .filter(Boolean)
+        .join(' ')}
+      {...rest}
+    >
+      {children}
+    </Tag>
+  ),
+);
+
+CardTitle.displayName = 'CardTitle';
+
+/* ----------------------------------------------------------------
+   CARD DESCRIPTION
+   small type scale; secondary text color.
+   ---------------------------------------------------------------- */
+
+export interface CardDescriptionProps extends HTMLAttributes<HTMLParagraphElement> {}
+
+export const CardDescription = forwardRef<HTMLParagraphElement, CardDescriptionProps>(
+  ({ children, className, ...rest }, ref) => (
+    <p
+      ref={ref}
+      className={[
+        'text-[var(--type-small)] leading-[var(--type-small-lh)]',
+        'text-[var(--color-text-secondary)]',
+        'mt-[var(--space-1)]',
+        className,
+      ]
+        .filter(Boolean)
+        .join(' ')}
+      {...rest}
+    >
+      {children}
+    </p>
+  ),
+);
+
+CardDescription.displayName = 'CardDescription';
+
+/* ----------------------------------------------------------------
+   CARD CONTENT
+   Removes top padding when it follows a CardHeader.
+   ---------------------------------------------------------------- */
+
+export interface CardContentProps extends HTMLAttributes<HTMLDivElement> {}
+
+export const CardContent = forwardRef<HTMLDivElement, CardContentProps>(
+  ({ children, className, ...rest }, ref) => (
+    <div
+      ref={ref}
+      className={[
+        'px-[var(--spacing-card-pad)] pb-[var(--spacing-card-pad)]',
+        /* Remove top padding: CardHeader already provides bottom padding */
+        '[.card-has-header_+_&]:pt-0 pt-[var(--spacing-card-pad)]',
+        className,
+      ]
+        .filter(Boolean)
+        .join(' ')}
+      {...rest}
+    >
+      {children}
+    </div>
+  ),
+);
+
+CardContent.displayName = 'CardContent';
+
+/* ----------------------------------------------------------------
+   CARD FOOTER
+   Border-top divider; flex row for action buttons.
+   ---------------------------------------------------------------- */
+
+export interface CardFooterProps extends HTMLAttributes<HTMLDivElement> {}
+
+export const CardFooter = forwardRef<HTMLDivElement, CardFooterProps>(
+  ({ children, className, ...rest }, ref) => (
+    <div
+      ref={ref}
+      className={[
+        'flex flex-row items-center gap-[var(--space-2)]',
+        'px-[var(--spacing-card-pad)] py-[var(--space-4)]',
+        'border-t border-[var(--color-border-default)]',
+        className,
+      ]
+        .filter(Boolean)
+        .join(' ')}
+      {...rest}
+    >
+      {children}
+    </div>
+  ),
+);
+
+CardFooter.displayName = 'CardFooter';
+