# @pepperi-addons/ngx-lib-react

Thin React wrappers around Pepperi Angular Elements (Web Components) for better DX in React apps.

## Quickstart: test in another addon (0.0.1)

- **Install**

```bash
npm i @pepperi-addons/ngx-lib-react
```

- **Load Elements (embedded in this package)**

```ts
// e.g., in src/index.tsx or src/main.tsx
import '@pepperi-addons/ngx-lib-react/elements/runtime.js';
import '@pepperi-addons/ngx-lib-react/elements/polyfills.js';
import '@pepperi-addons/ngx-lib-react/elements/main.js';
import '@pepperi-addons/ngx-lib-react/elements/styles.css';
```

- **Theme wrapper**

```tsx
export function App() {
    return <div className="pepperi-theme">{/* ... */}</div>;
}
```

- **Use components**

```tsx
import { PepButton, PepTextbox, PepSelect, PepListChooser, PepDraggableItems } from '@pepperi-addons/ngx-lib-react';

export function Example() {
    return (
        <div className="pepperi-theme">
            <PepButton value="Save" styleType="strong" />
            <PepTextbox label="Amount" type="currency" accessory="$" />
            <PepSelect label="Status" options={[{ key: 'open', value: 'Open' }]} />

            <PepListChooser
                options={[
                    { key: 'all', text: 'All Lists' },
                    { key: 'favorites', text: 'Favorites' },
                    { key: 'archived', text: 'Archived' },
                ]}
                currentList={{ key: 'all', text: 'All Lists' }}
                sizeType="md"
                onChange={(e) => console.log('List changed', e.source)}
            />

            <PepDraggableItems
                title="Drag me"
                items={[{ title: 'Item 1', data: { key: '1' } }, { title: 'Item 2', data: { key: '2' } }]}
                onItemDragStarted={(e) => console.log('Drag started', e)}
                onItemDragEnded={(e) => console.log('Drag ended', e)}
            />
        </div>
    );
}
```

This package expects you to load the Elements bundle and theme CSS (from `@pepperi-addons/ngx-lib-elements`) in your app.

## Install

```bash
npm i @pepperi-addons/ngx-lib-react @pepperi-addons/ngx-lib-elements
```

## Setup in React

Load the elements scripts and CSS once in your app (e.g., in `src/index.tsx`):

```ts
import '@pepperi-addons/ngx-lib-elements/runtime.js';
import '@pepperi-addons/ngx-lib-elements/polyfills.js';
import '@pepperi-addons/ngx-lib-elements/main.js';
import '@pepperi-addons/ngx-lib-elements/styles.css';
```

Wrap your app with the Pepperi theme class:

```tsx
export function App() {
    return <div className="pepperi-theme">{/* ... */}</div>;
}
```

## Consume in another (React) project

- **Install**

```bash
npm i @pepperi-addons/ngx-lib-react
```

- **Load Pepperi Elements (required at runtime)**
  - **Option A: via this package (embedded Elements, recommended)**

```ts
// e.g., in src/index.tsx or src/main.tsx
import '@pepperi-addons/ngx-lib-react/elements/runtime.js';
import '@pepperi-addons/ngx-lib-react/elements/polyfills.js';
import '@pepperi-addons/ngx-lib-react/elements/main.js';
import '@pepperi-addons/ngx-lib-react/elements/styles.css';
```

  - **Option B: host the compiled files and include tags**

```html
<!-- Place files from dist/ngx-lib-elements on your public path/CDN -->
<link rel="stylesheet" href="/pep-elements/styles.css" />
<script src="/pep-elements/runtime.js" defer></script>
<script src="/pep-elements/polyfills.js" defer></script>
<script src="/pep-elements/main.js" defer></script>
```

- **Theme**: Ensure a parent element has the `pepperi-theme` class (see example above).

## Usage

```tsx
import { PepButton, PepSelect, PepTextbox } from '@pepperi-addons/ngx-lib-react';

export function Example() {
    return (
        <div className="pepperi-theme">
            <PepButton value="Save" styleType="strong" onButtonClick={(e) => console.log(e)} />

            <PepTextbox label="Amount" type="currency" accessory="$" minFractionDigits={2} maxFractionDigits={2}
                        onValueChange={(v) => console.log('Amount', v)} />

            <PepSelect label="Status" onValueChange={(v) => console.log('Status', v)} />
        </div>
    );
}
```

Notes:
- For arrays/objects, the wrappers set element properties (not attributes) under the hood.
- Events are bridged from the custom element `CustomEvent` to React callbacks.
- `className` is forwarded to the custom element host (`class` attribute) so styling works as expected.
- Ensure `.pepperi-theme` is applied at app level so Angular Material overlays are themed.

## ⚠️ Angular Services NOT Exported Directly

Angular service **classes** (e.g. `PepHttpService`, `PepSessionService`,
`PepCustomizationService`) are not exported from this package, to avoid pulling
Angular and its DI runtime into your React bundle.

Instead you should use:

- **HTTP helper functions** (no Angular runtime).
- **Bridge-based helpers** that call selected Angular services (HTTP, Session,
  Customization, Translate) via the Elements bundle at runtime (see
  `SERVICES.md` for full details).
- **Custom element components** (PepDialog, PepSnackBar, etc.) for UI.
- Standard JavaScript libraries (uuid, validator, js-cookie, etc.) for
  general utilities.

See [SERVICES.md](./SERVICES.md) for complete documentation on available
service helpers (HTTP/session/customization) and usage examples.

For a concise, repo-level summary of all exported helpers and build artifacts,
see [`docs/services-export-summary.md`](../../docs/services-export-summary.md).