@signalcore/ui 0.1.0 → 1.0.0-beta.0

package/src/kit/Combobox.tsx

@@ -0,0 +1,247 @@
+import { CaretUpDownIcon, CheckIcon, XIcon, type Icon } from "@phosphor-icons/react";
+import { useId, useLayoutEffect, useRef, useState, type KeyboardEvent } from "react";
+
+import { useKit, useParts } from "./context";
+import { ariaOf, type ControlBase } from "./Field";
+import { matches, type Option } from "./options";
+import { Popover, usePopover } from "./Popover";
+
+export interface ComboboxProps extends ControlBase {
+  options: Option[];
+  /** The ids picked: one at most, unless `multiple`. */
+  value: string[];
+  multiple: boolean;
+  onChange: (ids: string[]) => void;
+  /** An option from words that match none, such as a time typed "21:15"; null when they make none. */
+  typed?: ((text: string) => Option | null) | undefined;
+  /** The option the list opens on while nothing is picked. */
+  start?: string | undefined;
+  placeholder: string;
+  icon?: Icon | undefined;
+}
+
+/**
+ * A long list to pick from, as the ARIA combobox: the person types to narrow it, the arrows walk
+ * it, Enter picks, Escape closes; focus stays in the box. One picked reads in the box; several
+ * sit in it as tags (Backspace takes the last). Words that match nothing can still make an
+ * option (`typed`): a time not on the half hours.
+ */
+export function Combobox({
+  options,
+  value,
+  multiple,
+  onChange,
+  typed,
+  start,
+  placeholder,
+  icon: Leading,
+  ...control
+}: ComboboxProps) {
+  const { id, invalid, disabled } = control;
+  const aria = ariaOf(control);
+  const { messages } = useKit();
+  const part = useParts();
+  const listId = useId();
+  const box = useRef<HTMLInputElement>(null);
+  // The list as it is on the page: the portal puts it there a render after it opens.
+  const [list, setList] = useState<HTMLUListElement | null>(null);
+  const centered = useRef<HTMLUListElement | null>(null);
+  // What the person typed, while they type; null shows what is picked.
+  const [query, setQuery] = useState<string | null>(null);
+  const [open, setOpen] = useState(false);
+  const [active, setActive] = useState(-1);
+  const close = () => {
+    setOpen(false);
+    setQuery(null);
+  };
+  const popover = usePopover(open, (next) => (next ? setOpen(true) : close()), {
+    width: "trigger",
+  });
+
+  const picked = value.map((id) => options.find((option) => option.id === id) ?? { id, label: id });
+  const found = query === null ? options : options.filter((option) => matches(option, query));
+  const made = query !== null && found.length === 0 ? (typed?.(query) ?? null) : null;
+  const shown = made ? [made] : found;
+
+  const show = () => {
+    const first = value[0] ?? start;
+    setActive(
+      Math.max(
+        0,
+        options.findIndex((option) => option.id === first),
+      ),
+    );
+    setOpen(true);
+  };
+
+  const pick = (option: Option) => {
+    setQuery(null);
+    if (!multiple) {
+      onChange([option.id]);
+      setOpen(false);
+    } else {
+      onChange(
+        value.includes(option.id) ? value.filter((id) => id !== option.id) : [...value, option.id],
+      );
+    }
+  };
+
+  // Leaving the box keeps a time typed whole, and an emptied box clears the pick.
+  const leave = () => {
+    if (query !== null && !multiple) {
+      const kept = query.trim() === "" ? null : (typed?.(query) ?? undefined);
+      if (kept === null) onChange([]);
+      else if (kept !== undefined) onChange([kept.id]);
+    }
+    close();
+  };
+
+  const onKeyDown = (event: KeyboardEvent<HTMLInputElement>) => {
+    switch (event.key) {
+      case "ArrowDown":
+      case "ArrowUp": {
+        event.preventDefault();
+        if (!open) return show();
+        const move = event.key === "ArrowDown" ? 1 : -1;
+        setActive((at) => (shown.length === 0 ? -1 : (at + move + shown.length) % shown.length));
+        return;
+      }
+      case "Enter": {
+        if (!open) return;
+        event.preventDefault();
+        const option = shown[active];
+        if (option) pick(option);
+        return;
+      }
+      case "Escape":
+        // An open list takes its Escape: the page and the chat don't see it.
+        if (open) {
+          event.preventDefault();
+          event.stopPropagation();
+          close();
+        }
+        return;
+      case "Backspace":
+        if (multiple && !query && value.length > 0) onChange(value.slice(0, -1));
+    }
+  };
+
+  // The one under the arrows stays in sight; as the list appears, it sits in the middle.
+  useLayoutEffect(() => {
+    const item = list?.children[active];
+    if (!list || !(item instanceof HTMLElement)) return;
+    reveal(list, item, centered.current !== list);
+    centered.current = list;
+  }, [active, list]);
+
+  return (
+    <>
+      <div
+        ref={popover.refs.setReference}
+        {...popover.getReferenceProps()}
+        onClick={() => box.current?.focus()}
+        data-invalid={invalid || undefined}
+        part="control"
+        className={part("sc-control")}
+      >
+        {Leading && <Leading aria-hidden />}
+        {multiple &&
+          picked.map((option) => (
+            <span key={option.id} className={part("sc-control__tag")}>
+              {option.label}
+              <button
+                type="button"
+                tabIndex={-1}
+                aria-label={messages.remove(option.label)}
+                disabled={disabled}
+                onClick={(event) => {
+                  event.stopPropagation();
+                  onChange(value.filter((id) => id !== option.id));
+                }}
+              >
+                <XIcon aria-hidden />
+              </button>
+            </span>
+          ))}
+        <input
+          ref={box}
+          id={id}
+          role="combobox"
+          aria-expanded={open}
+          aria-controls={open ? listId : undefined}
+          aria-autocomplete="list"
+          aria-activedescendant={open && shown[active] ? `${listId}-${active}` : undefined}
+          {...aria}
+          autoComplete="off"
+          spellCheck={false}
+          placeholder={multiple && value.length > 0 ? "" : open ? messages.search : placeholder}
+          value={query ?? (multiple ? "" : (picked[0]?.label ?? ""))}
+          disabled={disabled}
+          onFocus={(event) => event.target.select()}
+          onClick={() => {
+            if (!open) show();
+          }}
+          onChange={(event) => {
+            setQuery(event.target.value);
+            setActive(0);
+            setOpen(true);
+          }}
+          onKeyDown={onKeyDown}
+          onBlur={leave}
+          className={part("sc-control__input")}
+        />
+        <CaretUpDownIcon aria-hidden />
+      </div>
+      {open && (
+        <Popover popover={popover} focus={false}>
+          {/* A press in the list keeps the focus in the box. */}
+          <div onMouseDown={(event) => event.preventDefault()}>
+            {shown.length === 0 ? (
+              <p className={part("sc-listbox__empty")}>{messages.noResults}</p>
+            ) : (
+              <ul
+                ref={setList}
+                id={listId}
+                role="listbox"
+                aria-labelledby={aria["aria-labelledby"]}
+                aria-multiselectable={multiple || undefined}
+                className={part("sc-listbox")}
+              >
+                {shown.map((option, index) => {
+                  const selected = value.includes(option.id);
+                  return (
+                    <li
+                      key={option.id}
+                      id={`${listId}-${index}`}
+                      role="option"
+                      aria-selected={selected}
+                      data-active={index === active || undefined}
+                      onMouseMove={() => setActive(index)}
+                      onClick={() => pick(option)}
+                      className={part("sc-listbox__item")}
+                    >
+                      <span>
+                        {option.label}
+                        {option.hint !== undefined && <small>{option.hint}</small>}
+                      </span>
+                      {selected && <CheckIcon aria-hidden weight="bold" />}
+                    </li>
+                  );
+                })}
+              </ul>
+            )}
+          </div>
+        </Popover>
+      )}
+    </>
+  );
+}
+
+/** Scrolls a list so the item shows: just enough, or with it in the middle. */
+function reveal(list: HTMLElement, item: HTMLElement, middle: boolean) {
+  const top = item.offsetTop;
+  const bottom = top + item.offsetHeight;
+  if (middle) list.scrollTop = top - (list.clientHeight - item.offsetHeight) / 2;
+  else if (top < list.scrollTop) list.scrollTop = top;
+  else if (bottom > list.scrollTop + list.clientHeight) list.scrollTop = bottom - list.clientHeight;
+}

