@dcl/react-ecs 7.7.7-13655406288.commit-7b2a671 → 7.7.7

package/README.md

@@ -1 +1,131 @@
-# React ECS
+# @dcl/react-ecs
+
+React bindings for Decentraland's Entity Component System (ECS), providing a declarative way to build UIs in Decentraland scenes using React's component model and JSX syntax.
+
+## Features
+
+- **Flexbox-based Layout**: Implements a subset of CSS Flexbox for powerful and intuitive UI layouts
+- **React Components**: Familiar React-like component API for building UIs
+- **Type Safety**: Full TypeScript support with proper type definitions
+- **Event Handling**: Support for mouse events and user interactions
+- **Performance**: Optimized reconciliation for minimal runtime overhead
+- **Theme Support**: Built-in light and dark theme system with context-based switching
+
+## Component Guidelines
+
+All components in @dcl/react-ecs must:
+
+- Return JSX.Elements for consistency and composability
+- Support theme integration through context
+- Be reusable and composable with other components
+
+## Installation
+
+```bash
+npm install @dcl/react-ecs
+```
+
+## Basic Usage
+
+```tsx
+import { ReactEcs, UiEntity, Label, Button } from '@dcl/react-ecs'
+
+export function MyUI() {
+  return (
+    <UiEntity
+      uiTransform={{
+        width: 300,
+        height: 100,
+        display: 'flex',
+        justifyContent: 'center',
+        alignItems: 'center'
+      }}
+    >
+      <Label value="Hello Decentraland!" />
+      <Button value="Click Me!" onMouseDown={() => console.log('clicked!')} />
+    </UiEntity>
+  )
+}
+```
+
+## Theme System
+
+The package includes a theme system for consistent UI styling:
+
+```tsx
+import { ReactEcs, ThemeProvider, Button } from '@dcl/react-ecs'
+
+// Wrap your UI with ThemeProvider
+export function MyUI() {
+  return (
+    <ThemeProvider>
+      <Button value="Theme-Aware Button" />
+    </ThemeProvider>
+  )
+}
+
+// Use themes in custom components
+function CustomComponent() {
+  const { theme, toggleTheme } = React.useContext(ThemeContext)
+
+  return (
+    <UiEntity
+      uiBackground={{
+        color: theme === 'light' ? '#FFFFFF' : '#000000'
+      }}
+      onMouseDown={toggleTheme}
+    />
+  )
+}
+```
+
+## Components
+
+### Core Components
+
+- **UiEntity**: Base component for UI elements
+- **Label**: Text display component
+- **Button**: Interactive button component
+- **Input**: Text input field
+- **Dropdown**: Selection dropdown menu
+
+### Layout System
+
+The layout system is based on Flexbox and supports the following properties:
+
+- `display: 'flex'`
+- `flexDirection: 'row' | 'column'`
+- `justifyContent: 'flex-start' | 'center' | 'flex-end' | 'space-between' | 'space-around'`
+- `alignItems: 'flex-start' | 'center' | 'flex-end' | 'stretch'`
+- `width`, `height`
+- `margin`, `padding`
+- `positionType: 'absolute' | 'relative'`
+
+## Event Handling
+
+Components support the following mouse events:
+
+```tsx
+<Button onMouseDown={() => {}} onMouseUp={() => {}} onMouseEnter={() => {}} onMouseLeave={() => {}} />
+```
+
+## Technical Details
+
+The package implements a custom React reconciler that bridges React's component model with Decentraland's ECS. It:
+
+1. Translates JSX into ECS entities and components
+2. Manages component lifecycle and updates
+3. Handles event delegation and bubbling
+4. Provides a performant update mechanism
+
+## Related Documentation
+
+For more details about the UI system architecture and design decisions:
+
+- [ADR-124: Implementing Flexbox-based UI](https://adr.decentraland.org/adr/ADR-124)
+- [ADR-125: User Interface Components](https://adr.decentraland.org/adr/ADR-125)
+- [ADR-237: SDK 7 Custom UI Components](https://adr.decentraland.org/adr/ADR-237)
+
+## License
+
+Apache 2.0

package/dist/reconciler/index.js

@@ -124,6 +124,7 @@ export function createReconciler(engine, pointerEvents) {
     }
     function removeChildEntity(instance) {
         changeEvents.delete(instance.entity);
+        clickEvents.delete(instance.entity);
         engine.removeEntity(instance.entity);
         for (const child of instance._child) {
             removeChildEntity(child);
@@ -170,13 +171,23 @@ export function createReconciler(engine, pointerEvents) {
         removeChildEntity(child);
     }
     function updateOnChange(entity, componentId, state) {
+        const hasEvent = changeEvents.has(entity);
         const event = changeEvents.get(entity) || changeEvents.set(entity, new Map()).get(entity);
-        const oldState = event.get(componentId);
         const onChangeCallback = state?.onChangeCallback;
         const onSubmitCallback = state?.onSubmitCallback;
-        const value = state?.value ?? oldState?.value;
-        const isSubmit = state?.isSubmit ?? oldState?.isSubmit;
-        event.set(componentId, { onChangeCallback, onSubmitCallback, value, isSubmit });
+        event.set(componentId, { onChangeCallback, onSubmitCallback });
+        // Create onChange callback if its the first callback event for this entity
+        if (!hasEvent) {
+            const resultComponentId = componentId === UiDropdown.componentId ? UiDropdownResult.componentId : UiInputResult.componentId;
+            engine.getComponent(resultComponentId).onChange(entity, (value) => {
+                if (value?.isSubmit) {
+                    const onSubmit = changeEvents.get(entity)?.get(componentId)?.onSubmitCallback;
+                    onSubmit && onSubmit(value?.value);
+                }
+                const onChange = changeEvents.get(entity)?.get(componentId)?.onChangeCallback;
+                onChange && onChange(value?.value);
+            });
+        }
     }
     const hostConfig = {
         ...noopConfig,
@@ -251,32 +262,8 @@ export function createReconciler(engine, pointerEvents) {
     const root = reconciler.createContainer({}, 0, null, false, null, '', 
     /* istanbul ignore next */
     function () { }, null);
-    // Maybe this could be something similar to Input system, but since we
-    // are going to use this only here, i prefer to scope it here.
-    function handleOnChange(componentId, resultComponent) {
-        for (const [entity, Result] of engine.getEntitiesWith(resultComponent)) {
-            const entityState = changeEvents.get(entity)?.get(componentId);
-            const isSubmit = !!Result.isSubmit;
-            if (entityState?.onChangeCallback && Result.value !== entityState.value) {
-                entityState.onChangeCallback(Result.value);
-            }
-            if (entityState?.onSubmitCallback && isSubmit && !entityState.isSubmit) {
-                entityState.onSubmitCallback(Result.value);
-            }
-            updateOnChange(entity, componentId, {
-                onChangeCallback: entityState?.onChangeCallback,
-                onSubmitCallback: entityState?.onSubmitCallback,
-                value: Result.value,
-                isSubmit
-            });
-        }
-    }
     return {
         update: function (component) {
-            if (changeEvents.size) {
-                handleOnChange(UiInput.componentId, UiInputResult);
-                handleOnChange(UiDropdown.componentId, UiDropdownResult);
-            }
             return reconciler.updateContainer(component, root, null);
         },
         getEntities: () => Array.from(entities)

package/dist/system.d.ts

@@ -1,3 +1,4 @@
+import type { IEngine, PointerEventsSystem } from '@dcl/ecs';
 import type { ReactEcs } from './react-ecs';
 /**
  * @public
@@ -10,3 +11,7 @@ export interface ReactBasedUiSystem {
     destroy(): void;
     setUiRenderer(ui: UiComponent): void;
 }
+/**
+ * @public
+ */
+export declare function createReactBasedUiSystem(engine: IEngine, pointerSystem: PointerEventsSystem): ReactBasedUiSystem;

package/dist/system.js

@@ -1,6 +1,6 @@
 import { createReconciler } from './reconciler';
 /**
- * @internal
+ * @public
  */
 export function createReactBasedUiSystem(engine, pointerSystem) {
     const renderer = createReconciler(engine, pointerSystem);

package/package.json

@@ -1,11 +1,11 @@
 {
   "name": "@dcl/react-ecs",
   "description": "Decentraland ECS",
-  "version": "7.7.7-13655406288.commit-7b2a671",
+  "version": "7.7.7",
   "author": "DCL",
   "bugs": "https://github.com/decentraland/js-sdk-toolchain/issues",
   "dependencies": {
-    "@dcl/ecs": "7.7.7-13655406288.commit-7b2a671",
+    "@dcl/ecs": "7.7.7",
     "react": "^18.2.0",
     "react-reconciler": "^0.29.0"
   },
@@ -40,5 +40,5 @@
     "tsconfig": "./tsconfig.json"
   },
   "types": "./dist/index.d.ts",
-  "commit": "7b2a6716919850a45b2f84abc9d05a1500ad6af3"
+  "commit": "b532f7c70b2b1cbd4ea7e4a67831cc23a81d2459"
 }