@repobit/dex-system-design 0.23.95 → 0.23.97

package/src/blog/src/index.js

@@ -0,0 +1,104 @@
+import './shell/blog-shell.js';
+
+import './atoms/blog-tag.js';
+
+import './atoms/blog-avatar.js';
+
+import './atoms/blog-meta.js';
+
+import './atoms/blog-title.js';
+
+import './atoms/blog-authors.js';
+
+import './atoms/blog-abstract.js';
+
+import './atoms/blog-product-upsell.js';
+
+import './atoms/blog-dek.js';
+
+import './atoms/blog-paragraph.js';
+
+import './atoms/blog-heading.js';
+import './atoms/blog-subhead.js';
+import './atoms/blog-related-label.js';
+
+import './atoms/blog-key-takeaways.js';
+
+import './atoms/blog-link.js';
+
+import './atoms/blog-featured-image.js';
+
+import './atoms/blog-image.js';
+
+import './atoms/blog-caption.js';
+
+import './atoms/blog-blockquote.js';
+import './atoms/blog-code-block.js';
+import './atoms/blog-standout.js';
+
+import './atoms/blog-table-of-contents.js';
+import './atoms/blog-related-articles.js';
+
+import './atoms/blog-newsletter-signup.js';
+
+import './atoms/blog-report-promo.js';
+
+import './content/blog-page-layout.js';
+
+import './content/blog-atoms-showcase.js';
+
+import './content/blog-article.js';
+
+
+
+export { BlogElement } from './base/blog-element.js';
+
+export { BlogTag } from './atoms/blog-tag.js';
+
+export { BlogAvatar } from './atoms/blog-avatar.js';
+
+export { BlogMeta } from './atoms/blog-meta.js';
+
+export { BlogTitle } from './atoms/blog-title.js';
+
+export { BlogAuthors } from './atoms/blog-authors.js';
+
+export { BlogAbstract } from './atoms/blog-abstract.js';
+export { BlogProductUpsell } from './atoms/blog-product-upsell.js';
+export { BlogDek } from './atoms/blog-dek.js';
+
+export { BlogParagraph } from './atoms/blog-paragraph.js';
+
+export { BlogHeading } from './atoms/blog-heading.js';
+export { BlogSubhead } from './atoms/blog-subhead.js';
+export { BlogRelatedLabel } from './atoms/blog-related-label.js';
+
+export { BlogKeyTakeaways } from './atoms/blog-key-takeaways.js';
+
+export { BlogLink } from './atoms/blog-link.js';
+
+export { BlogFeaturedImage } from './atoms/blog-featured-image.js';
+
+export { BlogImage } from './atoms/blog-image.js';
+
+export { BlogCaption } from './atoms/blog-caption.js';
+
+export { BlogBlockquote } from './atoms/blog-blockquote.js';
+export { BlogCodeBlock } from './atoms/blog-code-block.js';
+export { BlogStandout } from './atoms/blog-standout.js';
+export { BlogTableOfContents } from './atoms/blog-table-of-contents.js';
+export { BlogRelatedArticles } from './atoms/blog-related-articles.js';
+
+export { BlogReportPromo } from './atoms/blog-report-promo.js';
+
+export { BlogNewsletterSignup } from './atoms/blog-newsletter-signup.js';
+
+export { BlogShell } from './shell/blog-shell.js';
+
+export { BlogAtomsShowcase } from './content/blog-atoms-showcase.js';
+
+export { BlogArticle } from './content/blog-article.js';
+export { BlogPageLayout } from './content/blog-page-layout.js';
+
+export { breakpoints, minWidth, matchesBreakpoint } from './breakpoints.js';
+

package/src/blog/src/lib/article-toc.js

