@polderlabs/bizar 6.3.0 → 7.0.0

package/bizar-dash/src/web/ui/data/DataTable.tsx

@@ -0,0 +1,216 @@
+/*
+ * DataTable.tsx — Sortable data table (Wave 2B).
+ *
+ * The most complex data component. Sticky header, click-to-sort columns,
+ * controlled/uncontrolled sort state, custom cell renderers, empty and
+ * loading states, optional compact row padding. Sort logic uses the column's
+ * `accessor` (or falls back to identity) and handles string vs numeric
+ * comparison correctly. Click-to-select rows via onRowClick. The table is a
+ * two-element scroll container so the sticky header stays pinned even on
+ * vertically-long data sets inside a constrained card.
+ */
+
+import {
+  useMemo,
+  useState,
+  type CSSProperties,
+  type ReactNode,
+} from 'react';
+import { ArrowDown, ArrowUp, ChevronsUpDown } from 'lucide-react';
+import { cx } from '../utils/cx';
+
+export type DataTableColumn<T> = {
+  key: string;
+  header: string;
+  width?: string | number;
+  align?: 'left' | 'right' | 'center';
+  sortable?: boolean;
+  render?: (row: T) => ReactNode;
+  accessor?: (row: T) => string | number;
+};
+
+export type DataTableSort = {
+  key: string;
+  direction: 'asc' | 'desc';
+};
+
+export type DataTableProps<T> = {
+  columns: Array<DataTableColumn<T>>;
+  data: T[];
+  rowKey: (row: T) => string;
+  onRowClick?: (row: T) => void;
+  sort?: DataTableSort | null;
+  onSortChange?: (sort: DataTableSort | null) => void;
+  empty?: ReactNode;
+  loading?: boolean;
+  compact?: boolean;
+  className?: string;
+};
+
+function defaultAccessor<T>(row: T): string | number {
+  // Fall back to identity when an accessor isn't provided. T may be any
+  // shape, so we use a best-effort cast.
+  if (row == null) return '';
+  if (typeof row === 'string' || typeof row === 'number') return row;
+  return String(row);
+}
+
+function compareValues(a: string | number, b: string | number): number {
+  if (typeof a === 'number' && typeof b === 'number') return a - b;
+  return String(a).localeCompare(String(b));
+}
+
+export function DataTable<T>({
+  columns,
+  data,
+  rowKey,
+  onRowClick,
+  sort: controlledSort,
+  onSortChange,
+  empty,
+  loading = false,
+  compact = false,
+  className,
+}: DataTableProps<T>): React.JSX.Element {
+  const [internalSort, setInternalSort] = useState<DataTableSort | null>(null);
+  const sort = controlledSort ?? internalSort;
+
+  const sortedData = useMemo(() => {
+    if (!sort) return data;
+    const col = columns.find((c) => c.key === sort.key);
+    if (!col) return data;
+    const accessor = col.accessor ?? defaultAccessor;
+    const copy = [...data];
+    copy.sort((a, b) => {
+      const cmp = compareValues(accessor(a), accessor(b));
+      return sort.direction === 'asc' ? cmp : -cmp;
+    });
+    return copy;
+  }, [data, columns, sort]);
+
+  const handleSort = (key: string): void => {
+    const next: DataTableSort | null =
+      !sort || sort.key !== key
+        ? { key, direction: 'asc' }
+        : sort.direction === 'asc'
+          ? { key, direction: 'desc' }
+          : null;
+    if (controlledSort === undefined) {
+      setInternalSort(next);
+    }
+    onSortChange?.(next);
+  };
+
+  const renderBody = (): ReactNode => {
+    if (loading) {
+      const skeletonCols = columns.length;
+      return (
+        <>
+          {Array.from({ length: 3 }).map((_, i) => (
+            <tr key={`skel-${i}`} className="bd-data-table__skeleton-row">
+              {Array.from({ length: skeletonCols }).map((__, j) => (
+                <td key={`skel-${i}-${j}`}>
+                  <div className="bd-data-table__skeleton" />
+                </td>
+              ))}
+            </tr>
+          ))}
+        </>
+      );
+    }
+    if (sortedData.length === 0) {
+      return (
+        <tr>
+          <td colSpan={columns.length} className="bd-data-table__empty">
+            {empty ?? 'No data'}
+          </td>
+        </tr>
+      );
+    }
+    return sortedData.map((row) => (
+      <tr
+        key={rowKey(row)}
+        className={cx(onRowClick && 'bd-data-table__row--clickable')}
+        onClick={onRowClick ? () => onRowClick(row) : undefined}
+      >
+        {columns.map((col) => (
+          <td
+            key={col.key}
+            className={cx(
+              'bd-data-table__td',
+              col.align === 'right' && 'bd-data-table__td--right',
+              col.align === 'center' && 'bd-data-table__td--center',
+            )}
+          >
+            {col.render
+              ? col.render(row)
+              : String(col.accessor ? col.accessor(row) : '')}
+          </td>
+        ))}
+      </tr>
+    ));
+  };
+
+  return (
+    <div
+      className={cx(
+        'bd-data-table',
+        compact && 'bd-data-table--compact',
+        className,
+      )}
+    >
+      <div className="bd-data-table__scroll">
+        <table className="bd-data-table__table">
+          <thead className="bd-data-table__thead">
+            <tr className="bd-data-table__tr">
+              {columns.map((col) => {
+                const isSorted = sort?.key === col.key;
+                const style: CSSProperties | undefined =
+                  col.width !== undefined
+                    ? { width: col.width }
+                    : undefined;
+                return (
+                  <th
+                    key={col.key}
+                    style={style}
+                    className={cx(
+                      'bd-data-table__th',
+                      col.align === 'right' && 'bd-data-table__th--right',
+                      col.align === 'center' && 'bd-data-table__th--center',
+                      col.sortable && 'bd-data-table__th--sortable',
+                      isSorted && 'bd-data-table__th--sorted',
+                    )}
+                    onClick={col.sortable ? () => handleSort(col.key) : undefined}
+                    aria-sort={
+                      isSorted
+                        ? sort!.direction === 'asc'
+                          ? 'ascending'
+                          : 'descending'
+                        : undefined
+                    }
+                  >
+                    {col.header}
+                    {col.sortable && (
+                      <span className="bd-data-table__sort-icon">
+                        {isSorted ? (
+                          sort!.direction === 'asc' ? (
+                            <ArrowUp size={12} aria-hidden="true" />
+                          ) : (
+                            <ArrowDown size={12} aria-hidden="true" />
+                          )
+                        ) : (
+                          <ChevronsUpDown size={12} aria-hidden="true" />
+                        )}
+                      </span>
+                    )}
+                  </th>
+                );
+              })}
+            </tr>
+          </thead>
+          <tbody className="bd-data-table__tbody">{renderBody()}</tbody>
+        </table>
+      </div>
+    </div>
+  );
+}

