@fpkit/acss 0.5.7 → 0.5.9

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/README.mdx

@@ -0,0 +1,101 @@
+import { Meta } from "@storybook/blocks";
+
+<Meta title="FP.REACT Components/Details/Readme" />
+
+# Details Component
+
+## Summary
+
+The `Details` component is a versatile and accessible component that provides a
+collapsible section for displaying content. It is built using functional
+components and hooks, ensuring reusability and performance optimization.
+
+## Features
+
+- Accessible with aria-label support.
+- Customizable with styles and class names.
+- Supports icons and custom summary content.
+- Easy to integrate and use in any React application.
+
+## Props
+
+| Name            | Type                                                  | Description                                       |
+| --------------- | ----------------------------------------------------- | ------------------------------------------------- |
+| `summary`       | `React.ReactNode`                                     | The summary text shown for the details. Required. |
+| `ariaLabel`     | `string`                                              | The aria-label element for accessibility.         |
+| `styles`        | `React.CSSProperties`                                 | CSS styles object.                                |
+| `classes`       | `string`                                              | Classnames string.                                |
+| `open`          | `boolean`                                             | Whether the details is open.                      |
+| `onToggle`      | `(e: React.PointerEvent<HTMLDetailsElement>) => void` | onToggle callback.                                |
+| `onPointerDown` | `(e: React.PointerEvent<HTMLDetailsElement>) => void` | onPointerDown callback.                           |
+| `children`      | `React.ReactNode`                                     | The content inside the details.                   |
+| `ref`           | `React.Ref<any>`                                      | Ref object.                                       |
+| `name`          | `string`                                              | Name attribute for the details element.           |
+
+## Technical Details
+
+The `Details` component is built using TypeScript for type-checking and enhanced
+developer experience. It uses functional components and hooks to ensure
+performance and reusability.
+
+## Usage Example
+
+### Basic Usage
+
+```tsx
+import React from "react";
+import Details from "./details";
+import Icons from "../icons/icon";
+
+const content = (
+  <>
+    <p>Example content inside the details component.</p>
+  </>
+);
+
+const icon = <Icons.Add />;
+
+const Example = () => (
+  <Details summary="Summary Section" icon={icon} ariaLabel="Details Section">
+    {content}
+  </Details>
+);
+
+export default Example;
+```
+
+### Advanced Usage
+
+```tsx
+import React from "react";
+import Details from "./details";
+import Icons from "../icons/icon";
+
+const content = (
+  <>
+    <p>Advanced example content inside the details component.</p>
+  </>
+);
+
+const icon = <Icons.Add />;
+
+const AdvancedExample = () => (
+  <Details
+    summary="Advanced Summary Section"
+    icon={icon}
+    ariaLabel="Advanced Details Section"
+    open={true}
+    onToggle={(e) => console.log("Toggled", e)}
+  >
+    {content}
+  </Details>
+);
+
+export default AdvancedExample;
+```
+
+### Additional Notes
+
+- Ensure to provide meaningful aria-labels for accessibility.
+- Customize the component using the `styles` and `classes` props.
+- Use the `onToggle` and `onPointerDown` callbacks for custom interactions.

package/src/components/details/details.scss

