@signalcore/ui 0.1.0 → 1.0.0-beta.1

package/src/kit/Inputs.tsx

@@ -0,0 +1,250 @@
+import {
+  CheckIcon,
+  EnvelopeSimpleIcon,
+  EyeIcon,
+  EyeSlashIcon,
+  GlobeSimpleIcon,
+  LockSimpleIcon,
+  MinusIcon,
+  PhoneIcon,
+  PlusIcon,
+} from "@phosphor-icons/react";
+import { useLayoutEffect, useRef, useState, type ReactNode } from "react";
+
+import { useKit, useParts } from "./context";
+import { ariaOf, Box, type ControlBase } from "./Field";
+import { stepped, type NumberBounds } from "./numbers";
+
+interface WordsProps extends ControlBase {
+  value: string;
+  onChange: (value: string) => void;
+  placeholder?: string | undefined;
+}
+
+const SHAPES = {
+  text: { type: "text", inputMode: "text", autoComplete: undefined, icon: undefined },
+  email: { type: "email", inputMode: "email", autoComplete: "email", icon: EnvelopeSimpleIcon },
+  phone: { type: "tel", inputMode: "tel", autoComplete: "tel", icon: PhoneIcon },
+  url: { type: "url", inputMode: "url", autoComplete: "url", icon: GlobeSimpleIcon },
+} as const;
+
+/** Words on one line; an email, a phone or an address with its icon and the right keyboard. */
+export function TextInput({
+  kind = "text",
+  value,
+  onChange,
+  placeholder,
+  ...control
+}: WordsProps & { kind?: keyof typeof SHAPES | undefined }) {
+  const part = useParts();
+  const shape = SHAPES[kind];
+  return (
+    <Box icon={shape.icon} invalid={control.invalid}>
+      <input
+        id={control.id}
+        type={shape.type}
+        inputMode={shape.inputMode}
+        autoComplete={shape.autoComplete}
+        spellCheck={kind === "text" ? undefined : false}
+        placeholder={placeholder}
+        value={value}
+        disabled={control.disabled}
+        onChange={(event) => onChange(event.target.value)}
+        className={part("sc-control__input")}
+        {...ariaOf(control)}
+      />
+    </Box>
+  );
+}
+
+/** Words over a few lines: the box grows with them up to a height, then scrolls. */
+export function TextArea({ value, onChange, placeholder, ...control }: WordsProps) {
+  const part = useParts();
+  const box = useRef<HTMLTextAreaElement>(null);
+  useLayoutEffect(() => {
+    const element = box.current;
+    if (!element) return;
+    element.style.height = "auto";
+    element.style.height = `${element.scrollHeight}px`;
+  }, [value]);
+  return (
+    <Box invalid={control.invalid}>
+      <textarea
+        ref={box}
+        id={control.id}
+        rows={3}
+        placeholder={placeholder}
+        value={value}
+        disabled={control.disabled}
+        onChange={(event) => onChange(event.target.value)}
+        className={part("sc-control__input")}
+        {...ariaOf(control)}
+      />
+    </Box>
+  );
+}
+
+/** A number: typed, or a step at a time with − and + (or the arrows), its unit after it. */
+export function NumberInput({
+  value,
+  onChange,
+  placeholder,
+  min,
+  max,
+  step,
+  unit,
+  ...control
+}: ControlBase &
+  NumberBounds & {
+    value: number | null;
+    onChange: (value: number | null) => void;
+    placeholder?: string | undefined;
+    unit?: string | undefined;
+  }) {
+  const { messages } = useKit();
+  const part = useParts();
+  const move = (direction: 1 | -1) => onChange(stepped({ min, max, step }, value, direction));
+  const atLeast = value !== null && min !== undefined && value <= min;
+  const atMost = value !== null && max !== undefined && value >= max;
+  return (
+    <Box
+      invalid={control.invalid}
+      end={
+        <>
+          {unit !== undefined && (
+            <span aria-hidden className={part("sc-control__unit")}>
+              {unit}
+            </span>
+          )}
+          <span className={part("sc-control__steppers")}>
+            <Stepper
+              label={messages.decrease}
+              off={control.disabled || atLeast}
+              onPress={() => move(-1)}
+            >
+              <MinusIcon aria-hidden />
+            </Stepper>
+            <Stepper
+              label={messages.increase}
+              off={control.disabled || atMost}
+              onPress={() => move(1)}
+            >
+              <PlusIcon aria-hidden />
+            </Stepper>
+          </span>
+        </>
+      }
+    >
+      <input
+        id={control.id}
+        type="number"
+        inputMode="decimal"
+        min={min}
+        max={max}
+        step={step ?? "any"}
+        placeholder={placeholder}
+        value={value ?? ""}
+        disabled={control.disabled}
+        onChange={(event) => {
+          const typed = event.target.value;
+          onChange(typed === "" ? null : Number(typed));
+        }}
+        onKeyDown={(event) => {
+          // The arrows step as the buttons do: within the bounds, on the step's decimals.
+          if (event.key !== "ArrowUp" && event.key !== "ArrowDown") return;
+          event.preventDefault();
+          move(event.key === "ArrowUp" ? 1 : -1);
+        }}
+        className={part("sc-control__input")}
+        {...ariaOf(control)}
+      />
+    </Box>
+  );
+}
+
+/** A stepper is for the pointer; the keyboard has the arrows, so it takes no tab stop. */
+function Stepper({
+  label,
+  off,
+  onPress,
+  children,
+}: {
+  label: string;
+  off: boolean | undefined;
+  onPress: () => void;
+  children: ReactNode;
+}) {
+  return (
+    <button type="button" tabIndex={-1} aria-label={label} disabled={off} onClick={onPress}>
+      {children}
+    </button>
+  );
+}
+
+/** A value typed once and never shown again: hidden as it is typed, unless the person asks. */
+export function SecretInput({ value, onChange, placeholder, ...control }: WordsProps) {
+  const { messages } = useKit();
+  const part = useParts();
+  const [shown, setShown] = useState(false);
+  return (
+    <Box
+      icon={LockSimpleIcon}
+      invalid={control.invalid}
+      end={
+        <button
+          type="button"
+          aria-label={shown ? messages.hide : messages.show}
+          aria-pressed={shown}
+          aria-controls={control.id}
+          disabled={control.disabled}
+          onClick={() => setShown((now) => !now)}
+          className={part("sc-control__reveal")}
+        >
+          {shown ? <EyeSlashIcon aria-hidden /> : <EyeIcon aria-hidden />}
+        </button>
+      }
+    >
+      <input
+        id={control.id}
+        type={shown ? "text" : "password"}
+        autoComplete="off"
+        autoCapitalize="off"
+        spellCheck={false}
+        placeholder={placeholder}
+        value={value}
+        disabled={control.disabled}
+        onChange={(event) => onChange(event.target.value)}
+        className={part("sc-control__input")}
+        {...ariaOf(control)}
+      />
+    </Box>
+  );
+}
+
+/** A box to tick, the sentence beside it its label; drawn in the accent once ticked. */
+export function Checkbox({
+  value,
+  onChange,
+  children,
+  ...control
+}: Omit<ControlBase, "labelledBy" | "label"> & {
+  value: boolean;
+  onChange: (value: boolean) => void;
+  children: ReactNode;
+}) {
+  const part = useParts();
+  return (
+    <label className={part("sc-check")}>
+      <input
+        id={control.id}
+        type="checkbox"
+        checked={value}
+        disabled={control.disabled}
+        onChange={(event) => onChange(event.target.checked)}
+        {...ariaOf(control)}
+      />
+      <CheckIcon aria-hidden weight="bold" />
+      <span>{children}</span>
+    </label>
+  );
+}

