@fpkit/acss 0.5.5 → 0.5.6

package/src/components/README.mdx

@@ -0,0 +1,84 @@
+import { Meta } from "@storybook/blocks";
+
+<Meta title="ACSS UI" />
+
+# UI Component
+
+A lightweight polymorphic component that serves as a foundation for building
+flexible UI elements.
+
+## Features
+
+- Polymorphic component that can render as any HTML element
+- Type-safe props with TypeScript
+- Supports custom styling through CSS properties and classes
+- Forward ref support
+- Lightweight and performant
+
+## Props
+
+| Prop     | Type                | Description                           |
+| -------- | ------------------- | ------------------------------------- |
+| as       | React.ElementType   | HTML element to render (default: div) |
+| styles   | React.CSSProperties | Inline styles object                  |
+| classes  | string              | CSS class names                       |
+| children | React.ReactNode     | Child elements                        |
+| ...props | any                 | All valid HTML attributes             |
+
+## Technical Details
+
+The component uses advanced TypeScript features to ensure type safety:
+
+- Polymorphic refs
+- Component props with proper type inference
+- Props omission to avoid conflicts
+
+## Usage Examples
+
+### Basic Usage
+
+```tsx
+import UI from '#components/ui'
+
+// Render as a div (default)
+<UI classes="my-class">Content</UI>
+
+// Render as a button
+<UI as="button" classes="btn">Click me</UI>
+
+// With custom styles
+<UI
+  as="section"
+  styles={{ padding: "1rem", background: "#f0f0f0" }}
+>
+  Section content
+</UI>
+```
+
+### Advanced Usage
+
+```tsx
+import UI from "#components/ui";
+
+// With ref forwarding
+const MyComponent = () => {
+  const ref = useRef<HTMLDivElement>(null);
+
+  return (
+    <UI
+      ref={ref}
+      as="div"
+      styles={{ position: "relative" }}
+      classes="container"
+    >
+      Custom component
+    </UI>
+  );
+};
+```
+
+## Additional Notes
+
+- The component automatically merges default styles with custom styles
+- TypeScript will provide proper type hints for element-specific props
+- Use the `as` prop to change the rendered element while maintaining type safety

package/src/components/alert/README.mdx

@@ -0,0 +1,86 @@
+import { Meta } from "@storybook/blocks";
+
+# Alert Component
+
+## Summary
+
+The Alert component is used to display important messages to users. It can be
+dismissible and supports various interaction tests.
+
+## Features
+
+- Display alert messages
+- Dismissible option
+- Customizable title and content
+- Interaction testing support
+
+## Props
+
+| Prop          | Type        | Description                               |
+| ------------- | ----------- | ----------------------------------------- |
+| `title`       | `string`    | The title of the alert                    |
+| `children`    | `ReactNode` | The content of the alert                  |
+| `dismissible` | `boolean`   | Whether the alert can be dismissed        |
+| `onDismiss`   | `function`  | Callback function when alert is dismissed |
+| `open`        | `boolean`   | Whether the alert is visible              |
+| `className`   | `string`    | Additional CSS classes for the alert      |
+
+## Technical Details
+
+The Alert component is built using React functional components and hooks. It
+supports interaction testing using Storybook.
+
+## Usage Example
+
+### Basic Usage
+
+```tsx
+import React from "react";
+import Alert from "./alert";
+
+const App = () => (
+  <Alert
+    title="Alert Title"
+    dismissible={true}
+    onDismiss={() => console.log("Alert dismissed")}
+  >
+    This is an alert message
+  </Alert>
+);
+
+export default App;
+```
+
+### Advanced Usage
+
+```tsx
+import React, { useState } from "react";
+import Alert from "./alert";
+
+const App = () => {
+  const [isOpen, setIsOpen] = useState(true);
+
+  return (
+    <div>
+      <button onClick={() => setIsOpen(!isOpen)}>Toggle Alert</button>
+      {isOpen && (
+        <Alert
+          title="Advanced Alert"
+          dismissible={true}
+          onDismiss={() => setIsOpen(false)}
+        >
+          This is an advanced alert message
+        </Alert>
+      )}
+    </div>
+  );
+};
+
+export default App;
+```
+
+### Additional Notes
+
+- Ensure to handle the `onDismiss` callback to manage the alert's visibility
+  state.
+- Customize the alert's appearance using the `className` prop.

package/src/components/alert/alert.mdx

