axiom-editor 1.0.2 → 1.0.4

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Aditya
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,99 +1,231 @@
 # AxiomEditor
 
-A premium, modular narrative architecture block editor built on React, Tiptap, and Tailwind CSS. 
+A premium, modular narrative architecture block editor built on **React**, **Tiptap**, and **Tailwind CSS**.
 
-AxiomEditor provides a ready-to-use monolithic editor wrapper while remaining completely modular, allowing developers to construct custom editing layouts by arranging the core providers, toolbars, and canvas elements.
+AxiomEditor is designed for modern developers who need a gorgeous, distraction-free editing interface out of the box, but require the flexibility to tear it down and build custom compositions. By default, it ships with a dark-mode obsidian aesthetic, custom multi-color highlights, drag-and-drop media embeds, and clean AST rendering support.
 
 ---
 
-## Features
+## Key Features
 
-- 📝 **Tiptap Core Integration:** Clean, extensible rich-text editing.
-- 🎨 **Themeable Design System:** Easily toggle between dark, light, or custom color schemes using CSS Custom Properties (CSS variables).
-- 🧩 **Modular Architecture:** Arrange toolbars, scroll windows, and modals wherever they fit best in your layout.
-- 🖋️ **Advanced Multi-Color Styling:** Highlight, bold, underline, or strike-through words with custom colors concurrently.
-- 🖼️ **Media Embeds:** Built-in support for YouTube, X (Twitter), Instagram, and inline image uploads.
-- 🤖 **Developer AST Output:** Export and render raw serialized JSON nodes dynamically.
+*   ✨ **Monolithic & Modular APIs:** Use the all-in-one `<AxiomEditor />` component for instant setup, or compose custom layouts using `<AxiomEditorProvider />`, `<AxiomToolbar />`, and `<AxiomContent />`.
+*   🚀 **Advanced Slash Commands:** Press `/` on a blank line to trigger a fluid slash command dropdown with smooth transitions and keyboard navigation support.
+*   🎨 **Full Design Token Control:** Every color, border, and background is mapped to standard CSS custom properties. Customize the editor to light mode, amber mode, or your corporate brand with single CSS overrides.
+*   🌈 **Simultaneous Multi-Color Highlighting:** Support for concurrently underlining or striking-through text in multiple custom colors (Bone, Amber, Charcoal, Obsidian, and Accent Primary).
+*   🖼️ **Advanced Media System:** Drop-in embeds for **YouTube** videos, **X (Twitter)** posts, **Instagram** reels, and inline image uploads with resizing handles and captions.
+*   📊 **Sync & Word Count Indicator:** Minimalist bottom status bar showing word counts and a Pulsing Sync indicator representing save-states.
+*   💾 **Serialized JSON AST Parser:** Direct access to Tiptap JSON abstract syntax trees (AST) and a fast renderer component (`<AxiomJSONRenderer />`) to display them on user pages.
 
 ---
 
 ## Installation
 
-Install the package and its peer dependencies in your React project:
+Install the package and its required peer dependencies in your React project:
 
 ```bash
 npm install axiom-editor lucide-react react react-dom
 ```
 
+### Import Styles
+Make sure to import the editor stylesheet in your main entry file (e.g., `main.tsx` or `_app.tsx`):
+
+```tsx
+import 'axiom-editor/style.css';
+```
+
 ---
 
-## Quick Start
+## Implementation Guide
 
