react-native-divkit 0.1.0-alpha.1

package/src/components/utilities/README.md

@@ -0,0 +1,175 @@
+# Utility Components
+
+Base utility components for DivKit React Native library.
+
+## Components
+
+### Outer
+
+Base wrapper component for all DivKit components. Handles common properties like visibility, sizing, padding, margins, background, borders, and actions.
+
+**Features:**
+- ✅ Visibility handling (`gone`, `invisible`, `visible`)
+- ✅ Width/Height sizing (`fixed`, `match_parent`, `wrap_content`)
+- ✅ Padding and margins (with RTL support)
+- ✅ Opacity/alpha
+- ✅ Background (solid colors for MVP)
+- ✅ Borders (width, color, style, radius)
+- ✅ Shadows
+- ✅ Actions (tap handlers)
+- ✅ Reactive variable binding
+
+**Usage:**
+
+```tsx
+import { Outer } from './components/utilities';
+
+function MyComponent({ componentContext }) {
+  return (
+    <Outer componentContext={componentContext}>
+      <Text>Content goes here</Text>
+    </Outer>
+  );
+}
+```
+
+**Props:**
+
+- `componentContext: ComponentContext` - Component context with JSON and variables
+- `children: ReactNode` - Child components to render
+- `style?: ViewStyle` - Additional custom styles
+
+**Visibility Behavior:**
+
+- `gone` - Component returns `null` (removed from layout)
+- `invisible` - Component rendered with `opacity: 0` (takes space but not visible)
+- `visible` - Component rendered normally
+
+**Sizing:**
+
+- `fixed` - Explicit size in dp
+- `match_parent` - Fills parent container (100% width/height)
+- `wrap_content` - Wraps content size (default React Native behavior)
+
+**Actions:**
+
+If the component has `actions` defined in JSON, Outer automatically wraps children in `Pressable` for tap handling.
+
+**RTL Support:**
+
+Padding and margins respect `direction` from DivKitContext:
+- `start`/`end` → automatically mapped to `left`/`right` based on direction
+- Supports both LTR and RTL layouts
+
+---
+
+### Unknown
+
+Fallback component for unsupported component types. Renders a placeholder in DEV mode and nothing in production.
+
+**Usage:**
+
+```tsx
+import { Unknown } from './components/utilities';
+
+function ComponentResolver({ type }) {
+  switch (type) {
+    case 'text':
+      return <DivText />;
+    case 'container':
+      return <DivContainer />;
+    default:
+      return <Unknown type={type} message="Not implemented yet" />;
+  }
+}
+```
+
+**Props:**
+
+- `type: string` - Component type that is unknown
+- `message?: string` - Optional error message
+
+**Behavior:**
+
+- **DEV mode**: Renders yellow warning box with component type
+- **Production**: Returns `null` (renders nothing)
+- Logs warning to console in DEV mode
+
+---
+
+## Implementation Notes
+
+### MVP Scope
+
+The current implementation is MVP-focused and includes only essential features:
+
+**Included:**
+- Basic sizing and layout
+- Solid color backgrounds
+- Simple borders and shadows
+- Basic action handling
+
+**Deferred (Post-MVP):**
+- Complex backgrounds (images, gradients)
+- Advanced animations and transitions
+- Extensions
+- Custom focus handling
+- Transform/transformations
+- Visibility actions
+- Layout provider
+
+### Performance
+
+- Uses `useMemo` for style computation to minimize re-renders
+- Reactive variables are tracked via `useDerivedFromVarsSimple`
+- Conditional rendering based on visibility for optimal performance
+
+### Future Enhancements
+
+1. **Advanced Backgrounds** - Add support for images, gradients, nine-patch
+2. **Animations** - Implement action animations and transitions
+3. **Focus** - Add keyboard focus and custom focus styles
+4. **Accessibility** - Enhanced accessibility support
+5. **Extensions** - Plugin system for custom behaviors
+6. **Layout Provider** - Width/height variable tracking
+
+---
+
+## Related Files
+
+- [Outer.tsx](./Outer.tsx) - Main wrapper component
+- [Unknown.tsx](./Unknown.tsx) - Fallback component
+- [Web Outer.svelte](../../../web/divkit/src/components/utilities/Outer.svelte) - Reference implementation
+
+---
+
+## Testing
+
+Test Outer component behavior:
+
+```tsx
+import { render } from '@testing-library/react-native';
+import { Outer } from './Outer';
+
+it('renders children when visible', () => {
+  const { getByText } = render(
+    <Outer componentContext={mockContext}>
+      <Text>Test</Text>
+    </Outer>
+  );
+  expect(getByText('Test')).toBeTruthy();
+});
+
+it('returns null when visibility is gone', () => {
+  const context = {
+    ...mockContext,
+    json: { ...mockContext.json, visibility: 'gone' }
+  };
+  const { queryByText } = render(
+    <Outer componentContext={context}>
+      <Text>Test</Text>
+    </Outer>
+  );
+  expect(queryByText('Test')).toBeNull();
+});
+```

