tinywidgets 1.0.16 → 1.1.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tinywidgets",
-  "version": "1.0.16",
+  "version": "1.1.0",
   "author": "jamesgpearce",
   "repository": "github:tinyplex/tinywidgets",
   "license": "MIT",
@@ -21,26 +21,26 @@
   "devDependencies": {
     "@types/react": "^18.3.11",
     "@types/react-dom": "^18.3.0",
-    "@typescript-eslint/eslint-plugin": "^8.8.0",
-    "@typescript-eslint/parser": "^8.8.0",
-    "cspell": "^8.14.4",
+    "@typescript-eslint/eslint-plugin": "^8.17.0",
+    "@typescript-eslint/parser": "^8.17.0",
+    "cspell": "^8.16.1",
     "eslint": "^8.57.0",
     "eslint-config-prettier": "^9.1.0",
-    "eslint-plugin-react": "^7.37.1",
-    "eslint-plugin-react-hooks": "^4.6.2",
-    "eslint-plugin-react-refresh": "^0.4.12",
-    "prettier": "^3.3.3",
-    "typescript": "^5.6.2"
+    "eslint-plugin-react": "^7.37.2",
+    "eslint-plugin-react-hooks": "^5.1.0",
+    "eslint-plugin-react-refresh": "^0.4.16",
+    "prettier": "^3.4.2",
+    "typescript": "^5.7.2"
   },
   "exports": {
     ".": "./src/index.ts",
     "./css": "./src/index.css.ts"
   },
   "dependencies": {
-    "@vanilla-extract/css": "^1.16.0",
-    "lucide-react": "^0.447.0",
+    "@vanilla-extract/css": "^1.16.1",
+    "lucide-react": "^0.468.0",
     "react": "^18.3.1",
     "react-dom": "^18.3.1",
-    "tinybase": "^5.3.2"
+    "tinybase": "^5.4.2"
   }
 }

package/src/components/TasksProvider/index.tsx

