refactor!: deprecate proxyWithHistory (#839)

* docs: update proxyWithHistory website page

Adds reference to new npm package and codesandbox demo

* docs: update proxyWithHistory example with new package

* refactor!: deprecate proxyWithHistory

docs/api/utils/proxyWithHistory.mdx

@@ -12,7 +12,7 @@ description: ''
 This is a utility function to create a proxy with snapshot history.
 
 ```js
-import { proxyWithHistory } from 'valtio/utils'
+import { proxyWithHistory } from 'valtio-history'
 
 const state = proxyWithHistory({ count: 0 })
 console.log(state.value) // ---> { count: 0 }
@@ -26,4 +26,4 @@ console.log(state.value) // ---> { count: 1 }
 
 ## Codesandbox demo
 
-https://codesandbox.io/s/admiring-wright-2oh2x?file=/src/App.tsx
+https://codesandbox.io/s/valtio-history-example-v0-m353xc?file=/src/App.tsx

examples/editor-proxyWithHistory/package.json

@@ -7,7 +7,8 @@
   "dependencies": {
     "react": "17.0.2",
     "react-dom": "17.0.2",
-    "valtio": "1.2.11"
+    "valtio": "1.2.11",
+    "valtio-history": "0.0.1"
   },
   "devDependencies": {
     "@types/react": "17.0.20",

examples/editor-proxyWithHistory/src/App.tsx

@@ -1,22 +1,29 @@
 import './styles.css'
 import React from 'react'
 import { useSnapshot } from 'valtio'
-import { proxyWithHistory } from 'valtio/utils'
+import { proxyWithHistory } from 'valtio-history'
 
 const textProxy = proxyWithHistory({
-  text: 'Add some test to this initial value and then undo/redo',
+  text: 'Add some text to this initial value and then undo/redo',
 })
-const update = (e: React.ChangeEvent<HTMLTextAreaElement>) =>
-  (textProxy.value.text = e.target.value)
+
+const update = (event: React.ChangeEvent<HTMLTextAreaElement>) =>
+  (textProxy.value.text = event.target.value)
 
 export default function App() {
-  const { value, undo, redo, history, canUndo, canRedo } =
+  const { value, undo, redo, history, canUndo, canRedo, getCurrentChangeDate } =
     useSnapshot(textProxy)
 
   return (
     <div className="App">
       <h2>Editor with history</h2>
-      <small>{history.index} changes</small>
+      <div className="info">
+        <span>
+          change {history.index + 1} / {history.nodes.length}
+        </span>
+        <span>|</span>
+        <span>{getCurrentChangeDate().toISOString()}</span>
+      </div>
       <div className="editor">
         <textarea value={value.text} rows={4} onChange={update} />
       </div>

examples/editor-proxyWithHistory/src/styles.css

@@ -3,6 +3,16 @@
   text-align: center;
 }
 
+.info {
+  display: flex;
+  justify-content: center;
+  padding: 16px;
+
+  & > span {
+    margin-right: 32px;
+  }
+}
+
 .editor {
   display: flex;
   margin: 0 auto;

readme.md

@@ -314,7 +314,7 @@ For more information, check out [this guide](./docs/guides/computed-properties.m
 This is a utility function to create a proxy with snapshot history.
 
 ```js
-import { proxyWithHistory } from 'valtio/utils'
+import { proxyWithHistory } from 'valtio-history'
 
 const state = proxyWithHistory({ count: 0 })
 console.log(state.value) // ---> { count: 0 }

src/vanilla/utils.ts

@@ -4,6 +4,6 @@ export { devtools } from './utils/devtools.ts'
 export { derive, underive, unstable_deriveSubscriptions } from 'derive-valtio'
 export { addComputed_DEPRECATED as addComputed } from './utils/addComputed.ts'
 export { proxyWithComputed_DEPRECATED as proxyWithComputed } from './utils/proxyWithComputed.ts'
-export { proxyWithHistory } from './utils/proxyWithHistory.ts'
+export { proxyWithHistory_DEPRECATED as proxyWithHistory } from './utils/proxyWithHistory.ts'
 export { proxySet } from './utils/proxySet.ts'
 export { proxyMap } from './utils/proxyMap.ts'

src/vanilla/utils/proxyWithHistory.ts

@@ -53,8 +53,19 @@ const deepClone = <T>(obj: T): T => {
  * const state = proxyWithHistory({
  *   count: 1,
  * })
+ *
+ * @deprecated Please use the `valtio-history` package. eg.
+ * import { proxyWithHistory } from 'valtio-history'
  */
-export function proxyWithHistory<V>(initialValue: V, skipSubscribe = false) {
+export function proxyWithHistory_DEPRECATED<V>(
+  initialValue: V,
+  skipSubscribe = false,
+) {
+  if (import.meta.env?.MODE !== 'production') {
+    console.warn(
+      'proxyWithHistory is deprecated. Please use the "valtio-history" package; refer to the docs',
+    )
+  }
   const proxyObject = proxy({
     value: initialValue,
     history: ref({