-Import the editor and its stylesheet, and mount it in your React application:
+### 1. Quick Start (Monolithic Layout)
+
+For standard setups, use the monolithic wrapper which includes a top sticky toolbar, a fixed-height editor canvas, and automated media modal routing.
 
 ```tsx
 import React, { useState } from 'react';
 import { AxiomEditor } from 'axiom-editor';
-import 'axiom-editor/style.css'; // Don't forget to import the CSS!
+import type { JSONContent } from '@tiptap/core';
+import 'axiom-editor/style.css';
 
 function App() {
-  const [content, setContent] = useState('<p>Welcome to AxiomEditor!</p>');
+  const [content, setContent] = useState<JSONContent | string>('<p>Write your narrative here...</p>');
 
   return (
-    <div style={{ padding: '2rem', background: '#121212' }}>
-      <AxiomEditor 
-        initialContent={content}
-        onChange={(json, html) => setContent(html)}
-      />
+    <div className="min-h-screen bg-neutral-900 p-8 flex items-center justify-center">
+      <div className="w-full max-w-4xl bg-neutral-950 p-6 rounded-2xl border border-neutral-800">
+        <AxiomEditor 
+          initialContent={content}
+          onChange={(json, html) => {
+            console.log('JSON AST:', json);
+            console.log('HTML String:', html);
+          }}
+        />
+      </div>
     </div>
   );
 }
+
+export default App;
+```
+
+---
+
+### 2. Advanced Modular UI Composition
+
+If you want a custom layout—such as placing the toolbar at the bottom, embedding the editor canvas in a floating card, or building custom sidebar controls—you can compose the subcomponents directly.
+
+All child components inside `<AxiomEditorProvider />` share the editor context automatically via the `useAxiomEditor` hook.
+
+```tsx
+import React from 'react';
+import { 
+  AxiomEditorProvider, 
+  AxiomToolbar, 
+  AxiomContent, 
+  MediaMenu, 
+  useAxiomEditor 
+} from 'axiom-editor';
+
+function CustomSyncIndicator() {
+  const { editor } = useAxiomEditor();
+  if (!editor) return null;
+  
+  return (
+    <div className="text-xs text-neutral-500 font-mono">
+      Words: {editor.storage.characterCount.words()}
+    </div>
+  );
+}
+
+function CustomLayoutEditor() {
+  return (
+    <AxiomEditorProvider initialContent="Composition is key.">
+      <div className="flex flex-col gap-6 p-4 border rounded-3xl bg-black">
+        
+        {/* Render Canvas First */}
+        <div className="p-4 bg-zinc-900/50 rounded-2xl">
+          <AxiomContent />
+        </div>
+        
+        {/* Render Toolbar Below the Canvas */}
+        <div className="p-2 border-t border-zinc-800 flex items-center justify-between">
+          <AxiomToolbar />
+          <CustomSyncIndicator />
+        </div>
+        
+        {/* The Media Insertion Modals */}
+        <MediaMenu />
+      </div>
+    </AxiomEditorProvider>
+  );
+}
+```
+
+---
+
+### 3. Native Image Upload Handler
+
+Configure the `uploadImage` hook to handle local file selection and return a secure uploaded image URL. Below is a production-ready example integrating with **Cloudinary**:
+
+```tsx
+const handleImageUpload = async (file: File): Promise<string> => {
+  const formData = new FormData();
+  formData.append('file', file);
+  formData.append('upload_preset', 'your_unsigned_preset'); // Replace with your preset
+  formData.append('cloud_name', 'your_cloudinary_cloud_name'); // Replace with your cloud name
+
+  const response = await fetch(
+    `https://api.cloudinary.com/v1_1/your_cloudinary_cloud_name/image/upload`,
+    {
+      method: 'POST',
+      body: formData,
+    }
+  );
+
+  if (!response.ok) {
+    throw new Error('Image upload failed');
+  }
+
+  const result = await response.json();
+  return result.secure_url; // Returns the public hosting URL for Tiptap
+};
+
+// Usage:
+// <AxiomEditor uploadImage={handleImageUpload} ... />
 ```
 
 ---
 
 ## Custom Theming
 
-AxiomEditor is styled using Tailwind classes mapped internally to CSS custom properties. By default, it runs in a sleek dark theme. 
+AxiomEditor namespaced classes are bound to CSS variables, preventing compilation purges in host projects and ensuring complete customizability. By default, it features a rich dark-mode theme. 
 
-To change the theme or create your own, simply target the `.axiom-editor-wrapper` selector in your own CSS and override the custom properties:
+To override colors, target the `.axiom-editor-wrapper` wrapper in your CSS:
 
-### Example: Light Mode Theme
 ```css
+/* Custom Light Mode Theme */
 .axiom-editor-wrapper {
-  --axiom-bg: #ffffff;          /* Editor background */
-  --axiom-bg-card: #f4f4f5;     /* Dropdown backgrounds */
-  --axiom-text: #09090b;        /* Main text color */
-  --axiom-text-muted: #71717a;  /* Subtitles & placeholders */
-  --axiom-border: #e4e4e7;      /* Borders & dividers */
-  --axiom-primary: #ef4444;     /* Active highlights & accents */
+  --axiom-bg: #ffffff;
+  --axiom-bg-card: #f4f4f5;
+  --axiom-text: #09090b;
+  --axiom-text-muted: #71717a;
+  --axiom-border: #e4e4e7;
+  --axiom-border-separator: #d4d4d8;
+  --axiom-primary: #f59e0b; /* Amber accent highlight */
+  --axiom-primary-text: #09090b;
+  --axiom-primary-text-muted: #d97706;
+  --axiom-button-active: #f3f4f6;
+  --axiom-button-active-text: #0f172a;
 }
 ```
 
+### Full Token References
+
+| CSS Variable | Description | Default Dark Theme Value |
+| :--- | :--- | :--- |
+| `--axiom-bg` | Main editor viewport background | `#0f0f10` (Obsidian black) |
+| `--axiom-bg-card` | Menus, popups, and modal background | `#18181b` (Charcoal zinc) |
+| `--axiom-text` | Body and header text | `#fafafa` (Bone white) |
+| `--axiom-text-muted` | Secondary indicators, placeholders | `#71717a` (Steel gray) |
+| `--axiom-border` | Component borders and wrappers | `rgba(250, 250, 250, 0.1)` |
+| `--axiom-border-separator` | Internal toolbar separator vertical rules | `rgba(250, 250, 250, 0.06)` |
+| `--axiom-primary` | Accent highlight color | `#ffbf00` (Amber gold) |
+| `--axiom-primary-text` | Text color on active primary buttons | `#0f0f10` |
+| `--axiom-primary-text-muted`| Colored highlights, word count save states | `#ffbf00` |
+| `--axiom-button-active` | Active formatting state buttons background | `rgba(250, 250, 250, 0.08)` |
+| `--axiom-button-active-text`| Active state icon/font color | `#ffbf00` |
+
 ---
 
