@dismissible/react-client 0.0.1-canary.10

package/README.md

@@ -0,0 +1,435 @@
+# @dismissible/react-client
+
+A React component library for creating dismissible UI elements with persistent state management.
+
+[![npm version](https://badge.fury.io/js/@dismissible%2Freact-client.svg)](https://badge.fury.io/js/@dismissible%2Freact-client)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+## Features
+
+- 🎯 **Easy to use** - Simple component API for dismissible content
+- 💾 **Persistent state** - Dismissal state is saved and restored across sessions
+- 🎨 **Customizable** - Custom loading, error, and dismiss button components
+- ♿ **Accessible** - Built with accessibility best practices
+- 🪝 **Hook-based** - Includes `useDismissibleItem` hook for custom implementations
+- 📦 **Lightweight** - Minimal bundle size with tree-shaking support
+- 🔧 **TypeScript** - Full TypeScript support with complete type definitions
+
+## Installation
+
+```bash
+npm install @dismissible/react-client
+```
+
+### Peer Dependencies
+
+Make sure you have React 18+ installed:
+
+```bash
+npm install react react-dom
+```
+
+## Quick Start
+
+```tsx
+import React from 'react';
+import { Dismissible } from '@dismissible/react-client';
+
+function App() {
+  return (
+    <Dismissible id="welcome-banner-123-413-31-1">
+      <div className="banner">
+        <h2>Welcome to our app!</h2>
+        <p>This banner can be dismissed and won't show again.</p>
+      </div>
+    </Dismissible>
+  );
+}
+```
+
+## API Reference
+
+### `<Dismissible>` Component
+
+The main component for creating dismissible content.
+
+#### Props
+
+| Prop | Type | Required | Description |
+|------|------|----------|-------------|
+| `id` | `string` | ✅ | Unique identifier for the dismissible item |
+| `children` | `ReactNode` | ✅ | Content to render when not dismissed |
+| `onDismiss` | `() => void` | ❌ | Callback fired when item is dismissed |
+| `LoadingComponent` | `ComponentType<{id: string}>` | ❌ | Custom loading component |
+| `ErrorComponent` | `ComponentType<{id: string, error: Error}>` | ❌ | Custom error component |
+| `DismissButtonComponent` | `ComponentType<{id: string, onDismiss: () => Promise<void>, ariaLabel: string}>` | ❌ | Custom dismiss button |
+
+#### Example
+
+```tsx
+<Dismissible
+  id="promo-banner"
+  onDismiss={() => console.log('Banner dismissed')}
+  onRestore={() => console.log('Banner restored')}
+>
+  <div className="promo">
+    <h3>Special Offer!</h3>
+    <p>Get 50% off your first order</p>
+  </div>
+</Dismissible>
+```
+
+### `useDismissibleItem` Hook
+
+For custom implementations and advanced use cases.
+
+#### Parameters
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `id` | `string` | ✅ | Unique identifier for the dismissible item |
+
+#### Returns
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `dismissedOn` | `string \| null` | ISO date string when item was dismissed, or null |
+| `dismiss` | `() => Promise<void>` | Function to dismiss the item |
+| `isLoading` | `boolean` | Loading state indicator |
+| `error` | `Error \| null` | Error state, if any |
+
+#### Example
+
+```tsx
+import { useDismissibleItem } from '@dismissible/react-client';
+
+function CustomDismissible({ id, children }) {
+  const { dismissedOn, dismiss, isLoading, error } = useDismissibleItem(id);
+
+  if (dismissedOn) {
+    return null; // Item is dismissed
+  }
+
+  if (isLoading) {
+    return <div>Loading...</div>;
+  }
+
+  if (error) {
+    return <div>Error: {error.message}</div>;
+  }
+
+  return (
+    <div>
+      {children}
+      <button onClick={dismiss}>
+        Dismiss
+      </button>
+    </div>
+  );
+}
+```
+
+## Usage Examples
+
+### Basic Dismissible Banner
+
+```tsx
+import { Dismissible } from '@dismissible/react-client';
+
+function WelcomeBanner() {
+  return (
+    <Dismissible id="welcome-banner-234-432-432-1">
+      <div className="alert alert-info">
+        <h4>Welcome!</h4>
+        <p>Thanks for joining our platform. Here are some quick tips to get started.</p>
+      </div>
+    </Dismissible>
+  );
+}
+```
+
+### Custom Dismiss Button
+
+```tsx
+import { Dismissible } from '@dismissible/react-client';
+
+const CustomDismissButton = ({ onDismiss, ariaLabel }) => (
+  <button
+    onClick={onDismiss}
+    className="custom-close-btn"
+    aria-label={ariaLabel}
+  >
+    ✕
+  </button>
+);
+
+function CustomBanner() {
+  return (
+    <Dismissible
+      id="custom-banner"
+      DismissButtonComponent={CustomDismissButton}
+    >
+      <div className="banner">
+        <p>This banner has a custom dismiss button!</p>
+      </div>
+    </Dismissible>
+  );
+}
+```
+
+### Custom Loading and Error Components
+
+```tsx
+import { Dismissible } from '@dismissible/react-client';
+
+const CustomLoader = ({ id }) => (
+  <div className="spinner">
+    <div className="bounce1"></div>
+    <div className="bounce2"></div>
+    <div className="bounce3"></div>
+  </div>
+);
+
+const CustomError = ({ error }) => (
+  <div className="error-card">
+    <h4>Oops! Something went wrong</h4>
+    <p>{error.message}</p>
+    <button onClick={() => window.location.reload()}>
+      Try Again
+    </button>
+  </div>
+);
+
+function AdvancedBanner() {
+  return (
+    <Dismissible
+      id="advanced-banner"
+      LoadingComponent={CustomLoader}
+      ErrorComponent={CustomError}
+    >
+      <div className="banner">
+        <p>This banner has custom loading and error states!</p>
+      </div>
+    </Dismissible>
+  );
+}
+```
+
+### Multiple Dismissible Items
+
+```tsx
+import { Dismissible } from '@dismissible/react-client';
+
+function Dashboard() {
+  return (
+    <div>
+      <Dismissible id="feature-announcement-234-432-432-1">
+        <div className="alert alert-success">
+          🎉 New feature: Dark mode is now available!
+        </div>
+      </Dismissible>
+
+      <Dismissible id="maintenance-notice-234-432-432-1">
+        <div className="alert alert-warning">
+          ⚠️ Scheduled maintenance: Sunday 2AM-4AM EST
+        </div>
+      </Dismissible>
+
+      <Dismissible id="survey-request-234-432-432-1">
+        <div className="alert alert-info">
+          📝 Help us improve! Take our 2-minute survey.
+        </div>
+      </Dismissible>
+    </div>
+  );
+}
+```
+
+### Conditional Dismissible Content
+
+```tsx
+import { Dismissible } from '@dismissible/react-client';
+
+function ConditionalBanner({ user }) {
+  // Only show to new users
+  if (user.isReturning) {
+    return null;
+  }
+
+  return (
+    <Dismissible id={`onboarding-${user.id}`}>
+      <div className="onboarding-tips">
+        <h3>Getting Started</h3>
+        <ul>
+          <li>Complete your profile</li>
+          <li>Connect with friends</li>
+          <li>Explore our features</li>
+        </ul>
+      </div>
+    </Dismissible>
+  );
+}
+```
+
+### Using the Hook for Complex Logic
+
+```tsx
+import { useDismissibleItem } from '@dismissible/react-client';
+import { useState, useEffect } from 'react';
+
+function SmartNotification({ id, message, type = 'info' }) {
+  const { dismissedOn, dismiss, isLoading } = useDismissibleItem(id);
+  const [autoHide, setAutoHide] = useState(false);
+
+  // Auto-hide after 10 seconds for info messages
+  useEffect(() => {
+    if (type === 'info' && !dismissedOn) {
+      const timer = setTimeout(() => {
+        setAutoHide(true);
+        dismiss();
+      }, 10000);
+      
+      return () => clearTimeout(timer);
+    }
+  }, [type, dismissedOn, dismiss]);
+
+  if (dismissedOn || autoHide) {
+    return null;
+  }
+
+  return (
+    <div className={`notification notification-${type}`}>
+      <span>{message}</span>
+      <button 
+        onClick={dismiss}
+        disabled={isLoading}
+        className="dismiss-btn"
+      >
+        {isLoading ? '...' : '×'}
+      </button>
+    </div>
+  );
+}
+```
+
+## Styling
+
+The library includes minimal default styles. You can override them or provide your own:
+
+```css
+/* Default classes you can style */
+.dismissible-container {
+  /* Container for the dismissible content */
+}
+
+.dismissible-loading {
+  /* Loading state */
+}
+
+.dismissible-error {
+  /* Error state */
+}
+
+.dismissible-dismiss-btn {
+  /* Default dismiss button */
+}
+```
+
+## TypeScript Support
+
+The library is written in TypeScript and exports all type definitions:
+
+```tsx
+import type { 
+  DismissibleProps,
+  IDismissibleItem 
+} from '@dismissible/react-client';
+
+const MyComponent: React.FC<DismissibleProps> = (props) => {
+  // Your component implementation
+};
+```
+
+## Development
+
+### Prerequisites
+
+- Node.js 18+
+- npm or yarn
+
+### Setup
+
+```bash
+# Clone the repository
+git clone https://github.com/your-org/dismissible.git
+cd dismissible/react-client
+
+# Install dependencies
+npm install
+
+# Start development server
+npm run dev
+```
+
+### Available Scripts
+
+- `npm run dev` - Start development server with Vite
+- `npm run build` - Build the library for production
+- `npm run test` - Run tests with Vitest
+- `npm run test:watch` - Run tests in watch mode
+- `npm run lint` - Run ESLint
+- `npm run format` - Format code with Prettier
+- `npm run storybook` - Start Storybook development server
+- `npm run build-storybook` - Build Storybook for production
+
+### Testing
+
+```bash
+# Run all tests
+npm run test
+
+# Run tests in watch mode
+npm run test:watch
+
+# Run tests with coverage
+npm run test -- --coverage
+```
+
+### Storybook
+
+The library includes Storybook for component development and documentation:
+
+```bash
+npm run storybook
+```
+
+## Contributing
+
+We welcome contributions! Please see our [Contributing Guide](../CONTRIBUTING.md) for details.
+
+### Development Workflow
+
+1. Fork the repository
+2. Create a feature branch: `git checkout -b feature/my-new-feature`
+3. Make your changes
+4. Add tests for new functionality
+5. Run tests: `npm run test`
+6. Run linting: `npm run lint`
+7. Commit your changes: `git commit -am 'Add new feature'`
+8. Push to the branch: `git push origin feature/my-new-feature`
+9. Submit a pull request
+
+## License
+
+MIT © [Your Organization](https://github.com/your-org)
+
+## Support
+
+- 📖 [Documentation](https://docs.dismissible.io)
+- 🐛 [Issue Tracker](https://github.com/your-org/dismissible/issues)
+- 💬 [Discussions](https://github.com/your-org/dismissible/discussions)
+- 📧 [Email Support](mailto:support@dismissible.io)
+
+## Changelog
+
+See [CHANGELOG.md](./CHANGELOG.md) for a detailed list of changes.