@particle-academy/react-fancy 2.7.0 → 2.8.0

package/docs/AccordionPanel.md

@@ -118,6 +118,7 @@ const [open, setOpen] = useState<string[]>(["wishlist"]);
 | `pinned` | `boolean` | `false` | Never collapses; doesn't need a Trigger |
 | `className` | `string` | - | Class on the section's outer container |
 | `openClassName` / `closedClassName` | `string` | - | Class applied per state |
+| `unstyled` | `boolean` | `false` | Skip the default flex layout (`items-center`, `gap-1`, row/col by orientation). Use for full-bleed panel sections where the trigger should stretch to fill the panel. *Since v2.7.0.* |
 
 ### AccordionPanel.Trigger
 
@@ -133,3 +134,8 @@ const [open, setOpen] = useState<string[]>(["wishlist"]);
 |------|------|---------|-------------|
 | `children` | `ReactNode` | **required** | Open-state content |
 | `className` | `string` | - | Layout class on the content container |
+| `unstyled` | `boolean` | `false` | Skip the default flex layout. Same intent as `Section.unstyled` — for full-bleed panel content (chat panes, canvas surfaces). *Since v2.7.0.* |
+
+## Hitbox
+
+The default open-state Trigger renders as a thin 1px divider on the section's trailing edge, but the **clickable hitbox is 12px wide** (`w-3` / `h-3`) so users don't have to land pixel-perfect on the line. The visible 1px line darkens on hover and an inset chevron fades in. *Since v2.7.0.*

package/docs/Kanban.md

@@ -1,6 +1,6 @@
 # Kanban
 
-A drag-and-drop kanban board using the HTML5 Drag and Drop API. Cards can be moved between columns.
+A drag-and-drop kanban board using the HTML5 Drag and Drop API. Cards drag between columns and within a column; columns can be reordered with a `<Kanban.ColumnHandle>`. Cards accept arbitrary children, so you have full creative control over what each card looks like.
 
 ## Import
 
@@ -11,12 +11,16 @@ import { Kanban } from "@particle-academy/react-fancy";
 ## Basic Usage
 
 ```tsx
-<Kanban onCardMove={(cardId, from, to) => console.log(`${cardId}: ${from} -> ${to}`)}>
-  <Kanban.Column id="todo" title="To Do">
+<Kanban
+  onCardMove={(cardId, from, to, toIndex) => {
+    // toIndex is the destination position within `to`.
+  }}
+>
+  <Kanban.Column id="todo" title="To Do" wipLimit={4}>
     <Kanban.Card id="task-1">Design homepage</Kanban.Card>
     <Kanban.Card id="task-2">Write tests</Kanban.Card>
   </Kanban.Column>
-  <Kanban.Column id="in-progress" title="In Progress">
+  <Kanban.Column id="in-progress" title="In Progress" wipLimit={2}>
     <Kanban.Card id="task-3">Build API</Kanban.Card>
   </Kanban.Column>
   <Kanban.Column id="done" title="Done">
@@ -25,30 +29,78 @@ import { Kanban } from "@particle-academy/react-fancy";
 </Kanban>
 ```
 
+The board ships with a drop-position indicator (a thin blue line that appears where the dragged card will land), full within-column reorder, and a header chip that shows `count / wipLimit` and turns red over capacity.
+
+## Compound parts
+
+| Component | Role |
+|-----------|------|
+| `Kanban` | Root. Owns drag state and computes column drop positions. |
+| `Kanban.Column` | A drop target. Renders a column header (when `title` is set), tracks card drop position. |
+| `Kanban.Card` | A draggable card. Accepts arbitrary children. |
+| `Kanban.ColumnHandle` | Optional. Mount inside a column to make that column draggable for column reorder. |
+
 ## Props
 
 ### Kanban (root)
 
 | Prop | Type | Default | Description |
 |------|------|---------|-------------|
-| onCardMove | `(cardId: string, fromColumn: string, toColumn: string) => void` | - | Callback when a card is dropped into a different column |
-| className | `string` | - | Additional CSS classes |
+| `onCardMove` | `(cardId, fromColumn, toColumn, toIndex) => void` | - | Fires on every card drop. `toIndex` is the destination position within `toColumn` (0-based; equal to current count means append). For a same-column reorder, `fromColumn === toColumn`. |
+| `onColumnMove` | `(columnId, toIndex) => void` | - | Fires when a column is dropped at a new position. Only fires if at least one column has a `<Kanban.ColumnHandle>` and a column was actually dragged. |
+| `className` | `string` | - | Additional CSS classes |
 
 ### Kanban.Column
 
 | Prop | Type | Default | Description |
 |------|------|---------|-------------|
