@kamod-ch/preactpress 1.0.0

package/src/shared/locale.ts

@@ -0,0 +1,116 @@
+import type {
+  LocaleConfig,
+  ResolvedI18n,
+  ResolvedLocale,
+  SiteData,
+  ThemeConfig
+} from '../node/siteConfig.js'
+import { normalizeRoute } from './route.js'
+
+export function resolveLocales(
+  userLocales: Record<string, LocaleConfig> | undefined,
+  site: SiteData,
+  themeConfig: ThemeConfig
+): ResolvedI18n | undefined {
+  const entries = Object.entries(userLocales ?? {})
+  if (entries.length === 0) return undefined
+
+  const defaultLocaleKey = userLocales?.root ? 'root' : entries[0][0]
+  const locales = entries.map(([key, locale]) => {
+    const prefix = localePrefixForKey(key)
+    const link = locale.link ?? `${prefix || ''}/`
+    const lang = locale.lang ?? (key === 'root' ? site.lang : key)
+    const localeSite = {
+      ...site,
+      title: locale.title ?? site.title,
+      description: locale.description ?? site.description,
+      lang
+    }
+
+    return {
+      key,
+      label: locale.label,
+      lang,
+      link,
+      prefix,
+      site: localeSite,
+      themeConfig: {
+        ...themeConfig,
+        ...(locale.themeConfig ?? {})
+      }
+    }
+  })
+
+  return { defaultLocaleKey, locales }
+}
+
+export function localePrefixForKey(key: string): string {
+  return key === 'root' ? '' : normalizeRoute(`/${key}`)
+}
+
+export function localeFromRoute(
+  route: string,
+  i18n: ResolvedI18n | undefined
+): ResolvedLocale | undefined {
+  if (!i18n) return undefined
+  const normalized = normalizeRoute(route)
+  const prefixed = [...i18n.locales]
+    .filter((locale) => locale.prefix)
+    .sort((a, b) => b.prefix.length - a.prefix.length)
+  const match = prefixed.find(
+    (locale) => normalized === locale.prefix || normalized.startsWith(`${locale.prefix}/`)
+  )
+  if (match) return match
+  return i18n.locales.find((locale) => locale.key === i18n.defaultLocaleKey) ?? i18n.locales[0]
+}
+
+export function stripLocalePrefix(route: string, locale: ResolvedLocale | undefined): string {
+  const normalized = normalizeRoute(route)
+  if (!locale?.prefix) return normalized
+  if (normalized === locale.prefix) return '/'
+  if (normalized.startsWith(`${locale.prefix}/`)) {
+    return normalizeRoute(normalized.slice(locale.prefix.length))
+  }
+  return normalized
+}
+
+export function routePathKey(route: string, i18n: ResolvedI18n | undefined): string {
+  return stripLocalePrefix(route, localeFromRoute(route, i18n))
+}
+
+export function localizeRoute(pathKey: string, locale: ResolvedLocale): string {
+  const normalized = normalizeRoute(pathKey)
+  if (!locale.prefix) return normalized
+  return normalized === '/' ? locale.prefix : normalizeRoute(`${locale.prefix}${normalized}`)
+}
+
+export function localizedRouteForLocale(
+  route: string,
+  targetLocale: ResolvedLocale,
+  i18n: ResolvedI18n | undefined,
+  availableRoutes?: ReadonlySet<string>
+): string {
+  const pathKey = routePathKey(route, i18n)
+  const localized = localizeRoute(pathKey, targetLocale)
+  if (!availableRoutes || availableRoutes.has(localized)) return localized
+  return normalizeRoute(targetLocale.link)
+}
+
+export function siteForRoute(
+  site: SiteData,
+  route: string,
+  i18n: ResolvedI18n | undefined
+): SiteData {
+  const localeSite = localeFromRoute(route, i18n)?.site
+  if (!localeSite) return site
+  // `base` is a deployment setting; locale copies are resolved before CLI overrides.
+  return { ...localeSite, base: site.base }
+}
+
+export function themeConfigForRoute(
+  themeConfig: ThemeConfig,
+  route: string,
+  i18n: ResolvedI18n | undefined
+): ThemeConfig {
+  return localeFromRoute(route, i18n)?.themeConfig ?? themeConfig
+}