package/bizar-dash/src/web/ui/data/EmptyState.tsx

@@ -0,0 +1,60 @@
+/*
+ * EmptyState.tsx — Friendly empty-state placeholder (Wave 2B).
+ *
+ * Replaces the legacy components/EmptyState.tsx with a smaller, opinions-on
+ * shape: title is the only required field, optional description paragraph,
+ * default icon is a sad-cloud lucide glyph (drops in if no icon is passed),
+ * and an optional single-action button whose whole row is a labelled ghost
+ * CTA. `inline` mode removes the centred padding for use inside dense cards.
+ */
+
+import type { ReactNode } from 'react';
+import { Cloud } from 'lucide-react';
+import { cx } from '../utils/cx';
+
+export type EmptyStateProps = {
+  title: string;
+  description?: ReactNode;
+  icon?: ReactNode;
+  action?: { label: string; onClick: () => void };
+  inline?: boolean;
+  className?: string;
+};
+
+export function EmptyState({
+  title,
+  description,
+  icon,
+  action,
+  inline = false,
+  className,
+}: EmptyStateProps): React.JSX.Element {
+  return (
+    <div
+      className={cx(
+        'bd-state',
+        inline && 'bd-state--inline',
+        className,
+      )}
+    >
+      {icon !== null && (
+        <div className="bd-state__icon" aria-hidden="true">
+          {icon ?? <Cloud size={32} />}
+        </div>
+      )}
+      <div className="bd-state__title">{title}</div>
+      {description && (
+        <div className="bd-state__description">{description}</div>
+      )}
+      {action && (
+        <button
+          type="button"
+          className="bd-state__action bd-state__action--ghost"
+          onClick={action.onClick}
+        >
+          {action.label}
+        </button>
+      )}
+    </div>
+  );
+}

