chati-dev 4.3.1 → 4.4.0

package/framework/scaffold/saas-dashboard/components/interaction/Form.tsx.template

@@ -0,0 +1,424 @@
+/**
+ * components/interaction/Form.tsx
+ * SaaS Dashboard Preset -- D_interaction phase
+ *
+ * WHY THIS EXISTS
+ * ---------------
+ * Form composition is one of the highest-friction areas in dashboard UI.
+ * Three recurring failures:
+ *
+ *   1. Error summary placement: errors appear in field-level tooltips only,
+ *      so keyboard users navigating linearly miss them. A centralized error
+ *      summary at the top of the form, announced via role=alert and focus-
+ *      managed on submit failure, is the accessible pattern.
+ *
+ *   2. Responsive layout inconsistency: developers reach for ad-hoc grid
+ *      utilities, producing forms that look great on desktop but stack
+ *      badly on mobile or create awkward widths on tablet. FormRow
+ *      encapsulates the 1-column mobile / 2-column desktop pattern once.
+ *
+ *   3. Action bar stickiness on mobile: a long form with a floating submit
+ *      button that disappears into the scroll area is a conversion killer
+ *      on mobile. FormActions sticks to the bottom of the viewport on
+ *      narrow screens but flows inline at desktop widths.
+ *
+ * COMPONENT MAP
+ * -------------
+ * Form          -- <form> wrapper, handles onSubmit + error summary
+ * FormSection   -- Labeled group (<fieldset> + <legend> or <div> + heading)
+ * FormRow       -- CSS grid: 1-col mobile, 2-col desktop
+ * FormActions   -- Action bar with primary + cancel
+ *
+ * USAGE EXAMPLE
+ * -------------
+ * <Form onSubmit={handleSubmit} errors={formErrors}>
+ *   <FormSection label="Personal details">
+ *     <FormRow>
+ *       <Field label="First name" required inputProps={{ name: 'firstName' }} />
+ *       <Field label="Last name" required inputProps={{ name: 'lastName' }} />
+ *     </FormRow>
+ *     <Field label="Email address" required inputProps={{ type: 'email', name: 'email' }} />
+ *   </FormSection>
+ *   <FormActions primaryLabel="Save changes" onCancel={handleCancel} />
+ * </Form>
+ *
+ * TOKEN USAGE
+ * -----------
+ * All spacing, colors, and radii reference CSS custom properties.
+ */
+
+'use client';
+
+import React, {
+  useRef,
+  useEffect,
+  type FormHTMLAttributes,
+  type ReactNode,
+} from 'react';
+import { AlertCircle } from 'lucide-react';
+import { Button } from '@/components/primitives/Button';
+import { Field } from '@/components/interaction/Field';
+
+// ---------------------------------------------------------------------------
+// Form root
+// ---------------------------------------------------------------------------
+
+export interface FormError {
+  field?: string;
+  message: string;
+}
+
+export interface FormProps extends Omit<FormHTMLAttributes<HTMLFormElement>, 'onSubmit'> {
+  onSubmit: (e: React.FormEvent<HTMLFormElement>) => void | Promise<void>;
+  /** Top-level errors rendered in the error summary block. */
+  errors?: FormError[];
+  children: ReactNode;
+}
+
+export function Form({ onSubmit, errors, children, ...rest }: FormProps) {
+  const errorSummaryRef = useRef<HTMLDivElement>(null);
+
+  // Move focus to error summary on new errors (accessibility: SR users hear it)
+  useEffect(() => {
+    if (errors && errors.length > 0) {
+      errorSummaryRef.current?.focus();
+    }
+  }, [errors]);
+
+  async function handleSubmit(e: React.FormEvent<HTMLFormElement>) {
+    e.preventDefault();
+    await onSubmit(e);
+  }
+
+  return (
+    <form
+      onSubmit={handleSubmit}
+      noValidate
+      style={{ display: 'flex', flexDirection: 'column', gap: 'var(--spacing-section)' }}
+      {...rest}
+    >
+      {/* Error summary */}
+      {errors && errors.length > 0 && (
+        <div
+          ref={errorSummaryRef}
+          role="alert"
+          aria-live="assertive"
+          tabIndex={-1}
+          style={{
+            display: 'flex',
+            gap: 'var(--space-3)',
+            padding: 'var(--space-4)',
+            backgroundColor: 'var(--color-danger-subtle)',
+            border: '1px solid var(--color-danger)',
+            borderRadius: 'var(--radius-default)',
+            outline: 'none',
+          }}
+        >
+          <AlertCircle
+            size={18}
+            aria-hidden="true"
+            style={{ color: 'var(--color-danger)', flexShrink: 0, marginTop: '1px' }}
+          />
+          <div style={{ flex: 1 }}>
+            <p
+              style={{
+                fontSize: 'var(--type-small)',
+                fontWeight: 600,
+                color: 'var(--color-danger)',
+                margin: '0 0 var(--space-1)',
+              }}
+            >
+              Please fix the following errors:
+            </p>
+            <ul
+              style={{
+                margin: 0,
+                paddingLeft: 'var(--space-4)',
+                fontSize: 'var(--type-small)',
+                color: 'var(--color-danger)',
+              }}
+            >
+              {errors.map((err, i) => (
+                <li key={i}>{err.message}</li>
+              ))}
+            </ul>
+          </div>
+        </div>
+      )}
+
+      {children}
+    </form>
+  );
+}
+
+// ---------------------------------------------------------------------------
+// FormSection
+// ---------------------------------------------------------------------------
+
+export interface FormSectionProps {
+  /** Rendered as a <legend> inside <fieldset> when useFieldset=true,
+   *  otherwise as a heading above the group. */
+  label: string;
+  /** Optional description below the label. */
+  description?: string;
+  /** Use semantic <fieldset> + <legend>. Default true for radio/checkbox groups. */
+  useFieldset?: boolean;
+  children: ReactNode;
+}
+
+export function FormSection({
+  label,
+  description,
+  useFieldset = false,
+  children,
+}: FormSectionProps) {
+  const content = (
+    <>
+      <div
+        style={{
+          paddingBottom: 'var(--space-5)',
+          borderBottom: '1px solid var(--color-border-default)',
+          marginBottom: 'var(--space-6)',
+        }}
+      >
+        {useFieldset ? (
+          <legend
+            style={{
+              fontSize: 'var(--type-h4)',
+              lineHeight: 'var(--type-h4-lh)',
+              fontWeight: 600,
+              color: 'var(--color-text-primary)',
+              letterSpacing: 'var(--type-h4-ls)',
+              padding: 0,
+            }}
+          >
+            {label}
+          </legend>
+        ) : (
+          <h3
+            style={{
+              fontSize: 'var(--type-h4)',
+              lineHeight: 'var(--type-h4-lh)',
+              fontWeight: 600,
+              color: 'var(--color-text-primary)',
+              letterSpacing: 'var(--type-h4-ls)',
+              margin: 0,
+            }}
+          >
+            {label}
+          </h3>
+        )}
+        {description && (
+          <p
+            style={{
+              fontSize: 'var(--type-small)',
+              lineHeight: 'var(--type-small-lh)',
+              color: 'var(--color-text-secondary)',
+              margin: 'var(--space-1) 0 0',
+            }}
+          >
+            {description}
+          </p>
+        )}
+      </div>
+      <div
+        style={{ display: 'flex', flexDirection: 'column', gap: 'var(--spacing-card-gap)' }}
+      >
+        {children}
+      </div>
+    </>
+  );
+
+  if (useFieldset) {
+    return (
+      <fieldset
+        style={{
+          border: 'none',
+          padding: 0,
+          margin: 0,
+        }}
+      >
+        {content}
+      </fieldset>
+    );
+  }
+
+  return <div>{content}</div>;
+}
+
+// ---------------------------------------------------------------------------
+// FormRow (responsive 2-col grid)
+// ---------------------------------------------------------------------------
+
+export function FormRow({ children }: { children: ReactNode }) {
+  return (
+    <div
+      style={{
+        display: 'grid',
+        gap: 'var(--spacing-card-gap)',
+        // CSS custom property trick: Tailwind-free responsive grid via
+        // container query when available, viewport query as fallback.
+        gridTemplateColumns: 'repeat(auto-fit, minmax(min(100%, 240px), 1fr))',
+      }}
+    >
+      {children}
+    </div>
+  );
+}
+
+// ---------------------------------------------------------------------------
+// FormActions
+// ---------------------------------------------------------------------------
+
+export interface FormActionsProps {
+  /** Primary action label (submit button). */
+  primaryLabel?: string;
+  /** Called when cancel is clicked. Renders cancel button only when provided. */
+  onCancel?: () => void;
+  /** Set true when form submission is in progress. */
+  loading?: boolean;
+  /** Disables primary button. */
+  disabled?: boolean;
+}
+
+export function FormActions({
+  primaryLabel = 'Save changes',
+  onCancel,
+  loading = false,
+  disabled = false,
+}: FormActionsProps) {
+  return (
+    <div
+      style={{
+        display: 'flex',
+        alignItems: 'center',
+        justifyContent: 'flex-end',
+        gap: 'var(--space-3)',
+        paddingTop: 'var(--space-6)',
+        borderTop: '1px solid var(--color-border-default)',
+        // Sticky on mobile: stays visible at bottom of viewport
+        position: 'sticky',
+        bottom: 0,
+        backgroundColor: 'var(--color-bg-base)',
+        zIndex: 10,
+        marginInline: 'calc(-1 * var(--spacing-card-pad))',
+        paddingInline: 'var(--spacing-card-pad)',
+        paddingBottom: 'var(--space-4)',
+      }}
+    >
+      {onCancel && (
+        <Button
+          variant="secondary"
+          size="md"
+          type="button"
+          onClick={onCancel}
+          disabled={loading}
+        >
+          Cancel
+        </Button>
+      )}
+      <Button
+        variant="primary"
+        size="md"
+        type="submit"
+        loading={loading}
+        disabled={disabled}
+      >
+        {primaryLabel}
+      </Button>
+    </div>
+  );
+}
+
+// ---------------------------------------------------------------------------
+// FormExample (demonstration component, not part of the public API)
+// ---------------------------------------------------------------------------
+
+/**
+ * FormExample: a complete, self-contained form demonstrating:
+ * - Real labels (never placeholder-only)
+ * - Validation error states
+ * - Required field marking
+ * - 2-column responsive row
+ * - FormActions with loading state
+ *
+ * Import path: @/components/interaction/Form (named export)
+ */
+export function FormExample() {
+  return (
+    <Form
+      onSubmit={async (e) => {
+        // Replace with your submit handler
+        await new Promise((r) => setTimeout(r, 1200));
+      }}
+      errors={[
+        { field: 'email', message: 'Email address is not valid' },
+      ]}
+    >
+      <FormSection
+        label="Account details"
+        description="Update your personal information and contact details."
+      >
+        <FormRow>
+          <Field
+            label="First name"
+            required
+            inputProps={{
+              name: 'firstName',
+              autoComplete: 'given-name',
+              placeholder: 'Ada',
+            }}
+          />
+          <Field
+            label="Last name"
+            required
+            inputProps={{
+              name: 'lastName',
+              autoComplete: 'family-name',
+              placeholder: 'Lovelace',
+            }}
+          />
+        </FormRow>
+
+        <Field
+          label="Email address"
+          required
+          error="Email address is not valid"
+          hint="Used for login and notifications"
+          inputProps={{
+            type: 'email',
+            name: 'email',
+            autoComplete: 'email',
+            placeholder: 'ada@example.com',
+          }}
+        />
+
+        <Field
+          label="Role"
+          as="select"
+          hint="Determines permissions and dashboard access."
+          selectProps={{ name: 'role', defaultValue: '' }}
+        >
+          <option value="" disabled>
+            Select a role...
+          </option>
+          <option value="admin">Admin</option>
+          <option value="editor">Editor</option>
+          <option value="viewer">Viewer</option>
+        </Field>
+
+        <Field
+          label="Notes"
+          as="textarea"
+          hint="Optional context for the team."
+          textareaProps={{
+            name: 'notes',
+            placeholder: 'Anything the team should know...',
+          }}
+        />
+      </FormSection>
+
+      <FormActions primaryLabel="Save changes" onCancel={() => {}} />
+    </Form>
+  );
+}

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

