@colixsystems/widget-sdk 0.289.0 → 0.291.0

package/README.md

@@ -90,7 +90,15 @@ See the design reference for the full architecture: [`docs/architecture/widget-m
 
 ## Status
 
-`v0.289.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.291.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.291.0 (contract 1.238.0)
+
+**New linter rule `grid-cell-too-narrow` (severity `error`, blocking).** A `<Grid minCellWidth={N}>` with `N` under 200 whose cell holds more than one `Text` is refused, naming the cell width and the default of 240: on cards carrying a title, a duration and a price it makes five narrow columns at desktop width, with broken words and the price wrapped onto two lines. A cell of a single `Text` (a chip, an avatar, an icon tile) passes at any width, and a Grid without `minCellWidth` passes. A width given as a `const` is followed; one computed at runtime is beyond the scan. See *Design & visual polish*.
+
+### What's new in 0.290.0 (contract 1.238.0)
+
+**New `useConnector(connectorRef)` hook — a widget can call one of the workspace's REST connectors and use the answer itself.** Bind a connector with a `{ type: "connectorRef" }` property and declare `connectors.call:*` in `requestedScopes`. `call(operation, { params, query, body })` names an operation the workspace listed for apps on that connector — never a method or a path — and resolves `{ status, content_type, body }` with the outside API's status and parsed body. The whole call has 250 ms, token exchange included: a slower outside API is cut off and the call rejects with `UPSTREAM_TIMEOUT`. The credential is added on the server and never reaches the app. A new `connectors` host client (`createConnectorsClient` in `@colixsystems/actions-client`), the `connectorRef` property type, the `connectors.call:*` scope and a `ConnectorError`. Everything is additive.
 
 ### What's new in 0.289.0 (contract 1.237.0)
 
@@ -3488,6 +3496,7 @@ A widget that works but looks unfinished is only half done. `useTheme()` is the
 - **Spend one gradient.** `<Gradient colors={[theme.colors.primary, theme.colors.primaryStrong]} angle={160} style={…}>` is a `View` that paints a gradient behind its children, so it replaces the `View` you'd otherwise give a flat `backgroundColor`. `angle` is CSS degrees (0 = to top, 90 = to right, default 180); text on it uses `colors.onPrimary`. Exactly **one** per widget — on the focal element — and never behind body text. Both hosts render it identically (web paints CSS, native uses `expo-linear-gradient`), so there is no per-platform branching to write; don't import `expo-linear-gradient` yourself and don't write a `backgroundImage` string.
 - **Answer the touch.** Every tappable card, row and list entry lifts while the pointer is over it (web) or it is pressed (touch). One declaration does both: give the Pressable a style FUNCTION and spread `pressableLift` — `<Pressable onPress={open} style={(state) => [styles.card, ...pressableLift(state)]}>`. The lift is a -2px nudge plus one elevation step from `theme.interaction`, with the web transition built in. Never hand-write hover logic or your own pressed shadows, and never fake feedback with `opacity` — a dimmed surface reads as disabling itself.
 - **Size to your container — measure it, don't stretch into it.** The same widget sits in a full-width desktop section (~1400px), a half-width grid cell (~700px) and a phone (~360px), so layout built only from `flex: 1` stretches to fill whatever it is handed — a month calendar ends up with 200px day cells and swallows the page. Measure your own width with `const [width, onLayout] = useContainerWidth();`, spreading `onLayout` on an unpadded root `View` (a React Native callback, so it behaves identically on both hosts). A width of `0` means "not yet measured" and the SDK helpers answer it with the wide form, so do not special-case it — except a count or size computed from the width (a calendar day, a chart, a card grid's cards per line), which renders nothing size-dependent until the width arrives: a widget gets no declared breakpoint prop, but it can always measure. **Every form, list, table and filter bar lays out in three tiers**: `const [width, onLayout] = useContainerWidth();` then branch on `widthTier(width)` — a form is one column narrow, paired short fields at medium, a 2–3 column grid capped near 1000px wide; a list is stacked cards, one-line cards, then real columns under a header; a filter bar is one toolbar row (search, a dropdown per facet, sort) with the active filters as removable chips beneath, and a single "Filters" button opening a panel when narrow. **Cap a repeating cell** rather than giving a grid `flex: 1` — `const cell = Math.max(32, Math.min(Math.floor((usable - gap * (columns - 1)) / columns), 64));`, with a calendar day cell topping out at 56–72px on `aspectRatio: 1`, and the grid given its exact computed width plus `alignSelf: 'center'` when the cap leaves slack. **Split two co-equal surfaces in the wide tier** (`flexDirection: widthTier(width) === 'wide' ? 'row' : 'column'`, each half `{ flex: 1, minWidth: 0 }`) — a picker beside the form it feeds on a wide canvas, stacked in reading order below it. Never hardcode a width, never put `flex: 1` / `height: '100%'` on a content widget's root, and don't read the screen with `Dimensions` — the screen is not the widget. **Whatever you narrow, you centre** — a block that caps its own measure carries all three of `{ width: '100%', maxWidth: FORM_MAX, alignSelf: 'center' }`, because `alignSelf` alone stops the block stretching and sizes it to its content instead, and `maxWidth` alone leaves the widget flush left with dead space beside it; a capped wrap row lays its cells out along the MAIN axis, so it centres with `justifyContent: 'center'` on the row instead — but a card grid or a tile row is never capped. **Lay out a card grid, a tile row or a grid of capped cells with `<Grid>` by default** — it measures its own unpadded box and applies the rules below; lay one out yourself when it needs what `<Grid>` cannot express, such as masonry or cells that span lines. **A card grid fills its lines, it never wraps freely** — a free `flexWrap` strands the remainder (six cards that fit five render 5 + 1). Count the cards that fit the measured width (`const max = Math.max(1, Math.floor((width + gap) / (CARD_MIN + gap)));`), take `const lines = Math.ceil(count / max); const cols = Math.ceil(count / lines);`, and render each slice of `cols` cards as a row of `{ flex: 1, minWidth: 0 }` cells, padding the last line with empty `{ flex: 1 }` spacers so its cards keep the width of the cards above (six that fit five are 3 + 3, ten that fit four are 4 + 4 + 2). **A short value never breaks across lines** — a time, date, price, count, percentage or code takes `numberOfLines={1}` and `flexShrink: 0`, never a fixed width narrower than it, and a narrow slot re-arranges or steps the font down instead. **A metric / stat-tile row FILLS ITS ROW** — when you know the count, balance the lines (`const lines = Math.ceil(count / max); const base = Math.floor(count / lines); const extra = count % lines; const rows = Array.from({ length: lines }, (_, i) => tiles.slice(i * base + Math.min(i, extra), (i + 1) * base + Math.min(i + 1, extra)));`, with `max` 4 / 3 / 2 by tier, each tile `{ flex: 1, minWidth: 0 }`), and when the count comes from data wrap it (`{ flexDirection: 'row', flexWrap: 'wrap', gap: theme.spacing.md }`, each tile `{ flexGrow: 1, flexBasis: TILE_MIN }`, never a `maxWidth` — capped tiles cluster to one side), because a bare `flexDirection: 'row'` has no way to break and a React Native flex child defaults to `flexShrink: 0` (unlike CSS), so the tiles cannot give ground either: the row runs past its container, spilling out of the card natively and cut off by the scrolling page column on web, with nothing thrown and nothing logged, once there are enough of them (four fit where five do not). The basis is also the per-line ceiling — `Math.floor((usable + gap) / (TILE_MIN + gap))` tiles fit a line, so 240 tops out at five across a full-width ~1400px section and 320 at four; past four or five a line the tiles stop reading as cards.
