@appsemble/lang-sdk 0.40.9 → 0.40.11-test.0

package/constants/patterns.d.ts

@@ -18,6 +18,12 @@ export declare const partialNormalized: RegExp;
  * A pattern for exactly matching a lower case hyphen separated string.
  */
 export declare const normalized: RegExp;
+/**
+ * A pattern for validating a theme variable (custom CSS property) value.
+ *
+ * Any single-line CSS value that cannot escape its declaration block is allowed.
+ */
+export declare const themeVariableValue: RegExp;
 /**
  * A pattern for matching the block name pattern of @organization/project.
  */

package/constants/patterns.js

@@ -19,6 +19,12 @@ export const partialNormalized = /([0-9a-z](?:(?!.*--)[-0-9a-z]*[0-9a-z])?)/;
  * A pattern for exactly matching a lower case hyphen separated string.
  */
 export const normalized = new RegExp(`^${partialNormalized.source}$`);
+/**
+ * A pattern for validating a theme variable (custom CSS property) value.
+ *
+ * Any single-line CSS value that cannot escape its declaration block is allowed.
+ */
+export const themeVariableValue = /^[^\n\r;{}]+$/;
 /**
  * A pattern for matching the block name pattern of @organization/project.
  */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@appsemble/lang-sdk",
-  "version": "0.40.9",
+  "version": "0.40.11-test.0",
   "description": "Language SDK for Appsemble",
   "keywords": [
     "app",

package/schemas/AppDefinition.js

@@ -27,7 +27,27 @@ This will be displayed on the app store.
             description: 'Properties related to the layout of the app.',
         },
         notifications: {
-            enum: ['login', 'opt-in', 'startup'],
+            oneOf: [
+                { enum: ['login', 'opt-in', 'startup'] },
+                {
+                    type: 'object',
+                    required: ['roles'],
+                    additionalProperties: false,
+                    properties: {
+                        default: {
+                            enum: ['login', 'none', 'opt-in', 'startup'],
+                            description: `The strategy for roles that aren’t listed in \`roles\`, and for users without
+a role. Defaults to \`none\`.`,
+                        },
+                        roles: {
+                            type: 'object',
+                            minProperties: 1,
+                            description: 'The strategy per role.',
+                            additionalProperties: { enum: ['login', 'none', 'opt-in'] },
+                        },
+                    },
+                },
+            ],
             description: `The strategy to use for apps to subscribe to push notifications.
 
 If specified, push notifications can be sent to subscribed users via the _Notifications_ tab in the
@@ -37,6 +57,10 @@ to \`startup\` will cause Appsemble to immediately request for the permission up
 If this is set to \`login\`, the app will request permissions for push notification once the user
 logs in.
 
+To use a different strategy per role, set \`roles\` to a map of role names to \`login\`, \`opt-in\`, or
+\`none\`. Roles that aren’t listed use \`default\`. A member with several roles gets the most eager
+strategy of those roles. Only roles assigned to the member count, not roles they inherit.
+
 > **Note**: Setting \`notifications\` to \`startup\` is not recommended, due to its invasive nature.
 `,
         },

package/schemas/BlockDefinition.js

@@ -1,4 +1,4 @@
-import { partialNormalized, semver } from '../constants/index.js';
+import { normalized, partialNormalized, semver } from '../constants/index.js';
 export const BlockDefinition = {
     type: 'object',
     description: 'A block that is displayed on a page.',
@@ -29,6 +29,19 @@ Some examples:
 
 Since blocks may change over time, a version must be specified in order to ensure that the block
 will remain the same until it is manually updated.
+`,
+        },
+        name: {
+            type: 'string',
+            pattern: normalized.source,
+            maxLength: 40,
+            description: `A name which identifies this single block instance.
+
+The name is rendered as a \`data-block-name\` attribute on the wrapper element of the block, so app
+styles can target one instance instead of every block of the same type. Names must be lower case and
+hyphen separated.
+
+For example, a block named \`screen-title\` is targeted with \`[data-block-name='screen-title']\`.
 `,
         },
         layout: {

package/schemas/Theme.js

@@ -1,5 +1,5 @@
 import { baseTheme } from '../constants/baseTheme.js';
-import { hexColor } from '../constants/patterns.js';
+import { hexColor, normalized, themeVariableValue } from '../constants/patterns.js';
 export const Theme = {
     type: 'object',
     description: 'A generic theme definition.',
@@ -90,6 +90,38 @@ the CSS of the app and its blocks. It falls back to the body font.
                 { $ref: '#/components/schemas/GoogleFontDefinition' },
             ],
         },
