@applicaster/zapp-react-native-ui-components 15.0.0-alpha.4225160176 → 15.0.0-alpha.4232833803

package/Components/Cell/TvOSCellComponent.tsx

@@ -195,7 +195,6 @@ class TvOSCell extends React.Component<Props, State> {
       groupId,
       component,
       index,
-      componentsMapOffset,
     } = this.props;
 
     this.setScreenLayout(componentAnchorPointY, screenLayout);
@@ -222,8 +221,7 @@ class TvOSCell extends React.Component<Props, State> {
       const totalOffset =
         headerOffset +
         toNumberWithDefaultZero(componentAnchorPointY) +
-        extraAnchorPointYOffset -
-        toNumberWithDefaultZero(componentsMapOffset) +
+        extraAnchorPointYOffset +
         componentMarginTop +
         componentPaddingTop;
 

package/Components/Layout/TV/__tests__/__snapshots__/index.test.tsx.snap

@@ -9,6 +9,11 @@ exports[`Layout TV renders 1`] = `
     excludeFromFocusSearching={true}
     id="/river/A1234"
     preferredFocus={true}
+    style={
+      {
+        "flex": 1,
+      }
+    }
   >
     <View
       Components={

package/Components/MasterCell/CONFIG_BUILDER_TO_REACT_COMPONENT.md

@@ -0,0 +1,144 @@
+# Config Builder -> React Component Migration Guide
+
+This guide explains how to migrate MasterCell config-builders to React components incrementally, without breaking existing config-node rendering.
+
+## Why This Exists
+
+MasterCell currently supports config-node builders such as:
+
+```ts
+{
+  type: "View",
+  style: {},
+  additionalProps: {},
+  data: [],
+  elements: []
+}
+```
+
+This is still valid and should continue to work.
+
+For incremental migration, MasterCell also supports inline React nodes:
+
+```ts
+{
+  type: "ReactComponent",
+  style: {},
+  additionalProps: {
+    component: MyComponent
+  }
+}
+```
+
+This lets you migrate one builder at a time.
+
+## Rendering Pipeline
+
+1. Builder returns node config (`type`, `style`, `additionalProps`, `data`, `elements`).
+2. `configInflater` converts `additionalProps` into runtime `props` and resolves `data`.
+3. `elementMapper` renders:
+4. String `type` nodes via component registry (`components[type]`).
+5. `type: "ReactComponent"` nodes via `props.component`.
+
+## Migration Pattern
+
+1. Keep existing builder API unchanged.
+2. Add a dedicated React component for the node being migrated.
+3. Change builder output from string `type` to `type: "ReactComponent"`.
+4. Pass component reference through `additionalProps.component`.
+5. Keep behavioral props unchanged (`testID`, roles, accessibility props).
+6. Set `renderChildren` explicitly:
+7. `false` when React component renders everything itself.
+8. `true` (or omit) when builder still provides `elements` children.
+9. Set `requiresCellUUID: true` only if the component needs `cellUUID`.
+10. Update builder-shape tests and rendering tests together.
+
+## Example Using `TextLabelsContainer.ts`
+
+Current builder (config-node only):
+
+```ts
+export const TextLabelsContainer = ({ actionIdentifier, testID, style, extraProps }) => ({
+  type: "View",
+  additionalProps: {
+    mobileActionRole: "label_container",
+  },
+  elements: [
+    {
+      type: "Text",
+      style,
+      additionalProps: {
+        label: { context: actionIdentifier, name: "label_1" },
+        state: "default",
+        mobileActionRole: "label",
+        testID: testID ? `${testID}-label` : undefined,
+        ...extraProps,
+      },
+    },
+  ],
+});
+```
+
+Incremental migration target:
+
+```ts
+import { TextLabelsContainerView } from "./TextLabelsContainerView";
+
+export const TextLabelsContainer = ({ actionIdentifier, testID, style, extraProps }) => ({
+  type: "ReactComponent",
+  additionalProps: {
+    component: TextLabelsContainerView,
+    renderChildren: false,
+    mobileActionRole: "label_container",
+    actionIdentifier,
+    testID,
+    textStyle: style,
+    textProps: extraProps,
+  },
+});
+```
+
+And React component:
+
+```tsx
+export const TextLabelsContainerView = ({
+  actionIdentifier,
+  testID,
+  textStyle,
+  textProps,
+  mobileActionRole,
+}) => (
+  <View mobileActionRole={mobileActionRole}>
+    <Text
+      style={textStyle}
+      label={{ context: actionIdentifier, name: "label_1" }}
+      state="default"
+      mobileActionRole="label"
+      testID={testID ? `${testID}-label` : undefined}
+      {...textProps}
+    />
+  </View>
+);
+```
+
+This keeps external behavior and props contract intact while moving implementation to React.
+
+## Rules for Safe Incremental Migration
+
+1. Do not change role markers used by parent logic (for example `mobileActionRole`).
+2. Do not rename `testID` contracts during migration.
+3. Keep output shape stable for parent builders (`null` handling, `elements` presence).
+4. Keep data-mapping semantics identical (`label`, `state`, `entry`, etc.).
+5. Migrate one node per PR where possible.
+
+## Testing Checklist
+
+1. Builder test: node type and required props (`component`, role, `testID`) are correct.
+2. Rendering test: `configInflater + elementMapper` still renders expected UI.
+3. Behavior test: parent container logic that clones/filters children still works.
+4. Regression test: hidden/empty states still return `null` as before.
+
+## Important Limitation
+
+`additionalProps.component` is a function reference and is suitable for local JS-built trees.
+If a tree must be fully serialized JSON, use a string `componentKey` and resolve it in a registry instead of storing a function directly.

package/Components/MasterCell/DefaultComponents/ActionButtonsCore/__tests__/model.test.ts

@@ -0,0 +1,80 @@
+import { buildActionButtonsModel } from "../model";
+
+describe("buildActionButtonsModel", () => {
+  it("returns null when the container is disabled", () => {
+    const configuration = {
+      mobile_buttons_container_buttons_enabled: false,
+      mobile_button_1_button_enabled: true,
+    };
+
+    const value = (key) => configuration[key];
+
+    expect(
+      buildActionButtonsModel({
+        configuration,
+        value,
+        containerPrefix: "mobile_buttons_container",
+        buttonPrefix: "mobile_button",
+      })
+    ).toBeNull();
+  });
+
+  it("returns explicit enabled slots and semantic container data", () => {
+    const configuration = {
+      mobile_buttons_container_buttons_enabled: true,
+      mobile_buttons_container_align: "right",
+      mobile_buttons_container_margin_top: 1,
+      mobile_buttons_container_margin_right: 2,
+      mobile_buttons_container_margin_bottom: 3,
+      mobile_buttons_container_margin_left: 4,
+      mobile_buttons_container_stacking: "vertical",
+      mobile_buttons_container_horizontal_gutter: 8,
+      mobile_buttons_container_vertical_gutter: 12,
+      mobile_buttons_container_independent_styles: false,
+      mobile_button_1_button_enabled: true,
+      mobile_button_2_button_enabled: false,
+      mobile_button_3_button_enabled: true,
+    };
+
+    const value = (key) => configuration[key];
+
+    expect(
+      buildActionButtonsModel({
+        configuration,
+        value,
+        containerPrefix: "mobile_buttons_container",
+        buttonPrefix: "mobile_button",
+      })
+    ).toEqual({
+      enabledSlots: [1, 3],
+      buttonsCount: 2,
+      container: {
+        horizontalAlign: "flex-end",
+        margins: {
+          top: 1,
+          right: 2,
+          bottom: 3,
+          left: 4,
+        },
+        stacking: "vertical",
+        horizontalGutter: 8,
+        verticalGutter: 12,
+        independentStyles: false,
+      },
+      buttons: [
+        {
+          slot: 1,
+          renderIndex: 0,
+          specificPrefix: "mobile_button_1",
+          stylePrefix: "mobile_button_1",
+        },
+        {
+          slot: 3,
+          renderIndex: 1,
+          specificPrefix: "mobile_button_3",
+          stylePrefix: "mobile_button_1",
+        },
+      ],
+    });
+  });
+});

package/Components/MasterCell/DefaultComponents/ActionButtonsCore/__tests__/placement.test.ts

@@ -0,0 +1,187 @@
+import {
+  insertBetweenLabelContainers,
+  insertBetweenLabels,
+} from "../placement";
+
+describe("ActionButtonsCore placement", () => {
+  const buttons = { type: "View", name: "buttons" };
+
+  const above_labels = [
+    { name: "above_label_1" },
+    { name: "above_label_2" },
+    { name: "above_label_3" },
+  ];
+
+  const below_labels = [
+    { name: "below_label_1" },
+    { name: "below_label_2" },
+    { name: "below_label_3" },
+  ];
+
+  it("inserts buttons after the matching label", () => {
+    expect(
+      insertBetweenLabels({ position: "below_label_2" }, buttons, below_labels)
+    ).toEqual([below_labels[0], below_labels[1], buttons, below_labels[2]]);
+  });
+
+  it("inserts buttons before the matching label", () => {
+    expect(
+      insertBetweenLabels({ position: "above_label_2" }, buttons, above_labels)
+    ).toEqual([above_labels[0], buttons, above_labels[1], above_labels[2]]);
+  });
+
+  it("prepends buttons only when on_top is allowed", () => {
+    expect(
+      insertBetweenLabels(
+        { position: "on_top", allowOnTop: true },
+        buttons,
+        below_labels
+      )
+    ).toEqual([buttons, ...below_labels]);
+
+    expect(
+      insertBetweenLabels(
+        { position: "on_top", allowOnTop: false },
+        buttons,
+        below_labels
+      )
+    ).toEqual(below_labels);
+  });
+
+  it("appends buttons when appendWhenMissing is enabled", () => {
+    expect(
+      insertBetweenLabels(
+        { position: "unknown", appendWhenMissing: true },
+        buttons,
+        below_labels
+      )
+    ).toEqual([...below_labels, buttons]);
+  });
+
+  it("returns labels unchanged when appendWhenMissing is disabled", () => {
+    expect(
+      insertBetweenLabels(
+        { position: "unknown", appendWhenMissing: false },
+        buttons,
+        below_labels
+      )
+    ).toEqual(below_labels);
+  });
+
+  const labelContainers = [
+    {
+      elements: [
+        {
+          elements: [{ name: "top_label_1" }, { name: "top_label_2" }],
+        },
+      ],
+    },
+    {
+      elements: [
+        {
+          elements: [{ name: "bottom_label_1" }],
+        },
+      ],
+    },
+  ];
+
+  it("inserts buttons after the matching label in a nested container", () => {
+    expect(
+      insertBetweenLabelContainers(
+        { position: "below_top_label_2" },
+        buttons,
+        labelContainers
+      )
+    ).toEqual([
+      {
+        elements: [
+          {
+            elements: [
+              { name: "top_label_1" },
+              { name: "top_label_2" },
+              buttons,
+            ],
+          },
+        ],
+      },
+      labelContainers[1],
+    ]);
+  });
+
+  it("inserts buttons before the matching label in a nested container", () => {
+    expect(
+      insertBetweenLabelContainers(
+        { position: "above_top_label_2" },
+        buttons,
+        labelContainers
+      )
+    ).toEqual([
+      {
+        elements: [
+          {
+            elements: [
+              { name: "top_label_1" },
+              buttons,
+              { name: "top_label_2" },
+            ],
+          },
+        ],
+      },
+      labelContainers[1],
+    ]);
+  });
+
+  it("prepends buttons into the first container only when on_top is allowed", () => {
+    expect(
+      insertBetweenLabelContainers(
+        { position: "on_top", allowOnTop: true },
+        buttons,
+        labelContainers
+      )
+    ).toEqual([
+      {
+        elements: [buttons, ...labelContainers[0].elements],
+      },
+      labelContainers[1],
+    ]);
+  });
+
+  it("appends buttons into the last container when configured", () => {
+    expect(
+      insertBetweenLabelContainers(
+        { position: "unknown", appendWhenMissing: true },
+        buttons,
+        labelContainers
+      )
+    ).toEqual([
+      labelContainers[0],
+      {
+        elements: [...labelContainers[1].elements, buttons],
+      },
+    ]);
+  });
+
+  it("inserts buttons after a matching label in a direct two-level container", () => {
+    const directLabelContainers = [
+      {
+        elements: [{ name: "top_label_1" }, { name: "top_label_2" }],
+      },
+      {
+        elements: [{ name: "bottom_label_1" }],
+      },
+    ];
+
+    expect(
+      insertBetweenLabelContainers(
+        { position: "below_top_label_2" },
+        buttons,
+        directLabelContainers
+      )
+    ).toEqual([
+      {
+        elements: [{ name: "top_label_1" }, { name: "top_label_2" }, buttons],
+      },
+      directLabelContainers[1],
+    ]);
+  });
+});

package/Components/MasterCell/DefaultComponents/ActionButtonsCore/__tests__/selectors.test.ts

@@ -0,0 +1,45 @@
+import {
+  getButtonSlotPrefix,
+  getEnabledButtonSlots,
+  getStylePrefix,
+} from "../selectors";
+
+describe("ActionButtonsCore selectors", () => {
+  it("returns explicit enabled button slots without collapsing sparse slots", () => {
+    const configuration = {
+      mobile_button_1_button_enabled: true,
+      mobile_button_2_button_enabled: false,
+      mobile_button_3_button_enabled: true,
+    };
+
+    expect(getEnabledButtonSlots(configuration, "mobile_button")).toEqual([
+      1, 3,
+    ]);
+  });
+
+  it("returns slot-based prefixes", () => {
+    expect(getButtonSlotPrefix("tv_buttons_button", 3)).toBe(
+      "tv_buttons_button_3"
+    );
+  });
+
+  it("reuses button 1 styles when independent styles are disabled", () => {
+    expect(
+      getStylePrefix({
+        slot: 3,
+        independentStyles: false,
+        buttonPrefix: "mobile_button",
+      })
+    ).toBe("mobile_button_1");
+  });
+
+  it("uses the explicit slot prefix when independent styles are enabled", () => {
+    expect(
+      getStylePrefix({
+        slot: 3,
+        independentStyles: true,
+        buttonPrefix: "mobile_button",
+      })
+    ).toBe("mobile_button_3");
+  });
+});

package/Components/MasterCell/DefaultComponents/ActionButtonsCore/__tests__/style.test.ts

@@ -0,0 +1,49 @@
+import { buildContainerLayout, getContainerMargins } from "../style";
+
+describe("ActionButtonsCore style helpers", () => {
+  it("returns numeric margins with zero defaults", () => {
+    const configuration = {
+      mobile_buttons_container_margin_top: "4",
+      mobile_buttons_container_margin_left: 6,
+    };
+
+    const value = (key) => configuration[key];
+
+    expect(getContainerMargins(value, "mobile_buttons_container")).toEqual({
+      top: 4,
+      right: 0,
+      bottom: 0,
+      left: 6,
+    });
+  });
+
+  it("returns semantic layout data using shared alignment mapping", () => {
+    const configuration = {
+      tv_buttons_container_align: "middle",
+      tv_buttons_container_margin_top: 1,
+      tv_buttons_container_margin_right: 2,
+      tv_buttons_container_margin_bottom: 3,
+      tv_buttons_container_margin_left: 4,
+      tv_buttons_container_stacking: "vertical",
+      tv_buttons_container_horizontal_gutter: 8,
+      tv_buttons_container_vertical_gutter: 12,
+      tv_buttons_container_independent_styles: true,
+    };
+
+    const value = (key) => configuration[key];
+
+    expect(buildContainerLayout(value, "tv_buttons_container")).toEqual({
+      horizontalAlign: "center",
+      margins: {
+        top: 1,
+        right: 2,
+        bottom: 3,
+        left: 4,
+      },
+      stacking: "vertical",
+      horizontalGutter: 8,
+      verticalGutter: 12,
+      independentStyles: true,
+    });
+  });
+});

package/Components/MasterCell/DefaultComponents/ActionButtonsCore/components/ActionButtonController.tsx

@@ -0,0 +1,165 @@
+import React, {
+  useCallback,
+  useEffect,
+  useMemo,
+  useRef,
+  useState,
+} from "react";
+import { useActions } from "@applicaster/zapp-react-native-utils/reactHooks/actions";
+
+type ActionDefinition = {
+  identifier?: string;
+};
+
+type ControllerRenderProps = {
+  actionContext: any;
+  actionState: any;
+  entry: any;
+  isActive: boolean;
+  onPress: () => Promise<unknown> | unknown;
+};
+
+type Props = {
+  action?: ActionDefinition;
+  pluginIdentifier?: string;
+  entry?: any;
+  onMissingActionContext?: (identifier?: string) => void;
+  children: (props: ControllerRenderProps) => React.ReactNode;
+};
+
+const resolveIsActive = (actionState: any, fallbackSelected = false) => {
+  if (actionState == null) {
+    return fallbackSelected;
+  }
+
+  return Boolean(
+    actionState?.active ??
+      actionState?.isActive ??
+      actionState?.selected ??
+      actionState?.isSelected ??
+      fallbackSelected
+  );
+};
+
+const buildLegacySelection = (entry: any, actionContext: any) => {
+  const defaultIsSelected = Array.isArray(actionContext?.state)
+    ? (actionContext?.state || []).includes(entry)
+    : false;
+
+  return actionContext?.masterCell?.isSelected
+    ? actionContext.masterCell.isSelected(entry)
+    : defaultIsSelected;
+};
+
+export function ActionButtonController({
+  action,
+  pluginIdentifier,
+  entry,
+  onMissingActionContext,
+  children,
+}: Props) {
+  const resolvedEntry = entry;
+  const resolvedIdentifier = action?.identifier || pluginIdentifier || "";
+  const actionContext = useActions(resolvedIdentifier);
+
+  const actionDisabled =
+    typeof actionContext?.isActionAvailable === "function" &&
+    !actionContext.isActionAvailable(resolvedEntry);
+
+  const supportsEntryState =
+    typeof actionContext?.initialEntryState === "function" && !actionDisabled;
+
+  const hydrationKey = `${resolvedIdentifier}::${String(resolvedEntry?.id ?? "")}`;
+  const lastHydratedKeyRef = useRef<string | null>(null);
+
+  const [actionState, setActionState] = useState(() =>
+    supportsEntryState ? actionContext.initialEntryState(resolvedEntry) : null
+  );
+
+  useEffect(() => {
+    if (supportsEntryState) {
+      if (lastHydratedKeyRef.current === hydrationKey) {
+        return;
+      }
+
+      lastHydratedKeyRef.current = hydrationKey;
+      setActionState(actionContext.initialEntryState(resolvedEntry));
+    }
+  }, [supportsEntryState, actionContext, resolvedEntry, hydrationKey]);
+
+  useEffect(() => {
+    if (typeof actionContext?.addListener === "function") {
+      return actionContext.addListener(String(resolvedEntry?.id), (nextState) =>
+        setActionState(nextState)
+      );
+    }
+
+    if (typeof actionContext?.addListeners === "function") {
+      return actionContext.addListeners(
+        ({ entryState, entry: updatedEntry }) => {
+          if (updatedEntry?.id === resolvedEntry?.id) {
+            setActionState(entryState);
+          }
+        }
+      );
+    }
+
+    return undefined;
+  }, [
+    actionContext,
+    resolvedEntry?.id,
+    resolvedIdentifier,
+    actionContext?.addListener,
+    actionContext?.addListeners,
+  ]);
+
+  const legacySelected = useMemo(() => {
+    if (!actionContext || supportsEntryState) {
+      return false;
+    }
+
+    return buildLegacySelection(resolvedEntry, actionContext);
+  }, [actionContext, supportsEntryState, resolvedEntry]);
+
+  const isActive = resolveIsActive(actionState, legacySelected);
+
+  const onPress = useCallback(async () => {
+    if (!actionContext) {
+      return;
+    }
+
+    if (supportsEntryState) {
+      return actionContext.invokeAction?.(resolvedEntry, {
+        updateState: setActionState,
+      });
+    }
+
+    const favouritesAction = legacySelected
+      ? actionContext.removeFavourite
+      : actionContext.addFavourite;
+
+    const toggleAction = actionContext?.invokeAction ?? favouritesAction;
+
+    return toggleAction?.(resolvedEntry);
+  }, [actionContext, supportsEntryState, resolvedEntry, legacySelected]);
+
+  if (!actionContext || actionDisabled) {
+    if (!actionContext) {
+      onMissingActionContext?.(resolvedIdentifier);
+    }
+
+    return null;
+  }
+
+  return (
+    <>
+      {children({
+        actionContext,
+        actionState,
+        entry: resolvedEntry,
+        isActive,
+        onPress,
+      })}
+    </>
+  );
+}