@sondor-technology/sondor-components 1.0.9 → 1.0.10

package/src/components/progress/progress.ts

@@ -0,0 +1,95 @@
+import {LitElement, html, css} from "lit";
+import {customElement, property} from "lit/decorators.js";
+import {ifDefined} from "lit/directives/if-defined.js";
+import {resetStyles} from "../../styles/reset.js";
+
+/** Determinate when `value` is set, indeterminate otherwise. */
+@customElement("st-progress")
+export class StProgress extends LitElement {
+  @property({type: Number}) value?: number;
+  @property({type: Number}) max = 100;
+  @property({type: String}) label = "Progress";
+  @property({type: String, reflect: true}) color: "primary" | "success" | "warning" | "error" =
+    "primary";
+
+  static styles = [
+    resetStyles,
+    css`
+      :host {
+        display: block;
+      }
+      .track {
+        height: 0.5rem;
+        overflow: hidden;
+        border-radius: 999px;
+        background: var(--st-color-surface-muted);
+        border: 1px solid var(--st-color-border);
+      }
+      .bar {
+        height: 100%;
+        width: var(--_pct, 40%);
+        border-radius: inherit;
+        background: var(--_bar, var(--st-color-primary));
+        transition: width 0.2s ease;
+      }
+      :host([color="success"]) {
+        --_bar: var(--st-color-success);
+      }
+      :host([color="warning"]) {
+        --_bar: var(--st-color-warning);
+      }
+      :host([color="error"]) {
+        --_bar: var(--st-color-error);
+      }
+      .indeterminate .bar {
+        animation: slide 1.2s ease-in-out infinite;
+        width: 40%;
+      }
+      @keyframes slide {
+        from {
+          margin-left: -40%;
+        }
+        to {
+          margin-left: 100%;
+        }
+      }
+      @media (prefers-reduced-motion: reduce) {
+        .indeterminate .bar {
+          animation: none;
+          margin-left: 30%;
+        }
+        .bar {
+          transition: none;
+        }
+      }
+    `,
+  ];
+
+  private get _percent() {
+    if (this.value === undefined || this.max <= 0) return undefined;
+    return Math.min(100, Math.max(0, (this.value / this.max) * 100));
+  }
+
+  render() {
+    const pct = this._percent;
+    const determinate = pct !== undefined;
+    return html`
+      <div
+        class="track ${determinate ? "" : "indeterminate"}"
+        role="progressbar"
+        aria-label=${this.label}
+        aria-valuemin="0"
+        aria-valuemax=${ifDefined(determinate ? this.max : undefined)}
+        aria-valuenow=${ifDefined(determinate ? this.value : undefined)}
+      >
+        <div class="bar" style=${determinate ? `--_pct:${pct}%` : ""}></div>
+      </div>
+    `;
+  }
+}
+
+declare global {
+  interface HTMLElementTagNameMap {
+    "st-progress": StProgress;
+  }
+}

package/src/components/project-grid/project-card.ts

@@ -0,0 +1,19 @@
+import {customElement} from "lit/decorators.js";
+import {StCard} from "../section/card.js";
+
+/**
+ * One piece of work in a `st-project-grid`: a picture, a title linking to the project, a short
+ * description and links to the code or a live demo.
+ *
+ * Slots: `image`, `meta` (the year, role or technologies), `title` (a heading containing the
+ * link), the default slot (the description) and `footer` (links or buttons). Set `tags` (comma
+ * separated) for the grid's filter.
+ */
+@customElement("st-project-card")
+export class StProjectCard extends StCard {}
+
+declare global {
+  interface HTMLElementTagNameMap {
+    "st-project-card": StProjectCard;
+  }
+}

package/src/components/project-grid/project-grid.ts

@@ -0,0 +1,19 @@
+import {customElement} from "lit/decorators.js";
+import {StCardRow} from "../section/card-row.js";
+import "./project-card.js";
+
+/**
+ * A portfolio row: your projects as `st-project-card` items in a grid, optionally filtered by
+ * topic (`filterable`).
+ *
+ * Slots: `eyebrow`, `title`, `lead` and the default slot for the `st-project-card` items.
+ * Events: `st-filter` `{tag, count}` when a topic is chosen.
+ */
+@customElement("st-project-grid")
+export class StProjectGrid extends StCardRow {}
+
+declare global {
+  interface HTMLElementTagNameMap {
+    "st-project-grid": StProjectGrid;
+  }
+}

package/src/components/radio/radio.ts

