@cparkerwebm/webmonterey 1.0.0

package/src/includes/webmonterey/prose/inline.ts

@@ -0,0 +1,71 @@
+/*
+ * INLINE TEXT FORMATTING for prose blocks.
+ *
+ * Page JSON is plain strings, but real copy needs bold lead-ins and links — a privacy policy
+ * is almost entirely "**Something.** explanation, see [the policy](/privacy)". Supporting that
+ * without shipping a markdown parser is the whole job of this module.
+ *
+ * The supported subset is deliberately tiny and will not grow without a reason:
+ *
+ *   **bold**              ->  <strong>bold</strong>
+ *   _italic_              ->  <em>italic</em>
+ *   [text](/url)          ->  <a href="/url">text</a>
+ *
+ * ORDER IS LOAD-BEARING. Everything is HTML-escaped FIRST, then the three patterns are
+ * applied to the escaped string. Do not reverse this to "parse then escape": the markers are
+ * all ASCII punctuation that survives escaping intact, so escaping first costs nothing and
+ * means a `<script>` in page JSON is inert no matter what. Page JSON is trusted content —
+ * it arrives through a reviewed commit, not a form — but a content model that is safe only
+ * while everyone remembers to be careful is not safe.
+ *
+ * The output is passed to `set:html`, which does NOT sanitise. This module is the sanitiser.
+ */
+
+/** Escape the five characters that can break out of text or an attribute value. */
+export function escapeHtml(value: string): string {
+  return value
+    .replace(/&/g, '&amp;')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;')
+    .replace(/'/g, '&#39;');
+}
+
+/*
+ * Schemes allowed in a link. `javascript:` and `data:` are the two that turn a link into
+ * script execution, so this is an allowlist rather than a blocklist — a blocklist misses
+ * `vbscript:`, control characters inside the scheme, and whatever comes next.
+ *
+ * A relative URL (`/privacy`, `#section`, `contact`) has no scheme and is always allowed.
+ */
+const SAFE_SCHEME = /^(https?:|mailto:|tel:)/i;
+const HAS_SCHEME = /^[a-z][a-z0-9+.-]*:/i;
+
+function safeHref(href: string): string | null {
+  const trimmed = href.trim();
+  if (!trimmed) return null;
+  if (!HAS_SCHEME.test(trimmed)) return trimmed; // relative
+  return SAFE_SCHEME.test(trimmed) ? trimmed : null;
+}
+
+/**
+ * Render one string of prose to HTML. Escapes everything, then applies the subset above.
+ *
+ * A link with an unsafe scheme degrades to its own text — the words survive, the link does
+ * not. Silently dropping the whole phrase would lose content the author wrote.
+ */
+export function renderInline(text: string): string {
+  return (
+    escapeHtml(text)
+      // Links first: their label may itself contain bold, and the URL must not be scanned
+      // for emphasis markers (an underscore in a query string is not italic).
+      .replace(/\[([^\]]+)\]\(([^)\s]+)\)/g, (_match, label: string, href: string) => {
+        const safe = safeHref(href);
+        return safe === null ? label : `<a href="${safe}">${label}</a>`;
+      })
+      .replace(/\*\*([^*]+)\*\*/g, '<strong>$1</strong>')
+      // Underscores only count as emphasis at a word boundary, so snake_case_identifiers and
+      // the underscores inside a URL that already became an href are left alone.
+      .replace(/(^|\s)_([^_]+)_(?=$|[\s.,;:!?)])/g, '$1<em>$2</em>')
+  );
+}

package/src/includes/webmonterey/scroll-top/ScrollTop.astro

