@codeleap/portals 6.3.0 → 6.8.0

package/dist/utils.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Generates a random 7-character alphanumeric ID.
+ * @returns Random ID string
+ */
+export declare const randomId: () => string;
+/**
+ * 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 declare function awaitTransition(count?: number, duration?: number): Promise<void>;
+//# sourceMappingURL=utils.d.ts.map

package/dist/utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"utils.d.ts","sourceRoot":"","sources":["../src/utils.ts"],"names":[],"mappings":"AAEA;;;GAGG;AACH,eAAO,MAAM,QAAQ,cAEpB,CAAA;AAED;;;;GAIG;AACH,wBAAsB,eAAe,CAAC,KAAK,CAAC,EAAE,MAAM,EAAE,QAAQ,SAAO,iBAIpE"}

package/package.json

@@ -1,7 +1,20 @@
 {
   "name": "@codeleap/portals",
-  "version": "6.3.0",
+  "version": "6.8.0",
   "main": "src/index.ts",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "source": "./src/index.ts",
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
   "license": "UNLICENSED",
   "repository": {
     "url": "https://github.com/codeleap-uk/internal-libs-monorepo.git",
@@ -9,24 +22,25 @@
     "directory": "packages/portals"
   },
   "devDependencies": {
-    "@codeleap/types": "6.3.0",
-    "@codeleap/config": "6.3.0",
-    "@codeleap/utils": "6.3.0",
-    "@codeleap/logger": "6.3.0",
+    "@codeleap/types": "6.8.0",
+    "@codeleap/config": "6.8.0",
+    "@codeleap/utils": "6.8.0",
+    "@codeleap/logger": "6.8.0",
     "ts-node-dev": "1.1.8"
   },
   "scripts": {
-    "build": "echo 'No build needed'",
+    "build": "tsc --build tsconfig.build.json",
+    "typecheck": "bun tsc --noEmit -p ./tsconfig.json",
     "lint": "eslint -c  .eslintrc.js --fix \"./src/**/*.{ts,tsx,js,jsx}\"",
     "run-sc": "tsnd --transpile-only"
   },
   "peerDependencies": {
-    "@codeleap/types": "6.3.0",
-    "@codeleap/utils": "6.3.0",
-    "@codeleap/logger": "6.3.0",
-    "typescript": "5.5.2",
+    "@codeleap/types": "6.8.0",
+    "@codeleap/utils": "6.8.0",
+    "@codeleap/logger": "6.8.0",
+    "typescript": "6.0.3",
     "react": "19.1.0",
     "nanostores": "*",
     "@nanostores/react": "*"
   }
-}
+}

package/src/factors/alert.ts

@@ -1,14 +1,17 @@
 import { AnyFunction } from '@codeleap/types'
 import { Modal } from './modal'
 
+/** Discriminant for alert categories used to control icon/style in the wrapper component. */
 export type AlertType = 'info' | 'error' | 'warn' | 'ask' | 'custom'
 
+/** A single button option rendered inside an alert dialog. */
 export type AlertOption = {
   text: string
   onPress?: AnyFunction
   style?: 'destructive' | 'outline' | 'cancel' | 'default' | 'minimal'
 }
 
