@signalcore/ui 0.1.0 → 1.0.0-beta.1

package/src/kit/RatingField.tsx

@@ -0,0 +1,62 @@
+import { StarIcon } from "@phosphor-icons/react";
+import { useState } from "react";
+
+import { useRadios } from "./Choices";
+import { useKit, useParts } from "./context";
+import { ariaOf, type ControlBase } from "./Field";
+
+/** Stars when none are given, and the most a rating draws. */
+export const STARS = 5;
+const MOST = 10;
+
+/**
+ * Stars up to `max`, as a group of radios: the arrows move the rating, the pointer lights the
+ * stars it is over before the press, and the rating reads beside them.
+ */
+export function RatingField({
+  value,
+  onChange,
+  max = STARS,
+  ...control
+}: ControlBase & {
+  /** The stars given, or none. */
+  value: number | null;
+  onChange: (value: number) => void;
+  max?: number | undefined;
+}) {
+  const { messages } = useKit();
+  const part = useParts();
+  const stars = Math.min(MOST, Math.max(1, Math.round(max)));
+  const rating = value === null ? 0 : Math.round(value);
+  const [over, setOver] = useState(0);
+  const radios = useRadios(stars, rating - 1, (index) => onChange(index + 1));
+  const lit = over || rating;
+  return (
+    <div
+      role="radiogroup"
+      {...ariaOf(control)}
+      onMouseLeave={() => setOver(0)}
+      className={part("sc-rating")}
+    >
+      {Array.from({ length: stars }, (_, index) => (
+        <button
+          key={index}
+          ref={radios.ref(index)}
+          type="button"
+          role="radio"
+          aria-checked={rating === index + 1}
+          aria-label={messages.stars(index + 1)}
+          tabIndex={radios.tabIndex(index)}
+          disabled={control.disabled}
+          data-lit={index < lit || undefined}
+          onKeyDown={(event) => radios.onKeyDown(event, index)}
+          onMouseEnter={() => setOver(index + 1)}
+          onClick={() => onChange(index + 1)}
+        >
+          <StarIcon aria-hidden weight={index < lit ? "fill" : "regular"} />
+        </button>
+      ))}
+      {rating > 0 && <span aria-hidden>{messages.rated(rating, stars)}</span>}
+    </div>
+  );
+}

package/src/kit/Stat.tsx

@@ -0,0 +1,60 @@
+import type { ReactNode } from "react";
+
+import { joined, useParts } from "./context";
+
+export type Tone = "info" | "success" | "warning" | "danger";
+
+/** One number that matters: a quiet label, the figure large, a line of context in its tone. */
+export function Stat({
+  label,
+  value,
+  hint,
+  tone,
+  className,
+}: {
+  label: ReactNode;
+  value: ReactNode;
+  hint?: ReactNode;
+  /** The hint's: a rise in success, a fall in danger. */
+  tone?: Tone | undefined;
+  className?: string | undefined;
+}) {
+  const part = useParts();
+  return (
+    <div
+      part="stat"
+      className={joined(
+        part("sc-stat", ...(tone !== undefined ? ([`sc-stat--${tone}`] as const) : [])),
+        className,
+      )}
+    >
+      <span className={part("sc-stat__label")}>{label}</span>
+      <strong className={part("sc-stat__value")}>{value}</strong>
+      {hint !== undefined && <small className={part("sc-stat__hint")}>{hint}</small>}
+    </div>
+  );
+}
+
+/**
+ * Figures side by side in one hairline box, a hairline between each, their figures a size
+ * quieter than a `Stat` alone: a day at a glance. All in a row where the box has room, two
+ * across where it has not.
+ */
+export function Stats({
+  label,
+  className,
+  children,
+}: {
+  /** What the figures are, for screen readers, when no heading above them says it. */
+  label?: string | undefined;
+  className?: string | undefined;
+  /** The figures, each a `Stat`. */
+  children: ReactNode;
+}) {
+  const part = useParts();
+  return (
+    <div role="group" aria-label={label} className={joined(part("sc-stats"), className)}>
+      <div className={part("sc-stats__grid")}>{children}</div>
+    </div>
+  );
+}

package/src/kit/Switch.tsx

