@fpkit/acss 0.5.8 → 0.5.9

package/src/components/breadcrumbs/breadcrumb.tsx

@@ -1,38 +1,38 @@
 // Code: Breadcrumb component
-import React from 'react'
-import UI from '#components/ui'
-import { Truncate } from '#libs/content'
-import Link from '#components/link/link'
+import React from "react";
+import UI from "#components/ui";
+import { Truncate } from "#libs/content";
+import Link from "#components/link/link";
 
 // TYPES
 
 type customRoute = {
   /** The path or id for routing */
-  path?: string
+  path?: string;
   /** The display name */
-  name: string
+  name: string;
   /** The url if linking out */
-  url?: string
-}
+  url?: string;
+};
 
 type BreadcrumbProps = {
   /** Array of custom route objects */
-  routes?: customRoute[]
+  routes?: customRoute[];
   /** Starting route node */
-  startRoute?: React.ReactNode
+  startRoute?: React.ReactNode;
   /* Starting route url */
-  startRouteUrl?: string
+  startRouteUrl?: string;
   /** Spacer node between routes */
-  spacer?: React.ReactNode
+  spacer?: React.ReactNode;
   /** String representing current route */
-  currentRoute?: string
+  currentRoute?: string;
   /** Prefix breadcrumb aria-label - "prefix breadcrumb" */
-  ariaLabelPrefix?: string
+  ariaLabelPrefix?: string;
   /** Truncate breadcrumb text after this length */
-  truncateLength?: number
+  truncateLength?: number;
   /** Link props for breadcrumb links */
-  linkProps?: React.ComponentProps<typeof Link>
-} & React.ComponentProps<typeof UI>
+  linkProps?: React.ComponentProps<typeof Link>;
+} & React.ComponentProps<typeof UI>;
 
 // Components
 
@@ -53,11 +53,17 @@ const Items = ({
   ...props
 }: React.ComponentProps<typeof UI>) => {
   return (
-    <li data-list="unstyled inline" {...props}>
+    <li
+      id={id}
+      style={styles}
+      className={classes}
+      data-list="unstyled inline"
+      {...props}
+    >
       {children}
     </li>
-  )
-}
+  );
+};
 
 /**
  * List component.
@@ -70,8 +76,8 @@ const List = ({ children, ...props }: React.ComponentProps<typeof UI>) => {
     <UI as="ol" data-list="unstyled inline" {...props}>
       {children}
     </UI>
-  )
-}
+  );
+};
 
 /**
  * Nav component.
@@ -93,8 +99,8 @@ const Nav = ({
     <UI as="nav" id={id} styles={styles} className={classes} {...props}>
       <List>{children}</List>
     </UI>
-  )
-}
+  );
+};
 
 /**
  * Navigation component for breadcrumbs.
@@ -110,7 +116,7 @@ const Nav = ({
  * @param props.children - Child components.
  */
 export const Breadcrumb = ({
-  startRoute = 'Home',
+  startRoute = "Home",
   startRouteUrl = "/",
   currentRoute,
   spacer = <>&#47;</>,
@@ -123,13 +129,13 @@ export const Breadcrumb = ({
   linkProps,
   ...props
 }: BreadcrumbProps): React.JSX.Element => {
-  const [currentPath, setCurrentPath] = React.useState('')
+  const [currentPath, setCurrentPath] = React.useState("");
   React.useEffect(() => {
-    const path = currentRoute || window.location.pathname
+    const path = currentRoute || window.location.pathname;
     if (path.length) {
-      setCurrentPath(path)
+      setCurrentPath(path);
     }
-  }, [currentRoute])
+  }, [currentRoute]);
 
   /**
    * Gets the path name for the given path segment.
@@ -138,23 +144,22 @@ export const Breadcrumb = ({
    * @returns The path name object for the given path segment.
    */
   const getPathName = (pathSegment: string): customRoute => {
-    const route = routes?.find((route) => route.path === pathSegment)
+    const route = routes?.find((route) => route.path === pathSegment);
 
     return {
       path: route?.path || pathSegment,
       name: route?.name || pathSegment,
       url: route?.url || pathSegment,
-    }
-  }
+    };
+  };
 
   /** Array of path segments from current path */
