components

4.5 KB

1. # Modal
3. A window over the page with a title, a × and any content; the page behind is dimmed, blocked and does not scroll.
4. Esc, the × and a click on the dim background close it (the background click can be switched off); buttons in a footer
5. close it too. The focus stays inside while it is open and goes back to the element that opened it. The page opens and
6. closes it and is told **how** it was closed. Demo: `/modal` (https://components.hybriel.worldapi.org/modal).
8. Pure Hybriel: one file, `modal.hl`, with its own `Style`; no JavaScript file. It is the browser's own `<dialog>` opened
9. with `showModal()` (page behind inert, focus in, focus back), plus Tab / Shift+Tab going round inside, the reasons, the
10. background click and the scroll lock.
12. ## Use it in an app
14. Copy `components/modal/modal.hl` (optionally `shared/tokens.hl` for the app's own accent), then:
16. ```
17. import Modal from './modal.hl'
19. String result = ''
21. View {
22. page { on close(e) { emit pageClosed(e) }
23. button { type = "button" "Delete…" on click(e) { emit pageAsk(e) } }
24. Modal { id = "confirm" title = "Delete the draft?"
25. p { "This cannot be undone." }
26. footer {
27. button { type = "button" value = "cancel" "Cancel" }
28. button { type = "button" value = "ok" "Delete" }
29. }
30. }
31. }
32. }
34. on pageAsk(e) { document.getElementById('confirm').showModal() }
35. on pageClosed(e) { if (e.detail.id == 'confirm' && e.detail.reason == 'ok') { result = 'deleted' } }
36. ```
38. ## Attributes
39. | Attribute | Meaning |
40. |---|---|
41. | `id` | the id of the `<dialog>`: the page opens / closes it by this id (required when there are several) — default `modal` |
42. | `title` | the heading of the window (also its `aria-label`) |
43. | `backdropClose` | `"false"` = a click on the dim background does NOT close it (default `"true"`) |
44. | `closeLabel` | the tooltip / label of the × (default `Close`) |
45. | content | everything written inside `Modal { … }` is the content (the host's content: its handlers and members are the page's) |
47. Write every attribute as a **literal** (`title = "…"`): then several modals stand on one page, each with its own values.
48. (A composed component's members are the page's state; bound to a changing member, all modals would share it.)
50. ## Footer buttons
51. A `footer { … }` inside the content is the footer: laid out at the bottom right, sticky under a long content, the last
52. button is the main one (accent colour; black without a theme). A click on a footer button closes the modal with the button's `value` as the
53. reason (no `value` → its text). A footer button may have its own `on click` (the page's handler): it runs first, and when
54. it closes the modal itself with `close('saved')`, that reason wins (the demo's "Save"). A button that must keep the modal
55. open (e.g. a check that fails) goes in the content, not in the `footer`.
57. ## Open and close from the page
58. - open: `document.getElementById('<id>').showModal()` in any handler (the focused element — usually the button that was
59. clicked — gets the focus back when it closes).
60. - close: `document.getElementById('<id>').close('<reason>')` — the reason is what the page is told.
62. ## Events
63. When it closes, a **bubbling `close` event** is sent from `<modal-dialog>`; catch it on any element around the modal:
64. `on close(e) { … }`.
66. | `e.detail.reason` | how it was closed |
67. |---|---|
68. | `close` | the × |
69. | `escape` | the Esc key |
70. | `backdrop` | a click on the dim background |
71. | the button's `value` (or text) | a footer button |
72. | whatever the page passed | `close('<reason>')` from the page |
74. `e.detail.id` is the modal's id. (A custom event name such as `modalclose` would be nicer, but hl:web binds only
75. standard DOM event names — hybriel ticket #31 — so it is `close`.)
77. ## Behaviour
78. - The page behind is inert (no clicks, no focus) and does not scroll (`html { overflow: hidden }` while one is open).
79. - The window stays inside the screen (at most the screen height minus 2rem); a long content scrolls inside it.
80. - A press that starts inside the window and ends on the background (selecting text) does not close it.
81. - Phone: the window is the screen width minus 1rem each side.
82. - Colours are the semantic tokens with a black/white/grey fallback (the base look is black, white and greys (no frames; root README "Look"); an app that declares the WorldAPI tokens (layouts.worldapi.org's theme) restyles it): a white window on the grey dimmed page; buttons have no border.
84. ## Not yet
85. Open / close animation; stacking one modal on top of another is untested; the page cannot bind the modal's `open` state
86. as a member (it opens it with `showModal()`).