@colixsystems/widget-sdk 0.174.0 → 0.176.0

package/README.md

@@ -60,7 +60,7 @@ The data layer lives in **four separate domain-client packages**, each instantia
 | **DIRECTORY** | `useGroups(query)` (optional: query) | `{ groups, loading, error, refetch, create, remove, addMember, removeMember }` | `directory.groups.*` — `groups.read:*` (mutations also `groups.write:*`) |
 | **DIRECTORY** | `useInvites(query)` (optional: query) | `{ invites, loading, error, refetch, resend, revoke }` | `directory.invites.*` — `users.write:*` + the SystemAcl `users.write` capability (the whole invite surface, list included). `query` is `{ status?, limit?, offset? }` with `status` ∈ `pending \| accepted \| revoked \| expired \| all` (endpoint default `all`). |
 | **DIRECTORY** | `useBankIdLink()` | `{ linked, available, status, qr, message, startLink, refresh, cancel, unlink, refetchStatus, … }` | `directory.bankid.*` — no scope (JWT-gated self-service) |
-| **FILESTORE** (`ctx.filestore`) | `usePdfExport({ spaceType, folderId })` (optional: folderId) | `{ exportToPdf, exporting, error, lastExported }` | `ctx.filestore.files.exportPdf` — `files.write:*`. `exportToPdf(html, { fileName?, folderId? })` renders the HTML to a PDF server-side and saves it as a file (`application/pdf`); same server-side renderer on web + native. |
+| **FILESTORE** (`ctx.filestore`) | `usePdfExport({ spaceType, folderId })` (optional: spaceType, folderId) | `{ openPdf, opening, canOpenPdf, exportToPdf, exporting, error, lastExported }` | `ctx.filestore.files.renderPdf` + `ctx.device.pdfViewer`, `ctx.filestore.files.exportPdf` — `files.write:*`. `openPdf(html, { fileName? })` renders the HTML to a PDF server-side and OPENS it (web: PDF tab; native: print / share sheet) without saving. `exportToPdf(html, { fileName?, folderId? })` renders it and saves it as a file (`application/pdf`). Same server-side renderer on web + native. |
 | **PAYMENTS** (`ctx.payments`) | `usePayments()` | `{ requestPayment, getPayment }` | `ctx.payments.*` — `payments.charge:appUser`. Rejects with `PaymentError { code, message, retryable }`; when `retryable` is `false` show `message` and drop the retry. Charges are accepted ONLY in the currency the workspace sells in — omit `currency` and the platform applies it (a disagreeing literal is a publish-blocking `payment-currency` finding). |
 | **NOTIFICATIONS** (`ctx.notifications`) | `useSendNotification()` | `{ send, sending, error }` | `ctx.notifications.send` — `notifications.send:appUser`. `send({ recipient_user_id, title, body, link?, payload? })` notifies one app user in the same workspace; call from an event handler (never render); rejects with `NotificationError`. |
 | **IDENTIFICATION** (`ctx.identification`) | `useIdentification({ provider, purpose, pollIntervalMs })` (optional: every key, and the whole argument) | `{ available, status, qr, autoStartToken, message, identity, identificationId, start, refresh, cancel, reset, … }` | `ctx.identification.*` — no scope (the visitor is deliberately NOT signed in). Gate the UI on `available`; `start()` opens the order and the hook polls to completion. `identity` carries `personal_number_masked` + a stable `subject_hash` — never a raw personal number. |
