@edoxen/browser 0.1.0

package/src/config/paths.spec.ts

@@ -0,0 +1,59 @@
+import { describe, expect, it } from 'vitest'
+
+import { activeDataKeys, resolveDataPaths } from './paths.js'
+import type { DataConfig } from './schema.js'
+
+function cfg(data: DataConfig): DataConfig {
+  return data
+}
+
+describe('resolveDataPaths', () => {
+  it('returns decisions plus null for omitted entities', () => {
+    const paths = resolveDataPaths(cfg({ decisions: './data/decisions' }))
+    expect(paths).toEqual({
+      decisions: './data/decisions',
+      meetings: null,
+      agendas: null,
+      minutes: null,
+      committee: null,
+    })
+  })
+
+  it('preserves every provided entity path', () => {
+    const paths = resolveDataPaths(cfg({
+      decisions: './data/decisions',
+      meetings: './data/meetings',
+      agendas: './data/agendas',
+      minutes: './data/minutes',
+      committee: './data/committee.yaml',
+    }))
+    expect(paths.committee).toBe('./data/committee.yaml')
+    expect(paths.minutes).toBe('./data/minutes')
+  })
+})
+
+describe('activeDataKeys', () => {
+  it('lists only keys that have a path', () => {
+    expect(activeDataKeys(cfg({ decisions: './data/decisions' }))).toEqual(['decisions'])
+  })
+
+  it('lists every key when all are present, in canonical order', () => {
+    const keys = activeDataKeys(cfg({
+      decisions: './d',
+      meetings: './m',
+      agendas: './a',
+      minutes: './min',
+      committee: './c.yaml',
+    }))
+    expect(keys).toEqual(['decisions', 'meetings', 'agendas', 'minutes', 'committee'])
+  })
+
+  it('keeps stable order regardless of object key order', () => {
+    const keys = activeDataKeys(cfg({
+      committee: './c.yaml',
+      decisions: './d',
+      meetings: './m',
+    }))
+    expect(keys).toEqual(['decisions', 'meetings', 'committee'])
+  })
+})

package/src/config/paths.ts

@@ -0,0 +1,26 @@
+import type { DataConfig } from './schema.js'
+
+export interface ResolvedDataPaths {
+  readonly decisions: string
+  readonly meetings: string | null
+  readonly agendas: string | null
+  readonly minutes: string | null
+  readonly committee: string | null
+}
+
+const KEYS = ['decisions', 'meetings', 'agendas', 'minutes', 'committee'] as const
+export type DataPathKey = (typeof KEYS)[number]
+
+export function resolveDataPaths(data: DataConfig): ResolvedDataPaths {
+  return {
+    decisions: data.decisions,
+    meetings: data.meetings ?? null,
+    agendas: data.agendas ?? null,
+    minutes: data.minutes ?? null,
+    committee: data.committee ?? null,
+  }
+}
+
+export function activeDataKeys(data: DataConfig): readonly DataPathKey[] {
+  return KEYS.filter((k) => data[k] !== undefined)
+}

package/src/config/schema.spec.ts

