@softr/sdk 0.0.69 → 0.0.70

package/dist/index.d.ts

@@ -6,6 +6,7 @@ import { DateOptions, DateParts, DateSeparator, DateValue, FixedDateFormat, Form
 import { SoftrContext } from "./auth/context.js";
 import { AuthSettings } from "./auth/platform.js";
 import { checkAccess, defineVisibility, isAuthorized } from "./visibility/visibility.js";
+import { Page, PageSettings, definePage, pageHead } from "./visibility/page.js";
 import { assertRouteAccess, guardRoute, isAccessError, isAlreadyAuthenticatedError, isForbiddenError, isUnauthenticatedError } from "./visibility/route.js";
 import { toReturnPath } from "./auth/returnPath.js";
 import { AuthOptions, AuthSettingsProvider, getAuthSettings, getSoftrContext, initialSoftrContext, softrAuthMiddleware, useAuthSettings, useCurrentUser } from "./auth/isomorphic.js";
@@ -16,4 +17,4 @@ import { useUserTimezone } from "./timezone.js";
 import { PwaInstall, PwaPlatform, SoftrPwaHead, usePwaInstall } from "./pwa.js";
 import { DefaultErrorOverlay } from "./default-error-overlay.js";
 import { Audience } from "./visibility/audience.js";
-export { type ActionPermissions, Audience, type AuthOptions, type AuthSettings, AuthSettingsProvider, type DateOptions, type DateParts, type DateSeparator, type DateValue, DefaultErrorOverlay, type FieldShape, type FileAttachment, type FileItem, type FixedDateFormat, FormattedDate, type Formatting, FormattingScope, type PwaInstall, type PwaPlatform, type SoftrContext, type SoftrDatasources, type SoftrFieldRegistry, SoftrPwaHead, type SoftrUserGroupId, type SoftrUserGroups, type User, type WeekDay, assertRouteAccess, checkAccess, defineIntegration, defineMutation, defineQuery, defineVisibility, defineWorkflow, fieldShape, formatDate, formatDateTime, formatDuration, formatField, formatNumber, formatValue, getAuthSettings, getSoftrContext, guardRoute, initialSoftrContext, isAccessError, isAlreadyAuthenticatedError, isAuthorized, isForbiddenError, isUnauthenticatedError, registerSoftrFields, softrAuthMiddleware, softrMcpMiddleware, toReturnPath, useAuthSettings, useCurrentUser, useFileUpload, useFormatting, useOverrides, usePwaInstall, useUserTimezone };
+export { type ActionPermissions, Audience, type AuthOptions, type AuthSettings, AuthSettingsProvider, type DateOptions, type DateParts, type DateSeparator, type DateValue, DefaultErrorOverlay, type FieldShape, type FileAttachment, type FileItem, type FixedDateFormat, FormattedDate, type Formatting, FormattingScope, type Page, type PageSettings, type PwaInstall, type PwaPlatform, type SoftrContext, type SoftrDatasources, type SoftrFieldRegistry, SoftrPwaHead, type SoftrUserGroupId, type SoftrUserGroups, type User, type WeekDay, assertRouteAccess, checkAccess, defineIntegration, defineMutation, definePage, defineQuery, defineVisibility, defineWorkflow, fieldShape, formatDate, formatDateTime, formatDuration, formatField, formatNumber, formatValue, getAuthSettings, getSoftrContext, guardRoute, initialSoftrContext, isAccessError, isAlreadyAuthenticatedError, isAuthorized, isForbiddenError, isUnauthenticatedError, pageHead, registerSoftrFields, softrAuthMiddleware, softrMcpMiddleware, toReturnPath, useAuthSettings, useCurrentUser, useFileUpload, useFormatting, useOverrides, usePwaInstall, useUserTimezone };

package/dist/index.js

@@ -2,6 +2,7 @@ import { useFileUpload } from "./core/use-file-upload.js";
 import { defineIntegration, defineMutation, defineQuery, defineWorkflow } from "./action.js";
 import { checkAccess, defineVisibility, isAuthorized } from "./visibility/visibility.js";
 import { assertRouteAccess, guardRoute, isAccessError, isAlreadyAuthenticatedError, isForbiddenError, isUnauthenticatedError } from "./visibility/route.js";
+import { definePage, pageHead } from "./visibility/page.js";
 import { toReturnPath } from "./auth/returnPath.js";
 import { FormattedDate, FormattingScope, formatDate, formatDateTime, formatNumber, useFormatting } from "./formatting.js";
 import { SoftrPwaHead, usePwaInstall } from "./pwa.js";
@@ -13,4 +14,4 @@ import { useUserTimezone } from "./timezone.js";
 import { DefaultErrorOverlay } from "./default-error-overlay.js";
 import { Audience } from "./visibility/audience.js";
 
-export { Audience, AuthSettingsProvider, DefaultErrorOverlay, FormattedDate, FormattingScope, SoftrPwaHead, assertRouteAccess, checkAccess, defineIntegration, defineMutation, defineQuery, defineVisibility, defineWorkflow, fieldShape, formatDate, formatDateTime, formatDuration, formatField, formatNumber, formatValue, getAuthSettings, getSoftrContext, guardRoute, initialSoftrContext, isAccessError, isAlreadyAuthenticatedError, isAuthorized, isForbiddenError, isUnauthenticatedError, registerSoftrFields, softrAuthMiddleware, softrMcpMiddleware, toReturnPath, useAuthSettings, useCurrentUser, useFileUpload, useFormatting, useOverrides, usePwaInstall, useUserTimezone };
+export { Audience, AuthSettingsProvider, DefaultErrorOverlay, FormattedDate, FormattingScope, SoftrPwaHead, assertRouteAccess, checkAccess, defineIntegration, defineMutation, definePage, defineQuery, defineVisibility, defineWorkflow, fieldShape, formatDate, formatDateTime, formatDuration, formatField, formatNumber, formatValue, getAuthSettings, getSoftrContext, guardRoute, initialSoftrContext, isAccessError, isAlreadyAuthenticatedError, isAuthorized, isForbiddenError, isUnauthenticatedError, pageHead, registerSoftrFields, softrAuthMiddleware, softrMcpMiddleware, toReturnPath, useAuthSettings, useCurrentUser, useFileUpload, useFormatting, useOverrides, usePwaInstall, useUserTimezone };

package/dist/package.js

@@ -1,5 +1,5 @@
 //#region package.json
-var version = "0.0.69";
+var version = "0.0.70";
 
 //#endregion
 export { version };

package/dist/visibility/page.d.ts

@@ -0,0 +1,72 @@
+import { VisibilityRule } from "./visibility.js";
+import { AnyRouteMatch } from "@tanstack/react-router";
+
+//#region src/visibility/page.d.ts
+/** The part of TanStack's `head` context a page setting can read. */
+type HeadContext = {
+  match: {
+    id: string;
+  };
+  matches: ReadonlyArray<{
+    id: string;
+  }>;
+  loaderData?: AnyRouteMatch["loaderData"];
+};
+type HeadSetting<T> = T | ((ctx: HeadContext) => T | undefined);
+type PageSettings = {
+  visibility?: VisibilityRule;
+  title?: HeadSetting<string>;
+  description?: HeadSetting<string>;
+  searchEngineIndexing?: HeadSetting<boolean>;
+  canonicalUrl?: HeadSetting<string>;
+  socialTitle?: HeadSetting<string>;
+  socialDescription?: HeadSetting<string>;
+  socialImage?: HeadSetting<string>;
+};
+declare const pageBrand: unique symbol;
+/** The settings {@link definePage} has produced. */
+type Page<S extends PageSettings = PageSettings> = S & {
+  readonly [pageBrand]: "page";
+};
+/**
+ * Declares a route's settings: who may open it, its title and its SEO tags.
+ *
+ * One call per route file, at module scope, with an object literal. Studio
+ * reads and rewrites each setting written out as a literal; a computed one is
+ * changed in the code. A head setting that depends on the route's data is a
+ * function of its head context. The route's `beforeLoad` and `head` apply it.
+ *
+ * @example
+ * const pageSettings = definePage({
+ *   visibility: { userGroupTypes: ["LOGGED_IN_USERS"] },
+ *   title: ({ loaderData }) => loaderData?.name,
+ * })
+ *
+ * export const Route = createFileRoute("/_app/projects/$projectId")({
+ *   beforeLoad: guardRoute(pageSettings),
+ *   loader: ({ params }) => loadProject({ data: params.projectId }),
+ *   head: pageHead(pageSettings),
+ *   component: Project,
+ * })
+ */
+declare function definePage<const S extends PageSettings>(settings: S & { [K in Exclude<keyof S, keyof PageSettings>]: never }): Page<S>;
+type Meta = NonNullable<AnyRouteMatch["meta"]>;
+type Links = NonNullable<AnyRouteMatch["links"]>;
+/**
+ * The router keeps the deepest route's tag for each title, name and property,
+ * so a layout's settings reach every page under it that does not state its own.
+ * A canonical URL names one page, so only the page the visitor is on renders
+ * its own.
+ *
+ * Returned rather than called with the route's context: a `head` written as
+ * `(ctx) => …` before `loader` stops TypeScript inferring the loader's types.
+ *
+ * @example
+ * head: pageHead(pageSettings)
+ */
+declare function pageHead(page: Page): (ctx: HeadContext) => {
+  meta: Meta;
+  links: Links;
+};
+//#endregion
+export { Page, PageSettings, definePage, pageHead };

package/dist/visibility/page.js

@@ -0,0 +1,79 @@
+//#region src/visibility/page.ts
+/**
+* Declares a route's settings: who may open it, its title and its SEO tags.
+*
+* One call per route file, at module scope, with an object literal. Studio
+* reads and rewrites each setting written out as a literal; a computed one is
+* changed in the code. A head setting that depends on the route's data is a
+* function of its head context. The route's `beforeLoad` and `head` apply it.
+*
+* @example
+* const pageSettings = definePage({
+*   visibility: { userGroupTypes: ["LOGGED_IN_USERS"] },
+*   title: ({ loaderData }) => loaderData?.name,
+* })
+*
+* export const Route = createFileRoute("/_app/projects/$projectId")({
+*   beforeLoad: guardRoute(pageSettings),
+*   loader: ({ params }) => loadProject({ data: params.projectId }),
+*   head: pageHead(pageSettings),
+*   component: Project,
+* })
+*/
+function definePage(settings) {
+	return settings;
+}
+/**
+* The router keeps the deepest route's tag for each title, name and property,
+* so a layout's settings reach every page under it that does not state its own.
+* A canonical URL names one page, so only the page the visitor is on renders
+* its own.
+*
+* Returned rather than called with the route's context: a `head` written as
+* `(ctx) => …` before `loader` stops TypeScript inferring the loader's types.
+*
+* @example
+* head: pageHead(pageSettings)
+*/
+function pageHead(page) {
+	return (ctx) => {
+		const resolve = (setting) => typeof setting === "function" ? setting(ctx) : setting;
+		const tag = (setting, make) => {
+			const value = resolve(setting);
+			return typeof value === "string" && value !== "" ? [make(value)] : [];
+		};
+		const indexing = resolve(page.searchEngineIndexing);
+		return {
+			meta: [
+				...tag(page.title, (title) => ({ title })),
+				...tag(page.description, (content) => ({
+					name: "description",
+					content
+				})),
+				...tag(page.socialTitle, (content) => ({
+					property: "og:title",
+					content
+				})),
+				...tag(page.socialDescription, (content) => ({
+					property: "og:description",
+					content
+				})),
+				...tag(page.socialImage, (content) => ({
+					property: "og:image",
+					content
+				})),
+				...typeof indexing === "boolean" ? [{
+					name: "robots",
+					content: indexing ? "index" : "noindex"
+				}] : []
+			],
+			links: ctx.matches.at(-1)?.id === ctx.match.id ? tag(page.canonicalUrl, (href) => ({
+				rel: "canonical",
+				href
+			})) : []
+		};
+	};
+}
+
+//#endregion
+export { definePage, pageHead };

package/dist/visibility/route.d.ts

@@ -1,4 +1,5 @@
-import { AccessContext, AccessReason, Narrowed, Visibility, VisibilityRule } from "./visibility.js";
+import { AccessContext, AccessReason, Narrowed, VisibilityRule } from "./visibility.js";
+import { Page, PageSettings } from "./page.js";
 
 //#region src/visibility/route.d.ts
 
@@ -42,8 +43,11 @@ declare function isUnauthenticatedError(error: unknown): error is AccessError;
 declare function isForbiddenError(error: unknown): error is AccessError;
 /** True for an access error thrown because a signed-out-only route saw a user. */
 declare function isAlreadyAuthenticatedError(error: unknown): error is AccessError;
+type GuardedPage = Page<PageSettings & {
+  visibility: VisibilityRule;
+}>;
 /**
- * A `beforeLoad` handler that denies a visitor who fails the rule.
+ * A `beforeLoad` handler that denies a visitor the page's rule does not admit.
  *
  * Each reason falls back to the app's configured behaviour. Pass `overrides` to
  * change what any one reason does. A redirected signed-out visitor carries the
@@ -52,9 +56,9 @@ declare function isAlreadyAuthenticatedError(error: unknown): error is AccessErr
  * Throws a router redirect, so it belongs in `beforeLoad` and nowhere else.
  *
  * @example
- * beforeLoad: guardRoute(visibility, { unauthenticated: "/sign-in" })
+ * beforeLoad: guardRoute(pageSettings, { unauthenticated: "/sign-in" })
  */
-declare function guardRoute(visibility: Visibility, overrides?: GuardOverrides): (opts: {
+declare function guardRoute(page: GuardedPage, overrides?: GuardOverrides): (opts: {
   context: AccessContext;
   location: {
     href: string;
@@ -66,7 +70,7 @@ declare function guardRoute(visibility: Visibility, overrides?: GuardOverrides):
  *
  * @example
  * beforeLoad: (opts) => {
- *   assertRouteAccess(visibility, opts)
+ *   assertRouteAccess(pageSettings, opts)
  *   if (opts.params.projectId === "demo") throw redirect({ to: "/projects" })
  * }
  */
@@ -75,7 +79,9 @@ declare function assertRouteAccess<R extends VisibilityRule, O extends {
   location: {
     href: string;
   };
-}>(visibility: Visibility<R>, opts: O): asserts opts is O & {
+}>(page: Page<PageSettings & {
+  visibility: R;
+}>, opts: O): asserts opts is O & {
   context: Narrowed<R>;
 };
 //#endregion

package/dist/visibility/route.js

@@ -1,4 +1,5 @@
-import { ACCESS_REASONS, checkAccess } from "./visibility.js";
+import { panic } from "../assertions.js";
+import { ACCESS_REASONS, checkRule } from "./visibility.js";
 import { softrConfig } from "../softr-config.js";
 import { redirect } from "@tanstack/react-router";
 
@@ -52,8 +53,11 @@ function thrownFor(reason, overrides, location) {
 		reason
 	};
 }
+function ruleOf(page) {
+	return page.visibility ?? panic("the page states no visibility rule to guard it with");
+}
 /**
-* A `beforeLoad` handler that denies a visitor who fails the rule.
+* A `beforeLoad` handler that denies a visitor the page's rule does not admit.
 *
 * Each reason falls back to the app's configured behaviour. Pass `overrides` to
 * change what any one reason does. A redirected signed-out visitor carries the
@@ -62,11 +66,11 @@ function thrownFor(reason, overrides, location) {
 * Throws a router redirect, so it belongs in `beforeLoad` and nowhere else.
 *
 * @example
-* beforeLoad: guardRoute(visibility, { unauthenticated: "/sign-in" })
+* beforeLoad: guardRoute(pageSettings, { unauthenticated: "/sign-in" })
 */
-function guardRoute(visibility, overrides) {
+function guardRoute(page, overrides) {
 	return ({ context, location }) => {
-		const result = checkAccess(visibility, context);
+		const result = checkRule(ruleOf(page), context);
 		if (result.ok) return;
 		throw thrownFor(result.reason, overrides, location);
 	};
@@ -77,12 +81,12 @@ function guardRoute(visibility, overrides) {
 *
 * @example
 * beforeLoad: (opts) => {
-*   assertRouteAccess(visibility, opts)
+*   assertRouteAccess(pageSettings, opts)
 *   if (opts.params.projectId === "demo") throw redirect({ to: "/projects" })
 * }
 */
-function assertRouteAccess(visibility, opts) {
-	const result = checkAccess(visibility, opts.context);
+function assertRouteAccess(page, opts) {
+	const result = checkRule(ruleOf(page), opts.context);
 	if (result.ok) return;
 	throw thrownFor(result.reason, void 0, opts.location);
 }

package/dist/visibility/visibility.d.ts

@@ -48,18 +48,13 @@ type Narrowed<R extends VisibilityRule> = R["userGroupTypes"] extends ReadonlyAr
   user: null;
 } : AccessContext : AccessContext;
 /**
- * Declares who may see a route or a region of the page.
- *
- * At module scope in a route file, with a literal rule: the build reads these
- * declarations out of the source to publish the app's route visibility.
+ * Declares who may see a region of the page. A route's own rule is the
+ * `visibility` of its `definePage`.
  *
  * @example
- * const visibility = defineVisibility({ userGroupTypes: ["LOGGED_IN_USERS"] })
+ * const staffOnly = defineVisibility({ userGroupTypes: ["LOGGED_IN_USERS"], customGroups: ["…"] })
  *
- * export const Route = createFileRoute("/about")({
- *   beforeLoad: guardRoute(visibility),
- *   component: About,
- * })
+ * <Audience visibility={staffOnly} fallback={null}>…</Audience>
  */
 declare function defineVisibility<const R extends VisibilityRule>(rule: R): Visibility<R>;
 /**

package/dist/visibility/visibility.js

@@ -13,8 +13,12 @@ const ACCESS_REASONS = [
 ];
 /** The decision and, when a visitor is denied, the reason. Throws nothing. */
 function checkAccess(visibility, context) {
+	return checkRule(visibility, context);
+}
+/** {@link checkAccess} for a page's rule, which {@link defineVisibility} has not produced. */
+function checkRule(rule, context) {
 	const { user } = context;
-	const audiences = visibility.userGroupTypes;
+	const audiences = rule.userGroupTypes;
 	if (user === null) return audiences.includes("NON_LOGGED_IN_USERS") ? { ok: true } : {
 		ok: false,
 		reason: "unauthenticated"
@@ -23,7 +27,7 @@ function checkAccess(visibility, context) {
 		ok: false,
 		reason: "alreadyAuthenticated"
 	};
-	const required = visibility.customGroups ?? [];
+	const required = rule.customGroups ?? [];
 	if (required.length === 0) return { ok: true };
 	return required.some((id) => user.userGroupIds.includes(id)) ? { ok: true } : {
 		ok: false,
@@ -31,18 +35,13 @@ function checkAccess(visibility, context) {
 	};
 }
 /**
-* Declares who may see a route or a region of the page.
-*
-* At module scope in a route file, with a literal rule: the build reads these
-* declarations out of the source to publish the app's route visibility.
+* Declares who may see a region of the page. A route's own rule is the
+* `visibility` of its `definePage`.
 *
 * @example
-* const visibility = defineVisibility({ userGroupTypes: ["LOGGED_IN_USERS"] })
+* const staffOnly = defineVisibility({ userGroupTypes: ["LOGGED_IN_USERS"], customGroups: ["…"] })
 *
-* export const Route = createFileRoute("/about")({
-*   beforeLoad: guardRoute(visibility),
-*   component: About,
-* })
+* <Audience visibility={staffOnly} fallback={null}>…</Audience>
 */
 function defineVisibility(rule) {
 	return rule;
@@ -56,4 +55,4 @@ function isAuthorized(visibility, context) {
 }
 
 //#endregion
-export { ACCESS_REASONS, checkAccess, defineVisibility, isAuthorized };
+export { ACCESS_REASONS, checkAccess, checkRule, defineVisibility, isAuthorized };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@softr/sdk",
-  "version": "0.0.69",
+  "version": "0.0.70",
   "type": "module",
   "exports": {
     ".": { "types": "./dist/index.d.ts", "import": "./dist/index.js" },