@hraness/design-kit 0.39.0 → 0.40.1

package/dist/stylex.css

@@ -4031,6 +4031,10 @@
     .x1k5gbb1.x1k5gbb1 {
       color: highlighttext;
     }
+
+    .x1ljrylj.x1ljrylj {
+      color: linktext;
+    }
   }
 
   @media (width <= 48rem) {

package/dist/testing.js

@@ -237,14 +237,34 @@ function assertFakeHandles(html, allowedHandles, label = "markup") {
       fail(`${label} links to ${match[1] ?? ""}, which is not a reserved example domain.`);
   }
 }
+var WALKTHROUGH_COPY_LIMITS = Object.freeze({
+  labelWords: 3,
+  hintCharacters: 60
+});
+function assertWalkthroughCopy(steps, label = "walkthrough") {
+  for (const step of steps) {
+    const words = step.label.trim().split(/\s+/u).filter(Boolean).length;
+    if (words === 0 || words > WALKTHROUGH_COPY_LIMITS.labelWords)
+      fail(`${label} step "${step.id}" label has ${String(words)} words; use one to ${String(WALKTHROUGH_COPY_LIMITS.labelWords)}.`);
+    const hint = step.hint?.trim();
+    if (hint === undefined || hint === "")
+      continue;
+    if (hint.length > WALKTHROUGH_COPY_LIMITS.hintCharacters)
+      fail(`${label} step "${step.id}" hint is ${String(hint.length)} characters; keep it within ${String(WALKTHROUGH_COPY_LIMITS.hintCharacters)}.`);
+    if ((hint.match(/[.!?](\s|$)/gu) ?? []).length > 1)
+      fail(`${label} step "${step.id}" hint has more than one sentence.`);
+  }
+}
 export {
   stripMockupSamples,
   renderMatrix,
   htmlText,
   blogConformance,
+  assertWalkthroughCopy,
   assertRoleImgWithLabel,
   assertNoHeadings,
   assertFakeHandles,
+  WALKTHROUGH_COPY_LIMITS,
   ConformanceError,
   BLOG_CONFORMANCE_LIMITS
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hraness/design-kit",
-  "version": "0.39.0",
+  "version": "0.40.1",
   "description": "React components and CSS for Hraness apps and product sites: application shells, marketing sections, charts, themes, effects, and syntax highlighting. Built on @hraness/ui.",
   "license": "MIT",
   "type": "module",

package/portfolio-inventory.json

@@ -6,7 +6,7 @@
       "name": "@hraness/design-kit",
       "path": ".",
       "visibility": "public",
-      "version": "0.39.0"
+      "version": "0.40.1"
     }
   ],
   "contract": "hraness.portfolio-inventory/v1",

package/src/mockups/client.tsx

@@ -373,17 +373,61 @@ export type ThroughStep = Readonly<{
 }>;
 
 /** Fill owns the outer shell and its top-level frames, never nested width-fit graphics. */
