@fluentui-react-native/framework-base 0.2.0 → 0.3.0

package/src/component-patterns/README.md

@@ -2,38 +2,75 @@
 
 These are the base component patterns shared across the deprecated or v0 framework (found under packages/deprecated), and the newer framework (found under packages/framework). This also includes the custom JSX handlers required to render them properly.
 
-There are two main patterns exposed here: direct rendering and staged rendering.
+There are two main patterns exposed here: direct rendering and phased rendering.
 
 ## Direct Rendering
 
-The direct rendering pattern allows a component to be called directly, rather than creating a new entry in the DOM.
+The direct rendering pattern allows a component to be called directly, rather than creating a new entry in the render tree.
 
-As an example, if you want to create a wrapper around a component called `MyText` that has `italicize` as one of its props, that always wants to set that value to true. You could define:
+As an example, if you want to create a wrapper around a component called `MyText` that has `italicize` as one of its props, that always wants to set that value to true, you could define:
 
 ```ts
 const MyNewText: React.FunctionComponent<MyTextProps> = (props) => {
-  return <MyText {...props, italicize: true} />;
-}
+  return <MyText {...props} italicize={true} />;
+};
 ```
 
-When this is rendered, there is an entry for `MyNewText` which contains a `MyText` (another entry), which might contains `Text` (for react-native usage). The direct rendering pattern is one where a component can denote that it is safe to be called directly as a function, instead operating as a prop transform that gets applied to the underlying component.
+When this is rendered, there is an entry for `MyNewText` which contains a `MyText` (another entry), which might contain `Text` (for react-native usage). The direct rendering pattern is one where a component can denote that it is safe to be called directly as a function, instead operating as a prop transform that gets applied to the underlying component.
 
-- For the above to be safe, `MyNewText` should NOT use hooks. In the case of any conditional rendering logic this will break the rule of hooks.
+- For the above to be safe, `MyNewText` should NOT use hooks. In the case of any conditional rendering logic this will break the rules of hooks.
 
 There are two types of implementations in this folder:
 
-- `DirectComponent` - a functional component that marks itself as direct with a `_callDirect: true` attached property. This will then be called as a normal function component, with children included as part of props.
-- `LegacyDirectComponent` - the pattern currently used in this library that should be moved away from. In this case `_canCompose: true` is set as an attached property, and the function component will be called with children split from props.
+- `DirectComponent` - a functional component that marks itself as direct with a `_callDirect: true` attached property. This will then be called as a normal function component, with children included as part of props. Use the `directComponent()` helper to create these.
+- `LegacyDirectComponent` - the pattern currently used in legacy code that should be moved away from. In this case `_canCompose: true` is set as an attached property, and the function component will be called with children split from props.
 
-The internal logic of the JSX rendering helpers will handle both patterns. In the case of the newer `DirectComponent` pattern, the component will still work, even without any jsx hooks, whereas the `LegacyDirectComponent` pattern will have a somewhat undefined behavior with regards to children.
+The internal logic of the JSX rendering helpers (`renderForJsxRuntime` and `renderForClassicRuntime`) will handle both patterns. In the case of the newer `DirectComponent` pattern, the component will still work, even without any jsx hooks, whereas the `LegacyDirectComponent` pattern will have somewhat undefined behavior with regards to children.
 
-## Staged Rendering
+### Example: Using directComponent
 
