@sixthshift/design-system 0.7.0 → 0.8.0

package/src/components/DataTable/DataTable.tsx

@@ -0,0 +1,261 @@
+"use client";
+
+import { useControllableState } from "@sixthshift/design-system/hooks";
+import { cn } from "@sixthshift/design-system/utils";
+import { cva, type VariantProps } from "class-variance-authority";
+import { ArrowDown, ArrowUp, ChevronsUpDown } from "lucide-react";
+import { forwardRef, type HTMLAttributes, type KeyboardEvent, type ReactElement, type ReactNode, type Ref, useMemo } from "react";
+
+/**
+ * Geometry only. Every colour reads a `--data-table-*` component token whose
+ * value is decided by src/components/DataTable/data-table.recipe.css.
+ *
+ * `size` is cell density: `sm` for back-office lists scanned dozens of rows at
+ * a time, `md` for tables that are the page's main content.
+ */
+const cellVariants = cva("px-3 align-middle", {
+  variants: {
+    size: {
+      sm: "h-9 py-1.5 text-xs",
+      md: "h-11 py-2 text-sm",
+    },
+  },
+  defaultVariants: {
+    size: "md",
+  },
+});
+
+export type DataTableSize = NonNullable<VariantProps<typeof cellVariants>["size"]>;
+
+export type DataTableAlign = "start" | "center" | "end";
+
+export type DataTableColumn<Row> = {
+  /** Stable key — also what `sort.columnId` refers to. */
+  id: string;
+  /** Header content. */
+  header: ReactNode;
+  /** Cell content for one row. */
+  cell: (row: Row) => ReactNode;
+  /**
+   * Makes the column sortable. The returned value is what rows are compared
+   * by — return cents, not a formatted price, and an ISO date, not "Tue 3rd".
+   */
+  sortValue?: (row: Row) => string | number;
+  /** Text alignment for header and cells. Numbers read best at `end`. */
+  align?: DataTableAlign;
+  /** A CSS width for the column, e.g. `"8rem"` or `"20%"`. */
+  width?: string;
+  /** Extra classes for this column's `<td>`s. */
+  className?: string;
+};
+
+export type DataTableSortDirection = "asc" | "desc";
+
+export type DataTableSort = {
+  columnId: string;
+  direction: DataTableSortDirection;
+};
+
+export type DataTableProps<Row> = Omit<HTMLAttributes<HTMLDivElement>, "children"> &
+  VariantProps<typeof cellVariants> & {
+    columns: readonly DataTableColumn<Row>[];
+    rows: readonly Row[];
+    /** Stable id per row, used as the React key. */
+    getRowId: (row: Row) => string;
+    /** Controlled sort. `null` is unsorted — rows in the order given. */
+    sort?: DataTableSort | null;
+    /** Initial sort in uncontrolled mode. */
+    defaultSort?: DataTableSort | null;
+    /** Called when a header is clicked: ascending, then descending, then unsorted. */
+    onSortChange?: (sort: DataTableSort | null) => void;
+    /**
+     * Report sort changes without reordering `rows`, for data sorted where it
+     * is fetched. The headers still show the sort state.
+     */
+    manualSorting?: boolean;
+    /** Makes every row activatable by pointer, `Enter` or `Space`. */
+    onRowClick?: (row: Row) => void;
+    /** Shown in place of the body when `rows` is empty. */
+    empty?: ReactNode;
+    /** Names the table for assistive tech. Visually hidden unless `showCaption`. */
+    caption?: ReactNode;
+    showCaption?: boolean;
+    /** Keep the header row visible while the wrapper scrolls vertically. Give the wrapper a height via `className`. */
+    stickyHeader?: boolean;
+  };
+
+const alignClass: Record<DataTableAlign, string> = {
+  start: "text-start",
+  center: "text-center",
+  end: "text-end",
+};
+
+const ariaSort = { asc: "ascending", desc: "descending" } as const;
+
+function nextSort(current: DataTableSort | null, columnId: string): DataTableSort | null {
+  if (current?.columnId !== columnId) return { columnId, direction: "asc" };
+  return current.direction === "asc" ? { columnId, direction: "desc" } : null;
+}
+
+function compare(a: string | number, b: string | number): number {
+  if (typeof a === "number" && typeof b === "number") return a - b;
+  return String(a).localeCompare(String(b), undefined, { numeric: true, sensitivity: "base" });
+}
+
+/**
+ * `forwardRef` erases the generic, so the implementation takes the ref as an
+ * argument and the export below restores `<Row>` — the same arrangement
+ * Select.tsx uses for `<T>`.
+ */
+const DataTableRoot = forwardRef(function DataTableRoot<Row>(
+  {
+    className,
+    columns,
+    rows,
+    getRowId,
+    size = "md",
+    sort: controlledSort,
+    defaultSort = null,
+    onSortChange,
+    manualSorting = false,
+    onRowClick,
+    empty,
+    caption,
+    showCaption = false,
+    stickyHeader = false,
+    ...props
+  }: DataTableProps<Row>,
+  ref: Ref<HTMLDivElement>
+) {
+  const [sort, setSort] = useControllableState<DataTableSort | null>({
+    value: controlledSort,
+    defaultValue: defaultSort,
+    onChange: onSortChange,
+  });
+
+  const sortedRows = useMemo(() => {
+    if (manualSorting || sort === null) return rows;
+    const sortValue = columns.find((column) => column.id === sort.columnId)?.sortValue;
+    if (!sortValue) return rows;
+    const factor = sort.direction === "asc" ? 1 : -1;
+    // Array.prototype.sort is stable, so equal keys keep the caller's order.
+    return [...rows].sort((a, b) => factor * compare(sortValue(a), sortValue(b)));
+  }, [rows, columns, sort, manualSorting]);
+
+  const interactive = onRowClick !== undefined;
+
+  const handleRowKeyDown = (event: KeyboardEvent<HTMLTableRowElement>, row: Row) => {
+    if (event.target !== event.currentTarget) return; // a button inside the row keeps its own keys
+    if (event.key === "Enter" || event.key === " ") {
+      event.preventDefault();
+      onRowClick?.(row);
+    }
+  };
+
+  return (
+    <div
+      ref={ref}
+      className={cn(
+        "data-table border-(color:--data-table-border) w-full overflow-auto rounded-lg border bg-(--data-table-bg) text-(--data-table-fg)",
+        className
+      )}
+      {...props}
+    >
+      <table className="w-full border-collapse">
+        {caption !== undefined && <caption className={cn(showCaption ? "px-3 py-2 text-start font-medium text-sm" : "sr-only")}>{caption}</caption>}
+        <thead className={cn("bg-(--data-table-header-bg)", stickyHeader && "sticky top-0 z-10")}>
+          <tr className="border-(color:--data-table-border) border-b">
+            {columns.map((column) => {
+              const align = column.align ?? "start";
+              const sorted = sort?.columnId === column.id ? sort.direction : undefined;
+              const Icon = sorted === "asc" ? ArrowUp : sorted === "desc" ? ArrowDown : ChevronsUpDown;
+              return (
+                <th
+                  key={column.id}
+                  scope="col"
+                  aria-sort={column.sortValue ? (sorted ? ariaSort[sorted] : "none") : undefined}
+                  style={column.width ? { width: column.width } : undefined}
+                  className={cn(cellVariants({ size }), alignClass[align], "whitespace-nowrap font-medium text-(--data-table-header-fg)")}
+                >
+                  {column.sortValue ? (
+                    <button
+                      type="button"
+                      onClick={() => setSort(nextSort(sort, column.id))}
+                      className={cn(
+                        "focus-visible:ring-(color:--data-table-ring) -mx-1 inline-flex cursor-pointer items-center gap-1 rounded-sm px-1 hover:text-(--data-table-fg) focus-visible:outline-hidden focus-visible:ring-2",
+                        align === "end" && "flex-row-reverse"
+                      )}
+                    >
+                      {column.header}
+                      <Icon aria-hidden="true" className={cn("size-3.5 shrink-0", sorted === undefined && "opacity-50")} />
+                    </button>
+                  ) : (
+                    column.header
+                  )}
+                </th>
+              );
+            })}
+          </tr>
+        </thead>
+        <tbody>
+          {sortedRows.length === 0 ? (
+            <tr>
+              <td colSpan={columns.length} className="px-3 py-10 text-center text-(--data-table-empty-fg) text-sm">
+                {empty ?? "Nothing to show"}
+              </td>
+            </tr>
+          ) : (
+            sortedRows.map((row) => (
+              <tr
+                key={getRowId(row)}
+                data-interactive={interactive || undefined}
+                onClick={interactive ? () => onRowClick(row) : undefined}
+                onKeyDown={interactive ? (event) => handleRowKeyDown(event, row) : undefined}
+                // A row is not a native control, but a clickable table row is the
+                // established back-office pattern. It stays a `row` so the table
+                // semantics survive, and gains a tab stop and Enter/Space like
+                // Card does when it is clickable.
+                tabIndex={interactive ? 0 : undefined}
+                className={cn(
+                  "border-(color:--data-table-border) border-b last:border-b-0",
+                  interactive &&
+                    "focus-visible:outline-(color:--data-table-ring) cursor-pointer hover:bg-(--data-table-row-bg-hovered) focus-visible:outline-2 focus-visible:-outline-offset-2"
+                )}
+              >
+                {columns.map((column) => (
+                  <td key={column.id} className={cn(cellVariants({ size }), alignClass[column.align ?? "start"], column.className)}>
+                    {column.cell(row)}
+                  </td>
+                ))}
+              </tr>
+            ))
+          )}
+        </tbody>
+      </table>
+    </div>
+  );
+});
+
+/**
+ * A data table for back-office lists — orders, products, customers.
+ *
+ * Props-based, per docs/component-api-design.md: rows are uniform, so they
+ * arrive as a `rows` array and a `columns` config, and each column's `cell`
+ * renders one row's content. Anything interactive in a cell — a status
+ * Badge, an action Button — is just what `cell` returns.
+ *
+ * A column with `sortValue` gets a header button cycling ascending →
+ * descending → unsorted, and `aria-sort` on its `<th>`. Sorting is
+ * client-side and stable; pass `manualSorting` to only report the change when
+ * the data is sorted where it is fetched. Sort state is controlled or
+ * uncontrolled through `sort`/`defaultSort`/`onSortChange`.
+ *
+ * `onRowClick` makes every row a tab stop activated by pointer, `Enter` or
+ * `Space` — keys pressed on a control inside the row are left to that control.
+ *
+ * The wrapper scrolls, so a wide table on a phone scrolls sideways inside its
+ * border rather than widening the page.
+ */
+export const DataTable = DataTableRoot as <Row>(props: DataTableProps<Row> & { ref?: Ref<HTMLDivElement> }) => ReactElement;
+
+export { cellVariants as dataTableCellVariants };

