@signalcore/ui 0.1.0 → 1.0.0-beta.0

package/dist/automation/when.d.ts

@@ -0,0 +1,36 @@
+import { Automation, Trigger } from "./types.js";
+import { AutomationMessages, DayRef } from "./messages.js";
+//#region src/automation/when.d.ts
+/** A time of day as the locale writes it ("9:00", "9:00 AM"), from a cron line's hour and minute. */
+export declare function clockOf(hour: number, minute: number, code: string): string;
+/** A trigger in words, and whether it names the one time of day it runs (so the next needs none). */
+export interface When {
+  text: string;
+  timed: boolean;
+}
+/** A trigger in words: its schedule as a sentence, a webhook's call, an app's event. */
+export declare function whenOf(trigger: Trigger, words: AutomationMessages, code: string): When;
+/** A cron line as a sentence: its days, then its times or how often. */
+export declare function scheduleOf(line: string, words: AutomationMessages, code: string): When;
+/**
+ * A moment's day beside `now`, where the person is: today, yesterday, tomorrow, a weekday within
+ * the week, else its date (with its year when not this one).
+ */
+export declare function dayRefOf(moment: Date, now: Date, code: string, weekday?: "short" | "long"): DayRef;
+/** A moment's time of day where the person is: "9:00". */
+export declare const timeOf: (moment: Date, code: string) => string;
+/** When a run started: "Hoy 9:00", "Ayer 16:12", "Lun 9:00", "3 oct 9:00". */
+export declare function momentOf(at: Date, now: Date, words: AutomationMessages, code: string): string;
+/**
+ * The line under an automation's title: when it runs and, while it is on and has a next run,
+ * when that is ("Cada día laborable a las 9:00, próxima mañana"). The next run's time is said
+ * when the sentence doesn't already say it, and always when it is today.
+ */
+export declare function lineOf(automation: Pick<Automation, "trigger" | "on" | "next_run_at">, now: Date, words: AutomationMessages, code: string): string;
+/** How long a run took, once it ended. */
+export declare function tookOf(run: {
+  started_at: string;
+  ended_at: string | null;
+}, words: AutomationMessages): string | null;
+//#endregion
+//# sourceMappingURL=when.d.ts.map

package/dist/automation/when.js