@@ -0,0 +1,209 @@
+---
+import { copy } from '../copy.ts';
+/*
+ * Back-to-top control — a circular progress ring that fills 0→100% with scroll depth,
+ * wrapping an up arrow. Fixed to the bottom-right.
+ *
+ * The ring is a conic-gradient driven by ONE custom property, --webm-scroll-progress, which
+ * the script updates. No SVG, no stroke-dasharray maths, no per-frame layout.
+ *
+ * Progress is tracked with a scroll listener throttled to requestAnimationFrame — unlike the
+ * show/hide case, a ring genuinely needs a continuous value, so IntersectionObserver cannot
+ * do the job. The handler is passive and does one style write per frame at most.
+ *
+ * Where scroll-driven animations are supported the ring is driven natively by
+ * `animation-timeline: scroll()` instead, with zero JavaScript; the script is the fallback
+ * and stands down when CSS is handling it.
+ *
+ * USAGE — near the end of <body> in the layout:
+ *
+ *   <ScrollTop />
+ */
+interface Props {
+  /** Accessible name. */
+  label?: string;
+  /** Hide the control until the visitor has scrolled this fraction of the page (0–1). */
+  revealAfter?: number;
+}
+
+const { label = copy.scrollTop.label, revealAfter = 0.15 } = Astro.props;
+---
+
+<!--
+  href="#top" is a browser-defined special case that scrolls to the top of the DOCUMENT and
+  needs no matching element. Do NOT point this at #webm-main: once a site has a header above
+  <main>, "Back to top" would land the visitor below it, hijack the skip link's target, and
+  push a hash into history.
+-->
+<a class="webm-scroll-top" href="#top" data-reveal-after={revealAfter} aria-label={label} hidden>
+  <span class="webm-scroll-top__ring" aria-hidden="true"></span>
+  <svg
+    class="webm-scroll-top__icon"
+    viewBox="0 0 24 24"
+    width="18"
+    height="18"
+    aria-hidden="true"
+    focusable="false"
+  >
+    <path
+      d="M12 19V5M5 12l7-7 7 7"
+      fill="none"
+      stroke="currentColor"
+      stroke-width="2.5"
+      stroke-linecap="round"
+      stroke-linejoin="round"></path>
+  </svg>
+</a>
+
+<style>
+  @layer webm.components.core {
+    .webm-scroll-top {
+      /* 0 → 1. Read by the conic-gradient below. */
+      --webm-scroll-progress: 0;
+      --webm-scroll-size: 3rem;
+      --webm-scroll-ring-width: 3px;
+
+      position: fixed;
+      inset-block-end: var(--webm-space-md);
+      inset-inline-end: var(--webm-space-md);
+      z-index: var(--webm-z-sticky);
+
+      display: grid;
+      place-items: center;
+      inline-size: var(--webm-scroll-size);
+      block-size: var(--webm-scroll-size);
+
+      color: var(--webm-action);
+      background-color: var(--webm-surface-raised);
+      border-radius: var(--webm-radius-circle);
+      box-shadow: var(--webm-shadow-md);
+
+      transition:
+        opacity var(--webm-duration-normal) var(--webm-ease-out),
+        translate var(--webm-duration-normal) var(--webm-ease-out);
+    }
+
+    /* Entry state the script sets for one frame, so the reveal has something to animate to. */
+    .webm-scroll-top:where([data-entering]) {
+      opacity: 0;
+      translate: 0 var(--webm-space-sm);
+    }
+
+    /*
+     * The ring. A conic-gradient hard-stops at the progress angle: filled in --webm-action,
+     * unfilled in a muted track. `mask` punches out the middle so only a ring remains —
+     * cheaper and sharper than an SVG circle, and it animates on the compositor.
+     */
+    .webm-scroll-top__ring {
+      position: absolute;
+      inset: 0;
+      border-radius: inherit;
+      background: conic-gradient(
+        from 0deg,
+        var(--webm-action) calc(var(--webm-scroll-progress) * 360deg),
+        var(--webm-border-subtle) 0
+      );
+      mask: radial-gradient(
+        closest-side,
+        transparent calc(100% - var(--webm-scroll-ring-width)),
+        black calc(100% - var(--webm-scroll-ring-width))
+      );
+    }
+
+    .webm-scroll-top__icon {
+      /* Above the ring, and nudged optically rather than mathematically centred. */
+      position: relative;
+    }
+
+    .webm-scroll-top:hover {
+      color: var(--webm-action-dark);
+    }
+
+    /*
+     * Preferred path: drive the ring from the scroll timeline itself — no JavaScript at all.
+     * The script detects this support and stops updating the property.
+     */
+    @supports (animation-timeline: scroll()) {
+      .webm-scroll-top__ring {
+        animation: webm-scroll-ring linear both;
+        animation-timeline: scroll(root block);
+      }
+    }
+  }
+
+  @keyframes webm-scroll-ring {
+    from {
+      --webm-scroll-progress: 0;
+    }
+    to {
+      --webm-scroll-progress: 1;
+    }
+  }
+</style>
+
+<!--
+  Registering the custom property is what makes --webm-scroll-progress ANIMATABLE. Without
+  @property it is an untyped token that jumps 0 → 1 with no interpolation, so the CSS-driven
+  ring would snap rather than sweep. It has to live outside the scoped <style> block because
+  @property is always global.
+-->
+<style is:global>
+  @property --webm-scroll-progress {
+    syntax: '<number>';
+    inherits: false;
+    initial-value: 0;
+  }
+</style>
+
+<script>
+  const button = document.querySelector<HTMLAnchorElement>('.webm-scroll-top');
+
+  if (button) {
+    const revealAfter = Number(button.dataset.revealAfter ?? '0.15');
+
+    // If CSS can drive the ring from the scroll timeline, JS only handles show/hide.
+    const cssDrivesRing = CSS.supports('animation-timeline', 'scroll()');
+
+    let ticking = false;
+
+    const update = () => {
+      ticking = false;
+
+      const doc = document.documentElement;
+      const scrollable = doc.scrollHeight - doc.clientHeight;
+
+      // A page shorter than the viewport has nothing to scroll: never show the control.
+      if (scrollable <= 0) {
+        if (!button.hidden) button.hidden = true;
+        return;
+      }
+
+      const progress = Math.min(Math.max(doc.scrollTop / scrollable, 0), 1);
+
+      if (!cssDrivesRing) {
+        button.style.setProperty('--webm-scroll-progress', String(progress));
+      }
+
+      const shouldShow = progress > revealAfter;
+
+      if (shouldShow && button.hidden) {
+        button.hidden = false;
+        button.setAttribute('data-entering', '');
+        // Next frame, drop the attribute so the transition has a target to run to.
+        requestAnimationFrame(() => button.removeAttribute('data-entering'));
+      } else if (!shouldShow && !button.hidden) {
+        button.hidden = true;
+      }
+    };
+
+    const onScroll = () => {
+      if (ticking) return;
+      ticking = true;
+      requestAnimationFrame(update);
+    };
+
+    addEventListener('scroll', onScroll, { passive: true });
+    addEventListener('resize', onScroll, { passive: true });
+    update();
+  }
+</script>