package/bizar-dash/src/web/ui/data/ErrorState.tsx

@@ -0,0 +1,56 @@
+/*
+ * ErrorState.tsx — Inline error block for data contexts (Wave 2B).
+ *
+ * Compact, actionable error display. Shows a danger-coloured error string
+ * (stringified if an Error object is passed) inside a subtle tinted box so
+ * the eye finds it without breaking the layout. Optional `onRetry` adds a
+ * primary "Try again" CTA button.
+ */
+
+import { AlertTriangle } from 'lucide-react';
+import { cx } from '../utils/cx';
+
+export type ErrorStateProps = {
+  title?: string;
+  error: Error | string;
+  onRetry?: () => void;
+  inline?: boolean;
+  className?: string;
+};
+
+function stringifyError(err: Error | string): string {
+  if (typeof err === 'string') return err;
+  if (err.message) return err.message;
+  return err.name || 'Unknown error';
+}
+
+export function ErrorState({
+  title = 'Something went wrong',
+  error,
+  onRetry,
+  inline = false,
+  className,
+}: ErrorStateProps): React.JSX.Element {
+  const message = stringifyError(error);
+  return (
+    <div
+      className={cx('bd-state', inline && 'bd-state--inline', className)}
+      role="alert"
+    >
+      <div className="bd-state__icon" aria-hidden="true">
+        <AlertTriangle size={28} />
+      </div>
+      <div className="bd-state__title">{title}</div>
+      <div className="bd-state__error">{message}</div>
+      {onRetry && (
+        <button
+          type="button"
+          className="bd-state__action"
+          onClick={onRetry}
+        >
+          Try again
+        </button>
+      )}
+    </div>
+  );
+}

package/bizar-dash/src/web/ui/data/KeyValueList.tsx

@@ -0,0 +1,106 @@
+/*
+ * KeyValueList.tsx — Definition-list style rows (Wave 2B).
+ *
+ * Renders label/value pairs in either a definition-grid (horizontal, two
+ * columns) or stacked (vertical, label above value) layout. Each value can
+ * be opt-in mono-font and/or copyable — `copyable` adds a small icon button
+ * that copies `String(value)` to the clipboard and briefly switches to a
+ * checkmark so the action is confirmed. The whole item is keyboard-focusable
+ * for screen-reader users.
+ */
+
+import {
+  useCallback,
+  useEffect,
+  useRef,
+  useState,
+  type ReactNode,
+} from 'react';
+import { Check, Copy } from 'lucide-react';
+import { cx } from '../utils/cx';
+
+export type KeyValueItem = {
+  key: string;
+  label: string;
+  value: ReactNode;
+  mono?: boolean;
+  copyable?: boolean;
+};
+
+export type KeyValueListProps = {
+  items: KeyValueItem[];
+  orientation?: 'horizontal' | 'vertical';
+  className?: string;
+};
+
+function CopyButton({ text }: { text: string }): React.JSX.Element {
+  const [done, setDone] = useState(false);
+  const timer = useRef<ReturnType<typeof setTimeout> | null>(null);
+
+  useEffect(
+    () => () => {
+      if (timer.current) clearTimeout(timer.current);
+    },
+    [],
+  );
+
+  const onClick = useCallback(() => {
+    if (typeof navigator === 'undefined' || !navigator.clipboard) return;
+    navigator.clipboard
+      .writeText(text)
+      .then(() => {
+        setDone(true);
+        if (timer.current) clearTimeout(timer.current);
+        timer.current = setTimeout(() => setDone(false), 1500);
+      })
+      .catch(() => {
+        // ignore — clipboard may be unavailable in private mode
+      });
+  }, [text]);
+
+  return (
+    <button
+      type="button"
+      className={cx('bd-kv-list__copy', done && 'bd-kv-list__copy--done')}
+      aria-label={done ? 'Copied' : 'Copy to clipboard'}
+      onClick={onClick}
+    >
+      {done ? <Check size={12} /> : <Copy size={12} />}
+    </button>
+  );
+}
+
+export function KeyValueList({
+  items,
+  orientation = 'horizontal',
+  className,
+}: KeyValueListProps): React.JSX.Element {
+  return (
+    <dl
+      className={cx(
+        'bd-kv-list',
+        orientation === 'horizontal'
+          ? 'bd-kv-list--horizontal'
+          : 'bd-kv-list--vertical',
+        className,
+      )}
+    >
+      {items.map((item) => (
+        <div key={item.key} className="bd-kv-list__row">
+          <dt className="bd-kv-list__label">{item.label}</dt>
+          <dd
+            className={cx(
+              'bd-kv-list__value',
+              item.mono && 'bd-kv-list__value--mono',
+            )}
+          >
+            <span>{item.value}</span>
+            {item.copyable && (
+              <CopyButton text={String(item.value)} />
+            )}
+          </dd>
+        </div>
+      ))}
+    </dl>
+  );
+}