package/src/kit/DateField.tsx

@@ -0,0 +1,156 @@
+import {
+  CalendarBlankIcon,
+  CaretDownIcon,
+  CaretLeftIcon,
+  CaretRightIcon,
+} from "@phosphor-icons/react";
+import { useState } from "react";
+import { DayPicker, type ChevronProps, type ClassNames } from "react-day-picker";
+
+import { useKit, useParts } from "./context";
+import { dayAllowed, dayOf, daySpan, formatDay, isoDay, openingDay, type DayBounds } from "./dates";
+import { ariaOf, type ControlBase } from "./Field";
+import { Popover, usePopover } from "./Popover";
+
+/** The calendar's parts, under the kit's names: the host's look reaches them by token. */
+const CALENDAR: Partial<ClassNames> = {
+  months: "sc-calendar__months",
+  month: "sc-calendar__month",
+  month_caption: "sc-calendar__caption",
+  caption_label: "sc-calendar__title",
+  nav: "sc-calendar__nav",
+  button_previous: "sc-calendar__step",
+  button_next: "sc-calendar__step",
+  chevron: "sc-calendar__chevron",
+  month_grid: "sc-calendar__grid",
+  weekdays: "sc-calendar__weekdays",
+  weekday: "sc-calendar__weekday",
+  weeks: "sc-calendar__weeks",
+  week: "sc-calendar__week",
+  day: "sc-calendar__day",
+  day_button: "sc-calendar__button",
+  selected: "sc-calendar__day--selected",
+  today: "sc-calendar__day--today",
+  disabled: "sc-calendar__day--disabled",
+  outside: "sc-calendar__day--outside",
+  hidden: "sc-calendar__day--hidden",
+  focused: "sc-calendar__day--focused",
+};
+
+export interface DateFieldProps extends ControlBase, DayBounds {
+  /** The day picked, "YYYY-MM-DD", or none. */
+  value: string | null;
+  onChange: (day: string) => void;
+  placeholder?: string | undefined;
+}
+
+/**
+ * A day: a button that reads the day picked in the host's language and opens a calendar under
+ * it. Only the days offered can be picked (`dates`, between `earliest` and `latest`), and when
+ * they are bounded, those stand out. Picking one closes it and gives the focus back.
+ */
+export function DateField({
+  value,
+  onChange,
+  placeholder,
+  dates,
+  earliest,
+  latest,
+  ...control
+}: DateFieldProps) {
+  const { code, messages } = useKit();
+  const part = useParts();
+  const [open, setOpen] = useState(false);
+  const popover = usePopover(open, setOpen, { width: "own", role: "dialog" });
+  const picked = value !== null && dayOf(value) ? value : null;
+  const { id, labelledBy } = control;
+  return (
+    <>
+      <button
+        ref={popover.refs.setReference}
+        id={id}
+        type="button"
+        disabled={control.disabled}
+        data-invalid={control.invalid || undefined}
+        data-empty={picked === null || undefined}
+        {...popover.getReferenceProps({ onClick: () => setOpen(!open) })}
+        {...ariaOf(control)}
+        // Its name is its label and the day it reads.
+        aria-labelledby={
+          labelledBy === undefined || id === undefined ? labelledBy : `${labelledBy} ${id}`
+        }
+        aria-required={undefined}
+        part="control"
+        className={part("sc-control", "sc-control--trigger")}
+      >
+        <CalendarBlankIcon aria-hidden />
+        <span>{picked ? formatDay(picked, code) : (placeholder ?? messages.chooseDate)}</span>
+        <CaretDownIcon aria-hidden />
+      </button>
+      {open && (
+        <Popover popover={popover} focus label={messages.chooseDate}>
+          <Calendar
+            bounds={{ dates, earliest, latest }}
+            picked={picked}
+            onPick={(day) => {
+              onChange(day);
+              setOpen(false);
+            }}
+          />
+        </Popover>
+      )}
+    </>
+  );
+}
+
+/**
+ * The month grid, react-day-picker in the kit's look: it opens on the day picked, else the
+ * first offered; it goes no further than the bounds; the arrows walk the days, Page Up and Down
+ * the months.
+ */
+function Calendar({
+  bounds,
+  picked,
+  onPick,
+}: {
+  bounds: DayBounds;
+  picked: string | null;
+  onPick: (day: string) => void;
+}) {
+  const { locale } = useKit();
+  const part = useParts();
+  const today = new Date();
+  const { first, last } = daySpan(bounds);
+  const start = first !== undefined ? dayOf(first) : null;
+  const end = last !== undefined ? dayOf(last) : null;
+  const offered = (date: Date) => dayAllowed(bounds, isoDay(date));
+  return (
+    <DayPicker
+      mode="single"
+      selected={(picked && dayOf(picked)) || undefined}
+      onSelect={(date) => {
+        if (date) onPick(isoDay(date));
+      }}
+      defaultMonth={dayOf(openingDay(bounds, picked, today)) ?? today}
+      {...(start && { startMonth: start })}
+      {...(end && { endMonth: end })}
+      disabled={(date) => !offered(date)}
+      modifiers={start !== null || end !== null ? { offered } : {}}
+      modifiersClassNames={{ offered: "sc-calendar__day--offered" }}
+      {...(locale && { locale })}
+      navLayout="after"
+      showOutsideDays
+      autoFocus
+      classNames={{ ...CALENDAR, root: part("sc-calendar") }}
+      components={{ Chevron }}
+    />
+  );
+}
+
+function Chevron({ orientation }: ChevronProps) {
+  return orientation === "left" ? (
+    <CaretLeftIcon aria-hidden weight="bold" />
+  ) : (
+    <CaretRightIcon aria-hidden weight="bold" />
+  );
+}

