@particle-academy/react-fancy 3.2.1 → 3.3.0

package/README.md

@@ -1,6 +1,6 @@
 # @particle-academy/react-fancy
 
-React UI component library — the React port of the `fancy-flux` Blade/Livewire component library. The goal is **visual and behavioral parity** with fancy-flux.
+React UI component library for **Human+ UX** — controlled, agent-bridgeable primitives that humans and agents share. Every component exposes `value` / `onChange`, stable handles, and JSON-friendly props so MCP bridges can drive the UI without DOM scraping.
 
 ## Inertia.js integration
 
@@ -240,7 +240,7 @@ src/
 
 - `Size` — `"xs" | "sm" | "md" | "lg" | "xl"`
 - `Color` — Full Tailwind color palette (17 colors)
-- `ActionColor` — Subset of 10 standalone colors matching fancy-flux
+- `ActionColor` — Subset of 10 standalone colors used by Action and friends
 - `Variant` — `"solid" | "outline" | "ghost" | "soft"`
 - `Placement` — `"top" | "bottom" | "left" | "right"` + start/end variants
 
@@ -268,16 +268,23 @@ Every component follows this structure:
 
 Use `lucide-react` as the default icon library. It is a dependency of this package and marked as external in tsup. Components should import icons directly (e.g., `import { X, ChevronDown } from "lucide-react"`).
 
-### Parity with fancy-flux
+### Human+ UX contract
 
