@mikedown/core 0.1.0 → 0.2.0

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog
 
+## 0.2.0
+
+- `bindMikeDownValue` (`@mikedown/core/binding`): the framework-neutral value binding the React, Vue, Angular and web component wrappers are built on (pristine writes, debounced change, flush on blur, read-only, disabled and touched state).
+- Editor options for `placeholder`, `id` and ARIA naming, and a landmark role on the editor.
+- The bound theme is re-applied only when it changes, which ends a theme update loop.
+- List markers are set explicitly, so page CSS resets can no longer strip bullets and numbers.
+- Completed task text uses the muted text color, keeping at least 4.5:1 contrast in light and dark themes.
+- Task checkboxes are named after their item for screen readers and have a 24 by 24px click and touch target.
+- Toolbar buttons that show text have screen reader names that start with that text; toolbar icons are hidden from assistive technology.
+- The floating table toolbar shows only while a focused cursor is in a table.
+- Toolbar buttons that don't fit move into a More (⋯) menu at the end of the toolbar instead of being cut off.
+
 ## 0.1.0
 
 First public release. The MikeDown WYSIWYG markdown editor as a framework-agnostic package, the same editor that ships in the MikeDown VS Code extension and MikeDown Desktop.

package/README.md

@@ -8,7 +8,7 @@ The MikeDown WYSIWYG markdown editor as a framework-agnostic package: TipTap (Pr
 npm install @mikedown/core
 ```
 
-Install the peer dependencies too (see [Peer dependencies](#peer-dependencies)). The package is ESM only.
+npm 7+ and pnpm 8+ install the peer dependencies for you (see [Peer dependencies](#peer-dependencies)); Yarn does not, so use the `yarn add` line under [Framework wrappers](#framework-wrappers). The package is ESM only.
 
 ## Minimal example
 
@@ -33,6 +33,36 @@ handle.destroy();
 
 The editor fills its container (`height: 100%`), so give the container a height. Without one the editor falls back to a `240px` minimum height; set `--mikedown-min-height` to change that floor.
 
+## Binding a value
+
+`bindMikeDownValue` is the glue a form field or framework wrapper needs, in one call. Import it from the package root or from `@mikedown/core/binding`.
+
+```ts
+import { bindMikeDownValue } from '@mikedown/core/binding';
+
+const field = bindMikeDownValue(container, {
+  initialValue: '# Hello',
+  debounceMs: 150,
+  onValue: (markdown) => save(markdown),
+  theme: 'auto',
+  darkSelector: 'html[data-mode=dark]',
+  id: 'notes',
+  ariaLabel: 'Meeting notes',
+  placeholder: 'Start writing…',
+});
+
+field.setValue(fromServer);   // loads pristine; skipped when equal to the current value
+field.flush();                // report a pending change now
+field.setTheme('dark');
+field.focus();
+field.handle;                 // the MikeDownEditorHandle
+field.destroy();              // flushes, then removes observers and listeners
+```
+
+- **Change reporting.** `onValue` fires after `debounceMs` of quiet and at once on blur. `outputTransform(markdown)` maps the text on its way out; `setValue` compares against its output.
+- **Theme.** `auto` is dark when the container or an ancestor matches `darkSelector` (it uses `closest()`, so both `html[data-mode=dark]` and a `.dark-theme` wrapper work), re-checked when attributes change. Without a selector it follows `prefers-color-scheme`.
+- **Accessibility.** `id`, `ariaLabel` and `ariaLabelledBy` go on the editable surface in both views (rich text and source). With only an `id`, the binding looks up `label[for=id]`, uses it as the name and focuses the editor when it is clicked. `ariaLabelledBy` is the sturdier choice. The accessible name follows ARIA's order: `aria-labelledby`, then `aria-label`, then `<label for>` elements. A bound editor drops `role="main"` (`landmark: false`), since a field is not a page landmark; the same `landmark`, `placeholder`, `id`, `ariaLabel` and `ariaLabelledBy` options exist on `createMikeDownEditor`.
+
 ## Host interface
 
 `options.host` is a `MikeDownHost`. Only `onChange` is required. Every other method is optional, and leaving one out turns its feature off and hides its UI. `NoopHost` is a ready-made host with just `onChange`.
@@ -121,7 +151,7 @@ The app must have exactly one copy of ProseMirror and CodeMirror, so these are p
 
 `tiptap-markdown`, `markdown-it-emoji`, `markdown-it-footnote`, `markdown-it-mark` and `nspell` are regular dependencies and install with the package.
 
-`katex` is a required peer because `styles.css` imports its stylesheet. `mermaid` is optional. Both are loaded with dynamic `import()` the first time a diagram or formula appears, so they stay out of your initial bundle. Without `mermaid` the diagram block shows an error or the raw source.
+`katex` is a required peer because `styles.css` imports its stylesheet. `mermaid` is optional. Both are loaded with dynamic `import()` the first time a diagram or formula appears, so they stay out of your initial bundle. Without `mermaid` the diagram block shows an error or the raw source. Install it anyway for Angular and Next.js (Turbopack) builds, which resolve the `import('mermaid')` at build time and fail without it; Vite builds pass.
 
 ## Bundler notes
 
@@ -134,6 +164,23 @@ The app must have exactly one copy of ProseMirror and CodeMirror, so these are p
 
 Mermaid renders SVG with `securityLevel: 'strict'` and loads its diagram types by dynamic `import()`. Your CSP needs `script-src 'self'` (or wherever your chunks are served from) and must allow inline styles for the SVG output (`style-src 'unsafe-inline'`, or a nonce on the style elements your bundler injects). A page that cannot allow this should set `features: { mermaid: false }`. KaTeX needs no script or eval permissions, only its stylesheet and fonts.
 
+## Framework wrappers
+
+- [`@mikedown/web-component`](https://www.npmjs.com/package/@mikedown/web-component): `<mikedown-editor>`, a form-associated custom element for plain HTML, CDN pages and server-rendered templates.
+- [`@mikedown/react`](https://www.npmjs.com/package/@mikedown/react): `MikeDownEditor` for React 18 and 19.
+- [`@mikedown/vue`](https://www.npmjs.com/package/@mikedown/vue): `MikeDownEditor` with `v-model` for Vue 3.3+.
+- [`@mikedown/angular`](https://www.npmjs.com/package/@mikedown/angular): a form control for Angular 17+.
+
+Each wrapper depends only on core and its framework. Yarn does not install peers, so list core's:
+
+```bash
+yarn add @mikedown/core @codemirror/commands @codemirror/lang-markdown @codemirror/language @codemirror/state @codemirror/theme-one-dark @codemirror/view @tiptap/core @tiptap/extension-code-block-lowlight @tiptap/extension-hard-break @tiptap/extension-highlight @tiptap/extension-image @tiptap/extension-link @tiptap/extension-placeholder @tiptap/extension-table @tiptap/extension-table-cell @tiptap/extension-table-header @tiptap/extension-table-row @tiptap/extension-task-item @tiptap/extension-task-list @tiptap/extension-text @tiptap/pm @tiptap/starter-kit katex lowlight mermaid
+```
+
+## Testing
+
+Use vitest with jsdom, stubbing `Range.prototype.getBoundingClientRect` and `getClientRects`. Jest: add `transformIgnorePatterns: ['/node_modules/(?!(@mikedown|lowlight|devlop)/)']` so the ESM-only packages in core's import graph get transformed (TipTap, CodeMirror and `tiptap-markdown` ship `require` builds). vitest is the recommended runner.
+
 ## Demo
 
 From a clone of the repository:
@@ -144,6 +191,20 @@ npm run demo:core
 
 This builds the package and serves `packages/core/demo/` with two editors side by side, a theme toggle, a "Log markdown" button and an `uploadImage` stub that returns an object URL.
 
+## Browser support
+
+Current Chrome, Edge, Firefox and Safari (ES2020 output, ESM only).
+
+## Privacy
+
+No telemetry. The editor makes no network calls except the ones you configure: spell check dictionaries (when `spellcheckDictionaryUrl` is set), your `host` callbacks, and the lazy `import()` of KaTeX and Mermaid from your own bundle.
+
+## Links
+
+- [Developers hub](https://www.iadev.net/mikedown/developers/)
+- [npm](https://www.npmjs.com/package/@mikedown/core)
+- [GitHub](https://github.com/mikejoseph23/mikedown/tree/main/packages/core)
+
 ## Build
 
 ```bash

package/dist/index.d.ts

@@ -353,6 +353,19 @@ interface MikeDownOptions {
      * the rich editor and source mode.
      */
     hostOwnsShortcuts?: boolean;
+    /** Empty-document placeholder. Default: "Type / for commands…" or "Start writing…". */
+    placeholder?: string;
+    /** `id` of the editable surface (the contenteditable, and the source view's content). */
+    id?: string;
+    /** Accessible name of the editable surface. Default "Document text". */
+    ariaLabel?: string;
+    /** Id of the element that names the editable surface. Wins over `ariaLabel`'s default. */
+    ariaLabelledBy?: string;
+    /**
+     * Put `role="main"` on the editor container. Default true (VS Code, Desktop).
+     * Embedded form fields pass false, since a field is not a page landmark.
+     */
+    landmark?: boolean;
 }
 type MikeDownCommand = 'toggleBold' | 'toggleItalic' | 'toggleStrike' | 'toggleHighlight' | 'toggleCode' | 'toggleBulletList' | 'toggleOrderedList' | 'toggleTaskList' | 'pasteWithoutFormatting' | 'openEmojiPicker' | 'undo' | 'redo' | 'toggleSource' | 'toggleSidebar' | 'openSettings' | 'copyAsRichText' | 'heading1' | 'heading2' | 'heading3' | 'heading4' | 'heading5' | 'heading6' | 'paragraph' | 'openFind' | 'openFindReplace' | 'insertTable' | 'insertLink' | 'insertImage' | 'zoomIn' | 'zoomOut' | 'zoomReset';
 type MikeDownEvent = 'change' | 'focus' | 'blur' | 'ready';
@@ -455,5 +468,57 @@ interface MikeDownEditorHandle {
 
 declare function createMikeDownEditor(container: HTMLElement, options: MikeDownOptions): MikeDownEditorHandle;
 
-export { DEFAULT_FEATURES, NoopHost, createMikeDownEditor };
-export type { BacklinkItem, DiffBaseline, ImageInsertResult, ImagePathMapping, ImageResizeRequest, ImageResizeResult, ImageUploadRequest, LinkCheckRequest, LinkOpenBehavior, LinkSuggestion, MikeDownCommand, MikeDownEditorHandle, MikeDownEvent, MikeDownFeatures, MikeDownHost, MikeDownOptions, MikeDownSettings, MikeDownSettingsPatch, MikeDownSettingsSection, MikeDownSettingsSectionBuild, MikeDownSettingsSectionContext, MikeDownSidebarPrefs, MikeDownStats, MikeDownViewState, NormalizationStyle, SidebarFooterLink, SidebarStateUpdate, TagCount, WikilinkResolution };
+/**
+ * Value binding for framework wrappers. Every wrapper (React, Vue, Angular,
+ * the web component) needs the same glue around the editor: a debounced change
+ * callback that reports at once on blur, external writes that load pristine and
+ * skip when nothing changed, a theme that can follow the page, and an accessible
+ * name for the editable surface. `bindMikeDownValue` holds it once.
+ */
+
+type BindingTheme = 'light' | 'dark' | 'auto';
+interface MikeDownBindingOptions extends Omit<MikeDownOptions, 'host' | 'initialMarkdown' | 'theme'> {
+    /** Loaded as the pristine baseline. Default ''. */
+    initialValue?: string;
+    /** Quiet time after the last keystroke before `onValue` fires. Default 150. 0 reports at once. */
+    debounceMs?: number;
+    /** Called with the markdown after the debounce, and at once on blur. Not called when the text equals the last value. */
+    onValue?: (markdown: string) => void;
+    /**
+     * Called when focus leaves the whole control (editor and toolbar), like a native input's blur. Moving into the
+     * core's menus and dialogs (`.mikedown-portal`) does not count. A pending change is flushed first.
+     */
+    onTouched?: () => void;
+    /** Start disabled. A disabled binding is read-only too. */
+    disabled?: boolean;
+    /** Default 'auto'. */
+    theme?: BindingTheme;
+    /**
+     * CSS selector for 'auto': dark when the container, or an ancestor, matches
+     * (`html[data-mode=dark]`, `.dark-theme`). Without it 'auto' follows
+     * `prefers-color-scheme`.
+     */
+    darkSelector?: string;
+    /** Maps the markdown on its way out (e.g. to preserve brackets). `setValue` compares against its output. */
+    outputTransform?: (markdown: string) => string;
+    /** Optional host methods (image upload, wikilinks, ...). `onChange` is run before the binding's own. */
+    host?: Partial<MikeDownHost>;
+}
+interface MikeDownBinding {
+    /** The underlying editor handle. */
+    readonly handle: MikeDownEditorHandle;
+    /** Load an external value as the pristine baseline. Skipped when it equals the current value. */
+    setValue(markdown: string): void;
+    /** Report a pending change now. */
+    flush(): void;
+    setTheme(theme: BindingTheme): void;
+    /** Read-only is `readOnly || disabled`. */
+    setReadOnly(readOnly: boolean): void;
+    setDisabled(disabled: boolean): void;
+    focus(): void;
+    destroy(): void;
+}
+declare function bindMikeDownValue(container: HTMLElement, options?: MikeDownBindingOptions): MikeDownBinding;
+
+export { DEFAULT_FEATURES, NoopHost, bindMikeDownValue, createMikeDownEditor };
+export type { BacklinkItem, BindingTheme, DiffBaseline, ImageInsertResult, ImagePathMapping, ImageResizeRequest, ImageResizeResult, ImageUploadRequest, LinkCheckRequest, LinkOpenBehavior, LinkSuggestion, MikeDownBinding, MikeDownBindingOptions, MikeDownCommand, MikeDownEditorHandle, MikeDownEvent, MikeDownFeatures, MikeDownHost, MikeDownOptions, MikeDownSettings, MikeDownSettingsPatch, MikeDownSettingsSection, MikeDownSettingsSectionBuild, MikeDownSettingsSectionContext, MikeDownSidebarPrefs, MikeDownStats, MikeDownViewState, NormalizationStyle, SidebarFooterLink, SidebarStateUpdate, TagCount, WikilinkResolution };