@@ -1,22 +1,22 @@
 details {
-  --details-w: 100%;
-  --details-h: max-content;
-  --details-border: 1px solid #dfdfdf;
-  --details-display: flex;
-  --details-justify: flex-start;
+  --details-border: 0.0625rem solid #dfdfdf;
   --details-direction: column;
+  --details-display: flex;
   --details-gap: 0rem;
+  --details-h: max-content;
+  --details-justify: flex-start;
   --details-px: 1.5rem;
   --details-py: 1rem;
-  --details-radius: var(--border-radius);
+  --details-radius: 0;
+  --details-w: 100%;
+  --max-h-closed: 6.25rem;
+  --max-h-open: 50rem;
+  --summary-align: center;
   --summary-cursor: pointer;
-  --summary-transitions: all 0.75s ease-in-out;
   --summary-display: flex;
-  --summary-justify: flex-start;
-  --summary-align: center;
   --summary-gap: 0.5rem;
-  --max-h-closed: 6.25rem;
-  --max-h-open: 50rem;
+  --summary-justify: flex-start;
+  --summary-transitions: all 0.75s ease-in-out;
 
   interpolate-size: allow-keywords;
   display: var(--details-display);
@@ -25,12 +25,11 @@ details {
   gap: var(--details-gap);
   width: var(--details-w);
   border: var(--details-border);
+  border-left: none;
+  border-right: none;
   transition: var(--summary-transitions);
   max-height: var(--max-h-closed);
   overflow: clip;
-  border-radius: var(--details-radius);
-
-  // Handle multiple details elements
   & + details {
     border-radius: 0; // remove radius from middle elements
     border-top: none; // optional: remove double borders
@@ -71,7 +70,7 @@ details {
 
     &:focus-within {
       outline: none;
-      border-bottom: solid 2px var(--details-border);
+      border-bottom: solid 2px currentColor;
       background-color: whitesmoke;
     }
 
@@ -84,6 +83,13 @@ details {
     }
   }
 
+  .list-styles {
+    summary {
+      border-left: none;
+      border-right: none;
+    }
+  }
+
   > section {
     padding-inline: var(--details-px);
     padding-block: var(--details-py);

package/src/components/details/details.stories.tsx

@@ -60,6 +60,12 @@ export const DetailsDropdown: Story = {
   },
 } as Story;
 
+export const DetailsStyles: Story = {
+  args: {
+    classes: "list-style",
+  },
+} as Story;
+
 export const DetailsOpen: Story = {
   args: {
     open: true,
@@ -123,19 +129,41 @@ export const DetailsAccordion: Story = {
 
 export const DetailsInteractionTest: Story = {
   args: {},
-  play: async ({ canvasElement }) => {
+  play: async ({ canvasElement, step }) => {
     const canvas = within(canvasElement);
 
     // Find the summary element
     const summaryElement = canvas.getByText("Summary Section");
+    // add an open step
+    await step("Open the details", async () => {
+      // Simulate a click on the summary element
+      await userEvent.click(summaryElement, { delay: 500 });
+
+      // Assert that the details element is open
+      const detailsElement = canvas.getByRole("group", {
+        name: /details dropdown/i,
+      });
+      expect(detailsElement).toHaveAttribute("open");
+    });
+
+    await step("Close the detail panel", async () => {
+      await userEvent.click(summaryElement, { delay: 500 });
+
+      expect(summaryElement).not.toHaveAttribute("open");
+    });
+
+    // test if it works with the space bar
+    await step("Open the details with space", async () => {
+      summaryElement.focus();
+      expect(summaryElement).toHaveFocus();
 
-    // Simulate a click on the summary element
-    await userEvent.click(summaryElement);
+      await userEvent.type(summaryElement, "{space}", { delay: 500 });
 
-    // Assert that the details element is open
-    const detailsElement = canvas.getByRole("group", {
-      name: /details dropdown/i,
+      // Assert that the details element is open
+      const detailsElement = canvas.getByRole("group", {
+        name: /details dropdown/i,
+      });
+      expect(detailsElement).toHaveAttribute("open");
     });
-    expect(detailsElement).toHaveAttribute("open");
   },
 };

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/dialog/dialog-modal.stories.tsx

@@ -104,7 +104,7 @@ export const ModalInteractions: Story = {
       expect(openButton).not.toHaveFocus();
 
       const dialog = canvas.getByRole("dialog");
-      await userEvent.keyboard(" "); // Close the dialog with the keyboard
+      await userEvent.type(dialog, "{Escape}", { delay: 500 }); // Close the dialog with the keyboard
       await waitFor(() => {
         expect(dialog).not.toBeVisible();
       });

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.