@colixsystems/widget-sdk 0.41.0 → 0.43.0

package/README.md

@@ -8,7 +8,7 @@ The data layer lives in **four separate domain-client packages**, each instantia
 | ----------- | ------- | -------- |
 | `ctx.datastore` | `@colixsystems/datastore-client` | `tables.{list,get}`, `schema(tableId)`, `records(tableId).{ list(query), get(id), create(values), update(id,values) [PATCH], delete(id), aggregate(spec), permissions(recordId).{ list, grant, update, revoke } }` |
 | `ctx.directory` | `@colixsystems/directory-client` | `me()`, `users.{list,get,invite,deactivate,reactivate}`, `groups.{list,create,remove,addMember,removeMember,listMine}`, `invites.{list,revoke,resend}` |
-| `ctx.assets` | `@colixsystems/assets-client` | the Asset Manager: `get(id)`, `list(query)`, `upload(formData)` over `/files` — what `useAsset()` resolves |
+| `ctx.assets` | `@colixsystems/assets-client` | the Asset Manager: `get(id)`, `list(query)`, `upload(formData)` over `/files` — what `useAsset()` (single asset by id) and `useAssetsByTag()` (every asset carrying a tag) resolve |
 | `ctx.payments` | `@colixsystems/payments-client` | `requestPayment(body)`, `getPayment(id)` |
 
 **Wire / casing: snake_case end to end.** The clients send and return snake_case **verbatim** (`created_at`, `group_ids`, `can_read`, `amount_cents`, `data_type`, `is_active`, …). There is **no case transform anywhere** — not on the client and not in the backend; the only casing boundary is Prisma `@map` (snake_case field → camelCase column). Author-defined record column values pass through verbatim. Every `list(...)` returns the `{ data, meta }` envelope; the read hooks unwrap `res.data` for you.
@@ -34,6 +34,7 @@ The data layer lives in **four separate domain-client packages**, each instantia
 | **DATASTORE** | `useDatastoreMutation(table)` | `{ create, update, delete }` | `records(table).{ create, update (PATCH), delete }` — `datastore.write:*` |
 | **DATASTORE** | `useRecordPermissions(tableId, recordId)` | `{ permissions, loading, error, grant, revoke, update, refetch }` | `records(table).permissions(record).{ list, grant, update, revoke }` — `acl.write:records` (+ `can_grant` on the record) |
 | **FILES** (`ctx.assets`) | `useAsset(id)` | `{ url, file, loading, error, refetch }` | `ctx.assets.get` — no scope |
+| **FILES** | `useAssetsByTag(tag, { type? })` | `{ assets, loading, error, refetch }` | `ctx.assets.list` (unwraps `{ data, meta }` to `assets`) — no scope. `type` defaults to `"image"`; pass `"all"` / `"audio"` / `"video"` / `"document"` to widen. Falsy `tag` collapses to `assets: []` without a round-trip. |
 | **DIRECTORY** (`ctx.directory`) | `useDirectory(query?)` | `{ users, loading, error, refetch }` | `directory.users.list` — `directory.read:users` |
 | **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:*`) |
@@ -48,7 +49,15 @@ See the design reference for the full architecture: [`docs/architecture/widget-m
 
 ## Status
 
