@julseb-lib/react 0.0.85 → 0.0.87

package/dist/lib/components/Link/Link.tsx

@@ -1,68 +1,88 @@
-/*=============================================== Link component ===============================================*/
-
-import { forwardRef, type RefObject } from "react"
+import type { FC, Ref } from "react"
 import { Link as RouterLink, NavLink } from "react-router-dom"
 import type { ILibLink } from "./types"
 
 /**
- * @description Returns a Link component
- * @link https://documentation-components-react.vercel.app/components/link
- * @extends HTMLDivElement
- * @prop data-testid?: string
- * @prop ref?: ForwardedRef<HTMLDivElement>
+ * Link component for rendering a button, anchor, NavLink, or RouterLink based on provided props.
+ *
+ * @component
+ * @extends HTMLButtonElement | HTMLAnchorElement
+ * @param {Object} props - Link props.
+ * @param {string} [props.data-testid] - Test id for testing purposes.
+ *  * @param {Ref<HTMLButtonElement | HTMLAnchorElement>} [props.ref] - Ref forwarded to the root element.
+ * @param {boolean} [props.isNavLink] - Render as a NavLink (from react-router-dom).
+ * @param {string} [props.to] - Target path for RouterLink or NavLink.
+ * @param {string} [props.href] - Href for anchor element.
+ * @param {() => void} [props.onClick] - Click handler for button element.
+ * @param {boolean} [props.blank] - Open link in new tab.
+ * @param {boolean} [props.end] - NavLink end prop.
+ * @param {any} [props.rest] - Additional props passed to the rendered element.
+ * @returns {JSX.Element|null} The rendered Link component.
+ *
+ * @see https://documentation-components-react.vercel.app/components/link
+ * @example
+ * <Link to="/about" isNavLink>About</Link>
+ * <Link href="https://example.com" blank>External</Link>
+ * <Link onClick={handleClick}>Button</Link>
  */
-export const Link = forwardRef<HTMLAnchorElement | HTMLButtonElement, ILibLink>(
-    (
-        { "data-testid": testid, isNavLink, to, href, onClick, blank, end, ...rest },
-        ref
-    ) => {
-        if (onClick)
-            return (
-                <button
-                    data-testid={testid}
-                    ref={ref as RefObject<HTMLButtonElement>}
-                    onClick={onClick}
-                    {...rest}
-                />
-            )
+export const Link: FC<ILibLink> = ({
+    "data-testid": testid,
+    as,
+    ref,
+    isNavLink,
+    to,
+    href,
+    onClick,
+    blank,
+    end,
+    ...rest
+}) => {
+    if (onClick)
+        return (
+            <button
+                data-testid={testid}
+                ref={ref as Ref<HTMLButtonElement>}
+                onClick={onClick}
+                {...rest}
+            />
+        )
 
-        if (href)
-            return (
-                <a
-                    data-testid={testid}
-                    ref={ref as RefObject<HTMLAnchorElement>}
-                    href={href}
-                    target={blank ? "_blank" : undefined}
-                    rel={blank ? "noreferrer noopener" : undefined}
-                    {...rest}
-                />
-            )
+    if (href)
+        return (
+            <a
+                data-testid={testid}
+                ref={ref as Ref<HTMLAnchorElement>}
+                href={href}
+                target={blank ? "_blank" : undefined}
+                rel={blank ? "noreferrer noopener" : undefined}
+                {...rest}
+            />
+        )
 
-        if (isNavLink && to)
-            return (
-                <NavLink
-                    data-testid={testid}
-                    ref={ref as RefObject<HTMLAnchorElement>}
-                    to={to}
-                    target={blank ? "_blank" : undefined}
-                    rel={blank ? "noreferrer noopener" : undefined}
-                    end={end}
-                    {...rest}
-                />
-            )
+    if (isNavLink && to)
+        return (
+            <NavLink
+                data-testid={testid}
+                ref={ref as Ref<HTMLAnchorElement>}
+                to={to}
+                target={blank ? "_blank" : undefined}
+                rel={blank ? "noreferrer noopener" : undefined}
+                end={end}
+                {...rest}
+            />
+        )
 
-        if (to)
-            return (
-                <RouterLink
-                    data-testid={testid}
-                    ref={ref as RefObject<HTMLAnchorElement>}
-                    to={to}
-                    target={blank ? "_blank" : undefined}
-                    rel={blank ? "noreferrer noopener" : undefined}
-                    {...rest}
-                />
-            )
+    if (to)
+        return (
+            <RouterLink
+                data-testid={testid}
+                ref={ref as Ref<HTMLAnchorElement>}
+                to={to}
+                target={blank ? "_blank" : undefined}
+                rel={blank ? "noreferrer noopener" : undefined}
+                {...rest}
+            />
+        )
 
-        return null
-    }
-)
+    return null
+}

