@astro-minimax/core 0.1.0

package/src/plugins/shiki-transformers.ts

@@ -0,0 +1,212 @@
+interface HastElement {
+  type: "element";
+  tagName: string;
+  properties: Record<string, unknown>;
+  children: (HastElement | HastText)[];
+}
+
+interface HastText {
+  type: "text";
+  value: string;
+}
+
+interface ShikiTransformerContext {
+  options: {
+    lang: string;
+    meta?: { __raw?: string; [key: string]: unknown };
+  };
+  source: string;
+  lines: unknown[];
+  addClassToHast?: (node: HastElement, cls: string) => void;
+}
+
+interface ShikiTransformer {
+  name: string;
+  pre?: (this: ShikiTransformerContext, node: HastElement) => void;
+}
+
+function el(
+  tag: string,
+  props: Record<string, unknown>,
+  children: (HastElement | HastText)[] | string = []
+): HastElement {
+  return {
+    type: "element",
+    tagName: tag,
+    properties: props,
+    children:
+      typeof children === "string"
+        ? [{ type: "text" as const, value: children }]
+        : children,
+  };
+}
+
+function parseMetaString(str = ""): Record<string, string | true> {
+  return Object.fromEntries(
+    str.split(" ").reduce(
+      (acc: [string, string | true][], cur) => {
+        const matched = cur.match(/(.+)?=("(.+)"|'(.+)')$/);
+        if (matched === null) return acc;
+        const key = matched[1];
+        const value = matched[3] || matched[4] || true;
+        acc.push([key, value]);
+        return acc;
+      },
+      [] as [string, string | true][]
+    )
+  );
+}
+
+/**
+ * Wraps the default `<pre>` in a `<div>` container for richer layout
+ * (title bar, language label, copy button, collapse toggle).
+ */
+export const updateStyle = (): ShikiTransformer => ({
+  name: "shiki-transformer-update-style",
+  pre(node) {
+    const container: HastElement = {
+      type: "element",
+      tagName: "pre",
+      properties: {},
+      children: node.children,
+    };
+    node.children = [container];
+    node.tagName = "div";
+  },
+});
+
+/**
+ * Parses `title="..."` or `file="..."` from the code-fence meta string
+ * and prepends a styled title bar to the code block.
+ */
+export const addTitle = (): ShikiTransformer => ({
+  name: "shiki-transformer-add-title",
+  pre(node) {
+    const rawMeta = this.options.meta?.__raw;
+    if (!rawMeta) return;
+    const meta = parseMetaString(rawMeta);
+    const label = meta.title || meta.file;
+    if (!label) return;
+
+    node.children.unshift(
+      el("div", { class: "code-title" }, label.toString())
+    );
+  },
+});
+
+/**
+ * Appends a language label (e.g. `ts`, `css`) to the top-right of the block.
+ */
+export const addLanguage = (): ShikiTransformer => ({
+  name: "shiki-transformer-add-language",
+  pre(node) {
+    node.children.push(el("span", { class: "code-language" }, this.options.lang));
+  },
+});
+
+const clipboardSvg: HastElement = el(
+  "svg",
+  {
+    width: "16",
+    height: "16",
+    viewBox: "0 0 24 24",
+    fill: "none",
+    stroke: "currentColor",
+    "stroke-width": "2",
+    "stroke-linecap": "round",
+    "stroke-linejoin": "round",
+  },
+  [
+    el("rect", {
+      x: "9",
+      y: "9",
+      width: "13",
+      height: "13",
+      rx: "2",
+      ry: "2",
+    }),
+    el("path", {
+      d: "M5 15H4a2 2 0 0 1-2-2V4a2 2 0 0 1 2-2h9a2 2 0 0 1 2 2v1",
+    }),
+  ]
+);
+
+const checkSvg: HastElement = el(
+  "svg",
+  {
+    width: "16",
+    height: "16",
+    viewBox: "0 0 24 24",
+    fill: "none",
+    stroke: "currentColor",
+    "stroke-width": "2",
+    "stroke-linecap": "round",
+    "stroke-linejoin": "round",
+  },
+  [el("polyline", { points: "20 6 9 17 4 12" })]
+);
+
+/**
+ * Injects a copy-to-clipboard button at build time.
+ */
+export const addCopyButton = (timeout = 2000): ShikiTransformer => ({
+  name: "shiki-transformer-copy-button",
+  pre(node) {
+    node.children.push(
+      el(
+        "button",
+        {
+          class: "code-copy",
+          "aria-label": "Copy code",
+          "data-code": this.source,
+          onclick: `navigator.clipboard.writeText(this.dataset.code);this.classList.add('copied');setTimeout(()=>this.classList.remove('copied'),${timeout})`,
+        },
+        [
+          el("span", { class: "ready" }, [clipboardSvg]),
+          el("span", { class: "success" }, [checkSvg]),
+        ]
+      )
+    );
+  },
+});
+
+const chevronSvg: HastElement = el(
+  "svg",
+  {
+    width: "16",
+    height: "16",
+    viewBox: "0 0 24 24",
+    fill: "none",
+    stroke: "currentColor",
+    "stroke-width": "2",
+    "stroke-linecap": "round",
+    "stroke-linejoin": "round",
+  },
+  [el("polyline", { points: "6 9 12 15 18 9" })]
+);
+
+/**
+ * Collapses code blocks that exceed `maxLines` lines.
+ */
+export const addCollapse = (maxLines = 15): ShikiTransformer => ({
+  name: "shiki-transformer-add-collapse",
+  pre(node) {
+    if (this.lines.length <= maxLines) return;
+    node.properties = {
+      ...node.properties,
+      class: `${(node.properties?.class as string) || ""} collapsed`,
+    };
+    node.children.push(
+      el(
+        "button",
+        {
+          class: "code-collapse-toggle",
+          "aria-label": "Toggle collapse code block",
+          onclick: "this.parentElement.classList.toggle('collapsed')",
+        },
+        [chevronSvg, el("span", {}, " Expand")]
+      )
+    );
+    node.children.push(el("div", { class: "code-collapse-fade" }));
+  },
+});

