luxen-ui 0.6.2 → 0.7.0

package/dist/templates/elements/prose-editor.md

@@ -0,0 +1,216 @@
+---
+outline: deep
+---
+
+# Prose Editor
+
+A rich text editor built on [Tiptap](https://tiptap.dev) (ProseMirror). Form-associated — its value is the editor HTML, so it submits inside a `<form>` like a native field.
+
+```html
+<l-prose-editor placeholder="Write something…"></l-prose-editor>
+```
+
+The editable area renders in light DOM, so its content styles ship as a separate stylesheet you import once globally. See [Importing](#importing).
+
+<ElementSpec
+  tag="l-prose-editor"
+  type="shadow"
+/>
+
+## Options
+
+### Basic
+
+The default toolbar covers headings, marks, lists, links, code, an emoji picker and undo/redo. Set initial content with `initial-html`.
+
+```html
+<l-prose-editor
+  placeholder="Write something…"
+  initial-html="<h2>Release notes</h2><p>This editor ships with a <strong>default</strong> toolbar covering headings, marks, lists, links and more.</p><ul><li>Built on Tiptap</li><li>Form-associated</li></ul>"
+></l-prose-editor>
+```
+
+### Toolbar preset
+
+Set `toolbar-preset="minimal"` for a compact bold/italic/underline toolbar.
+
+```html
+<l-prose-editor
+  toolbar-preset="minimal"
+  placeholder="Bold, italic, underline only…"
+></l-prose-editor>
+```
+
+### Custom toolbar
+
+Set `toolbar` to a comma-separated list of commands to build your own layout. Use `divider` to insert a separator.
+
+```html
+<l-prose-editor
+  toolbar="bold,italic,link,divider,bulletlist,orderedlist,divider,undo,redo"
+  placeholder="Custom toolbar…"
+></l-prose-editor>
+```
+
+Available commands: `heading-1`, `heading-2`, `heading-3`, `bold`, `italic`, `underline`, `strike`, `highlight`, `bulletlist`, `orderedlist`, `blockquote`, `code-block`, `horizontal-rule`, `link`, `emoji`, `attachment`, `undo`, `redo`, `divider`.
+
+### Toolbar placement
+
+Set `toolbar-placement="bottom"` to move the toolbar below the content.
+
+```html
+<l-prose-editor
+  toolbar-placement="bottom"
+  placeholder="Toolbar sits below the content…"
+></l-prose-editor>
+```
+
+## Examples
+
+### Form integration
+
+The editor participates in forms via its `name` attribute. The submitted value is the HTML string; `required` blocks submission while empty.
+
+```html
+<form
+  class="flex flex-col items-start gap-4"
+  onsubmit="
+    event.preventDefault();
+    const data = new FormData(event.target);
+    alert('description = ' + data.get('description'));
+  "
+>
+  <label class="flex w-full flex-col gap-1">
+    <span class="text-sm font-medium">Description</span>
+    <l-prose-editor
+      name="description"
+      required
+      toolbar-preset="minimal"
+      placeholder="Describe your product…"
+    ></l-prose-editor>
+  </label>
+  <button
+    type="submit"
+    class="l-button"
+    data-variant="primary"
+  >
+    Submit
+  </button>
+</form>
+```
+
+## Accessibility
+
+### Criteria
+
+| Check | Description |
+|-------|-------------|
+| Toolbar role | The toolbar uses `role="toolbar"` with an accessible label |
+| Button state | Each toolbar button exposes `aria-pressed` reflecting whether the mark/format is active |
+| Button label | Icon-only buttons carry an `aria-label` and `title` describing the action |
+| Focus state | Visible focus ring on toolbar buttons for keyboard users |
+| Form validation | When `required`, an empty editor reports a `valueMissing` validation message to the form |
+
+### Rules
+- Associate a visible `<label>` with the editor, or set `aria-label` on the host element
+- Keep custom toolbars logically ordered so keyboard users encounter commands in a predictable sequence
+
+### Keyboard interactions
+
+| Key | Description |
+|-----|-------------|
+| Tab | Moves focus into the toolbar, then into the editable content |
+| Ctrl/Cmd + B | Toggles bold |
+| Ctrl/Cmd + I | Toggles italic |
+| Ctrl/Cmd + U | Toggles underline |
+| Ctrl/Cmd + Z | Undo |
+| Ctrl/Cmd + Shift + Z | Redo |
+| Escape | Closes the emoji picker when open |
+
+## API reference
+
+### Importing
+
+Import the element and the content stylesheet once globally. The stylesheet styles the editable area, which renders in light DOM to avoid `contenteditable` caret bugs inside shadow trees.
+
+```js
+import 'luxen-ui/prose-editor';
+```
+
+```css
+@import 'luxen-ui/css/prose-editor';
+```
+
+### Attributes & Properties
+
+<ApiTable :data="[
+  { Attribute: 'initial-html', Description: 'Initial content as an HTML string' },
+  { Attribute: 'initial-json', Description: 'Initial content as a serialized ProseMirror JSON string. Used when `initial-html` is not set' },
+  { Attribute: 'toolbar-preset', Description: 'Built-in toolbar layout: `default` (full) or `minimal`. Defaults to `default`' },
+  { Attribute: 'toolbar', Description: 'Comma-separated list of commands. Overrides `toolbar-preset` when set' },
+  { Attribute: 'toolbar-placement', Description: 'Where the toolbar sits: `top` (default) or `bottom`. Reflects to attribute' },
+  { Attribute: 'editor-class', Description: 'Class applied to the editable element. Defaults to `prose` (for Tailwind Typography)' },
+  { Attribute: 'placeholder', Description: 'Text shown when the editor is empty' },
+  { Attribute: 'autofocus', Description: 'Focus the editor on creation' },
+  { Attribute: 'name', Description: 'Form field name. The submitted value is the editor HTML' },
+  { Attribute: 'required', Description: 'Marks the field invalid while the editor is empty' },
+  { Attribute: 'disabled', Description: 'Disables editing' },
+  { Property: 'editor', Description: 'The underlying Tiptap `Editor` instance. Available after first render' },
+]" />
+
+### Methods
+
+<ApiTable :data="[
+  { Method: 'getHTML()', Description: 'Returns the content as an HTML string. An empty paragraph resolves to `\'\'`' },
+  { Method: 'getJSON()', Description: 'Returns the content as ProseMirror JSON' },
+  { Method: 'clear()', Description: 'Removes all content' },
+  { Method: 'focus()', Description: 'Focuses the editable content' },
+  { Method: 'blur()', Description: 'Removes focus from the editable content' },
+]" />
+
+### Events
+
+<ApiTable :data="[
+  { Event: 'change', Description: 'Fired when the content changes. `event.detail` is `{ html, json }`' },
+  { Event: 'add-file', Description: 'Fired when the `attachment` toolbar button is clicked. Wire up your own upload flow' },
+]" />
+
+### Slots
+
+<ApiTable :data="[
+  { Slot: 'toolbar-start', Description: 'Content placed before the generated toolbar buttons' },
+  { Slot: 'toolbar-end', Description: 'Content placed after the generated toolbar buttons' },
+]" />
+
+### CSS Parts
+
+<ApiTable :data="[
+  { Part: 'wrapper', Description: 'The editor frame wrapping the toolbar and content' },
+  { Part: 'toolbar', Description: 'The toolbar row' },
+  { Part: 'toolbar-button', Description: 'Any toolbar button' },
+  { Part: 'divider', Description: 'A toolbar divider' },
+  { Part: 'editor', Description: 'The container around the editable content' },
+]" />
+
+### CSS custom properties
+
+<ApiTable :data="[
+  { Name: '--border-color', Description: 'Color of the editor frame border' },
+  { Name: '--border-width', Description: 'Width of the editor frame border' },
+  { Name: '--border-radius', Description: 'Corner radius of the editor frame' },
+  { Name: '--background', Description: 'Background color of the editor' },
+  { Name: '--color', Description: 'Text color of the editor' },
+  { Name: '--toolbar-background', Description: 'Background color of the toolbar' },
+  { Name: '--toolbar-padding', Description: 'Padding around the toolbar' },
+  { Name: '--toolbar-gap', Description: 'Gap between toolbar buttons' },
+  { Name: '--toolbar-divider-color', Description: 'Color of toolbar dividers' },
+  { Name: '--toolbar-button-size', Description: 'Size of toolbar buttons' },
+  { Name: '--toolbar-button-radius', Description: 'Corner radius of toolbar buttons' },
+  { Name: '--toolbar-button-color', Description: 'Icon color of inactive toolbar buttons' },
+  { Name: '--toolbar-button-color-active', Description: 'Icon color of hovered/active toolbar buttons' },
+  { Name: '--toolbar-button-background-hover', Description: 'Background of hovered toolbar buttons' },
+  { Name: '--toolbar-button-background-active', Description: 'Background of active toolbar buttons' },
+  { Name: '--content-padding', Description: 'Padding of the editable content area' },
+  { Name: '--content-min-height', Description: 'Minimum height of the editable content area' },
+  { Name: '--placeholder-color', Description: 'Color of the placeholder text' },
+]" />

