sid-ui 0.0.0-stage → 0.1.1

package/src/components/Responsive.tsx

@@ -0,0 +1,128 @@
+"use client";
+
+import { useEffect, useState, type CSSProperties, type ReactNode, type RefObject } from "react";
+
+import {
+  spacing,
+  tierFor,
+  type ResponsiveTo,
+  type SpacingStep,
+  type Tier,
+  type TierOrBase,
+} from "./breakpoints";
+
+/** Live content-box width of an element; 0 until measured. */
+export function useElementWidth(ref: RefObject<HTMLElement | null>) {
+  const [width, setWidth] = useState(0);
+  useEffect(() => {
+    const el = ref.current;
+    if (!el) return;
+    const observer = new ResizeObserver(([entry]) => setWidth(Math.round(entry.contentRect.width)));
+    observer.observe(el);
+    return () => observer.disconnect();
+  }, [ref]);
+  return width;
+}
+
+/** Container tier of an element — the same tiers GridSystem uses in container mode. */
+export function useContainerBreakpoint(ref: RefObject<HTMLElement | null>): TierOrBase {
+  return tierFor(useElementWidth(ref), "container");
+}
+
+/** Viewport tier of the window — Astryx's own width breakpoints. */
+export function useViewportBreakpoint(): TierOrBase {
+  const [width, setWidth] = useState(0);
+  useEffect(() => {
+    const update = () => setWidth(window.innerWidth);
+    update();
+    window.addEventListener("resize", update);
+    return () => window.removeEventListener("resize", update);
+  }, []);
+  return tierFor(width, "viewport");
+}
+
+export interface ResponsiveContainerProps {
+  children: ReactNode;
+  className?: string;
+  style?: CSSProperties;
+}
+
+/** Marks a region that Show, Hide, and ResponsiveStack measure in container mode. */
+export function ResponsiveContainer({ children, className, style }: ResponsiveContainerProps) {
+  return (
+    <div className={["os-responsive-container", className].filter(Boolean).join(" ")} style={style}>
+      {children}
+    </div>
+  );
+}
+
+export interface ResponsiveStackProps {
+  children: ReactNode;
+  /** Tier where the stack turns from a column into a row. */
+  from?: Tier;
+  gap?: SpacingStep;
+  responsiveTo?: ResponsiveTo;
+  /** Give every child an equal share of the row. */
+  isEqual?: boolean;
+  /** Cross-axis alignment once horizontal. */
+  align?: "start" | "center" | "end" | "stretch";
+  /** Put the last child first while stacked — e.g. an image above its copy. */
+  isReversedWhenStacked?: boolean;
+}
+
+/** Stacked on narrow widths, side by side from a tier up. */
+export function ResponsiveStack({
+  children,
+  from = "md",
+  gap = 4,
+  responsiveTo = "container",
+  isEqual,
+  align = "stretch",
+  isReversedWhenStacked,
+}: ResponsiveStackProps) {
+  return (
+    <div className={`os-rstack-root os-responsive-${responsiveTo}`}>
+      <div
+        className={[
+          "os-rstack",
+          `os-rstack-from-${from}`,
+          isEqual && "os-rstack-equal",
+          isReversedWhenStacked && "os-rstack-reverse",
+        ]
+          .filter(Boolean)
+          .join(" ")}
+        style={{ "--os-rstack-gap": spacing(gap), "--os-rstack-align": align } as CSSProperties}
+      >
+        {children}
+      </div>
+    </div>
+  );
+}
+
+export interface ShowProps {
+  children: ReactNode;
+  /** Visible at this tier and wider. */
+  from?: Tier;
+  /** Visible below this tier. */
+  below?: Tier;
+  /** container reads the nearest ResponsiveContainer, GridSystem, or ResponsiveFrame. */
+  responsiveTo?: ResponsiveTo;
+}
+
+/** Renders children only inside a width range. Pure CSS — no layout flash. */
+export function Show({ children, from, below, responsiveTo = "container" }: ShowProps) {
+  const classes = [
+    "os-show",
+    `os-show-${responsiveTo}`,
+    from && `os-show-from-${from}`,
+    below && `os-show-below-${below}`,
+  ]
+    .filter(Boolean)
+    .join(" ");
+  return <div className={classes}>{children}</div>;
+}
+
+/** The inverse of Show: hidden inside the range. */
+export function Hide({ from, below, ...props }: ShowProps) {
+  return <Show {...props} from={below} below={from} />;
+}

