g-comments 0.1.0 → 0.2.1

package/CHANGELOG.md

@@ -6,6 +6,33 @@ All notable changes to `g-comments` are listed here. The format follows
 
 ## [Unreleased]
 
+## [0.2.1] - 2026-10-20
+
+### Changed
+
+- The default stylesheet lives in the `gc-defaults` cascade layer and a forum
+  theme's CSS is imported into `gc-forum`, so site CSS beats the forum's and the
+  forum's beats the defaults regardless of load order or specificity. The forum
+  stylesheet is no longer a `<link>`: it is an `@import … layer(gc-forum)` in
+  the installed `<style>`.
+
+## [0.2.0] - 2026-10-20
+
+### Added
+
+- `theme="forum"` (provider, `<Comments>`, `<discourse-comments>`): applies the
+  forum's own palettes, fonts and "Embedded CSS" to the widget, from the
+  plugin's `GET /comments/theme`. Forum colours are exposed as
+  `--gc-forum-<name>`; tokens you set still win.
+- `client.theme()` and `useForumTheme()` return the same data for sites that
+  style their own UI after the forum.
+
+### Changed
+
+- The custom elements attach their default styles as `<style>` elements
+  instead of constructed stylesheets, so a stylesheet added to the shadow root
+  later (such as the forum's) wins ties.
+
 ## [0.1.0] - Unreleased
 
 First release, against the `discourse-comments` forum plugin.

package/README.md

@@ -28,7 +28,7 @@ import "g-comments/styles.css";
 // Once, near the root of the app.
 <DiscourseComments
   forum="https://forum.example.com"
-  theme="auto" // "light" | "dark" | "auto" (prefers-color-scheme) | "inherit"
+  theme="auto" // "light" | "dark" | "auto" (prefers-color-scheme) | "inherit" | "forum"
   locale="en" // "pt-BR" is bundled too; `messages` overrides single strings
   appearance={{ variables: { accent: "var(--brand)", radius: "0" } }}
   onEvent={(event) => analytics.track(event.type, event)}
@@ -134,9 +134,9 @@ depth, and `Item` keeps the inline reply, edit, report and delete panels.
 (`.gc-root.gc-root--styled`); nothing outside it is touched. Class names follow
 BEM (`gc-comment`, `gc-comment__body`, `gc-composer--replying`,
 `gc-button--primary`, …) and stay in place with `unstyled`, which only drops
-`gc-root--styled`. Selectors carry one class of specificity, so your own class
-rules win when loaded after the stylesheet. Cooked comment HTML is wrapped in
-`.gc-prose`.
+`gc-root--styled`. The rules live in the `gc-defaults` cascade layer, so your
+own (unlayered) CSS wins whatever its order or specificity. Cooked comment HTML
+is wrapped in `.gc-prose`.
 
 `appearance.elements` adds class names: `root`, `header`, `count`, `sort`,
 `signIn`, `composer`, `textarea`, `toolbar`, `list`, `comment`, `avatar`,
@@ -166,7 +166,41 @@ colour scheme.
 `theme` sets `data-gc-theme` on the root: `light`, `dark`, or `auto`, which
 switches with `prefers-color-scheme`. `inherit` sets nothing and derives the
 neutral colours from the page's text colour, for sites that theme the widget
-themselves. The layout works down to 320px wide.
+themselves. `forum` applies the forum's own look (below). The layout works
+down to 320px wide.
+
+### Use the forum's look
+
+```tsx
+<DiscourseComments forum="https://forum.example.com" theme="forum">
+```
+
+`theme="forum"` loads the forum's theme once per forum (`GET /comments/theme`)
+and installs it where the widget lives: the page's `<head>`, or the custom
+element's shadow root. Three things arrive:
+
+- **Colours.** Every custom property the forum's colour definitions emit is
+  available on the widget root as `--gc-forum-<name>` (`--gc-forum-primary`,
+  `--gc-forum-tertiary`, `--gc-forum-primary-low`, …), and the widget tokens
+  default to them: `fg` ← `primary`, `fgMuted` ← `primary-medium`, `bg` ←
+  `secondary`, `bgSubtle` ← `primary-very-low`, `border` ← `primary-low`,
+  `accent` ← `tertiary`, `accentFg` ← `secondary`, `danger` ← `danger`. When
+  the theme has a dark palette it applies under `prefers-color-scheme: dark`.
+- **Fonts.** `--gc-font` defaults to the forum's body font;
+  `--gc-forum-font-body`, `--gc-forum-font-heading` and
+  `--gc-forum-font-monospace` carry the stacks, and `@font-face` rules are
+  added to the page for fonts the forum serves.
+- **Theme CSS.** The default theme's "Embedded CSS" (Admin → Customize →
+  Themes → Edit CSS/HTML → Embedded) is imported into the `gc-forum` cascade
+  layer, so forum admins can style the `gc-*` classes without touching the
+  site.
+
+Precedence, for tokens and for plain CSS alike: what a component sets
+(`appearance`) beats the site's own CSS and `--gc-*` values, which beat the
+forum's, which beat the defaults. Site CSS is unlayered and the forum's sits in
+`gc-forum` above `gc-defaults`, so no ordering or specificity tricks are
+needed. `useForumTheme()` returns the same data for sites that style their own
+UI after the forum.
 
 ## Custom elements (no framework)
 