@@ -73,7 +73,17 @@ See the design reference for the full architecture: [`docs/architecture/widget-m
 
 ## Status
 
-`v0.174.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.176.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.176.0 (contract 1.137.0)
+
+**`manifest.description` is optional.** A widget publishes with a name and no description; when present, the description must still be a string. The storefront shows no blurb for a widget without one.
+
+### What's new in 0.175.0 (contract 1.136.0)
+
+**Open a PDF for the user to view, print or share, without saving it (sc-9135).** `usePdfExport()` gains `openPdf(html, { fileName? })`, `opening` and `canOpenPdf`. The HTML is rendered server-side by the same headless-Chromium pipeline as `exportToPdf`, and the host opens the result: a new browser tab with the PDF viewer on the web Player, and the OS print and share sheet in the native export (`expo-print`). Nothing is stored, so a widget that only opens PDFs calls `usePdfExport()` with no arguments. Call `openPdf` directly from the press handler, because the web host opens its tab inside that press and a tab opened after an `await` is refused by the popup blocker. `canOpenPdf` is false on a host with no PDF viewer, where `openPdf` rejects with `err.code` `UNSUPPORTED`. The wire errors arrive on `err.status`: 401 not signed in, 413 over the size cap, 429 too many renders, 503 renderer busy. The HTML runs no scripts and loads only `https:` / `data:` images and `https:` fonts. On native, closing the print sheet resolves `openPdf` like closing the web tab does. Needs `@colixsystems/filestore-client@0.11.0` (`files.renderPdf`). The host slice is the new `device.pdfViewer`.
+
+**Breaking for authors: `createObjectURL` is now a banned API** (lint rule `no-createobjecturl`). Widgets used it to open a hand-built plain-text blob as a stand-in "print version": it only works in a browser, and on the web it opens widget-built bytes on the host's origin. A widget version that calls it fails lint at submission; versions already published keep running. Open a generated document with `openPdf`, upload a file with `useFilestoreUpload`, and preview a picked photo from the `uri` `useCamera` returns.
 
 ### What's new in 0.174.0 (contract 1.135.0)
 

package/dist/contract.cjs

@@ -1179,9 +1179,22 @@ const HOOKS = [
   {
     name: "usePdfExport",
     signature: "usePdfExport({ spaceType, folderId })",
-    optionalArgs: ["folderId"],
-    description:
-      "Render an HTML string to a PDF server-side and SAVE it as a file in " +
+    optionalArgs: ["spaceType", "folderId"],
+    description:
+      "Render an HTML string to a PDF server-side, then either OPEN it or SAVE " +
+      "it. `openPdf(html, { fileName? })` is THE way to give the user a PDF " +
+      "to view, print, download or share: it renders the HTML and opens the " +
+      "result — the browser's PDF viewer in a new tab on the web Player, the " +
+      "OS print / share sheet in the native export — and SAVES NOTHING, so " +
+      "a widget that only opens PDFs calls `usePdfExport()` with no " +
+      "arguments (`spaceType` names where exportToPdf saves). Call " +
+      "it straight from the press handler (the web tab opens before the " +
+      "render so popup blockers allow it). It resolves once the document is " +
+      "handed to the viewer and rejects with `err.code` UNSUPPORTED when the " +
+      "host has no PDF viewer (check `canOpenPdf`), or the wire error " +
+      "(`err.status` 401 not signed in, 413 over the size cap, 429 too many " +
+      "renders, 503 renderer busy — try again). The rest of this entry is " +
+      "the SAVE path. `exportToPdf` renders and SAVES it as a file in " +
       "the end-user's Filestore space. The widget passes the SPACE " +
       "(`{ spaceType, folderId? }`); the hook resolves owner_id from the host " +
       "context and POSTs JSON through ctx.filestore.files.exportPdf. " +
@@ -1194,6 +1207,9 @@ const HOOKS = [
       "service (headless Chromium) — the SAME server-side pipeline on the web " +
       "Player and the native export, so no browser-only PDF library is used.",
     returnShape: {
+      openPdf: "(html, { fileName? }) => Promise<void>",
+      opening: "boolean",
+      canOpenPdf: "boolean",
       exportToPdf: "(html, { fileName?, folderId? }) => Promise<FilestoreFile>",
       exporting: "boolean",
       error: "Error | null",
@@ -2582,8 +2598,8 @@ const MANIFEST_SCHEMA = {
   },
   description: {
     type: "string",
-    required: true,
-    description: "1-2 sentence storefront description.",
+    required: false,
+    description: "Optional. 1-2 sentence storefront description.",
   },
   author: {
     type: "object",
@@ -2958,10 +2974,14 @@ const WIDGET_CONTEXT_SHAPE = {
       "speech: { isSupported() -> boolean, start(options, { onResult, onError, onEnd }) -> Promise<{ stop(), abort() }> }, " +
       "camera: { isSupported() -> boolean, capture(options?) -> Promise<asset | null>, pick(options?) -> Promise<asset | null> }, " +
       "imageEditor: { isSupported() -> boolean, edit(uri, actions, options?) -> Promise<asset> }, " +
-      "barcode: { isSupported() -> boolean, scan(options?) -> Promise<{ value, format } | null> } }. " +
-      "Backs useGeolocation(), useSpeechToText(), useCamera(), useImageEditor() and useBarcodeScanner(). The web Player brokers them via " +
-      "navigator.geolocation, window.SpeechRecognition, a getUserMedia camera preview, a host-side canvas and BarcodeDetector; the Expo export via " +
-      "expo-location, expo-speech-recognition, expo-image-picker, expo-image-manipulator and expo-camera. " +
+      "barcode: { isSupported() -> boolean, scan(options?) -> Promise<{ value, format } | null> }, " +
+      "pdfViewer: { isSupported() -> boolean, open({ fileName, load: () => Promise<ArrayBuffer> }) -> Promise<void> } }. " +
+      "Backs useGeolocation(), useSpeechToText(), useCamera(), useImageEditor(), useBarcodeScanner() and usePdfExport().openPdf. The web Player brokers them via " +
+      "navigator.geolocation, window.SpeechRecognition, a getUserMedia camera preview, a host-side canvas, BarcodeDetector and a new browser tab; the Expo export via " +
+      "expo-location, expo-speech-recognition, expo-image-picker, expo-image-manipulator, expo-camera and expo-print. " +
+      "pdfViewer.open must be CALLED synchronously from the user's press: the web broker opens its tab before awaiting `load` " +
+      "(the server render), which is what keeps a popup blocker from refusing it; the Expo export writes the bytes to the " +
+      "cache and hands them to the OS print sheet. " +
       "imageEditor.edit applies resize / crop / rotate / flip in order and rejects with an ImageEditorError " +
       "(.code UNSUPPORTED | INVALID_ACTION | DECODE_FAILED | ENCODE_FAILED | INTERNAL). " +
       "getCurrentPosition rejects with a GeolocationError (.code PERMISSION_DENIED | UNAVAILABLE | TIMEOUT | UNSUPPORTED | INTERNAL). " +
@@ -2989,6 +3009,7 @@ const WIDGET_CONTEXT_SHAPE = {
       camera: "object",
       imageEditor: "object",
       barcode: "object",
+      pdfViewer: "object",
     },
   },
 };
@@ -3053,6 +3074,11 @@ const BANNED_APIS = [
     reason: "Dynamic import bypasses the loader's allowlist.",
   },
   { identifier: "globalThis", reason: "Host environment escape." },
+  {
+    identifier: "createObjectURL",
+    reason:
+      "Web-only and opens widget-built bytes on the host origin; open a PDF with usePdfExport().openPdf.",
+  },
 ];
 
 // REQ-WSDK-PLATFORM §3.4, §5: vetted package allowlist. Each entry is a
@@ -4684,7 +4710,13 @@ const CONTRACT = deepFreeze({
   //    options and a new `options` arg on useDatastoreRecord stamp each row
   //    with `_capabilities`, so a widget shows Edit/Delete only on rows the
   //    user may change. New linter warning `row-action-not-gated`.
-  version: "1.135.0",
+  // 1.136.0: additive (sc-9135) — `usePdfExport()` gains `openPdf(html,
+  //    { fileName? })`, `opening` and `canOpenPdf`: render server-side and
+  //    OPEN the PDF (web: browser viewer tab; native: expo-print sheet)
+  //    without saving it, through the new `device.pdfViewer` host slice. And
+  //    `createObjectURL` joins `bannedApis`: widgets reached for it to fake a
+  //    "print version" as a plain-text blob that never worked on native.
+  version: "1.137.0",
   sharedTranslationKeys: SHARED_TRANSLATION_KEYS,
   hooks: HOOKS,
   primitives: PRIMITIVES,

package/dist/contract.js

@@ -1179,9 +1179,22 @@ const HOOKS = [
   {
     name: "usePdfExport",
     signature: "usePdfExport({ spaceType, folderId })",
-    optionalArgs: ["folderId"],
-    description:
-      "Render an HTML string to a PDF server-side and SAVE it as a file in " +
+    optionalArgs: ["spaceType", "folderId"],
+    description:
+      "Render an HTML string to a PDF server-side, then either OPEN it or SAVE " +
+      "it. `openPdf(html, { fileName? })` is THE way to give the user a PDF " +
+      "to view, print, download or share: it renders the HTML and opens the " +
+      "result — the browser's PDF viewer in a new tab on the web Player, the " +
+      "OS print / share sheet in the native export — and SAVES NOTHING, so " +
+      "a widget that only opens PDFs calls `usePdfExport()` with no " +
+      "arguments (`spaceType` names where exportToPdf saves). Call " +
+      "it straight from the press handler (the web tab opens before the " +
+      "render so popup blockers allow it). It resolves once the document is " +
+      "handed to the viewer and rejects with `err.code` UNSUPPORTED when the " +
+      "host has no PDF viewer (check `canOpenPdf`), or the wire error " +
+      "(`err.status` 401 not signed in, 413 over the size cap, 429 too many " +
+      "renders, 503 renderer busy — try again). The rest of this entry is " +
+      "the SAVE path. `exportToPdf` renders and SAVES it as a file in " +
       "the end-user's Filestore space. The widget passes the SPACE " +
       "(`{ spaceType, folderId? }`); the hook resolves owner_id from the host " +
       "context and POSTs JSON through ctx.filestore.files.exportPdf. " +
@@ -1194,6 +1207,9 @@ const HOOKS = [
       "service (headless Chromium) — the SAME server-side pipeline on the web " +
       "Player and the native export, so no browser-only PDF library is used.",
     returnShape: {
+      openPdf: "(html, { fileName? }) => Promise<void>",
+      opening: "boolean",
+      canOpenPdf: "boolean",
       exportToPdf: "(html, { fileName?, folderId? }) => Promise<FilestoreFile>",
       exporting: "boolean",
       error: "Error | null",
@@ -2578,8 +2594,8 @@ const MANIFEST_SCHEMA = {
   },
   description: {
     type: "string",
-    required: true,
-    description: "1-2 sentence storefront description.",
+    required: false,
+    description: "Optional. 1-2 sentence storefront description.",
   },
   author: {
     type: "object",
@@ -2954,10 +2970,14 @@ const WIDGET_CONTEXT_SHAPE = {
       "speech: { isSupported() -> boolean, start(options, { onResult, onError, onEnd }) -> Promise<{ stop(), abort() }> }, " +
       "camera: { isSupported() -> boolean, capture(options?) -> Promise<asset | null>, pick(options?) -> Promise<asset | null> }, " +
       "imageEditor: { isSupported() -> boolean, edit(uri, actions, options?) -> Promise<asset> }, " +
-      "barcode: { isSupported() -> boolean, scan(options?) -> Promise<{ value, format } | null> } }. " +
-      "Backs useGeolocation(), useSpeechToText(), useCamera(), useImageEditor() and useBarcodeScanner(). The web Player brokers them via " +
-      "navigator.geolocation, window.SpeechRecognition, a getUserMedia camera preview, a host-side canvas and BarcodeDetector; the Expo export via " +
-      "expo-location, expo-speech-recognition, expo-image-picker, expo-image-manipulator and expo-camera. " +
+      "barcode: { isSupported() -> boolean, scan(options?) -> Promise<{ value, format } | null> }, " +
+      "pdfViewer: { isSupported() -> boolean, open({ fileName, load: () => Promise<ArrayBuffer> }) -> Promise<void> } }. " +
+      "Backs useGeolocation(), useSpeechToText(), useCamera(), useImageEditor(), useBarcodeScanner() and usePdfExport().openPdf. The web Player brokers them via " +
+      "navigator.geolocation, window.SpeechRecognition, a getUserMedia camera preview, a host-side canvas, BarcodeDetector and a new browser tab; the Expo export via " +
+      "expo-location, expo-speech-recognition, expo-image-picker, expo-image-manipulator, expo-camera and expo-print. " +
+      "pdfViewer.open must be CALLED synchronously from the user's press: the web broker opens its tab before awaiting `load` " +
+      "(the server render), which is what keeps a popup blocker from refusing it; the Expo export writes the bytes to the " +
+      "cache and hands them to the OS print sheet. " +
       "imageEditor.edit applies resize / crop / rotate / flip in order and rejects with an ImageEditorError " +
       "(.code UNSUPPORTED | INVALID_ACTION | DECODE_FAILED | ENCODE_FAILED | INTERNAL). " +
       "getCurrentPosition rejects with a GeolocationError (.code PERMISSION_DENIED | UNAVAILABLE | TIMEOUT | UNSUPPORTED | INTERNAL). " +
@@ -2985,6 +3005,7 @@ const WIDGET_CONTEXT_SHAPE = {
       camera: "object",
       imageEditor: "object",
       barcode: "object",
+      pdfViewer: "object",
     },
   },
 };
@@ -3049,6 +3070,11 @@ const BANNED_APIS = [
     reason: "Dynamic import bypasses the loader's allowlist.",
   },
   { identifier: "globalThis", reason: "Host environment escape." },
+  {
+    identifier: "createObjectURL",
+    reason:
+      "Web-only and opens widget-built bytes on the host origin; open a PDF with usePdfExport().openPdf.",
+  },
 ];
 
 // REQ-WSDK-PLATFORM §3.4, §5: vetted package allowlist. Each entry is a
@@ -4680,7 +4706,13 @@ const CONTRACT = deepFreeze({
   //    options and a new `options` arg on useDatastoreRecord stamp each row
   //    with `_capabilities`, so a widget shows Edit/Delete only on rows the
   //    user may change. New linter warning `row-action-not-gated`.
-  version: "1.135.0",
+  // 1.136.0: additive (sc-9135) — `usePdfExport()` gains `openPdf(html,
+  //    { fileName? })`, `opening` and `canOpenPdf`: render server-side and
+  //    OPEN the PDF (web: browser viewer tab; native: expo-print sheet)
+  //    without saving it, through the new `device.pdfViewer` host slice. And
+  //    `createObjectURL` joins `bannedApis`: widgets reached for it to fake a
+  //    "print version" as a plain-text blob that never worked on native.
+  version: "1.137.0",
   sharedTranslationKeys: SHARED_TRANSLATION_KEYS,
   hooks: HOOKS,
   primitives: PRIMITIVES,

package/dist/hooks.js

@@ -4149,9 +4149,18 @@ export function useFilestoreUpload(options) {
 }
 
 /**
- * sc-2314 — render an HTML string to a PDF server-side and SAVE it into the
- * end-user's Filestore space. Returns `{ exportToPdf, exporting, error,
- * lastExported }`. The widget passes the SPACE (`{ spaceType, folderId? }`);
+ * sc-2314 / sc-9135 — render an HTML string to a PDF server-side, then OPEN it
+ * or SAVE it. Returns `{ openPdf, opening, canOpenPdf, exportToPdf, exporting,
+ * error, lastExported }`.
+ *
+ * `openPdf(html, { fileName? })` renders without saving and hands the bytes to
+ * the host's `device.pdfViewer`: a browser PDF tab on web, the OS print sheet
+ * on native. It is how a widget offers "print / view / download as PDF".
+ * `canOpenPdf` is false on a host with no viewer, where openPdf rejects with
+ * `err.code` UNSUPPORTED.
+ *
+ * `exportToPdf` SAVES into the end-user's Filestore space. The widget passes
+ * the SPACE (`{ spaceType, folderId? }`);
  * the hook resolves `owner_id` the same way the upload hook does (tenant for
  * PROJECT, app user for PERSONAL) and posts JSON to
  * `ctx.filestore.files.exportPdf`.
@@ -4189,6 +4198,45 @@ export function usePdfExport(options) {
 
   const filesRef = useRef(ctx.filestore.files);
   filesRef.current = ctx.filestore.files;
+  const viewerRef = useRef(ctx.device && ctx.device.pdfViewer);
+  viewerRef.current = ctx.device && ctx.device.pdfViewer;
+  const [opening, setOpening] = useState(false);
+  const openingCountRef = useRef(0);
+
+  const canOpenPdf =
+    _canOpenPdf(viewerRef.current) &&
+    typeof ctx.filestore.files.renderPdf === "function";
+
+  // Deliberately no `await` before viewer.open: the web broker must open its
+  // tab inside the press that called us, or a popup blocker refuses it.
+  const openPdf = useCallback(async (html, overrides) => {
+    if (typeof html !== "string" || html.trim().length === 0) {
+      throw new Error("usePdfExport: html is required");
+    }
+    const viewer = viewerRef.current;
+    const files = filesRef.current;
+    if (!_canOpenPdf(viewer) || typeof files.renderPdf !== "function") {
+      const err = new Error("This app cannot open PDFs here.");
+      err.code = "UNSUPPORTED";
+      setError(err);
+      throw err;
+    }
+    setError(null);
+    openingCountRef.current += 1;
+    setOpening(true);
+    try {
+      await viewer.open({
+        fileName: _pdfFileName(overrides && overrides.fileName),
+        load: () => files.renderPdf({ html }),
+      });
+    } catch (err) {
+      setError(err);
+      throw err;
+    } finally {
+      openingCountRef.current -= 1;
+      if (openingCountRef.current === 0) setOpening(false);
+    }
+  }, []);
 
   const exportToPdf = useCallback(
     async (html, overrides) => {
@@ -4228,7 +4276,36 @@ export function usePdfExport(options) {
     [ownerId, defaultFolderId, spaceType],
   );
 
-  return { exportToPdf, exporting, error, lastExported };
+  return {
+    openPdf,
+    opening,
+    canOpenPdf,
+    exportToPdf,
+    exporting,
+    error,
+    lastExported,
+  };
+}
+
+function _canOpenPdf(viewer) {
+  return Boolean(
+    viewer &&
+      typeof viewer.open === "function" &&
+      (typeof viewer.isSupported !== "function" || viewer.isSupported()),
+  );
+}
+
+// The name the viewer offers when the user saves or shares the document.
+function _pdfFileName(fileName) {
+  const base =
+    typeof fileName === "string" && fileName.trim()
+      ? Array.from(fileName.trim(), (ch) =>
+          ch < " " || ch === "/" || ch === "\\" ? "_" : ch,
+        )
+          .join("")
+          .slice(0, 120)
+      : "document";
+  return /\.pdf$/i.test(base) ? base : `${base}.pdf`;
 }
 
 /**

package/dist/manifest.cjs

@@ -196,7 +196,12 @@ function validateManifest(m) {
   );
 
   pushIf(errors, isNonEmptyString(manifest.icon), "manifest.icon must be a non-empty string");
-  pushIf(errors, isNonEmptyString(manifest.description), "manifest.description must be a non-empty string");
+  // sc-9142: optional — a listing needs a name, not a blurb.
+  pushIf(
+    errors,
+    manifest.description === undefined || typeof manifest.description === "string",
+    "manifest.description must be a string when present",
+  );
 
   if (manifest.author === null || typeof manifest.author !== "object") {
     errors.push("manifest.author must be an object with a name");

package/dist/manifest.js

@@ -242,7 +242,12 @@ function validateManifest(m) {
   );
 
   pushIf(errors, isNonEmptyString(manifest.icon), "manifest.icon must be a non-empty string");
-  pushIf(errors, isNonEmptyString(manifest.description), "manifest.description must be a non-empty string");
+  // sc-9142: optional — a listing needs a name, not a blurb.
+  pushIf(
+    errors,
+    manifest.description === undefined || typeof manifest.description === "string",
+    "manifest.description must be a string when present",
+  );
 
   if (manifest.author === null || typeof manifest.author !== "object") {
     errors.push("manifest.author must be an object with a name");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@colixsystems/widget-sdk",
-  "version": "0.174.0",
+  "version": "0.176.0",
   "description": "Common widget interface for AppStudio. Implements WidgetManifest, WidgetContext, property schema, and helper hooks.",
   "homepage": "https://github.com/Colix-AB/AppStudio",
   "type": "module",