@owdproject/react 0.0.0-stage → 4.0.0-alpha.4

package/LICENSE

@@ -0,0 +1,20 @@
+MIT License
+
+Copyright (c) 2025  Open Web Desktop Team ~ github.com/owdproject
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
+WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR
+IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -1,3 +1,68 @@
-# Temporary Holding Version
+<div align="center">
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+  <h1>@owdproject/react</h1>
+
+  <p>
+    <strong>Official React 18 & 19 Adapter for Open Web Desktop.</strong><br /><br />
+    Concurrent-safe <code>useSyncExternalStore</code> hooks and pointer drag/resize<br />
+    bindings powered by <code>@owdproject/core</code>.
+  </p>
+
+  <br />
+
+  <p>
+    <a href="https://npmjs.com/package/@owdproject/react"><img src="https://img.shields.io/npm/v/@owdproject/react/alpha.svg?style=flat&colorA=020420&colorB=00DC82" alt="npm version" /></a>
+    <a href="https://react.dev"><img src="https://img.shields.io/badge/React-020420?logo=react" alt="React" /></a>
+    <a href="https://github.com/owdproject/core/blob/main/LICENSE"><img src="https://img.shields.io/badge/License-MIT-00DC82.svg?style=flat&colorA=020420&colorB=00DC82" alt="License" /></a>
+  </p>
+
+</div>
+
+---
+
+## Overview
+
+`@owdproject/react` (`4.0.0-alpha.0`) connects [`@owdproject/core`](https://npmjs.com/package/@owdproject/core)'s frozen immutable snapshots (`Object.freeze`) directly to React 18/19 `useSyncExternalStore` with zero state tearing.
+
+---
+
+## Quick Start
+
+```bash
+pnpm add @owdproject/core@4.0.0-alpha.0 @owdproject/react@4.0.0-alpha.0
+```
+
+```tsx
+import { createDesktop, useDesktop, useWindowInstance, useDesktopDrag } from '@owdproject/react'
+
+const desktop = createDesktop()
+
+export function DesktopShell() {
+  const { windows, focusedWindow } = useDesktop(desktop)
+  return (
+    <div>
+      {windows.map((win) => (
+        <div key={win.id}>{win.config.title}</div>
+      ))}
+    </div>
+  )
+}
+```
+
+---
+
+## Exported Hooks
+
+| Hook | Description |
+| :--- | :--- |
+| **`useDesktop(instanceOrOptions?)`** | Subscribes to a `Desktop` instance via `useSyncExternalStore`. |
+| **`useWindowManager(manager?)`** | Subscribes to `WindowManager` window lists and focus state. |
+| **`useWindowInstance(instance)`** | Subscribes to an individual `WindowInstance` actor. |
+| **`useDesktopDrag(options)`** | Returns `{ isDragging, activeSnapZone, startDrag, cancelDrag }`. |
+| **`useDesktopResize(options)`** | Returns `{ isResizing, startResize, cancelResize }`. |
+
+---
+
+## License
+
+[MIT](https://opensource.org/licenses/MIT)

package/dist/index.d.mts

@@ -0,0 +1,74 @@
+import { ApplicationConfig, WindowConfig, Desktop, WindowInstance, ApplicationInstance, WindowBounds, DesktopWorkareaRect, DesktopSnapshot, ResizeDirection, WindowState, WindowManager } from '@owdproject/core';
+export * from '@owdproject/core';
+import { SnapZoneHint } from '@owdproject/core/types';
+import * as react from 'react';
+import { ComponentType } from 'react';
+
+/** Runtime props shared by React application windows, independently of a theme. */
+interface ReactApplicationWindowProps {
+    desktop: Desktop;
+    window: WindowInstance;
+    application: ApplicationInstance;
+    /** Closes through the owning application, including its cancellable hooks. */
+    close: () => Promise<boolean>;
+}
+interface ReactApplicationWindowConfig extends Omit<WindowConfig, 'component'> {
+    component: ComponentType<ReactApplicationWindowProps>;
+}
+interface ReactApplicationConfig extends Omit<ApplicationConfig, 'windows'> {
+    windows?: Record<string, ReactApplicationWindowConfig>;
+}
+/** Registration and launch retain the engine's lifecycle and singleton behavior. */
+declare function registerReactApplication(desktop: Desktop, config: ReactApplicationConfig): ApplicationInstance;
+declare function closeReactApplicationWindow(desktop: Desktop, window: WindowInstance): Promise<boolean>;
+/** Render the component from this window's registered model, without a theme app catalog. */
+declare function ReactApplicationWindow({ desktop, window }: {
+    desktop: Desktop;
+    window: WindowInstance;
+}): react.ReactElement<ReactApplicationWindowProps, string | react.JSXElementConstructor<any>> | null;
+
+/**
+ * @owdproject/react
+ * Official React 18/19 reactive adapter for @owdproject/core using useSyncExternalStore.
+ */
+
+declare function useDesktop(desktop: Desktop): DesktopSnapshot & {
+    desktop: Desktop;
+};
+declare function useWindowManager(manager: WindowManager): {
+    windows: WindowInstance[];
+    focused: WindowInstance | undefined;
+    manager: WindowManager;
+};
+declare function useWindowInstance(instance: WindowInstance): {
+    state: WindowState;
+    instance: WindowInstance;
+};
+interface ReactDesktopDragOptions {
+    getBounds: () => WindowBounds;
+    getWorkarea?: () => DesktopWorkareaRect | undefined;
+    onStart?: () => void;
+    onMove?: (bounds: WindowBounds, snapZone: SnapZoneHint | null) => void;
+    onEnd?: (finalBounds: WindowBounds, snapZone: SnapZoneHint | null) => void;
+    onCancel?: () => void;
+}
+declare function useDesktopDrag(options: ReactDesktopDragOptions): {
+    startDrag: (event: PointerEvent) => () => void;
+};
+interface ReactDesktopResizeOptions {
+    getBounds: () => WindowBounds;
+    minWidth?: number;
+    minHeight?: number;
+    maxWidth?: number;
+    maxHeight?: number;
+    onStart?: () => void;
+    onMove?: (bounds: WindowBounds) => void;
+    onEnd?: (finalBounds: WindowBounds) => void;
+    onCancel?: () => void;
+}
+declare function useDesktopResize(options: ReactDesktopResizeOptions): {
+    startResize: (event: PointerEvent, direction: ResizeDirection) => () => void;
+};
+
+export { ReactApplicationWindow, closeReactApplicationWindow, registerReactApplication, useDesktop, useDesktopDrag, useDesktopResize, useWindowInstance, useWindowManager };
+export type { ReactApplicationConfig, ReactApplicationWindowConfig, ReactApplicationWindowProps, ReactDesktopDragOptions, ReactDesktopResizeOptions };

package/dist/index.d.ts

@@ -0,0 +1,74 @@
+import { ApplicationConfig, WindowConfig, Desktop, WindowInstance, ApplicationInstance, WindowBounds, DesktopWorkareaRect, DesktopSnapshot, ResizeDirection, WindowState, WindowManager } from '@owdproject/core';
+export * from '@owdproject/core';
+import { SnapZoneHint } from '@owdproject/core/types';
+import * as react from 'react';
+import { ComponentType } from 'react';
+
+/** Runtime props shared by React application windows, independently of a theme. */
+interface ReactApplicationWindowProps {
+    desktop: Desktop;
+    window: WindowInstance;
+    application: ApplicationInstance;
+    /** Closes through the owning application, including its cancellable hooks. */
+    close: () => Promise<boolean>;
+}
+interface ReactApplicationWindowConfig extends Omit<WindowConfig, 'component'> {
+    component: ComponentType<ReactApplicationWindowProps>;
+}
+interface ReactApplicationConfig extends Omit<ApplicationConfig, 'windows'> {
+    windows?: Record<string, ReactApplicationWindowConfig>;
+}
+/** Registration and launch retain the engine's lifecycle and singleton behavior. */
+declare function registerReactApplication(desktop: Desktop, config: ReactApplicationConfig): ApplicationInstance;
+declare function closeReactApplicationWindow(desktop: Desktop, window: WindowInstance): Promise<boolean>;
+/** Render the component from this window's registered model, without a theme app catalog. */
+declare function ReactApplicationWindow({ desktop, window }: {
+    desktop: Desktop;
+    window: WindowInstance;
+}): react.ReactElement<ReactApplicationWindowProps, string | react.JSXElementConstructor<any>> | null;
+
+/**
+ * @owdproject/react
+ * Official React 18/19 reactive adapter for @owdproject/core using useSyncExternalStore.
+ */
+
+declare function useDesktop(desktop: Desktop): DesktopSnapshot & {
+    desktop: Desktop;
+};
+declare function useWindowManager(manager: WindowManager): {
+    windows: WindowInstance[];
+    focused: WindowInstance | undefined;
+    manager: WindowManager;
+};
+declare function useWindowInstance(instance: WindowInstance): {
+    state: WindowState;
+    instance: WindowInstance;
+};
+interface ReactDesktopDragOptions {
+    getBounds: () => WindowBounds;
+    getWorkarea?: () => DesktopWorkareaRect | undefined;
+    onStart?: () => void;
+    onMove?: (bounds: WindowBounds, snapZone: SnapZoneHint | null) => void;
+    onEnd?: (finalBounds: WindowBounds, snapZone: SnapZoneHint | null) => void;
+    onCancel?: () => void;
+}
+declare function useDesktopDrag(options: ReactDesktopDragOptions): {
+    startDrag: (event: PointerEvent) => () => void;
+};
+interface ReactDesktopResizeOptions {
+    getBounds: () => WindowBounds;
+    minWidth?: number;
+    minHeight?: number;
+    maxWidth?: number;
+    maxHeight?: number;
+    onStart?: () => void;
+    onMove?: (bounds: WindowBounds) => void;
+    onEnd?: (finalBounds: WindowBounds) => void;
+    onCancel?: () => void;
+}
+declare function useDesktopResize(options: ReactDesktopResizeOptions): {
+    startResize: (event: PointerEvent, direction: ResizeDirection) => () => void;
+};
+
+export { ReactApplicationWindow, closeReactApplicationWindow, registerReactApplication, useDesktop, useDesktopDrag, useDesktopResize, useWindowInstance, useWindowManager };
+export type { ReactApplicationConfig, ReactApplicationWindowConfig, ReactApplicationWindowProps, ReactDesktopDragOptions, ReactDesktopResizeOptions };

package/dist/index.mjs

@@ -0,0 +1,99 @@
+import { createElement, useCallback, useSyncExternalStore } from 'react';
+import { DesktopPointerSession } from '@owdproject/core';
+export * from '@owdproject/core';
+
+function registerReactApplication(desktop, config) {
+  return desktop.applications.register(config);
+}
+async function closeReactApplicationWindow(desktop, window) {
+  const application = window.applicationId ? desktop.applications.get(window.applicationId) : void 0;
+  return application ? application.closeWindow(window.id) : desktop.windows.closeWindow(window.id);
+}
+function ReactApplicationWindow({ desktop, window }) {
+  const application = window.applicationId ? desktop.applications.get(window.applicationId) : void 0;
+  const Component = window.config.component;
+  if (!application || !Component) return null;
+  return createElement(Component, {
+    desktop,
+    window,
+    application,
+    close: () => closeReactApplicationWindow(desktop, window)
+  });
+}
+
+function useDesktop(desktop) {
+  const subscribe = useCallback(
+    (onStoreChange) => desktop.subscribe(onStoreChange),
+    [desktop]
+  );
+  const getSnapshot = useCallback(() => desktop.getSnapshot(), [desktop]);
+  const snapshot = useSyncExternalStore(subscribe, getSnapshot, getSnapshot);
+  return {
+    desktop,
+    ...snapshot
+  };
+}
+function useWindowManager(manager) {
+  const subscribe = useCallback(
+    (onStoreChange) => manager.subscribe(onStoreChange),
+    [manager]
+  );
+  const getSnapshot = useCallback(() => manager.getSnapshot(), [manager]);
+  const windows = useSyncExternalStore(subscribe, getSnapshot, getSnapshot);
+  const focused = windows.find((w) => w.state.focused);
+  return {
+    windows,
+    focused,
+    manager
+  };
+}
+function useWindowInstance(instance) {
+  const subscribe = useCallback(
+    (onStoreChange) => instance.subscribe(onStoreChange),
+    [instance]
+  );
+  const getSnapshot = useCallback(() => instance.getSnapshot(), [instance]);
+  const state = useSyncExternalStore(subscribe, getSnapshot, getSnapshot);
+  return {
+    state,
+    instance
+  };
+}
+function useDesktopDrag(options) {
+  const startDrag = useCallback(
+    (event) => {
+      return DesktopPointerSession.startDrag(event, {
+        initialBounds: options.getBounds(),
+        workarea: options.getWorkarea?.(),
+        onStart: options.onStart,
+        onMove: options.onMove,
+        onEnd: options.onEnd,
+        onCancel: options.onCancel
+      });
+    },
+    [options]
+  );
+  return { startDrag };
+}
+function useDesktopResize(options) {
+  const startResize = useCallback(
+    (event, direction) => {
+      return DesktopPointerSession.startResize(event, {
+        direction,
+        initialBounds: options.getBounds(),
+        minWidth: options.minWidth,
+        minHeight: options.minHeight,
+        maxWidth: options.maxWidth,
+        maxHeight: options.maxHeight,
+        onStart: options.onStart,
+        onMove: options.onMove,
+        onEnd: options.onEnd,
+        onCancel: options.onCancel
+      });
+    },
+    [options]
+  );
+  return { startResize };
+}
+
+export { ReactApplicationWindow, closeReactApplicationWindow, registerReactApplication, useDesktop, useDesktopDrag, useDesktopResize, useWindowInstance, useWindowManager };

package/package.json

@@ -1,6 +1,49 @@
 {
   "name": "@owdproject/react",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "4.0.0-alpha.4",
+  "description": "Official React 18/19 adapter for @owdproject/core",
+  "homepage": "https://github.com/owdproject/react#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/owdproject/react.git"
+  },
+  "author": {
+    "name": "Diego Villa (@dxlliv)",
+    "url": "https://github.com/dxlliv"
+  },
+  "license": "MIT",
+  "type": "module",
+  "main": "./dist/index.mjs",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "unbuild",
+    "prepack": "unbuild"
+  },
+  "publishConfig": {
+    "access": "public",
+    "tag": "alpha",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "default": "./dist/index.mjs"
+    }
+  },
+  "dependencies": {
+    "@owdproject/core": "^4.0.0-alpha.3"
+  },
+  "peerDependencies": {
+    "react": ">=18.0.0"
+  },
+  "devDependencies": {
+    "unbuild": "^3.6.1",
+    "typescript": "~6.0.3"
+  }
+}