@payglocal_ui/flux-ui 0.2.5 → 0.3.0

package/src/copyable-cell.tsx

@@ -0,0 +1,253 @@
+"use client";
+
+import { useEffect, useRef, useState, type MouseEvent } from "react";
+import { Check, Copy } from "lucide-react";
+import { toast } from "sonner";
+import { Button } from "./button";
+import { Tooltip, TooltipContent, TooltipProvider, TooltipTrigger } from "./tooltip";
+import { cn } from "./utils";
+
+export interface CopyableCellProps {
+  /**
+   * The full value. This is what reaches the clipboard, the tooltip and the
+   * accessible name — always, even when `display` shortens what is on screen.
+   * Shortening what is shown must never shorten what the user walks away with.
+   */
+  value?: string | null;
+  /** What to render instead of `value` — an elided form, typically. */
+  display?: string;
+  /** The noun in the tooltip and the toast: "Transaction ID copied". */
+  label?: string;
+  /**
+   * Makes the value the handle that opens the row, rendered as a link. Without
+   * it the value is plain text that can still be copied.
+   *
+   * The copy button stops propagation, so an id that opens a row does not also
+   * open it when copied.
+   */
+  onClick?: () => void;
+  /** Render the value in the primary colour. */
+  accent?: boolean;
+  monospace?: boolean;
+  /** What an absent value renders as. Default the em dash every grid uses. */
+  fallback?: string;
+  /**
+   * - `inline` (default) — the value, with its own copy button beside it.
+   * - `cell` — the **whole** element is the copy target and the value
+   *   underlines on hover. For a fixed-width column where a separate button
+   *   would cost more room than the value it copies.
+   *
+   * `cell` ignores `onClick`: a cell cannot both copy and open the row on the
+   * same click.
+   */
+  variant?: "inline" | "cell";
+  /**
+   * Keep the copy button invisible until the row (or any `group` ancestor) is
+   * hovered, or the button itself is focused. Opacity only — it keeps its
+   * space, so revealing it never shifts the row.
+   *
+   * Defaults to `true`, which is what a table wants: twelve permanent copy
+   * buttons are twelve pieces of chrome competing with the data. Pass `false`
+   * for a detail field, where there is no row to hover and the control would
+   * simply never appear. Pointer-coarse devices have no hover to give, so it
+   * stays visible there regardless.
+   */
+  revealOnHover?: boolean;
+  /**
+   * Announce the copy with a toast. Off for a field whose tick and tooltip are
+   * feedback enough, and where a toast per copy would be noise.
+   */
+  showToast?: boolean;
+  /** Extra classes on the value itself, e.g. a muted secondary placement. */
+  valueClassName?: string;
+  className?: string;
+}
+
+/**
+ * The canonical identifier cell: a value plus a copy button that fades in on
+ * the row's hover.
+ *
+ * Reveal-on-hover is the point. A table of twelve ids with twelve permanent
+ * copy buttons is twelve pieces of chrome competing with the data; the row the
+ * pointer is on is the only one whose button is useful.
+ *
+ * It relies on the row's own `group` class, which every `DataTable` `<tr>`
+ * already carries. Outside a DataTable row, pass `className="group"` on an
+ * ancestor or the button stays hidden.
+ */
+export function CopyableCell({
+  value,
+  display,
+  label = "Value",
+  onClick,
+  accent = false,
+  monospace = false,
+  fallback = "—",
+  variant = "inline",
+  revealOnHover = true,
+  showToast = true,
+  valueClassName,
+  className,
+}: CopyableCellProps) {
+  const [copied, setCopied] = useState(false);
+  const timer = useRef<ReturnType<typeof setTimeout> | null>(null);
+
+  // The tick reverts on a timer, so an unmount mid-flight must not leave it
+  // running against a gone component.
+  useEffect(
+    () => () => {
+      if (timer.current) clearTimeout(timer.current);
+    },
+    []
+  );
+
+  if (!value) return <span className="text-muted-foreground">{fallback}</span>;
+
+  const copyValue = async () => {
+    try {
+      await navigator.clipboard.writeText(value);
+      setCopied(true);
+      if (showToast) toast.success(`${label} copied`);
+      if (timer.current) clearTimeout(timer.current);
+      timer.current = setTimeout(() => setCopied(false), 1500);
+    } catch {
+      // Clipboard blocked — an insecure context, or permission denied. Copying
+      // an id is not worth an error toast over; the value is still on screen.
+    }
+  };
+
+  /**
+   * Copying is never also a request to open the record the value belongs to,
+   * so the event stops here. DataTable's own `onRowClick` already skips a
+   * click on a button; this also covers rows made clickable some other way.
+   */
+  const copy = (e: MouseEvent) => {
+    e.stopPropagation();
+    void copyValue();
+  };
+
+  const text = cn(
+    "min-w-0 truncate font-medium",
+    accent ? "text-primary" : "text-foreground",
+    monospace && "font-mono",
+    valueClassName
+  );
+
+  /** Names the full value when the screen only shows part of it. */
+  const elided = display !== undefined && display !== value;
+  const copyHint = copied ? "Copied" : elided ? `Copy ${value}` : `Copy ${label}`;
+
+  if (variant === "cell") {
+    // The whole box copies, so there is no separate button to reach for — in a
+    // narrow column that button costs more width than the value it copies. The
+    // value underlines on hover to say the box is the target; the icon is a
+    // marker, not a second control, which is why it is not focusable.
+    return (
+      <TooltipProvider delayDuration={200}>
+        <Tooltip>
+          <TooltipTrigger asChild>
+            <div
+              role="button"
+              tabIndex={0}
+              onClick={copy}
+              onKeyDown={(e) => {
+                if (e.key !== "Enter" && e.key !== " ") return;
+                e.preventDefault();
+                e.stopPropagation();
+                void copyValue();
+              }}
+              aria-label={copied ? "Copied to clipboard" : `Copy ${value}`}
+              className={cn(
+                "group/copy flex min-w-0 cursor-pointer items-center gap-1 rounded-md",
+                "focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring/35",
+                className
+              )}
+            >
+              <span className={cn(text, "flex-1 group-hover/copy:underline")}>
+                {display ?? value}
+              </span>
+              {copied ? (
+                <Check className="h-3 w-3 shrink-0 text-muted-foreground" />
+              ) : (
+                <Copy
+                  className={cn(
+                    "h-3 w-3 shrink-0 text-muted-foreground",
+                    revealOnHover &&
+                      "opacity-0 transition-opacity group-hover/copy:opacity-100 group-focus-visible/copy:opacity-100 [@media(hover:none)]:opacity-100"
+                  )}
+                />
+              )}
+            </div>
+          </TooltipTrigger>
+          <TooltipContent side="top" className="text-xs">
+            {copied ? "Copied" : "Copy"}
+          </TooltipContent>
+        </Tooltip>
+      </TooltipProvider>
+    );
+  }
+
+  return (
+    <div className={cn("group/copy flex min-w-0 items-center gap-1", className)}>
+      {onClick ? (
+        // A bare <button>, deliberately, where the rest of flux would reach for
+        // `Button variant="link"`. That variant hard-codes `text-[15px]`, and
+        // the obvious override — `text-[inherit]` — does not beat it: Tailwind
+        // and tailwind-merge read `text-[<non-length>]` as a COLOUR, so the
+        // size class survives and the cell renders 2px larger than every other
+        // cell in the row. Preflight already gives a bare button `font: inherit`,
+        // so this simply inherits the cell's size at whatever density the table
+        // is using, which is what a cell should do.
+        <button
+          type="button"
+          onClick={onClick}
+          title={value}
+          className={cn(
+            "cursor-pointer bg-transparent p-0 text-left underline-offset-4",
+            "hover:underline focus-visible:underline focus-visible:outline-none",
+            text
+          )}
+        >
+          {display ?? value}
+        </button>
+      ) : (
+        <span className={text} title={value}>
+          {display ?? value}
+        </span>
+      )}
+
+      <TooltipProvider delayDuration={200}>
+        <Tooltip>
+          <TooltipTrigger asChild>
+            <Button
+              type="button"
+              variant="ghost"
+              onClick={copy}
+              aria-label={`Copy ${label}`}
+              // `group-hover` is the DataTable row; `group-hover/copy` covers a
+              // cell used outside one, where hovering the value itself should
+              // still reveal the button.
+              className={cn(
+                "h-5 w-5 min-h-0 min-w-0 shrink-0 rounded-md p-0 text-muted-foreground",
+                revealOnHover && [
+                  "opacity-0 transition-opacity",
+                  // `group-hover` is the DataTable row; `group-hover/copy`
+                  // covers a cell used outside one, where hovering the value
+                  // itself should still reveal the button.
+                  "focus-visible:opacity-100 group-hover:opacity-100 group-hover/copy:opacity-100",
+                  // No hover to wait for on a touch device, so it simply shows.
+                  "[@media(hover:none)]:opacity-100",
+                ]
+              )}
+            >
+              {copied ? <Check className="h-3 w-3" /> : <Copy className="h-3 w-3" />}
+            </Button>
+          </TooltipTrigger>
+          <TooltipContent side="top" className="text-xs">
+            {copyHint}
+          </TooltipContent>
+        </Tooltip>
+      </TooltipProvider>
+    </div>
+  );
+}

