yummies 7.10.0 → 7.12.0

package/mobx.d.ts

@@ -5,14 +5,51 @@ type ObservableAnnotationsArray<T extends AnyObject = AnyObject> = [
     AnnotationMapEntry,
     ...(keyof T | (string & {}))[]
 ][];
+/**
+ * Applies a compact list of MobX annotations to an object using either
+ * decorator-style invocation or the annotation map form accepted by `makeObservable`.
+ *
+ * @template T Target object type.
+ * @param context Object that should become observable.
+ * @param annotationsArray Tuples of annotation followed by annotated field names.
+ * @param useDecorators Enables decorator-style application before calling `makeObservable`.
+ *
+ * @example
+ * ```ts
+ * applyObservable(store, [[observable, 'items'], [action, 'setItems']]);
+ * ```
+ *
+ * @example
+ * ```ts
+ * applyObservable(viewModel, [[computed, 'fullName']], true);
+ * ```
+ */
 declare const applyObservable: <T extends AnyObject>(context: T, annotationsArray: ObservableAnnotationsArray<T>, useDecorators?: boolean) => void;
 
 interface IEnhancedAtom<TMeta extends AnyObject = AnyObject> extends IAtom {
     meta: TMeta;
 }
 /**
- * Creates an enhanced atom with meta data
- * And bind `reportChanged` and `reportObserved` method to the atom
+ * Creates a MobX atom extended with metadata and bound reporting methods.
+ *
+ * @template TMeta Metadata object stored on the atom.
+ * @param name Atom name used by MobX for debugging.
+ * @param onBecomeObservedHandler Callback fired when the atom becomes observed.
+ * @param onBecomeUnobservedHandler Callback fired when the atom is no longer observed.
+ * @param meta Optional metadata attached to the atom.
+ * @returns Atom instance with `meta`, `reportChanged` and `reportObserved`.
+ *
+ * @example
+ * ```ts
+ * const atom = createEnhancedAtom('user-status');
+ * atom.reportChanged();
+ * ```
+ *
+ * @example
+ * ```ts
+ * const atom = createEnhancedAtom('cache', undefined, undefined, { scope: 'users' });
+ * atom.meta.scope;
+ * ```
  */
 declare const createEnhancedAtom: <TMeta extends AnyObject>(name: string, onBecomeObservedHandler?: (atom: IEnhancedAtom<TMeta>) => void, onBecomeUnobservedHandler?: (atom: IEnhancedAtom<TMeta>) => void, meta?: TMeta) => IEnhancedAtom<TMeta>;
 
@@ -43,12 +80,97 @@ interface CreateRefConfig<T = any, TMeta = AnyObject> {
     comparer?: IEqualsComparer<T | null>;
 }
 /**
- * Creates ref thing to attach HTMLElements in React and all other
+ * Creates a MobX-aware ref that behaves like a callback ref and exposes
+ * observable `current` and `meta` fields.
+ *
+ * @template T Referenced value type.
+ * @template TMeta Additional observable metadata stored on the ref.
+ * @param cfg Optional callbacks, initial value and comparer configuration.
+ * @returns Observable ref function object.
+ *
+ * @example
+ * ```ts
+ * const inputRef = createRef<HTMLInputElement>();
+ * inputRef.set(document.createElement('input'));
+ * ```
+ *
+ * @example
+ * ```ts
+ * const ref = createRef<number>();
+ * ref(3);
+ * ref.current; // 3
+ * ```
+ *
+ * @example
+ * ```ts
+ * const nodeRef = createRef({
+ *   onUnset: () => console.log('detached'),
+ *   meta: { mounted: false },
+ * });
+ * ```
  */
 declare const createRef: <T = any, TMeta = AnyObject>(cfg?: CreateRefConfig<T, TMeta>) => Ref<T, TMeta>;
+/**
+ * Checks whether the provided value is a ref created by `createRef`.
+ *
+ * @template T Referenced value type.
+ * @template TMeta Ref metadata type.
+ * @param value Value to inspect.
+ * @returns `true` when the value is a ref-like function with `current`.
+ *
+ * @example
+ * ```ts
+ * const ref = createRef<number>();
+ * isRef(ref); // true
+ * ```
+ *
+ * @example
+ * ```ts
+ * isRef({ current: 1 }); // false
+ * ```
+ */
 declare const isRef: <T, TMeta = any>(value: T | Ref<T, TMeta>) => value is Ref<T, TMeta>;
