@particle-academy/react-fancy 2.2.0 → 2.2.1

package/docs/Action.md

@@ -18,7 +18,7 @@ import { Action } from "@particle-academy/react-fancy";
 
 | Prop | Type | Default | Description |
 |------|------|---------|-------------|
-| variant | `"default" \| "circle"` | `"default"` | Shape variant |
+| variant | `"default" \| "circle" \| "ghost"` | `"default"` | Shape/fill variant. `"ghost"` is transparent with subtle hover. |
 | color | `ActionColor` | - | Standalone color (overrides state colors). One of: `"blue"`, `"emerald"`, `"amber"`, `"red"`, `"violet"`, `"indigo"`, `"sky"`, `"rose"`, `"orange"`, `"zinc"` |
 | size | `"xs" \| "sm" \| "md" \| "lg" \| "xl"` | `"md"` | Button size |
 | active | `boolean` | - | Active state (blue highlight) |
@@ -74,3 +74,10 @@ Also extends all native `<button>` HTML attributes (except `color`).
   Read docs
 </Action>
 ```
+
+### Ghost variant
+
+```tsx
+<Action variant="ghost" color="red" icon="trash-2">Delete</Action>
+<Action variant="ghost" icon="download">Export</Action>
+```

package/docs/Editor.md

@@ -60,6 +60,7 @@ A visual separator between toolbar groups. No props.
 | Prop | Type | Default | Description |
 |------|------|---------|-------------|
 | className | `string` | - | Additional CSS classes |
+| maxHeight | `number` | - | Max height in px before scrolling. When set, the content area becomes scrollable. |
 
 ## Markdown Output
 
@@ -70,14 +71,81 @@ A visual separator between toolbar groups. No props.
 </Editor>
 ```
 
+## Scrollable Editor
+
+Constrain the editor's height and let it scroll instead of growing the page:
+
+```tsx
+<Editor defaultValue={longHtml}>
+  <Editor.Toolbar />
+  <Editor.Content maxHeight={320} />
+</Editor>
+```
+
+## useEditor Hook
+
+Access editor state and commands from a child component (typically used inside a custom toolbar):
+
+```tsx
+import { useEditor } from "@particle-academy/react-fancy";
+
+function CustomToolbarButtons() {
+  const { exec } = useEditor();
+  return (
+    <>
+      <button onClick={() => exec("bold")}>B</button>
+      <Editor.Toolbar.Separator />
+      <button onClick={() => exec("formatBlock", "h1")}>H1</button>
+    </>
+  );
+}
+```
+
+### EditorContextValue
+
+| Property | Type | Description |
+|----------|------|-------------|
+| exec | `(command: string, arg?: string) => void` | Execute a `document.execCommand`-style formatting command |
+| insertText | `(text: string) => void` | Insert text at the current cursor position |
+| wrapSelection | `(before: string, after: string) => void` | Wrap the selection with before/after strings |
+| contentRef | `RefObject<HTMLDivElement \| null>` | Ref to the editable content element |
+| outputFormat | `"html" \| "markdown"` | Current output format |
+| lineSpacing | `number` | Current line spacing |
+| placeholder | `string` | Current placeholder text |
+| extensions | `RenderExtension[]` | Merged render extensions (global + instance) |
+
+## Render Extensions
+
+Render extensions let you embed custom React components inline using tag names you choose (e.g., `<alert>`, `<questions>`, `<thinking>`). The same extensions work in both `Editor` and `ContentRenderer`.
+
+```tsx
+import type { RenderExtension, RenderExtensionProps } from "@particle-academy/react-fancy";
+
+function AlertRenderer({ content, attributes }: RenderExtensionProps) {
+  const variant = attributes.type || "info";
+  return <div className={`alert alert-${variant}`}>{content}</div>;
+}
+
+const extensions: RenderExtension[] = [
+  { tag: "alert", component: AlertRenderer },
+];
+
+<Editor extensions={extensions} defaultValue='<alert type="info">Hello</alert>'>
+  <Editor.Toolbar />
+  <Editor.Content />
+</Editor>
+```
+
+Register extensions globally with `registerExtension` (applies to all instances) or pass them per-instance via the `extensions` prop. Per-instance extensions are merged with global ones.
+
 ## Custom Toolbar
 
 ```tsx
 <Editor defaultValue="">
   <Editor.Toolbar>
-    <button onClick={() => exec("bold")}>B</button>
+    <CustomToolbarButtons />
     <Editor.Toolbar.Separator />
-    <button onClick={() => exec("italic")}>I</button>
+    <MoreButtons />
   </Editor.Toolbar>
   <Editor.Content />
 </Editor>

package/docs/Icon.md

@@ -5,7 +5,13 @@ An icon container that resolves icon names from registered icon sets (Lucide by
 ## Import
 
 ```tsx
