@julseb-lib/react 0.1.3 → 0.1.4

package/src/lib/components/Masonry/__preview__/Masonry.preview.tsx

@@ -0,0 +1,58 @@
+import { Masonry, Image, uuid } from "../../../"
+import type { ILibMasonry } from "../../../types/components-props"
+import type { ComponentPreview } from "../../../../data/components"
+
+const images: Array<string> = [
+	"https://images.unsplash.com/photo-1636390785258-f59cd6883a03?ixid=MnwxMjA3fDB8MHxwaG90by1wYWdlfHx8fGVufDB8fHx8&ixlib=rb-1.2.1&auto=format&fit=crop&w=1470&q=80",
+	"https://images.unsplash.com/photo-1647599708318-1b267bf44fd2?ixlib=rb-1.2.1&ixid=MnwxMjA3fDB8MHx0b3BpYy1mZWVkfDEzfGJvOGpRS1RhRTBZfHxlbnwwfHx8fA%3D%3D&auto=format&fit=crop&w=800&q=60",
+	"https://images.unsplash.com/photo-1636390785299-b4df455163dd?ixid=MnwxMjA3fDB8MHxwaG90by1wYWdlfHx8fGVufDB8fHx8&ixlib=rb-1.2.1&auto=format&fit=crop&w=1470&q=80",
+	"https://images.unsplash.com/photo-1634705146926-b8fbca28f431?ixid=MnwxMjA3fDB8MHxwaG90by1wYWdlfHx8fGVufDB8fHx8&ixlib=rb-1.2.1&auto=format&fit=crop&w=1928&q=80",
+	"https://images.unsplash.com/photo-1647458792028-f9b3599d4208?ixlib=rb-1.2.1&ixid=MnwxMjA3fDB8MHx0b3BpYy1mZWVkfDEwfGJvOGpRS1RhRTBZfHxlbnwwfHx8fA%3D%3D&auto=format&fit=crop&w=800&q=60",
+	"https://images.unsplash.com/photo-1647725280666-bb7f94a15d69?ixlib=rb-1.2.1&ixid=MnwxMjA3fDB8MHx0b3BpYy1mZWVkfDF8Ym84alFLVGFFMFl8fGVufDB8fHx8&auto=format&fit=crop&w=800&q=60",
+	"https://images.unsplash.com/photo-1647831591495-2f9ce7dd3d1d?ixlib=rb-1.2.1&ixid=MnwxMjA3fDB8MHx0b3BpYy1mZWVkfDN8Ym84alFLVGFFMFl8fGVufDB8fHx8&auto=format&fit=crop&w=800&q=60",
+	"https://images.unsplash.com/photo-1647831570034-51d43eac0694?ixlib=rb-1.2.1&ixid=MnwxMjA3fDB8MHx0b3BpYy1mZWVkfDV8Ym84alFLVGFFMFl8fGVufDB8fHx8&auto=format&fit=crop&w=800&q=60",
+	"https://images.unsplash.com/photo-1647464884405-42bbd541bc17?ixlib=rb-1.2.1&ixid=MnwxMjA3fDB8MHx0b3BpYy1mZWVkfDd8Ym84alFLVGFFMFl8fGVufDB8fHx8&auto=format&fit=crop&w=800&q=60",
+	"https://images.unsplash.com/photo-1646330685088-d8a402b0dcc2?ixlib=rb-1.2.1&ixid=MnwxMjA3fDB8MHx0b3BpYy1mZWVkfDE5fGJvOGpRS1RhRTBZfHxlbnwwfHx8fA%3D%3D&auto=format&fit=crop&w=800&q=60",
+	"https://images.unsplash.com/photo-1636207543865-acf3ad382295?ixlib=rb-1.2.1&ixid=MnwxMjA3fDB8MHxwaG90by1wYWdlfHx8fGVufDB8fHx8&auto=format&fit=crop&w=1470&q=80",
+]
+
+export const masonryPreview: ComponentPreview<ILibMasonry> = {
+	name: "Masonry",
+	component: Masonry,
+	category: "components",
+	import: "Masonry",
+	additionalImports: null,
+	optionalImports: null,
+	propsImport: "ILibMasonry",
+	additionalTypeImports: null,
+	extends: ["HTMLDivElement"],
+	previews: [
+		{
+			demo: (
+				<Masonry col={3} gap="xl">
+					{images.map((image, i) => (
+						<Image src={image} alt={`Img ${i}`} key={uuid()} />
+					))}
+				</Masonry>
+			),
+		},
+	],
+	props: [
+		{
+			name: "col",
+			type: "number",
+			possibleValues: null,
+			defaultValue: "4",
+			description: "Number of columns in the masonry grid.",
+			isRequired: false,
+		},
+		{
+			name: "gap",
+			type: "string",
+			possibleValues: ["2xs", "xs", "sm", "md", "lg", "xl", "2xl"],
+			defaultValue: "lg",
+			description: "Gap between grid items.",
+			isRequired: false,
+		},
+	],
+}

