@colixsystems/widget-sdk 0.59.0 → 0.60.0

package/README.md

@@ -52,7 +52,11 @@ See the design reference for the full architecture: [`docs/architecture/widget-m
 
 ## Status
 
-`v0.59.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
 
@@ -214,7 +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 (as held in a datastore `FILE` column) to a displayable `url` (its `presigned_url`, absolutized for web + native) via `ctx.filestore.files.get(id)`. Empty / deleted / not-found ids resolve to `url: null` so a display widget shows a fallback. Requires `files.read:*`.
+- `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

@@ -1891,7 +1891,14 @@ const CONTRACT = deepFreeze({
   //    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.
-  version: "1.40.0",
+  // 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

@@ -1891,7 +1891,14 @@ const CONTRACT = deepFreeze({
   //    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.
-  version: "1.40.0",
+  // 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/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.native.js

@@ -24,6 +24,8 @@ export {
   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.59.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"