@morphemecms/cms 0.0.0-stage → 0.1.0

package/theme/ui/Toolbar.tsx

@@ -0,0 +1,67 @@
+// A toolbar (m3.material.io/components/toolbars, M3 Expressive; .toolbar in ../styles/ui.css): a row of actions (icon
+// buttons, buttons), docked (`kind`: docked, the default: the whole width at the bottom of the screen, as the site's bar
+// on a phone, components/ActionBar.astro) or floating (a pill over the page), in its colour
+// (`color`: standard, the surface, the default, or vibrant, the accent), across or, floating, `vertical`. A floating one
+// can be paired with a FAB (`fab`, the theme's Fab from @theme/ui/Fab: beside it, under a vertical one), and then
+// collapse into it (`expanded` false: only the FAB is shown, as while the page scrolls). Its kind and colour are
+// Material's names; how it looks is the theme's. Where it stands (fixed at the bottom of the screen, hidden while the
+// page scrolls) is the component's own. It is a role="toolbar" with its name (`label`): on the site
+// ui/toolbar.script.ts moves between its actions with the arrow keys (one stop for Tab). Other attributes (data-…) go
+// on it, and `className` after its own classes (with a FAB on the box round both). An Astro component gives an element
+// the same classes with toolbarClass (and role="toolbar" and its aria-label itself), and the box round it and its FAB
+// with toolbarWithFabClass.
+import type { ReactNode } from 'react';
+
+export type ToolbarKind = 'docked' | 'floating';
+export type ToolbarColor = 'standard' | 'vibrant';
+
+/** A toolbar's classes; `expanded` false: collapsed into its FAB. */
+export const toolbarClass = (kind: ToolbarKind = 'docked', color: ToolbarColor = 'standard', vertical = false, expanded = true) =>
+  `toolbar toolbar-${kind} toolbar-${color}${vertical && kind === 'floating' ? ' toolbar-vertical' : ''}${expanded ? '' : ' toolbar-collapsed'}`;
+
+/** The classes of the box round a floating toolbar and its FAB. */
+export const toolbarWithFabClass = (vertical = false) => `toolbar-with-fab${vertical ? ' toolbar-with-fab-vertical' : ''}`;
+
+export default function Toolbar({
+  label,
+  kind,
+  color,
+  vertical,
+  fab,
+  expanded = true,
+  className,
+  children,
+  ...rest
+}: {
+  label: string;
+  kind?: ToolbarKind;
+  color?: ToolbarColor;
+  vertical?: boolean;
+  fab?: ReactNode;
+  expanded?: boolean;
+  className?: string;
+  children: ReactNode;
+} & Record<string, unknown>) {
+  const floating = kind === 'floating';
+  const across = !(vertical && floating);
+  const paired = floating && fab;
+  const bar = (
+    <div
+      role="toolbar"
+      aria-label={label}
+      aria-orientation={across ? undefined : 'vertical'}
+      className={[toolbarClass(kind, color, vertical, !paired || expanded), !paired && className].filter(Boolean).join(' ')}
+      inert={paired && !expanded ? true : undefined}
+      {...rest}
+    >
+      {children}
+    </div>
+  );
+  if (!paired) return bar;
+  return (
+    <div className={[toolbarWithFabClass(!across), className].filter(Boolean).join(' ')}>
+      {bar}
+      {fab}
+    </div>
+  );
+}

package/theme/ui/Tooltip.tsx