-The issue with the direct component pattern above, is that hooks are integral to writing functional components. The staged rendering pattern is designed to help with this. In this case a component is implemented in two stages, the prep stage where hooks are called, and the rendering stage where the tree is emitted.
+```ts
+import { directComponent } from '@fluentui-react-native/framework-base';
+
+const MyNewText = directComponent<MyTextProps>((props) => {
+  return <MyText {...props} italicize={true} />;
+});
+```
+
+## Phased Rendering
+
+The issue with the direct component pattern above is that hooks are integral to writing functional components. The phased rendering pattern is designed to help with this. In this case a component is implemented in two phases: the prep phase where hooks are called, and the rendering phase where the tree is emitted.
+
+As above there is a newer and older version of the pattern:
+
+- `PhasedComponent` - the newer version of the pattern, where the returned component function expects children as part of props. Create these using `phasedComponent()`. The attached property is `_phasedRender`.
+- `ComposableFunction` (deprecated) - the older "staged" version, where children are split out and JSX hooks are required to render correctly. Create these using the deprecated `stagedComponent()`. The attached property is `_staged`.
+
+Note that while the newer patterns work without any JSX hooks, the hooks will enable element flattening.
+
+### Example: Using phasedComponent
+
+```ts
+import { phasedComponent } from '@fluentui-react-native/framework-base';
+
+const MyComponent = phasedComponent<MyComponentProps>((props) => {
+  // Phase 1: Hooks and logic
+  const theme = useTheme();
+  const styles = useStyles(theme, props);
+
+  // Phase 2: Return a component that renders
+  return (innerProps) => {
+    return <View style={styles}>{innerProps.children}</View>;
+  };
+});
+```
+
+## JSX Runtime
 
-As above there is a newer and older version of the pattern.
+This package provides a custom JSX runtime (`@fluentui-react-native/framework-base/jsx-runtime`) that automatically handles both direct and phased rendering patterns. When you use the `@jsxImportSource @fluentui-react-native/framework-base` pragma, the custom runtime will:
 
-- `StagedComponent` - the newer version of the pattern, where the returned component function expects children as part of props.
-- `StagedRender` - the older version, where children are split out and JSX hooks are required to render correctly.
+1. Detect components marked with `_callDirect` or `_canCompose` and call them directly
+2. Handle the different children patterns (props vs. rest args)
+3. Fall back to standard React rendering for normal components
 
-Note that while the newer patterns work without any JSX hooks, the hooks will enable the element flattening.
+This enables element flattening without requiring explicit calls to helper functions.

package/src/component-patterns/directComponent.ts

@@ -0,0 +1,9 @@
+import type { FunctionComponent } from './render.types';
+
+/**
+ * @param component functional component, usually a closure, to make into a direct component
+ * @return the same component with the direct component flag set, return type is a pure function component
+ */
+export function directComponent<TProps>(component: FunctionComponent<TProps>): FunctionComponent<TProps> {
+  return Object.assign(component, { _callDirect: true });
+}

package/src/component-patterns/extract.ts

@@ -0,0 +1,32 @@
+import type { ViewStyle, TextStyle, ImageStyle } from 'react-native';
+
+type StyleTypes = ViewStyle | TextStyle | ImageStyle;
+type PropsWithStyle = { style?: ViewStyle | TextStyle | ImageStyle };
+type PropsWithChildren = { children?: React.ReactNode };
+
+/**
+ * Extract the props from a React element. If the element is undefined, undefined will be returned.
+ * @param element The React element from which to extract the props.
+ * @returns The extracted props or undefined if the element is undefined.
+ */
+export function extractProps<T extends object>(element?: React.ReactElement): T | undefined {
+  return element ? (element.props as T) : undefined;
+}
+
+/**
+ * Extract the children from a React element. If the element is undefined, undefined will be returned.
+ * @param element The React element from which to extract the children.
+ * @returns The extracted children or undefined if the element is undefined.
+ */
+export function extractChildren(element?: React.ReactElement): React.ReactNode | undefined {
+  return extractProps<PropsWithChildren>(element)?.children;
+}
+
+/**
+ * Extract a style object from a React element. If the element is undefined or does not have a style prop, an empty object will be returned.
+ * @param element The React element from which to extract the style.
+ * @returns The extracted style object or an empty object if not available.
+ */
+export function extractStyle<T extends StyleTypes = ViewStyle>(element?: React.ReactElement): T {
+  return (extractProps<PropsWithStyle>(element)?.style as T) ?? ({} as T);
+}

package/src/component-patterns/phasedComponent.ts

