@colixsystems/widget-sdk 0.277.2 → 0.277.3

package/README.md

@@ -63,7 +63,8 @@ The data layer lives in **four separate domain-client packages**, each instantia
 | **DATASTORE** | `useTyping(tableId, recordId)` | `{ typingUserIds, setTyping, status }` — status `"connecting" \| "live" \| "unavailable"` | `records(table).typing` — `datastore.read:<table>`. Who else is typing in one record, over the same socket as `useDatastoreSubscription`. Call `setTyping(true)` on every keystroke (throttled to one signal per 3 s; `false` is sent after 5 s idle) and `setTyping(false)` on send, clear or blur. `typingUserIds` lists the OTHER users' ids; each drops out 6 s after their last signal. Needs a signed-in user who can read the record. Never throws: an anonymous visitor, a refused subscription or a host whose client lacks `typing` reads `{ typingUserIds: [], status: "unavailable" }`. Re-subscribes when either id changes. |
 | **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) |
 | **DATASTORE** | `useCanWrite(tableId, options)` (optional: options) | `{ canWrite, loading, error, refetch }` | `myPermissions(tableId, { recordId? })` — scope `datastore.read:<table>`. A FLOOR, not a full replacement for domain-specific write rules: answers "may this caller write", reading the same table-ACL answer the write endpoint enforces — so a table granting Create to Everyone answers `true` for a logged-out visitor, and this hook alone is the right gate for a widget meant to work without signing in. Pass `{ recordId }` for a per-row check. A widget whose own rule is MORE SPECIFIC than the table ACL (e.g. "only the assigned user may edit this row") must still hand-check that in addition. Pair with `useUser()` to also tell "not signed in" apart from "signed in but forbidden" — both resolve `canWrite: false` here. Falsy `tableId`, or a host that hasn't injected `myPermissions` (an older host), collapses to `{ canWrite: false, loading: false, error: null, refetch: async () => undefined }` rather than throwing. |
-| **FILES** (`ctx.assets`) | `useAsset(id)` | `{ url, asset, loading, error, refetch }` | `ctx.assets.get` — no scope |
+| **FILES** (`ctx.filestore`) | `useFilestoreFile(fileId)` | `{ file, url, urls, loading, error, refetch }` | `ctx.filestore.files.get` — `files.read:*`. **A FILE column's value is a filestore file id.** Draw it with `<FileImage fileId={row.photo} variant="card" />`, or read `useFilestoreFile(row.photo).url` (`urls.thumbnail` / `.card` / `.large` for a smaller render); `url` and `urls` are `null` until the fetch resolves and for an empty cell. Never pass a column value to `useAsset`: it resolves no file id, so the picture renders blank. |
+| **FILES** (`ctx.assets`) | `useAsset(id)` | `{ url, asset, loading, error, refetch }` | `ctx.assets.get` — no scope. Takes an asset-library id: an `asset` property's value, or the `asset_id` an image import (`import_image`, `import_stock_image`) answers. Never a FILE column's value, which is a filestore file id (see `useFilestoreFile`). |
 | **FILES** | `useAssetsByTag(tag, { type })` (optional: the whole argument, and `type` within it) | `{ 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. |
 | **FILES** (`ctx.widget`) | `useBundledAsset(fileName)` | `string \| null` | `ctx.widget.assets` — no scope. The URL of an image or sound the widget package ships in its `assets/` directory, or `null` when it has no file with that name. See [Bundled images and sounds](#bundled-images-and-sounds). |
 | **DIRECTORY** (`ctx.directory`) | `useDirectory(query)` (optional: query) | `{ users, loading, error, refetch }` | `directory.users.list` — `directory.read:users` |
@@ -86,7 +87,11 @@ See the design reference for the full architecture: [`docs/architecture/widget-m
 
 ## Status
 