package/src/data-card-list.tsx

@@ -0,0 +1,188 @@
+"use client";
+
+import type { ReactNode } from "react";
+import { ChevronLeft, ChevronRight } from "lucide-react";
+import { Button } from "./button";
+import { normalizePagination, type DataTablePagination } from "./data-table";
+import { EmptyState } from "./empty-state";
+import { Shimmer } from "./skeleton";
+import { cn } from "./utils";
+
+/**
+ * The narrow-viewport counterpart to {@link DataTableCard}: the same records as
+ * a stack of cards.
+ *
+ * It is a separate component rather than a mode of the table on purpose. A
+ * card list is not a table with its columns hidden — it chooses a handful of
+ * fields, gives them a hierarchy, and drops the rest. Folding that into
+ * `DataTableCard` would mean one component carrying two layouts and a
+ * breakpoint, and every table paying for props it does not use.
+ *
+ * Pair the two with CSS, not a media-query hook:
+ *
+ * ```tsx
+ * <DataTableCard className="hidden lg:block" … />
+ * <DataCardList className="lg:hidden" … />
+ * ```
+ *
+ * Both render; CSS shows one. A JS breakpoint would have to start with a guess
+ * on the server, so one cohort sees the wrong layout on first paint, and a
+ * resize across the breakpoint unmounts the visible half — taking scroll
+ * position and any open row with it.
+ *
+ * What it owns is the surface, not the card: the bordered container, the
+ * loading skeletons, the empty state and the pager. Those are the four things
+ * every hand-rolled card list in the apps reimplemented, and the four that had
+ * drifted. The card itself stays with the feature, via `renderCard` — that is
+ * the part that genuinely differs per record.
+ */
+export interface DataCardListProps<T> {
+  rows: T[];
+  rowKey: (row: T) => string;
+  /** One record as a card. The only part a feature has to write. */
+  renderCard: (row: T, index: number) => ReactNode;
+  isLoading?: boolean;
+  /**
+   * The loading placeholder for one card. Omit for a generic card-shaped
+   * shimmer — good enough for most lists, and worth replacing only where the
+   * real card has a distinctive shape worth pre-announcing.
+   */
+  renderSkeleton?: (index: number) => ReactNode;
+  skeletonCount?: number;
+  emptyTitle?: string;
+  emptyDescription?: string;
+  /**
+   * Replaces the list when there are no rows — an illustrated placeholder,
+   * typically. Same split as `DataTableCard`: the title/description pair is the
+   * plain "nothing matched" state, this is the drawn first-run one.
+   */
+  emptyState?: ReactNode;
+  /**
+   * Replaces the rows entirely when the request failed.
+   *
+   * Distinct from an empty result with error-worded copy: that keeps the
+   * column headers, which is right for "nothing matched" and wrong for "we
+   * could not load this" — headers imply data was fetched and found empty.
+   */
+  errorState?: ReactNode;
+  /**
+   * The same {@link DataTablePagination} the table takes, so a list and the
+   * table beside it cannot disagree about which page they are on. Rendered as
+   * a compact Prev / Next pager rather than a numbered strip: a row of page
+   * numbers is the first thing to go wrong on a phone.
+   */
+  pagination?: DataTablePagination;
+  /** Wraps the list in the same bordered card the table uses. Default true. */
+  bordered?: boolean;
+  className?: string;
+}
+
+/** A generic card-shaped placeholder: a title line, two details, a value. */
+function DefaultCardSkeleton() {
+  return (
+    <div className="rounded-xl border border-border bg-card p-3.5">
+      <div className="flex items-center gap-2">
+        <Shimmer className="h-4 w-40" />
+        <Shimmer className="ml-auto h-3.5 w-5" rounded="sm" />
+      </div>
+      <Shimmer className="mt-2 h-3 w-28" />
+      <Shimmer className="mt-1.5 h-3 w-44" />
+      <Shimmer className="mt-2.5 h-3.5 w-32" />
+    </div>
+  );
+}
+
+export function DataCardList<T>({
+  rows,
+  rowKey,
+  renderCard,
+  isLoading = false,
+  renderSkeleton,
+  skeletonCount = 6,
+  emptyTitle = "Nothing to show",
+  emptyDescription,
+  emptyState,
+  errorState,
+  pagination = { mode: "client" },
+  bordered = true,
+  className,
+}: DataCardListProps<T>) {
+  const pager = normalizePagination(pagination, rows.length, 1);
+
+  // Only `client` mode holds every row, so only `client` mode slices; the
+  // others were handed exactly this page. Same rule as the table.
+  const page = pager.sliceLocally
+    ? rows.slice((pager.page - 1) * pager.pageSize, pager.page * pager.pageSize)
+    : rows;
+
+  const isCursor = pager.totalPages === undefined;
+  const hasPrev = isCursor ? !!pager.hasPrev : pager.page > 1;
+  const hasNext = isCursor ? !!pager.hasNext : pager.page < (pager.totalPages ?? 1);
+
+  const goPrev = () =>
+    isCursor ? pager.onPrev?.() : pagination.mode === "page" && pagination.onPageChange(pager.page - 1);
+  const goNext = () =>
+    isCursor ? pager.onNext?.() : pagination.mode === "page" && pagination.onPageChange(pager.page + 1);
+
+  const showPager =
+    !errorState && pager.showFooter && !isLoading && page.length > 0 && (hasPrev || hasNext);
+
+  return (
+    <div
+      className={cn(
+        "flex flex-col gap-3 p-4",
+        bordered && "rounded-xl border border-border bg-card",
+        className
+      )}
+    >
+      {errorState ? (
+        errorState
+      ) : isLoading ? (
+        Array.from({ length: skeletonCount }).map((_, i) =>
+          renderSkeleton ? (
+            <div key={i}>{renderSkeleton(i)}</div>
+          ) : (
+            <DefaultCardSkeleton key={i} />
+          )
+        )
+      ) : page.length === 0 ? (
+        (emptyState ?? <EmptyState title={emptyTitle} description={emptyDescription} />)
+      ) : (
+        page.map((row, i) => <div key={rowKey(row)}>{renderCard(row, i)}</div>)
+      )}
+
+      {showPager && (
+        <div className="flex items-center justify-between gap-2 pt-1">
+          <Button
+            type="button"
+            variant="ghost"
+            size="sm"
+            disabled={!hasPrev}
+            onClick={goPrev}
+            leftIcon={<ChevronLeft className="h-3.5 w-3.5" />}
+          >
+            Prev
+          </Button>
+
+          {/* No total in cursor mode, so no "of N" — the same honesty the
+              table's own footer keeps. */}
+          <span className="text-[12px] tabular-nums text-muted-foreground">
+            Page {pager.page}
+            {pager.totalPages !== undefined ? ` of ${pager.totalPages}` : ""}
+          </span>
+
+          <Button
+            type="button"
+            variant="ghost"
+            size="sm"
+            disabled={!hasNext}
+            onClick={goNext}
+            rightIcon={<ChevronRight className="h-3.5 w-3.5" />}
+          >
+            Next
+          </Button>
+        </div>
+      )}
+    </div>
+  );
+}