-  const segments = currentPath.split('/').filter((segment) => segment)
+  const segments = currentPath.split("/").filter((segment) => segment);
   /** Index of last item in segments array */
-  const lastSegment = segments.length - 1
+  const lastSegment = segments.length - 1;
 
   /** Unique id for breadcrumb */
-  const uuid = React.useId()
-
+  const uuid = React.useId();
 
   return currentPath.length ? (
     <Nav
@@ -165,62 +170,62 @@ export const Breadcrumb = ({
       aria-label={ariaLabelPrefix}
     >
       <Items key={`${startRoute}-${uuid}`}>
-        <Link href={startRouteUrl} {...linkProps}>{startRoute}</Link>
+        <Link href={startRouteUrl} {...linkProps}>
+          {startRoute}
+        </Link>
       </Items>
       <>
-      {segments.length ? (
-        segments.map((segment: any, index: number) => {
-          const currentSegment = getPathName(segment)
-          const { name, url, path } = currentSegment
-          return index === lastSegment ? (
-            <>
-              {typeof segments[lastSegment] === 'string' &&
-                segments[lastSegment].length > 3 &&
-                segments[lastSegment] !== segments[lastSegment - 1] && (
-                  <Items  key={`${path || index}-${uuid}`}>
-                     
-                      <span aria-hidden="true">{spacer}</span>
-                      <a
-                      href="#"
-                        aria-current="page"
-                        aria-label={
-                          name.length > truncateLength ? name : undefined
-                        }
-                      >
-                        {Truncate(decodeURIComponent(name), truncateLength)}
-                      </a>
-                     
-                  </Items>
-                )}
-            </>
-          ) : (
-            <Items key={`${currentSegment?.name}-${uuid}`}>
-              <span aria-hidden="true">{spacer}</span>
-              <span>
-                <Link
-                  href={url}
-                  aria-label={name.length > truncateLength ? name : undefined}
-                 {...linkProps}
-                >
-                  {Truncate(decodeURIComponent(name), truncateLength)}
-                </Link>
-              </span>
-            </Items>
-          );
-        })
-      ) : (
-        null
-      )}
+        {segments.length
+          ? segments.map((segment: string, index: number) => {
+              const currentSegment = getPathName(segment);
+              const { name, url, path } = currentSegment;
+              return index === lastSegment ? (
+                <>
+                  {typeof segments[lastSegment] === "string" &&
+                    segments[lastSegment].length > 3 &&
+                    segments[lastSegment] !== segments[lastSegment - 1] && (
+                      <Items key={`${path || index}-${uuid}`}>
+                        <span aria-hidden="true">{spacer}</span>
+                        <a
+                          href="#"
+                          aria-current="page"
+                          aria-label={
+                            name.length > truncateLength ? name : undefined
+                          }
+                        >
+                          {Truncate(decodeURIComponent(name), truncateLength)}
+                        </a>
+                      </Items>
+                    )}
+                </>
+              ) : (
+                <Items key={`${currentSegment?.name}-${uuid}`}>
+                  <span aria-hidden="true">{spacer}</span>
+                  <span>
+                    <Link
+                      href={url}
+                      aria-label={
+                        name.length > truncateLength ? name : undefined
+                      }
+                      {...linkProps}
+                    >
+                      {Truncate(decodeURIComponent(name), truncateLength)}
+                    </Link>
+                  </span>
+                </Items>
+              );
+            })
+          : null}
       </>
     </Nav>
   ) : (
     <></>
-  )
-}
+  );
+};
 
-export default Breadcrumb
+export default Breadcrumb;
 
-Breadcrumb.displayName = 'BreadCrumb'
-Breadcrumb.Nav = Nav
-Breadcrumb.List = List
-Breadcrumb.Items = Items
+Breadcrumb.displayName = "BreadCrumb";
+Breadcrumb.Nav = Nav;
+Breadcrumb.List = List;
+Breadcrumb.Items = Items;

package/src/components/cards/README.mdx

