@fpkit/acss 0.5.12 → 0.6.0

package/src/components/tag/tag.stories.tsx

@@ -1,38 +1,412 @@
 import { StoryObj, Meta } from "@storybook/react-vite";
 import { within, expect } from "storybook/test";
-
+import { useState } from "react";
 import Tag from "./tag";
+import type { TagVariant } from "./tag.types";
 import "./tag.scss";
 
 const meta: Meta<typeof Tag> = {
   title: "FP.React Components/Tag",
   component: Tag,
-  tags: ["beta"],
+  tags: ["autodocs", "beta"],
+  argTypes: {
+    variant: {
+      control: "select",
+      options: ["alpha", "beta", "stable", "production"] as TagVariant[],
+      description: "Visual variant with predefined color schemes",
+      table: {
+        type: { summary: "TagVariant" },
+        defaultValue: { summary: "undefined" },
+      },
+    },
+    elm: {
+      control: "radio",
+      options: ["span", "p"],
+      description: "HTML element to render (span for inline, p for block)",
+      table: {
+        type: { summary: "span | p" },
+        defaultValue: { summary: "span" },
+      },
+    },
+    role: {
+      control: "radio",
+      options: ["note", "status"],
+      description: "ARIA role (note for static, status for dynamic content)",
+      table: {
+        type: { summary: "note | status" },
+        defaultValue: { summary: "note" },
+      },
+    },
+    children: {
+      control: "text",
+      description: "Content to display inside the tag",
+    },
+  },
   args: {
-    children: "Basic Tag",
-    // styles: Tag.styles,
+    children: "Tag",
   },
-} as Meta;
+  parameters: {
+    docs: {
+      description: {
+        component:
+          "A small inline label component for displaying status, versions, or environment indicators with WCAG 2.1 AA accessibility compliance.",
+      },
+    },
+  },
+} satisfies Meta<typeof Tag>;
 
 export default meta;
 type Story = StoryObj<typeof Tag>;
 
