@better-forge/ui 0.0.0-stage → 0.1.1

package/src/components/ui/Pagination.tsx

@@ -0,0 +1,37 @@
+import type { ReactNode } from 'react'
+
+type PaginationProps = {
+  /** 1-based current page. */
+  page: number
+  onPageChange: (page: number) => void
+  /** Text on the left, e.g. "Page 2 of 5 · 93 entries". Defaults to "Page X of Y" when pageCount is known. */
+  summary?: ReactNode | undefined
+  /** Hide the whole bar when there is only one page (default true; ignored with hasNext). */
+  hideWhenSingle?: boolean | undefined
+} & (
+  | { pageCount: number; hasNext?: never }
+  /** For cursor/unknown-total lists: whether a next page exists. */
+  | { hasNext: boolean; pageCount?: never }
+)
+
+export function Pagination({ page, onPageChange, summary, hideWhenSingle = true, pageCount, hasNext }: PaginationProps) {
+  const canPrev = page > 1
+  const canNext = pageCount !== undefined ? page < pageCount : Boolean(hasNext)
+  if (pageCount !== undefined && hideWhenSingle && pageCount <= 1) return null
+
+  const text = summary ?? (pageCount !== undefined ? `Page ${page} of ${pageCount}` : `Page ${page}`)
+
+  return (
+    <nav aria-label="Pagination" className="flex flex-wrap items-center justify-between gap-3">
+      <span className="text-sm" style={{ color: 'var(--m3-secondary)' }}>{text}</span>
+      <div className="flex gap-2">
+        <button type="button" onClick={() => onPageChange(page - 1)} disabled={!canPrev} aria-label="Previous page" className="btn btn-outline btn-sm text-sm font-normal">
+          ← Prev
+        </button>
+        <button type="button" onClick={() => onPageChange(page + 1)} disabled={!canNext} aria-label="Next page" className="btn btn-outline btn-sm text-sm font-normal">
+          Next →
+        </button>
+      </div>
+    </nav>
+  )
+}

package/src/components/ui/QuickStartPanel.tsx

@@ -0,0 +1,57 @@
+import { useId, type ReactNode } from 'react'
+
+export interface QuickStartOption<K extends string> {
+  key: K
+  label: string
+  hint: string
+  /** Icon element (a Material Symbol or a brand glyph), rendered inside the tile's icon chip. */
+  icon: ReactNode
+}
+
+interface QuickStartPanelProps<K extends string> {
+  title: string
+  description?: ReactNode | undefined
+  options: QuickStartOption<K>[]
+  onPick: (key: K) => void
+}
+
+/**
+ * First-run panel shown in place of an empty list when the first step is a choice, e.g. which kind of
+ * channel to create. Each tile starts the create flow with that choice already made.
+ */
+export function QuickStartPanel<K extends string>({ title, description, options, onPick }: QuickStartPanelProps<K>) {
+  const titleId = useId()
+  return (
+    <section
+      aria-labelledby={titleId}
+      className="rounded-2xl p-5 space-y-4"
+      style={{ background: 'var(--m3-surface-container-low)', border: '1px solid var(--m3-outline-variant)' }}
+    >
+      <div className="space-y-0.5">
+        <h2 id={titleId} className="font-headline font-semibold text-[15px]" style={{ color: 'var(--m3-on-surface)' }}>{title}</h2>
+        {description && <p className="text-[13px]" style={{ color: 'var(--m3-secondary)' }}>{description}</p>}
+      </div>
+      <ul className="grid gap-2.5 grid-cols-[repeat(auto-fill,minmax(150px,1fr))]">
+        {options.map((option) => (
+          <li key={option.key}>
+            <button
+              type="button"
+              onClick={() => onPick(option.key)}
+              className="w-full h-full grid gap-2 content-start text-left rounded-[14px] p-3.5 border border-outline-variant bg-surface text-on-surface hover:border-outline hover:bg-surface-container-lowest motion-safe:transition-colors focus-ring"
+            >
+              <span
+                className="grid place-items-center w-[34px] h-[34px] rounded-[10px]"
+                aria-hidden="true"
+                style={{ background: 'var(--admin-icon-container)', color: 'var(--admin-icon-color)' }}
+              >
+                {option.icon}
+              </span>
+              <span className="text-[13px] font-semibold">{option.label}</span>
+              <span className="text-xs" style={{ color: 'var(--m3-secondary)' }}>{option.hint}</span>
+            </button>
+          </li>
+        ))}
+      </ul>
+    </section>
+  )
+}

