@colixsystems/widget-sdk 0.236.0 → 0.238.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/search-field-tokens.js

@@ -0,0 +1,85 @@
+// What `<SearchField>` draws from the theme's `search` scope: where its
+// magnifier sits, and the field look it lays over `<TextField>`'s `muted` one.
+// Platform-free, so both hosts lay the field out from the same answer.
+
+import { CONTRACT } from "./contract.js";
+import { normaliseThemeComponents } from "./theme-components.js";
+import { resolveTextFieldTokens } from "./text-field-tokens.js";
+
+export const SEARCH_ICON_POSITIONS = CONTRACT.themeComponentSearchIconPositions;
+export const DEFAULT_SEARCH_ICON_POSITION = "start";
+
+// The `search` tokens that restyle the field; each is a `<TextField>` override.
+export const SEARCH_FIELD_LOOK_TOKENS = Object.freeze([
+  "background",
+  "borderColor",
+  "radius",
+  "height",
+]);
+
+function searchScope(theme) {
+  const components = theme && typeof theme === "object" ? theme.components : undefined;
+  return normaliseThemeComponents({ search: components && components.search }).search || {};
+}
+
+/**
+ * The magnifier's position: the field's own prop, then the theme, then start.
+ *
+ * @param {unknown} own — the `iconPosition` prop.
+ * @param {unknown} themed — the theme's `search.iconPosition`.
+ */
+export function searchIconPosition(own, themed) {
+  if (SEARCH_ICON_POSITIONS.includes(own)) return own;
+  if (SEARCH_ICON_POSITIONS.includes(themed)) return themed;
+  return DEFAULT_SEARCH_ICON_POSITION;
+}
+
+/**
+ * Resolve one search field. `field` holds only the tokens the theme set, so
+ * an unset one leaves `<TextField>` on the `muted` look it always drew.
+ *
+ * @param {object} theme — the resolved workspace theme (`useTheme()` shape).
+ * @param {{ iconPosition?: string }} [own] — the field's own props.
+ * @returns {{ iconPosition: string, field: Record<string, string|number> }}
+ */
+export function resolveSearchFieldTokens(theme, own) {
+  const scope = searchScope(theme);
+  const field = {};
+  for (const name of SEARCH_FIELD_LOOK_TOKENS) {
+    if (scope[name] !== undefined) field[name] = scope[name];
+  }
+  return {
+    iconPosition: searchIconPosition(own && own.iconPosition, scope.iconPosition),
+    field,
+  };
+}
+
+/**
+ * Where the glyph and the clear control go. At the end, the clear control
+ * takes the glyph's slot while there is text, so the two never overlap.
+ *
+ * @param {string} iconPosition — a resolved SEARCH_ICON_POSITIONS value.
+ * @param {boolean} clearable — the field has text and is enabled.
+ * @returns {{ glyph: "start"|"end"|null, padStart: boolean, padEnd: boolean }}
+ */
+export function searchFieldLayout(iconPosition, clearable) {
+  const glyphAtEnd = iconPosition === "end" && !clearable;
+  return {
+    glyph: iconPosition === "start" ? "start" : glyphAtEnd ? "end" : null,
+    padStart: iconPosition === "start",
+    padEnd: clearable || iconPosition === "end",
+  };
+}
+
+/**
+ * What each `search` token resolves to while unset, keyed by token name, for
+ * the Studio to preview: the `muted` field the search box falls back to.
+ *
+ * @param {object} theme — the resolved workspace theme.
+ */
+export function searchScopeDefaults(theme) {
+  const field = resolveTextFieldTokens(theme);
+  const out = { iconPosition: DEFAULT_SEARCH_ICON_POSITION };
+  for (const name of SEARCH_FIELD_LOOK_TOKENS) out[name] = field[name];
+  return out;
+}

package/dist/search-field-view.js

@@ -1,13 +1,15 @@
 // The ONE implementation behind the `<SearchField>` SDK primitive. It is
 // `<TextField>` with a search glyph and a clear control, so it wears the same
