osameditor 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 osameditor authors
+
+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

@@ -0,0 +1,452 @@
+# osameditor
+
+A **configurable rich text editor** for **React** and **Next.js** (TypeScript or
+JavaScript), built for blog platforms.
+
+- 🧩 **Pick exactly the tools you want** — want only H2 + H3, bold and a link? Pass
+  a list. Every button is opt-in.
+- 🖼️ **Media built in** — image upload / by-URL / **your own library**, resize,
+  **float text around the image**, caption, alt & title, **link an image**,
+  YouTube, Instagram, video (incl. HLS), generic embeds, PDF documents.
+- ☁️ **Storage = OsamStorage or your own API** — chunked uploads via
+  [**OsamStorage**](https://www.npmjs.com/package/osamstorage), or POST to your
+  **own backend / VPS**. Plus a GET/POST **media-library** hook for a reusable
+  image list.
+- 🖥️ **Fullscreen**, **HTML source view**, and **Custom HTML/CSS blocks** with a
+  built-in sanitizer.
+- 🧑‍💻 **Code blocks** with syntax highlighting + one-click **Copy**.
+- 🎨 **Recolor everything from props** — surface, toolbar, buttons — or via CSS
+  variables. Light/dark aware. Ships `"use client"`, SSR-safe for the Next.js
+  App Router.
+
+Built on [TipTap](https://tiptap.dev/) / ProseMirror.
+
+---
+
+## Install
+
+```bash
+npm install osameditor
+# optional — only if you upload through OsamStorage:
+npm install osamstorage
+# optional — only if you embed HLS (.m3u8) video, e.g. OsamStorage-processed video:
+npm install hls.js
+```
+
+`react` and `react-dom` (>=17) are peer dependencies.
+
+---
+
+## Quick start
+
+### Next.js (App Router)
+
+```tsx
+// app/write/editor.tsx
+"use client";
+
+import { useState } from "react";
+import { OsamEditor } from "osameditor";
+import "osameditor/styles.css";
+
+export default function Editor() {
+  const [html, setHtml] = useState("<p>Hello world</p>");
+
+  return (
+    <OsamEditor
+      toolbar="blog"
+      defaultValue={html}
+      onChange={(next) => setHtml(next)}
+    />
+  );
+}
+```
+
+### Plain React (Vite / CRA)
+
+Same component, same import. No extra setup — just render `<OsamEditor />` inside
+a client component.
+
+---
+
+## Choose what goes in your toolbar
+
+Pass `toolbar` an **array of items**, a **preset name**, or `false` (no toolbar).
+
+```tsx
+// Only what you need:
+<OsamEditor toolbar={["h2", "h3", "bold", "italic", "link", "bulletList"]} />
+
+// A preset:
+<OsamEditor toolbar="minimal" />   // "full" | "blog" | "basic" | "minimal"
+
+// Group with dividers and a right-aligned section:
+<OsamEditor
+  toolbar={["headings", "|", "bold", "italic", "spacer", "undo", "redo"]}
+/>
+```
+
+**The toolbar drives the schema.** If `image` / `youtube` / `codeBlock` etc. aren't
+in your toolbar (and you didn't enable them explicitly), those node types aren't
+even loaded — smaller schema, cleaner output. `"|"` is a divider, `"spacer"`
+pushes the rest to the right.
+
+<details>
+<summary><strong>Every toolbar item</strong></summary>
+
+| Group | Items |
+|---|---|
+| **Formatting** | `bold` `italic` `underline` `strike` `code` `color` `highlight` `clearFormatting` |
+| **Headings** | `headings` (dropdown) · or individual `h1` `h2` `h3` `h4` `h5` `h6` · `paragraph` |
+| **Alignment** | `alignLeft` `alignCenter` `alignRight` `alignJustify` `hardBreak` |
+| **Lists** | `bulletList` `orderedList` `taskList` `indent` `outdent` |
+| **Links** | `link` `unlink` |
+| **Quotes & code** | `blockquote` `codeBlock` |
+| **Media** | `image` `imageUrl` `mediaLibrary` `youtube` `instagram` `video` `embed` `pdf` |
+| **View / advanced** | `fullscreen` `source` (HTML view) `customHtml` (HTML block) |
+| **Misc** | `horizontalRule` `undo` `redo` |
+| **Layout** | `\|` (divider) `spacer` (push rest right) |
+
+</details>
+
+### Restrict heading levels
+
+```tsx
+<OsamEditor toolbar={["headings", "bold"]} heading={{ levels: [2, 3] }} />
+```
+
+Using `h2` / `h3` items in the toolbar does this automatically:
+
+```tsx
+<OsamEditor toolbar={["h2", "h3", "bold"]} />   // schema allows only H2 & H3
+```
+
+---
+
+## Storage / uploads
+
+The editor never talks to a backend directly — it calls one **`UploadHandler`**.
+Three ways to provide one:
+
+### 1. OsamStorage (images → WebP, video → HLS, PDF)
+
+```tsx
+import { OsamEditor, createOsamStorageUploader } from "osameditor";
+
+const storage = createOsamStorageUploader({
+  // Same contract as the osamstorage SDK — point at your token route.
+  getToken: async () => (await fetch("/api/osam-token", { method: "POST" }).then(r => r.json())).token,
+  resolveUrl: (data) => data?.url ?? data?.fileUrl,       // map the merge response → URL
+  resolvePoster: (data) => data?.poster,                  // optional (video thumbnail)
+});
+
+<OsamEditor toolbar="blog" upload={{ handler: storage }} />
+```
+
+Your token route keeps `MAIN_TOKEN` on the server — see
+[`example/nextjs-api-token-route.ts`](example/nextjs-api-token-route.ts).
+
+### 2. Your own VPS / server
+
+```tsx
+import { OsamEditor, createVpsUploader } from "osameditor";
+
+const uploader = createVpsUploader({
+  endpoint: "/api/upload",                       // multipart/form-data POST, field "file"
+  headers: () => ({ Authorization: `Bearer ${token}` }),
+  resolveUrl: (res) => res.url,                  // shape of YOUR JSON response
+});
+
+<OsamEditor toolbar="blog" upload={{ handler: uploader, maxSize: 25 * 1024 * 1024 }} />
+```
+
+Reports real upload progress (`XHR`) and supports cancellation.
+
+### 3. Any custom handler
+
+```tsx
+const uploader: UploadHandler = async (file, { kind, onProgress, signal }) => {
+  const url = await myS3PresignedUpload(file, onProgress, signal);
+  return { url, kind };
+};
+```
+
+```ts
+type UploadHandler = (
+  file: File,
+  ctx: { kind: "image" | "video" | "pdf"; onProgress?: (pct: number) => void; signal?: AbortSignal },
+) => Promise<{ url: string; kind?: "image" | "video" | "pdf"; poster?: string; width?: number; height?: number }>;
+```
+
+> **No handler?** Upload buttons disappear, but `imageUrl` / `youtube` / `embed`
+> (by-URL) still work.
+
+---
+
+## Feature configuration
+
+```tsx
+<OsamEditor
+  toolbar="full"
+  placeholder="Write something…"
+  dir="ltr"
+
+  heading={{ levels: [1, 2, 3] }}
+
+  link={{
+    allowTargetBlank: true,        // "open in new tab" checkbox
+    allowRelAttributes: true,      // nofollow / sponsored checkboxes
+    defaultRel: "noopener noreferrer nofollow",
+    protocols: ["http", "https", "mailto", "tel"],
+    autolink: true,
+  }}
+
+  color={{ colors: ["#111", "#e11", "#1a1"] }}
+  highlight={{ highlights: ["#fff3a3", "#a5d8ff"] }}
+
+  image={{
+    resizable: true,   // drag-resize (10–100% of the row)
+    caption: true,      // <figcaption>
+    align: true,        // left / right FLOAT (text wraps), center = block
+    link: true,         // wrap the image in <a>
+    accept: "image/*",
+    maxSize: 8 * 1024 * 1024,
+  }}
+
+  upload={{ handler: storage, video: true, pdf: true }}
+
+  embed={{
+    allowedHosts: ["youtube.com", "vimeo.com", "codepen.io"],  // "*" = any
+    defaultRatio: "16/9",
+  }}
+
+  codeBlock={{ copyButton: true, defaultLanguage: "tsx" }}  // or just `codeBlock`
+  taskList
+  horizontalRule
+
+  branding                     // "powered by osamtech.com" credit (on by default)
+  defaultFullscreen={false}
+/>
+```
+
+Set any feature to `false` to force it off; omit it and it's inferred from the
+toolbar.
+
+### Image + text layout
+
+`left` / `right` alignment **float** the image, so when the reader shrinks it to
+10–20% the body text flows into the freed space:
+
+```
+┌────────┐  Your paragraph text wraps around the floated
+│  img   │  image and fills the rest of the row instead of
+│ (20%)  │  leaving it blank. Pick "center" for a normal
+└────────┘  full-width block with text above and below.
+```
+
+Toolbar controls appear on the selected image: float ⇤ / ⇔ / ⇥, size
+(25/50/75/100%), reset, and 🔗 to link it.
+
+### Image library (your own GET/POST API)
+
+Give the editor your own endpoints and users get a **"Library" tab** of their
+past uploads:
+
+```tsx
+<OsamEditor
+  toolbar={["image", "mediaLibrary", /* … */]}
+  upload={{ handler: storage }}
+  mediaLibrary={{
+    list: "/api/my-images",             // GET → ["https://…", …] or [{ url, name, thumbnail }]
+    save: "/api/my-images",             // POST { url } after each upload
+    headers: () => ({ Authorization: `Bearer ${token}` }),
+    // resolveList: (res) => res.data,  // if your GET shape differs
+  }}
+/>
+```
+
+`list` / `save` can also be functions (`() => Promise<string[]>` / `(url) => …`).
+
+### HTML / inline CSS
+
+```tsx
+<OsamEditor
+  html={{
+    sourceView: true,       // toolbar "</>" toggles the whole post to an HTML textarea
+    customBlock: true,      // insert discrete "Custom HTML/CSS" blocks
+    styleAttributes: true,  // keep style="" on paragraphs / headings / quotes
+    classAttributes: true,  // keep class / id
+    allowStyleTags: false,  // <style> blocks (<script> is ALWAYS stripped)
+  }}
+/>
+// shorthand: html   (all of the above with defaults)
+```
+
+A built-in sanitizer removes `<script>`, inline `on*` handlers and
+`javascript:` URLs on every source-view apply, custom-block render and paste.
+
+### Fullscreen
+
+Add `"fullscreen"` to the toolbar (it's in the `full` / `blog` presets). The
+editor goes `position: fixed` and fills the entire viewport — a 32″ screen gets
+a 32″ editor. `Esc` exits. Control it with `fullscreen` / `onFullscreenChange`
+if you want.
+
+### Localization
+
+```tsx
+<OsamEditor labels={{ bold: "Gras", "dialog.insert": "Insérer", link: "Lien" }} />
+```
+
+---
+
+## Controlled vs uncontrolled
+
+```tsx
+// Uncontrolled (recommended for big documents)
+<OsamEditor defaultValue={initialHtml} onChange={(html, { json }) => save(json)} />
+
+// Controlled
+<OsamEditor value={html} onChange={setHtml} />
+```
+
+`onChange(html, { json, editor })` — `html` for storage/rendering, `json` (TipTap
+doc) for a structured store.
+
+---
+
+## Rendering saved content on your site
+
+```tsx
+import { OsamContent } from "osameditor";
+import "osameditor/styles.css";
+
+export default function Post({ html }: { html: string }) {
+  return <OsamContent html={html} />;   // same look as the editor
+}
+```
+
+`OsamContent` also upgrades `.m3u8` videos with `hls.js` (if installed) outside
+Safari. Pass `hls={false}` to skip.
+
+---
+
+## Advanced — build your own UI
+
+```tsx
+import { useOsamEditor, Toolbar } from "osameditor";
+import { EditorContent } from "@tiptap/react";
+
+function MyEditor() {
+  const { editor, config } = useOsamEditor({
+    toolbar: ["bold", "italic", "h2"],
+    content: "<p>hi</p>",
+    onUpdate: ({ html }) => console.log(html),
+  });
+
+  return (
+    <>
+      <MyFloatingMenu editor={editor} />
+      <Toolbar editor={editor} config={config} />
+      <EditorContent editor={editor} />
+    </>
+  );
+}
+```
+
+Add raw TipTap extensions:
+
+```tsx
+import Mention from "@tiptap/extension-mention";
+
+<OsamEditor extensions={(base) => [...base, Mention.configure({ /* … */ })]} />
+```
+
+`ResizableImage`, `Embed`, `CodeBlock`, `CustomHtml`, `PreserveAttributes`,
+`resolveEmbed`, `buildExtensions`, `resolveConfig`, `sanitizeHtml`,
+`themeToStyle`, `loadMediaLibrary` are also exported.
+
+---
+
+## Props
+
+| Prop | Type | Default |
+|---|---|---|
+| `toolbar` | `ToolbarItem[] \| "full" \| "blog" \| "basic" \| "minimal" \| false` | `"full"` |
+| `defaultValue` / `value` | `string \| JSONContent` | `""` |
+| `onChange` | `(html, { json, editor }) => void` | — |
+| `onReady` | `(editor) => void` | — |
+| `editable` | `boolean` | `true` |
+| `autofocus` | `boolean \| "start" \| "end" \| number` | `false` |
+| `placeholder` | `string` | `"Write something…"` |
+| `minHeight` | `number \| string` | `260` |
+| `toolbarPosition` | `"top" \| "bottom" \| "none"` | `"top"` |
+| `stickyToolbar` | `boolean` | `false` |
+| `fullscreen` / `defaultFullscreen` / `onFullscreenChange` | `boolean` / `boolean` / `(b) => void` | `false` |
+| `theme` | `OsamEditorTheme` (surface / toolbar / button colors) | — |
+| `branding` | `boolean` — show "powered by osamtech.com" | `true` |
+| `mediaLibrary` | `{ list, save?, headers?, resolveList? }` | — |
+| `html` | `boolean \| { sourceView, customBlock, styleAttributes, classAttributes, allowStyleTags }` | inferred |
+| `heading` `link` `color` `highlight` `image` `embed` `upload` `codeBlock` `taskList` `blockquote` `horizontalRule` `textAlign` | see [Feature configuration](#feature-configuration) | inferred |
+| `extensions` | `AnyExtension[] \| (base) => AnyExtension[]` | — |
+| `starterKit` | `object` | `{}` |
+| `labels` | `Record<string, string>` | — |
+| `dir` | `"ltr" \| "rtl"` | `"ltr"` |
+| `className` / `style` | — | — |
+
+---
+
+## Theming
+
+**From props** — every editor instance can be recolored (users can pick their
+own colors):
+
+```tsx
+<OsamEditor
+  theme={{
+    background: "#ffffff",
+    foreground: "#1a1a1a",
+    accent: "#7c3aed",
+    border: "#e5e7eb",
+    radius: 12,
+    fontFamily: "'Inter', sans-serif",
+    // toolbar + buttons
+    toolbarBackground: "#faf5ff",
+    buttonColor: "#4b5563",
+    buttonHoverBackground: "#f3e8ff",
+    buttonActiveBackground: "#ede9fe",
+    buttonActiveColor: "#6d28d9",
+    contentBackground: "#ffffff",
+    codeBackground: "#f6f8fa",
+  }}
+/>
+```
+
+**From CSS** — the same knobs are CSS variables:
+
+```css
+.osam-editor {
+  --osam-accent: #7c3aed;
+  --osam-toolbar-bg: #faf5ff;
+  --osam-btn-fg: #4b5563;
+  --osam-radius: 12px;
+}
+/* force a theme regardless of system: */
+.osam-editor[data-theme="dark"] { /* … */ }
+```
+
+---
+
+## Notes
+
+- **Next.js:** the package is a client module. Import `<OsamEditor />` from a
+  `"use client"` component (or `next/dynamic` with `ssr: false`). Server rendering
+  is safe; it just mounts empty and hydrates.
+- **Output HTML** uses semantic markup: `<figure><img><figcaption>` for images,
+  `<div data-osam-embed><iframe|video|object></div>` for media — renders fine
+  without any JS via `OsamContent` or a plain container.
+- Only images, video and PDF are accepted for upload (matches OsamStorage).
+
+## License
+
+MIT