package/src/components/ui/StateViews.tsx

@@ -0,0 +1,135 @@
+import clsx from 'clsx'
+import type { CSSProperties, ReactNode } from 'react'
+
+interface LoadingStateProps {
+  label?: string | undefined
+  className?: string | undefined
+}
+
+/** Centered spinner with a caption for data that is still loading. */
+export function LoadingState({ label = 'Loading…', className }: LoadingStateProps) {
+  return (
+    <div role="status" aria-live="polite" className={clsx('flex items-center justify-center gap-3 py-12 text-sm', className)} style={{ color: 'var(--m3-secondary)' }}>
+      <span className="material-symbols-outlined animate-spin" aria-hidden="true" style={{ fontSize: '20px' }}>progress_activity</span>
+      <span>{label}</span>
+    </div>
+  )
+}
+
+interface ErrorStateProps {
+  message?: ReactNode | undefined
+  /** Renders a "Try again" button. Pass e.g. `() => void query.refetch()`. */
+  onRetry?: (() => void) | undefined
+  className?: string | undefined
+}
+
+/** Failed-to-load panel with an optional retry action. */
+export function ErrorState({ message = 'Something went wrong while loading this data.', onRetry, className }: ErrorStateProps) {
+  return (
+    <div
+      role="alert"
+      className={clsx('flex flex-col items-center justify-center gap-3 rounded-2xl px-6 py-10 text-center', className)}
+      style={{ background: 'var(--m3-down-bg)', color: 'var(--m3-down)' }}
+    >
+      <span className="material-symbols-outlined" aria-hidden="true" style={{ fontSize: '28px' }}>error</span>
+      <p className="text-sm max-w-md">{message}</p>
+      {onRetry && (
+        <button type="button" onClick={onRetry} className="btn btn-secondary btn-sm">
+          <span className="material-symbols-outlined" aria-hidden="true">refresh</span>
+          Try again
+        </button>
+      )}
+    </div>
+  )
+}
+
+type EmptyStateVariant = 'card' | 'inset' | 'row'
+
+interface EmptyStateProps {
+  title: ReactNode
+  description?: ReactNode | undefined
+  /** Material Symbols icon name, e.g. "radio_button_checked". */
+  icon?: string | undefined
+  /**
+   * Optional follow-up action. Leave it out when the page header already offers the same action and
+   * put an `EmptyStateLink` in the description instead.
+   */
+  action?: ReactNode | undefined
+  /**
+   * - `card` (default): a standalone compact strip, for pages without a table or list container.
+   * - `inset`: a row inside a card or list, separated from what is above it by a divider.
+   * - `row`: bare content for a table cell; use `EmptyTableRow` rather than this directly.
+   */
+  variant?: EmptyStateVariant | undefined
+  className?: string | undefined
+}
+
+const EMPTY_VARIANT_CLASS: Record<EmptyStateVariant, string> = {
+  card: 'rounded-2xl px-5 py-4',
+  inset: 'px-6 py-5',
+  row: '',
+}
+
+const EMPTY_VARIANT_STYLE: Record<EmptyStateVariant, CSSProperties | undefined> = {
+  card: { background: 'var(--m3-surface-container-low)', border: '1px solid var(--m3-outline-variant)' },
+  inset: { borderTop: '1px solid var(--m3-outline-variant)' },
+  row: undefined,
+}
+
+/** Compact placeholder for an empty list: an icon, a short explanation and an optional action in one row. */
+export function EmptyState({ title, description, icon = 'inbox', action, variant = 'card', className }: EmptyStateProps) {
+  return (
+    <div
+      className={clsx('flex flex-wrap items-center gap-x-3.5 gap-y-3 text-left', EMPTY_VARIANT_CLASS[variant], className)}
+      style={EMPTY_VARIANT_STYLE[variant]}
+    >
+      <span
+        className="grid place-items-center w-10 h-10 rounded-xl flex-none"
+        aria-hidden="true"
+        style={{ background: 'var(--admin-icon-container)', color: 'var(--admin-icon-color)' }}
+      >
+        <span className="material-symbols-outlined" style={{ fontSize: '20px' }}>{icon}</span>
+      </span>
+      <div className="min-w-0 flex-[1_1_15rem] space-y-0.5">
+        <p className="font-headline font-semibold text-sm" style={{ color: 'var(--m3-on-surface)' }}>{title}</p>
+        {description && <p className="text-[13px]" style={{ color: 'var(--m3-secondary)' }}>{description}</p>}
+      </div>
+      {action && <div className="flex-none sm:ml-auto">{action}</div>}
+    </div>
+  )
+}
+
+interface EmptyTableRowProps extends Omit<EmptyStateProps, 'variant' | 'className'> {
+  /** Number of columns in the table, so the message spans the whole row. */
+  colSpan: number
+}
+
+/** The only `<tbody>` row while a table has no data, so the table and its headers keep their place. */
+export function EmptyTableRow({ colSpan, ...props }: EmptyTableRowProps) {
+  return (
+    <tr>
+      <td colSpan={colSpan} className="px-4 py-7">
+        <EmptyState variant="row" {...props} />
+      </td>
+    </tr>
+  )
+}
+
+interface EmptyStateLinkProps {
+  onClick: () => void
+  children: ReactNode
+}
+
+/** Inline text action inside an empty-state description, e.g. "Alerts stay silent until you [add a channel]." */
+export function EmptyStateLink({ onClick, children }: EmptyStateLinkProps) {
+  return (
+    <button
+      type="button"
+      onClick={onClick}
+      className="font-semibold underline underline-offset-[3px] rounded focus-ring"
+      style={{ color: 'var(--m3-on-surface)' }}
+    >
+      {children}
+    </button>
+  )
+}

