@timmo001/groundwork-ui 0.0.0-stage → 0.0.0

package/src/layout.ts

@@ -0,0 +1,182 @@
+/**
+ * `gw-page`, `gw-stack`, `gw-row` and `gw-grid`: page width and spacing.
+ * Docs: https://groundwork.timmo.dev/components/layout/#stack-row-and-grid
+ *
+ * @module
+ */
+import { GwElement, css, h } from "./element.js";
+import { base } from "./styles.js";
+
+/**
+ * Centers a page's content at the theme's width, with the page gap between
+ * its children.
+ *
+ * @element gw-page
+ * @summary A page's content column.
+ *
+ * @attr {boolean} narrow - Uses the narrow content width, for forms and settings.
+ *
+ * @slot - The page's content.
+ *
+ * @csspart page - The content column.
+ */
+export class GwPage extends GwElement {
+  static override properties = {
+    narrow: { type: "boolean", reflect: true },
+  } as const;
+
+  static override styles = [
+    base,
+    css`
+      :host {
+        display: block;
+      }
+
+      .page {
+        display: flex;
+        flex-direction: column;
+        gap: var(--gw-space-6);
+        width: 100%;
+        max-width: var(--gw-content-width);
+        margin-inline: auto;
+      }
+
+      :host([narrow]) .page {
+        max-width: var(--gw-content-width-narrow);
+      }
+    `,
+  ];
+
+  declare narrow: boolean;
+
+  constructor() {
+    super();
+    this.narrow = false;
+  }
+
+  protected override create(root: ShadowRoot) {
+    root.append(h("div", { class: "page", part: "page" }, h("slot")));
+  }
+}
+
+const gaps = css`
+  :host([gap="s"]) {
+    --gw-gap: var(--gw-space-1);
+  }
+
+  :host([gap="l"]) {
+    --gw-gap: var(--gw-space-6);
+  }
+`;
+
+/** A layout element whose shadow root is a single slot. */
+class GwSlotted extends GwElement {
+  protected override create(root: ShadowRoot) {
+    root.append(h("slot"));
+  }
+}
+
+/**
+ * Stacks its children in a column.
+ *
+ * @element gw-stack
+ * @summary Children in a column.
+ *
+ * @attr {"s"|"l"} gap - A smaller or larger gap.
+ *
+ * @slot - The children.
+ *
+ * @cssprop --gw-gap - The gap. Defaults to `--gw-space-3`.
+ */
+export class GwStack extends GwSlotted {
+  static override styles = [
+    base,
+    gaps,
+    css`
+      :host {
+        display: flex;
+        flex-direction: column;
+        gap: var(--gw-gap, var(--gw-space-3));
+      }
+    `,
+  ];
+}
+
+/**
+ * Lines its children up in a row, wrapping when they run out of room.
+ *
+ * @element gw-row
+ * @summary Children in a wrapping row.
+ *
+ * @attr {"s"|"l"} gap - A smaller or larger gap.
+ * @attr {boolean} nowrap - Keeps the children on one line.
+ *
+ * @slot - The children.
+ *
+ * @cssprop --gw-gap - The gap. Defaults to `--gw-space-2`.
+ */
+export class GwRow extends GwSlotted {
+  static override styles = [
+    base,
+    gaps,
+    css`
+      :host {
+        display: flex;
+        flex-wrap: wrap;
+        gap: var(--gw-gap, var(--gw-space-2));
+        align-items: center;
+      }
+
+      :host([nowrap]) {
+        flex-wrap: nowrap;
+      }
+    `,
+  ];
+}
+
+/**
+ * Fills as many columns as fit, each at least `--gw-grid-min` wide.
+ *
+ * @element gw-grid
+ * @summary Children in responsive columns.
+ *
+ * @attr {"s"|"l"} gap - A smaller or larger gap.
+ *
+ * @slot - The children.
+ *
+ * @cssprop --gw-grid-min - The narrowest a column gets. Defaults to `18rem`.
+ * @cssprop --gw-gap - The gap. Defaults to `--gw-space-3`.
+ */
+export class GwGrid extends GwSlotted {
+  static override styles = [
+    base,
+    gaps,
+    css`
+      :host {
+        display: grid;
+        grid-template-columns: repeat(
+          auto-fill,
+          minmax(min(100%, var(--gw-grid-min, 18rem)), 1fr)
+        );
+        gap: var(--gw-gap, var(--gw-space-3));
+      }
+    `,
+  ];
+}
+
+GwPage.define("gw-page");
+
+GwStack.define("gw-stack");
+
+GwRow.define("gw-row");
+
+GwGrid.define("gw-grid");
+
+declare global {
+  interface HTMLElementTagNameMap {
+    "gw-page": GwPage;
+    "gw-stack": GwStack;
+    "gw-row": GwRow;
+    "gw-grid": GwGrid;
+  }
+}

