@erquhart/heroui-native 1.0.0-beta.10.1

package/src/components/spinner/spinner.tsx

@@ -0,0 +1,195 @@
+import { forwardRef, useMemo } from 'react';
+import type { View } from 'react-native';
+import Animated from 'react-native-reanimated';
+import { AnimationSettingsProvider } from '../../helpers/contexts/animation-settings-context';
+import { useThemeColor } from '../../helpers/theme';
+import { createContext, getElementWithDefault } from '../../helpers/utils';
+import * as ActivityIndicatorPrimitives from '../../primitives/activity-indicator';
+import { SpinnerIcon } from './spinner-icon';
+import {
+  useSpinnerIndicatorAnimation,
+  useSpinnerRootAnimation,
+} from './spinner.animation';
+import { DISPLAY_NAME, SPINNER_SIZE_MAP } from './spinner.constants';
+import spinnerStyles from './spinner.styles';
+import type {
+  SpinnerContextValue,
+  SpinnerIndicatorProps,
+  SpinnerProps,
+} from './spinner.types';
+
+const AnimatedRoot = Animated.createAnimatedComponent(
+  ActivityIndicatorPrimitives.Root
+);
+
+const AnimatedIndicator = Animated.createAnimatedComponent(
+  ActivityIndicatorPrimitives.Indicator
+);
+
+const [SpinnerProvider, useSpinnerContext] = createContext<SpinnerContextValue>(
+  {
+    name: 'SpinnerContext',
+  }
+);
+
+const SpinnerRoot = forwardRef<View, SpinnerProps>((props, ref) => {
+  const {
+    children,
+    size = 'md',
+    color = 'default',
+    isLoading = true,
+    className,
+    animation,
+    ...restProps
+  } = props;
+
+  const tvStyles = spinnerStyles.root({
+    size,
+    className,
+  });
+
+  const { entering, exiting, isAllAnimationsDisabled } =
+    useSpinnerRootAnimation({
+      animation,
+    });
+
+  const indicatorElement = useMemo(
+    () =>
+      getElementWithDefault(
+        children,
+        DISPLAY_NAME.INDICATOR,
+        <SpinnerIndicator />
+      ),
+    [children]
+  );
+
+  const contextValue = useMemo(
+    () => ({
+      size,
+      color,
+      isLoading,
+    }),
+    [size, color, isLoading]
+  );
+
+  const animationSettingsContextValue = useMemo(
+    () => ({
+      isAllAnimationsDisabled,
+    }),
+    [isAllAnimationsDisabled]
+  );
+
+  return (
+    <AnimationSettingsProvider value={animationSettingsContextValue}>
+      <SpinnerProvider value={contextValue}>
+        <AnimatedRoot
+          ref={ref}
+          entering={entering}
+          exiting={exiting}
+          isLoading={isLoading}
+          className={tvStyles}
+          {...restProps}
+        >
+          {children || indicatorElement}
+        </AnimatedRoot>
+      </SpinnerProvider>
+    </AnimationSettingsProvider>
+  );
+});
+
+// --------------------------------------------------
+
+const SpinnerIndicator = forwardRef<View, SpinnerIndicatorProps>(
+  (props, ref) => {
+    const {
+      children,
+      className,
+      style,
+      iconProps,
+      animation,
+      isAnimatedStyleActive = true,
+      ...restProps
+    } = props;
+
+    const { size, color, isLoading } = useSpinnerContext();
+
+    const [
+      themeColorAccent,
+      themeColorSuccess,
+      themeColorWarning,
+      themeColorDanger,
+    ] = useThemeColor(['accent', 'success', 'warning', 'danger']);
+
+    const indicatorClassName = spinnerStyles.indicator({
+      className,
+    });
+
+    const iconSize = SPINNER_SIZE_MAP[size];
+
+    const colorMap: Record<string, string> = {
+      default: themeColorAccent,
+      success: themeColorSuccess,
+      warning: themeColorWarning,
+      danger: themeColorDanger,
+    };
+
+    const iconColor = colorMap[color] || color;
+
+    const { rContainerStyle } = useSpinnerIndicatorAnimation({
+      animation,
+      isLoading,
+    });
+
+    const indicatorStyle = isAnimatedStyleActive
+      ? [rContainerStyle, style]
+      : style;
+
+    if (!isLoading) {
+      return null;
+    }
+
+    return (
+      <AnimatedIndicator
+        ref={ref}
+        className={indicatorClassName}
+        style={indicatorStyle}
+        {...restProps}
+      >
+        {children || (
+          <SpinnerIcon
+            width={iconProps?.width ?? iconSize}
+            height={iconProps?.height ?? iconSize}
+            color={iconProps?.color ?? iconColor}
+          />
+        )}
+      </AnimatedIndicator>
+    );
+  }
+);
+
+// --------------------------------------------------
+
+SpinnerRoot.displayName = DISPLAY_NAME.ROOT;
+SpinnerIndicator.displayName = DISPLAY_NAME.INDICATOR;
+
+/**
+ * Compound Spinner component with sub-components
+ *
+ * @component Spinner - Main container that controls loading state, size, and color.
+ * Renders a default animated indicator if no children provided.
+ *
+ * @component Spinner.Indicator - Optional sub-component for customizing animation configuration
+ * and icon appearance. Accepts custom children to replace the default icon.
+ * When omitted, Spinner uses a default indicator with standard animation settings.
+ *
+ * Props flow from Spinner to Indicator via context (size, color, isLoading).
+ * The indicator only renders when isLoading is true.
+ *
+ * @see Full documentation: https://heroui.com/components/spinner
+ */
+const CompoundSpinner = Object.assign(SpinnerRoot, {
+  /** @optional Customize animation configuration and icon appearance */
+  Indicator: SpinnerIndicator,
+});
+
+export default CompoundSpinner;

