@julseb-lib/react 0.1.2 → 0.1.4

package/src/lib/components/ListGroup/ListGroup.tsx

@@ -0,0 +1,96 @@
+import { useRef, type FC } from "react"
+import { uuid } from "@julseb-lib/utils"
+import { clsx } from "../../utils"
+import { useMergeRefs } from "../../hooks"
+import { ListGroupTitle } from "./ListGroupTitle"
+import { ListGroupItem } from "./ListGroupItem"
+import type { ILibListGroup } from "./types"
+
+/**
+ * ListGroup component for displaying a structured list of items with optional title, numbering, and separators.
+ *
+ * @component
+ *
+ * @example
+ * <ListGroup
+ *   title="My List"
+ *   items={[
+ *     { title: "Item 1", body: "Description 1" },
+ *     { title: "Item 2", body: "Description 2" }
+ *   ]}
+ *   showNumbers
+ * />
+ *
+ * @extends HTMLDivElement
+ *
+ * @prop {string} [props.className] - Additional CSS classes to apply to the list group container.
+ * @prop {React.ElementType} [props.element="div"] - HTML element type to render as the container.
+ * @prop {React.Ref<any>} [props.ref] - Ref to the list group container element.
+ * @prop {React.ReactNode} [props.children] - Child components to render inside the list group.
+ * @prop {string | object} [props.title] - Title text or configuration object for the list group header.
+ * @prop {boolean} [props.noSeparator] - Whether to hide separators between list items.
+ * @prop {boolean} [props.showNumbers] - Whether to display numbers next to each list item.
+ * @prop {Array} [props.items] - Array of item objects to render as list items.
+ *
+ * @returns {JSX.Element} The rendered ListGroup component.
+ *
+ * @see https://doc-julseb-lib-react.vercel.app/components/list-group
+ */
+export const ListGroup: FC<ILibListGroup> = ({
+	className,
+	element = "div",
+	ref,
+	children,
+	title,
+	noSeparator,
+	showNumbers,
+	items,
+	...rest
+}) => {
+	const Element = element
+	const listRef = useRef<HTMLDivElement>(null)
+
+	return (
+		<Element
+			ref={useMergeRefs([ref, listRef])}
+			className={clsx(
+				"border border-gray-200 rounded-lg overflow-y-scroll",
+				"list-group-container",
+				className,
+			)}
+			{...rest}
+		>
+			{title && (
+				<ListGroupTitle
+					{...(title as any)}
+					isFixed={typeof title === "object" ? title.isFixed : false}
+					noSeparator={noSeparator}
+					listRef={listRef}
+					className={typeof title === "object" && title.className}
+					ref={typeof title === "object" ? title.ref : null}
+					shadow={
+						typeof title === "object"
+							? title.shadowOnScroll
+							: undefined
+					}
+				>
+					{typeof title === "object" ? title.text : title}
+				</ListGroupTitle>
+			)}
+
+			{items
+				? items.map((item, i) => (
+						<ListGroupItem
+							{...(item as any)}
+							key={uuid()}
+							title={item.title}
+							number={showNumbers ? i + 1 : undefined}
+							body={item.body}
+							contentRight={item.contentRight}
+							noSeparator={noSeparator}
+						/>
+					))
+				: children}
+		</Element>
+	)
+}

package/src/lib/components/ListGroup/ListGroupItem.tsx

