hb-messages-box

Category: messaging · Tags: messaging, chat · Package: @htmlbricks/hb-messages-box

Overview

hb-messages-box is a chat shell that composes two child custom elements:

• hb-messages-list — renders the thread from your messages and authors data, with optional options passed through unchanged.
• hb-messages-send — provides the composer; when the user sends content, this host re-dispatches the child’s sendMessage event on itself so your page can hook a single transport layer.

Optional message JSON can seed the draft text in the composer. The host does not append new rows to messages for you after send; you typically update messages from your own handler (or your backend push layer).

Dependencies

The bundle registers hb-messages-list and hb-messages-send (same package version as this component). Styling and behavior details for the list and composer live in those packages’ documentation and extra/docs.ts files.

Styling

This element’s shadow root mainly handles layout (flex column, scrollable list region, composer strip). List and composer each ship Bulma in their own shadow trees; theme them with --bulma-* and component-specific variables documented on hb-messages-list and hb-messages-send.

Host CSS custom properties

| Variable | Default | Purpose | |----------|---------|---------| | --hb-messages-box-min-height | 100px | Minimum height of the host (:host). | | --hb-messages-box-list-min-height | 200px | Minimum height of the list + composer column (.hb-messages-box). |

CSS parts

| Part | Purpose | |------|---------| | msglist | Wrapper around hb-messages-list for host-level styling. | | msgsend | Wrapper around hb-messages-send for host-level styling. |

Slots

None.

Custom element

hb-messages-box

Attributes and properties (HTML)

Web component attributes are strings. Use snake_case names. Complex values must be JSON strings (e.g. messages='[{"id":"1",...}]'). Booleans elsewhere in the framework are often yes / no as strings; this component’s public payload is mostly JSON for messages, authors, options, and message.

| Attribute | Required | Description | |-----------|----------|-------------| | messages | Yes | JSON string: array of message objects (TMessage[]). | | authors | Yes | JSON string: array of participant objects (TAuthor[]). | | options | No | JSON string: bag forwarded to hb-messages-list (may be {}). | | message | No | JSON string: { "text"?: string } (and shapes your tooling accepts) to seed the composer draft; parsed on the client when provided as a string. | | id | No | Declared on the component type for optional host use. |

timestamp in JSON is typically an ISO date string after serialization; ensure your list implementation accepts the shape you pass.

Events

Listen for sendMessage on hb-messages-box. The detail is the same object hb-messages-send emits (this host forwards it without changing fields): text, id, tags (string array), and files (staged rows with id, name, mimetype, fileSize, content (File), optional objectUrl). Your handler should perform validation, upload files if needed, and update messages (and clear or adjust the composer via message / child state) according to your app rules.

Data shapes (TypeScript)

Authoring types for the thread and participants (types/webcomponent.type.d.ts):

export type TMessage = {
  id: string;
  text: string;
  timestamp: Date;
  type: "text" | "image" | "video" | "audio" | "file";
  status?: "pending" | "sent" | "received" | "read";
  system?: boolean;
  reply?: boolean;
  quotedMessageId?: string;
  authorId?: string;
  uri?: string;
};

export type TAuthor = {
  id: string;
  name: string;
  avatar?: string;
  status: "online" | "offline" | "away" | "busy";
  me?: boolean;
};

export type TMessageSend = {
  text?: string;
};

export type Component = {
  id?: string;
  style?: string;
  messages: TMessage[];
  authors: TAuthor[];
  options?: {
    showTimestamp?: boolean;
    showAvatar?: boolean;
    showName?: boolean;
    bubbles?: boolean;
  };
  message?: TMessageSend;
};

export type Events = {
  sendMessage: {
    text?: string;
    id: string;
    tags: string[];
    files: {
      id: string;
      name: string;
      mimetype: string;
      fileSize: number;
      content: File;
      objectUrl?: string;
    }[];
  };
};

The sendMessage detail matches hb-messages-send (types/webcomponent.type.d.ts there defines MessageSendFileItem for each file row).

Minimal HTML example

<hb-messages-box
  messages="[]"
  authors='[{"id":"u1","name":"You","status":"online","me":true}]'
></hb-messages-box>

Example with messages and send handler (vanilla JS)

<hb-messages-box id="chat"></hb-messages-box>
<script>
  const el = document.getElementById("chat");
  const authors = JSON.stringify([
    { id: "u1", name: "You", status: "online", me: true },
    { id: "u2", name: "Bot", status: "offline" },
  ]);
  let messages = [];
  function render() {
    el.setAttribute("messages", JSON.stringify(messages));
    el.setAttribute("authors", authors);
  }
  el.addEventListener("sendMessage", (e) => {
    const { text, id, tags, files } = e.detail;
    // Send to your API, then append a row and re-render:
    messages = [
      ...messages,
      {
        id: id,
        text: text || "",
        timestamp: new Date().toISOString(),
        type: "text",
        status: "pending",
        authorId: "u1",
      },
    ];
    render();
  });
  render();
</script>

Adjust field names and timestamp format to whatever hb-messages-list expects for your integration.