@appsemble/lang-sdk 0.37.6 → 0.38.1

package/gridUtils.d.ts

@@ -0,0 +1,63 @@
+import { type GridLayoutDefinition, type PageDefinition, type PageLayoutDefinition, type ResponsiveGridLayoutDefinition } from './types/index.js';
+/**
+ * The template area a page grid layout uses to place the breadcrumb trail.
+ */
+export declare const breadcrumbsGridArea = "breadcrumbs";
+/**
+ * The devices a responsive grid layout is defined for, from the smallest breakpoint up.
+ */
+export declare const gridDeviceOrder: readonly ["mobile", "tablet", "desktop"];
+/**
+ * One of the devices a responsive grid layout is defined for.
+ */
+export type GridDeviceName = (typeof gridDeviceOrder)[number];
+/**
+ * The grid a device falls back to when neither it nor a smaller device defines one.
+ */
+export declare const defaultGridLayout: Readonly<GridLayoutDefinition>;
+/**
+ * Collect the template areas a responsive grid layout defines.
+ *
+ * @param layoutDefinition The responsive grid layout to read.
+ * @returns Every area named by the template of any device layout, without the `.` placeholder.
+ */
+export declare function getGridTemplateAreas(layoutDefinition: ResponsiveGridLayoutDefinition | undefined): Set<string>;
+/**
+ * Collect the grid layouts of a page, in definition order.
+ *
+ * A page type that splits its content over sub pages defines a grid per sub page, so a tab, a step
+ * or a loop sub page each carry their own. A basic page has a single grid, and a container page has
+ * none of its own.
+ *
+ * @param page The page to read the grid layouts of.
+ * @returns The layout of every sub page the page renders, which is undefined where none is defined.
+ */
+export declare function getPageGridLayouts(page: PageDefinition): (PageLayoutDefinition | undefined)[];
+/**
+ * Collect the template areas each device renders.
+ *
+ * A device that defines no template of its own inherits the one of the next smaller device, the way
+ * the app applies the grid of a page, down to a fallback of the single `main` area. So the areas a
+ * device renders are not the areas its own template names.
+ *
+ * @param layout The responsive grid layout to read.
+ * @returns The areas rendered by each device, keyed by device name.
+ */
+export declare function getCascadedGridTemplateAreas(layout: ResponsiveGridLayoutDefinition | undefined): Record<GridDeviceName, Set<string>>;
+/**
+ * Check whether a grid layout places the breadcrumb trail.
+ *
+ * Every device has to render the area, since a device that does not would place the trail against
+ * implicit grid lines rather than inside the layout.
+ *
+ * @param layout The responsive grid layout to check.
+ * @returns Whether every device renders the breadcrumbs template area.
+ */
+export declare function hasBreadcrumbsGridArea(layout: PageLayoutDefinition | undefined): boolean;
+/**
+ * Check whether a page renders the breadcrumb trail from a grid layout.
+ *
+ * @param page The page to check the grid layouts of.
+ * @returns Whether any grid layout of the page places the breadcrumb trail.
+ */
+export declare function pageHasBreadcrumbsGridArea(page: PageDefinition): boolean;

package/gridUtils.js

@@ -0,0 +1,114 @@
+/**
+ * The template area a page grid layout uses to place the breadcrumb trail.
+ */
+export const breadcrumbsGridArea = 'breadcrumbs';
+/**
+ * The devices a responsive grid layout is defined for, from the smallest breakpoint up.
+ */
+export const gridDeviceOrder = ['mobile', 'tablet', 'desktop'];
+/**
+ * The grid a device falls back to when neither it nor a smaller device defines one.
+ */
+export const defaultGridLayout = {
+    columns: 1,
+    template: ['main'],
+};
+function getTemplateAreas(template) {
+    const areas = new Set();
+    for (const row of template) {
+        for (const area of row.split(' ')) {
+            if (area && area !== '.') {
+                areas.add(area);
+            }
+        }
+    }
+    return areas;
+}
+/**
+ * Collect the template areas a responsive grid layout defines.
+ *
+ * @param layoutDefinition The responsive grid layout to read.
+ * @returns Every area named by the template of any device layout, without the `.` placeholder.
+ */
+export function getGridTemplateAreas(layoutDefinition) {
+    const areas = new Set();
+    if (!layoutDefinition) {
+        return areas;
+    }
+    for (const deviceDefinition of Object.values(layoutDefinition)) {
+        for (const area of getTemplateAreas(deviceDefinition?.layout?.template ?? [])) {
+            areas.add(area);
+        }
+    }
+    return areas;
+}
+/**
+ * Collect the grid layouts of a page, in definition order.
+ *
+ * A page type that splits its content over sub pages defines a grid per sub page, so a tab, a step
+ * or a loop sub page each carry their own. A basic page has a single grid, and a container page has
+ * none of its own.
+ *
+ * @param page The page to read the grid layouts of.
+ * @returns The layout of every sub page the page renders, which is undefined where none is defined.
+ */
+export function getPageGridLayouts(page) {
+    switch (page.type) {
+        case 'container':
+            return [];
+        case 'flow':
+            return page.steps.map((step) => step.layout);
+        case 'loop':
+            return [page.start, page.foreach, page.end].flatMap((subPage) => subPage ? [subPage.layout] : []);
+        case 'tabs':
+            return page.tabs
+                ? page.tabs.map((tab) => tab.layout)
+                : page.definition
+                    ? [page.definition.foreach.layout]
+                    : [];
+        default:
+            return [page.layout];
+    }
+}
+/**
+ * Collect the template areas each device renders.
+ *
+ * A device that defines no template of its own inherits the one of the next smaller device, the way
+ * the app applies the grid of a page, down to a fallback of the single `main` area. So the areas a
+ * device renders are not the areas its own template names.
+ *
+ * @param layout The responsive grid layout to read.
+ * @returns The areas rendered by each device, keyed by device name.
+ */
+export function getCascadedGridTemplateAreas(layout) {
+    let { template } = defaultGridLayout;
+    return Object.fromEntries(gridDeviceOrder.map((device) => {
+        template = layout?.[device]?.layout?.template ?? template;
+        return [device, getTemplateAreas(template)];
+    }));
+}
+/**
+ * Check whether a grid layout places the breadcrumb trail.
+ *
+ * Every device has to render the area, since a device that does not would place the trail against
+ * implicit grid lines rather than inside the layout.
+ *
+ * @param layout The responsive grid layout to check.
+ * @returns Whether every device renders the breadcrumbs template area.
+ */
+export function hasBreadcrumbsGridArea(layout) {
+    if (!layout) {
+        return false;
+    }
+    return Object.values(getCascadedGridTemplateAreas(layout)).every((areas) => areas.has(breadcrumbsGridArea));
+}
+/**
+ * Check whether a page renders the breadcrumb trail from a grid layout.
+ *
+ * @param page The page to check the grid layouts of.
+ * @returns Whether any grid layout of the page places the breadcrumb trail.
+ */
+export function pageHasBreadcrumbsGridArea(page) {
+    return getPageGridLayouts(page).some(hasBreadcrumbsGridArea);
+}
+//# sourceMappingURL=gridUtils.js.map

