@colixsystems/widget-sdk 0.237.0 → 0.239.0

package/dist/list-view.js

@@ -14,6 +14,9 @@ import {
   resolveListTokens,
   listRowFrame,
   listSideEdgeWidth,
+  listCardRowFrame,
+  listCardGap,
+  listVariant,
   LIST_TOKEN_NAMES,
   LIST_SELECTED_BAR_WIDTH,
 } from "./list-tokens.js";
@@ -33,6 +36,10 @@ function listOverrides(props) {
   return out;
 }
 
+function hasNode(node) {
+  return node !== undefined && node !== null && node !== false;
+}
+
 function soleElement(children) {
   const parts = React.Children.toArray(children);
   return parts.length === 1 && React.isValidElement(parts[0]) ? parts[0] : null;
@@ -50,16 +57,31 @@ const HORIZONTAL_PADDING = [
 /**
  * Bind the shared list components to one platform's primitives.
  *
- * @param {{View: any, Text: any, Pressable: any}} rn
+ * @param {{View: any, Text: any, Pressable: any, Card: any}} rn — `Card` is
+ *   the platform's bound `<Card>`, the surface of a card-style list's rows.
  */
 export function makeList(rn) {
-  const { View, Text, Pressable } = rn;
+  const { View, Text, Pressable, Card } = rn;
   const ListContext = React.createContext(null);
 
+  // What a `<List>` hands its rows: overrides, the widget's defaults, its variant.
+  // Tokens carry into a nested list; the variant is each list's own.
+  function listContextValue(props, inherited) {
+    const { variant, defaults } = props;
+    return {
+      overrides: { ...(inherited && inherited.overrides), ...listOverrides(props) },
+      defaults: { ...(inherited && inherited.defaults), ...defaults },
+      variant: listVariant(variant),
+    };
+  }
+
   function useRowTokens(props) {
     const theme = useListTheme();
     const inherited = React.useContext(ListContext);
-    return [theme, resolveListTokens(theme, { ...inherited, ...listOverrides(props) })];
+    const list = listContextValue(props, inherited);
+    // Only a `<List>` chooses the variant; a row follows it.
+    const variant = inherited ? inherited.variant : "plain";
+    return [theme, resolveListTokens(theme, list.overrides, list.defaults), { ...list, variant }];
   }
 
   // A lone row View spans the row, as the title block does. Anything
@@ -71,52 +93,67 @@ export function makeList(rn) {
       : children;
   }
 
+  function titleBlock(title, subtitle, typography, colors) {
+    return React.createElement(
+      View,
+      { style: { flex: 1, gap: 2 } },
+      title !== undefined && title !== null
+        ? React.createElement(
+            Text,
+            { style: textRoleStyle("subtitle", typography, colors), numberOfLines: 1 },
+            title,
+          )
+        : null,
+      subtitle !== undefined && subtitle !== null
+        ? React.createElement(
+            Text,
+            { style: textRoleStyle("caption", typography, colors), numberOfLines: 2 },
+            subtitle,
+          )
+        : null,
+    );
+  }
+
+  function rowBody(props, typography, colors) {
+    return props.children !== undefined
+      ? customBody(props.children)
+      : titleBlock(props.title, props.subtitle, typography, colors);
+  }
+
   function setsOwnInset(style) {
     const flat = flattenStyle(style);
     return HORIZONTAL_PADDING.some((key) => flat[key] !== undefined);
   }
 
-  function List(props) {
-    const { children, style, testID } = props;
-    const theme = useListTheme();
-    const inherited = React.useContext(ListContext);
-    const overrides = { ...inherited, ...listOverrides(props) };
-    const tokens = resolveListTokens(theme, overrides);
-    // No divider under the last row: the list's own edge ends it.
-    const rows = React.Children.toArray(children);
-    const last = rows.length - 1;
-    const content = rows.map((row, i) =>
-      i === last && React.isValidElement(row) && row.props.divider === undefined
-        ? React.cloneElement(row, { divider: false })
-        : row,
-    );
-    return React.createElement(
-      ListContext.Provider,
-      { value: overrides },
-      React.createElement(View, { style: [{ gap: tokens.gap }, style], testID }, content),
-    );
-  }
-  List.displayName = "List";
-
-  function ListRow(props) {
-    const {
-      title,
-      subtitle,
-      leading,
-      trailing,
+  // accessibilityRole + aria-*: the pair that announces on both hosts.
+  function pressProps({ onPress, disabled = false, selected = false, accessibilityLabel }) {
+    return {
       onPress,
-      selected = false,
-      disabled = false,
-      divider = true,
+      disabled,
+      accessibilityRole: "button",
       accessibilityLabel,
-      style,
-      testID,
-      children,
-    } = props;
-    const [theme, tokens] = useRowTokens(props);
-    const { colors, spacing, typography } = theme;
+      "aria-selected": selected,
+      "aria-disabled": disabled,
+    };
+  }
 
-    const pressable = typeof onPress === "function";
+  // Beside `actions`, the tap target is the row minus its buttons,
+  // laid out as the row is so nothing moves.
+  function pressRegionStyle(style, spacing) {
+    const flat = flattenStyle(style);
+    return {
+      flex: 1,
+      minWidth: 0,
+      alignSelf: "stretch",
+      flexDirection: "row",
+      alignItems: flat.alignItems ?? "center",
+      gap: flat.gap ?? spacing.md,
+    };
+  }
+
+  function plainRowStyle(props, tokens, spacing) {
+    const { selected = false, divider = true, style } = props;
+    const pressable = typeof props.onPress === "function";
     // A tile is outlined; a flush band is separated by its bottom divider.
     const edge = tokens.separated
       ? tokens.dividerWidth > 0
@@ -125,7 +162,7 @@ export function makeList(rn) {
       : divider && tokens.dividerWidth > 0
         ? { borderBottomWidth: tokens.dividerWidth, borderColor: tokens.dividerColor }
         : null;
-    const rowStyle = {
+    return {
       // An inset the widget sets itself is left exactly as it asked.
       ...listRowFrame(tokens, spacing, selected && !setsOwnInset(style)),
       paddingVertical: tokens.rowPadding,
@@ -143,44 +180,44 @@ export function makeList(rn) {
           }
         : null),
     };
+  }
+
+  // The row's slots, with its own buttons kept outside the tap target.
+  function rowSlots(props, row) {
+    const { leading, trailing, actions, disabled = false, style } = props;
+    const body = rowBody(props, row.theme.typography, row.colors);
+    if (!row.splitPress) return [leading || null, body, trailing || null, actions || null];
+    return [
+      React.createElement(
+        Pressable,
+        {
+          ...pressProps(props),
+          onPressIn: () => row.setPressed(true),
+          onPressOut: () => row.setPressed(false),
+          style: [pressRegionStyle(style, row.theme.spacing), disabled ? { opacity: 0.5 } : null],
+        },
+        leading || null,
+        body,
+        trailing || null,
+      ),
+      actions,
+    ];
+  }
 
-    const body =
-      children !== undefined
-        ? customBody(children)
-        : React.createElement(
-            View,
-            { style: { flex: 1, gap: 2 } },
-            title !== undefined && title !== null
-              ? React.createElement(
-                  Text,
-                  {
-                    style: textRoleStyle("subtitle", typography, colors),
-                    numberOfLines: 1,
-                  },
-                  title,
-                )
-              : null,
-            subtitle !== undefined && subtitle !== null
-              ? React.createElement(
-                  Text,
-                  {
-                    style: textRoleStyle("caption", typography, colors),
-                    numberOfLines: 2,
-                  },
-                  subtitle,
-                )
-              : null,
-          );
-    const content = [leading || null, body, trailing || null];
+  function PlainRow({ props, row }) {
+    const { disabled = false, accessibilityLabel, style, testID } = props;
+    const rowStyle = plainRowStyle(props, row.tokens, row.theme.spacing);
+    const pressedFill = { backgroundColor: row.tokens.pressedBackground };
+    const content = rowSlots(props, { ...row, colors: row.theme.colors });
 
-    if (!pressable) {
+    if (!row.pressable || row.splitPress) {
       return React.createElement(
         View,
         {
-          style: [rowStyle, style],
+          style: [rowStyle, row.pressed ? pressedFill : null, style],
           testID,
-          accessibilityLabel,
-          accessible: accessibilityLabel ? true : undefined,
+          accessibilityLabel: row.splitPress ? undefined : accessibilityLabel,
+          accessible: accessibilityLabel && !row.splitPress ? true : undefined,
         },
         ...content,
       );
@@ -188,17 +225,11 @@ export function makeList(rn) {
     return React.createElement(
       Pressable,
       {
-        onPress,
-        disabled,
-        // accessibilityRole + aria-*: the pair that announces on both hosts.
-        accessibilityRole: "button",
-        accessibilityLabel,
-        "aria-selected": selected,
-        "aria-disabled": disabled,
+        ...pressProps(props),
         testID,
         style: ({ pressed }) => [
           rowStyle,
-          pressed ? { backgroundColor: tokens.pressedBackground } : null,
+          pressed ? pressedFill : null,
           disabled ? { opacity: 0.5 } : null,
           style,
         ],
@@ -206,6 +237,92 @@ export function makeList(rn) {
       ...content,
     );
   }
+
+  // Each row is the app's `<Card>`; the card scope paints it, the list
+  // scope arranges what is inside.
+  function CardRow({ props, row }) {
+    const { selected = false, disabled = false, accessibilityLabel, style, testID } = props;
+    const { tokens, theme } = row;
+    const frame = listCardRowFrame(tokens, theme.spacing, row.pressable);
+    // The card's own border carries the accent, so nothing shifts.
+    const mark = selected
+      ? { backgroundColor: tokens.selectedBackground, borderColor: tokens.selectedAccent }
+      : null;
+    const pressedFill = { backgroundColor: tokens.pressedBackground };
+    // A function child reads the inks of the card's own fill.
+    const content = ({ colors }) =>
+      React.createElement(React.Fragment, null, ...rowSlots(props, { ...row, colors }));
+
+    if (!row.pressable || row.splitPress) {
+      return React.createElement(
+        Card,
+        {
+          testID,
+          accessibilityLabel: row.splitPress ? undefined : accessibilityLabel,
+          accessible: accessibilityLabel && !row.splitPress ? true : undefined,
+          containerStyle: [frame, mark, row.pressed ? pressedFill : null, style],
+        },
+        content,
+      );
+    }
+    return React.createElement(
+      Card,
+      {
+        as: Pressable,
+        fillInGradient: true,
+        ...pressProps(props),
+        testID,
+        containerStyle: ({ pressed }) => [
+          frame,
+          mark,
+          pressed ? pressedFill : null,
+          disabled ? { opacity: 0.5 } : null,
+          style,
+        ],
+      },
+      content,
+    );
+  }
+
+  function List(props) {
+    const { children, style, testID } = props;
+    const theme = useListTheme();
+    const value = listContextValue(props, React.useContext(ListContext));
+    const tokens = resolveListTokens(theme, value.overrides, value.defaults);
+    const gap = value.variant === "card" ? listCardGap(tokens, theme.spacing) : tokens.gap;
+    // No divider under the last row: the list's own edge ends it.
+    const rows = React.Children.toArray(children);
+    const last = rows.length - 1;
+    const content = rows.map((row, i) =>
+      i === last && React.isValidElement(row) && row.props.divider === undefined
+        ? React.cloneElement(row, { divider: false })
+        : row,
+    );
+    return React.createElement(
+      ListContext.Provider,
+      { value },
+      React.createElement(View, { style: [{ gap }, style], testID }, content),
+    );
+  }
+  List.displayName = "List";
+
+  function ListRow(props) {
+    const [theme, tokens, list] = useRowTokens(props);
+    const [pressed, setPressed] = React.useState(false);
+    const pressable = typeof props.onPress === "function";
+    const row = {
+      theme,
+      tokens,
+      pressable,
+      // Buttons inside a button are unreachable; `actions` sit beside it.
+      splitPress: pressable && hasNode(props.actions),
+      pressed,
+      setPressed,
+    };
+    return list.variant === "card"
+      ? React.createElement(CardRow, { props, row })
+      : React.createElement(PlainRow, { props, row });
+  }
   ListRow.displayName = "ListRow";
 
   // A table's column labels: a ListRow's frame and body slot with none of its

package/dist/list.js

@@ -2,6 +2,12 @@
 // ./list-view.js to react-native-web; see ./primitives.js for why not the bare specifier.
 
 import * as ReactNative from "react-native-web";
+import { Card } from "./card.js";
 import { makeList } from "./list-view.js";
 
-export const { List, ListRow, ListHeader, EmptyState } = makeList(ReactNative);
+export const { List, ListRow, ListHeader, EmptyState } = makeList({
+  View: ReactNative.View,
+  Text: ReactNative.Text,
+  Pressable: ReactNative.Pressable,
+  Card,
+});

package/dist/list.native.js

@@ -1,7 +1,8 @@
 // `<List>`, `<ListRow>`, `<ListHeader>`, `<EmptyState>` (native). Binds
-// ./list-view.js to React Native's own primitives; only the import differs from ./list.js.
+// ./list-view.js to React Native's own primitives; only the imports differ from ./list.js.
 
 import { View, Text, Pressable } from "react-native";
+import { Card } from "./card.native.js";
 import { makeList } from "./list-view.js";
 
-export const { List, ListRow, ListHeader, EmptyState } = makeList({ View, Text, Pressable });
+export const { List, ListRow, ListHeader, EmptyState } = makeList({ View, Text, Pressable, Card });

package/dist/primitives.js

@@ -73,9 +73,7 @@ export { Icon } from "./icon.js";
 export { DateTimePicker } from "./datetimepicker.js";
 // sc-1378 — `<FilePicker>` (web). Wraps a hidden DOM `<input type="file">`
 // because react-native-web has no native equivalent. The native build's
-// counterpart (./filepicker.native.js) degrades to a disabled trigger until
-// a vetted expo-document-picker pin lands. `isSupported` is a static
-// boolean widgets branch on to hide the trigger on native.
+// counterpart (./filepicker.native.js) opens the OS document picker.
 export { FilePicker } from "./filepicker.js";
 // REQ-AI-AGENT-DESIGN (sc-3696) — `<Gradient>` (web). Paints a CSS
 // `linear-gradient` on a View; the native build (./gradient.native.js) delegates

package/dist/primitives.native.js

@@ -31,10 +31,8 @@ export { Icon } from "./icon.js";
 // `./datetimepicker.js`. Both files honour the same ISO 8601 value /
 // onChange contract.
 export { DateTimePicker } from "./datetimepicker.native.js";
-// sc-1378 — `<FilePicker>` (native). Web counterpart (./filepicker.js)
-// wraps a hidden DOM `<input type="file">`; native has no portable
-// equivalent yet, so this build renders a disabled trigger and exposes
-// `FilePicker.isSupported = false` for widgets to branch on.
+// sc-1378 — `<FilePicker>` (native). Opens the OS document picker
+// (expo-document-picker); the web counterpart wraps a hidden file input.
 export { FilePicker } from "./filepicker.native.js";
 // REQ-AI-AGENT-DESIGN (sc-3696) — `<Gradient>` (native). Delegates to
 // expo-linear-gradient (pinned unconditionally in every export); the web build

package/dist/property-schema.js

@@ -34,6 +34,11 @@ const VALID_TYPES = new Set([
   // `useNavigation().goTo(pageId, params)`. Bare uuid string — tenant-copy
   // remaps it through the layout walk's pageId map (see tenant-copy.service.js).
   "pageRef",
+  // REQ-BLD-19: `sectionRef` is a section picker for the widget's OWN page,
+  // emitting a bare layout node id; a widget scrolls to it via
+  // `useNavigation().scrollToSection(id)`. Node ids survive Copy Workspace
+  // unchanged, and page duplication remaps them, so no per-prop hook.
+  "sectionRef",
   // REQ-WDG-RICHTEXT: `richText` is a rich-text (HTML) string. Renders a
   // Tiptap editor in the Studio Properties Panel; the widget renders the
   // sanitised HTML. Stored as a string, so no tenant-copy remap is needed.
@@ -153,6 +158,7 @@ function coerceLeaf(def, value, path, errors) {
     case "recordBinding":
     case "groupRef":
     case "pageRef":
+    case "sectionRef":
     case "agentRef":
     case "richText":
     case "asset":

package/dist/select-logic.js

@@ -0,0 +1,83 @@
+// The `<Select>` rules that need no renderer: where focus lands when the
+// sheet opens, the draft a `multiple` select edits until Done, and what its
+// trigger shows. Both hosts share them, and the node suite tests them.
+
+/** The default trigger text once the picked labels no longer fit. */
+export function defaultSelectedCountText(count) {
+  return `${count} selected`;
+}
+
+/** A `values` prop as a list; anything else is no choice. */
+export function valueList(values) {
+  return Array.isArray(values) ? values : [];
+}
+
+/**
+ * The option focused when the sheet opens: the first picked one that can be
+ * picked, else the first enabled one, else -1.
+ *
+ * @param {Array<{disabled?: boolean}>} options
+ * @param {(option: object) => boolean} isPicked
+ */
+export function initialFocusIndex(options, isPicked) {
+  const list = Array.isArray(options) ? options : [];
+  const picked = list.findIndex((option) => isPicked(option) && !option.disabled);
+  return picked !== -1 ? picked : list.findIndex((option) => !option.disabled);
+}
+
+/**
+ * The draft with `value` added, or removed when it is already in it. Values
+ * compare strictly, so 1 and "1" are two choices.
+ *
+ * @param {Array<string|number>} draft
+ * @param {string|number} value
+ */
+export function toggleValue(draft, value) {
+  const list = valueList(draft);
+  return list.includes(value) ? list.filter((own) => own !== value) : [...list, value];
+}
+
+/**
+ * The values Done reports: the picked options in the order they are listed,
+ * then any picked value no option carries any more, so confirming without a
+ * change never drops a stored value.
+ *
+ * @param {Array<{value: string|number}>} options
+ * @param {Array<string|number>} draft
+ */
+export function committedValues(options, draft) {
+  const list = valueList(draft);
+  const known = (Array.isArray(options) ? options : []).map((option) => option.value);
+  return [
+    ...known.filter((value) => list.includes(value)),
+    ...list.filter((value) => !known.includes(value)),
+  ];
+}
+
+/** Whether two value lists hold the same values, whatever their order. */
+export function sameValues(a, b) {
+  const left = valueList(a);
+  const right = valueList(b);
+  return left.length === right.length && left.every((value) => right.includes(value));
+}
+
+/** The options whose value is picked, in the order they are listed. */
+export function pickedOptions(options, values) {
+  const list = valueList(values);
+  return (Array.isArray(options) ? options : []).filter((option) => list.includes(option.value));
+}
+
+/**
+ * What a `multiple` trigger shows: the placeholder with nothing picked, the
+ * picked labels as chips once they are measured to fit on its one line,
+ * otherwise the count. Until both widths are known it shows the count, so
+ * the trigger never draws chips that overflow it.
+ *
+ * @param {{picked: number, available?: number|null, needed?: number|null}} sizes
+ * @returns {"placeholder"|"chips"|"count"}
+ */
+export function triggerSummary({ picked, available, needed }) {
+  if (!picked) return "placeholder";
+  const measured = Number.isFinite(available) && Number.isFinite(needed) && available > 0;
+  return measured && needed <= available ? "chips" : "count";
+}