-export const TagComponent: Story = {
-  args: {},
+/**
+ * Default tag with no variant styling
+ */
+export const Default: Story = {
+  args: {
+    children: "Default Tag",
+  },
   play: async ({ canvasElement }) => {
     const canvas = within(canvasElement);
-    expect(canvas.queryByText(/basic tag/i)).toBeInTheDocument();
+    const tag = canvas.getByRole("note");
+    expect(tag).toBeInTheDocument();
+    expect(tag.textContent).toBe("Default Tag");
   },
 };
 
+/**
+ * Alpha variant - for early development stage indicators
+ */
+export const Alpha: Story = {
+  args: {
+    variant: "alpha",
+    children: "Alpha",
+  },
+  parameters: {
+    docs: {
+      description: {
+        story:
+          "Alpha variant with warning colors for early development features.",
+      },
+    },
+  },
+} as Story;
+
+/**
+ * Beta variant - for pre-release version indicators
+ */
 export const Beta: Story = {
   args: {
-    "data-tag": "beta",
+    variant: "beta",
+    children: "Beta",
+  },
+  parameters: {
+    docs: {
+      description: {
+        story: "Beta variant with warning colors for pre-release features.",
+      },
+    },
+  },
+} as Story;
+
+/**
+ * Stable variant - for production-ready release indicators
+ */
+export const Stable: Story = {
+  args: {
+    variant: "stable",
+    children: "Stable",
+  },
+  parameters: {
+    docs: {
+      description: {
+        story:
+          "Stable variant with success colors for production-ready releases.",
+      },
+    },
   },
 } as Story;
 
+/**
+ * Production variant - for live environment indicators
+ */
 export const Production: Story = {
   args: {
-    "data-tag": "production",
+    variant: "production",
+    children: "Production",
+  },
+  parameters: {
+    docs: {
+      description: {
+        story:
+          "Production variant with primary colors for live environment indicators.",
+      },
+    },
+  },
+} as Story;
+
+/**
+ * All variants displayed together for comparison
+ */
+export const AllVariants: Story = {
+  render: () => (
+    <div
+      style={{
+        display: "flex",
+        gap: "1rem",
+        flexWrap: "wrap",
+        alignItems: "center",
+      }}
+    >
+      <Tag>Default</Tag>
+      <Tag variant="alpha">Alpha</Tag>
+      <Tag variant="beta">Beta</Tag>
+      <Tag variant="stable">Stable</Tag>
+      <Tag variant="production">Production</Tag>
+    </div>
+  ),
+  parameters: {
+    docs: {
+      description: {
+        story: "Comparison of all available tag variants side by side.",
+      },
+    },
   },
 } as Story;
+
+/**
+ * Block-level tag using paragraph element
+ */
+export const BlockLevelTag: Story = {
+  args: {
+    elm: "p",
+    variant: "beta",
+    children: "Block-level Beta Tag",
+  },
+  parameters: {
+    docs: {
+      description: {
+        story:
+          "Tag rendered as a block-level paragraph element with modified border radius.",
+      },
+    },
+  },
+} as Story;
+
+/**
+ * Dynamic status tag with role="status" for live updates
+ */
+const DynamicStatusComponent = () => {
+  const [status, setStatus] = useState<"Deploying" | "Deployed">("Deploying");
+
+  return (
+    <div style={{ display: "flex", gap: "1rem", alignItems: "center" }}>
+      <Tag role="status" variant={status === "Deployed" ? "stable" : "beta"}>
+        {status}
+      </Tag>
+      <button
+        onClick={() =>
+          setStatus(status === "Deploying" ? "Deployed" : "Deploying")
+        }
+        style={{ padding: "0.5rem 1rem", cursor: "pointer" }}
+      >
+        Toggle Status
+      </button>
+    </div>
+  );
+};
+
+export const DynamicStatus: Story = {
+  render: () => <DynamicStatusComponent />,
+  parameters: {
+    docs: {
+      description: {
+        story:
+          'Demonstrates role="status" for dynamic content that announces updates to screen readers.',
+      },
+    },
+  },
+};
+
+/**
+ * Tag with accessibility label for additional context
+ */
+export const WithAriaLabel: Story = {
+  args: {
+    variant: "beta",
+    children: "Beta",
+    "aria-label": "Beta version - feedback welcome",
+  },
+  parameters: {
+    docs: {
+      description: {
+        story:
+          "Tag with aria-label providing additional context for screen reader users.",
+      },
+    },
+  },
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement);
+    const tag = canvas.getByLabelText("Beta version - feedback welcome");
+    expect(tag).toBeInTheDocument();
+  },
+};
+
+/**
+ * Tags used inline within text content
+ */
+export const InlineUsage: Story = {
+  render: () => (
+    <p style={{ fontSize: "1rem", lineHeight: "1.6" }}>
+      This feature is currently in{" "}
+      <Tag variant="beta" aria-label="Beta testing phase">
+        Beta
+      </Tag>{" "}
+      and will be moved to{" "}
+      <Tag variant="stable" aria-label="Stable release">
+        Stable
+      </Tag>{" "}
+      after testing is complete.
+    </p>
+  ),
+  parameters: {
+    docs: {
+      description: {
+        story:
+          "Tags used inline within paragraph text for contextual labeling.",
+      },
+    },
+  },
+};
+
+/**
+ * Version tags with custom styling
+ */
+export const VersionTags: Story = {
+  render: () => (
+    <div style={{ display: "flex", gap: "0.5rem", flexWrap: "wrap" }}>
+      <Tag variant="alpha">v0.1.0-alpha</Tag>
+      <Tag variant="beta">v0.9.0-beta</Tag>
+      <Tag variant="stable">v1.0.0</Tag>
+      <Tag variant="stable">v2.0.0</Tag>
+      <Tag variant="production">v2.1.0</Tag>
+    </div>
+  ),
+  parameters: {
+    docs: {
+      description: {
+        story: "Tags used for version labeling with semantic variants.",
+      },
+    },
+  },
+};
+
+/**
+ * Custom styled tags with inline styles
+ */
+export const CustomStyling: Story = {
+  render: () => (
+    <div
+      style={{
+        display: "flex",
+        gap: "1rem",
+        flexWrap: "wrap",
+        alignItems: "center",
+      }}
+    >
+      <Tag
+        styles={{
+          backgroundColor: "#ff6b6b",
+          color: "white",
+          fontSize: "0.75rem",
+        }}
+      >
+        Custom Red
+      </Tag>
+      <Tag
+        variant="beta"
+        styles={{
+          fontSize: "1rem",
+          padding: "0.5rem 1rem",
+          fontWeight: "bold",
+        }}
+      >
+        Large Beta
+      </Tag>
+      <Tag
+        styles={{
+          backgroundColor: "#4ecdc4",
+          color: "white",
+          borderRadius: "0.25rem",
+        }}
+      >
+        Square Tag
+      </Tag>
+    </div>
+  ),
+  parameters: {
+    docs: {
+      description: {
+        story:
+          "Tags with custom inline styles overriding default CSS custom properties.",
+      },
+    },
+  },
+};
+
+/**
+ * Accessibility test - keyboard navigation and screen reader support
+ */
+export const AccessibilityDemo: Story = {
+  render: () => (
+    <div style={{ display: "flex", flexDirection: "column", gap: "1rem" }}>
+      <div>
+        <strong>Static Tags (role="note"):</strong>
+        <div style={{ display: "flex", gap: "0.5rem", marginTop: "0.5rem" }}>
+          <Tag variant="stable" aria-label="Version 1.0 stable release">
+            v1.0
+          </Tag>
+          <Tag variant="beta" aria-label="Beta feature under testing">
+            Beta
+          </Tag>
+        </div>
+      </div>
+      <div>
+        <strong>Dynamic Tags (role="status"):</strong>
+        <div style={{ display: "flex", gap: "0.5rem", marginTop: "0.5rem" }}>
+          <Tag
+            role="status"
+            variant="production"
+            aria-label="Server running status"
+          >
+            Running
+          </Tag>
+          <Tag
+            role="status"
+            variant="beta"
+            aria-label="Build in progress status"
+          >
+            Building...
+          </Tag>
+        </div>
+      </div>
+    </div>
+  ),
+  parameters: {
+    docs: {
+      description: {
+        story:
+          'Demonstrates proper ARIA role usage: role="note" for static content, role="status" for dynamic updates.',
+      },
+    },
+    a11y: {
+      config: {
+        rules: [
+          {
+            id: "color-contrast",
+            enabled: true,
+          },
+        ],
+      },
+    },
+  },
+};