@@ -83,7 +83,7 @@ export class StRadio extends LitElement {
       }
 
       :host([checked]) .control::after {
-        background-color: #ffffff; /* Explicitly white for contrast */
+        background-color: var(--st-white); /* Explicitly white for contrast */
         transform: scale(1);
       }
 

package/src/components/reveal/reveal.constants.ts

@@ -0,0 +1,20 @@
+export const revealEffects = [
+  "fade",
+  "slide-up",
+  "slide-down",
+  "slide-left",
+  "slide-right",
+  "zoom",
+  "blur",
+  "none",
+] as const;
+
+/**
+ * How content appears. The slide effects name the direction the content travels as it arrives:
+ * `slide-up` rises from below, `slide-down` drops in from above, `slide-left` moves leftwards
+ * from the right, `slide-right` moves rightwards from the left. `none` turns the animation off.
+ */
+export type RevealEffect = (typeof revealEffects)[number];
+
+/** Lifecycle of a reveal. Absent until the element is armed, so unarmed content is always visible. */
+export type RevealState = "pending" | "in" | "out";

package/src/components/reveal/reveal.ts

@@ -0,0 +1,344 @@
+import {LitElement, html, css, PropertyValues} from "lit";
+import {customElement, property} from "lit/decorators.js";
+import {resetStyles} from "../../styles/reset.js";
+import type {RevealEffect, RevealState} from "./reveal.constants.js";
+
+/** One observer per offset, shared by every reveal on the page. */
+const observers = new Map<number, IntersectionObserver>();
+const instances = new WeakMap<Element, StReveal>();
+
+function observerFor(offset: number): IntersectionObserver {
+  let observer = observers.get(offset);
+  if (!observer) {
+    // Shrinking the bottom of the viewport makes content reveal once it has travelled `offset`%
+    // into view, and works for elements taller than the screen (a ratio threshold would not).
+    observer = new IntersectionObserver(
+      (entries) => entries.forEach((entry) => instances.get(entry.target)?.handleIntersection(entry)),
+      {rootMargin: `0px 0px -${offset}% 0px`},
+    );
+    observers.set(offset, observer);
+  }
+  return observer;
+}
+
+/** False for people who prefer reduced motion and when a page opts out with `data-reveal="off"`. */
+function canAnimate(): boolean {
+  if (typeof IntersectionObserver === "undefined") return false;
+  if (window.matchMedia("(prefers-reduced-motion: reduce)").matches) return false;
+  return document.documentElement.dataset.reveal !== "off";
+}
+
+/** The hidden look. Used for the host itself, or for each child when `stagger` is set. */
+const hidden = css`
+  opacity: 0;
+  transform: translate3d(var(--_tx), var(--_ty), 0) scale(var(--_scale));
+  filter: blur(var(--_blur));
+  will-change: opacity, transform;
+`;
+
+const shown = css`
+  opacity: 1;
+  transform: none;
+  filter: none;
+`;
+
+const transitions = css`
+  transition:
+    opacity var(--_duration) var(--_ease),
+    transform var(--_duration) var(--_ease),
+    filter var(--_duration) var(--_ease);
+`;
+
+/**
+ * Animates its content into view as it is scrolled to, and optionally back out as it leaves.
+ *
+ * The content always stays in the DOM, so search engines, screen readers and find-in-page see
+ * all of it. Content is only visually hidden once the element is armed in the browser, and only
+ * when it starts below the fold. Without JavaScript, with reduced motion, or with
+ * `<html data-reveal="off">`, everything is simply visible.
+ *
+ * Set `stagger` (milliseconds) to animate the direct children one after another instead of the
+ * element as a whole.
+ *
+ * Events: `st-reveal-in` and `st-reveal-out` (bubbles, composed) when the state changes.
+ */
+@customElement("st-reveal")
+export class StReveal extends LitElement {
+  @property({type: String, reflect: true}) effect: RevealEffect = "slide-up";
+  /** Length of the animation in milliseconds. */
+  @property({type: Number}) duration = 600;
+  /** Wait before the animation starts, in milliseconds. */
+  @property({type: Number}) delay = 0;
+  /** How far slide effects travel (any CSS length). */
+  @property({type: String}) distance = "2rem";
+  /** Any CSS timing function. Defaults to a gentle ease-out. */
+  @property({type: String}) easing = "";
+  /** Percentage of the viewport height the element must travel into view before it reveals. */
+  @property({type: Number}) offset = 10;
+  /** Milliseconds between each child when animating children in sequence (0 animates as one). */
+  @property({type: Number}) stagger = 0;
+  /** Animate out as the content leaves the viewport, and back in when it returns. */
+  @property({type: Boolean}) out = false;
+
+  private _state?: RevealState;
+  private _armFrame = 0;
+  private _observed?: IntersectionObserver;
+
+  static styles = [
+    resetStyles,
+    css`
+      :host {
+        display: block;
+        --_distance: 2rem;
+        --_duration: var(--st-duration-reveal, 600ms);
+        --_delay: 0ms;
+        --_ease: var(--st-ease-out, cubic-bezier(0.22, 1, 0.36, 1));
+        --_stagger: 0ms;
+        --_tx: 0;
+        --_ty: var(--_distance);
+        --_scale: 1;
+        --_blur: 0;
+      }
+
+      :host([effect="fade"]) {
+        --_ty: 0;
+      }
+      :host([effect="slide-up"]) {
+        --_ty: var(--_distance);
+      }
+      :host([effect="slide-down"]) {
+        --_ty: calc(var(--_distance) * -1);
+      }
+      :host([effect="slide-left"]) {
+        --_tx: var(--_distance);
+        --_ty: 0;
+      }
+      :host([effect="slide-right"]) {
+        --_tx: calc(var(--_distance) * -1);
+        --_ty: 0;
+      }
+      :host([effect="zoom"]) {
+        --_ty: 0;
+        --_scale: 0.92;
+      }
+      :host([effect="blur"]) {
+        --_ty: 0;
+        --_blur: 0.75rem;
+      }
+
+      /* Vertical slides keep travelling the way the content left the screen. */
+      :host([data-reveal="out"][data-exit="top"][effect="slide-up"]),
+      :host([data-reveal="out"][data-exit="top"][effect="slide-down"]) {
+        --_ty: calc(var(--_distance) * -1);
+      }
+      :host([data-reveal="out"][data-exit="bottom"][effect="slide-up"]),
+      :host([data-reveal="out"][data-exit="bottom"][effect="slide-down"]) {
+        --_ty: var(--_distance);
+      }
+
+      /* Whole element */
+      :host([data-reveal]:not([data-staggered])) {
+        ${transitions}
+        transition-delay: var(--_delay);
+      }
+      :host([data-reveal="pending"]:not([data-staggered])),
+      :host([data-reveal="out"]:not([data-staggered])) {
+        ${hidden}
+      }
+      :host([data-reveal="in"]:not([data-staggered])) {
+        ${shown}
+      }
+
+      /* Children in sequence */
+      :host([data-staggered][data-reveal]) ::slotted(*) {
+        ${transitions}
+        transition-delay: calc(var(--_delay) + var(--st-reveal-i, 0) * var(--_stagger));
+      }
+      :host([data-staggered][data-reveal="pending"]) ::slotted(*),
+      :host([data-staggered][data-reveal="out"]) ::slotted(*) {
+        ${hidden}
+      }
+      :host([data-staggered][data-reveal="in"]) ::slotted(*) {
+        ${shown}
+      }
+
+      /* Replay jumps back to the hidden state without animating there. */
+      :host([data-instant]),
+      :host([data-instant]) ::slotted(*) {
+        transition: none !important;
+      }
+
+      @media (prefers-reduced-motion: reduce), print {
+        :host,
+        :host ::slotted(*) {
+          opacity: 1 !important;
+          transform: none !important;
+          filter: none !important;
+          transition: none !important;
+        }
+      }
+    `,
+  ];
+
+  /** Current phase, or undefined while the content is simply visible (never armed). */
+  get state(): RevealState | undefined {
+    return this._state;
+  }
+
+  connectedCallback() {
+    super.connectedCallback();
+    this.addEventListener("focusin", this._onFocusIn);
+    this._arm();
+  }
+
+  disconnectedCallback() {
+    this.removeEventListener("focusin", this._onFocusIn);
+    this._disarm();
+    super.disconnectedCallback();
+  }
+
+  /** Hides the content again and plays the entry animation, for demos and previews. */
+  replay() {
+    if (this.effect === "none" || !canAnimate()) return;
+    if (!this._observed) this._arm();
+    this._hideInstantly();
+    requestAnimationFrame(() => {
+      requestAnimationFrame(() => {
+        if (this._isInViewport()) this._setState("in");
+      });
+    });
+  }
+
+  protected updated(changed: PropertyValues<this>) {
+    this.style.setProperty("--_duration", `${this.duration}ms`);
+    this.style.setProperty("--_delay", `${this.delay}ms`);
+    this.style.setProperty("--_stagger", `${this.stagger}ms`);
+    this.style.setProperty("--_distance", this.distance);
+    if (this.easing) this.style.setProperty("--_ease", this.easing);
+    else this.style.removeProperty("--_ease");
+
+    // Only a genuine change re-arms: on the first update every property is "changed".
+    const retune = (["effect", "offset", "out", "stagger"] as const).some(
+      (key) => changed.has(key) && changed.get(key) !== undefined,
+    );
+    if (retune) {
+      this._disarm();
+      this._arm();
+    }
+  }
+
+  // ------------------------------------------------------------------ arming
+
+  private _arm(allowRetry = true) {
+    if (this._observed || this.effect === "none" || !canAnimate()) return;
+
+    // Content that has just been added may not have a box yet. Give it one frame to get laid out
+    // before judging where it is, so content already on screen is never made to fade in.
+    if (allowRetry && this.getClientRects().length === 0) {
+      cancelAnimationFrame(this._armFrame);
+      this._armFrame = requestAnimationFrame(() => this._arm(false));
+      return;
+    }
+    this.toggleAttribute("data-staggered", this.stagger > 0);
+
+    const belowFold = this._startsBelowFold();
+    // Content already on screen, or already scrolled past, is shown straight away.
+    if (belowFold) this._hideInstantly();
+    else this._setState("in", false);
+
+    this._observed = observerFor(this.offset);
+    instances.set(this, this);
+    this._observed.observe(this);
+  }
+
+  /** Whether the content starts below the visible part of the screen. */
+  private _startsBelowFold(): boolean {
+    const limit = window.innerHeight * (1 - this.offset / 100);
+    if (this.getClientRects().length > 0) return this.getBoundingClientRect().top > limit;
+
+    // Not displayed. Inside a row that skips off-screen work (content-visibility) the nearest
+    // displayed ancestor says where we are; inside something hidden we have no position, so we
+    // wait and reveal as soon as we are shown on screen.
+    let node: Element | null = this.parentElement ?? (this.getRootNode() as ShadowRoot).host ?? null;
+    while (node && node.getClientRects().length === 0) {
+      node = node.parentElement ?? (node.getRootNode() as ShadowRoot).host ?? null;
+    }
+    if (node && getComputedStyle(node).contentVisibility === "auto") {
+      return node.getBoundingClientRect().top > limit;
+    }
+    return true;
+  }
+
+  private _disarm() {
+    cancelAnimationFrame(this._armFrame);
+    this._observed?.unobserve(this);
+    this._observed = undefined;
+    this._state = undefined;
+    this.removeAttribute("data-reveal");
+    this.removeAttribute("data-exit");
+  }
+
+  /** Moves to the hidden state without animating there (the hide itself must never be seen). */
+  private _hideInstantly() {
+    this.toggleAttribute("data-instant", true);
+    this._setState("pending", false);
+    void this.offsetWidth; // flush the hidden style while transitions are off
+    // Wait for the settings (distance, duration...) to be applied so they too skip the transition.
+    void this.updateComplete.then(() => {
+      void this.offsetWidth;
+      requestAnimationFrame(() => this.removeAttribute("data-instant"));
+    });
+  }
+
+  /** @internal Called by the shared observer. */
+  handleIntersection(entry: IntersectionObserverEntry) {
+    if (entry.isIntersecting) {
+      if (this._state !== "in") this._setState("in");
+      if (!this.out) this._unobserve();
+    } else if (this.out && this._state === "in") {
+      const rect = entry.boundingClientRect;
+      this.setAttribute("data-exit", rect.top + rect.height / 2 < window.innerHeight / 2 ? "top" : "bottom");
+      this._setState("out");
+    }
+  }
+
+  private _unobserve() {
+    this._observed?.unobserve(this);
+    this._observed = undefined;
+  }
+
+  private _setState(state: RevealState, announce = true) {
+    if (this._state === state) return;
+    this._state = state;
+    this.setAttribute("data-reveal", state);
+    if (announce && state !== "pending") {
+      this.dispatchEvent(new CustomEvent(`st-reveal-${state}`, {bubbles: true, composed: true}));
+    }
+  }
+
+  private _isInViewport() {
+    const rect = this.getBoundingClientRect();
+    return rect.bottom > 0 && rect.top < window.innerHeight * (1 - this.offset / 100);
+  }
+
+  /** Keyboard users must never land on invisible content. */
+  private _onFocusIn = () => {
+    if (this._state === "pending" || this._state === "out") this._setState("in");
+  };
+
+  private _onSlotChange(e: Event) {
+    (e.target as HTMLSlotElement)
+      .assignedElements()
+      .forEach((child, i) => (child as HTMLElement).style.setProperty("--st-reveal-i", String(i)));
+  }
+
+  render() {
+    return html`<slot @slotchange=${this._onSlotChange}></slot>`;
+  }
+}
+
+declare global {
+  interface HTMLElementTagNameMap {
+    "st-reveal": StReveal;
+  }
+}

