@hraness/design-kit 0.31.1

package/src/react/theme.tsx

@@ -0,0 +1,402 @@
+"use client";
+
+import {
+  AppearanceIcon,
+  IconButton,
+  Menu,
+  MenuItem,
+  MenuTrigger,
+  SegmentedControl,
+  cn,
+  type SegmentedItem,
+} from "@hraness/ui";
+import * as stylex from "@stylexjs/stylex";
+import { ThemeProvider as NextThemeProvider, useTheme } from "next-themes";
+import {
+  type ReactNode,
+  useEffect,
+  useRef,
+  useSyncExternalStore,
+} from "react";
+
+import {
+  type ConcreteDesignTheme,
+  defaultDesignTheme,
+  type DesignTheme,
+  type DesignThemeLabels,
+  designThemeLabel,
+  designThemeStorageKey,
+  designThemes,
+  isDesignTheme,
+  normalizeDesignTheme,
+} from "../appearance.js";
+import { colors } from "../index.js";
+import { DesignPaletteMenuButton, useDesignPalette } from "./design-palette.js";
+import {
+  DesignPortalThemeProvider,
+  useDesignPortalClassName,
+} from "./design-theme-context.js";
+import { resolveEffectiveTheme } from "./theme-resolution.js";
+import { themeStyles } from "./theme.stylex.js";
+import {
+  acquireThemeColorMeta,
+  type ThemeColorMetaRegistration,
+} from "./theme-color-sync.js";
+
+export {
+  type ConcreteDesignTheme,
+  defaultDesignTheme,
+  type DesignTheme,
+  designThemeStorageKey,
+  designThemes,
+  isDesignTheme,
+  normalizeDesignTheme,
+} from "../appearance.js";
+
+const concreteThemes = ["light", "dark"] as const;
+const emptySubscribe = (): (() => void) => () => undefined;
+
+function useHydrated(): boolean {
+  return useSyncExternalStore(emptySubscribe, () => true, () => false);
+}
+
+function themeStorageGuardScript(storageKey: string): string {
+  const serializedKey = JSON.stringify(storageKey)
+    .replaceAll("<", "\\u003c")
+    .replaceAll("\u2028", "\\u2028")
+    .replaceAll("\u2029", "\\u2029");
+  return `(()=>{try{const key=${serializedKey};const value=localStorage.getItem(key);if(value!==null&&value!=="light"&&value!=="dark"&&value!=="system")localStorage.setItem(key,"${defaultDesignTheme}")}catch{}})();`;
+}
+
+function PersistedThemeNormalizer() {
+  const { setTheme, theme } = useTheme();
+
+  useEffect(() => {
+    if (theme !== undefined && !isDesignTheme(theme)) setTheme(defaultDesignTheme);
+  }, [setTheme, theme]);
+
+  return null;
+}
+
+function PortalThemeBridge({
+  children,
+  forcedTheme,
+}: Readonly<{
+  children: ReactNode;
+  forcedTheme: ConcreteDesignTheme | undefined;
+}>) {
+  const { resolvedTheme } = useTheme();
+  const portalTheme = resolveEffectiveTheme(forcedTheme, resolvedTheme);
+
+  return (
+    <DesignPortalThemeProvider theme={portalTheme}>
+      {children}
+    </DesignPortalThemeProvider>
+  );
+}
+
+export interface DesignThemeProviderProps {
+  readonly children: ReactNode;
+  /** Locks products with an explicit single-theme identity to one concrete theme. */
+  readonly forcedTheme?: ConcreteDesignTheme;
+  /** Applied to next-themes' blocking bootstrap script for strict CSPs. */
+  readonly nonce?: string;
+  /** Defaults to the shared, versioned browser preference key. */
+  readonly storageKey?: string;
+}
+
+/**
+ * Shared appearance boundary for browser products. System is the first-visit
+ * preference, while explicit Light, Dark, and System choices persist.
+ */
+export function DesignThemeProvider({
+  children,
+  forcedTheme,
+  nonce,
+  storageKey = designThemeStorageKey,
+}: DesignThemeProviderProps) {
+  return (
+    <>
+      {forcedTheme === undefined ? (
+        <script
+          {...(nonce === undefined ? {} : { nonce })}
+          data-hraness-design-theme-guard=""
+          dangerouslySetInnerHTML={{ __html: themeStorageGuardScript(storageKey) }}
+          suppressHydrationWarning
+        />
+      ) : null}
+      <NextThemeProvider
+        {...(nonce === undefined ? {} : { nonce })}
+        attribute="data-theme"
+        defaultTheme={forcedTheme ?? defaultDesignTheme}
+        disableTransitionOnChange
+        // next-themes captures this flag when its applying callback is created.
+        // Keep System resolvable after unforcing; forcedTheme still wins while set.
+        enableSystem
+        forcedTheme={forcedTheme}
+        storageKey={storageKey}
+        themes={[...concreteThemes]}
+      >
+        {forcedTheme === undefined ? <PersistedThemeNormalizer /> : null}
+        <PortalThemeBridge forcedTheme={forcedTheme}>{children}</PortalThemeBridge>
+      </NextThemeProvider>
+    </>
+  );
+}
+
+export type ThemeToggleLabels = DesignThemeLabels;
+export type ThemeToggleDisplay = "icons" | "labels";
+export type ThemeTogglePresentation = "menu" | "segmented";
+
+function themeToggleLabel(id: DesignTheme, labels?: ThemeToggleLabels): string {
+  return designThemeLabel(id, labels);
+}
+
+export function themeToggleItems(
+  labels?: ThemeToggleLabels,
+): readonly [SegmentedItem<DesignTheme>, ...SegmentedItem<DesignTheme>[]] {
+  return [
+    { id: "light", label: themeToggleLabel("light", labels) },
+    { id: "dark", label: themeToggleLabel("dark", labels) },
+    { id: "system", label: themeToggleLabel("system", labels) },
+  ];
+}
+
+function themeToggleIcon(id: DesignTheme): ReactNode {
+  return <AppearanceIcon name={id} />;
+}
+
+function themeToggleIconItems(
+  labels?: ThemeToggleLabels,
+): readonly [SegmentedItem<DesignTheme>, ...SegmentedItem<DesignTheme>[]] {
+  return [
+    {
+      ariaLabel: themeToggleLabel("light", labels),
+      id: "light",
+      label: themeToggleIcon("light"),
+    },
+    {
+      ariaLabel: themeToggleLabel("dark", labels),
+      id: "dark",
+      label: themeToggleIcon("dark"),
+    },
+    {
+      ariaLabel: themeToggleLabel("system", labels),
+      id: "system",
+      label: themeToggleIcon("system"),
+    },
+  ];
+}
+
+interface ThemeToggleBaseProps {
+  readonly "aria-label"?: string;
+  readonly className?: string;
+  readonly labels?: ThemeToggleLabels;
+  readonly size?: "compact" | "default";
+}
+
+type ThemeTogglePresentationProps =
+  | {
+    /** Three visible choices for settings and other surfaces with stable inline room. */
+    readonly display?: ThemeToggleDisplay;
+    readonly presentation?: "segmented";
+  }
+  | {
+    /** One bounded trigger for persistent chrome and text-enlargement reflow. */
+    readonly display?: never;
+    readonly presentation: "menu";
+  };
+
+type ThemeToggleControlProps =
+  | {
+    readonly onChange?: never;
+    readonly value?: never;
+  }
+  | {
+    readonly onChange: (theme: DesignTheme) => void;
+    readonly value: DesignTheme;
+  };
+
+export type ThemeToggleProps =
+  & ThemeToggleBaseProps
+  & ThemeToggleControlProps
+  & ThemeTogglePresentationProps;
+
+/**
+ * A hydration-stable, persisted Light/Dark/System appearance control.
+ * Persistent product chrome defaults to the compact menu presentation.
+ */
+export function ThemeToggle({
+  "aria-label": ariaLabel = "Appearance",
+  className,
+  display,
+  labels,
+  onChange,
+  presentation,
+  size = "compact",
+  value: controlledValue,
+}: ThemeToggleProps) {
+  const portalClassName = useDesignPortalClassName();
+  const hydrated = useHydrated();
+  const { setTheme, theme } = useTheme();
+  const controlled = controlledValue !== undefined;
+  const ready = controlled || hydrated;
+  const value = controlledValue ?? (hydrated ? normalizeDesignTheme(theme) : defaultDesignTheme);
+  const resolvedPresentation = presentation ?? (display === undefined ? "menu" : "segmented");
+  const resolvedDisplay = display ?? "icons";
+  const items = resolvedDisplay === "icons" ? themeToggleIconItems(labels) : themeToggleItems(labels);
+  const presentationStyles = stylex.props(
+    themeStyles.root,
+    resolvedPresentation === "menu" && themeStyles.menuRoot,
+    !ready && themeStyles.notReady,
+  );
+  const changeTheme = (nextTheme: DesignTheme): void => {
+    if (controlled) onChange?.(nextTheme);
+    else setTheme(nextTheme);
+  };
+  const currentLabel = themeToggleLabel(value, labels);
+
+  return (
+    <div
+      {...presentationStyles}
+      aria-busy={!ready || undefined}
+      className={cn(
+        "hraness-design-theme-toggle",
+        presentationStyles.className,
+        className,
+      )}
+      data-display={resolvedPresentation === "menu" ? "icons" : resolvedDisplay}
+      data-hraness-appearance-menu={resolvedPresentation === "menu" ? "" : undefined}
+      data-hraness-theme-toggle-stylex=""
+      data-presentation={resolvedPresentation}
+      data-ready={ready ? "true" : "false"}
+      data-theme-value={value}
+    >
+      {resolvedPresentation === "menu" ? (
+        <MenuTrigger>
+          <IconButton
+            aria-label={`${ariaLabel}: ${currentLabel}`}
+            controlClassName="hraness-design-theme-toggle__trigger"
+            controlXstyle={themeStyles.trigger}
+            isDisabled={!ready}
+            size={size}
+            tooltip={`${ariaLabel}: ${currentLabel}`}
+          >
+            {themeToggleIcon(value)}
+          </IconButton>
+          <Menu
+            aria-label={ariaLabel}
+            className="hraness-design-theme-toggle__menu"
+            disallowEmptySelection
+            onAction={(key) => {
+              if (isDesignTheme(key)) changeTheme(key);
+            }}
+            popoverClassName={cn(
+              "hraness-design-theme-toggle__popover",
+              portalClassName,
+            )}
+            popoverXstyle={themeStyles.popover}
+            selectedKeys={[value]}
+            selectionMode="single"
+            xstyle={themeStyles.menu}
+          >
+            {designThemes.map((id) => (
+              <MenuItem
+                className="hraness-design-theme-toggle__item"
+                data-theme-value={id}
+                id={id}
+                key={id}
+                leading={themeToggleIcon(id)}
+                textValue={themeToggleLabel(id, labels)}
+                xstyle={[
+                  themeStyles.item,
+                  id === value && themeStyles.itemSelected,
+                ]}
+              >
+                {themeToggleLabel(id, labels)}
+              </MenuItem>
+            ))}
+          </Menu>
+        </MenuTrigger>
+      ) : (
+        <SegmentedControl
+          aria-label={ariaLabel}
+          isDisabled={!ready}
+          items={items}
+          onChange={changeTheme}
+          size={size}
+          value={value}
+        />
+      )}
+    </div>
+  );
+}
+
+export type ThemeMenuButtonProps = ThemeToggleBaseProps & ThemeToggleControlProps;
+
+/**
+ * The canonical persistent appearance selector. Render it as the final action
+ * in a product header so every surface exposes the same icon-menu pattern.
+ */
+export function ThemeMenuButton(props: ThemeMenuButtonProps) {
+  const palette = useDesignPalette();
+  if (palette !== null) return <DesignPaletteMenuButton {...props} />;
+  return <ThemeToggle {...props} presentation="menu" />;
+}
+
+export interface ThemeColorSyncProps {
+  readonly darkColor?: string;
+  readonly lightColor?: string;
+  readonly metaName?: string;
+}
+
+export function themeColorFor(
+  resolvedTheme: string | undefined,
+  values: Readonly<{ dark: string; light: string }>,
+): string {
+  return resolvedTheme === "dark" ? values.dark : values.light;
+}
+
+/** Keeps browser and installed-app chrome aligned with forced or resolved appearance. */
+export function ThemeColorSync({
+  darkColor = colors.dark.background,
+  lightColor = colors.light.background,
+  metaName = "theme-color",
+}: ThemeColorSyncProps) {
+  const palette = useDesignPalette();
+  const { forcedTheme, resolvedTheme } = useTheme();
+  const effectiveTheme = resolveEffectiveTheme(forcedTheme, resolvedTheme);
+  const registrationId = useRef(Symbol("hraness-design-theme-color"));
+  const registration = useRef<ThemeColorMetaRegistration | null>(null);
+  const resolvedColor = palette !== null
+    // The adopted palette controller already owns theme-color, including when
+    // its bootstrap was loaded as a separate bundle before React.
+    ? (metaName !== "theme-color" && palette.ready ? palette.background : undefined)
+    : effectiveTheme !== undefined
+      ? themeColorFor(effectiveTheme, { dark: darkColor, light: lightColor })
+      : undefined;
+  const hasResolvedColor = resolvedColor !== undefined;
+  const latestColor = useRef(resolvedColor);
+  latestColor.current = resolvedColor;
+
+  useEffect(() => {
+    if (!hasResolvedColor || latestColor.current === undefined) return;
+    const current = acquireThemeColorMeta(
+      document,
+      metaName,
+      registrationId.current,
+      latestColor.current,
+    );
+    registration.current = current;
+    return () => {
+      if (registration.current === current) registration.current = null;
+      current.release();
+    };
+  }, [hasResolvedColor, metaName]);
+
+  useEffect(() => {
+    if (resolvedColor !== undefined) registration.current?.update(resolvedColor);
+  }, [resolvedColor]);
+
+  return null;
+}