@@ -0,0 +1,168 @@
+import { parseCron } from "./cron.js";
+//#region src/automation/when.ts
+/**
+* When an automation runs, and when one ran, as a person says it: its trigger in a sentence
+* ("Cada día laborable a las 9:00"), its next run ("próxima mañana"), the moment a run started
+* ("Ayer 16:12"), how long it took. The words are the host's (`AutomationMessages`); the locale's
+* code writes the times, the days and the lists. Pure, so it is tested without a page.
+*/
+/** A time of day as the locale writes it ("9:00", "9:00 AM"), from a cron line's hour and minute. */
+function clockOf(hour, minute, code) {
+	return new Intl.DateTimeFormat(code, {
+		hour: "numeric",
+		minute: "2-digit",
+		timeZone: "UTC"
+	}).format(new Date(Date.UTC(2026, 0, 1, hour, minute)));
+}
+/** A trigger in words: its schedule as a sentence, a webhook's call, an app's event. */
+function whenOf(trigger, words, code) {
+	switch (trigger.kind) {
+		case "schedule": return trigger.schedule === null ? {
+			text: words.custom,
+			timed: false
+		} : scheduleOf(trigger.schedule, words, code);
+		case "webhook": return {
+			text: words.webhook,
+			timed: false
+		};
+		case "event": return {
+			text: words.event(trigger.app_title ?? trigger.app, trigger.event_title),
+			timed: false
+		};
+	}
+}
+const sorted = (values) => [...values].sort((a, b) => a - b);
+/** Whether the values are every `step`-th one from `from` up to `to`: 0, 15, 30, 45. */
+function stepOf(values) {
+	if (values.length < 2) return null;
+	const step = (values[1] ?? 0) - (values[0] ?? 0);
+	return values.every((value, at) => value === (values[0] ?? 0) + at * step) ? step : null;
+}
+/** Monday first, as a week is read; Sunday is 0 in cron. */
+const weekOrder = (day) => (day + 6) % 7;
+function weekdayName(day, code) {
+	return new Intl.DateTimeFormat(code, {
+		weekday: "long",
+		timeZone: "UTC"
+	}).format(new Date(Date.UTC(2026, 0, 4 + day)));
+}
+/** The days a line runs on, in words; null for what a sentence can't say. */
+function daysOf(cron, words, code) {
+	if (cron.months.size !== 12) return null;
+	if (cron.anyDay && cron.anyWeekday) return words.daily;
+	if (cron.anyDay) {
+		const days = [...cron.weekdays].sort((a, b) => weekOrder(a) - weekOrder(b));
+		const key = days.join(",");
+		if (days.length === 7) return words.daily;
+		if (key === "1,2,3,4,5") return words.weekdays;
+		if (key === "6,0") return words.weekends;
+		return words.weekly(days.map((day) => weekdayName(day, code)));
+	}
+	if (cron.anyWeekday) return words.monthly(sorted(cron.days));
+	return null;
+}
+/** At most this many times are listed one by one; more read as a frequency. */
+const LISTED = 4;
+/** The times a line runs at in a day: listed ("a las 9:00"), or how often ("cada hora"). */
+function timesOf(cron, words, code) {
+	const hours = sorted(cron.hours);
+	const minutes = sorted(cron.minutes);
+	const first = hours[0] ?? 0;
+	const last = hours[hours.length - 1] ?? 0;
+	if (hours.length * minutes.length <= LISTED) {
+		const times = hours.flatMap((hour) => minutes.map((minute) => clockOf(hour, minute, code)));
+		return {
+			text: words.at(times),
+			listed: times.length
+		};
+	}
+	const minuteStep = minutes.length === 60 ? 1 : stepOf(minutes);
+	const hourStep = hours.length === 24 || hours.length === 1 ? 1 : stepOf(hours);
+	let often;
+	if (minutes.length === 1 && hourStep !== null) often = words.every(hourStep, "hour");
+	else if (minuteStep !== null && minutes[0] === 0 && 60 % minuteStep === 0 && hourStep === 1) often = words.every(minuteStep, "minute");
+	else return null;
+	if (hourStep !== null && hours.length * hourStep === 24 && first < hourStep) return {
+		text: often,
+		listed: 0
+	};
+	const from = clockOf(first, minutes[0] ?? 0, code);
+	const to = clockOf(last, minutes[minutes.length - 1] ?? 0, code);
+	return {
+		text: `${often} ${words.between(from, to)}`,
+		listed: 0
+	};
+}
+/** A cron line as a sentence: its days, then its times or how often. */
+function scheduleOf(line, words, code) {
+	const cron = parseCron(line);
+	const days = cron && daysOf(cron, words, code);
+	const times = cron && timesOf(cron, words, code);
+	if (!days || !times) return {
+		text: words.custom,
+		timed: false
+	};
+	if (times.listed > 0) return {
+		text: `${days} ${times.text}`,
+		timed: times.listed === 1
+	};
+	return {
+		text: days === words.daily ? times.text : words.on(times.text, days),
+		timed: false
+	};
+}
+/** A calendar day where the person is, as a count of days from the epoch's. */
+const dayNumber = (moment) => Math.round((new Date(moment.getFullYear(), moment.getMonth(), moment.getDate()).getTime() - new Date(1970, 0, 1).getTime()) / 864e5);
+/**
+* A moment's day beside `now`, where the person is: today, yesterday, tomorrow, a weekday within
+* the week, else its date (with its year when not this one).
+*/
+function dayRefOf(moment, now, code, weekday = "short") {
+	const days = dayNumber(moment) - dayNumber(now);
+	if (days === 0) return { kind: "today" };
+	if (days === -1) return { kind: "yesterday" };
+	if (days === 1) return { kind: "tomorrow" };
+	if (Math.abs(days) < 7) return {
+		kind: "weekday",
+		name: new Intl.DateTimeFormat(code, { weekday }).format(moment)
+	};
+	return {
+		kind: "date",
+		name: new Intl.DateTimeFormat(code, {
+			day: "numeric",
+			month: "short",
+			...moment.getFullYear() === now.getFullYear() ? {} : { year: "numeric" }
+		}).format(moment)
+	};
+}
+/** A moment's time of day where the person is: "9:00". */
+const timeOf = (moment, code) => new Intl.DateTimeFormat(code, {
+	hour: "numeric",
+	minute: "2-digit"
+}).format(moment);
+/** When a run started: "Hoy 9:00", "Ayer 16:12", "Lun 9:00", "3 oct 9:00". */
+function momentOf(at, now, words, code) {
+	return words.moment(dayRefOf(at, now, code), timeOf(at, code));
+}
+/**
+* The line under an automation's title: when it runs and, while it is on and has a next run,
+* when that is ("Cada día laborable a las 9:00, próxima mañana"). The next run's time is said
+* when the sentence doesn't already say it, and always when it is today.
+*/
+function lineOf(automation, now, words, code) {
+	const when = whenOf(automation.trigger, words, code);
+	if (!automation.on || automation.next_run_at === null) return when.text;
+	const next = new Date(automation.next_run_at);
+	const day = dayRefOf(next, now, code, "long");
+	const time = when.timed && day.kind !== "today" ? null : timeOf(next, code);
+	return `${when.text}, ${words.next(day, time)}`;
+}
+/** How long a run took, once it ended. */
+function tookOf(run, words) {
+	if (run.ended_at === null) return null;
+	return words.took(Math.max(0, Date.parse(run.ended_at) - Date.parse(run.started_at)));
+}
+//#endregion
+export { clockOf, dayRefOf, lineOf, momentOf, scheduleOf, timeOf, tookOf, whenOf };
+
+//# sourceMappingURL=when.js.map

