@colixsystems/widget-sdk 0.245.0 → 0.246.0

package/README.md

@@ -84,7 +84,42 @@ See the design reference for the full architecture: [`docs/architecture/widget-m
 
 ## Status
 
-`v0.245.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.246.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.246.0 (contract 1.200.0)
+
+**The standard components are the default, not a limit.** Every component description now says what it is for and when a request needs something it cannot draw — a colour-swatch picker, a tri-state tick box, a confirmation that asks you to type a name — in which case you build that one piece yourself from theme tokens, with the right accessibility role and state. Correctness rules are unchanged: screen-level surfaces still go through `<Overlay>`, irreversible actions are still confirmed, and formatted text is still markdown.
+
+**Menus, popovers and tooltips anchored to their trigger.** `<Menu>` opens a list of actions from one control, `<Popover>` shows your own content beside it, and `<Tooltip>` names an icon-only button. They open beside the trigger on a wide screen, flip at the screen edge, become a bottom sheet on a phone, and close on the backdrop, Escape and Android back; no card or list clips them. A picked item's `onPress` runs once the menu has left the screen, so an item can open a `<ConfirmDialog>` that returns focus to the menu's button when it closes. On the web an anchored panel closes when the page scrolls beneath it. Menus are keyboard-navigable `menu`/`menuitem` lists; tooltips show on hover and focus on the web and on long press on touch. They follow Design > Components > Dropdown menus (`popover`), which gains `radius` and `shadow`; an unthemed `<Select>` is unchanged.
+
+```jsx
+<Menu trigger={<IconButton icon="more-horizontal" accessibilityLabel="More actions" />}
+  items={[{ label: "Edit", icon: "pencil", onPress: edit },
+          canDelete && { label: "Delete", icon: "trash-2", danger: true, onPress: askDelete }]} />
+```
+
+**Quiet buttons, icon buttons and busy states.** `<Button>` gains `variant="ghost"` and `variant="link"`, a `size` of `sm` (36px), `md` (44px, the default) or `lg` (52px), `busy` (a `<Spinner>` over the kept label; it cannot be pressed again) and `selected` for a toggle. `<IconButton icon accessibilityLabel>` is the same themed button as an icon-only square of at least 36px on both hosts. Both pass `onLongPress`, `aria-haspopup`, `aria-expanded` and their ref through, so they work as a `<Menu>`/`<Popover>` trigger and inside a `<Tooltip>`. Existing buttons render exactly as before.
+
+```jsx
+<Button title="Save" onPress={save} busy={saving} />
+<Button title="Load more" variant="ghost" onPress={next} />
+<IconButton icon="trash-2" accessibilityLabel="Delete order" color={theme.colors.danger} onPress={remove} />
+```
+
+**One way to show a stored picture: `<FileImage>` and `<Avatar fileId>`.** Give `<FileImage>` a FILE column's value and it resolves the file with `useFilestoreFile`, draws a `<Skeleton>` in the app's Loading look while it loads, and shows an image glyph (or a blank box) instead of a broken image. Signed URLs expire, so a failed load refetches the file once before giving up. Pass `uri` for a URL you already hold. `<Avatar fileId>` does the same for a person's photo and keeps the initials if it cannot load; `url` callers are unchanged.
+
+```jsx
+<FileImage fileId={product.Photo} variant="card" aspectRatio={4 / 3} accessibilityLabel={product.Name} />
+<Avatar name={member.Name} fileId={member.Photo} size="sm" />
+```
+
+**`<RadioGroup>`: one choice from a short visible list.** It takes the form controls' `label`, `helper`, `error` and `disabled`, and options `{ value, label, description, icon, disabled }`. `variant="list"` (default) and `"card"` follow Design > Components > Inputs; `"segmented"` draws the Tabs scope's segmented strip. On the web the group is one tab stop, the arrows move the choice past disabled options and Space picks; on native a tap picks. A long list stays a `Select`.
+
+```jsx
+<RadioGroup variant="card" label="Delivery" value={speed} onValueChange={setSpeed}
+  options={[{ value: "standard", label: "Standard", description: "3-5 working days" },
+            { value: "express", label: "Express", description: "Next working day" }]} />
+```
 
 ### What's new in 0.245.0 (contract 1.199.0)
 
@@ -3037,6 +3072,7 @@ import { defineWidget, validateManifest, useDatastoreQuery, Text, View } from "@
 - `Accordion`, `AccordionItem` — themed collapsible sections. `<Accordion><AccordionItem title subtitle trailing>…</AccordionItem></Accordion>` draws its surface from the theme's `card` scope and its headers and dividers from the `list` scope; one section open at a time, or `multiple`. Never hand-roll a collapsible from `Pressable` + a chevron.
 - `Spinner`, `Skeleton` — the themed loading states. `<Spinner size label>` for a pending action; `<Skeleton shape="text" | "block" | "circle" | "listRow">` (or a group of bones) for content whose layout you know. The spinner wears `colors.loader`, the skeleton follows the theme's `loading` scope; both stop under reduced motion and mark one busy region. Never use `ActivityIndicator` or hand-build placeholder bars.
 - `Checkbox`, `Switch`, `Select`, `SearchField` — the themed tick box, on/off toggle, picker and search box. Like `TextField` they follow the theme's `muted` scope, Design > Components > Inputs (and `popover`, Dropdown menus, for the Select's option sheet; `SearchField` also reads `search`, Search fields, for its glyph position, corner radius, background, border colour and height, each falling back to Inputs) and take `label`, `helper`, `error` and `disabled`. `Select` opens its options at screen level; with `multiple` it takes `values` / `onValuesChange`, ticks options in the same sheet and commits them on Done. Never hand-roll one from `Pressable` and `View`.