package/src/components/ResponsiveFrame.tsx

@@ -0,0 +1,122 @@
+"use client";
+
+import { useRef, useState, type KeyboardEvent, type PointerEvent, type ReactNode } from "react";
+
+import { SegmentedControl, SegmentedControlItem } from "./Action";
+import { tierFor } from "./breakpoints";
+import { Text } from "./Primitives";
+import { useElementWidth } from "./Responsive";
+
+export interface FramePreset {
+  label: string;
+  /** px, or "fill" for the full available width. */
+  width: number | "fill";
+}
+
+export const FRAME_PRESETS: FramePreset[] = [
+  { label: "Phone", width: 360 },
+  { label: "Tablet", width: 640 },
+  { label: "Laptop", width: 880 },
+  { label: "Fill", width: "fill" },
+];
+
+const MIN_FRAME_WIDTH = 280;
+const KEY_STEP = 16;
+
+export interface ResponsiveFrameProps {
+  children: ReactNode;
+  presets?: FramePreset[];
+  /** Preset label to start on. */
+  defaultPreset?: string;
+  /** Accessible name for the frame. */
+  label?: string;
+}
+
+/**
+ * Shows content at a chosen width. Pick a device preset or drag the edge;
+ * everything inside measures this frame as its container, so GridSystem,
+ * ResponsiveStack, Show/Hide, and Astryx Grid all reflow live.
+ */
+export function ResponsiveFrame({
+  children,
+  presets = FRAME_PRESETS,
+  defaultPreset = "Fill",
+  label = "Responsive preview",
+}: ResponsiveFrameProps) {
+  const contentRef = useRef<HTMLDivElement>(null);
+  /** What children actually get — presets size the content box, not the chrome. */
+  const actual = useElementWidth(contentRef);
+  const initial = presets.find((p) => p.label === defaultPreset)?.width ?? "fill";
+  const [width, setWidth] = useState<number | "fill">(initial);
+  const drag = useRef<{ x: number; width: number } | null>(null);
+  const active = presets.find((p) => p.width === width)?.label ?? "";
+
+  function resizeTo(next: number) {
+    setWidth(Math.max(MIN_FRAME_WIDTH, Math.round(next)));
+  }
+
+  function onPointerDown(event: PointerEvent<HTMLDivElement>) {
+    event.currentTarget.setPointerCapture(event.pointerId);
+    drag.current = { x: event.clientX, width: actual };
+  }
+
+  function onPointerMove(event: PointerEvent<HTMLDivElement>) {
+    if (!drag.current) return;
+    resizeTo(drag.current.width + (event.clientX - drag.current.x));
+  }
+
+  function onKeyDown(event: KeyboardEvent<HTMLDivElement>) {
+    const delta = event.key === "ArrowRight" ? KEY_STEP : event.key === "ArrowLeft" ? -KEY_STEP : 0;
+    if (!delta) return;
+    event.preventDefault();
+    resizeTo(actual + delta);
+  }
+
+  return (
+    <div className="os-rframe">
+      <div className="os-rframe-bar">
+        <SegmentedControl
+          label="Preview width"
+          size="sm"
+          value={active}
+          onChange={(value) => setWidth(presets.find((p) => p.label === value)?.width ?? "fill")}
+        >
+          {presets.map((preset) => (
+            <SegmentedControlItem key={preset.label} value={preset.label} label={preset.label} />
+          ))}
+        </SegmentedControl>
+        <Text type="supporting" color="secondary" hasTabularNumbers>
+          {actual ? `${actual}px · ${tierFor(actual, "container")}` : ""}
+        </Text>
+      </div>
+      <div className="os-rframe-stage">
+        <div
+          className={width === "fill" ? "os-rframe-viewport os-rframe-fill" : "os-rframe-viewport"}
+          style={
+            width === "fill" ? undefined : { width: `calc(${width}px + 2 * var(--os-rframe-pad))` }
+          }
+          role="group"
+          aria-label={label}
+        >
+          <div ref={contentRef} className="os-rframe-content os-responsive-container">
+            {children}
+          </div>
+        </div>
+        <div
+          className="os-rframe-handle"
+          role="separator"
+          aria-orientation="vertical"
+          aria-label="Resize preview"
+          aria-valuenow={actual}
+          aria-valuemin={MIN_FRAME_WIDTH}
+          tabIndex={0}
+          onPointerDown={onPointerDown}
+          onPointerMove={onPointerMove}
+          onPointerUp={() => (drag.current = null)}
+          onPointerCancel={() => (drag.current = null)}
+          onKeyDown={onKeyDown}
+        />
+      </div>
+    </div>
+  );
+}

