@primer-io/primer-js 0.3.2 → 0.3.3

package/dist/web-types.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://raw.githubusercontent.com/JetBrains/web-types/master/schema/web-types.json",
   "name": "@primer-io/primer-js",
-  "version": "0.3.2",
+  "version": "0.3.3",
   "description-markup": "markdown",
   "contributions": {
     "html": {

package/package.json

@@ -2,7 +2,7 @@
   "name": "@primer-io/primer-js",
   "description": "Primer Composable Checkout is a web component-based SDK for building secure, customizable, and PCI-compliant checkout experiences. Designed with a modular architecture, it integrates seamlessly with any JavaScript framework and supports multiple payment methods.",
   "license": "BSD-3-Clause",
-  "version": "0.3.2",
+  "version": "0.3.3",
   "type": "module",
   "main": "./dist/primer-loader.js",
   "types": "./dist/primer-loader.d.ts",
@@ -45,4 +45,4 @@
   },
   "customElements": "dist/custom-elements.json",
   "web-types": "./dist/web-types.json"
-}
+}

package/src/controllers/reactive-state/README.md

@@ -0,0 +1,210 @@
+# Reactive State Management Library
+
+A TypeScript library for state management in reactive controllers that solves common issues:
+
+- Enforces type safety for state, actions, and reducers
+- Catches missing action handlers at compile time
+- Enables splitting state into smaller contexts for optimal performance
+- Provides a consistent pattern for state management across controllers
+
+## Key Concepts
+
+### Action Types
+
+Actions are defined as discriminated unions with a `type` property:
+
+```typescript
+type UserAction =
+  | { type: 'SET_NAME'; payload: string }
+  | { type: 'SET_EMAIL'; payload: string }
+  | { type: 'RESET' };
+```
+
+### Handlers Map
+
+Action handlers are defined in a map where every action type must have a corresponding handler:
+
+```typescript
+const handlers: ActionHandlerMap<UserState, UserAction, null> = {
+  SET_NAME: (state, action) => ({ ...state, name: action.payload }),
+  SET_EMAIL: (state, action) => ({ ...state, email: action.payload }),
+  RESET: () => initialUserState,
+};
+```
+
+If you forget to handle an action, TypeScript will generate a compile-time error.
+
+## Core Components
+
+### `ReactiveStateController`
+
+Base class for creating state controllers:
+
+```typescript
+class ReactiveStateController<
+  Host extends ReactiveControllerHost,
+  State,
+  Action extends { type: string },
+  Callbacks = ReducerCallbacks<State, Action> | null,
+> {
+  constructor(
+    host: Host,
+    initialState: State,
+    reducer: TypedReducer<State, Action, Callbacks>,
+    initialCallbacks: Callbacks,
+    stateHandler?: (state: State) => void,
+  );
+
+  // Public API for accessing state
+  public get currentState(): Readonly<State>;
+
+  // Dispatch actions to update state
+  protected dispatch(action: Action): void;
+}
+```
+
+### `CompositeStateController`
+
+For managing multiple state slices to avoid excessive re-renders:
+
+```typescript
+class CompositeStateController<Host extends ReactiveControllerHost> {
+  // Add sub-controllers for different state slices
+  addController<State, Action, Callbacks>(
+    controller: ReactiveStateController<Host, State, Action, Callbacks>,
+  ): void;
+}
+```
+
+### `createReducer`
+
+Creates a type-safe reducer from handlers:
+
+```typescript
+function createReducer<State, Action extends { type: string }, Callbacks>(
+  handlers: ActionHandlerMap<State, Action, Callbacks>,
+): TypedReducer<State, Action, Callbacks>;
+```
+
+## Simple Example
+
+```typescript
+// 1. Define your state interface
+interface CounterState {
+  count: number;
+}
+
+// 2. Define possible actions
+type CounterAction =
+  | { type: 'INCREMENT' }
+  | { type: 'DECREMENT' }
+  | { type: 'SET_COUNT'; payload: number };
+
+// 3. Create initial state
+const initialState: CounterState = { count: 0 };
+
+// 4. Define action handlers
+const handlers: ActionHandlerMap<CounterState, CounterAction, null> = {
+  INCREMENT: (state) => ({ ...state, count: state.count + 1 }),
+  DECREMENT: (state) => ({ ...state, count: state.count - 1 }),
+  SET_COUNT: (state, action) => ({ ...state, count: action.payload }),
+};
+
+// 5. Create a reducer
+const counterReducer = createReducer(handlers);
+
+// 6. Create your controller
+class CounterController extends ReactiveStateController<
+  ReactiveControllerHost,
+  CounterState,
+  CounterAction,
+  null
+> {
+  constructor(host: ReactiveControllerHost) {
+    super(host, initialState, counterReducer, null);
+  }
+
+  // Public API methods
+  increment() {
+    this.dispatch({ type: 'INCREMENT' });
+  }
+
+  decrement() {
+    this.dispatch({ type: 'DECREMENT' });
+  }
+
+  setCount(count: number) {
+    this.dispatch({ type: 'SET_COUNT', payload: count });
+  }
+
+  // Public getter for the count
+  get count(): number {
+    return this.currentState.count;
+  }
+}
+```
+
+## Advanced Usage: State Splitting
+
+For complex components, splitting state improves performance by preventing unnecessary re-renders:
+
+```typescript
+// 1. Define separate state slices
+interface CoreState {
+  /* core properties */
+}
+interface FormState {
+  /* form properties that change frequently */
+}
+
+// 2. Create separate controllers for each slice
+class CoreController extends ReactiveStateController<
+  Host,
+  CoreState,
+  CoreAction,
+  null
+> {
+  /* ... */
+}
+class FormController extends ReactiveStateController<
+  Host,
+  FormState,
+  FormAction,
+  null
+> {
+  /* ... */
+}
+
+// 3. Combine with CompositeStateController
+class ComplexController extends CompositeStateController<Host> {
+  private coreController: CoreController;
+  private formController: FormController;
+
+  constructor(host: Host) {
+    super(host);
+
+    this.coreController = new CoreController(host /* ... */);
+    this.formController = new FormController(host /* ... */);
+
+    this.addController(this.coreController);
+    this.addController(this.formController);
+  }
+
+  // Expose state slices through getters
+  get coreState(): Readonly<CoreState> {
+    return this.coreController.currentState;
+  }
+
+  get formState(): Readonly<FormState> {
+    return this.formController.currentState;
+  }
+}
+```
+
+## Benefits
+
+- **Type Safety**: Ensures all action types are handled correctly
+- **Performance**: Granular state updates through context splitting
+- **Maintainability**: Consistent patterns across all controllers
+- **Debugging**: Predictable state updates through pure reducer functions
+- **Testability**: Easy to test state transitions in isolation