-// field and takes the same props; the platform bindings (`search-field.js` /
-// `search-field.native.js`) differ only in where the primitives come from.
+// field and takes the same props, plus the theme's `search` look; the platform
+// bindings (`search-field.js` / `search-field.native.js`) differ only in where
+// the primitives come from.
 
 import React from "react";
 import { useHostTheme } from "./hooks.js";
 import { DEFAULT_THEME_TOKENS } from "./_theme-tokens.js";
 import { Icon } from "./icon.js";
 import { resolveFormControlTokens } from "./form-control-tokens.js";
+import { resolveSearchFieldTokens, searchFieldLayout } from "./search-field-tokens.js";
 import {
   errorMessage,
   hasNote,
@@ -24,6 +26,17 @@ const ADORNMENT_WIDTH = 40;
 // A real target: the web host ignores hitSlop, so size carries it.
 const CLEAR_MIN_SIZE = 36;
 
+function adornmentSlot(side) {
+  return {
+    position: "absolute",
+    top: 0,
+    bottom: 0,
+    alignItems: "center",
+    justifyContent: "center",
+    ...(side === "start" ? { left: 0 } : { right: 0 }),
+  };
+}
+
 /**
  * Bind the shared search field to one platform's primitives.
  *
@@ -45,6 +58,7 @@ export function makeSearchField(rn) {
       error,
       disabled = false,
       accessibilityLabel,
+      iconPosition,
       style,
       containerStyle,
       testID,
@@ -52,6 +66,7 @@ export function makeSearchField(rn) {
     } = props;
     const theme = useHostTheme() || DEFAULT_THEME_TOKENS;
     const t = resolveFormControlTokens(theme);
+    const search = resolveSearchFieldTokens(theme, { iconPosition });
     const inputRef = React.useRef(null);
     const setRef = React.useMemo(() => shareRef(ref, inputRef), [ref]);
     const noteId = React.useId();
@@ -60,6 +75,8 @@ export function makeSearchField(rn) {
       if (input && typeof input.focus === "function") input.focus();
     };
     const hasText = typeof value === "string" && value.length > 0;
+    const clearable = hasText && !disabled;
+    const layout = searchFieldLayout(search.iconPosition, clearable);
     const clear = () => {
       if (typeof onChangeText === "function") onChangeText("");
       if (typeof onClear === "function") onClear();
@@ -98,30 +115,30 @@ export function makeSearchField(rn) {
           autoCapitalize: "none",
           autoCorrect: false,
           testID,
+          // The field's own props beat the theme's search look.
+          ...search.field,
           ...rest,
           style: [
-            { paddingLeft: ADORNMENT_WIDTH },
-            hasText && !disabled ? { paddingRight: ADORNMENT_WIDTH } : null,
+            layout.padStart ? { paddingLeft: ADORNMENT_WIDTH } : null,
+            layout.padEnd ? { paddingRight: ADORNMENT_WIDTH } : null,
             style,
           ],
         }),
-        h(
-          View,
-          {
-            style: {
-              position: "absolute",
-              left: 0,
-              top: 0,
-              bottom: 0,
-              width: ADORNMENT_WIDTH,
-              alignItems: "center",
-              justifyContent: "center",
-              pointerEvents: "none",
-            },
-          },
-          h(Icon, { name: "search", size: GLYPH_SIZE, color: t.placeholderColor }),
-        ),
-        hasText && !disabled
+        layout.glyph
+          ? h(
+              View,
+              {
+                testID: testID ? `${testID}-icon` : undefined,
+                style: {
+                  ...adornmentSlot(layout.glyph),
+                  width: ADORNMENT_WIDTH,
+                  pointerEvents: "none",
+                },
+              },
+              h(Icon, { name: "search", size: GLYPH_SIZE, color: t.placeholderColor }),
+            )
+          : null,
+        clearable
           ? h(
               Pressable,
               {
@@ -131,14 +148,10 @@ export function makeSearchField(rn) {
                 testID: testID ? `${testID}-clear` : undefined,
                 style: ({ pressed }) => [
                   {
-                    position: "absolute",
+                    ...adornmentSlot("end"),
                     right: 2,
-                    top: 0,
-                    bottom: 0,
                     minWidth: CLEAR_MIN_SIZE,
                     minHeight: CLEAR_MIN_SIZE,
-                    alignItems: "center",
-                    justifyContent: "center",
                   },
                   pressed ? { opacity: 0.6 } : null,
                 ],