@@ -0,0 +1,86 @@
+import { type FC } from "react"
+import { Text } from "../Text"
+import { clsx } from "../../utils"
+import type { ILibListGroupItem } from "./types"
+
+/**
+ * ListGroupItem component for rendering individual items within a list group with optional numbering, content, and separators.
+ *
+ * @component
+ *
+ * @example
+ * <ListGroupItem
+ *   title="Item Title"
+ *   body="Item description"
+ *   number={1}
+ *   contentRight={<Button>Action</Button>}
+ * />
+ *
+ * @extends HTMLDivElement
+ *
+ * @prop {string} [props.className] - Additional CSS classes to apply to the list item container.
+ * @prop {React.ElementType} [props.element="div"] - HTML element type to render as the container.
+ * @prop {React.Ref<any>} [props.ref] - Ref to the list item container element.
+ * @prop {React.ReactNode} [props.children] - Child components to render inside the list item.
+ * @prop {string} [props.title] - Title text to display for the list item.
+ * @prop {string} [props.body] - Body text or description to display below the title.
+ * @prop {React.ReactNode} [props.contentRight] - Content to display on the right side of the list item.
+ * @prop {boolean} [props.noSeparator] - Whether to hide the separator border between list items.
+ * @prop {number} [props.number] - Number to display before the title when using numbered lists.
+ *
+ * @returns {JSX.Element} The rendered ListGroupItem component.
+ *
+ * @see https://doc-julseb-lib-react.vercel.app/components/list-group
+ */
+export const ListGroupItem: FC<ILibListGroupItem> = ({
+	className,
+	element = "div",
+	ref,
+	children,
+	title,
+	body,
+	contentRight,
+	noSeparator,
+	number,
+	...rest
+}) => {
+	const Element = element
+
+	return (
+		<Element
+			ref={ref}
+			className={clsx(
+				"flex justify-between gap-2 p-2 w-full",
+				!noSeparator &&
+					"[&:not(:last-child)]:border-b [&:not(:last-child)]:border-b-gray-200",
+				"disabled:bg-gray-200 disabled:text-gray-500",
+				"list-group-item",
+				className,
+			)}
+			{...rest}
+		>
+			{children ?? (
+				<>
+					<div className="flex flex-col gap-0.5 content-wrapper grow">
+						{number ? (
+							<span className="inline-flex gap-2 title-wrapper">
+								<span className="number">{number}</span>
+								<Text tag="h6" className="title">
+									{title}
+								</Text>
+							</span>
+						) : (
+							<Text tag="h6" className="title">
+								{title}
+							</Text>
+						)}
+
+						{body && <Text className="body">{body}</Text>}
+					</div>
+
+					{contentRight}
+				</>
+			)}
+		</Element>
+	)
+}

package/src/lib/components/ListGroup/ListGroupTitle.tsx

@@ -0,0 +1,84 @@
+import { useEffect, useState, type FC } from "react"
+import { Text } from "../Text"
+import { clsx, genBoxShadow } from "../../utils"
+import type { ILibListGroupTitle } from "./types"
+
+/**
+ * ListGroupTitle component for rendering a styled header/title for list groups with optional fixed positioning and shadow effects.
+ *
+ * @component
+ *
+ * @example
+ * <ListGroupTitle
+ *   isFixed
+ *   shadow="lg"
+ *   listRef={listRef}
+ * >
+ *   My List Title
+ * </ListGroupTitle>
+ *
+ * @extends HTMLDivElement
+ *
+ * @prop {string} [props.className] - Additional CSS classes to apply to the title container.
+ * @prop {React.ElementType} [props.element=Text] - HTML element type to render as the container.
+ * @prop {React.Ref<any>} [props.ref] - Ref to the title element.
+ * @prop {React.ReactNode} [props.children] - Content to display inside the title.
+ * @prop {boolean} [props.isFixed] - Whether the title should be sticky positioned at the top.
+ * @prop {"xs" | "sm" | "md" | "lg" | "xl" | "2xl" | "inner" | "none"} [props.shadow] - Shadow variant to apply when scrolled.
+ * @prop {React.RefObject} [props.listRef] - Ref to the scrollable list container for scroll detection.
+ * @prop {boolean} [props.noSeparator] - Whether to hide the bottom border separator.
+ *
+ * @returns {JSX.Element} The rendered ListGroupTitle component.
+ *
+ * @see https://doc-julseb-lib-react.vercel.app/components/list-group
+ */
+export const ListGroupTitle: FC<ILibListGroupTitle> = ({
+	className,
+	element = Text,
+	ref,
+	children,
+	isFixed,
+	shadow,
+	listRef,
+	noSeparator,
+	...rest
+}) => {
+	const Element = element
+	const [isScrolled, setIsScrolled] = useState(false)
+
+	useEffect(() => {
+		if (listRef && typeof listRef !== "function" && listRef.current) {
+			const handleScroll = () => {
+				const scroll = listRef.current?.scrollTop
+
+				if (scroll && scroll >= 24) {
+					setIsScrolled(true)
+				} else {
+					setIsScrolled(false)
+				}
+			}
+			listRef.current.addEventListener("scroll", handleScroll)
+			return () => {
+				listRef.current?.removeEventListener("scroll", handleScroll)
+			}
+		}
+	}, [])
+
+	return (
+		<Element
+			ref={ref}
+			tag="h6"
+			className={clsx(
+				"bg-primary-500 p-3 w-full font-black text-white text-left transition-shadow duration-200",
+				!noSeparator && "border-b-gray-200 border-b",
+				isFixed && "sticky top-0 left-0",
+				isScrolled && shadow && genBoxShadow[shadow],
+				"list-group-title",
+				className,
+			)}
+			{...rest}
+		>
+			{children}
+		</Element>
+	)
+}

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