@@ -0,0 +1,74 @@
+import { Meta } from "@storybook/blocks";
+
+<Meta title="FP.REACT Components/Alert/Readme" />
+
+# Alert Component
+
+## Summary
+
+The `Alert` component is a customizable component for displaying status messages
+with different severity levels. It supports multiple severity types (default,
+info, success, warning, error) and can include optional titles and dismissal
+functionality.
+
+## Features
+
+- Multiple severity levels with matching visual indicators
+- Optional title and dismissible states
+- Accessible by default with appropriate ARIA attributes
+- Customizable icons through `iconProps`
+
+## Props
+
+```tsx
+export type AlertProps = {
+  open: boolean;
+  severity?: "default" | "info" | "success" | "warning" | "error";
+  children: React.ReactNode;
+  title?: string;
+  dismissible?: boolean;
+  onDismiss?: () => void;
+  iconProps?: IconProps;
+} & React.ComponentProps<typeof UI>;
+```
+
+## Technical Details
+
+The `Alert` component uses the `UI` component for rendering and supports various
+severity levels with corresponding ARIA attributes for accessibility. It also
+allows for custom icons through the `iconProps` prop.
+
+## Usage Example
+
+### Basic Usage
+
+```tsx
+import Alert from "#components/alert";
+
+<Alert open={true} severity="info">
+  This is an info alert.
+</Alert>;
+```
+
+### Advanced Usage
+
+```tsx
+import Alert from "#components/alert";
+
+<Alert
+  open={true}
+  severity="error"
+  title="Error"
+  dismissible={true}
+  onDismiss={() => console.log("Alert dismissed")}
+  iconProps={{ fill: "#000", size: 24 }}
+>
+  This is an error alert with a custom icon.
+</Alert>;
+```
+
+### Additional Notes
+
+- The `Alert` component is designed to be accessible by default.
+- The `dismissible` prop allows the alert to be dismissed by the user.
+- Custom icons can be provided through the `iconProps` prop.

package/src/components/alert/alert.scss

@@ -0,0 +1,80 @@
+[role="alert"] {
+  /* Success colors */
+  --alert-success-bg: #e6f4ea;
+  --alert-success-border: #34a853;
+  --alert-success-text: #1e4620;
+
+  /* Error colors */
+  --alert-error-bg: #fdeded;
+  --alert-error-border: #d32f2f;
+  --alert-error-text: #5f2120;
+
+  /* Warning colors */
+  --alert-warning-bg: #fff4e5;
+  --alert-warning-border: #ff9800;
+  --alert-warning-text: #663c00;
+
+  /* Info colors */
+  --alert-info-bg: #e5f6fd;
+  --alert-info-border: #0288d1;
+  --alert-info-text: #084154;
+
+  --alert-border: thin solid currentColor;
+
+  background-color: var(--alert-bg, whitesmoke);
+  border: var(--alert-border, currentColor);
+  color: var(--alert-color, currentColor);
+  padding: var(--alert-padding, var(--spc-4));
+  margin-block-end: var(--alert-margin-block-end);
+  font-size: var(--fs-0);
+  line-height: 1.6;
+  display: flex;
+  flex-direction: row;
+  // align-items: center;
+  border-radius: var(--alert-border-radius, var(--border-radius));
+  border: var(--alert-border);
+  gap: var(--alert-gap, var(--spc-4));
+  div {
+    margin-block-start: 0;
+    align-items: center;
+  }
+
+  .alert-message {
+    flex: 2;
+    margin-block-start: 0;
+    h3 {
+      margin-block-end: 0;
+    }
+  }
+
+  &[data-alert~="info"] {
+    --alert-bg: var(--alert-info-bg);
+    --alert-color: var(--alert-info-text);
+    border-color: var(--alert-info-border);
+  }
+
+  &[data-alert~="warning"] {
+    --alert-bg: var(--alert-warning-bg);
+    --alert-color: var(--alert-warning-text);
+    border-color: var(--alert-warning-border);
+  }
+
+  &[data-alert~="error"] {
+    --alert-bg: var(--alert-error-bg);
+    --alert-color: var(--alert-error-text);
+    border-color: var(--alert-error-border);
+  }
+
+  &[data-alert~="success"] {
+    --alert-bg: var(--alert-success-bg);
+    --alert-color: var(--alert-success-text);
+    border-color: var(--alert-success-border);
+  }
+
+  button {
+    &[data-btn~="icon"] {
+      --btn-bg: transparent;
+      max-height: fit-content;
+    }
+  }
+}

package/src/components/alert/alert.stories.tsx

