@rowakit/table 0.1.0 → 0.2.1

package/README.md

@@ -11,7 +11,9 @@ RowaKit Table is a React table component designed for real-world internal applic
 ✅ **Minimal API** - Few props, convention over configuration  
 ✅ **Escape hatch** - `col.custom()` for any rendering need  
 ✅ **Action buttons** - Built-in support for row actions with confirmation  
-✅ **5 column types** - Text, Date, Boolean, Actions, Custom  
+✅ **7 column types** - Text, Date, Boolean, Badge, Number, Actions, Custom  
+✅ **Column modifiers** - Width, align, truncate support (v0.2.0+)  
+✅ **Server-side filters** - Type-specific filter UI with auto-generated inputs (v0.2.0+)  
 ✅ **State management** - Automatic loading, error, and empty states  
 ✅ **Smart fetching** - Retry on error, stale request handling
 
@@ -235,6 +237,86 @@ col.boolean('enabled', { format: (val) => val ? '✓' : '✗' })
 
 **Default format:** `'Yes'` / `'No'`
 
+#### `col.badge(field, options?)` (v0.2.0+)
+
+Badge column with visual tone mapping for status/enum values.
+
+```typescript
+col.badge('status', {
+  header: 'Status',
+  map: {
+    active: { label: 'Active', tone: 'success' },
+    pending: { label: 'Pending', tone: 'warning' },
+    inactive: { label: 'Inactive', tone: 'neutral' },
+    error: { label: 'Error', tone: 'danger' }
+  }
+})
+
+col.badge('priority', {
+  header: 'Priority',
+  sortable: true,
+  map: {
+    high: { label: 'High', tone: 'danger' },
+    medium: { label: 'Medium', tone: 'warning' },
+    low: { label: 'Low', tone: 'success' }
+  }
+})
+```
+
+**Options:**
+- `header?: string` - Custom header label
+- `sortable?: boolean` - Enable sorting
+- `map?: Record<string, { label: string; tone: BadgeTone }>` - Map values to badge labels and visual tones
+- `width?: number` - Column width in pixels
+- `align?: 'left' | 'center' | 'right'` - Text alignment
+- `truncate?: boolean` - Truncate with ellipsis
+
+**Badge Tones:**
+- `'neutral'` - Gray (default)
+- `'success'` - Green
+- `'warning'` - Yellow/Orange
+- `'danger'` - Red
+
+#### `col.number(field, options?)` (v0.2.0+)
+
+Number column with formatting support (currency, percentages, decimals).
+
+```typescript
+// Basic number
+col.number('quantity')
+
+// Currency formatting with Intl.NumberFormat
+col.number('price', {
+  header: 'Price',
+  sortable: true,
+  format: { style: 'currency', currency: 'USD' }
+})
+
+// Percentage
+col.number('discount', {
+  header: 'Discount',
+  format: { style: 'percent', minimumFractionDigits: 1 }
+})
+
+// Custom formatter
+col.number('score', {
+  header: 'Score',
+  format: (value) => `${value.toFixed(1)} pts`
+})
+```
+
+**Options:**
+- `header?: string` - Custom header label
+- `sortable?: boolean` - Enable sorting
+- `format?: Intl.NumberFormatOptions | ((value: number) => string)` - Formatting
+  - `Intl.NumberFormatOptions`: e.g., `{ style: 'currency', currency: 'USD' }`
+  - Function: Custom formatter like `(value) => value.toFixed(2)`
+- `width?: number` - Column width in pixels
+- `align?: 'left' | 'center' | 'right'` - Text alignment (defaults to 'right')
+- `truncate?: boolean` - Truncate with ellipsis
+
+**Default format:** Plain number with right alignment
+
 #### `col.actions(actions)`
 
 Actions column with buttons for row operations.
