@blogmcp/community 0.0.0-stage → 0.1.0

package/dist/vue.js

@@ -0,0 +1,97 @@
+import { defineComponent, ref, onMounted, watch, onBeforeUnmount, h } from "vue";
+function useMount(kind, options, load) {
+  const host = ref(null);
+  let unmount = null;
+  let gone = false;
+  let ticket = 0;
+  async function mount() {
+    const mine = ++ticket;
+    const mountFn = await load();
+    if (gone || mine !== ticket || !host.value) return;
+    unmount?.();
+    unmount = mountFn({ ...options(), container: host.value });
+  }
+  onMounted(() => void mount());
+  watch(
+    () => JSON.stringify(options(), (_k, v) => typeof v === "function" ? "[fn]" : v),
+    () => void mount()
+  );
+  onBeforeUnmount(() => {
+    gone = true;
+    unmount?.();
+    unmount = null;
+  });
+  return () => h("div", { ref: host, "data-blogmcp-community": kind });
+}
+function defined(o) {
+  const out = {};
+  for (const [k, v] of Object.entries(o)) if (v !== void 0 && v !== null) out[k] = v;
+  return out;
+}
+const KbDiscussion = defineComponent({
+  name: "KbDiscussion",
+  props: {
+    articleId: { type: String, required: true },
+    apiBase: String,
+    siteBase: String,
+    lang: String,
+    signInHref: String,
+    routes: Object,
+    pollMs: Number,
+    nonce: String,
+    transport: Function
+  },
+  setup(props) {
+    return useMount(
+      "discussion",
+      () => defined({ ...props }),
+      async () => (await import("./chunks/mount-DzjwnHyx.js").then((n) => n.l)).mountDiscussion
+    );
+  }
+});
+const KbNoticeForm = defineComponent({
+  name: "KbNoticeForm",
+  props: {
+    target: Object,
+    articleId: String,
+    apiBase: String,
+    siteBase: String,
+    lang: String,
+    turnstileSiteKey: String,
+    routes: Object,
+    nonce: String,
+    transport: Function
+  },
+  setup(props) {
+    return useMount(
+      "notice-form",
+      () => defined({ ...props }),
+      async () => (await import("./chunks/mount-DzjwnHyx.js").then((n) => n.l)).mountNoticeForm
+    );
+  }
+});
+const KbMyCommunity = defineComponent({
+  name: "KbMyCommunity",
+  props: {
+    decisionId: String,
+    apiBase: String,
+    siteBase: String,
+    lang: String,
+    signInHref: String,
+    routes: Object,
+    nonce: String,
+    transport: Function
+  },
+  setup(props) {
+    return useMount(
+      "my-community",
+      () => defined({ ...props }),
+      async () => (await import("./chunks/mount-DzjwnHyx.js").then((n) => n.l)).mountMyCommunity
+    );
+  }
+});
+export {
+  KbDiscussion,
+  KbMyCommunity,
+  KbNoticeForm
+};

package/package.json

@@ -1,6 +1,82 @@
 {
   "name": "@blogmcp/community",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Community elements for your own site: the discussion under an article, the DSA notice form and the reader's „My community” panel. Custom elements + Vue/React wrappers + a script build, over @blogmcp/sdk/community.",
+  "type": "module",
+  "publishConfig": {
+    "access": "public"
+  },
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "sideEffects": [
+    "./dist/global.js",
+    "./dist/blogmcp-community.global.js",
+    "./src/global.ts"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./vue": {
+      "types": "./dist/vue.d.ts",
+      "import": "./dist/vue.js"
+    },
+    "./react": {
+      "types": "./dist/react.d.ts",
+      "import": "./dist/react.js"
+    },
+    "./global": "./dist/blogmcp-community.global.js"
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "scripts": {
+    "build": "vite build && vite build --config vite.global.config.ts && vue-tsc -p tsconfig.build.json && node scripts/check-size.mjs",
+    "test": "vitest run",
+    "test:e2e": "playwright test --config test/e2e/playwright.config.ts",
+    "typecheck": "vue-tsc --noEmit -p tsconfig.json",
+    "prepack": "node ../../scripts/pack-dist-types.mjs prepack",
+    "postpack": "node ../../scripts/pack-dist-types.mjs postpack"
+  },
+  "dependencies": {
+    "@blogmcp/sanitize": "^0.9.0",
+    "@blogmcp/sdk": "^0.9.0",
+    "vue": "^3.5.0"
+  },
+  "peerDependencies": {
+    "react": ">=18"
+  },
+  "peerDependenciesMeta": {
+    "react": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@playwright/test": "^1.49.0",
+    "@types/node": "^20.10.0",
+    "@types/react": "^18.3.0",
+    "@types/react-dom": "^18.3.0",
+    "@vitejs/plugin-vue": "^6.0.0",
+    "happy-dom": "^17.4.0",
+    "react": "^18.3.0",
+    "react-dom": "^18.3.0",
+    "typescript": "^5.3.3",
+    "vite": "^7.3.0",
+    "vitest": "^3.0.0",
+    "vue-tsc": "^2.0.0"
+  },
+  "keywords": [
+    "blogmcp",
+    "community",
+    "discussion",
+    "comments",
+    "dsa",
+    "custom-element",
+    "vue",
+    "react"
+  ],
+  "license": "MIT"
+}

