@meith/web 0.16.0

package/src/server/theme-admin.ts

@@ -0,0 +1,203 @@
+import { msg } from '@meith/i18n'
+import 'server-only'
+
+import forumConfig from '@board/config'
+
+import { ForbiddenError } from '@meith/core'
+import { getDb, PostgresThemeAdminRepository, type ThemeRecord } from '@meith/db'
+
+import type { EditableToken } from '@/view/theme-draft'
+import { tokenCopy } from '@/view/theme-tokens'
+
+import { getContainer } from './container'
+import { getTranslator } from './i18n'
+import { type TokenOverrides, validateTokenOverrides } from './theme-style'
+
+export function themeAdminRepository(): PostgresThemeAdminRepository | null {
+  return getContainer().dataSource === 'postgres' ? new PostgresThemeAdminRepository(getDb()) : null
+}
+
+export function requireThemeAdmin(): PostgresThemeAdminRepository {
+  const repository = themeAdminRepository()
+  if (repository === null) {
+    throw new ForbiddenError(msg('error.app.board-running-in-memory-sample-data-24'))
+  }
+  return repository
+}
+
+export type TokenRow = EditableToken
+
+export interface ThemeAdminView {
+  readonly key: string
+  readonly title: string
+  readonly isBuildTheme: boolean
+  readonly isDefault: boolean
+  readonly enabled: boolean
+  readonly tokens: readonly TokenRow[]
+  readonly customCss: string
+  readonly customised: boolean
+  readonly updatedAt: Date | null
+}
+
+export interface ThemeListing {
+  readonly key: string
+  readonly title: string
+  readonly isBuildTheme: boolean
+  readonly isDefault: boolean
+  readonly enabled: boolean
+  readonly overriddenTokens: number
+  readonly hasCustomCss: boolean
+  readonly updatedAt: Date | null
+}
+
+const buildThemeKey = forumConfig.defaultTheme
+
+function countOverrides(raw: unknown): number {
+  if (typeof raw !== 'object' || raw === null || Array.isArray(raw)) return 0
+
+  const record = raw as Record<string, unknown>
+  const scheme = (value: unknown): string[] =>
+    typeof value === 'object' && value !== null && !Array.isArray(value)
+      ? Object.keys(value as Record<string, unknown>)
+      : []
+
+  const keys = Object.keys(record)
+  if (keys.length > 0 && keys.every((key) => key === 'light' || key === 'dark')) {
+    return new Set([...scheme(record.light), ...scheme(record.dark)]).size
+  }
+  return keys.length
+}
+
+export async function themeListing(): Promise<readonly ThemeListing[]> {
+  const repository = themeAdminRepository()
+  const rows = repository === null ? [] : await repository.list()
+  const byKey = new Map(rows.map((row) => [row.key, row]))
+
+  const registered = Object.values(forumConfig.themes)
+  const claimed = registered.find((theme) => byKey.get(theme.key)?.isDefault === true)
+
+  return registered.map((theme) => {
+    const row = byKey.get(theme.key)
+    const enabled = row?.enabled !== false
+    return {
+      key: theme.key,
+      title: theme.title,
+      isBuildTheme: theme.key === buildThemeKey,
+      isDefault:
+        claimed === undefined || byKey.get(claimed.key)?.enabled === false
+          ? theme.key === buildThemeKey
+          : claimed.key === theme.key,
+      enabled,
+      overriddenTokens: countOverrides(row?.tokenOverrides),
+      hasCustomCss: (row?.customCss ?? null) !== null,
+      updatedAt: row?.updatedAt ?? null,
+    }
+  })
+}
+
+export async function buildThemeAdminView(key: string): Promise<ThemeAdminView | null> {
+  const t = await getTranslator()
+  const installed = forumConfig.themes[key]
+  const repository = themeAdminRepository()
+  if (installed === undefined || repository === null) return null
+
+  const record: ThemeRecord | null = await repository.read(key)
+
+  let overrides: TokenOverrides = { light: {}, dark: {} }
+  try {
+    overrides = validateTokenOverrides(installed.tokens, record?.tokenOverrides)
+  } catch {
+    /* ignore */
+  }
+
+  const listing = (await themeListing()).find((entry) => entry.key === key)
+
+  return {
+    key,
+    title: installed.title,
+    isBuildTheme: key === buildThemeKey,
+    isDefault: listing?.isDefault ?? key === buildThemeKey,
+    enabled: listing?.enabled ?? true,
+    tokens: Object.keys(installed.tokens.light).map((name) => {
+      const light = installed.tokens.light[name] ?? ''
+      const dark = installed.tokens.dark[name] ?? ''
+      const meta = tokenCopy(name, t)
+      return {
+        name,
+        label: meta.label,
+        hint: meta.hint,
+        kind: meta.kind,
+        light,
+        dark,
+        overrideLight: overrides.light[name] ?? '',
+        overrideDark: overrides.dark[name] ?? '',
+      }
+    }),
+    customCss: record?.customCss ?? '',
+    customised: record !== null,
+    updatedAt: record?.updatedAt ?? null,
+  }
+}
+
+export function themeTokens(
+  key: string,
+): { light: Readonly<Record<string, string>>; dark: Readonly<Record<string, string>> } | null {
+  const installed = forumConfig.themes[key]
+  return installed === undefined
+    ? null
+    : { light: installed.tokens.light, dark: installed.tokens.dark }
+}
+
+export function themeTitle(key: string): string | null {
+  return forumConfig.themes[key]?.title ?? null
+}
+
+export function isBuildTheme(key: string): boolean {
+  return key === buildThemeKey
+}
+
+export interface SampleSurface {
+  readonly background: string
+  readonly foreground: string
+}
+
+export async function boardSampleSurfaces(): Promise<{
+  readonly light: SampleSurface
+  readonly dark: SampleSurface
+}> {
+  const listing = await themeListing().catch(() => [])
+  const key = listing.find((entry) => entry.isDefault)?.key ?? buildThemeKey
+  const theme = forumConfig.themes[key] ?? forumConfig.themes[buildThemeKey]
+
+  const light = theme?.tokens.light ?? {}
+  const dark = theme?.tokens.dark ?? {}
+
+  let overrides: TokenOverrides = { light: {}, dark: {} }
+  if (theme !== undefined) {
+    const record = await themeAdminRepository()
+      ?.read(key)
+      .catch(() => null)
+    try {
+      overrides = validateTokenOverrides(theme.tokens, record?.tokenOverrides)
+    } catch {
+      /* ignore */
+    }
+  }
+
+  const pick = (
+    shipped: Readonly<Record<string, string>>,
+    override: Readonly<Record<string, string>>,
+    name: string,
+  ): string => override[name] ?? shipped[name] ?? ''
+
+  return {
+    light: {
+      background: pick(light, overrides.light, 'card'),
+      foreground: pick(light, overrides.light, 'card-foreground'),
+    },
+    dark: {
+      background: pick(dark, overrides.dark, 'card'),
+      foreground: pick(dark, overrides.dark, 'card-foreground'),
+    },
+  }
+}

