@eifi1/ui-kit 0.7.1 → 0.8.1

package/src/components/scroll-area.tsx

@@ -0,0 +1,129 @@
+import { useCallback, useLayoutEffect, useRef, useState } from "react";
+import type { ComponentPropsWithoutRef, Ref, RefObject } from "react";
+import { cn } from "../lib/cn";
+
+/**
+ * Whether `ref`'s element currently overflows its box — the one fact a scroll
+ * container needs to decide whether it is a keyboard stop.
+ *
+ * Measured on every commit (cheap: two reads, and state is set only on a change) and
+ * whenever the element or one of its direct children resizes, which covers both
+ * "the panel got narrower" and "the rows arrived". Without `ResizeObserver` (jsdom,
+ * very old engines) the per-commit measurement is what remains.
+ *
+ * Shared with {@link Table}'s overflow wrapper, which has the same obligation.
+ */
+export function useScrollOverflow(ref: RefObject<HTMLElement | null>): boolean {
+  const [overflowing, setOverflowing] = useState(false);
+
+  const measure = useCallback(() => {
+    const el = ref.current;
+    if (!el) return;
+    const next = el.scrollHeight > el.clientHeight + 1 || el.scrollWidth > el.clientWidth + 1;
+    setOverflowing((prev) => (prev === next ? prev : next));
+  }, [ref]);
+
+  // No dependency list on purpose: content changes arrive as re-renders.
+  useLayoutEffect(() => {
+    measure();
+  });
+
+  useLayoutEffect(() => {
+    const el = ref.current;
+    if (!el || typeof ResizeObserver === "undefined") return;
+    const ro = new ResizeObserver(measure);
+    ro.observe(el);
+    for (const child of Array.from(el.children)) ro.observe(child);
+    return () => ro.disconnect();
+  }, [ref, measure]);
+
+  return overflowing;
+}
+
+/** Thin, token-coloured scrollbars. `scrollbar-width` / `scrollbar-color` are the
+ *  standard (Firefox, Chrome 121+); the `::-webkit-scrollbar` rules are for Safari,
+ *  which has neither. Where the standard pair applies, Chrome ignores the rest. */
+export const THIN_SCROLLBAR_CLASS = cn(
+  "[scrollbar-width:thin] [scrollbar-color:var(--border-strong)_transparent]",
+  "[&::-webkit-scrollbar]:size-2 [&::-webkit-scrollbar-track]:bg-transparent",
+  "[&::-webkit-scrollbar-thumb]:rounded-full [&::-webkit-scrollbar-thumb]:bg-[var(--border-strong)]",
+);
+
+const AXIS = {
+  vertical: "overflow-y-auto overflow-x-hidden",
+  horizontal: "overflow-x-auto overflow-y-hidden",
+  both: "overflow-auto",
+} as const;
+
+export interface ScrollAreaProps extends ComponentPropsWithoutRef<"div"> {
+  /** Which way the content may scroll. Default `vertical`. */
+  orientation?: keyof typeof AXIS;
+  /**
+   * The region's accessible name. With it (or `aria-labelledby`) the container is a
+   * `role="region"` a reader can find and name; without it, it is a plain box.
+   * Name every ScrollArea whose content can overflow: once it is a tab stop, a
+   * reader announces it on focus, and an unnamed one is announced as nothing.
+   */
+  label?: string;
+  ref?: Ref<HTMLDivElement>;
+}
+
+/**
+ * A styled overflow container: a thin scrollbar in the kit's colours, a focus ring,
+ * and the keyboard access a plain `overflow-auto` div does not have.
+ *
+ * kastlan used Radix's ScrollArea for this and nothing else from it. Radix draws a
+ * custom scrollbar in JavaScript; the platform's own, thinned and coloured, costs no
+ * script and keeps native momentum, overscroll and scrollbar-dragging behaviour.
+ *
+ * A container that scrolls but holds nothing focusable cannot be scrolled from the
+ * keyboard at all — Tab jumps straight past it (WCAG 2.1.1). So while the content
+ * overflows, the container itself is a tab stop (`tabIndex=0`), and arrow keys and
+ * Page Up/Down scroll it natively. While nothing overflows it is not, so a short list
+ * adds no empty stop to the tab order.
+ */
+export function ScrollArea({
+  orientation = "vertical",
+  label,
+  className,
+  ref,
+  tabIndex,
+  "aria-labelledby": labelledBy,
+  ...rest
+}: ScrollAreaProps) {
+  const inner = useRef<HTMLDivElement | null>(null);
+  const overflowing = useScrollOverflow(inner);
+  const setRef = useCallback(
+    (el: HTMLDivElement | null) => {
+      inner.current = el;
+      if (typeof ref === "function") ref(el);
+      else if (ref) ref.current = el;
+    },
+    [ref],
+  );
+  const named = label !== undefined || labelledBy !== undefined;
+
+  return (
+    <div
+      {...rest}
+      ref={setRef}
+      role={named ? "region" : undefined}
+      aria-label={label}
+      aria-labelledby={labelledBy}
+      tabIndex={tabIndex ?? (overflowing ? 0 : undefined)}
+      data-overflowing={overflowing || undefined}
+      data-orientation={orientation}
+      className={cn(
+        "relative min-h-0 min-w-0",
+        AXIS[orientation],
+        THIN_SCROLLBAR_CLASS,
+        // An OUTLINE, inset: a ring is a box-shadow, which paints beneath the content —
+        // a row with its own background would cover exactly the part of the ring that
+        // says where focus is. An outline paints above it, and the negative offset
+        // keeps it inside a parent that clips.
+        "focus-visible:outline-2 focus-visible:-outline-offset-2 focus-visible:outline-[var(--brand)]",
+        className,
+      )}
+    />
+  );
+}

