@appsemble/lang-sdk 0.39.2 → 0.40.0

package/BasicValidator.d.ts

@@ -1,5 +1,6 @@
 import { type CustomFormat, type Options, type Schema, Validator, type ValidatorResult } from 'jsonschema';
 import { type JsonObject } from 'type-fest';
+import { isValidIconReference } from './icons.js';
 import { type BlockDefinition } from './index.js';
 interface ValidatorFactoryOptions {
     schemas: Record<string, Schema>;
@@ -15,6 +16,7 @@ export declare class BaseValidatorFactory {
         byte: () => boolean;
         binary: () => boolean;
         password: () => boolean;
+        icon: typeof isValidIconReference;
     };
     private schemas;
     private customFormats;

package/BasicValidator.js

@@ -1,4 +1,5 @@
 import { Validator, } from 'jsonschema';
+import { isValidIconReference } from './icons.js';
 import { schemas as allSchemas } from './index.js';
 import { escapeJsonPointer } from './jsonPointer.js';
 import { has } from './miscellaneous.js';
@@ -9,7 +10,10 @@ export class BaseValidatorFactory {
     }
     build() {
         const validator = new Validator();
-        for (const [key, format] of Object.entries(this.customFormats ?? {})) {
+        for (const [key, format] of Object.entries({
+            ...BaseValidatorFactory.defaultCustomFormats,
+            ...this.customFormats,
+        })) {
             validator.customFormats[key] = format;
         }
         for (const [key, schema] of Object.entries(this.schemas)) {
@@ -31,13 +35,13 @@ BaseValidatorFactory.defaultCustomFormats = {
     byte: () => true,
     binary: () => true,
     password: () => true,
+    icon: isValidIconReference,
 };
 export class BlockExampleValidator {
     constructor() {
         this.validator = new BaseValidatorFactory({
             schemas: allSchemas,
             customFormats: {
-                ...BaseValidatorFactory.defaultCustomFormats,
                 fontawesome: () => true,
                 remapper: () => true,
                 action: () => true,
@@ -98,7 +102,6 @@ export class BlockParamInstanceValidator {
         this.validator = new BaseValidatorFactory({
             schemas: {},
             customFormats: {
-                ...BaseValidatorFactory.defaultCustomFormats,
                 // TODO: validate more
                 fontawesome: () => true,
                 // TODO: validate more
@@ -132,7 +135,6 @@ export class BlockParamSchemaValidator {
         this.validator = new BaseValidatorFactory({
             schemas: allSchemas,
             customFormats: {
-                ...BaseValidatorFactory.defaultCustomFormats,
                 fontawesome: () => true,
                 remapper: () => true,
                 action: () => true,
@@ -149,9 +151,6 @@ export class AppValidator {
     constructor() {
         this.validator = new BaseValidatorFactory({
             schemas: allSchemas,
-            customFormats: {
-                ...BaseValidatorFactory.defaultCustomFormats,
-            },
         }).build();
     }
     validateApp(app) {
@@ -162,9 +161,6 @@ export class RemapperValidator {
     constructor() {
         this.validator = new BaseValidatorFactory({
             schemas: allSchemas,
-            customFormats: {
-                ...BaseValidatorFactory.defaultCustomFormats,
-            },
         }).build();
     }
     validateRemapper(remapper) {

package/icons.d.ts

@@ -0,0 +1,64 @@
+import { type IconName } from '@fortawesome/fontawesome-common-types';
+import { type IconReference, type IconRegistry } from './types/index.js';
+/**
+ * The prefix marking a reference to a key in the app’s `icons` registry.
+ */
+export declare const customIconPrefix = "icon:";
+/**
+ * Check whether a value is a valid icon registry key or icon asset name.
+ *
+ * @param name The value to check.
+ * @returns Whether the value matches the icon name grammar.
+ */
+export declare function isValidIconName(name: unknown): name is string;
+export type ParsedIconReference = {
+    type: 'custom';
+    key: string;
+} | {
+    type: 'fontawesome';
+    name: IconName;
+} | {
+    type: 'invalid';
+    reason: string;
+};
+/**
+ * Parse an icon reference without consulting a registry.
+ *
+ * Bare names are treated as Font Awesome names without checking them against the Font Awesome
+ * icon set. Only the `icon:` prefix is recognized; any other colon-separated prefix is rejected.
+ *
+ * @param reference The value to parse.
+ * @returns The parsed reference, or an invalid result with a reason.
+ */
+export declare function parseIconReference(reference: unknown): ParsedIconReference;
+/**
+ * Check whether a value is a syntactically valid icon reference.
+ *
+ * This is the check behind the `icon` schema format. It doesn’t consult a registry.
+ *
+ * @param reference The value to check.
+ * @returns Whether the value is a bare icon name or a well-formed `icon:<key>` reference.
+ */
+export declare function isValidIconReference(reference: unknown): reference is IconReference;
+export type ResolvedIcon = {
+    type: 'asset';
+    key: string;
+    asset: string;
+} | {
+    type: 'fontawesome';
+    name: IconName;
+} | {
+    type: 'invalid';
+    reason: string;
+};
+/**
+ * Resolve an icon reference against an icon registry.
+ *
+ * Registry keys and entries are validated here as well, so the result is safe to render even if
+ * the registry wasn’t validated when it was published. Only own properties of the registry count.
+ *
+ * @param reference The icon reference to resolve.
+ * @param registry The app’s icon registry.
+ * @returns A Font Awesome icon name, a validated asset name, or an invalid result with a reason.
+ */
+export declare function resolveIconReference(reference: unknown, registry?: IconRegistry | null): ResolvedIcon;

package/icons.js

@@ -0,0 +1,90 @@
+import { normalized } from './constants/index.js';
+import { has } from './miscellaneous.js';
+/**
+ * The prefix marking a reference to a key in the app’s `icons` registry.
+ */
+export const customIconPrefix = 'icon:';
+/**
+ * Check whether a value is a valid icon registry key or icon asset name.
+ *
+ * @param name The value to check.
+ * @returns Whether the value matches the icon name grammar.
+ */
+export function isValidIconName(name) {
+    return typeof name === 'string' && normalized.test(name);
+}
+/**
+ * Parse an icon reference without consulting a registry.
+ *
+ * Bare names are treated as Font Awesome names without checking them against the Font Awesome
+ * icon set. Only the `icon:` prefix is recognized; any other colon-separated prefix is rejected.
+ *
+ * @param reference The value to parse.
+ * @returns The parsed reference, or an invalid result with a reason.
+ */
+export function parseIconReference(reference) {
+    if (typeof reference !== 'string') {
+        return { type: 'invalid', reason: 'must be a string' };
+    }
+    if (!reference) {
+        return { type: 'invalid', reason: 'must not be empty' };
+    }
+    if (reference.startsWith(customIconPrefix)) {
+        const key = reference.slice(customIconPrefix.length);
+        if (!isValidIconName(key)) {
+            return {
+                type: 'invalid',
+                reason: `has the invalid icon key “${key}”; keys must match ${normalized.source}`,
+            };
+        }
+        return { type: 'custom', key };
+    }
+    if (reference.includes(':')) {
+        return {
+            type: 'invalid',
+            reason: `uses the unsupported prefix “${reference.slice(0, reference.indexOf(':') + 1)}”; only “${customIconPrefix}” is supported`,
+        };
+    }
+    return { type: 'fontawesome', name: reference };
+}
+/**
+ * Check whether a value is a syntactically valid icon reference.
+ *
+ * This is the check behind the `icon` schema format. It doesn’t consult a registry.
+ *
+ * @param reference The value to check.
+ * @returns Whether the value is a bare icon name or a well-formed `icon:<key>` reference.
+ */
+export function isValidIconReference(reference) {
+    return parseIconReference(reference).type !== 'invalid';
+}
+/**
+ * Resolve an icon reference against an icon registry.
+ *
+ * Registry keys and entries are validated here as well, so the result is safe to render even if
+ * the registry wasn’t validated when it was published. Only own properties of the registry count.
+ *
+ * @param reference The icon reference to resolve.
+ * @param registry The app’s icon registry.
+ * @returns A Font Awesome icon name, a validated asset name, or an invalid result with a reason.
+ */
+export function resolveIconReference(reference, registry) {
+    const parsed = parseIconReference(reference);
+    if (parsed.type !== 'custom') {
+        return parsed;
+    }
+    const { key } = parsed;
+    if (typeof registry !== 'object' || !registry || !has(registry, key)) {
+        return { type: 'invalid', reason: `references the unknown icon key “${key}”` };
+    }
+    const entry = registry[key];
+    const asset = typeof entry === 'object' && entry ? entry.asset : null;
+    if (!isValidIconName(asset)) {
+        return {
+            type: 'invalid',
+            reason: `references the icon key “${key}”, which has an invalid asset name`,
+        };
+    }
+    return { type: 'asset', key, asset };
+}
+//# sourceMappingURL=icons.js.map

package/index.d.ts

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

package/index.js

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@appsemble/lang-sdk",
-  "version": "0.39.2",
+  "version": "0.40.0",
   "description": "Language SDK for Appsemble",
   "keywords": [
     "app",

package/schemas/AppDefinition.js

@@ -91,6 +91,16 @@ The most basic resource has a \`schema\` property and defines the minimal securi
         theme: {
             $ref: '#/components/schemas/Theme',
         },
+        icons: {
+            type: 'object',
+            description: `Custom icons that can be referenced as \`icon:<key>\` wherever an icon is accepted.
+
+Each key names an app-level SVG asset by its name. Keys and asset names must consist of lower case
+letters, digits, and single hyphens. Keys are case-sensitive, and \`icon:<key>\` never falls back
+to a Font Awesome icon.
+`,
+            additionalProperties: { $ref: '#/components/schemas/IconRegistryEntryDefinition' },
+        },
         contentSecurityPolicy: {
             type: 'object',
             description: `Additional CSP source expressions for the published app page.

package/schemas/BasePageDefinition.js

@@ -48,9 +48,11 @@ navigation. Set to \`hidden\` to display no navigational menus at all.
         },
         icon: {
             type: 'string',
-            description: `An optional icon from the fontawesome icon set
+            format: 'icon',
+            description: `An optional icon from the Font Awesome icon set, or a custom icon reference.
 
-This will be displayed in the navigation menu.
+This will be displayed in the navigation menu. Use \`icon:<key>\` to reference a key from the app’s
+\`icons\` registry.
 `,
         },
         parent: {

package/schemas/IconRegistryEntryDefinition.d.ts

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

package/schemas/IconRegistryEntryDefinition.js

@@ -0,0 +1,19 @@
+import { normalized } from '../constants/index.js';
+export const IconRegistryEntryDefinition = {
+    type: 'object',
+    description: 'A custom icon in the app’s `icons` registry.',
+    required: ['asset'],
+    additionalProperties: false,
+    properties: {
+        asset: {
+            type: 'string',
+            pattern: normalized.source,
+            description: `The name of the app-level asset holding the icon’s SVG artwork.
+
+This is an asset name, not a URL or asset ID. The asset doesn’t need to exist when the app is
+published, but the icon only renders once an SVG asset with this name has been uploaded.
+`,
+        },
+    },
+};
+//# sourceMappingURL=IconRegistryEntryDefinition.js.map

package/schemas/index.d.ts

@@ -132,3 +132,4 @@ export * from './NavbarDeviceGridLayoutDefinition.js';
 export * from './NavbarLayoutDefinition.js';
 export * from './PageLayoutDefinition.js';
 export * from './PageParentDefinition.js';
+export * from './IconRegistryEntryDefinition.js';

package/schemas/index.js

@@ -132,4 +132,5 @@ export * from './NavbarDeviceGridLayoutDefinition.js';
 export * from './NavbarLayoutDefinition.js';
 export * from './PageLayoutDefinition.js';
 export * from './PageParentDefinition.js';
+export * from './IconRegistryEntryDefinition.js';
 //# sourceMappingURL=index.js.map

package/schemas/json/JSONSchemaString.js

@@ -68,6 +68,7 @@ export const JSONSchemaString = extendJSONSchema(BaseJSONSchema, {
                 'event-emitter',
                 'event-listener',
                 'fontawesome',
+                'icon',
             ],
             description: 'The format values should adhere to.',
         },

package/serverActions.d.ts

@@ -1,2 +1,2 @@
-export declare const serverActions: Set<"each" | "email" | "app.member.query" | "condition" | "log" | "noop" | "notify" | "request" | "resource.create" | "resource.delete" | "resource.delete.all" | "resource.delete.bulk" | "resource.get" | "resource.patch" | "resource.query" | "resource.update" | "static" | "throw">;
+export declare const serverActions: Set<"email" | "log" | "static" | "noop" | "throw" | "resource.get" | "resource.patch" | "resource.query" | "resource.update" | "app.member.query" | "condition" | "each" | "notify" | "request" | "resource.create" | "resource.delete.all" | "resource.delete.bulk" | "resource.delete">;
 export type ServerActionName = typeof serverActions extends Set<infer T> ? T : never;

package/types/core.d.ts

@@ -12,6 +12,23 @@ import { type Theme } from './theme.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[]>;
+/**
+ * A reference to an icon.
+ *
+ * A bare name refers to a Font Awesome icon. A name prefixed with `icon:` refers to a key in the
+ * app’s `icons` registry, which maps it to an uploaded SVG asset.
+ */
+export type IconReference = IconName | `icon:${string}`;
+export interface IconRegistryEntry {
+    /**
+     * The name of the app-level asset holding the icon’s SVG artwork.
+     */
+    asset: string;
+}
+/**
+ * A mapping of semantic icon keys to the assets holding their artwork.
+ */
+export type IconRegistry = Record<string, IconRegistryEntry>;
 export interface AppDefinition {
     /**
      * The name of the app.
@@ -171,6 +188,12 @@ export interface AppDefinition {
      * The global theme for the app.
      */
     theme?: Partial<Theme>;
+    /**
+     * Custom icons that may be referenced as `icon:<key>` from pages, blocks, and login buttons.
+     *
+     * Each key maps to an app-level SVG asset by name.
+     */
+    icons?: IconRegistry;
     /**
      * Extra content security policy source expressions for the published app page.
      *
@@ -257,11 +280,12 @@ export interface BasePageDefinition {
      */
     roles?: ViewRole[];
     /**
-     * An optional icon from the fontawesome icon set
+     * An optional icon from the Font Awesome icon set, or an `icon:<key>` reference to the app’s
+     * `icons` registry.
      *
      * This will be displayed in the navigation menu.
      */
-    icon?: IconName;
+    icon?: IconReference;
     /**
      * Page parameters can be used for linking to a page that should display a single resource.
      */

package/validation.js

@@ -7,6 +7,7 @@ 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 { isValidIconName, parseIconReference } from './icons.js';
 import { iterAction, iterApp } from './iterApp.js';
 import { has } from './miscellaneous.js';
 import { normalize } from './normalize.js';
@@ -1238,6 +1239,101 @@ function validateResourceReferences(definition, report) {
         }
     }
 }
+function validateIcons({ icons }, report) {
+    if (!icons) {
+        return;
+    }
+    for (const key of Object.keys(icons)) {
+        if (!isValidIconName(key)) {
+            report(key, 'is not a valid icon key; use lower case letters, digits, and single hyphens', [
+                'icons',
+                key,
+            ]);
+        }
+    }
+}
+/**
+ * Collect the string values of an instance which its schema marks with the given format.
+ *
+ * Schema references, nested objects, arrays, and composition keywords are followed.
+ *
+ * @param instance The value to inspect.
+ * @param schema The schema describing the value.
+ * @param root The root schema, used to resolve local `$ref`s to its definitions.
+ * @param format The format to look for.
+ * @param path The path of the instance, used for reporting.
+ * @param found The collected values, keyed by their JSON path.
+ */
+function collectFormattedStrings(instance, schema, root, format, path, found) {
+    if (!schema || typeof schema !== 'object') {
+        return;
+    }
+    if (schema.$ref) {
+        const match = /^#\/definitions\/(.+)$/.exec(schema.$ref);
+        if (match) {
+            collectFormattedStrings(instance, root.definitions?.[decodeURIComponent(match[1])], root, format, path, found);
+        }
+        return;
+    }
+    if (typeof instance === 'string') {
+        if (schema.format === format) {
+            found.set(JSON.stringify(path), [path, instance]);
+        }
+    }
+    else if (Array.isArray(instance)) {
+        for (const [index, item] of instance.entries()) {
+            const itemSchema = Array.isArray(schema.items)
+                ? (schema.items[index] ??
+                    (typeof schema.additionalItems === 'object' ? schema.additionalItems : undefined))
+                : schema.items;
+            collectFormattedStrings(item, itemSchema, root, format, [...path, index], found);
+        }
+    }
+    else if (typeof instance === 'object' && instance) {
+        for (const [key, value] of Object.entries(instance)) {
+            const propertySchema = has(schema.properties, key)
+                ? schema.properties[key]
+                : (Object.entries(schema.patternProperties ?? {}).find(([pattern]) => new RegExp(pattern).test(key))?.[1] ??
+                    (typeof schema.additionalProperties === 'object'
+                        ? schema.additionalProperties
+                        : undefined));
+            collectFormattedStrings(value, propertySchema, root, format, [...path, key], found);
+        }
+    }
+    for (const branches of [schema.anyOf, schema.oneOf, schema.allOf]) {
+        for (const branch of branches ?? []) {
+            collectFormattedStrings(instance, branch, root, format, path, found);
+        }
+    }
+}
+function validateIconReferences(definition, blockVersions, report) {
+    const check = (reference, path) => {
+        // Syntax errors are reported by the schema validation and invalid registry entries by
+        // validateIcons; only check registry membership here.
+        const parsed = parseIconReference(reference);
+        if (parsed.type === 'custom' && !has(definition.icons, parsed.key)) {
+            report(reference, `references the unknown icon key “${parsed.key}”`, path);
+        }
+    };
+    iterApp(definition, {
+        onPage(page, path) {
+            if (typeof page.icon === 'string') {
+                check(page.icon, [...path, 'icon']);
+            }
+        },
+        onBlock(block, path) {
+            const version = blockVersions.get(normalizeBlockName(block.type))?.get(block.version);
+            if (!version?.parameters || !block.parameters) {
+                return;
+            }
+            const found = new Map();
+            collectFormattedStrings(block.parameters, version.parameters, version.parameters, 'icon', [...path, 'parameters'], found);
+            for (const [iconPath, reference] of found.values()) {
+                check(reference, iconPath);
+            }
+        },
+    });
+}
 function validateLanguage({ defaultLanguage }, report) {
     if (defaultLanguage != null && !languageTags.check(defaultLanguage)) {
         report(defaultLanguage, 'is not a valid language code', ['defaultLanguage']);
@@ -1667,6 +1763,8 @@ export async function validateAppDefinition(definition, getBlockVersions, contro
         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);