@@ -0,0 +1,263 @@
+import { describe, expect, it } from 'vitest'
+
+import {
+  BodySchema,
+  EdoxenConfigSchema,
+  FeaturesSchema,
+  LocaleEntrySchema,
+  NavItemSchema,
+  SocialItemSchema,
+  defineConfig,
+} from './schema.js'
+
+describe('EdoxenConfigSchema', () => {
+  describe('site', () => {
+    it('accepts a minimal config and applies defaults', () => {
+      const cfg = EdoxenConfigSchema.parse({
+        site: { title: 'X', url: 'https://x.org' },
+        data: { decisions: './data/decisions' },
+      })
+
+      expect(cfg.site.title).toBe('X')
+      expect(cfg.site.description).toBe('')
+      expect(cfg.site.basePath).toBe('/')
+      expect(cfg.site.locale).toBe('en')
+    })
+
+    it('rejects an empty title', () => {
+      expect(() =>
+        EdoxenConfigSchema.parse({
+          site: { title: '', url: 'https://x.org' },
+          data: { decisions: './data/decisions' },
+        }),
+      ).toThrow()
+    })
+
+    it('rejects an invalid URL', () => {
+      expect(() =>
+        EdoxenConfigSchema.parse({
+          site: { title: 'X', url: 'bad' },
+          data: { decisions: './data/decisions' },
+        }),
+      ).toThrow()
+    })
+
+    it('rejects a malformed basePath', () => {
+      expect(() =>
+        EdoxenConfigSchema.parse({
+          site: { title: 'X', url: 'https://x.org', basePath: 'resolutions' },
+          data: { decisions: './data/decisions' },
+        }),
+      ).toThrow()
+    })
+
+    it('rejects a non-ISO-639 locale', () => {
+      expect(() =>
+        EdoxenConfigSchema.parse({
+          site: { title: 'X', url: 'https://x.org', locale: 'english' },
+          data: { decisions: './data/decisions' },
+        }),
+      ).toThrow()
+    })
+  })
+
+  describe('data', () => {
+    it('requires decisions path; other entities optional', () => {
+      const cfg = EdoxenConfigSchema.parse({
+        site: { title: 'X', url: 'https://x.org' },
+        data: { decisions: './data/decisions' },
+      })
+      expect(cfg.data.decisions).toBe('./data/decisions')
+      expect(cfg.data.meetings).toBeUndefined()
+    })
+
+    it('accepts all entity paths', () => {
+      const cfg = EdoxenConfigSchema.parse({
+        site: { title: 'X', url: 'https://x.org' },
+        data: {
+          decisions: './data/decisions',
+          meetings: './data/meetings',
+          agendas: './data/agendas',
+          minutes: './data/minutes',
+          committee: './data/committee.yaml',
+        },
+      })
+      expect(cfg.data.committee).toBe('./data/committee.yaml')
+    })
+
+    it('rejects config without decisions path', () => {
+      expect(() =>
+        EdoxenConfigSchema.parse({
+          site: { title: 'X', url: 'https://x.org' },
+          data: {},
+        }),
+      ).toThrow()
+    })
+  })
+
+  describe('bodies', () => {
+    it('defaults to a single committee body', () => {
+      const cfg = EdoxenConfigSchema.parse({
+        site: { title: 'X', url: 'https://x.org' },
+        data: { decisions: './data/decisions' },
+      })
+      expect(cfg.bodies).toEqual([{ code: 'committee', name: 'Committee' }])
+    })
+
+    it('accepts OIML-style multi-body with colors', () => {
+      const cfg = EdoxenConfigSchema.parse({
+        site: { title: 'X', url: 'https://x.org' },
+        data: { decisions: './data/decisions' },
+        bodies: [
+          { code: 'ciml', name: 'CIML', color: '#1e40af', textColor: '#ffffff' },
+          { code: 'conference', name: 'Conference', color: '#7c2d12' },
+        ],
+      })
+      expect(cfg.bodies[0]?.code).toBe('ciml')
+      expect(cfg.bodies[1]?.color).toBe('#7c2d12')
+    })
+
+    it('rejects an invalid body code', () => {
+      expect(() =>
+        BodySchema.parse({ code: 'CIML', name: 'CIML' }),
+      ).toThrow()
+    })
+
+    it('rejects a non-hex color', () => {
+      expect(() =>
+        BodySchema.parse({ code: 'ciml', name: 'CIML', color: 'blue' }),
+      ).toThrow()
+    })
+  })
+
+  describe('locales', () => {
+    it('defaults to a single English locale', () => {
+      const cfg = EdoxenConfigSchema.parse({
+        site: { title: 'X', url: 'https://x.org' },
+        data: { decisions: './data/decisions' },
+      })
+      expect(cfg.locales).toEqual([{ code: 'en', label: 'English', routePrefix: '' }])
+    })
+
+    it('accepts bilingual EN/FR with route prefix', () => {
+      const cfg = EdoxenConfigSchema.parse({
+        site: { title: 'X', url: 'https://x.org' },
+        data: { decisions: './data/decisions' },
+        locales: [
+          { code: 'en', label: 'English' },
+          { code: 'fr', label: 'Français', routePrefix: '/fr' },
+        ],
+      })
+      expect(cfg.locales[1]?.routePrefix).toBe('/fr')
+    })
+
+    it('rejects a 4-letter locale code', () => {
+      expect(() => LocaleEntrySchema.parse({ code: 'eng1', label: 'X' })).toThrow()
+    })
+  })
+
+  describe('theme', () => {
+    it('applies full defaults when omitted', () => {
+      const cfg = EdoxenConfigSchema.parse({
+        site: { title: 'X', url: 'https://x.org' },
+        data: { decisions: './data/decisions' },
+      })
+      expect(cfg.theme.primary).toBe('#1f2937')
+      expect(cfg.theme.dark.surface).toBe('#1f2937')
+      expect(cfg.theme.radius).toBe('0.25rem')
+    })
+
+    it('rejects a non-hex theme color', () => {
+      const cfg = {
+        site: { title: 'X', url: 'https://x.org' },
+        data: { decisions: './data/decisions' },
+        theme: { primary: 'red' },
+      }
+      expect(() => EdoxenConfigSchema.parse(cfg)).toThrow()
+    })
+
+    it('accepts custom properties for consumer overrides', () => {
+      const cfg = EdoxenConfigSchema.parse({
+        site: { title: 'X', url: 'https://x.org' },
+        data: { decisions: './data/decisions' },
+        theme: { customProperties: { 'font-display': 'Inter, sans-serif' } },
+      })
+      expect(cfg.theme.customProperties['font-display']).toBe('Inter, sans-serif')
+    })
+  })
+
+  describe('nav', () => {
+    it('rejects an href that is not absolute or http(s)/mailto', () => {
+      expect(() =>
+        NavItemSchema.parse({ label: 'Home', href: 'relative/path' }),
+      ).toThrow()
+    })
+
+    it('accepts absolute path, http, https, and mailto', () => {
+      expect(NavItemSchema.parse({ label: 'A', href: '/' }).href).toBe('/')
+      expect(NavItemSchema.parse({ label: 'B', href: '/decisions' }).href).toBe('/decisions')
+      expect(NavItemSchema.parse({ label: 'C', href: 'https://example.org' }).href).toBe('https://example.org')
+      expect(NavItemSchema.parse({ label: 'D', href: 'mailto:x@y.org' }).href).toBe('mailto:x@y.org')
+    })
+  })
+
+  describe('social', () => {
+    it('accepts a known icon enum', () => {
+      expect(SocialItemSchema.parse({ label: 'GH', href: 'https://gh.org', icon: 'github' }).icon).toBe('github')
+    })
+
+    it('rejects an unknown icon', () => {
+      expect(() =>
+        SocialItemSchema.parse({ label: 'X', href: 'https://x.org', icon: 'myspace' }),
+      ).toThrow()
+    })
+
+    it('rejects a non-URL href', () => {
+      expect(() =>
+        SocialItemSchema.parse({ label: 'X', href: '/relative' }),
+      ).toThrow()
+    })
+  })
+
+  describe('features', () => {
+    it('applies defaults', () => {
+      const f = FeaturesSchema.parse({})
+      expect(f.search).toBe(true)
+      expect(f.doi).toBe(false)
+      expect(f.pagination.enabled).toBe(false)
+      expect(f.pagination.pageSize).toBe(50)
+    })
+
+    it('accepts pagination override', () => {
+      const f = FeaturesSchema.parse({ pagination: { enabled: true, pageSize: 100 } })
+      expect(f.pagination.pageSize).toBe(100)
+    })
+
+    it('rejects a non-positive page size', () => {
+      expect(() =>
+        FeaturesSchema.parse({ pagination: { enabled: true, pageSize: 0 } }),
+      ).toThrow()
+    })
+  })
+
+  describe('defineConfig', () => {
+    it('returns a parsed config with defaults filled in', () => {
+      const cfg = defineConfig({
+        site: { title: 'My Site', url: 'https://mine.org' },
+        data: { decisions: './data/decisions' },
+      })
+      expect(cfg.site.title).toBe('My Site')
+      expect(cfg.site.locale).toBe('en')
+      expect(cfg.features.search).toBe(true)
+    })
+
+    it('throws on invalid input with a ZodError', () => {
+      expect(() =>
+        EdoxenConfigSchema.parse({
+          site: { title: 'X' },
+          data: { decisions: './data/decisions' },
+        }),
+      ).toThrow()
+    })
+  })
+})

