@colixsystems/widget-sdk 0.142.1 → 0.143.0

package/README.md

@@ -32,6 +32,7 @@ The data layer lives in **four separate domain-client packages**, each instantia
 | **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** | `useScreenTitle(title)` | `void` | `ctx.screen.reportTitle` — no scope. Names the screen the widget is on, so the host paints that name in the app header beside the back control instead of the app brand. The page's own name is the default; only the widget knows the screen is really "Order #1423" rather than "Orders". The MOST RECENT call wins — with several widgets on one screen the last to report owns the title, and on unmount (or an empty title) the host falls back to the most recent surviving report and finally to the page name. Only a screen showing the back control paints a title; a root page keeps the brand. 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` — wired by the Player and the Expo export; an authoring preview omits it and the call is a no-op — no scope |
@@ -70,7 +71,22 @@ See the design reference for the full architecture: [`docs/architecture/widget-m
 
 ## Status
 
-`v0.142.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.143.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.143.0 (contract 1.111.0)
+
+**A widget can name the screen it is on — `useScreenTitle(title)` + the optional `ctx.screen` slice (sc-7955).** The app header now shows the PAGE title beside the back control on a sub-page, instead of repeating the app brand on every screen. The page's own name is the default, but a page is often about one record, and only the widget has it:
+
+```js
+const { data: order } = useDatastoreRecord(tableId, recordId);
+useScreenTitle(order ? `Order #${order.reference}` : null);
+```
+
+- The header reads "Order #1423" rather than "Orders" as soon as the record lands; before it does, the blank title leaves the page name standing (only a non-empty string registers).
+- `reportTitle` returns a release function, so the title reverts cleanly when the widget unmounts or its title empties.
+- **The most recent call wins.** With two title-setting widgets on one screen the last to report owns the header; when it goes, the host falls back to the most recent surviving report, then to the page name.
+- Only a screen that shows the back control paints a title — a root/menu page keeps the app brand or logo untouched.
+- Optional slice: on the Studio canvas and the Agent Mode edit preview there is no app header, so the hook is a no-op rather than an error.
 
 ### What's new in 0.142.1
 

package/dist/contract.cjs

@@ -718,6 +718,26 @@ const HOOKS = [
     requiredContextSlice: ["section.reportEmpty"],
     scopes: null,
   },
+  {
+    name: "useScreenTitle",
+    signature: "useScreenTitle(title)",
+    description:
+      "Name the screen this widget is on, so the host paints that name in the " +
+      "app header beside the back control. The page's own name is the default; " +
+      "only the widget knows when the screen is really \"Order #1423\" rather " +
+      "than \"Orders\". The MOST RECENT call wins: with several widgets on one " +
+      "screen the last to report owns the title, and when that widget unmounts " +
+      "(or passes an empty title) the host falls back to the most recent " +
+      "surviving report and finally to the page name. Only a screen that shows " +
+      "the back control paints a title — a root page keeps the app brand, so a " +
+      "title reported there is held but not shown. Safe on a host that does not " +
+      "implement it (Studio canvas, Agent Mode edit preview) — a no-op there.",
+    returnShape: {
+      "(returns)": "void",
+    },
+    requiredContextSlice: ["screen.reportTitle"],
+    scopes: null,
+  },
   {
     name: "useNavigation",
     signature: "useNavigation()",
@@ -2321,6 +2341,22 @@ const WIDGET_CONTEXT_SHAPE = {
     required: false,
     fields: { subscribe: "function" },
   },
+  // sc-7955 — widget -> host screen-chrome signal. The widget owns the knowledge
+  // (it has the record), the host owns the chrome (the header title slot).
+  // Optional so an AUTHORING host can omit it: with no slice the hook is a
+  // no-op on the Studio canvas and the Agent Mode edit preview, neither of
+  // which paints an app header at all.
+  screen: {
+    description:
+      "Optional screen-chrome slot. { reportTitle(title) -> release }. " +
+      "Registers this widget's title for the screen it is on and returns a " +
+      "release function that withdraws it; the host paints the most recently " +
+      "registered title in the header beside the back control and falls back " +
+      "to the page name once every registration is released. Backs " +
+      "useScreenTitle().",
+    required: false,
+    fields: { reportTitle: "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
@@ -3983,6 +4019,14 @@ const CONTRACT = deepFreeze({
   //    and the sc-7352 backfill deletes the stored key (a bottom-tabs app's
   //    strip becomes the sidebar's quick bar) BEFORE this ships.
   //    `menuItemCap` / `quickBarCap` keep their signatures.
+  // 1.111.0: additive (sc-7955) -- `screen` joins `widgetContextShape` and
+  //    `useScreenTitle(title)` joins `hooks`: a widget names the screen it is
+  //    on, and the host paints that name in the header beside the back control
+  //    instead of the app brand. `reportTitle` returns a release function; the
+  //    MOST RECENT registration wins and the host falls back to the most recent
+  //    surviving one, then to the page name. The slice is OPTIONAL, so an
+  //    authoring host (Studio canvas, Agent Mode edit preview) omits it and the
+  //    hook is a no-op there rather than an error.
   // 1.110.0: additive (sc-7885) — `triggeredBy` joins `actionScriptGlobals`:
   //    WHO initiated this run, as `{ type, id, name, email, role }`, or `null`
   //    on `schedule` / `record_*` where nothing did. `type` is `"app_user"` (an
@@ -3992,7 +4036,7 @@ const CONTRACT = deepFreeze({
   //    integration identity; this describes the caller, it does not grant
   //    anything. The same commit adds `properties` to this list, which the
   //    action-sdk copy had carried since 1.50.0 while this one had not.
-  version: "1.110.0",
+  version: "1.111.0",
   sharedTranslationKeys: SHARED_TRANSLATION_KEYS,
   hooks: HOOKS,
   primitives: PRIMITIVES,

package/dist/contract.js

@@ -718,6 +718,26 @@ const HOOKS = [
     requiredContextSlice: ["section.reportEmpty"],
     scopes: null,
   },
+  {
+    name: "useScreenTitle",
+    signature: "useScreenTitle(title)",
+    description:
+      "Name the screen this widget is on, so the host paints that name in the " +
+      "app header beside the back control. The page's own name is the default; " +
+      "only the widget knows when the screen is really \"Order #1423\" rather " +
+      "than \"Orders\". The MOST RECENT call wins: with several widgets on one " +
+      "screen the last to report owns the title, and when that widget unmounts " +
+      "(or passes an empty title) the host falls back to the most recent " +
+      "surviving report and finally to the page name. Only a screen that shows " +
+      "the back control paints a title — a root page keeps the app brand, so a " +
+      "title reported there is held but not shown. Safe on a host that does not " +
+      "implement it (Studio canvas, Agent Mode edit preview) — a no-op there.",
+    returnShape: {
+      "(returns)": "void",
+    },
+    requiredContextSlice: ["screen.reportTitle"],
+    scopes: null,
+  },
   {
     name: "useNavigation",
     signature: "useNavigation()",
@@ -2317,6 +2337,22 @@ const WIDGET_CONTEXT_SHAPE = {
     required: false,
     fields: { subscribe: "function" },
   },
+  // sc-7955 — widget -> host screen-chrome signal. The widget owns the knowledge
+  // (it has the record), the host owns the chrome (the header title slot).
+  // Optional so an AUTHORING host can omit it: with no slice the hook is a
+  // no-op on the Studio canvas and the Agent Mode edit preview, neither of
+  // which paints an app header at all.
+  screen: {
+    description:
+      "Optional screen-chrome slot. { reportTitle(title) -> release }. " +
+      "Registers this widget's title for the screen it is on and returns a " +
+      "release function that withdraws it; the host paints the most recently " +
+      "registered title in the header beside the back control and falls back " +
+      "to the page name once every registration is released. Backs " +
+      "useScreenTitle().",
+    required: false,
+    fields: { reportTitle: "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
@@ -3979,6 +4015,14 @@ const CONTRACT = deepFreeze({
   //    and the sc-7352 backfill deletes the stored key (a bottom-tabs app's
   //    strip becomes the sidebar's quick bar) BEFORE this ships.
   //    `menuItemCap` / `quickBarCap` keep their signatures.
+  // 1.111.0: additive (sc-7955) -- `screen` joins `widgetContextShape` and
+  //    `useScreenTitle(title)` joins `hooks`: a widget names the screen it is
+  //    on, and the host paints that name in the header beside the back control
+  //    instead of the app brand. `reportTitle` returns a release function; the
+  //    MOST RECENT registration wins and the host falls back to the most recent
+  //    surviving one, then to the page name. The slice is OPTIONAL, so an
+  //    authoring host (Studio canvas, Agent Mode edit preview) omits it and the
+  //    hook is a no-op there rather than an error.
   // 1.110.0: additive (sc-7885) — `triggeredBy` joins `actionScriptGlobals`:
   //    WHO initiated this run, as `{ type, id, name, email, role }`, or `null`
   //    on `schedule` / `record_*` where nothing did. `type` is `"app_user"` (an
@@ -3988,7 +4032,7 @@ const CONTRACT = deepFreeze({
   //    integration identity; this describes the caller, it does not grant
   //    anything. The same commit adds `properties` to this list, which the
   //    action-sdk copy had carried since 1.50.0 while this one had not.
-  version: "1.110.0",
+  version: "1.111.0",
   sharedTranslationKeys: SHARED_TRANSLATION_KEYS,
   hooks: HOOKS,
   primitives: PRIMITIVES,

package/dist/hooks.js

@@ -386,6 +386,36 @@ export function useSectionEmpty(isEmpty) {
   }, [empty]);
 }
 
+/**
+ * sc-7955 — name the screen this widget is on, so the host paints that name in
+ * the header beside the back control. The page name is the default; only the
+ * widget knows when the screen is really "Order #1423" rather than "Orders".
+ *
+ * The MOST RECENT call wins: with several widgets on one screen the last to
+ * report owns the title, and when that widget unmounts (or passes an empty
+ * title) the host falls back to the most recent surviving report, then to the
+ * page name. Pass a blank or non-string title to bow out without unmounting
+ * (only a non-empty string registers, so a numeric id registers nothing).
+ *
+ * Keep it short — roughly 25 characters. The slot is one line and truncates
+ * with an ellipsis, sharing the row with back and the bell/identity cluster.
+ *
+ * Only a screen that shows the back control paints a title — a root page keeps
+ * the app brand, so a title reported there is held but not shown.
+ *
+ * Safe to call on a host that does not implement it: the hook is a no-op on the
+ * Studio canvas and the Agent Mode edit preview, which paint no app header.
+ */
+export function useScreenTitle(title) {
+  const ctx = useWidgetContextOrThrow("useScreenTitle");
+  const report = ctx.screen && ctx.screen.reportTitle;
+  const text = typeof title === "string" ? title.trim() : "";
+  useEffect(() => {
+    if (typeof report !== "function" || !text) return undefined;
+    return report(text);
+  }, [report, text]);
+}
+
 /**
  * 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

package/dist/index.d.ts

@@ -1473,6 +1473,8 @@ export function useRefresh(
  * collapse. Safe on a host that does not implement it — a no-op there.
  */
 export function useSectionEmpty(isEmpty: boolean): void;
+/** sc-7955 — name this screen for the header title slot; most recent call wins. */
+export function useScreenTitle(title: string | null | undefined): void;
 
 /** The layout event a react-native primitive passes to `onLayout`. */
 export interface WidgetLayoutEvent {

package/dist/index.js

@@ -75,6 +75,7 @@ export {
   useChildRenderer,
   useRefresh,
   useSectionEmpty,
+  useScreenTitle,
   useContainerWidth,
   useGeolocation,
   GeolocationError,

package/dist/index.native.js

@@ -75,6 +75,7 @@ export {
   useChildRenderer,
   useRefresh,
   useSectionEmpty,
+  useScreenTitle,
   useContainerWidth,
   useGeolocation,
   GeolocationError,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@colixsystems/widget-sdk",
-  "version": "0.142.1",
+  "version": "0.143.0",
   "description": "Common widget interface for AppStudio. Implements WidgetManifest, WidgetContext, property schema, and helper hooks.",
   "homepage": "https://github.com/Colix-AB/AppStudio",
   "type": "module",
@@ -49,7 +49,7 @@
   ],
   "scripts": {
     "build": "node scripts/build.js",
-    "test": "node --test src/__tests__/contract.test.js src/__tests__/theme-token-refs.test.js src/__tests__/vetted-imports-audit.test.js src/__tests__/hooks-users.test.js src/__tests__/hooks-groups.test.js src/__tests__/hooks-invites.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-payments.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-widget-event.test.js src/__tests__/hooks-widget-input.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-page-url.test.js src/__tests__/linter-image-height.test.js src/__tests__/linter-flex-basis-percent.test.js src/__tests__/linter-hardcoded-design.test.js src/__tests__/linter-editability.test.js src/__tests__/linter-measured-padding.test.js src/__tests__/linter-payment-error.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__/flatten-entry.test.js src/__tests__/host-externals.test.js src/__tests__/datetimepicker.test.js src/__tests__/property-schema-resolve.test.js src/__tests__/corner-radius.test.js src/__tests__/theme-components-parity.test.js src/__tests__/navigation-parity.test.js src/__tests__/theme-depth-tokens.test.js src/__tests__/interaction-lift.test.js src/__tests__/toast-host.test.js src/__tests__/overlay-tokens.test.js src/__tests__/hooks-domain-error-mapping.test.js src/__tests__/linter-datastore-error.test.js src/__tests__/linter-write-gating.test.js src/__tests__/hooks-speech-to-text.test.js src/__tests__/hooks-camera.test.js src/__tests__/hooks-barcode.test.js src/__tests__/hooks-image-editor.test.js src/__tests__/hooks-bound-columns.test.js src/__tests__/hooks-stable-query.test.js src/__tests__/hooks-can-write.test.js src/__tests__/widget-route.test.js src/__tests__/linter-html-in-content.test.js src/__tests__/markdown.test.js src/__tests__/markdown-edit.test.js src/__tests__/richtext-tokens.test.js src/__tests__/style-group.test.js"
+    "test": "node --test src/__tests__/contract.test.js src/__tests__/theme-token-refs.test.js src/__tests__/vetted-imports-audit.test.js src/__tests__/hooks-users.test.js src/__tests__/hooks-groups.test.js src/__tests__/hooks-invites.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-payments.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-screen-title.test.js src/__tests__/hooks-widget-event.test.js src/__tests__/hooks-widget-input.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-page-url.test.js src/__tests__/linter-image-height.test.js src/__tests__/linter-flex-basis-percent.test.js src/__tests__/linter-hardcoded-design.test.js src/__tests__/linter-editability.test.js src/__tests__/linter-measured-padding.test.js src/__tests__/linter-payment-error.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__/flatten-entry.test.js src/__tests__/host-externals.test.js src/__tests__/datetimepicker.test.js src/__tests__/property-schema-resolve.test.js src/__tests__/corner-radius.test.js src/__tests__/theme-components-parity.test.js src/__tests__/navigation-parity.test.js src/__tests__/theme-depth-tokens.test.js src/__tests__/interaction-lift.test.js src/__tests__/toast-host.test.js src/__tests__/overlay-tokens.test.js src/__tests__/hooks-domain-error-mapping.test.js src/__tests__/linter-datastore-error.test.js src/__tests__/linter-write-gating.test.js src/__tests__/hooks-speech-to-text.test.js src/__tests__/hooks-camera.test.js src/__tests__/hooks-barcode.test.js src/__tests__/hooks-image-editor.test.js src/__tests__/hooks-bound-columns.test.js src/__tests__/hooks-stable-query.test.js src/__tests__/hooks-can-write.test.js src/__tests__/widget-route.test.js src/__tests__/linter-html-in-content.test.js src/__tests__/markdown.test.js src/__tests__/markdown-edit.test.js src/__tests__/richtext-tokens.test.js src/__tests__/style-group.test.js"
   },
   "engines": {
     "node": ">=18"