@colixsystems/widget-sdk 0.182.0 → 0.183.0

package/README.md

@@ -59,7 +59,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 }` | `directory.users.*` — `users.read:*` plus the `users.read` (or `users.write`) capability, else `FORBIDDEN` (edits, incl. `sendPasswordReset()`, 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). |
@@ -74,7 +74,28 @@ See the design reference for the full architecture: [`docs/architecture/widget-m
 
 ## Status
 
-`v0.182.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.183.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.183.0 (contract 1.144.0)
+
+**A widget can prepare an invitation now and send it later.** `useUsers().invite()` always emailed the invitation the moment it was 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.182.0 (contract 1.143.0)
 
@@ -1392,7 +1413,7 @@ Additive — one new hook, one new optional device capability, one new error cla
 
 **New linter rule `measured-width-ignores-padding` — a measured width includes the measuring element's own padding (sc-4913).**
 
-- **`measured-width-ignores-padding` (severity `warning`, non-blocking).** A widget that puts `onLayout` on an element which sets its own `padding` (or `paddingHorizontal`/`Left`/`Right`), and then sizes grid cells from the measured number, is flagged. `onLayout` reports the element's **frame** width and padding sits inside that frame, so the space the children really get is `width - paddingLeft - paddingRight`. Cells sized to fill the raw measurement overflow the content box, the last one wraps, and the widget ships a whole empty column of whitespace beside its cards — on both the web Player and the native Expo export, with nothing in the console. Author fix: spread `onLayout` on an **unpadded** element (keep the padding on a parent, or measure an inner `<View>` inside the padded root) so the number you hold is the usable width. Better still for content-sized cells: skip the measurement entirely and wrap with flex — a `{ flexDirection: "row", flexWrap: "wrap", gap }` row whose cards take `{ flexGrow: 1, flexBasis: CARD_MIN }` splits the row's real content width itself and can never leave a leftover band.
+- **`measured-width-ignores-padding` (severity `warning`, non-blocking).** A widget that puts `onLayout` on an element which sets its own `padding` (or `paddingHorizontal`/`Left`/`Right`), and then sizes grid cells from the measured number, is flagged. `onLayout` reports the element's **frame** width and padding sits inside that frame, so the space the children really get is `width - paddingLeft - paddingRight`. Cells sized to fill the raw measurement overflow the content box, the last one wraps, and the widget ships a whole empty column of whitespace beside its cards — on both the web Player and the native Expo export, with nothing in the console. Author fix: spread `onLayout` on an **unpadded** element (keep the padding on a parent, or measure an inner `<View>` inside the padded root) so the number you hold is the usable width. For content-sized cards, that unpadded measurement is also how a grid counts its cards per line (see the card-grid rule under **Size to your container**).
 - **Why a warning.** The rule fires only when the measured value feeds sizing arithmetic — a padded box measured just to pick a wide/narrow form (`isNarrowWidth(width)`) is off by one padding pair and stays silent. A widget that already subtracts its own padding by hand matches too, because no text scan can verify the subtraction; that is deliberate — the remediation is correct for it as well and retires the arithmetic. Comments are not scanned, so documenting the anti-pattern is safe.
 
 `CONTRACT` is unchanged (no new field), and no export changed signature.
@@ -2044,7 +2065,7 @@ A widget that works but looks unfinished is only half done. `useTheme()` is the
 - **Tint the supporting cast.** `colors.primarySoft` is a tint of the workspace accent over the surface and `colors.onPrimarySoft` is guaranteed readable on it (WCAG AA, on light and dark themes alike). Use the pair for chips, secondary buttons, progress tracks, icon badges and selected rows. One saturated accent moment surrounded by several pale echoes of the same hue is what reads as designed — a row of grey-outlined buttons reads as a form. Never hand-mix a tint with `rgba(...)` or a translucent overlay.
 - **Spend one gradient.** `<Gradient colors={[theme.colors.primary, theme.colors.primaryStrong]} angle={160} style={…}>` is a `View` that paints a gradient behind its children, so it replaces the `View` you'd otherwise give a flat `backgroundColor`. `angle` is CSS degrees (0 = to top, 90 = to right, default 180); text on it uses `colors.onPrimary`. Exactly **one** per widget — on the focal element — and never behind body text. Both hosts render it identically (web paints CSS, native uses `expo-linear-gradient`), so there is no per-platform branching to write; don't import `expo-linear-gradient` yourself and don't write a `backgroundImage` string.
 - **Answer the touch.** Every tappable card, row and list entry lifts while the pointer is over it (web) or it is pressed (touch). One declaration does both: give the Pressable a style FUNCTION and spread `pressableLift` — `<Pressable onPress={open} style={(state) => [styles.card, ...pressableLift(state)]}>`. The lift is a -2px nudge plus one elevation step from `theme.interaction`, with the web transition built in. Never hand-write hover logic or your own pressed shadows, and never fake feedback with `opacity` — a dimmed surface reads as disabling itself.
-- **Size to your container — measure it, don't stretch into it.** The same widget sits in a full-width desktop section (~1400px), a half-width grid cell (~700px) and a phone (~360px), so layout built only from `flex: 1` stretches to fill whatever it is handed — a month calendar ends up with 200px day cells and swallows the page. Measure your own width with `const [width, onLayout] = useContainerWidth();`, spreading `onLayout` on an unpadded root `View` (a React Native callback, so it behaves identically on both hosts). A width of `0` means "not yet measured" and the SDK helpers answer it with the wide form, so do not special-case it — except a cell whose definite size is computed from the width (a calendar day, a chart), which renders nothing size-dependent until the width arrives: a widget gets no declared breakpoint prop, but it can always measure. **Every form, list, table and filter bar lays out in three tiers** (sc-8508): `const [width, onLayout] = useContainerWidth();` then branch on `widthTier(width)` — a form is one column narrow, paired short fields at medium, a 2–3 column grid capped near 1000px wide; a list is stacked cards, one-line cards, then real columns under a header; a filter bar is one toolbar row (search, a dropdown per facet, sort) with the active filters as removable chips beneath, and a single "Filters" button opening a panel when narrow. **Cap a repeating cell** rather than giving a grid `flex: 1` — `const cell = Math.max(32, Math.min(Math.floor((usable - gap * (columns - 1)) / columns), 64));`, with a calendar day cell topping out at 56–72px on `aspectRatio: 1`, and the grid given its exact computed width plus `alignSelf: 'center'` when the cap leaves slack. **Split two co-equal surfaces in the wide tier** (`flexDirection: widthTier(width) === 'wide' ? 'row' : 'column'`, each half `{ flex: 1, minWidth: 0 }`) — a picker beside the form it feeds on a wide canvas, stacked in reading order below it. Never hardcode a width, never put `flex: 1` / `height: '100%'` on a content widget's root, and don't read the screen with `Dimensions` — the screen is not the widget. **Whatever you narrow, you centre** — a block that caps its own measure carries all three of `{ width: '100%', maxWidth: FORM_MAX, alignSelf: 'center' }`, because `alignSelf` alone stops the block stretching and sizes it to its content instead, and `maxWidth` alone leaves the widget flush left with dead space beside it; a capped wrap row lays its cells out along the MAIN axis, so it centres with `justifyContent: 'center'` on the row instead. **A metric / stat-tile row FILLS ITS ROW** — when you know the count, balance the lines (`const lines = Math.ceil(count / max); const base = Math.floor(count / lines); const extra = count % lines; const rows = Array.from({ length: lines }, (_, i) => tiles.slice(i * base + Math.min(i, extra), (i + 1) * base + Math.min(i + 1, extra)));`, with `max` 4 / 3 / 2 by tier, each tile `{ flex: 1, minWidth: 0 }`), and when the count comes from data wrap it (`{ flexDirection: 'row', flexWrap: 'wrap', gap: theme.spacing.md }`, each tile `{ flexGrow: 1, flexBasis: TILE_MIN }`, never a `maxWidth` — capped tiles cluster to one side), because a bare `flexDirection: 'row'` has no way to break and a React Native flex child defaults to `flexShrink: 0` (unlike CSS), so the tiles cannot give ground either: the row runs past its container, spilling out of the card natively and cut off by the scrolling page column on web, with nothing thrown and nothing logged, once there are enough of them (four fit where five do not). The basis is also the per-line ceiling — `Math.floor((usable + gap) / (TILE_MIN + gap))` tiles fit a line, so 240 tops out at five across a full-width ~1400px section and 320 at four; past four or five a line the tiles stop reading as cards.
+- **Size to your container — measure it, don't stretch into it.** The same widget sits in a full-width desktop section (~1400px), a half-width grid cell (~700px) and a phone (~360px), so layout built only from `flex: 1` stretches to fill whatever it is handed — a month calendar ends up with 200px day cells and swallows the page. Measure your own width with `const [width, onLayout] = useContainerWidth();`, spreading `onLayout` on an unpadded root `View` (a React Native callback, so it behaves identically on both hosts). A width of `0` means "not yet measured" and the SDK helpers answer it with the wide form, so do not special-case it — except a count or size computed from the width (a calendar day, a chart, a card grid's cards per line), which renders nothing size-dependent until the width arrives: a widget gets no declared breakpoint prop, but it can always measure. **Every form, list, table and filter bar lays out in three tiers** (sc-8508): `const [width, onLayout] = useContainerWidth();` then branch on `widthTier(width)` — a form is one column narrow, paired short fields at medium, a 2–3 column grid capped near 1000px wide; a list is stacked cards, one-line cards, then real columns under a header; a filter bar is one toolbar row (search, a dropdown per facet, sort) with the active filters as removable chips beneath, and a single "Filters" button opening a panel when narrow. **Cap a repeating cell** rather than giving a grid `flex: 1` — `const cell = Math.max(32, Math.min(Math.floor((usable - gap * (columns - 1)) / columns), 64));`, with a calendar day cell topping out at 56–72px on `aspectRatio: 1`, and the grid given its exact computed width plus `alignSelf: 'center'` when the cap leaves slack. **Split two co-equal surfaces in the wide tier** (`flexDirection: widthTier(width) === 'wide' ? 'row' : 'column'`, each half `{ flex: 1, minWidth: 0 }`) — a picker beside the form it feeds on a wide canvas, stacked in reading order below it. Never hardcode a width, never put `flex: 1` / `height: '100%'` on a content widget's root, and don't read the screen with `Dimensions` — the screen is not the widget. **Whatever you narrow, you centre** — a block that caps its own measure carries all three of `{ width: '100%', maxWidth: FORM_MAX, alignSelf: 'center' }`, because `alignSelf` alone stops the block stretching and sizes it to its content instead, and `maxWidth` alone leaves the widget flush left with dead space beside it; a capped wrap row lays its cells out along the MAIN axis, so it centres with `justifyContent: 'center'` on the row instead — but a card grid or a tile row is never capped. **A card grid fills its lines, it never wraps freely** — a free `flexWrap` strands the remainder (six cards that fit five render 5 + 1). Count the cards that fit the measured width (`const max = Math.max(1, Math.floor((width + gap) / (CARD_MIN + gap)));`), take `const lines = Math.ceil(count / max); const cols = Math.ceil(count / lines);`, and render each slice of `cols` cards as a row of `{ flex: 1, minWidth: 0 }` cells, padding the last line with empty `{ flex: 1 }` spacers so its cards keep the width of the cards above (six that fit five are 3 + 3, ten that fit four are 4 + 4 + 2). **A short value never breaks across lines** — a time, date, price, count, percentage or code takes `numberOfLines={1}` and `flexShrink: 0`, never a fixed width narrower than it, and a narrow slot re-arranges or steps the font down instead. **A metric / stat-tile row FILLS ITS ROW** — when you know the count, balance the lines (`const lines = Math.ceil(count / max); const base = Math.floor(count / lines); const extra = count % lines; const rows = Array.from({ length: lines }, (_, i) => tiles.slice(i * base + Math.min(i, extra), (i + 1) * base + Math.min(i + 1, extra)));`, with `max` 4 / 3 / 2 by tier, each tile `{ flex: 1, minWidth: 0 }`), and when the count comes from data wrap it (`{ flexDirection: 'row', flexWrap: 'wrap', gap: theme.spacing.md }`, each tile `{ flexGrow: 1, flexBasis: TILE_MIN }`, never a `maxWidth` — capped tiles cluster to one side), because a bare `flexDirection: 'row'` has no way to break and a React Native flex child defaults to `flexShrink: 0` (unlike CSS), so the tiles cannot give ground either: the row runs past its container, spilling out of the card natively and cut off by the scrolling page column on web, with nothing thrown and nothing logged, once there are enough of them (four fit where five do not). The basis is also the per-line ceiling — `Math.floor((usable + gap) / (TILE_MIN + gap))` tiles fit a line, so 240 tops out at five across a full-width ~1400px section and 320 at four; past four or five a line the tiles stop reading as cards.
 - **Compose forms — pair fields into rows, don't stack one per row.** Lay the form out in three tiers and cap it near 1000px, centred with the three declarations above — never a 560–720px column alone in a wide box, which leaves a form that IS the page as a narrow strip in empty space. Put short, related fields side by side (first + last name, city + postal code, expiry + CVC): a row of `{ flexDirection: 'row', flexWrap: 'wrap', gap: theme.spacing.md }` with each field cell `{ flexGrow: 1, flexBasis: 160 }` splits the width on a wide card and wraps to stacked on a narrow phone — the right recipe for field pairs because it needs no measurement (a fixed-width column overflows a phone; when a layout needs a real column count instead of wrapping, measure your width as above). Keep wide fields (email, address, notes) full-width with `width: '100%'` — NEVER `flexBasis: '100%'`, which sizes the main axis and therefore claims the parent's whole HEIGHT in a column (sc-7274) — cap it at two–three per row, group a long form into labelled sections, and label every input above it (not placeholder-only). Give a `multiline` field BOTH a floor and a ceiling (`{ minHeight: 150, maxHeight: 260 }`) so a long value scrolls inside the box instead of growing past its card, and keep the Save / Cancel row in normal flow below the fields, never positioned over them. When a field carries an icon beside it (a search glyph, a clear button), the border belongs on the WRAPPER row and the `TextInput` inside it goes borderless and transparent with `flex: 1, minWidth: 0` (the `minWidth: 0` stops a long value pushing the border past its container) — React Native has no `:focus-within`, so drive the wrapper's `borderColor` between `colors.border` and `colors.primary` from the input's own `onFocus` / `onBlur`. A border left on the input rings only its own `<input>` box on web, leaving the icon outside the ring; never absolutely-position the icon over the field to work around it.
 - **Respond to touch.** Give every `Pressable` the lift via the function-style `style={(state) => [base, ...pressableLift(state)]}` — see "Answer the touch" above. Never dim with `opacity`, which reads as the surface disabling itself.
 - **Drag and drop — show what is being dragged.** A drag where the item stays put reads as broken. Three things change the moment a drag starts: the **drag proxy** (the item lifts and follows the finger — `...theme.elevation.lg`, `{ scale: 1.03 }`, `opacity: 0.9`; for a tall or full-width item drag a compact `primarySoft` pill with its icon + one line of label instead), the **source placeholder** (the vacated slot keeps its height as a quiet `colors.surfaceMuted` block so the list doesn't collapse), and the **drop target** (one slot at a time highlighted with `primarySoft` or a 2px `colors.primary` border). Always animate the release — settle into the new slot, or `Animated.spring(pan, { toValue: { x: 0, y: 0 }, useNativeDriver: false })` back to the origin on cancel. Build it with `Animated` + `PanResponder` from `react-native` (the only mechanism that behaves identically on both hosts) — never HTML5 drag events (`draggable` / `onDragStart` / `dataTransfer` are web-only, and `document` / `window` are banned) — and start the drag from a `GripVertical` grip handle whenever the row is also tappable or sits in a `ScrollView`. **A board (kanban, pipeline) drops onto ANOTHER column**, which needs four more things: the board's root renders the one proxy (a column clips whatever leaves it); you hit-test the drop yourself — `measureInWindow` every column and the board when the drag starts and compare the gesture's window `moveX` (never `onLayout` frames, which are relative to a padded or scrolled parent) — highlighting exactly one target; the drop WRITES (`update(id, { [statusField]: value })` through `useDatastoreMutation`, optimistic until `refetch()`, a toast and a spring-back on failure); and three or more columns go in a `horizontal` `ScrollView` when `widthTier(width) === "narrow"`, with the grip claiming the gesture (`onStartShouldSetPanResponder`, `onPanResponderTerminationRequest: () => false`) and carrying `touchAction: 'none'` on web so a finger drag moves the card instead of scrolling the page. And because `useRef(PanResponder.create(...))` runs ONCE, everything its callbacks read — the `useCanWrite` flag included, which starts `false` — goes through a ref refreshed every render (`latest.current.canDrag`); the publish gate `widget.staleResponder` rejects a value read directly.
@@ -2101,11 +2122,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';
@@ -2120,7 +2143,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>
       ))}
@@ -2129,9 +2154,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
@@ -2139,7 +2171,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

@@ -1697,8 +1697,9 @@ const HOOKS = [
   // deactivate / reactivate / sendPasswordReset) 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:*`.