package/src/kit/List.tsx

@@ -0,0 +1,135 @@
+import { CaretRightIcon, CheckIcon } from "@phosphor-icons/react";
+import type { MouseEvent, ReactNode } from "react";
+
+import { joined, useParts } from "./context";
+
+/**
+ * Rows in one hairline box, a hairline between each, like a group of settings: a list of
+ * things, of automations, of an agent's files.
+ */
+export function List({
+  label,
+  className,
+  children,
+}: {
+  /** The list's name, for screen readers, when no heading above it says it. */
+  label?: string | undefined;
+  className?: string | undefined;
+  children: ReactNode;
+}) {
+  const part = useParts();
+  return (
+    <ul aria-label={label} part="list" className={joined(part("sc-list"), className)}>
+      {children}
+    </ul>
+  );
+}
+
+export interface RowProps {
+  /** At its start, usually a `Mark`: what kind of thing it is. */
+  mark?: ReactNode;
+  /** What it is, up to two lines. */
+  title: ReactNode;
+  /** A quieter line under it: when it runs, a detail. */
+  subtitle?: ReactNode;
+  /** What went wrong with it, under the rest in the danger tone: why a run failed. */
+  error?: ReactNode;
+  /** At its right, quiet, in figures that line up: a price, a time, a count. */
+  meta?: ReactNode;
+  /** The host's controls at its end, apart from the row's own press: a switch, a ⋯ menu. */
+  trailing?: ReactNode;
+  /** Pressing the row: it lights under the pointer and carries a caret. */
+  onPress?: (() => void) | undefined;
+  /**
+   * Where the row goes: it is a link to that page, which can be opened apart too. With
+   * `onPress`, a plain click calls it instead, so the host's router takes it there.
+   */
+  href?: string | undefined;
+  /** It is the one picked: a check in the caret's place, on a breath of the accent. */
+  pressed?: boolean | undefined;
+  disabled?: boolean | undefined;
+  /** Kept in its place, quieter: something paused. */
+  quiet?: boolean | undefined;
+  className?: string | undefined;
+}
+
+/** A click that means "go here", not "open it apart" (a modifier, another button). */
+const plain = (event: MouseEvent): boolean =>
+  !event.defaultPrevented &&
+  event.button === 0 &&
+  !(event.metaKey || event.ctrlKey || event.shiftKey || event.altKey);
+
+/**
+ * One row of a `List`: its mark, its title over a quieter line (and what went wrong, when
+ * something did), a detail at the right, the host's controls at its end. With `href` the row
+ * (but not its controls) is a link; with only `onPress`, a button.
+ */
+export function Row({
+  mark,
+  title,
+  subtitle,
+  error,
+  meta,
+  trailing,
+  onPress,
+  href,
+  pressed,
+  disabled,
+  quiet,
+  className,
+}: RowProps) {
+  const part = useParts();
+  const body = (
+    <>
+      {mark}
+      <span className={part("sc-row__text")}>
+        <span className={part("sc-row__title")}>{title}</span>
+        {subtitle !== undefined && <span className={part("sc-row__subtitle")}>{subtitle}</span>}
+        {error !== undefined && <span className={part("sc-row__error")}>{error}</span>}
+      </span>
+      {meta !== undefined && <span className={part("sc-row__meta")}>{meta}</span>}
+    </>
+  );
+  return (
+    <li
+      part="row"
+      className={joined(
+        part(
+          "sc-row",
+          ...(quiet ? (["sc-row--quiet"] as const) : []),
+          ...(pressed ? (["sc-row--pressed"] as const) : []),
+        ),
+        className,
+      )}
+    >
+      {href !== undefined ? (
+        <a
+          href={href}
+          onClick={(event) => {
+            if (!onPress || !plain(event)) return;
+            event.preventDefault();
+            onPress();
+          }}
+          className={part("sc-row__main")}
+        >
+          {body}
+          <CaretRightIcon aria-hidden />
+        </a>
+      ) : onPress ? (
+        <button
+          type="button"
+          disabled={disabled}
+          aria-pressed={pressed || undefined}
+          onClick={onPress}
+          className={part("sc-row__main")}
+        >
+          {body}
+          {pressed ? <CheckIcon aria-hidden weight="bold" /> : <CaretRightIcon aria-hidden />}
+        </button>
+      ) : (
+        <div className={part("sc-row__main")}>{body}</div>
+      )}
+      {trailing !== undefined && <div className={part("sc-row__trailing")}>{trailing}</div>}
+    </li>
+  );
+}

