react-native-divkit 0.1.0-alpha.1

package/src/components/README.md

@@ -0,0 +1,230 @@
+# DivKit React Native Components - Phase 5 Complete
+
+## MVP Components Implemented
+
+### 1. DivText (`text/DivText.tsx`)
+Text rendering component with variable substitution and styling.
+
+**Features:**
+- ✅ Text rendering with variable substitution
+- ✅ Font styling (size, weight, color, family)
+- ✅ Text alignment (horizontal, RTL support)
+- ✅ Max lines with ellipsize
+- ✅ Line height, letter spacing
+- ✅ Text decorations (underline, strikethrough)
+- ✅ Font feature settings (basic)
+
+**Deferred:**
+- Text ranges (nested styling)
+- Text images
+- Text gradients
+- Text shadows
+- Auto ellipsize
+- Selectable text with custom actions
+
+### 2. DivContainer (`container/DivContainer.tsx`)
+Flex container component for layout management.
+
+**Features:**
+- ✅ Vertical/horizontal/overlap orientation
+- ✅ Content alignment (horizontal & vertical)
+- ✅ Item spacing (gap)
+- ✅ Flex layout with proper alignment
+- ✅ RTL support
+
+**Deferred:**
+- Wrap layout mode
+- Separators (visual dividers)
+- Line separators (for wrap mode)
+- Aspect ratio constraints
+- Item builder (dynamic items from data)
+- Clip to bounds
+
+### 3. DivImage (`image/DivImage.tsx`)
+Image component with network loading and scaling.
+
+**Features:**
+- ✅ Network image loading
+- ✅ Scaling modes (fill, fit, stretch, no_scale)
+- ✅ Placeholder color while loading
+- ✅ Loading indicator
+- ✅ Error handling
+- ✅ Aspect ratio
+
+**Deferred:**
+- GIF support (requires react-native-gif)
+- Image preview (blur-up technique)
+- Tint color and tint modes
+- Image filters (blur, etc.)
+- Appearance animations
+- High priority preview
+- react-native-fast-image integration
+
+### 4. DivState (`state/DivState.tsx`)
+State management component for switching between different UI states.
+
+**Features:**
+- ✅ State selection by state_id
+- ✅ Default state
+- ✅ State switching via actions (set_state)
+- ✅ State registration in StateContext
+- ✅ State variable binding (state_id_variable)
+- ✅ Two-way binding with variables
+
+**Deferred:**
+- Transition animations (in/out/change)
+- Animation timing and interpolation
+- Clip to bounds
+- Advanced state management
+- Multiple concurrent state transitions
+
+### 5. DivComponent (`DivComponent.tsx`)
+Universal component router that dispatches to appropriate component based on type.
+
+**Supported Types:**
+- `text` → DivText
+- `container` → DivContainer
+- `image` / `gif` → DivImage
+- `state` → DivState
+
+**Deferred Types:**
+- `gallery`, `pager`, `tabs`
+- `slider`, `indicator`
+- `input`, `select`, `switch`
+- `video`, `custom`
+- `separator`, `grid`
+
+## Utility Components
+
+### Outer (`utilities/Outer.tsx`)
+Base wrapper component providing common functionality for all components.
+
+**Features:**
+- Visibility handling (visible/invisible/gone)
+- Sizing (width/height with fixed/match_parent/wrap_content)
+- Padding and margins
+- Background (solid colors)
+- Borders and border radius
+- Shadows
+- Opacity/alpha
+- Action handling (onPress)
+
+### Unknown (`utilities/Unknown.tsx`)
+Fallback component for unsupported types.
+
+## Architecture
+
+```
+DivComponent (router)
+    ├── DivText
+    │   └── Outer
+    ├── DivContainer
+    │   ├── Outer
+    │   └── DivComponent (recursive for children)
+    ├── DivImage
+    │   └── Outer
+    └── DivState
+        ├── Outer
+        └── DivComponent (recursive for active state)
+```
+
+## Integration with Context System
+
+All components integrate with:
+- **DivKitContext**: Access to variables, actions, configuration
+- **StateContext**: State management and transitions
+- **ActionContext**: Action execution
+- **EnabledContext**: Visibility and enabled state
+
+## Integration with Hooks
+
+All components use reactive hooks:
+- `useDerivedFromVarsSimple`: Variable substitution
+- `useAction`, `useActionHandler`: Action execution
+- `useDivKitContext`, `useStateContext`: Context access
+
+## Usage Example
+
+```tsx
+import { DivComponent } from 'react-native-divkit';
+
+const json = {
+  type: 'container',
+  orientation: 'vertical',
+  items: [
+    {
+      type: 'text',
+      text: 'Hello @{userName}!',
+      font_size: 24
+    },
+    {
+      type: 'image',
+      image_url: 'https://example.com/image.png',
+      scale: 'fit'
+    }
+  ]
+};
+
+const componentContext = {
+  json,
+  variables: variablesMap,
+  // ... other context props
+};
+
+<DivComponent componentContext={componentContext} />
+```
+
+## Next Steps (Phase 6)
+
+1. Create main DivKit component
+2. Implement component context creation
+3. Setup variable initialization
+4. Implement template resolution
+5. Create DivKitView wrapper
+6. Build public API exports
+
+## File Structure
+
+```
+src/components/
+├── DivComponent.tsx          # Universal router
+├── text/
+│   ├── DivText.tsx          # Text component
+│   └── index.ts
+├── container/
+│   ├── DivContainer.tsx     # Container component
+│   └── index.ts
+├── image/
+│   ├── DivImage.tsx         # Image component
+│   └── index.ts
+├── state/
+│   ├── DivState.tsx         # State component
+│   └── index.ts
+├── utilities/
+│   ├── Outer.tsx            # Base wrapper
+│   ├── Unknown.tsx          # Fallback
+│   └── index.ts
+└── index.ts                  # Public exports
+```
+
+## Testing TODO
+
+- [ ] Unit tests for each component
+- [ ] Integration tests with variables
+- [ ] State transition tests
+- [ ] Layout tests (snapshot testing)
+- [ ] Action execution tests
+- [ ] Error handling tests
+
+## Known Limitations (MVP)
+
+1. **Text ranges**: Nested text styling not supported
+2. **Wrap layout**: Container wrap mode not implemented
+3. **Separators**: Visual dividers between items not implemented
+4. **GIF animations**: Requires additional native modules
+5. **Image tinting**: Tint modes not implemented
+6. **Transitions**: State transitions are instant (no animations)
+7. **Templates**: Not yet integrated (Phase 6)
+8. **Item builder**: Dynamic items from data not supported
+
+These limitations will be addressed in post-MVP versions.

