November 2023 Release of the APL 2023.3 compliant APL Viewhost Web

For more details on this release refer to CHANGELOG.md

To learn about APL see: https://developer.amazon.com/docs/alexa-presentation-language/understand-apl.html

Author: amzn-admfox

CHANGELOG.md

@@ -1,25 +1,38 @@
 # Changelog for apl-viewhost-web
 
+## [2023.3]
+This release adds support for version 2023.3 of the APL specification. Please also see APL Core Library for changes: [apl-core-library CHANGELOG](https://github.com/alexa/apl-core-library/blob/master/CHANGELOG.md)
+ 
+### Added
+- Add support for conditional import
+- Add support for auto sizing
+- Add support gradient as Frame background
+- Exported caption control class `cueControl` for APL videos
+ 
+### Changed
+- Changed default font to sans-serif to meet the APL Spec
+- Bug fixes
+ 
 ## [2023.2]
 This release adds support for version 2023.2 of the APL specification. Please also see APL Core Library for changes: [apl-core-library CHANGELOG](https://github.com/alexa/apl-core-library/blob/master/CHANGELOG.md)
-
+ 
 ### Added
 - Add support for the seekTo ControlMedia command
-
+ 
 ### Changed
 - Remove usage of APL Core Library's deprecated getTheme API
 - Bug fixes
-
+ 
 ## [2023.1]
 This release adds support for version 2023.1 of the APL specification. Please also see APL Core Library for changes: [apl-core-library CHANGELOG](https://github.com/alexa/apl-core-library/blob/master/CHANGELOG.md)
-
+ 
 ### Added
 - SRT support for APL Video textTrack
 - Support for new Porter-Duff blend modes
-
+ 
 ### Changed
 - Bug fixes
-
+ 
 ## [2022.2]
 This release adds support for version 2022.2 of the APL specification. Please also see APL Core Library for changes: [apl-core-library CHANGELOG](https://github.com/alexa/apl-core-library/blob/master/CHANGELOG.md)
 

README.md

@@ -1,10 +1,10 @@
 # Alexa Presentation Language (APL) Viewhost Web
 
 <p>
- <a href="https://github.com/alexa/apl-viewhost-web/tree/v2023.2.0" alt="version">
- <img src="https://img.shields.io/badge/stable%20version-2023.2.0-brightgreen" /></a>
- <a href="https://github.com/alexa/apl-core-library/tree/v2023.2.0" alt="APLCore">
- <img src="https://img.shields.io/badge/apl%20core%20library-2023.2.0-navy" /></a>
+ <a href="https://github.com/alexa/apl-viewhost-web/tree/v2023.3.0" alt="version">
+ <img src="https://img.shields.io/badge/stable%20version-2023.3.0-brightgreen" /></a>
+ <a href="https://github.com/alexa/apl-core-library/tree/v2023.3.0" alt="APLCore">
+ <img src="https://img.shields.io/badge/apl%20core%20library-2023.3.0-navy" /></a>
 </p>
 
 ## Introduction

js/apl-html/lib/dts/ConfigurationChange.d.ts

@@ -7,6 +7,8 @@ declare namespace APL {
     export class ConfigurationChange extends Deletable {
         public static create() : ConfigurationChange;
         public size(width : number, height : number) : ConfigurationChange;
+        public sizeRange(width : number, minWidth : number, maxWidth : number,
+                         height : number, minHeight : number, maxHeight : number) : ConfigurationChange;
         public theme(theme : string) : ConfigurationChange;
         public viewportMode(viewportMode : string) : ConfigurationChange;
         public fontScale(scale : number) : ConfigurationChange;

js/apl-html/lib/dts/Content.d.ts

@@ -17,6 +17,7 @@ declare namespace APL {
 
     export class Content extends Deletable {
         public static create(document: string): Content;
+        public refresh(metrics: Metrics, config: RootConfig): void;
         public getRequestedPackages(): Set<ImportRequest>;
         public addPackage(request: ImportRequest, data: string): void;
         public isError(): boolean;

js/apl-html/lib/dts/Context.d.ts

@@ -81,6 +81,8 @@ declare namespace APL {
 
         public nextTime(): number;
 
+        public getViewportPixelSize(): object[];
+
         public getViewportWidth(): number;
 
         public getViewportHeight(): number;

js/apl-html/lib/dts/Metrics.d.ts

@@ -11,5 +11,7 @@ declare namespace APL {
         public theme(theme : string) : Metrics;
         public shape(shape : string) : Metrics;
         public mode(mode : string) : Metrics;
+        public minAndMaxWidth(minWidth : number, maxWidth : number) : Metrics;
+        public minAndMaxHeight(minHeight : number, maxHeight : number) : Metrics;
     }
 }

js/apl-html/package.json

@@ -52,8 +52,5 @@
     "webpack-cli": "^3.3.12",
     "webpack-merge": "^4.2.1",
     "xregexp": "4.2.4"
-  },
-  "npm-pretty-much": {
-    "legacyPackageNameAlias": "apl-html"
   }
 }

js/apl-html/src/APLRenderer.ts

@@ -13,6 +13,7 @@ import { MeasureMode } from './components/text/MeasureMode';
 import { TextMeasurement } from './components/text/Text';
 import { IVideoFactory } from './components/video/IVideoFactory';
 import { VideoFactory } from './components/video/VideoFactory';
+import { Content } from './Content';
 import { AnimationQuality } from './enums/AnimationQuality';
 import { DisplayState } from './enums/DisplayState';
 import { FocusDirection } from './enums/FocusDirection';
@@ -67,6 +68,15 @@ export interface IViewportCharacteristics {
     shape?: ViewportShape;
     /** Dots per inch */
     dpi: number;
+    /** Providing the min & max will turn on auto-sizing feature */
+    /** The minimum width of the viewport, in pixels */
+    minWidth?: number;
+    /** The maximum width of the viewport, in pixels */
+    maxWidth?: number;
+    /** The minimum height of the viewport, in pixels */
+    minHeight?: number;
+    /** The maximum height of the viewport, in pixels */
+    maxHeight?: number;
 }
 
 export interface IEnvironmentBase {
@@ -110,8 +120,20 @@ export interface IConfigurationChangeOptions extends IEnvironmentBase {
     width?: number;
     /** Viewport Height in pixels */
     height?: number;
+    /** Providing the min & max will turn on auto-sizing feature. Must provide all of the 6 values:
+     *  minWidth, maxWidth, minHeight, maxHeight, width, height
+     */
+    /** The minimum width of the viewport, in pixels */
+    minWidth?: number;
+    /** The maximum width of the viewport, in pixels */
+    maxWidth?: number;
+    /** The minimum height of the viewport, in pixels */
+    minHeight?: number;
+    /** The maximum height of the viewport, in pixels */
+    maxHeight?: number;
     /** APL theme. Usually 'light' or 'dark' */
     docTheme?: string;
+    theme?: string;
     /** Device mode. If no provided "HUB" is used. */
     mode?: DeviceMode;
     /** Relative size of fonts to display as specified by the OS accessibility settings */
@@ -250,6 +272,12 @@ export interface IAPLOptions {
      */
     onOpenUrl?: (source: string) => Promise<boolean>;
 
+    /**
+     * Callback for view size update during auto-resizing. width and height in pixels
+     * Runtime should return quickly as this method blocks the rendering path
+     */
+    onViewportSizeUpdate?: (pixelWidth: number, pixelHeight: number) => void;
+
     /**
      * Contains developer tool options
      */
@@ -315,6 +343,8 @@ export default abstract class APLRenderer<Options = any> {
      */
     protected abstract getAudioPlayerFactory(): IAudioPlayerFactory;
 
+    public content: Content;
+
     /** A reference to the APL root context */
     public context: APL.Context;
 
@@ -403,6 +433,24 @@ export default abstract class APLRenderer<Options = any> {
      */
     private isEdge: boolean = browserIsEdge(window.navigator.userAgent);
 
+    /**
+     * @internal
+     * @ignore
+     */
+    private lastKnownViewWidth: number = 0;
+
+    /**
+     * @internal
+     * @ignore
+     */
+    private lastKnownViewHeight: number = 0;
+
+    /**
+     * @internal
+     * @ignore
+     */
+    protected isAutoSizing: boolean = false;
+
     public get options(): Options {
         return this.mOptions as any as Options;
     }
@@ -423,7 +471,9 @@ export default abstract class APLRenderer<Options = any> {
         }
 
         this.view = mOptions.view;
-        this.setViewSize(mOptions.viewport.width, mOptions.viewport.height);
+        this.lastKnownViewWidth = mOptions.viewport.width;
+        this.lastKnownViewHeight = mOptions.viewport.height;
+        this.setViewSize(this.lastKnownViewWidth, this.lastKnownViewHeight);
         if (mOptions.viewport.shape === 'ROUND') {
             this.view.style.clipPath = 'circle(50%)';
         } else {
@@ -507,6 +557,9 @@ export default abstract class APLRenderer<Options = any> {
         if (mOptions.onResizingIgnored) {
             this.onResizingIgnored = mOptions.onResizingIgnored;
         }
+        if (mOptions.onViewportSizeUpdate) {
+            this.onViewportSizeUpdate = mOptions.onViewportSizeUpdate;
+        }
 
         this.maxTimeDeltaBetweenFrames = (1000 * this.TOLERANCE / this.MAXFPS);
     }
@@ -533,6 +586,10 @@ export default abstract class APLRenderer<Options = any> {
         this.requestId = requestAnimationFrame(this.update);
     }
 
+    public async loadPackages(): Promise<boolean> {
+        return true;
+    }
+
     /**
      * Sets the renderer view size in pixels
      * @param width width in pixels
@@ -560,10 +617,23 @@ export default abstract class APLRenderer<Options = any> {
      * @param configurationChangeOptions The configuration change options to provide to core.
      */
     public onConfigurationChange(configurationChangeOptions: IConfigurationChangeOptions): void {
-        if (!this.supportsResizing && (configurationChangeOptions.width || configurationChangeOptions.height)) {
+        if (configurationChangeOptions.minWidth && configurationChangeOptions.maxWidth &&
+            configurationChangeOptions.maxHeight && configurationChangeOptions.minHeight &&
+            configurationChangeOptions.minWidth > configurationChangeOptions.maxWidth &&
+            configurationChangeOptions.minHeight > configurationChangeOptions.maxHeight) {
+            throw new Error(`Invalid Configuration Change Options. minWidth > maxWidth and minHeight > maxHeight`);
+        }
+
+        if (configurationChangeOptions.minWidth && configurationChangeOptions.maxWidth &&
+            configurationChangeOptions.maxHeight && configurationChangeOptions.minHeight &&
+            configurationChangeOptions.minWidth < configurationChangeOptions.maxWidth &&
+            configurationChangeOptions.minHeight < configurationChangeOptions.maxHeight) {
+            this.isAutoSizing = true;
+        }
+
+        if (!this.supportsResizing && !this.isAutoSizing &&
+            (configurationChangeOptions.width || configurationChangeOptions.height)) {
             this.onResizingIgnored(configurationChangeOptions.width, configurationChangeOptions.height);
-            configurationChangeOptions.width = undefined;
-            configurationChangeOptions.height = undefined;
         }
         this.configurationChangeThrottle(configurationChangeOptions);
     }
@@ -723,6 +793,11 @@ export default abstract class APLRenderer<Options = any> {
         this.logger.warn(`onResizeIgnored: width: ${ignoredWidth}, height: ${ignoredHeight}`);
     }
 
+    public onViewportSizeUpdate(width: number, height: number): void {
+        this.logger.warn(`resize function not provided. Using default size: ${width} x ${height}`);
+        this.setViewSize(width, height);
+    }
+
     /**
      * Called by core when a text measure is required
      * @param component The component to measure
@@ -734,7 +809,13 @@ export default abstract class APLRenderer<Options = any> {
      */
     public onMeasure(component: APL.Component, measureWidth: number, widthMode: MeasureMode,
                      measureHeight: number, heightMode: MeasureMode) {
-        const {width, height} = this.mOptions.viewport;
+        let {width, height} = this.mOptions.viewport;
+        if (this.mOptions.viewport.maxWidth) {
+            width = this.mOptions.viewport.maxWidth;
+        }
+        if (this.mOptions.viewport.maxHeight) {
+            height = this.mOptions.viewport.maxHeight;
+        }
         const comp = new TextMeasurement(component, width, height);
         comp.init();
         return comp.onMeasure(measureWidth, widthMode, measureHeight, heightMode);
@@ -986,8 +1067,13 @@ export default abstract class APLRenderer<Options = any> {
             commandFactory(event, this);
         }
 
+        if (this.content && !this.content.isReady()) {
+            return;
+        }
+
         if (this.context) {
             if (this.context.isDirty()) {
+                this.checkAndUpdateViewportSize();
                 const dirtyComponents = this.context.getDirty();
                 for (const dirtyId of dirtyComponents) {
                     const component = this.componentMap[dirtyId];
@@ -1222,6 +1308,8 @@ export default abstract class APLRenderer<Options = any> {
             // already rendered
             return;
         }
+
+        this.checkAndUpdateViewportSize();
         const top = this.context.topComponent();
         this.top = componentFactory(this, top) as Component;
         this.view.appendChild(this.top.container);
@@ -1306,4 +1394,20 @@ export default abstract class APLRenderer<Options = any> {
             }
         }
     }
+
+    /**
+     * @internal
+     * @ignore
+     */
+    private checkAndUpdateViewportSize(): void {
+        const newSize = this.context.getViewportPixelSize();
+
+        if (this.lastKnownViewWidth !== newSize['width'] ||
+            this.lastKnownViewHeight !== newSize['height']) {
+            this.logger.info('Viewport size updated by APL Core: ' + JSON.stringify(newSize));
+            this.lastKnownViewWidth = newSize['width'];
+            this.lastKnownViewHeight = newSize['height'];
+            this.onViewportSizeUpdate(this.lastKnownViewWidth, this.lastKnownViewHeight);
+        }
+    }
 }

js/apl-html/src/CommandFactory.ts

@@ -22,7 +22,7 @@ import { SendEvent } from './events/SendEvent';
  * @param renderer A reference to the renderer instance
  * @internal
  */
-export const commandFactory = (event: APL.Event, renderer: APLRenderer) => {
+export const commandFactory = async (event: APL.Event, renderer: APLRenderer) => {
     if (factoryMap[event.getType()]) {
         return factoryMap[event.getType()](event, renderer);
     }
@@ -45,9 +45,9 @@ const factoryMap = {
         command.execute();
         return command;
     },
-    [EventType.kEventTypeReinflate]: (event: APL.Event, renderer: APLRenderer) => {
+    [EventType.kEventTypeReinflate]: async (event: APL.Event, renderer: APLRenderer) => {
         const command = new ReInflate(event, renderer);
-        command.execute();
+        await command.execute();
         return command;
     },
     [EventType.kEventTypeFinish]: (event: APL.Event, renderer: APLRenderer) => {

js/apl-html/src/ComponentFactory.ts

@@ -12,7 +12,6 @@ import { EditText } from './components/EditText';
 import { Frame } from './components/Frame';
 import { GridSequence } from './components/GridSequence';
 import { Image } from './components/Image';
-import { NoOpComponent } from './components/NoOpComponent';
 import { PagerComponent } from './components/pager/PagerComponent';
 import { ScrollView } from './components/ScrollView';
 import { Sequence } from './components/Sequence';
@@ -72,9 +71,7 @@ const factoryMap = {
         return new Container(renderer, component, componentFactory, parent);
     },
     [ComponentType.kComponentTypeEditText]: (renderer: APLRenderer, component: APL.Component, parent?: Component) => {
-        return  renderer.options.environment.disallowEditText ?
-            new NoOpComponent(renderer, component, componentFactory, parent) :
-            new EditText(renderer, component, componentFactory, parent);
+        return new EditText(renderer, component, componentFactory, parent);
     },
     [ComponentType.kComponentTypeFrame]: (renderer: APLRenderer, component: APL.Component, parent?: Component) => {
         return new Frame(renderer, component, componentFactory, parent);
@@ -97,15 +94,12 @@ const factoryMap = {
     [ComponentType.kComponentTypeText]: (renderer: APLRenderer, component: APL.Component, parent?: Component) => {
         return new Text(renderer, component, componentFactory, parent);
     },
-    [ComponentType.kComponentTypeTouchWrapper]: (renderer: APLRenderer, component: APL.Component,
-                                                 parent?: Component) => {
+    [ComponentType.kComponentTypeTouchWrapper]: (renderer: APLRenderer, component: APL.Component, parent?: Component) => {
         return new TouchWrapper(renderer, component, componentFactory, parent);
     },
     [ComponentType.kComponentTypeVideo]: (renderer: APLRenderer, component: APL.Component, parent?: Component) => {
-        return  renderer.options.environment.disallowVideo ?
-            new NoOpComponent(renderer, component, componentFactory, parent) :
-            renderer.videoFactory.create(renderer, component, componentFactory, parent);
-        },
+        return renderer.videoFactory.create(renderer, component, componentFactory, parent);
+    },
     [ComponentType.kComponentTypeVectorGraphic]: (renderer: APLRenderer, component: APL.Component,
                                                   parent?: Component) => {
         return new VectorGraphic(renderer, component, componentFactory, new VectorGraphicElementUpdater(), parent);