+/** Configuration options for displaying an alert dialog. */
 export type AlertOptions = {
   title?: string
   body?: string
@@ -22,88 +25,45 @@ export type AlertOptions = {
  * Provides convenient methods for common alert scenarios.
  */
 export class Alert {
-  static modal: Modal<AlertOptions>
 
+  /**
+   * Returns the Modal instance used to display alerts.
+   * Must be implemented by the consuming app before calling any alert method.
+   * @throws Error if not implemented
+   */
   static openAlert(): Modal<AlertOptions> {
-    return Alert.modal
+    throw new Error('Please implement Alert.openAlert to use the alert system')
   }
 
   private trigger(args: AlertOptions) {
     Alert.openAlert().open(args)
   }
 
-  /**
-   * Opens an alert with 'ask' type (for questions).
-   * @param args - Alert options (defaults title to 'Quick question')
-   */
+  /** Opens an alert with 'ask' type. */
   ask(args: AlertOptions) {
-    const { title = 'Quick question', ...rest } = args
-
-    this.trigger({
-      ...rest,
-      title,
-      type: 'ask',
-    })
+    this.trigger({ ...args, type: 'ask' })
   }
 
-  /**
-   * Opens an alert with 'error' type.
-   * @param args - Alert options (defaults title to 'Whoops!' and body to 'Something went wrong')
-   */
+  /** Opens an alert with 'error' type. */
   error(args: AlertOptions) {
-    const { title = 'Whoops!', body = 'Something went wrong', ...rest } = args
-
-    this.trigger({
-      ...rest,
-      title,
-      body,
-      type: 'error',
-    })
+    this.trigger({ ...args, type: 'error' })
   }
 
-  /**
-   * Opens an alert with 'warn' type.
-   * @param args - Alert options (defaults title to 'Hang on' and body to 'Are you sure?')
-   */
+  /** Opens an alert with 'warn' type. */
   warn(args: AlertOptions) {
-    const { title = 'Hang on', body = 'Are you sure?', ...rest } = args
-
-    this.trigger({
-      ...rest,
-      title,
-      body,
-      type: 'warn',
-    })
+    this.trigger({ ...args, type: 'warn' })
   }
 
-  /**
-   * Opens an alert with 'info' type.
-   * @param args - Alert options (defaults title to 'Hang on' and body to 'Are you sure?')
-   */
+  /** Opens an alert with 'info' type. */
   info(args: AlertOptions) {
-    const { title = 'Hang on', body = 'Are you sure?', ...rest } = args
-
-    this.trigger({
-      ...rest,
-      title,
-      body,
-      type: 'info',
-    })
+    this.trigger({ ...args, type: 'info' })
   }
 
-  /**
-   * Opens a custom alert with user-defined options and type.
-   * @param options - Custom alert options and additional properties
-   */
+  /** Opens a custom alert with user-defined options and type. */
   custom<T>(options: Partial<AlertOptions> & T) {
-    this.trigger({
-      ...(options as any),
-      type: 'custom',
-    })
+    this.trigger({ ...(options as any), type: 'custom' })
   }
 }
 
-/**
- * Global alert instance for showing alerts throughout the app.
- */
+/** Global alert instance for showing alerts throughout the app. */
 export const alert = new Alert()

package/src/factors/bottomSheet.ts

@@ -15,22 +15,35 @@ import { ReactElement } from 'react'
 export class BottomSheet<Params = {}, Result = {}, Metadata = {}> extends Portal<Params, Result, Metadata, BottomSheetRef, BottomSheetWrapperProps> {
   displayName = 'BottomSheet'
 
-  static WrapperComponent: (props: PortalWrapperProps<BottomSheetWrapperProps, BottomSheetRef>) => ReactElement = () => null
+  /** Wrapper component used to render bottom sheet UI. Must be assigned by the consuming app. */
+  static WrapperComponent: (props: PortalWrapperProps<BottomSheetWrapperProps, BottomSheetRef>) => ReactElement | null = () => null
 
+  /** Default transition duration in milliseconds for bottom sheet open/close animations. */
   static DEFAULT_TRANSITION_DURATION = 200
 
+  /** @inheritdoc */
   protected get defaultTransitionDuration() {
     return BottomSheet.DEFAULT_TRANSITION_DURATION
   }
 
+  /** @inheritdoc */
   protected get wrapperComponent(): any {
     return BottomSheet.WrapperComponent
   }
 
+  /** Closes all open BottomSheet instances. */
+  static async closeAll() {
+    const registries = BottomSheet.registry.getAll()
+    await Promise.all(registries.map(instance => instance.close()))
+  }
+
+  /** Name of the ref method to call imperatively when opening the sheet (set by the consuming app). */
   static openKeyMethod: Keyof<BottomSheetRef>
 
+  /** Name of the ref method to call imperatively when closing the sheet (set by the consuming app). */
   static closeKeyMethod: Keyof<BottomSheetRef>
 
+  /** Returns default config: `rendersWhenHidden=true` and `resetParamsOnClose=false`. */
   protected getDefaultConfig(): Partial<PortalConfig<Params, Metadata>> {
     return {
       rendersWhenHidden: true,
@@ -38,22 +51,26 @@ export class BottomSheet<Params = {}, Result = {}, Metadata = {}> extends Portal
     } as Partial<PortalConfig<Params, Metadata>>
   }
 
+  /** Calls the native open method on the ref via `openKeyMethod`, if configured. */
   protected openBottomSheet() {
     if (!!BottomSheet.openKeyMethod && !!this.ref?.current) {
-      this.ref?.current?.[BottomSheet.openKeyMethod as string]?.()
+      (this.ref?.current as Record<string, (() => void) | undefined>)?.[BottomSheet.openKeyMethod as string]?.()
     }
   }
 
+  /** Calls the native close method on the ref via `closeKeyMethod`, if configured. */
   protected closeBottomSheet() {
     if (!!BottomSheet.closeKeyMethod && !!this.ref?.current) {
-      this.ref?.current?.[BottomSheet.closeKeyMethod as string]?.()
+      (this.ref?.current as Record<string, (() => void) | undefined>)?.[BottomSheet.closeKeyMethod as string]?.()
     }
   }
 
+  /** @inheritdoc — also triggers the native open animation via `openBottomSheet()`. */
   protected handleOpen() {
     this.openBottomSheet()
   }
 
+  /** @inheritdoc — also triggers the native close animation via `closeBottomSheet()`. */
   protected handleClose() {
     this.closeBottomSheet()
   }

package/src/factors/drawer.ts

@@ -14,17 +14,27 @@ import { PortalConstructorParam, PortalWrapperProps } from '../types'
 export class Drawer<Params = {}, Result = {}, Metadata = {}> extends Portal<Params, Result, Metadata, DrawerRef, DrawerWrapperProps> {
   displayName = 'Drawer'
 
-  static WrapperComponent: (props: PortalWrapperProps<DrawerWrapperProps, DrawerRef>) => ReactElement = () => null
+  /** Wrapper component used to render drawer UI. Must be assigned by the consuming app. */
+  static WrapperComponent: (props: PortalWrapperProps<DrawerWrapperProps, DrawerRef>) => ReactElement | null = () => null
 
+  /** Default transition duration in milliseconds for drawer open/close animations. */
   static DEFAULT_TRANSITION_DURATION = 200
 
+  /** @inheritdoc */
   protected get defaultTransitionDuration() {
     return Drawer.DEFAULT_TRANSITION_DURATION
   }
 
+  /** @inheritdoc */
   protected get wrapperComponent(): any {
     return Drawer.WrapperComponent
   }
+
+  /** Closes all open Drawer instances. */
+  static async closeAll() {
+    const registries = Drawer.registry.getAll()
+    await Promise.all(registries.map(instance => instance.close()))
+  }
 }
 
 /**

package/src/factors/modal.ts

@@ -14,17 +14,27 @@ import { PortalConstructorParam, PortalWrapperProps } from '../types'
 export class Modal<Params = {}, Result = {}, Metadata = {}> extends Portal<Params, Result, Metadata, ModalRef, ModalWrapperProps> {
   displayName = 'Modal'
 
-  static WrapperComponent: (props: PortalWrapperProps<ModalWrapperProps, ModalRef>) => ReactElement = () => null
+  /** Wrapper component used to render modal UI. Must be assigned by the consuming app. */
+  static WrapperComponent: (props: PortalWrapperProps<ModalWrapperProps, ModalRef>) => ReactElement | null = () => null
 
+  /** Default transition duration in milliseconds for modal open/close animations. */
   static DEFAULT_TRANSITION_DURATION = 200
 
+  /** @inheritdoc */
   protected get defaultTransitionDuration() {
     return Modal.DEFAULT_TRANSITION_DURATION
   }
 
+  /** @inheritdoc */
   protected get wrapperComponent(): any {
     return Modal.WrapperComponent
   }
+
+  /** Closes all open Modal instances. */
+  static async closeAll() {
+    const registries = Modal.registry.getAll()
+    await Promise.all(registries.map(instance => instance.close()))
+  }
 }
 
 /**

package/src/globals.ts

@@ -1,13 +1,19 @@
 /* eslint-disable @typescript-eslint/no-empty-interface */
 
+/** Props for the bottom sheet wrapper component. Extend this interface in the consuming app. */
 export interface BottomSheetWrapperProps {}
 
+/** Ref type for the bottom sheet component. Extend this interface to expose imperative methods. */
 export interface BottomSheetRef {}
 
+/** Props for the modal wrapper component. Extend this interface in the consuming app. */
 export interface ModalWrapperProps {}
 
+/** Ref type for the modal component. Extend this interface to expose imperative methods. */
 export interface ModalRef {}
 
+/** Props for the drawer wrapper component. Extend this interface in the consuming app. */
 export interface DrawerWrapperProps {}
 
+/** Ref type for the drawer component. Extend this interface to expose imperative methods. */
 export interface DrawerRef {}

package/src/lib/Portal.tsx

@@ -11,6 +11,11 @@ import { PortalRequest } from './PortalRequest'
 
 type IAtom<T> = ReturnType<typeof atom<T>>
 
+/**
+ * Nanostores atom holding the IDs of all currently registered portals in creation order.
+ * Drives `GlobalOutlet` re-renders when portals are added or removed (including ephemeral ones).
+ * Read-only outside of portal lifecycle code — mutate only via `Portal` constructor/`onVisibilityChanged`.
+ */
 export const registeredIds = atom<string[]>([])
 
 /**
@@ -28,9 +33,9 @@ export class Portal<Params = {}, Result = {}, Metadata = {}, RefType = any, Wrap
 
   id: string
 
-  RenderContent: RenderPortalContent<Params, Result, RefType>
+  RenderContent!: RenderPortalContent<Params, Result, RefType>
 
-  ref?: React.RefObject<RefType>
+  ref?: React.RefObject<RefType | null>
 
   requestHandler: PortalRequest<Params, Result>
 
@@ -38,7 +43,7 @@ export class Portal<Params = {}, Result = {}, Metadata = {}, RefType = any, Wrap
 
   _wrapperProps: IAtom<WrapperProps>
 
-  _lazyWrapperProps: (params: Params) => WrapperProps
+  _lazyWrapperProps!: (params: Params) => WrapperProps
 
   static registry = new PortalRegistry<Portal<any, any, any>>()
 
@@ -56,7 +61,7 @@ export class Portal<Params = {}, Result = {}, Metadata = {}, RefType = any, Wrap
     return Portal.generateId
   }
 
-  protected get defaultTransitionDuration() {
+  protected get defaultTransitionDuration(): number | null {
     return null
   }
 
@@ -74,15 +79,17 @@ export class Portal<Params = {}, Result = {}, Metadata = {}, RefType = any, Wrap
     return this
   }
 
+  /** Gets the resolve handler for the pending request. */
   get resolve() {
     return this.requestHandler.resolve
   }
 
+  /** Gets the reject handler for the pending request. */
   get reject() {
     return this.requestHandler.reject
   }
 
-  private onVisibilityChanged(visible: boolean, wasVisible: boolean) {
+  private onVisibilityChanged(visible: boolean, wasVisible?: boolean) {
     if (this._config.independent) {
       return
     }
@@ -92,19 +99,30 @@ export class Portal<Params = {}, Result = {}, Metadata = {}, RefType = any, Wrap
     } else {
       if (wasVisible && !visible) {
         if (this.hasPendingRequest) {
-          this.requestHandler.resolve?.(null)
+          this.requestHandler.resolve?.(undefined)
           this.requestHandler.clearRequest()
         }
+
+        if (this._config.ephemeral) {
+          this.registry.unregister(this.id)
+          registeredIds.set(registeredIds.get().filter(id => id !== this.id))
+          return
+        }
       }
 
       this.registry.remove(this.id)
     }
   }
 
+  /** Gets the z-index position of the portal in the registry stack. */
   get stackIndex() {
     return this.registry.getStackIndex(this.id)
   }
 
+  /**
+   * Creates a new portal instance.
+   * @param idOrConfig - Portal ID string or configuration object with optional id field
+   */
   constructor(idOrConfig?: PortalConstructorParam<Params, Metadata>) {
     super()
 
@@ -124,10 +142,10 @@ export class Portal<Params = {}, Result = {}, Metadata = {}, RefType = any, Wrap
     }
 
     this.initializeState({
-      initialParams: this._config.initialParams,
-      startsOpen: this._config.startsOpen,
+      initialParams: this._config.initialParams!,
+      startsOpen: this._config.startsOpen!,
       resetParamsOnClose: this._config.resetParamsOnClose,
-      transitionDuration: this._config.transitionDuration,
+      transitionDuration: this._config.transitionDuration!,
     })
 
     this.id = id ?? this.idGenerator()
@@ -157,6 +175,7 @@ export class Portal<Params = {}, Result = {}, Metadata = {}, RefType = any, Wrap
     this.resetParams = this.resetParams.bind(this)
     this.getParams = this.getParams.bind(this)
     this.request = this.request.bind(this)
+    this.assertInitialized = this.assertInitialized.bind(this)
   }
 
   /**
@@ -213,12 +232,16 @@ export class Portal<Params = {}, Result = {}, Metadata = {}, RefType = any, Wrap
    * @returns Object with visible and params state
    */
   useState() {
-    const visible = useStore(this.visible)
-    const params = useStore(this.params)
+    
+    const { visible: visibleStore, params: paramsStore } = this.assertInitialized()
+    
+    const visible = useStore(visibleStore)
+    const params = useStore(paramsStore)
 
     return { visible, params }
   }
 
+  /** Whether there is a pending request awaiting resolution. */
   get hasPendingRequest() {
     return this.requestHandler.hasPendingRequest
   }
@@ -228,11 +251,22 @@ export class Portal<Params = {}, Result = {}, Metadata = {}, RefType = any, Wrap
    * @param props - Combined params and wrapper props
    * @returns JSX element with portal content wrapped in wrapper component
    */
-  Component(props?: Params & { portalProps?: WrapperProps }): JSX.Element {
+  Component(props?: Params & { portalProps?: WrapperProps }): JSX.Element | null {
     const { visible, params } = this.useState()
     const wrapperProps = useStore(this._wrapperProps)
     const { portalProps = {}, ...propParams } = props || {}
 
+    const [mounted, setMounted] = React.useState(visible)
+
+    React.useEffect(() => {
+      if (visible) {
+        setMounted(true)
+        return
+      }
+      const timer = setTimeout(() => setMounted(false), this._config?.transitionDuration ?? 0)
+      return () => clearTimeout(timer)
+    }, [visible])
+
     const Content = this.RenderContent
 
     if (!Content) {
@@ -240,7 +274,7 @@ export class Portal<Params = {}, Result = {}, Metadata = {}, RefType = any, Wrap
       return null
     }
 
-    if (!visible && !this._config?.rendersWhenHidden) return null
+    if (!visible && !mounted && !this._config?.rendersWhenHidden) return null
 
     const request = this.requestHandler.getRequestHandlers()
 
@@ -261,6 +295,7 @@ export class Portal<Params = {}, Result = {}, Metadata = {}, RefType = any, Wrap
       zIndex={this.stackIndex}
       ref={this.ref}
     >
+      {/* @ts-ignore — Content is a call signature, not a component type; LibraryManagedAttributes can't verify the spread */}
       <Content
         visible={visible}
         toggle={this.toggle}
@@ -269,7 +304,7 @@ export class Portal<Params = {}, Result = {}, Metadata = {}, RefType = any, Wrap
         setParams={this.setParams}
         {...params}
         {...(propParams ?? {})}
-        request={this.hasPendingRequest ? request : null}
+        request={this.hasPendingRequest ? request : undefined}
         nextOrToggle={this.toggle}
         previousOrToggle={this.toggle}
         ref={this.ref}
@@ -287,6 +322,19 @@ export class Portal<Params = {}, Result = {}, Metadata = {}, RefType = any, Wrap
     return this.requestHandler.request(params, force)
   }
 
+  /**
+   * Resets all registered portals to their closed initial state.
+   * Useful in test afterEach hooks to prevent state leaking between tests.
+   */
+  static resetAll() {
+    Portal.registry.getAll().forEach(portal => {
+      portal.visible?.set(false)
+      if (portal._initialParams !== undefined) {
+        portal.params?.set(portal._initialParams as any)
+      }
+    })
+  }
+
   /**
    * Global outlet component that renders all non-independent portals.
    * Place this once in your app root.

package/src/lib/PortalRequest.ts

@@ -6,9 +6,9 @@
  * @template Result - Type of result returned when request resolves
  */
 export class PortalRequest<Params = {}, Result = {}> {
-  resolve: (result: Result) => void
+  resolve?: (result: Result | undefined) => void
 
-  reject: (reason: unknown) => void
+  reject?: (reason: unknown) => void
 
   private onOpen: (params?: Params) => Promise<void>
 
@@ -41,13 +41,13 @@ export class PortalRequest<Params = {}, Result = {}> {
    * @param force - Force new request even if one is pending
    * @returns Promise that resolves with portal result
    */
-  request(params?: Params, force = false): Promise<Result> {
+  request(params?: Params, force = false): Promise<Result|undefined> {
     if (this.hasPendingRequest && !force) {
       return Promise.reject(new Error('This portal already has a pending request'))
     }
 
-    return new Promise<Result>((resolve, reject) => {
-      const onResolve = (result: Result) => {
+    return new Promise<Result|undefined>((resolve, reject) => {
+      const onResolve = (result: Result|undefined) => {
         resolve(result)
         this.onClose()
         this.clearRequest()