use-telegram/readme.md

A TypeScript package for easy integration with Telegram WebApp API

# use-telegram

A TypeScript package for easy integration with Telegram WebApp API. Provides React hooks and context for managing Telegram WebApp's MainButton with full TypeScript support.

## Features

- 🚀 **React Hooks**: Easy-to-use hooks for Telegram WebApp integration
- 📝 **TypeScript**: Full TypeScript support with proper type definitions
- 🎯 **Flexible**: Support for both persistent and one-time action buttons
- 🔄 **Auto-updates**: Button text and options update automatically on state changes
- 🎯 **Flexible**: Support for both persistent and one-time action buttons

## Installation

```bash
npm install use-telegram
```

## Quick Start

### 1. Wrap your app with the provider

```tsx
import { TelegramWebContextProvider } from 'use-telegram';

function App() {
  return (
    <TelegramWebContextProvider>
      <YourApp />
    </TelegramWebContextProvider>
  );
}
```

### 2. Use the hooks in your components

```tsx
import { useMainButton, useActionButton } from 'use-telegram';

function MyComponent() {
  const [count, setCount] = useState(0);

  // Persistent button that stays visible
  const counterBtn = useMainButton(
    { text: `Counter ${count}`, hasShineEffect: true }, 
    (btn) => {
      setCount(prev => {
        const newCount = prev + 1;
        btn.setText(`Counter ${newCount}`);
        return newCount;
      });
    }
  );

  // One-time button that hides after click
  const oneTimeBtn = useActionButton(
    { text: 'One time button', hasShineEffect: true }, 
    () => {
      alert('One time button clicked');
    }
  );

  return (
    <div>
      <button onClick={counterBtn.showButton}>Show Counter Button</button>
      <button onClick={oneTimeBtn.showButton}>Show One-time Button</button>
      <button onClick={counterBtn.hideButton}>Hide Button</button>
    </div>
  );
}
```

## API Reference

### Hooks

#### `useMainButton(options, onClick?)`

Creates a persistent main button that stays visible until manually hidden.

**Parameters:**
- `options` (Partial<MainButton>): Button configuration
- `onClick?` (btn: MainButton) => void: Click handler with button instance

**Returns:**
- `showButton()`: Function to show the button
- `hideButton()`: Function to hide the button

#### `useActionButton(options, onClick?)`

Creates a one-time action button that automatically hides after being clicked.

**Parameters:**
- `options` (Partial<MainButton>): Button configuration
- `onClick?` (btn: MainButton) => void: Click handler with button instance

**Returns:**
- `showButton()`: Function to show the button
- `hideButton()`: Function to hide the button

### Button Options

```typescript
interface MainButton {
  text: string;           // Button text
  color?: string;         // Button color (hex format)
  hasShineEffect?: boolean; // Enable shine effect
}
```

### Context Provider

#### `TelegramWebContextProvider`

Wraps your app to provide Telegram WebApp functionality.

**Props:**
- `children`: React components
- `theme?`: Optional theme parameters

```tsx
<TelegramWebContextProvider theme={{ bg_color: '#ffffff' }}>
  {children}
</TelegramWebContextProvider>
```

## Examples

### Counter with Auto-updating Text

```tsx
import { useState } from 'react';
import { useMainButton } from 'use-telegram';

function Counter() {
  const [count, setCount] = useState(0);

  const btn = useMainButton(
    { text: `Count: ${count}`, hasShineEffect: true },
    (btn) => {
      setCount(prev => {
        const newCount = prev + 1;
        btn.setText(`Count: ${newCount}`);
        return newCount;
      });
    }
  );

  return (
    <div>
      <p>Current count: {count}</p>
      <button onClick={btn.showButton}>Show Counter Button</button>
      <button onClick={btn.hideButton}>Hide Button</button>
    </div>
  );
}
```

### Form Submission

```tsx
import { useActionButton } from 'use-telegram';

function Form() {
  const [formData, setFormData] = useState('');

  const submitBtn = useActionButton(
    { text: 'Submit Form', color: '#007AFF' },
    () => {
      // Form will be submitted and button will auto-hide
      console.log('Form submitted:', formData);
    }
  );

  return (
    <div>
      <input 
        value={formData} 
        onChange={(e) => setFormData(e.target.value)}
        placeholder="Enter data"
      />
      <button onClick={submitBtn.showButton}>Show Submit Button</button>
    </div>
  );
}
```

### Custom Theme

```tsx
import { TelegramWebContextProvider } from 'use-telegram';

function App() {
  const theme = {
    bg_color: '#ffffff',
    text_color: '#000000',
    hint_color: '#999999',
    link_color: '#007AFF',
    button_color: '#007AFF',
    button_text_color: '#ffffff'
  };

  return (
    <TelegramWebContextProvider theme={theme}>
      <YourApp />
    </TelegramWebContextProvider>
  );
}
```

## Requirements

- React 18+
- Node.js 16+
- Telegram WebApp environment

## Browser Support

This package is designed to work within Telegram's WebApp environment. Make sure your app is running inside Telegram's WebApp container.

## Development

```bash
# Install dependencies
npm install

# Build the package
npm run build

# Watch for changes
npm run dev

# Lint code
npm run lint

# Format code
npm run format
```

## Contributing

1. Fork the repository
2. Create your feature branch (`git checkout -b feature/amazing-feature`)
3. Commit your changes (`git commit -m 'Add some amazing feature'`)
4. Push to the branch (`git push origin feature/amazing-feature`)
5. Open a Pull Request

## License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

## Support

If you encounter any issues or have questions, please [open an issue](https://github.com/muzmich/use-telegram/issues) on GitHub.

## Changelog

### 1.0.0
- Initial release
- Support for MainButton and ActionButton hooks
- Theme customization
- Full TypeScript support