@colixsystems/widget-sdk 0.247.0 → 0.248.0

package/dist/data-table-view.js

@@ -0,0 +1,388 @@
+// The ONE implementation behind `<DataTable>`. The bindings (`data-table.js`
+// / `data-table.native.js`) differ only in where the primitives and the list,
+// loading, menu and button parts come from, so the hosts cannot drift.
+//
+// A record list in three tiers from its own measured width: stacked
+// label/value cards, one card per row, then aligned columns under a sticky
+// header. Every tier is drawn by `<List>` / `<ListRow>` / `<ListHeader>`, so
+// the theme's `list` scope (and `card` scope for the cards) styles it.
+
+import React from "react";
+import { useContainerWidth, useHostTheme, useHostSharedText } from "./hooks.js";
+import { DEFAULT_THEME_TOKENS } from "./_theme-tokens.js";
+import { CONTRACT } from "./contract.js";
+import { Icon } from "./icon.js";
+import { LIST_TOKEN_NAMES, resolveListTokens } from "./list-tokens.js";
+import { textRoleStyle } from "./text-roles.js";
+import {
+  DATA_TABLE_HEADER_TARGET,
+  DATA_TABLE_SKELETON_ROWS,
+  DEFAULT_SORT_LABELS,
+  ariaSortFor,
+  cellText,
+  dataTableLayout,
+  justifyFor,
+  nextSort,
+  normaliseColumns,
+  normaliseSort,
+  resolveMaxHeight,
+  rowKey,
+  sortRows,
+  sortSpokenLabel,
+  sortStateWords,
+  sortsClientSide,
+} from "./data-table-logic.js";
+
+const h = React.createElement;
+const EMPTY_FALLBACK = CONTRACT.sharedTranslationKeys.no_results.en;
+const SORT_ICON_SIZE = 14;
+const SORT_GLYPHS = Object.freeze({
+  none: "chevrons-up-down",
+  ascending: "arrow-up",
+  descending: "arrow-down",
+});
+const VISUALLY_HIDDEN = {
+  position: "absolute",
+  width: 1,
+  height: 1,
+  overflow: "hidden",
+  opacity: 0,
+};
+
+function useTableTheme() {
+  return useHostTheme() || DEFAULT_THEME_TOKENS;
+}
+
+function listOverrides(props) {
+  const out = {};
+  for (const name of LIST_TOKEN_NAMES) {
+    if (props[name] !== undefined && props[name] !== null) out[name] = props[name];
+  }
+  return out;
+}
+
+function testId(base, part) {
+  return base ? `${base}-${part}` : undefined;
+}
+
+function cellBox(column) {
+  return { flex: column.flex, minWidth: column.minWidth, justifyContent: "center" };
+}
+
+/**
+ * Bind the shared table to one platform's primitives and parts.
+ *
+ * @param {{View: any, Text: any, Pressable: any, ScrollView: any, Platform: any,
+ *   AccessibilityInfo: any}} rn
+ * @param {{List: any, ListRow: any, ListHeader: any, EmptyState: any,
+ *   Skeleton: any, Menu: any, Button: any}} parts — the same host's components.
+ */
+export function makeDataTable(rn, parts) {
+  const { View, Text, Pressable, ScrollView, Platform, AccessibilityInfo } = rn;
+  const { List, ListRow, ListHeader, EmptyState, Skeleton, Menu, Button } = parts;
+  const web = Platform.OS === "web";
+
+  // A string or number becomes text in the slot's style; a node is drawn as given.
+  function cellNode(column, row, renderCell, style, lines) {
+    const own = column.render
+      ? column.render(row, column)
+      : typeof renderCell === "function"
+        ? renderCell(row, column)
+        : undefined;
+    const value = own !== undefined ? own : cellText(row && row[column.key]) || "—";
+    if (typeof value !== "string" && typeof value !== "number") return value;
+    return h(Text, { style: [style, { textAlign: column.align }], numberOfLines: lines }, value);
+  }
+
+  // `change` is null when nobody can act on a sort: a controlled one without
+  // `onSortChange` would be announced but never happen.
+  function useSort({ sort, defaultSort, onSortChange, labels, columns }) {
+    const [own, setOwn] = React.useState(() => normaliseSort(defaultSort));
+    const [spoken, setSpoken] = React.useState("");
+    const controlled = sort !== undefined;
+    const current = controlled ? normaliseSort(sort) : own;
+    const reported = typeof onSortChange === "function";
+    // The web refocuses the menu's trigger, whose name then says the sort.
+    const change = (key, { announce = true } = {}) => {
+      const next = nextSort(current, key);
+      if (!controlled) setOwn(next);
+      if (reported) onSortChange(next);
+      if (!announce) return;
+      const column = columns.find((c) => c.key === key);
+      const text = sortSpokenLabel(String(column ? column.label : key), { key }, next, labels);
+      if (web) setSpoken(text);
+      else if (AccessibilityInfo && typeof AccessibilityInfo.announceForAccessibility === "function") {
+        AccessibilityInfo.announceForAccessibility(text);
+      }
+    };
+    return [current, controlled && !reported ? null : change, spoken];
+  }
+
+  // The sort state is the button's description, so the tap's announcement
+  // is the one thing a reader says when it changes.
+  function HeaderCell({ column, sort, onSort, labels, testID }) {
+    const { colors, typography } = useTableTheme();
+    const stateId = React.useId();
+    const label = h(
+      Text,
+      {
+        style: [textRoleStyle("overline", typography, colors), { textAlign: column.align, flexShrink: 1 }],
+        numberOfLines: 1,
+      },
+      column.label,
+    );
+    if (!column.sortable || !onSort) return h(View, { style: cellBox(column) }, label);
+    const state = ariaSortFor(column, sort);
+    const words = sortStateWords(column, sort, labels);
+    const described = words ? (web ? { "aria-describedby": stateId } : { accessibilityHint: words }) : null;
+    return h(
+      View,
+      { style: cellBox(column) },
+      web && words ? h(Text, { nativeID: stateId, "aria-hidden": true, style: VISUALLY_HIDDEN }, words) : null,
+      h(
+        Pressable,
+        {
+          onPress: () => onSort(column.key),
+          accessibilityRole: "button",
+          accessibilityLabel: String(column.label),
+          ...described,
+          testID: testId(testID, `sort-${column.key}`),
+          style: {
+            minHeight: DATA_TABLE_HEADER_TARGET,
+            flexDirection: "row",
+            alignItems: "center",
+            justifyContent: justifyFor(column.align),
+            gap: 4,
+          },
+        },
+        label,
+        h(Icon, {
+          name: SORT_GLYPHS[state],
+          size: SORT_ICON_SIZE,
+          color: state === "none" ? colors.onSurfaceMuted : colors.onSurface,
+        }),
+      ),
+    );
+  }
+
+  // Inside a card's scope, so the text takes that card's own inks.
+  function StackedBody({ columns, row, renderCell }) {
+    const { colors, typography, spacing } = useTableTheme();
+    const caption = textRoleStyle("caption", typography, colors);
+    const body = textRoleStyle("body", typography, colors);
+    return h(
+      View,
+      { style: { flex: 1, minWidth: 0, gap: spacing.xs } },
+      ...columns.map((column) =>
+        h(
+          View,
+          { key: column.key, style: { gap: 2 } },
+          h(Text, { style: caption }, column.label),
+          cellNode({ ...column, align: "left" }, row, renderCell, body, undefined),
+        ),
+      ),
+    );
+  }
+
+  function CardBody({ columns, row, renderCell }) {
+    const { colors, typography, spacing } = useTableTheme();
+    const [first, ...details] = columns;
+    const caption = textRoleStyle("caption", typography, colors);
+    const body = textRoleStyle("body", typography, colors);
+    return h(
+      View,
+      { style: { flex: 1, minWidth: 0, gap: 2 } },
+      cellNode({ ...first, align: "left" }, row, renderCell, textRoleStyle("subtitle", typography, colors), 1),
+      details.length > 0
+        ? h(
+            View,
+            { style: { flexDirection: "row", alignItems: "center", gap: spacing.md, minWidth: 0 } },
+            ...details.map((column) =>
+              h(
+                View,
+                {
+                  key: column.key,
+                  style: { flexDirection: "row", alignItems: "center", gap: spacing.xs, flexShrink: 1, minWidth: 0 },
+                },
+                h(Text, { style: caption, numberOfLines: 1 }, column.label),
+                cellNode({ ...column, align: "left" }, row, renderCell, body, 1),
+              ),
+            ),
+          )
+        : null,
+    );
+  }
+
+  function ColumnCells({ columns, row, renderCell }) {
+    const { colors, typography } = useTableTheme();
+    const body = textRoleStyle("body", typography, colors);
+    return columns.map((column) =>
+      h(View, { key: column.key, style: cellBox(column) }, cellNode(column, row, renderCell, body, 1)),
+    );
+  }
+
+  function rowsOf(table, layout) {
+    const { columns, rows, keyField, renderCell, onRowPress, overrides, testID } = table;
+    const Body = layout === "stacked" ? StackedBody : layout === "cards" ? CardBody : ColumnCells;
+    return h(
+      List,
+      { ...overrides, variant: layout === "columns" ? "plain" : "card" },
+      ...rows.map((row, index) => {
+        const key = rowKey(row, keyField, index);
+        return h(
+          ListRow,
+          {
+            key,
+            onPress: typeof onRowPress === "function" ? () => onRowPress(row) : undefined,
+            testID: testId(testID, `row-${key}`),
+          },
+          h(Body, { columns, row, renderCell }),
+        );
+      }),
+    );
+  }
+
+  function bodyOf(table, layout) {
+    if (table.loading && table.rows.length === 0) {
+      return h(Skeleton, { shape: "listRow", count: DATA_TABLE_SKELETON_ROWS, leading: false });
+    }
+    if (table.rows.length === 0) {
+      return h(EmptyState, {
+        title: table.emptyTitle,
+        message: table.emptyMessage,
+        testID: testId(table.testID, "empty"),
+      });
+    }
+    return rowsOf(table, layout);
+  }
+
+  function SortMenu({ table }) {
+    const { columns, sort, onSort, labels, testID } = table;
+    const sortable = columns.filter((c) => c.sortable);
+    if (sortable.length === 0 || !onSort) return null;
+    const active = sort ? sortable.find((c) => c.key === sort.key) : undefined;
+    const state = active ? ariaSortFor(active, sort) : "none";
+    const spoken = active ? sortSpokenLabel(String(active.label), active, sort, labels) : "";
+    return h(
+      View,
+      { style: { flexDirection: "row", justifyContent: "flex-end" } },
+      h(Menu, {
+        accessibilityLabel: labels.sort,
+        testID: testId(testID, "sort-menu"),
+        trigger: h(Button, {
+          variant: "ghost",
+          title: active ? `${labels.sort}: ${active.label}` : labels.sort,
+          icon: SORT_GLYPHS[state],
+          iconPosition: "trailing",
+          accessibilityLabel: active ? `${labels.sort}: ${spoken}` : labels.sort,
+          testID: testId(testID, "sort"),
+        }),
+        items: sortable.map((column) => ({
+          key: column.key,
+          label: String(column.label),
+          icon: active && active.key === column.key ? SORT_GLYPHS[state] : undefined,
+          accessibilityLabel: sortSpokenLabel(String(column.label), column, sort, labels),
+          onPress: () => onSort(column.key, { announce: !web }),
+          testID: testId(testID, `sort-${column.key}`),
+        })),
+      }),
+    );
+  }
+
+  // Opaque, or scrolled rows show through: the rows' own Lists fill first.
+  function headerFill(theme, overrides) {
+    return resolveListTokens(theme, overrides).background || theme.colors.surface;
+  }
+
+  // Inside the page's scroller; Android scrolls only the outer one without it.
+  function ColumnsLayout({ table }) {
+    const theme = useTableTheme();
+    return h(
+      ScrollView,
+      {
+        style: { maxHeight: table.maxHeight },
+        nestedScrollEnabled: true,
+        stickyHeaderIndices: [0],
+        testID: testId(table.testID, "scroll"),
+      },
+      h(
+        ListHeader,
+        {
+          ...table.overrides,
+          style: { backgroundColor: headerFill(theme, table.overrides) },
+          testID: testId(table.testID, "header"),
+        },
+        ...table.columns.map((column) =>
+          h(HeaderCell, {
+            key: column.key,
+            column,
+            sort: table.sort,
+            onSort: table.onSort,
+            labels: table.labels,
+            testID: table.testID,
+          }),
+        ),
+      ),
+      bodyOf(table, "columns"),
+    );
+  }
+
+  function CardsLayout({ table, layout }) {
+    const { spacing } = useTableTheme();
+    return h(
+      View,
+      { style: { gap: spacing.sm } },
+      h(SortMenu, { table }),
+      h(
+        ScrollView,
+        { style: { maxHeight: table.maxHeight }, nestedScrollEnabled: true, testID: testId(table.testID, "scroll") },
+        bodyOf(table, layout),
+      ),
+    );
+  }
+
+  /**
+   * @param {object} props — see `DataTable` in index.d.ts.
+   */
+  function DataTable(props) {
+    const { rows, keyField = "id", sort, defaultSort, onSortChange, sortLabels, style, testID } = props;
+    const [width, onLayout] = useContainerWidth();
+    const layout = dataTableLayout(width);
+    const columns = normaliseColumns(props.columns);
+    const labels = { ...DEFAULT_SORT_LABELS, ...sortLabels };
+    const [current, onSort, spoken] = useSort({ sort, defaultSort, onSortChange, labels, columns });
+    const given = Array.isArray(rows) ? rows : [];
+    const emptyFallback = useHostSharedText("no_results", EMPTY_FALLBACK);
+    const table = {
+      columns,
+      rows: sortsClientSide(onSortChange) ? sortRows(given, current) : given,
+      keyField,
+      renderCell: props.renderCell,
+      onRowPress: props.onRowPress,
+      sort: current,
+      onSort,
+      labels,
+      loading: props.loading === true,
+      emptyTitle: props.emptyTitle,
+      emptyMessage: props.emptyMessage ?? (props.emptyTitle ? undefined : emptyFallback),
+      maxHeight: resolveMaxHeight(props.maxHeight),
+      overrides: listOverrides(props),
+      testID,
+    };
+    const content =
+      columns.length === 0
+        ? null
+        : layout === "columns"
+          ? h(ColumnsLayout, { table })
+          : h(CardsLayout, { table, layout });
+    return h(
+      View,
+      { testID, accessibilityLabel: props.accessibilityLabel, style: [{ alignSelf: "stretch" }, style] },
+      h(View, { onLayout }, content),
+      web ? h(Text, { "aria-live": "polite", style: VISUALLY_HIDDEN }, spoken) : null,
+    );
+  }
+  DataTable.displayName = "DataTable";
+
+  return DataTable;
+}

