@meith/web 0.16.0

package/src/view/theme-tokens.ts

@@ -0,0 +1,333 @@
+import type { Translator } from '@meith/i18n'
+
+import { untranslated } from './time'
+
+export type TokenKind = 'colour' | 'length' | 'text'
+
+export interface TokenMeta {
+  readonly labelKey: string
+  readonly hintKey: string
+  readonly kind: TokenKind
+}
+
+export interface TokenGroup<T> {
+  readonly titleKey: string
+  readonly blurbKey: string
+  readonly tokens: readonly T[]
+}
+
+interface GroupSpec {
+  readonly titleKey: string
+  readonly blurbKey: string
+  readonly tokens: readonly (readonly [string, string, string, TokenKind?])[]
+}
+
+const GROUPS: readonly GroupSpec[] = [
+  {
+    titleKey: 'themeToken.group.brand.title',
+    blurbKey: 'themeToken.group.brand.blurb',
+    tokens: [
+      ['primary', 'themeToken.primary.label', 'themeToken.primary.hint'],
+      ['primary-hover', 'themeToken.primary-hover.label', 'themeToken.primary-hover.hint'],
+      [
+        'primary-foreground',
+        'themeToken.primary-foreground.label',
+        'themeToken.primary-foreground.hint',
+      ],
+      ['ring', 'themeToken.ring.label', 'themeToken.ring.hint'],
+    ],
+  },
+  {
+    titleKey: 'themeToken.group.page-and-panels.title',
+    blurbKey: 'themeToken.group.page-and-panels.blurb',
+    tokens: [
+      ['background', 'themeToken.background.label', 'themeToken.background.hint'],
+      ['foreground', 'themeToken.foreground.label', 'themeToken.foreground.hint'],
+      ['surface', 'themeToken.surface.label', 'themeToken.surface.hint'],
+      ['card', 'themeToken.card.label', 'themeToken.card.hint'],
+      ['card-foreground', 'themeToken.card-foreground.label', 'themeToken.card-foreground.hint'],
+      ['muted', 'themeToken.muted.label', 'themeToken.muted.hint'],
+      ['muted-foreground', 'themeToken.muted-foreground.label', 'themeToken.muted-foreground.hint'],
+      ['secondary', 'themeToken.secondary.label', 'themeToken.secondary.hint'],
+      [
+        'secondary-foreground',
+        'themeToken.secondary-foreground.label',
+        'themeToken.secondary-foreground.hint',
+      ],
+      ['accent', 'themeToken.accent.label', 'themeToken.accent.hint'],
+      [
+        'accent-foreground',
+        'themeToken.accent-foreground.label',
+        'themeToken.accent-foreground.hint',
+      ],
+      ['border', 'themeToken.border.label', 'themeToken.border.hint'],
+      ['input', 'themeToken.input.label', 'themeToken.input.hint'],
+      ['shadow-tint', 'themeToken.shadow-tint.label', 'themeToken.shadow-tint.hint'],
+    ],
+  },
+  {
+    titleKey: 'themeToken.group.destructive-actions.title',
+    blurbKey: 'themeToken.group.destructive-actions.blurb',
+    tokens: [
+      ['destructive', 'themeToken.destructive.label', 'themeToken.destructive.hint'],
+      [
+        'destructive-foreground',
+        'themeToken.destructive-foreground.label',
+        'themeToken.destructive-foreground.hint',
+      ],
+    ],
+  },
+  {
+    titleKey: 'themeToken.group.forums-and-threads.title',
+    blurbKey: 'themeToken.group.forums-and-threads.blurb',
+    tokens: [
+      ['forum-unread', 'themeToken.forum-unread.label', 'themeToken.forum-unread.hint'],
+      ['forum-read', 'themeToken.forum-read.label', 'themeToken.forum-read.hint'],
+      ['forum-locked', 'themeToken.forum-locked.label', 'themeToken.forum-locked.hint'],
+      ['thread-pinned', 'themeToken.thread-pinned.label', 'themeToken.thread-pinned.hint'],
+      ['thread-locked', 'themeToken.thread-locked.label', 'themeToken.thread-locked.hint'],
+      ['thread-moved', 'themeToken.thread-moved.label', 'themeToken.thread-moved.hint'],
+      [
+        'thread-unapproved',
+        'themeToken.thread-unapproved.label',
+        'themeToken.thread-unapproved.hint',
+      ],
+      ['thread-deleted', 'themeToken.thread-deleted.label', 'themeToken.thread-deleted.hint'],
+    ],
+  },
+  {
+    titleKey: 'themeToken.group.posts.title',
+    blurbKey: 'themeToken.group.posts.blurb',
+    tokens: [
+      ['post-highlight', 'themeToken.post-highlight.label', 'themeToken.post-highlight.hint'],
+      ['post-own', 'themeToken.post-own.label', 'themeToken.post-own.hint'],
+      ['post-unapproved', 'themeToken.post-unapproved.label', 'themeToken.post-unapproved.hint'],
+    ],
+  },
+  {
+    titleKey: 'themeToken.group.moderation.title',
+    blurbKey: 'themeToken.group.moderation.blurb',
+    tokens: [
+      ['moderation-pending', 'themeToken.moderation-pending.label', ''],
+      ['moderation-approved', 'themeToken.moderation-approved.label', ''],
+      ['moderation-rejected', 'themeToken.moderation-rejected.label', ''],
+    ],
+  },
+  {
+    titleKey: 'themeToken.group.member-groups.title',
+    blurbKey: 'themeToken.group.member-groups.blurb',
+    tokens: [
+      ['group-admin', 'themeToken.group-admin.label', ''],
+      ['group-supermod', 'themeToken.group-supermod.label', ''],
+      ['group-mod', 'themeToken.group-mod.label', ''],
+      ['group-banned', 'themeToken.group-banned.label', ''],
+    ],
+  },
+  {
+    titleKey: 'themeToken.group.shape-and-type.title',
+    blurbKey: 'themeToken.group.shape-and-type.blurb',
+    tokens: [
+      ['radius', 'themeToken.radius.label', 'themeToken.radius.hint', 'length'],
+      ['density-unit', 'themeToken.density-unit.label', 'themeToken.density-unit.hint', 'length'],
+      ['elevation', 'themeToken.elevation.label', 'themeToken.elevation.hint', 'text'],
+      [
+        'font-sans-stack',
+        'themeToken.font-sans-stack.label',
+        'themeToken.font-sans-stack.hint',
+        'text',
+      ],
+      [
+        'font-heading-stack',
+        'themeToken.font-heading-stack.label',
+        'themeToken.font-heading-stack.hint',
+        'text',
+      ],
+      [
+        'font-mono-stack',
+        'themeToken.font-mono-stack.label',
+        'themeToken.font-mono-stack.hint',
+        'text',
+      ],
+    ],
+  },
+]
+
+const META = new Map<string, TokenMeta>()
+for (const group of GROUPS) {
+  for (const [name, labelKey, hintKey, kind] of group.tokens) {
+    META.set(name, { labelKey, hintKey, kind: kind ?? 'colour' })
+  }
+}
+
+export function tokenMeta(name: string): TokenMeta {
+  return META.get(name) ?? { labelKey: name, hintKey: '', kind: 'colour' }
+}
+
+export function tokenGroupCopy(t: Translator = untranslated()): Readonly<Record<string, string>> {
+  const copy: Record<string, string> = {
+    'themeToken.group.other.title': t.t('themeToken.group.other.title'),
+    'themeToken.group.other.blurb': t.t('themeToken.group.other.blurb'),
+  }
+  for (const group of GROUPS) {
+    copy[group.titleKey] = t.t(group.titleKey)
+    copy[group.blurbKey] = t.t(group.blurbKey)
+  }
+  for (const preset of BRAND_PRESETS) copy[preset.titleKey] = t.t(preset.titleKey)
+  return copy
+}
+
+export function tokenCopy(
+  name: string,
+  t: Translator = untranslated(),
+): { readonly label: string; readonly hint: string; readonly kind: TokenKind } {
+  const meta = tokenMeta(name)
+  return {
+    label: t.has(meta.labelKey) ? t.t(meta.labelKey) : name,
+    hint: meta.hintKey === '' ? '' : t.t(meta.hintKey),
+    kind: meta.kind,
+  }
+}
+
+export function isSchemeIndependent(name: string): boolean {
+  return tokenMeta(name).kind !== 'colour'
+}
+
+export function groupTokens<T extends { readonly name: string }>(
+  tokens: readonly T[],
+): readonly TokenGroup<T>[] {
+  const byName = new Map(tokens.map((token) => [token.name, token]))
+  const groups: TokenGroup<T>[] = []
+  const placed = new Set<string>()
+
+  for (const group of GROUPS) {
+    const members: T[] = []
+    for (const [name] of group.tokens) {
+      const token = byName.get(name)
+      if (token === undefined) continue
+      members.push(token)
+      placed.add(name)
+    }
+    if (members.length > 0) {
+      groups.push({ titleKey: group.titleKey, blurbKey: group.blurbKey, tokens: members })
+    }
+  }
+
+  const rest = tokens.filter((token) => !placed.has(token.name))
+  if (rest.length > 0) {
+    groups.push({
+      titleKey: 'themeToken.group.other.title',
+      blurbKey: 'themeToken.group.other.blurb',
+      tokens: rest,
+    })
+  }
+
+  return groups
+}
+
+export const BRAND_TOKENS = ['primary', 'primary-hover', 'primary-foreground', 'ring'] as const
+
+export interface BrandPreset {
+  readonly key: string
+  readonly titleKey: string
+  readonly light: Readonly<Record<string, string>>
+  readonly dark: Readonly<Record<string, string>>
+}
+
+export const BRAND_PRESETS: readonly BrandPreset[] = [
+  {
+    key: 'meith',
+    titleKey: 'themeToken.preset.meith',
+    light: {
+      primary: '#047857',
+      'primary-hover': '#036045',
+      'primary-foreground': '#ffffff',
+      ring: '#047857',
+    },
+    dark: {
+      primary: '#34d399',
+      'primary-hover': '#5ee7b7',
+      'primary-foreground': '#04160f',
+      ring: '#34d399',
+    },
+  },
+  {
+    key: 'ocean',
+    titleKey: 'themeToken.preset.ocean',
+    light: {
+      primary: '#1d4ed8',
+      'primary-hover': '#1739a8',
+      'primary-foreground': '#ffffff',
+      ring: '#1d4ed8',
+    },
+    dark: {
+      primary: '#93c5fd',
+      'primary-hover': '#bfdbfe',
+      'primary-foreground': '#0b1220',
+      ring: '#93c5fd',
+    },
+  },
+  {
+    key: 'forest',
+    titleKey: 'themeToken.preset.forest',
+    light: {
+      primary: '#15803d',
+      'primary-hover': '#106430',
+      'primary-foreground': '#ffffff',
+      ring: '#15803d',
+    },
+    dark: {
+      primary: '#86efac',
+      'primary-hover': '#b2f5c9',
+      'primary-foreground': '#052e16',
+      ring: '#86efac',
+    },
+  },
+  {
+    key: 'plum',
+    titleKey: 'themeToken.preset.plum',
+    light: {
+      primary: '#7e22ce',
+      'primary-hover': '#651ba4',
+      'primary-foreground': '#ffffff',
+      ring: '#7e22ce',
+    },
+    dark: {
+      primary: '#d8b4fe',
+      'primary-hover': '#e7d0fe',
+      'primary-foreground': '#2e1065',
+      ring: '#d8b4fe',
+    },
+  },
+  {
+    key: 'rust',
+    titleKey: 'themeToken.preset.rust',
+    light: {
+      primary: '#b91c1c',
+      'primary-hover': '#961717',
+      'primary-foreground': '#ffffff',
+      ring: '#b91c1c',
+    },
+    dark: {
+      primary: '#fca5a5',
+      'primary-hover': '#fdc7c7',
+      'primary-foreground': '#450a0a',
+      ring: '#fca5a5',
+    },
+  },
+  {
+    key: 'sand',
+    titleKey: 'themeToken.preset.sand',
+    light: {
+      primary: '#92400e',
+      'primary-hover': '#74330b',
+      'primary-foreground': '#ffffff',
+      ring: '#92400e',
+    },
+    dark: {
+      primary: '#fcd34d',
+      'primary-hover': '#fde28a',
+      'primary-foreground': '#3b2506',
+      ring: '#fcd34d',
+    },
+  },
+]

