@dloizides/marketing-astro-kit 1.5.1 → 1.6.0

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog
 
+## 1.6.0
+
+### Added
+
+- `<HairlineFigure />` (`./HairlineFigure.astro`) plus `HAIRLINE_FIGURES`, `TOUCH_SAFE_HAIRLINE_FIGURES` and `clampHairlineIntensity` (`./hairline`). Wraps `@lucasmarkes/hairline` 0.3.0 (exact pin): SSR 5:4 box, lazy mount near the viewport, destroy on page swap, `--hairline-*` mapped from the theming contract. HAIRLINE-1 "Adopt hairline isometric line figures".
+
+## 1.5.2
+
+### Fixed
+
+- `.dmk-disclaimer` (DemoFrame) and `.pmk-footnote` (PricingComparison) cap their measure at 65ch; at 1280 px they ran 102-113 characters per line. Mobile is unaffected.
+
 ## 1.3.0
 
 ### Added

package/README.md

@@ -10,6 +10,7 @@ credibility + conversion markers an executive scans for before they trust a SaaS
 | `PrimaryCta.astro` | A themeable **primary call-to-action** (link OR spam-safe contact) with an optional secondary CTA. Pair with `buildPrimaryCta` so ONE `SIGNUP_URL` constant drives whether it's a real signup link or lead-capture. |
 | `DemoFrame.astro` | A themeable, **client-side "try it" demo** shell for static sites (no backend): eyebrow/title/intro, a row of clickable example chips, a per-example result panel (bespoke product body via a named `result-<id>` slot), a "sample data" disclaimer, and a primary CTA. Tiny inline vanilla JS toggles which result shows; first example visible without JS. |
 | `GuideCard.astro` | A themeable **card for a guides / SEO content-hub** listing — one guide's tags, title, description and date. Pair with `guideFrontmatterSchema` on an Astro content collection. |
+| `HairlineFigure.astro` | A **Hairline isometric line figure** (`@lucasmarkes/hairline`, pinned 0.3.0) for heroes and empty states: an empty 5:4 box server-side, drawn on the client once it nears the viewport, coloured from the host's tokens. |
 
 ## Config-driven primary CTA (`PrimaryCta` + `buildPrimaryCta`)
 
@@ -161,6 +162,29 @@ const guides = (await getCollection('guides', ({ data }) => !data.draft))
 `updatedDate?`, `tags`, `ogImage?`, `canonical?`, `draft?`. It is built on
 `astro/zod`, so it is the same zod instance Astro's content layer uses.
 