@@ -0,0 +1,58 @@
+// A tooltip (m3.material.io/components/tooltips, .tooltip in ../styles/ui.css) on what it is about (`children`: one
+// element, a button or a link, which gets aria-describedby, so screen readers read the tooltip after its name). Plain
+// (`text`: a short label, e.g. on an icon button) or rich (`subhead`, `supportingText` and evt. an action, `action`, a
+// text button with its `label` and `href` or other attributes on it). Over its anchor, under it when there is no room
+// above. On the site ui/tooltip.script.ts shows it while the mouse is over its anchor (or over it) and while the anchor
+// has focus, and Escape hides it; without the script it shows on hover and focus by CSS. `open`: shown from the start
+// (in the editor, where it is only drawn). How it looks is the theme's (--tooltip-*).
+import { cloneElement, isValidElement, useId, type ReactElement, type ReactNode } from 'react';
+import Button from '@theme/ui/Button';
+
+export type TooltipAction = { label: string; href?: string } & Record<string, unknown>;
+
+/** A tooltip's classes, plain or rich. */
+export const tooltipClass = (rich?: boolean) => `tooltip ${rich ? 'tooltip-rich' : 'tooltip-plain'}`;
+
+export default function Tooltip({
+  text,
+  subhead,
+  supportingText,
+  action,
+  open,
+  className,
+  children,
+}: {
+  text?: ReactNode;
+  subhead?: ReactNode;
+  supportingText?: ReactNode;
+  action?: TooltipAction;
+  open?: boolean;
+  className?: string;
+  children: ReactElement<{ 'aria-describedby'?: string }>;
+}) {
+  const id = useId();
+  const rich = text === undefined;
+  const { label, ...actionRest } = action ?? { label: '' };
+  return (
+    <span className={['tooltip-anchor', className].filter(Boolean).join(' ')} data-tooltip="" data-tooltip-open={open || undefined}>
+      {isValidElement(children) ? cloneElement(children, { 'aria-describedby': id }) : children}
+      <span id={id} role={action ? undefined : 'tooltip'} className={tooltipClass(rich)}>
+        {rich ? (
+          <>
+            {subhead && <span className="tooltip-subhead">{subhead}</span>}
+            {supportingText && <span className="tooltip-supporting-text">{supportingText}</span>}
+            {action && (
+              <span className="tooltip-actions">
+                <Button kind="text" size="small" className="tooltip-action" {...actionRest}>
+                  {label}
+                </Button>
+              </span>
+            )}
+          </>
+        ) : (
+          text
+        )}
+      </span>
+    </span>
+  );
+}

package/theme/ui/TopAppBar.tsx

@@ -0,0 +1,77 @@
+// A top app bar (m3.material.io/components/app-bars, which Material now calls the app bar; .top-app-bar in
+// ../styles/ui.css): the bar at the top of a page. Without a `kind` it is only the container, and what is in it is the
+// header's own (components/Header.astro, and a theme's own header: the logo, the menu and its button). With a kind it
+// has Material's elements, each in its place: the leading button (`leading`, an icon button: the menu, back), the
+// headline (`headline`, a heading with `headingLevel`, else a <p>) with its subtitle (`subtitle`), and the trailing
+// elements (`trailing`: icon buttons, an avatar or another picture, a filled button). The kinds are M3 Expressive's:
+// `search` (a search bar instead of the headline, `search`: the theme's Search, with its own icons inside it and the
+// leading and trailing ones outside it), `small` (the headline in the bar), and `medium-flexible` and `large-flexible`
+// (a larger headline under the bar, wrapping when it is long, which a component collapses into a small bar with
+// `collapsed`, data-collapsed: the headline in the bar). `align` puts the headline (or the search bar's text) at the
+// start, the default, or in the middle. Another surface, line and shadow once the page scrolls under it (data-stuck, set
+// by layouts/Base.astro on [data-header]). Where it stands (sticky at the top) is the component's own. An Astro header
+// gives its element the class with topAppBarClass, and the kind's with topAppBarClasses.
+import type { ReactNode } from 'react';
+
+export type TopAppBarKind = 'search' | 'small' | 'medium-flexible' | 'large-flexible';
+export type TopAppBarAlign = 'start' | 'center';
+
+/** The kinds, in Material's order. */
+export const topAppBarKinds: TopAppBarKind[] = ['search', 'small', 'medium-flexible', 'large-flexible'];
+
+/** A top app bar's class: the container's. */
+export const topAppBarClass = 'top-app-bar';
+
+/** A top app bar's classes with its kind and its alignment (without a kind only the container's). */
+export const topAppBarClasses = (kind?: TopAppBarKind, align: TopAppBarAlign = 'start') =>
+  [topAppBarClass, kind && `top-app-bar-${kind}`, kind && align === 'center' && 'top-app-bar-center'].filter(Boolean).join(' ');
+
+export default function TopAppBar({
+  kind,
+  align,
+  leading,
+  headline,
+  subtitle,
+  headingLevel,
+  trailing,
+  search,
+  collapsed,
+  className,
+  children,
+  ...rest
+}: {
+  kind?: TopAppBarKind;
+  align?: TopAppBarAlign;
+  leading?: ReactNode;
+  headline?: ReactNode;
+  subtitle?: ReactNode;
+  headingLevel?: 1 | 2 | 3 | 4 | 5 | 6;
+  trailing?: ReactNode;
+  search?: ReactNode;
+  collapsed?: boolean;
+  className?: string;
+  children?: ReactNode;
+} & Record<string, unknown>) {
+  const Heading = headingLevel ? (`h${headingLevel}` as const) : 'p';
+  const flexible = kind === 'medium-flexible' || kind === 'large-flexible';
+  return (
+    <header
+      className={[topAppBarClasses(kind, align), className].filter(Boolean).join(' ')}
+      data-collapsed={(flexible && collapsed) || undefined}
+      {...rest}
+    >
+      {kind && leading && <div className="top-app-bar-leading">{leading}</div>}
+      {kind === 'search'
+        ? search && <div className="top-app-bar-search-bar">{search}</div>
+        : kind &&
+          headline !== undefined && (
+            <div className="top-app-bar-headline-group">
+              <Heading className="top-app-bar-headline">{headline}</Heading>
+              {subtitle && <p className="top-app-bar-subtitle">{subtitle}</p>}
+            </div>
+          )}
+      {kind && trailing && <div className="top-app-bar-trailing">{trailing}</div>}
+      {children}
+    </header>
+  );
+}

