@colixsystems/widget-sdk 0.53.0 → 0.55.0

package/README.md

@@ -19,7 +19,7 @@ The data layer lives in **four separate domain-client packages**, each instantia
 | ----- | ---------------- | ------- | ------------- |
 | **CORE** | `useTheme()` | `{ colors, spacing, radii, typography }` | `ctx.workspace.theme` — no scope |
 | **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, display_name, roles, group_ids }` | `ctx.user` (snake_case verbatim; `id` null when anonymous) — no scope |
+| **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 }` | `ctx.navigation` — no scope (external URLs use the `Linking` primitive) |
 | **CORE** | `useWidgetEvent(name)` | `(payload?) => void` | `ctx.events.emit` — no scope |
 | **CORE** | `useChildRenderer()` | `{ renderNode(node) }` | `ctx.renderer` — no scope (prefer the `WidgetTree` component) |
@@ -40,6 +40,7 @@ The data layer lives in **four separate domain-client packages**, each instantia
 | **DIRECTORY** | `useUsers(query?)` | `{ users, loading, error, refetch, invite, deactivate, reactivate, remove }` | `directory.users.*` — `users.read:*` (edits also `users.write:*`; `remove()` also `users.delete:*`) |
 | **DIRECTORY** | `useGroups(query?)` | `{ groups, loading, error, refetch, create, remove, addMember, removeMember }` | `directory.groups.*` — `groups.read:*` (mutations also `groups.write:*`) |
 | **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? })` | `{ 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. |
 | **PAYMENTS** (`ctx.payments`) | `usePayments()` | `{ requestPayment, getPayment }` | `ctx.payments.*` — `payments.charge:appUser` |
 | **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`. |
 
@@ -51,7 +52,15 @@ See the design reference for the full architecture: [`docs/architecture/widget-m
 
 ## Status
 
-`v0.53.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.55.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.55.0
+
+**Dynamic record selection for `valueRef` (sc-2327).** The `valueRef` binding gains an optional `mode` field: `"static"` (the default — pin a specific `recordId`, the only prior behaviour) or `"latest"` (resolve the most recently created row live, sorting on the host-managed `created_at` descending with `limit: 1`; `recordId` is ignored). The built-in Field Value widget reads it to offer a "Latest entry" that updates as records are added, with no per-host code — the same baked widget source and the same injected `@colixsystems/datastore-client` run on the web Player and the native Expo export. The `ValueRefBinding` type adds `mode?: "static" | "latest"`. Existing bindings carry no `mode` and read as static. `CONTRACT.version` → `1.39.0`. Additive — no existing field changed shape.
+
+### What's new in 0.54.0
+
+**Generate & save PDFs from a widget (sc-2314).** New `usePdfExport({ spaceType, folderId? })` hook. `exportToPdf(html, { fileName?, folderId? })` renders the HTML to a PDF **server-side** (the platform's headless-Chromium pipeline) and saves it into the end-user's Filestore via `ctx.filestore.files.exportPdf`, resolving to the created file row (`application/pdf`). It reuses the filestore owner_id resolution + per-folder write gate and the existing `files.write:*` scope. Because the rendering is server-side, the capability behaves identically on the web Player and the native Expo export — no browser-only PDF library is added to the vetted set. Pairs with `@colixsystems/filestore-client@0.6.0`'s new `files.exportPdf(...)`. `CONTRACT.version` → `1.38.0`. Additive — no existing hook, primitive, manifest field, or token changed shape.
 
 ### What's new in 0.53.0
 
@@ -278,7 +287,7 @@ Also: `useFileSignatures(fileIds)` is now **self-scoped** (the caller's own sign
 
 - **The SDK no longer owns any data facade.** The bespoke per-hook facades that used to live on `WidgetContext` (`ctx.datastore` as an opaque host object, `ctx.directory.listUsers`, `ctx.users`, `ctx.groups`, `ctx.recordPermissions`, `ctx.assets.get`) are replaced by four host-instantiated, host-injected domain clients: `ctx.datastore` (`@colixsystems/datastore-client`), `ctx.directory` (`@colixsystems/directory-client`), `ctx.assets` (`@colixsystems/assets-client`, flattened), `ctx.payments` (`@colixsystems/payments-client`). The SDK imports none of them and ships no HTTP.
 - **`ctx.recordPermissions`, `ctx.users`, `ctx.groups` are removed.** Per-record permission management moved under `ctx.datastore.records(tableId).permissions(recordId)`; user / group administration moved under `ctx.directory.users` / `ctx.directory.groups`. The hooks (`useRecordPermissions`, `useUsers`, `useGroups`) keep the same names and signatures — only the client slice they read changed.
-- **snake_case end to end, no client-side transform.** Clients send and return snake_case verbatim (`group_ids`, `can_read`, `is_active`, `amount_cents`, `data_type`, `created_at`, …). The SDK passes bodies straight through and unwraps the `{ data, meta }` list envelope without renaming a single field. Hook return rows and `useUser()` fields are therefore snake_case (`display_name`, `group_ids`, `is_active`, `member_count`, and `useRecordPermissions` rows carry `user_id` / `group_id` / `can_read` / `can_write` / `can_delete` / `can_grant`).
+- **snake_case end to end, no client-side transform.** Clients send and return snake_case verbatim (`group_ids`, `can_read`, `is_active`, `amount_cents`, `data_type`, `created_at`, …). The SDK passes bodies straight through and unwraps the `{ data, meta }` list envelope without renaming a single field. Wire-payload hook return rows are therefore snake_case (`is_active`, `member_count`, and `useRecordPermissions` rows carry `user_id` / `group_id` / `can_read` / `can_write` / `can_delete` / `can_grant`). The one exception is `useUser()`: it reads the host-built `ctx.user` context object, not a wire payload, so its fields are **camelCase** (`displayName`, `groupIds`).
 - **Companion package versions:** `datastore-client 0.5.0`, `assets-client 0.4.0`, `directory-client 0.1.0`, `payments-client 0.1.0`.
 - **`CONTRACT.version` → `1.9.0`.** Breaking for `WidgetContext` consumers (removed slices, renamed wire fields); the hook export surface is unchanged.
 
@@ -423,7 +432,7 @@ import { defineWidget, validateManifest, useDatastoreQuery, Text, View } from "@
 
 - `defineWidget({ manifest, component })` — validates the manifest and produces a widget module the host can register.
 - `validateManifest(m)` / `validatePropertySchema(s)` / `validateProps(schema, props)` — shape validation; no third-party deps.
-- `useDatastoreQuery`, `useDatastoreRecord`, `useDatastoreSchema`, `useDatastoreMutation`, `useDirectory`, `useUsers`, `useGroups`, `useRecordPermissions`, `useAsset`, `useWidgetEvent`, `usePayments`, `useSendNotification`, `useTheme`, `useI18n`, `useUser`, `useNavigation`, `useChildRenderer`, `useClipboard`, `useToast` — hooks that read from the host-provided `WidgetContext` (or, for `useClipboard`, the platform clipboard API directly). `useDirectory(query?)` returns `{ users, loading, error, refetch }` (each user `{ id, name, role }`) and requires the `directory.read:users` scope. `useUsers(query?)` returns `{ users, loading, error, refetch, invite, deactivate, reactivate, remove }` and requires `users.read:*` (mutations also need `users.write:*`); rejections are a `DirectoryError`. `useGroups(query?)` returns `{ groups, loading, error, refetch, create, remove, addMember, removeMember }` and requires `groups.read:*` (mutations also need `groups.write:*`). `usePayments()` returns `{ requestPayment, getPayment }` and requires the `payments.charge:appUser` scope; `requestPayment(...)` rejects with a `PaymentError`. `useSendNotification()` returns `{ send, sending, error }` and requires the `notifications.send:appUser` scope; `send({ recipient_user_id, title, body, link?, payload? })` notifies one app user in the same workspace (cross-workspace `recipient_user_id` is rejected), must be called from an event handler rather than render, and rejects with a `NotificationError`. `useUser()` returns the active end-user identity `{ id, email, display_name, roles, group_ids }` (snake_case verbatim; `id` is `null` for anonymous / preview). `useNavigation()` returns `{ goTo, goBack, push, replace, back, currentRoute }` for internal page navigation — for external URLs use the `Linking` primitive (`Linking.openURL(url)`). `useDatastoreRecord(tableId, recordId)` returns `{ data, loading, error, refetch }` for a single record (data is one row or null). `useDatastoreSchema(tableId)` returns `{ schema, loading, error, refetch }` where `schema` is `{ id, name, columns: [{ id, name, data_type, required, relation_type, target_table_id, is_identification }] }` (structure only, no row data; snake_case verbatim) — use it to resolve a stored `columnId` to its column type at runtime; requires the `datastore.read:<table>` scope. `useAsset(fileId)` returns `{ url, file, loading, error, refetch }` — the `url` is an absolute URL composed against the host's API base. `useChildRenderer()` returns `{ renderNode(node) }` — container widgets call it to render arbitrary child page-tree nodes (prefer the `WidgetTree` component for the common case).
+- `useDatastoreQuery`, `useDatastoreRecord`, `useDatastoreSchema`, `useDatastoreMutation`, `useDirectory`, `useUsers`, `useGroups`, `useRecordPermissions`, `useAsset`, `useWidgetEvent`, `usePayments`, `useSendNotification`, `useTheme`, `useI18n`, `useUser`, `useNavigation`, `useChildRenderer`, `useClipboard`, `useToast` — hooks that read from the host-provided `WidgetContext` (or, for `useClipboard`, the platform clipboard API directly). `useDirectory(query?)` returns `{ users, loading, error, refetch }` (each user `{ id, name, role }`) and requires the `directory.read:users` scope. `useUsers(query?)` returns `{ users, loading, error, refetch, invite, deactivate, reactivate, remove }` and requires `users.read:*` (mutations also need `users.write:*`); rejections are a `DirectoryError`. `useGroups(query?)` returns `{ groups, loading, error, refetch, create, remove, addMember, removeMember }` and requires `groups.read:*` (mutations also need `groups.write:*`). `usePayments()` returns `{ requestPayment, getPayment }` and requires the `payments.charge:appUser` scope; `requestPayment(...)` rejects with a `PaymentError`. `useSendNotification()` returns `{ send, sending, error }` and requires the `notifications.send:appUser` scope; `send({ recipient_user_id, title, body, link?, payload? })` notifies one app user in the same workspace (cross-workspace `recipient_user_id` is rejected), must be called from an event handler rather than render, and rejects with a `NotificationError`. `useUser()` returns the active end-user identity `{ id, email, displayName, roles, groupIds }` (camelCase — the host-built context object, not a wire payload; `id` is `null` for anonymous / preview). `useNavigation()` returns `{ goTo, goBack, push, replace, back, currentRoute }` for internal page navigation — for external URLs use the `Linking` primitive (`Linking.openURL(url)`). `useDatastoreRecord(tableId, recordId)` returns `{ data, loading, error, refetch }` for a single record (data is one row or null). `useDatastoreSchema(tableId)` returns `{ schema, loading, error, refetch }` where `schema` is `{ id, name, columns: [{ id, name, data_type, required, relation_type, target_table_id, is_identification }] }` (structure only, no row data; snake_case verbatim) — use it to resolve a stored `columnId` to its column type at runtime; requires the `datastore.read:<table>` scope. `useAsset(fileId)` returns `{ url, file, loading, error, refetch }` — the `url` is an absolute URL composed against the host's API base. `useChildRenderer()` returns `{ renderNode(node) }` — container widgets call it to render arbitrary child page-tree nodes (prefer the `WidgetTree` component for the common case).
 - `WidgetTree({ node })` — component that renders an author-authored child node through the host's renderer; used by Tabs / Card / custom containers to host arbitrary child widgets.
 - `Text`, `View`, `Pressable`, `Image`, `ScrollView`, `TextInput`, `FlatList`, `SectionList`, `ActivityIndicator`, `Switch`, `StyleSheet`, `Linking`, `Icon`, `DateTimePicker` — re-exported from `react-native` (the RN primitives) or implemented in the SDK (`Icon` wraps `lucide-react-native`; `DateTimePicker` wraps `@react-native-community/datetimepicker` on native and renders `<input type="date|time|datetime-local">` directly on web because the RN library has no react-native-web mapping). The web build aliases `react-native` to `react-native-web` so the RN-re-exported primitives render in the browser without any per-platform code; the exported Expo app's Metro bundler resolves the real `react-native` library. `Linking` is a static API (`Linking.openURL(url)`) — use it for external URLs, and use `useNavigation().goTo(pageId)` for internal page navigation. See https://reactnative.dev/docs/ for per-component props.
 - `WidgetContextProvider` — React context provider that the host (Studio, Player, exported app) wraps widgets with.

package/dist/contract.cjs

@@ -235,6 +235,29 @@ const HOOKS = [
     requiredContextSlice: ["filestore.files"],
     scopes: ["files.write:*"],
   },
+  {
+    name: "usePdfExport",
+    signature: "usePdfExport({ spaceType, folderId? })",
+    description:
+      "Render an HTML string to a PDF server-side and SAVE 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. " +
+      "`exportToPdf(html, { fileName?, folderId? })` resolves to the created " +
+      "file row (mime_type `application/pdf`) or throws the wire error; a 404 " +
+      "means the destination folder denied a write, a 413 that the rendered " +
+      "PDF exceeded the size cap. The HTML is rendered by the host's PDF " +
+      "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: {
+      exportToPdf: "(html, { fileName?, folderId? }) => Promise<FilestoreFile>",
+      exporting: "boolean",
+      error: "Error | null",
+      lastExported: "FilestoreFile | null",
+    },
+    requiredContextSlice: ["filestore.files"],
+    scopes: ["files.write:*"],
+  },
   {
     name: "useFilestoreFolders",
     signature: "useFilestoreFolders({ spaceType, parentFolderId?, q?, enabled? })",
@@ -975,9 +998,9 @@ const WIDGET_CONTEXT_SHAPE = {
   },
   user: {
     description:
-      "Signed-in user, host-provided VERBATIM (snake_case: { id, email, display_name, roles, group_ids }). Not a data-client.",
+      "Signed-in user, host-built context object (camelCase: { id, email, displayName, roles, groupIds }) — NOT a wire payload, so it is the one camelCase island among the hooks. Not a data-client.",
     required: true,
-    fields: { id: "string", email: "string", display_name: "string" },
+    fields: { id: "string", email: "string", displayName: "string" },
   },
   workspace: {
     description:
@@ -1824,7 +1847,24 @@ const CONTRACT = deepFreeze({
   //    the platform host, and an unknown slug / SSRF / timeout throws a
   //    catchable Error. New entry in ACTION_SCRIPT_GLOBALS only — no widget
   //    hook, primitive, manifest field, or token changed shape; minor bump.
-  version: "1.37.0",
+  //
+  // 1.38.0: additive (sc-2314) — new `usePdfExport({ spaceType, folderId? })`
+  //    hook. `exportToPdf(html, { fileName?, folderId? })` renders the HTML to
+  //    a PDF server-side (the host's headless-Chromium pipeline) and SAVES it
+  //    into the Filestore via `ctx.filestore.files.exportPdf`, resolving to the
+  //    created file row (`application/pdf`). Reuses the filestore owner_id
+  //    resolution + per-folder write gate; gated on the existing
+  //    `files.write:*` scope. The same server-side renderer backs the web
+  //    Player and the native export, so no browser-only PDF library is added
+  //    to the vetted set. No existing hook, primitive, manifest field, or
+  //    token changed shape — minor bump.
+  // 1.39.0: additive (sc-2327) — the `valueRef` propertySchema binding gains
+  //    an optional `mode` field: "static" (a pinned recordId, the default and
+  //    the only prior behaviour) or "latest" (the most recently created row,
+  //    resolved live by `created_at` desc with limit 1; recordId ignored). The
+  //    Field Value widget reads it to show a live "latest entry". Existing
+  //    bindings have no `mode` and read as static — additive, minor bump.
+  version: "1.39.0",
   sharedTranslationKeys: SHARED_TRANSLATION_KEYS,
   hooks: HOOKS,
   primitives: PRIMITIVES,

package/dist/contract.js

@@ -235,6 +235,29 @@ const HOOKS = [
     requiredContextSlice: ["filestore.files"],
     scopes: ["files.write:*"],
   },
+  {
+    name: "usePdfExport",
+    signature: "usePdfExport({ spaceType, folderId? })",
+    description:
+      "Render an HTML string to a PDF server-side and SAVE 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. " +
+      "`exportToPdf(html, { fileName?, folderId? })` resolves to the created " +
+      "file row (mime_type `application/pdf`) or throws the wire error; a 404 " +
+      "means the destination folder denied a write, a 413 that the rendered " +
+      "PDF exceeded the size cap. The HTML is rendered by the host's PDF " +
+      "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: {
+      exportToPdf: "(html, { fileName?, folderId? }) => Promise<FilestoreFile>",
+      exporting: "boolean",
+      error: "Error | null",
+      lastExported: "FilestoreFile | null",
+    },
+    requiredContextSlice: ["filestore.files"],
+    scopes: ["files.write:*"],
+  },
   {
     name: "useFilestoreFolders",
     signature: "useFilestoreFolders({ spaceType, parentFolderId?, q?, enabled? })",
@@ -975,9 +998,9 @@ const WIDGET_CONTEXT_SHAPE = {
   },
   user: {
     description:
-      "Signed-in user, host-provided VERBATIM (snake_case: { id, email, display_name, roles, group_ids }). Not a data-client.",
+      "Signed-in user, host-built context object (camelCase: { id, email, displayName, roles, groupIds }) — NOT a wire payload, so it is the one camelCase island among the hooks. Not a data-client.",
     required: true,
-    fields: { id: "string", email: "string", display_name: "string" },
+    fields: { id: "string", email: "string", displayName: "string" },
   },
   workspace: {
     description:
@@ -1824,7 +1847,24 @@ const CONTRACT = deepFreeze({
   //    the platform host, and an unknown slug / SSRF / timeout throws a
   //    catchable Error. New entry in ACTION_SCRIPT_GLOBALS only — no widget
   //    hook, primitive, manifest field, or token changed shape; minor bump.
-  version: "1.37.0",
+  //
+  // 1.38.0: additive (sc-2314) — new `usePdfExport({ spaceType, folderId? })`
+  //    hook. `exportToPdf(html, { fileName?, folderId? })` renders the HTML to
+  //    a PDF server-side (the host's headless-Chromium pipeline) and SAVES it
+  //    into the Filestore via `ctx.filestore.files.exportPdf`, resolving to the
+  //    created file row (`application/pdf`). Reuses the filestore owner_id
+  //    resolution + per-folder write gate; gated on the existing
+  //    `files.write:*` scope. The same server-side renderer backs the web
+  //    Player and the native export, so no browser-only PDF library is added
+  //    to the vetted set. No existing hook, primitive, manifest field, or
+  //    token changed shape — minor bump.
+  // 1.39.0: additive (sc-2327) — the `valueRef` propertySchema binding gains
+  //    an optional `mode` field: "static" (a pinned recordId, the default and
+  //    the only prior behaviour) or "latest" (the most recently created row,
+  //    resolved live by `created_at` desc with limit 1; recordId ignored). The
+  //    Field Value widget reads it to show a live "latest entry". Existing
+  //    bindings have no `mode` and read as static — additive, minor bump.
+  version: "1.39.0",
   sharedTranslationKeys: SHARED_TRANSLATION_KEYS,
   hooks: HOOKS,
   primitives: PRIMITIVES,

package/dist/hooks.js

@@ -113,7 +113,7 @@ export function useWidgetStyle() {
 
 /**
  * Returns the active end-user identity VERBATIM from the host, e.g.
- *   `{ id, email, display_name, roles, group_ids }` (snake_case fields).
+ *   `{ id, email, displayName, roles, groupIds }` (camelCase — host-built context, not a wire payload).
  *
  * `id` is `null` for anonymous visitors (and on the Studio canvas preview,
  * which renders widgets as if signed-out so the public branch shows). The
@@ -1578,6 +1578,87 @@ export function useFilestoreUpload(options) {
   return { upload, uploading, error, lastUploaded };
 }
 
+/**
+ * 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? }`);
+ * 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`.
+ *
+ * `exportToPdf(html, { fileName?, folderId? })` resolves to the created file
+ * record (`{ id, name, mime_type: "application/pdf", presigned_url, … }`).
+ * `fileName` defaults to `document.pdf` and is forced to a `.pdf` suffix by the
+ * backend. The HTML is rendered by the host's PDF service (headless Chromium)
+ * — the SAME server-side pipeline backs the web Player and the native export,
+ * so the capability behaves identically on both platforms (no browser-only PDF
+ * library is involved).
+ *
+ * A 404 means the destination folder denied a write; a 413 means the rendered
+ * PDF exceeded the size cap.
+ */
+export function usePdfExport(options) {
+  const ctx = useWidgetContextOrThrow("usePdfExport");
+  if (
+    !ctx.filestore ||
+    !ctx.filestore.files ||
+    typeof ctx.filestore.files.exportPdf !== "function"
+  ) {
+    throw new Error(
+      "usePdfExport: host did not inject a filestore client (ctx.filestore.files.exportPdf)",
+    );
+  }
+  const { spaceType = "project", folderId: defaultFolderId = null } = options || {};
+  const ownerId = _filestoreOwnerId(ctx, spaceType);
+
+  const [exporting, setExporting] = useState(false);
+  const [error, setError] = useState(null);
+  const [lastExported, setLastExported] = useState(null);
+
+  const filesRef = useRef(ctx.filestore.files);
+  filesRef.current = ctx.filestore.files;
+
+  const exportToPdf = useCallback(
+    async (html, overrides) => {
+      if (typeof html !== "string" || html.trim().length === 0) {
+        throw new Error("usePdfExport: html is required");
+      }
+      if (!ownerId) {
+        const err = new Error("Sign in to save a PDF");
+        setError(err);
+        throw err;
+      }
+      const folderId =
+        overrides && Object.prototype.hasOwnProperty.call(overrides, "folderId")
+          ? overrides.folderId
+          : defaultFolderId;
+      const fileName = overrides && overrides.fileName;
+      const body = {
+        html,
+        space_type: String(spaceType || "project").toUpperCase(),
+        owner_id: ownerId,
+      };
+      if (folderId) body.folder_id = folderId;
+      if (fileName) body.file_name = fileName;
+      setExporting(true);
+      setError(null);
+      try {
+        const created = await filesRef.current.exportPdf(body);
+        setLastExported(created || null);
+        setExporting(false);
+        return created;
+      } catch (err) {
+        setError(err);
+        setExporting(false);
+        throw err;
+      }
+    },
+    [ownerId, defaultFolderId, spaceType],
+  );
+
+  return { exportToPdf, exporting, error, lastExported };
+}
+
 /**
  * Browse the end-user's Filestore folders. Returns { folders, loading, error,
  * refetch }. Mirrors useFilestoreFiles for subfolder navigation: the widget

package/dist/index.d.ts

@@ -101,6 +101,12 @@ export interface ValueRefBinding {
   tableId?: string;
   recordId?: string;
   column?: string;
+  /**
+   * How the record is chosen. "static" (default, may be omitted) pins
+   * `recordId`; "latest" resolves the most recently created row live and
+   * ignores `recordId`.
+   */
+  mode?: "static" | "latest";
 }
 
 export interface WidgetEventDescriptor {
@@ -424,13 +430,13 @@ export interface WidgetContext<TProps = unknown> {
    * Absent / `false` everywhere the host has not opted the widget into filling.
    */
   fill?: boolean;
-  /** Active end-user identity, snake_case verbatim. `id` is null when anonymous. */
+  /** Active end-user identity from the host-built context (camelCase, not a wire payload). `id` is null when anonymous. */
   user: {
     id: string | null;
     email: string | null;
-    display_name: string | null;
+    displayName: string | null;
     roles: string[];
-    group_ids: string[];
+    groupIds: string[];
   };
   workspace: {
     id: string;
@@ -883,9 +889,9 @@ export function useI18n(): {
 export function useUser(): {
   id: string | null;
   email: string | null;
-  display_name: string | null;
+  displayName: string | null;
   roles: string[];
-  group_ids: string[];
+  groupIds: string[];
 };
 
 /**

package/dist/index.js

@@ -19,6 +19,7 @@ export {
   useAssetsByTag,
   useFilestoreFiles,
   useFilestoreUpload,
+  usePdfExport,
   useFilestoreFolders,
   useFileSignature,
   useFileSignatures,

package/dist/index.native.js

@@ -19,6 +19,7 @@ export {
   useAssetsByTag,
   useFilestoreFiles,
   useFilestoreUpload,
+  usePdfExport,
   useFilestoreFolders,
   useFileSignature,
   useFileSignatures,

package/dist/property-schema.js

@@ -183,10 +183,12 @@ function coerceLeaf(def, value, path, errors) {
       }
       return value.map((item, i) => coerceLeaf(def.items, item, `${path}[${i}]`, errors));
     case "valueRef": {
-      // REQ-WDG-VALUEREF: a `{ tableId, recordId, column }` binding. Each
-      // sub-field is an optional string (a half-configured binding is valid
+      // REQ-WDG-VALUEREF: a `{ tableId, recordId, column, mode }` binding.
+      // Each string sub-field is optional (a half-configured binding is valid
       // while the author is still picking); the bound widget treats any
-      // missing piece as "no value" and shows its fallback.
+      // missing piece as "no value" and shows its fallback. sc-2327: `mode`
+      // selects how the record is chosen — "static" (a pinned recordId, the
+      // default) or "latest" (the newest row, resolved live; recordId ignored).
       if (!isPlainObject(value)) {
         errors.push(`${path}: expected object`);
         return value;
@@ -197,6 +199,14 @@ function coerceLeaf(def, value, path, errors) {
           errors.push(`${path}.${sub}: expected string`);
         }
       }
+      if (
+        value.mode !== undefined &&
+        value.mode !== null &&
+        value.mode !== "static" &&
+        value.mode !== "latest"
+      ) {
+        errors.push(`${path}.mode: expected "static" or "latest"`);
+      }
       return value;
     }
     case "object": {

package/package.json

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