react-container-kit 1.0.0

package/README.md

@@ -0,0 +1,252 @@
+# react-container-kit
+
+TypeScript utilities for the React container pattern — named containers, provider composition, and type helpers. Built on top of [`unstated-next`](https://github.com/jamiebuilds/unstated-next).
+
+## Installation
+
+```sh
+yarn add react-container-kit unstated-next react
+```
+
+## API
+
+### `createContainer` (re-export)
+
+Re-exported directly from `unstated-next`. Create a container from a custom hook:
+
+```ts
+import { createContainer } from 'react-container-kit';
+
+interface Profile { firstName: string; lastName: string; }
+
+function useProfileInternal(initialState?: Profile) {
+  const [profile, setProfile] = useState<Profile>(initialState ?? { firstName: '', lastName: '' });
+  return { profile, setProfile };
+}
+
+const container = createContainer(useProfileInternal);
+export const ProfileProvider = container.Provider;
+export const useProfile = container.useContainer;
+```
+
+### `createNamedContainer`
+
+Like `createContainer`, but sets a `displayName` on the Provider for better React DevTools readability. Without this, every container's provider shows as `"Provider"` in the component tree.
+
+```ts
+import { createNamedContainer } from 'react-container-kit';
+
+const { Provider: ProfileProvider, useContainer: useProfile } =
+  createNamedContainer('Profile', useProfileInternal);
+// ProfileProvider now shows as "ProfileProvider" in React DevTools
+```
+
+### `composeProviders`
+
+Composes multiple provider components into a single wrapper, eliminating deeply-nested JSX. Providers are applied outermost-first (left to right).
+
+```tsx
+import { composeProviders } from 'react-container-kit';
+
+// Before — deeply nested:
+// <SnackbarProvider>
+//   <ThemeProvider>
+//     <RouterProvider>
+//       {children}
+//     </RouterProvider>
+//   </ThemeProvider>
+// </SnackbarProvider>
+
+const AppProviders = composeProviders(SnackbarProvider, ThemeProvider, RouterProvider);
+
+function App() {
+  return <AppProviders><Routes /></AppProviders>;
+}
+```
+
+> **Note:** `composeProviders` is suited for providers that don't require dynamic props at render time. For providers that need `initialState` computed from fetched data, continue to use JSX directly.
+
+### Type utilities
+
+```ts
+import type { ContainerValue, ContainerState, TypedContainer } from 'react-container-kit';
+
+const ProfileContainer = createContainer(useProfileInternal);
+
+// Extract the hook's return type
+type ProfileValue = ContainerValue<typeof ProfileContainer>;
+// -> { profile: Profile; setProfile: Dispatch<SetStateAction<Profile>> }
+
+// Extract the initialState type
+type ProfileInitialState = ContainerState<typeof ProfileContainer>;
+// -> Profile
+
+// Type a variable that holds any container
+function logContainer(c: TypedContainer<unknown>) { ... }
+```
+
+## Patterns from the field
+
+Based on real-world usage, the recommended pattern for a container module is:
+
+<!-- markdownlint-disable-next-line MD033 -->
+<details>
+  <!-- markdownlint-disable-next-line MD033 -->
+  <summary>See types defined for <code>User</code> example below.</summary>
+
+For the purposes of this example the types are deifind in one file shown below.
+
+In a production ready application these types would be defined `common`/`shared` folders and `Locale` would be in an `i18n` related file. The files don't _only_ relate to the `User` interfaceb but for the purposes of this example they do.
+
+```ts
+// src/core/types/user.ts
+
+export interface Media {
+  id?: string;
+  url: string;
+}
+
+export enum UserState {
+  DELETED = 'DELETED',
+  BLOCKED = 'BLOCKED',
+  INVITED = 'INVITED',
+  ACTIVE = 'ACTIVE',
+}
+
+export enum UserType {
+  USER = 'USER',
+  ADMIN = 'ADMIN',
+}
+
+export interface User {
+  id: string;
+  firstName?: string;
+  lastName?: string;
+  type: UserType;
+  state: UserState;
+  email: string;
+  phone?: string;
+  profilePicture?: Media;
+}
+```
+
+</details>
+
+```ts
+// src/core/data/profile/index.ts
+import { useState } from 'react';
+import { createNamedContainer } from 'react-container-kit';
+import type { User } from 'core/types/user';
+
+export type ProfileDraft = Pick<User, 'firstName' | 'lastName' | 'phone' | 'language'>;
+
+const defaultUser: User = {
+  id: '',
+  firstName: '',
+  lastName: '',
+  email: '',
+  phone: '',
+  type: UserType.USER,
+  state: UserState.ACTIVE,
+};
+
+interface UseProfile {
+  profile: User;
+  update: (draft: ProfileDraft) => Promise<void>;
+}
+
+function useProfileInternal(initialState?: User): UseProfile {
+  const [profile, setProfile] = useState<User>(initialState || defaultUser);
+
+  async function update(draft: ProfileDraft) {
+    try {
+      const res = await updateProfile(draft);
+      setProfile(res);
+      return res;
+    } catch (e) {
+      console.error(e);
+    }
+
+    return undefined;
+  }
+
+  return { profile, update };
+}
+
+const { Provider: ProfileProvider, useContainer: useProfile } =
+  createNamedContainer('Profile', useProfileInternal);
+
+export { ProfileProvider };
+export default useProfile;
+```
+
+## In depth - When and why to use this package
+
+### `createNamedContainer`
+
+React DevTools identifies components in the tree by their `displayName`. Without it, every container's provider renders as the generic label `"Provider"` — in an app with several containers, the component tree becomes a wall of identical entries that tells you nothing about which context is which.
+
+`createNamedContainer` is a drop-in replacement for `createContainer` that accepts a name as its first argument and uses it to label the provider in DevTools. Pass `'Profile'` and the provider appears as `"ProfileProvider"`, matching the naming convention used by libraries like React Router and React Query. The returned container is otherwise identical in shape: the same `{ Provider, useContainer }` pair, the same TypeScript generics, the same `initialState` support.
+
+The name also surfaces in error messages. When `useContainer` is called outside its provider, React includes the component name in the error, so `"ProfileProvider"` in the stack trace points you directly to the missing wrapper rather than leaving you to work out which of your many `"Provider"` components is absent.
+
+Use `createNamedContainer` by default for all containers — there is no downside, and the DevTools clarity pays off immediately once your component tree grows beyond a handful of providers.
+
+### `composeProviders`
+
+As an application grows, it is common for many providers to wrap the same subtree. Three containers already requires three levels of JSX nesting; a real app with auth, theming, routing, snackbars, and feature flags can easily reach ten. This nesting is structural boilerplate — it adds indentation and diff noise without conveying any intent.
+
+`composeProviders(...providers)` collapses any number of provider components into a single wrapper. The order is outermost-first, reading left to right: `composeProviders(A, B, C)` is equivalent to `<A><B><C>{children}</C></B></A>`. The resulting component is assigned a `displayName` derived from its members, so DevTools shows the composition rather than hiding it.
+
+The constraint to keep in mind: `composeProviders` renders each provider with only `children` — no other props. It is the right tool for providers that are self-contained and initialise from module-level config or internal defaults (themes, routing, snackbars, analytics). For providers that need `initialState` derived from runtime data — for example, seeding a user container after an auth response — keep those in JSX where you can pass the prop directly. In practice, one or two dynamic providers in JSX alongside a single `AppProviders = composeProviders(...)` is the common pattern.
+
+### Type utilities
+
+**`ContainerValue<C>`** extracts the return type of a container's `useContainer` — the value your hook hands to consuming components. This lets you name and reuse that type across your codebase without importing or re-declaring the hook. It is the canonical way to derive types from a container while keeping its internals encapsulated.
+
+```ts
+type ProfileValue = ContainerValue<typeof ProfileContainer>;
+// -> { profile: Profile; setProfile: Dispatch<SetStateAction<Profile>> }
+```
+
+**`ContainerState<C>`** extracts the `initialState` prop type from a container's `Provider`. Useful when writing test helpers or factory functions that need to accept or pass `initialState` without reaching into the container's hook directly.
+
+```ts
+type ProfileInitialState = ContainerState<typeof ProfileContainer>;
+// -> Profile
+```
+
+**`TypedContainer<Value, State>`** is a structural interface describing the shape every container conforms to: a `Provider` component and a `useContainer` hook. Use it to type function parameters or variables that should accept any container without coupling to a specific one.
+
+```ts
+function wrapContainer<V>(container: TypedContainer<V>) { ... }
+```
+
+**`AnyProvider<P>`** types any React component that accepts `children` plus any additional props `P`. Useful when building utilities that work with arbitrary provider components, regardless of their own prop requirements.
+
+## Tests
+
+The test suite uses [Vitest](https://vitest.dev/) with [React Testing Library](https://testing-library.com/docs/react-testing-library/intro/) and [happy-dom](https://github.com/capricorn86/happy-dom) for the DOM environment. Compile-time type assertions are validated separately with `tsc`.
+
+Run the suite:
+
+```sh
+yarn test              # vitest run (all runtime tests)
+yarn test:types        # tsc --noEmit on *.test-d.ts files
+yarn test:coverage     # vitest with v8 coverage
+```
+
+### Test files
+
+| File | Description | Tests | Coverage |
+|---|---|---|---|
+| `__tests__/create-named-container.test.ts` | Return shape, `displayName` assignment, `useContainer` integration, container independence | 14 | 100% |
+| `__tests__/compose-providers.test.ts` | Return value, provider ordering, context chaining, children rendering, edge cases | 18 | 100% |
+| `__tests__/index.test.ts` | Public API export presence and basic callability | 6 | — |
+| `__tests__/types.test-d.ts` | Compile-time assertions for `ContainerValue`, `ContainerState`, `TypedContainer`, `AnyProvider` | 21 | — |
+
+**Total: 38 runtime tests passing · 100% statement/branch/function/line coverage on runtime source**
+
+## License
+
+MIT

package/dist/index.d.mts

@@ -0,0 +1,103 @@
+import * as unstated_next from 'unstated-next';
+export { Container, createContainer } from 'unstated-next';
+import { ComponentType, ReactNode } from 'react';
+
+/**
+ * Creates an unstated-next container and sets a displayName on the Provider
+ * for improved React DevTools readability.
+ *
+ * Without a displayName, every container's Provider appears as "Provider" in
+ * the React component tree. This wrapper names it "<name>Provider" so that
+ * e.g. `createNamedContainer('Profile', useProfile)` shows as "ProfileProvider"
+ * in DevTools.
+ *
+ * @example
+ * // Instead of:
+ * const container = createContainer(useProfile);
+ * export const ProfileProvider = container.Provider; // shows as "Provider" in DevTools
+ * export const useProfile = container.useContainer;
+ *
+ * // Use:
+ * const { Provider: ProfileProvider, useContainer: useProfile } =
+ *   createNamedContainer('Profile', useProfile);
+ * // ProfileProvider now shows as "ProfileProvider" in DevTools
+ */
+declare function createNamedContainer<Value, State = void>(name: string, useHook: (initialState?: State) => Value): unstated_next.Container<Value, State>;
+
+/**
+ * Any React component that accepts children and optional additional props.
+ */
+type AnyProvider<P extends Record<string, unknown> = Record<string, unknown>> = ComponentType<P & {
+    children?: ReactNode;
+}>;
+/**
+ * Composes multiple provider components into a single wrapper component.
+ * Providers are applied outermost-first (left to right in the argument list).
+ *
+ * This eliminates the deeply-nested JSX pattern common when multiple
+ * unstated-next containers need to wrap the same subtree.
+ *
+ * @example
+ * // Before: deeply nested JSX
+ * <SnackbarProvider>
+ *   <ProfileProvider initialState={profile}>
+ *     <OrganizationProvider initialState={org}>
+ *       {children}
+ *     </OrganizationProvider>
+ *   </ProfileProvider>
+ * </SnackbarProvider>
+ *
+ * // After: compose providers without dynamic props
+ * const AppProviders = composeProviders(
+ *   SnackbarProvider,
+ *   ThemeProvider,
+ *   RouterProvider,
+ * );
+ * // <AppProviders>{children}</AppProviders>
+ */
+declare function composeProviders(...providers: ComponentType<{
+    children?: ReactNode;
+}>[]): ComponentType<{
+    children?: ReactNode;
+}>;
+
+/**
+ * Extracts the value (return type of useContainer) from a container.
+ *
+ * @example
+ * const SnackbarContainer = createContainer(useSnackbar);
+ * type SnackbarValue = ContainerValue<typeof SnackbarContainer>;
+ * // -> [Queue, SnackbarState]
+ */
+type ContainerValue<C> = C extends {
+    useContainer: () => infer V;
+} ? V : never;
+/**
+ * Extracts the initialState type from a container's Provider.
+ *
+ * @example
+ * const ProfileContainer = createContainer(useProfile);
+ * type ProfileState = ContainerState<typeof ProfileContainer>;
+ * // -> User
+ */
+type ContainerState<C> = C extends {
+    Provider: ComponentType<infer P>;
+} ? P extends {
+    initialState?: infer S;
+} ? S : never : never;
+/**
+ * A fully-typed container shape returned by createContainer.
+ * Useful for typing variables that hold any container.
+ *
+ * @example
+ * function wrapContainer<V, S>(container: TypedContainer<V, S>) { ... }
+ */
+interface TypedContainer<Value, State = void> {
+    Provider: ComponentType<{
+        initialState?: State;
+        children: ReactNode;
+    }>;
+    useContainer: () => Value;
+}
+
+export { type AnyProvider, type ContainerState, type ContainerValue, type TypedContainer, composeProviders, createNamedContainer };

package/dist/index.d.ts

@@ -0,0 +1,103 @@
+import * as unstated_next from 'unstated-next';
+export { Container, createContainer } from 'unstated-next';
+import { ComponentType, ReactNode } from 'react';
+
+/**
+ * Creates an unstated-next container and sets a displayName on the Provider
+ * for improved React DevTools readability.
+ *
+ * Without a displayName, every container's Provider appears as "Provider" in
+ * the React component tree. This wrapper names it "<name>Provider" so that
+ * e.g. `createNamedContainer('Profile', useProfile)` shows as "ProfileProvider"
+ * in DevTools.
+ *
+ * @example
+ * // Instead of:
+ * const container = createContainer(useProfile);
+ * export const ProfileProvider = container.Provider; // shows as "Provider" in DevTools
+ * export const useProfile = container.useContainer;
+ *
+ * // Use:
+ * const { Provider: ProfileProvider, useContainer: useProfile } =
+ *   createNamedContainer('Profile', useProfile);
+ * // ProfileProvider now shows as "ProfileProvider" in DevTools
+ */
+declare function createNamedContainer<Value, State = void>(name: string, useHook: (initialState?: State) => Value): unstated_next.Container<Value, State>;
+
+/**
+ * Any React component that accepts children and optional additional props.
+ */
+type AnyProvider<P extends Record<string, unknown> = Record<string, unknown>> = ComponentType<P & {
+    children?: ReactNode;
+}>;
+/**
+ * Composes multiple provider components into a single wrapper component.
+ * Providers are applied outermost-first (left to right in the argument list).
+ *
+ * This eliminates the deeply-nested JSX pattern common when multiple
+ * unstated-next containers need to wrap the same subtree.
+ *
+ * @example
+ * // Before: deeply nested JSX
+ * <SnackbarProvider>
+ *   <ProfileProvider initialState={profile}>
+ *     <OrganizationProvider initialState={org}>
+ *       {children}
+ *     </OrganizationProvider>
+ *   </ProfileProvider>
+ * </SnackbarProvider>
+ *
+ * // After: compose providers without dynamic props
+ * const AppProviders = composeProviders(
+ *   SnackbarProvider,
+ *   ThemeProvider,
+ *   RouterProvider,
+ * );
+ * // <AppProviders>{children}</AppProviders>
+ */
+declare function composeProviders(...providers: ComponentType<{
+    children?: ReactNode;
+}>[]): ComponentType<{
+    children?: ReactNode;
+}>;
+
+/**
+ * Extracts the value (return type of useContainer) from a container.
+ *
+ * @example
+ * const SnackbarContainer = createContainer(useSnackbar);
+ * type SnackbarValue = ContainerValue<typeof SnackbarContainer>;
+ * // -> [Queue, SnackbarState]
+ */
+type ContainerValue<C> = C extends {
+    useContainer: () => infer V;
+} ? V : never;
+/**
+ * Extracts the initialState type from a container's Provider.
+ *
+ * @example
+ * const ProfileContainer = createContainer(useProfile);
+ * type ProfileState = ContainerState<typeof ProfileContainer>;
+ * // -> User
+ */
+type ContainerState<C> = C extends {
+    Provider: ComponentType<infer P>;
+} ? P extends {
+    initialState?: infer S;
+} ? S : never : never;
+/**
+ * A fully-typed container shape returned by createContainer.
+ * Useful for typing variables that hold any container.
+ *
+ * @example
+ * function wrapContainer<V, S>(container: TypedContainer<V, S>) { ... }
+ */
+interface TypedContainer<Value, State = void> {
+    Provider: ComponentType<{
+        initialState?: State;
+        children: ReactNode;
+    }>;
+    useContainer: () => Value;
+}
+
+export { type AnyProvider, type ContainerState, type ContainerValue, type TypedContainer, composeProviders, createNamedContainer };

package/dist/index.js

@@ -0,0 +1,56 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  composeProviders: () => composeProviders,
+  createContainer: () => import_unstated_next2.createContainer,
+  createNamedContainer: () => createNamedContainer
+});
+module.exports = __toCommonJS(index_exports);
+var import_unstated_next2 = require("unstated-next");
+
+// src/create-named-container.ts
+var import_unstated_next = require("unstated-next");
+function createNamedContainer(name, useHook) {
+  const container = (0, import_unstated_next.createContainer)(useHook);
+  container.Provider.displayName = `${name}Provider`;
+  return container;
+}
+
+// src/compose-providers.ts
+var import_react = require("react");
+function composeProviders(...providers) {
+  function ComposedProviders({ children }) {
+    return providers.reduceRight(
+      (child, Provider) => (0, import_react.createElement)(Provider, null, child),
+      children
+    );
+  }
+  ComposedProviders.displayName = `ComposedProviders(${providers.map((p) => p.displayName || p.name || "Unknown").join(", ")})`;
+  return ComposedProviders;
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  composeProviders,
+  createContainer,
+  createNamedContainer
+});
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts","../src/create-named-container.ts","../src/compose-providers.ts"],"sourcesContent":["// Re-export the core unstated-next API so consumers only need this package\nexport { createContainer } from 'unstated-next';\nexport type { Container } from 'unstated-next';\n\n// Enhanced container factory with React DevTools displayName support\nexport { createNamedContainer } from './create-named-container';\n\n// Provider composition utility\nexport { composeProviders } from './compose-providers';\nexport type { AnyProvider } from './compose-providers';\n\n// TypeScript utility types for working with containers\nexport type { ContainerValue, ContainerState, TypedContainer } from './types';\n","import { createContainer } from 'unstated-next';\n\n/**\n * Creates an unstated-next container and sets a displayName on the Provider\n * for improved React DevTools readability.\n *\n * Without a displayName, every container's Provider appears as \"Provider\" in\n * the React component tree. This wrapper names it \"<name>Provider\" so that\n * e.g. `createNamedContainer('Profile', useProfile)` shows as \"ProfileProvider\"\n * in DevTools.\n *\n * @example\n * // Instead of:\n * const container = createContainer(useProfile);\n * export const ProfileProvider = container.Provider; // shows as \"Provider\" in DevTools\n * export const useProfile = container.useContainer;\n *\n * // Use:\n * const { Provider: ProfileProvider, useContainer: useProfile } =\n *   createNamedContainer('Profile', useProfile);\n * // ProfileProvider now shows as \"ProfileProvider\" in DevTools\n */\nexport function createNamedContainer<Value, State = void>(\n  name: string,\n  useHook: (initialState?: State) => Value,\n) {\n  const container = createContainer<Value, State>(useHook);\n  container.Provider.displayName = `${name}Provider`;\n  return container;\n}\n","import { createElement, type ComponentType, type ReactElement, type ReactNode } from 'react';\n\n/**\n * Any React component that accepts children and optional additional props.\n */\nexport type AnyProvider<P extends Record<string, unknown> = Record<string, unknown>> =\n  ComponentType<P & { children?: ReactNode }>;\n\n/**\n * Composes multiple provider components into a single wrapper component.\n * Providers are applied outermost-first (left to right in the argument list).\n *\n * This eliminates the deeply-nested JSX pattern common when multiple\n * unstated-next containers need to wrap the same subtree.\n *\n * @example\n * // Before: deeply nested JSX\n * <SnackbarProvider>\n *   <ProfileProvider initialState={profile}>\n *     <OrganizationProvider initialState={org}>\n *       {children}\n *     </OrganizationProvider>\n *   </ProfileProvider>\n * </SnackbarProvider>\n *\n * // After: compose providers without dynamic props\n * const AppProviders = composeProviders(\n *   SnackbarProvider,\n *   ThemeProvider,\n *   RouterProvider,\n * );\n * // <AppProviders>{children}</AppProviders>\n */\nexport function composeProviders(\n  ...providers: ComponentType<{ children?: ReactNode }>[]\n): ComponentType<{ children?: ReactNode }> {\n  function ComposedProviders({ children }: { children?: ReactNode }): ReactElement {\n    return providers.reduceRight<ReactElement>(\n      (child, Provider) => createElement(Provider, null, child),\n      children as ReactElement,\n    );\n  }\n\n  ComposedProviders.displayName = `ComposedProviders(${providers\n    .map((p) => p.displayName || p.name || 'Unknown')\n    .join(', ')})`;\n\n  return ComposedProviders;\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AACA,IAAAA,wBAAgC;;;ACDhC,2BAAgC;AAsBzB,SAAS,qBACd,MACA,SACA;AACA,QAAM,gBAAY,sCAA8B,OAAO;AACvD,YAAU,SAAS,cAAc,GAAG,IAAI;AACxC,SAAO;AACT;;;AC7BA,mBAAqF;AAiC9E,SAAS,oBACX,WACsC;AACzC,WAAS,kBAAkB,EAAE,SAAS,GAA2C;AAC/E,WAAO,UAAU;AAAA,MACf,CAAC,OAAO,iBAAa,4BAAc,UAAU,MAAM,KAAK;AAAA,MACxD;AAAA,IACF;AAAA,EACF;AAEA,oBAAkB,cAAc,qBAAqB,UAClD,IAAI,CAAC,MAAM,EAAE,eAAe,EAAE,QAAQ,SAAS,EAC/C,KAAK,IAAI,CAAC;AAEb,SAAO;AACT;","names":["import_unstated_next"]}