-import { Icon, registerIconSet, configureIcons } from "@particle-academy/react-fancy";
+import {
+  Icon,
+  registerIcons,
+  registerIconSet,
+  configureIcons,
+} from "@particle-academy/react-fancy";
+import type { IconSet } from "@particle-academy/react-fancy";
 ```
 
 ## Basic Usage
@@ -26,9 +32,29 @@ Also extends all native `<span>` HTML attributes. When `children` are provided,
 
 ## Icon Configuration
 
+Three APIs configure icons: `registerIcons` for tree-shakeable individual Lucide icons, `registerIconSet` for custom icon libraries, and `configureIcons` for choosing the default set.
+
+### registerIcons
+
+Register individual icon components into the built-in `"lucide"` set by their kebab-case name. This is the recommended way to opt into tree-shaking — only the icons you import are bundled.
+
+```tsx
+import { registerIcons } from "@particle-academy/react-fancy";
+import { Home, Settings, Mail } from "lucide-react";
+
+registerIcons({ Home, Settings, Mail });
+
+// Then use them via their kebab-case names:
+<Icon name="home" />
+<Icon name="settings" />
+<Icon name="mail" />
+```
+
+Call this once at app startup (e.g., in `setup-icons.ts`).
+
 ### registerIconSet
 
-Register a custom icon set by name.
+Register a complete custom icon set by name.
 
 ```tsx
 import { registerIconSet } from "@particle-academy/react-fancy";

package/docs/Input.md

@@ -42,12 +42,12 @@ Extends all native `<input>` attributes (except `size`, `type`, `prefix`).
 ### With leading icon
 
 ```tsx
-import { Search } from "lucide-react";
+import { Input, Icon } from "@particle-academy/react-fancy";
 
 <Input
   label="Search"
   type="search"
-  leading={<Search size={16} />}
+  leading={<Icon name="search" size="sm" />}
   placeholder="Search..."
 />
 ```

package/docs/Menu.md

@@ -11,10 +11,12 @@ import { Menu } from "@particle-academy/react-fancy";
 ## Basic Usage
 
 ```tsx
+import { Menu, Icon } from "@particle-academy/react-fancy";
+
 <Menu>
-  <Menu.Item href="/" active>Home</Menu.Item>
-  <Menu.Item href="/about">About</Menu.Item>
-  <Menu.Submenu label="Products" icon={<BoxIcon />}>
+  <Menu.Item href="/" icon={<Icon name="home" size="sm" />} active>Home</Menu.Item>
+  <Menu.Item href="/about" icon={<Icon name="info" size="sm" />}>About</Menu.Item>
+  <Menu.Submenu label="Products" icon={<Icon name="box" size="sm" />}>
     <Menu.Item href="/products/widgets">Widgets</Menu.Item>
     <Menu.Item href="/products/gadgets">Gadgets</Menu.Item>
   </Menu.Submenu>
@@ -64,8 +66,26 @@ import { Menu } from "@particle-academy/react-fancy";
 
 ```tsx
 <Menu orientation="horizontal">
-  <Menu.Item href="/" active>Home</Menu.Item>
-  <Menu.Item href="/docs">Docs</Menu.Item>
-  <Menu.Item href="/pricing" badge={<span>New</span>}>Pricing</Menu.Item>
+  <Menu.Item href="/" icon={<Icon name="home" size="sm" />} active>Home</Menu.Item>
+  <Menu.Item href="/docs" icon={<Icon name="book" size="sm" />}>Docs</Menu.Item>
+  <Menu.Item href="/pricing" badge={<Badge size="sm">New</Badge>}>Pricing</Menu.Item>
+</Menu>
+```
+
+## Grouped Vertical Menu
+
+```tsx
+<Menu orientation="vertical">
+  <Menu.Group label="Main">
+    <Menu.Item icon={<Icon name="home" size="sm" />} active>Dashboard</Menu.Item>
+    <Menu.Item icon={<Icon name="mail" size="sm" />} badge={<Badge size="sm">3</Badge>}>Inbox</Menu.Item>
+  </Menu.Group>
+  <Menu.Group label="Settings">
+    <Menu.Submenu label="Configuration" icon={<Icon name="settings" size="sm" />} defaultOpen>
+      <Menu.Item>General</Menu.Item>
+      <Menu.Item>Security</Menu.Item>
+    </Menu.Submenu>
+    <Menu.Item icon={<Icon name="palette" size="sm" />} disabled>Theme (coming soon)</Menu.Item>
+  </Menu.Group>
 </Menu>
 ```

package/docs/MobileMenu.md

@@ -8,6 +8,12 @@ Mobile navigation components with two variants: a slide-out flyout panel and a f
 import { MobileMenu } from "@particle-academy/react-fancy";
 ```
 
+## Import
+
+```tsx
+import { MobileMenu, Icon } from "@particle-academy/react-fancy";
+```
+
 ## Flyout
 
 A slide-out panel from the left or right edge.
