@sondor-technology/sondor-components 1.0.9 → 1.0.10

package/src/components/section/card-row.ts

@@ -0,0 +1,152 @@
+import {html, css, nothing, PropertyValues, TemplateResult} from "lit";
+import {property, state} from "lit/decorators.js";
+import {StSection} from "./section.js";
+import {StCard} from "./card.js";
+
+/**
+ * Base for rows that list cards (blog posts, projects). Cards sit in a grid or a single column and
+ * can be filtered by topic: add `filterable` and a button appears for every topic used in the
+ * cards' `tags`.
+ */
+export abstract class StCardRow extends StSection {
+  /** The most columns on wide screens (grid layout). */
+  @property({type: Number}) columns = 3;
+  /** `grid` or one card per row. */
+  @property({type: String, reflect: true}) layout: "grid" | "list" = "grid";
+  /** Shows topic buttons that filter the cards. */
+  @property({type: Boolean, reflect: true}) filterable = false;
+  @property({type: String, attribute: "filter-label"}) filterLabel = "Filter by topic";
+  @property({type: String, attribute: "all-label"}) allLabel = "All";
+
+  @state() private _tags: string[] = [];
+  @state() private _active = "";
+  @state() private _visible = 0;
+  @state() private _total = 0;
+
+  static styles = [
+    ...StSection.styles,
+    css`
+      .items {
+        --_columns: 3;
+        --_gap: var(--st-spacing-lg);
+        display: grid;
+        gap: var(--_gap);
+        grid-template-columns: repeat(
+          auto-fill,
+          minmax(max(16rem, calc((100% - (var(--_columns) - 1) * var(--_gap)) / var(--_columns))), 1fr)
+        );
+      }
+
+      :host([layout="list"]) .items {
+        grid-template-columns: minmax(0, 1fr);
+      }
+
+      .filters {
+        display: flex;
+        flex-wrap: wrap;
+        justify-content: center;
+        gap: var(--st-spacing-sm);
+        margin-bottom: var(--st-spacing-xl);
+      }
+
+      .chip {
+        padding: var(--st-spacing-xs) var(--st-spacing-md);
+        border: 1px solid var(--st-color-border);
+        border-radius: 999px;
+        background: none;
+        color: var(--st-color-text);
+        cursor: pointer;
+      }
+
+      .chip:hover {
+        background: var(--st-color-surface-hover);
+      }
+
+      .chip[aria-pressed="true"] {
+        border-color: var(--st-color-primary);
+        background: var(--st-color-primary);
+        color: var(--st-color-bg);
+      }
+
+      .chip:focus-visible {
+        outline: 2px solid var(--st-color-primary);
+        outline-offset: 2px;
+      }
+
+      .status {
+        position: absolute;
+        width: 1px;
+        height: 1px;
+        overflow: hidden;
+        clip-path: inset(50%);
+      }
+    `,
+  ];
+
+  private get _cards(): StCard[] {
+    const slot = this.renderRoot?.querySelector<HTMLSlotElement>(".items slot");
+    return (slot?.assignedElements({flatten: true}) ?? []).filter((el): el is StCard => el instanceof StCard);
+  }
+
+  protected updated(changed: PropertyValues<this>) {
+    super.updated(changed);
+    this.renderRoot
+      .querySelector<HTMLElement>(".items")
+      ?.style.setProperty("--_columns", String(Math.max(1, this.columns)));
+    if (changed.has("layout")) this._cards.forEach((card) => (card.layout = this.layout));
+  }
+
+  private _onCardsChange = (e: Event) => {
+    this._onItemsChange(e);
+    const cards = this._cards;
+    cards.forEach((card) => (card.layout = this.layout));
+    this._tags = [...new Set(cards.flatMap((card) => card.tagList))].sort((a, b) => a.localeCompare(b));
+    this._total = cards.length;
+    this._applyFilter();
+  };
+
+  private _applyFilter() {
+    const cards = this._cards;
+    cards.forEach((card) => card.toggleAttribute("hidden", !!this._active && !card.tagList.includes(this._active)));
+    this._visible = cards.filter((card) => !card.hidden).length;
+  }
+
+  private _choose(tag: string) {
+    this._active = tag;
+    this._applyFilter();
+    this.dispatchEvent(
+      new CustomEvent("st-filter", {detail: {tag: tag || null, count: this._visible}, bubbles: true, composed: true}),
+    );
+  }
+
+  private _renderFilters(): TemplateResult | typeof nothing {
+    if (!this.filterable || this._tags.length === 0) return nothing;
+    return html`
+      <div class="filters" role="group" aria-label=${this.filterLabel}>
+        ${["", ...this._tags].map(
+          (tag) => html`
+            <button
+              type="button"
+              class="chip"
+              aria-pressed=${this._active === tag ? "true" : "false"}
+              @click=${() => this._choose(tag)}
+            >
+              ${tag || this.allLabel}
+            </button>
+          `,
+        )}
+      </div>
+      <p class="status" role="status">${this._visible} of ${this._total} shown</p>
+    `;
+  }
+
+  render() {
+    return this.frame(
+      html`
+        ${this._renderFilters()}
+        <div class="items"><slot @slotchange=${this._onCardsChange}></slot></div>
+      `,
+      {animated: false},
+    );
+  }
+}

