aplance-ui 1.0.1

package/registry/components/ui/chart/types.ts

@@ -0,0 +1,210 @@
+import type { ReactNode } from "react";
+
+export type ChartDatum = Record<string, string | number | null | undefined>;
+
+export type ChartColorMap = Record<string, string>;
+
+export type ChartSeriesType = "bar" | "line" | "area";
+
+export type AxisFormatter = (value: string | number) => string;
+
+export type TooltipValueFormatter = (
+  value: string | number,
+  meta: { name?: string | number; dataKey?: string | number },
+) => string;
+
+export type TooltipLabelFormatter = (label: string | number) => string;
+
+export type ReferenceLineConfig = {
+  value: number;
+  /** Which axis to draw the line on. Default: "y". */
+  axis?: "x" | "y";
+  label?: string;
+  /** CSS token (e.g. "--color-chart-secondary") or raw CSS color. */
+  color?: string;
+  strokeDasharray?: string;
+  /** Which Y axis to attach to when axis is "y". Default: "left". */
+  yAxisId?: "left" | "right";
+};
+
+export type ChartSeries = {
+  key: string;
+  label?: string;
+  /** CSS token or raw CSS color. */
+  color?: string;
+  type?: ChartSeriesType;
+  stackId?: string;
+  yAxisId?: "left" | "right";
+  strokeWidth?: number;
+  fillOpacity?: number;
+  /** Show dots on data points. Applies to line and area series. Default: false. */
+  dot?: boolean;
+  /** Connect across null/undefined data gaps. Applies to line and area series. Default: false. */
+  connectNulls?: boolean;
+};
+
+export type ScatterSeries = {
+  key: string;
+  label?: string;
+  /** CSS token or raw CSS color. */
+  color?: string;
+  data: ChartDatum[];
+};
+
+export const CHART_COLOR_TOKENS = {
+  primary: "--color-chart-primary",
+  secondary: "--color-chart-secondary",
+  tertiary: "--color-chart-tertiary",
+  quaternary: "--color-chart-quaternary",
+  quinary: "--color-chart-quinary",
+  muted: "--color-chart-muted",
+  grid: "--color-chart-grid",
+  cursor: "--color-chart-cursor",
+} as const;
+
+export type ChartColorTokenName = keyof typeof CHART_COLOR_TOKENS;
+
+// ─── Base prop shapes ─────────────────────────────────────────────────────────
+
+type ChartBaseProps = {
+  title: string;
+  description?: string;
+  height?: number;
+  className?: string;
+  emptyMessage?: string;
+  /** Show a loading indicator in place of the chart. */
+  isLoading?: boolean;
+};
+
+type CartesianChartBaseProps = ChartBaseProps & {
+  data: ChartDatum[];
+  categoryKey: string;
+  showGrid?: boolean;
+  showXAxis?: boolean;
+  showYAxis?: boolean;
+  showTooltip?: boolean;
+  /** Show a color legend below the chart. Default: false. */
+  showLegend?: boolean;
+  allowDecimals?: boolean;
+  xTickFormatter?: AxisFormatter;
+  yTickFormatter?: AxisFormatter;
+  tooltipValueFormatter?: TooltipValueFormatter;
+  tooltipLabelFormatter?: TooltipLabelFormatter;
+  /** Horizontal or vertical threshold / target lines drawn across the chart. */
+  referenceLines?: ReferenceLineConfig[];
+};
+
+// ─── Chart variant props ──────────────────────────────────────────────────────
+
+export type BarChartProps = CartesianChartBaseProps & {
+  type: "bar";
+  dataKey?: string;
+  series?: ChartSeries[];
+  maxBarSize?: number;
+  /** Map of normalized category label → token/color (e.g. "qualified": "--color-chart-secondary"). */
+  colors?: ChartColorMap;
+  /**
+   * Bar orientation. "vertical" = bars grow up (default).
+   * "horizontal" = bars grow right (category axis on Y).
+   */
+  orientation?: "vertical" | "horizontal";
+  /** Gap between bar groups as a percent string ("20%") or pixel number. */
+  barCategoryGap?: number | string;
+};
+
+export type AreaChartProps = CartesianChartBaseProps & {
+  type: "area";
+  dataKey?: string;
+  series?: ChartSeries[];
+  /** Token or CSS color for single-series shorthand. */
+  color?: string;
+  seriesLabel?: string;
+  /** Show dots on data points. Default: false. */
+  showDots?: boolean;
+  /** Connect across null/undefined data gaps. Default: false. */
+  connectNulls?: boolean;
+};
+
+export type LineChartProps = CartesianChartBaseProps & {
+  type: "line";
+  dataKey?: string;
+  series?: ChartSeries[];
+  /** Token or CSS color for single-series shorthand. */
+  color?: string;
+  seriesLabel?: string;
+  curveType?: "linear" | "monotone" | "step";
+  /** Show dots on data points. Default: false. */
+  showDots?: boolean;
+  /** Connect across null/undefined data gaps. Default: false. */
+  connectNulls?: boolean;
+};
+
+export type ComposedChartProps = CartesianChartBaseProps & {
+  type: "composed";
+  series: ChartSeries[];
+};
+
+export type DonutChartProps = ChartBaseProps & {
+  type: "donut";
+  data: ChartDatum[];
+  dataKey: string;
+  nameKey: string;
+  /** Map of normalized segment label → token/color. */
+  colors?: ChartColorMap;
+  centerContent?: ReactNode;
+  /** Show color legend below the chart. Default: true. */
+  showLegend?: boolean;
+  innerRadius?: number;
+  outerRadius?: number;
+  paddingAngle?: number;
+  tooltipValueFormatter?: TooltipValueFormatter;
+  tooltipLabelFormatter?: TooltipLabelFormatter;
+};
+
+export type RadialBarChartProps = ChartBaseProps & {
+  type: "radialbar";
+  data: ChartDatum[];
+  dataKey: string;
+  nameKey: string;
+  /** Map of normalized item label → token/color. */
+  colors?: ChartColorMap;
+  /** Show color legend below the chart. Default: true. */
+  showLegend?: boolean;
+  /**
+   * Domain maximum - all bars scale relative to this value.
+   * Defaults to the maximum value found in the dataset.
+   */
+  maxValue?: number;
+  tooltipValueFormatter?: TooltipValueFormatter;
+  tooltipLabelFormatter?: TooltipLabelFormatter;
+};
+
+export type ScatterChartProps = ChartBaseProps & {
+  type: "scatter";
+  series: ScatterSeries[];
+  /** Data key used for the X axis across all series. */
+  xKey: string;
+  /** Data key used for the Y axis across all series. */
+  yKey: string;
+  /** Optional data key for bubble size (Z axis). */
+  zKey?: string;
+  showGrid?: boolean;
+  showXAxis?: boolean;
+  showYAxis?: boolean;
+  showTooltip?: boolean;
+  /** Show color legend below the chart when there are multiple series. Default: false. */
+  showLegend?: boolean;
+  allowDecimals?: boolean;
+  xTickFormatter?: AxisFormatter;
+  yTickFormatter?: AxisFormatter;
+  tooltipValueFormatter?: TooltipValueFormatter;
+};
+
+export type ChartProps =
+  | BarChartProps
+  | AreaChartProps
+  | LineChartProps
+  | ComposedChartProps
+  | DonutChartProps
+  | RadialBarChartProps
+  | ScatterChartProps;