@@ -294,6 +376,41 @@ col.custom('summary', (row) => {
 })
 ```
 
+### Column Modifiers (v0.2.0+)
+
+All column types (text, date, boolean, badge, number) support these optional modifiers:
+
+```typescript
+// Width: Set fixed column width in pixels
+col.text('name', { width: 200 })
+
+// Align: Control text alignment
+col.text('status', { align: 'center' })
+col.number('price', { align: 'right' }) // numbers default to 'right'
+
+// Truncate: Enable text truncation with ellipsis
+col.text('description', { truncate: true, width: 300 })
+
+// Combine multiple modifiers
+col.badge('status', {
+  header: 'Status',
+  width: 120,
+  align: 'center',
+  truncate: true,
+  map: { active: 'success', inactive: 'neutral' }
+})
+```
+
+**Modifiers:**
+- `width?: number` - Column width in pixels
+- `align?: 'left' | 'center' | 'right'` - Text alignment
+- `truncate?: boolean` - Truncate long text with ellipsis (requires `width`)
+
+**Notes:**
+- Number columns default to `align: 'right'`
+- Other columns default to `align: 'left'`
+- Truncate works best with a fixed `width`
+
 ### Pagination
 
 The table includes built-in pagination controls that appear automatically when data is loaded.
@@ -411,6 +528,8 @@ const fetchUsers: Fetcher<User> = async ({ page, pageSize, sort }) => {
 - ✅ Text columns with `sortable: true`
 - ✅ Date columns with `sortable: true`
 - ✅ Boolean columns with `sortable: true`
+- ✅ Badge columns with `sortable: true` (v0.2.0+)
+- ✅ Number columns with `sortable: true` (v0.2.0+)
 - ❌ Actions columns (never sortable)
 - ❌ Custom columns (not sortable by default)
 
@@ -421,6 +540,147 @@ const fetchUsers: Fetcher<User> = async ({ page, pageSize, sort }) => {
 - Cleared when clicking a sorted column three times
 - Replaced when clicking a different sortable column
 
+### Filters (v0.2.0+)
+
+Server-side filtering with type-specific filter inputs rendered in a header row.
+
+**Features:**
+- **Auto-Generated UI** - Filter inputs based on column type
+- **Server-Side Only** - All filtering happens in your backend
+- **Multiple Operators** - contains, equals, in, range
+- **Clear Filters** - Individual and bulk filter clearing
+- **Page Reset** - Resets to page 1 when filters change
+
+**Enable Filters:**
+
+```typescript
+<RowaKitTable
+  fetcher={fetchUsers}
+  columns={columns}
+  rowKey="id"
+  enableFilters={true}  // Add this prop
+/>
+```
+
+**Filter Types by Column:**
+
+```typescript
+// Text column: Text input with "contains" operator
+col.text('name', { header: 'Name' })
+// → User types "john" → filters: { name: { op: 'contains', value: 'john' } }
+
+// Number column: Text input with "equals" operator
+col.number('age', { header: 'Age' })
+// → User types "25" → filters: { age: { op: 'equals', value: '25' } }
+
+// Badge column: Select dropdown with "equals" operator
+col.badge('status', {
+  header: 'Status',
+  map: { active: 'success', inactive: 'neutral', pending: 'warning' }
+})
+// → User selects "active" → filters: { status: { op: 'equals', value: 'active' } }
+
+// Boolean column: Select dropdown (All/True/False) with "equals" operator
+col.boolean('isVerified', { header: 'Verified' })
+// → User selects "True" → filters: { isVerified: { op: 'equals', value: true } }
+
+// Date column: Two date inputs with "range" operator
+col.date('createdAt', { header: 'Created' })
+// → User enters from/to dates → filters: { createdAt: { op: 'range', value: { from: '2024-01-01', to: '2024-12-31' } } }
+```
+
+**Fetcher Integration:**
+
+```typescript
+const fetchUsers: Fetcher<User> = async ({ page, pageSize, sort, filters }) => {
+  // filters is undefined when no filters are active
+  // filters = { fieldName: FilterValue, ... } when filtering
+  
+  const params = new URLSearchParams({
+    page: String(page),
+    limit: String(pageSize),
+  });
+  
+  if (sort) {
+    params.append('sortBy', sort.field);
+    params.append('sortOrder', sort.direction);
+  }
+  
+  if (filters) {
+    // Example: Convert filters to query params
+    for (const [field, filter] of Object.entries(filters)) {
+      if (filter.op === 'contains') {
+        params.append(`${field}_contains`, filter.value);
+      } else if (filter.op === 'equals') {
+        params.append(field, String(filter.value));
+      } else if (filter.op === 'range') {
+        if (filter.value.from) params.append(`${field}_from`, filter.value.from);
+        if (filter.value.to) params.append(`${field}_to`, filter.value.to);
+      }
+    }
+  }
+  
+  const response = await fetch(`/api/users?${params}`);
+  return response.json();
+};
+```
+
+**Filter Value Types:**
+
+```typescript
+type FilterValue =
+  | { op: 'contains'; value: string }           // Text search
+  | { op: 'equals'; value: string | number | boolean | null }  // Exact match
+  | { op: 'in'; value: Array<string | number> } // Multiple values (future)
+  | { op: 'range'; value: { from?: string; to?: string } };    // Date range
+
+type Filters = Record<string, FilterValue>;
+```
+
+**Important Rules:**
+
+1. **Undefined when empty**: `query.filters` is `undefined` when no filters are active (not `{}`)
+2. **Page resets**: Changing any filter resets page to 1
+3. **No client filtering**: All filtering must be handled by your backend
+4. **Actions/Custom columns**: Not filterable (no filter input rendered)
+
+**⚠️ Number Filter Behavior:**
+
+Number filters use **exact match** semantics (`op: 'equals'`). The filter value is sent as a string, and your backend must handle the comparison:
+
+```typescript
+// If user types "15" in a number filter input
+filters: { discount: { op: 'equals', value: '15' } }
+
+// Your backend must convert and compare appropriately:
+// If your data has discount as a fraction (0.15), you must convert:
+// parseInt('15') / 100 === 0.15  OR  parseFloat('15') / 100 === 0.15
+```
+
+**Common Pattern:**
+
+If your data uses decimals or percentages, ensure your backend coerces the filter value correctly:
+
+```typescript
+// Example: Number filter for percentage discount
+if (filters?.discount) {
+  const filterValue = parseFloat(filters.discount.value);
+  // If data is stored as fraction (0.15):
+  const compareValue = filterValue / 100;  // Convert "15" → 0.15
+  // Filter records where discount === compareValue
+}
+```
+
+**Clear Filters:**
+
+A "Clear all filters" button appears automatically when filters are active:
+
+```typescript
+// User applies filters
+// → "Clear all filters" button appears above table
+// → Click button → all filters cleared → page resets to 1
+```
+
 ### Actions
 
 The table provides built-in support for row actions with confirmation dialogs, loading states, and conditional disabling.
@@ -1059,6 +1319,41 @@ Full TypeScript support. Your data model drives type checking throughout.
 - Column resizing
 - Saved views
 
+## Changelog
+
+See the detailed changelog for release history and migration notes:
+
+- [CHANGELOG.md](./CHANGELOG.md) — highlights and details for v0.2.1 and future releases.
+
+### v0.2.1 - Production Release (2026-01-02)
+- ✅ **Fixed**: Number filter type coercion for accurate field matching
+- ✅ **Production Ready**: All 193 tests passing, dependencies hardened
+- ✅ **Backwards Compatible**: No breaking changes from v0.2.0
+
+### v0.2.0 - Stage B Features (2026-01-02)
+- Added `col.badge` and `col.number` column types
+- Column modifiers: `width`, `align`, `truncate`
+- Server-side header filter UI with type-specific inputs
+- Fixed numeric-filter value coercion bug (filter inputs now send numbers)
+
+## Release Notes — v0.2.0 (2026-01-02)
+
+This release introduces Stage B features and several hardening fixes to make `@rowakit/table` production-ready for internal apps.
+
+- Release: `v0.2.0`
+- Date: 2026-01-02
+- Key additions:
+  - `col.badge` — visual badge mapping for enum/status values with tone support
+  - `col.number` — number column with Intl formatting and percentage/currency helpers
+  - Column modifiers (`width`, `align`, `truncate`) supported across column types
+  - Server-side filters: auto-generated, type-specific inputs in the header row
+- Fixes & hardening:
+  - Removed direct React dependencies (now peerDependencies only)
+  - Resolved numeric filter coercion and clarified backend contract in README
+  - Deduplicated release checklist and improved demo documentation
+
+See the full changelog for migration notes and detailed descriptions: [CHANGELOG.md](./CHANGELOG.md)
+
 ## License
 
 MIT