@@ -0,0 +1,133 @@
+import { Meta } from "@storybook/blocks";
+
+<Meta title="FP.REACT Components/Card/Readme" />
+
+# Card Component
+
+The Card component is a versatile and reusable React component for creating
+card-like UI elements. It's part of the FPKit React component library.
+
+## Usage
+
+```tsx
+import Card from "@fpkit/cards";
+
+<Card elm="div">
+  <Card.Title>Card Title</Card.Title>
+  <Card.Content
+    className="custom-card-content"
+    styles={{ color: "blue", padding: "1rem" }}
+  >
+    This is the content of the card.
+  </Card.Content>
+</Card>;
+```
+
+## Components
+
+### Card
+
+The main container component for the card.
+
+#### Props
+
+- `elm?: 'div' | 'aside' | 'section' | 'article'` - HTML element to render as
+  (default: 'div')
+- `title?: React.ReactNode` - Card title
+- `footer?: React.ReactNode` - Card footer
+- `styles?: React.CSSProperties` - Inline styles
+- `classes?: string` - Additional CSS classes
+- `id?: string` - Unique ID for the card
+
+All other props, such as `aria-*` attributes, `data-*` attributes, and event
+handlers (e.g., `onClick`, `onMouseEnter`), are passed through to the underlying
+UI component. This allows you to customize the behavior and accessibility of the
+Card component as needed.
+
+### Card.Title
+
+A sub-component for rendering the card's title.
+
+#### Props
+
+- `as?: React.ElementType` - HTML element to render as (default: 'h3')
+- `className?: string` - Additional CSS classes
+- `styles?: React.CSSProperties` - Inline styles
+
+#### Example
+
+### Card.Content
+
+A sub-component for rendering the card's main content.
+
+#### Props
+
+- `className?: string` - Additional CSS classes
+- `styles?: React.CSSProperties` - Inline styles
+
+## Styling
+
+The component uses CSS classes for styling:
+
+- `.card-title` for the title
+- `.card-content` for the content
+
+To integrate these styles with CSS Modules or SASS/SCSS:
+
+1. Create a CSS Module file (e.g., `Card.module.scss`) or a SASS/SCSS file
+   (e.g., `Card.scss`).
+
+## Accessibility
+
+The Card component is designed with accessibility in mind:
+
+- It uses semantic HTML elements (`div`, `aside`, `section`, or `article`) for
+  the main container.
+- The Title component defaults to using an `h3` element, which can be changed if
+  needed.
+- The Content component uses an `article` element for semantic structure.
+
+### Example with ARIA Attributes
+
+```tsx
+<Card classes={styles.card}>
+  <Card.Title className={styles.cardTitle}>Card Title</Card.Title>
+  <Card.Content className={styles.cardContent}>
+    This is the content of the card.
+  </Card.Content>
+</Card>
+```
+
+You can override these classes or provide additional styling through the
+`className` and `styles` props.
+
+## Accessibility
+
+The Card component is designed with accessibility in mind:
+
+- It uses semantic HTML elements (`div`, `aside`, `section`, or `article`) for
+  the main container.
+- The Title component defaults to using an `h3` element, which can be changed if
+  needed.
+- The Content component uses an `article` element for semantic structure.
+
+## TypeScript
+
+This component is written in TypeScript and provides type definitions for all
+props and sub-components.
+
+## Contributing
+
+When contributing to this component, please follow the established code style
+and conventions. Ensure all changes are well-tested using **Vitest** and
+documented. Additionally, use **ESLint** and **Prettier** for code formatting
+and linting to maintain consistency.
+
+This README provides an overview of the Card component, its usage, available
+props, styling information, and accessibility considerations. It also mentions
+that the component is written in TypeScript and provides guidance for
+contributors.
+
+```
+
+```

package/src/components/details/details.tsx

@@ -15,18 +15,25 @@ type DetailsProps = {
 } & React.ComponentProps<"details"> &
   Partial<React.ComponentProps<typeof UI>>;
 
