@colixsystems/widget-sdk 0.78.0 → 0.80.0

package/README.md

@@ -26,6 +26,9 @@ The data layer lives in **four separate domain-client packages**, each instantia
 | **CORE** | `useWidgetEvent(name)` | `(payload?) => void` | `ctx.events.emit` — no scope |
 | **CORE** | `useChildRenderer()` | `{ renderNode(node) }` | `ctx.renderer` — no scope (prefer the `WidgetTree` component) |
 | **CORE** | `useFill()` | `boolean` | `ctx.fill` — no scope. `true` when the host sized this widget to fill its page-grid tile's reserved height (containers + media fill by default; the author can override per tile). Media-style widgets switch to a `flex: 1` / `height: "100%"` layout; others ignore it. Defaults `false`. |
+| **CORE** | `useContainerWidth()` | `[width, onLayout]` | No context slice, no scope. Measures the width the widget's OWN box has, so it can lay itself out for the space it is in rather than for the screen. Spread the handler onto your outermost primitive. Use it for any widget with a wide form and a narrow one (a table, a toolbar, a row of tiles) — never switch on the device or window width, because a widget in a one-of-three grid cell on desktop has phone-width room and a widget filling a phone page does not. Width is 0 until the first layout: render the WIDE form then. One implementation covers web (react-native-web) and the native export. |
+| **CORE** | `isNarrowWidth(width)` | `boolean` | No context slice, no scope. True when a MEASURED width is below `NARROW_WIDTH_PX` (480) — the one threshold every widget switches at, so a page reflows together rather than raggedly. An unmeasured width (0) is NOT narrow, so nothing flashes through the narrow form on first paint. |
+| **CORE** | `useSectionEmpty(isEmpty)` | `void` | `ctx.section.reportEmpty` — no scope. Declares that the widget has NO content to show, so the host drops its layout slot instead of reserving space (and its parent's `gap`) for it. Returning `null` is not enough: the host wraps every widget in an entrance element, so a widget rendering nothing still leaves an empty box the parent stack gaps around. For a CONDITIONALLY ABSENT section (a per-record child collection with no rows for this record), never to suppress a genuine empty state. Stays mounted while collapsed, so passing `false` brings it back. Authoring surfaces never collapse. No-op on a host that doesn't implement it. |
 | **CORE** | `useRefresh(handler)` | `void` | `ctx.refresh.subscribe` — no scope. Subscribes the handler to the page-level refresh tick (pull-to-refresh on mobile). Handler may return a Promise — the host waits for `allSettled` before clearing the spinner. The three datastore hooks auto-subscribe their own `refetch`; widgets only call this directly to re-run non-datastore work. No-op on a host that doesn't implement refresh. |
 | **CORE** | `useClipboard()` | `{ copy, paste, hasContent }` | platform clipboard (web `navigator.clipboard` / native `expo-clipboard`); rejects with `ClipboardError` — no scope |
 | **CORE** | `useToast()` | `{ showToast }` | `ctx.toast.showToast` (falls back to a CustomEvent / console) — no scope |
@@ -301,6 +304,10 @@ useEffect(() => {
 
 ### What's new in 0.41.0
 
+**New `useContainerWidth()` hook + `isNarrowWidth(width)` / `NARROW_WIDTH_PX` (sc-4399).** A widget can now measure the width of its OWN box and lay itself out for the space it is in. This is the capability that was missing for every widget except Gallery, which had hand-rolled the same `onLayout` measurement for its carousel — that copy is now gone and Gallery reads the hook. It matters because the screen is the wrong question: a widget in a one-of-three grid cell on a desktop page has phone-width room, and a widget filling a phone page does not, so a table-shaped widget that switches on the device is wrong in both directions. `isNarrowWidth` gives every widget one threshold (480) to switch at, so a page of them reflows together instead of raggedly, and an unmeasured width (0) is deliberately not narrow so nothing flashes through its narrow form on first paint. `onLayout` is a react-native primitive callback, so ONE implementation serves the web Player and the exported app. Additive — `CONTRACT.version` bumped to the next minor for two new hooks.
+
+**New `useSectionEmpty(isEmpty)` hook + optional `ctx.section` slice (sc-4416).** A widget can now tell the host it has no content to show, and the host removes its layout slot rather than reserving space for it. This closes a gap that `null` alone could not: the host wraps every widget node in an entrance element, so a widget that rendered nothing still left an empty box its parent stack put `gap` around — a dead band of whitespace exactly where the content would have been. It matters most for a per-record child collection (a policy detail page whose quiz section only exists for policies that have questions): the widget owns the rows, so only the widget can say, and `visibleWhen` cannot reach it because "has related rows" is not a field the record carries. The widget stays MOUNTED while collapsed, so when rows arrive it reports `false` and the section returns on its own — no measurement, no second pass. The slot (`ctx.section.reportEmpty`) is optional and deliberately omitted on authoring surfaces: on the Studio canvas and in the Agent Mode edit preview an empty widget must stay visible and selectable, or an absent section could never be edited. Additive — `CONTRACT.version` bumped to the next minor for a new hook plus a new optional context slice.
+
 **New `useRefresh(handler)` hook + page-level refresh signal (sc-1179).** Pull-to-refresh on the mobile web Player + the native Expo export's `RefreshControl` now fans a page-level refresh tick out to every widget on the page. The three datastore hooks — `useDatastoreQuery`, `useDatastoreRecord`, `useAsset` — auto-subscribe their own `refetch`, so a widget built on those hooks gets refreshed for free. Widgets that need to re-run other work (a third-party `fetch`, a derived calculation) call `useRefresh(async () => { … })` directly. The handler may return a Promise — the host waits on `Promise.allSettled` of every subscriber before clearing the spinner. The slot (`ctx.refresh.subscribe`) is optional on the WidgetContext: a host that does not implement refresh (the Studio canvas preview) simply omits it and the hook collapses to a no-op. Additive — `CONTRACT.version` bumped to the next minor since the contract grew a new hook + a new (optional) context slice.
 
 ### What's new in 0.40.2
@@ -630,7 +637,7 @@ A widget that works but looks unfinished is only half done. `useTheme()` is the
 - **Tint the supporting cast.** `colors.primarySoft` is a tint of the workspace accent over the surface and `colors.onPrimarySoft` is guaranteed readable on it (WCAG AA, on light and dark themes alike). Use the pair for chips, secondary buttons, progress tracks, icon badges and selected rows. One saturated accent moment surrounded by several pale echoes of the same hue is what reads as designed — a row of grey-outlined buttons reads as a form. Never hand-mix a tint with `rgba(...)` or a translucent overlay.
 - **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.
 - **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 `onLayout={(e) => setWidth(e.nativeEvent.layout.width)}` on the root `View` (a React Native primitive, so it behaves identically on both hosts), render nothing size-dependent while `width === 0`, and compute every threshold from the measured value: a widget gets no declared breakpoint prop, but it can always measure. **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 above ~720px measured width** (`flexDirection: width >= 720 ? '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.
-- **Compose forms — pair fields into rows, don't stack one per row.** 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, cap it at two–three per row, group a long form into labelled sections, and label every input above it (not placeholder-only).
+- **Compose forms — pair fields into rows, don't stack one per row.** 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, 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.
 - **Respond to touch.** Give every `Pressable` a pressed state via the function-style `style={({ pressed }) => [base, pressed && { opacity: 0.7 }]}`.
 - **Drag and drop — show what is being dragged.** 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`.
 - **Use icons for clarity.** Pair a `lucide-react-native` icon with its label at a consistent size, coloured from the theme. The label never repeats the icon as a character — with a `Plus` icon the button says "Add item", never "+ Add item" (that renders a doubled plus).

package/dist/container-width.js

@@ -0,0 +1,28 @@
+// sc-4399 — the narrow-form threshold, in its own dependency-free module.
+//
+// Deliberately NOT in hooks.js: that file's test harnesses load it through a
+// hand-rolled transform that only understands `export function`, so an
+// `export const` there breaks every hooks test at once. Keeping the constant
+// here also means a consumer that just wants the number pays no React import.
+//
+// `useContainerWidth` itself stays in hooks.js, where React is already
+// imported — it is the hook that measures; these two only classify.
+
+/**
+ * The width below which a widget should adopt its narrow form — a table
+ * becomes stacked label/value blocks, a toolbar wraps. ONE number so a page of
+ * widgets reflows together instead of raggedly.
+ */
+export const NARROW_WIDTH_PX = 480;
+
+/**
+ * True when a MEASURED width is below the threshold.
+ *
+ * An unmeasured width (0, before the first `onLayout`) is deliberately NOT
+ * narrow: the wide rendering is the historical one, so a widget that never
+ * lays out is unchanged, and no widget flashes through its narrow form on
+ * first paint.
+ */
+export function isNarrowWidth(width) {
+  return typeof width === "number" && width > 0 && width < NARROW_WIDTH_PX;
+}

package/dist/contract.cjs

@@ -358,6 +358,68 @@ const HOOKS = [
     requiredContextSlice: ["refresh.subscribe"],
     scopes: null,
   },
+  {
+    name: "useContainerWidth",
+    signature: "useContainerWidth()",
+    description:
+      "Measure the width the widget's OWN box has, so it can lay itself out " +
+      "for the space it is in rather than for the screen. Returns " +
+      "`[width, onLayout]`; spread the handler onto the widget's outermost " +
+      "primitive. A widget in a 1-of-3 grid cell on a desktop page has " +
+      "phone-width room while a widget filling a phone page does not, and the " +
+      "window width answers neither question — this is why a table-shaped " +
+      "widget must not switch on the device. `onLayout` is the react-native " +
+      "callback, so ONE implementation serves the web Player (through " +
+      "react-native-web) and the native export. Before the first layout the " +
+      "width is 0: treat that as \"not yet measured\" and render the wide " +
+      "form. Pair it with `isNarrowWidth(width)` so every widget switches at " +
+      "the same threshold. Takes no host context, so it is safe everywhere " +
+      "including the Studio canvas.",
+    returnShape: {
+      "(returns)": "[number, function]",
+    },
+    requiredContextSlice: [],
+    scopes: null,
+  },
+  {
+    name: "isNarrowWidth",
+    signature: "isNarrowWidth(width)",
+    description:
+      "True when a MEASURED width is below `NARROW_WIDTH_PX` (480), the one " +
+      "threshold at which a widget adopts its narrow form — a table becomes " +
+      "stacked cards, a toolbar wraps. One number so a page of widgets " +
+      "reflows together instead of raggedly. An unmeasured width (0) is " +
+      "deliberately NOT narrow, so a widget that never lays out keeps its " +
+      "historical wide rendering.",
+    returnShape: {
+      "(returns)": "boolean",
+    },
+    requiredContextSlice: [],
+    scopes: null,
+  },
+  {
+    name: "useSectionEmpty",
+    signature: "useSectionEmpty(isEmpty)",
+    description:
+      "Declare that this widget currently has NO content to show, so the host " +
+      "removes its layout slot instead of reserving space for it. Returning " +
+      "null is NOT enough on its own: the host wraps every widget node in an " +
+      "entrance wrapper, so a widget that renders nothing still leaves an " +
+      "empty box its parent stack puts `gap` around — a dead band of " +
+      "whitespace where the content would have been. Only the widget has the " +
+      "rows, so only the widget can say. Use it for a CONDITIONALLY ABSENT " +
+      "section (a per-record child collection with no rows for the record " +
+      "being viewed), never to suppress a genuine empty state a user is " +
+      "expected to fill. The widget stays mounted while collapsed, so passing " +
+      "false later brings the section back. Authoring surfaces (Studio canvas, " +
+      "Agent Mode edit preview) never collapse, so an absent section stays " +
+      "editable. Safe on a host that does not implement it — a no-op there.",
+    returnShape: {
+      "(returns)": "void",
+    },
+    requiredContextSlice: ["section.reportEmpty"],
+    scopes: null,
+  },
   {
     name: "useNavigation",
     signature: "useNavigation()",
@@ -1438,6 +1500,21 @@ const WIDGET_CONTEXT_SHAPE = {
     required: false,
     fields: { subscribe: "function" },
   },
+  // sc-4416 — widget -> host emptiness signal. The widget owns the knowledge
+  // (it has the rows); the host owns the spacing (the slot and its gap).
+  // Optional so an AUTHORING host can omit it on purpose: with no slice the
+  // hook is a no-op and an empty widget stays visible and selectable on the
+  // Studio canvas and in the Agent Mode edit preview.
+  section: {
+    description:
+      "Optional layout-slot slot. { reportEmpty(isEmpty) }. Called by the " +
+      "widget when it has no content to show; the host then drops the node's " +
+      "layout slot so its parent stack puts no gap around it. Backs " +
+      "useSectionEmpty(). Omitted on authoring surfaces, where an empty " +
+      "widget must stay visible.",
+    required: false,
+    fields: { reportEmpty: "function" },
+  },
   events: {
     description: "{ emit(name, payload) }.",
     required: true,
@@ -2368,7 +2445,15 @@ const CONTRACT = deepFreeze({
   //    public endpoint instead, which skips the cache, the metering and the
   //    workspace's provider. Publishing the host list here keeps the linter,
   //    the Developer guide and the agent prompt reading one source.
-  version: "1.52.0",
+  // 1.54.0: additive (sc-4399, epic 4395) — `useContainerWidth()` +
+  //    `isNarrowWidth(width)` / `NARROW_WIDTH_PX`. Built-in widgets laid
+  //    themselves out at a fixed size — UserManagement's rows alone carried
+  //    ~800px of minWidth — so a page that reflowed around them still
+  //    overflowed, because the widget inside demanded desktop width. Gallery
+  //    already measured its own box with onLayout; this promotes that one
+  //    pattern to the SDK so custom and marketplace widgets get it too,
+  //    instead of each rolling its own.
+  version: "1.54.0",
   sharedTranslationKeys: SHARED_TRANSLATION_KEYS,
   hooks: HOOKS,
   primitives: PRIMITIVES,

package/dist/contract.js

@@ -358,6 +358,68 @@ const HOOKS = [
     requiredContextSlice: ["refresh.subscribe"],
     scopes: null,
   },
+  {
+    name: "useContainerWidth",
+    signature: "useContainerWidth()",
+    description:
+      "Measure the width the widget's OWN box has, so it can lay itself out " +
+      "for the space it is in rather than for the screen. Returns " +
+      "`[width, onLayout]`; spread the handler onto the widget's outermost " +
+      "primitive. A widget in a 1-of-3 grid cell on a desktop page has " +
+      "phone-width room while a widget filling a phone page does not, and the " +
+      "window width answers neither question — this is why a table-shaped " +
+      "widget must not switch on the device. `onLayout` is the react-native " +
+      "callback, so ONE implementation serves the web Player (through " +
+      "react-native-web) and the native export. Before the first layout the " +
+      "width is 0: treat that as \"not yet measured\" and render the wide " +
+      "form. Pair it with `isNarrowWidth(width)` so every widget switches at " +
+      "the same threshold. Takes no host context, so it is safe everywhere " +
+      "including the Studio canvas.",
+    returnShape: {
+      "(returns)": "[number, function]",
+    },
+    requiredContextSlice: [],
+    scopes: null,
+  },
+  {
+    name: "isNarrowWidth",
+    signature: "isNarrowWidth(width)",
+    description:
+      "True when a MEASURED width is below `NARROW_WIDTH_PX` (480), the one " +
+      "threshold at which a widget adopts its narrow form — a table becomes " +
+      "stacked cards, a toolbar wraps. One number so a page of widgets " +
+      "reflows together instead of raggedly. An unmeasured width (0) is " +
+      "deliberately NOT narrow, so a widget that never lays out keeps its " +
+      "historical wide rendering.",
+    returnShape: {
+      "(returns)": "boolean",
+    },
+    requiredContextSlice: [],
+    scopes: null,
+  },
+  {
+    name: "useSectionEmpty",
+    signature: "useSectionEmpty(isEmpty)",
+    description:
+      "Declare that this widget currently has NO content to show, so the host " +
+      "removes its layout slot instead of reserving space for it. Returning " +
+      "null is NOT enough on its own: the host wraps every widget node in an " +
+      "entrance wrapper, so a widget that renders nothing still leaves an " +
+      "empty box its parent stack puts `gap` around — a dead band of " +
+      "whitespace where the content would have been. Only the widget has the " +
+      "rows, so only the widget can say. Use it for a CONDITIONALLY ABSENT " +
+      "section (a per-record child collection with no rows for the record " +
+      "being viewed), never to suppress a genuine empty state a user is " +
+      "expected to fill. The widget stays mounted while collapsed, so passing " +
+      "false later brings the section back. Authoring surfaces (Studio canvas, " +
+      "Agent Mode edit preview) never collapse, so an absent section stays " +
+      "editable. Safe on a host that does not implement it — a no-op there.",
+    returnShape: {
+      "(returns)": "void",
+    },
+    requiredContextSlice: ["section.reportEmpty"],
+    scopes: null,
+  },
   {
     name: "useNavigation",
     signature: "useNavigation()",
@@ -1438,6 +1500,21 @@ const WIDGET_CONTEXT_SHAPE = {
     required: false,
     fields: { subscribe: "function" },
   },
+  // sc-4416 — widget -> host emptiness signal. The widget owns the knowledge
+  // (it has the rows); the host owns the spacing (the slot and its gap).
+  // Optional so an AUTHORING host can omit it on purpose: with no slice the
+  // hook is a no-op and an empty widget stays visible and selectable on the
+  // Studio canvas and in the Agent Mode edit preview.
+  section: {
+    description:
+      "Optional layout-slot slot. { reportEmpty(isEmpty) }. Called by the " +
+      "widget when it has no content to show; the host then drops the node's " +
+      "layout slot so its parent stack puts no gap around it. Backs " +
+      "useSectionEmpty(). Omitted on authoring surfaces, where an empty " +
+      "widget must stay visible.",
+    required: false,
+    fields: { reportEmpty: "function" },
+  },
   events: {
     description: "{ emit(name, payload) }.",
     required: true,
@@ -2368,7 +2445,15 @@ const CONTRACT = deepFreeze({
   //    public endpoint instead, which skips the cache, the metering and the
   //    workspace's provider. Publishing the host list here keeps the linter,
   //    the Developer guide and the agent prompt reading one source.
-  version: "1.52.0",
+  // 1.54.0: additive (sc-4399, epic 4395) — `useContainerWidth()` +
+  //    `isNarrowWidth(width)` / `NARROW_WIDTH_PX`. Built-in widgets laid
+  //    themselves out at a fixed size — UserManagement's rows alone carried
+  //    ~800px of minWidth — so a page that reflowed around them still
+  //    overflowed, because the widget inside demanded desktop width. Gallery
+  //    already measured its own box with onLayout; this promotes that one
+  //    pattern to the SDK so custom and marketplace widgets get it too,
+  //    instead of each rolling its own.
+  version: "1.54.0",
   sharedTranslationKeys: SHARED_TRANSLATION_KEYS,
   hooks: HOOKS,
   primitives: PRIMITIVES,

package/dist/hooks.js

@@ -242,6 +242,85 @@ export function useRefresh(handler) {
   }, []);
 }
 
+/**
+ * sc-4416 — declare that this widget currently has NO content to show, so the
+ * host removes its layout slot instead of reserving space for it.
+ *
+ *   const { data: rows } = useDatastoreQuery(props.tableId, query);
+ *   useSectionEmpty(rows.length === 0);
+ *   if (rows.length === 0) return null;
+ *
+ * Returning `null` is not enough on its own. The host wraps every widget node
+ * in an element (the mount-time entrance wrapper), so a widget that renders
+ * nothing still leaves an empty box that its parent stack puts `gap` around —
+ * a dead band of whitespace exactly where the content would have been. This
+ * hook is how the widget tells the host to collapse that slot; nothing else
+ * can know, because only the widget has the rows.
+ *
+ * Reach for it whenever a section is CONDITIONALLY ABSENT — a per-record child
+ * collection with no rows for the record being viewed (a policy with no quiz
+ * questions), a panel that only applies to some states. Do NOT use it to hide
+ * a genuine empty state: a list the user is expected to fill should still say
+ * "Nothing here yet" so the page does not look broken.
+ *
+ * The widget stays MOUNTED while collapsed, so when rows do arrive it simply
+ * calls `useSectionEmpty(false)` on the next render and the section reappears.
+ * Call it unconditionally (it is a hook) and let the argument carry the state.
+ *
+ * Authoring surfaces never collapse — the Studio canvas and the Agent Mode
+ * edit preview keep an empty widget visible and selectable, or an absent
+ * section could not be edited. Safe to call on a host that does not implement
+ * it: the hook collapses to a no-op.
+ */
+export function useSectionEmpty(isEmpty) {
+  const ctx = useWidgetContextOrThrow("useSectionEmpty");
+  const report = ctx.section && ctx.section.reportEmpty;
+  const reportRef = useRef(report);
+  reportRef.current = report;
+  const empty = isEmpty === true;
+  useEffect(() => {
+    const fn = reportRef.current;
+    if (typeof fn !== "function") return undefined;
+    fn(empty);
+    // No cleanup on change — releasing the collapse before re-declaring it
+    // would flash the reserved slot back in between the two renders. The host
+    // drops its per-node state when the node unmounts.
+    return undefined;
+  }, [empty]);
+}
+
+/**
+ * sc-4399 — measure the width the widget's own box actually has, so it can lay
+ * itself out for the space it is in rather than for the screen. A widget in a
+ * 1-of-3 grid cell on a desktop page has phone-width room; a widget filling a
+ * phone page does not. The window width answers neither question.
+ *
+ * Spread the returned handler onto the widget's outermost primitive:
+ *
+ *   const [width, onLayout] = useContainerWidth();
+ *   return <View onLayout={onLayout}>{isNarrowWidth(width) ? <Cards/> : <Table/>}</View>;
+ *
+ * `onLayout` is the react-native primitive callback, so ONE implementation
+ * serves the web Player (through react-native-web) and the native export.
+ * Before the first layout the width is 0 — treat that as "not yet measured"
+ * and render the wide form, which is what `isNarrowWidth`
+ * (./container-width.js) does.
+ *
+ * Takes no context, so it is safe on every host including the Studio canvas.
+ */
+export function useContainerWidth() {
+  const [width, setWidth] = useState(0);
+  const onLayout = useCallback((event) => {
+    const next =
+      event && event.nativeEvent && event.nativeEvent.layout
+        ? event.nativeEvent.layout.width
+        : undefined;
+    if (typeof next !== "number" || !(next > 0)) return;
+    setWidth((prev) => (prev === next ? prev : next));
+  }, []);
+  return [width, onLayout];
+}
+
 /**
  * Returns the host-provided navigation surface:
  *   `{ goTo, goBack, push, replace, back, currentRoute }`.

package/dist/index.d.ts

@@ -1096,6 +1096,48 @@ export function useRefresh(
   handler: () => void | Promise<unknown>,
 ): void;
 
+/**
+ * sc-4416 — declare that this widget currently has NO content to show, so the
+ * host removes its layout slot rather than reserving space for it.
+ *
+ * Returning `null` alone is not enough: the host wraps every widget node in an
+ * entrance wrapper, so a widget rendering nothing still leaves an empty box
+ * that its parent stack puts `gap` around. Use it for a CONDITIONALLY ABSENT
+ * section (a per-record child collection with no rows for this record), never
+ * to suppress a genuine empty state. The widget stays mounted while collapsed,
+ * so passing `false` later brings the section back. Authoring surfaces never
+ * collapse. Safe on a host that does not implement it — a no-op there.
+ */
+export function useSectionEmpty(isEmpty: boolean): void;
+
+/** The layout event a react-native primitive passes to `onLayout`. */
+export interface WidgetLayoutEvent {
+  nativeEvent: { layout: { width: number; height: number; x: number; y: number } };
+}
+
+/**
+ * sc-4399 — measure the width the widget's OWN box has, so it can lay itself
+ * out for the space it is in rather than for the screen. Spread the returned
+ * handler onto the widget's outermost primitive; ONE implementation serves the
+ * web Player (via react-native-web) and the native export. The width is 0
+ * before the first layout — treat that as "not yet measured" and render the
+ * wide form, which is what `isNarrowWidth` does.
+ */
+export function useContainerWidth(): [
+  number,
+  (event: WidgetLayoutEvent) => void,
+];
+
+/** The width below which a widget should adopt its narrow form (480). */
+export const NARROW_WIDTH_PX: number;
+
+/**
+ * True when a MEASURED width is below `NARROW_WIDTH_PX`. An unmeasured width
+ * (0) is deliberately NOT narrow, so a widget that never lays out keeps its
+ * historical wide rendering.
+ */
+export function isNarrowWidth(width: number): boolean;
+
 /** Pass-through options for `useGeolocation().getCurrentPosition(...)`. */
 export interface GeolocationOptions {
   enableHighAccuracy?: boolean;

package/dist/index.js

@@ -50,10 +50,13 @@ export {
   usePageContext,
   useChildRenderer,
   useRefresh,
+  useSectionEmpty,
+  useContainerWidth,
   useGeolocation,
   GeolocationError,
   WidgetTree,
 } from "./hooks.js";
+export { isNarrowWidth, NARROW_WIDTH_PX } from "./container-width.js";
 // REQ-WSDK-PLATFORM §6 — Tier A hooks. Each ships in a per-platform file
 // (./clipboard.js / .native.js, ./toast.js / .native.js); index.js picks
 // the web variant and index.native.js picks the native variant.

package/dist/index.native.js

@@ -50,10 +50,13 @@ export {
   usePageContext,
   useChildRenderer,
   useRefresh,
+  useSectionEmpty,
+  useContainerWidth,
   useGeolocation,
   GeolocationError,
   WidgetTree,
 } from "./hooks.js";
+export { isNarrowWidth, NARROW_WIDTH_PX } from "./container-width.js";
 // REQ-WSDK-PLATFORM §6 — Tier A hooks (native variants).
 export { useClipboard, ClipboardError } from "./clipboard.native.js";
 export { useToast } from "./toast.native.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@colixsystems/widget-sdk",
-  "version": "0.78.0",
+  "version": "0.80.0",
   "description": "Common widget interface for AppStudio. Implements WidgetManifest, WidgetContext, property schema, and helper hooks.",
   "type": "module",
   "main": "./dist/index.js",
@@ -48,7 +48,7 @@
   ],
   "scripts": {
     "build": "node scripts/build.js",
-    "test": "node --test src/__tests__/contract.test.js src/__tests__/hooks-users.test.js src/__tests__/hooks-groups.test.js src/__tests__/hooks-schema.test.js src/__tests__/hooks-assets-by-tag.test.js src/__tests__/hooks-filestore-upload.test.js src/__tests__/hooks-filestore-file.test.js src/__tests__/hooks-mutation.test.js src/__tests__/hooks-record-permissions.test.js src/__tests__/hooks-geolocation.test.js src/__tests__/hooks-identification.test.js src/__tests__/hooks-subscription.test.js src/__tests__/hooks-volatile-query-key.test.js src/__tests__/linter-users-scope.test.js src/__tests__/linter-comments.test.js src/__tests__/linter-translation-api.test.js src/__tests__/linter-image-height.test.js src/__tests__/linter-platform.test.js src/__tests__/linter-react-import.test.js src/__tests__/lucide-icon-names.test.js src/__tests__/lucideIconName.test.js src/__tests__/manifest-actions.test.js src/__tests__/widget-translations.test.js src/__tests__/hooks-translate.test.js src/__tests__/devserver.test.js src/__tests__/host-externals.test.js src/__tests__/datetimepicker.test.js src/__tests__/property-schema-resolve.test.js src/__tests__/theme-components-parity.test.js src/__tests__/theme-depth-tokens.test.js"
+    "test": "node --test src/__tests__/contract.test.js src/__tests__/hooks-users.test.js src/__tests__/hooks-groups.test.js src/__tests__/hooks-schema.test.js src/__tests__/hooks-assets-by-tag.test.js src/__tests__/hooks-filestore-upload.test.js src/__tests__/hooks-filestore-file.test.js src/__tests__/hooks-mutation.test.js src/__tests__/hooks-record-permissions.test.js src/__tests__/hooks-geolocation.test.js src/__tests__/hooks-section-empty.test.js src/__tests__/hooks-identification.test.js src/__tests__/hooks-subscription.test.js src/__tests__/hooks-volatile-query-key.test.js src/__tests__/linter-users-scope.test.js src/__tests__/linter-comments.test.js src/__tests__/linter-translation-api.test.js src/__tests__/linter-image-height.test.js src/__tests__/linter-platform.test.js src/__tests__/linter-react-import.test.js src/__tests__/lucide-icon-names.test.js src/__tests__/lucideIconName.test.js src/__tests__/manifest-actions.test.js src/__tests__/widget-translations.test.js src/__tests__/hooks-translate.test.js src/__tests__/devserver.test.js src/__tests__/host-externals.test.js src/__tests__/datetimepicker.test.js src/__tests__/property-schema-resolve.test.js src/__tests__/theme-components-parity.test.js src/__tests__/theme-depth-tokens.test.js"
   },
   "engines": {
     "node": ">=18"