package/src/lib/components/Masonry/types.ts

@@ -0,0 +1,8 @@
+import type { ReactNode } from "react"
+import type { LibComponentBase, LibSpacers } from "../../types"
+
+export interface ILibMasonry extends LibComponentBase<HTMLDivElement> {
+	children?: Array<ReactNode>
+	col?: number
+	gap?: LibSpacers
+}

package/src/lib/components/Masonry/utils.tsx

@@ -0,0 +1,28 @@
+import { useEffect, useRef, type ReactNode } from "react"
+
+export function useEventListener(
+	eventNames: keyof GlobalEventHandlersEventMap,
+	handler: () => void,
+	element = globalThis,
+) {
+	const savedHandler = useRef<() => void>(null)
+	useEffect(() => (savedHandler.current = handler), [handler])
+
+	useEffect(() => {
+		if (!element.addEventListener) return
+
+		const listener = (e: EventListenerOrEventListenerObject) =>
+			(savedHandler as any).current(e!)
+
+		for (const e of eventNames as any) element.addEventListener(e, listener)
+
+		return () => {
+			for (const e of eventNames as any)
+				element.removeEventListener(e, listener)
+		}
+	}, [element, eventNames])
+}
+
+export function fillCols(children: Array<ReactNode>, cols: Array<any>) {
+	children.forEach((child, i) => cols[i % cols.length].push(child))
+}

package/src/lib/components/Modal/Modal.tsx