package/src/components/ui/Switch.tsx

@@ -0,0 +1,65 @@
+import clsx from 'clsx'
+import { useId, type ReactNode } from 'react'
+
+interface SwitchProps {
+  checked: boolean
+  onChange: (checked: boolean) => void
+  /** Visible label; clicking it toggles the switch. Without it pass `aria-label`. */
+  label?: ReactNode | undefined
+  description?: ReactNode | undefined
+  disabled?: boolean | undefined
+  id?: string | undefined
+  'aria-label'?: string | undefined
+  className?: string | undefined
+}
+
+/** On/off toggle rendered as <button role="switch">, optionally with a clickable label and a description. */
+export function Switch({ checked, onChange, label, description, disabled = false, id, 'aria-label': ariaLabel, className }: SwitchProps) {
+  const generatedId = useId()
+  const switchId = id ?? generatedId
+  const labelId = `${switchId}-label`
+  const descriptionId = `${switchId}-description`
+
+  const control = (
+    <button
+      id={switchId}
+      type="button"
+      role="switch"
+      aria-checked={checked}
+      aria-label={label ? undefined : ariaLabel}
+      aria-labelledby={label ? labelId : undefined}
+      aria-describedby={description ? descriptionId : undefined}
+      disabled={disabled}
+      onClick={() => onChange(!checked)}
+      className="relative flex-shrink-0 w-12 h-7 rounded-full transition-colors focus-ring disabled:opacity-50 disabled:cursor-not-allowed"
+      style={{ background: checked ? 'var(--admin-control-accent)' : 'var(--m3-outline-variant)' }}
+    >
+      <span
+        aria-hidden="true"
+        className="absolute top-1 w-5 h-5 rounded-full transition-all"
+        style={{ left: checked ? '24px' : '4px', background: checked ? 'var(--admin-control-on)' : 'var(--m3-outline)' }}
+      />
+    </button>
+  )
+
+  if (!label && !description) return <span className={clsx('inline-flex', className)}>{control}</span>
+
+  return (
+    <div className={clsx('flex items-start justify-between gap-4', className)}>
+      <div className="min-w-0">
+        {label && (
+          <label
+            id={labelId}
+            htmlFor={switchId}
+            className={clsx('block text-sm font-medium', disabled ? 'cursor-not-allowed' : 'cursor-pointer')}
+            style={{ color: 'var(--m3-on-surface)' }}
+          >
+            {label}
+          </label>
+        )}
+        {description && <p id={descriptionId} className="text-xs mt-0.5" style={{ color: 'var(--m3-secondary)' }}>{description}</p>}
+      </div>
+      {control}
+    </div>
+  )
+}