package/registry/components/ui/chart/utils.ts

@@ -0,0 +1,59 @@
+import { CHART_COLOR_TOKENS } from "./types";
+
+const SERIES_COLOR_ORDER = [
+  "primary",
+  "secondary",
+  "tertiary",
+  "quaternary",
+  "quinary",
+] as const;
+
+const FALLBACK_COLORS = {
+  primary: "#3b82f6",
+  secondary: "#5f97f7",
+  tertiary: "#82adf9",
+  quaternary: "#a4c2fb",
+  quinary: "#6d79e6",
+  muted: "#6b7280",
+  grid: "#e5e7eb",
+  cursor: "rgba(148, 163, 184, 0.20)",
+} as const;
+
+/**
+ * Accepts either a CSS variable token (e.g. "--color-chart-primary") or a raw CSS color.
+ * Falls back safely when tokens are missing.
+ */
+export const resolveColorToken = (tokenOrColor: string | undefined, fallback: string): string => {
+  if (!tokenOrColor) return fallback;
+
+  const value = tokenOrColor.trim();
+  if (!value) return fallback;
+
+  if (!value.startsWith("--")) {
+    return value;
+  }
+
+  // Use CSS variable references directly so theme changes update chart colors
+  // even when Storybook toggles theme tokens without triggering a React rerender.
+  return `var(${value}, ${fallback})`;
+};
+
+export const createChartPalette = () => ({
+  primary: resolveColorToken(CHART_COLOR_TOKENS.primary, FALLBACK_COLORS.primary),
+  secondary: resolveColorToken(CHART_COLOR_TOKENS.secondary, FALLBACK_COLORS.secondary),
+  tertiary: resolveColorToken(CHART_COLOR_TOKENS.tertiary, FALLBACK_COLORS.tertiary),
+  quaternary: resolveColorToken(CHART_COLOR_TOKENS.quaternary, FALLBACK_COLORS.quaternary),
+  quinary: resolveColorToken(CHART_COLOR_TOKENS.quinary, FALLBACK_COLORS.quinary),
+  muted: resolveColorToken(CHART_COLOR_TOKENS.muted, FALLBACK_COLORS.muted),
+  grid: resolveColorToken(CHART_COLOR_TOKENS.grid, FALLBACK_COLORS.grid),
+  cursor: resolveColorToken(CHART_COLOR_TOKENS.cursor, FALLBACK_COLORS.cursor),
+});
+
+export type ChartPalette = ReturnType<typeof createChartPalette>;
+
+export const pickSeriesColor = (palette: ChartPalette, index: number): string => {
+  const tokenName = SERIES_COLOR_ORDER[index % SERIES_COLOR_ORDER.length];
+  return palette[tokenName];
+};
+
+export const toLookupKey = (value: unknown): string => String(value ?? "").trim().toLowerCase();

