@appsemble/lang-sdk 0.37.6 → 0.38.0

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.0",
   "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/schemas/AppLayoutDefinition.js

@@ -104,6 +104,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/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,9 @@
-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',
+});
 //# sourceMappingURL=PageLayoutDefinition.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,10 @@ 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';

package/schemas/index.js

@@ -124,7 +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';
 //# 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 {
@@ -118,6 +118,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.
          *
@@ -316,6 +334,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

@@ -437,7 +437,7 @@ function validateTemplateAreasAreRectangular(template, report, path) {
         }
     }
 }
-function validatePageLayoutDefinition(layoutDefinition, report, path) {
+function validateResponsiveGridLayoutDefinition(layoutDefinition, report, path) {
     if (!layoutDefinition) {
         return;
     }
@@ -445,10 +445,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',
@@ -465,12 +471,67 @@ function validateBlockGridAreas(blocks, layoutDefinition, report, path) {
     }
 }
 function validateSubPageLayout(layout, blocks, report, path) {
-    validatePageLayoutDefinition(layout, report, path);
+    validateResponsiveGridLayoutDefinition(layout, report, path);
     if (layout && 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);
+                }
+            }
+        }
+    }
     iterApp(definition, {
         onPage(page, path) {
             // Basic page
@@ -503,10 +564,19 @@ function validateGridLayout(definition, report) {
             // Loop page
             if (page.type === 'loop') {
                 const loopPage = page;
+                if (loopPage.start) {
+                    validateSubPageLayout(loopPage.start.layout, loopPage.start.blocks, report, [
+                        ...path,
+                        'start',
+                    ]);
+                }
                 validateSubPageLayout(loopPage.foreach.layout, loopPage.foreach.blocks, report, [
                     ...path,
                     'foreach',
                 ]);
+                if (loopPage.end) {
+                    validateSubPageLayout(loopPage.end.layout, loopPage.end.blocks, report, [...path, 'end']);
+                }
             }
         },
     });