@webstir-io/module-contract 0.8.1 → 0.9.1

package/dist/client-nav.d.ts

@@ -15,5 +15,19 @@ export declare const CLIENT_NAV_HEADERS: {
     /** Identifies one form submission, so the same post sent again gets the first answer. */
     readonly submission: 'x-webstir-submission';
 };
-/** The form field carrying the submission id when client-nav falls back to a normal post. */
+/**
+ * The form field carrying a submission id: rendered into every POST form a view renders, and set by
+ * client-nav when it falls back to a normal post.
+ */
 export declare const CLIENT_NAV_SUBMISSION_FIELD = "_webstir_submission";
+/**
+ * The form field carrying the address of the page a form was rendered on, so a failed submission
+ * goes back to that page even when the browser sends no Referer, or one that names the address of
+ * an earlier failed post.
+ */
+export declare const FORM_PAGE_FIELD = "_webstir_page";
+/**
+ * The form field an app writes into a form that is one of many on a page (one per item), naming
+ * the state its failures go to: `<input type="hidden" name="_webstir_form" value="reply:42">`.
+ */
+export declare const FORM_ID_FIELD = "_webstir_form";

package/dist/client-nav.js

@@ -15,5 +15,19 @@ export const CLIENT_NAV_HEADERS = {
     /** Identifies one form submission, so the same post sent again gets the first answer. */
     submission: 'x-webstir-submission',
 };
-/** The form field carrying the submission id when client-nav falls back to a normal post. */
+/**
+ * The form field carrying a submission id: rendered into every POST form a view renders, and set by
+ * client-nav when it falls back to a normal post.
+ */
 export const CLIENT_NAV_SUBMISSION_FIELD = '_webstir_submission';
+/**
+ * The form field carrying the address of the page a form was rendered on, so a failed submission
+ * goes back to that page even when the browser sends no Referer, or one that names the address of
+ * an earlier failed post.
+ */
+export const FORM_PAGE_FIELD = '_webstir_page';
+/**
+ * The form field an app writes into a form that is one of many on a page (one per item), naming
+ * the state its failures go to: `<input type="hidden" name="_webstir_form" value="reply:42">`.
+ */
+export const FORM_ID_FIELD = '_webstir_form';

package/dist/index.d.ts

