@hraness/design-kit 0.34.0 → 0.35.1

package/src/react/marketing-account.stylex.ts

@@ -0,0 +1,74 @@
+import * as stylex from "@stylexjs/stylex";
+
+export const marketingAccountStyles = stylex.create({
+  section: {
+    alignItems: "center",
+    "border-top": "var(--hraness-marketing-rule, 1px solid var(--line))",
+    color: "var(--foreground)",
+    display: "grid",
+    gap: "2rem 4rem",
+    gridTemplateColumns: { default: "minmax(0, 1fr)", "@media (min-width: 50rem)": "minmax(0, 1fr) minmax(0, 1fr)" },
+    paddingBlock: "clamp(2.5rem, 6vw, 4rem)",
+    scrollMarginTop: "calc(var(--hraness-sticky-offset, 5rem) + 2rem)",
+  },
+  copy: { minWidth: 0 },
+  heading: {
+    fontFamily: "var(--font-text)",
+    fontSize: "clamp(1.625rem, 1.3rem + 1vw, 2.25rem)",
+    fontWeight: 550,
+    letterSpacing: "-0.02em",
+    lineHeight: 1.15,
+    margin: 0,
+    textWrap: "balance",
+  },
+  summary: {
+    color: "var(--muted)",
+    fontSize: "1rem",
+    lineHeight: 1.6,
+    marginTop: "1rem",
+    maxWidth: "42ch",
+    textWrap: "pretty",
+  },
+  content: { minWidth: 0 },
+  actions: { alignItems: "center", display: "flex", flexWrap: "wrap", gap: "0.75rem 1.5rem" },
+  primary: {
+    alignItems: "center",
+    backgroundColor: { default: "var(--primary)", ":hover": "color-mix(in oklch, var(--primary) 88%, var(--foreground))", "@media (forced-colors: active)": "ButtonFace" },
+    borderWidth: "1px",
+    borderStyle: "solid",
+    borderColor: { default: "transparent", "@media (forced-colors: active)": "ButtonText" },
+    borderRadius: "0.625rem",
+    color: { default: "var(--primary-foreground)", "@media (forced-colors: active)": "ButtonText" },
+    display: "inline-flex",
+    fontFamily: "var(--font-text)",
+    fontSize: "1.0625rem",
+    fontWeight: 550,
+    justifyContent: "center",
+    lineHeight: 1.3,
+    maxWidth: "100%",
+    minHeight: "3.5rem",
+    outline: { default: null, ":focus-visible": "2px solid var(--primary)" },
+    outlineOffset: { default: null, ":focus-visible": "3px" },
+    paddingBlock: "0.875rem",
+    paddingInline: "1.5rem",
+    textAlign: "center",
+    textDecoration: "none",
+  },
+  signIn: {
+    alignItems: "center",
+    color: "var(--foreground)",
+    display: "inline-flex",
+    fontFamily: "var(--font-text)",
+    fontSize: "1.0625rem",
+    fontWeight: 450,
+    lineHeight: 1.3,
+    minHeight: "3.5rem",
+    outline: { default: null, ":focus-visible": "2px solid var(--primary)" },
+    outlineOffset: { default: null, ":focus-visible": "3px" },
+    textDecorationLine: "underline",
+    textDecorationStyle: "dotted",
+    textDecorationColor: { default: "color-mix(in srgb, currentColor 45%, transparent)", ":hover": "currentColor", "@media (forced-colors: active)": "LinkText" },
+    textDecorationThickness: "1px",
+    textUnderlineOffset: "0.22em",
+  },
+});

package/src/react/marketing-account.tsx