package/src/components/utilities/Unknown.tsx

@@ -0,0 +1,60 @@
+import React from 'react';
+import { View, Text, StyleSheet } from 'react-native';
+
+export interface UnknownProps {
+    type: string;
+    message?: string;
+}
+
+/**
+ * Unknown component - fallback for unsupported component types
+ * Renders a placeholder with error message
+ */
+export function Unknown({ type, message }: UnknownProps) {
+    if (__DEV__) {
+        console.warn(`[DivKit] Unknown component type: "${type}"${message ? ` - ${message}` : ''}`);
+    }
+
+    // Only show visual error in DEV mode
+    if (__DEV__) {
+        return (
+            <View style={styles.container}>
+                <Text style={styles.title}>Unknown Component</Text>
+                <Text style={styles.type}>Type: {type}</Text>
+                {message && <Text style={styles.message}>{message}</Text>}
+            </View>
+        );
+    }
+
+    // In production, render nothing
+    return null;
+}
+
+const styles = StyleSheet.create({
+    container: {
+        padding: 16,
+        margin: 8,
+        backgroundColor: '#fff3cd',
+        borderWidth: 1,
+        borderColor: '#ffc107',
+        borderRadius: 4,
+        borderStyle: 'dashed'
+    },
+    title: {
+        fontSize: 14,
+        fontWeight: 'bold',
+        color: '#856404',
+        marginBottom: 4
+    },
+    type: {
+        fontSize: 12,
+        color: '#856404',
+        fontFamily: 'monospace'
+    },
+    message: {
+        fontSize: 11,
+        color: '#856404',
+        marginTop: 4,
+        fontStyle: 'italic'
+    }
+});

package/src/components/utilities/index.ts

@@ -0,0 +1,4 @@
+export { Outer } from './Outer';
+export type { OuterProps } from './Outer';
+export { Unknown } from './Unknown';
+export type { UnknownProps } from './Unknown';

package/src/context/ActionContext.tsx

@@ -0,0 +1,37 @@
+import { createContext, useContext } from 'react';
+
+/**
+ * Action context interface
+ * Based on ActionCtxValue from Web implementation
+ *
+ * This context is used to track whether a component or its parent has actions.
+ * It's useful for optimizing rendering and event handling.
+ */
+export interface ActionContextValue {
+    /**
+     * Check if the current component or any parent has actions
+     * @returns true if actions are present
+     */
+    hasAction(): boolean;
+}
+
+export const ActionContext = createContext<ActionContextValue | null>(null);
+
+/**
+ * Hook to access ActionContext
+ * Throws an error if used outside of ActionContext.Provider
+ */
+export function useActionContext(): ActionContextValue {
+    const context = useContext(ActionContext);
+    if (!context) {
+        throw new Error('useActionContext must be used within ActionContext.Provider');
+    }
+    return context;
+}
+
+/**
+ * Hook to safely access ActionContext (returns null if not available)
+ */
+export function useActionContextOptional(): ActionContextValue | null {
+    return useContext(ActionContext);
+}

package/src/context/DivKitContext.tsx

@@ -0,0 +1,54 @@
+import { createContext, useContext } from 'react';
+import type { Action, Direction } from '../../typings/common';
+import type { MaybeMissing } from '../expressions/json';
+import type { Variable } from '../expressions/variable';
+import type { ComponentContext } from '../types/componentContext';
+
+/**
+ * Main DivKit context interface
+ * Based on RootCtxValue from Web implementation with simplifications for MVP
+ */
+export interface DivKitContextValue {
+    // Logging & callbacks
+    logStat(type: string, action: MaybeMissing<Action>): void;
+    execCustomAction(action: Action & { url: string }): void;
+
+    // Configuration
+    direction: Direction;
+    platform: 'desktop' | 'touch';
+
+    // Variable system
+    variables: Map<string, Variable>;
+    getVariable(name: string): Variable | undefined;
+    setVariable(name: string, value: unknown): void;
+
+    // Component registration (simplified for MVP)
+    registerComponent(id: string, context: ComponentContext): void;
+    unregisterComponent(id: string): void;
+
+    // Action execution
+    execAnyActions(
+        actions: MaybeMissing<Action[]> | undefined,
+        opts?: {
+            componentContext?: ComponentContext;
+            processUrls?: boolean;
+        }
+    ): Promise<void>;
+
+    // ID generation (for unique component IDs)
+    genId(key: string): string;
+}
+
+export const DivKitContext = createContext<DivKitContextValue | null>(null);
+
+/**
+ * Hook to access DivKitContext
+ * Throws an error if used outside of DivKitContext.Provider
+ */
+export function useDivKitContext(): DivKitContextValue {
+    const context = useContext(DivKitContext);
+    if (!context) {
+        throw new Error('useDivKitContext must be used within DivKitContext.Provider');
+    }
+    return context;
+}

