Messages widget

Chat icon with an unread badge. Click navigates to Cobuntu's /conversations surface. Badge polls the messaging service every 60s while the page is visible.

Install

<script src="/widgets/v1/messages.js" async></script>
<div data-cobuntu-messages></div>

Why not embed the chat UI itself

Chat runs sockets, conversation streams, composition, attachments, voice notes. Bundling that into a third-party widget would balloon the bundle 30–50× and create state-sync nightmares with the React app on Cobuntu pages. The widget intentionally stays as a navigation affordance + unread indicator; the real UI lives at /conversations.

Three levels of customization

Level 1 — CSS variables

--cobuntu-bg, --cobuntu-color, --cobuntu-border, --cobuntu-radius, --cobuntu-padding, --cobuntu-font, --cobuntu-font-size, --cobuntu-hover-color, --cobuntu-badge-bg, --cobuntu-badge-text.

Level 2 — data attributes

Attribute	Values	Default
`data-variant`	`icon` \| `button`	`icon`
`data-size`	`sm` \| `md` \| `lg`	`md`
`data-show-badge`	`true` \| `false`	`true`
`data-label`	string (aria-label)	`Messages`
`data-button-label`	string (button variant)	`Messages`
`data-require-auth`	`prompt` \| `hide`	`prompt`

require-auth=hide removes the widget entirely for logged-out users. prompt shows it; click bounces to /login?next=/conversations.

Level 3 — render-yourself slot

<div data-cobuntu-messages>
  <button data-cobuntu-action="open-messages" class="my-icon-btn">
    <svg>…my own icon…</svg>
    <span data-cobuntu-bind="unread-count"
          data-cobuntu-show="has-unread"
          class="my-badge">0</span>
  </button>
</div>

Bindings: data-cobuntu-bind="unread-count", data-cobuntu-show="has-unread|no-unread", data-cobuntu-action="open-messages".

Auth gating

Unread API requires auth. Logged-out users with data-require-auth="prompt" see the icon without a badge; click goes through /login and back to /conversations. With data-require-auth="hide" the widget is invisible.

Public JS API

window.CobuntuMessages = {
  unread(): number,
  refresh(): Promise<void>,
  open(): void,  // navigate to /conversations (or login if needed)
};

Versioning

v1 frozen. Breaking changes ship as v2 under /widgets/v2/messages.js.

Auth Notifications