@colixsystems/widget-sdk 0.219.0 → 0.219.1

package/README.md

@@ -32,7 +32,7 @@ The data layer lives in **four separate domain-client packages**, each instantia
 | **CORE** | `useWidgetEvent(name)` | `(payload?) => void` | `ctx.events.emit` — no scope. The hook IS the emitter: `const emitSlot = useWidgetEvent("slotChosen")`, then `emitSlot(payload)`. Never destructure the result — there is no `emit` member. A sibling's input reads the payload, and a page action the author binds to the event (Run action, Navigate) runs with it — fired from one control, only that control runs it. |
 | **CORE** | `useWidgetInput(inputName)` | the published payload, or `undefined` | `ctx.inputs` — no scope. Reads a value ANOTHER widget on the same page published with `useWidgetEvent`. Declare the input in `manifest.inputs`; the page author wires it to one sibling's declared event. The channel retains the last payload, so a widget that mounts later still reads it. `undefined` while unwired or before the first publish — always render a sensible default. Page-scoped and ephemeral: use `useRouteParams()` for state that must survive navigation, the datastore for state that must persist. |
 | **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** | `useFill()` | `boolean` | `ctx.fill` — no scope. `true` when the host sized this widget to fill a box of definite height: a widget in the section a fit-to-screen page stretches to the bottom of the screen, or one given a fixed slot height. Media-style widgets, and a chat or feed that scrolls its own content, switch to a `flex: 1` / `height: "100%"` layout and scroll inside it; 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** | `widthTier(width)` | `"narrow" \| "medium" \| "wide"` | No context slice, no scope. Which of THREE layouts a measured width calls for: narrow below `NARROW_WIDTH_PX` (480), wide at or above `WIDE_WIDTH_PX` (960), medium between. `widthTier(w) === "narrow"` exactly when `isNarrowWidth(w)`; an unmeasured width (0) is "wide". |