+/**
+ * Normalizes a plain value or an existing ref into a `Ref` instance.
+ *
+ * @template T Referenced value type.
+ * @template TMeta Ref metadata type.
+ * @param value Existing ref or initial plain value.
+ * @param cfg Optional ref configuration applied when a new ref is created.
+ * @returns Existing ref or a newly created ref initialized with `value`.
+ *
+ * @example
+ * ```ts
+ * const ref = toRef(document.body);
+ * ref.current === document.body;
+ * ```
+ *
+ * @example
+ * ```ts
+ * const existingRef = createRef<number>();
+ * const sameRef = toRef(existingRef);
+ * ```
+ */
 declare const toRef: <T, TMeta = any>(value: T | Ref<T, TMeta>, cfg?: Omit<CreateRefConfig<T, TMeta>, "initial">) => Ref<T, TMeta>;
 
+/**
+ * Wraps a plain object into a deeply observable structure and allows
+ * patch-like updates while preserving nested observable references where possible.
+ *
+ * @template TData Observable object shape.
+ *
+ * @example
+ * ```ts
+ * const state = new DeepObservableStruct({ user: { name: 'Ann' } });
+ * state.set({ user: { name: 'Bob' } });
+ * ```
+ *
+ * @example
+ * ```ts
+ * const state = new DeepObservableStruct({ filters: { active: true } });
+ * state.set({ filters: { active: false, archived: true } });
+ * ```
+ */
 declare class DeepObservableStruct<TData extends AnyObject> {
     data: TData;
     constructor(data: TData);
@@ -56,13 +178,57 @@ declare class DeepObservableStruct<TData extends AnyObject> {
 }
 
 type ObservableObjectAdministration = Parameters<Exclude<AnnotationMapEntry, boolean>['make_']>[0];
+/**
+ * Returns the internal MobX administration object associated with an observable target.
+ *
+ * @param context Observable object instance.
+ * @returns MobX administration internals stored under `$mobx`.
+ *
+ * @example
+ * ```ts
+ * const admin = getMobxAdministration(store);
+ * admin.name_;
+ * ```
+ *
+ * @example
+ * ```ts
+ * const values = getMobxAdministration(formState).values_;
+ * ```
+ */
 declare const getMobxAdministration: (context: AnyObject) => ObservableObjectAdministration;
 
 /**
- * When ONE OF the properties is becomes observed then `onStart` function is called.
- * WHen ALL properties are unobserved then `onEnd` function is called with the `metaData` that was returned by `onStart`.
+ * Starts side effects only while one or more MobX observables are being observed.
+ *
+ * When the first property becomes observed, `onStart` is called. When all tracked
+ * properties become unobserved, `onEnd` is called with the value returned by
+ * `onStart`. Cleanup can be delayed via `endDelay`.
+ *
+ * It uses MobX `onBecomeObserved` and `onBecomeUnobserved` hooks to perform
+ * lazy subscription management.
+ *
+ * @template TMetaData Data returned from `onStart` and forwarded to `onEnd`.
+ * @param config Configuration for tracked properties and lifecycle callbacks.
+ * @returns Cleanup function that clears the tracked state and runs `onEnd`.
+ *
+ * @example
+ * ```ts
+ * const stop = lazyObserve({
+ *   context: store,
+ *   property: 'items',
+ *   onStart: () => api.subscribe(),
+ *   onEnd: (subscription) => subscription.unsubscribe(),
+ * });
+ * ```
  *
- * It uses `onBecomeObserved` and `onBecomeUnobserved` mobx hooks to perform lazy observation.
+ * @example
+ * ```ts
+ * lazyObserve({
+ *   property: [boxA, boxB],
+ *   onStart: () => console.log('observed'),
+ *   endDelay: 300,
+ * });
+ * ```
  */
 declare const lazyObserve: <TMetaData = void>({ context, property, onStart, onEnd, endDelay, }: {
     context?: any;