@appsemble/sdk 0.39.2 → 0.40.1

package/README.md

@@ -1,9 +1,9 @@
-# ![](https://gitlab.com/appsemble/appsemble/-/raw/0.39.2/config/assets/logo.svg) Appsemble SDK
+# ![](https://gitlab.com/appsemble/appsemble/-/raw/0.40.1/config/assets/logo.svg) Appsemble SDK
 
 > Build your own blocks
 
 [![npm](https://img.shields.io/npm/v/@appsemble/sdk)](https://www.npmjs.com/package/@appsemble/sdk)
-[![GitLab CI](https://gitlab.com/appsemble/appsemble/badges/0.39.2/pipeline.svg)](https://gitlab.com/appsemble/appsemble/-/releases/0.39.2)
+[![GitLab CI](https://gitlab.com/appsemble/appsemble/badges/0.40.1/pipeline.svg)](https://gitlab.com/appsemble/appsemble/-/releases/0.40.1)
 [![Prettier](https://img.shields.io/badge/code_style-prettier-ff69b4.svg)](https://prettier.io)
 
 ## Table of Contents
@@ -153,5 +153,5 @@ declare module '@appsemble/sdk' {
 
 ## License
 
-[LGPL-3.0-only](https://gitlab.com/appsemble/appsemble/-/blob/0.39.2/LICENSE.md) ©
+[LGPL-3.0-only](https://gitlab.com/appsemble/appsemble/-/blob/0.40.1/LICENSE.md) ©
 [Appsemble](https://appsemble.com)

package/index.d.ts

@@ -1,13 +1,46 @@
-import { type Action, type ActionError, type BaseMessage, type Theme } from '@appsemble/lang-sdk';
+import { type Action, type ActionError, type BaseMessage, type IconReference, type IconRegistry, type IconRegistryEntry, type Theme } from '@appsemble/lang-sdk';
 import { type BulmaColor, type BulmaSize } from '@appsemble/types';
 import { type IconName } from '@fortawesome/fontawesome-common-types';
 import { type Promisable } from 'type-fest';
-export { type IconName };
+export { type IconName, type IconReference, type IconRegistry, type IconRegistryEntry };
 export { type Action, type BulmaColor, type BulmaSize, type Theme };
 /**
  * A user defined remapper function.
  */
 export type Remapper = object[] | boolean | number | object | string;
+/**
+ * Options for rendering an icon.
+ */
+export interface IconRenderOptions {
+    /**
+     * An additional CSS class to apply to the outer `.icon` wrapper.
+     */
+    className?: string;
+    /**
+     * The Bulma size modifier of the wrapper.
+     */
+    size?: BulmaSize;
+    /**
+     * The size modifier of a Font Awesome glyph. Defaults to a value derived from `size`.
+     *
+     * Custom icons fill the wrapper, so only `size` affects them.
+     */
+    iconSize?: '2x' | '3x' | 'lg';
+}
+/**
+ * An icon reference resolved against the app’s icon registry.
+ *
+ * Invalid references, including registry keys which don’t exist, never produce a URL.
+ */
+export type RenderableIcon = {
+    type: 'asset';
+    url: string;
+} | {
+    type: 'fontawesome';
+    name: IconName;
+} | {
+    type: 'invalid';
+};
 /**
  * Actions defined on a block.
  *
@@ -107,7 +140,7 @@ export interface MenuItem {
     /**
      * The icon to display next to the title.
      */
-    icon?: IconName;
+    icon?: IconReference;
     /**
      * The color to use for the icon.
      */
@@ -192,6 +225,23 @@ export interface BlockUtils extends Utils {
      * @returns String containing the FontAwesome classes for the icon.
      */
     fa: (icon: IconName) => string;
+    /**
+     * Resolve a Font Awesome icon name or an `icon:<key>` reference against the app’s icon registry.
+     *
+     * @param reference The icon reference to resolve.
+     * @returns A Font Awesome name, the URL of a custom icon asset, or an invalid result.
+     */
+    resolveIcon: (reference: IconReference) => RenderableIcon;
+    /**
+     * Create a DOM element rendering a Font Awesome icon or a custom icon from the app’s registry.
+     *
+     * Each call returns a fresh `.icon` wrapper. Replace the element when the reference changes.
+     *
+     * @param reference The icon reference to render.
+     * @param options Rendering options.
+     * @returns A span element containing the glyph or image.
+     */
+    icon: (reference: IconReference, options?: IconRenderOptions) => HTMLSpanElement;
     /**
      * @param items The list of menu items to display.
      * @param header A header that can be used to separate from other block menus.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@appsemble/sdk",
-  "version": "0.39.2",
+  "version": "0.40.1",
   "description": "Build your own blocks",
   "keywords": [
     "app",
@@ -43,8 +43,8 @@
     "test": "vitest"
   },
   "dependencies": {
-    "@appsemble/types": "0.39.2",
-    "@appsemble/lang-sdk": "0.39.2",
+    "@appsemble/types": "0.40.1",
+    "@appsemble/lang-sdk": "0.40.1",
     "@fortawesome/fontawesome-common-types": "^6.0.0",
     "type-fest": "^4.0.0"
   },