-- **Always reference the corresponding Blade component** in `packages/fancy-flux/stubs/resources/views/flux/` when implementing or updating a component. Match the Tailwind classes, color values, state logic, and dark mode support exactly.
-- React-specific additions (e.g., `loading` spinner, `href` anchor rendering) are fine — they don't exist in Blade but are idiomatic in React.
-- Icons are passed as `ReactNode` (not string names like Blade's `<flux:icon>`). This is the correct React pattern.
+Every interactive component must:
+
+- Expose **`value` + `onChange`** so an agent can read and write state. No internal-only state for anything an agent might want to inspect or change.
+- Carry **stable handles** — `id`, `data-react-fancy-*` attributes, or a selector prop — so MCP bridges can address elements without guessing DOM structure.
+- Accept **JSON-friendly props** — arrays of objects, primitives, simple discriminated unions. Avoid forcing React children for things the agent needs to populate.
+- Support a **bridgeable surface**: a `register<Surface>Bridge(server, { adapter })` (in `agent-integrations`) should be sketchable in one sitting.
+- Broadcast **`AgentActivity`** events for mutations so presence, undo, and coaching layers can compose.
+- Provide **trust-but-verify** hooks for destructive actions — agents propose, humans confirm via `pendingMode` / staged-write affordances.
+
+Purely visual primitives (labels, dividers, layout shells) only owe the first bullet.
 
 ### Styling
 
 - **Tailwind v4** — CSS-first config. Use `@import "tailwindcss"` not `@tailwind` directives.
-- **Dark mode** — Every color variant must include `dark:` equivalents. Check fancy-flux for the exact classes. Portal components get dark mode automatically via the Portal wrapper.
+- **Dark mode** — Every color variant must include `dark:` equivalents. Portal components get dark mode automatically via the Portal wrapper.
 - **No component library deps** — Only `clsx`, `tailwind-merge`, and `lucide-react`. Don't add Radix, Headless UI, or similar.
 - Class maps should be `Record<Size, string>` (or similar) constants outside the component function, not inline.
 

package/dist/index.cjs

@@ -6673,6 +6673,127 @@ var Timeline = Object.assign(TimelineRoot, {
   Item: TimelineItem,
   Block: TimelineBlock
 });
+var TONE_CLASSES = {
+  violet: "bg-violet-500 hover:bg-violet-600",
+  emerald: "bg-emerald-500 hover:bg-emerald-600",
+  sky: "bg-sky-500 hover:bg-sky-600",
+  rose: "bg-rose-500 hover:bg-rose-600",
+  amber: "bg-amber-500 hover:bg-amber-600",
+  indigo: "bg-indigo-500 hover:bg-indigo-600",
+  blue: "bg-blue-500 hover:bg-blue-600",
+  zinc: "bg-zinc-500 hover:bg-zinc-600"
+};
+var OFF_CLASSES = "bg-zinc-100 hover:bg-zinc-200 dark:bg-zinc-800 dark:hover:bg-zinc-700";
+var TimeGrid = react.forwardRef(
+  ({
+    rows,
+    cols,
+    value,
+    onChange,
+    toneOn = "violet",
+    cellWidth = 20,
+    cellHeight = 16,
+    sparseColLabels = true,
+    toggleStripsOnHeaderClick = true,
+    ariaCell,
+    cellId,
+    className
+  }, ref) => {
+    const [drag, setDrag] = react.useState(null);
+    const setCell = (r, c, v) => {
+      if (value[r]?.[c] === v) return;
+      const next = value.map((row) => row.slice());
+      next[r][c] = v;
+      onChange(next);
+    };
+    const toggleRow = (r) => {
+      if (!toggleStripsOnHeaderClick) return;
+      const all = value[r].every(Boolean);
+      const next = value.map((row) => row.slice());
+      for (let c = 0; c < cols.length; c++) next[r][c] = !all;
+      onChange(next);
+    };
+    const toggleCol = (c) => {
+      if (!toggleStripsOnHeaderClick) return;
+      const all = value.every((row) => row[c]);
+      const next = value.map((row) => row.slice());
+      for (let r = 0; r < rows.length; r++) next[r][c] = !all;
+      onChange(next);
+    };
+    const colStep = Math.max(1, Math.floor(cols.length / 6));
+    const onTone = TONE_CLASSES[toneOn];
+    return /* @__PURE__ */ jsxRuntime.jsx(
+      "div",
+      {
+        ref,
+        "data-react-fancy-timegrid": "",
+        className: cn(
+          "select-none overflow-x-auto",
+          className
+        ),
+        onMouseLeave: () => setDrag(null),
+        onMouseUp: () => setDrag(null),
+        children: /* @__PURE__ */ jsxRuntime.jsxs("table", { className: "text-[10px]", children: [
+          /* @__PURE__ */ jsxRuntime.jsx("thead", { children: /* @__PURE__ */ jsxRuntime.jsxs("tr", { children: [
+            /* @__PURE__ */ jsxRuntime.jsx("th", {}),
+            cols.map((label, c) => /* @__PURE__ */ jsxRuntime.jsx(
+              "th",
+              {
+                onClick: () => toggleCol(c),
+                style: { width: cellWidth },
+                "data-react-fancy-timegrid-col": c,
+                className: cn(
+                  "text-zinc-400",
+                  toggleStripsOnHeaderClick && "cursor-pointer hover:text-zinc-700 dark:hover:text-zinc-200"
+                ),
+                children: sparseColLabels ? c % colStep === 0 ? label : "" : label
+              },
+              c
+            ))
+          ] }) }),
+          /* @__PURE__ */ jsxRuntime.jsx("tbody", { children: rows.map((label, r) => /* @__PURE__ */ jsxRuntime.jsxs("tr", { children: [
+            /* @__PURE__ */ jsxRuntime.jsx(
+              "th",
+              {
+                onClick: () => toggleRow(r),
+                "data-react-fancy-timegrid-row": r,
+                className: cn(
+                  "pr-1 text-right font-medium text-zinc-500",
+                  toggleStripsOnHeaderClick && "cursor-pointer hover:text-zinc-800 dark:hover:text-zinc-200"
+                ),
+                children: label
+              }
+            ),
+            cols.map((_, c) => {
+              const on = value[r]?.[c] ?? false;
+              return /* @__PURE__ */ jsxRuntime.jsx("td", { className: "p-px", children: /* @__PURE__ */ jsxRuntime.jsx(
+                "button",
+                {
+                  type: "button",
+                  onMouseDown: () => {
+                    const v = !on;
+                    setDrag(v);
+                    setCell(r, c, v);
+                  },
+                  onMouseEnter: () => drag !== null && setCell(r, c, drag),
+                  style: { width: cellWidth, height: cellHeight },
+                  "data-react-fancy-timegrid-cell": cellId ? cellId(r, c) : `${r}:${c}`,
+                  "aria-pressed": on,
+                  "aria-label": ariaCell ? ariaCell(r, c, on) : `${rows[r]} ${cols[c]} ${on ? "on" : "off"}`,
+                  className: cn(
+                    "block rounded-sm transition",
+                    on ? onTone : OFF_CLASSES
+                  )
+                }
+              ) }, c);
+            })
+          ] }, r)) })
+        ] })
+      }
+    );
+  }
+);
+TimeGrid.displayName = "TimeGrid";
 var Tooltip = react.forwardRef(
   function Tooltip2({ children, content, placement = "top", delay = 200, offset = 8, className }, _ref) {
     const [open, setOpen] = react.useState(false);
@@ -13179,6 +13300,7 @@ exports.Table = Table;
 exports.Tabs = Tabs;
 exports.Text = Text;
 exports.Textarea = Textarea;
+exports.TimeGrid = TimeGrid;
 exports.TimePicker = TimePicker;
 exports.Timeline = Timeline;
 exports.Toast = Toast;