@payglocal_ui/flux-ui 0.2.3 → 0.2.5

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@payglocal_ui/flux-ui",
-  "version": "0.2.3",
+  "version": "0.2.5",
   "description": "Flux UI primitives — inputs, fields, dialog, data table, charts, calendar, and more (Tailwind v4 + Radix).",
   "license": "MIT",
   "type": "module",

package/src/data-table.tsx

@@ -4,7 +4,7 @@ import type { ReactNode } from "react";
 import { cn } from "./utils";
 import { TableRowSkeleton } from "./skeleton";
 import { EmptyState } from "./empty-state";
-import { ChevronLeft, ChevronRight } from "lucide-react";
+import { ChevronDown, ChevronLeft, ChevronRight } from "lucide-react";
 import { useState } from "react";
 
 export type DataTableDensity = "default" | "comfortable" | "compact";
@@ -24,6 +24,38 @@ function getPageRange(current: number, total: number): (number | "…")[] {
   return pages;
 }
 
+/**
+ * Row expansion: a disclosure column plus a full-width panel rendered directly
+ * beneath the expanded row. Use it when the detail belongs *with* the row in
+ * the flow of the table (a request's headers, a payload, a breakdown) rather
+ * than in a drawer that covers it.
+ *
+ * Leave `expandedKeys` unset for uncontrolled behaviour (the table remembers
+ * which rows are open). Pass `expandedKeys` + `onExpandedChange` to drive it
+ * from outside — needed when opening a row triggers a fetch.
+ */
+export type DataTableExpandable<T> = {
+  /** The panel shown under an expanded row. */
+  render: (row: T, index: number) => ReactNode;
+  /**
+   * Which rows can open at all. Rows that cannot get no toggle and no chevron,
+   * keeping the column's width without implying an affordance that isn't there.
+   * Defaults to every row.
+   */
+  isExpandable?: (row: T, index: number) => boolean;
+  /** Controlled open rows, as `rowKey` values. Omit for uncontrolled. */
+  expandedKeys?: string[];
+  /** Fires on every open/close in controlled mode. */
+  onExpandedChange?: (keys: string[]) => void;
+  /**
+   * Fires only when a row opens, in both modes — the hook for lazily fetching
+   * that row's detail. Not called on close.
+   */
+  onExpand?: (row: T, index: number) => void;
+  /** Accessible name for the toggle. Default "Toggle row details". */
+  toggleLabel?: string;
+};
+
 export type Column<T> = {
   key: string;
   header: ReactNode;
@@ -72,6 +104,22 @@ interface DataTableProps<T> {
    * flush with nothing trailing it. Takes precedence over `rowCta`.
    */
   rowAction?: ReactNode | ((row: T, index: number) => ReactNode);
+  /**
+   * Makes the whole row a click target — the row itself opens a drawer, a
+   * detail page, whatever the table drills into — instead of that living in a
+   * per-cell wrapper or a hover-revealed button.
+   *
+   * The handler sits on the `<tr>`, so the entire row including cell padding
+   * and the empty space between columns is clickable, and the row gets
+   * `cursor-pointer` plus keyboard access (focusable, Enter / Space).
+   *
+   * Clicks that originate inside something interactive — a `<button>`, `<a>`,
+   * a form control, a Radix trigger, or anything marked
+   * `data-row-click-ignore` — do NOT fire this. Copy buttons, per-row menus
+   * and the `rowAction` overlay therefore keep doing only their own job
+   * without each having to stop propagation.
+   */
+  onRowClick?: (row: T, index: number) => void;
   /** Row / cell vertical rhythm and horizontal gutters */
   density?: DataTableDensity;
   /**
@@ -93,6 +141,17 @@ interface DataTableProps<T> {
   footerCountLabels?: { singular: string; plural: string };
   /** With `density="compact"`, use tighter cell gutters (`pl-1.5 pr-2.5` vs `px-3`). Footer keeps normal horizontal padding. */
   snug?: boolean;
+  /**
+   * Extra control at the far left of the built-in footer, before the
+   * "Showing x–y of N" summary — a rows-per-page picker, typically.
+   *
+   * Without it a grid that needs a page-size control has to abandon the
+   * built-in footer and hand-roll one, which is how two different pagers end up
+   * in the same app.
+   */
+  footerLeading?: ReactNode;
+  /** Per-row disclosure panel rendered beneath the row. See `DataTableExpandable`. */
+  expandable?: DataTableExpandable<T>;
 }
 
 export function DataTable<T>({
@@ -110,6 +169,7 @@ export function DataTable<T>({
   rowKey,
   rowCta,
   rowAction,
+  onRowClick,
   density = "default",
   tableLayout = "fixed",
   theadClassName,
@@ -117,6 +177,8 @@ export function DataTable<T>({
   footerSummary = "range",
   footerCountLabels = { singular: "item", plural: "items" },
   snug = false,
+  expandable,
+  footerLeading,
 }: DataTableProps<T>) {
   const isControlled = controlledPage !== undefined;
   const [internalPage, setInternalPage] = useState(1);
@@ -136,6 +198,31 @@ export function DataTable<T>({
   // width while the table still spans the full container width.
   const hasSpacer = tableLayout === "content";
 
+  // Row expansion. Uncontrolled by default; `expandedKeys` hands control to the
+  // caller, which is what a row whose panel fetches its own data needs.
+  // `onExpand` fires only on open, in both modes.
+  const [internalExpanded, setInternalExpanded] = useState<string[]>([]);
+  const isExpandControlled = expandable?.expandedKeys !== undefined;
+  const expandedKeys = isExpandControlled ? expandable!.expandedKeys! : internalExpanded;
+  const hasExpand = expandable != null;
+  /** Every column the expansion panel has to span. */
+  const totalColSpan =
+    columns.length + (hasExpand ? 1 : 0) + (hasSpacer ? 1 : 0) + (hasAction ? 1 : 0);
+
+  /** Whether this row is open — drives both its own styling and the panel. */
+  const rowExpanded = (row: T, index: number) =>
+    hasExpand &&
+    (expandable!.isExpandable?.(row, index) ?? true) &&
+    expandedKeys.includes(rowKeys[index]);
+
+  const toggleExpanded = (key: string, row: T, index: number) => {
+    const isOpen = expandedKeys.includes(key);
+    const next = isOpen ? expandedKeys.filter((k) => k !== key) : [...expandedKeys, key];
+    if (isExpandControlled) expandable!.onExpandedChange?.(next);
+    else setInternalExpanded(next);
+    if (!isOpen) expandable!.onExpand?.(row, index);
+  };
+
   const total = totalRows ?? data.length;
   const totalPages = Math.ceil(total / pageSize);
   const paginated = isControlled ? data : data.slice((page - 1) * pageSize, page * pageSize);
@@ -172,10 +259,51 @@ export function DataTable<T>({
     : compact
       ? "text-[11px] font-semibold text-muted-foreground"
       : "text-[11px] font-semibold text-foreground/75 dark:text-foreground/85";
+  /**
+   * Expansion geometry, in px, derived from the same padding the cells use:
+   *
+   * - `expandIndent` lines the panel's content up with the first DATA column
+   *   (past the 40px disclosure column), so the detail reads as hanging off the
+   *   row rather than starting outside it.
+   * - `expandGuideLeft` is the centre of the chevron, where the vertical
+   *   connector runs — the cue that the panel belongs to the row above.
+   *
+   * Both live here rather than in each consumer's panel: a hardcoded indent in
+   * a feature silently drifts the moment this padding or the column width
+   * changes.
+   */
+  const cellPadLeft = comfortable ? 20 : compact ? (snug ? 6 : 12) : 16;
+  const expandIndent = 40 + cellPadLeft;
+  const expandGuideLeft = cellPadLeft + 10;
+
   // Action overlay geometry: the action floats this many px in from the right
   // edge of the viewport (it has no reserved column — it overlays the row).
   const actionGutter = comfortable ? 20 : compact ? 12 : 16;
 
+  /**
+   * Selector for everything a row-level click must keep its hands off. A click
+   * landing inside one of these belongs to that control alone — a copy button,
+   * a per-row menu, a link, a checkbox, the `rowAction` overlay — so the row
+   * handler ignores it rather than firing as well.
+   *
+   * `data-row-click-ignore` is the escape hatch for anything not covered here
+   * (a custom widget in a cell, a drag handle) without it needing to stop
+   * propagation itself.
+   */
+  const ROW_CLICK_IGNORE =
+    'button, a, input, select, textarea, label, [role="button"], [role="link"], ' +
+    '[role="checkbox"], [role="menuitem"], [role="menu"], [role="dialog"], ' +
+    "[data-row-click-ignore]";
+
+  /** Whether a click/keypress inside a row should reach `onRowClick`. */
+  const isRowClickTarget = (target: EventTarget | null, rowEl: HTMLElement) => {
+    if (!(target instanceof Element)) return false;
+    const interactive = target.closest(ROW_CLICK_IGNORE);
+    // `closest` can walk out of the row entirely (a portalled menu, say); only
+    // a match inside THIS row means the click belonged to that control.
+    return !(interactive && rowEl.contains(interactive));
+  };
+
   return (
     <div
       className={cn(
@@ -205,6 +333,7 @@ export function DataTable<T>({
         >
           {tableLayout === "fixed" && (
             <colgroup>
+              {hasExpand ? <col style={{ width: 40 }} /> : null}
               {columns.map((col) => (
                 <col
                   key={col.key}
@@ -234,6 +363,7 @@ export function DataTable<T>({
                 headerStyle === "surface" ? "border-border" : "border-border/70"
               )}
             >
+              {hasExpand ? <th className={cn(headPad, "w-10 p-0")} aria-hidden /> : null}
               {columns.map((col) => (
                 <th
                   key={col.key}
@@ -264,19 +394,19 @@ export function DataTable<T>({
               Array.from({ length: skeletonRows }).map((_, i) => (
                 <TableRowSkeleton
                   key={i}
-                  cols={columns.length}
+                  cols={columns.length + (hasExpand ? 1 : 0)}
                   density={density}
                   snug={snug}
                 />
               ))
             ) : paginated.length === 0 ? (
               <tr>
-                <td colSpan={columns.length + (hasSpacer ? 1 : 0) + (hasAction ? 1 : 0)}>
+                <td colSpan={totalColSpan}>
                   <EmptyState title={emptyTitle} description={emptyDescription} />
                 </td>
               </tr>
             ) : (
-              paginated.map((row, i) => (
+              paginated.flatMap((row, i) => [
                 <tr
                   key={rowKeys[i]}
                   className={cn(
@@ -285,9 +415,67 @@ export function DataTable<T>({
                     compact && "min-h-[44px]",
                     "hover:bg-muted/40 dark:hover:bg-muted/25",
                     hasAction &&
-                      "hover:shadow-[0_1px_0_rgba(0,0,0,0.04)] dark:hover:shadow-none"
+                      "hover:shadow-[0_1px_0_rgba(0,0,0,0.04)] dark:hover:shadow-none",
+                    // Clickable rows read as clickable, and show a focus ring
+                    // when reached by keyboard. `focus-visible` only, so a
+                    // mouse click does not leave a ring behind on the row.
+                    onRowClick &&
+                      "cursor-pointer focus-visible:outline-none focus-visible:bg-muted/40 dark:focus-visible:bg-muted/25",
+                    // An open row takes its panel's background and drops the
+                    // divider beneath it, so the row and its detail read as one
+                    // block. Hover is pinned to the same value, or moving the
+                    // mouse over an open row would make it flicker away from
+                    // the panel it belongs to.
+                    rowExpanded(row, i) &&
+                      "border-b-0 bg-muted/40 hover:bg-muted/40 dark:bg-muted/25 dark:hover:bg-muted/25"
                   )}
+                  // Keyboard parity with the mouse: the row is reachable by
+                  // Tab and activated by Enter / Space, which a bare <tr> with
+                  // an onClick would not be. No role override — the row stays a
+                  // row for assistive tech rather than claiming to be a button.
+                  tabIndex={onRowClick ? 0 : undefined}
+                  onClick={
+                    onRowClick
+                      ? (e) => {
+                          if (!isRowClickTarget(e.target, e.currentTarget)) return;
+                          onRowClick(row, i);
+                        }
+                      : undefined
+                  }
+                  onKeyDown={
+                    onRowClick
+                      ? (e) => {
+                          if (e.key !== "Enter" && e.key !== " ") return;
+                          // Only the row's own focus activates it; a keypress
+                          // inside a control in the row belongs to that control.
+                          if (e.target !== e.currentTarget) return;
+                          // Space scrolls the page by default.
+                          e.preventDefault();
+                          onRowClick(row, i);
+                        }
+                      : undefined
+                  }
                 >
+                  {hasExpand ? (
+                    <td className={cn(cellPad, "w-10 align-middle")}>
+                      {(expandable!.isExpandable?.(row, i) ?? true) ? (
+                        <button
+                          type="button"
+                          aria-expanded={rowExpanded(row, i)}
+                          aria-label={expandable!.toggleLabel ?? "Toggle row details"}
+                          onClick={() => toggleExpanded(rowKeys[i], row, i)}
+                          className="inline-flex h-5 w-5 items-center justify-center rounded-md text-muted-foreground transition-colors hover:bg-muted hover:text-foreground focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring"
+                        >
+                          <ChevronDown
+                            className={cn(
+                              "h-3.5 w-3.5 transition-transform duration-150",
+                              rowExpanded(row, i) && "rotate-180"
+                            )}
+                          />
+                        </button>
+                      ) : null}
+                    </td>
+                  ) : null}
                   {columns.map((col) => (
                     <td
                       key={col.key}
@@ -358,8 +546,38 @@ export function DataTable<T>({
                       </span>
                     </td>
                   ) : null}
-                </tr>
-              ))
+                </tr>,
+
+                // The panel spans every column, including the toggle, spacer and
+                // action cells, so it reads as one band under its row rather
+                // than as a cell inside the grid.
+                rowExpanded(row, i) ? (
+                  <tr
+                    key={`${rowKeys[i]}__panel`}
+                    className="border-b border-border/60 bg-muted/40 last:border-b-0 dark:bg-muted/25"
+                  >
+                    <td colSpan={totalColSpan} className="p-0 align-top">
+                      <div
+                        className="relative"
+                        style={{ paddingLeft: expandIndent, paddingRight: cellPadLeft }}
+                      >
+                        {/* Connector: a hairline dropping from the chevron down
+                            the panel. The row and its detail share a background
+                            so they read as one block, which on its own leaves
+                            nothing to say the lower half is derived rather than
+                            more row content — this is that cue. Stops short of
+                            the bottom so it reads as hanging, not as a border. */}
+                        <span
+                          aria-hidden
+                          className="absolute top-0 bottom-4 w-px bg-border"
+                          style={{ left: expandGuideLeft }}
+                        />
+                        {expandable!.render(row, i)}
+                      </div>
+                    </td>
+                  </tr>
+                ) : null,
+              ])
             )}
           </tbody>
         </table>
@@ -370,32 +588,38 @@ export function DataTable<T>({
           className={cn(
             "flex items-center gap-4 flex-wrap border-t border-border",
             footerPad,
-            footerSummary === "count" && totalPages <= 1
+            footerSummary === "count" && totalPages <= 1 && !footerLeading
               ? "justify-start"
               : "justify-between"
           )}
         >
-          {footerSummary === "count" ? (
-            <span className="text-[12px] text-muted-foreground tabular-nums">
-              <span className="font-medium text-foreground">{total}</span>{" "}
-              {total === 1
-                ? footerCountLabels.singular
-                : footerCountLabels.plural}
-            </span>
-          ) : (
-            <span className="text-[12px] text-muted-foreground tabular-nums">
-              Showing{" "}
-              <span className="text-foreground font-medium">
-                {Math.min((page - 1) * pageSize + 1, total)}–
-                {Math.min(page * pageSize, total)}
-              </span>{" "}
-              of{" "}
-              <span className="text-foreground font-medium">
-                {total.toLocaleString()}
-              </span>{" "}
-              {total !== 1 ? "results" : "result"}
-            </span>
-          )}
+          {/* `footerLeading` (a rows-per-page picker, typically) groups with the
+              summary on the left rather than becoming a third item the
+              justify-between would fling to its own corner. */}
+          <div className="flex items-center gap-3">
+            {footerLeading}
+            {footerSummary === "count" ? (
+              <span className="text-[12px] text-muted-foreground tabular-nums">
+                <span className="font-medium text-foreground">{total}</span>{" "}
+                {total === 1
+                  ? footerCountLabels.singular
+                  : footerCountLabels.plural}
+              </span>
+            ) : (
+              <span className="text-[12px] text-muted-foreground tabular-nums">
+                Showing{" "}
+                <span className="text-foreground font-medium">
+                  {Math.min((page - 1) * pageSize + 1, total)}–
+                  {Math.min(page * pageSize, total)}
+                </span>{" "}
+                of{" "}
+                <span className="text-foreground font-medium">
+                  {total.toLocaleString()}
+                </span>{" "}
+                {total !== 1 ? "results" : "result"}
+              </span>
+            )}
+          </div>
 
           {(footerSummary === "range" || footerSummary === "count") &&
             totalPages > 1 && (

package/src/dropdown-menu.tsx

@@ -74,7 +74,10 @@ const DropdownMenuItem = React.forwardRef<
   <DropdownMenuPrimitive.Item
     ref={ref}
     className={cn(
-      "relative flex cursor-default select-none items-center gap-2 rounded-lg px-3 py-2.5 text-[15px] outline-none transition-colors",
+      // 13px / tighter padding: a menu drops out of a toolbar button or a
+      // compact table control, and at 15px with 10px vertical padding it read
+      // as a larger, separate UI than the control that opened it.
+      "relative flex cursor-default select-none items-center gap-2 rounded-lg px-2.5 py-1.5 text-[13px] outline-none transition-colors",
       "focus:bg-muted focus:text-foreground data-[disabled]:pointer-events-none data-[disabled]:opacity-50",
       inset && "pl-8",
       className

package/src/index.ts

@@ -194,6 +194,7 @@ export {
   SelectScrollUpButton,
   SelectScrollDownButton,
 } from "./select";
+export type { SelectTriggerSize } from "./select";
 export { Command, CommandInput, CommandList, CommandEmpty, CommandGroup, CommandItem, CommandSeparator, CommandShortcut } from "./command";
 export type {
   CommandProps,
@@ -232,7 +233,7 @@ export { Shimmer, StatCardSkeleton, TableRowSkeleton, ChartSkeleton } from "./sk
 
 // Data display
 export { DataTable } from "./data-table";
-export type { Column, DataTableDensity, DataTableFooterSummary, DataTableHeaderStyle } from "./data-table";
+export type { Column, DataTableDensity, DataTableExpandable, DataTableFooterSummary, DataTableHeaderStyle } from "./data-table";
 export { EmptyState } from "./empty-state";
 export { PageHeader } from "./page-header";
 export { Code, CodeBlock } from "./code";

package/src/select.tsx

@@ -9,14 +9,31 @@ const Select = SelectPrimitive.Root;
 const SelectGroup = SelectPrimitive.Group;
 const SelectValue = SelectPrimitive.Value;
 
+/**
+ * `md` (default) is the form-field trigger. `sm` is for dense furniture — a
+ * rows-per-page picker in a table footer, a control inside a toolbar — where
+ * the full-height field towers over everything beside it.
+ *
+ * This is a size prop rather than a job for `className` because the base sets
+ * `min-h-11`, which beats an `h-8` utility: every caller wanting a short
+ * trigger had to override min-height, padding, gap and text size together.
+ */
+export type SelectTriggerSize = "sm" | "md";
+
+const selectTriggerSizes: Record<SelectTriggerSize, string> = {
+  md: "h-11 min-h-11 gap-2.5 px-4 py-2 text-[15px]",
+  sm: "h-7 min-h-7 w-auto gap-1 px-2 py-0 text-[12px]",
+};
+
 const SelectTrigger = React.forwardRef<
   React.ElementRef<typeof SelectPrimitive.Trigger>,
-  React.ComponentPropsWithoutRef<typeof SelectPrimitive.Trigger>
->(({ className, children, ...props }, ref) => (
+  React.ComponentPropsWithoutRef<typeof SelectPrimitive.Trigger> & { size?: SelectTriggerSize }
+>(({ className, children, size = "md", ...props }, ref) => (
   <SelectPrimitive.Trigger
     ref={ref}
     className={cn(
-      "flex h-11 min-h-11 w-full items-center justify-between gap-2.5 rounded-lg border border-border bg-card px-4 py-2 text-[15px] text-foreground shadow-sm outline-none",
+      "flex w-full items-center justify-between rounded-lg border border-border bg-card text-foreground shadow-sm outline-none",
+      selectTriggerSizes[size],
       "ring-ring/50 focus-visible:ring-2 disabled:cursor-not-allowed disabled:opacity-50",
       "[&>span]:line-clamp-1",
       className