@hraness/design-kit 0.31.1

package/src/react/production-data-preview-notice.stylex.ts

@@ -0,0 +1,40 @@
+import * as stylex from "@stylexjs/stylex";
+
+export const productionDataPreviewNoticeStyles = stylex.create({
+  emphasis: {
+    fontWeight: "var(--font-weight-bold, 700)",
+    letterSpacing: "0.04em",
+    textTransform: "uppercase",
+  },
+  root: {
+    alignItems: "center",
+    backgroundColor: "#ffcc33",
+    backgroundAttachment: "scroll",
+    backgroundClip: "border-box",
+    backgroundImage: "none",
+    backgroundOrigin: "padding-box",
+    backgroundPosition: "0% 0%",
+    backgroundRepeat: "repeat",
+    backgroundSize: "auto",
+    "border-block-end-color": "#5c1906",
+    "border-block-end-style": "solid",
+    "border-block-end-width": 2,
+    boxShadow: "0 3px 12px rgb(36 20 0 / 0.35)",
+    color: "#241400",
+    display: "flex",
+    flexWrap: "wrap",
+    fontFamily: "var(--font-text, system-ui, sans-serif)",
+    fontSize: "var(--text-label, 0.875rem)",
+    gap: "var(--space-1, 0.25rem) var(--space-3, 0.75rem)",
+    "inset-block-start": 0,
+    justifyContent: "center",
+    lineHeight: 1.35,
+    minHeight: "3rem",
+    paddingBlock: "max(var(--space-2, 0.5rem), env(safe-area-inset-top))",
+    paddingInline: "max(var(--space-4, 1rem), env(safe-area-inset-left)) max(var(--space-4, 1rem), env(safe-area-inset-right))",
+    position: "sticky",
+    textAlign: "center",
+    width: "100%",
+    zIndex: "calc(var(--z-tooltip, 3000) + 1)",
+  },
+});

package/src/react/production-data-preview-notice.tsx

@@ -0,0 +1,34 @@
+"use client";
+
+import * as stylex from "@stylexjs/stylex";
+
+import { productionDataPreviewNoticeStyles } from "./production-data-preview-notice.stylex.js";
+
+export interface ProductionDataPreviewNoticeProps {
+  /** A non-empty deployment origin enables the warning without exposing it in the rendered page. */
+  readonly surfaceOrigin?: string | undefined;
+}
+
+/** A sticky warning for previews that are connected to production data. */
+export function ProductionDataPreviewNotice({
+  surfaceOrigin,
+}: ProductionDataPreviewNoticeProps) {
+  if (surfaceOrigin === undefined || surfaceOrigin === "") return null;
+
+  const noticePresentation = stylex.props(productionDataPreviewNoticeStyles.root);
+  const emphasisPresentation = stylex.props(
+    productionDataPreviewNoticeStyles.emphasis,
+  );
+
+  return (
+    <aside
+      {...noticePresentation}
+      aria-label="Production data preview warning"
+      className={`hraness-design-production-data-preview-notice ${noticePresentation.className}`}
+      role="alert"
+    >
+      <strong {...emphasisPresentation}>Production data preview</strong>
+      <span>This preview uses production data. Actions are real and affect production.</span>
+    </aside>
+  );
+}

package/src/react/provider-mark.stylex.ts