-## Modular UI Composition
+## Rendering Content Outside the Editor
 
-If you do not want the standard top-toolbar layout, you can arrange the modular components inside the `AxiomEditorProvider` block:
+When saving content from the editor, you should store the **JSON AST** output. To render this JSON back on your website or article page with correct narrative styling, use `<AxiomJSONRenderer />`:
 
 ```tsx
-import { 
-  AxiomEditorProvider, 
-  AxiomToolbar, 
-  AxiomContent, 
-  MediaMenu 
-} from 'axiom-editor';
-
-function CustomEditor() {
+import React from 'react';
+import { AxiomJSONRenderer } from 'axiom-editor';
+
+const savedArticleJson = {
+  type: "doc",
+  content: [
+    {
+      type: "heading",
+      attrs: { level: 1 },
+      content: [{ type: "text", text: "Stunning Block Architectures" }]
+    },
+    {
+      type: "paragraph",
+      content: [{ type: "text", text: "This content was rendered directly from JSON AST." }]
+    }
+  ]
+};
+
+function ArticlePage() {
   return (
-    <AxiomEditorProvider initialContent="...">
-      <div className="my-custom-layout">
-        {/* Render editor canvas first, then toolbar on bottom */}
-        <AxiomContent />
-        <AxiomToolbar />
-        <MediaMenu />
-      </div>
-    </AxiomEditorProvider>
+    <article className="max-w-3xl mx-auto p-6 bg-zinc-950 text-white">
+      {/* Renders Tiptap nodes natively using React elements */}
+      <AxiomJSONRenderer content={savedArticleJson} />
+    </article>
   );
 }
 ```
@@ -102,26 +234,28 @@ function CustomEditor() {
 
 ## API Reference
 
-### `<AxiomEditor />`
-Out-of-the-box wrapper for ease-of-use.
-- `initialContent`: `string | JSONContent` - Initial document value.
-- `onChange`: `(json: JSONContent, html: string) => void` - Triggers when text changes.
-- `uploadImage`: `(file: File) => Promise<string>` - Async hook for uploading images.
-
-### `<AxiomEditorProvider />`
-Manages Tiptap instances and state. Essential for modular composition.
+### Props: `<AxiomEditor />` & `<AxiomEditorProvider />`
 
-### `<AxiomContent />`
-The text editing canvas. Automatically handles text scrolling and caps at 650px.
+| Prop | Type | Description |
+| :--- | :--- | :--- |
+| `initialContent` | `string \| JSONContent` | Initial markdown, HTML string, or parsed JSON AST document content. |
+| `onChange` | `(json: JSONContent, html: string) => void` | Event fires on text/formatting changes, returning the AST and HTML string. |
+| `uploadImage` | `(file: File) => Promise<string>` | Async file uploading function returning a public url path. |
+| `minHeightClass` | `string` | Optional CSS height class for canvas height configuration. |
+| `maxHeightClass` | `string` | Optional CSS height class for max constraints configuration. |
 
-### `<AxiomToolbar />`
-The responsive text formatting and media-insertion toolbar.
+### Component Exports
 
-### `<AxiomJSONRenderer />`
-A fast React component to render serialized Tiptap JSON AST directly to elements.
+*   **`<AxiomEditor />`**: Easy-to-use monolithic component with built-in toolbar, canvas, and insertion routing.
+*   **`<AxiomEditorProvider />`**: Context wrapper mapping editor instances. Required for composing custom layouts.
+*   **`<AxiomContent />`**: Editor editor content layer with scroll constraints and styling namespaces.
+*   **`<AxiomToolbar />`**: Text layout modifiers, formatting utilities, headers, and video hooks.
+*   **`<MediaMenu />`**: Absolute-overlay modal triggers handling links, tweets, YouTube, and image attachments.
+*   **`<AxiomJSONRenderer />`**: High performance rendering agent mapping saved JSON schemas back to React nodes.
+*   **`useAxiomEditor()`**: Custom hook retrieving current `{ editor }` instance variables and status.
 
 ---
 
 ## License
 
-MIT © Axiom Editor Team
+This project is licensed under the [MIT License](./LICENSE).