@blogmcp/community 0.0.0-stage → 0.1.0

package/src/element.ts

@@ -0,0 +1,109 @@
+/// <reference path="./shims.d.ts" />
+/**
+ * The three custom elements (Vue inside a shadow root each), m1-contracts.md §10.4:
+ *
+ *   <blogmcp-discussion>    article-id, api-base, site-base, lang, sign-in-href, routes, poll-ms, nonce
+ *   <blogmcp-notice-form>   api-base, site-base, lang, turnstile-site-key, target | article-id, routes, nonce
+ *   <blogmcp-my-community>  api-base, site-base, lang, decision-id, routes, sign-in-href, nonce
+ *
+ * Each carries ONE inline stylesheet in its shadow root, with the CSP nonce honoured: the one given when the
+ * elements are defined (the script build passes `document.currentScript.nonce`), else the element's own
+ * `nonce` — read from the property, because a page with a CSP hides the attribute once it is connected.
+ */
+import { defineCustomElement, type Component } from 'vue'
+import DiscussionView from './ui/DiscussionView.vue'
+import MyCommunityView from './ui/MyCommunityView.vue'
+import NoticeFormView from './ui/NoticeFormView.vue'
+import css from './ui/styles.css?inline'
+
+/**
+ * Vue's ESM build reads three compile-time flags as globals, and only a bundler running Vue's own plugin
+ * defines them. A React site (or any bundler without `@vitejs/plugin-vue`) leaves them undefined, and mounting
+ * the element then throws `__VUE_PROD_DEVTOOLS__ is not defined` (the review layer met it on the drhoubicka
+ * storefront, 2026-10-02). Give them Vue's documented defaults when nothing did; a site that set them keeps
+ * its values.
+ */
+function ensureVueFeatureFlags(): void {
+  const g = globalThis as Record<string, unknown>
+  const defaults: Record<string, boolean> = {
+    __VUE_OPTIONS_API__: true,
+    __VUE_PROD_DEVTOOLS__: false,
+    __VUE_PROD_HYDRATION_MISMATCH_DETAILS__: false,
+  }
+  for (const [flag, value] of Object.entries(defaults)) if (typeof g[flag] === 'undefined') g[flag] = value
+}
+
+export const DISCUSSION_ELEMENT_TAG = 'blogmcp-discussion'
+export const NOTICE_FORM_ELEMENT_TAG = 'blogmcp-notice-form'
+export const MY_COMMUNITY_ELEMENT_TAG = 'blogmcp-my-community'
+
+export interface DefineCommunityElementOptions {
+  /** Another tag name for the element. */
+  tag?: string
+  /** CSP nonce for the element's `<style>` (else each element's own `nonce`). */
+  nonce?: string
+}
+
+export interface DefineCommunityElementsOptions {
+  /** CSP nonce for the elements' `<style>`. */
+  nonce?: string
+  tags?: { discussion?: string; noticeForm?: string; myCommunity?: string }
+}
+
+/** The element's own nonce: the property (a CSP hides the attribute once connected), else the attribute. */
+function ownNonce(el: HTMLElement): string | undefined {
+  const fromProperty = (el as HTMLElement & { nonce?: unknown }).nonce
+  if (typeof fromProperty === 'string' && fromProperty !== '') return fromProperty
+  return el.getAttribute('nonce') || undefined
+}
+
+function communityElement(component: Component, defineNonce: string | undefined): CustomElementConstructor {
+  // No `styles` option: the stylesheet is put in below, so a per-element nonce can be honoured.
+  const Base = defineCustomElement(component as Parameters<typeof defineCustomElement>[0])
+  return class CommunityElement extends Base {
+    override connectedCallback(): void {
+      const own = ownNonce(this)
+      const nonce = defineNonce || own
+      // The element carries the nonce it uses (the IDL property, which a CSP never hides), so what it loads
+      // later — the notice form's Turnstile script — gets the same one, the script build's included.
+      if (nonce && !own) (this as HTMLElement & { nonce: string }).nonce = nonce
+      const root = this.shadowRoot
+      if (root && !root.querySelector('style[data-bcm]')) {
+        const style = document.createElement('style')
+        style.setAttribute('data-bcm', '')
+        if (nonce) style.setAttribute('nonce', nonce)
+        style.textContent = css
+        root.prepend(style)
+      }
+      super.connectedCallback()
+    }
+  }
+}
+
+function define(tag: string, component: Component, nonce: string | undefined): void {
+  if (typeof customElements === 'undefined' || customElements.get(tag)) return
+  ensureVueFeatureFlags()
+  customElements.define(tag, communityElement(component, nonce))
+}
+
+/** Register `<blogmcp-discussion>` (once; later calls are no-ops). Browser only. */
+export function defineDiscussionElement(opts: DefineCommunityElementOptions = {}): void {
+  define(opts.tag ?? DISCUSSION_ELEMENT_TAG, DiscussionView, opts.nonce)
+}
+
+/** Register `<blogmcp-notice-form>` (once). Browser only. */
+export function defineNoticeFormElement(opts: DefineCommunityElementOptions = {}): void {
+  define(opts.tag ?? NOTICE_FORM_ELEMENT_TAG, NoticeFormView, opts.nonce)
+}
+
+/** Register `<blogmcp-my-community>` (once). Browser only. */
+export function defineMyCommunityElement(opts: DefineCommunityElementOptions = {}): void {
+  define(opts.tag ?? MY_COMMUNITY_ELEMENT_TAG, MyCommunityView, opts.nonce)
+}
+
+/** Register all three (once). Browser only. */
+export function defineCommunityElements(opts: DefineCommunityElementsOptions = {}): void {
+  defineDiscussionElement({ tag: opts.tags?.discussion, nonce: opts.nonce })
+  defineNoticeFormElement({ tag: opts.tags?.noticeForm, nonce: opts.nonce })
+  defineMyCommunityElement({ tag: opts.tags?.myCommunity, nonce: opts.nonce })
+}