package/src/components/DataTable/data-table.recipe.css

@@ -0,0 +1,28 @@
+/**
+ * DataTable recipe — the component-token layer for DataTable.
+ *
+ * No variant/intent axis: status colour inside a table belongs to what the
+ * cells render (a Badge), not to the table. The table itself is the Elevated
+ * tier's container — the same surface and rule colours as card.css — through
+ * its own tokens, so a consumer can re-point one without the other.
+ *
+ * The grammar is `--data-table-[{part}-]{context}[-{state}]`. Parts are the
+ * `header` row, a `row` (only its hover, which applies only when rows are
+ * clickable), and the `empty` state's text. `--data-table-border` draws the
+ * outer frame and the rules between rows alike.
+ *
+ * `@layer components` is load-bearing, not tidiness — see button.css.
+ */
+
+@layer components {
+  .data-table {
+    --data-table-bg: var(--bg-normal);
+    --data-table-fg: var(--fg-normal);
+    --data-table-border: var(--border-normal);
+    --data-table-ring: var(--focus-ring);
+    --data-table-header-bg: var(--bg-subtle);
+    --data-table-header-fg: var(--fg-subtle);
+    --data-table-row-bg-hovered: var(--bg-normal-hovered);
+    --data-table-empty-fg: var(--fg-subtle);
+  }
+}