@@ -0,0 +1,206 @@
+/** @param {string} text */
+export function slugify(text) {
+  return text
+    .toLowerCase()
+    .trim()
+    .replace(/[^\w\s-]/g, '')
+    .replace(/\s+/g, '-')
+    .replace(/-+/g, '-');
+}
+
+/** @param {Array<Record<string, unknown>>} blocks */
+export function assignSubheadAnchors(blocks) {
+  const seen = new Map();
+
+  return blocks.map((block) => {
+    if (block.type !== 'subhead' || typeof block.text !== 'string') {
+      return block;
+    }
+
+    let id = slugify(block.text);
+    const count = seen.get(id) ?? 0;
+    seen.set(id, count + 1);
+
+    if (count > 0) {
+      id = `${id}-${count + 1}`;
+    }
+
+    return { ...block, anchorId: id };
+  });
+}
+
+/** @param {Array<Record<string, unknown>>} blocks */
+export function buildTocItems(blocks) {
+  return blocks
+    .filter((block) => block.type === 'subhead' && typeof block.text === 'string')
+    .map((block) => ({
+      id: block.anchorId ?? slugify(block.text),
+      label: block.text,
+    }));
+}
+
+/**
+ * Scroll so a heading sits below the top offset (matches scroll-margin behavior).
+ *
+ * @param {Element} el
+ * @param {number} offsetPx
+ * @param {ScrollBehavior} [behavior]
+ */
+export function scrollToHeading(el, offsetPx, behavior = 'smooth') {
+  window.scrollTo({
+    top: getHeadingDocumentTop(el) - offsetPx,
+    behavior,
+  });
+}
+
+/**
+ * Document Y position of the scroll-spy reading line.
+ *
+ * @param {number} offsetPx distance from viewport top
+ */
+export function getTocReadingLine(offsetPx) {
+  return window.scrollY + offsetPx;
+}
+
+/**
+ * Absolute document Y for a heading element.
+ *
+ * @param {Element} el
+ */
+export function getHeadingDocumentTop(el) {
+  return el.getBoundingClientRect().top + window.scrollY;
+}
+
+/**
+ * Which TOC item is active.
+ *
+ * Prefers the section heading visible in the upper viewport (what the reader
+ * sees as the current chapter), then falls back to a document reading line.
+ *
+ * @param {Array<{ id: string, el: Element }>} headings
+ * @param {number} readingLineOffsetPx
+ */
+export function resolveActiveTocId(headings, readingLineOffsetPx) {
+  if (!headings.length) {
+    return '';
+  }
+
+  const titleZoneMax = Math.max(
+    readingLineOffsetPx,
+    window.innerHeight * 0.3,
+  );
+
+  let titleZoneActive = '';
+
+  for (const { id, el } of headings) {
+    const rectTop = el.getBoundingClientRect().top;
+
+    if (rectTop >= -16 && rectTop <= titleZoneMax) {
+      titleZoneActive = id;
+    }
+  }
+
+  if (titleZoneActive) {
+    return titleZoneActive;
+  }
+
+  const readingLine = getTocReadingLine(readingLineOffsetPx);
+  const tops = headings.map(({ el }) => getHeadingDocumentTop(el));
+
+  if (readingLine < tops[0]) {
+    return headings[0].id;
+  }
+
+  for (let i = 0; i < headings.length; i++) {
+    const start = tops[i];
+    const end = i + 1 < tops.length ? tops[i + 1] : Number.POSITIVE_INFINITY;
+
+    if (readingLine >= start && readingLine < end) {
+      return headings[i].id;
+    }
+  }
+
+  return headings[headings.length - 1].id;
+}
+
+/** @param {string} id */
+export function findArticleSubhead(id) {
+  const article = document.querySelector('blog-article');
+
+  if (!article?.shadowRoot) {
+    return null;
+  }
+
+  return (
+    article.shadowRoot.getElementById(id) ??
+    article.shadowRoot.querySelector(`blog-subhead[id="${CSS.escape(id)}"]`)
+  );
+}
+
+const TOC_SCROLL_LOCK = 'data-toc-scroll-lock';
+
+/** @param {string} id */
+export function setTocScrollLock(id) {
+  document.documentElement.setAttribute(TOC_SCROLL_LOCK, id);
+}
+
+export function clearTocScrollLock() {
+  document.documentElement.removeAttribute(TOC_SCROLL_LOCK);
+}
+
+export function getTocScrollLock() {
+  return document.documentElement.getAttribute(TOC_SCROLL_LOCK);
+}
+
+/** @param {() => void} onEnd */
+export function watchTocScrollEnd(onEnd) {
+  const lockedId = getTocScrollLock();
+
+  const finish = () => {
+    clearTocScrollLock();
+    onEnd(lockedId);
+  };
+
+  if ('onscrollend' in window) {
+    window.addEventListener('scrollend', finish, { once: true });
+    return;
+  }
+
+  window.setTimeout(finish, 600);
+}
+
+/**
+ * Split body blocks so the TOC can sit after Key Takeaways on narrow viewports.
+ *
+ * @param {Array<Record<string, unknown>>} blocks
+ */
+export function splitBlocksForTocPlacement(blocks) {
+  const takeawaysIndex = blocks.findIndex((block) => block.type === 'takeaways');
+
+  if (takeawaysIndex === -1) {
+    return { leading: [], trailing: blocks };
+  }
+
+  return {
+    leading: blocks.slice(0, takeawaysIndex + 1),
+    trailing: blocks.slice(takeawaysIndex + 1),
+  };
+}
+
+/**
+ * Split body at the first subhead — preamble (intro, takeaways) vs sections (TOC anchor).
+ *
+ * @param {Array<Record<string, unknown>>} blocks
+ */
+export function splitBodyAtFirstSubhead(blocks) {
+  const subheadIndex = blocks.findIndex((block) => block.type === 'subhead');
+
+  if (subheadIndex === -1) {
+    return { preamble: blocks, sections: [] };
+  }
+
+  return {
+    preamble: blocks.slice(0, subheadIndex),
+    sections: blocks.slice(subheadIndex),
+  };
+}

