@colixsystems/widget-sdk 0.265.0 → 0.266.1

package/README.md

@@ -69,7 +69,7 @@ The data layer lives in **four separate domain-client packages**, each instantia
 | **DIRECTORY** (`ctx.directory`) | `useDirectory(query)` (optional: query) | `{ users, loading, error, refetch }` | `directory.users.list` — `directory.read:users` |
 | **DIRECTORY** | `useUsers(query)` (optional: query) | `{ users, loading, error, refetch, invite, deactivate, reactivate, remove, sendPasswordReset, update }` | `directory.users.*` — `users.read:*` plus the `users.read` (or `users.write`) capability, else `FORBIDDEN` (edits, incl. `sendPasswordReset()` and `update()`, also `users.write:*`; `remove()` also `users.delete:*`) |
 | **DIRECTORY** | `useGroups(query)` (optional: query) | `{ groups, loading, error, refetch, create, remove, addMember, removeMember }` | `directory.groups.*` — `groups.read:*` (mutations also `groups.write:*`) |
-| **DIRECTORY** | `useInvites(query)` (optional: query) | `{ invites, loading, error, refetch, resend, revoke }` | `directory.invites.*` — `users.write:*` + the SystemAcl `users.write` capability (the whole invite surface, list included). `query` is `{ status?, q?, app_user_id?, limit?, offset? }` with `status` ∈ `pending \| accepted \| revoked \| expired \| open \| all` (endpoint default `all`; `open` = `pending` or `expired`); `q` matches the invite's name or email, `app_user_id` returns the invites reserving that user id. |
+| **DIRECTORY** | `useInvites(query)` (optional: query) | `{ invites, loading, error, refetch, resend, revoke }` | `directory.invites.*` — `users.write:*` + the SystemAcl `users.write` capability (the whole invite surface, list included). `query` is `{ status?, q?, app_user_id?, limit?, offset? }` with `status` ∈ `pending \| accepted \| revoked \| expired \| not_sent \| open \| all` (endpoint default `all`; `open` = `pending`, `not_sent` or `expired`); `q` matches the invite's name or email, `app_user_id` returns the invites reserving that user id. `resend(inviteId)` sends the invitation — the first send of a `not_sent` one included. |
 | **DIRECTORY** | `useBankIdLink()` | `{ linked, available, status, qr, message, startLink, refresh, cancel, unlink, refetchStatus, … }` | `directory.bankid.*` — no scope (JWT-gated self-service) |
 | **FILESTORE** (`ctx.filestore`) | `usePdfExport({ spaceType, folderId })` (optional: spaceType, folderId) | `{ openPdf, opening, canOpenPdf, exportToPdf, exporting, error, lastExported }` | `ctx.filestore.files.renderPdf` + `ctx.device.pdfViewer`, `ctx.filestore.files.exportPdf` — `files.write:*`. `openPdf(html, { fileName? })` renders the HTML to a PDF server-side and OPENS it (web: PDF tab; native: print / share sheet) without saving. `exportToPdf(html, { fileName?, folderId? })` renders it and saves it as a file (`application/pdf`). Same server-side renderer on web + native. |
 | **PAYMENTS** (`ctx.payments`) | `usePayments()` | `{ requestPayment, getPayment }` | `ctx.payments.*` — `payments.charge:appUser`. Rejects with `PaymentError { code, message, retryable }`; when `retryable` is `false` show `message` and drop the retry. Charges are accepted ONLY in the currency the workspace sells in — omit `currency` and the platform applies it (a disagreeing literal is a publish-blocking `payment-currency` finding). |