package/src/components/ui/Toast.tsx

@@ -0,0 +1,104 @@
+import { createContext, useCallback, useContext, useEffect, useMemo, useRef, useState, type ReactNode } from 'react'
+import { createPortal } from 'react-dom'
+import { MODAL_Z_INDEX } from '../ModalShell'
+
+export type ToastTone = 'success' | 'error' | 'info'
+
+export interface ToastOptions {
+  /** Milliseconds before it disappears on its own; 0 keeps it until dismissed. Default 4000. */
+  duration?: number | undefined
+}
+
+export interface ToastApi {
+  success: (message: ReactNode, options?: ToastOptions) => number
+  error: (message: ReactNode, options?: ToastOptions) => number
+  info: (message: ReactNode, options?: ToastOptions) => number
+  dismiss: (id: number) => void
+}
+
+interface ToastEntry { id: number; tone: ToastTone; message: ReactNode; duration: number }
+
+export const TOAST_DURATION = 4000
+
+const noop: ToastApi = { success: () => 0, error: () => 0, info: () => 0, dismiss: () => {} }
+
+// Outside a provider (isolated component tests) toasts are silently dropped instead of throwing.
+const ToastContext = createContext<ToastApi>(noop)
+
+/** `const toast = useToast(); toast.success('Saved')`. The returned object is stable across renders. */
+export function useToast(): ToastApi {
+  return useContext(ToastContext)
+}
+
+const TONE_STYLE: Record<ToastTone, { icon: string; color: string }> = {
+  success: { icon: 'check_circle', color: 'var(--m3-up)' },
+  error:   { icon: 'error',        color: 'var(--m3-down)' },
+  info:    { icon: 'info',         color: 'var(--m3-on-surface-variant)' },
+}
+
+function ToastItem({ toast, onDismiss }: { toast: ToastEntry; onDismiss: (id: number) => void }) {
+  const [paused, setPaused] = useState(false)
+  const { icon, color } = TONE_STYLE[toast.tone]
+
+  useEffect(() => {
+    if (paused || toast.duration <= 0) return
+    const timer = setTimeout(() => onDismiss(toast.id), toast.duration)
+    return () => clearTimeout(timer)
+  }, [paused, toast.duration, toast.id, onDismiss])
+
+  return (
+    <div
+      role={toast.tone === 'error' ? 'alert' : 'status'}
+      data-tone={toast.tone}
+      className="admin-toast pointer-events-auto flex items-start gap-3 rounded-xl px-4 py-3 text-sm w-full"
+      style={{ background: 'var(--m3-surface-container-lowest)', color: 'var(--m3-on-surface)', border: '1px solid var(--m3-outline-variant)', borderLeft: `4px solid ${color}`, boxShadow: '0 8px 24px rgba(0,0,0,0.14)' }}
+      onMouseEnter={() => setPaused(true)}
+      onMouseLeave={() => setPaused(false)}
+      onFocus={() => setPaused(true)}
+      onBlur={() => setPaused(false)}
+    >
+      <span className="material-symbols-outlined flex-shrink-0 mt-px" aria-hidden="true" style={{ fontSize: '18px', color }}>{icon}</span>
+      <div className="flex-1 min-w-0 break-words">{toast.message}</div>
+      <button type="button" onClick={() => onDismiss(toast.id)} aria-label="Dismiss" className="btn-icon -my-1 -mr-2 w-7 h-7">
+        <span className="material-symbols-outlined" aria-hidden="true" style={{ fontSize: '16px' }}>close</span>
+      </button>
+    </div>
+  )
+}
+
+/** Mount once near the root; renders the bottom-right toast stack above every modal. */
+export function ToastProvider({ children }: { children: ReactNode }) {
+  const [toasts, setToasts] = useState<ToastEntry[]>([])
+  const nextId = useRef(1)
+
+  const dismiss = useCallback((id: number) => {
+    setToasts((current) => current.filter((toast) => toast.id !== id))
+  }, [])
+
+  const api = useMemo<ToastApi>(() => {
+    const push = (tone: ToastTone) => (message: ReactNode, options?: ToastOptions) => {
+      const id = nextId.current++
+      setToasts((current) => [...current.slice(-4), { id, tone, message, duration: options?.duration ?? TOAST_DURATION }])
+      return id
+    }
+    return { success: push('success'), error: push('error'), info: push('info'), dismiss }
+  }, [dismiss])
+
+  return (
+    <ToastContext.Provider value={api}>
+      {children}
+      {createPortal(
+        <div
+          role="region"
+          aria-live="polite"
+          aria-label="Notifications"
+          className="fixed bottom-4 right-4 left-4 sm:left-auto sm:w-96 flex flex-col items-end gap-2 pointer-events-none"
+          style={{ zIndex: MODAL_Z_INDEX + 1 }}
+        >
+          {toasts.map((toast) => <ToastItem key={toast.id} toast={toast} onDismiss={dismiss} />)}
+        </div>,
+        document.body,
+      )}
+    </ToastContext.Provider>
+  )
+}

