storion 0.2.3 → 0.4.0

package/dist/react/withStore.d.ts

@@ -0,0 +1,140 @@
+import { ReactNode, FC, Ref, ForwardRefRenderFunction, ForwardRefExoticComponent, RefAttributes } from 'react';
+import { Equality, SelectorContext } from '../types';
+
+export interface WithStoreOptions<TOutput extends object> {
+    displayName?: string;
+    /**
+     * Custom equality function for comparing hook output.
+     * Controls when the memoized render function re-renders.
+     *
+     * Note: To control input props equality, wrap the final component with memo().
+     */
+    equality?: Equality<TOutput>;
+}
+/**
+ * Hook function that receives SelectorContext and props.
+ *
+ * Can use:
+ * - Store access via ctx.get()
+ * - React hooks (useState, useEffect, useMemo, etc.)
+ * - Return any values including functions
+ *
+ * The hook is called during render phase, so all React hooks rules apply.
+ *
+ * ⚠️ Limitation: Cannot use React hooks inside pick() callbacks:
+ * ```tsx
+ * // ❌ DON'T: React hooks inside pick callback
+ * const value = ctx.pick(store, state => {
+ *   const [x] = useState(0); // ❌ Error: Invalid hook call
+ *   return state.value + x;
+ * });
+ *
+ * // ✅ DO: React hooks outside pick
+ * const [x] = useState(0);
+ * const value = ctx.pick(store, state => state.value + x);
+ * ```
+ *
+ * @example
+ * ```tsx
+ * const Component = withStore(
+ *   (ctx, { userId }) => {
+ *     const [user] = ctx.get(userStore);
+ *     const [count, setCount] = useState(0);
+ *
+ *     return {
+ *       userName: user.name,
+ *       count,
+ *       increment: () => setCount(c => c + 1), // ✅ Can return functions
+ *     };
+ *   },
+ *   ({ userName, count, increment }) => (
+ *     <div onClick={increment}>{userName}: {count}</div>
+ *   )
+ * );
+ * ```
+ */
+export type WithStoreHook<TInput extends object, TOutput extends object> = (context: SelectorContext, props: TInput) => TOutput;
+/**
+ * Render function without ref support.
+ */
+export type WithStoreRender<TOutput extends object> = (props: TOutput) => ReactNode;
+/**
+ * Render function with ref support.
+ */
+export type WithStoreRenderWithRef<TOutput extends object, TRef = unknown> = (props: TOutput, ref: Ref<TRef>) => ReactNode;
+/**
+ * Testing utilities exposed on components created with withStore(hook, render)
+ */
+export interface WithStoreTestUtils<TInput extends object, TOutput extends object> {
+    /**
+     * The hook function for testing.
+     * Call this to test the hook logic independently.
+     *
+     * @example
+     * ```ts
+     * const result = MyComponent.use(mockCtx, { userId: '123' });
+     * expect(result.name).toBe('John');
+     * ```
+     */
+    use: WithStoreHook<TInput, TOutput>;
+    /**
+     * The render function for testing.
+     * Call this to test the render output independently.
+     *
+     * @example
+     * ```tsx
+     * const element = MyComponent.render({ name: 'John' });
+     * // Or with testing-library:
+     * render(MyComponent.render({ name: 'John' }));
+     * ```
+     */
+    render: (props: TOutput) => ReactNode;
+}
+/**
+ * Testing utilities exposed on HOCs created with withStore(hook)
+ */
+export interface WithStoreHOCTestUtils<TInput extends object, TOutput extends object> {
+    /**
+     * The hook function for testing.
+     * Call this to test the hook logic independently.
+     *
+     * @example
+     * ```ts
+     * const result = withUserData.use(mockCtx, { userId: '123' });
+     * expect(result.name).toBe('John');
+     * ```
+     */
+    use: WithStoreHook<TInput, TOutput>;
+}
+/**
+ * Component type with testing utilities (no ref)
+ */
+export type WithStoreComponent<TInput extends object, TOutput extends object> = FC<TInput> & WithStoreTestUtils<TInput, TOutput>;
+/**
+ * Component type with testing utilities (with ref)
+ */
+export type WithStoreComponentWithRef<TInput extends object, TOutput extends object, TRef = unknown> = ForwardRefExoticComponent<TInput & RefAttributes<TRef>> & WithStoreTestUtils<TInput, TOutput>;
+/**
+ * HOC type with testing utilities
+ */
+export type WithStoreHOC<TInput extends object, TOutput extends object> = {
+    (component: FC<TOutput>): FC<TInput>;
+    <TRef = unknown>(component: ForwardRefRenderFunction<TRef, TOutput>): ForwardRefExoticComponent<TInput & RefAttributes<TRef>>;
+} & WithStoreHOCTestUtils<TInput, TOutput>;
+/**
+ * Direct mode: Create component with hook and render function (no ref).
+ * Returns component with `use` and `render` properties for testing.
+ */
+export declare function withStore<TInput extends object, TOutput extends object>(hook: WithStoreHook<TInput, TOutput>, render: WithStoreRender<TOutput>, options?: WithStoreOptions<TOutput>): WithStoreComponent<TInput, TOutput>;
+/**
+ * Direct mode: Create component with hook and render function (with ref).
+ * Automatically detected when render function has 2 parameters.
+ * Returns component with `use` and `render` properties for testing.
+ */
+export declare function withStore<TInput extends object, TOutput extends object, TRef = unknown>(hook: WithStoreHook<TInput, TOutput>, render: WithStoreRenderWithRef<TOutput, TRef>, options?: WithStoreOptions<TOutput>): WithStoreComponentWithRef<TInput, TOutput, TRef>;
+/**
+ * HOC mode: Create HOC that transforms props using hook.
+ * Returns a function that accepts a component, with `use` property for testing.
+ */
+export declare function withStore<TInput extends object, TOutput extends object>(hook: WithStoreHook<TInput, TOutput>, options?: WithStoreOptions<TOutput>): WithStoreHOC<TInput, TOutput>;
+//# sourceMappingURL=withStore.d.ts.map

package/dist/react/withStore.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"withStore.d.ts","sourceRoot":"","sources":["../../src/react/withStore.tsx"],"names":[],"mappings":"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"}