package/src/components/container/DivContainer.tsx

@@ -0,0 +1,222 @@
+import React, { useMemo } from 'react';
+import { View, ViewStyle } from 'react-native';
+import type { ComponentContext } from '../../types/componentContext';
+import type { DivContainerData, ContainerOrientation } from '../../types/container';
+import type { ContentAlignmentHorizontal, ContentAlignmentVertical } from '../../types/alignment';
+import { Outer } from '../utilities/Outer';
+import { DivComponent } from '../DivComponent';
+import { useDerivedFromVarsSimple } from '../../hooks/useDerivedFromVars';
+import { useDivKitContext } from '../../context/DivKitContext';
+
+export interface DivContainerProps {
+    componentContext: ComponentContext<DivContainerData>;
+}
+
+/**
+ * DivContainer component - renders a flex container with child items
+ * MVP implementation with basic features:
+ * - Vertical/horizontal/overlap orientation
+ * - Content alignment (horizontal & vertical)
+ * - Item spacing (gap)
+ * - Flex layout with proper alignment
+ *
+ * Deferred for post-MVP:
+ * - Wrap layout mode
+ * - Separators (show_at_start, show_between, show_at_end)
+ * - Line separators (for wrap mode)
+ * - Aspect ratio constraints
+ * - Item builder (dynamic items from data)
+ * - Clip to bounds
+ *
+ * Based on Web Container.svelte
+ */
+export function DivContainer({ componentContext }: DivContainerProps) {
+    const { direction } = useDivKitContext();
+    const { json, variables } = componentContext;
+
+    // Reactive properties
+    const orientation = useDerivedFromVarsSimple<ContainerOrientation>(
+        json.orientation || 'vertical',
+        variables || new Map()
+    );
+
+    const contentAlignmentHorizontal = useDerivedFromVarsSimple<ContentAlignmentHorizontal>(
+        json.content_alignment_horizontal || 'start',
+        variables || new Map()
+    );
+
+    const contentAlignmentVertical = useDerivedFromVarsSimple<ContentAlignmentVertical>(
+        json.content_alignment_vertical || 'top',
+        variables || new Map()
+    );
+
+    const itemSpacing = useDerivedFromVarsSimple<number>(
+        json.item_spacing || 0,
+        variables || new Map()
+    );
+
+    // Build container style
+    const containerStyle = useMemo((): ViewStyle => {
+        const style: ViewStyle = {
+            display: 'flex'
+        };
+
+        // Orientation -> flexDirection
+        if (orientation === 'horizontal') {
+            style.flexDirection = 'row';
+        } else if (orientation === 'vertical') {
+            style.flexDirection = 'column';
+        } else if (orientation === 'overlap') {
+            // Overlap is like CSS position: relative with absolute children
+            // In React Native, this is achieved differently
+            // For MVP, we'll use a simple approach with View
+            style.position = 'relative';
+        }
+
+        // Content alignment horizontal
+        // Maps to justifyContent for row, alignItems for column
+        if (orientation === 'horizontal') {
+            // Horizontal orientation: content_alignment_horizontal -> justifyContent
+            style.justifyContent = mapContentAlignmentToJustify(contentAlignmentHorizontal, direction);
+            // content_alignment_vertical -> alignItems (cross axis)
+            style.alignItems = mapContentAlignmentToAlign(contentAlignmentVertical);
+        } else if (orientation === 'vertical') {
+            // Vertical orientation: content_alignment_vertical -> justifyContent
+            style.justifyContent = mapContentAlignmentToJustify(contentAlignmentVertical, direction);
+            // content_alignment_horizontal -> alignItems (cross axis)
+            style.alignItems = mapContentAlignmentToAlign(contentAlignmentHorizontal, direction);
+        }
+
+        // Item spacing (gap between items)
+        // React Native 0.71+ supports gap property
+        if (itemSpacing && itemSpacing > 0 && orientation !== 'overlap') {
+            style.gap = itemSpacing;
+        }
+
+        return style;
+    }, [orientation, contentAlignmentHorizontal, contentAlignmentVertical, itemSpacing, direction]);
+
+    // For overlap mode, we need to position children absolutely
+    const childWrapperStyle = useMemo((): ViewStyle | undefined => {
+        if (orientation === 'overlap') {
+            return {
+                position: 'absolute',
+                top: 0,
+                left: 0,
+                right: 0,
+                bottom: 0
+            };
+        }
+        return undefined;
+    }, [orientation]);
+
+    // Render children
+    // We'll import DivComponent dynamically or assume it's available
+    // For now, we'll use a placeholder and fix this in the integration phase
+    const renderChildren = () => {
+        if (!json.items || json.items.length === 0) {
+            return null;
+        }
+
+        return json.items.map((item, index) => {
+            const childContext = componentContext.produceChildContext(item, {
+                path: index,
+            });
+
+            if (!childContext) {
+                return null;
+            }
+
+            const child = (
+                <DivComponent
+                    key={item.id || `item-${index}`}
+                    componentContext={childContext}
+                />
+            );
+
+            // Wrap in positioned View for overlap mode
+            if (orientation === 'overlap' && childWrapperStyle) {
+                return (
+                    <View key={item.id || `item-${index}`} style={childWrapperStyle}>
+                        {child}
+                    </View>
+                );
+            }
+
+            return child;
+        });
+    };
+
+    return (
+        <Outer componentContext={componentContext}>
+            <View style={containerStyle}>
+                {renderChildren()}
+            </View>
+        </Outer>
+    );
+}
+
+/**
+ * Maps DivKit ContentAlignment to React Native justifyContent
+ * Used for main axis alignment
+ */
+function mapContentAlignmentToJustify(
+    alignment: ContentAlignmentHorizontal | ContentAlignmentVertical | undefined,
+    _direction: 'ltr' | 'rtl' = 'ltr'
+): ViewStyle['justifyContent'] {
+    if (!alignment) return 'flex-start';
+
+    switch (alignment) {
+        case 'start':
+        case 'left':
+        case 'top':
+            return 'flex-start';
+        case 'center':
+            return 'center';
+        case 'end':
+        case 'right':
+        case 'bottom':
+            return 'flex-end';
+        case 'space-between':
+            return 'space-between';
+        case 'space-around':
+            return 'space-around';
+        case 'space-evenly':
+            return 'space-evenly';
+        default:
+            return 'flex-start';
+    }
+}
+
+/**
+ * Maps DivKit ContentAlignment to React Native alignItems
+ * Used for cross axis alignment
+ */
+function mapContentAlignmentToAlign(
+    alignment: ContentAlignmentHorizontal | ContentAlignmentVertical | undefined,
+    _direction: 'ltr' | 'rtl' = 'ltr'
+): ViewStyle['alignItems'] {
+    if (!alignment) return 'flex-start';
+
+    switch (alignment) {
+        case 'start':
+        case 'left':
+        case 'top':
+            return 'flex-start';
+        case 'center':
+            return 'center';
+        case 'end':
+        case 'right':
+        case 'bottom':
+            return 'flex-end';
+        case 'baseline':
+            return 'baseline';
+        // space-* values don't apply to cross axis
+        case 'space-between':
+        case 'space-around':
+        case 'space-evenly':
+            return 'flex-start';
+        default:
+            return 'flex-start';
+    }
+}

