@arcanejs/react-toolkit 0.1.4 → 0.2.0

package/README.md

@@ -15,7 +15,7 @@ The UI has also been designed primarily with touch devices in mind,
 but also works well with a cursor and keyboard.
 
 <p align="center">
-  <img src="./docs/architecture.svg" alt="Architecture Diagram">
+  <img src="https://raw.githubusercontent.com/arcanejs/arcanejs/main/packages/react-toolkit/docs/architecture.svg" alt="Architecture Diagram">
 </p>
 
 ## What
@@ -114,7 +114,7 @@ ToolkitRenderer.render(<ControlPanel />, toolkit);
 You would then be able to access the following control panel
 from [localhost:3000](http://localhost:3000):
 
-![Control Panel Screenshot](./docs/example-controller.png)
+![Control Panel Screenshot](https://raw.githubusercontent.com/arcanejs/arcanejs/main/packages/react-toolkit/docs/example-controller.png)
 
 Please note:
 

package/dist/data.d.mts

@@ -0,0 +1,45 @@
+import { ReactNode, FC, Context } from 'react';
+import { ZodType } from 'zod';
+
+type ProviderProps = {
+    path: string;
+    children: ReactNode;
+};
+type DataFileUpdater<T> = (update: (current: T) => T) => void;
+type DataFileContext<T> = {
+    data: T;
+    updateData: DataFileUpdater<T>;
+    /**
+     * Can be called to force an attempt to re-save the data to disk
+     */
+    saveData: () => void;
+    /**
+     * If an error has ocurred in the last operation (e.g. load or save,
+     * then this will be set to that error).
+     *
+     * Can be used for example to re-prompt users to save data.
+     */
+    error: unknown;
+};
+type DataFile<T> = {
+    Provider: FC<ProviderProps>;
+    context: Context<DataFileContext<T>>;
+};
+type DataFileProps<T> = {
+    schema: ZodType<T>;
+    defaultValue: T;
+    /**
+     * When the file path changes and the file does not yet exist,
+     * should the previous data be stored in the new file
+     * or should the new file be reset to the default value?
+     *
+     * @default 'defaultValue'
+     */
+    onPathChange?: 'transfer' | 'defaultValue';
+};
+declare function useDataFileData<T>(dataFile: DataFile<T>): T;
+declare function useDataFileUpdater<T>(dataFile: DataFile<T>): DataFileUpdater<T>;
+declare function useDataFile<T>(dataFile: DataFile<T>): DataFileContext<T>;
+declare function createDataFileSpec<T>({ schema, defaultValue, onPathChange, }: DataFileProps<T>): DataFile<T>;
+
+export { type ProviderProps, createDataFileSpec, useDataFile, useDataFileData, useDataFileUpdater };

package/dist/data.d.ts

@@ -0,0 +1,45 @@
+import { ReactNode, FC, Context } from 'react';
+import { ZodType } from 'zod';
+
+type ProviderProps = {
+    path: string;
+    children: ReactNode;
+};
+type DataFileUpdater<T> = (update: (current: T) => T) => void;
+type DataFileContext<T> = {
+    data: T;
+    updateData: DataFileUpdater<T>;
+    /**
+     * Can be called to force an attempt to re-save the data to disk
+     */
+    saveData: () => void;
+    /**
+     * If an error has ocurred in the last operation (e.g. load or save,
+     * then this will be set to that error).
+     *
+     * Can be used for example to re-prompt users to save data.
+     */
+    error: unknown;
+};
+type DataFile<T> = {
+    Provider: FC<ProviderProps>;
+    context: Context<DataFileContext<T>>;
+};
+type DataFileProps<T> = {
+    schema: ZodType<T>;
+    defaultValue: T;
+    /**
+     * When the file path changes and the file does not yet exist,
+     * should the previous data be stored in the new file
+     * or should the new file be reset to the default value?
+     *
+     * @default 'defaultValue'
+     */
+    onPathChange?: 'transfer' | 'defaultValue';
+};
+declare function useDataFileData<T>(dataFile: DataFile<T>): T;
+declare function useDataFileUpdater<T>(dataFile: DataFile<T>): DataFileUpdater<T>;
+declare function useDataFile<T>(dataFile: DataFile<T>): DataFileContext<T>;
+declare function createDataFileSpec<T>({ schema, defaultValue, onPathChange, }: DataFileProps<T>): DataFile<T>;
+
+export { type ProviderProps, createDataFileSpec, useDataFile, useDataFileData, useDataFileUpdater };

package/dist/data.js

@@ -0,0 +1,203 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/data.tsx
+var data_exports = {};
+__export(data_exports, {
+  createDataFileSpec: () => createDataFileSpec,
+  useDataFile: () => useDataFile,
+  useDataFileData: () => useDataFileData,
+  useDataFileUpdater: () => useDataFileUpdater
+});
+module.exports = __toCommonJS(data_exports);
+var import_fs = require("fs");
+var import_react = require("react");
+var import_lodash = require("lodash");
+var import_path = require("path");
+var import_jsx_runtime = require("react/jsx-runtime");
+function useDataFileData(dataFile) {
+  return (0, import_react.useContext)(dataFile.context).data;
+}
+function useDataFileUpdater(dataFile) {
+  return (0, import_react.useContext)(dataFile.context).updateData;
+}
+function useDataFile(dataFile) {
+  return (0, import_react.useContext)(dataFile.context);
+}
+function createDataFileSpec({
+  schema,
+  defaultValue,
+  onPathChange = "defaultValue"
+}) {
+  const context = (0, import_react.createContext)({
+    data: defaultValue,
+    updateData: () => {
+      throw new Error("Data file provider not used");
+    },
+    saveData: () => {
+      throw new Error("Data file provider not used");
+    },
+    error: void 0
+  });
+  const Provider = ({ path, children }) => {
+    const state = (0, import_react.useRef)({
+      path: null,
+      data: void 0,
+      previousData: void 0,
+      state: {
+        state: "saved"
+      }
+    });
+    const [data, setData] = (0, import_react.useState)({
+      status: "loading"
+    });
+    const updateDataFromState = (0, import_react.useMemo)(
+      () => () => {
+        const data2 = state.current.data;
+        if (state.current.state.state === "error") {
+          setData({
+            status: "error",
+            error: state.current.state.error,
+            data: data2
+          });
+          return;
+        }
+        if (data2 === void 0) {
+          setData({
+            status: "loading"
+          });
+          return;
+        }
+        setData({
+          status: "ready",
+          data: data2
+        });
+      },
+      []
+    );
+    const requestFileWriteToDisk = (0, import_react.useMemo)(
+      () => (0, import_lodash.throttle)(
+        async () => {
+          if (state.current.state.state === "saved") {
+            return;
+          }
+          const currentPath = state.current.path;
+          const currentData = state.current.data;
+          if (!currentPath || currentData === void 0) {
+            return;
+          }
+          try {
+            const json = JSON.stringify(currentData, null, 2);
+            await import_fs.promises.mkdir((0, import_path.dirname)(currentPath), { recursive: true });
+            await import_fs.promises.writeFile(currentPath, json, "utf8");
+            if (state.current.path === currentPath && state.current.data === currentData) {
+              state.current.state = { state: "saved" };
+            }
+          } catch (error) {
+            if (state.current.path === currentPath && state.current.data === currentData) {
+              state.current.state = { state: "error", error };
+              updateDataFromState();
+            }
+          }
+        },
+        500,
+        {
+          // Write leading so that we always write to disk quickly when
+          // only single things have changed
+          leading: true,
+          // Trailing is important otherwise we may lose data
+          trailing: true
+        }
+      ),
+      []
+    );
+    (0, import_react.useEffect)(() => {
+      state.current = {
+        path,
+        data: void 0,
+        previousData: state.current.data ?? state.current.previousData,
+        state: {
+          state: "saved"
+        }
+      };
+      import_fs.promises.readFile(path, "utf8").then((data2) => {
+        const parsedData = schema.parse(JSON.parse(data2));
+        if (state.current.path === path) {
+          state.current.data = parsedData;
+          state.current.state = { state: "saved" };
+          updateDataFromState();
+        }
+      }).catch((error) => {
+        if (state.current.path !== path) {
+          return;
+        }
+        if (error.code === "ENOENT") {
+          console.log("Creating new file");
+          const initialData = onPathChange === "transfer" && state.current.previousData !== void 0 ? state.current.previousData : defaultValue;
+          state.current.data = initialData;
+          state.current.state = { state: "dirty" };
+          requestFileWriteToDisk();
+          updateDataFromState();
+          return;
+        }
+        state.current.state = { state: "error", error };
+        updateDataFromState();
+      });
+    }, [path]);
+    const updateData = (0, import_react.useMemo)(
+      () => (update) => {
+        if (state.current.path !== path) {
+          return;
+        }
+        if (state.current.data === void 0) {
+          throw new Error("Attempt to update data before it has been loaded");
+        }
+        state.current.data = update(state.current.data);
+        state.current.state = { state: "dirty" };
+        requestFileWriteToDisk();
+        updateDataFromState();
+      },
+      [path]
+    );
+    const providedContext = (0, import_react.useMemo)(
+      () => ({
+        data: data.status !== "loading" && data.data !== void 0 ? data.data : defaultValue,
+        updateData,
+        saveData: requestFileWriteToDisk,
+        error: data.status === "error" ? data.error : void 0
+      }),
+      [data, updateData]
+    );
+    if (data.status === "loading") {
+      return /* @__PURE__ */ (0, import_jsx_runtime.jsx)(import_jsx_runtime.Fragment, { children: "Loading..." });
+    }
+    return /* @__PURE__ */ (0, import_jsx_runtime.jsx)(context.Provider, { value: providedContext, children });
+  };
+  return {
+    Provider,
+    context
+  };
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  createDataFileSpec,
+  useDataFile,
+  useDataFileData,
+  useDataFileUpdater
+});

package/dist/data.mjs

@@ -0,0 +1,182 @@
+// src/data.tsx
+import { promises as fs } from "fs";
+import {
+  useMemo,
+  useContext,
+  createContext,
+  useState,
+  useEffect,
+  useRef
+} from "react";
+import { throttle } from "lodash";
+import { dirname } from "path";
+import { Fragment, jsx } from "react/jsx-runtime";
+function useDataFileData(dataFile) {
+  return useContext(dataFile.context).data;
+}
+function useDataFileUpdater(dataFile) {
+  return useContext(dataFile.context).updateData;
+}
+function useDataFile(dataFile) {
+  return useContext(dataFile.context);
+}
+function createDataFileSpec({
+  schema,
+  defaultValue,
+  onPathChange = "defaultValue"
+}) {
+  const context = createContext({
+    data: defaultValue,
+    updateData: () => {
+      throw new Error("Data file provider not used");
+    },
+    saveData: () => {
+      throw new Error("Data file provider not used");
+    },
+    error: void 0
+  });
+  const Provider = ({ path, children }) => {
+    const state = useRef({
+      path: null,
+      data: void 0,
+      previousData: void 0,
+      state: {
+        state: "saved"
+      }
+    });
+    const [data, setData] = useState({
+      status: "loading"
+    });
+    const updateDataFromState = useMemo(
+      () => () => {
+        const data2 = state.current.data;
+        if (state.current.state.state === "error") {
+          setData({
+            status: "error",
+            error: state.current.state.error,
+            data: data2
+          });
+          return;
+        }
+        if (data2 === void 0) {
+          setData({
+            status: "loading"
+          });
+          return;
+        }
+        setData({
+          status: "ready",
+          data: data2
+        });
+      },
+      []
+    );
+    const requestFileWriteToDisk = useMemo(
+      () => throttle(
+        async () => {
+          if (state.current.state.state === "saved") {
+            return;
+          }
+          const currentPath = state.current.path;
+          const currentData = state.current.data;
+          if (!currentPath || currentData === void 0) {
+            return;
+          }
+          try {
+            const json = JSON.stringify(currentData, null, 2);
+            await fs.mkdir(dirname(currentPath), { recursive: true });
+            await fs.writeFile(currentPath, json, "utf8");
+            if (state.current.path === currentPath && state.current.data === currentData) {
+              state.current.state = { state: "saved" };
+            }
+          } catch (error) {
+            if (state.current.path === currentPath && state.current.data === currentData) {
+              state.current.state = { state: "error", error };
+              updateDataFromState();
+            }
+          }
+        },
+        500,
+        {
+          // Write leading so that we always write to disk quickly when
+          // only single things have changed
+          leading: true,
+          // Trailing is important otherwise we may lose data
+          trailing: true
+        }
+      ),
+      []
+    );
+    useEffect(() => {
+      state.current = {
+        path,
+        data: void 0,
+        previousData: state.current.data ?? state.current.previousData,
+        state: {
+          state: "saved"
+        }
+      };
+      fs.readFile(path, "utf8").then((data2) => {
+        const parsedData = schema.parse(JSON.parse(data2));
+        if (state.current.path === path) {
+          state.current.data = parsedData;
+          state.current.state = { state: "saved" };
+          updateDataFromState();
+        }
+      }).catch((error) => {
+        if (state.current.path !== path) {
+          return;
+        }
+        if (error.code === "ENOENT") {
+          console.log("Creating new file");
+          const initialData = onPathChange === "transfer" && state.current.previousData !== void 0 ? state.current.previousData : defaultValue;
+          state.current.data = initialData;
+          state.current.state = { state: "dirty" };
+          requestFileWriteToDisk();
+          updateDataFromState();
+          return;
+        }
+        state.current.state = { state: "error", error };
+        updateDataFromState();
+      });
+    }, [path]);
+    const updateData = useMemo(
+      () => (update) => {
+        if (state.current.path !== path) {
+          return;
+        }
+        if (state.current.data === void 0) {
+          throw new Error("Attempt to update data before it has been loaded");
+        }
+        state.current.data = update(state.current.data);
+        state.current.state = { state: "dirty" };
+        requestFileWriteToDisk();
+        updateDataFromState();
+      },
+      [path]
+    );
+    const providedContext = useMemo(
+      () => ({
+        data: data.status !== "loading" && data.data !== void 0 ? data.data : defaultValue,
+        updateData,
+        saveData: requestFileWriteToDisk,
+        error: data.status === "error" ? data.error : void 0
+      }),
+      [data, updateData]
+    );
+    if (data.status === "loading") {
+      return /* @__PURE__ */ jsx(Fragment, { children: "Loading..." });
+    }
+    return /* @__PURE__ */ jsx(context.Provider, { value: providedContext, children });
+  };
+  return {
+    Provider,
+    context
+  };
+}
+export {
+  createDataFileSpec,
+  useDataFile,
+  useDataFileData,
+  useDataFileUpdater
+};

package/dist/index.d.mts

@@ -1,68 +1,82 @@
 import * as ld from '@arcanejs/toolkit';
-import { Props as Props$1, Events as Events$1 } from '@arcanejs/toolkit/components/group';
-import { Props, Events } from '@arcanejs/toolkit/components/button';
-import { Props as Props$2 } from '@arcanejs/toolkit/components/label';
-import { Props as Props$3 } from '@arcanejs/toolkit/components/rect';
-import { Props as Props$4, Events as Events$2 } from '@arcanejs/toolkit/components/slider-button';
-import { Props as Props$5, Events as Events$3 } from '@arcanejs/toolkit/components/switch';
-import { TabProps, TabsProps } from '@arcanejs/toolkit/components/tabs';
-import { Props as Props$6, Events as Events$4 } from '@arcanejs/toolkit/components/text-input';
-import { Props as Props$7 } from '@arcanejs/toolkit/components/timeline';
+import { Props as Props$1, Events as Events$1, Group as Group$1, GroupHeader as GroupHeader$1 } from '@arcanejs/toolkit/components/group';
+import { Props, Events, Button as Button$1 } from '@arcanejs/toolkit/components/button';
+import { Props as Props$2, Label as Label$1 } from '@arcanejs/toolkit/components/label';
+import { Props as Props$3, Rect as Rect$1 } from '@arcanejs/toolkit/components/rect';
+import { Props as Props$4, Events as Events$2, SliderButton as SliderButton$1 } from '@arcanejs/toolkit/components/slider-button';
+import { Props as Props$5, Events as Events$3, Switch as Switch$1 } from '@arcanejs/toolkit/components/switch';
+import { TabProps, Tab as Tab$1, TabsProps, Tabs as Tabs$1 } from '@arcanejs/toolkit/components/tabs';
+import { Props as Props$6, Events as Events$4, TextInput as TextInput$1 } from '@arcanejs/toolkit/components/text-input';
+import { Props as Props$7, Timeline as Timeline$1 } from '@arcanejs/toolkit/components/timeline';
 import * as React from 'react';
+import { Ref } from 'react';
 
-type Children = JSX.Element | string | (string | JSX.Element)[];
+type Child = JSX.Element | string | null | undefined;
+type Children = Child | Child[];
 interface LightDeskIntrinsicElements {
     button: Props & {
         children?: never;
         onClick?: Events['click'];
+        ref?: Ref<Button$1>;
     };
     group: Props$1 & {
         children?: Children;
         onTitleChanged?: Events$1['title-changed'];
+        ref?: Ref<Group$1>;
     };
     'group-header': {
         children?: Children;
+        ref?: Ref<GroupHeader$1>;
     };
     label: Props$2 & {
         children?: never;
+        ref?: Ref<Label$1>;
     };
     rect: Props$3 & {
         children?: never;
+        ref?: Ref<Rect$1>;
     };
     'slider-button': Props$4 & {
         children?: never;
         onChange?: Events$2['change'];
+        ref?: Ref<SliderButton$1>;
     };
     switch: Props$5 & {
         children?: never;
         onChange?: Events$3['change'];
+        ref?: Ref<Switch$1>;
     };
     tab: TabProps & {
         children?: JSX.Element | string;
+        ref?: Ref<Tab$1>;
     };
     tabs: TabsProps & {
         children?: JSX.Element | JSX.Element[];
+        ref?: Ref<Tabs$1>;
     };
     'text-input': Props$6 & {
         children?: JSX.Element | JSX.Element[];
         onChange?: Events$4['change'];
+        ref?: Ref<TextInput$1>;
     };
     timeline: Props$7 & {
         children?: never;
+        ref?: Ref<Timeline$1>;
     };
 }
 
-declare const Button: React.FunctionComponent<LightDeskIntrinsicElements['button']>;
-declare const Group: React.FunctionComponent<LightDeskIntrinsicElements['group']>;
-declare const GroupHeader: React.FunctionComponent<LightDeskIntrinsicElements['group-header']>;
-declare const Label: React.FunctionComponent<LightDeskIntrinsicElements['label']>;
-declare const Rect: React.FunctionComponent<LightDeskIntrinsicElements['rect']>;
-declare const SliderButton: React.FunctionComponent<LightDeskIntrinsicElements['slider-button']>;
-declare const Switch: React.FunctionComponent<LightDeskIntrinsicElements['switch']>;
-declare const Tab: React.FunctionComponent<LightDeskIntrinsicElements['tab']>;
-declare const Tabs: React.FunctionComponent<LightDeskIntrinsicElements['tabs']>;
-declare const TextInput: React.FunctionComponent<LightDeskIntrinsicElements['text-input']>;
-declare const Timeline: React.FunctionComponent<LightDeskIntrinsicElements['timeline']>;
+type ComponentWithRef<T, P> = React.ForwardRefExoticComponent<React.PropsWithoutRef<P> & React.RefAttributes<T>>;
+declare const Button: ComponentWithRef<Button$1, LightDeskIntrinsicElements['button']>;
+declare const Group: ComponentWithRef<Group$1, LightDeskIntrinsicElements['group']>;
+declare const GroupHeader: ComponentWithRef<GroupHeader$1, LightDeskIntrinsicElements['group-header']>;
+declare const Label: ComponentWithRef<Label$1, LightDeskIntrinsicElements['label']>;
+declare const Rect: ComponentWithRef<Rect$1, LightDeskIntrinsicElements['rect']>;
+declare const SliderButton: ComponentWithRef<SliderButton$1, LightDeskIntrinsicElements['slider-button']>;
+declare const Switch: ComponentWithRef<Switch$1, LightDeskIntrinsicElements['switch']>;
+declare const Tab: ComponentWithRef<Tab$1, LightDeskIntrinsicElements['tab']>;
+declare const Tabs: ComponentWithRef<Tabs$1, LightDeskIntrinsicElements['tabs']>;
+declare const TextInput: ComponentWithRef<TextInput$1, LightDeskIntrinsicElements['text-input']>;
+declare const Timeline: ComponentWithRef<Timeline$1, LightDeskIntrinsicElements['timeline']>;
 
 declare const ToolkitRenderer: {
     renderGroup: (component: JSX.Element, container: ld.Group) => void;