@@ -0,0 +1,246 @@
+import { Link } from "react-router-dom"
+import { BiStar } from "react-icons/bi"
+import { ListGroup, convertDateShort, Badge, Text } from "../../../"
+import type { LibListGroupItem } from "../../../types"
+import type { ILibListGroup } from "../../../types/components-props"
+import type { ComponentPreview } from "../../../../data/components"
+
+const items: Array<LibListGroupItem> = [
+	{
+		title: "Basic item",
+	},
+	{
+		title: "With text",
+		body: "And body",
+	},
+	{
+		title: "With badge and number",
+		contentRight: (
+			<Badge color="danger" className="px-2">
+				350
+			</Badge>
+		),
+	},
+	{
+		title: "With badge and icon",
+		contentRight: (
+			<Badge color="success">
+				<BiStar />
+			</Badge>
+		),
+		className: "bg-danger-500",
+	},
+	{
+		title: "With color badge",
+		contentRight: <Badge color="warning" />,
+	},
+	{
+		title: "Router link",
+		contentRight: (
+			<Text tag="small" color="gray">
+				{convertDateShort("2022-09-07")}
+			</Text>
+		),
+		body: "Body",
+		element: Link,
+		// @ts-ignore
+		to: "/",
+	},
+	{
+		title: "Anchor link",
+		contentRight: (
+			<Text tag="small" color="gray">
+				{convertDateShort("2022-09-07")}
+			</Text>
+		),
+		body: "Body",
+		element: "a",
+		// @ts-ignore
+		href: "#",
+	},
+	{
+		title: "Button",
+		contentRight: (
+			<Text tag="small" color="gray">
+				{convertDateShort("2022-09-07")}
+			</Text>
+		),
+		body: "Body",
+		element: "button",
+		// @ts-ignore
+		onClick: () => alert("Clicked!"),
+	},
+	{
+		title: "Button disabled",
+		contentRight: (
+			<Text tag="small" color="gray">
+				{convertDateShort("2022-09-07")}
+			</Text>
+		),
+		element: "button",
+		// @ts-ignore
+		onClick: () => alert("Clicked!"),
+		// @ts-ignore
+		disabled: true,
+	},
+]
+
+export const listGroupPreview: ComponentPreview<ILibListGroup> = {
+	name: "List Group",
+	component: ListGroup,
+	category: "components",
+	import: "ListGroup",
+	additionalImports: [],
+	optionalImports: ["ListGroupTitle", "ListGroupItem"],
+	propsImport: "ILibListGroup",
+	additionalTypeImports: ["LibListGroupItem"],
+	extends: ["HTMLDivElement"],
+	previews: [
+		{
+			previewTitle: "Default",
+			props: { items, title: "Hello World", showNumbers: true },
+		},
+		{
+			previewTitle: "With max height",
+			props: {
+				items,
+				title: {
+					text: "Title",
+					isFixed: true,
+					shadowOnScroll: "lg",
+					className: "bg-black",
+				},
+				className: "max-h-[300px]",
+				noSeparator: true,
+			},
+		},
+	],
+	propsTitle: "ListGroup",
+	props: [
+		{
+			name: "title",
+			type: "string | Object",
+			possibleValues: [],
+			defaultValue: null,
+			description:
+				"Title text or configuration object for the list group header.",
+			isRequired: false,
+		},
+		{
+			name: "noSeparator",
+			type: "boolean",
+			possibleValues: [],
+			defaultValue: null,
+			description: "Whether to hide separators between list items.",
+			isRequired: false,
+		},
+		{
+			name: "showNumbers",
+			type: "boolean",
+			possibleValues: [],
+			defaultValue: null,
+			description: "Whether to display numbers next to each list item.",
+			isRequired: false,
+		},
+		{
+			name: "items",
+			type: "Array of objects",
+			possibleValues: [],
+			defaultValue: null,
+			description: "Array of item objects to render as list items.",
+			isRequired: false,
+		},
+	],
+	propsSecondTitle: "ListGroupTitle",
+	propsSecond: [
+		{
+			name: "isFixed",
+			type: "boolean",
+			possibleValues: [],
+			defaultValue: null,
+			description:
+				"Whether the title should be sticky positioned at the top.",
+			isRequired: false,
+		},
+		{
+			name: "noSeparator",
+			type: "boolean",
+			possibleValues: [],
+			defaultValue: null,
+			description: "Whether to hide the bottom border separator.",
+			isRequired: false,
+		},
+		{
+			name: "shadow",
+			type: "string",
+			possibleValues: [
+				"xs",
+				"sm",
+				"md",
+				"lg",
+				"xl",
+				"2xl",
+				"inner",
+				"none",
+			],
+			defaultValue: null,
+			description: "Shadow variant to apply when scrolled.",
+			isRequired: false,
+		},
+		{
+			name: "listRef",
+			type: "Ref",
+			possibleValues: [],
+			defaultValue: null,
+			description:
+				"Ref to the scrollable list container for scroll detection.",
+			isRequired: false,
+		},
+	],
+	propsThirdTitle: "ListGroupItem",
+	propsThird: [
+		{
+			name: "title",
+			type: "ReactNode",
+			possibleValues: [],
+			defaultValue: null,
+			description: "Title text to display for the list item.",
+			isRequired: true,
+		},
+		{
+			name: "body",
+			type: "ReactNode",
+			possibleValues: [],
+			defaultValue: null,
+			description: "Body text or description to display below the title.",
+			isRequired: false,
+		},
+		{
+			name: "contentRight",
+			type: "ReactNode",
+			possibleValues: [],
+			defaultValue: null,
+			description:
+				"Content to display on the right side of the list item.",
+			isRequired: false,
+		},
+		{
+			name: "noSeparator",
+			type: "boolean",
+			possibleValues: [],
+			defaultValue: null,
+			description:
+				"Whether to hide the separator border between list items.",
+			isRequired: false,
+		},
+		{
+			name: "number",
+			type: "number",
+			possibleValues: [],
+			defaultValue: null,
+			description:
+				"Number to display before the title when using numbered lists.",
+			isRequired: false,
+		},
+	],
+}

