@ultimat3/ui 24.0.0 → 25.0.0

package/src/catalog/build-catalog.ts

@@ -5,8 +5,8 @@ import type { ComponentDoc } from './parse-component';
 import { parseComponents } from './parse-component';
 import { renderCatalog } from './render-catalog';
 
-const COMPONENTS_DIR = new URL('../components/', import.meta.url).pathname;
-export const CATALOG_PATH = new URL('../../CATALOG.md', import.meta.url).pathname;
+const COMPONENTS_DIR = Bun.fileURLToPath(new URL('../components/', import.meta.url));
+export const CATALOG_PATH = Bun.fileURLToPath(new URL('../../CATALOG.md', import.meta.url));
 
 /** Alphabetical by file, so the page's order is the order an agent scans for a name. */
 export async function collectComponents(): Promise<ComponentDoc[]> {

package/src/components/Accordion.tsx

@@ -11,6 +11,7 @@ import type { AccordionSection } from './accordion-view';
 import { accordionOpenIds } from './accordion-view';
 import type { HeadingLevel } from './heading-level';
 import { headingTag } from './heading-level';
+import { headingNode } from './heading-node';
 import { Icon } from './Icon';
 
 export interface AccordionItem extends AccordionSection {
@@ -39,7 +40,8 @@ export interface AccordionProps {
 export function Accordion(props: AccordionProps): JSX.Element {
   const base = useId('accordion');
   const open = accordionOpenIds(props.items, props.exclusive === true);
-  const Title = props.level === undefined ? 'span' : headingTag(props.level);
+  // Resolved once, so an off-scale level throws `X_UI_INVALID_VALUE` here as it always did.
+  const heading = props.level === undefined ? undefined : headingTag(props.level);
 
   return (
     <div class={cx(styles['accordion'], props.class)}>
@@ -53,7 +55,11 @@ export function Accordion(props: AccordionProps): JSX.Element {
         >
           <summary class={styles['summary']}>
             <Icon glyph={iconChevronDown} class={styles['marker']} size="sm" />
-            <Title class={styles['title']}>{item.title}</Title>
+            {heading === undefined ? (
+              <span class={styles['title']}>{item.title}</span>
+            ) : (
+              headingNode(heading, { class: styles['title'] }, () => item.title)
+            )}
           </summary>
           <div class={styles['panel']}>{item.panel}</div>
         </details>

package/src/components/AppShell.module.scss

@@ -4,6 +4,9 @@
 // writing mode is handled by the grid itself, so RTL needs no second rule.
 .shell {
   display: grid;
+  // `minmax(0, …)`, never the implicit `auto`: an auto track is at least its content's min-content
+  // width, so a header that did not shrink laid a 390px phone out 429px wide.
+  grid-template-columns: minmax(0, 1fr);
   grid-template-areas: 'header' 'sidebar' 'main' 'footer';
   grid-template-rows: auto auto 1fr auto;
   min-block-size: 100dvh;
@@ -51,13 +54,66 @@
   }
 }
 
+// The bar the banner sits in: the menu button (below `md`) and the app's header, side by side.
+.top {
+  display: flex;
+  min-inline-size: 0;
+  align-items: center;
+  gap: t.space(2);
+  grid-area: header;
+  padding-inline-start: t.space(2);
+  border-block-end: 1px solid t.role('line');
+  background: t.role('surface');
+
+  @include t.respond-to(md) {
+    padding-inline-start: 0;
+  }
+}
+
+.menuOnly {
+  display: none;
+}
+
 .header {
   @include t.row(t.space(4), center, space-between);
-  grid-area: header;
+  flex: 1;
+  min-inline-size: 0;
   padding-block: t.space(3);
   padding-inline: t.space(4);
-  border-block-end: 1px solid t.role('line');
-  background: t.role('surface');
+}
+
+// Hidden unless the engine can open the panel it names: a button that does nothing is worse than
+// the band an engine without popovers still shows. A touch target: this bar exists for a phone.
+.menuButton,
+.close {
+  @include t.focus-ring;
+  @include t.touch-target;
+  display: none;
+  align-items: center;
+  justify-content: center;
+  gap: t.space(2);
+  padding-inline: t.space(3);
+  border: 0;
+  border-radius: t.radius(md);
+  background: none;
+  color: t.role('fg-strong');
+  font: inherit;
+  cursor: pointer;
+
+  &:hover {
+    background: t.role('bg-soft');
+  }
+}
+
+.close {
+  margin-inline-start: auto;
+}
+
+// On a phone the menu button is its icon; the label stays in the accessibility tree as its name.
+.menuLabel {
+  @include t.respond-down(sm) {
+    @include t.visually-hidden;
+  }
 }
 
 .sticky {
@@ -66,13 +122,23 @@
   inset-block-start: 0;
 }
 
-// Below `md` the sidebar is a band above the content; from `md` it is the inline-start column.
+// From `md` the sidebar is the inline-start column; below it, the popover panel further down.
+// Every `[popover]` gets a UA style — fixed, centred, bordered, hidden while closed — so the
+// in-flow box undoes each, and is what an engine without popovers shows at every width.
 .sidebar {
   @include t.custom-scrollbar;
+  display: block;
+  position: static;
+  inset: auto;
+  inline-size: auto;
+  block-size: auto;
+  margin: 0;
   grid-area: sidebar;
   padding: t.space(4);
+  border: 0;
   border-block-end: 1px solid t.role('line');
   background: t.role('bg-soft');
+  color: t.role('fg');
   overflow: auto;
 
   // Deliberately not sticky: a sticky sidebar and a sticky header both anchored at 0 overlap,
@@ -108,3 +174,38 @@
   color: t.role('fg-muted');
   font-size: t.text(sm);
 }
+
+// --- Below `md`, where the engine has popovers: the sidebar is an edge panel ----------------------
+// The same look as `Drawer`'s inline-start side — raised surface, line edge, scrim — so the two
+// off-canvas surfaces in an app read as one.
+@include t.respond-down(md) {
+  @supports selector(:popover-open) {
+    .sidebar:not(:popover-open) {
+      display: none;
+    }
+
+    .sidebar:popover-open {
+      @include t.scrim-backdrop;
+      position: fixed;
+      inset-block: 0;
+      inset-inline-start: 0;
+      inset-inline-end: auto;
+      inline-size: min(var(--shell-sidebar, 16rem), calc(100vw - #{t.space(12)}));
+      block-size: 100dvh;
+      max-block-size: 100dvh;
+      border-block-end: 0;
+      border-inline-end: 1px solid t.role('line');
+      background: t.role('surface-raised');
+      box-shadow: t.shadow(xl);
+    }
+
+    .menuButton,
+    .close {
+      display: inline-flex;
+    }
+
+    .menuOnly {
+      display: flex;
+    }
+  }
+}

package/src/components/AppShell.tsx

@@ -1,28 +1,35 @@
 // The page frame every app screen sits in: skip link, banner, navigation, main, contentinfo.
-// Stateless on purpose — below `md` the sidebar becomes a band above the content instead of
-// growing an open/closed flag, because an off-canvas menu is already `Drawer` and axiom 1 allows
-// exactly one of those.
+// Stateless, and scriptless: below `md` the sidebar `<nav>` is a native `popover` panel at the
+// inline-start edge, opened by a `popovertarget` menu button — the browser holds the open state,
+// Esc and light dismiss, so the frame on every page costs no island. Not `Drawer`: that is a modal
+// `<dialog>` opened from an effect, so it needs a hydrated island, and a `<dialog>` cannot also be
+// the in-flow `navigation` landmark at `md` and up. An engine with no popovers keeps the old band.
 
 import type { JSX } from 'solid-js';
 import { LIVE_REGION_LEVELS, liveRegionAttrs, useId } from '../a11y';
 import { cx } from '../cx';
 import { UI_KEYS } from '../i18n-keys';
+import { iconMenu } from '../icons/glyphs/menu';
+import { iconX } from '../icons/glyphs/x';
 import { useUi } from '../theme/context';
 import styles from './AppShell.module.scss';
 import { shellIds } from './app-shell-view';
+import { Icon } from './Icon';
 
 export interface AppShellProps {
   /** The page. Rendered inside the one `<main>`, which is the skip link's target. */
   children: JSX.Element;
   header?: JSX.Element | undefined;
-  /** Rendered inside a `<nav>` landmark at the inline start. */
+  /** Rendered inside a `<nav>` landmark: the inline-start column at `md` and up, a panel below. */
   sidebar?: JSX.Element | undefined;
   footer?: JSX.Element | undefined;
   /** Accessible name for the sidebar landmark. Defaults to the translated `ui.navigation`. */
   sidebarLabel?: string | undefined;
   /** Skip-link text. Defaults to the translated `ui.skip`. */
   skipLabel?: string | undefined;
-  /** Sidebar track width at `md` and up. Any CSS length. */
+  /** The menu button's text below `md`. Defaults to the translated `ui.menu`. */
+  menuLabel?: string | undefined;
+  /** Sidebar track width at `md` and up, and the panel's width below. Any CSS length. */
   sidebarWidth?: string | undefined;
   /** Keeps the header pinned while the main region scrolls. */
   stickyHeader?: boolean | undefined;
@@ -41,13 +48,44 @@ export function AppShell(props: AppShellProps): JSX.Element {
       <a class={styles['skip']} href={ids.skipHref}>
         {props.skipLabel ?? ui.t(UI_KEYS.skip)}
       </a>
-      {props.header === undefined ? null : (
-        <header class={cx(styles['header'], props.stickyHeader !== false && styles['sticky'])}>
-          {props.header}
-        </header>
+      {props.header === undefined && props.sidebar === undefined ? null : (
+        // The menu button sits beside the banner, not inside it: the header holds exactly what
+        // the app handed it, and the bar is what sticks.
+        <div
+          class={cx(
+            styles['top'],
+            // A bar holding only the menu button is shown only where that button is.
+            props.header === undefined && styles['menuOnly'],
+            props.stickyHeader !== false && styles['sticky'],
+          )}
+        >
+          {props.sidebar === undefined ? null : (
+            <button type="button" class={styles['menuButton']} popovertarget={ids.navId}>
+              <Icon glyph={iconMenu} size="md" />
+              <span class={styles['menuLabel']}>{props.menuLabel ?? ui.t(UI_KEYS.menu)}</span>
+            </button>
+          )}
+          {props.header === undefined ? null : (
+            <header class={styles['header']}>{props.header}</header>
+          )}
+        </div>
       )}
       {props.sidebar === undefined ? null : (
-        <nav class={styles['sidebar']} aria-label={props.sidebarLabel ?? ui.t(UI_KEYS.navigation)}>
+        <nav
+          id={ids.navId}
+          class={styles['sidebar']}
+          popover="auto"
+          aria-label={props.sidebarLabel ?? ui.t(UI_KEYS.navigation)}
+        >
+          <button
+            type="button"
+            class={styles['close']}
+            popovertarget={ids.navId}
+            popovertargetaction="hide"
+            aria-label={ui.t(UI_KEYS.close)}
+          >
+            <Icon glyph={iconX} size="md" />
+          </button>
           {props.sidebar}
         </nav>
       )}

package/src/components/BarChart.module.scss

@@ -1,6 +1,18 @@
 @use '../tokens' as t;
 
 .chart {
+  display: grid;
+  gap: t.space(1);
+  inline-size: 100%;
+  // The svg does not mirror in a right-to-left page; the keyboard layer over it must not either.
+  direction: ltr;
+}
+
+.box {
+  position: relative;
+}
+
+.plot {
   display: block;
   inline-size: 100%;
   block-size: auto;
@@ -26,10 +38,15 @@
   }
 }
 
-// The second series — what went wrong, stacked on what went right.
+// The second series — what went wrong, stacked on what went right. Its dashed outline is the cue
+// that does not depend on telling red from blue; the legend's swatch carries the same edge.
 .secondary {
   fill: t.role('danger');
   opacity: 0.6;
+  stroke: t.role('fg-strong');
+  stroke-width: 1;
+  stroke-dasharray: 3 2;
+  vector-effect: non-scaling-stroke;
   transition: opacity t.duration(fast) t.easing(out);
 
   &:hover {
@@ -44,13 +61,34 @@
 .axis {
   @include t.data-text;
 
-  // SVG text scales with the chart: below `sm` these shrink to unreadable specks, and an
-  // unreadable label is noise. Every bar still carries its `<title>`.
-  display: none;
-  font-size: t.rem(8px);
-  fill: t.role('fg-muted');
+  // HTML text, outside the viewBox: it keeps this step at every chart width (issue 494).
+  font-size: t.text(xs);
+  line-height: t.leading(tight);
+  color: t.role('fg-muted');
+}
+
+// The busiest value, over the top grid line's end.
+.max {
+  justify-self: end;
+}
 
-  @include t.respond-to(sm) {
-    display: block;
-  }
+// The first and last keys, under the first and last bars.
+.keys {
+  display: flex;
+  justify-content: space-between;
+  gap: t.space(2);
+}
+
+// Legend keys: the bar's own fill, and the second series' fill with its dashed edge.
+.swatch {
+  display: block;
+  inline-size: t.space(3);
+  block-size: t.space(3);
+  border-radius: t.radius(sm);
+  background: t.role('accent');
+}
+
+.swatchSecondary {
+  border: t.stroke(hairline) dashed t.role('fg-strong');
+  background: t.role('danger', 0.6);
 }

package/src/components/BarChart.tsx

@@ -1,14 +1,20 @@
 // A bar chart of one series — clicks per day, signups per week — or two stacked (done, and failed
-// on top), as static SVG. No charting
-// library: the framework's own docs use a sparkline pulling one in as the cautionary example, and
-// a route's JS budget counts raw minified bytes. `<rect>` bars cost nothing to hydrate, so the
-// server-rendered shell IS the chart. Geometry lives in `bar-chart-view.ts`.
+// on top): SVG bars, HTML axis labels. No charting library: the framework's own docs use a
+// sparkline pulling one in as the cautionary example, and a route's JS budget counts raw minified
+// bytes. `<rect>` bars cost nothing to hydrate, so the server-rendered shell IS the chart. The
+// labels sit outside the svg because text inside a viewBox scales with it — a speck at phone width.
+// It stands in a `ChartFrame`: a legend for two series, and a hidden table of the same numbers.
 
 import type { JSX } from 'solid-js';
 import { cx } from '../cx';
+import { useUi } from '../theme/context';
 import styles from './BarChart.module.scss';
 import type { ChartPoint } from './bar-chart-view';
 import { BAR_CHART, barRects, GRID_STEPS, gridY, maxOf, secondaryRects } from './bar-chart-view';
+import type { ChartHit, ChartLegendItem } from './ChartFrame';
+import { ChartFrame, chartHits } from './ChartFrame';
+import type { ChartSeries } from './chart-frame-view';
+import { chartNumberFormat, chartTable, cssPercent, hitEdge, pointLabel } from './chart-frame-view';
 
 export interface BarChartProps {
   /** The accessible name for the whole chart, already translated. */
@@ -18,87 +24,161 @@ export interface BarChartProps {
   /** Draw the last bar at full strength — the eye lands where the live number is. Default on. */
   highlightLast?: boolean | undefined;
   /**
-   * Names of the two series, already translated, read by each rect's `<title>`. Give them when a
-   * point carries `secondary`: a stacked bar with no name for its top is two numbers and no key.
+   * Names of the two series, already translated, read by each rect's `<title>`, the legend and
+   * the data table. Give them when a point carries `secondary`: a stacked bar with no name for its
+   * top is two numbers and no key.
    */
   seriesLabels?: { readonly primary: string; readonly secondary: string } | undefined;
+  /** The key column's head in the data table, already translated — "Day". */
+  keyLabel?: string | undefined;
+  /** Formats every value. Default: `Intl.NumberFormat` in the page's locale. */
+  format?: ((value: number) => string) | undefined;
+  /** Give every bar a tab stop and a hover/focus readout. Default off: no tab stops. */
+  focusable?: boolean | undefined;
+  /** Show the caption above the plot. Default off — it names the figure either way. */
+  showCaption?: boolean | undefined;
+  /** Lands on the root `<figure>`, which holds the svg and its HTML axis labels. */
   class?: string | undefined;
 }
 
 export function BarChart(props: BarChartProps): JSX.Element {
+  const ui = useUi();
+  const format = (value: number): string => (props.format ?? chartNumberFormat(ui.locale))(value);
   const rects = (): readonly ReturnType<typeof barRects>[number][] => barRects(props.points);
   const tops = (): ReturnType<typeof secondaryRects> => secondaryRects(props.points);
   const named = (label: string | undefined, value: number): string =>
-    label === undefined ? String(value) : `${label} ${value}`;
+    label === undefined ? format(value) : `${label} ${format(value)}`;
   const lastIndex = (): number => props.points.length - 1;
-  const first = (): ChartPoint | undefined => props.points[0];
-  const last = (): ChartPoint | undefined => props.points.at(-1);
   const highlight = (): boolean => props.highlightLast !== false;
+  const stacked = (): boolean => props.points.some((point) => (point.secondary ?? 0) > 0);
+
+  const series = (): readonly ChartSeries[] => [
+    { label: props.seriesLabels?.primary ?? props.label, values: props.points.map((p) => p.value) },
+    ...(props.seriesLabels !== undefined || stacked()
+      ? [
+          {
+            label: props.seriesLabels?.secondary ?? '',
+            values: props.points.map((p) => p.secondary ?? 0),
+          },
+        ]
+      : []),
+  ];
+
+  const legend = (): readonly ChartLegendItem[] | undefined =>
+    props.seriesLabels === undefined
+      ? undefined
+      : [
+          { label: props.seriesLabels.primary, swatch: <span class={styles['swatch']} /> },
+          {
+            label: props.seriesLabels.secondary,
+            swatch: <span class={cx(styles['swatch'], styles['swatchSecondary'])} />,
+          },
+        ];
+
+  const hits = (): readonly ChartHit[] =>
+    props.points.flatMap((point, index) => {
+      const rect = rects()[index];
+      if (rect === undefined) return [];
+      const top = tops()[index] ?? null;
+      const x = rect.x + rect.width / 2;
+      const own = (y: number, label: string | undefined, value: number): ChartHit => ({
+        x: cssPercent(x, BAR_CHART.width),
+        y: cssPercent(y, BAR_CHART.height),
+        label: pointLabel(point.key, label, format(value)),
+        edge: hitEdge(x, BAR_CHART.width),
+      });
+      const first = own(rect.y, props.seriesLabels?.primary, point.value);
+      return top === null
+        ? [first]
+        : [first, own(top.y, props.seriesLabels?.secondary, point.secondary ?? 0)];
+    });
+
   return (
-    <svg
-      role="img"
-      aria-label={props.label}
-      viewBox={`0 0 ${BAR_CHART.width} ${BAR_CHART.height}`}
-      class={cx(styles['chart'], props.class)}
+    <ChartFrame
+      label={props.label}
+      showCaption={props.showCaption}
+      class={props.class}
+      legend={legend()}
+      table={chartTable({
+        caption: props.label,
+        keyLabel: props.keyLabel,
+        keys: props.points.map((point) => point.key),
+        series: series(),
+        format,
+      })}
     >
-      {GRID_STEPS.map((step) => (
-        <line
-          class={styles['grid']}
-          x1={0}
-          x2={BAR_CHART.width}
-          y1={gridY(step)}
-          y2={gridY(step)}
-        />
-      ))}
-      {props.points.map((point, index) => {
-        const rect = rects()[index];
-        if (rect === undefined) return null;
-        const top = tops()[index] ?? null;
-        return (
-          <g>
-            <rect
-              class={cx(styles['bar'], highlight() && index === lastIndex() && styles['last'])}
-              x={rect.x}
-              y={rect.y}
-              width={rect.width}
-              height={rect.height}
-              rx={2}
-              data-bar="true"
-            >
-              <title>{`${point.key}: ${named(props.seriesLabels?.primary, point.value)}`}</title>
-            </rect>
-            {top === null ? null : (
-              <rect
-                class={cx(
-                  styles['secondary'],
-                  highlight() && index === lastIndex() && styles['last'],
-                )}
-                x={top.x}
-                y={top.y}
-                width={top.width}
-                height={top.height}
-                rx={2}
-                data-series="secondary"
-              >
-                <title>{`${point.key}: ${named(props.seriesLabels?.secondary, point.secondary ?? 0)}`}</title>
-              </rect>
+      <div class={styles['chart']}>
+        {/* aria-hidden: the svg is the image and names itself; a bare "9" read aloud is noise. */}
+        <span class={cx(styles['axis'], styles['max'])} data-axis="max" aria-hidden="true">
+          {format(maxOf(props.points))}
+        </span>
+        <div class={styles['box']}>
+          <svg
+            role="img"
+            aria-label={props.label}
+            viewBox={`0 0 ${BAR_CHART.width} ${BAR_CHART.height}`}
+            class={styles['plot']}
+          >
+            {GRID_STEPS.map((step) => (
+              <line
+                class={styles['grid']}
+                x1={0}
+                x2={BAR_CHART.width}
+                y1={gridY(step)}
+                y2={gridY(step)}
+              />
+            ))}
+            {props.points.map((point, index) => {
+              const rect = rects()[index];
+              if (rect === undefined) return null;
+              const top = tops()[index] ?? null;
+              const last = highlight() && index === lastIndex();
+              return (
+                <g>
+                  <rect
+                    class={cx(styles['bar'], last && styles['last'])}
+                    x={rect.x}
+                    y={rect.y}
+                    width={rect.width}
+                    height={rect.height}
+                    rx={2}
+                    data-bar="true"
+                  >
+                    <title>{`${point.key}: ${named(props.seriesLabels?.primary, point.value)}`}</title>
+                  </rect>
+                  {top === null ? null : (
+                    <rect
+                      class={cx(styles['secondary'], last && styles['last'])}
+                      x={top.x}
+                      y={top.y}
+                      width={top.width}
+                      height={top.height}
+                      rx={2}
+                      data-series="secondary"
+                    >
+                      <title>{`${point.key}: ${named(props.seriesLabels?.secondary, point.secondary ?? 0)}`}</title>
+                    </rect>
+                  )}
+                </g>
+              );
+            })}
+          </svg>
+          {props.focusable === true ? chartHits(hits()) : null}
+        </div>
+        {props.points.length === 0 ? null : (
+          <div class={styles['keys']} aria-hidden="true">
+            <span class={styles['axis']} data-axis="first">
+              {props.points[0]?.key}
+            </span>
+            {/* One point: its bar is both first and last, so its key is named once. */}
+            {props.points.length === 1 ? null : (
+              <span class={styles['axis']} data-axis="last">
+                {props.points.at(-1)?.key}
+              </span>
             )}
-          </g>
-        );
-      })}
-      <text class={styles['axis']} x={BAR_CHART.width} y={BAR_CHART.top - 3} text-anchor="end">
-        {maxOf(props.points)}
-      </text>
-      {first() === undefined ? null : (
-        <text class={styles['axis']} x={0} y={BAR_CHART.height - 3} text-anchor="start">
-          {first()?.key}
-        </text>
-      )}
-      {last() === undefined ? null : (
-        <text class={styles['axis']} x={BAR_CHART.width} y={BAR_CHART.height - 3} text-anchor="end">
-          {last()?.key}
-        </text>
-      )}
-    </svg>
+          </div>
+        )}
+      </div>
+    </ChartFrame>
   );
 }