package/src/global.ts

@@ -0,0 +1,12 @@
+/**
+ * The `<script>` build: registers `<blogmcp-discussion>`, `<blogmcp-notice-form>` and `<blogmcp-my-community>`
+ * with the script tag's own CSP nonce, and exposes `window.BlogmcpCommunity`.
+ */
+import { defineCommunityElements } from './element'
+import { mountDiscussion, mountMyCommunity, mountNoticeForm } from './mount'
+import { VERSION } from './version'
+
+const script = typeof document !== 'undefined' ? (document.currentScript as HTMLScriptElement | null) : null
+defineCommunityElements({ nonce: script?.nonce || undefined })
+
+export { defineCommunityElements, mountDiscussion, mountMyCommunity, mountNoticeForm, VERSION }

package/src/index.ts

@@ -0,0 +1,35 @@
+/**
+ * @blogmcp/community — the community's elements for a site's own pages (m1-contracts.md §10.4; docs: "Add
+ * discussions to your frontend"), over `@blogmcp/sdk/community`. Every element talks to the HOST's relative
+ * base (`api-base`; default `/api/community` under the site's `site-base`: a headless site's BFF from
+ * `@blogmcp/sdk/community/server`, or with `site-base="/blog"` a managed blog's own proxy), never to kb-api directly.
+ *
+ *   - `<blogmcp-discussion>`   the discussion under an article;
+ *   - `<blogmcp-notice-form>`  the DSA notice form, for anyone;
+ *   - `<blogmcp-my-community>` the reader's „Moje komunita", a statement page, a notifier's status page;
+ *   - `defineCommunityElements()` and one `define…Element()` each — the custom elements;
+ *   - `mountDiscussion(…)`, `mountNoticeForm(…)`, `mountMyCommunity(…)` — mount one from code;
+ *   - `@blogmcp/community/vue`, `@blogmcp/community/react` — `<KbDiscussion>`, `<KbNoticeForm>`, `<KbMyCommunity>`;
+ *   - `@blogmcp/community/global` — one `<script>` for sites without a bundler.
+ */
+export {
+  defineCommunityElements,
+  defineDiscussionElement,
+  defineNoticeFormElement,
+  defineMyCommunityElement,
+  DISCUSSION_ELEMENT_TAG,
+  NOTICE_FORM_ELEMENT_TAG,
+  MY_COMMUNITY_ELEMENT_TAG,
+  type DefineCommunityElementOptions,
+  type DefineCommunityElementsOptions,
+} from './element'
+export { mountDiscussion, mountNoticeForm, mountMyCommunity, type MountDiscussionOptions, type MountNoticeFormOptions, type MountMyCommunityOptions } from './mount'
+export { createDiscussionController, type DiscussionController, type DiscussionControllerOptions, type DiscussionUi, type ComposerMode, type Draft } from './core/discussion'
+export { createNoticeForm, type NoticeFormController, type NoticeFormOptions, type NoticeFormUi } from './core/notice'
+export { createPanel, type PanelController, type PanelOptions, type PanelUi } from './core/panel'
+export { createOnboarding, type OnboardingModel, type OnboardingOptions, type OnboardingStep } from './core/onboarding'
+export { pickLang, type Lang } from './core/i18n'
+export { AVATAR_PRESETS, type AvatarPreset } from './core/avatars'
+export { DEFAULT_API_BASE } from './core/client'
+export type { CommunityRoutes } from './core/attrs'
+export { VERSION } from './version'

