JS: Expose button event type in gui/widget button callback (#4252)

* JS: Expose button event type in gui/widget button callback --nobuild * js_sdk: bump major version * unit_tests: fix js test * js: fix gui widget demo --------- Co-authored-by: Anna Antonenko <portasynthinca3@gmail.com> Co-authored-by: hedger <hedger@users.noreply.github.com>
2026-05-23 05:24:46 -07:00 · 2025-09-24 00:16:47 +02:00
parent f4138e5999
commit 8bd66c9920
15 changed files with 107 additions and 37 deletions
--- a/applications/system/js_app/packages/create-fz-app/package.json
+++ b/applications/system/js_app/packages/create-fz-app/package.json
@@ -1,6 +1,6 @@
 {
  "name": "@flipperdevices/create-fz-app",
-  "version": "0.1.1",
+  "version": "0.1.2",
  "description": "Template package for JS apps Flipper Zero",
  "bin": "index.js",
  "type": "module",
--- a/applications/system/js_app/packages/create-fz-app/template/package.json
+++ b/applications/system/js_app/packages/create-fz-app/template/package.json
@@ -6,7 +6,7 @@
    "start": "npm run build && node node_modules/@flipperdevices/fz-sdk/sdk.js upload"
  },
  "devDependencies": {
-    "@flipperdevices/fz-sdk": "^0.3",
+    "@flipperdevices/fz-sdk": "^1.0",
    "typescript": "^5.6.3"
  }
 }
--- a/applications/system/js_app/packages/fz-sdk/global.d.ts
+++ b/applications/system/js_app/packages/fz-sdk/global.d.ts
@@ -72,7 +72,7 @@
 * @brief Checks compatibility between the script and the JS SDK that the
 *        firmware provides
 * 
- * @note You're looking at JS SDK v0.3
+ * @note You're looking at JS SDK v1.0
 * 
 * @param expectedMajor JS SDK major version expected by the script
 * @param expectedMinor JS SDK minor version expected by the script
@@ -92,7 +92,7 @@ declare function sdkCompatibilityStatus(expectedMajor: number, expectedMinor: nu
 * @brief Checks compatibility between the script and the JS SDK that the
 *        firmware provides in a boolean fashion
 * 
- * @note You're looking at JS SDK v0.3
+ * @note You're looking at JS SDK v1.0
 * 
 * @param expectedMajor JS SDK major version expected by the script
 * @param expectedMinor JS SDK minor version expected by the script
@@ -105,7 +105,7 @@ declare function isSdkCompatible(expectedMajor: number, expectedMinor: number):
 * @brief Asks the user whether to continue executing the script if the versions
 *        are not compatible. Does nothing if they are.
 * 
- * @note You're looking at JS SDK v0.3
+ * @note You're looking at JS SDK v1.0
 * 
 * @param expectedMajor JS SDK major version expected by the script
 * @param expectedMinor JS SDK minor version expected by the script
--- a/applications/system/js_app/packages/fz-sdk/gpio/index.d.ts
+++ b/applications/system/js_app/packages/fz-sdk/gpio/index.d.ts
@@ -80,6 +80,7 @@ export interface Pin {
     * PWM-related methods on this pin will throw an error when called.
     * @note On Flipper Zero only pins PA4 and PA7 support PWM
     * @version Added in JS SDK 0.2, extra feature `"gpio-pwm"`
+     * @version Baseline since JS SDK 1.0
     */
    isPwmSupported(): boolean;
    /**
@@ -89,18 +90,21 @@ export interface Pin {
     * @param freq Frequency in Hz
     * @param duty Duty cycle in %
     * @version Added in JS SDK 0.2, extra feature `"gpio-pwm"`
+     * @version Baseline since JS SDK 1.0
     */
    pwmWrite(freq: number, duty: number): void;
    /**
     * Determines whether PWM is running. Throws an error if PWM is not
     * supported on this pin.
     * @version Added in JS SDK 0.2, extra feature `"gpio-pwm"`
+     * @version Baseline since JS SDK 1.0
     */
    isPwmRunning(): boolean;
    /**
     * Stops PWM. Does not restore previous pin configuration. Throws an error
     * if PWM is not supported on this pin.
     * @version Added in JS SDK 0.2, extra feature `"gpio-pwm"`
+     * @version Baseline since JS SDK 1.0
     */
    pwmStop(): void;
 }
--- a/applications/system/js_app/packages/fz-sdk/gui/icon.d.ts
+++ b/applications/system/js_app/packages/fz-sdk/gui/icon.d.ts
@@ -7,6 +7,7 @@ export type IconData = symbol & { "__tag__": "icon" };
 * Gets a built-in firmware icon for use in GUI
 * @param icon Name of the icon
 * @version Added in JS SDK 0.2, extra feature `"gui-widget"`
+ * @version Baseline since JS SDK 1.0
 */
 export declare function getBuiltin(icon: BuiltinIcon): IconData;

@@ -14,5 +15,6 @@ export declare function getBuiltin(icon: BuiltinIcon): IconData;
 * Loads a .fxbm icon (XBM Flipper sprite, from flipperzero-game-engine) for use in GUI
 * @param path Path to the .fxbm file
 * @version Added in JS SDK 0.3, extra feature `"gui-widget-extras"`
+ * @version Baseline since JS SDK 1.0
 */
 export declare function loadFxbm(path: string): IconData;
--- a/applications/system/js_app/packages/fz-sdk/gui/index.d.ts
+++ b/applications/system/js_app/packages/fz-sdk/gui/index.d.ts
@@ -133,17 +133,20 @@ export declare class View<Props extends Properties, Child> {
     * Adds a child to the View
     * @param child Child to add
     * @version Added in JS SDK 0.2, extra feature `"gui-widget"`
+     * @version Baseline since JS SDK 1.0
     */
    addChild<C extends Child>(child: C): void;
    /**
     * Removes all children from the View
     * @version Added in JS SDK 0.2, extra feature `"gui-widget"`
+     * @version Baseline since JS SDK 1.0
     */
    resetChildren(): void;
    /**
     * Removes all previous children from the View and assigns new children
     * @param children The list of children to assign
     * @version Added in JS SDK 0.2, extra feature `"gui-widget"`
+     * @version Baseline since JS SDK 1.0
     */
    setChildren(children: Child[]): void;
 }
@@ -158,7 +161,9 @@ export declare class ViewFactory<Props extends Properties, Child, V extends View
     * Create view instance with custom values, can be changed later with set()
     * @param initial Dictionary of property names to values
     * @param children Optional list of children to add to the view
-     * @version Added in JS SDK 0.1; amended in JS SDK 0.2, extra feature `"gui-widget"`
+     * @version Added in JS SDK 0.1
+     * @version Amended in JS SDK 0.2, extra feature `"gui-widget"`
+     * @version Baseline since JS SDK 1.0
     */
    makeWith(initial: Partial<Props>, children?: Child[]): V;
 }
