@getvitops/emdash 2.0.0-alpha.1 → 2.0.0-alpha.3

package/src/astro/blocks/nav.ts

@@ -1,5 +1,5 @@
 /**
- * Pure decisions behind the `vitops.nav` block, kept out of `Nav.astro` so they are asserted in
+ * Pure decisions behind the `vitops_nav` block, kept out of `Nav.astro` so they are asserted in
  * `nav.test.ts` without rendering (the split `sitenav.ts` makes for `<SiteNav>`). The menu-tree
  * helpers themselves — depth trimming, `aria-current` — are `@getvitops/astro`'s, not copied.
  */

package/src/astro/blocks/render.container.test.ts

@@ -30,7 +30,7 @@ async function render(component: unknown, node: object) {
   return container.renderToString(component as Component, { props: { node } });
 }
 
-describe('vitops.cards', () => {
+describe('vitops_cards', () => {
   const cards = [
     {
       title: 'Cut costs',
@@ -42,7 +42,7 @@ describe('vitops.cards', () => {
 
   it('renders the title as a heading at the chosen level (U19), not a paragraph', async () => {
     const html = await render(Cards, { cards, level: '4' });
-    expect(html).toContain('<h4 class="font-heading">Cut costs</h4>');
+    expect(html).toContain('<h4 class="card__title font-heading">Cut costs</h4>');
     expect(html).not.toContain('<p class="font-heading"');
   });
 
@@ -73,7 +73,7 @@ describe('vitops.cards', () => {
   });
 });
 
-describe('vitops.hero', () => {
+describe('vitops_hero', () => {
   it('accents starred words and honours the heading level', async () => {
     const html = await render(Hero, { heading: 'Two services. *One team.*', level: '3' });
     expect(html).toContain(
@@ -83,11 +83,14 @@ describe('vitops.hero', () => {
 
   it('renders the optional cards slot', async () => {
     const html = await render(Hero, { heading: 'Hi', cards: [{ title: 'A', body: 'b' }] });
-    expect(html).toContain('<h3 class="font-heading">A</h3>');
+    // the hero defaults to h1, so its option cards sit one level down
+    expect(html).toContain('<h2 class="font-heading">A</h2>');
+    const under2 = await render(Hero, { heading: 'Hi', level: '2', cards: [{ title: 'A' }] });
+    expect(under2).toContain('<h3 class="font-heading">A</h3>');
   });
 });
 
-describe('vitops.logos', () => {
+describe('vitops_logos', () => {
   it('is a labelled list of images with alt text', async () => {
     const html = await render(Logos, {
       label: 'Key partners',
@@ -103,12 +106,28 @@ describe('vitops.logos', () => {
     expect(html).toContain('<a href="/acme">');
   });
 
+  it('shows the name as text when an entry has no image, linked or not', async () => {
+    const html = await render(Logos, {
+      logos: [
+        { alt: 'Acme Partners', href: '/acme' },
+        { alt: 'Beta Group' },
+        { image: '/c.svg', alt: 'Gamma' },
+        { image: '', alt: '' },
+      ],
+    });
+    expect(html).toContain('<span class="logos__name font-heading">Acme Partners</span>');
+    expect(html).toContain('<span class="logos__name font-heading">Beta Group</span>');
+    expect(html).toContain('<a href="/acme"><span');
+    expect(html).toContain('alt="Gamma"');
+    expect(html.match(/logos__item/g)).toHaveLength(3);
+  });
+
   it('renders nothing with no logos', async () => {
     expect((await render(Logos, { logos: [] })).trim()).toBe('');
   });
 });
 
-describe('vitops.steps', () => {
+describe('vitops_steps', () => {
   it('is an ordered list with real headings and a tone', async () => {
     const html = await render(Steps, {
       steps: [{ title: 'Call', text: 'We talk' }, { title: 'Build' }],
@@ -123,7 +142,7 @@ describe('vitops.steps', () => {
   });
 });
 
-describe('vitops.stats', () => {
+describe('vitops_stats', () => {
   const stats = [
     { value: '82%', label: 'Faster', group: 'Ops', delta: '+3 this week', state: 'up' },
   ];
@@ -150,7 +169,7 @@ describe('vitops.stats', () => {
   });
 });
 
-describe('vitops.callout', () => {
+describe('vitops_callout', () => {
   it('is a heading, text and actions in a tinted or solid band — not a banner', async () => {
     const html = await render(Callout, {
       heading: 'Ready?',
@@ -168,7 +187,7 @@ describe('vitops.callout', () => {
   });
 });
 
-describe('vitops.entries', () => {
+describe('vitops_entries', () => {
   it('emits <wc-entries> with a semantic heading + dl per entry', async () => {
     const html = await render(Entries, {
       level: '4',
@@ -191,7 +210,7 @@ describe('vitops.entries', () => {
   });
 });
 
-describe('vitops.pricing', () => {
+describe('vitops_pricing', () => {
   it('aligns plans through the pricing-card subgrid rows', async () => {
     const html = await render(Pricing, {
       plans: [
@@ -221,7 +240,7 @@ describe('vitops.pricing', () => {
   });
 });
 
-describe('vitops.embed', () => {
+describe('vitops_embed', () => {
   it('ships the iframe with NO src and the address on data-consent-src', async () => {
     const html = await render(Embed, {
       provider: 'youtube',
@@ -289,12 +308,12 @@ const review = (id: string, rating: number, extra: object = {}) => ({
   ...extra,
 });
 
-describe('vitops.reviews', () => {
+describe('vitops_reviews', () => {
   it('renders nothing when the cache is empty (a fresh scaffold has no reviews.json)', async () => {
     fixtures.cache = { version: 1, locations: {} };
     const { default: Reviews } = await import('./Reviews.astro');
     // The dev-only note is allowed (vitest runs with DEV on); no card or wrapper is.
-    const html = await render(Reviews, { _type: 'vitops.reviews' });
+    const html = await render(Reviews, { _type: 'vitops_reviews' });
     expect(html).not.toContain('<article');
     expect(html).not.toMatch(/class="reviews[" ]/);
   });
@@ -371,7 +390,7 @@ describe('vitops.reviews', () => {
   });
 });
 
-describe('vitops.nav', () => {
+describe('vitops_nav', () => {
   const menu = {
     label: 'Footer site map',
     items: [
@@ -441,7 +460,7 @@ describe('vitops.nav', () => {
 // block the test nests, so it resolves as in production. (Not the whole `blockComponents` map:
 // that imports Section.astro, which imports `emdash/ui`, which awaits this very factory.)
 vi.mock('virtual:emdash/block-components', async () => ({
-  pluginBlockComponents: { 'vitops.logos': (await import('./Logos.astro')).default },
+  pluginBlockComponents: { vitops_logos: (await import('./Logos.astro')).default },
 }));
 
 vi.mock('virtual:emdash/config', () => ({ default: {} }));
@@ -466,8 +485,8 @@ describe('vitops_section', () => {
               style: 'normal',
               children: [{ _type: 'span', _key: 'b', text: 'Body copy' }],
             },
-            // The point of the block: another vitops.* block resolves INSIDE the body.
-            { _type: 'vitops.logos', _key: 'c', logos: [{ image: '/x.svg', alt: 'Acme' }] },
+            // The point of the block: another vitops_* block resolves INSIDE the body.
+            { _type: 'vitops_logos', _key: 'c', logos: [{ image: '/x.svg', alt: 'Acme' }] },
           ],
         },
       },
@@ -481,7 +500,7 @@ describe('vitops_section', () => {
   }, 60_000);
 });
 
-describe('vitops.form', () => {
+describe('vitops_form', () => {
   async function renderForm(node: object, path = '/contact') {
     const container = await AstroContainer.create();
     return container.renderToString(Form as unknown as Component, {
@@ -506,6 +525,19 @@ describe('vitops.form', () => {
     expect(html).toContain('Send message');
   });
 
+  it('renders "tick any number" as a fieldset of checkboxes sharing one name', async () => {
+    const html = await renderForm({
+      ...SAMPLE_FORM_BLOCK,
+      fields: [
+        { label: 'Interests', name: 'interests', type: 'checkboxes', options: 'IT\nMarketing' },
+      ],
+    });
+    expect(html).toContain('<fieldset');
+    expect(html).toContain('<legend class="form-group__label">Interests</legend>');
+    expect(html.match(/name="interests"/g)).toHaveLength(2);
+    expect(html).toContain('value="Marketing"');
+  });
+
   it('never submits a phone field as `phone`: the route drops that name', async () => {
     const html = await renderForm(SAMPLE_FORM_BLOCK);
     expect(html).toContain('name="tel"');
@@ -560,7 +592,7 @@ describe('vitops.form', () => {
     const html = await renderForm({ ...SAMPLE_FORM_BLOCK, action: 'https://evil.example/steal' });
     expect(html).toContain('action="/api/track"');
     expect(html).not.toContain('evil.example');
-    expect(await renderForm({ _type: 'vitops.form', fields: [] })).not.toContain('<form');
+    expect(await renderForm({ _type: 'vitops_form', fields: [] })).not.toContain('<form');
   });
 
   it('escapes editor text', async () => {
@@ -608,3 +640,43 @@ describe('escape hatches (anchor, className, style)', () => {
     },
   );
 });
+
+describe('per-item colour and hero card extras', () => {
+  const rows = [
+    { title: 'Pine', body: 'a', tone: 'success' },
+    { title: 'Amber', body: 'b', color: 'amber' },
+    { title: 'Plain', body: 'c' },
+  ];
+
+  it('a row sets its own --tone-* properties; a row with none inherits', async () => {
+    const html = await render(Cards, { variant: 'panel', tone: 'info', cards: rows });
+    const items = html.match(/<li[^>]*class="card[^"]*"[^>]*>/g)!;
+    expect(items).toHaveLength(3);
+    expect(items[0]).toContain('--color-bg-success-muted');
+    expect(items[1]).toContain('--color-amber-100');
+    expect(items[2]).toContain('--color-bg-info-muted'); // the block's own
+  });
+
+  it('applies to stats and steps rows', async () => {
+    const stats = await render(Stats, {
+      stats: [{ value: '1', tone: 'danger' }, { value: '2' }],
+    });
+    expect(stats).toContain('stats__item" style="--tone-bg');
+    const steps = await render(Steps, {
+      steps: [{ title: 'A', color: 'amber' }, { title: 'B' }],
+    });
+    expect(steps).toContain('steps__item" style="--tone-bg');
+  });
+
+  it('hero cards take an eyebrow, a button and a tone', async () => {
+    const html = await render(Hero, {
+      heading: 'H',
+      level: '1',
+      cards: [{ title: 'Door', eyebrow: 'For IT', ctaLabel: 'Go', ctaHref: '/go', color: 'amber' }],
+    });
+    expect(html).toContain('class="font-eyebrow">For IT');
+    expect(html).toContain('<a class="cta" href="/go">');
+    expect(html).toContain('card subgrid-card tone');
+    expect(html).not.toContain('stretched-link');
+  });
+});

package/src/astro/blocks/tone.test.ts

@@ -51,3 +51,13 @@ describe('joinStyle', () => {
     expect(joinStyle('--a: 1', '', '--b: 2')).toBe('--a: 1; --b: 2');
   });
 });
+
+describe('solid fill from a hue and step', () => {
+  it("takes its text from the site's -on token for that step", () => {
+    expect(resolveTone('', 'amber-500').style).toContain(
+      '--tone-on-solid: var(--color-amber-500-on)',
+    );
+    expect(resolveTone('', 'navy').style).toContain('--tone-on-solid: var(--color-navy-600-on)');
+    expect(resolveTone('', 'navy').className).toBe('tone');
+  });
+});

package/src/astro/blocks/tone.ts

@@ -7,7 +7,10 @@
  *   fallbacks, then `neutral`.
  * - **`color`** — the escape hatch: a palette hue (`amber`) or hue and step (`amber-300`).
  *   Wins over `tone` when set. Contrast is NOT checked for it — the generator's contrast
- *   contract covers roles, not arbitrary hue/step pairs — so it is for decoration.
+ *   contract covers roles, not arbitrary hue/step pairs — so it is for decoration. A solid fill
+ *   reads from the site's `--color-<hue>-<step>-on` and the tint flips with the colour scheme
+ *   (`light-dark()`); mid steps (300–500) cannot reach APCA Lc 75 with either text colour, so use
+ *   a role where contrast matters.
  *
  * **Why CSS custom properties, not classes.** A class name built from a field value
  * (`bg-${tone}`) is invisible to Tailwind's scanner, so it generates nothing in that
@@ -82,14 +85,21 @@ export function resolveTone(tone?: unknown, color?: unknown): ResolvedTone {
   if (hue) {
     const [, name, step] = hue;
     const at = (s: string) => `var(--color-${name}-${s})`;
+    // The foreground is the site's own: the generator emits `--color-<hue>-<step>-on` for every
+    // step, picked by the same APCA rule as `text-on-<role>`, so a fill by hue and step reads
+    // without a fixed white and without asking the browser to guess.
+    const fill = step ?? '600';
+    // Raw hue steps never re-point in dark, so the tint flips here: `light-dark()` follows the
+    // `color-scheme` the generator sets under the dark selector.
+    const flip = (light: string, dark: string) => `light-dark(${at(light)}, ${at(dark)})`;
     return {
       className: 'tone',
       style: [
-        `--tone-bg: ${at('100')}`,
-        `--tone-fg: ${at('900')}`,
-        `--tone-border: ${at('300')}`,
-        `--tone-solid: ${at(step ?? '600')}`,
-        `--tone-on-solid: #fff`,
+        `--tone-bg: ${flip('100', '900')}`,
+        `--tone-fg: ${flip('900', '100')}`,
+        `--tone-border: ${flip('300', '700')}`,
+        `--tone-solid: ${at(fill)}`,
+        `--tone-on-solid: ${at(`${fill}-on`)}`,
       ].join('; '),
     };
   }
@@ -120,3 +130,35 @@ export function joinStyle(...parts: (string | undefined | false)[]): string | un
   const out = parts.filter(Boolean).join('; ');
   return out || undefined;
 }
+
+/**
+ * A repeater row's own colour: the `style` that overrides the block's `--tone-*` properties for
+ * that item, or `undefined` when the row sets none (it then inherits the block's). Only the custom
+ * properties are written, so the row picks up the block's own `.tone` surface and just recolours it.
+ */
+export function rowTone(row: Record<string, unknown>): string | undefined {
+  return resolveTone(row.tone, row.color).style || undefined;
+}
+
+/**
+ * The `theme` every block can carry: a backdrop for the block's own root element, chosen from the
+ * site's colour roles. `<role>` is the tinted surface (`bg-<role>-muted`, with the role's text);
+ * `<role>:solid` is the filled backdrop with the contrast-computed `text-on-<role>`; `none` or
+ * nothing is no theme. Contrast is therefore the generator's guarantee, not the editor's judgement,
+ * and a site that styles its roles as raised, glass or flat gets that look, because the tokens are
+ * the site's own.
+ *
+ * Returns the classes and `--tone-*` style to put on the root element, or `undefined` for no theme.
+ */
+export function resolveTheme(theme: unknown): { className: string; style: string } | undefined {
+  if (typeof theme !== 'string') return undefined;
+  const [role, fill] = theme
+    .trim()
+    .toLowerCase()
+    .replace(/^none$/, '')
+    .split(':');
+  if (!role || !ROLE.test(role)) return undefined;
+  const tone = resolveTone(role);
+  if (!tone.style) return undefined;
+  return { className: fill === 'solid' ? 'tone tone--solid' : 'tone', style: tone.style };
+}

package/src/astro/blocks/unrendered.ts

@@ -0,0 +1,23 @@
+/**
+ * Which `vitops_*` blocks in a Portable Text body have no renderer in the merged plugin map.
+ *
+ * `<PortableText>` logs `[components.type] is missing "vitops.…"` and drops the block, and the
+ * build still succeeds. Renderers that nest a body (`vitops_section`, widget areas) emit a
+ * `data-vitops-unrendered` marker for each such type so `vitops emdash check-prerender` can fail
+ * the build instead of publishing a page with holes in it.
+ *
+ * The virtual module is imported lazily, for the same reason `emdash/ui` is: it imports this
+ * package's `./astro` entry, so a static import closes the cycle.
+ */
+export async function unrenderedTypes(body: unknown): Promise<string[]> {
+  if (!Array.isArray(body)) return [];
+  const wanted = new Set<string>();
+  for (const node of body) {
+    const type = node && typeof node === 'object' ? (node as { _type?: unknown })._type : undefined;
+    if (typeof type === 'string' && type.startsWith('vitops_')) wanted.add(type);
+  }
+  if (wanted.size === 0) return [];
+  const { pluginBlockComponents } = await import('virtual:emdash/block-components');
+  const map = (pluginBlockComponents ?? {}) as Record<string, unknown>;
+  return [...wanted].filter((type) => !map[type]).sort();
+}

package/src/astro/blocks/value.test.ts

@@ -1,5 +1,15 @@
 import { describe, expect, it } from 'vite-plus/test';
-import { accentRuns, headingTag, lines, linkRuns, pairs, paragraphs, rows, text } from './value.ts';
+import {
+  accentRuns,
+  headingTag,
+  outlineTag,
+  lines,
+  linkRuns,
+  pairs,
+  paragraphs,
+  rows,
+  text,
+} from './value.ts';
 
 describe('editor-text helpers', () => {
   it('headingTag clamps to h2-h6 and falls back', () => {
@@ -54,3 +64,19 @@ describe('repeater helpers', () => {
     expect(paragraphs('')).toEqual([]);
   });
 });
+
+describe('outlineTag', () => {
+  it('allows h1 through h6', () => {
+    expect(outlineTag('1')).toBe('h1');
+    expect(outlineTag(6)).toBe('h6');
+  });
+  it('returns p for a heading that is not in the outline', () => {
+    expect(outlineTag('p')).toBe('p');
+    expect(outlineTag(' P ')).toBe('p');
+  });
+  it('falls back for anything else', () => {
+    expect(outlineTag(undefined, 1)).toBe('h1');
+    expect(outlineTag(9)).toBe('h2');
+    expect(outlineTag('x', 3)).toBe('h3');
+  });
+});

package/src/astro/blocks/value.ts

@@ -59,6 +59,22 @@ export function headingTag(
   return `h${clamped}` as 'h2' | 'h3' | 'h4' | 'h5' | 'h6';
 }
 
+/**
+ * The element for a block that may own the page's title: `h1`–`h6`, or `p` when the heading is
+ * visual only and the outline should not carry it (the role class still styles it). Hero and
+ * section use this; every other block keeps `headingTag`'s `h2`–`h6`, so a page's `h1` only
+ * comes from a block an editor chose it for.
+ */
+export function outlineTag(
+  level: unknown,
+  fallback: 1 | 2 | 3 | 4 | 5 | 6 = 2,
+): 'h1' | 'h2' | 'h3' | 'h4' | 'h5' | 'h6' | 'p' {
+  if (String(level).trim().toLowerCase() === 'p') return 'p';
+  const n = Math.round(Number(level));
+  const clamped = Number.isFinite(n) && n >= 1 && n <= 6 ? n : fallback;
+  return `h${clamped}` as 'h1' | 'h2' | 'h3' | 'h4' | 'h5' | 'h6';
+}
+
 /** One run of inline text, optionally a link. */
 export interface Run {
   text: string;

package/src/astro/index.ts

@@ -8,6 +8,7 @@
  * `defineBlockComponents` / `<Blocks components={…}>`. EmDash does not merge it.
  */
 import Badges from './blocks/Badges.astro';
+import { resolveTheme } from './blocks/tone.ts';
 import WidgetArea from './blocks/WidgetArea.astro';
 import Accordion from './blocks/Accordion.astro';
 import ActionLink from './blocks/ActionLink.astro';
@@ -33,29 +34,29 @@ import Stats from './blocks/Stats.astro';
 import Steps from './blocks/Steps.astro';
 
 export const blockComponents = {
-  'vitops.actionLink': ActionLink,
-  'vitops.imageCompare': ImageCompare,
-  'vitops.copyButton': CopyButton,
-  'vitops.banner': Banner,
-  'vitops.details': Details,
-  'vitops.carousel': Carousel,
-  'vitops.gallery': Gallery,
-  'vitops.cards': Cards,
-  'vitops.accordion': Accordion,
-  'vitops.hero': Hero,
-  'vitops.marquee': Marquee,
-  'vitops.logos': Logos,
-  'vitops.steps': Steps,
-  'vitops.stats': Stats,
-  'vitops.callout': Callout,
-  'vitops.entries': Entries,
-  'vitops.pricing': Pricing,
-  'vitops.embed': Embed,
-  'vitops.form': Form,
-  'vitops.reviews': Reviews,
-  'vitops.nav': Nav,
-  'vitops.badges': Badges,
-  'vitops.widgetArea': WidgetArea,
+  vitops_actionLink: ActionLink,
+  vitops_imageCompare: ImageCompare,
+  vitops_copyButton: CopyButton,
+  vitops_banner: Banner,
+  vitops_details: Details,
+  vitops_carousel: Carousel,
+  vitops_gallery: Gallery,
+  vitops_cards: Cards,
+  vitops_accordion: Accordion,
+  vitops_hero: Hero,
+  vitops_marquee: Marquee,
+  vitops_logos: Logos,
+  vitops_steps: Steps,
+  vitops_stats: Stats,
+  vitops_callout: Callout,
+  vitops_entries: Entries,
+  vitops_pricing: Pricing,
+  vitops_embed: Embed,
+  vitops_form: Form,
+  vitops_reviews: Reviews,
+  vitops_nav: Nav,
+  vitops_badges: Badges,
+  vitops_widgetArea: WidgetArea,
 };
 
 /** Keyed by block-type slug (see `SECTION_SLUG`), not by Portable Text `_type`. */
@@ -63,5 +64,14 @@ export const blockTypeComponents = {
   vitops_section: Section,
 };
 
-/** The framework-styled widget area, for a site layout (the block form is `vitops.widgetArea`). */
+/** The framework-styled widget area, for a site layout (the block form is `vitops_widgetArea`). */
 export { default as VitopsWidgetArea } from './WidgetArea.astro';
+
+/**
+ * `themeAttrs('surface')` → `{ class, style }` for the layout's `<body>` (or any element a site owns):
+ * the same backdrop-and-readable-text every block's `theme` field gives, from the site's own roles.
+ */
+export function themeAttrs(theme: string | undefined): { class?: string; style?: string } {
+  const t = resolveTheme(theme);
+  return t ? { class: t.className, style: t.style } : {};
+}