npm package: @lelbakna/tarl
Description: A React component library for language learning interfaces
Latest version: 0.1.34

# TARL - Language Learning Component Library

A comprehensive React component library for building language learning interfaces with Redux Toolkit Query integration.

## Features

- 🎨 Built with Tailwind CSS for styling
- ⚛️ React components with TypeScript
- 🔄 Redux Toolkit Query integration
- 🎭 Framer Motion animations
- 📦 Ready for NPM publishing
- 🚀 Framework agnostic (works with React, Next.js, etc.)
- 📝 Full TypeScript support

## Installation

```bash
npm install tarl
```

### Peer Dependencies

Make sure to install the required peer dependencies:

```bash
npm install react react-dom @reduxjs/toolkit react-redux framer-motion
```

## Quick Start

### 1. Set up Redux Store

```tsx
import { Provider } from 'react-redux';
import { createTarlStore } from 'tarl';

const store = createTarlStore();

function App() {
  return (
    <Provider store={store}>
      {/* Your app */}
    </Provider>
  );
}
```

### 2. Import Styles

```tsx
import 'tarl/styles'; // or 'tarl/dist/styles.css'
```

### 3. Use Components

```tsx
import { LanguageLearningInterface } from 'tarl';

function MyApp() {
  return (
    <LanguageLearningInterface
      activityId={3}
      source="interactive"
      userName="John Doe"
      sessionNumber={3}
    />
  );
}
```

## Core Components

### LanguageLearningInterface

The main component for displaying language learning activities.

```tsx
import { LanguageLearningInterface } from 'tarl';

<LanguageLearningInterface
  activityId={3}                    // Activity ID from API
  source="interactive"              // 'interactive' or 'slides'
  userName="John Doe"              // User name
  sessionNumber={3}                // Session number
  onBack={() => console.log('back')}
  onContinue={() => console.log('continue')}
  onReplay={() => console.log('replay')}
/>
```

### SplashScreen

Display a splash screen before starting the activity.

```tsx
import { SplashScreen } from 'tarl';

<SplashScreen
  activityId={3}
  onStart={() => setShowSplash(false)}
/>
```

### Header

Header component with session info and progress.

```tsx
import { Header } from 'tarl';

<Header
  sessionNumber={3}
  sessionType="Ecriture"
  currentStep={1}
  etapes={etapes}
  userName="John Doe"
  mode="interactive"
  onBack={() => {}}
/>
```

## API Integration

### Using RTK Query Hooks

```tsx
import { useGetActivityPropositionsQuery } from 'tarl';

function MyComponent() {
  const { data, isLoading, error } = useGetActivityPropositionsQuery({
    activityId: 3,
    source: 'interactive'
  });

  if (isLoading) return <div>Loading...</div>;
  if (error) return <div>Error: {error.toString()}</div>;

  return <div>{/* Use data */}</div>;
}
```

### Using Component Wrapper

```tsx
import { LanguageLearningInterfaceWithQuery } from 'tarl';

<LanguageLearningInterfaceWithQuery
  activityId={3}
  sessionNumber={3}
  userName="John Doe"
/>
```

## Environment Variables

Set up your API endpoints:

```env
NEXT_PUBLIC_API_BASE_URL=http://localhost:8003
NEXT_PUBLIC_PRONUNCIATION_API_BASE_URL=http://localhost:8002
```

## Complete Example

```tsx
import { Provider } from 'react-redux';
import { createTarlStore, LanguageLearningInterface } from 'tarl';
import 'tarl/styles';

const store = createTarlStore();

function App() {
  return (
    <Provider store={store}>
      <LanguageLearningInterface
        activityId={3}
        source="interactive"
        userName="John Doe"
        sessionNumber={3}
        onBack={() => console.log('Back clicked')}
        onContinue={() => console.log('Continue clicked')}
        onReplay={() => console.log('Replay clicked')}
      />
    </Provider>
  );
}
```

## Available Components

- `LanguageLearningInterface` - Main learning interface
- `SplashScreen` - Splash screen component
- `Header` - Header with session info
- `Button` - Custom button component
- `Card` - Card container
- `LetterBlock` - Letter block display
- `LetterInputs` - Letter input component
- `ActionButtons` - Action buttons
- `MicrophoneButton` - Microphone button
- `SpeakerButton` - Speaker button
- `VoiceRecorder` - Voice recorder
- `WordIllustration` - Word illustration
- `BookCharacter` - Book character animation
- `ProgressTag` - Progress tag
- `TimerBar` - Timer bar
- And more...

## Available Hooks

- `useWordLearningData` - Get word learning data
- `useAudioPlayback` - Audio playback hook
- `useTimer` - Timer hook
- `useLetterInput` - Letter input hook
- `useCelebration` - Celebration animations
- `useLocalStoragePersistence` - Local storage persistence

## Building the Library

To build the library for distribution:

```bash
npm run build:lib
```

This creates the `dist/` folder with:
- `index.js` - CommonJS build
- `index.esm.js` - ES Module build
- `index.d.ts` - TypeScript declarations
- `styles.css` - Compiled Tailwind CSS

## Development

To run the development server:

```bash
npm run dev
```

## Publishing

1. Update `package.json` version
2. Build: `npm run build:lib`
3. Publish: `npm publish` (or `npm publish --access public` for scoped packages)

## Project Structure

```
TARL/
├── src/
│   ├── components/      # React components
│   ├── hooks/          # Custom hooks
│   ├── api/            # RTK Query API
│   ├── store/          # Redux store
│   ├── styles/         # Tailwind CSS styles
│   ├── types/           # TypeScript types
│   └── index.ts         # Main export file
├── app/                 # Next.js app (for development)
├── dist/                # Built library (generated)
└── package.json
```

## Image Assets

The library uses images from `/images/` path. Make sure to:
1. Copy the `public/images/` folder to your consuming project's public directory
2. Or configure your build tool to handle image paths correctly

## License

MIT