package/src/context/EnabledContext.tsx

@@ -0,0 +1,50 @@
+import { createContext, useContext } from 'react';
+import type { Observable } from '../stores/createObservable';
+
+/**
+ * Enabled context interface
+ * Based on EnabledCtxValue from Web implementation
+ *
+ * This context tracks whether the current component is enabled.
+ * Used for cascading enabled/disabled state down the component tree.
+ */
+export interface EnabledContextValue {
+    /**
+     * Observable that tracks whether the component is enabled
+     * Subscribers will be notified when the enabled state changes
+     */
+    isEnabled: Observable<boolean>;
+}
+
+export const EnabledContext = createContext<EnabledContextValue | null>(null);
+
+/**
+ * Hook to access EnabledContext
+ * Throws an error if used outside of EnabledContext.Provider
+ */
+export function useEnabledContext(): EnabledContextValue {
+    const context = useContext(EnabledContext);
+    if (!context) {
+        throw new Error('useEnabledContext must be used within EnabledContext.Provider');
+    }
+    return context;
+}
+
+/**
+ * Hook to safely access EnabledContext (returns null if not available)
+ */
+export function useEnabledContextOptional(): EnabledContextValue | null {
+    return useContext(EnabledContext);
+}
+
+/**
+ * Hook to get the current enabled state value
+ * Returns true if no EnabledContext is available (enabled by default)
+ */
+export function useIsEnabled(): boolean {
+    const context = useEnabledContextOptional();
+    if (!context) {
+        return true; // Enabled by default if no context
+    }
+    return context.isEnabled.get();
+}

package/src/context/StateContext.tsx

@@ -0,0 +1,75 @@
+import { createContext, useContext } from 'react';
+
+/**
+ * State setter function type
+ * Takes a state ID and returns a promise that resolves when the state is changed
+ */
+export type StateSetter = (stateId: string) => Promise<void>;
+
+/**
+ * State context interface
+ * Based on StateCtxValue from Web implementation, simplified for MVP
+ *
+ * This context manages state transitions for div-state components.
+ * In the MVP version, complex transitions are deferred.
+ */
+export interface StateContextValue {
+    /**
+     * Register a state component
+     * @param id - Component ID
+     * @param setState - Function to change the state
+     * @returns Unregister function
+     */
+    registerState(id: string, setState: StateSetter): () => void;
+
+    /**
+     * Switch to a specific state by ID
+     * @param stateId - The state ID to switch to
+     */
+    switchState(stateId: string): Promise<void>;
+
+    /**
+     * Get state setter by component ID
+     * @param id - Component ID
+     * @returns State setter function or undefined
+     */
+    getStateSetter(id: string): StateSetter | undefined;
+
+    /**
+     * Register a child component (for tracking purposes)
+     * Simplified for MVP - full transition support deferred
+     */
+    registerChild(id: string): void;
+
+    /**
+     * Unregister a child component
+     */
+    unregisterChild(id: string): void;
+
+    /**
+     * Check if there's a transition change for a component
+     * MVP: Always returns false (transitions deferred)
+     */
+    hasTransitionChange(id?: string): boolean;
+}
+
+export const StateContext = createContext<StateContextValue | null>(null);
+
+/**
+ * Hook to access StateContext
+ * Throws an error if used outside of StateContext.Provider
+ */
+export function useStateContext(): StateContextValue {
+    const context = useContext(StateContext);
+    if (!context) {
+        throw new Error('useStateContext must be used within StateContext.Provider');
+    }
+    return context;
+}
+
+/**
+ * Hook to safely access StateContext (returns null if not available)
+ */
+export function useStateContextOptional(): StateContextValue | null {
+    return useContext(StateContext);
+}

package/src/context/index.ts