package/registry/components/ui/copy-button/copy-button.module.css

@@ -0,0 +1,21 @@
+.base {
+  display: inline-flex;
+  align-items: center;
+}
+
+.icon {
+  flex-shrink: 0;
+}
+
+.preview {
+  max-width: 20ch;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+
+.token_preview {
+  font-family: ui-monospace, SFMono-Regular, "SF Mono", Menlo, Monaco, Consolas,
+    "Liberation Mono", "Courier New", monospace;
+  letter-spacing: 0.01em;
+}

package/registry/components/ui/copy-button/copy-button.tsx

@@ -0,0 +1,123 @@
+import { useEffect, useRef, useState } from "react";
+import clsx from "clsx";
+import { Button } from "../button/button";
+import { IconCopy, IconCheck } from "@tabler/icons-react";
+import type { ButtonLayout, ButtonSize, ButtonVariant } from "../button/button";
+import s from "./copy-button.module.css";
+
+export type CopyPreview = "none" | "truncate" | "mask-token";
+
+export type CopyButtonProps = {
+  value: string;
+  className?: string;
+  buttonVariant?: ButtonVariant;
+  buttonSize?: ButtonSize;
+  buttonLayout?: ButtonLayout;
+  variant?: ButtonVariant;
+  size?: ButtonSize;
+  layout?: ButtonLayout;
+  preview?: CopyPreview;
+  previewMaxLength?: number;
+};
+
+const maskToken = (raw: string): string => {
+  const value = raw.trim();
+  if (value.length <= 8) return "*".repeat(Math.max(value.length, 4));
+  return `${value.slice(0, 4)}****${value.slice(-4)}`;
+};
+
+const previewValue = (value: string, preview: CopyPreview, maxLength: number): string | null => {
+  if (preview === "none") return null;
+  if (preview === "mask-token") return maskToken(value);
+  if (value.length <= maxLength) return value;
+  return `${value.slice(0, maxLength)}...`;
+};
+
+export function CopyButton({
+  value,
+  className,
+  buttonVariant,
+  buttonSize,
+  buttonLayout,
+  variant,
+  size,
+  layout,
+  preview = "none",
+  previewMaxLength = 24,
+}: CopyButtonProps) {
+  const [copied, setCopied] = useState(false);
+  const timeoutRef = useRef<number | null>(null);
+
+  useEffect(() => {
+    return () => {
+      if (timeoutRef.current !== null) {
+        window.clearTimeout(timeoutRef.current);
+      }
+    };
+  }, []);
+
+  const copyWithFallback = async (text: string): Promise<boolean> => {
+    try {
+      if (navigator.clipboard?.writeText) {
+        await navigator.clipboard.writeText(text);
+        return true;
+      }
+    } catch {
+      // fallback below
+    }
+
+    const area = document.createElement("textarea");
+    area.value = text;
+    area.setAttribute("readonly", "");
+    area.style.position = "fixed";
+    area.style.opacity = "0";
+    document.body.appendChild(area);
+    area.select();
+    const success = document.execCommand("copy");
+    document.body.removeChild(area);
+    return success;
+  };
+
+  const handleCopy = async () => {
+    const success = await copyWithFallback(value);
+    if (!success) return;
+
+    setCopied(true);
+    if (timeoutRef.current !== null) {
+      window.clearTimeout(timeoutRef.current);
+    }
+    timeoutRef.current = window.setTimeout(() => setCopied(false), 2000);
+  };
+
+  const previewText = previewValue(value, preview, previewMaxLength);
+  const hasPreview = previewText !== null;
+  const resolvedVariant = buttonVariant ?? variant ?? "bordered";
+  const resolvedSize = buttonSize ?? size ?? "default";
+  const resolvedLayout = buttonLayout ?? layout ?? (hasPreview ? "default" : "box");
+  const showPreview = hasPreview && resolvedLayout !== "box";
+
+  return (
+    <Button
+      variant={resolvedVariant}
+      size={resolvedSize}
+      layout={resolvedLayout}
+      onClick={handleCopy}
+      type="button"
+      className={clsx(s.base, className)}
+      title={copied ? "Copied!" : "Copy to clipboard"}
+      aria-label={copied ? "Copied value" : "Copy value"}
+    >
+      {copied ? <IconCheck size={16} className={s.icon} /> : <IconCopy size={16} className={s.icon} />}
+      {showPreview && (
+        <span
+          className={clsx(
+            s.preview,
+            preview === "mask-token" && s.token_preview,
+          )}
+        >
+          {copied ? "Copied" : previewText}
+        </span>
+      )}
+    </Button>
+  );
+}

package/registry/components/ui/countdown/countdown.module.css

@@ -0,0 +1,5 @@
+.root {
+  font-family: var(--font-family-1);
+  font-variant-numeric: tabular-nums;
+  color: var(--color-foreground);
+}

package/registry/components/ui/countdown/countdown.tsx

@@ -0,0 +1,152 @@
+import {
+  useCallback,
+  useEffect,
+  useImperativeHandle,
+  useRef,
+  useState,
+  type ReactNode,
+  type Ref,
+} from "react";
+import clsx from "clsx";
+import s from "./countdown.module.css";
+
+export type CountdownFormat =
+  | "mm:ss"
+  | "ss"
+  | "hh:mm:ss"
+  | ((remaining: number) => ReactNode);
+
+export type CountdownState = {
+  remaining: number;
+  isRunning: boolean;
+  isComplete: boolean;
+  formatted: ReactNode;
+  start: () => void;
+  pause: () => void;
+  reset: (newDuration?: number) => void;
+};
+
+export type CountdownHandle = Pick<CountdownState, "start" | "pause" | "reset">;
+
+export type CountdownProps = {
+  /** Initial duration in seconds. */
+  duration: number;
+  /** Display format. Default: "mm:ss". Pass a function for full control. */
+  format?: CountdownFormat;
+  /** Auto-start on mount. Default: true. */
+  autoStart?: boolean;
+  /** Fired every second with the remaining seconds (post-decrement). */
+  onTick?: (remaining: number) => void;
+  /** Fired once when remaining reaches 0. */
+  onComplete?: () => void;
+  /**
+   * Render-prop children. Called with the countdown state on every tick -
+   * lets you swap in any UI (e.g. a Button when complete) without needing
+   * a wrapper component. When omitted, the formatted time is rendered.
+   */
+  children?: (state: CountdownState) => ReactNode;
+  className?: string;
+  style?: React.CSSProperties;
+  ref?: Ref<CountdownHandle>;
+};
+
+const pad2 = (n: number) => String(n).padStart(2, "0");
+
+const formatRemaining = (
+  remaining: number,
+  format: CountdownFormat,
+): ReactNode => {
+  if (typeof format === "function") return format(remaining);
+  const seconds = remaining % 60;
+  const minutes = Math.floor(remaining / 60) % 60;
+  const hours = Math.floor(remaining / 3600);
+  switch (format) {
+    case "ss":
+      return String(remaining);
+    case "hh:mm:ss":
+      return `${pad2(hours)}:${pad2(minutes)}:${pad2(seconds)}`;
+    case "mm:ss":
+    default:
+      return `${pad2(Math.floor(remaining / 60))}:${pad2(seconds)}`;
+  }
+};
+
+export const Countdown = ({
+  duration,
+  format = "mm:ss",
+  autoStart = true,
+  onTick,
+  onComplete,
+  children,
+  className,
+  style,
+  ref,
+}: CountdownProps) => {
+  const [remaining, setRemaining] = useState(duration);
+  const [running, setRunning] = useState(autoStart);
+
+  // Latest-callback refs - keep the interval effect free of callback-identity
+  // deps so a parent re-render doesn't tear down and recreate the interval.
+  const onTickRef = useRef(onTick);
+  const onCompleteRef = useRef(onComplete);
+  useEffect(() => {
+    onTickRef.current = onTick;
+    onCompleteRef.current = onComplete;
+  }, [onTick, onComplete]);
+
+  useEffect(() => {
+    if (!running) return;
+    if (remaining <= 0) {
+      setRunning(false);
+      onCompleteRef.current?.();
+      return;
+    }
+    const id = setInterval(() => {
+      setRemaining((r) => {
+        const next = r - 1;
+        onTickRef.current?.(next);
+        return next;
+      });
+    }, 1000);
+    return () => clearInterval(id);
+  }, [running, remaining]);
+
+  const start = useCallback(() => setRunning(true), []);
+  const pause = useCallback(() => setRunning(false), []);
+  const reset = useCallback(
+    (newDuration?: number) => {
+      setRemaining(newDuration ?? duration);
+      setRunning(true);
+    },
+    [duration],
+  );
+
+  useImperativeHandle(ref, () => ({ start, pause, reset }), [start, pause, reset]);
+
+  if (typeof children === "function") {
+    return (
+      <>
+        {children({
+          remaining,
+          isRunning: running,
+          isComplete: remaining <= 0,
+          formatted: formatRemaining(remaining, format),
+          start,
+          pause,
+          reset,
+        })}
+      </>
+    );
+  }
+
+  return (
+    <span
+      className={clsx(s.root, className)}
+      style={style}
+      role="timer"
+      aria-live="off"
+    >
+      {formatRemaining(remaining, format)}
+    </span>
+  );
+};

package/registry/components/ui/data-table/checkbox-column.tsx

@@ -0,0 +1,59 @@
+import type { ColumnDef } from "@tanstack/react-table";
+import { Input } from "../input-fields/input/input";
+import s from "./data-table.module.css";
+
+/**
+ * Pre-built select-all / per-row checkbox column using `<Input type="checkbox">`.
+ * Handles indeterminate state on the header checkbox.
+ *
+ * @example
+ * const cols = useMemo(
+ *   () => [checkboxColumn<MyRow>(editingRowId), ...rest],
+ *   [editingRowId]
+ * )
+ */
+export function checkboxColumn<TData extends { id: string }>(
+  editingRowId?: string | null,
+): ColumnDef<TData> {
+  return {
+    id: "select",
+    // Compact fixed width keeps checkbox cells visually balanced while
+    // reserving enough room for focus ring rendering.
+    size: 42,
+    minSize: 42,
+    maxSize: 50,
+    enableSorting: false,
+    enableHiding: false,
+    enableResizing: false,
+    enableGrouping: false,
+    meta: {
+      align: "center",
+      truncate: false,
+    },
+    header: ({ table }) => (
+      <Input
+        type="checkbox"
+        checked={table.getIsAllRowsSelected()}
+        className={s.selection_checkbox}
+        disabled={editingRowId != null}
+        ref={(el: HTMLInputElement | null) => {
+          if (el)
+            el.indeterminate =
+              table.getIsSomeRowsSelected() && !table.getIsAllRowsSelected();
+        }}
+        onChange={table.getToggleAllRowsSelectedHandler()}
+        aria-label="Select all rows"
+      />
+    ),
+    cell: ({ row }) => (
+      <Input
+        type="checkbox"
+        className={s.selection_checkbox}
+        checked={row.getIsSelected()}
+        disabled={!row.getCanSelect() || editingRowId != null}
+        onChange={row.getToggleSelectedHandler()}
+        aria-label={`Select row ${row.id}`}
+      />
+    ),
+  };
+}