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

package/README.md

@@ -185,6 +185,62 @@ couldn't begin again), `close`, `agent` (its name when the face can't be read),
 (`--text`, `--voice`; `aria-checked` on the one on), `sc-space__caption` (`--person`, `--agent`),
 `sc-space__status`.
 
+### Panels, modals and your own blocks
+
+What the agent shows can stand apart from the conversation (`show` and `ask_person` with
+`where`, v3/UI.md, Surfaces): in a **panel** beside the chat (over it, where the space is narrow:
+the rep's week while they talk), or in a **modal** over the page (something to answer now; once
+used it closes and the chat goes on). Each opens as it comes, and a conversation that opens
+waiting on one opens it; the reply keeps a quiet line, "Ray abrió tu semana" (`opened`), that
+opens it again. Your page decides what it allows: `surfaces={{ panel: true, modal: false }}`
+(both by default); a place left out shows in the conversation, as on a channel. `AgentChat`
+takes the same `surfaces`.
+
+`blocks` registers your own blocks by the name each was declared with (`PUT /v1/blocks/{name}`):
+`blocks={{ "demoprep.deal-card": DealCard }}`. The agent gives only props, which the API checked
+against your schema; your component gets `{props, text, active, onAction}` (`HostBlockProps`),
+and a block it has no component for shows its words in a quiet card (`sc-surface__host`).
+
+```tsx
+function DealCard({ props }: HostBlockProps<{ title: string; amount: number }>) {
+  return <YourDealCard title={props.title} amount={props.amount} />;
+}
+
+<AgentSpace
+  client={client}
+  agentId="agt_…"
+  surfaces={{ panel: true, modal: true }}
+  blocks={{ "demoprep.deal-card": DealCard }}
+/>;
+```
+
+Words: `opened(name, title)`, `closePlaced`. Parts: `sc-chat__placed` (`--open`), `sc-chat--placed`
+(a panel is open), `sc-placed` (`--panel`, `--modal`, the latter a `<dialog>`),
+`sc-placed__head`, `sc-placed__title`, `sc-placed__body`.
+
+### Threads, unread, and several yeses at once
+
+A person keeps several conversations (threads) with the agent, each with its title: one your
+backend opened for them (`conversations.start` with `contact`, `title`, `say`), one they began.
+`AgentSpace` shows a line over the chat, **Conversaciones**, with a dot while another thread has
+something for them; it lists them by title with how many of the agent's messages are unread, to
+go to one or start another (`threads={false}` turns it off). The chat reads what comes as it
+shows it on a person's page (`POST /conversations/{id}/read`), so `unread` follows; the widget's
+launcher wears a dot while something waits, for someone who talked before.
+
+For your own layout: `useUnread(client, agentId)` (`{threads, unread, waiting, refresh}`, read
+every 20 s and when the page comes back into sight), `<Threads threads current onSelect onNew
+onBack />` and `<Conversation client id … />` (the chat of one thread, `AgentChat`'s props).
+Words: `THREAD_MESSAGES`, `THREAD_MESSAGES_ES`. Parts: `sc-threads`, `sc-threads__head`,
+`sc-threads__title`, `sc-threads__list`, `sc-threads__item` (`--current`), `sc-threads__name`,
+`sc-threads__badge`, `sc-threads__dot`, `sc-space__threads`, `sc-space__dot`.
+
+When one reply waits on the person's yes for several actions, they come in one card
+(`sc-chat__requests`): a box ticked for each, what each would take under it, editable, and one
+button, **Aprobar todo** (or as many as are ticked), sending a yes for each ticked (with what was
+changed: `data.input`) and a no for the rest, in one `actions` frame. Words: `approvals`,
+`approveAll`, `approveSome`, `declineAll`.
+
 ## The widget
 
 `<signalcore-chat>` for pages without React: one script, React and the stylesheet inside it,
@@ -234,6 +290,10 @@ flow at the element's size (560px tall unless your CSS says). A visitor's conver
 | `stylesheet`      | your own CSS for the widget: the CSS itself (anything with a `{`) or its address; adopted inside the shadow root, after ours. Also the element's `stylesheet` property                                |
 | `unstyled`        | our look's defaults drop away (grounds, lines, shadows, corners, every ink but the page's text), the layout stays: for a host that styles everything                                                  |
 | `shadow`          | `none`: no shadow root; the widget draws in the page (our stylesheet goes first in `<head>`, so your CSS wins), for a host whose global CSS should apply directly. Read once, as the element connects |
