explico 0.1.0

package/src/components/examples/CompactExamples.astro

@@ -0,0 +1,253 @@
+---
+interface Props {
+  /** Text shown on the native disclosure while the examples are collapsed. */
+  summary?: string;
+  /** Optional one-line cue below the disclosure title. */
+  hint?: string;
+  /** Accessible name for the tab list created by progressive enhancement. */
+  tabsLabel?: string;
+}
+
+const {
+  summary = 'Worked examples',
+  hint = 'Open and choose an example.',
+  tabsLabel = summary,
+} = Astro.props;
+---
+
+<compact-examples data-tabs-label={tabsLabel}>
+  <details class="compact-examples">
+    <summary class="compact-examples__summary">
+      <span class="compact-examples__title">{summary}</span>
+      {hint && <span class="compact-examples__hint">{hint}</span>}
+    </summary>
+    <div class="compact-examples__body">
+      <slot />
+    </div>
+  </details>
+</compact-examples>
+
+<style>
+  compact-examples {
+    display: block;
+    margin-block: 1.5rem;
+  }
+
+  .compact-examples {
+    overflow: clip;
+    border: 1px solid var(--sl-color-gray-5);
+    border-radius: 0.75rem;
+    background: var(--sl-color-gray-7);
+  }
+
+  .compact-examples__summary {
+    padding: 0.8rem 1rem;
+    cursor: pointer;
+  }
+
+  .compact-examples__summary::marker {
+    color: var(--sl-color-text-accent);
+  }
+
+  .compact-examples__summary:focus-visible {
+    outline: 3px solid var(--sl-color-accent);
+    outline-offset: -3px;
+  }
+
+  .compact-examples__title {
+    font-weight: 700;
+  }
+
+  .compact-examples__hint {
+    display: block;
+    margin-block-start: 0.15rem;
+    color: var(--sl-color-gray-3);
+    font-size: var(--sl-text-sm);
+  }
+
+  .compact-examples__body {
+    padding: 0.25rem 1rem 1rem;
+    border-block-start: 1px solid var(--sl-color-gray-5);
+  }
+
+  :global(.compact-examples__tabs) {
+    display: flex;
+    gap: 0.25rem;
+    overflow-x: auto;
+    margin: 0 -1rem 1rem;
+    padding: 0.55rem 1rem 0;
+    border-block-end: 1px solid var(--sl-color-gray-5);
+  }
+
+  :global(.compact-examples__tab) {
+    flex: 0 0 auto;
+    padding: 0.45rem 0.7rem;
+    color: var(--sl-color-gray-3);
+    font: inherit;
+    font-size: var(--sl-text-sm);
+    font-weight: 600;
+    line-height: var(--sl-line-height-headings);
+    cursor: pointer;
+    border: 0;
+    border-block-end: 3px solid transparent;
+    background: transparent;
+  }
+
+  :global(.compact-examples__tab[aria-selected='true']) {
+    color: var(--sl-color-text-accent);
+    border-block-end-color: var(--sl-color-text-accent);
+  }
+
+  :global(.compact-examples__tab:focus-visible) {
+    outline: 3px solid var(--sl-color-accent);
+    outline-offset: -3px;
+  }
+
+  :global(.compact-example[role='tabpanel']) {
+    margin: 0;
+  }
+
+  @media print {
+    .compact-examples {
+      overflow: visible;
+      border: 0;
+      background: transparent;
+    }
+
+    .compact-examples__summary,
+    :global(.compact-examples__tabs) {
+      display: none;
+    }
+
+    .compact-examples__body {
+      display: block !important;
+      padding: 0;
+      border: 0;
+    }
+
+    :global(.compact-example[hidden]) {
+      display: block !important;
+    }
+
+    :global(.compact-example + .compact-example) {
+      margin-block-start: 1.5rem;
+    }
+
+    :global(.compact-example__heading[hidden]) {
+      display: block !important;
+    }
+  }
+</style>
+
+<script>
+  class CompactExamplesElement extends HTMLElement {
+    static nextId = 0;
+
+    connectedCallback() {
+      if (this.dataset.enhanced === 'true') return;
+
+      const details =
+        this.querySelector<HTMLDetailsElement>(':scope > details');
+      const body = details?.querySelector<HTMLElement>(
+        ':scope > .compact-examples__body',
+      );
+      if (!details || !body) return;
+
+      const panels = Array.from(
+        body.querySelectorAll<HTMLElement>(':scope > [data-compact-example]'),
+      );
+      if (panels.length < 2) return;
+
+      this.dataset.enhanced = 'true';
+      const instanceId = `compact-examples-${CompactExamplesElement.nextId++}`;
+      const tablist = document.createElement('div');
+      tablist.className = 'compact-examples__tabs';
+      tablist.setAttribute('role', 'tablist');
+      tablist.setAttribute(
+        'aria-label',
+        this.dataset.tabsLabel || 'Worked examples',
+      );
+
+      const tabs = panels.map((panel, index) => {
+        const label = panel.dataset.exampleLabel || `Example ${index + 1}`;
+        const panelId = panel.id || `${instanceId}-panel-${index + 1}`;
+        const tabId = `${instanceId}-tab-${index + 1}`;
+        panel.id = panelId;
+        panel.setAttribute('role', 'tabpanel');
+        panel.setAttribute('aria-labelledby', tabId);
+
+        const heading = panel.querySelector<HTMLElement>(
+          ':scope > .compact-example__heading',
+        );
+        if (heading) heading.hidden = true;
+
+        const tab = document.createElement('button');
+        tab.type = 'button';
+        tab.className = 'compact-examples__tab';
+        tab.id = tabId;
+        tab.textContent = label;
+        tab.setAttribute('role', 'tab');
+        tab.setAttribute('aria-controls', panelId);
+        tablist.append(tab);
+        return tab;
+      });
+
+      const activate = (activeIndex: number, moveFocus = false) => {
+        tabs.forEach((tab, index) => {
+          const selected = index === activeIndex;
+          tab.setAttribute('aria-selected', String(selected));
+          tab.tabIndex = selected ? 0 : -1;
+          panels[index].hidden = !selected;
+        });
+        if (moveFocus) tabs[activeIndex].focus();
+      };
+
+      tabs.forEach((tab, index) => {
+        tab.addEventListener('click', () => activate(index));
+        tab.addEventListener('keydown', (event) => {
+          let nextIndex: number | undefined;
+          if (event.key === 'ArrowLeft') {
+            nextIndex = (index - 1 + tabs.length) % tabs.length;
+          } else if (event.key === 'ArrowRight') {
+            nextIndex = (index + 1) % tabs.length;
+          } else if (event.key === 'Home') {
+            nextIndex = 0;
+          } else if (event.key === 'End') {
+            nextIndex = tabs.length - 1;
+          }
+
+          if (nextIndex === undefined) return;
+          event.preventDefault();
+          activate(nextIndex, true);
+        });
+      });
+
+      body.prepend(tablist);
+      activate(0);
+
+      let openBeforePrint: boolean | undefined;
+      const enterPrintMode = () => {
+        if (openBeforePrint !== undefined) return;
+        openBeforePrint = details.open;
+        details.open = true;
+      };
+      const leavePrintMode = () => {
+        if (openBeforePrint === undefined) return;
+        details.open = openBeforePrint;
+        openBeforePrint = undefined;
+      };
+      const printMedia = window.matchMedia('print');
+      printMedia.addEventListener('change', (event) => {
+        if (event.matches) enterPrintMode();
+        else leavePrintMode();
+      });
+      window.addEventListener('beforeprint', enterPrintMode);
+      window.addEventListener('afterprint', leavePrintMode);
+      if (printMedia.matches) enterPrintMode();
+    }
+  }
+
+  if (!customElements.get('compact-examples')) {
+    customElements.define('compact-examples', CompactExamplesElement);
+  }
+</script>