package/src/server/theme-runtime.ts

@@ -0,0 +1,89 @@
+import 'server-only'
+
+import forumConfig from '@board/config'
+import { cache } from 'react'
+
+import { CacheTags, cachedGlobal, env } from '@meith/core'
+import { getDb, PostgresThemeRepository, type ThemeRuntimeState } from '@meith/db'
+import { drivers } from '@meith/drivers'
+import { DARK_TOKENS as DEFAULT_DARK, LIGHT_TOKENS as DEFAULT_LIGHT } from '@meith/theme-default'
+
+import {
+  type BoardTheme,
+  effectiveTokens,
+  renderBoardStyle,
+  type ThemeRuntimeStyle,
+  type ThemeTokens,
+} from './theme-style'
+
+export interface ThemeChoice {
+  readonly key: string
+  readonly title: string
+}
+
+export interface BoardThemeStyle extends ThemeRuntimeStyle {
+  readonly choices: readonly ThemeChoice[]
+  readonly defaultKey: string
+  readonly defaultTokens: ThemeTokens
+}
+
+const registered = Object.values(forumConfig.themes)
+const buildTheme = forumConfig.themes[forumConfig.defaultTheme]!
+
+const COMPILED_TOKENS = { light: DEFAULT_LIGHT, dark: DEFAULT_DARK }
+
+function shippedStyle(): BoardThemeStyle {
+  return composeBoard([])
+}
+
+function composeBoard(rows: readonly ThemeRuntimeState[]): BoardThemeStyle {
+  const byKey = new Map(rows.map((row) => [row.key, row]))
+
+  const enabled = registered.filter((theme) => byKey.get(theme.key)?.enabled !== false)
+
+  if (!enabled.some((theme) => theme.key === buildTheme.key)) enabled.unshift(buildTheme)
+
+  const claimed = registered.find((theme) => byKey.get(theme.key)?.isDefault === true)
+  const defaultKey =
+    claimed !== undefined && enabled.includes(claimed) ? claimed.key : buildTheme.key
+
+  const themes: BoardTheme[] = enabled.map((theme) => ({
+    key: theme.key,
+    tokens: theme.tokens,
+    overrides: byKey.get(theme.key)?.tokenOverrides,
+    customCss: byKey.get(theme.key)?.customCss ?? null,
+  }))
+
+  const active = themes.find((theme) => theme.key === defaultKey)
+
+  return {
+    ...renderBoardStyle({ themes, defaultKey, baseline: COMPILED_TOKENS }),
+    choices: enabled.map((theme) => ({ key: theme.key, title: theme.title })),
+    defaultKey,
+    defaultTokens: active === undefined ? COMPILED_TOKENS : effectiveTokens(active),
+  }
+}
+
+const TTL_SECONDS = 60
+
+function loadPostgresBoardStyle(): Promise<BoardThemeStyle> {
+  return cachedGlobal(
+    drivers().cache,
+    {
+      key: ['board-theme-style'],
+      tags: registered.map((theme) => CacheTags.theme(theme.key)),
+      revalidate: TTL_SECONDS,
+    },
+    async () => composeBoard(await new PostgresThemeRepository(getDb()).listRuntime()),
+  )
+}
+
+export const getBoardThemeStyle = cache(async (): Promise<BoardThemeStyle> => {
+  if (env.DATA_SOURCE === 'fixture') return shippedStyle()
+
+  return loadPostgresBoardStyle().catch(() => shippedStyle())
+})
+
+export async function getThemeRuntimeStyle(): Promise<ThemeRuntimeStyle> {
+  return getBoardThemeStyle()
+}