package/src/components/section/card.ts

@@ -0,0 +1,197 @@
+import {html, css, TemplateResult} from "lit";
+import {property} from "lit/decorators.js";
+import {resetStyles} from "../../styles/reset.js";
+import {StRowItem} from "./row-item.js";
+
+/**
+ * Base for the cards in a filterable list (a blog post, a project). A card is a link target as a
+ * whole: pressing anywhere on it follows the link in its `title`, while that link stays a normal
+ * anchor in your markup for keyboard users, screen readers and search engines.
+ *
+ * Slots: `image`, `meta` (a date, reading time, tags), `title` (a heading containing the link),
+ * the default slot (a short description) and `footer` (extra links or buttons).
+ */
+export abstract class StCard extends StRowItem {
+  /** Comma-separated topics, used by the list's filter, such as `web, design`. */
+  @property({type: String}) tags = "";
+  /** Set by the list: a column of cards, or one card per row with the picture beside it. */
+  @property({type: String, reflect: true}) layout: "grid" | "list" = "grid";
+
+  static styles = [
+    resetStyles,
+    css`
+      :host {
+        display: block;
+      }
+
+      article {
+        display: flex;
+        flex-direction: column;
+        height: 100%;
+        overflow: hidden;
+        border: 1px solid var(--st-color-border);
+        border-radius: var(--st-radius-lg);
+        background: var(--st-row-card-bg, var(--st-color-surface));
+        transition:
+          border-color 0.2s ease,
+          box-shadow 0.2s ease;
+      }
+
+      :host([data-linked]) article {
+        cursor: pointer;
+      }
+
+      :host([data-linked]:hover) article {
+        border-color: var(--st-color-primary);
+        box-shadow: var(--st-shadow-md);
+      }
+
+      :host(:focus-within) article {
+        border-color: var(--st-color-primary);
+        outline: 2px solid var(--st-color-primary);
+        outline-offset: 2px;
+      }
+
+      .image:empty,
+      .image[hidden] {
+        display: none;
+      }
+
+      .image ::slotted(*) {
+        display: block;
+        width: 100%;
+        height: 100%;
+        aspect-ratio: 16 / 9;
+        object-fit: cover;
+      }
+
+      .body {
+        display: grid;
+        flex: 1;
+        align-content: start;
+        gap: var(--st-spacing-sm);
+        padding: var(--st-spacing-lg);
+      }
+
+      ::slotted([slot="meta"]) {
+        display: flex;
+        flex-wrap: wrap;
+        gap: var(--st-spacing-sm);
+        color: var(--st-color-text-muted);
+        font-size: var(--st-font-size-sm);
+      }
+
+      ::slotted([slot="title"]) {
+        margin: 0 !important;
+        font-size: var(--st-font-size-xl) !important;
+      }
+
+      .description {
+        color: var(--st-color-text-muted);
+      }
+
+      .description ::slotted(*) {
+        margin: 0;
+      }
+
+      .footer {
+        display: flex;
+        flex-wrap: wrap;
+        gap: var(--st-spacing-md);
+        padding: 0 var(--st-spacing-lg) var(--st-spacing-lg);
+      }
+
+      .footer[hidden] {
+        display: none;
+      }
+
+      .content {
+        display: contents;
+      }
+
+      /* One card per row, with the picture beside the text. */
+      @media (min-width: 40rem) {
+        :host([layout="list"]) article {
+          flex-direction: row;
+        }
+
+        :host([layout="list"]) .image {
+          flex: 0 0 34%;
+        }
+
+        :host([layout="list"]) .image ::slotted(*) {
+          aspect-ratio: auto;
+        }
+
+        :host([layout="list"]) .content {
+          display: flex;
+          flex: 1;
+          flex-direction: column;
+        }
+      }
+
+      @media (prefers-reduced-motion: reduce) {
+        article {
+          transition: none;
+        }
+      }
+    `,
+  ];
+
+  /** The topics as a clean list. */
+  get tagList(): string[] {
+    return this.tags
+      .split(",")
+      .map((tag) => tag.trim())
+      .filter(Boolean);
+  }
+
+  connectedCallback() {
+    super.connectedCallback();
+    this.addEventListener("click", this._onClick);
+    this._markLinked();
+  }
+
+  disconnectedCallback() {
+    this.removeEventListener("click", this._onClick);
+    super.disconnectedCallback();
+  }
+
+  private _titleLink(): HTMLAnchorElement | null {
+    return this.querySelector<HTMLAnchorElement>(':scope > [slot="title"] a[href], :scope > a[slot="title"]');
+  }
+
+  private _markLinked() {
+    this.toggleAttribute("data-linked", !!this._titleLink());
+  }
+
+  private _onClick = (e: MouseEvent) => {
+    if (e.defaultPrevented || e.button !== 0) return;
+    // Real links, buttons and fields inside the card keep doing their own thing.
+    const interactive = e
+      .composedPath()
+      .some((el) => el instanceof HTMLElement && el !== this && el.matches("a, button, input, select, textarea, summary"));
+    if (interactive) return;
+    this._titleLink()?.click();
+  };
+
+  protected renderCard(): TemplateResult {
+    return this.frame(html`
+      <article>
+        <div class="image"><slot name="image"></slot></div>
+        <div class="content">
+          <div class="body">
+            <slot name="meta"></slot>
+            <slot name="title" @slotchange=${() => this._markLinked()}></slot>
+            <div class="description"><slot></slot></div>
+          </div>
+          <div class="footer"><slot name="footer"></slot></div>
+        </div>
+      </article>
+    `);
+  }
+
+  render() {
+    return this.renderCard();
+  }
+}