package/src/kit/Mark.tsx

@@ -0,0 +1,64 @@
+import type { Icon } from "@phosphor-icons/react";
+import type { CSSProperties, ReactNode } from "react";
+
+import { joined, useParts } from "./context";
+
+export interface MarkProps {
+  /** A glyph, alone, in the muted ink: what kind of thing it is. */
+  icon?: Icon | undefined;
+  /** A picture instead: an app's logo, as it comes (a square one with its own ground, its corners
+   * softened). */
+  src?: string | undefined;
+  /** The picture is a photo that fills the mark, not a logo inside it. */
+  photo?: boolean | undefined;
+  /** What it holds is a logo (drawn by the host, as `children`): a picture in it is sized and
+   * cornered as `src`'s. */
+  logo?: boolean | undefined;
+  /** It stands for a person: their photo round, where a thing's is square. */
+  round?: boolean | undefined;
+  /** The host's own drawing, in place of `icon` or `src`: a glyph, a logo, an initial. */
+  children?: ReactNode;
+  /** The side it keeps in its row, in pixels: 28 by default. */
+  size?: number | undefined;
+  className?: string | undefined;
+}
+
+/**
+ * What kind of thing a row is, at its start, bare: a glyph in the muted ink, an app's logo as it
+ * comes, an initial, or a photo (round for a person). Nothing is drawn behind it; it keeps its
+ * square so rows line up. It only shows, so it is hidden from screen readers.
+ */
+export function Mark({
+  icon: Glyph,
+  src,
+  photo,
+  logo,
+  round,
+  size = 28,
+  className,
+  children,
+}: MarkProps) {
+  const part = useParts();
+  const kind = [
+    ...(src === undefined && !logo
+      ? []
+      : photo
+        ? (["sc-mark--photo"] as const)
+        : (["sc-mark--logo"] as const)),
+    ...(round ? (["sc-mark--round"] as const) : []),
+  ];
+  return (
+    <span
+      aria-hidden
+      style={{ "--_mark": `${size}px` } as CSSProperties}
+      className={joined(part("sc-mark", ...kind), className)}
+    >
+      {children ??
+        (src !== undefined ? (
+          <img src={src} alt="" loading="lazy" referrerPolicy="no-referrer" />
+        ) : (
+          Glyph && <Glyph weight="regular" />
+        ))}
+    </span>
+  );
+}