@@ -193,7 +227,7 @@ Attributes mirror the React props, in kebab-case:
 | `identifier`, `url`, `title` | same | thread identity; `url` and `title` default to the page |
 | `sort` | `sort` | `best`, `hot`, `newest`, `oldest` |
 | `sign-in` | `signIn` | `inline` (default), `on-submit`, `manual` |
-| `theme` | `theme` | `auto` (default), `light`, `dark`, `inherit` |
+| `theme` | `theme` | `auto` (default), `light`, `dark`, `inherit`, `forum` |
 | `locale` | `locale` | `en`, `pt-BR` |
 | `max-depth` | `maxDepth` | number, default 2 |
 | `read-only`, `unstyled`, `debug` | same | boolean: present means true (`"false"` is false) |
@@ -245,8 +279,10 @@ discourse-comments::part(gc-comment--pinned) {
 ```
 
 `unstyled` drops the default stylesheet's effect (the classes and parts stay),
-and `theme="inherit"` derives the neutral colours from the page's text colour.
-The count element has no styles of its own and inherits the page's font.
+`theme="inherit"` derives the neutral colours from the page's text colour, and
+`theme="forum"` loads the forum's palettes, fonts and theme CSS into the shadow
+root (see "Use the forum's look"). The count element has no styles of its own
+and inherits the page's font.
 
 `defineElements({ comments: "my-comments", count: "my-count" })` registers the
 same elements under other names; names that are already defined are left

package/dist/{chunk-X6RAR374.cjs → chunk-IBNNENCZ.cjs}

@@ -2660,6 +2660,7 @@ function createClientWithInternals(options, internals) {
   const realtime = internals.realtime ?? new MessageBusPoller({ base: forum.base, fetch: http.fetch, log });
   const batcher = new CountsBatcher(http);
   let configGeneration = 0;
+  let themePromise = null;
   let degradedRecheck;
   let degradedChecks = 0;
   function config() {
@@ -2778,6 +2779,16 @@ function createClientWithInternals(options, internals) {
     }
     return http.request("POST", `${threadPath(threadId)}/attachments`, { form });
   }
+  function theme() {
+    if (lifetime.signal.aborted) {
+      return Promise.reject(disposedError());
+    }
+    themePromise ??= http.request("GET", "/theme").catch((error) => {
+      themePromise = null;
+      throw error;
+    });
+    return themePromise;
+  }
   const client = {
     forum: forum.base,
     forumOrigin: forum.origin,
@@ -2786,6 +2797,7 @@ function createClientWithInternals(options, internals) {
     threads: { open },
     attachments: { upload },
     config,
+    theme,
     counts: (refs) => batcher.request(refs),
     count: async (ref) => (await batcher.request([ref]))[encodeRef(ref)] ?? 0,
     preview: async (body) => (await http.request("POST", "/preview", { json: { raw: body } })).html,
@@ -3073,5 +3085,5 @@ exports.memoryStorage = memoryStorage;
 exports.normalizeForum = normalizeForum;
 exports.ptBR = ptBR;
 exports.resolveLocale = resolveLocale;
-//# sourceMappingURL=chunk-X6RAR374.cjs.map
-//# sourceMappingURL=chunk-X6RAR374.cjs.map
+//# sourceMappingURL=chunk-IBNNENCZ.cjs.map
+//# sourceMappingURL=chunk-IBNNENCZ.cjs.map