-`v0.41.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.43.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.43.0
+
+**New `useAssetsByTag(tag, { type? })` hook (sc-1241).** Lists every tenant asset carrying a given tag — backs the built-in Gallery widget's "All images with a tag" source mode (which used to render a stub) and is a general SDK primitive any widget can call (an audio playlist filtered by mood, a document index by category, an image wall by topic). Reads `ctx.assets.list({ tag, type, limit })` (already injected by both the web Player and the native Expo export) and unwraps `{ data, meta }`. `type` defaults to `"image"` so the common Gallery case gets only images back; pass `"all"` (or `"audio"` / `"video"` / `"document"`) to widen. Falsy `tag` collapses to `assets: []` without a network round-trip. Additive — `CONTRACT.version` bumped to 1.30.0. The `assets` context slice grows a new required field `list: "function"` (both hosts already inject it).
+
+### What's new in 0.42.0
+
+**RELATION columns hydrate with a display label (sc-1181).** Record reads now return `{ id, label }` for ONE_TO_ONE / ONE_TO_MANY and `[{ id, label }, ...]` for MANY_TO_MANY (empty array when no links) — `label` is the value of the column pointed at by the new optional `display_column_id` on `DatastoreSchemaColumn`, or, when unset, the first STRING/TEXT column on the target table. Widgets should render `record.<rel>.label` (or `record.<rel>.map(r => r.label).join(", ")` for M:M) directly; `.id` is still there for the foreign-key case. The cell-formatting helpers in the built-in `DataList`, `TabbedDatalist`, and `FieldValue` widgets already walk arrays and prefer `label` over `name` / `id` — author widgets that need the same can copy that pattern. `CONTRACT.version` is unchanged.
 
 ### What's new in 0.41.0
 

package/dist/contract.cjs

@@ -175,6 +175,28 @@ const HOOKS = [
     requiredContextSlice: ["assets.get"],
     scopes: null,
   },
+  {
+    name: "useAssetsByTag",
+    signature: "useAssetsByTag(tag, { type? } = {})",
+    description:
+      "List every tenant asset carrying a given tag. Backs the Gallery " +
+      "widget's tag-source mode but is a general SDK primitive — any widget " +
+      "can render a collection of assets the author groups by tag (image " +
+      "wall, audio playlist filtered by mood, document index by category). " +
+      "Reads ctx.assets.list({ tag, type, limit }) and unwraps the " +
+      "{ data, meta } envelope to the assets array. When tag is falsy the " +
+      "hook collapses to an empty result without a network round-trip. " +
+      "type defaults to 'image' so a Gallery using it gets only images " +
+      "back; pass type: 'all' (or 'audio' / 'video' / 'document') to widen.",
+    returnShape: {
+      assets: "Asset[]",
+      loading: "boolean",
+      error: "DatastoreError | null",
+      refetch: "() => Promise<void>",
+    },
+    requiredContextSlice: ["assets.list"],
+    scopes: null,
+  },
   {
     name: "useFilestoreFiles",
     signature: "useFilestoreFiles({ spaceType, folderId?, q?, type? })",
@@ -924,9 +946,9 @@ const WIDGET_CONTEXT_SHAPE = {
     description:
       "Injected @colixsystems/assets-client instance, FLATTENED so asset ops are top-level. " +
       "{ get(id) -> Promise<{ id, url, ... }>, list(query) -> Promise<{ data, meta }>, upload(formData) }. " +
-      "Backs useAsset(); the returned asset already carries an absolute url the widget can drop into an <Image source>.",
+      "Backs useAsset() (resolve one asset by id) and useAssetsByTag() (list every tenant asset carrying a tag); the returned assets already carry absolute urls the widget can drop into an <Image source>.",
     required: true,
-    fields: { get: "function" },
+    fields: { get: "function", list: "function" },
   },
   filestore: {
     description:
@@ -1627,7 +1649,16 @@ const CONTRACT = deepFreeze({
   //    useDatastoreRecord / useAsset) auto-subscribe their own `refetch`.
   //    No existing hook, primitive, manifest field, or token changed shape
   //    — minor bump on the pre-1.0 channel.
-  version: "1.29.0",
+  //
+  // 1.30.0: additive (sc-1241) — `useAssetsByTag(tag, { type? })` lists every
+  //    tenant asset carrying a given tag. Backs the Gallery widget's
+  //    "All images with a tag" source mode (which used to render a stub),
+  //    but is a general SDK primitive any widget can call. Reads
+  //    `ctx.assets.list({ tag, type, limit })` (already injected by both
+  //    hosts) and unwraps `{ data, meta }`. New required field on the
+  //    `assets` context slice: `list: "function"`. No existing hook,
+  //    primitive, manifest field, or token changed shape — minor bump.
+  version: "1.30.0",
   sharedTranslationKeys: SHARED_TRANSLATION_KEYS,
   hooks: HOOKS,
   primitives: PRIMITIVES,

package/dist/contract.js

@@ -175,6 +175,28 @@ const HOOKS = [
     requiredContextSlice: ["assets.get"],
     scopes: null,
   },
+  {
+    name: "useAssetsByTag",
+    signature: "useAssetsByTag(tag, { type? } = {})",
+    description:
+      "List every tenant asset carrying a given tag. Backs the Gallery " +
+      "widget's tag-source mode but is a general SDK primitive — any widget " +
+      "can render a collection of assets the author groups by tag (image " +
+      "wall, audio playlist filtered by mood, document index by category). " +
+      "Reads ctx.assets.list({ tag, type, limit }) and unwraps the " +
+      "{ data, meta } envelope to the assets array. When tag is falsy the " +
+      "hook collapses to an empty result without a network round-trip. " +
+      "type defaults to 'image' so a Gallery using it gets only images " +
+      "back; pass type: 'all' (or 'audio' / 'video' / 'document') to widen.",
+    returnShape: {
+      assets: "Asset[]",
+      loading: "boolean",
+      error: "DatastoreError | null",
+      refetch: "() => Promise<void>",
+    },
+    requiredContextSlice: ["assets.list"],
+    scopes: null,
+  },
   {
     name: "useFilestoreFiles",
     signature: "useFilestoreFiles({ spaceType, folderId?, q?, type? })",
@@ -924,9 +946,9 @@ const WIDGET_CONTEXT_SHAPE = {
     description:
       "Injected @colixsystems/assets-client instance, FLATTENED so asset ops are top-level. " +
       "{ get(id) -> Promise<{ id, url, ... }>, list(query) -> Promise<{ data, meta }>, upload(formData) }. " +
-      "Backs useAsset(); the returned asset already carries an absolute url the widget can drop into an <Image source>.",
+      "Backs useAsset() (resolve one asset by id) and useAssetsByTag() (list every tenant asset carrying a tag); the returned assets already carry absolute urls the widget can drop into an <Image source>.",
     required: true,
-    fields: { get: "function" },
+    fields: { get: "function", list: "function" },
   },
   filestore: {
     description:
@@ -1627,7 +1649,16 @@ const CONTRACT = deepFreeze({
   //    useDatastoreRecord / useAsset) auto-subscribe their own `refetch`.
   //    No existing hook, primitive, manifest field, or token changed shape
   //    — minor bump on the pre-1.0 channel.
-  version: "1.29.0",
+  //
+  // 1.30.0: additive (sc-1241) — `useAssetsByTag(tag, { type? })` lists every
+  //    tenant asset carrying a given tag. Backs the Gallery widget's
+  //    "All images with a tag" source mode (which used to render a stub),
+  //    but is a general SDK primitive any widget can call. Reads
+  //    `ctx.assets.list({ tag, type, limit })` (already injected by both
+  //    hosts) and unwraps `{ data, meta }`. New required field on the
+  //    `assets` context slice: `list: "function"`. No existing hook,
+  //    primitive, manifest field, or token changed shape — minor bump.
+  version: "1.30.0",
   sharedTranslationKeys: SHARED_TRANSLATION_KEYS,
   hooks: HOOKS,
   primitives: PRIMITIVES,

package/dist/hooks.js

@@ -1197,6 +1197,80 @@ export function useAsset(assetId) {
   return { url, asset, loading, error, refetch };
 }
 
+/**
+ * List every tenant asset carrying a given tag. Returns
+ * `{ assets, loading, error, refetch }`. The widget passes a single `tag`
+ * string plus an optional `{ type }` filter (defaults to `"image"` so the
+ * common gallery case gets only images back; pass `"all"` / `"audio"` /
+ * `"video"` / `"document"` to widen). The hook calls
+ * `ctx.assets.list({ tag, type, limit: 1000 })` and unwraps the
+ * `{ data, meta }` envelope to the array. When `tag` is falsy or whitespace
+ * the hook collapses to an empty result without a network round-trip.
+ *
+ * Like `useAsset`, every returned row already carries an absolute `url` the
+ * widget can drop into `<Image source>`.
+ */
+export function useAssetsByTag(tag, options) {
+  const ctx = useWidgetContextOrThrow("useAssetsByTag");
+  if (!ctx.assets || typeof ctx.assets.list !== "function") {
+    throw new Error(
+      "useAssetsByTag: host did not inject an assets client (ctx.assets.list)",
+    );
+  }
+  const type = (options && options.type) || "image";
+  const trimmedTag = typeof tag === "string" ? tag.trim() : "";
+  const ready = trimmedTag.length > 0;
+
+  const [assets, setAssets] = useState([]);
+  const [loading, setLoading] = useState(ready);
+  const [error, setError] = useState(null);
+
+  const listRef = useRef(ctx.assets.list);
+  listRef.current = ctx.assets.list;
+  const argsRef = useRef({ tag: trimmedTag, type });
+  argsRef.current = { tag: trimmedTag, type };
+  const runRef = useRef(0);
+
+  const doFetch = useCallback(async () => {
+    const myRun = ++runRef.current;
+    const { tag: t, type: ty } = argsRef.current;
+    if (!t) {
+      setLoading(false);
+      setError(null);
+      setAssets([]);
+      return;
+    }
+    setLoading(true);
+    setError(null);
+    try {
+      const res = await listRef.current({ tag: t, type: ty, limit: 1000 });
+      const rows = res && Array.isArray(res.data) ? res.data : [];
+      if (runRef.current !== myRun) return;
+      setAssets(rows);
+      setLoading(false);
+    } catch (err) {
+      if (runRef.current !== myRun) return;
+      setError(toDatastoreError(err));
+      setLoading(false);
+    }
+  }, []);
+
+  useEffect(() => {
+    doFetch();
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [trimmedTag, type]);
+
+  const refetch = useCallback(async () => {
+    await doFetch();
+  }, [doFetch]);
+
+  // sc-1179 — auto-subscribe to the page-level refresh tick so a Gallery in
+  // tag mode picks up newly tagged assets when the author refreshes.
+  useRefresh(refetch);
+
+  return { assets, loading, error, refetch };
+}
+
 /* ============================================================================
  * FILESTORE CLIENT — ctx.filestore (@colixsystems/filestore-client)
  *

package/dist/index.d.ts

@@ -662,6 +662,13 @@ export interface DatastoreSchemaColumn {
   relation_type?: "ONE_TO_ONE" | "ONE_TO_MANY" | "MANY_TO_MANY" | null;
   /** For RELATION columns only — the id of the table this column points at. */
   target_table_id?: string | null;
+  /**
+   * For RELATION columns only — id of a column on `target_table_id` whose
+   * value supplies the `label` hydrated next to the related record id in
+   * record responses. `null` falls back to the first STRING/TEXT column on
+   * the target table.
+   */
+  display_column_id?: string | null;
   /** True when this column is the table's display/identification column. */
   is_identification?: boolean;
 }
@@ -757,6 +764,35 @@ export function useAsset(assetId: string | null | undefined): {
   refetch(): Promise<void>;
 };
 
+/**
+ * List every tenant asset carrying a given tag. Reads `ctx.assets.list({
+ * tag, type, limit })` and unwraps the `{ data, meta }` envelope.
+ *
+ * `type` defaults to `"image"` so the common Gallery case gets only images
+ * back; pass `"all"` (or `"audio"` / `"video"` / `"document"`) to widen.
+ * When `tag` is falsy the hook collapses to an empty result without a
+ * network round-trip.
+ */
+export function useAssetsByTag(
+  tag: string | null | undefined,
+  options?: {
+    type?: "image" | "audio" | "video" | "document" | "all";
+  },
+): {
+  assets: Array<{
+    id: string;
+    url: string;
+    stored_filename?: string;
+    mime_type?: string;
+    size_bytes?: number;
+    tags?: string[];
+    [k: string]: unknown;
+  }>;
+  loading: boolean;
+  error: DatastoreError | null;
+  refetch(): Promise<void>;
+};
+
 export function useI18n(): {
   locale: string;
   t(key: string, fallback?: string): string;

package/dist/index.js

@@ -15,6 +15,7 @@ export {
   useDatastoreRecord,
   useDatastoreSchema,
   useAsset,
+  useAssetsByTag,
   useFilestoreFiles,
   useFilestoreFolders,
   useFileSignature,

package/dist/index.native.js

@@ -15,6 +15,7 @@ export {
   useDatastoreRecord,
   useDatastoreSchema,
   useAsset,
+  useAssetsByTag,
   useFilestoreFiles,
   useFilestoreFolders,
   useFileSignature,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@colixsystems/widget-sdk",
-  "version": "0.41.0",
+  "version": "0.43.0",
   "description": "Common widget interface for AppStudio. Implements WidgetManifest, WidgetContext, property schema, and helper hooks.",
   "type": "module",
   "main": "./dist/index.js",
@@ -39,7 +39,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-mutation.test.js src/__tests__/hooks-record-permissions.test.js src/__tests__/hooks-subscription.test.js src/__tests__/linter-users-scope.test.js src/__tests__/linter-comments.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"
+    "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-mutation.test.js src/__tests__/hooks-record-permissions.test.js src/__tests__/hooks-subscription.test.js src/__tests__/linter-users-scope.test.js src/__tests__/linter-comments.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"
   },
   "engines": {
     "node": ">=18"