package/src/mount.ts

@@ -0,0 +1,127 @@
+/**
+ * Put an element on the page from code: what the Vue and React wrappers do, and what any other framework can
+ * call from its client-side mount hook. The element is defined first, so it is created already upgraded (no
+ * upgrade of an unknown element later, which some DOMs never run), and every attribute and property is set
+ * BEFORE it connects, so it mounts with them; the returned function removes the element again (its poll and
+ * requests stop with it).
+ */
+import type { CommunityTransport } from '@blogmcp/sdk/community'
+import type { CommunityRoutes } from './core/attrs'
+import {
+  DISCUSSION_ELEMENT_TAG,
+  MY_COMMUNITY_ELEMENT_TAG,
+  NOTICE_FORM_ELEMENT_TAG,
+  defineDiscussionElement,
+  defineMyCommunityElement,
+  defineNoticeFormElement,
+} from './element'
+
+interface CommonMountOptions {
+  /** The host's relative base (default `/api/community` under `siteBase`): its proxy or BFF. Never kb-api's URL. */
+  apiBase?: string
+  /**
+   * The path the site is served under (`/blog` on a managed blog, whose host's own `/api/` is kb-api): the default
+   * api-base and the default pages are taken under it. A page or base the host names itself is used as it is.
+   */
+  siteBase?: string
+  /** `cs` or `en` (`sk` reads Czech); default the page's `<html lang>`. */
+  lang?: string
+  /** The host's community pages (statements, the panel, the rules, the notice form, a notifier's status). */
+  routes?: CommunityRoutes
+  /** CSP nonce for the element's stylesheet (and the Turnstile script). */
+  nonce?: string
+  /** A replacement transport (tests; a signing transport later). */
+  transport?: CommunityTransport
+  /** Where the element goes; default `document.body`. */
+  container?: Element
+}
+
+export interface MountDiscussionOptions extends CommonMountOptions {
+  articleId: string
+  /** The site's sign-in page; the current path is put in its fragment. */
+  signInHref?: string
+  /** Head poll interval in ms (default 20 000; 0 = off). */
+  pollMs?: number
+}
+
+export interface MountNoticeFormOptions extends CommonMountOptions {
+  /** What is reported: a message, a member (by id or handle) or an article. */
+  target?: { conversationId: string; seq: number } | { memberId: string } | { handle: string } | { articleId: string }
+  /** Or the article (when `target` is absent). */
+  articleId?: string
+  /** The site's Turnstile site key; without it no widget renders (kb-api then decides alone). */
+  turnstileSiteKey?: string
+}
+
+export interface MountMyCommunityOptions extends CommonMountOptions {
+  /** Open this statement of reasons (the host's statement page). */
+  decisionId?: string
+  /** The site's sign-in page. */
+  signInHref?: string
+}
+
+type Settable = HTMLElement & { transport?: CommunityTransport }
+
+function attrs(el: HTMLElement, values: Record<string, string | number | undefined | null>): void {
+  for (const [name, value] of Object.entries(values)) if (value !== undefined && value !== null && value !== '') el.setAttribute(name, String(value))
+}
+
+function place(el: Settable, o: CommonMountOptions): () => void {
+  // Set before the element connects, so it mounts with it.
+  if (o.transport) el.transport = o.transport
+  ;(o.container ?? document.body).appendChild(el)
+  return () => el.remove()
+}
+
+/** Mount `<blogmcp-discussion>`; returns the function that removes it. */
+export function mountDiscussion(o: MountDiscussionOptions): () => void {
+  if (typeof document === 'undefined') return () => {}
+  defineDiscussionElement({ nonce: o.nonce })
+  const el = document.createElement(DISCUSSION_ELEMENT_TAG) as Settable
+  attrs(el, {
+    'article-id': o.articleId,
+    'api-base': o.apiBase,
+    'site-base': o.siteBase,
+    lang: o.lang,
+    'sign-in-href': o.signInHref,
+    routes: o.routes ? JSON.stringify(o.routes) : undefined,
+    'poll-ms': o.pollMs,
+    nonce: o.nonce,
+  })
+  return place(el, o)
+}
+
+/** Mount `<blogmcp-notice-form>`; returns the function that removes it. */
+export function mountNoticeForm(o: MountNoticeFormOptions): () => void {
+  if (typeof document === 'undefined') return () => {}
+  defineNoticeFormElement({ nonce: o.nonce })
+  const el = document.createElement(NOTICE_FORM_ELEMENT_TAG) as Settable
+  attrs(el, {
+    'api-base': o.apiBase,
+    'site-base': o.siteBase,
+    lang: o.lang,
+    'turnstile-site-key': o.turnstileSiteKey,
+    target: o.target ? JSON.stringify(o.target) : undefined,
+    'article-id': o.articleId,
+    routes: o.routes ? JSON.stringify(o.routes) : undefined,
+    nonce: o.nonce,
+  })
+  return place(el, o)
+}
+
+/** Mount `<blogmcp-my-community>`; returns the function that removes it. */
+export function mountMyCommunity(o: MountMyCommunityOptions = {}): () => void {
+  if (typeof document === 'undefined') return () => {}
+  defineMyCommunityElement({ nonce: o.nonce })
+  const el = document.createElement(MY_COMMUNITY_ELEMENT_TAG) as Settable
+  attrs(el, {
+    'api-base': o.apiBase,
+    'site-base': o.siteBase,
+    lang: o.lang,
+    'decision-id': o.decisionId,
+    routes: o.routes ? JSON.stringify(o.routes) : undefined,
+    'sign-in-href': o.signInHref,
+    nonce: o.nonce,
+  })
+  return place(el, o)
+}

