@colixsystems/widget-sdk 0.246.0 → 0.248.0

package/dist/data-table-logic.js

@@ -0,0 +1,179 @@
+// The `<DataTable>` rules without a renderer: which layout a width gets, how
+// its columns read, and how rows sort. React-free, so both hosts and the SDK's
+// own tests share one answer.
+
+import { widthTier } from "./container-width.js";
+
+/** The rows' scroll box stops here unless `maxHeight` says otherwise. */
+export const DATA_TABLE_DEFAULT_MAX_HEIGHT = 480;
+/** Placeholder rows while the first page loads. */
+export const DATA_TABLE_SKELETON_ROWS = 3;
+/** A sortable header is a button, so it keeps the touch-target floor. */
+export const DATA_TABLE_HEADER_TARGET = 44;
+export const DATA_TABLE_ALIGNS = Object.freeze(["left", "center", "right"]);
+export const DATA_TABLE_LAYOUTS = Object.freeze({
+  narrow: "stacked",
+  medium: "cards",
+  wide: "columns",
+});
+/** The English words a sort is spoken with; a widget passes its own language. */
+export const DEFAULT_SORT_LABELS = Object.freeze({
+  sort: "Sort",
+  ascending: "sorted ascending",
+  descending: "sorted descending",
+});
+
+const JUSTIFY = Object.freeze({ left: "flex-start", center: "center", right: "flex-end" });
+
+function isText(value) {
+  return typeof value === "string" && value.length > 0;
+}
+
+function positive(value, fallback) {
+  return typeof value === "number" && Number.isFinite(value) && value > 0 ? value : fallback;
+}
+
+/**
+ * The layout a MEASURED width calls for: stacked label/value cards when
+ * narrow, one card per row at medium, aligned columns when wide. An
+ * unmeasured width is "columns", as `widthTier(0)` is "wide".
+ */
+export function dataTableLayout(width) {
+  return DATA_TABLE_LAYOUTS[widthTier(width)];
+}
+
+function normaliseColumn(entry) {
+  const column = typeof entry === "string" ? { key: entry } : entry;
+  if (!column || typeof column !== "object" || !isText(column.key)) return null;
+  return {
+    key: column.key,
+    label: column.label !== undefined && column.label !== null ? column.label : column.key,
+    flex: positive(column.flex, 1),
+    align: DATA_TABLE_ALIGNS.includes(column.align) ? column.align : "left",
+    minWidth: positive(column.minWidth, 0),
+    sortable: column.sortable === true,
+    render: typeof column.render === "function" ? column.render : null,
+  };
+}
+
+/**
+ * The columns as the table draws them. A bare string is a column of that
+ * key; an entry without a key is dropped; a repeated key keeps its first.
+ */
+export function normaliseColumns(columns) {
+  if (!Array.isArray(columns)) return [];
+  const seen = new Set();
+  const out = [];
+  for (const entry of columns) {
+    const column = normaliseColumn(entry);
+    if (!column || seen.has(column.key)) continue;
+    seen.add(column.key);
+    out.push(column);
+  }
+  return out;
+}
+
+/** A `{ key, direction }` sort, or null when it names no column. */
+export function normaliseSort(sort) {
+  if (!sort || typeof sort !== "object" || !isText(sort.key)) return null;
+  return { key: sort.key, direction: sort.direction === "desc" ? "desc" : "asc" };
+}
+
+/** A header tap: a new column sorts ascending, the sorted one flips. */
+export function nextSort(current, key) {
+  const now = normaliseSort(current);
+  const flip = now && now.key === key && now.direction === "asc";
+  return { key, direction: flip ? "desc" : "asc" };
+}
+
+/** The text a cell shows for a record value; nothing for an empty one. */
+export function cellText(value) {
+  if (value === null || value === undefined) return "";
+  if (Array.isArray(value)) return value.map(cellText).filter(Boolean).join(", ");
+  if (typeof value === "string" || typeof value === "number" || typeof value === "boolean") {
+    return String(value);
+  }
+  if (typeof value === "object") {
+    for (const name of ["label", "name", "id"]) {
+      if (typeof value[name] === "string") return value[name];
+    }
+  }
+  return "";
+}
+
+function sortKey(value) {
+  if (typeof value === "number" && Number.isFinite(value)) return value;
+  if (value instanceof Date) return Number.isNaN(value.getTime()) ? null : value.getTime();
+  if (typeof value === "boolean") return value ? 1 : 0;
+  const text = cellText(value);
+  return text === "" ? null : text;
+}
+
+function compareKeys(a, b) {
+  if (typeof a === "number" && typeof b === "number") return a - b;
+  return String(a).localeCompare(String(b), undefined, { numeric: true, sensitivity: "base" });
+}
+
+/**
+ * The rows in `sort` order, as a new array; stable, with empty values last
+ * in either direction. Without a sort, the rows as given.
+ */
+export function sortRows(rows, sort) {
+  const list = Array.isArray(rows) ? rows : [];
+  const by = normaliseSort(sort);
+  if (!by) return list;
+  const sign = by.direction === "desc" ? -1 : 1;
+  return list
+    .map((row, index) => ({ row, index, key: sortKey(row && row[by.key]) }))
+    .sort((a, b) => {
+      if (a.key === null || b.key === null) {
+        return a.key === b.key ? a.index - b.index : a.key === null ? 1 : -1;
+      }
+      return sign * compareKeys(a.key, b.key) || a.index - b.index;
+    })
+    .map((entry) => entry.row);
+}
+
+/** A row's React key: its `keyField` value, else its position. */
+export function rowKey(row, keyField, index) {
+  const value = row && typeof row === "object" ? row[keyField] : undefined;
+  return value !== undefined && value !== null && value !== "" ? String(value) : `row-${index}`;
+}
+
+/** A sortable column's sort state: "none", "ascending" or "descending". */
+export function ariaSortFor(column, sort) {
+  const by = normaliseSort(sort);
+  if (!by || by.key !== column.key) return "none";
+  return by.direction === "desc" ? "descending" : "ascending";
+}
+
+/** A header's spoken name: its label, and the sort when it is the sorted one. */
+export function sortSpokenLabel(label, column, sort, labels = DEFAULT_SORT_LABELS) {
+  const words = sortStateWords(column, sort, labels);
+  return words ? `${label}, ${words}` : label;
+}
+
+/** The words a sorted column's state is spoken with; "" when it is not sorted. */
+export function sortStateWords(column, sort, labels = DEFAULT_SORT_LABELS) {
+  const state = ariaSortFor(column, sort);
+  if (state === "none") return "";
+  return state === "descending" ? labels.descending : labels.ascending;
+}
+
+/** The rows' scroll-box height: a positive number, else the default. */
+export function resolveMaxHeight(maxHeight) {
+  return positive(maxHeight, DATA_TABLE_DEFAULT_MAX_HEIGHT);
+}
+
+/** How a column's content sits across its cell. */
+export function justifyFor(align) {
+  return JUSTIFY[align] || JUSTIFY.left;
+}
+
+/**
+ * Who orders the rows. With `onSortChange` the widget re-queries (server
+ * sort) and the table draws the rows as given; without it the table sorts.
+ */
+export function sortsClientSide(onSortChange) {
+  return typeof onSortChange !== "function";
+}

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 },
+);