package/src/core/attrs.ts

@@ -0,0 +1,147 @@
+/**
+ * What the elements read from their attributes: the host's page routes (`routes`, JSON), the notice form's
+ * target (`target`, JSON, or `article-id`), and the link the discussion gives a reader without a session
+ * to report a message on the host's notice page.
+ *
+ * Every path is the HOST's (m1-contracts.md §10.2: the elements take the host's routes as attributes) and
+ * must be a path on its own site — one leading `/`, never `//` or `/\`, no blank, control character or
+ * backslash; anything else is dropped and the managed blog's default (COMMUNITY_ROUTES) applies.
+ *
+ * The defaults are router-relative (the SDK's COMMUNITY_ROUTES: "the blog prepends its own base"). A site served
+ * under a path — a managed blog under `/blog`, whose host's own `/api/` goes straight to kb-api — names it in
+ * `site-base`, and the defaults (the pages and the api-base) are taken under it; what the host names itself
+ * (`routes`, `api-base`, the tenant's MyState.links) is a full site path already and is used as it is.
+ */
+import { COMMUNITY_ROUTES, type NoticeTarget } from '@blogmcp/sdk/community'
+
+/** The host's community pages, as the `routes` attribute names them (all optional). */
+export interface CommunityRoutes {
+  /** A statement of reasons; `{id}` is the decision's id (`/komunita/rozhodnuti/{id}`). */
+  statementPath?: string
+  /** The „Moje komunita" panel. */
+  myCommunityPath?: string
+  /** The rules page (rendered by the host without JavaScript). */
+  rulesPath?: string
+  /** The notice form. */
+  reportPath?: string
+  /** A notifier's status page (the receipt goes in its fragment). */
+  noticesPath?: string
+  /**
+   * The site's consultation page (drhoubicka's „poradna"): the regulated preset's `report_to_manufacturer` note
+   * becomes a link to it (m1-contracts.md §7.6). No default — without it the note stays text.
+   */
+  consultationPath?: string
+}
+
+const ROUTE_KEYS = ['statementPath', 'myCommunityPath', 'rulesPath', 'reportPath', 'noticesPath', 'consultationPath'] as const
+
+/** A path on the host's own site (the SDK's links.ts rule). */
+export function isSitePath(path: unknown): path is string {
+  return typeof path === 'string' && /^\/(?![/\\])/.test(path) && !/[\s\\\u0000-\u001f\u007f]/.test(path)
+}
+
+type Rec = Record<string, unknown>
+const isRecord = (v: unknown): v is Rec => typeof v === 'object' && v !== null && !Array.isArray(v)
+
+/** A JSON attribute's value (a string), or the object a framework set as the property. */
+function jsonOf(value: unknown): unknown {
+  if (typeof value !== 'string') return value
+  if (value.trim() === '') return null
+  try {
+    return JSON.parse(value) as unknown
+  } catch {
+    return null
+  }
+}
+
+/** The `routes` attribute: the site paths it names; anything malformed is left out. */
+export function parseRoutes(value: unknown): CommunityRoutes {
+  const raw = jsonOf(value)
+  const out: CommunityRoutes = {}
+  if (!isRecord(raw)) return out
+  for (const key of ROUTE_KEYS) if (isSitePath(raw[key])) out[key] = raw[key] as string
+  return out
+}
+
+/**
+ * The `site-base` attribute: the path the site is served under, without a trailing `/` (`/blog`; '' for the root,
+ * also when absent) — or null when it is no plain path (a URL, a query, a dot segment): the element then renders
+ * nothing, as for an absolute api-base.
+ */
+export function siteBaseOf(value: unknown): string | null {
+  if (value === undefined || value === null || value === '') return ''
+  if (typeof value !== 'string') return null
+  const base = value.replace(/\/+$/, '')
+  if (base === '') return value.startsWith('/') ? '' : null
+  return /^(?:\/(?!\.{1,2}(?:\/|$))[A-Za-z0-9._~%-]+)+$/.test(base) ? base : null
+}
+
+/**
+ * The pages with the managed blog's defaults filled in under the site's base (statementPath stays a template).
+ * A page the host or the tenant names is its own full path.
+ */
+export function routesWithDefaults(
+  routes: CommunityRoutes,
+  tenant?: { statementPath?: string | null; myCommunityPath?: string | null } | null,
+  siteBase = '',
+) {
+  const site = (path: string | null | undefined): string | undefined => (isSitePath(path) ? path : undefined)
+  return {
+    statementPath: routes.statementPath ?? site(tenant?.statementPath) ?? `${siteBase}${COMMUNITY_ROUTES.statement}`,
+    myCommunityPath: routes.myCommunityPath ?? site(tenant?.myCommunityPath) ?? `${siteBase}${COMMUNITY_ROUTES.myCommunity}`,
+    rulesPath: routes.rulesPath ?? `${siteBase}${COMMUNITY_ROUTES.rules}`,
+    reportPath: routes.reportPath ?? `${siteBase}${COMMUNITY_ROUTES.report}`,
+    noticesPath: routes.noticesPath ?? `${siteBase}${COMMUNITY_ROUTES.notices}`,
+    consultationPath: routes.consultationPath ?? null,
+  }
+}
+
+const ID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i
+const HANDLE_RE = /^[a-z0-9][a-z0-9_]{2,29}$/
+const isId = (v: unknown): v is string => typeof v === 'string' && ID_RE.test(v)
+const isSeq = (v: unknown): v is number => typeof v === 'number' && Number.isSafeInteger(v) && v > 0
+
+/** A notice target of one of kb-api's four shapes, or null (the form then has nothing to report). */
+export function parseTarget(value: unknown): NoticeTarget | null {
+  const raw = jsonOf(value)
+  if (!isRecord(raw)) return null
+  if ('conversationId' in raw) return isId(raw.conversationId) && isSeq(raw.seq) ? { conversationId: raw.conversationId.toLowerCase(), seq: raw.seq } : null
+  if ('memberId' in raw) return isId(raw.memberId) ? { memberId: raw.memberId.toLowerCase() } : null
+  if ('handle' in raw) return typeof raw.handle === 'string' && HANDLE_RE.test(raw.handle) ? { handle: raw.handle } : null
+  if ('articleId' in raw) return isId(raw.articleId) ? { articleId: raw.articleId.toLowerCase() } : null
+  return null
+}
+
+export type NoticeTargetKind = 'message' | 'profile' | 'article'
+
+export function targetKind(target: NoticeTarget): NoticeTargetKind {
+  if ('conversationId' in target) return 'message'
+  if ('articleId' in target) return 'article'
+  return 'profile'
+}
+
+/**
+ * The notice page's link for a message, for a reader without a session (who cannot use the member's
+ * report): `${reportPath}#c=<conversationId>&s=<seq>`. The ids are public; they travel in the fragment so
+ * the notice page stays one address (no crawlable variants — the storefront's rule for the sign-in link).
+ */
+export function reportLink(reportPath: string, target: { conversationId: string; seq: number }): string | null {
+  if (!isSitePath(reportPath) || reportPath.includes('#') || !isId(target.conversationId) || !isSeq(target.seq)) return null
+  return `${reportPath}#c=${target.conversationId.toLowerCase()}&s=${target.seq}`
+}
+
+/** The target the discussion's report link carries (`#c=…&s=…`), or `#a=<articleId>`; null for anything else. */
+export function targetFromHash(hash: string): NoticeTarget | null {
+  if (typeof hash !== 'string' || !hash.startsWith('#') || hash.startsWith('#t=')) return null
+  const params = new Map<string, string>()
+  for (const part of hash.slice(1).split('&')) {
+    const eq = part.indexOf('=')
+    if (eq > 0) params.set(part.slice(0, eq), part.slice(eq + 1))
+  }
+  const c = params.get('c')
+  const s = params.get('s')
+  if (c !== undefined && s !== undefined && /^\d{1,15}$/.test(s)) return parseTarget({ conversationId: c, seq: Number(s) })
+  const a = params.get('a')
+  if (a !== undefined) return parseTarget({ articleId: a })
+  return null
+}

