@papernote/ui 1.10.19 → 1.10.21

package/src/components/PivotTable.tsx

@@ -0,0 +1,422 @@
+import { useMemo } from 'react';
+
+/**
+ * PivotTable - Transforms flat data into a cross-tabulation table
+ *
+ * Takes data like:
+ *   [{ principal: 'A', month: 1, amount: 100 }, { principal: 'A', month: 2, amount: 200 }, ...]
+ *
+ * And displays it as:
+ *   | Principal | January | February | ... | Total | Average |
+ *   |-----------|---------|----------|-----|-------|---------|
+ *   | A         | $100    | $200     | ... | $300  | $150    |
+ */
+
+export interface PivotTableProps<T = Record<string, unknown>> {
+  /** Array of data rows to pivot */
+  data: T[];
+  /** Field name to use for row labels */
+  rowField: string;
+  /** Field name to use for column headers */
+  columnField: string;
+  /** Field name containing the values to display */
+  valueField: string;
+  /** Optional map of column field values to display labels */
+  columnLabels?: Record<string | number, string>;
+  /** Optional row label header text */
+  rowLabel?: string;
+  /** Format function for values */
+  formatValue?: (value: number | null) => string;
+  /** Show row totals column */
+  showRowTotals?: boolean;
+  /** Show row averages column */
+  showRowAverages?: boolean;
+  /** Show column totals row */
+  showColumnTotals?: boolean;
+  /** Custom className */
+  className?: string;
+  /** Sort columns by label or value */
+  sortColumns?: 'label' | 'value' | 'none';
+  /** Sort rows alphabetically */
+  sortRows?: boolean;
+  /** Empty cell placeholder */
+  emptyValue?: string;
+}
+
+interface PivotedData {
+  rowLabels: string[];
+  columnLabels: string[];
+  columnKeys: (string | number)[];
+  matrix: (number | null)[][];
+  rowTotals: number[];
+  rowAverages: number[];
+  columnTotals: number[];
+  grandTotal: number;
+}
+
+/**
+ * Default currency formatter
+ */
+const defaultFormatValue = (value: number | null): string => {
+  if (value === null || value === undefined) return '-';
+  return new Intl.NumberFormat('en-US', {
+    style: 'currency',
+    currency: 'USD',
+    minimumFractionDigits: 2,
+    maximumFractionDigits: 2,
+  }).format(value);
+};
+
+/**
+ * Transform flat data into pivoted structure
+ */
+function pivotData<T>(
+  data: T[],
+  rowField: string,
+  columnField: string,
+  valueField: string,
+  columnLabels?: Record<string | number, string>,
+  sortColumns?: 'label' | 'value' | 'none',
+  sortRows?: boolean
+): PivotedData {
+  // Extract unique row and column values
+  const rowSet = new Set<string>();
+  const columnSet = new Set<string | number>();
+  const valueMap = new Map<string, number>();
+
+  for (const row of data) {
+    const rowValue = String((row as Record<string, unknown>)[rowField] ?? '');
+    const colValue = (row as Record<string, unknown>)[columnField];
+    const val = (row as Record<string, unknown>)[valueField];
+
+    if (rowValue) rowSet.add(rowValue);
+    if (colValue !== undefined && colValue !== null) columnSet.add(colValue as string | number);
+
+    // Create composite key for the cell
+    const key = `${rowValue}|||${colValue}`;
+    const numVal = typeof val === 'number' ? val : parseFloat(String(val)) || 0;
+    valueMap.set(key, (valueMap.get(key) || 0) + numVal);
+  }
+
+  // Sort row labels
+  let rowLabels = Array.from(rowSet);
+  if (sortRows !== false) {
+    rowLabels.sort((a, b) => a.localeCompare(b));
+  }
+
+  // Sort column keys
+  let columnKeys = Array.from(columnSet);
+  if (sortColumns === 'label') {
+    columnKeys.sort((a, b) => {
+      const labelA = columnLabels?.[a] ?? String(a);
+      const labelB = columnLabels?.[b] ?? String(b);
+      return labelA.localeCompare(labelB);
+    });
+  } else if (sortColumns !== 'none') {
+    // Default: sort by value (numeric if possible)
+    columnKeys.sort((a, b) => {
+      const numA = typeof a === 'number' ? a : parseFloat(String(a));
+      const numB = typeof b === 'number' ? b : parseFloat(String(b));
+      if (!isNaN(numA) && !isNaN(numB)) return numA - numB;
+      return String(a).localeCompare(String(b));
+    });
+  }
+
+  // Build column labels array
+  const colLabels = columnKeys.map((k) => columnLabels?.[k] ?? String(k));
+
+  // Build the matrix
+  const matrix: (number | null)[][] = [];
+  const rowTotals: number[] = [];
+  const rowAverages: number[] = [];
+  const columnTotals: number[] = new Array(columnKeys.length).fill(0);
+  let grandTotal = 0;
+
+  for (const rowLabel of rowLabels) {
+    const rowData: (number | null)[] = [];
+    let rowSum = 0;
+    let rowCount = 0;
+
+    for (let colIdx = 0; colIdx < columnKeys.length; colIdx++) {
+      const colKey = columnKeys[colIdx];
+      const key = `${rowLabel}|||${colKey}`;
+      const value = valueMap.get(key) ?? null;
+      rowData.push(value);
+
+      if (value !== null) {
+        rowSum += value;
+        rowCount++;
+        columnTotals[colIdx] += value;
+        grandTotal += value;
+      }
+    }
+
+    matrix.push(rowData);
+    rowTotals.push(rowSum);
+    rowAverages.push(rowCount > 0 ? rowSum / rowCount : 0);
+  }
+
+  return {
+    rowLabels,
+    columnLabels: colLabels,
+    columnKeys,
+    matrix,
+    rowTotals,
+    rowAverages,
+    columnTotals,
+    grandTotal,
+  };
+}
+
+/**
+ * PivotTable Component
+ */
+export function PivotTable<T = Record<string, unknown>>({
+  data,
+  rowField,
+  columnField,
+  valueField,
+  columnLabels,
+  rowLabel = '',
+  formatValue = defaultFormatValue,
+  showRowTotals = true,
+  showRowAverages = false,
+  showColumnTotals = true,
+  className = '',
+  sortColumns = 'value',
+  sortRows = true,
+  emptyValue = '-',
+}: PivotTableProps<T>) {
+  const pivoted = useMemo(
+    () => pivotData(data, rowField, columnField, valueField, columnLabels, sortColumns, sortRows),
+    [data, rowField, columnField, valueField, columnLabels, sortColumns, sortRows]
+  );
+
+  const formatCell = (value: number | null): string => {
+    if (value === null || value === undefined) return emptyValue;
+    return formatValue(value);
+  };
+
+  // Calculate column totals row average
+  const columnTotalsAverage =
+    pivoted.columnTotals.length > 0
+      ? pivoted.columnTotals.reduce((a, b) => a + b, 0) / pivoted.columnTotals.length
+      : 0;
+
+  return (
+    <div className={`pivot-table-container ${className}`} style={{ overflowX: 'auto' }}>
+      <table
+        style={{
+          width: '100%',
+          borderCollapse: 'collapse',
+          fontSize: '14px',
+          fontFamily: 'inherit',
+        }}
+      >
+        <thead>
+          <tr style={{ backgroundColor: '#f8fafc', borderBottom: '2px solid #e2e8f0' }}>
+            {/* Row label header */}
+            <th
+              style={{
+                padding: '12px 16px',
+                textAlign: 'left',
+                fontWeight: 600,
+                color: '#334155',
+                position: 'sticky',
+                left: 0,
+                backgroundColor: '#f8fafc',
+                zIndex: 1,
+                minWidth: '150px',
+              }}
+            >
+              {rowLabel}
+            </th>
+            {/* Column headers */}
+            {pivoted.columnLabels.map((label, idx) => (
+              <th
+                key={idx}
+                style={{
+                  padding: '12px 16px',
+                  textAlign: 'right',
+                  fontWeight: 600,
+                  color: '#334155',
+                  minWidth: '100px',
+                  whiteSpace: 'nowrap',
+                }}
+              >
+                {label}
+              </th>
+            ))}
+            {/* Total header */}
+            {showRowTotals && (
+              <th
+                style={{
+                  padding: '12px 16px',
+                  textAlign: 'right',
+                  fontWeight: 700,
+                  color: '#1e40af',
+                  backgroundColor: '#eff6ff',
+                  minWidth: '100px',
+                }}
+              >
+                Total
+              </th>
+            )}
+            {/* Average header */}
+            {showRowAverages && (
+              <th
+                style={{
+                  padding: '12px 16px',
+                  textAlign: 'right',
+                  fontWeight: 700,
+                  color: '#166534',
+                  backgroundColor: '#f0fdf4',
+                  minWidth: '100px',
+                }}
+              >
+                Average
+              </th>
+            )}
+          </tr>
+        </thead>
+        <tbody>
+          {pivoted.rowLabels.map((rowLabel, rowIdx) => (
+            <tr
+              key={rowIdx}
+              style={{
+                borderBottom: '1px solid #e2e8f0',
+                backgroundColor: rowIdx % 2 === 0 ? '#ffffff' : '#f8fafc',
+              }}
+            >
+              {/* Row label */}
+              <td
+                style={{
+                  padding: '10px 16px',
+                  fontWeight: 500,
+                  color: '#1e293b',
+                  position: 'sticky',
+                  left: 0,
+                  backgroundColor: rowIdx % 2 === 0 ? '#ffffff' : '#f8fafc',
+                  zIndex: 1,
+                }}
+              >
+                {rowLabel}
+              </td>
+              {/* Data cells */}
+              {pivoted.matrix[rowIdx].map((value, colIdx) => (
+                <td
+                  key={colIdx}
+                  style={{
+                    padding: '10px 16px',
+                    textAlign: 'right',
+                    color: value === null ? '#94a3b8' : '#334155',
+                    fontVariantNumeric: 'tabular-nums',
+                  }}
+                >
+                  {formatCell(value)}
+                </td>
+              ))}
+              {/* Row total */}
+              {showRowTotals && (
+                <td
+                  style={{
+                    padding: '10px 16px',
+                    textAlign: 'right',
+                    fontWeight: 600,
+                    color: '#1e40af',
+                    backgroundColor: '#eff6ff',
+                    fontVariantNumeric: 'tabular-nums',
+                  }}
+                >
+                  {formatCell(pivoted.rowTotals[rowIdx])}
+                </td>
+              )}
+              {/* Row average */}
+              {showRowAverages && (
+                <td
+                  style={{
+                    padding: '10px 16px',
+                    textAlign: 'right',
+                    fontWeight: 600,
+                    color: '#166534',
+                    backgroundColor: '#f0fdf4',
+                    fontVariantNumeric: 'tabular-nums',
+                  }}
+                >
+                  {formatCell(pivoted.rowAverages[rowIdx])}
+                </td>
+              )}
+            </tr>
+          ))}
+          {/* Column totals row */}
+          {showColumnTotals && (
+            <tr
+              style={{
+                borderTop: '2px solid #e2e8f0',
+                backgroundColor: '#f1f5f9',
+                fontWeight: 600,
+              }}
+            >
+              <td
+                style={{
+                  padding: '12px 16px',
+                  fontWeight: 700,
+                  color: '#1e293b',
+                  position: 'sticky',
+                  left: 0,
+                  backgroundColor: '#f1f5f9',
+                  zIndex: 1,
+                }}
+              >
+                Total
+              </td>
+              {pivoted.columnTotals.map((total, idx) => (
+                <td
+                  key={idx}
+                  style={{
+                    padding: '12px 16px',
+                    textAlign: 'right',
+                    color: '#1e293b',
+                    fontVariantNumeric: 'tabular-nums',
+                  }}
+                >
+                  {formatCell(total)}
+                </td>
+              ))}
+              {showRowTotals && (
+                <td
+                  style={{
+                    padding: '12px 16px',
+                    textAlign: 'right',
+                    fontWeight: 700,
+                    color: '#1e40af',
+                    backgroundColor: '#dbeafe',
+                    fontVariantNumeric: 'tabular-nums',
+                  }}
+                >
+                  {formatCell(pivoted.grandTotal)}
+                </td>
+              )}
+              {showRowAverages && (
+                <td
+                  style={{
+                    padding: '12px 16px',
+                    textAlign: 'right',
+                    fontWeight: 700,
+                    color: '#166534',
+                    backgroundColor: '#dcfce7',
+                    fontVariantNumeric: 'tabular-nums',
+                  }}
+                >
+                  {formatCell(columnTotalsAverage)}
+                </td>
+              )}
+            </tr>
+          )}
+        </tbody>
+      </table>
+    </div>
+  );
+}
+
+export default PivotTable;