package/src/components/tag/tag.test.tsx

@@ -0,0 +1,210 @@
+import React from 'react'
+import { describe, it, expect } from 'vitest'
+import { render, screen } from '@testing-library/react'
+import Tag from './tag'
+import type { TagVariant } from './tag.types'
+
+describe('Tag Component', () => {
+  describe('Rendering', () => {
+    it('should render with default props', () => {
+      render(<Tag>Default Tag</Tag>)
+      const tag = screen.getByText('Default Tag')
+      expect(tag).toBeInTheDocument()
+      expect(tag.tagName).toBe('SPAN')
+    })
+
+    it('should render children correctly', () => {
+      render(<Tag>Test Content</Tag>)
+      expect(screen.getByText('Test Content')).toBeInTheDocument()
+    })
+
+    it('should render as span element by default', () => {
+      render(<Tag>Span Tag</Tag>)
+      const tag = screen.getByText('Span Tag')
+      expect(tag.tagName).toBe('SPAN')
+    })
+
+    it('should render as p element when elm prop is "p"', () => {
+      render(<Tag elm="p">Paragraph Tag</Tag>)
+      const tag = screen.getByText('Paragraph Tag')
+      expect(tag.tagName).toBe('P')
+    })
+  })
+
+  describe('Accessibility (ARIA Roles)', () => {
+    it('should have role="note" by default', () => {
+      render(<Tag>Note Tag</Tag>)
+      const tag = screen.getByRole('note')
+      expect(tag).toBeInTheDocument()
+    })
+
+    it('should apply role="status" when specified', () => {
+      render(<Tag role="status">Status Tag</Tag>)
+      const tag = screen.getByRole('status')
+      expect(tag).toBeInTheDocument()
+    })
+
+    it('should support aria-label for additional context', () => {
+      render(<Tag aria-label="Beta version indicator">Beta</Tag>)
+      const tag = screen.getByLabelText('Beta version indicator')
+      expect(tag).toBeInTheDocument()
+    })
+
+    it('should support aria-describedby for extended descriptions', () => {
+      render(
+        <>
+          <div id="beta-desc">This is a beta feature</div>
+          <Tag aria-describedby="beta-desc">Beta</Tag>
+        </>
+      )
+      const tag = screen.getByRole('note')
+      expect(tag).toHaveAttribute('aria-describedby', 'beta-desc')
+    })
+  })
+
+  describe('Variants', () => {
+    const variants: TagVariant[] = ['alpha', 'beta', 'stable', 'production']
+
+    variants.forEach((variant) => {
+      it(`should apply data-tag="${variant}" attribute for ${variant} variant`, () => {
+        render(<Tag variant={variant}>{variant}</Tag>)
+        const tag = screen.getByText(variant)
+        expect(tag).toHaveAttribute('data-tag', variant)
+      })
+    })
+
+    it('should not apply data-tag attribute when variant is undefined', () => {
+      render(<Tag>No Variant</Tag>)
+      const tag = screen.getByText('No Variant')
+      expect(tag).not.toHaveAttribute('data-tag')
+    })
+  })
+
+  describe('Custom Styling', () => {
+    it('should apply custom inline styles via styles prop', () => {
+      render(
+        <Tag styles={{ backgroundColor: 'red', color: 'white', fontSize: '1rem' }}>
+          Styled Tag
+        </Tag>
+      )
+      const tag = screen.getByText('Styled Tag')
+      expect(tag).toHaveStyle({ fontSize: '1rem' })
+      expect(tag.style.backgroundColor).toBeTruthy()
+      expect(tag.style.color).toBeTruthy()
+    })
+
+    it('should apply CSS classes via classes prop', () => {
+      render(<Tag classes="custom-class another-class">Classed Tag</Tag>)
+      const tag = screen.getByText('Classed Tag')
+      expect(tag).toHaveClass('custom-class', 'another-class')
+    })
+
+    it('should apply id attribute', () => {
+      render(<Tag id="unique-tag">ID Tag</Tag>)
+      const tag = screen.getByText('ID Tag')
+      expect(tag).toHaveAttribute('id', 'unique-tag')
+    })
+  })
+
+  describe('Component Composition', () => {
+    it('should render with both variant and custom styles', () => {
+      render(
+        <Tag variant="beta" styles={{ fontSize: '1rem' }}>
+          Combined
+        </Tag>
+      )
+      const tag = screen.getByText('Combined')
+      expect(tag).toHaveAttribute('data-tag', 'beta')
+      expect(tag).toHaveStyle({ fontSize: '1rem' })
+    })
+
+    it('should render with all props combined', () => {
+      render(
+        <Tag
+          elm="p"
+          role="status"
+          variant="production"
+          id="prod-tag"
+          aria-label="Production environment"
+          classes="production-tag"
+          styles={{ fontWeight: 'bold' }}
+        >
+          Production
+        </Tag>
+      )
+      const tag = screen.getByRole('status')
+      expect(tag.tagName).toBe('P')
+      expect(tag).toHaveAttribute('data-tag', 'production')
+      expect(tag).toHaveAttribute('id', 'prod-tag')
+      expect(tag).toHaveAttribute('aria-label', 'Production environment')
+      expect(tag).toHaveClass('production-tag')
+      expect(tag).toHaveStyle({ fontWeight: 'bold' })
+    })
+  })
+
+  describe('Type Safety', () => {
+    it('should accept valid TagVariant values', () => {
+      // These should compile without TypeScript errors
+      const validVariants: TagVariant[] = ['alpha', 'beta', 'stable', 'production']
+      validVariants.forEach((variant) => {
+        const { unmount } = render(<Tag variant={variant}>{variant}</Tag>)
+        expect(screen.getByText(variant)).toBeInTheDocument()
+        unmount()
+      })
+    })
+
+    it('should accept valid elm prop values', () => {
+      const { rerender } = render(<Tag elm="span">Span</Tag>)
+      expect(screen.getByText('Span').tagName).toBe('SPAN')
+
+      rerender(<Tag elm="p">Paragraph</Tag>)
+      expect(screen.getByText('Paragraph').tagName).toBe('P')
+    })
+
+    it('should accept valid role prop values', () => {
+      const { rerender } = render(<Tag role="note">Note</Tag>)
+      expect(screen.getByRole('note')).toBeInTheDocument()
+
+      rerender(<Tag role="status">Status</Tag>)
+      expect(screen.getByRole('status')).toBeInTheDocument()
+    })
+  })
+
+  describe('Edge Cases', () => {
+    it('should require children for accessibility', () => {
+      // TypeScript should enforce children as required
+      // This test verifies meaningful content is provided
+      render(<Tag aria-label="Tag with content">Required Content</Tag>)
+      const tag = screen.getByLabelText('Tag with content')
+      expect(tag).toBeInTheDocument()
+      expect(tag).toHaveTextContent('Required Content')
+    })
+
+    it('should handle multiple children', () => {
+      render(
+        <Tag>
+          <span>Part 1</span>
+          <span>Part 2</span>
+        </Tag>
+      )
+      expect(screen.getByText('Part 1')).toBeInTheDocument()
+      expect(screen.getByText('Part 2')).toBeInTheDocument()
+    })
+
+    it('should handle complex children with React elements', () => {
+      render(
+        <Tag variant="beta">
+          <strong>Beta</strong> <em>v2.0</em>
+        </Tag>
+      )
+      expect(screen.getByText('Beta')).toBeInTheDocument()
+      expect(screen.getByText('v2.0')).toBeInTheDocument()
+    })
+  })
+
+  describe('Display Name', () => {
+    it('should have correct displayName for debugging', () => {
+      expect(Tag.displayName).toBe('Tag')
+    })
+  })
+})