package/dist/lib/components/Link/index.ts

@@ -1,3 +1 @@
-/*=============================================== Link exports ===============================================*/
-
 export * from "./Link"

package/dist/lib/components/Link/types.ts

@@ -1,5 +1,3 @@
-/*=============================================== Link types ===============================================*/
-
 import type { LibComponentBase, LibButtonLinkBlank } from "../../types"
 
 export type ILibLink = LibComponentBase<HTMLAnchorElement | HTMLButtonElement> &

package/dist/lib/components/Linkify/Linkify.tsx

@@ -1,6 +1,4 @@
-/*=============================================== Linkify component ===============================================*/
-
-import { forwardRef, Fragment } from "react"
+import { Fragment, type FC } from "react"
 import { uuid } from "@julseb-lib/utils"
 import { Text } from "../../"
 import type { ILibLinkify } from "./types"
@@ -9,23 +7,32 @@ const URL_REGEX =
     /^(http:\/\/www\.|https:\/\/www\.|http:\/\/|https:\/\/)?[a-z0-9]+([\-\.]{1}[a-z0-9]+)*\.[a-z]{2,5}(:[0-9]{1,5})?(\/.*)?$/gm
 
 /**
- * @description Transform `http://<url>` to `<a href="http://<url>">http://<url></a>`
- * @link https://documentation-components-react.vercel.app/components/linkify
+ * Linkify component for transforming URLs in text into clickable anchor links.
+ *
+ * @component
  * @extends ILibText
- * @prop data-testid?: string
- * @prop as?: ElementType
- * @prop ref?: ForwardedRef<HTMLHeadingElement & HTMLParagraphElement & HTMLQuoteElement & HTMLUListElement & HTMLOListElement & HTMLDListElement>
- * @prop blank?: boolean
+ * @param {Object} props - Linkify props.
+ * @param {string} [props.data-testid] - Test id for testing purposes.
+ *  * @param {ElementType} [props.as] - Custom element type to render as.
+ *  * @param {Ref<HTMLHeadingElement & HTMLParagraphElement & HTMLQuoteElement & HTMLUListElement & HTMLOListElement & HTMLDListElement>} [props.ref] - Ref forwarded to the root element.
+ * @param {boolean} [props.blank] - Open links in a new tab.
+ * @param {string} [props.className] - Additional class names.
+ *  * @param {ReactNode} [props.children] - Text content to linkify.
+ * @returns {JSX.Element} The rendered Linkify component.
+ *
+ * @see https://documentation-components-react.vercel.app/components/linkify
+ * @example
+ * <Linkify>
+ *   Visit http://example.com for more info.
+ * </Linkify>
  */
-export const Linkify = forwardRef<
-    HTMLHeadingElement &
-        HTMLParagraphElement &
-        HTMLQuoteElement &
-        HTMLUListElement &
-        HTMLOListElement &
-        HTMLDListElement,
-    ILibLinkify
->(({ children, blank, className, ...rest }, ref) => {
+export const Linkify: FC<ILibLinkify> = ({
+    children,
+    blank,
+    className,
+    ref,
+    ...rest
+}) => {
     const words: Array<string> = children ? children.split(" ") : []
 
     return (
@@ -48,4 +55,4 @@ export const Linkify = forwardRef<
             )}
         </Text>
     )
-})
+}