package/src/core/avatars.ts

@@ -0,0 +1,44 @@
+/**
+ * The avatar presets a member picks from (kb-api stores the id, `^[a-z0-9_]{1,64}$`, and knows no list).
+ * Each is one emoji: a screen reader names it in the reader's own language, so the picker needs no words of
+ * ours. An id this list does not know (a newer element's) shows the name's initial instead.
+ */
+export interface AvatarPreset {
+  readonly id: string
+  readonly emoji: string
+}
+
+export const AVATAR_PRESETS: readonly AvatarPreset[] = Object.freeze([
+  Object.freeze({ id: 'fox', emoji: '🦊' }),
+  Object.freeze({ id: 'owl', emoji: '🦉' }),
+  Object.freeze({ id: 'bear', emoji: '🐻' }),
+  Object.freeze({ id: 'hedgehog', emoji: '🦔' }),
+  Object.freeze({ id: 'frog', emoji: '🐸' }),
+  Object.freeze({ id: 'bee', emoji: '🐝' }),
+  Object.freeze({ id: 'leaf', emoji: '🍃' }),
+  Object.freeze({ id: 'flower', emoji: '🌼' }),
+  Object.freeze({ id: 'tree', emoji: '🌲' }),
+  Object.freeze({ id: 'star', emoji: '⭐' }),
+])
+
+const BY_ID = new Map(AVATAR_PRESETS.map((p) => [p.id, p.emoji]))
+
+/** The preset's emoji, or null for none or an unknown id. */
+export function avatarEmoji(preset: string | null | undefined): string | null {
+  return typeof preset === 'string' ? (BY_ID.get(preset) ?? null) : null
+}
+
+/** The first letter of a name (the avatar of a member without a known preset). */
+export function initialOf(name: string | null | undefined): string {
+  if (typeof name !== 'string') return ''
+  for (const ch of name.trim()) return ch.toLocaleUpperCase()
+  return ''
+}
+
+/** A stable hue for a member id, so the same member keeps the same initial's colour (decoration only). */
+export function hueOf(id: string | null | undefined): number {
+  if (typeof id !== 'string' || id === '') return 210
+  let h = 0
+  for (let i = 0; i < id.length; i++) h = (h * 31 + id.charCodeAt(i)) % 360
+  return h
+}

