@colixsystems/widget-sdk 0.205.1 → 0.207.0

package/dist/toast-host.js

@@ -18,7 +18,7 @@ export const TOAST_DEFAULTS = Object.freeze({
 const KINDS = Object.freeze(["success", "error", "warning", "info"]);
 
 // `error` is the widget-facing kind; `danger` is the theme's colour role.
-const KIND_COLOR_ROLE = Object.freeze({
+export const KIND_COLOR_ROLE = Object.freeze({
   success: "success",
   error: "danger",
   warning: "warning",

package/package.json

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

package/src/contract.js

@@ -704,6 +704,25 @@ const THEME_COMPONENTS = Object.freeze({
     }),
     targets: Object.freeze({}),
   }),
+  // Inline messages: `<Banner>` reads this scope directly, so it names the
+  // SDK component it styles and binds no widget field.
+  alert: Object.freeze({
+    label: "Alerts",
+    sdkComponents: Object.freeze(["Banner"]),
+    tokens: Object.freeze({
+      radius: Object.freeze({ type: "size", min: 0, max: 32, uiDefault: "radii.md" }),
+      borderWidth: Object.freeze({ type: "size", min: 0, max: 4 }),
+      infoBackground: Object.freeze({ type: "color" }),
+      infoTextColor: Object.freeze({ type: "color" }),
+      successBackground: Object.freeze({ type: "color" }),
+      successTextColor: Object.freeze({ type: "color" }),
+      warningBackground: Object.freeze({ type: "color" }),
+      warningTextColor: Object.freeze({ type: "color" }),
+      errorBackground: Object.freeze({ type: "color" }),
+      errorTextColor: Object.freeze({ type: "color" }),
+    }),
+    targets: Object.freeze({}),
+  }),
 });
 
 // sc-4505 — the value types a widget event payload field may declare. Narrower
@@ -2064,6 +2083,62 @@ const HOOKS = [
     requiredContextSlice: ["directory.users"],
     scopes: ["users.activity:*"],
   },
+  // sc-11025 / REQ-USERMGMT-12 — online status for people who share a record.
+  {
+    name: "useOnlineMembers",
+    signature: "useOnlineMembers(tableId, recordIds)",
+    description:
+      "Who is online among the members of each record the viewer is a " +
+      "member of (a conversation, a team, a case), on a table that shows its " +
+      "members' online status (a template table's `presence: true`, or the " +
+      "table setting in the Studio). Members hold their OWN read grant on the " +
+      "record, given to them by a person (a grant from a template or one " +
+      "inherited from a parent row names no member). `online` is a Set of " +
+      "the user ids online across the records; `byRecord[recordId]` is " +
+      "{ online_user_ids, online_count } — the ids are capped at 100 per " +
+      "record, so count with `online_count`. A record the viewer only reads " +
+      "(through a group or a grant to everyone) or cannot read answers with " +
+      "nobody. Refreshes every minute while the app is in front, on return " +
+      "to it and on pull-to-refresh. `supported` is true only once the " +
+      "workspace answered: it is false while the workspace does not record " +
+      "user activity, when the table has not opted in, when the viewer hides " +
+      "their own status (useOnlineVisibility), and in a preview — then show " +
+      "NO online state at all, never \"offline\". The viewer's own id may be " +
+      "in `online`; leave it out when you mean \"someone else is here\". " +
+      "Never timestamps. Declare `directory.read:users`: the publish checks " +
+      "do not require it for this hook, but it is the scope the hook belongs to.",
+    returnShape: {
+      supported: "boolean  // false: render no online dots, no counts, no 'offline' state",
+      online: "Set<string>  // user ids online across the records",
+      byRecord: "{ [recordId]: { online_user_ids: string[], online_count: number } }",
+      loading: "boolean",
+      error: "DirectoryError | null  // reason ACTIVITY_UNAVAILABLE, ACTIVITY_DISABLED, ONLINE_STATUS_HIDDEN, PRESENCE_NOT_ENABLED or FORBIDDEN (not a live person) when refused",
+      refetch: "() => Promise<void>",
+    },
+    requiredContextSlice: ["directory.presence"],
+    scopes: ["directory.read:users"],
+  },
+  {
+    name: "useOnlineVisibility",
+    signature: "useOnlineVisibility()",
+    description:
+      "The viewer's own \"Show when I'm online\" switch, on by default. " +
+      "`supported` is false where the workspace shows nobody online: offer " +
+      "the switch only when it is true. `setShowOnline(false)` hides the " +
+      "viewer from everyone, and they then see nobody online either; every " +
+      "useOnlineMembers on the page re-reads. No scope: it is the viewer's " +
+      "own setting.",
+    returnShape: {
+      supported: "boolean",
+      showOnline: "boolean | null  // null until known",
+      loading: "boolean",
+      saving: "boolean",
+      error: "DirectoryError | null",
+      setShowOnline: "(showOnline: boolean) => Promise<void>  // rejects with DirectoryError",
+    },
+    requiredContextSlice: ["directory.presence"],
+    scopes: null,
+  },
   // REQ-USERMGMT / REQ-ACL-SYS M3 — AppUserGroup administration. Returns
   // `{ groups, loading, error, refetch, create, remove, addMember, removeMember }`.
   // Reads need `groups.read:*`; mutations need `groups.write:*`. Removing a
@@ -2906,6 +2981,13 @@ const PRIMITIVES = [
     rnComponent: null,
     docsUrl: null,
   },
+  {
+    name: "Banner",
+    description:
+      'Themed inline message. `<Banner tone="error" title="Could not save" message={err.message} action={{ label: "Retry", onPress: save }} onDismiss={() => setErr(null)} />`. THE way to show an error, warning, success or notice that belongs to a place in the widget and stays until it is resolved: a list that failed to load, a form the user cannot submit yet, a "read-only" or "offline" notice. Render it where the problem is — above the list or form it concerns. Use `useToast()` instead for a brief confirmation of something the user just did ("Saved", "Deleted") that needs no decision and may disappear on its own; never both for one event. Its fill, text colour, border and corner radius come from the app\'s theme per tone (Design > Components > Alerts), so never hand-roll a tinted box from `View` + a border + a hex. Props: `tone` ("info" default | "success" | "warning" | "error"), `title` (optional, one short line) and `message` (wraps — never truncate it): text, or an element you built when part of it needs its own styling, `icon` (a lucide name replacing the tone\'s own glyph, or `false` for none), `action` (`{ label, onPress, accessibilityLabel?, testID? }`, ONE action such as Retry), `onDismiss` (pass it to show a close control; you hide the banner in the handler), `dismissAccessibilityLabel` (default "Dismiss" — pass a translated one), `style` (spacing around it), `testID`. An `error` is marked as an alert, and the other tones as a polite status: the web and Android announce them when they appear, while iOS reads the banner in place.',
+    rnComponent: null,
+    docsUrl: null,
+  },
   {
     name: "Accordion",
     description:
@@ -3214,7 +3296,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` (any table in the same array, in any order; tables may relate to each other both ways). 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. sc-7557: a column may declare `encrypted: true` — its values are stored AES-256-GCM encrypted at rest under a per-workspace subkey. The widget still reads and writes PLAINTEXT (the platform encrypts on write, decrypts for end users); studio users see `🔒` instead, and the column cannot be searched, filtered or sorted on. Sample `rows` you seed for it are encrypted the same way. Not valid on `RELATION` — its value is a foreign key the backend must resolve — and publishing one is rejected. An `inheritAcl` RELATION column may add `inheritAclReadOnly: true` — rows then inherit READ access only, so members of the parent read every child and may add children, but change or delete only the rows they created (pair with `grantCreatorPermissions`). A column may declare `defaultValue`, written when a create omits it: `@currentUser` on USER, `@now` on DATE / DATETIME, or a literal of the column's own type (none on FILE, RELATION or USER_GROUP — ids belong to the installing workspace). `defaultLocked: true` on an `@currentUser` / `@now` default makes the server always stamp it and ignore any client value on create and update, so an author column cannot be forged. `immutable: true` makes a column write-once: a create sets it as usual and any value sent for it on update is ignored (not valid on a MANY_TO_MANY relation).",
+      "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` (any table in the same array, in any order; tables may relate to each other both ways). 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. sc-7557: a column may declare `encrypted: true` — its values are stored AES-256-GCM encrypted at rest under a per-workspace subkey. The widget still reads and writes PLAINTEXT (the platform encrypts on write, decrypts for end users); studio users see `🔒` instead, and the column cannot be searched, filtered or sorted on. Sample `rows` you seed for it are encrypted the same way. Not valid on `RELATION` — its value is a foreign key the backend must resolve — and publishing one is rejected. An `inheritAcl` RELATION column may add `inheritAclReadOnly: true` — rows then inherit READ access only, so members of the parent read every child and may add children, but change or delete only the rows they created (pair with `grantCreatorPermissions`). A column may declare `defaultValue`, written when a create omits it: `@currentUser` on USER, `@now` on DATE / DATETIME, or a literal of the column's own type (none on FILE, RELATION or USER_GROUP — ids belong to the installing workspace). `defaultLocked: true` on an `@currentUser` / `@now` default makes the server always stamp it and ignore any client value on create and update, so an author column cannot be forged. `immutable: true` makes a column write-once: a create sets it as usual and any value sent for it on update is ignored (not valid on a MANY_TO_MANY relation). A table may declare `presence: true` so the people who share a row see which of each other are online (useOnlineMembers); it takes effect only while the workspace records user activity, and an upgrade that declares it turns it on for the existing table.",
   },
   translations: {
     type: "object",
@@ -3365,10 +3447,11 @@ const WIDGET_CONTEXT_SHAPE = {
       "{ me(), users: { list(query?) -> Promise<{ data, meta }>, get(id), invite(body), deactivate(id), reactivate(id) }, " +
       "groups: { list(query?) -> Promise<{ data, meta }>, create(body), remove(id), addMember(groupId, userId), removeMember(groupId, userId), listMine() }, " +
       "invites: { list(), revoke(id), resend(id) }, " +
-      "bankid: { status() -> { linked, available }, startLink() -> { order_ref, qr, ... }, collect(orderRef), cancel(orderRef), unlink() } }. " +
-      "users backs useDirectory() + useUsers(); groups backs useGroups(); invites backs useInvites() (list/resend/revoke pending invites, gated by users.write:* + the users.write capability); bankid backs useBankIdLink() (REQ-BANKID-AUTH — self-service account linking, JWT-gated, no widget scope). List methods return the { data, meta } envelope verbatim (hooks unwrap res.data); rows/bodies are snake_case. Reads gated by directory.read:users / users.read:* / groups.read:*; mutations by users.write:* / groups.write:* (destructive user removal by users.delete:*).",
+      "bankid: { status() -> { linked, available }, startLink() -> { order_ref, qr, ... }, collect(orderRef), cancel(orderRef), unlink() }, " +
+      "presence: { online(tableId, recordIds) -> { data: [{ record_id, online_user_ids, online_count }] }, me() -> { show_online }, setShowOnline(bool) -> { show_online } } }. " +
+      "users backs useDirectory() + useUsers(); groups backs useGroups(); invites backs useInvites() (list/resend/revoke pending invites, gated by users.write:* + the users.write capability); bankid backs useBankIdLink() (REQ-BANKID-AUTH — self-service account linking, JWT-gated, no widget scope); presence backs useOnlineMembers() + useOnlineVisibility() (session-gated, no scope header). List methods return the { data, meta } envelope verbatim (hooks unwrap res.data); rows/bodies are snake_case. Reads gated by directory.read:users / users.read:* / groups.read:*; mutations by users.write:* / groups.write:* (destructive user removal by users.delete:*).",
     required: true,
-    fields: { users: "object", groups: "object", invites: "object", bankid: "object" },
+    fields: { users: "object", groups: "object", invites: "object", bankid: "object", presence: "object" },
   },
   assets: {
     description:
@@ -5460,7 +5543,14 @@ const CONTRACT = deepFreeze({
   //    and `useInactiveUsers` read user activity through the new
   //    `ctx.directory.users.activity` / `.inactive` / `.remind`, behind the
   //    new `users.activity:*` scope.
-  version: "1.164.0",
+  // 1.165.0: additive (sc-11025) — `useOnlineMembers(tableId, recordIds)`
+  //    and `useOnlineVisibility()` read who of a record's members is online
+  //    and the viewer's own switch, through the new `ctx.directory.presence`.
+  //    A `datastoreTemplate` table may declare `presence: true`.
+  // 1.166.0: additive (sc-10927) — the `Banner` primitive (a themed inline
+  //    error, warning, success or notice) and the `alert` component scope it
+  //    reads.
+  version: "1.166.0",
   sharedTranslationKeys: SHARED_TRANSLATION_KEYS,
   hooks: HOOKS,
   primitives: PRIMITIVES,