@@ -0,0 +1,69 @@
+import * as stylex from "@stylexjs/stylex";
+import type { ReactNode } from "react";
+
+import { marketingAccountStyles as styles } from "./marketing-account.stylex.js";
+
+/** Optional account access near the end of a product's marketing page. */
+export function MarketingAccount({
+  children,
+  className,
+  heading = "Your account",
+  id = "account",
+  summary,
+}: Readonly<{
+  children: ReactNode;
+  className?: string;
+  heading?: string;
+  id?: string;
+  summary: ReactNode;
+}>) {
+  const presentation = stylex.props(styles.section);
+  return (
+    <section
+      {...presentation}
+      aria-labelledby={`${id}-heading`}
+      className={["hraness-marketing-account", presentation.className, className].filter(Boolean).join(" ")}
+      id={id}
+    >
+      <div {...stylex.props(styles.copy)}>
+        <h2 {...stylex.props(styles.heading)} id={`${id}-heading`}>{heading}</h2>
+        <div {...stylex.props(styles.summary)}>{summary}</div>
+      </div>
+      <div {...stylex.props(styles.content)}>{children}</div>
+    </section>
+  );
+}
+
+export interface MarketingAccountAction {
+  readonly href: string;
+  readonly analyticsEvent?: string;
+  readonly analyticsId?: string;
+}
+
+/** One prominent account action and an optional, equally tall sign-in link. */
+export function MarketingAccountActions({ primary, signIn }: Readonly<{
+  primary: MarketingAccountAction & Readonly<{ label: string }>;
+  signIn?: MarketingAccountAction;
+}>) {
+  return (
+    <div {...stylex.props(styles.actions)} className={`hraness-marketing-account__actions ${stylex.props(styles.actions).className}`}>
+      <a
+        {...stylex.props(styles.primary)}
+        className={`hraness-marketing-account__primary ${stylex.props(styles.primary).className}`}
+        data-analytics-event={primary.analyticsEvent}
+        data-analytics-id={primary.analyticsId}
+        data-emphasis="primary"
+        href={primary.href}
+      >{primary.label}</a>
+      {signIn === undefined ? null : (
+        <a
+          {...stylex.props(styles.signIn)}
+          className={`hraness-marketing-account__sign-in ${stylex.props(styles.signIn).className}`}
+          data-analytics-event={signIn.analyticsEvent}
+          data-analytics-id={signIn.analyticsId}
+          href={signIn.href}
+        >Sign in</a>
+      )}
+    </div>
+  );
+}

package/src/react/marketing-comparison.stylex.ts

@@ -0,0 +1,24 @@
+import * as stylex from "@stylexjs/stylex";
+
+export const comparisonStyles = stylex.create({
+  figure: { "margin": "0", "min-inline-size": "0", "color": "var(--hraness-marketing-ink, var(--foreground))", "font-family": "var(--font-text)" },
+  scroll: { "overflow-x": "auto", "max-inline-size": "100%", "outline": { "default": null, ":focus-visible": "2px solid var(--primary)" }, "outline-offset": { "default": null, ":focus-visible": "3px" } },
+  table: { "inline-size": "100%", "border-collapse": "collapse", "text-align": "start", "font-size": "0.9375rem", "line-height": "1.4" },
+  caption: { "padding-block-end": "1.25rem", "text-align": "start", "font-size": "1.125rem", "font-weight": "550", "color": "var(--foreground)" },
+  corner: { "min-inline-size": "9rem", "border-block-end": "1px solid var(--line)" },
+  option: { "padding": "1rem", "min-inline-size": "8.5rem", "border-block-end": "1px solid var(--line)", "vertical-align": "bottom", "font-weight": "600" },
+  optionLabel: { "display": "flex", "align-items": "center", "gap": "0.6rem" },
+  mark: { "object-fit": "contain", "flex-shrink": "0", "inline-size": "1.5rem", "block-size": "1.5rem" },
+  rowLabel: { "padding": "1rem 1rem 1rem 0", "min-inline-size": "9rem", "max-inline-size": "15rem", "border-block-end": "1px solid var(--line)", "vertical-align": "top", "font-weight": "500" },
+  cell: { "padding": "1rem", "border-block-end": "1px solid var(--line)", "vertical-align": "top" },
+  highlight: { "background-color": { "default": "color-mix(in srgb, var(--primary) 5%, transparent)", "@media (forced-colors: active)": "Canvas" }, "color": "var(--foreground)" },
+  value: { "display": "grid", "gap": "0.25rem" },
+  label: { "display": "flex", "align-items": "flex-start", "gap": "0.45rem" },
+  glyph: { "flex-shrink": "0", "margin-block-start": "0.1rem", "inline-size": "1.125rem", "block-size": "1.125rem" },
+  positive: { "color": { "default": "var(--hraness-studio-emerald)", "@media (forced-colors: active)": "CanvasText" } },
+  negative: { "color": { "default": "var(--muted)", "@media (forced-colors: active)": "CanvasText" } },
+  conditional: { "color": { "default": "var(--hraness-studio-amber)", "@media (forced-colors: active)": "CanvasText" } },
+  text: { "font-variant-numeric": "tabular-nums" },
+  detail: { "display": "block", "color": "var(--muted)", "font-size": "0.8125rem", "font-weight": "400", "line-height": "1.45", "margin-block-start": "0.2rem", "max-inline-size": "26ch" },
+  note: { "color": "var(--muted)", "font-size": "0.875rem", "line-height": "1.5", "margin-block-start": "1rem", "max-inline-size": "76ch" },
+});