package/src/components/ui/index.ts

@@ -0,0 +1,9 @@
+export { Alert, type AlertTone } from './Alert'
+export { Field, type FieldControlProps } from './Field'
+export { PageContainer, PageHeader } from './PageHeader'
+export { QuickStartPanel, type QuickStartOption } from './QuickStartPanel'
+export { Pagination } from './Pagination'
+export { DataTable, DataTh, MAX_COLUMN_WIDTH, MIN_COLUMN_WIDTH, ResizeHandle, useTableSort, type SortDirection, type SortValue, type TableSort } from './DataTable'
+export { EmptyState, EmptyStateLink, EmptyTableRow, ErrorState, LoadingState } from './StateViews'
+export { Switch } from './Switch'
+export { TOAST_DURATION, ToastProvider, useToast, type ToastApi, type ToastOptions, type ToastTone } from './Toast'

package/src/config.ts

@@ -0,0 +1,46 @@
+export interface UiConfig {
+  /** Names what the interface keeps in the browser: keys in storage and window events start with it (`<prefix>-dark-mode`). */
+  storagePrefix: string
+  /** Where the API answers. */
+  apiBase: string
+  /** The cookie the server puts the CSRF token in; it is sent back in a header on every change. */
+  csrfCookie: string
+  /** Where the interface is served, without a trailing slash (`/admin`): the pages to sign in and to change a password are below it. */
+  basePath: string
+  /** For a user who does not belong in this interface (say, one who may only view a public page): the address to send them to instead. */
+  redirectAfterSignIn?: (user: { role: string }) => string | null
+  /** The names and pictures the application is known by. */
+  brand: { name: string; logoLight: string; logoDark: string }
+  /** Wording that names things only the application knows. */
+  texts: {
+    /** What an API token can never manage, in the sentence "It cannot manage ..." (for example `users, single sign-on, vaults or other tokens`). */
+    tokenCannotManage: string
+    /** What a token with the vault permission can attach a vault secret to (`a job or channel`). */
+    tokenVaultTargets: string
+    /** Said when a test sign-in would create an account; `{user}` is replaced by the account. */
+    ssoNewAccount: string
+    /** Added to the single sign-on settings to say who may sign in; empty adds nothing. */
+    ssoSignInHint: string
+    /** The name of the application, as the interface calls it in sentences. */
+    appName: string
+    /** What uses the secrets kept in a vault (`jobs`), in sentences like "... that jobs can use". */
+    secretConsumers: string
+    /** An example of the path of a secret in an external vault. */
+    vaultPathExample: string
+  }
+}
+
+let current: UiConfig = { storagePrefix: 'better', apiBase: '/api/v1', csrfCookie: 'better_csrf', basePath: '', brand: { name: 'Better', logoLight: '', logoDark: '' }, texts: { ssoNewAccount: 'Creates the account {user} and links this identity-provider account to it.', ssoSignInHint: '', appName: 'This application', secretConsumers: 'the application', vaultPathExample: 'app/database', tokenCannotManage: 'users, single sign-on, vaults or other tokens', tokenVaultTargets: 'an object' } }
+
+/**
+ * Tells the interface what application it is part of. Call it before anything is rendered; what is read from storage
+ * is read on first use, after this.
+ */
+export function configureUi(options: Partial<UiConfig>): void {
+  current = { ...current, ...options }
+}
+
+export const uiConfig = (): UiConfig => current
+
+/** The name the interface uses for `name` in storage and in window events. */
+export const storageKey = (name: string): string => `${current.storagePrefix}-${name}`

