@lessly/sdk-app 63.0.0 → 63.2.0

package/docs/recipes/access.md

@@ -234,6 +234,32 @@ method cannot drift the day an operation is re-levelled. The accessor path is a
 lossy view of the key, so never rebuild `operationKey` from it either — read it
 off the method.
 
+### Reading a level without a method
+
+Sometimes there is no method to read `op.level` from: an App test double that has
+to answer `can()` for a key, a runtime probe over keys it was handed. The answer
+is still not a literal and still not a table in the App — `@lessly/sdk-app`
+exports the catalog's own level map:
+
+```ts
+import { operations, accessReason } from '@lessly/sdk-app';
+
+operations['mail_domain_create'];   // 'admin'
+operations['analytics_insight_delete'];  // 'write'
+```
+
+`operations` is `Readonly<Record<string, ToolLevel>>`, keyed by operation key. It
+is regenerated at publish time from the live catalog, so it re-levels with the
+platform exactly as the generated methods do — which is the whole reason it may
+be read where a hand-written table may not (APP-012).
+
+A key the map does not carry answers `undefined`, and that is the case
+`accessReason`'s string form already covers: pass the bare key and get
+*"Requires access to `<key>`. Ask an admin of this product."* — no level invented,
+no `level:undefined` in front of a user. Where you do hold a method, keep reading
+`op.level` off it: the map is for the keys no method covers, not a second way to
+do what the method already does.
+
 ### Your App mounts its own `TooltipProvider`
 
 Mount **one `TooltipProvider` per App canvas** — at the root of your remote, as in
@@ -358,6 +384,17 @@ it is not a judgement call you make silently — write it into your App's spec a
 named exception with the reason. An ungated write that nobody wrote down is
 indistinguishable from one nobody thought about.
 
+### One reason for a surface-wide gate
+
+Where a gate disables a *capability across a whole surface* — dragging any node on
+a canvas, a bulk action over a list or a grid — the reason goes on the control
+that **owns** the capability: the toggle, the toolbar button, the surface header.
+Not on every affected element. Thirty identical focusable wrappers are thirty
+extra tab stops and one sentence repeated thirty times; that is noise, not thirty
+explanations. Keyboard reachability (below) is satisfied on the owning control,
+and the elements themselves just go inert — `draggable={false}`, `readOnly`,
+`disabled` — with no wrapper of their own.
+
 ### Buttons that touch more than one operation
 
 Two shapes, and they gate differently. Get this wrong and you either grey out a
@@ -405,6 +442,22 @@ const reason = denied
 Both shapes hand the method to `accessReason`, so neither needs to know which
 operation it ended up gating on.
 
+### Controls that stage a change
+
+A control that **stages** a change — it writes nothing itself; the write is sent
+later, by a Save or an Apply — is gated on the operation that staged change will
+eventually send. Two failure modes, and both are common:
+
+- **Gated on nothing.** A Viewer rearranges, fills in and stages happily, and
+  meets the refusal at Save — somewhere else on the screen, after the work.
+- **Gated twice in a row.** If the entry point that reaches the staging control
+  is already gated on that same operation, the staging control does not repeat
+  the gate: the reader has met the sentence once and cannot get here without
+  passing it.
+
+So: gate the staging control on the staged operation *unless* the upstream
+control is already gated on the same one.
+
 ### Forms with a deferred save
 
 A form the reader fills in and *then* saves is the one case where a hint per

package/docs/rules.md

@@ -382,6 +382,14 @@ The level MUST come from the generated method itself (`op.level`, on the
 the App, not a literal, and never a rule of thumb about verbs — `analytics_*_delete`
 is `write` while `mail_domain_create` is `admin`, and only the catalog knows.
 
+Where there is no method to read from — a test double, a runtime probe over keys
+it was handed — the App MUST NOT hand-type the level either. `@lessly/sdk-app`
+exports `operations`, the catalog's own level map
+(`Readonly<Record<string, ToolLevel>>`, keyed by operation key), regenerated at
+publish time from the live catalog; read the level from it. A key it does not
+carry answers `undefined`, which is exactly the case `accessReason`'s string form
+covers — no level is invented for it.
+
 The gate belongs to the OPERATION, not to a gesture: where a write is reachable
 by several paths (drag and arrow keys, click and Enter, button and hotkey) all of
 them MUST be gated together, or the hole left behind is one only keyboard users
@@ -389,6 +397,20 @@ find. Implicit form submission is such a path: a disabled submit button does not
 reliably stop Enter inside a field, so the `onSubmit` handler MUST be gated (or
 the fields made `readOnly`) rather than the button alone.
 
+A gate that disables a capability across a WHOLE SURFACE — dragging any node on
+a canvas, a bulk action over a list or a grid — MUST attach the reason to the
+control that owns the capability (the toggle, the toolbar, the surface header)
+and MUST NOT attach it to every affected element: thirty identical focusable
+wrappers are thirty extra tab stops and one sentence thirty times, not thirty
+explanations. Keyboard reachability is satisfied on the owning control; the
+elements themselves just go inert.
+
+A control that STAGES a change — it writes nothing itself, the write is sent
+later by a Save or an Apply — MUST be gated on the operation the staged change
+will send, UNLESS the upstream control that reaches it is already gated on that
+same operation. Never on nothing (the caller does the work and meets the refusal
+later, somewhere else) and never twice in a row.
+
 A control that performs SEVERAL operations per click is disabled if ANY of them
 is denied. A DISPATCHER control — one operation per click, selected by a mode or
 a switch — MUST instead be gated on the operation it is about to call, and name

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lessly/sdk-app",
-  "version": "63.0.0",
+  "version": "63.2.0",
   "type": "module",
   "sideEffects": false,
   "engines": {