npm package: @spteck/react-controls-v2
Description: Framework-agnostic React controls for Vite, Next.js, and SPFx - based on Fluent UI 9
Author: João Mendes
Latest version: 2.4.4

# @spteck/react-controls-v2

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)**.

---

## 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

---

## 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 |
|-----------|-------------|
| `Stack` | Flexbox horizontal/vertical layout with alignment and gap |
| `StackV2` | Extended 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 |
| `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 |
| `Popup` | Floating popover / popup panel |

### Forms & Input

| Component | Description |
|-----------|-------------|
| `SelectDate` | Date picker with calendar dropdown |
| `SelectTime` | Time picker with configurable intervals |
| `SelectView` | View mode switcher (list, grid, compact) |
| `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 |
| `IconButton` | Icon-only button with tooltip |
| `ItemPicker` | Tag-based item picker with suggestions |
| `CalendarControl` | Full calendar with month, week and day views |

### 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) |

### 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 |

### 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 |

### Feedback & Status

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

### Typography

| Component | Description |
|-----------|-------------|
| `TypographyControl` | Fluent-styled text with variant, size and color 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 |

### 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 |

### AI & Advanced

| Component | Description |
|-----------|-------------|
| `AIAssistant` | Full streaming AI chat assistant |
| `AISearchControl` | Natural language search powered by Azure OpenAI |

### Hooks

| Hook | Description |
|------|-------------|
| `useApplicationContext()` | Access application context anywhere inside `UniversalProvider` |
| `useGraphAPI()` | Make Microsoft Graph API calls with built-in error handling |
| `useLogging()` | Structured logging via the configured provider |
| `useIndexedDBCache()` | IndexedDB-based caching with TTL support |
| `usePolling(fn, interval)` | Repeatedly call a function at a fixed interval |
| `useTimeZoneHelper()` | Format and convert dates across time zones |

### Core & Utilities

| Component | Description |
|-----------|-------------|
| `UniversalProvider` | Root context provider for the whole app |
| `FluentUIProvider` | Fluent UI theme root with portal styling and scoped IDs |
| `BaseComponentProps` | Shared responsive spacing/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