package/src/kit/MarkStack.tsx

@@ -0,0 +1,29 @@
+import { Children, type ReactNode } from "react";
+
+import { joined, useParts } from "./context";
+
+/**
+ * A few marks side by side, a little apart, and how many more after them: an agent's apps, its
+ * channels' kinds. Like a mark, it only shows, so screen readers skip it.
+ */
+export function MarkStack({
+  more = 0,
+  className,
+  children,
+}: {
+  /** How many are not drawn: "+3" after the last. */
+  more?: number | undefined;
+  className?: string | undefined;
+  /** The marks, usually small `Mark`s or a host's logos. */
+  children: ReactNode;
+}) {
+  const part = useParts();
+  return (
+    <span aria-hidden className={joined(part("sc-stack"), className)}>
+      {Children.map(children, (mark) => (
+        <span className={part("sc-stack__item")}>{mark}</span>
+      ))}
+      {more > 0 && <span className={part("sc-stack__more")}>+{more}</span>}
+    </span>
+  );
+}

package/src/kit/Note.tsx

@@ -0,0 +1,42 @@
+import {
+  CheckCircleIcon,
+  InfoIcon,
+  WarningCircleIcon,
+  WarningIcon,
+  type Icon,
+} from "@phosphor-icons/react";
+import type { ReactNode } from "react";
+
+import { joined, useParts } from "./context";
+import type { Tone } from "./Stat";
+
+const MARKS: Readonly<Record<Tone, Icon>> = {
+  info: InfoIcon,
+  success: CheckCircleIcon,
+  warning: WarningIcon,
+  danger: WarningCircleIcon,
+};
+
+/** A line that stands out: its tone's mark and the words on a wash of it, edged by it. */
+export function Note({
+  tone,
+  className,
+  children,
+}: {
+  tone: Tone;
+  className?: string | undefined;
+  children: ReactNode;
+}) {
+  const part = useParts();
+  const Mark = MARKS[tone];
+  return (
+    <div
+      role="note"
+      part={`note note-${tone}`}
+      className={joined(part("sc-note", `sc-note--${tone}`), className)}
+    >
+      <Mark aria-hidden weight="fill" />
+      <div className={part("sc-note__body")}>{children}</div>
+    </div>
+  );
+}

package/src/kit/Popover.tsx

