@hraness/design-kit 0.31.1

package/src/react/route-state.tsx

@@ -0,0 +1,350 @@
+"use client";
+
+import {
+  Skeleton,
+  Spinner,
+  cn,
+  type ContentHeadingLevel,
+} from "@hraness/ui";
+import * as stylex from "@stylexjs/stylex";
+import { useEffect, useId, useRef, type ReactNode } from "react";
+
+import { attachStatusPage } from "../browser/status-page.js";
+import { colors } from "../index.js";
+import {
+  STATUS_PAGE_AGENT_PREFIX,
+  STATUS_PAGE_BACK_LABEL,
+  STATUS_PAGE_HINT_PREFIX,
+  STATUS_PAGE_NEXT_HEADING_ID,
+  resolveStatusPage,
+  statusPageRoutesAttribute,
+  type StatusPageContent,
+} from "../status-page.js";
+import { PageCanvas } from "./surfaces.js";
+import { routeStateStyles } from "./route-state.stylex.js";
+import {
+  defaultDesignTheme,
+  DesignThemeProvider,
+  type DesignTheme,
+  ThemeColorSync,
+  ThemeMenuButton,
+} from "./theme.js";
+
+type StatusHeadingLevel = Exclude<ContentHeadingLevel, "h6">;
+
+export interface StatusPageProps extends StatusPageContent {
+  readonly canvasAs?: "div" | "main";
+  /** Adds a standalone header menu; product layouts should normally own it. */
+  readonly showThemeToggle?: boolean;
+  readonly titleAs?: StatusHeadingLevel;
+  /** Error pages only: renders Try again as the primary action. */
+  readonly onRetry?: () => void;
+  /** Error pages only: moves focus to the page and announces it. */
+  readonly announce?: boolean;
+  readonly autoFocus?: boolean;
+}
+
+const lowerHeading: Readonly<Record<StatusHeadingLevel, ContentHeadingLevel>> = {
+  h1: "h2", h2: "h3", h3: "h4", h4: "h5", h5: "h6",
+};
+
+/**
+ * Shared full-page status composition: the 404 page and recoverable errors.
+ * Markup matches `renderStatusPageHtml`, styled by `status-page.css`; the
+ * browser enhancement adds the dot field, the closest-page hint, and Back.
+ */
+export function StatusPage({
+  announce = true,
+  autoFocus = true,
+  canvasAs = "main",
+  onRetry,
+  showThemeToggle = false,
+  titleAs = "h1",
+  ...content
+}: StatusPageProps) {
+  const page = resolveStatusPage(content);
+  const rootRef = useRef<HTMLElement>(null);
+  const focusId = `${useId()}-status`;
+  const error = page.kind === "error";
+  const notFound = page.kind === "not-found";
+  const routes = notFound ? statusPageRoutesAttribute(page.routes) : undefined;
+  const Root = canvasAs;
+  const Title = titleAs;
+  const NextHeading = lowerHeading[titleAs];
+  const headerPresentation = stylex.props(routeStateStyles.header);
+
+  useEffect(() => {
+    const root = rootRef.current;
+    if (!root) return;
+    return attachStatusPage(root);
+  }, [routes]);
+  useEffect(() => {
+    if (error && autoFocus) rootRef.current?.focus();
+  }, [autoFocus, error]);
+
+  return (
+    <Root
+      aria-label={error ? page.title : undefined}
+      aria-live={error && announce ? "assertive" : undefined}
+      className="hraness-status-page"
+      data-hraness-status-routes={routes}
+      data-kind={page.kind}
+      id={error ? focusId : undefined}
+      ref={rootRef as never}
+      tabIndex={error ? -1 : undefined}
+    >
+      {showThemeToggle ? (
+        <header
+          {...headerPresentation}
+          className={cn("hraness-design-route-state__header", headerPresentation.className)}
+        >
+          <ThemeMenuButton />
+        </header>
+      ) : null}
+      <div className="hraness-status-page__inner">
+        <div aria-hidden="true" className="hraness-status-page__code">
+          <span className="hraness-status-page__glyph">{page.glyph}</span>
+          <canvas className="hraness-status-page__field" />
+        </div>
+        <Title className="hraness-status-page__title">{page.title}</Title>
+        <p className="hraness-status-page__summary">{page.summary}</p>
+        {notFound ? (
+          <p className="hraness-status-page__hint" hidden>
+            {STATUS_PAGE_HINT_PREFIX} <a className="hraness-status-page__hint-link" href="/" />?
+          </p>
+        ) : null}
+        <div className="hraness-status-page__actions">
+          {onRetry ? (
+            <>
+              <button
+                className="hraness-status-page__action hraness-foil"
+                data-emphasis="primary"
+                data-foil=""
+                onClick={onRetry}
+                type="button"
+              >
+                Try again
+              </button>
+              <a className="hraness-status-page__action" href={page.primaryAction.href}>
+                {page.primaryAction.label}
+              </a>
+            </>
+          ) : (
+            <a
+              className="hraness-status-page__action hraness-foil"
+              data-emphasis="primary"
+              data-foil=""
+              href={page.primaryAction.href}
+            >
+              {page.primaryAction.label}
+            </a>
+          )}
+          <a className="hraness-status-page__back" hidden href="/">{STATUS_PAGE_BACK_LABEL}</a>
+        </div>
+        {page.next.length === 0 ? null : (
+          <nav aria-labelledby={STATUS_PAGE_NEXT_HEADING_ID} className="hraness-status-page__next">
+            <NextHeading className="hraness-status-page__next-heading" id={STATUS_PAGE_NEXT_HEADING_ID}>
+              {page.nextHeading}
+            </NextHeading>
+            <ul className="hraness-status-page__next-list">
+              {page.next.map((link, index) => (
+                <li key={`${String(index)}:${link.href}`}>
+                  <a className="hraness-status-page__next-link" href={link.href}>
+                    <span className="hraness-status-page__next-label">{link.label}</span>
+                    {link.description === undefined ? null : (
+                      <span className="hraness-status-page__next-description">{link.description}</span>
+                    )}
+                  </a>
+                </li>
+              ))}
+            </ul>
+          </nav>
+        )}
+        {page.agentIndexHref === undefined ? null : (
+          <p className="hraness-status-page__agent">
+            {STATUS_PAGE_AGENT_PREFIX} <a href={page.agentIndexHref}>{page.agentIndexHref}</a>
+          </p>
+        )}
+      </div>
+    </Root>
+  );
+}
+
+export interface RouteErrorPageProps {
+  /** Set false only for an already-visible, inert demonstration of this state. */
+  readonly announce?: boolean;
+  /** Disable only when the full-page composition is rendered as an inert preview. */
+  readonly autoFocus?: boolean;
+  readonly canvasAs?: "div" | "main";
+  readonly error: Error & { readonly digest?: string };
+  readonly reset: () => void;
+  /** Adds a standalone header menu; product layouts should normally own it. */
+  readonly showThemeToggle?: boolean;
+  readonly titleAs?: StatusHeadingLevel;
+  /** Product name for the home action ("Go to Sponge"). */
+  readonly siteName?: string;
+  readonly homeHref?: string;
+}
+
+export type RouteNotFoundPageProps = Omit<StatusPageProps, "kind" | "onRetry" | "announce" | "autoFocus">;
+
+export interface RouteLoadingPageProps {
+  /** Set false only for an already-visible, inert demonstration of this state. */
+  readonly announce?: boolean;
+  readonly canvasAs?: "div" | "main";
+}
+
+export interface GlobalErrorDocumentProps extends RouteErrorPageProps {
+  readonly bodyClassName?: string;
+  /** Browser chrome color used whenever the resolved appearance is Dark. */
+  readonly darkColor?: string;
+  readonly diagnostics?: ReactNode;
+  /** Browser chrome color used whenever the resolved appearance is Light. */
+  readonly lightColor?: string;
+  /** Defaults to the shared stored preference with a System first-visit choice. */
+  readonly theme?: DesignTheme;
+}
+
+/** Shared root-segment 404 treatment for Next products. */
+export function RouteNotFoundPage(props: RouteNotFoundPageProps = {}) {
+  return <StatusPage {...props} kind="not-found" />;
+}
+
+/** Shared recoverable route-error treatment for Next products. */
+export function RouteErrorPage({
+  announce = true,
+  autoFocus = true,
+  canvasAs = "main",
+  error,
+  homeHref = "/",
+  reset,
+  showThemeToggle = false,
+  siteName,
+  titleAs = "h1",
+}: RouteErrorPageProps) {
+  return (
+    <StatusPage
+      announce={announce}
+      autoFocus={autoFocus}
+      canvasAs={canvasAs}
+      key={error.digest ?? error.message}
+      kind="error"
+      onRetry={reset}
+      primaryAction={{ href: homeHref, label: siteName ? `Go to ${siteName}` : "Return home" }}
+      showThemeToggle={showThemeToggle}
+      titleAs={titleAs}
+    />
+  );
+}
+
+/** Shared root loading treatment for Next products. */
+export function RouteLoadingPage({
+  announce = true,
+  canvasAs = "main",
+}: RouteLoadingPageProps = {}) {
+  const rootPresentation = stylex.props(routeStateStyles.root);
+  const loadingPresentation = stylex.props(routeStateStyles.loading);
+  const titlePresentation = stylex.props(routeStateStyles.row);
+  const skeletonPresentation = stylex.props(routeStateStyles.skeletons);
+
+  return (
+    <PageCanvas
+      aria-busy={announce ? "true" : undefined}
+      as={canvasAs}
+      className={cn(
+        "hraness-design-route-state",
+        rootPresentation.className,
+      )}
+    >
+      <section
+        {...loadingPresentation}
+        className={cn(
+          "hraness-design-route-state__loading",
+          loadingPresentation.className,
+        )}
+        role={announce ? "status" : undefined}
+      >
+        <div
+          {...titlePresentation}
+          className={cn(
+            "hraness-design-route-state__loading-title",
+            titlePresentation.className,
+          )}
+        >
+          <Spinner />
+          <strong>Loading page</strong>
+        </div>
+        <div
+          {...skeletonPresentation}
+          aria-hidden="true"
+          className={cn(
+            "hraness-design-route-state__skeletons",
+            skeletonPresentation.className,
+          )}
+        >
+          <Skeleton height="1rem" isText width="88%" />
+          <Skeleton height="1rem" isText width="64%" />
+          <Skeleton height="8rem" width="100%" />
+        </div>
+      </section>
+    </PageCanvas>
+  );
+}
+
+/**
+ * Last-resort Next boundary. It owns the document because global-error replaces
+ * the root layout, including its normal appearance provider.
+ */
+export function GlobalErrorDocument({
+  bodyClassName,
+  darkColor = colors.dark.background,
+  diagnostics,
+  lightColor = colors.light.background,
+  theme = defaultDesignTheme,
+  ...props
+}: GlobalErrorDocumentProps) {
+  const content = (
+    <>
+      {diagnostics}
+      <RouteErrorPage {...props} showThemeToggle={false} />
+    </>
+  );
+
+  return (
+    <html data-theme={theme === "system" ? "light" : theme} lang="en" suppressHydrationWarning>
+      <head>
+        <meta
+          content={theme === "system" ? "light dark" : theme}
+          name="color-scheme"
+        />
+        {theme === "system" ? (
+          <>
+            <meta
+              content={lightColor}
+              media="(prefers-color-scheme: light)"
+              name="theme-color"
+            />
+            <meta
+              content={darkColor}
+              media="(prefers-color-scheme: dark)"
+              name="theme-color"
+            />
+          </>
+        ) : (
+          <meta
+            content={theme === "dark" ? darkColor : lightColor}
+            name="theme-color"
+          />
+        )}
+      </head>
+      <body className={bodyClassName}>
+        {theme === "system" ? (
+          <DesignThemeProvider>
+            <ThemeColorSync darkColor={darkColor} lightColor={lightColor} />
+            {content}
+          </DesignThemeProvider>
+        ) : content}
+      </body>
+    </html>
+  );
+}