+## Hairline line figures (`HairlineFigure`)
+
+```astro
+---
+import HairlineFigure from '@dloizides/marketing-astro-kit/HairlineFigure.astro';
+---
+<HairlineFigure figure="terrain" label="Pillars rising over a plinth" intensity={0.6} class="hero-figure" />
+```
+
+| Prop | Meaning |
+|---|---|
+| `figure` | One of the 27 names in `HAIRLINE_FIGURES` (`@dloizides/marketing-astro-kit/hairline`). |
+| `label` | Required accessible name. A figure is decoration; it never carries information the reader needs. |
+| `intensity` | 0..1, clamped; default 0.5. |
+| `class` | Host-side sizing / placement. |
+
+- **Server render:** an empty `5:4` box, so nothing shifts when it draws. No JS runs until the box is within 200px of the viewport (IntersectionObserver); then the Hairline engine (~170 KB raw, its own lazy chunk) is imported and the figure mounted. Every figure is destroyed on `astro:before-swap`.
+- **Version:** `@lucasmarkes/hairline` is an exact-pinned dependency of this kit. Never add it to a site's own `package.json`; bump it here, deliberately.
+- **Colours:** the component maps the theming contract onto Hairline's variables: `--hairline-plate` <- `--bg`, `--hairline-hi` <- `--ink`, `--hairline-edge` <- `--brand`, `--hairline-mid` <- `--muted`, `--hairline-lo` <- `--hairline`. A missing host token falls through to Hairline's own light/dark defaults. The mapping has zero specificity: on a tinted section set it on the figure, e.g. `.band .hairline-figure { --hairline-plate: var(--bg-tint); }`. Never a hex value.
+- **Touch:** Hairline sets `touch-action: pan-y`, so a vertical finger drag scrolls the page. Figures driven by the pointer's HEIGHT (`elevator`, `laptop`, `terminal`, `cabinet`, `drawer`, `sieve`, `exploded`, `phone`) fight that scroll on a phone; on touch-first pages pick from `TOUCH_SAFE_HAIRLINE_FIGURES` (`terrain`, `riffle`, `keyboard`, `router`, `rail`, `dish`, `turntable`, `plot`). The figure at rest must read on its own: nothing may depend on hover.
+- **Script bundling:** unlike `HeroBackdrop`, this script is a bundled Astro `<script>` (it imports an npm module), so it emits a root-absolute `/_astro/*.js` URL. On a host that serves a tenant from a sub-directory (kefi-landings), set Astro's `build.assetsPrefix` before using it there.
+- **Vite-alias consumers** (the kit aliased to source, not installed) must have `@lucasmarkes/hairline@0.3.0` resolvable from the site.
+
 ## Theming contract
 
 The components read these CSS vars off the host `:root` (each has a sensible

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dloizides/marketing-astro-kit",
-  "version": "1.5.1",
+  "version": "1.6.0",
   "description": "Reusable, themeable Astro marketing sections for product sites — a Free-vs-Pro pricing comparison table, a trust / credibility section (security cards, customer-logo + testimonial placeholders, discreet built-by), a client-side \"try it\" demo shell, and an SEO guides/content-hub card + frontmatter schema. Data-driven via a shared TypeScript schema; themed entirely through the host site's CSS custom properties.",
   "keywords": [
     "astro",
@@ -17,7 +17,9 @@
     "hero",
     "background",
     "canvas",
-    "animation"
+    "animation",
+    "hairline",
+    "illustration"
   ],
   "author": "dloizides",
   "license": "MIT",
@@ -42,7 +44,12 @@
     "./icons": "./src/icons.ts",
     "./HeroBackdrop.astro": "./src/HeroBackdrop.astro",
     "./heroBackdrop": "./src/heroBackdrop/presets.ts",
-    "./heroBackdrop/types": "./src/heroBackdrop/types.ts"
+    "./heroBackdrop/types": "./src/heroBackdrop/types.ts",
+    "./HairlineFigure.astro": "./src/HairlineFigure.astro",
+    "./hairline": "./src/hairline/figures.ts"
+  },
+  "dependencies": {
+    "@lucasmarkes/hairline": "0.3.0"
   },
   "peerDependencies": {
     "astro": ">=4"

package/src/DemoFrame.astro

@@ -254,6 +254,7 @@ const { examples } = data;
     line-height: 1.5;
     color: var(--_muted);
     font-style: italic;
+    max-width: 65ch;
   }
   .dmk-disclaimer__dot {
     flex-shrink: 0;

package/src/HairlineFigure.astro

@@ -0,0 +1,41 @@
+---
+import { clampHairlineIntensity, type HairlineFigureName } from './hairline/figures';
+
+interface Props {
+  /** Which Hairline figure to draw; on touch-first surfaces prefer `TOUCH_SAFE_HAIRLINE_FIGURES`. */
+  figure: HairlineFigureName;
+  /** The accessible name; the figure is decoration and must never carry information. */
+  label: string;
+  intensity?: number;
+  class?: string;
+}
+
+const { figure, label, intensity, class: className = '' } = Astro.props;
+---
+
+<div
+  class:list={['hairline-figure', className]}
+  data-hairline-figure={figure}
+  data-hairline-intensity={clampHairlineIntensity(intensity)}
+  data-hairline-label={label}
+>
+</div>
+
+<style>
+  :where(.hairline-figure) {
+    display: block;
+    width: 100%;
+    aspect-ratio: 5 / 4;
+    --hairline-plate: var(--bg);
+    --hairline-hi: var(--ink);
+    --hairline-edge: var(--brand);
+    --hairline-mid: var(--muted);
+    --hairline-lo: var(--hairline);
+  }
+</style>
+
+<script>
+  import { startHairlineFigures } from './hairline/mount';
+
+  startHairlineFigures();
+</script>

package/src/PricingComparison.astro

@@ -345,6 +345,7 @@ const { tiers, groups } = data;
     color: var(--_muted);
     font-size: 13.5px;
     margin: 18px 2px 0;
+    max-width: 65ch;
   }
 
   /* Concierge / one-time callout --------------------------------------- */

