@signalcore/ui 0.1.0 → 1.0.0-beta.1

package/src/surface/values.ts

@@ -0,0 +1,361 @@
+/**
+ * What a surface sends, as pure functions: each block's action, a form's values from its fields,
+ * the words the person's answer reads as, and what is wrong with a value. The controls hold
+ * values in the shapes the contract sends (`blocks.ts`); nothing here touches the page.
+ */
+import type {
+  ButtonBlock,
+  ChoiceBlock,
+  Entry,
+  FieldValue,
+  FormBlock,
+  FormField,
+  ListBlock,
+  Option,
+} from "../blocks";
+import {
+  DAY,
+  dayAllowed,
+  formatDay,
+  formatMoment,
+  formatTime,
+  MOMENT,
+  momentParts,
+  slotAllowed,
+  TIME,
+} from "../kit/dates";
+import type { KitMessages } from "../kit/messages";
+import { formatNumber, withUnit } from "../kit/numbers";
+import { STARS } from "../kit/RatingField";
+import type { Action, Attachment } from "../types";
+
+/**
+ * What a block sends when the person uses it: its action's name, what it carries, and the words
+ * the app shows for it (the option picked, the button, the form's answer).
+ */
+export type SurfaceAction = Omit<Action, "surface">;
+
+/** A form's values by field name, as its controls hold them. */
+export type Values = Record<string, FieldValue>;
+
+/** The field kinds this renderer draws; a surface with another falls back to its text. */
+export const FIELD_KINDS: ReadonlySet<string> = new Set([
+  "text",
+  "textarea",
+  "email",
+  "phone",
+  "url",
+  "number",
+  "date",
+  "time",
+  "datetime",
+  "select",
+  "multiselect",
+  "checkbox",
+  "range",
+  "rating",
+  "file",
+  "secret",
+]);
+
+/** Up to this many options, a select shows them all; more go in a list to search. */
+export const FEW_OPTIONS = 5;
+/** Up to this many, a multiselect is chips; more go in a list to search. */
+export const FEW_CHIPS = 8;
+/** What a secret reads as, anywhere it is shown. */
+export const MASK = "••••••••";
+/** The longest answer label the API takes. */
+const LABEL_MAX = 2000;
+
+const EMAIL = /^[^\s@]+@[^\s@]+\.[^\s@]{2,}$/;
+const PHONE = /^\+?[\d\s().-]+$/;
+const URL_SHAPE = /^(https?:\/\/)?[^\s/.]+(\.[^\s/.]+)+(\/\S*)?$/i;
+
+// --- The blocks' actions ------------------------------------------------------------------
+
+/** A button's action: its name, nothing more, under its label. */
+export function pressed(block: ButtonBlock & { action: string }): SurfaceAction {
+  return { name: block.action, data: {}, label: block.label };
+}
+
+/** A choice's action: the option's id, under its label. */
+export function picked(block: ChoiceBlock, option: Option): SurfaceAction {
+  return { name: block.action, data: { option: option.id }, label: option.label };
+}
+
+/** A choice answered in the person's own words, under them. */
+export function answeredIn(block: ChoiceBlock, text: string): SurfaceAction {
+  return { name: block.action, data: { text }, label: text };
+}
+
+/** A list's action: the entry's id, under its title. */
+export function chosen(block: ListBlock & { action: string }, entry: Entry): SurfaceAction {
+  return { name: block.action, data: { item: entry.id }, label: entry.title };
+}
+
+/**
+ * A form's action: its values by field name (an empty field as null), under the words of its
+ * one answer when it asks one thing (the day, the slot, the options picked, the files' names,
+ * read from `files`), its submit's when it asks more.
+ */
+export function filled(
+  block: FormBlock,
+  values: Values,
+  code: string,
+  messages: KitMessages,
+  files?: ReadonlyMap<string, Attachment>,
+): SurfaceAction {
+  const data: Values = {};
+  for (const field of block.fields) data[field.name] = sent(field, values[field.name] ?? null);
+  const only = block.fields.length === 1 ? block.fields[0] : undefined;
+  const answer = only ? labelOf(only, data[only.name] ?? null, code, messages, { files }) : "";
+  return { name: block.action, data, label: clip(answer) || (block.submit ?? messages.send) };
+}
+
+/** A value as it goes: words trimmed, an empty one as null, a moment only once whole. */
+export function sent(field: FormField, value: FieldValue): FieldValue {
+  if (typeof value === "string") {
+    const text = value.trim();
+    if (field.kind === "datetime") return MOMENT.test(text) ? text : null;
+    return text === "" ? null : text;
+  }
+  if (typeof value === "number") return Number.isFinite(value) ? value : null;
+  return value;
+}
+
+// --- Where a form starts ------------------------------------------------------------------
+
+/**
+ * Each field's first value: what the person already sent (`answered`, the form's own action's
+ * data), else what the agent gave it, else empty; a value that does not fit its kind is left out.
+ */
+export function startValues(fields: FormField[], answered?: Record<string, unknown>): Values {
+  const values: Values = {};
+  for (const field of fields) {
+    const given = answered && field.name in answered ? answered[field.name] : field.value;
+    values[field.name] = fit(field, given) ?? emptyOf(field);
+  }
+  return values;
+}
+
+/** A field with nothing given: unticked, none picked, a slider at its least, else nothing. */
+export function emptyOf(field: FormField): FieldValue {
+  switch (field.kind) {
+    case "checkbox":
+      return false;
+    case "multiselect":
+    case "file":
+      return [];
+    case "range":
+      return field.min ?? 0;
+    default:
+      return null;
+  }
+}
+
+/** A value read as the field's kind holds it, or null when it does not fit. */
+export function fit(field: FormField, raw: unknown): FieldValue {
+  switch (field.kind) {
+    case "checkbox":
+      return raw === true || raw === "true"
+        ? true
+        : raw === false || raw === "false"
+          ? false
+          : null;
+    case "number":
+    case "range":
+    case "rating": {
+      const number = typeof raw === "string" && raw.trim() !== "" ? Number(raw) : raw;
+      return typeof number === "number" && Number.isFinite(number) ? number : null;
+    }
+    case "multiselect": {
+      const ids = Array.isArray(raw) ? raw : typeof raw === "string" ? [raw] : [];
+      return ids.filter((id): id is string => typeof id === "string" && hasOption(field, id));
+    }
+    case "file": {
+      const ids = Array.isArray(raw) ? raw : typeof raw === "string" ? [raw] : [];
+      const strings = ids.filter((id): id is string => typeof id === "string" && id !== "");
+      return field.multiple ? strings : strings.slice(0, 1);
+    }
+    case "select":
+      return typeof raw === "string" && hasOption(field, raw) ? raw : null;
+    case "date":
+      return typeof raw === "string" && DAY.test(raw) ? raw : null;
+    case "time":
+      return typeof raw === "string" && TIME.test(raw) ? raw : null;
+    case "datetime":
+      return typeof raw === "string" && MOMENT.test(raw.slice(0, 16)) ? raw.slice(0, 16) : null;
+    default:
+      return typeof raw === "string" || typeof raw === "number" ? String(raw) : null;
+  }
+}
+
+// --- What a value reads as ----------------------------------------------------------------
+
+/**
+ * A value in words, as the person's answer reads in the chat: a day and a time in the host's
+ * language (against `today`), the options' labels joined, the files' names (from `files`), a
+ * number with its unit; "" when it is empty. A secret is never shown.
+ */
+export function labelOf(
+  field: FormField,
+  value: FieldValue,
+  code: string,
+  messages: KitMessages,
+  {
+    today = new Date(),
+    files,
+  }: { today?: Date | undefined; files?: ReadonlyMap<string, Attachment> | undefined } = {},
+): string {
+  if (field.kind === "secret") return value === null || value === "" ? "" : MASK;
+  if (field.kind === "checkbox") return value === true ? messages.yes : messages.no;
+  if (value === null) return "";
+  if (Array.isArray(value)) {
+    const labels = value.map((id) =>
+      field.kind === "file"
+        ? (files?.get(id)?.name ?? messages.file)
+        : (optionOf(field, id)?.label ?? id),
+    );
+    return labels.length === 0
+      ? ""
+      : new Intl.ListFormat(code, { type: "conjunction" }).format(labels);
+  }
+  if (typeof value === "number") {
+    if (field.kind === "rating") return messages.rated(value, field.max ?? STARS);
+    return withUnit(formatNumber(value, code), field.unit);
+  }
+  if (typeof value !== "string") return "";
+  switch (field.kind) {
+    case "select":
+      return optionOf(field, value)?.label ?? value;
+    case "date":
+      return formatDay(value, code, today);
+    case "time":
+      return TIME.test(value) ? formatTime(value, code) : value;
+    case "datetime":
+      return formatMoment(value, code, today);
+    default:
+      return value.trim();
+  }
+}
+
+function clip(text: string): string {
+  return text.length > LABEL_MAX ? `${text.slice(0, LABEL_MAX - 1)}…` : text;
+}
+
+// --- What is wrong with a value -----------------------------------------------------------
+
+/** What is wrong with each field's value, by name; a field with nothing wrong is not in it. */
+export function problemsOf(
+  fields: FormField[],
+  values: Values,
+  code: string,
+  messages: KitMessages,
+): Record<string, string> {
+  const problems: Record<string, string> = {};
+  for (const field of fields) {
+    const problem = problemOf(field, values[field.name] ?? null, code, messages);
+    if (problem !== null) problems[field.name] = problem;
+  }
+  return problems;
+}
+
+/**
+ * What is wrong with a value, in words, or null: empty when it must be filled, a shape that is
+ * not an email, a phone or an address, a number out of its bounds, a day or a time the field
+ * does not offer.
+ */
+export function problemOf(
+  field: FormField,
+  value: FieldValue,
+  code: string,
+  messages: KitMessages,
+): string | null {
+  if (isEmpty(field, value)) return field.required ? emptyWords(field, messages) : null;
+  const text = typeof value === "string" ? value.trim() : "";
+  switch (field.kind) {
+    case "email":
+      return EMAIL.test(text) ? null : messages.invalidEmail;
+    case "phone":
+      return PHONE.test(text) && text.replace(/\D/g, "").length >= 6 ? null : messages.invalidPhone;
+    case "url":
+      return URL_SHAPE.test(text) ? null : messages.invalidUrl;
+    case "number":
+    case "range":
+    case "rating":
+      return typeof value === "number" && Number.isFinite(value)
+        ? outOfBounds(field, value, code, messages)
+        : messages.invalidNumber;
+    case "date":
+      return dayAllowed(field, text) ? null : messages.unavailableDate;
+    case "time":
+      if (!TIME.test(text)) return messages.invalidTime;
+      return slotAllowed(field.times, text) ? null : messages.unavailableTime;
+    case "datetime": {
+      const [date, time] = momentParts(text);
+      if (date === "" || time === "") return messages.chooseMoment;
+      if (!dayAllowed(field, date)) return messages.unavailableDate;
+      if (!TIME.test(time)) return messages.invalidTime;
+      return slotAllowed(field.times, time) ? null : messages.unavailableTime;
+    }
+    case "select":
+      return hasOption(field, text) ? null : messages.chooseOption;
+    case "multiselect":
+      return Array.isArray(value) && value.every((id) => hasOption(field, id))
+        ? null
+        : messages.chooseOption;
+    default:
+      return null;
+  }
+}
+
+/** Whether nothing was given: no words, no pick, an unticked box, no stars. */
+export function isEmpty(field: FormField, value: FieldValue): boolean {
+  if (value === null) return true;
+  if (field.kind === "checkbox") return value !== true;
+  if (typeof value === "string") return value.trim() === "";
+  if (Array.isArray(value)) return value.length === 0;
+  return false;
+}
+
+function emptyWords(field: FormField, messages: KitMessages): string {
+  switch (field.kind) {
+    case "date":
+      return messages.chooseDate;
+    case "time":
+      return messages.chooseTime;
+    case "datetime":
+      return messages.chooseMoment;
+    case "select":
+    case "multiselect":
+      return messages.chooseOption;
+    case "rating":
+      return messages.chooseRating;
+    case "checkbox":
+      return messages.check;
+    case "file":
+      return messages.chooseFile;
+    default:
+      return messages.required;
+  }
+}
+
+function outOfBounds(
+  field: FormField,
+  value: number,
+  code: string,
+  messages: KitMessages,
+): string | null {
+  const { min, max } = field;
+  if (min !== undefined && value < min) return messages.atLeast(formatNumber(min, code));
+  if (max !== undefined && value > max) return messages.atMost(formatNumber(max, code));
+  return null;
+}
+
+export function optionOf(field: FormField, id: string): Option | undefined {
+  return field.options?.find((option) => option.id === id);
+}
+
+function hasOption(field: FormField, id: string): boolean {
+  return optionOf(field, id) !== undefined;
+}

package/src/tint.ts

@@ -0,0 +1,14 @@
+/** The tints an agent's tile can take: the soft ones, never a state or the accent. */
+export type AgentTint = "sky" | "rose" | "sand";
+
+const TINTS: readonly AgentTint[] = ["sky", "rose", "sand"];
+
+/**
+ * The tint an agent keeps wherever it appears (a squad's map, its profile, its card): picked from
+ * its id, so a rename changes nothing, and spread evenly over the three.
+ */
+export function agentTint(id: string): AgentTint {
+  let hash = 0;
+  for (const char of id) hash = (hash * 31 + (char.codePointAt(0) ?? 0)) >>> 0;
+  return TINTS[hash % TINTS.length] ?? "sky";
+}