package/bizar-dash/src/web/ui/data/LoadingState.tsx

@@ -0,0 +1,65 @@
+/*
+ * LoadingState.tsx — Placeholder for in-flight data (Wave 2B).
+ *
+ * Two modes: when `rows` is set, renders N skeleton bars (use inside cards
+ * and detail panels); otherwise renders a centred spinner with an optional
+ * label. Skeleton bars use a shimmer animation that picks up the active
+ * theme via the token-driven gradient — no per-mode flag needed.
+ */
+
+import { cx } from '../utils/cx';
+
+export type LoadingStateProps = {
+  label?: string;
+  rows?: number;
+  inline?: boolean;
+  className?: string;
+};
+
+export function LoadingState({
+  label,
+  rows = 3,
+  inline = false,
+  className,
+}: LoadingStateProps): React.JSX.Element {
+  if (rows > 0) {
+    return (
+      <div
+        className={cx(
+          'bd-state',
+          inline && 'bd-state--inline',
+          className,
+        )}
+        role="status"
+        aria-live="polite"
+        aria-label={label ?? 'Loading'}
+      >
+        <div className="bd-skeleton-row" aria-hidden="true">
+          {Array.from({ length: rows }).map((_, i) => (
+            <div key={i} className="bd-skeleton-row__bar" />
+          ))}
+        </div>
+        {label && <div className="bd-state__label">{label}</div>}
+      </div>
+    );
+  }
+
+  return (
+    <div
+      className={cx(
+        'bd-state',
+        inline && 'bd-state--inline',
+        className,
+      )}
+      role="status"
+      aria-live="polite"
+      aria-label={label ?? 'Loading'}
+    >
+      <div
+        className={cx('bd-spinner', inline && 'bd-spinner--inline')}
+        aria-hidden="true"
+      />
+      {label && <div className="bd-state__label">{label}</div>}
+    </div>
+  );
+}

package/bizar-dash/src/web/ui/data/Sparkline.tsx

@@ -0,0 +1,87 @@
+/*
+ * Sparkline.tsx — Tiny inline SVG line chart (Wave 2B).
+ *
+ * No axes, no labels, no legend — purely a visual trend strip. Auto-scales
+ * any numeric input to its own min/max so a flat-line series still draws a
+ * line at mid-height. Renders a soft fill below the line for warmth. Uses
+ * CSS variables (var(--chart-1) / var(--accent-subtle) by default) so it
+ * picks up theme changes automatically.
+ */
+
+export type SparklineProps = {
+  data: number[];
+  width?: number;
+  height?: number;
+  stroke?: string;
+  fill?: string;
+  ariaLabel?: string;
+  className?: string;
+};
+
+function buildPath(
+  data: number[],
+  width: number,
+  height: number,
+  padY: number,
+): { line: string; area: string; min: number; max: number } {
+  if (data.length === 0) {
+    return { line: '', area: '', min: 0, max: 0 };
+  }
+  // Single point or flat-line series → draw at mid-height.
+  const min = Math.min(...data);
+  const max = Math.max(...data);
+  const range = max - min || 1;
+  const innerH = height - padY * 2;
+  const innerW = width;
+  const stepX = data.length > 1 ? innerW / (data.length - 1) : 0;
+
+  const points = data.map((v, i) => {
+    const x = i * stepX;
+    const y = padY + innerH - ((v - min) / range) * innerH;
+    return [x, y] as const;
+  });
+
+  const line = points
+    .map(([x, y], i) => `${i === 0 ? 'M' : 'L'}${x.toFixed(2)},${y.toFixed(2)}`)
+    .join(' ');
+
+  const last = points[points.length - 1];
+  const first = points[0];
+  const area =
+    `${line} L${last[0].toFixed(2)},${(height - padY).toFixed(2)} ` +
+    `L${first[0].toFixed(2)},${(height - padY).toFixed(2)} Z`;
+
+  return { line, area, min, max };
+}
+
+export function Sparkline({
+  data,
+  width = 80,
+  height = 24,
+  stroke = 'var(--chart-1)',
+  fill = 'var(--accent-subtle)',
+  ariaLabel,
+  className,
+}: SparklineProps): React.JSX.Element {
+  const padY = 2;
+  const { line, area } = buildPath(data, width, height, padY);
+
+  return (
+    <svg
+      role="img"
+      aria-label={ariaLabel ?? `Sparkline of ${data.length} values`}
+      className={className}
+      width={width}
+      height={height}
+      viewBox={`0 0 ${width} ${height}`}
+      preserveAspectRatio="none"
+    >
+      {data.length > 0 && (
+        <>
+          <path className="bd-sparkline__fill" d={area} fill={fill} />
+          <path className="bd-sparkline__line" d={line} stroke={stroke} />
+        </>
+      )}
+    </svg>
+  );
+}

