@codeleap/portals 6.3.0

package/package.json

@@ -0,0 +1,32 @@
+{
+  "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": "6.3.0",
+    "@codeleap/config": "6.3.0",
+    "@codeleap/utils": "6.3.0",
+    "@codeleap/logger": "6.3.0",
+    "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": "6.3.0",
+    "@codeleap/utils": "6.3.0",
+    "@codeleap/logger": "6.3.0",
+    "typescript": "5.5.2",
+    "react": "19.1.0",
+    "nanostores": "*",
+    "@nanostores/react": "*"
+  }
+}

package/package.json.bak

@@ -0,0 +1,32 @@
+{
+  "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": "*"
+  }
+}

package/src/factors/alert.ts

@@ -0,0 +1,109 @@
+import { AnyFunction } from '@codeleap/types'
+import { Modal } from './modal'
+
+export type AlertType = 'info' | 'error' | 'warn' | 'ask' | 'custom'
+
+export type AlertOption = {
+  text: string
+  onPress?: AnyFunction
+  style?: 'destructive' | 'outline' | 'cancel' | 'default' | 'minimal'
+}
+
+export type AlertOptions = {
+  title?: string
+  body?: string
+  options?: AlertOption[]
+  onDismiss?: AnyFunction
+  type?: AlertType
+}
+
+/**
+ * Alert utility for displaying typed alert modals (info, error, warn, ask, custom).
+ * Provides convenient methods for common alert scenarios.
+ */
+export class Alert {
+  static modal: Modal<AlertOptions>
+
+  static openAlert(): Modal<AlertOptions> {
+    return Alert.modal
+  }
+
+  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')
+   */
+  ask(args: AlertOptions) {
+    const { title = 'Quick question', ...rest } = args
+
+    this.trigger({
+      ...rest,
+      title,
+      type: 'ask',
+    })
+  }
+
+  /**
+   * Opens an alert with 'error' type.
+   * @param args - Alert options (defaults title to 'Whoops!' and body to 'Something went wrong')
+   */
+  error(args: AlertOptions) {
+    const { title = 'Whoops!', body = 'Something went wrong', ...rest } = args
+
+    this.trigger({
+      ...rest,
+      title,
+      body,
+      type: 'error',
+    })
+  }
+
+  /**
+   * Opens an alert with 'warn' type.
+   * @param args - Alert options (defaults title to 'Hang on' and body to 'Are you sure?')
+   */
+  warn(args: AlertOptions) {
+    const { title = 'Hang on', body = 'Are you sure?', ...rest } = args
+
+    this.trigger({
+      ...rest,
+      title,
+      body,
+      type: 'warn',
+    })
+  }
+
+  /**
+   * Opens an alert with 'info' type.
+   * @param args - Alert options (defaults title to 'Hang on' and body to 'Are you sure?')
+   */
+  info(args: AlertOptions) {
+    const { title = 'Hang on', body = 'Are you sure?', ...rest } = args
+
+    this.trigger({
+      ...rest,
+      title,
+      body,
+      type: 'info',
+    })
+  }
+
+  /**
+   * Opens a custom alert with user-defined options and type.
+   * @param options - Custom alert options and additional properties
+   */
+  custom<T>(options: Partial<AlertOptions> & T) {
+    this.trigger({
+      ...(options as any),
+      type: 'custom',
+    })
+  }
+}
+
+/**
+ * Global alert instance for showing alerts throughout the app.
+ */
+export const alert = new Alert()

package/src/factors/bottomSheet.ts