package/src/server/theme-style.ts

@@ -0,0 +1,279 @@
+import { colourToHex } from '@meith/theme-kit'
+
+export interface ThemeTokens {
+  readonly light: Readonly<Record<string, string>>
+  readonly dark: Readonly<Record<string, string>>
+}
+
+export interface ThemeRuntimeStyle {
+  readonly css: string
+  readonly browserThemeColor: { readonly light: string; readonly dark: string }
+}
+
+export interface TokenOverrides {
+  readonly light: Readonly<Record<string, string>>
+  readonly dark: Readonly<Record<string, string>>
+}
+
+export interface BoardTheme {
+  readonly key: string
+  readonly tokens: ThemeTokens
+  readonly overrides: unknown
+  readonly customCss: string | null
+}
+
+export type ColourScheme = 'light' | 'dark'
+
+export const COLOUR_SCHEMES: readonly ColourScheme[] = ['light', 'dark']
+
+const MAX_CUSTOM_CSS_LENGTH = 100_000
+
+const THEME_KEY = /^[a-z0-9][a-z0-9_-]*$/i
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value)
+}
+
+export function assertSafeCssValue(name: string, value: string): void {
+  if (
+    value.length === 0 ||
+    value.length > 256 ||
+    /[;{}<>]/.test(value) ||
+    !/^[a-zA-Z0-9#%(),.\s'"/+*=-]+$/.test(value)
+  ) {
+    throw new Error(`Theme ${name} has an unsafe CSS value.`)
+  }
+}
+
+function assertSafeThemeKey(key: string): void {
+  if (!THEME_KEY.test(key)) {
+    throw new Error(`Theme key "${key}" cannot be used in a stylesheet selector.`)
+  }
+}
+
+function isSchemeShaped(raw: Record<string, unknown>): boolean {
+  const keys = Object.keys(raw)
+  return (
+    keys.every((key) => key === 'light' || key === 'dark') &&
+    keys.every((key) => isRecord(raw[key]))
+  )
+}
+
+function validateScheme(tokens: ThemeTokens, raw: Record<string, unknown>): Record<string, string> {
+  const overrides: Record<string, string> = {}
+  for (const [name, value] of Object.entries(raw)) {
+    if (!(name in tokens.light) || !(name in tokens.dark)) {
+      throw new Error(`Theme token "${name}" is not declared by this theme.`)
+    }
+    if (typeof value !== 'string') {
+      throw new Error(`Theme token "${name}" must have a string value.`)
+    }
+    assertSafeCssValue(`token "${name}"`, value)
+    if (name === 'background' && colorToHex(value) === null) {
+      throw new Error('Theme token "background" must be an sRGB hex or OKLCH colour.')
+    }
+    overrides[name] = value
+  }
+  return overrides
+}
+
+export function validateTokenOverrides(tokens: ThemeTokens, raw: unknown): TokenOverrides {
+  if (raw === undefined || raw === null) return { light: {}, dark: {} }
+  if (!isRecord(raw)) throw new Error('Theme token overrides must be an object.')
+
+  if (isSchemeShaped(raw)) {
+    return {
+      light: validateScheme(tokens, isRecord(raw.light) ? raw.light : {}),
+      dark: validateScheme(tokens, isRecord(raw.dark) ? raw.dark : {}),
+    }
+  }
+
+  const both = validateScheme(tokens, raw)
+  return { light: both, dark: { ...both } }
+}
+
+export function validateCustomCss(value: string | null): string | null {
+  if (value === null || value.trim() === '') return null
+  if (
+    value.length > MAX_CUSTOM_CSS_LENGTH ||
+    /<\/style|@import|url\s*\(|expression\s*\(/i.test(value)
+  ) {
+    throw new Error('Theme custom CSS contains an unsafe construct.')
+  }
+  return value
+}
+
+export const colorToHex = colourToHex
+
+function declarations(values: Readonly<Record<string, string>>): string {
+  return Object.entries(values)
+    .map(([name, value]) => `--${name}:${value};`)
+    .join('')
+}
+
+export function effectiveTokens(theme: BoardTheme): ThemeTokens {
+  const overrides = validateTokenOverrides(theme.tokens, theme.overrides)
+  return {
+    light: { ...theme.tokens.light, ...overrides.light },
+    dark: { ...theme.tokens.dark, ...overrides.dark },
+  }
+}
+
+function differing(
+  values: Readonly<Record<string, string>>,
+  against: Readonly<Record<string, string>>,
+): Record<string, string> {
+  const out: Record<string, string> = {}
+  for (const [name, value] of Object.entries(values)) {
+    if (against[name] !== value) {
+      assertSafeCssValue(`token "${name}"`, value)
+      out[name] = value
+    }
+  }
+  return out
+}
+
+function restatedForDark(
+  light: Readonly<Record<string, string>>,
+  dark: Record<string, string>,
+  darkValues: Readonly<Record<string, string>>,
+): Record<string, string> {
+  const out = { ...dark }
+
+  for (const name of Object.keys(light)) {
+    if (name in out) continue
+    const value = darkValues[name]
+    if (value === undefined) continue
+    assertSafeCssValue(`token "${name}"`, value)
+    out[name] = value
+  }
+
+  return out
+}
+
+function schemeBlocks(
+  light: Record<string, string>,
+  dark: Record<string, string>,
+  selector: { light: string; dark: string; media: string },
+): string {
+  const lightCss = declarations(light)
+  const darkCss = declarations(dark)
+
+  return (
+    (lightCss === '' ? '' : `${selector.light}{${lightCss}}`) +
+    (darkCss === ''
+      ? ''
+      : `${selector.dark}{${darkCss}}` +
+        `@media (prefers-color-scheme: dark){${selector.media}{${darkCss}}}`)
+  )
+}
+
+export function renderBoardStyle(input: {
+  readonly themes: readonly BoardTheme[]
+  readonly defaultKey: string
+  readonly baseline: ThemeTokens
+}): ThemeRuntimeStyle {
+  const active = input.themes.find((theme) => theme.key === input.defaultKey)
+  if (active === undefined) {
+    throw new Error(`Theme "${input.defaultKey}" is not among the enabled themes.`)
+  }
+
+  const activeTokens = effectiveTokens(active)
+
+  const activeLight = differing(activeTokens.light, input.baseline.light)
+
+  let css = schemeBlocks(
+    activeLight,
+    restatedForDark(
+      activeLight,
+      differing(activeTokens.dark, input.baseline.dark),
+      activeTokens.dark,
+    ),
+    { light: ':root', dark: '.dark', media: ':root:not(.light)' },
+  )
+  css += validateCustomCss(active.customCss) ?? ''
+
+  for (const theme of input.themes) {
+    if (theme.key === active.key) continue
+    assertSafeThemeKey(theme.key)
+
+    const tokens = effectiveTokens(theme)
+    const scope = `[data-theme="${theme.key}"]`
+    const light = differing(tokens.light, activeTokens.light)
+
+    css += schemeBlocks(
+      light,
+      restatedForDark(light, differing(tokens.dark, activeTokens.dark), tokens.dark),
+      {
+        light: `:root${scope}`,
+        dark: `.dark${scope}`,
+        media: `:root${scope}:not(.light)`,
+      },
+    )
+
+    const custom = validateCustomCss(theme.customCss)
+    if (custom !== null) css += `:root${scope}{${custom}}`
+  }
+
+  const light = colorToHex(activeTokens.light.background ?? '')
+  const dark = colorToHex(activeTokens.dark.background ?? '')
+  if (light === null || dark === null) {
+    throw new Error('Theme background tokens must be sRGB hex or OKLCH colours.')
+  }
+
+  return { css, browserThemeColor: { light, dark } }
+}
+
+export function renderThemeStyle(
+  tokens: ThemeTokens,
+  rawOverrides: unknown,
+  customCss: string | null,
+  baseline: ThemeTokens = tokens,
+): ThemeRuntimeStyle {
+  return renderBoardStyle({
+    themes: [{ key: 'default', tokens, overrides: rawOverrides, customCss }],
+    defaultKey: 'default',
+    baseline,
+  })
+}
+
+export interface GroupNameColour {
+  readonly groupId: number
+  readonly light: string | null
+  readonly dark: string | null
+}
+
+export function groupNameClass(groupId: number): string {
+  return `gname-${groupId}`
+}
+
+export function renderGroupNameStyle(groups: readonly GroupNameColour[]): string {
+  if (groups.length === 0) return ''
+
+  const block = (pick: (group: GroupNameColour) => string | null, prefix: string): string =>
+    groups
+      .map((group) => {
+        const colour = pick(group)
+        if (colour === null) return ''
+        assertSafeCssValue(`group ${group.groupId} colour`, colour)
+        const selector = `.${groupNameClass(group.groupId)}`
+        return `${prefix}${selector}${selector}{color:${colour};}`
+      })
+      .join('')
+
+  const scheme = (
+    pick: (group: GroupNameColour) => string | null,
+    chosen: ColourScheme,
+    other: ColourScheme,
+  ): string => {
+    const chose = block(pick, `.${chosen} `)
+    if (chose === '') return ''
+
+    const followsTheSystem = block(pick, `:root:not(.${other}) `)
+    return `${chose}@media (prefers-color-scheme: ${chosen}){${followsTheSystem}}`
+  }
+
+  return (
+    scheme((group) => group.light, 'light', 'dark') + scheme((group) => group.dark, 'dark', 'light')
+  )
+}

package/src/server/theme.ts

@@ -0,0 +1,52 @@
+import 'server-only'
+
+import forumConfig from '@board/config'
+import { cookies } from 'next/headers'
+import { cache } from 'react'
+
+import { assertThemeContract, type ResolvedTheme, resolveTheme } from '@meith/theme-kit'
+
+import {
+  type ColourSchemePreference,
+  isColourScheme,
+  SCHEME_COOKIE,
+  THEME_COOKIE,
+} from '@/view/theme-preference'
+
+import { getBoardThemeStyle } from './theme-runtime'
+
+const RESOLVED: ReadonlyMap<string, ResolvedTheme> = new Map(
+  Object.values(forumConfig.themes)
+    .filter((theme) => theme.theme !== undefined)
+    .map((theme) => [theme.key, resolveTheme(theme.theme!)]),
+)
+
+export const buildTheme: ResolvedTheme = RESOLVED.get(forumConfig.defaultTheme)!
+
+if (buildTheme === undefined) {
+  throw new Error(
+    `community.config.ts: defaultTheme "${forumConfig.defaultTheme}" fills no slots, so this ` +
+      'board cannot render a page. A token-only theme is legitimate as an alternate, ' +
+      'never as the theme a build is made of.',
+  )
+}
+
+for (const theme of RESOLVED.values()) assertThemeContract(theme)
+
+export const currentThemeKey = cache(async (): Promise<string> => {
+  const { choices, defaultKey } = await getBoardThemeStyle()
+  const chosen = (await cookies()).get(THEME_COOKIE)?.value
+
+  return chosen !== undefined && choices.some((choice) => choice.key === chosen)
+    ? chosen
+    : defaultKey
+})
+
+export const currentTheme = cache(async (): Promise<ResolvedTheme> => {
+  return RESOLVED.get(await currentThemeKey()) ?? buildTheme
+})
+
+export const currentColourScheme = cache(async (): Promise<ColourSchemePreference> => {
+  const chosen = (await cookies()).get(SCHEME_COOKIE)?.value
+  return isColourScheme(chosen) ? chosen : 'system'
+})