@dsbtek/component-library 1.0.0 → 1.0.1

package/README.md

@@ -1,17 +1,340 @@
-# SFT Advanced Components
+# @dsbtek/component-library
 
-This package provides advanced React components built on top of shadcn/ui.
+A collection of advanced React components built with shadcn/ui.
+
+## Table of Contents
+
+-   [Installation](#installation)
+-   [Components](#components)
+    -   [AdvancedCombobox](#advancedcombobox)
+    -   [AdvancedDataTable](#advanceddatatable)
+-   [Styling](#styling)
+-   [Contributing](#contributing)
+-   [License](#license)
 
 ## Installation
 
+1. Install the package and its peer dependencies:
+
+```bash
+# Install the component library
+npm install @dsbtek/component-library
+
+# Install peer dependencies
+npm install @radix-ui/react-popover cmdk class-variance-authority clsx lucide-react tailwind-merge
+```
+
+2. Set up Tailwind CSS in your project:
+
 ```bash
-npm install @smartflowtech/component-library
+# Install Tailwind CSS and its dependencies
+npm install -D tailwindcss postcss autoprefixer tailwindcss-animate
+```
+
+3. Initialize Tailwind CSS if you haven't already:
+
+```bash
+npx tailwindcss init -p
+```
+
+4. Update your `tailwind.config.js`:
+
+```javascript
+/** @type {import('tailwindcss').Config} */
+module.exports = {
+    darkMode: ['class'],
+    content: [
+        './src/**/*.{js,ts,jsx,tsx}',
+        './node_modules/@dsbtek/component-library/**/*.{js,ts,jsx,tsx}',
+    ],
+    theme: {
+        extend: {
+            colors: {
+                border: 'hsl(var(--border))',
+                input: 'hsl(var(--input))',
+                ring: 'hsl(var(--ring))',
+                background: 'hsl(var(--background))',
+                foreground: 'hsl(var(--foreground))',
+                primary: {
+                    DEFAULT: 'hsl(var(--primary))',
+                    foreground: 'hsl(var(--primary-foreground))',
+                },
+                secondary: {
+                    DEFAULT: 'hsl(var(--secondary))',
+                    foreground: 'hsl(var(--secondary-foreground))',
+                },
+                destructive: {
+                    DEFAULT: 'hsl(var(--destructive))',
+                    foreground: 'hsl(var(--destructive-foreground))',
+                },
+                muted: {
+                    DEFAULT: 'hsl(var(--muted))',
+                    foreground: 'hsl(var(--muted-foreground))',
+                },
+                accent: {
+                    DEFAULT: 'hsl(var(--accent))',
+                    foreground: 'hsl(var(--accent-foreground))',
+                },
+                popover: {
+                    DEFAULT: 'hsl(var(--popover))',
+                    foreground: 'hsl(var(--popover-foreground))',
+                },
+                card: {
+                    DEFAULT: 'hsl(var(--card))',
+                    foreground: 'hsl(var(--card-foreground))',
+                },
+            },
+            borderRadius: {
+                lg: `var(--radius)`,
+                md: `calc(var(--radius) - 2px)`,
+                sm: 'calc(var(--radius) - 4px)',
+            },
+        },
+    },
+    plugins: [require('tailwindcss-animate')],
+};
 ```
 
-## Usage
+5. Add the following CSS variables to your global CSS file:
 
-```jsx
-import { AdvancedCombobox } from '@smartflowtech/component-library';
+```css
+@tailwind base;
+@tailwind components;
+@tailwind utilities;
 
-// ... rest of the documentation
+@layer base {
+    :root {
+        --background: 0 0% 100%;
+        --foreground: 222.2 84% 4.9%;
+        --card: 0 0% 100%;
+        --card-foreground: 222.2 84% 4.9%;
+        --popover: 0 0% 100%;
+        --popover-foreground: 222.2 84% 4.9%;
+        --primary: 222.2 47.4% 11.2%;
+        --primary-foreground: 210 40% 98%;
+        --secondary: 210 40% 96.1%;
+        --secondary-foreground: 222.2 47.4% 11.2%;
+        --muted: 210 40% 96.1%;
+        --muted-foreground: 215.4 16.3% 46.9%;
+        --accent: 210 40% 96.1%;
+        --accent-foreground: 222.2 47.4% 11.2%;
+        --destructive: 0 84.2% 60.2%;
+        --destructive-foreground: 210 40% 98%;
+        --border: 214.3 31.8% 91.4%;
+        --input: 214.3 31.8% 91.4%;
+        --ring: 222.2 84% 4.9%;
+        --radius: 0.5rem;
+    }
+}
 ```
+
+## Components
+
+### AdvancedCombobox
+
+A searchable dropdown component with single or multiple selection support.
+
+#### Features
+
+-   Single or multiple item selection
+-   Search functionality with fuzzy matching
+-   Keyboard navigation support (↑↓ to navigate, Enter to select)
+-   Clear selection option
+-   Customizable styling
+-   Accessible by default (WAI-ARIA compliant)
+
+#### Props
+
+| Prop        | Type                                      | Default  | Description                                |
+| ----------- | ----------------------------------------- | -------- | ------------------------------------------ |
+| items       | `Array<{ value: string, label: string }>` | Required | Array of items to display in the dropdown  |
+| placeholder | `string`                                  | Required | Placeholder text when no item is selected  |
+| onSelect    | `(value: string) => void`                 | Required | Callback function when an item is selected |
+| multiple    | `boolean`                                 | `false`  | Enable multiple item selection             |
+| searchable  | `boolean`                                 | `true`   | Enable search functionality                |
+| className   | `string`                                  | -        | Additional CSS classes                     |
+
+#### Keyboard Shortcuts
+
+-   `↑/↓`: Navigate through items
+-   `Enter`: Select highlighted item
+-   `Esc`: Close dropdown
+-   `Backspace`: Clear selection (when input is empty)
+-   `Type`: Search items (when searchable is true)
+
+#### Example Usage
+
+```tsx
+import { AdvancedCombobox } from '@dsbtek/component-library';
+
+// Single Selection with Search
+function SingleSelectExample() {
+    return (
+        <AdvancedCombobox
+            items={[
+                { value: '1', label: 'Option 1' },
+                { value: '2', label: 'Option 2' },
+                { value: '3', label: 'Option 3' },
+            ]}
+            placeholder="Select an option"
+            onSelect={(value) => console.log('Selected:', value)}
+        />
+    );
+}
+
+// Multiple Selection
+function MultipleSelectExample() {
+    return (
+        <AdvancedCombobox
+            items={[
+                { value: 'react', label: 'React' },
+                { value: 'vue', label: 'Vue' },
+                { value: 'angular', label: 'Angular' },
+            ]}
+            placeholder="Select frameworks"
+            onSelect={(value) => console.log('Selected:', value)}
+            multiple={true}
+        />
+    );
+}
+```
+
+### AdvancedDataTable
+
+A feature-rich data table component with sorting, filtering, and pagination.
+
+#### Features
+
+-   Column sorting (click column headers)
+-   Text filtering
+-   Pagination with customizable page sizes
+-   Row selection with checkboxes
+-   Responsive design
+-   Customizable styling
+-   Loading states
+-   Empty state handling
+
+#### Props
+
+| Prop                | Type                                                 | Default      | Description                                        |
+| ------------------- | ---------------------------------------------------- | ------------ | -------------------------------------------------- |
+| columns             | `Array<Column<T>>`                                   | Required     | Array of column definitions                        |
+| fetchData           | `(params: FetchParams) => Promise<FetchResponse<T>>` | Required     | Function to fetch data with pagination and sorting |
+| itemsPerPageOptions | `number[]`                                           | `[10,20,50]` | Available options for items per page               |
+| className           | `string`                                             | -            | Additional CSS classes                             |
+
+#### Column Definition
+
+| Property   | Type                                        | Default  | Description                              |
+| ---------- | ------------------------------------------- | -------- | ---------------------------------------- |
+| accessor   | `keyof T \| ((item: T) => React.ReactNode)` | Required | Key or function to access the cell value |
+| header     | `string`                                    | Required | Column header text                       |
+| sortable   | `boolean`                                   | `false`  | Enable column sorting                    |
+| filterable | `boolean`                                   | `false`  | Enable column filtering                  |
+| cell       | `(value: any, item: T) => React.ReactNode`  | -        | Custom cell renderer                     |
+
+#### FetchParams Type
+
+```typescript
+interface FetchParams {
+    page: number;
+    perPage: number;
+    sortBy?: string;
+    sortOrder?: 'asc' | 'desc';
+    filters?: Record<string, string>;
+}
+```
+
+#### FetchResponse Type
+
+```typescript
+interface FetchResponse<T> {
+    data: T[];
+    meta: {
+        current_page: number;
+        last_page: number;
+        per_page: number;
+        total: number;
+    };
+}
+```
+
+#### Example Usage
+
+```tsx
+import { AdvancedDataTable } from '@dsbtek/component-library';
+
+function TableExample() {
+    const columns = [
+        {
+            accessor: 'name',
+            header: 'Name',
+            sortable: true,
+            filterable: true,
+        },
+        {
+            accessor: 'email',
+            header: 'Email',
+            sortable: true,
+        },
+        {
+            accessor: 'status',
+            header: 'Status',
+            cell: (value) => (
+                <span className={`status-${value.toLowerCase()}`}>{value}</span>
+            ),
+        },
+    ];
+
+    const fetchData = async (params) => {
+        const response = await fetch(
+            '/api/users?' +
+                new URLSearchParams({
+                    page: params.page.toString(),
+                    perPage: params.perPage.toString(),
+                    sortBy: params.sortBy,
+                    sortOrder: params.sortOrder,
+                    ...params.filters,
+                }),
+        );
+        return response.json();
+    };
+
+    return (
+        <AdvancedDataTable
+            columns={columns}
+            fetchData={fetchData}
+            itemsPerPageOptions={[5, 10, 20, 50]}
+        />
+    );
+}
+```
+
+## Styling
+
+All components use Tailwind CSS for styling and can be customized using Tailwind classes. The components also respect the theme variables defined in your CSS.
+
+### Custom Styling Example
+
+```tsx
+<AdvancedCombobox
+    className="w-[300px] rounded-lg"
+    items={items}
+    placeholder="Custom styled combobox"
+    onSelect={handleSelect}
+/>
+
+<AdvancedDataTable
+    className="border rounded-lg shadow-sm"
+    columns={columns}
+    fetchData={fetchData}
+/>
+```
+
+## Contributing
+
+[Add contribution guidelines here]
+
+## License
+
+MIT

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@dsbtek/component-library",
-    "version": "1.0.0",
+    "version": "1.0.1",
     "main": "./dist/index.js",
     "module": "./dist/index.mjs",
     "types": "./dist/index.d.ts",