@@ -0,0 +1,54 @@
+import React from 'react';
+import type { ComposableFunction, PhasedComponent, PhasedRender, FunctionComponent } from './render.types';
+import { renderForJsxRuntime } from './render';
+import type { LegacyDirectComponent } from './render.types';
+
+/**
+ * Extract the phased render function from a component, if it has one.
+ * Handles both the newer PhasedComponent pattern (_phasedRender) and the legacy
+ * ComposableFunction pattern (_staged) for backward compatibility.
+ *
+ * @param component - The component to extract the phased render from
+ * @returns The phased render function if present, undefined otherwise
+ */
+export function getPhasedRender<TProps>(component: React.ComponentType<TProps>): PhasedRender<TProps> | undefined {
+  // only a function component can have a phased render
+  if (typeof component === 'function') {
+    // if this has a phased render function, return it
+    if ((component as PhasedComponent<TProps>)._phasedRender) {
+      return (component as PhasedComponent<TProps>)._phasedRender;
+    } else if ((component as ComposableFunction<TProps>)._staged) {
+      // for backward compatibility check for staged render and return a wrapper that maps the signature
+      const staged = (component as ComposableFunction<TProps>)._staged;
+      return (props: TProps) => {
+        const { children, ...rest } = props as React.PropsWithChildren<TProps>;
+        const inner = staged(rest as TProps, ...React.Children.toArray(children));
+        // staged render functions were not consistently marking contents as composable, though they were treated
+        // as such in useHook. To maintain compatibility we mark the returned function as composable here. This was
+        // dangerous, but this shim is necessary for backward compatibility. The newer pattern is explicit about this.
+        if (typeof inner === 'function' && !(inner as LegacyDirectComponent<TProps>)._canCompose) {
+          return Object.assign(inner, { _canCompose: true });
+        }
+        return inner;
+      };
+    }
+  }
+  return undefined;
+}
+
+/**
+ * Take a phased render function and make a real component out of it, attaching the phased render function
+ * so it can be split if used in that manner.
+ * @param getInnerPhase - phased render function to wrap into a staged component
+ */
+export function phasedComponent<TProps>(getInnerPhase: PhasedRender<TProps>): FunctionComponent<TProps> {
+  return Object.assign(
+    (props: React.PropsWithChildren<TProps>) => {
+      // pull out children from props
+      const { children, ...outerProps } = props;
+      const Inner = getInnerPhase(outerProps as TProps);
+      return renderForJsxRuntime(Inner, { children });
+    },
+    { _phasedRender: getInnerPhase },
+  );
+}

package/src/component-patterns/render.ts

@@ -4,7 +4,7 @@ import type { RenderType, RenderResult, DirectComponent, LegacyDirectComponent }
 
 export type CustomRender = () => RenderResult;
 