package/src/components/scroll-progress/scroll-progress.ts

@@ -0,0 +1,119 @@
+import {LitElement, html, css} from "lit";
+import {customElement, property} from "lit/decorators.js";
+import {resetStyles} from "../../styles/reset.js";
+
+/**
+ * A thin bar showing how far down the page (or an article) the reader has scrolled.
+ *
+ * By default it tracks the whole page and sticks to the top of the screen. Point `target` at an
+ * element (such as the article) to measure progress through just that element. The bar is
+ * decorative and hidden from screen readers.
+ *
+ * Events: `st-scroll-progress` with `detail.progress` (0 to 1), only when the value changes.
+ */
+@customElement("st-scroll-progress")
+export class StScrollProgress extends LitElement {
+  /** CSS selector of the element to measure. Empty tracks the whole page. */
+  @property({type: String}) target = "";
+  @property({type: String, reflect: true}) position: "top" | "bottom" = "top";
+
+  private _progress = 0;
+  private _frame = 0;
+
+  static styles = [
+    resetStyles,
+    css`
+      :host {
+        position: fixed;
+        left: 0;
+        right: 0;
+        top: 0;
+        z-index: var(--st-scroll-progress-z, 100);
+        height: var(--st-scroll-progress-height, 0.25rem);
+        pointer-events: none;
+      }
+
+      :host([position="bottom"]) {
+        top: auto;
+        bottom: 0;
+      }
+
+      .bar {
+        width: 100%;
+        height: 100%;
+        background: var(--st-scroll-progress-color, var(--st-color-primary));
+        transform: scaleX(var(--_progress, 0));
+        transform-origin: left;
+        transition: transform 0.1s linear;
+      }
+
+      @media (prefers-reduced-motion: reduce) {
+        .bar {
+          transition: none;
+        }
+      }
+    `,
+  ];
+
+  /** Progress through the page or target, from 0 to 1. */
+  get progress() {
+    return this._progress;
+  }
+
+  connectedCallback() {
+    super.connectedCallback();
+    window.addEventListener("scroll", this._schedule, {passive: true});
+    window.addEventListener("resize", this._schedule, {passive: true});
+    this._schedule();
+  }
+
+  disconnectedCallback() {
+    window.removeEventListener("scroll", this._schedule);
+    window.removeEventListener("resize", this._schedule);
+    cancelAnimationFrame(this._frame);
+    super.disconnectedCallback();
+  }
+
+  protected updated() {
+    this._schedule();
+  }
+
+  private _schedule = () => {
+    cancelAnimationFrame(this._frame);
+    this._frame = requestAnimationFrame(() => this._measure());
+  };
+
+  private _measure() {
+    const element = this.target ? document.querySelector(this.target) : null;
+    let progress: number;
+
+    if (element) {
+      // Read: how much of the element has scrolled past the top of the screen.
+      const rect = element.getBoundingClientRect();
+      const scrollable = rect.height - window.innerHeight;
+      progress = scrollable > 0 ? -rect.top / scrollable : rect.top < 0 ? 1 : 0;
+    } else {
+      const root = document.documentElement;
+      const scrollable = root.scrollHeight - window.innerHeight;
+      progress = scrollable > 0 ? window.scrollY / scrollable : 0;
+    }
+
+    progress = Math.min(1, Math.max(0, progress));
+    if (progress === this._progress) return;
+    this._progress = progress;
+    this.style.setProperty("--_progress", String(progress));
+    this.dispatchEvent(
+      new CustomEvent("st-scroll-progress", {detail: {progress}, bubbles: true, composed: true}),
+    );
+  }
+
+  render() {
+    return html`<div class="bar" aria-hidden="true"></div>`;
+  }
+}
+
+declare global {
+  interface HTMLElementTagNameMap {
+    "st-scroll-progress": StScrollProgress;
+  }
+}