package/src/hairline/figures.ts

@@ -0,0 +1,54 @@
+export const HAIRLINE_FIGURES = [
+  'basket',
+  'branches',
+  'cabinet',
+  'dish',
+  'drawer',
+  'elevator',
+  'exploded',
+  'keyboard',
+  'laptop',
+  'lockers',
+  'loupe',
+  'padlock',
+  'patch',
+  'phone',
+  'phosphor',
+  'plot',
+  'plug',
+  'query',
+  'rail',
+  'riffle',
+  'router',
+  'sieve',
+  'slow',
+  'terminal',
+  'terrain',
+  'turntable',
+  'vault',
+] as const;
+
+export type HairlineFigureName = (typeof HAIRLINE_FIGURES)[number];
+
+export const TOUCH_SAFE_HAIRLINE_FIGURES: readonly HairlineFigureName[] = [
+  'terrain',
+  'riffle',
+  'keyboard',
+  'router',
+  'rail',
+  'dish',
+  'turntable',
+  'plot',
+];
+
+export const DEFAULT_HAIRLINE_INTENSITY = 0.5;
+
+export function isHairlineFigureName(value: string): value is HairlineFigureName {
+  return (HAIRLINE_FIGURES as readonly string[]).includes(value);
+}
+
+/** Clamps an intensity to the 0..1 range Hairline accepts; a non-finite value becomes the default. */
+export function clampHairlineIntensity(value: number | undefined): number {
+  if (value === undefined || !Number.isFinite(value)) return DEFAULT_HAIRLINE_INTENSITY;
+  return Math.min(1, Math.max(0, value));
+}

package/src/hairline/mount.ts

@@ -0,0 +1,53 @@
+import type { Figure } from '@lucasmarkes/hairline';
+import { clampHairlineIntensity, isHairlineFigureName } from './figures';
+
+const HOST_SELECTOR = '[data-hairline-figure]';
+const NEAR_VIEWPORT_MARGIN = '200px 0px';
+
+const running = new Map<HTMLElement, Figure>();
+let observer: IntersectionObserver | null = null;
+
+async function mountFigure(host: HTMLElement): Promise<void> {
+  const name = host.dataset.hairlineFigure ?? '';
+  if (!isHairlineFigureName(name) || running.has(host)) return;
+  const figures = await import('@lucasmarkes/hairline');
+  if (!host.isConnected || running.has(host)) return;
+  const figure = figures[name](host, {
+    intensity: clampHairlineIntensity(Number(host.dataset.hairlineIntensity)),
+    label: host.dataset.hairlineLabel,
+  });
+  running.set(host, figure);
+}
+
+function onIntersect(entries: IntersectionObserverEntry[], watcher: IntersectionObserver): void {
+  entries.forEach((entry) => {
+    if (!entry.isIntersecting) return;
+    watcher.unobserve(entry.target);
+    void mountFigure(entry.target as HTMLElement);
+  });
+}
+
+function observeFigures(): void {
+  const hosts = document.querySelectorAll<HTMLElement>(HOST_SELECTOR);
+  if (hosts.length === 0) return;
+  if (typeof IntersectionObserver === 'undefined') {
+    hosts.forEach((host) => void mountFigure(host));
+    return;
+  }
+  observer ??= new IntersectionObserver(onIntersect, { rootMargin: NEAR_VIEWPORT_MARGIN });
+  hosts.forEach((host) => observer?.observe(host));
+}
+
+function destroyFigures(): void {
+  observer?.disconnect();
+  observer = null;
+  running.forEach((figure) => figure.destroy());
+  running.clear();
+}
+
+/** Mounts every Hairline host on the page as it nears the viewport and tears them down on an Astro page swap. */
+export function startHairlineFigures(): void {
+  observeFigures();
+  document.addEventListener('astro:page-load', observeFigures);
+  document.addEventListener('astro:before-swap', destroyFigures);
+}