@uniflowed/web 0.0.0-alpha.18

package/regions.js

@@ -0,0 +1,155 @@
+// @flow
+//
+// `@uniflowed/web/regions`: the elements that exist for a screen reader.
+//
+// A single-page application breaks two things a browser does for free. It
+// navigates without a page load, so nothing announces that the page changed;
+// and it updates regions in place, so a reader who is not looking at that part
+// of the screen is never told.
+//
+// Both are one element with the right ARIA attributes, and both are easy to
+// get subtly wrong — which is why they are components rather than advice.
+//
+// # What belongs in this module
+//
+// The two kinds of region a document has for assistive technology: landmark
+// regions, which say what a part of the page *is* (`Page`, `Layout`) or how to
+// reach one (`SkipLink`), and live regions, which say that something in it
+// changed (`Announcer`). The test is whether a sighted reader would notice its
+// absence — if only a screen reader would, it is here.
+//
+// Not here: a widget that carries ARIA alongside a visual job. A dialog, a tab
+// list or a menu is `@uniflowed/ui`'s, and comes with focus management and
+// keyboard behaviour this module deliberately has no opinion about. The
+// elements here render markup and nothing else; that is why they can be used
+// on a page that has no design system at all.
+
+import * as React from "@uniflowed/react";
+
+/**
+ * The id `Page` renders and `SkipLink` points at.
+ *
+ * One constant rather than two string literals, because the two have to agree
+ * and a skip link that points at nothing fails silently — the focus simply
+ * stays where it was, and only someone navigating by keyboard ever finds out.
+ */
+const MAIN_ID: string = "uf-main";
+
+/**
+ * How a thing is hidden from eyes but not from a screen reader.
+ *
+ * `display: none` and `visibility: hidden` both take an element out of the
+ * accessibility tree as well, which is the usual way this is got wrong. Inline
+ * rather than a class, because a component in a library cannot assume the
+ * application has loaded any particular stylesheet.
+ */
+const VISUALLY_HIDDEN = {
+  position: "absolute",
+  width: "1px",
+  height: "1px",
+  margin: "-1px",
+  padding: 0,
+  overflow: "hidden",
+  // Both spellings: `clip` is deprecated and still the one older screen
+  // readers honour.
+  clip: "rect(0 0 0 0)",
+  clipPath: "inset(50%)",
+  whiteSpace: "nowrap",
+  border: 0,
+};
+
+/**
+ * A live region: text put here is read out when it changes.
+ *
+ * `polite` waits for the reader to finish what they are saying, which is right
+ * for everything except an error the reader must hear now. `assertive`
+ * interrupts, and interrupting someone mid-sentence to say "saved" is why it is
+ * not the default.
+ *
+ * The element is always rendered, empty or not. A live region that appears at
+ * the same moment as its text is not announced — the screen reader has to be
+ * watching it *before* it changes — which is the mistake that makes an
+ * announcer look like it does nothing.
+ */
+export component Announcer(
+  children?: React.Node,
+  urgency?: "polite" | "assertive" = "polite",
+  atomic?: boolean = true,
+) renders React.Node {
+  return (
+    <div aria-live={urgency} aria-atomic={atomic} style={VISUALLY_HIDDEN}>
+      {children}
+    </div>
+  );
+}
+
+/**
+ * The page's main content, as a landmark.
+ *
+ * `<main>` is what "skip to content" skips to and what a screen reader's
+ * landmark list offers, and there must be exactly one per document — which is
+ * why this is not something a layout should also render.
+ */
+export component Page(children?: React.Node, className?: string) renders React.Node {
+  return (
+    <main id={MAIN_ID} className={className}>
+      {children}
+    </main>
+  );
+}
+
+/**
+ * "Skip to content": the first thing a keyboard reaches on the page.
+ *
+ * Without it, tabbing into a page means tabbing through the whole navigation
+ * before reaching a word of the content — on every route, every time. It is
+ * the cheapest accessibility fix there is and the one most often missing,
+ * because it is invisible when it works and so nobody notices it is absent.
+ *
+ * Render it first inside the layout, before the navigation. It is hidden until
+ * it takes focus and then shows itself, which is why it does not cost a
+ * design anything: the only person who ever sees it is the person using it.
+ */
+export component SkipLink(children?: React.Node = "Skip to content") renders React.Node {
+  const [focused, setFocused] = React.useState(false);
+
+  return (
+    <a
+      href={`#${MAIN_ID}`}
+      onFocus={() => setFocused(true)}
+      onBlur={() => setFocused(false)}
+      style={
+        focused
+          ? {
+              position: "absolute",
+              top: "0.5rem",
+              left: "0.5rem",
+              // Above anything a page is likely to have stacked, since the
+              // link has to be readable wherever it lands.
+              zIndex: 1000,
+              padding: "0.5rem 0.75rem",
+              background: "Canvas",
+              color: "CanvasText",
+              // `CanvasText` follows the reader's own light or dark setting,
+              // so the link stays legible without knowing the page's theme.
+              border: "1px solid CanvasText",
+              borderRadius: "0.25rem",
+            }
+          : VISUALLY_HIDDEN
+      }
+    >
+      {children}
+    </a>
+  );
+}
+
+/**
+ * The frame around a page: whatever is the same between routes.
+ *
+ * A plain grouping element rather than a landmark, because the landmarks
+ * inside it — `<nav>`, `<main>`, `<footer>` — are the ones a reader navigates
+ * by, and wrapping them in another one adds a level to walk through.
+ */
+export component Layout(children?: React.Node, className?: string) renders React.Node {
+  return <div className={className}>{children}</div>;
+}

