@edoxen/browser 0.1.0

package/src/i18n/index.spec.ts

@@ -0,0 +1,121 @@
+import { describe, expect, it } from 'vitest'
+import type { LocalizedString } from '@edoxen/edoxen'
+
+import {
+  availableSpellings,
+  getLocaleFromUrl,
+  localizedHref,
+  pickLocalizedString,
+  pickLocalizedValue,
+  threeToTwo,
+  twoToThree,
+} from './index.js'
+
+function ls(spelling: string, value: string): LocalizedString {
+  return { spelling, value }
+}
+
+describe('twoToThree / threeToTwo', () => {
+  it('maps ISO 639-1 to ISO 639-3', () => {
+    expect(twoToThree('en')).toBe('eng')
+    expect(twoToThree('fr')).toBe('fra')
+  })
+
+  it('passes through unknown codes', () => {
+    expect(twoToThree('xx')).toBe('xx')
+    expect(threeToTwo('xxx')).toBe('xxx')
+  })
+
+  it('round-trips for known codes', () => {
+    expect(threeToTwo(twoToThree('en'))).toBe('en')
+  })
+})
+
+describe('pickLocalizedString', () => {
+  const list = [ls('eng', 'Hello'), ls('fra', 'Bonjour'), ls('zho-Hans', '你好')]
+
+  it('matches the exact 2-letter locale via the 3-letter mapping', () => {
+    expect(pickLocalizedString(list, 'en')?.value).toBe('Hello')
+  })
+
+  it('matches the exact 3-letter locale directly', () => {
+    expect(pickLocalizedString(list, 'fra')?.value).toBe('Bonjour')
+  })
+
+  it('matches language+script combinations', () => {
+    expect(pickLocalizedString(list, 'zh')?.value).toBe('你好')
+  })
+
+  it('falls back to the first entry when no match exists', () => {
+    expect(pickLocalizedString(list, 'ja')?.value).toBe('Hello')
+  })
+
+  it('returns null when the list is empty', () => {
+    expect(pickLocalizedString([], 'en')).toBeNull()
+    expect(pickLocalizedString(undefined, 'en')).toBeNull()
+  })
+})
+
+describe('pickLocalizedValue', () => {
+  it('returns the value, not the wrapper', () => {
+    expect(pickLocalizedValue([ls('eng', 'Hi')], 'en')).toBe('Hi')
+  })
+
+  it('falls back to the provided default', () => {
+    expect(pickLocalizedValue([], 'en', 'none')).toBe('none')
+  })
+})
+
+describe('availableSpellings', () => {
+  it('lists distinct spellings in stable order', () => {
+    expect(
+      availableSpellings([ls('fra', 'a'), ls('eng', 'b'), ls('fra', 'c')]),
+    ).toEqual(['eng', 'fra'])
+  })
+
+  it('omits empty spellings', () => {
+    expect(availableSpellings([ls('', 'x')])).toEqual([])
+  })
+})
+
+describe('getLocaleFromUrl', () => {
+  const locales = [
+    { code: 'en', routePrefix: '' },
+    { code: 'fr', routePrefix: '/fr' },
+    { code: 'de', routePrefix: '/de' },
+  ]
+
+  it('returns the default locale with no prefix for root paths', () => {
+    expect(getLocaleFromUrl('/', locales, 'en')).toEqual({ locale: 'en', prefix: '' })
+    expect(getLocaleFromUrl('/decisions/x', locales, 'en')).toEqual({ locale: 'en', prefix: '' })
+  })
+
+  it('detects the /fr prefix', () => {
+    expect(getLocaleFromUrl('/fr', locales, 'en')).toEqual({ locale: 'fr', prefix: '/fr' })
+    expect(getLocaleFromUrl('/fr/decisions/x', locales, 'en')).toEqual({ locale: 'fr', prefix: '/fr' })
+  })
+
+  it('handles prefix declared without leading slash', () => {
+    const locs = [{ code: 'fr', routePrefix: 'fr' }]
+    expect(getLocaleFromUrl('/fr/decisions', locs, 'en').locale).toBe('fr')
+  })
+})
+
+describe('localizedHref', () => {
+  const locales = [
+    { code: 'en', routePrefix: '' },
+    { code: 'fr', routePrefix: '/fr' },
+  ]
+
+  it('returns the href unchanged for the default locale', () => {
+    expect(localizedHref('/decisions/x', 'en', locales, 'en')).toBe('/decisions/x')
+  })
+
+  it('prefixes the href for non-default locales', () => {
+    expect(localizedHref('/decisions/x', 'fr', locales, 'en')).toBe('/fr/decisions/x')
+  })
+
+  it('handles hrefs without leading slash', () => {
+    expect(localizedHref('decisions', 'fr', locales, 'en')).toBe('/fr/decisions')
+  })
+})