package/src/includes/webmonterey/site.ts

@@ -0,0 +1,136 @@
+/*
+ * Typed access to the client's webmonterey.json.
+ *
+ * THIN BY DESIGN. Everything here is a binding of a pure helper in config.ts to the real config,
+ * which arrives through the `virtual:webm/site` module the integration provides. The logic is
+ * tested without a build; this file is what wires it up.
+ *
+ * The question everything asks of this file is whether a field has actually been filled in yet.
+ * `client` and `domain` ship as the literal CHANGEME, and five surfaces depend on knowing that -
+ * each wanting a DIFFERENT answer to "what should I do about it":
+ *
+ *   Credit.astro     throw, because a credit link with a placeholder in utm_content is worse
+ *                    than no build
+ *   robots.txt       omit the Sitemap: line, because pointing crawlers at a sitemap that does
+ *                    not exist is worse than omitting it
+ *   structured data  emit nothing at all, because @id values need a real origin
+ *   email            fall back to the domain, because failing a live enquiry over a cosmetic
+ *                    subject-line prefix trades a real loss for a trivial one
+ *
+ * So this module answers the question and deliberately does NOT decide the consequence.
+ */
+import site from 'virtual:webm/site';
+import {
+  DEFAULT_LOCALE,
+  DEFAULT_TIME_ZONE,
+  isStagingDeployment,
+  zonedHour,
+  isConfigured,
+  PLACEHOLDER,
+  resolveDisplayName,
+  type Organization,
+  type SiteConfig,
+  type SiteFeatures,
+} from './config.ts';
+
+export { PLACEHOLDER, isConfigured, isStagingDeployment };
+export type { SiteConfig, SiteFeatures, Organization };
+
+export const config: SiteConfig = site;
+
+export const client = site.client;
+export const domain = site.domain;
+export const features: SiteFeatures = site.features ?? {};
+export const organization: Organization = site.organization ?? {};
+
+/** The short name for titles, falling back to the display name. See SiteConfig.shortName. */
+export const shortName = isConfigured(site.shortName) ? site.shortName! : displayName();
+
+/** Whether to append the site name to a page title. See SiteConfig.brandTitles. */
+export const brandTitles = site.brandTitles !== false;
+
+/**
+ * The Google Tag Manager container id, or '' when the site has not set one.
+ *
+ * `isConfigured` rather than a plain read, so the literal CHANGEME never reaches a script tag:
+ * GTM would request a container by that name, 404, and leave a broken third-party request on
+ * every page of the site.
+ */
+export const gtmId = isConfigured(site.gtmId) ? site.gtmId! : '';
+
+/**
+ * What this deployment is FOR. See SiteConfig.environment.
+ *
+ * Unset means production — see the field's own note for why that default is the safe one.
+ */
+export const environment = site.environment ?? 'production';
+
+/** True when this deployment must not touch a client's real contacts. */
+export const isStaging = environment === 'staging';
+export const isProduction = !isStaging;
+
+/**
+ * Where staging email goes instead of its real recipients, or '' when the site has not said.
+ * There is no default - see SiteConfig.stagingEmail. sendEmail refuses on '' rather than guessing.
+ */
+export const stagingEmail = isConfigured(site.stagingEmail) ? site.stagingEmail! : '';
+
+export const hasClient = isConfigured(client);
+export const hasDomain = isConfigured(domain);
+
+/*
+ * THE PHONE NUMBER, from organization.telephone.
+ *
+ * Stored in E.164 - a leading + and country code, no punctuation - because that is what Google
+ * expects in structured data. That is also exactly what a `tel:` href wants, so the same value
+ * serves the JSON-LD and the call link on a mobile menu, and there is one place to change it.
+ *
+ * The human-readable form is a display decision and belongs in the component that shows it.
+ *
+ * Added because webmonterey.com had already patched this into its own copy of this file. That
+ * is the copy-forward failure the package exists to end: a fix made in one site's src/includes/
+ * reaches no other site, ever, and nothing reports that it is missing.
+ */
+export const telephone = organization.telephone ?? '';
+export const hasTelephone = isConfigured(telephone);
+
+/** Never returns 'CHANGEME'. See resolveDisplayName. */
+export function displayName(): string {
+  return resolveDisplayName(client, domain);
+}
+
+/**
+ * IANA zone for every client-facing date. Everything stored is UTC, so nothing reaches a person
+ * without passing through this - a prerendered page especially, which bakes in build-time values
+ * and must be handed the zone explicitly rather than trusting the build machine's clock.
+ */
+export const timeZone = site.timeZone ?? DEFAULT_TIME_ZONE;
+export const locale = site.locale ?? DEFAULT_LOCALE;
+
+/**
+ * The hour, 0-23, in THIS site's zone. See zonedHour in config.ts for why a scheduled job needs
+ * it and why it cannot use a fixed UTC hour.
+ *
+ *     export default defineWorker({
+ *       scheduled: (c, env, ctx) => {
+ *         if (hourNow(new Date(c.scheduledTime)) !== 21) return;   // 9pm local, all year
+ *         ctx.waitUntil(sendSummaries(env));
+ *       },
+ *     });
+ */
+export function hourNow(at: Date = new Date()): number {
+  return zonedHour(at, timeZone);
+}
+
+/**
+ * Format a date in the client's zone and locale.
+ *
+ * Never call toLocaleString without a zone on a prerendered route: the build machine's clock is
+ * the developer's and the Worker's is UTC, so a date rendered at build is wrong in one of them.
+ */
+export function formatDate(
+  value: Date | string | number,
+  options: Intl.DateTimeFormatOptions = {},
+): string {
+  return new Intl.DateTimeFormat(locale, { timeZone, ...options }).format(new Date(value));
+}