@liquefy/cascade.ui 1.0.0 → 2.0.0

package/README.md

@@ -1,6 +1,6 @@
 # cascade.ui
 
-Themed widgets, layout, overlays, portals, popovers and color schemes for
+Themed widgets, layout, overlays, modals, popovers and color schemes for
 [Cascade](https://github.com/erobwen/liquefy#readme) - and its basic theme.
 
 ```console
@@ -61,13 +61,32 @@ import { button, currentColorScheme } from "@liquefy/cascade.ui";
 // button giving it another base color. Everything inside a
 // colorSchemeScope() of that theme follows (put one around your app).
 const scheme = currentColorScheme();
-return button({ key: "green" }, text({ key: "greenText", text: "Go green" }), () => { scheme.base = "#2e7d32"; });
+return button(text("Go green"), () => { scheme.base = "#2e7d32"; });
 ```
 
 ## Layout and the rest
 
 - `row`, `column`, `filler`, `centerMiddle`, `zStack`, ... and their styles
   (`fillerStyle`, `fitContainerStyle`, ...).
-- `overlayFrame()` and `overlay()` - modal content over the app.
+- `overlayFrame()` and `overlay()` - content over the app, shown from
+  wherever it's built: any content, custom or animated. One overlay per
+  frame: an overlay shown on a frame already showing another evicts it (the
+  other isn't shown again until it's shown anew). Overlays stack across
+  frames - one opened from inside another's content - not side by side on
+  one. By design, for now: this may change should a use case turn up that
+  needs several on one frame.
+- `modalAssembly()` - what an `overlay()` usually shows: a backdrop (a click
+  on it closes) and the content in a centered window - full screen, without
+  the backdrop, in a frame narrower than `fullScreenBelow`, and a themed
+  `dialog()` in it follows, back arrow and all. Its parts on their own:
+  `modalBackdrop()` and `modal()`.
+
+  ```js
+  overlay({ showing: this.open },
+    modalAssembly({ close, width: 360, fullScreenBelow: 600 },
+      dialog({ title: "Settings", close }, ...)))
+  ```
 - `popover()` - beside an element, following it when it moves.
-- `portal()` and `portalContents()` - content placed somewhere else in the tree.
+- `dropdown({ options, value, onSelect })` - one choice out of several: a button
+  showing it, opening a list of them all in a popover. Made of the theme's own
+  button, card and list items; an option's `style` previews it in the list.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@liquefy/cascade.ui",
-  "version": "1.0.0",
-  "description": "Themed widgets, layout, overlays, portals, popovers and color schemes for Cascade - and its basic theme.",
+  "version": "2.0.0",
+  "description": "Themed widgets, layout, overlays, modals, popovers, a dropdown and color schemes for Cascade - and its basic theme.",
   "keywords": [
     "reactive",
     "ui",
@@ -32,9 +32,9 @@
     "url": "https://github.com/erobwen/liquefy/issues"
   },
   "homepage": "https://github.com/erobwen/liquefy/tree/main/cascade.ui#readme",
-  "dependencies": {
-    "@liquefy/cascade.component": "^1.0.0",
-    "@liquefy/cascade.dom": "^1.0.0"
+  "peerDependencies": {
+    "@liquefy/cascade.component": "^2.0.0",
+    "@liquefy/cascade.dom": "^2.0.0"
   },
   "devDependencies": {
     "mocha": "^10.8.2",

package/src/BasicTheme.js

@@ -55,8 +55,9 @@ const styleSheet = `
   width: 36px; height: 36px; padding: 0; margin: 0; border: none; border-radius: 6px;
   color: inherit; background: transparent; cursor: pointer; transition: background-color 0.15s;
 }
-.cb-icon-button:hover { background: rgba(127, 150, 175, 0.18); }
-.cb-icon-button:active { background: rgba(127, 150, 175, 0.32); }
+.cb-icon-button:hover:not(:disabled) { background: rgba(127, 150, 175, 0.18); }
+.cb-icon-button:active:not(:disabled) { background: rgba(127, 150, 175, 0.32); }
+.cb-icon-button:disabled { opacity: 0.38; cursor: default; }
 .cb-list-item { padding: 8px 12px; border-radius: 6px; cursor: pointer; user-select: none; transition: background-color 0.15s; }
 .cb-list-item:hover { background: ${c.accentFaint}; }
 .cb-list-item.cb-active { background: ${c.accentSoft}; font-weight: bold; }
@@ -154,14 +155,17 @@ class BasicDialog extends Component {
   setProperties({ title, close, fullScreen, style, children }) {
     this.title = title || "";
     this.close = close || null;
-    this.fullScreen = !!fullScreen;
+    // Given, or - unset - as the modal() it's shown in presents it (see
+    // cascade.ui's Modal.js).
+    this.fullScreen = typeof(fullScreen) === "boolean" ? fullScreen : null;
     this.style = frozen(style || null);
     this.dialogChildren = frozen(children || []);
   }
 
   build() {
+    const fullScreen = this.fullScreen !== null ? this.fullScreen : this.inherit("modalPresentation") === "fullScreen";
     const close = callback("close", () => this.close && this.close());
-    const frame = this.fullScreen
+    const frame = fullScreen
       ? { width: "100%", height: "100%" }
       : { borderRadius: "10px", boxShadow: dialogShadow };
     return column(
@@ -173,16 +177,16 @@ class BasicDialog extends Component {
         {
           key: "titleBar",
           style: {
-            padding: this.fullScreen ? "6px 16px 6px 6px" : "6px 6px 6px 16px",
-            ...(this.fullScreen ? { minHeight: "48px" } : {}),
+            padding: fullScreen ? "6px 16px 6px 6px" : "6px 6px 6px 16px",
+            ...(fullScreen ? { minHeight: "48px" } : {}),
             background: c.chromeDark, color: c.onChrome, flex: "none", alignItems: "center", gap: "8px", fontWeight: "bold",
           },
         },
-        iconButton({ key: "back", icon: "arrow_back", title: "Back", onClick: close }).show(this.fullScreen),
+        iconButton({ key: "back", icon: "arrow_back", title: "Back", onClick: close }).showIf(fullScreen),
         // text(): a lone string starting lowercase (a file name, say)
         // would be taken for an implicit key.
         filler({ key: "title" }, text({ key: "titleText", text: this.title })),
-        iconButton({ key: "close", icon: "close", title: "Close", onClick: close }).show(!this.fullScreen),
+        iconButton({ key: "close", icon: "close", title: "Close", onClick: close }).showIf(!fullScreen),
       ),
       // Sized by its content, scrolling once the dialog has a height of its own.
       column({ key: "body", style: { flex: "1 1 auto", minHeight: 0, overflow: "auto" } }, this.dialogChildren),
@@ -208,7 +212,7 @@ class BasicTextField extends Component {
     ensureStyleSheet();
     return htmlLabel(
       { key: "field", style: { display: "flex", flexDirection: "column", gap: "4px", ...this.style } },
-      span({ key: "label", style: { fontSize: "13px", opacity: 0.8 } }, text({ key: "labelText", text: this.label })).show(!!this.label),
+      span({ key: "label", style: { fontSize: "13px", opacity: 0.8 } }, text({ key: "labelText", text: this.label })).showIf(!!this.label),
       row(
         { key: "inputRow", style: { alignItems: "center", gap: "6px" } },
         htmlInput({
@@ -222,7 +226,7 @@ class BasicTextField extends Component {
         }),
         this.unit ? span({ key: "unit" }, text({ key: "unitText", text: this.unit })) : null,
       ),
-      div({ key: "error", style: { fontSize: "12px", color: c.error } }, text({ key: "errorText", text: this.error || "" })).show(!!this.error),
+      div({ key: "error", style: { fontSize: "12px", color: c.error } }, text({ key: "errorText", text: this.error || "" })).showIf(!!this.error),
     );
   }
 }

package/src/Dropdown.js

@@ -0,0 +1,84 @@
+import { Component, frozen, callback } from "@liquefy/cascade.component";
+import { span, text } from "@liquefy/cascade.dom";
+import { button, icon, card, listItem } from "./widgets.js";
+import { popover } from "./Popover.js";
+
+/**
+ * Dropdown - one choice out of several, compactly: a button showing the
+ * choice made, opening a list of them all below it (a popover - see
+ * Popover.js). Made of the theme's own widgets - button, card, list
+ * items - so it looks like the rest of whatever theme it's in.
+ *
+ *   dropdown({
+ *     options: [{ value: "Title", label: "Title", style: { fontWeight: 700 } }, ...],
+ *     value: "Title",
+ *     onSelect: (value) => ...,
+ *   })
+ *
+ *  - options: `{ value, label, style }` - `style`, if given, is the label's
+ *    own in the list: a preview of what choosing it means (a font, say).
+ *  - value: the option chosen - none shows `placeholder`.
+ *  - onSelect(value): called with the option clicked; the list closes.
+ *  - disabled, title, placeholder, style (the button's).
+ */
+export function dropdown(...parameters) {
+  return new Dropdown(...parameters);
+}
+
+export class Dropdown extends Component {
+  setProperties({ options, value, onSelect, disabled, title, placeholder, style }) {
+    this.options = frozen(options || []);
+    this.value = value;
+    this.onSelect = onSelect || null;
+    this.disabled = !!disabled;
+    this.title = title || undefined;
+    this.placeholder = placeholder || "";
+    this.style = frozen(style || null);
+  }
+
+  initialState() {
+    return { open: false, anchor: null };
+  }
+
+  choose(value) {
+    this.open = false;
+    if (this.onSelect) this.onSelect(value);
+  }
+
+  build() {
+    // Disabled while open: closed, for good - not hidden only to pop open on
+    // its own again once it's enabled.
+    if (this.disabled && this.open) this.setState({ open: false });
+    const chosen = this.options.find((option) => option.value === this.value);
+    return [
+      button(
+        {
+          disabled: this.disabled,
+          title: this.title,
+          style: { justifyContent: "space-between", gap: "4px", paddingRight: "6px", ...this.style },
+          onClick: callback("toggle", (event) => {
+            // The button itself - the list follows it, should it move.
+            this.anchor = event.currentTarget;
+            this.open = !this.open;
+          }),
+        },
+        text(chosen ? chosen.label : this.placeholder),
+        icon({ name: "arrow_drop_down" }),
+      ),
+      popover(
+        { anchor: this.anchor, showing: this.open, close: callback("close", () => { this.open = false; }) },
+        card(
+          { style: { padding: "4px", display: "flex", flexDirection: "column", gap: "2px", minWidth: "160px", maxHeight: "60vh", overflowY: "auto", boxShadow: "0 4px 16px rgba(0, 0, 0, 0.25)" } },
+          this.options.map((option) => listItem(
+            {
+              key: "option" + option.value,
+              active: option.value === this.value,
+              onClick: callback("choose" + option.value, () => this.choose(option.value)),
+            },
+            span({ style: option.style || {} }, text(option.label)),
+          )),
+        ),
+      ),
+    ];
+  }
+}

package/src/Layout.js

@@ -1,120 +1,153 @@
-import { toPropertiesWithChildren } from "@liquefy/cascade.component";
-import { div } from "@liquefy/cascade.dom";
-
-/**
- * Layout - ported from flow.ui/basic/src/Layout.js: a small kit of style
- * constants plus the styled-div functions built from them, all following
- * the same unwritten flow convention every component's own doc in this
- * codebase now points back to (see cascade.DOM/src/applyStyle.js): every
- * one of these takes an optional `style` property, merged as
- * `{...ownDefault, ...style}` - the caller's own value always wins - and
- * applied straight onto the one div each of these builds, not onto some
- * further wrapper. That's the actual mechanism behind "extra divs are
- * usually unnecessary": a creator styles its child directly, including
- * fitting it into a flex row/column or making it fill its container,
- * instead of wrapping it in a div dedicated to just that.
- *
- * Two style families here, not one "fillStyle": fitContainerStyle sizes by
- * *absolute* dimensions (width/height: 100% of the parent's own box, no
- * flex participation implied), fillerStyle sizes by *flex* participation
- * (flexGrow/Shrink: 1, flexBasis: 0 - takes an equal share of whatever
- * room a flex row/column has left). Reach for fitContainerStyle when the
- * parent isn't a flex container (or you want 100% regardless of flex
- * distribution) and fillerStyle when it is and you want this child to
- * share/absorb the remaining space with its siblings.
- *
- * One deliberate correction from flow's own copy: flow.ui/basic/src/Layout.js's
- * own flexContainerStyle sets `justifyContent: "flexStart"` - not valid CSS
- * (camelCase is for the *property* name in a JS style object, not a
- * property's *value* - the real value is the kebab-case string
- * "flex-start"). Harmless there in practice (an invalid value is simply
- * ignored, and justify-content's own initial value, "normal", already packs
- * items at the start for ordinary content) but not worth reproducing
- * knowingly - fixed here to the real value.
- *
- * flow's own componentTypeName argument to styledDiv() (purely a debug-id
- * label, baked into flow.core's own aggregateToString()-style element id)
- * isn't ported - cascade.DOM's DOMElementComponent doesn't have an equivalent
- * hook yet (setProperties() has no special case for it, so passing one
- * through today would just land as a meaningless "componenttypename" DOM
- * attribute instead). Every element built here still gets a real, unique
- * debug id from DOMNodeRenderComponent's own aggregateToString() fallback
- * (this.constructor.name-based) - just not one that says "row" vs "column".
- */
-
-// --- Basic layout styles ---
-
-export const flexContainerStyle = {
-  overflow: "hidden",
-  boxSizing: "border-box",
-  display: "flex",
-  alignItems: "stretch",
-  justifyContent: "flex-start",
-  whiteSpace: "normal",
-  userSelect: "none",
-};
-
-export const rowStyle = { ...flexContainerStyle, flexDirection: "row" };
-export const columnStyle = { ...flexContainerStyle, flexDirection: "column" };
-
-export const centerStyle = { ...rowStyle, justifyContent: "center", alignItems: "stretch" };
-export const middleStyle = { ...columnStyle, justifyContent: "center", alignItems: "stretch" };
-export const centerMiddleStyle = { ...rowStyle, justifyContent: "center", alignItems: "center" };
-
-// --- Basic element styles ---
-
-// For a bottom-up component inside a scroll container - sized by its own
-// content, not stretched or shrunk to fit.
-export const naturalSizeStyle = { overflow: "visible", flexGrow: "0", flexShrink: "0", flexBasis: "auto" };
-
-// Fill 100% of the parent's own box - absolute sizing, no flex participation
-// implied (works inside or outside a flex container).
-export const fitContainerStyle = { overflow: "hidden", boxSizing: "border-box", width: "100%", height: "100%" };
-
-// Grow/shrink to take an equal share of whatever room is left in a flex
-// row/column, ignoring its own content's natural size - scroll panels,
-// equal space distribution.
-export const fillerStyle = { overflow: "hidden", boxSizing: "border-box", flexGrow: "1", flexShrink: "1", flexBasis: "0" };
-
-// Same, but based on its own content's natural size rather than an equal
-// 0-basis share - grows/shrinks around whatever it would naturally be.
-export const autoFillerStyle = { overflow: "hidden", boxSizing: "border-box", flexGrow: "1", flexShrink: "1", flexBasis: "auto" };
-
-// Visualizes a component's own bounds during development - not meant to
-// ship.
-export const layoutBorderStyle = { borderStyle: "solid", borderColor: "light-gray", borderWidth: "1px", boxSizing: "border-box" };
-
-// Opts back out of fitContainerStyle/fillerStyle's own overflow: hidden -
-// for content that must be allowed to overflow its own box (an animation,
-// a popover, ...).
-export const overflowVisibleStyle = { overflow: "visible" };
-
-// --- styledDiv: the shared mechanism behind every function below ---
-
-// A div (asked for through the service locator, like any div() call) with
-// `defaultStyle` merged underneath whatever `style` property is given, so
-// the caller's own value always wins (see this file's own class doc).
-function styledDiv(defaultStyle, parameters) {
-  const properties = toPropertiesWithChildren(parameters);
-  properties.style = { ...defaultStyle, ...properties.style };
-  return div(properties);
-}
-
-// --- Basic layout containers ---
-
-export const wrapper = (...parameters) => styledDiv({}, parameters);
-export const row = (...parameters) => styledDiv(rowStyle, parameters);
-export const column = (...parameters) => styledDiv(columnStyle, parameters);
-export const center = (...parameters) => styledDiv(centerStyle, parameters);
-export const middle = (...parameters) => styledDiv(middleStyle, parameters);
-export const centerMiddle = (...parameters) => styledDiv(centerMiddleStyle, parameters);
-
-// --- Basic layout fillers ---
-
-export const filler = (...parameters) => styledDiv(fillerStyle, parameters);
-
-// --- zStack: children stacked on top of each other, edge to edge ---
-
-export const zStackElementStyle = { ...fitContainerStyle, position: "absolute", top: 0, left: 0, width: "100%", height: "100%" };
-
-export const zStack = (...parameters) => styledDiv({ position: "relative" }, parameters);
+import { toPropertiesWithChildren } from "@liquefy/cascade.component";
+import { div } from "@liquefy/cascade.dom";
+
+/**
+ * Layout - ported from flow.ui/basic/src/Layout.js: a small kit of style
+ * constants plus the styled-div functions built from them, all following
+ * the same unwritten flow convention every component's own doc in this
+ * codebase now points back to (see cascade.DOM/src/applyStyle.js): every
+ * one of these takes an optional `style` property, merged as
+ * `{...ownDefault, ...style}` - the caller's own value always wins - and
+ * applied straight onto the one div each of these builds, not onto some
+ * further wrapper. That's the actual mechanism behind "extra divs are
+ * usually unnecessary": a creator styles its child directly, including
+ * fitting it into a flex row/column or making it fill its container,
+ * instead of wrapping it in a div dedicated to just that.
+ *
+ * Two style families here, not one "fillStyle": fitContainerStyle sizes by
+ * *absolute* dimensions (width/height: 100% of the parent's own box, no
+ * flex participation implied), fillerStyle sizes by *flex* participation
+ * (flexGrow/Shrink: 1, flexBasis: 0 - takes an equal share of whatever
+ * room a flex row/column has left). Reach for fitContainerStyle when the
+ * parent isn't a flex container (or you want 100% regardless of flex
+ * distribution) and fillerStyle when it is and you want this child to
+ * share/absorb the remaining space with its siblings.
+ *
+ * One deliberate correction from flow's own copy: flow.ui/basic/src/Layout.js's
+ * own flexContainerStyle sets `justifyContent: "flexStart"` - not valid CSS
+ * (camelCase is for the *property* name in a JS style object, not a
+ * property's *value* - the real value is the kebab-case string
+ * "flex-start"). Harmless there in practice (an invalid value is simply
+ * ignored, and justify-content's own initial value, "normal", already packs
+ * items at the start for ordinary content) but not worth reproducing
+ * knowingly - fixed here to the real value.
+ *
+ * flow's own componentTypeName argument to styledDiv() (purely a debug-id
+ * label, baked into flow.core's own aggregateToString()-style element id)
+ * isn't ported - cascade.DOM's DOMElementComponent doesn't have an equivalent
+ * hook yet (setProperties() has no special case for it, so passing one
+ * through today would just land as a meaningless "componenttypename" DOM
+ * attribute instead). Every element built here still gets a real, unique
+ * debug id from DOMNodeComponent's own aggregateToString() fallback
+ * (this.constructor.name-based) - just not one that says "row" vs "column".
+ */
+
+// --- Basic layout styles ---
+
+// No overflow: hidden, unlike flow's: flow clipped every layout container,
+// for a strict top-down layout that made bounds easier to calculate further
+// down - measured bounds (cascade.dom's elementBoundsProvider()) do that job
+// now. What it did for flex layout is kept, though: min-width/min-height 0
+// let a container shrink below its content's size in the row or column
+// it's in (flex items don't, by default - they'd push the row wider
+// instead). Its content then overflows, visibly, where it doesn't fit;
+// clip it where that's wanted (overflow: "hidden" in its style). And text
+// in it can be selected, like text anywhere else.
+const shrinkable = { minWidth: 0, minHeight: 0 };
+
+export const flexContainerStyle = {
+  ...shrinkable,
+  boxSizing: "border-box",
+  display: "flex",
+  alignItems: "stretch",
+  justifyContent: "flex-start",
+  whiteSpace: "normal",
+};
+
+export const rowStyle = { ...flexContainerStyle, flexDirection: "row" };
+export const columnStyle = { ...flexContainerStyle, flexDirection: "column" };
+
+export const centerStyle = { ...rowStyle, justifyContent: "center", alignItems: "stretch" };
+export const middleStyle = { ...columnStyle, justifyContent: "center", alignItems: "stretch" };
+export const centerMiddleStyle = { ...rowStyle, justifyContent: "center", alignItems: "center" };
+
+// --- Basic element styles ---
+
+// For a bottom-up component inside a scroll container - sized by its own
+// content, not stretched or shrunk to fit.
+export const naturalSizeStyle = { overflow: "visible", flexGrow: "0", flexShrink: "0", flexBasis: "auto" };
+
+// Fill 100% of the parent's own box - absolute sizing, no flex participation
+// implied (works inside or outside a flex container).
+export const fitContainerStyle = { ...shrinkable, boxSizing: "border-box", width: "100%", height: "100%" };
+
+// Grow/shrink to take an equal share of whatever room is left in a flex
+// row/column, ignoring its own content's natural size - scroll panels,
+// equal space distribution.
+export const fillerStyle = { ...shrinkable, boxSizing: "border-box", flexGrow: "1", flexShrink: "1", flexBasis: "0" };
+
+// Same, but based on its own content's natural size rather than an equal
+// 0-basis share - grows/shrinks around whatever it would naturally be.
+export const autoFillerStyle = { ...shrinkable, boxSizing: "border-box", flexGrow: "1", flexShrink: "1", flexBasis: "auto" };
+
+// Visualizes a component's own bounds during development - not meant to
+// ship.
+export const layoutBorderStyle = { borderStyle: "solid", borderColor: "lightgray", borderWidth: "1px", boxSizing: "border-box" };
+
+// Content allowed to overflow its own box - what every layout container
+// here does already (there's no clipping by default any more); kept for
+// what's written against the old default.
+export const overflowVisibleStyle = { overflow: "visible" };
+
+// --- styledDiv: the shared mechanism behind every function below ---
+
+// A div (asked for through the service locator, like any div() call) with
+// `defaultStyle` merged underneath whatever `style` property is given, so
+// the caller's own value always wins (see this file's own class doc).
+function styledDiv(defaultStyle, parameters) {
+  const properties = toPropertiesWithChildren(parameters);
+  properties.style = { ...defaultStyle, ...properties.style };
+  return div(properties);
+}
+
+// --- Basic layout containers ---
+
+export const wrapper = (...parameters) => styledDiv({}, parameters);
+export const row = (...parameters) => styledDiv(rowStyle, parameters);
+export const column = (...parameters) => styledDiv(columnStyle, parameters);
+export const center = (...parameters) => styledDiv(centerStyle, parameters);
+export const middle = (...parameters) => styledDiv(middleStyle, parameters);
+export const centerMiddle = (...parameters) => styledDiv(centerMiddleStyle, parameters);
+
+// --- Basic layout fillers ---
+
+export const filler = (...parameters) => styledDiv(fillerStyle, parameters);
+
+// --- zStack: children stacked on top of each other, edge to edge ---
+
+// What each child of a zStack gets - by the zStack itself (a class, and a
+// stylesheet rule for its direct children), so its children need no style
+// of their own for it. A child's own style still wins: it can deviate.
+export const zStackElementStyle = { ...fitContainerStyle, position: "absolute", top: 0, left: 0, width: "100%", height: "100%" };
+
+const zStackClass = "cascade-z-stack";
+const documentsStyled = new WeakSet();
+
+function ensureZStackRule() {
+  if (typeof(document) === "undefined" || !document.head || documentsStyled.has(document)) return;
+  documentsStyled.add(document);
+  const element = document.createElement("style");
+  element.setAttribute("data-cascade-layout", "");
+  element.textContent = "." + zStackClass + " > * { position: absolute; top: 0; left: 0; width: 100%; height: 100%; box-sizing: border-box; min-width: 0; min-height: 0; }";
+  document.head.appendChild(element);
+}
+
+export const zStack = (...parameters) => {
+  ensureZStackRule();
+  const properties = toPropertiesWithChildren(parameters);
+  const given = properties.className || properties.class;
+  delete properties.className;
+  properties.class = given ? zStackClass + " " + given : zStackClass;
+  properties.style = { position: "relative", ...properties.style };
+  return div(properties);
+};

package/src/Modal.js

@@ -0,0 +1,136 @@
+import { Component, frozen, observable, accessInitialValues, withoutRecording } from "@liquefy/cascade.component";
+import { div } from "@liquefy/cascade.dom";
+
+/**
+ * Modals - ready-made pieces for what an overlay() shows, each usable on
+ * its own:
+ *
+ *  - modalBackdrop({ close, style }): the dimmed layer behind a modal,
+ *    covering the frame; a click on it calls `close`.
+ *  - modal({ fullScreen, width, height, style }, content): places its
+ *    content in the frame - a window of the given size, centered, or
+ *    (`fullScreen`) filling the whole frame. The content fills it. What's
+ *    inside can tell which: modal() provides `modalPresentation`
+ *    ("window" or "fullScreen") - a themed dialog() goes full screen by
+ *    itself, back arrow and all.
+ *  - modalAssembly({ close, fullScreenBelow, width, height, backdrop }, content):
+ *    both - a backdrop (unless `backdrop: false`) and a modal - and full
+ *    screen, without a backdrop, while the frame is narrower than
+ *    `fullScreenBelow` (a phone's screen): it reads the frame's size where
+ *    it's shown (see OverlayFrame - a layer is a measured element).
+ *
+ * The ready-to-go way to show a dialog modally, then:
+ *
+ *   overlay({ showing: this.open },
+ *     modalAssembly({ close, fullScreenBelow: 600, width: 360 },
+ *       dialog({ title: "Settings", close }, ...)))
+ *
+ * And for anything else - an animated entrance, a sheet sliding up from
+ * below - overlay() takes any content at all, a backdrop of its own
+ * included.
+ */
+export function modalBackdrop(...parameters) {
+  return new ModalBackdrop(...parameters);
+}
+
+export function modal(...parameters) {
+  return new Modal(...parameters);
+}
+
+export function modalAssembly(...parameters) {
+  return new ModalAssembly(...parameters);
+}
+
+// The dimmed layer behind a modal - where a click closes it.
+export const modalBackdropColor = "rgba(0, 0, 0, 0.4)";
+
+const coverFrame = { position: "absolute", top: 0, left: 0, width: "100%", height: "100%", boxSizing: "border-box" };
+
+export class ModalBackdrop extends Component {
+  setProperties({ close, style }) {
+    this.close = close || null;
+    this.style = frozen(style || null);
+  }
+
+  build() {
+    return div({
+      onclick: this.close,
+      style: { ...coverFrame, pointerEvents: "auto", background: modalBackdropColor, ...this.style },
+    });
+  }
+}
+
+export class Modal extends Component {
+  setProperties({ fullScreen, width, height, style, children }) {
+    this.fullScreen = !!fullScreen;
+    this.width = typeof(width) === "number" ? width + "px" : (width || null);
+    this.height = typeof(height) === "number" ? height + "px" : (height || null);
+    this.style = frozen(style || null);
+    this.modalChildren = frozen(children || []);
+  }
+
+  // What's inside can tell how it's presented - not a size, a mode, the
+  // same for everything in it. An object of its own, rewritten at the
+  // baseline when it changes, as everything a context holds (see
+  // cascade.component's RenderContext.js).
+  provide() {
+    const u = this.unobservable;
+    if (!u.provided) u.provided = observable({ modalPresentation: this.presentation() });
+    return u.provided;
+  }
+
+  presentation() {
+    return this.fullScreen ? "fullScreen" : "window";
+  }
+
+  build() {
+    const presentation = this.presentation();
+    const provided = this.provide();
+    if (withoutRecording(() => provided.modalPresentation) !== presentation) {
+      accessInitialValues(() => { provided.modalPresentation = presentation; });
+    }
+    // The content fills whatever it's in: the frame, or the window.
+    const box = { display: "flex", flexDirection: "column", boxSizing: "border-box", pointerEvents: "auto" };
+    if (this.fullScreen) {
+      return div({ style: { ...coverFrame, ...box, ...this.style } }, this.modalChildren);
+    }
+    return div(
+      { style: { ...coverFrame, display: "flex", alignItems: "center", justifyContent: "center", pointerEvents: "none" } },
+      div(
+        { style: { ...box, width: this.width || "auto", height: this.height || "auto", maxWidth: "100%", maxHeight: "100%", ...this.style } },
+        this.modalChildren,
+      ),
+    );
+  }
+}
+
+export class ModalAssembly extends Component {
+  setProperties({ close, fullScreen, fullScreenBelow, width, height, backdrop, style, children }) {
+    this.close = close || null;
+    this.fullScreen = typeof(fullScreen) === "boolean" ? fullScreen : null;
+    this.fullScreenBelow = typeof(fullScreenBelow) === "number" ? fullScreenBelow : null;
+    this.width = width;
+    this.height = height;
+    this.backdrop = backdrop !== false;
+    this.style = frozen(style || null);
+    this.modalChildren = frozen(children || []);
+  }
+
+  // Full screen: as told - or below `fullScreenBelow`, by the width of the
+  // frame it's shown in (a measured layer - see OverlayFrame).
+  isFullScreen() {
+    if (this.fullScreen !== null) return this.fullScreen;
+    if (this.fullScreenBelow === null) return false;
+    const width = this.fromTarget("width");
+    return typeof(width) === "number" && width < this.fullScreenBelow;
+  }
+
+  build() {
+    const fullScreen = this.isFullScreen();
+    return [
+      // Keyed: left out while full screen, and kept.
+      modalBackdrop({ key: "backdrop", close: this.close }).showIf(this.backdrop && !fullScreen),
+      modal({ fullScreen, width: this.width, height: this.height, style: this.style }, this.modalChildren),
+    ];
+  }
+}