fansunited-sports-ui 0.0.1

package/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2024 Fans United
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+

package/README.md

@@ -0,0 +1,269 @@
+# fansunited-sports-ui
+
+A comprehensive React component library for building sports websites and applications. Built with **Tailwind CSS v4** for seamless theming integration.
+
+[![npm version](https://img.shields.io/npm/v/fansunited-sports-ui)](https://www.npmjs.com/package/fansunited-sports-ui)
+[![license](https://img.shields.io/npm/l/fansunited-sports-ui)](https://github.com/nicklatkovich/fansunited-sports-ui/blob/main/LICENSE)
+
+## Features
+
+- 🏟️ **Sports-focused** — Purpose-built for media sites, football clubs, federations, and betting affiliates
+- 🎨 **Tailwind CSS v4** — Uses native Tailwind classes to automatically match your design system
+- 📦 **Three-layer architecture** — Primitives, Components, and Blocks for flexible composition
+- 🎯 **Type-Safe** — Full TypeScript support with comprehensive type definitions
+- 🔧 **Highly Customizable** — Flexible styling system with standardized customization options
+- 📱 **Responsive** — Mobile-first design that works on all screen sizes
+- 🎭 **Theme Support** — Works with Tailwind's theme system and custom color palettes
+
+---
+
+## Installation
+
+Install the package via npm:
+
+```bash
+npm install fansunited-sports-ui
+```
+
+### Peer Dependencies
+
+This library requires the following peer dependencies:
+
+```json
+{
+    "react": "^18.0.0 || ^19.0.0",
+    "react-dom": "^18.0.0 || ^19.0.0",
+    "tailwindcss": "^4.0.0",
+    "@tailwindcss/postcss": "^4.0.0"
+}
+```
+
+Install them if you haven't already:
+
+```bash
+npm install react react-dom tailwindcss @tailwindcss/postcss
+```
+
+---
+
+## Setup
+
+### 1. Configure Tailwind CSS
+
+Update your Tailwind CSS configuration to scan the component library files. This ensures that all Tailwind classes used by the components are included in your build.
+
+**For Tailwind CSS v4 with `@import` in CSS:**
+
+In your main CSS file (e.g., `src/index.css` or `app/globals.css`):
+
+```css
+@import "tailwindcss";
+
+/* Your custom theme and styles */
+```
+
+**Configure content paths in `tailwind.config.js` (or `tailwind.config.ts`):**
+
+```js
+/** @type {import('tailwindcss').Config} */
+export default {
+    content: [
+        "./index.html",
+        "./src/**/*.{js,ts,jsx,tsx}",
+        // Add this line to scan the component library
+        "./node_modules/fansunited-sports-ui/dist/**/*.{js,mjs,cjs}",
+    ],
+    theme: {
+        extend: {},
+    },
+    plugins: [],
+};
+```
+
+**Important:** The component library uses Tailwind's native color classes (e.g., `bg-primary-600`, `from-primary-600`) instead of hardcoded colors. This means the components will automatically match your application's design system and theme.
+
+### 2. Configure PostCSS
+
+Ensure your `postcss.config.js` includes the Tailwind CSS PostCSS plugin:
+
+```js
+export default {
+    plugins: {
+        "@tailwindcss/postcss": {},
+        autoprefixer: {},
+    },
+};
+```
+
+### 3. Define Your Theme (Optional)
+
+The components use Tailwind's color system. You can customize the primary and secondary colors in your CSS using the `@theme` directive:
+
+```css
+@import "tailwindcss";
+
+@theme {
+    /* Primary color palette */
+    --color-primary-50: oklch(0.97 0.01 250);
+    --color-primary-100: oklch(0.93 0.03 250);
+    --color-primary-200: oklch(0.85 0.06 250);
+    --color-primary-300: oklch(0.75 0.1 250);
+    --color-primary-400: oklch(0.65 0.14 250);
+    --color-primary-500: oklch(0.57 0.17 250);
+    --color-primary-600: oklch(0.5 0.17 250);
+    --color-primary-700: oklch(0.43 0.15 250);
+    --color-primary-800: oklch(0.35 0.12 250);
+    --color-primary-900: oklch(0.27 0.09 250);
+    --color-primary-950: oklch(0.18 0.06 250);
+
+    /* Secondary color palette */
+    --color-secondary-50: oklch(0.97 0.02 50);
+    --color-secondary-100: oklch(0.94 0.04 50);
+    --color-secondary-200: oklch(0.88 0.08 50);
+    --color-secondary-300: oklch(0.8 0.12 50);
+    --color-secondary-400: oklch(0.72 0.15 50);
+    --color-secondary-500: oklch(0.68 0.18 50);
+    --color-secondary-600: oklch(0.62 0.18 50);
+    --color-secondary-700: oklch(0.54 0.16 50);
+    --color-secondary-800: oklch(0.45 0.13 50);
+    --color-secondary-900: oklch(0.36 0.1 50);
+    --color-secondary-950: oklch(0.25 0.07 50);
+}
+```
+
+---
+
+## Quick Start
+
+### Basic Usage
+
+Import and use the components in your React application:
+
+```tsx
+import { MatchScore, ContentCard } from "fansunited-sports-ui";
+
+function App() {
+    return (
+        <MatchScore
+            match={{
+                id: "1",
+                competitorOne: { id: "1", name: "Arsenal", score: { main: 2 } },
+                competitorTwo: { id: "2", name: "Chelsea", score: { main: 1 } },
+                status: "final",
+            }}
+            variant="scoreCard"
+        />
+    );
+}
+```
+
+---
+
+## Architecture
+
+The library is organized into three layers:
+
+### Layer 1: Primitives
+
+Pure UI building blocks with no domain knowledge:
+
+| Component                | Description                        |
+| ------------------------ | ---------------------------------- |
+| `Badge` / `BadgeGroup`   | Status labels and tags             |
+| `CtaButton` / `CtaGroup` | Call-to-action buttons             |
+| `EntityDisplay`          | Generic entity with image and name |
+| `Countdown`              | Timer display                      |
+| `Pagination`             | Page navigation                    |
+| `Tooltip`                | Hover information                  |
+
+### Layer 2: Components
+
+Domain-aware components with single responsibility:
+
+| Component         | Description                                                                                |
+| ----------------- | ------------------------------------------------------------------------------------------ |
+| `MatchScore`      | Match display with variants: `inline`, `scoreCard`, `scoreLine`, `embedded`                |
+| `ContentCard`     | Flexible cards with variants: `hero`, `standard`, `standardHorizontal`, `promo`, `minimal` |
+| `BettingOdds`     | Odds display with operator branding                                                        |
+| `StatsTable`      | Tabular statistics (standings, leaderboards)                                               |
+| `StatsGrid`       | Grid of stat items                                                                         |
+| `StatsHeadToHead` | Comparison bars                                                                            |
+| `FormIndicator`   | Win/draw/loss form display                                                                 |
+| `ProfileHeader`   | Entity profile headers                                                                     |
+| `MatchupHeader`   | Two-entity matchup display                                                                 |
+| `SectionHeader`   | Section titles with optional actions                                                       |
+
+### Layer 3: Blocks
+
+Pre-assembled composites ready for use:
+
+| Block                    | Description                       |
+| ------------------------ | --------------------------------- |
+| `MatchListBlock`         | List of matches with grouping     |
+| `ContentListBlock`       | Grid/list of content cards        |
+| `FeaturedContentBlock`   | Hero + supporting content layouts |
+| `HeadToHeadBlock`        | Complete H2H comparison           |
+| `CompetitorProfileBlock` | Full competitor profile           |
+| `SquadBlock`             | Team squad display                |
+
+---
+
+## Styling
+
+Every component accepts a `styles` prop for customization:
+
+```tsx
+<MatchScore
+    match={match}
+    styles={{
+        borderRadius: "lg",
+        shadow: "md",
+        padding: "lg",
+        typography: {
+            teamName: "text-lg font-bold",
+            score: "text-3xl font-black",
+        },
+    }}
+/>
+```
+
+### Common Style Options
+
+| Option                   | Values                                                             |
+| ------------------------ | ------------------------------------------------------------------ |
+| `borderRadius`           | `none` \| `sm` \| `md` \| `lg` \| `xl` \| `2xl` \| `3xl` \| `full` |
+| `shadow` / `hoverShadow` | `none` \| `sm` \| `md` \| `lg` \| `xl` \| `2xl`                    |
+| `padding`                | `none` \| `sm` \| `md` \| `lg` \| `xl`                             |
+| `typography`             | Tailwind classes for text elements                                 |
+| `background`             | Custom background classes                                          |
+| `container`              | Additional container classes                                       |
+
+---
+
+## TypeScript Support
+
+All components are fully typed. Import types as needed:
+
+```tsx
+import type {
+    MatchScoreContent,
+    MatchScoreProps,
+    CardContent,
+    CardStyles,
+    Competitor,
+    MatchSimple,
+} from "fansunited-sports-ui";
+```
+
+---
+
+## Browser Support
+
+- Chrome, Firefox, Safari, Edge (latest 2 versions)
+- React 18.x or 19.x
+
+---
+
+## License
+
+MIT © [Fans United](https://fansunited.com)

package/dist/BADGE.md

@@ -0,0 +1,50 @@
+# Badge
+
+A visual badge component for displaying labels, tags, or status indicators.
+
+## Usage
+
+```tsx
+import { Badge } from "@fansunited/tailwind-ui-components";
+
+// Primary badge
+<Badge badge={{ text: "NEW", variant: "primary", position: "top-right" }} />
+
+// Success badge
+<Badge badge={{ text: "Live", variant: "success", position: "top-left" }} />
+
+// Custom styled badge
+<Badge badge={{ text: "VIP", variant: "custom", position: "top-right", styles: { container: "bg-gold text-black" } }} />
+```
+
+## Props
+
+| Prop    | Type          | Description                |
+| ------- | ------------- | -------------------------- |
+| `badge` | `BadgeConfig` | Badge configuration object |
+
+### BadgeConfig
+
+| Property   | Type                                                                                                | Default     | Description                        |
+| ---------- | --------------------------------------------------------------------------------------------------- | ----------- | ---------------------------------- |
+| `text`     | `string`                                                                                            | -           | Badge text content                 |
+| `variant`  | `"default" \| "primary" \| "secondary" \| "success" \| "warning" \| "danger" \| "info" \| "custom"` | `"default"` | Visual variant                     |
+| `position` | `"top-left" \| "top-right" \| "bottom-left" \| "bottom-right"`                                      | -           | Position when used in card context |
+| `styles`   | `BadgeStyles`                                                                                       | -           | Style customization options        |
+
+### BadgeStyles
+
+| Property    | Type     | Description                                                 |
+| ----------- | -------- | ----------------------------------------------------------- |
+| `container` | `string` | Tailwind classes for the badge (used with "custom" variant) |
+
+## Variants
+
+- **default**: Neutral gray background
+- **primary**: Primary color background
+- **secondary**: Secondary color background
+- **success**: Green background
+- **warning**: Yellow background
+- **danger**: Red background
+- **info**: Cyan background
+- **custom**: No default styles - use `styles.container` for full customization

package/dist/BADGE_GROUP.md

@@ -0,0 +1,43 @@
+# BadgeGroup
+
+A component for rendering multiple badges at specific positions within a container.
+
+## Usage
+
+```tsx
+import { BadgeGroup } from "@fansunited/tailwind-ui-components";
+
+// Render all badges
+<BadgeGroup badges={content.badges} />
+
+// Only render top badges
+<BadgeGroup badges={content.badges} positions={["top-left", "top-right"]} />
+
+// With custom container styling
+<BadgeGroup badges={content.badges} styles={{ container: "p-4" }} />
+```
+
+## Props
+
+| Prop        | Type                                                                  | Default       | Description                 |
+| ----------- | --------------------------------------------------------------------- | ------------- | --------------------------- |
+| `badges`    | `BadgeConfig[]`                                                       | -             | Array of badge configs      |
+| `positions` | `Array<"top-left" \| "top-right" \| "bottom-left" \| "bottom-right">` | All positions | Filter badges by position   |
+| `styles`    | `BadgeGroupStyles`                                                    | -             | Style customization options |
+
+### BadgeGroupStyles
+
+| Property    | Type     | Description                                        |
+| ----------- | -------- | -------------------------------------------------- |
+| `container` | `string` | Tailwind classes for each position group container |
+
+## Positioning
+
+Badges are automatically positioned using absolute positioning:
+
+- **top-left**: Top left corner with padding
+- **top-right**: Top right corner with padding
+- **bottom-left**: Bottom left corner with padding
+- **bottom-right**: Bottom right corner with padding
+
+Multiple badges at the same position are displayed in a flex row with gap.

package/dist/BETTING_ODDS.md

@@ -0,0 +1,245 @@
+# BettingOdds Component
+
+A flexible React component for displaying betting odds with operator branding, change indicators, and multiple display modes.
+
+## Features
+
+- **Responsive Layouts**: Automatically switches between horizontal and grid layouts based on the number of odds
+- **Operator Branding**: Display betting operator logos with custom colors
+- **Change Indicators**: Visual arrows showing odds movement (up/down)
+- **Deep Linking**: Support for clickable odds and operator logos
+- **Flash Mode**: Alternating display between operator logo and odds
+- **Customizable Styling**: Configurable padding, typography, and display modes
+
+## Installation
+
+```tsx
+import { BettingOdds } from "@fansunited/tailwind-ui-components";
+import type { BettingOddsProps } from "@fansunited/tailwind-ui-components";
+```
+
+## Basic Usage
+
+### Simple 1X2 Odds
+
+```tsx
+<BettingOdds
+    odds={[
+        { label: "1", value: 2.8, change: "up" },
+        { label: "X", value: 3.1, change: "none" },
+        { label: "2", value: 2.5, change: "down" },
+    ]}
+    operator={{
+        name: "Bet365",
+        logo: { url: "https://example.com/bet365-logo.png", alt: "Bet365" },
+        url: "https://www.bet365.com",
+        backgroundColor: "#037b5b",
+        textColor: "#ffffff",
+    }}
+/>
+```
+
+### Moneyline (2 Odds)
+
+```tsx
+<BettingOdds
+    odds={[
+        { label: "Home Win", value: 1.85, url: "https://example.com/home" },
+        { label: "Away Win", value: 2.05, url: "https://example.com/away" },
+    ]}
+    operator={{
+        name: "William Hill",
+        url: "https://www.williamhill.com",
+    }}
+/>
+```
+
+## Layout Behavior
+
+The component automatically adjusts its layout based on the number of odds:
+
+- **1-3 odds**: Horizontal layout with operator logo (max 110px width) on the left
+- **4+ odds**: Vertical layout with full-width operator logo on top and odds in a 3-column grid
+
+## Props
+
+### `BettingOddsProps`
+
+| Prop       | Type                | Required | Default | Description                                  |
+| ---------- | ------------------- | -------- | ------- | -------------------------------------------- |
+| `odds`     | `OddsValue[]`       | Yes      | -       | Array of odds values to display              |
+| `operator` | `BettingOperator`   | No       | -       | Betting operator providing the odds          |
+| `label`    | `string`            | No       | -       | Overall label for odds section (e.g., "1X2") |
+| `styles`   | `BettingOddsStyles` | No       | `{}`    | Style configuration                          |
+
+### `OddsValue`
+
+| Property      | Type                       | Required | Description                                         |
+| ------------- | -------------------------- | -------- | --------------------------------------------------- |
+| `label`       | `string`                   | Yes      | Label for the odd (e.g., "1", "X", "2", "Over 2.5") |
+| `value`       | `number \| string`         | Yes      | Odds value (e.g., 2.8, "1")                         |
+| `url`         | `string`                   | No       | Deep link URL for this specific odd                 |
+| `change`      | `"up" \| "down" \| "none"` | No       | Change indicator (default: "none")                  |
+| `onClick`     | `(odd: OddsValue) => void` | No       | Click handler (suppresses default navigation)       |
+| `eventId`     | `string`                   | No       | Optional event ID for platform integration          |
+| `selectionId` | `string`                   | No       | Optional selection ID for platform integration      |
+
+### `BettingOperator`
+
+| Property          | Type                                  | Required | Description                                   |
+| ----------------- | ------------------------------------- | -------- | --------------------------------------------- |
+| `name`            | `string`                              | Yes      | Operator name (e.g., "Bet365")                |
+| `url`             | `string`                              | Yes      | Deep link URL to the betting page             |
+| `logo`            | `ImageWithVariations`                 | No       | Operator logo                                 |
+| `backgroundColor` | `string`                              | No       | Custom background color (e.g., "#1e3a8a")     |
+| `textColor`       | `string`                              | No       | Custom text color (e.g., "#ffffff")           |
+| `onClick`         | `(operator: BettingOperator) => void` | No       | Click handler (suppresses default navigation) |
+
+### `BettingOddsStyles`
+
+| Property        | Type                             | Default     | Description                         |
+| --------------- | -------------------------------- | ----------- | ----------------------------------- |
+| `padding`       | `"none" \| "sm" \| "md" \| "lg"` | `"md"`      | Padding size                        |
+| `typography`    | `"sm" \| "md" \| "lg"`           | `"md"`      | Typography size                     |
+| `mode`          | `"default" \| "flash"`           | `"default"` | Display mode                        |
+| `flashInterval` | `number`                         | `3000`      | Flash mode interval in milliseconds |
+
+## Advanced Examples
+
+### Flash Mode
+
+Flash mode alternates between showing the operator logo and the odds at a configurable interval:
+
+```tsx
+<BettingOdds
+    odds={[
+        { label: "1", value: 2.8 },
+        { label: "X", value: 3.1 },
+        { label: "2", value: 2.5 },
+    ]}
+    operator={{
+        name: "Bet365",
+        logo: { url: "https://example.com/bet365-logo.png", alt: "Bet365" },
+        url: "https://www.bet365.com",
+        backgroundColor: "#037b5b",
+    }}
+    styles={{
+        mode: "flash",
+        flashInterval: 3000, // Switch every 3 seconds
+    }}
+/>
+```
+
+### Multiple Odds (Grid Layout)
+
+When displaying 4 or more odds, the component automatically uses a grid layout with 3 odds per row:
+
+```tsx
+<BettingOdds
+    odds={[
+        { label: "1-0", value: 8.5, change: "up" },
+        { label: "2-0", value: 12.0 },
+        { label: "2-1", value: 9.0, change: "down" },
+        { label: "0-0", value: 11.0 },
+        { label: "1-1", value: 6.5, change: "up" },
+    ]}
+    operator={{
+        name: "Bet365",
+        url: "https://www.bet365.com",
+    }}
+    label="Correct Score"
+/>
+```
+
+### Custom Styling
+
+```tsx
+<BettingOdds
+    odds={[
+        { label: "Over 2.5", value: 1.85 },
+        { label: "Under 2.5", value: 2.05 },
+    ]}
+    operator={{
+        name: "Betfair",
+        url: "https://www.betfair.com",
+    }}
+    styles={{
+        padding: "lg",
+        typography: "lg",
+    }}
+/>
+```
+
+### Custom Click Handlers
+
+You can provide custom click handlers to intercept clicks on odds or the operator logo. When provided, these handlers suppress the default navigation behavior:
+
+```tsx
+<BettingOdds
+    odds={[
+        {
+            label: "1",
+            value: 2.8,
+            url: "https://www.bet365.com/home-win",
+            onClick: (odd) => {
+                // Custom tracking or navigation logic
+                console.log("Clicked odd:", odd.label, odd.value);
+                // Navigate programmatically or trigger analytics
+                trackBetClick(odd);
+            },
+        },
+        {
+            label: "X",
+            value: 3.1,
+            url: "https://www.bet365.com/draw",
+            onClick: (odd) => {
+                trackBetClick(odd);
+            },
+        },
+        {
+            label: "2",
+            value: 2.5,
+            url: "https://www.bet365.com/away-win",
+            onClick: (odd) => {
+                trackBetClick(odd);
+            },
+        },
+    ]}
+    operator={{
+        name: "Bet365",
+        url: "https://www.bet365.com",
+        onClick: (operator) => {
+            // Custom operator click handling
+            console.log("Clicked operator:", operator.name);
+            trackOperatorClick(operator);
+        },
+    }}
+/>
+```
+
+This is useful for:
+
+- Analytics tracking before navigation
+- Custom navigation logic (e.g., opening modals, in-app browsers)
+- Integration with state management
+- Platform-specific deep linking
+
+## Styling
+
+The component uses Tailwind CSS utility classes and respects your application's theme configuration. Key design tokens used:
+
+- `bg-muted` / `bg-muted/50` - Background colors
+- `text-foreground` / `text-muted-foreground` - Text colors
+- `text-green-500` / `text-red-500` - Change indicators
+- Custom colors via `backgroundColor` and `textColor` props
+
+## Accessibility
+
+- All clickable odds and operator logos are properly linked with `<a>` tags
+- External links include `target="_blank"` and `rel="noopener noreferrer"`
+- Click events include `stopPropagation()` to prevent unwanted bubbling
+- Operator logos include proper `alt` text
+
+## Examples
+
+For complete working examples, see `src/examples/BettingOddsExamples.tsx` in the repository.