@12-apps/ui 1.0.0

package/src/components/data-display/DataGrid/DataGrid.types.ts

@@ -0,0 +1,171 @@
+import type React from 'react';
+
+export type GridSizeMode = 'auto' | 'fixed' | 'fill';
+export type GridDensity = 'compact' | 'comfortable' | 'spacious';
+export type SortDirection = 'asc' | 'desc' | null;
+export type GridSelectionMode = 'none' | 'single' | 'multi';
+export type PaginationMode = 'client' | 'server';
+export type SortMode = 'client' | 'server';
+export type FilterMode = 'client' | 'server';
+export type EditMode = 'none' | 'cell' | 'row';
+
+export interface GridColumn<T = Record<string, unknown>> {
+  /** Unique column id (stable across renders) */
+  id: string;
+  /** Column header label (string or node) */
+  header: React.ReactNode;
+  /** Accessor: key or function to derive value from row */
+  accessor?: keyof T | ((row: T) => unknown);
+  /** Column type influences default formatting and editors */
+  type?: 'text' | 'number' | 'date' | 'datetime' | 'boolean' | 'currency' | 'actions';
+  /** Width hints (px) and min/max constraints */
+  width?: number;
+  minWidth?: number;
+  maxWidth?: number;
+  /** Column is initially hidden */
+  hidden?: boolean;
+  /** Pin to left/right (sticky) */
+  pin?: 'left' | 'right';
+  /** Enable/disable sort, filter, resize, reorder, edit per column */
+  enableSort?: boolean;
+  enableFilter?: boolean;
+  enableResize?: boolean;
+  enableReorder?: boolean;
+  enableEdit?: boolean;
+  /** Custom renderers */
+  cell?: (ctx: { value: unknown; row: T; rowIndex: number; col: GridColumn<T> }) => React.ReactNode;
+  headerCell?: (col: GridColumn<T>) => React.ReactNode;
+  /** Cell editor renderer (edit mode) */
+  editor?: (ctx: {
+    value: unknown;
+    row: T;
+    onChange: (next: unknown) => void;
+    commit: () => void;
+    cancel: () => void;
+  }) => React.ReactNode;
+  /** Column-specific filter UI and predicate (client mode) */
+  filterComponent?: (ctx: {
+    value: unknown;
+    setValue: (next: unknown) => void;
+    col: GridColumn<T>;
+  }) => React.ReactNode;
+  filterPredicate?: (value: unknown, filterValue: unknown, row: T) => boolean;
+  /** Accessibility label for header button controls */
+  ariaLabel?: string;
+}
+
+export interface GridSort {
+  id: string; // column id
+  dir: SortDirection; // asc | desc | null
+}
+
+export interface GridFilter {
+  id: string; // column id
+  value: unknown; // opaque filter value per column type
+}
+
+export interface GridRowExpansion<T = Record<string, unknown>> {
+  /** Render expanded content */
+  render: (row: T, rowIndex: number) => React.ReactNode;
+  /** Controlled expanded row ids */
+  expandedRowIds?: Array<string | number>;
+  /** Uncontrolled defaults */
+  defaultExpandedRowIds?: Array<string | number>;
+  /** Row id equality uses `getRowId` */
+  onChangeExpanded?: (ids: Array<string | number>) => void;
+}
+
+export interface GridSelection {
+  mode?: GridSelectionMode; // none | single | multi
+  selectedRowIds?: Array<string | number>; // controlled
+  defaultSelectedRowIds?: Array<string | number>;
+  onChangeSelected?: (ids: Array<string | number>) => void;
+}
+
+export interface GridPagination {
+  mode?: PaginationMode; // client | server
+  pageIndex?: number; // controlled, 0-based
+  pageSize?: number; // rows per page
+  rowCount?: number; // total rows (server)
+  onChangePage?: (nextIndex: number) => void;
+  onChangePageSize?: (nextSize: number) => void;
+}
+
+export interface GridSorting {
+  mode?: SortMode; // client | server
+  sortBy?: GridSort[]; // controlled
+  defaultSortBy?: GridSort[];
+  onChangeSortBy?: (next: GridSort[]) => void;
+}
+
+export interface GridFiltering {
+  mode?: FilterMode; // client | server
+  filters?: GridFilter[]; // controlled
+  defaultFilters?: GridFilter[];
+  onChangeFilters?: (next: GridFilter[]) => void;
+}
+
+export interface GridEditing<T = Record<string, unknown>> {
+  mode?: EditMode; // none | cell | row
+  /** Called when a cell (or row) attempts to commit a value */
+  onEditCommit?: (ctx: {
+    rowId: string | number;
+    colId: string;
+    value: unknown;
+    row: T;
+  }) => Promise<void> | void;
+  /** Validation error message per cell (controlled) */
+  getCellError?: (rowId: string | number, colId: string) => string | undefined;
+}
+
+export interface DataGridProps<T = Record<string, unknown>> extends React.HTMLAttributes<HTMLElement> {
+  /** Dataset (client mode uses this array; server mode renders current page) */
+  rows: T[];
+  /** Stable row id accessor */
+  getRowId?: (row: T, index: number) => string | number;
+  /** Column definitions */
+  columns: GridColumn<T>[];
+
+  /** Sizing, density, and layout */
+  sizeMode?: GridSizeMode; // auto | fixed | fill
+  density?: GridDensity; // compact | comfortable | spacious
+  rowHeight?: number; // default row height (px)
+  headerHeight?: number; // default header height (px)
+  footerHeight?: number; // optional
+
+  /** Interaction features */
+  selection?: GridSelection;
+  pagination?: GridPagination;
+  sorting?: GridSorting;
+  filtering?: GridFiltering;
+  expansion?: GridRowExpansion<T>;
+  editing?: GridEditing<T>;
+
+  /** Virtualization toggles */
+  virtualizeRows?: boolean; // default: true for large datasets
+  virtualizeColumns?: boolean; // optional; default: false
+
+  /** Sticky headers/footers and pinned columns */
+  stickyHeader?: boolean;
+  stickyFooter?: boolean;
+
+  /** Empty/loading/error states */
+  loading?: boolean;
+  error?: React.ReactNode; // message or node for error state
+  emptyState?: React.ReactNode; // custom empty component
+
+  /** Server-fetch hooks (used by server modes) */
+  onRequestData?: (params: {
+    pageIndex?: number;
+    pageSize?: number;
+    sortBy?: GridSort[];
+    filters?: GridFilter[];
+  }) => void;
+
+  /** Accessibility */
+  ariaLabel?: string; // label for entire grid region
+  ariaDescription?: string;
+
+  /** Testing id passthrough */
+  'data-testid'?: string;
+}