package/src/react.ts

@@ -0,0 +1,53 @@
+/**
+ * `<KbDiscussion>`, `<KbNoticeForm>`, `<KbMyCommunity>` for React (18 and 19, Next.js App Router included — this
+ * module is a client component): each mounts its element after hydration and removes it on unmount. Each
+ * renders one empty `<div>` as the mount point — nothing else, on the server or the client — so the element
+ * sits where the component does and the page's markup is otherwise the site's alone.
+ *
+ *   <KbDiscussion articleId={article.id} apiBase="/api/community" signInHref={`/sign-in#${pathname}`} />
+ */
+import { createElement, useEffect, useRef, type ReactElement } from 'react'
+import type { MountDiscussionOptions, MountMyCommunityOptions, MountNoticeFormOptions } from './mount'
+
+export type KbDiscussionProps = Omit<MountDiscussionOptions, 'container'>
+export type KbNoticeFormProps = Omit<MountNoticeFormOptions, 'container'>
+export type KbMyCommunityProps = Omit<MountMyCommunityOptions, 'container'>
+
+/** The options that, changed, mount the element anew (functions by identity are left out). */
+const keyOf = (props: object): string => JSON.stringify(props, (_k, v: unknown) => (typeof v === 'function' ? '[fn]' : v))
+
+function useMounted<P extends object>(kind: string, props: P, load: () => Promise<(o: P & { container: Element }) => () => void>): ReactElement {
+  const host = useRef<HTMLDivElement>(null)
+  // The latest props, read at mount: a parent that rebuilds an object prop on every render must not tear
+  // the element down (an open composer, its text) — only a changed value does.
+  const latest = useRef(props)
+  latest.current = props
+  const key = keyOf(props)
+  useEffect(() => {
+    let unmount: (() => void) | null = null
+    let gone = false
+    void load().then((mount) => {
+      if (!gone && host.current) unmount = mount({ ...latest.current, container: host.current })
+    })
+    return () => {
+      gone = true
+      unmount?.()
+    }
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [key])
+  return createElement('div', { ref: host, 'data-blogmcp-community': kind })
+}
+
+export function KbDiscussion(props: KbDiscussionProps): ReactElement {
+  return useMounted('discussion', props, async () => (await import('./mount')).mountDiscussion)
+}
+
+export function KbNoticeForm(props: KbNoticeFormProps): ReactElement {
+  return useMounted('notice-form', props, async () => (await import('./mount')).mountNoticeForm)
+}
+
+export function KbMyCommunity(props: KbMyCommunityProps): ReactElement {
+  return useMounted('my-community', props, async () => (await import('./mount')).mountMyCommunity)
+}
+
+export type { MountDiscussionOptions, MountNoticeFormOptions, MountMyCommunityOptions }

package/src/shims.d.ts

@@ -0,0 +1,11 @@
+// Module shapes for the build's own imports, so a TypeScript consumer reading this package's
+// sources (in-repo, before `prepack` points `types` at dist) compiles without Vue tooling.
+declare module '*.vue' {
+  import type { DefineComponent } from 'vue'
+  const component: DefineComponent<Record<string, unknown>, Record<string, unknown>, unknown>
+  export default component
+}
+declare module '*.css?inline' {
+  const css: string
+  export default css
+}

package/src/ui/AuthorAvatar.vue

@@ -0,0 +1,26 @@
+<script setup lang="ts">
+/** A member's avatar preset (an emoji), else the initial of their name; decoration only (the name is beside it). */
+import { computed } from 'vue'
+import type { KnownAuthor } from '@blogmcp/sdk/community'
+import { avatarEmoji, hueOf, initialOf } from '../core/avatars'
+
+const props = defineProps<{ author: KnownAuthor | { kind: 'member'; memberId: string | null; displayName: string | null; avatarPreset: string | null } }>()
+
+const emoji = computed(() => (props.author.kind === 'member' ? avatarEmoji(props.author.avatarPreset) : null))
+const initial = computed(() => {
+  const a = props.author
+  if (a.kind === 'member') return initialOf(a.displayName)
+  if (a.kind === 'staff') return initialOf(a.displayName)
+  return ''
+})
+const background = computed(() => {
+  const a = props.author
+  if (emoji.value || !initial.value) return undefined
+  const id = a.kind === 'member' ? a.memberId : a.kind === 'staff' ? a.staffId : null
+  return `hsl(${hueOf(id)} 45% 42%)`
+})
+</script>
+
+<template>
+  <span class="bcm-avatar" :class="{ 'bcm-avatar-initial': !emoji && initial }" :style="background ? { background } : undefined" aria-hidden="true">{{ emoji ?? initial }}</span>
+</template>

package/src/ui/ConfirmDialog.vue

@@ -0,0 +1,38 @@
+<script setup lang="ts">
+/** A yes/no question in a native modal dialog (delete a message, withdraw the consent, delete the profile). */
+import { ref } from 'vue'
+import { uid, useModal, useText } from './context'
+import type { CommunityMessageKey } from '@blogmcp/sdk/community'
+import type { TextParams } from '../core/i18n'
+
+const props = defineProps<{
+  title: CommunityMessageKey
+  explain?: CommunityMessageKey
+  explainParams?: TextParams
+  confirm: CommunityMessageKey
+  cancel?: CommunityMessageKey
+  danger?: boolean
+  busy?: boolean
+  fallbackFocus?: () => HTMLElement | null
+}>()
+const emit = defineEmits<{ confirm: []; cancel: [] }>()
+const { t } = useText()
+
+const dialog = ref<HTMLDialogElement | null>(null)
+const id = uid('bcm-dialog')
+useModal(dialog, () => emit('cancel'), props.fallbackFocus)
+</script>
+
+<template>
+  <dialog ref="dialog" class="bcm-dialog" :aria-labelledby="`${id}-title`" :aria-describedby="explain ? `${id}-explain` : undefined">
+    <div class="bcm-dialog-body">
+      <h3 :id="`${id}-title`">{{ t(title) }}</h3>
+      <p v-if="explain" :id="`${id}-explain`">{{ t(explain, explainParams) }}</p>
+      <div class="bcm-row">
+        <span class="bcm-spacer" />
+        <button type="button" class="bcm-btn" :disabled="busy" @click="emit('cancel')">{{ t(cancel ?? 'common.cancel') }}</button>
+        <button type="button" class="bcm-btn bcm-primary" :class="{ 'bcm-danger': danger }" :disabled="busy" @click="emit('confirm')">{{ t(confirm) }}</button>
+      </div>
+    </div>
+  </dialog>
+</template>