@particle-academy/react-fancy 4.13.0 → 4.14.0

package/docs/Editor.md

@@ -1,6 +1,6 @@
 # Editor
 
-A rich text editor built on `contentEditable` with a configurable toolbar, HTML or Markdown output, and support for render extensions.
+A rich text editor built on `contentEditable` with a configurable toolbar, HTML or Markdown output, a **Source** toggle for editing the raw markup, and support for render extensions.
 
 ## Import
 
@@ -30,6 +30,9 @@ import { Editor } from "@particle-academy/react-fancy";
 | lineSpacing | `number` | `1.6` | Line height for content area |
 | placeholder | `string` | - | Placeholder text |
 | extensions | `RenderExtension[]` | - | Per-instance render extensions (merged with global) |
+| showSource | `boolean` | - | Controlled source-view flag. When `true`, the content area shows the raw `value` (in `outputFormat`) in an editable `<textarea>` |
+| defaultShowSource | `boolean` | `false` | Initial source-view flag when uncontrolled |
+| onShowSourceChange | `(showSource: boolean) => void` | - | Fired when the Source toggle (or an agent) flips source view on/off |
 | className | `string` | - | Additional CSS classes |
 
 ### Editor.Toolbar
@@ -39,6 +42,7 @@ import { Editor } from "@particle-academy/react-fancy";
 | actions | `EditorAction[]` | - | Custom toolbar actions |
 | onAction | `(command: string) => void` | - | Custom action handler |
 | children | `ReactNode` | - | Custom toolbar content |
+| showSourceToggle | `boolean` | `true` | Append a Source toggle to the default toolbar. Ignored when `children` are supplied — custom toolbars compose their own `<Editor.SourceToggle />` |
 | className | `string` | - | Additional CSS classes |
 
 #### EditorAction
@@ -55,12 +59,24 @@ import { Editor } from "@particle-academy/react-fancy";
 
 A visual separator between toolbar groups. No props.
 
+### Editor.SourceToggle
+
+A toolbar button that reveals the raw HTML/Markdown behind the editor. It is appended to the default toolbar automatically; add it to a **custom** toolbar wherever you like. Reads `showSource` / `setShowSource` from context.
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| icon | `ReactNode` | `</>` | Toggle glyph/label |
+| title | `string` | `"Source"` | Accessible title in rich-text mode (click → source) |
+| activeTitle | `string` | `"Rich text"` | Accessible title in source mode (click → rich text) |
+| className | `string` | - | Additional CSS classes |
+
 ### Editor.Content
 
 | Prop | Type | Default | Description |
 |------|------|---------|-------------|
 | className | `string` | - | Additional CSS classes |
 | maxHeight | `number` | - | Max height in px before scrolling. When set, the content area becomes scrollable. |
+| sourceClassName | `string` | - | Classes applied to the raw-source `<textarea>` shown while source mode is on |
 
 ## Markdown Output
 
@@ -71,6 +87,42 @@ A visual separator between toolbar groups. No props.
 </Editor>
 ```
 
+## Source View
+
+The default toolbar includes a **Source** toggle (`</>`) on the right. Clicking it
+swaps the rich-text surface for a `<textarea>` showing the raw markup — HTML when
+`outputFormat="html"`, Markdown when `outputFormat="markdown"`. Edits made in the
+textarea flow straight to `value`; toggling back re-renders the rich-text surface
+from the edited source. Formatting buttons in the default toolbar are disabled
+while source view is open.
+
+```tsx
+// Source toggle is on by default — nothing to wire up.
+<Editor defaultValue="<p>Hello world</p>" outputFormat="html">
+  <Editor.Toolbar />
+  <Editor.Content />
+</Editor>
+
+// Opt out of the default toggle:
+<Editor.Toolbar showSourceToggle={false} />
+```
+
+Drive it yourself (controlled), or drop the toggle into a custom toolbar:
+
+```tsx
+<Editor
+  showSource={showSource}
+  onShowSourceChange={setShowSource}
+  defaultValue="<p>Hello</p>"
+>
+  <Editor.Toolbar>
+    <CustomToolbarButtons />
+    <Editor.SourceToggle className="ml-auto" />
+  </Editor.Toolbar>
+  <Editor.Content />
+</Editor>
+```
+
 ## Scrollable Editor
 
 Constrain the editor's height and let it scroll instead of growing the page:
@@ -113,6 +165,8 @@ function CustomToolbarButtons() {
 | lineSpacing | `number` | Current line spacing |
 | placeholder | `string` | Current placeholder text |
 | extensions | `RenderExtension[]` | Merged render extensions (global + instance) |
+| showSource | `boolean` | Whether the raw-source view is showing instead of the rich-text surface |
+| setShowSource | `(showSource: boolean) => void` | Toggle/set the raw-source view |
 
 ## Render Extensions
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@particle-academy/react-fancy",
-  "version": "4.13.0",
+  "version": "4.14.0",
   "description": "React UI component library for Human+ UX — controlled, agent-bridgeable primitives",
   "repository": {
     "type": "git",