package/bizar-dash/src/web/ui/data/StatTile.tsx

@@ -0,0 +1,87 @@
+/*
+ * StatTile.tsx — KPI tile for the dashboard hero row (Wave 2B).
+ *
+ * Compact [icon] [label/value/delta] layout. Whole tile becomes a clickable
+ * surface when `href` is supplied (renders an <a>); otherwise a plain <div>.
+ * Value uses font-mono + tabular-nums so a row of tiles stays column-aligned
+ * even when digit counts change (12 vs 1234). Loading state replaces the
+ * value with a shimmer skeleton; everything else stays put.
+ */
+
+import type { HTMLAttributes, ReactNode } from 'react';
+import { ArrowDown, ArrowUp } from 'lucide-react';
+import { cx } from '../utils/cx';
+
+export type StatTileProps = HTMLAttributes<HTMLElement> & {
+  label: string;
+  value: string | number;
+  unit?: string;
+  delta?: { value: number; direction: 'up' | 'down' };
+  icon?: ReactNode;
+  href?: string;
+  loading?: boolean;
+  className?: string;
+};
+
+export function StatTile({
+  label,
+  value,
+  unit,
+  delta,
+  icon,
+  href,
+  loading = false,
+  className,
+  ...rest
+}: StatTileProps): React.JSX.Element {
+  const Tag = href ? 'a' : 'div';
+  // When rendering an <a>, only forward anchor-safe attrs. When rendering a
+  // <div>, forward all HTMLAttributes. The intersection avoids TS complaints
+  // about ref / event-handler types that differ between the two tags.
+  const forwarded = href
+    ? ({ href, ...rest } as HTMLAttributes<HTMLElement>)
+    : (rest as HTMLAttributes<HTMLElement>);
+
+  return (
+    <Tag
+      {...forwarded}
+      className={cx(
+        'bd-stat-tile',
+        href && 'bd-stat-tile--clickable',
+        className,
+      )}
+    >
+      {icon && <div className="bd-stat-tile__icon">{icon}</div>}
+      <div className="bd-stat-tile__body">
+        <div className="bd-stat-tile__label">{label}</div>
+        <div className="bd-stat-tile__value-row">
+          {loading ? (
+            <div className="bd-stat-tile__skeleton" aria-hidden="true" />
+          ) : (
+            <>
+              <span className="bd-stat-tile__value">{value}</span>
+              {unit && <span className="bd-stat-tile__unit">{unit}</span>}
+            </>
+          )}
+        </div>
+        {delta && !loading && (
+          <div
+            className={cx(
+              'bd-stat-tile__delta',
+              delta.direction === 'up' && 'bd-stat-tile__delta--up',
+              delta.direction === 'down' && 'bd-stat-tile__delta--down',
+            )}
+            aria-label={`${delta.direction === 'up' ? 'up' : 'down'} ${delta.value}`}
+          >
+            {delta.direction === 'up' ? (
+              <ArrowUp size={12} aria-hidden="true" />
+            ) : (
+              <ArrowDown size={12} aria-hidden="true" />
+            )}
+            <span>{delta.value}</span>
+          </div>
+        )}
+      </div>
+    </Tag>
+  );
+}