package/src/shared/pageChrome.ts

@@ -0,0 +1,244 @@
+import { pageLayoutFromMeta, type PageLayout } from './pageMeta.js'
+
+export type PageAside = boolean | 'left'
+export type PageOutlineConfig = number | [number, number] | 'deep' | false
+export type PageOutlineLevels = [number, number] | false
+
+export type ThemeableImage =
+  | string
+  | { src: string; alt?: string }
+  | { light: string; dark: string; alt?: string }
+
+export interface HeroAction {
+  theme: 'brand' | 'alt'
+  text: string
+  link: string
+  target?: string
+  rel?: string
+}
+
+export interface Hero {
+  name?: string
+  text?: string
+  tagline?: string
+  image?: ThemeableImage
+  actions: HeroAction[]
+}
+
+export type FeatureIcon =
+  | string
+  | { src: string; alt?: string; width?: string; height?: string }
+  | { light: string; dark: string; alt?: string; width?: string; height?: string }
+
+export interface Feature {
+  icon?: FeatureIcon
+  title: string
+  details: string
+  link?: string
+  linkText?: string
+  rel?: string
+  target?: string
+}
+
+export interface PageChromeThemeConfig {
+  outline?: boolean | PageOutlineConfig
+  footer?: string
+  editLink?: unknown
+  lastUpdated?: boolean
+}
+
+export interface ResolvedPageChrome {
+  layout: PageLayout
+  isHome: boolean
+  showNavbar: boolean
+  showSidebar: boolean
+  aside: PageAside
+  showAside: boolean
+  outlineLevels: PageOutlineLevels
+  showPager: boolean
+  showFooter: boolean
+  showEditLink: boolean
+  showLastUpdated: boolean
+  pageClass?: string
+  markdownStyles: boolean
+  hero?: Hero
+  features: Feature[]
+}
+
+export interface OutlineHeading {
+  id: string
+  text: string
+  level: number
+}
+
+export function resolvePageChrome(
+  meta: Record<string, unknown> | undefined,
+  themeConfig: PageChromeThemeConfig = {}
+): ResolvedPageChrome {
+  const layout = pageLayoutFromMeta(meta)
+  const isHome = layout === 'home' || meta?.isHome === true
+  const aside = resolveAside(meta?.aside, layout === 'doc')
+  const outlineLevels = resolveOutlineLevels(meta?.outline, themeConfig.outline)
+  const showAside = aside !== false && outlineLevels !== false
+
+  return {
+    layout,
+    isHome,
+    showNavbar: resolveBoolean(meta?.navbar, true),
+    showSidebar: resolveBoolean(meta?.sidebar, layout === 'doc'),
+    aside,
+    showAside,
+    outlineLevels,
+    showPager: layout === 'doc',
+    showFooter: Boolean(themeConfig.footer) && resolveBoolean(meta?.footer, true),
+    showEditLink: Boolean(themeConfig.editLink) && resolveBoolean(meta?.editLink, true),
+    showLastUpdated: Boolean(themeConfig.lastUpdated) && resolveBoolean(meta?.lastUpdated, true),
+    pageClass: resolveString(meta?.pageClass),
+    markdownStyles: layout !== 'page' && meta?.markdownStyles !== false,
+    hero: parseHero(meta?.hero),
+    features: parseFeatures(meta?.features)
+  }
+}
+
+export function filterHeadingsForOutline<T extends OutlineHeading>(
+  headings: T[],
+  levels: PageOutlineLevels
+): T[] {
+  if (levels === false) return []
+  const [min, max] = levels
+  return headings.filter((heading) => heading.level >= min && heading.level <= max)
+}
+
+export function parseHero(value: unknown): Hero | undefined {
+  if (!isRecord(value)) return undefined
+
+  const name = resolveString(value.name)
+  const text = resolveString(value.text)
+  const tagline = resolveString(value.tagline)
+  const image = parseThemeableImage(value.image)
+  const actions = Array.isArray(value.actions)
+    ? value.actions.map(parseHeroAction).filter((action): action is HeroAction => Boolean(action))
+    : []
+
+  if (!name && !text && !tagline && !image && actions.length === 0) return undefined
+
+  return { name, text, tagline, image, actions }
+}
+
+export function parseFeatures(value: unknown): Feature[] {
+  if (!Array.isArray(value)) return []
+  return value.map(parseFeature).filter((feature): feature is Feature => Boolean(feature))
+}
+
+function parseHeroAction(value: unknown): HeroAction | undefined {
+  if (!isRecord(value)) return undefined
+  const text = resolveString(value.text)
+  const link = resolveString(value.link)
+  if (!text || !link) return undefined
+
+  return {
+    theme: value.theme === 'alt' ? 'alt' : 'brand',
+    text,
+    link,
+    target: resolveString(value.target),
+    rel: resolveString(value.rel)
+  }
+}
+
+function parseFeature(value: unknown): Feature | undefined {
+  if (!isRecord(value)) return undefined
+  const title = resolveString(value.title)
+  const details = resolveString(value.details)
+  if (!title || !details) return undefined
+
+  return {
+    icon: parseFeatureIcon(value.icon),
+    title,
+    details,
+    link: resolveString(value.link),
+    linkText: resolveString(value.linkText),
+    rel: resolveString(value.rel),
+    target: resolveString(value.target)
+  }
+}
+
+function parseThemeableImage(value: unknown): ThemeableImage | undefined {
+  if (typeof value === 'string' && value.trim()) return value.trim()
+  if (!isRecord(value)) return undefined
+
+  const src = resolveString(value.src)
+  if (src) return { src, alt: resolveString(value.alt) }
+
+  const light = resolveString(value.light)
+  const dark = resolveString(value.dark)
+  if (light && dark) return { light, dark, alt: resolveString(value.alt) }
+
+  return undefined
+}
+
+function parseFeatureIcon(value: unknown): FeatureIcon | undefined {
+  if (typeof value === 'string' && value.trim()) return value.trim()
+  if (!isRecord(value)) return undefined
+
+  const width = resolveString(value.width)
+  const height = resolveString(value.height)
+  const src = resolveString(value.src)
+  if (src) return { src, alt: resolveString(value.alt), width, height }
+
+  const light = resolveString(value.light)
+  const dark = resolveString(value.dark)
+  if (light && dark) {
+    return { light, dark, alt: resolveString(value.alt), width, height }
+  }
+
+  return undefined
+}
+
+function resolveAside(value: unknown, defaultValue: boolean): PageAside {
+  if (value === 'left') return 'left'
+  if (typeof value === 'boolean') return value
+  return defaultValue
+}
+
+function resolveOutlineLevels(
+  pageValue: unknown,
+  siteValue: PageChromeThemeConfig['outline']
+): PageOutlineLevels {
+  const pageLevels = parseOutlineLevels(pageValue)
+  if (pageLevels !== undefined) return pageLevels
+
+  if (siteValue === false) return false
+  return parseOutlineLevels(siteValue) ?? [2, 3]
+}
+
+function parseOutlineLevels(value: unknown): PageOutlineLevels | undefined {
+  if (value === false) return false
+  if (value === 'deep') return [2, 6]
+  if (typeof value === 'number') return normalizeOutlineRange(value, value)
+  if (Array.isArray(value) && value.length === 2) {
+    const [min, max] = value
+    if (typeof min === 'number' && typeof max === 'number') {
+      return normalizeOutlineRange(min, max)
+    }
+  }
+  return undefined
+}
+
+function normalizeOutlineRange(min: number, max: number): PageOutlineLevels | undefined {
+  if (!Number.isFinite(min) || !Number.isFinite(max)) return undefined
+  const start = Math.max(1, Math.min(6, Math.trunc(min)))
+  const end = Math.max(1, Math.min(6, Math.trunc(max)))
+  return start <= end ? [start, end] : [end, start]
+}
+
+function resolveBoolean(value: unknown, defaultValue: boolean): boolean {
+  return typeof value === 'boolean' ? value : defaultValue
+}
+
+function resolveString(value: unknown): string | undefined {
+  return typeof value === 'string' && value.trim() ? value.trim() : undefined
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return Boolean(value) && typeof value === 'object' && !Array.isArray(value)
+}

