@liquefy/cascade.ui 1.0.0 → 2.0.0

package/src/Popover.js

@@ -1,158 +1,174 @@
-import { Component, frozen, callback } from "@liquefy/cascade.component";
-import { div } from "@liquefy/cascade.dom";
-import { overlay } from "./Overlay.js";
-import { zStack, wrapper, fitContainerStyle, zStackElementStyle } from "./Layout.js";
-
-/**
- * Popover - ported from flow.ui/basic/src/popover.js: content shown next to
- * something on the page (an information button, say), over everything
- * else, closed by clicking anywhere outside it.
- *
- *  - anchor: what it points to - an element (typically what was clicked:
- *    `event.currentTarget`), or a rectangle in viewport coordinates. An
- *    element it follows: while it's shown, a resize of the window, or a
- *    scroll, places it again, where the element now is - watched in the
- *    frames after, for as long as it keeps moving, so whatever lays out
- *    again on the same resize has done so, however late (a toolbar moving
- *    the button it was opened from, say). A rectangle stays put.
- *  - showing, close: whether it's shown, and what a click outside it calls.
- *  - style, children: the popover's own content (usually a card or an
- *    alert), and extra style for the box it's placed in.
- *
- * Flow measured the popover's own size to place it; here it's placed by
- * which quarter of the window its anchor is in instead - below the anchor
- * when that's in the upper half, above it otherwise, and aligned to the
- * anchor's left or right edge, whichever is further from the window's
- * edge - so it never needs measuring, and so never needs a second pass.
- * Shown through overlay() - the nearest OverlayFrame shows it.
- */
-export function popover(...parameters) {
-  return new Popover(...parameters);
-}
-
-const GAP = 6;
-
-export class Popover extends Component {
-  setProperties({ anchor, showing, close, style, children }) {
-    this.anchor = frozen(anchor || null);
-    this.showing = !!showing;
-    this.close = close || null;
-    this.style = frozen(style || null);
-    this.popoverChildren = frozen(children || []);
-  }
-
-  // `moved`: counts the frames after a resize or a scroll, while it's
-  // shown and anchored to an element - so it's built, and placed, again
-  // (see follow()).
-  initializeState() {
-    return { moved: 0 };
-  }
-
-  initialUnobservables() {
-    return { following: null };
-  }
-
-  // Where the anchor is now - or, for an element no longer in the page (a
-  // theme switch replacing the button, say), where it last was.
-  anchorRect() {
-    const anchor = this.anchor;
-    if (!anchor) return { left: 0, top: 0, right: 0, bottom: 0 };
-    if (typeof(anchor.getBoundingClientRect) !== "function") return anchor;
-    const u = this.unobservable;
-    if (anchor.isConnected || !u.lastAnchorRect) u.lastAnchorRect = anchor.getBoundingClientRect();
-    return u.lastAnchorRect;
-  }
-
-  // Following an element: while shown, on a resize or a scroll, place again
-  // - in the frames after, whenever the element has moved.
-  follow() {
-    const u = this.unobservable;
-    if (u.following) return;
-    const view = document.defaultView;
-    const later = view.requestAnimationFrame ? (action) => view.requestAnimationFrame(action) : (action) => setTimeout(action, 0);
-    // Watched frame by frame, until it has held still for a few: what moves
-    // it may lay out again later than the next frame - a bounds provider's
-    // ResizeObserver, say, which runs after animation frames.
-    const sameRect = (a, b) => a && b && a.left === b.left && a.top === b.top && a.right === b.right && a.bottom === b.bottom;
-    let watching = false;
-    let stillFrames = 0;
-    const watch = () => {
-      if (!u.following) { watching = false; return; }
-      const anchor = this.anchor;
-      const rect = anchor && anchor.isConnected && typeof(anchor.getBoundingClientRect) === "function" ? anchor.getBoundingClientRect() : null;
-      // Placed again if the element has moved - or the window has changed
-      // size: a placement from its right or bottom edge moves along with it.
-      const viewportChanged = u.placedViewport !== view.innerWidth + "x" + view.innerHeight;
-      if ((rect && !sameRect(rect, u.lastAnchorRect)) || viewportChanged) {
-        stillFrames = 0;
-        this.moved = this.moved + 1;
-      } else stillFrames++;
-      if (stillFrames < 3) later(watch);
-      else watching = false;
-    };
-    const moved = () => {
-      stillFrames = 0;
-      if (watching) return;
-      watching = true;
-      later(watch);
-    };
-    view.addEventListener("resize", moved);
-    document.addEventListener("scroll", moved, true);
-    u.following = () => {
-      view.removeEventListener("resize", moved);
-      document.removeEventListener("scroll", moved, true);
-    };
-  }
-
-  unfollow() {
-    const u = this.unobservable;
-    if (!u.following) return;
-    u.following();
-    u.following = null;
-  }
-
-  onHide() {
-    this.unfollow();
-  }
-
-  onDispose() {
-    super.onDispose();
-    this.unfollow();
-  }
-
-  placement() {
-    const anchor = this.anchorRect();
-    const view = document.defaultView;
-    const width = view ? view.innerWidth : 1024;
-    const height = view ? view.innerHeight : 768;
-    this.unobservable.placedViewport = width + "x" + height;
-    const placement = {};
-    if ((anchor.top + anchor.bottom) / 2 < height / 2) placement.top = anchor.bottom + GAP + "px";
-    else placement.bottom = height - anchor.top + GAP + "px";
-    if ((anchor.left + anchor.right) / 2 < width / 2) placement.left = anchor.left + "px";
-    else placement.right = width - anchor.right + "px";
-    return placement;
-  }
-
-  build() {
-    this.moved; // Placed again when its anchor element has moved - see follow().
-    const followsElement = this.anchor !== null && typeof(this.anchor.getBoundingClientRect) === "function";
-    if (this.showing && followsElement) this.follow();
-    else this.unfollow();
-    return overlay(
-      { key: "overlay", showing: this.showing },
-      zStack(
-        { key: "layer", style: { ...fitContainerStyle, pointerEvents: "none" } },
-        div({
-          key: "outside",
-          onmousedown: callback("outside", () => this.close && this.close()),
-          style: { ...zStackElementStyle, pointerEvents: "auto" },
-        }),
-        wrapper(
-          { key: "content", style: { position: "fixed", pointerEvents: "auto", maxWidth: "min(800px, 90vw)", ...this.placement(), ...this.style } },
-          this.popoverChildren,
-        ),
-      ),
-    );
-  }
-}
+import { Component, frozen, callback, withoutRecording } from "@liquefy/cascade.component";
+import { div } from "@liquefy/cascade.dom";
+import { overlay } from "./Overlay.js";
+import { zStack, wrapper, fitContainerStyle } from "./Layout.js";
+
+/**
+ * Popover - ported from flow.ui/basic/src/popover.js: content shown next to
+ * something on the page (an information button, say), over everything
+ * else, closed by clicking anywhere outside it.
+ *
+ *  - anchor: what it points to - an element (typically what was clicked:
+ *    `event.currentTarget`), or a rectangle in viewport coordinates. An
+ *    element it follows: while it's shown, a resize of the window, or a
+ *    scroll, places it again, where the element now is - watched in the
+ *    frames after, for as long as it keeps moving, so whatever lays out
+ *    again on the same resize has done so, however late (a toolbar moving
+ *    the button it was opened from, say). A rectangle stays put.
+ *  - showing, close: whether it's shown, and what a click outside it calls.
+ *  - style, children: the popover's own content (usually a card or an
+ *    alert), and extra style for the box it's placed in.
+ *
+ * Flow measured the popover's own size to place it; here it's placed by
+ * which quarter of the window its anchor is in instead - below the anchor
+ * when that's in the upper half, above it otherwise, and aligned to the
+ * anchor's left or right edge, whichever is further from the window's
+ * edge - so it never needs measuring, and so never needs a second pass.
+ * Shown through overlay() - the nearest OverlayFrame shows it.
+ */
+export function popover(...parameters) {
+  return new Popover(...parameters);
+}
+
+const GAP = 6;
+
+export class Popover extends Component {
+  setProperties({ anchor, showing, close, style, children }) {
+    this.anchor = frozen(anchor || null);
+    this.showing = !!showing;
+    this.close = close || null;
+    this.style = frozen(style || null);
+    this.popoverChildren = frozen(children || []);
+  }
+
+  // `moved`: counts the frames after a resize or a scroll, while it's
+  // shown and anchored to an element - so it's built, and placed, again
+  // (see follow()).
+  initialState() {
+    return { moved: 0 };
+  }
+
+  initialUnobservables() {
+    return { following: null };
+  }
+
+  // Where the anchor is now - or, for an element no longer in the page (a
+  // theme switch replacing the button, say), where it last was.
+  anchorRect() {
+    const anchor = this.anchor;
+    if (!anchor) return { left: 0, top: 0, right: 0, bottom: 0 };
+    if (typeof(anchor.getBoundingClientRect) !== "function") return anchor;
+    const u = this.unobservable;
+    if (anchor.isConnected || !u.lastAnchorRect) u.lastAnchorRect = anchor.getBoundingClientRect();
+    return u.lastAnchorRect;
+  }
+
+  // Following an element: while shown, on a resize or a scroll, place again
+  // - in the frames after, whenever the element has moved.
+  follow() {
+    const u = this.unobservable;
+    if (u.following) return;
+    const view = document.defaultView;
+    const later = view.requestAnimationFrame ? (action) => view.requestAnimationFrame(action) : (action) => setTimeout(action, 0);
+    // Watched frame by frame, until it has held still for a few: what moves
+    // it may lay out again later than the next frame - a bounds provider's
+    // ResizeObserver, say, which runs after animation frames.
+    const sameRect = (a, b) => a && b && a.left === b.left && a.top === b.top && a.right === b.right && a.bottom === b.bottom;
+    let watching = false;
+    let stillFrames = 0;
+    const watch = () => {
+      if (!u.following) { watching = false; return; }
+      const anchor = this.anchor;
+      const rect = anchor && anchor.isConnected && typeof(anchor.getBoundingClientRect) === "function" ? anchor.getBoundingClientRect() : null;
+      // Placed again if the element has moved - or the window has changed
+      // size: a placement from its right or bottom edge moves along with it.
+      const viewportChanged = u.placedViewport !== view.innerWidth + "x" + view.innerHeight;
+      if ((rect && !sameRect(rect, u.lastAnchorRect)) || viewportChanged) {
+        stillFrames = 0;
+        this.moved = this.moved + 1;
+      } else stillFrames++;
+      if (stillFrames < 3) later(watch);
+      else watching = false;
+    };
+    const moved = () => {
+      stillFrames = 0;
+      if (watching) return;
+      watching = true;
+      later(watch);
+    };
+    view.addEventListener("resize", moved);
+    document.addEventListener("scroll", moved, true);
+    u.following = () => {
+      view.removeEventListener("resize", moved);
+      document.removeEventListener("scroll", moved, true);
+    };
+  }
+
+  unfollow() {
+    const u = this.unobservable;
+    if (!u.following) return;
+    u.following();
+    u.following = null;
+  }
+
+  onHide() {
+    this.unfollow();
+  }
+
+  // Shown again (its page switched back to, say): an up-to-date build
+  // doesn't rerun, so follow the element again here. Read without
+  // recording - this runs inside whoever is rendering.
+  onShow() {
+    withoutRecording(() => {
+      if (this.showing && this.followsElement()) this.follow();
+    });
+  }
+
+  followsElement() {
+    return this.anchor !== null && typeof(this.anchor.getBoundingClientRect) === "function";
+  }
+
+  onDispose() {
+    super.onDispose();
+    this.unfollow();
+  }
+
+  placement() {
+    const anchor = this.anchorRect();
+    const view = document.defaultView;
+    const width = view ? view.innerWidth : 1024;
+    const height = view ? view.innerHeight : 768;
+    this.unobservable.placedViewport = width + "x" + height;
+    const placement = {};
+    if ((anchor.top + anchor.bottom) / 2 < height / 2) placement.top = anchor.bottom + GAP + "px";
+    else placement.bottom = height - anchor.top + GAP + "px";
+    if ((anchor.left + anchor.right) / 2 < width / 2) placement.left = anchor.left + "px";
+    else placement.right = width - anchor.right + "px";
+    return placement;
+  }
+
+  build() {
+    this.moved; // Placed again when its anchor element has moved - see follow().
+    const followsElement = this.followsElement();
+    if (this.showing && followsElement) this.follow();
+    else this.unfollow();
+    return overlay(
+      { key: "overlay", showing: this.showing },
+      zStack(
+        { key: "layer", style: { ...fitContainerStyle, pointerEvents: "none" } },
+        div({
+          key: "outside",
+          onmousedown: callback("outside", () => this.close && this.close()),
+          style: { pointerEvents: "auto" },
+        }),
+        // Its own size and place - not the whole layer, as the zStack gives
+        // its children (see zStackElementStyle): stretched, the invisible
+        // rest of the box would catch the clicks meant for outside it.
+        wrapper(
+          { key: "content", style: { position: "fixed", top: "auto", left: "auto", width: "auto", height: "auto", pointerEvents: "auto", maxWidth: "min(800px, 90vw)", ...this.placement(), ...this.style } },
+          this.popoverChildren,
+        ),
+      ),
+    );
+  }
+}

