@ultimat3/ui 23.0.0 → 25.0.0

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>
   );
 }

package/src/components/Card.tsx

@@ -21,20 +21,56 @@ export interface CardProps {
 }
 
 export function Card(props: CardProps): JSX.Element {
-  const Tag = props.as ?? 'div';
-  return (
-    <Tag
-      class={cx(
-        styles['card'],
-        styles[`elevation-${props.elevation ?? 'sm'}`],
-        props.interactive === true && styles['interactive'],
-        props.class,
-      )}
-      style={{ '--card-padding': `var(--space-${props.padding ?? 5})` }}
-    >
-      {props.header === undefined ? null : <div class={styles['header']}>{props.header}</div>}
-      <div class={styles['body']}>{props.children}</div>
-      {props.footer === undefined ? null : <div class={styles['footer']}>{props.footer}</div>}
-    </Tag>
-  );
+  const cls = (): string =>
+    cx(
+      styles['card'],
+      styles[`elevation-${props.elevation ?? 'sm'}`],
+      props.interactive === true && styles['interactive'],
+      props.class,
+    );
+  const style = (): JSX.CSSProperties => ({
+    '--card-padding': `var(--space-${props.padding ?? 5})`,
+  });
+  const header = (): JSX.Element =>
+    props.header === undefined ? null : <div class={styles['header']}>{props.header}</div>;
+  const body = (): JSX.Element => <div class={styles['body']}>{props.children}</div>;
+  const footer = (): JSX.Element =>
+    props.footer === undefined ? null : <div class={styles['footer']}>{props.footer}</div>;
+
+  // One intrinsic per case, never `const Tag = props.as; <Tag>`: the island build compiles a
+  // capitalised tag to `createComponent(Tag)` and calls the string (#488, `intrinsic-root.test.ts`).
+  switch (props.as ?? 'div') {
+    case 'article':
+      return (
+        <article class={cls()} style={style()}>
+          {header()}
+          {body()}
+          {footer()}
+        </article>
+      );
+    case 'section':
+      return (
+        <section class={cls()} style={style()}>
+          {header()}
+          {body()}
+          {footer()}
+        </section>
+      );
+    case 'li':
+      return (
+        <li class={cls()} style={style()}>
+          {header()}
+          {body()}
+          {footer()}
+        </li>
+      );
+    case 'div':
+      return (
+        <div class={cls()} style={style()}>
+          {header()}
+          {body()}
+          {footer()}
+        </div>
+      );
+  }
 }

package/src/components/ChartFrame.module.scss

