@colixsystems/widget-sdk 0.37.0 → 0.39.0

package/dist/hooks.js

@@ -12,7 +12,7 @@
 // four-client mapping is obvious at a glance:
 //   - CORE       — WidgetContext + non-data hooks (no domain client)
 //   - DATASTORE  — ctx.datastore (@colixsystems/datastore-client)
-//   - FILES      — ctx.files (@colixsystems/files-client)
+//   - ASSETS     — ctx.assets (@colixsystems/assets-client)
 //   - DIRECTORY  — ctx.directory (@colixsystems/directory-client)
 //   - PAYMENTS   — ctx.payments (@colixsystems/payments-client)
 //
@@ -26,10 +26,18 @@ import React, {
   useRef,
   useState,
 } from "react";
-// REQ-L10N-WIDGET: the per-widget translation key format lives in ONE place
-// (contract.js). useI18n (lookup) and the backend seeder (write) both call it
-// so the namespaced key can never drift between the two sides.
-import { widgetTranslationKey } from "./contract.js";
+// REQ-L10N-WIDGET / REQ-L10N-SHARED: the translation key formats live in ONE
+// place (contract.js). useI18n (lookup) and the backend seeder (write) both
+// call them so the namespaced keys can never drift between the two sides.
+// `widgetTranslationKey` builds the per-widget key (`widget.<id>.<key>`);
+// `sharedTranslationKey` builds the tenant-wide predefined key
+// (`shared.<key>`); `isSharedTranslationKey` tells the hook whether a bare key
+// is one of the predefined shared keys and so should try the shared namespace.
+import {
+  widgetTranslationKey,
+  sharedTranslationKey,
+  isSharedTranslationKey,
+} from "./contract.js";
 
 /** @internal — host-injected context value of shape WidgetContext (see index.d.ts). */
 const HostWidgetContext = createContext(null);
@@ -240,7 +248,27 @@ export function useI18n() {
             return scoped;
           }
         }