package/src/components/container/index.ts

@@ -0,0 +1,2 @@
+export { DivContainer } from './DivContainer';
+export type { DivContainerProps } from './DivContainer';

package/src/components/image/DivImage.tsx

@@ -0,0 +1,172 @@
+import React, { useMemo, useState } from 'react';
+import { Image, View, ViewStyle, ImageStyle, ActivityIndicator } from 'react-native';
+import type { ComponentContext } from '../../types/componentContext';
+import type { DivImageData } from '../../types/image';
+import type { ImageScale } from '../../types/imageScale';
+import { Outer } from '../utilities/Outer';
+import { useDerivedFromVarsSimple } from '../../hooks/useDerivedFromVars';
+import { wrapError } from '../../utils/wrapError';
+
+export interface DivImageProps {
+    componentContext: ComponentContext<DivImageData>;
+}
+
+/**
+ * DivImage component - renders images from network URLs
+ * MVP implementation with basic features:
+ * - Network image loading
+ * - Scaling modes (fill, fit, stretch, no_scale)
+ * - Placeholder color while loading
+ * - Content alignment (horizontal & vertical)
+ * - Aspect ratio
+ *
+ * Deferred for post-MVP:
+ * - GIF support (requires native module or library)
+ * - Image preview (blur-up technique)
+ * - Tint color and tint modes
+ * - Image filters (blur, etc.)
+ * - Appearance animations
+ * - High priority preview
+ * - Preload required flag
+ * - react-native-fast-image integration
+ *
+ * Based on Web Image.svelte
+ */
+export function DivImage({ componentContext }: DivImageProps) {
+    const { json, variables } = componentContext;
+    const [loading, setLoading] = useState(true);
+    const [error, setError] = useState(false);
+
+    // Reactive properties
+    const imageUrl = useDerivedFromVarsSimple<string | undefined>(
+        json.image_url || json.gif_url,
+        variables || new Map()
+    );
+
+    const scale = useDerivedFromVarsSimple<ImageScale>(
+        json.scale || 'fill',
+        variables || new Map()
+    );
+
+    const placeholderColor = useDerivedFromVarsSimple<string | undefined>(
+        json.placeholder_color,
+        variables || new Map()
+    );
+
+    // Map DivKit scale to React Native resizeMode
+    const resizeMode = useMemo((): ImageStyle['resizeMode'] => {
+        switch (scale) {
+            case 'fill':
+                return 'cover'; // Fills the area, may crop
+            case 'fit':
+                return 'contain'; // Fits within area, no crop
+            case 'stretch':
+                return 'stretch'; // Stretches to fill, may distort
+            case 'no_scale':
+                return 'center'; // Original size, centered
+            default:
+                return 'cover';
+        }
+    }, [scale]);
+
+    // Container style (for placeholder and loading)
+    const containerStyle = useMemo((): ViewStyle => {
+        const style: ViewStyle = {
+            overflow: 'hidden'
+        };
+
+        // Placeholder background
+        if (placeholderColor && loading) {
+            style.backgroundColor = placeholderColor;
+        }
+
+        // Aspect ratio
+        if (json.aspect?.ratio) {
+            style.aspectRatio = json.aspect.ratio;
+        }
+
+        return style;
+    }, [placeholderColor, loading, json.aspect]);
+
+    // Image style
+    const imageStyle = useMemo((): ImageStyle => {
+        const style: ImageStyle = {
+            width: '100%',
+            height: '100%'
+        };
+
+        // Aspect ratio
+        if (json.aspect?.ratio) {
+            style.aspectRatio = json.aspect.ratio;
+        }
+
+        return style;
+    }, [json.aspect]);
+
+    // Handle image load events
+    const handleLoadStart = () => {
+        setLoading(true);
+        setError(false);
+    };
+
+    const handleLoadEnd = () => {
+        setLoading(false);
+    };
+
+    const handleError = () => {
+        setLoading(false);
+        setError(true);
+        componentContext.logError(wrapError(new Error(`Failed to load image: ${imageUrl}`)));
+    };
+
+    // Render error state
+    if (error) {
+        return (
+            <Outer componentContext={componentContext}>
+                <View style={[containerStyle, { backgroundColor: placeholderColor || '#EEEEEE' }]}>
+                    {/* Error placeholder - could be customized */}
+                </View>
+            </Outer>
+        );
+    }
+
+    // Render loading state
+    if (!imageUrl) {
+        return (
+            <Outer componentContext={componentContext}>
+                <View style={[containerStyle, { backgroundColor: placeholderColor || '#EEEEEE' }]} />
+            </Outer>
+        );
+    }
+
+    return (
+        <Outer componentContext={componentContext}>
+            <View style={containerStyle}>
+                <Image
+                    source={{ uri: imageUrl }}
+                    style={imageStyle}
+                    resizeMode={resizeMode}
+                    onLoadStart={handleLoadStart}
+                    onLoadEnd={handleLoadEnd}
+                    onError={handleError}
+                />
+                {loading && (
+                    <View
+                        style={{
+                            position: 'absolute',
+                            top: 0,
+                            left: 0,
+                            right: 0,
+                            bottom: 0,
+                            justifyContent: 'center',
+                            alignItems: 'center',
+                            backgroundColor: placeholderColor || 'transparent'
+                        }}
+                    >
+                        <ActivityIndicator size="small" color="#999999" />
+                    </View>
+                )}
+            </View>
+        </Outer>
+    );
+}

package/src/components/image/index.ts

@@ -0,0 +1,2 @@
+export { DivImage } from './DivImage';
+export type { DivImageProps } from './DivImage';

package/src/components/index.ts

@@ -0,0 +1,20 @@
+// Component router
+export { DivComponent } from './DivComponent';
+export type { DivComponentProps } from './DivComponent';
+
+// Individual components
+export { DivText } from './text';
+export { DivContainer } from './container';
+export { DivImage } from './image';
+export { DivState } from './state';
+
+// Utilities
+export { Outer } from './utilities/Outer';
+export { Unknown } from './utilities/Unknown';
+
+// Types
+export type { DivTextProps } from './text';
+export type { DivContainerProps } from './container';
+export type { DivImageProps } from './image';
+export type { DivStateProps } from './state';
+export type { OuterProps } from './utilities/Outer';