@@ -0,0 +1,287 @@
+import * as UiReact from 'tinybase/ui-react/with-schemas';
+import {
+  Id,
+  Store as StoreWithSchemas,
+  createStore,
+} from 'tinybase/with-schemas';
+import React, {
+  ReactNode,
+  createContext,
+  useCallback,
+  useContext,
+  useEffect,
+  useRef,
+} from 'react';
+import {
+  Provider as UiReactProvider,
+  useStore,
+  useStores,
+} from 'tinybase/ui-react';
+import {Persister} from 'tinybase/persisters/with-schemas';
+import {Store} from 'tinybase';
+import {createLocalPersister} from 'tinybase/persisters/persister-browser/with-schemas';
+
+export type Task =
+  | ((
+      arg: string,
+      store: Store | undefined,
+      scheduleTask: ScheduleTask,
+    ) => void)
+  | ((
+      arg: string,
+      store: StoreWithSchemas<any> | undefined,
+      scheduleTask: ScheduleTask,
+    ) => void)
+  | ((
+      arg: string,
+      store: Store | undefined,
+      scheduleTask: ScheduleTask,
+    ) => Promise<void>)
+  | ((
+      arg: string,
+      store: StoreWithSchemas<any> | undefined,
+      scheduleTask: ScheduleTask,
+    ) => Promise<void>);
+export type Tasks = {
+  [taskId: string]: Task;
+};
+export type ScheduleTask = (taskId: Id, arg?: string, storeId?: string) => void;
+
+const STORE_ID = 'tinywidgets/Tasks';
+const TABLE_ID = 'tasks';
+
+const TABLES_SCHEMA = {
+  tasks: {
+    taskId: {type: 'string', default: ''},
+    arg: {type: 'string'},
+    storeId: {type: 'string'},
+    running: {type: 'boolean'},
+    expires: {type: 'number', default: 0},
+  },
+} as const;
+const VALUES_SCHEMA = {} as const;
+type Schemas = [typeof TABLES_SCHEMA, typeof VALUES_SCHEMA];
+const {useCreateStore, useCreatePersister} =
+  UiReact as UiReact.WithSchemas<Schemas>;
+
+const Context = createContext<ScheduleTask>(() => {});
+
+const TaskRunner = ({
+  tasks,
+  tasksStore,
+  interval,
+}: {
+  readonly tasks: Tasks;
+  readonly tasksStore: StoreWithSchemas<Schemas>;
+  readonly interval: number;
+}) => {
+  const store = useStore();
+  const stores = useStores();
+  const scheduleTask = useContext(Context);
+  useEffect(() => {
+    const nextJob = async () => {
+      const jobId = tasksStore.getRowIds(TABLE_ID)[0];
+      if (jobId != null) {
+        const {taskId, arg, storeId, running, expires} = tasksStore.getRow(
+          TABLE_ID,
+          jobId,
+        );
+        if (expires > Date.now()) {
+          const task = tasks[taskId];
+          if (task && !running) {
+            tasksStore.setCell(TABLE_ID, jobId, 'running', true);
+            try {
+              await task(
+                arg ?? '',
+                storeId == null ? store : (stores[storeId] as any),
+                scheduleTask,
+              );
+            } catch {}
+            tasksStore.delRow(TABLE_ID, jobId);
+          }
+        } else {
+          tasksStore.delRow(TABLE_ID, jobId);
+        }
+      }
+    };
+    const intervalHandle = setInterval(nextJob, interval * 1000);
+    return () => clearInterval(intervalHandle);
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [tasksStore, JSON.stringify(Object.keys(stores))]);
+
+  return null;
+};
+
+/**
+ * The useScheduleTask hook returns a function that can be used to schedule a
+ * new task.
+ *
+ * The returned function takes the following arguments:
+ *
+ * - `taskId`: a required string to identify the task by Id.
+ * - `arg`: an optional string that will be passed to the task when run.
+ * - `storeId`: an optional string that will be used to look up a Store by Id
+ *   in the current TinyBase Provider context and be passed to the task.
+ *
+ * @example
+ * ```tsx
+ * const TaskButton = () => {
+ *   const scheduleTask = useScheduleTask();
+ *   return (<Button
+ *     title="Hello"
+ *     onClick={() => scheduleTask('greet', 'Hello')}
+ *   />);
+ * };
+ * // ...
+ * <TasksProvider tasks={{greet: (arg) => alert(arg)}}>
+ *   <TaskButton />
+ * </TasksProvider>
+ * ```
+ * This example shows the hook returning a function that will schedule a task to
+ * be run by the provider. Note that it may take as long as a second (the
+ * default interval between task executions) for the alert to appear.
+ * @example
+ * ```tsx
+ * const TaskButton2 = () => {
+ *   const scheduleTask = useScheduleTask();
+ *   return (<Button
+ *     iconRight={Lucide.Globe}
+ *     title="Hello"
+ *     onClick={() => scheduleTask('greet1', 'Hello')}
+ *   />);
+ * };
+ * // ...
+ * <TasksProvider tasks={{
+ *   greet1: async (arg, store, scheduleTask) => {
+ *     scheduleTask('greet2', 'World');
+ *     alert(arg);
+ *   },
+ *   greet2: (arg) => alert(arg)
+ * }}>
+ *   <TaskButton2 />
+ * </TasksProvider>
+ * ```
+ * This example shows the hook returning a function that will schedule a task to
+ * be run by the provider. That task in turn will call another.
+ */
+export const useScheduleTask = () => useContext(Context);
+
+/**
+ * The `TasksProvider` component is a non-visual component that makes it easy to
+ * manage sequential tasks in your TinyWidget application.
+ *
+ * @param props The props for the component.
+ * @returns The TasksProvider component.
+ * @icon Lucide.FileClock
+ * @example
+ * ```tsx
+ * const TaskButton1 = () => {
+ *   const scheduleTask = useScheduleTask();
+ *   return (<Button
+ *     iconRight={Lucide.Hand}
+ *     title="Hello"
+ *     onClick={() => scheduleTask('greet1')}
+ *   />);
+ * };
+ * const TaskButton2 = () => {
+ *   const scheduleTask = useScheduleTask();
+ *   return (<Button
+ *     iconRight={Lucide.Globe}
+ *     title="World"
+ *     onClick={() => scheduleTask('greet2')}
+ *   />);
+ * };
+ * // ...
+ * <TasksProvider tasks={{
+ *   greet1: () => alert('Hello'),
+ *   greet2: () => alert('World'),
+ * }}>
+ *   <TaskButton1 />
+ *   <TaskButton2 />
+ * </TasksProvider>
+ * ```
+ * This example shows the hook returning a function that will schedule a task to
+ * be run by the provider. That task in turn will call another.
+ */
+export const TasksProvider = ({
+  tasks,
+  interval = 1,
+  expiry = 5,
+  children,
+}: {
+  /**
+   * An object listing all the tasks that can be executed, keyed by Id.
+   *
+   * Each task is a function that receives a string argument, a reference to a
+   * Store (each as specified when `scheduleTask` was called), and a reference
+   * to the `scheduleTask` function again so that tasks can be chained.
+   *
+   * A task can be asynchronous.
+   */
+  readonly tasks: Tasks;
+  /**
+   * The interval in seconds between each task execution, defaulting to 1.
+   */
+  readonly interval?: number;
+  /**
+   * The time in seconds from scheduling until a task expires and will not be
+   * started, defaulting to 5.
+   */
+  readonly expiry?: number;
+  /**
+   * The children of the component to be rendered.
+   */
+  readonly children: ReactNode;
+}) => {
+  const pendingAddedJobs = useRef<
+    [taskId: string, arg?: string, storeId?: string][]
+  >([]);
+  const activePersister = useRef<Persister<Schemas> | undefined>();
+
+  const tasksStore = useCreateStore(() =>
+    createStore().setSchema(TABLES_SCHEMA, VALUES_SCHEMA),
+  );
+
+  useCreatePersister(
+    tasksStore,
+    (tasksStore) => createLocalPersister(tasksStore, STORE_ID),
+    [],
+    async (persister) => {
+      await persister.startAutoLoad();
+      tasksStore.forEachRow('tasks', (taskId, _) =>
+        tasksStore.delCell('tasks', taskId, 'running'),
+      );
+      await persister.startAutoSave();
+      activePersister.current = persister;
+      pendingAddedJobs.current.forEach((pendingAddedJob) =>
+        scheduleTask(...pendingAddedJob),
+      );
+      pendingAddedJobs.current.splice(0);
+    },
+  );
+
+  const scheduleTask: ScheduleTask = useCallback(
+    (taskId: string, arg?: string, storeId?: string) => {
+      if (activePersister.current) {
+        tasksStore.addRow(TABLE_ID, {
+          taskId,
+          expires: Date.now() + expiry * 1000,
+          arg,
+          storeId,
+        });
+      } else {
+        pendingAddedJobs.current.push([taskId, arg, storeId]);
+      }
+    },
+    [tasksStore, expiry],
+  );
+
+  return (
+    <Context.Provider value={scheduleTask}>
+      <UiReactProvider>
+        {children}
+        <TaskRunner tasks={tasks} tasksStore={tasksStore} interval={interval} />
+      </UiReactProvider>
+    </Context.Provider>
+  );
+};

package/src/index.ts

@@ -10,6 +10,10 @@ export {Metric} from './components/Metric/index.tsx';
 export {Row} from './components/Row/index.tsx';
 export {Summary} from './components/Summary/index.tsx';
 export {Tag} from './components/Tag/index.tsx';
+export {
+  TasksProvider,
+  useScheduleTask,
+} from './components/TasksProvider/index.tsx';
 
 export {useRoute, useSetRouteCallback} from './stores/RouteStore.tsx';
 export {useDark} from './stores/LocalStore.tsx';