chore: consolidate new foundation and archive v1 (#1495)

v1/packages/mosaic/framework/skills/vueuse-functions/references/refWithControl.md

@@ -0,0 +1,145 @@
+---
+category: Reactivity
+alias: controlledRef
+related: computedWithControl
+---
+
+# refWithControl
+
+Fine-grained controls over ref and its reactivity.
+
+## Usage
+
+`refWithControl` uses `extendRef` to provide two extra functions `get` and `set` to have better control over when it should track/trigger the reactivity.
+
+```ts
+import { refWithControl } from '@vueuse/core';
+
+const num = refWithControl(0);
+const doubled = computed(() => num.value * 2);
+
+// just like normal ref
+num.value = 42;
+console.log(num.value); // 42
+console.log(doubled.value); // 84
+
+// set value without triggering the reactivity
+num.set(30, false);
+console.log(num.value); // 30
+console.log(doubled.value); // 84 (doesn't update)
+
+// get value without tracking the reactivity
+watchEffect(() => {
+  console.log(num.peek());
+}); // 30
+
+num.value = 50; // watch effect wouldn't be triggered since it collected nothing.
+console.log(doubled.value); // 100 (updated again since it's a reactive set)
+```
+
+### `peek`, `lay`, `untrackedGet`, `silentSet`
+
+We also provide some shorthands for doing the get/set without track/triggering the reactivity system. The following lines are equivalent.
+
+```ts
+import { refWithControl } from '@vueuse/core';
+// ---cut---
+const foo = refWithControl('foo');
+```
+
+```ts
+import { refWithControl } from '@vueuse/core';
+
+const foo = refWithControl('foo');
+// ---cut---
+// getting
+foo.get(false);
+foo.untrackedGet();
+foo.peek(); // an alias for `untrackedGet`
+```
+
+```ts
+import { refWithControl } from '@vueuse/core';
+
+const foo = refWithControl('foo');
+// ---cut---
+// setting
+foo.set('bar', false);
+foo.silentSet('bar');
+foo.lay('bar'); // an alias for `silentSet`
+```
+
+## Configurations
+
+### `onBeforeChange()`
+
+`onBeforeChange` option is offered to give control over if a new value should be accepted. For example:
+
+```ts
+import { refWithControl } from '@vueuse/core';
+// ---cut---
+const num = refWithControl(0, {
+  onBeforeChange(value, oldValue) {
+    // disallow changes larger then ±5 in one operation
+    if (Math.abs(value - oldValue) > 5) return false; // returning `false` to dismiss the change
+  },
+});
+
+num.value += 1;
+console.log(num.value); // 1
+
+num.value += 6;
+console.log(num.value); // 1 (change been dismissed)
+```
+
+### `onChanged()`
+
+`onChanged` option offers a similar functionally as Vue's `watch` but being synchronized with less overhead compared to `watch`.
+
+```ts
+import { refWithControl } from '@vueuse/core';
+// ---cut---
+const num = refWithControl(0, {
+  onChanged(value, oldValue) {
+    console.log(value);
+  },
+});
+```
+
+## Type Declarations
+
+```ts
+export interface ControlledRefOptions<T> {
+  /**
+   * Callback function before the ref changing.
+   *
+   * Returning `false` to dismiss the change.
+   */
+  onBeforeChange?: (value: T, oldValue: T) => void | boolean;
+  /**
+   * Callback function after the ref changed
+   *
+   * This happens synchronously, with less overhead compare to `watch`
+   */
+  onChanged?: (value: T, oldValue: T) => void;
+}
+/**
+ * Fine-grained controls over ref and its reactivity.
+ *
+ * @__NO_SIDE_EFFECTS__
+ */
+export declare function refWithControl<T>(
+  initial: T,
+  options?: ControlledRefOptions<T>,
+): ShallowUnwrapRef<{
+  get: (tracking?: boolean) => T;
+  set: (value: T, triggering?: boolean) => void;
+  untrackedGet: () => T;
+  silentSet: (v: T) => void;
+  peek: () => T;
+  lay: (v: T) => void;
+}> &
+  Ref<T, T>;
+/** @deprecated use `refWithControl` instead */
+export declare const controlledRef: typeof refWithControl;
+```