package/src/hooks/useDarkMode.ts

@@ -0,0 +1,38 @@
+import { useState, useEffect } from 'react'
+import { safeLocalStorage } from '@better-forge/contracts'
+import { storageKey } from '../config'
+
+// The public status app keeps a copy of this hook with the same behaviour, since it does not use this package.
+
+export function useDarkMode(): [boolean, () => void] {
+  const [isDark, setIsDark] = useState(() => {
+    if (typeof window === 'undefined') return false
+    const stored = safeLocalStorage.get(storageKey('dark-mode'))
+    if (stored !== null) return stored === 'true'
+    return window.matchMedia('(prefers-color-scheme: dark)').matches
+  })
+
+  useEffect(() => {
+    const html = document.documentElement
+    if (isDark) {
+      html.classList.add('dark')
+    } else {
+      html.classList.remove('dark')
+    }
+    safeLocalStorage.set(storageKey('dark-mode'), String(isDark))
+    // Every mounted instance (e.g. the sidebar toggle and a page that swaps its logo) listens for this, so one toggle
+    // updates them all.
+    window.dispatchEvent(new CustomEvent(storageKey('dark-mode-change'), { detail: isDark }))
+  }, [isDark])
+
+  useEffect(() => {
+    const handler = (e: Event) => {
+      const dark = (e as CustomEvent<boolean>).detail
+      setIsDark(dark)
+    }
+    window.addEventListener(storageKey('dark-mode-change'), handler)
+    return () => window.removeEventListener(storageKey('dark-mode-change'), handler)
+  }, [])
+
+  return [isDark, () => setIsDark((d) => !d)]
+}

package/src/hooks/useDebouncedValue.ts

