@colixsystems/widget-sdk 0.62.0 → 0.63.0

package/README.md

@@ -53,7 +53,11 @@ See the design reference for the full architecture: [`docs/architecture/widget-m
 
 ## Status
 
-`v0.62.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.63.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.63.0
+
+**New optional manifest field `rendersOwnChrome` (sc-3331).** A boolean (default `false`) that declares whether your widget renders its OWN section header — a heading (and optional subtitle), plus any primary action for its section — making it a self-contained section. Set it `true` when your widget draws its own title (from a `title`/`subtitle` prop with a real default, so the author can still retitle it in the Properties Panel), and the AppStudio app-builder will place the widget as the WHOLE section: it will NOT add a standalone heading or a duplicate action button above it, so the section is never double-titled. Leave it `false`/omitted for a content-only widget whose heading the page supplies. `CONTRACT.version` → `1.42.0`. Additive — existing manifests omit it and read `false`, so no widget needs changing.
 
 ### What's new in 0.62.0
 

package/dist/contract.cjs

@@ -971,6 +971,13 @@ const MANIFEST_SCHEMA = {
       "never auto-applies style — the widget owns placement.",
     default: {},
   },
+  rendersOwnChrome: {
+    type: "boolean",
+    required: false,
+    description:
+      "Optional (default false). TRUE when the widget renders its OWN section header — a heading (and optional subtitle), plus any primary action for its section — making it a self-contained section. The AppStudio app-builder reads this when it places an already-installed widget: it lays the widget out as the WHOLE section and does NOT add a standalone heading or a duplicate action button above it, so the section is never double-titled. Set it to match what the component actually renders; leave it false (or omit) for a content-only widget whose heading the page supplies.",
+    default: false,
+  },
   events: {
     type: "object[]",
     required: true,
@@ -1908,7 +1915,11 @@ const CONTRACT = deepFreeze({
   //    no in-code `|| "fallback"`. Backed by a host-only subpath export
   //    (`@colixsystems/widget-sdk/host` -> resolveProps); the author-facing entry
   //    is unchanged. No existing behaviour changes — minor bump.
-  version: "1.41.0",
+  // 1.42.0 (sc-3331) — new OPTIONAL manifest field `rendersOwnChrome` (boolean,
+  //    default false): declares that the widget renders its own section header,
+  //    so the app-builder places it as a whole section without stacking a
+  //    heading above it. Additive — existing manifests omit it and read false.
+  version: "1.42.0",
   sharedTranslationKeys: SHARED_TRANSLATION_KEYS,
   hooks: HOOKS,
   primitives: PRIMITIVES,

package/dist/contract.js

@@ -971,6 +971,13 @@ const MANIFEST_SCHEMA = {
       "never auto-applies style — the widget owns placement.",
     default: {},
   },
+  rendersOwnChrome: {
+    type: "boolean",
+    required: false,
+    description:
+      "Optional (default false). TRUE when the widget renders its OWN section header — a heading (and optional subtitle), plus any primary action for its section — making it a self-contained section. The AppStudio app-builder reads this when it places an already-installed widget: it lays the widget out as the WHOLE section and does NOT add a standalone heading or a duplicate action button above it, so the section is never double-titled. Set it to match what the component actually renders; leave it false (or omit) for a content-only widget whose heading the page supplies.",
+    default: false,
+  },
   events: {
     type: "object[]",
     required: true,
@@ -1908,7 +1915,11 @@ const CONTRACT = deepFreeze({
   //    no in-code `|| "fallback"`. Backed by a host-only subpath export
   //    (`@colixsystems/widget-sdk/host` -> resolveProps); the author-facing entry
   //    is unchanged. No existing behaviour changes — minor bump.
-  version: "1.41.0",
+  // 1.42.0 (sc-3331) — new OPTIONAL manifest field `rendersOwnChrome` (boolean,
+  //    default false): declares that the widget renders its own section header,
+  //    so the app-builder places it as a whole section without stacking a
+  //    heading above it. Additive — existing manifests omit it and read false.
+  version: "1.42.0",
   sharedTranslationKeys: SHARED_TRANSLATION_KEYS,
   hooks: HOOKS,
   primitives: PRIMITIVES,

package/dist/hooks.js

@@ -2823,16 +2823,37 @@ function toPaymentError(err) {
  *       anything yourself (no `Linking.openURL`, no `checkout_url` to
  *       handle). The mock provider auto-confirms (`status: "PAID"`, no
  *       redirect). Rejects with a `PaymentError`.
- *   getPayment(paymentId) → Promise<payment> — poll the terminal status.
- *
- * Because the web redirect reloads the app on return, confirm completion
- * from server-authoritative state (the Mollie webhook flips the charge /
- * your datastore record) — re-read your bound record on mount, or poll
- * `getPayment(id)` after the mock/native flow resolves. Requires the
- * `payments.charge:appUser` scope in the manifest's `requestedScopes`. The
- * charge settles to the workspace owner; the app user confirms the amount
- * in hosted Checkout. No card data touches the widget — never collect card
- * fields yourself.
+ *   getPayment(paymentId) → Promise<payment> — read the current status
+ *       (`PENDING` | `PAID` | `FAILED`), scoped server-side to the caller.
+ *
+ * THE PAYER IS ALWAYS A SIGNED-IN APP USER — charging requires it, and a paid
+ * widget lives on a page behind login. So read the buyer's identity from
+ * `useUser()` (`{ id, email, displayName }`) and connect the record you write
+ * to `user.id`. Do NOT re-collect the name / email `useUser()` already gives
+ * you as required inputs; pre-filling an editable field from it, or asking for
+ * genuinely new details (phone, address, notes), is fine.
+ *
+ * CONFIRM FROM SERVER STATE, NOT MEMORY — and handle success, failure, AND
+ * cancel. On web `requestPayment` triggers a full-page redirect, so the app
+ * reloads on return and any in-memory "done" flag is gone. One pattern works on
+ * both platforms:
+ *   1. On mount, read `useRouteParams()`. After the web redirect it carries
+ *      `payment` (`"success"` | `"cancel"`) and, on success, `payment_id`.
+ *      `"cancel"` → the user backed out: show a "payment cancelled" state, do
+ *      NOT treat it as paid. `"success"` + `payment_id` → poll `getPayment(id)`
+ *      until it leaves `PENDING`, then branch: `PAID` → confirm / write the
+ *      record; `FAILED` → show a failure state.
+ *   2. Also poll the `id` that `requestPayment` RESOLVES with — the mock
+ *      provider and the native in-app-browser flow return here without a reload,
+ *      so route params are absent and this branch reconciles instead.
+ * Poll a bounded number of times (e.g. every ~1.5s for up to ~30s) because the
+ * Mollie webhook may land a moment after the redirect; if it is still `PENDING`
+ * when you give up, show a "still processing" state rather than "paid".
+ *
+ * Requires the `payments.charge:appUser` scope in the manifest's
+ * `requestedScopes`. The charge settles to the workspace owner; the app user
+ * confirms the amount in hosted Checkout. No card data touches the widget —
+ * never collect card fields yourself.
  */
 export function usePayments() {
   const ctx = useWidgetContextOrThrow("usePayments");

package/package.json

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