@fpkit/acss 0.5.4 → 0.5.6

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.

package/src/components/alert/elements/dismiss-button.stories.tsx

@@ -0,0 +1,31 @@
+import { StoryObj, Meta } from "@storybook/react";
+import { within, expect } from "@storybook/test";
+import DismissButton from "./dismiss-button";
+
+const meta: Meta<typeof DismissButton> = {
+  title: "FP.REACT Elements/DismissButton",
+  component: DismissButton,
+  tags: ["new"],
+  parameters: {
+    actions: { argTypesRegex: "^on.*" },
+    docs: {
+      description: {
+        component: "A button component used to dismiss alerts.",
+      },
+    },
+  },
+  args: {
+    onDismiss: () => alert("Dismiss button clicked"),
+  },
+} as Meta;
+
+export default meta;
+type Story = StoryObj<typeof DismissButton>;
+
+export const Default: Story = {
+  args: {},
+  play: async ({ canvasElement }: { canvasElement: HTMLElement }) => {
+    const canvas = within(canvasElement);
+    expect(canvas.getByLabelText(/close alert/i)).toBeInTheDocument();
+  },
+} as Story;

package/src/components/alert/elements/dismiss-button.tsx

@@ -0,0 +1,28 @@
+import React from "react";
+import Button from "#components/buttons/button";
+import Icon from "#components/icons/icon";
+/** Props for the DismissButton component */
+type DismissButtonProps = {
+  /** Callback function when dismiss button is clicked */
+  onDismiss: () => void;
+  /** Size of the close icon in pixels. Defaults to 16 */
+  iconSize?: number;
+};
+export const DismissButton = React.memo(
+  ({ onDismiss, iconSize = 16 }: DismissButtonProps) => (
+    <Button
+      type="button"
+      onClick={onDismiss}
+      aria-label="Close alert"
+      className="alert-dismiss"
+      data-btn="icon sm"
+    >
+      <Icon>
+        <Icon.Close size={iconSize} />
+      </Icon>
+    </Button>
+  )
+);
+
+export default DismissButton;
+DismissButton.displayName = "DismissButton";

package/src/components/badge/badge.mdx

@@ -0,0 +1,124 @@
+import { Meta } from "@storybook/blocks";
+
+<Meta title="FP.REACT Components/Badge/Readme" />
+
+# Badge Component
+
+A lightweight and flexible badge component for displaying small counts, labels,
+or status indicators. The Badge component renders as a superscript element with
+customizable styling.
+
+## Features
+
+- Renders as a `<sup>` element with nested `<span>`
+- Fully customizable via CSS custom properties
+- Supports rounded and standard variants
+- ARIA-friendly with proper accessibility attributes
+- Integrates with FPKit UI component system
+
+## Props
+
+The Badge component accepts the following props:
+
+- `children: React.ReactNode` - Content to display inside the badge
+- `id?: string` - Optional ID for the badge element
+- `styles?: object` - Custom styles object
+- `classes?: string` - Additional CSS classes
+- `data-badge?: string` - Data attribute for badge variants (e.g. "rounded")
+- All standard HTML attributes supported by `<sup>` element
+
+## Technical Details
+
+- Built using React functional components
+- Uses TypeScript for type safety
+- Styled with CSS custom properties
+- Leverages base UI component from FPKit
+
+## Usage Example
+
+### Basic Usage
+
+```tsx
+import Badge from "./badge";
+
+function Example() {
+  return (
+    <p>
+      Messages <Badge>3</Badge>
+    </p>
+  );
+}
+```
+
+### Rounded Badge
+
+```tsx
+import Badge from "./badge";
+
+function Example() {
+  return (
+    <p>
+      Status <Badge data-badge="rounded">21</Badge>
+    </p>
+  );
+}
+```
+
+### Custom Styled Badge
+
+```tsx
+import Badge from "./badge";
+
+function Example() {
+  return (
+    <p>
+      Count{" "}
+      <Badge
+        styles={{
+          "--badge-bg": "blue",
+          "--badge-color": "white",
+        }}
+        aria-label="badge count"
+      >
+        5
+      </Badge>
+    </p>
+  );
+}
+```
+
+## Styling
+
+The component uses CSS custom properties for styling:
+
+```css
+--badge-bg: lightgray; /* Background color */
+--badge-color: currentColor; /* Text color */
+--badge-radius: 0.5rem; /* Border radius */
+--badge-padding: 0.3rem; /* Inner padding */
+--badge-v-align: 0.5rem; /* Vertical alignment */
+--badge-fs: var(--fs-1); /* Font size */
+```
+
+For rounded badges, use the `data-badge="rounded"` attribute which sets:
+
+```css
+--badge-radius: 100%;
+--badge-padding: 0.2rem;
+```
+
+## WCAG 2.1 Guidelines
+
+- Ensures sufficient color contrast (1.4.3)
+- Supports text resizing (1.4.4)
+- Maintains spacing on zoom (1.4.12)
+- Uses semantic HTML elements (4.1.1)
+- Provides meaningful content (4.1.2)
+
+## Additional Notes
+
+- Use semantic values for badge content
+- Ensure adequate color contrast when customizing
+- Keep badge content concise
+- Include ARIA labels when needed
+- Test with screen readers and keyboard navigation