g-comments 0.0.0-stage → 0.2.0

package/dist/react.d.cts

@@ -0,0 +1,335 @@
+import * as react from 'react';
+import { ReactNode } from 'react';
+import { g as Comment, V as Pending, o as Commenter, r as CommentsError, T as Messages, C as CreateClientOptions, a as CommentsClient, e as AuthStatus, c as AuthProvider, a1 as SignInOptions, U as OpenThreadOptions, Z as PostResult, a9 as ThreadHandle, ab as ThreadSnapshot, b as CountRef, N as ForumTheme } from './messages-C9bMljl3.cjs';
+
+/**
+ * `auto` follows `prefers-color-scheme`, `inherit` leaves the colours to the
+ * page, and `forum` applies the forum's own palettes, fonts and theme CSS.
+ */
+type Theme = "auto" | "light" | "dark" | "inherit" | "forum";
+/** Design tokens; each is set as `--gc-<kebab-case name>` on the widget root. */
+type AppearanceVariable = "font" | "fg" | "fgMuted" | "bg" | "bgSubtle" | "border" | "accent" | "accentFg" | "danger" | "radius" | "shadow" | "space" | "avatarSize";
+/** Elements that accept extra class names through `appearance.elements`. */
+type AppearanceElement = "root" | "header" | "count" | "sort" | "signIn" | "composer" | "textarea" | "toolbar" | "list" | "comment" | "avatar" | "meta" | "body" | "actions" | "menu" | "button" | "primaryButton" | "loadMore" | "pill" | "notice" | "dialog";
+interface Appearance {
+    /** Token overrides, e.g. `{ accent: "var(--brand)", radius: "0" }`. */
+    variables?: Partial<Record<AppearanceVariable, string>>;
+    /** Extra class names, e.g. `{ comment: "card", button: "btn" }`. */
+    elements?: Partial<Record<AppearanceElement, string>>;
+}
+
+/** What the widget was doing when an `error` event fired. */
+type CommentsAction = "open" | "load" | "loadMore" | "loadReplies" | "context" | "post" | "edit" | "delete" | "like" | "flag" | "pin" | "upload" | "preview" | "signIn" | "theme";
+/** Delivered to `<DiscourseComments onEvent>`. */
+type CommentsEvent = {
+    type: "comment.posted";
+    threadId: string;
+    comment: Comment;
+}
+/** The comment went to the review queue instead of being published. */
+ | {
+    type: "comment.pending";
+    threadId: string;
+    pending: Pending;
+} | {
+    type: "comment.liked";
+    threadId: string;
+    comment: Comment;
+    liked: boolean;
+} | {
+    type: "auth.signedIn";
+    user: Commenter;
+}
+/** `expired` is true when the forum ended the session (the key was revoked or expired). */
+ | {
+    type: "auth.signedOut";
+    expired: boolean;
+} | {
+    type: "error";
+    action: CommentsAction;
+    error: CommentsError;
+    threadId?: string;
+};
+
+interface ProviderOptions {
+    children?: ReactNode;
+    /** Default appearance for every widget inside; widgets merge their own on top. */
+    appearance?: Appearance;
+    /** UI language (`en`, `pt-BR`; other `pt*` map to `pt-BR`), also sent as `Accept-Language`. */
+    locale?: string;
+    /** Overrides for individual UI strings. */
+    messages?: Partial<Messages>;
+    theme?: Theme;
+    /** Logs client activity and shows setup diagnostics outside localhost. */
+    debug?: boolean;
+    onEvent?: (event: CommentsEvent) => void;
+}
+/** Client options beyond `forum`; they apply when the shared client is first created. */
+type ClientCreationOptions = Omit<CreateClientOptions, "forum" | "locale" | "debug">;
+type DiscourseCommentsProps = ProviderOptions & (({
+    forum: string;
+    client?: undefined;
+} & ClientCreationOptions) | {
+    client: CommentsClient;
+    forum?: undefined;
+});
+/**
+ * Shares one client (auth, config, counts batching, realtime) with every
+ * comments widget and hook below it.
+ */
+declare function DiscourseComments(props: DiscourseCommentsProps): react.JSX.Element;
+
+/** The client the surrounding `<DiscourseComments>` provides. */
+declare function useClient(): CommentsClient;
+
+interface PartProps {
+    className?: string;
+}
+declare function Avatar({ className }: PartProps): react.JSX.Element;
+/** Author, badges, timestamp (a `#gc-<id>` permalink) and edited mark. */
+declare function Meta({ className }: PartProps): react.JSX.Element;
+/** The comment's cooked HTML, or its inline editor while editing. */
+declare function Body({ className }: PartProps): react.JSX.Element;
+/** Like, reply and a menu with copy link, edit, delete, report and feature. */
+declare function Actions({ className }: PartProps): react.JSX.Element | null;
+
+interface ComposerProps {
+    /** Replies to this comment (the inline reply composer). */
+    replyTo?: Comment;
+    /** Edits this comment; its markdown is loaded from the forum. */
+    editing?: Comment;
+    placeholder?: string;
+    autoFocus?: boolean;
+    /** Called after a successful post or save, and when the reader cancels. */
+    onDone?: () => void;
+    className?: string;
+}
+/**
+ * The markdown composer. Without `replyTo`/`editing` it is the thread's main
+ * composer and renders only when the reader may write (or may sign in on submit).
+ */
+declare function Composer(props: ComposerProps): react.JSX.Element | null;
+
+/**
+ * Explains setup problems (origin not allowed, plugin disabled, basic auth
+ * blocking preflights…). Renders on localhost-like hosts or with `debug`.
+ */
+declare function DevPanel({ className }: {
+    className?: string;
+}): react.JSX.Element | null;
+
+interface HeaderProps {
+    /** Defaults to `<Comments.Count />` and `<Comments.Sort />`. */
+    children?: ReactNode;
+    className?: string;
+}
+declare function Header({ children, className }: HeaderProps): react.JSX.Element;
+interface CountProps {
+    /** Heading element; `h2` by default. */
+    as?: "h2" | "h3" | "h4" | "h5" | "h6" | "p" | "span";
+    /** Custom content for the comment count, e.g. `(n) => n`. */
+    render?: (count: number) => ReactNode;
+    className?: string;
+}
+declare function Count({ as: Tag, render, className }: CountProps): react.JSX.Element;
+declare function Sort({ className }: {
+    className?: string;
+}): react.JSX.Element | null;
+
+type RenderComment = (comment: Comment, depth: number) => ReactNode;
+interface ListProps {
+    /** Renders one comment; defaults to `<Comments.Item comment={c} depth={depth} />`. */
+    children?: RenderComment;
+    className?: string;
+}
+/** The comment tree, with its loading, error and "continue this thread" states. */
+declare function List({ children, className }: ListProps): react.JSX.Element | null;
+interface ItemProps {
+    comment: Comment;
+    /** 0 for top-level comments. */
+    depth?: number;
+    /** Replaces the default avatar, meta, body and actions. */
+    children?: ReactNode;
+    /** Render the comment without its replies (used for ancestors in a focused branch). */
+    showReplies?: boolean;
+    className?: string;
+}
+/** One comment: its card, inline reply/edit/report panels and its replies. */
+declare function Item({ comment, depth, children, showReplies, className }: ItemProps): react.JSX.Element;
+
+interface CommenterState {
+    user: Commenter | null;
+    status: AuthStatus;
+    /** The forum's sign-in providers; empty until the forum config has loaded. */
+    providers: readonly AuthProvider[];
+    /** The forum is answering anonymously under load: treat the widget as read-only. */
+    degraded: boolean;
+    /** Why the last sign-in failed or the session ended. */
+    error: CommentsError | null;
+    /** Opens the forum's sign-in popup; call it from a click handler so it is not blocked. */
+    signIn(options?: SignInOptions): Promise<Commenter | null>;
+    cancelSignIn(): void;
+    signOut(): Promise<void>;
+}
+/** The signed-in reader of the provider's forum (or of `forum`). */
+declare function useCommenter(options?: {
+    forum?: string;
+}): CommenterState;
+
+/**
+ * Where signing in happens: `inline` shows a "Join the conversation" panel,
+ * `on-submit` lets anonymous readers write and signs them in when they post,
+ * `manual` leaves it to the site (`useCommenter().signIn()`).
+ */
+type SignInMode = "inline" | "on-submit" | "manual";
+interface CommentsProps extends OpenThreadOptions {
+    /** Uses the shared client for this forum instead of the provider's. */
+    forum?: string;
+    /** Visual nesting levels; deeper replies collapse into "Continue this thread". */
+    maxDepth?: number;
+    signIn?: SignInMode;
+    /**
+     * With `signIn="manual"`, called when an anonymous reader tries to like or
+     * reply, so the site can start its own sign-in. Without it those actions are
+     * unavailable to anonymous readers in manual mode.
+     */
+    onSignInRequired?: () => void;
+    /** Hides every write action. */
+    readOnly?: boolean;
+    /** Comment id to scroll to and highlight; defaults to the `#gc-<id>` fragment. */
+    highlight?: number | null;
+    /** Shown above the composer; defaults to the forum's setting. */
+    guidelinesUrl?: string;
+    onPosted?: (result: PostResult) => void;
+    appearance?: Appearance;
+    /** Renders without the default styles; class names stay for targeting. */
+    unstyled?: boolean;
+    theme?: Theme;
+    locale?: string;
+    className?: string;
+}
+interface RootProps extends CommentsProps {
+    children?: ReactNode;
+}
+/**
+ * Opens the thread and provides it to the primitives inside. Without a
+ * provider or `forum` nothing can be opened, so it renders a quiet notice
+ * instead of throwing (a consumer's tests may mount pages without one).
+ */
+declare function Root(props: RootProps): react.JSX.Element;
+
+interface SignInProps {
+    /** Custom UI; called in every sign-in mode, including `manual`. */
+    children?: (commenter: CommenterState) => ReactNode;
+    className?: string;
+}
+/**
+ * Inline mode: a "Join the conversation" panel with the forum's providers.
+ * Signed in: who is commenting, with a sign-out button.
+ */
+declare function SignIn({ children, className }: SignInProps): react.JSX.Element | null;
+
+/** Read-only, closed and not-allowed notices that replace the composer. */
+declare function Notice({ className }: {
+    className?: string;
+}): react.JSX.Element | null;
+/** The "N new comments" pill for top-level comments that arrived live. */
+declare function NewComments({ className }: {
+    className?: string;
+}): react.JSX.Element;
+/** The reader's own comments that went to the review queue. */
+declare function AwaitingApproval({ className }: {
+    className?: string;
+}): react.JSX.Element;
+declare function LoadMore({ className }: {
+    className?: string;
+}): react.JSX.Element | null;
+
+/**
+ * The drop-in comments section for the current page, assembled from the
+ * `Comments.*` primitives that are also exported for custom layouts.
+ */
+declare function CommentsSection(props: CommentsProps): react.JSX.Element;
+declare const Comments: typeof CommentsSection & {
+    Root: typeof Root;
+    Header: typeof Header;
+    Count: typeof Count;
+    Sort: typeof Sort;
+    SignIn: typeof SignIn;
+    Composer: typeof Composer;
+    List: typeof List;
+    Item: typeof Item;
+    Avatar: typeof Avatar;
+    Meta: typeof Meta;
+    Body: typeof Body;
+    Actions: typeof Actions;
+    LoadMore: typeof LoadMore;
+    NewComments: typeof NewComments;
+    AwaitingApproval: typeof AwaitingApproval;
+    Notice: typeof Notice;
+    DevPanel: typeof DevPanel;
+};
+
+interface CommentCountProps {
+    identifier?: string;
+    /** Host the `identifier` belongs to; defaults to the current page's host. */
+    host?: string;
+    /** Defaults to the current page (canonical link, else the address). */
+    url?: string;
+    topicId?: number;
+    /** Uses the shared client for this forum instead of the provider's. */
+    forum?: string;
+    /** Custom content, e.g. `(n) => n` for just the number. */
+    render?: (count: number) => ReactNode;
+    className?: string;
+}
+/** "12 comments" for a page, fetched once on mount and batched with other counts. */
+declare function CommentCount({ identifier, host, url, topicId, forum, render, className, }: CommentCountProps): react.JSX.Element | null;
+
+interface UseThreadOptions extends OpenThreadOptions {
+    /** Uses the shared client for this forum instead of the provider's. */
+    forum?: string;
+}
+interface UseThreadResult {
+    /** `null` until the thread has been opened. */
+    thread: ThreadHandle | null;
+    /** Re-rendered on every change; `null` until the thread has been opened. */
+    snapshot: ThreadSnapshot | null;
+    /** Why the thread could not be opened; load failures live in `snapshot.error`. */
+    error: CommentsError | null;
+    /** Opens the thread again after `error`, or reloads it after a failed load. */
+    retry(): void;
+}
+/**
+ * Opens the page's thread and keeps a live snapshot of it. The handle is
+ * disposed on unmount and reopened when `identifier`, `url` or (without `url`)
+ * the page address changes; `sort` changes reload the same handle.
+ */
+declare function useThread(options?: UseThreadOptions): UseThreadResult;
+
+interface CommentCountState {
+    /** `null` while loading or after an error. */
+    count: number | null;
+    error: CommentsError | null;
+}
+/**
+ * Fetches a comment count once per ref. Lookups from the same render are
+ * batched into one request by the client; the count is not live.
+ */
+declare function useCommentCount(ref: CountRef | null, options?: {
+    forum?: string;
+}): CommentCountState;
+
+interface ForumThemeState {
+    /** `null` until loaded (or when `enabled` is false). */
+    theme: ForumTheme | null;
+    error: CommentsError | null;
+}
+/**
+ * The forum's palettes, fonts and theme stylesheets (`GET /comments/theme`),
+ * for sites that style their own UI after the forum. `<Comments theme="forum">`
+ * applies the same data to the widget.
+ */
+declare function useForumTheme(): ForumThemeState;
+
+export { type Appearance, type AppearanceElement, type AppearanceVariable, CommentCount, type CommentCountProps, type CommentCountState, type CommenterState, Comments, type CommentsAction, type CommentsEvent, type CommentsProps, type ComposerProps, type CountProps, DiscourseComments, type DiscourseCommentsProps, type ForumThemeState, type HeaderProps, type ItemProps, type ListProps, type RenderComment, type RootProps, type SignInMode, type SignInProps, type Theme, type UseThreadOptions, type UseThreadResult, useClient, useCommentCount, useCommenter, useForumTheme, useThread };

