@colixsystems/widget-sdk 0.73.0 → 0.75.0

package/README.md

@@ -54,7 +54,27 @@ See the design reference for the full architecture: [`docs/architecture/widget-m
 
 ## Status
 
-`v0.73.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.75.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.75.0
+
+**`ui.group: "Basics"` marks a widget's quick style knobs (sc-4100).** A `styleSchema` field has always accepted the `propertySchema` `ui.group` key; the Studio now reads one reserved group name from it, so a widget with several styleable elements can expose per-element controls without burying the two or three an author reaches for first.
+
+- **Group every style field, or none of them.** In a grouped `styleSchema`, put the whole-widget basics (`background`, `textColor`, `align`) under the exact group `"Basics"` and each per-element field under a group named for the element it styles (`"Card"`, `"Title"`, `"Chip"`, …). Keep the total under about 12 fields.
+- **Where each surface renders.** The Builder's Properties panel renders **every** group. Agent Mode's in-preview edit panel — a quick-tweak surface — renders **only** `"Basics"` and points the author at the Builder for the rest.
+- **Nothing changes for an ungrouped `styleSchema`.** A flat schema (no `ui.group` anywhere) renders in full in both surfaces exactly as before, so every already-published widget is unaffected. A grouped schema that declares no `"Basics"` group also renders in full — the trim needs a group to trim *to*.
+
+No export, type, hook, or `CONTRACT` field changed; `CONTRACT.version` stays `1.51.0`. This is an additive host convention over an existing manifest key.
+
+### What's new in 0.74.0
+
+**Calling a translation vendor directly is now a blocking lint finding (sc-4085).** `useTranslate()` has brokered content translation since 0.70.0, but nothing stopped a widget fetching a free public endpoint instead — and generated widgets routinely did, reaching for `api.mymemory.translated.net`. That call skips the workspace's provider, the shared cache and the metered budget, and ships an unvetted third-party endpoint into every app the widget is installed in.
+
+- **New rule `no-external-translation-api`.** `severity: "error"`, so it fails `appstudio-widget lint` and blocks submission. There is no `appstudio-lint-ignore` opt-out: a hostname match is unambiguous, so unlike a relative `/api/` path there is no correct code for a directive to rescue.
+- **`CONTRACT.translationApiHosts`** publishes the refused vendor list (MyMemory, LibreTranslate, DeepL, Google, Microsoft, Yandex, Lingvanex), matched case-insensitively as host substrings against code. Comments are blanked first, so documenting the rule is safe.
+- **Nothing changes for a widget that was already correct.** `useTranslate()` for content the workspace's users typed, `useI18n().t()` for text you author, and `fetch`/`axios` for genuine third-party APIs all lint exactly as before.
+
+`CONTRACT.version` → `1.51.0`. Additive: one new contract field and one new lint rule; no existing export changed signature.
 
 ### What's new in 0.71.0
 

package/dist/contract.cjs

@@ -1783,6 +1783,24 @@ const HOST_API_URL_PATTERNS = [
   "`/api/",
 ];
 
+// sc-4085: machine translation is platform-brokered (`useTranslate()`), so a
+// widget calling a translation vendor directly is a contract violation, not a
+// third-party API call. The direct call bypasses the platform's provider key,
+// the durable translation cache, and the workspace's metered budget — the same
+// reason a widget may never wire its own payment processor. Matched as literal
+// host substrings against code (comments are blanked before matching).
+const TRANSLATION_API_HOSTS = [
+  "mymemory.translated.net",
+  "libretranslate",
+  "deepl.com",
+  "translate.googleapis.com",
+  "translation.googleapis.com",
+  "translate.google.com",
+  "microsofttranslator.com",
+  "translate.yandex",
+  "lingvanex.com",
+];
+
 function deepFreeze(value) {
   if (value === null || typeof value !== "object") return value;
   if (Object.isFrozen(value)) return value;
@@ -2266,7 +2284,13 @@ const CONTRACT = deepFreeze({
   //    from this list — never told an author it existed. That omission is why
   //    a generated script inlines a plaintext credential instead of reading
   //    `secrets["KEY"]`. No runtime change; the global was already there.
-  version: "1.50.0",
+  // 1.51.0: additive (sc-4085) — `translationApiHosts`, the machine-translation
+  //    vendor hosts the linter refuses. `useTranslate()` has brokered content
+  //    translation since sc-3783, but nothing stopped a widget calling a free
+  //    public endpoint instead, which skips the cache, the metering and the
+  //    workspace's provider. Publishing the host list here keeps the linter,
+  //    the Developer guide and the agent prompt reading one source.
+  version: "1.51.0",
   sharedTranslationKeys: SHARED_TRANSLATION_KEYS,
   hooks: HOOKS,
   primitives: PRIMITIVES,
@@ -2287,6 +2311,7 @@ const CONTRACT = deepFreeze({
   vettedImports: VETTED_IMPORTS,
   allowedBareImports: ALLOWED_BARE_IMPORTS,
   hostApiUrlPatterns: HOST_API_URL_PATTERNS,
+  translationApiHosts: TRANSLATION_API_HOSTS,
 });
 
 function isHookAllowed(name) {

package/dist/contract.js

@@ -1783,6 +1783,24 @@ const HOST_API_URL_PATTERNS = [
   "`/api/",
 ];
 
+// sc-4085: machine translation is platform-brokered (`useTranslate()`), so a
+// widget calling a translation vendor directly is a contract violation, not a
+// third-party API call. The direct call bypasses the platform's provider key,
+// the durable translation cache, and the workspace's metered budget — the same
+// reason a widget may never wire its own payment processor. Matched as literal
+// host substrings against code (comments are blanked before matching).
+const TRANSLATION_API_HOSTS = [
+  "mymemory.translated.net",
+  "libretranslate",
+  "deepl.com",
+  "translate.googleapis.com",
+  "translation.googleapis.com",
+  "translate.google.com",
+  "microsofttranslator.com",
+  "translate.yandex",
+  "lingvanex.com",
+];
+
 function deepFreeze(value) {
   if (value === null || typeof value !== "object") return value;
   if (Object.isFrozen(value)) return value;
@@ -2266,7 +2284,13 @@ const CONTRACT = deepFreeze({
   //    from this list — never told an author it existed. That omission is why
   //    a generated script inlines a plaintext credential instead of reading
   //    `secrets["KEY"]`. No runtime change; the global was already there.
-  version: "1.50.0",
+  // 1.51.0: additive (sc-4085) — `translationApiHosts`, the machine-translation
+  //    vendor hosts the linter refuses. `useTranslate()` has brokered content
+  //    translation since sc-3783, but nothing stopped a widget calling a free
+  //    public endpoint instead, which skips the cache, the metering and the
+  //    workspace's provider. Publishing the host list here keeps the linter,
+  //    the Developer guide and the agent prompt reading one source.
+  version: "1.51.0",
   sharedTranslationKeys: SHARED_TRANSLATION_KEYS,
   hooks: HOOKS,
   primitives: PRIMITIVES,
@@ -2287,6 +2311,7 @@ const CONTRACT = deepFreeze({
   vettedImports: VETTED_IMPORTS,
   allowedBareImports: ALLOWED_BARE_IMPORTS,
   hostApiUrlPatterns: HOST_API_URL_PATTERNS,
+  translationApiHosts: TRANSLATION_API_HOSTS,
 });
 
 function isHookAllowed(name) {

package/dist/linter.cjs

@@ -392,6 +392,39 @@ function _hostApiUrlRules(source) {
   return findings;
 }
 
+// sc-4085 — see linter.js for the rationale comment. The two files must stay
+// in lockstep (the contract test asserts behaviour-equivalence).
+function _translationApiRules(source) {
+  const findings = [];
+  const hosts = CONTRACT.translationApiHosts || [];
+  const lines = _stripNonCode(source, { keepStrings: true }).split(/\r?\n/);
+  for (let i = 0; i < lines.length; i += 1) {
+    const line = lines[i];
+    const lowered = line.toLowerCase();
+    for (const host of hosts) {
+      if (lowered.includes(host)) {
+        findings.push({
+          rule: "no-external-translation-api",
+          severity: "error",
+          label:
+            `source calls the translation vendor "${host}" directly — ` +
+            `translation is brokered by the platform. Use the SDK's ` +
+            `\`useTranslate()\` hook for content the workspace's users typed ` +
+            `(records, file names, API payloads) and \`useI18n().t(key, ` +
+            `fallback)\` for text you author yourself. A direct vendor call ` +
+            `bypasses the platform's provider key, the shared translation ` +
+            `cache and the workspace's metered budget, and it ships an ` +
+            `unvetted endpoint into the app.`,
+          line: i + 1,
+          snippet: line.trim().slice(0, 200),
+        });
+        break;
+      }
+    }
+  }
+  return findings;
+}
+
 // REQ-USERMGMT / REQ-ACL-SYS M3 — scope-required-for-user-mutation. See
 // linter.js for the rationale comment. The two files must stay in
 // lockstep (the contract test asserts behaviour-equivalence).
@@ -785,6 +818,7 @@ function lintSource(source, options) {
     })),
   );
   findings.push(..._hostApiUrlRules(source));
+  findings.push(..._translationApiRules(source));
   findings.push(..._lucideIconRules(source));
   findings.push(..._reactInScopeRules(source));
   findings.push(..._imagePercentHeightRules(source));

package/dist/linter.js

@@ -437,6 +437,51 @@ function _hostApiUrlRules(source) {
   return findings;
 }
 
+// sc-4085 — no-external-translation-api.
+//
+// Translation is a platform capability, not a third-party API: `useTranslate()`
+// (sc-3783) routes content through the platform's provider key, a durable
+// tenant-scoped cache and a metered budget. A widget that fetches a vendor
+// endpoint itself gets none of that, and ships an unvetted third-party
+// dependency into every app the widget is installed in — the same reason a
+// widget may never wire its own payment processor.
+//
+// This is an `error`, not a `warning` like `no-host-api-url`, and it carries no
+// opt-out directive: a hostname match is unambiguous (unlike a relative `/api/`
+// path, which a legitimate third-party call cannot always avoid), so there is
+// no correct code for the directive to rescue. A workspace that needs a
+// different provider changes the platform's translation key, not the widget.
+function _translationApiRules(source) {
+  const findings = [];
+  const hosts = CONTRACT.translationApiHosts || [];
+  const lines = _stripNonCode(source, { keepStrings: true }).split(/\r?\n/);
+  for (let i = 0; i < lines.length; i += 1) {
+    const line = lines[i];
+    const lowered = line.toLowerCase();
+    for (const host of hosts) {
+      if (lowered.includes(host)) {
+        findings.push({
+          rule: "no-external-translation-api",
+          severity: "error",
+          label:
+            `source calls the translation vendor "${host}" directly — ` +
+            `translation is brokered by the platform. Use the SDK's ` +
+            `\`useTranslate()\` hook for content the workspace's users typed ` +
+            `(records, file names, API payloads) and \`useI18n().t(key, ` +
+            `fallback)\` for text you author yourself. A direct vendor call ` +
+            `bypasses the platform's provider key, the shared translation ` +
+            `cache and the workspace's metered budget, and it ships an ` +
+            `unvetted endpoint into the app.`,
+          line: i + 1,
+          snippet: line.trim().slice(0, 200),
+        });
+        break;
+      }
+    }
+  }
+  return findings;
+}
+
 // REQ-USERMGMT / REQ-ACL-SYS M3 — scope-required-for-user-mutation.
 //
 // A widget that calls `useUsers().invite()` / `.deactivate()` /
@@ -901,6 +946,7 @@ export function lintSource(source, options) {
   );
   // REQ-WSDK-PLATFORM §3.5: soft host-API URL warning (does not block).
   findings.push(..._hostApiUrlRules(source));
+  findings.push(..._translationApiRules(source));
   findings.push(..._lucideIconRules(source));
   // sc-2353 — widget source must be self-contained (reference React ⇒ import it).
   findings.push(..._reactInScopeRules(source));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@colixsystems/widget-sdk",
-  "version": "0.73.0",
+  "version": "0.75.0",
   "description": "Common widget interface for AppStudio. Implements WidgetManifest, WidgetContext, property schema, and helper hooks.",
   "type": "module",
   "main": "./dist/index.js",
@@ -48,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-filestore-file.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__/hooks-volatile-query-key.test.js src/__tests__/linter-users-scope.test.js src/__tests__/linter-comments.test.js src/__tests__/linter-image-height.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__/hooks-translate.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 src/__tests__/theme-components-parity.test.js src/__tests__/theme-depth-tokens.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-filestore-file.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__/hooks-volatile-query-key.test.js src/__tests__/linter-users-scope.test.js src/__tests__/linter-comments.test.js src/__tests__/linter-translation-api.test.js src/__tests__/linter-image-height.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__/hooks-translate.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 src/__tests__/theme-components-parity.test.js src/__tests__/theme-depth-tokens.test.js"
   },
   "engines": {
     "node": ">=18"