@lessly/sdk-app 61.2.0 → 62.1.0

package/docs/rules.md

@@ -338,6 +338,91 @@ An App SHOULD reflect the caller's access in its UI: **disable, with a reason**
 (not hide) a primary action the caller cannot perform, using `useCan` from
 `@lessly/sdk-app/react` or `app.access.can()` directly, and render a 403 that
 `isAccessDenied()` recognises as a **neutral empty state** rather than an error.
+That reason MUST live on a `Tooltip` wrapper around the disabled control, never
+on a native `title=` of the control itself: the base `buttonVariants` carry
+`disabled:pointer-events-none`, so a disabled control fires no hover for the
+browser to render a `title` from, and a native tooltip is unreachable by
+keyboard and by touch in any case. An App that draws such a tooltip MUST mount
+its own `TooltipProvider` once at the root of its remote — `Tooltip.Root` throws
+without one, and the standalone build, the dev entry and the tests all render
+outside the shell.
+
+That reason MUST be exactly one sentence, the same in every App:
+
+> `Requires level:<op.level> (<op.operationKey>). Ask an admin of this product.`
+
+— e.g. `Requires level:admin (mail_domain_create). Ask an admin of this product.`
+Both values MUST be read from the generated method, never written as literals.
+`@lessly/sdk-app` exports `accessReason(op)`, which is that sentence; an App
+SHOULD use it rather than assembling the text itself.
+
+Where a control has only an operation key and no generated method to point at,
+the App MUST NOT guess the level or render `level:undefined`; it says instead:
+
+> `Requires access to <operationKey>. Ask an admin of this product.`
+
+That string form is a **degradation** for operations no generated method covers,
+not licence to pass a key where a method exists — the accessor path is a lossy
+view of the key. An App whose every gate holds an `Operation` never uses it, and
+that is the norm rather than an omission. `accessReason` explains ONE operation;
+choosing which one to explain among a button's several is the caller's, not the
+helper's.
+It names what an admin can grant, not the caller's role: a role name gives them
+nothing to act on. It names the operation key as well as the level because a
+level alone does not identify the grant — seventeen controls on one screen can
+all require `level:write` — and an admin grants both by level and by exact key,
+so the user has to be able to pass on both. Building it from the method also
+keeps it from drifting when the catalog re-levels a tool. Whatever renders it MUST be verified reachable **from the keyboard** —
+Tab to the wrapper, the tooltip opens (in tests: `userEvent.tab()` then
+`findByRole('tooltip')`). Asserting only that a hint attribute is present does
+not satisfy this: that assertion is green against a hint no user can reach.
+
+The level MUST come from the generated method itself (`op.level`, on the
+`Operation` the method satisfies) and from nowhere else: not a lookup table in
+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.
+
+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
+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 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
+that operation's level and key; gating it on the union greys out a button the caller can
+in fact use.
+
+An App SHOULD state the constraint once in a card footer (`CardNote`) rather than
+on every control of a form whose save is deferred: the reader meets the sentence
+before editing rather than after, and one line replaces fifteen identical
+tooltips. The fields stay inactive and the save stays disabled either way — the
+note replaces the per-control hints, not the gate. And the `Tooltip` trigger MUST sit outside every element carrying
+`pointer-events-none` — the App's own lists, chips and overlays as much as the
+kit's disabled buttons — since the hint is swallowed by the same mechanics either
+way.
+
+This applies to every gated write, not only the ones with a button. A drag
+handle, an inline-editable cell and a field that autosaves on blur are gated the
+same way: the native inactive state for that control (`draggable={false}`,
+`readOnly`, `disabled`) plus the reason on a keyboard-reachable `Tooltip`
+wrapper. Leaving a write ungated for the gateway to refuse is permitted ONLY
+where the element has no wrapper that can be made focusable, and that exception
+MUST be written into the App's own spec with its reason. A button that performs
+several operations is disabled if ANY of them is denied, and its reason names
+the level and key of the operation that blocked it.
+
+The reason is claimed only when the App actually knows it. With
+`access.state === 'error'` the `/me` call failed and **nothing** is known about
+the caller's role: the App MUST make no prediction — leave the control enabled,
+name no missing operation, and let the gateway answer, rendering any refusal through
+`isAccessDenied`. Disabling on error makes the client the authority and tells
+the user their role forbids something no one has established. (`can()` itself is
+unaffected: it stays `false` unless the state is `ready`.) While the state is
+`idle` or `loading` the control SHOULD start disabled and enable itself, but
+SHOULD NOT name a missing level or operation it does not yet know.
 
 An App MUST NOT treat that prediction as enforcement. `can()` answers from a
 snapshot fetched once from the `organization_product_me` tool; the gateway is
@@ -363,4 +448,11 @@ Pass the generated method rather than a hand-written tool id
 (`app.access.can(app.mail.domain.create)`): the accessor path is a lossy view
 of the tool id, so a literal string can silently drift from the call it gates.
 
+One gap is known and accepted: `@lessly/ui`'s `ConfirmDialog` takes an `onError`
+that returns a string, so the kit picks the tone and a refusal raised inside the
+dialog cannot be painted neutrally yet. An App SHOULD still route that error
+through `isAccessDenied()` for the *words*, and MUST NOT reimplement the confirm
+flow to win the colour — it would forfeit the focus trap, busy state, confirm
+phrase and step-up. Tracked as platform #2915.
+
 See `recipes/access.md` for the load-once pattern and the empty-state shape.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lessly/sdk-app",
-  "version": "61.2.0",
+  "version": "62.1.0",
   "type": "module",
   "sideEffects": false,
   "engines": {
@@ -148,6 +148,16 @@
         "default": "./dist/organization/index.cjs"
       }
     },
+    "./playground": {
+      "import": {
+        "types": "./dist/playground/index.d.ts",
+        "default": "./dist/playground/index.js"
+      },
+      "require": {
+        "types": "./dist/playground/index.d.cts",
+        "default": "./dist/playground/index.cjs"
+      }
+    },
     "./realtime": {
       "import": {
         "types": "./dist/realtime/index.d.ts",
@@ -199,5 +209,5 @@
       }
     }
   },
-  "sdkContentHash": "sha256:e136531e93f19a2cd0e3d8b282f4cb0037bfac84b281cea72e6bcb372d34925b"
+  "sdkContentHash": "sha256:965d6441024647f1461d4e50bedeba9d79dca805ea4668ca8c9ecedefc1c0d0a"
 }