package/src/lib/components/ListGroup/index.ts

@@ -0,0 +1,3 @@
+export * from "./ListGroup"
+export * from "./ListGroupTitle"
+export * from "./ListGroupItem"

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

@@ -0,0 +1,69 @@
+import type { Ref } from "react"
+import type {
+	ClassNames,
+	LibComponentBase,
+	LibListGroupItem,
+	LibShadows,
+	ReactChildren,
+} from "../../types"
+
+/*====================== ListGroup ======================*/
+
+interface ILibListGroupBase
+	extends Omit<LibComponentBase<HTMLDivElement>, "title"> {
+	title?:
+		| string
+		| {
+				text: string
+				isFixed?: boolean
+				className?: ClassNames
+				ref?: Ref<HTMLDivElement>
+				shadowOnScroll?: LibShadows
+		  }
+	noSeparator?: boolean
+	showNumbers?: boolean
+}
+
+interface ListGroupWithItems extends ILibListGroupBase {
+	items: Array<LibListGroupItem>
+	children?: never
+}
+
+interface ListGroupWithChildren extends ILibListGroupBase {
+	items?: never
+	children?: ReactChildren
+}
+
+export type ILibListGroup = ListGroupWithItems | ListGroupWithChildren
+
+/*====================== ListGroupTitle ======================*/
+
+interface ILibListGroupTitleBase extends LibComponentBase<HTMLDivElement> {
+	isFixed?: boolean
+	noSeparator?: boolean
+}
+
+interface ListGroupTitleWithShadow extends ILibListGroupTitleBase {
+	shadow?: LibShadows
+	listRef: Ref<HTMLDivElement>
+}
+
+interface ListGroupTitleWithoutShadow extends ILibListGroupTitleBase {
+	shadow?: null | undefined
+	listRef?: Ref<HTMLDivElement>
+}
+
+export type ILibListGroupTitle =
+	| ListGroupTitleWithShadow
+	| ListGroupTitleWithoutShadow
+
+/*====================== ListGroupItem ======================*/
+
+export interface ILibListGroupItem
+	extends Omit<LibComponentBase<HTMLDivElement>, "title"> {
+	title: ReactChildren
+	body?: ReactChildren
+	contentRight?: ReactChildren
+	noSeparator?: boolean
+	number?: number
+}