@@ -98,6 +98,29 @@ export interface FormState {
 export interface FormStateReader {
     read(formId: string): FormState;
 }
+/**
+ * What a page binds for one form: whether it came back from a failed submission, what was typed in
+ * each field, and the first error per field (and `form`, for errors about the whole form).
+ */
+export declare function formStateSchema<const TFields extends readonly string[]>(fields: TFields): z.ZodObject<{
+    submitted: z.ZodBoolean;
+    values: z.ZodObject<Record<TFields[number], z.ZodOptional<z.ZodString>>, "strip", z.ZodTypeAny, z.objectUtil.addQuestionMarks<z.baseObjectOutputType<Record<TFields[number], z.ZodOptional<z.ZodString>>>, any> extends infer T ? { [k in keyof T]: T[k]; } : never, z.baseObjectInputType<Record<TFields[number], z.ZodOptional<z.ZodString>>> extends infer T_1 ? { [k in keyof T_1]: T_1[k]; } : never>;
+    errors: z.ZodObject<Record<(readonly [...TFields, "form"])[number], z.ZodOptional<z.ZodString>>, "strip", z.ZodTypeAny, z.objectUtil.addQuestionMarks<z.baseObjectOutputType<Record<(readonly [...TFields, "form"])[number], z.ZodOptional<z.ZodString>>>, any> extends infer T_2 ? { [k in keyof T_2]: T_2[k]; } : never, z.baseObjectInputType<Record<(readonly [...TFields, "form"])[number], z.ZodOptional<z.ZodString>>> extends infer T_3 ? { [k in keyof T_3]: T_3[k]; } : never>;
+}, "strip", z.ZodTypeAny, z.objectUtil.addQuestionMarks<z.baseObjectOutputType<{
+    submitted: z.ZodBoolean;
+    values: z.ZodObject<Record<TFields[number], z.ZodOptional<z.ZodString>>, "strip", z.ZodTypeAny, z.objectUtil.addQuestionMarks<z.baseObjectOutputType<Record<TFields[number], z.ZodOptional<z.ZodString>>>, any> extends infer T ? { [k in keyof T]: T[k]; } : never, z.baseObjectInputType<Record<TFields[number], z.ZodOptional<z.ZodString>>> extends infer T_1 ? { [k in keyof T_1]: T_1[k]; } : never>;
+    errors: z.ZodObject<Record<(readonly [...TFields, "form"])[number], z.ZodOptional<z.ZodString>>, "strip", z.ZodTypeAny, z.objectUtil.addQuestionMarks<z.baseObjectOutputType<Record<(readonly [...TFields, "form"])[number], z.ZodOptional<z.ZodString>>>, any> extends infer T_2 ? { [k in keyof T_2]: T_2[k]; } : never, z.baseObjectInputType<Record<(readonly [...TFields, "form"])[number], z.ZodOptional<z.ZodString>>> extends infer T_3 ? { [k in keyof T_3]: T_3[k]; } : never>;
+}>, any> extends infer T_4 ? { [k in keyof T_4]: T_4[k]; } : never, z.baseObjectInputType<{
+    submitted: z.ZodBoolean;
+    values: z.ZodObject<Record<TFields[number], z.ZodOptional<z.ZodString>>, "strip", z.ZodTypeAny, z.objectUtil.addQuestionMarks<z.baseObjectOutputType<Record<TFields[number], z.ZodOptional<z.ZodString>>>, any> extends infer T ? { [k in keyof T]: T[k]; } : never, z.baseObjectInputType<Record<TFields[number], z.ZodOptional<z.ZodString>>> extends infer T_1 ? { [k in keyof T_1]: T_1[k]; } : never>;
+    errors: z.ZodObject<Record<(readonly [...TFields, "form"])[number], z.ZodOptional<z.ZodString>>, "strip", z.ZodTypeAny, z.objectUtil.addQuestionMarks<z.baseObjectOutputType<Record<(readonly [...TFields, "form"])[number], z.ZodOptional<z.ZodString>>>, any> extends infer T_2 ? { [k in keyof T_2]: T_2[k]; } : never, z.baseObjectInputType<Record<(readonly [...TFields, "form"])[number], z.ZodOptional<z.ZodString>>> extends infer T_3 ? { [k in keyof T_3]: T_3[k]; } : never>;
+}> extends infer T_5 ? { [k in keyof T_5]: T_5[k]; } : never>;
+/** A form's state as `formStateSchema(fields)` binds it, with `defaults` for a fresh form. */
+export declare function formView<const TFields extends readonly string[]>(state: FormState, fields: TFields, defaults?: Partial<Record<TFields[number], string>>): {
+    submitted: boolean;
+    values: Partial<Record<TFields[number], string>>;
+    errors: Partial<Record<TFields[number] | 'form', string>>;
+};
 export interface SSRContext<TParams = Record<string, string>, TAuth = unknown, TSession = unknown, TEnv extends EnvAccessor = EnvAccessor, TLogger extends Logger = Logger> {
     readonly url: URL;
     readonly params: TParams;
@@ -196,6 +219,18 @@ export declare const moduleErrorSchema: z.ZodObject<{
     correlationId?: string | undefined;
 }>;
 export type ModuleError = z.infer<typeof moduleErrorSchema>;
+/**
+ * Who reaches a route or view: `'required'` is anyone signed in; `{ role }` is someone signed in
+ * whose user has that role. Others are sent to sign in; signed in without the role is a 404.
+ */
+export declare const accessRequirementSchema: z.ZodUnion<[z.ZodLiteral<"required">, z.ZodObject<{
+    role: z.ZodString;
+}, "strict", z.ZodTypeAny, {
+    role: string;
+}, {
+    role: string;
+}>]>;
+export type AccessRequirement = z.infer<typeof accessRequirementSchema>;
 export declare const httpMethodSchema: z.ZodEnum<["GET", "HEAD", "POST", "PUT", "PATCH", "DELETE", "OPTIONS"]>;
 export type HttpMethod = z.infer<typeof httpMethodSchema>;
 export declare const routeInteractionKindSchema: z.ZodEnum<["navigation", "mutation"]>;
@@ -362,6 +397,17 @@ export declare const routeSessionSchema: z.ZodObject<{
 export type RouteSessionDefinition = z.infer<typeof routeSessionSchema>;
 export declare const flashLevelSchema: z.ZodEnum<["info", "success", "warning", "error"]>;
 export type FlashLevel = z.infer<typeof flashLevelSchema>;
+/** What a page binds as `flash`: the messages an action left for it. The framework supplies it. */
+export declare const flashSchema: z.ZodArray<z.ZodObject<{
+    level: z.ZodEnum<["info", "success", "warning", "error"]>;
+    message: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    level: "error" | "info" | "success" | "warning";
+    message: string;
+}, {
+    level: "error" | "info" | "success" | "warning";
+    message: string;
+}>, "many">;
 export declare const flashPublishConditionSchema: z.ZodEnum<["always", "success", "error"]>;
 export type FlashPublishCondition = z.infer<typeof flashPublishConditionSchema>;
 export declare const routeFlashMessageSchema: z.ZodObject<{
@@ -418,6 +464,8 @@ export declare const routeFlashSchema: z.ZodObject<{
 }>;
 export type RouteFlashDefinition = z.infer<typeof routeFlashSchema>;
 export declare const routeFormSchema: z.ZodObject<{
+    /** The form's id, which the page's loader reads its state by; the route's name by default. */
+    id: z.ZodOptional<z.ZodString>;
     contentType: z.ZodOptional<z.ZodEnum<["application/x-www-form-urlencoded", "multipart/form-data", "text/plain"]>>;
     csrf: z.ZodOptional<z.ZodBoolean>;
     session: z.ZodOptional<z.ZodObject<{
@@ -466,6 +514,7 @@ export declare const routeFormSchema: z.ZodObject<{
         }[] | undefined;
     }>>;
 }, "strict", z.ZodTypeAny, {
+    id?: string | undefined;
     contentType?: "application/x-www-form-urlencoded" | "multipart/form-data" | "text/plain" | undefined;
     csrf?: boolean | undefined;
     session?: {
@@ -482,6 +531,7 @@ export declare const routeFormSchema: z.ZodObject<{
         }[] | undefined;
     } | undefined;
 }, {
+    id?: string | undefined;
     contentType?: "application/x-www-form-urlencoded" | "multipart/form-data" | "text/plain" | undefined;
     csrf?: boolean | undefined;
     session?: {
@@ -1603,8 +1653,14 @@ export declare const routeDefinitionSchema: z.ZodObject<{
         mode?: "optional" | "required" | undefined;
         write?: boolean | undefined;
     }>>;
-    /** `required`: only a signed-in user reaches the route; others are sent to sign in. */
-    auth: z.ZodOptional<z.ZodEnum<["required"]>>;
+    /** Who reaches the route: see `accessRequirementSchema`. */
+    auth: z.ZodOptional<z.ZodUnion<[z.ZodLiteral<"required">, z.ZodObject<{
+        role: z.ZodString;
+    }, "strict", z.ZodTypeAny, {
+        role: string;
+    }, {
+        role: string;
+    }>]>>;
     flash: z.ZodOptional<z.ZodObject<{
         consume: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
         publish: z.ZodOptional<z.ZodArray<z.ZodObject<{
@@ -1641,6 +1697,8 @@ export declare const routeDefinitionSchema: z.ZodObject<{
         }[] | undefined;
     }>>;
     form: z.ZodOptional<z.ZodObject<{
+        /** The form's id, which the page's loader reads its state by; the route's name by default. */
+        id: z.ZodOptional<z.ZodString>;
         contentType: z.ZodOptional<z.ZodEnum<["application/x-www-form-urlencoded", "multipart/form-data", "text/plain"]>>;
         csrf: z.ZodOptional<z.ZodBoolean>;
         session: z.ZodOptional<z.ZodObject<{
@@ -1689,6 +1747,7 @@ export declare const routeDefinitionSchema: z.ZodObject<{
             }[] | undefined;
         }>>;
     }, "strict", z.ZodTypeAny, {
+        id?: string | undefined;
         contentType?: "application/x-www-form-urlencoded" | "multipart/form-data" | "text/plain" | undefined;
         csrf?: boolean | undefined;
         session?: {
@@ -1705,6 +1764,7 @@ export declare const routeDefinitionSchema: z.ZodObject<{
             }[] | undefined;
         } | undefined;
     }, {
+        id?: string | undefined;
         contentType?: "application/x-www-form-urlencoded" | "multipart/form-data" | "text/plain" | undefined;
         csrf?: boolean | undefined;
         session?: {
@@ -2308,7 +2368,9 @@ export declare const routeDefinitionSchema: z.ZodObject<{
         mode?: "optional" | "required" | undefined;
         write?: boolean | undefined;
     } | undefined;
-    auth?: "required" | undefined;
+    auth?: "required" | {
+        role: string;
+    } | undefined;
     flash?: {
         consume?: string[] | undefined;
         publish?: {
@@ -2319,6 +2381,7 @@ export declare const routeDefinitionSchema: z.ZodObject<{
         }[] | undefined;
     } | undefined;
     form?: {
+        id?: string | undefined;
         contentType?: "application/x-www-form-urlencoded" | "multipart/form-data" | "text/plain" | undefined;
         csrf?: boolean | undefined;
         session?: {
@@ -2472,7 +2535,9 @@ export declare const routeDefinitionSchema: z.ZodObject<{
         mode?: "optional" | "required" | undefined;
         write?: boolean | undefined;
     } | undefined;
-    auth?: "required" | undefined;
+    auth?: "required" | {
+        role: string;
+    } | undefined;
     flash?: {
         consume?: string[] | undefined;
         publish?: {
@@ -2483,6 +2548,7 @@ export declare const routeDefinitionSchema: z.ZodObject<{
         }[] | undefined;
     } | undefined;
     form?: {
+        id?: string | undefined;
         contentType?: "application/x-www-form-urlencoded" | "multipart/form-data" | "text/plain" | undefined;
         csrf?: boolean | undefined;
         session?: {
@@ -2703,8 +2769,14 @@ export declare const viewDefinitionSchema: z.ZodObject<{
     summary: z.ZodOptional<z.ZodString>;
     description: z.ZodOptional<z.ZodString>;
     tags: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
-    /** `required`: only a signed-in user sees the page; others are sent to sign in. */
-    auth: z.ZodOptional<z.ZodEnum<["required"]>>;
+    /** Who sees the page: see `accessRequirementSchema`. */
+    auth: z.ZodOptional<z.ZodUnion<[z.ZodLiteral<"required">, z.ZodObject<{
+        role: z.ZodString;
+    }, "strict", z.ZodTypeAny, {
+        role: string;
+    }, {
+        role: string;
+    }>]>>;
     params: z.ZodOptional<z.ZodObject<{
         kind: z.ZodDefault<z.ZodEnum<["zod", "json-schema", "ts-rest"]>>;
         name: z.ZodString;
@@ -2747,7 +2819,9 @@ export declare const viewDefinitionSchema: z.ZodObject<{
     summary?: string | undefined;
     description?: string | undefined;
     tags?: string[] | undefined;
-    auth?: "required" | undefined;
+    auth?: "required" | {
+        role: string;
+    } | undefined;
     params?: {
         kind: "json-schema" | "ts-rest" | "zod";
         name: string;
@@ -2770,7 +2844,9 @@ export declare const viewDefinitionSchema: z.ZodObject<{
     summary?: string | undefined;
     description?: string | undefined;
     tags?: string[] | undefined;
-    auth?: "required" | undefined;
+    auth?: "required" | {
+        role: string;
+    } | undefined;
     params?: {
         kind?: "json-schema" | "ts-rest" | "zod" | undefined;
         name: string;
@@ -2791,7 +2867,9 @@ export type ViewDefinition = z.infer<typeof viewDefinitionSchema>;
 export type ViewLoaderContext<TContext extends SSRContext, TParams extends z.ZodTypeAny | undefined> = TContext & {
     readonly params: InferOrNever<TParams>;
 };
-export type ViewLoader<TContext extends SSRContext, TParams extends z.ZodTypeAny | undefined, TData extends z.ZodTypeAny> = (context: ViewLoaderContext<TContext, TParams>) => Promise<z.infer<TData>> | z.infer<TData>;
+/** What a loader returns: the page's data, less the `flash` the framework adds. */
+export type ViewLoaderData<TData extends z.ZodTypeAny> = z.input<TData> extends Record<string, unknown> ? Omit<z.input<TData>, 'flash'> : z.input<TData>;
+export type ViewLoader<TContext extends SSRContext, TParams extends z.ZodTypeAny | undefined, TData extends z.ZodTypeAny> = (context: ViewLoaderContext<TContext, TParams>) => Promise<ViewLoaderData<TData>> | ViewLoaderData<TData>;
 export interface ViewSpec<TContext extends SSRContext = SSRContext, TParams extends z.ZodTypeAny | undefined = undefined, TData extends z.ZodTypeAny = z.ZodTypeAny> {
     readonly definition: ViewDefinition;
     readonly params?: TParams;
@@ -2912,8 +2990,14 @@ export declare const moduleManifestSchema: z.ZodObject<{
             mode?: "optional" | "required" | undefined;
             write?: boolean | undefined;
         }>>;
-        /** `required`: only a signed-in user reaches the route; others are sent to sign in. */
-        auth: z.ZodOptional<z.ZodEnum<["required"]>>;
+        /** Who reaches the route: see `accessRequirementSchema`. */
+        auth: z.ZodOptional<z.ZodUnion<[z.ZodLiteral<"required">, z.ZodObject<{
+            role: z.ZodString;
+        }, "strict", z.ZodTypeAny, {
+            role: string;
+        }, {
+            role: string;
+        }>]>>;
         flash: z.ZodOptional<z.ZodObject<{
             consume: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
             publish: z.ZodOptional<z.ZodArray<z.ZodObject<{
@@ -2950,6 +3034,8 @@ export declare const moduleManifestSchema: z.ZodObject<{
             }[] | undefined;
         }>>;
         form: z.ZodOptional<z.ZodObject<{
+            /** The form's id, which the page's loader reads its state by; the route's name by default. */
+            id: z.ZodOptional<z.ZodString>;
             contentType: z.ZodOptional<z.ZodEnum<["application/x-www-form-urlencoded", "multipart/form-data", "text/plain"]>>;
             csrf: z.ZodOptional<z.ZodBoolean>;
             session: z.ZodOptional<z.ZodObject<{
@@ -2998,6 +3084,7 @@ export declare const moduleManifestSchema: z.ZodObject<{
                 }[] | undefined;
             }>>;
         }, "strict", z.ZodTypeAny, {
+            id?: string | undefined;
             contentType?: "application/x-www-form-urlencoded" | "multipart/form-data" | "text/plain" | undefined;
             csrf?: boolean | undefined;
             session?: {
@@ -3014,6 +3101,7 @@ export declare const moduleManifestSchema: z.ZodObject<{
                 }[] | undefined;
             } | undefined;
         }, {
+            id?: string | undefined;
             contentType?: "application/x-www-form-urlencoded" | "multipart/form-data" | "text/plain" | undefined;
             csrf?: boolean | undefined;
             session?: {
@@ -3617,7 +3705,9 @@ export declare const moduleManifestSchema: z.ZodObject<{
             mode?: "optional" | "required" | undefined;
             write?: boolean | undefined;
         } | undefined;
-        auth?: "required" | undefined;
+        auth?: "required" | {
+            role: string;
+        } | undefined;
         flash?: {
             consume?: string[] | undefined;
             publish?: {
@@ -3628,6 +3718,7 @@ export declare const moduleManifestSchema: z.ZodObject<{
             }[] | undefined;
         } | undefined;
         form?: {
+            id?: string | undefined;
             contentType?: "application/x-www-form-urlencoded" | "multipart/form-data" | "text/plain" | undefined;
             csrf?: boolean | undefined;
             session?: {
@@ -3781,7 +3872,9 @@ export declare const moduleManifestSchema: z.ZodObject<{
             mode?: "optional" | "required" | undefined;
             write?: boolean | undefined;
         } | undefined;
-        auth?: "required" | undefined;
+        auth?: "required" | {
+            role: string;
+        } | undefined;
         flash?: {
             consume?: string[] | undefined;
             publish?: {
@@ -3792,6 +3885,7 @@ export declare const moduleManifestSchema: z.ZodObject<{
             }[] | undefined;
         } | undefined;
         form?: {
+            id?: string | undefined;
             contentType?: "application/x-www-form-urlencoded" | "multipart/form-data" | "text/plain" | undefined;
             csrf?: boolean | undefined;
             session?: {
@@ -3938,8 +4032,14 @@ export declare const moduleManifestSchema: z.ZodObject<{
         summary: z.ZodOptional<z.ZodString>;
         description: z.ZodOptional<z.ZodString>;
         tags: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
-        /** `required`: only a signed-in user sees the page; others are sent to sign in. */
-        auth: z.ZodOptional<z.ZodEnum<["required"]>>;
+        /** Who sees the page: see `accessRequirementSchema`. */
+        auth: z.ZodOptional<z.ZodUnion<[z.ZodLiteral<"required">, z.ZodObject<{
+            role: z.ZodString;
+        }, "strict", z.ZodTypeAny, {
+            role: string;
+        }, {
+            role: string;
+        }>]>>;
         params: z.ZodOptional<z.ZodObject<{
             kind: z.ZodDefault<z.ZodEnum<["zod", "json-schema", "ts-rest"]>>;
             name: z.ZodString;
@@ -3982,7 +4082,9 @@ export declare const moduleManifestSchema: z.ZodObject<{
         summary?: string | undefined;
         description?: string | undefined;
         tags?: string[] | undefined;
-        auth?: "required" | undefined;
+        auth?: "required" | {
+            role: string;
+        } | undefined;
         params?: {
             kind: "json-schema" | "ts-rest" | "zod";
             name: string;
@@ -4005,7 +4107,9 @@ export declare const moduleManifestSchema: z.ZodObject<{
         summary?: string | undefined;
         description?: string | undefined;
         tags?: string[] | undefined;
-        auth?: "required" | undefined;
+        auth?: "required" | {
+            role: string;
+        } | undefined;
         params?: {
             kind?: "json-schema" | "ts-rest" | "zod" | undefined;
             name: string;
@@ -4112,7 +4216,9 @@ export declare const moduleManifestSchema: z.ZodObject<{
             mode?: "optional" | "required" | undefined;
             write?: boolean | undefined;
         } | undefined;
-        auth?: "required" | undefined;
+        auth?: "required" | {
+            role: string;
+        } | undefined;
         flash?: {
             consume?: string[] | undefined;
             publish?: {
@@ -4123,6 +4229,7 @@ export declare const moduleManifestSchema: z.ZodObject<{
             }[] | undefined;
         } | undefined;
         form?: {
+            id?: string | undefined;
             contentType?: "application/x-www-form-urlencoded" | "multipart/form-data" | "text/plain" | undefined;
             csrf?: boolean | undefined;
             session?: {
@@ -4269,7 +4376,9 @@ export declare const moduleManifestSchema: z.ZodObject<{
         summary?: string | undefined;
         description?: string | undefined;
         tags?: string[] | undefined;
-        auth?: "required" | undefined;
+        auth?: "required" | {
+            role: string;
+        } | undefined;
         params?: {
             kind: "json-schema" | "ts-rest" | "zod";
             name: string;
@@ -4336,7 +4445,9 @@ export declare const moduleManifestSchema: z.ZodObject<{
             mode?: "optional" | "required" | undefined;
             write?: boolean | undefined;
         } | undefined;
-        auth?: "required" | undefined;
+        auth?: "required" | {
+            role: string;
+        } | undefined;
         flash?: {
             consume?: string[] | undefined;
             publish?: {
@@ -4347,6 +4458,7 @@ export declare const moduleManifestSchema: z.ZodObject<{
             }[] | undefined;
         } | undefined;
         form?: {
+            id?: string | undefined;
             contentType?: "application/x-www-form-urlencoded" | "multipart/form-data" | "text/plain" | undefined;
             csrf?: boolean | undefined;
             session?: {
@@ -4493,7 +4605,9 @@ export declare const moduleManifestSchema: z.ZodObject<{
         summary?: string | undefined;
         description?: string | undefined;
         tags?: string[] | undefined;
-        auth?: "required" | undefined;
+        auth?: "required" | {
+            role: string;
+        } | undefined;
         params?: {
             kind?: "json-schema" | "ts-rest" | "zod" | undefined;
             name: string;
@@ -4567,6 +4681,6 @@ export { fromTsRestRoute, fromTsRestRouter } from './adapters/ts-rest.js';
 export type { FromTsRestRouteOptions, FromTsRestRouterOptions, RouterRouteConfig, } from './adapters/ts-rest.js';
 export { RENDER_PROGRAM_FILE, RENDER_PROGRAM_VERSION, renderFlashMessageSchema, renderFlashSchema, renderNodeSchema, renderPathSchema, renderProgramSchema, renderSourceLocationSchema, } from './render-program.js';
 export type { RenderFlashMessage, RenderNode, RenderPath, RenderProgram, RenderSourceLocation, } from './render-program.js';
-export { executeRenderProgram, programUsesCsrf, readRenderProgram, RENDER_CSRF_FIELD, RenderProgramError, prepareViewData, schemaDeclaresField, } from './render-execute.js';
+export { executeRenderProgram, programUsesCsrf, readRenderProgram, RENDER_CSRF_FIELD, RenderProgramError, prepareViewData, schemaDeclaresField, withShellData, } from './render-execute.js';
 export type { ExecuteRenderProgramOptions, PreparedViewData } from './render-execute.js';
-export { CLIENT_NAV_HEADERS, CLIENT_NAV_SUBMISSION_FIELD } from './client-nav.js';
+export { CLIENT_NAV_HEADERS, CLIENT_NAV_SUBMISSION_FIELD, FORM_ID_FIELD, FORM_PAGE_FIELD, } from './client-nav.js';

package/dist/index.js

@@ -4,6 +4,35 @@ export const CONTRACT_VERSION = '1.0.0';
 export const contractVersionLiteral = z.literal(CONTRACT_VERSION);
 export const moduleKindSchema = z.enum(['frontend', 'backend']);
 export const logLevelSchema = z.enum(['trace', 'debug', 'info', 'warn', 'error', 'fatal']);
+/**
+ * What a page binds for one form: whether it came back from a failed submission, what was typed in
+ * each field, and the first error per field (and `form`, for errors about the whole form).
+ */
+export function formStateSchema(fields) {
+    const strings = (names) => z.object(Object.fromEntries(names.map((name) => [name, z.string().optional()])));
+    return z.object({
+        submitted: z.boolean(),
+        values: strings(fields),
+        errors: strings([...fields, 'form']),
+    });
+}
+/** A form's state as `formStateSchema(fields)` binds it, with `defaults` for a fresh form. */
+export function formView(state, fields, defaults = {}) {
+    const values = {};
+    const errors = {};
+    for (const field of fields) {
+        const value = state.values[field];
+        const typed = typeof value === 'string' ? value : Array.isArray(value) ? value[0] : undefined;
+        const shown = state.submitted ? typed : defaults[field];
+        if (shown !== undefined)
+            values[field] = shown;
+        if (state.errors[field])
+            errors[field] = state.errors[field];
+    }
+    if (state.errors.form)
+        errors.form = state.errors.form;
+    return { submitted: state.submitted, values, errors };
+}
 export const moduleErrorCodeSchema = z.enum([
     'validation',
     'auth',
@@ -19,6 +48,14 @@ export const moduleErrorSchema = z.object({
     cause: z.unknown().optional(),
     correlationId: z.string().optional(),
 });
+/**
+ * Who reaches a route or view: `'required'` is anyone signed in; `{ role }` is someone signed in
+ * whose user has that role. Others are sent to sign in; signed in without the role is a 404.
+ */
+export const accessRequirementSchema = z.union([
+    z.literal('required'),
+    z.object({ role: z.string().min(1) }).strict(),
+]);
 export const httpMethodSchema = z.enum([
     'GET',
     'HEAD',
@@ -79,6 +116,8 @@ export const routeSessionSchema = z
 })
     .strict();
 export const flashLevelSchema = z.enum(['info', 'success', 'warning', 'error']);
+/** What a page binds as `flash`: the messages an action left for it. The framework supplies it. */
+export const flashSchema = z.array(z.object({ level: flashLevelSchema, message: z.string() }));
 export const flashPublishConditionSchema = z.enum(['always', 'success', 'error']);
 export const routeFlashMessageSchema = z
     .object({
@@ -96,6 +135,8 @@ export const routeFlashSchema = z
     .strict();
 export const routeFormSchema = z
     .object({
+    /** The form's id, which the page's loader reads its state by; the route's name by default. */
+    id: z.string().min(1).optional(),
     contentType: formEncodingSchema.optional(),
     csrf: z.boolean().optional(),
     session: routeSessionSchema.optional(),
@@ -159,8 +200,8 @@ export const routeDefinitionSchema = z.object({
     interaction: routeInteractionKindSchema.optional(),
     requestHooks: z.array(requestHookReferenceSchema).optional(),
     session: routeSessionSchema.optional(),
-    /** `required`: only a signed-in user reaches the route; others are sent to sign in. */
-    auth: z.enum(['required']).optional(),
+    /** Who reaches the route: see `accessRequirementSchema`. */
+    auth: accessRequirementSchema.optional(),
     flash: routeFlashSchema.optional(),
     form: routeFormSchema.optional(),
     fragment: routeFragmentSchema.optional(),
@@ -182,8 +223,8 @@ export const viewDefinitionSchema = z.object({
     summary: z.string().optional(),
     description: z.string().optional(),
     tags: z.array(z.string()).optional(),
-    /** `required`: only a signed-in user sees the page; others are sent to sign in. */
-    auth: z.enum(['required']).optional(),
+    /** Who sees the page: see `accessRequirementSchema`. */
+    auth: accessRequirementSchema.optional(),
     params: schemaReferenceSchema.optional(),
     data: schemaReferenceSchema.optional(),
     renderMode: z.enum(['ssg', 'ssr', 'spa']).optional(),
@@ -237,5 +278,5 @@ export function createModule(definition) {
 }
 export { fromTsRestRoute, fromTsRestRouter } from './adapters/ts-rest.js';
 export { RENDER_PROGRAM_FILE, RENDER_PROGRAM_VERSION, renderFlashMessageSchema, renderFlashSchema, renderNodeSchema, renderPathSchema, renderProgramSchema, renderSourceLocationSchema, } from './render-program.js';
-export { executeRenderProgram, programUsesCsrf, readRenderProgram, RENDER_CSRF_FIELD, RenderProgramError, prepareViewData, schemaDeclaresField, } from './render-execute.js';
-export { CLIENT_NAV_HEADERS, CLIENT_NAV_SUBMISSION_FIELD } from './client-nav.js';
+export { executeRenderProgram, programUsesCsrf, readRenderProgram, RENDER_CSRF_FIELD, RenderProgramError, prepareViewData, schemaDeclaresField, withShellData, } from './render-execute.js';
+export { CLIENT_NAV_HEADERS, CLIENT_NAV_SUBMISSION_FIELD, FORM_ID_FIELD, FORM_PAGE_FIELD, } from './client-nav.js';

package/dist/render-execute.d.ts

@@ -10,6 +10,13 @@ export interface ExecuteRenderProgramOptions {
      * POST forms render without a token field.
      */
     readonly csrfToken?: string | false;
+    /**
+     * A new id for each POST form rendered, so the same submission sent again (a resent post, a
+     * double click) is answered once. Left out, forms render without one.
+     */
+    readonly submissionId?: () => string;
+    /** The page's own address, rendered into each POST form so a failure returns to it. */
+    readonly pagePath?: string;
 }
 export declare function readRenderProgram(value: unknown, source: string): RenderProgram;
 export declare function programUsesCsrf(program: RenderProgram): boolean;
@@ -28,6 +35,11 @@ export type PreparedViewData = {
  * failing that, without it, starting with what the schema declares.
  */
 export declare function prepareViewData(schema: unknown, loaded: unknown, flash: readonly unknown[]): PreparedViewData;
+/**
+ * A page's data with the app's shell data beside it as `shell`, checked against the shell's schema
+ * when it has one.
+ */
+export declare function withShellData(data: unknown, shellSchema: unknown, loaded: unknown): PreparedViewData;
 /**
  * Whether a zod-style schema's underlying object declares `field`, looking through wrappers
  * such as optional, default, refine and transform, and into unions and intersections. A schema

package/dist/render-execute.js

@@ -1,3 +1,4 @@
+import { CLIENT_NAV_SUBMISSION_FIELD, FORM_PAGE_FIELD } from './client-nav.js';
 import { RENDER_PROGRAM_VERSION } from './render-version.js';
 export const RENDER_CSRF_FIELD = '_csrf';
 const SAFE_URL_SCHEMES = new Set(['http', 'https', 'mailto', 'tel']);
@@ -63,6 +64,12 @@ function run(nodes, data, scopes, options, out) {
                     throw new Error('A POST form needs a CSRF token, but none was supplied.');
                 }
                 out.push(`<input type="hidden" name="${RENDER_CSRF_FIELD}" value="${escapeAttribute(options.csrfToken)}">`);
+                if (options.submissionId) {
+                    out.push(`<input type="hidden" name="${CLIENT_NAV_SUBMISSION_FIELD}" value="${escapeAttribute(options.submissionId())}">`);
+                }
+                if (options.pagePath) {
+                    out.push(`<input type="hidden" name="${FORM_PAGE_FIELD}" value="${escapeAttribute(options.pagePath)}">`);
+                }
                 break;
             case 'text': {
                 const value = read(node.path, data, scopes);
@@ -194,6 +201,22 @@ export function prepareViewData(schema, loaded, flash) {
     }
     return { ok: false, error: describeSchemaError(firstError) };
 }
+/**
+ * A page's data with the app's shell data beside it as `shell`, checked against the shell's schema
+ * when it has one.
+ */
+export function withShellData(data, shellSchema, loaded) {
+    if (!isPlainObject(data)) {
+        return { ok: true, data };
+    }
+    if (!shellSchema || typeof shellSchema.safeParse !== 'function') {
+        return { ok: true, data: { ...data, shell: loaded } };
+    }
+    const parsed = shellSchema.safeParse(loaded);
+    return parsed.success
+        ? { ok: true, data: { ...data, shell: parsed.data } }
+        : { ok: false, error: describeSchemaError(parsed.error) };
+}
 function mergeFlash(value, flash) {
     if (!isPlainObject(value)) {
         return value;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@webstir-io/module-contract",
-  "version": "0.8.1",
+  "version": "0.9.1",
   "description": "Public contract definitions for Webstir frontend and backend module providers.",
   "type": "module",
   "main": "dist/index.js",

package/schema/module-manifest.schema.json

@@ -147,9 +147,24 @@
                 "additionalProperties": false
               },
               "auth": {
-                "type": "string",
-                "enum": [
-                  "required"
+                "anyOf": [
+                  {
+                    "type": "string",
+                    "const": "required"
+                  },
+                  {
+                    "type": "object",
+                    "properties": {
+                      "role": {
+                        "type": "string",
+                        "minLength": 1
+                      }
+                    },
+                    "required": [
+                      "role"
+                    ],
+                    "additionalProperties": false
+                  }
                 ]
               },
               "flash": {
@@ -205,6 +220,10 @@
               "form": {
                 "type": "object",
                 "properties": {
+                  "id": {
+                    "type": "string",
+                    "minLength": 1
+                  },
                   "contentType": {
                     "type": "string",
                     "enum": [
@@ -486,10 +505,7 @@
                 }
               },
               "auth": {
-                "type": "string",
-                "enum": [
-                  "required"
-                ]
+                "$ref": "#/definitions/module-manifest/properties/routes/items/properties/auth"
               },
               "params": {
                 "$ref": "#/definitions/module-manifest/properties/routes/items/properties/input/properties/params"

package/schema/route-definition.schema.json

@@ -76,9 +76,24 @@
           "additionalProperties": false
         },
         "auth": {
-          "type": "string",
-          "enum": [
-            "required"
+          "anyOf": [
+            {
+              "type": "string",
+              "const": "required"
+            },
+            {
+              "type": "object",
+              "properties": {
+                "role": {
+                  "type": "string",
+                  "minLength": 1
+                }
+              },
+              "required": [
+                "role"
+              ],
+              "additionalProperties": false
+            }
           ]
         },
         "flash": {
@@ -134,6 +149,10 @@
         "form": {
           "type": "object",
           "properties": {
+            "id": {
+              "type": "string",
+              "minLength": 1
+            },
             "contentType": {
               "type": "string",
               "enum": [

package/schema/view-definition.schema.json

@@ -29,9 +29,24 @@
           }
         },
         "auth": {
-          "type": "string",
-          "enum": [
-            "required"
+          "anyOf": [
+            {
+              "type": "string",
+              "const": "required"
+            },
+            {
+              "type": "object",
+              "properties": {
+                "role": {
+                  "type": "string",
+                  "minLength": 1
+                }
+              },
+              "required": [
+                "role"
+              ],
+              "additionalProperties": false
+            }
           ]
         },
         "params": {