package/index.d.ts

@@ -6,6 +6,7 @@ export * from './authorization.js';
 export * from './blockUtils.js';
 export * from './validation.js';
 export * from './findPageByName.js';
+export * from './gridUtils.js';
 export * from './pageUtils.js';
 export * from './iterApp.js';
 export * from './serverActions.js';

package/index.js

@@ -6,6 +6,7 @@ export * from './authorization.js';
 export * from './blockUtils.js';
 export * from './validation.js';
 export * from './findPageByName.js';
+export * from './gridUtils.js';
 export * from './pageUtils.js';
 export * from './iterApp.js';
 export * from './serverActions.js';

package/iterApp.js

@@ -121,8 +121,13 @@ export function iterPage(page, callbacks, prefix = []) {
         if (result) {
             return true;
         }
-        const { foreach } = page;
-        return ['steps.first', 'steps', 'steps.last'].some((suffix) => iterBlockList(foreach?.blocks ?? [], callbacks, [...prefix, suffix, 'blocks']));
+        const { end, foreach, start } = page;
+        const subPages = [
+            ['steps.first', start ?? foreach],
+            ['steps', foreach],
+            ['steps.last', end ?? foreach],
+        ];
+        return subPages.some(([suffix, subPage]) => iterBlockList(subPage?.blocks ?? [], callbacks, [...prefix, suffix, 'blocks']));
     }
     if (page.type === 'container') {
         let result = false;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@appsemble/lang-sdk",
-  "version": "0.37.6",
+  "version": "0.38.1",
   "description": "Language SDK for Appsemble",
   "keywords": [
     "app",
@@ -58,7 +58,7 @@
   "devDependencies": {
     "@types/language-tags": "1.0.4",
     "@types/lcm": "0.0.2",
-    "vitest": "4.1.10"
+    "vitest": "4.1.11"
   },
   "engines": {
     "node": ">=24"

package/pageUtils.d.ts

@@ -5,4 +5,13 @@ export declare function getPageMessageId(pageName: string): string;
 export declare function getPagePathSegment(page: string | NamedPage): string;
 export declare function getPageDisplayName(page: NamedPage, getAppMessage: MessageGetter): string;
 export declare function findPageById(pages: PageDefinition[], normalizedPageId: string, appMessageIds: string[], getAppMessage: MessageGetter): PageDefinition | null;
+/**
+ * Collect the pages a page sits under, by following `parent` upwards.
+ *
+ * @param pages The pages of the app.
+ * @param page The page to collect the ancestors of.
+ * @param appMemberRoles The roles held by the app member, used to resolve role-scoped parents.
+ * @returns The ancestors, root first, excluding the page itself.
+ */
+export declare function getPageAncestors(pages: PageDefinition[], page: PageDefinition, appMemberRoles?: string[]): PageDefinition[];
 export {};

package/pageUtils.js

@@ -1,3 +1,4 @@
+import { findPageByName } from './findPageByName.js';
 import { normalize } from './normalize.js';
 export function getPageMessageId(pageName) {
     return `pages.${normalize(pageName)}`;
@@ -35,4 +36,44 @@ export function findPageById(pages, normalizedPageId, appMessageIds, getAppMessa
     }
     return null;
 }
+/**
+ * Resolve which parent page applies to a member.
+ *
+ * @param parent The `parent` of a page, in any of its accepted forms.
+ * @param appMemberRoles The roles held by the app member.
+ * @returns The name of the applicable parent page, if any.
+ */
+function resolveParentName(parent, appMemberRoles) {
+    for (const entry of [].concat(parent ?? [])) {
+        if (typeof entry === 'string') {
+            return entry;
+        }
+        if (!entry.roles || entry.roles.some((role) => appMemberRoles.includes(role))) {
+            return entry.page;
+        }
+    }
+}
+/**
+ * Collect the pages a page sits under, by following `parent` upwards.
+ *
+ * @param pages The pages of the app.
+ * @param page The page to collect the ancestors of.
+ * @param appMemberRoles The roles held by the app member, used to resolve role-scoped parents.
+ * @returns The ancestors, root first, excluding the page itself.
+ */
+export function getPageAncestors(pages, page, appMemberRoles = []) {
+    const ancestors = [];
+    const visited = new Set([page.name]);
+    let current = page;
+    for (let parentName = resolveParentName(current.parent, appMemberRoles); parentName; parentName = resolveParentName(current.parent, appMemberRoles)) {
+        const parent = findPageByName(pages, parentName);
+        if (!parent || visited.has(parent.name)) {
+            break;
+        }
+        visited.add(parent.name);
+        ancestors.unshift(parent);
+        current = parent;
+    }
+    return ancestors;
+}
 //# sourceMappingURL=pageUtils.js.map

package/schemas/AppLayoutDefinition.js

@@ -91,6 +91,15 @@ rendered as side navigation.
             type: 'string',
             enum: ['appName', 'pageName'],
         },
+        breadcrumbs: {
+            type: 'boolean',
+            default: false,
+            description: `Whether to display a breadcrumb trail below the title bar.
+
+The trail is built from the \`parent\` of each page. A grid layout that names a \`breadcrumbs\`
+template area renders the trail in that area instead.
+`,
+        },
         hideTitleBar: {
             description: 'Whether to hide the title bar',
             type: 'boolean',
@@ -104,6 +113,20 @@ Only applies when \`navigation\` is set to \`top\`.
             type: 'boolean',
             default: false,
         },
+        navbar: {
+            $ref: '#/components/schemas/NavbarLayoutDefinition',
+            description: `Responsive grid layout for the top navigation header.
+
+Only applies when \`navigation\` is set to \`top\` and cannot be combined with \`stackedHeader\`.
+`,
+        },
+        breakpoints: {
+            $ref: '#/components/schemas/GridBreakpointsDefinition',
+            description: `Minimum viewport widths in pixels at which the tablet and desktop grid layouts apply.
+
+Applies to every responsive grid layout in the app, including pages and the navbar.
+`,
+        },
         hideGroupDropdown: {
             description: `Whether to hide the group dropdown.
 

package/schemas/BasePageDefinition.js

@@ -53,6 +53,25 @@ navigation. Set to \`hidden\` to display no navigational menus at all.
 This will be displayed in the navigation menu.
 `,
         },
+        parent: {
+            description: `The page this page sits under in the breadcrumb hierarchy.
+
+A page name applies to every app member. An entry carrying \`roles\` applies only to members holding
+one of those roles. A list is resolved in order, so the first matching entry wins and an entry
+without \`roles\` acts as the fallback.
+
+A page that declares \`parameters\` cannot be used as a parent, because its URL cannot be resolved
+from another page.
+`,
+            anyOf: [
+                { $ref: '#/components/schemas/PageParentDefinition' },
+                {
+                    type: 'array',
+                    minItems: 1,
+                    items: { $ref: '#/components/schemas/PageParentDefinition' },
+                },
+            ],
+        },
         parameters: {
             type: 'array',
             description: `Page parameters can be used for linking to a page that should display a single resource.

package/schemas/BlockDefinition.js

@@ -91,7 +91,10 @@ The exact meaning of the parameters depends on the block type.
         events: { $ref: '#/components/schemas/EventsDefinition' },
         gridArea: {
             type: 'string',
-            description: 'Grid area defined in the page layout definition',
+            description: `Grid area defined in the page layout definition.
+
+The \`breadcrumbs\` area is reserved for the breadcrumb trail of the app.
+`,
         },
     },
 };