package/src/i18n/index.ts

@@ -0,0 +1,90 @@
+import type { LocalizedString } from '@edoxen/edoxen'
+
+const TWO_TO_THREE: Readonly<Record<string, string>> = {
+  en: 'eng', fr: 'fra', de: 'deu', es: 'spa', it: 'ita',
+  ja: 'jpn', zh: 'zho', ko: 'kor', ru: 'rus', pt: 'por',
+  nl: 'nld', sv: 'swe', pl: 'pol', tr: 'tur', ar: 'ara',
+  he: 'heb', hi: 'hin',
+}
+
+const THREE_TO_TWO: Readonly<Record<string, string>> = Object.fromEntries(
+  Object.entries(TWO_TO_THREE).map(([two, three]) => [three, two]),
+)
+
+export function twoToThree(code: string): string {
+  return TWO_TO_THREE[code] ?? code
+}
+
+export function threeToTwo(code: string): string {
+  return THREE_TO_TWO[code] ?? code
+}
+
+export interface LocaleResolution {
+  readonly locale: string
+  readonly prefix: string
+}
+
+export function getLocaleFromUrl(
+  pathname: string,
+  locales: ReadonlyArray<{ code: string; routePrefix?: string }>,
+  defaultLocale: string,
+): LocaleResolution {
+  for (const entry of locales) {
+    const prefix = entry.routePrefix ?? ''
+    if (!prefix) continue
+    const normalized = prefix.startsWith('/') ? prefix : `/${prefix}`
+    if (pathname === normalized || pathname.startsWith(`${normalized}/`)) {
+      return { locale: entry.code, prefix: normalized }
+    }
+  }
+  return { locale: defaultLocale, prefix: '' }
+}
+
+export function localizedHref(
+  href: string,
+  locale: string,
+  locales: ReadonlyArray<{ code: string; routePrefix?: string }>,
+  defaultLocale: string,
+): string {
+  if (locale === defaultLocale) return href
+  const entry = locales.find((l) => l.code === locale)
+  const prefix = entry?.routePrefix ?? ''
+  if (!prefix) return href
+  const normalized = prefix.startsWith('/') ? prefix : `/${prefix}`
+  const slash = href.startsWith('/') ? '' : '/'
+  return `${normalized}${slash}${href}`
+}
+
+export function pickLocalizedString(
+  list: readonly LocalizedString[] | undefined,
+  locale: string,
+): LocalizedString | null {
+  if (!list || list.length === 0) return null
+
+  const norm = locale.toLowerCase()
+  const three = twoToThree(norm)
+
+  let hit = list.find((ls) => (ls.spelling ?? '').toLowerCase() === norm || (ls.spelling ?? '').toLowerCase() === three)
+  if (hit) return hit
+
+  hit = list.find((ls) => {
+    const sp = (ls.spelling ?? '').toLowerCase()
+    return sp.startsWith(`${norm}-`) || sp.startsWith(`${three}-`) || sp.startsWith(`${three}:`)
+  })
+  if (hit) return hit
+
+  return list[0] ?? null
+}
+
+export function pickLocalizedValue(
+  list: readonly LocalizedString[] | undefined,
+  locale: string,
+  fallback = '',
+): string {
+  return pickLocalizedString(list, locale)?.value ?? fallback
+}
+
+export function availableSpellings(list: readonly LocalizedString[] | undefined): readonly string[] {
+  if (!list) return []
+  return [...new Set(list.map((ls) => ls.spelling).filter((s): s is string => Boolean(s)))].sort()
+}

package/src/index.ts