package/src/components/data-display/DataGrid/index.ts

@@ -0,0 +1,21 @@
+export { DataGrid } from './DataGrid';
+export type {
+  DataGridProps,
+  EditMode,
+  FilterMode,
+  GridColumn,
+  GridDensity,
+  GridEditing,
+  GridFilter,
+  GridFiltering,
+  GridPagination,
+  GridRowExpansion,
+  GridSelection,
+  GridSelectionMode,
+  GridSizeMode,
+  GridSort,
+  GridSorting,
+  PaginationMode,
+  SortDirection,
+  SortMode,
+} from './DataGrid.types';

package/src/components/data-display/DateTimeDisplay/DateTimeDisplay.tsx

@@ -0,0 +1,197 @@
+import { Box, Tooltip, Typography } from '@mui/material';
+import { forwardRef, useMemo } from 'react';
+
+import type { DateTimeDisplayProps } from './DateTimeDisplay.types';
+
+/**
+ * Format a date for display
+ */
+function formatDatePart(date: Date, format: 'short' | 'long' | 'numeric'): string {
+  const options: Intl.DateTimeFormatOptions = {
+    year: 'numeric',
+    month: format === 'numeric' ? '2-digit' : format === 'short' ? 'short' : 'long',
+    day: format === 'numeric' ? '2-digit' : 'numeric',
+  };
+  return date.toLocaleDateString(undefined, options);
+}
+
+/**
+ * Format time for display
+ */
+function formatTimePart(
+  date: Date,
+  timeFormat: '12h' | '24h',
+  showTimezone: boolean,
+): string {
+  const options: Intl.DateTimeFormatOptions = {
+    hour: 'numeric',
+    minute: '2-digit',
+    hour12: timeFormat === '12h',
+    ...(showTimezone && { timeZoneName: 'short' }),
+  };
+  return date.toLocaleTimeString(undefined, options);
+}
+
+/**
+ * Get font sizes based on size prop
+ */
+function getFontSizes(size: 'small' | 'medium' | 'large') {
+  switch (size) {
+    case 'small':
+      return { date: '0.75rem', time: '0.65rem' };
+    case 'large':
+      return { date: '1rem', time: '0.875rem' };
+    case 'medium':
+    default:
+      return { date: '0.875rem', time: '0.75rem' };
+  }
+}
+
+/**
+ * DateTimeDisplay component - displays date and time in a stacked format
+ * with date on one line and time on another.
+ */
+export const DateTimeDisplay = forwardRef<HTMLSpanElement, DateTimeDisplayProps>(
+  (
+    {
+      date,
+      dateFormat = 'short',
+      timeFormat = '12h',
+      showTimezone = false,
+      size = 'medium',
+      showTooltip = true,
+      tooltipContent,
+      sx,
+      dataTestId,
+    },
+    ref,
+  ) => {
+    const dateObj = useMemo(() => {
+      if (!date) return null;
+      return date instanceof Date ? date : new Date(date);
+    }, [date]);
+
+    // Auto-detect if time is midnight (no meaningful time)
+    const hasTime = useMemo(() => {
+      if (!dateObj || isNaN(dateObj.getTime())) return false;
+      // If time is midnight (ignoring milliseconds), assume no time was provided
+      const hours = dateObj.getHours();
+      const minutes = dateObj.getMinutes();
+      const seconds = dateObj.getSeconds();
+      // Check if time is midnight (00:00:00) - ignore milliseconds
+      const isMidnight = hours === 0 && minutes === 0 && seconds === 0;
+      return !isMidnight;
+    }, [dateObj]);
+
+
+    const formattedDate = useMemo(() => {
+      if (!dateObj || isNaN(dateObj.getTime())) return null;
+      return formatDatePart(dateObj, dateFormat);
+    }, [dateObj, dateFormat]);
+
+    const formattedTime = useMemo(() => {
+      if (!dateObj || isNaN(dateObj.getTime()) || !hasTime) return null;
+      return formatTimePart(dateObj, timeFormat, showTimezone);
+    }, [dateObj, hasTime, timeFormat, showTimezone]);
+
+    const fullDateTime = useMemo(() => {
+      if (!dateObj || isNaN(dateObj.getTime())) return null;
+
+      // If no time to show, only show date in tooltip
+      if (!hasTime) {
+        return dateObj.toLocaleDateString(undefined, {
+          weekday: 'long',
+          year: 'numeric',
+          month: 'long',
+          day: 'numeric',
+        });
+      }
+
+      return dateObj.toLocaleString(undefined, {
+        weekday: 'long',
+        year: 'numeric',
+        month: 'long',
+        day: 'numeric',
+        hour: 'numeric',
+        minute: '2-digit',
+        second: '2-digit',
+        timeZoneName: 'short',
+      });
+    }, [dateObj, hasTime]);
+
+    const fontSizes = getFontSizes(size);
+
+    // Handle invalid or missing date
+    if (!dateObj || isNaN(dateObj.getTime())) {
+      return (
+        <Box
+          component="span"
+          ref={ref}
+          data-testid={dataTestId}
+          sx={{ color: 'text.disabled', ...sx }}
+        >
+          <Typography variant="caption">-</Typography>
+        </Box>
+      );
+    }
+
+    const content = (
+      <Box
+        component="span"
+        ref={ref}
+        data-testid={dataTestId}
+        sx={{
+          display: 'inline-flex',
+          flexDirection: 'column',
+          lineHeight: 1.3,
+          cursor: showTooltip ? 'help' : 'default',
+          ...sx,
+        }}
+      >
+        <Typography
+          component="span"
+          sx={{
+            fontWeight: 500,
+            fontSize: fontSizes.date,
+          }}
+          data-testid={dataTestId ? `${dataTestId}-date` : undefined}
+        >
+          {formattedDate}
+        </Typography>
+        {formattedTime && (
+          <Typography
+            component="span"
+            sx={{
+              fontSize: fontSizes.time,
+              color: 'text.secondary',
+            }}
+            data-testid={dataTestId ? `${dataTestId}-time` : undefined}
+          >
+            {formattedTime}
+          </Typography>
+        )}
+      </Box>
+    );
+
+    if (!showTooltip) {
+      return content;
+    }
+
+    return (
+      <Tooltip
+        title={tooltipContent || fullDateTime}
+        arrow
+        placement="top"
+        slotProps={{
+          tooltip: {
+            sx: { px: 2, py: 1 },
+          },
+        }}
+      >
+        {content}
+      </Tooltip>
+    );
+  },
+);
+
+DateTimeDisplay.displayName = 'DateTimeDisplay';