package/dist/react.d.ts

@@ -0,0 +1,335 @@
+import * as react from 'react';
+import { ReactNode } from 'react';
+import { g as Comment, V as Pending, o as Commenter, r as CommentsError, T as Messages, C as CreateClientOptions, a as CommentsClient, e as AuthStatus, c as AuthProvider, a1 as SignInOptions, U as OpenThreadOptions, Z as PostResult, a9 as ThreadHandle, ab as ThreadSnapshot, b as CountRef, N as ForumTheme } from './messages-C9bMljl3.js';
+
+/**
+ * `auto` follows `prefers-color-scheme`, `inherit` leaves the colours to the
+ * page, and `forum` applies the forum's own palettes, fonts and theme CSS.
+ */
+type Theme = "auto" | "light" | "dark" | "inherit" | "forum";
+/** Design tokens; each is set as `--gc-<kebab-case name>` on the widget root. */
+type AppearanceVariable = "font" | "fg" | "fgMuted" | "bg" | "bgSubtle" | "border" | "accent" | "accentFg" | "danger" | "radius" | "shadow" | "space" | "avatarSize";
+/** Elements that accept extra class names through `appearance.elements`. */
+type AppearanceElement = "root" | "header" | "count" | "sort" | "signIn" | "composer" | "textarea" | "toolbar" | "list" | "comment" | "avatar" | "meta" | "body" | "actions" | "menu" | "button" | "primaryButton" | "loadMore" | "pill" | "notice" | "dialog";
+interface Appearance {
+    /** Token overrides, e.g. `{ accent: "var(--brand)", radius: "0" }`. */
+    variables?: Partial<Record<AppearanceVariable, string>>;
+    /** Extra class names, e.g. `{ comment: "card", button: "btn" }`. */
+    elements?: Partial<Record<AppearanceElement, string>>;
+}
+
+/** What the widget was doing when an `error` event fired. */
+type CommentsAction = "open" | "load" | "loadMore" | "loadReplies" | "context" | "post" | "edit" | "delete" | "like" | "flag" | "pin" | "upload" | "preview" | "signIn" | "theme";
+/** Delivered to `<DiscourseComments onEvent>`. */
+type CommentsEvent = {
+    type: "comment.posted";
+    threadId: string;
+    comment: Comment;
+}
+/** The comment went to the review queue instead of being published. */
+ | {
+    type: "comment.pending";
+    threadId: string;
+    pending: Pending;
+} | {
+    type: "comment.liked";
+    threadId: string;
+    comment: Comment;
+    liked: boolean;
+} | {
+    type: "auth.signedIn";
+    user: Commenter;
+}
+/** `expired` is true when the forum ended the session (the key was revoked or expired). */
+ | {
+    type: "auth.signedOut";
+    expired: boolean;
+} | {
+    type: "error";
+    action: CommentsAction;
+    error: CommentsError;
+    threadId?: string;
+};
+
+interface ProviderOptions {
+    children?: ReactNode;
+    /** Default appearance for every widget inside; widgets merge their own on top. */
+    appearance?: Appearance;
+    /** UI language (`en`, `pt-BR`; other `pt*` map to `pt-BR`), also sent as `Accept-Language`. */
+    locale?: string;
+    /** Overrides for individual UI strings. */
+    messages?: Partial<Messages>;
+    theme?: Theme;
+    /** Logs client activity and shows setup diagnostics outside localhost. */
+    debug?: boolean;
+    onEvent?: (event: CommentsEvent) => void;
+}
+/** Client options beyond `forum`; they apply when the shared client is first created. */
+type ClientCreationOptions = Omit<CreateClientOptions, "forum" | "locale" | "debug">;
+type DiscourseCommentsProps = ProviderOptions & (({
+    forum: string;
+    client?: undefined;
+} & ClientCreationOptions) | {
+    client: CommentsClient;
+    forum?: undefined;
+});
+/**
+ * Shares one client (auth, config, counts batching, realtime) with every
+ * comments widget and hook below it.
+ */
+declare function DiscourseComments(props: DiscourseCommentsProps): react.JSX.Element;
+
+/** The client the surrounding `<DiscourseComments>` provides. */
+declare function useClient(): CommentsClient;
+
+interface PartProps {
+    className?: string;
+}
+declare function Avatar({ className }: PartProps): react.JSX.Element;
+/** Author, badges, timestamp (a `#gc-<id>` permalink) and edited mark. */
+declare function Meta({ className }: PartProps): react.JSX.Element;
+/** The comment's cooked HTML, or its inline editor while editing. */
+declare function Body({ className }: PartProps): react.JSX.Element;
+/** Like, reply and a menu with copy link, edit, delete, report and feature. */
+declare function Actions({ className }: PartProps): react.JSX.Element | null;
+
+interface ComposerProps {
+    /** Replies to this comment (the inline reply composer). */
+    replyTo?: Comment;
+    /** Edits this comment; its markdown is loaded from the forum. */
+    editing?: Comment;
+    placeholder?: string;
+    autoFocus?: boolean;
+    /** Called after a successful post or save, and when the reader cancels. */
+    onDone?: () => void;
+    className?: string;
+}
+/**
+ * The markdown composer. Without `replyTo`/`editing` it is the thread's main
+ * composer and renders only when the reader may write (or may sign in on submit).
+ */
+declare function Composer(props: ComposerProps): react.JSX.Element | null;
+
+/**
+ * Explains setup problems (origin not allowed, plugin disabled, basic auth
+ * blocking preflights…). Renders on localhost-like hosts or with `debug`.
+ */
+declare function DevPanel({ className }: {
+    className?: string;
+}): react.JSX.Element | null;
+
+interface HeaderProps {
+    /** Defaults to `<Comments.Count />` and `<Comments.Sort />`. */
+    children?: ReactNode;
+    className?: string;
+}
+declare function Header({ children, className }: HeaderProps): react.JSX.Element;
+interface CountProps {
+    /** Heading element; `h2` by default. */
+    as?: "h2" | "h3" | "h4" | "h5" | "h6" | "p" | "span";
+    /** Custom content for the comment count, e.g. `(n) => n`. */
+    render?: (count: number) => ReactNode;
+    className?: string;
+}
+declare function Count({ as: Tag, render, className }: CountProps): react.JSX.Element;
+declare function Sort({ className }: {
+    className?: string;
+}): react.JSX.Element | null;
+
+type RenderComment = (comment: Comment, depth: number) => ReactNode;
+interface ListProps {
+    /** Renders one comment; defaults to `<Comments.Item comment={c} depth={depth} />`. */
+    children?: RenderComment;
+    className?: string;
+}
+/** The comment tree, with its loading, error and "continue this thread" states. */
+declare function List({ children, className }: ListProps): react.JSX.Element | null;
+interface ItemProps {
+    comment: Comment;
+    /** 0 for top-level comments. */
+    depth?: number;
+    /** Replaces the default avatar, meta, body and actions. */
+    children?: ReactNode;
+    /** Render the comment without its replies (used for ancestors in a focused branch). */
+    showReplies?: boolean;
+    className?: string;
+}
+/** One comment: its card, inline reply/edit/report panels and its replies. */
+declare function Item({ comment, depth, children, showReplies, className }: ItemProps): react.JSX.Element;
+
+interface CommenterState {
+    user: Commenter | null;
+    status: AuthStatus;
+    /** The forum's sign-in providers; empty until the forum config has loaded. */
+    providers: readonly AuthProvider[];
+    /** The forum is answering anonymously under load: treat the widget as read-only. */
+    degraded: boolean;
+    /** Why the last sign-in failed or the session ended. */
+    error: CommentsError | null;
+    /** Opens the forum's sign-in popup; call it from a click handler so it is not blocked. */
+    signIn(options?: SignInOptions): Promise<Commenter | null>;
+    cancelSignIn(): void;
+    signOut(): Promise<void>;
+}
+/** The signed-in reader of the provider's forum (or of `forum`). */
+declare function useCommenter(options?: {
+    forum?: string;
+}): CommenterState;
+
+/**
+ * Where signing in happens: `inline` shows a "Join the conversation" panel,
+ * `on-submit` lets anonymous readers write and signs them in when they post,
+ * `manual` leaves it to the site (`useCommenter().signIn()`).
+ */
+type SignInMode = "inline" | "on-submit" | "manual";
+interface CommentsProps extends OpenThreadOptions {
+    /** Uses the shared client for this forum instead of the provider's. */
+    forum?: string;
+    /** Visual nesting levels; deeper replies collapse into "Continue this thread". */
+    maxDepth?: number;
+    signIn?: SignInMode;
+    /**
+     * With `signIn="manual"`, called when an anonymous reader tries to like or
+     * reply, so the site can start its own sign-in. Without it those actions are
+     * unavailable to anonymous readers in manual mode.
+     */
+    onSignInRequired?: () => void;
+    /** Hides every write action. */
+    readOnly?: boolean;
+    /** Comment id to scroll to and highlight; defaults to the `#gc-<id>` fragment. */
+    highlight?: number | null;
+    /** Shown above the composer; defaults to the forum's setting. */
+    guidelinesUrl?: string;
+    onPosted?: (result: PostResult) => void;
+    appearance?: Appearance;
+    /** Renders without the default styles; class names stay for targeting. */
+    unstyled?: boolean;
+    theme?: Theme;
+    locale?: string;
+    className?: string;
+}
+interface RootProps extends CommentsProps {
+    children?: ReactNode;
+}
+/**
+ * Opens the thread and provides it to the primitives inside. Without a
+ * provider or `forum` nothing can be opened, so it renders a quiet notice
+ * instead of throwing (a consumer's tests may mount pages without one).
+ */
+declare function Root(props: RootProps): react.JSX.Element;
+
+interface SignInProps {
+    /** Custom UI; called in every sign-in mode, including `manual`. */
+    children?: (commenter: CommenterState) => ReactNode;
+    className?: string;
+}
+/**
+ * Inline mode: a "Join the conversation" panel with the forum's providers.
+ * Signed in: who is commenting, with a sign-out button.
+ */
+declare function SignIn({ children, className }: SignInProps): react.JSX.Element | null;
+
+/** Read-only, closed and not-allowed notices that replace the composer. */
+declare function Notice({ className }: {
+    className?: string;
+}): react.JSX.Element | null;
+/** The "N new comments" pill for top-level comments that arrived live. */
+declare function NewComments({ className }: {
+    className?: string;
+}): react.JSX.Element;
+/** The reader's own comments that went to the review queue. */
+declare function AwaitingApproval({ className }: {
+    className?: string;
+}): react.JSX.Element;
+declare function LoadMore({ className }: {
+    className?: string;
+}): react.JSX.Element | null;
+
+/**
+ * The drop-in comments section for the current page, assembled from the
+ * `Comments.*` primitives that are also exported for custom layouts.
+ */
+declare function CommentsSection(props: CommentsProps): react.JSX.Element;
+declare const Comments: typeof CommentsSection & {
+    Root: typeof Root;
+    Header: typeof Header;
+    Count: typeof Count;
+    Sort: typeof Sort;
+    SignIn: typeof SignIn;
+    Composer: typeof Composer;
+    List: typeof List;
+    Item: typeof Item;
+    Avatar: typeof Avatar;
+    Meta: typeof Meta;
+    Body: typeof Body;
+    Actions: typeof Actions;
+    LoadMore: typeof LoadMore;
+    NewComments: typeof NewComments;
+    AwaitingApproval: typeof AwaitingApproval;
+    Notice: typeof Notice;
+    DevPanel: typeof DevPanel;
+};
+
+interface CommentCountProps {
+    identifier?: string;
+    /** Host the `identifier` belongs to; defaults to the current page's host. */
+    host?: string;
+    /** Defaults to the current page (canonical link, else the address). */
+    url?: string;
+    topicId?: number;
+    /** Uses the shared client for this forum instead of the provider's. */
+    forum?: string;
+    /** Custom content, e.g. `(n) => n` for just the number. */
+    render?: (count: number) => ReactNode;
+    className?: string;
+}
+/** "12 comments" for a page, fetched once on mount and batched with other counts. */
+declare function CommentCount({ identifier, host, url, topicId, forum, render, className, }: CommentCountProps): react.JSX.Element | null;
+
+interface UseThreadOptions extends OpenThreadOptions {
+    /** Uses the shared client for this forum instead of the provider's. */
+    forum?: string;
+}
+interface UseThreadResult {
+    /** `null` until the thread has been opened. */
+    thread: ThreadHandle | null;
+    /** Re-rendered on every change; `null` until the thread has been opened. */
+    snapshot: ThreadSnapshot | null;
+    /** Why the thread could not be opened; load failures live in `snapshot.error`. */
+    error: CommentsError | null;
+    /** Opens the thread again after `error`, or reloads it after a failed load. */
+    retry(): void;
+}
+/**
+ * Opens the page's thread and keeps a live snapshot of it. The handle is
+ * disposed on unmount and reopened when `identifier`, `url` or (without `url`)
+ * the page address changes; `sort` changes reload the same handle.
+ */
+declare function useThread(options?: UseThreadOptions): UseThreadResult;
+
+interface CommentCountState {
+    /** `null` while loading or after an error. */
+    count: number | null;
+    error: CommentsError | null;
+}
+/**
+ * Fetches a comment count once per ref. Lookups from the same render are
+ * batched into one request by the client; the count is not live.
+ */
+declare function useCommentCount(ref: CountRef | null, options?: {
+    forum?: string;
+}): CommentCountState;
+
+interface ForumThemeState {
+    /** `null` until loaded (or when `enabled` is false). */
+    theme: ForumTheme | null;
+    error: CommentsError | null;
+}
+/**
+ * The forum's palettes, fonts and theme stylesheets (`GET /comments/theme`),
+ * for sites that style their own UI after the forum. `<Comments theme="forum">`
+ * applies the same data to the widget.
+ */
+declare function useForumTheme(): ForumThemeState;
+
+export { type Appearance, type AppearanceElement, type AppearanceVariable, CommentCount, type CommentCountProps, type CommentCountState, type CommenterState, Comments, type CommentsAction, type CommentsEvent, type CommentsProps, type ComposerProps, type CountProps, DiscourseComments, type DiscourseCommentsProps, type ForumThemeState, type HeaderProps, type ItemProps, type ListProps, type RenderComment, type RootProps, type SignInMode, type SignInProps, type Theme, type UseThreadOptions, type UseThreadResult, useClient, useCommentCount, useCommenter, useForumTheme, useThread };