@@ -0,0 +1,132 @@
+import { StoryObj, Meta, StoryFn } from "@storybook/react";
+import { within, expect, userEvent, fn } from "@storybook/test";
+
+import Alert from "./alert";
+import WithInstructions from "#decorators/instructions.jsx";
+import React from "react";
+
+const ButtonDecorator = (Story: StoryFn) => {
+  const [isOpen, setIsOpen] = React.useState(false);
+  return (
+    <div>
+      <button onClick={() => setIsOpen(!isOpen)}>Open Alert</button>
+      <Story
+        args={{
+          open: isOpen,
+          title: "Alert Title",
+          children: "This is an alert message",
+          dismissible: false,
+        }}
+      />
+    </div>
+  );
+};
+
+const instructions = (
+  <>
+    <p>We are testing the following interactions on the alert:</p>
+    <ul>
+      <li>Tab through the alert.</li>
+      <li>Check if the button gets focused.</li>
+      <li>Click the button to dismiss the alert.</li>
+      <li>Check that the alert is no longer in the document.</li>
+    </ul>
+  </>
+);
+
+const meta: Meta<typeof Alert> = {
+  title: "FP.REACT Components/Alert",
+  component: Alert,
+  tags: ["beta"],
+  parameters: {
+    docs: {
+      description: {
+        component:
+          "The Alert component is used to display important messages to users. It can be dismissible and supports various interaction tests",
+      },
+    },
+  },
+  args: {
+    title: "Alert Title",
+    children:
+      "The Alert component is used to display important messages to users.",
+    dismissible: true,
+    onDismiss: () => fn(),
+  },
+} as Meta;
+
+export default meta;
+type Story = StoryObj<typeof Alert>;
+
+export const DefaultAlert: Story = {
+  args: {
+    open: true,
+  },
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement);
+    expect(canvas.getByText(/this is an alert message/i)).toBeInTheDocument();
+  },
+} as Story;
+
+export const SuccessAlert: Story = {
+  args: {
+    open: true,
+    severity: "success",
+  },
+} as Story;
+
+export const WarningAlert: Story = {
+  args: {
+    open: true,
+    severity: "warning",
+  },
+} as Story;
+
+export const ErrorAlert: Story = {
+  args: {
+    open: true,
+    severity: "error",
+  },
+} as Story;
+
+export const InfoAlert: Story = {
+  args: {
+    open: true,
+    severity: "info",
+  },
+} as Story;
+
+export const OpenAlert: Story = {
+  decorators: [ButtonDecorator],
+} as Story;
+
+export const InteractionTest: Story = {
+  args: {
+    open: true,
+    className: "my alert",
+  },
+  decorators: [WithInstructions(instructions, "Alert interactions test:")],
+  play: async ({ canvasElement, step }) => {
+    const canvas = within(canvasElement);
+    const alert = canvas.getByRole("alert");
+    const dismissButton = canvas.getByRole("button", { name: /close alert/i });
+    await step(
+      "Check that the alert and button are in the document",
+      async () => {
+        expect(alert).toBeInTheDocument();
+        expect(dismissButton).toBeInTheDocument();
+      }
+    );
+    // await step(
+    //   "Tab through the alert and check if the button gets focused",
+    //   async () => {
+    //     userEvent.tab({ delay: 500 });
+    //     expect(dismissButton).toHaveFocus();
+    //   }
+    // );
+    await step("Click the button to dismiss the alert", async () => {
+      await userEvent.click(dismissButton, { delay: 500 });
+      expect(alert).not.toBeInTheDocument();
+    });
+  },
+} as Story;

package/src/components/alert/alert.tsx