package/src/reading.css

@@ -0,0 +1,72 @@
+/*
+ * Shared reading scale.
+ *
+ * `.hraness-prose` is the opt-in long-form reading grammar: docs, guides,
+ * methodology pages and article surfaces that do not run the full
+ * plain-publication shell. Put the class on the prose container; the shared
+ * `--hraness-type-*` tokens in typography.css carry the scale, so a site can
+ * retune it in one place.
+ *
+ * Serif display faces opt in with `data-hraness-reading-face="serif"` on the
+ * prose container or an ancestor: their smaller x-height reads ~15% smaller at
+ * the same font-size and they carry no bold cut, so the display scale steps up
+ * and the display weight drops to the face's single cut. h3 and below stay in
+ * the text face (see typography.css), so they keep the text scale.
+ */
+
+:where([data-hraness-reading-face="serif"]) {
+  --hraness-type-h1-size: clamp(2.5rem, 2rem + 1.8vw, 3.375rem);
+  --hraness-type-h2-size: clamp(1.875rem, 1.55rem + 1vw, 2.375rem);
+  --hraness-type-heading-weight: 400;
+}
+
+.hraness-prose {
+  max-inline-size: var(--hraness-type-reading-measure, 70ch);
+  font-size: var(--hraness-type-reading-size, clamp(1rem, .95rem + .25vw, 1.0625rem));
+  line-height: var(--hraness-type-reading-leading, 1.7);
+}
+
+.hraness-prose :is(h1, h2) {
+  font-family: var(--hraness-type-heading-font, var(--font-heading, var(--font-text, inherit)));
+  font-weight: var(--hraness-type-heading-weight, 600);
+  text-wrap: balance;
+}
+
+.hraness-prose h3 {
+  font-family: var(--hraness-type-h3-font, var(--font-text, inherit));
+  font-weight: var(--hraness-type-h3-weight, 650);
+  text-wrap: balance;
+}
+
+.hraness-prose h1 {
+  margin: 0 0 1rem;
+  font-size: var(--hraness-type-h1-size, clamp(2.25rem, 1.8rem + 1.6vw, 3rem));
+  line-height: 1.08;
+  letter-spacing: -.025em;
+}
+
+.hraness-prose h2 {
+  margin: var(--hraness-type-section-space, 3rem) 0 .6em;
+  font-size: var(--hraness-type-h2-size, clamp(1.75rem, 1.45rem + .9vw, 2.125rem));
+  line-height: 1.16;
+  letter-spacing: -.018em;
+}
+
+.hraness-prose h3 {
+  margin: var(--hraness-type-subsection-space, 2rem) 0 .5em;
+  font-size: var(--hraness-type-h3-size, clamp(1.25rem, 1.15rem + .4vw, 1.4375rem));
+  line-height: 1.28;
+  letter-spacing: -.01em;
+}
+
+.hraness-prose :is(h4, h5, h6) {
+  margin: 1.6rem 0 .4em;
+  font-family: var(--hraness-type-h4-font, var(--font-text, inherit));
+  font-size: var(--hraness-type-h4-size, 1.0625rem);
+  font-weight: var(--hraness-type-h4-weight, 650);
+  line-height: 1.4;
+}
+
+.hraness-prose :is(h1, h2, h3, h4) + :is(h2, h3, h4) {
+  margin-block-start: .75rem;
+}