package/src/components/hover-panel.ts

@@ -0,0 +1,273 @@
+/**
+ * Interaction engine for the shared hover/pin panel (see `HoverPanel.astro`).
+ *
+ * One copy of the positioning, pin, Escape, outside-close, and
+ * article-column-clamp logic that the notation layer and the citation layer
+ * both need. Each layer supplies the domain-specific seams — how to find a
+ * trigger, how to key it, how to fill the panel — and keeps its own markup.
+ *
+ * The panel is `position: fixed`. Placement clears the whole display equation
+ * a marker sits inside (never just the glyph), decides the side against the
+ * space left by the sticky site header, and keeps the box within the article
+ * column so it never lands under a navigation rail.
+ */
+
+export interface HoverPanelState {
+  activeKey: string | null;
+  pinnedKey: string | null;
+  visible: boolean;
+}
+
+export interface HoverPanelConfig {
+  /** The `<aside data-hover-panel>` element. */
+  panel: HTMLElement;
+  /**
+   * Element used only to locate the enclosing article column for the
+   * horizontal clamp. Defaults to the panel itself.
+   */
+  root?: HTMLElement;
+  /** Interactive element (marker, list row, control) for an event target. */
+  triggerFrom: (node: EventTarget | null) => HTMLElement | null;
+  /** Stable key identifying the content a trigger points at. */
+  keyFor: (trigger: HTMLElement) => string | null;
+  /**
+   * Fill the panel for `trigger`/`key`. Return `false` to abort the open
+   * (unknown key); the panel stays hidden.
+   */
+  render: (trigger: HTMLElement, key: string) => boolean | void;
+  /** A pin toggle for an event target (a list button, an in-panel button). */
+  pinControlFrom?: (node: EventTarget | null) => HTMLElement | null;
+  /** Called after the panel is shown for `key`. */
+  onShow?: (key: string, trigger: HTMLElement) => void;
+  /** Called after the panel is hidden. */
+  onClose?: () => void;
+  /** Called after every open, close, or pin change. */
+  onSync?: (state: HoverPanelState) => void;
+}
+
+function closestElement(node: EventTarget | null, selector: string) {
+  return node instanceof Element ? node.closest<HTMLElement>(selector) : null;
+}
+
+export function createHoverPanel(config: HoverPanelConfig) {
+  const { panel } = config;
+  if (panel.dataset.hoverPanelReady === 'true') return;
+  panel.dataset.hoverPanelReady = 'true';
+
+  const anchorRoot = config.root ?? panel;
+
+  let activeKey: string | null = null;
+  let activeAnchor: HTMLElement | null = null;
+  let pinned: { key: string; anchor: HTMLElement } | null = null;
+
+  const sync = () => {
+    config.onSync?.({
+      activeKey,
+      pinnedKey: pinned?.key ?? null,
+      visible: panel.hidden === false,
+    });
+  };
+
+  const pinControlFrom = (node: EventTarget | null) =>
+    config.pinControlFrom?.(node) ?? null;
+
+  const interactiveFrom = (node: EventTarget | null) =>
+    pinControlFrom(node) ?? config.triggerFrom(node);
+
+  const position = () => {
+    if (panel.hidden || !activeAnchor) return;
+
+    const edge = 12;
+    const gap = 10;
+    const displayEquation = activeAnchor.closest<HTMLElement>('.katex-display');
+    const safeRegion = displayEquation ?? activeAnchor;
+    const regionRect = safeRegion.getBoundingClientRect();
+    const anchorRect = activeAnchor.getBoundingClientRect();
+
+    // The usable band is bounded by the sticky header, not the raw viewport
+    // edge. Decide the side against that real space so a clamp against the
+    // header can never push the panel back down over the equation.
+    const headerBottom =
+      document.querySelector<HTMLElement>('.header')?.getBoundingClientRect()
+        .bottom ?? 0;
+    const verticalStart = Math.max(edge, headerBottom + edge);
+    const verticalEnd = window.innerHeight - edge;
+    const spaceAbove = regionRect.top - gap - verticalStart;
+    const spaceBelow = verticalEnd - regionRect.bottom - gap;
+
+    // Measure the panel in the roomier band, then keep it on whichever side
+    // actually clears the safe region; shrink only when neither side fits.
+    panel.style.maxHeight = `${Math.max(spaceAbove, spaceBelow, 0)}px`;
+    let panelRect = panel.getBoundingClientRect();
+    const placeBelow =
+      spaceBelow >= panelRect.height || spaceBelow >= spaceAbove;
+    panel.style.maxHeight = `${Math.max(placeBelow ? spaceBelow : spaceAbove, 0)}px`;
+    panelRect = panel.getBoundingClientRect();
+
+    let top = placeBelow
+      ? regionRect.bottom + gap
+      : regionRect.top - gap - panelRect.height;
+    let left = anchorRect.left + anchorRect.width / 2 - panelRect.width / 2;
+
+    const article =
+      anchorRoot
+        .closest<HTMLElement>('.main-pane')
+        ?.querySelector<HTMLElement>('.sl-markdown-content') ??
+      document.querySelector<HTMLElement>('.sl-markdown-content');
+    const articleRect = article?.getBoundingClientRect();
+    const horizontalStart = Math.max(edge, articleRect?.left ?? edge);
+    const horizontalEnd = Math.min(
+      window.innerWidth - edge,
+      articleRect?.right ?? window.innerWidth - edge,
+    );
+
+    top = Math.max(
+      verticalStart,
+      Math.min(top, verticalEnd - panelRect.height),
+    );
+    left =
+      horizontalEnd - horizontalStart >= panelRect.width
+        ? Math.max(
+            horizontalStart,
+            Math.min(left, horizontalEnd - panelRect.width),
+          )
+        : Math.max(
+            edge,
+            Math.min(left, window.innerWidth - panelRect.width - edge),
+          );
+
+    panel.style.top = `${Math.round(top)}px`;
+    panel.style.left = `${Math.round(left)}px`;
+  };
+
+  const show = (anchor: HTMLElement) => {
+    const key = config.keyFor(anchor);
+    if (!key) return;
+    if (config.render(anchor, key) === false) return;
+
+    activeKey = key;
+    activeAnchor = anchor;
+    config.onShow?.(key, anchor);
+
+    panel.style.visibility = 'hidden';
+    panel.hidden = false;
+    position();
+    panel.style.visibility = 'visible';
+    sync();
+  };
+
+  const close = () => {
+    activeKey = null;
+    activeAnchor = null;
+    panel.hidden = true;
+    config.onClose?.();
+    sync();
+  };
+
+  const restorePinnedOrClose = () => {
+    window.requestAnimationFrame(() => {
+      const focused = config.triggerFrom(document.activeElement);
+      if (focused && config.keyFor(focused) === activeKey) return;
+      if (pinned) {
+        show(pinned.anchor);
+        return;
+      }
+      if (
+        activeAnchor?.matches(':hover') ||
+        panel.matches(':hover') ||
+        panel.contains(document.activeElement)
+      ) {
+        return;
+      }
+      close();
+    });
+  };
+
+  const togglePin = (key: string, anchor: HTMLElement) => {
+    if (pinned?.key === key && pinned.anchor === anchor) {
+      pinned = null;
+      close();
+      return;
+    }
+    pinned = { key, anchor };
+    show(anchor);
+  };
+
+  document.addEventListener('pointerover', (event) => {
+    if (event.pointerType === 'touch' || pinned) return;
+    const anchor = config.triggerFrom(event.target);
+    const key = anchor ? config.keyFor(anchor) : null;
+    if (anchor && key && anchor !== config.triggerFrom(event.relatedTarget)) {
+      show(anchor);
+    }
+  });
+
+  document.addEventListener('pointerout', (event) => {
+    if (event.pointerType === 'touch') return;
+    const anchor = config.triggerFrom(event.target);
+    if (!anchor || anchor === config.triggerFrom(event.relatedTarget)) return;
+    if (
+      event.relatedTarget instanceof Node &&
+      panel.contains(event.relatedTarget)
+    ) {
+      return;
+    }
+    restorePinnedOrClose();
+  });
+
+  document.addEventListener('focusin', (event) => {
+    const anchor = config.triggerFrom(event.target);
+    const key = anchor ? config.keyFor(anchor) : null;
+    if (anchor && key) show(anchor);
+  });
+  document.addEventListener('focusout', restorePinnedOrClose);
+
+  document.addEventListener('click', (event) => {
+    const control = pinControlFrom(event.target);
+    if (control) {
+      const ownKey = config.keyFor(control);
+      if (ownKey) {
+        togglePin(ownKey, control);
+      } else if (activeKey && activeAnchor) {
+        togglePin(activeKey, activeAnchor);
+      }
+      return;
+    }
+
+    const trigger = config.triggerFrom(event.target);
+    if (!trigger || trigger.closest('a')) return;
+    const key = config.keyFor(trigger);
+    if (!key) return;
+    event.preventDefault();
+    togglePin(key, trigger);
+  });
+
+  document.addEventListener('pointerdown', (event) => {
+    if (!pinned) return;
+    if (
+      interactiveFrom(event.target) ||
+      (event.target instanceof Node && panel.contains(event.target))
+    ) {
+      return;
+    }
+    pinned = null;
+    close();
+  });
+
+  document.addEventListener('keydown', (event) => {
+    if (event.key !== 'Escape' || (!activeKey && !pinned)) return;
+    pinned = null;
+    close();
+  });
+
+  panel.addEventListener('pointerleave', restorePinnedOrClose);
+  window.addEventListener('resize', position, { passive: true });
+  window.addEventListener('scroll', position, {
+    passive: true,
+    capture: true,
+  });
+
+  sync();
+}
+
+export { closestElement };