+- **A Grid cell that holds more than one `Text` is at least 200 wide.** A cell that holds more than one Text is at least 200 wide: `<Grid minCellWidth={150}>` makes five narrow columns at desktop width, and a card carrying a title, a duration and a price breaks words and wraps the price onto two lines there. Leave `minCellWidth` off (the default is 240) or set it to 240 or more; a width under 200 is for cells of a single `Text` (chips, avatars, icon tiles), and the publish gate refuses (`grid-cell-too-narrow`) a narrower Grid whose cell holds more than one `Text`. An action inside a card is a `<Button>`, never a `Pressable` around text.
 - **Compose forms — pair fields into rows, don't stack one per row.** Lay a form out with `<Form>` by default (above), which does the following for you; when it needs what `<Form>` cannot do (a multi-step wizard, a form beside a live preview, fields laid over a picture), lay the form out in three tiers and cap it near 1000px, centred with the three declarations above — never a 560–720px column alone in a wide box, which leaves a form that IS the page as a narrow strip in empty space. Put short, related fields side by side (first + last name, city + postal code, expiry + CVC): a row of `{ flexDirection: 'row', flexWrap: 'wrap', gap: theme.spacing.md }` with each field cell `{ flexGrow: 1, flexBasis: 160 }` splits the width on a wide card and wraps to stacked on a narrow phone — the right recipe for field pairs because it needs no measurement (a fixed-width column overflows a phone; when a layout needs a real column count instead of wrapping, measure your width as above). Keep wide fields (email, address, notes) full-width with `width: '100%'` — NEVER `flexBasis: '100%'`, which sizes the main axis and therefore claims the parent's whole HEIGHT in a column — cap it at two–three per row, group a long form into labelled sections, and label every input above it (not placeholder-only). Give a `multiline` field BOTH a floor and a ceiling (`{ minHeight: 150, maxHeight: 260 }`) so a long value scrolls inside the box instead of growing past its card, and keep the Save / Cancel row in normal flow below the fields, never positioned over them. A search box is `<SearchField>`, which already carries its glyph and clear control. Any other icon goes inside the field through `leadingIcon` / `trailingIcon`; never wrap a `<TextField>` in a bordered row, since it draws its own border. Put a unit beside the field as a sibling in a row (`flex: 1, minWidth: 0` on the field, so a long value shrinks instead of pushing the row past its container) rather than rebuilding the field to hold it: a hand-built bordered wrapper around a bare `TextInput` loses the app's input look and its label, focus and error handling.
 - **Respond to touch.** Give every `Pressable` the lift via the function-style `style={(state) => [base, ...pressableLift(state)]}` — see "Answer the touch" above. Never dim with `opacity`, which reads as the surface disabling itself.
 - **Drag and drop — show what is being dragged.** Use `<SortableList>` for a list the user reorders and `<Board>` for cards moved between columns by default: they do everything this item describes, on both hosts, and give a user who cannot drag the same moves from the handle. When the request needs what they cannot do (free-form positioning on a canvas, a drag between two widgets), build your own as follows. A drag where the item stays put reads as broken. Three things change the moment a drag starts: the **drag proxy** (the item lifts and follows the finger — `...theme.elevation.lg`, `{ scale: 1.03 }`, `opacity: 0.9`; for a tall or full-width item drag a compact `primarySoft` pill with its icon + one line of label instead), the **source placeholder** (the vacated slot keeps its height as a quiet `colors.surfaceMuted` block so the list doesn't collapse), and the **drop target** (one slot at a time highlighted with `primarySoft` or a 2px `colors.primary` border). Always animate the release — settle into the new slot, or `Animated.spring(pan, { toValue: { x: 0, y: 0 }, useNativeDriver: false })` back to the origin on cancel. Build it with `Animated` + `PanResponder` from `react-native` (the only mechanism that behaves identically on both hosts) — never HTML5 drag events (`draggable` / `onDragStart` / `dataTransfer` are web-only, and `document` / `window` are banned) — and start the drag from a `GripVertical` grip handle whenever the row is also tappable or sits in a `ScrollView`. **A board (kanban, pipeline) drops onto ANOTHER column**, which needs four more things: the board's root renders the one proxy (a column clips whatever leaves it); you hit-test the drop yourself — `measureInWindow` every column and the board when the drag starts and compare the gesture's window `moveX` (never `onLayout` frames, which are relative to a padded or scrolled parent) — highlighting exactly one target; the drop WRITES (`update(id, { [statusField]: value })` through `useDatastoreMutation`, optimistic until `refetch()`, a toast and a spring-back on failure); and three or more columns go in a `horizontal` `ScrollView` when `widthTier(width) === "narrow"`, with the grip claiming the gesture (`onStartShouldSetPanResponder`, `onPanResponderTerminationRequest: () => false`) and carrying `touchAction: 'none'` on web so a finger drag moves the card instead of scrolling the page. And because `useRef(PanResponder.create(...))` runs ONCE, everything its callbacks read — the `useCanWrite` flag included, which starts `false` — goes through a ref refreshed every render (`latest.current.canDrag`); the publish gate `widget.staleResponder` rejects a value read directly.
@@ -3900,6 +3909,8 @@ Pass `--manifest` to enable `style-field-unread` and the three editability rules
 
 `flex-basis-percent` flags a literal percentage `flexBasis` — `"100%"`, `"50%"`, or the ternary a responsive cell writes. `flex-basis` sizes the MAIN axis, so in a column parent it asks for the parent's HEIGHT: under an ancestor that makes that height definite (a Grid cell stretches its child on the web Player) the child fills the container and, since a `View` never shrinks, overflows over everything below it. Say full-width with `width: "100%"` — correct in a column AND in a wrap row — and keep a NUMBER for a wrap threshold. A warning, because the percentage is right in a row and a text scan cannot see the parent.
 
+`grid-cell-too-narrow` refuses a `<Grid minCellWidth={N}>` with `N` under 200 whose cell holds more than one `Text`, naming the cell width and the default of 240: a card with a title and a price breaks its words at that width. A cell of a single `Text` passes at any width, and a Grid without `minCellWidth` passes. An error.
+
 `row-action-not-gated` flags a widget that calls `update` or `delete` from `useDatastoreMutation` without a per-row permission check: no `_capabilities` read and no `useCanWrite(tableId, { recordId })`. The table-level `useCanWrite(tableId)` only answers "may create", so a list gated on it shows Edit / Delete on rows the server will refuse. A warning.
 
 `no-html-in-content` flags an HTML tag inside a **string** — `"<strong>"`, `"<br>"`, `"<p>…</p>"`. There is no HTML renderer on either host, so the tag reaches the reader as literal text; author formatted text with `<MarkdownInput>` and render it with `<RichText>` instead. Only string and template content is scanned, so your own `<View>` / `<Text>` JSX can never trip it. A warning for a human author, blocking for the AI widget agent.

package/dist/contract.cjs

@@ -2299,6 +2299,46 @@ const HOOKS = [
     requiredContextSlice: ["actions.run"],
     scopes: ["actions.run:*"],
   },
+  {
+    name: "useConnector",
+    signature: "useConnector(connectorRef)",
+    description:
+      "sc-15659 — call one of the WORKSPACE's REST connectors (a configured " +
+      "outside API) straight from the widget, and use the answer in the " +
+      "widget. call(operation, { params, query, body }) names an OPERATION " +
+      "the workspace listed for apps on that connector, never a method or a " +
+      "path: the server builds the request from the listing and adds the " +
+      "connector's credential, which never reaches the app. `params` fills " +
+      "the operation's {name} path segments (one whole segment each, no " +
+      "slashes); `query` may use only the names the operation lists; `body` " +
+      "only where the operation takes one. call resolves with { status, " +
+      "content_type, body } — the outside API's status (a non-2xx answer " +
+      "still resolves: branch on status) and its parsed JSON or text body. " +
+      "The whole call must finish within 250 ms, token exchange included: a " +
+      "slower outside API is cut off and the call rejects with UPSTREAM_TIMEOUT. " +
+      "May run on mount for a read operation; an operation that changes data " +
+      "belongs in an event handler. `connectorRef` is a connector id an " +
+      "author bound through a `connectorRef` property — when it is missing, " +
+      "or the host brokers no connectors client, `available` is false and " +
+      "call() rejects UNAVAILABLE; render a visible 'pick a connector' state, " +
+      "NEVER a blank box. Only signed-in app users may call. ConnectorError.code: " +
+      "OPERATION_NOT_ALLOWED (403), CONNECTOR_NOT_FOUND (404, also when the " +
+      "connector is not callable from the app) and CONNECTOR_SETUP_INCOMPLETE " +
+      "(409) will NOT clear on a retry, so show an 'isn't available' state; " +
+      "RATE_LIMITED (429) will; INVALID_CONNECTOR_PARAMS (400) means an " +
+      "argument the operation does not take; UPSTREAM_ERROR (502) and " +
+      "UPSTREAM_TIMEOUT (504) mean the outside API failed; AUTH_REQUIRED, " +
+      "TOKEN_EXPIRED and TOKEN_INVALID mean the app user must sign in. NEVER " +
+      "show an app user a raw error. Reads ctx.connectors.",
+    returnShape: {
+      available: "boolean  // false when no connector is bound or the host brokers none",
+      call: "(operation, { params?, query?, body? }) => Promise<{ status, content_type, body }>  // rejects with ConnectorError",
+      calling: "boolean  // true while any call is in flight",
+      error: "ConnectorError | null  // the last call's error; cleared by the next call or a rebind",
+    },
+    requiredContextSlice: ["connectors.call"],
+    scopes: ["connectors.call:*"],
+  },
   {
     name: "useDatastoreMutation",
     signature: "useDatastoreMutation(tableId)",
@@ -4342,6 +4382,17 @@ const WIDGET_CONTEXT_SHAPE = {
     required: false,
     fields: { run: "function", status: "function" },
   },
+  connectors: {
+    description:
+      "sc-15659 — injected connectors client from @colixsystems/actions-client. " +
+      "{ call(connectorId, operation, { params, query, body }) -> Promise<{ status, content_type, body }> }. " +
+      "Backs useConnector(). Calls one operation the workspace listed on an app-callable " +
+      "connector, as the signed-in caller; the credential is added server-side. Errors carry " +
+      "the server's `code` and `status`. Absent on a host that brokers none, where " +
+      "useConnector() degrades to available: false rather than throwing.",
+    required: false,
+    fields: { call: "function" },
+  },
   linkPreviews: {
     description:
       "Injected @colixsystems/link-preview-client instance. { get(url) -> Promise<{ url, title, description, site_name, image_url }> }. " +
@@ -6751,7 +6802,10 @@ const CONTRACT = deepFreeze({
   //    PaymentError codes.
   // 1.237.0: widening — `manifest.translations` may declare up to 500 keys
   //    (was 200).
-  version: "1.237.0",
+  // 1.238.0: additive (sc-15659) — `useConnector(connectorRef)` + the
+  //    `connectors` host client + the `connectorRef` propertySchema type + the
+  //    `connectors.call:*` scope. A widget calls a REST connector's listed operations.
+  version: "1.238.0",
   sharedTranslationKeys: SHARED_TRANSLATION_KEYS,
   hooks: HOOKS,
   primitives: PRIMITIVES,

package/dist/contract.js

@@ -2295,6 +2295,46 @@ const HOOKS = [
     requiredContextSlice: ["actions.run"],
     scopes: ["actions.run:*"],
   },
+  {
+    name: "useConnector",
+    signature: "useConnector(connectorRef)",
+    description:
+      "sc-15659 — call one of the WORKSPACE's REST connectors (a configured " +
+      "outside API) straight from the widget, and use the answer in the " +
+      "widget. call(operation, { params, query, body }) names an OPERATION " +
+      "the workspace listed for apps on that connector, never a method or a " +
+      "path: the server builds the request from the listing and adds the " +
+      "connector's credential, which never reaches the app. `params` fills " +
+      "the operation's {name} path segments (one whole segment each, no " +
+      "slashes); `query` may use only the names the operation lists; `body` " +
+      "only where the operation takes one. call resolves with { status, " +
+      "content_type, body } — the outside API's status (a non-2xx answer " +
+      "still resolves: branch on status) and its parsed JSON or text body. " +
+      "The whole call must finish within 250 ms, token exchange included: a " +
+      "slower outside API is cut off and the call rejects with UPSTREAM_TIMEOUT. " +
+      "May run on mount for a read operation; an operation that changes data " +
+      "belongs in an event handler. `connectorRef` is a connector id an " +
+      "author bound through a `connectorRef` property — when it is missing, " +
+      "or the host brokers no connectors client, `available` is false and " +
+      "call() rejects UNAVAILABLE; render a visible 'pick a connector' state, " +
+      "NEVER a blank box. Only signed-in app users may call. ConnectorError.code: " +
+      "OPERATION_NOT_ALLOWED (403), CONNECTOR_NOT_FOUND (404, also when the " +
+      "connector is not callable from the app) and CONNECTOR_SETUP_INCOMPLETE " +
+      "(409) will NOT clear on a retry, so show an 'isn't available' state; " +
+      "RATE_LIMITED (429) will; INVALID_CONNECTOR_PARAMS (400) means an " +
+      "argument the operation does not take; UPSTREAM_ERROR (502) and " +
+      "UPSTREAM_TIMEOUT (504) mean the outside API failed; AUTH_REQUIRED, " +
+      "TOKEN_EXPIRED and TOKEN_INVALID mean the app user must sign in. NEVER " +
+      "show an app user a raw error. Reads ctx.connectors.",
+    returnShape: {
+      available: "boolean  // false when no connector is bound or the host brokers none",
+      call: "(operation, { params?, query?, body? }) => Promise<{ status, content_type, body }>  // rejects with ConnectorError",
+      calling: "boolean  // true while any call is in flight",
+      error: "ConnectorError | null  // the last call's error; cleared by the next call or a rebind",
+    },
+    requiredContextSlice: ["connectors.call"],
+    scopes: ["connectors.call:*"],
+  },
   {
     name: "useDatastoreMutation",
     signature: "useDatastoreMutation(tableId)",
@@ -4338,6 +4378,17 @@ const WIDGET_CONTEXT_SHAPE = {
     required: false,
     fields: { run: "function", status: "function" },
   },
+  connectors: {
+    description:
+      "sc-15659 — injected connectors client from @colixsystems/actions-client. " +
+      "{ call(connectorId, operation, { params, query, body }) -> Promise<{ status, content_type, body }> }. " +
+      "Backs useConnector(). Calls one operation the workspace listed on an app-callable " +
+      "connector, as the signed-in caller; the credential is added server-side. Errors carry " +
+      "the server's `code` and `status`. Absent on a host that brokers none, where " +
+      "useConnector() degrades to available: false rather than throwing.",
+    required: false,
+    fields: { call: "function" },
+  },
   linkPreviews: {
     description:
       "Injected @colixsystems/link-preview-client instance. { get(url) -> Promise<{ url, title, description, site_name, image_url }> }. " +
@@ -6747,7 +6798,10 @@ const CONTRACT = deepFreeze({
   //    PaymentError codes.
   // 1.237.0: widening — `manifest.translations` may declare up to 500 keys
   //    (was 200).
-  version: "1.237.0",
+  // 1.238.0: additive (sc-15659) — `useConnector(connectorRef)` + the
+  //    `connectors` host client + the `connectorRef` propertySchema type + the
+  //    `connectors.call:*` scope. A widget calls a REST connector's listed operations.
+  version: "1.238.0",
   sharedTranslationKeys: SHARED_TRANSLATION_KEYS,
   hooks: HOOKS,
   primitives: PRIMITIVES,

package/dist/hooks.js

@@ -4118,6 +4118,115 @@ export function useAction(actionRef) {
   };
 }
 
+/**
+ * sc-15659 — what useConnector() rejects with. `code` is one of:
+ *   - "UNAVAILABLE"                — no connector bound, or the host brokers no
+ *                                    connectors client (render the unbound state)
+ *   - "OPERATION_NOT_ALLOWED"      — 403 (the workspace did not list this operation)
+ *   - "INVALID_CONNECTOR_PARAMS"   — 400 (an argument the operation does not take)
+ *   - "CONNECTOR_NOT_FOUND"        — 404 (gone, or no longer callable from the app)
+ *   - "CONNECTOR_SETUP_INCOMPLETE" — 409 (the workspace has not finished its sign-in)
+ *   - "RATE_LIMITED"               — 429 (too many calls — retry shortly)
+ *   - "AUTH_REQUIRED" / "TOKEN_EXPIRED" / "TOKEN_INVALID" — 401 (no app session)
+ *   - "UPSTREAM_ERROR" / "UPSTREAM_TIMEOUT" — 502 / 504 (the outside API failed)
+ *   - "CONNECTOR_FAILED"           — no answer came
+ *
+ * The connectors client owns these codes; any other server code passes through.
+ */
+export class ConnectorError extends Error {
+  constructor(code, message, opts) {
+    super(message);
+    this.name = "ConnectorError";
+    this.code = code;
+    if (opts && opts.cause) this.cause = opts.cause;
+  }
+}
+
+function toConnectorError(err) {
+  if (err instanceof ConnectorError) return err;
+  const code = err && typeof err.code === "string" && err.code ? err.code : "CONNECTOR_FAILED";
+  const message = (err && err.message) || "The connector call failed";
+  return new ConnectorError(code, message, { cause: err });
+}
+
+/**
+ * sc-15659 — call one of the workspace's REST connectors through an operation
+ * the workspace listed for apps. Returns `{ available, call, calling, error }`.
+ *
+ *   call(operation, { params?, query?, body? }) → Promise<{ status, content_type, body }>
+ *
+ * The widget owns what it does with the answer. A non-2xx upstream status
+ * still resolves; a platform refusal rejects with a ConnectorError. The
+ * connector's credential is added on the server and never reaches the app.
+ *
+ * `connectorRef` is the connector id an author bound through a
+ * `connectorRef` property. When it is absent, or the host brokers no
+ * connectors client, `available` is false and `call` rejects UNAVAILABLE
+ * rather than throwing at render — render a visible unbound state.
+ *
+ * Routes through the injected `@colixsystems/actions-client` at
+ * `ctx.connectors`, so the Player and the Expo export call identically.
+ */
+export function useConnector(connectorRef) {
+  const ctx = useWidgetContextOrThrow("useConnector");
+  const available =
+    Boolean(connectorRef) && Boolean(ctx.connectors) && typeof ctx.connectors.call === "function";
+
+  const clientRef = useRef(null);
+  clientRef.current = available ? ctx.connectors : null;
+  const connectorIdRef = useRef(connectorRef);
+  connectorIdRef.current = connectorRef;
+
+  const mountedRef = useRef(true);
+  useEffect(() => {
+    mountedRef.current = true;
+    return () => {
+      mountedRef.current = false;
+    };
+  }, []);
+
+  // A rebind starts clean: another connector's error never shows.
+  const [outcome, setOutcome] = useState({ boundTo: connectorRef, pending: 0, error: null });
+
+  const call = useCallback(async (operation, args) => {
+    const client = clientRef.current;
+    const connectorId = connectorIdRef.current;
+    if (!client || !connectorId) {
+      throw new ConnectorError("UNAVAILABLE", "No connector is available for this host");
+    }
+    const settle = (error) => {
+      if (!mountedRef.current) return;
+      setOutcome((prior) =>
+        prior.boundTo === connectorId
+          ? { boundTo: connectorId, pending: Math.max(0, prior.pending - 1), error }
+          : prior,
+      );
+    };
+    setOutcome((prior) =>
+      prior.boundTo === connectorId
+        ? { ...prior, pending: prior.pending + 1, error: null }
+        : { boundTo: connectorId, pending: 1, error: null },
+    );
+    try {
+      const answer = await client.call(connectorId, operation, args);
+      settle(null);
+      return answer;
+    } catch (err) {
+      const e = toConnectorError(err);
+      settle(e);
+      throw e;
+    }
+  }, []);
+
+  const current = outcome.boundTo === connectorRef;
+  return {
+    available,
+    call,
+    calling: current && outcome.pending > 0,
+    error: current ? outcome.error : null,
+  };
+}
+
 /**
  * Datastore mutation hook. Returns { create, update, delete }, each method
  * returning a Promise. Routes through the injected

package/dist/index.d.ts

@@ -910,6 +910,10 @@ export interface WidgetContext<TProps = unknown> {
     /** sc-14224 — whether a run would reach the script; optional on older hosts. */
     status?(actionId: string): Promise<{ available: boolean; reason: string | null }>;
   };
+  /** sc-15659 — injected @colixsystems/actions-client backing useConnector(). */
+  connectors?: {
+    call(connectorId: string, operation: string, args?: ConnectorCallArgs): Promise<ConnectorCallResult>;
+  };
   /** Injected @colixsystems/link-preview-client backing useLinkPreview(). */
   linkPreviews?: { get(url: string): Promise<LinkPreview> };
   /** Host child-node renderer; backs WidgetTree / useChildRenderer. */
@@ -2105,6 +2109,40 @@ export interface ActionApi {
  */
 export function useAction(actionRef: string | null | undefined): ActionApi;
 
+export interface ConnectorCallArgs {
+  /** Values for the operation's `{name}` path segments; one whole segment each. */
+  params?: Record<string, string | number>;
+  /** Only the query names the operation lists. */
+  query?: Record<string, string | number | boolean | Array<string | number | boolean>>;
+  /** A JSON body, only for an operation that takes one. */
+  body?: unknown;
+}
+
+/** The outside API's answer: its status (non-2xx still resolves) and parsed body. */
+export interface ConnectorCallResult {
+  status: number;
+  content_type: string | null;
+  body: unknown;
+}
+
+export interface ConnectorApi {
+  /** False when no connector is bound or the host brokers no connectors client. */
+  available: boolean;
+  /** Call one operation the workspace listed; rejects with ConnectorError. */
+  call(operation: string, args?: ConnectorCallArgs): Promise<ConnectorCallResult>;
+  /** True while any call is in flight. */
+  calling: boolean;
+  /** The last call's error; cleared by the next call or a rebind. */
+  error: ConnectorError | null;
+}
+
+/**
+ * sc-15659 — call one of the workspace's REST connectors through an operation
+ * the workspace listed for apps. The widget needs `connectors.call:*` in
+ * `requestedScopes`; the credential never reaches the app.
+ */
+export function useConnector(connectorRef: string | null | undefined): ConnectorApi;
+
 // REQ-RT-07 realtime subscription transport state.
 export type DatastoreSubscriptionStatus =
   | "connecting"
@@ -3441,6 +3479,30 @@ export class AgentError extends Error {
  * `RATE_LIMITED` will. `AUTH_REQUIRED`, `TOKEN_EXPIRED` and `TOKEN_INVALID`
  * mean the app user must sign in. Never show an app user the raw message.
  */
+/**
+ * sc-15659 — structured error thrown by `useConnector().call`. Branch on
+ * `code`: `OPERATION_NOT_ALLOWED`, `CONNECTOR_NOT_FOUND` and
+ * `CONNECTOR_SETUP_INCOMPLETE` will not clear on a retry, `RATE_LIMITED` will.
+ * Never show an app user the raw message.
+ */
+export class ConnectorError extends Error {
+  code:
+    | "UNAVAILABLE"
+    | "INVALID_CONNECTOR_PARAMS"
+    | "OPERATION_NOT_ALLOWED"
+    | "CONNECTOR_NOT_FOUND"
+    | "CONNECTOR_SETUP_INCOMPLETE"
+    | "RATE_LIMITED"
+    | "AUTH_REQUIRED"
+    | "TOKEN_EXPIRED"
+    | "TOKEN_INVALID"
+    | "UPSTREAM_ERROR"
+    | "UPSTREAM_TIMEOUT"
+    | "CONNECTOR_FAILED"
+    | (string & {});
+  constructor(code: string, message: string, opts?: { cause?: unknown });
+}
+
 export class ActionError extends Error {
   code:
     | "UNAVAILABLE"

package/dist/index.js

@@ -30,6 +30,7 @@ export {
   PermissionError,
   AgentError,
   ActionError,
+  ConnectorError,
   useDatastoreQuery,
   useDatastoreRecord,
   useDatastoreSchema,
@@ -39,6 +40,7 @@ export {
   useInterpretDraft,
   useAgent,
   useAction,
+  useConnector,
   useAsset,
   useAssetsByTag,
   useBundledAsset,

package/dist/index.native.js

@@ -30,6 +30,7 @@ export {
   PermissionError,
   AgentError,
   ActionError,
+  ConnectorError,
   useDatastoreQuery,
   useDatastoreRecord,
   useDatastoreSchema,
@@ -39,6 +40,7 @@ export {
   useInterpretDraft,
   useAgent,
   useAction,
+  useConnector,
   useAsset,
   useAssetsByTag,
   useBundledAsset,

package/dist/linter.cjs

@@ -861,6 +861,16 @@ function _scopeRules(source, manifest) {
       snippet: "",
     });
   }
+  // sc-15659 — DISCLOSURE, as for useAction: the server gate is the app-user
+  // JWT plus the connector's app opt-in and listed operations.
+  if (/\buseConnector\s*\(/.test(source) && !declared.has("connectors.call:*")) {
+    findings.push({
+      rule: "scope-required-for-useConnector",
+      label: "useConnector() requires `connectors.call:*` in manifest.requestedScopes",
+      line: 0,
+      snippet: "",
+    });
+  }
   const lines = source.split(/\r?\n/);
   let firedUsersWrite = false;
   let firedUsersDelete = false;
@@ -2155,6 +2165,79 @@ function _fieldInBorderedRowRules(source) {
   return findings;
 }
 
+// sc-15754 — a Grid cell narrower than the default fits one Text, not a card.
+//
+// `<Grid minCellWidth={150}>` on cards carrying a title, a duration and a
+// price made five narrow columns at desktop width, with broken words and the
+// prices wrapped onto two lines; the agent cannot see that until it renders.
+// A cell of a single Text (a chip, an avatar, an icon tile) is fine at any
+// width, so only a cell holding more than one Text is refused. A width read
+// from a `const` is followed; one computed at runtime stays beyond the scan.
+const _GRID_DEFAULT_MIN_CELL_WIDTH = 240; // grid-logic.js DEFAULT_MIN_CELL_WIDTH
+const _GRID_NARROW_CELL_WIDTH = 200;
+const _MIN_CELL_WIDTH_ATTR_RE =
+  /\bminCellWidth\s*=\s*\{\s*(\d+(?:\.\d+)?|[A-Za-z_$][\w$]*)\s*\}/;
+
+function _gridMinCellWidth(structure, attrs) {
+  const hit = _MIN_CELL_WIDTH_ATTR_RE.exec(attrs);
+  if (!hit) return NaN;
+  if (/^\d/.test(hit[1])) return Number(hit[1]);
+  const declared = new RegExp(`\\bconst\\s+${hit[1]}\\s*=\\s*(\\d+(?:\\.\\d+)?)\\s*;`).exec(structure);
+  return declared ? Number(declared[1]) : NaN;
+}
+
+function _gridCellWidthRules(source) {
+  const findings = [];
+  const structure = _stripNonCode(source);
+  const index = _jsxScanIndex(structure);
+  const sourceLines = source.split(/\r?\n/);
+  const lineAt = _lineCounter(structure);
+  const open = _openTagStack();
+  _JSX_TOKEN_RE.lastIndex = 0;
+  let token;
+  while ((token = _JSX_TOKEN_RE.exec(structure))) {
+    const [, closing, name] = token;
+    const parent = open.top();
+    if (!name) {
+      if (structure[token.index + 1 + closing.length] !== ">") continue;
+      // A fragment is transparent: its children are its parent's children.
+      if (closing) open.pop();
+      else open.push({ name: "", narrow: parent && parent.narrow, cell: parent && parent.cell });
+      continue;
+    }
+    if (closing) {
+      open.close(name);
+      continue;
+    }
+    const end = index.tagEnd(token.index);
+    if (end === -1) break;
+    const tag = { name, narrow: undefined, cell: parent && parent.cell };
+    if (parent && parent.narrow !== undefined) tag.cell = { width: parent.narrow, at: token.index, texts: 0 };
+    if (name === "Grid") {
+      const width = _gridMinCellWidth(structure, structure.slice(token.index, end));
+      if (width < _GRID_NARROW_CELL_WIDTH) tag.narrow = width;
+    }
+    if (name === "Text" && tag.cell && ++tag.cell.texts === 2) {
+      const line = lineAt(tag.cell.at);
+      findings.push({
+        rule: "grid-cell-too-narrow",
+        severity: "error",
+        label:
+          `<Grid minCellWidth={${tag.cell.width}}> makes each cell ${tag.cell.width}px wide, and a cell ` +
+          `holding more than one Text breaks its words and wraps a price or a time onto two ` +
+          `lines at that width. Leave minCellWidth off (the default is ${_GRID_DEFAULT_MIN_CELL_WIDTH}) ` +
+          `or set it to ${_GRID_DEFAULT_MIN_CELL_WIDTH} or more; a width under ${_GRID_NARROW_CELL_WIDTH} ` +
+          `fits only a cell of a single Text, such as a chip, an avatar or an icon tile.`,
+        line,
+        snippet: (sourceLines[line - 1] || "").trim().slice(0, 200),
+      });
+    }
+    if (!_selfClosing(structure, end)) open.push(tag);
+    _JSX_TOKEN_RE.lastIndex = end + 1;
+  }
+  return findings;
+}
+
 // sc-4913 — a measured frame INCLUDES the element's own padding.
 //
 // `onLayout` reports the frame width, and padding sits inside that frame. A
@@ -2886,6 +2969,8 @@ function lintSource(source, options) {
   findings.push(..._fullWidthMarginRules(source));
   // sc-12232 — soft warning: a field inside a bordered row draws two borders.
   findings.push(..._fieldInBorderedRowRules(source));
+  // sc-15754 — a Grid cell under 200px holding more than one Text is refused.
+  findings.push(..._gridCellWidthRules(source));
   // sc-4913 — soft warning: a measured width that includes the widget's own
   // padding wraps the last grid column into an empty one.
   findings.push(..._measuredPaddingRules(source));

package/dist/linter.js

@@ -856,6 +856,16 @@ function _scopeRules(source, manifest) {
       snippet: "",
     });
   }
+  // sc-15659 — DISCLOSURE, as for useAction: the server gate is the app-user
+  // JWT plus the connector's app opt-in and listed operations.
+  if (/\buseConnector\s*\(/.test(source) && !declared.has("connectors.call:*")) {
+    findings.push({
+      rule: "scope-required-for-useConnector",
+      label: "useConnector() requires `connectors.call:*` in manifest.requestedScopes",
+      line: 0,
+      snippet: "",
+    });
+  }
   const lines = source.split(/\r?\n/);
   let firedUsersWrite = false;
   let firedUsersDelete = false;
@@ -2150,6 +2160,79 @@ function _fieldInBorderedRowRules(source) {
   return findings;
 }
 
+// sc-15754 — a Grid cell narrower than the default fits one Text, not a card.
+//
+// `<Grid minCellWidth={150}>` on cards carrying a title, a duration and a
+// price made five narrow columns at desktop width, with broken words and the
+// prices wrapped onto two lines; the agent cannot see that until it renders.
+// A cell of a single Text (a chip, an avatar, an icon tile) is fine at any
+// width, so only a cell holding more than one Text is refused. A width read
+// from a `const` is followed; one computed at runtime stays beyond the scan.
+const _GRID_DEFAULT_MIN_CELL_WIDTH = 240; // grid-logic.js DEFAULT_MIN_CELL_WIDTH
+const _GRID_NARROW_CELL_WIDTH = 200;
+const _MIN_CELL_WIDTH_ATTR_RE =
+  /\bminCellWidth\s*=\s*\{\s*(\d+(?:\.\d+)?|[A-Za-z_$][\w$]*)\s*\}/;
+
+function _gridMinCellWidth(structure, attrs) {
+  const hit = _MIN_CELL_WIDTH_ATTR_RE.exec(attrs);
+  if (!hit) return NaN;
+  if (/^\d/.test(hit[1])) return Number(hit[1]);
+  const declared = new RegExp(`\\bconst\\s+${hit[1]}\\s*=\\s*(\\d+(?:\\.\\d+)?)\\s*;`).exec(structure);
+  return declared ? Number(declared[1]) : NaN;
+}
+
+function _gridCellWidthRules(source) {
+  const findings = [];
+  const structure = _stripNonCode(source);
+  const index = _jsxScanIndex(structure);
+  const sourceLines = source.split(/\r?\n/);
+  const lineAt = _lineCounter(structure);
+  const open = _openTagStack();
+  _JSX_TOKEN_RE.lastIndex = 0;
+  let token;
+  while ((token = _JSX_TOKEN_RE.exec(structure))) {
+    const [, closing, name] = token;
+    const parent = open.top();
+    if (!name) {
+      if (structure[token.index + 1 + closing.length] !== ">") continue;
+      // A fragment is transparent: its children are its parent's children.
+      if (closing) open.pop();
+      else open.push({ name: "", narrow: parent && parent.narrow, cell: parent && parent.cell });
+      continue;
+    }
+    if (closing) {
+      open.close(name);
+      continue;
+    }
+    const end = index.tagEnd(token.index);
+    if (end === -1) break;
+    const tag = { name, narrow: undefined, cell: parent && parent.cell };
+    if (parent && parent.narrow !== undefined) tag.cell = { width: parent.narrow, at: token.index, texts: 0 };
+    if (name === "Grid") {
+      const width = _gridMinCellWidth(structure, structure.slice(token.index, end));
+      if (width < _GRID_NARROW_CELL_WIDTH) tag.narrow = width;
+    }
+    if (name === "Text" && tag.cell && ++tag.cell.texts === 2) {
+      const line = lineAt(tag.cell.at);
+      findings.push({
+        rule: "grid-cell-too-narrow",
+        severity: "error",
+        label:
+          `<Grid minCellWidth={${tag.cell.width}}> makes each cell ${tag.cell.width}px wide, and a cell ` +
+          `holding more than one Text breaks its words and wraps a price or a time onto two ` +
+          `lines at that width. Leave minCellWidth off (the default is ${_GRID_DEFAULT_MIN_CELL_WIDTH}) ` +
+          `or set it to ${_GRID_DEFAULT_MIN_CELL_WIDTH} or more; a width under ${_GRID_NARROW_CELL_WIDTH} ` +
+          `fits only a cell of a single Text, such as a chip, an avatar or an icon tile.`,
+        line,
+        snippet: (sourceLines[line - 1] || "").trim().slice(0, 200),
+      });
+    }
+    if (!_selfClosing(structure, end)) open.push(tag);
+    _JSX_TOKEN_RE.lastIndex = end + 1;
+  }
+  return findings;
+}
+
 // sc-4913 — a measured frame INCLUDES the element's own padding.
 //
 // `onLayout` reports the frame width, and padding sits inside that frame. A
@@ -2881,6 +2964,8 @@ export function lintSource(source, options) {
   findings.push(..._fullWidthMarginRules(source));
   // sc-12232 — soft warning: a field inside a bordered row draws two borders.
   findings.push(..._fieldInBorderedRowRules(source));
+  // sc-15754 — a Grid cell under 200px holding more than one Text is refused.
+  findings.push(..._gridCellWidthRules(source));
   // sc-4913 — soft warning: a measured width that includes the widget's own
   // padding wraps the last grid column into an empty one.
   findings.push(..._measuredPaddingRules(source));

package/dist/property-schema.js

@@ -32,6 +32,9 @@ const VALID_TYPES = new Set([
   // sc-13843: `actionRef` picks one of the workspace's Actions, a bare
   // Action UUID a widget passes to `useAction(actionRef)`. Remapped like agentRef.
   "actionRef",
+  // sc-15659: `connectorRef` picks one of the workspace's app-callable REST
+  // connectors, a bare id a widget passes to `useConnector`. Remapped likewise.
+  "connectorRef",
   // REQ-WDG-PAGEREF: `pageRef` is a page picker that emits a bare AppPage
   // UUID into the page JSON. Renders a page `<select>` in the Studio
   // Properties Panel; a widget reads it and navigates via
@@ -164,6 +167,7 @@ function coerceLeaf(def, value, path, errors) {
     case "sectionRef":
     case "agentRef":
     case "actionRef":
+    case "connectorRef":
     case "richText":
     case "asset":
     case "folderRef":

package/package.json

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

package/src/contract.js

@@ -2295,6 +2295,46 @@ const HOOKS = [
     requiredContextSlice: ["actions.run"],
     scopes: ["actions.run:*"],
   },
+  {
+    name: "useConnector",
+    signature: "useConnector(connectorRef)",
+    description:
+      "sc-15659 — call one of the WORKSPACE's REST connectors (a configured " +
+      "outside API) straight from the widget, and use the answer in the " +
+      "widget. call(operation, { params, query, body }) names an OPERATION " +
+      "the workspace listed for apps on that connector, never a method or a " +
+      "path: the server builds the request from the listing and adds the " +
+      "connector's credential, which never reaches the app. `params` fills " +
+      "the operation's {name} path segments (one whole segment each, no " +
+      "slashes); `query` may use only the names the operation lists; `body` " +
+      "only where the operation takes one. call resolves with { status, " +
+      "content_type, body } — the outside API's status (a non-2xx answer " +
+      "still resolves: branch on status) and its parsed JSON or text body. " +
+      "The whole call must finish within 250 ms, token exchange included: a " +
+      "slower outside API is cut off and the call rejects with UPSTREAM_TIMEOUT. " +
+      "May run on mount for a read operation; an operation that changes data " +
+      "belongs in an event handler. `connectorRef` is a connector id an " +
+      "author bound through a `connectorRef` property — when it is missing, " +
+      "or the host brokers no connectors client, `available` is false and " +
+      "call() rejects UNAVAILABLE; render a visible 'pick a connector' state, " +
+      "NEVER a blank box. Only signed-in app users may call. ConnectorError.code: " +
+      "OPERATION_NOT_ALLOWED (403), CONNECTOR_NOT_FOUND (404, also when the " +
+      "connector is not callable from the app) and CONNECTOR_SETUP_INCOMPLETE " +
+      "(409) will NOT clear on a retry, so show an 'isn't available' state; " +
+      "RATE_LIMITED (429) will; INVALID_CONNECTOR_PARAMS (400) means an " +
+      "argument the operation does not take; UPSTREAM_ERROR (502) and " +
+      "UPSTREAM_TIMEOUT (504) mean the outside API failed; AUTH_REQUIRED, " +
+      "TOKEN_EXPIRED and TOKEN_INVALID mean the app user must sign in. NEVER " +
+      "show an app user a raw error. Reads ctx.connectors.",
+    returnShape: {
+      available: "boolean  // false when no connector is bound or the host brokers none",
+      call: "(operation, { params?, query?, body? }) => Promise<{ status, content_type, body }>  // rejects with ConnectorError",
+      calling: "boolean  // true while any call is in flight",
+      error: "ConnectorError | null  // the last call's error; cleared by the next call or a rebind",
+    },
+    requiredContextSlice: ["connectors.call"],
+    scopes: ["connectors.call:*"],
+  },
   {
     name: "useDatastoreMutation",
     signature: "useDatastoreMutation(tableId)",
@@ -4338,6 +4378,17 @@ const WIDGET_CONTEXT_SHAPE = {
     required: false,
     fields: { run: "function", status: "function" },
   },
+  connectors: {
+    description:
+      "sc-15659 — injected connectors client from @colixsystems/actions-client. " +
+      "{ call(connectorId, operation, { params, query, body }) -> Promise<{ status, content_type, body }> }. " +
+      "Backs useConnector(). Calls one operation the workspace listed on an app-callable " +
+      "connector, as the signed-in caller; the credential is added server-side. Errors carry " +
+      "the server's `code` and `status`. Absent on a host that brokers none, where " +
+      "useConnector() degrades to available: false rather than throwing.",
+    required: false,
+    fields: { call: "function" },
+  },
   linkPreviews: {
     description:
       "Injected @colixsystems/link-preview-client instance. { get(url) -> Promise<{ url, title, description, site_name, image_url }> }. " +
@@ -6747,7 +6798,10 @@ const CONTRACT = deepFreeze({
   //    PaymentError codes.
   // 1.237.0: widening — `manifest.translations` may declare up to 500 keys
   //    (was 200).
-  version: "1.237.0",
+  // 1.238.0: additive (sc-15659) — `useConnector(connectorRef)` + the
+  //    `connectors` host client + the `connectorRef` propertySchema type + the
+  //    `connectors.call:*` scope. A widget calls a REST connector's listed operations.
+  version: "1.238.0",
   sharedTranslationKeys: SHARED_TRANSLATION_KEYS,
   hooks: HOOKS,
   primitives: PRIMITIVES,