package/src/components/Segment.tsx

@@ -0,0 +1,190 @@
+"use client";
+
+import { useRef, useState, type KeyboardEvent, type ReactNode } from "react";
+
+const SEGMENT_SELECTOR = "[data-os-segment]";
+
+function siblings(from: HTMLElement) {
+  const root = from.closest(".os-segments");
+  return root ? Array.from(root.querySelectorAll<HTMLElement>(SEGMENT_SELECTOR)) : [from];
+}
+
+function focusSibling(from: HTMLElement, offset: 1 | -1) {
+  const list = siblings(from);
+  list[list.indexOf(from) + offset]?.focus();
+}
+
+export interface NumberSegmentProps {
+  value: number | null;
+  min: number;
+  max: number;
+  /** Digits shown, e.g. 2 for "09" or 4 for a year. */
+  digits: number;
+  placeholder: string;
+  label: string;
+  onChange: (value: number | null) => void;
+  /** Maps the stored value to what is shown, e.g. 13 → "01" on a 12-hour field. */
+  format?: (value: number) => string;
+  disabled?: boolean;
+}
+
+/**
+ * One typed part of a date or time. Digits fill it and hop to the next part;
+ * arrows step and wrap; Backspace clears, then moves back.
+ */
+export function NumberSegment({
+  value,
+  min,
+  max,
+  digits,
+  placeholder,
+  label,
+  onChange,
+  format,
+  disabled,
+}: NumberSegmentProps) {
+  // State drives what is shown; the ref is what handlers read, so fast typing
+  // and the blur that follows an auto-advance never see a stale buffer.
+  const [buffer, setBufferState] = useState("");
+  const bufferRef = useRef("");
+  function setBuffer(next: string) {
+    bufferRef.current = next;
+    setBufferState(next);
+  }
+
+  function step(delta: number) {
+    const span = max - min + 1;
+    const base = value ?? (delta > 0 ? min - 1 : max + 1);
+    onChange(((((base - min + delta + span) % span) + span) % span) + min);
+  }
+
+  function onKeyDown(event: KeyboardEvent<HTMLSpanElement>) {
+    const el = event.currentTarget;
+    if (event.key === "ArrowUp" || event.key === "ArrowDown") {
+      event.preventDefault();
+      setBuffer("");
+      step(event.key === "ArrowUp" ? 1 : -1);
+    } else if (event.key === "ArrowRight") {
+      event.preventDefault();
+      focusSibling(el, 1);
+    } else if (event.key === "ArrowLeft") {
+      event.preventDefault();
+      focusSibling(el, -1);
+    } else if (event.key === "Backspace" || event.key === "Delete") {
+      event.preventDefault();
+      if (bufferRef.current) setBuffer(bufferRef.current.slice(0, -1));
+      else if (value != null) onChange(null);
+      else focusSibling(el, -1);
+    } else if (/^\d$/.test(event.key)) {
+      event.preventDefault();
+      let next = bufferRef.current + event.key;
+      if (Number(next) > max) next = event.key;
+      const parsed = Number(next);
+      const complete = next.length >= digits || parsed * 10 > max;
+      if (complete) {
+        setBuffer("");
+        onChange(Math.min(Math.max(parsed, min), max));
+        focusSibling(el, 1);
+      } else {
+        setBuffer(next);
+      }
+    }
+  }
+
+  const shown = buffer
+    ? buffer.padStart(digits, "0")
+    : value == null
+      ? placeholder
+      : format
+        ? format(value)
+        : String(value).padStart(digits, "0");
+
+  return (
+    <span
+      data-os-segment=""
+      role="spinbutton"
+      tabIndex={disabled ? -1 : 0}
+      aria-label={label}
+      aria-valuemin={min}
+      aria-valuemax={max}
+      aria-valuenow={value ?? undefined}
+      aria-valuetext={value == null ? "Empty" : shown}
+      aria-disabled={disabled || undefined}
+      className={value == null && !buffer ? "os-segment os-segment-empty" : "os-segment"}
+      onKeyDown={disabled ? undefined : onKeyDown}
+      onBlur={() => {
+        const pending = bufferRef.current;
+        if (pending && Number(pending) >= min) onChange(Number(pending));
+        setBuffer("");
+      }}
+    >
+      {shown}
+    </span>
+  );
+}
+
+export interface ChoiceSegmentProps<T extends string> {
+  value: T | null;
+  options: readonly T[];
+  placeholder: string;
+  label: string;
+  onChange: (value: T) => void;
+  disabled?: boolean;
+}
+
+/** A typed part with a closed set — AM/PM. Type its first letter or step with arrows. */
+export function ChoiceSegment<T extends string>({
+  value,
+  options,
+  placeholder,
+  label,
+  onChange,
+  disabled,
+}: ChoiceSegmentProps<T>) {
+  function onKeyDown(event: KeyboardEvent<HTMLSpanElement>) {
+    const el = event.currentTarget;
+    const index = value == null ? -1 : options.indexOf(value);
+    if (event.key === "ArrowUp" || event.key === "ArrowDown") {
+      event.preventDefault();
+      const delta = event.key === "ArrowUp" ? 1 : -1;
+      onChange(options[(index + delta + options.length) % options.length]);
+    } else if (event.key === "ArrowRight") {
+      event.preventDefault();
+      focusSibling(el, 1);
+    } else if (event.key === "ArrowLeft" || event.key === "Backspace") {
+      event.preventDefault();
+      focusSibling(el, -1);
+    } else {
+      const hit = options.find((option) =>
+        option.toLowerCase().startsWith(event.key.toLowerCase()),
+      );
+      if (hit) {
+        event.preventDefault();
+        onChange(hit);
+      }
+    }
+  }
+
+  return (
+    <span
+      data-os-segment=""
+      role="spinbutton"
+      tabIndex={disabled ? -1 : 0}
+      aria-label={label}
+      aria-valuetext={value ?? "Empty"}
+      aria-disabled={disabled || undefined}
+      className={value == null ? "os-segment os-segment-empty" : "os-segment"}
+      onKeyDown={disabled ? undefined : onKeyDown}
+    >
+      {value ?? placeholder}
+    </span>
+  );
+}
+
+export function SegmentDivider({ children }: { children: ReactNode }) {
+  return (
+    <span className="os-segment-divider" aria-hidden>
+      {children}
+    </span>
+  );
+}