package/time.js

@@ -0,0 +1,187 @@
+// @flow
+//
+// `@uniflowed/web/time`: rendering an instant.
+//
+// The whole difficulty is that a server and a browser are in different places.
+// `new Date().toLocaleString()` on a server in UTC and in a browser in Tokyo
+// produce different text, React notices during hydration, and the fix people
+// reach for — rendering nothing until an effect runs — makes the date invisible
+// to a crawler and shifts the layout when it appears.
+//
+// So `Time` formats deterministically by default: the same string on both
+// sides, chosen by the caller rather than by the environment. A caller who
+// genuinely wants the reader's locale asks for it, and gets a component that
+// renders the deterministic form first and upgrades after hydration — which is
+// the honest version of what the naive code was trying to do.
+//
+// # Temporal, not `Date`
+//
+// This component is built on `@uniflowed/core/temporal` and the choice is not
+// cosmetic. `Date` has one time zone — whichever the machine is set to — and
+// the two machines here are set to different ones, which is the entire problem
+// restated. There is no way to write "six in the morning UTC, shown as three in
+// the afternoon in Tokyo" with a `Date` without going through the host's zone
+// on the way, and going through the host's zone is what makes the two renders
+// disagree. A `Temporal.Instant` carries no zone and a `Temporal.ZonedDateTime`
+// carries the zone it was asked for, so the server's text is a function of the
+// instant and a zone name rather than of the machine.
+//
+// The zone the deterministic text is rendered in comes from the render itself —
+// `RenderProvider` fixes it and the markup carries it — so the browser
+// reproduces the server's string exactly, and *then* moves to the reader's own
+// zone. Without a provider the deterministic zone is UTC, which is unambiguous
+// and the same everywhere, rather than the host's, which is neither.
+//
+// # What belongs in this module
+//
+// Anything whose difficulty is that the two renders are in different places or
+// at different moments: a formatted date, a duration, a countdown, a
+// timezone-aware label. The test is whether hydration would notice a
+// difference.
+//
+// Not here: a hook that reads a clock to schedule work — `useInterval` and
+// `useTimeout` are `@uniflowed/hooks`'s, and this module renders a value
+// rather than driving one. Locale-formatted numbers and currency have the same
+// hydration problem and would be a module of their own rather than a second
+// subject inside this one, because nothing about a price is about an instant.
+
+import * as React from "@uniflowed/react";
+import type { Instant } from "@uniflowed/core/temporal";
+import { Temporal } from "@uniflowed/core/temporal";
+import { useRenderEnvelope } from "@uniflowed/hooks/render";
+
+/** Whatever a caller has an instant written as. */
+export type TimeValue = Instant | Date | string | number;
+
+/** What to show. Everything but `local` and `relative` is the same everywhere. */
+export type TimeFormat =
+  /** `2026-09-04T06:00:00Z`. Unambiguous, and the same on every machine. */
+  | "iso"
+  /** `2026-09-04`. The calendar date in the render's zone. */
+  | "date"
+  /** `2026-09-04 15:00 +09:00`. The wall clock in the render's zone. */
+  | "zoned"
+  /** The reader's own locale and zone, applied after hydration. */
+  | "local"
+  /** "3 minutes ago", relative to now, after hydration. */
+  | "relative";
+
+/** Milliseconds in each unit, largest first, for the relative form. */
+const UNITS: $ReadOnlyArray<[Intl$RelativeTimeFormatUnit, number]> = [
+  ["year", 31_536_000_000],
+  ["month", 2_592_000_000],
+  ["day", 86_400_000],
+  ["hour", 3_600_000],
+  ["minute", 60_000],
+  ["second", 1_000],
+];
+
+/**
+ * Whatever the caller passed, as a `Temporal.Instant`.
+ *
+ * A string must carry an offset, because Temporal refuses one that does not and
+ * this component must not be more permissive than the standard it is built on:
+ * `"2026-09-04"` is a date and not an instant, and every implementation that
+ * has guessed which midnight it meant has guessed differently.
+ */
+export function asInstant(value: TimeValue): Instant {
+  if (value instanceof Date) {
+    return Temporal.Instant.fromEpochMilliseconds(value.getTime());
+  }
+  if (typeof value === "number") {
+    return Temporal.Instant.fromEpochMilliseconds(value);
+  }
+  if (typeof value === "string") {
+    return Temporal.Instant.from(value);
+  }
+  return value;
+}
+
+/** The text that is the same on a server and in a browser. */
+function stable(at: Instant, format: TimeFormat, zone: string): string {
+  if (format === "iso") {
+    return at.toString();
+  }
+  const zoned = at.toZonedDateTimeISO(zone);
+  if (format === "date") {
+    return zoned.toPlainDate().toString();
+  }
+  // `local` and `relative` start here too: it is the most readable form that
+  // still says exactly which instant it is, which is what a reader with no
+  // JavaScript and a crawler both end up with.
+  const time = `${String(zoned.hour).padStart(2, "0")}:${String(zoned.minute).padStart(2, "0")}`;
+  return `${zoned.toPlainDate().toString()} ${time} ${zoned.offset}`;
+}
+
+/**
+ * "3 minutes ago", or "in 3 minutes".
+ *
+ * `from` defaults to the injected clock rather than to `new Date()`, so a test
+ * can decide what "now" is and a server render is reproducible. Both arguments
+ * take anything `Time` takes.
+ */
+export function relative(at: TimeValue, from?: TimeValue): string {
+  const target = asInstant(at);
+  const origin = from === undefined ? Temporal.Now.instant() : asInstant(from);
+  const difference = target.epochMilliseconds - origin.epochMilliseconds;
+  const formatter = new Intl.RelativeTimeFormat(undefined, { numeric: "auto" });
+  for (const [unit, span] of UNITS) {
+    if (Math.abs(difference) >= span) {
+      return formatter.format(Math.round(difference / span), unit);
+    }
+  }
+  // Under a second in either direction is "now", not "in 0 seconds".
+  return formatter.format(0, "second");
+}
+
+/**
+ * An instant, as a `<time>` element.
+ *
+ * The machine-readable value is always in `dateTime`, whatever the text says,
+ * so a crawler and a screen reader get the exact instant even when a reader
+ * sees "3 minutes ago".
+ *
+ * `iso`, `date` and `zoned` render the same string on both sides and never
+ * change. `local` and `relative` render the deterministic form first and
+ * replace it after hydration — the text is there for the first paint and for
+ * anything that does not run JavaScript, and it becomes the reader's own format
+ * once it can.
+ *
+ * `zone` is the zone the deterministic forms are written in. It defaults to the
+ * one the render fixed, so a page under a `RenderProvider` shows its server's
+ * zone until it can show the reader's; with no provider it is UTC, because a
+ * default that reads the host would be a different string on each side and
+ * would defeat the entire component.
+ */
+export component Time(
+  value: TimeValue,
+  format?: TimeFormat = "iso",
+  zone?: string,
+  locale?: string,
+  className?: string,
+) renders React.Node {
+  const at = asInstant(value);
+  const machine = at.toString();
+  const rendered = useRenderEnvelope();
+  const server = stable(at, format, zone ?? rendered?.timeZone ?? "UTC");
+
+  // Starts at the deterministic text on both sides, so hydration matches; the
+  // effect below is what makes it the reader's.
+  const [text, setText] = React.useState(server);
+
+  React.useEffect(() => {
+    if (format === "local") {
+      setText(at.toZonedDateTimeISO(Temporal.Now.timeZoneId()).toLocaleString(locale));
+    } else if (format === "relative") {
+      setText(relative(at));
+    }
+    // `machine` rather than `at`: a caller passing a string builds a new instant
+    // every render, and depending on the object would re-run this forever.
+  }, [machine, format, locale]);
+
+  return (
+    <time dateTime={machine} className={className}>
+      {text}
+    </time>
+  );
+}