package/src/motion.ts

@@ -0,0 +1,105 @@
+/**
+ * Motion helpers: fades that never pop, heights that glide instead of jump,
+ * and View Transitions for whole-view changes. All respect reduced motion.
+ *
+ * @module
+ */
+
+/** Whether the person asked for reduced motion. */
+export const reducedMotion = () =>
+  window.matchMedia("(prefers-reduced-motion: reduce)").matches;
+
+/**
+ * Reads a motion duration token in milliseconds, such as
+ * `--gw-motion-slow`, falling back when the tokens aren't loaded.
+ */
+export const motionDuration = (
+  element: Element,
+  token: string,
+  fallback: number,
+) =>
+  Number.parseFloat(getComputedStyle(element).getPropertyValue(token)) ||
+  fallback;
+
+/**
+ * The curve for fades. A decelerating curve lands most of an opacity change
+ * in the first frames and reads as a pop, so fades ease in and out.
+ */
+export const fadeEasing = "cubic-bezier(0.4, 0, 0.2, 1)";
+
+/**
+ * Fades `element` in, after `delay`, over `duration` (`--gw-motion-slow` by
+ * default). Use it when content replaces a skeleton. With reduced motion it
+ * shows at once.
+ */
+export const fadeIn = (
+  element: HTMLElement,
+  { delay = 0, duration }: { delay?: number; duration?: number } = {},
+) =>
+  element.animate([{ opacity: 0 }, { opacity: 1 }], {
+    delay,
+    duration: reducedMotion()
+      ? 0
+      : (duration ?? motionDuration(element, "--gw-motion-slow", 350)),
+    easing: fadeEasing,
+    fill: "backwards",
+  });
+
+/**
+ * Glides `element` from the height it had before a change to the height it
+ * has after, as an expansion panel opens, so content arriving or going never
+ * jumps the layout. Measure with `before = element.offsetHeight` ahead of the
+ * change, then call this once it's rendered. Skipped when motion is reduced.
+ */
+export const animateHeight = (element: HTMLElement, before: number) => {
+  const after = element.offsetHeight;
+
+  if (before === after || before === 0 || reducedMotion()) {
+    return;
+  }
+
+  const duration = motionDuration(element, "--gw-motion-normal", 250);
+
+  element.animate(
+    { height: [`${before}px`, `${after}px`], overflow: ["clip", "clip"] },
+    { duration, easing: "cubic-bezier(0.2, 0, 0, 1)" },
+  );
+};
+
+/**
+ * Runs a DOM change inside a View Transition where the browser supports one
+ * and motion isn't reduced, otherwise runs it straight away, after Home
+ * Assistant's `withViewTransition()`. Use it for changes to the whole view,
+ * such as switching theme or mode; component state uses CSS transitions.
+ *
+ * The change may return a promise, such as a Lit element's
+ * `updateComplete`, so the new view is captured once it has rendered. Keep
+ * it quick: the page is frozen until it settles.
+ */
+export const withViewTransition = (
+  change: () => void | Promise<void>,
+): Promise<void> => {
+  const reduced = reducedMotion();
+
+  if (document.startViewTransition === undefined || reduced) {
+    return Promise.resolve(change());
+  }
+
+  let changed = false;
+
+  try {
+    const transition = document.startViewTransition(() => {
+      changed = true;
+
+      return change();
+    });
+
+    // A transition skipped by a newer one rejects with AbortError; the change
+    // itself still happened.
+    transition.ready.catch(() => undefined);
+
+    return transition.finished.catch(() => undefined);
+  } catch {
+    return changed ? Promise.resolve() : Promise.resolve(change());
+  }
+};