@@ -0,0 +1,28 @@
+import { joined, useParts } from "./context";
+
+export interface SwitchProps {
+  checked: boolean;
+  onChange: (checked: boolean) => void;
+  /** What it turns on and off, for screen readers when no label beside it says so. */
+  label?: string | undefined;
+  labelledBy?: string | undefined;
+  disabled?: boolean | undefined;
+  className?: string | undefined;
+}
+
+/** On or off at once, as the ARIA switch: a track lit in the accent when on, its knob across. */
+export function Switch({ checked, onChange, label, labelledBy, disabled, className }: SwitchProps) {
+  const part = useParts();
+  return (
+    <button
+      type="button"
+      role="switch"
+      aria-checked={checked}
+      aria-label={labelledBy === undefined ? label : undefined}
+      aria-labelledby={labelledBy}
+      disabled={disabled}
+      onClick={() => onChange(!checked)}
+      className={joined(part("sc-switch"), className)}
+    />
+  );
+}

package/src/kit/Tag.tsx

@@ -0,0 +1,32 @@
+import type { ReactNode } from "react";
+
+import { joined, useParts } from "./context";
+import type { Tone } from "./Stat";
+
+/**
+ * A short word beside what it qualifies, no pill: how something stands, in its tone ("Falló" in
+ * danger, "Espera tu respuesta" in the accent), a small glyph or dot before the words when
+ * `children` starts with one. For state only: a property a row always has is said by where the
+ * row sits (under a heading), not by a word on each.
+ */
+export function Tag({
+  tone,
+  className,
+  children,
+}: {
+  tone?: Tone | undefined;
+  className?: string | undefined;
+  children: ReactNode;
+}) {
+  const part = useParts();
+  return (
+    <span
+      className={joined(
+        part("sc-tag", ...(tone !== undefined ? ([`sc-tag--${tone}`] as const) : [])),
+        className,
+      )}
+    >
+      {children}
+    </span>
+  );
+}

package/src/kit/Tile.tsx

@@ -0,0 +1,74 @@
+import type { ReactNode } from "react";
+
+import { joined, useParts } from "./context";
+
+/**
+ * Tiles in a grid that asks its own width, not the window's: two across, one when narrow, three
+ * when there is room. What an agent works with, a squad's agents at a glance.
+ */
+export function Tiles({
+  label,
+  className,
+  children,
+}: {
+  /** The grid's name, for screen readers, when no heading above it says it. */
+  label?: string | undefined;
+  className?: string | undefined;
+  children: ReactNode;
+}) {
+  const part = useParts();
+  return (
+    <div className={joined(part("sc-tiles"), className)}>
+      <ul aria-label={label} className={part("sc-tiles__grid")}>
+        {children}
+      </ul>
+    </div>
+  );
+}
+
+export interface TileProps {
+  /** At its start, usually a small `Mark`: what kind of thing it is. */
+  mark?: ReactNode;
+  /** What it is, in a word or two. */
+  title: ReactNode;
+  /** How many it holds, at its end, in figures that line up. */
+  count?: ReactNode;
+  /** In the count's place, what says it better: a few logos and how many more. */
+  end?: ReactNode;
+  /** Pressing the tile: it opens what it stands for. */
+  onPress?: (() => void) | undefined;
+  /** Holding nothing yet: quieter, still to press. */
+  quiet?: boolean | undefined;
+  className?: string | undefined;
+}
+
+/**
+ * One tile of `Tiles`, on one line: its mark, its name, and at its end its count (or what says it
+ * better). With `onPress` the whole tile is a button.
+ */
+export function Tile({ mark, title, count, end, onPress, quiet, className }: TileProps) {
+  const part = useParts();
+  const body = (
+    <>
+      {mark}
+      <span className={part("sc-tile__title")}>{title}</span>
+      {end ?? (count !== undefined && <span className={part("sc-tile__count")}>{count}</span>)}
+    </>
+  );
+  return (
+    <li
+      className={joined(
+        part("sc-tile", ...(quiet ? (["sc-tile--quiet"] as const) : [])),
+        className,
+      )}
+    >
+      {onPress ? (
+        <button type="button" onClick={onPress} className={part("sc-tile__main")}>
+          {body}
+        </button>
+      ) : (
+        <div className={part("sc-tile__main")}>{body}</div>
+      )}
+    </li>
+  );
+}