@@ -0,0 +1,74 @@
+export {
+  EdoxenConfigSchema,
+  SiteSchema,
+  DataSchema,
+  OutputSchema,
+  BodySchema,
+  LocaleEntrySchema,
+  ThemeSchema,
+  NavItemSchema,
+  SocialItemSchema,
+  FeaturesSchema,
+  defineConfig,
+  resolveDataPaths,
+  activeDataKeys,
+  generateCssTokens,
+  type EdoxenConfig,
+  type EdoxenConfigInput,
+  type SiteConfig,
+  type DataConfig,
+  type OutputConfig,
+  type BodyEntry,
+  type LocaleEntry,
+  type ThemeConfig,
+  type NavItem,
+  type SocialItem,
+  type FeaturesConfig,
+  type ResolvedDataPaths,
+  type DataPathKey,
+} from './config/index.js'
+
+export {
+  loadAll,
+  validateAll,
+  buildProjectFromLoaded,
+  preparePayloads,
+  prepareDecisionsList,
+  prepareMeetingsList,
+  lintProject,
+  type LoadedData,
+  type LoadError,
+  type LoadResult,
+  type DataSource,
+  type ValidationReport,
+  type DecisionListItem,
+  type DecisionListPayload,
+  type DecisionListFacets,
+  type MeetingListItem,
+  type MeetingListPayload,
+  type MeetingListFacets,
+  type PagePayloads,
+  type LintReport,
+  type LintFinding,
+  type LintSeverity,
+} from './data/index.js'
+
+export {
+  decisionJsonLd,
+  decisionListItemJsonLd,
+  meetingJsonLd,
+  meetingListItemJsonLd,
+  type SeoContext,
+  type JsonLd,
+} from './seo/index.js'
+
+export {
+  pickLocalizedString,
+  pickLocalizedValue,
+  availableSpellings,
+  twoToThree,
+  threeToTwo,
+} from './i18n/index.js'
+
+export { EdoxenBrowserError, formatValidationErrors } from './errors.js'
+export { default as edoxenBrowser, type IntegrationOptions } from './integration.js'

package/src/integration.ts

