@colixsystems/widget-sdk 0.58.0 → 0.60.0

package/README.md

@@ -52,7 +52,15 @@ See the design reference for the full architecture: [`docs/architecture/widget-m
 
 ## Status
 
-`v0.58.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.60.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.60.0
+
+**The host fills `propertySchema` defaults onto props (sc-3228).** The platform host now applies a widget's manifest `default`s at its render boundary: for every leaf a page left unset it substitutes the declared `default`; an explicitly-bound value passes through untouched. The web Player and the native Expo export both do this against the widget's `propertySchema`, so an unset `columnRef` / field binding arrives as its declared default (e.g. `"Title"`) on BOTH hosts instead of `undefined`. **For widget authors this means: read `props.<field>` directly — the in-code `props.titleField || "Title"` fallback pattern is no longer needed and should be removed.** This is done for you by the host; there is no author API to call. (The resolver lives at the host-only subpath `@colixsystems/widget-sdk/host`, consumed by the platform hosts, not by widgets.) `CONTRACT.version` → `1.41.0`. Additive — no existing export changed signature.
+
+### What's new in 0.59.0
+
+**Display a stored file by id — `useFilestoreFile(fileId)` (sc-3031).** A new FILESTORE read hook that resolves ONE file id to a displayable URL. Given a file id the app stored — chiefly a datastore `FILE` column, which holds a filestore file id (a string), never bytes — it fetches the record via `ctx.filestore.files.get(id)` and returns `{ file, url, loading, error, refetch }`, where `url` is the record's `presigned_url` absolutized by the client so it renders on the web Player **and** the native Expo export alike. Drop `url` straight into `<Image source={{ uri: url }} />`. An empty id makes no round-trip (`{ file: null, url: null }`); a deleted / not-found id degrades the same way (`url` stays null, `error` carries the wire error) so a display widget shows its fallback instead of crashing. This closes the upload→store→display loop: `useFilestoreUpload(...).upload(file)` → write `file.id` into the `FILE` column → `useFilestoreFile(id).url` to show it. Requires the `files.read:*` scope. `CONTRACT.version` → `1.40.0`. Additive — one new read hook; no existing export changed signature.
 
 ### What's new in 0.58.0
 
@@ -210,6 +218,7 @@ Also: `useFileSignatures(fileIds)` is now **self-scoped** (the caller's own sign
 
 **Filestore browsing + BankID file signing for widgets (REQ-FS / REQ-SIGN).** Three new hooks read a newly-injected `ctx.filestore` (the `@colixsystems/filestore-client`, now constructed by both the web and native hosts):
 - `useFilestoreFiles({ spaceType, folderId?, q?, type? })` → `{ files, loading, error, refetch }` — browses the end-user's Filestore space. The hook resolves `owner_id` from the host context (tenant for a project space, the app user for a personal space), so the widget only picks the space.
+- `useFilestoreFile(fileId)` → `{ file, url, loading, error, refetch }` — resolves ONE file id to a displayable `url` (its `presigned_url`, absolutized for web + native) via `ctx.filestore.files.get(id)`. A datastore `FILE` column holds — and reads back as — that **bare file-id string**; it is NOT hydrated into an object the way a `RELATION` (`{ id, label }`) or `USER` (`{ id, name }`) column is, so pass the value straight to the hook (no `{ id }` / `{ url }` unwrapping guard). Empty / deleted / not-found ids resolve to `url: null` so a display widget shows a fallback. Requires `files.read:*`.
 - `useFilestoreFolders({ spaceType, parentFolderId?, q?, enabled? })` → `{ folders, loading, error, refetch }` — the folder-navigation companion to `useFilestoreFiles`; pass `enabled:false` to suspend fetching.
 - `useFilestoreUpload({ spaceType, folderId? })` → `{ upload, uploading, error, lastUploaded }` — POSTs a multipart upload to `ctx.filestore.files.upload`. Resolves `owner_id` from the host context (like the read hooks) so the widget only picks the space + destination folder. Pair with the `<FilePicker>` primitive for the visible trigger. Requires the `files.write:*` scope.
 - `useFileSignature(fileId)` → `{ status, qr, signerName, verdict, initiate, refresh, cancel, verify, … }` — drives a BankID signing flow for a file (the backend hashes the bytes server-side, binds the digest into the signature, and verifies the proof offline).

package/dist/contract.cjs

@@ -214,6 +214,29 @@ const HOOKS = [
     requiredContextSlice: ["filestore.files"],
     scopes: ["files.read:*"],
   },
+  {
+    name: "useFilestoreFile",
+    signature: "useFilestoreFile(fileId)",
+    description:
+      "Resolve ONE Filestore file id to a displayable URL. Given a file id " +
+      "the app stored (e.g. a datastore FILE column, which holds a filestore " +
+      "file id — never bytes), the hook fetches the record via " +
+      "ctx.filestore.files.get(id) and surfaces its `presigned_url` as `url`, " +
+      "ready to drop into <Image source={{ uri: url }} />. The URL is " +
+      "absolutized by the client so it loads on web AND native. An empty id " +
+      "collapses to { file: null, url: null } with no round-trip; a deleted / " +
+      "not-found id degrades the same way (url stays null, error carries the " +
+      "wire error) so a display widget shows its fallback instead of crashing.",
+    returnShape: {
+      file: "FilestoreFile | null",
+      url: "string | null",
+      loading: "boolean",
+      error: "Error | null",
+      refetch: "() => Promise<void>",
+    },
+    requiredContextSlice: ["filestore.files"],
+    scopes: ["files.read:*"],
+  },
   {
     name: "useFilestoreUpload",
     signature: "useFilestoreUpload({ spaceType, folderId? })",
@@ -1864,7 +1887,18 @@ const CONTRACT = deepFreeze({
   //    resolved live by `created_at` desc with limit 1; recordId ignored). The
   //    Data 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",
+  // 1.40.0: additive (sc-3031) — `useFilestoreFile(fileId)` resolves one
+  //    filestore file id (as held in a datastore FILE column) to a
+  //    displayable `url` (its presigned_url, absolutized for web + native).
+  //    New read hook, no existing behaviour changes — minor bump.
+  // 1.41.0: additive (sc-3228) — the host (web Player + native export) now
+  //    fills a widget's propertySchema `default`s onto props at the render
+  //    boundary, so an unset `columnRef` / field binding arrives as its declared
+  //    default instead of undefined. A widget reads `props.<field>` directly —
+  //    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",
   sharedTranslationKeys: SHARED_TRANSLATION_KEYS,
   hooks: HOOKS,
   primitives: PRIMITIVES,

package/dist/contract.js

@@ -214,6 +214,29 @@ const HOOKS = [
     requiredContextSlice: ["filestore.files"],
     scopes: ["files.read:*"],
   },
+  {
+    name: "useFilestoreFile",
+    signature: "useFilestoreFile(fileId)",
+    description:
+      "Resolve ONE Filestore file id to a displayable URL. Given a file id " +
+      "the app stored (e.g. a datastore FILE column, which holds a filestore " +
+      "file id — never bytes), the hook fetches the record via " +
+      "ctx.filestore.files.get(id) and surfaces its `presigned_url` as `url`, " +
+      "ready to drop into <Image source={{ uri: url }} />. The URL is " +
+      "absolutized by the client so it loads on web AND native. An empty id " +
+      "collapses to { file: null, url: null } with no round-trip; a deleted / " +
+      "not-found id degrades the same way (url stays null, error carries the " +
+      "wire error) so a display widget shows its fallback instead of crashing.",
+    returnShape: {
+      file: "FilestoreFile | null",
+      url: "string | null",
+      loading: "boolean",
+      error: "Error | null",
+      refetch: "() => Promise<void>",
+    },
+    requiredContextSlice: ["filestore.files"],
+    scopes: ["files.read:*"],
+  },
   {
     name: "useFilestoreUpload",
     signature: "useFilestoreUpload({ spaceType, folderId? })",
@@ -1864,7 +1887,18 @@ const CONTRACT = deepFreeze({
   //    resolved live by `created_at` desc with limit 1; recordId ignored). The
   //    Data 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",
+  // 1.40.0: additive (sc-3031) — `useFilestoreFile(fileId)` resolves one
+  //    filestore file id (as held in a datastore FILE column) to a
+  //    displayable `url` (its presigned_url, absolutized for web + native).
+  //    New read hook, no existing behaviour changes — minor bump.
+  // 1.41.0: additive (sc-3228) — the host (web Player + native export) now
+  //    fills a widget's propertySchema `default`s onto props at the render
+  //    boundary, so an unset `columnRef` / field binding arrives as its declared
+  //    default instead of undefined. A widget reads `props.<field>` directly —
+  //    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",
   sharedTranslationKeys: SHARED_TRANSLATION_KEYS,
   hooks: HOOKS,
   primitives: PRIMITIVES,

package/dist/hooks.js

@@ -1502,6 +1502,80 @@ export function useFilestoreFiles(options) {
   return { files, loading, error, refetch };
 }
 
+/**
+ * sc-3031 — resolve ONE Filestore file id to a displayable URL. Returns
+ * `{ file, url, loading, error, refetch }`. Given a file id the app stored
+ * (e.g. a datastore FILE column, which holds a filestore file id — never
+ * bytes), the hook fetches the file record via `ctx.filestore.files.get(id)`
+ * and surfaces its `presigned_url` as `url`, ready to drop straight into an
+ * `<Image source={{ uri: url }} />`. The URL is absolutized by the filestore
+ * client, so it loads on the web Player AND the native export.
+ *
+ * An empty / null id collapses to `{ file: null, url: null }` with no network
+ * round-trip; a deleted or not-found id degrades the same way (`url` stays
+ * null and `error` carries the wire error) so a display widget shows its
+ * fallback instead of crashing.
+ */
+export function useFilestoreFile(fileId) {
+  const ctx = useWidgetContextOrThrow("useFilestoreFile");
+  if (
+    !ctx.filestore ||
+    !ctx.filestore.files ||
+    typeof ctx.filestore.files.get !== "function"
+  ) {
+    throw new Error(
+      "useFilestoreFile: host did not inject a filestore client (ctx.filestore.files.get)",
+    );
+  }
+
+  const [file, setFile] = useState(null);
+  const [loading, setLoading] = useState(Boolean(fileId));
+  const [error, setError] = useState(null);
+
+  const filesRef = useRef(ctx.filestore.files);
+  filesRef.current = ctx.filestore.files;
+  const idRef = useRef(fileId);
+  idRef.current = fileId;
+  const runRef = useRef(0);
+
+  const doFetch = useCallback(async () => {
+    const myRun = ++runRef.current;
+    const id = idRef.current;
+    if (!id) {
+      setLoading(false);
+      setError(null);
+      setFile(null);
+      return;
+    }
+    setLoading(true);
+    setError(null);
+    try {
+      const row = await filesRef.current.get(id);
+      if (runRef.current !== myRun) return;
+      setFile(row || null);
+      setLoading(false);
+    } catch (err) {
+      if (runRef.current !== myRun) return;
+      setError(err);
+      setFile(null);
+      setLoading(false);
+    }
+  }, []);
+
+  useEffect(() => {
+    doFetch();
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [fileId]);
+
+  const refetch = useCallback(async () => {
+    await doFetch();
+  }, [doFetch]);
+
+  const url =
+    file && typeof file.presigned_url === "string" ? file.presigned_url : null;
+  return { file, url, loading, error, refetch };
+}
+
 /**
  * sc-1378 — upload a file into the end-user's Filestore space. Returns
  * `{ upload, uploading, error, lastUploaded }`. The widget passes the

package/dist/host.d.ts

@@ -0,0 +1,13 @@
+// Host-integration surface — not the author-facing widget API. See host.js.
+import type { WidgetPropertySchema } from "./index";
+
+/**
+ * Host render-boundary helper: fills a widget's propertySchema `default`s onto
+ * props for unset (undefined/null) leaves; explicitly-bound values pass
+ * through. Never validates or coerces; always returns the merged object.
+ * Applied by the platform hosts, never by widget authors.
+ */
+export function resolveProps<T = Record<string, unknown>>(
+  schema: WidgetPropertySchema,
+  props: unknown,
+): T;

package/dist/host.js

@@ -0,0 +1,12 @@
+// Host-integration surface — NOT part of the author-facing widget API.
+// These exports are consumed only by the platform hosts that render widgets
+// (the web Player / Studio Canvas and the native Expo export), never by a
+// widget author. Authors receive already-correct props and never call these.
+//
+// `resolveProps` lives here (re-exported from property-schema.js, the single
+// source of schema semantics) so the host can fill a widget's declared
+// propertySchema `default`s onto props at its render boundary. It is
+// deliberately kept off the main entry (`@colixsystems/widget-sdk`) so it does
+// not appear in the author import surface or the Developer guide.
+
+export { resolveProps } from "./property-schema.js";

package/dist/index.js

@@ -18,6 +18,7 @@ export {
   useAsset,
   useAssetsByTag,
   useFilestoreFiles,
+  useFilestoreFile,
   useFilestoreUpload,
   usePdfExport,
   useFilestoreFolders,

package/dist/index.native.js

@@ -18,11 +18,14 @@ export {
   useAsset,
   useAssetsByTag,
   useFilestoreFiles,
+  useFilestoreFile,
   useFilestoreUpload,
   usePdfExport,
   useFilestoreFolders,
   useFileSignature,
   useFileSignatures,
+  useFileRoster,
+  useFolderPermissions,
   useDatastoreMutation,
   useDirectory,
   useUsers,

package/dist/property-schema.js

@@ -243,3 +243,56 @@ export function validateProps(schema, props) {
   }
   return errors.length === 0 ? { ok: true, value: out } : { ok: false, errors };
 }
+
+// Defaults are static config; clone object/array ones so a widget mutating
+// its props can never corrupt the shared manifest default.
+function cloneDefault(value) {
+  if (value === null || typeof value !== "object") return value;
+  return JSON.parse(JSON.stringify(value));
+}
+
+function resolveLeaf(def, value) {
+  if (!isPlainObject(def)) return value;
+  if (value === undefined || value === null) {
+    return def.default !== undefined ? cloneDefault(def.default) : value;
+  }
+  if (
+    def.type === "object" &&
+    isPlainObject(def.properties) &&
+    isPlainObject(value)
+  ) {
+    const out = { ...value };
+    for (const [k, child] of Object.entries(def.properties)) {
+      out[k] = resolveLeaf(child, value[k]);
+    }
+    return out;
+  }
+  // Fill per-element defaults for an author-supplied array<object> (e.g. a
+  // `columns` list whose item objects carry field-level defaults).
+  if (def.type === "array" && isPlainObject(def.items) && Array.isArray(value)) {
+    return value.map((item) => resolveLeaf(def.items, item));
+  }
+  return value;
+}
+
+/**
+ * Fills in a widget's `propertySchema` defaults on `props` for the host render
+ * boundary: any leaf the author left unset (undefined/null) takes its declared
+ * `default`; an explicitly-set value passes through untouched. Unlike
+ * {@link validateProps} it never validates or coerces and always returns the
+ * merged object — a partially-configured binding stays valid while the author
+ * is still picking. Applied once by the host (web Player + native export) so a
+ * widget reads `props.<field>` directly without in-code fallbacks.
+ * @param {Record<string, any>} schema
+ * @param {unknown} props
+ * @returns {Record<string, unknown>}
+ */
+export function resolveProps(schema, props) {
+  const input = isPlainObject(props) ? props : {};
+  if (!isPlainObject(schema)) return input;
+  const out = { ...input };
+  for (const [k, def] of Object.entries(schema)) {
+    out[k] = resolveLeaf(def, input[k]);
+  }
+  return out;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@colixsystems/widget-sdk",
-  "version": "0.58.0",
+  "version": "0.60.0",
   "description": "Common widget interface for AppStudio. Implements WidgetManifest, WidgetContext, property schema, and helper hooks.",
   "type": "module",
   "main": "./dist/index.js",
@@ -22,6 +22,12 @@
       "import": "./dist/dev-shims.js",
       "default": "./dist/dev-shims.js"
     },
+    "./host": {
+      "types": "./dist/host.d.ts",
+      "react-native": "./dist/host.js",
+      "import": "./dist/host.js",
+      "default": "./dist/host.js"
+    },
     "./contract": {
       "types": "./dist/index.d.ts",
       "require": "./dist/contract.cjs",
@@ -42,7 +48,7 @@
   ],
   "scripts": {
     "build": "node scripts/build.js",
-    "test": "node --test src/__tests__/contract.test.js src/__tests__/hooks-users.test.js src/__tests__/hooks-groups.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-mutation.test.js src/__tests__/hooks-record-permissions.test.js src/__tests__/hooks-geolocation.test.js src/__tests__/hooks-subscription.test.js src/__tests__/linter-users-scope.test.js src/__tests__/linter-comments.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__/devserver.test.js src/__tests__/host-externals.test.js src/__tests__/datetimepicker.test.js"
+    "test": "node --test src/__tests__/contract.test.js src/__tests__/hooks-users.test.js src/__tests__/hooks-groups.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-mutation.test.js src/__tests__/hooks-record-permissions.test.js src/__tests__/hooks-geolocation.test.js src/__tests__/hooks-subscription.test.js src/__tests__/linter-users-scope.test.js src/__tests__/linter-comments.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__/devserver.test.js src/__tests__/host-externals.test.js src/__tests__/datetimepicker.test.js src/__tests__/property-schema-resolve.test.js"
   },
   "engines": {
     "node": ">=18"