@@ -1716,8 +1717,13 @@ const HOOKS = [
       "scope; edit-style mutations (invite/deactivate/reactivate/" +
       "sendPasswordReset) 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 " +
@@ -1730,7 +1736,7 @@ const HOOKS = [
       error: "DirectoryError | null  // { code, 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",
@@ -1775,7 +1781,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)",
@@ -1785,13 +1792,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 " +
@@ -1808,12 +1825,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",
     },
@@ -2855,7 +2872,7 @@ const WIDGET_CONTEXT_SHAPE = {
       "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:*).",
+      "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). 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" },
   },
@@ -4782,7 +4799,11 @@ const CONTRACT = deepFreeze({
   //    accept.
   // 1.143.0: additive (sc-9756) — a datastoreTemplate RELATION column may
   //    declare `onDelete` ("CASCADE" | "SET_NULL") for ONE_TO_ONE/ONE_TO_MANY.
-  version: "1.143.0",
+  // 1.144.0: additive (sc-9714) — `useUsers().invite` takes an optional
+  //    `send_invitation`; `false` stores the invite unsent. Invite rows gain
+  //    `sent_at` and the `not_sent` status, and `useInvites().resend` is its
+  //    first send. Omitting the flag emails at once, as before.
+  version: "1.144.0",
   sharedTranslationKeys: SHARED_TRANSLATION_KEYS,
   hooks: HOOKS,
   primitives: PRIMITIVES,

package/dist/contract.js

@@ -1697,8 +1697,9 @@ const HOOKS = [
   // deactivate / reactivate / sendPasswordReset) 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:*`.
@@ -1716,8 +1717,13 @@ const HOOKS = [
       "scope; edit-style mutations (invite/deactivate/reactivate/" +
       "sendPasswordReset) 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 " +
@@ -1730,7 +1736,7 @@ const HOOKS = [
       error: "DirectoryError | null  // { code, 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",
@@ -1775,7 +1781,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)",
@@ -1785,13 +1792,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 " +
@@ -1808,12 +1825,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",
     },
@@ -2851,7 +2868,7 @@ const WIDGET_CONTEXT_SHAPE = {
       "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:*).",
+      "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). 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" },
   },
@@ -4778,7 +4795,11 @@ const CONTRACT = deepFreeze({
   //    accept.
   // 1.143.0: additive (sc-9756) — a datastoreTemplate RELATION column may
   //    declare `onDelete` ("CASCADE" | "SET_NULL") for ONE_TO_ONE/ONE_TO_MANY.
-  version: "1.143.0",
+  // 1.144.0: additive (sc-9714) — `useUsers().invite` takes an optional
+  //    `send_invitation`; `false` stores the invite unsent. Invite rows gain
+  //    `sent_at` and the `not_sent` status, and `useInvites().resend` is its
+  //    first send. Omitting the flag emails at once, as before.
+  version: "1.144.0",
   sharedTranslationKeys: SHARED_TRANSLATION_KEYS,
   hooks: HOOKS,
   primitives: PRIMITIVES,

package/dist/hooks.js

@@ -5137,7 +5137,7 @@ export function useDirectory(query) {
  * invite, deactivate, reactivate}` — `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
@@ -5374,15 +5374,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
@@ -5449,7 +5454,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

@@ -2181,13 +2181,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;
@@ -2202,7 +2214,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;
@@ -2271,8 +2285,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. */
@@ -2293,7 +2308,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/package.json

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