react-state-basis 0.2.2 → 0.2.3

package/README.md

@@ -206,6 +206,23 @@ Basis performs a global audit of your state space to calculate its **Mathematica
 <br/>
 <img src="./example/screenshots/systemHealthReport.gif" width="700" alt="System Health Report Demo" />
 
+---
+---
+
+## 🔍 Case Study: Auditing a Production-Ready Admin Dashboard
+
+I ran Basis on a complex `shadcn/ui` admin template to see how it handles professional-grade code. Here is what the mathematical engine discovered:
+
+<p align="center">
+  <img src="./assets/real-world-audit.png" width="800" alt="Basis Real World Audit" />
+</p>
+
+### Key Insights from the Audit:
+*   **Double Render Detection:** Basis flagged a "Double Render Cycle" in the `use-mobile.tsx` hook. It detected that state was being manually synchronized within an effect, causing unnecessary UI churn.
+*   **Stability Verification:** The engine verified that the `Sidebar` callbacks were correctly memoized, providing a "Stable Callback" confirmation.
+*   **Valid Projections:** Complex table states (pagination, filters) were confirmed as valid mathematical projections, ensuring no redundant `useState` was used.
+
+Math reveals exactly what standard code reviews often miss: the **temporal topology** of your application.
 ---
 
 ## Roadmap

package/dist/index.d.mts

