@hraness/design-kit 0.39.0 → 0.40.0

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.0",
   "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.0"
     }
   ],
   "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/react/design-gallery.tsx

@@ -468,9 +468,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/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.`);
+  }
+}