package/src/scripts/lightbox.ts

@@ -0,0 +1,63 @@
+function initLightbox() {
+  const article = document.getElementById("article");
+  if (!article) return;
+
+  let overlay: HTMLDivElement | null = null;
+
+  function createOverlay() {
+    if (overlay) return overlay;
+    overlay = document.createElement("div");
+    overlay.id = "lightbox-overlay";
+    overlay.setAttribute("role", "dialog");
+    overlay.setAttribute("aria-modal", "true");
+    overlay.setAttribute("aria-label", "Image preview");
+    overlay.innerHTML = `
+      <button id="lightbox-close" aria-label="Close" class="lightbox-close">&times;</button>
+      <img id="lightbox-img" src="" alt="" />
+    `;
+    document.body.appendChild(overlay);
+
+    overlay.addEventListener("click", e => {
+      if (
+        e.target === overlay ||
+        (e.target as HTMLElement).id === "lightbox-close"
+      ) {
+        close();
+      }
+    });
+
+    return overlay;
+  }
+
+  function open(src: string, alt: string) {
+    const el = createOverlay();
+    const img = el.querySelector("#lightbox-img") as HTMLImageElement;
+    img.src = src;
+    img.alt = alt;
+    el.classList.add("active");
+    document.body.style.overflow = "hidden";
+    document.addEventListener("keydown", onKey);
+  }
+
+  function close() {
+    if (!overlay) return;
+    overlay.classList.remove("active");
+    document.body.style.overflow = "";
+    document.removeEventListener("keydown", onKey);
+  }
+
+  function onKey(e: KeyboardEvent) {
+    if (e.key === "Escape") close();
+  }
+
+  const images = article.querySelectorAll("img");
+  images.forEach(img => {
+    if (img.closest("a")) return;
+    img.style.cursor = "zoom-in";
+    img.addEventListener("click", () => {
+      open(img.src, img.alt || "");
+    });
+  });
+}
+
+document.addEventListener("astro:page-load", initLightbox);

package/src/scripts/reading-position.ts

@@ -0,0 +1,56 @@
+const STORAGE_KEY = "reading-positions";
+const MAX_ENTRIES = 50;
+
+interface ReadingEntry {
+  scrollY: number;
+  ts: number;
+}
+
+function getPositions(): Record<string, ReadingEntry> {
+  try {
+    return JSON.parse(sessionStorage.getItem(STORAGE_KEY) || "{}");
+  } catch {
+    return {};
+  }
+}
+
+function savePosition(path: string, scrollY: number) {
+  const positions = getPositions();
+  positions[path] = { scrollY, ts: Date.now() };
+
+  const keys = Object.keys(positions);
+  if (keys.length > MAX_ENTRIES) {
+    const sorted = keys.sort((a, b) => positions[a].ts - positions[b].ts);
+    for (let i = 0; i < keys.length - MAX_ENTRIES; i++) {
+      delete positions[sorted[i]];
+    }
+  }
+
+  sessionStorage.setItem(STORAGE_KEY, JSON.stringify(positions));
+}
+
+function initReadingPosition() {
+  const article = document.getElementById("article");
+  if (!article) return;
+
+  const path = window.location.pathname;
+  const positions = getPositions();
+  const entry = positions[path];
+
+  if (entry && entry.scrollY > 100) {
+    requestAnimationFrame(() => {
+      window.scrollTo({ top: entry.scrollY, behavior: "instant" });
+    });
+  }
+
+  let rafId: number | null = null;
+  document.addEventListener("scroll", () => {
+    if (rafId) return;
+    rafId = requestAnimationFrame(() => {
+      savePosition(path, window.scrollY);
+      rafId = null;
+    });
+  });
+}
+
+document.addEventListener("astro:page-load", initReadingPosition);