package/dist/index.mjs

@@ -0,0 +1,29 @@
+// src/index.ts
+import { createContainer as createContainer2 } from "unstated-next";
+
+// src/create-named-container.ts
+import { createContainer } from "unstated-next";
+function createNamedContainer(name, useHook) {
+  const container = createContainer(useHook);
+  container.Provider.displayName = `${name}Provider`;
+  return container;
+}
+
+// src/compose-providers.ts
+import { createElement } from "react";
+function composeProviders(...providers) {
+  function ComposedProviders({ children }) {
+    return providers.reduceRight(
+      (child, Provider) => createElement(Provider, null, child),
+      children
+    );
+  }
+  ComposedProviders.displayName = `ComposedProviders(${providers.map((p) => p.displayName || p.name || "Unknown").join(", ")})`;
+  return ComposedProviders;
+}
+export {
+  composeProviders,
+  createContainer2 as createContainer,
+  createNamedContainer
+};
+//# sourceMappingURL=index.mjs.map

package/dist/index.mjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts","../src/create-named-container.ts","../src/compose-providers.ts"],"sourcesContent":["// Re-export the core unstated-next API so consumers only need this package\nexport { createContainer } from 'unstated-next';\nexport type { Container } from 'unstated-next';\n\n// Enhanced container factory with React DevTools displayName support\nexport { createNamedContainer } from './create-named-container';\n\n// Provider composition utility\nexport { composeProviders } from './compose-providers';\nexport type { AnyProvider } from './compose-providers';\n\n// TypeScript utility types for working with containers\nexport type { ContainerValue, ContainerState, TypedContainer } from './types';\n","import { createContainer } from 'unstated-next';\n\n/**\n * Creates an unstated-next container and sets a displayName on the Provider\n * for improved React DevTools readability.\n *\n * Without a displayName, every container's Provider appears as \"Provider\" in\n * the React component tree. This wrapper names it \"<name>Provider\" so that\n * e.g. `createNamedContainer('Profile', useProfile)` shows as \"ProfileProvider\"\n * in DevTools.\n *\n * @example\n * // Instead of:\n * const container = createContainer(useProfile);\n * export const ProfileProvider = container.Provider; // shows as \"Provider\" in DevTools\n * export const useProfile = container.useContainer;\n *\n * // Use:\n * const { Provider: ProfileProvider, useContainer: useProfile } =\n *   createNamedContainer('Profile', useProfile);\n * // ProfileProvider now shows as \"ProfileProvider\" in DevTools\n */\nexport function createNamedContainer<Value, State = void>(\n  name: string,\n  useHook: (initialState?: State) => Value,\n) {\n  const container = createContainer<Value, State>(useHook);\n  container.Provider.displayName = `${name}Provider`;\n  return container;\n}\n","import { createElement, type ComponentType, type ReactElement, type ReactNode } from 'react';\n\n/**\n * Any React component that accepts children and optional additional props.\n */\nexport type AnyProvider<P extends Record<string, unknown> = Record<string, unknown>> =\n  ComponentType<P & { children?: ReactNode }>;\n\n/**\n * Composes multiple provider components into a single wrapper component.\n * Providers are applied outermost-first (left to right in the argument list).\n *\n * This eliminates the deeply-nested JSX pattern common when multiple\n * unstated-next containers need to wrap the same subtree.\n *\n * @example\n * // Before: deeply nested JSX\n * <SnackbarProvider>\n *   <ProfileProvider initialState={profile}>\n *     <OrganizationProvider initialState={org}>\n *       {children}\n *     </OrganizationProvider>\n *   </ProfileProvider>\n * </SnackbarProvider>\n *\n * // After: compose providers without dynamic props\n * const AppProviders = composeProviders(\n *   SnackbarProvider,\n *   ThemeProvider,\n *   RouterProvider,\n * );\n * // <AppProviders>{children}</AppProviders>\n */\nexport function composeProviders(\n  ...providers: ComponentType<{ children?: ReactNode }>[]\n): ComponentType<{ children?: ReactNode }> {\n  function ComposedProviders({ children }: { children?: ReactNode }): ReactElement {\n    return providers.reduceRight<ReactElement>(\n      (child, Provider) => createElement(Provider, null, child),\n      children as ReactElement,\n    );\n  }\n\n  ComposedProviders.displayName = `ComposedProviders(${providers\n    .map((p) => p.displayName || p.name || 'Unknown')\n    .join(', ')})`;\n\n  return ComposedProviders;\n}\n"],"mappings":";AACA,SAAS,mBAAAA,wBAAuB;;;ACDhC,SAAS,uBAAuB;AAsBzB,SAAS,qBACd,MACA,SACA;AACA,QAAM,YAAY,gBAA8B,OAAO;AACvD,YAAU,SAAS,cAAc,GAAG,IAAI;AACxC,SAAO;AACT;;;AC7BA,SAAS,qBAA4E;AAiC9E,SAAS,oBACX,WACsC;AACzC,WAAS,kBAAkB,EAAE,SAAS,GAA2C;AAC/E,WAAO,UAAU;AAAA,MACf,CAAC,OAAO,aAAa,cAAc,UAAU,MAAM,KAAK;AAAA,MACxD;AAAA,IACF;AAAA,EACF;AAEA,oBAAkB,cAAc,qBAAqB,UAClD,IAAI,CAAC,MAAM,EAAE,eAAe,EAAE,QAAQ,SAAS,EAC/C,KAAK,IAAI,CAAC;AAEb,SAAO;AACT;","names":["createContainer"]}

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "react-container-kit",
+  "version": "1.0.0",
+  "description": "TypeScript utilities for the React container pattern — named containers, provider composition, and type helpers",
+  "packageManager": "yarn@4.13.0",
+  "main": "./dist/index.js",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:types": "tsc --project tsconfig.types-test.json --noEmit",
+    "test:coverage": "vitest run --coverage",
+    "prepublishOnly": "yarn build && yarn typecheck && yarn test && yarn test:types",
+    "release": "yarn npm publish"
+  },
+  "peerDependencies": {
+    "react": ">=16.8.0",
+    "unstated-next": "^1.1.0"
+  },
+  "devDependencies": {
+    "@testing-library/dom": "^10.0.0",
+    "@testing-library/react": "^16.0.0",
+    "@types/react": "^18.0.0",
+    "@vitejs/plugin-react": "^4.0.0",
+    "@vitest/coverage-v8": "^2.0.0",
+    "happy-dom": "^14.0.0",
+    "react": "^18.0.0",
+    "react-dom": "^18.0.0",
+    "tsup": "^8.0.0",
+    "typescript": "^5.0.0",
+    "unstated-next": "^1.1.0",
+    "vite": "^5.0.0",
+    "vitest": "^2.0.0"
+  }
+}