package/src/components/DataTable/index.ts

@@ -0,0 +1,10 @@
+export {
+  DataTable,
+  type DataTableAlign,
+  type DataTableColumn,
+  type DataTableProps,
+  type DataTableSize,
+  type DataTableSort,
+  type DataTableSortDirection,
+  dataTableCellVariants,
+} from "./DataTable";

package/src/components/FileDropzone/FileDropzone.tsx

@@ -0,0 +1,239 @@
+"use client";
+
+import { cva, type VariantProps } from "class-variance-authority";
+import { Upload } from "lucide-react";
+import * as React from "react";
+
+/**
+ * Geometry only. Every colour reads a `--file-dropzone-*` component token
+ * whose value is decided by src/components/FileDropzone/file-dropzone.recipe.css.
+ *
+ * `size` is the target's footprint: `sm` sits inline in a form row beside other
+ * fields, `md` is a panel of its own (an image manager's "add photos" tile).
+ */
+const fileDropzoneVariants = cva(
+  // One literal, deliberately — see Button.tsx for why a `+` concatenation is a trap.
+  "file-dropzone border-(color:--file-dropzone-border) focus-visible:ring-(color:--file-dropzone-ring) relative flex w-full cursor-pointer flex-col items-center justify-center rounded-lg border-2 border-dashed bg-(--file-dropzone-bg) text-center text-(--file-dropzone-fg) transition-colors hover:bg-(--file-dropzone-bg-hovered) focus-visible:outline-hidden focus-visible:ring-2 data-[disabled=true]:cursor-not-allowed data-[disabled=true]:opacity-50",
+  {
+    variants: {
+      size: {
+        sm: "min-h-20 gap-1 px-4 py-3 text-xs [&_svg]:size-4",
+        md: "min-h-36 gap-2 px-6 py-6 text-sm [&_svg]:size-6",
+      },
+    },
+    defaultVariants: {
+      size: "md",
+    },
+  }
+);
+
+export type FileDropzoneSize = NonNullable<VariantProps<typeof fileDropzoneVariants>["size"]>;
+
+export type FileDropzoneRejection = {
+  file: File;
+  /** `type` — not in `accept`; `size` — over `maxSize`. */
+  reason: "type" | "size";
+};
+
+export type FileDropzoneProps = Omit<React.HTMLAttributes<HTMLDivElement>, "onDrop" | "children"> &
+  VariantProps<typeof fileDropzoneVariants> & {
+    /** Called with the accepted files from a drop or the file picker. Never called with an empty list. */
+    onFilesChange: (files: File[]) => void;
+    /** Called with files that failed `accept` or `maxSize`, when any did. */
+    onFilesRejected?: (rejections: FileDropzoneRejection[]) => void;
+    /** Same syntax as the native `accept` attribute: `"image/*"`, `".pdf,.docx"`. Also checked on drop. */
+    accept?: string;
+    /** Allow more than one file per drop or pick. */
+    multiple?: boolean;
+    /** Largest accepted file, in bytes. */
+    maxSize?: number;
+    disabled?: boolean;
+    /** Shows a busy state (e.g. while uploading) and blocks new files without disabling the control. */
+    pending?: boolean;
+    /** The main line. Default: "Drop files here or click to browse". */
+    label?: React.ReactNode;
+    /** A secondary line, e.g. accepted types and size limit. */
+    hint?: React.ReactNode;
+    /** Replaces the default upload icon. Pass `null` for none. */
+    icon?: React.ReactNode;
+    /** Input name, for native form submission of the picked files. */
+    name?: string;
+  };
+
+function matchesAccept(file: File, accept: string | undefined): boolean {
+  if (!accept) return true;
+  const rules = accept
+    .split(",")
+    .map((rule) => rule.trim().toLowerCase())
+    .filter(Boolean);
+  if (rules.length === 0) return true;
+  const name = file.name.toLowerCase();
+  const type = file.type.toLowerCase();
+  return rules.some((rule) => {
+    if (rule.startsWith(".")) return name.endsWith(rule);
+    if (rule.endsWith("/*")) return type.startsWith(rule.slice(0, -1));
+    return type === rule;
+  });
+}
+
+/**
+ * A drop target for files that doubles as a file-picker button — product
+ * photos, attachments, imports.
+ *
+ * The whole surface is one control: `role="button"`, a tab stop, and `Enter`
+ * or `Space` opens the native picker, the same as a click. Dragging files over
+ * it sets `data-state="active"`, which the recipe styles. The hidden `<input
+ * type="file">` is the real picker, so `accept`, `multiple` and `name` behave
+ * natively; `accept` and `maxSize` are also enforced on drop, where the
+ * browser does not, and failures go to `onFilesRejected` rather than being
+ * silently dropped. Without `multiple`, a drop of several files keeps the first.
+ *
+ * `pending` shows a spinner-free busy state (`aria-busy`) and ignores new
+ * files while an upload runs, without leaving the tab order — the same split
+ * Switch makes between `pending` and `disabled`.
+ *
+ * The component holds no file list of its own: it reports files and the
+ * caller decides what to show, so there is no value/defaultValue triad.
+ */
+export const FileDropzone = React.forwardRef<HTMLDivElement, FileDropzoneProps>(
+  (
+    {
+      className,
+      size = "md",
+      onFilesChange,
+      onFilesRejected,
+      accept,
+      multiple = false,
+      maxSize,
+      disabled = false,
+      pending = false,
+      label = "Drop files here or click to browse",
+      hint,
+      icon,
+      name,
+      onKeyDown,
+      onClick,
+      ...props
+    },
+    ref
+  ) => {
+    const inputRef = React.useRef<HTMLInputElement>(null);
+    const [active, setActive] = React.useState(false);
+    // dragenter/dragleave fire for every child crossed; count them so the state does not flicker.
+    const depth = React.useRef(0);
+    const labelId = React.useId();
+    const hintId = React.useId();
+
+    const interactive = !disabled && !pending;
+
+    const handleFiles = (list: FileList | null) => {
+      if (!list || !interactive) return;
+      const files = Array.from(list);
+      const accepted: File[] = [];
+      const rejected: FileDropzoneRejection[] = [];
+      for (const file of files) {
+        if (!matchesAccept(file, accept)) rejected.push({ file, reason: "type" });
+        else if (maxSize !== undefined && file.size > maxSize) rejected.push({ file, reason: "size" });
+        else accepted.push(file);
+      }
+      const kept = multiple ? accepted : accepted.slice(0, 1);
+      if (rejected.length > 0) onFilesRejected?.(rejected);
+      if (kept.length > 0) onFilesChange(kept);
+    };
+
+    const openPicker = () => {
+      if (interactive) inputRef.current?.click();
+    };
+
+    const handleKeyDown = (event: React.KeyboardEvent<HTMLDivElement>) => {
+      onKeyDown?.(event);
+      if (event.defaultPrevented || event.target !== event.currentTarget) return;
+      if (event.key === "Enter" || event.key === " ") {
+        event.preventDefault();
+        openPicker();
+      }
+    };
+
+    const handleDragEnter = (event: React.DragEvent<HTMLDivElement>) => {
+      event.preventDefault();
+      if (!interactive) return;
+      depth.current += 1;
+      setActive(true);
+    };
+
+    const handleDragLeave = (event: React.DragEvent<HTMLDivElement>) => {
+      event.preventDefault();
+      depth.current = Math.max(0, depth.current - 1);
+      if (depth.current === 0) setActive(false);
+    };
+
+    const handleDragOver = (event: React.DragEvent<HTMLDivElement>) => {
+      event.preventDefault();
+      event.dataTransfer.dropEffect = interactive ? "copy" : "none";
+    };
+
+    const handleDrop = (event: React.DragEvent<HTMLDivElement>) => {
+      event.preventDefault();
+      depth.current = 0;
+      setActive(false);
+      handleFiles(event.dataTransfer.files);
+    };
+
+    return (
+      // biome-ignore lint/a11y/useSemanticElements: the target holds the native file <input>, and interactive content is not allowed inside a <button>; role="button" with Enter/Space handling is the WAI-ARIA button pattern
+      <div
+        ref={ref}
+        role="button"
+        tabIndex={disabled ? -1 : 0}
+        aria-disabled={disabled || undefined}
+        aria-busy={pending || undefined}
+        aria-labelledby={labelId}
+        aria-describedby={hint ? hintId : undefined}
+        data-state={active ? "active" : "idle"}
+        data-disabled={disabled}
+        className={fileDropzoneVariants({ size, className })}
+        onClick={(event) => {
+          onClick?.(event);
+          if (!event.defaultPrevented) openPicker();
+        }}
+        onKeyDown={handleKeyDown}
+        onDragEnter={handleDragEnter}
+        onDragLeave={handleDragLeave}
+        onDragOver={handleDragOver}
+        onDrop={handleDrop}
+        {...props}
+      >
+        {icon === undefined ? <Upload aria-hidden="true" className="text-(--file-dropzone-icon-fg)" /> : icon}
+        <span id={labelId} className="font-medium">
+          {label}
+        </span>
+        {hint && (
+          <span id={hintId} className="text-(--file-dropzone-hint-fg)">
+            {hint}
+          </span>
+        )}
+        <input
+          ref={inputRef}
+          type="file"
+          // `hidden`, not `sr-only`: a rendered input inside role="button" is a nested
+          // interactive control (axe `nested-interactive`). `click()` and form submission
+          // still work on a display:none file input.
+          hidden
+          accept={accept}
+          multiple={multiple}
+          name={name}
+          disabled={disabled}
+          onClick={(event) => event.stopPropagation()}
+          onChange={(event) => {
+            handleFiles(event.target.files);
+            // Reset so picking the same file again still fires change.
+            event.target.value = "";
+          }}
+        />
+      </div>
+    );
+  }
+);
+FileDropzone.displayName = "FileDropzone";
+
+export { fileDropzoneVariants };