package/src/components/spinner/spinner.types.ts

@@ -0,0 +1,158 @@
+import type { ViewProps } from 'react-native';
+import type {
+  AnimatedProps,
+  EntryOrExitLayoutType,
+  WithTimingConfig,
+} from 'react-native-reanimated';
+import type {
+  Animation,
+  AnimationRoot,
+  AnimationValue,
+} from '../../helpers/types/animation';
+
+/**
+ * Base spinner size variants
+ */
+export type SpinnerSize = 'sm' | 'md' | 'lg';
+
+/**
+ * Base spinner color variants
+ */
+export type SpinnerColor = 'default' | 'success' | 'warning' | 'danger';
+
+/**
+ * Animation configuration for spinner root component
+ */
+export type SpinnerRootAnimation = AnimationRoot<{
+  entering?: AnimationValue<{
+    /**
+     * Custom entering animation for spinner root
+     */
+    value?: EntryOrExitLayoutType;
+  }>;
+  exiting?: AnimationValue<{
+    /**
+     * Custom exiting animation for spinner root
+     */
+    value?: EntryOrExitLayoutType;
+  }>;
+}>;
+
+/**
+ * Props for the main Spinner component
+ */
+export interface SpinnerProps extends AnimatedProps<ViewProps> {
+  /** Content to render inside the spinner */
+  children?: React.ReactNode;
+
+  /** Size of the spinner @default 'md' */
+  size?: SpinnerSize;
+
+  /** Color theme of the spinner @default 'default' */
+  color?: SpinnerColor | (string & {});
+
+  /** Whether the spinner is loading @default true */
+  isLoading?: boolean;
+
+  /** Custom class name for the spinner */
+  className?: string;
+
+  /**
+   * Animation configuration for spinner root
+   * - `"disable-all"`: Disable all animations including children
+   * - `false` or `"disabled"`: Disable only root animations
+   * - `true` or `undefined`: Use default animations
+   * - `object`: Custom animation configuration
+   */
+  animation?: SpinnerRootAnimation;
+}
+
+/**
+ * Props for icon component
+ */
+export interface SpinnerIconProps {
+  /** Width of the icon */
+  width?: number | string;
+
+  /** Height of the icon */
+  height?: number | string;
+
+  /** Color of the icon */
+  color?: string;
+}
+
+/**
+ * Animation configuration for spinner indicator component
+ */
+export type SpinnerIndicatorAnimation = Animation<{
+  rotation?: AnimationValue<{
+    /**
+     * Rotation speed multiplier
+     * @default 1.1
+     */
+    speed?: number;
+    /**
+     * Animation easing configuration
+     * @default Easing.linear
+     */
+    easing?: WithTimingConfig['easing'];
+  }>;
+}>;
+
+/**
+ * Props for the SpinnerIndicator component
+ */
+export interface SpinnerIndicatorProps extends AnimatedProps<ViewProps> {
+  /** Content to render inside the indicator */
+  children?: React.ReactNode;
+
+  /** Props for the default icon */
+  iconProps?: SpinnerIconProps;
+
+  /** Custom class name for the indicator element
+   *
+   * @note The following style properties are occupied by animations and cannot be set via className:
+   * - `transform` (specifically `rotate`) - Animated for continuous rotation animation
+   *
+   * To customize this property, use the `animation` prop:
+   * ```tsx
+   * <Spinner.Indicator
+   *   animation={{
+   *     rotation: { speed: 1.1, easing: Easing.linear }
+   *   }}
+   * />
+   * ```
+   *
+   * To completely disable animated styles and use your own via className or style prop, set `isAnimatedStyleActive={false}`.
+   */
+  className?: string;
+
+  /**
+   * Animation configuration for spinner indicator
+   * - `false` or `"disabled"`: Disable all animations
+   * - `true` or `undefined`: Use default animations
+   * - `object`: Custom animation configuration
+   */
+  animation?: SpinnerIndicatorAnimation;
+  /**
+   * Whether animated styles (react-native-reanimated) are active
+   * When `false`, the animated style is removed and you can implement custom logic
+   * This prop should only be used when you want to write custom styling logic instead of the default animated styles
+   * @default true
+   */
+  isAnimatedStyleActive?: boolean;
+}
+
+/**
+ * Context value for spinner components
+ */
+export interface SpinnerContextValue {
+  /** Size of the spinner */
+  size: SpinnerSize;
+
+  /** Color of the spinner */
+  color: SpinnerColor | string;
+
+  /** Whether the spinner is loading */
+  isLoading: boolean;
+}