@@ -0,0 +1,99 @@
+import { Portal } from '../lib/Portal'
+import { PortalConstructorParam, PortalConfig, PortalWrapperProps } from '../types'
+import { BottomSheetRef, BottomSheetWrapperProps } from '../globals'
+import { Keyof } from '@codeleap/types'
+import { ReactElement } from 'react'
+
+/**
+ * Bottom sheet portal for bottom-sliding panels.
+ * Extends Portal with bottom sheet-specific wrapper, configuration and ref methods.
+ *
+ * @template Params - Custom bottom sheet parameters
+ * @template Result - Type of result returned by request
+ * @template Metadata - Additional configuration metadata
+ */
+export class BottomSheet<Params = {}, Result = {}, Metadata = {}> extends Portal<Params, Result, Metadata, BottomSheetRef, BottomSheetWrapperProps> {
+  displayName = 'BottomSheet'
+
+  static WrapperComponent: (props: PortalWrapperProps<BottomSheetWrapperProps, BottomSheetRef>) => ReactElement = () => null
+
+  static DEFAULT_TRANSITION_DURATION = 200
+
+  protected get defaultTransitionDuration() {
+    return BottomSheet.DEFAULT_TRANSITION_DURATION
+  }
+
+  protected get wrapperComponent(): any {
+    return BottomSheet.WrapperComponent
+  }
+
+  static openKeyMethod: Keyof<BottomSheetRef>
+
+  static closeKeyMethod: Keyof<BottomSheetRef>
+
+  protected getDefaultConfig(): Partial<PortalConfig<Params, Metadata>> {
+    return {
+      rendersWhenHidden: true,
+      resetParamsOnClose: false,
+    } as Partial<PortalConfig<Params, Metadata>>
+  }
+
+  protected openBottomSheet() {
+    if (!!BottomSheet.openKeyMethod && !!this.ref?.current) {
+      this.ref?.current?.[BottomSheet.openKeyMethod as string]?.()
+    }
+  }
+
+  protected closeBottomSheet() {
+    if (!!BottomSheet.closeKeyMethod && !!this.ref?.current) {
+      this.ref?.current?.[BottomSheet.closeKeyMethod as string]?.()
+    }
+  }
+
+  protected handleOpen() {
+    this.openBottomSheet()
+  }
+
+  protected handleClose() {
+    this.closeBottomSheet()
+  }
+
+  /**
+   * Registers a callback to be called when bottom sheet opens.
+   * Overrides parent to ensure native open method is called.
+   * @param callback - Function to execute on open
+   * @returns The bottom sheet instance for chaining
+   */
+  onOpen(callback: (portal: Portal<Params, Result, Metadata, BottomSheetRef, BottomSheetWrapperProps>) => void) {
+    this.handleOpen = () => {
+      this.openBottomSheet()
+      callback(this)
+    }
+
+    return this
+  }
+
+  /**
+   * Registers a callback to be called when bottom sheet closes.
+   * Overrides parent to ensure native close method is called.
+   * @param callback - Function to execute on close
+   * @returns The bottom sheet instance for chaining
+   */
+  onClose(callback: (portal: Portal<Params, Result, Metadata, BottomSheetRef, BottomSheetWrapperProps>) => void) {
+    this.handleClose = () => {
+      this.closeBottomSheet()
+      callback(this)
+    }
+
+    return this
+  }
+}
+
+/**
+ * Factory function to create a new BottomSheet instance.
+ * @param idOrConfig - BottomSheet ID or configuration object
+ * @returns New BottomSheet instance
+ */
+export function bottomSheet<Params = {}, Result = {}, Metadata = {}>(idOrConfig?: PortalConstructorParam<Params, Metadata>) {
+  return new BottomSheet<Params, Result, Metadata>(idOrConfig)
+}

package/src/factors/drawer.ts

@@ -0,0 +1,37 @@
+import { ReactElement } from 'react'
+import { DrawerRef, DrawerWrapperProps } from '../globals'
+import { Portal } from '../lib/Portal'
+import { PortalConstructorParam, PortalWrapperProps } from '../types'
+
+/**
+ * Drawer portal for side-sliding panels.
+ * Extends Portal with drawer-specific wrapper and configuration.
+ *
+ * @template Params - Custom drawer parameters
+ * @template Result - Type of result returned by request
+ * @template Metadata - Additional configuration metadata
+ */
+export class Drawer<Params = {}, Result = {}, Metadata = {}> extends Portal<Params, Result, Metadata, DrawerRef, DrawerWrapperProps> {
+  displayName = 'Drawer'
+
+  static WrapperComponent: (props: PortalWrapperProps<DrawerWrapperProps, DrawerRef>) => ReactElement = () => null
+
+  static DEFAULT_TRANSITION_DURATION = 200
+
+  protected get defaultTransitionDuration() {
+    return Drawer.DEFAULT_TRANSITION_DURATION
+  }
+
+  protected get wrapperComponent(): any {
+    return Drawer.WrapperComponent
+  }
+}
+
+/**
+ * Factory function to create a new Drawer instance.
+ * @param idOrConfig - Drawer ID or configuration object
+ * @returns New Drawer instance
+ */
+export function drawer<Params = {}, Result = {}, Metadata = {}>(idOrConfig?: PortalConstructorParam<Params, Metadata>) {
+  return new Drawer<Params, Result, Metadata>(idOrConfig)
+}

package/src/factors/modal.ts

