aplance-ui 1.0.1

package/registry/components/ui/data-table/utils.ts

@@ -0,0 +1,445 @@
+import type {
+  Column,
+  ColumnOrderState,
+  ColumnPinningState,
+  ColumnSizingState,
+  ExpandedState,
+  Updater,
+  VisibilityState,
+} from "@tanstack/react-table";
+import type { CSSProperties } from "react";
+import type {
+  ApplyPersistedTarget,
+  ColumnIdSource,
+  PersistedState,
+  SnapshotInput,
+} from "./types";
+
+/**
+ * Per-cell style map for one column. Returns the fixed width plus the
+ * sticky offset when the column is pinned. Reading offsets straight from
+ * tanstack (`getStart`/`getAfter`) keeps header and body cells in sync
+ * even after resizing or reordering - no manual bookkeeping needed.
+ */
+export function getColumnStyle<TData>(
+  column: Column<TData, unknown>,
+  size: number,
+  extraWidth = 0,
+): CSSProperties {
+  const isPinned = column.getIsPinned();
+  const computedWidth = size + extraWidth;
+  const style: CSSProperties = {
+    width: `${computedWidth}px`,
+    minWidth: `${computedWidth}px`,
+    maxWidth: `${computedWidth}px`,
+  };
+  if (isPinned === "left") {
+    style.left = `${column.getStart("left")}px`;
+  } else if (isPinned === "right") {
+    style.right = `${column.getAfter("right")}px`;
+  }
+  return style;
+}
+
+/** Move `sourceId` to the position currently held by `targetId`. */
+export function reorderColumnOrder(
+  order: ColumnOrderState,
+  sourceId: string,
+  targetId: string,
+): ColumnOrderState {
+  const next = order.slice();
+  const fromIdx = next.indexOf(sourceId);
+  const toIdx = next.indexOf(targetId);
+  if (fromIdx === -1 || toIdx === -1) return order;
+  next.splice(fromIdx, 1);
+  next.splice(toIdx, 0, sourceId);
+  return next;
+}
+
+/**
+ * Last visible pinned column on its side. Used by the divider style so
+ * we don't draw an inset line between adjacent pinned columns - only at
+ * the boundary between the pinned region and the scrolling center.
+ */
+export function isLastPinned<TData>(column: Column<TData, unknown>): boolean {
+  const pinned = column.getIsPinned();
+  if (pinned !== "left" && pinned !== "right") return false;
+  return column.getIsLastColumn(pinned);
+}
+
+/**
+ * Default formatter for aggregated values when a column does not provide
+ * an `aggregatedCell`. Numbers fall back to `toLocaleString` and arrays
+ * to a count; everything else is rendered as-is.
+ */
+export function formatAggregated(value: unknown): string {
+  if (value == null) return "";
+  if (typeof value === "number") return value.toLocaleString();
+  if (Array.isArray(value)) return `${value.length} items`;
+  return String(value);
+}
+
+/**
+ * Resolve the runtime column id from a raw `ColumnDef`. Mirrors how
+ * tanstack derives ids: explicit `id` first, then `accessorKey` for
+ * accessor columns. Useful when consumers need to build menus (visibility,
+ * grouping, etc.) from the same column array they hand to the table -
+ * tanstack only assigns the resolved id once the table is built, so
+ * reading `c.id` directly off the def returns `undefined` for accessor
+ * columns and breaks state maps keyed by id.
+ */
+export function columnId(def: ColumnIdSource): string {
+  if (def.id) return def.id;
+  if (def.accessorKey != null) return String(def.accessorKey);
+  return "";
+}
+
+/**
+ * TanStack `Updater<T>` is `T | ((old: T) => T)`. When `T` itself extends
+ * `Function`, TypeScript widens the function branch to `((old: T) => T) |
+ * (T & Function)` after the `typeof` narrowing - and `T & Function` has no
+ * call signatures, so a cast is required to keep the compiler happy.
+ */
+export function resolveUpdater<T>(updater: Updater<T>, prev: T): T {
+  return typeof updater === "function"
+    ? (updater as (old: T) => T)(prev)
+    : updater;
+}
+
+export const SELECT_COLUMN_ID = "select";
+
+// ─────────────────────────────────────────────────────────────────────────────
+// State persistence helpers (URL search params / localStorage / manual).
+// Pure functions - no React. The hook-level orchestration in `useDataTable`
+// supplies the current state + setters and these functions take care of the
+// snapshot/apply/read/write mechanics.
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * Single source-of-truth for every URL param key used by the persistence
+ * layer. Both `readSearchParams` and `writeSearchParams` reference these
+ * values - adding or renaming a key is one edit here, not scattered string
+ * literals across multiple functions.
+ */
+export const PARAM_KEYS = {
+  pageIndex: "pageIndex",
+  pageSize: "pageSize",
+  sortBy: "sortBy",
+  sortDir: "sortDir",
+  columnOrder: "columnOrder",
+  columnVisibility: "columnVisibility",
+  columnPinning: "columnPinning",
+  columnSizing: "columnSizing",
+  grouping: "grouping",
+  expanded: "expanded",
+} as const;
+
+export type ParamKey = (typeof PARAM_KEYS)[keyof typeof PARAM_KEYS];
+
+/**
+ * Reserved param keys used by the snapshot encoding itself. Filter keys must
+ * not collide with these - when iterating filter keys we skip any reserved
+ * names so a filter named `pageIndex` cannot stomp on the pagination param.
+ * Derived from `PARAM_KEYS` so the two never drift apart.
+ */
+export const RESERVED_PARAM_KEYS = new Set<string>(Object.values(PARAM_KEYS));
+
+const isNonEmptyExpanded = (e: ExpandedState | undefined): boolean =>
+  e !== undefined && (e === true || Object.keys(e).length > 0);
+
+/**
+ * Build a `PersistedState` snapshot from current state, omitting empty/default
+ * slices so the persisted blob (URL or storage) stays minimal.
+ * `defaultPageSize` lives on `SnapshotInput` so callers don't need to thread
+ * it as a separate argument - it's part of the snapshot's own context.
+ */
+export function snapshotPersistedState(input: SnapshotInput): PersistedState {
+  const out: PersistedState = {};
+
+  const activeFilters: Record<string, string> = {};
+  for (const [k, v] of Object.entries(input.filterValues)) {
+    if (v) activeFilters[k] = v;
+  }
+  if (Object.keys(activeFilters).length > 0) out.filterValues = activeFilters;
+
+  // Only persist pagination when it actually differs from defaults -
+  // pageSize is always a truthy number so `if (pageSize)` would always fire.
+  if (
+    input.pagination.pageIndex > 0 ||
+    input.pagination.pageSize !== input.defaultPageSize
+  ) {
+    out.pagination = input.pagination;
+  }
+
+  if (input.sorting.length > 0) out.sorting = input.sorting;
+  if (input.columnOrder.length > 0) out.columnOrder = input.columnOrder;
+  if (Object.keys(input.columnVisibility).length > 0) {
+    out.columnVisibility = input.columnVisibility;
+  }
+  if (input.columnPinning.left?.length || input.columnPinning.right?.length) {
+    out.columnPinning = input.columnPinning;
+  }
+  if (Object.keys(input.columnSizing).length > 0) {
+    out.columnSizing = input.columnSizing;
+  }
+  if (input.grouping.length > 0) out.grouping = input.grouping;
+  if (isNonEmptyExpanded(input.expanded)) out.expanded = input.expanded;
+
+  return out;
+}
+
+/**
+ * Apply a `PersistedState` blob back onto the controlled setters. Each slice
+ * is independently optional - partial blobs (e.g. only `sorting`) work fine.
+ * Unknown filter keys from a stale URL/blob are silently ignored.
+ */
+export function applyPersistedState(
+  state: PersistedState,
+  target: ApplyPersistedTarget,
+): void {
+  if (state.filterValues) {
+    const next = { ...target.filterValues };
+    for (const key of target.filterKeys) {
+      const v = state.filterValues[key];
+      if (v !== undefined) next[key] = v;
+    }
+    target.setFilterValues(next);
+  }
+  if (state.pagination) target.setPagination(state.pagination);
+  if (state.sorting) target.setSorting(state.sorting);
+  if (state.columnOrder) target.setColumnOrder(state.columnOrder);
+  if (state.columnVisibility)
+    target.setColumnVisibility(state.columnVisibility);
+  if (state.columnPinning) target.setColumnPinning(state.columnPinning);
+  if (state.columnSizing) target.setColumnSizing(state.columnSizing);
+  if (state.grouping) target.setGrouping(state.grouping);
+  if (state.expanded !== undefined) target.setExpanded(state.expanded);
+}
+
+/**
+ * Decode a URL `?...` query string into a `PersistedState` blob. Flat
+ * encoding, hand-editable. `pageIndex` is stored 1-based for human
+ * readability; `pageSize` falls back to `defaultPageSize` when absent.
+ */
+export function readSearchParams(
+  filterKeys: string[],
+  paramMap: Partial<Record<string, string>>,
+  defaultPageSize: number,
+): PersistedState {
+  const out: PersistedState = {};
+  const params = new URLSearchParams(window.location.search);
+  const p = (k: string) => paramMap[k] ?? k;
+
+  const filterValues: Record<string, string> = {};
+  for (const key of filterKeys) {
+    const raw = params.get(p(key));
+    if (raw !== null) filterValues[key] = raw;
+  }
+  if (Object.keys(filterValues).length > 0) out.filterValues = filterValues;
+
+  const rawPage = params.get(p(PARAM_KEYS.pageIndex));
+  const rawSize = params.get(p(PARAM_KEYS.pageSize));
+  if (rawPage !== null || rawSize !== null) {
+    const pageIndex = rawPage !== null ? Math.max(0, Number(rawPage) - 1) : 0;
+    const pageSize =
+      rawSize !== null && Number.isFinite(Number(rawSize))
+        ? Number(rawSize)
+        : defaultPageSize;
+    out.pagination = {
+      pageIndex: Number.isFinite(pageIndex) ? pageIndex : 0,
+      pageSize,
+    };
+  }
+
+  const rawSortBy = params.get(p(PARAM_KEYS.sortBy));
+  const rawSortDir = params.get(p(PARAM_KEYS.sortDir));
+  if (rawSortBy) {
+    out.sorting = [{ id: rawSortBy, desc: rawSortDir === "desc" }];
+  }
+
+  const rawColOrder = params.get(p(PARAM_KEYS.columnOrder));
+  if (rawColOrder) out.columnOrder = rawColOrder.split(",");
+
+  const tryJson = <T>(key: ParamKey): T | undefined => {
+    const raw = params.get(p(key));
+    if (!raw) return undefined;
+    try {
+      return JSON.parse(raw) as T;
+    } catch {
+      return undefined;
+    }
+  };
+
+  const colVis = tryJson<VisibilityState>(PARAM_KEYS.columnVisibility);
+  if (colVis) out.columnVisibility = colVis;
+  const colPin = tryJson<ColumnPinningState>(PARAM_KEYS.columnPinning);
+  if (colPin) out.columnPinning = colPin;
+  const colSize = tryJson<ColumnSizingState>(PARAM_KEYS.columnSizing);
+  if (colSize) out.columnSizing = colSize;
+
+  const rawGrouping = params.get(p(PARAM_KEYS.grouping));
+  if (rawGrouping) out.grouping = rawGrouping.split(",");
+
+  const expanded = tryJson<ExpandedState>(PARAM_KEYS.expanded);
+  if (expanded !== undefined) out.expanded = expanded;
+
+  return out;
+}
+
+/**
+ * Encode a `PersistedState` blob into the URL via `history.replaceState`.
+ * `pageSize` is omitted when it matches `defaultPageSize` so a fresh URL
+ * stays clean; reserved param keys are protected against filter-key collisions.
+ */
+export function writeSearchParams(
+  state: PersistedState,
+  filterKeys: string[],
+  paramMap: Partial<Record<string, string>>,
+  defaultPageSize: number,
+): void {
+  const params = new URLSearchParams(window.location.search);
+  const p = (k: string) => paramMap[k] ?? k;
+
+  // Helper: set a JSON-serialised param or delete it when absent.
+  // Handles all truthy checks uniformly including `false` and `{}` for
+  // `expanded`, which are valid non-default states but would be dropped
+  // by a plain `if (value)` guard.
+  const setJson = (key: ParamKey, value: unknown): void => {
+    if (value !== undefined && value !== null) {
+      params.set(p(key), JSON.stringify(value));
+    } else {
+      params.delete(p(key));
+    }
+  };
+
+  // Filters - every declared filter key must be set or deleted (absent
+  // value === "cleared"). Keys outside the universe are left untouched.
+  const active = state.filterValues ?? {};
+  for (const key of filterKeys) {
+    if (RESERVED_PARAM_KEYS.has(key)) continue;
+    const value = active[key];
+    if (value) params.set(p(key), value);
+    else params.delete(p(key));
+  }
+
+  if (state.pagination && state.pagination.pageIndex > 0) {
+    params.set(p(PARAM_KEYS.pageIndex), String(state.pagination.pageIndex + 1));
+  } else {
+    params.delete(p(PARAM_KEYS.pageIndex));
+  }
+  if (state.pagination && state.pagination.pageSize !== defaultPageSize) {
+    params.set(p(PARAM_KEYS.pageSize), String(state.pagination.pageSize));
+  } else {
+    params.delete(p(PARAM_KEYS.pageSize));
+  }
+
+  if (state.sorting && state.sorting.length > 0) {
+    params.set(p(PARAM_KEYS.sortBy), state.sorting[0].id);
+    params.set(p(PARAM_KEYS.sortDir), state.sorting[0].desc ? "desc" : "asc");
+  } else {
+    params.delete(p(PARAM_KEYS.sortBy));
+    params.delete(p(PARAM_KEYS.sortDir));
+  }
+
+  // Guard against empty arrays serialising to "" which reads back as [''].
+  if (state.columnOrder?.length) {
+    params.set(p(PARAM_KEYS.columnOrder), state.columnOrder.join(","));
+  } else {
+    params.delete(p(PARAM_KEYS.columnOrder));
+  }
+
+  setJson(PARAM_KEYS.columnVisibility, state.columnVisibility ?? null);
+  setJson(PARAM_KEYS.columnPinning, state.columnPinning ?? null);
+  setJson(PARAM_KEYS.columnSizing, state.columnSizing ?? null);
+
+  // Same empty-array guard for grouping.
+  if (state.grouping?.length) {
+    params.set(p(PARAM_KEYS.grouping), state.grouping.join(","));
+  } else {
+    params.delete(p(PARAM_KEYS.grouping));
+  }
+
+  // `expanded` can be `false` or `{}` - both are valid and must be preserved.
+  setJson(
+    PARAM_KEYS.expanded,
+    state.expanded !== undefined ? state.expanded : null,
+  );
+
+  const qs = params.toString();
+  window.history.replaceState(
+    null,
+    "",
+    qs ? `${window.location.pathname}?${qs}` : window.location.pathname,
+  );
+}
+
+/** Read a persisted blob from `localStorage` under `storageKey`. */
+export function readLocalStorage(storageKey: string): PersistedState {
+  try {
+    const raw = window.localStorage.getItem(storageKey);
+    if (!raw) return {};
+    return JSON.parse(raw) as PersistedState;
+  } catch {
+    return {};
+  }
+}
+
+/** Write (or remove, if empty) the persisted blob under `storageKey`. */
+export function writeLocalStorage(
+  storageKey: string,
+  state: PersistedState,
+): void {
+  try {
+    if (Object.keys(state).length === 0) {
+      window.localStorage.removeItem(storageKey);
+    } else {
+      window.localStorage.setItem(storageKey, JSON.stringify(state));
+    }
+  } catch {
+    /* quota exceeded or storage disabled - silently no-op */
+  }
+}
+
+export function normalizeColumnPinningState(
+  pinning: ColumnPinningState | undefined,
+  pinSelectionColumn: boolean,
+  defaultColumnPinning?: ColumnPinningState,
+): ColumnPinningState | undefined {
+  const left = pinning?.left ?? [];
+  const right = pinning?.right ?? [];
+
+  const defaultLeft = defaultColumnPinning?.left ?? [];
+  const defaultRight = defaultColumnPinning?.right ?? [];
+
+  const actualDefaultLeft =
+    pinSelectionColumn && !defaultLeft.includes(SELECT_COLUMN_ID)
+      ? [SELECT_COLUMN_ID, ...defaultLeft]
+      : defaultLeft;
+
+  const finalLeft =
+    pinSelectionColumn && !left.includes(SELECT_COLUMN_ID)
+      ? [SELECT_COLUMN_ID, ...left]
+      : left;
+
+  // Use a Set for O(n) lookup instead of repeated Array.includes (O(n²)).
+  const defaultLeftSet = new Set(actualDefaultLeft);
+  const orderedLeft = [
+    ...actualDefaultLeft.filter((id) => finalLeft.includes(id)),
+    ...finalLeft.filter((id) => !defaultLeftSet.has(id)),
+  ];
+
+  const dynamicRight = right.filter((id) => !defaultRight.includes(id));
+  const orderedRight = [
+    ...dynamicRight,
+    ...defaultRight.filter((id) => right.includes(id)),
+  ];
+
+  if (!pinning && actualDefaultLeft.length === 0 && defaultRight.length === 0) {
+    return undefined;
+  }
+
+  return {
+    left: orderedLeft,
+    right: orderedRight,
+  };
+}

