npm package: @legionhandtech/lht-react-widgets
Description: Legion Opportunities Widget - React component and web component for embedding opportunities
Latest version: 0.1.1

# @legionhandtech/lht-react-widgets

Embeddable Legion widgets for React applications. Each widget renders in an isolated iframe — no style conflicts, no CORS issues, no extra dependencies.

## Install

```bash
npm install @legionhandtech/lht-react-widgets
```

React 17+ is a peer dependency (only needed for the React components — web component imports work without React).

## Quick Start

```tsx
import { LegionOpportunities } from '@legionhandtech/lht-react-widgets';

function App() {
  return (
    <LegionOpportunities
      baseUrl="https://your-legion-domain.com"
      count={5}
      layout="horizontal"
      theme="light"
    />
  );
}
```

## Widgets

### LegionOpportunities

Displays opportunity cards in a horizontal or vertical layout.

```tsx
import { LegionOpportunities } from '@legionhandtech/lht-react-widgets';

<LegionOpportunities
  baseUrl="https://your-legion-domain.com"
  count={5}
  layout="horizontal"
  theme="dark"
  tags="featured,new"
  height="400px"
  apiKey="your-api-key"
  onLoad={(detail) => console.log('Loaded', detail)}
  onError={(msg) => console.error(msg)}
/>
```

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `baseUrl` | `string` | **required** | Base URL of your Legion instance |
| `count` | `number` | `5` | Number of opportunities (1–20) |
| `layout` | `"horizontal" \| "vertical"` | `"horizontal"` | Card layout direction |
| `tags` | `string` | — | Comma-separated tag filter |
| `theme` | `"light" \| "dark" \| "minimal" \| "bold" \| "corporate" \| "vibrant"` | `"light"` | Preset theme |
| `height` | `string` | `"auto"` | Widget height CSS value |
| `apiKey` | `string` | — | API key for authentication |

---

### LegionCommunityGallery

A media gallery showcasing community content.

```tsx
import { LegionCommunityGallery } from '@legionhandtech/lht-react-widgets';

<LegionCommunityGallery
  baseUrl="https://your-legion-domain.com"
  count={4}
  theme="light"
  communityUrl="/community"
/>
```

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `baseUrl` | `string` | **required** | Base URL of your Legion instance |
| `count` | `number` | `4` | Number of gallery items (1–12) |
| `theme` | `"light" \| "dark"` | `"light"` | Preset theme |
| `showViewAll` | `boolean` | `true` | Show "View all" link |
| `viewAllUrl` | `string` | `"/gallery"` | URL for the "View all" link |
| `communityUrl` | `string` | — | URL when clicking a media item |
| `height` | `string` | `"auto"` | Widget height CSS value |

---

### LegionQA

An interactive Q&A / knowledge-base widget.

```tsx
import { LegionQA } from '@legionhandtech/lht-react-widgets';

<LegionQA
  baseUrl="https://your-legion-domain.com"
  authToken="jwt-token"
  productId="prod-123"
  theme="light"
/>
```

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `baseUrl` | `string` | **required** | Base URL of your Legion instance |
| `authToken` | `string` | — | JWT token for authenticated features |
| `productId` | `string` | — | Scope questions to a product |
| `username` | `string` | `"Anonymous"` | Display name |
| `pageSize` | `number` | `5` | Items per page |
| `theme` | `"light" \| "dark"` | `"light"` | Preset theme |
| `showSearch` | `boolean` | `true` | Show search bar |
| `showAskButton` | `boolean` | `true` | Show "Ask a Question" button |
| `width` | `string` | `"600px"` | Widget width CSS value |
| `height` | `string` | `"800px"` | Widget height CSS value |

---

### LegionSocial

A social feed widget with grid and feed layouts.

```tsx
import { LegionSocial } from '@legionhandtech/lht-react-widgets';

<LegionSocial
  baseUrl="https://your-legion-domain.com"
  layout="feed"
  theme="dark"
  channel="general"
/>
```

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `baseUrl` | `string` | **required** | Base URL of your Legion instance |
| `layout` | `"feed" \| "grid" \| "compact"` | `"feed"` | Layout style |
| `theme` | `"light" \| "dark"` | `"light"` | Preset theme |
| `rows` | `number` | `3` | Number of rows (grid layout) |
| `cols` | `number` | `3` | Number of columns (grid layout) |
| `communityUrl` | `string` | — | Link to full community page |
| `channel` | `string` | — | Filter to a specific channel |
| `authToken` | `string` | — | JWT token |
| `userId` | `string` | — | Current user ID |
| `username` | `string` | — | Current user display name |
| `height` | `string` | `"800"` | Widget height CSS value |

---

### LegionWallet

Displays a user's wallet balance and transaction history.