package/src/components/surface/index.ts

@@ -0,0 +1,2 @@
+export { default as Surface, useSurface } from './surface';
+export type { SurfaceRootProps, SurfaceVariant } from './surface.types';

package/src/components/surface/surface.animation.ts

@@ -0,0 +1,18 @@
+import { useCombinedAnimationDisabledState } from '../../helpers/hooks';
+import type { AnimationRootDisableAll } from '../../helpers/types/animation';
+
+/**
+ * Animation hook for Surface root component
+ * Handles root-level animation configuration and provides context for child components
+ */
+export function useSurfaceRootAnimation(options: {
+  animation: AnimationRootDisableAll | undefined;
+}) {
+  const { animation } = options;
+
+  const isAllAnimationsDisabled = useCombinedAnimationDisabledState(animation);
+
+  return {
+    isAllAnimationsDisabled,
+  };
+}

package/src/components/surface/surface.constants.ts

@@ -0,0 +1,6 @@
+/**
+ * Display names for Surface components
+ */
+export const DISPLAY_NAME = {
+  ROOT: 'HeroUINative.Surface.Root',
+};

package/src/components/surface/surface.md

@@ -0,0 +1,141 @@
+# Surface
+
+Container component that provides elevation and background styling.
+
+## Imports
+
+Note: Before importing this component, ensure you have completed the setup as per the [Quick Start guide](../../../README.md).
+
+```tsx
+import { Surface } from 'heroui-native';
+```
+
+## Usage
+
+### Basic Usage
+
+The Surface component creates a container with consistent padding and styling.
+
+```tsx
+<Surface>...</Surface>
+```
+
+### Variants
+
+Control the visual appearance with different surface levels.
+
+```tsx
+<Surface variant="default">
+  ...
+</Surface>
+
+<Surface variant="secondary">
+  ...
+</Surface>
+
+<Surface variant="tertiary">
+  ...
+</Surface>
+
+<Surface variant="quaternary">
+  ...
+</Surface>
+```
+
+### Nested Surfaces
+
+Create visual hierarchy by nesting surfaces with different variants.
+
+```tsx
+<Surface variant="default">
+  ...
+  <Surface variant="secondary">
+    ...
+    <Surface variant="tertiary">
+      ...
+      <Surface variant="quaternary">...</Surface>
+    </Surface>
+  </Surface>
+</Surface>
+```
+
+### Custom Styling
+
+Apply custom styles using className or style props.
+
+```tsx
+<Surface className="bg-accent-soft">
+  ...
+</Surface>
+
+<Surface variant="quaternary" className="p-0">
+  ...
+</Surface>
+```
+
+### Disable All Animations
+
+Disable all animations including children by using the `"disable-all"` value for the `animation` prop.
+
+```tsx
+{
+  /* Disable all animations including children */
+}
+<Surface animation="disable-all">No Animations</Surface>;
+```
+
+## Example
+
+```tsx
+import { Surface } from 'heroui-native';
+import { Text, View } from 'react-native';
+
+export default function SurfaceExample() {
+  return (
+    <View className="gap-4">
+      <Surface variant="default" className="gap-2">
+        <AppText className="text-foreground">Surface Content</AppText>
+        <AppText className="text-muted">
+          This is a default surface variant. It uses bg-surface styling.
+        </AppText>
+      </Surface>
+
+      <Surface variant="secondary" className="gap-2">
+        <AppText className="text-foreground">Surface Content</AppText>
+        <AppText className="text-muted">
+          This is a secondary surface variant. It uses bg-surface-secondary
+          styling.
+        </AppText>
+      </Surface>
+
+      <Surface variant="tertiary" className="gap-2">
+        <AppText className="text-foreground">Surface Content</AppText>
+        <AppText className="text-muted">
+          This is a tertiary surface variant. It uses bg-surface-tertiary
+          styling.
+        </AppText>
+      </Surface>
+
+      <Surface variant="quaternary" className="gap-2">
+        <AppText className="text-foreground">Surface Content</AppText>
+        <AppText className="text-muted">
+          This is a quaternary surface variant. It uses bg-surface-quaternary
+          styling.
+        </AppText>
+      </Surface>
+    </View>
+  );
+}
+```
+
+## API Reference
+
+### Surface
+
+| prop           | type                                                                      | default     | description                                                                               |
+| -------------- | ------------------------------------------------------------------------- | ----------- | ----------------------------------------------------------------------------------------- |
+| `variant`      | `'default' \| 'secondary' \| 'tertiary' \| 'quaternary' \| 'transparent'` | `'default'` | Visual variant controlling background color and border                                    |
+| `children`     | `React.ReactNode`                                                         | -           | Content to be rendered inside the surface                                                 |
+| `className`    | `string`                                                                  | -           | Additional CSS classes to apply                                                           |
+| `animation`    | `"disable-all" \| undefined`                                              | `undefined` | Animation configuration. Use `"disable-all"` to disable all animations including children |
+| `...ViewProps` | `ViewProps`                                                               | -           | All standard React Native View props are supported                                        |