+- `RadioGroup` — the themed pick-ONE of a short list that stays on screen. `<RadioGroup options value onValueChange variant>` with `variant` `"list"` (default) or `"card"`, both following `muted` (Design > Components > Inputs), or `"segmented"`, the `tabs` scope's segmented strip; options are `{ value, label, description, icon, disabled, testID }`, and it takes `label`, `helper`, `error` and `disabled`. Radio role and checked state on both hosts; on the web one tab stop, arrows move the choice. Use it by default for two to about six visible options; a long list is a `Select`, and a choice it cannot draw (a picture or a swatch per option) is yours to build, with the radio role.
 - `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.
 - `Chip`, `ChipGroup` — the themed filter chip, tag or pill. `<Chip label selected onPress onRemove disabled>` follows the theme's `chip` scope; `<ChipGroup>` spaces and wraps its chips and, with `selection="single"`, announces them as one choice. Never hand-roll a chip from `Pressable` + a pill radius.
 - `textRoleStyle(role, typography, colors)`, `TEXT_ROLES` — the style of a semantic text tier, shared with the built-in widgets.

package/dist/button-tokens.js

@@ -0,0 +1,154 @@
+// The variants, sizes and quiet looks behind `<Button>` and `<IconButton>`.
+// Platform-free and React-free, so both hosts resolve one look and tests can
+// pin it.
+
+import { DEFAULT_THEME_TOKENS } from "./_theme-tokens.js";
+
+export const BUTTON_VARIANTS = Object.freeze([
+  "primary",
+  "secondary",
+  "outlined",
+  "danger",
+  "ghost",
+  "link",
+]);
+export const BUTTON_SIZES = Object.freeze(["sm", "md", "lg"]);
+export const DEFAULT_BUTTON_SIZE = "md";
+
+// A quiet button has no chrome of its own, so the theme's fill, border,
+// shadow and label colour (drawn for a filled button) never reach it.
+const QUIET_VARIANTS = Object.freeze(["ghost", "link"]);
+const THEME_PAINT_FIELDS = Object.freeze([
+  "background",
+  "gradient",
+  "textColor",
+  "borderColor",
+  "borderWidth",
+  "shadow",
+  "ringColor",
+  "ringWidth",
+  "dangerBackground",
+  "dangerBorderColor",
+  "dangerTextColor",
+]);
+
+// The square an `<IconButton>` draws, and the glyph inside it.
+export const ICON_BUTTON_SIZES = Object.freeze({
+  sm: Object.freeze({ box: 36, glyph: 16 }),
+  md: Object.freeze({ box: 44, glyph: 20 }),
+  lg: Object.freeze({ box: 52, glyph: 24 }),
+});
+// The touch target a native platform recommends; hitSlop reaches it on a
+// device, while the web only ever has the box itself.
+const NATIVE_TOUCH_TARGET = 44;
+
+export function resolveButtonVariant(variant) {
+  return BUTTON_VARIANTS.includes(variant) ? variant : "primary";
+}
+
+export function resolveButtonSize(size) {
+  return BUTTON_SIZES.includes(size) ? size : DEFAULT_BUTTON_SIZE;
+}
+
+export function isQuietLook(variant, selected) {
+  return selected === true || QUIET_VARIANTS.includes(variant);
+}
+
+/**
+ * A variant's own paint before the section, the theme or the caller move it.
+ * `selected` is a toggle's on state: the accent's quiet tint, whatever the
+ * variant.
+ */
+export function variantPaint(variant, colors, selected = false) {
+  if (selected) {
+    return {
+      container: { backgroundColor: colors.primarySoft || DEFAULT_THEME_TOKENS.colors.primarySoft },
+      ink: colors.onPrimarySoft || DEFAULT_THEME_TOKENS.colors.onPrimarySoft,
+    };
+  }
+  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,
+    };
+  }
+  if (QUIET_VARIANTS.includes(variant)) {
+    return { container: { backgroundColor: "transparent" }, ink: colors.primary };
+  }
+  return { container: { backgroundColor: colors.primary }, ink: colors.onPrimary };
+}
+
+/**
+ * The theme-folded fields a quiet look keeps: its shape, weight, size and
+ * insets, but none of the paint the app's button look set for a filled
+ * button. A field the caller passed in `own` is always kept.
+ */
+export function quietButtonFields(folded, own) {
+  const caller = own || {};
+  const kept = { ...folded };
+  for (const key of THEME_PAINT_FIELDS) {
+    if (caller[key] === undefined) delete kept[key];
+  }
+  return kept;
+}
+
+/** The insets, minimum size and label size of a button at `size`. */
+export function buttonSizeFrame(size, variant, theme) {
+  const { spacing, typography } = theme;
+  const frames = {
+    sm: {
+      frame: { paddingHorizontal: spacing.sm, paddingVertical: spacing.xs, minHeight: 36, minWidth: 48 },
+      fontSize: typography.sizes.sm,
+    },
+    md: {
+      frame: { paddingHorizontal: spacing.md, paddingVertical: spacing.sm, minHeight: 44, minWidth: 64 },
+      fontSize: typography.sizes.sm,
+    },
+    lg: {
+      frame: { paddingHorizontal: spacing.lg, paddingVertical: spacing.sm, minHeight: 52, minWidth: 80 },
+      fontSize: typography.sizes.md,
+    },
+  };
+  const { frame, fontSize } = frames[resolveButtonSize(size)];
+  // A link reads as text, so it keeps its height but drops the side insets.
+  if (variant === "link") return { frame: { ...frame, paddingHorizontal: 0, minWidth: 0 }, fontSize };
+  return { frame, fontSize };
+}
+
+/** The square box and glyph size of an `<IconButton>`. */
+export function iconButtonFrame(size) {
+  return ICON_BUTTON_SIZES[resolveButtonSize(size)];
+}
+
+/** What extends a box smaller than the native touch target up to it. */
+export function iconButtonHitSlop(box) {
+  if (box >= NATIVE_TOUCH_TARGET) return undefined;
+  const reach = (NATIVE_TOUCH_TARGET - box) / 2;
+  return { top: reach, bottom: reach, left: reach, right: reach };
+}
+
+/**
+ * The colour of a busy button's `<Spinner>`: the label's ink on a fill the
+ * button paints, else unset so the spinner wears `theme.colors.loader`.
+ */
+export function busySpinnerColor(fill, ink, gradient) {
+  const painted = Boolean(gradient) || (typeof fill === "string" && fill !== "transparent");
+  return painted ? ink : undefined;
+}
+
+/** The spinner diameter that sits inside a label of `fontSize`. */
+export function busySpinnerSize(fontSize) {
+  return fontSize > 14 ? "md" : "sm";
+}

package/dist/button-view.js

@@ -1,11 +1,12 @@
-// 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.
+// The ONE button surface, behind the `<Button>` and `<IconButton>` SDK
+// primitives and the built-in Button widget. The bindings (`button.js` /
+// `button.native.js`) differ only in their primitives and in which
+// `<Gradient>` and `<Spinner>` they pass.
 
 import React from "react";
 import { useHostTheme } from "./hooks.js";
 import { DEFAULT_THEME_TOKENS } from "./_theme-tokens.js";
-import { lucideGlyph } from "./icon.js";
+import { Icon, lucideGlyph } from "./icon.js";
 import { applyThemeComponentStyle } from "./theme-components.js";
 import { cornerRadiusOverlay, shadowStyle, gradientProps } from "./card-style.js";
 import { flattenStyle } from "./flatten-style.js";
@@ -15,41 +16,41 @@ import {
   ownedButtonPaint,
   paintOnBackdrop,
 } from "./button-style.js";
+import {
+  BUTTON_VARIANTS,
+  buttonSizeFrame,
+  busySpinnerColor,
+  busySpinnerSize,
+  iconButtonFrame,
+  iconButtonHitSlop,
+  isQuietLook,
+  quietButtonFields,
+  resolveButtonVariant,
+  variantPaint,
+} from "./button-tokens.js";
 
-export const BUTTON_VARIANTS = Object.freeze(["primary", "secondary", "outlined", "danger"]);
+export { BUTTON_VARIANTS };
 
 // 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 };
-}
+const HIDDEN = { "aria-hidden": true, importantForAccessibility: "no-hide-descendants" };
+const CENTRED_OVER = {
+  position: "absolute",
+  top: 0,
+  right: 0,
+  bottom: 0,
+  left: 0,
+  alignItems: "center",
+  justifyContent: "center",
+};
 
 // Precedence, weakest first: variant, danger scope, ring, then the fields.
-function containerLayers(variant, f, colors, owned) {
-  const paint = paintOnBackdrop(variant, variantPaint(variant, colors), colors, owned);
+function containerLayers(variant, selected, f, colors, owned) {
+  const paint = paintOnBackdrop(variant, variantPaint(variant, colors, selected), colors, owned);
   let ink = paint.ink;
   const layers = [paint.container];
-  if (variant === "danger") {
+  if (variant === "danger" && !selected) {
     if (f.dangerBackground) layers.push({ backgroundColor: f.dangerBackground });
     if (f.dangerBorderColor) layers.push({ borderWidth: 1, borderColor: f.dangerBorderColor });
     if (f.dangerTextColor) ink = f.dangerTextColor;
@@ -80,17 +81,105 @@ function wrapGlyph(View, glyph, key) {
   return React.createElement(View, { key }, glyph);
 }
 
+/** The resolved fields, paint and gradient one button draws with. */
+function useButtonLook({ variant, selected, fields, hostThemed, style, labelStyle }) {
+  const theme = useHostTheme() || DEFAULT_THEME_TOKENS;
+  const folded = hostThemed
+    ? fields || {}
+    : applyThemeComponentStyle(THEMED_AS, theme, { style: fields }).style || {};
+  const f = isQuietLook(variant, selected) ? quietButtonFields(folded, fields) : folded;
+  const owned = ownedButtonPaint(variant, f, flattenStyle(style), flattenStyle(labelStyle));
+  const { layers, ink } = containerLayers(variant, selected, f, theme.colors, owned);
+  return { theme, f, layers, ink, gradient: gradientProps(f.gradient) };
+}
+
+function fillOf(layers) {
+  return flattenStyle(layers).backgroundColor;
+}
+
+/**
+ * The state both hosts announce, as aria-* props (the web binding drops
+ * the older state object). React Native has no aria-pressed, so a toggle is
+ * aria-selected on a device.
+ */
+function pressableState({ disabled, busy, selected, expanded }, web) {
+  const toggle = typeof selected === "boolean";
+  const opens = typeof expanded === "boolean";
+  return {
+    disabled: disabled || busy,
+    "aria-disabled": disabled || busy,
+    ...(busy ? { "aria-busy": true } : null),
+    ...(toggle ? { [web ? "aria-pressed" : "aria-selected"]: selected } : null),
+    ...(opens ? { "aria-expanded": expanded } : null),
+  };
+}
+
+/**
+ * What `<Menu>`, `<Popover>` and `<Tooltip>` put on the control they wrap,
+ * so a button can open them and say whether it has.
+ */
+function triggerProps(props) {
+  const expanded = props["aria-expanded"];
+  return {
+    expanded: typeof expanded === "boolean" ? expanded : undefined,
+    pass: {
+      ...(typeof props.onLongPress === "function" ? { onLongPress: props.onLongPress } : null),
+      ...(props["aria-haspopup"] ? { "aria-haspopup": props["aria-haspopup"] } : null),
+      ...(props["aria-describedby"] ? { "aria-describedby": props["aria-describedby"] } : null),
+    },
+  };
+}
+
+function pressable(props) {
+  return typeof props.onPress === "function" || typeof props.onLongPress === "function";
+}
+
 /**
  * Bind the shared button to one platform's primitives.
  *
- * @param {{View: any, Text: any, Pressable: any, StyleSheet: any, Gradient: any}} rn
+ * @param {{View: any, Text: any, Pressable: any, StyleSheet: any, Gradient: any, Spinner: any, Platform: any}} rn
  */
 export function makeButton(rn) {
-  const { View, Text, Pressable, StyleSheet, Gradient } = rn;
+  const { View, Text, Pressable, StyleSheet, Gradient, Spinner, Platform } = rn;
+  const web = Platform.OS === "web";
+
+  function gradientFill(gradient, radius, radii) {
+    return 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(radius),
+      ],
+    });
+  }
+
+  // Over the hidden content, so a busy button keeps its size.
+  function busyMark(look, layers, fontSize) {
+    return React.createElement(
+      View,
+      { key: "busy", ...HIDDEN, style: CENTRED_OVER },
+      React.createElement(Spinner, {
+        size: busySpinnerSize(fontSize),
+        color: busySpinnerColor(fillOf(layers), look.ink, look.gradient),
+      }),
+    );
+  }
+
+  function pressedStyle(container, disabled) {
+    return ({ pressed }) => [...container, pressed && !disabled ? { opacity: 0.85 } : null];
+  }
 
   /**
    * @param {string} props.title — the label.
-   * @param {string} [props.variant] — primary | secondary | outlined | danger.
+   * @param {string} [props.variant] — primary | secondary | outlined | danger | ghost | link.
+   * @param {string} [props.size] — sm | md (default) | lg.
+   * @param {boolean} [props.busy] — a pending action: a spinner over the
+   *   kept label, and the button cannot be pressed.
+   * @param {boolean} [props.selected] — a toggle's state; omit for a plain button.
    * @param {object} [props.fields] — per-instance button-surface fields
    *   (background, textColor, borderColor, borderWidth, paddingX, paddingY,
    *   radius, fontWeight, fontSize, shadow, gradient, danger*, ring*).
@@ -100,50 +189,51 @@ export function makeButton(rn) {
    * @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.
-   * @param {object} ref — forwarded to the pressable, so a caller can focus it.
+   * @param {Function} [props.onLongPress] — a `<Tooltip>` shows on it.
+   * @param {string} [props["aria-haspopup"]] — set by a `<Menu>` or `<Popover>`.
+   * @param {boolean} [props["aria-expanded"]] — whether that surface is open.
+   * @param {object} ref — forwarded to the pressable, so a caller can focus
+   *   it and a `<Menu>` or `<Tooltip>` can place itself beside it.
    */
-  const Button = React.forwardRef(function Button({
-    title,
-    variant = "primary",
-    icon,
-    iconPosition = "leading",
-    fields,
-    onPress,
-    disabled = false,
-    style,
-    labelStyle,
-    hostThemed = false,
-    accessibilityLabel,
-    testID,
-  }, ref) {
-    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 owned = ownedButtonPaint(
-      resolvedVariant,
-      f,
-      flattenStyle(style),
-      flattenStyle(labelStyle),
-    );
-    const { layers, ink } = containerLayers(resolvedVariant, f, colors, owned);
-
+  const Button = React.forwardRef(function Button(props, ref) {
+    const {
+      title,
+      variant = "primary",
+      size,
+      icon,
+      iconPosition = "leading",
+      fields,
+      onPress,
+      disabled = false,
+      busy = false,
+      selected,
+      style,
+      labelStyle,
+      hostThemed = false,
+      accessibilityLabel,
+      testID,
+    } = props;
+    const trigger = triggerProps(props);
+    const resolvedVariant = resolveButtonVariant(variant);
+    const look = useButtonLook({
+      variant: resolvedVariant,
+      selected: selected === true,
+      fields,
+      hostThemed,
+      style,
+      labelStyle,
+    });
+    const { theme, f, layers, ink, gradient } = look;
+    const { spacing, radii, typography } = theme;
+    const sized = buttonSizeFrame(size, resolvedVariant, theme);
     const fontSize =
-      typeof f.fontSize === "number" && Number.isFinite(f.fontSize)
-        ? f.fontSize
-        : typography.sizes.sm;
+      typeof f.fontSize === "number" && Number.isFinite(f.fontSize) ? f.fontSize : sized.fontSize;
     const glyph = iconNode(icon, Math.round(fontSize), ink);
-    const gradient = gradientProps(f.gradient);
 
     const container = [
       {
-        paddingHorizontal: spacing.md,
-        paddingVertical: spacing.sm,
+        ...sized.frame,
         borderRadius: radii.sm,
-        minHeight: 44,
-        minWidth: 64,
         alignItems: "center",
         justifyContent: "center",
         alignSelf: "flex-start",
@@ -158,9 +248,11 @@ export function makeButton(rn) {
     const label = React.createElement(
       Text,
       {
+        key: "label",
         style: [
-          { fontSize: typography.sizes.sm, fontWeight: "600", fontFamily: typography.fontFamily },
+          { fontSize: sized.fontSize, fontWeight: "600", fontFamily: typography.fontFamily },
           { color: ink },
+          resolvedVariant === "link" ? { textDecorationLine: "underline" } : null,
           typeof f.fontSize === "number" ? { fontSize: f.fontSize } : null,
           labelStyle,
           buttonSurfaceTextOverlay(f),
@@ -168,44 +260,110 @@ export function makeButton(rn) {
       },
       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,
+    const content = [
       glyph && iconPosition !== "trailing" ? wrapGlyph(View, glyph, "lead") : null,
-      React.cloneElement(label, { key: "label" }),
+      label,
       glyph && iconPosition === "trailing" ? wrapGlyph(View, glyph, "trail") : null,
     ];
+    const children = [
+      gradient ? gradientFill(gradient, f.radius, radii) : null,
+      // Hidden, not removed: the button keeps its width while busy.
+      busy
+        ? React.createElement(View, { key: "content", style: { flexDirection: "row", gap: spacing.xs, opacity: 0 } }, content)
+        : content,
+      busy ? busyMark(look, layers, fontSize) : null,
+    ];
 
-    if (typeof onPress !== "function") {
-      return React.createElement(View, { style: container, testID, accessibilityLabel }, children);
+    if (!pressable(props)) {
+      return React.createElement(View, { ref, style: container, testID, accessibilityLabel }, children);
     }
     return React.createElement(
       Pressable,
       {
         ref,
         onPress,
-        disabled,
+        ...trigger.pass,
+        ...pressableState({ disabled, busy, selected, expanded: trigger.expanded }, web),
         accessibilityRole: "button",
         accessibilityLabel: accessibilityLabel || (typeof title === "string" ? title : undefined),
-        "aria-disabled": disabled,
         testID,
-        style: ({ pressed }) => [...container, pressed && !disabled ? { opacity: 0.85 } : null],
+        style: pressedStyle(container, disabled || busy),
       },
       children,
     );
   });
-
   Button.displayName = "Button";
-  return Button;
+
+  /**
+   * A square button that shows only an icon.
+   *
+   * @param {string} props.icon — a lucide name, drawn with the SDK `<Icon>`.
+   * @param {string} props.accessibilityLabel — required: the button's only name.
+   * @param {string} [props.variant] — ghost (default) | primary | secondary | outlined | danger.
+   * @param {string} [props.size] — sm (36) | md (44, default) | lg (52).
+   * @param {string} [props.color] — the glyph's colour, over the variant's.
+   * @param {Function} [props.onLongPress] — a `<Tooltip>` shows on it.
+   * @param {boolean} [props["aria-expanded"]] — set by a `<Menu>` or `<Popover>`.
+   */
+  const IconButton = React.forwardRef(function IconButton(props, ref) {
+    const {
+      icon,
+      accessibilityLabel,
+      variant = "ghost",
+      size,
+      color,
+      fields,
+      onPress,
+      disabled = false,
+      busy = false,
+      selected,
+      style,
+      testID,
+    } = props;
+    const trigger = triggerProps(props);
+    const resolvedVariant = resolveButtonVariant(variant === "link" ? "ghost" : variant);
+    const look = useButtonLook({
+      variant: resolvedVariant,
+      selected: selected === true,
+      fields,
+      hostThemed: false,
+      style,
+    });
+    const { theme, f, layers, ink, gradient } = look;
+    const { box, glyph } = iconButtonFrame(size);
+
+    const container = [
+      { borderRadius: theme.radii.sm, alignItems: "center", justifyContent: "center", alignSelf: "flex-start" },
+      ...layers,
+      // A real square: the web ignores hitSlop, so the box is the target.
+      { width: box, height: box, minWidth: box, minHeight: box, paddingHorizontal: 0, paddingVertical: 0 },
+      gradient ? { backgroundColor: "transparent" } : null,
+      disabled ? { opacity: 0.5 } : null,
+      style,
+    ];
+    const children = [
+      gradient ? gradientFill(gradient, f.radius, theme.radii) : null,
+      busy
+        ? busyMark(look, layers, glyph)
+        : React.createElement(View, { key: "glyph", ...HIDDEN }, React.createElement(Icon, { name: icon, size: glyph, color: color || ink })),
+    ];
+    return React.createElement(
+      Pressable,
+      {
+        ref,
+        onPress,
+        ...trigger.pass,
+        ...pressableState({ disabled, busy, selected, expanded: trigger.expanded }, web),
+        hitSlop: iconButtonHitSlop(box),
+        accessibilityRole: "button",
+        accessibilityLabel,
+        testID,
+        style: pressedStyle(container, disabled || busy),
+      },
+      children,
+    );
+  });
+  IconButton.displayName = "IconButton";
+
+  return { Button, IconButton };
 }

package/dist/button.js

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

package/dist/button.native.js

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