package/src/styles.ts

@@ -0,0 +1,122 @@
+/**
+ * Styles and helpers every component shares: the base sheet, tones and icons.
+ *
+ * @module
+ */
+import { css } from "./element.js";
+
+const svgNamespace = "http://www.w3.org/2000/svg";
+
+/**
+ * What every component shares: box sizing, the focus ring, icons and the
+ * tones that set `--gw-tone` from a `tone` attribute.
+ */
+export const base = css`
+  :host {
+    font-family: var(--gw-font-sans);
+    color: var(--gw-color-text-primary);
+  }
+
+  *,
+  *::before,
+  *::after {
+    box-sizing: border-box;
+  }
+
+  [hidden] {
+    display: none !important;
+  }
+
+  :focus-visible {
+    outline: var(--gw-focus-width) solid var(--gw-color-focus);
+    outline-offset: var(--gw-focus-offset);
+  }
+
+  .icon {
+    flex: none;
+    width: var(--gw-icon-size, 1.25rem);
+    height: var(--gw-icon-size, 1.25rem);
+    fill: currentColor;
+  }
+
+  :host([tone="accent"]) {
+    --gw-tone: var(--gw-color-accent);
+    --gw-tone-fill: var(--gw-color-fill-accent-quiet);
+    --gw-tone-border: var(--gw-color-border-accent);
+  }
+
+  :host([tone="info"]) {
+    --gw-tone: var(--gw-color-info);
+    --gw-tone-fill: var(--gw-color-fill-info-quiet);
+    --gw-tone-border: var(--gw-color-border-info);
+  }
+
+  :host([tone="success"]) {
+    --gw-tone: var(--gw-color-success);
+    --gw-tone-fill: var(--gw-color-fill-success-quiet);
+    --gw-tone-border: var(--gw-color-border-success);
+  }
+
+  :host([tone="warning"]) {
+    --gw-tone: var(--gw-color-warning);
+    --gw-tone-fill: var(--gw-color-fill-warning-quiet);
+    --gw-tone-border: var(--gw-color-border-warning);
+  }
+
+  :host([tone="danger"]) {
+    --gw-tone: var(--gw-color-danger);
+    --gw-tone-fill: var(--gw-color-fill-danger-quiet);
+    --gw-tone-border: var(--gw-color-border-danger);
+  }
+
+  :host([tone="important"]) {
+    --gw-tone: var(--gw-color-important);
+    --gw-tone-fill: var(--gw-color-fill-important-quiet);
+    --gw-tone-border: var(--gw-color-border-important);
+  }
+
+  @media (prefers-reduced-motion: reduce) {
+    *,
+    *::before,
+    *::after {
+      animation-duration: 0s !important;
+      transition-duration: 0s !important;
+    }
+  }
+`;
+
+/** The tones a component's `tone` attribute takes. */
+export type Tone =
+  | "neutral"
+  | "accent"
+  | "info"
+  | "success"
+  | "warning"
+  | "danger"
+  | "important";
+
+/**
+ * An icon from SVG path data, such as one of `@mdi/js`'s or Lucide's paths,
+ * so each app picks its own set. Without a label it's hidden from assistive
+ * technology. Change its path later with `setIconPath`.
+ */
+export const createIcon = (path: string, label?: string) => {
+  const element = document.createElementNS(svgNamespace, "svg");
+
+  element.classList.add("icon");
+  element.setAttribute("viewBox", "0 0 24 24");
+  element.setAttribute("role", label === undefined ? "presentation" : "img");
+  element.setAttribute("aria-hidden", label === undefined ? "true" : "false");
+
+  if (label !== undefined) element.setAttribute("aria-label", label);
+
+  element.append(document.createElementNS(svgNamespace, "path"));
+  setIconPath(element, path);
+
+  return element;
+};
+
+/** Changes an icon's path data. */
+export const setIconPath = (icon: SVGSVGElement, path: string) => {
+  icon.querySelector("path")?.setAttribute("d", path);
+};