@codeleap/portals 6.3.0 → 7.0.0

package/src/lib/PortalState.ts

@@ -12,11 +12,12 @@ function initAtomWithPromise<T>(a: IAtom<T>, promise: Promise<T>) {
   })
 }
 
+/** Configuration for initializing portal state: initial params, visibility, reset behavior, and transition timing. */
 export type PortalStateConfig<Params> = {
-  initialParams: Params | (() => Promise<Params>)
-  startsOpen: boolean | (() => Promise<boolean>)
+  initialParams?: Params | (() => Promise<Params>)
+  startsOpen?: boolean | (() => Promise<boolean>)
   resetParamsOnClose?: boolean
-  transitionDuration: number
+  transitionDuration?: number
 }
 
 /**
@@ -26,13 +27,32 @@ export type PortalStateConfig<Params> = {
  * @template Params - Type of parameters managed by the state
  */
 export class PortalState<Params = {}> {
-  visible: IAtom<boolean>
+  /** Nanostores atom managing portal visibility state. */
+  visible!: IAtom<boolean>
 
-  params: IAtom<Params>
+  /** Nanostores atom managing portal parameters. */
+  params!: IAtom<Params>
 
-  _initialParams: Params
+  /** Initial parameter values used when resetting. */
+  _initialParams!: Params
 
-  private config: PortalStateConfig<Params>
+  private config!: PortalStateConfig<Params>
+
+  /**
+   * Asserts the portal state has been initialized and returns the initialized stores.
+   * @throws Error if `initializeState()` has not been called yet
+   */
+  assertInitialized() {
+    if (!this.visible || !this.params || !this.config || this._initialParams === undefined) {
+      throw new Error('PortalState has not been initialized. Call initializeState() first.')
+    }
+    return {
+      visible: this.visible,
+      params: this.params,
+      config: this.config,
+      initialParams: this._initialParams,
+    }
+  }
 
   /**
    * Initializes the portal state with configuration.
@@ -63,18 +83,24 @@ export class PortalState<Params = {}> {
     }
   }
 
+  /** Gets the current visibility state. */
   get isVisible() {
-    return this.visible.get()
+    const { visible } = this.assertInitialized()
+    return visible.get()
   }
 
+  /** Gets the current parameter values. */
   get currentParams() {
-    return this.params.get()
+    const { params } = this.assertInitialized()
+    return params.get()
   }
 
   private awaitTransition(count = 1) {
-    return awaitTransition(count, this.config.transitionDuration)
+    const { config } = this.assertInitialized()
+    return awaitTransition(count, config.transitionDuration)
   }
 
+  /** Lifecycle hook called after the portal opens. Override in subclasses to run custom logic. */
   protected handleOpen() { }
 
   /**
@@ -82,38 +108,45 @@ export class PortalState<Params = {}> {
    * @param params - Parameters to merge with current params
    */
   async open(params?: Params) {
-    if (this.visible.get()) {
+    const { visible, params: paramsAtom } = this.assertInitialized()
+
+    if (visible.get()) {
       return
     }
 
     if (params) {
-      this.params.set({
-        ...this.params.get(),
+      paramsAtom.set({
+        ...paramsAtom.get(),
         ...params,
       })
     }
 
-    this.visible.set(true)
+    visible.set(true)
 
     await this.awaitTransition()
 
     this.handleOpen()
   }
 
+  /** Lifecycle hook called after the portal closes. Override in subclasses to run custom logic. */
   protected handleClose() { }
 
   /**
    * Closes the portal and optionally resets parameters.
    */
   async close() {
-    if (!this.visible.get()) {
+    const { visible, config } = this.assertInitialized()
+
+    if (!visible.get()) {
       return this.awaitTransition()
     }
 
-    this.visible.set(false)
+    visible.set(false)
 
-    if (this.config.resetParamsOnClose) {
-      this.resetParams()
+    if (config.resetParamsOnClose) {
+      setTimeout(() => {
+        this.resetParams()
+      }, 1000)
     }
 
     this.handleClose()
@@ -125,7 +158,9 @@ export class PortalState<Params = {}> {
    * Toggles portal visibility (opens if closed, closes if open).
    */
   toggle() {
-    if (this.visible.get()) {
+    const { visible } = this.assertInitialized()
+
+    if (visible.get()) {
       return this.close()
     } else {
       return this.open()
@@ -137,11 +172,12 @@ export class PortalState<Params = {}> {
    * @param next - Partial params or updater function
    */
   setParams(next: Partial<Params> | ((prev: Params) => Partial<Params>)) {
-    const prev = this.params.get()
+    const { params } = this.assertInitialized()
+    const prev = params.get()
 
     const patch = TypeGuards.isFunction(next) ? next(prev) : next
 
-    this.params.set({
+    params.set({
       ...prev,
       ...patch,
     })
@@ -151,7 +187,8 @@ export class PortalState<Params = {}> {
    * Resets parameters to initial values.
    */
   resetParams() {
-    this.params.set(this._initialParams ?? {} as Params)
+    const { params, initialParams } = this.assertInitialized()
+    params.set(initialParams)
   }
 
   /**
@@ -159,7 +196,8 @@ export class PortalState<Params = {}> {
    * @returns Current params object
    */
   getParams() {
-    return this.params.get()
+    const { params } = this.assertInitialized()
+    return params.get()
   }
 
   /**
@@ -167,7 +205,8 @@ export class PortalState<Params = {}> {
    * @param callback - Function called when visibility changes
    * @returns Unsubscribe function
    */
-  subscribe(callback: (visible: boolean, wasVisible: boolean) => void) {
-    return this.visible.subscribe(callback)
+  subscribe(callback: (visible: boolean, wasVisible?: boolean) => void) {
+    const { visible } = this.assertInitialized()
+    return visible.subscribe(callback)
   }
 }

package/src/types/misc.ts

@@ -1,7 +1,9 @@
 import { AnyFunction } from '@codeleap/types'
 
+/** Extracts all but the first element of a tuple type. */
 type AllButFirst<T extends any[]> = T extends [infer _, ...infer Rest] ? Rest : []
 
+/** Produces a version of function `T` whose first parameter excludes type `E`. */
 export type ExcludeFromParam<
   T extends AnyFunction,
   E = any

package/src/types/portal.ts

@@ -1,22 +1,25 @@
 import { Ref } from 'react'
 
+/** Props injected into portal content: visibility flag, lifecycle methods, and the portal's current params. */
 export type PortalParams<P = {}, Result = {}> = {
   visible: boolean
-  toggle: () => void
-  close: () => void
-  open: () => void
+  toggle: () => void | Promise<void>
+  close: () => void | Promise<void>
+  open: (params?: P) => void | Promise<void>
   setParams: (next: Partial<P> | ((prev: P) => Partial<P>)) => void
   request?: {
-    resolve: (result: Result) => void
-    reject: (reason: unknown) => void
+    resolve?: (result: Result) => void
+    reject?: (reason: unknown) => void
   }
 } & P
 
+/** Function that renders portal content, receiving params and an optional ref. */
 export type RenderPortalContent<Params = {}, Result = {}, RefType = any> = (
   props: PortalParams<Params, Result>,
   ref?: React.RefObject<RefType>
 ) => React.ReactElement
 
+/** Configuration options for portal initialization and runtime behavior. */
 export type PortalConfig<P, M = {}> = {
   initialParams?: P | (() => Promise<P>)
   startsOpen?: boolean | (() => Promise<boolean>)
@@ -25,10 +28,13 @@ export type PortalConfig<P, M = {}> = {
   metadata?: M
   transitionDuration?: number
   resetParamsOnClose?: boolean
+  ephemeral?: boolean
 }
 
+/** Constructor parameter — either a portal ID string or a config object with an optional `id` field. */
 export type PortalConstructorParam<Params = {}, Metadata = {}> = (Partial<PortalConfig<Params, Metadata>> & { id?: string }) | string
 
+/** Props passed to the wrapper component (modal/drawer/sheet) including lifecycle handlers and z-index. */
 export type PortalWrapperProps<P, R> = P & {
   close: () => void
   open: () => void

package/src/utils.ts

@@ -1,9 +1,18 @@
 import { waitFor } from '@codeleap/utils'
 
+/**
+ * Generates a random 7-character alphanumeric ID.
+ * @returns Random ID string
+ */
 export const randomId = () => {
   return Math.random().toString(36).slice(2, 9)
 }
 
+/**
+ * Waits for one or more animation transitions to complete.
+ * @param count - Number of transitions to wait for (defaults to 1)
+ * @param duration - Duration per transition in milliseconds (defaults to 1000)
+ */
 export async function awaitTransition(count?: number, duration = 1000) {
   for (let i = 0; i < (count ?? 1); i++) {
     await waitFor(duration)

package/package.json.bak

@@ -1,32 +0,0 @@
-{
-  "name": "@codeleap/portals",
-  "version": "6.3.0",
-  "main": "src/index.ts",
-  "license": "UNLICENSED",
-  "repository": {
-    "url": "https://github.com/codeleap-uk/internal-libs-monorepo.git",
-    "type": "git",
-    "directory": "packages/portals"
-  },
-  "devDependencies": {
-    "@codeleap/types": "workspace:*",
-    "@codeleap/config": "workspace:*",
-    "@codeleap/utils": "workspace:*",
-    "@codeleap/logger": "workspace:*",
-    "ts-node-dev": "1.1.8"
-  },
-  "scripts": {
-    "build": "echo 'No build needed'",
-    "lint": "eslint -c  .eslintrc.js --fix \"./src/**/*.{ts,tsx,js,jsx}\"",
-    "run-sc": "tsnd --transpile-only"
-  },
-  "peerDependencies": {
-    "@codeleap/types": "workspace:*",
-    "@codeleap/utils": "workspace:*",
-    "@codeleap/logger": "workspace:*",
-    "typescript": "5.5.2",
-    "react": "19.1.0",
-    "nanostores": "*",
-    "@nanostores/react": "*"
-  }
-}