package/src/react/marketing-comparison.tsx

@@ -0,0 +1,73 @@
+import * as stylex from "@stylexjs/stylex";
+import type { ReactNode } from "react";
+import { ComparisonGlyph } from "./article.js";
+import { comparisonStyles as styles } from "./marketing-comparison.stylex.js";
+
+export type MarketingComparisonStatus = "yes" | "no" | "partial" | "optional" | "depends";
+export type MarketingComparisonValue = boolean | "partial" | string | Readonly<{
+  status: MarketingComparisonStatus;
+  label?: string;
+  detail?: string;
+}>;
+export interface MarketingComparisonOption { readonly name: string; readonly mark?: string }
+export interface MarketingComparisonRow {
+  readonly label: string;
+  readonly values: readonly MarketingComparisonValue[];
+  readonly note?: string;
+}
+const labels = { yes: "Yes", no: "No", partial: "Partly", optional: "Optional", depends: "Depends" } as const;
+
+function presentation(slot: string, props: ReturnType<typeof stylex.props>) {
+  const hook = slot.replace(/[A-Z]/gu, (letter) => `-${letter.toLowerCase()}`);
+  return { ...props, className: `hraness-marketing-comparison__${hook} ${props.className}` };
+}
+
+function Value({ value }: Readonly<{ value: MarketingComparisonValue }>) {
+  if (typeof value === "string" && value !== "partial") return <span {...presentation("text", stylex.props(styles.text))}>{value}</span>;
+  const status = typeof value === "object" ? value.status : value === true ? "yes" : value === false ? "no" : "partial";
+  const label = typeof value === "object" ? value.label ?? labels[status] : labels[status];
+  const detail = typeof value === "object" ? value.detail : undefined;
+  return <div {...presentation("value", stylex.props(styles.value))} data-comparison-status={status}>
+    <span {...presentation("label", stylex.props(styles.label))}>
+      <ComparisonGlyph className={`hraness-marketing-comparison__glyph ${stylex.props(styles.glyph, status === "yes" ? styles.positive : status === "no" ? styles.negative : styles.conditional).className}`}
+        kind={status === "yes" || status === "no" ? status : "partial"} />
+      <span>{label}</span>
+    </span>
+    {detail === undefined ? null : <small {...presentation("detail", stylex.props(styles.detail))}>{detail}</small>}
+  </div>;
+}
+
+/** Concise product comparisons with visible words for every icon and conditional claim. */
+export function MarketingComparison({ caption, className, highlight, id, note, options, rows }: Readonly<{
+  caption: string;
+  className?: string;
+  highlight?: number;
+  id?: string;
+  note?: ReactNode;
+  options: readonly MarketingComparisonOption[];
+  rows: readonly MarketingComparisonRow[];
+}>) {
+  if (caption.trim() === "") throw new RangeError("Marketing comparison needs a caption.");
+  if (options.length === 0) throw new RangeError("Marketing comparison needs at least one option.");
+  if (highlight !== undefined && (!Number.isInteger(highlight) || highlight < 0 || highlight >= options.length)) throw new RangeError("Marketing comparison highlight must be an option index.");
+  for (const row of rows) if (row.values.length !== options.length) throw new RangeError(`Marketing comparison row ${JSON.stringify(row.label)} must have one value per option.`);
+  return <figure {...presentation("figure", stylex.props(styles.figure))} className={["hraness-marketing-comparison", stylex.props(styles.figure).className, className].filter(Boolean).join(" ")} id={id}>
+    <div {...presentation("scroll", stylex.props(styles.scroll))} aria-label={caption} role="region" tabIndex={0}>
+      <table {...presentation("table", stylex.props(styles.table))}>
+        <caption {...presentation("caption", stylex.props(styles.caption))}>{caption}</caption>
+        <thead><tr><td {...presentation("corner", stylex.props(styles.corner))} />{options.map((option, index) =>
+          <th {...presentation("option", stylex.props(styles.option, index === highlight && styles.highlight))} data-highlight={index === highlight ? "" : undefined} key={option.name} scope="col">
+            <span {...presentation("optionLabel", stylex.props(styles.optionLabel))}>
+              {option.mark === undefined ? null : <img alt="" {...presentation("mark", stylex.props(styles.mark))} height={24} src={option.mark} width={24} />}
+              <span>{option.name}</span>
+            </span>
+          </th>)}</tr></thead>
+        <tbody>{rows.map((row) => <tr key={row.label}>
+          <th {...presentation("rowLabel", stylex.props(styles.rowLabel))} scope="row">{row.label}{row.note === undefined ? null : <small {...presentation("detail", stylex.props(styles.detail))}>{row.note}</small>}</th>
+          {row.values.map((value, index) => <td {...presentation("cell", stylex.props(styles.cell, index === highlight && styles.highlight))} data-highlight={index === highlight ? "" : undefined} key={index}><Value value={value} /></td>)}
+        </tr>)}</tbody>
+      </table>
+    </div>
+    {note === undefined || note === null ? null : <figcaption {...presentation("note", stylex.props(styles.note))}>{note}</figcaption>}
+  </figure>;
+}