package/src/components/section/row-item.ts

@@ -0,0 +1,38 @@
+import {LitElement, html, TemplateResult} from "lit";
+import {property} from "lit/decorators.js";
+import type {RevealEffect} from "../reveal/reveal.constants.js";
+import "../reveal/reveal.js";
+
+/**
+ * Base class for the repeated items inside a row (a feature, a stat, a testimonial...). It makes
+ * each item animate in as it is scrolled to. The row hands down its own `reveal` setting and a
+ * small delay by position, so items arrive one after another. Set `reveal` on an item to
+ * override the row.
+ */
+export abstract class StRowItem extends LitElement {
+  /** How the item animates in. Leave empty to follow the row it is in. */
+  @property({type: String, reflect: true}) reveal: RevealEffect | "" = "";
+  /** The row's own effect, set by the row. */
+  @property({attribute: false}) inheritedReveal: RevealEffect = "slide-up";
+  /** Milliseconds before the animation starts. Set by the row. */
+  @property({type: Number, attribute: "reveal-delay"}) revealDelay = 0;
+
+  /** The effect in use: the item's own, otherwise its row's. */
+  get effect(): RevealEffect {
+    return this.reveal || this.inheritedReveal;
+  }
+
+  /** Wraps the item's content so it animates in. */
+  protected frame(content: TemplateResult): TemplateResult {
+    return html`
+      <st-reveal
+        effect=${this.effect}
+        delay=${this.revealDelay}
+        offset="5"
+        style="display: block; height: 100%"
+      >
+        ${content}
+      </st-reveal>
+    `;
+  }
+}

package/src/components/section/section.ts

