Stack Modals
Overview:
Stack Modals is a lightweight and versatile JavaScript library for managing modals in web applications. It provides an easy-to-use interface for creating and managing a stack of modal dialogs, allowing for smooth and intuitive user experiences.
Features:
- Stack Management: Easily manage a stack of modals, enabling sequential display and dismissal.
- Customization: Customize the appearance and behavior of modals to suit your application's design and requirements.
- Event Handling: Handle modal events such as open, close, and overlay click with ease.
- Lightweight: Small footprint and minimal dependencies make it ideal for use in various web projects.
- Compatibility: Compatible with modern web browsers and frameworks, including React, Angular, and Vue.js.
- Dynamic Import Support: Enables dynamic import functionality, facilitating reduced initial bundle size and efficient loading of resources.
Installation:
You can install Stack Modals via npm:
npm install stack-modals
Or include it directly in your HTML:
<script src="https://unpkg.com/stack-modals/dist/stack-modals.min.js"></script>
Usage:
- Include the Stack Modals library in your project.
- Initialize the modal stack.
- Create and manage modals as needed.
import { StackModals, createModal } from 'stack-modals'
enum ModalName {
HELLO_MODAL = 'HELLO_MODAL',
BYE_MODAL = 'BYE_MODAL'
}
type HelloModalProps = {
title: string;
subtitle?: string;
}
type ByeModalProps = {
title: string;
exitText?: string;
}
/* Initial state with strongly typed values */
const initialState = {
/* With createModal() util: */
...createModal<ModalName.HELLO_MODAL, HelloModalProps>
(ModalName.HELLO_MODAL, { subtitle: 'Default Subtitle', title: 'Default Title' }),
/* Without util */
[ModalName.BYE_MODAL]: {
title: 'Bye!',
exitText: ':('
} as ByeModalProps
}
const { stack, addModal, updateModal, deleteModal, clearModals } = new StackModals(initialState)
/*
* Function addModal returns a key that (modalKey) can be used to:
* - delete modal from stack,
* - search the inside the stack (for getting passed paremetrs)
* - update the state of the current modal
* */
const modalKey = addModal('MODAL', { title: 'Title' })
/* Update case */
updateModal(modalKey, { title: '', subtitle: 'After update' });
/* Delete case */
deleteModal(modalKey)
/* Search in stack case */
stack.get(modalKey)
/*
* Using the function clearModals(), you can delete all modal windows based on their name.
* For example: clearModals(ModalName.HELLO_MODAL)
* shoud remove all windows with name ModalName.HELLO_MODAL from the stack
* */
clearModals(ModalName.HELLO_MODAL)Usage with ReactJS:
import { StackModals, createModal } from 'stack-modals'
import {useEffect, useState, FC} from "react";
import type {ModalNameType, ModalScheme, OpenModalFnResult} from "stack-modals/types";
/* All modal names enum */
enum ModalName {
CONFIRM = 'CONFIRM'
}
/* Specific modal props */
type ConfirmModalProps = {
title: string;
subtitle?: string;
}
/* All modal scheme based on ModalScheme*/
type GlobalModalState = {
[ModalName.CONFIRM]: ConfirmModalProps
}
/* Default modal props (for passing inside the stack render */
export type BaseModalProps<S extends ModalScheme = GlobalModalState> = {
modalKey: OpenModalFnResult<S>;
modalName: ModalNameType<S>;
onClose: (key: OpenModalFnResult<S>) => void;
};
const { stack, addModal, updateModal, addTrap, getModalName, deleteModal, clearModals } = new StackModals({
...createModal<'CONFIRM', ConfirmModalProps>('CONFIRM', { subtitle: 'Default Subtitle', title: 'Default Title' }),
})
// file modals/ConfirmModal.tsx
export const ConfirmModal: FC<ConfirmModalProps & BaseModalProps> = ({ modalKey, modalName, onClose, handleComplete, handleCancel, subtitle, title}) => {
return (
<YourCustomModalComponent modalName={modalName} modalKey={modalKey} onClose={onClose}>
<h3>Modal key: {modalKey}</h3>
<p>{title}</p>
<caption>{subtitle}</caption>
<button onClick={() => onClose(modalKey)}>close</button>
</YourCustomModalComponent>
)
}
// file modules/ModalModule.tsx (can be inserted in the top level of our App)
export const ModalModule: FC = () => {
const [openedModals, setOpenedModals] = useState(stack)
useEffect(() => {
const handler = (newStack: typeof stack) => {
setOpenedModals(() => new Map(newStack))
}
addTrap("add", handler)
addTrap("update", handler)
addTrap("delete", handler)
}, []);
return (
<div>
{Array.from(openedModals.entries()).map(([key, props]) => {
const name = getModalName(key)
const createDefaultProps = <T extends keyof GlobalModalState>(modalName: T) => ({
key,
modalName,
modalKey: key,
onClose: deleteModal,
...(props as GlobalModalState[T])
});
switch (name) {
case ModalName.CONFIRM:
return <ConfirmModal {...createDefaultProps(ModalName.CONFIRM)} />
default:
return null
}
})}
</div>
)
}
// file hooks/useModal.tsx
export const useModal = () => {
return {
openModal: addModal,
closeModal: deleteModal,
updateModal,
}
}Documentation:
For detailed documentation and examples, visit the Stack Modals GitHub repository.
Contributing:
Contributions are welcome! If you find any issues or have suggestions for improvements, please feel free to open an issue or submit a pull request on the Stack Modals GitHub repository.
License:
Stack Modals is licensed under the MIT License. See the LICENSE file for details.
Credits:
Stack Modals is developed and maintained by Your Name / Organization. Special thanks to all contributors who have helped make this project possible.
Support:
If you need assistance or have any questions, you can reach out to the maintainers via the GitHub repository.