package/schemas/GridBreakpointsDefinition.d.ts

@@ -0,0 +1,2 @@
+import { type OpenAPIV3 } from 'openapi-types';
+export declare const GridBreakpointsDefinition: OpenAPIV3.NonArraySchemaObject;

package/schemas/GridBreakpointsDefinition.js

@@ -0,0 +1,22 @@
+export const GridBreakpointsDefinition = {
+    type: 'object',
+    description: `Minimum viewport widths in pixels at which the tablet and desktop grid layouts apply.
+
+The mobile layout always applies from a width of 0. Each breakpoint must be smaller than the next.
+`,
+    additionalProperties: false,
+    minProperties: 1,
+    properties: {
+        tablet: {
+            type: 'integer',
+            minimum: 0,
+            description: 'Minimum viewport width in pixels at which the tablet grid layout applies.',
+        },
+        desktop: {
+            type: 'integer',
+            minimum: 0,
+            description: 'Minimum viewport width in pixels at which the desktop grid layout applies.',
+        },
+    },
+};
+//# sourceMappingURL=GridBreakpointsDefinition.js.map

package/schemas/GridSpacingDefinition.js

@@ -5,9 +5,9 @@ export const GridSpacingDefinition = {
     properties: {
         unit: {
             type: 'string',
-            description: 'CSS unit for spacing calculations (e.g., "1rem", "8px")',
+            description: 'CSS unit or custom property for spacing calculations (e.g., "1rem", "8px", "var(--grid-unit)")',
             default: '1rem',
-            pattern: '^-?(\\d+\\.?\\d*|\\.\\d+)(rem|em|px|%|vh|vw|vmin|vmax|ch|ex|cm|mm|in|pt|pc)$',
+            pattern: '^(?:-?(\\d+\\.?\\d*|\\.\\d+)(rem|em|px|%|vh|vw|vmin|vmax|ch|ex|cm|mm|in|pt|pc)|var\\(--[A-Za-z_][A-Za-z0-9_-]*\\))$',
         },
         gap: {
             type: 'number',

package/schemas/LoopPageDefinition.js

@@ -27,6 +27,14 @@ By default the flow page retains it's data after navigating once. Set to false t
 `,
             default: true,
         },
+        start: {
+            $ref: '#/components/schemas/SubPage',
+            description: 'A page to display before the generated loop pages.',
+        },
+        end: {
+            $ref: '#/components/schemas/SubPage',
+            description: 'A page to display after the generated loop pages.',
+        },
     },
 });
 //# sourceMappingURL=LoopPageDefinition.js.map

package/schemas/NavbarDeviceGridLayoutDefinition.d.ts

@@ -0,0 +1 @@
+export declare const NavbarDeviceGridLayoutDefinition: import("openapi-types").OpenAPIV3.SchemaObject;

package/schemas/NavbarDeviceGridLayoutDefinition.js

@@ -0,0 +1,9 @@
+import { DeviceGridLayoutDefinition } from './DeviceGridLayoutDefinition.js';
+import { extendJSONSchema } from './utils/extendJSONSchema.js';
+export const NavbarDeviceGridLayoutDefinition = extendJSONSchema(DeviceGridLayoutDefinition, {
+    type: 'object',
+    additionalProperties: false,
+    required: ['layout'],
+    description: 'Grid layout definition for a navbar breakpoint',
+});
+//# sourceMappingURL=NavbarDeviceGridLayoutDefinition.js.map

package/schemas/NavbarLayoutDefinition.d.ts

@@ -0,0 +1 @@
+export declare const NavbarLayoutDefinition: import("openapi-types").OpenAPIV3.SchemaObject;

package/schemas/NavbarLayoutDefinition.js

@@ -0,0 +1,24 @@
+import { ResponsiveGridLayoutDefinition } from './ResponsiveGridLayoutDefinition.js';
+import { extendJSONSchema } from './utils/extendJSONSchema.js';
+export const NavbarLayoutDefinition = extendJSONSchema(ResponsiveGridLayoutDefinition, {
+    type: 'object',
+    additionalProperties: false,
+    minProperties: 1,
+    description: `Responsive grid layout for the top navigation header.
+
+The available template areas are logo, name, navigation, and controls.
+Each rendered area must be included and their first visual occurrence must follow that order.
+`,
+    properties: {
+        desktop: {
+            $ref: '#/components/schemas/NavbarDeviceGridLayoutDefinition',
+        },
+        mobile: {
+            $ref: '#/components/schemas/NavbarDeviceGridLayoutDefinition',
+        },
+        tablet: {
+            $ref: '#/components/schemas/NavbarDeviceGridLayoutDefinition',
+        },
+    },
+});
+//# sourceMappingURL=NavbarLayoutDefinition.js.map

package/schemas/PageLayoutDefinition.d.ts

@@ -1,2 +1 @@
-import { type OpenAPIV3 } from 'openapi-types';
-export declare const PageLayoutDefinition: OpenAPIV3.NonArraySchemaObject;
+export declare const PageLayoutDefinition: import("openapi-types").OpenAPIV3.SchemaObject;

package/schemas/PageLayoutDefinition.js

@@ -1,18 +1,14 @@
-export const PageLayoutDefinition = {
+import { ResponsiveGridLayoutDefinition } from './ResponsiveGridLayoutDefinition.js';
+import { extendJSONSchema } from './utils/extendJSONSchema.js';
+export const PageLayoutDefinition = extendJSONSchema(ResponsiveGridLayoutDefinition, {
     type: 'object',
-    description: 'Grid layout of the page, define as an anchor to re-use across multiple pages',
     additionalProperties: false,
     minProperties: 1,
-    properties: {
-        mobile: {
-            $ref: '#/components/schemas/DeviceGridLayoutDefinition',
-        },
-        tablet: {
-            $ref: '#/components/schemas/DeviceGridLayoutDefinition',
-        },
-        desktop: {
-            $ref: '#/components/schemas/DeviceGridLayoutDefinition',
-        },
-    },
-};
+    description: `Responsive grid layout for a page.
+
+The \`breadcrumbs\` template area is reserved for the breadcrumb trail of the app. It requires
+\`layout.breadcrumbs\`, has to be part of the grid every breakpoint renders, and has to be defined by
+every sub page of a page or by none of them.
+`,
+});
 //# sourceMappingURL=PageLayoutDefinition.js.map

package/schemas/PageParentDefinition.d.ts

@@ -0,0 +1,2 @@
+import { type OpenAPIV3 } from 'openapi-types';
+export declare const PageParentDefinition: OpenAPIV3.SchemaObject;

package/schemas/PageParentDefinition.js

@@ -0,0 +1,35 @@
+export const PageParentDefinition = {
+    description: `A candidate parent page, optionally scoped to a set of roles.
+
+A plain string names the parent page. An object scopes that parent to the roles that may use it.
+`,
+    anyOf: [
+        {
+            type: 'string',
+            maxLength: 50,
+            description: 'The name of the parent page.',
+        },
+        {
+            type: 'object',
+            additionalProperties: false,
+            required: ['page'],
+            properties: {
+                page: {
+                    type: 'string',
+                    maxLength: 50,
+                    description: 'The name of the parent page.',
+                },
+                roles: {
+                    type: 'array',
+                    minItems: 1,
+                    items: { type: 'string' },
+                    description: `The roles this parent applies to.
+
+When omitted, the parent applies to every app member.
+`,
+                },
+            },
+        },
+    ],
+};
+//# sourceMappingURL=PageParentDefinition.js.map

package/schemas/ResourceDefinition.js

@@ -100,10 +100,10 @@ name of the resource and how it should behave.
         },
         enforceOrderingGroupByFields: {
             type: 'array',
-            pattern: '^[a-zA-Z0-9]*$',
             description: 'Group resources by fields when handling resource positions',
             items: {
                 type: 'string',
+                pattern: '^[a-zA-Z0-9]*$',
             },
             minItems: 1,
         },

