APL-CORE: December 2024 Release of APL 2024.3 compliant core engine (2024.3.0)

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: middendc

Diff for: CHANGELOG.md

@@ -1,5 +1,21 @@
 # Changelog
 
+## [2024.3]
+This release adds support for version 2024.3 of the APL specification.
+
+### Added
+
+- Add the ImportPackage Command. Refactored the APL Package section to consolidate common package definitions. Included the accept property for all package loading. Add an environment property packages to list packages loaded at document inflation.
+- Add List tags to support bulleted lists.
+- Add data as allowed image source type.
+- Add FlexSequence Component.
+- Add role to context elements.
+- Add the String.indexOf, String.lastIndexOf, and String.includes functions to String functions.
+
+### Changed
+- Bug fixes.
+- Performance improvements.
+
 ## [2024.2]
 
 This release adds support for version 2024.2 of the APL specification.

Diff for: android/README.md

@@ -0,0 +1,11 @@
+# Introduction
+This folder contains an Android gradle project that will build *APLCoreEngine* with the Android SDK/NDK and publish the static library binaries as a prefab with a coordinate of `com.amazon.apl.android:coreengine`.
+
+# Publishing
+By default, the gradle project contains the `publishToMavenLocal` task which will publish `com.amazon.apl.android:coreengine` to a local maven repository. Additional publish targets must be added by the user.
+
+# Unit Tests
+In order to run unit tests that include coverage of calls made to native libraries, this gradle project is capable of building *APLCoreEngine* using the default tool chain located on the host computer. Invoking the gradle task `buildHostBinary` will build `apl` and `alexaext` static libraries capable of being used in unit tests.
+
+# Shortcuts
+Running the `localBuild` task will call both `publishToMavenLocal` and `buildHostBinary` automatically.

Diff for: android/build.gradle

@@ -5,7 +5,7 @@
 
 // Top-level build file where you can add configuration options common to all sub-projects/modules.
 