@@ -0,0 +1,193 @@
+/**
+ * components/primitives/Badge.tsx -- saas-dashboard preset v1.0.0
+ *
+ * WHY BADGES NEED A PRIMITIVE
+ * ----------------------------
+ * Status indicators, count bubbles, category tags, and removable
+ * filter chips all share the same fundamental anatomy:
+ *   - Pill or rounded-rectangle shape
+ *   - Small type scale (caption or small)
+ *   - Semantic color that communicates intent (success=green, etc.)
+ *   - Optional leading dot for additional visual emphasis
+ *   - Optional trailing X for removable tags
+ *
+ * Without a shared primitive, these proliferate as ad-hoc div+span
+ * combinations with inconsistent padding, varying font weights, and
+ * colour values that reference raw hex instead of semantic tokens.
+ * The Badge primitive centralises this into one contract.
+ *
+ * VARIANT SEMANTICS
+ * -----------------
+ *   default:     Neutral tint. Use for categories, labels.
+ *   success:     Green tint. Use for active, complete, healthy.
+ *   warning:     Amber tint. Use for pending, at-risk, expiring.
+ *   danger:      Red tint. Use for error, critical, overdue.
+ *   info:        Sky tint. Use for informational, new, beta.
+ *   accent:      Violet tint. Use for featured, promoted, selected.
+ *
+ * Each variant uses the semantic *-subtle token for background and
+ * the full-saturation token for text/dot. This ensures the badge
+ * reads clearly on all surface levels (bg-base, bg-raised, bg-overlay).
+ *
+ * SIZE SYSTEM
+ * -----------
+ *   sm: 12px type (caption), 2px/8px padding -- for table cells, tight grids
+ *   md: 14px type (small), 4px/10px padding  -- default, standalone usage
+ *
+ * DOT VARIANT
+ * -----------
+ * Renders a 6px filled circle before the label text, color-matched
+ * to the variant's full-saturation token. Communicates "status"
+ * more emphatically than text alone.
+ *
+ * REMOVABLE VARIANT
+ * -----------------
+ * Appends an X icon button. The button has its own focus ring and
+ * is keyboard-accessible. The badge animates out via framer-motion
+ * AnimatePresence when removed (opacity fade, scale, --duration-fast).
+ *
+ * The parent is responsible for removing the badge from the list on
+ * onRemove; the badge itself only handles the visual transition.
+ *
+ * TRANSITIONS
+ * -----------
+ * Mount/unmount animation via framer-motion AnimatePresence:
+ *   enter: opacity 0 -> 1, scale 0.85 -> 1, ease-out, duration-fast
+ *   exit:  opacity 1 -> 0, scale 1 -> 0.85, ease-in, duration-fast
+ * Hover on removable X: opacity 0.7 -> 1, duration-instant.
+ */
+
+import { type HTMLAttributes, type MouseEventHandler } from 'react';
+import { AnimatePresence, motion } from 'framer-motion';
+import { X } from 'lucide-react';
+import { DURATION, EASING } from '@/lib/brand';
+
+export interface BadgeProps extends HTMLAttributes<HTMLSpanElement> {
+  /** Color intent */
+  variant?: 'default' | 'success' | 'warning' | 'danger' | 'info' | 'accent';
+  /** Size */
+  size?: 'sm' | 'md';
+  /** Renders a 6px status dot before label */
+  dot?: boolean;
+  /** Makes badge a removable tag with X icon button */
+  removable?: boolean;
+  /** Called when X is clicked (requires removable=true) */
+  onRemove?: MouseEventHandler<HTMLButtonElement>;
+  /** Controls AnimatePresence for exit animation */
+  visible?: boolean;
+}
+
+/* ----------------------------------------------------------------
+   CLASS MAPS
+   ---------------------------------------------------------------- */
+
+const SIZE_CLASSES: Record<NonNullable<BadgeProps['size']>, string> = {
+  sm: 'px-[var(--space-2)] py-[var(--space-px)] text-[var(--type-caption)] leading-[var(--type-caption-lh)] tracking-[var(--type-caption-ls)]',
+  md: 'px-[var(--space-3)] py-[var(--space-1)] text-[var(--type-small)] leading-[var(--type-small-lh)]',
+};
+
+const DOT_COLOR: Record<NonNullable<BadgeProps['variant']>, string> = {
+  default: 'bg-[var(--color-neutral-400)]',
+  success: 'bg-[var(--color-success)]',
+  warning: 'bg-[var(--color-warning)]',
+  danger:  'bg-[var(--color-danger)]',
+  info:    'bg-[var(--color-info)]',
+  accent:  'bg-[var(--color-accent)]',
+};
+
+const VARIANT_CLASSES: Record<NonNullable<BadgeProps['variant']>, string> = {
+  default: 'bg-[var(--color-bg-raised)] text-[var(--color-text-secondary)] border border-[var(--color-border-default)]',
+  success: 'bg-[var(--color-success-subtle)] text-[var(--color-success)]',
+  warning: 'bg-[var(--color-warning-subtle)] text-[var(--color-warning)]',
+  danger:  'bg-[var(--color-danger-subtle)] text-[var(--color-danger)]',
+  info:    'bg-[var(--color-info-subtle)] text-[var(--color-info)]',
+  accent:  'bg-[var(--color-accent-subtle)] text-[var(--color-accent-hover)]',
+};
+
+/* ----------------------------------------------------------------
+   COMPONENT
+   ---------------------------------------------------------------- */
+
+export function Badge({
+  variant = 'default',
+  size = 'md',
+  dot = false,
+  removable = false,
+  onRemove,
+  visible = true,
+  children,
+  className,
+  ...rest
+}: BadgeProps) {
+  const classes = [
+    'inline-flex items-center gap-[var(--space-1)]',
+    'rounded-[var(--radius-pill)]',
+    'font-[var(--font-weight-medium)]',
+    'whitespace-nowrap',
+    VARIANT_CLASSES[variant],
+    SIZE_CLASSES[size],
+    className,
+  ]
+    .filter(Boolean)
+    .join(' ');
+
+  const badgeContent = (
+    <span className={classes} {...rest}>
+      {dot && (
+        <span
+          aria-hidden="true"
+          className={[
+            'inline-block rounded-full w-1.5 h-1.5 shrink-0',
+            DOT_COLOR[variant],
+          ].join(' ')}
+        />
+      )}
+
+      <span>{children}</span>
+
+      {removable && (
+        <button
+          type="button"
+          onClick={onRemove}
+          aria-label={`Remove ${typeof children === 'string' ? children : 'item'}`}
+          className={[
+            'inline-flex items-center justify-center',
+            'w-3.5 h-3.5 rounded-full',
+            'opacity-60 hover:opacity-100',
+            'transition-opacity [transition-duration:var(--duration-instant)]',
+            '[transition-timing-function:var(--ease-in-out)]',
+            'focus-visible:outline-none focus-visible:ring-1',
+            'focus-visible:ring-[var(--color-focus-ring)]',
+            'cursor-pointer',
+          ].join(' ')}
+        >
+          <X size={10} aria-hidden="true" />
+        </button>
+      )}
+    </span>
+  );
+
+  /* For removable badges, wrap in AnimatePresence for exit animation */
+  if (removable) {
+    return (
+      <AnimatePresence>
+        {visible && (
+          <motion.span
+            initial={{ opacity: 0, scale: 0.85 }}
+            animate={{ opacity: 1, scale: 1 }}
+            exit={{ opacity: 0, scale: 0.85 }}
+            transition={{
+              duration: DURATION.fast / 1000,
+              ease: EASING.out,
+            }}
+            style={{ display: 'inline-flex' }}
+          >
+            {badgeContent}
+          </motion.span>
+        )}
+      </AnimatePresence>
+    );
+  }
+
+  return badgeContent;
+}