@@ -86,7 +86,32 @@ See the design reference for the full architecture: [`docs/architecture/widget-m
 
 ## Status
 
-`v0.265.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.266.1` — 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.266.1 (contract 1.216.0)
+
+**An open `<Modal>` or `<Overlay>` holds the page still on the web.** Scrolling past the end of a dialog's body, or over a dialog with nothing to scroll, used to scroll the page behind it. The page now stays put until the dialog closes, as it already did in the phone app. Nothing changes for a widget. An anchored `<Menu>`, `<Popover>` or `<Tooltip>` still closes when the page scrolls under it.
+
+### What's new in 0.266.0 (contract 1.216.0)
+
+**A widget can prepare an invitation now and send it later, again.** 0.194.0 withdrew this; it is back with the same shape. Without it `useUsers().invite()` emails the invitation the moment it is created, so a widget could not line people up ahead of a launch day or let a second person check the list first. `invite()` now takes an optional `send_invitation`:
+
+```js
+const { invite } = useUsers();
+const { invites, resend } = useInvites({ status: "not_sent" });
+
+const prepared = await invite({ email: "bo@example.com", name: "Bo", send_invitation: false });
+// prepared.status === "not_sent", prepared.sent_at === null — nobody was emailed.
+
+await resend(prepared.id);   // emails it; the row is now "pending" with a fresh 7-day expiry
+```
+
+- **`send_invitation`** defaults to `true`, so an existing `invite({ email, name, group_ids })` call emails at once exactly as before. `false` stores the invitation and emails nobody. A value that is not a boolean rejects with a `DirectoryError` coded `VALIDATION`.
+- **`not_sent` joins the invite `status` values**, and every invite row carries **`sent_at`** (`null` until the first send). A `not_sent` invitation cannot be accepted yet and its `expires_at` means nothing until it is sent, so show no expiry for it. `useInvites({ status: "not_sent" })` lists just the prepared ones. Where several states apply the first of accepted, revoked, not_sent, expired, pending wins.
+- **`useInvites().resend(inviteId)` is the one call that sends**, whether or not the invitation was sent before. There is no separate `send` method: on a `not_sent` row it is the first send, on a `pending` or `expired` one it sends again, and either way it stamps `sent_at`, restarts the expiry and resolves the row as `pending`. Label the button to match the row — "Send invitation" when `status === "not_sent"`, "Resend" otherwise.
+- **A widget that switches on `status` should handle the new value.** A `not_sent` row falls through an `if (status === "pending")` check, so a list that offers its actions only to pending rows would leave a prepared invitation with no way to send it.
+
+The built-in User Management widget offers the choice on its invite form ("Send the invitation later", off by default) and a "Send invitation" action on each row that has not been sent. No new scope: both calls sit under `users.write:*`, as before.
 
 ### What's new in 0.265.0 (contract 1.215.0)
 
@@ -1311,7 +1336,7 @@ An installed widget is not rebuilt or republished for this. The web Player hands
 
 ### What's new in 0.183.0 (contract 1.144.0)
 
-Send-later invitations (`send_invitation`, the `not_sent` status, `sent_at`). Withdrawn in 0.194.0.
+Send-later invitations (`send_invitation`, the `not_sent` status, `sent_at`). Withdrawn in 0.194.0, reinstated in 0.266.0.
 
 ### What's new in 0.182.0 (contract 1.143.0)
 
@@ -3349,11 +3374,13 @@ The matching manifest declares the scopes:
 }
 ```
 
+`invite()` emails the invitation at once. Pass `send_invitation: false` to store it without emailing anyone — the row comes back with `status: "not_sent"` and `sent_at: null` — and send it later with `useInvites().resend(inviteId)`.
+
 The host rejects calls whose scope is not declared in the manifest (the SDK linter catches this statically too). Declaring a write scope is also a consent prompt the Studio admin sees at install time — the wider the scope set, the more careful the admin is about granting the install.
 
 ## Listing pending invitations from a widget
 
-`useInvites(query?)` lists the workspace's invites and resends / revokes them:
+`useInvites(query?)` lists the workspace's invites and sends / revokes them:
 
 ```jsx
 import { useInvites, View, Text, Pressable } from '@colixsystems/widget-sdk';
@@ -3368,7 +3395,9 @@ function PendingInvites() {
       {invites.map((i) => (
         <View key={i.id}>
           <Text>{i.email} · {i.status}</Text>
-          <Pressable onPress={() => resend(i.id).catch(() => {})}><Text>Resend</Text></Pressable>
+          <Pressable onPress={() => resend(i.id).catch(() => {})}>
+            <Text>{i.status === 'not_sent' ? 'Send invitation' : 'Resend'}</Text>
+          </Pressable>
           <Pressable onPress={() => revoke(i.id).catch(() => {})}><Text>Revoke</Text></Pressable>
         </View>
       ))}
@@ -3377,9 +3406,16 @@ function PendingInvites() {
 }
 ```
 
-Rows are snake_case: `{ id, app_user_id, email, name, group_ids, status, expires_at,
-accepted_at, revoked_at, created_at }`. Trust the server-computed `status` rather than
-comparing `expires_at` against the device clock.
+Rows are snake_case: `{ id, app_user_id, email, name, group_ids, status, sent_at,
+expires_at, accepted_at, revoked_at, created_at }`. `status` is one of `pending`,
+`accepted`, `revoked`, `expired` or `not_sent`; trust the server-computed value rather
+than comparing `expires_at` against the device clock.
+
+A `not_sent` row is an invitation created with `send_invitation: false`: nobody has
+been emailed and `sent_at` is `null`. `resend(inviteId)` is the one call that sends
+an invitation, a first send and a repeat send alike — it emails the invitee, stamps
+`sent_at`, restarts the 7-day expiry and resolves the row as `pending`. Pass
+`{ status: 'not_sent' }` to list only the prepared ones.
 
 `query` also takes `q` (a case-insensitive substring match on the invite's name or
 email) and `app_user_id`. Each row's `app_user_id` is the id the invitee's user account
@@ -3387,7 +3423,7 @@ will have once they accept. A `USER` column may hold that id before the person h
 joined — it then reads back as `{ id, name, invited: true }`, with no `email` — and
 `useInvites({ app_user_id: value.id, status: 'open', limit: 1 })` returns the invite
 behind it. `status: 'open'` is every invite that is neither accepted nor revoked
-(`pending` or `expired`); a re-invite keeps the id, so without it earlier invites match too.
+(`pending`, `not_sent` or `expired`); a re-invite keeps the id, so without it earlier invites match too.
 
 **The gate is `users.write`, not `users.read`.** A pending invite exposes the email of
 someone who is not a member yet, so the backend gates the entire invite surface —

package/dist/contract.cjs

@@ -2361,8 +2361,9 @@ const HOOKS = [
   // deactivate / reactivate / sendPasswordReset / update) additionally need
   // `users.write:*`, and the
   // destructive `remove` needs `users.delete:*` (SC-902). The `invite`
-  // call accepts `{ email, name, groupIds? }` and returns the resulting
-  // AppUserInvite row (the email is sent by the host). Mutating users from
+  // call accepts `{ email, name, group_ids?, send_invitation? }` and returns
+  // the resulting AppUserInvite row (the host sends the email, unless
+  // `send_invitation` is false). Mutating users from
   // a widget requires the corresponding SystemAcl capability grant in the
   // tenant (`users.write` for edits, `users.delete` for removal); widgets
   // that only call read methods need only `users.read:*`.
@@ -2382,8 +2383,13 @@ const HOOKS = [
       "scope; edit-style mutations (invite/deactivate/reactivate/" +
       "sendPasswordReset/update) need users.write:*, and the destructive remove() " +
       "additionally needs users.delete:* (SC-902). The `invite` call accepts " +
-      "{ email, name, group_ids? } and returns the resulting AppUserInvite row " +
-      "(the email is sent by the host). sendPasswordReset(userId) mails the " +
+      "{ email, name, group_ids?, send_invitation? } and returns the resulting " +
+      "AppUserInvite row { id, email, name, expires_at, sent_at, status }. " +
+      "The host emails the invitation at once unless send_invitation is " +
+      "false: then nothing is emailed, the row comes back with sent_at null " +
+      "and status 'not_sent', and useInvites().resend(inviteId) sends it " +
+      "later. A send_invitation that is not a boolean rejects with " +
+      "DirectoryError code VALIDATION. sendPasswordReset(userId) mails the " +
       "standard self-serve reset link to that user's own registered address " +
       "and resolves { sent, email_masked } — never the token or the link, so " +
       "it cannot be used to sign in as them. It rejects with a DirectoryError " +
@@ -2422,7 +2428,7 @@ const HOOKS = [
       error: "DirectoryError | null  // { code, reason, message, retryable }",
       refetch: "() => Promise<void>",
       invite:
-        "({ email, name, group_ids? }) => Promise<Invite>  // rejects with DirectoryError",
+        "({ email, name, group_ids?, send_invitation? }) => Promise<Invite>  // send_invitation: false stores it unsent (status 'not_sent'); rejects with DirectoryError",
       deactivate: "(userId) => Promise<User>  // rejects with DirectoryError",
       reactivate: "(userId) => Promise<User>  // rejects with DirectoryError",
       remove: "(userId) => Promise<void>  // rejects with DirectoryError",
@@ -2640,7 +2646,8 @@ const HOOKS = [
   // sc-5097 — pending AppUser invite administration. Returns
   // `{ invites, loading, error, refetch, resend, revoke }`. Reads need
   // `invites.read:*`; resend/revoke need `invites.write:*` plus the
-  // caller's `users.write` SystemAcl capability.
+  // caller's `users.write` SystemAcl capability. sc-9714: `resend` is also
+  // the first send of a `not_sent` invite — there is no separate `send`.
   {
     name: "useInvites",
     signature: "useInvites(query)",
@@ -2650,13 +2657,23 @@ const HOOKS = [
       "directory-client at ctx.directory.invites.{list,resend,revoke}. " +
       "Returns { invites, loading, error, refetch, resend, revoke }. list " +
       "returns the { data, meta } envelope verbatim — the hook unwraps " +
-      "res.data; rows are snake_case (email, status, expires_at, …) and " +
-      "status is the server-computed pending/accepted/revoked/expired " +
-      "value. query is { status?, q?, app_user_id?, limit?, offset? } passed " +
+      "res.data; rows are snake_case (email, status, sent_at, expires_at, …) " +
+      "and status is the server-computed pending/accepted/revoked/expired/" +
+      "not_sent value. not_sent is an invitation created with " +
+      "send_invitation: false that has not been emailed yet: its sent_at is " +
+      "null, it cannot be accepted until it is sent, and its expires_at " +
+      "means nothing yet, so show no expiry for it. resend(inviteId) is the " +
+      "ONE call that sends an invitation — the first send of a not_sent one " +
+      "and a repeat send of a sent one alike: it emails the invitee, stamps " +
+      "sent_at, restarts the 7-day expiry and resolves the row with status " +
+      "'pending'. There is no separate send method; label the button " +
+      "'Send invitation' on a not_sent row and 'Resend' on a pending one. " +
+      "query is { status?, q?, app_user_id?, limit?, offset? } passed " +
       "verbatim; the endpoint defaults to status 'all', so pass " +
-      "{ status: 'pending' } for the usual outstanding-invite list; " +
-      "status 'open' is every invite neither accepted nor revoked (pending " +
-      "or expired). q is a " +
+      "{ status: 'pending' } for the usual outstanding-invite list and " +
+      "{ status: 'not_sent' } for the prepared ones; " +
+      "status 'open' is every invite neither accepted nor revoked (pending, " +
+      "not_sent or expired). q is a " +
       "case-insensitive substring match on the invite's name or email. " +
       "Each row's app_user_id is the id the invitee's user account will " +
       "have once they accept; a USER column may already hold it, and " +
@@ -2673,12 +2690,12 @@ const HOOKS = [
       "refetch on success.",
     returnShape: {
       invites:
-        "Array<{ id, app_user_id, email, name, group_ids, status, expires_at, accepted_at, revoked_at, created_at }>  // snake_case rows; unwrapped from { data, meta }",
+        "Array<{ id, app_user_id, email, name, group_ids, status, sent_at, expires_at, accepted_at, revoked_at, created_at }>  // snake_case rows; status is pending | accepted | revoked | expired | not_sent; unwrapped from { data, meta }",
       loading: "boolean",
       error: "DirectoryError | null  // { code, message, retryable }",
       refetch: "() => Promise<void>",
       resend:
-        "(inviteId) => Promise<Invite>  // refetches; rejects with DirectoryError",
+        "(inviteId) => Promise<Invite>  // sends it (first send of a not_sent invite too); refetches; rejects with DirectoryError",
       revoke:
         "(inviteId) => Promise<void>  // refetches; rejects with DirectoryError",
     },
@@ -4172,7 +4189,7 @@ const WIDGET_CONTEXT_SHAPE = {
       "invites: { list(), revoke(id), resend(id) }, " +
       "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:*).",
+      "users backs useDirectory() + useUsers(); groups backs useGroups(); invites backs useInvites() (list/resend/revoke invites — resend also sends one created with send_invitation: false — 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", presence: "object" },
   },
@@ -6445,7 +6462,11 @@ const CONTRACT = deepFreeze({
   //    random id per row and may be `defaultLocked`.
   // 1.215.0: additive (sc-13938) — `usePdfExport` `openPdf` / `exportToPdf`
   //    take `appendFileIds`: stored PDFs whose pages follow the rendered HTML.
-  version: "1.215.0",
+  // 1.216.0: additive (sc-14096) — reinstates 1.144.0, withdrawn in 1.155.0:
+  //    `useUsers().invite` takes `send_invitation` (false stores the invite
+  //    unsent), invite rows carry `sent_at`, `not_sent` is a status, and
+  //    `useInvites().resend` performs the first send.
+  version: "1.216.0",
   sharedTranslationKeys: SHARED_TRANSLATION_KEYS,
   hooks: HOOKS,
   primitives: PRIMITIVES,

package/dist/contract.js

@@ -2358,8 +2358,9 @@ const HOOKS = [
   // deactivate / reactivate / sendPasswordReset / update) additionally need
   // `users.write:*`, and the
   // destructive `remove` needs `users.delete:*` (SC-902). The `invite`
-  // call accepts `{ email, name, groupIds? }` and returns the resulting
-  // AppUserInvite row (the email is sent by the host). Mutating users from
+  // call accepts `{ email, name, group_ids?, send_invitation? }` and returns
+  // the resulting AppUserInvite row (the host sends the email, unless
+  // `send_invitation` is false). Mutating users from
   // a widget requires the corresponding SystemAcl capability grant in the
   // tenant (`users.write` for edits, `users.delete` for removal); widgets
   // that only call read methods need only `users.read:*`.
@@ -2379,8 +2380,13 @@ const HOOKS = [
       "scope; edit-style mutations (invite/deactivate/reactivate/" +
       "sendPasswordReset/update) need users.write:*, and the destructive remove() " +
       "additionally needs users.delete:* (SC-902). The `invite` call accepts " +
-      "{ email, name, group_ids? } and returns the resulting AppUserInvite row " +
-      "(the email is sent by the host). sendPasswordReset(userId) mails the " +
+      "{ email, name, group_ids?, send_invitation? } and returns the resulting " +
+      "AppUserInvite row { id, email, name, expires_at, sent_at, status }. " +
+      "The host emails the invitation at once unless send_invitation is " +
+      "false: then nothing is emailed, the row comes back with sent_at null " +
+      "and status 'not_sent', and useInvites().resend(inviteId) sends it " +
+      "later. A send_invitation that is not a boolean rejects with " +
+      "DirectoryError code VALIDATION. sendPasswordReset(userId) mails the " +
       "standard self-serve reset link to that user's own registered address " +
       "and resolves { sent, email_masked } — never the token or the link, so " +
       "it cannot be used to sign in as them. It rejects with a DirectoryError " +
@@ -2419,7 +2425,7 @@ const HOOKS = [
       error: "DirectoryError | null  // { code, reason, message, retryable }",
       refetch: "() => Promise<void>",
       invite:
-        "({ email, name, group_ids? }) => Promise<Invite>  // rejects with DirectoryError",
+        "({ email, name, group_ids?, send_invitation? }) => Promise<Invite>  // send_invitation: false stores it unsent (status 'not_sent'); rejects with DirectoryError",
       deactivate: "(userId) => Promise<User>  // rejects with DirectoryError",
       reactivate: "(userId) => Promise<User>  // rejects with DirectoryError",
       remove: "(userId) => Promise<void>  // rejects with DirectoryError",
@@ -2637,7 +2643,8 @@ const HOOKS = [
   // sc-5097 — pending AppUser invite administration. Returns
   // `{ invites, loading, error, refetch, resend, revoke }`. Reads need
   // `invites.read:*`; resend/revoke need `invites.write:*` plus the
-  // caller's `users.write` SystemAcl capability.
+  // caller's `users.write` SystemAcl capability. sc-9714: `resend` is also
+  // the first send of a `not_sent` invite — there is no separate `send`.
   {
     name: "useInvites",
     signature: "useInvites(query)",
@@ -2647,13 +2654,23 @@ const HOOKS = [
       "directory-client at ctx.directory.invites.{list,resend,revoke}. " +
       "Returns { invites, loading, error, refetch, resend, revoke }. list " +
       "returns the { data, meta } envelope verbatim — the hook unwraps " +
-      "res.data; rows are snake_case (email, status, expires_at, …) and " +
-      "status is the server-computed pending/accepted/revoked/expired " +
-      "value. query is { status?, q?, app_user_id?, limit?, offset? } passed " +
+      "res.data; rows are snake_case (email, status, sent_at, expires_at, …) " +
+      "and status is the server-computed pending/accepted/revoked/expired/" +
+      "not_sent value. not_sent is an invitation created with " +
+      "send_invitation: false that has not been emailed yet: its sent_at is " +
+      "null, it cannot be accepted until it is sent, and its expires_at " +
+      "means nothing yet, so show no expiry for it. resend(inviteId) is the " +
+      "ONE call that sends an invitation — the first send of a not_sent one " +
+      "and a repeat send of a sent one alike: it emails the invitee, stamps " +
+      "sent_at, restarts the 7-day expiry and resolves the row with status " +
+      "'pending'. There is no separate send method; label the button " +
+      "'Send invitation' on a not_sent row and 'Resend' on a pending one. " +
+      "query is { status?, q?, app_user_id?, limit?, offset? } passed " +
       "verbatim; the endpoint defaults to status 'all', so pass " +
-      "{ status: 'pending' } for the usual outstanding-invite list; " +
-      "status 'open' is every invite neither accepted nor revoked (pending " +
-      "or expired). q is a " +
+      "{ status: 'pending' } for the usual outstanding-invite list and " +
+      "{ status: 'not_sent' } for the prepared ones; " +
+      "status 'open' is every invite neither accepted nor revoked (pending, " +
+      "not_sent or expired). q is a " +
       "case-insensitive substring match on the invite's name or email. " +
       "Each row's app_user_id is the id the invitee's user account will " +
       "have once they accept; a USER column may already hold it, and " +
@@ -2670,12 +2687,12 @@ const HOOKS = [
       "refetch on success.",
     returnShape: {
       invites:
-        "Array<{ id, app_user_id, email, name, group_ids, status, expires_at, accepted_at, revoked_at, created_at }>  // snake_case rows; unwrapped from { data, meta }",
+        "Array<{ id, app_user_id, email, name, group_ids, status, sent_at, expires_at, accepted_at, revoked_at, created_at }>  // snake_case rows; status is pending | accepted | revoked | expired | not_sent; unwrapped from { data, meta }",
       loading: "boolean",
       error: "DirectoryError | null  // { code, message, retryable }",
       refetch: "() => Promise<void>",
       resend:
-        "(inviteId) => Promise<Invite>  // refetches; rejects with DirectoryError",
+        "(inviteId) => Promise<Invite>  // sends it (first send of a not_sent invite too); refetches; rejects with DirectoryError",
       revoke:
         "(inviteId) => Promise<void>  // refetches; rejects with DirectoryError",
     },
@@ -4169,7 +4186,7 @@ const WIDGET_CONTEXT_SHAPE = {
       "invites: { list(), revoke(id), resend(id) }, " +
       "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:*).",
+      "users backs useDirectory() + useUsers(); groups backs useGroups(); invites backs useInvites() (list/resend/revoke invites — resend also sends one created with send_invitation: false — 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", presence: "object" },
   },
@@ -6442,7 +6459,11 @@ const CONTRACT = deepFreeze({
   //    random id per row and may be `defaultLocked`.
   // 1.215.0: additive (sc-13938) — `usePdfExport` `openPdf` / `exportToPdf`
   //    take `appendFileIds`: stored PDFs whose pages follow the rendered HTML.
-  version: "1.215.0",
+  // 1.216.0: additive (sc-14096) — reinstates 1.144.0, withdrawn in 1.155.0:
+  //    `useUsers().invite` takes `send_invitation` (false stores the invite
+  //    unsent), invite rows carry `sent_at`, `not_sent` is a status, and
+  //    `useInvites().resend` performs the first send.
+  version: "1.216.0",
   sharedTranslationKeys: SHARED_TRANSLATION_KEYS,
   hooks: HOOKS,
   primitives: PRIMITIVES,

package/dist/hooks.js

@@ -5977,7 +5977,7 @@ export function useDirectory(query) {
  * invite, deactivate, reactivate, sendPasswordReset, update}` — `list` resolves to the `{ data, meta }`
  * envelope VERBATIM, so we unwrap `res.data` (default `[]`). User rows are
  * snake_case (`id`, `name`, `email`, `role`, `is_active`, …) and bodies
- * (e.g. `{ email, name, group_ids? }`) pass through verbatim. `query` is an
+ * (e.g. `{ email, name, group_ids?, send_invitation? }`) pass through verbatim. `query` is an
  * optional `{ q?, role?, is_active?, group_id?, limit?, offset? }`; `group_id`
  * (the `id` of a `useGroups()` row) narrows the list to that group's members.
  * The list refetches whenever `JSON.stringify(query)` changes; the imperative methods
@@ -6228,15 +6228,20 @@ export function useGroups(query) {
  * `{ data, meta }` envelope VERBATIM, so we unwrap `res.data` (default `[]`).
  *
  * Rows are snake_case exactly as the backend projects them: `{ id, tenant_id,
- * email, name, group_ids, status, expires_at, accepted_at, revoked_at,
- * created_at, invited_by_studio_user_id }`. `status` is the server-computed
- * lifecycle value (`"pending" | "accepted" | "revoked" | "expired"`) — prefer
- * it over re-deriving expiry on the client, whose clock may disagree.
+ * email, name, group_ids, status, sent_at, expires_at, accepted_at,
+ * revoked_at, created_at, invited_by_studio_user_id }`. `status` is the
+ * server-computed lifecycle value (`"pending" | "accepted" | "revoked" |
+ * "expired" | "not_sent"`) — prefer it over re-deriving expiry on the client,
+ * whose clock may disagree.
+ *
+ * `not_sent` is an invite created with `send_invitation: false`: `sent_at` is
+ * null and nothing was emailed. `resend(inviteId)` is the one call that sends
+ * — a first send and a repeat send alike — and resolves the row as `pending`.
  *
  * `query` is an optional `{ status?, limit?, offset? }` passed through
  * verbatim; `status` accepts `"pending" | "accepted" | "revoked" | "expired" |
- * "all"` and the endpoint defaults to `"all"`, so pass `{ status: "pending" }`
- * for the usual "who hasn't accepted yet" list.
+ * "not_sent" | "all"` and the endpoint defaults to `"all"`, so pass
+ * `{ status: "pending" }` for the usual "who hasn't accepted yet" list.
  *
  * The WHOLE invite surface — list included — is gated on the `users.write`
  * capability plus a signed `users.write:*` scope: a pending invite exposes
@@ -6303,7 +6308,8 @@ export function useInvites(query) {
   }, [doFetch]);
 
   // Both mutations re-list on success: revoking drops the row and resending
-  // moves `expires_at`, so a stale list would show the operator the old state.
+  // moves `expires_at` (and a first send's status), so a stale list would
+  // show the operator the old state.
   const resend = useCallback(
     async (inviteId) => {
       try {

package/dist/index.d.ts

@@ -3289,13 +3289,25 @@ export interface InviteArgs {
   email: string;
   name?: string;
   group_ids?: string[];
+  /**
+   * Defaults to `true`: the invitation is emailed at once. `false` stores it
+   * without emailing anyone (`status: "not_sent"`); send it later with
+   * `useInvites().resend(inviteId)`.
+   */
+  send_invitation?: boolean;
 }
 
+/**
+ * When several apply the first of accepted, revoked, not_sent, expired,
+ * pending wins. `not_sent` is an invitation created with
+ * `send_invitation: false` that has not been emailed yet.
+ */
 export type AppUserInviteStatus =
   | "pending"
   | "accepted"
   | "revoked"
-  | "expired";
+  | "expired"
+  | "not_sent";
 
 export interface AppUserInviteRow {
   id: string;
@@ -3310,7 +3322,9 @@ export interface AppUserInviteRow {
   status: AppUserInviteStatus;
   name?: string;
   group_ids?: string[];
-  invited_at?: string;
+  /** When the invitation email last left; `null` until it is first sent. */
+  sent_at: string | null;
+  /** Meaningless while `status` is `"not_sent"` — it restarts on the send. */
   expires_at?: string;
   accepted_at?: string | null;
   revoked_at?: string | null;
@@ -3410,8 +3424,9 @@ export function useGroups(query?: GroupsQuery): GroupsApi;
 
 export interface InvitesQuery {
   /**
-   * Defaults to "all" server-side; pass "pending" for outstanding invites.
-   * "open" is "pending" or "expired": neither accepted nor revoked.
+   * Defaults to "all" server-side; pass "pending" for outstanding invites and
+   * "not_sent" for the ones prepared but not emailed yet.
+   * "open" is "pending", "not_sent" or "expired": neither accepted nor revoked.
    */
   status?: AppUserInviteStatus | "open" | "all";
   /** Case-insensitive substring match on the invite's name or email. */
@@ -3432,7 +3447,12 @@ export interface InvitesApi {
   loading: boolean;
   error: DirectoryError | null;
   refetch(): Promise<void>;
-  /** Re-send the invitation email. Refetches on success. */
+  /**
+   * Email the invitation and restart its 7-day expiry. The one call that
+   * sends: the first send of a `not_sent` invitation and a repeat send of a
+   * sent one alike. Resolves the row with `status: "pending"`; refetches on
+   * success.
+   */
   resend(inviteId: string): Promise<AppUserInviteRow>;
   /** Cancel a pending invitation. Refetches on success. */
   revoke(inviteId: string): Promise<void>;

package/dist/property-schema.js

@@ -82,6 +82,9 @@ const VALID_TYPES = new Set([
   "object", "array",
 ]);
 
+/** The propertySchema field types, for documentation generated from this list. */
+export const PROPERTY_TYPES = Object.freeze([...VALID_TYPES]);
+
 function isPlainObject(v) {
   return v !== null && typeof v === "object" && !Array.isArray(v);
 }

package/dist/web-modal.js

@@ -59,6 +59,32 @@ function useCloseOnOutsideScroll(container, enabled, onCloseRef) {
   }, [container, enabled, onCloseRef]);
 }
 
+// A dialog owns the screen, as on native: the page beneath must not
+// scroll, even once the dialog's own body runs out of scroll.
+let pageScrollLocks = 0;
+let unlockedRootStyle = null;
+
+function usePageScrollLock(enabled) {
+  React.useEffect(() => {
+    if (!enabled) return undefined;
+    const root = document.documentElement;
+    if (pageScrollLocks++ === 0) {
+      unlockedRootStyle = {
+        overflow: root.style.overflow,
+        scrollbarGutter: root.style.scrollbarGutter,
+      };
+      // Keep a visible scrollbar's space, so the page does not shift sideways.
+      if (window.innerWidth > root.clientWidth) root.style.scrollbarGutter = "stable";
+      root.style.overflow = "hidden";
+    }
+    return () => {
+      if (--pageScrollLocks > 0) return;
+      root.style.overflow = unlockedRootStyle.overflow;
+      root.style.scrollbarGutter = unlockedRootStyle.scrollbarGutter;
+    };
+  }, [enabled]);
+}
+
 function tabStops(dialog) {
   return Array.from(dialog.querySelectorAll(FOCUSABLE)).filter(
     (node) => node.getAttribute("aria-hidden") !== "true",
@@ -147,6 +173,8 @@ function ModalLayer({
   }, [visible]);
   const container = useBodyContainer(visible);
   useCloseOnOutsideScroll(container, closesOnOutsideScroll, onCloseRef);
+  // An anchored panel closes on a scroll beneath instead.
+  usePageScrollLock(Boolean(container) && !closesOnOutsideScroll);
 
   React.useEffect(() => {
     const dialog = dialogRef.current;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@colixsystems/widget-sdk",
-  "version": "0.265.0",
+  "version": "0.266.1",
   "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

@@ -2358,8 +2358,9 @@ const HOOKS = [
   // deactivate / reactivate / sendPasswordReset / update) additionally need
   // `users.write:*`, and the
   // destructive `remove` needs `users.delete:*` (SC-902). The `invite`
-  // call accepts `{ email, name, groupIds? }` and returns the resulting
-  // AppUserInvite row (the email is sent by the host). Mutating users from
+  // call accepts `{ email, name, group_ids?, send_invitation? }` and returns
+  // the resulting AppUserInvite row (the host sends the email, unless
+  // `send_invitation` is false). Mutating users from
   // a widget requires the corresponding SystemAcl capability grant in the
   // tenant (`users.write` for edits, `users.delete` for removal); widgets
   // that only call read methods need only `users.read:*`.
@@ -2379,8 +2380,13 @@ const HOOKS = [
       "scope; edit-style mutations (invite/deactivate/reactivate/" +
       "sendPasswordReset/update) need users.write:*, and the destructive remove() " +
       "additionally needs users.delete:* (SC-902). The `invite` call accepts " +
-      "{ email, name, group_ids? } and returns the resulting AppUserInvite row " +
-      "(the email is sent by the host). sendPasswordReset(userId) mails the " +
+      "{ email, name, group_ids?, send_invitation? } and returns the resulting " +
+      "AppUserInvite row { id, email, name, expires_at, sent_at, status }. " +
+      "The host emails the invitation at once unless send_invitation is " +
+      "false: then nothing is emailed, the row comes back with sent_at null " +
+      "and status 'not_sent', and useInvites().resend(inviteId) sends it " +
+      "later. A send_invitation that is not a boolean rejects with " +
+      "DirectoryError code VALIDATION. sendPasswordReset(userId) mails the " +
       "standard self-serve reset link to that user's own registered address " +
       "and resolves { sent, email_masked } — never the token or the link, so " +
       "it cannot be used to sign in as them. It rejects with a DirectoryError " +
@@ -2419,7 +2425,7 @@ const HOOKS = [
       error: "DirectoryError | null  // { code, reason, message, retryable }",
       refetch: "() => Promise<void>",
       invite:
-        "({ email, name, group_ids? }) => Promise<Invite>  // rejects with DirectoryError",
+        "({ email, name, group_ids?, send_invitation? }) => Promise<Invite>  // send_invitation: false stores it unsent (status 'not_sent'); rejects with DirectoryError",
       deactivate: "(userId) => Promise<User>  // rejects with DirectoryError",
       reactivate: "(userId) => Promise<User>  // rejects with DirectoryError",
       remove: "(userId) => Promise<void>  // rejects with DirectoryError",
@@ -2637,7 +2643,8 @@ const HOOKS = [
   // sc-5097 — pending AppUser invite administration. Returns
   // `{ invites, loading, error, refetch, resend, revoke }`. Reads need
   // `invites.read:*`; resend/revoke need `invites.write:*` plus the
-  // caller's `users.write` SystemAcl capability.
+  // caller's `users.write` SystemAcl capability. sc-9714: `resend` is also
+  // the first send of a `not_sent` invite — there is no separate `send`.
   {
     name: "useInvites",
     signature: "useInvites(query)",
@@ -2647,13 +2654,23 @@ const HOOKS = [
       "directory-client at ctx.directory.invites.{list,resend,revoke}. " +
       "Returns { invites, loading, error, refetch, resend, revoke }. list " +
       "returns the { data, meta } envelope verbatim — the hook unwraps " +
-      "res.data; rows are snake_case (email, status, expires_at, …) and " +
-      "status is the server-computed pending/accepted/revoked/expired " +
-      "value. query is { status?, q?, app_user_id?, limit?, offset? } passed " +
+      "res.data; rows are snake_case (email, status, sent_at, expires_at, …) " +
+      "and status is the server-computed pending/accepted/revoked/expired/" +
+      "not_sent value. not_sent is an invitation created with " +
+      "send_invitation: false that has not been emailed yet: its sent_at is " +
+      "null, it cannot be accepted until it is sent, and its expires_at " +
+      "means nothing yet, so show no expiry for it. resend(inviteId) is the " +
+      "ONE call that sends an invitation — the first send of a not_sent one " +
+      "and a repeat send of a sent one alike: it emails the invitee, stamps " +
+      "sent_at, restarts the 7-day expiry and resolves the row with status " +
+      "'pending'. There is no separate send method; label the button " +
+      "'Send invitation' on a not_sent row and 'Resend' on a pending one. " +
+      "query is { status?, q?, app_user_id?, limit?, offset? } passed " +
       "verbatim; the endpoint defaults to status 'all', so pass " +
-      "{ status: 'pending' } for the usual outstanding-invite list; " +
-      "status 'open' is every invite neither accepted nor revoked (pending " +
-      "or expired). q is a " +
+      "{ status: 'pending' } for the usual outstanding-invite list and " +
+      "{ status: 'not_sent' } for the prepared ones; " +
+      "status 'open' is every invite neither accepted nor revoked (pending, " +
+      "not_sent or expired). q is a " +
       "case-insensitive substring match on the invite's name or email. " +
       "Each row's app_user_id is the id the invitee's user account will " +
       "have once they accept; a USER column may already hold it, and " +
@@ -2670,12 +2687,12 @@ const HOOKS = [
       "refetch on success.",
     returnShape: {
       invites:
-        "Array<{ id, app_user_id, email, name, group_ids, status, expires_at, accepted_at, revoked_at, created_at }>  // snake_case rows; unwrapped from { data, meta }",
+        "Array<{ id, app_user_id, email, name, group_ids, status, sent_at, expires_at, accepted_at, revoked_at, created_at }>  // snake_case rows; status is pending | accepted | revoked | expired | not_sent; unwrapped from { data, meta }",
       loading: "boolean",
       error: "DirectoryError | null  // { code, message, retryable }",
       refetch: "() => Promise<void>",
       resend:
-        "(inviteId) => Promise<Invite>  // refetches; rejects with DirectoryError",
+        "(inviteId) => Promise<Invite>  // sends it (first send of a not_sent invite too); refetches; rejects with DirectoryError",
       revoke:
         "(inviteId) => Promise<void>  // refetches; rejects with DirectoryError",
     },
@@ -4169,7 +4186,7 @@ const WIDGET_CONTEXT_SHAPE = {
       "invites: { list(), revoke(id), resend(id) }, " +
       "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:*).",
+      "users backs useDirectory() + useUsers(); groups backs useGroups(); invites backs useInvites() (list/resend/revoke invites — resend also sends one created with send_invitation: false — 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", presence: "object" },
   },
@@ -6442,7 +6459,11 @@ const CONTRACT = deepFreeze({
   //    random id per row and may be `defaultLocked`.
   // 1.215.0: additive (sc-13938) — `usePdfExport` `openPdf` / `exportToPdf`
   //    take `appendFileIds`: stored PDFs whose pages follow the rendered HTML.
-  version: "1.215.0",
+  // 1.216.0: additive (sc-14096) — reinstates 1.144.0, withdrawn in 1.155.0:
+  //    `useUsers().invite` takes `send_invitation` (false stores the invite
+  //    unsent), invite rows carry `sent_at`, `not_sent` is a status, and
+  //    `useInvites().resend` performs the first send.
+  version: "1.216.0",
   sharedTranslationKeys: SHARED_TRANSLATION_KEYS,
   hooks: HOOKS,
   primitives: PRIMITIVES,