@blakesteve/roster 2.6.2 → 2.8.0

package/README.md

@@ -1,113 +1,168 @@
-# Roster 📋
+# @blakesteve/roster ✦
 
-**Roster** is the atomic UI component library powering the **MegaSquad** ecosystem.
+A production-grade atomic component library built with **React 19**, **TypeScript**, **Tailwind CSS v4**, and **Vite**.
 
-It is built with **React 19**, **TypeScript**, **Tailwind CSS v4**, and **Vite**, offering a set of high-quality, accessible, and theme-aware components.
+Roster ships a curated set of accessible, theme-aware components organized around the Atomic Design methodology — atoms, molecules, and organisms — each with Storybook documentation and full test coverage.
 
-## 🚀 Features
+## Features
 
-- **Next.js App Router Ready:** All components are automatically bundled with `"use client"` directives for seamless SSR integration without context crashes.
-- **Decoupled Theming:** Bring your own brand. Roster ships structural CSS separately from its default design tokens, allowing you to easily override CSS variables or use the default MegaSquad theme.
-- **Atomic Design:** Components organized by atoms, molecules, and organisms.
-- **TypeScript First:** Fully typed for excellent developer experience (DX).
-- **Adaptive Dark Mode:** Fully supports manual, class-based dark mode toggling (`.dark`) independent of OS preferences.
-- **Headless UI:** Accessible interactive components powered by `@headlessui/react`.
-- **Tree-Shakeable:** Import only what you need.
+- **Atomic Design** — components organized as atoms, molecules, and organisms
+- **TypeScript first** — fully typed props with exported variant types for maximum DX
+- **Adaptive dark mode** — class-based toggling (`.dark`) independent of OS preferences
+- **`"use client"` pre-bundled** — all outputs include the directive for seamless Next.js App Router integration
+- **Accessible** — interactive components powered by [`@headlessui/react`](https://headlessui.com) and [`@radix-ui`](https://radix-ui.com)
+- **Tree-shakeable** — import only what you need
 
-## 📦 Installation
+## Installation
 
 ```bash
-npm install roster
-# or
-yarn add roster
+npm install @blakesteve/roster
 ```
 
-### Peer Dependencies
+Roster ships pre-compiled CSS — you do not need Tailwind installed in your host app to use it.
 
-Roster relies on a few peer dependencies that must be installed in your host application:
+### Peer dependencies
 
 ```json
-"peerDependencies": {
+{
   "react": "^19.0.0",
-  "react-dom": "^19.0.0",
-  "tailwindcss": "^4.0.0"
+  "react-dom": "^19.0.0"
 }
 ```
 
-## 💻 Usage
+## Setup
 
-### 1. Import Styles
+Import Roster's CSS once at the root of your application (`layout.tsx`, `main.tsx`, or `App.tsx`):
 
-Roster splits its CSS into two parts to give you ultimate flexibility over your theme. You must import the CSS at the root of your application (e.g., in `layout.tsx`, `main.tsx`, or `App.tsx`).
-
-````tsx
-// 1. Required: The structural Tailwind utility classes
-import "roster/dist/roster.css";
-
-// 2. Optional: The default MegaSquad color and theme tokens
-// (Omit this file if you are defining your own --roster-* variables in your app's global CSS)
-import "roster/dist/tokens.css";
+```tsx
+// Compiled component styles — always required
+import "@blakesteve/roster/style.css";
 
-### 2. Import Components
+// Default design tokens (color palette, spacing, radius)
+// Omit this if you are supplying your own --roster-* CSS variables
+import "@blakesteve/roster/tokens.css";
+```
 
-Now you can use the components anywhere in your app.
+## Quick start
 
 ```tsx
-import { Button, Spinner } from "roster";
+import { Button, Spinner } from "@blakesteve/roster";
 
 function App() {
   return (
-    <div className="p-4 flex flex-col gap-4">
-      {/* Primary Button */}
-      <Button colorScheme="primary" onClick={() => alert("Clicked!")}>
-        Save Changes
+    <div className="flex flex-col gap-4 p-4">
+      <Button colorScheme="primary" onClick={() => alert("Saved!")}>
+        Save changes
       </Button>
 
-      {/* Destructive Variant */}
-      <Button colorScheme="destructive" variant="outline">
-        Delete Account
+      <Button colorScheme="error" variant="outline">
+        Delete account
       </Button>
 
-      {/* Loading State */}
-      <Button isLoading>Processing...</Button>
+      <Button isLoading>Processing…</Button>
 
-      {/* Standalone Spinner */}
-      <Spinner size="lg" className="text-accent-500" />
+      <Spinner size="lg" />
     </div>
   );
 }
-````
-
-## 🎨 Development
+```
 
-We use **Storybook** to develop and document components in isolation.
+## Component catalog
+
+### Atoms
+
+| Component | Description |
+|---|---|
+| `Avatar` | User avatar with image, initials fallback, and optional popover |
+| `Badge` | Status label with semantic color schemes and fill variants |
+| `Button` | Primary interactive element — solid, soft, outline, ghost, link variants |
+| `Card` | Bordered surface container |
+| `Checkbox` | Accessible checkbox with label support |
+| `Disclosure` | Show/hide toggle using HeadlessUI |
+| `Input` | Text input with label, error state, and icon slots |
+| `Link` | Styled anchor with variant support |
+| `Select` | Dropdown selector |
+| `Spinner` | Loading indicator |
+| `Switch` | Toggle switch |
+| `Textarea` | Multi-line text input |
+| `Tooltip` | Radix-powered tooltip — hover/focus on desktop, tap-to-toggle on mobile |
+
+### Molecules
+
+| Component | Description |
+|---|---|
+| `Accordion` | Collapsible content sections (single or multi-expand) |
+| `Breadcrumbs` | Navigation trail |
+| `CallToAction` | Prominent hero-style CTA block |
+| `EmptyState` | Zero-data placeholder with icon and action slot |
+| `ErrorState` | Error display with retry action |
+| `MatchupCard` | Head-to-head comparison card |
+
+### Organisms
+
+| Component | Description |
+|---|---|
+| `ActionBar` | Sticky bottom action strip |
+| `Countdown` | Live countdown timer |
+| `DataTable` | Full-featured table with sorting and pagination via TanStack Table |
+| `Dialog` | Modal dialog |
+| `Footer` | Site footer |
+| `Navbar` | Responsive navigation bar with mobile slide-out |
+| `Table` | Static data table |
+
+### Hooks
+
+| Hook | Description |
+|---|---|
+| `useCountdown` | Countdown timer logic without the UI |
+
+## Development
+
+Storybook is the component playground. Each component has dedicated stories covering all variants, props, and light/dark mode.
 
 ```bash
-# Install dependencies
 npm install
-
-# Start Storybook
 npm run storybook
+# → http://localhost:6006
 ```
 
-This will open the component playground at http://localhost:6006.
+## Testing
 
-## 🛠️ Building
+```bash
+# Unit tests (Vitest + jsdom)
+npm run test:run
+
+# Unit tests in watch mode
+npm run test
+
+# Storybook interaction tests (Vitest + Playwright)
+npx vitest run --project storybook
+```
 
-To build the library for production (outputs to `dist/`):
+## Building
 
 ```bash
 npm run build
 ```
 
-This generates:
+Output in `dist/`:
+
+| File | Description |
+|---|---|
+| `roster.es.js` | ES module bundle |
+| `roster.umd.js` | UMD bundle |
+| `roster.css` | Compiled component styles |
+| `tokens.css` | Design token CSS variables |
+| `index.d.ts` | TypeScript definitions |
+
+## Contributing
+
+Pull requests are welcome. Please:
 
-- `dist/roster.es.js` (Main library ES Modules)
-- `dist/tokens.es.js` (Token injection script)
-- `dist/roster.css` (Compiled structural Tailwind styles)
-- `dist/tokens.css` (Design token CSS variables)
-- `dist/index.d.ts` (Type definitions)
+1. Open an issue or discussion first for significant changes
+2. Follow the existing code style (CVA variants, forwardRef, Storybook stories, unit tests)
+3. Fill out the pull request template checklist before requesting review
 
-## 📄 License
+## License
 
-MIT © Blake Ball
+MIT © [Blake Ball](https://github.com/blakesteve)

package/dist/components/atoms/AvatarStrip/AvatarStrip.d.ts

@@ -0,0 +1,53 @@
+import { ReactNode } from 'react';
+export type AvatarStripColorScheme = "primary" | "orange" | "teal" | "purple" | "amber" | "success" | "error" | "neutral";
+export interface AvatarStripItem {
+    /** Unique identifier. Pass as `excludeKey` to hide this item (e.g. current user). */
+    key: string;
+    /** Display name — used as the avatar title and the source of the single-letter initials. */
+    label: string;
+    /** Avatar image URL. Falls back to initials when omitted or when the image fails to load. */
+    src?: string;
+    /** Background color scheme for the initials avatar. Defaults to `"neutral"`. */
+    colorScheme?: AvatarStripColorScheme;
+    /** When provided, the avatar is wrapped in an `<a>` tag with this href. */
+    href?: string;
+}
+export interface AvatarStripProps {
+    /** Ordered list of avatar items. */
+    items: AvatarStripItem[];
+    /** Maximum number of avatars to show before collapsing into a +N chip. Default: `5`. */
+    maxDisplay?: number;
+    /**
+     * The true total count. When provided, the overflow chip shows
+     * `totalCount - visible.length` instead of `items.length - maxDisplay`,
+     * keeping the number accurate when the fetched array is a subset of the real total.
+     */
+    totalCount?: number;
+    /** Remove one item by key before rendering — typically used to hide the current user. */
+    excludeKey?: string;
+    /** When provided, renders a `✕` dismiss button at the leading edge of the strip. */
+    onDismiss?: () => void;
+    /**
+     * Rendered immediately after the overflow chip inside the avatar stack.
+     * Use for a ghost-slot CTA, an add-member button, or any custom element
+     * that should sit within the `-space-x-2` stack.
+     */
+    trailingSlot?: ReactNode;
+    /** Rendered to the right of the avatar stack. Accepts any React node. */
+    label?: ReactNode;
+    /**
+     * Tailwind class that sets the ring color around each avatar and the overflow chip.
+     * Should match the background the strip is rendered on to produce the cutout stack effect.
+     * Default: `"ring-white dark:ring-gray-900"`.
+     */
+    ringClass?: string;
+    /** Extra classes applied to the outermost `<div>`. */
+    className?: string;
+}
+/**
+ * A compact social-proof strip: a stacked row of overlapping avatars with an
+ * optional overflow chip, dismiss button, trailing slot, and label area.
+ *
+ * Returns `null` when there are no visible items and no `trailingSlot`.
+ */
+export declare function AvatarStrip({ items, maxDisplay, totalCount, excludeKey, onDismiss, trailingSlot, label, ringClass, className, }: AvatarStripProps): import("react/jsx-runtime").JSX.Element | null;

package/dist/components/atoms/CollapsibleDescription/CollapsibleDescription.d.ts

@@ -0,0 +1,20 @@
+import * as React from "react";
+export type CollapsibleDescriptionSize = "sm" | "md" | "lg";
+export interface CollapsibleDescriptionProps {
+    /** Content to display. Accepts a string or any React node. */
+    children: React.ReactNode;
+    /** Controls how many lines are visible before the toggle appears. */
+    size?: CollapsibleDescriptionSize;
+    /** Label for the expand button. */
+    expandLabel?: string;
+    /** Label for the collapse button. */
+    collapseLabel?: string;
+    /** Extra classes applied to the outer wrapper. */
+    className?: string;
+}
+/**
+ * Clamps content to a fixed height and reveals a toggle when it overflows.
+ * Uses CSS `mask-image` for the fade-out effect so it works on any background
+ * without needing to know the background color.
+ */
+export declare function CollapsibleDescription({ children, size, expandLabel, collapseLabel, className, }: CollapsibleDescriptionProps): import("react/jsx-runtime").JSX.Element;

package/dist/components/atoms/LiquidTabs/LiquidTabs.d.ts

@@ -0,0 +1,39 @@
+import { ReactNode } from 'react';
+export interface TabItem {
+    id: string;
+    /** Static label, or a render function that receives whether this tab is active. */
+    label: ReactNode | ((isActive: boolean) => ReactNode);
+}
+export interface LiquidTabsProps {
+    tabs: TabItem[];
+    /** The `id` of the currently active tab. */
+    activeTab: string;
+    /** Called with the new tab `id` when the user selects a different tab. */
+    onChange: (id: string) => void;
+    /**
+     * `"pill"` (default) — floating pill inside a padded container.
+     *   Width is `w-fit` by default; use `fullWidth` to stretch it.
+     *   Liquid feel via scaleY squash during the stretch phase.
+     *
+     * `"filled"` — active tab fills its entire cell; container is always `w-full`.
+     *   Liquid feel via border-radius morphing (oval during stretch) so the
+     *   full-height pill never gaps at the container edges.
+     */
+    variant?: "pill" | "filled";
+    /** Stretch the `pill` variant container to full width with `flex-1` buttons. */
+    fullWidth?: boolean;
+    /** Extra classes applied to the outer container. */
+    className?: string;
+}
+/**
+ * Controlled tab strip with a liquid sliding indicator.
+ *
+ * The pill animation is driven by direct DOM ref manipulation (no setState)
+ * to avoid re-renders during the transition. Two-phase motion:
+ *   1. Stretch — pill expands to span the gap between old and new tab (130 ms ease-out).
+ *   2. Contract — pill snaps to the target tab (160 ms ease-in).
+ *
+ * `getBoundingClientRect` is used to measure tab positions, so the component
+ * must be rendered in a document with a real layout engine to animate.
+ */
+export declare function LiquidTabs({ tabs, activeTab, onChange, variant, fullWidth, className, }: LiquidTabsProps): import("react/jsx-runtime").JSX.Element;

package/dist/components/atoms/SegmentBar/SegmentBar.d.ts

@@ -0,0 +1,30 @@
+export type SegmentBarSize = "sm" | "md";
+export interface SegmentBarSegment {
+    /** Unique identifier for the segment. */
+    key: string;
+    /** Display label used in the legend and the bar segment's title tooltip. */
+    label: string;
+    /** Raw vote / count / quantity. Percentages are computed from the total. */
+    value: number;
+    /** CSS color for the bar segment and legend dot (hex, rgb, hsl, or CSS variable). */
+    color: string;
+}
+export interface SegmentBarProps {
+    /** Ordered list of segments rendered left to right. */
+    segments: SegmentBarSegment[];
+    /** Height of the bar track. */
+    size?: SegmentBarSize;
+    /** Render a dot-and-label legend below the bar. */
+    showLegend?: boolean;
+    /** Extra classes applied to the outer wrapper. */
+    className?: string;
+}
+/**
+ * A proportional horizontal bar divided into colored segments.
+ * Percentages are computed automatically from raw `value` fields.
+ * Colors are passed as CSS color strings so any palette works without
+ * requiring specific Tailwind classes to be present in the consumer's build.
+ *
+ * Returns `null` when all segment values sum to zero.
+ */
+export declare function SegmentBar({ segments, size, showLegend, className, }: SegmentBarProps): import("react/jsx-runtime").JSX.Element | null;

package/dist/components/atoms/Tooltip/Tooltip.d.ts

@@ -0,0 +1,31 @@
+import * as React from "react";
+export type TooltipPlacement = "top" | "bottom" | "left" | "right";
+export type TooltipVariant = "dark" | "light";
+export interface TooltipProps {
+    /** The tooltip's popup content. Accepts a string or any React node. */
+    content: React.ReactNode;
+    /** The element that triggers the tooltip on hover, focus, or tap. */
+    children: React.ReactNode;
+    /** Which side of the trigger the tooltip appears on. Radix auto-flips if there isn't enough room. */
+    placement?: TooltipPlacement;
+    /** Visual theme for the tooltip bubble. `dark` is the default and works on both light and dark backgrounds. */
+    variant?: TooltipVariant;
+    /** Milliseconds of hover delay before the tooltip opens (default 300). */
+    delayDuration?: number;
+    /** Mount the tooltip open — useful for visual stories and testing. */
+    defaultOpen?: boolean;
+    /** Extra classes applied to the tooltip content bubble. */
+    className?: string;
+}
+/**
+ * Radix-powered tooltip with a caret arrow and entry animation.
+ *
+ * - **Desktop:** opens on hover (configurable delay) or keyboard focus.
+ * - **Mobile:** tap the trigger to toggle open; tap anywhere else to dismiss.
+ *   This avoids tooltips getting permanently stuck open on touchscreens.
+ *
+ * The trigger is wrapped in a focusable `<span>` so any element — including
+ * non-interactive ones — can act as a tooltip anchor without breaking
+ * Radix's `asChild` forwarding.
+ */
+export declare function Tooltip({ content, children, placement, variant, delayDuration, defaultOpen, className, }: TooltipProps): import("react/jsx-runtime").JSX.Element;

package/dist/components/organisms/Footer/Footer.d.ts

@@ -1,11 +1,26 @@
 import { default as React } from 'react';
 import { VariantProps } from 'class-variance-authority';
 import { footerVariants } from './footer-variants';
+export interface FooterLink {
+    label: string;
+    href: string;
+}
 export interface FooterProps extends React.HTMLAttributes<HTMLElement>, VariantProps<typeof footerVariants> {
-    /** * The company name to display in the copyright notice.
+    /**
+     * The company name to display in the copyright notice.
      * @default "Ball Collaborative"
      */
     companyName?: string;
+    /**
+     * Optional navigation links rendered as a row above the copyright line.
+     * Useful for pages like Privacy Policy, Contact, Terms, etc.
+     */
+    links?: FooterLink[];
+    /**
+     * Router-aware link element (e.g. Next.js `Link`). When provided, each
+     * footer link is rendered with this element instead of a plain `<a>` tag.
+     */
+    routerElement?: React.ElementType;
 }
 declare const Footer: React.ForwardRefExoticComponent<FooterProps & React.RefAttributes<HTMLElement>>;
 export { Footer };

package/dist/index.d.ts

@@ -21,6 +21,11 @@ export * from './components/atoms/Switch/Switch';
 export * from './components/atoms/Switch/switch-variants';
 export * from './components/atoms/Textarea/Textarea';
 export * from './components/atoms/Textarea/textarea-variants';
+export * from './components/atoms/AvatarStrip/AvatarStrip';
+export * from './components/atoms/LiquidTabs/LiquidTabs';
+export * from './components/atoms/Tooltip/Tooltip';
+export * from './components/atoms/CollapsibleDescription/CollapsibleDescription';
+export * from './components/atoms/SegmentBar/SegmentBar';
 export * from './components/molecules/Accordion/Accordion';
 export * from './components/molecules/Breadcrumbs/Breadcrumbs';
 export * from './components/molecules/Breadcrumbs/breadcrumb-variants';