@colixsystems/widget-sdk 0.163.0 → 0.164.0

package/README.md

@@ -73,7 +73,24 @@ See the design reference for the full architecture: [`docs/architecture/widget-m
 
 ## Status
 
-`v0.163.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)
 
@@ -1801,6 +1818,7 @@ 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 });

package/dist/contract.cjs

@@ -416,6 +416,7 @@ const MUTED_INPUT_FIELDS = Object.freeze({
   textColor: "inputTextColor",
   borderColor: "inputBorderColor",
   radius: "inputRadius",
+  height: "inputHeight",
 });
 
 // The Form widgets' choice-field option list -- the closest thing this
@@ -576,6 +577,8 @@ const THEME_COMPONENTS = Object.freeze({
       textColor: Object.freeze({ type: "color", uiDefault: "colors.onSurfaceMuted" }),
       borderColor: Object.freeze({ type: "color", uiDefault: "colors.border" }),
       radius: Object.freeze({ type: "size", min: 0, max: 48, uiDefault: "radii.sm" }),
+      // The field's minimum height; `<TextField>` reads it directly too.
+      height: Object.freeze({ type: "size", min: 32, max: 72 }),
     }),
     targets: Object.freeze({
       "appstudio.form-input": MUTED_INPUT_FIELDS,
@@ -2260,6 +2263,27 @@ const PRIMITIVES = [
     rnComponent: null,
     docsUrl: null,
   },
+  {
+    name: "Card",
+    description:
+      'Themed card surface. `<Card>…</Card>` — THE way to draw a card, panel or tile: with no props it takes the app\'s card look (Theme Settings > Cards: background, border, corner radius, padding, shadow, gradient) so it matches every built-in card. Override one card with `background`, `borderColor`, `radius`, `padding` (a number or `{ top, right, bottom, left }`), `shadow` ("none" | "sm" | "md" | "lg") or `gradient` (`{ from, to, angle }`), or pass `style={props.style}` when your widget declares the `cardBackground` / `cardBorderColor` / `cardRadius` / `cardPadding` / `cardGradient` / `shadow` / `margin` style fields, so an author can restyle it. A gradient paints on both hosts. `as` renders the card as another container (e.g. `Pressable`, `ScrollView`) and every other prop lands on it. Never hand-roll a card from `View` + border + radius.',
+    rnComponent: null,
+    docsUrl: null,
+  },
+  {
+    name: "Button",
+    description:
+      'Themed button. `<Button title="Save" onPress={save} />` — THE way to draw a button: its fill, label colour, border, corner radius, padding, weight, shadow and gradient come from the app\'s button look (Theme Settings > Buttons, and Destructive / Focus ring for the danger variant and emphasis border), so it matches the built-in Button widget. Props: `title`, `onPress` (omit it for a purely visual button inside something else that is pressable), `variant` ("primary" default | "secondary" | "outlined" | "danger"), `icon` (a lucide name) with `iconPosition` ("leading" | "trailing"), `disabled`, `accessibilityLabel`, `testID`, `style` (extra container style, e.g. `alignSelf`) and `labelStyle`. Pass `fields` — `{ background, textColor, borderColor, borderWidth, paddingX, paddingY, radius, fontWeight, fontSize, shadow, gradient }` — to override one button, e.g. from style fields your widget declares. Never hand-roll a button from `Pressable` + background + radius.',
+    rnComponent: null,
+    docsUrl: null,
+  },
+  {
+    name: "TextField",
+    description:
+      'Themed text-entry field. `<TextField value={name} onChangeText={setName} placeholder="Your name" accessibilityLabel="Name" />` — every `TextInput` prop works, and its background, text colour, border, corner radius and height come from the app\'s input look (Theme Settings > Muted), so a widget\'s fields match the built-in forms. `multiline` grows the field to a ceiling and then scrolls inside it. Override one field with `background`, `textColor`, `borderColor`, `radius` or `height`; `style` is merged last. Use it instead of styling a bare `TextInput`.',
+    rnComponent: null,
+    docsUrl: null,
+  },
 ];
 
 const CATEGORIES = [
@@ -4454,7 +4478,12 @@ const CONTRACT = deepFreeze({
   //    used by `tabs.style`. The page Tabs container renders through `Tabs` on
   //    both hosts. Additive: an unthemed strip is the segmented control the
   //    export always drew.
-  version: "1.126.0",
+  // 1.127.0: additive — the `Card`, `Button` and `TextField` primitives,
+  //    lifted from the built-in widgets' shared card surface, button surface
+  //    and form field so every widget draws them from one implementation, plus
+  //    a `height` token on the `muted` scope. Additive: the built-ins render
+  //    exactly as before.
+  version: "1.127.0",
   sharedTranslationKeys: SHARED_TRANSLATION_KEYS,
   hooks: HOOKS,
   primitives: PRIMITIVES,

package/dist/contract.js

@@ -416,6 +416,7 @@ const MUTED_INPUT_FIELDS = Object.freeze({
   textColor: "inputTextColor",
   borderColor: "inputBorderColor",
   radius: "inputRadius",
+  height: "inputHeight",
 });
 
 // The Form widgets' choice-field option list -- the closest thing this
@@ -576,6 +577,8 @@ const THEME_COMPONENTS = Object.freeze({
       textColor: Object.freeze({ type: "color", uiDefault: "colors.onSurfaceMuted" }),
       borderColor: Object.freeze({ type: "color", uiDefault: "colors.border" }),
       radius: Object.freeze({ type: "size", min: 0, max: 48, uiDefault: "radii.sm" }),
+      // The field's minimum height; `<TextField>` reads it directly too.
+      height: Object.freeze({ type: "size", min: 32, max: 72 }),
     }),
     targets: Object.freeze({
       "appstudio.form-input": MUTED_INPUT_FIELDS,
@@ -2260,6 +2263,27 @@ const PRIMITIVES = [
     rnComponent: null,
     docsUrl: null,
   },
+  {
+    name: "Card",
+    description:
+      'Themed card surface. `<Card>…</Card>` — THE way to draw a card, panel or tile: with no props it takes the app\'s card look (Theme Settings > Cards: background, border, corner radius, padding, shadow, gradient) so it matches every built-in card. Override one card with `background`, `borderColor`, `radius`, `padding` (a number or `{ top, right, bottom, left }`), `shadow` ("none" | "sm" | "md" | "lg") or `gradient` (`{ from, to, angle }`), or pass `style={props.style}` when your widget declares the `cardBackground` / `cardBorderColor` / `cardRadius` / `cardPadding` / `cardGradient` / `shadow` / `margin` style fields, so an author can restyle it. A gradient paints on both hosts. `as` renders the card as another container (e.g. `Pressable`, `ScrollView`) and every other prop lands on it. Never hand-roll a card from `View` + border + radius.',
+    rnComponent: null,
+    docsUrl: null,
+  },
+  {
+    name: "Button",
+    description:
+      'Themed button. `<Button title="Save" onPress={save} />` — THE way to draw a button: its fill, label colour, border, corner radius, padding, weight, shadow and gradient come from the app\'s button look (Theme Settings > Buttons, and Destructive / Focus ring for the danger variant and emphasis border), so it matches the built-in Button widget. Props: `title`, `onPress` (omit it for a purely visual button inside something else that is pressable), `variant` ("primary" default | "secondary" | "outlined" | "danger"), `icon` (a lucide name) with `iconPosition` ("leading" | "trailing"), `disabled`, `accessibilityLabel`, `testID`, `style` (extra container style, e.g. `alignSelf`) and `labelStyle`. Pass `fields` — `{ background, textColor, borderColor, borderWidth, paddingX, paddingY, radius, fontWeight, fontSize, shadow, gradient }` — to override one button, e.g. from style fields your widget declares. Never hand-roll a button from `Pressable` + background + radius.',
+    rnComponent: null,
+    docsUrl: null,
+  },
+  {
+    name: "TextField",
+    description:
+      'Themed text-entry field. `<TextField value={name} onChangeText={setName} placeholder="Your name" accessibilityLabel="Name" />` — every `TextInput` prop works, and its background, text colour, border, corner radius and height come from the app\'s input look (Theme Settings > Muted), so a widget\'s fields match the built-in forms. `multiline` grows the field to a ceiling and then scrolls inside it. Override one field with `background`, `textColor`, `borderColor`, `radius` or `height`; `style` is merged last. Use it instead of styling a bare `TextInput`.',
+    rnComponent: null,
+    docsUrl: null,
+  },
 ];
 
 const CATEGORIES = [
@@ -4450,7 +4474,12 @@ const CONTRACT = deepFreeze({
   //    used by `tabs.style`. The page Tabs container renders through `Tabs` on
   //    both hosts. Additive: an unthemed strip is the segmented control the
   //    export always drew.
-  version: "1.126.0",
+  // 1.127.0: additive — the `Card`, `Button` and `TextField` primitives,
+  //    lifted from the built-in widgets' shared card surface, button surface
+  //    and form field so every widget draws them from one implementation, plus
+  //    a `height` token on the `muted` scope. Additive: the built-ins render
+  //    exactly as before.
+  version: "1.127.0",
   sharedTranslationKeys: SHARED_TRANSLATION_KEYS,
   hooks: HOOKS,
   primitives: PRIMITIVES,

package/dist/icon.js

@@ -18,10 +18,14 @@ import React from "react";
 import * as LucideIcons from "lucide-react-native";
 import { normalizeLucideIconName } from "./lucideIconName.js";
 
-export function Icon({ name, size, color }) {
+/** The lucide component a name resolves to, or null for an unknown name. */
+export function lucideGlyph(name) {
   const resolved = normalizeLucideIconName(name);
-  const candidate = resolved ? LucideIcons[resolved] : null;
-  const Component = candidate || LucideIcons.Square;
+  return (resolved && LucideIcons[resolved]) || null;
+}
+
+export function Icon({ name, size, color }) {
+  const Component = lucideGlyph(name) || LucideIcons.Square;
   const pixelSize = Number.isFinite(size) && size > 0 ? size : 24;
   return React.createElement(Component, {
     size: pixelSize,

package/dist/index.d.ts

@@ -2615,6 +2615,89 @@ export const EmptyState: (props: {
   children?: ReactNode;
 }) => any;
 
+/**
+ * Themed card surface. With no props it takes the app's card look (Theme
+ * Settings > Cards). Props override one card; `style` takes the `card*` style
+ * fields a widget declares; `as` renders it as another container.
+ *
+ * @example
+ *   <Card><Text>…</Text></Card>
+ *   <Card as={Pressable} onPress={open} radius={12} shadow="md">…</Card>
+ */
+export const Card: (props: {
+  background?: string;
+  borderColor?: string;
+  radius?: number | { topLeft?: number; topRight?: number; bottomRight?: number; bottomLeft?: number };
+  padding?: number | { top?: number; right?: number; bottom?: number; left?: number };
+  shadow?: "none" | "sm" | "md" | "lg";
+  gradient?: { from: string; to: string; angle?: number };
+  /** `card*` style fields, `shadow`, `margin` — a widget's per-instance style. */
+  style?: Record<string, any>;
+  /** The caller's own base style; a card given none starts from the theme. */
+  baseStyle?: any;
+  as?: any;
+  fillInGradient?: boolean;
+  containerStyle?: any;
+  withoutMargin?: boolean;
+  children?: ReactNode;
+  [prop: string]: any;
+}) => any;
+
+export type ButtonVariant = "primary" | "secondary" | "outlined" | "danger";
+export const BUTTON_VARIANTS: readonly ButtonVariant[];
+
+/**
+ * Themed button (Theme Settings > Buttons, Destructive, Focus ring). Omit
+ * `onPress` for a purely visual button inside something pressable.
+ *
+ * @example
+ *   <Button title="Save" onPress={save} />
+ *   <Button title="Delete" variant="danger" icon="trash-2" onPress={remove} />
+ */
+export const Button: (props: {
+  title: ReactNode;
+  variant?: ButtonVariant;
+  icon?: string;
+  iconPosition?: "leading" | "trailing";
+  onPress?: () => void;
+  disabled?: boolean;
+  /** Per-button surface fields; unset ones follow the theme. */
+  fields?: {
+    background?: string;
+    textColor?: string;
+    borderColor?: string;
+    borderWidth?: number;
+    paddingX?: number;
+    paddingY?: number;
+    radius?: number;
+    fontWeight?: string;
+    fontSize?: number;
+    shadow?: "none" | "sm" | "md" | "lg";
+    gradient?: { from: string; to: string; angle?: number };
+  };
+  style?: any;
+  labelStyle?: any;
+  accessibilityLabel?: string;
+  testID?: string;
+}) => any;
+
+/**
+ * Themed text-entry field (Theme Settings > Muted). Every TextInput prop works.
+ *
+ * @example
+ *   <TextField value={name} onChangeText={setName} placeholder="Your name" accessibilityLabel="Name" />
+ */
+export const TextField: (props: {
+  background?: string;
+  textColor?: string;
+  borderColor?: string;
+  radius?: number;
+  height?: number;
+  multiline?: boolean;
+  style?: any;
+  [prop: string]: any;
+}) => any;
+
 export type TabStyle = "segmented" | "pill" | "underline";
 
 /**

package/dist/index.js

@@ -191,6 +191,34 @@ export {
 export { insertAtCaret, pushRecentEmoji } from "./emoji-picker-tokens.js";
 // Themed list building blocks; rows follow the theme's `list` scope.
 export { List, ListRow, EmptyState } from "./list.js";
+// The one card surface: the theme's `card` scope, a gradient fill, margin.
+export { Card } from "./card.js";
+export {
+  SHADOW_PRESETS,
+  shadowStyle,
+  SPACING_MAX_PX,
+  CARD_RADIUS_MAX_PX,
+  FRAME_RADIUS_MAX_PX,
+  marginStyle,
+  spacingOverlay,
+  cornerRadiusOverlay,
+  cardSurfaceStyle,
+  cardOverlay,
+  gradientProps,
+  cardGradientProps,
+} from "./card-style.js";
+// The themed button; follows the theme's button, destructive and ring scopes.
+export { Button, BUTTON_VARIANTS } from "./button.js";
+export {
+  BUTTON_PADDING_MAX,
+  BUTTON_BORDER_WIDTH_MAX,
+  SELF_ALIGNMENTS,
+  buttonSurfaceOverlay,
+  buttonSurfaceTextOverlay,
+  selfAlignStyle,
+} from "./button-style.js";
+// The themed text-entry field; follows the theme's `muted` scope.
+export { TextField } from "./text-field.js";
 // A themed tab strip; follows the theme's `tabs` scope.
 export { Tabs } from "./tabs.js";
 // The semantic text tiers, shared with the built-in widgets.

package/dist/index.native.js

@@ -184,6 +184,34 @@ export {
 export { insertAtCaret, pushRecentEmoji } from "./emoji-picker-tokens.js";
 // Themed list building blocks; rows follow the theme's `list` scope.
 export { List, ListRow, EmptyState } from "./list.native.js";
+// The one card surface: the theme's `card` scope, a gradient fill, margin.
+export { Card } from "./card.native.js";
+export {
+  SHADOW_PRESETS,
+  shadowStyle,
+  SPACING_MAX_PX,
+  CARD_RADIUS_MAX_PX,
+  FRAME_RADIUS_MAX_PX,
+  marginStyle,
+  spacingOverlay,
+  cornerRadiusOverlay,
+  cardSurfaceStyle,
+  cardOverlay,
+  gradientProps,
+  cardGradientProps,
+} from "./card-style.js";
+// The themed button; follows the theme's button, destructive and ring scopes.
+export { Button, BUTTON_VARIANTS } from "./button.native.js";
+export {
+  BUTTON_PADDING_MAX,
+  BUTTON_BORDER_WIDTH_MAX,
+  SELF_ALIGNMENTS,
+  buttonSurfaceOverlay,
+  buttonSurfaceTextOverlay,
+  selfAlignStyle,
+} from "./button-style.js";
+// The themed text-entry field; follows the theme's `muted` scope.
+export { TextField } from "./text-field.native.js";
 // A themed tab strip; follows the theme's `tabs` scope.
 export { Tabs } from "./tabs.native.js";
 // The semantic text tiers, shared with the built-in widgets.

package/dist/text-field-tokens.js

@@ -0,0 +1,54 @@
+// The values `<TextField>` paints with, resolved from the theme's `muted`
+// component scope — the text-entry surface the built-in forms already theme.
+// Platform-free, so both hosts draw one field from the same numbers.
+
+import { DEFAULT_THEME_TOKENS } from "./_theme-tokens.js";
+
+// A field below 44px misses the touch-target floor on both platforms.
+export const TEXT_FIELD_MIN_HEIGHT = 44;
+
+// Per-field overrides, named as the `muted` scope's tokens are.
+export const TEXT_FIELD_TOKEN_NAMES = Object.freeze([
+  "background",
+  "textColor",
+  "borderColor",
+  "radius",
+  "height",
+]);
+
+function pick(overrides, scope, name) {
+  const own = overrides && overrides[name];
+  if (own !== undefined && own !== null && own !== "") return own;
+  const themed = scope && scope[name];
+  if (themed !== undefined && themed !== null && themed !== "") return themed;
+  return undefined;
+}
+
+/**
+ * Resolve one text field: explicit override, then the theme's `muted` scope,
+ * then the theme tokens. Unthemed, it is the field the built-in forms drew.
+ *
+ * @param {object} theme — the resolved workspace theme (`useTheme()` shape).
+ * @param {object} [overrides] — per-field values keyed by TEXT_FIELD_TOKEN_NAMES.
+ */
+export function resolveTextFieldTokens(theme, overrides) {
+  const base = theme && typeof theme === "object" ? theme : DEFAULT_THEME_TOKENS;
+  const colors = base.colors || DEFAULT_THEME_TOKENS.colors;
+  const radii = base.radii || DEFAULT_THEME_TOKENS.radii;
+  const spacing = base.spacing || DEFAULT_THEME_TOKENS.spacing;
+  const typography = base.typography || DEFAULT_THEME_TOKENS.typography;
+  const scope = base.components && base.components.muted;
+  return {
+    background: pick(overrides, scope, "background") ?? colors.surfaceMuted,
+    textColor: pick(overrides, scope, "textColor") ?? colors.onSurface,
+    borderColor: pick(overrides, scope, "borderColor") ?? colors.border,
+    radius: pick(overrides, scope, "radius") ?? radii.sm,
+    height: pick(overrides, scope, "height") ?? TEXT_FIELD_MIN_HEIGHT,
+    paddingHorizontal: spacing.md,
+    paddingVertical: spacing.sm,
+    fontFamily: typography.fontFamily,
+    fontSize: typography.sizes.md,
+    placeholderColor: colors.onSurfaceMuted,
+    focusColor: colors.primary,
+  };
+}

package/dist/text-field-view.js

@@ -0,0 +1,79 @@
+// The ONE text-entry field, behind the `<TextField>` SDK primitive and the
+// built-in form fields. The bindings differ only in where `TextInput` comes
+// from, so the hosts cannot drift.
+
+import React from "react";
+import { useHostTheme } from "./hooks.js";
+import { DEFAULT_THEME_TOKENS } from "./_theme-tokens.js";
+import {
+  resolveTextFieldTokens,
+  TEXT_FIELD_TOKEN_NAMES,
+} from "./text-field-tokens.js";
+
+// A paragraph field grows to a ceiling, then scrolls inside itself.
+const MULTILINE = { minHeight: 88, maxHeight: 220, textAlignVertical: "top" };
+
+/**
+ * Bind the shared field to one platform's primitives.
+ *
+ * @param {{TextInput: any}} rn
+ */
+export function makeTextField(rn) {
+  const { TextInput } = rn;
+
+  const TextField = React.forwardRef(function TextField(props, ref) {
+    const {
+      style,
+      multiline = false,
+      placeholderTextColor,
+      onFocus,
+      onBlur,
+      ...others
+    } = props;
+    const theme = useHostTheme() || DEFAULT_THEME_TOKENS;
+    // Native draws no focus ring, so the border itself shows focus.
+    const [focused, setFocused] = React.useState(false);
+    const overrides = {};
+    const rest = {};
+    for (const [key, value] of Object.entries(others)) {
+      if (TEXT_FIELD_TOKEN_NAMES.includes(key)) overrides[key] = value;
+      else rest[key] = value;
+    }
+    const t = resolveTextFieldTokens(theme, overrides);
+    return React.createElement(TextInput, {
+      ref,
+      multiline,
+      placeholderTextColor: placeholderTextColor || t.placeholderColor,
+      style: [
+        {
+          borderWidth: 1,
+          borderColor: t.borderColor,
+          borderRadius: t.radius,
+          paddingHorizontal: t.paddingHorizontal,
+          paddingVertical: t.paddingVertical,
+          minHeight: t.height,
+          backgroundColor: t.background,
+          color: t.textColor,
+          fontFamily: t.fontFamily,
+          fontSize: t.fontSize,
+        },
+        focused ? { borderColor: t.focusColor } : null,
+        style,
+        // After the caller's style: a paragraph field keeps its 88px floor.
+        multiline ? MULTILINE : null,
+      ],
+      onFocus: (e) => {
+        setFocused(true);
+        if (typeof onFocus === "function") onFocus(e);
+      },
+      onBlur: (e) => {
+        setFocused(false);
+        if (typeof onBlur === "function") onBlur(e);
+      },
+      ...rest,
+    });
+  });
+
+  TextField.displayName = "TextField";
+  return TextField;
+}

package/dist/text-field.js

@@ -0,0 +1,7 @@
+// `<TextField>` (web). Binds ./text-field-view.js to react-native-web; see
+// ./primitives.js for why not the bare specifier.
+
+import * as ReactNative from "react-native-web";
+import { makeTextField } from "./text-field-view.js";
+
+export const TextField = makeTextField(ReactNative);

package/dist/text-field.native.js

@@ -0,0 +1,7 @@
+// `<TextField>` (native). Binds ./text-field-view.js to React Native's own
+// `TextInput`; only the import differs from ./text-field.js.
+
+import { TextInput } from "react-native";
+import { makeTextField } from "./text-field-view.js";
+
+export const TextField = makeTextField({ TextInput });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@colixsystems/widget-sdk",
-  "version": "0.163.0",
+  "version": "0.164.0",
   "description": "Common widget interface for AppStudio. Implements WidgetManifest, WidgetContext, property schema, and helper hooks.",
   "homepage": "https://github.com/Colix-AB/AppStudio",
   "type": "module",