@@ -0,0 +1,37 @@
+import { ReactElement } from 'react'
+import { ModalRef, ModalWrapperProps } from '../globals'
+import { Portal } from '../lib/Portal'
+import { PortalConstructorParam, PortalWrapperProps } from '../types'
+
+/**
+ * Modal portal for centered overlay dialogs.
+ * Extends Portal with modal-specific wrapper and configuration.
+ *
+ * @template Params - Custom modal parameters
+ * @template Result - Type of result returned by request
+ * @template Metadata - Additional configuration metadata
+ */
+export class Modal<Params = {}, Result = {}, Metadata = {}> extends Portal<Params, Result, Metadata, ModalRef, ModalWrapperProps> {
+  displayName = 'Modal'
+
+  static WrapperComponent: (props: PortalWrapperProps<ModalWrapperProps, ModalRef>) => ReactElement = () => null
+
+  static DEFAULT_TRANSITION_DURATION = 200
+
+  protected get defaultTransitionDuration() {
+    return Modal.DEFAULT_TRANSITION_DURATION
+  }
+
+  protected get wrapperComponent(): any {
+    return Modal.WrapperComponent
+  }
+}
+
+/**
+ * Factory function to create a new Modal instance.
+ * @param idOrConfig - Modal ID or configuration object
+ * @returns New Modal instance
+ */
+export function modal<Params = {}, Result = {}, Metadata = {}>(idOrConfig?: PortalConstructorParam<Params, Metadata>) {
+  return new Modal<Params, Result, Metadata>(idOrConfig)
+}

package/src/globals.ts

@@ -0,0 +1,13 @@
+/* eslint-disable @typescript-eslint/no-empty-interface */
+
+export interface BottomSheetWrapperProps {}
+
+export interface BottomSheetRef {}
+
+export interface ModalWrapperProps {}
+
+export interface ModalRef {}
+
+export interface DrawerWrapperProps {}
+
+export interface DrawerRef {}

package/src/index.ts

@@ -0,0 +1,13 @@
+export * from './lib/Portal'
+export * from './lib/PortalRegistry'
+export * from './lib/PortalState'
+export * from './lib/PortalRequest'
+export * from './types/misc'
+export * from './types/portal'
+export * from './utils'
+// export * from './lib/modalFlow'
+export * from './factors/alert'
+export * from './factors/modal'
+export * from './factors/bottomSheet'
+export * from './factors/drawer'
+export * from './globals'

package/src/lib/Portal.tsx

