@boxcustodia/library 2.0.0-alpha.22 → 2.0.0-alpha.24

package/src/hooks/use-selection/use-selection.stories.tsx

@@ -1,14 +1,13 @@
 import { Meta, StoryObj } from "@storybook/react-vite";
-import { Trash } from "lucide-react";
-import { useMemo, useState } from "react";
+import { useState } from "react";
 import { Button, Checkbox } from "../../components";
 import { cn } from "../../lib";
 import { useSelection } from "../use-selection";
 
 /**
- * Gestión de la selección de elementos en una lista.
- * Optimizado para un rendimiento eficiente, utiliza un conjunto (Set) interno para almacenar los elementos seleccionados, permitiendo consultas rápidas para verificar si un elemento está seleccionado.
- * Proporciona funciones simples para seleccionar, deseleccionar, alternar la selección de un elemento, seleccionar todos los elementos, limpiar la selección y obtener el estado actual de la selección
+ * `useSelection` manages item selection in a list. v2 adds key-based identity,
+ * `defaultSelected`, `onChange`, `selectedKeys`, `selectAll`, `invert`, and
+ * `selectRange` — while keeping all v1 actions stable across renders.
  */
 const meta: Meta = {
   title: "hooks/useSelection",
@@ -18,122 +17,378 @@ const meta: Meta = {
 export default meta;
 type Story = StoryObj<typeof meta>;
 
+// ─── Default ──────────────────────────────────────────────────────────────────
+
+/**
+ * Basic string list showcasing select/toggle/clear/toggleAll/selectAll.
+ * All flags (`isAllSelected`, `isSomeSelected`, `isNoneSelected`) are shown live.
+ */
+
+const fruits = ["Apple", "Banana", "Cherry", "Dragonfruit", "Elderberry"];
 export const Default: Story = {
   render: () => {
-    const items = useMemo(() => ["🍆", "🍅", "🥑", "🥬"], []);
     const {
       selected,
+      isSelected,
       toggle,
-      toggleAll,
       clear,
-      isSelected,
+      toggleAll,
+      selectAll,
       isAllSelected,
+      isSomeSelected,
       isNoneSelected,
-      setSelected,
-    } = useSelection(items);
+    } = useSelection(fruits);
 
     return (
-      <div className="space-y-4">
-        <div className="flex gap-2">
+      <div className="space-y-4 p-4">
+        <div className="space-y-1">
+          {fruits.map((fruit) => (
+            <div key={fruit} className="flex items-center gap-2">
+              <Checkbox
+                name={fruit}
+                checked={isSelected(fruit)}
+                onCheckedChange={() => toggle(fruit)}
+              />
+              <span className="text-sm">{fruit}</span>
+            </div>
+          ))}
+        </div>
+
+        <div className="flex flex-wrap gap-2">
+          <Button size="sm" variant="outline" onClick={toggleAll}>
+            Toggle all
+          </Button>
+          <Button size="sm" variant="outline" onClick={selectAll}>
+            Select all
+          </Button>
+          <Button size="sm" variant="outline" onClick={clear}>
+            Clear
+          </Button>
+        </div>
+
+        <pre className="rounded-md bg-slate-950 p-4 text-xs text-white">
+          <code>
+            {JSON.stringify(
+              { selected, isAllSelected, isSomeSelected, isNoneSelected },
+              null,
+              2,
+            )}
+          </code>
+        </pre>
+      </div>
+    );
+  },
+};
+
+// ─── WithKeyFn ────────────────────────────────────────────────────────────────
+
+/**
+ * Demonstrates key-based identity. Clicking "Refetch" replaces the items array
+ * with structurally-equal but referentially-new objects. With `keyFn`, selection
+ * survives the re-creation; without it, selection would be silently lost.
+ */
+export const WithKeyFn: Story = {
+  render: () => {
+    const [items, setItems] = useState([
+      { id: 1, name: "Alice" },
+      { id: 2, name: "Bob" },
+      { id: 3, name: "Carol" },
+    ]);
+
+    const { isSelected, toggle, selected, selectedKeys } = useSelection(items, {
+      keyFn: (item) => item.id,
+    });
+
+    const handleRefetch = () => {
+      // Simulate a re-fetch: same data, brand-new object references
+      setItems((prev) => prev.map((item) => ({ ...item })));
+    };
+
+    return (
+      <div className="space-y-4 p-4">
+        <p className="text-sm text-slate-500">
+          Click "Refetch" to replace the array with new object references.
+          Selection persists because <code>keyFn</code> uses stable IDs.
+        </p>
+
+        <div className="space-y-1">
           {items.map((item) => (
+            <div key={item.id} className="flex items-center gap-2">
+              <Checkbox
+                name={String(item.id)}
+                checked={isSelected(item)}
+                onCheckedChange={() => toggle(item)}
+              />
+              <span className="text-sm">{item.name}</span>
+            </div>
+          ))}
+        </div>
+
+        <Button size="sm" variant="outline" onClick={handleRefetch}>
+          Refetch (re-create object references)
+        </Button>
+
+        <pre className="rounded-md bg-slate-950 p-4 text-xs text-white">
+          <code>
+            {JSON.stringify(
+              {
+                selected: selected.map((i) => i.name),
+                selectedKeys: [...selectedKeys],
+              },
+              null,
+              2,
+            )}
+          </code>
+        </pre>
+      </div>
+    );
+  },
+};
+
+// ─── SelectRange ──────────────────────────────────────────────────────────────
+
+/**
+ * Shift-click range selection. Click a row to set the anchor, then
+ * Shift+click another row to select the inclusive range between them.
+ */
+export const SelectRange: Story = {
+  render: () => {
+    const items = [
+      "Document 1",
+      "Document 2",
+      "Document 3",
+      "Document 4",
+      "Document 5",
+      "Document 6",
+    ];
+
+    const [anchor, setAnchor] = useState<number | null>(null);
+    const { isSelected, toggle, selectRange, selected, clear } =
+      useSelection(items);
+
+    const handleClick = (index: number, shiftKey: boolean) => {
+      if (shiftKey && anchor !== null) {
+        selectRange(anchor, index);
+      } else {
+        toggle(items[index]);
+        setAnchor(index);
+      }
+    };
+
+    return (
+      <div className="space-y-4 p-4">
+        <p className="text-sm text-slate-500">
+          Click to toggle. Hold Shift and click to select a range from the last
+          clicked row.
+        </p>
+
+        <div className="rounded-md border">
+          {items.map((item, index) => (
             <div
               key={item}
-              onClick={() => toggle(item)}
               className={cn(
-                "rounded transition-colors w-32 h-32 shadow text-3xl grid place-items-center cursor-pointer",
-                { "bg-accent": isSelected(item) },
+                "flex cursor-pointer select-none items-center gap-3 border-b px-3 py-2 text-sm last:border-b-0",
+                isSelected(item) ? "bg-blue-50" : "hover:bg-slate-50",
               )}
+              onClick={(e) => handleClick(index, e.shiftKey)}
             >
-              {item}
+              <Checkbox
+                name={item}
+                checked={isSelected(item)}
+                onCheckedChange={() => handleClick(index, false)}
+              />
+              <span>{item}</span>
+              {anchor === index && (
+                <span className="ml-auto text-xs text-slate-400">anchor</span>
+              )}
             </div>
           ))}
         </div>
 
-        <div className="flex gap-4 my-2">
-          <Button onClick={clear}>Limpiar</Button>
-          <Button onClick={toggleAll}>Toggle all</Button>
-          <Button onClick={() => setSelected(["🍅"])}>set 🍅</Button>
+        <div className="flex gap-2">
+          <Button size="sm" variant="outline" onClick={clear}>
+            Clear
+          </Button>
         </div>
 
-        <pre className="p-4 text-white rounded-md bg-slate-950">
-          <code className="block">
-            Selected:{" "}
-            <span className="text-blue-300">
-              {JSON.stringify(selected, null, 2)}
-            </span>
-          </code>
-          <code className="block">
-            isAllSelected:{" "}
-            <span className={isAllSelected ? "text-green-500" : "text-red-500"}>
-              {JSON.stringify(isAllSelected)}
-            </span>
-          </code>
-          <code className="block">
-            isNoneSelected:{" "}
-            <span
-              className={isNoneSelected ? "text-green-500" : "text-red-500"}
+        <pre className="rounded-md bg-slate-950 p-4 text-xs text-white">
+          <code>{JSON.stringify({ selected }, null, 2)}</code>
+        </pre>
+      </div>
+    );
+  },
+};
+
+// ─── Invert ───────────────────────────────────────────────────────────────────
+
+/**
+ * Shows `invert()` which flips the current selection relative to `items`.
+ * None → All, All → None, Partial → complement.
+ */
+export const Invert: Story = {
+  render: () => {
+    const tags = ["React", "TypeScript", "Tailwind", "Vite", "Biome", "Vitest"];
+    const { isSelected, toggle, invert, selectAll, clear, selected } =
+      useSelection(tags);
+
+    return (
+      <div className="space-y-4 p-4">
+        <div className="flex flex-wrap gap-2">
+          {tags.map((tag) => (
+            <button
+              key={tag}
+              type="button"
+              onClick={() => toggle(tag)}
+              className={cn(
+                "rounded-full border px-3 py-1 text-sm transition-colors",
+                isSelected(tag)
+                  ? "border-blue-500 bg-blue-500 text-white"
+                  : "border-slate-300 bg-white text-slate-700 hover:border-slate-400",
+              )}
             >
-              {JSON.stringify(isNoneSelected)}
-            </span>
-          </code>
+              {tag}
+            </button>
+          ))}
+        </div>
+
+        <div className="flex flex-wrap gap-2">
+          <Button size="sm" variant="outline" onClick={invert}>
+            Invert selection
+          </Button>
+          <Button size="sm" variant="outline" onClick={selectAll}>
+            Select all
+          </Button>
+          <Button size="sm" variant="outline" onClick={clear}>
+            Clear
+          </Button>
+        </div>
+
+        <pre className="rounded-md bg-slate-950 p-4 text-xs text-white">
+          <code>{JSON.stringify({ selected }, null, 2)}</code>
         </pre>
       </div>
     );
   },
 };
 
-export const DynamicArray: Story = {
-  name: "Array dinamico",
+// ─── DefaultSelected ──────────────────────────────────────────────────────────
+
+/**
+ * Pre-initializes selection via `defaultSelected`. The hook seeds the
+ * selection once on mount and ignores further changes to the option.
+ */
+export const DefaultSelected: Story = {
   render: () => {
-    // state o useMemo
-    const [items, setItems] = useState([
-      { id: 1, name: "Item 1" },
-      { id: 2, name: "Item 2" },
-      { id: 3, name: "Item 3" },
-    ]);
+    const items = ["Option A", "Option B", "Option C", "Option D"];
+    const { isSelected, toggle, selected } = useSelection(items, {
+      defaultSelected: ["Option B", "Option D"],
+    });
 
-    const { selected, toggle, isSelected, unselect } = useSelection(items);
+    return (
+      <div className="space-y-4 p-4">
+        <p className="text-sm text-slate-500">
+          Options B and D are pre-selected via <code>defaultSelected</code>.
+        </p>
 
-    const addNewItem = () => {
-      const id = new Date().getTime();
-      setItems((prevItems) => [...prevItems, { id, name: `Item ${id}` }]);
-    };
+        <div className="space-y-1">
+          {items.map((item) => (
+            <div key={item} className="flex items-center gap-2">
+              <Checkbox
+                name={item}
+                checked={isSelected(item)}
+                onCheckedChange={() => toggle(item)}
+              />
+              <span className="text-sm">{item}</span>
+            </div>
+          ))}
+        </div>
 
-    const removeItem = (item: { id: number; name: string }) => {
-      setItems((prevItems) => prevItems.filter((i) => i.id !== item.id));
-      unselect(item);
-    };
+        <pre className="rounded-md bg-slate-950 p-4 text-xs text-white">
+          <code>{JSON.stringify({ selected }, null, 2)}</code>
+        </pre>
+      </div>
+    );
+  },
+};
+
+// ─── Controlled ───────────────────────────────────────────────────────────────
+
+/**
+ * External state drives selection via `setSelected`. `onChange` fires after
+ * each change and logs the derived `selected` items (orphaned keys excluded).
+ */
+export const Controlled: Story = {
+  render: () => {
+    const items = [
+      { id: 1, label: "Task 1" },
+      { id: 2, label: "Task 2" },
+      { id: 3, label: "Task 3" },
+      { id: 4, label: "Task 4" },
+    ];
+
+    const [log, setLog] = useState<string[]>([]);
+
+    const { isSelected, toggle, setSelected, selected, clear } = useSelection(
+      items,
+      {
+        keyFn: (item) => item.id,
+        onChange: (newSelected) => {
+          setLog((prev) => [
+            `onChange → [${newSelected.map((i) => i.label).join(", ")}]`,
+            ...prev.slice(0, 4),
+          ]);
+        },
+      },
+    );
 
     return (
-      <div>
-        {items.map((item) => (
-          <div key={item.id} className="flex items-center gap-2">
-            <Checkbox
-              name={item.id.toString()}
-              checked={isSelected(item)}
-              onCheckedChange={() => toggle(item)}
-            />
-            <span className="text-sm">{item.name}</span>
-            <Button
-              size="icon"
-              variant="ghost"
-              onClick={() => removeItem(item)}
-            >
-              <Trash />
-            </Button>
-          </div>
-        ))}
-        <Button className="my-2" onClick={addNewItem}>
-          Añadir nuevo elemento
-        </Button>
-        <pre className="p-4 text-white rounded-md bg-slate-950">
-          <code className="block">
-            Selected:{" "}
-            <span className="text-blue-300">
-              {JSON.stringify(selected, null, 2)}
-            </span>
+      <div className="space-y-4 p-4">
+        <div className="space-y-1">
+          {items.map((item) => (
+            <div key={item.id} className="flex items-center gap-2">
+              <Checkbox
+                name={String(item.id)}
+                checked={isSelected(item)}
+                onCheckedChange={() => toggle(item)}
+              />
+              <span className="text-sm">{item.label}</span>
+            </div>
+          ))}
+        </div>
+
+        <div className="flex flex-wrap gap-2">
+          <Button
+            size="sm"
+            variant="outline"
+            onClick={() => setSelected([items[0], items[2]])}
+          >
+            Set [Task 1, Task 3]
+          </Button>
+          <Button size="sm" variant="outline" onClick={clear}>
+            Clear
+          </Button>
+        </div>
+
+        <pre className="rounded-md bg-slate-950 p-4 text-xs text-white">
+          <code>
+            {JSON.stringify(
+              { selected: selected.map((i) => i.label) },
+              null,
+              2,
+            )}
           </code>
         </pre>
+
+        {log.length > 0 && (
+          <div className="space-y-1">
+            <p className="text-xs font-medium text-slate-500">onChange log:</p>
+            {log.map((entry, i) => (
+              <p key={i} className="font-mono text-xs text-slate-600">
+                {entry}
+              </p>
+            ))}
+          </div>
+        )}
       </div>
     );
   },