package/src/react/server.ts

@@ -0,0 +1,11 @@
+export * from "./article.js";
+export * from "./particle-halo.js";
+export * from "./procedural-backdrop.js";
+export * from "./procedural-recipe.js";
+export * from "./product-marketing.js";
+export * from "./surfaces.js";
+export * from "./syntax-code.js";
+export * from "./foil-mark.js";
+export * from "./provider-mark.js";
+export * from "./platform-icons.js";
+export * from "./launch-beats.js";

package/src/react/social-kit-panel.tsx

@@ -0,0 +1,103 @@
+import { useCallback, useId, useState } from "react";
+import {
+  blueskyPostLength,
+  characterLength,
+  LAUNCH_LIMITS,
+  xPostLength,
+  type SocialKit,
+} from "../launch.js";
+
+/*
+ * Client component: a closed <details> that lists every post in a social kit
+ * with its length against the channel limit and a copy button. It is for the
+ * person posting, so products render it only on their own post page, never
+ * in the article outline.
+ */
+
+type Entry = Readonly<{ key: string; label: string; text: string; length: number; limit: number }>;
+
+function kitEntries(kit: SocialKit): readonly Entry[] {
+  const thread = (channel: string, label: string, posts: readonly string[], measure: (text: string) => number, limit: number): Entry[] =>
+    posts.map((text, index) => ({ key: `${channel}.${index}`, label: `${label} ${index + 1} of ${posts.length}`, text, length: measure(text), limit }));
+  return [
+    ...thread("x", "X post", kit.x, xPostLength, LAUNCH_LIMITS.x),
+    ...thread("bluesky", "Bluesky post", kit.bluesky, blueskyPostLength, LAUNCH_LIMITS.bluesky),
+    ...thread("threads", "Threads post", kit.threads, characterLength, LAUNCH_LIMITS.threads),
+    { key: "linkedin", label: "LinkedIn post", text: kit.linkedin, length: characterLength(kit.linkedin), limit: LAUNCH_LIMITS.linkedin },
+    { key: "productHunt.tagline", label: "Product Hunt tagline", text: kit.productHunt.tagline, length: characterLength(kit.productHunt.tagline), limit: LAUNCH_LIMITS.productHuntTagline },
+    {
+      key: "productHunt.description",
+      label: "Product Hunt description",
+      text: kit.productHunt.description,
+      length: characterLength(kit.productHunt.description),
+      limit: LAUNCH_LIMITS.productHuntDescription,
+    },
+  ];
+}
+
+async function writeClipboard(text: string): Promise<boolean> {
+  try {
+    await navigator.clipboard.writeText(text);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * The social kit for a launch post: each post with a character counter and a
+ * copy button, plus the fact sheet for anyone writing their own post.
+ * Closed by default.
+ */
+export function SocialKitPanel({
+  className,
+  kit,
+  summary = "Social posts for this launch",
+}: Readonly<{ className?: string; kit: SocialKit; summary?: string }>) {
+  const id = useId();
+  const [status, setStatus] = useState<Readonly<{ key: string; ok: boolean }> | null>(null);
+  const copy = useCallback(async (entry: Entry) => {
+    setStatus({ key: entry.key, ok: await writeClipboard(entry.text) });
+  }, []);
+  const entries = kitEntries(kit);
+  return (
+    <details className={["plain-publication__social-kit", className].filter(Boolean).join(" ")} data-hraness-social-kit="">
+      <summary>{summary}</summary>
+      <ol className="plain-publication__social-kit-list">
+        {entries.map((entry) => {
+          const over = entry.length > entry.limit;
+          const counterId = `${id}-${entry.key}-count`;
+          return (
+            <li className="plain-publication__social-kit-item" data-over={over ? "" : undefined} key={entry.key}>
+              <div className="plain-publication__social-kit-head">
+                <span className="plain-publication__social-kit-label">{entry.label}</span>
+                <span className="plain-publication__social-kit-count" id={counterId}>
+                  {entry.length} of {entry.limit}
+                </span>
+                <button
+                  aria-describedby={counterId}
+                  className="plain-publication__social-kit-copy"
+                  onClick={() => void copy(entry)}
+                  type="button"
+                >
+                  {status?.key === entry.key ? (status.ok ? "Copied" : "Copy failed") : "Copy"}
+                  <span className="plain-publication__visually-hidden"> {entry.label}</span>
+                </button>
+              </div>
+              <p className="plain-publication__social-kit-text">{entry.text}</p>
+            </li>
+          );
+        })}
+      </ol>
+      {kit.showHnFacts.length === 0 ? null : (
+        <div className="plain-publication__social-kit-facts">
+          <p>Facts for your own post</p>
+          <ul>{kit.showHnFacts.map((fact) => <li key={fact}>{fact}</li>)}</ul>
+        </div>
+      )}
+      <p aria-live="polite" className="plain-publication__visually-hidden">
+        {status === null ? "" : status.ok ? "Copied to the clipboard." : "Copying failed. Select the text and copy it."}
+      </p>
+    </details>
+  );
+}

package/src/react/sticky-offset.tsx

@@ -0,0 +1,33 @@
+"use client";
+
+import { useEffect } from "react";
+
+import {
+  measureStickyOffset,
+  publishStickyOffset,
+  stickyOffsetCustomProperty,
+  stickyOffsetHeaderSelector,
+  syncStickyOffset,
+} from "../browser/sticky-offset.js";
+
+export type { StickyOffsetSyncOptions } from "../browser/sticky-offset.js";
+export {
+  measureStickyOffset,
+  publishStickyOffset,
+  stickyOffsetCustomProperty,
+  stickyOffsetHeaderSelector,
+  syncStickyOffset,
+};
+
+/**
+ * Measure sticky marketing chrome and publish --hraness-sticky-offset. Render
+ * once beside the site header; the helper does not run on module import.
+ */
+export function StickyOffsetSync({
+  header,
+}: Readonly<{
+  header?: string;
+}> = {}) {
+  useEffect(() => syncStickyOffset(header === undefined ? {} : { header }), [header]);
+  return null;
+}

package/src/react/surfaces.stylex.ts

@@ -0,0 +1,179 @@
+import * as stylex from "@stylexjs/stylex";
+
+export const ditherSurfaceStyles = stylex.create({
+  coarse: {
+    "--hraness-design-dither-size": "7px",
+  },
+  fine: {
+    "--hraness-design-dither-size": "3px",
+  },
+  texture: {
+    backgroundImage: {
+      default:
+        "radial-gradient(color-mix(in srgb, currentColor 18%, transparent) 0.75px, transparent 0.75px)",
+      "@media (forced-colors: active)": "none",
+    },
+    backgroundSize:
+      "var(--hraness-design-dither-size, 4px) var(--hraness-design-dither-size, 4px)",
+  },
+});
+
+const forcedColors = "@media (forced-colors: active)";
+
+export const layoutSurfaceStyles = stylex.create({
+  bar: {
+    alignItems: "center",
+    display: "flex",
+    gap: "var(--space-3)",
+    "min-inline-size": 0,
+  },
+  barContent: {
+    flex: "1 1 auto",
+  },
+  barPart: {
+    alignItems: "center",
+    display: "flex",
+    gap: "var(--space-2)",
+    "min-inline-size": 0,
+  },
+  bottomBar: {
+    "border-block-start-style": "solid",
+    "border-block-start-width": 1,
+    "min-block-size": "var(--bottom-bar-height)",
+    "padding-block": "var(--layout-chrome-inset)",
+    "padding-inline": "var(--layout-chrome-inset)",
+  },
+  dockedAbsolute: {
+    position: "absolute",
+  },
+  dockedContent: {
+    "inline-size": "min(100%, var(--page-canvas-width))",
+    "margin-inline": "auto",
+  },
+  dockedContentCompactInset: {
+    "padding-block":
+      "var(--space-1) max(var(--space-1), env(safe-area-inset-bottom))",
+    "padding-inline":
+      "max(var(--layout-edge-inset), env(safe-area-inset-left)) max(var(--layout-edge-inset), env(safe-area-inset-right))",
+  },
+  dockedContentCompactNoInset: {
+    "padding-block":
+      "var(--space-1) max(var(--space-1), env(safe-area-inset-bottom))",
+    "padding-inline":
+      "max(var(--layout-chrome-inset), env(safe-area-inset-left)) max(var(--layout-chrome-inset), env(safe-area-inset-right))",
+  },
+  dockedContentDefaultInset: {
+    "padding-block":
+      "var(--layout-chrome-inset) max(var(--layout-chrome-inset), env(safe-area-inset-bottom))",
+    "padding-inline":
+      "max(var(--layout-edge-inset), env(safe-area-inset-left)) max(var(--layout-edge-inset), env(safe-area-inset-right))",
+  },
+  dockedContentDefaultNoInset: {
+    "padding-block":
+      "var(--layout-chrome-inset) max(var(--layout-chrome-inset), env(safe-area-inset-bottom))",
+    "padding-inline":
+      "max(var(--layout-chrome-inset), env(safe-area-inset-left)) max(var(--layout-chrome-inset), env(safe-area-inset-right))",
+  },
+  dockedFixed: {
+    position: "fixed",
+  },
+  dockedFooter: {
+    "border-block-start-style": "solid",
+    "border-block-start-width": 1,
+    "inset-block-end": 0,
+    "inset-inline": 0,
+    zIndex: "var(--z-chrome)",
+  },
+  dockedSticky: {
+    position: "sticky",
+  },
+  fullSize: {
+    "max-inline-size": "none",
+  },
+  pageCanvas: {
+    "inline-size": "min(100%, var(--page-canvas-width))",
+    "margin-inline": "auto",
+    "min-inline-size": 0,
+  },
+  pageContentInset: {
+    "padding-block": "var(--layout-edge-inset)",
+    "padding-inline": "var(--layout-edge-inset)",
+  },
+  pageNoInset: {
+    "padding-block": 0,
+    "padding-inline": 0,
+  },
+  surface: {
+    backgroundAttachment: "scroll",
+    backgroundClip: "border-box",
+    backgroundColor: {
+      default: "var(--background)",
+      [forcedColors]: "Canvas",
+    },
+    backgroundImage: "none",
+    backgroundOrigin: "padding-box",
+    backgroundPosition: "0% 0%",
+    backgroundRepeat: "repeat",
+    backgroundSize: "auto",
+    "border-block-end-color": {
+      default: "var(--line)",
+      [forcedColors]: "CanvasText",
+    },
+    "border-block-start-color": {
+      default: "var(--line)",
+      [forcedColors]: "CanvasText",
+    },
+    "border-inline-end-color": {
+      default: "var(--line)",
+      [forcedColors]: "CanvasText",
+    },
+    "border-inline-start-color": {
+      default: "var(--line)",
+      [forcedColors]: "CanvasText",
+    },
+  },
+  topBar: {
+    "border-block-end-color": {
+      default: "var(--hraness-design-top-bar-edge, var(--line))",
+      [forcedColors]: "CanvasText",
+    },
+    "border-block-end-style": "solid",
+    "border-block-end-width": 1,
+    "min-block-size": "var(--top-bar-height)",
+  },
+  topBarActions: {
+    "margin-inline-start": "auto",
+  },
+  topBarGlass: {
+    // The global capability/media boundary binds both values locally; atoms
+    // paint them without repeating feature queries in optimized delivery.
+    "-webkit-backdrop-filter": "var(--hraness-design-top-bar-backdrop, none)",
+    "backdrop-filter": "var(--hraness-design-top-bar-backdrop, none)",
+    backgroundColor: {
+      default: "var(--hraness-design-top-bar-background, var(--background))",
+      [forcedColors]: "Canvas",
+    },
+  },
+  topBarSticky: {
+    "inset-block-start": 0,
+    "padding-block":
+      "max(var(--layout-chrome-inset), env(safe-area-inset-top)) var(--layout-chrome-inset)",
+    "padding-inline":
+      "max(var(--layout-chrome-inset), env(safe-area-inset-left)) max(var(--layout-chrome-inset), env(safe-area-inset-right))",
+    position: "sticky",
+    zIndex: "var(--z-chrome)",
+  },
+  topBarStatic: {
+    "padding-block": "var(--layout-chrome-inset)",
+    "padding-inline": "var(--layout-chrome-inset)",
+  },
+  topBarTitle: {
+    fontWeight: "var(--font-weight-bold)",
+    overflow: "hidden",
+    textOverflow: "ellipsis",
+    whiteSpace: "nowrap",
+  },
+  wideSize: {
+    "max-inline-size": "var(--page-canvas-wide)",
+  },
+});