@voilabs/mark 0.0.1

package/README.md

@@ -0,0 +1,728 @@
+# @voilabs/mark
+
+A modern React rich text editor library built on top of Tiptap, Tailwind CSS, Radix UI, and TypeScript.
+
+It is designed as a reusable package rather than a demo application, and ships a polished editing shell with a formatting toolbar, slash commands, media support, paragraph styles, theme switching, translations, and a Tailwind integration helper.
+
+## Table of Contents
+
+- [Overview](#overview)
+- [Quick Start](#quick-start)
+- [Highlights](#highlights)
+- [Prerequisites](#prerequisites)
+- [Installation](#installation)
+- [Tailwind Integration](#tailwind-integration)
+- [API Reference](#api-reference)
+- [Development Workflow](#development-workflow)
+- [Build and Distribution](#build-and-distribution)
+- [Dependency Management](#dependency-management)
+- [Architecture](#architecture)
+- [Project Structure](#project-structure)
+- [Tech Stack and Dependencies](#tech-stack-and-dependencies)
+- [Contributing](#contributing)
+- [License](#license)
+
+## Overview
+
+`@voilabs/mark` is a library-first editor package that exposes a ready-to-use `Editor` component and several supporting exports for advanced integration scenarios.
+
+The package focuses on:
+
+- rich text authoring with Tiptap
+- consistent, modern UI primitives using Radix UI
+- Tailwind-friendly styling and host-project theming
+- configurable typography and named paragraph styles
+- image and video insertion workflows
+- English and Turkish localization support
+- distribution as a typed library with multiple entry points
+
+The editor accepts initial content as HTML or Markdown, can auto-detect the incoming format, and emits content updates as Markdown through `onChange`.
+
+## Quick Start
+
+```ts
+import { Editor } from "@voilabs/mark";
+```
+
+### Basic Usage
+
+```tsx
+import { useState } from "react";
+import { Editor } from "@voilabs/mark";
+import translations from "@voilabs/mark/translations/en-US";
+
+export function ArticleEditor() {
+    const [value, setValue] = useState("# Hello world");
+
+    return (
+        <Editor
+            value={value}
+            format="auto"
+            theme="auto"
+            translations={translations}
+            onChange={setValue}
+        />
+    );
+}
+```
+
+### With Upload Support
+
+```tsx
+import { Editor } from "@voilabs/mark";
+
+async function uploadFile(file: File): Promise<{ url: string }> {
+    const formData = new FormData();
+    formData.append("file", file);
+
+    const response = await fetch("/api/upload", {
+        method: "POST",
+        body: formData,
+    });
+
+    if (!response.ok) {
+        throw new Error("Upload failed");
+    }
+
+    return response.json();
+}
+
+export function MediaEnabledEditor() {
+    return (
+        <Editor
+            value="Start writing..."
+            onUpload={uploadFile}
+            onChange={(markdown) => {
+                console.log(markdown);
+            }}
+        />
+    );
+}
+```
+
+### With Custom Paragraph Styles
+
+```tsx
+import {
+    Editor,
+    DEFAULT_PARAGRAPH_STYLES,
+    type ParagraphStyle,
+} from "@voilabs/mark";
+
+const customStyles: ParagraphStyle[] = [
+    ...DEFAULT_PARAGRAPH_STYLES,
+    {
+        id: "callout",
+        label: "Callout",
+        preview: "Callout",
+        type: "blockquote",
+        fontSize: "18px",
+        fontWeight: "600",
+        color: "#0f172a",
+    },
+];
+
+export function StyledEditor() {
+    return <Editor styles={customStyles} />;
+}
+```
+
+### With Translation Overrides
+
+```tsx
+import { Editor } from "@voilabs/mark";
+import trTR from "@voilabs/mark/translations/tr-TR";
+
+export function TurkishEditor() {
+    return (
+        <Editor
+            translations={{
+                ...trTR,
+                placeholder: "Yazmaya baslayin",
+            }}
+        />
+    );
+}
+```
+
+## Highlights
+
+### Editing Experience
+
+- Toolbar with undo/redo, headings, lists, quote, code block, inline marks, text alignment, links, highlight colors, font family, and font size controls
+- Slash command menu triggered by `/` for quick insertion of text blocks, headings, lists, images, tables, quotes, and code blocks
+- Word count footer with zoom controls and fullscreen toggle
+- Global drag handle for block insertion, duplication, reordering, anchor-link copying, color actions, and deletion
+
+### Media Support
+
+- Custom image node implementation with resize handles, crop mode, rotation, object-fit frame mode, pan controls, upload state, and alt text editing
+- Video node support for uploaded video insertion
+- Drag-and-drop and paste image upload handling when an `onUpload` callback is provided
+- Slash-command image insertion with file picker support or URL prompt fallback
+
+### Styling and Customization
+
+- Tailwind-based UI with overridable class slots via `EditorClassNames`
+- Built-in light and dark themes with persisted theme preference in cookie/localStorage when `theme="auto"`
+- Named paragraph styles with a Word-like quick style gallery
+- Right-click style editing with local persistence in `localStorage`
+- Translation override support through `translations`
+
+### Packaging
+
+- Typed library output generated by Vite and `vite-plugin-dts`
+- ESM, UMD, and declaration outputs under `dist`
+
+## Prerequisites
+
+Before using or developing this package, make sure you have:
+
+- Node.js 20 or newer recommended
+- npm 10 or newer recommended
+- a React application using React 19
+- TypeScript 5 if you want full type support
+
+If you plan to use the Tailwind helper export, your host application should also be configured for Tailwind CSS.
+
+## Installation
+
+### Library Consumers
+
+Install the package and its peer dependencies:
+
+```bash
+npm install @voilabs/mark react react-dom typescript
+```
+
+### Tailwind Plugin Consumers
+
+If you use the exported Tailwind plugin helper, also ensure your project has the typography plugin available:
+
+```bash
+npm install @tailwindcss/typography
+```
+
+### Repository Setup
+
+To work on the library itself:
+
+```bash
+bun install
+```
+
+## Tailwind Integration
+
+The editor UI is built with Tailwind utility classes. In host projects, the package export `@voilabs/mark/plugin` can help Tailwind discover the library's compiled class usage.
+
+Example configuration:
+
+```ts
+import editorTailwindPlugin from "@voilabs/mark/plugin";
+
+export default {
+    plugins: [editorTailwindPlugin],
+};
+```
+
+What the plugin does:
+
+- resolves the installed package path
+- points Tailwind content scanning to the package `dist` files
+- enables `tailwindcss-animate`
+- enables `@tailwindcss/typography`
+
+## API Reference
+
+### `Editor`
+
+```ts
+import { Editor } from "@voilabs/mark";
+```
+
+### `EditorProps`
+
+| Prop                 | Type                                       | Description                                                                                                  |
+| -------------------- | ------------------------------------------ | ------------------------------------------------------------------------------------------------------------ |
+| `value`              | `string`                                   | Initial editor content. Supports HTML or Markdown depending on `format`.                                     |
+| `onChange`           | `(value: string) => void`                  | Receives Markdown output whenever the editor updates.                                                        |
+| `format`             | `"html" \| "markdown" \| "auto"`           | Controls how the initial value is interpreted. `auto` detects Markdown-like input.                           |
+| `theme`              | `"light" \| "dark" \| "auto"`              | Forces a theme or enables persisted user switching.                                                          |
+| `onUpload`           | `(file: File) => Promise<{ url: string }>` | Upload handler used by toolbar uploads, slash-command image insertion, paste uploads, and drag/drop uploads. |
+| `disableVideoUpload` | `boolean`                                  | Disables video upload actions in the toolbar.                                                                |
+| `disableImageUpload` | `boolean`                                  | Disables image upload actions and image upload-driven insertion flows.                                       |
+| `classNames`         | `EditorClassNames`                         | Fine-grained class slot overrides for editor shell, toolbar, menus, footer, drag handle, and image UI.       |
+| `translations`       | `Partial<EditorTranslations>`              | Partial translation override merged over built-in English strings.                                           |
+| `styles`             | `ParagraphStyle[]`                         | Replaces the default quick style set shown in the toolbar style gallery.                                     |
+
+### `ParagraphStyle`
+
+Each paragraph style can define:
+
+- `id`
+- `label`
+- `preview`
+- `type`
+- `level`
+- `fontFamily`
+- `fontSize`
+- `fontWeight`
+- `fontStyle`
+- `color`
+- `letterSpacing`
+- `lineHeight`
+- `textTransform`
+
+### `EditorClassNames`
+
+`EditorClassNames` exposes slot-level styling hooks for nearly every visible part of the editor.
+
+### Shell and Content Slots
+
+| Slot              | Purpose                        |
+| ----------------- | ------------------------------ |
+| `root`            | Outer editor wrapper           |
+| `content`         | Main scrollable content region |
+| `contentScroller` | Content scrolling container    |
+| `contentInner`    | Inner centered content wrapper |
+| `editorContent`   | `EditorContent` host container |
+| `prose`           | Tiptap prose typography layer  |
+
+### Footer Slots
+
+| Slot                     | Purpose                              |
+| ------------------------ | ------------------------------------ |
+| `footer`                 | Footer root container                |
+| `footerWordCount`        | Word count label area                |
+| `footerControls`         | Footer controls wrapper              |
+| `footerButton`           | Shared footer button styling         |
+| `footerButtonDisabled`   | Disabled footer button state         |
+| `footerZoomGroup`        | Zoom controls group                  |
+| `footerZoomButton`       | Zoom increment and decrement buttons |
+| `footerZoomValue`        | Zoom percentage button               |
+| `footerFullscreenButton` | Fullscreen toggle button             |
+
+### Toolbar Slots
+
+| Slot                    | Purpose                          |
+| ----------------------- | -------------------------------- |
+| `toolbar`               | Toolbar root container           |
+| `toolbarInner`          | Toolbar scroll container         |
+| `toolbarGroup`          | Toolbar button group wrapper     |
+| `toolbarButton`         | Shared toolbar button styling    |
+| `toolbarButtonActive`   | Active toolbar button state      |
+| `toolbarButtonDisabled` | Disabled toolbar button state    |
+| `toolbarButtonIcon`     | Toolbar button icon wrapper      |
+| `toolbarTrigger`        | Dropdown trigger buttons         |
+| `toolbarTriggerActive`  | Active dropdown trigger state    |
+| `toolbarTriggerIcon`    | Dropdown trigger icon wrapper    |
+| `toolbarTriggerLabel`   | Dropdown trigger label text      |
+| `toolbarTriggerChevron` | Dropdown trigger chevron         |
+| `toolbarSeparator`      | Separator between toolbar groups |
+| `toolbarFileInput`      | Hidden media file input          |
+| `toolbarUploadButton`   | Upload button                    |
+| `toolbarUploadIcon`     | Upload button icon               |
+| `toolbarUploadLabel`    | Upload button label              |
+
+### Style Bar Slots
+
+| Slot                 | Purpose                       |
+| -------------------- | ----------------------------- |
+| `styleBar`           | Quick style gallery container |
+| `styleBarItem`       | Individual style card         |
+| `styleBarItemActive` | Active style card             |
+
+### Style Editor Slots
+
+| Slot                   | Purpose                              |
+| ---------------------- | ------------------------------------ |
+| `styleEditPopover`     | Right-click style edit popover       |
+| `styleEditInput`       | Inputs inside the style editor       |
+| `styleEditSaveButton`  | Save button inside the style editor  |
+| `styleEditResetButton` | Reset button inside the style editor |
+
+### Font Family Slots
+
+| Slot                          | Purpose                      |
+| ----------------------------- | ---------------------------- |
+| `toolbarFontFamilyTrigger`    | Font family combobox trigger |
+| `toolbarFontFamilyPopover`    | Font family popover body     |
+| `toolbarFontFamilySearch`     | Font family search input     |
+| `toolbarFontFamilyList`       | Font family list container   |
+| `toolbarFontFamilyItem`       | Individual font option       |
+| `toolbarFontFamilyItemActive` | Active font option           |
+
+### Font Size Slots
+
+| Slot                           | Purpose                        |
+| ------------------------------ | ------------------------------ |
+| `toolbarFontSizeControl`       | Font size control wrapper      |
+| `toolbarFontSizeControlActive` | Active font size control state |
+| `toolbarFontSizeIcon`          | Font size icon wrapper         |
+| `toolbarFontSizeInput`         | Font size text input           |
+| `toolbarFontSizeUnit`          | Font size unit label           |
+| `toolbarFontSizeStepButton`    | Increase and decrease buttons  |
+| `toolbarFontSizeResetButton`   | Reset font size button         |
+
+### Link Popover Slots
+
+| Slot                      | Purpose                      |
+| ------------------------- | ---------------------------- |
+| `toolbarLinkButton`       | Link toolbar button          |
+| `toolbarLinkPopoverBody`  | Link popover content wrapper |
+| `toolbarLinkPopoverLabel` | Link popover heading         |
+| `toolbarLinkInput`        | Link URL input               |
+| `toolbarLinkActions`      | Link action buttons wrapper  |
+| `toolbarLinkApplyButton`  | Apply link button            |
+| `toolbarLinkUnlinkButton` | Remove link button           |
+
+### Highlight Slots
+
+| Slot                           | Purpose                          |
+| ------------------------------ | -------------------------------- |
+| `toolbarHighlightButton`       | Highlight toolbar button         |
+| `toolbarHighlightIndicator`    | Color indicator under the button |
+| `toolbarHighlightPopoverBody`  | Highlight palette popover body   |
+| `toolbarHighlightPopoverLabel` | Highlight palette label          |
+| `toolbarHighlightGrid`         | Highlight swatch grid            |
+| `toolbarHighlightSwatch`       | Individual highlight swatch      |
+| `toolbarHighlightSwatchActive` | Active highlight swatch          |
+| `toolbarHighlightClearButton`  | Clear highlight button           |
+
+### Shared Overlay Slots
+
+| Slot                        | Purpose                           |
+| --------------------------- | --------------------------------- |
+| `tooltipContent`            | Tooltip content container         |
+| `tooltipArrow`              | Tooltip arrow                     |
+| `popoverContent`            | Shared popover content container  |
+| `dropdownContent`           | Main dropdown menu content        |
+| `dropdownSubContent`        | Nested dropdown menu content      |
+| `dropdownSubTrigger`        | Nested dropdown trigger item      |
+| `dropdownSubTriggerChevron` | Nested dropdown chevron           |
+| `dropdownItem`              | Standard dropdown item            |
+| `dropdownItemActive`        | Active dropdown item state        |
+| `dropdownItemIcon`          | Dropdown item icon                |
+| `dropdownItemLabel`         | Dropdown item label               |
+| `dropdownItemCheck`         | Dropdown selected-state checkmark |
+| `dropdownCheckboxItem`      | Checkbox dropdown item            |
+| `dropdownRadioItem`         | Radio dropdown item               |
+| `dropdownIndicator`         | Dropdown indicator wrapper        |
+| `dropdownLabel`             | Dropdown section label            |
+| `dropdownSeparator`         | Dropdown separator                |
+| `dropdownShortcut`          | Dropdown shortcut hint text       |
+
+### Slash Command Slots
+
+| Slot                     | Purpose                      |
+| ------------------------ | ---------------------------- |
+| `slashCommandMenu`       | Slash command menu container |
+| `slashCommandItem`       | Slash command item           |
+| `slashCommandItemActive` | Active slash command item    |
+| `slashCommandIcon`       | Slash command icon wrapper   |
+| `slashCommandTitle`      | Slash command item label     |
+| `slashCommandEmpty`      | Empty state wrapper          |
+| `slashCommandEmptyIcon`  | Empty state icon             |
+
+### Drag Handle Slots
+
+| Slot                          | Purpose                             |
+| ----------------------------- | ----------------------------------- |
+| `dragHandleRoot`              | Floating drag handle root           |
+| `dragHandleAddButton`         | Add-block button                    |
+| `dragHandleMenuButton`        | Grip/menu button                    |
+| `dragHandleMenuContent`       | Drag handle dropdown content        |
+| `dragHandleSubContent`        | Nested drag handle dropdown content |
+| `dragHandleColorSectionLabel` | Text/background color section label |
+| `dragHandleColorTextPreview`  | Text color preview glyph            |
+| `dragHandleColorSwatch`       | Background color swatch             |
+| `dragHandleCheckIcon`         | Selected-state check icon           |
+| `dragHandleDeleteItem`        | Delete item styling                 |
+
+### Image Node Slots
+
+| Slot                           | Purpose                      |
+| ------------------------------ | ---------------------------- |
+| `imageNodeWrapper`             | Outer image node wrapper     |
+| `imageContainer`               | Image selection frame        |
+| `imageCropArea`                | Crop area wrapper            |
+| `imageCropToolbar`             | Crop mode toolbar            |
+| `imageCropButton`              | Shared crop toolbar button   |
+| `imageCropCancelButton`        | Cancel crop button           |
+| `imageCropApplyButton`         | Apply crop button            |
+| `imageFrame`                   | Image frame container        |
+| `imageElement`                 | Rendered `<img>` element     |
+| `imageLoadingOverlay`          | Upload/loading overlay       |
+| `imageLoadingBox`              | Loader badge container       |
+| `imageLoadingIcon`             | Loader icon                  |
+| `imagePanHintOverlay`          | Pan hint overlay             |
+| `imagePanHint`                 | Pan hint text                |
+| `imageToolbar`                 | Image hover toolbar          |
+| `imageToolbarButton`           | Shared image toolbar button  |
+| `imageToolbarSeparator`        | Divider inside image toolbar |
+| `imageDeleteButton`            | Image delete button          |
+| `imageAltButton`               | Alt text button              |
+| `imageAltPopover`              | Alt text popover body        |
+| `imageAltLabel`                | Alt text popover label       |
+| `imageAltInput`                | Alt text input               |
+| `imageAltActions`              | Alt text action row          |
+| `imageAltApplyButton`          | Apply alt text button        |
+| `imageAltClearButton`          | Clear alt text button        |
+| `imageResizeHandle`            | Shared resize handle styling |
+| `imageResizeHandleRight`       | Right resize handle          |
+| `imageResizeHandleBottom`      | Bottom resize handle         |
+| `imageResizeHandleBottomRight` | Bottom-right resize handle   |
+| `imageModeBadge`               | Mode hint wrapper            |
+| `imageModeText`                | Mode hint label              |
+
+This API is intended for design system integration without forcing a fork of the editor internals.
+
+### Translations
+
+The library ships with:
+
+- `en-US`
+- `tr-TR`
+
+You can either import a full locale object or pass a partial object to override selected labels.
+
+## Development Workflow
+
+This repository is configured as a library project, not as a local preview app.
+
+### Install Dependencies
+
+```bash
+bun install
+```
+
+### Development Build Watch
+
+```bash
+bun run dev
+```
+
+This runs:
+
+```bash
+vite build --watch
+```
+
+Use this mode when you want incremental rebuilds of the library output while developing the package.
+
+### Production Build
+
+```bash
+bun run build
+```
+
+This runs:
+
+```bash
+vite build && tsc -p tsconfig.build.json
+```
+
+The command generates JavaScript bundles and declaration files into `dist/`.
+
+## Build and Distribution
+
+The Vite configuration builds multiple library entry points:
+
+- `src/index.ts`
+- `src/plugin.ts`
+- `src/translations/en-US.ts`
+- `src/translations/tr-TR.ts`
+
+The package metadata exposes:
+
+- main editor entry
+- Tailwind plugin entry
+- locale entries
+
+Distributed assets include:
+
+- ESM bundles
+- UMD bundles
+- `.d.ts` type declarations
+
+The package is configured to publish:
+
+- `dist`
+- `README.md`
+- `LICENSE`
+- `package.json`
+
+## Dependency Management
+
+### Peer Dependencies
+
+The package declares the following peers:
+
+- `react`
+- `react-dom`
+- `typescript`
+
+### Runtime Dependencies
+
+The runtime layer relies heavily on:
+
+- Tiptap extensions and editor packages
+- Radix UI primitives
+- Tailwind merge helpers
+- icon and motion libraries
+- media and popup utilities such as `react-easy-crop` and `tippy.js`
+
+### Development Dependencies
+
+Development and build-time tooling includes:
+
+- Babel and Rollup-related packages
+- Vite and React integration tooling
+- TypeScript
+- declaration generation plugins
+
+### Lockfiles
+
+The repository currently includes both `package-lock.json` and `bun.lock`, which suggests npm and Bun have both been used during development. This README uses Bun for repository workflows and npm for consumer installation examples.
+
+## Architecture
+
+The codebase is organized as a reusable component library with a single primary editor shell and a set of supporting modules.
+
+### High-Level Design
+
+1. `src/components/Editor.tsx` creates the Tiptap editor instance and composes the full editor shell.
+2. `src/components/editor/Toolbar.tsx` provides the main authoring controls and style management UI.
+3. `src/components/editor/GlobalDragHandleMenu.tsx` adds block-level actions beside the editing surface.
+4. `src/components/editor/extensions/*` defines custom Tiptap extensions for images, video, font size, font family, and extra text-style attributes.
+5. `src/components/editor/slash-command/*` implements the `/` suggestion system.
+6. `src/components/editor/EditorContext.tsx` shares theme, translations, class names, and styles with nested UI primitives.
+7. `src/plugin.ts` exports a Tailwind helper plugin intended to help host apps include the editor's utility classes.
+
+### Content Flow
+
+The editor follows this runtime flow:
+
+1. Initial `value` is read as HTML, Markdown, or auto-detected content.
+2. Tiptap extensions are registered, including the custom image/video and typography extensions.
+3. User actions update the internal ProseMirror document.
+4. `onChange` is called with `editor.getMarkdown()`.
+
+Important behavior:
+
+- Input supports HTML, Markdown, or auto-detection via the `format` prop.
+- Output is Markdown on every update, regardless of the original input format.
+- Auto theme mode persists the chosen theme using the `VOILABS_REACT_EDITOR_THEME` key.
+- Style overrides are stored locally using the `voilabs-editor-style-overrides` key.
+
+### Extensibility Points
+
+- `onUpload` for custom media upload pipelines
+- `styles` for custom paragraph style sets
+- `classNames` for granular visual overrides
+- `translations` for partial locale overrides
+- exported Tiptap extensions such as `AdvancedImage`, `FontSize`, and `Video`
+
+## Project Structure
+
+```text
+editor/
+|- src/
+|  |- components/
+|  |  |- Editor.tsx
+|  |  |- editor/
+|  |  |  |- EditorContext.tsx
+|  |  |  |- Toolbar.tsx
+|  |  |  |- StyleBar.tsx
+|  |  |  |- StyleEditPopover.tsx
+|  |  |  |- GlobalDragHandleMenu.tsx
+|  |  |  |- classNames.ts
+|  |  |  |- paragraphStyles.ts
+|  |  |  |- translations.ts
+|  |  |  |- useStyleStorage.ts
+|  |  |  |- extensions/
+|  |  |  |  |- AdvancedImage.tsx
+|  |  |  |  |- ImageNodeView.tsx
+|  |  |  |  |- FontFamily.ts
+|  |  |  |  |- FontSize.ts
+|  |  |  |  |- TextStyleAttributes.ts
+|  |  |  |  `- Video.tsx
+|  |  |  `- slash-command/
+|  |  |     |- commands.ts
+|  |  |     |- commands-list.tsx
+|  |  |     `- suggestion.tsx
+|  |  `- ui/
+|  |     |- Dropdown.tsx
+|  |     |- DropdownMenu.tsx
+|  |     |- Popover.tsx
+|  |     `- Tooltip.tsx
+|  |- lib/
+|  |  `- utils.ts
+|  |- translations/
+|  |  |- en-US.ts
+|  |  `- tr-TR.ts
+|  |- index.ts
+|  `- plugin.ts
+|- package.json
+|- vite.config.ts
+|- tsconfig.json
+`- tsconfig.build.json
+```
+
+## Tech Stack and Dependencies
+
+### Core Runtime
+
+- React 19
+- Tiptap 3 ecosystem
+- ProseMirror through `@tiptap/pm`
+- Tailwind CSS 4
+- Radix UI popover, dropdown menu, and tooltip primitives
+- `lucide-react` for editor icons
+- `react-easy-crop` for image cropping
+- `tippy.js` for slash command popup positioning
+
+### Build Tooling
+
+- Vite library mode
+- TypeScript 5
+- `vite-plugin-dts` for declaration generation
+- `@vitejs/plugin-react`
+- `@tailwindcss/vite`
+
+### Noteworthy Implementation Details
+
+- The editor uses a custom `image` node implementation instead of the default Tiptap image extension.
+- The `Video` extension renders native HTML `<video>` nodes with controls enabled.
+- The toolbar uses context-aware command selection so inline formatting can apply to the current word even when no explicit range is selected.
+- The drag handle menu performs block-level actions by resolving the top-level node under the cursor.
+- The Tailwind helper plugin tries to resolve the installed package path dynamically and scans the built `dist` files for content extraction.
+
+## Contributing
+
+Contributions should preserve the package's library-first design, typed public API, and editor usability.
+
+Recommended contribution process:
+
+1. Fork or branch from the latest mainline source.
+2. Install dependencies with `npm install`.
+3. Make focused changes with clear intent.
+4. Verify the package builds successfully with `npm run build`.
+5. Update documentation when behavior or public API changes.
+6. Open a pull request with a concise explanation of the change.
+
+Suggested contribution guidelines:
+
+- keep public API changes intentional and documented
+- avoid breaking translation keys without updating shipped locales
+- preserve Markdown output behavior unless a deliberate API change is introduced
+- keep Tailwind class slot compatibility in mind when changing UI structure
+- prefer incremental, reviewable pull requests
+
+At the moment, the repository does not define dedicated lint or test scripts in `package.json`, so build validation is the primary verification step.
+
+## License
+
+This project is licensed under the MIT License.
+
+See [LICENSE](./LICENSE) for the full text.