package/theme/ui/bottomSheet.script.ts

@@ -0,0 +1,8 @@
+// What a standard bottom sheet (BottomSheet.tsx with kind 'standard') does on the site: it can be dragged between its
+// states and tapped open and closed (standardBottomSheet in bottomSheet.ts). Run on every page by the theme's Base.astro
+// (blockScripts, packages/editor/site/blockScripts.ts); without a standard bottom sheet on the page it does nothing.
+import { standardBottomSheet } from '@theme/ui/bottomSheet';
+
+export default function bottomSheets() {
+  document.querySelectorAll<HTMLElement>('[data-bottom-sheet-standard]').forEach((sheet) => standardBottomSheet(sheet));
+}

package/theme/ui/bottomSheet.ts

@@ -0,0 +1,211 @@
+// What a bottom sheet (BottomSheet.tsx) does in a browser.
+// A modal one (in its <dialog> with bottomSheetClass), for the script that shows it (an app's: Calendly's
+// Sheet.astro): bottomSheet(dialog) gives it its open() and close(). Native <dialog>:
+// focus handling, Escape and screen readers work out of the box. Motion: on a phone it slides up and down (a state
+// transition) and its drag handle can be pulled down to close it (feedback), on a computer (from 48rem, a dialog in the
+// middle of the screen) it fades; with reduced motion it appears and disappears at once. Its close button, Escape and a
+// tap on the scrim (outside it) close it; the page under it does not scroll while it is open. It moves with the site's
+// motion scheme (motionSpring, @morphemecms/cms/lib/motion.ts).
+// A standard one (kind 'standard', at the bottom of the screen without a scrim; bottomSheet.script.ts on every page,
+// or a block's or an app's script that wants its controls): standardBottomSheet(sheet) lets it be dragged by its handle
+// and its header between the states it rests in (collapsed, half-expanded where that is clearly between the others,
+// expanded, and hidden when it has a close button), to the nearest when let go, or on to the next when it is flicked;
+// a tap on the handle (or Enter or Space on it) expands it when it is collapsed and collapses it otherwise, and its close
+// button hides it. How high each state is, is ui.css's (data-state), read without being painted, so a theme sets it
+// there. It gives its state() and set(state) to show it in another (also again after it is hidden). The height follows
+// with the site's motion scheme; with reduced motion it changes at once.
+import { animate } from 'motion';
+import { motionSpring } from '@morphemecms/cms/lib/motion';
+import type { BottomSheetState } from '@theme/ui/BottomSheet';
+
+export type BottomSheetControls = { open: () => void; close: () => Promise<void> };
+export type StandardBottomSheetControls = { state: () => BottomSheetState; set: (state: BottomSheetState) => Promise<void> };
+
+export function bottomSheet(sheet: HTMLDialogElement): BottomSheetControls {
+  const panel = sheet.querySelector<HTMLElement>('[data-bottom-sheet-container]')!;
+  const handle = sheet.querySelector<HTMLElement>('[data-bottom-sheet-handle]');
+  const reduce = matchMedia('(prefers-reduced-motion: reduce)').matches;
+  // A dialog in the middle on a computer (.bottom-sheet in ui.css): it fades, and has no handle to drag.
+  const wide = matchMedia('(width >= 48rem)');
+  let closing = false;
+
+  function open() {
+    if (sheet.open) return;
+    sheet.showModal();
+    document.documentElement.style.overflow = 'hidden';
+    if (reduce) return;
+    if (wide.matches) animate(panel, { opacity: [0, 1], scale: [0.98, 1] }, motionSpring('spatial'));
+    else animate(panel, { y: ['100%', '0%'] }, motionSpring('spatial'));
+  }
+
+  async function close() {
+    if (!sheet.open || closing) return;
+    closing = true;
+    if (!reduce) await animate(panel, wide.matches ? { opacity: 0, scale: 0.98 } : { y: '100%' }, motionSpring('spatial', 'fast'));
+    sheet.close();
+    panel.style.transform = '';
+    panel.style.opacity = '';
+    document.documentElement.style.overflow = '';
+    closing = false;
+  }
+
+  sheet.querySelector('[data-bottom-sheet-close]')?.addEventListener('click', close);
+  // Escape: animate out instead of the dialog's instant close.
+  sheet.addEventListener('cancel', (e) => {
+    e.preventDefault();
+    close();
+  });
+  // A tap on the scrim (outside the sheet) closes it.
+  sheet.addEventListener('click', (e) => {
+    if (e.target === sheet) close();
+  });
+
+  // Drag the handle down to close.
+  let startY = 0;
+  let dragging = false;
+  handle?.addEventListener('pointerdown', (e) => {
+    dragging = true;
+    startY = e.clientY;
+    handle.setPointerCapture(e.pointerId);
+  });
+  handle?.addEventListener('pointermove', (e) => {
+    if (!dragging) return;
+    const dy = Math.max(0, e.clientY - startY);
+    panel.style.transform = `translateY(${dy}px)`;
+  });
+  const endDrag = (e: PointerEvent) => {
+    if (!dragging) return;
+    dragging = false;
+    const dy = Math.max(0, e.clientY - startY);
+    if (dy > 120) close();
+    else if (reduce) panel.style.transform = '';
+    else animate(panel, { y: 0 }, motionSpring('spatial'));
+  };
+  handle?.addEventListener('pointerup', endDrag);
+  handle?.addEventListener('pointercancel', endDrag);
+
+  return { open, close };
+}
+
+const standardSheets = new WeakMap<HTMLElement, StandardBottomSheetControls>();
+
+export function standardBottomSheet(sheet: HTMLElement): StandardBottomSheetControls {
+  const known = standardSheets.get(sheet);
+  if (known) return known;
+  const handle = sheet.querySelector<HTMLElement>('[data-bottom-sheet-handle]');
+  const header = sheet.querySelector<HTMLElement>('[data-bottom-sheet-header]');
+  const closeButton = sheet.querySelector<HTMLElement>('[data-bottom-sheet-close]');
+  const reduce = matchMedia('(prefers-reduced-motion: reduce)').matches;
+  const state = () => (sheet.dataset.state as BottomSheetState | undefined) ?? 'collapsed';
+
+  // How high it is in a state, as ui.css draws it: set, measured and put back before anything is painted.
+  function heightIn(s: BottomSheetState) {
+    if (s === 'hidden') return 0;
+    const was = { state: sheet.dataset.state, height: sheet.style.height };
+    sheet.style.height = '';
+    sheet.dataset.state = s;
+    const px = sheet.offsetHeight;
+    sheet.dataset.state = was.state;
+    sheet.style.height = was.height;
+    return px;
+  }
+  // The states it rests in, from the lowest: half-expanded only where it is clearly between the others.
+  function stops() {
+    const collapsed = heightIn('collapsed');
+    const half = heightIn('half-expanded');
+    const expanded = heightIn('expanded');
+    return [
+      ...(closeButton ? [{ state: 'hidden' as const, height: 0 }] : []),
+      { state: 'collapsed' as const, height: collapsed },
+      ...(half - collapsed > 48 && expanded - half > 48 ? [{ state: 'half-expanded' as const, height: half }] : []),
+      { state: 'expanded' as const, height: expanded },
+    ];
+  }
+  const shown = (s: BottomSheetState) => {
+    sheet.dataset.state = s;
+    sheet.style.height = '';
+    handle?.setAttribute('aria-expanded', String(s === 'half-expanded' || s === 'expanded'));
+  };
+
+  // From the height it has now (0 when hidden) to the one of `to`, with all of it there while it moves.
+  async function set(to: BottomSheetState) {
+    const from = state() === 'hidden' ? 0 : sheet.offsetHeight;
+    const height = heightIn(to);
+    if (reduce || from === height) return shown(to);
+    sheet.dataset.state = 'expanded';
+    sheet.dataset.moving = '';
+    await animate(sheet, { height: [from, height] }, motionSpring('spatial'));
+    delete sheet.dataset.moving;
+    shown(to);
+  }
+
+  // Dragged by the handle or the header (not by a button in it), followed by its height.
+  let drag: { y: number; height: number; min: number; max: number; last: { y: number; t: number }; v: number } | undefined;
+  let dragged = false;
+  // The click that follows letting go of a drag is not a tap.
+  let afterDrag = false;
+  const down = (e: PointerEvent) => {
+    const target = e.target as Element;
+    if (e.button !== 0 || (target.closest('button, a') && target.closest('[data-bottom-sheet-handle]') === null)) return;
+    const list = stops();
+    drag = {
+      y: e.clientY,
+      height: sheet.offsetHeight,
+      min: list[0].height,
+      max: list.at(-1)!.height,
+      last: { y: e.clientY, t: e.timeStamp },
+      v: 0,
+    };
+    (e.currentTarget as HTMLElement).setPointerCapture(e.pointerId);
+  };
+  const move = (e: PointerEvent) => {
+    if (!drag) return;
+    const dy = e.clientY - drag.y;
+    if (!dragged && Math.abs(dy) < 4) return;
+    if (!dragged) {
+      dragged = true;
+      sheet.dataset.state = 'expanded';
+      sheet.dataset.moving = '';
+    }
+    sheet.style.height = `${Math.max(drag.min, Math.min(drag.max, drag.height - dy))}px`;
+    const dt = e.timeStamp - drag.last.t;
+    if (dt > 0) drag.v = (drag.last.y - e.clientY) / dt;
+    drag.last = { y: e.clientY, t: e.timeStamp };
+  };
+  const up = () => {
+    if (!drag) return;
+    const { v } = drag;
+    drag = undefined;
+    if (!dragged) return;
+    dragged = false;
+    afterDrag = true;
+    setTimeout(() => (afterDrag = false));
+    delete sheet.dataset.moving;
+    const height = sheet.offsetHeight;
+    const list = stops();
+    // Flicked: on to the next state that way; else the nearest.
+    const next =
+      v > 0.4
+        ? list.find((s) => s.height > height + 1)
+        : v < -0.4
+          ? list.findLast((s) => s.height < height - 1)
+          : list.reduce((a, b) => (Math.abs(b.height - height) < Math.abs(a.height - height) ? b : a));
+    set((next ?? list.reduce((a, b) => (Math.abs(b.height - height) < Math.abs(a.height - height) ? b : a))).state);
+  };
+  for (const el of [handle, header]) {
+    el?.addEventListener('pointerdown', down);
+    el?.addEventListener('pointermove', move);
+    el?.addEventListener('pointerup', up);
+    el?.addEventListener('pointercancel', up);
+  }
+  // A tap on the handle (or Enter or Space): expanded when collapsed, else collapsed; not after it was dragged.
+  handle?.addEventListener('click', () => {
+    if (afterDrag) return;
+    set(state() === 'collapsed' || state() === 'hidden' ? 'expanded' : 'collapsed');
+  });
+  closeButton?.addEventListener('click', () => set('hidden'));
+
+  const controls = { state, set };
+  standardSheets.set(sheet, controls);
+  return controls;
+}

