@luigisbox/luma 0.0.0-stage → 0.2.0

package/parity/hints.mjs

@@ -0,0 +1,132 @@
+// Where to fix a template difference `yarn luma parity` found: the integration's
+// file, from our side's selector. A style (a computed property, a box, the
+// rendered font) is fixed in CSS: the integration's stylesheet with a rule
+// for that class or marker. Structure (a missing part, its text, the order)
+// is fixed in a template: the integration's `template-*.ts` that renders the
+// class or marker, else Luma's built-in template that does (copied into the
+// integration under the same name, it overrides it). Pure: the files are
+// passed in (run.mjs reads integration/), unit-tested.
+
+/** Luma's built-in templates by the marker they render (src/widgets/…), and the integration folder that overrides them. */
+export const BUILT_IN = Object.freeze({
+  tile: 'search/template-search-result-default.ts',
+  image: 'search/template-search-result-default.ts',
+  title: 'search/template-search-result-default.ts',
+  price: 'search/template-search-result-default.ts',
+  'old-price': 'search/template-search-result-default.ts',
+  badge: 'search/template-search-result-default.ts',
+  discount: 'search/template-search-result-default.ts',
+  list: 'search/template-search-results-default.ts',
+  count: 'search/template-search-header.ts',
+  sort: 'search/template-search-header.ts',
+  facets: 'search/template-search-facets-default.ts',
+  'facet-group': 'search/template-search-facets-default.ts',
+  'facet-title': 'search/template-search-facets-default.ts',
+  'facet-value': 'search/template-search-facets-default.ts',
+  chip: 'search/template-search-facets-default.ts',
+  pagination: 'search/template-search-pagination.ts',
+  more: 'search/template-search-pagination.ts',
+  empty: 'search/template-search-box.ts',
+  'ac-panel': 'autocomplete/template-autocomplete-box.ts',
+  'ac-section': 'autocomplete/template-autocomplete-box.ts',
+  'ac-title': 'autocomplete/template-autocomplete-box.ts',
+  'ac-all': 'autocomplete/template-autocomplete-box.ts',
+  'ac-empty': 'autocomplete/template-autocomplete-empty.ts',
+  'ac-row': 'autocomplete/template-autocomplete-result-default.ts',
+  'range-slider': 'search/template-search-range-default.ts',
+  'range-min': 'search/template-search-range-default.ts',
+  'range-max': 'search/template-search-range-default.ts',
+});
+
+/** Properties fixed in a template (markup), not in CSS. */
+const STRUCTURE = new Set(['presence', 'text', 'order', 'unpaired', 'controls']);
+
+/**
+ * What a selector's last compound names: its classes, its data-lbx-part
+ * markers, its other attributes, its tag.
+ * @param {string | null | undefined} sel
+ */
+export const namesOf = (sel) => {
+  const last = String(sel ?? '').trim().split(/\s*[\s>+~]\s*(?![^[]*\])/).filter(Boolean).pop() ?? '';
+  const classes = [...last.matchAll(/\.(-?[_a-zA-Z][\w-]*)/g)].map((m) => m[1]);
+  const markers = [...last.matchAll(/\[data-lbx-part[~*|^$]?=["']?([\w-]+)["']?\]/g)].map((m) => m[1]);
+  const attrs = [...last.matchAll(/\[([\w-]+)(?:[~*|^$]?=[^\]]*)?\]/g)].map((m) => m[1]).filter((a) => a !== 'data-lbx-part');
+  const tag = /^[a-z][\w-]*/i.exec(last)?.[0] ?? null;
+  return { last, classes, markers, attrs, tag };
+};
+
+const esc = (s) => s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+/** The folder a role's templates and styles live in. */
+const folderOf = (role) => (/^ac-/.test(role ?? '') ? 'autocomplete' : 'search');
+
+/**
+ * Where to fix one template difference (a `findings` entry), as a sentence:
+ * the file, the selector there, and what theirs has.
+ * @param {{ prop: string, group?: string, part: string, theirs: any, ours: any, selector?: { ours?: string | null, part?: { ours?: string | null } }, role?: string | null }} f
+ * @param {{ path: string, text: string }[]} files the integration's files (integration/…), and Luma's own templates (src/…: only to read the class of the element a marker names)
+ * @returns {{ file: string | null, kind: 'css' | 'template', hint: string }}
+ */
+export const hintFor = (f, files = []) => {
+  const sel = f.selector?.part?.ours ?? f.selector?.ours ?? null;
+  const n = namesOf(sel);
+  const role = f.role ?? f.selector?.role ?? n.markers[0] ?? null;
+  const kind = STRUCTURE.has(f.prop) ? 'template' : 'css';
+  const show = (v) => (typeof v === 'string' ? v : JSON.stringify(v));
+  const folder = folderOf(role);
+  // The widget's own folder first (a title marker is in the tile's template and in the autocomplete row's).
+  const mine = (x) => (x.path.startsWith(`integration/${folder}/`) ? 0 : 1);
+  const css = files.filter((x) => /\.css$/.test(x.path) && !x.path.startsWith('src/')).sort((a, b) => mine(a) - mine(b));
+  const ofLuma = files.filter((x) => x.path.startsWith('src/'));
+  const tpl = files.filter((x) => /(^|\/)template-[^/]*\.ts$/.test(x.path) && !x.path.startsWith('src/')).sort((a, b) => mine(a) - mine(b));
+  // A marker alone (ours named by data-lbx-part): the class the integration's template gives that element.
+  if (!n.classes.length && n.markers.length)
+    for (const x of [...tpl, ...ofLuma]) {
+      const tag = new RegExp(`<[a-z][^>]*data-lbx-part=["'][^"']*(?<![\\w-])${esc(n.markers[0])}(?![\\w-])[^>]*>`).exec(x.text)?.[0];
+      const cls = tag && /class=["']([^"'$]+)["']/.exec(tag)?.[1].trim().split(/\s+/)[0];
+      if (cls) {
+        n.classes.push(cls);
+        break;
+      }
+    }
+  const target = n.classes.length ? `.${n.classes[0]}` : n.markers.length ? `[data-lbx-part~="${n.markers[0]}"]` : (n.last || sel || '(our element)');
+  const inCss = (x) => n.classes.some((c) => new RegExp(`\\.${esc(c)}(?![\\w-])`).test(x.text)) || n.markers.some((m) => new RegExp(`data-lbx-part[~*]?=["']?${esc(m)}["']?`).test(x.text));
+  const inTpl = (x) => n.classes.some((c) => new RegExp(`class(Name)?=["'\`][^"'\`]*(?<![\\w-])${esc(c)}(?![\\w-])`).test(x.text)) || n.markers.some((m) => new RegExp(`data-lbx-part=["']?[^"']*(?<![\\w-])${esc(m)}(?![\\w-])`).test(x.text));
+  if (kind === 'css') {
+    const GRID = {
+      columns: 'grid-template-columns',
+      columnGap: 'column-gap',
+      rowGap: 'row-gap',
+      itemWidth: 'the items\' width',
+      'sibling-row-gap': 'the space between one and the next below it (a margin, a `+ *` rule, the parent\'s row-gap)',
+      'sibling-column-gap': 'the space between one and the next beside it (a margin, the parent\'s column-gap)',
+    };
+    if (f.prop === 'sibling-direction') GRID[f.prop] = 'stacked or side by side (the parent\'s display, flex-direction)';
+    const what =
+      f.prop === 'rendered-font' ? `the font theirs renders (${show(f.theirs)}): font-family, and the @font-face it needs`
+      : ['x', 'y', 'width', 'height'].includes(f.prop) ? `its ${f.prop} (theirs ${show(f.theirs)}px, ours ${show(f.ours)}px): the size, padding, margin or gap that sets it`
+      : f.prop === 'pixels' ? 'what the other differences leave (the crops in the HTML report)'
+      : GRID[f.prop] ? `${GRID[f.prop]}: theirs ${show(f.theirs)}${f.prop === 'columns' ? ' columns per row' : f.prop === 'sibling-direction' ? '' : 'px'}, ours ${show(f.ours)} (at the viewports listed)`
+      : `${f.prop}: ${show(f.theirs)}`;
+    const has = css.find(inCss);
+    if (has) return { file: has.path, kind, hint: `${has.path}: ${target} { ${what} }` };
+    const own = css.find((x) => x.path.startsWith(`integration/${folder}/`) && !/style-host\.css$/.test(x.path)) ?? null;
+    const file = own?.path ?? `integration/${folder}/style-${folder}.css`;
+    return { file, kind, hint: `${file}${own ? '' : ' (new)'}: a rule ${target} { ${what} }` };
+  }
+  const has = tpl.find(inTpl);
+  const what =
+    f.prop === 'presence' ? (f.theirs === 'present' ? `render the ${f.part === 'root' ? 'element' : f.part} theirs has` : `remove the ${f.part === 'root' ? 'element' : f.part} theirs does not have`)
+    : f.prop === 'text' ? `its text: theirs ${JSON.stringify(f.theirs)}, ours ${JSON.stringify(f.ours)}`
+    : f.prop === 'order' ? `the parts in their order: ${f.theirs}`
+    : f.prop === 'controls' ? `the controls theirs has in the ${f.part} (theirs ${show(f.theirs)}, ours ${show(f.ours)}): ${f.delta}`
+    : `${f.prop}: ${show(f.theirs)}`;
+  if (has) return { file: has.path, kind, hint: `${has.path} (${target}): ${what}` };
+  // A part ours lacks: the template that renders its component's root.
+  const rn = namesOf(f.selector?.ours ?? null);
+  const rootTpl = f.selector?.part ? tpl.find((x) => rn.classes.some((c) => new RegExp(`class(Name)?=["'\`][^"'\`]*(?<![\\w-])${esc(c)}(?![\\w-])`).test(x.text)) || rn.markers.some((m) => new RegExp(`data-lbx-part=["']?[^"']*(?<![\\w-])${esc(m)}(?![\\w-])`).test(x.text))) : null;
+  const builtIn = BUILT_IN[role ?? ''] ?? BUILT_IN[rn.markers[0] ?? ''] ?? null;
+  const own = rootTpl ?? (builtIn ? tpl.find((x) => x.path === `integration/${builtIn}`) : null);
+  if (own) return { file: own.path, kind, hint: `${own.path} (${target}${rootTpl ? `, inside ${rn.last}` : ''}): ${what}` };
+  if (builtIn) return { file: `integration/${builtIn}`, kind, hint: `integration/${builtIn} (new: a copy of Luma's src/widgets/${builtIn}, which renders ${target}): ${what}` };
+  return { file: null, kind, hint: `the template that renders ${target} (no integration file names it): ${what}` };
+};

package/parity/hold.mjs

@@ -0,0 +1,54 @@
+// Luma on a page as a customer installs it (README, "What the site includes"): the
+// generic early-hold snippet (snippet/early-hold.min.js) first in <head>,
+// then the build. `yarn luma parity` (ours in every mode: replay, --record,
+// --live, --dev) and `yarn luma a11y` put the build in the storefront's own page
+// this way: before, they imported the build alone, so every full page load
+// painted their listing first (the snippet never held it), which production
+// never shows once the rules are stored (docs/PARITY.md, "The hold").
+//
+// No HTML is rewritten (a recording replays byte for byte, a live page is the
+// browser's own response): an init script (addInitScript, before any script
+// of the page) watches for <head> and inserts the snippet as its first child,
+// an inline <script> that runs at once, before the first script of their
+// <head> (the parser runs a microtask checkpoint before each of its scripts)
+// and before the first paint; then it imports the build.
+import { readFileSync } from 'node:fs';
+
+/** The snippet customers paste first in <head> (README's copy is the same: `yarn snippet:check`). */
+export const SNIPPET = readFileSync(new URL('../snippet/early-hold.min.js', import.meta.url), 'utf8').trim();
+
+/**
+ * In the page, before any of its scripts (addInitScript; self-contained):
+ * on `origin`'s top document, the snippet (`snippet`, its source) first in
+ * <head>, then `import(bundle)` (the build's entry). `snippet: ''` leaves it
+ * out (the build alone, as before). `window.__lbx.hold` (Luma's one global) says what was put
+ * in: `{ snippet: true|false, bundle }`.
+ * @param {{ origin: string, bundle: string | null, snippet: string, tag?: string }} cfg
+ */
+export function holdInit(cfg) {
+  if (location.origin !== cfg.origin || window.top !== window) return;
+  const L = (window.__lbx = window.__lbx || {});
+  if (L.hold) return;
+  const state = (L.hold = { snippet: false, bundle: cfg.bundle || null });
+  let done = false;
+  const inject = () => {
+    if (done) return true;
+    const head = document.head;
+    if (!head) return false;
+    done = true;
+    if (cfg.snippet) {
+      const s = document.createElement('script');
+      s.setAttribute('data-lbx-parity', 'early-hold');
+      s.textContent = cfg.snippet;
+      head.insertBefore(s, head.firstChild);
+      state.snippet = true;
+    }
+    if (cfg.bundle) import(cfg.bundle).catch((e) => console.error(`[${cfg.tag || 'parity'}] the integration did not load`, e));
+    return true;
+  };
+  if (inject()) return;
+  const mo = new MutationObserver(() => {
+    if (inject()) mo.disconnect();
+  });
+  mo.observe(document, { childList: true, subtree: true });
+}