package/registry/components/ui/empty-state/empty-state.module.css

@@ -0,0 +1,26 @@
+.root {
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  justify-content: center;
+  padding: var(--spacing-14) var(--spacing-9);
+  text-align: center;
+  gap: var(--spacing-5);
+}
+
+.icon {
+  color: var(--color-muted-foreground);
+  opacity: 0.5;
+}
+
+.title {
+  font-size: var(--font-size-base);
+  font-weight: 500;
+  color: var(--color-foreground);
+}
+
+.description {
+  font-size: var(--font-size-sm);
+  color: var(--color-muted-foreground);
+  max-width: 300px;
+}

package/registry/components/ui/empty-state/empty-state.tsx

@@ -0,0 +1,32 @@
+import type { ElementType } from "react";
+import { Icon } from "../../primitives/icon/icon";
+import s from "./empty-state.module.css";
+
+type EmptyStateProps = {
+  icon?: ElementType;
+  title: string;
+  description?: string;
+  children?: React.ReactNode;
+};
+
+export function EmptyState({
+  icon: IconComponent,
+  title,
+  description,
+  children,
+}: EmptyStateProps) {
+  return (
+    <div className={s.root}>
+      {IconComponent && (
+        <div className={s.icon}>
+          <Icon size="lg">
+            <IconComponent />
+          </Icon>
+        </div>
+      )}
+      <p className={s.title}>{title}</p>
+      {description && <p className={s.description}>{description}</p>}
+      {children}
+    </div>
+  );
+}