@@ -18,9 +24,9 @@ const [open, setOpen] = useState(false);
 <button onClick={() => setOpen(true)}>Menu</button>
 
 <MobileMenu.Flyout open={open} onClose={() => setOpen(false)} side="left" title="Menu">
-  <MobileMenu.Item href="/" icon={<HomeIcon />} active>Home</MobileMenu.Item>
-  <MobileMenu.Item href="/about" icon={<InfoIcon />}>About</MobileMenu.Item>
-  <MobileMenu.Item href="/contact" icon={<MailIcon />}>Contact</MobileMenu.Item>
+  <MobileMenu.Item href="/" icon={<Icon name="home" />} active>Home</MobileMenu.Item>
+  <MobileMenu.Item href="/about" icon={<Icon name="info" />}>About</MobileMenu.Item>
+  <MobileMenu.Item href="/contact" icon={<Icon name="mail" />}>Contact</MobileMenu.Item>
 </MobileMenu.Flyout>
 ```
 
@@ -30,9 +36,9 @@ A fixed bottom navigation bar for mobile.
 
 ```tsx
 <MobileMenu.BottomBar>
-  <MobileMenu.Item href="/" icon={<HomeIcon />} active>Home</MobileMenu.Item>
-  <MobileMenu.Item href="/search" icon={<SearchIcon />}>Search</MobileMenu.Item>
-  <MobileMenu.Item href="/profile" icon={<UserIcon />}>Profile</MobileMenu.Item>
+  <MobileMenu.Item href="/" icon={<Icon name="home" />} active>Home</MobileMenu.Item>
+  <MobileMenu.Item href="/search" icon={<Icon name="search" />}>Search</MobileMenu.Item>
+  <MobileMenu.Item href="/profile" icon={<Icon name="user" />}>Profile</MobileMenu.Item>
 </MobileMenu.BottomBar>
 ```
 

package/docs/Sidebar.md

@@ -11,9 +11,11 @@ import { Sidebar } from "@particle-academy/react-fancy";
 ## Basic Usage
 
 ```tsx
+import { Sidebar, Icon } from "@particle-academy/react-fancy";
+
 <Sidebar>
-  <Sidebar.Item href="/" icon={<HomeIcon />} active>Home</Sidebar.Item>
-  <Sidebar.Item href="/settings" icon={<GearIcon />}>Settings</Sidebar.Item>
+  <Sidebar.Item href="/" icon={<Icon name="home" size="sm" />} active>Home</Sidebar.Item>
+  <Sidebar.Item href="/settings" icon={<Icon name="settings" size="sm" />}>Settings</Sidebar.Item>
   <Sidebar.Group label="Projects">
     <Sidebar.Item href="/project-a">Project A</Sidebar.Item>
     <Sidebar.Item href="/project-b">Project B</Sidebar.Item>
@@ -77,12 +79,30 @@ import { Sidebar } from "@particle-academy/react-fancy";
 const [collapsed, setCollapsed] = useState(false);
 
 <Sidebar collapsed={collapsed} onCollapsedChange={setCollapsed} collapseMode="icons">
-  <Sidebar.Item icon={<HomeIcon />}>Dashboard</Sidebar.Item>
-  <Sidebar.Item icon={<UsersIcon />}>Users</Sidebar.Item>
-  <Sidebar.Submenu label="Reports" icon={<ChartIcon />} defaultOpen>
+  <Sidebar.Item icon={<Icon name="home" size="sm" />}>Dashboard</Sidebar.Item>
+  <Sidebar.Item icon={<Icon name="users" size="sm" />}>Users</Sidebar.Item>
+  <Sidebar.Submenu label="Reports" icon={<Icon name="bar-chart-3" size="sm" />} defaultOpen>
     <Sidebar.Item>Monthly</Sidebar.Item>
     <Sidebar.Item>Yearly</Sidebar.Item>
   </Sidebar.Submenu>
   <Sidebar.Toggle />
 </Sidebar>
 ```
+
+### collapseMode
+
+- `"icons"` (default) — only the icon is shown when collapsed; falls back to the first 3 letters if no icon is provided
+- `"letters"` — the first 3 letters of the label are always shown
+
+## useSidebar Hook
+
+Access collapsed state from any child component:
+
+```tsx
+import { useSidebar } from "@particle-academy/react-fancy";
+
+function CollapseAware() {
+  const { collapsed, setCollapsed } = useSidebar();
+  return <button onClick={() => setCollapsed(!collapsed)}>Toggle</button>;
+}
+```

package/package.json

@@ -1,7 +1,13 @@
 {
   "name": "@particle-academy/react-fancy",
-  "version": "2.2.0",
+  "version": "2.2.1",
   "description": "React UI component library — React port of the fancy-flux Blade component library",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Particle-Academy/react-fancy.git"
+  },
+  "homepage": "https://github.com/Particle-Academy/react-fancy#readme",
+  "bugs": "https://github.com/Particle-Academy/react-fancy/issues",
   "type": "module",
   "main": "./dist/index.cjs",
   "module": "./dist/index.js",