# @spteck/react-controls-v2

**v2.6.3** — A comprehensive, framework-agnostic React component library built on **Fluent UI 9**, designed for enterprise applications. Works seamlessly with **Vite**, **Next.js**, **Create React App**, and **SharePoint Framework (SPFx)**.

> 🔗 **Live Showcase & Docs:** [reactcontrols.spteckapps.com](https://reactcontrols.spteckapps.com)

---

## Features

- **Framework Agnostic** — Works with any React 17+ or 18+ project
- **Fluent UI 9 Based** — Modern Microsoft design system with full theming support
- **Full TypeScript Support** — Strongly typed props and interfaces
- **SPFx Ready** — Supports SharePoint Framework without SPFx-specific dependencies in the core
- **Microsoft Graph Integration** — Built-in hooks and providers for Microsoft Graph API
- **Responsive Design** — Breakpoint-based spacing and layout utilities
- **Tree-Shakeable** — Import only what you need
- **Accessible** — WCAG-compliant via Fluent UI
- **Adaptive Cards** — Full Adaptive Cards rendering with Fluent UI styling
- **AI Components** — Chat assistant and AI-powered search out of the box
- **Rich Text Editing** — TipTap-based editor with full formatting toolbar
- **Export Utilities** — One-hook Excel / CSV / JSON export with async paginated fetchers

---

## Showcase & Documentation

> **Live demos, code samples, and usage details for every component are available at:**
>
> **[https://reactcontrols.spteckapps.com](https://reactcontrols.spteckapps.com)**

Visit the showcase site to explore interactive previews, copy ready-to-use code snippets, and see all available props for each control.

---

## Installation

```bash
npm install @spteck/react-controls-v2
```

### Peer Dependencies

```bash
npm install react react-dom
```

For SPFx applications:

```bash
npm install @spteck/react-controls-v2 @spteck/react-controls-v2-spfx-adapter
```

---

## Recommended App Root

Use `FluentUIProvider` at the top of your app to apply the Fluent UI theme, scope generated IDs, and ensure dialogs, menus, and other portals inherit the same styles.

```tsx
import * as React from 'react';
import { webDarkTheme, webLightTheme } from '@fluentui/react-components';
import { FluentUIProvider } from '@spteck/react-controls-v2';

export function App() {
  const [isDark, setIsDark] = React.useState(false);
  const theme = isDark ? webDarkTheme : webLightTheme;

  return (
    <FluentUIProvider
      theme={theme}
      applicationName="contoso-app"
      applyStylesToPortals={true}
      targetDocument={document}
    >
      <YourRoutes />
    </FluentUIProvider>
  );
}
```

If you are also using app context and localization, the recommended provider order is:

```tsx
<FluentUIProvider theme={theme} applicationName="contoso-app">
  <UniversalProvider context={appContext}>
    <LocalizationProvider locale={locale}>
      <App />
    </LocalizationProvider>
  </UniversalProvider>
</FluentUIProvider>
```

---

## Available Controls

### Layout & Structure

| Component | Description |
|-----------|-------------|
| `StackV2` | Extended flexbox stack with responsive spacing, alignment, and wrapping |
| `Grid` | CSS Grid layout with responsive columns and auto-flow |
| `Layout` | Named grid-area template layout (e.g., Holy Grail) |
| `Card` | Fluent UI Card with header, body, footer, and preview slots |
| `Space` | Inline spacing / visual gap utility |
| `AspectRatio` | Constrain content to a fixed aspect ratio |
| `Center` | Center content horizontally and/or vertically |
| `Container` | Responsive max-width container |
| `Carousel` | Horizontally scrollable item carousel |
| `SplitPane` | Resizable two-pane split layout |
| `Popup` | Floating popover / popup panel |

### Hero

| Component | Description |
|-----------|-------------|
| `Hero` | Full-bleed media hero with 7 layouts: fullscreen, split, featured, mosaic, grid, filmstrip, and carousel. Supports image and video items with optional overlays. |

### Forms & Input

| Component | Description |
|-----------|-------------|
| `InputField` | Text input with validation and labels |
| `DropdownField` | Drop-down select with validation, custom rendering, default value, and message support |
| `SearchControl` | Search box with filtering |
| `CalendarControl` | Full calendar with month, week, and day views |
| `CompactCalendar` | Compact inline date picker |
| `SelectTime` | Time picker with configurable intervals |
| `SelectView` | View mode switcher (list, grid, compact) |
| `IconButton` | Icon-only button with tooltip |
| `ItemPicker` | Tag-based item picker with suggestions and paging |
| `Spotlight` | Command palette overlay with search, keyboard navigation, grouped actions, and configurable shortcuts |
| `Dropzone` | Drag-and-drop file upload with MIME-type filtering, size limits, and preview |
| `RichTextEditor` | TipTap-based editor with formatting toolbar, links, colours, image upload, and more |
| `OTPField` | One-time password / PIN input field |
| `Mentions` | @mention input with suggestions |

### Pickers

| Component | Description |
|-----------|-------------|
| `ColorPicker` | Sketch, Chrome, Colorful, Wheel, Circle, Compact, Block, Material, Github, and Slider pickers |
| `EmojiPicker` | Self-contained emoji picker popup with category tabs, search, and configurable dimensions |

### Data Display

| Component | Description |
|-----------|-------------|
| `DataGrid` | Sortable, selectable, resizable data table |
| `DataGridV2` | Virtualized high-performance data grid with infinite scroll, sorting, resizing, row selection, and imperative handle API |
| `KPICard` | Key performance indicator card (default and compact variants) |
| `KPICardCompact` | Compact KPI card for dense dashboards |
| `Skeleton` | Auto-extracting skeleton screens with pixel-perfect placeholders |

### Navigation

| Component | Description |
|-----------|-------------|
| `Navigation` | Side navigation drawer with sections and icons |
| `Breadcrumb` | Navigation breadcrumb with overflow support |
| `ButtonMenu` | Button with a dropdown list of options |
| `CustomControlBar` | Configurable toolbar for custom actions |
| `GenericOverFlowMenu` | Overflow-aware menu that collapses items automatically |
| `ListToolbar` | SharePoint-style list action toolbar |

### Dialogs & Overlays

| Component | Description |
|-----------|-------------|
| `RenderDialog` | Fluent UI modal dialog with title and actions |
| `RenderDrawer` | Side-panel drawer (start or end position) |
| `RenderHeader` | StackV2-based header with icon, title, description, and optional close button |
| `Popup` | Floating popover panel |
| `ShareDialog` | Share link / people picker dialog |

### Feedback & Status

| Component | Description |
|-----------|-------------|
| `ShowError` | Friendly error message display |
| `ShowMessage` | Info / success / warning status banner |
| `RenderSpinner` | Loading spinner |

### Typography & Content

| Component | Description |
|-----------|-------------|
| `TypographyControl` | Fluent-styled text with variant, size, weight, and colour support |
| `RenderLabel` | Field label with optional required indicator |
| `MarkdownRenderer` | Converts Markdown to styled HTML |
| `ContentRenderer` | Auto-detects and renders Markdown, HTML, Adaptive Cards, or plain text |
| `MermaidDiagram` | Renders Mermaid diagram syntax as SVG |
| `Blockquote` | Styled quotation block with icon badge and semantic colours |
| `Marquee` | Infinitely scrolling content strip with configurable direction, speed, pause-on-hover, and fade edges |
| `Spoiler` | Toggle visibility of long content with show/hide control and smooth collapse animation |
| `Timeline` | Vertical timeline with active state tracking, custom bullets, line variants, and configurable alignment |
| `Stepper` | Progress through a sequence of steps with active highlighting, custom icons, and completed-state content |
| `InlineSVG` | Load, sanitize, and render SVG from URLs, data URIs, and raw markup |
| `BackgroundImage` | Full-width background images with cover sizing and overlay support |

### News & Publishing

| Component | Description |
|-----------|-------------|
| `NewsCard` | Standard vertical news card — image on top, headline, category badge, body text, author/date meta row, and a stats row (views, likes, comments, optional share button). Supports `default` and `overlay` variants, over-due accent, per-card settings panel, and click/link navigation. |
| `NewsCardCompact` | Compact horizontal news card — thumbnail beside the text. Supports `default`, `flat`, and `overlay` variants plus all the same stats/share/settings props as `NewsCard`. |
| `NewsBigCard` | Large feature card with a wide side image column. Supports `default` and `overlay` variants, full visibility controls (`showBodyText`, `showAuthorDate`, `showStats`, `showComments`, `showShare`), and an optional settings panel. |
| `NewsFeed` | Feed container that renders a collection of `INewsFeedItem` objects in one of nine layout variants: `grid`, `list`, `filmstrip`, `marquee`, `carousel`, `mosaic`, `feature`, `masonry`, and `trending`. Supports drag-and-drop reordering, fixed-height scrolling, and feed-wide visibility toggles. |
| `NewsTrendingFeed` | Compact trending-news sidebar widget — numbered thumbnail list with headline, category, date, and an optional "view all" action. |
| `NewsStats` | Stats row sub-component used by the card components — displays views, likes, comments (with Fluent UI `Tooltip`s), and an optional circular share `Button`. |

#### `INewsItem` interface

```ts
interface INewsItem {
  headline:  string;          // required — main card headline
  category?: string;          // section label shown above the headline
  bodyText?: string;          // short description or body copy
  author?:   string;          // author display name
  date?:     string | Date;   // published date (ISO string, formatted string, or Date)
  imageUrl?: string;          // image URL
  views?:    number;          // view count shown in the stats row
  likes?:    number;          // like count shown in the stats row
  comments?: number;          // comment count (shown when showComments is true)
}
```

#### Common card props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `showBodyText` | `boolean` | `true` | Show / hide body text |
| `showAuthorDate` | `boolean` | `true` | Show / hide author and date |
| `showStats` | `boolean` | `true` | Show / hide the stats row (views, likes, comments) |
| `showComments` | `boolean` | `true` | Show comment count inside the stats row |
| `showShare` | `boolean` | `false` | Show a circular share icon-button in the stats row |
| `onShare` | `(item: INewsItem) => void` | — | Called when the share button is clicked |
| `showCardSettings` | `boolean` | `false` | Show a settings gear button for per-card display customisation |
| `isOverDue` | `boolean` | `false` | Apply an amber over-due colour accent to the card |
| `headlineLines` | `number` | `1` | Max lines before headline is clamped |
| `bodyLines` | `number` | `3` | Max lines before body text is clamped |
| `locale` | `string` | browser | BCP 47 locale for date formatting |
| `timeZone` | `string` | browser | IANA time-zone identifier for date formatting |

---

### Media & Content

| Component | Description |
|-----------|-------------|
| `VideoPlayer` | Multi-source video player (YouTube, Vimeo, MP4, etc.) |
| `AdaptiveCardHost` | Renders Adaptive Cards with Fluent UI styling |
| `WorldMap` | Interactive world map with MapLibre GL |

### People & Users

| Component | Description |
|-----------|-------------|
| `UserCard` | User persona with live presence status from Graph API |
| `LivePersona` | Persona wrapper with SPFx hover card support |
| `StackedUsers` | Overlapping avatar stack for groups of users |
| `ListItemActivityMessage` | SharePoint list item activity / audit trail |


### Hooks

| Hook | Description |
|------|-------------|
| `useApplicationContext()` | Access application context anywhere inside `UniversalProvider` |
| `useAppToast()` | Consolidated toast notifications — success, error, warning, info, action buttons, and programmatic dismiss |
| `useExportData()` | Export data to Excel, JSON, and CSV with optional header styling, async paginated fetchers, and a built-in progress dialog |
| `useFluentEmoji()` | Resolve reaction types to Fluent emoji image URLs with style and skin-tone support |
| `useIndexedDBCache()` | IndexedDB-backed caching with TTL support |
| `useLogging()` | Structured logging with info, warn, error, and verbose — pluggable transport via `UniversalProvider` |
| `usePolling(fn, interval)` | Repeatedly call a function at a fixed interval with manual start/stop control |
| `useTimeZoneHelper()` | DST-safe timezone conversions and locale-aware date/time formatting |
| `useBrandCenterFonts()` | Load and apply brand fonts from the Microsoft Brand Center |

### Core & Utilities

| Item | Description |
|------|-------------|
| `UniversalProvider` | Root context provider — supplies app context, logging, storage, and Graph client |
| `FluentUIProvider` | Fluent UI theme root with portal styling and scoped generated IDs |
| `LocalizationProvider` | Locale-aware date / number / string formatting provider |
| `BaseComponentProps` | Shared responsive spacing and sizing interface |
| `LocalStorageProvider` | `IStorageProvider` implementation using `localStorage` |

---

## Disclaimer

This project is provided **"as is"**, without warranty of any kind, express or implied. The author(s) make no representations or guarantees regarding the accuracy, reliability, completeness, or suitability of this software for any particular purpose.

By using this library you acknowledge and agree that:

- **No liability** — The author(s) shall not be held responsible or liable for any damages, losses, costs, or expenses arising from the use or inability to use this software, including but not limited to bugs, data loss, security vulnerabilities, service interruptions, or any other issue.
- **No warranty** — There is no guarantee that this software is free of defects, errors, or security vulnerabilities. It is your responsibility to evaluate and bear all risks associated with its use.
- **No obligation** — The author(s) are under no obligation to provide support, maintenance, updates, bug fixes, or enhancements. Any support provided is entirely at the author's discretion.
- **Use at your own risk** — This software is intended for educational and professional use. You are solely responsible for determining the appropriateness of using or redistributing it and assume all risks associated with your use.
- **Not affiliated** — This project is a personal/community initiative and is **not affiliated with, endorsed by, or supported by Microsoft Corporation** or any other organization.

The source code is **not publicly available**. This library is distributed as a compiled package under the MIT License. If you require access to the source code, please contact the author at [joao.j.mendes@spteck.com](mailto:joao.j.mendes@spteck.com).

## License

MIT © João Mendes
