@applicaster/zapp-react-native-utils 16.0.0-rc.31 → 16.0.0-rc.33

package/manifestUtils/fieldUtils/index.js

@@ -1,3 +1,121 @@
+const { ZAPPIFEST_FIELDS } = require("../keys");
+const { toCamelCase } = require("../_internals");
+
+const SIDES = ["top", "right", "bottom", "left"];
+
+/**
+ * Parses a CSS margin/padding shorthand string into [top, right, bottom, left].
+ *
+ * 1 value  → all four sides
+ * 2 values → top/bottom, right/left
+ * 3 values → top, right/left, bottom
+ * 4 values → top, right, bottom, left
+ *
+ * @param {string} str
+ * @returns {[number, number, number, number]}
+ */
+function parseShorthand(str) {
+  const parts = String(str).trim().split(/\s+/).map(Number);
+
+  switch (parts.length) {
+    case 1:
+      return [parts[0], parts[0], parts[0], parts[0]];
+    case 2:
+      return [parts[0], parts[1], parts[0], parts[1]];
+    case 3:
+      return [parts[0], parts[1], parts[2], parts[1]];
+    case 4:
+      return parts;
+    default:
+      throw new Error(
+        `Shorthand expects 1–4 space-separated values, got ${parts.length}: "${str}"`
+      );
+  }
+}
+
+function spacingFields(prefix, initialValues) {
+  const platforms = Object.keys(initialValues);
+
+  const parsed = Object.fromEntries(
+    platforms.map((p) => [p, parseShorthand(initialValues[p])])
+  );
+
+  return SIDES.map((side, i) => ({
+    suffix: `${prefix} ${side}`,
+    type: ZAPPIFEST_FIELDS.number_input,
+    initialValue: Object.fromEntries(platforms.map((p) => [p, parsed[p][i]])),
+  }));
+}
+
+/**
+ * Generates four margin field descriptors (top/right/bottom/left) from a
+ * per-platform CSS shorthand string.
+ *
+ * @param {string} suffix - prefix word for generated field names, e.g. "margin"
+ * @param {Record<string, string>} initialValues - e.g. { mobile: "0 0 20", tv: "0 0 90" }
+ * @returns {object[]}
+ */
+function margin(suffix, initialValues) {
+  return spacingFields(suffix, initialValues);
+}
+
+/**
+ * Generates four padding field descriptors (top/right/bottom/left) from a
+ * per-platform CSS shorthand string.
+ *
+ * @param {string} suffix - prefix word for generated field names, e.g. "padding"
+ * @param {Record<string, string>} initialValues - e.g. { mobile: "0 20", tv: "0 124" }
+ * @returns {object[]}
+ */
+function padding(suffix, initialValues) {
+  return spacingFields(suffix, initialValues);
+}
+
+/**
+ * Returns a flat camelCase defaults object for a spacing shorthand.
+ * e.g. marginDefaults("margin", "0 0 20") → { marginTop: 0, marginRight: 0, marginBottom: 20, marginLeft: 0 }
+ *
+ * @param {string} suffix - e.g. "margin" or "padding"
+ * @param {string} shorthand - CSS-like shorthand string
+ * @returns {Record<string, number>}
+ */
+function spacingDefaults(suffix, shorthand) {
+  const values = parseShorthand(shorthand);
+
+  return Object.fromEntries(
+    SIDES.map((side, i) => [toCamelCase(`${suffix} ${side}`), values[i]])
+  );
+}
+
+function marginDefaults(suffix, shorthand) {
+  return spacingDefaults(suffix, shorthand);
+}
+
+function paddingDefaults(suffix, shorthand) {
+  return spacingDefaults(suffix, shorthand);
+}
+
+/**
+ * Returns four field descriptors (top/right/bottom/left) with only suffix and type — no initialValue.
+ * Used when defaults are stored separately in the subgroup spec.
+ *
+ * @param {string} prefix - e.g. "margin" or "padding"
+ * @returns {object[]}
+ */
+function marginFields(prefix) {
+  return SIDES.map((side) => ({
+    suffix: `${prefix} ${side}`,
+    type: ZAPPIFEST_FIELDS.number_input,
+  }));
+}
+
+function paddingFields(prefix) {
+  return SIDES.map((side) => ({
+    suffix: `${prefix} ${side}`,
+    type: ZAPPIFEST_FIELDS.number_input,
+  }));
+}
+
 /**
  * Appends new conditional_fields from conditions array
  * to config.conditional_fields
@@ -48,6 +166,13 @@ function createConditionalField(key, condition_value, category = "styles") {
 }
 
 module.exports = {
+  parseShorthand,
+  margin,
+  padding,
+  marginDefaults,
+  paddingDefaults,
+  marginFields,
+  paddingFields,
   withConditional,
   getConditionalKey,
   createConditionalField,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@applicaster/zapp-react-native-utils",
-  "version": "16.0.0-rc.31",
+  "version": "16.0.0-rc.33",
   "description": "Applicaster Zapp React Native utilities package",
   "main": "index.js",
   "types": "index.d.ts",
@@ -27,7 +27,7 @@
   },
   "homepage": "https://github.com/applicaster/quickbrick#readme",
   "dependencies": {
-    "@applicaster/applicaster-types": "16.0.0-rc.31",
+    "@applicaster/applicaster-types": "16.0.0-rc.33",
     "buffer": "^5.2.1",
     "camelize": "^1.0.0",
     "dayjs": "^1.11.10",

package/reactHooks/actions/index.ts

@@ -1,8 +1,12 @@
 /// <reference types="@applicaster/applicaster-types" />
 /* eslint-disable @typescript-eslint/no-unused-vars */
