@repobit/dex-system-design 0.23.94 → 0.23.96

package/src/blog/src/atoms/blog-table-of-contents.js

@@ -0,0 +1,447 @@
+import { css, html, nothing } from 'lit';
+import { BlogElement } from '../base/blog-element.js';
+import {
+  findArticleSubhead,
+  getTocScrollLock,
+  resolveActiveTocId,
+  scrollToHeading,
+  setTocScrollLock,
+  watchTocScrollEnd
+} from '../lib/article-toc.js';
+
+/**
+ * Article table of contents — anchor links to in-body subheads.
+ * Highlights the active chapter with a blue marker while scrolling.
+ *
+ * @property {string} title
+ * @property {Array<{ id: string, label: string }>} items
+ * @property {boolean} collapsible — collapsed by default; mobile inline TOC
+ */
+export class BlogTableOfContents extends BlogElement {
+  static properties = {
+    title      : { type: String },
+    items      : { type: Array },
+    collapsible: { type: Boolean, reflect: true },
+    activeId   : { type: String, state: true },
+    isOpen     : { type: Boolean, state: true }
+  };
+
+  constructor() {
+    super();
+    this.title = 'Contents';
+    this.items = [];
+    this.collapsible = false;
+    this.isOpen = false;
+    this.activeId = '';
+    /** @type {Array<{ id: string, el: Element }>} */
+    this._headings = [];
+    /** @type {(() => void) | null} */
+    this._onScroll = null;
+    /** @type {number} */
+    this._scrollRaf = 0;
+    /** @type {number} */
+    this._spyRetry = 0;
+  }
+
+  static styles = [
+    ...BlogElement.styles,
+    css`
+      :host {
+        display: block;
+      }
+
+      .toc {
+        border: var(--blog-takeaways-border-width) solid
+          var(--blog-takeaways-border-color);
+        border-radius: var(--blog-takeaways-borderRadius);
+        background: var(--blog-takeaways-background);
+        overflow: hidden;
+      }
+
+      .toc__header {
+        padding: var(--blog-takeaways-header-padding-block)
+          var(--blog-takeaways-padding-inline);
+        padding-bottom: var(--blog-takeaways-header-padding-bottom);
+      }
+
+      :host([collapsible]) .toc__header {
+        padding-bottom: var(--blog-takeaways-header-padding-block);
+      }
+
+      .toc__title {
+        margin: 0;
+        font-family: var(--blog-takeaways-title-fontFamily);
+        font-size: var(--blog-takeaways-title-fontSize);
+        font-weight: var(--blog-takeaways-title-fontWeight);
+        line-height: var(--blog-takeaways-title-lineHeight);
+        color: var(--blog-takeaways-title-color);
+      }
+
+      .toc__toggle {
+        display: flex;
+        align-items: center;
+        justify-content: space-between;
+        gap: var(--spacing-12);
+        width: 100%;
+        margin: 0;
+        padding: 0;
+        border: 0;
+        background: transparent;
+        cursor: pointer;
+        text-align: left;
+        font: inherit;
+        color: inherit;
+      }
+
+      .toc__toggle:focus-visible {
+        outline: var(--focus-outline-traditional);
+        outline-offset: var(--focus-outline-offset);
+      }
+
+      .toc__toggle-icon {
+        flex-shrink: 0;
+        display: flex;
+        align-items: center;
+        justify-content: center;
+        width: var(--blog-toc-toggle-size);
+        height: var(--blog-toc-toggle-size);
+        font-family: var(--typography-fontFamily-sans);
+        font-size: var(--blog-toc-toggle-fontSize);
+        font-weight: var(--typography-fontWeight-normal);
+        line-height: var(--typography-lineHeight-none);
+        color: var(--blog-toc-toggle-color);
+        transition: color var(--transition-duration-fast)
+          var(--transition-easing-ease-out);
+      }
+
+      .toc__toggle:hover .toc__toggle-icon,
+      .toc__toggle:focus-visible .toc__toggle-icon {
+        color: var(--blog-toc-toggle-hover-color);
+      }
+
+      .toc__divider {
+        margin: 0;
+        border: 0;
+        border-top: var(--blog-takeaways-divider-width) solid
+          var(--blog-takeaways-divider-color);
+      }
+
+      :host([collapsible]) .toc--collapsed .toc__divider,
+      :host([collapsible]) .toc--collapsed .toc__list {
+        display: none;
+      }
+
+      .toc__list {
+        margin: 0;
+        padding: var(--blog-takeaways-body-padding-top)
+          var(--blog-takeaways-padding-inline)
+          var(--blog-takeaways-body-padding-bottom);
+        list-style: none;
+      }
+
+      .toc__item {
+        position: relative;
+      }
+
+      .toc__item::before {
+        content: '';
+        position: absolute;
+        left: calc(
+          -1 * (var(--blog-toc-marker-size) + var(--blog-toc-marker-gap))
+        );
+        top: var(--blog-toc-marker-offset-top);
+        width: var(--blog-toc-marker-size);
+        height: var(--blog-toc-marker-size);
+        border-radius: var(--radius-full);
+        background: transparent;
+        transform: translateY(-50%);
+        transition: background-color var(--transition-duration-fast)
+          var(--transition-easing-ease-out);
+      }
+
+      .toc__item[data-active]::before {
+        background: var(--blog-toc-marker-color);
+      }
+
+      .toc__list li + li {
+        margin-top: var(--blog-toc-item-gap);
+      }
+
+      .toc__link {
+        display: block;
+        font-family: var(--typography-fontFamily-sans);
+        font-size: var(--blog-toc-link-fontSize);
+        font-weight: var(--blog-toc-link-fontWeight);
+        line-height: var(--blog-toc-link-lineHeight);
+        color: var(--blog-toc-link-color);
+        text-decoration: none;
+        transition: color var(--transition-duration-fast)
+          var(--transition-easing-ease-out);
+      }
+
+      .toc__item[data-active] .toc__link {
+        color: var(--blog-toc-link-active-color);
+        font-weight: var(--typography-fontWeight-medium);
+      }
+
+      .toc__link:hover {
+        color: var(--blog-toc-link-hover-color);
+        text-decoration: underline;
+      }
+
+      .toc__link:focus-visible {
+        outline: var(--focus-outline-traditional);
+        outline-offset: var(--focus-outline-offset);
+      }
+    `
+  ];
+
+  connectedCallback() {
+    super.connectedCallback();
+    this._spyRetry = requestAnimationFrame(() => this._attachScrollSpy());
+  }
+
+  updated(changed) {
+    if (changed.has('items')) {
+      this._detachScrollSpy();
+      this._spyRetry = requestAnimationFrame(() => this._attachScrollSpy());
+    }
+  }
+
+  disconnectedCallback() {
+    super.disconnectedCallback();
+    cancelAnimationFrame(this._spyRetry);
+    this._detachScrollSpy();
+  }
+
+  _findHeading(id) {
+    const root = this.getRootNode();
+
+    if (root && root !== this) {
+      const inRoot =
+        root instanceof Document
+          ? document.getElementById(id)
+          : (root.getElementById?.(id) ??
+            root.querySelector?.(`blog-subhead[id="${CSS.escape(id)}"]`));
+
+      if (inRoot) {
+        return inRoot;
+      }
+    }
+
+    return findArticleSubhead(id);
+  }
+
+  _attachScrollSpy() {
+    const root = this.getRootNode();
+
+    if (!root || root === this) {
+      return;
+    }
+
+    this._headings = this.items
+      .map(({ id }) => {
+        const el = this._findHeading(id);
+        return el ? { id, el } : null;
+      })
+      .filter(Boolean);
+
+    if (!this._headings.length) {
+      return;
+    }
+
+    this._onScroll = () => {
+      if (this._scrollRaf) {
+        return;
+      }
+
+      this._scrollRaf = requestAnimationFrame(() => {
+        this._scrollRaf = 0;
+        this._updateActiveId();
+      });
+    };
+
+    window.addEventListener('scroll', this._onScroll, { passive: true });
+    this._updateActiveId();
+    this._scrollToInitialHash();
+  }
+
+  _scrollToInitialHash() {
+    const hashId = window.location.hash.slice(1);
+
+    if (!hashId || !this._headings.some(({ id }) => id === hashId)) {
+      return;
+    }
+
+    requestAnimationFrame(() => {
+      const target = this._findHeading(hashId);
+
+      if (!target) {
+        return;
+      }
+
+      setTocScrollLock(hashId);
+      scrollToHeading(target, this._scrollOffset(), 'auto');
+      this.activeId = hashId;
+      watchTocScrollEnd((lockedId) => {
+        if (lockedId) {
+          this.activeId = lockedId;
+        }
+      });
+    });
+  }
+
+  _detachScrollSpy() {
+    if (this._onScroll) {
+      window.removeEventListener('scroll', this._onScroll);
+      this._onScroll = null;
+    }
+
+    if (this._scrollRaf) {
+      cancelAnimationFrame(this._scrollRaf);
+      this._scrollRaf = 0;
+    }
+
+    this._headings = [];
+  }
+
+  _scrollOffset() {
+    const heading = this._headings[0]?.el;
+
+    if (heading) {
+      const margin = getComputedStyle(heading).scrollMarginTop.trim();
+      const parsed = Number.parseFloat(margin);
+
+      if (Number.isFinite(parsed)) {
+        return parsed;
+      }
+    }
+
+    return this._readTokenPx('--blog-toc-scroll-offset', 48);
+  }
+
+  _readingLineOffset() {
+    return this._readTokenPx('--blog-toc-reading-line-offset', 128);
+  }
+
+  _readTokenPx(token, fallback) {
+    const value = getComputedStyle(this).getPropertyValue(token)
+      .trim();
+    const parsed = Number.parseFloat(value);
+
+    return Number.isFinite(parsed) ? parsed : fallback;
+  }
+
+  _updateActiveId() {
+    if (!this._headings.length) {
+      return;
+    }
+
+    const lockedId = getTocScrollLock();
+
+    if (lockedId) {
+      if (this.activeId !== lockedId) {
+        this.activeId = lockedId;
+      }
+      return;
+    }
+
+    const active = resolveActiveTocId(this._headings, this._readingLineOffset());
+
+    if (this.activeId !== active) {
+      this.activeId = active;
+    }
+  }
+
+  _toggleExpanded() {
+    this.isOpen = !this.isOpen;
+  }
+
+  /** @param {Event} event @param {string} id */
+  _onLinkClick(event, id) {
+    event.preventDefault();
+
+    const target = this._findHeading(id);
+
+    if (!target) {
+      return;
+    }
+
+    setTocScrollLock(id);
+    this.activeId = id;
+    scrollToHeading(target, this._scrollOffset());
+    history.pushState(null, '', `#${id}`);
+    watchTocScrollEnd((lockedId) => {
+      if (lockedId) {
+        this.activeId = lockedId;
+      }
+    });
+  }
+
+  _renderHeader() {
+    if (this.collapsible) {
+      return html`
+        <header class="toc__header">
+          <button
+            type="button"
+            class="toc__toggle"
+            part="toggle"
+            aria-expanded=${this.isOpen ? 'true' : 'false'}
+            aria-controls="toc-list"
+            @click=${this._toggleExpanded}
+          >
+            <span class="toc__title" part="title">${this.title}</span>
+            <span class="toc__toggle-icon" part="toggle-icon" aria-hidden="true"
+              >${this.isOpen ? '−' : '+'}</span
+            >
+          </button>
+        </header>
+      `;
+    }
+
+    return html`
+      <header class="toc__header">
+        <h2 class="toc__title" part="title">${this.title}</h2>
+      </header>
+    `;
+  }
+
+  render() {
+    if (!this.items.length) {
+      return null;
+    }
+
+    return html`
+      <nav
+        class="toc ${this.collapsible && !this.isOpen ? 'toc--collapsed' : ''}"
+        part="toc"
+        aria-label=${this.title}
+      >
+        ${this._renderHeader()}
+        <hr class="toc__divider" />
+        <ol id="toc-list" class="toc__list" part="list">
+          ${this.items.map(
+            (item) => html`
+              <li
+                class="toc__item"
+                part="item"
+                data-active=${item.id === this.activeId || nothing}
+              >
+                <a
+                  class="toc__link"
+                  part="link"
+                  href="#${item.id}"
+                  aria-current=${item.id === this.activeId ? 'location' : nothing}
+                  @click=${(event) => this._onLinkClick(event, item.id)}
+                  >${item.label}</a
+                >
+              </li>
+            `
+          )}
+        </ol>
+      </nav>
+    `;
+  }
+}
+
+customElements.define('blog-table-of-contents', BlogTableOfContents);

