@primer-io/primer-js 0.3.2 → 0.3.4

package/dist/vscode.html-custom-data.json

@@ -115,8 +115,11 @@
     },
     {
       "name": "primer-dialog",
-      "description": "\n---\n",
-      "attributes": [],
+      "description": "\n---\n\n\n### **Events:**\n - **primer-dialog-close**\n\n### **Methods:**\n - **startExitAnimation(): _void_** - Public method to trigger exit animation programmatically",
+      "attributes": [
+        { "name": "size", "values": [{ "name": "flex" }, { "name": "large" }] },
+        { "name": "showCloseButton", "values": [] }
+      ],
       "references": []
     },
     {
@@ -364,6 +367,20 @@
       ],
       "references": []
     },
+    {
+      "name": "primer-portal-dialog",
+      "description": "\n---\n\n\n### **Methods:**\n - **openDialog(): _void_** - Opens the content dialog\n- **closeDialog(): _void_** - Closes the dialog with animation",
+      "attributes": [
+        { "name": "size", "values": [{ "name": "flex" }, { "name": "large" }] },
+        { "name": "showCloseButton", "values": [] },
+        { "name": "onOpen", "values": [{ "name": "() => void" }] },
+        {
+          "name": "secureHtmlContent",
+          "values": [{ "name": "SecureHtmlContentAccess" }]
+        }
+      ],
+      "references": []
+    },
     {
       "name": "primer-checkout-complete",
       "description": "\n---\n",

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.4",
   "description-markup": "markdown",
   "contributions": {
     "html": {
@@ -253,11 +253,26 @@
         },
         {
           "name": "primer-dialog",
-          "description": "\n---\n",
+          "description": "\n---\n\n\n### **Events:**\n - **primer-dialog-close**\n\n### **Methods:**\n - **startExitAnimation(): _void_** - Public method to trigger exit animation programmatically",
           "doc-url": "",
-          "attributes": [],
-          "events": [],
-          "js": { "properties": [], "events": [] }
+          "attributes": [
+            {
+              "name": "size",
+              "value": { "type": "'flex' | 'large'", "default": "'flex'" }
+            },
+            {
+              "name": "showCloseButton",
+              "value": { "type": "boolean", "default": "true" }
+            }
+          ],
+          "events": [{ "name": "primer-dialog-close", "type": "CustomEvent" }],
+          "js": {
+            "properties": [
+              { "name": "size", "type": "'flex' | 'large'" },
+              { "name": "showCloseButton", "type": "boolean" }
+            ],
+            "events": [{ "name": "primer-dialog-close", "type": "CustomEvent" }]
+          }
         },
         {
           "name": "primer-error-message",
@@ -892,6 +907,40 @@
             "events": []
           }
         },
+        {
+          "name": "primer-portal-dialog",
+          "description": "\n---\n\n\n### **Methods:**\n - **openDialog(): _void_** - Opens the content dialog\n- **closeDialog(): _void_** - Closes the dialog with animation",
+          "doc-url": "",
+          "attributes": [
+            {
+              "name": "size",
+              "value": { "type": "'flex' | 'large'", "default": "'large'" }
+            },
+            {
+              "name": "showCloseButton",
+              "value": { "type": "boolean", "default": "false" }
+            },
+            { "name": "onOpen", "value": { "type": "() => void | undefined" } },
+            {
+              "name": "secureHtmlContent",
+              "value": { "type": "SecureHtmlContentAccess | undefined" }
+            }
+          ],
+          "events": [],
+          "js": {
+            "properties": [
+              { "name": "size", "type": "'flex' | 'large'" },
+              { "name": "showCloseButton", "type": "boolean" },
+              { "name": "onOpen", "type": "() => void | undefined" },
+              {
+                "name": "secureHtmlContent",
+                "type": "SecureHtmlContentAccess | undefined"
+              },
+              { "name": "open", "type": "boolean" }
+            ],
+            "events": []
+          }
+        },
         {
           "name": "primer-checkout-complete",
           "description": "\n---\n",

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.4",
   "type": "module",
   "main": "./dist/primer-loader.js",
   "types": "./dist/primer-loader.d.ts",
@@ -35,6 +35,10 @@
     },
     "./src/*": "./src/*"
   },
+  "scripts": {
+    "prepack": "clean-package",
+    "postpack": "clean-package restore"
+  },
   "peerDependencies": {
     "react": "^18.2.0 || ^19.0.0"
   },
@@ -45,4 +49,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