@umituz/web-design-system 5.3.0 → 5.4.0

package/src/presentation/organisms/LoadingState.tsx

@@ -1,7 +1,3 @@
-/**
- * LoadingState Component (Organism)
- * @description Component for displaying loading states (Responsive)
- */
 
 import { forwardRef } from 'react';
 import { cn, getSpacing, getGap } from '../../infrastructure/utils';

package/src/presentation/organisms/MapPreview.tsx

@@ -1,20 +1,11 @@
-/**
- * MapPreview Component (Organism)
- * @description Static map stand-in drawn with a contour motif — a neutral
- *   placeholder for locations until a real GIS integration exists. Colors
- *   come from the semantic tokens, so it adapts to every host theme.
- */
 
 import { MapPin } from 'lucide-react';
 
 export interface MapPreviewProps {
-  /** Location caption, e.g. "Torba, Bodrum". */
   label: string;
   coordinates?: { lat: number; lng: number };
   height?: number;
-  /** Secondary caption line, e.g. an integration note. */
   hint?: string;
-  /** Degrees formatting for the coordinate readout; defaults to 4 decimals. */
   formatCoordinate?: (value: number) => string;
 }
 

package/src/presentation/organisms/MetricCard.tsx

@@ -1,7 +1,3 @@
-/**
- * MetricCard Component (Organism)
- * @description Card component for displaying metrics and statistics with trend indicators (Responsive)
- */
 
 import { forwardRef } from 'react';
 import { cn, getSpacing, getIconSize, getTextSize, getGap } from '../../infrastructure/utils';