package/src/blog/src/lib/load-prism.js

@@ -0,0 +1,23 @@
+/** Load PrismJS (vendor bundle, manual highlight mode). */
+let loadPromise;
+
+/** @returns {Promise<typeof Prism>} */
+export function loadPrism() {
+  if (globalThis.Prism) {
+    return Promise.resolve(globalThis.Prism);
+  }
+
+  if (!loadPromise) {
+    loadPromise = new Promise((resolve, reject) => {
+      const script = document.createElement('script');
+      script.src = '/vendor/prism/prism.js';
+      script.dataset.manual = '';
+      script.onload = () => resolve(globalThis.Prism);
+      script.onerror = () =>
+        reject(new Error('Failed to load Prism from /vendor/prism/prism.js'));
+      document.head.appendChild(script);
+    });
+  }
+
+  return loadPromise;
+}

package/src/blog/src/shell/blog-shell.js

@@ -0,0 +1,31 @@
+import { css, html } from 'lit';
+import { LitElement } from 'lit';
+import { tokens, blogTokens, legacyTokens } from '../../tokens/index.js';
+
+/**
+ * Root page shell — sets base typography and exposes tokens on :host.
+ * Load tokens.css globally as well for non-component markup.
+ */
+export class BlogShell extends LitElement {
+  static styles = [
+    tokens,
+    blogTokens,
+    legacyTokens,
+    css`
+      :host {
+        display: block;
+        font-family: var(--typography-fontFamily-sans);
+        font-size: var(--typography-body-regular-fontSize);
+        line-height: var(--typography-body-regular-lineHeight);
+        color: var(--color-text-primary);
+        background: var(--color-surface);
+      }
+    `,
+  ];
+
+  render() {
+    return html`<slot></slot>`;
+  }
+}
+
+customElements.define('blog-shell', BlogShell);

package/src/blog/src/styles/prism-theme.js

@@ -0,0 +1,65 @@
+import { css } from 'lit';
+
+/** Prism token styles scoped to blog-code-block — mirrors vendor monochrome theme via tokens. */
+export const prismTheme = css`
+  pre[class*='language-'],
+  code[class*='language-'] {
+    color: var(--blog-code-block-color);
+    background: none;
+    text-shadow: none;
+    font-family: var(--blog-code-block-fontFamily);
+    font-size: var(--blog-code-block-fontSize);
+    font-weight: var(--blog-code-block-fontWeight);
+    line-height: var(--blog-code-block-lineHeight);
+    text-align: left;
+    white-space: pre;
+    word-spacing: normal;
+    word-break: normal;
+    tab-size: 4;
+    hyphens: none;
+  }
+
+  pre[class*='language-'] {
+    margin: 0;
+    padding: var(--blog-code-block-padding);
+    overflow: auto;
+    border-radius: var(--blog-code-block-borderRadius);
+    background: var(--blog-code-block-background);
+  }
+
+  code[class*='language-'] ::selection,
+  pre[class*='language-'] ::selection {
+    background: var(--blog-code-block-selection-background);
+  }
+
+  :is(.token.comment, .token.prolog, .token.doctype, .token.cdata, .token.punctuation,
+    .token.namespace, .token.property, .token.tag, .token.boolean, .token.number,
+    .token.constant, .token.symbol, .token.deleted, .token.selector, .token.attr-name,
+    .token.string, .token.char, .token.builtin, .token.inserted, .token.operator,
+    .token.entity, .token.url, .token.atrule, .token.attr-value, .token.keyword,
+    .token.class-name, .token.function, .token.variable, .token.regex,
+    .token.important) {
+    color: var(--blog-code-block-color);
+  }
+
+  .token.entity {
+    cursor: help;
+  }
+
+  .token.bold,
+  .token.important {
+    font-weight: var(--typography-fontWeight-bold);
+  }
+
+  .token.italic {
+    font-style: italic;
+  }
+
+  .token.entity,
+  .token.operator,
+  .token.url,
+  .language-css .token.string,
+  .style .token.string {
+    background: none;
+  }
+`;