@neynar/ui 0.4.0 → 0.5.0

package/src/components/ui/typography.tsx

@@ -1,609 +0,0 @@
-import * as React from "react";
-
-import { cn } from "@/lib/utils";
-
-/**
- * Typography Components - Purpose-named, Tailwind-first text components
- *
- * This module provides semantic typography components for web applications.
- * Each component has a clear purpose and sensible Tailwind CSS defaults that
- * can be fully overridden via the className prop.
- *
- * Design Philosophy:
- * - Purpose-obvious naming (PageTitle, BodyText, Caption)
- * - Semantic HTML defaults (h1, h2, p, etc.)
- * - Tailwind-first with zero abstraction
- * - Full className override control
- * - Appropriate sizing for web apps (not marketing sites)
- *
- * @see {@link https://tailwindcss.com} Tailwind CSS documentation
- * @since 2.0.0
- */
-
-/**
- * Base typography component props
- *
- * All typography components accept these props:
- * - `as` - The HTML element to render (each component has a sensible default)
- * - `className` - Additional Tailwind classes to merge with defaults
- * - `children` - Content to render
- * - All standard HTML attributes for the underlying element
- */
-type TypographyBaseProps<T extends React.ElementType> = {
-  /** The HTML element or component to render as */
-  as?: T;
-  /** Additional CSS classes for custom styling */
-  className?: string;
-  /** Content to render within the typography element */
-  children?: React.ReactNode;
-};
-
-type TypographyProps<T extends React.ElementType> = TypographyBaseProps<T> &
-  Omit<React.ComponentPropsWithoutRef<T>, keyof TypographyBaseProps<T>>;
-
-/**
- * Props for PageTitle (Documentation only - NOT used in component implementation)
- */
-// eslint-disable-next-line unused-imports/no-unused-vars
-type PageTitleDocsProps = {
-  /** The HTML element to render @default "h1" */
-  as?: React.ElementType;
-  /** Additional Tailwind CSS classes to customize styling */
-  className?: string;
-  /** Content to render within the page title */
-  children?: React.ReactNode;
-} & React.HTMLAttributes<HTMLHeadingElement>;
-
-/**
- * Props for SectionTitle (Documentation only - NOT used in component implementation)
- */
-// eslint-disable-next-line unused-imports/no-unused-vars
-type SectionTitleDocsProps = {
-  /** The HTML element to render @default "h2" */
-  as?: React.ElementType;
-  /** Additional Tailwind CSS classes to customize styling */
-  className?: string;
-  /** Content to render within the section title */
-  children?: React.ReactNode;
-} & React.HTMLAttributes<HTMLHeadingElement>;
-
-/**
- * Props for SubsectionTitle (Documentation only - NOT used in component implementation)
- */
-// eslint-disable-next-line unused-imports/no-unused-vars
-type SubsectionTitleDocsProps = {
-  /** The HTML element to render @default "h3" */
-  as?: React.ElementType;
-  /** Additional Tailwind CSS classes to customize styling */
-  className?: string;
-  /** Content to render within the subsection title */
-  children?: React.ReactNode;
-} & React.HTMLAttributes<HTMLHeadingElement>;
-
-/**
- * Props for BodyText (Documentation only - NOT used in component implementation)
- */
-// eslint-disable-next-line unused-imports/no-unused-vars
-type BodyTextDocsProps = {
-  /** The HTML element to render @default "p" */
-  as?: React.ElementType;
-  /** Additional Tailwind CSS classes to customize styling */
-  className?: string;
-  /** Content to render within the body text */
-  children?: React.ReactNode;
-} & React.HTMLAttributes<HTMLParagraphElement>;
-
-/**
- * Props for BodyTextLarge (Documentation only - NOT used in component implementation)
- */
-// eslint-disable-next-line unused-imports/no-unused-vars
-type BodyTextLargeDocsProps = {
-  /** The HTML element to render @default "p" */
-  as?: React.ElementType;
-  /** Additional Tailwind CSS classes to customize styling */
-  className?: string;
-  /** Content to render within the large body text */
-  children?: React.ReactNode;
-} & React.HTMLAttributes<HTMLParagraphElement>;
-
-/**
- * Props for BodyTextSmall (Documentation only - NOT used in component implementation)
- */
-// eslint-disable-next-line unused-imports/no-unused-vars
-type BodyTextSmallDocsProps = {
-  /** The HTML element to render @default "p" */
-  as?: React.ElementType;
-  /** Additional Tailwind CSS classes to customize styling */
-  className?: string;
-  /** Content to render within the small body text */
-  children?: React.ReactNode;
-} & React.HTMLAttributes<HTMLParagraphElement>;
-
-/**
- * Props for Caption (Documentation only - NOT used in component implementation)
- */
-// eslint-disable-next-line unused-imports/no-unused-vars
-type CaptionDocsProps = {
-  /** The HTML element to render @default "span" */
-  as?: React.ElementType;
-  /** Additional Tailwind CSS classes to customize styling */
-  className?: string;
-  /** Content to render within the caption */
-  children?: React.ReactNode;
-} & React.HTMLAttributes<HTMLSpanElement>;
-
-/**
- * Props for Overline (Documentation only - NOT used in component implementation)
- */
-// eslint-disable-next-line unused-imports/no-unused-vars
-type OverlineDocsProps = {
-  /** The HTML element to render @default "span" */
-  as?: React.ElementType;
-  /** Additional Tailwind CSS classes to customize styling */
-  className?: string;
-  /** Content to render within the overline */
-  children?: React.ReactNode;
-} & React.HTMLAttributes<HTMLSpanElement>;
-
-/**
- * Props for Code (Documentation only - NOT used in component implementation)
- */
-// eslint-disable-next-line unused-imports/no-unused-vars
-type CodeDocsProps = {
-  /** The HTML element to render @default "code" */
-  as?: React.ElementType;
-  /** Additional Tailwind CSS classes to customize styling */
-  className?: string;
-  /** Content to render within the code element */
-  children?: React.ReactNode;
-} & React.HTMLAttributes<HTMLElement>;
-
-/**
- * Props for Blockquote (Documentation only - NOT used in component implementation)
- */
-// eslint-disable-next-line unused-imports/no-unused-vars
-type BlockquoteDocsProps = {
-  /** The HTML element to render @default "blockquote" */
-  as?: React.ElementType;
-  /** Additional Tailwind CSS classes to customize styling */
-  className?: string;
-  /** Content to render within the blockquote */
-  children?: React.ReactNode;
-} & React.HTMLAttributes<HTMLQuoteElement>;
-
-/**
- * PageTitle - Primary page heading component
- *
- * The main heading for a page, typically used once per page. Uses text-3xl (30px)
- * which is appropriate for web application page titles. Defaults to h1 element.
- *
- * @param as - HTML element to render @default "h1"
- * @param className - Additional Tailwind classes (e.g., "text-4xl text-accent")
- * @param children - Content to render
- * @param ...props - All standard HTMLHeadingElement attributes
- *
- * @example
- * ```tsx
- * // Default usage
- * <PageTitle>User Dashboard</PageTitle>
- *
- * // With custom styling
- * <PageTitle className="text-4xl text-accent">
- *   Custom Styled Title
- * </PageTitle>
- *
- * // As different element
- * <PageTitle as="h2">Section Title as H2</PageTitle>
- *
- * // Responsive sizing
- * <PageTitle className="text-2xl md:text-3xl lg:text-4xl">
- *   Responsive Title
- * </PageTitle>
- * ```
- *
- * @accessibility
- * - Should be used once per page for proper document outline
- * - Provides main page topic for screen readers
- * - Helps with keyboard navigation landmarks
- */
-export function PageTitle<T extends React.ElementType = "h1">({
-  className,
-  as,
-  ...props
-}: TypographyProps<T>) {
-  const Component = as || "h1";
-  return (
-    <Component
-      className={cn("text-3xl font-bold leading-tight tracking-wide", className)}
-      {...props}
-    />
-  );
-}
-
-/**
- * SectionTitle - Secondary section heading component
- *
- * Section headings that divide page content into logical groups. Uses text-2xl (24px)
- * for clear hierarchy below PageTitle. Defaults to h2 element.
- *
- * @param as - HTML element to render @default "h2"
- * @param className - Additional Tailwind classes
- * @param children - Content to render
- * @param ...props - All standard HTMLHeadingElement attributes
- *
- * @example
- * ```tsx
- * // Default usage
- * <SectionTitle>Recent Activity</SectionTitle>
- *
- * // With custom color
- * <SectionTitle className="text-accent">
- *   Featured Section
- * </SectionTitle>
- *
- * // As h3 element
- * <SectionTitle as="h3">Subsection Title</SectionTitle>
- * ```
- *
- * @accessibility
- * - Maintains document outline hierarchy
- * - Should follow PageTitle (h1) in document flow
- * - Provides section navigation for screen readers
- */
-export function SectionTitle<T extends React.ElementType = "h2">({
-  className,
-  as,
-  ...props
-}: TypographyProps<T>) {
-  const Component = as || "h2";
-  return (
-    <Component
-      className={cn("text-2xl font-semibold leading-tight tracking-wide", className)}
-      {...props}
-    />
-  );
-}
-
-/**
- * SubsectionTitle - Tertiary subsection heading component
- *
- * Subsection headings for further content division. Uses text-xl (20px) for
- * subtle distinction from SectionTitle. Defaults to h3 element.
- *
- * @param as - HTML element to render @default "h3"
- * @param className - Additional Tailwind classes
- * @param children - Content to render
- * @param ...props - All standard HTMLHeadingElement attributes
- *
- * @example
- * ```tsx
- * // Default usage
- * <SubsectionTitle>Configuration Options</SubsectionTitle>
- *
- * // With custom styling
- * <SubsectionTitle className="text-muted-foreground">
- *   Optional Settings
- * </SubsectionTitle>
- * ```
- *
- * @accessibility
- * - Should follow SectionTitle (h2) in document flow
- * - Helps create detailed content structure
- * - Supports screen reader document navigation
- */
-export function SubsectionTitle<T extends React.ElementType = "h3">({
-  className,
-  as,
-  ...props
-}: TypographyProps<T>) {
-  const Component = as || "h3";
-  return (
-    <Component
-      className={cn("text-xl font-semibold leading-snug tracking-wide", className)}
-      {...props}
-    />
-  );
-}
-
-/**
- * BodyText - Primary paragraph text component
- *
- * Standard paragraph element for readable body text. Uses text-base (16px) with
- * relaxed line height for optimal readability. Defaults to p element.
- *
- * @param as - HTML element to render @default "p"
- * @param className - Additional Tailwind classes
- * @param children - Content to render
- * @param ...props - All standard HTMLParagraphElement attributes
- *
- * @example
- * ```tsx
- * // Default usage
- * <BodyText>
- *   This is standard body text that provides information to the user.
- * </BodyText>
- *
- * // With custom styling
- * <BodyText className="text-muted-foreground">
- *   Secondary information with reduced visual prominence.
- * </BodyText>
- *
- * // As different element
- * <BodyText as="div">
- *   Body text in a div container.
- * </BodyText>
- * ```
- *
- * @accessibility
- * - Provides proper semantic structure for body content
- * - Maintains readable line height for accessibility
- * - Supports screen reader text flow and navigation
- */
-export function BodyText<T extends React.ElementType = "p">({
-  className,
-  as,
-  ...props
-}: TypographyProps<T>) {
-  const Component = as || "p";
-  return (
-    <Component
-      className={cn("text-base leading-relaxed tracking-wide", className)}
-      {...props}
-    />
-  );
-}
-
-/**
- * BodyTextLarge - Emphasized body text component
- *
- * Larger body text for lead paragraphs and emphasized content. Uses text-lg (18px)
- * with relaxed line height. Defaults to p element.
- *
- * @param as - HTML element to render @default "p"
- * @param className - Additional Tailwind classes
- * @param children - Content to render
- * @param ...props - All standard HTMLParagraphElement attributes
- *
- * @example
- * ```tsx
- * // Lead paragraph
- * <BodyTextLarge>
- *   This is a lead paragraph that introduces the main content.
- * </BodyTextLarge>
- *
- * // Emphasized content
- * <BodyTextLarge className="font-medium text-accent">
- *   Important announcement text.
- * </BodyTextLarge>
- * ```
- */
-export function BodyTextLarge<T extends React.ElementType = "p">({
-  className,
-  as,
-  ...props
-}: TypographyProps<T>) {
-  const Component = as || "p";
-  return (
-    <Component
-      className={cn("text-lg leading-relaxed tracking-wide", className)}
-      {...props}
-    />
-  );
-}
-
-/**
- * BodyTextSmall - De-emphasized body text component
- *
- * Smaller body text for less prominent content. Uses text-sm (14px) with
- * normal line height. Defaults to p element.
- *
- * @param as - HTML element to render @default "p"
- * @param className - Additional Tailwind classes
- * @param children - Content to render
- * @param ...props - All standard HTMLParagraphElement attributes
- *
- * @example
- * ```tsx
- * // Small body text
- * <BodyTextSmall>
- *   This is smaller, less prominent body text.
- * </BodyTextSmall>
- *
- * // Helper text
- * <BodyTextSmall className="text-muted-foreground">
- *   Additional context or helper information.
- * </BodyTextSmall>
- * ```
- */
-export function BodyTextSmall<T extends React.ElementType = "p">({
-  className,
-  as,
-  ...props
-}: TypographyProps<T>) {
-  const Component = as || "p";
-  return (
-    <Component
-      className={cn("text-sm leading-normal tracking-wide", className)}
-      {...props}
-    />
-  );
-}
-
-/**
- * Caption - Small supplementary text component
- *
- * Small text for metadata, timestamps, and supplementary information. Uses text-sm (14px)
- * with muted color. Defaults to span element for inline usage.
- *
- * @param as - HTML element to render @default "span"
- * @param className - Additional Tailwind classes
- * @param children - Content to render
- * @param ...props - All standard HTMLSpanElement attributes
- *
- * @example
- * ```tsx
- * // Timestamp
- * <Caption>Last updated 2 minutes ago</Caption>
- *
- * // Image caption
- * <Caption>Figure 1: System architecture diagram</Caption>
- *
- * // Metadata
- * <Caption className="block mt-2">
- *   Created by John Doe on Jan 15, 2025
- * </Caption>
- * ```
- *
- * @accessibility
- * - Maintains inline text flow for screen readers
- * - Sufficient contrast with muted color
- * - Works well for supplementary information
- */
-export function Caption<T extends React.ElementType = "span">({
-  className,
-  as,
-  ...props
-}: TypographyProps<T>) {
-  const Component = as || "span";
-  return (
-    <Component
-      className={cn("text-sm text-muted-foreground leading-normal tracking-wide", className)}
-      {...props}
-    />
-  );
-}
-
-
-/**
- * Overline - Small uppercase label component
- *
- * Small uppercase text for category tags and eyebrow labels. Uses text-xs (12px)
- * with uppercase transformation and wide tracking. Defaults to span element.
- *
- * @param as - HTML element to render @default "span"
- * @param className - Additional Tailwind classes
- * @param children - Content to render
- * @param ...props - All standard HTMLSpanElement attributes
- *
- * @example
- * ```tsx
- * // Category label
- * <Overline>Featured</Overline>
- *
- * // Section eyebrow
- * <Overline className="text-accent-foreground">
- *   New Feature
- * </Overline>
- *
- * // Tag
- * <Overline className="bg-accent px-2 py-1 rounded">
- *   Beta
- * </Overline>
- * ```
- */
-export function Overline<T extends React.ElementType = "span">({
-  className,
-  as,
-  ...props
-}: TypographyProps<T>) {
-  const Component = as || "span";
-  return (
-    <Component
-      className={cn("text-xs font-medium uppercase tracking-wider", className)}
-      {...props}
-    />
-  );
-}
-
-/**
- * Code - Inline code component
- *
- * Monospace text for inline code snippets and technical references. Uses text-sm
- * with monospace font and subtle background. Defaults to code element.
- *
- * @param as - HTML element to render @default "code"
- * @param className - Additional Tailwind classes
- * @param children - Content to render
- * @param ...props - All standard HTMLElement attributes
- *
- * @example
- * ```tsx
- * // Inline code
- * <Code>const message = "Hello, world!";</Code>
- *
- * // Variable reference
- * <p>Set the <Code>API_KEY</Code> environment variable.</p>
- *
- * // Terminal command
- * <Code className="bg-accent">npm install @neynar/ui</Code>
- * ```
- *
- * @accessibility
- * - Uses semantic code element for proper meaning
- * - Monospace font aids in code readability
- * - Screen readers understand this as technical content
- */
-export function Code<T extends React.ElementType = "code">({
-  className,
-  as,
-  ...props
-}: TypographyProps<T>) {
-  const Component = as || "code";
-  return (
-    <Component
-      className={cn("font-mono text-sm bg-muted px-1 rounded", className)}
-      {...props}
-    />
-  );
-}
-
-/**
- * Blockquote - Quoted text component
- *
- * Semantic blockquote element for extended quotations and excerpts. Features
- * italic styling and left border for visual distinction. Defaults to blockquote element.
- *
- * @param as - HTML element to render @default "blockquote"
- * @param className - Additional Tailwind classes
- * @param children - Content to render
- * @param ...props - All standard HTMLQuoteElement attributes
- *
- * @example
- * ```tsx
- * // Simple quote
- * <Blockquote>
- *   "The best way to predict the future is to invent it."
- * </Blockquote>
- *
- * // With attribution
- * <div>
- *   <Blockquote>
- *     "Building great products requires deep understanding of user needs."
- *   </Blockquote>
- *   <Caption className="mt-2">— Product Team</Caption>
- * </div>
- *
- * // Custom styling
- * <Blockquote className="bg-muted/50 p-4 rounded-lg">
- *   Customer testimonial or feedback.
- * </Blockquote>
- * ```
- *
- * @accessibility
- * - Uses semantic blockquote element for proper quotation meaning
- * - Screen readers understand this as quoted content
- * - Maintains proper text flow and readability
- */
-export function Blockquote<T extends React.ElementType = "blockquote">({
-  className,
-  as,
-  ...props
-}: TypographyProps<T>) {
-  const Component = as || "blockquote";
-  return (
-    <Component
-      className={cn("border-l-4 border-border pl-4 italic tracking-wide", className)}
-      {...props}
-    />
-  );
-}