@sixthshift/design-system 0.6.0 → 0.8.0

package/src/components/Badge/Badge.tsx

@@ -55,23 +55,29 @@ export type BadgeIntent = Loose<BadgeIntentName>;
 export type BadgeRecipeProps = VariantProps<typeof badgeVariants> & {
   variant?: BadgeVariant | undefined;
   intent?: BadgeIntent | undefined;
+  /** Re-points this element's brand tokens to a brand the theme defines. See the Scoped brands docs. */
+  brand?: string | undefined;
   className?: string | undefined;
 };
 
 /**
- * The class string plus the two attributes the recipe selects on.
+ * The class string plus the attributes the recipe selects on. `data-brand` is
+ * omitted unless `brand` is set, same as `buttonRecipe`.
  */
-export function badgeRecipe({ variant = "solid", intent = "brand", className }: BadgeRecipeProps) {
+export function badgeRecipe({ variant = "solid", intent = "brand", brand, className }: BadgeRecipeProps) {
   return {
     className: cn(variantStructure[variant], badgeVariants({ className })),
     "data-variant": variant,
     "data-intent": intent,
+    "data-brand": brand,
   };
 }
 
 export type BadgeProps = React.HTMLAttributes<HTMLSpanElement> & {
   variant?: BadgeVariant | undefined;
   intent?: BadgeIntent | undefined;
+  /** Name of a brand the theme defines, rendered as `data-brand`. Omitted, the badge follows the nearest `data-brand` ancestor. */
+  brand?: string | undefined;
 };
 
 /**
@@ -89,8 +95,8 @@ export type BadgeProps = React.HTMLAttributes<HTMLSpanElement> & {
  * same seam Button uses, so a consumer can re-point a cell without a
  * release.
  */
-export const Badge = React.forwardRef<HTMLSpanElement, BadgeProps>(({ className, variant = "solid", intent = "brand", ...props }, ref) => {
-  return <span ref={ref} {...badgeRecipe({ variant, intent, className })} {...props} />;
+export const Badge = React.forwardRef<HTMLSpanElement, BadgeProps>(({ className, variant = "solid", intent = "brand", brand, ...props }, ref) => {
+  return <span ref={ref} {...badgeRecipe({ variant, intent, brand, className })} {...props} />;
 });
 Badge.displayName = "Badge";
 

package/src/components/Button/Button.tsx

@@ -86,18 +86,23 @@ export type ButtonIntent = Loose<ButtonIntentName>;
 export type ButtonRecipeProps = VariantProps<typeof buttonVariants> & {
   variant?: ButtonVariant | undefined;
   intent?: ButtonIntent | undefined;
+  /** Re-points this element's brand tokens to a brand the theme defines. See the Scoped brands docs. */
+  brand?: string | undefined;
   iconOnly?: boolean | undefined;
   className?: string | undefined;
 };
 
 /**
- * The class string plus the two attributes the recipe selects on.
+ * The class string plus the attributes the recipe selects on.
+ *
+ * `data-brand` is only emitted when `brand` is set: `undefined` makes React
+ * omit the attribute, so the element takes its brand from its surroundings.
  *
  * Shared with Toggle and ToggleGroupItem, which are built on Button's look. The
  * data attributes are half the contract now, so anything reusing that look has
  * to emit them as well or it lands on the recipe's floor instead of a cell.
  */
-export function buttonRecipe({ variant = "solid", intent = "neutral", size, iconOnly = false, className }: ButtonRecipeProps) {
+export function buttonRecipe({ variant = "solid", intent = "neutral", brand, size, iconOnly = false, className }: ButtonRecipeProps) {
   return {
     className: cn(
       variantStructure[variant],
@@ -106,6 +111,7 @@ export function buttonRecipe({ variant = "solid", intent = "neutral", size, icon
     ),
     "data-variant": variant,
     "data-intent": intent,
+    "data-brand": brand,
   };
 }
 
@@ -113,6 +119,12 @@ export type ButtonProps = React.ButtonHTMLAttributes<HTMLButtonElement> &
   VariantProps<typeof buttonVariants> & {
     variant?: ButtonVariant | undefined;
     intent?: ButtonIntent | undefined;
+    /**
+     * Name of a brand the theme defines, rendered as `data-brand`. Re-points
+     * every brand token on this element, so `intent="brand"` takes that brand's
+     * colour. Omitted, the button follows the nearest `data-brand` ancestor.
+     */
+    brand?: string | undefined;
     /** Square the button at its current size, for an icon with no label. */
     iconOnly?: boolean;
     asChild?: boolean;
@@ -147,15 +159,23 @@ export type ButtonProps = React.ButtonHTMLAttributes<HTMLButtonElement> &
  * `aria-label`, since there is no text to name it. It is a separate prop rather
  * than a size, so `size="sm" iconOnly` is expressible.
  *
+ * `brand` scopes the `brand` intent to one of the theme's named brands
+ * (`<Button intent="brand" brand="mint">`), for a theme with more than one
+ * brand colour. It renders `data-brand` and nothing else; the theme's CSS gives
+ * the name meaning, and an unknown name falls back to the surrounding brand.
+ *
  * `asChild` renders the child element with Button's styling instead of a
  * `<button>`, for links that should look like buttons. `loading` shows a spinner
  * and disables the control, so it does not need `disabled` as well.
  */
 const Button = React.forwardRef<HTMLButtonElement, ButtonProps>(
-  ({ className, variant = "solid", intent = "neutral", size, iconOnly = false, asChild = false, loading = false, children, disabled, ...props }, ref) => {
+  (
+    { className, variant = "solid", intent = "neutral", brand, size, iconOnly = false, asChild = false, loading = false, children, disabled, ...props },
+    ref
+  ) => {
     const Comp = asChild ? Slot : "button";
     return (
-      <Comp {...buttonRecipe({ variant, intent, size, iconOnly, className })} ref={ref} disabled={disabled || loading} {...props}>
+      <Comp {...buttonRecipe({ variant, intent, brand, size, iconOnly, className })} ref={ref} disabled={disabled || loading} {...props}>
         {loading ? (
           <>
             <svg className="animate-spin" xmlns="http://www.w3.org/2000/svg" fill="none" viewBox="0 0 24 24" aria-hidden="true">

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/DatePicker/DatePicker.tsx

@@ -21,6 +21,7 @@ import {
   toISODateRange,
 } from "../../date-time";
 import { PickerField } from "../../internal";
+import { closestBrand } from "../../internal/brandScope";
 import { useEscapeLayer } from "../../internal/escapeLayers";
 import { CalendarView } from "../Calendar/CalendarView";
 import { isDateDisabled } from "../Calendar/calendar.hooks";
@@ -539,6 +540,8 @@ export const DatePicker = React.forwardRef<HTMLDivElement, DatePickerProps>((pro
             role="dialog"
             aria-label="Choose date"
             style={floatingStyles}
+            // Portalled out of the trigger's brand scope, so carry it across.
+            data-brand={closestBrand(context.elements.domReference)}
             className="z-popover rounded-xl border border-border-normal bg-bg-normal p-4 shadow-lg"
             {...getFloatingProps()}
           >

package/src/components/DateTimePicker/DateTimePicker.tsx

@@ -16,6 +16,7 @@ import {
   toISOInstantOrUndefined,
 } from "../../date-time";
 import { PickerField } from "../../internal";
+import { closestBrand } from "../../internal/brandScope";
 import { useEscapeLayer } from "../../internal/escapeLayers";
 import { Button } from "../Button";
 import { CalendarView } from "../Calendar/CalendarView";
@@ -410,6 +411,8 @@ export const DateTimePicker = React.forwardRef<HTMLDivElement, DateTimePickerPro
             role="dialog"
             aria-label="Choose date and time"
             style={floatingStyles}
+            // Portalled out of the trigger's brand scope, so carry it across.
+            data-brand={closestBrand(context.elements.domReference)}
             className="z-popover rounded-xl border border-border-normal bg-bg-normal p-4 shadow-lg"
             {...getFloatingProps()}
           >

package/src/components/DateTimeRangePicker/DateTimeRangePicker.tsx

@@ -19,6 +19,7 @@ import {
   toISOInstantRange,
 } from "../../date-time";
 import { PickerField } from "../../internal";
+import { closestBrand } from "../../internal/brandScope";
 import { useEscapeLayer } from "../../internal/escapeLayers";
 import { Button } from "../Button";
 import { CalendarView } from "../Calendar/CalendarView";
@@ -630,6 +631,8 @@ export const DateTimeRangePicker = React.forwardRef<HTMLDivElement, DateTimeRang
             role="dialog"
             aria-label="Choose date and time range"
             style={floatingStyles}
+            // Portalled out of the trigger's brand scope, so carry it across.
+            data-brand={closestBrand(context.elements.domReference)}
             className="z-popover rounded-xl border border-border-normal bg-bg-normal p-4 shadow-lg"
             {...getFloatingProps()}
           >