-        // 2) Fall back to the raw key (shared app keys + widgets with no
+        // 2) REQ-L10N-SHARED: for a predefined SHARED key, try the tenant-wide
+        //    `shared.<key>` namespace next. This is what lets identical
+        //    default-widget strings ("Submit", "Cancel", …) translate ONCE: a
+        //    widget that has no per-instance `widget.<id>.<key>` override
+        //    inherits the shared value. The per-widget step above runs FIRST,
+        //    so an author override of a single instance still wins for that
+        //    instance. Only the predefined keys are tried here — an
+        //    author-invented bare key is never silently shared.
+        if (isSharedTranslationKey(key)) {
+          const shared = sharedTranslationKey(key);
+          const scoped = hostT(shared);
+          if (
+            typeof scoped === "string" &&
+            scoped.length > 0 &&
+            scoped !== shared &&
+            !scoped.startsWith("{{t:")
+          ) {
+            return scoped;
+          }
+        }
+        // 3) Fall back to the raw key (shared app keys + widgets with no
         //    manifest translations — unchanged from pre-1.10 behaviour).
         const out = hostT(key, fallback);
         if (typeof out === "string" && out.length > 0 && out !== key) {
@@ -1029,59 +1057,60 @@ export function useDatastoreSubscription(table, handlers, options) {
 }
 
 /* ============================================================================
- * FILES CLIENT — ctx.files (@colixsystems/files-client)
+ * ASSETS CLIENT — ctx.assets (@colixsystems/assets-client)
  *
- * Files, folders, shares. Covers: useFile.
+ * The Asset Manager: resolve a tenant asset (image / audio / video / doc) by
+ * id to a browser-usable URL. Covers: useAsset.
  * ==========================================================================*/
 
 /**
- * Stateful file-asset resolver hook. Returns { url, file, loading, error,
+ * Stateful asset resolver hook. Returns { url, asset, loading, error,
  * refetch }.
  *
- * The host injects a `@colixsystems/files-client` instance at `ctx.files`,
- * FLATTENED so file ops are top-level. We call `ctx.files.get(fileId)`,
- * which resolves to `{ url, ...meta }` — the returned file already carries
+ * The host injects a `@colixsystems/assets-client` instance at `ctx.assets`,
+ * FLATTENED so asset ops are top-level. We call `ctx.assets.get(assetId)`,
+ * which resolves to `{ url, ...meta }` — the returned asset already carries
  * an absolute URL so the widget can drop it straight into an `<Image
  * source>` without knowing where the API lives. A missing/soft-deleted
  * asset surfaces as `{ url: null, error: <DatastoreError NOT_FOUND> }`.
  *
- * When `fileId` is falsy the hook collapses to { url: null, file: null,
+ * When `assetId` is falsy the hook collapses to { url: null, asset: null,
  * loading: false, error: null, refetch } without a network round-trip,
  * so a widget rendering before the author has bound an asset stays
  * loop-free.
  */
-export function useFile(fileId) {
-  const ctx = useWidgetContextOrThrow("useFile");
-  if (!ctx.files || typeof ctx.files.get !== "function") {
-    throw new Error("useFile: host did not inject a files client");
+export function useAsset(assetId) {
+  const ctx = useWidgetContextOrThrow("useAsset");
+  if (!ctx.assets || typeof ctx.assets.get !== "function") {
+    throw new Error("useAsset: host did not inject an assets client");
   }
-  const ready = Boolean(fileId);
-  const [file, setFile] = useState(null);
+  const ready = Boolean(assetId);
+  const [asset, setAsset] = useState(null);
   const [loading, setLoading] = useState(ready);
   const [error, setError] = useState(null);
 
-  const fileIdRef = useRef(fileId);
-  const getRef = useRef(ctx.files.get);
-  fileIdRef.current = fileId;
-  getRef.current = ctx.files.get;
+  const assetIdRef = useRef(assetId);
+  const getRef = useRef(ctx.assets.get);
+  assetIdRef.current = assetId;
+  getRef.current = ctx.assets.get;
 
   const runRef = useRef(0);
 
   const doFetch = useCallback(async () => {
     const myRun = ++runRef.current;
-    const id = fileIdRef.current;
+    const id = assetIdRef.current;
     if (!id) {
       setLoading(false);
       setError(null);
-      setFile(null);
+      setAsset(null);
       return;
     }
     setLoading(true);
     setError(null);
     try {
-      const f = await getRef.current(id);
+      const a = await getRef.current(id);
       if (runRef.current !== myRun) return;
-      setFile(f || null);
+      setAsset(a || null);
       setLoading(false);
     } catch (err) {
       if (runRef.current !== myRun) return;
@@ -1093,17 +1122,17 @@ export function useFile(fileId) {
   useEffect(() => {
     doFetch();
     // eslint-disable-next-line react-hooks/exhaustive-deps
-  }, [fileId]);
+  }, [assetId]);
 
   const refetch = useCallback(async () => {
     await doFetch();
   }, [doFetch]);
 
   const url =
-    file && typeof file.url === "string" && file.url.length > 0
-      ? file.url
+    asset && typeof asset.url === "string" && asset.url.length > 0
+      ? asset.url
       : null;
-  return { url, file, loading, error, refetch };
+  return { url, asset, loading, error, refetch };
 }
 
 /* ============================================================================

package/dist/index.d.ts

@@ -375,13 +375,13 @@ export interface DirectoryClient {
 }
 
 /**
- * Structural shape of the injected Asset-Manager files client (`ctx.files`).
+ * Structural shape of the injected Asset-Manager client (`ctx.assets`).
  * Slimmed to the three top-level ops the host injects — `get` / `list` /
- * `upload`. Backs `useFile`, which calls `ctx.files.get(id)`. The returned
- * file carries an absolute `url` safe to drop into `<Image source>`.
+ * `upload`. Backs `useAsset`, which calls `ctx.assets.get(id)`. The returned
+ * asset carries an absolute `url` safe to drop into `<Image source>`.
  */
-export interface FilesClient {
-  get(fileId: string): Promise<unknown>;
+export interface AssetsClient {
+  get(assetId: string): Promise<unknown>;
   list(query?: Record<string, unknown>): Promise<ListEnvelope>;
   upload(formData: unknown): Promise<unknown>;
 }
@@ -431,8 +431,8 @@ export interface WidgetContext<TProps = unknown> {
   datastore: DatastoreClient;
   /** Injected @colixsystems/directory-client (users + groups + invites). */
   directory: DirectoryClient;
-  /** Injected Asset-Manager files client: { get, list, upload }. */
-  files: FilesClient;
+  /** Injected @colixsystems/assets-client: { get, list, upload }. */
+  assets: AssetsClient;
   /** Injected @colixsystems/payments-client. */
   payments: PaymentsClient;
   /** Host child-node renderer; backs WidgetTree / useChildRenderer. */
@@ -457,7 +457,7 @@ export interface WidgetContext<TProps = unknown> {
 /**
  * The widget's component receives the author-authored props **as React
  * props** — the same shape and calling convention every built-in widget
- * uses (`<MetricWidget tableId={...} sumField={...} />`). Everything
+ * uses (`<ChartWidget tableId={...} groupByField={...} />`). Everything
  * else from `WidgetContext` (datastore, user, workspace, navigation,
  * i18n, …) is reachable via the SDK hooks (`useDatastoreMutation`,
  * `useDatastoreQuery`, `useTheme`, `useI18n`, `useWidgetEvent`), which
@@ -742,9 +742,9 @@ export function useChildRenderer(): {
  */
 export const WidgetTree: (props: { node: unknown }) => unknown;
 
-export function useFile(fileId: string | null | undefined): {
+export function useAsset(assetId: string | null | undefined): {
   url: string | null;
-  file: {
+  asset: {
     id: string;
     url: string;
     stored_filename?: string;

package/dist/index.js

@@ -14,7 +14,7 @@ export {
   useDatastoreQuery,
   useDatastoreRecord,
   useDatastoreSchema,
-  useFile,
+  useAsset,
   useFilestoreFiles,
   useFilestoreFolders,
   useFileSignature,

package/dist/index.native.js

@@ -14,7 +14,7 @@ export {
   useDatastoreQuery,
   useDatastoreRecord,
   useDatastoreSchema,
-  useFile,
+  useAsset,
   useFilestoreFiles,
   useFilestoreFolders,
   useFileSignature,

package/dist/webbundle.js

@@ -0,0 +1,125 @@
+// REQ-WSDK-PLATFORM bundle (sc-1064): the SINGLE web-entry bundler shared by the
+// publish packer (`scripts/pack-first-party-widget.mjs`) and the dev server
+// (`devserver.js`). Both paths feed a widget's WEB entry through this so what
+// you `dev` is byte-shape-identical to what ships (CLAUDE.md §3, one source).
+//
+// Why a bundler at all (vs. the sucrase transpile the native entry still uses):
+// the Studio's runtime loader resolves bare specifiers only for the host's OWN
+// shimmed set (`dev-shims.hostExternalSpecifiers()` — react family, react-dom,
+// the SDK, and a few vetted packages). A transpile-only web entry leaves
+// `import … from "react-leaflet"` / `"leaflet"` / `"leaflet/dist/leaflet.css"`
+// / the marker PNGs bare, and the loader's `findUnresolvedBareImports` guard
+// rejects the bundle ("unresolvable bare imports: react-leaflet, leaflet, …").
+// esbuild inlines all of those while leaving the host-resolved set external.
+//
+// What's externalised vs. inlined:
+//   * external = `hostExternalSpecifiers()` — the host injects its OWN React,
+//     react-dom, SDK, and vetted packages at runtime; inlining a second copy of
+//     React/react-dom would break the shared-instance invariant (mismatched
+//     renderer). These stay as bare `import`s the loader rewrites to blob shims.
+//   * inlined  = everything else: `react-leaflet`, `leaflet`, the marker PNGs
+//     (→ data URLs), the `leaflet/dist/leaflet.css` side-effect import (→ a JS
+//     module that injects a <style> at runtime).
+//
+// esbuild is a LAZY, optional dependency — imported only when this module's
+// `bundleWebEntry` runs (the `dev`/pack paths), never by the published SDK
+// runtime. Same pattern as `loadTransform()`'s `sucrase` import in devserver.js.
+
+import { hostExternalSpecifiers } from "./dev-shims.js";
+
+/**
+ * Lazily resolve esbuild's `build`. Kept out of the module's static imports so
+ * the published SDK runtime never forces the dependency — only the dev/pack
+ * bundle paths reach it. Throws a friendly install hint when it's absent
+ * (mirrors `loadTransform`'s sucrase handling).
+ *
+ * @returns {Promise<typeof import("esbuild")>}
+ */
+export async function loadEsbuild() {
+  try {
+    return await import("esbuild");
+  } catch {
+    throw new Error(
+      "Bundling a widget's web entry needs the optional `esbuild` dependency.\n" +
+        "Install it in your widget project:\n" +
+        "  npm install --save-dev esbuild",
+    );
+  }
+}
+
+// esbuild plugin: resolve `import "….css"` (a side-effect import) to a tiny JS
+// module that injects the CSS through a runtime <style> element. The output
+// bundle then carries NO `.css` import, and the styling still applies the
+// moment the module is evaluated in the browser. Guarded by
+// `typeof document !== "undefined"` so the same module is a no-op under SSR /
+// the native runtime (which never loads the web entry, but belt-and-braces).
+function cssInjectPlugin() {
+  return {
+    name: "appstudio-css-inject",
+    setup(build) {
+      build.onLoad({ filter: /\.css$/ }, async (args) => {
+        const { readFile } = await import("node:fs/promises");
+        const css = await readFile(args.path, "utf8");
+        const contents =
+          "if (typeof document !== \"undefined\") {\n" +
+          "  const __s = document.createElement(\"style\");\n" +
+          "  __s.setAttribute(\"data-appstudio-widget-css\", \"1\");\n" +
+          `  __s.textContent = ${JSON.stringify(css)};\n` +
+          "  document.head.appendChild(__s);\n" +
+          "}\n" +
+          "export default undefined;\n";
+        return { contents, loader: "js" };
+      });
+    },
+  };
+}
+
+/**
+ * Bundle a widget's WEB entry into a single ESM string with the host-resolved
+ * specifiers left external. JSX is transformed with the automatic runtime (so
+ * the loader's react/jsx-runtime shims resolve it), `.png` assets become data
+ * URLs, and `.css` side-effect imports become runtime <style> injectors.
+ *
+ * @param {object} opts
+ * @param {string} opts.entryPath  absolute path to the web entry (e.g. the
+ *   resolved `MapWidget.web.jsx`).
+ * @param {string[]} [opts.external]  bare specifiers to leave external. Defaults
+ *   to `hostExternalSpecifiers()` — the canonical host-resolved set.
+ * @param {string[]} [opts.nodePaths]  extra `node_modules` roots esbuild should
+ *   search when resolving the inlined deps (`react-leaflet`, `leaflet`, …). The
+ *   packer passes the frontend's `node_modules` (where the vetted web packages
+ *   are installed per the adding-vetted-packages skill) so the bundle resolves
+ *   them no matter the invoking CWD.
+ * @returns {Promise<string>} the bundled ESM source.
+ */
+export async function bundleWebEntry({
+  entryPath,
+  external = hostExternalSpecifiers(),
+  nodePaths = [],
+}) {
+  const esbuild = await loadEsbuild();
+  const result = await esbuild.build({
+    entryPoints: [entryPath],
+    bundle: true,
+    write: false,
+    format: "esm",
+    platform: "browser",
+    target: ["es2020"],
+    jsx: "automatic",
+    // Leave the host-resolved set as bare `import`s; the Studio loader rewrites
+    // them to blob shims at runtime (and Metro resolves them in the export).
+    external,
+    loader: { ".png": "dataurl", ".jpg": "dataurl", ".gif": "dataurl" },
+    plugins: [cssInjectPlugin()],
+    // esbuild walks up from the entry for node_modules by default; `nodePaths`
+    // adds extra roots so a packer invoked from the repo root still resolves the
+    // vetted web packages installed under frontend/node_modules.
+    nodePaths,
+    logLevel: "silent",
+  });
+  const out = result.outputFiles?.[0];
+  if (!out) {
+    throw new Error(`esbuild produced no output for ${entryPath}`);
+  }
+  return out.text;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@colixsystems/widget-sdk",
-  "version": "0.37.0",
+  "version": "0.39.0",
   "description": "Common widget interface for AppStudio. Implements WidgetManifest, WidgetContext, property schema, and helper hooks.",
   "type": "module",
   "main": "./dist/index.js",
@@ -18,6 +18,10 @@
       "import": "./dist/linter.js",
       "default": "./dist/linter.js"
     },
+    "./dev-shims": {
+      "import": "./dist/dev-shims.js",
+      "default": "./dist/dev-shims.js"
+    },
     "./contract": {
       "types": "./dist/index.d.ts",
       "require": "./dist/contract.cjs",
@@ -35,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"
+    "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"
   },
   "engines": {
     "node": ">=18"
@@ -66,6 +70,7 @@
     }
   },
   "optionalDependencies": {
+    "esbuild": "^0.28.0",
     "sucrase": "^3.35.0"
   },
   "keywords": [