@@ -0,0 +1,33 @@
+/**
+ * Context exports for React Native DivKit
+ * Phase 2: Context System
+ */
+
+export {
+    DivKitContext,
+    useDivKitContext,
+    type DivKitContextValue
+} from './DivKitContext';
+
+export {
+    ActionContext,
+    useActionContext,
+    useActionContextOptional,
+    type ActionContextValue
+} from './ActionContext';
+
+export {
+    StateContext,
+    useStateContext,
+    useStateContextOptional,
+    type StateContextValue,
+    type StateSetter
+} from './StateContext';
+
+export {
+    EnabledContext,
+    useEnabledContext,
+    useEnabledContextOptional,
+    useIsEnabled,
+    type EnabledContextValue
+} from './EnabledContext';

package/src/expressions/ast.d.ts

@@ -0,0 +1,101 @@
+export type Node = BinaryExpression | LogicalExpression |
+    UnaryExpression |
+    StringLiteral | NumberLiteral | IntegerLiteral | BooleanLiteral |
+    TemplateLiteral |
+    ConditionalExpression | TryExpression |
+    CallExpression | MethodExpression |
+    Variable;
+
+export type UnaryOperator = '!' | '+' | '-';
+
+export type EqualityOperator = '==' | '!=';
+
+export type CompareOperator = '>' | '>=' | '<' | '<=';
+
+export type SumOperator = '+' | '-';
+
+export type FactorOperator = '/' | '*' | '%';
+
+export type LogicalOperator = '&&' | '||';
+
+export interface BinaryExpression {
+    type: 'BinaryExpression',
+    operator: EqualityOperator | CompareOperator | SumOperator | FactorOperator;
+    left: Node;
+    right: Node;
+}
+
+export interface LogicalExpression {
+    type: 'LogicalExpression',
+    operator: LogicalOperator;
+    left: Node;
+    right: Node;
+}
+
+export interface StringLiteral {
+    type: 'StringLiteral';
+    value: string;
+}
+
+export interface TemplateLiteral {
+    type: 'TemplateLiteral';
+    quasis: StringLiteral[];
+    expressions: Node[];
+}
+
+export interface NumberLiteral {
+    type: 'NumberLiteral';
+    value: number;
+}
+
+export interface IntegerLiteral {
+    type: 'IntegerLiteral';
+    value: bigint;
+}
+
+export interface BooleanLiteral {
+    type: 'BooleanLiteral';
+    value: boolean;
+}
+
+export interface ConditionalExpression {
+    type: 'ConditionalExpression';
+    test: Node;
+    consequent: Node;
+    alternate: Node;
+}
+
+export interface TryExpression {
+    type: 'TryExpression';
+    test: Node;
+    alternate: Node;
+}
+
+export interface Identifier {
+    type: 'Identifier';
+    name: string;
+}
+
+export interface Variable {
+    type: 'Variable';
+    id: Identifier;
+}
+
+export interface UnaryExpression {
+    type: 'UnaryExpression';
+    operator: UnaryOperator;
+    argument: Node;
+}
+
+export interface CallExpression {
+    type: 'CallExpression';
+    callee: Identifier;
+    arguments: Node[];
+}
+
+export interface MethodExpression {
+    type: 'MethodExpression';
+    object: Node;
+    method: Identifier;
+    arguments: Node[];
+}

package/src/expressions/bigint.ts

@@ -0,0 +1,38 @@
+export function toBigIntNoCheck(val: number | bigint | string): bigint {
+    return BigInt(val);
+}
+
+export const MAX_INT = toBigIntNoCheck('9223372036854775807');
+export const MIN_INT = toBigIntNoCheck('-9223372036854775808');
+
+export function toBigInt(val: number | bigint | string): bigint {
+    const res = toBigIntNoCheck(val);
+    if (res > MAX_INT || res < MIN_INT) {
+        throw new Error('Integer overflow.');
+    }
+    return res;
+}
+
+export const bigIntZero = toBigInt(0);
+
+export function absBigInt(val: bigint): bigint {
+    let res = val;
+
+    if (res < 0) {
+        res = -res;
+    }
+
+    return res;
+}
+
+export function signBigInt(val: bigint): bigint {
+    let res = 0;
+
+    if (val > 0) {
+        res = 1;
+    } else if (val < 0) {
+        res = -1;
+    }
+
+    return toBigInt(res);
+}

package/src/expressions/const.ts

@@ -0,0 +1,16 @@
+export const MAX_INT32 = 2147483647;
+export const MIN_INT32 = -2147483648;
+
+export const MAX_NUMBER = Number.MAX_VALUE;
+export const MIN_NUMBER = Number.MIN_VALUE;
+
+export const STRING = 'string';
+export const INTEGER = 'integer';
+export const NUMBER = 'number';
+export const BOOLEAN = 'boolean';
+export const COLOR = 'color';
+export const URL = 'url';
+export const DATETIME = 'datetime';
+export const DICT = 'dict';
+export const ARRAY = 'array';
+export const FUNCTION = 'function';