@@ -0,0 +1,232 @@
+import {LitElement, html, css, nothing, isServer, PropertyValues, TemplateResult} from "lit";
+import {customElement, property, state} from "lit/decorators.js";
+import {resetStyles} from "../../styles/reset.js";
+import type {ContainerSize} from "../container/container.js";
+import type {RevealEffect} from "../reveal/reveal.constants.js";
+import "../container/container.js";
+import "../reveal/reveal.js";
+import {StRowItem} from "./row-item.js";
+
+export const sectionTones = ["auto", "default", "surface", "accent"] as const;
+export type SectionTone = (typeof sectionTones)[number];
+export const sectionSpaces = ["none", "sm", "md", "lg"] as const;
+export type SectionSpace = (typeof sectionSpaces)[number];
+
+const HEADER_SLOTS = ["eyebrow", "title", "lead"];
+
+/** Items in a row animate in turn, three at a time, so late items don't wait to be seen. */
+const ITEM_DELAY_MS = 120;
+const ITEMS_PER_WAVE = 3;
+
+/**
+ * A full-width row of a page: a background, responsive vertical spacing, a centred container and
+ * an optional header made of an eyebrow, title and lead. Stack rows to build a page. The ready-made
+ * rows (hero, features, call to action and so on) are all built on it, so every row shares the
+ * same spacing, header, tones and animation, and any row can follow any other.
+ *
+ * Slots: `eyebrow`, `title`, `lead` (the header: slot real headings so search engines and screen
+ * readers understand the page outline) and the default slot for the content.
+ *
+ * Tone: by default (`auto`) neighbouring rows alternate between the page and surface colours, so
+ * stacked rows are visually separated with no effort. Set `tone` to choose one yourself.
+ *
+ * Animation: the header and content animate in as they scroll into view (`reveal`, turn off with
+ * `reveal="none"`). Give the host an `id` to link to it (`#pricing`). Off-screen rows are not
+ * rendered until they are near the viewport (`content-visibility`); add `eager` to turn that off.
+ */
+@customElement("st-section")
+export class StSection extends LitElement {
+  /** `auto` alternates between rows; the others are fixed. */
+  @property({type: String, reflect: true}) tone: SectionTone = "auto";
+  /** Vertical padding. */
+  @property({type: String, reflect: true}) space: SectionSpace = "md";
+  /** Maximum width of the content. */
+  @property({type: String, reflect: true}) width: ContainerSize = "lg";
+  /** Alignment of the header block. */
+  @property({type: String, reflect: true}) align: "start" | "center" = "center";
+  /** How the row animates in as it is scrolled to. `none` turns it off. */
+  @property({type: String, reflect: true}) reveal: RevealEffect = "slide-up";
+  /** Accessible name. When set the section becomes a labelled landmark. */
+  @property({type: String}) label = "";
+  /** Renders immediately even when off screen. */
+  @property({type: Boolean, reflect: true}) eager = false;
+
+  @state() private _hasHeader = false;
+
+  static styles = [
+    resetStyles,
+    css`
+      :host {
+        display: block;
+        /* The align attribute doubles as an old HTML text-align hint; only the header should centre. */
+        text-align: start;
+        scroll-margin-top: var(--st-section-scroll-offset, var(--st-site-header-height, 0px));
+        background: var(--_bg, var(--st-color-bg));
+        color: var(--_fg, var(--st-color-text));
+        --_pad: var(--st-section-space-md);
+        /* Cards and tiles inside a row read this so they stand out from the row behind them. */
+        --st-row-card-bg: var(--st-color-surface);
+      }
+
+      :host(:not([eager])) {
+        content-visibility: auto;
+        contain-intrinsic-size: auto 36rem;
+      }
+
+      :host([tone="surface"]) {
+        --_bg: var(--st-color-surface);
+        --st-row-card-bg: var(--st-color-bg);
+      }
+
+      /* Auto: every second row takes the surface colour. Pure CSS, so it also works before any
+         JavaScript runs and with server rendering. */
+      :host([tone="auto"]:nth-child(even)) {
+        --_bg: var(--st-color-surface);
+        --st-row-card-bg: var(--st-color-bg);
+      }
+
+      :host([tone="accent"]) {
+        --_bg: var(--st-color-primary);
+        --_fg: var(--st-color-on-primary);
+        --_muted: var(--st-color-on-primary);
+        --st-row-card-bg: rgb(255 255 255 / 0.12);
+      }
+
+      :host([space="none"]) {
+        --_pad: 0;
+      }
+      :host([space="sm"]) {
+        --_pad: var(--st-section-space-sm);
+      }
+      :host([space="lg"]) {
+        --_pad: var(--st-section-space-lg);
+      }
+
+      .section {
+        padding-block: var(--_pad);
+      }
+
+      .header {
+        display: grid;
+        gap: var(--st-spacing-sm);
+        max-width: 48rem;
+        margin-bottom: var(--st-spacing-2xl);
+      }
+
+      :host([align="center"]) .header {
+        margin-inline: auto;
+        text-align: center;
+      }
+
+      ::slotted([slot="eyebrow"]) {
+        margin: 0;
+        color: var(--_eyebrow, var(--st-color-primary-text));
+        font-size: var(--st-font-size-sm);
+        font-weight: var(--st-font-weight-bold);
+        letter-spacing: 0.08em;
+        text-transform: uppercase;
+      }
+
+      :host([tone="accent"]) ::slotted([slot="eyebrow"]) {
+        --_eyebrow: var(--st-color-on-primary);
+      }
+
+      ::slotted([slot="title"]) {
+        margin: 0 !important;
+        color: inherit;
+        font-size: var(--st-font-size-3xl) !important;
+        line-height: var(--st-line-height-tight) !important;
+      }
+
+      ::slotted([slot="lead"]) {
+        margin: 0;
+        color: var(--_muted, var(--st-color-text-muted));
+        font-size: var(--st-font-size-lg);
+      }
+
+      [hidden] {
+        display: none !important;
+      }
+    `,
+  ];
+
+  private _onHeaderSlotChange = () => (this._hasHeader = this._headerPresent());
+
+  protected willUpdate(changed: PropertyValues<this>) {
+    // Know about the header before the first render, so a row at the top of the page is shown
+    // straight away instead of fading in once its header is discovered. (The server cannot look.)
+    if (!this.hasUpdated) this._hasHeader = isServer || this._headerPresent();
+    super.willUpdate(changed);
+  }
+
+  private _headerPresent() {
+    return HEADER_SLOTS.some((name) => this.querySelector(`:scope > [slot="${name}"]`));
+  }
+
+  /** Hands the row's animation settings to any item components inside it. */
+  protected _onItemsChange = (e: Event) => {
+    const items = (e.target as HTMLSlotElement)
+      .assignedElements({flatten: true})
+      .filter((el): el is StRowItem => el instanceof StRowItem);
+    items.forEach((item, i) => {
+      item.inheritedReveal = this.reveal;
+      item.revealDelay = (i % ITEMS_PER_WAVE) * ITEM_DELAY_MS;
+    });
+  };
+
+  protected updated(changed: PropertyValues<this>) {
+    // A row that changes its animation after load passes the change on to its items.
+    if (changed.has("reveal") && changed.get("reveal") !== undefined) {
+      this.renderRoot.querySelector("slot:not([name])")?.dispatchEvent(new Event("slotchange"));
+    }
+  }
+
+  /** The eyebrow, title and lead. Rows that lay the header out themselves call this directly. */
+  protected renderHeader(): TemplateResult {
+    return html`
+      <st-reveal class="header-reveal" effect=${this.reveal} ?hidden=${!this._hasHeader}>
+        <div class="header">
+          ${HEADER_SLOTS.map(
+            (name) => html`<slot name=${name} @slotchange=${this._onHeaderSlotChange}></slot>`,
+          )}
+        </div>
+      </st-reveal>
+    `;
+  }
+
+  /** Wraps part of a row so it animates in with the row's effect. */
+  protected animateIn(content: TemplateResult, delay = 0): TemplateResult {
+    return html`<st-reveal effect=${this.reveal} delay=${delay}>${content}</st-reveal>`;
+  }
+
+  /**
+   * The band every row sits in. Pass the row's content.
+   *  - `header: false`: the row lays the header out itself and calls `renderHeader()`.
+   *  - `animated: false`: the row animates its own parts (or its items do), so the content is not
+   *    wrapped in a second animation.
+   */
+  protected frame(
+    content: TemplateResult,
+    options: {header?: boolean; animated?: boolean} = {},
+  ): TemplateResult {
+    const {header = true, animated = true} = options;
+    return html`
+      <div class="section" role=${this.label ? "region" : nothing} aria-label=${this.label || nothing}>
+        <st-container size=${this.width}>
+          ${header ? this.renderHeader() : nothing}
+          ${animated ? this.animateIn(content, 100) : content}
+        </st-container>
+      </div>
+    `;
+  }
+
+  render() {
+    return this.frame(html`<slot @slotchange=${this._onItemsChange}></slot>`);
+  }
+}
+
+declare global {
+  interface HTMLElementTagNameMap {
+    "st-section": StSection;
+  }
+}

package/src/components/select/select.ts

@@ -94,7 +94,7 @@ export class StSelect extends LitElement {
     }
 
     .combobox.is-invalid {
-      border-color: var(--st-color-danger, #dc2626);
+      border-color: var(--st-color-danger);
     }
 
     .combobox:focus-visible {
@@ -136,7 +136,7 @@ export class StSelect extends LitElement {
       background: var(--st-color-surface);
       border: 1px solid var(--st-color-border);
       border-radius: var(--st-radius-md);
-      box-shadow: 0 4px 6px -1px rgba(0, 0, 0, 0.1);
+      box-shadow: var(--st-shadow-md);
       overflow: hidden;
     }
 
@@ -191,7 +191,7 @@ export class StSelect extends LitElement {
       display: block;
       margin-top: var(--st-spacing-xs);
       font-size: var(--st-font-size-xs);
-      color: var(--st-color-danger, #dc2626);
+      color: var(--st-color-danger);
     }
 
     .hidden-native {