package/src/kit/Field.tsx

@@ -0,0 +1,137 @@
+import { WarningCircleIcon, type Icon } from "@phosphor-icons/react";
+import { useId, type ReactNode } from "react";
+
+import { joined, useKit, useParts } from "./context";
+
+/** What names a control and ties it to its field: the ids its label, help and error carry. */
+export interface ControlBase {
+  id?: string | undefined;
+  /** Its label's id; without one, `label` names it. */
+  labelledBy?: string | undefined;
+  label?: string | undefined;
+  /** Its help's and its error's ids. */
+  describedBy?: string | undefined;
+  invalid?: boolean | undefined;
+  required?: boolean | undefined;
+  disabled?: boolean | undefined;
+}
+
+/** The ARIA a control carries, from what names it and what is wrong with it. */
+export function ariaOf(control: ControlBase) {
+  return {
+    "aria-labelledby": control.labelledBy,
+    "aria-label": control.labelledBy === undefined ? control.label : undefined,
+    "aria-describedby": control.describedBy,
+    "aria-invalid": control.invalid || undefined,
+    "aria-required": control.required || undefined,
+  };
+}
+
+/** What a field hands its control: its id, and the ids that name it and describe it. */
+export interface FieldIds {
+  id: string;
+  labelledBy: string | undefined;
+  describedBy: string | undefined;
+  invalid: boolean;
+}
+
+/**
+ * A label without the word that says it may stay empty, written into it ("Notas (opcional)"):
+ * the quiet word beside it says so once.
+ */
+export function withoutOptional(label: ReactNode, word: string): ReactNode {
+  if (typeof label !== "string") return label;
+  const said = label.replace(/\s*\(([^)]*)\)\s*$/u, (whole, inside: string) =>
+    inside.trim().toLowerCase() === word.toLowerCase() ? "" : whole,
+  );
+  return said === "" ? label : said;
+}
+
+/**
+ * One thing to fill: its label (a quiet word beside it when it may stay empty), the control,
+ * then a line of help and what is wrong, both read with the control. `group` is for a control
+ * made of buttons (cards, chips, stars), which no <label> can point at: the label names it.
+ */
+export function Field({
+  label,
+  optional,
+  help,
+  error,
+  group,
+  name,
+  className,
+  children,
+}: {
+  label?: ReactNode;
+  optional?: boolean | undefined;
+  help?: ReactNode;
+  error?: string | undefined;
+  group?: boolean | undefined;
+  /** Marks the field (`data-field`), so a form can find it to focus. */
+  name?: string | undefined;
+  className?: string | undefined;
+  children: (ids: FieldIds) => ReactNode;
+}) {
+  const { messages } = useKit();
+  const part = useParts();
+  const base = useId();
+  const ids = { control: `${base}c`, label: `${base}l`, help: `${base}h`, error: `${base}e` };
+  const described = [help !== undefined && ids.help, error !== undefined && ids.error];
+  const Label = group ? "span" : "label";
+  return (
+    <div data-field={name} part="field" className={joined(part("sc-field"), className)}>
+      {label !== undefined && (
+        <Label
+          id={ids.label}
+          {...(!group && { htmlFor: ids.control })}
+          className={part("sc-field__label")}
+        >
+          {optional ? withoutOptional(label, messages.optional) : label}
+          {optional && <small className={part("sc-field__optional")}>{messages.optional}</small>}
+        </Label>
+      )}
+      {children({
+        id: ids.control,
+        labelledBy: label !== undefined ? ids.label : undefined,
+        describedBy: described.filter(Boolean).join(" ") || undefined,
+        invalid: error !== undefined,
+      })}
+      {help !== undefined && (
+        <p id={ids.help} className={part("sc-field__help")}>
+          {help}
+        </p>
+      )}
+      {error !== undefined && (
+        <p id={ids.error} className={part("sc-field__error")}>
+          <WarningCircleIcon aria-hidden weight="fill" />
+          {error}
+        </p>
+      )}
+    </div>
+  );
+}
+
+/**
+ * The box a control sits in: a hairline at the inner corners, an icon at its start, more at its
+ * end; the accent and its ring while anything in it has focus, the danger tone while it is wrong.
+ */
+export function Box({
+  icon: Leading,
+  invalid,
+  end,
+  children,
+}: {
+  icon?: Icon | undefined;
+  invalid?: boolean | undefined;
+  end?: ReactNode;
+  children: ReactNode;
+}) {
+  const part = useParts();
+  return (
+    <div part="control" className={part("sc-control")} data-invalid={invalid || undefined}>
+      {Leading && <Leading aria-hidden />}
+      {children}
+      {end}
+    </div>
+  );
+}