@konce-pt/angular 0.8.3 → 0.9.0

package/chat/src/lib/llms.txt

@@ -0,0 +1,160 @@
+# KptChat (kpt-chat, kpt-chat-message, kpt-chat-typing, kpt-chat-composer, kpt-chat-dock)
+
+A conversation: a grouped message list, a typing indicator, a composer and a floating dock in the
+corner of the screen. The row-building core — grouping, day separators, send-status arithmetic —
+lives in `@konce-pt/chat`: plain TypeScript, tested, shared with the React port.
+
+Import: `import { KptChat, KptChatComposer, KptChatDock, KptChatMessage, KptChatTyping } from '@konce-pt/angular/chat';`
+
+The library covers presentation and the local state of the list. Transport — a socket, HTTP, retry
+with backoff — stays in the application: the component takes messages and only reports `(retry)`
+and `(loadMore)`.
+
+## KptChat — inputs / outputs
+- `messages: readonly KptChatMessage<T>[]` — **in chronological order**; the component does not sort
+- `currentUser: string` — the author id treated as "me": those messages go right and carry a status
+- `groupGapMs: number` (default `KPT_CHAT_GROUP_GAP_MS`, 5 min) — the silence that breaks a group
+- `unreadFrom: string | null` — the id of the first unread message; the divider goes above it
+- `offline: boolean` — the warning strip with a count of messages waiting to be sent
+- `typing: readonly KptChatAuthor[]` — who is typing right now
+- `autoScroll: boolean` (default true), `actions: boolean`, `emptyLabel: string`
+- `reactionOptions: readonly KptChatReactionOption[]` (default `KPT_CHAT_REACTIONS`) — passed to the bubbles
+- `(retry)`, `(reply)` → `KptChatMessage<T>`; `(react)` → `KptChatReactEvent<T>` (`{ message, emoji }`);
+  `(quoted)` → `KptChatReplyRef`; `(loadMore)` → `void`, fired when the viewport reaches the top
+
+## Example
+    <kpt-chat
+      [messages]="messages()"
+      currentUser="me"
+      [typing]="typing()"
+      [offline]="offline()"
+      (retry)="resend($event)"
+      (loadMore)="loadOlder()"
+    />
+    <kpt-chat-composer allowAttachments [offline]="offline()" (send)="onSend($event)" />
+
+The composer is a sibling, not a slot: a read-only conversation (an archive, a preview) should not
+have to carry a text field it never shows.
+
+## Custom bubble content
+An `<ng-template>` inside `<kpt-chat>` replaces the bubble's text; the context is the message as
+`$implicit` and the whole row as `row`. The bubble, its grouping and its meta row stay in place —
+only the content is yours.
+
+    <kpt-chat [messages]="messages()" currentUser="me">
+      <ng-template let-message><kpt-card>{{ message.data.title }}</kpt-card></ng-template>
+    </kpt-chat>
+
+## KptChatMessage — the bubble on its own
+Works with a whole `[message]` object or with single inputs (`author`, `text`, `time`, `status`,
+`attachments`, `reactions`, `replyTo`), and takes projected content, so it renders anything.
+- `align`: 'start' | 'end' — someone else's message versus your own
+- `variant`: 'neutral' | 'primary' | 'solid' | 'ghost' | 'system'
+- `position`: 'single' | 'first' | 'middle' | 'last' — the place in a group
+- `showAuthor` / `showAvatar` / `showMeta` / `tail` / `actions`: boolean
+- `reactionOptions`: `readonly KptChatReactionOption[]` (default `KPT_CHAT_REACTIONS`) — the picker set
+
+The default variant follows the alignment: your own message gets the full `solid`, someone else's
+gets `neutral`. The theme is monochrome, so the difference between bubbles is lightness, not hue —
+`--kpt-color-primary-subtle` has exactly the lightness of `--kpt-color-muted`, which would make the
+two sides indistinguishable. For a quieter list set `variant="primary"` by hand.
+
+## Bubble actions: reply and react
+`actions` puts two buttons beside the bubble, shown on hover and on focus. The arrow emits
+`(reply)` with the whole message — `replyRefFrom()` from `@konce-pt/chat` turns it into the
+`replyTo` the composer's quote bar wants. The smiley opens a picker of five reactions (like, heart,
+smile, wow, sad — `KPT_CHAT_REACTIONS`, overridable through `reactionOptions`) and emits `(react)`
+with the chosen emoji.
+
+Neither one writes to the model: the library says what was clicked, the application decides what
+the conversation looks like afterwards. `toggleReaction(message.reactions, emoji)` does that
+arithmetic — it adds the reaction, takes it back on a second click and drops an entry that reaches
+zero, keeping the order of the rest.
+
+    (reply)="replyTo.set(replyRefFrom($event))"
+    (react)="onReact($event)"   // toggleReaction(item.reactions, $event.emoji)
+
+The picker closes on Escape, on a click outside and on picking; an option already given is marked
+`aria-pressed`, so it is visible which one the next click takes back. The retry arrow of a failed
+message takes the place of both — a message that has not gone out has nothing to reply to yet.
+
+## Grouping is what the shape is made of
+`position` decides which corner collapses, which bubble wears the tail, carries the avatar and shows
+the clock. Inside a group the corner on the sender's side drops to `--kpt-radius-sm`, so the bubbles
+read as one utterance. `kpt-chat` gets all of it from `buildChatRows()`; set it by hand only when
+you build the list yourself.
+
+A group breaks on a different author, a gap longer than `groupGapMs`, a calendar-day boundary, a
+system message and the unread divider.
+
+The bubble that wears the tail has a **square** bottom corner on that side — a rounded one curved
+away from the tail and the list background showed through the gap, which made the tail read as a
+separate arrow stuck next to the bubble rather than a part of it. Bubbles without a tail keep the
+rounded corner.
+
+## One day pill, not a stack of them
+The separators in the list travel with the content; which day the view is standing in is told by one
+pill floating over the list (`.kpt-chat__day`, `aria-hidden`, outside the scrolling area). Sticky
+separators looked right until the first collision: every next one pinned to the same edge, so a stack
+of frames grew up there and the older, wider pills stuck out from behind the newest.
+
+On every scroll (and after every re-render and resize) the component measures the separators, the
+unread divider and the system notices, hands the rectangles to `chatDayIndicator()` from
+`@konce-pt/chat` and swaps the pill's text. A centred label driving into the pill's band puts the
+pill out — it is the pill that yields, never the content — and with a separator that is also the
+handover, since the arriving "Today" says the same thing. Bubbles are not blockers: a pill over an
+utterance is the normal chat picture. The pill keeps its last label while it is out, so its band does
+not change height under the script that measures it.
+
+## An unsent message must be able to say so
+`status: 'failed'` outlines the bubble with `--kpt-color-danger-border` and puts a retry arrow
+**outside** it, on the outer side of the list. That bubble also shows its meta row even in the
+middle of a group — the arrow with nothing to explain it would be a mystery.
+Statuses: `sending`, `sent`, `delivered`, `read` (the same double check, in the accent colour) and
+`failed`. Out-of-order acks are what `mergeStatus()` from `@konce-pt/chat` is for.
+
+## KptChatComposer
+`[(value)]`, `placeholder`, `disabled`, `offline`, `allowAttachments`, `maxRows` (default 6),
+`enterToSend` (default true), `[(replyTo)]`, `(send)` → `{ text, files, replyTo }`, `(typing)`.
+Enter sends, Shift+Enter breaks the line; `enterToSend=false` swaps the two. The field grows with
+the content up to `maxRows` and then scrolls.
+
+It is **not** a Signal Forms control and will not become one: it never enters a form, has no
+`touched`/`invalid` state, and its value disappears on send. `model('')` describes that honestly.
+
+## KptChatDock
+`[(open)]`, `position` ('bottom-end' | 'bottom-start'), `unread`, `header`, `icon`, `width`,
+`offset` (distance from the corner, both axes, default `--kpt-space-6`).
+
+## Sharing the corner with kpt-scroll-top
+`kpt-scroll-top` pins itself to the same spot with the same `--kpt-z-overlay`, and it would swallow
+the chat FAB whole — only the unread badge would stick out, and the button could not be clicked.
+The stylesheet resolves it by itself: when a `bottom-end` dock is on the page, the scroll-top button
+steps **aside** (`:root:has()` shifts it left by the width of the FAB plus a gap). Sideways, not up,
+because the conversation panel stands above the FAB — moving it up would trade one collision for a
+worse one, with the button landing on the messages.
+It applies to `bottom-end` only, and it measures from the default offset: an application that sets
+`offset` positions the scroll-top button itself.
+The FAB is `kpt-fab` — the dock uses it, it does not replace it. The panel content is projected, so
+the dock knows nothing about messages. Opening moves focus to the composer, `Escape` closes and
+returns focus to the FAB. Below `--kpt-breakpoint-sm` the panel goes full-screen.
+
+    <kpt-chat-dock [(open)]="open" [unread]="unread()" header="Support">
+      <kpt-chat [messages]="messages()" currentUser="me" />
+      <kpt-chat-composer (send)="onSend($event)" />
+    </kpt-chat-dock>
+
+## Accessibility
+The list is `role="log"` with `aria-live="polite"`, so a new message is announced without cutting
+off what is being read. Each bubble is an `article` labelled with author, time and status — content
+alone would say nothing about who wrote it or whether it was sent. The typing indicator is
+`role="status"`; under `prefers-reduced-motion` the dots stop bouncing and pulse instead — they are
+the only carrier of "someone is typing", so switching them off entirely would remove the message.
+
+## Tokens
+Bubble `--kpt-color-muted` (incoming) / `--kpt-color-primary` + `--kpt-color-on-primary` (own);
+failed `--kpt-color-danger-subtle` + `--kpt-color-danger-border`; offline strip
+`--kpt-color-warning-subtle`; the day pill `--kpt-color-surface-raised` + a border and
+`--kpt-elevation-1` (the same look in the list and floating above it — the floating one travels over
+the bubbles and has to stand apart from them); dock `--kpt-elevation-3`
+and `--kpt-z-overlay`.