-import { Context, useContext, useState } from "react";
+import { Context, useCallback, useContext, useEffect, useState } from "react";
 import { ActionsContext } from "@applicaster/zapp-react-native-ui-components/Contexts/ActionsContext";
 
+import {
+  observeEntryState,
+  RegisteredActionValue,
+} from "../../uiActionsRegistrator";
 import { reactHooksLogger } from "../logger";
 
 const logger = reactHooksLogger.addSubsystem("actions");
@@ -46,3 +50,49 @@ export function useActions<T = unknown>(plugId: string): any {
 
   return context;
 }
+
+export type UseEntryActionState = {
+  state: CellActionEntryState | undefined;
+  invokeAction: (options?: InvokeArgsOptions) => void;
+};
+
+/**
+ * Subscribes a component to a single action's state for a given `entry`.
+ *
+ * It observes state changes reactively via `observeEntryState` (which is backed
+ * by the action's `addListener`), seeds the initial value synchronously from
+ * `initialEntryState`, and returns a memoized `invokeAction` that forwards
+ * optimistic `updateState` updates back into local state.
+ *
+ * This is the single, unified way to drive an action button - it works the same
+ * for registry actions, legacy context-provider actions and entry actions.
+ */
+export function useEntryActionState(
+  action: RegisteredActionValue | undefined,
+  entry: ZappEntry | ZappFeed
+): UseEntryActionState {
+  const [state, setState] = useState<CellActionEntryState | undefined>(() =>
+    action?.initialEntryState?.(entry)
+  );
+
+  const entryId = (entry as ZappEntry)?.id;
+
+  useEffect(() => {
+    if (!action) return undefined;
+
+    const subscription = observeEntryState(action, entry).subscribe(setState);
+
+    return () => subscription.unsubscribe();
+    // eslint-disable-next-line @wogns3623/better-exhaustive-deps/exhaustive-deps
+  }, [action, entryId]);
+
+  const invokeAction = useCallback(
+    (options: InvokeArgsOptions = {}) => {
+      action?.invokeAction?.(entry, { updateState: setState, ...options });
+    },
+    // eslint-disable-next-line @wogns3623/better-exhaustive-deps/exhaustive-deps
+    [action, entryId]
+  );
+
+  return { state, invokeAction };
+}

package/uiActionsRegistrator/index.ts