package/src/components/StatusBadge.tsx

@@ -1,8 +1,8 @@
 
-import { CheckCircle, Clock, AlertCircle, XCircle } from 'lucide-react';
+import { CheckCircle, Clock, AlertCircle, XCircle, Info } from 'lucide-react';
 
 export interface StatusBadgeProps {
-  status: 'paid' | 'pending' | 'overdue' | 'cancelled' | 'success' | 'warning' | 'error' | 'info';
+  status: 'paid' | 'pending' | 'overdue' | 'cancelled' | 'success' | 'warning' | 'caution' | 'error' | 'info';
   label?: string;
   size?: 'sm' | 'md' | 'lg';
   showIcon?: boolean;
@@ -29,6 +29,11 @@ const statusConfig = {
     defaultLabel: 'Warning',
     className: 'bg-warning-100 text-warning-800',
   },
+  caution: {
+    icon: Info,
+    defaultLabel: 'Caution',
+    className: 'bg-warning-100 text-warning-700',
+  },
   overdue: {
     icon: AlertCircle,
     defaultLabel: 'Overdue',

package/src/components/Text.stories.tsx

@@ -16,7 +16,7 @@ Text component for consistent typography across the application.
 - **Semantic elements**: Render as p, span, div, h1-h6, or label
 - **Size scale**: xs, sm, base, lg, xl, 2xl
 - **Weight options**: normal, medium, semibold, bold
-- **Color variants**: primary, secondary, muted, accent, error, success, warning
+- **Color variants**: primary, secondary, muted, accent, error, success, warning, caution
 - **Text alignment**: left, center, right
 - **Truncation**: Single line truncate or multi-line clamp (1-6 lines)
 - **Transform**: uppercase, lowercase, capitalize
@@ -61,7 +61,7 @@ import { Text } from 'notebook-ui';
     },
     color: {
       control: 'select',
-      options: ['primary', 'secondary', 'muted', 'accent', 'error', 'success', 'warning'],
+      options: ['primary', 'secondary', 'muted', 'accent', 'error', 'success', 'warning', 'caution'],
       description: 'Text color',
     },
     align: {
@@ -120,7 +120,9 @@ export const Weights: Story = {
 };
 
 /**
- * All available color variants including the new `warning` color.
+ * All available color variants including `warning` and `caution` colors.
+ * - **warning**: Urgent attention needed (brighter amber)
+ * - **caution**: Informational, exploratory states like sandbox/demo mode (darker, subdued amber)
  */
 export const Colors: Story = {
   render: () => (
@@ -130,15 +132,16 @@ export const Colors: Story = {
       <Text color="muted">Muted - Subdued text</Text>
       <Text color="accent">Accent - Branded color</Text>
       <Text color="success">Success - Positive feedback</Text>
-      <Text color="warning">Warning - Caution messages</Text>
+      <Text color="warning">Warning - Urgent attention</Text>
+      <Text color="caution">Caution - Informational, exploratory</Text>
       <Text color="error">Error - Error messages</Text>
     </Stack>
   ),
 };
 
 /**
- * The warning color is useful for displaying caution messages,
- * threshold alerts, or status indicators that need attention.
+ * The warning color is useful for urgent alerts, threshold warnings,
+ * or status indicators that need immediate attention.
  */
 export const WarningColor: Story = {
   render: () => (
@@ -156,6 +159,27 @@ export const WarningColor: Story = {
   ),
 };
 
+/**
+ * The caution color is for informational states that need context but aren't alarming.
+ * Use for demo/sandbox modes, wash sale notices, or exploratory features.
+ * It's calmer than warning - inviting users to explore safely.
+ */
+export const CautionColor: Story = {
+  render: () => (
+    <Stack spacing="md">
+      <Text color="caution" size="lg" weight="semibold">
+        Demo Mode: Changes will not be saved
+      </Text>
+      <Text color="caution">
+        This is a sandbox environment for testing
+      </Text>
+      <Text color="caution" size="sm">
+        Wash sale: Cost basis adjusted for tax purposes
+      </Text>
+    </Stack>
+  ),
+};
+
 export const Alignment: Story = {
   render: () => (
     <Stack spacing="sm" style={{ width: '300px' }}>

package/src/components/Text.tsx

@@ -23,7 +23,7 @@ export interface TextProps extends Omit<React.HTMLAttributes<HTMLElement>, 'colo
   /** Weight variant */
   weight?: 'normal' | 'medium' | 'semibold' | 'bold';
   /** Color variant */
-  color?: 'primary' | 'secondary' | 'muted' | 'accent' | 'error' | 'success' | 'warning';
+  color?: 'primary' | 'secondary' | 'muted' | 'accent' | 'error' | 'success' | 'warning' | 'caution';
   /** Text alignment */
   align?: 'left' | 'center' | 'right';
   /** Truncate text with ellipsis (single line) */
@@ -54,9 +54,10 @@ export interface TextProps extends Omit<React.HTMLAttributes<HTMLElement>, 'colo
  * <Text size="lg" weight="semibold" color="primary">
  *   Hello World
  * </Text>
- * 
+ *
  * <Text color="warning">Warning message</Text>
- * 
+ * <Text color="caution">Caution message (informational, not alarming)</Text>
+ *
  * // With ref
  * const textRef = useRef<HTMLParagraphElement>(null);
  * <Text ref={textRef}>Measurable text</Text>
@@ -130,6 +131,7 @@ export const Text = forwardRef<HTMLElement, TextProps>(({
     error: 'text-error-600',
     success: 'text-success-600',
     warning: 'text-warning-600',
+    caution: 'text-warning-700',
   };
 
   const alignClasses = {

package/src/components/index.ts

@@ -404,6 +404,10 @@ export type {
   FrozenRowMode,
 } from './DataGrid';
 
+// PivotTable (cross-tabulation display)
+export { default as PivotTable } from './PivotTable';
+export type { PivotTableProps } from './PivotTable';
+
 export { default as SwipeActions } from './SwipeActions';
 export type { SwipeActionsProps, SwipeAction } from './SwipeActions';