package/src/config/schema.ts

@@ -0,0 +1,132 @@
+import { z } from 'zod'
+
+// Validation patterns. Centralised so call sites stay DRY and the rules
+// can be swapped for `@iso24229/iso639-data` lookups when that package
+// publishes (see TODO.browser/25-audit-and-improvements.md §7.5).
+const LOCALE_RE = /^[a-z]{2,3}$/
+const SCRIPT_RE = /^[A-Z][a-z]{3}$/
+const HEX_RE = /^#[0-9a-fA-F]{3,8}$/
+const BODY_CODE_RE = /^[a-z][a-z0-9_-]*$/
+const HREF_RE = /^(\/[^/]*|https?:|mailto:)/
+const PATH_RE = /.+/
+
+export const SiteSchema = z.object({
+  title: z.string().min(1),
+  description: z.string().default(''),
+  url: z.string().url(),
+  basePath: z.string().regex(/^\/.*\/$|^\/$/, 'must be a root "/" or "/path/"').default('/'),
+  locale: z.string().regex(LOCALE_RE, 'must be an ISO 639-1/3 code').default('en'),
+})
+export type SiteConfig = z.infer<typeof SiteSchema>
+
+export const DataSchema = z.object({
+  decisions: z.string().regex(PATH_RE),
+  meetings: z.string().regex(PATH_RE).optional(),
+  agendas: z.string().regex(PATH_RE).optional(),
+  minutes: z.string().regex(PATH_RE).optional(),
+  committee: z.string().regex(PATH_RE).optional(),
+})
+export type DataConfig = z.infer<typeof DataSchema>
+
+export const OutputSchema = z.object({
+  dir: z.string().default('./dist'),
+  sitemap: z.boolean().default(true),
+  robots: z.boolean().default(true),
+})
+export type OutputConfig = z.infer<typeof OutputSchema>
+
+export const BodySchema = z.object({
+  code: z.string().regex(BODY_CODE_RE, 'lowercase letters, digits, _ or -'),
+  name: z.string().min(1),
+  color: z.string().regex(HEX_RE).optional(),
+  textColor: z.string().regex(HEX_RE).optional(),
+  icon: z.string().optional(),
+})
+export type BodyEntry = z.infer<typeof BodySchema>
+
+export const LocaleEntrySchema = z.object({
+  code: z.string().regex(LOCALE_RE, 'must be an ISO 639-1/3 code'),
+  label: z.string().min(1),
+  routePrefix: z.string().default(''),
+})
+export type LocaleEntry = z.infer<typeof LocaleEntrySchema>
+
+const colorFields = z.string().regex(HEX_RE)
+
+export const ThemeSchema = z.object({
+  primary: colorFields.default('#1f2937'),
+  accent: colorFields.default('#3b82f6'),
+  surface: colorFields.default('#ffffff'),
+  background: colorFields.default('#f9fafb'),
+  text: colorFields.default('#1f2937'),
+  muted: colorFields.default('#6b7280'),
+  border: colorFields.default('#e5e7eb'),
+  success: colorFields.default('#10b981'),
+  warning: colorFields.default('#f59e0b'),
+  danger: colorFields.default('#ef4444'),
+  dark: z.object({
+    primary: colorFields.default('#f9fafb'),
+    accent: colorFields.default('#3b82f6'),
+    surface: colorFields.default('#1f2937'),
+    background: colorFields.default('#111827'),
+    text: colorFields.default('#f9fafb'),
+    muted: colorFields.default('#9ca3af'),
+    border: colorFields.default('#374151'),
+  }).default({}),
+  logos: z.object({
+    primary: z.string().optional(),
+    footer: z.string().optional(),
+    favicon: z.string().optional(),
+  }).default({}),
+  fontFamily: z.string().optional(),
+  radius: z.string().default('0.25rem'),
+  customProperties: z.record(z.string()).default({}),
+})
+export type ThemeConfig = z.infer<typeof ThemeSchema>
+
+export const NavItemSchema = z.object({
+  label: z.string().min(1),
+  href: z.string().regex(HREF_RE, 'must start with "/", "http:", "https:", or "mailto:"'),
+  locale: z.string().regex(LOCALE_RE).optional(),
+})
+export type NavItem = z.infer<typeof NavItemSchema>
+
+export const SocialItemSchema = z.object({
+  label: z.string().min(1),
+  href: z.string().url(),
+  icon: z.enum(['github', 'email', 'linkedin', 'twitter', 'website', 'rss']).optional(),
+})
+export type SocialItem = z.infer<typeof SocialItemSchema>
+
+export const FeaturesSchema = z.object({
+  search: z.boolean().default(true),
+  timeline: z.boolean().default(true),
+  urnCopy: z.boolean().default(true),
+  doi: z.boolean().default(false),
+  darkMode: z.boolean().default(true),
+  printStyles: z.boolean().default(true),
+  pagination: z.object({
+    enabled: z.boolean().default(false),
+    pageSize: z.number().int().positive().default(50),
+  }).default({}),
+})
+export type FeaturesConfig = z.infer<typeof FeaturesSchema>
+
+export const EdoxenConfigSchema = z.object({
+  site: SiteSchema,
+  data: DataSchema,
+  output: OutputSchema.default({}),
+  bodies: z.array(BodySchema).default([{ code: 'committee', name: 'Committee' }]),
+  locales: z.array(LocaleEntrySchema).default([{ code: 'en', label: 'English', routePrefix: '' }]),
+  theme: ThemeSchema.default({}),
+  nav: z.array(NavItemSchema).default([]),
+  social: z.array(SocialItemSchema).default([]),
+  features: FeaturesSchema.default({}),
+})
+
+export type EdoxenConfig = z.infer<typeof EdoxenConfigSchema>
+export type EdoxenConfigInput = z.input<typeof EdoxenConfigSchema>
+
+export function defineConfig(config: EdoxenConfigInput): EdoxenConfig {
+  return EdoxenConfigSchema.parse(config)
+}