@@ -0,0 +1,107 @@
+import { useRef, type FC } from "react"
+import { BiX } from "react-icons/bi"
+import { enableScroll } from "@julseb-lib/utils"
+import { useKeyPress, useClickOutside } from "../../hooks"
+import { clsx } from "../../utils"
+import type { ILibModal } from "./types"
+
+/**
+ * Modal component for displaying overlay content with backdrop, close functionality, and keyboard navigation support.
+ *
+ * @component
+ *
+ * @example
+ * <Modal
+ *   isOpen={isOpen}
+ *   setIsOpen={setIsOpen}
+ *   labelClose="Close dialog"
+ * >
+ *   <div className="bg-white p-6 rounded-lg">
+ *     <h2>Modal Content</h2>
+ *     <p>This is a modal dialog.</p>
+ *   </div>
+ * </Modal>
+ *
+ * @extends HTMLDivElement
+ *
+ * @prop {string} [props.className] - Additional CSS classes to apply to the modal container.
+ * @prop {React.ElementType} [props.element="div"] - HTML element type to render as the container.
+ * @prop {React.Ref<any>} [props.ref] - Ref to the modal element.
+ * @prop {React.ReactNode} [props.children] - Content to display inside the modal.
+ * @prop {boolean} [props.isOpen] - Whether the modal is currently visible.
+ * @prop {function} [props.setIsOpen] - Function to control the modal open/closed state.
+ * @prop {boolean} [props.disableEsc] - Whether to disable closing the modal with the Escape key.
+ * @prop {boolean} [props.hideCloseButton] - Whether to hide the close button in the modal.
+ * @prop {React.ReactNode} [props.closeIcon=<BiX size={32} />] - Custom close icon for the modal.
+ * @prop {string} [props.labelClose="Close modal"] - Aria label for the close button.
+ *
+ * @returns {JSX.Element} The rendered Modal component.
+ *
+ * @see https://doc-julseb-lib-react.vercel.app/components/modal
+ */
+export const Modal: FC<ILibModal> = ({
+	className,
+	element = "div",
+	ref,
+	children,
+	isOpen,
+	setIsOpen,
+	disableEsc,
+	hideCloseButton,
+	closeIcon = <BiX size={32} />,
+	labelClose = "Close modal",
+	...rest
+}) => {
+	const Element = element
+
+	const el = useRef<HTMLDivElement>(null)
+
+	const handleClose = () => {
+		if (isOpen) {
+			setIsOpen(false)
+			enableScroll()
+		}
+	}
+
+	useClickOutside(el as any, handleClose)
+	useKeyPress("Escape", () => {
+		if (isOpen && !disableEsc) handleClose()
+	})
+
+	return (
+		<Element
+			ref={ref}
+			className={clsx(
+				"top-0 left-0 z-999 fixed flex justify-center items-center bg-overlay-black-80 w-full h-svh",
+				isOpen && "open",
+				"invisible opacity-0 [&.open]:visible [&.open]:opacity-100",
+				"modal",
+				className,
+			)}
+			{...rest}
+		>
+			<button
+				className={clsx(
+					"top-2 right-2 z-10 absolute flex justify-center items-center size-12 text-white hover:text-gray-300 active:text-gray-100",
+					"modal-close",
+				)}
+				onClick={() => setIsOpen(false)}
+				aria-label={labelClose}
+				role="button"
+				type="button"
+			>
+				{closeIcon}
+			</button>
+
+			<div
+				ref={el}
+				className={clsx(
+					"z-0 relative flex justify-center items-center w-full max-w-[90%]",
+					"modal-content",
+				)}
+			>
+				{children}
+			</div>
+		</Element>
+	)
+}

package/src/lib/components/Modal/__preview__/Modal.preview.tsx

@@ -0,0 +1,125 @@
+import { useState, type FC } from "react"
+import {
+	Modal,
+	Button,
+	disableScroll,
+	Image,
+	Alert,
+	Text,
+	Flexbox,
+} from "../../../"
+import type { ILibModal } from "../../../types/components-props"
+import type { ComponentPreview } from "../../../../data/components"
+
+const Preview: FC<Omit<ILibModal, "isOpen" | "setIsOpen">> = props => {
+	const [isOpen, setIsOpen] = useState(false)
+
+	return (
+		<>
+			<Button
+				onClick={() => {
+					setIsOpen(true)
+					disableScroll()
+				}}
+			>
+				Open modal
+			</Button>
+
+			<Modal {...(props as any)} isOpen={isOpen} setIsOpen={setIsOpen} />
+		</>
+	)
+}
+
+export const modalPreview: ComponentPreview<ILibModal> = {
+	name: "Modal",
+	component: Modal,
+	category: "components",
+	import: "Modal",
+	additionalImports: [],
+	optionalImports: [],
+	propsImport: "ILibModal",
+	additionalTypeImports: [],
+	extends: ["HTMLDivElement"],
+	previews: [
+		{
+			previewTitle: "With image",
+			demo: (
+				<Preview>
+					<Image
+						src="/images/image-card.jpg"
+						alt="Img"
+						className="h-[90svh]"
+						fit="contain"
+					/>
+				</Preview>
+			),
+		},
+		{
+			previewTitle: "With alert",
+			demo: (
+				<Preview>
+					<Alert color="danger">
+						<Text>Modal text</Text>
+						<Flexbox gap="sm">
+							<Button color="danger">Button</Button>
+							<Button color="danger" variant="transparent">
+								Button
+							</Button>
+						</Flexbox>
+					</Alert>
+				</Preview>
+			),
+		},
+	],
+	props: [
+		{
+			name: "isOpen",
+			type: "boolean",
+			possibleValues: [],
+			defaultValue: null,
+			description: "Whether the modal is currently visible.",
+			isRequired: true,
+		},
+		{
+			name: "setIsOpen",
+			type: "function",
+			possibleValues: [],
+			defaultValue: null,
+			description: "Function to control the modal open/closed state.",
+			isRequired: true,
+		},
+		{
+			name: "disableEsc",
+			type: "boolean",
+			possibleValues: [],
+			defaultValue: null,
+			description:
+				"Whether to disable closing the modal with the Escape key.",
+			isRequired: false,
+		},
+		{
+			name: "hideCloseButton",
+			type: "boolean",
+			possibleValues: [],
+			defaultValue: null,
+			description: "Whether to hide the close button in the modal.",
+			isRequired: false,
+		},
+		{
+			name: "closeIcon",
+			type: "ReactElement",
+			possibleValues: [],
+			defaultValue: null,
+			description: "Custom close icon for the modal.",
+			isRequired: false,
+		},
+		{
+			name: "labelClose",
+			type: "string",
+			possibleValues: [],
+			defaultValue: "Close modal",
+			description: "Aria label for the close button.",
+			isRequired: false,
+		},
+	],
+}