-function asDirectComponent<TProps>(type: RenderType): DirectComponent<TProps> | undefined {
+export function asDirectComponent<TProps>(type: RenderType): DirectComponent<TProps> | undefined {
   if (typeof type === 'function' && (type as DirectComponent<TProps>)._callDirect) {
     return type as DirectComponent<TProps>;
   }
@@ -22,7 +22,7 @@ export function renderForJsxRuntime<TProps>(
   type: React.ElementType,
   props: React.PropsWithChildren<TProps>,
   key?: React.Key,
-  jsxFn: typeof ReactJSX.jsx = ReactJSX.jsx,
+  jsxFn: typeof ReactJSX.jsx = undefined,
 ): RenderResult {
   const legacyDirect = asLegacyDirectComponent(type);
   if (legacyDirect) {
@@ -35,20 +35,28 @@ export function renderForJsxRuntime<TProps>(
     const newProps = { ...props, key };
     return directComponent(newProps);
   }
-  return jsxFn(type, props, key);
+
+  // auto-detect whether to use jsx or jsxs based on number of children, 0 or 1 = jsx, more than 1 = jsxs
+  if (!jsxFn) {
+    if (React.Children.count(props.children) > 1) {
+      jsxFn = ReactJSX.jsxs;
+    } else {
+      jsxFn = ReactJSX.jsx;
+    }
+  }
+  // Extract key from props to avoid React 19 warning about spreading key prop
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  const { key: propsKey, ...propsWithoutKey } = props as any;
+  // Use explicitly passed key, or fall back to key from props
+  const finalKey = key ?? propsKey;
+  // now call the appropriate jsx function to render the component
+  return jsxFn(type, propsWithoutKey, finalKey);
 }
 
 export function renderForClassicRuntime<TProps>(type: RenderType, props: TProps, ...children: React.ReactNode[]): RenderResult {
-  const legacyDirect = asLegacyDirectComponent(type);
-  if (legacyDirect) {
-    return legacyDirect(props, ...children) as RenderResult;
-  }
-  const directComponent = asDirectComponent(type);
-  if (directComponent) {
-    const newProps = { ...props, children };
-    return directComponent(newProps);
-  }
-  return React.createElement(type, props, ...children);
+  // if it is a non-string type with _canCompose set just call the function directly, otherwise call createElement as normal
+  const propsWithChildren = { children, ...props };
+  return renderForJsxRuntime(type as React.ElementType, propsWithChildren);
 }
 
 export const renderSlot = renderForClassicRuntime;

package/src/component-patterns/render.types.ts

@@ -1,11 +1,14 @@
 import type React from 'react';
-import type ReactJSX from 'react/jsx-runtime';
+//import type ReactJSX from 'react/jsx-runtime';
+import type { FurnJSX } from '../jsx-namespace';
 
 /**
  * Base types for rendering components in a react application, extracted from react types
  */
-export type RenderResult = ReturnType<typeof ReactJSX.jsx>;
-export type RenderType = Parameters<typeof ReactJSX.jsx>[0] | string;
+export type RenderResult = FurnJSX.Element;
+//export type RenderResult = ReturnType<typeof ReactJSX.jsx>;
+export type RenderType = FurnJSX.ElementType;
+//export type RenderType = Parameters<typeof ReactJSX.jsx>[0] | string;
 
 /**
  * The standard element type inputs for react and react-native. This might be View or Button, or it might be 'div' in web. Effectively
@@ -13,6 +16,11 @@ export type RenderType = Parameters<typeof ReactJSX.jsx>[0] | string;
  */
 export type NativeReactType = RenderType;
 
+/**
+ * Get the props from a react component type
+ */
+export type PropsOf<TComponent> = TComponent extends React.JSXElementConstructor<infer P> ? P : never;
+
 /**
  * DIRECT RENDERING
  *
@@ -29,78 +37,95 @@ export type NativeReactType = RenderType;
 /**
  * type of the render function, not a FunctionComponent to help prevent hook usage
  */
-export type DirectComponentFunction<TProps> = (props: TProps) => RenderResult;
+export type FunctionComponentCore<TProps> = (props: TProps) => RenderResult;
+
+/**
+ * A function component that returns an element type. This allows for the empty call props usage for native
+ * components, as well as handles the returns of React components.
+ */
+export type FunctionComponent<TProps> = FunctionComponentCore<TProps> & {
+  displayName?: string;
+};
 
 /**
  * The full component definition that has the attached properties to allow the jsx handlers to render it directly.
  */
-export type DirectComponent<TProps> = DirectComponentFunction<TProps> & {
+export type DirectComponent<TProps> = FunctionComponentCore<TProps> & {
   displayName?: string;
   _callDirect?: boolean;
 };
 
+type LegacyComponentFunction<TProps> = (props: TProps, ...children: React.ReactNode[]) => RenderResult;
+
 /**
  * Legacy slot function type, this allows the rendering handlers to bypass the normal JSX rendering and call the function
  * directly. This expects the function to have children as the last argument of the call which isn't consistent with standard
  * react usage, where children are passed as a prop. If writing new components use the DirectComponent type instead.
  * @deprecated use DirectComponent instead
  */
-export type LegacyDirectComponent<TProps> = React.FunctionComponent<TProps> & {
+export type LegacyDirectComponent<TProps> = LegacyComponentFunction<TProps> & {
   _canCompose?: boolean;
 };
 
 /**
- * Legacy type name used for consistency with old rendering patterns.
+ * Slot function type used in the composition framework. Slot functions return React elements (not arbitrary ReactNode values)
+ * since they always either call staged render functions or React.createElement.
  */
-export type SlotFn<TProps> = LegacyDirectComponent<TProps>;
+export type SlotFn<TProps> = {
+  (props: TProps, ...children: React.ReactNode[]): React.ReactElement | null;
+  _canCompose?: boolean;
+};
 
 /**
- * MULTI-STAGE RENDERING
+ * PHASED RENDERING (formerly called "staged" or "two-stage" rendering)
  *
- * The above direct rendering pattern is useful for simple components, but it does not allow for hooks or complex logic. The staged render pattern allows
- * for a component to be rendered in two stages, allowing for hooks to be used in the first stage and then the second stage to be a simple render function that can
+ * The above direct rendering pattern is useful for simple components, but it does not allow for hooks or complex logic. The phased render pattern allows
+ * for a component to be rendered in two phases, allowing for hooks to be used in the first phase and then the second phase to be a simple render function that can
  * be called directly.
  *
- * In code that respects the pattern the first stage will be called with props (though children will not be present) and will return a function that will be called
- * with additional props, this time with children present. This allows for the first stage to handle all the logic and hooks, while the second stage can be a simple render function
+ * In code that respects the pattern, the first phase will be called with props (though children will not be present) and will return a function that will be called
+ * with additional props, this time with children present. This allows for the first phase to handle all the logic and hooks, while the second phase can be a simple render function
  * that can leverage direct rendering if supported.
  *
- * The component itself will be a FunctionComponent, but it will have an attached property that is the staged render function. This allows the component to be used in two
+ * The component itself will be a FunctionComponent, but it will have an attached property that is the phased render function. This allows the component to be used in two
  * parts via the useSlot hook, or to be used directly in JSX/TSX as a normal component.
  */
 
 /**
- * This is an updated version of the staged render that handles children and types more consistently. Generally children
- * will be passed as part of the props for component rendering, it is inconsistent to have them as a variable argument.
+ * Phased render function signature. This is the recommended pattern for components that need hooks.
+ *
+ * Phase 1 receives props (without children) and can use hooks to compute derived state.
+ * Phase 2 returns a component that will be called with props including children.
  *
- * The `children` prop will be automatically inferred and typed correctly by the prop type. Hooks are still expected
+ * Children will be passed as part of the props for component rendering. The `children` prop will be
+ * automatically inferred and typed correctly by the prop type.
  */
-export type TwoStageRender<TProps> = (props: TProps) => React.ComponentType<React.PropsWithChildren<TProps>>;
+export type PhasedRender<TProps> = (props: TProps) => React.ComponentType<React.PropsWithChildren<TProps>>;
 
 /**
- * Component type for a component that can be rendered in two stages, with the attached render function.
+ * Component type for a component that can be rendered in two phases, with the attached phased render function.
+ * Use phasedComponent() to create these.
  */
-export type StagedComponent<TProps> = React.FunctionComponent<TProps> & {
-  _twoStageRender?: TwoStageRender<TProps>;
+export type PhasedComponent<TProps> = FunctionComponent<TProps> & {
+  _phasedRender?: PhasedRender<TProps>;
 };
-
 /**
- * The final rendering of the props in a staged render. This is the function component signature that matches that of
+ * The final rendering of the props in a phased render. This is the function component signature that matches that of
  * React.createElement, children (if present) will be part of the variable args at the end.
  */
-export type FinalRender<TProps> = (props: TProps, ...children: React.ReactNode[]) => JSX.Element | null;
+export type FinalRender<TProps> = (props: TProps, ...children: React.ReactNode[]) => FurnJSX.Element | null;
 
 /**
- * Signature for a staged render function.
- * @deprecated Use TwoStageRender instead
+ * Legacy staged render function signature.
+ * @deprecated Use PhasedRender instead. This older pattern splits children from props which is inconsistent with React conventions.
  */
 export type StagedRender<TProps> = (props: TProps, ...args: any[]) => FinalRender<TProps>;
 
 /**
- * Signature for a component that uses the staged render pattern.
- * @deprecated Use TwoStageRender instead
+ * Legacy component type that uses the staged render pattern.
+ * @deprecated Use PhasedComponent instead. Create with phasedComponent() rather than stagedComponent().
  */
-export type ComposableFunction<TProps> = React.FunctionComponent<TProps> & { _staged?: StagedRender<TProps> };
+export type ComposableFunction<TProps> = FunctionComponent<TProps> & { _staged?: StagedRender<TProps> };
 
 /**
  * A type aggregating all the custom types that can be used in the render process.
@@ -109,6 +134,6 @@ export type ComposableFunction<TProps> = React.FunctionComponent<TProps> & { _st
 export type AnyCustomType<TProps> =
   | React.FunctionComponent<TProps>
   | DirectComponent<TProps>
-  | StagedComponent<TProps>
+  | PhasedComponent<TProps>
   | ComposableFunction<TProps>
   | LegacyDirectComponent<TProps>;

package/src/component-patterns/stagedComponent.ts

@@ -0,0 +1,24 @@
+import * as React from 'react';
+
+import type { StagedRender, ComposableFunction } from './render.types';
+
+function asArray<T>(val: T | T[]): T[] {
+  return Array.isArray(val) ? val : [val];
+}
+
+/**
+ * Take a staged render function and make a real component out of it
+ *
+ * @param staged - staged render function to wrap into a staged component
+ * @param memo - optional flag to enable wrapping the created component in a React.memo HOC
+ * @deprecated Use phasedComponent from phasedComponent.ts instead
+ */
+export function stagedComponent<TProps>(staged: StagedRender<TProps>, memo?: boolean): ComposableFunction<TProps> {
+  const component = (props: React.PropsWithChildren<TProps>) => {
+    const { children, ...rest } = props;
+    return staged(rest as TProps)({} as React.PropsWithChildren<TProps>, asArray(children));
+  };
+  const stagedComponent = memo ? React.memo(component) : component;
+  Object.assign(stagedComponent, { _staged: staged });
+  return stagedComponent as ComposableFunction<TProps>;
+}

package/src/immutable-merge/Merge.test.ts

@@ -305,7 +305,11 @@ describe('Immutable merge unit tests', () => {
   const arrayMerger = (...targets: any[]) => {
     const arrays = targets.filter((t) => Array.isArray(t));
     let result = [];
-    arrays.forEach((v) => (result = result.concat(...v)));
+    for (const v of arrays) {
+      if (v.length > 0) {
+        result = result.concat(...v);
+      }
+    }
     return result;
   };
 

package/src/index.ts

@@ -19,22 +19,42 @@ export type { StyleProp } from './merge-props/mergeStyles.types';
 export { mergeStyles } from './merge-props/mergeStyles';
 export { mergeProps } from './merge-props/mergeProps';
 
-// component pattern exports
-export { renderForClassicRuntime, renderForJsxRuntime, renderSlot } from './component-patterns/render';
+// component pattern exports - extracting from elements
+export { extractChildren, extractProps, extractStyle } from './component-patterns/extract';
+
+// component pattern exports - rendering utilities
+export { renderForJsxRuntime, renderSlot, asDirectComponent } from './component-patterns/render';
+
+// component pattern exports - core types
 export type {
   DirectComponent,
-  DirectComponentFunction,
+  FunctionComponent,
+  FunctionComponentCore,
   LegacyDirectComponent,
-  StagedComponent,
-  StagedRender,
-  TwoStageRender,
+  PhasedComponent,
+  PhasedRender,
+  PropsOf,
   RenderType,
   RenderResult,
+  StagedRender,
   ComposableFunction,
   FinalRender,
   SlotFn,
   NativeReactType,
 } from './component-patterns/render.types';
+
+// component pattern exports - component builders
+export { directComponent } from './component-patterns/directComponent';
+export { getPhasedRender, phasedComponent } from './component-patterns/phasedComponent';
+export { stagedComponent } from './component-patterns/stagedComponent';
+
+// component pattern exports - legacy JSX handlers
 export { withSlots } from './component-patterns/withSlots';
-export { stagedComponent, twoStageComponent } from './component-patterns/stagedComponent';
+
+// jsx runtime exports
 export { jsx, jsxs } from './jsx-runtime';
+export type { FurnJSX } from './jsx-namespace';
+
+// general utilities
+export { filterProps } from './utilities/filterProps';
+export type { PropsFilter } from './utilities/filterProps';

package/src/jsx-namespace.ts

@@ -0,0 +1,83 @@
+import type React from 'react';
+
+/**
+ * This file defines a custom JSX namespace that re-exports React's JSX types, but also allows us to add our own custom behavior to the JSX runtime.
+ * The main reason we need this is to support our "direct component" pattern, which allows certain components to bypass React's createElement and
+ * return their own React elements directly from the JSX runtime.
+ *
+ * Exporting this custom namespace is required to make intrinsic attributes like key and ref work correctly with our custom JSX functions. The normal
+ * fallback behavior if not defined is to not allow any attributes on intrinsic elements, which breaks a lot of React functionality.
+ *
+ * The custom behavior is implemented in the jsx and jsxs functions, which first check if the type being rendered is a direct component and if so, call it directly.
+ *
+ * Thanks to the emotion library's jsx-namespace for providing a reference implementation of how to do this while handling both React 18 and React 19's
+ * changes to the JSX types.
+ */
+
+type IsPreReact19 = 2 extends Parameters<React.FunctionComponent<any>>['length'] ? true : false;
+
+/**
+ * The following types are intrinsic types for React, but handled in a way that allows them to be correctly resolved in both
+ * React 18 and React 19.
+ *
+ * React 18:
+ * - JSX.Element, JSX.ElementClass, etc.
+ * - no React.JSX namespace
+ *
+ * React 19:
+ * - React.JSX.Element, React.JSX.ElementClass, etc.
+ * - no global JSX namespace
+ *
+ * In both cases, we want to be able to reference these types in our custom JSX namespace, so we conditionally define them based on whether we're in
+ * a pre-React 19 environment or not. The @ts-expect-error comments are used because both can't be valid at the same time so there will always be
+ * an error.
+ */
+
+/** @ts-expect-error references types for both react 18 and react 19, only one can be valid at a time */
+type ReactJSXElement = true extends IsPreReact19 ? JSX.Element : React.JSX.Element;
+
+/** @ts-expect-error references types for both react 18 and react 19, only one can be valid at a time */
+type ReactJSXElementClass = true extends IsPreReact19 ? JSX.ElementClass : React.JSX.ElementClass;
+
+/** @ts-expect-error references types for both react 18 and react 19, only one can be valid at a time */
+type ReactJSXElementAttributesProperty = true extends IsPreReact19 ? JSX.ElementAttributesProperty : React.JSX.ElementAttributesProperty;
+
+/** @ts-expect-error references types for both react 18 and react 19, only one can be valid at a time */
+type ReactJSXElementChildrenAttribute = true extends IsPreReact19 ? JSX.ElementChildrenAttribute : React.JSX.ElementChildrenAttribute;
+
+// prettier-ignore
+/** @ts-expect-error references types for both react 18 and react 19, only one can be valid at a time */
+type ReactJSXLibraryManagedAttributes<C, P> = true extends IsPreReact19 ? JSX.LibraryManagedAttributes<C, P> : React.JSX.LibraryManagedAttributes<C, P>;
+
+/** @ts-expect-error references types for both react 18 and react 19, only one can be valid at a time */
+type ReactJSXIntrinsicAttributes = true extends IsPreReact19 ? JSX.IntrinsicAttributes : React.JSX.IntrinsicAttributes;
+
+// prettier-ignore
+/** @ts-expect-error references types for both react 18 and react 19, only one can be valid at a time */
+type ReactJSXIntrinsicClassAttributes<T> = true extends IsPreReact19 ? JSX.IntrinsicClassAttributes<T> : React.JSX.IntrinsicClassAttributes<T>;
+
+/** @ts-expect-error references types for both react 18 and react 19, only one can be valid at a time */
+type ReactJSXIntrinsicElements = true extends IsPreReact19 ? JSX.IntrinsicElements : React.JSX.IntrinsicElements;
+
+// based on the code from @types/react@18.2.8
+// https://github.com/DefinitelyTyped/DefinitelyTyped/blob/3197efc097d522c4bf02b94e1a0766d007d6cdeb/types/react/index.d.ts#LL3204C13-L3204C13
+type ReactJSXElementType = true extends IsPreReact19 ? string | React.JSXElementConstructor<any> : React.JSX.ElementType;
+
+// eslint-disable-next-line @typescript-eslint/no-namespace
+export declare namespace FurnJSX {
+  export type ElementType = ReactJSXElementType;
+  // eslint-disable-next-line @typescript-eslint/no-empty-object-type
+  export interface Element extends ReactJSXElement {}
+  // eslint-disable-next-line @typescript-eslint/no-empty-object-type
+  export interface ElementClass extends ReactJSXElementClass {}
+  // eslint-disable-next-line @typescript-eslint/no-empty-object-type
+  export interface ElementAttributesProperty extends ReactJSXElementAttributesProperty {}
+  // eslint-disable-next-line @typescript-eslint/no-empty-object-type
+  export interface ElementChildrenAttribute extends ReactJSXElementChildrenAttribute {}
+  export type LibraryManagedAttributes<C, P> = ReactJSXLibraryManagedAttributes<C, P>;
+  // eslint-disable-next-line @typescript-eslint/no-empty-object-type
+  export interface IntrinsicAttributes extends ReactJSXIntrinsicAttributes {}
+  // eslint-disable-next-line @typescript-eslint/no-empty-object-type
+  export interface IntrinsicClassAttributes<T> extends ReactJSXIntrinsicClassAttributes<T> {}
+  export type IntrinsicElements = ReactJSXIntrinsicElements;
+}

package/src/jsx-runtime.ts

@@ -1,11 +1,15 @@
 import type React from 'react';
 import * as ReactJSX from 'react/jsx-runtime';
 import { renderForJsxRuntime } from './component-patterns/render';
+export type { FurnJSX as JSX } from './jsx-namespace';
 
-export function jsx(type: React.ElementType, props: React.PropsWithChildren<unknown>, key?: React.Key): React.ReactElement {
+export const jsx: typeof ReactJSX.jsx = (type, props, key?: React.Key) => {
   return renderForJsxRuntime(type, props, key, ReactJSX.jsx);
-}
+};
 
-export function jsxs(type: React.ElementType, props: React.PropsWithChildren<unknown>, key?: React.Key): React.ReactElement {
+export const jsxs: typeof ReactJSX.jsxs = (type, props, key?: React.Key) => {
   return renderForJsxRuntime(type, props, key, ReactJSX.jsxs);
-}
+};
+
+// Re-export Fragment for <></> syntax
+export { Fragment } from 'react/jsx-runtime';

package/src/memo-cache/README.md

@@ -134,7 +134,7 @@ export const MyComponent = (props: IMyComponentProps) => {
   }, [theme]);
 
   // merge the styles if a style is passed in via props, caching the union to ensure consistent object identity
-  newProps.style = newProps.style ? themeLocalCache(() => mergeStyles(style, newProps.style), [newProps.style])[0] : style;
+  newProps.style = newProps.style ? themeLocalCache(() => mergeStyles<MyStyleType>(style, newProps.style), [newProps.style])[0] : style;
 
   return <InnerControl {...newProps} />;
 };

package/src/merge-props/mergeStyles.test.ts

@@ -1,8 +1,9 @@
-import type { ColorValue } from 'react-native';
-
 import { flattenStyle, mergeAndFlattenStyles, mergeStyles } from './mergeStyles';
 import type { StyleProp } from './mergeStyles.types';
 
+type OpaqueColorValue = symbol & { __TYPE__: 'Color' };
+type ColorValue = string | OpaqueColorValue;
+
 interface IFakeStyle {
   backgroundColor?: ColorValue;
   color?: ColorValue;