@@ -0,0 +1,22 @@
+import { useCallback, useEffect, useRef, useState } from 'react'
+
+/**
+ * Returns `value` once it has stopped changing for `delay` ms, plus a `flush` that applies it immediately
+ * (e.g. on Enter) or sets an explicit value (e.g. clearing a search box).
+ */
+export function useDebouncedValue<T>(value: T, delay = 300): [T, (next?: T) => void] {
+  const [debounced, setDebounced] = useState(value)
+  const latest = useRef(value)
+
+  useEffect(() => {
+    latest.current = value
+    const timer = setTimeout(() => setDebounced(value), delay)
+    return () => clearTimeout(timer)
+  }, [value, delay])
+
+  const flush = useCallback((next?: T) => {
+    setDebounced(next === undefined ? latest.current : next)
+  }, [])
+
+  return [debounced, flush]
+}

package/src/index.ts

@@ -0,0 +1,42 @@
+export * from './components/ui'
+export { ConfirmModal } from './components/ConfirmModal'
+export { ConfirmIdentityModal } from './components/ConfirmIdentityModal'
+export { ErrorBoundary, isChunkLoadError } from './components/ErrorBoundary'
+export { CopyButton } from './components/CopyButton'
+export { Modal, ModalFooter, ModalHeader, ModalShell, MODAL_BACKDROP, MODAL_Z_INDEX } from './components/ModalShell'
+export { SidePanelFrame, SideTabStrip, type SidePanelLayout, type SidePanelMeta, type SideTab } from './components/SidePanel'
+export { VaultTypePicker, VAULT_TYPE_ICONS, isReferenceVault, type VaultTypeValue } from './components/VaultTypePicker'
+export { useDebouncedValue } from './hooks/useDebouncedValue'
+export { compareVersions, parseChangelog, releasesBetween, summarizeRelease, type ReleaseGroup, type ReleaseItem, type ReleaseNotes, type ReleaseSummary } from './lib/changelog'
+export { configureUi, storageKey } from './config'
+export { useDarkMode } from './hooks/useDarkMode'
+export {
+  DATE_FORMATS, TIME_FORMATS, formatClock, formatDate, formatDateTime, formatDayMonth, getDatePrefs, setDatePrefs, useDatePrefs,
+  type DateFormat, type DatePrefs, type TimeFormat,
+} from './lib/dateFormat'
+export { uiConfig, type UiConfig } from './config'
+export { navigation } from './navigation'
+export {
+  ApiError, api, clearSession, enterAfterSignIn, getCurrentUser, isAuthenticated, mustChangePassword, setSession, type AuthUser,
+} from './api/client'
+export { WhatsNew, markWhatsNewSeen, pendingWhatsNew } from './components/WhatsNew'
+export { createAdminShell, type AdminShellConfig, type ExternalLink, type NavItem, type NavSection } from './shell/AdminShell'
+export { default as BackupsPage } from './pages/Backups'
+export { default as ChangePasswordPage } from './pages/ChangePassword'
+export { default as SettingsPage } from './pages/Settings'
+export { default as SsoConfirmPage } from './pages/SsoConfirm'
+export { default as SsoTestResultPage } from './pages/SsoTestResult'
+export { ResetTwoFactorModal } from './components/ResetTwoFactorModal'
+export { SingleSignOnModal } from './components/SingleSignOnModal'
+export {
+  ssoConfirmChannel, SsoConfirmationNote, isSsoConfirmationRequired, isSsoSession, useSsoConfirmation, type SsoConfirmationState,
+} from './components/SsoConfirmation'
+export { default as ApiTokensPage } from './pages/ApiTokens'
+export { default as AuditLogPage, type AuditEntities } from './pages/AuditLog'
+export { default as UsersPage, type UserRole, type UsersPageAction, type UsersPageProps } from './pages/Users'
+export { ConnectionStringSection, CredentialSection } from './components/CredentialSection'
+export { JSON_MAPPING_FIELDS, Note, SectionDivider, toggleInSet, type SecretSummary, type VaultPickerProps, type VaultSummary } from './components/formParts'
+export { default as VaultPage } from './pages/Vault'
+export { default as LoginPage, type LoginPageProps } from './pages/Login'
+export { default as SetupPage } from './pages/Setup'
+export { RequireAuth, RequirePasswordChanged, SetupGate, createRoleGuard } from './shell/guards'