package/src/lib/components/Modal/types.ts

@@ -0,0 +1,21 @@
+import type { DispatchState, LibComponentBase, ReactElement } from "../../types"
+
+interface ILibModalBase extends LibComponentBase<HTMLDivElement> {
+	isOpen: boolean
+	setIsOpen: DispatchState<boolean>
+	disableEsc?: boolean
+}
+
+interface ModalWithCloseButton extends ILibModalBase {
+	hideCloseButton?: false | undefined
+	closeIcon?: ReactElement
+	labelClose?: string
+}
+
+interface ModalWithoutCloseButton extends ILibModalBase {
+	hideCloseButton?: true
+	closeIcon?: never
+	labelClose?: never
+}
+
+export type ILibModal = ModalWithCloseButton | ModalWithoutCloseButton

package/src/lib/components/PageLoading/PageLoading.tsx

@@ -0,0 +1,64 @@
+import { useEffect, type FC } from "react"
+import { disableScroll } from "@julseb-lib/utils"
+import { Loader } from "../Loader"
+import { clsx, genBgAllColors } from "../../utils"
+import type { ILibPageLoading } from "./types"
+
+/**
+ * PageLoading component for displaying a full-screen loading overlay with customizable background and loader.
+ *
+ * @component
+ *
+ * @example
+ * <PageLoading
+ *   backgroundColor="primary-500"
+ *   loaderColor="white"
+ *   loaderVariant={2}
+ *   stopScrolling
+ * />
+ *
+ * @extends HTMLDivElement
+ *
+ * @prop {string} [props.className] - Additional CSS classes to apply to the page loading container.
+ * @prop {React.ElementType} [props.element="div"] - HTML element type to render as the container.
+ * @prop {React.Ref<any>} [props.ref] - Ref to the page loading element.
+ * @prop {LibColors} [props.backgroundColor="primary-500"] - Background color for the loading overlay.
+ * @prop {LibColorsShort} [props.loaderColor="white"] - Color of the loading spinner.
+ * @prop {1 | 2 | 3} [props.loaderVariant=1] - Visual variant of the loading spinner.
+ * @prop {boolean} [props.stopScrolling] - Whether to disable page scrolling while loading is visible.
+ *
+ * @returns {JSX.Element} The rendered PageLoading component.
+ *
+ * @see https://doc-julseb-lib-react.vercel.app/components/page-loading
+ */
+export const PageLoading: FC<ILibPageLoading> = ({
+	className,
+	element = "div",
+	ref,
+	backgroundColor = "primary-500",
+	loaderColor = "white",
+	loaderVariant = 1,
+	stopScrolling,
+	...rest
+}) => {
+	const Element = element
+
+	useEffect(() => {
+		if (stopScrolling) disableScroll()
+	}, [stopScrolling])
+
+	return (
+		<Element
+			ref={ref}
+			className={clsx(
+				"top-0 left-0 z-999 fixed flex justify-center items-center w-full h-svh",
+				genBgAllColors[backgroundColor],
+				"page-loading",
+				className,
+			)}
+			{...rest}
+		>
+			<Loader variant={loaderVariant} color={loaderColor} />
+		</Element>
+	)
+}