package/src/components/Sparkline.tsx

@@ -0,0 +1,52 @@
+"use client";
+
+import { useRef } from "react";
+
+import { areaPath, linePath, linearScale } from "./chartMath";
+import { useElementWidth } from "./Responsive";
+
+import type { ChartTone } from "./chartParts";
+
+const DEFAULT_HEIGHT = 36;
+/** Keeps the end dot and its ring inside the frame. */
+const INSET = 5;
+
+/**
+ * A small trend under a KpiWidget number: a 2px line with a light wash and the latest
+ * point marked. It has no axes; the figure above it carries the value.
+ */
+export function Sparkline({
+  values,
+  label,
+  tone = "blue",
+  height = DEFAULT_HEIGHT,
+}: {
+  values: number[];
+  /** Read to screen readers, e.g. "Applications per week, last 12 weeks". */
+  label: string;
+  tone?: ChartTone;
+  height?: number;
+}) {
+  const frame = useRef<HTMLDivElement>(null);
+  const width = useElementWidth(frame);
+  const max = Math.max(0, ...values);
+  const min = Math.min(max, ...values);
+  const x = linearScale([0, Math.max(1, values.length - 1)], [INSET, width - INSET]);
+  const y = linearScale([min, max === min ? min + 1 : max], [height - INSET, INSET]);
+  const points = values.map((value, index) => ({ x: x(index), y: y(value) }));
+  const last = points[points.length - 1];
+  const summary =
+    values.length > 0 ? `${label}: from ${values[0]} to ${values[values.length - 1]}` : label;
+
+  return (
+    <div ref={frame} className="os-sparkline" style={{ height }} role="img" aria-label={summary}>
+      {width > 0 && points.length > 0 ? (
+        <svg width={width} height={height} data-tone={tone} aria-hidden>
+          <path className="os-chart-area" d={areaPath(points, height)} />
+          <path className="os-chart-line" d={linePath(points)} />
+          <circle className="os-chart-dot" cx={last.x} cy={last.y} r={3.5} />
+        </svg>
+      ) : null}
+    </div>
+  );
+}

package/src/components/StateSelector.tsx