package/src/view/thread-view.ts

@@ -0,0 +1,280 @@
+import type { ForumRow } from '@meith/forums'
+import type { Translator } from '@meith/i18n'
+import { type BoardVocabulary, type CompiledWordFilter, postBodyHtml } from '@meith/markdown'
+import { editedNote, type PostListingRow, type PostPage } from '@meith/posts'
+import { suppress } from '@meith/relations'
+import type {
+  PaginationModel,
+  PostAttachmentModel,
+  PostBitModel,
+  ThreadViewModel,
+} from '@meith/theme-kit'
+import type { ThreadListingRow } from '@meith/threads'
+
+import { forumHref } from './board-index'
+import { count } from './count'
+import { threadRowModel } from './forum-display'
+import type { MemberIdentity } from './member-identity'
+import { memberHref } from './member-profile'
+import { postAnchor } from './post-link'
+import { formatDate, formatTime, untranslated } from './time'
+import { filterWords } from './word-filter'
+
+export interface PostCapabilities {
+  readonly viewerUserId: number | null
+  readonly editOwn: boolean
+  readonly editOthers: boolean
+  readonly softDelete: boolean
+  readonly restore: boolean
+  readonly editWindowMinutes: number
+  readonly bypassesWindow: boolean
+  readonly canReport: boolean
+  readonly canWarn: boolean
+  readonly canRate?: boolean
+  readonly ratingNeedsForm?: boolean
+}
+
+const NO_CAPABILITIES: PostCapabilities = {
+  viewerUserId: null,
+  editOwn: false,
+  editOthers: false,
+  softDelete: false,
+  restore: false,
+  editWindowMinutes: 0,
+  bypassesWindow: false,
+  canReport: false,
+  canWarn: false,
+  canRate: false,
+  ratingNeedsForm: true,
+}
+
+function withinEditWindow(
+  post: PostListingRow,
+  capabilities: PostCapabilities,
+  now: Date,
+): boolean {
+  if (capabilities.bypassesWindow || capabilities.editWindowMinutes <= 0) return true
+  const elapsed = (now.getTime() - post.createdAt.getTime()) / 60_000
+  return elapsed <= capabilities.editWindowMinutes
+}
+
+interface PostContext {
+  readonly now: Date
+  readonly replyHref: string | null
+  readonly capabilities: PostCapabilities
+  readonly t: Translator | undefined
+  readonly fields: ReadonlyMap<number, readonly { label: string; value: string }[]>
+  readonly signatures: ReadonlyMap<number, string>
+  readonly avatars: ReadonlyMap<number, string>
+  readonly identities: ReadonlyMap<number, MemberIdentity>
+  readonly ignoredIds: ReadonlySet<number>
+  readonly revealedPostIds: ReadonlySet<number>
+  readonly revealHref: (postId: number, number: number) => string
+  readonly wordFilter: CompiledWordFilter | undefined
+  readonly vocabulary: BoardVocabulary | undefined
+  readonly attachments: ReadonlyMap<number, readonly PostAttachmentModel[]>
+}
+
+function post(post: PostListingRow, thread: ThreadListingRow, context: PostContext): PostBitModel {
+  const { now, replyHref, capabilities, t, fields, signatures } = context
+  const isOwn =
+    capabilities.viewerUserId !== null && post.authorUserId === capabilities.viewerUserId
+  const manageHref = `/thread/${thread.id}-${thread.slug}/edit?post=${post.id}`
+
+  const hidden = suppress({
+    authorUserId: post.authorUserId,
+    viewerUserId: capabilities.viewerUserId,
+    ignoredIds: context.ignoredIds,
+    revealedPostIds: context.revealedPostIds,
+    postId: post.id,
+  })
+
+  const identity =
+    post.authorUserId === null ? undefined : context.identities.get(post.authorUserId)
+
+  const mayEdit =
+    post.visibility !== 'deleted' &&
+    (isOwn
+      ? capabilities.editOwn && withinEditWindow(post, capabilities, now)
+      : capabilities.editOthers)
+
+  return {
+    id: post.id,
+    number: post.number,
+    permalink: `/thread/${thread.id}-${thread.slug}#${postAnchor(post.number)}`,
+    quoteSource: hidden ? '' : post.message,
+    author: {
+      userId: post.authorUserId,
+      username: post.authorUsername,
+      profileHref: post.authorUserId === null ? null : memberHref(post.authorUserId),
+      avatarUrl:
+        hidden || post.authorUserId === null
+          ? null
+          : (context.avatars.get(post.authorUserId) ?? null),
+      title: identity?.title ?? null,
+      nameClass: identity?.nameClass ?? null,
+      badge: identity?.badge ?? null,
+      reputation: identity?.reputation === undefined ? null : count(identity.reputation, t),
+      postCount: count(post.authorPostCount, t),
+      joinedAt: post.authorJoinedAt === null ? null : formatDate(post.authorJoinedAt, t),
+      signatureHtml:
+        hidden || post.authorUserId === null ? null : (signatures.get(post.authorUserId) ?? null),
+      isOnline: false,
+      fields: hidden || post.authorUserId === null ? [] : (fields.get(post.authorUserId) ?? []),
+    },
+    bodyHtml: hidden
+      ? ''
+      : filterWords(
+          postBodyHtml(post, context.vocabulary, {
+            quoteAttribution:
+              t === undefined
+                ? undefined
+                : (author) => t.t('markdown.quote.attribution', { author }),
+          }),
+          context.wordFilter,
+        ),
+    postedAt: formatTime(post.createdAt, now, t),
+    editedNote: editedNote(
+      { editedAt: post.editedAt, editedByUsername: post.editedByUsername, reason: post.editReason },
+      (at) => formatTime(at, now, t).label,
+    ),
+    isFirstPost: post.isFirstPost,
+    visibility: post.visibility,
+    attachments: hidden ? [] : (context.attachments.get(post.id) ?? []),
+    ignored: hidden
+      ? {
+          authorUsername: post.authorUsername,
+          revealHref: context.revealHref(post.id, post.number),
+        }
+      : null,
+    actions: {
+      quoteHref:
+        replyHref === null || post.visibility !== 'visible' || hidden
+          ? null
+          : `${replyHref}?quote=${post.id}`,
+      editHref: mayEdit ? manageHref : null,
+      restoreHref: post.visibility === 'deleted' && capabilities.restore ? manageHref : null,
+      historyHref:
+        post.editedAt !== null && (isOwn || capabilities.editOthers)
+          ? `/thread/${thread.id}-${thread.slug}/post/${post.id}/history`
+          : null,
+      reportHref:
+        capabilities.canReport && !isOwn && post.visibility === 'visible'
+          ? `/report?kind=post&id=${post.id}`
+          : null,
+      warnHref:
+        capabilities.canWarn && !isOwn && post.authorUserId !== null
+          ? `/moderation/warn?user=${post.authorUserId}&post=${post.id}`
+          : null,
+      rateHref:
+        capabilities.canRate === true &&
+        !isOwn &&
+        post.authorUserId !== null &&
+        !hidden &&
+        capabilities.ratingNeedsForm !== false
+          ? `/member/${post.authorUserId}/reputation?post=${post.id}`
+          : null,
+      moderateHref: null,
+    },
+  }
+}
+
+export interface ThreadViewInput {
+  readonly thread: ThreadListingRow
+  readonly forum: ForumRow
+  readonly page: PostPage
+  readonly pageNumber: number
+  readonly pagination?: PaginationModel
+  readonly nextHref: string | null
+  readonly markReadAction?: string | null
+  readonly replyHref?: string | null
+  readonly capabilities?: PostCapabilities
+  readonly now: Date
+  readonly t?: Translator
+  readonly authorFields?: ReadonlyMap<number, readonly { label: string; value: string }[]>
+  readonly signatures?: ReadonlyMap<number, string>
+  readonly avatars?: ReadonlyMap<number, string>
+  readonly identities?: ReadonlyMap<number, MemberIdentity>
+  readonly attachments?: ReadonlyMap<number, readonly PostAttachmentModel[]>
+  readonly ignoredIds?: ReadonlySet<number>
+  readonly revealedPostIds?: ReadonlySet<number>
+  readonly wordFilter?: CompiledWordFilter | undefined
+  readonly vocabulary?: BoardVocabulary | undefined
+  readonly currentHref?: string
+}
+
+const EMPTY_IDS: ReadonlySet<number> = new Set()
+const EMPTY_SIGNATURES: ReadonlyMap<number, string> = new Map()
+const EMPTY_ATTACHMENTS: ReadonlyMap<number, readonly PostAttachmentModel[]> = new Map()
+const EMPTY_AVATARS: ReadonlyMap<number, string> = new Map()
+const EMPTY_IDENTITIES: ReadonlyMap<number, MemberIdentity> = new Map()
+
+export function revealHref(currentHref: string, postId: number, number: number): string {
+  const [path = '', hash] = currentHref.split('#')
+  void hash
+  const separator = path.includes('?') ? '&' : '?'
+  return `${path}${separator}reveal=${postId}#${postAnchor(number)}`
+}
+
+export function threadToolsHeading(
+  isForumModerator: boolean,
+  t: Translator = untranslated(),
+): string {
+  return t.t(isForumModerator ? 'thread.moderatorTools' : 'thread.threadTools')
+}
+
+export function revealedFrom(raw: string | readonly string[] | undefined): ReadonlySet<number> {
+  if (raw === undefined) return EMPTY_IDS
+  const values = typeof raw === 'string' ? [raw] : raw
+  const ids = new Set<number>()
+  for (const value of values) {
+    for (const part of value.split(',')) {
+      const id = Number(part)
+      if (Number.isInteger(id) && id > 0) ids.add(id)
+    }
+  }
+  return ids
+}
+
+export interface ThreadView {
+  readonly view: Omit<ThreadViewModel, 'regions'>
+  readonly posts: readonly PostBitModel[]
+  readonly pagination: PaginationModel
+}
+
+export function buildThreadView(input: ThreadViewInput): ThreadView {
+  return {
+    view: {
+      thread: threadRowModel(input.thread, input.now, null, input.t),
+      forum: { label: input.forum.title, href: forumHref(input.forum) },
+      replyHref: input.replyHref ?? null,
+      markReadAction: input.markReadAction ?? null,
+    },
+    posts: input.page.rows.map((entry) =>
+      post(entry, input.thread, {
+        now: input.now,
+        replyHref: input.replyHref ?? null,
+        capabilities: input.capabilities ?? NO_CAPABILITIES,
+        t: input.t,
+        fields: input.authorFields ?? new Map(),
+        signatures: input.signatures ?? EMPTY_SIGNATURES,
+        attachments: input.attachments ?? EMPTY_ATTACHMENTS,
+        avatars: input.avatars ?? EMPTY_AVATARS,
+        identities: input.identities ?? EMPTY_IDENTITIES,
+        ignoredIds: input.ignoredIds ?? EMPTY_IDS,
+        revealedPostIds: input.revealedPostIds ?? EMPTY_IDS,
+        revealHref: (postId, number) => revealHref(input.currentHref ?? '', postId, number),
+        wordFilter: input.wordFilter,
+        vocabulary: input.vocabulary,
+      }),
+    ),
+    pagination: input.pagination ?? {
+      page: input.pageNumber,
+      pageCount: input.pageNumber,
+      pageCountIsExact: false,
+      pages: [{ page: input.pageNumber, href: '', isCurrent: true }],
+      previousHref: null,
+      nextHref: input.nextHref,
+    },
+  }
+}

