@signalcore/ui 1.0.0-beta.3 → 1.0.0-beta.4

package/src/client.ts

@@ -13,6 +13,7 @@ import type {
   FileLink,
   FilePreview,
   StoredFile,
+  ViewRendered,
 } from "./types";
 
 /**
@@ -153,6 +154,14 @@ export interface Client {
     /** One run of an automation with its record: every call it made, step by step. */
     get: (id: string) => Promise<RunRecord>;
   };
+  /** What an agent keeps on show for each person it serves (`compose_view`, `/agents/{id}/views`). */
+  views: {
+    /**
+     * A view rendered from the rows now: for a person, their own; for the business, for the
+     * contact it names (`contact`, their id).
+     */
+    render: (name: string, contact?: string) => Promise<ViewRendered>;
+  };
   /**
    * The tasks an agent runs for contacts, each with its newest runs: a person's own only (what
    * they asked the agent for in their conversations); the business's, every one.
@@ -366,6 +375,13 @@ export function createClient(options: ClientOptions): Client {
     runs: {
       get: (id) => json("GET", `/runs/${seg(id)}`),
     },
+    views: {
+      render: (name, contact) =>
+        json(
+          "GET",
+          `/views/${seg(name)}/render${contact === undefined ? "" : `?contact=${seg(contact)}`}`,
+        ),
+    },
     tasks: {
       list: (agentId) => json("GET", `/agents/${seg(agentId)}/tasks`),
       switch: (agentId, taskId, on) =>

package/src/contract.ts

@@ -247,6 +247,20 @@ export interface AutomationOut {
   last_run: RunOut | null;
 }
 
+/** What a host block is for, in a sentence the agent reads, and the JSON Schema of its props: an object's. */
+export interface BlockIn {
+  description: string;
+  schema: Record<string, unknown>;
+}
+
+export interface BlockOut {
+  name: string;
+  description: string;
+  schema: Record<string, unknown>;
+  created_at: string;
+  updated_at: string;
+}
+
 /** What the automation moves: its table's rows counted by the value of one field. */
 export interface Board {
   table: string;
@@ -255,6 +269,38 @@ export interface Board {
   counts: Array<Count>;
 }
 
+/** Cards in columns, a column per stage. With `action`, the person may move a card to another column, which sends `action` with `{"card": id, "column": id}`: the agent then does what moving it means. */
+export interface BoardBlock {
+  type: "board";
+  columns: Array<BoardColumn>;
+  action?: string | null;
+}
+
+/** One card of a board. */
+export interface BoardCard {
+  id: string;
+  title: string;
+  subtitle?: string | null;
+  meta?: string | null;
+}
+
+export interface BoardColumn {
+  id: string;
+  title: string;
+  cards: Array<BoardCard>;
+}
+
+/** The rows as cards in columns, a column per option of a choice (`column`). */
+export interface BoardPiece {
+  type: "board";
+  title: string;
+  item: string;
+  column: string;
+  subtitle?: string | null;
+  meta?: string | null;
+  query: Rows;
+}
+
 /** One thing the person can do: pressing it sends `action`, or, with `url`, opens the page (a payment, a document). Two buttons that do different things carry different action names: the name is the whole of what comes back. */
 export interface Button {
   type: "button";
@@ -264,6 +310,38 @@ export interface Button {
   tone?: "primary" | "neutral" | "danger";
 }
 
+/** A day's events, or a week's from `start`, at their hours. With `action`, pressing one sends it with `{"event": id}`; one with `url` opens its page instead. */
+export interface Calendar {
+  type: "calendar";
+  span?: "day" | "week";
+  start: string;
+  events: Array<CalendarEvent>;
+  action?: string | null;
+}
+
+/** One thing on a calendar: its title at its time (a day alone: all of it), until `end`, with a line of detail (where, with whom) and a page to open (`url`). */
+export interface CalendarEvent {
+  id: string;
+  title: string;
+  start: string;
+  end?: string | null;
+  detail?: string | null;
+  url?: string | null;
+}
+
+/** The rows whose date (`at`) falls today (`day`) or this week, at their hours: each called by `item`, until `end`, with `detail` under it and `link` (an https address) to open. */
+export interface CalendarPiece {
+  type: "calendar";
+  title: string;
+  span?: "day" | "week";
+  item: string;
+  at: string;
+  end?: string | null;
+  detail?: string | null;
+  link?: string | null;
+  query: Scope;
+}
+
 /** The call a conversation is (VOICE.md): the owner's in the browser or a phone call, when the worker took it and when it ended, why and how long. */
 export interface CallGlance {
   id: string;
@@ -290,7 +368,7 @@ export interface Card {
   title?: string | null;
   subtitle?: string | null;
   image?: string | null;
-  children: Array<Card | Stack | Divider | Text | Fields | Table | Listing | Stat | Chart | Note | Image | Button | Choice | Form | AutomationBlock | FileBlock>;
+  children: Array<Card | Stack | Divider | Text | Fields | Table | Listing | Stat | Chart | Note | Image | Button | Choice | Form | Calendar | Timeline | BoardBlock | AutomationBlock | FileBlock | HostBlock>;
 }
 
 /** A page of the apps a search finds. */
@@ -603,7 +681,7 @@ export interface DashboardOut {
 export interface DashboardView {
   id: string;
   title: string;
-  blocks: Array<Card | Stack | Divider | Text | Fields | Table | Listing | Stat | Chart | Note | Image | Button | Choice | Form | AutomationBlock | FileBlock>;
+  blocks: Array<Card | Stack | Divider | Text | Fields | Table | Listing | Stat | Chart | Note | Image | Button | Choice | Form | Calendar | Timeline | BoardBlock | AutomationBlock | FileBlock | HostBlock>;
   rendered_at: string;
 }
 
@@ -952,6 +1030,24 @@ export interface HolderIn {
   title?: string | null;
 }
 
+/** One of the host's own blocks, by the name it declared: `props` as its schema says (the API checks them against it), and `text`, the same in words, which a page that doesn't draw it shows instead, as a channel does. */
+export interface HostBlock {
+  type: "host";
+  name: string;
+  props: Record<string, unknown>;
+  text: string;
+}
+
+/** One of the host's own blocks: its `props` as given; with a rows `query`, one block per row, each prop of `fields` taken from that row's field. `text`: the same in words. */
+export interface HostPiece {
+  type: "host";
+  name: string;
+  text: string;
+  props?: Record<string, unknown>;
+  fields?: Record<string, string>;
+  query?: Rows | null;
+}
+
 /** The week, in the agent's time zone: each day's stretches, in order and apart; a day left out, or empty, is closed. */
 export interface Hours {
   mon?: Array<Span>;
@@ -1466,6 +1562,11 @@ export interface SchemasDecisionOut {
   run_id: string | null;
 }
 
+export interface Scope {
+  table: string;
+  where?: Array<Where>;
+}
+
 export interface SecretIn {
   value: string;
   hosts?: Array<string>;
@@ -1548,7 +1649,7 @@ export interface Span {
 export interface Stack {
   type: "stack";
   direction?: "column" | "row";
-  children: Array<Card | Stack | Divider | Text | Fields | Table | Listing | Stat | Chart | Note | Image | Button | Choice | Form | AutomationBlock | FileBlock>;
+  children: Array<Card | Stack | Divider | Text | Fields | Table | Listing | Stat | Chart | Note | Image | Button | Choice | Form | Calendar | Timeline | BoardBlock | AutomationBlock | FileBlock | HostBlock>;
 }
 
 /** One number that matters, under its label, with a line of context (a change, a goal). */
@@ -1729,6 +1830,33 @@ export interface TextPreview {
   truncated: boolean;
 }
 
+/** Dated things, one under another, the newest first. */
+export interface Timeline {
+  type: "timeline";
+  items: Array<TimelineItem>;
+}
+
+/** One thing on a timeline: what happened (or will) and when, a line about it, and where it stands: `status` in a word, `tone` its mark. */
+export interface TimelineItem {
+  id?: string | null;
+  at: string;
+  title: string;
+  text?: string | null;
+  status?: string | null;
+  tone?: "info" | "success" | "warning" | "danger" | null;
+}
+
+/** The rows by a date (`at`), the newest first: each called by `item`, with `text` under it and `status`, where it stands, in a word. */
+export interface TimelinePiece {
+  type: "timeline";
+  title: string;
+  item: string;
+  at: string;
+  text?: string | null;
+  status?: string | null;
+  query: Rows;
+}
+
 export interface TokenIn {
   agents: Array<string>;
   external_id: string;
@@ -1848,6 +1976,39 @@ export interface UsedOut {
   unpriced: number;
 }
 
+/** A view's name, title or blocks changed: only what is sent. */
+export interface ViewChange {
+  name?: string | null;
+  title?: string | null;
+  blocks?: Array<StatPiece | ChartPiece | TablePiece | ListPiece | NotePiece | CalendarPiece | TimelinePiece | BoardPiece | HostPiece> | null;
+}
+
+export interface ViewIn {
+  name: string;
+  title: string;
+  blocks: Array<StatPiece | ChartPiece | TablePiece | ListPiece | NotePiece | CalendarPiece | TimelinePiece | BoardPiece | HostPiece>;
+}
+
+export interface ViewOut {
+  id: string;
+  agent_id: string;
+  name: string;
+  title: string;
+  blocks: Array<StatPiece | ChartPiece | TablePiece | ListPiece | NotePiece | CalendarPiece | TimelinePiece | BoardPiece | HostPiece>;
+  created_at: string;
+  updated_at: string;
+}
+
+/** A view rendered for one contact: its blocks as the kit draws them, filled from the rows now, and `text`, the same in words (what a page that can't draw them shows). */
+export interface ViewRendered {
+  name: string;
+  title: string;
+  contact_id: string;
+  blocks: Array<Card | Stack | Divider | Text | Fields | Table | Listing | Stat | Chart | Note | Image | Button | Choice | Form | Calendar | Timeline | BoardBlock | AutomationBlock | FileBlock | HostBlock>;
+  text: string;
+  rendered_at: string;
+}
+
 /** How an agent talks on a call (VOICE.md). The defaults are the old product's, in Spanish: its ElevenLabs voice (Carolina, from Spain), up to ten minutes, a goodbye ends it. */
 export interface Voice {
   language?: string;
@@ -1919,10 +2080,10 @@ export interface WhatsAppIn {
   mode?: "cloud_api" | "coexistence";
 }
 
-/** One filter: the field compared with `value` by `op`. `last_days` keeps the rows whose date falls in the last `value` days; `contains` looks for words in a text. */
+/** One filter: the field compared with `value` by `op`. `last_days` keeps the rows whose date falls in the last `value` days, `next_days` those in the next `value` days (from now on); `contains` looks for words in a text. */
 export interface Where {
   field: string;
-  op?: "eq" | "ne" | "gt" | "gte" | "lt" | "lte" | "contains" | "last_days";
+  op?: "eq" | "ne" | "gt" | "gte" | "lt" | "lte" | "contains" | "last_days" | "next_days";
   value: string | number | boolean;
 }
 

package/src/es.ts

@@ -233,6 +233,13 @@ export const KIT_MESSAGES_ES: KitMessages = {
     failed: "No se ha podido conectar",
     preparing: "Preparando la conexión",
   },
+  calendar: { allDay: "Todo el día", empty: "Nada previsto" },
+  board: {
+    move: (card) => `Mover ${card}`,
+    moveTo: "Mover a",
+    moved: (card, column) => `${card} a ${column}`,
+    empty: "Nada aquí",
+  },
 };
 
 export const BROWSER_MESSAGES_ES: BrowserMessages = {
@@ -321,6 +328,8 @@ export const CHAT_MESSAGES_ES: ChatMessages = {
   declineAll: "Rechazar todo",
   confirming: "Esperando la confirmación del negocio",
   handedOff: "Pasada a una persona",
+  opened: (name, title) => `${name} abrió ${title}`,
+  closePlaced: "Cerrar",
   handover: (holder, by, name) => {
     const automation = by.kind === "automation" ? ` por «${by.title}»` : "";
     switch (holder) {

package/src/index.ts

@@ -144,7 +144,12 @@ export type {
 export type {
   AutomationBlock,
   Block,
+  BoardBlock,
+  BoardCard,
+  BoardColumn,
   ButtonBlock,
+  CalendarBlock,
+  CalendarEvent,
   CardBlock,
   ChartBlock,
   ChartPoint,
@@ -156,15 +161,19 @@ export type {
   FieldValue,
   FormBlock,
   FormField,
+  HostBlock,
   ImageBlock,
   ListBlock,
   NoteBlock,
   Option,
+  Place,
   StackBlock,
   StatBlock,
   Surface as SurfaceData,
   TableBlock,
   TextBlock,
+  TimelineBlock,
+  TimelineItem,
   Tone,
 } from "./blocks";
 export { ApiError, createClient } from "./client";
@@ -179,6 +188,8 @@ export { FILES_PER_MESSAGE, TOOL_ERROR_MAX, toolResultOf } from "./frames";
 export type { Frame, ToolResult, UpFrame } from "./frames";
 export { Button } from "./kit/Button";
 export type { ButtonProps } from "./kit/Button";
+export { Agenda, daysOf, hoursOf } from "./kit/Agenda";
+export { Kanban, placed } from "./kit/Kanban";
 export { Card } from "./kit/Card";
 export { Chips, Choices } from "./kit/Choices";
 export { Combobox } from "./kit/Combobox";
@@ -203,7 +214,7 @@ export { Mark } from "./kit/Mark";
 export type { MarkProps } from "./kit/Mark";
 export { MarkStack } from "./kit/MarkStack";
 export { KIT_MESSAGES } from "./kit/messages";
-export type { KitLocale, KitMessages } from "./kit/messages";
+export type { BoardMessages, CalendarMessages, KitLocale, KitMessages } from "./kit/messages";
 export { Note } from "./kit/Note";
 export { RangeField } from "./kit/RangeField";
 export { RatingField } from "./kit/RatingField";
@@ -213,11 +224,22 @@ export { AudioPlayer } from "./kit/AudioPlayer";
 export type { AudioPlayerProps } from "./kit/AudioPlayer";
 export type { SwitchProps } from "./kit/Switch";
 export { Tag } from "./kit/Tag";
+export { formatWhen, Timeline } from "./kit/Timeline";
 export { Tile, Tiles } from "./kit/Tile";
 export type { TileProps } from "./kit/Tile";
 export { DateTimeField, TimeField } from "./kit/TimeField";
 export type { DateTimeFieldProps, TimeFieldProps } from "./kit/TimeField";
-export type { BlockProps, SurfaceComponents, SurfacePart } from "./surface/scope";
+export type {
+  BlockProps,
+  HostBlockProps,
+  HostBlocks,
+  SurfaceComponents,
+  SurfacePart,
+} from "./surface/scope";
+export { EVERY_PLACE, placeOf } from "./surface/places";
+export type { SurfacePlaces } from "./surface/places";
+export { Placed } from "./surface/Placed";
+export type { PlacedPart } from "./surface/Placed";
 export { Surface } from "./surface/Surface";
 export type { SurfaceProps } from "./surface/Surface";
 export { chosen, filled, labelOf, picked, pressed, problemOf } from "./surface/values";
@@ -263,6 +285,7 @@ export type {
   StepState,
   StoredFile,
   ToolCall,
+  ViewRendered,
   Weekday,
   WeekHours,
   WidgetConfig,
@@ -271,6 +294,8 @@ export type {
 } from "./types";
 export { WIDGET_FONTS } from "./types";
 export { useAgentFace } from "./useAgentFace";
+export { View, VIEW_POLL_MS, useView } from "./View";
+export type { ViewProps, ViewRead } from "./View";
 export type { FaceRead } from "./useAgentFace";
 export { NO_TOOL, useConversation } from "./useConversation";
 export type { LiveConversation, ToolHandler } from "./useConversation";

package/src/kit/Agenda.tsx

@@ -0,0 +1,161 @@
+import { Fragment, type ReactNode } from "react";
+
+import type { CalendarEvent } from "../blocks";
+import { useKit, useParts } from "./context";
+import { dayOf, formatTime, isoDay, momentParts, TIME } from "./dates";
+
+/** The days a calendar shows from its first: a day's, or a week's. */
+export function daysOf(span: "day" | "week", start: string): string[] {
+  const first = dayOf(start);
+  if (!first) return [];
+  return Array.from({ length: span === "week" ? 7 : 1 }, (_, index) => {
+    const day = new Date(first);
+    day.setDate(first.getDate() + index);
+    return isoDay(day);
+  });
+}
+
+/** An event's hours as the language writes them: "10:00 – 11:00", one end, or none (a day). */
+export function hoursOf(event: CalendarEvent, code: string): string | null {
+  const [day, from] = momentParts(event.start);
+  if (!TIME.test(from)) return null;
+  const [endDay, to] = momentParts(event.end ?? null);
+  const until = endDay === day && TIME.test(to) ? to : null;
+  return until === null
+    ? formatTime(from, code)
+    : `${formatTime(from, code)} – ${formatTime(until, code)}`;
+}
+
+/**
+ * A day's events, or a week's, at their hours: each day under its weekday and number (today in
+ * the accent), its events in order, each with its hours (or "all day"), its title and a quiet
+ * line of detail. In a narrow place the days go one under another, an empty one a single quiet
+ * line; wide enough, the week stands as seven columns. An event with a page opens it apart;
+ * with `onEvent`, pressing one sends it.
+ */
+export function Agenda({
+  span,
+  start,
+  events,
+  onEvent,
+  disabled = false,
+  today = new Date(),
+}: {
+  span: "day" | "week";
+  /** The first day shown, "YYYY-MM-DD". */
+  start: string;
+  events: CalendarEvent[];
+  onEvent?: ((event: CalendarEvent) => void) | undefined;
+  disabled?: boolean | undefined;
+  /** What counts as today; now by default. */
+  today?: Date | undefined;
+}) {
+  const part = useParts();
+  const { code, messages } = useKit();
+  const now = isoDay(today);
+  const days = daysOf(span, start);
+  const weekday = new Intl.DateTimeFormat(code, { weekday: "short" });
+  const whole = new Intl.DateTimeFormat(code, { weekday: "long", day: "numeric", month: "long" });
+  return (
+    <div
+      part="agenda"
+      className={part("sc-agenda", ...(span === "day" ? (["sc-agenda--day"] as const) : []))}
+    >
+      <div className={part("sc-agenda__days")}>
+        {days.map((day) => {
+          const date = dayOf(day) ?? today;
+          const own = events.filter((event) => event.start.slice(0, 10) === day);
+          return (
+            <section
+              key={day}
+              aria-label={whole.format(date)}
+              className={part(
+                "sc-agenda__day",
+                ...(day === now ? (["sc-agenda__day--today"] as const) : []),
+                ...(own.length === 0 ? (["sc-agenda__day--empty"] as const) : []),
+              )}
+            >
+              {span === "week" && (
+                <h4 aria-hidden className={part("sc-agenda__date")}>
+                  <span className={part("sc-agenda__weekday")}>{weekday.format(date)}</span>
+                  <span className={part("sc-agenda__number")}>{date.getDate()}</span>
+                </h4>
+              )}
+              {own.length === 0 ? (
+                <p className={part("sc-agenda__empty")}>{messages.calendar.empty}</p>
+              ) : (
+                <ol className={part("sc-agenda__events")}>
+                  {own.map((event) => (
+                    <li key={event.id}>
+                      <Event event={event} onEvent={onEvent} disabled={disabled}>
+                        <span className={part("sc-agenda__time")}>
+                          {(hoursOf(event, code) ?? messages.calendar.allDay)
+                            .split(" – ")
+                            .map((end, index) =>
+                              // A range breaks before its dash, never inside a time ("5:00 PM").
+                              index === 0 ? (
+                                <span key={index}>{end}</span>
+                              ) : (
+                                <Fragment key={index}>
+                                  {" "}
+                                  <span>– {end}</span>
+                                </Fragment>
+                              ),
+                            )}
+                        </span>
+                        <span className={part("sc-agenda__what")}>
+                          <span className={part("sc-agenda__title")}>{event.title}</span>
+                          {event.detail !== undefined && (
+                            <span className={part("sc-agenda__detail")}>{event.detail}</span>
+                          )}
+                        </span>
+                      </Event>
+                    </li>
+                  ))}
+                </ol>
+              )}
+            </section>
+          );
+        })}
+      </div>
+    </div>
+  );
+}
+
+/** One event: a link to its page, a button that sends it, or just its words. */
+function Event({
+  event,
+  onEvent,
+  disabled,
+  children,
+}: {
+  event: CalendarEvent;
+  onEvent: ((event: CalendarEvent) => void) | undefined;
+  disabled: boolean;
+  children: ReactNode;
+}) {
+  const part = useParts();
+  const className = part("sc-agenda__event");
+  if (event.url !== undefined && /^https:\/\//i.test(event.url)) {
+    return (
+      <a className={className} href={event.url} target="_blank" rel="noreferrer noopener">
+        {children}
+      </a>
+    );
+  }
+  if (onEvent !== undefined) {
+    return (
+      <button
+        type="button"
+        className={className}
+        disabled={disabled}
+        onClick={() => {
+          onEvent(event);
+        }}
+      >
+        {children}
+      </button>
+    );
+  }
+  return <div className={className}>{children}</div>;
+}