@@ -0,0 +1,39 @@
+"use client";
+
+import { Selector } from "./DataInput";
+import { US_STATES } from "./places";
+
+const OPTIONS = US_STATES.map((state) => ({
+  value: state.abbreviation,
+  label: state.name,
+  description: state.abbreviation,
+}));
+
+/** A searchable list of US states. The value is the postal abbreviation. */
+export function StateSelector({
+  label,
+  value,
+  onChange,
+  isLabelHidden,
+  isDisabled,
+}: {
+  label: string;
+  value: string;
+  onChange: (state: string) => void;
+  isLabelHidden?: boolean;
+  isDisabled?: boolean;
+}) {
+  return (
+    <Selector
+      label={label}
+      isLabelHidden={isLabelHidden}
+      options={OPTIONS}
+      value={value}
+      onChange={onChange}
+      hasSearch
+      searchPlaceholder="Search states"
+      placeholder="Select a state"
+      isDisabled={isDisabled}
+    />
+  );
+}

package/src/components/Sticky.tsx

@@ -0,0 +1,95 @@
+"use client";
+
+import {
+  useEffect,
+  useRef,
+  useState,
+  type CSSProperties,
+  type ReactNode,
+  type RefObject,
+} from "react";
+
+import { spacing, type SpacingStep } from "./breakpoints";
+
+const SCROLLABLE = /(auto|scroll|overlay)/;
+
+/** The nearest ancestor that scrolls vertically, or null for the window. */
+function scrollParent(el: HTMLElement | null): HTMLElement | null {
+  let node = el?.parentElement ?? null;
+  while (node && node !== document.body) {
+    if (SCROLLABLE.test(getComputedStyle(node).overflowY)) return node;
+    node = node.parentElement;
+  }
+  return null;
+}
+
+/**
+ * Visible height of whatever scrolls the sticky element — the window or a
+ * scroll container. The scroller is looked up again whenever layout changes,
+ * because a container's overflow style can arrive after the first render.
+ */
+function useScrollportHeight(ref: RefObject<HTMLElement | null>, enabled: boolean) {
+  const [height, setHeight] = useState<number | null>(null);
+  useEffect(() => {
+    const el = ref.current;
+    if (!enabled || !el) return;
+    let scroller: HTMLElement | null = null;
+    let frame = 0;
+    const observer = new ResizeObserver(() => measure());
+    function measure() {
+      const next = scrollParent(el);
+      if (next !== scroller) {
+        if (scroller) observer.unobserve(scroller);
+        if (next) observer.observe(next);
+        scroller = next;
+      }
+      setHeight(scroller ? scroller.clientHeight : window.innerHeight);
+    }
+    // A container can start scrolling without resizing (overflow flips from
+    // clip to auto), so re-check once per frame while anything scrolls.
+    const onScroll = () => {
+      cancelAnimationFrame(frame);
+      frame = requestAnimationFrame(measure);
+    };
+    if (el.parentElement) observer.observe(el.parentElement);
+    measure();
+    window.addEventListener("resize", measure);
+    document.addEventListener("scroll", onScroll, { capture: true, passive: true });
+    return () => {
+      cancelAnimationFrame(frame);
+      observer.disconnect();
+      window.removeEventListener("resize", measure);
+      document.removeEventListener("scroll", onScroll, { capture: true });
+    };
+  }, [ref, enabled]);
+  return height;
+}
+
+export interface StickyProps {
+  children: ReactNode;
+  /** Gap kept above the element while stuck — a spacing step. With `fill`, also kept below. */
+  offset?: SpacingStep;
+  /**
+   * Size the element to the visible scroll area, so a tall panel scrolls inside
+   * itself instead of running past the fold. Pair with Layout height="fill".
+   */
+  fill?: boolean;
+}
+
+/**
+ * Keeps a panel in view while its column scrolls — a detail pane beside a list,
+ * a summary beside a form. Works in the window or any scroll container.
+ */
+export function Sticky({ children, offset = 0, fill = false }: StickyProps) {
+  const ref = useRef<HTMLDivElement>(null);
+  const scrollport = useScrollportHeight(ref, fill);
+  const style = {
+    "--os-sticky-offset": spacing(offset),
+    ...(fill && scrollport ? { "--os-sticky-scrollport": `${scrollport}px` } : {}),
+  } as CSSProperties;
+  return (
+    <div ref={ref} className={fill ? "os-sticky os-sticky-fill" : "os-sticky"} style={style}>
+      {children}
+    </div>
+  );
+}