@multiplatform.one/table 6.1.0 → 6.4.0

package/src/components/DataTable/DataTable.stories.tsx

@@ -85,7 +85,7 @@ const columns: DataTableColumn<User>[] = [
     header: "Avatar",
     cell: (info) => (
       <Avatar circular size="$3">
-        <Avatar.Image accessibilityLabel="User avatar" src={info.getValue()} />
+        <Avatar.Image alt="User avatar" src={info.getValue()} />
         <Avatar.Fallback backgroundColor="$gray6" />
       </Avatar>
     ),
@@ -431,13 +431,10 @@ const basicColumns: DataTableColumn<Person>[] = [
     header: "Status",
     cell: (info) => {
       const status = info.getValue();
+      // Sanctioned intent ramp values (UX-P15 / Axiom 12): the *11 rungs stay
+      // AA on both schemes, unlike the raw CSS `green`/`red` they replace.
       return (
-        <Text
-          style={{
-            color: status === "active" ? "green" : "red",
-            fontWeight: "bold",
-          }}
-        >
+        <Text color={status === "active" ? "$green11" : "$red11"} fontWeight="bold">
           {status}
         </Text>
       );
@@ -458,6 +455,23 @@ export const Basic: Story = {
   args: {
     data: sampleData,
     columns: basicColumns as DataTableColumn<Record<string, any>>[],
+    // Rest on a middle page so every pagination control renders live —
+    // a bare-disabled prev/next at rest trips the `[theme]` guardrail
+    // (UX-P19 / DG-ST-03) and demos nothing.
+    initialState: {
+      pagination: { pageIndex: 1, pageSize: 2 },
+    },
+  },
+};
+
+export const Loading: Story = {
+  args: {
+    data: sampleData,
+    columns: basicColumns as DataTableColumn<Record<string, any>>[],
+    initialState: {
+      isLoading: true,
+    },
+    "aria-label": "Loading table",
   },
 };
 
@@ -466,8 +480,9 @@ export const WithPagination: Story = {
     data: sampleData,
     columns: basicColumns as DataTableColumn<Record<string, any>>[],
     enablePagination: true,
+    // Middle page: prev AND next stay live at rest (no bare-disabled nav).
     initialState: {
-      pagination: { pageIndex: 0, pageSize: 2 },
+      pagination: { pageIndex: 1, pageSize: 2 },
     },
   },
 };
@@ -488,6 +503,32 @@ export const WithFiltering: Story = {
   },
 };
 
+/**
+ * Chrome-suppression contract (one outer filter authority): the host screen
+ * owns filtering and injects tuples via `initialState.filters`; the table
+ * renders NO filter entry points — no toolbar Filter button, no column
+ * funnels, no chips row — while the injected filters keep applying (rows
+ * below are pre-filtered to status=active). Search and header sort stay.
+ * The backoffice doctype list is the canonical consumer (MOD-04).
+ */
+export const ExternallyFiltered: Story = {
+  args: {
+    data: sampleData,
+    columns: basicColumns as DataTableColumn<Record<string, any>>[],
+    enableFiltering: false,
+    enableSorting: true,
+    initialState: {
+      filters: [
+        {
+          id: "external-status",
+          columnId: "status",
+          value: { operator: "is", value: "active" },
+        },
+      ],
+    },
+  },
+};
+
 export const FullFeatured: Story = {
   args: {
     data: sampleData,
@@ -495,8 +536,9 @@ export const FullFeatured: Story = {
     enableFiltering: true,
     enableSorting: true,
     enablePagination: true,
+    // 3 pages, resting mid-page: every nav control live (no bare-disabled).
     initialState: {
-      pagination: { pageIndex: 0, pageSize: 3 },
+      pagination: { pageIndex: 1, pageSize: 2 },
     },
   },
 };
@@ -599,6 +641,47 @@ export const Empty: Story = {
   },
 };
 
+/**
+ * Active filter matches nothing: "No results found" — distinct from the
+ * unfiltered Empty state's "No data available" (DG-TBL-06 / Axiom 6).
+ * Clearing the filter from the toolbar restores the rows.
+ */
+export const NoResults: Story = {
+  args: {
+    data: sampleData,
+    columns: basicColumns as DataTableColumn<Record<string, any>>[],
+    enableFiltering: true,
+    initialState: {
+      filters: [
+        {
+          id: "no-results-filter",
+          columnId: "name",
+          value: { operator: "contains", value: "zzz-no-match" },
+        },
+      ],
+    },
+    "aria-label": "Filtered table with no matching rows",
+  },
+};
+
+/**
+ * Failed load: error chrome with a Retry action replaces the rows — a failed
+ * table must never masquerade as empty, and the retry affordance makes the
+ * error state actionable (DG-ST-01 "error with retry" / Axiom 6). `onRetry`
+ * wires the Retry button; `state.error` carries the message.
+ */
+export const ErrorWithRetry: Story = {
+  args: {
+    data: sampleData,
+    columns: basicColumns as DataTableColumn<Record<string, any>>[],
+    initialState: {
+      error: "The rows could not be loaded.",
+    },
+    onRetry: fn(),
+    "aria-label": "Table with failed load",
+  },
+};
+
 export const ReadOnly: Story = {
   args: {
     data: sampleData,
@@ -616,6 +699,83 @@ export const WithRowNumbers: Story = {
   },
 };
 
+const selectionBulkActions = [
+  {
+    id: "export",
+    label: "Export",
+    onExecute: (items: Record<string, any>[], clear: () => void) => {
+      fn()(items);
+      clear();
+    },
+  },
+  {
+    id: "archive",
+    label: "Archive",
+    onExecute: (items: Record<string, any>[], clear: () => void) => {
+      fn()(items);
+      clear();
+    },
+  },
+  {
+    id: "tag",
+    label: "Tag",
+    onExecute: (items: Record<string, any>[], clear: () => void) => {
+      fn()(items);
+      clear();
+    },
+  },
+  {
+    id: "assign",
+    label: "Assign",
+    onExecute: (items: Record<string, any>[], clear: () => void) => {
+      fn()(items);
+      clear();
+    },
+  },
+  {
+    id: "notify",
+    label: "Notify",
+    onExecute: (items: Record<string, any>[], clear: () => void) => {
+      fn()(items);
+      clear();
+    },
+  },
+  {
+    id: "delete",
+    label: "Delete",
+    variant: "destructive" as const,
+    requiresConfirmation: true,
+    onExecute: (items: Record<string, any>[], clear: () => void) => {
+      fn()(items);
+      clear();
+    },
+  },
+];
+
+/** DG-TBL-02/03 — enableRowSelection + selectAllScope + auto bulk bar */
+export const WithRowSelection: Story = {
+  args: {
+    data: sampleData,
+    columns: basicColumns as DataTableColumn<Record<string, any>>[],
+    enableRowSelection: true,
+    selectAllScope: "page",
+    bulkActions: selectionBulkActions,
+    enablePagination: true,
+    initialState: {
+      pagination: { pageIndex: 1, pageSize: 2 },
+    },
+    "aria-label": "Row selection data table",
+  },
+  argTypes: {
+    selectAllScope: {
+      control: "radio",
+      options: ["page", "filtered"],
+      description: "Header select-all scope (DG-TBL-03)",
+    },
+    enableRowSelection: { control: "boolean" },
+  },
+};
+
 // Editable Table Data
 interface EditablePerson {
   id: number;
@@ -690,6 +850,26 @@ export const EditableTable: Story = {
   render: () => <EditableTableStory />,
 };
 
+/**
+ * UX-011 / Axiom 6 HONEST STATE: `disabled` renders the whole table inert —
+ * search, sorting, selection, cell editing, and pagination do nothing — and
+ * visibly disabled (LC-40): chrome dims, cell editors wash, the root carries
+ * `aria-disabled` and (web) `inert`. Read-only is the different, never-dimmed
+ * state (see ReadOnly).
+ */
+export const Disabled: Story = {
+  args: {
+    data: editableData as unknown as Record<string, any>[],
+    columns: editableColumns as DataTableColumn<Record<string, any>>[],
+    disabled: true,
+    enableRowSelection: true,
+    enableSorting: true,
+    enableGlobalSearch: true,
+    enableFiltering: true,
+    enablePagination: true,
+  },
+};
+
 export const WithFieldTypes: Story = {
   render: () => <EditableTableStory />,
 };
@@ -2521,3 +2701,177 @@ const ScrollLayoutStory = () => {
 export const ColumnLayoutScroll: Story = {
   render: () => <ScrollLayoutStory />,
 };
+
+// ============================================================================
+// RESPONSIVE CARD LAYOUT STORIES
+// ============================================================================
+
+/**
+ * Full-chrome card layout: search, filters, sorting, selection, and
+ * pagination all operate on the card list. `layout="cards"` pins the
+ * card list at any viewport so the story is inspectable at desktop
+ * width; `layout="auto"` (the default) switches automatically below
+ * the `$sm` breakpoint.
+ */
+const CardLayoutStory = () => {
+  const data = useMemo(() => generateUsers(25), []);
+  return (
+    <View padding="$4" maxWidth={480} width="100%">
+      <DataTable
+        data={data}
+        columns={columns}
+        layout="cards"
+        enableGlobalSearch={true}
+        enableFiltering={true}
+        enableSorting={true}
+        enableRowSelection={true}
+        enablePagination={true}
+        initialState={{ pagination: { pageIndex: 1, pageSize: 10 } }}
+        bulkActions={[
+          {
+            id: "archive",
+            label: "Archive",
+            onExecute: (_items: any[], clear: () => void) => clear(),
+          },
+        ]}
+        aria-label="Card layout table"
+      />
+    </View>
+  );
+};
+
+export const CardLayout: Story = {
+  render: () => <CardLayoutStory />,
+};
+
+/** Default responsive behavior: grid at desktop width, cards below `$sm`. */
+export const CardLayoutAuto: Story = {
+  args: {
+    data: sampleData,
+    columns: basicColumns as DataTableColumn<Record<string, any>>[],
+    layout: "auto",
+    enableGlobalSearch: true,
+    enableFiltering: true,
+    enableSorting: true,
+    enablePagination: true,
+    initialState: {
+      pagination: { pageIndex: 1, pageSize: 2 },
+    },
+  },
+};
+
+// ============================================================================
+// HIDDEN-FIELD FILTERING (toolbar Filter surface)
+// ============================================================================
+
+/** Only 3 of the 11 user fields are visible columns. */
+const hiddenFilterColumns: DataTableColumn<User>[] = [
+  { accessorKey: "firstName", header: "First Name" },
+  { accessorKey: "age", header: "Age", field: "stepper" },
+  {
+    accessorKey: "status",
+    header: "Status",
+    field: "select",
+    fieldProps: {
+      options: [
+        { label: "Active", value: "active" },
+        { label: "Inactive", value: "inactive" },
+        { label: "Pending", value: "pending" },
+      ],
+    },
+  },
+];
+
+/**
+ * The rest of the record filters through the toolbar "Filter" surface:
+ * searchable field list (visible columns grouped first, then "More
+ * fields"), live-commit operator/value editor, and removable chips for
+ * every active filter — the honest-state surface for filters on fields
+ * with no visible column.
+ */
+const hiddenFilterFields = [
+  { id: "email", label: "Email", type: "text" as const },
+  {
+    id: "department",
+    label: "Department",
+    type: "select" as const,
+    options: [
+      { label: "Engineering", value: "Engineering" },
+      { label: "Marketing", value: "Marketing" },
+      { label: "Sales", value: "Sales" },
+      { label: "HR", value: "HR" },
+      { label: "Finance", value: "Finance" },
+    ],
+  },
+  { id: "role", label: "Role", type: "text" as const },
+  { id: "salary", label: "Salary", type: "number" as const },
+  { id: "joinDate", label: "Join Date", type: "date" as const },
+  { id: "lastLogin", label: "Last Login", type: "date" as const },
+];
+
+const HiddenFieldFiltersStory = ({ syncWithUrl = false }: { syncWithUrl?: boolean }) => {
+  const data = useMemo(() => generateUsers(40), []);
+  return (
+    <DataTable
+      data={data}
+      columns={hiddenFilterColumns}
+      filterableFields={hiddenFilterFields}
+      enableGlobalSearch
+      enableFiltering
+      enableSorting
+      enablePagination
+      syncWithUrl={syncWithUrl}
+      initialState={{ pagination: { pageIndex: 1, pageSize: 10 } }}
+      aria-label="Hidden field filters table"
+    />
+  );
+};
+
+export const HiddenFieldFilters: Story = {
+  render: () => <HiddenFieldFiltersStory />,
+};
+
+/** Same table with URL sync — hidden-field filters serialize like column filters. */
+export const HiddenFieldFiltersUrlSync: Story = {
+  render: () => <HiddenFieldFiltersStory syncWithUrl />,
+};
+
+const CompoundCompositionStory = () => {
+  const data = useMemo(() => generateUsers(30), []);
+  return (
+    <DataTable
+      data={data}
+      columns={columns}
+      enableGlobalSearch={false}
+      enableFiltering={false}
+      enablePagination={false}
+      initialState={{ pagination: { pageIndex: 1, pageSize: 10 } }}
+      aria-label="Compound composition table"
+    >
+      <DataTable.Toolbar enableFiltering={false} />
+      <DataTable.Filters
+        availableColumns={[
+          { id: "age", label: "Age", type: "number" },
+          {
+            id: "department",
+            label: "Department",
+            type: "select",
+            options: [
+              { label: "Engineering", value: "Engineering", count: 12 },
+              { label: "Marketing", value: "Marketing", count: 8 },
+              { label: "Sales", value: "Sales", count: 6 },
+              { label: "HR", value: "HR", count: 4 },
+              { label: "Finance", value: "Finance", count: 3 },
+            ],
+          },
+          { id: "role", label: "Role", type: "text" },
+        ]}
+      />
+      <DataTable.Pagination />
+    </DataTable>
+  );
+};
+
+export const CompoundComposition: Story = {
+  render: () => <CompoundCompositionStory />,
+};

package/src/components/DataTable/DataTableCardControls.tsx

@@ -0,0 +1,148 @@
+/**
+ * DataTableCardControls - sort + filter affordances for the card layout.
+ *
+ * In the grid layout, sorting and per-column filtering live in the column
+ * headers. The card layout has no headers, so this compact control row
+ * restores those affordances above the card list: a sort menu (cycles
+ * none → asc → desc per sortable column, mirroring the header click
+ * cycle) and the existing DataTableFilters compact chrome (add filter +
+ * active count + clear). Both operate on the same table state as the
+ * grid — no parallel state.
+ */
+
+import { CaretDownIcon, CaretUpDownIcon } from "@phosphor-icons/react";
+import { DropdownMenu } from "@multiplatform.one/components";
+import { Button } from "@multiplatform.one/forms";
+import { useResolvedKnobs } from "@multiplatform.one/theme";
+import { useState } from "react";
+import { View, XStack } from "tamagui";
+import { useTranslation } from "react-i18next";
+import type { DataTableColumnType, FacetedFilterOption } from "../../types";
+import { withInterp } from "../../utils/withInterp";
+import { DataTableFilters } from "../DataTableFilters";
+
+export interface DataTableCardControlsProps {
+  /** TanStack table instance (from useDataTable). */
+  table: any;
+  enableSorting?: boolean;
+  enableFiltering?: boolean;
+  /** Columns offered by the filter builder (id/label/type). */
+  availableColumns?: Array<{
+    id: string;
+    label: string;
+    type: DataTableColumnType;
+    options?: FacetedFilterOption[];
+  }>;
+  compact?: boolean;
+  /** Table-level disabled state (UX-011): controls render inert + LC-40 visible. */
+  disabled?: boolean;
+}
+
+/** Resolve the human label for a TanStack column (string header, else id). */
+function getColumnLabel(column: any): string {
+  return typeof column.columnDef.header === "string" ? column.columnDef.header : column.id;
+}
+
+export function DataTableCardControls({
+  table,
+  enableSorting = false,
+  enableFiltering = false,
+  availableColumns = [],
+  compact = false,
+  disabled = false,
+}: DataTableCardControlsProps) {
+  const { t } = useTranslation();
+  const { knobProps, disabledState } = useResolvedKnobs({ compact });
+  const [sortMenuOpen, setSortMenuOpen] = useState(false);
+
+  const sortableColumns = enableSorting
+    ? table.getVisibleLeafColumns().filter((col: any) => col.getCanSort())
+    : [];
+
+  const activeSort = table.getState().sorting?.[0];
+  const activeSortColumn = activeSort ? table.getColumn(activeSort.id) : undefined;
+  const sortLabel = activeSortColumn
+    ? `${getColumnLabel(activeSortColumn)} ${activeSort.desc ? "\u2193" : "\u2191"}`
+    : t("Sort");
+
+  if (!enableSorting && !enableFiltering) return null;
+
+  return (
+    <XStack
+      alignItems="center"
+      flexWrap="wrap"
+      gap="$2"
+      paddingVertical="$2"
+      role="toolbar"
+      aria-label={t("Card list controls")}
+    >
+      {enableSorting && sortableColumns.length > 0 && (
+        <DropdownMenu
+          open={disabled ? false : sortMenuOpen}
+          onOpenChange={(open: boolean) => {
+            if (disabled) return;
+            setSortMenuOpen(open);
+          }}
+        >
+          <DropdownMenu.Trigger asChild>
+            <Button
+              size={knobProps.sizeToken}
+              variant="outlined"
+              icon={<CaretUpDownIcon size={16} />}
+              aria-label={t("Sort rows")}
+              disabled={disabled}
+            >
+              {sortLabel}
+            </Button>
+          </DropdownMenu.Trigger>
+          <DropdownMenu.Content>
+            <DropdownMenu.Label>{t("Sort by")}</DropdownMenu.Label>
+            {sortableColumns.map((column: any) => {
+              const sorted = column.getIsSorted();
+              return (
+                <DropdownMenu.Item
+                  key={column.id}
+                  closeOnSelect={false}
+                  icon={
+                    sorted === "asc" ? (
+                      <CaretDownIcon size={14} />
+                    ) : sorted === "desc" ? (
+                      <CaretDownIcon size={14} style={{ transform: "rotate(180deg)" }} />
+                    ) : (
+                      <CaretUpDownIcon size={14} />
+                    )
+                  }
+                  aria-label={withInterp(
+                    t("Sort by {{column}}", { column: getColumnLabel(column) }),
+                    {
+                      column: getColumnLabel(column),
+                    },
+                  )}
+                  onSelect={() => {
+                    // Same cycle as the grid header click: none → asc → desc → none.
+                    if (sorted === false) column.toggleSorting(false);
+                    else if (sorted === "asc") column.toggleSorting(true);
+                    else column.clearSorting();
+                  }}
+                >
+                  {getColumnLabel(column)}
+                </DropdownMenu.Item>
+              );
+            })}
+          </DropdownMenu.Content>
+        </DropdownMenu>
+      )}
+      {enableFiltering && availableColumns.length > 0 && (
+        // DataTableFilters (chrome) has no disabled API — the wrapper is the
+        // LC-40 carrier and interaction gate for the disabled table.
+        <View
+          {...(disabled
+            ? { ...disabledState.chromeKnobProps, pointerEvents: "none" as const }
+            : {})}
+        >
+          <DataTableFilters compact availableColumns={availableColumns} />
+        </View>
+      )}
+    </XStack>
+  );
+}