@fpkit/acss 0.5.13 → 0.6.0

package/src/components/tag/tag.tsx

@@ -1,25 +1,122 @@
 import React from 'react'
 import UI from '#components/ui'
+import type { TagProps, TagVariant } from './tag.types'
 
-export type TagProps = {
-  /** HTML element to display the badge as span or p */
-  elm?: 'span' | 'p'
-  /**  Aria role for the component - conditional */
-  role: 'note' | 'status'
-} & React.ComponentProps<typeof UI>
-
+/**
+ * Tag - A small inline label component for displaying status, versions, or environment indicators
+ *
+ * The Tag component is used to highlight supplementary information such as release stages
+ * (alpha, beta, stable), environment indicators (production), or version labels. It renders
+ * as either a `<span>` (inline) or `<p>` (block) element with semantic ARIA roles.
+ *
+ * ## Design Philosophy
+ *
+ * Tags serve as visual and semantic indicators that:
+ * - Communicate the state or stage of features, releases, or environments
+ * - Provide quick visual scanning through color-coded variants
+ * - Maintain accessibility through proper ARIA roles and labels
+ *
+ * ## Styling Architecture
+ *
+ * The Tag component uses CSS custom properties (CSS variables) for theming and styling,
+ * allowing for easy customization through the `data-tag` attribute. Each variant
+ * (alpha, beta, stable, production) applies predefined color schemes defined in SCSS.
+ *
+ * ## Accessibility Considerations (WCAG 2.1 AA Compliance)
+ *
+ * - **Semantic Roles**: Uses `role="note"` for static tags or `role="status"` for dynamic content
+ *   - `role="note"`: Read once by screen readers, suitable for static labels (default)
+ *   - `role="status"`: Announces updates to screen readers, use for changing status indicators
+ * - **Color Independence**: Don't rely solely on color to convey meaning - include text labels
+ * - **Text Alternatives**: For icon-only tags, provide `aria-label` for screen reader context
+ * - **Contrast Ratios**: All variants meet WCAG AA contrast requirements (4.5:1 for normal text)
+ * - **Live Regions**: When using `role="status"`, tag becomes a live region for accessibility
+ *
+ * ## When to Use Each Role
+ *
+ * **Use `role="note"` (default) when:**
+ * - Displaying static version numbers (e.g., "v2.1.0")
+ * - Showing fixed environment indicators (e.g., "Beta Feature")
+ * - Labeling unchanging content categories
+ *
+ * **Use `role="status"` when:**
+ * - Indicating real-time status that may change (e.g., "Processing" → "Complete")
+ * - Displaying live build/deployment states
+ * - Showing dynamic feature flags that toggle
+ *
+ * @param {TagProps} props - Component props
+ * @returns {React.ReactElement} A Tag component
+ *
+ * @example
+ * // Basic tag with beta variant (default inline span)
+ * <Tag variant="beta">Beta</Tag>
+ *
+ * @example
+ * // Production environment indicator as block element
+ * <Tag elm="p" variant="production">Production Environment</Tag>
+ *
+ * @example
+ * // Dynamic status tag with live updates
+ * <Tag role="status" variant="stable">
+ *   {isDeployed ? 'Deployed' : 'Deploying...'}
+ * </Tag>
+ *
+ * @example
+ * // Tag with custom styling and accessibility label
+ * <Tag
+ *   variant="alpha"
+ *   aria-label="Alpha version - may contain bugs"
+ *   styles={{ fontSize: '0.75rem' }}
+ * >
+ *   Alpha
+ * </Tag>
+ *
+ * @example
+ * // ✅ GOOD: Clear text content with variant for visual enhancement
+ * <Tag variant="stable">v2.0 Stable</Tag>
+ *
+ * @example
+ * // ✅ GOOD: Dynamic status with proper role
+ * <Tag role="status" variant="production">{deploymentStatus}</Tag>
+ *
+ * @example
+ * // ✅ GOOD: Accessible tag with descriptive label
+ * <Tag variant="beta" aria-label="Beta feature - feedback welcome">
+ *   Beta
+ * </Tag>
+ *
+ * @example
+ * // ❌ BAD: Relying only on color without text
+ * <Tag variant="production" aria-label="Production" />
+ *
+ * @example
+ * // ❌ BAD: Using status role for static content
+ * <Tag role="status" variant="stable">v1.0</Tag>
+ */
 export const Tag = ({
   elm = 'span',
   role = 'note',
+  variant,
   children,
   styles,
   ...props
 }: TagProps) => {
+  // Map variant to data-tag attribute for SCSS styling
+  const dataTag = variant ? variant : undefined
+
   return (
-    <UI as={elm} role={role} styles={styles} {...props}>
+    <UI
+      as={elm}
+      role={role}
+      data-tag={dataTag}
+      styles={styles}
+      {...props}
+    >
       {children}
     </UI>
   )
 }
-export default Tag
+
 Tag.displayName = 'Tag'
+export default Tag
+export type { TagProps, TagVariant }

package/src/components/tag/tag.types.ts