@@ -21,7 +17,7 @@ export interface MetricCardProps extends BaseProps {
   variant?: ColorVariant;
   trendValueFormatter?: (value: number) => string;
   onClick?: () => void;
-  responsiveLayout?: boolean; // Enable responsive layout changes
+  responsiveLayout?: boolean;
 }
 
 const trendColors: Record<ColorVariant, { positive: string; negative: string; bg: string }> = {

package/src/presentation/organisms/Modal.tsx

@@ -1,7 +1,3 @@
-/**
- * Modal Component (Organism)
- * @description Convenience modal with title, description, size and footer presets
- */
 
 import type { ReactNode } from 'react';
 import { AlertTriangle } from 'lucide-react';

package/src/presentation/organisms/PhotoGallery.tsx

@@ -1,20 +1,11 @@
-/**
- * PhotoGallery Component (Organism)
- * @description Placeholder photo gallery — renders tinted tiles with a
- *   caption bar for photos that have no storage backend yet. When a host
- *   wires real image URLs it can render them inside the same tile frame.
- */
 
 import { Image as ImageIcon, ImageOff } from 'lucide-react';
 import { cn } from '../../infrastructure/utils';
 
 export interface PhotoTile {
   id: string;
-  /** Primary caption, e.g. the photo title. */
   label?: string;
-  /** Secondary caption line, e.g. a kind tag or a date. */
   meta?: string;
-  /** Optional image URL — rendered in place of the placeholder mark. */
   src?: string;
 }
 

package/src/presentation/organisms/PlanPicker.tsx

@@ -1,8 +1,3 @@
-/**
- * PlanPicker Component (Organism)
- * @description Pricing plan card group with an optional billing cycle switch;
- * money stays caller-computed — price and features are plain nodes
- */
 
 import type { KeyboardEvent, ReactNode } from 'react';
 import { Check } from 'lucide-react';

package/src/presentation/organisms/Popover.tsx

@@ -1,7 +1,3 @@
-/**
- * Popover Component (Organism)
- * @description Popover dialog (Shadcn/ui compatible)
- */
 
 import * as React from 'react';
 import * as PopoverPrimitive from '@radix-ui/react-popover';

package/src/presentation/organisms/Sheet.tsx

@@ -1,7 +1,3 @@
-/**
- * Sheet Component (Organism)
- * @description Slide-over sheet dialog (Shadcn/ui compatible)
- */
 
 import * as SheetPrimitive from '@radix-ui/react-dialog';
 import { X } from 'lucide-react';

package/src/presentation/organisms/StatCard.tsx

@@ -1,7 +1,3 @@
-/**
- * StatCard Component (Organism)
- * @description Enhanced metric card with progress bar and target tracking (Responsive)
- */
 
 import { forwardRef, type ComponentType } from 'react';
 import { cn, getSpacing, getIconSize, getContainerSize, getTextSize, getSpaceY, getGap } from '../../infrastructure/utils';
@@ -20,7 +16,6 @@ export interface StatCardProps extends BaseProps {
     value: number;
     label?: string;
   };
-  /** Secondary context line rendered under the title. */
   meta?: string;
   target?: {
     value: string;

package/src/presentation/organisms/StatsGrid.tsx

@@ -0,0 +1,110 @@
+import * as React from 'react';
+import { Card } from './Card';
+import { Skeleton } from '../atoms/Skeleton';
+import { TrendingUp, TrendingDown, Minus } from 'lucide-react';
+import { cn } from '../../infrastructure/utils';
+
+export interface StatItem {
+  id?: string;
+  title: string;
+  value: string | number;
+  change?: string;
+  trend?: 'up' | 'down' | 'neutral';
+  icon?: React.ReactNode;
+  description?: string;
+}
+
+export interface StatsGridProps extends React.HTMLAttributes<HTMLDivElement> {
+  stats: StatItem[];
+  columns?: 2 | 3 | 4;
+  loading?: boolean;
+}
+
+const colStyles = {
+  2: 'grid-cols-1 sm:grid-cols-2',
+  3: 'grid-cols-1 sm:grid-cols-2 lg:grid-cols-3',
+  4: 'grid-cols-1 sm:grid-cols-2 lg:grid-cols-4',
+};
+
+export const StatsGrid = React.forwardRef<HTMLDivElement, StatsGridProps>(
+  ({ stats, columns = 4, loading = false, className, ...props }, ref) => {
+    if (loading) {
+      return (
+        <div
+          ref={ref}
+          className={cn('grid gap-4 w-full', colStyles[columns], className)}
+          {...props}
+        >
+          {Array.from({ length: columns }).map((_, i) => (
+            <Card key={i} className="p-5 flex flex-col gap-3">
+              <Skeleton className="h-4 w-24" />
+              <Skeleton className="h-8 w-32" />
+              <Skeleton className="h-3 w-40" />
+            </Card>
+          ))}
+        </div>
+      );
+    }
+
+    return (
+      <div
+        ref={ref}
+        className={cn('grid gap-4 w-full', colStyles[columns], className)}
+        {...props}
+      >
+        {stats.map((stat, idx) => {
+          const isUp = stat.trend === 'up';
+          const isDown = stat.trend === 'down';
+
+          return (
+            <Card
+              key={stat.id ?? idx}
+              className="p-5 flex flex-col justify-between transition-shadow hover:shadow-md"
+            >
+              <div className="flex items-start justify-between gap-2">
+                <span className="text-sm font-medium text-muted-foreground truncate">
+                  {stat.title}
+                </span>
+                {stat.icon && (
+                  <div className="size-9 rounded-lg bg-accent/60 flex items-center justify-center text-foreground shrink-0 [&_svg]:size-4">
+                    {stat.icon}
+                  </div>
+                )}
+              </div>
+
+              <div className="mt-3 flex items-baseline justify-between gap-2">
+                <div className="text-2xl font-bold tracking-tight text-foreground">
+                  {stat.value}
+                </div>
+
+                {stat.change && (
+                  <span
+                    className={cn(
+                      'inline-flex items-center gap-1 text-xs font-semibold px-2 py-0.5 rounded-full',
+                      isUp && 'bg-emerald-500/10 text-emerald-600 dark:text-emerald-400',
+                      isDown && 'bg-rose-500/10 text-rose-600 dark:text-rose-400',
+                      !isUp && !isDown && 'bg-accent text-muted-foreground'
+                    )}
+                  >
+                    {isUp && <TrendingUp className="size-3" />}
+                    {isDown && <TrendingDown className="size-3" />}
+                    {!isUp && !isDown && <Minus className="size-3" />}
+                    <span>{stat.change}</span>
+                  </span>
+                )}
+              </div>
+
+              {stat.description && (
+                <p className="mt-2 text-xs text-muted-foreground line-clamp-1">
+                  {stat.description}
+                </p>
+              )}
+            </Card>
+          );
+        })}
+      </div>
+    );
+  }
+);
+
+StatsGrid.displayName = 'StatsGrid';

package/src/presentation/organisms/StatusBadge.tsx

@@ -1,9 +1,3 @@
-/**
- * StatusBadge Component (Organism)
- * @description Vocab-driven status badge — resolves a raw value against a
- *   status map (label + tone), falling back to a neutral badge with the
- *   raw value as its label.
- */
 
 import type { ReactNode } from 'react';
 import { Badge } from '../atoms/Badge';
@@ -17,11 +11,6 @@ export interface StatusEntry {
 
 export type StatusVocab = Record<string, StatusEntry>;
 
-/**
- * Status vocab fabric — build a vocab from a domain label map (raw value →
- * display label) plus an optional tone table (raw value → badge tone).
- * Entries without a tone render neutral.
- */
 export function statusVocab(
   labels: Record<string, string>,
   tones: Record<string, BadgeVariant> = {},
@@ -36,7 +25,6 @@ export function statusVocab(
 export interface StatusBadgeProps {
   vocab: StatusVocab;
   value: string;
-  /** Render text in place of the vocab entry's label (tone still comes from the vocab). */
   label?: ReactNode;
   dot?: boolean;
   mono?: boolean;

package/src/presentation/organisms/Stepper.tsx

@@ -1,8 +1,3 @@
-/**
- * Stepper Component (Organism)
- * @description Horizontal or vertical step indicator with derived status,
- * optional click navigation and per-step override/lock control
- */
 
 import type { ReactNode } from 'react';
 import { Check } from 'lucide-react';

package/src/presentation/organisms/Table.tsx

@@ -1,7 +1,3 @@
-/**
- * Table Component (Organism)
- * @description Data table component
- */
 
 import { forwardRef, type HTMLAttributes, type TdHTMLAttributes, type ThHTMLAttributes } from 'react';
 import React from 'react';

package/src/presentation/organisms/Tabs.tsx

@@ -1,7 +1,3 @@
-/**
- * Tabs Component (Organism)
- * @description Tabbed interface
- */
 
 import { useRef, useState, useCallback, type KeyboardEvent, type ReactNode, type HTMLAttributes } from 'react';
 import { cn } from '../../infrastructure/utils';
@@ -23,7 +19,6 @@ export interface TabsProps extends HTMLAttributes<HTMLDivElement>, BaseProps {
   variant?: 'default' | 'pills' | 'underline';
   ariaLabel?: string;
   panelId?: string;
-  /** Render only the tab list (e.g. URL-driven tabs whose content lives elsewhere). */
   showPanel?: boolean;
 }
 
@@ -95,7 +90,6 @@ export function Tabs({ tabs, defaultValue, value, onValueChange, variant = 'defa
 
   return (
     <div className={cn('w-full', className)} {...props}>
-      {/* Tab List */}
       <div
         ref={listRef}
         role="tablist"
@@ -138,7 +132,6 @@ export function Tabs({ tabs, defaultValue, value, onValueChange, variant = 'defa
         })}
       </div>
 
-      {/* Tab Content */}
       {showPanel && (
         <div
           role="tabpanel"

package/src/presentation/organisms/Timeline.tsx

@@ -1,7 +1,3 @@
-/**
- * Timeline Component (Organism)
- * @description Vertical activity timeline: meta line, title, optional body, tone dot
- */
 
 import { forwardRef } from 'react';
 import type { HTMLAttributes, ReactNode } from 'react';
@@ -11,21 +7,17 @@ import type { BaseProps } from '../../domain/types';
 export type TimelineTone = 'primary' | 'success' | 'warning' | 'destructive' | 'info' | 'neutral' | 'violet';
 
 export interface TimelineItem {
-  /** ISO timestamp rendered as the meta line unless `meta` overrides it. */
   at: string;
   title: ReactNode;
   body?: ReactNode;
   tone?: TimelineTone;
   meta?: ReactNode;
-  /** Replaces the tone dot with an icon, tinted by `tone` (or muted when omitted). */
   icon?: ReactNode;
-  /** Replaces the tone dot with an avatar (e.g. the acting user); takes precedence over `icon`. */
   avatar?: ReactNode;
 }
 
 export interface TimelineProps extends HTMLAttributes<HTMLOListElement>, BaseProps {
   items: TimelineItem[];
-  /** Render newest first (default) instead of the given order. */
   newestFirst?: boolean;
 }
 

package/src/presentation/organisms/Toaster.tsx

@@ -1,9 +1,3 @@
-/**
- * Toaster Component (Organism)
- * @description Toast notification system. ToastProvider wraps the app root
- * ONCE and renders the viewport (bottom-right stack, max 4, auto-dismiss
- * 4.2 s); pages fire toasts via useToast()({ kind, title, description }).
- */
 
 import { createContext, useCallback, useContext, useMemo, useRef, useState } from 'react';
 import type { ReactNode } from 'react';
@@ -24,10 +18,8 @@ export interface ToastShorthandOptions {
 }
 
 interface ToastApi {
-  /** Fire a toast — after every mutating action is the fleet idiom. */
   toast: {
     (t: ToastOptions): void;
-    /** Shorthand call: toast('Saved', { tone: 'success', message: '…' }). */
     (title: string, options?: ToastShorthandOptions): void;
   };
 }
@@ -38,7 +30,6 @@ interface ToastEntry extends ToastOptions {
 
 const ToastContext = createContext<ToastApi>({ toast: () => {} });
 
-/** Consume from any page below the provider: const { toast } = useToast(); */
 export function useToast(): ToastApi {
   return useContext(ToastContext);
 }

package/src/presentation/organisms/ToggleGroup.tsx

@@ -1,7 +1,3 @@
-/**
- * Toggle Group Component (Organism) - Shadcn/ui format
- * @description Group of toggle buttons with single or multiple selection
- */
 
 import * as React from 'react';
 import * as ToggleGroupPrimitive from '@radix-ui/react-toggle-group';

package/src/presentation/organisms/index.ts

@@ -1,9 +1,3 @@
-/**
- * Organisms Export
- * @description Organism components - complex UI combinations
- * Subpath: @umituz/web-design-system/organisms
- */
-
 export { Card, CardHeader, CardTitle, CardDescription, CardContent, CardFooter } from './Card';
 export type { CardProps, CardHeaderProps } from './Card';
 
@@ -18,7 +12,7 @@ export {
   TableRow,
   TableHead,
   TableCell,
-  TableCaption
+  TableCaption,
 } from './Table';
 export type { TableProps } from './Table';
 
@@ -41,10 +35,10 @@ export {
 } from './Dialog';
 
 export { CommandPalette } from './CommandPalette';
+export type { CommandPaletteProps, CommandGroup, CommandItem } from './CommandPalette';
 
 export { ErrorBoundary } from './ErrorBoundary';
 export type { ErrorBoundaryProps } from './ErrorBoundary';
-export type { CommandPaletteProps, CommandGroup, CommandItem } from './CommandPalette';
 
 export { Breadcrumbs } from './Breadcrumb';
 export type { BreadcrumbsProps, BreadcrumbItem } from './Breadcrumb';
@@ -117,7 +111,7 @@ export {
 export { ToggleGroup, ToggleGroupItem } from './ToggleGroup';
 
 export { ToastProvider, useToast } from './Toaster';
-export type { ToastKind, ToastOptions } from './Toaster';
+export type { ToastKind, ToastOptions, ToastShorthandOptions } from './Toaster';
 
 export { KeyValueList } from './KeyValueList';
 export type { KeyValueListProps, KeyValueItem } from './KeyValueList';
@@ -154,8 +148,6 @@ export type { PhotoGalleryProps, PhotoTile } from './PhotoGallery';
 export { Lightbox } from './Lightbox';
 export type { LightboxProps } from './Lightbox';
 
-export type { ToastShorthandOptions } from './Toaster';
-
 export { Timeline } from './Timeline';
 export type { TimelineProps, TimelineItem, TimelineTone } from './Timeline';
 
@@ -186,3 +178,10 @@ export type { PlanPickerProps, PlanPickerPlan, PlanPickerCycle } from './PlanPic
 
 export { CoverArt } from './CoverArt';
 export type { CoverArtProps } from './CoverArt';
+
+// New Productivity Organisms
+export { StatsGrid } from './StatsGrid';
+export type { StatsGridProps, StatItem } from './StatsGrid';
+
+export { DescriptionList } from './DescriptionList';
+export type { DescriptionListProps, DescriptionItem } from './DescriptionList';

package/src/presentation/templates/CrudPageTemplate.tsx

@@ -0,0 +1,69 @@
+import * as React from 'react';
+import { Breadcrumbs, type BreadcrumbItem } from '../organisms/Breadcrumb';
+import { cn } from '../../infrastructure/utils';
+
+export interface CrudPageTemplateProps extends Omit<React.HTMLAttributes<HTMLDivElement>, 'title'> {
+  title: React.ReactNode;
+  description?: React.ReactNode;
+  breadcrumbItems?: BreadcrumbItem[];
+  actions?: React.ReactNode;
+  stats?: React.ReactNode;
+  toolbar?: React.ReactNode;
+  children: React.ReactNode;
+}
+
+export const CrudPageTemplate = React.forwardRef<HTMLDivElement, CrudPageTemplateProps>(
+  (
+    {
+      title,
+      description,
+      breadcrumbItems,
+      actions,
+      stats,
+      toolbar,
+      children,
+      className,
+      ...props
+    },
+    ref
+  ) => {
+    return (
+      <div
+        ref={ref}
+        className={cn('w-full flex flex-col gap-6 p-4 sm:p-6 lg:p-8', className)}
+        {...props}
+      >
+        {/* Breadcrumbs */}
+        {breadcrumbItems && breadcrumbItems.length > 0 && (
+          <div>
+            <Breadcrumbs items={breadcrumbItems} />
+          </div>
+        )}
+
+        {/* Page Header */}
+        <div className="flex flex-col sm:flex-row sm:items-center sm:justify-between gap-4">
+          <div>
+            <h1 className="text-2xl sm:text-3xl font-bold tracking-tight text-foreground">
+              {title}
+            </h1>
+            {description && (
+              <p className="text-sm text-muted-foreground mt-1">{description}</p>
+            )}
+          </div>
+          {actions && <div className="flex items-center gap-2 shrink-0">{actions}</div>}
+        </div>
+
+        {/* Optional Stats Grid */}
+        {stats && <div>{stats}</div>}
+
+        {/* Optional Search / Filter Toolbar */}
+        {toolbar && <div>{toolbar}</div>}
+
+        {/* Main Content (Table / List / Cards) */}
+        <div className="w-full">{children}</div>
+      </div>
+    );
+  }
+);
+
+CrudPageTemplate.displayName = 'CrudPageTemplate';

package/src/presentation/templates/Form.tsx

@@ -1,7 +1,3 @@
-/**
- * Form Template (Template)
- * @description Complete form structure
- */
 
 import { forwardRef, type FormHTMLAttributes, type HTMLAttributes } from 'react';
 import { cn } from '../../infrastructure/utils';

package/src/presentation/templates/List.tsx

@@ -1,7 +1,3 @@
-/**
- * List Template (Template)
- * @description Structured list container
- */
 
 import { forwardRef, type HTMLAttributes } from 'react';
 import { cn } from '../../infrastructure/utils';

package/src/presentation/templates/PageHeader.tsx

@@ -1,7 +1,3 @@
-/**
- * PageHeader Template Component
- * @description Centralized page header with consistent heading styling
- */
 
 import { forwardRef, type HTMLAttributes } from 'react';
 import { type ReactNode } from 'react';

package/src/presentation/templates/PageLayout.tsx

@@ -1,7 +1,3 @@
-/**
- * PageLayout Template Component
- * @description Centralized page layout with consistent padding, max-width, and theme integration
- */
 
 import { forwardRef, type HTMLAttributes } from 'react';
 import { cn } from '../../infrastructure/utils';

package/src/presentation/templates/ProjectSkeleton.tsx

@@ -1,7 +1,3 @@
-/**
- * ProjectSkeleton Template Component
- * @description Loading skeleton for project cards
- */
 
 import { forwardRef, type HTMLAttributes } from 'react';
 import { cn } from '../../infrastructure/utils';

package/src/presentation/templates/ResponsiveContainer.tsx

@@ -1,7 +1,3 @@
-/**
- * ResponsiveContainer Template Component
- * @description Responsive wrapper with mobile/desktop optimizations
- */
 
 import { forwardRef, type HTMLAttributes, type ReactNode } from 'react';
 import { cn } from '../../infrastructure/utils';
@@ -14,58 +10,22 @@ export interface ResponsiveContainerProps
   extends Omit<HTMLAttributes<HTMLDivElement>, 'children'>,
     BaseProps {
   children?: ReactNode;
-  /**
-   * Maximum width on mobile devices
-   * @default 'full'
-   */
   mobileMaxWidth?: ResponsiveSize;
 
-  /**
-   * Maximum width on tablet devices
-   * @default 'lg'
-   */
   tabletMaxWidth?: ResponsiveSize;
 
-  /**
-   * Maximum width on desktop devices
-   * @default 'xl'
-   */
   desktopMaxWidth?: ResponsiveSize;
 
-  /**
-   * Padding on mobile devices
-   * @default true
-   */
   mobilePadding?: boolean;
 
-  /**
-   * Padding on tablet devices
-   * @default true
-   */
   tabletPadding?: boolean;
 
-  /**
-   * Padding on desktop devices
-   * @default true
-   */
   desktopPadding?: boolean;
 
-  /**
-   * Center content horizontally
-   * @default true
-   */
   centered?: boolean;
 
-  /**
-   * Background gradient
-   * @default false
-   */
   gradient?: boolean;
 
-  /**
-   * Minimum height
-   * @default 'auto'
-   */
   minHeight?: 'auto' | 'screen' | 'full';
 }
 
@@ -100,7 +60,6 @@ export const ResponsiveContainer = forwardRef<
   ) => {
     const { currentBreakpoint: breakpoint } = useBreakpoint();
 
-    // Determine current max width based on breakpoint
     const getCurrentMaxWidth = (): string => {
       if (!breakpoint) return maxWidthClasses[mobileMaxWidth];
 
@@ -113,7 +72,6 @@ export const ResponsiveContainer = forwardRef<
       return maxWidthClasses[desktopMaxWidth];
     };
 
-    // Determine current padding based on breakpoint
     const getCurrentPadding = (): string => {
       if (!breakpoint) return mobilePadding ? 'px-4' : '';
 
@@ -126,7 +84,6 @@ export const ResponsiveContainer = forwardRef<
       return desktopPadding ? 'px-8' : '';
     };
 
-    // Determine current py padding based on breakpoint
     const getCurrentPyPadding = (): string => {
       if (!breakpoint) return 'py-8';
 

package/src/presentation/templates/Section.tsx

@@ -1,7 +1,3 @@
-/**
- * Section Template (Template)
- * @description Content section with header
- */
 
 import { forwardRef, type HTMLAttributes } from 'react';
 import { cn } from '../../infrastructure/utils';