package/src/data-table-card.tsx

@@ -0,0 +1,205 @@
+"use client";
+
+import type { CSSProperties, ReactNode } from "react";
+import { DataTable } from "./data-table";
+import type {
+  Column,
+  DataTableDensity,
+  DataTableExpandable,
+  DataTablePagination,
+  DataTableSorting,
+} from "./data-table";
+import { cn } from "./utils";
+
+/**
+ * The canonical table surface: one bordered card holding a title, tabs, a
+ * filter toolbar, the grid, and a footer — in that order, with the same
+ * dividers and gutters every time.
+ *
+ * `DataTable` on its own is the grid. This is everything around it, and it
+ * exists because that surrounding chrome is where tables actually drift: one
+ * feature puts its filters above the card, another inside it; one draws a
+ * divider under the tabs, another does not; one pads the toolbar `py-3` and the
+ * next `py-2.5`. None of that is a decision a feature should be making.
+ *
+ * Pagination goes through `pagination`, in every mode — including cursor APIs
+ * that carry no row total. The `footer` slot is for a footer that is genuinely
+ * not a pager; passing one hides the table's own.
+ */
+export interface DataTableCardProps<T> {
+  columns: Column<T>[];
+  data: T[];
+  rowKey: (row: T) => string;
+  isLoading?: boolean;
+  /**
+   * Section title. For a grid that names itself — an analytics section like
+   * "Top 10 Merchants by Volume" — rather than a page-level grid, whose name is
+   * the page header. Renders above `tabs`.
+   */
+  title?: string;
+  /** One line under the title. Only meaningful with `title`. */
+  description?: string;
+  /** Controls on the title row, flush right (a period toggle, Refresh, …). */
+  actions?: ReactNode;
+  /** Tab bar near the top of the card, above the toolbar. */
+  tabs?: ReactNode;
+  /** Filters / search / action buttons, as a row inside the card top. */
+  toolbar?: ReactNode;
+  /**
+   * A non-pager footer inside the card bottom. Hides the table's own footer, so
+   * do NOT use it for pagination — that is what `pagination` is for, in every
+   * mode. Hand-rolling a pager here is how two different pagers end up in one
+   * app.
+   */
+  footer?: ReactNode;
+  emptyTitle?: string;
+  emptyDescription?: string;
+  /**
+   * Replaces the grid when there are no rows — an illustrated placeholder,
+   * typically.
+   *
+   * `emptyTitle` / `emptyDescription` give the table's own text-only empty
+   * state, which keeps the column headers and is right for "nothing matched
+   * your filters". This is for the first-run case, where there is no data yet
+   * because none has ever existed, and a drawn state says that better than a
+   * header row over nothing.
+   */
+  emptyState?: ReactNode;
+  /**
+   * Replaces the rows entirely when the request failed.
+   *
+   * Distinct from an empty result with error-worded copy: that keeps the
+   * column headers, which is right for "nothing matched" and wrong for "we
+   * could not load this" — headers imply data was fetched and found empty.
+   */
+  errorState?: ReactNode;
+  /** See {@link DataTablePagination}. Omit for client-side paging at 10/page. */
+  pagination?: DataTablePagination;
+  /** See {@link DataTableSorting}. */
+  sorting?: DataTableSorting;
+  rowAction?: ReactNode | ((row: T, index: number) => ReactNode);
+  /**
+   * Makes the whole row a click target, for a grid that drills into a detail
+   * view. Passed straight through, so it brings the keyboard affordances with
+   * it and does not fire for clicks landing on a button, link or form control
+   * inside a cell.
+   */
+  onRowClick?: (row: T, index: number) => void;
+  /** Defaults to "content"; pass "fixed" for grids with frozen sticky columns. */
+  tableLayout?: "auto" | "fixed" | "content";
+  /** Per-row disclosure panel rendered beneath the row. */
+  expandable?: DataTableExpandable<T>;
+  /** Row rhythm. Defaults to `compact`, which is what a data-dense grid wants. */
+  density?: DataTableDensity;
+  skeletonRows?: number;
+  /**
+   * CSS max-height for the internally scrolling body, so the toolbar and footer
+   * stay put while the rows scroll and the page itself does not grow.
+   *
+   * The default assumes a page header plus this card's toolbar; a card that
+   * also carries a `tabs` row needs a smaller cap, or the page starts scrolling
+   * as well. Pass `"none"` to let the card grow with its content instead.
+   */
+  maxBodyHeight?: string;
+  className?: string;
+}
+
+export function DataTableCard<T>({
+  columns,
+  data,
+  rowKey,
+  isLoading,
+  title,
+  description,
+  actions,
+  tabs,
+  toolbar,
+  footer,
+  emptyTitle,
+  emptyDescription,
+  emptyState,
+  errorState,
+  pagination,
+  sorting,
+  rowAction,
+  onRowClick,
+  tableLayout = "content",
+  expandable,
+  density = "compact",
+  skeletonRows = 8,
+  maxBodyHeight = "calc(100vh - 260px)",
+  className,
+}: DataTableCardProps<T>) {
+  const capped = maxBodyHeight !== "none";
+  /** The illustrated stand-in only applies once loading has settled. */
+  const showEmptyState = !!emptyState && !isLoading && data.length === 0;
+
+  return (
+    <div
+      className={cn("overflow-hidden rounded-xl border border-border bg-card", className)}
+      style={
+        capped ? ({ ["--dtc-max-body" as string]: maxBodyHeight } as CSSProperties) : undefined
+      }
+    >
+      {title && (
+        <div className="flex flex-wrap items-start justify-between gap-3 border-b border-border px-4 py-3.5">
+          <div className="min-w-0">
+            <h2 className="text-sm font-semibold text-foreground">{title}</h2>
+            {description && <p className="mt-0.5 text-xs text-muted-foreground">{description}</p>}
+          </div>
+          {actions && <div className="flex shrink-0 items-center gap-2">{actions}</div>}
+        </div>
+      )}
+
+      {tabs && <div className="border-b border-border px-4 pt-3">{tabs}</div>}
+      {toolbar && <div className="border-b border-border px-4 py-3">{toolbar}</div>}
+
+      {errorState}
+      {!errorState && showEmptyState && emptyState}
+
+      <DataTable<T>
+        className={cn(
+          (showEmptyState || errorState) && "hidden",
+          // The card already draws the border and radius; a second set inside
+          // it would read as a table nested in a card.
+          "rounded-none border-0",
+          footer && "[&>.border-t]:hidden",
+          // Cap the scroll container so the body scrolls internally while the
+          // toolbar and footer stay fixed. The cap comes from an inline custom
+          // property rather than a class, so a caller's `className` override
+          // cannot depend on class-merge order.
+          capped &&
+            "[&>div:first-child]:max-h-[var(--dtc-max-body)] [&>div:first-child]:overflow-y-auto"
+        )}
+        // The header sticks to the top of that scroll area, which is only
+        // meaningful while the body actually scrolls.
+        theadClassName={capped ? "sticky top-0 z-20 [&_th]:bg-card" : undefined}
+        tableLayout={tableLayout}
+        columns={columns}
+        data={data}
+        isLoading={isLoading}
+        rowKey={rowKey}
+        skeletonRows={skeletonRows}
+        density={density}
+        pagination={pagination}
+        sorting={sorting}
+        rowAction={rowAction}
+        onRowClick={onRowClick}
+        emptyTitle={emptyTitle}
+        emptyDescription={emptyDescription}
+        expandable={expandable}
+      />
+
+      {footer && (
+        <div className="flex flex-wrap items-center justify-between gap-3 border-t border-border px-4 py-3">
+          {footer}
+        </div>
+      )}
+    </div>
+  );
+}
+
+/** Right-aligned group for toolbar action buttons. */
+export function TableToolbarActions({ children }: { children: ReactNode }) {
+  return <div className="ml-auto flex items-center gap-2">{children}</div>;
+}