@@ -0,0 +1,233 @@
+import type { AstroIntegration, AstroIntegrationLogger } from 'astro'
+import { mkdir, readFile, writeFile } from 'node:fs/promises'
+import { fileURLToPath } from 'node:url'
+import { extname } from 'node:path'
+
+import {
+  EdoxenConfigSchema,
+  type EdoxenConfig,
+  type EdoxenConfigInput,
+} from './config/index.js'
+import {
+  loadAll,
+  validateAll,
+  buildProjectFromLoaded,
+  preparePayloads,
+  type PagePayloads,
+} from './data/index.js'
+import { EdoxenBrowserError, formatValidationErrors } from './errors.js'
+
+export interface IntegrationOptions {
+  config: EdoxenConfigInput
+  injectRoutes?: boolean
+}
+
+const DEFAULT_ROUTE_PATTERNS: ReadonlyArray<readonly [string, string]> = [
+  ['/', 'index.astro'],
+  ['/decisions', 'decisions/index.astro'],
+  ['/decisions/[urn]', 'decisions/[urn].astro'],
+  ['/meetings', 'meetings/index.astro'],
+  ['/meetings/[urn]', 'meetings/[urn].astro'],
+  ['/about', 'about.astro'],
+  ['/404', '404.astro'],
+]
+
+const LOCALIZED_ROUTE_PATTERNS: ReadonlyArray<readonly [string, string]> = [
+  ['/[lang]', '[lang]/index.astro'],
+  ['/[lang]/decisions', '[lang]/decisions/index.astro'],
+  ['/[lang]/decisions/[urn]', '[lang]/decisions/[urn].astro'],
+  ['/[lang]/meetings', '[lang]/meetings/index.astro'],
+  ['/[lang]/meetings/[urn]', '[lang]/meetings/[urn].astro'],
+  ['/[lang]/about', '[lang]/about.astro'],
+]
+
+interface IntegrationCache {
+  readonly config: EdoxenConfig
+  readonly payloads: PagePayloads
+  readonly redirects: ReadonlyArray<readonly [string, string, AstroRedirectStatus]>
+}
+
+type AstroRedirectStatus = 300 | 301 | 302 | 303 | 304 | 307 | 308
+
+interface LegacyRedirect {
+  from: string
+  to: string
+  status?: AstroRedirectStatus
+}
+
+function normalizeRedirectStatus(n: number | undefined): AstroRedirectStatus {
+  const allowed: readonly number[] = [300, 301, 302, 303, 304, 307, 308]
+  return (allowed.includes(n ?? 301) ? n : 301) as AstroRedirectStatus
+}
+
+async function readRedirects(dataDir: string): Promise<LegacyRedirect[]> {
+  try {
+    const raw = await readFile(`${dataDir}/redirects.yaml`, 'utf8')
+    const { parse } = await import('yaml')
+    const parsed = parse(raw) as Array<{ from?: string; to?: string; status?: number }> | null
+    if (!Array.isArray(parsed)) return []
+    return parsed
+      .filter((r) => r && typeof r.from === 'string' && typeof r.to === 'string')
+      .map((r) => ({
+        from: r.from as string,
+        to: r.to as string,
+        status: normalizeRedirectStatus(r.status),
+      }))
+  } catch {
+    return []
+  }
+}
+
+async function buildCache(opts: IntegrationOptions, logger: AstroIntegrationLogger): Promise<IntegrationCache> {
+  const parseResult = EdoxenConfigSchema.safeParse(opts.config)
+  if (!parseResult.success) {
+    throw new EdoxenBrowserError(
+      'config',
+      'edoxen.config.ts failed schema validation',
+      parseResult.error.issues.map((i) => `${i.path.join('.') || '<root>'}: ${i.message}`),
+    )
+  }
+  const cfg = parseResult.data
+  logger.info(`Loading data from ${cfg.data.decisions}`)
+
+  const loaded = await loadAll(cfg.data)
+  if (!loaded.ok) {
+    throw new EdoxenBrowserError(
+      'load',
+      'Failed to load one or more data sources',
+      loaded.error.map((e) => `${e.source} (${e.path}): ${e.cause.message}`),
+    )
+  }
+
+  const report = await validateAll(loaded.value)
+  if (!report.valid) {
+    const details: string[] = []
+    if (report.decisions) details.push(...formatValidationErrors(report.decisions.errors))
+    if (report.meetings) details.push(...formatValidationErrors(report.meetings.errors))
+    throw new EdoxenBrowserError('validate', 'Schema validation failed for one or more data sources', details)
+  }
+
+  const project = buildProjectFromLoaded(loaded.value)
+  const payloads = preparePayloads(project)
+  const redirects = await readRedirects(cfg.data.decisions.replace(/\/[^/]+$/, ''))
+  logger.info(`Loaded ${project.decisions.length} decisions, ${project.meetings.length} meetings, ${redirects.length} redirects`)
+  return {
+    config: cfg,
+    payloads,
+    redirects: redirects.map((r) => [r.from, r.to, r.status ?? 301] as const),
+  }
+}
+
+const VIRTUAL_CONFIG = 'virtual:edoxen-config'
+const VIRTUAL_PAYLOADS = 'virtual:edoxen-payloads'
+
+function dataEndpointPayload(cache: IntegrationCache, name: 'decisions' | 'meetings'): string {
+  if (name === 'decisions') {
+    return JSON.stringify({
+      items: cache.payloads.decisionsList.items,
+      facetBodies: [...cache.payloads.decisionsList.facets.bodies],
+      facetKinds: [...cache.payloads.decisionsList.facets.kinds],
+      facetYears: [...cache.payloads.decisionsList.facets.years],
+    })
+  }
+  return JSON.stringify({
+    items: cache.payloads.meetingsList.items,
+    facetDecades: [...cache.payloads.meetingsList.facets.decades],
+    facetBodies: [...cache.payloads.meetingsList.facets.bodies],
+    facetCountries: [...cache.payloads.meetingsList.facets.countries],
+  })
+}
+
+function serveDataEndpoint(req: unknown, res: { setHeader: (k: string, v: string) => void; end: (s: string) => void; statusCode: number }, cache: IntegrationCache, name: 'decisions' | 'meetings'): void {
+  res.setHeader('Content-Type', 'application/json; charset=utf-8')
+  res.setHeader('Cache-Control', 'no-store')
+  res.end(dataEndpointPayload(cache, name))
+}
+
+export default function edoxenBrowser(opts: IntegrationOptions): AstroIntegration {
+  let cache: IntegrationCache | null = null
+  const injectRoutes = opts.injectRoutes ?? true
+  const pagesRoot = new URL('./astro/pages/', import.meta.url)
+
+  return {
+    name: '@edoxen/browser',
+    hooks: {
+      'astro:config:setup': async ({ logger, updateConfig, injectRoute }) => {
+        cache = await buildCache(opts, logger)
+
+        if (injectRoutes && injectRoute) {
+          for (const [pattern, file] of DEFAULT_ROUTE_PATTERNS) {
+            injectRoute({ pattern, entrypoint: new URL(file, pagesRoot) })
+          }
+          const nonDefaultLocales = cache.config.locales.filter((l) => (l.routePrefix ?? '') !== '')
+          if (nonDefaultLocales.length > 0) {
+            for (const [pattern, file] of LOCALIZED_ROUTE_PATTERNS) {
+              injectRoute({ pattern, entrypoint: new URL(file, pagesRoot) })
+            }
+          }
+        }
+
+        const redirectMap: Record<string, { status: AstroRedirectStatus; destination: string }> = {}
+        for (const [from, to, status] of cache.redirects) {
+          redirectMap[from] = { status, destination: to }
+        }
+
+        updateConfig({
+          redirects: redirectMap,
+          vite: {
+            plugins: [
+              {
+                name: 'edoxen-virtual-modules',
+                resolveId(id: string): string | null {
+                  if (id === VIRTUAL_CONFIG) return `\0${VIRTUAL_CONFIG}`
+                  if (id === VIRTUAL_PAYLOADS) return `\0${VIRTUAL_PAYLOADS}`
+                  return null
+                },
+                load(id: string): string | null {
+                  if (!cache) throw new EdoxenBrowserError('build', 'Integration cache not ready')
+                  if (id === `\0${VIRTUAL_CONFIG}`) {
+                    return `export default ${JSON.stringify(cache.config)}`
+                  }
+                  if (id === `\0${VIRTUAL_PAYLOADS}`) {
+                    return `export default ${JSON.stringify(cache.payloads)}`
+                  }
+                  return null
+                },
+                configureServer(server: { middlewares: { use: (handler: (req: unknown, res: unknown, next: () => void) => void) => void } }) {
+                  server.middlewares.use((req, res, next) => {
+                    if (!cache) {
+                      next()
+                      return
+                    }
+                    const url = (req as { url?: string }).url ?? ''
+                    if (url === '/data/decisions.json') {
+                      serveDataEndpoint(req, res as never, cache, 'decisions')
+                      return
+                    }
+                    if (url === '/data/meetings.json') {
+                      serveDataEndpoint(req, res as never, cache, 'meetings')
+                      return
+                    }
+                    next()
+                  })
+                },
+              },
+            ],
+          },
+        })
+      },
+
+      'astro:build:done': async ({ dir }: { dir: URL }) => {
+        if (!cache) return
+        const dataDir = new URL('data/', dir)
+        await mkdir(dataDir, { recursive: true })
+        await writeFile(new URL('decisions.json', dataDir), dataEndpointPayload(cache, 'decisions'))
+        await writeFile(new URL('meetings.json', dataDir), dataEndpointPayload(cache, 'meetings'))
+      },
+    },
+  }
+}
+
+export const playgroundDir = fileURLToPath(new URL('../', import.meta.url))
+export type { PagePayloads }
+export const acceptedExt = extname

