React-window-manager NPM

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.currenttargetWindowId
`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.currentwindowId 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.currentwindowId 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 statestitle is initialised in states state.
`iniWindowState()`	title: String, value: any	returns either statestitle 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 statestitle and sync with windowSpecsRef. Use this when you only need to set statetitle but not consume in the current WindowcontextProvider
`getWindowState()`	title: String	returns statestitle. Use this when you only need statetitle but not update statetitle in the current WindowcontextProvider
`useWindowState()`	title: String, value: any	returns statestitle and it's setter. Like React.useState()