```tsx
import { LegionWallet } from '@legionhandtech/lht-react-widgets';

<LegionWallet
  baseUrl="https://your-legion-domain.com"
  userId="user-123"
  apiKey="your-api-key"
  theme="light"
/>
```

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `baseUrl` | `string` | **required** | Base URL of your Legion instance |
| `userId` | `string` | — | User ID to display wallet for |
| `apiKey` | `string` | — | API key for authentication |
| `theme` | `"light" \| "dark"` | `"light"` | Preset theme |
| `showBalance` | `boolean` | — | Show the balance section |
| `showHistory` | `boolean` | — | Show the transaction history |
| `height` | `string` | `"500px"` | Widget height CSS value |

---

### LegionMatrix

A matrix / leaderboard display widget.

```tsx
import { LegionMatrix } from '@legionhandtech/lht-react-widgets';

<LegionMatrix
  baseUrl="https://your-legion-domain.com"
  theme="dark"
  emptyTitle="No data yet"
  height="600px"
/>
```

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `baseUrl` | `string` | **required** | Base URL of your Legion instance |
| `theme` | `"light" \| "dark"` | `"light"` | Preset theme |
| `emptyTitle` | `string` | — | Title shown when no data |
| `emptyIcon` | `string` | — | Icon shown when no data |
| `height` | `string` | `"600px"` | Widget height CSS value |

---

## Common Props

Every widget also accepts:

| Prop | Type | Description |
|------|------|-------------|
| `className` | `string` | CSS class on the wrapper `<div>` |
| `style` | `React.CSSProperties` | Inline styles on the wrapper `<div>` |
| `onLoad` | `(detail) => void` | Fires when the widget iframe loads |
| `onError` | `(message: string) => void` | Fires when the widget iframe fails to load |

## Theming

Each widget supports fine-grained CSS-variable theming via additional props. Pass them alongside the core props:

```tsx
<LegionOpportunities
  baseUrl="https://your-legion-domain.com"
  oppTitleColor="#1a1b1e"
  oppButtonBg="#228be6"
  oppCardRadius="16px"
  oppTransitionDuration="0.2s"
/>
```

Theming props are prefixed by widget name (`opp*`, `gallery*`, `qa*`, `social*`, `wallet*`, `matrix*`). Full lists are available in each widget's TypeScript types:

```ts
import type {
  OpportunitiesThemingProps,
  CommunityGalleryThemingProps,
  QAThemingProps,
  SocialThemingProps,
  WalletThemingProps,
  MatrixThemingProps,
} from '@legionhandtech/lht-react-widgets';
```

## Imperative Ref

All widgets expose a `refresh()` method via React ref:

```tsx
import { useRef } from 'react';
import { LegionOpportunities } from '@legionhandtech/lht-react-widgets';
import type { LegionOpportunitiesHandle } from '@legionhandtech/lht-react-widgets';

function App() {
  const ref = useRef<LegionOpportunitiesHandle>(null);

  return (
    <>
      <button onClick={() => ref.current?.refresh()}>Reload</button>
      <LegionOpportunities ref={ref} baseUrl="https://your-legion-domain.com" />
    </>
  );
}
```

Handle types: `LegionOpportunitiesHandle`, `LegionCommunityGalleryHandle`, `LegionQAHandle`, `LegionSocialHandle`, `LegionWalletHandle`, `LegionMatrixHandle`.

## Web Components (from NPM)

If you prefer custom elements over React components, import the web component entry:

```ts
// Register <legion-opportunities> custom element
import '@legionhandtech/lht-react-widgets/web-component';
```

Then use it in HTML or JSX:

```html
<legion-opportunities
  base-url="https://your-legion-domain.com"
  count="5"
  layout="horizontal"
  theme="light">
</legion-opportunities>
```

Available web component imports:

| Import Path | Custom Element |
|-------------|---------------|
| `/web-component` | `<legion-opportunities>` |
| `/community-gallery-web-component` | `<legion-community-gallery>` |
| `/qa-web-component` | `<legion-qa>` |
| `/social-web-component` | `<legion-social>` |
| `/wallet-web-component` | `<legion-wallet>` |
| `/matrix-web-component` | `<legion-matrix>` |

> Web component imports do **not** require React.

## Sub-path Imports

For smaller bundles, import only the widget you need:

```ts
import { LegionOpportunities } from '@legionhandtech/lht-react-widgets/opportunities';
import { LegionCommunityGallery } from '@legionhandtech/lht-react-widgets/community-gallery';
import { LegionQA } from '@legionhandtech/lht-react-widgets/qa';
import { LegionSocial } from '@legionhandtech/lht-react-widgets/social';
import { LegionWallet } from '@legionhandtech/lht-react-widgets/wallet';
import { LegionMatrix } from '@legionhandtech/lht-react-widgets/matrix';
```

## TypeScript

The package ships with full TypeScript declarations (`.d.ts` and `.d.mts`). All prop interfaces, theming types, and ref handle types are exported.

## License

MIT