package/registry/components/ui/input-fields/color-picker/color-palette.module.css

@@ -0,0 +1,102 @@
+/* Color palette - standalone wheel + hex input + swatch row.
+   Wraps react-colorful and overrides its sizing/radii via the .react-colorful
+   class names (escaped via :global since they live outside CSS Modules). */
+
+.root {
+  display: flex;
+  flex-direction: column;
+  gap: var(--spacing-4);
+  padding: var(--spacing-4);
+  background-color: var(--color-background);
+  font-family: var(--font-family-1);
+}
+
+.picker {
+  width: 100% !important;
+  height: 12rem !important;
+
+  :global(.react-colorful__saturation) {
+    border-radius: var(--radius-md) var(--radius-md) 0 0;
+  }
+
+  :global(.react-colorful__last-control) {
+    border-radius: 0 0 var(--radius-md) var(--radius-md);
+  }
+
+  :global(.react-colorful__hue),
+  :global(.react-colorful__alpha) {
+    height: var(--spacing-10);
+  }
+
+  :global(.react-colorful__pointer) {
+    width: var(--spacing-10);
+    height: var(--spacing-10);
+  }
+}
+
+.controls {
+  display: flex;
+  align-items: center;
+  gap: var(--spacing-3);
+  height: var(--spacing-11);
+  padding-left: var(--spacing-4);
+  border: 1px solid var(--color-border);
+  border-radius: var(--radius-md);
+  background-color: var(--color-muted);
+  transition:
+    border-color var(--transition-fast),
+    box-shadow var(--transition-fast);
+
+  &:focus-within {
+    border-color: var(--color-ring);
+    box-shadow: var(--shadow-ring);
+  }
+}
+
+.hash {
+  color: var(--color-muted-foreground);
+  font-size: var(--font-size-sm);
+}
+
+.hex_input {
+  flex: 1;
+  min-width: 0;
+  border: 0;
+  outline: none;
+  background: transparent;
+  color: var(--color-foreground);
+  font-family: inherit;
+  font-size: var(--font-size-sm);
+  text-transform: uppercase;
+  letter-spacing: 0.05em;
+}
+
+.swatches {
+  display: grid;
+  grid-template-columns: repeat(10, 1fr);
+  gap: var(--spacing-2);
+}
+
+.swatch_button {
+  width: 100%;
+  aspect-ratio: 1;
+  padding: 0;
+  border: 1px solid var(--color-border);
+  border-radius: var(--radius-sm);
+  cursor: pointer;
+  transition: transform var(--transition-fast);
+
+  &:hover {
+    transform: scale(1.08);
+  }
+
+  &:focus-visible {
+    outline: none;
+    box-shadow: var(--shadow-ring);
+  }
+
+  &[aria-selected="true"] {
+    border-color: var(--color-foreground);
+    border-width: 2px;
+  }
+}