@@ -0,0 +1,300 @@
+import React, { JSX, useLayoutEffect } from 'react'
+import { atom } from 'nanostores'
+import { useStore } from '@nanostores/react'
+import { AnyRecord, TypeGuards } from '@codeleap/types'
+import { logger } from '@codeleap/logger'
+import { randomId } from '../utils'
+import { PortalConfig, PortalConstructorParam, RenderPortalContent } from '../types'
+import { PortalRegistry } from './PortalRegistry'
+import { PortalState } from './PortalState'
+import { PortalRequest } from './PortalRequest'
+
+type IAtom<T> = ReturnType<typeof atom<T>>
+
+export const registeredIds = atom<string[]>([])
+
+/**
+ * Base class for creating portals (modal, drawer, bottom sheet, etc).
+ * Manages state, visibility, params and lifecycle of floating components.
+ *
+ * @template Params - Custom portal parameters
+ * @template Result - Type of result returned by request
+ * @template Metadata - Additional configuration metadata
+ * @template RefType - Type of wrapper component ref
+ * @template WrapperProps - Props for wrapper component
+ */
+export class Portal<Params = {}, Result = {}, Metadata = {}, RefType = any, WrapperProps = AnyRecord> extends PortalState<Params> {
+  displayName = 'Portal'
+
+  id: string
+
+  RenderContent: RenderPortalContent<Params, Result, RefType>
+
+  ref?: React.RefObject<RefType>
+
+  requestHandler: PortalRequest<Params, Result>
+
+  _config: PortalConfig<Params, Metadata>
+
+  _wrapperProps: IAtom<WrapperProps>
+
+  _lazyWrapperProps: (params: Params) => WrapperProps
+
+  static registry = new PortalRegistry<Portal<any, any, any>>()
+
+  static generateId = randomId
+
+  protected getDefaultConfig(): Partial<PortalConfig<Params, Metadata>> {
+    return {}
+  }
+
+  protected get registry(): PortalRegistry<any> {
+    return Portal.registry
+  }
+
+  protected get idGenerator(): () => string {
+    return Portal.generateId
+  }
+
+  protected get defaultTransitionDuration() {
+    return null
+  }
+
+  protected get wrapperComponent(): any {
+    return null
+  }
+
+  /**
+   * Sets the render function for portal content.
+   * @param render - Function that renders the portal content
+   * @returns The portal instance for chaining
+   */
+  content(render: RenderPortalContent<Params, Result, RefType>) {
+    this.RenderContent = render
+    return this
+  }
+
+  get resolve() {
+    return this.requestHandler.resolve
+  }
+
+  get reject() {
+    return this.requestHandler.reject
+  }
+
+  private onVisibilityChanged(visible: boolean, wasVisible: boolean) {
+    if (this._config.independent) {
+      return
+    }
+
+    if (visible) {
+      this.registry.push(this.id)
+    } else {
+      if (wasVisible && !visible) {
+        if (this.hasPendingRequest) {
+          this.requestHandler.resolve?.(null)
+          this.requestHandler.clearRequest()
+        }
+      }
+
+      this.registry.remove(this.id)
+    }
+  }
+
+  get stackIndex() {
+    return this.registry.getStackIndex(this.id)
+  }
+
+  constructor(idOrConfig?: PortalConstructorParam<Params, Metadata>) {
+    super()
+
+    const id = TypeGuards.isString(idOrConfig) ? idOrConfig : idOrConfig?.id
+    const config = TypeGuards.isObject(idOrConfig) ? idOrConfig : {}
+
+    this._config = {
+      initialParams: {} as Params,
+      startsOpen: false,
+      independent: false,
+      rendersWhenHidden: false,
+      metadata: {} as Metadata,
+      resetParamsOnClose: true,
+      transitionDuration: (this.constructor as any).DEFAULT_TRANSITION_DURATION,
+      ...this.getDefaultConfig(),
+      ...config,
+    }
+
+    this.initializeState({
+      initialParams: this._config.initialParams,
+      startsOpen: this._config.startsOpen,
+      resetParamsOnClose: this._config.resetParamsOnClose,
+      transitionDuration: this._config.transitionDuration,
+    })
+
+    this.id = id ?? this.idGenerator()
+
+    this.requestHandler = new PortalRequest<Params, Result>(
+      this.open.bind(this),
+      this.close.bind(this),
+    )
+
+    this._wrapperProps = atom({})
+    this.ref = React.createRef<RefType>()
+
+    this.registry.register(this.id, this)
+    registeredIds.set([...registeredIds.get(), this.id])
+
+    this.subscribe((visible, wasVisible) => {
+      this.onVisibilityChanged(visible, wasVisible)
+    })
+
+    this.Component = this.Component.bind(this)
+    this.useState = this.useState.bind(this)
+    this.useProps = this.useProps.bind(this)
+    this.toggle = this.toggle.bind(this)
+    this.open = this.open.bind(this)
+    this.close = this.close.bind(this)
+    this.setParams = this.setParams.bind(this)
+    this.resetParams = this.resetParams.bind(this)
+    this.getParams = this.getParams.bind(this)
+    this.request = this.request.bind(this)
+  }
+
+  /**
+   * Registers a callback to be called when portal closes.
+   * @param callback - Function to execute on close
+   * @returns The portal instance for chaining
+   */
+  onClose(callback: (portal: Portal<Params, Result, Metadata, RefType, WrapperProps>) => void) {
+    this.handleClose = () => callback(this)
+    return this
+  }
+
+  /**
+   * Registers a callback to be called when portal opens.
+   * @param callback - Function to execute on open
+   * @returns The portal instance for chaining
+   */
+  onOpen(callback: (portal: Portal<Params, Result, Metadata, RefType, WrapperProps>) => void) {
+    this.handleOpen = () => callback(this)
+    return this
+  }
+
+  /**
+   * Sets wrapper component props. Can be static or a function based on params.
+   * @param props - Props object or function that returns props
+   * @returns The portal instance for chaining
+   */
+  props(props: WrapperProps | ((params: Params) => WrapperProps)) {
+    if (TypeGuards.isFunction(props)) {
+      this._lazyWrapperProps = props
+    } else {
+      this._wrapperProps.set(props)
+    }
+
+    return this
+  }
+
+  /**
+   * React hook to update wrapper props with dependency tracking.
+   * @param props - Props to merge with existing wrapper props
+   * @param deps - Dependency array for effect
+   */
+  useProps(props: WrapperProps, deps: React.DependencyList = []) {
+    useLayoutEffect(() => {
+      this._wrapperProps.set({
+        ...this._wrapperProps.get(),
+        ...props,
+      })
+    }, deps)
+  }
+
+  /**
+   * React hook to access portal state (visibility and params).
+   * @returns Object with visible and params state
+   */
+  useState() {
+    const visible = useStore(this.visible)
+    const params = useStore(this.params)
+
+    return { visible, params }
+  }
+
+  get hasPendingRequest() {
+    return this.requestHandler.hasPendingRequest
+  }
+
+  /**
+   * Renders the portal component. Use this as a React component.
+   * @param props - Combined params and wrapper props
+   * @returns JSX element with portal content wrapped in wrapper component
+   */
+  Component(props?: Params & { portalProps?: WrapperProps }): JSX.Element {
+    const { visible, params } = this.useState()
+    const wrapperProps = useStore(this._wrapperProps)
+    const { portalProps = {}, ...propParams } = props || {}
+
+    const Content = this.RenderContent
+
+    if (!Content) {
+      logger.warn(`${this.displayName} ${this.id} has no content. Did you forget to call .content()?`)
+      return null
+    }
+
+    if (!visible && !this._config?.rendersWhenHidden) return null
+
+    const request = this.requestHandler.getRequestHandlers()
+
+    const lazyWrapperProps = this?._lazyWrapperProps ? this._lazyWrapperProps(params) : {}
+
+    const WrapperComponent = this.wrapperComponent
+
+    return <WrapperComponent
+      {...this._config}
+      {...this._wrapperProps}
+      {...portalProps}
+      {...wrapperProps}
+      {...lazyWrapperProps}
+      close={this.close}
+      open={this.open}
+      visible={visible}
+      toggle={this.toggle}
+      zIndex={this.stackIndex}
+      ref={this.ref}
+    >
+      <Content
+        visible={visible}
+        toggle={this.toggle}
+        close={this.close}
+        open={this.open}
+        setParams={this.setParams}
+        {...params}
+        {...(propParams ?? {})}
+        request={this.hasPendingRequest ? request : null}
+        nextOrToggle={this.toggle}
+        previousOrToggle={this.toggle}
+        ref={this.ref}
+      />
+    </WrapperComponent>
+  }
+
+  /**
+   * Creates a request promise that resolves when portal is closed with result.
+   * @param params - Parameters to pass to the portal
+   * @param force - Force new request even if one is pending
+   * @returns Promise that resolves with portal result
+   */
+  request(params?: Params, force = false) {
+    return this.requestHandler.request(params, force)
+  }
+
+  /**
+   * Global outlet component that renders all non-independent portals.
+   * Place this once in your app root.
+   * @returns JSX element rendering all registered portals
+   */
+  static GlobalOutlet() {
+    useStore(registeredIds)
+    const portals = Portal.registry.filter(p => !p._config?.independent)
+    return <>{portals.map(portal => <portal.Component key={portal.id} />)}</>
+  }
+}