package/src/config/tokens.spec.ts

@@ -0,0 +1,57 @@
+import { describe, expect, it } from 'vitest'
+
+import { generateCssTokens } from './tokens.js'
+import { ThemeSchema } from './schema.js'
+
+function parseTheme(input: Record<string, unknown>) {
+  return ThemeSchema.parse(input)
+}
+
+describe('generateCssTokens', () => {
+  it('emits a :root block with every default color token', () => {
+    const theme = parseTheme({})
+    const css = generateCssTokens(theme)
+    expect(css).toContain(':root {')
+    expect(css).toContain('--edoxen-color-primary: #1f2937;')
+    expect(css).toContain('--edoxen-color-accent: #3b82f6;')
+    expect(css).toContain('--edoxen-color-success: #10b981;')
+    expect(css).toContain('--edoxen-radius-sm: 0.25rem;')
+  })
+
+  it('does not double-emit radius as a color', () => {
+    const theme = parseTheme({})
+    const css = generateCssTokens(theme)
+    expect(css).not.toContain('--edoxen-color-radius')
+    expect(css).not.toContain('--edoxen-color-font-family')
+  })
+
+  it('emits font-family token under --edoxen-font-sans', () => {
+    const theme = parseTheme({ fontFamily: 'Inter, sans-serif' })
+    expect(generateCssTokens(theme)).toContain('--edoxen-font-sans: Inter, sans-serif;')
+  })
+
+  it('emits dark-mode tokens under [data-theme="dark"]', () => {
+    const theme = parseTheme({})
+    const css = generateCssTokens(theme)
+    expect(css).toContain(':root[data-theme="dark"] { --edoxen-color-surface: #1f2937; }')
+    expect(css).toContain(':root[data-theme="dark"] { --edoxen-color-background: #111827; }')
+  })
+
+  it('reflects consumer overrides', () => {
+    const theme = parseTheme({ primary: '#ff0000' })
+    expect(generateCssTokens(theme)).toContain('--edoxen-color-primary: #ff0000;')
+  })
+
+  it('emits custom properties as --edoxen-* kebab-case tokens', () => {
+    const theme = parseTheme({ customProperties: { fontDisplay: 'Inter', 'hero-size': '4rem' } })
+    const css = generateCssTokens(theme)
+    expect(css).toContain('--edoxen-font-display: Inter;')
+    expect(css).toContain('--edoxen-hero-size: 4rem;')
+  })
+
+  it('skips nested object fields from the root :root block', () => {
+    const theme = parseTheme({})
+    const css = generateCssTokens(theme)
+    expect(css).not.toContain('[object Object]')
+  })
+})