@@ -1,6 +1,8 @@
-import * as React$1 from 'react';
-import React__default, { Dispatch, SetStateAction, Reducer, DependencyList, EffectCallback, Context, ReactNode } from 'react';
-export { CSSProperties, Context, DependencyList, Dispatch, EffectCallback, FC, PropsWithChildren, ReactElement, ReactNode, Reducer, SetStateAction } from 'react';
+import * as React from 'react';
+import React__default, { ReactNode } from 'react';
+export { React };
+export { React as default };
+export { AnchorHTMLAttributes, Attributes, ButtonHTMLAttributes, CSSProperties, ChangeEvent, ComponentProps, ComponentPropsWithRef, ComponentPropsWithoutRef, ComponentType, DependencyList, DetailedHTMLProps, Dispatch, DragEvent, EffectCallback, ElementType, FC, FocusEvent, FormEvent, HTMLAttributes, HTMLProps, InputHTMLAttributes, JSX, Key, KeyboardEvent, MouseEvent, MutableRefObject, PointerEvent, PropsWithChildren, ReactElement, ReactNode, ReactPortal, Reducer, Ref, RefObject, SVGProps, SetStateAction, TouchEvent } from 'react';
 
 interface BasisConfig {
     debug: boolean;
@@ -27,22 +29,38 @@ declare const __testEngine__: {
     endEffectTracking: () => void;
 };
 
-declare function useState<T>(initialValue: T, label?: string): [T, Dispatch<SetStateAction<T>>];
-declare function useReducer<S, A, I>(reducer: Reducer<S, A>, initialArg: I & S, init?: any, label?: string): [S, Dispatch<A>];
-declare function useMemo<T>(factory: () => T, depsOrLabel?: DependencyList | string, label?: string): T;
-declare function useCallback<T extends (...args: any[]) => any>(callback: T, depsOrLabel?: DependencyList | string, label?: string): T;
-declare function useEffect(effect: EffectCallback, depsOrLabel?: DependencyList | string, label?: string): void;
-declare function useLayoutEffect(effect: EffectCallback, depsOrLabel?: DependencyList | string, label?: string): void;
-declare function useInsertionEffect(effect: EffectCallback, deps?: DependencyList, _label?: string): void;
+interface BasisProviderProps {
+    children: ReactNode;
+    debug?: boolean;
+}
+declare const BasisProvider: React__default.FC<BasisProviderProps>;
+declare const useBasisConfig: () => {
+    debug: boolean;
+};
+
+type GetReducerState<R extends React.Reducer<any, any>> = R extends React.Reducer<infer S, any> ? S : never;
+type GetReducerAction<R extends React.Reducer<any, any>> = R extends React.Reducer<any, infer A> ? A : never;
+declare function useState<S>(initialState: S | (() => S), label?: string): [S, React.Dispatch<React.SetStateAction<S>>];
+declare function useRef<T>(initialValue: T): React.RefObject<T>;
+declare function useRef<T>(initialValue: T | null): React.RefObject<T>;
+declare function useRef<T = undefined>(): React.MutableRefObject<T | undefined>;
+declare function useReducer<R extends React.Reducer<any, any>, I>(reducer: R, initialArg: I, init?: any, label?: string): [GetReducerState<R>, React.Dispatch<GetReducerAction<R>>];
+declare function useMemo<T>(factory: () => T, deps: React.DependencyList | undefined, label?: string): T;
+declare function useCallback<T extends (...args: any[]) => any>(callback: T, deps: React.DependencyList, label?: string): T;
+declare function useEffect(effect: React.EffectCallback, deps?: React.DependencyList, label?: string): void;
+declare function useLayoutEffect(effect: React.EffectCallback, deps?: React.DependencyList, label?: string): void;
 declare function useTransition(_label?: string): [boolean, (callback: () => void) => void];
 declare function useDeferredValue<T>(value: T, initialValueOrLabel?: T | string, label?: string): T;
-declare function useRef<T>(initialValue: T, _label?: string): React$1.RefObject<T>;
-declare function createContext<T>(defaultValue: T, label?: string): Context<T>;
-declare function useContext<T>(context: Context<T>): T;
-declare function useId(_label?: string): string;
-declare function useDebugValue<T>(value: T, formatter?: (value: T) => any, _label?: string): void;
-declare function useImperativeHandle<T, R extends T>(ref: React.Ref<T> | undefined, init: () => R, deps?: DependencyList, _label?: string): void;
-declare function useSyncExternalStore<Snapshot>(subscribe: (onStoreChange: () => void) => () => void, getSnapshot: () => Snapshot, getServerSnapshot?: () => Snapshot, _label?: string): Snapshot;
+declare function createContext<T>(defaultValue: T, label?: string): React.Context<T>;
+declare const useContext: typeof React.useContext;
+declare const useId: (label?: string) => string;
+declare const useDebugValue: typeof React.useDebugValue;
+declare const useImperativeHandle: typeof React.useImperativeHandle;
+declare const useInsertionEffect: typeof React.useInsertionEffect;
+declare const useSyncExternalStore: any;
+declare function use<T>(usable: React.Usable<T>): T;
+declare function useOptimistic<S, P>(passthrough: S, reducer?: (state: S, payload: P) => S, label?: string): [S, (payload: P) => void];
+declare function useActionState<State, Payload>(action: (state: State, payload: Payload) => Promise<State> | State, initialState: State, permalink?: string, label?: string): [state: State, dispatch: (payload: Payload) => void, isPending: boolean];
 declare const __test__: {
     registerVariable: (label: string) => void;
     unregisterVariable: (label: string) => void;
@@ -53,13 +71,30 @@ declare const __test__: {
     currentTickBatch: any;
 };
 
-interface BasisProviderProps {
-    children: ReactNode;
-    debug?: boolean;
-}
-declare const BasisProvider: React__default.FC<BasisProviderProps>;
-declare const useBasisConfig: () => {
-    debug: boolean;
+declare const Children: {
+    map<T, C>(children: C | readonly C[], fn: (child: C, index: number) => T): C extends null | undefined ? C : Array<Exclude<T, boolean | null | undefined>>;
+    forEach<C>(children: C | readonly C[], fn: (child: C, index: number) => void): void;
+    count(children: any): number;
+    only<C>(children: C): C extends any[] ? never : C;
+    toArray(children: React.ReactNode | React.ReactNode[]): Array<Exclude<React.ReactNode, boolean | null | undefined>>;
 };
+declare const Component: typeof React.Component;
+declare const Fragment: React.ExoticComponent<React.FragmentProps>;
+declare const Profiler: React.ExoticComponent<React.ProfilerProps>;
+declare const PureComponent: typeof React.PureComponent;
+declare const StrictMode: React.ExoticComponent<{
+    children?: React.ReactNode | undefined;
+}>;
+declare const Suspense: React.ExoticComponent<React.SuspenseProps>;
+declare const cloneElement: typeof React.cloneElement;
+declare const createRef: typeof React.createRef;
+declare const forwardRef: typeof React.forwardRef;
+declare const isValidElement: typeof React.isValidElement;
+declare const lazy: typeof React.lazy;
+declare const memo: typeof React.memo;
+declare const startTransition: typeof React.startTransition;
+declare const version: string;
+declare const createPortal: any;
+declare const flushSync: any;
 
-export { type BasisConfig, BasisProvider, __testEngine__, __test__, beginEffectTracking, config, configureBasis, createContext, currentTickBatch, endEffectTracking, history, printBasisHealthReport, recordUpdate, registerVariable, unregisterVariable, useBasisConfig, useCallback, useContext, useDebugValue, useDeferredValue, useEffect, useId, useImperativeHandle, useInsertionEffect, useLayoutEffect, useMemo, useReducer, useRef, useState, useSyncExternalStore, useTransition };
+export { BasisProvider, Children, Component, Fragment, Profiler, PureComponent, StrictMode, Suspense, __testEngine__, __test__, beginEffectTracking, cloneElement, config, configureBasis, createContext, createPortal, createRef, currentTickBatch, endEffectTracking, flushSync, forwardRef, history, isValidElement, lazy, memo, printBasisHealthReport, recordUpdate, registerVariable, startTransition, unregisterVariable, use, useActionState, useBasisConfig, useCallback, useContext, useDebugValue, useDeferredValue, useEffect, useId, useImperativeHandle, useInsertionEffect, useLayoutEffect, useMemo, useOptimistic, useReducer, useRef, useState, useSyncExternalStore, useTransition, version };

package/dist/index.d.ts

@@ -1,6 +1,8 @@
-import * as React$1 from 'react';
-import React__default, { Dispatch, SetStateAction, Reducer, DependencyList, EffectCallback, Context, ReactNode } from 'react';
-export { CSSProperties, Context, DependencyList, Dispatch, EffectCallback, FC, PropsWithChildren, ReactElement, ReactNode, Reducer, SetStateAction } from 'react';
+import * as React from 'react';
+import React__default, { ReactNode } from 'react';
+export { React };
+export { React as default };
+export { AnchorHTMLAttributes, Attributes, ButtonHTMLAttributes, CSSProperties, ChangeEvent, ComponentProps, ComponentPropsWithRef, ComponentPropsWithoutRef, ComponentType, DependencyList, DetailedHTMLProps, Dispatch, DragEvent, EffectCallback, ElementType, FC, FocusEvent, FormEvent, HTMLAttributes, HTMLProps, InputHTMLAttributes, JSX, Key, KeyboardEvent, MouseEvent, MutableRefObject, PointerEvent, PropsWithChildren, ReactElement, ReactNode, ReactPortal, Reducer, Ref, RefObject, SVGProps, SetStateAction, TouchEvent } from 'react';
 
 interface BasisConfig {
     debug: boolean;
@@ -27,22 +29,38 @@ declare const __testEngine__: {
     endEffectTracking: () => void;
 };
 
-declare function useState<T>(initialValue: T, label?: string): [T, Dispatch<SetStateAction<T>>];
-declare function useReducer<S, A, I>(reducer: Reducer<S, A>, initialArg: I & S, init?: any, label?: string): [S, Dispatch<A>];
-declare function useMemo<T>(factory: () => T, depsOrLabel?: DependencyList | string, label?: string): T;
-declare function useCallback<T extends (...args: any[]) => any>(callback: T, depsOrLabel?: DependencyList | string, label?: string): T;
-declare function useEffect(effect: EffectCallback, depsOrLabel?: DependencyList | string, label?: string): void;
-declare function useLayoutEffect(effect: EffectCallback, depsOrLabel?: DependencyList | string, label?: string): void;
-declare function useInsertionEffect(effect: EffectCallback, deps?: DependencyList, _label?: string): void;
+interface BasisProviderProps {
+    children: ReactNode;
+    debug?: boolean;
+}
+declare const BasisProvider: React__default.FC<BasisProviderProps>;
+declare const useBasisConfig: () => {
+    debug: boolean;
+};
+
+type GetReducerState<R extends React.Reducer<any, any>> = R extends React.Reducer<infer S, any> ? S : never;
+type GetReducerAction<R extends React.Reducer<any, any>> = R extends React.Reducer<any, infer A> ? A : never;
+declare function useState<S>(initialState: S | (() => S), label?: string): [S, React.Dispatch<React.SetStateAction<S>>];
+declare function useRef<T>(initialValue: T): React.RefObject<T>;
+declare function useRef<T>(initialValue: T | null): React.RefObject<T>;
+declare function useRef<T = undefined>(): React.MutableRefObject<T | undefined>;
+declare function useReducer<R extends React.Reducer<any, any>, I>(reducer: R, initialArg: I, init?: any, label?: string): [GetReducerState<R>, React.Dispatch<GetReducerAction<R>>];
+declare function useMemo<T>(factory: () => T, deps: React.DependencyList | undefined, label?: string): T;
+declare function useCallback<T extends (...args: any[]) => any>(callback: T, deps: React.DependencyList, label?: string): T;
+declare function useEffect(effect: React.EffectCallback, deps?: React.DependencyList, label?: string): void;
+declare function useLayoutEffect(effect: React.EffectCallback, deps?: React.DependencyList, label?: string): void;
 declare function useTransition(_label?: string): [boolean, (callback: () => void) => void];
 declare function useDeferredValue<T>(value: T, initialValueOrLabel?: T | string, label?: string): T;
-declare function useRef<T>(initialValue: T, _label?: string): React$1.RefObject<T>;
-declare function createContext<T>(defaultValue: T, label?: string): Context<T>;
-declare function useContext<T>(context: Context<T>): T;
-declare function useId(_label?: string): string;
-declare function useDebugValue<T>(value: T, formatter?: (value: T) => any, _label?: string): void;
-declare function useImperativeHandle<T, R extends T>(ref: React.Ref<T> | undefined, init: () => R, deps?: DependencyList, _label?: string): void;
-declare function useSyncExternalStore<Snapshot>(subscribe: (onStoreChange: () => void) => () => void, getSnapshot: () => Snapshot, getServerSnapshot?: () => Snapshot, _label?: string): Snapshot;
+declare function createContext<T>(defaultValue: T, label?: string): React.Context<T>;
+declare const useContext: typeof React.useContext;
+declare const useId: (label?: string) => string;
+declare const useDebugValue: typeof React.useDebugValue;
+declare const useImperativeHandle: typeof React.useImperativeHandle;
+declare const useInsertionEffect: typeof React.useInsertionEffect;
+declare const useSyncExternalStore: any;
+declare function use<T>(usable: React.Usable<T>): T;
+declare function useOptimistic<S, P>(passthrough: S, reducer?: (state: S, payload: P) => S, label?: string): [S, (payload: P) => void];
+declare function useActionState<State, Payload>(action: (state: State, payload: Payload) => Promise<State> | State, initialState: State, permalink?: string, label?: string): [state: State, dispatch: (payload: Payload) => void, isPending: boolean];
 declare const __test__: {
     registerVariable: (label: string) => void;
     unregisterVariable: (label: string) => void;
@@ -53,13 +71,30 @@ declare const __test__: {
     currentTickBatch: any;
 };
 
-interface BasisProviderProps {
-    children: ReactNode;
-    debug?: boolean;
-}
-declare const BasisProvider: React__default.FC<BasisProviderProps>;
-declare const useBasisConfig: () => {
-    debug: boolean;
+declare const Children: {
+    map<T, C>(children: C | readonly C[], fn: (child: C, index: number) => T): C extends null | undefined ? C : Array<Exclude<T, boolean | null | undefined>>;
+    forEach<C>(children: C | readonly C[], fn: (child: C, index: number) => void): void;
+    count(children: any): number;
+    only<C>(children: C): C extends any[] ? never : C;
+    toArray(children: React.ReactNode | React.ReactNode[]): Array<Exclude<React.ReactNode, boolean | null | undefined>>;
 };
+declare const Component: typeof React.Component;
+declare const Fragment: React.ExoticComponent<React.FragmentProps>;
+declare const Profiler: React.ExoticComponent<React.ProfilerProps>;
+declare const PureComponent: typeof React.PureComponent;
+declare const StrictMode: React.ExoticComponent<{
+    children?: React.ReactNode | undefined;
+}>;
+declare const Suspense: React.ExoticComponent<React.SuspenseProps>;
+declare const cloneElement: typeof React.cloneElement;
+declare const createRef: typeof React.createRef;
+declare const forwardRef: typeof React.forwardRef;
+declare const isValidElement: typeof React.isValidElement;
+declare const lazy: typeof React.lazy;
+declare const memo: typeof React.memo;
+declare const startTransition: typeof React.startTransition;
+declare const version: string;
+declare const createPortal: any;
+declare const flushSync: any;
 
-export { type BasisConfig, BasisProvider, __testEngine__, __test__, beginEffectTracking, config, configureBasis, createContext, currentTickBatch, endEffectTracking, history, printBasisHealthReport, recordUpdate, registerVariable, unregisterVariable, useBasisConfig, useCallback, useContext, useDebugValue, useDeferredValue, useEffect, useId, useImperativeHandle, useInsertionEffect, useLayoutEffect, useMemo, useReducer, useRef, useState, useSyncExternalStore, useTransition };
+export { BasisProvider, Children, Component, Fragment, Profiler, PureComponent, StrictMode, Suspense, __testEngine__, __test__, beginEffectTracking, cloneElement, config, configureBasis, createContext, createPortal, createRef, currentTickBatch, endEffectTracking, flushSync, forwardRef, history, isValidElement, lazy, memo, printBasisHealthReport, recordUpdate, registerVariable, startTransition, unregisterVariable, use, useActionState, useBasisConfig, useCallback, useContext, useDebugValue, useDeferredValue, useEffect, useId, useImperativeHandle, useInsertionEffect, useLayoutEffect, useMemo, useOptimistic, useReducer, useRef, useState, useSyncExternalStore, useTransition, version };