-function fillFrames(stage: HTMLElement): HTMLElement[] {
-  const frames: HTMLElement[] = [];
+function panelFillFrames(stage: HTMLElement): HTMLElement[][] {
+  const panels: HTMLElement[][] = [];
   for (const panel of stage.querySelectorAll<HTMLElement>(":scope > .hkm-step-panel, :scope > .hkm-mode-surface")) {
     const fit = panel.querySelector<HTMLElement>(":scope > .hkm-fit");
     if (fit === null) continue;
+    const frames: HTMLElement[] = [];
     for (const root of fit.querySelectorAll<HTMLElement>(".hkm-root")) {
       const enclosingRoot = root.parentElement?.closest(".hkm-root");
       if (root.closest(".hkm-fit") === fit && (enclosingRoot === null || enclosingRoot === undefined || !fit.contains(enclosingRoot))) frames.push(root);
     }
+    panels.push(frames);
+  }
+  return panels;
+}
+
+function fillFrames(stage: HTMLElement): HTMLElement[] {
+  return panelFillFrames(stage).flat();
+}
+
+/**
+ * Mark each panel's frame, and the product wrappers between it and the fit,
+ * so a frame wrapped in product markup still grows to the full stage instead
+ * of leaving an empty band under a shorter slide. A panel with several
+ * top-level frames keeps its own arrangement.
+ */
+function markFillFrames(stage: HTMLElement): void {
+  for (const frames of panelFillFrames(stage)) {
+    for (const frame of frames) frame.setAttribute("data-hkm-fill-frame", "");
+    const [frame] = frames;
+    if (frames.length !== 1 || frame === undefined) continue;
+    const path: HTMLElement[] = [];
+    for (let node = frame.parentElement; node !== null; node = node.parentElement) {
+      path.push(node);
+      if (node.classList.contains("hkm-fit-inner")) break;
+    }
+    // Only single-column wrappers become a stack; a side-by-side product
+    // layout keeps its own arrangement.
+    if (path.every(stacksVertically)) for (const node of path) node.setAttribute("data-hkm-fill-path", "");
+  }
+}
+
+function stacksVertically(node: HTMLElement): boolean {
+  if (node.hasAttribute("data-hkm-fill-path")) return true;
+  const style = getComputedStyle(node);
+  if (style.display === "block" || style.display === "flow-root") return true;
+  if (style.display === "grid") return style.gridTemplateColumns.trim().split(/\s+/u).length === 1;
+  if (style.display === "flex") return style.flexDirection.startsWith("column");
+  return false;
+}
+
+function clearFillFrames(stage: HTMLElement): void {
+  for (const node of stage.querySelectorAll("[data-hkm-fill-frame], [data-hkm-fill-path]")) {
+    node.removeAttribute("data-hkm-fill-frame");
+    node.removeAttribute("data-hkm-fill-path");
   }
-  return frames;
 }
 
 function presentationBodies(stage: HTMLElement): HTMLElement[] {
@@ -413,7 +457,7 @@ function measureNestedFits(stage: HTMLElement): void {
 function fitShowcaseStage(stage: HTMLDivElement, minimumHeight: number): void {
   const owner = stage.parentElement;
   if (owner === null || stage.clientWidth <= 0) return;
-  for (const frame of fillFrames(stage)) frame.setAttribute("data-hkm-fill-frame", "");
+  markFillFrames(stage);
   const probe = stage.cloneNode(true) as HTMLDivElement;
   probe.setAttribute("aria-hidden", "true");
   probe.setAttribute("inert", "");
@@ -501,7 +545,7 @@ function useFittedShowcaseStage(fit: "natural" | "fill", source: unknown, variat
       node.style.removeProperty("--hkm-showcase-fill-height");
       node.removeAttribute("data-hkm-fitted");
       for (const body of presentationBodies(node)) body.style.removeProperty("--hkm-terminal-presentation-size");
-      for (const frame of fillFrames(node)) frame.removeAttribute("data-hkm-fill-frame");
+      clearFillFrames(node);
     };
   }, [fit, source, variation, minimumHeight]);
   return stage;
@@ -538,6 +582,14 @@ export function StepThrough({
   assertUniqueIds(steps, "StepThrough step");
   if (fit !== "natural" && fit !== "fill") throw new RangeError("StepThrough fit must be natural or fill.");
   const stage = useFittedShowcaseStage(fit, steps);
+  // Natural walkthroughs fit by width only, but still stretch each slide's
+  // frame to the shared stage height. Fill walkthroughs mark frames while fitting.
+  useIsomorphicLayoutEffect(() => {
+    const node = stage.current;
+    if (fit === "fill" || node === null) return undefined;
+    markFillFrames(node);
+    return () => clearFillFrames(node);
+  }, [fit, steps]);
   const captionText = optionalText(caption, "StepThrough");
   const id = useId();
   const [index, setIndex] = useState(() => Math.max(0, steps.findIndex((step) => step.id === initial)));

package/src/mockups.css

@@ -2593,11 +2593,37 @@
     min-block-size: 0;
   }
 
-  .hkm-showcase[data-hkm-fit="fill"] :is(.hkm-step-stage, .hkm-mode-stage):not([data-hkm-measuring]) [data-hkm-fill-frame] > .hkm-window:has(> .hkm-page) {
+  /* A slide never leaves an empty band under a shorter frame. Each panel's
+   * single top-level frame grows to the stage through any product wrappers
+   * (marked as the fill path), and its window body takes the remaining height. */
+  /* Important so a product wrapper's own single-column grid or block layout
+   * cannot leave the extra height in its rows instead of the frame. */
+  .hkm-showcase :is(.hkm-step-stage, .hkm-mode-stage):not([data-hkm-measuring]) [data-hkm-fill-path] {
+    display: flex !important;
+    flex-direction: column !important;
+  }
+
+  .hkm-showcase :is(.hkm-step-stage, .hkm-mode-stage):not([data-hkm-measuring]) [data-hkm-fill-path] > :is([data-hkm-fill-path], [data-hkm-fill-frame]) {
+    flex: 1 1 auto;
+    block-size: auto;
+    min-block-size: 0;
+  }
+
+  .hkm-showcase :is(.hkm-step-stage, .hkm-mode-stage):not([data-hkm-measuring]) [data-hkm-fill-path] > [data-hkm-fill-frame] > .hkm-window {
+    block-size: 100%;
+  }
+
+  .hkm-showcase :is(.hkm-step-stage, .hkm-mode-stage):not([data-hkm-measuring]) [data-hkm-fill-frame] > .hkm-window:has(> .hkm-page),
+  .hkm-showcase :is(.hkm-step-stage, .hkm-mode-stage):not([data-hkm-measuring]) [data-hkm-fill-path] > [data-hkm-fill-frame] > .hkm-window {
     display: flex;
     flex-direction: column;
   }
 
+  .hkm-showcase :is(.hkm-step-stage, .hkm-mode-stage):not([data-hkm-measuring]) [data-hkm-fill-path] > [data-hkm-fill-frame] > .hkm-window > :last-child:not(.hkm-title-bar, .hkm-browser-bar) {
+    flex: 1 1 auto;
+    min-block-size: 0;
+  }
+
   .hkm-showcase[data-hkm-fit="fill"] :is(.hkm-step-stage, .hkm-mode-stage):not([data-hkm-measuring]) [data-hkm-fill-frame] > .hkm-window > .hkm-page {
     flex: 1 1 auto;
     block-size: auto;
@@ -2605,10 +2631,35 @@
     max-block-size: none;
   }
 
-  .hkm-showcase[data-hkm-fit="fill"] :is(.hkm-step-stage, .hkm-mode-stage):not([data-hkm-measuring]) [data-hkm-fill-frame] > .hkm-window > :is(.hkm-title-bar, .hkm-browser-bar) {
+  .hkm-showcase :is(.hkm-step-stage, .hkm-mode-stage):not([data-hkm-measuring]) [data-hkm-fill-frame] > .hkm-window > :is(.hkm-title-bar, .hkm-browser-bar) {
     flex: none;
   }
 
+  /* The panel draws the frame, so a wrapped window drops its own edge too. */
+  .hkm-showcase :is(.hkm-step-panel, .hkm-mode-surface) [data-hkm-fill-path] > [data-hkm-fill-frame],
+  .hkm-showcase :is(.hkm-step-panel, .hkm-mode-surface) [data-hkm-fill-path] > [data-hkm-fill-frame] > .hkm-window {
+    border: 0;
+    border-radius: 0;
+    box-shadow: none;
+  }
+
+  /* A walkthrough stage is at least as tall as its tallest slide and its step
+   * list, so a selected step never hangs past the preview's edge. Natural
+   * walkthroughs stretch their unscaled slides the same way. */
+  .hkm-showcase.hkm-steps[data-hkm-fit="fill"] .hkm-step-stage:not([data-hkm-measuring]) {
+    block-size: auto;
+    min-block-size: var(--hkm-showcase-fill-height, 0px);
+  }
+
+  .hkm-showcase.hkm-steps:not([data-hkm-fit="fill"]) .hkm-step-stage > .hkm-step-panel {
+    align-self: stretch;
+  }
+
+  .hkm-showcase.hkm-steps:not([data-hkm-fit="fill"]) .hkm-step-panel > .hkm-fit:not(:has(> [data-hkm-scaled])),
+  .hkm-showcase.hkm-steps:not([data-hkm-fit="fill"]) .hkm-step-panel > .hkm-fit > .hkm-fit-inner:not([data-hkm-scaled]) {
+    block-size: 100%;
+  }
+
   /* A walkthrough is one tabbed selector: the steps and the preview share an
    * edge. Compact layouts attach a tab strip to the preview's top edge between
    * Back and Next. Wide layouts stack the steps on its start edge, flush with

package/src/plain-publication.css

@@ -25,7 +25,7 @@
   flex: 1 0 auto;
 }
 
-:where(.plain-site.plain-publication a:not(.hraness-design-skip-link)) {
+:where(.plain-site.plain-publication a:not(.hraness-design-skip-link)):not(:where(.hraness-marketing-account__primary, .hraness-marketing-account__sign-in)) {
   color: var(--plain-link);
   overflow-wrap: anywhere;
   text-decoration: none;
@@ -36,12 +36,12 @@
 :where(
   .plain-site.plain-publication
     a:not(.hraness-design-skip-link):is(:hover, :focus-visible)
-) {
+):not(:where(.hraness-marketing-account__primary, .hraness-marketing-account__sign-in)) {
   text-decoration-line: underline;
   text-decoration-style: dotted;
 }
 
-:where(.plain-site.plain-publication a:not(.hraness-design-skip-link):focus-visible) {
+:where(.plain-site.plain-publication a:not(.hraness-design-skip-link):focus-visible):not(:where(.hraness-marketing-account__primary, .hraness-marketing-account__sign-in)) {
   border-radius: 1px;
   outline: 1px dotted currentColor;
   outline-offset: 3px;
@@ -50,7 +50,7 @@
 :where(
   .plain-site.plain-publication
     a:not(.hraness-design-skip-link):focus:not(:focus-visible)
-) {
+):not(:where(.hraness-marketing-account__primary, .hraness-marketing-account__sign-in)) {
   outline: none;
 }
 
@@ -726,6 +726,7 @@
 }
 
 @media (forced-colors: none) {
+  .plain-site.plain-publication.plain-publication--embedded .plain-publication__byline a:is(:hover, :focus-visible),
   .plain-site.plain-publication.plain-publication--embedded .plain-publication__article-body a:is(:hover, :focus-visible) {
     text-decoration-color: currentColor;
   }

package/src/plain-site.css

@@ -111,7 +111,7 @@
   box-sizing: border-box;
 }
 
-:where(.plain-header a, .plain-page a, .plain-footer a) {
+:where(.plain-header a, .plain-page a, .plain-footer a):not(:where(.hraness-marketing-account__primary, .hraness-marketing-account__sign-in)) {
   color: var(--plain-link);
   overflow-wrap: anywhere;
   text-decoration: none;
@@ -123,7 +123,7 @@
   .plain-header a:is(:hover, :focus-visible),
   .plain-page a:is(:hover, :focus-visible),
   .plain-footer a:is(:hover, :focus-visible)
-) {
+):not(:where(.hraness-marketing-account__primary, .hraness-marketing-account__sign-in)) {
   text-decoration: underline;
 }
 
@@ -131,7 +131,7 @@
   .plain-header a:focus-visible,
   .plain-page a:focus-visible,
   .plain-footer a:focus-visible
-) {
+):not(:where(.hraness-marketing-account__primary, .hraness-marketing-account__sign-in)) {
   border-radius: 1px;
   outline: 1px dotted currentColor;
   outline-offset: 3px;
@@ -141,7 +141,7 @@
   .plain-header a:focus:not(:focus-visible),
   .plain-page a:focus:not(:focus-visible),
   .plain-footer a:focus:not(:focus-visible)
-) {
+):not(:where(.hraness-marketing-account__primary, .hraness-marketing-account__sign-in)) {
   outline: none;
 }
 

package/src/react/design-gallery.tsx

@@ -309,6 +309,16 @@ export function DesignSystemGallery({
             </p>
           </div>
         </div>
+        <div
+          aria-label="Plain site account actions"
+          className="design-gallery__plain-theme plain-site plain-publication"
+        >
+          <div className="plain-page">
+            <MarketingAccount id="plain-account" summary="Keep your preferences across devices.">
+              <MarketingAccountActions primary={{ href: "#plain-account", label: "Create account" }} signIn={{ href: "#plain-account" }} />
+            </MarketingAccount>
+          </div>
+        </div>
       </section>
 
       <section className="design-gallery__section" id="paper-theme">
@@ -468,9 +478,9 @@ export function DesignSystemGallery({
           </MarketingSection>
           <MarketingSection heading="Show the result at each step." headingId="gallery-walkthrough" headingLevel={3} label="Walkthrough" summary="Use short labels and visible explanations beside a compact illustration of what changes.">
             <StepThrough fit="fill" label="Run a Relay job" steps={[
-              { id: "choose", label: "Choose a job", hint: "Pick a saved job and review the file it reads before starting the run.", render: () => <GalleryJobPreview state="ready" /> },
-              { id: "run", label: "Watch the run", hint: "See the input check, transformation, and saved output as separate stages.", render: () => <GalleryJobPreview state="running" /> },
-              { id: "inspect", label: "Read the result", hint: "Open the saved report with the run ID and source file beside it.", render: () => <GalleryJobPreview state="saved" /> },
+              { id: "choose", label: "Choose a job", hint: "Pick a saved job and check the file it reads.", render: () => <GalleryJobPreview state="ready" /> },
+              { id: "run", label: "Watch the run", hint: "The input check, the transform, and the saved output.", render: () => <GalleryJobPreview state="running" /> },
+              { id: "inspect", label: "Read the result", hint: "Open the report beside its run ID and source.", render: () => <GalleryJobPreview state="saved" /> },
             ]} />
           </MarketingSection>
           <MarketingPrimitives

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

@@ -56,7 +56,7 @@ export const marketingAccountStyles = stylex.create({
   },
   signIn: {
     alignItems: "center",
-    color: "var(--foreground)",
+    color: { default: "var(--foreground)", "@media (forced-colors: active)": "LinkText" },
     display: "inline-flex",
     fontFamily: "var(--font-text)",
     fontSize: "1.0625rem",
@@ -67,7 +67,7 @@ export const marketingAccountStyles = stylex.create({
     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" },
+    textDecorationColor: { default: "color-mix(in srgb, currentColor 45%, transparent)", ":hover": "currentColor", ":focus-visible": "currentColor", "@media (forced-colors: active)": "LinkText" },
     textDecorationThickness: "1px",
     textUnderlineOffset: "0.22em",
   },

package/src/testing.ts

@@ -305,3 +305,22 @@ export function assertFakeHandles(html: string, allowedHandles: readonly string[
     if (!RESERVED_HOST.test(match[1] ?? "")) fail(`${label} links to ${match[1] ?? ""}, which is not a reserved example domain.`);
   }
 }
+
+/** Limits from MARKETING_COPY.md for `StepThrough` steps. */
+export const WALKTHROUGH_COPY_LIMITS = Object.freeze({ labelWords: 3, hintCharacters: 60 });
+
+/**
+ * Walkthrough labels name a step in at most three words, and each hint is one
+ * sentence of at most 60 characters, so the wide step list stays no taller
+ * than the illustration it sits beside.
+ */
+export function assertWalkthroughCopy(steps: readonly Readonly<{ id: string; label: string; hint?: string }>[], label = "walkthrough"): void {
+  for (const step of steps) {
+    const words = step.label.trim().split(/\s+/u).filter(Boolean).length;
+    if (words === 0 || words > WALKTHROUGH_COPY_LIMITS.labelWords) fail(`${label} step "${step.id}" label has ${String(words)} words; use one to ${String(WALKTHROUGH_COPY_LIMITS.labelWords)}.`);
+    const hint = step.hint?.trim();
+    if (hint === undefined || hint === "") continue;
+    if (hint.length > WALKTHROUGH_COPY_LIMITS.hintCharacters) fail(`${label} step "${step.id}" hint is ${String(hint.length)} characters; keep it within ${String(WALKTHROUGH_COPY_LIMITS.hintCharacters)}.`);
+    if ((hint.match(/[.!?](\s|$)/gu) ?? []).length > 1) fail(`${label} step "${step.id}" hint has more than one sentence.`);
+  }
+}