@@ -0,0 +1,132 @@
+import * as stylex from "@stylexjs/stylex";
+
+/**
+ * ProviderMark: a soft accent-tinted tile carrying either vendor-colored art
+ * or a retinted monochrome glyph. `--_mark-accent` is set per mark by the
+ * component; every color below derives from it so surfaces stay in the
+ * mark's palette without per-brand rules. Color art overlays the
+ * currentColor glyph, so in forced colors the art hides and the glyph keeps
+ * a system color. Marks with no artwork fall back to their monogram.
+ */
+export const providerMarkStyles = stylex.create({
+  tile: {
+    alignItems: "center",
+    aspectRatio: "1",
+    backgroundColor: {
+      default: "color-mix(in srgb, var(--_mark-accent) 14%, var(--surface, Canvas))",
+      "@media (forced-colors: active)": "Canvas",
+    },
+    backgroundImage: {
+      default:
+        "linear-gradient(180deg, color-mix(in srgb, white 24%, transparent), transparent 48%), linear-gradient(160deg, color-mix(in srgb, var(--_mark-accent) 26%, transparent), color-mix(in srgb, var(--_mark-accent) 6%, transparent) 74%)",
+      "@media (forced-colors: active)": "none",
+    },
+    borderRadius: "calc(var(--_mark-size) * 0.26)",
+    boxShadow: {
+      default:
+        "inset 0 1px 0 color-mix(in srgb, white 55%, transparent), inset 0 -1px 0 color-mix(in srgb, var(--_mark-accent) 18%, transparent), 0 1px 2px color-mix(in srgb, var(--_mark-accent) 30%, transparent)",
+      "@media (forced-colors: active)": "none",
+    },
+    boxSizing: "border-box",
+    color: "light-dark(color-mix(in srgb, var(--_mark-accent) 78%, black), color-mix(in srgb, var(--_mark-accent) 55%, white))",
+    display: "inline-flex",
+    flexShrink: 0,
+    inlineSize: "var(--_mark-size)",
+    justifyContent: "center",
+    outline: {
+      default: "1px solid color-mix(in srgb, var(--_mark-accent) 28%, transparent)",
+      "@media (forced-colors: active)": "1px solid ButtonBorder",
+    },
+    outlineOffset: "-1px",
+    position: "relative",
+    verticalAlign: "middle",
+  },
+  solid: {
+    backgroundColor: {
+      default: "var(--_mark-accent)",
+      "@media (forced-colors: active)": "Canvas",
+    },
+    backgroundImage: {
+      default:
+        "linear-gradient(180deg, color-mix(in srgb, white 22%, transparent), transparent 52%), linear-gradient(160deg, transparent, color-mix(in srgb, var(--_mark-accent) 78%, black))",
+      "@media (forced-colors: active)": "none",
+    },
+    color: "var(--_mark-on-accent, #f7f6f2)",
+    outline: {
+      default: "1px solid color-mix(in srgb, var(--_mark-accent) 70%, black)",
+      "@media (forced-colors: active)": "1px solid ButtonBorder",
+    },
+  },
+  plain: {
+    backgroundColor: "transparent",
+    backgroundImage: "none",
+    boxShadow: "none",
+    color: "light-dark(color-mix(in srgb, var(--_mark-accent) 82%, black), color-mix(in srgb, var(--_mark-accent) 58%, white))",
+    outline: "none",
+  },
+  glyph: {
+    blockSize: "64%",
+    display: "inline-flex",
+    inlineSize: "64%",
+  },
+  art: {
+    blockSize: "68%",
+    display: {
+      default: "inline-flex",
+      "@media (forced-colors: active)": "none",
+    },
+    inlineSize: "68%",
+    inset: "0",
+    margin: "auto",
+    position: "absolute",
+  },
+  monogram: {
+    alignItems: "center",
+    color: "inherit",
+    display: {
+      default: "none",
+      "@media (forced-colors: active)": "inline-flex",
+    },
+    fontSize: "calc(var(--_mark-size) * 0.36)",
+    fontWeight: 700,
+    inset: "0",
+    justifyContent: "center",
+    letterSpacing: "0.02em",
+    lineHeight: 1,
+    position: "absolute",
+  },
+  monogramOnly: {
+    display: "inline-flex",
+    position: "static",
+  },
+  chip: {
+    alignItems: "center",
+    display: "inline-flex",
+    gap: "calc(var(--_mark-size) * 0.4)",
+    minInlineSize: 0,
+  },
+  chipName: {
+    color: "var(--foreground, CanvasText)",
+    fontSize: "calc(var(--_mark-size) * 0.46)",
+    fontWeight: 550,
+    letterSpacing: "-0.01em",
+    lineHeight: 1.2,
+    minInlineSize: 0,
+    overflow: "hidden",
+    textOverflow: "ellipsis",
+    whiteSpace: "nowrap",
+  },
+});
+
+export function providerMarkClassName(
+  part: keyof typeof providerMarkStyles,
+  caller?: string,
+): string {
+  const hook =
+    part === "tile"
+      ? "hraness-provider-mark"
+      : `hraness-provider-mark__${part.replaceAll(/[A-Z]/gu, (c) => `-${c.toLowerCase()}`)}`;
+  return [hook, stylex.props(providerMarkStyles[part]).className, caller]
+    .filter(Boolean)
+    .join(" ");
+}

package/src/react/provider-mark.tsx