@@ -0,0 +1,121 @@
+import {
+  autoUpdate,
+  flip,
+  FloatingFocusManager,
+  FloatingPortal,
+  offset,
+  shift,
+  size,
+  useDismiss,
+  useFloating,
+  useInteractions,
+  useRole,
+} from "@floating-ui/react";
+import type { ReactNode } from "react";
+
+import { useParts } from "./context";
+
+/** The least height a panel keeps, flipping above its trigger before it shrinks under this. */
+const LEAST = 180;
+
+/**
+ * A panel that floats by its trigger: under it, flipped above when there is no room, kept in the
+ * window, as tall as fits; Escape or a press outside closes it. `width` "trigger" makes it as
+ * wide as its trigger (a list), "own" leaves it its own (a calendar). `role` is the panel's for
+ * a dialog; a combobox words its own.
+ */
+export function usePopover(
+  open: boolean,
+  setOpen: (open: boolean) => void,
+  { width, role }: { width: "trigger" | "own"; role?: "dialog" },
+) {
+  const floating = useFloating({
+    open,
+    onOpenChange: setOpen,
+    placement: "bottom-start",
+    // Placed by its offsets, so its opening can move it with a transform of its own.
+    transform: false,
+    whileElementsMounted: autoUpdate,
+    middleware: [
+      offset(6),
+      flip({ padding: 8, fallbackStrategy: "initialPlacement" }),
+      shift({ padding: 8 }),
+      size({
+        padding: 8,
+        apply({ rects, availableHeight, elements }) {
+          elements.floating.style.maxHeight = `${Math.max(LEAST, availableHeight)}px`;
+          if (width === "trigger") elements.floating.style.width = `${rects.reference.width}px`;
+        },
+      }),
+    ],
+  });
+  const dismiss = useDismiss(floating.context);
+  const dialog = useRole(floating.context, { role: "dialog", enabled: role === "dialog" });
+  const interactions = useInteractions([dismiss, dialog]);
+  return { ...floating, ...interactions };
+}
+
+export type PopoverState = ReturnType<typeof usePopover>;
+
+/**
+ * Where the panel goes instead of the page's end: the host's dialog the trigger sits in (a modal
+ * one keeps the pointer and the focus inside itself), or the element the host marked
+ * `data-sc-portal` around it (a shadow root's, whose styles stop at its edge: the widget's).
+ * None is `undefined`, the page's end: floating-ui reads a `null` root as one still to come, and
+ * draws nothing until it does.
+ */
+const layerOf = (trigger: Element | null): HTMLElement | undefined =>
+  trigger?.closest<HTMLElement>(
+    '[role="dialog"], [role="alertdialog"], dialog, [data-sc-portal]',
+  ) ?? undefined;
+
+/**
+ * The panel itself, in a portal at the page's end so nothing clips it (inside the host's dialog
+ * or `data-sc-portal`, when the trigger is in one); it carries `sc`, so the host's tokens reach
+ * it there. With `focus` it takes the focus while open (a calendar, which puts it on a day) and
+ * gives it back to the trigger on close; tabbing out closes it. Without, focus stays where it is
+ * (a combobox's box).
+ */
+export function Popover({
+  popover,
+  focus,
+  label,
+  children,
+}: {
+  popover: PopoverState;
+  focus: boolean;
+  label?: string | undefined;
+  children: ReactNode;
+}) {
+  const part = useParts();
+  const panel = (
+    <div
+      ref={popover.refs.setFloating}
+      style={popover.floatingStyles}
+      aria-label={label}
+      {...popover.getFloatingProps({
+        // Escape closes the panel and goes no further: not the page's own Escape, not the chat's.
+        onKeyDown: (event) => {
+          if (event.key !== "Escape") return;
+          event.preventDefault();
+          event.stopPropagation();
+          popover.context.onOpenChange(false);
+        },
+      })}
+      className={`sc ${part("sc-popover")}`}
+    >
+      {children}
+    </div>
+  );
+  return (
+    <FloatingPortal root={layerOf(popover.refs.domReference.current)}>
+      {focus ? (
+        <FloatingFocusManager context={popover.context} initialFocus={-1} modal={false}>
+          {panel}
+        </FloatingFocusManager>
+      ) : (
+        panel
+      )}
+    </FloatingPortal>
+  );
+}

package/src/kit/RangeField.tsx

@@ -0,0 +1,53 @@
+import type { CSSProperties } from "react";
+
+import { useKit, useParts } from "./context";
+import { ariaOf, type ControlBase } from "./Field";
+import { formatNumber, withUnit, type NumberBounds } from "./numbers";
+
+/**
+ * A number on a slider between its least and its most: the value rides over the thumb in a
+ * bubble, with its unit, and the two ends sit under the track.
+ */
+export function RangeField({
+  value,
+  onChange,
+  min = 0,
+  max = 100,
+  step,
+  unit,
+  ...control
+}: ControlBase &
+  NumberBounds & {
+    value: number;
+    onChange: (value: number) => void;
+    unit?: string | undefined;
+  }) {
+  const { code } = useKit();
+  const part = useParts();
+  const share = max > min ? (Math.min(max, Math.max(min, value)) - min) / (max - min) : 0;
+  const said = withUnit(formatNumber(value, code), unit);
+  return (
+    <div className={part("sc-range")} style={{ "--_share": share } as CSSProperties}>
+      <output htmlFor={control.id} aria-hidden>
+        {said}
+      </output>
+      <input
+        id={control.id}
+        type="range"
+        min={min}
+        max={max}
+        step={step ?? 1}
+        value={value}
+        disabled={control.disabled}
+        onChange={(event) => onChange(Number(event.target.value))}
+        aria-valuetext={said}
+        {...ariaOf(control)}
+        aria-required={undefined}
+      />
+      <span aria-hidden>
+        <span>{withUnit(formatNumber(min, code), unit)}</span>
+        <span>{withUnit(formatNumber(max, code), unit)}</span>
+      </span>
+    </div>
+  );
+}