package/src/islands/decade-scroller.ts

@@ -0,0 +1,18 @@
+class DecadeScroller extends HTMLElement {
+  connectedCallback(): void {
+    const links = this.querySelectorAll('a[href^="#decade-"]')
+    links.forEach((link) => {
+      link.addEventListener('click', (event) => {
+        const href = (event.currentTarget as HTMLAnchorElement).getAttribute('href')
+        if (!href) return
+        const target = document.querySelector(href)
+        if (!target) return
+        event.preventDefault()
+        target.scrollIntoView({ behavior: 'smooth', block: 'start' })
+        window.history.replaceState(null, '', href)
+      })
+    })
+  }
+}
+
+customElements.define('decade-scroller', DecadeScroller)

package/src/islands/print-button.ts

@@ -0,0 +1,12 @@
+class PrintButton extends HTMLElement {
+  connectedCallback(): void {
+    const btn = document.createElement('button')
+    btn.type = 'button'
+    btn.className = 'edoxen-print-button'
+    btn.textContent = this.dataset.label ?? 'Print'
+    btn.addEventListener('click', () => window.print())
+    this.appendChild(btn)
+  }
+}
+
+customElements.define('print-button', PrintButton)

package/src/islands/search-filter-core.spec.ts

@@ -0,0 +1,84 @@
+import { describe, expect, it } from 'vitest'
+
+import {
+  EMPTY_STATE,
+  countFacets,
+  decodeState,
+  encodeState,
+  filterItems,
+  toggle,
+  type SearchableItem,
+} from './search-filter-core.js'
+
+const items: SearchableItem[] = [
+  { urn: 'urn:a:1', title: 'First decision', bodyType: 'ciml', kind: 'resolution', year: 2024 },
+  { urn: 'urn:a:2', title: 'Second decision', bodyType: 'ciml', kind: 'recommendation', year: 2023 },
+  { urn: 'urn:b:1', title: 'Other body decision', bodyType: 'conference', kind: 'resolution', year: 2024 },
+]
+
+describe('filterItems', () => {
+  it('returns everything with an empty state', () => {
+    expect(filterItems(items, EMPTY_STATE).length).toBe(3)
+  })
+
+  it('filters by substring query against title + urn', () => {
+    expect(filterItems(items, { ...EMPTY_STATE, query: 'first' }).map((i) => i.urn)).toEqual(['urn:a:1'])
+    expect(filterItems(items, { ...EMPTY_STATE, query: 'urn:b' }).map((i) => i.urn)).toEqual(['urn:b:1'])
+  })
+
+  it('filters by body', () => {
+    const state = { ...EMPTY_STATE, bodies: new Set(['ciml']) }
+    expect(filterItems(items, state).length).toBe(2)
+  })
+
+  it('combines query + body filters', () => {
+    const state = { ...EMPTY_STATE, query: 'decision', bodies: new Set(['conference']) }
+    expect(filterItems(items, state).map((i) => i.urn)).toEqual(['urn:b:1'])
+  })
+
+  it('is case-insensitive on the query', () => {
+    expect(filterItems(items, { ...EMPTY_STATE, query: 'FIRST' }).map((i) => i.urn)).toEqual(['urn:a:1'])
+  })
+})
+
+describe('countFacets', () => {
+  it('counts distinct bodies, kinds, years', () => {
+    const facets = countFacets(items)
+    expect(facets.bodies.get('ciml')).toBe(2)
+    expect(facets.bodies.get('conference')).toBe(1)
+    expect(facets.kinds.get('resolution')).toBe(2)
+    expect(facets.years.get(2024)).toBe(2)
+  })
+})
+
+describe('toggle', () => {
+  it('adds then removes a key', () => {
+    const s1 = toggle(new Set<string>(), 'a')
+    expect([...s1]).toEqual(['a'])
+    const s2 = toggle(s1, 'a')
+    expect([...s2]).toEqual([])
+  })
+})
+
+describe('encodeState / decodeState', () => {
+  it('round-trips a complex state through URL hash', () => {
+    const state = {
+      query: 'publishes',
+      bodies: new Set(['ciml', 'conference']),
+      kinds: new Set(['resolution']),
+      years: new Set([2023, 2024]),
+    }
+    const hash = encodeState(state)
+    const restored = decodeState(hash)
+    expect(restored.query).toBe(state.query)
+    expect([...restored.bodies].sort()).toEqual(['ciml', 'conference'])
+    expect([...restored.kinds]).toEqual(['resolution'])
+    expect([...restored.years].sort()).toEqual([2023, 2024])
+  })
+
+  it('returns empty state for empty hash', () => {
+    const restored = decodeState('')
+    expect(restored.query).toBe('')
+    expect(restored.bodies.size).toBe(0)
+  })
+})