feat: streamline usePuck history API

measuredco · Jun 20, 2024 · c8b2807 · c8b2807
1 parent 3918f54
commit c8b2807
Show file tree

Hide file tree

Showing 3 changed files with 67 additions and 3 deletions.
diff --git a/apps/docs/pages/docs/api-reference/functions/use-puck.mdx b/apps/docs/pages/docs/api-reference/functions/use-puck.mdx
@@ -32,6 +32,7 @@ export function Editor() {
 | ------------------------------- | ------------------------------------------------ | --------------------------------------------------- |
 | [`appState`](#appstate)         | `{ data: {}, ui: {} }`                           | [AppState](/docs/api-reference/app-state)           |
 | [`dispatch`](#dispatch)         | `(action: PuckAction) => void`                   | Function                                            |
+| [`history`](#history)           | `{}`                                             | Object                                              |
 | [`selectedItem`](#selecteditem) | `{ type: "Heading", props: {id: "my-heading"} }` | [ComponentData](/docs/api-reference/data#content-1) |
 
 ### `appState`
@@ -56,6 +57,58 @@ dispatch({
 });
 ```
 
+### `history`
+
+The `history` API provides programmatic access to the undo/redo [AppState](/docs/api-reference/app-state) history.
+
+| Param                            | Example                        | Type                           |
+| -------------------------------- | ------------------------------ | ------------------------------ |
+| [`back`](#historyback)           | `() => void`                   | Function                       |
+| [`forward`](#historyforward)     | `() => void`                   | Function                       |
+| [`hasPast`](#historyhaspast)     | `true`                         | Boolean                        |
+| [`hasFuture`](#historyhasfuture) | `false`                        | Boolean                        |
+| [`histories`](#historyhistories) | `[{ id: 'abc123', data: {} }]` | [History](#history-params)\[\] |
+| [`index`](#historyindex)         | `5`                            | Number                         |
+
+#### `history.back`
+
+A function to move the app state back through the [histories](#historyhistories).
+
+#### `history.forward`
+
+A function to move the app state forward through the [histories](#historyhistories).
+
+#### `history.hasPast`
+
+A boolean describing whether or not the present app state has past history items.
+
+#### `history.hasFuture`
+
+A boolean describing whether or not the present app state has future history items.
+
+#### `history.histories`
+
+An array describing the recorded history as `History` objects.
+
+##### `History` params
+
+| Param  | Example  | Type                                      |
+| ------ | -------- | ----------------------------------------- |
+| `data` | `{}`     | [AppState](/docs/api-reference/app-state) |
+| `id`   | `abc123` | String                                    |
+
+###### `data`
+
+The [app state](/docs/api-reference/app-state) payload for this history entry.
+
+###### `id`
+
+A unique ID for this history entry.
+
+#### `history.index`
+
+The index of the currently selected history in [`history.histories`](#historyhistories)
+
 ### `selectedItem`
 
 The currently selected item, as defined by `appState.ui.itemSelector`.

diff --git a/packages/core/lib/use-history-store.ts b/packages/core/lib/use-history-store.ts
@@ -8,16 +8,19 @@ export type History<D = any> = {
 };
 
 export type HistoryStore<D = any> = {
+  // Exposed via usePuck
   index: number;
-  currentHistory: History;
   hasPast: boolean;
   hasFuture: boolean;
+  histories: History<D>[];
+
+  // Internal
   record: (data: D) => void;
   back: VoidFunction;
   forward: VoidFunction;
+  currentHistory: History;
   nextHistory: History<D> | null;
   prevHistory: History<D> | null;
-  histories: History<D>[];
 };
 
 const EMPTY_HISTORY_INDEX = -1;

diff --git a/packages/core/lib/use-puck.ts b/packages/core/lib/use-puck.ts
@@ -13,7 +13,15 @@ export const usePuck = () => {
     appState,
     config,
     dispatch,
-    history,
+    history: {
+      back: history.back!,
+      forward: history.forward!,
+      hasPast: history.historyStore!.hasPast,
+      hasFuture: history.historyStore!.hasFuture,
+      histories: history.historyStore!.histories,
+      index: history.historyStore!.index,
+      historyStore: history.historyStore,
+    },
     selectedItem: selectedItem || null,
   };
 };