package/src/lib/PortalRegistry.ts

@@ -0,0 +1,91 @@
+/**
+ * Registry for managing portal instances and their stacking order.
+ * Maintains a registry of portals by ID and tracks their z-index stack.
+ *
+ * @template T - Type of portal instances to manage
+ */
+export class PortalRegistry<T> {
+  private registry: Record<string, T> = {}
+
+  private stack: string[] = []
+
+  /**
+   * Registers a portal instance with an ID.
+   * @param id - Unique identifier for the portal
+   * @param instance - Portal instance to register
+   */
+  register(id: string, instance: T) {
+    this.registry[id] = instance
+  }
+
+  /**
+   * Unregisters a portal and removes it from the stack.
+   * @param id - Portal ID to unregister
+   */
+  unregister(id: string) {
+    delete this.registry[id]
+    this.remove(id)
+  }
+
+  /**
+   * Retrieves a portal instance by ID.
+   * @param id - Portal ID to retrieve
+   * @returns Portal instance or undefined
+   */
+  getInstance(id: string): T {
+    return this.registry[id]
+  }
+
+  /**
+   * Adds a portal ID to the top of the stack.
+   * @param id - Portal ID to push
+   */
+  push(id: string) {
+    this.stack.push(id)
+  }
+
+  /**
+   * Removes a portal ID from the stack and all portals above it.
+   * @param id - Portal ID to remove
+   */
+  remove(id: string) {
+    const index = this.stack.indexOf(id)
+    if (index > -1) {
+      this.stack = this.stack.slice(0, index)
+    }
+  }
+
+  /**
+   * Gets the stack index (z-index position) of a portal.
+   * @param id - Portal ID to find
+   * @returns Stack index or -1 if not found
+   */
+  getStackIndex(id: string): number {
+    return this.stack.indexOf(id)
+  }
+
+  /**
+   * Retrieves all registered portal instances.
+   * @returns Array of all portal instances
+   */
+  getAll(): T[] {
+    return Object.values(this.registry)
+  }
+
+  /**
+   * Filters portal instances by predicate function.
+   * @param predicate - Function to test each instance
+   * @returns Filtered array of portal instances
+   */
+  filter(predicate: (instance: T) => boolean): T[] {
+    return this.getAll().filter(predicate)
+  }
+
+  /**
+   * Clears all portals from registry and stack.
+   */
+  clear() {
+    this.registry = {}
+    this.stack = []
+  }
+}

package/src/lib/PortalRequest.ts