+        variables: {
+            type: 'object',
+            description: `Custom CSS properties (design tokens) exposed on \`:root\` in the theme CSS.
+
+Each entry is emitted as a \`--<name>\` custom property. Names must be lower case and hyphen
+separated. Custom properties inherit into every block's shadow DOM, so tokens defined once are
+usable in core, shared, and block styles.
+
+For example:
+
+\`\`\`yaml
+theme:
+  variables:
+    night: '#0e1220'
+    font-display: "'Baloo 2', sans-serif"
+\`\`\`
+
+These can be referenced in custom CSS as \`var(--night)\` and \`var(--font-display)\`.
+`,
+            minProperties: 1,
+            maxProperties: 32,
+            // The validator supports propertyNames, but the OpenAPI schema object type does not know it.
+            propertyNames: {
+                pattern: normalized.source,
+                maxLength: 40,
+            },
+            additionalProperties: {
+                type: 'string',
+                pattern: themeVariableValue.source,
+                maxLength: 128,
+            },
+        },
     },
 };
 //# sourceMappingURL=Theme.js.map

package/schemas/actions/EmailActionDefinition.js

@@ -42,7 +42,7 @@ If \`to\`, \`cc\`, and \`bcc\` all end up being empty, no emails will be sent bu
 
 The remapper must resolve to an object containing the following properties:
 
-- \`target\`: The asset ID or link to download contents from to add as an attachment. This is mutually exclusive with \`content\`.
+- \`target\`: The asset ID or link to download contents from to add as an attachment. This is mutually exclusive with \`content\`. The files downloaded from links may total at most 25 MiB per email.
 - \`content\`: The raw content to include as the file content. This is mutually exclusive with \`target\`.
 - \`filename\`: The filename to include the attachment as.
 - \`accept\` If the target is a URL, this will be set as the HTTP \`Accept\` header when downloading the file.

package/types/block.d.ts

@@ -48,6 +48,14 @@ export interface BlockDefinition extends ControllerDefinition {
      * ^\d+\.\d+\.\d+$
      */
     version: string;
+    /**
+     * A name which identifies this single block instance.
+     *
+     * It is rendered as a `data-block-name` attribute on the wrapper element of the block, so app
+     * styles can target one instance instead of every block of the same type. Names must be lower
+     * case and hyphen separated.
+     */
+    name?: string;
     /**
      * An optional header to render above the block.
      */

package/types/core.d.ts

@@ -184,9 +184,19 @@ export interface AppDefinition {
     /**
      * The strategy to use for apps to subscribe to push notifications.
      *
-     * If this is omitted, push notifications can not be sent.
+     * Either one strategy for all app members, or a strategy per role. If this is omitted, push
+     * notifications can not be sent.
      */
-    notifications?: 'login' | 'opt-in' | 'startup';
+    notifications?: 'login' | 'opt-in' | 'startup' | {
+        /**
+         * The strategy for roles that aren't listed in `roles`, and for users without a role.
+         */
+        default?: 'login' | 'none' | 'opt-in' | 'startup';
+        /**
+         * The strategy per role.
+         */
+        roles: Record<AppRole, 'login' | 'none' | 'opt-in'>;
+    };
     /**
      * The pages of the app.
      */

package/types/theme.d.ts

@@ -51,6 +51,13 @@ export interface Theme {
      * The name of a font available on Google fonts.
      */
     font: FontDefinition;
+    /**
+     * Custom CSS properties (design tokens) exposed on `:root` in the compiled theme CSS.
+     *
+     * Each entry is emitted as a `--<name>` custom property. Custom properties inherit into every
+     * block's shadow DOM, so tokens defined once are usable in core, shared, and block styles.
+     */
+    variables?: Record<string, string>;
     /**
      * A second font family the app loads, exposed as the `--font-family-display` custom property for
      * the CSS of the app and its blocks.

package/validation.js

@@ -9,7 +9,7 @@ import { findPageByName } from './findPageByName.js';
 import { isAppLink } from './pageUtils.js';
 import { bottomNavigationGridArea, breadcrumbsGridArea, builtinPagesGridAreaOrder, getBuiltinPagesDefaultGridLayout, getCascadedGridTemplateAreas, getGridTemplateAreas, gridDeviceOrder, resendBannerGridArea, } from './gridUtils.js';
 import { isValidIconName, parseIconReference } from './icons.js';
-import { iterApp } from './iterApp.js';
+import { iterApp, iterBlockList } from './iterApp.js';
 import { has } from './miscellaneous.js';
 import { normalize } from './normalize.js';
 import { serverActions } from './serverActions.js';
@@ -97,7 +97,7 @@ function validateUniquePageNames(definition, report) {
                 pageNames.set(normalizedPageName, [pagePath]);
             }
             if (page.type === 'container') {
-                checkPages(page.pages, pagePath);
+                checkPages(page.pages ?? [], pagePath);
             }
         }
     }
@@ -122,7 +122,7 @@ function iterPageParents(pages, onParent, prefix = ['pages']) {
             onParent(entry, Array.isArray(page.parent) ? [...pagePath, 'parent', entryIndex] : [...pagePath, 'parent'], page);
         }
         if (page.type === 'container') {
-            iterPageParents(page.pages, onParent, [...pagePath, 'pages']);
+            iterPageParents(page.pages ?? [], onParent, [...pagePath, 'pages']);
         }
     }
 }
@@ -167,6 +167,74 @@ function validatePageParents(definition, report) {
         }
     });
 }
+/**
+ * Validates the blocks in the app definition to ensure there are no duplicate block names.
+ *
+ * A block name identifies a single block within the screen it is rendered in. A page renders one
+ * of its tabs or steps at a time, so uniqueness is scoped to the block list the block belongs to.
+ * The same name may be used on other pages, tabs and steps, which lets an app style the same role
+ * everywhere with one rule.
+ *
+ * @param definition The definition of the app
+ * @param report A function used to report a value.
+ */
+function validateUniqueBlockNames(definition, report) {
+    function checkBlockList(blocks, path) {
+        const names = new Set();
+        iterBlockList(blocks, {
+            onBlock(block, blockPath) {
+                if (block.name) {
+                    if (names.has(block.name)) {
+                        report(block.name, 'is a duplicate block name', [...blockPath, 'name']);
+                    }
+                    else {
+                        names.add(block.name);
+                    }
+                }
+            },
+        }, path);
+    }
+    iterApp(definition, {
+        onPage(page, path) {
+            // Basic page
+            if (page.type === 'page' || page.type === undefined) {
+                checkBlockList(page.blocks, [...path, 'blocks']);
+                return;
+            }
+            // Tabs page
+            if (page.type === 'tabs') {
+                const tabsPage = page;
+                if (tabsPage.tabs) {
+                    for (const [tabId, tab] of tabsPage.tabs.entries()) {
+                        checkBlockList(tab.blocks, [...path, 'tabs', tabId, 'blocks']);
+                    }
+                }
+                else if (tabsPage.definition?.foreach) {
+                    checkBlockList(tabsPage.definition.foreach.blocks, [
+                        ...path,
+                        'definition',
+                        'foreach',
+                        'blocks',
+                    ]);
+                }
+                return;
+            }
+            // Flow page
+            if (page.type === 'flow' && page.steps) {
+                const flowPage = page;
+                for (const [stepId, step] of flowPage.steps.entries()) {
+                    checkBlockList(step.blocks, [...path, 'steps', stepId, 'blocks']);
+                }
+                return;
+            }
+            // Loop page
+            if (page.type === 'loop') {
+                const loopPage = page;
+                checkBlockList(loopPage.foreach.blocks, [...path, 'foreach', 'blocks']);
+            }
+        },
+    });
+}
 function validateMembersSchema(definition, report) {
     if (!definition.members?.properties) {
         return;
@@ -703,7 +771,7 @@ function validateGridLayout(definition, report) {
             // Flow page
             if (page.type === 'flow') {
                 const flowPage = page;
-                const steps = flowPage.steps.map((step, stepId) => [
+                const steps = (flowPage.steps ?? []).map((step, stepId) => [
                     step,
                     [...path, 'steps', stepId],
                 ]);
@@ -1122,8 +1190,9 @@ function validateSecurity(definition, report) {
             checkRoleExists(role, [...path, 'roles', index], ['$guest', ...predefinedRoles]);
         }
     };
+    const notificationRoles = notifications && typeof notifications === 'object' ? notifications.roles : undefined;
     if (!security) {
-        if (notifications === 'login') {
+        if (notifications === 'login' || notificationRoles) {
             report(notifications, 'only works if security is defined', ['notifications']);
         }
         return;
@@ -1224,6 +1293,11 @@ function validateSecurity(definition, report) {
             }
         });
     }
+    if (notificationRoles) {
+        for (const role of Object.keys(notificationRoles)) {
+            checkRoleExists(role, ['notifications', 'roles', role]);
+        }
+    }
     const { hideGroupDropdown } = definition.layout ?? {};
     if (Array.isArray(hideGroupDropdown)) {
         for (const [index, role] of hideGroupDropdown.entries()) {
@@ -1819,6 +1893,9 @@ export async function validateAppDefinition(definition, getBlockVersions, contro
     const report = (instance, message, path) => {
         result.errors.push(new ValidationError(message, instance, undefined, path));
     };
+    const reportUnexpectedError = (error) => {
+        report(null, `Unexpected error: ${error instanceof Error ? error.message : error}`, []);
+    };
     try {
         // IMPORTANT: Create a deep copy to prevent validation logic from mutating the original definition.
         // The imperative/procedural-style algorithms below (e.g., in validateActions) build up arrays
@@ -1834,27 +1911,37 @@ export async function validateAppDefinition(definition, getBlockVersions, contro
             }
             blockVersionMap.get(version.name).set(version.version, version);
         }
-        validateController(clonedDefinition, controllerImplementations, report);
-        validateCronJobs(clonedDefinition, report);
-        validateDefaultPage(clonedDefinition, report);
-        validateHooks(clonedDefinition, report);
-        validateIcons(clonedDefinition, report);
-        validateIconReferences(clonedDefinition, blockVersionMap, report);
-        validateLanguage(clonedDefinition, report);
-        validateResourceReferences(clonedDefinition, report);
-        validateMembersSchema(clonedDefinition, report);
-        validatePageParents(clonedDefinition, report);
-        validatePhoneNumberDefinition(clonedDefinition, report);
-        validateResourceSchemas(clonedDefinition, report);
-        validateSecurity(clonedDefinition, report);
-        validateBlocks(clonedDefinition, blockVersionMap, report);
-        validateActions(clonedDefinition, report);
-        validateEvents(clonedDefinition, blockVersionMap, report);
-        validateUniquePageNames(clonedDefinition, report);
-        validateGridLayout(clonedDefinition, report);
+        // Run each check on its own, so a check that fails does not keep the others from reporting.
+        const check = (validate) => {
+            try {
+                validate();
+            }
+            catch (error) {
+                reportUnexpectedError(error);
+            }
+        };
+        check(() => validateController(clonedDefinition, controllerImplementations, report));
+        check(() => validateCronJobs(clonedDefinition, report));
+        check(() => validateDefaultPage(clonedDefinition, report));
+        check(() => validateHooks(clonedDefinition, report));
+        check(() => validateIcons(clonedDefinition, report));
+        check(() => validateIconReferences(clonedDefinition, blockVersionMap, report));
+        check(() => validateLanguage(clonedDefinition, report));
+        check(() => validateResourceReferences(clonedDefinition, report));
+        check(() => validateMembersSchema(clonedDefinition, report));
+        check(() => validatePageParents(clonedDefinition, report));
+        check(() => validatePhoneNumberDefinition(clonedDefinition, report));
+        check(() => validateResourceSchemas(clonedDefinition, report));
+        check(() => validateSecurity(clonedDefinition, report));
+        check(() => validateBlocks(clonedDefinition, blockVersionMap, report));
+        check(() => validateActions(clonedDefinition, report));
+        check(() => validateEvents(clonedDefinition, blockVersionMap, report));
+        check(() => validateUniquePageNames(clonedDefinition, report));
+        check(() => validateUniqueBlockNames(clonedDefinition, report));
+        check(() => validateGridLayout(clonedDefinition, report));
     }
     catch (error) {
-        report(null, `Unexpected error: ${error instanceof Error ? error.message : error}`, []);
+        reportUnexpectedError(error);
     }
     return result;
 }