@symbiote-native/components 3.1.1 → 3.1.3

package/build/behaviors/image-background.js

@@ -1,35 +1,11 @@
-// ImageBackground's host behavior: the composition and the prop split the wrapper component did,
-// moved below the framework so the primitive can be a bare tag.
-//
-// THE TWO-NODE SHAPE IS RN'S. `ImageBackground.js:74-103` opens a `<View>` carrying the app's
-// `style`, puts an absolutely-filled `<Image>` inside it, and lays the app's `{children}` AFTER
-// that image so they paint on top. The tag commits the same two nodes — `image-background` (an
-// RCTView, the tag an app writes) with an RCTImageView built under it.
-//
-// WHY THE SLOT TAKES NO CHILDREN, which is the one thing this primitive needed that ScrollView,
-// ActivityIndicator and Button did not. `childHost` answers two questions at once — which node an
-// owner prop redirects onto, and which node the app's children go under — and those had the same
-// answer for every primitive until this one. Here they differ: the image takes `imageStyle` and the
-// whole `...props` spread, while the children belong beside it. `slotTakesNoChildren` is what
-// splits them (`IHostBehavior`, and it is not a JSX nicety upstream could have collapsed — an
-// Android `<Image>` is an `ImageView`, not a `ViewGroup`).
-//
-// WHERE THE APP'S PROPS GO. RN destructures `children, style, imageStyle, imageRef,
-// importantForAccessibility, ...props` and spreads `...props` onto the Image
-// (`ImageBackground.js:62-81`), so the set that moves is OPEN — every event, every accessibility
-// prop, `testID`, `id`, whatever an app writes next — and only a complement can express it.
-// `IMAGE_BACKGROUND_HOST_PROPS` is that complement, and `importantForAccessibility` is IN it despite
-// never being part of the spread: RN reapplies it explicitly to both nodes (`:76,82`), so it stays on
-// the owner here too and the image gets its own copy derived from `ownerProps` (FIXED 2026-09-20 —
-// it used to redirect to the image alone and never reach the owner at all, which the module's own
-// comment rationalized as "the divergence from RN predates all of it").
-//
-// WHAT THE IMAGE'S FOLD OWES. Everything on the image arrives as a real prop write, so its payload
-// is built by the shared `foldImagePayload` like any other `image`. Two things cannot arrive that
-// way and are folded here: the style, which is DERIVED from the owner's own `style` (RN proxies the
-// wrapper's width/height onto the image so it fills the box rather than collapsing to the source's
-// intrinsic size), and `id`, whose rename to `nativeID` is applied per adapter on the tag THEY
-// create and so never reaches a node a behavior built.
+// ImageBackground's host behavior. RN's `ImageBackground.js:74-103` opens a `<View>` with the
+// app's `style`, an absolutely-filled `<Image>` inside, children painted AFTER on top — this tag
+// commits the same two nodes (`image-background` + its inner image).
+// `childHost` normally answers both "where do owner props redirect" and "where do children go" —
+// here they differ (image takes the spread, children stay on the owner), so
+// `slotTakesNoChildren` splits them; not a JSX nicety, an Android `<Image>` is not a ViewGroup.
+// RN spreads an OPEN prop set onto the Image (`ImageBackground.js:62-81`);
+// `IMAGE_BACKGROUND_HOST_PROPS` below is the complement RN keeps on the wrapper instead.
 import { appendChild, createElement, registerHostBehavior, } from '@symbiote-native/engine';
 import { descriptorFor } from '../component-names';
 import { IMAGE_TAG, registerImageBehavior } from './image.js';
@@ -37,12 +13,9 @@ export const IMAGE_BACKGROUND_TAG = 'image-background';
 // The inner image's own tag. Distinct from `image` because the absolute fill must NOT reach a bare
 // `<image>`, and a tag is the only thing a per-node rule can branch on.
 export const IMAGE_BACKGROUND_IMAGE_TAG = 'image-background-image';