package/src/core/client.ts

@@ -0,0 +1,54 @@
+/**
+ * The client an element talks through: the SDK's `createCommunityClient` over the HOST's relative base
+ * (`api-base`; default `/api/community` under the site's `site-base` — a headless site's BFF, the storefront's,
+ * or with `site-base="/blog"` a managed blog's own proxy). Never kb-api directly: its community namespaces answer
+ * no CORS (m1-contracts.md §7.1), and the client refuses an absolute base. On a managed blog the tenant host's
+ * `/api/` IS kb-api, so `/api/community` there would skip the blog's proxy and its session. An element with an
+ * unusable base warns once and renders nothing.
+ */
+import { createCommunityClient, isRelativeCommunityBase, type CommunityClient, type CommunityTransport } from '@blogmcp/sdk/community'
+import { siteBaseOf } from './attrs'
+
+/** The base the hosts serve the community under, below their site base (§12; the BFF's default basePath). */
+export const DEFAULT_API_BASE = '/api/community'
+
+const warned = new Set<string>()
+
+/**
+ * One console line per problem and page, for the site's developer — never a value from the page. The
+ * message starts with `[blogmcp-community]` (test/text-only.spec.ts tells developer lines from reader text
+ * by it).
+ */
+export function warnOnce(key: string, message: `[blogmcp-community] ${string}`): void {
+  if (warned.has(key)) return
+  warned.add(key)
+  console.warn(message)
+}
+
+/**
+ * The `site-base` attribute as a path prefix ('' at the site's root), or null — the developer told once — when it
+ * is no path on this site.
+ */
+export function siteBaseFor(value: string | null | undefined): string | null {
+  const base = siteBaseOf(value)
+  if (base === null) warnOnce('site-base', '[blogmcp-community] site-base must be a path on this site (e.g. "/blog"), never a URL: the site’s pages and its proxy are found under it')
+  return base
+}
+
+/**
+ * The client for an element's `api-base` (and an injected transport), or null when the base is not a relative
+ * path. Without an `api-base`: `/api/community` under the site's base.
+ */
+export function communityClientFor(apiBase: string | null | undefined, transport?: CommunityTransport | null, siteBase = ''): CommunityClient | null {
+  const base = apiBase === undefined || apiBase === null || apiBase === '' ? `${siteBase}${DEFAULT_API_BASE}` : apiBase
+  if (!isRelativeCommunityBase(base)) {
+    warnOnce('api-base', '[blogmcp-community] api-base must be a path on this site (e.g. "/api/community"), never a URL: the community API is reached through the site’s own proxy or BFF')
+    return null
+  }
+  try {
+    return createCommunityClient(transport ? { base, transport } : { base })
+  } catch {
+    warnOnce('api-base', '[blogmcp-community] api-base was refused by the community client')
+    return null
+  }
+}