package/src/components/FileDropzone/file-dropzone.recipe.css

@@ -0,0 +1,38 @@
+/**
+ * FileDropzone recipe — the component-token layer for FileDropzone.
+ *
+ * No variant/intent axis: a dropzone is a form control, so like Input every
+ * colour is a fixed semantic token. The one state that changes colour is a
+ * drag in progress, which the component renders as `data-state="active"`
+ * and the recipe keys a cell on — the same way steps.css keys on `data-state`.
+ *
+ * The grammar is `--file-dropzone-[{part}-]{context}[-{state}]`. Parts are
+ * the `icon` and the `hint` line. The surface reads the subtle ground so the
+ * dashed target stands apart from the fields around it, and a drag over it
+ * takes the brand wash — the same pairing Tabs uses for its selected cell.
+ *
+ * `@layer components` is load-bearing, not tidiness — see button.css.
+ */
+
+@layer components {
+  .file-dropzone {
+    --file-dropzone-bg: var(--bg-subtle);
+    --file-dropzone-bg-hovered: var(--bg-subtle-hovered);
+    --file-dropzone-fg: var(--fg-normal);
+    --file-dropzone-border: var(--border-normal);
+    --file-dropzone-ring: var(--focus-ring);
+    --file-dropzone-icon-fg: var(--fg-subtle);
+    --file-dropzone-hint-fg: var(--fg-subtle);
+  }
+
+  /* A drag in progress: the brand wash, hover included, so the target does not
+     flicker back to subtle as the pointer moves across it. */
+  .file-dropzone[data-state="active"] {
+    --file-dropzone-bg: var(--bg-brand-subtle);
+    --file-dropzone-bg-hovered: var(--bg-brand-subtle);
+    --file-dropzone-border: var(--border-brand);
+    --file-dropzone-icon-fg: var(--fg-brand);
+    /* fg-subtle drops below 4.5:1 on the brand wash in light mode. */
+    --file-dropzone-hint-fg: var(--fg-normal);
+  }
+}

package/src/components/FileDropzone/index.ts

@@ -0,0 +1 @@
+export { FileDropzone, type FileDropzoneProps, type FileDropzoneRejection, type FileDropzoneSize, fileDropzoneVariants } from "./FileDropzone";