-/**3
- * Details component props interface.
+/**
+ * A React component that renders a details element with a summary and content.
  *
- * @param {React.CSSProperties} [styles] - CSS styles object.
- * @param {string} [classes] - Classnames string.
- * @param {boolean} [open] - Whether the details is open.
- * @param {(e: React.PointerEvent<HTMLDetailsElement>) => void} [onToggle] - onToggle callback.
- * @param {(e: React.PointerEvent<HTMLDetailsElement>) => void} [onPointerDown] - onPointerDown callback.
- * @param {ReactNode} children - The content inside the details.
- * @param {string} [ariaLabel] - aria-label for accessibility.
- * @param {React.Ref<any>} [ref] - Ref object.
- * @param {Object} props - Other props.
+ * @param summary - The summary text shown for the details.
+ * @param ariaLabel - The aria-label element for accessibility.
+ * @param icon - An optional icon to display in the summary.
+ * @param styles - Optional styles to apply to the details element.
+ * @param classes - Optional CSS classes to apply to the details element.
+ * @param name - An optional name for the details element.
+ * @param open - Whether the details element should be initially open.
+ * @param onPointerDown - A callback function to be called when the summary is clicked.
+ * @param onToggle - A callback function to be called when the details element is toggled.
+ * @param children - The content to be displayed inside the details element.
+ * @param ref - A ref to the details element.
+ * @param props - Additional props to be passed to the details element.
+ * @example
+ * <Details summary="Details" ariaLabel="Details">
+ *   <p>Details content</p>
+ * </Details>
  */
 export const Details = ({
   summary,

package/src/components/form/inputs.tsx

@@ -1,25 +1,20 @@
-import React from 'react'
-import FP from '../fp'
+import React from "react";
+import FP from "../fp";
 
 export type InputProps = {
   /**
    * The type of the input.
    */
-  type?: 'text' | 'password' | 'email' | 'number' | 'tel' | 'url' | 'search'
+  type?: "text" | "password" | "email" | "number" | "tel" | "url" | "search";
 
   /**
    * Set the element as disabled
    */
-  isDisabled?: boolean
-} & React.ComponentProps<typeof FP>
+  isDisabled?: boolean;
+} & React.ComponentProps<typeof FP>;
 
-/**
- * Input component that renders an HTML input element.
- * @param {InputProps} props - The input component props.
- * @returns {JSX.Element} - The input component.
- */
 export const Input = ({
-  type = 'text',
+  type = "text",
   name,
   value,
   placeholder,
@@ -38,29 +33,29 @@ export const Input = ({
 }: InputProps): JSX.Element => {
   const handleChange = (e: React.ChangeEvent<HTMLInputElement>) => {
     if (onChange && !disabled) {
-      onChange?.(e)
+      onChange?.(e);
     }
-  }
+  };
 
   const handleBlur = (e: React.FocusEvent<HTMLInputElement>) => {
     if (onBlur && !disabled) {
-      onBlur?.(e)
+      onBlur?.(e);
     }
-  }
+  };
 
   const handleKeyDown = (e: React.KeyboardEvent<HTMLInputElement>) => {
     if (onPointerDown && !disabled) {
-      e.preventDefault()
-      onPointerDown?.(e)
+      e.preventDefault();
+      onPointerDown?.(e);
     }
-  }
+  };
 
   return (
     <FP
       as="input"
       id={id}
       type={type}
-      placeholder={placeholder || `${required ? '*' : ''} ${type} input `}
+      placeholder={placeholder || `${required ? "*" : ""} ${type} input `}
       className={classes}
       styles={styles}
       onChange={handleChange}
@@ -77,8 +72,7 @@ export const Input = ({
       readOnly={readonly}
       {...props}
     />
-  )
-}
-
-Input.displayName = 'Input'
-export default Input
+  );
+};
+Input.displayName = "Input";
+export default Input;

package/src/components/heading/heading.tsx

@@ -1,15 +1,27 @@
-import React from 'react'
-import UI from '#components/ui'
-import { type } from 'os'
+import React from "react";
+import UI from "#components/ui";
 
 export type TitleProps = {
-  children: React.ReactNode
-  type: 'h1' | 'h2' | 'h3' | 'h4' | 'h5' | 'h6'
-  ui?: string
-} & React.ComponentProps<typeof UI>
+  children: React.ReactNode;
+  type: "h1" | "h2" | "h3" | "h4" | "h5" | "h6";
+  ui?: string;
+} & React.ComponentProps<typeof UI>;
 