@@ -0,0 +1,87 @@
+/**
+ * Handles promise-based portal requests with resolve/reject semantics.
+ * Manages the async flow of opening a portal and waiting for a result.
+ *
+ * @template Params - Parameters for opening the portal
+ * @template Result - Type of result returned when request resolves
+ */
+export class PortalRequest<Params = {}, Result = {}> {
+  resolve: (result: Result) => void
+
+  reject: (reason: unknown) => void
+
+  private onOpen: (params?: Params) => Promise<void>
+
+  private onClose: () => Promise<void>
+
+  /**
+   * Creates a portal request handler.
+   * @param onOpen - Function to call when opening portal
+   * @param onClose - Function to call when closing portal
+   */
+  constructor(
+    onOpen: (params?: Params) => Promise<void>,
+    onClose: () => Promise<void>,
+  ) {
+    this.onOpen = onOpen
+    this.onClose = onClose
+  }
+
+  /**
+   * Checks if there's a pending request waiting for resolution.
+   * @returns True if request is pending
+   */
+  get hasPendingRequest() {
+    return !!this.resolve && !!this.reject
+  }
+
+  /**
+   * Creates a new request promise that opens the portal and waits for result.
+   * @param params - Parameters to pass when opening portal
+   * @param force - Force new request even if one is pending
+   * @returns Promise that resolves with portal result
+   */
+  request(params?: Params, force = false): Promise<Result> {
+    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) => {
+        resolve(result)
+        this.onClose()
+        this.clearRequest()
+      }
+
+      const onReject = (reason: unknown) => {
+        reject(reason)
+        this.onClose()
+        this.clearRequest()
+      }
+
+      this.resolve = onResolve
+      this.reject = onReject
+
+      this.onOpen(params)
+    })
+  }
+
+  /**
+   * Clears the current request resolve/reject handlers.
+   */
+  clearRequest() {
+    this.resolve = undefined
+    this.reject = undefined
+  }
+
+  /**
+   * Gets the current request handlers for resolve and reject.
+   * @returns Object with resolve and reject functions
+   */
+  getRequestHandlers() {
+    return {
+      resolve: this.resolve,
+      reject: this.reject,
+    }
+  }
+}

package/src/lib/PortalState.ts

@@ -0,0 +1,173 @@
+import { atom, onMount, task } from 'nanostores'
+import { TypeGuards } from '@codeleap/types'
+import { awaitTransition } from '../utils'
+
+type IAtom<T> = ReturnType<typeof atom<T>>
+
+function initAtomWithPromise<T>(a: IAtom<T>, promise: Promise<T>) {
+  onMount(a, () => {
+    task(async () => {
+      a.set(await promise)
+    })
+  })
+}
+
+export type PortalStateConfig<Params> = {
+  initialParams: Params | (() => Promise<Params>)
+  startsOpen: boolean | (() => Promise<boolean>)
+  resetParamsOnClose?: boolean
+  transitionDuration: number
+}
+
+/**
+ * Manages portal visibility and parameter state with nanostores.
+ * Handles opening, closing, toggling and parameter updates.
+ *
+ * @template Params - Type of parameters managed by the state
+ */
+export class PortalState<Params = {}> {
+  visible: IAtom<boolean>
+
+  params: IAtom<Params>
+
+  _initialParams: Params
+
+  private config: PortalStateConfig<Params>
+
+  /**
+   * Initializes the portal state with configuration.
+   * @param config - Configuration for initial state, visibility and params
+   */
+  initializeState(config: PortalStateConfig<Params>) {
+    this.config = config
+
+    const initialVisible = TypeGuards.isBoolean(config.startsOpen) ? config.startsOpen : false
+    const initialParams = TypeGuards.isFunction(config.initialParams)
+      ? {} as Params
+      : (config.initialParams ?? {}) as Params
+
+    this._initialParams = initialParams
+
+    this.visible = atom(initialVisible)
+    this.params = atom(initialParams)
+
+    if (TypeGuards.isFunction(config.startsOpen)) {
+      initAtomWithPromise(this.visible, config.startsOpen())
+    }
+
+    if (TypeGuards.isFunction(config.initialParams)) {
+      initAtomWithPromise(this.params, config.initialParams().then(p => {
+        this._initialParams = p
+        return p
+      }))
+    }
+  }
+
+  get isVisible() {
+    return this.visible.get()
+  }
+
+  get currentParams() {
+    return this.params.get()
+  }
+
+  private awaitTransition(count = 1) {
+    return awaitTransition(count, this.config.transitionDuration)
+  }
+
+  protected handleOpen() { }
+
+  /**
+   * Opens the portal with optional parameters.
+   * @param params - Parameters to merge with current params
+   */
+  async open(params?: Params) {
+    if (this.visible.get()) {
+      return
+    }
+
+    if (params) {
+      this.params.set({
+        ...this.params.get(),
+        ...params,
+      })
+    }
+
+    this.visible.set(true)
+
+    await this.awaitTransition()
+
+    this.handleOpen()
+  }
+
+  protected handleClose() { }
+
+  /**
+   * Closes the portal and optionally resets parameters.
+   */
+  async close() {
+    if (!this.visible.get()) {
+      return this.awaitTransition()
+    }
+
+    this.visible.set(false)
+
+    if (this.config.resetParamsOnClose) {
+      this.resetParams()
+    }
+
+    this.handleClose()
+
+    await this.awaitTransition()
+  }
+
+  /**
+   * Toggles portal visibility (opens if closed, closes if open).
+   */
+  toggle() {
+    if (this.visible.get()) {
+      return this.close()
+    } else {
+      return this.open()
+    }
+  }
+
+  /**
+   * Updates portal parameters by merging with current params.
+   * @param next - Partial params or updater function
+   */
+  setParams(next: Partial<Params> | ((prev: Params) => Partial<Params>)) {
+    const prev = this.params.get()
+
+    const patch = TypeGuards.isFunction(next) ? next(prev) : next
+
+    this.params.set({
+      ...prev,
+      ...patch,
+    })
+  }
+
+  /**
+   * Resets parameters to initial values.
+   */
+  resetParams() {
+    this.params.set(this._initialParams ?? {} as Params)
+  }
+
+  /**
+   * Gets current parameter values.
+   * @returns Current params object
+   */
+  getParams() {
+    return this.params.get()
+  }
+
+  /**
+   * Subscribes to visibility changes.
+   * @param callback - Function called when visibility changes
+   * @returns Unsubscribe function
+   */
+  subscribe(callback: (visible: boolean, wasVisible: boolean) => void) {
+    return this.visible.subscribe(callback)
+  }
+}