package/src/components/separator.tsx

@@ -0,0 +1,37 @@
+import type { ComponentPropsWithoutRef } from "react";
+import { cn } from "../lib/cn";
+
+export interface SeparatorProps extends Omit<ComponentPropsWithoutRef<"div">, "children" | "role"> {
+  orientation?: "horizontal" | "vertical";
+  /**
+   * `false` (default, as in Radix): a real `role="separator"`, which a reader
+   * announces — right between groups of controls, a menu's sections, a toolbar's
+   * halves. `true`: a line for the eye only (`role="none"`), for a divider that
+   * separates nothing the structure does not already separate.
+   */
+  decorative?: boolean;
+}
+
+/**
+ * A hairline between two things.
+ *
+ * kastlan's other Radix leftover. `aria-orientation` is set only when vertical:
+ * horizontal is the role's default, and stating a default is noise in every reader's
+ * verbose mode.
+ */
+export function Separator({ orientation = "horizontal", decorative = false, className, ...rest }: SeparatorProps) {
+  const vertical = orientation === "vertical";
+  return (
+    <div
+      {...rest}
+      role={decorative ? "none" : "separator"}
+      aria-orientation={!decorative && vertical ? "vertical" : undefined}
+      data-orientation={orientation}
+      className={cn(
+        "shrink-0 bg-[var(--border)]",
+        vertical ? "w-px self-stretch" : "h-px w-full",
+        className,
+      )}
+    />
+  );
+}

package/src/components/series-chart-ticks.ts

@@ -50,3 +50,138 @@ export function niceTicks(
   }
   return ticks.length ? ticks : undefined;
 }