+/**
+ * A flexible heading component that renders different heading levels.
+ *
+ * @component
+ * @param {'h1' | 'h2' | 'h3' | 'h4' | 'h5' | 'h6'} [props.type='h3'] - The heading level to render
+ * @param {string} [props.id] - Optional ID attribute for the heading
+ * @param {React.CSSProperties} [props.styles] - Custom styles to apply to the heading
+ * @param {string} [props.ui] - Custom UI modifier to be added as a data attribute
+ * @param {ReactNode} props.children - The content to be rendered within the heading
+ * @param {Object} [props] - Additional props to be spread onto the heading element
+ *
+ * @returns {JSX.Element} A heading element of the specified type
+ */
 const Heading = ({
-  type = 'h3',
+  type = "h3",
   id,
   styles,
   ui,
@@ -20,8 +32,8 @@ const Heading = ({
     <UI as={type} id={id} styles={styles} data-ui={ui} {...props}>
       {children}
     </UI>
-  )
-}
+  );
+};
 
-export default Heading
-Heading.displayName = 'Heading'
+export default Heading;
+Heading.displayName = "Heading";

package/src/components/text/README.mdx

@@ -0,0 +1,98 @@
+import { Meta } from "@storybook/blocks";
+
+<Meta title="FP.REACT Components/Text/Readme" />
+
+# Text Component
+
+## Summary
+
+The `Text` component is a flexible wrapper for rendering various text elements
+such as paragraphs, spans, and other inline or block-level elements. It supports
+customization through props like `elm`, `text`, and additional styles or
+classes.
+
+The `Title` component is a specialized version of `Text` for rendering HTML
+headings (`h1` to `h6`).
+
+## Features
+
+- Render any valid HTML text element.
+- Pass text content directly or use children for nested elements.
+- Fully customizable with styles and classes.
+- Supports accessibility with `id` and other attributes.
+
+## Props
+
+### Text Props
+
+| Name       | Type                  | Default | Description                         |
+| ---------- | --------------------- | ------- | ----------------------------------- |
+| `elm`      | `TextElements`        | `'p'`   | The HTML element to render.         |
+| `text`     | `string`              | `''`    | Text content to display.            |
+| `id`       | `string`              | `''`    | Unique identifier for the element.  |
+| `styles`   | `React.CSSProperties` | `null`  | Inline styles for the element.      |
+| `classes`  | `string`              | `''`    | Additional CSS classes for styling. |
+| `children` | `React.ReactNode`     | `null`  | Nested content inside the element.  |
+
+### Title Props
+
+| Name       | Type                                           | Default | Description                         |
+| ---------- | ---------------------------------------------- | ------- | ----------------------------------- |
+| `elm`      | `'h1' \| 'h2' \| 'h3' \| 'h4' \| 'h5' \| 'h6'` | `'h3'`  | The HTML heading element to render. |
+| `id`       | `string`                                       | `''`    | Unique identifier for the element.  |
+| `styles`   | `React.CSSProperties`                          | `null`  | Inline styles for the element.      |
+| `classes`  | `string`                                       | `''`    | Additional CSS classes for styling. |
+| `children` | `React.ReactNode`                              | `null`  | Nested content inside the element.  |
+
+## Technical Details
+
+- The `Text` component uses the `UI` component internally to render the
+  specified element.
+- The `Title` component is a wrapper around `Text` with default settings for
+  headings.
+- Both components support additional props inherited from the `UI` component.
+
+## Usage Examples
+
+### Basic Usage
+
+```tsx
+import { Text, Title } from "./text";
+
+const App = () => (
+  <>
+    <Text elm="p" text="This is a paragraph." />
+    <Text elm="span" text="This is a span." />
+    <Title elm="h1">This is a heading</Title>
+  </>
+);
+```
+
+### Advanced Usage
+
+```tsx
+import { Text, Title } from "./text";
+
+const App = () => (
+  <>
+    <Text
+      elm="blockquote"
+      styles={{ fontStyle: "italic", color: "gray" }}
+      text="This is a blockquote."
+    />
+    <Title
+      elm="h2"
+      classes="custom-heading"
+      styles={{ fontWeight: "bold", fontSize: "2rem" }}
+    >
+      Custom Heading
+    </Title>
+  </>
+);
+```
+
+### Additional Notes
+
+- Use the `elm` prop to specify the desired HTML element.
+- Combine `styles` and `classes` for advanced styling.
+- Use `children` for nested content when `text` is not sufficient.