package/dist/lib/components/Linkify/index.ts

@@ -1,3 +1 @@
-/*=============================================== Linkify exports ===============================================*/
-
 export * from "./Linkify"

package/dist/lib/components/Linkify/types.ts

@@ -1,5 +1,3 @@
-/*=============================================== Linkify types ===============================================*/
-
 import type { ILibText } from "../Text/types"
 
 export type ILibLinkify = ILibText & {

package/dist/lib/components/ListGroup/ListGroup.tsx

@@ -1,6 +1,4 @@
-/*=============================================== ListGroup component ===============================================*/
-
-import { forwardRef, useRef } from "react"
+import { useRef, type FC } from "react"
 import classNames from "classnames"
 import { uuid } from "@julseb-lib/utils"
 import { useMergeRefs } from "../../hooks"
@@ -10,104 +8,103 @@ import { StyledListGroup } from "./styles"
 import type { ILibListGroup } from "./types"
 
 /**
- * @description Returns a ListGroup component
- * @link https://documentation-components-react.vercel.app/components/list-group
+ * ListGroup component for rendering a styled list with optional title, separators, numbering, and flexible items or custom children.
+ *
+ * @component
  * @extends HTMLDivElement
- * @prop data-testid?: string
- * @prop as?: ElementType
- * @prop ref?: ForwardedRef<HTMLDivElement>
- * @prop items: Array<LibListGroupItem> => only if children is not defined
- * @prop children?: ReactChildren => only if items is not defined
- * @prop title?: string | { text: string; backgroundColor?: Any color from the library; contentColor?: Any color from the library; isFixed?: boolean; id?: string; className?: string; ref?: ForwardedRef<HTMLDivElement>; shadowOnScroll?: "xxl" | "xl" | "l" | "m" | "s" | "xs" }
- * @prop noSeparator?: boolean
- * @prop showNumbers?: boolean
- * @prop maxHeight?: number | string
+ * @param {Object} props - ListGroup props.
+ * @param {string} [props.data-testid] - Test id for testing purposes.
+ *  * @param {ElementType} [props.as] - Custom element type to render as.
+ *  * @param {Ref<HTMLDivElement>} [props.ref] - Ref forwarded to the root element.
+ * @param {string} [props.className] - Additional class names.
+ * @param {Array<LibListGroupItem>} [props.items] - Array of list group items (used if children is not provided).
+ *  * @param {ReactNode} [props.children] - Custom list content (used if items is not provided).
+ * @param {string | Object} [props.title] - Title for the list group, or an object with text, backgroundColor, contentColor, isFixed, id, className, ref, shadowOnScroll.
+ * @param {boolean} [props.noSeparator] - Hide separators between items.
+ * @param {boolean} [props.showNumbers] - Show item numbers.
+ * @param {number|string} [props.maxHeight] - Maximum height for the list group.
+ * @param {any} [props.rest] - Additional props passed to the root element.
+ * @returns {JSX.Element} The rendered ListGroup component.
  *
- * @type LibListGroupItem
- * @prop data-testid?: string
- * @prop className?: string
- * @prop id?: string
- * @prop ref?: ForwardedRef<HTMLLIElement>
- * @prop text: string
- * @prop subtext?: string
- * @prop badge?: boolean | { icon?: string | JSX.Element => only if `number` is not defined; number?: number => only if `icon` is not defined; backgroundColor?: LibAllColors; contentColor?: LibAllColors } => only if `date` is not defined
- * @prop date?: string | Date => only if `badge` is not defined
- * @prop onClick?: void => only if to or href are not defined
- * @prop disabled?: boolean => only if onClick is defined
- * @prop to?: string => only if onClick and href are not defined
- * @prop href?: string => only if onClick and to are not defined
- * @prop blank?: boolean => only if to or href are defined
+ * @see https://documentation-components-react.vercel.app/components/list-group
+ * @example
+ * <ListGroup
+ *   title="Fruits"
+ *   items={[
+ *     { text: "Apple" },
+ *     { text: "Banana", badge: { number: 2 } },
+ *     { text: "Orange", date: "2024-05-19" }
+ *   ]}
+ *   showNumbers
+ *   maxHeight={300}
+ * />
  */
-export const ListGroup = forwardRef<HTMLDivElement, ILibListGroup>(
-    (
-        {
-            "data-testid": testid,
-            className,
-            as,
-            children,
-            showNumbers,
-            items,
-            maxHeight,
-            title,
-            noSeparator,
-            ...rest
-        },
-        ref
-    ) => {
-        const listRef = useRef<HTMLDivElement>(null)
+export const ListGroup: FC<ILibListGroup> = ({
+    "data-testid": testid,
+    as,
+    ref,
+    className,
+    children,
+    showNumbers,
+    items,
+    maxHeight,
+    title,
+    noSeparator,
+    ...rest
+}) => {
+    const listRef = useRef<HTMLDivElement>(null)
 
-        return (
-            <StyledListGroup
-                data-testid={testid}
-                ref={useMergeRefs([ref, listRef])}
-                as={as}
-                className={className}
-                $maxHeight={maxHeight}
-                $hasTitleFixed={
-                    !!(title && typeof title === "object" && title.isFixed)
-                }
-                {...rest}
-            >
-                {title && (
-                    <ListGroupTitle
-                        data-testid={testid && `${testid}.ListGroupTitle`}
-                        className={className && "ListGroupTitle"}
-                        backgroundColor={
-                            typeof title === "object"
-                                ? title.backgroundColor
-                                : "primary"
-                        }
-                        contentColor={
-                            typeof title === "object"
-                                ? title.contentColor
-                                : "background"
-                        }
-                        noSeparator={noSeparator}
-                        isFixed={typeof title === "object" && title.isFixed}
-                        listRef={listRef}
-                        {...(title as any)}
-                    >
-                        {typeof title === "object" ? title.text : title}
-                    </ListGroupTitle>
-                )}
+    return (
+        <StyledListGroup
+            data-testid={testid}
+            ref={useMergeRefs([ref, listRef])}
+            as={as}
+            className={className}
+            $maxHeight={maxHeight}
+            $hasTitleFixed={
+                !!(title && typeof title === "object" && title.isFixed)
+            }
+            {...rest}
+        >
+            {title && (
+                <ListGroupTitle
+                    data-testid={testid && `${testid}.ListGroupTitle`}
+                    className={className && "ListGroupTitle"}
+                    backgroundColor={
+                        typeof title === "object"
+                            ? title.backgroundColor
+                            : "primary"
+                    }
+                    contentColor={
+                        typeof title === "object"
+                            ? title.contentColor
+                            : "background"
+                    }
+                    noSeparator={noSeparator}
+                    isFixed={typeof title === "object" && title.isFixed}
+                    listRef={listRef}
+                    {...(title as any)}
+                >
+                    {typeof title === "object" ? title.text : title}
+                </ListGroupTitle>
+            )}
 
-                {items?.map((item, i) => (
-                    <ListGroupItem
-                        data-testid={item["data-testid"] || testid}
-                        className={classNames(item.className, {
-                            ListGroupItem: !!className,
-                        })}
-                        id={item.id}
-                        ref={item.ref}
-                        item={item}
-                        number={showNumbers ? i + 1 : undefined}
-                        isInArray
-                        noSeparator={noSeparator}
-                        {...(item as any)}
-                        key={uuid()}
-                    />
-                )) ?? children}
-            </StyledListGroup>
-        )
-    }
-)
+            {items?.map((item, i) => (
+                <ListGroupItem
+                    data-testid={item["data-testid"] || testid}
+                    className={classNames(item.className, {
+                        ListGroupItem: !!className,
+                    })}
+                    id={item.id}
+                    ref={item.ref}
+                    item={item}
+                    number={showNumbers ? i + 1 : undefined}
+                    isInArray
+                    noSeparator={noSeparator}
+                    {...(item as any)}
+                    key={uuid()}
+                />
+            )) ?? children}
+        </StyledListGroup>
+    )
+}