@@ -83,7 +83,11 @@ See the design reference for the full architecture: [`docs/architecture/widget-m
 
 ## Status
 
-`v0.219.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.219.1` — 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.219.1
+
+**`useFill()` says when it is true today.** It described a page-grid tile with a "Fill tile height" choice, a layout that no longer exists. A host now fills a widget in two cases: the widget sits in the section a fit-to-screen page stretches to the bottom of the screen, or the widget has a fixed slot height. A chat or feed that scrolls its own content is one of the widgets that should honour it. A documentation correction; `CONTRACT.version` is unchanged.
 
 ### What's new in 0.219.0 (contract 1.175.0)
 

package/dist/contract.cjs

@@ -942,13 +942,14 @@ const HOOKS = [
     name: "useFill",
     signature: "useFill()",
     description:
-      "Returns true when the host has sized this widget to fill its layout " +
-      'slot\'s available height — a page-grid tile whose author chose "Fill ' +
-      'tile height", or a widget type that fills by default (containers and ' +
-      "media). When true, a widget that has a meaningful filled form (Image, " +
-      "Chart, Map, Video) should switch from its intrinsic height to a stretch " +
-      'style (flex: 1 / height: "100%"); widgets with no useful filled form ' +
-      "may ignore it. Defaults to false wherever the host has not opted the " +
+      "Returns true when the host has sized this widget to fill a box of " +
+      "definite height — a widget in the section a fit-to-screen page " +
+      "stretches to the bottom of the screen, or a widget given a fixed slot " +
+      "height. When true, a widget that has a meaningful filled form (Image, " +
+      "Chart, Map, Video, a chat or feed that scrolls its own content) should " +
+      "switch from its intrinsic height to a stretch style (flex: 1 / " +
+      'height: "100%") and scroll inside it; widgets with no useful filled ' +
+      "form may ignore it. Defaults to false wherever the host has not opted the " +
       "widget into filling, so calling it is always safe. The SAME value is " +
       "injected by the web Player and the native export (widget-parity skill), so a " +
       "widget's fill behaviour is identical on both platforms.",
@@ -3549,15 +3550,16 @@ const WIDGET_CONTEXT_SHAPE = {
     },
   },
   // REQ-LAY-08 — optional host layout hint backing useFill(). True when the
-  // host sized this widget to fill its layout slot's available height (a
-  // page-grid tile set to "Fill tile height", or a default-fill widget type).
+  // host sized this widget to fill a box of definite height (a fit-to-screen
+  // page's stretched section, or a fixed slot height).
   // Optional: a host that never fills a widget simply omits it and useFill()
   // returns false, so existing hosts need no change.
   fill: {
     description:
       "Optional host layout hint (boolean). True when the host sized this " +
-      "widget to fill its layout slot's available height (page-grid tile " +
-      "fill). Backs useFill(); defaults to false when absent.",
+      "widget to fill a box of definite height (a fit-to-screen page's " +
+      "stretched section, or a fixed slot height). Backs useFill(); defaults " +
+      "to false when absent.",
     required: false,
     fields: {},
   },

package/dist/contract.js

@@ -942,13 +942,14 @@ const HOOKS = [
     name: "useFill",
     signature: "useFill()",
     description:
-      "Returns true when the host has sized this widget to fill its layout " +
-      'slot\'s available height — a page-grid tile whose author chose "Fill ' +
-      'tile height", or a widget type that fills by default (containers and ' +
-      "media). When true, a widget that has a meaningful filled form (Image, " +
-      "Chart, Map, Video) should switch from its intrinsic height to a stretch " +
-      'style (flex: 1 / height: "100%"); widgets with no useful filled form ' +
-      "may ignore it. Defaults to false wherever the host has not opted the " +
+      "Returns true when the host has sized this widget to fill a box of " +
+      "definite height — a widget in the section a fit-to-screen page " +
+      "stretches to the bottom of the screen, or a widget given a fixed slot " +
+      "height. When true, a widget that has a meaningful filled form (Image, " +
+      "Chart, Map, Video, a chat or feed that scrolls its own content) should " +
+      "switch from its intrinsic height to a stretch style (flex: 1 / " +
+      'height: "100%") and scroll inside it; widgets with no useful filled ' +
+      "form may ignore it. Defaults to false wherever the host has not opted the " +
       "widget into filling, so calling it is always safe. The SAME value is " +
       "injected by the web Player and the native export (widget-parity skill), so a " +
       "widget's fill behaviour is identical on both platforms.",
@@ -3545,15 +3546,16 @@ const WIDGET_CONTEXT_SHAPE = {
     },
   },
   // REQ-LAY-08 — optional host layout hint backing useFill(). True when the
-  // host sized this widget to fill its layout slot's available height (a
-  // page-grid tile set to "Fill tile height", or a default-fill widget type).
+  // host sized this widget to fill a box of definite height (a fit-to-screen
+  // page's stretched section, or a fixed slot height).
   // Optional: a host that never fills a widget simply omits it and useFill()
   // returns false, so existing hosts need no change.
   fill: {
     description:
       "Optional host layout hint (boolean). True when the host sized this " +
-      "widget to fill its layout slot's available height (page-grid tile " +
-      "fill). Backs useFill(); defaults to false when absent.",
+      "widget to fill a box of definite height (a fit-to-screen page's " +
+      "stretched section, or a fixed slot height). Backs useFill(); defaults " +
+      "to false when absent.",
     required: false,
     fields: {},
   },

package/dist/hooks.js

@@ -392,14 +392,15 @@ export function useUserPhoto() {
 }
 
 /**
- * Returns `true` when the host has sized this widget to fill the available
- * height of its layout slot — today that means a page-grid tile whose author
- * chose "Fill tile height" (or a widget type that fills by default, like
- * containers and media). When `true`, a widget that has a meaningful filled
- * form (Image, Chart, Map, Video, …) should switch from its intrinsic height
- * to a stretch style (`flex: 1` / `height: "100%"`); widgets with no useful
- * filled form may ignore it. Defaults to `false` everywhere the host has not
- * opted the widget into filling, so calling it is always safe.
+ * Returns `true` when the host has sized this widget to fill a box of
+ * definite height — a widget in the section a fit-to-screen page stretches to
+ * the bottom of the screen, or a widget given a fixed slot height. When
+ * `true`, a widget that has a meaningful filled form (Image, Chart, Map,
+ * Video, a chat or feed that scrolls its own content, …) should switch from
+ * its intrinsic height to a stretch style (`flex: 1` / `height: "100%"`) and
+ * scroll inside it; widgets with no useful filled form may ignore it.
+ * Defaults to `false` everywhere the host has not opted the widget into
+ * filling, so calling it is always safe.
  *
  * The SAME value is injected by the web Player host and the native export
  * host (widget-parity skill), so a widget's fill behaviour is identical on both

package/dist/index.d.ts

@@ -728,8 +728,8 @@ export interface WidgetContext<TProps = unknown> {
   };
   /**
    * REQ-LAY-08 — optional host layout hint backing `useFill()`. `true` when
-   * the host sized this widget to fill its layout slot's available height (a
-   * page-grid tile set to "Fill tile height", or a default-fill widget type).
+   * the host sized this widget to fill a box of definite height (a
+   * fit-to-screen page's stretched section, or a fixed slot height).
    * Absent / `false` everywhere the host has not opted the widget into filling.
    */
   fill?: boolean;
@@ -1948,11 +1948,13 @@ export interface UserPhotoApi {
 export function useUserPhoto(): UserPhotoApi;
 
 /**
- * REQ-LAY-08 — returns `true` when the host has sized this widget to fill its
- * layout slot's available height (a page-grid tile set to "Fill tile height",
- * or a default-fill widget type — containers + media). Widgets that can
- * stretch (Image, Chart, Map, Video, …) should switch to a fill style
- * (`flex: 1` / `height: "100%"`) when this is `true`; others may ignore it.
+ * REQ-LAY-08 — returns `true` when the host has sized this widget to fill a
+ * box of definite height (a widget in the section a fit-to-screen page
+ * stretches to the bottom of the screen, or one given a fixed slot height).
+ * Widgets that can stretch (Image, Chart, Map, Video, a chat or feed that
+ * scrolls itself, …) should switch to a fill style (`flex: 1` /
+ * `height: "100%"`) and scroll inside it when this is `true`; others may
+ * ignore it.
  * Defaults to `false`, so calling it is always safe, and the same value is
  * injected on web and native so fill behaviour is identical on both platforms.
  */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@colixsystems/widget-sdk",
-  "version": "0.219.0",
+  "version": "0.219.1",
   "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

@@ -942,13 +942,14 @@ const HOOKS = [
     name: "useFill",
     signature: "useFill()",
     description:
-      "Returns true when the host has sized this widget to fill its layout " +
-      'slot\'s available height — a page-grid tile whose author chose "Fill ' +
-      'tile height", or a widget type that fills by default (containers and ' +
-      "media). When true, a widget that has a meaningful filled form (Image, " +
-      "Chart, Map, Video) should switch from its intrinsic height to a stretch " +
-      'style (flex: 1 / height: "100%"); widgets with no useful filled form ' +
-      "may ignore it. Defaults to false wherever the host has not opted the " +
+      "Returns true when the host has sized this widget to fill a box of " +
+      "definite height — a widget in the section a fit-to-screen page " +
+      "stretches to the bottom of the screen, or a widget given a fixed slot " +
+      "height. When true, a widget that has a meaningful filled form (Image, " +
+      "Chart, Map, Video, a chat or feed that scrolls its own content) should " +
+      "switch from its intrinsic height to a stretch style (flex: 1 / " +
+      'height: "100%") and scroll inside it; widgets with no useful filled ' +
+      "form may ignore it. Defaults to false wherever the host has not opted the " +
       "widget into filling, so calling it is always safe. The SAME value is " +
       "injected by the web Player and the native export (widget-parity skill), so a " +
       "widget's fill behaviour is identical on both platforms.",
@@ -3545,15 +3546,16 @@ const WIDGET_CONTEXT_SHAPE = {
     },
   },
   // REQ-LAY-08 — optional host layout hint backing useFill(). True when the
-  // host sized this widget to fill its layout slot's available height (a
-  // page-grid tile set to "Fill tile height", or a default-fill widget type).
+  // host sized this widget to fill a box of definite height (a fit-to-screen
+  // page's stretched section, or a fixed slot height).
   // Optional: a host that never fills a widget simply omits it and useFill()
   // returns false, so existing hosts need no change.
   fill: {
     description:
       "Optional host layout hint (boolean). True when the host sized this " +
-      "widget to fill its layout slot's available height (page-grid tile " +
-      "fill). Backs useFill(); defaults to false when absent.",
+      "widget to fill a box of definite height (a fit-to-screen page's " +
+      "stretched section, or a fixed slot height). Backs useFill(); defaults " +
+      "to false when absent.",
     required: false,
     fields: {},
   },