-// The props RN keeps on the wrapper View (`ImageBackground.js:74-78`), plus the two spellings of a
-// class name — `routeProp`'s slot redirect runs above its own class branch, so an unlisted `class`
-// would style the image instead of the box. `importantForAccessibility` stays too: RN destructures
-// it out of `...props` and reapplies it explicitly to BOTH the wrapper (:76) and the image (:82), so
-// it is never part of the spread — the engine derives the image's own copy from this node
-// (`foldImageBackgroundImageProps` in `SymbioteFabricProps.cpp`), the same seam the box proxy uses.
+// Kept on the wrapper (`ImageBackground.js:74-78`), plus both class spellings — the slot redirect
+// runs above the class branch, so an unlisted `class` would style the image instead. RN reapplies
+// `importantForAccessibility` to BOTH nodes (:76,82); the image gets its own derived copy.
 const IMAGE_BACKGROUND_HOST_PROPS = [
     'style',
     'class',
@@ -56,49 +29,16 @@ const IMAGE_BACKGROUND_SLOT_DERIVED = ['style', 'importantForAccessibility'];
 // value for it — every adapter's wrapper resolved one — and `routeProp` routes a string landing on
 // `style` as `class` instead, so the registry resolves it on the image with nothing needed here.
 const IMAGE_BACKGROUND_SLOT_PROPS = { imageStyle: 'style' };
-// The owner's fold is GONE (2026-09-18), not moved into this file under another name: its whole
-// content was `accessibilityIgnoresInvertColors: true`, a function of the tag and nothing else, and
-// it is `foldImageBackgroundProps` in `SymbioteFabricProps.cpp` now. The owner therefore pays no
-// trip into JS at all, and a committed ImageBackground is down from two crossings to one — the
-// remaining one is the inner image's, below, which derives its style from THIS node and so cannot be
-// a per-node rule. Contract: `core/engine/cpp/tests/js/image-background-payload.itest.ts`.
-// THE IMAGE'S FOLD IS GONE TOO (2026-09-18) — `foldImageBackgroundImageProps` in
-// `SymbioteFabricProps.cpp`, and with it this primitive costs ZERO trips into JS on both nodes.
-//
-// It outlived every other fold in this file because both of its inputs live on the node ABOVE: the
-// app writes `style` on the `<image-background>` and `IMAGE_BACKGROUND_HOST_PROPS` keeps it there.
-// "A per-node rule cannot reach another node" is what this file used to say, and it was a fact about
-// the JS FOLD rather than the engine — the tree is in C++, so `fabricProps` takes `ownerProps` from
-// `node.parent` and the proxy reads it there.
-//
-// The `id -> nativeID` half went earlier still and was DEAD before this port: `foldIdAlias` applies
-// to every tagged node and runs ahead of any fold, so by the time this ran the key was already
-// renamed. Worth naming, because a fold that still spells a rule someone else now applies reads as
-// load-bearing and is not.
-//
-// Contract: `core/engine/cpp/tests/js/image-background-image-payload.itest.ts`.
-// Returns the image, so `slotProps` / `slotPropsExcept` / `slotDerived` all point at it — and the
-// app's children stay on the owner because of `slotTakesNoChildren`, not because of what this
-// returns. The image is appended FIRST and nothing else is ever placed in front of it, which is
-// what makes the children paint over it.
-//
-// Built WITH `IMAGE_TAG` since 2026-09-18, which is the reverse of what it used to do and for a
-// reason that reversed with it. It used to withhold the tag so the node would not get Image's
-// `payloadFold` — a single slot this primitive needed for its own derived style — and call the
-// shared mapping by hand at the end. The mapping is the ENGINE's now, reached off the tag, so the
-// tag is how this node gets the platform half at all; the JS slot is free for the composition.
-//
-// ONE ORDERING DIFFERENCE FALLS OUT, and it is deliberate rather than overlooked. The image rule
-// folds the image's own `width`/`height` PROPS under its style, and the background rule then layers
-// the box's dimensions over that — where RN nests it the other way (`ImageBackground.js:83-98` puts
-// the props under the proxied box size). So when an app sets BOTH a `width` prop on the
-// ImageBackground and a conflicting width in its `style`, RN gives the style's and we give the
-// prop's.
-//
-// It is left this way rather than reproduced: RN's own comment calls that nesting a "Temporary
-// Workaround" for an Image that overwrites its own dimensions, and an explicit prop winning over an
-// inherited box is the less surprising of the two. Pinned in
-// `core/components/src/behaviors/image-background.test.ts` so it stays a decision.
+// The owner's fold is GONE: its one job (`accessibilityIgnoresInvertColors: true`) is
+// `foldImageBackgroundProps` in C++ now (`image-background-payload.itest.ts`).
+// The image's fold is GONE too — `foldImageBackgroundImageProps` in C++, reading `ownerProps`
+// from `node.parent` for the style proxy (`image-background-image-payload.itest.ts`).
+// Returns the image, so `slotProps`/`slotPropsExcept`/`slotDerived` point at it; children stay on
+// the owner via `slotTakesNoChildren`. Built WITH `IMAGE_TAG` so the engine's Image mapping still
+// applies to it — the JS slot is free for composition only.
+// ONE ORDERING DIFFERENCE, deliberate: the image rule folds its own `width`/`height` under its
+// style, then the box's dimensions layer over that — RN nests it the other way
+// (`ImageBackground.js:83-98`). Pinned in `image-background.test.ts` so it stays a decision.
 //
 // THE TAG IS ITS OWN, and that is what the C++ port needed. The node used to carry plain `image`,
 // which is right for everything the ordinary image rule does and wrong for the fill — a bare

package/build/behaviors/image.js

@@ -1,13 +1,6 @@
-// Image's host behavior, and it carries no runtime at all — no listeners, no timers, no commit
-// hook, and since 2026-09-18 no fold either. What is left is ONE declaration: that this tag's three
-// source props are resolved on the way in.
-//
-// WHERE THE FOLD WENT: `foldImageProps` in `SymbioteFabricProps.cpp`, with
-// `core/engine/cpp/tests/js/image-payload.itest.ts` as its contract. The `srcSet`/`src`/`source`
-// precedence, the W3C header decoration, the `width`/`height` fold into style, `alt` becoming
-// `accessibilityLabel` + `accessible`, `resizeMode`/`tintColor` falling back to style keys, and
-// `loadingIndicatorSource` being plucked down to a bare uri — all of it is a function of the tag,
-// which is what makes it the platform's.
+// Image's host behavior carries no runtime — no listeners, no timers, no fold. `foldImageProps`
+// in C++ resolves the `srcSet`/`src`/`source` precedence, style folds and a11y mapping, asserted
+// in `core/engine/cpp/tests/js/image-payload.itest.ts`.
 //
 // WHY THIS ONE DID NOT MOVE WHOLE, and it is the first that did not. `resolveAssetSource` turns the
 // number `require('./logo.png')` returns into a `{uri, width, height, scale}` by asking METRO'S

package/build/behaviors/input-accessory-view.js

@@ -1,54 +1,13 @@
-// InputAccessoryView's host behavior. This file itself still owns no per-node runtime — the
-// primitive's real rule lives in `foldInputAccessoryViewProps` (`SymbioteFabricProps.cpp`) now.
-//
-// THE OLD FOLD WAS GONE, not moved (2026-09-18): read end to end it split the bag into
-// consumed/passthrough and reassembled it — there was no aliasing at all, every consumed name left
-// under the same name, and the one thing it actually changed was dropping a `nativeID` or
-// `backgroundColor` that was not a `string`. That is defensive narrowing of a typed view object,
-// not a rule native cares about — and it was WRONG on `backgroundColor`, whose validAttributes
-// entry carries `processColor` and therefore accepts a number.
-//
-// A REAL RULE WAS FOUND WHILE READING VENDOR FOR THE PORT (2026-09-20):
-// `InputAccessoryView.js`'s `styles.container = {position: 'absolute'}`, composed AFTER the app's
-// own style (`[props.style, styles.container]`) so it wins over any `position` an app authors.
-// Every InputAccessoryView is positioned absolutely; nothing about it is per-instance, so it is
-// `foldInputAccessoryViewProps` now rather than anything here. Contract:
-// `core/engine/cpp/tests/js/touchable-payload.itest.ts`.
-//
-// NOT YET PORTED, and recorded honestly rather than silently skipped: vendor also wraps the app's
-// children in an inner `SafeAreaView` sized to `useWindowDimensions().width` (`InputAccessoryView.js`
-// render body) and returns nothing at all when it has zero children. Both are real structural gaps
-// — a composed child node plus a live window-dimension binding — genuinely larger than a tag-only
-// rule, and are NOT covered by this pass.
-//
-// TODO(rn-parity): port both. Needs (a) a `buildStructure` composing an inner wrapper node styled
-// `{flex: 1, width}` around the app's children, with `width` read from a live window-dimensions
-// subscription (no `SafeAreaView` primitive exists in this codebase yet — it would need building),
-// and (b) suppressing the whole node (both platforms, not just Android's void case already fixed
-// here) when it has zero children, matching `React.Children.count(props.children) === 0`.
-//
-// The `id -> nativeID` alias — is `foldIdAlias` in `SymbioteFabricProps.cpp`, applied to every
-// tagged node rather than per primitive.
-//
-// PLATFORM. This is the only primitive in its group that is not platform-invariant in what it
-// COMMITS TO: `input-accessory-view` resolves to `RCTInputAccessoryView` on iOS and to the void
-// component on Android. The fold itself is platform-invariant on purpose.
-//
-// FIXED (2026-09-20). `InputAccessoryView.js` on Android does `console.warn('<InputAccessoryView>
-// is only supported on iOS.'); return null` — the WHOLE component, children included, renders
-// NOTHING. We used to commit a real `RCTView` and its whole children subtree (the toolbar content
-// an app wrapped in it) — an extra, laid-out, potentially visible view where a real device shows
-// none. `backgroundColor` being a declared iOS prop vs an Android style key is the SAME already-
-// narrow gap, unaffected by this.
-//
-// The fix needed a new engine primitive, because every existing "commits no node of its own"
-// tier-2 primitive (`touchable-native-feedback`, `touchable-without-feedback`) is an ANCHOR — it
-// hoists its single child up in its own place, which is the opposite of what this tag needs: its
-// whole subtree must vanish. `VOID_COMPONENT` (`core/engine/src/node.ts`, `OP_CREATE_VOID` in
-// `mutation-buffer.ts`) is that primitive — a node the commit walk stops at, recursively,
-// contributing neither itself nor its children. Wired purely through
-// `core/components/src/component-names/index.android.ts`'s per-platform table, the same seam
-// `ANCHOR_COMPONENT` already used — this behavior file needed no change at all.
+// InputAccessoryView's host behavior owns no per-node runtime — the rule is
+// `foldInputAccessoryViewProps` in C++, including the container's absolute-position style RN
+// always composes over the app's own (`core/engine/cpp/tests/js/touchable-payload.itest.ts`).
+// NOT YET PORTED: vendor also wraps children in an inner SafeAreaView sized to
+// `useWindowDimensions().width` and renders nothing with zero children.
+// TODO(rn-parity): needs a `buildStructure` wrapper node, a live window-dimensions subscription,
+// and suppressing the whole node on both platforms when childless.
+// Android resolves to `VOID_COMPONENT` (`core/engine/src/node.ts`, `OP_CREATE_VOID`): the commit
+// walk stops there recursively, contributing neither the node nor its children — wired through
+// `component-names/index.android.ts`, this behavior file needed no change.
 import { Platform, registerHostBehavior, } from '@symbiote-native/engine';
 export const INPUT_ACCESSORY_VIEW_TAG = 'input-accessory-view';
 // `InputAccessoryView.js:110-113` — off iOS it warns and renders nothing (the void component).

package/build/behaviors/pressable.d.ts

@@ -1,69 +1,23 @@
-import { type IHostBehavior, type ISymbioteNode } from '@symbiote-native/engine';
+import { type IEventDispatch, type IHostBehavior, type ISymbioteNode } from '@symbiote-native/engine';
 import { type IPressMachineConfig } from '../state/pressable';
 import type { IAccessibilityStateValue } from '../accessibility-props';
 export declare const PRESSABLE_TAG = "pressable";
-/**
- * A last look at the machine's config before its handlers are built, for a tag that IS a pressable
- * plus something — TouchableOpacity, whose fade has to run between the machine and the app's own
- * `onPressIn`.
- *
- * Called from `rebuild`, so once per gesture rather than once per mount: it sees the config the
- * props actually hold by the time a finger lands, and anything it captures is discarded with the
- * gesture. Per-node state that must OUTLIVE a gesture belongs on the caller's own WeakMap.
- */
 export type IPressConfigRefinement = (node: ISymbioteNode, config: IPressMachineConfig) => IPressMachineConfig;
-/**
- * What the machine reads as `disabled`, for a tag whose spelling of it is not the raw prop.
- *
- * There is no resolver by default because RN's Pressable hands Pressability the RAW prop
- * (`Pressable.js:266`) — `aria-disabled` there changes only what is ANNOUNCED. Button is the one
- * primitive that differs: it resolves `disabled ?? aria-disabled ?? accessibilityState.disabled` in
- * the component and passes the ANSWER down as the touchable's own prop (`Button.js:337` -> `:386`),
- * which a single tag has no second node to pass to.
- *
- * Reads the bag and returns the answer; it must never write one back. `resolveButtonDisabled`
- * short-circuits on an authored `disabled`, so a resolved value stored in `node.props.disabled`
- * would answer the NEXT resolution as if the app had written it and the tag could never re-enable.
- */
 export type IDisabledResolver = (props: Readonly<Record<string, unknown>>) => boolean | undefined;
 export type ICancelableResolver = (source: ISymbioteNode) => boolean | undefined;
 export declare function booleanOr(value: unknown): boolean | undefined;
 export declare function asAccessibilityState(value: unknown): IAccessibilityStateValue | undefined;
 export declare function accessibleUnlessOptedOut(props: Readonly<Record<string, unknown>>): boolean;
-/**
- * The Android ripple's three view commands around the app's callbacks (TNF :230-252,
- * useAndroidRippleForView.js:77-104). The JS responder takes the touch before Android's own
- * pressed handling, so without them the ripple never animates. Hotspot first: it starts under
- * the finger.
- */
 export declare function withNativeFeedbackCommands(node: ISymbioteNode, config: IPressMachineConfig): IPressMachineConfig;
-/**
- * The machine on `node`, reading its props and the app's callbacks off `options.source` when that
- * is a different node.
- *
- * Exported for a behavior whose responder is not its own node — `./touchable-native-feedback`,
- * whose tag commits nothing and adopts the app's single child as the responder. Every other caller
- * goes through `createPressBehavior`, where source and node are the same.
- *
- * Re-callable on the same node: a second call replaces the state and the dispatchers, which is what
- * a re-arm after `detachPressMachine` needs.
- */
-export declare function attachPressMachine(node: ISymbioteNode, options?: {
+export declare const PRESS_DISPATCH: IEventDispatch;
+export type IAttachOptions = {
     readonly refine?: IPressConfigRefinement;
     readonly disabledOf?: IDisabledResolver;
     readonly cancelableOf?: ICancelableResolver;
     readonly source?: ISymbioteNode;
-}): void;
+};
+export declare function attachPressMachine(node: ISymbioteNode, options?: IAttachOptions): void;
 /** See `attachPressMachine`: the same teardown `createPressBehavior` registers as its `detach`. */
 export declare function detachPressMachine(node: ISymbioteNode): void;
-/**
- * The press machine as behavior parts, so a tag that is a pressable PLUS something can compose it
- * instead of re-implementing it.
- *
- * Spread into the caller's own behavior and wrap `attach`/`detach` around these — the touchable
- * family needs a per-node Animated value opened before the machine and closed after it. The
- * WeakMap holding the machine's own state is keyed by node, so one node may hold exactly one of
- * these; a tag composing it therefore must not also register the plain `pressable` behavior.
- */
 export declare function createPressBehavior(refine?: IPressConfigRefinement, disabledOf?: IDisabledResolver): Pick<IHostBehavior, 'attach' | 'detach' | 'ownedListeners'>;
 export declare function registerPressableBehavior(): void;