package/src/kit/TimeField.tsx

@@ -0,0 +1,157 @@
+import { ClockIcon } from "@phosphor-icons/react";
+
+import { useRadios } from "./Choices";
+import { Combobox } from "./Combobox";
+import { useKit, useParts } from "./context";
+import { DateField } from "./DateField";
+import {
+  DAY_END,
+  formatTime,
+  halfHours,
+  momentOf,
+  momentParts,
+  parseEndTime,
+  parseTime,
+  type DayBounds,
+} from "./dates";
+import { ariaOf, type ControlBase } from "./Field";
+
+/** Where a list of times opens while none is picked: the start of a working day. */
+const MORNING = "09:00";
+
+export interface TimeFieldProps extends ControlBase {
+  /** The time picked, "HH:MM", or none. */
+  value: string | null;
+  onChange: (time: string | null) => void;
+  /** The only slots, "HH:MM". */
+  times?: string[] | undefined;
+  placeholder?: string | undefined;
+  /** It is where a stretch of the day ends: the day's end ("24:00") is offered last, and typed. */
+  endOfDay?: boolean | undefined;
+}
+
+/**
+ * A time: the slots offered as chips to pick one of, when there are; else a list of the half
+ * hours to search, which also takes a time typed ("9:15", "21.30").
+ */
+export function TimeField(props: TimeFieldProps) {
+  return props.times ? <Slots {...props} times={props.times} /> : <AnyTime {...props} />;
+}
+
+/** The slots, a chip each in a grid, as one group of radios. */
+function Slots({
+  value,
+  onChange,
+  times,
+  endOfDay: _,
+  ...control
+}: TimeFieldProps & { times: string[] }) {
+  const { code } = useKit();
+  const part = useParts();
+  const checked = value === null ? -1 : times.indexOf(value);
+  const radios = useRadios(times.length, checked, (index) => {
+    const time = times[index];
+    if (time !== undefined) onChange(time);
+  });
+  return (
+    <div role="radiogroup" {...ariaOf(control)} className={part("sc-slots")}>
+      {times.map((time, index) => (
+        <button
+          key={time}
+          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(time)}
+          className={part("sc-chip")}
+        >
+          {formatTime(time, code)}
+        </button>
+      ))}
+    </div>
+  );
+}
+
+/** Any time of the day: the half hours to pick from, or one typed; an end, the day's end too. */
+function AnyTime({
+  value,
+  onChange,
+  placeholder,
+  times: _,
+  endOfDay = false,
+  ...control
+}: TimeFieldProps) {
+  const { code, messages } = useKit();
+  const parse = endOfDay ? parseEndTime : parseTime;
+  const time = value !== null && parse(value) ? value : null;
+  const times = endOfDay ? [...halfHours(), DAY_END] : halfHours();
+  if (time !== null && !times.includes(time)) times.push(time);
+  return (
+    <Combobox
+      {...control}
+      options={times.toSorted().map((at) => ({ id: at, label: formatTime(at, code) }))}
+      value={time === null ? [] : [time]}
+      multiple={false}
+      onChange={(ids) => onChange(ids[0] ?? null)}
+      typed={(text) => {
+        const typed = parse(text);
+        return typed === null ? null : { id: typed, label: formatTime(typed, code) };
+      }}
+      start={MORNING}
+      placeholder={placeholder ?? messages.chooseTime}
+      icon={ClockIcon}
+    />
+  );
+}
+
+export interface DateTimeFieldProps extends ControlBase, DayBounds {
+  /** "YYYY-MM-DDTHH:MM"; held as "YYYY-MM-DDT" or "THH:MM" while half picked; none when neither. */
+  value: string | null;
+  onChange: (moment: string | null) => void;
+  times?: string[] | undefined;
+}
+
+/**
+ * A moment: a day and a time side by side, one over the other when narrow or when the time is
+ * a grid of slots. Each half is kept while the other is still to pick.
+ */
+export function DateTimeField({
+  value,
+  onChange,
+  dates,
+  earliest,
+  latest,
+  times,
+  ...control
+}: DateTimeFieldProps) {
+  const part = useParts();
+  const [date, time] = momentParts(value);
+  return (
+    <div
+      role="group"
+      {...ariaOf(control)}
+      aria-required={undefined}
+      data-slots={times ? "" : undefined}
+      className={part("sc-moment")}
+    >
+      <DateField
+        {...control}
+        value={date || null}
+        dates={dates}
+        earliest={earliest}
+        latest={latest}
+        onChange={(day) => onChange(momentOf(day, time))}
+      />
+      <TimeField
+        {...control}
+        id={control.id === undefined ? undefined : `${control.id}-time`}
+        value={time || null}
+        times={times}
+        onChange={(at) => onChange(momentOf(date, at ?? ""))}
+      />
+    </div>
+  );
+}

