Skip to content

Commit 227a4be

Browse files
committed
docs(skills): the objectstack-ui actions rule teaches pressed, the reader's own toggle state
A record header action can declare `pressed`, a CEL predicate over the same scope as `visible` that the header draws as `aria-pressed` while it holds. The rule says it is display only, that a boolean literal is refused, which spellings rename onto it, and how a per-reader fact reaches it through an `attachedOnRead` block. The addition is paid for inside the file: the bare-CEL paragraph folds into the `visible` bullet, the `ctx` section drops the blessed-name code block that restates the objectstack-data hooks reference, and the new-tab and param-pattern prose is condensed. Co-Authored-By: Claude <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01L9qibz4G9FrLR4TRExx6gn
1 parent 82b29fe commit 227a4be

1 file changed

Lines changed: 29 additions & 56 deletions

File tree

‎skills/objectstack-ui/rules/actions.md‎

Lines changed: 29 additions & 56 deletions
Original file line numberDiff line numberDiff line change
@@ -15,19 +15,15 @@
1515

1616
## Visibility, Disable & Feedback
1717

18-
- `visible` — CEL predicate (prefer the `P\`...\`` tagged template); when false the action is **hidden**.
18+
- `visible` — a bare CEL predicate over the current record (prefer the `P\`...\`` template; `record.<field>` resolves identically on every surface, never `${…}`- or `{…}`-wrapped — see `objectstack-formula`); when false the action is **hidden**.
1919
- `disabled` — `boolean` **or** a CEL predicate; when true the action **shows but greys out**. Use this (not `visible`) when the action should stay discoverable but locked in the current state.
20-
- `disabledReason` — an I18nLabel (a plain sentence or an inline locale map) a greyed action shows as its hover title and accessible description. Display-only: never a predicate and never a gate (the hook or permission still refuses). Omit it to keep the console's default "Not available for this record"; a blank one is refused, and `disabledMessage` / `disabledTooltip` / `disabledHint` / `disabledText` are refused naming this key. The reason goes here, not in `description`.
20+
- `disabledReason` — an I18nLabel (a sentence or an inline locale map) a greyed action shows as its hover title and accessible description. Display-only: never a predicate and never a gate (the hook or permission still refuses). Omit it to keep the console's default "Not available for this record"; a blank one is refused, and `disabledMessage` / `disabledTooltip` / `disabledHint` / `disabledText` are refused naming this key. The reason goes here, not in `description`.
21+
- `pressed` — a CEL predicate over the same scope as `visible` that marks the action as already done by this reader: while TRUE the record header draws it pressed (`aria-pressed`). Display-only, never a gate; a boolean literal is refused (a constant is a style, not a reader's state), and `active` / `activeWhen` / `pressedWhen` are refused naming this key. A per-reader fact (the reader's vote) is a block the object declares under `attachedOnRead`, filled per caller by a service or `afterFind` hook, read as `has(record.viewer) && record.viewer.vote == 'helpful'`.
2122
- `confirmText` — set for any destructive or irreversible operation.
22-
- `successMessage` / `errorMessage` — toast copy on success / failure. Always set `successMessage` for non-obvious outcomes; without it the UI shows a generic "Action completed" toast.
23+
- `successMessage` / `errorMessage` — toast copy on success / failure. Set `successMessage` for non-obvious outcomes; without it the UI shows a generic "Action completed" toast.
2324
- Copy holes are `{{ }}`: `confirmText` reads `record`, `successMessage` `record` and `result` (the handler's answer); `errorMessage` takes none. A `bulkActionDefs` entry's `confirmText` reads `{{ count }}` and its params by bare name (`{{ tier }}`). `${record.name}`, `{name}`, logic in a hole and a blank sentence fail `os validate`.
2425
- `undoable: true` — an **Undo** in the success toast (and `Ctrl+Z`). Snapshot: runtime on `operation: 'update'`, console on `type: 'api'`; else refused.
2526

26-
Predicates are **bare CEL** — `record.status == "converted"`, evaluated against
27-
the current record. `record.<field>` resolves identically on every surface
28-
(`record_header`, `list_item`, …); prefer it over the bare-field form. Never
29-
wrap a predicate in `${…}` or `{…}` braces (see `objectstack-formula`).
30-
3127
<!-- os:check -->
3228
```typescript
3329
import { defineAction } from '@objectstack/spec/ui';
@@ -112,40 +108,22 @@ export const AddToCampaignAction = defineAction({
112108

113109
### Action body context (`ctx`)
114110

115-
A server-side action `body` (and a registered function `handler`) receives a
116-
`ctx` with `input` (the modal params), `record` (the target row, when a
117-
`recordId` is in scope), `api` (scoped cross-object CRUD), and the caller
118-
identity. Read the caller's active organization under the **blessed**
119-
`organizationId` name — the same value as the `organization_id` column and
120-
`current_user.organizationId` in RLS:
121-
122-
```typescript
123-
// ✅ Blessed — identical to the hook surface (ctx.user / ctx.session)
124-
const org = ctx.user?.organizationId ?? ctx.session?.organizationId;
125-
```
126-
127-
Action bodies execute **trusted** (the `ctx.engine` / `ctx.api` facade bypasses
128-
RLS/FLS), so a body that must scope by org reads it from `ctx` explicitly.
129-
`ctx.user` is `undefined` for a context-less / self-invoked call. Same two
130-
isolation axes, same blessed name, same `undefined` cases as hooks — see the
131-
objectstack-data hooks reference.
132-
133-
The caller's position names are on `ctx.session.positions` (absent, not empty,
134-
when the caller holds none). **This array is not an authorization input**:
135-
`positions.includes('admin')` is a defect under a blessed name — ask the
136-
security service for privilege (ADR-0095).
111+
A server-side `body` (or a registered `handler`) receives `ctx` with `input` (the dialog params), `record` (the target row, when a
112+
`recordId` is in scope), `api` (scoped cross-object CRUD) and the caller. Read
113+
the active organization as `ctx.user?.organizationId ?? ctx.session?.organizationId`
114+
— the blessed name, with the same isolation axes and `undefined` cases as hooks
115+
(objectstack-data hooks reference). Bodies execute **trusted** (`ctx.api` /
116+
`ctx.engine` bypass RLS/FLS), so a body that must scope by org reads it from
117+
`ctx` explicitly. `ctx.session.positions` (absent when the caller holds none) is
118+
**not an authorization input** — ask the security service for privilege (ADR-0095).
137119

138120
## Opening in a New Tab (`openIn` / `opensInNewTab` / `newTabUrl`)
139121

140-
There are **two** mechanisms here. Pick by whether the URL is static or computed:
141-
142122
### `openIn: 'new-tab'` — simplest case (static `target`)
143123

144-
When you have a **static** `target` URL (relative or absolute) you just want
145-
opened in a new tab, set `openIn: 'new-tab'` on a `type: 'url'` action. No
146-
handler, no synchronous pre-open. `openIn: 'self'` forces in-place navigation;
147-
omit it and external/absolute URLs open in a new tab while relative URLs
148-
navigate in place.
124+
A **static** `target` URL on a `type: 'url'` action: `openIn: 'new-tab'` opens
125+
it in a new tab, `'self'` forces in-place navigation; omitted, absolute URLs open
126+
in a new tab and relative ones navigate in place.
149127

150128
<!-- os:check -->
151129
```typescript
@@ -163,14 +141,12 @@ export const PrintA3Action = defineAction({
163141

164142
### `opensInNewTab` + `newTabUrl` — async / computed redirect (SSO)
165143

166-
For actions whose redirect URL is **computed after a fetch** (SSO and SSO-like
167-
handlers), set `opensInNewTab: true`. The renderer pre-opens the tab
168-
**synchronously** on click so popup blockers don't fire, then navigates it to
169-
the handler's returned `redirectUrl`. To skip the round-trip, add `newTabUrl`
170-
— a backend path starting with `/` (`{recordId}` placeholder; an external URL
171-
is refused, use `openIn` above). Valid **only** with `opensInNewTab: true`; the
172-
endpoint must enforce its own auth (the new tab carries no in-app session
173-
context).
144+
A redirect URL **computed after a fetch** (SSO-like handlers): `opensInNewTab:
145+
true` pre-opens the tab synchronously on click (no popup blocker), then navigates
146+
it to the handler's `redirectUrl`. `newTabUrl` skips the round-trip — a backend
147+
path starting with `/` (`{recordId}` placeholder; an external URL is refused, use
148+
`openIn`), valid only with `opensInNewTab: true`; the endpoint enforces its own
149+
auth (the tab carries no in-app session).
174150

175151
```typescript
176152
export const OpenInvoicePdfAction = defineAction({
@@ -187,18 +163,15 @@ export const OpenInvoicePdfAction = defineAction({
187163

188164
> A printable document (an invoice) is a page that declares `print` — [Print pages](./pages.md#print-pages).
189165
190-
> ⚠️ **Never express new-tab behavior via `params`.** `params` is exclusively
191-
> `ActionParam[]` for collecting **user input**. Writing an object form like
192-
> `params: { newTab: true }` fails the zod build outright; the array form
193-
> `params: [{ name: 'newTab', type: 'checkbox' }]` *builds* but mis-renders as a
194-
> user-facing checkbox in the param-collection dialog. Use one of the two mechanisms above.
166+
> ⚠️ **Never express new-tab behavior via `params`** — it is `ActionParam[]` for
167+
> **user input** only: `params: [{ name: 'newTab', type: 'checkbox' }]` builds and
168+
> draws a checkbox in the dialog. Use one of the two mechanisms above.
195169
196170
## Action Parameter Patterns
197171

198-
Prefer **field-backed** params (`{ field: 'email' }`) over inline declarations
199-
— the runtime resolves label (i18n), type, validation, options, placeholder,
200-
and widget mapping from object metadata. Use `objectOverride` to reference a
201-
field from a different object. Set `defaultFromRow: true` to pre-fill from
202-
the selected row in `list_item` contexts.
172+
Prefer **field-backed** params (`{ field: 'email' }`): label (i18n), type,
173+
validation, options, placeholder and widget come from the object metadata;
174+
`objectOverride` borrows a field of another object, and `defaultFromRow: true`
175+
pre-fills from the selected row in `list_item` contexts.
203176

204-
> **Best practice:** set `refreshAfter: true` whenever the action mutates the current record.
177+
> Set `refreshAfter: true` whenever the action mutates the current record.

0 commit comments

Comments
 (0)