package/src/scripts/theme-utils.ts

@@ -0,0 +1,19 @@
+export function getIsDark(): boolean {
+  return document.documentElement.getAttribute("data-theme") === "dark";
+}
+
+export function getCSSVar(name: string): string {
+  return getComputedStyle(document.documentElement)
+    .getPropertyValue(name)
+    .trim();
+}
+
+export function onThemeChange(
+  callback: (isDark: boolean) => void
+): () => void {
+  const handler = (e: CustomEvent<ThemeChangeDetail>) => {
+    callback(e.detail.isDark);
+  };
+  window.addEventListener("themechange", handler);
+  return () => window.removeEventListener("themechange", handler);
+}

package/src/scripts/theme.ts

@@ -0,0 +1,179 @@
+// Constants
+
+const THEME = "theme";
+const LIGHT = "light";
+const DARK = "dark";
+
+// Initial color scheme
+// Can be "light", "dark", or empty string for system's prefers-color-scheme
+const initialColorScheme = "";
+
+function getPreferTheme(): string {
+  // get theme data from local storage (user's explicit choice)
+  const currentTheme = localStorage.getItem(THEME);
+  if (currentTheme) return currentTheme;
+
+  // return initial color scheme if it is set (site default)
+  if (initialColorScheme) return initialColorScheme;
+
+  // return user device's prefer color scheme (system fallback)
+  return window.matchMedia("(prefers-color-scheme: dark)").matches
+    ? DARK
+    : LIGHT;
+}
+
+// Use existing theme value from inline script if available, otherwise detect
+let themeValue = window.theme?.themeValue ?? getPreferTheme();
+
+function setPreference(): void {
+  localStorage.setItem(THEME, themeValue);
+  reflectPreference();
+}
+
+function reflectPreference(): void {
+  document.firstElementChild?.setAttribute("data-theme", themeValue);
+
+  document.querySelector("#theme-btn")?.setAttribute("aria-label", themeValue);
+
+  const body = document.body;
+  if (body) {
+    const computedStyles = window.getComputedStyle(body);
+    const bgColor = computedStyles.backgroundColor;
+    document
+      .querySelector("meta[name='theme-color']")
+      ?.setAttribute("content", bgColor);
+  }
+
+  // Defer viz re-renders to avoid blocking the theme transition animation
+  requestAnimationFrame(() => {
+    window.dispatchEvent(
+      new CustomEvent("themechange", {
+        detail: { isDark: themeValue === DARK, theme: themeValue },
+      })
+    );
+  });
+}
+
+// Check if View Transitions API is supported
+function supportsViewTransitions(): boolean {
+  return "startViewTransition" in document;
+}
+
+// Toggle theme with optional View Transition animation
+function toggleThemeWithTransition(event?: MouseEvent): void {
+  const newTheme = themeValue === LIGHT ? DARK : LIGHT;
+
+  // Check for reduced motion preference
+  const prefersReducedMotion = window.matchMedia(
+    "(prefers-reduced-motion: reduce)"
+  ).matches;
+
+  // Get click position for circular animation
+  const x = event?.clientX ?? window.innerWidth / 2;
+  const y = event?.clientY ?? window.innerHeight / 2;
+
+  // Update theme value
+  themeValue = newTheme;
+  window.theme?.setTheme(themeValue);
+
+  // Skip animations if user prefers reduced motion
+  if (prefersReducedMotion) {
+    setPreference();
+    return;
+  }
+
+  // Check if View Transitions API is supported
+  if (supportsViewTransitions()) {
+    // Set CSS variables for animation origin
+    document.documentElement.style.setProperty("--theme-x", `${x}px`);
+    document.documentElement.style.setProperty("--theme-y", `${y}px`);
+
+    // Add transition class
+    const html = document.documentElement;
+    html.classList.add("theme-transition");
+
+    if (newTheme === DARK) {
+      html.classList.add("dark-transition");
+    } else {
+      html.classList.remove("dark-transition");
+    }
+
+    // Start View Transition with optimized timing
+    const transition = document.startViewTransition?.(() => {
+      setPreference();
+    });
+
+    // Clean up classes after animation completes
+    transition?.finished.then(() => {
+      html.classList.remove("theme-transition", "dark-transition");
+    });
+  } else {
+    // Fallback for browsers without View Transitions API
+    document.documentElement.classList.add("no-view-transitions");
+    setPreference();
+
+    // Remove class after transition completes (optimized timing)
+    setTimeout(() => {
+      document.documentElement.classList.remove("no-view-transitions");
+    }, 400);
+  }
+}
+
+// Update the global theme API
+if (window.theme) {
+  window.theme.setPreference = setPreference;
+  window.theme.reflectPreference = reflectPreference;
+} else {
+  window.theme = {
+    themeValue,
+    setPreference,
+    reflectPreference,
+    getTheme: () => themeValue,
+    setTheme: (val: string) => {
+      themeValue = val;
+    },
+  };
+}
+
+// Ensure theme is reflected (in case body wasn't ready when inline script ran)
+reflectPreference();
+
+function setThemeFeature(): void {
+  // set on load so screen readers can get the latest value on the button
+  reflectPreference();
+
+  // now this script can find and listen for clicks on the control
+  document.querySelector("#theme-btn")?.addEventListener("click", e => {
+    toggleThemeWithTransition(e as MouseEvent);
+  });
+}
+
+// Set up theme features after page load
+setThemeFeature();
+
+// Runs on view transitions navigation
+document.addEventListener("astro:after-swap", setThemeFeature);
+
+// Set theme-color value before page transition
+// to avoid navigation bar color flickering in Android dark mode
+document.addEventListener("astro:before-swap", event => {
+  const astroEvent = event;
+  const bgColor = document
+    .querySelector("meta[name='theme-color']")
+    ?.getAttribute("content");
+
+  if (bgColor) {
+    astroEvent.newDocument
+      .querySelector("meta[name='theme-color']")
+      ?.setAttribute("content", bgColor);
+  }
+});
+
+// sync with system changes
+window
+  .matchMedia("(prefers-color-scheme: dark)")
+  .addEventListener("change", ({ matches: isDark }) => {
+    themeValue = isDark ? DARK : LIGHT;
+    window.theme?.setTheme(themeValue);
+    setPreference();
+  });