package/src/lib/changelog.ts

@@ -0,0 +1,93 @@
+export interface ReleaseItem {
+  title: string
+  summary: string
+}
+
+export interface ReleaseGroup {
+  heading: string
+  items: ReleaseItem[]
+}
+
+export interface ReleaseNotes {
+  version: string
+  date: string
+  groups: ReleaseGroup[]
+}
+
+const RELEASE_HEADING = /^## \[(\d+\.\d+\.\d+)\](?: - (\S+))?\s*$/
+const GROUP_HEADING = /^### (.+?)\s*$/
+const ITEM = /^- (?:\*\*(.+?)\*\*:?\s*)?(.*)$/
+
+function plain(text: string): string {
+  return text.replace(/\[([^\]]+)\]\([^)]*\)/g, '$1').replace(/[`*]/g, '').trim()
+}
+
+function firstSentence(text: string): string {
+  const match = /^(.+?[.!?])(?:\s|$)/.exec(text)
+  return plain(match ? match[1]! : text)
+}
+
+/**
+ * Released sections of docs/changelog.md, newest first; each top-level bullet is cut down to its bold title and
+ * the first sentence of its text. The Unreleased section and nested bullets are left out.
+ */
+export function parseChangelog(markdown: string): ReleaseNotes[] {
+  const releases: ReleaseNotes[] = []
+  let release: ReleaseNotes | null = null
+  let group: ReleaseGroup | null = null
+  for (const line of markdown.split(/\r?\n/)) {
+    const releaseMatch = RELEASE_HEADING.exec(line)
+    if (releaseMatch) {
+      release = { version: releaseMatch[1]!, date: releaseMatch[2] ?? '', groups: [] }
+      releases.push(release)
+      group = null
+    } else if (line.startsWith('## ')) {
+      release = null
+    } else if (release) {
+      const groupMatch = GROUP_HEADING.exec(line)
+      if (groupMatch) {
+        group = { heading: groupMatch[1]!, items: [] }
+        release.groups.push(group)
+        continue
+      }
+      const item = group ? ITEM.exec(line) : null
+      if (item && group) group.items.push({ title: plain(item[1] ?? ''), summary: firstSentence(item[2] ?? '') })
+    }
+  }
+  return releases.map((r) => ({ ...r, groups: r.groups.filter((g) => g.items.length > 0) }))
+}
+
+/** Negative, zero or positive like a sort comparator; plain x.y.z versions only. */
+export function compareVersions(a: string, b: string): number {
+  const left = a.split('.').map(Number)
+  const right = b.split('.').map(Number)
+  for (let i = 0; i < 3; i++) {
+    const diff = (left[i] ?? 0) - (right[i] ?? 0)
+    if (diff !== 0) return diff
+  }
+  return 0
+}
+
+/** Releases after `seen` up to and including `current`, newest first. */
+export function releasesBetween(releases: ReleaseNotes[], seen: string, current: string): ReleaseNotes[] {
+  return releases.filter((r) => compareVersions(r.version, seen) > 0 && compareVersions(r.version, current) <= 0)
+}
+
+export interface ReleaseSummary {
+  version: string
+  added: ReleaseItem[]
+  /** Changed, Removed and any other kind of entry that is not new or a fix. */
+  changed: ReleaseItem[]
+  fixed: ReleaseItem[]
+}
+
+/** One release sorted by the kind of change; fixes are only counted. */
+export function summarizeRelease(release: ReleaseNotes): ReleaseSummary {
+  const summary: ReleaseSummary = { version: release.version, added: [], changed: [], fixed: [] }
+  for (const group of release.groups) {
+    if (group.heading === 'Added') summary.added.push(...group.items)
+    else if (group.heading === 'Fixed') summary.fixed.push(...group.items)
+    else summary.changed.push(...group.items)
+  }
+  return summary
+}