@colixsystems/widget-sdk 0.135.0 → 0.136.0

package/README.md

@@ -70,7 +70,40 @@ See the design reference for the full architecture: [`docs/architecture/widget-m
 
 ## Status
 
-`v0.135.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.136.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.136.0 (contract 1.105.0)
+
+**A `datastoreTemplate` can now say WHICH AUDIENCE gets which access — not just the two anonymous ones (sc-7530).** `publicGrant` could only ever reach `everyone` and `authenticated`, because those are the two principals that need no id. Anything naming a real user group was unexpressible: a group id belongs to the workspace that installs your widget, so it could never travel in your manifest. The practical cost was that a permission model you had already set up correctly — say an admin group with full CRUD while ordinary signed-in users only read — shipped to your installers as nothing at all, and every one of them rebuilt it by hand across both the table grant and the record permissions.
+
+Templates now name their audiences symbolically and let the installer bind them:
+
+```js
+datastoreTemplate: {
+  roles: [
+    { key: "admin", label: "Administrators", description: "Manages orders end to end" },
+  ],
+  tables: [
+    {
+      suffix: "Orders",
+      columns: [...],
+      // the id-less audiences, unchanged
+      publicGrant: { canRead: true, canWrite: false, canDelete: false },
+      // the audience that needs a real group
+      roleGrants: [{ role: "admin", canRead: true, canWrite: true, canDelete: true }],
+    },
+  ],
+}
+```
+
+`roles` is declared ONCE per template and referenced by every table, so three widgets over two tables ask the installing workspace **one** question per audience rather than one per grant. At install they pick one of their own groups for each role, or have one created for them under the role's label.
+
+- **`key`** is lowercase-kebab (`/^[a-z][a-z0-9-]*$/`), at most 8 roles per template. A `roleGrants` entry naming a role you did not declare is a publish error, as is granting the same role twice on one table or granting it no verb at all.
+- **`canDelete` is row-level only.** A table-scope grant answers "may I create a record"; only a record permission answers a question about a row. Both halves are written for you from the one declaration.
+- **An unbound role is an ordinary outcome, never a failed install.** If the installer skips a role, no grant is written and they are told which role is still unbound — they can bind it later from the table's permissions.
+- **Purely additive.** A template declaring neither `roles` nor `roleGrants` behaves exactly as it does today.
+
+Also tightened in this release: the `publicGrant` flags are now type-checked. They never were, so a stringy `canRead: "false"` read as truthy and silently opened the table to anonymous reads. If you have been passing anything but a real boolean there, publishing will now tell you.
 
 ### What's new in 0.135.0 (contract 1.104.0)
 

package/dist/contract.cjs

@@ -2153,7 +2153,7 @@ const MANIFEST_SCHEMA = {
     type: "object",
     required: false,
     description:
-      "Optional. Tables the widget needs, seeded into the workspace at install time. Authors wire them into the widget's `tableRef` properties via the Properties Panel — the SDK does not auto-bind. Limits: 8 tables, 24 columns per table. RELATION columns address siblings by `targetSuffix` (must be declared earlier in the array). Tables persist across uninstalls. A `tableRef` property may also carry `sharedTable: true`, declaring that the table is the APP'S OWN — the author picks an existing table and the widget seeds nothing for it. That is the correct shape for a widget that reads data it does not own (a chart, a metric, a manager view over another widget's table). `sharedTable` exempts the property from needing a seeded table at publish (`manifest.requiredTableRefsHaveTemplate`) WITHOUT making it optional: the author must still bind one, and the host still refuses to place the widget unbound. Use it instead of dropping `required` — a widget that silently renders an empty tile is the defect it looks like a fix for.",
+      "Optional. Tables the widget needs, seeded into the workspace at install time. Authors wire them into the widget's `tableRef` properties via the Properties Panel — the SDK does not auto-bind. Limits: 8 tables, 24 columns per table. RELATION columns address siblings by `targetSuffix` (must be declared earlier in the array). Tables persist across uninstalls. A `tableRef` property may also carry `sharedTable: true`, declaring that the table is the APP'S OWN — the author picks an existing table and the widget seeds nothing for it. That is the correct shape for a widget that reads data it does not own (a chart, a metric, a manager view over another widget's table). `sharedTable` exempts the property from needing a seeded table at publish (`manifest.requiredTableRefsHaveTemplate`) WITHOUT making it optional: the author must still bind one, and the host still refuses to place the widget unbound. Use it instead of dropping `required` — a widget that silently renders an empty tile is the defect it looks like a fix for. sc-7530: a table may also declare `roleGrants` — group-scoped access named SYMBOLICALLY, because a group id belongs to the workspace that installs the widget and could never travel in the manifest. Declare the audiences once at template level as `roles: [{ key, label, description? }]` (key is lowercase kebab, max 8 roles), then per table `roleGrants: [{ role, canRead?, canWrite?, canDelete? }]`. The installing workspace binds each role to one of its own user groups (or has one created) during the install consent step, so a permission model where an admin group does everything and signed-in users only read survives the trip between workspaces. Use `publicGrant` for the two id-less audiences (everyone / any signed-in user) and `roleGrants` for anything that names a group. A role nobody binds simply writes no grant — it never fails the install.",
   },
   translations: {
     type: "object",
@@ -3913,7 +3913,20 @@ const CONTRACT = deepFreeze({
   // the web half is a widget.web.jsx typed-code or QR path. Pinned in the
   // export and gated behind the `nfc` export capability, because its iOS
   // entitlement obliges every App ID that carries it.
-  version: "1.104.0",
+  // 1.105.0: additive (sc-7530) — a `datastoreTemplate` can declare the
+  //    AUDIENCES its tables grant access to, not just the two id-less ones.
+  //    `publicGrant` could only ever reach `everyone` and `authenticated`, so a
+  //    widget whose author had set up "an admin group does everything, signed-in
+  //    users only read" shipped that model to nobody: a group id is tenant-local
+  //    and cannot travel in a manifest. Templates now declare `roles:
+  //    [{ key, label, description? }]` once (lowercase-kebab key, max 8) and
+  //    per table `roleGrants: [{ role, canRead?, canWrite?, canDelete? }]`; the
+  //    installing workspace binds each role to one of ITS OWN user groups — or
+  //    has one created — during the install consent step. Purely additive: a
+  //    template declaring neither behaves exactly as before, and a role nobody
+  //    binds writes no grant rather than failing the install. Minor bump on the
+  //    pre-1.0 channel.
+  version: "1.105.0",
   sharedTranslationKeys: SHARED_TRANSLATION_KEYS,
   hooks: HOOKS,
   primitives: PRIMITIVES,

package/dist/contract.js

@@ -2153,7 +2153,7 @@ const MANIFEST_SCHEMA = {
     type: "object",
     required: false,
     description:
-      "Optional. Tables the widget needs, seeded into the workspace at install time. Authors wire them into the widget's `tableRef` properties via the Properties Panel — the SDK does not auto-bind. Limits: 8 tables, 24 columns per table. RELATION columns address siblings by `targetSuffix` (must be declared earlier in the array). Tables persist across uninstalls. A `tableRef` property may also carry `sharedTable: true`, declaring that the table is the APP'S OWN — the author picks an existing table and the widget seeds nothing for it. That is the correct shape for a widget that reads data it does not own (a chart, a metric, a manager view over another widget's table). `sharedTable` exempts the property from needing a seeded table at publish (`manifest.requiredTableRefsHaveTemplate`) WITHOUT making it optional: the author must still bind one, and the host still refuses to place the widget unbound. Use it instead of dropping `required` — a widget that silently renders an empty tile is the defect it looks like a fix for.",
+      "Optional. Tables the widget needs, seeded into the workspace at install time. Authors wire them into the widget's `tableRef` properties via the Properties Panel — the SDK does not auto-bind. Limits: 8 tables, 24 columns per table. RELATION columns address siblings by `targetSuffix` (must be declared earlier in the array). Tables persist across uninstalls. A `tableRef` property may also carry `sharedTable: true`, declaring that the table is the APP'S OWN — the author picks an existing table and the widget seeds nothing for it. That is the correct shape for a widget that reads data it does not own (a chart, a metric, a manager view over another widget's table). `sharedTable` exempts the property from needing a seeded table at publish (`manifest.requiredTableRefsHaveTemplate`) WITHOUT making it optional: the author must still bind one, and the host still refuses to place the widget unbound. Use it instead of dropping `required` — a widget that silently renders an empty tile is the defect it looks like a fix for. sc-7530: a table may also declare `roleGrants` — group-scoped access named SYMBOLICALLY, because a group id belongs to the workspace that installs the widget and could never travel in the manifest. Declare the audiences once at template level as `roles: [{ key, label, description? }]` (key is lowercase kebab, max 8 roles), then per table `roleGrants: [{ role, canRead?, canWrite?, canDelete? }]`. The installing workspace binds each role to one of its own user groups (or has one created) during the install consent step, so a permission model where an admin group does everything and signed-in users only read survives the trip between workspaces. Use `publicGrant` for the two id-less audiences (everyone / any signed-in user) and `roleGrants` for anything that names a group. A role nobody binds simply writes no grant — it never fails the install.",
   },
   translations: {
     type: "object",
@@ -3913,7 +3913,20 @@ const CONTRACT = deepFreeze({
   // the web half is a widget.web.jsx typed-code or QR path. Pinned in the
   // export and gated behind the `nfc` export capability, because its iOS
   // entitlement obliges every App ID that carries it.
-  version: "1.104.0",
+  // 1.105.0: additive (sc-7530) — a `datastoreTemplate` can declare the
+  //    AUDIENCES its tables grant access to, not just the two id-less ones.
+  //    `publicGrant` could only ever reach `everyone` and `authenticated`, so a
+  //    widget whose author had set up "an admin group does everything, signed-in
+  //    users only read" shipped that model to nobody: a group id is tenant-local
+  //    and cannot travel in a manifest. Templates now declare `roles:
+  //    [{ key, label, description? }]` once (lowercase-kebab key, max 8) and
+  //    per table `roleGrants: [{ role, canRead?, canWrite?, canDelete? }]`; the
+  //    installing workspace binds each role to one of ITS OWN user groups — or
+  //    has one created — during the install consent step. Purely additive: a
+  //    template declaring neither behaves exactly as before, and a role nobody
+  //    binds writes no grant rather than failing the install. Minor bump on the
+  //    pre-1.0 channel.
+  version: "1.105.0",
   sharedTranslationKeys: SHARED_TRANSLATION_KEYS,
   hooks: HOOKS,
   primitives: PRIMITIVES,

package/dist/index.d.ts

@@ -201,6 +201,14 @@ export interface WidgetDatastoreTemplateTable {
    * studio-owner only regardless.
    */
   publicGrant?: { canRead?: boolean; canWrite?: boolean; canDelete?: boolean };
+  /**
+   * sc-7530: group-scoped grants, named symbolically. Each entry's `role` must
+   * be a `key` declared on the template's `roles`. Unlike `publicGrant` — which
+   * can only reach the two synthetic principals (`everyone` / `authenticated`)
+   * — these express "this audience gets these verbs" and are bound to a real
+   * group by the workspace that installs the widget.
+   */
+  roleGrants?: WidgetDatastoreTemplateRoleGrant[];
   columns: WidgetDatastoreTemplateColumn[];
   /**
    * Optional sample rows seeded into the table at install time so the widget
@@ -213,8 +221,44 @@ export interface WidgetDatastoreTemplateTable {
   >;
 }
 
+/**
+ * sc-7530: a role the template's `roleGrants` name. Declared once per template
+ * and referenced by every table, so several widgets over several tables ask the
+ * installing workspace ONE question per audience rather than one per grant.
+ *
+ * Symbolic on purpose. A group id is tenant-local, so it could only ever be
+ * wrong in the workspace that installs the widget — the installer binds each
+ * role to one of their OWN groups (or has one created) at install time.
+ */
+export interface WidgetDatastoreTemplateRole {
+  /** Stable within the template; matches /^[a-z][a-z0-9-]*$/. */
+  key: string;
+  /** What the installing workspace sees in the binding step. */
+  label: string;
+  /** Why the role exists — shown under the label. */
+  description?: string;
+}
+
+/** sc-7530: the verbs one role holds over one table. */
+export interface WidgetDatastoreTemplateRoleGrant {
+  /** A `key` from the template's `roles`. */
+  role: string;
+  /** Read the table and the rows in it. */
+  canRead?: boolean;
+  /** Create records, and edit existing ones. */
+  canWrite?: boolean;
+  /** Delete records. Row-level only — table scope has no delete verb. */
+  canDelete?: boolean;
+}
+
 export interface WidgetDatastoreTemplate {
   tables: WidgetDatastoreTemplateTable[];
+  /**
+   * sc-7530: the audiences this template's tables grant access to. Bound to
+   * real `AppUserGroup`s by the installing workspace; an unbound role simply
+   * writes no grant.
+   */
+  roles?: WidgetDatastoreTemplateRole[];
 }
 
 /**

package/package.json

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