package/src/components/surface/surface.styles.ts

@@ -0,0 +1,26 @@
+import { StyleSheet } from 'react-native';
+import { tv } from 'tailwind-variants';
+
+const root = tv({
+  base: 'p-4 rounded-3xl overflow-hidden',
+  variants: {
+    variant: {
+      default: 'bg-surface',
+      secondary: 'bg-surface-secondary',
+      tertiary: 'bg-surface-tertiary',
+      quaternary: 'bg-surface-quaternary',
+      transparent: 'bg-transparent',
+    },
+  },
+  defaultVariants: {
+    variant: 'default',
+  },
+});
+
+export const styleSheet = StyleSheet.create({
+  root: {
+    borderCurve: 'continuous',
+  },
+});
+
+export default root;

package/src/components/surface/surface.tsx

@@ -0,0 +1,66 @@
+import { forwardRef, useMemo } from 'react';
+import { View } from 'react-native';
+import { AnimationSettingsProvider } from '../../helpers/contexts/animation-settings-context';
+import type { ViewRef } from '../../helpers/types/primitives';
+import { createContext } from '../../helpers/utils';
+import { useSurfaceRootAnimation } from './surface.animation';
+import { DISPLAY_NAME } from './surface.constants';
+import surfaceStyles, { styleSheet } from './surface.styles';
+import type { SurfaceContextValue, SurfaceRootProps } from './surface.types';
+
+const [SurfaceProvider, useSurface] = createContext<SurfaceContextValue>({
+  name: 'SurfaceContext',
+  strict: false,
+});
+
+const Surface = forwardRef<ViewRef, SurfaceRootProps>(
+  (
+    { children, variant = 'default', className, style, animation, ...props },
+    ref
+  ) => {
+    const tvStyles = surfaceStyles({ variant, className });
+
+    const { isAllAnimationsDisabled } = useSurfaceRootAnimation({
+      animation,
+    });
+
+    const animationSettingsContextValue = useMemo(
+      () => ({
+        isAllAnimationsDisabled,
+      }),
+      [isAllAnimationsDisabled]
+    );
+
+    const contextValue = useMemo(() => ({ variant }), [variant]);
+
+    return (
+      <AnimationSettingsProvider value={animationSettingsContextValue}>
+        <SurfaceProvider value={contextValue}>
+          <View
+            ref={ref}
+            className={tvStyles}
+            style={[styleSheet.root, style]}
+            {...props}
+          >
+            {children}
+          </View>
+        </SurfaceProvider>
+      </AnimationSettingsProvider>
+    );
+  }
+);
+
+Surface.displayName = DISPLAY_NAME.ROOT;
+
+/**
+ * Surface component
+ *
+ * @component Surface - Container component that provides elevation and background styling.
+ * Used as a base for other components like Card. Supports different visual variants
+ * for various elevation levels and styling needs.
+ *
+ * @see Full documentation: https://heroui.com/components/surface
+ */
+export default Surface;
+
+export { useSurface };

