@kubex/zinc 1.0.103 → 1.0.104

package/docs/pages/components/markdown-editor.md

@@ -0,0 +1,301 @@
+---
+meta:
+  title: Markdown Editor
+  description: A markdown editor with live preview, split view, and fullscreen mode.
+layout: component
+---
+
+`zn-markdown-editor` wraps the full markdown authoring workflow in a single
+form control: a textarea for writing, a live preview rendered with
+[`marked`](https://marked.js.org/) (bundled with the component), toggleable
+editor / split / preview modes, a fullscreen toggle, and `localStorage`
+persistence for the selected view.
+
+```html:preview
+<zn-markdown-editor
+  label="Content"
+  name="content"
+  help-text="Supports GitHub-flavored markdown"
+  value="# Hello
+
+Write some **markdown** on the left — use the toolbar to switch to split or preview."
+></zn-markdown-editor>
+```
+
+## Examples
+
+### Initial Value via Attribute
+
+Set the initial markdown with the `value` attribute.
+
+```html:preview
+<zn-markdown-editor
+  label="Article"
+  name="article"
+  value="## Release notes
+
+- New payments dashboard
+- Faster settlement reporting"
+></zn-markdown-editor>
+```
+
+### Initial Value via Light DOM
+
+If no `value` attribute is set, `zn-markdown-editor` reads its initial markdown
+from its own text-node children. This is handy when rendering server-side
+content into the tag without escaping quotes:
+
+```html:preview
+<zn-markdown-editor name="content" label="Terms">
+# Terms of Service
+
+This copy was rendered from a server-side template and picked up automatically.
+</zn-markdown-editor>
+```
+
+### Setting the Default View
+
+Use the `view-mode` attribute to open directly in `editor` (default), `split`,
+or `preview`.
+
+```html:preview
+<zn-markdown-editor
+  name="content"
+  label="Split by default"
+  view-mode="split"
+  value="## Split view
+
+See both at once."
+></zn-markdown-editor>
+
+<br />
+
+<zn-markdown-editor
+  name="content"
+  label="Preview by default"
+  view-mode="preview"
+  value="## Preview view
+
+Toggle to the editor to edit."
+></zn-markdown-editor>
+```
+
+### Persisting the Selected View
+
+The chosen view mode is persisted in `localStorage` under the key set by
+`storage-key` (default `zn-markdown-editor-view-mode`). Use distinct keys
+when multiple editors should remember their own preference.
+
+```html:preview
+<zn-markdown-editor
+  name="email_template"
+  label="Email template"
+  storage-key="email-template-view"
+></zn-markdown-editor>
+```
+
+To opt out of persistence, set `storage-key` to an empty string:
+
+```html
+
+<zn-markdown-editor storage-key=""></zn-markdown-editor>
+```
+
+### Help Text
+
+Add descriptive help text with the `help-text` attribute, or use the slot for
+HTML content.
+
+```html:preview
+<zn-markdown-editor
+  label="Release notes"
+  name="notes"
+  help-text="Use headings, lists, and code fences for emphasis."
+></zn-markdown-editor>
+
+<br />
+
+<zn-markdown-editor label="Release notes" name="notes">
+  <div slot="help-text">
+    See the <a href="https://commonmark.org/help/">CommonMark cheatsheet</a>
+    for a full syntax reference.
+  </div>
+</zn-markdown-editor>
+```
+
+### Rows
+
+Use `rows` to change the initial height of the editor before it overflows.
+Default is `20`.
+
+```html:preview
+<zn-markdown-editor label="Short editor" rows="6"></zn-markdown-editor>
+```
+
+### Required, Readonly, Disabled
+
+`zn-markdown-editor` forwards standard form-control state onto its underlying
+textarea.
+
+```html:preview
+<zn-markdown-editor label="Required" name="content" required></zn-markdown-editor>
+
+<br />
+
+<zn-markdown-editor
+  label="Readonly"
+  name="content"
+  readonly
+  value="## Read-only content
+
+Visible but not editable."
+></zn-markdown-editor>
+
+<br />
+
+<zn-markdown-editor
+  label="Disabled"
+  name="content"
+  disabled
+  value="Disabled editor."
+></zn-markdown-editor>
+```
+
+### Form Integration
+
+`zn-markdown-editor` is a [form control](/getting-started/form-controls), so
+its value is submitted with the surrounding form.
+
+```html:preview
+<form class="markdown-editor-form">
+  <zn-markdown-editor
+    name="content"
+    label="Document"
+    required
+    value="## Getting started
+
+Write your content here."
+  ></zn-markdown-editor>
+  <br />
+  <zn-button type="submit" color="success">Submit</zn-button>
+  <zn-button type="reset" color="secondary">Reset</zn-button>
+</form>
+
+<script type="module">
+  const form = document.querySelector('.markdown-editor-form');
+
+  await customElements.whenDefined('zn-button');
+  await customElements.whenDefined('zn-markdown-editor');
+
+  form.addEventListener('submit', (e) => {
+    e.preventDefault();
+    const data = Object.fromEntries(new FormData(form));
+    alert('Submitted!\n\n' + JSON.stringify(data, null, 2));
+  });
+</script>
+```
+
+### Reacting to Events
+
+Listen for content and view-mode changes.
+
+```html:preview
+<zn-markdown-editor
+  id="event-editor"
+  name="content"
+  label="Event demo"
+  value="Type here..."
+></zn-markdown-editor>
+
+<div id="event-log" style="margin-top: 1rem; padding: 1rem; background: var(--zn-color-neutral-100); border-radius: 4px; font-family: monospace; font-size: 0.875rem; max-height: 200px; overflow-y: auto;">
+  Events will appear here...
+</div>
+
+<script type="module">
+  const editor = document.getElementById('event-editor');
+  const log = document.getElementById('event-log');
+
+  await customElements.whenDefined('zn-markdown-editor');
+
+  function push(name, detail = '') {
+    const t = new Date().toLocaleTimeString();
+    log.innerHTML = `[${t}] ${name}${detail ? ': ' + detail : ''}<br>` + log.innerHTML;
+  }
+
+  editor.addEventListener('zn-input', () => push('zn-input', `length=${editor.value.length}`));
+  editor.addEventListener('zn-change', () => push('zn-change'));
+  editor.addEventListener('zn-view-mode-change', (e) => push('zn-view-mode-change', e.detail.mode));
+</script>
+```
+
+### Programmatic Control
+
+`focus()`, `blur()`, `checkValidity()`, and `reportValidity()` are all
+available on the element.
+
+```html:preview
+<zn-markdown-editor
+  id="control-editor"
+  name="content"
+  label="Controlled editor"
+  value="## Controlled"
+></zn-markdown-editor>
+<br />
+<zn-button id="editor-focus">Focus</zn-button>
+<zn-button id="editor-blur">Blur</zn-button>
+<zn-button id="editor-split">Switch to split</zn-button>
+<zn-button id="editor-preview">Switch to preview</zn-button>
+<zn-button id="editor-clear" color="error">Clear</zn-button>
+
+<script type="module">
+  const editor = document.getElementById('control-editor');
+
+  await customElements.whenDefined('zn-button');
+  await customElements.whenDefined('zn-markdown-editor');
+
+  document.getElementById('editor-focus').addEventListener('click', () => editor.focus());
+  document.getElementById('editor-blur').addEventListener('click', () => editor.blur());
+  document.getElementById('editor-split').addEventListener('click', () => { editor.viewMode = 'split'; });
+  document.getElementById('editor-preview').addEventListener('click', () => { editor.viewMode = 'preview'; });
+  document.getElementById('editor-clear').addEventListener('click', () => { editor.value = ''; });
+</script>
+```
+
+### Fullscreen Mode
+
+Click the fullscreen icon in the top-right to expand the editor to cover its
+nearest positioned ancestor. Click again to collapse. This is driven by the
+`expanded` state on the element, so you can also toggle it programmatically:
+
+```html
+
+<zn-markdown-editor id="fs-editor"></zn-markdown-editor>
+
+<script>
+  document.getElementById('fs-editor').expanded = true;
+</script>
+```
+
+## Events
+
+| Event                 | Detail                                       | Description                                 |
+|-----------------------|----------------------------------------------|---------------------------------------------|
+| `zn-input`            | –                                            | Fired on every keystroke in the editor.     |
+| `zn-change`           | –                                            | Fired when the editor's value is committed. |
+| `zn-view-mode-change` | `{ mode: 'editor' \| 'split' \| 'preview' }` | Fired when the user switches view modes.    |
+
+## Slots
+
+| Slot        | Description                                                         |
+|-------------|---------------------------------------------------------------------|
+| `label`     | Custom HTML label. Alternatively use the `label` attribute.         |
+| `help-text` | Custom HTML help text. Alternatively use the `help-text` attribute. |
+
+## CSS Parts
+
+| Part      | Description                         |
+|-----------|-------------------------------------|
+| `base`    | The component's base wrapper.       |
+| `toolbar` | The view-mode / fullscreen toolbar. |
+| `editor`  | The textarea wrapper.               |
+| `preview` | The rendered markdown preview pane. |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kubex/zinc",
-  "version": "1.0.103",
+  "version": "1.0.104",
   "description": "A collection of web components for building web applications based off of @shoelace-style/Shoelace",
   "keywords": [
     "web components",
@@ -51,6 +51,7 @@
     "composed-offset-position": "^0.0.6",
     "emoji-mart": "^5.6.0",
     "lit": "^2.7.6",
+    "marked": "^18.0.2",
     "quill": "^2.0.3"
   },
   "devDependencies": {

package/src/components/markdown-editor/index.ts

@@ -0,0 +1,12 @@
+import ZnMarkdownEditor from './markdown-editor.component';
+
+export * from './markdown-editor.component';
+export default ZnMarkdownEditor;
+
+ZnMarkdownEditor.define('zn-markdown-editor');
+
+declare global {
+  interface HTMLElementTagNameMap {
+    'zn-markdown-editor': ZnMarkdownEditor;
+  }
+}

package/src/components/markdown-editor/markdown-editor.component.ts

@@ -0,0 +1,332 @@
+import {classMap} from "lit/directives/class-map.js";
+import {type CSSResultGroup, html, type PropertyValues, unsafeCSS} from 'lit';
+import {defaultValue} from "../../internal/default-value";
+import {FormControlController} from "../../internal/form";
+import {HasSlotController} from "../../internal/slot";
+import {marked} from "marked";
+import {property, query, state} from 'lit/decorators.js';
+import {watch} from "../../internal/watch";
+import ZincElement from '../../internal/zinc-element';
+import type {ZincFormControl} from '../../internal/zinc-element';
+import type ZnTextarea from "../textarea";
+
+import styles from './markdown-editor.scss';
+
+type ViewMode = 'editor' | 'split' | 'preview';
+
+const VIEW_MODES: {mode: ViewMode; icon: string; label: string}[] = [
+  {mode: 'editor', icon: 'edit_note', label: 'Editor'},
+  {mode: 'split', icon: 'vertical_split', label: 'Split'},
+  {mode: 'preview', icon: 'visibility', label: 'Preview'},
+];
+
+/**
+ * @summary A markdown editor with live preview, split view, and a fullscreen mode.
+ * @documentation https://zinc.style/components/markdown-editor
+ * @status experimental
+ * @since 1.0
+ *
+ * @dependency zn-textarea
+ * @dependency zn-button-group
+ * @dependency zn-icon
+ *
+ * @event zn-change - Emitted when the markdown content changes.
+ * @event zn-input - Emitted on each keystroke in the editor.
+ * @event zn-view-mode-change - Emitted when the user switches between editor / split / preview.
+ *
+ * @slot label - The editor label. Alternatively, use the `label` attribute.
+ * @slot help-text - Help text shown below the editor. Alternatively, use the `help-text` attribute.
+ *
+ * @csspart base - The component's base wrapper.
+ * @csspart toolbar - The toolbar containing the view-mode and fullscreen controls.
+ * @csspart editor - The textarea wrapper.
+ * @csspart preview - The rendered markdown preview.
+ */
+export default class ZnMarkdownEditor extends ZincElement implements ZincFormControl {
+  static styles: CSSResultGroup = unsafeCSS(styles);
+
+  private readonly formControlController = new FormControlController(this, {
+    assumeInteractionOn: ['zn-input', 'zn-change'],
+  });
+  private readonly hasSlotController = new HasSlotController(this, 'label', 'help-text');
+
+  private debounceTimer: ReturnType<typeof setTimeout> | null = null;
+
+  @query('zn-textarea') textarea: ZnTextarea;
+  @query('.markdown-editor__preview') previewEl: HTMLDivElement;
+
+  /** The name of the control, submitted as part of form data. */
+  @property() name = '';
+
+  /** The current markdown content. */
+  @property() value = '';
+
+  /** The default value — used when resetting the form. */
+  @defaultValue() defaultValue = '';
+
+  /** The control's label. If you need HTML, use the `label` slot. */
+  @property() label = '';
+
+  /** Help text displayed below the editor. If you need HTML, use the `help-text` slot. */
+  @property({attribute: 'help-text'}) helpText = '';
+
+  /** Placeholder text shown when the editor is empty. */
+  @property() placeholder = 'Enter markdown content...';
+
+  /** Number of rows for the textarea. */
+  @property({type: Number}) rows = 20;
+
+  /** Which view to show. */
+  @property({reflect: true, attribute: 'view-mode'})
+  viewMode: ViewMode = 'editor';
+
+  /**
+   * Key used to persist the selected view mode to `localStorage`. Set to an empty string to disable persistence.
+   */
+  @property({attribute: 'storage-key'}) storageKey = 'zn-markdown-editor-view-mode';
+
+  /** Makes the editor required for form submission. */
+  @property({type: Boolean, reflect: true}) required = false;
+
+  /** Makes the editor read-only. */
+  @property({type: Boolean, reflect: true}) readonly = false;
+
+  /** Disables the editor. */
+  @property({type: Boolean, reflect: true}) disabled = false;
+
+  /** Whether the editor is currently expanded to cover its containing positioned ancestor. */
+  @state() expanded = false;
+
+  get validity(): ValidityState {
+    return this.textarea?.validity;
+  }
+
+  get validationMessage(): string {
+    return this.textarea?.validationMessage ?? '';
+  }
+
+  checkValidity(): boolean {
+    return this.textarea?.checkValidity() ?? true;
+  }
+
+  getForm(): HTMLFormElement | null {
+    return this.formControlController.getForm();
+  }
+
+  reportValidity(): boolean {
+    return this.textarea?.reportValidity() ?? true;
+  }
+
+  setCustomValidity(message: string): void {
+    this.textarea?.setCustomValidity(message);
+    this.formControlController.updateValidity();
+  }
+
+  /** Sets focus on the editor. */
+  focus(options?: FocusOptions) {
+    this.textarea?.focus(options);
+  }
+
+  /** Removes focus from the editor. */
+  blur() {
+    this.textarea?.blur();
+  }
+
+  connectedCallback() {
+    super.connectedCallback();
+
+    // Pull initial value from light-DOM text content if no value attr/property is set.
+    if (!this.hasAttribute('value') && !this.value) {
+      const textNodes = Array.from(this.childNodes).filter(n => n.nodeType === Node.TEXT_NODE);
+      const raw = textNodes.map(n => n.textContent ?? '').join('');
+      const content = raw.replace(/\r\n/g, '\n').trim();
+      if (content.length > 0) {
+        this.value = content;
+        this.defaultValue = content;
+        textNodes.forEach(n => {
+          if ((n.textContent ?? '').trim().length > 0) n.parentNode?.removeChild(n);
+        });
+      }
+    }
+
+    const stored = this.readStoredViewMode();
+    if (stored) this.viewMode = stored;
+  }
+
+  disconnectedCallback() {
+    super.disconnectedCallback();
+    if (this.debounceTimer) clearTimeout(this.debounceTimer);
+  }
+
+  protected firstUpdated(_changedProperties: PropertyValues) {
+    void _changedProperties;
+    this.formControlController.updateValidity();
+    if (this.viewMode !== 'editor') this.renderPreview();
+  }
+
+  private readStoredViewMode(): ViewMode | null {
+    if (!this.storageKey) return null;
+    try {
+      const saved = localStorage.getItem(this.storageKey);
+      if (saved === 'editor' || saved === 'split' || saved === 'preview') return saved;
+    } catch {
+      // localStorage not available
+    }
+    return null;
+  }
+
+  private writeStoredViewMode(mode: ViewMode) {
+    if (!this.storageKey) return;
+    try {
+      localStorage.setItem(this.storageKey, mode);
+    } catch {
+      // ignore
+    }
+  }
+
+  private renderPreview() {
+    if (this.viewMode === 'editor') return;
+    if (!this.previewEl) return;
+    const parsed = marked.parse(this.value || '', {async: false});
+    this.previewEl.innerHTML = typeof parsed === 'string' ? parsed : '';
+  }
+
+  private handleInput = () => {
+    this.value = this.textarea.value;
+    this.emit('zn-input');
+    if (this.debounceTimer) clearTimeout(this.debounceTimer);
+    this.debounceTimer = setTimeout(() => this.renderPreview(), 150);
+  };
+
+  private handleChange = () => {
+    this.value = this.textarea.value;
+    this.emit('zn-change');
+    this.renderPreview();
+  };
+
+  private handleViewToggle = (e: Event) => {
+    const host = (e.target as HTMLElement).closest<HTMLElement>('[data-mode]');
+    const mode = host?.dataset.mode as ViewMode | undefined;
+    if (!mode || mode === this.viewMode) return;
+    this.viewMode = mode;
+  };
+
+  private handleExpandToggle = () => {
+    this.expanded = !this.expanded;
+  };
+
+  @watch('viewMode', {waitUntilFirstUpdate: true})
+  async handleViewModeChange() {
+    await this.updateComplete;
+    this.writeStoredViewMode(this.viewMode);
+    this.renderPreview();
+    this.dispatchEvent(new CustomEvent('zn-view-mode-change', {
+      bubbles: true,
+      composed: true,
+      detail: {mode: this.viewMode},
+    }));
+  }
+
+  @watch('value', {waitUntilFirstUpdate: true})
+  async handleValueChange() {
+    await this.updateComplete;
+    this.formControlController.updateValidity();
+    this.renderPreview();
+  }
+
+  @watch('markedReady', {waitUntilFirstUpdate: true})
+  handleMarkedReady() {
+    this.renderPreview();
+  }
+
+  render() {
+    const hasLabelSlot = this.hasSlotController.test('label');
+    const hasHelpSlot = this.hasSlotController.test('help-text');
+    const hasLabel = !!this.label || hasLabelSlot;
+    const hasHelpText = !!this.helpText || hasHelpSlot;
+    const showEditor = this.viewMode === 'editor' || this.viewMode === 'split';
+    const showPreview = this.viewMode === 'preview' || this.viewMode === 'split';
+
+    return html`
+      <div part="base"
+           class=${classMap({
+             'markdown-editor': true,
+             'markdown-editor--expanded': this.expanded,
+             'markdown-editor--split': this.viewMode === 'split',
+             'markdown-editor--preview-only': this.viewMode === 'preview',
+           })}>
+        ${hasLabel ? html`
+          <label class="markdown-editor__label">
+            <slot name="label">${this.label}</slot>
+          </label>` : ''}
+
+        <div part="toolbar" class="markdown-editor__toolbar">
+          <zn-button-group class="markdown-editor__view-toggle" @click=${this.handleViewToggle}>
+            ${VIEW_MODES.map(v => this.renderViewButton(v.mode, v.icon, v.label))}
+          </zn-button-group>
+          <zn-button
+            class="markdown-editor__expand-btn"
+            type="button"
+            size="medium"
+            color="secondary"
+            icon=${this.expanded ? 'close_fullscreen' : 'open_in_full'}
+            icon-size="18"
+            tooltip=${this.expanded ? 'Collapse' : 'Expand'}
+            @click=${this.handleExpandToggle}
+          ></zn-button>
+        </div>
+
+        <div class="markdown-editor__body">
+          <div part="editor"
+               class="markdown-editor__editor"
+               ?hidden=${!showEditor}>
+            <zn-textarea
+              .value=${this.value}
+              name=${this.name || ''}
+              placeholder=${this.placeholder}
+              rows=${this.rows}
+              resize="auto"
+              ?required=${this.required}
+              ?readonly=${this.readonly}
+              ?disabled=${this.disabled}
+              @zn-input=${this.handleInput}
+              @zn-change=${this.handleChange}
+            ></zn-textarea>
+          </div>
+          <div part="preview"
+               class="markdown-editor__preview-wrapper"
+               ?hidden=${!showPreview}>
+            <div class="markdown-editor__preview"></div>
+          </div>
+        </div>
+
+        ${hasHelpText ? html`
+          <div class="markdown-editor__help-text">
+            <slot name="help-text">${this.helpText}</slot>
+          </div>` : ''}
+      </div>
+    `;
+  }
+
+  private renderViewButton(mode: ViewMode, icon: string, label: string) {
+    const isActive = this.viewMode === mode;
+    return html`
+      <zn-button
+        class=${classMap({
+          'markdown-editor__view-btn': true,
+          'markdown-editor__view-btn--active': isActive,
+        })}
+        data-mode=${mode}
+        type="button"
+        size="medium"
+        color="default"
+        ?outline=${!isActive}
+        square
+        icon=${icon}
+        icon-size="18"
+        tooltip=${label}
+        aria-pressed=${isActive ? 'true' : 'false'}
+      ></zn-button>
+    `;
+  }
+}