@@ -0,0 +1,188 @@
+@use '../tokens' as t;
+
+// The figure is the container every chart's layout asks about: a 390px phone column and a
+// 1440px dashboard tile are the same component at two container widths, never two components.
+.frame {
+  @include t.container(chart-frame);
+  // The visually-hidden table is absolute; this keeps it inside the figure, not the page.
+  position: relative;
+  display: grid;
+  gap: t.space(2);
+  inline-size: 100%;
+  margin: 0;
+
+  // A series' colour is its slot's role, keyed on `data-series` so every chart (and its legend)
+  // reads one rule. `chart-1` … `chart-8` are the categorical roles, AA against both surfaces.
+  @for $slot from 1 through 8 {
+    [data-series='#{$slot}'] {
+      --series: #{t.role('chart-#{$slot}')};
+    }
+  }
+}
+
+.caption {
+  @include t.label-caps;
+  color: t.role('fg-muted');
+}
+
+.hidden {
+  @include t.visually-hidden;
+}
+
+.layout {
+  display: grid;
+  gap: t.space(3);
+  min-inline-size: 0;
+}
+
+.plot {
+  min-inline-size: 0;
+}
+
+// Narrow first: the legend is a wrapping row under the plot.
+.legend {
+  display: flex;
+  flex-wrap: wrap;
+  gap: t.space(1) t.space(4);
+  margin: 0;
+  padding: 0;
+  list-style: none;
+}
+
+// Wide enough for a plot AND a column beside it: the legend stands at the plot's end edge.
+@include t.container-query(chart-frame, 40rem) {
+  .withLegend {
+    grid-template-columns: minmax(0, 1fr) auto;
+    align-items: center;
+  }
+
+  .withLegend .legend {
+    flex-direction: column;
+    flex-wrap: nowrap;
+  }
+}
+
+.item {
+  display: flex;
+  align-items: center;
+  gap: t.space(2);
+  min-inline-size: 0;
+  font-size: t.text(sm);
+  color: t.role('fg');
+}
+
+.swatch {
+  display: inline-flex;
+  flex: none;
+}
+
+.name {
+  @include t.truncate;
+}
+
+.value {
+  @include t.data-text;
+  color: t.role('fg-strong');
+}
+
+.detail {
+  @include t.data-text;
+  color: t.role('fg-muted');
+}
+
+.key {
+  display: block;
+  inline-size: t.space(6);
+  block-size: t.space(3);
+  overflow: visible;
+}
+
+.keyLine {
+  fill: none;
+  stroke: var(--series);
+  stroke-width: 2;
+  stroke-linecap: round;
+  vector-effect: non-scaling-stroke;
+}
+
+.keyMarker {
+  fill: var(--series);
+}
+
+// --- The keyboard layer ------------------------------------------------------
+// Over the plot box, which every chart sheet makes `position: relative`. The layer lets the
+// pointer through to nothing in particular; only the points themselves are targets.
+.hits {
+  position: absolute;
+  inset: 0;
+  pointer-events: none;
+}
+
+.hit {
+  // A small visible dot, a finger-sized target: the pseudo-element grows the hit area.
+  @include t.touch-target($extend: true);
+  position: absolute;
+  inset-block-start: var(--y);
+  inset-inline-start: var(--x);
+  inline-size: t.space(3);
+  block-size: t.space(3);
+  // Centred on the point by half its own size — margins, not a percentage translate, so the rule
+  // reads the same in either direction (`rtl-sheets.test.ts`).
+  margin-block-start: calc(#{t.space(3)} / -2);
+  margin-inline-start: calc(#{t.space(3)} / -2);
+  border-radius: t.radius(full);
+  pointer-events: auto;
+  cursor: default;
+
+  &:hover,
+  &:focus-visible {
+    background: t.role('fg-strong', 0.18);
+  }
+
+  @include t.focus-ring;
+}
+
+// The readout: a zero-width anchor over the point whose bubble overflows it equally both ways
+// (flex `center`), so it is centred with no translate. Visible on hover and keyboard focus only.
+.readout {
+  position: absolute;
+  inset-block-end: calc(100% + #{t.space(2)});
+  inset-inline-start: 50%;
+  display: flex;
+  justify-content: center;
+  inline-size: 0;
+  visibility: hidden;
+  opacity: 0;
+  transition: opacity t.duration(fast) t.easing(out);
+
+  .hit:hover > &,
+  .hit:focus-visible > & {
+    visibility: visible;
+    opacity: 1;
+  }
+
+  // A point at the edge of the plot opens its readout inward, so it never leaves the box.
+  .hit[data-edge='start'] > & {
+    inset-inline-start: 0;
+    justify-content: flex-start;
+  }
+
+  .hit[data-edge='end'] > & {
+    inset-inline-start: auto;
+    inset-inline-end: 0;
+    justify-content: flex-end;
+  }
+}
+
+.bubble {
+  @include t.data-text;
+  flex: none;
+  padding: t.space(1) t.space(2);
+  border: t.stroke(hairline) solid t.role('line');
+  border-radius: t.radius(sm);
+  background: t.role('surface-raised');
+  box-shadow: t.shadow(md);
+  color: t.role('fg-strong');
+  font-size: t.text(xs);
+  white-space: nowrap;
+}