package/theme/ui/carousel.script.ts

@@ -0,0 +1,28 @@
+// What a carousel (Carousel.tsx) does on the site: its page indicator is shown, follows the scroll position and jumps
+// to an item, and a multi-browse or hero carousel's items grow and shrink as they pass (carouselLayout in
+// carouselLayout.ts). Run on every page by the theme's Base.astro (blockScripts, packages/editor/site/blockScripts.ts); without a carousel
+// on the page it does nothing.
+import { carouselLayout, scrollFor, shownItem } from '@theme/ui/carouselLayout';
+
+export default function carousel() {
+  const reduce = matchMedia('(prefers-reduced-motion: reduce)').matches;
+
+  document.querySelectorAll<HTMLElement>('[data-carousel]').forEach((carousel) => {
+    const indicator = carousel.querySelector<HTMLElement>('[data-carousel-indicator]')!;
+    const row = carousel.querySelector<HTMLElement>('[data-carousel-items]')!;
+    const dots = [...carousel.querySelectorAll<HTMLButtonElement>('[data-carousel-dot]')];
+    indicator.hidden = false;
+    carouselLayout(carousel);
+
+    const go = (i: number) => row.scrollTo({ left: scrollFor(row, i), behavior: reduce ? 'auto' : 'smooth' });
+    const update = () => {
+      const active = shownItem(row);
+      dots.forEach((d, n) => d.setAttribute('aria-current', String(n === active)));
+    };
+
+    row.addEventListener('scroll', () => requestAnimationFrame(update), { passive: true });
+    addEventListener('resize', update, { passive: true });
+    dots.forEach((d, i) => d.addEventListener('click', () => go(i)));
+    update();
+  });
+}