--- a/applications/system/js_app/packages/fz-sdk/gui/widget.d.ts
+++ b/applications/system/js_app/packages/fz-sdk/gui/widget.d.ts
@@ -23,6 +23,7 @@
 * This view has the elements as its children.
 * 
 * @version Added in JS SDK 0.2, extra feature `"gui-widget"`
+ * @version Baseline since JS SDK 1.0
 * @module
 */

@@ -42,9 +43,21 @@ type TextBoxElement = { element: "text_box", stripToDots: boolean } & Position &
 type TextScrollElement = { element: "text_scroll" } & Position & Size & Text;
 type ButtonElement = { element: "button", button: "left" | "center" | "right" } & Text;
 type IconElement = { element: "icon", iconData: IconData } & Position;
-type RectElement = { element: "rect", radius: number, fill: boolean } & Position & Size; /** @version Amended in JS SDK 0.3, extra feature `"gui-widget-extras"` */
-type CircleElement = { element: "circle", radius: number, fill: boolean } & Position; /** @version Added in JS SDK 0.3, extra feature `"gui-widget-extras"` */
-type LineElement = { element: "line", x1: number, y1: number, x2: number, y2: number }; /** @version Added in JS SDK 0.3, extra feature `"gui-widget-extras"` */
+/**
+ * @version Amended in JS SDK 0.3, extra feature `"gui-widget-extras"`
+ * @version Baseline since JS SDK 1.0
+ * */
+type RectElement = { element: "rect", radius: number, fill: boolean } & Position & Size;
+/**
+ * @version Added in JS SDK 0.3, extra feature `"gui-widget-extras"`
+ * @version Baseline since JS SDK 1.0
+ * */
+type CircleElement = { element: "circle", radius: number, fill: boolean } & Position;
+/**
+ * @version Added in JS SDK 0.3, extra feature `"gui-widget-extras"`
+ * @version Baseline since JS SDK 1.0
+ * */
+type LineElement = { element: "line", x1: number, y1: number, x2: number, y2: number };

 type Element = StringMultilineElement
    | StringElement
@@ -58,12 +71,16 @@ type Element = StringMultilineElement

 type Props = {};
 type Child = Element;
+declare class ButtonEvent {
+    key: "left" | "center" | "right";
+    type: "press" | "release" | "short" | "long" | "repeat";
+}
 declare class Widget extends View<Props, Child> {
    /**
     * Event source for buttons. Only gets fired if there's a corresponding
     * button element.
     */
-    button: Contract<"left" | "center" | "right">;
+    button: Contract<ButtonEvent>;
 }
 declare class WidgetFactory extends ViewFactory<Props, Child, Widget> { }
 declare const factory: WidgetFactory;
--- a/applications/system/js_app/packages/fz-sdk/package.json
+++ b/applications/system/js_app/packages/fz-sdk/package.json
@@ -1,6 +1,6 @@
 {
  "name": "@flipperdevices/fz-sdk",
-  "version": "0.3.0",
+  "version": "1.0.0",
  "description": "Type declarations and documentation for native JS modules available on Flipper Zero",
  "keywords": [
    "flipper",
--- a/applications/system/js_app/packages/fz-sdk/serial/index.d.ts
+++ b/applications/system/js_app/packages/fz-sdk/serial/index.d.ts
@@ -29,6 +29,7 @@ export interface Framing {
 * @param framing See `Framing` type
 * @version Added in JS SDK 0.1
 * @version Added `framing` parameter in JS SDK 0.3, extra feature `"serial-framing"`
+ * @version Baseline since JS SDK 1.0
 */
 export declare function setup(port: "lpuart" | "usart", baudRate: number, framing?: Framing): void;