package/src/lib/components/PageLoading/__preview__/PageLoading.preview.tsx

@@ -0,0 +1,66 @@
+import { Link } from "react-router-dom"
+import { PageLoading, Text } from "../../../"
+import type { ILibPageLoading } from "../../../types/components-props"
+import type { ComponentPreview } from "../../../../data/components"
+
+export const pageLoadingPreview: ComponentPreview<ILibPageLoading> = {
+	name: "Page Loading",
+	component: PageLoading,
+	category: "components",
+	import: "PageLoading",
+	additionalImports: [],
+	optionalImports: [],
+	propsImport: "ILibPageLoading",
+	additionalTypeImports: [],
+	extends: ["HTMLDivElement"],
+	previews: [
+		{
+			demo: (
+				<Text>
+					<Link
+						to="/page-loading/demo"
+						target="_blank"
+						rel="noreferrer noopener"
+					>
+						Demo here
+					</Link>
+				</Text>
+			),
+		},
+	],
+	props: [
+		{
+			name: "backgroundColor",
+			type: "string",
+			possibleValues: "Any color from the library",
+			defaultValue: "primary-500",
+			description: "Background color for the loading overlay.",
+			isRequired: false,
+		},
+		{
+			name: "loaderColor",
+			type: "string",
+			possibleValues: "Any color from the library",
+			defaultValue: "white",
+			description: "Color of the loading spinner.",
+			isRequired: false,
+		},
+		{
+			name: "loaderVariant",
+			type: "number",
+			possibleValues: [1, 2, 3],
+			defaultValue: "1",
+			description: "Visual variant of the loading spinner.",
+			isRequired: false,
+		},
+		{
+			name: "stopScrolling",
+			type: "boolean",
+			possibleValues: [],
+			defaultValue: "false",
+			description:
+				"Whether to disable page scrolling while loading is visible.",
+			isRequired: false,
+		},
+	],
+}

package/src/lib/components/PageLoading/types.ts

@@ -0,0 +1,13 @@
+import type {
+	LibAllColors,
+	LibComponentBase,
+	LibLoaderVariant,
+} from "../../types"
+
+export interface ILibPageLoading extends LibComponentBase<HTMLDivElement> {
+	backgroundColor?: LibAllColors
+	loaderColor?: LibAllColors
+	loaderVariant?: LibLoaderVariant
+	stopScrolling?: boolean
+	children?: never
+}

package/src/lib/components/Pagination/Pagination.tsx