package/src/index.js

@@ -1,5 +1,6 @@
 export { OverlayFrame, overlayFrame } from "./OverlayFrame.js";
 export { Overlay, overlay } from "./Overlay.js";
+export { ModalBackdrop, Modal, ModalAssembly, modalBackdrop, modal, modalAssembly, modalBackdropColor } from "./Modal.js";
 export {
   flexContainerStyle, rowStyle, columnStyle,
   centerStyle, middleStyle, centerMiddleStyle,
@@ -7,9 +8,9 @@ export {
   layoutBorderStyle, overflowVisibleStyle, zStackElementStyle,
   wrapper, row, column, center, middle, centerMiddle, filler, zStack,
 } from "./Layout.js";
-export { widget, button, icon, iconButton, card, controlPanel, alert, listItem, dialog, textField, checkbox, colorField, tabBar, alertSeverities, toButtonProperties } from "./widgets.js";
+export { widget, button, icon, iconButton, card, controlPanel, alert, listItem, dialog, textField, checkbox, colorField, tabBar, alertSeverities, toButtonProperties, keyAsLabel } from "./widgets.js";
 export { popover } from "./Popover.js";
-export { portal, portalContents, Portal, PortalContents } from "./Portal.js";
+export { Dropdown, dropdown } from "./Dropdown.js";
 export { BasicThemeServiceLocator, basicTheme, basicShadow } from "./BasicTheme.js";
 export {
   ColorScheme, ColorSchemeScope, colorSchemeScope, currentColorScheme, themeColor, deriveColors, colorVariables, defaultColors,

package/src/widgets.js

@@ -1,109 +1,127 @@
-import { toProperties, toPropertiesWithChildren, findImplicitChildren, locateService } from "@liquefy/cascade.component";
-import { defaultDOMServiceLocator } from "@liquefy/cascade.dom";
-
-/**
- * Themed widgets - ported from flow.ui/themed: app code calls `button(...)`
- * and gets whatever the current theme provides for it, found through the
- * service locator in the render context (see cascade.component's
- * ServiceLocator.js) as `{ type: "widget", name: "button", properties }`.
- * Which theme that is, is decided by whoever set up the render context -
- * the app, or a subtree overriding it (serviceProvider()) - never by the
- * component using the widget.
- *
- * Each widget has a property contract every theme implements, so switching
- * themes changes appearance, not meaning:
- *
- *  - button: `key`, `onClick`, `disabled`, `variant` ("filled" for the
- *    main thing to do - what else a theme knows is up to it), `style`, `children` - with
- *    flow's own argument convention, a loose function argument is
- *    `onClick` and anything else loose is a child:
- *    `button("Save", () => save())`.
- *  - icon: `key`, `name` (a Material icon name - "info", "close",
- *    "shopping_cart", ...), `style` (fontSize sets its size). Both themes
- *    draw icons with Google's icon fonts, which the app links (see
- *    cascade.application/demo/index.html).
- *  - iconButton: `key`, `icon` (an icon name), `onClick` (or a loose
- *    function), `title`, `style` - a round button showing just an icon.
- *  - card: `key`, `variant` ("elevated" - the default - "filled" or
- *    "outlined"), `style`, `children` - a surface to group content on.
- *  - controlPanel: `key`, `style`, `children` - controls in a row (buttons,
- *    fields, a label), on a surface of their own, spaced evenly and
- *    wrapping when there isn't room: what a page puts its controls in, so
- *    they sit apart from what they control.
- *  - alert: `key`, `severity` ("info" - the default - "success",
- *    "warning" or "error"), `style`, `children` - a message with its
- *    severity's icon and colors (see alertSeverities).
- *  - listItem: `key`, `active`, `onClick` (or a loose function),
- *    `style`, `children` - one clickable row of a list, marked when active.
- *  - dialog: `key`, `title`, `close` (called by its close button),
- *    `fullScreen`, `style`, `children` - a dialog's own box: title bar,
- *    close button and body. Full screen, it fills whatever it's placed in,
- *    as a phone app's screen does: no corners, no shadow, and a back arrow
- *    at the top left (calling `close`) instead of the close button. Where it's shown (docked, or modal over the app) is up to
- *    whoever places it - see cascade.ui's overlay().
- *  - textField: `key`, `label` (optional), `placeholder`, `value`, `onInput` (called with the new
- *    value, as text), `type` ("text" - the default - or "number"), `unit`
- *    (shown after the value: "kg"), `error` (a message, shown under it,
- *    marking it as wrong), `style` - a labelled input field.
- *  - checkbox: `key`, `label`, `checked`, `onChange` (called with whether
- *    it's now checked), `style`.
- *  - colorField: `key`, `label`, `value` (a hex color: "#34495e"),
- *    `onInput` (called with the new one, as it's being picked), `style` - a
- *    color, and the browser's own picker for it.
- *  - tabBar: `key`, `tabs` (`[{ key, title }]`), `selected` (a tab's key),
- *    `onSelect` (called with the key of the tab clicked), `style` - a row of
- *    tabs, one of them selected. What each shows is up to whoever places it.
- *
- * Widgets that are more than one element (an alert: icon plus message) are
- * components of their own in each theme, so the keys inside them are
- * scoped to them rather than to whoever builds them - two alerts on one
- * page don't collide.
- *
- * No theme in the context providing a widget falls back to the DOM
- * default, which ends in a visible, warning placeholder (see
- * DOMDebugServiceLocator) rather than an error.
- */
-
-export function toButtonProperties(parameters) {
-  const properties = toProperties(parameters);
-  const content = properties.componentContent;
-  if (content) {
-    const handlers = content.filter((item) => typeof(item) === "function");
-    if (handlers.length > 1) throw new Error("button(): only one loose onClick function allowed.");
-    if (handlers.length === 1) {
-      if (properties.onClick) throw new Error("button(): onClick given both loosely and in properties.");
-      properties.onClick = handlers[0];
-    }
-    const rest = content.filter((item) => typeof(item) !== "function");
-    if (rest.length > 0) properties.componentContent = rest;
-    else delete properties.componentContent;
-  }
-  findImplicitChildren(properties);
-  return properties;
-}
-
-export function widget(name, properties) {
-  return locateService({ type: "widget", name, properties }, defaultDOMServiceLocator);
-}
-
-export const button = (...parameters) => widget("button", toButtonProperties(parameters));
-export const icon = (...parameters) => widget("icon", toProperties(parameters));
-export const iconButton = (...parameters) => widget("iconButton", toButtonProperties(parameters));
-export const card = (...parameters) => widget("card", toPropertiesWithChildren(parameters));
-export const controlPanel = (...parameters) => widget("controlPanel", toPropertiesWithChildren(parameters));
-export const alert = (...parameters) => widget("alert", toPropertiesWithChildren(parameters));
-export const listItem = (...parameters) => widget("listItem", toButtonProperties(parameters));
-export const dialog = (...parameters) => widget("dialog", toPropertiesWithChildren(parameters));
-export const textField = (...parameters) => widget("textField", toProperties(parameters));
-export const checkbox = (...parameters) => widget("checkbox", toProperties(parameters));
-export const colorField = (...parameters) => widget("colorField", toProperties(parameters));
-export const tabBar = (...parameters) => widget("tabBar", toProperties(parameters));
-
-// Each alert severity's icon and colors - the same in every theme, so a
-// warning reads as a warning whichever one is in use.
-export const alertSeverities = {
-  info: { icon: "info", background: "#f0f8ff", iconColor: "rgb(2, 136, 209)", color: "rgb(1, 67, 97)" },
-  success: { icon: "check_circle", background: "#edf7ed", iconColor: "rgb(46, 125, 50)", color: "rgb(30, 70, 32)" },
-  warning: { icon: "warning", background: "#fff4e5", iconColor: "rgb(237, 108, 2)", color: "rgb(102, 60, 0)" },
-  error: { icon: "error", background: "#fdeded", iconColor: "rgb(211, 47, 47)", color: "rgb(95, 33, 32)" },
-};
+import { toProperties, toPropertiesWithChildren, findImplicitChildren, locateService } from "@liquefy/cascade.component";
+import { defaultDOMServiceLocator, text } from "@liquefy/cascade.dom";
+
+/**
+ * Themed widgets - ported from flow.ui/themed: app code calls `button(...)`
+ * and gets whatever the current theme provides for it, found through the
+ * service locator in the render context (see cascade.component's
+ * ServiceLocator.js) as `{ type: "widget", name: "button", properties }`.
+ * Which theme that is, is decided by whoever set up the render context -
+ * the app, or a subtree overriding it (serviceProvider()) - never by the
+ * component using the widget.
+ *
+ * Each widget has a property contract every theme implements, so switching
+ * themes changes appearance, not meaning:
+ *
+ *  - button: `key`, `onClick`, `disabled`, `variant` ("filled" for the
+ *    main thing to do - what else a theme knows is up to it), `style`, `children` - with
+ *    flow's own argument convention, a loose function argument is
+ *    `onClick` and anything else loose is a child:
+ *    `button("Save", () => save())`.
+ *  - icon: `key`, `name` (a Material icon name - "info", "close",
+ *    "shopping_cart", ...), `style` (fontSize sets its size). Both themes
+ *    draw icons with Google's icon fonts, which the app links (see
+ *    cascade.application/demo/index.html).
+ *  - iconButton: `key`, `icon` (an icon name), `onClick` (or a loose
+ *    function), `title`, `disabled`, `style` - a round button showing just
+ *    an icon.
+ *  - card: `key`, `variant` ("elevated" - the default - "filled" or
+ *    "outlined"), `style`, `children` - a surface to group content on.
+ *  - controlPanel: `key`, `style`, `children` - controls in a row (buttons,
+ *    fields, a label), on a surface of their own, spaced evenly and
+ *    wrapping when there isn't room: what a page puts its controls in, so
+ *    they sit apart from what they control.
+ *  - alert: `key`, `severity` ("info" - the default - "success",
+ *    "warning" or "error"), `style`, `children` - a message with its
+ *    severity's icon and colors (see alertSeverities).
+ *  - listItem: `key`, `active`, `onClick` (or a loose function),
+ *    `style`, `children` - one clickable row of a list, marked when active.
+ *  - dialog: `key`, `title`, `close` (called by its close button),
+ *    `fullScreen`, `style`, `children` - a dialog's own box: title bar,
+ *    close button and body. Full screen, it fills whatever it's placed in,
+ *    as a phone app's screen does: no corners, no shadow, and a back arrow
+ *    at the top left (calling `close`) instead of the close button. Where it's shown (docked, or modal over the app) is up to
+ *    whoever places it - see cascade.ui's overlay().
+ *  - textField: `key`, `label` (optional), `placeholder`, `value`, `onInput` (called with the new
+ *    value, as text), `type` ("text" - the default - or "number"), `unit`
+ *    (shown after the value: "kg"), `error` (a message, shown under it,
+ *    marking it as wrong), `style` - a labelled input field.
+ *  - checkbox: `key`, `label`, `checked`, `onChange` (called with whether
+ *    it's now checked), `style`.
+ *  - colorField: `key`, `label`, `value` (a hex color: "#34495e"),
+ *    `onInput` (called with the new one, as it's being picked), `style` - a
+ *    color, and the browser's own picker for it.
+ *  - tabBar: `key`, `tabs` (`[{ key, title }]`), `selected` (a tab's key),
+ *    `onSelect` (called with the key of the tab clicked), `style` - a row of
+ *    tabs, one of them selected. What each shows is up to whoever places it.
+ *
+ * Widgets that are more than one element (an alert: icon plus message) are
+ * components of their own in each theme, so the keys inside them are
+ * scoped to them rather than to whoever builds them - two alerts on one
+ * page don't collide.
+ *
+ * No theme in the context providing a widget falls back to the DOM
+ * default, which ends in a visible, warning placeholder (see
+ * DOMDebugServiceLocator) rather than an error.
+ */
+
+export function toButtonProperties(parameters) {
+  const properties = toProperties(parameters);
+  const content = properties.componentContent;
+  if (content) {
+    const handlers = content.filter((item) => typeof(item) === "function");
+    if (handlers.length > 1) throw new Error("button(): only one loose onClick function allowed.");
+    if (handlers.length === 1) {
+      if (properties.onClick) throw new Error("button(): onClick given both loosely and in properties.");
+      properties.onClick = handlers[0];
+    }
+    const rest = content.filter((item) => typeof(item) !== "function");
+    if (rest.length > 0) properties.componentContent = rest;
+    else delete properties.componentContent;
+  }
+  findImplicitChildren(properties);
+  return properties;
+}
+
+// A button given nothing to show - `button("save", () => save())`, where
+// the leading lowercase string is its key (see cascade.component's
+// implicitProperties.js) - shows its key as its label, as words:
+// "save" -> "Save", "openDialog" -> "Open dialog".
+function withKeyAsLabel(properties) {
+  const hasContent = (properties.children && properties.children.length > 0) || (properties.componentContent && properties.componentContent.length > 0);
+  if (!hasContent && typeof(properties.key) === "string" && properties.key !== "") {
+    properties.children = [text({ key: properties.key + ".label", text: keyAsLabel(properties.key) })];
+  }
+  return properties;
+}
+
+export function keyAsLabel(key) {
+  const words = key.replace(/([a-z0-9])([A-Z])/g, "$1 $2").replace(/[-_]+/g, " ").trim().toLowerCase();
+  return words.charAt(0).toUpperCase() + words.slice(1);
+}
+
+export function widget(name, properties) {
+  return locateService({ type: "widget", name, properties }, defaultDOMServiceLocator);
+}
+
+export const button = (...parameters) => widget("button", withKeyAsLabel(toButtonProperties(parameters)));
+export const icon = (...parameters) => widget("icon", toProperties(parameters));
+export const iconButton = (...parameters) => widget("iconButton", toButtonProperties(parameters));
+export const card = (...parameters) => widget("card", toPropertiesWithChildren(parameters));
+export const controlPanel = (...parameters) => widget("controlPanel", toPropertiesWithChildren(parameters));
+export const alert = (...parameters) => widget("alert", toPropertiesWithChildren(parameters));
+export const listItem = (...parameters) => widget("listItem", toButtonProperties(parameters));
+export const dialog = (...parameters) => widget("dialog", toPropertiesWithChildren(parameters));
+export const textField = (...parameters) => widget("textField", toProperties(parameters));
+export const checkbox = (...parameters) => widget("checkbox", toProperties(parameters));
+export const colorField = (...parameters) => widget("colorField", toProperties(parameters));
+export const tabBar = (...parameters) => widget("tabBar", toProperties(parameters));
+
+// Each alert severity's icon and colors - the same in every theme, so a
+// warning reads as a warning whichever one is in use.
+export const alertSeverities = {
+  info: { icon: "info", background: "#f0f8ff", iconColor: "rgb(2, 136, 209)", color: "rgb(1, 67, 97)" },
+  success: { icon: "check_circle", background: "#edf7ed", iconColor: "rgb(46, 125, 50)", color: "rgb(30, 70, 32)" },
+  warning: { icon: "warning", background: "#fff4e5", iconColor: "rgb(237, 108, 2)", color: "rgb(102, 60, 0)" },
+  error: { icon: "error", background: "#fdeded", iconColor: "rgb(211, 47, 47)", color: "rgb(95, 33, 32)" },
+};