@signalcore/ui 0.1.0 → 1.0.0-beta.0

package/src/kit/AudioPlayer.tsx

@@ -0,0 +1,129 @@
+import { PauseIcon, PlayIcon } from "@phosphor-icons/react";
+import { useRef, useState, type ReactEventHandler } from "react";
+
+import { joined, useKit, useParts } from "./context";
+import { useWaveform } from "./waveform";
+
+export interface AudioPlayerProps {
+  src: string | undefined;
+  /** What it is, for screen readers: a voice note, a call's recording, a file's name. */
+  label: string;
+  onError?: ReactEventHandler<HTMLAudioElement> | undefined;
+  /** In a bar, beside other tools: a smaller play, a shorter waveform. */
+  compact?: boolean | undefined;
+  className?: string | undefined;
+}
+
+/** How many bars the waveform draws, and how high an even one stands while it is read. */
+const BARS = { full: 44, compact: 24 } as const;
+const EVEN = 0.35;
+/** The quietest bar still shows: silence reads as a line, not as nothing. */
+const LEAST = 0.12;
+
+/**
+ * Audio, played the kit's way: a quiet round play and pause, the audio's own waveform (its bars
+ * light up as it plays; dragging through it seeks), and its time (how long it is until it plays,
+ * then how far it is). The browser's own element plays it, never shown; a length the file
+ * doesn't tell yet is learnt as it plays.
+ */
+export function AudioPlayer({ src, label, onError, compact, className }: AudioPlayerProps) {
+  const part = useParts();
+  const { messages: words } = useKit();
+  const audio = useRef<HTMLAudioElement>(null);
+  const [playing, setPlaying] = useState(false);
+  const [at, setAt] = useState(0);
+  const [length, setLength] = useState<number | null>(null);
+  const bars = compact ? BARS.compact : BARS.full;
+  const wave = useWaveform(src, bars);
+  const learn = () => {
+    const seconds = audio.current?.duration;
+    if (seconds !== undefined && Number.isFinite(seconds)) setLength(seconds);
+  };
+  // The element's length, else the decoded one (an Ogg tells it only once played through).
+  const seconds = length ?? wave?.seconds ?? null;
+  const played = seconds ? Math.min(1, at / seconds) : 0;
+  return (
+    <div
+      role="group"
+      aria-label={label}
+      className={joined(
+        part("sc-audio", ...(compact ? (["sc-audio--compact"] as const) : [])),
+        className,
+      )}
+    >
+      <audio
+        ref={audio}
+        src={src}
+        preload="metadata"
+        onLoadedMetadata={learn}
+        onDurationChange={learn}
+        onPlay={() => {
+          setPlaying(true);
+        }}
+        onPause={() => {
+          setPlaying(false);
+        }}
+        onEnded={() => {
+          setPlaying(false);
+          setAt(0);
+        }}
+        onTimeUpdate={() => {
+          learn();
+          setAt(audio.current?.currentTime ?? 0);
+        }}
+        onError={onError}
+      />
+      <button
+        type="button"
+        className={part("sc-audio__play")}
+        aria-label={playing ? words.pause : words.play}
+        disabled={src === undefined}
+        onClick={() => {
+          const element = audio.current;
+          if (element === null) return;
+          if (element.paused) void element.play();
+          else element.pause();
+        }}
+      >
+        {playing ? <PauseIcon weight="fill" /> : <PlayIcon weight="fill" />}
+      </button>
+      <div className={part("sc-audio__wave")}>
+        {Array.from({ length: bars }, (_, index) => (
+          <span
+            key={index}
+            aria-hidden
+            data-played={index / bars < played ? "" : undefined}
+            style={{ height: `${Math.max(LEAST, wave?.heights[index] ?? EVEN) * 100}%` }}
+          />
+        ))}
+        <input
+          type="range"
+          min={0}
+          max={seconds ?? 0}
+          step="any"
+          value={Math.min(at, seconds ?? 0)}
+          disabled={seconds === null}
+          aria-label={words.position}
+          aria-valuetext={clock(at)}
+          onChange={(event) => {
+            const seconds = Number(event.target.value);
+            if (audio.current !== null) audio.current.currentTime = seconds;
+            setAt(seconds);
+          }}
+        />
+      </div>
+      <span className={part("sc-audio__time")}>
+        {clock(playing || at > 0 ? at : (seconds ?? 0))}
+      </span>
+    </div>
+  );
+}
+
+/** Seconds as a player says them: 0:07, 1:42, 1:02:05. */
+export function clock(seconds: number): string {
+  const whole = Math.max(0, Math.floor(seconds));
+  const hours = Math.floor(whole / 3600);
+  const minutes = Math.floor((whole % 3600) / 60);
+  const rest = String(whole % 60).padStart(2, "0");
+  return hours > 0 ? `${hours}:${String(minutes).padStart(2, "0")}:${rest}` : `${minutes}:${rest}`;
+}

