adp-web-components 0.3.18 → 0.3.20

package/dist/collection/templates/highlight.js

@@ -0,0 +1,194 @@
+/**
+ * adp-web-components — the showcase syntax highlighter.
+ *
+ * A highlighter in about fifty lines of rules, because the alternative is a CDN
+ * script tag and §3 of the design language exists to keep those off these pages.
+ *
+ * One pass per snippet: a single alternation walks the string, so a token
+ * already emitted is never re-scanned. Sequential .replace() calls would match
+ * `class="tok-key"` inside their own output. Every pattern uses NON-CAPTURING
+ * groups only — the group index IS the rule index, which is how a match is
+ * traced back to the rule that produced it.
+ *
+ * Five token classes exist and no more. They are styled in
+ * `templates/harness.src.css`, which is COMPILED into the gitignored
+ * harness.css, so a sixth class here would render as plain body text and a
+ * renamed one would silently lose its colour:
+ *
+ *   tok-key      magenta   keywords, selectors, at-rules, literals
+ *   tok-str      green     strings and literal values
+ *   tok-attr     blue      names you address — attributes, JSON keys, CSS
+ *                          properties, shadow parts
+ *   tok-comment  grey      comments
+ *   tok-punct    grey      structural punctuation
+ *
+ * Kept deliberately dumb. None of these grammars is a parser: they carry no
+ * state, so they cannot know whether they are inside a rule block or a selector
+ * list, and each is tuned for the shape the showcase actually prints —
+ * hand-written, one declaration per line. Minified input degrades; it does not
+ * break.
+ *
+ * Usage:
+ *
+ *   import { highlight } from '../highlight.js';
+ *
+ *   element.innerHTML = highlight(source, 'css');
+ */
+
+export const GRAMMARS = {
+  HTML: [
+    { token: 'comment', pattern: '<!--[\\s\\S]*?-->' },
+    { token: 'str', pattern: '"[^"]*"' },
+    { token: 'key', pattern: '</?[a-zA-Z][\\w-]*' },
+    { token: 'attr', pattern: '[a-zA-Z-]+(?==)' },
+    { token: 'punct', pattern: '/?>' },
+  ],
+  JavaScript: [
+    { token: 'comment', pattern: '//[^\\n]*' },
+    { token: 'str', pattern: "'[^']*'" },
+    { token: 'key', pattern: '\\b(?:import|from|await|const|let|new|return|try|catch|document)\\b' },
+    { token: 'attr', pattern: '\\b[a-zA-Z_$][\\w$]*(?=\\s*:)' },
+    { token: 'punct', pattern: '[{}();,]' },
+  ],
+  Shell: [
+    { token: 'comment', pattern: '#[^\\n]*' },
+    { token: 'key', pattern: '^\\S+' },
+  ],
+
+  /*
+   * JSON. A key is a string sitting in front of a colon, and that is the one
+   * distinction worth drawing: a structure file is read by its keys, and
+   * painting them the same green as every value turns it into a wall.
+   */
+  JSON: [
+    { token: 'attr', pattern: '"(?:\\\\.|[^"\\\\])*"(?=\\s*:)' },
+    { token: 'str', pattern: '"(?:\\\\.|[^"\\\\])*"' },
+    { token: 'key', pattern: '\\b(?:true|false|null)\\b' },
+    { token: 'key', pattern: '-?\\b\\d+(?:\\.\\d+)?(?:[eE][+-]?\\d+)?\\b' },
+    { token: 'punct', pattern: '[{}\\[\\],:]' },
+  ],
+
+  /*
+   * CSS, where the ordering IS the grammar.
+   *
+   *   `::part(name)` is first among the selector rules because it is the thing a
+   *   theme file is FOR. It takes the blue "name you address" colour so it reads
+   *   apart from the magenta selector it hangs off.
+   *
+   *   A property is told from a pseudo-class with no state at all, by what
+   *   follows the colon: `color: red;` reaches a `;` or a `}` with no brace in
+   *   between, while `a:hover {` hits the `{` first. That rule is anchored to
+   *   the start of a line (the scanner runs with `m`) and swallows the colon, so
+   *   `color:red` cannot leave a bare `:red` behind for the pseudo-class rule to
+   *   claim. The leading indentation rides along inside the span, which is
+   *   invisible — colour only reaches glyphs.
+   *
+   *   The hex rule outranks the id-selector rule because `#fff` is a colour far
+   *   more often than it is an id. `#abc` is genuinely ambiguous and goes to the
+   *   colour; both are coloured, just not the same.
+   */
+  CSS: [
+    { token: 'comment', pattern: '/\\*[\\s\\S]*?\\*/' },
+    { token: 'str', pattern: '"[^"]*"|\'[^\']*\'' },
+    { token: 'key', pattern: '@[a-zA-Z-]+' },
+    { token: 'attr', pattern: '::part\\([^()]*\\)' },
+    { token: 'key', pattern: '::?[a-zA-Z][a-zA-Z-]*(?:\\((?:[^()]|\\([^()]*\\))*\\))?' },
+    { token: 'key', pattern: '!\\s*important\\b' },
+    { token: 'attr', pattern: '^[ \\t]*[a-zA-Z-][a-zA-Z0-9-]*\\s*:(?=[^;{}]*[;}])' },
+    { token: 'key', pattern: '^[ \\t]*[a-zA-Z][a-zA-Z0-9-]*(?=[^;{}]*\\{)' },
+    { token: 'str', pattern: '#[0-9a-fA-F]{3,8}\\b' },
+    { token: 'key', pattern: '[.#][a-zA-Z_-][a-zA-Z0-9_-]*' },
+    { token: 'key', pattern: '\\[[^\\]]*\\]' },
+    { token: 'str', pattern: '\\b\\d+(?:\\.\\d+)?[a-zA-Z%]*' },
+    { token: 'punct', pattern: '[{}();,:]' },
+  ],
+};
+
+/**
+ * The spellings a caller is likely to have to hand — a file extension, a `lang`
+ * attribute, a lower-cased label. The canonical keys above stay display-cased
+ * because they are also what the landing page prints above a snippet.
+ */
+const ALIASES = Object.assign(Object.create(null), {
+  html: 'HTML',
+  javascript: 'JavaScript',
+  js: 'JavaScript',
+  shell: 'Shell',
+  sh: 'Shell',
+  bash: 'Shell',
+  json: 'JSON',
+  css: 'CSS',
+});
+
+/*
+ * One compiled scanner per grammar. Keyed by the rules array rather than by name
+ * so an alias cannot compile a second copy, and weak so a caller passing its own
+ * grammar array does not pin it here forever.
+ */
+const scanners = new WeakMap();
+
+export function escapeHtml(text) {
+  return String(text).replace(/[&<>]/g, character => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;' })[character]);
+}
+
+/**
+ * Marks a snippet up for the `.code` block styling.
+ *
+ * @param {string} code the snippet, as written
+ * @param {string} lang a grammar name or alias. Anything unrecognised comes back
+ *                      escaped and unmarked, which is the right answer for a
+ *                      language nothing here understands.
+ * @returns {string} HTML — escaped text with `<span class="tok-…">` around every
+ *                   recognised token.
+ */
+export function highlight(code, lang) {
+  const rules = grammarFor(lang);
+
+  if (!rules) return escapeHtml(code);
+
+  const scanner = scannerFor(rules);
+
+  let output = '';
+  let index = 0;
+  let match;
+
+  // The scanner is shared and carries lastIndex between calls; nothing here is
+  // re-entrant, so rewinding once at the top is enough.
+  scanner.lastIndex = 0;
+
+  while ((match = scanner.exec(code)) !== null) {
+    // A zero-length match would loop forever; nothing here can produce one, but
+    // the guard costs a line and the failure is a hung tab.
+    if (match[0] === '') break;
+
+    const rule = rules[match.slice(1).findIndex(group => group !== undefined)];
+
+    output += escapeHtml(code.slice(index, match.index));
+    output += '<span class="tok-' + rule.token + '">' + escapeHtml(match[0]) + '</span>';
+    index = match.index + match[0].length;
+  }
+
+  return output + escapeHtml(code.slice(index));
+}
+
+/** Own properties only — `GRAMMARS['constructor']` is not a grammar. */
+function grammarFor(lang) {
+  const name = String(lang ?? '');
+
+  if (Object.prototype.hasOwnProperty.call(GRAMMARS, name)) return GRAMMARS[name];
+
+  const canonical = ALIASES[name.toLowerCase()];
+
+  return canonical ? GRAMMARS[canonical] : null;
+}
+
+function scannerFor(rules) {
+  let scanner = scanners.get(rules);
+
+  if (!scanner) {
+    scanner = new RegExp(rules.map(rule => '(' + rule.pattern + ')').join('|'), 'gm');
+    scanners.set(rules, scanner);
+  }
+
+  return scanner;
+}

package/dist/collection/templates/nav.js

@@ -0,0 +1,320 @@
+/**
+ * Navigation for the frozen prototypes.
+ *
+ * They predate the harness, and §8 says they are records rather than pages
+ * waiting to be restyled — so they cannot link `harness.css`. Tailwind's
+ * preflight alone would rewrite every one of them, which is precisely the record
+ * being destroyed.
+ *
+ * So this is a shadow-DOM custom element with its own styles: nothing leaks in,
+ * nothing leaks out, and it is `position: fixed`, so it contributes no layout and
+ * the page underneath renders exactly as it did before. A prototype adopts it
+ * with one line and no other change:
+ *
+ *   <script type="module" src="/templates/nav.js"></script>
+ *
+ * Harness pages do not use this — they get the integrated sticky bar from
+ * harness.js. Both read the same `catalog.json`, so neither can go stale.
+ *
+ * See .shift/repos/adp/web-components/templates-design-language.md §8.
+ */
+
+/*
+ * Paths come out of the catalog root-absolute (`/templates/…`), which only
+ * resolves when the site is the server root. This element ships on the frozen
+ * prototypes, which sit one directory down, and the built site can be mounted
+ * anywhere — so every path is re-resolved against the directory this module was
+ * loaded from instead. `harness.js` carries the same two lines for the same
+ * reason; they cannot be shared without giving the prototypes a second module.
+ */
+const SITE_ROOT = new URL('../', import.meta.url);
+
+/** A catalog path as a URL path valid from wherever this page sits. */
+const site = value => new URL(String(value).replace(/^\//, ''), SITE_ROOT).pathname;
+
+const STYLES = /* css */ `
+  :host {
+    /* The harness tokens, hardcoded: this file cannot import the stylesheet that
+       defines them without dragging Tailwind in with it. */
+    --surface: #ffffff;
+    --ground: #eef1f5;
+    --line: #dde4ec;
+    --ink: #121922;
+    --muted: #7b8794;
+    --accent: #7a5d08;
+    --gold: #f9cb4b;
+    --on-gold: #2a2000;
+
+    position: fixed;
+    z-index: 2147483000;
+    bottom: 1rem;
+    left: 1rem;
+    font-family: ui-sans-serif, system-ui, -apple-system, 'Segoe UI', Roboto, sans-serif;
+    font-size: 13px;
+    line-height: 1.4;
+  }
+
+  @media (prefers-color-scheme: dark) {
+    :host {
+      --surface: #151b23;
+      --ground: #0c1016;
+      --line: #262f3a;
+      --ink: #e8eef4;
+      --muted: #76838f;
+      --accent: #f9cb4b;
+    }
+  }
+
+  * {
+    box-sizing: border-box;
+  }
+
+  /* Dashed, mono, uppercase: a cropped screenshot must not read as prototype UI (R2). */
+  .launcher {
+    display: flex;
+    gap: 0.5rem;
+    align-items: center;
+    padding: 0.4rem 0.7rem;
+    color: var(--ink);
+    background: var(--surface);
+    border: 1px dashed var(--line);
+    border-radius: 999px;
+    box-shadow: 0 6px 20px rgb(18 25 34 / 18%);
+    cursor: pointer;
+    font: inherit;
+    font-family: ui-monospace, 'SFMono-Regular', Menlo, Consolas, monospace;
+    font-size: 11px;
+    letter-spacing: 0.08em;
+    text-transform: uppercase;
+    transition: border-color 150ms ease, color 150ms ease;
+  }
+
+  .launcher:hover {
+    color: var(--accent);
+    border-color: var(--accent);
+  }
+
+  .launcher svg {
+    display: block;
+    width: 13px;
+    height: 13px;
+    color: var(--accent);
+  }
+
+  .panel {
+    position: absolute;
+    bottom: calc(100% + 0.5rem);
+    left: 0;
+    width: min(22rem, calc(100vw - 2rem));
+    max-height: min(70vh, 34rem);
+    overflow-y: auto;
+    padding: 0.4rem;
+    color: var(--ink);
+    background: var(--surface);
+    border: 1px solid var(--line);
+    border-radius: 14px;
+    box-shadow: 0 18px 45px rgb(18 25 34 / 22%);
+    overscroll-behavior: contain;
+  }
+
+  [hidden] {
+    display: none !important;
+  }
+
+  .home {
+    display: flex;
+    gap: 0.5rem;
+    align-items: center;
+    margin-bottom: 0.25rem;
+    padding: 0.45rem 0.6rem;
+    color: var(--ink);
+    background: var(--ground);
+    border-radius: 9px;
+    font-weight: 600;
+    text-decoration: none;
+  }
+
+  .home:hover {
+    color: var(--accent);
+  }
+
+  details {
+    border-top: 1px solid var(--line);
+  }
+
+  details:first-of-type {
+    border-top: 0;
+  }
+
+  summary {
+    display: flex;
+    gap: 0.5rem;
+    align-items: center;
+    padding: 0.45rem 0.6rem;
+    color: var(--muted);
+    cursor: pointer;
+    font-family: ui-monospace, 'SFMono-Regular', Menlo, Consolas, monospace;
+    font-size: 11px;
+    letter-spacing: 0.08em;
+    text-transform: uppercase;
+    list-style: none;
+  }
+
+  summary::-webkit-details-marker {
+    display: none;
+  }
+
+  summary::before {
+    color: var(--muted);
+    content: '▸';
+    font-size: 9px;
+    transition: transform 150ms ease;
+  }
+
+  details[open] summary::before {
+    transform: rotate(90deg);
+  }
+
+  .count {
+    margin-inline-start: auto;
+    font-variant-numeric: tabular-nums;
+    opacity: 0.7;
+  }
+
+  a.page {
+    display: block;
+    padding: 0.4rem 0.6rem 0.4rem 1.5rem;
+    overflow: hidden;
+    color: var(--ink);
+    border-radius: 8px;
+    text-decoration: none;
+    text-overflow: ellipsis;
+    white-space: nowrap;
+  }
+
+  a.page:hover {
+    background: var(--ground);
+  }
+
+  a.page[aria-current='page'] {
+    color: var(--on-gold);
+    background: var(--gold);
+    font-weight: 600;
+  }
+
+  .empty {
+    padding: 0.6rem;
+    color: var(--muted);
+  }
+
+  :focus-visible {
+    outline: 2px solid var(--accent);
+    outline-offset: 2px;
+  }
+
+  @media (prefers-reduced-motion: reduce) {
+    * {
+      transition-duration: 0.01ms !important;
+    }
+  }
+`;
+
+const ICON = /* html */ `
+  <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2.5" stroke-linecap="round" aria-hidden="true">
+    <path d="M4 6h16M4 12h16M4 18h16" />
+  </svg>
+`;
+
+class HarnessNav extends HTMLElement {
+  #open = false;
+
+  connectedCallback() {
+    if (this.shadowRoot) return;
+
+    const root = this.attachShadow({ mode: 'open' });
+
+    root.innerHTML = /* html */ `
+      <style>${STYLES}</style>
+      <button class="launcher" type="button" aria-expanded="false" aria-controls="panel">${ICON} Pages</button>
+      <div class="panel" id="panel" hidden><p class="empty">Loading…</p></div>
+    `;
+
+    this.launcher = root.querySelector('.launcher');
+    this.panel = root.querySelector('.panel');
+
+    this.launcher.addEventListener('click', () => this.toggle(!this.#open));
+
+    // `composedPath` because a click inside the shadow root reports this host as
+    // its target from the outside.
+    this.onDocumentClick = event => {
+      if (this.#open && !event.composedPath().includes(this)) this.toggle(false);
+    };
+
+    this.onKeydown = event => {
+      if (event.key === 'Escape') this.toggle(false);
+    };
+
+    document.addEventListener('click', this.onDocumentClick);
+    document.addEventListener('keydown', this.onKeydown);
+
+    this.load();
+  }
+
+  disconnectedCallback() {
+    document.removeEventListener('click', this.onDocumentClick);
+    document.removeEventListener('keydown', this.onKeydown);
+  }
+
+  toggle(open) {
+    this.#open = open;
+    this.panel.hidden = !open;
+    this.launcher.setAttribute('aria-expanded', String(open));
+  }
+
+  async load() {
+    let catalog;
+
+    try {
+      const response = await fetch(new URL('catalog.json', import.meta.url));
+
+      if (!response.ok) throw new Error(String(response.status));
+
+      catalog = await response.json();
+    } catch {
+      this.panel.innerHTML = '<p class="empty">No catalog. Run <code>npm start</code>.</p>';
+      return;
+    }
+
+    const here = window.location.pathname;
+    const escape = value => String(value).replace(/[&<>"]/g, character => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;' })[character]);
+
+    const groups = catalog.areas.map(area => {
+      const pages = catalog.pages.filter(page => page.area === area.id);
+      const current = pages.some(page => site(page.path) === here);
+
+      const items = pages
+        .map(page => `<a class="page" href="${escape(site(page.path))}"${site(page.path) === here ? ' aria-current="page"' : ''}>${escape(page.title)}</a>`)
+        .join('');
+
+      return `
+        <details${current ? ' open' : ''}>
+          <summary>${escape(area.label)}<span class="count">${pages.length}</span></summary>
+          ${items}
+        </details>
+      `;
+    });
+
+    this.panel.innerHTML = `<a class="home" href="${escape(site('/'))}">← Showcase home</a>${groups.join('')}`;
+  }
+}
+
+customElements.define('harness-nav', HarnessNav);
+
+// Self-injecting, so a page adopts it with a script tag and nothing else. Guarded
+// because a page is free to place the element itself.
+if (!document.querySelector('harness-nav')) {
+  const mount = () => document.body.append(document.createElement('harness-nav'));
+
+  if (document.body) mount();
+  else document.addEventListener('DOMContentLoaded', mount);
+}