@softr/sdk 0.0.88-signing.0 → 0.0.89-alpha.0

package/skills/softr-sdk/region-visibility/SKILL.md

@@ -9,7 +9,7 @@ description: >-
 metadata:
   type: sub-skill
   library: softr-sdk
-  library_version: 0.0.88-signing.0
+  library_version: 0.0.89-alpha.0
 ---
 
 **Boundary.** `Audience` and `defineVisibility` come from `@softr/sdk` and work anywhere.
@@ -47,11 +47,9 @@ The rules are the same four a route uses, and [routes-and-visibility](../routes-
 
 ### Where the rule is declared
 
-A region's rule is an ordinary value. It can sit beside the component, or come from a module the whole app shares so several regions read the same one. A route's rule cannot. Softr reads that one out of the route file, so it has to be declared there.
+A region's rule is an ordinary value. It can sit beside the component, in the route file, or in a module the whole app shares so several regions read the same one.
 
-Two files cannot hold a region's rule. Any declaration in `__root.tsx` is a build error. In the lazy half of a split route, Softr takes the first declaration as the route's own. Put the rule in the component's file or a shared module and import it.
-
-A route file may declare a region's rule alongside its own. The route's rule is the one `beforeLoad` names.
+It is separate from the route's own rule. That one is the `visibility` of the route's `definePage`, which `beforeLoad` applies: see [routes-and-visibility/SKILL.md](../routes-and-visibility/SKILL.md).
 
 ### Hiding a control is not authorization
 

package/skills/softr-sdk/routes-and-visibility/SKILL.md

@@ -1,21 +1,22 @@
 ---
 name: routes-and-visibility
 description: >-
-  Add a route file and declare who may see it: defineVisibility with
-  LOGGED_IN_USERS, NON_LOGGED_IN_USERS and customGroups, guardRoute and
-  assertRouteAccess in a route, isAuthorized and checkAccess anywhere, rendering
-  an access error, and the lint rule that requires the declaration.
+  Add a route file and declare its settings: definePage with its visibility
+  (LOGGED_IN_USERS, NON_LOGGED_IN_USERS and customGroups) and its title,
+  guardRoute or assertRouteAccess in beforeLoad, pageHead in head,
+  isAuthorized and checkAccess anywhere, rendering an access error, and the
+  lint rules that require the declaration.
 metadata:
   type: sub-skill
   library: softr-sdk
-  library_version: 0.0.88-signing.0
+  library_version: 0.0.89-alpha.0
 ---
 
-**Boundary.** `defineVisibility`, the access functions and the error predicates come from `@softr/sdk` and work anywhere.
+**Boundary.** `definePage`, `pageHead`, the access functions and the error predicates come from `@softr/sdk` and work anywhere.
 
 # Route visibility
 
-Every route file in a Softr app declares who may see it. Softr reads that declaration out of the source text without executing it and publishes it to Softr Studio, which shows the app owner every route and its audience. That is why the rules below are strict: a rule Softr cannot read is a rule Studio cannot show.
+Every route file in a Softr app declares its settings: who may see it, its title and its SEO tags. Softr reads them out of the source text without executing it and shows them in Softr Studio, where the app owner sees every route and its audience and can change them. That is why the rules below are strict: a setting Softr cannot read is a setting Studio cannot show.
 
 ## Setup
 
@@ -23,12 +24,16 @@ Every route file, without exception, looks like this:
 
 ```tsx
 import { createFileRoute } from '@tanstack/react-router'
-import { defineVisibility, guardRoute } from '@softr/sdk'
+import { definePage, guardRoute, pageHead } from '@softr/sdk'
 
-const visibility = defineVisibility({ userGroupTypes: ['LOGGED_IN_USERS'] })
+const pageSettings = definePage({
+  visibility: { userGroupTypes: ['LOGGED_IN_USERS'] },
+  title: 'Billing',
+})
 
 export const Route = createFileRoute('/_app/billing')({
-  beforeLoad: guardRoute(visibility),
+  beforeLoad: guardRoute(pageSettings),
+  head: pageHead(pageSettings),
   component: Billing,
 })
 
@@ -37,30 +42,31 @@ function Billing() {
 }
 ```
 
-The route's rule is one `defineVisibility` call at module scope, with an inline object literal as its argument.
+The route's settings are one `definePage` call at module scope, with an inline object literal as its argument. It always states `visibility`, and a page states its `title` too. `beforeLoad` applies the visibility, and `head` renders the title and the SEO tags.
 
-Four constraints on that shape, because Softr reads the file rather than running it:
+These constraints hold, because Softr reads the file rather than running it:
 
 - The call must initialise a top-level `const`.
 - The import must be a direct named import from `@softr/sdk`.
-- The route guards itself in `beforeLoad`, naming a rule declared in the same file. A rule imported from elsewhere is rejected.
-- Every value inside the literal is written there too. A group id taken from a `const`, a spread or an import is rejected, even when two routes share it: repeat the id on each.
-- Never declare on `__root.tsx`. The root cannot carry an audience, so a declaration there would gate nothing while looking like it does. Softr rejects it. Put the rule on a layout below the root instead.
+- A route file has one `definePage`. The route names it in `beforeLoad` and in `head`. A page imported from elsewhere is rejected.
+- Every value inside the literal is written there too. A group id taken from a `const`, a spread or an import still type-checks, but Studio can no longer change that setting. Repeat the id on each route, even when two routes share it.
+- A head setting that depends on the route's data is a function of its head context: `title: ({ loaderData }) => loaderData?.name`.
+- Never state `visibility` on `__root.tsx`. The root cannot carry an audience, so a rule there would gate nothing while looking like it does. Its `definePage` holds the app-wide head defaults only. Put the rule on a layout below the root instead.
 
 `userGroupTypes` is a set, so a rule names one audience or several:
 
 ```ts
-defineVisibility({ userGroupTypes: ['NON_LOGGED_IN_USERS', 'LOGGED_IN_USERS'] })  // everyone, signed in or not
-defineVisibility({ userGroupTypes: ['NON_LOGGED_IN_USERS'] })                     // signed-out only: login, signup
-defineVisibility({ userGroupTypes: ['LOGGED_IN_USERS'] })                         // any signed-in visitor
-defineVisibility({                                                                // those groups only
+visibility: { userGroupTypes: ['NON_LOGGED_IN_USERS', 'LOGGED_IN_USERS'] }  // everyone, signed in or not
+visibility: { userGroupTypes: ['NON_LOGGED_IN_USERS'] }                     // signed-out only: login, signup
+visibility: { userGroupTypes: ['LOGGED_IN_USERS'] }                         // any signed-in visitor
+visibility: {                                                               // those groups only
   userGroupTypes: ['LOGGED_IN_USERS'],
   customGroups: ['00000000-0000-0000-0000-00000000000a'],
-})
-defineVisibility({                                                                // signed-out visitors AND those groups
+}
+visibility: {                                                               // signed-out visitors AND those groups
   userGroupTypes: ['NON_LOGGED_IN_USERS', 'LOGGED_IN_USERS'],
   customGroups: ['00000000-0000-0000-0000-00000000000a'],
-})
+}
 ```
 
 Everyone is both audiences, as in the first line above. A set names each audience at most once and is never empty — the type and the build both reject one that does not. `customGroups` never stands alone: it narrows the `LOGGED_IN_USERS` half of the set, so the rule still names that half, and one without `userGroupTypes` is a type error. Absent or empty it means **any** signed-in visitor, not "nobody".
@@ -74,17 +80,20 @@ Take every id in `customGroups` from `docs/user-groups.md`, which lists each gro
 ```tsx
 // src/routes/_app.tsx: guards every route under /_app
 import { Outlet, createFileRoute } from '@tanstack/react-router'
-import { defineVisibility, guardRoute } from '@softr/sdk'
+import { definePage, guardRoute, pageHead } from '@softr/sdk'
 
-const visibility = defineVisibility({ userGroupTypes: ['LOGGED_IN_USERS'] })
+const pageSettings = definePage({ visibility: { userGroupTypes: ['LOGGED_IN_USERS'] } })
 
 export const Route = createFileRoute('/_app')({
-  beforeLoad: guardRoute(visibility),
+  beforeLoad: guardRoute(pageSettings),
+  head: pageHead(pageSettings),
   component: () => <Outlet />,
 })
 ```
 
-The whole match chain runs, so a layout guards everything beneath it. Sibling routes do not guard each other. `/admin/index.tsx` does nothing for `/admin/users.tsx` unless an `admin.tsx` layout exists. A route below a guarded layout declares and guards its own rule too.
+A pathless layout like this one is not a page, so it needs no `title`.
+
+The whole match chain runs, so a layout guards everything beneath it. Sibling routes do not guard each other. `/admin/index.tsx` does nothing for `/admin/users.tsx` unless an `admin.tsx` layout exists. A route below a guarded layout declares and guards its own settings too.
 
 A thrown error renders in place of the guarded route's component. A shell layout guarded with `LOGGED_IN_USERS`, where `unauthenticated` redirects, sends a signed-out visitor away before anything renders there. A rule that can _throw_ — a `customGroups` rule with `forbidden` set to throw — should not sit on the shell itself, or the error replaces the nav and chrome. Put it on a layout inside the shell, or on the restricted routes, so the error renders inside the chrome.
 
@@ -93,9 +102,9 @@ A thrown error renders in place of the guarded route's component. A shell layout
 `guardRoute` takes per-reason overrides as a second argument. A bare string is shorthand for a redirect.
 
 ```ts
-beforeLoad: guardRoute(visibility, { unauthenticated: '/marketing/sign-up' }),
-beforeLoad: guardRoute(visibility, { forbidden: { strategy: 'throw' } }),
-beforeLoad: guardRoute(visibility, {
+beforeLoad: guardRoute(pageSettings, { unauthenticated: '/marketing/sign-up' }),
+beforeLoad: guardRoute(pageSettings, { forbidden: { strategy: 'throw' } }),
+beforeLoad: guardRoute(pageSettings, {
   unauthenticated: { strategy: 'redirect', to: '/marketing/sign-up' },
   forbidden: { strategy: 'throw' },
 }),
@@ -142,15 +151,19 @@ That file covers every route at once; a route's own overrides win over it. A rul
 
 ```tsx
 import { createFileRoute } from '@tanstack/react-router'
-import { defineVisibility, guardRoute, isAccessError, isForbiddenError } from '@softr/sdk'
+import { definePage, guardRoute, isAccessError, isForbiddenError, pageHead } from '@softr/sdk'
 
-const visibility = defineVisibility({
-  userGroupTypes: ['LOGGED_IN_USERS'],
-  customGroups: ['00000000-0000-0000-0000-00000000000a'],
+const pageSettings = definePage({
+  visibility: {
+    userGroupTypes: ['LOGGED_IN_USERS'],
+    customGroups: ['00000000-0000-0000-0000-00000000000a'],
+  },
+  title: 'Billing',
 })
 
 export const Route = createFileRoute('/_app/billing')({
-  beforeLoad: guardRoute(visibility),
+  beforeLoad: guardRoute(pageSettings),
+  head: pageHead(pageSettings),
   component: Billing,
   errorComponent: ({ error }: { error: unknown }) => {
     if (isForbiddenError(error)) return <UpgradePrompt />
@@ -166,25 +179,53 @@ Use the predicates: `isAccessError` for any of the three, and `isUnauthenticated
 
 ### Run the check and then keep going
 
-`guardRoute` covers almost everything. When a route needs its own logic afterwards, `assertRouteAccess(visibility, opts)` applies the same rule to the whole `beforeLoad` argument and throws the same access error, using the default behaviour for each reason. It takes no overrides.
+`guardRoute` covers almost everything. When a route needs its own logic afterwards, `assertRouteAccess(pageSettings, opts)` applies the same rule to the whole `beforeLoad` argument and throws the same access error, using the default behaviour for each reason. It takes no overrides.
 
 It also narrows `opts.context.user` for the rest of the handler, where the set names one audience and no other: `User` under `['LOGGED_IN_USERS']`, `null` under `['NON_LOGGED_IN_USERS']`. A set naming both admits either kind of visitor, so it narrows to neither. `guardRoute` cannot, because it hands `beforeLoad` a function rather than running inside one.
 
-```ts
-import { redirect } from '@tanstack/react-router'
-import { assertRouteAccess } from '@softr/sdk'
+```tsx
+import { createFileRoute, redirect } from '@tanstack/react-router'
+import { assertRouteAccess, definePage, pageHead } from '@softr/sdk'
+
+const pageSettings = definePage({
+  visibility: { userGroupTypes: ['LOGGED_IN_USERS'] },
+  title: 'Reports',
+})
 
-beforeLoad: (opts) => {
-  assertRouteAccess(visibility, opts)
-  if (opts.context.user.email.endsWith('@example.com')) throw redirect({ to: '/internal' })
-},
+export const Route = createFileRoute('/_app/reports')({
+  beforeLoad: (opts) => {
+    assertRouteAccess(pageSettings, opts)
+    if (opts.context.user.email.endsWith('@example.com')) throw redirect({ to: '/internal' })
+  },
+  head: pageHead(pageSettings),
+  component: Reports,
+})
 ```
 
 Take `opts` whole. A `context` destructured in the parameter list does not narrow.
 
-Reach for `assertRouteAccess` when the route wants the error thrown for it, `isAuthorized(visibility, context)` when it wants the same narrowing without a throw, and `checkAccess(visibility, context)` when it needs to branch on why. `checkAccess` returns `{ ok: true } | { ok: false, reason }` and throws nothing. All of them are synchronous and make no request.
+`guardRoute` and `assertRouteAccess` throw router redirects, so they belong in a route and nowhere else. That is what `Route` in their names marks.
+
+### Check a rule without a throw
+
+`isAuthorized(rule, context)` and `checkAccess(rule, context)` answer the same question and throw nothing, so they work anywhere: in a loader, a component or a server function. They take a rule from `defineVisibility`, not a page. Use `isAuthorized` for the same narrowing of `context.user` as `assertRouteAccess`, and `checkAccess` to branch on why: it returns `{ ok: true } | { ok: false, reason }`. All of them are synchronous and make no request.
+
+```tsx
+import { defineVisibility, isAuthorized, useCurrentUser } from '@softr/sdk'
+
+const staffOnly = defineVisibility({
+  userGroupTypes: ['LOGGED_IN_USERS'],
+  customGroups: ['00000000-0000-0000-0000-00000000000a'],
+})
+
+function StaffNote() {
+  const context = { user: useCurrentUser() }
+  if (!isAuthorized(staffOnly, context)) return null
+  return <p>Signed in as staff: {context.user.email}</p>
+}
+```
 
-`guardRoute` and `assertRouteAccess` throw router redirects, so they belong in a route and nowhere else. That is what `Route` in their names marks. `isAuthorized` and `checkAccess` throw nothing and answer anywhere, in a loader, a component or a server function.
+To show or hide a part of a page, `Audience` is simpler: see [region-visibility/SKILL.md](../region-visibility/SKILL.md).
 
 ## References
 

package/skills/softr-sdk/workflows/SKILL.md

@@ -9,7 +9,7 @@ description: >-
 metadata:
   type: sub-skill
   library: softr-sdk
-  library_version: 0.0.88-signing.0
+  library_version: 0.0.89-alpha.0
 ---
 
 **Boundary.** `workflow` lives on `@softr/sdk/server` and runs only inside a `createServerFn` handler — importing it into a component fails the build. `defineWorkflow` and every type come from `@softr/sdk` and can be imported anywhere.