package/src/kit/Button.tsx

@@ -0,0 +1,97 @@
+import { ArrowUpRightIcon, type Icon } from "@phosphor-icons/react";
+import type { ButtonHTMLAttributes, ReactNode } from "react";
+
+import { joined, useParts } from "./context";
+
+export interface ButtonProps extends Omit<ButtonHTMLAttributes<HTMLButtonElement>, "children"> {
+  /**
+   * primary: the ink, for the one that matters; neutral: a hairline; danger: what can't be
+   * undone; ghost: bare until the pointer is on it (a row's ⋯).
+   */
+  tone?: "primary" | "neutral" | "danger" | "ghost" | undefined;
+  /** sm: 28px, for a row or a line of words. */
+  size?: "md" | "sm" | undefined;
+  /** A glyph before the words; alone, the button is a square and `aria-label` names it. */
+  icon?: Icon | undefined;
+  /** A page to open apart instead: the button is a link, an arrow after its words. */
+  href?: string | undefined;
+  /** With `href`, the link saves what it points at under this name instead of opening it. */
+  download?: string | undefined;
+  /** It was the one pressed: ringed in the accent. */
+  pressed?: boolean | undefined;
+  children?: ReactNode;
+}
+
+/**
+ * A pill to press: a hairline by default, filled with the ink for the main action, the danger
+ * tone for what can't be undone, bare for a quiet control. With `href` it is a link that opens
+ * its page apart, never sending this page's address along; with `download` too, one that saves.
+ */
+export function Button({
+  tone = "neutral",
+  size = "md",
+  icon: Glyph,
+  href,
+  download,
+  pressed,
+  className,
+  children,
+  type = "button",
+  part: own,
+  ...rest
+}: ButtonProps) {
+  const part = useParts();
+  // Its part names for a page's `::part()`: the caller's own, then the kit's.
+  const named = joined(own, "button", `button-${tone}`);
+  const classes = joined(
+    part(
+      "sc-button",
+      `sc-button--${tone}`,
+      ...(size === "sm" ? (["sc-button--sm"] as const) : []),
+      ...(children === undefined ? (["sc-button--icon"] as const) : []),
+    ),
+    className,
+  );
+  if (href !== undefined && download !== undefined) {
+    return (
+      <a
+        href={href}
+        download={download}
+        aria-label={rest["aria-label"]}
+        part={named}
+        className={classes}
+      >
+        {Glyph && <Glyph aria-hidden weight="bold" />}
+        {children}
+      </a>
+    );
+  }
+  if (href !== undefined) {
+    return (
+      <a
+        href={href}
+        target="_blank"
+        rel="noopener noreferrer"
+        aria-label={rest["aria-label"]}
+        part={named}
+        className={classes}
+      >
+        {Glyph && <Glyph aria-hidden weight="bold" />}
+        {children}
+        <ArrowUpRightIcon aria-hidden weight="bold" />
+      </a>
+    );
+  }
+  return (
+    <button
+      type={type}
+      aria-pressed={pressed || undefined}
+      part={named}
+      className={classes}
+      {...rest}
+    >
+      {Glyph && <Glyph aria-hidden weight="bold" />}
+      {children}
+    </button>
+  );
+}

package/src/kit/Card.tsx

@@ -0,0 +1,47 @@
+import type { ReactNode } from "react";
+
+import { joined, useParts } from "./context";
+import { Mark } from "./Mark";
+
+/**
+ * Things under a title and a quieter line, set apart in one hairline box lifted a hair. With
+ * `image`, the head starts with it, bare, as `Mark` draws a logo.
+ */
+export function Card({
+  title,
+  subtitle,
+  image,
+  className,
+  children,
+}: {
+  title?: ReactNode;
+  subtitle?: ReactNode;
+  /** A logo or a picture at the head's start. */
+  image?: string | undefined;
+  className?: string | undefined;
+  children: ReactNode;
+}) {
+  const part = useParts();
+  const words = (title !== undefined || subtitle !== undefined) && (
+    <div className={part("sc-panel__heading")}>
+      {title !== undefined && <h3 className={part("sc-panel__title")}>{title}</h3>}
+      {subtitle !== undefined && <p className={part("sc-panel__subtitle")}>{subtitle}</p>}
+    </div>
+  );
+  return (
+    <section part="card" className={joined(part("sc-panel"), className)}>
+      {(words !== false || image !== undefined) && (
+        <header
+          className={part(
+            "sc-panel__head",
+            ...(image !== undefined ? (["sc-panel__head--image"] as const) : []),
+          )}
+        >
+          {image !== undefined && <Mark src={image} size={44} />}
+          {words}
+        </header>
+      )}
+      {children}
+    </section>
+  );
+}