package/dist/automation/when.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"when.js","names":[],"sources":["../../src/automation/when.ts"],"sourcesContent":["/**\n * When an automation runs, and when one ran, as a person says it: its trigger in a sentence\n * (\"Cada día laborable a las 9:00\"), its next run (\"próxima mañana\"), the moment a run started\n * (\"Ayer 16:12\"), how long it took. The words are the host's (`AutomationMessages`); the locale's\n * code writes the times, the days and the lists. Pure, so it is tested without a page.\n */\n\nimport { parseCron, type Cron } from \"./cron\";\nimport type { AutomationMessages, DayRef } from \"./messages\";\nimport type { Automation, Trigger } from \"./types\";\n\n/** A time of day as the locale writes it (\"9:00\", \"9:00 AM\"), from a cron line's hour and minute. */\nexport function clockOf(hour: number, minute: number, code: string): string {\n  return new Intl.DateTimeFormat(code, {\n    hour: \"numeric\",\n    minute: \"2-digit\",\n    timeZone: \"UTC\",\n  }).format(new Date(Date.UTC(2026, 0, 1, hour, minute)));\n}\n\n/** A trigger in words, and whether it names the one time of day it runs (so the next needs none). */\nexport interface When {\n  text: string;\n  timed: boolean;\n}\n\n/** A trigger in words: its schedule as a sentence, a webhook's call, an app's event. */\nexport function whenOf(trigger: Trigger, words: AutomationMessages, code: string): When {\n  switch (trigger.kind) {\n    case \"schedule\":\n      return trigger.schedule === null\n        ? { text: words.custom, timed: false }\n        : scheduleOf(trigger.schedule, words, code);\n    case \"webhook\":\n      return { text: words.webhook, timed: false };\n    case \"event\":\n      return {\n        text: words.event(trigger.app_title ?? trigger.app, trigger.event_title),\n        timed: false,\n      };\n  }\n}\n\nconst sorted = (values: ReadonlySet<number>): number[] => [...values].sort((a, b) => a - b);\n\n/** Whether the values are every `step`-th one from `from` up to `to`: 0, 15, 30, 45. */\nfunction stepOf(values: number[]): number | null {\n  if (values.length < 2) return null;\n  const step = (values[1] ?? 0) - (values[0] ?? 0);\n  return values.every((value, at) => value === (values[0] ?? 0) + at * step) ? step : null;\n}\n\n/** Monday first, as a week is read; Sunday is 0 in cron. */\nconst weekOrder = (day: number) => (day + 6) % 7;\n\nfunction weekdayName(day: number, code: string): string {\n  // 4 January 2026 is a Sunday.\n  return new Intl.DateTimeFormat(code, { weekday: \"long\", timeZone: \"UTC\" }).format(\n    new Date(Date.UTC(2026, 0, 4 + day)),\n  );\n}\n\n/** The days a line runs on, in words; null for what a sentence can't say. */\nfunction daysOf(cron: Cron, words: AutomationMessages, code: string): string | null {\n  if (cron.months.size !== 12) return null;\n  if (cron.anyDay && cron.anyWeekday) return words.daily;\n  if (cron.anyDay) {\n    const days = [...cron.weekdays].sort((a, b) => weekOrder(a) - weekOrder(b));\n    const key = days.join(\",\");\n    if (days.length === 7) return words.daily;\n    if (key === \"1,2,3,4,5\") return words.weekdays;\n    if (key === \"6,0\") return words.weekends;\n    return words.weekly(days.map((day) => weekdayName(day, code)));\n  }\n  if (cron.anyWeekday) return words.monthly(sorted(cron.days));\n  return null;\n}\n\n/** At most this many times are listed one by one; more read as a frequency. */\nconst LISTED = 4;\n\n/** The times a line runs at in a day: listed (\"a las 9:00\"), or how often (\"cada hora\"). */\nfunction timesOf(\n  cron: Cron,\n  words: AutomationMessages,\n  code: string,\n): { text: string; listed: number } | null {\n  const hours = sorted(cron.hours);\n  const minutes = sorted(cron.minutes);\n  const first = hours[0] ?? 0;\n  const last = hours[hours.length - 1] ?? 0;\n  if (hours.length * minutes.length <= LISTED) {\n    const times = hours.flatMap((hour) => minutes.map((minute) => clockOf(hour, minute, code)));\n    return { text: words.at(times), listed: times.length };\n  }\n  // Once in each of its hours, every few hours; or every few minutes through its hours.\n  const minuteStep = minutes.length === 60 ? 1 : stepOf(minutes);\n  const hourStep = hours.length === 24 || hours.length === 1 ? 1 : stepOf(hours);\n  let often: string;\n  if (minutes.length === 1 && hourStep !== null) {\n    often = words.every(hourStep, \"hour\");\n  } else if (minuteStep !== null && minutes[0] === 0 && 60 % minuteStep === 0 && hourStep === 1) {\n    often = words.every(minuteStep, \"minute\");\n  } else {\n    return null;\n  }\n  // The whole day (\"cada 2 horas\"), or a part of it (\"cada hora de 8:00 a 18:00\").\n  const whole = hourStep !== null && hours.length * hourStep === 24 && first < hourStep;\n  if (whole) return { text: often, listed: 0 };\n  const from = clockOf(first, minutes[0] ?? 0, code);\n  const to = clockOf(last, minutes[minutes.length - 1] ?? 0, code);\n  return { text: `${often} ${words.between(from, to)}`, listed: 0 };\n}\n\n/** A cron line as a sentence: its days, then its times or how often. */\nexport function scheduleOf(line: string, words: AutomationMessages, code: string): When {\n  const cron = parseCron(line);\n  const days = cron && daysOf(cron, words, code);\n  const times = cron && timesOf(cron, words, code);\n  if (!days || !times) return { text: words.custom, timed: false };\n  if (times.listed > 0) return { text: `${days} ${times.text}`, timed: times.listed === 1 };\n  return { text: days === words.daily ? times.text : words.on(times.text, days), timed: false };\n}\n\n/** A calendar day where the person is, as a count of days from the epoch's. */\nconst dayNumber = (moment: Date): number =>\n  Math.round(\n    (new Date(moment.getFullYear(), moment.getMonth(), moment.getDate()).getTime() -\n      new Date(1970, 0, 1).getTime()) /\n      86_400_000,\n  );\n\n/**\n * A moment's day beside `now`, where the person is: today, yesterday, tomorrow, a weekday within\n * the week, else its date (with its year when not this one).\n */\nexport function dayRefOf(\n  moment: Date,\n  now: Date,\n  code: string,\n  weekday: \"short\" | \"long\" = \"short\",\n): DayRef {\n  const days = dayNumber(moment) - dayNumber(now);\n  if (days === 0) return { kind: \"today\" };\n  if (days === -1) return { kind: \"yesterday\" };\n  if (days === 1) return { kind: \"tomorrow\" };\n  if (Math.abs(days) < 7) {\n    return { kind: \"weekday\", name: new Intl.DateTimeFormat(code, { weekday }).format(moment) };\n  }\n  return {\n    kind: \"date\",\n    name: new Intl.DateTimeFormat(code, {\n      day: \"numeric\",\n      month: \"short\",\n      ...(moment.getFullYear() === now.getFullYear() ? {} : { year: \"numeric\" }),\n    }).format(moment),\n  };\n}\n\n/** A moment's time of day where the person is: \"9:00\". */\nexport const timeOf = (moment: Date, code: string): string =>\n  new Intl.DateTimeFormat(code, { hour: \"numeric\", minute: \"2-digit\" }).format(moment);\n\n/** When a run started: \"Hoy 9:00\", \"Ayer 16:12\", \"Lun 9:00\", \"3 oct 9:00\". */\nexport function momentOf(at: Date, now: Date, words: AutomationMessages, code: string): string {\n  return words.moment(dayRefOf(at, now, code), timeOf(at, code));\n}\n\n/**\n * The line under an automation's title: when it runs and, while it is on and has a next run,\n * when that is (\"Cada día laborable a las 9:00, próxima mañana\"). The next run's time is said\n * when the sentence doesn't already say it, and always when it is today.\n */\nexport function lineOf(\n  automation: Pick<Automation, \"trigger\" | \"on\" | \"next_run_at\">,\n  now: Date,\n  words: AutomationMessages,\n  code: string,\n): string {\n  const when = whenOf(automation.trigger, words, code);\n  if (!automation.on || automation.next_run_at === null) return when.text;\n  const next = new Date(automation.next_run_at);\n  const day = dayRefOf(next, now, code, \"long\");\n  const time = when.timed && day.kind !== \"today\" ? null : timeOf(next, code);\n  return `${when.text}, ${words.next(day, time)}`;\n}\n\n/** How long a run took, once it ended. */\nexport function tookOf(\n  run: { started_at: string; ended_at: string | null },\n  words: AutomationMessages,\n): string | null {\n  if (run.ended_at === null) return null;\n  return words.took(Math.max(0, Date.parse(run.ended_at) - Date.parse(run.started_at)));\n}\n"],"mappings":"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"}