package/src/react/marketing-diagram.stylex.ts

@@ -0,0 +1,8 @@
+import * as stylex from "@stylexjs/stylex";
+
+export const diagramStyles = stylex.create({
+  figure: { "margin": "0", "min-inline-size": "0", "color": "var(--foreground)", "font-family": "var(--font-text)" },
+  scroll: { "overflow-x": "auto", "max-inline-size": "100%", "outline": { "default": null, ":focus-visible": "2px solid var(--primary)" }, "outline-offset": { "default": null, ":focus-visible": "3px" } },
+  canvas: { "display": "block", "inline-size": "100%", "min-inline-size": "40rem", "block-size": "auto", "font-family": "var(--font-text)", "font-size": "20px", "color": "var(--primary)" },
+  caption: { "margin-block-start": "1rem", "max-inline-size": "76ch", "color": "var(--muted)", "font-size": "0.875rem", "line-height": "1.5" },
+});

package/src/react/marketing-diagram.tsx

@@ -0,0 +1,33 @@
+import * as stylex from "@stylexjs/stylex";
+import type { ReactNode } from "react";
+import { diagramMetrics } from "../diagrams.js";
+import { diagramStyles as styles } from "./marketing-diagram.stylex.js";
+
+/** A bounded arrowhead whose paint follows its connector's stroke. IDs are caller-owned. */
+export function DiagramArrowhead({ id }: Readonly<{ id: string }>) {
+  if (id.trim() === "" || /\s/u.test(id)) throw new RangeError("Diagram arrowhead needs one nonempty SVG ID.");
+  return <marker id={id} markerHeight={diagramMetrics.arrowheadSize} markerUnits="userSpaceOnUse" markerWidth={diagramMetrics.arrowheadSize} orient="auto-start-reverse" refX="5.5" refY="3" viewBox="0 0 6 6">
+    <path d="M0 0 L6 3 L0 6 Z" fill="context-stroke" />
+  </marker>;
+}
+
+/** An accessible SVG frame. Layout and facts stay with the consuming product. */
+export function MarketingDiagram({ caption, children, className, height, label, width }: Readonly<{
+  caption?: ReactNode;
+  children: ReactNode;
+  className?: string;
+  height: number;
+  label: string;
+  width: number;
+}>) {
+  if (!Number.isFinite(width) || !Number.isFinite(height) || width <= 0 || height <= 0) throw new RangeError("Marketing diagram dimensions must be positive.");
+  if (label.trim() === "") throw new RangeError("Marketing diagram needs a useful accessible label.");
+  return <figure className={["hraness-diagram", stylex.props(styles.figure).className, className].filter(Boolean).join(" ")}>
+    <div {...stylex.props(styles.scroll)} className={`hraness-diagram__scroll ${stylex.props(styles.scroll).className}`} aria-label={label} role="region" tabIndex={0}>
+      <svg {...stylex.props(styles.canvas)} className={`hraness-diagram__canvas ${stylex.props(styles.canvas).className}`} aria-label={label} height={height} role="img" viewBox={`0 0 ${width} ${height}`} width={width}>
+        {children}
+      </svg>
+    </div>
+    {caption === undefined || caption === null ? null : <figcaption {...stylex.props(styles.caption)}>{caption}</figcaption>}
+  </figure>;
+}