package/src/kit/Chart.tsx

@@ -0,0 +1,129 @@
+import { useId, useState, type PointerEvent } from "react";
+
+import type { ChartPoint } from "../blocks";
+import { useKit, useParts } from "./context";
+import { formatNumber } from "./numbers";
+
+/** The line's drawing box: wide and short; it stretches to the chart's width. */
+const WIDTH = 600;
+const HEIGHT = 160;
+/** Room above the highest point, so its dot is never cut. */
+const HEADROOM = 8;
+
+/**
+ * Figures over a few labels, one series in the chart's ink: `bar`, a row a label, its bar from
+ * one baseline and its figure at the tip; `line`, the labels in their order (days, weeks) as one
+ * line over a wash, its extremes on the axis and the point under the pointer told in full.
+ */
+export function Chart({ kind, points }: { kind: "bar" | "line"; points: ChartPoint[] }) {
+  return kind === "line" ? <Line points={points} /> : <Bars points={points} />;
+}
+
+function Bars({ points }: { points: ChartPoint[] }) {
+  const part = useParts();
+  const { code } = useKit();
+  const most = Math.max(...points.map((point) => point.value), 0);
+  return (
+    <ul part="chart" className={part("sc-chart", "sc-chart--bar")}>
+      {points.map((point, index) => (
+        <li key={index} className={part("sc-chart__row")}>
+          <span className={part("sc-chart__label")}>{point.label}</span>
+          <span className={part("sc-chart__track")}>
+            <span
+              className={part("sc-chart__bar")}
+              style={{ width: most > 0 ? `${(Math.max(point.value, 0) / most) * 100}%` : 0 }}
+            />
+          </span>
+          <span className={part("sc-chart__value")}>{formatNumber(point.value, code)}</span>
+        </li>
+      ))}
+    </ul>
+  );
+}
+
+function Line({ points }: { points: ChartPoint[] }) {
+  const part = useParts();
+  const { code } = useKit();
+  const wash = useId();
+  const [shown, setShown] = useState<number | null>(null);
+  const values = points.map((point) => point.value);
+  const most = Math.max(...values, 0);
+  const least = Math.min(...values, 0);
+  const span = most - least || 1;
+  const x = (index: number) =>
+    points.length === 1 ? WIDTH / 2 : (index / (points.length - 1)) * WIDTH;
+  const y = (value: number) => HEADROOM + (1 - (value - least) / span) * (HEIGHT - HEADROOM);
+  const line = points.map((point, index) => `${x(index)},${y(point.value)}`).join(" ");
+  const area = `${x(0)},${y(least)} ${line} ${x(points.length - 1)},${y(least)}`;
+  const first = points[0];
+  const last = points.at(-1);
+  const hovered = shown === null ? undefined : points[shown];
+
+  const onPointerMove = (event: PointerEvent<HTMLDivElement>) => {
+    const box = event.currentTarget.getBoundingClientRect();
+    const at = (event.clientX - box.left) / box.width;
+    setShown(Math.min(points.length - 1, Math.max(0, Math.round(at * (points.length - 1)))));
+  };
+
+  return (
+    <figure part="chart" className={part("sc-chart", "sc-chart--line")}>
+      <span className={part("sc-chart__top")}>{formatNumber(most, code)}</span>
+      <div
+        className={part("sc-chart__plot")}
+        onPointerMove={onPointerMove}
+        onPointerLeave={() => {
+          setShown(null);
+        }}
+      >
+        <svg viewBox={`0 0 ${WIDTH} ${HEIGHT}`} preserveAspectRatio="none" aria-hidden>
+          <defs>
+            <linearGradient id={wash} x1="0" x2="0" y1="0" y2="1">
+              <stop offset="0" className={part("sc-chart__wash")} />
+              <stop offset="1" className={part("sc-chart__wash")} stopOpacity={0} />
+            </linearGradient>
+          </defs>
+          <line x1={0} x2={WIDTH} y1={HEIGHT} y2={HEIGHT} className={part("sc-chart__axis")} />
+          <polygon points={area} fill={`url(#${wash})`} />
+          <polyline points={line} className={part("sc-chart__line")} />
+        </svg>
+        {hovered !== undefined && shown !== null && (
+          <>
+            <span
+              className={part("sc-chart__dot")}
+              style={{
+                left: `${(x(shown) / WIDTH) * 100}%`,
+                top: `${(y(hovered.value) / HEIGHT) * 100}%`,
+              }}
+            />
+            <span
+              role="status"
+              className={part("sc-chart__tip")}
+              style={{
+                left: `${(x(shown) / WIDTH) * 100}%`,
+                // Kept inside the chart at its ends.
+                translate: shown === 0 ? "0" : shown === points.length - 1 ? "-100%" : "-50%",
+              }}
+            >
+              <span>{hovered.label}</span>
+              <strong>{formatNumber(hovered.value, code)}</strong>
+            </span>
+          </>
+        )}
+      </div>
+      <figcaption className={part("sc-chart__ends")}>
+        <span>{first?.label}</span>
+        {points.length > 1 && <span>{last?.label}</span>}
+      </figcaption>
+      <table className={part("sc-chart__data")}>
+        <tbody>
+          {points.map((point, index) => (
+            <tr key={index}>
+              <th scope="row">{point.label}</th>
+              <td>{formatNumber(point.value, code)}</td>
+            </tr>
+          ))}
+        </tbody>
+      </table>
+    </figure>
+  );
+}