package/src/components/surface/surface.types.ts

@@ -0,0 +1,47 @@
+import type { ViewProps } from 'react-native';
+import type { AnimationRootDisableAll } from '../../helpers/types/animation';
+
+/**
+ * Variant options for the Surface component
+ */
+export type SurfaceVariant =
+  | 'default'
+  | 'secondary'
+  | 'tertiary'
+  | 'quaternary'
+  | 'transparent';
+
+/**
+ * Props for the Surface.Root component
+ */
+export interface SurfaceRootProps extends ViewProps {
+  /**
+   * Children elements to be rendered inside the surface
+   */
+  children?: React.ReactNode;
+  /**
+   * Visual variant of the surface
+   * @default 'default'
+   */
+  variant?: SurfaceVariant;
+  /**
+   * Additional CSS classes
+   */
+  className?: string;
+  /**
+   * Animation configuration for surface
+   * - `"disable-all"`: Disable all animations including children
+   * - `undefined`: Use default animations
+   */
+  animation?: AnimationRootDisableAll;
+}
+
+/**
+ * Context value for the Surface component
+ */
+export interface SurfaceContextValue {
+  /**
+   * Visual variant of the surface
+   */
+  variant: SurfaceVariant;
+}

package/src/components/switch/index.ts

@@ -0,0 +1,2 @@
+export { default as Switch, useSwitch } from './switch';
+export * from './switch.types';