package/schemas/ResponsiveGridLayoutDefinition.d.ts

@@ -0,0 +1,2 @@
+import { type OpenAPIV3 } from 'openapi-types';
+export declare const ResponsiveGridLayoutDefinition: OpenAPIV3.NonArraySchemaObject;

package/schemas/ResponsiveGridLayoutDefinition.js

@@ -0,0 +1,18 @@
+export const ResponsiveGridLayoutDefinition = {
+    type: 'object',
+    description: 'Responsive grid layout',
+    additionalProperties: false,
+    minProperties: 1,
+    properties: {
+        mobile: {
+            $ref: '#/components/schemas/DeviceGridLayoutDefinition',
+        },
+        tablet: {
+            $ref: '#/components/schemas/DeviceGridLayoutDefinition',
+        },
+        desktop: {
+            $ref: '#/components/schemas/DeviceGridLayoutDefinition',
+        },
+    },
+};
+//# sourceMappingURL=ResponsiveGridLayoutDefinition.js.map

package/schemas/index.d.ts

@@ -124,6 +124,11 @@ export * from './TabsPageDefinition.js';
 export * from './Theme.js';
 export * from './WebhookDefinition.js';
 export * from './DeviceGridLayoutDefinition.js';
+export * from './GridBreakpointsDefinition.js';
 export * from './GridLayoutDefinition.js';
 export * from './GridSpacingDefinition.js';