+| `surfaces`        | where the agent may put what it shows besides the conversation: `panel`, `modal`, both (`"panel modal"`, the default) or none (`""`)                                                                  |
+
+Your own blocks go as the element's `blocks` property, React components the widget's React
+draws: `document.querySelector("signalcore-chat").blocks = { "demoprep.deal-card": DealCard }`.
 
 By default the widget takes your page's type and ink: the font, the base size and the text colour
 the element inherits come through the shadow root and stand in for our defaults (read as it draws,
@@ -317,23 +377,26 @@ from its credentials: `"business"` (our app's cookie) or `"person"` (a token, a
 visitor); the chat draws a yes the business decides by it, and shows a person none of the
 agent's steps (`steps`).
 
-| Method                                                                      | Does                                                                                                                                                                                                                                                     |
-| --------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `agents.face(id)`                                                           | what a person may know of the agent (`GET /agents/{id}/face`): `AgentFace {id, name, role, icon, voice: {enabled}}`                                                                                                                                      |
-| `agents.about(id)`                                                          | what the agent says about itself (`about`, null until written; `about_at`, null once stale) and its `facts`                                                                                                                                              |
-| `agents.describe(id)`                                                       | has the agent write about itself anew (a model call, a few seconds); answers like `about`                                                                                                                                                                |
-| `agents.files(id)`                                                          | the agent's own files (`StoredFile`: `id, path, media_type, size, searchable, created_at`), by path                                                                                                                                                      |
-| `agents.putFile(id, path, blob, searchable)`                                | stores the blob's bytes under the path (replacing a file of that name), its type as the file's; `searchable` makes it knowledge `search_files` reads (text, Markdown, JSON, YAML, PDF). 50 MB at most, 5 GB per organization                             |
-| `agents.deleteFile(id, path)`                                               | removes one of the agent's own files                                                                                                                                                                                                                     |
-| `agents.memories(id)`                                                       | what the agent remembered (`MemoryFact`: `id, text, created_at`), newest first                                                                                                                                                                           |
-| `agents.forget(id, memoryId)`                                               | takes one memory from it                                                                                                                                                                                                                                 |
-| `agents.call(id)`                                                           | the owner's call with the agent from our app (`POST /agents/{id}/voice/token`, `/api` only): `CallToken {url, token, room, call_id, conversation_id}`, LiveKit's address and a token for the call's room, and the call's conversation (a test), made now |
-| `files.list()` · `files.put(path, blob, searchable)` · `files.delete(path)` | the organization's files, shared with every agent: the same three as the agent's own                                                                                                                                                                     |
-| `conversations.get(id)`                                                     | one conversation with its messages, who answers it (`handled_by`: `agent`, `person` or `nobody`) and every change of it (`handovers`); on a channel, `channel`, `contact` (`muted`) and each message's `author`, `delivery` and `decision`               |
-| `conversations.start(agentId)`                                              | a new conversation with an agent                                                                                                                                                                                                                         |
-| `conversations.call(agentId)`                                               | a call with the agent for whoever may talk to it, a person's as theirs (`POST /agents/{id}/calls`): a `CallToken`, what `VoiceCall`'s `connect` answers, with the call's own conversation, made now, where what is said lands                            |
-| `channels.list(agentId?)`                                                   | the organization's channels, or one agent's (`Channel`: `id, agent_id, kind, provider, name, external_id, status, detail, settings, created_at`), the disconnected ones too                                                                              |
-| `liveUrl(conversationId, { fresh? })`                                       | the socket's address, signed in (a promise): `ws:` beside `http:` and `wss:` beside `https:`, with `?token=` (and `&visitor=`) but in our app; `fresh` asks `getToken` for a new token first                                                             |
+| Method                                                                      | Does                                                                                                                                                                                                                                                                                                                                  |
+| --------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `agents.face(id)`                                                           | what a person may know of the agent (`GET /agents/{id}/face`): `AgentFace {id, name, role, icon, voice: {enabled}}`                                                                                                                                                                                                                   |
+| `agents.about(id)`                                                          | what the agent says about itself (`about`, null until written; `about_at`, null once stale) and its `facts`                                                                                                                                                                                                                           |
+| `agents.describe(id)`                                                       | has the agent write about itself anew (a model call, a few seconds); answers like `about`                                                                                                                                                                                                                                             |
+| `agents.files(id)`                                                          | the agent's own files (`StoredFile`: `id, path, media_type, size, searchable, created_at`), by path                                                                                                                                                                                                                                   |
+| `agents.putFile(id, path, blob, searchable)`                                | stores the blob's bytes under the path (replacing a file of that name), its type as the file's; `searchable` makes it knowledge `search_files` reads (text, Markdown, JSON, YAML, PDF). 50 MB at most, 5 GB per organization                                                                                                          |
+| `agents.deleteFile(id, path)`                                               | removes one of the agent's own files                                                                                                                                                                                                                                                                                                  |
+| `agents.memories(id)`                                                       | what the agent remembered (`MemoryFact`: `id, text, created_at`), newest first                                                                                                                                                                                                                                                        |
+| `agents.forget(id, memoryId)`                                               | takes one memory from it                                                                                                                                                                                                                                                                                                              |
+| `agents.call(id)`                                                           | **app only** (`POST /agents/{id}/voice/token` is `/api`'s, 404 on `/v1`): the owner's call with the agent from our app, `CallToken {url, token, room, call_id, conversation_id}`, LiveKit's address and a token for the call's room, and the call's conversation (a test), made now. A host's page uses `conversations.call(agentId)` |
+| `files.list()` · `files.put(path, blob, searchable)` · `files.delete(path)` | the organization's files, shared with every agent: the same three as the agent's own                                                                                                                                                                                                                                                  |
+| `conversations.get(id)`                                                     | one conversation with its messages, who answers it (`handled_by`: `agent`, `person` or `nobody`) and every change of it (`handovers`); on a channel, `channel`, `contact` (`muted`) and each message's `author`, `delivery` and `decision`                                                                                            |
+| `conversations.list(agentId)`                                               | the agent's conversations, newest first (a person's own), each with `title`, `unread` and `waiting_on_person`                                                                                                                                                                                                                         |
+| `conversations.start(agentId, { title })`                                   | a new conversation with an agent, titled when given                                                                                                                                                                                                                                                                                   |
+| `conversations.read(id)`                                                    | how far the person has read it: all of it, now (the chat calls it as it shows what comes)                                                                                                                                                                                                                                             |
+| `conversations.rename(id, title)`                                           | its title, as the person gives it                                                                                                                                                                                                                                                                                                     |
+| `conversations.call(agentId)`                                               | a call with the agent for whoever may talk to it, a person's as theirs (`POST /agents/{id}/calls`): a `CallToken`, what `VoiceCall`'s `connect` answers, with the call's own conversation, made now, where what is said lands                                                                                                         |
+| `channels.list(agentId?)`                                                   | the organization's channels, or one agent's (`Channel`: `id, agent_id, kind, provider, name, external_id, status, detail, settings, created_at`), the disconnected ones too                                                                                                                                                           |
+| `liveUrl(conversationId, { fresh? })`                                       | the socket's address, signed in (a promise): `ws:` beside `http:` and `wss:` beside `https:`, with `?token=` (and `&visitor=`) but in our app; `fresh` asks `getToken` for a new token first                                                                                                                                          |
 
 ## The frames
 
@@ -378,15 +441,15 @@ from how the call's promise settled).
   the page and its answer goes up (each call once; one told again is answered again with what it
   gave; the turn stays under way until its step settles); without it each is refused with
   `NO_TOOL`. It answers `{ messages, draft, pending,
-awaiting, open, loading, error, say(text), act(action), stop(), browser,
+awaiting, open, loading, error, say(text), act(action), actAll(actions), stop(), browser,
 watchScreen(listener), control(to), input(event), holder, handovers }`. The history, read each
   time the socket opens and kept live by its frames;
   `pending` from the person's message to `done`, `stopped` or a turn error, `draft` the reply so
   far. What `step`, `ui` and `request` frames say lands on the reply's steps, so a message is
   the one place a step is drawn from, live or read back. `awaiting` is the step the turn waits
   on: a surface to answer, or an action waiting for the person's leave (the step's `request`,
-  `decides: "person"`; `act` on its id with `approve` or `decline`); `say` is refused until they
-  act. A yes the business gives (`decides: "business"`) waits on its step and holds nothing; the
+  `decides: "person"`; `act` on its id with `approve` or `decline`, `actAll` on several at once,
+  a yes's `data.input` changing what it runs with); `say` is refused until they act. A yes the business gives (`decides: "business"`) waits on its step and holds nothing; the
   person's answer on one, refused `business`, puts it back as the business's. `onError(code)`
   hears the socket's codes and `load` (the
   history could not be read): the host words them, the hook shows no text; `tool` (an answer of
@@ -509,7 +572,7 @@ an agent, the one a customer has on the phone, through LiveKit (`livekit-client`
 when it mounts and ends when it unmounts (key it on the attempt for another). It opens the
 microphone first (no call is made for someone who can't be heard), then asks `connect()` where to
 join (`{url, token}`: our API's `client.conversations.call(agentId)` answers both, with the
-call's conversation; `client.agents.call(id)` for the owner's test), joins the room and publishes the microphone; the agent's voice plays as it comes,
+call's conversation; `client.agents.call(id)` for the owner's test in our own app, never on `/v1`), joins the room and publishes the microphone; the agent's voice plays as it comes,
 and the call is on once the agent joins (its time counts from then).
 
 What it draws, centred: the `Orb`, large (`orbSize`, 280 px; `orb`: `"wave"`, the default, or
@@ -705,6 +768,48 @@ works, a check and "Conectada" in its place (`sc-surface__connect--done`), and a
 it failed. It changes as the connection does, from the `ui` frames the API sends again on the
 same id; before the API has asked for it (`connection` null), only the app as the agent named it.
 
+The kit's blocks of time and work: a `calendar` (`Agenda`: a day's events, or a week's from its
+`start`, at their hours; one with a `url` opens its page, with the calendar's `action` the rest
+send `{event}`; narrow, the days go one under another, an empty one a quiet line; 680px and up,
+the week stands as seven columns), a `timeline` (`Timeline`: dated things the newest first, each
+a dot on a hairline, in its `tone` when it has one, its `status` a quiet word), a `board`
+(`Kanban`: cards in columns; with its `action`, a card dragged to another column, or moved from
+its button's list of the others, goes there at once and sends `{card, column}`, labelled
+`board.moved`). A `host` block is one of yours, drawn by the component `blocks` registers under
+its `name` (a component that fails as it draws leaves its words, and the rest draws). Words:
+`calendar` (`allDay`, `empty`), `board` (`move`, `moveTo`, `moved`, `empty`). Parts:
+`sc-agenda` (`--day`), `sc-agenda__days`, `sc-agenda__day` (`--today`, `--empty`),
+`sc-agenda__date`, `sc-agenda__weekday`, `sc-agenda__number`, `sc-agenda__events`,
+`sc-agenda__event`, `sc-agenda__time`, `sc-agenda__what`, `sc-agenda__title`,
+`sc-agenda__detail`, `sc-agenda__empty`; `sc-timeline`, `sc-timeline__item` (`--info`,
+`--success`, `--warning`, `--danger`), `sc-timeline__dot`, `sc-timeline__body`,
+`sc-timeline__head`, `sc-timeline__title`, `sc-timeline__status`, `sc-timeline__when`,
+`sc-timeline__text`; `sc-board`, `sc-board__column` (`--over`), `sc-board__head`,
+`sc-board__title`, `sc-board__count`, `sc-board__cards`, `sc-board__card` (`--dragging`),
+`sc-board__card-title`, `sc-board__card-subtitle`, `sc-board__card-meta`, `sc-board__move`,
+`sc-board__menu`, `sc-board__empty`.
+
+## View
+
+`<View client name contact? blocks? components? classNames? messages? locale? onAction? />` draws
+an agent's view where your page puts it: what the agent keeps on show for each person (their
+next meeting, their week), a dashboard's spec rendered for one contact with their own rows
+(`GET /views/{name}/render`). With a person's token it is theirs; for the business, `contact`
+names whom (their id). It is read when shown and again every `VIEW_POLL_MS` (30 s), so it shows
+what the rows hold now; while it is first read an empty box holds its place, and a view that
+isn't there (or isn't the person's) draws nothing. `useView(client, name, contact?)` gives
+`{view, problem, gone}` for your own layout (`view.title`, `view.blocks`, `view.text`).
+
+```tsx
+<View
+  client={client}
+  name="proxima_reunion"
+  blocks={{ "demoprep.deal-card": DealCard }}
+  messages={KIT_MESSAGES_ES}
+  locale={es}
+/>
+```
+
 ## AgentAbout
 
 `<AgentAbout client agentId name messages? classNames? controls? apps? locale? view? onViewChange? onOpenFile? onOpenConversation? />`: Qué puede, made to sit

package/dist/AgentAbout.js

@@ -45,7 +45,9 @@ const ABOUT_MESSAGES = {
 		schedule: "At a time",
 		webhook: "When called",
 		event: "On an event",
-		platform: "On a message"
+		platform: "On a message",
+		manual: "When started",
+		after: "After another"
 	},
 	topics: {
 		apps: "Apps",
@@ -576,7 +578,9 @@ const KIND_ICONS = {
 	schedule: "clock",
 	webhook: "code",
 	event: "bell",
-	platform: "message"
+	platform: "message",
+	manual: "hand",
+	after: "check"
 };
 /** An app's mark: the host's logo when it draws one, else the provider's, bare. */
 function appMark(app, apps, size) {