@@ -0,0 +1,154 @@
+import React from "react";
+import UI from "#components/ui";
+import Icon from "#components/icons/icon";
+import { IconProps } from "#components/icons/types";
+import DismissButton from "./elements/dismiss-button";
+
+// First, define a type for the valid severity values
+type Severity = "default" | "info" | "success" | "warning" | "error";
+
+/**
+ * Props for the Alert component.
+ */
+export type AlertProps = {
+  /**
+   * Whether the alert is open.
+   */
+  open: boolean;
+  /**
+   * The severity level of the alert.
+   * @default "default"
+   */
+  severity?: Severity;
+  /**
+   * The main message content.
+   */
+  children: React.ReactNode;
+  /**
+   * Optional title for the alert.
+   */
+  title?: string;
+  /**
+   * Whether the alert can be dismissed.
+   * @default false
+   */
+  dismissible?: boolean;
+  /**
+   * Callback when alert is dismissed.
+   */
+  onDismiss?: () => void;
+
+  /**
+   * Size of the icon in pixels.
+   * @default 32
+   */
+  iconSize?: number;
+
+  /**
+   * Additional props to pass to the Icon component.
+   */
+  iconProps?: IconProps;
+} & React.ComponentProps<typeof UI>;
+
+/**
+ * Alert is a customizable component for displaying status messages with different severity levels.
+ * It supports multiple severity types (default, info, success, warning, error) and can include
+ * optional titles and dismissal functionality.
+ *
+ * Features:
+ * - Multiple severity levels with matching visual indicators
+ * - Optional title and dismissible states
+ * - Accessible by default with appropriate ARIA attributes
+ * - Customizable icons through iconProps
+ *
+ * @example
+ * ```tsx
+ * <Alert
+ *   open={true}
+ *   severity="info"
+ *   title="Optional Title"
+ *   dismissible={true}
+ *   onDismiss={() => console.log('Alert dismissed')}
+ * >
+ *   Alert message content
+ * </Alert>
+ * ```
+ *
+ * @see {@link AlertProps} for available configuration options
+ */ const Alert: React.FC<AlertProps> = ({
+  open,
+  severity = "default",
+  children,
+  title,
+  dismissible = false,
+  onDismiss,
+  iconSize,
+  iconProps,
+  ...props
+}) => {
+  const [isVisible, setIsVisible] = React.useState(open);
+
+  React.useEffect(() => {
+    setIsVisible(open);
+  }, [open]);
+
+  if (!isVisible) return null;
+
+  const handleDismiss = (): void => {
+    setIsVisible(false);
+    onDismiss?.();
+  };
+
+  /**
+   * Default props for the Icon component used in the Alert component.
+   * These props set the fill color to white and the size to 32 pixels.
+   */
+  const defaultIconProps: IconProps = {
+    size: iconSize || 32,
+  };
+
+  // Update the severityType object with the type
+  const severityType: Record<Severity, "polite" | "assertive"> = {
+    default: "polite",
+    info: "polite",
+    success: "polite",
+    warning: "polite",
+    error: "assertive",
+  } as const;
+
+  const mergedIconProps = { ...defaultIconProps, ...iconProps };
+
+  // Update the severityIcons object with the type
+  const severityIcons: Record<Severity, JSX.Element> = {
+    info: <Icon.InfoSolid {...mergedIconProps} />,
+    success: <Icon.SuccessSolid {...mergedIconProps} />,
+    warning: <Icon.WarnSolid {...mergedIconProps} />,
+    error: <Icon.AlertSolid {...mergedIconProps} />,
+    default: <Icon.AlertSquareSolid {...mergedIconProps} />,
+  };
+
+  return (
+    <UI
+      as="div"
+      role="alert"
+      aria-live={severityType[severity]}
+      aria-atomic="true"
+      className={`alert alert-${severity}`}
+      data-alert={severity}
+      {...props}
+    >
+      <UI aria-hidden="true">{severityIcons[severity]}</UI>
+      <UI as="div" className="alert-message">
+        {title && (
+          <UI as="h3" className="alert-title">
+            {title}
+          </UI>
+        )}
+        <UI as="div">{children}</UI>
+      </UI>
+      {dismissible && <DismissButton onDismiss={handleDismiss} />}
+    </UI>
+  );
+};
+export default Alert;
+Alert.displayName = "Alert";

package/src/components/alert/elements/README.mdx

@@ -0,0 +1,77 @@
+import { Meta } from "@storybook/blocks";
+
+<Meta title="FP.REACT Elements/DismissButton/Readme" />
+
+# DismissButton
+
+## Summary
+
+The `DismissButton` component is a reusable button designed to dismiss alerts.
+It includes an icon and an optional callback function for handling dismiss
+actions.
+
+## Features
+
+- Customizable icon size
+- Callback function for dismiss actions
+- Accessible with `aria-label`
+
+## Props
+
+| Name        | Type         | Default | Description                                      |
+| ----------- | ------------ | ------- | ------------------------------------------------ |
+| `onDismiss` | `() => void` | -       | Callback function when dismiss button is clicked |
+| `iconSize`  | `number`     | `16`    | Size of the close icon in pixels                 |
+
+## Technical Details
+
+The `DismissButton` component uses the `Button` and `Icon` components from the
+`#components` library. It is memoized using `React.memo` for performance
+optimization.
+
+## Usage Example
+
+### Basic Usage
+
+```tsx
+import React from "react";
+import DismissButton from "#components/alert/elements/dismiss-button";
+
+const handleDismiss = () => {
+  console.log("Alert dismissed");
+};
+
+const AlertComponent = () => (
+  <div className="alert">
+    <span>Alert message</span>
+    <DismissButton onDismiss={handleDismiss} />
+  </div>
+);
+
+export default AlertComponent;
+```
+
+### Advanced Usage
+
+```tsx
+import React from "react";
+import DismissButton from "#components/alert/elements/dismiss-button";
+
+const handleDismiss = () => {
+  // Custom logic for dismissing the alert
+};
+
+const CustomAlert = () => (
+  <div className="custom-alert">
+    <span>Custom alert message</span>
+    <DismissButton onDismiss={handleDismiss} iconSize={24} />
+  </div>
+);
+
+export default CustomAlert;
+```
+
+## Additional Notes
+
+- Ensure the `onDismiss` callback is provided to handle the dismiss action.
+- The `iconSize` prop can be adjusted to fit the design requirements.