+
+/**
+ * {@link niceTicks} on whole numbers only: the step never drops below 1, so a short
+ * index series (a domain of [-0.2, 4.2]) is ticked 0 1 2 3 4 instead of every half.
+ * `undefined` when the window holds no whole number at all, so the caller can fall
+ * back to the fractional ticks of a deep zoom rather than show none.
+ */
+export function integerTicks(
+  domain: readonly [number, number] | undefined,
+  target: number = TARGET_TICKS,
+): number[] | undefined {
+  if (!domain) return undefined;
+  const [low, high] = domain;
+  if (!Number.isFinite(low) || !Number.isFinite(high) || !(high >= low)) return undefined;
+  const step = high > low ? Math.max(1, niceStep(high - low, target)) : 1;
+  const ticks: number[] = [];
+  const first = Math.ceil(low / step - 1e-6);
+  const last = Math.floor(high / step + 1e-6);
+  for (let k = first; k <= last; k++) ticks.push(k * step + 0);
+  return ticks.length ? ticks : undefined;
+}
+
+/**
+ * The slots of a CATEGORY axis that lie inside a window over their positions.
+ *
+ * `SeriesChart` draws a category axis on the slot INDEX (see `x.type: "category"`), so a
+ * zoom window is a range of fractional positions — [2.6, 8.3] after a drag across the
+ * third to ninth month. A tick belongs on every whole slot inside it, and on nothing in
+ * between: there is no month 2.5. Recharts' `minTickGap` thins them where they crowd.
+ */
+export function categoryTicks(
+  domain: readonly [number, number] | undefined,
+  count: number,
+): number[] | undefined {
+  if (!domain || !(count > 0)) return undefined;
+  const first = Math.max(0, Math.ceil(domain[0] - 1e-6));
+  const last = Math.min(count - 1, Math.floor(domain[1] + 1e-6));
+  const ticks: number[] = [];
+  for (let slot = first; slot <= last; slot++) ticks.push(slot);
+  return ticks.length ? ticks : undefined;
+}
+
+/** What one tick of a time axis stands for, which is also how its label is written. */
+export type TimeTickUnit = "hour" | "day" | "month" | "year";
+
+const HOUR = 3_600_000;
+const DAY = 24 * HOUR;
+
+/**
+ * The calendar steps a time axis may tick in, with their rough length for choosing.
+ * Months and years are stepped with `Date` setters, not by adding their "length":
+ * thirty days from the 1st of February is the 3rd of March, and a tick that promises a
+ * month start and prints the 3rd is the ruler lying.
+ */
+const TIME_STEPS: readonly { unit: TimeTickUnit; n: number; ms: number }[] = [
+  { unit: "hour", n: 1, ms: HOUR },
+  { unit: "hour", n: 3, ms: 3 * HOUR },
+  { unit: "hour", n: 6, ms: 6 * HOUR },
+  { unit: "hour", n: 12, ms: 12 * HOUR },
+  { unit: "day", n: 1, ms: DAY },
+  { unit: "day", n: 2, ms: 2 * DAY },
+  { unit: "day", n: 7, ms: 7 * DAY },
+  { unit: "month", n: 1, ms: 30.44 * DAY },
+  { unit: "month", n: 2, ms: 60.88 * DAY },
+  { unit: "month", n: 3, ms: 91.31 * DAY },
+  { unit: "month", n: 6, ms: 182.62 * DAY },
+];
+
+/**
+ * Calendar ticks inside a window of epoch milliseconds — midnights, Mondays, month and
+ * quarter starts, new years, in LOCAL time — and the unit they are in, so the label can
+ * say as much as the tick means ("Mar 26" for a month start, "14 Mar" for a day).
+ *
+ * The time counterpart of {@link niceTicks}: a 1/2/5 ladder over raw milliseconds lands
+ * on 5 × 10⁹ ms, every 58 days, at whatever hour that happens to be. keksdose's price
+ * history and cash buffer each thinned their own ticks by hand for exactly this reason.
+ */
+export function timeTicksWithUnit(
+  domain: readonly [number, number] | undefined,
+  target: number = TARGET_TICKS,
+): { ticks: number[]; unit: TimeTickUnit } | undefined {
+  if (!domain) return undefined;
+  const [low, high] = domain;
+  if (!Number.isFinite(low) || !Number.isFinite(high) || !(high > low)) return undefined;
+  const rough = (high - low) / Math.max(1, target);
+  let unit: TimeTickUnit = "year";
+  let n = 1;
+  let best = Infinity;
+  for (const step of TIME_STEPS) {
+    const miss = Math.abs(Math.log(step.ms / rough));
+    if (miss < best) {
+      best = miss;
+      unit = step.unit;
+      n = step.n;
+    }
+  }
+  // The year ladder competes on the same terms as the table: one year is 365.25 days.
+  const yearN = Math.max(1, Math.round(niceStep((high - low) / (365.25 * DAY), target)));
+  if (Math.abs(Math.log((yearN * 365.25 * DAY) / rough)) < best) {
+    unit = "year";
+    n = yearN;
+  }
+
+  const start = new Date(low);
+  start.setMinutes(0, 0, 0);
+  if (unit !== "hour") start.setHours(0);
+  if (unit === "month" || unit === "year") start.setDate(1);
+  if (unit === "year") start.setMonth(0);
+  // Onto the step's own grid: hours of the day, Mondays, month indices, years — so a
+  // zoom window starting on a Wednesday still ticks on Mondays.
+  if (unit === "hour") start.setHours(start.getHours() - (start.getHours() % n));
+  if (unit === "day" && n === 7) start.setDate(start.getDate() - ((start.getDay() + 6) % 7));
+  if (unit === "month") start.setMonth(start.getMonth() - (start.getMonth() % n));
+  if (unit === "year") start.setFullYear(start.getFullYear() - (start.getFullYear() % n));
+
+  const ticks: number[] = [];
+  const at = new Date(start);
+  // Bounded, so a window of a million years cannot hang the render.
+  for (let guard = 0; guard < 1000 && at.getTime() <= high; guard++) {
+    if (at.getTime() >= low) ticks.push(at.getTime());
+    if (unit === "hour") at.setHours(at.getHours() + n);
+    else if (unit === "day") at.setDate(at.getDate() + n);
+    else if (unit === "month") at.setMonth(at.getMonth() + n);
+    else at.setFullYear(at.getFullYear() + n);
+  }
+  return ticks.length ? { ticks, unit } : undefined;
+}
+
+/** {@link timeTicksWithUnit}, ticks only. */
+export function timeTicks(
+  domain: readonly [number, number] | undefined,
+  target: number = TARGET_TICKS,
+): number[] | undefined {
+  return timeTicksWithUnit(domain, target)?.ticks;
+}