package/src/tests/Portal.spec.tsx

@@ -0,0 +1,229 @@
+import { describe, it, expect, beforeEach } from 'bun:test'
+import { renderHook, act } from '@testing-library/react'
+import React from 'react'
+import { modal } from '../factors/modal'
+
+describe('Portal', () => {
+  let testModal: ReturnType<typeof modal>
+
+  beforeEach(() => {
+    testModal = modal({ id: 'TEST_MODAL' })
+      .content((props) => {
+        const { visible, toggle, userId } = props
+        return (
+          <div>
+            <p data-testid='visibility'>{visible ? 'open' : 'closed'}</p>
+            <p data-testid='userId'>{userId}</p>
+            <button onClick={toggle}>Toggle</button>
+          </div>
+        )
+      })
+  })
+
+  describe('constructor', () => {
+    it('should create portal with default config', () => {
+      expect(testModal.id).toBe('TEST_MODAL')
+      expect(testModal.isVisible).toBe(false)
+    })
+
+    it('should create portal with auto-generated ID', () => {
+      const autoModal = modal()
+      expect(autoModal.id).toBeDefined()
+      expect(typeof autoModal.id).toBe('string')
+    })
+
+    it('should create portal with initial params', () => {
+      const modalWithParams = modal<{ theme: string }>({
+        initialParams: { theme: 'dark' },
+      })
+      expect(modalWithParams.currentParams.theme).toBe('dark')
+    })
+  })
+
+  describe('open and close', () => {
+    it('should open portal', async () => {
+      expect(testModal.isVisible).toBe(false)
+
+      await testModal.open()
+
+      expect(testModal.isVisible).toBe(true)
+    })
+
+    it('should close portal', async () => {
+      await testModal.open()
+      expect(testModal.isVisible).toBe(true)
+
+      await testModal.close()
+
+      expect(testModal.isVisible).toBe(false)
+    })
+
+    it('should toggle portal', async () => {
+      expect(testModal.isVisible).toBe(false)
+
+      await testModal.toggle()
+      expect(testModal.isVisible).toBe(true)
+
+      await testModal.toggle()
+      expect(testModal.isVisible).toBe(false)
+    })
+
+    it('should open with params', async () => {
+      await testModal.open({ userId: '123' })
+
+      expect(testModal.currentParams.userId).toBe('123')
+    })
+  })
+
+  describe('params management', () => {
+    it('should set params', () => {
+      testModal.setParams({ userId: '456' })
+
+      expect(testModal.currentParams.userId).toBe('456')
+    })
+
+    it('should set params with updater function', () => {
+      testModal.setParams({ count: 0 })
+
+      testModal.setParams((prev) => ({ count: prev.count + 1 }))
+
+      expect(testModal.currentParams.count).toBe(1)
+    })
+
+    it('should reset params', () => {
+      const modalWithDefaults = modal({
+        initialParams: { theme: 'dark' },
+      })
+
+      modalWithDefaults.setParams({ theme: 'light' })
+      expect(modalWithDefaults.currentParams.theme).toBe('light')
+
+      modalWithDefaults.resetParams()
+      expect(modalWithDefaults.currentParams.theme).toBe('dark')
+    })
+  })
+
+  describe('useState hook', () => {
+    it('should return visible and params', () => {
+      const { result } = renderHook(() => testModal.useState())
+
+      expect(result.current.visible).toBe(false)
+      expect(result.current.params).toBeDefined()
+    })
+
+    it('should update when portal opens', async () => {
+      const { result } = renderHook(() => testModal.useState())
+
+      expect(result.current.visible).toBe(false)
+
+      await act(async () => {
+        await testModal.open({ userId: '789' })
+      })
+
+      expect(result.current.visible).toBe(true)
+      expect(result.current.params.userId).toBe('789')
+    })
+  })
+
+  describe('request system', () => {
+    it('should resolve request', async () => {
+      interface ConfirmResult {
+        confirmed: boolean
+      }
+
+      const confirmModal = modal<{ message: string }, ConfirmResult>()
+        .content((props) => {
+          const { request, message } = props
+
+          return (
+            <div>
+              <p>{message}</p>
+              <button onClick={() => request?.resolve({ confirmed: true })}>
+                Yes
+              </button>
+            </div>
+          )
+        })
+
+      const requestPromise = confirmModal.request({ message: 'Continue?' })
+
+      // Simulate user clicking yes
+      await act(async () => {
+        confirmModal.resolve({ confirmed: true })
+      })
+
+      const result = await requestPromise
+
+      expect(result.confirmed).toBe(true)
+    })
+
+    it('should have pending request', async () => {
+      const confirmModal = modal()
+
+      expect(confirmModal.hasPendingRequest).toBe(false)
+
+      const promise = confirmModal.request()
+
+      expect(confirmModal.hasPendingRequest).toBe(true)
+
+      await act(async () => {
+        confirmModal.resolve(null)
+      })
+
+      await promise
+
+      expect(confirmModal.hasPendingRequest).toBe(false)
+    })
+  })
+
+  describe('lifecycle hooks', () => {
+    it('should call onOpen callback', async () => {
+      let openCalled = false
+
+      const hookModal = modal()
+        .onOpen(() => {
+          openCalled = true
+        })
+        .content(() => <div>Content</div>)
+
+      await hookModal.open()
+
+      expect(openCalled).toBe(true)
+    })
+
+    it('should call onClose callback', async () => {
+      let closeCalled = false
+
+      const hookModal = modal()
+        .onClose(() => {
+          closeCalled = true
+        })
+        .content(() => <div>Content</div>)
+
+      await hookModal.open()
+      await hookModal.close()
+
+      expect(closeCalled).toBe(true)
+    })
+  })
+
+  describe('props configuration', () => {
+    it('should set static props', () => {
+      const propsModal = modal()
+        .props({ title: 'Test Modal' })
+
+      expect(propsModal._wrapperProps.get().title).toBe('Test Modal')
+    })
+
+    it('should set dynamic props', async () => {
+      const dynamicModal = modal<{ itemName: string }>()
+        .props((params) => ({
+          title: `Editing ${params.itemName}`,
+        }))
+
+      // Dynamic props are evaluated in component render
+      // Just verify the function is set
+      expect(dynamicModal._lazyWrapperProps).toBeDefined()
+    })
+  })
+})