-`v0.277.2` — 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.277.3` — 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.277.3
+
+**A FILE column's value goes to `<FileImage fileId>` or `useFilestoreFile`, never `useAsset`.** The hook table's FILES group now leads with the filestore file id a FILE column holds and says that `useAsset(id)` takes an asset-library id. A new linter warning, `useAsset-on-file-column`, flags `useAsset(row.photo)` (a value read from a datastore row) in a widget that reads records: the hook resolves no URL for a file id, so the picture renders blank.
 
 ### What's new in 0.277.2
 

package/dist/linter.cjs

@@ -1584,6 +1584,32 @@ function _rawUseMemoIntoDatastoreQueryRules(source) {
   return findings;
 }
 
+// A FILE column holds a filestore file id; useAsset resolves asset-library
+// ids only, so a row value passed to it renders a blank picture.
+function _useAssetOnFileColumnRules(source) {
+  const code = _stripNonCode(source);
+  if (!/\buseDatastore(?:Query|Record)\w*\s*\(/.test(code)) return [];
+  const callRe = /\buseAsset\s*\(\s*(?:row|record|item)\s*\??\s*[.[]/g;
+  const sourceLines = source.split(/\r?\n/);
+  const lineAt = _lineCounter(code);
+  const findings = [];
+  let m;
+  while ((m = callRe.exec(code))) {
+    const line = lineAt(m.index);
+    findings.push({
+      rule: "useAsset-on-file-column",
+      severity: "warning",
+      label:
+        "useAsset() resolves an asset-library id, never a FILE column's value: " +
+        "that is a filestore file id, so draw it with <FileImage fileId={…}> " +
+        "or read useFilestoreFile(id).url.",
+      line,
+      snippet: (sourceLines[line - 1] || "").trim().slice(0, 200),
+    });
+  }
+  return findings;
+}
+
 // sc-5206 — soft warning, the write-gate twin of `write-not-gated-on-user`.
 // A widget that hand-derives write permission from `useUser().groupIds` /
 // `.roles` re-implements the table ACL client-side and drifts from it the
@@ -2874,6 +2900,7 @@ function lintSource(source, options) {
   // sc-5206 — soft warnings steering a widget toward the two new hooks.
   findings.push(..._rawUseMemoIntoDatastoreQueryRules(source));
   findings.push(..._handRolledWriteGateRules(source));
+  findings.push(..._useAssetOnFileColumnRules(source));
   findings.push(..._rowActionGatingRules(source));
   // REQ-USERMGMT / REQ-ACL-SYS M3 — scope-aware rules. Run after the
   // line-by-line scan so banned-identifier findings stay first in the

package/dist/linter.js

@@ -1579,6 +1579,32 @@ function _rawUseMemoIntoDatastoreQueryRules(source) {
   return findings;
 }
 
+// A FILE column holds a filestore file id; useAsset resolves asset-library
+// ids only, so a row value passed to it renders a blank picture.
+function _useAssetOnFileColumnRules(source) {
+  const code = _stripNonCode(source);
+  if (!/\buseDatastore(?:Query|Record)\w*\s*\(/.test(code)) return [];
+  const callRe = /\buseAsset\s*\(\s*(?:row|record|item)\s*\??\s*[.[]/g;
+  const sourceLines = source.split(/\r?\n/);
+  const lineAt = _lineCounter(code);
+  const findings = [];
+  let m;
+  while ((m = callRe.exec(code))) {
+    const line = lineAt(m.index);
+    findings.push({
+      rule: "useAsset-on-file-column",
+      severity: "warning",
+      label:
+        "useAsset() resolves an asset-library id, never a FILE column's value: " +
+        "that is a filestore file id, so draw it with <FileImage fileId={…}> " +
+        "or read useFilestoreFile(id).url.",
+      line,
+      snippet: (sourceLines[line - 1] || "").trim().slice(0, 200),
+    });
+  }
+  return findings;
+}
+
 // sc-5206 — soft warning, the write-gate twin of `write-not-gated-on-user`.
 // A widget that hand-derives write permission from `useUser().groupIds` /
 // `.roles` re-implements the table ACL client-side and drifts from it the
@@ -2869,6 +2895,7 @@ export function lintSource(source, options) {
   // sc-5206 — soft warnings steering a widget toward the two new hooks.
   findings.push(..._rawUseMemoIntoDatastoreQueryRules(source));
   findings.push(..._handRolledWriteGateRules(source));
+  findings.push(..._useAssetOnFileColumnRules(source));
   findings.push(..._rowActionGatingRules(source));
   // REQ-USERMGMT / REQ-ACL-SYS M3 — scope-aware rules. Run after the
   // line-by-line scan so banned-identifier findings stay first in the

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@colixsystems/widget-sdk",
-  "version": "0.277.2",
+  "version": "0.277.3",
   "description": "Common widget interface for AppStudio. Implements WidgetManifest, WidgetContext, property schema, and helper hooks.",
   "homepage": "https://github.com/Colix-AB/AppStudio",
   "type": "module",