package/src/lib/components/Loader/Loader.tsx

@@ -0,0 +1,38 @@
+import { type FC } from "react"
+import { LoaderOne } from "./templates/LoaderOne"
+import { LoaderTwo } from "./templates/LoaderTwo"
+import { LoaderThree } from "./templates/LoaderThree"
+import type { ILibLoader } from "./types"
+
+/**
+ * Loader component for displaying a loading indicator with multiple style variants and color options.
+ *
+ * @component
+ *
+ * @example
+ * <Loader variant={2} color="primary" />
+ *
+ * @extends HTMLSpanElement
+ *
+ * @prop {1 | 2 | 3} [props.variant=1] Possible values: 1, 2, 3. - Loader variant style.
+ * @prop {string} [props.color="primary"] Any color from the library. - Loader color.
+ * @prop {string} [props.className] - Additional CSS classes to apply to the loader.
+ * @prop {keyof JSX.IntrinsicElements} [props.element="span"] - The HTML element to render as the loader.
+ * @prop {React.Ref<any>} [props.ref] - Ref to the loader element.
+ * @prop {any} [props.rest] - Additional props spread to the loader element.
+ *
+ * @returns {JSX.Element} The rendered Loader component.
+ *
+ * @see https://doc-julseb-lib-react.vercel.app/components/loader
+ */
+export const Loader: FC<ILibLoader> = ({ variant, ...rest }) => {
+	switch (variant) {
+		case 2:
+			return <LoaderTwo {...rest} />
+		case 3:
+			return <LoaderThree {...rest} />
+		case 1:
+		default:
+			return <LoaderOne {...rest} />
+	}
+}

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

@@ -0,0 +1,38 @@
+import { Loader } from "../../../"
+import type { ILibLoader } from "../../../types/components-props"
+import type { ComponentPreview } from "../../../../data/components"
+
+export const loaderPreview: ComponentPreview<ILibLoader> = {
+	name: "Loader",
+	component: Loader,
+	category: "components",
+	import: "Loader",
+	additionalImports: null,
+	optionalImports: null,
+	propsImport: "ILibLoader",
+	additionalTypeImports: null,
+	extends: ["HTMLSpanElement"],
+	previews: [
+		{ previewTitle: "Default", props: {} },
+		{ previewTitle: "Variant 2", props: { variant: 2 } },
+		{ previewTitle: "Variant 3", props: { variant: 3 } },
+	],
+	props: [
+		{
+			name: "variant",
+			type: "number",
+			possibleValues: ["1", "2", "3"],
+			defaultValue: "1",
+			description: "Loader variant style.",
+			isRequired: false,
+		},
+		{
+			name: "color",
+			type: "string",
+			possibleValues: "Any color from the library",
+			defaultValue: "primary",
+			description: "Loader color.",
+			isRequired: false,
+		},
+	],
+}

package/src/lib/components/Loader/templates/LoaderOne.tsx

@@ -0,0 +1,27 @@
+import { type FC } from "react"
+import { clsx } from "../../../utils"
+import { genBorderBottomColor } from "../utils/gen-border-bottom"
+import type { ILibLoader } from "../types"
+
+export const LoaderOne: FC<Omit<ILibLoader, "variant">> = ({
+	className,
+	element = "span",
+	ref,
+	color = "primary",
+	...rest
+}) => {
+	const Element = element
+
+	return (
+		<Element
+			ref={ref}
+			className={clsx(
+				"inline-block relative border-8 border-transparent rounded-full size-12 animate-spin",
+				genBorderBottomColor[color],
+				"loader loader-1",
+				className,
+			)}
+			{...rest}
+		/>
+	)
+}