package/src/types/index.ts

@@ -0,0 +1 @@
+export * from './portal'

package/src/types/misc.ts

@@ -0,0 +1,8 @@
+import { AnyFunction } from '@codeleap/types'
+
+type AllButFirst<T extends any[]> = T extends [infer _, ...infer Rest] ? Rest : []
+
+export type ExcludeFromParam<
+  T extends AnyFunction,
+  E = any
+> = (p?: Exclude<Parameters<T>[0], E>, ...args: AllButFirst<Parameters<T>>) => ReturnType<T>

package/src/types/portal.ts

@@ -0,0 +1,39 @@
+import { Ref } from 'react'
+
+export type PortalParams<P = {}, Result = {}> = {
+  visible: boolean
+  toggle: () => void
+  close: () => void
+  open: () => void
+  setParams: (next: Partial<P> | ((prev: P) => Partial<P>)) => void
+  request?: {
+    resolve: (result: Result) => void
+    reject: (reason: unknown) => void
+  }
+} & P
+
+export type RenderPortalContent<Params = {}, Result = {}, RefType = any> = (
+  props: PortalParams<Params, Result>,
+  ref?: React.RefObject<RefType>
+) => React.ReactElement
+
+export type PortalConfig<P, M = {}> = {
+  initialParams?: P | (() => Promise<P>)
+  startsOpen?: boolean | (() => Promise<boolean>)
+  independent?: boolean
+  rendersWhenHidden?: boolean
+  metadata?: M
+  transitionDuration?: number
+  resetParamsOnClose?: boolean
+}
+
+export type PortalConstructorParam<Params = {}, Metadata = {}> = (Partial<PortalConfig<Params, Metadata>> & { id?: string }) | string
+
+export type PortalWrapperProps<P, R> = P & {
+  close: () => void
+  open: () => void
+  toggle: () => void
+  zIndex: number
+  visible: boolean
+  ref: Ref<R>
+}

package/src/utils.ts

@@ -0,0 +1,11 @@
+import { waitFor } from '@codeleap/utils'
+
+export const randomId = () => {
+  return Math.random().toString(36).slice(2, 9)
+}
+
+export async function awaitTransition(count?: number, duration = 1000) {
+  for (let i = 0; i < (count ?? 1); i++) {
+    await waitFor(duration)
+  }
+}