@colixsystems/widget-sdk 0.57.0 → 0.59.0

package/README.md

@@ -52,7 +52,15 @@ See the design reference for the full architecture: [`docs/architecture/widget-m
 
 ## Status
 
-`v0.57.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.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**.
+
+### 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
+
+**Filter the directory by group (sc-2964).** `useDirectory(query?)` and `useUsers(query?)` gain an optional `group_id` on the query object (`{ q?, role?, is_active?, group_id?, limit?, offset? }`). Pass the `id` of a `useGroups()` row to list only that group's members — pair it with a group picker to build "members of group X". A `group_id` from another tenant or a non-existent one returns an empty roster, never a cross-tenant member. The `DirectoryQuery` / `UsersQuery` types add `group_id?: string`; existing callers pass no `group_id` and see the full roster. No scope, manifest field, import, or hook signature changed — `CONTRACT` is unchanged; the query flows verbatim through the injected `@colixsystems/directory-client` on both the web Player and the native Expo export.
 
 ### What's new in 0.57.0
 
@@ -206,6 +214,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:*`.
 - `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).
@@ -454,6 +463,7 @@ A widget that works but looks unfinished is only half done. `useTheme()` is the
 
 - **Pull spacing and corners from tokens.** Use `theme.spacing` (`xs / sm / md / lg / xl`) for a consistent padding and gap rhythm, and `theme.radii` (`sm / md / lg / pill`) for corners. Don't hardcode raw pixel values.
 - **Build a hierarchy.** A clear title (large, bold, `colors.onSurface`), body text, and muted captions in `colors.onSurfaceMuted` — three weights, not one flat size. Reserve `colors.primary` (with `colors.onPrimary` for text on it) for the single most important action or metric.
+- **Set the theme font on every `Text`.** React Native `Text` does not inherit `fontFamily` from a parent, so a text element that omits it falls back to the system font and ignores the workspace's configured font. Put `theme.typography.fontFamily` on every text style (a shared `StyleSheet` built from `theme` keeps it in one place) and size text with `theme.typography.sizes`.
 - **Contain and elevate.** Wrap a logical unit in a surface: `colors.surface` + padding + `radii.md` + a `colors.border` hairline or a subtle shadow. Use the status roles (`danger / success / warning / info`) for state.
 - **Respond to touch.** Give every `Pressable` a pressed state via the function-style `style={({ pressed }) => [base, pressed && { opacity: 0.7 }]}`.
 - **Use icons for clarity.** Pair a `lucide-react-native` icon with its label at a consistent size, coloured from the theme.

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,11 @@ 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.
+  version: "1.40.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,11 @@ 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.
+  version: "1.40.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
@@ -2221,8 +2295,10 @@ function toDirectoryError(err) {
  * users is NOT part of this surface; the directory is read-only here (see
  * useUsers for administration).
  *
- * `query` is an optional `{ q?, role?, is_active?, limit?, offset? }`
- * object passed through verbatim. The hook re-fetches whenever
+ * `query` is an optional `{ q?, role?, is_active?, group_id?, limit?, offset? }`
+ * object passed through verbatim. `group_id` (the `id` of a `useGroups()` row)
+ * restricts the roster to that group's members — pair it with a group picker to
+ * build "members of group X". The hook re-fetches whenever
  * `JSON.stringify(query)` changes and exposes `refetch` for on-demand
  * reloads (e.g. a chat roster refresh).
  *
@@ -2300,8 +2376,10 @@ export function useDirectory(query) {
  * invite, deactivate, reactivate}` — `list` resolves to the `{ data, meta }`
  * envelope VERBATIM, so we unwrap `res.data` (default `[]`). User rows are
  * snake_case (`id`, `name`, `email`, `role`, `is_active`, …) and bodies
- * (e.g. `{ email, name, group_ids? }`) pass through verbatim. The list
- * refetches whenever `JSON.stringify(query)` changes; the imperative methods
+ * (e.g. `{ email, name, group_ids? }`) pass through verbatim. `query` is an
+ * optional `{ q?, role?, is_active?, group_id?, limit?, offset? }`; `group_id`
+ * (the `id` of a `useGroups()` row) narrows the list to that group's members.
+ * The list refetches whenever `JSON.stringify(query)` changes; the imperative methods
  * reject with a `DirectoryError`. Reads require the `users.read:*` scope;
  * mutations additionally require `users.write:*`. The host's signed
  * `X-Widget-Scopes` header + a tenant-scoped SystemAcl `users.read` /

package/dist/index.d.ts

@@ -585,6 +585,11 @@ export interface DirectoryQuery {
   role?: "USER" | "INTEGRATION" | "ALL";
   /** Filter by active state (snake_case on the wire). */
   is_active?: boolean;
+  /**
+   * Restrict the roster to members of one app-user group — the `id` of a
+   * `useGroups()` row. Pair with a group picker to build "members of group X".
+   */
+  group_id?: string;
   limit?: number;
   offset?: number;
 }
@@ -1082,6 +1087,8 @@ export interface UsersQuery {
   q?: string;
   role?: "USER" | "INTEGRATION" | "ALL";
   is_active?: boolean;
+  /** Restrict to members of one app-user group — the `id` of a `useGroups()` row. */
+  group_id?: string;
   limit?: number;
   offset?: number;
 }

package/dist/index.js

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

package/dist/index.native.js

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

package/package.json

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