-| id | `string` | - | Unique column identifier (required) |
-| title | `string` | - | Column header text |
-| className | `string` | - | Additional CSS classes |
+| `id` | `string` | **required** | Unique column identifier |
+| `title` | `string` | - | Column header text. When set, the column renders a built-in header with a count chip (and `count / wipLimit` if `wipLimit` is set). |
+| `wipLimit` | `number` | - | Soft work-in-progress limit. The header pill turns red when `cardCount > wipLimit`. Drops are not refused — enforce hard via `onCardMove`. *Since v2.8.0.* |
+| `hideWhenEmpty` | `boolean` | `false` | Render nothing when the column has zero card children. The column still re-mounts to receive drops while a card is being dragged elsewhere. *Since v2.8.0.* |
+| `unstyled` | `boolean` | `false` | Skip the default visuals (background, padding, min-height, fixed `w-72`) so you can render your own surface around the children. The drop target, drag-over ring, and column id wiring are kept. *Since v2.7.0.* |
+| `className` | `string` | - | Additional CSS classes |
 
 ### Kanban.Card
 
 | Prop | Type | Default | Description |
 |------|------|---------|-------------|
-| id | `string` | - | Unique card identifier (required) |
-| children | `ReactNode` | - | Card content |
-| className | `string` | - | Additional CSS classes |
+| `id` | `string` | **required** | Unique card identifier |
+| `children` | `ReactNode` | - | Card content |
+| `unstyled` | `boolean` | `false` | Skip the default border / padding / shadow so you can wrap your own `<Card>` (or any surface) inside. Drag handlers and `draggable` stay in place. *Since v2.7.0.* |
+| `className` | `string` | - | Additional CSS classes |
+
+### Kanban.ColumnHandle (since v2.8.0)
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `children` | `ReactNode` | **required** | Render the column header (or a grip icon) inside the handle. Anywhere inside is the drag origin. |
+| `className` | `string` | - | Additional CSS classes |
+
+Mount inside a `Kanban.Column`. Without it, the column is static.
+
+## Composing custom card visuals
+
+When you want full control over the card body — wrapping a `<Card>` with avatars, badges, dropdown menus — pass `unstyled` so the Kanban wrapper just provides drag plumbing:
+
+```tsx
+<Kanban.Card id={card.id} unstyled>
+  <Card variant="elevated" padding="none" className="overflow-hidden">
+    {/* your fancy card body */}
+  </Card>
+</Kanban.Card>
+```
+
+Same pattern works for columns:
+
+```tsx
+<Kanban.Column id="doing" unstyled wipLimit={3} className="w-80 rounded-xl bg-zinc-50 p-3 ring-1 ring-zinc-200">
+  <Kanban.ColumnHandle>
+    <MyColumnHeader title="In progress" wipLimit={3} />
+  </Kanban.ColumnHandle>
+  {cards.map((c) => <Kanban.Card key={c.id} id={c.id} unstyled>...</Kanban.Card>)}
+</Kanban.Column>
+```
 
 ## Stateful Example
 
@@ -58,22 +110,64 @@ const [columns, setColumns] = useState({
   doing: ["task-3"],
   done: [],
 });
+const [order, setOrder] = useState(["todo", "doing", "done"]);
+
+function handleCardMove(cardId, from, to, toIndex) {
+  setColumns((prev) => {
+    const fromList = prev[from].filter((id) => id !== cardId);
+    if (from === to) {
+      fromList.splice(toIndex, 0, cardId);
+      return { ...prev, [from]: fromList };
+    }
+    const toList = [...prev[to]];
+    toList.splice(toIndex, 0, cardId);
+    return { ...prev, [from]: fromList, [to]: toList };
+  });
+}
 
-function handleMove(cardId: string, from: string, to: string) {
-  setColumns((prev) => ({
-    ...prev,
-    [from]: prev[from].filter((id) => id !== cardId),
-    [to]: [...prev[to], cardId],
-  }));
+function handleColumnMove(id, toIndex) {
+  setOrder((prev) => {
+    const next = prev.filter((c) => c !== id);
+    next.splice(toIndex, 0, id);
+    return next;
+  });
 }
 
-<Kanban onCardMove={handleMove}>
-  {Object.entries(columns).map(([colId, cards]) => (
+<Kanban onCardMove={handleCardMove} onColumnMove={handleColumnMove}>
+  {order.map((colId) => (
     <Kanban.Column key={colId} id={colId} title={colId}>
-      {cards.map((id) => (
+      <Kanban.ColumnHandle>{/* header */}</Kanban.ColumnHandle>
+      {columns[colId].map((id) => (
         <Kanban.Card key={id} id={id}>{id}</Kanban.Card>
       ))}
     </Kanban.Column>
   ))}
 </Kanban>
 ```
+
+## Async move with rollback
+
+`onCardMove` can be `async`. Apply optimistically, revert on failure:
+
+```tsx
+async function handleMove(id, from, to, toIndex) {
+  const prev = state;
+  setState(s => move(s, id, from, to, toIndex));
+  try {
+    await api.move(id, to, toIndex);
+  } catch {
+    setState(prev);
+    toast.error("Move failed");
+  }
+}
+```
+
+## Pending
+
+The component still doesn't handle:
+
+- **Touch / mobile** — HTML5 DnD is desktop-only.
+- **Full keyboard navigation** — arrow-key / space-to-lift move pattern not yet implemented. Roles (`application`, `group`) are in place to lay groundwork.
+- **Custom drag preview** — uses the browser default ghost.
+- **Multi-select drag.**
+- **Swimlanes / row grouping.**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@particle-academy/react-fancy",
-  "version": "2.7.0",
+  "version": "2.8.0",
   "description": "React UI component library — React port of the fancy-flux Blade component library",
   "repository": {
     "type": "git",