@appsemble/lang-sdk 0.40.10 → 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.10",
+  "version": "0.40.11-test.0",
   "description": "Language SDK for Appsemble",
   "keywords": [
     "app",

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/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/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';
@@ -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;
@@ -1869,6 +1937,7 @@ export async function validateAppDefinition(definition, getBlockVersions, contro
         check(() => validateActions(clonedDefinition, report));
         check(() => validateEvents(clonedDefinition, blockVersionMap, report));
         check(() => validateUniquePageNames(clonedDefinition, report));
+        check(() => validateUniqueBlockNames(clonedDefinition, report));
         check(() => validateGridLayout(clonedDefinition, report));
     }
     catch (error) {