@colixsystems/widget-sdk 0.102.0 → 0.102.1

package/README.md

@@ -21,7 +21,7 @@ The data layer lives in **four separate domain-client packages**, each instantia
 | **CORE** | `useWorkspaceCurrency()` | `{ currency, formatMoney }` | `ctx.workspace.currency` — no scope. The currency this workspace charges its app users in, resolved at RENDER time. Render every price as `formatMoney(minorUnits)` and never write a currency symbol or code into a widget: the owner can change it after the widget ships, and a baked label then contradicts the charge. |
 | **CORE** | `useWidgetStyle()` | `{ [styleField]: value }` | `ctx.props.style` — no scope. The author-set per-widget style values declared in `manifest.styleSchema`; apply each onto whatever element you choose. |
 | **CORE** | `useUser()` | `{ id, email, displayName, roles, groupIds }` | `ctx.user` (host-built context, **camelCase** — not a wire payload; `id` null when anonymous) — no scope |
-| **CORE** | `useNavigation()` | `{ goTo, goBack, push, replace, back, currentRoute, openLink }` | `ctx.navigation` — no scope (`openLink` for a link of unknown shape; a known external URL can also use the `Linking` primitive) |
+| **CORE** | `useNavigation()` | `{ goTo, goBack, push, replace, back, currentRoute, openLink }` | `ctx.navigation` — no scope. `goTo(pageIdOrSlug, params?)` accepts a page UUID (a `pageRef` prop) **or its slug** (a row's page-key field) — both hosts resolve either (`openLink` for a link of unknown shape; a known external URL can also use the `Linking` primitive) |
 | **CORE** | `useRouteParams()` | `{ [paramKey]: value }` | `ctx.navigation.currentRoute.params` — no scope. The nav params the previous page passed via `goTo(pageId, params)`; the flat accessor for master→detail (read `recordId` on a detail page). Empty object when none. |
 | **CORE** | `usePageContext()` | `{ params, records }` | `ctx.pageContext` — no scope. The page's DECLARED parameters, resolved once by the host: `params` are coerced to their declared types, `records` holds the row already fetched for each `record` param (read it instead of fetching again). Both empty when the page declares none. |
 | **CORE** | `useWidgetRoute(initial)` | `[state, setState]` | `ctx.widgetRoute` — no scope. Where YOUR WIDGET is, persisted by the host so it survives a reload and travels in a shared link (the `w_<instanceId>` query key on web, the screen's route params natively): the folder a browser has opened, a wizard step, a selected tab, a list's sort and search. `useState` semantics over an object — writes MERGE, `null` clears a key back to its `initial`, and `initial` is read once. Values are scalars or flat arrays of scalars, size- and length-capped; anything else is not stored. NOT history (Back still leaves the page, on both platforms). Degrades to component state on the Studio canvas. |

package/dist/contract.cjs

@@ -655,11 +655,12 @@ const HOOKS = [
     name: "useNavigation",
     signature: "useNavigation()",
     returnShape: {
-      goTo: "(pageId: string, params?: object) => void",
+      goTo:
+        "(pageIdOrSlug: string, params?: object) => void — a page's UUID (a pageRef prop) OR its SLUG (e.g. a row's page-key field); both hosts resolve either. There is NO page-name lookup: a slug is the only data-carried navigation key.",
       openLink: "(link: string) => boolean",
       goBack: "() => void",
-      push: "(pageId: string, params?: object) => void",
-      replace: "(pageId: string, params?: object) => void",
+      push: "(pageIdOrSlug: string, params?: object) => void",
+      replace: "(pageIdOrSlug: string, params?: object) => void",
       back: "() => void",
       currentRoute: "{ pageId: string, params: object }",
     },
@@ -3259,7 +3260,13 @@ const CONTRACT = deepFreeze({
   //    are compressed to WebP by default; `compress: false` stores the file
   //    byte-for-byte. Existing callers are unaffected — the field is only sent
   //    when the opt-out is chosen.
-  version: "1.76.0",
+  // 1.77.0: documentation (sc-5713) — `goTo`/`push`/`replace` document that
+  //    they accept a page SLUG as well as a page UUID. Both hosts have always
+  //    resolved either (the web route reads id-or-slug; the export's
+  //    PAGE_ROUTES maps both to the screen name), but the contract said
+  //    `pageId` only, so data-driven widgets — whose rows carry slugs —
+  //    invented params patterns that navigate nowhere. No code changed shape.
+  version: "1.77.0",
   sharedTranslationKeys: SHARED_TRANSLATION_KEYS,
   hooks: HOOKS,
   primitives: PRIMITIVES,

package/dist/contract.js

@@ -655,11 +655,12 @@ const HOOKS = [
     name: "useNavigation",
     signature: "useNavigation()",
     returnShape: {
-      goTo: "(pageId: string, params?: object) => void",
+      goTo:
+        "(pageIdOrSlug: string, params?: object) => void — a page's UUID (a pageRef prop) OR its SLUG (e.g. a row's page-key field); both hosts resolve either. There is NO page-name lookup: a slug is the only data-carried navigation key.",
       openLink: "(link: string) => boolean",
       goBack: "() => void",
-      push: "(pageId: string, params?: object) => void",
-      replace: "(pageId: string, params?: object) => void",
+      push: "(pageIdOrSlug: string, params?: object) => void",
+      replace: "(pageIdOrSlug: string, params?: object) => void",
       back: "() => void",
       currentRoute: "{ pageId: string, params: object }",
     },
@@ -3259,7 +3260,13 @@ const CONTRACT = deepFreeze({
   //    are compressed to WebP by default; `compress: false` stores the file
   //    byte-for-byte. Existing callers are unaffected — the field is only sent
   //    when the opt-out is chosen.
-  version: "1.76.0",
+  // 1.77.0: documentation (sc-5713) — `goTo`/`push`/`replace` document that
+  //    they accept a page SLUG as well as a page UUID. Both hosts have always
+  //    resolved either (the web route reads id-or-slug; the export's
+  //    PAGE_ROUTES maps both to the screen name), but the contract said
+  //    `pageId` only, so data-driven widgets — whose rows carry slugs —
+  //    invented params patterns that navigate nowhere. No code changed shape.
+  version: "1.77.0",
   sharedTranslationKeys: SHARED_TRANSLATION_KEYS,
   hooks: HOOKS,
   primitives: PRIMITIVES,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@colixsystems/widget-sdk",
-  "version": "0.102.0",
+  "version": "0.102.1",
   "description": "Common widget interface for AppStudio. Implements WidgetManifest, WidgetContext, property schema, and helper hooks.",
   "type": "module",
   "main": "./dist/index.js",