@colixsystems/widget-sdk 0.162.0 → 0.164.0

package/README.md

@@ -73,7 +73,38 @@ See the design reference for the full architecture: [`docs/architecture/widget-m
 
 ## Status
 
-`v0.162.0` — pre-publish. The package surface (types, function names, export paths) is the v1 contract; runtime behaviour for some hooks is stubbed (each hook documents what's wired and what isn't). It is **not yet published to npm**.
+`v0.164.0` — pre-publish. The package surface (types, function names, export paths) is the v1 contract; runtime behaviour for some hooks is stubbed (each hook documents what's wired and what isn't). It is **not yet published to npm**.
+
+### What's new in 0.164.0 (contract 1.127.0)
+
+**`Card`, `Button` and `TextField` — the built-in widgets' own surfaces, now yours.** The built-in widgets drew their cards, buttons and text fields from shared code only they could reach, so a custom widget had to re-invent each one and never quite matched. The same implementations are now SDK components, and the built-ins render through them:
+
+```jsx
+<Card>
+  <TextField value={name} onChangeText={setName} placeholder="Your name" accessibilityLabel="Name" />
+  <Button title="Save" onPress={save} />
+</Card>
+```
+
+- **`<Card>`** takes the app's card look (Theme Settings > Cards) with no props. Override one card with `background`, `borderColor`, `radius`, `padding`, `shadow` or `gradient`, or pass `style={props.style}` when your widget declares the `card*` style fields. `as={Pressable}` makes the whole card pressable.
+- **`<Button>`** follows Theme Settings > Buttons (and Destructive / Focus ring). `variant` is `primary` | `secondary` | `outlined` | `danger`; `icon` / `iconPosition` add a lucide glyph; omit `onPress` for a visual inside something pressable; `fields` overrides one button's surface.
+- **`<TextField>`** is a `TextInput` in the app's input look (Theme Settings > Muted, which gains a **`height`** token); `multiline` grows to a ceiling, then scrolls.
+
+The card and button resolvers (`cardOverlay`, `shadowStyle`, `marginStyle`, `buttonSurfaceOverlay`, …) are exported too. Additive: the built-in widgets render exactly as before.
+
+### What's new in 0.163.0 (contract 1.126.0)
+
+**A themed tab strip: `Tabs`, and the `tabs` theme scope.** `<Tabs items={[{ key, label, icon? }]} value={tab} onChange={setTab} />` draws a strip whose look — a segmented control, pills, or an underline — and whose colours and corners come from **Theme Settings > Tabs** (`themeConfig.components.tabs`). It draws the strip only; render the selected panel yourself. The page Tabs container now renders through the same component on the web Player and in the exported app, so a page's tabs and a widget's tabs match, and the two hosts no longer draw different strips. Unthemed, the strip is the segmented control the exported app always drew.
+
+```jsx
+const [tab, setTab] = useState("open");
+<Tabs items={[{ key: "open", label: "Open" }, { key: "done", label: "Done", icon: "check" }]} value={tab} onChange={setTab} />
+{tab === "open" ? <OpenOrders /> : <DoneOrders />}
+```
+
+Pass `variant` ("segmented" | "pill" | "underline"), `activeColor`, `activeTextColor`, `textColor` or `radius` to override one strip, or declare the style fields `tabsStyle`, `tabsActiveColor`, `tabsActiveTextColor`, `tabsTextColor` and `tabsRadius` so an author can.
+
+The component-token vocabulary gains an **`enum`** type (`{ type: "enum", values }`), first used by `tabs.style`; `CONTRACT.themeComponentTabStyles` lists the styles.
 
 ### What's new in 0.162.0 (contract 1.125.0)
 
@@ -1787,6 +1818,8 @@ import { defineWidget, validateManifest, useDatastoreQuery, Text, View } from "@
 - `parseMarkdown`, `markdownToPlainText`, `parseMarkdownImage`, `formatMarkdownImage`, `stripHtmlToMarkdown`, `MARKDOWN_IMAGE_SIZES` — the same grammar as pure helpers, for content you inspect rather than render: the block list, a marker-free projection (list previews, search, a11y labels), the one-line image form read and written, a legacy-HTML row normalised to markdown on read, and the closed size list (`small` | `medium` | `large` | `full`).
 - `isSafeMarkdownImageSrc`, `isHttpImageSrc`, `normaliseMarkdownImageSize`, `readMarkdownAlt` — the image half of that grammar, for a widget rendering images itself via `renderImage`. `isSafeMarkdownImageSrc` is the same allowlist the parser applies (an `http(s)` URL or a filestore id; a `javascript:` scheme is refused), so the widget and the parser cannot disagree about which src is renderable.
 - `List`, `ListRow`, `EmptyState` — the themed list building blocks. `<ListRow title subtitle leading trailing onPress selected divider>` draws one record row from the theme's `list` scope (padding, height, gap, radius, background, divider); `<List>` spaces its rows and hands overrides down; `<EmptyState icon title message>` is the "nothing here" panel. Never hand-roll a row from `View` + `Pressable`.
+- `Card`, `Button`, `TextField` — the themed card surface, button and text field the built-in widgets render through. With no props each takes the app's look from Theme Settings (Cards, Buttons, Muted); never hand-roll one from `View` / `Pressable` / a bare `TextInput`.
+- `Tabs` — the themed tab strip. `<Tabs items value onChange>` draws a segmented control, pills or an underline as the theme's `tabs` scope says; render the selected panel yourself. Never hand-roll tabs from `Pressable` chips.
 - `textRoleStyle(role, typography, colors)`, `TEXT_ROLES` — the style of a semantic text tier, shared with the built-in widgets.
 - `WidgetContextProvider` — React context provider that the host (Studio, Player, exported app) wraps widgets with.
 

package/dist/button-style.js

@@ -0,0 +1,60 @@
+// The button-surface resolvers behind `<Button>`: one source for the SDK and
+// the built-in widgets (frontend `_shared/buttonStyle.js` re-exports these).
+// Platform-free, so both hosts resolve a button identically.
+
+export const BUTTON_PADDING_MAX = 64;
+export const BUTTON_BORDER_WIDTH_MAX = 8;
+
+// `stretch` is absent on purpose: a button never grows to its container.
+export const SELF_ALIGNMENTS = Object.freeze({
+  start: "flex-start",
+  center: "center",
+  end: "flex-end",
+});
+
+function read(style, prefix, key) {
+  const name = prefix
+    ? `${prefix}${key[0].toUpperCase()}${key.slice(1)}`
+    : key;
+  return style ? style[name] : undefined;
+}
+
+function px(value, max) {
+  return typeof value === "number" && Number.isFinite(value) && value >= 0
+    ? Math.min(value, max)
+    : undefined;
+}
+
+/**
+ * The container overlay for the set button-surface fields: padding, border
+ * colour and width. A width of 0 removes a variant's border, so zero survives.
+ * `prefix` reads a re-keyed field set (`buttonPaddingX`).
+ */
+export function buttonSurfaceOverlay(style, prefix = "") {
+  const paddingX = px(read(style, prefix, "paddingX"), BUTTON_PADDING_MAX);
+  const paddingY = px(read(style, prefix, "paddingY"), BUTTON_PADDING_MAX);
+  const borderColor = read(style, prefix, "borderColor");
+  const borderWidth = px(
+    read(style, prefix, "borderWidth"),
+    BUTTON_BORDER_WIDTH_MAX,
+  );
+  const overlay = {
+    ...(paddingX !== undefined ? { paddingHorizontal: paddingX } : null),
+    ...(paddingY !== undefined ? { paddingVertical: paddingY } : null),
+    ...(borderColor ? { borderWidth: 1, borderColor } : null),
+    ...(borderWidth !== undefined ? { borderWidth } : null),
+  };
+  return Object.keys(overlay).length > 0 ? overlay : null;
+}
+
+/** The label overlay for the button-surface fields that live on the text. */
+export function buttonSurfaceTextOverlay(style, prefix = "") {
+  const fontWeight = read(style, prefix, "fontWeight");
+  return fontWeight ? { fontWeight: String(fontWeight) } : null;
+}
+
+/** The author's alignment, or null to keep the widget's own default. */
+export function selfAlignStyle(style) {
+  const alignSelf = SELF_ALIGNMENTS[style && style.align];
+  return alignSelf ? { alignSelf } : null;
+}

package/dist/button-view.js

@@ -0,0 +1,197 @@
+// The ONE button surface, behind the `<Button>` SDK primitive and the built-in
+// Button widget. The bindings (`button.js` / `button.native.js`) differ only in
+// their primitives and in which `<Gradient>` paints a gradient fill.
+
+import React from "react";
+import { useHostTheme } from "./hooks.js";
+import { DEFAULT_THEME_TOKENS } from "./_theme-tokens.js";
+import { lucideGlyph } from "./icon.js";
+import { applyThemeComponentStyle } from "./theme-components.js";
+import { cornerRadiusOverlay, shadowStyle, gradientProps } from "./card-style.js";
+import { buttonSurfaceOverlay, buttonSurfaceTextOverlay } from "./button-style.js";
+
+export const BUTTON_VARIANTS = Object.freeze(["primary", "secondary", "outlined", "danger"]);
+
+// The theme's button, destructive and ring scopes reach a custom widget's
+// button exactly as the host folds them onto the built-in one.
+const THEMED_AS = "appstudio.button";
+
+function variantPaint(variant, colors) {
+  if (variant === "secondary") {
+    return {
+      container: { backgroundColor: colors.secondary, borderWidth: 1, borderColor: colors.border },
+      ink: colors.onSecondary,
+    };
+  }
+  if (variant === "danger") {
+    return {
+      container: { backgroundColor: colors.danger, borderWidth: 1, borderColor: colors.danger },
+      ink: colors.onPrimary,
+    };
+  }
+  if (variant === "outlined") {
+    return {
+      container: { backgroundColor: "transparent", borderWidth: 1, borderColor: colors.primary },
+      ink: colors.primary,
+    };
+  }
+  return { container: { backgroundColor: colors.primary }, ink: colors.onPrimary };
+}
+
+// Precedence, weakest first: variant, danger scope, ring, then the fields.
+function containerLayers(variant, f, colors) {
+  const paint = variantPaint(variant, colors);
+  let ink = paint.ink;
+  const layers = [paint.container];
+  if (variant === "danger") {
+    if (f.dangerBackground) layers.push({ backgroundColor: f.dangerBackground });
+    if (f.dangerBorderColor) layers.push({ borderWidth: 1, borderColor: f.dangerBorderColor });
+    if (f.dangerTextColor) ink = f.dangerTextColor;
+  }
+  if (f.ringColor) {
+    layers.push({
+      borderWidth: typeof f.ringWidth === "number" ? f.ringWidth : 2,
+      borderColor: f.ringColor,
+    });
+  }
+  if (f.background) layers.push({ backgroundColor: f.background });
+  layers.push(buttonSurfaceOverlay(f));
+  layers.push(cornerRadiusOverlay(f.radius));
+  if (f.textColor) ink = f.textColor;
+  if (f.shadow) layers.push(shadowStyle(f.shadow));
+  return { layers, ink };
+}
+
+// An unknown name draws nothing: a button keeps its label, not a placeholder.
+function iconNode(name, size, color) {
+  if (typeof name !== "string" || name.trim().length === 0) return null;
+  const Glyph = lucideGlyph(name);
+  return Glyph ? React.createElement(Glyph, { size, color }) : null;
+}
+
+// A positioned wrapper keeps a bare web <svg> above the absolute gradient fill.
+function wrapGlyph(View, glyph, key) {
+  return React.createElement(View, { key }, glyph);
+}
+
+/**
+ * Bind the shared button to one platform's primitives.
+ *
+ * @param {{View: any, Text: any, Pressable: any, StyleSheet: any, Gradient: any}} rn
+ */
+export function makeButton(rn) {
+  const { View, Text, Pressable, StyleSheet, Gradient } = rn;
+
+  /**
+   * @param {string} props.title — the label.
+   * @param {string} [props.variant] — primary | secondary | outlined | danger.
+   * @param {object} [props.fields] — per-instance button-surface fields
+   *   (background, textColor, borderColor, borderWidth, paddingX, paddingY,
+   *   radius, fontWeight, fontSize, shadow, gradient, danger*, ring*).
+   * @param {Function} [props.onPress] — makes it pressable; omit for a visual.
+   * @param {object|Array} [props.style] — extra container style, merged last.
+   * @param {object|Array} [props.labelStyle] — extra label style.
+   * @param {boolean} [props.hostThemed] — `fields` already carry the theme
+   *   (a built-in the host folded); skip the second fold, which would add the
+   *   Button widget's own scopes to a form submit or a Link action.
+   */
+  function Button({
+    title,
+    variant = "primary",
+    icon,
+    iconPosition = "leading",
+    fields,
+    onPress,
+    disabled = false,
+    style,
+    labelStyle,
+    hostThemed = false,
+    accessibilityLabel,
+    testID,
+  }) {
+    const theme = useHostTheme() || DEFAULT_THEME_TOKENS;
+    const { colors, spacing, radii, typography } = theme;
+    const f = hostThemed
+      ? fields || {}
+      : applyThemeComponentStyle(THEMED_AS, theme, { style: fields }).style || {};
+    const resolvedVariant = BUTTON_VARIANTS.includes(variant) ? variant : "primary";
+    const { layers, ink } = containerLayers(resolvedVariant, f, colors);
+
+    const fontSize =
+      typeof f.fontSize === "number" && Number.isFinite(f.fontSize)
+        ? f.fontSize
+        : typography.sizes.sm;
+    const glyph = iconNode(icon, Math.round(fontSize), ink);
+    const gradient = gradientProps(f.gradient);
+
+    const container = [
+      {
+        paddingHorizontal: spacing.md,
+        paddingVertical: spacing.sm,
+        borderRadius: radii.sm,
+        minHeight: 44,
+        minWidth: 64,
+        alignItems: "center",
+        justifyContent: "center",
+        alignSelf: "flex-start",
+      },
+      ...layers,
+      glyph ? { flexDirection: "row", gap: spacing.xs } : null,
+      // The gradient IS the fill, so it drops every flat background.
+      gradient ? { backgroundColor: "transparent" } : null,
+      disabled ? { opacity: 0.5 } : null,
+      style,
+    ];
+    const label = React.createElement(
+      Text,
+      {
+        style: [
+          { fontSize: typography.sizes.sm, fontWeight: "600", fontFamily: typography.fontFamily },
+          { color: ink },
+          typeof f.fontSize === "number" ? { fontSize: f.fontSize } : null,
+          labelStyle,
+          buttonSurfaceTextOverlay(f),
+        ],
+      },
+      title,
+    );
+    const children = [
+      gradient
+        ? React.createElement(Gradient, {
+            key: "fill",
+            colors: gradient.colors,
+            angle: gradient.angle,
+            // Rounded rather than clipped: `overflow: hidden` drops an iOS shadow.
+            style: [
+              StyleSheet.absoluteFill,
+              { borderRadius: radii.sm, pointerEvents: "none" },
+              cornerRadiusOverlay(f.radius),
+            ],
+          })
+        : null,
+      glyph && iconPosition !== "trailing" ? wrapGlyph(View, glyph, "lead") : null,
+      React.cloneElement(label, { key: "label" }),
+      glyph && iconPosition === "trailing" ? wrapGlyph(View, glyph, "trail") : null,
+    ];
+
+    if (typeof onPress !== "function") {
+      return React.createElement(View, { style: container, testID, accessibilityLabel }, children);
+    }
+    return React.createElement(
+      Pressable,
+      {
+        onPress,
+        disabled,
+        accessibilityRole: "button",
+        accessibilityLabel: accessibilityLabel || (typeof title === "string" ? title : undefined),
+        "aria-disabled": disabled,
+        testID,
+        style: ({ pressed }) => [...container, pressed && !disabled ? { opacity: 0.85 } : null],
+      },
+      children,
+    );
+  }
+
+  Button.displayName = "Button";
+  return Button;
+}

package/dist/button.js

@@ -0,0 +1,10 @@
+// `<Button>` (web). Binds ./button-view.js to react-native-web and the CSS
+// gradient; see ./primitives.js for why not the bare specifier.
+
+import * as ReactNative from "react-native-web";
+import { Gradient } from "./gradient.js";
+import { makeButton, BUTTON_VARIANTS } from "./button-view.js";
+
+export { BUTTON_VARIANTS };
+
+export const Button = makeButton({ ...ReactNative, Gradient });

package/dist/button.native.js

@@ -0,0 +1,10 @@
+// `<Button>` (native). Binds ./button-view.js to React Native and the
+// expo-linear-gradient `<Gradient>`; only the imports differ from ./button.js.
+
+import { View, Text, Pressable, StyleSheet } from "react-native";
+import { Gradient } from "./gradient.native.js";
+import { makeButton, BUTTON_VARIANTS } from "./button-view.js";
+
+export { BUTTON_VARIANTS };
+
+export const Button = makeButton({ View, Text, Pressable, StyleSheet, Gradient });

package/dist/card-style.js

@@ -0,0 +1,80 @@
+// The card-surface resolvers behind `<Card>`: one source for the SDK, the
+// built-in widgets (frontend `_shared/cardStyle.js` re-exports these) and the
+// exported app. Platform-free, so both hosts resolve a card identically.
+//
+// Every resolver emits ONLY the fields that are set, so a widget's own base
+// style keeps whatever the author left alone.
+
+import { CONTRACT, normaliseComponentGradient } from "./contract.js";
+import { normaliseCornerRadius, cornerRadiusStyle } from "./corner-radius.js";
+import { normaliseSpacing, spacingStyle, isZeroSpacing } from "./spacing.js";
+
+export const SHADOW_PRESETS = CONTRACT.themeTokens.elevation;
+
+/** An elevation level as an RN style object; unknown / unset is none. */
+export function shadowStyle(shadow) {
+  return SHADOW_PRESETS[shadow] || SHADOW_PRESETS.none;
+}
+
+export const SPACING_MAX_PX = 64;
+export const CARD_RADIUS_MAX_PX = 48;
+export const FRAME_RADIUS_MAX_PX = 64;
+
+/**
+ * The widget's outer margin. A full-bleed widget keeps only its vertical
+ * margin, so a side margin cannot pull the band back off the screen edge.
+ */
+export function marginStyle(style) {
+  const m = normaliseSpacing(style && style.margin, 0, SPACING_MAX_PX);
+  if (isZeroSpacing(m)) return null;
+  if (style.fullBleed) return { marginTop: m.top, marginBottom: m.bottom };
+  return spacingStyle(m, "margin");
+}
+
+/** A per-side padding/margin value; unset stays unset, an explicit 0 applies. */
+export function spacingOverlay(value, property, max = SPACING_MAX_PX) {
+  if (value === undefined || value === null || value === "") return null;
+  return spacingStyle(normaliseSpacing(value, 0, max), property);
+}
+
+/** A per-corner radius value; unset stays unset. */
+export function cornerRadiusOverlay(value, max = CARD_RADIUS_MAX_PX) {
+  if (value === undefined || value === null || value === "") return null;
+  return cornerRadiusStyle(normaliseCornerRadius(value, 0, max));
+}
+
+/** The card surface — every `card*` field plus the shadow, and no margin. */
+export function cardSurfaceStyle(style) {
+  const s = style || {};
+  return {
+    ...(s.cardBackground ? { backgroundColor: s.cardBackground } : null),
+    ...(s.cardBorderColor
+      ? { borderColor: s.cardBorderColor, borderWidth: 1 }
+      : null),
+    ...cornerRadiusOverlay(s.cardRadius, CARD_RADIUS_MAX_PX),
+    ...spacingOverlay(s.cardPadding, "padding"),
+    ...shadowStyle(s.shadow),
+  };
+}
+
+/** The card surface plus the widget's outer margin. */
+export function cardOverlay(style) {
+  return { ...cardSurfaceStyle(style), ...marginStyle(style || {}) };
+}
+
+/**
+ * A gradient value as `<Gradient>` props, or null when unpaintable. A
+ * per-instance value runs through the same normaliser the theme uses, so the
+ * two routes agree on which values paint.
+ */
+export function gradientProps(value) {
+  const gradient = normaliseComponentGradient(value);
+  return gradient
+    ? { colors: [gradient.from, gradient.to], angle: gradient.angle }
+    : null;
+}
+
+/** The card-surface gradient (`cardGradient`). */
+export function cardGradientProps(style) {
+  return gradientProps(style && style.cardGradient);
+}

package/dist/card-view.js

@@ -0,0 +1,174 @@
+// The ONE card surface, behind the `<Card>` SDK primitive and every built-in
+// widget that paints a card. The bindings (`card.js` / `card.native.js`) differ
+// only in their primitives and in which `<Gradient>` paints a gradient fill.
+//
+// A gradient is a COMPONENT on both hosts, never a style value, so the element
+// swap lives here once rather than in each widget.
+
+import React from "react";
+import { useHostTheme } from "./hooks.js";
+import { DEFAULT_THEME_TOKENS } from "./_theme-tokens.js";
+import { CONTRACT } from "./contract.js";
+import { cardOverlay, cardSurfaceStyle, cardGradientProps } from "./card-style.js";
+import { normaliseThemeComponents } from "./theme-components.js";
+
+// A wrapped scroller stays transparent and fits inside the gradient.
+const SCROLLER_IN_GRADIENT = { backgroundColor: "transparent", flexShrink: 1 };
+
+// A pressable inner container must still cover the whole card.
+const FILL_IN_GRADIENT = {
+  backgroundColor: "transparent",
+  flexGrow: 1,
+  alignSelf: "stretch",
+};
+
+const CLIP_TO_RADIUS = { overflow: "hidden" };
+
+const CARD_FIELDS = CONTRACT.themeComponents.card.universalFields;
+
+// The convenience props, each named for the `card*` field it sets.
+const PROP_FIELDS = Object.freeze({
+  background: CARD_FIELDS.background,
+  borderColor: CARD_FIELDS.borderColor,
+  radius: CARD_FIELDS.radius,
+  padding: CARD_FIELDS.padding,
+  gradient: CARD_FIELDS.gradient,
+  shadow: "shadow",
+});
+
+// `Pressable` hands its style `{ pressed }`, so a callable must stay callable.
+function composeStyle(base, extra) {
+  if (extra === undefined || extra === null) return base;
+  if (typeof extra === "function") return (state) => [...base, extra(state)];
+  return [...base, extra];
+}
+
+// The theme's `card` scope, as the `card*` fields a host would have folded in.
+function themedFields(theme) {
+  const scope = normaliseThemeComponents(theme.components).card || {};
+  const out = {};
+  for (const [token, field] of Object.entries(CARD_FIELDS)) {
+    if (scope[token] !== undefined) out[field] = scope[token];
+  }
+  if (scope.shadow !== undefined) out.shadow = scope.shadow;
+  return out;
+}
+
+function themedBase(theme) {
+  const { colors, radii, spacing } = theme;
+  return {
+    backgroundColor: colors.surface,
+    borderColor: colors.border,
+    borderWidth: 1,
+    borderRadius: radii.md,
+    padding: spacing.md,
+  };
+}
+
+/**
+ * Bind the shared card to one platform's primitives.
+ *
+ * @param {{View: any, Gradient: any}} rn
+ */
+export function makeCard(rn) {
+  const { View, Gradient } = rn;
+
+  /**
+   * @param {object} [props.style] — `card*` fields, `shadow`, `margin`
+   *   (a widget's per-instance style, theme tokens already folded in).
+   * @param {object|Array} [props.baseStyle] — the caller's own base style. A
+   *   card given none starts from the theme's surface and `card` scope.
+   * @param {React.ElementType} [props.as] — container; anything but `View`
+   *   renders INSIDE the gradient, never as it. Other props land on it.
+   * @param {boolean} [props.fillInGradient] — the inner container stretches to
+   *   the gradient instead of shrink-wrapping (a pressable, not a scroller).
+   * @param {object|Array|Function} [props.containerStyle] — style for the
+   *   element receiving the other props, so a Pressable's feedback lands.
+   * @param {boolean} [props.withoutMargin] — leave the margin off this surface
+   *   for a widget that rides it on an outer root.
+   */
+  function Card(props) {
+    const {
+      style,
+      baseStyle,
+      as: Container = View,
+      fillInGradient = false,
+      containerStyle,
+      withoutMargin = false,
+      children,
+      ...others
+    } = props;
+    const rest = {};
+    for (const [key, value] of Object.entries(others)) {
+      if (!(key in PROP_FIELDS)) rest[key] = value;
+    }
+    const theme = useHostTheme() || DEFAULT_THEME_TOKENS;
+
+    const explicit = {};
+    for (const [prop, field] of Object.entries(PROP_FIELDS)) {
+      if (props[prop] !== undefined && props[prop] !== null) explicit[field] = props[prop];
+    }
+    // A built-in brings its own base and receives the theme through `style`;
+    // anything else starts from the theme, so it matches without plumbing.
+    const standalone = baseStyle === undefined;
+    const fields = {
+      ...(standalone ? themedFields(theme) : null),
+      ...style,
+      ...explicit,
+    };
+    const base = standalone ? themedBase(theme) : baseStyle;
+
+    const overlay = withoutMargin ? cardSurfaceStyle(fields) : cardOverlay(fields);
+    const gradient = cardGradientProps(fields);
+
+    if (!gradient) {
+      return React.createElement(
+        Container,
+        { style: composeStyle([base, overlay], containerStyle), ...rest },
+        children,
+      );
+    }
+
+    // The gradient IS the background; a flat fill on top would hide it.
+    const paint = { ...overlay };
+    delete paint.backgroundColor;
+
+    if (Container === View) {
+      return React.createElement(
+        Gradient,
+        {
+          colors: gradient.colors,
+          angle: gradient.angle,
+          style: composeStyle([base, paint], containerStyle),
+          ...rest,
+        },
+        children,
+      );
+    }
+
+    // A scroller cannot BE a Gradient, so the wrapper takes the layout and
+    // paint; re-applying the base inside would double every padding.
+    return React.createElement(
+      Gradient,
+      {
+        colors: gradient.colors,
+        angle: gradient.angle,
+        style: [base, paint, CLIP_TO_RADIUS],
+      },
+      React.createElement(
+        Container,
+        {
+          style: composeStyle(
+            [fillInGradient ? FILL_IN_GRADIENT : SCROLLER_IN_GRADIENT],
+            containerStyle,
+          ),
+          ...rest,
+        },
+        children,
+      ),
+    );
+  }
+
+  Card.displayName = "Card";
+  return Card;
+}

package/dist/card.js

@@ -0,0 +1,8 @@
+// `<Card>` (web). Binds ./card-view.js to react-native-web and the CSS
+// gradient; see ./primitives.js for why not the bare specifier.
+
+import * as ReactNative from "react-native-web";
+import { Gradient } from "./gradient.js";
+import { makeCard } from "./card-view.js";
+
+export const Card = makeCard({ View: ReactNative.View, Gradient });

package/dist/card.native.js

@@ -0,0 +1,8 @@
+// `<Card>` (native). Binds ./card-view.js to React Native and the
+// expo-linear-gradient `<Gradient>`; only the imports differ from ./card.js.
+
+import { View } from "react-native";
+import { Gradient } from "./gradient.native.js";
+import { makeCard } from "./card-view.js";
+
+export const Card = makeCard({ View, Gradient });