package/src/config/tokens.ts

@@ -0,0 +1,48 @@
+import type { ThemeConfig } from './schema.js'
+
+const TOKEN_NAME_OVERRIDES: Record<string, string | null> = {
+  customProperties: null,
+  logos: null,
+  dark: null,
+  fontFamily: '--edoxen-font-sans',
+  radius: '--edoxen-radius-sm',
+}
+
+function tokenName(key: string): string | null {
+  const override = TOKEN_NAME_OVERRIDES[key]
+  if (override === null) return null
+  if (override) return override
+  return `--edoxen-color-${kebab(key)}`
+}
+
+function kebab(s: string): string {
+  return s.replace(/([a-z0-9])([A-Z])/g, '$1-$2').toLowerCase()
+}
+
+export function generateCssTokens(theme: ThemeConfig): string {
+  const lines: string[] = [':root {']
+
+  for (const [key, value] of Object.entries(theme)) {
+    if (typeof value !== 'string') continue
+    const name = tokenName(key)
+    if (name) lines.push(`  ${name}: ${value};`)
+  }
+
+  lines.push('}')
+
+  for (const [key, value] of Object.entries(theme.dark)) {
+    if (typeof value !== 'string') continue
+    const name = tokenName(key)
+    if (name) lines.push(`:root[data-theme="dark"] { ${name}: ${value}; }`)
+  }
+
+  if (theme.customProperties && Object.keys(theme.customProperties).length > 0) {
+    lines.push(':root {')
+    for (const [k, v] of Object.entries(theme.customProperties)) {
+      lines.push(`  --edoxen-${kebab(k)}: ${v};`)
+    }
+    lines.push('}')
+  }
+
+  return lines.join('\n')
+}

package/src/data/index.ts

@@ -0,0 +1,36 @@
+export {
+  loadAll,
+  type LoadedData,
+  type LoadError,
+  type LoadResult,
+  type DataSource,
+} from './load.js'
+
+export {
+  validateAll,
+  type ValidationReport,
+} from './validate.js'
+
+export {
+  buildProjectFromLoaded,
+} from './project.js'
+
+export {
+  preparePayloads,
+  prepareDecisionsList,
+  prepareMeetingsList,
+  type DecisionListItem,
+  type DecisionListPayload,
+  type DecisionListFacets,
+  type MeetingListItem,
+  type MeetingListPayload,
+  type MeetingListFacets,
+  type PagePayloads,
+} from './prepare.js'
+
+export {
+  lintProject,
+  type LintReport,
+  type LintFinding,
+  type LintSeverity,
+} from './lint.js'