package/src/components/data-display/DateTimeDisplay/DateTimeDisplay.types.ts

@@ -0,0 +1,46 @@
+import type { SxProps, Theme } from '@mui/material';
+
+export interface DateTimeDisplayProps {
+  /**
+   * The date to display. Can be a Date object or ISO string.
+   * Time is auto-detected: if time is midnight (00:00:00), only date is shown.
+   */
+  date: Date | string;
+  /**
+   * Date format for the date line
+   * @default 'short' - "Dec 16, 2024"
+   */
+  dateFormat?: 'short' | 'long' | 'numeric';
+  /**
+   * Time format
+   * @default '12h' - "3:45 PM"
+   */
+  timeFormat?: '12h' | '24h';
+  /**
+   * Whether to show timezone abbreviation in time
+   * @default false
+   */
+  showTimezone?: boolean;
+  /**
+   * Size variant
+   * @default 'medium'
+   */
+  size?: 'small' | 'medium' | 'large';
+  /**
+   * Whether to show a tooltip with full date/time
+   * @default true
+   */
+  showTooltip?: boolean;
+  /**
+   * Custom tooltip content
+   */
+  tooltipContent?: React.ReactNode;
+  /**
+   * Additional styles
+   */
+  sx?: SxProps<Theme>;
+  /**
+   * Test ID for testing
+   */
+  dataTestId?: string;
+}