package/dist/blocks.d.ts

@@ -0,0 +1,185 @@
+import { AutomationView } from "./automation/types.js";
+import { FileBlock } from "./types.js";
+//#region src/blocks.d.ts
+export type Tone = "info" | "success" | "warning" | "danger";
+/** Words, as Markdown. */
+export interface TextBlock {
+  type: "text";
+  text: string;
+}
+/** Label and value pairs: a summary a person reads at a glance. */
+export interface FieldsBlock {
+  type: "fields";
+  items: {
+    label: string;
+    value: string;
+  }[];
+}
+/** Rows under named columns; a row's cells come in the columns' order. */
+export interface TableBlock {
+  type: "table";
+  columns: string[];
+  rows: string[][];
+}
+export interface Entry {
+  id: string;
+  title: string;
+  subtitle?: string;
+  /** At its right: a price, a time, a status. */
+  meta?: string;
+  /** A small picture at its left (https). */
+  image?: string;
+}
+/** Things in a column; with `action`, picking one sends it with `{item: id}`. */
+export interface ListBlock {
+  type: "list";
+  items: Entry[];
+  action?: string;
+}
+/** One number that matters, under its label, with a line of context in its tone. */
+export interface StatBlock {
+  type: "stat";
+  label: string;
+  value: string;
+  hint?: string;
+  tone?: Tone;
+}
+export interface ChartPoint {
+  label: string;
+  value: number;
+}
+/**
+ * Figures over a few labels: bars to compare them (by state, by who), a line to follow them in
+ * time (by day, by week), the labels in their order.
+ */
+export interface ChartBlock {
+  type: "chart";
+  kind: "bar" | "line";
+  points: ChartPoint[];
+}
+/** A line that stands out: what the person should notice. */
+export interface NoteBlock {
+  type: "note";
+  tone: Tone;
+  text: string;
+}
+export interface ImageBlock {
+  type: "image";
+  /** https only. */
+  url: string;
+  alt: string;
+  caption?: string;
+}
+/**
+ * One of an agent's automations, as its page shows it, read only: the agent names it (`agent`,
+ * its name or id, and `name`), and the API fills in `view` before the surface is shown or kept,
+ * with its newest 5 runs; null when there is no such automation.
+ */
+export interface AutomationBlock {
+  type: "automation";
+  agent: string;
+  name: string;
+  view: AutomationView | null;
+}
+/** One thing the person can do: pressing it sends `action`, or, with `url`, opens that page. */
+export interface ButtonBlock {
+  type: "button";
+  label: string;
+  action?: string;
+  url?: string;
+  tone: "primary" | "neutral" | "danger";
+}
+export interface Option {
+  id: string;
+  label: string;
+  hint?: string;
+}
+/**
+ * Pick one of a few, at once; picking sends `action` with `{option: id}`. With `other`, a last
+ * row takes an answer in the person's own words instead: `{text}`.
+ */
+export interface ChoiceBlock {
+  type: "choice";
+  options: Option[];
+  action: string;
+  other?: boolean;
+}
+export type FieldKind = "text" | "textarea" | "email" | "phone" | "url" | "number" | "date" | "time" | "datetime" | "select" | "multiselect" | "checkbox" | "range" | "rating" |
+/** Files the person uploads to the conversation as they pick them; the value is their ids. */
+"file" |
+/** A value typed once and never stored by the conversation (`ask_person` only). */
+"secret";
+/** What a field holds: words, a number, yes or no, option ids; dates and times as ISO text. */
+export type FieldValue = string | number | boolean | string[] | null;
+/**
+ * One thing to fill. Its `kind` picks the control; the rest narrows it: `options` for a select or
+ * multiselect; `min`, `max`, `step` and `unit` for a number, range or rating (stars up to `max`,
+ * 5 by default); `dates` (the only days to pick, "YYYY-MM-DD"), `earliest` and `latest` for a
+ * date or datetime; `times` (the only slots, "HH:MM") for a time or datetime; `accept`,
+ * `multiple` and `max_mb` for a file.
+ */
+export interface FormField {
+  name: string;
+  /** None: the field stands alone, its question above it. */
+  label?: string;
+  kind: FieldKind;
+  required: boolean;
+  placeholder?: string;
+  /** A quiet line under it. */
+  help?: string;
+  options?: Option[];
+  min?: number;
+  max?: number;
+  step?: number;
+  unit?: string;
+  dates?: string[];
+  earliest?: string;
+  latest?: string;
+  times?: string[];
+  /** The kinds of file it takes: types, families ("image/*"), extensions (".xlsx"); none: any. */
+  accept?: string[];
+  /** More than one file. */
+  multiple?: boolean;
+  /** The most a file may weigh, in MB (50, the ceiling, by default). */
+  max_mb?: number;
+  /** What it starts with. */
+  value?: FieldValue;
+}
+/**
+ * Fields to fill; sending them sends `action` with the values by field name: words, a number,
+ * true or false, a date "YYYY-MM-DD", a time "HH:MM", a moment "YYYY-MM-DDTHH:MM", a
+ * multiselect's option ids, a file field's file ids.
+ */
+export interface FormBlock {
+  type: "form";
+  fields: FormField[];
+  /** None: the host's own word for sending (`KitMessages.send`). */
+  submit?: string;
+  action: string;
+}
+export interface DividerBlock {
+  type: "divider";
+}
+/** Blocks under a title: one thing, set apart. */
+export interface CardBlock {
+  type: "card";
+  title?: string;
+  subtitle?: string;
+  /** At its head's start: an app's logo, a product's picture (https). */
+  image?: string;
+  children: Block[];
+}
+/** Blocks laid out together: down, or across (wrapping on a narrow screen). */
+export interface StackBlock {
+  type: "stack";
+  direction: "column" | "row";
+  children: Block[];
+}
+export type Block = CardBlock | StackBlock | DividerBlock | TextBlock | FieldsBlock | TableBlock | ListBlock | StatBlock | ChartBlock | NoteBlock | ImageBlock | AutomationBlock | FileBlock | ButtonBlock | ChoiceBlock | FormBlock;
+/** What the agent shows: blocks, and the words a channel without a screen gets instead. */
+export interface Surface {
+  blocks: Block[];
+  text: string;
+}
+//#endregion
+//# sourceMappingURL=blocks.d.ts.map