@fpkit/acss 0.5.12 → 0.6.0

package/src/components/badge/badge.stories.tsx

@@ -2,50 +2,196 @@ import { StoryObj, Meta } from "@storybook/react-vite";
 import { within, expect } from "storybook/test";
 
 import Badge from "./badge";
+import "./badge.scss";
 
 const meta: Meta<typeof Badge> = {
   title: "FP.REACT Components/Badge",
   component: Badge,
-  tags: ["beta"],
+  tags: ["beta", "accessible"],
   args: {
-    children: "Link",
+    children: "5",
   },
-} as Story;
+} as Meta;
 
 export default meta;
 type Story = StoryObj<typeof Badge>;
 
-export const BadgeComponent: Story = {
-  args: {},
+/**
+ * Default badge story - demonstrates basic usage with notification count
+ */
+export const Default: Story = {
+  args: {
+    children: "5",
+    "aria-label": "5 unread notifications",
+  },
   play: async ({ canvasElement }) => {
     const canvas = within(canvasElement);
-    expect(canvas.getByText(/link/i)).toBeInTheDocument();
+    expect(canvas.getByText("5")).toBeInTheDocument();
+    expect(canvas.getByRole("status")).toHaveAttribute(
+      "aria-label",
+      "5 unread notifications"
+    );
   },
 };
 
-export const CustomBadge: Story = {
+/**
+ * Badge within text content - shows typical usage alongside other content
+ */
+export const WithinText: Story = {
+  render: () => {
+    return (
+      <p>
+        Messages
+        <Badge aria-label="3 unread messages">3</Badge>
+      </p>
+    );
+  },
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement);
+    expect(canvas.getByText(/messages/i)).toBeInTheDocument();
+    expect(canvas.getByText("3")).toBeInTheDocument();
+  },
+} as Story;
+
+/**
+ * Rounded variant badge - circular style for compact display
+ */
+export const RoundedVariant: Story = {
   args: {
-    children: "Custom",
+    variant: "rounded",
+    children: "99+",
+    "aria-label": "More than 99 notifications",
   },
-  render: () => {
+  render: (args) => {
     return (
       <p>
-        Custom
-        <Badge aria-label="badge">21</Badge>
+        Notifications
+        <Badge {...args} />
       </p>
     );
   },
   play: async ({ canvasElement }) => {
     const canvas = within(canvasElement);
-    expect(canvas.getByText(/custom/i)).toBeInTheDocument();
+    const badge = canvas.getByRole("status");
+    expect(badge).toHaveAttribute("data-badge", "rounded");
+    expect(canvas.getByText("99+")).toBeInTheDocument();
+  },
+} as Story;
+
+/**
+ * Multiple badges - demonstrates using multiple badges in the same context
+ */
+export const MultipleBadges: Story = {
+  render: () => {
+    return (
+      <div style={{ display: "flex", gap: "1rem", flexDirection: "column" }}>
+        <p>
+          Inbox
+          <Badge variant="rounded" aria-label="12 unread emails">
+            122
+          </Badge>
+        </p>
+        <p>
+          Inbox
+          <Badge variant="rounded" aria-label="12 unread emails">
+            12
+          </Badge>
+        </p>
+        <p>
+          Tasks
+          <Badge variant="rounded" aria-label="5 pending tasks">
+            5
+          </Badge>
+        </p>
+        <p>
+          Alerts
+          <Badge variant="rounded" aria-label="1 new alert">
+            1
+          </Badge>
+        </p>
+      </div>
+    );
   },
 } as Story;
 
-export const RoundedBadge: Story = {
+/**
+ * Rounded badges with fixed circular shape - demonstrates perfect circles with ellipsis truncation
+ * All rounded badges maintain a fixed size (1.5625rem), with content truncated using ellipsis if too long
+ */
+export const RoundedCircles: Story = {
   render: () => {
+    return (
+      <div style={{ display: "flex", gap: "1.5rem", flexDirection: "column" }}>
+        <p>
+          Single digit (perfect circle)
+          <Badge variant="rounded" aria-label="1 notification">
+            1
+          </Badge>
+        </p>
+        <p>
+          Single digit (perfect circle)
+          <Badge variant="rounded" aria-label="9 notifications">
+            9
+          </Badge>
+        </p>
+        <p>
+          Double digits (perfect circle)
+          <Badge variant="rounded" aria-label="12 notifications">
+            12
+          </Badge>
+        </p>
+        <p>
+          Double digits (perfect circle)
+          <Badge variant="rounded" aria-label="99 notifications">
+            99
+          </Badge>
+        </p>
+        <p>
+          ✅ Good: Formatted by developer
+          <Badge variant="rounded" aria-label="More than 99 notifications">
+            99+
+          </Badge>
+        </p>
+        <p>
+          ⚠️ Will truncate: Too many characters
+          <Badge variant="rounded" aria-label="More than 999 notifications">
+            999+
+          </Badge>
+        </p>
+        <p>
+          ⚠️ Will truncate: Text content
+          <Badge variant="rounded" aria-label="New feature available">
+            NEW
+          </Badge>
+        </p>
+        <p>
+          ⚠️ Will truncate: Very long text
+          <Badge variant="rounded" aria-label="Multiple notifications">
+            Multiple
+          </Badge>
+        </p>
+      </div>
+    );
+  },
+} as Story;
+
+/**
+ * Custom styled badge - demonstrates custom styling with inline styles
+ */
+export const CustomStyling: Story = {
+  args: {
+    children: "NEW",
+    "aria-label": "New feature",
+    styles: {
+      backgroundColor: "#10b981",
+      color: "white",
+    },
+  },
+  render: (args) => {
     return (
       <p>
-        Custom<Badge data-badge="rounded">21</Badge>
+        Feature Release
+        <Badge {...args} />
       </p>
     );
   },

package/src/components/badge/badge.test.tsx

@@ -0,0 +1,179 @@
+import React from "react";
+import { render, screen } from "@testing-library/react";
+import { Badge } from "./badge";
+
+describe("Badge", () => {
+  it("renders a badge element with the correct content", () => {
+    render(<Badge aria-label="5 notifications">5</Badge>);
+    const badge = screen.getByText("5");
+    expect(badge).toBeInTheDocument();
+  });
+
+  it("renders as a sup element by default", () => {
+    render(<Badge aria-label="notification badge">3</Badge>);
+    const badge = screen.getByRole("status");
+    expect(badge.tagName).toBe("SUP");
+  });
+
+  it("has role='status' by default for accessibility", () => {
+    render(<Badge aria-label="badge">12</Badge>);
+    const badge = screen.getByRole("status");
+    expect(badge).toHaveAttribute("role", "status");
+  });
+
+  it("applies aria-label for screen reader accessibility", () => {
+    render(<Badge aria-label="3 unread messages">3</Badge>);
+    const badge = screen.getByRole("status");
+    expect(badge).toHaveAttribute("aria-label", "3 unread messages");
+  });
+
+  it("renders with nested span element for styling", () => {
+    render(<Badge aria-label="badge">5</Badge>);
+    const badge = screen.getByRole("status");
+    const span = badge.querySelector("span");
+    expect(span).toBeInTheDocument();
+    expect(span?.textContent).toBe("5");
+  });
+
+  it("applies custom id when provided", () => {
+    render(
+      <Badge id="notification-badge" aria-label="notification">
+        10
+      </Badge>
+    );
+    const badge = screen.getByRole("status");
+    expect(badge).toHaveAttribute("id", "notification-badge");
+  });
+
+  it("applies custom className when provided via classes prop", () => {
+    render(
+      <Badge classes="custom-badge-class" aria-label="badge">
+        7
+      </Badge>
+    );
+    const badge = screen.getByRole("status");
+    expect(badge).toHaveClass("custom-badge-class");
+  });
+
+  it("applies custom inline styles when provided", () => {
+    render(
+      <Badge styles={{ backgroundColor: "red", fontSize: "1rem" }} aria-label="badge">
+        99+
+      </Badge>
+    );
+    const badge = screen.getByRole("status");
+    expect(badge).toHaveAttribute("style");
+    expect(badge).toHaveStyle({
+      fontSize: "1rem",
+    });
+  });
+
+  describe("variant prop", () => {
+    it("applies data-badge='rounded' when variant is 'rounded'", () => {
+      render(
+        <Badge variant="rounded" aria-label="rounded badge">
+          5
+        </Badge>
+      );
+      const badge = screen.getByRole("status");
+      expect(badge).toHaveAttribute("data-badge", "rounded");
+    });
+
+    it("does not apply data-badge attribute when variant is undefined", () => {
+      render(<Badge aria-label="default badge">3</Badge>);
+      const badge = screen.getByRole("status");
+      expect(badge).not.toHaveAttribute("data-badge");
+    });
+  });
+
+  describe("children rendering", () => {
+    it("renders numeric children correctly", () => {
+      render(<Badge aria-label="count">123</Badge>);
+      expect(screen.getByText("123")).toBeInTheDocument();
+    });
+
+    it("renders string children correctly", () => {
+      render(<Badge aria-label="new badge">NEW</Badge>);
+      expect(screen.getByText("NEW")).toBeInTheDocument();
+    });
+
+    it("renders React element children correctly", () => {
+      render(
+        <Badge aria-label="icon badge">
+          <span data-testid="custom-icon">★</span>
+        </Badge>
+      );
+      expect(screen.getByTestId("custom-icon")).toBeInTheDocument();
+    });
+  });
+
+  describe("accessibility", () => {
+    it("is accessible with proper aria-label", () => {
+      render(<Badge aria-label="12 items in cart">12</Badge>);
+      const badge = screen.getByRole("status", { name: "12 items in cart" });
+      expect(badge).toBeInTheDocument();
+    });
+
+    it("can override role attribute if needed", () => {
+      render(
+        <Badge role="note" aria-label="information">
+          i
+        </Badge>
+      );
+      // role="note" should be applied via props spread
+      const badge = screen.getByText("i").closest("sup");
+      expect(badge).toHaveAttribute("role", "note");
+    });
+
+    it("supports additional ARIA attributes", () => {
+      render(
+        <Badge aria-label="badge" aria-live="polite" aria-atomic="true">
+          5
+        </Badge>
+      );
+      const badge = screen.getByRole("status");
+      expect(badge).toHaveAttribute("aria-live", "polite");
+      expect(badge).toHaveAttribute("aria-atomic", "true");
+    });
+  });
+
+  describe("integration", () => {
+    it("renders correctly within text content", () => {
+      render(
+        <p>
+          Messages
+          <Badge aria-label="3 unread">3</Badge>
+        </p>
+      );
+      expect(screen.getByText("Messages")).toBeInTheDocument();
+      expect(screen.getByText("3")).toBeInTheDocument();
+    });
+
+    it("renders multiple badges independently", () => {
+      render(
+        <div>
+          <Badge aria-label="first badge">1</Badge>
+          <Badge aria-label="second badge">2</Badge>
+          <Badge aria-label="third badge" variant="rounded">
+            3
+          </Badge>
+        </div>
+      );
+      const badges = screen.getAllByRole("status");
+      expect(badges).toHaveLength(3);
+      expect(badges[2]).toHaveAttribute("data-badge", "rounded");
+    });
+  });
+
+  describe("props spreading", () => {
+    it("forwards additional props to the UI component", () => {
+      render(
+        <Badge data-testid="custom-badge" data-custom="value" aria-label="badge">
+          5
+        </Badge>
+      );
+      const badge = screen.getByTestId("custom-badge");
+      expect(badge).toHaveAttribute("data-custom", "value");
+    });
+  });
+});

package/src/components/badge/badge.tsx

@@ -1,17 +1,110 @@
 import UI from '#components/ui'
 import React from 'react'
 
+/**
+ * Props for the Badge component
+ *
+ * @property {React.ReactNode} children - Content to display inside the badge (typically numbers or short text)
+ * @property {string} [id] - Optional HTML id attribute for the badge element
+ * @property {React.CSSProperties} [styles] - Inline styles to apply to the badge
+ * @property {string} [classes] - CSS class names to apply to the badge
+ * @property {'rounded'} [variant] - Visual variant of the badge. Use 'rounded' for circular badges (fixed size with ellipsis for overflow)
+ * @property {string} [aria-label] - Accessible label for screen readers. Required for icon-only or number-only badges
+ * @property {'status' | 'note'} [role] - ARIA role for the badge. Defaults to 'status' for dynamic content
+ */
 export type BadgeProps = {
-  children: React.ReactNode
+  /**
+   * Content to display inside the badge (typically numbers or short text)
+   */
+  children?: React.ReactNode
+  /**
+   * Visual variant of the badge
+   * - 'rounded': Circular badge style
+   */
+  variant?: 'rounded'
 } & React.ComponentProps<typeof UI>
 
-const Badge = ({ id, styles, classes, children, ...props }: BadgeProps) => {
+/**
+ * Badge - A small label component for displaying status, counts, or notifications
+ *
+ * The Badge component is used to display supplementary information alongside other content,
+ * such as notification counts, status indicators, or labels. It renders as a semantic `<sup>`
+ * element with a nested `<span>` required for the component's styling architecture.
+ *
+ * ## Styling Architecture
+ *
+ * The Badge uses a nested structure (`<sup><span>content</span></sup>`) which is required
+ * for the SCSS styling system. The outer `<sup>` element provides positioning context,
+ * while the inner `<span>` receives the visual styling (background, padding, border-radius).
+ *
+ * ## Rounded Variant Behavior
+ *
+ * The `rounded` variant creates a perfect circular badge with fixed dimensions (1.5625rem).
+ * Content that exceeds the available space will be truncated with an ellipsis (...).
+ * **Best practice**: Format large numbers yourself (e.g., pass "99+" instead of "999").
+ *
+ * ## Accessibility Considerations
+ *
+ * - **Semantic HTML**: Uses `<sup>` (superscript) element for proper positioning context
+ * - **ARIA Role**: Defaults to `role="status"` for dynamic badges (e.g., unread counts)
+ * - **Accessible Names**: For icon-only or number-only badges, provide an `aria-label`
+ *   to give context (e.g., "3 unread messages" instead of just "3")
+ * - **Live Regions**: The `role="status"` makes badges announce updates to screen readers
+ *
+ * @param {BadgeProps} props - Component props
+ * @returns {React.ReactElement} A Badge component
+ *
+ * @example
+ * // Basic badge with notification count
+ * <p>
+ *   Messages
+ *   <Badge aria-label="3 unread messages">3</Badge>
+ * </p>
+ *
+ * @example
+ * // Rounded badge variant (perfect circle)
+ * <p>
+ *   Notifications
+ *   <Badge variant="rounded" aria-label="99 or more notifications">99+</Badge>
+ * </p>
+ *
+ * @example
+ * // Status badge with custom styling
+ * <p>
+ *   Active Users
+ *   <Badge styles={{ backgroundColor: 'green', color: 'white' }}>21</Badge>
+ * </p>
+ *
+ * @example
+ * // ✅ GOOD: Accessible badge with descriptive label and formatted content
+ * <Badge variant="rounded" aria-label="12 items in cart">12</Badge>
+ *
+ * @example
+ * // ✅ GOOD: Large numbers formatted by developer
+ * <Badge variant="rounded" aria-label="More than 99 notifications">99+</Badge>
+ *
+ * @example
+ * // ❌ BAD: Number-only badge without context for screen readers
+ * <Badge>12</Badge>
+ */
+export const Badge = ({ id, styles, classes, children, variant, ...props }: BadgeProps) => {
+  // Build data-badge attribute for variant styling
+  const dataBadge = variant ? variant : undefined
+
   return (
-    <UI as="sup" id={id} styles={styles} className={classes} {...props}>
+    <UI
+      as="sup"
+      id={id}
+      styles={styles}
+      className={classes}
+      data-badge={dataBadge}
+      role="status"
+      {...props}
+    >
       <UI as="span">{children}</UI>
     </UI>
   )
 }
 
-export default Badge
 Badge.displayName = 'Badge'
+export default Badge