+export * from './ResponsiveGridLayoutDefinition.js';
+export * from './NavbarDeviceGridLayoutDefinition.js';
+export * from './NavbarLayoutDefinition.js';
 export * from './PageLayoutDefinition.js';
+export * from './PageParentDefinition.js';

package/schemas/index.js

@@ -124,7 +124,12 @@ export * from './TabsPageDefinition.js';
 export * from './Theme.js';
 export * from './WebhookDefinition.js';
 export * from './DeviceGridLayoutDefinition.js';
+export * from './GridBreakpointsDefinition.js';
 export * from './GridLayoutDefinition.js';
 export * from './GridSpacingDefinition.js';
+export * from './ResponsiveGridLayoutDefinition.js';
+export * from './NavbarDeviceGridLayoutDefinition.js';
+export * from './NavbarLayoutDefinition.js';
 export * from './PageLayoutDefinition.js';
+export * from './PageParentDefinition.js';
 //# sourceMappingURL=index.js.map

package/types/core.d.ts

@@ -9,7 +9,7 @@ import { type ResourceDefinition } from './resource.js';
 import { type AppRole, type ViewRole } from './roles.js';
 import { type Security } from './security.js';
 import { type Theme } from './theme.js';
-import { type PageLayoutDefinition } from './gridLayout.js';
+import { type GridBreakpointsDefinition, type NavbarLayoutDefinition, type PageLayoutDefinition } from './gridLayout.js';
 export type SettingName = 'email' | 'languages' | 'name' | 'password' | 'phoneNumber' | 'picture';
 export type AppContentSecurityPolicy = Record<string, string[]>;
 export interface AppDefinition {
@@ -108,6 +108,10 @@ export interface AppDefinition {
          *
          */
         titleBarText?: 'appName' | 'pageName';
+        /**
+         * Whether to display a breadcrumb trail below the title bar.
+         */
+        breadcrumbs?: boolean;
         /**
          * Whether to hide the title bar from all pages in the app.
          */
@@ -118,6 +122,24 @@ export interface AppDefinition {
          * Only applies when `navigation` is set to `top`.
          */
         stackedHeader?: boolean;
+        /**
+         * Responsive grid layout for the top navigation header.
+         *
+         * Only applies when `navigation` is set to `top`. This cannot be combined with
+         * `stackedHeader`.
+         *
+         * The available template areas are logo, name, navigation, and controls.
+         * Each rendered area must be included and their first visual occurrence must follow that order.
+         */
+        navbar?: NavbarLayoutDefinition;
+        /**
+         * Minimum viewport widths in pixels at which the tablet and desktop grid layouts apply.
+         *
+         * Applies to every responsive grid layout in the app, including pages and the navbar. The
+         * mobile layout always applies from a width of 0. Each breakpoint must be smaller than the
+         * next.
+         */
+        breakpoints?: GridBreakpointsDefinition;
         /**
          * Whether to hide the group dropdown.
          *
@@ -181,6 +203,13 @@ export interface AppDefinition {
      */
     registry?: string;
 }
+/**
+ * A candidate parent page, optionally scoped to a set of roles.
+ */
+export type PageParentDefinition = string | {
+    page: string;
+    roles?: string[];
+};
 /**
  * This describes what a page will look like in the app.
  */
@@ -215,6 +244,14 @@ export interface BasePageDefinition {
      * top navigation is rendered as side navigation.
      */
     navigation?: Navigation | 'profileDropdown';
+    /**
+     * The page this page sits under in the breadcrumb hierarchy.
+     *
+     * A page name applies to every member. An entry carrying `roles` applies only to members holding
+     * one of them. A list is resolved in order, so the first matching entry wins and an entry without
+     * `roles` acts as the fallback.
+     */
+    parent?: PageParentDefinition | PageParentDefinition[];
     /**
      * A list of roles that may view the page.
      */
@@ -316,6 +353,14 @@ export interface LoopPageDefinition extends BasePageDefinition {
      * @default true
      */
     retainFlowData?: boolean;
+    /**
+     * The page to display before the generated loop pages.
+     */
+    start?: SubPageDefinition;
+    /**
+     * The page to display after the generated loop pages.
+     */
+    end?: SubPageDefinition;
 }
 export interface AlternateTabsDefinition {
     foreach: SubPageDefinition;

package/types/gridLayout.d.ts

@@ -8,12 +8,26 @@ export interface GridLayoutSpacingDefinition {
     padding: number;
     gap: number;
 }
+export interface GridBreakpointsDefinition {
+    tablet?: number;
+    desktop?: number;
+}
 export interface DeviceGridLayoutDefinition {
+    layout?: GridLayoutDefinition;
+    spacing?: GridLayoutSpacingDefinition;
+}
+export interface ResponsiveGridLayoutDefinition {
+    desktop?: DeviceGridLayoutDefinition;
+    mobile?: DeviceGridLayoutDefinition;
+    tablet?: DeviceGridLayoutDefinition;
+}
+export interface NavbarDeviceGridLayoutDefinition extends DeviceGridLayoutDefinition {
     layout: GridLayoutDefinition;
-    spacing: GridLayoutSpacingDefinition;
 }
-export type PageLayoutDefinition = RequireAtLeastOne<{
-    mobile: DeviceGridLayoutDefinition;
-    tablet: DeviceGridLayoutDefinition;
-    desktop: DeviceGridLayoutDefinition;
-}>;
+export interface ResponsiveNavbarGridLayoutDefinition {
+    desktop?: NavbarDeviceGridLayoutDefinition;
+    mobile?: NavbarDeviceGridLayoutDefinition;
+    tablet?: NavbarDeviceGridLayoutDefinition;
+}
+export type NavbarLayoutDefinition = RequireAtLeastOne<ResponsiveNavbarGridLayoutDefinition>;
+export type PageLayoutDefinition = RequireAtLeastOne<ResponsiveGridLayoutDefinition>;

package/validation.js

@@ -6,6 +6,7 @@ import { BlockParamInstanceValidator } from './BasicValidator.js';
 import { getAppBlocks, normalizeBlockName } from './blockUtils.js';
 import { partialNormalized } from './constants/index.js';
 import { findPageByName } from './findPageByName.js';
+import { breadcrumbsGridArea, getCascadedGridTemplateAreas, getGridTemplateAreas, gridDeviceOrder, } from './gridUtils.js';
 import { iterAction, iterApp } from './iterApp.js';
 import { has } from './miscellaneous.js';
 import { normalize } from './normalize.js';
@@ -109,6 +110,70 @@ function validateUniquePageNames(definition, report) {
     }
     checkPages(definition.pages);
 }
+/**
+ * Iterate over the parent entries of every page, including the pages nested in a container.
+ *
+ * `iterApp` gives a nested page the path of the container it sits in, which is too coarse to point
+ * at the `parent` of one page, so the pages are walked here instead.
+ *
+ * @param pages The pages to walk.
+ * @param onParent Called with each parent entry, the path it lives at, and the page declaring it.
+ * @param prefix The path the pages live at.
+ */
+function iterPageParents(pages, onParent, prefix = ['pages']) {
+    for (const [index, page] of pages.entries()) {
+        const pagePath = [...prefix, index];
+        for (const [entryIndex, entry] of []
+            .concat(page.parent ?? [])
+            .entries()) {
+            onParent(entry, Array.isArray(page.parent) ? [...pagePath, 'parent', entryIndex] : [...pagePath, 'parent'], page);
+        }
+        if (page.type === 'container') {
+            iterPageParents(page.pages, onParent, [...pagePath, 'pages']);
+        }
+    }
+}
+function validatePageParents(definition, report) {
+    if (!definition.pages) {
+        return;
+    }
+    // Every declared edge counts, whatever roles it is scoped to: roles overlap, so a cycle reachable
+    // under any role assignment is an authoring mistake.
+    function referencesItself(pageName, parentName) {
+        const visited = new Set();
+        const queue = [parentName];
+        while (queue.length) {
+            const name = queue.shift();
+            if (name === pageName) {
+                return true;
+            }
+            if (visited.has(name)) {
+                continue;
+            }
+            visited.add(name);
+            const parent = findPageByName(definition.pages, name);
+            for (const entry of [].concat(parent?.parent ?? [])) {
+                queue.push(typeof entry === 'string' ? entry : entry.page);
+            }
+        }
+        return false;
+    }
+    iterPageParents(definition.pages, (entry, path, page) => {
+        const parentName = typeof entry === 'string' ? entry : entry.page;
+        const parent = findPageByName(definition.pages, parentName);
+        if (!parent) {
+            report(parentName, 'refers to a page that doesn’t exist', path);
+            return;
+        }
+        if (referencesItself(page.name, parentName)) {
+            report(parentName, 'cyclically references itself', path);
+            return;
+        }
+        if (parent.parameters?.length) {
+            report(parentName, 'refers to a page with parameters, which cannot be used as a parent', path);
+        }
+    });
+}
 function validateMembersSchema(definition, report) {
     if (!definition.members?.properties) {
         return;
@@ -368,24 +433,6 @@ function validateController(definition, controllerImplementations, report) {
         },
     });
 }
-function getTemplateAreas(layoutDefinition) {
-    const areas = new Set();
-    if (!layoutDefinition) {
-        return areas;
-    }
-    for (const deviceDefinition of Object.values(layoutDefinition)) {
-        if (deviceDefinition?.layout?.template) {
-            for (const row of deviceDefinition.layout.template) {
-                for (const area of row.split(' ')) {
-                    if (area && area !== '.') {
-                        areas.add(area);
-                    }
-                }
-            }
-        }
-    }
-    return areas;
-}
 function validateTemplateAreasAreRectangular(template, report, path) {
     const grid = template.map((row) => row.split(' '));
     function isAreaRectangular(areaName) {
@@ -437,7 +484,7 @@ function validateTemplateAreasAreRectangular(template, report, path) {
         }
     }
 }
-function validatePageLayoutDefinition(layoutDefinition, report, path) {
+function validateResponsiveGridLayoutDefinition(layoutDefinition, report, path) {
     if (!layoutDefinition) {
         return;
     }
@@ -445,10 +492,16 @@ function validatePageLayoutDefinition(layoutDefinition, report, path) {
         if (!deviceDefinition?.layout?.template || !deviceDefinition?.layout?.columns) {
             continue;
         }
-        if (deviceDefinition.layout.template.some((row) => row.split(' ').length !== deviceDefinition.layout.columns)) {
-            report(deviceDefinition.layout.template, 'template needs to be the same length as number of columns', [...path, deviceName, 'layout', 'template']);
+        const { layout } = deviceDefinition;
+        if (layout.template.some((row) => row.split(' ').length !== layout.columns)) {
+            report(layout.template, 'template needs to be the same length as number of columns', [
+                ...path,
+                deviceName,
+                'layout',
+                'template',
+            ]);
         }
-        validateTemplateAreasAreRectangular(deviceDefinition.layout.template, report, [
+        validateTemplateAreasAreRectangular(layout.template, report, [
             ...path,
             deviceName,
             'layout',
@@ -457,56 +510,163 @@ function validatePageLayoutDefinition(layoutDefinition, report, path) {
     }
 }
 function validateBlockGridAreas(blocks, layoutDefinition, report, path) {
-    const templateAreas = getTemplateAreas(layoutDefinition);
+    const templateAreas = getGridTemplateAreas(layoutDefinition);
     for (const [idx, block] of blocks.entries()) {
-        if (block.gridArea && !templateAreas.has(block.gridArea)) {
+        if (block.gridArea === breadcrumbsGridArea) {
+            report(block.gridArea, 'is reserved for the breadcrumb trail', [...path, idx, 'gridArea']);
+        }
+        else if (layoutDefinition && block.gridArea && !templateAreas.has(block.gridArea)) {
             report(block.gridArea, `does not match any area defined in the layout template. Available areas: ${[...templateAreas].join(', ') || 'none'}`, [...path, idx, 'gridArea']);
         }
     }
 }
-function validateSubPageLayout(layout, blocks, report, path) {
-    validatePageLayoutDefinition(layout, report, path);
-    if (layout && blocks) {
+function validateBreadcrumbsGridArea(layout, report, path, breadcrumbsEnabled) {
+    if (!layout || !getGridTemplateAreas(layout).has(breadcrumbsGridArea)) {
+        return;
+    }
+    if (!breadcrumbsEnabled) {
+        for (const [deviceName, deviceDefinition] of Object.entries(layout)) {
+            const template = deviceDefinition?.layout?.template;
+            if (template?.some((row) => row.split(' ').includes(breadcrumbsGridArea))) {
+                report(template, `the '${breadcrumbsGridArea}' grid area requires layout.breadcrumbs to be enabled`, [...path, deviceName, 'layout', 'template']);
+            }
+        }
+        return;
+    }
+    // A device inherits the template of the next smaller one, so an area defined only for a larger
+    // device leaves the trail without a slot to sit in below that breakpoint.
+    const cascaded = getCascadedGridTemplateAreas(layout);
+    const missing = gridDeviceOrder.filter((device) => !cascaded[device].has(breadcrumbsGridArea));
+    if (missing.length) {
+        report(layout, `the '${breadcrumbsGridArea}' grid area is missing from the grid rendered on ${missing.join(', ')}`, path);
+    }
+}
+function validateConsistentBreadcrumbsGridArea(subPages, report) {
+    // The trail belongs to the page, so it may not appear on one sub page and be missing from the
+    // next. Defining the area consistently also lets the app runtime tell from the page definition
+    // alone whether a page renders the trail from its grid or below the title bar.
+    const declaresArea = ([subPage]) => getGridTemplateAreas(subPage.layout).has(breadcrumbsGridArea);
+    const declaring = subPages.filter(declaresArea);
+    if (!declaring.length || declaring.length === subPages.length) {
+        return;
+    }
+    for (const entry of subPages) {
+        if (!declaresArea(entry)) {
+            report(entry[0], `the '${breadcrumbsGridArea}' grid area must be defined by every sub page of this page or by none`, entry[1]);
+        }
+    }
+}
+function validateSubPageLayout(layout, blocks, report, path, breadcrumbsEnabled) {
+    validateResponsiveGridLayoutDefinition(layout, report, path);
+    validateBreadcrumbsGridArea(layout, report, path, breadcrumbsEnabled);
+    if (blocks) {
         validateBlockGridAreas(blocks, layout, report, [...path, 'blocks']);
     }
 }
 function validateGridLayout(definition, report) {
+    const breakpoints = definition.layout?.breakpoints;
+    if (breakpoints?.tablet != null &&
+        breakpoints?.desktop != null &&
+        breakpoints.tablet >= breakpoints.desktop) {
+        report(breakpoints, 'tablet breakpoint must be smaller than the desktop breakpoint', [
+            'layout',
+            'breakpoints',
+        ]);
+    }
+    const navbarLayout = definition.layout?.navbar;
+    validateResponsiveGridLayoutDefinition(navbarLayout, report, ['layout', 'navbar']);
+    if (navbarLayout) {
+        if (definition.layout?.navigation !== 'top') {
+            report(navbarLayout, 'only applies when navigation is set to top', ['layout', 'navbar']);
+        }
+        if (definition.layout?.stackedHeader) {
+            report(navbarLayout, 'cannot be combined with stackedHeader', ['layout', 'navbar']);
+        }
+        const navbarAreaOrder = ['logo', 'name', 'navigation', 'controls'];
+        const allowedAreas = new Set(['.', ...navbarAreaOrder]);
+        const requiredAreas = definition.layout?.logo?.position === 'navbar' ? navbarAreaOrder : navbarAreaOrder.slice(1);
+        for (const [deviceName, deviceDefinition] of Object.entries(navbarLayout)) {
+            if (!deviceDefinition?.layout?.template) {
+                continue;
+            }
+            const { template } = deviceDefinition.layout;
+            const templatePath = ['layout', 'navbar', deviceName, 'layout', 'template'];
+            const visualAreaOrder = [];
+            const visualAreas = new Set();
+            for (const [rowIndex, row] of deviceDefinition.layout.template.entries()) {
+                for (const area of row.split(' ')) {
+                    if (!allowedAreas.has(area)) {
+                        report(row, `unknown navbar grid area '${area}'`, [...templatePath, rowIndex]);
+                    }
+                    else if (area !== '.' && !visualAreas.has(area)) {
+                        visualAreas.add(area);
+                        visualAreaOrder.push(area);
+                    }
+                }
+            }
+            let hasMissingArea = false;
+            for (const area of requiredAreas) {
+                if (!visualAreas.has(area)) {
+                    hasMissingArea = true;
+                    report(template, `navbar grid is missing required area '${area}'`, templatePath);
+                }
+            }
+            if (!hasMissingArea) {
+                const expectedAreaOrder = navbarAreaOrder.filter((area) => visualAreas.has(area));
+                if (visualAreaOrder.some((area, index) => area !== expectedAreaOrder[index])) {
+                    report(template, `navbar grid areas must follow the accessible order: ${expectedAreaOrder.join(', ')}`, templatePath);
+                }
+            }
+        }
+    }
+    const breadcrumbsEnabled = definition.layout?.breadcrumbs === true;
     iterApp(definition, {
         onPage(page, path) {
             // Basic page
             if (page.type === 'page' || page.type === undefined) {
                 const basicPage = page;
-                validateSubPageLayout(basicPage.layout, basicPage.blocks, report, path);
+                validateSubPageLayout(basicPage.layout, basicPage.blocks, report, path, breadcrumbsEnabled);
                 return;
             }
             // Tabs page
             if (page.type === 'tabs') {
                 const tabsPage = page;
-                if (tabsPage.tabs) {
-                    for (const [tabId, tab] of tabsPage.tabs.entries()) {
-                        validateSubPageLayout(tab.layout, tab.blocks, report, [...path, 'tabs', tabId]);
-                    }
-                }
-                else if (tabsPage.definition?.foreach) {
-                    validateSubPageLayout(tabsPage.definition.foreach.layout, tabsPage.definition.foreach.blocks, report, [...path, 'definition', 'foreach']);
-                }
+                const tabs = tabsPage.tabs
+                    ? tabsPage.tabs.map((tab, tabId) => [tab, [...path, 'tabs', tabId]])
+                    : tabsPage.definition?.foreach
+                        ? [[tabsPage.definition.foreach, [...path, 'definition', 'foreach']]]
+                        : [];
+                for (const [tab, tabPath] of tabs) {
+                    validateSubPageLayout(tab.layout, tab.blocks, report, tabPath, breadcrumbsEnabled);
+                }
+                validateConsistentBreadcrumbsGridArea(tabs, report);
                 return;
             }
             // Flow page
             if (page.type === 'flow') {
                 const flowPage = page;
-                for (const [stepId, step] of flowPage.steps.entries()) {
-                    validateSubPageLayout(step.layout, step.blocks, report, [...path, 'steps', stepId]);
+                const steps = flowPage.steps.map((step, stepId) => [
+                    step,
+                    [...path, 'steps', stepId],
+                ]);
+                for (const [step, stepPath] of steps) {
+                    validateSubPageLayout(step.layout, step.blocks, report, stepPath, breadcrumbsEnabled);
                 }
+                validateConsistentBreadcrumbsGridArea(steps, report);
                 return;
             }
             // Loop page
             if (page.type === 'loop') {
                 const loopPage = page;
-                validateSubPageLayout(loopPage.foreach.layout, loopPage.foreach.blocks, report, [
-                    ...path,
-                    'foreach',
-                ]);
+                const subPages = [
+                    [loopPage.start, 'start'],
+                    [loopPage.foreach, 'foreach'],
+                    [loopPage.end, 'end'],
+                ].flatMap(([subPage, key]) => subPage ? [[subPage, [...path, key]]] : []);
+                for (const [subPage, subPagePath] of subPages) {
+                    validateSubPageLayout(subPage.layout, subPage.blocks, report, subPagePath, breadcrumbsEnabled);
+                }
+                validateConsistentBreadcrumbsGridArea(subPages, report);
             }
         },
     });
@@ -999,6 +1159,13 @@ function validateSecurity(definition, report) {
         }
     }
     iterApp(definition, { onBlock: checkRoles, onPage: checkRoles });
+    if (definition.pages) {
+        iterPageParents(definition.pages, (entry, path) => {
+            if (typeof entry !== 'string') {
+                checkRoles(entry, path);
+            }
+        });
+    }
     const { hideGroupDropdown } = definition.layout ?? {};
     if (Array.isArray(hideGroupDropdown)) {
         for (const [index, role] of hideGroupDropdown.entries()) {
@@ -1503,6 +1670,7 @@ export async function validateAppDefinition(definition, getBlockVersions, contro
         validateLanguage(clonedDefinition, report);
         validateResourceReferences(clonedDefinition, report);
         validateMembersSchema(clonedDefinition, report);
+        validatePageParents(clonedDefinition, report);
         validatePhoneNumberDefinition(clonedDefinition, report);
         validateResourceSchemas(clonedDefinition, report);
         validateSecurity(clonedDefinition, report);