package/src/relative-time.ts

@@ -0,0 +1,185 @@
+/**
+ * Framework-neutral relative time. Every input is parsed from `unknown` and
+ * rejected before formatting, so an invalid timestamp never renders as text.
+ */
+
+export type RelativeTimeInput = Date | number | string;
+export type RelativeTimeReference = Date | number;
+export type RelativeTimeNumeric = "auto" | "always";
+export type RelativeTimeUnit =
+  | "second"
+  | "minute"
+  | "hour"
+  | "day"
+  | "week"
+  | "month"
+  | "year";
+
+export interface RelativeTimeOptions {
+  /** Reference instant. Defaults to the current clock. */
+  readonly now?: RelativeTimeReference;
+  /** BCP 47 locale. Defaults to the runtime locale. */
+  readonly locale?: string;
+  /** `auto` allows phrases such as "now" and "yesterday". Defaults to `auto`. */
+  readonly numeric?: RelativeTimeNumeric;
+}
+
+/** A signed whole amount of one unit. Negative values are in the past. */
+export interface RelativeTimeValue {
+  readonly unit: RelativeTimeUnit;
+  readonly value: number;
+}
+
+const second = 1_000;
+const minute = 60 * second;
+const hour = 60 * minute;
+const day = 24 * hour;
+const week = 7 * day;
+const year = 365.2425 * day;
+const month = year / 12;
+
+interface RelativeTimeBucket {
+  readonly unit: RelativeTimeUnit;
+  readonly milliseconds: number;
+  /** The first rounded amount that moves to the next unit. */
+  readonly limit: number;
+}
+
+const buckets: readonly RelativeTimeBucket[] = [
+  { unit: "second", milliseconds: second, limit: 60 },
+  { unit: "minute", milliseconds: minute, limit: 60 },
+  { unit: "hour", milliseconds: hour, limit: 24 },
+  { unit: "day", milliseconds: day, limit: 7 },
+  { unit: "week", milliseconds: week, limit: 4 },
+  { unit: "month", milliseconds: month, limit: 12 },
+  { unit: "year", milliseconds: year, limit: Number.POSITIVE_INFINITY },
+];
+
+/** Units from finest to coarsest, in the order `resolveRelativeTime` tries them. */
+export const relativeTimeUnits: readonly RelativeTimeUnit[] = Object.freeze(
+  buckets.map((bucket) => bucket.unit),
+);
+
+/** ECMAScript's representable time range, in milliseconds either side of the epoch. */
+const maximumTime = 8.64e15;
+const isoDate = /^(\d{4})-(\d{2})-(\d{2})$/u;
+const isoDateTime =
+  /^(\d{4})-(\d{2})-(\d{2})T(\d{2}):(\d{2})(?::(\d{2})(?:\.(\d{1,9}))?)?(Z|[+-]\d{2}:\d{2})$/u;
+
+function describe(value: unknown): string {
+  if (typeof value === "string") return JSON.stringify(value);
+  if (value instanceof Date) return "an invalid Date";
+  return String(value);
+}
+
+function fromTime(time: number, label: string, original: unknown): Date {
+  if (!Number.isFinite(time) || Math.abs(time) > maximumTime) {
+    throw new RangeError(`${label} must be a valid instant; received ${describe(original)}.`);
+  }
+  return new Date(time);
+}
+
+function parseIsoString(value: string, label: string): Date {
+  const date = isoDate.exec(value);
+  const dateTime = date === null ? isoDateTime.exec(value) : null;
+  const parts = date ?? dateTime;
+  if (parts === null) {
+    throw new RangeError(
+      `${label} must be an ISO 8601 date (YYYY-MM-DD) or a date-time with Z or an offset; received ${describe(value)}.`,
+    );
+  }
+  const [yearText, monthText, dayText, hourText = "00", minuteText = "00", secondText = "00", fraction = "", zone = "Z"] =
+    parts.slice(1);
+  const fields = [yearText, monthText, dayText, hourText, minuteText, secondText].map(Number);
+  const [y, mo, d, h, mi, s] = fields as [number, number, number, number, number, number];
+  const offsetHours = zone === "Z" ? 0 : Number(zone.slice(1, 3));
+  const offsetRest = zone === "Z" ? 0 : Number(zone.slice(4, 6));
+  const offsetMinutes = (zone.startsWith("-") ? -1 : 1) * (offsetHours * 60 + offsetRest);
+  const milliseconds = Number(fraction.padEnd(3, "0").slice(0, 3));
+  const wall = new Date(0);
+  wall.setUTCFullYear(y, mo - 1, d);
+  wall.setUTCHours(h, mi, s, milliseconds);
+  const valid = h < 24 && mi < 60 && s < 60 && offsetHours < 24 && offsetRest < 60
+    && wall.getUTCFullYear() === y && wall.getUTCMonth() === mo - 1 && wall.getUTCDate() === d;
+  if (!valid) throw new RangeError(`${label} must name a real calendar instant; received ${describe(value)}.`);
+  return fromTime(wall.getTime() - offsetMinutes * minute, label, value);
+}
+
+/**
+ * Parse a timestamp from a Date, epoch milliseconds, or an ISO 8601 string.
+ * A date-only string is midnight UTC. A date-time string must carry `Z` or an
+ * offset, so the server and the browser resolve it to the same instant.
+ */
+export function parseRelativeTimeInput(value: unknown, label = "time"): Date {
+  if (value instanceof Date) return fromTime(value.getTime(), label, value);
+  if (typeof value === "number") return fromTime(value, label, value);
+  if (typeof value === "string") return parseIsoString(value.trim(), label);
+  throw new TypeError(`${label} must be a Date, epoch milliseconds, or an ISO 8601 string.`);
+}
+
+function parseReference(value: unknown): Date {
+  if (value === undefined) return new Date();
+  if (value instanceof Date || typeof value === "number") return parseRelativeTimeInput(value, "now");
+  throw new TypeError("now must be a Date or epoch milliseconds.");
+}
+
+function parseNumeric(value: unknown): RelativeTimeNumeric {
+  if (value === undefined) return "auto";
+  if (value === "auto" || value === "always") return value;
+  throw new TypeError(`numeric must be "auto" or "always"; received ${describe(value)}.`);
+}
+
+function parseLocale(value: unknown): string | undefined {
+  if (value === undefined) return undefined;
+  if (typeof value !== "string" || value.trim() === "") {
+    throw new TypeError("locale must be a non-empty BCP 47 language tag.");
+  }
+  return value;
+}
+
+/**
+ * Choose the unit and signed amount for a difference of `target - now`.
+ * Amounts round half away from zero, so `resolveRelativeTime(-x)` is always
+ * the exact negation of `resolveRelativeTime(x)`, including a signed zero.
+ */
+export function resolveRelativeTime(differenceMilliseconds: number): RelativeTimeValue {
+  if (!Number.isFinite(differenceMilliseconds)) {
+    throw new RangeError("The time difference must be a finite number of milliseconds.");
+  }
+  const magnitude = Math.abs(differenceMilliseconds);
+  const sign = differenceMilliseconds < 0 || Object.is(differenceMilliseconds, -0) ? -1 : 1;
+  for (const bucket of buckets) {
+    const amount = Math.round(magnitude / bucket.milliseconds);
+    if (amount < bucket.limit) {
+      // A past instant under half a second keeps a signed zero: "0 seconds ago".
+      return { unit: bucket.unit, value: sign * amount };
+    }
+  }
+  throw new RangeError("No relative time unit matched.");
+}
+
+const formatters = new Map<string, Intl.RelativeTimeFormat>();
+
+function formatterFor(locale: string | undefined, numeric: RelativeTimeNumeric): Intl.RelativeTimeFormat {
+  const key = `${locale ?? ""}\u0000${numeric}`;
+  let formatter = formatters.get(key);
+  if (formatter === undefined) {
+    formatter = new Intl.RelativeTimeFormat(locale, { numeric, style: "long" });
+    formatters.set(key, formatter);
+  }
+  return formatter;
+}
+
+/**
+ * Format `target` relative to `now`, for example "in 23 hours",
+ * "5 minutes ago" or "now". Throws on an invalid target, reference, locale or
+ * numeric option instead of rendering "Invalid Date".
+ */
+export function formatRelativeTime(target: RelativeTimeInput, options: RelativeTimeOptions = {}): string {
+  const instant = parseRelativeTimeInput(target, "target");
+  const reference = parseReference(options.now);
+  const numeric = parseNumeric(options.numeric);
+  const locale = parseLocale(options.locale);
+  const { unit, value } = resolveRelativeTime(instant.getTime() - reference.getTime());
+  return formatterFor(locale, numeric).format(value, unit);
+}

package/src/reset.css

@@ -0,0 +1,2 @@
+/* @hraness/ui owns the portable browser baseline. */
+@import "@hraness/ui/reset.css";

package/src/site-shell.css

@@ -0,0 +1,16 @@
+/** Viewport-height document layout. Nested application and gallery roots opt in. */
+:where(.hraness-site-shell, body.plain-site, body.hraness-marketing-page) {
+  display: flex;
+  flex-direction: column;
+  min-block-size: 100vh;
+  min-block-size: 100svh;
+  min-block-size: 100dvh;
+}
+
+:where(.hraness-site-shell, body.plain-site, body.hraness-marketing-page) > * {
+  flex-shrink: 0;
+}
+
+:where(.hraness-site-shell, body.plain-site, body.hraness-marketing-page) > :where(main, .hraness-site-shell__content) {
+  flex: 1 0 auto;
+}