package/src/scripts/web-vitals.ts

@@ -0,0 +1,96 @@
+type WebVitalMetric = {
+  name: string;
+  value: number;
+  rating: "good" | "needs-improvement" | "poor";
+  id: string;
+};
+
+function getRating(name: string, value: number): WebVitalMetric["rating"] {
+  const thresholds: Record<string, [number, number]> = {
+    CLS: [0.1, 0.25],
+    FID: [100, 300],
+    INP: [200, 500],
+    LCP: [2500, 4000],
+    FCP: [1800, 3000],
+    TTFB: [800, 1800],
+  };
+  const [good, poor] = thresholds[name] ?? [0, 0];
+  if (value <= good) return "good";
+  if (value <= poor) return "needs-improvement";
+  return "poor";
+}
+
+function reportMetric(metric: WebVitalMetric) {
+  if (import.meta.env.DEV) {
+    const color =
+      metric.rating === "good"
+        ? "#0cce6b"
+        : metric.rating === "needs-improvement"
+          ? "#ffa400"
+          : "#ff4e42";
+    // eslint-disable-next-line no-console
+    console.log(
+      `%c[Web Vitals] ${metric.name}: ${metric.value.toFixed(1)}ms (${metric.rating})`,
+      `color: ${color}; font-weight: bold;`
+    );
+  }
+}
+
+function observeWebVitals() {
+  if (typeof PerformanceObserver === "undefined") return;
+
+  const id = `v${Date.now()}-${Math.random().toString(36).slice(2, 7)}`;
+
+  try {
+    const lcpObserver = new PerformanceObserver(list => {
+      const entries = list.getEntries();
+      const last = entries[entries.length - 1];
+      if (last) {
+        reportMetric({
+          name: "LCP",
+          value: last.startTime,
+          rating: getRating("LCP", last.startTime),
+          id,
+        });
+      }
+    });
+    lcpObserver.observe({ type: "largest-contentful-paint", buffered: true });
+
+    const fcpObserver = new PerformanceObserver(list => {
+      for (const entry of list.getEntries()) {
+        if (entry.name === "first-contentful-paint") {
+          reportMetric({
+            name: "FCP",
+            value: entry.startTime,
+            rating: getRating("FCP", entry.startTime),
+            id,
+          });
+        }
+      }
+    });
+    fcpObserver.observe({ type: "paint", buffered: true });
+
+    const clsObserver = new PerformanceObserver(list => {
+      let clsValue = 0;
+      for (const entry of list.getEntries()) {
+        if (
+          !(entry as PerformanceEntry & { hadRecentInput?: boolean })
+            .hadRecentInput
+        ) {
+          clsValue += (entry as PerformanceEntry & { value: number }).value;
+        }
+      }
+      reportMetric({
+        name: "CLS",
+        value: clsValue,
+        rating: getRating("CLS", clsValue),
+        id,
+      });
+    });
+    clsObserver.observe({ type: "layout-shift", buffered: true });
+  } catch {
+    // PerformanceObserver types not supported in this browser
+  }
+}
+
+observeWebVitals();