package/src/blog/src/atoms/blog-tag.js

@@ -0,0 +1,86 @@
+import { css, html } from 'lit';
+import { BlogElement } from '../base/blog-element.js';
+
+/**
+ * Blog category/tag chip.
+ *
+ * @attr {string} label - Visible text
+ * @attr {string} href - Optional link URL
+ * @attr {'default'|'brand'} variant - Visual style
+ */
+export class BlogTag extends BlogElement {
+  static properties = {
+    label  : { type: String },
+    href   : { type: String },
+    variant: { type: String, reflect: true }
+  };
+
+  constructor() {
+    super();
+    this.label = '';
+    this.href = '';
+    this.variant = 'default';
+  }
+
+  static styles = [
+    ...BlogElement.styles,
+    css`
+      :host {
+        display: inline-block;
+      }
+
+      .tag {
+        display: inline-flex;
+        align-items: center;
+        gap: var(--blog-tag-gap);
+        padding: var(--blog-tag-padding);
+        font-family: var(--typography-fontFamily-sans);
+        font-size: var(--blog-tag-fontSize);
+        font-weight: var(--blog-tag-fontWeight);
+        line-height: var(--blog-tag-lineHeight);
+        border-radius: var(--blog-tag-borderRadius);
+        border: var(--blog-tag-border-width) solid
+          var(--blog-tag-default-border-color);
+        background: var(--blog-tag-default-background);
+        color: var(--blog-tag-default-color);
+        text-decoration: none;
+        transition: background-color var(--transition-duration-fast)
+            var(--transition-easing-smooth),
+          color var(--transition-duration-fast) var(--transition-easing-smooth),
+          border-color var(--transition-duration-fast)
+            var(--transition-easing-smooth);
+      }
+
+      :host([variant='brand']) .tag {
+        background: var(--blog-tag-brand-background);
+        color: var(--blog-tag-brand-color);
+        border-color: var(--blog-tag-brand-border-color);
+      }
+
+      :host([variant='brand']) .tag:hover {
+        background: var(--blog-tag-brand-hover-background);
+        color: var(--blog-tag-brand-hover-color);
+      }
+
+      :host(:not([variant='brand'])) .tag:hover {
+        background: var(--blog-tag-hover-background);
+        color: var(--blog-tag-hover-color);
+      }
+
+      .tag:focus-visible {
+        outline: var(--focus-outline-traditional);
+        outline-offset: var(--focus-outline-offset);
+      }
+    `
+  ];
+
+  render() {
+    if (this.href) {
+      return html`<a class="tag" href=${this.href} part="tag">${this.label}</a>`;
+    }
+
+    return html`<span class="tag" part="tag">${this.label}</span>`;
+  }
+}
+
+customElements.define('blog-tag', BlogTag);