package/src/react/platform-install.stylex.ts

@@ -156,11 +156,12 @@ export const platformInstallStyles = stylex.create({
   },
   command: {
     backgroundColor: { default: surface, [forced]: "Canvas" },
-    borderColor: { default: line, [forced]: "CanvasText" },
+    borderColor: { default: `color-mix(in srgb, ${focusRing} 34%, ${line})`, [forced]: "CanvasText" },
     borderRadius: "0.75rem",
     borderStyle: "solid",
     borderWidth: "1px",
     boxSizing: "border-box",
+    boxShadow: { default: `0 3px 16px color-mix(in srgb, ${focusRing} 7%, transparent)`, [forced]: "none" },
     display: "grid",
     minInlineSize: 0,
     overflow: "hidden",
@@ -220,40 +221,6 @@ export const platformInstallStyles = stylex.create({
     fontSize: "inherit",
     padding: 0,
   },
-  copy: {
-    alignItems: "center",
-    appearance: "none",
-    backgroundColor: {
-      default: `color-mix(in srgb, ${ink} 4%, ${surface})`,
-      ":hover": `color-mix(in srgb, ${ink} 9%, ${surface})`,
-      [forced]: "ButtonFace",
-    },
-    borderColor: { default: line, [forced]: "ButtonText" },
-    borderRadius: "0.5rem",
-    borderStyle: "solid",
-    borderWidth: "1px",
-    boxSizing: "border-box",
-    color: { default: ink, [forced]: "ButtonText" },
-    cursor: "pointer",
-    display: { default: "inline-flex", [noScript]: "none" },
-    flexShrink: 0,
-    fontFamily: textFont,
-    fontSize: "0.8125rem",
-    fontWeight: 500,
-    gap: "0.35rem",
-    lineHeight: 1,
-    margin: 0,
-    minBlockSize: { default: "2rem", "@media (pointer: coarse)": "2.75rem" },
-    outline: { default: "none", ":focus-visible": `2px solid ${focusRing}` },
-    outlineOffset: "1px",
-    paddingBlock: "0.35rem",
-    paddingInline: "0.65rem",
-  },
-  copyIcon: {
-    blockSize: "0.95rem",
-    flexShrink: 0,
-    inlineSize: "0.95rem",
-  },
   alternatives: {
     display: "grid",
     gap: "0.6rem",
@@ -268,6 +235,13 @@ export const platformInstallStyles = stylex.create({
     lineHeight: 1.5,
     margin: 0,
   },
+  commandNote: {
+    borderBlockStartColor: { default: line, [forced]: "CanvasText" },
+    borderBlockStartStyle: "solid",
+    borderBlockStartWidth: "1px",
+    paddingBlock: "0.65rem",
+    paddingInline: "0.95rem",
+  },
   unavailable: {
     borderColor: { default: line, [forced]: "CanvasText" },
     borderRadius: "0.75rem",
@@ -358,8 +332,6 @@ const hooks: Partial<Record<Part, string>> = {
   code: "hraness-platform-install__code",
   command: "hraness-platform-install__command",
   commandBar: "hraness-platform-install__command-bar",
-  copy: "hraness-platform-install__copy",
-  copyIcon: "hraness-platform-install__copy-icon",
   icon: "hraness-platform-icon",
   markSymbols: "hraness-platform-install__marks",
   note: "hraness-platform-install__note",

package/src/react/platform-install.tsx

@@ -11,6 +11,8 @@ import {
   platformMark,
   type PlatformId,
 } from "../platforms.js";
+import { SetupCopyButton } from "./setup-copy-button.js";
+import { SyntaxCode } from "./syntax-code.js";
 import { platformInstallClassName as cx } from "./platform-install.stylex.js";
 
 /** Another way to install on the same platform, such as npm or Homebrew. */
@@ -28,7 +30,7 @@ interface PlatformInstallTargetBase {
   readonly label?: string;
   /** Where the command runs, such as "Terminal" or "PowerShell". */
   readonly shell?: string;
-  /** A short qualifier under the command, such as "Apple silicon" or "x86_64 and ARM64, glibc 2.34+". */
+  /** A short qualifier in the primary command footer, such as "Apple silicon" or "Requires Bun 1.3.14+". */
   readonly note?: ReactNode;
   readonly alternatives?: readonly PlatformInstallAlternative[];
 }
@@ -166,22 +168,12 @@ function PlatformMarkUse({ platform, symbolId }: Readonly<{ platform: PlatformId
   );
 }
 
-function CopyGlyph({ copied }: Readonly<{ copied: boolean }>) {
-  return (
-    <svg aria-hidden="true" className={cx(["copyIcon"])} fill="none" focusable="false" stroke="currentColor"
-      strokeLinecap="round" strokeLinejoin="round" strokeWidth={2} viewBox="0 0 24 24">
-      {copied
-        ? <path d="M5 12.5l4.5 4.5L19 7.5" />
-        : <><rect height="12" rx="2" width="12" x="8" y="8" /><path d="M16 8V6a2 2 0 0 0-2-2H6a2 2 0 0 0-2 2v8a2 2 0 0 0 2 2h2" /></>}
-    </svg>
-  );
-}
-
 function CommandBlock({
   caption,
   command,
   copyKey,
   onCopy,
+  note,
   status,
   subject,
 }: Readonly<{
@@ -189,6 +181,7 @@ function CommandBlock({
   command: string;
   copyKey: string;
   onCopy: (key: string, command: string, subject: string, pre: HTMLElement | null) => void;
+  note?: ReactNode;
   status: CopyStatus | null;
   subject: string;
 }>) {
@@ -198,21 +191,20 @@ function CommandBlock({
     <div className={cx(["command"])} data-copy-state={state}>
       <div className={cx(["commandBar", (caption === undefined || caption === "") && "commandBarEmpty"])}>
         <span className={cx(["shell"])}>{caption}</span>
-        <button
-          className={cx(["copy"])}
-          data-copy-state={state}
-          onClick={() => onCopy(copyKey, command, subject, preRef.current)}
-          type="button"
-        >
-          <CopyGlyph copied={state === "copied"} />
-          <span>{state === "copied" ? "Copied" : state === "failed" ? "Select to copy" : "Copy"}</span>
-          <span className={cx(["status"])}> {subject}</span>
-        </button>
+        <SetupCopyButton
+          className="hraness-platform-install__copy"
+          iconClassName="hraness-platform-install__copy-icon"
+          failedLabel="Select to copy"
+          onCopy={() => onCopy(copyKey, command, subject, preRef.current)}
+          state={state}
+          subject={subject}
+        />
       </div>
       {/* Focusable so keyboard users can scroll a long command sideways. */}
       <pre aria-label={subject} className={cx(["pre"])} ref={preRef} tabIndex={0}>
-        <code className={cx(["code"])}>{command}</code>
+        <SyntaxCode className={cx(["code"])} code={command} language="shell" styles="classes" />
       </pre>
+      {note === undefined ? null : <div className={cx(["note", "commandNote"])}>{note}</div>}
     </div>
   );
 }
@@ -356,6 +348,7 @@ export function PlatformInstall({
                   command={target.command}
                   copyKey={`${target.id}:primary`}
                   onCopy={copy}
+                  note={target.note}
                   status={status}
                   subject={`${name} install command`}
                 />
@@ -376,7 +369,7 @@ export function PlatformInstall({
                   ))}
                 </ul>
               )}
-              {target.note === undefined ? null : <div className={cx(["note"])}>{target.note}</div>}
+              {target.command !== undefined || target.note === undefined ? null : <div className={cx(["note"])}>{target.note}</div>}
             </div>
           </div>
         );