@@ -0,0 +1,120 @@
+import type { CSSProperties } from "react";
+
+import {
+  providerMark,
+  providerMarkFallback,
+  providerMarkOnAccent,
+  type ProviderMarkDescriptor,
+} from "../provider-marks.js";
+import { providerMarkClassName } from "./provider-mark.stylex.js";
+
+export type ProviderMarkTone = "tile" | "solid" | "plain";
+
+export interface ProviderMarkProps {
+  readonly mark: ProviderMarkDescriptor | string;
+  readonly className?: string;
+  /** Decorative by default; pass a label only when no adjacent name exists. */
+  readonly label?: string;
+  readonly size?: number;
+  readonly tone?: ProviderMarkTone;
+}
+
+interface MarkStyle extends CSSProperties {
+  "--_mark-accent": string;
+  "--_mark-on-accent"?: string;
+  "--_mark-size": string;
+}
+
+function resolveMark(mark: ProviderMarkDescriptor | string): ProviderMarkDescriptor {
+  if (typeof mark !== "string") return mark;
+  return providerMark(mark) ?? providerMarkFallback(mark);
+}
+
+function Artwork({
+  mark,
+  tone,
+}: Readonly<{ mark: ProviderMarkDescriptor; tone: ProviderMarkTone }>) {
+  // Only the tinted tile carries vendor-colored art; solid and plain tones
+  // use the retintable glyph so contrast stays in the surface's control.
+  const art = tone === "tile" ? mark.art : null;
+  return (
+    <>
+      <svg
+        aria-hidden="true"
+        className={providerMarkClassName("glyph")}
+        dangerouslySetInnerHTML={{ __html: mark.glyph.body }}
+        fill="currentColor"
+        viewBox={mark.glyph.viewBox}
+      />
+      {art === null ? null : (
+        <svg
+          aria-hidden="true"
+          className={providerMarkClassName("art")}
+          dangerouslySetInnerHTML={{ __html: art.body }}
+          viewBox={art.viewBox}
+        />
+      )}
+    </>
+  );
+}
+
+/**
+ * One provider or agent identity: a soft accent-tinted tile by default, a
+ * saturated accent tile with `tone="solid"`, or the bare glyph with
+ * `tone="plain"`. Unknown identities render a monogram tile so surfaces
+ * never imply an official mark that does not exist.
+ */
+export function ProviderMark({ mark, className, label, size = 32, tone = "tile" }: ProviderMarkProps) {
+  if (!Number.isFinite(size) || size <= 0) throw new RangeError("ProviderMark size must be positive and finite.");
+  const resolved = resolveMark(mark);
+  const style: MarkStyle = {
+    "--_mark-accent": resolved.accent,
+    "--_mark-size": `${size}px`,
+  };
+  if (tone === "solid") style["--_mark-on-accent"] = providerMarkOnAccent(resolved);
+  const hasArtwork = resolved.glyph.body !== "";
+  return (
+    <span
+      aria-hidden={label === undefined ? true : undefined}
+      aria-label={label}
+      className={[
+        providerMarkClassName("tile"),
+        tone === "tile" ? "" : providerMarkClassName(tone),
+        className,
+      ]
+        .filter(Boolean)
+        .join(" ")}
+      role={label === undefined ? undefined : "img"}
+      style={style}
+    >
+      {hasArtwork ? <Artwork mark={resolved} tone={tone} /> : null}
+      <span
+        aria-hidden="true"
+        className={[
+          providerMarkClassName("monogram"),
+          hasArtwork ? "" : providerMarkClassName("monogramOnly"),
+        ]
+          .filter(Boolean)
+          .join(" ")}
+      >
+        {resolved.monogram}
+      </span>
+    </span>
+  );
+}
+
+export interface ProviderMarkChipProps extends Omit<ProviderMarkProps, "label"> {
+  /** Visible name; defaults to the registered display name. */
+  readonly name?: string;
+}
+
+/** The mark tile beside its display name; labels itself for a11y. */
+export function ProviderMarkChip({ mark, name, ...rest }: ProviderMarkChipProps) {
+  const resolved = resolveMark(mark);
+  return (
+    <span className={providerMarkClassName("chip")} style={{ "--_mark-size": `${rest.size ?? 32}px` } as CSSProperties}>
+      <ProviderMark mark={resolved} {...rest} />
+      <span className={providerMarkClassName("chipName")}>{name ?? resolved.name}</span>
+    </span>
+  );
+}

package/src/react/relative-time.tsx