package/src/view/time.ts

@@ -0,0 +1,31 @@
+import {
+  DEFAULT_TIME_ZONE,
+  EN_CATALOG,
+  formatDay,
+  formatTimestamp,
+  sourceTranslator,
+  type Translator,
+} from '@meith/i18n'
+import type { TimeModel } from '@meith/theme-kit'
+
+export const DEFAULT_TIMEZONE = DEFAULT_TIME_ZONE
+
+export function untranslated(timeZone: string = DEFAULT_TIMEZONE): Translator {
+  return sourceTranslator(EN_CATALOG, timeZone)
+}
+
+export function formatTime(
+  at: Date,
+  now: Date,
+  translator: Translator = untranslated(),
+): TimeModel {
+  return formatTimestamp(at, now, translator)
+}
+
+export function formatDate(at: Date, translator: Translator = untranslated()): TimeModel {
+  return formatDay(at, translator)
+}
+
+export function timezoneLabel(timeZone: string): string {
+  return timeZone.replace(/_/g, ' ')
+}

package/src/view/timezone.ts

@@ -0,0 +1,35 @@
+import { AUTOMATIC_TIMEZONE, isKnownTimezone } from '@meith/accounts'
+
+import { DEFAULT_TIMEZONE } from './time'
+
+export const TIMEZONE_COOKIE = 'meith_tz'
+
+export interface ResolvedTimezone {
+  readonly zone: string
+  readonly isAutomatic: boolean
+}
+
+export function detectedTimezone(value: string | null | undefined): string | null {
+  if (typeof value !== 'string') return null
+
+  const zone = value.trim()
+  if (zone === '' || zone === AUTOMATIC_TIMEZONE) return null
+
+  return isKnownTimezone(zone) ? zone : null
+}
+
+export function resolveTimezone(input: {
+  readonly stored?: string | null | undefined
+  readonly detected?: string | null | undefined
+}): ResolvedTimezone {
+  const stored = input.stored ?? null
+
+  if (stored !== null && stored !== AUTOMATIC_TIMEZONE && isKnownTimezone(stored)) {
+    return { zone: stored, isAutomatic: false }
+  }
+
+  return {
+    zone: detectedTimezone(input.detected) ?? DEFAULT_TIMEZONE,
+    isAutomatic: true,
+  }
+}

package/src/view/two-factor.ts

@@ -0,0 +1,6 @@
+/**
+ * The form-state key the fresh recovery codes travel back under. It lives here
+ * rather than beside the action because a `'use server'` module may export
+ * nothing but async functions, and the client component needs to read it.
+ */
+export const RECOVERY_CODES_FIELD = 'recoveryCodes'