components

5.3 KB

1. # Markdown editor
3. A Markdown field you edit **visually**: headings look like headings, **bold** is bold, lists are lists — while you type.
4. The value stays **plain Markdown**. A port of `worldapi-components/md-editor.js` as a pure Hybriel component: no JavaScript
5. of its own. Demo: `/md-editor`.
7. Use it in a page:
9. ```
10. import MdEditor from './md-editor.hl'
12. form { method = "post" action = "/save"
13. MdEditor { name = "summary" value = "# Title" }
14. }
15. ```
17. ## Files
18. Copy `md-editor.hl` (one file; it has its own `Style`). Nothing else. It needs the WorldAPI colour tokens only as an option:
19. every colour is `var(--color-…, <base value>)`, so an app that declares the tokens (and its `--color-accent`) wins and
20. an app without them shows the base look (black, white, greys, no frames — root README "Look").
22. ## Attributes
23. | Attribute | Meaning |
24. |---|---|
25. | `name` | the field name the Markdown posts under (default `markdown`) |
26. | `value` | the start Markdown |
27. | `placeholder` | the grey text of an empty editor (default `Write…`) |
28. | `rows` | the height of the source view (default 6) |
30. ## Reading the value
31. The Markdown lives in a hidden `<input name="…">` inside `<md-editor>`. It posts with the form, and every change fires a
32. bubbling DOM `input` event on that input: a wrapper element catches it with `on input(e) { text = e.target.value }`
33. (`e.target.name` says which editor, when there are several). A host cannot read a child member (hybriel#87), so the DOM
34. event is the way out.
36. ## What it makes (the Markdown tickets renders)
37. Headings `#`…`######` (toolbar: H cycles paragraph → H1 → H2 → H3), paragraphs (a single line break is kept), `-` / `1.` lists
38. (one level), fenced code blocks, `` `code` ``, links `[text](url)` / `<https://…>` / bare `https://…` (only `http(s)://`,
39. `mailto:`, `/path`, `#anchor` become links), *em*, **strong**. Images `![alt](address)` (http(s) or a `/path`; no `data:` / `javascript:`). Nothing else (quotes, tables, nesting, HTML) can be made;
40. pasted text is read as Markdown and pasted HTML is kept as plain text.
42. ## Keyboard and toolbar (the toolbar also works on a phone)
43. | Action | Keys | Toolbar |
44. |---|---|---|
45. | bold / italic / inline code | Ctrl+B / Ctrl+I / Ctrl+E (Cmd on Mac) | B, I, `<>` |
46. | link (add / change / remove) | Ctrl+K | Link → small form (Enter applies, Esc closes) |
47. | heading 1/2/3, paragraph | Ctrl+Alt+1/2/3, Ctrl+Alt+0 | H |
48. | bulleted / numbered list | Ctrl+Shift+8 / Ctrl+Shift+7 | • List, 1. List |
49. | code block | Ctrl+Alt+C | Block |
50. | undo / redo | Ctrl+Z / Ctrl+Shift+Z | ↶ ↷ |
51. | send the form | Ctrl+Enter | |
52. | line break inside a paragraph | Shift+Enter | |
54. **Typing Markdown formats it**: `# `, `- `, `* `, `1. ` at the start of a line make a heading / list; ```` ``` ```` + Enter a code
55. block; a closed `**x**`, `*x*`, `_x_`, `` `x` `` becomes formatted (Ctrl+Z turns it back). Backspace at the start of a heading /
56. list item / code block makes it a paragraph. Ctrl/Cmd+click opens a link.
58. ## Files and images
59. Drop files on the editor, paste them, or press **File** in the toolbar (several at once). Each file is sent to the app with
60. `emit server mdUpload(files)` — the framework uploads it over HTTP in parts and a progress bar per file shows under the toolbar
61. (`on client uploadProgress`). The **app decides where files are stored**: it must answer that face, or the upload fails
62. ("The upload failed." under the toolbar). The face gets a list of `{ bytes, name, type, size }` and returns a list of addresses,
63. one per file, in order. An image (`image/*`) lands in the text as `![name](address)` and is drawn; any other file as `[name](address)`.
64. Dropped files land where they were dropped, pasted / chosen ones at the caret (or at the end).
66. ```
67. on server mdUpload(files) {
68. let urls = []
69. for (f of files) { writeFile('storage/files/' + f.name, f.bytes) urls.push('/files/' + f.name) }
70. return urls
71. }
72. ```
73. The app also sets `uploadMax` on `WebFramework` (default 1 GiB) and serves the address (`directory` route). Demo: `demo.hl` (the site's `lib/uploads.hl`) keeps
74. files 24 h in `storage/md-files` under a random name, with a known extension only, served with `nosniff` + `sandbox`.
76. ## Markdown source
77. A "Markdown source" button in the footer switches the field to a plain textarea holding the raw Markdown (for copying it
78. out or pasting a larger text in) and back to "Visual editor"; switching back reads the typed text again.
80. ## How it is built (and its limits)
81. - The formatted surface is a `contenteditable` element; its content is built with `createElement` / text nodes only (never
82. `innerHTML` of user text) and is never re-rendered by the framework. Hybriel has no mount event, so a 100 ms CSS animation
83. on the surface fires `animationiteration` once the page is live and that hands the editor its first content.
84. - An untouched value is returned byte for byte; a changed value is written in one canonical form (`*em*`, `**strong**`, `- item`,
85. `1. item`, ```` ``` ```` fences, backslash escapes where needed). What Markdown cannot hold is dropped (empty paragraphs).
86. - Not ported from the JS version: the `<textarea>` "enhance" mode, `disabled` / `readonly` / `toolbar="none"`, the `[text](url)`
87. typing rule, per-block byte-for-byte spelling, and the `MdEditor.markdown` test API.
88. - Undo / redo is the browser's own; typing rules and the toolbar use the browser's editing commands so they undo.