@@ -0,0 +1,107 @@
+import React from 'react'
+import UI from '#components/ui'
+
+/**
+ * Available visual variants for the Tag component
+ *
+ * Each variant applies predefined color schemes and styling through CSS custom properties:
+ * - `alpha`: Early development stage indicator (warning colors)
+ * - `beta`: Pre-release version indicator (warning colors)
+ * - `stable`: Production-ready release indicator (success colors)
+ * - `production`: Live production environment indicator (primary colors)
+ *
+ * @example
+ * ```tsx
+ * <Tag variant="beta">Beta Feature</Tag>
+ * <Tag variant="stable">v2.0</Tag>
+ * ```
+ */
+export type TagVariant = 'alpha' | 'beta' | 'stable' | 'production'
+
+/**
+ * Props for the Tag component
+ *
+ * @property {React.ReactNode} children - REQUIRED - Content to display inside the tag (typically short text or version numbers)
+ * @property {'span' | 'p'} [elm='span'] - HTML element to render the tag as. Use 'p' for block-level tags, 'span' for inline
+ * @property {'note' | 'status'} [role='note'] - ARIA role for semantic meaning and screen reader announcements
+ * @property {TagVariant} [variant] - Visual variant that applies predefined color schemes (alpha, beta, stable, production)
+ * @property {string} [id] - Optional HTML id attribute for the tag element
+ * @property {React.CSSProperties} [styles] - Inline styles to apply to the tag
+ * @property {string} [classes] - CSS class names to apply to the tag
+ * @property {string} [aria-label] - Accessible label for screen readers. Recommended when tag content needs additional context
+ * @property {string} [aria-labelledby] - Reference to element(s) that label the tag for additional context
+ * @property {string} [aria-describedby] - Reference to element(s) that describe the tag for additional context
+ * @property {'off' | 'polite' | 'assertive'} [aria-live] - ARIA live region politeness setting for dynamic content (use with role="status")
+ *
+ * @example
+ * ```tsx
+ * // Basic tag with variant
+ * <Tag variant="beta">Beta</Tag>
+ *
+ * // Tag with custom element and role
+ * <Tag elm="p" role="status" variant="stable">v1.0 Released</Tag>
+ *
+ * // Tag with accessibility label
+ * <Tag variant="production" aria-label="Currently in production environment">
+ *   Production
+ * </Tag>
+ * ```
+ */
+export type TagProps = {
+  /**
+   * HTML element to display the tag as
+   * - 'span': Inline tag (default) - use for inline placement within text flow
+   * - 'p': Block-level tag - use when tag should appear as a distinct block element
+   */
+  elm?: 'span' | 'p'
+  /**
+   * ARIA role for semantic meaning and screen reader behavior
+   * - 'note': For static, informational tags (default) - screen readers read once
+   * - 'status': For dynamic tags that update - screen readers announce changes to users
+   *
+   * Choose 'status' when tag content changes dynamically (e.g., real-time status updates).
+   * Choose 'note' for static tags that provide contextual information.
+   */
+  role?: 'note' | 'status'
+  /**
+   * Visual variant that applies predefined color schemes
+   * - 'alpha': Early development stage (amber background with warning symbol ⚠)
+   * - 'beta': Pre-release version (amber background with warning symbol ⚠)
+   * - 'stable': Production-ready release (green background with checkmark ✓)
+   * - 'production': Live production environment (blue background with live indicator ●)
+   *
+   * Each variant includes both color AND visual symbols for accessibility (WCAG 1.4.1).
+   */
+  variant?: TagVariant
+  /**
+   * Content to display inside the tag
+   * REQUIRED - Ensures tag has meaningful content for all users including screen reader users
+   * Typically short text, version numbers, or status labels
+   */
+  children: React.ReactNode
+  /**
+   * Accessible label for screen readers
+   * Provides additional context beyond visible text
+   */
+  'aria-label'?: string
+  /**
+   * Reference to element(s) that label the tag
+   * Alternative to aria-label for programmatic labeling
+   */
+  'aria-labelledby'?: string
+  /**
+   * Reference to element(s) that describe the tag
+   * Provides additional descriptive context
+   */
+  'aria-describedby'?: string
+  /**
+   * ARIA live region politeness setting
+   * - 'off': Updates not announced (default)
+   * - 'polite': Announces when user is idle (recommended for role="status")
+   * - 'assertive': Announces immediately (use sparingly for critical updates)
+   */
+  'aria-live'?: 'off' | 'polite' | 'assertive'
+} & Omit<
+  React.ComponentProps<typeof UI>,
+  'as' | 'aria-label' | 'aria-labelledby' | 'aria-describedby' | 'aria-live'
+>

package/src/components/ui.tsx

@@ -7,6 +7,7 @@ import React from "react";
  *
  * This utility type ensures that refs are properly typed based on the element
  * being rendered. For example, a button element receives HTMLButtonElement ref.
+ * Excludes legacy string refs (deprecated since React 16.3).
  *
  * @typeParam C - The HTML element type (e.g., 'button', 'div', 'a')
  * @example
@@ -15,8 +16,9 @@ import React from "react";
  * type DivRef = PolymorphicRef<'div'>; // React.Ref<HTMLDivElement>
  * ```
  */
-type PolymorphicRef<C extends React.ElementType> =
-  React.ComponentPropsWithRef<C>["ref"];
+type PolymorphicRef<C extends React.ElementType> = React.Ref<
+  React.ElementRef<C>
+>;
 
 /**
  * Defines the 'as' prop that determines which HTML element to render.
@@ -74,6 +76,9 @@ type PolymorphicComponentProp<
  * to match the element being rendered, enabling focus management and direct
  * DOM access for accessibility features like programmatic focus control.
  *
+ * Supports both PolymorphicRef and ForwardedRef for compatibility with
+ * React.forwardRef components.
+ *
  * @typeParam C - The HTML element type
  * @typeParam Props - The custom props to add
  *
@@ -93,7 +98,7 @@ type PolymorphicComponentPropWithRef<
   C extends React.ElementType,
   Props = {},
 > = PolymorphicComponentProp<C, Props> & {
-  ref?: PolymorphicRef<C>;
+  ref?: PolymorphicRef<C> | React.ForwardedRef<React.ElementRef<C>>;
 };
 
 /**