@@ -0,0 +1,163 @@
+import { type FC } from "react"
+import { BiLeftArrowAlt, BiRightArrowAlt } from "react-icons/bi"
+import { usePagination, useMaxWidth } from "../../hooks"
+import { PaginationButton } from "./PaginationButton"
+import { clsx } from "../../utils"
+import type { ILibPagination } from "./types"
+
+/**
+ * Pagination component for navigating through multiple pages of content with customizable styling and navigation controls.
+ *
+ * @component
+ *
+ * @example
+ * <Pagination
+ *   currentPage={currentPage}
+ *   setCurrentPage={setCurrentPage}
+ *   totalPages={20}
+ *   accentColor="primary"
+ *   pageLimit={5}
+ * />
+ *
+ * @extends HTMLDivElement
+ *
+ * @prop {string} [props.className] - Additional CSS classes to apply to the pagination container.
+ * @prop {React.ElementType} [props.element="div"] - HTML element type to render as the container.
+ * @prop {React.Ref<any>} [props.ref] - Ref to the pagination element.
+ * @prop {React.ReactNode} [props.children] - Child components to render when not using totalPages prop.
+ * @prop {LibAllColors} [props.accentColor="primary"] - Color theme for active page and hover states.
+ * @prop {number} [props.totalPages] - Total number of pages available for navigation.
+ * @prop {object} [props.icons] - Custom icons for previous and next navigation buttons.
+ * @prop {React.ReactNode} [props.icons.prev] - Custom icon for the previous page button.
+ * @prop {React.ReactNode} [props.icons.next] - Custom icon for the next page button.
+ * @prop {number} [props.pageLimit=5] - Maximum number of page buttons to display at once.
+ * @prop {number} [props.currentPage] - Current active page number.
+ * @prop {function} [props.setCurrentPage] - Function to update the current page state.
+ *
+ * @returns {JSX.Element} The rendered Pagination component.
+ *
+ * @see https://doc-julseb-lib-react.vercel.app/components/pagination
+ */
+export const Pagination: FC<ILibPagination> = ({
+	className,
+	element = "div",
+	ref,
+	children,
+	accentColor = "primary",
+	totalPages,
+	icons,
+	pageLimit = 5,
+	currentPage,
+	setCurrentPage,
+	...rest
+}) => {
+	const Element = element
+
+	const { handlePrev, handlePage, handleNext } = usePagination({
+		currentPage: currentPage!,
+		setCurrentPage: setCurrentPage!,
+		totalPages,
+	})
+
+	const getPaginationGroup = () => {
+		const start = Math.floor((currentPage! - 1) / pageLimit) * pageLimit
+
+		return new Array(pageLimit)
+			.fill(totalPages)
+			.map((_, i) => start + i + 1)
+			.filter(item => item <= (totalPages || 0))
+	}
+
+	const paginationGroup = getPaginationGroup()
+
+	const isMobile = useMaxWidth(600)
+
+	if (totalPages && totalPages <= 1) return null
+
+	return (
+		<Element
+			ref={ref}
+			className={clsx(
+				"flex justify-center w-full",
+				isMobile ? "gap-1" : "gap-2",
+				"pagination",
+				className,
+			)}
+			{...rest}
+		>
+			{totalPages ? (
+				<>
+					<PaginationButton
+						onClick={handlePrev}
+						isActive={false}
+						disabled={currentPage === 1}
+						accentColor={accentColor}
+					>
+						{icons?.prev ?? <BiLeftArrowAlt size={24} />}
+					</PaginationButton>
+
+					{paginationGroup[0] !== 1 && (
+						<>
+							<PaginationButton
+								isActive={currentPage === 1}
+								onClick={() => handlePage(1)}
+								accentColor={accentColor}
+							>
+								1
+							</PaginationButton>
+
+							<PaginationButton
+								accentColor={accentColor}
+								readOnly
+							>
+								...
+							</PaginationButton>
+						</>
+					)}
+
+					{paginationGroup.map(n => (
+						<PaginationButton
+							isActive={n === currentPage}
+							onClick={() => handlePage(n)}
+							accentColor={accentColor}
+							key={n}
+						>
+							{n}
+						</PaginationButton>
+					))}
+
+					{paginationGroup[paginationGroup.length - 1] !==
+						totalPages && (
+						<>
+							<PaginationButton
+								accentColor={accentColor}
+								readOnly
+							>
+								...
+							</PaginationButton>
+
+							<PaginationButton
+								isActive={currentPage === totalPages}
+								onClick={() => handlePage(totalPages)}
+								accentColor={accentColor}
+							>
+								{totalPages}
+							</PaginationButton>
+						</>
+					)}
+
+					<PaginationButton
+						onClick={handleNext}
+						isActive={false}
+						disabled={currentPage === totalPages}
+						accentColor={accentColor}
+					>
+						{icons?.next ?? <BiRightArrowAlt size={24} />}
+					</PaginationButton>
+				</>
+			) : (
+				children
+			)}
+		</Element>
+	)
+}