package/src/blog/src/atoms/blog-title.js

@@ -0,0 +1,31 @@
+import { css, html } from 'lit';
+import { BlogElement } from '../base/blog-element.js';
+
+/** Article H1 — hero display title */
+export class BlogTitle extends BlogElement {
+  static styles = [
+    ...BlogElement.styles,
+    css`
+      :host {
+        display: block;
+      }
+
+      h1 {
+        margin: 0;
+        font-family: var(--blog-hero-title-fontFamily);
+        font-size: var(--blog-hero-title-fontSize);
+        font-weight: var(--blog-hero-title-fontWeight);
+        font-style: normal;
+        line-height: var(--blog-hero-title-lineHeight);
+        letter-spacing: var(--typography-display-md-letterSpacing);
+        color: var(--blog-hero-title-color);
+      }
+    `
+  ];
+
+  render() {
+    return html`<h1 part="title"><slot></slot></h1>`;
+  }
+}
+
+customElements.define('blog-title', BlogTitle);

package/src/blog/src/base/blog-element.js

@@ -0,0 +1,10 @@
+import { LitElement } from 'lit';
+import { blogTokens, tokens } from '../tokens/index.js';
+
+/**
+ * Base class for blog web components.
+ * Applies core + blog tokens to :host for shadow DOM.
+ */
+export class BlogElement extends LitElement {
+  static styles = [tokens, blogTokens];
+}

package/src/blog/src/breakpoints.js

@@ -0,0 +1,23 @@
+/** Breakpoint values in px — use in JS; CSS media queries cannot use var() */
+export const breakpoints = {
+  xs: 0,
+  sm: 576,
+  md: 768,
+  lg: 992,
+  xl: 1200,
+  xxl: 1400,
+};
+
+/** Returns a min-width media query string for use in Lit css templates */
+export function minWidth(bp) {
+  const value = breakpoints[bp];
+  if (value === undefined) {
+    throw new Error(`Unknown breakpoint: ${bp}`);
+  }
+  return `@media (min-width: ${value}px)`;
+}
+
+/** Match media query in JS */
+export function matchesBreakpoint(bp) {
+  return window.matchMedia(`(min-width: ${breakpoints[bp]}px)`).matches;
+}