package/src/kit/context.tsx

@@ -0,0 +1,246 @@
+import { createContext, useContext, type ReactNode } from "react";
+
+import { classes } from "../classes";
+import { KIT_MESSAGES, type KitLocale, type KitMessages } from "./messages";
+
+/**
+ * The kit's parts, by the class each carries: one BEM family per primitive. `classNames` adds a
+ * host's own under the same keys, so a host styles every place a primitive appears at once.
+ * (`sc-card` is the Ficha's; the kit's card is `sc-panel`.)
+ */
+export type KitPart =
+  | "sc-panel"
+  | "sc-panel__head"
+  | "sc-panel__head--image"
+  | "sc-panel__heading"
+  | "sc-panel__title"
+  | "sc-panel__subtitle"
+  | "sc-list"
+  | "sc-row"
+  | "sc-row--quiet"
+  | "sc-row--pressed"
+  | "sc-row__main"
+  | "sc-row__text"
+  | "sc-row__title"
+  | "sc-row__subtitle"
+  | "sc-row__error"
+  | "sc-row__meta"
+  | "sc-row__trailing"
+  | "sc-mark"
+  | "sc-mark--logo"
+  | "sc-mark--photo"
+  | "sc-mark--round"
+  | "sc-tiles"
+  | "sc-tiles__grid"
+  | "sc-tile"
+  | "sc-tile--quiet"
+  | "sc-tile__main"
+  | "sc-tile__count"
+  | "sc-tile__title"
+  | "sc-stack"
+  | "sc-stack__item"
+  | "sc-stack__more"
+  | "sc-tag"
+  | "sc-tag--info"
+  | "sc-tag--success"
+  | "sc-tag--warning"
+  | "sc-tag--danger"
+  | "sc-stat"
+  | "sc-stat--info"
+  | "sc-stat--success"
+  | "sc-stat--warning"
+  | "sc-stat--danger"
+  | "sc-stat__label"
+  | "sc-stat__value"
+  | "sc-stat__hint"
+  | "sc-stats"
+  | "sc-stats__grid"
+  | "sc-chart"
+  | "sc-chart--bar"
+  | "sc-chart--line"
+  | "sc-chart__row"
+  | "sc-chart__label"
+  | "sc-chart__track"
+  | "sc-chart__bar"
+  | "sc-chart__value"
+  | "sc-chart__top"
+  | "sc-chart__plot"
+  | "sc-chart__wash"
+  | "sc-chart__axis"
+  | "sc-chart__line"
+  | "sc-chart__dot"
+  | "sc-chart__tip"
+  | "sc-chart__ends"
+  | "sc-chart__data"
+  | "sc-note"
+  | "sc-note--info"
+  | "sc-note--success"
+  | "sc-note--warning"
+  | "sc-note--danger"
+  | "sc-note__body"
+  | "sc-button"
+  | "sc-button--primary"
+  | "sc-button--neutral"
+  | "sc-button--danger"
+  | "sc-button--ghost"
+  | "sc-button--sm"
+  | "sc-button--icon"
+  | "sc-switch"
+  | "sc-audio"
+  | "sc-audio--compact"
+  | "sc-audio__play"
+  | "sc-audio__wave"
+  | "sc-audio__time"
+  | "sc-field"
+  | "sc-field__label"
+  | "sc-field__optional"
+  | "sc-field__help"
+  | "sc-field__error"
+  | "sc-control"
+  | "sc-control--trigger"
+  | "sc-control__input"
+  | "sc-control__unit"
+  | "sc-control__steppers"
+  | "sc-control__reveal"
+  | "sc-control__tag"
+  | "sc-check"
+  | "sc-popover"
+  | "sc-listbox"
+  | "sc-listbox__item"
+  | "sc-listbox__empty"
+  | "sc-calendar"
+  | "sc-picks"
+  | "sc-segments"
+  | "sc-pick"
+  | "sc-chips"
+  | "sc-chip"
+  | "sc-slots"
+  | "sc-moment"
+  | "sc-range"
+  | "sc-rating"
+  | "sc-upload"
+  | "sc-upload__zone"
+  | "sc-upload__icon"
+  | "sc-upload__text"
+  | "sc-attachments"
+  | "sc-attachment"
+  | "sc-attachment--failed"
+  | "sc-attachment__main"
+  | "sc-attachment__text"
+  | "sc-attachment__name"
+  | "sc-attachment__meta"
+  | "sc-attachment__action"
+  | "sc-attachment__bar"
+  | "sc-orb"
+  | "sc-orb--idle"
+  | "sc-orb--listening"
+  | "sc-orb--thinking"
+  | "sc-orb--speaking"
+  | "sc-orb--still"
+  | "sc-orb--loading"
+  | "sc-orb__ring"
+  | "sc-orb__core"
+  | "sc-automation"
+  | "sc-automation--gone"
+  | "sc-automation__head"
+  | "sc-automation__heading"
+  | "sc-automation__title"
+  | "sc-automation__when"
+  | "sc-automation__end"
+  | "sc-automation__dot"
+  | "sc-automation__summary"
+  | "sc-automation__section"
+  | "sc-automation__label"
+  | "sc-automation__steps"
+  | "sc-automation__step"
+  | "sc-automation__number"
+  | "sc-automation__name"
+  | "sc-automation__uses"
+  | "sc-automation__use"
+  | "sc-automation__board"
+  | "sc-automation__more"
+  | "sc-automation__runs"
+  | "sc-automation__run--open"
+  | "sc-automation__status"
+  | "sc-automation__empty"
+  | "sc-run"
+  | "sc-run__head"
+  | "sc-run__by"
+  | "sc-run__end"
+  | "sc-run__took"
+  | "sc-run__heading"
+  | "sc-run__title"
+  | "sc-run__meta"
+  | "sc-run__summary"
+  | "sc-run__section"
+  | "sc-run__label"
+  | "sc-run__steps"
+  | "sc-run__step"
+  | "sc-run__number"
+  | "sc-run__name"
+  | "sc-run__calls"
+  | "sc-run__call"
+  | "sc-run__call--would"
+  | "sc-run__call--failed"
+  | "sc-run__count"
+  | "sc-run__error"
+  | "sc-run__live"
+  | "sc-run__links"
+  | "sc-run__empty";
+
+export type KitClassNames = Partial<Record<KitPart, string>> | undefined;
+
+/** What every primitive under one host shares: its classes, its words, its language. */
+interface KitScope {
+  classNames: KitClassNames;
+  messages: KitMessages;
+  locale: KitLocale | undefined;
+  /** The locale's code, for Intl: "es", "en-US". */
+  code: string;
+}
+
+const KitContext = createContext<KitScope>({
+  classNames: undefined,
+  messages: KIT_MESSAGES,
+  locale: undefined,
+  code: "en-US",
+});
+
+/**
+ * Gives the primitives under it the host's classes, words and language; without it they are
+ * the package's, in English.
+ */
+export function KitProvider({
+  classNames,
+  messages,
+  locale,
+  children,
+}: {
+  classNames?: KitClassNames;
+  messages?: Partial<KitMessages> | undefined;
+  locale?: KitLocale | undefined;
+  children: ReactNode;
+}) {
+  const scope: KitScope = {
+    classNames,
+    messages: { ...KIT_MESSAGES, ...messages },
+    locale,
+    code: locale?.code ?? "en-US",
+  };
+  return <KitContext value={scope}>{children}</KitContext>;
+}
+
+export function useKit(): KitScope {
+  return useContext(KitContext);
+}
+
+/** The classes of the kit's parts, each with the host's own under it. */
+export function useParts(): (...parts: KitPart[]) => string {
+  const { classNames } = useKit();
+  return (...parts) => classes(classNames, ...parts);
+}
+
+/** A part's classes and the caller's own, as one `className`. */
+export function joined(...names: (string | false | undefined)[]): string {
+  return names.filter(Boolean).join(" ");
+}