package/elements.json

@@ -127,6 +127,13 @@
       "inSkill": true,
       "inMockups": false
     },
+    {
+      "name": "prose-editor",
+      "displayName": "Prose editor",
+      "kind": "element",
+      "inSkill": true,
+      "inMockups": true
+    },
     {
       "name": "rating",
       "displayName": "Rating",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "luxen-ui",
-  "version": "0.6.2",
+  "version": "0.7.0",
   "description": "Modern web components and CSS-first UI library built with Lit. Framework-agnostic, customizable prefix, design tokens.",
   "keywords": [
     "custom-elements",
@@ -113,9 +113,16 @@
     "provenance": true
   },
   "dependencies": {
+    "@emoji-mart/data": "^1.2.1",
     "@floating-ui/dom": "^1.7.6",
+    "@tiptap/core": "^3.23.6",
+    "@tiptap/extension-highlight": "^3.23.6",
+    "@tiptap/extensions": "^3.23.6",
+    "@tiptap/pm": "^3.23.6",
+    "@tiptap/starter-kit": "^3.23.6",
     "embla-carousel": "^8.6.0",
     "embla-carousel-autoplay": "^8.6.0",
+    "emoji-mart": "^5.6.0",
     "iconify-icon": "^3.0.2",
     "lit": "^3.3.3"
   },