React Window Manager

Intro

React Window Manager is a react context that manages element rendering with:

• windowSpecsRef:

{
    [windowId]:{ 
        // Component: '', //this key is used by react-desktop-environment, you can also add your own key value pairs
        registeredId: [],
        props: {
            initialPosition: { left: 100, top: 100 },
            initialSize: { width: 100, height: 100 },
            initialTitle: ''
        },
        windows: {
            active: [],
            hidden: [],
            closed: []
        },
        states: {}
    }, 
    [windowId]:{
        registeredId: [ anotherWindowId, anotherWindowId, ... ],
        props: {
            initialPosition: { left: 100, top: 100 },
            initialSize: { width: 100, height: 100 },
            initialTitle: '',
            ['custom prop key']: 'custom prop value',
            ...
        },
        // Component: Component.name,
        windows: {
            active: [ childWindowId, childWindowId ],
            hidden: [ childWindowId, childWindowId, ...],
            closed: [ `${childWindowId}@${unixtimestamp}`, ...]
        },
        states: {
            ['state key']: 'state value',
            ...
        }
    }
}

Installation

npm i react-window-manager

Usage

// main.jsx
import React, { useContext } from 'react'
import ReactDOM from 'react-dom/client'
import './index.css'
import App from './App'
import WindowManagerRegistryProvider, {WindowManagerRegistryContext} from './lib';

ReactDOM.createRoot(document.getElementById('root')).render(<Wrapper/>);

function Wrapper(){
  return (
    <React.StrictMode>
      <WindowManagerRegistryProvider>
        <Main/>
      </WindowManagerRegistryProvider>
    </React.StrictMode>
  )
}

function Main(){
  const { initWindow } = useContext(WindowManagerRegistryContext);
  initWindow('app');
  return (
      <App/>
  )
}

import { useContext, useState, useEffect, useRef } from 'react';

import { WindowManagerContext, WindowManagerProvider, WindowManagerRegistryContext } from './lib';

function App() {
    const { initWindow } = useContext(WindowManagerRegistryContext)
    const { windows, registerWindow, hideWindow, unhideWindow, closeWindow} = useContext(WindowManagerContext);

    const [ idToAction, setIdToAction] = useState(0);
    
    return (
        <div style={{ width: '100vw', height: '100vh'}}>
            <button onClick={()=>{
                initWindow(idToAction)
                registerWindow(idToAction) 
            }}> initWindow </button> <br/>

            <input onChange={(e)=>{
                setIdToAction(e.target.value)
            }}></input><br/>
            <button onClick={()=>{ hideWindow(idToAction) }}> hideWindow </button><br/>
            <button onClick={()=>{ unhideWindow(idToAction) }}> unhideWindow </button><br/>
            <button onClick={()=>{ closeWindow(idToAction) }}> closeWindow </button><br/>
            
            { `active: ${ JSON.stringify(windows.active) }`}<br/>
            { `hidden: ${ JSON.stringify(windows.hidden) }`}<br/>
            { `closed: ${ JSON.stringify(windows.closed) }`}<br/>
        </div>
    )
}

export default function WrappedHome(){

    return (
        <WindowManagerProvider id={'app'}>
            <App/>
        </WindowManagerProvider>
    )
}

Refernece

WindowManagerRegistry

Provider

<WindowManagerRegistryProvider windowSpecsFromLastSession={Object} syncToDataBaseFunctions={Function}>
    {children}
<WindowManagerRegistryProvider/>

| Prop | Description | | --- | ----------- | | windowSpecsFromLastSession | windowSpecsRef.current default value. this could be retrieved from an external storage such as database or localStorage. | | [TODO] syncToDataBaseFunctions | his function is meant to save the current windowSpecsRef to your external store |

Context

const {
    initWindow, // Function
    getAllWindowSpecs, // Function
    doesTargetWindowIdExist, // Function
    getTargetWindowSpecsById, // Function
    setTargetWindowSpecsById, // Function
    reassginTargetWindowId // Function
} = useContext( WindowManagerRegistryProviderContext );

| Item | Params | Description | | - | - | - | | initWindow() | windowId: String | this adds a windowId key into windowSpecsRef.current | | getAllWindowSpecs() | n/a | deep copy and returns windowSpecsRef.current | | doesTargetWindowIdExist() | targetWindowId: String | returns true if targetWindowId exists in windowSpecsRef.current else false | | getTargetWindowSpecsById() | targetWindowId: String | deep copy and returns windowSpecsRef.current[targetWindowId] | | setTargetWindowSpecsById() | targetWindowId: String, specFragment: Object | replace the spcified specs of the targetWindowId. e.g. { Component: 'NewComponent', registeredIn: [ 'parentWindowId' ] } will replace Component and state key in the spec | | [usable] reassignTargetWindowId() | targetWindowId: String, newTargetWindowId: String | this renames targetWindowId in windowSpecsRef.current |

WindowManager

Provider

<WindowManagerProvider id={String}/>
id = the current window id in windowSpecsRef.current

| Prop | Description | | - | - | | id | the id reference for provider to extract the correct windowSpecs from windowSpecsRef.current |

Context

const {
    currentWindowId,
    // useState
    windows,
    states,
    // init
    registerWindow,
    // controllers
    liftWindowToTop,
    hideWindow,
    unhideWindow,
    closeWindow,
    // states
    isWindowStatesReady,
    initWindowState,
    setWindowState,
    getWindowState,
    useWindowState
} = useWindowManagerProvider

| Item | Params | Description | | - | - | - | | currentWindowId | n/a | the current windowId | | windows | n/a | the current windows state of WindowContextProvider. windowSpecs.current[windowId] mirrors this value. this value is cleared when WindowContextProvider is unmounted. Useful for debugging but bad for readability | | states | n/a | the current states state of WindowContextProvider. windowSpecs.current[windowId] mirrors this value. this value is cleared when WindowContextProvider is unmounted. Useful for debugging but bad for readability | | registerWindow() | childWindowId: String | registers child window in current window | | liftWindowToTop() | childWindowId: String | moves childWindowId to the end of active array in windows state. | | hideWindow() | childWindowId: String | moves childWindowId to the end of hidden array in windows state from active array. | | [usable]closeWindow() | childWindowId: String | moves childWindowId to the end of closed array in windows state from active or hidden array. TODO: behaviour when the closed window has its own child or is registered in multiple windows | | isWindowStatesReady() | stateTitlesArray: [String] | checks if states[title] is initialised in states state. | | iniWindowState() | title: String, value: any | returns either states[title] if exist or mutate states by adding title:value in it, sync with windowSpecsRef then returns value. Use this when you need a state value that renders before or with WindowContextProvider. | | setWindowState() | title: String, value: any | updates states[title] and sync with windowSpecsRef. Use this when you only need to set state[title] but not consume in the current WindowcontextProvider | | getWindowState() | title: String | returns states[title]. Use this when you only need state[title] but not update state[title] in the current WindowcontextProvider | | useWindowState() | title: String, value: any | returns states[title] and it's setter. Like React.useState() |