@getvitops/emdash 1.0.0 → 2.0.0-alpha.0

package/src/astro/blocks/form.ts

@@ -0,0 +1,158 @@
+/**
+ * Pure decisions for the `vitops.form` block: which of an editor's field rows become real
+ * controls, and under what submitted names.
+ *
+ * Names matter more than they look. `createConversionRoute` (`@getvitops/astro/routes`) is
+ * what receives the post, and it reserves a few: `phone` and `event` are the tel:/mailto:
+ * click-beacon payload and are dropped from a form submission, `cf-turnstile-response` is
+ * the Turnstile token, and `website`/`honeypot`/`_honeypot` are the honeypots (a filled one
+ * makes the route answer success and deliver nothing). A visitor-facing field called
+ * "Phone" must therefore not submit as `phone`, or the number silently vanishes from the
+ * notification and the CRM record. `identifySubmitter` reads `tel` for a phone number, so
+ * that is where it goes.
+ */
+
+export const FIELD_TYPES = ['text', 'email', 'tel', 'textarea', 'select', 'checkbox'] as const;
+export type FieldType = (typeof FIELD_TYPES)[number];
+
+/** Names the route treats specially. A field must never submit under one of these. */
+export const RESERVED_NAMES = new Set([
+  'event',
+  'phone',
+  'cf-turnstile-response',
+  'website',
+  'honeypot',
+  '_honeypot',
+  '_next',
+]);
+
+/** The honeypot's name: the first of the route's own defaults, so no option needs passing. */
+export const HONEYPOT_NAME = 'website';
+
+export const MAX_FIELDS = 20;
+
+export interface FormField {
+  /** Submitted name. */
+  name: string;
+  /** DOM id suffix; unique within the form. */
+  id: string;
+  label: string;
+  type: FieldType;
+  required: boolean;
+  placeholder: string;
+  help: string;
+  options: string[];
+  autocomplete: string | undefined;
+}
+
+const str = (v: unknown): string => (typeof v === 'string' ? v.trim() : '');
+
+/** `Your full name` -> `your_full_name`. Empty when the text holds nothing usable. */
+export function slugName(input: string): string {
+  return input
+    .toLowerCase()
+    .normalize('NFKD')
+    .replace(/[̀-ͯ]/g, '')
+    .replace(/[^a-z0-9]+/g, '_')
+    .replace(/^_+|_+$/g, '')
+    .slice(0, 40);
+}
+
+/** A submitted name for a row: the editor's `name` if usable, else one derived from the label. */
+export function fieldName(
+  raw: unknown,
+  label: string,
+  type: FieldType,
+  taken: Set<string>,
+): string {
+  let base = slugName(str(raw)) || slugName(label) || type;
+  if (!/^[a-z]/.test(base)) base = `f_${base}`;
+  if (base === 'phone') base = 'tel';
+  if (RESERVED_NAMES.has(base)) base = `${base}_field`;
+  let name = base;
+  for (let n = 2; taken.has(name); n++) name = `${base}_${n}`;
+  taken.add(name);
+  return name;
+}
+
+/** The HTML `autocomplete` token for a field, or undefined when there is no honest one. */
+export function autocompleteFor(name: string, type: FieldType): string | undefined {
+  if (type === 'email') return 'email';
+  if (type === 'tel') return 'tel';
+  if (type !== 'text') return undefined;
+  const map: Record<string, string> = {
+    name: 'name',
+    full_name: 'name',
+    your_name: 'name',
+    first_name: 'given-name',
+    given_name: 'given-name',
+    last_name: 'family-name',
+    family_name: 'family-name',
+    company: 'organization',
+    organization: 'organization',
+    organisation: 'organization',
+    postal_code: 'postal-code',
+    postcode: 'postal-code',
+    zip: 'postal-code',
+    city: 'address-level2',
+    address: 'street-address',
+  };
+  return map[name];
+}
+
+/** Editor rows to renderable fields. Rows with no label are dropped; at most {@link MAX_FIELDS}. */
+export function resolveFields(rows: Record<string, unknown>[]): FormField[] {
+  const taken = new Set<string>();
+  const out: FormField[] = [];
+  for (const row of rows) {
+    const label = str(row['label']);
+    if (!label) continue;
+    if (out.length >= MAX_FIELDS) break;
+    const rawType = str(row['type']);
+    const type = (FIELD_TYPES as readonly string[]).includes(rawType)
+      ? (rawType as FieldType)
+      : 'text';
+    const name = fieldName(row['name'], label, type, taken);
+    const options =
+      type === 'select'
+        ? str(row['options'])
+            .split('\n')
+            .map((o) => o.trim())
+            .filter(Boolean)
+        : [];
+    // A select with nothing to choose is unusable; render it as free text instead.
+    const effective: FieldType = type === 'select' && options.length === 0 ? 'text' : type;
+    out.push({
+      name,
+      id: `form-${out.length + 1}-${name}`,
+      label,
+      type: effective,
+      required: row['required'] === true,
+      placeholder:
+        effective === 'checkbox' || effective === 'select' ? '' : str(row['placeholder']),
+      help: str(row['help']),
+      options,
+      autocomplete: autocompleteFor(name, effective),
+    });
+  }
+  return out;
+}
+
+/**
+ * Where the endpoint may send a visitor back to: a same-site path, nothing else. The form
+ * posts its own page path as `_next`; the route that reads it must apply this too, or the
+ * field becomes an open redirect.
+ */
+export function safeNext(input: unknown): string | null {
+  const v = typeof input === 'string' ? input : '';
+  if (!v.startsWith('/') || v.startsWith('//') || v.includes('\\') || v.length > 200) return null;
+  // Control characters (and a query/fragment) are exactly what a redirect target must not carry.
+  // eslint-disable-next-line no-control-regex
+  if (/[\u0000-\u001f\u007f#?]/.test(v)) return null;
+  return v;
+}
+
+/** The endpoint a form posts to: a same-site path, defaulting to the conversion route. */
+export function safeAction(input: unknown): string {
+  return safeNext(input) ?? '/api/track';
+}

package/src/astro/blocks/head.stub.ts

@@ -0,0 +1,2 @@
+/** Test stand-in for `virtual:getvitops/head` (see vitest.container.config.ts). Mutable on purpose. */
+export default { turnstileSiteKey: null as string | null };

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

@@ -0,0 +1,51 @@
+import { describe, expect, it } from 'vite-plus/test';
+import { menuName, navDepth, navId, navLabel, navVariant } from './nav.ts';
+
+describe('menuName', () => {
+  it('accepts an EmDash menu slug', () => {
+    expect(menuName('footer-sitemap')).toBe('footer-sitemap');
+    expect(menuName(' primary ')).toBe('primary');
+  });
+
+  it('refuses anything that is not a slug, so it never reaches getMenu()', () => {
+    for (const bad of ['', '  ', '../x', 'a b', '<b>', 'a/b', '-lead', 'x'.repeat(65), 7, null])
+      expect(menuName(bad), String(bad)).toBeNull();
+  });
+});
+
+describe('navVariant / navDepth', () => {
+  it('falls back to a plain list and one level', () => {
+    expect(navVariant('nope')).toBe('list');
+    expect(navVariant(undefined)).toBe('list');
+    expect(navDepth(undefined)).toBe(1);
+    expect(navDepth('abc')).toBe(1);
+  });
+
+  it('keeps the four variants and clamps depth to 1-3', () => {
+    for (const v of ['list', 'inline', 'columns', 'sitenav']) expect(navVariant(v)).toBe(v);
+    expect([navDepth('2'), navDepth(3), navDepth('9'), navDepth(0)]).toEqual([2, 3, 3, 1]);
+  });
+});
+
+describe('navLabel: a unique landmark name', () => {
+  it('prefers the label, then the heading, then the menu label, then the name', () => {
+    expect(navLabel('Services', 'Heading', 'Menu label', 'm')).toBe('Services');
+    expect(navLabel('', 'Heading', 'Menu label', 'm')).toBe('Heading');
+    expect(navLabel('', '', 'Menu label', 'm')).toBe('Menu label');
+    expect(navLabel('', '', '', 'm')).toBe('m');
+  });
+
+  it('never repeats a name the header or footer landmark already carries', () => {
+    // <SiteNav> is "Primary"; <SiteFooter> is "Site map" and "Legal".
+    for (const taken of ['Primary', 'primary', 'Site map', 'Legal'])
+      expect(navLabel(taken, '', '', 'x')).toBe(`${taken} (this page)`);
+  });
+});
+
+describe('navId', () => {
+  it('is DOM-id safe and prefers the block key so two blocks of one menu stay apart', () => {
+    expect(navId('abc_123', 'primary')).toBe('navblock-abc-123');
+    expect(navId(undefined, 'Footer Sitemap')).toBe('navblock-footer-sitemap');
+    expect(navId('', '')).toBe('navblock-x');
+  });
+});

package/src/astro/blocks/nav.ts

@@ -0,0 +1,65 @@
+/**
+ * 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.
+ */
+
+export const NAV_VARIANTS = ['list', 'inline', 'columns', 'sitenav'] as const;
+export type NavVariant = (typeof NAV_VARIANTS)[number];
+
+/**
+ * An EmDash menu name is a slug. Anything else is refused before it reaches `getMenu()`, so a
+ * saved value can never be a path, a query or markup — and a block pointing at "nothing" is
+ * the same quiet no-op as one pointing at a menu that was deleted.
+ */
+export function menuName(input: unknown): string | null {
+  const name = typeof input === 'string' ? input.trim() : '';
+  return /^[a-z0-9][a-z0-9_-]{0,63}$/i.test(name) ? name : null;
+}
+
+export function navVariant(input: unknown): NavVariant {
+  return (NAV_VARIANTS as readonly string[]).includes(String(input))
+    ? (input as NavVariant)
+    : 'list';
+}
+
+/** 1–3 levels. A page-body nav that nests deeper is a site map, and wants its own page. */
+export function navDepth(input: unknown): 1 | 2 | 3 {
+  const n = Math.round(Number(input));
+  return n >= 3 ? 3 : n === 2 ? 2 : 1;
+}
+
+/**
+ * Names the header and footer landmarks already use. `<SiteNav>` is "Primary" and
+ * `<SiteFooter>` is "Site map" / "Legal"; a second `<nav aria-label="Primary">` in the page
+ * body would leave a screen-reader user a landmark list of identical entries.
+ */
+const TAKEN = new Set(['primary', 'site map', 'legal', 'main', 'navigation', 'menu']);
+
+/**
+ * The accessible name for the block's `<nav>`: the editor's `label`, else the visible
+ * `heading`, else the menu's own label, else its name. If that lands on one of the names the
+ * layout's header/footer already use, a distinguishing suffix is added rather than shipping
+ * two landmarks that read the same.
+ */
+export function navLabel(
+  label: unknown,
+  heading: unknown,
+  menuLabel: unknown,
+  name: string,
+): string {
+  const pick =
+    [label, heading, menuLabel, name]
+      .map((v) => (typeof v === 'string' ? v.trim() : ''))
+      .find(Boolean) ?? 'Links';
+  return TAKEN.has(pick.toLowerCase()) ? `${pick} (this page)` : pick;
+}
+
+/** A DOM-id-safe slug, used to keep two `sitenav`-variant blocks' drawer ids apart. */
+export function navId(key: unknown, name: string): string {
+  const slug = `${typeof key === 'string' && key ? key : name}`
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-|-$/g, '');
+  return `navblock-${slug || 'x'}`;
+}