@@ -0,0 +1,203 @@
+/* eslint-disable no-dupe-class-members */
+import { Observable } from "rxjs";
+import { createLogger } from "../logger";
+
+const { log_debug, log_warning, log_verbose } = createLogger({
+  subsystem: "UIActionsRegistry",
+  category: "ActionRegistration",
+});
+
+/**
+ * The runtime value of a UI action.
+ *
+ * This is the object that consumers interact with (render buttons for,
+ * invoke on press, read initial state from, etc.). It intentionally keeps an
+ * open shape (`[K: string]: any`) so that both the modern registry-based
+ * actions and the legacy context-provider based actions can be represented by
+ * the same structure.
+ */
+export type RegisteredActionValue = {
+  state?: any;
+  getInitialState?: () => Promise<void>;
+  initialEntryState?: (item: ZappEntry | ZappFeed) => CellActionEntryState;
+  invokeAction: (
+    item: ZappEntry | ZappFeed,
+    options?: InvokeArgsOptions
+  ) => void;
+  isActionAvailable?: (item: ZappEntry | ZappFeed) => boolean;
+  addListener?: (
+    entryId: string,
+    listener: CellActionStateListenerFunction
+  ) => CellActionStateRemoveListenerFunction;
+  /**
+   * Optional RX stream of the action state for a given entry. When not
+   * provided, `observeEntryState` derives one from `initialEntryState` +
+   * `addListener` (see below).
+   */
+  observeEntryState?: (
+    entry: ZappEntry | ZappFeed
+  ) => Observable<CellActionEntryState>;
+  [K: string]: any;
+};
+
+export type RegisteredAction = {
+  identifier: string; // Plugin identifier or synthetic name
+  action: RegisteredActionValue;
+};
+
+/**
+ * A function that, given an optional context (currently just the `entry`),
+ * returns the list of actions it wants to contribute.
+ *
+ * Returning an array is what allows a single provider (plugin or otherwise) to
+ * expose more than one action, and to compute those actions based on the entry.
+ */
+export type UIActionProvider = (params: {
+  entry?: ZappEntry | ZappFeed;
+}) => RegisteredAction[];
+
+/**
+ * Returns an RX `Observable` that emits the action state for `entry`.
+ *
+ * If the action already exposes its own `observeEntryState`, it is used as-is.
+ * Otherwise we build the stream from the legacy imperative API:
+ *  - it immediately emits `initialEntryState(entry)` (if available), and
+ *  - it subscribes to further changes via `addListener(entryId, listener)`,
+ *    unsubscribing automatically when the observable is torn down.
+ *
+ * This lets every action - old or new - be consumed reactively through a single
+ * mechanism, without each consumer having to wire up `addListener` manually.
+ */
+export function observeEntryState(
+  action: RegisteredActionValue | undefined,
+  entry: ZappEntry | ZappFeed
+): Observable<CellActionEntryState> {
+  if (typeof action?.observeEntryState === "function") {
+    return action.observeEntryState(entry);
+  }
+
+  return new Observable<CellActionEntryState>((subscriber) => {
+    const initialState = action?.initialEntryState?.(entry);
+
+    if (initialState !== undefined) {
+      subscriber.next(initialState);
+    }
+
+    const removeListener = action?.addListener?.(
+      String((entry as ZappEntry)?.id),
+      (state: CellActionEntryState) => subscriber.next(state)
+    );
+
+    return () => removeListener?.();
+  });
+}
+
+class UIActionsRegistry {
+  private registeredActions: Record<string, UIActionProvider> = {};
+
+  /**
+   * Register a dynamic action provider under a unique `name`.
+   * The provider can return one or more actions and may use the passed `entry`.
+   * Returns an unregister function.
+   */
+  registerActionProvider(
+    name: string,
+    actionProvider: UIActionProvider
+  ): () => void {
+    const isOverride = Boolean(this.registeredActions[name]);
+
+    if (isOverride) {
+      log_warning(
+        `registerActionProvider: overriding existing provider for "${name}"`,
+        { name }
+      );
+    } else {
+      log_debug(`registerActionProvider: registered "${name}"`, { name });
+    }
+
+    this.registeredActions[name] = actionProvider;
+
+    return () => {
+      // Only remove if it's still the same provider to avoid races where a
+      // newer registration replaced this one.
+      if (this.registeredActions[name] === actionProvider) {
+        delete this.registeredActions[name];
+        log_debug(`registerActionProvider: unregistered "${name}"`, { name });
+      } else {
+        log_debug(
+          `registerActionProvider: skipped unregister for "${name}" – newer provider is active`,
+          { name }
+        );
+      }
+    };
+  }
+
+  /**
+   * Convenience helper to register a single, static action from anywhere in the
+   * app (it does not need to be a plugin). Returns an unregister function.
+   */
+  registerAction(
+    identifier: string,
+    action: RegisteredActionValue
+  ): () => void {
+    log_debug(`registerAction: registering single action "${identifier}"`, {
+      identifier,
+    });
+
+    return this.registerActionProvider(identifier, () => [
+      { identifier, action },
+    ]);
+  }
+
+  getEntryActions(entry: ZappEntry): RegisteredAction[] {
+    const results = Object.keys(this.registeredActions)
+      .map((key) => this.registeredActions[key]({ entry }))
+      .flatMap((a) => a);
+
+    log_verbose(
+      `getEntryActions: resolved ${results.length} action(s) for entry "${entry?.id}"`,
+      { entryId: entry?.id, identifiers: results.map((r) => r.identifier) }
+    );
+
+    return results;
+  }
+
+  getActions(name: string, entry?: ZappEntry | ZappFeed): RegisteredAction[] {
+    if (!this.registeredActions[name]) {
+      log_warning(`getActions: no provider found for "${name}"`, { name });
+
+      return [];
+    }
+
+    const results = this.registeredActions[name]({ entry }) ?? [];
+
+    log_verbose(
+      `getActions: resolved ${results.length} action(s) for "${name}"`,
+      {
+        name,
+        entryId: (entry as ZappEntry)?.id,
+        identifiers: results.map((r) => r.identifier),
+      }
+    );
+
+    return results;
+  }
+
+  /**
+   * Returns the runtime value of the first action registered under `name`, or
+   * `undefined`. This mirrors the shape returned by the legacy `useActions`
+   * hook, easing migration of single-action consumers.
+   */
+  getAction(
+    name: string,
+    entry?: ZappEntry | ZappFeed
+  ): RegisteredActionValue | undefined {
+    return this.getActions(name, entry)[0]?.action;
+  }
+
+  hasAction(name: string): boolean {
+    return Boolean(this.registeredActions[name]);
+  }
+}
+
+export const uiActionsRegistry = new UIActionsRegistry();