package/registry/components/ui/input-fields/color-picker/color-palette.tsx

@@ -0,0 +1,92 @@
+import { useState, type CSSProperties } from "react";
+import clsx from "clsx";
+import { HexColorPicker, HexColorInput } from "react-colorful";
+import s from "./color-palette.module.css";
+
+export const DEFAULT_SWATCHES: readonly string[] = [
+  "#ef4444",
+  "#f97316",
+  "#eab308",
+  "#22c55e",
+  "#06b6d4",
+  "#3b82f6",
+  "#8b5cf6",
+  "#ec4899",
+  "#64748b",
+  "#000000",
+];
+
+export type ColorPaletteProps = {
+  /** Selected color as hex (controlled). Empty string = unset. */
+  value?: string;
+  /** Initial color (uncontrolled). */
+  defaultValue?: string;
+  /** Fires with the new hex value (`#rrggbb`) whenever it changes. */
+  onChange?: (color: string) => void;
+  /** Optional swatches displayed below the picker. Pass `[]` to hide. */
+  swatches?: readonly string[];
+  className?: string;
+  style?: CSSProperties;
+};
+
+/**
+ * Standalone color palette - saturation/hue picker + hex input + swatch row.
+ * Renderable on its own (e.g. inline in a settings panel) or inside any popover.
+ */
+export const ColorPalette = ({
+  value,
+  defaultValue,
+  onChange,
+  swatches = DEFAULT_SWATCHES,
+  className,
+  style,
+}: ColorPaletteProps) => {
+  const isControlled = value !== undefined;
+  const [internal, setInternal] = useState(defaultValue ?? "#ffffff");
+  const current = isControlled ? value || "#ffffff" : internal;
+
+  const commit = (next: string) => {
+    if (!isControlled) setInternal(next);
+    onChange?.(next);
+  };
+
+  return (
+    <div className={clsx(s.root, className)} style={style}>
+      <HexColorPicker
+        color={current}
+        onChange={commit}
+        className={s.picker}
+      />
+
+      <div className={s.controls}>
+        <span className={s.hash} aria-hidden="true">
+          #
+        </span>
+        <HexColorInput
+          color={current}
+          onChange={commit}
+          className={s.hex_input}
+          placeholder="000000"
+          aria-label="Hex color"
+        />
+      </div>
+
+      {swatches.length > 0 && (
+        <div className={s.swatches} role="listbox" aria-label="Color presets">
+          {swatches.map((c) => (
+            <button
+              key={c}
+              type="button"
+              role="option"
+              aria-selected={current.toLowerCase() === c.toLowerCase()}
+              className={s.swatch_button}
+              style={{ backgroundColor: c }}
+              onClick={() => commit(c)}
+              aria-label={c}
+            />
+          ))}
+        </div>
+      )}
+    </div>
+  );
+};