package/dist/data-table.js

@@ -0,0 +1,22 @@
+// `<DataTable>` (web). Binds ./data-table-view.js to react-native-web and the
+// web list, loading, menu and button parts; see ./primitives.js for why not
+// the bare specifier.
+
+import * as ReactNative from "react-native-web";
+import { List, ListRow, ListHeader, EmptyState } from "./list.js";
+import { Skeleton } from "./loading.js";
+import { Menu } from "./popover.js";
+import { Button } from "./button.js";
+import { makeDataTable } from "./data-table-view.js";
+
+export const DataTable = makeDataTable(
+  {
+    View: ReactNative.View,
+    Text: ReactNative.Text,
+    Pressable: ReactNative.Pressable,
+    ScrollView: ReactNative.ScrollView,
+    Platform: ReactNative.Platform,
+    AccessibilityInfo: ReactNative.AccessibilityInfo,
+  },
+  { List, ListRow, ListHeader, EmptyState, Skeleton, Menu, Button },
+);

package/dist/data-table.native.js

@@ -0,0 +1,14 @@
+// `<DataTable>` (native). Binds ./data-table-view.js to React Native's own
+// primitives and the native parts; only the imports differ from ./data-table.js.
+
+import { View, Text, Pressable, ScrollView, Platform, AccessibilityInfo } from "react-native";
+import { List, ListRow, ListHeader, EmptyState } from "./list.native.js";
+import { Skeleton } from "./loading.native.js";
+import { Menu } from "./popover.native.js";
+import { Button } from "./button.native.js";
+import { makeDataTable } from "./data-table-view.js";
+
+export const DataTable = makeDataTable(
+  { View, Text, Pressable, ScrollView, Platform, AccessibilityInfo },
+  { List, ListRow, ListHeader, EmptyState, Skeleton, Menu, Button },
+);