-def version = "2024.2.0";
+def version = "2024.3.0";
 
 buildscript {
     repositories {

Diff for: android/coreengine/build.gradle

@@ -39,6 +39,12 @@ android {
         }
     }
 
+    sourceSets {
+        main {
+            // No java sources.
+            java.srcDirs = []
+        }
+    }
     buildTypes {
         releaseWithSceneGraph {
             minifyEnabled false
@@ -108,6 +114,13 @@ publishing {
 task buildHostBinary(type: com.amazon.apl.android.CMakeTask) {
     cmakeArgs cmakeArg
     makeTargets "apl", "alexaext"
+    doLast {
+        copy {
+            from fileTree(dir: '.cxx/cmake/debug/host/', include: '**/*.a').files
+            include '**/*.a'
+            into '../build'
+        }
+    }
 }
 
 project.afterEvaluate {
@@ -122,10 +135,7 @@ project.afterEvaluate {
 }
 
 task release(dependsOn: ['build', 'publish', 'buildHostBinary']) {
-    doLast {
-        copy {
-            from '.cxx/cmake/debug/host/'
-            into '../build'
-        }
-    }
 }
+
+task localBuild(dependsOn: ['build', 'publishToMavenLocal', 'buildHostBinary']) {
+}

Diff for: apl-dev-env.sh

@@ -136,9 +136,8 @@ function apl-test-core {  # Run unit tests in the core build
                -DBUILD_ALEXAEXTENSIONS=ON \
                -DENABLE_SCENEGRAPH=ON .. && \
         make -j$APL_BUILD_PROCS && \
-        aplcore/unit/unittest && \
-        tools/unit/tools-unittest && \
-        extensions/unit/alexaext-unittest
+        aplcore/unit/unittest $@ && \
+        extensions/unit/alexaext-unittest $@
     )
 }
 
@@ -148,7 +147,6 @@ function apl-memcheck-core {  # Run unit tests in the core build
         $CMAKE -DBUILD_TESTS=ON  -DCOVERAGE=OFF .. && \
         make -j$APL_BUILD_PROCS && \
         valgrind --tool=memcheck --gen-suppressions=all --track-origins=yes --leak-check=full --num-callers=50 ./aplcore/unit/unittest && \
-        valgrind --tool=memcheck --gen-suppressions=all --track-origins=yes --leak-check=full --num-callers=50 ./tools/unit/tools-unittest && \
         valgrind --tool=memcheck --gen-suppressions=all --track-origins=yes --leak-check=full --num-callers=50 ./extensions/unit/alexaext-unittest
     )
 }

Diff for: aplcore/CMakeLists.txt

@@ -88,6 +88,7 @@ add_subdirectory(src/touch)
 add_subdirectory(src/utils)
 add_subdirectory(src/versioning)
 add_subdirectory(src/scenegraph)
+add_subdirectory(src/yoga)
 
 set(
     PUBLIC_HEADER_LIST

Diff for: aplcore/include/apl/action/action.h

@@ -28,6 +28,7 @@ namespace apl {
 
 // Forward declarations
 class ActionRef;
+class ActionData;
 
 using ActionList = std::vector<ActionPtr>;
 
@@ -200,6 +201,12 @@ class Action : public std::enable_shared_from_this<Action>,
      */
     virtual bool rehydrate(const CoreDocumentContext& context);
 
+    /**
+     * Get details about this action
+     * @return ActionData including details about target component and command (if any).
+     */
+    virtual ActionData getActionData();
+
 protected:
     virtual void onFinish() {}
 

Diff for: aplcore/include/apl/action/animatedscrollaction.h

@@ -41,6 +41,7 @@ class AnimatedScrollAction : public ResourceHoldingAction {
     void scroll(bool vertical, const Point& position);
 
     CoreComponentPtr mContainer;
+    ActionData getActionData() override;
 
 private:
     void advance();

Diff for: aplcore/include/apl/action/animateitemaction.h

@@ -39,6 +39,7 @@ class AnimateItemAction : public ResourceHoldingAction {
 
     void freeze() override;
     bool rehydrate(const CoreDocumentContext& context) override;
+    ActionData getActionData() override;
 
 private:
     void start();

Diff for: aplcore/include/apl/action/autopageaction.h

@@ -42,6 +42,7 @@ class AutoPageAction : public ResourceHoldingAction {
 
     void freeze() override;
     bool rehydrate(const CoreDocumentContext& context) override;
+    ActionData getActionData() override;
 
 private:
     void advance();

Diff for: aplcore/include/apl/action/controlmediaaction.h

@@ -37,6 +37,8 @@ class ControlMediaAction : public ResourceHoldingAction {
                        const std::shared_ptr<CoreCommand>& command,
                        const ComponentPtr& target);
 
+    ActionData getActionData() override;
+
 private:
     void start();
 

Diff for: aplcore/include/apl/action/playmediaaction.h

@@ -41,6 +41,7 @@ class PlayMediaAction : public ResourceHoldingAction {
 
     void freeze() override;
     bool rehydrate(const CoreDocumentContext& context) override;
+    ActionData getActionData() override;
 
 private:
     void start();

Diff for: aplcore/include/apl/action/setpageaction.h

@@ -38,6 +38,7 @@ class SetPageAction : public ResourceHoldingAction {
 
     void freeze() override;
     bool rehydrate(const CoreDocumentContext& context) override;
+    ActionData getActionData() override;
 
 private:
     void start();

Diff for: aplcore/include/apl/action/speakitemaction.h

@@ -54,11 +54,7 @@ class SpeakItemAction : public ResourceHoldingAction {
 
     void freeze() override;
     bool rehydrate(const CoreDocumentContext& context) override;
-
-private:
-    void start();
-    void scroll(const std::shared_ptr<ScrollToAction>& action);
-    void advance();
+    ActionData getActionData() override;
 
 private:
     friend class SpeakListAction;
@@ -69,10 +65,6 @@ class SpeakItemAction : public ResourceHoldingAction {
     std::string mSource;  // The URL of the audio file to play
 
     friend class SpeakItemActionPrivate;
-#ifdef SCENEGRAPH
-    friend class SpeakItemActionPrivateSceneGraph;
-#endif // SCENEGRAPH
-    friend class SpeakItemActionPrivateEvents;
     std::unique_ptr<SpeakItemActionPrivate> mPrivate;
 };
 

Diff for: aplcore/include/apl/apl.h

@@ -75,6 +75,7 @@
 #include "apl/primitives/urlrequest.h"
 #include "apl/scaling/metricstransform.h"
 #include "apl/touch/pointerevent.h"
+#include "apl/utils/dataurl.h"
 #include "apl/utils/localemethods.h"
 #include "apl/utils/log.h"
 #include "apl/utils/session.h"

Diff for: aplcore/include/apl/command/corecommand.h

@@ -119,6 +119,9 @@ class CoreCommand : public Command {
     const bool        mScreenLock;
     std::string       mSequencer;
 
+private:
+    void logProperties();
+
 private:
     std::string mBaseId;
     std::string mTargetId;

Diff for: aplcore/include/apl/common.h

@@ -71,6 +71,7 @@ class CoreDocumentContext;
 class CoreRootContext;
 class DataSource;
 class DataSourceProvider;
+class DataUrl;
 class Dependant;
 class DependantManager;
 class DocumentConfig;
@@ -128,6 +129,7 @@ using ConstCoreComponentPtr = std::shared_ptr<const CoreComponent>;
 using CoreDocumentContextPtr = std::shared_ptr<CoreDocumentContext>;
 using CoreRootContextPtr = std::shared_ptr<CoreRootContext>;
 using DataSourceProviderPtr = std::shared_ptr<DataSourceProvider>;
+using DataUrlPtr = std::shared_ptr<DataUrl>;
 using DependantPtr = std::shared_ptr<Dependant>;
 using DocumentConfigPtr = std::shared_ptr<DocumentConfig>;
 using DocumentContextDataPtr = std::shared_ptr<DocumentContextData>;

Diff for: aplcore/include/apl/component/component.h

@@ -222,7 +222,7 @@ class Component : public UIDObject,
      * @param key The PropertyKey of the prop to return.
      * @return The current value assigned to that property.
      */
-    const Object& getCalculated( PropertyKey key ) const { return mCalculated.get(key); }
+    const Object& getCalculated( PropertyKey key ) const;
 
     /**
      * @return The primitive type of the component.
@@ -251,15 +251,14 @@ class Component : public UIDObject,
     ConstContextPtr getContext() const { return mContext; }
 
     /**
-     * @return True if this component was properly created with all required
-     *         properties specified.
+     * @return True if this component was properly created and can be used from an external API standpoint.
      */
-    bool isValid() { return !mFlags.isSet(kComponentFlagInvalid); }
+    bool isValid() const { return !mFlags.isSet(kComponentFlagInvalid) && !mFlags.isSet(kComponentFlagIsReleased); }
 
     /**
      * @return True if this component has been inflated and should now run event handlers on a SetValue or equivalent.
      */
-    bool allowEventHandlers() { return mFlags.isSet(kComponentFlagAllowEventHandlers);}
+    bool allowEventHandlers() const { return mFlags.isSet(kComponentFlagAllowEventHandlers);}
 
     /**
      * An update message from the viewhost.  This method is used for all updates that take
@@ -280,8 +279,9 @@ class Component : public UIDObject,
     /**
      * Update component media state. Not applicable for every component.
      * @param state component's MediaState.
+     * @deprecated Use MediaPlayer interface.
      */
-    virtual void updateMediaState(const MediaState& state, bool fromEvent = false);
+    virtual void updateMediaState(const MediaState& state, bool fromEvent = false) { aplThrow(NOT_SUPPORTED_ERROR); }
 
     /**
      * Update graphics display.  Not applicable for every component.
@@ -524,6 +524,7 @@ class Component : public UIDObject,
     enum ComponentFlags : uint8_t {
         kComponentFlagInvalid = 1u << 0,  // Marks a component missing a required property
         kComponentFlagAllowEventHandlers = 1u << 1,  // Event handlers don't run when the component is first inflated
+        kComponentFlagIsReleased = 1u << 2,  // Component was released and no longer valid
     };
 
     Flags<ComponentFlags>  mFlags;

Diff for: aplcore/include/apl/component/componentpropdef.h

@@ -18,13 +18,12 @@
 
 #include "apl/component/component.h"
 #include "apl/engine/propdef.h"
-
-#include <yoga/YGNode.h>
+#include "apl/yoga/yoganode.h"
 
 namespace apl {
 
 using Trigger = void (*)(Component&);
-using LayoutFunc = void (*)(YGNodeRef nodeRef, const Object& object, const Context& context);
+using LayoutFunc = void (*)(YogaNode& node, const Object& object, const Context& context);
 using DefaultFunc = Object (*)(Component&, const RootConfig&);
 using GetterFunc = Object (*)(const CoreComponent&);
 using SetterFunc = void (*)(CoreComponent&, const Object&);

Diff for: aplcore/include/apl/component/componentproperties.h

@@ -92,6 +92,16 @@ enum FlexboxAlign {
     kFlexboxAlignAuto = 5
 };
 
+/**
+ * Used by alignItems in a FlexSequenceComponent
+ * Don't change these values without checking component.cpp
+ */
+enum FlexboxAlignAxis {
+    kFlexboxAlignAxisStart = 0,
+    kFlexboxAlignAxisEnd = 1,
+    kFlexboxAlignAxisCenter = 2
+};
+
 /**
  * Layout direction of a ContainerComponent
  */
@@ -746,6 +756,8 @@ enum PropertyKey {
     kPropertyOnCursorEnter,
     /// Component handler for cursor exit
     kPropertyOnCursorExit,
+    /// Component handler for cursor move
+    kPropertyOnCursorMove,
     /// Component attached to Yoga tree and has flexbox properties calculated.
     kPropertyLaidOut,
     /// EditTextComponent restrict the characters that can be entered
@@ -771,7 +783,8 @@ enum ComponentType {
     kComponentTypeText,
     kComponentTypeTouchWrapper,
     kComponentTypeVectorGraphic,
-    kComponentTypeVideo
+    kComponentTypeVideo,
+    kComponentTypeFlexSequenceComponent
 };
 
 extern Bimap<int, std::string> sAlignMap;
@@ -783,6 +796,7 @@ extern Bimap<int, std::string> sTextAlignVerticalMap;
 extern Bimap<int, std::string> sKeyboardTypeMap;
 extern Bimap<int, std::string> sSubmitKeyTypeMap;
 extern Bimap<int, std::string> sFlexboxAlignMap;
+extern Bimap<int, std::string> sFlexboxAlignAxisMap;
 extern Bimap<int, std::string> sContainerDirectionMap;
 extern Bimap<int, std::string> sFlexboxJustifyContentMap;
 extern Bimap<int, std::string> sFlexboxWrapMap;