tinywidgets 1.0.15 → 1.1.0

package/README.md

@@ -0,0 +1,60 @@
+# TinyWidgets
+
+A collection of tiny, reusable, UI components
+— wrapped in a helpful app layout with header, side bar, dark mode, and more.
+
+See the [website](https://tinywidgets.org/) for more details. Get started [here](https://tinywidgets.org/#installation).
+
+<img width="1213" alt="image" src="https://github.com/user-attachments/assets/22b69545-52d5-424d-ab80-084bb87237f4">
+
+---
+
+## Dependencies
+
+TinyWidgets uses [React](https://react.dev/) for DOM manipulation, [Vanilla-Extract](https://vanilla-extract.style/) at build-time for styling, [Lucide](https://lucide.dev/) for icons, and [TinyBase](https://tinybase.org/) for state management. Its philosophy is all about simplicity, decent defaults, a streamlined DOM, and concise styling.
+
+But, just to be clear - that doesn't mean you need to use Vanilla-Extract, Lucide, or Tinybase in the apps you build with these widgets. You can set arbitrary class names (from Tailwind, for example!) on all components if you like.
+
+## Help out!
+
+This project was created because [I](https://github.com/jamesgpearce) want to be able to build lots of local-first apps quickly and without the overhead of all the app boilerplate each time.
+
+Making it open source seemed like the right thing to do, so please try and it out and get involved. I'll always be interested in issues, more style variants, new components altogether, or even some professional-grade design assistance. I'm not a designer...
+
+See you on [GitHub](https://github.com/tinyplex/tinywidgets)!
+
+## Installation
+
+The easiest way to get started with TinyWidgets is to use its [Vite template](https://github.com/tinyplex/vite-tinywidgets/). This comes with the (simple) build configuration you need to work with TinyWidgets.
+
+To create a new TinyWidgets application using this template, do the following:
+
+1. Make a copy of this template into a new directory:
+
+```sh
+npx tiged tinyplex/vite-tinywidgets my-tinywidgets-app
+```
+
+2. Go into the directory:
+
+```sh
+cd my-tinywidgets-app
+```
+
+3. Install the dependencies:
+
+```sh
+npm install
+```
+
+4. Run the application:
+
+```sh
+npm run dev
+```
+
+5. The Vite server should start up. Go the URL shown and enjoy!
+
+<img width="1160" alt="image" src="https://github.com/user-attachments/assets/073a26dc-4212-4ab0-b5a0-d968ac47342c">
+
+Note that you can also create a production build with `npm run build`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tinywidgets",
-  "version": "1.0.15",
+  "version": "1.1.0",
   "author": "jamesgpearce",
   "repository": "github:tinyplex/tinywidgets",
   "license": "MIT",
@@ -16,31 +16,31 @@
   ],
   "type": "module",
   "scripts": {
-    "prePublishPackage": "eslint . && cspell --quiet . && tsc"
+    "prePublishPackage": "eslint . && cspell --quiet . && tsc && cp ../README.md ./README.md"
   },
   "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';