package/src/kit/Choices.tsx

@@ -0,0 +1,131 @@
+import { CheckIcon } from "@phosphor-icons/react";
+import { useRef, type KeyboardEvent } from "react";
+
+import { useParts } from "./context";
+import { ariaOf, type ControlBase } from "./Field";
+import { toggled, type Option } from "./options";
+
+const MOVES: Readonly<Record<string, 1 | -1>> = {
+  ArrowRight: 1,
+  ArrowDown: 1,
+  ArrowLeft: -1,
+  ArrowUp: -1,
+};
+
+/**
+ * A group of radios as native ones behave: one stop for Tab (the one checked, else the first),
+ * the arrows move to the next or the previous one and check it, Home and End to the ends.
+ */
+export function useRadios(count: number, checked: number, check: (index: number) => void) {
+  const items = useRef<(HTMLElement | null)[]>([]);
+  return {
+    ref: (index: number) => (element: HTMLElement | null) => {
+      items.current[index] = element;
+    },
+    tabIndex: (index: number) => (index === Math.max(0, checked) ? 0 : -1),
+    onKeyDown: (event: KeyboardEvent, index: number) => {
+      const move = MOVES[event.key];
+      const next =
+        event.key === "Home"
+          ? 0
+          : event.key === "End"
+            ? count - 1
+            : move !== undefined
+              ? (index + move + count) % count
+              : null;
+      if (next === null) return;
+      event.preventDefault();
+      items.current[next]?.focus();
+      check(next);
+    },
+  };
+}
+
+/** Few short options with no hints sit side by side in one bar; any other few are cards. */
+export function segmented(options: Option[]): boolean {
+  const length = options.reduce((sum, option) => sum + option.label.length, 0);
+  return options.length <= 4 && length <= 32 && options.every((option) => !option.hint);
+}
+
+/**
+ * One of a few options, all in sight, as a group of radios: one bar of segments when they are
+ * short, else a card each with its hint under its label and a dot that fills when picked.
+ */
+export function Choices({
+  options,
+  value,
+  onChange,
+  ...control
+}: ControlBase & {
+  options: Option[];
+  value: string | null;
+  onChange: (id: string) => void;
+}) {
+  const part = useParts();
+  const checked = options.findIndex((option) => option.id === value);
+  const radios = useRadios(options.length, checked, (index) => {
+    const option = options[index];
+    if (option) onChange(option.id);
+  });
+  const bar = segmented(options);
+  return (
+    <div role="radiogroup" {...ariaOf(control)} className={part(bar ? "sc-segments" : "sc-picks")}>
+      {options.map((option, index) => (
+        <button
+          key={option.id}
+          ref={radios.ref(index)}
+          type="button"
+          role="radio"
+          aria-checked={index === checked}
+          tabIndex={radios.tabIndex(index)}
+          disabled={control.disabled}
+          onKeyDown={(event) => radios.onKeyDown(event, index)}
+          onClick={() => onChange(option.id)}
+          className={part("sc-pick")}
+        >
+          {!bar && <i aria-hidden />}
+          <span>
+            {option.label}
+            {option.hint !== undefined && <small>{option.hint}</small>}
+          </span>
+        </button>
+      ))}
+    </div>
+  );
+}
+
+/** Several of a few options: a chip each, ticked on and off, a check on those picked. */
+export function Chips({
+  options,
+  value,
+  onChange,
+  ...control
+}: ControlBase & {
+  options: Option[];
+  value: string[];
+  onChange: (ids: string[]) => void;
+}) {
+  const part = useParts();
+  return (
+    <div role="group" {...ariaOf(control)} aria-required={undefined} className={part("sc-chips")}>
+      {options.map((option) => {
+        const on = value.includes(option.id);
+        return (
+          <button
+            key={option.id}
+            type="button"
+            role="checkbox"
+            aria-checked={on}
+            title={option.hint}
+            disabled={control.disabled}
+            onClick={() => onChange(toggled(options, value, option.id))}
+            className={part("sc-chip")}
+          >
+            {on && <CheckIcon aria-hidden weight="bold" />}
+            {option.label}
+          </button>
+        );
+      })}
+    </div>
+  );
+}