@@ -0,0 +1,117 @@
+"use client";
+
+import { useEffect, useState, type ComponentPropsWithoutRef } from "react";
+
+import {
+  formatRelativeTime,
+  parseRelativeTimeInput,
+  resolveRelativeTime,
+  type RelativeTimeInput,
+  type RelativeTimeNumeric,
+  type RelativeTimeReference,
+} from "../relative-time.js";
+
+/**
+ * `auto` refreshes about as often as the displayed unit can change. A number
+ * is a fixed interval in milliseconds. `off` keeps the first reference.
+ */
+export type RelativeTimeRefresh = "auto" | "off" | number;
+
+export interface RelativeTimeProps
+  extends Omit<ComponentPropsWithoutRef<"time">, "children" | "dateTime" | "title" | "suppressHydrationWarning"> {
+  /** The instant to describe: a Date, epoch milliseconds, or a zoned ISO 8601 string. */
+  readonly value: RelativeTimeInput;
+  /**
+   * The reference for the server render and the first client render. After
+   * mount the component follows the client clock unless `refreshInterval` is `off`.
+   */
+  readonly now?: RelativeTimeReference | undefined;
+  readonly locale?: string | undefined;
+  readonly numeric?: RelativeTimeNumeric | undefined;
+  /** Defaults to `auto`. A fixed interval must be a whole number from 1000 to 2147483647. */
+  readonly refreshInterval?: RelativeTimeRefresh | undefined;
+}
+
+const maximumTimeout = 2_147_483_647;
+const autoDelays = {
+  second: 1_000,
+  minute: 15_000,
+  hour: 60_000,
+  day: 3_600_000,
+  week: 3_600_000,
+  month: 3_600_000,
+  year: 3_600_000,
+} as const;
+
+function parseRefresh(value: unknown): RelativeTimeRefresh {
+  if (value === undefined) return "auto";
+  if (value === "auto" || value === "off") return value;
+  if (typeof value === "number" && Number.isInteger(value) && value >= 1_000 && value <= maximumTimeout) return value;
+  throw new RangeError(
+    `RelativeTime refreshInterval must be "auto", "off", or whole milliseconds from 1000 to ${maximumTimeout}.`,
+  );
+}
+
+function absoluteFormatter(locale: string | undefined): Intl.DateTimeFormat {
+  return new Intl.DateTimeFormat(locale, { dateStyle: "medium", timeStyle: "long" });
+}
+
+/**
+ * A `<time>` element whose text is relative ("5 minutes ago") and whose
+ * `title` is the absolute local date and time. The server render and the
+ * hydration render use `now`; the element is then re-created with the client
+ * clock and time zone, so no stale server text survives hydration.
+ */
+export function RelativeTime({
+  locale,
+  now,
+  numeric,
+  refreshInterval,
+  value,
+  ...timeProps
+}: RelativeTimeProps) {
+  const instant = parseRelativeTimeInput(value, "RelativeTime value");
+  const refresh = parseRefresh(refreshInterval);
+  const time = instant.getTime();
+  const [clock, setClock] = useState<number | null>(null);
+
+  useEffect(() => {
+    setClock(Date.now());
+    if (refresh === "off") return undefined;
+    let timer: ReturnType<typeof setTimeout> | undefined;
+    const schedule = () => {
+      const delay = typeof refresh === "number"
+        ? refresh
+        : autoDelays[resolveRelativeTime(time - Date.now()).unit];
+      timer = setTimeout(() => {
+        setClock(Date.now());
+        schedule();
+      }, delay);
+    };
+    schedule();
+    return () => clearTimeout(timer);
+  }, [refresh, time]);
+
+  const mounted = clock !== null;
+  const reference = refresh === "off" && now !== undefined
+    ? now
+    // Without `now` the first render reads the clock; the mount update replaces it.
+    : clock ?? now ?? Date.now();
+  const text = formatRelativeTime(instant, {
+    now: reference,
+    ...(locale === undefined ? {} : { locale }),
+    ...(numeric === undefined ? {} : { numeric }),
+  });
+
+  return (
+    <time
+      {...timeProps}
+      dateTime={instant.toISOString()}
+      key={mounted ? "client" : "server"}
+      suppressHydrationWarning
+      title={absoluteFormatter(locale).format(instant)}
+    >
+      {text}
+    </time>
+  );
+}

package/src/react/route-state.stylex.ts

@@ -0,0 +1,39 @@
+import * as stylex from "@stylexjs/stylex";
+
+export const routeStateStyles = stylex.create({
+  content: {
+    display: "grid",
+    gridRow: 2,
+    "min-block-size": 0,
+    placeItems: "center",
+  },
+  header: {
+    alignItems: "center",
+    alignSelf: "start",
+    display: "flex",
+    justifyContent: "flex-end",
+    justifySelf: "stretch",
+    "min-inline-size": 0,
+    padding: "var(--layout-chrome-inset)",
+  },
+  loading: {
+    display: "grid",
+    gap: "var(--space-4)",
+    "inline-size": "min(100%, 36rem)",
+  },
+  root: {
+    display: "grid",
+    gridTemplateRows: "auto minmax(0, 1fr)",
+    "min-block-size": "100%",
+  },
+  row: {
+    alignItems: "center",
+    display: "flex",
+    flexWrap: "wrap",
+    gap: "var(--space-2)",
+  },
+  skeletons: {
+    display: "grid",
+    gap: "var(--space-2)",
+  },
+});