package/src/components/data-display/DateTimeDisplay/index.ts

@@ -0,0 +1,2 @@
+export { DateTimeDisplay } from './DateTimeDisplay';
+export type { DateTimeDisplayProps } from './DateTimeDisplay.types';

package/src/components/data-display/DescriptionItem/DescriptionItem.md

@@ -0,0 +1,226 @@
+# DescriptionItem
+
+A label-value pair component for displaying read-only information in a consistent vertical layout.
+
+## Features
+
+- **Two Orientations**: Vertical (label above value) or horizontal (label beside value)
+- **Clear Visual Hierarchy**: Label displayed with distinct styling
+- **Flexible Values**: Supports text, numbers, or any React node as the value
+- **Uppercase Labels**: Labels are automatically styled in uppercase for consistency
+- **Custom Content**: Can render custom components like chips, buttons, or complex layouts
+- **Responsive**: Works well in grid or stack layouts
+- **Accessible**: Proper semantic HTML with data-testid support
+
+## Usage
+
+### Basic Usage
+
+```tsx
+import { DescriptionItem } from '@app-services-monitoring/ui';
+
+function MyComponent() {
+  return (
+    <DescriptionItem
+      label="Incident ID"
+      value="INC-12345"
+    />
+  );
+}
+```
+
+### With Number Value
+
+```tsx
+<DescriptionItem
+  label="Services Affected"
+  value={42}
+/>
+```
+
+### With Custom Component
+
+```tsx
+<DescriptionItem
+  label="Status"
+  value={<Chip label="Active" color="success" />}
+/>
+```
+
+### Horizontal Orientation
+
+```tsx
+<DescriptionItem
+  label="Name"
+  value="John Doe"
+  orientation="horizontal"
+/>
+```
+
+### Vertical Orientation (Default)
+
+```tsx
+<DescriptionItem
+  label="Name"
+  value="John Doe"
+  orientation="vertical"
+/>
+```
+
+### Copyable Value
+
+```tsx
+<DescriptionItem
+  label="Incident ID"
+  value={
+    <Box sx={{ display: 'flex', alignItems: 'center', gap: 0.5 }}>
+      <Text variant="body" size="sm" weight="semibold">
+        INC-12345
+      </Text>
+      <Button
+        variant="ghost"
+        size="sm"
+        onClick={() => navigator.clipboard.writeText('INC-12345')}
+        aria-label="Copy incident ID"
+      >
+        <ContentCopyIcon sx={{ fontSize: 16 }} />
+      </Button>
+    </Box>
+  }
+/>
+```
+
+### Grid Layout
+
+```tsx
+<Box
+  sx={{
+    display: 'grid',
+    gridTemplateColumns: { xs: '1fr', sm: 'repeat(2, 1fr)', md: 'repeat(4, 1fr)' },
+    gap: 3,
+  }}
+>
+  <DescriptionItem label="Incident ID" value="INC-12345" />
+  <DescriptionItem label="Started" value="2 hours ago" />
+  <DescriptionItem label="Duration" value="Ongoing" />
+  <DescriptionItem label="Services Affected" value={5} />
+</Box>
+```
+
+### Vertical Stack (Vertical Orientation)
+
+```tsx
+<Stack spacing={3}>
+  <DescriptionItem label="Name" value="John Doe" />
+  <DescriptionItem label="Email" value="john.doe@example.com" />
+  <DescriptionItem label="Department" value="Engineering" />
+</Stack>
+```
+
+### List Layout (Horizontal Orientation)
+
+```tsx
+<Stack spacing={2}>
+  <DescriptionItem label="Name" value="John Doe" orientation="horizontal" />
+  <DescriptionItem label="Email" value="john.doe@example.com" orientation="horizontal" />
+  <DescriptionItem label="Department" value="Engineering" orientation="horizontal" />
+  <DescriptionItem label="Role" value={<Chip label="Admin" />} orientation="horizontal" />
+</Stack>
+```
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `label` | `string` | Required | The label text to display |
+| `value` | `ReactNode` | Required | The value to display - can be text, number, or any React node |
+| `orientation` | `'vertical' \| 'horizontal'` | `'vertical'` | Layout orientation: vertical (label above) or horizontal (label beside) |
+| `className` | `string` | - | Optional CSS class name |
+| `data-testid` | `string` | `'description-item'` | Test ID for testing purposes |
+
+## Styling
+
+The component uses the following styling:
+- **Label**: Uppercase text, secondary color, extra-small size
+- **Value**: Semibold text for string/number values, small size
+- **Layout**:
+  - Vertical: Flex column layout with label on top, 0.25rem gap
+  - Horizontal: Flex row layout with label beside value, 1rem gap, center-aligned
+- **Label Width**: In horizontal mode, label has `fit-content` width and doesn't shrink
+
+## Value Rendering
+
+The component intelligently renders values:
+- **String/Number**: Automatically wrapped in `<Text>` component with semibold weight
+- **React Node**: Rendered as-is, allowing full customization
+
+## Common Patterns
+
+### Detail View
+
+```tsx
+<Box sx={{ display: 'grid', gridTemplateColumns: 'repeat(4, 1fr)', gap: 3 }}>
+  <DescriptionItem label="Order ID" value="ORD-001" />
+  <DescriptionItem label="Customer" value="Acme Corp" />
+  <DescriptionItem label="Total" value="$1,234.56" />
+  <DescriptionItem label="Status" value={<Chip label="Completed" />} />
+</Box>
+```
+
+### Profile Information
+
+```tsx
+<Stack spacing={3}>
+  <DescriptionItem label="Full Name" value="Jane Smith" />
+  <DescriptionItem label="Position" value="Senior Engineer" />
+  <DescriptionItem label="Department" value="Platform Engineering" />
+  <DescriptionItem label="Location" value="San Francisco, CA" />
+</Stack>
+```
+
+### Incident Metadata
+
+```tsx
+<Box sx={{ display: 'grid', gridTemplateColumns: 'repeat(4, 1fr)', gap: 3 }}>
+  <DescriptionItem
+    label="Incident ID"
+    value={
+      <Box sx={{ display: 'flex', alignItems: 'center', gap: 0.5 }}>
+        <Text>INC-12345</Text>
+        <Button variant="ghost" size="sm"><CopyIcon /></Button>
+      </Box>
+    }
+  />
+  <DescriptionItem label="Started" value="2 hours ago" />
+  <DescriptionItem label="Duration" value="Ongoing" />
+  <DescriptionItem label="Services" value={3} />
+</Box>
+```
+
+## Accessibility
+
+- Semantic HTML structure
+- Proper text hierarchy
+- Support for `data-testid` on container, label, and value elements
+- Works with screen readers
+- Supports `aria-label` on custom content
+
+## Best Practices
+
+1. **Use Clear Labels**: Keep labels concise and descriptive
+2. **Consistent Formatting**: Use consistent value formatting across related items
+3. **Choose Right Orientation**:
+   - Use **vertical** for grid layouts with multiple columns
+   - Use **horizontal** for list/stack layouts or narrow containers
+4. **Grid Layouts**: Use CSS Grid with vertical orientation for multi-column displays
+5. **List Layouts**: Use Stack with horizontal orientation for single-column lists
+6. **Empty Values**: Show "N/A" or "-" for missing/empty values
+7. **Interactive Elements**: When adding buttons/links, ensure proper accessibility
+8. **Custom Components**: Use appropriate components (Chip, Badge) for status indicators
+
+## Related Components
+
+- **Text**: For custom value rendering
+- **Chip**: For status/tag values
+- **Badge**: For count indicators
+- **Button**: For interactive actions in values