package/src/shared/pageHead.ts

@@ -0,0 +1,26 @@
+import type { HeadTag } from '../node/siteConfig.js'
+
+export function headTagsFromMeta(meta: Record<string, unknown> | undefined): HeadTag[] {
+  const raw = meta?.head
+  if (!Array.isArray(raw)) return []
+
+  const tags: HeadTag[] = []
+  for (const entry of raw) {
+    const tag = parseHeadTag(entry)
+    if (tag) tags.push(tag)
+  }
+  return tags
+}
+
+function parseHeadTag(entry: unknown): HeadTag | undefined {
+  if (!Array.isArray(entry) || entry.length < 2) return undefined
+  const name = entry[0]
+  const attrs = entry[1]
+  if (name !== 'meta' && name !== 'link' && name !== 'script') return undefined
+  if (!attrs || typeof attrs !== 'object') return undefined
+  const record = attrs as Record<string, string | boolean | undefined>
+  if (entry.length >= 3 && name === 'script') {
+    return ['script', record, typeof entry[2] === 'string' ? entry[2] : '']
+  }
+  return [name, record]
+}

package/src/shared/pageMeta.ts

@@ -0,0 +1,136 @@
+import type { Feature, Hero, PageAside, PageOutlineConfig } from './pageChrome.js'
+
+export const META_DESCRIPTION_MAX = 155
+export const PAGE_LAYOUTS = ['doc', 'home', 'page'] as const
+export type PageLayout = (typeof PAGE_LAYOUTS)[number]
+
+export const DEFAULT_TITLE_TEMPLATE = ':title | :siteTitle'
+
+/** Frontmatter and page metadata fields supported by PreactPress pages. */
+export interface PageMetaInput {
+  meta?: Record<string, unknown>
+  title?: string
+  titleTemplate?: string | false
+  description?: string
+  tags?: string[]
+  image?: string
+  pageType?: 'website' | 'article'
+  layout?: PageLayout
+  navbar?: boolean
+  sidebar?: boolean
+  aside?: PageAside
+  outline?: PageOutlineConfig
+  footer?: boolean
+  editLink?: boolean
+  lastUpdated?: boolean
+  pageClass?: string
+  isHome?: boolean
+  markdownStyles?: boolean
+  hero?: Hero
+  features?: Feature[]
+  kind?: 'markdown' | 'mdx'
+  html?: string
+}
+
+/** Alias for {@link PageMetaInput} — use in themes, hooks, and custom frontmatter helpers. */
+export type PageFrontmatter = PageMetaInput
+
+export interface SiteMetaInput {
+  title: string
+  description: string
+  titleTemplate?: string | false
+}
+
+export function formatTitleTemplate(
+  template: string | false | undefined,
+  params: { title?: string; siteTitle: string }
+): string {
+  if (template === false) {
+    return params.title?.trim() || params.siteTitle
+  }
+  const pattern = template?.trim() || DEFAULT_TITLE_TEMPLATE
+  if (!params.title?.trim()) return params.siteTitle
+  return pattern
+    .replace(/:title/g, params.title.trim())
+    .replace(/:siteTitle/g, params.siteTitle)
+}
+
+export function titleTemplateFromMeta(meta: Record<string, unknown> | undefined): string | false | undefined {
+  const value = meta?.titleTemplate
+  if (value === false) return false
+  return typeof value === 'string' ? value : undefined
+}
+
+export function excerptFromHtml(html: string, maxLen = META_DESCRIPTION_MAX): string {
+  const text = html
+    .replace(/<[^>]+>/g, ' ')
+    .replace(/&[a-z0-9#]+;/gi, ' ')
+    .replace(/\s+/g, ' ')
+    .trim()
+  if (!text) return ''
+  if (text.length <= maxLen) return text
+  const cut = text.slice(0, maxLen)
+  const lastSpace = cut.lastIndexOf(' ')
+  const trimmed = (lastSpace > 40 ? cut.slice(0, lastSpace) : cut).trim()
+  return `${trimmed}…`
+}
+
+export function resolvePageMeta(
+  page: PageMetaInput | undefined,
+  site: SiteMetaInput
+): { title: string; description: string } {
+  const { title, description } = resolvePageHeadMeta(page, site)
+  return { title, description }
+}
+
+export function resolvePageHeadMeta(
+  page: PageMetaInput | undefined,
+  site: SiteMetaInput
+): {
+  title: string
+  description: string
+  tags: string[]
+  image?: string
+  pageType: 'website' | 'article'
+} {
+  const template = page?.titleTemplate ?? site.titleTemplate
+  const title = formatTitleTemplate(template, {
+    title: page?.title,
+    siteTitle: site.title
+  })
+
+  let description =
+    (page?.description && String(page.description).trim()) || site.description.trim()
+
+  if (!description && page?.kind === 'markdown' && page.html) {
+    description = excerptFromHtml(page.html)
+  }
+
+  const tags = page?.tags?.filter((tag) => tag.trim()).map((tag) => tag.trim()) ?? []
+  const image = page?.image?.trim() || undefined
+  const pageType = page?.pageType === 'article' ? 'article' : 'website'
+
+  return { title, description, tags, image, pageType }
+}
+
+export function pageImageFromMeta(meta: Record<string, unknown>): string | undefined {
+  const value = meta.ogImage ?? meta.image
+  return typeof value === 'string' && value.trim() ? value.trim() : undefined
+}
+
+export function pageTypeFromMeta(meta: Record<string, unknown>): 'website' | 'article' {
+  return meta.type === 'article' ? 'article' : 'website'
+}
+
+export function pageLayoutFromMeta(meta: Record<string, unknown> | undefined): PageLayout {
+  const value = meta?.layout
+  return PAGE_LAYOUTS.includes(value as PageLayout) ? (value as PageLayout) : 'doc'
+}
+
+export function isPageLayout(value: unknown): value is PageLayout {
+  return PAGE_LAYOUTS.includes(value as PageLayout)
+}
+
+export function isDraftPage(meta: Record<string, unknown>): boolean {
+  return meta.draft === true
+}

package/src/shared/rewrites.ts

@@ -0,0 +1,35 @@
+import type { ContentFile } from '../node/content.js'
+import { normalizeRoute } from './route.js'
+
+export type RouteRewrites = Record<string, string>
+
+export function normalizeRewriteRoute(route: string): string {
+  return normalizeRoute(route)
+}
+
+export function applyRouteRewrites(
+  routeToFile: Map<string, ContentFile>,
+  rewrites: RouteRewrites
+): void {
+  for (const [aliasRaw, sourceRaw] of Object.entries(rewrites)) {
+    const alias = normalizeRewriteRoute(aliasRaw)
+    const source = normalizeRewriteRoute(sourceRaw)
+    const sourceFile = routeToFile.get(source)
+    if (!sourceFile) {
+      throw new Error(
+        `preactpress: rewrite source route not found: ${sourceRaw} (${source})`
+      )
+    }
+    const existing = routeToFile.get(alias)
+    if (existing && existing.file !== sourceFile.file) {
+      throw new Error(
+        `preactpress: rewrite collision for ${alias}: ${pathLabel(existing)} and ${pathLabel(sourceFile)}`
+      )
+    }
+    routeToFile.set(alias, { ...sourceFile, route: alias })
+  }
+}
+
+function pathLabel(file: ContentFile): string {
+  return file.route === '/' ? '/' : file.route
+}

package/src/shared/route.ts

@@ -0,0 +1,14 @@
+/** Normalize a path or route to a site route (no query/hash, leading slash, no trailing slash except `/`). */
+export function normalizeRoute(route: string): string {
+  const clean = route.split(/[?#]/, 1)[0] || '/'
+  const prefixed = clean.startsWith('/') ? clean : `/${clean}`
+  return prefixed.replace(/\/$/, '') || '/'
+}
+
+/** Map a request pathname to a site route using the configured base. */
+export function routeFromPathname(pathname: string, base: string): string {
+  const basePath = base === '/' ? '' : base.replace(/\/$/, '')
+  let p = pathname
+  if (basePath && p.startsWith(basePath)) p = p.slice(basePath.length) || '/'
+  return normalizeRoute(p)
+}

package/src/shared/search.ts

@@ -0,0 +1,105 @@
+export type SearchProvider = 'local' | 'algolia'
+
+export interface LocalSearchConfig {
+  provider: 'local'
+}
+
+export interface AlgoliaSearchOptions {
+  appId?: string
+  apiKey?: string
+  indexName?: string
+  placeholder?: string
+  maxResultsPerGroup?: number
+  disableUserPersonalization?: boolean
+  initialQuery?: string
+  recentSearchesLimit?: number
+  recentSearchesWithFavoritesLimit?: number
+  insights?: boolean
+  searchParameters?: Record<string, unknown>
+  /** Locale-specific overrides (merged with root options). */
+  locales?: Record<string, Partial<AlgoliaSearchOptions>>
+}
+
+export interface AlgoliaSearchConfig {
+  provider: 'algolia'
+  options: AlgoliaSearchOptions
+}
+
+/** `true` keeps local sidebar search; use `{ provider }` for explicit providers. */
+export type SearchConfig = boolean | LocalSearchConfig | AlgoliaSearchConfig
+
+export function resolveSearchProvider(search?: SearchConfig): SearchProvider | false {
+  if (search === true) return 'local'
+  if (search === false || search == null) return false
+  return search.provider
+}
+
+export function isLocalSearchEnabled(search?: SearchConfig): boolean {
+  return resolveSearchProvider(search) === 'local'
+}
+
+export function isAlgoliaSearchEnabled(search?: SearchConfig): boolean {
+  return resolveSearchProvider(search) === 'algolia'
+}
+
+export function algoliaOptionsFromSearch(search?: SearchConfig): AlgoliaSearchOptions | undefined {
+  if (typeof search === 'object' && search.provider === 'algolia') return search.options
+  return undefined
+}
+
+export function resolveAlgoliaOptions(
+  options: AlgoliaSearchOptions,
+  localeKey?: string
+): AlgoliaSearchOptions {
+  const { locales, ...root } = options
+  const override = localeKey && locales?.[localeKey] ? locales[localeKey] : {}
+  return {
+    ...root,
+    ...override,
+    searchParameters: override.searchParameters ?? root.searchParameters
+  }
+}
+
+export function validateAlgoliaCredentials(options: AlgoliaSearchOptions): {
+  valid: boolean
+  appId?: string
+  apiKey?: string
+  indexName?: string
+} {
+  const appId = options.appId?.trim()
+  const apiKey = options.apiKey?.trim()
+  const indexName = options.indexName?.trim()
+  return {
+    valid: Boolean(appId && apiKey && indexName),
+    appId,
+    apiKey,
+    indexName
+  }
+}
+
+export function getRelativeDocSearchUrl(url: string, base: string, cleanUrls = true): string {
+  const { pathname, hash } = new URL(url, 'http://preactpress.local')
+  const normalizedBase = base === '/' ? '' : base.replace(/\/$/, '')
+  let path = pathname
+  if (normalizedBase && path.startsWith(normalizedBase)) {
+    path = path.slice(normalizedBase.length) || '/'
+  }
+  const route = cleanUrls ? path.replace(/\.html$/, '').replace(/\/index$/, '/') || '/' : path
+  return `${route}${hash}`
+}
+
+export function navigateDocSearchResult(itemUrl: string, base: string): void {
+  const url = new URL(itemUrl, window.location.origin)
+  const normalizedBase = base === '/' ? '' : base.replace(/\/$/, '')
+  const href =
+    normalizedBase && !url.pathname.startsWith(normalizedBase)
+      ? itemUrl
+      : `${normalizedBase}${url.pathname.replace(normalizedBase, '') || '/'}${url.search}${url.hash}`
+  if (url.origin !== window.location.origin) {
+    window.location.assign(href)
+    return
+  }
+  window.history.pushState({}, '', href)
+  window.dispatchEvent(new PopStateEvent('popstate'))
+  window.scrollTo({ top: 0 })
+}