@hraness/design-kit 0.35.1 → 0.35.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hraness/design-kit",
-  "version": "0.35.1",
+  "version": "0.35.3",
   "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.35.1"
+      "version": "0.35.3"
     }
   ],
   "contract": "hraness.portfolio-inventory/v1",

package/src/article-html.ts

@@ -83,6 +83,8 @@ export interface ArticleHtmlInput {
   readonly id?: string;
   readonly provenance: ArticleProvenanceRecord | null;
   readonly published: ArticleIsoDate;
+  /** Show publication and update dates. Defaults to true; dates remain required and validated when hidden. */
+  readonly showDates?: boolean;
   readonly toc?: readonly ArticleTocItem[];
   readonly tocLabel?: string;
   readonly updated?: ArticleIsoDate;
@@ -91,7 +93,7 @@ export interface ArticleHtmlInput {
 /** The static equivalent of `MarketingArticle`. */
 export function renderArticleHtml(input: ArticleHtmlInput): string {
   const headingId = input.headingId ?? "article-title";
-  const { published, updated } = input;
+  const { published, updated, showDates = true } = input;
   assertArticleDates(updated === undefined ? { published } : { published, updated });
   const toc = input.toc ?? [];
   for (const item of toc) {
@@ -99,16 +101,16 @@ export function renderArticleHtml(input: ArticleHtmlInput): string {
   }
   const tocId = `${headingId}-contents`;
   const meta = [
-    input.author === undefined ? "" : renderArticleBylineHtml(input.author) + SEPARATOR,
-    dateHtml("Published", published),
-    updated === undefined ? "" : SEPARATOR + dateHtml("Updated", updated),
-  ].join("");
+    input.author === undefined ? "" : renderArticleBylineHtml(input.author),
+    showDates ? dateHtml("Published", published) : "",
+    showDates && updated !== undefined ? dateHtml("Updated", updated) : "",
+  ].filter(Boolean).join(SEPARATOR);
   const header = [
     '<header class="plain-publication__article-header">',
     present(input.eyebrow) ? `<p class="plain-publication__eyebrow">${escapeArticleHtml(input.eyebrow)}</p>` : "",
     `<h1 id="${escapeArticleHtml(headingId)}">${escapeArticleHtml(input.heading)}</h1>`,
     present(input.dek) ? `<p class="plain-publication__article-dek">${escapeArticleHtml(input.dek)}</p>` : "",
-    `<p class="plain-publication__article-meta">${meta}</p>`,
+    meta === "" ? "" : `<p class="plain-publication__article-meta">${meta}</p>`,
     input.provenance === null ? "" : renderArticleProvenanceHtml(input.provenance),
     "</header>",
   ].join("");
@@ -135,21 +137,35 @@ export function renderArticleHtml(input: ArticleHtmlInput): string {
 export function renderArticleSourcesHtml({
   heading = ARTICLE_SOURCES_HEADING,
   headingId = "article-sources",
+  showDates = true,
   sources,
-}: Readonly<{ heading?: string; headingId?: string; sources: readonly ArticleSourceItem[] }>): string {
+}: Readonly<{
+  heading?: string;
+  headingId?: string;
+  /** Show check dates. Defaults to true; checkedOn remains required and validated when hidden. */
+  showDates?: boolean;
+  sources: readonly ArticleSourceItem[];
+}>): string {
   if (sources.length === 0) return "";
-  for (const source of sources) assertArticleHref(source.href);
+  for (const source of sources) {
+    assertArticleHref(source.href);
+    formatArticleDate(source.checkedOn);
+  }
   return [
     `<section aria-labelledby="${escapeArticleHtml(headingId)}" class="plain-publication__sources">`,
     `<h2 id="${escapeArticleHtml(headingId)}">${escapeArticleHtml(heading)}</h2>`,
     "<ol>",
-    ...sources.map((source) => [
-      `<li><a href="${escapeArticleHtml(source.href)}">${escapeArticleHtml(source.title)}</a>`,
-      "<span>",
-      present(source.publisher) ? escapeArticleHtml(source.publisher) + SEPARATOR : "",
-      dateHtml("Checked", source.checkedOn),
-      "</span></li>",
-    ].join("")),
+    ...sources.map((source) => {
+      const meta = [
+        present(source.publisher) ? escapeArticleHtml(source.publisher) : "",
+        showDates ? dateHtml("Checked", source.checkedOn) : "",
+      ].filter(Boolean).join(SEPARATOR);
+      return [
+        `<li><a href="${escapeArticleHtml(source.href)}">${escapeArticleHtml(source.title)}</a>`,
+        meta === "" ? "" : `<span>${meta}</span>`,
+        "</li>",
+      ].join("");
+    }),
     "</ol></section>",
   ].join("");
 }
@@ -228,6 +244,7 @@ export function renderArticleIndexHtml({
   headingLevel = 2,
   id,
   items,
+  showDates = true,
   summary,
 }: Readonly<{
   className?: string;
@@ -236,6 +253,8 @@ export function renderArticleIndexHtml({
   headingLevel?: 1 | 2 | 3 | 4 | 5;
   id?: string;
   items: readonly ArticleIndexItem[];
+  /** Show publication and update dates. Defaults to true; item dates remain required and validated when hidden. */
+  showDates?: boolean;
   summary?: string;
 }>): string {
   if (![1, 2, 3, 4, 5].includes(headingLevel)) throw new RangeError("Article index heading level must be 1 to 5.");
@@ -259,10 +278,13 @@ export function renderArticleIndexHtml({
       present(item.eyebrow) ? `<p class="plain-publication__entry-label">${escapeArticleHtml(item.eyebrow)}</p>` : "",
       `<${entry} class="plain-publication__entry-title"><a href="${escapeArticleHtml(item.href)}">${escapeArticleHtml(item.title)}</a></${entry}>`,
       `<p class="plain-publication__entry-dek">${escapeArticleHtml(item.dek)}</p>`,
-      '<p class="plain-publication__entry-meta">',
-      dateHtml("Published", item.published),
-      item.updated === undefined ? "" : SEPARATOR + dateHtml("Updated", item.updated),
-      "</p></article>",
+      showDates ? [
+        '<p class="plain-publication__entry-meta">',
+        dateHtml("Published", item.published),
+        item.updated === undefined ? "" : SEPARATOR + dateHtml("Updated", item.updated),
+        "</p>",
+      ].join("") : "",
+      "</article>",
     ].join("")),
     "</div></section>",
   ].join("");

package/src/mockups/client.tsx

@@ -229,73 +229,84 @@ export function ModeShowcase<S extends string, M extends string, O extends strin
   return (
     <figure
       aria-label={label?.(surface) ?? `Illustration of ${surface.label.toLowerCase()}`}
-      className={joinMockupClasses("hkm-showcase", className)}
+      className={joinMockupClasses("hkm-showcase", "hkm-modes", className)}
       data-hkm-theme={theme}
       data-nosnippet=""
     >
-      <div className="hkm-showcase-controls">
-        {surfaces.length > 1 ? (
-          <div aria-label="Surface" className="hkm-tabs" role="tablist">
-            {surfaces.map((entry) => (
-              <button
-                aria-controls={`${id}-panel`}
-                aria-selected={entry.id === surface.id}
-                className="hkm-tab"
-                id={`${id}-tab-${entry.id}`}
-                key={entry.id}
-                onClick={() => setSurfaceId(entry.id)}
-                onKeyDown={onTabKey}
-                ref={(element) => {
-                  if (element === null) tabs.current.delete(entry.id);
-                  else tabs.current.set(entry.id, element);
-                }}
-                role="tab"
-                tabIndex={entry.id === surface.id ? 0 : -1}
-                type="button"
-              >
-                {entry.label}
-              </button>
-            ))}
-          </div>
-        ) : null}
-        <div className="hkm-showcase-settings">
-          <div className="hkm-showcase-row">
-            <span className="hkm-showcase-label" id={`${id}-mode`}>{modeLabel}</span>
-            <div aria-labelledby={`${id}-mode`} className="hkm-segmented" role="group">
-              {modes.map((entry) => (
-                <button aria-pressed={entry.id === mode} key={entry.id} onClick={() => chooseMode(entry.id)} type="button">
-                  {entry.label}
-                </button>
-              ))}
-            </div>
-          </div>
-          {options === undefined ? null : (
-            <div className="hkm-showcase-row">
-              <span className="hkm-showcase-label" id={`${id}-option`}>{optionLabel}</span>
-              <div aria-labelledby={`${id}-option`} className="hkm-segmented" role="group">
-                {options.map((entry) => (
-                  <button aria-pressed={entry.id === option} disabled={optionInactive} key={entry.id} onClick={() => chooseOption(entry.id)} type="button">
-                    {entry.label}
-                  </button>
-                ))}
-              </div>
-            </div>
-          )}
+      {surfaces.length > 1 ? (
+        <div aria-label="Surface" className="hkm-tabs hkm-folder-tabs" role="tablist">
+          {surfaces.map((entry) => (
+            <button
+              aria-controls={`${id}-panel`}
+              aria-selected={entry.id === surface.id}
+              className="hkm-tab"
+              id={`${id}-tab-${entry.id}`}
+              key={entry.id}
+              onClick={() => setSurfaceId(entry.id)}
+              onKeyDown={onTabKey}
+              ref={(element) => {
+                if (element === null) tabs.current.delete(entry.id);
+                else tabs.current.set(entry.id, element);
+              }}
+              role="tab"
+              tabIndex={entry.id === surface.id ? 0 : -1}
+              type="button"
+            >
+              {entry.label}
+            </button>
+          ))}
         </div>
-        {hint === "" ? null : <p className="hkm-showcase-hint">{hint}</p>}
-      </div>
+      ) : null}
       <div
         aria-labelledby={surfaces.length > 1 ? `${id}-tab-${surface.id}` : undefined}
-        className="hkm-showcase-stage"
-        data-hkm-animated={animated ? "" : undefined}
-        data-hkm-from={animated ? previousMode : undefined}
+        className="hkm-showcase-stage hkm-mode-panel"
         id={`${id}-panel`}
         role={surfaces.length > 1 ? "tabpanel" : undefined}
         style={{ "--hkm-page-height": `${height}px` } as CSSProperties}
       >
-        <FitToWidth minWidth={minWidth}>
-          {surface.render({ animated, mode, option, previousMode, theme })}
-        </FitToWidth>
+        <div className="hkm-showcase-controls">
+          <div className="hkm-showcase-settings">
+            <div className="hkm-showcase-row">
+              <span className="hkm-showcase-label" id={`${id}-mode`}>{modeLabel}</span>
+              <div aria-labelledby={`${id}-mode`} className="hkm-segmented" role="group">
+                {modes.map((entry) => (
+                  <button aria-pressed={entry.id === mode} key={entry.id} onClick={() => chooseMode(entry.id)} type="button">
+                    {entry.label}
+                  </button>
+                ))}
+              </div>
+            </div>
+            {options === undefined ? null : (
+              <div className="hkm-showcase-row">
+                <span className="hkm-showcase-label" id={`${id}-option`}>{optionLabel}</span>
+                <div aria-labelledby={`${id}-option`} className="hkm-segmented" role="group">
+                  {options.map((entry) => (
+                    <button aria-pressed={entry.id === option} disabled={optionInactive} key={entry.id} onClick={() => chooseOption(entry.id)} type="button">
+                      {entry.label}
+                    </button>
+                  ))}
+                </div>
+              </div>
+            )}
+          </div>
+          {hint === "" ? null : <p className="hkm-showcase-hint">{hint}</p>}
+        </div>
+        <div className="hkm-mode-stage">
+          {surfaces.map((entry) => (
+            <div
+              aria-hidden={entry.id !== surface.id}
+              className="hkm-mode-surface"
+              data-hkm-animated={entry.id === surface.id && animated ? "" : undefined}
+              data-hkm-from={entry.id === surface.id && animated ? previousMode : undefined}
+              inert={entry.id !== surface.id}
+              key={entry.id}
+            >
+              <FitToWidth minWidth={minWidth}>
+                {entry.render({ animated: entry.id === surface.id && animated, mode, option, previousMode, theme })}
+              </FitToWidth>
+            </div>
+          ))}
+        </div>
       </div>
       {!hasStatus && captionText === undefined ? null : (
         <figcaption className="hkm-showcase-caption">
@@ -367,7 +378,7 @@ export function StepThrough({
   return (
     <figure aria-label={`Illustration: ${label.toLowerCase()}`} className={joinMockupClasses("hkm-showcase", "hkm-steps", className)} data-hkm-theme={theme} data-nosnippet="">
       <div className="hkm-showcase-controls">
-        <div aria-label={label} className="hkm-tabs hkm-step-tabs" role="tablist">
+        <div aria-label={label} className="hkm-tabs hkm-folder-tabs hkm-step-tabs" role="tablist">
           {steps.map((entry, position) => (
             <button
               aria-controls={`${id}-panel-${entry.id}`}

package/src/mockups.css

@@ -2503,14 +2503,22 @@
     }
   }
 
-  /* Folder tabs share an edge with the stable-height walkthrough stage. */
-  .hkm-showcase.hkm-steps { gap: 0; }
+  /* Folder tabs share an edge with each showcase panel. */
+  .hkm-showcase:is(.hkm-steps, .hkm-modes) { gap: 0; }
   .hkm-showcase.hkm-steps .hkm-showcase-controls { padding: 0; border: 0; border-radius: 0; background: transparent; }
-  .hkm-showcase.hkm-steps .hkm-step-tabs { gap: 6px; margin: 0; padding: 0; border: 0; position: relative; z-index: 1; }
-  .hkm-showcase.hkm-steps .hkm-tab { min-block-size: 48px; padding: 12px 18px; border: 1px solid var(--hkm-sc-line); border-block-end: 0; border-radius: 12px 12px 0 0; background: var(--hkm-sc-field); color: var(--hkm-sc-muted); }
-  .hkm-showcase.hkm-steps .hkm-tab[aria-selected="true"] { background: var(--hkm-sc-bg); color: var(--hkm-sc-fg); }
-  .hkm-showcase.hkm-steps .hkm-tab:hover { color: var(--hkm-sc-fg); }
+  .hkm-showcase .hkm-folder-tabs { gap: 6px; margin: 0; padding: 0; border: 0; position: relative; z-index: 1; }
+  .hkm-showcase .hkm-folder-tabs .hkm-tab { min-block-size: 48px; padding: 12px 18px; border: 1px solid var(--hkm-sc-line); border-block-end: 0; border-radius: 12px 12px 0 0; background: var(--hkm-sc-field); color: var(--hkm-sc-muted); }
+  .hkm-showcase .hkm-folder-tabs .hkm-tab[aria-selected="true"] { background: var(--hkm-sc-bg); color: var(--hkm-sc-fg); }
+  .hkm-showcase .hkm-folder-tabs .hkm-tab:hover { color: var(--hkm-sc-fg); }
   .hkm-showcase.hkm-steps .hkm-step-stage { display: grid; border: 1px solid var(--hkm-sc-line); border-radius: 0 12px 12px 12px; background: var(--hkm-sc-bg); margin-block-start: -1px; overflow: clip; }
+  .hkm-showcase.hkm-modes .hkm-mode-panel { border: 1px solid var(--hkm-sc-line); border-radius: 12px; background: var(--hkm-sc-bg); overflow: clip; }
+  .hkm-showcase.hkm-modes .hkm-folder-tabs + .hkm-mode-panel { border-start-start-radius: 0; margin-block-start: -1px; }
+  .hkm-showcase.hkm-modes .hkm-showcase-controls { border: 0; border-block-end: 1px solid var(--hkm-sc-line); border-radius: 0; }
+  .hkm-mode-stage { display: grid; min-inline-size: 0; }
+  .hkm-mode-surface { grid-area: 1 / 1; min-inline-size: 0; align-self: start; }
+  .hkm-mode-surface[aria-hidden="true"] { visibility: hidden; pointer-events: none; }
+  .hkm-showcase.hkm-modes .hkm-mode-surface > .hkm-fit > .hkm-fit-inner > .hkm-root,
+  .hkm-showcase.hkm-modes .hkm-mode-surface > .hkm-fit > .hkm-fit-inner > .hkm-root > .hkm-window { border: 0; border-radius: 0; box-shadow: none; }
   .hkm-step-panel { grid-area: 1 / 1; min-inline-size: 0; align-self: start; }
   .hkm-step-panel[aria-hidden="true"] { visibility: hidden; pointer-events: none; }
   .hkm-showcase.hkm-steps .hkm-step-panel .hkm-root { border-start-start-radius: 0; border-start-end-radius: 0; box-shadow: none; }
@@ -2520,7 +2528,7 @@
   .hkm-showcase.hkm-steps .hkm-step-button:disabled { color: var(--hkm-sc-muted); background: transparent; }
   .hkm-showcase.hkm-steps .hkm-step-button[data-hkm-primary]:disabled { background: var(--hkm-sc-field); }
   .hkm-showcase.hkm-steps .hkm-step-announcement { position: absolute; inline-size: 1px; block-size: 1px; overflow: hidden; clip-path: inset(50%); white-space: nowrap; }
-  .hkm-showcase.hkm-steps .hkm-showcase-caption { margin-block-start: 1rem; }
+  .hkm-showcase:is(.hkm-steps, .hkm-modes) .hkm-showcase-caption { margin-block-start: 1rem; }
 
   /* ---------------------------------------------------------------- */
   /* Motion                                                           */

package/src/react/article.tsx

@@ -93,6 +93,8 @@ export interface MarketingArticleProps {
   /** Required so every article decides its drafting note. Pass null only for writing with no AI involvement and no review record. */
   readonly provenance: ArticleProvenanceRecord | null;
   readonly published: ArticleIsoDate;
+  /** Show publication and update dates. Defaults to true; dates remain required and validated when hidden. */
+  readonly showDates?: boolean;
   readonly toc?: readonly ArticleTocItem[];
   readonly tocLabel?: string;
   readonly updated?: ArticleIsoDate;
@@ -116,6 +118,7 @@ export function MarketingArticle({
   id,
   provenance,
   published,
+  showDates = true,
   toc,
   tocLabel = ARTICLE_TOC_LABEL,
   updated,
@@ -138,11 +141,13 @@ export function MarketingArticle({
         {eyebrow === undefined || eyebrow === "" ? null : <p className="plain-publication__eyebrow">{eyebrow}</p>}
         <h1 id={headingId}>{heading}</h1>
         {dek === undefined || dek === "" ? null : <p className="plain-publication__article-dek">{dek}</p>}
-        <p className="plain-publication__article-meta">
-          {author === undefined ? null : <><ArticleByline author={author} /><Separator /></>}
-          <ArticleDate label="Published" value={published} />
-          {updated === undefined ? null : <><Separator /><ArticleDate label="Updated" value={updated} /></>}
-        </p>
+        {author === undefined && !showDates ? null : (
+          <p className="plain-publication__article-meta">
+            {author === undefined ? null : <><ArticleByline author={author} />{showDates ? <Separator /> : null}</>}
+            {showDates ? <ArticleDate label="Published" value={published} /> : null}
+            {!showDates || updated === undefined ? null : <><Separator /><ArticleDate label="Updated" value={updated} /></>}
+          </p>
+        )}
         {provenance === null ? null : <ArticleProvenance provenance={provenance} />}
       </header>
       <div className="plain-publication__article-layout">
@@ -165,14 +170,20 @@ export function MarketingArticle({
 export function ArticleSources({
   heading = ARTICLE_SOURCES_HEADING,
   headingId = "article-sources",
+  showDates = true,
   sources,
 }: Readonly<{
   heading?: string;
   headingId?: string;
+  /** Show check dates. Defaults to true; checkedOn remains required and validated when hidden. */
+  showDates?: boolean;
   sources: readonly ArticleSourceItem[];
 }>) {
   if (sources.length === 0) return null;
-  for (const source of sources) assertArticleHref(source.href);
+  for (const source of sources) {
+    assertArticleHref(source.href);
+    formatArticleDate(source.checkedOn);
+  }
   return (
     <section aria-labelledby={headingId} className="plain-publication__sources">
       <h2 id={headingId}>{heading}</h2>
@@ -180,10 +191,12 @@ export function ArticleSources({
         {sources.map((source) => (
           <li key={`${source.href}-${source.title}`}>
             <a href={source.href}>{source.title}</a>
-            <span>
-              {source.publisher === undefined || source.publisher === "" ? null : <>{source.publisher}<Separator /></>}
-              <ArticleDate label="Checked" value={source.checkedOn} />
-            </span>
+            {!showDates && (source.publisher === undefined || source.publisher === "") ? null : (
+              <span>
+                {source.publisher === undefined || source.publisher === "" ? null : <>{source.publisher}{showDates ? <Separator /> : null}</>}
+                {showDates ? <ArticleDate label="Checked" value={source.checkedOn} /> : null}
+              </span>
+            )}
           </li>
         ))}
       </ol>
@@ -253,6 +266,7 @@ export function ArticleIndex({
   headingLevel = 2,
   id,
   items,
+  showDates = true,
   summary,
 }: Readonly<{
   className?: string;
@@ -261,6 +275,8 @@ export function ArticleIndex({
   headingLevel?: 1 | 2 | 3 | 4 | 5;
   id?: string;
   items: readonly ArticleIndexItem[];
+  /** Show publication and update dates. Defaults to true; item dates remain required and validated when hidden. */
+  showDates?: boolean;
   summary?: string;
 }>) {
   if (![1, 2, 3, 4, 5].includes(headingLevel)) throw new RangeError("Article index heading level must be 1 to 5.");
@@ -290,10 +306,12 @@ export function ArticleIndex({
             {item.eyebrow === undefined || item.eyebrow === "" ? null : <p className="plain-publication__entry-label">{item.eyebrow}</p>}
             <EntryTag className="plain-publication__entry-title"><a href={item.href}>{item.title}</a></EntryTag>
             <p className="plain-publication__entry-dek">{item.dek}</p>
-            <p className="plain-publication__entry-meta">
-              <ArticleDate label="Published" value={item.published} />
-              {item.updated === undefined ? null : <><Separator /><ArticleDate label="Updated" value={item.updated} /></>}
-            </p>
+            {showDates ? (
+              <p className="plain-publication__entry-meta">
+                <ArticleDate label="Published" value={item.published} />
+                {item.updated === undefined ? null : <><Separator /><ArticleDate label="Updated" value={item.updated} /></>}
+              </p>
+            ) : null}
           </article>
         ))}
       </div>

package/src/react/design-gallery.tsx

@@ -678,6 +678,7 @@ export function DesignSystemGallery({
           after={(
             <ArticleSources
               headingId="gallery-article-sources"
+              showDates={false}
               sources={[
                 { checkedOn: "2026-09-20", href: "#articles", publisher: "Relay", title: "Relay 2.4 release notes" },
               ]}
@@ -693,6 +694,7 @@ export function DesignSystemGallery({
             review: { reviewer: "an independent AI editorial review", reviewerType: "ai" },
           }}
           published="2026-09-10"
+          showDates={false}
           toc={[
             { href: "#gallery-article-problem", label: "The problem" },
             { href: "#gallery-article-approach", label: "The approach" },