g-comments 0.0.0-stage → 0.1.0

package/dist/element.d.ts

@@ -0,0 +1,770 @@
+/** Public sort names (`DiscourseComments::Sort`). */
+type Sort = "best" | "hot" | "newest" | "oldest";
+/** Report reasons accepted by `POST …/comments/:id/flag` (`Comment::Flag::FLAG_TYPES`). */
+type FlagType = "off_topic" | "inappropriate" | "spam" | "illegal" | "notify_moderators";
+/** `discourse_comments_thread_creation` setting values. */
+type ThreadCreation = "first_view" | "first_comment";
+/** `CommenterSerializer`: the signed-in reader, mention results, exchange/me responses. */
+interface Commenter {
+    id: number;
+    username: string;
+    name: string | null;
+    avatar_url: string;
+    title: string | null;
+    staff: boolean;
+}
+/** `ClientConfig#auth_providers` entry. */
+interface AuthProvider {
+    name: string;
+    title: string;
+}
+interface ForumInfo {
+    name: string;
+    base_url: string;
+    locale: string;
+}
+interface Features {
+    nested: boolean;
+    hot_sort: boolean;
+    mentions: boolean;
+    uploads: boolean;
+    /** `null` when the reactions plugin is not installed. */
+    reactions: boolean | null;
+}
+interface Limits {
+    min_post_length: number;
+    max_post_length: number;
+    roots_per_page: number;
+    children_per_page: number;
+    max_image_size_kb: number;
+    /** Pipe-separated list, as stored in the `authorized_extensions` site setting. */
+    authorized_extensions: string;
+}
+/** `ConfigSerializer` (`GET /comments/config`). */
+interface Config {
+    forum: ForumInfo;
+    features: Features;
+    limits: Limits;
+    auth_providers: AuthProvider[];
+    sorts: Sort[];
+    default_sort: Sort;
+    thread_creation: ThreadCreation;
+    guidelines_url: string | null;
+    scope_version: number;
+    /** Present only when the request carried a valid user API key. */
+    current_user?: Commenter;
+    /** Set when the forum served the request anonymously under load; the key is still valid. */
+    degraded?: true;
+}
+/** `ThreadSerializer`: a page's thread once its topic exists. */
+interface Thread {
+    /** Opaque handle; the topic id as a string. */
+    id: string;
+    topic_id: number;
+    key: string;
+    url: string;
+    title: string | null;
+    count: number;
+    closed: boolean;
+    listed: boolean;
+    can_comment: boolean;
+    nested: boolean;
+    sorts: Sort[];
+    sort: Sort;
+    pinned_ids: number[];
+    realtime: "live" | "poll";
+    message_bus_last_id: number;
+    forum_url: string;
+}
+/** `VirtualThreadSerializer`: a page whose topic does not exist yet. */
+interface VirtualThread {
+    id: `v:${string}`;
+    topic_id: null;
+    key: string;
+    url: string;
+    title: string;
+    count: 0;
+    closed: false;
+    listed: false;
+    can_comment: boolean;
+    nested: boolean;
+    sorts: Sort[];
+    sort: Sort;
+    pinned_ids: [];
+    realtime: "pending";
+    /** MessageBus channel where the forum announces `{ topic_id }` on creation. */
+    pending_channel: string;
+    message_bus_last_id: null;
+    forum_url: null;
+}
+type AnyThread = Thread | VirtualThread;
+/** `CommentSerializer#author`; `null` on deleted placeholders. */
+interface CommentAuthor {
+    id: number | null;
+    username: string | null;
+    name: string | null;
+    avatar_url: string | null;
+    title: string | null;
+    staff: boolean;
+}
+interface CommentReplyTo {
+    number: number;
+    username: string | null;
+}
+interface CommentLikes {
+    count: number;
+    liked: boolean;
+    can_like: boolean;
+}
+interface CommentPermissions {
+    edit: boolean;
+    delete: boolean;
+    flag: boolean;
+    pin: boolean;
+}
+/** `CommentSerializer`. Treat as immutable: the SDK replaces nodes instead of mutating them. */
+interface Comment {
+    id: number;
+    number: number;
+    author: CommentAuthor | null;
+    /** Server-sanitized cooked HTML with absolute links; `""` for deleted placeholders. */
+    html: string;
+    created_at: string;
+    updated_at: string;
+    edited: boolean;
+    /** `null` for top-level comments. Carries the parent's post number, not its id. */
+    reply_to: CommentReplyTo | null;
+    children: Comment[];
+    direct_reply_count: number;
+    total_descendant_count: number;
+    pinned: boolean;
+    likes: CommentLikes;
+    can: CommentPermissions;
+    pending: boolean;
+    deleted: boolean;
+    hidden: boolean;
+    url: string | null;
+}
+/** `{ pending }` from `POST …/comments` when the comment went to the review queue. */
+interface Pending {
+    reviewable_id: number | null;
+    message: string | null;
+    pending_count: number | null;
+}
+/** `UploadSerializer` as returned by `POST …/attachments`. */
+interface Upload {
+    id: number;
+    url: string;
+    original_filename: string;
+    filesize: number;
+    width: number | null;
+    height: number | null;
+    thumbnail_width: number | null;
+    thumbnail_height: number | null;
+    extension: string;
+    short_url: string;
+    short_path: string;
+    retain_hours: number | null;
+    human_filesize: string;
+    dominant_color: string | null;
+}
+/** Comment counts keyed by encoded ref (`url:…`, `id:<host>/<identifier>`, `t:<topic_id>`). */
+type Counts = Record<string, number>;
+type CountRef = {
+    url: string;
+} | {
+    identifier: string;
+    host?: string;
+} | {
+    topicId: number;
+};
+
+type CommentsErrorType = "invalid_key" | "not_logged_in" | "invalid_access" | "invalid_parameters" | "not_found" | "rate_limit" | "thread_conflict" | "page_not_allowed" | "invalid_url" | "no_category" | "thread_not_created" | "invalid_grant" | "user_not_allowed" | "submission_rejected" | "not_a_root_comment" | "pin_limit_reached" | "cancelled" | "storage_unavailable" | "unreachable" | "unknown";
+interface CommentsErrorOptions {
+    status?: number;
+    errors?: string[];
+    extras?: Record<string, unknown>;
+    waitSeconds?: number;
+    hint?: string;
+    serverType?: string;
+    cause?: unknown;
+}
+declare class CommentsError extends Error {
+    readonly name = "CommentsError";
+    readonly type: CommentsErrorType;
+    /** HTTP status, or 0 when no response was received. */
+    readonly status: number;
+    /** Human-readable messages from the server, safe to show inline. */
+    readonly errors: string[];
+    readonly extras: Record<string, unknown> | undefined;
+    /** Seconds until a rate-limited action may be retried. */
+    readonly waitSeconds: number | undefined;
+    /** Developer-facing explanation of the probable cause (setup problems). */
+    readonly hint: string | undefined;
+    /** The raw `error_type` from the server, if it sent one. */
+    readonly serverType: string | undefined;
+    constructor(type: CommentsErrorType, message: string, options?: CommentsErrorOptions);
+}
+
+/** 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";
+/** 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;
+};
+
+type AuthStatus = "anonymous" | "signing-in" | "signed-in";
+interface AuthState {
+    readonly status: AuthStatus;
+    readonly user: Commenter | null;
+    /** The forum served a request anonymously under load. The key is kept; treat the UI as read-only. */
+    readonly degraded: boolean;
+    /** Why the last sign-in failed or the session ended (`invalid_key` means it expired). */
+    readonly error: CommentsError | null;
+}
+interface SignInOptions {
+    /** An `auth_providers[].name` to go straight to that provider. */
+    provider?: string;
+    /** Defaults to `popup`; a blocked popup falls back to `redirect`. */
+    mode?: "popup" | "redirect";
+}
+interface CommentsAuth {
+    readonly status: AuthStatus;
+    readonly user: Commenter | null;
+    /** From `config().auth_providers`; empty until the config has loaded. */
+    readonly providers: readonly AuthProvider[];
+    /** Per-browser id the forum's user API key is bound to. */
+    readonly clientId: string;
+    /** Immutable, referentially stable while nothing changes. */
+    state(): AuthState;
+    onChange(listener: (state: AuthState) => void): () => void;
+    /** Resolves with the user (popup) or `null` once a redirect has started. */
+    signIn(options?: SignInOptions): Promise<Commenter | null>;
+    /** Abandons a pending popup sign-in. */
+    cancelSignIn(): void;
+    signOut(): Promise<void>;
+    /** Completes a redirect sign-in from `#gc_code=…&gc_nonce=…`; runs once per page load. */
+    handleRedirect(): Promise<Commenter | null>;
+}
+
+interface ComposerTiming {
+    typingDurationMsecs: number;
+    composerOpenDurationMsecs: number;
+}
+/**
+ * Measures what the forum's fast-typer check needs (`typing_duration_msecs`,
+ * `composer_open_duration_msecs`). Without it, a new account's first comments
+ * land in the review queue.
+ */
+interface ComposerTimer {
+    readonly started: boolean;
+    /** Call when the composer opens or gains focus; repeated calls are no-ops. */
+    start(): void;
+    /** Call on every input event. */
+    typing(): void;
+    measure(): ComposerTiming;
+    /** Returns the measurement and resets the timer. */
+    stop(): ComposerTiming;
+}
+
+type ThreadStatus = "idle" | "loading" | "ready" | "error";
+/** How updates arrive: MessageBus, the interval fallback, or not at all. */
+type ConnectionMode = "live" | "interval" | "off";
+interface BranchState {
+    /** Last children page loaded for this comment (-1 = only the preloaded ones). */
+    readonly page: number;
+    readonly loading: boolean;
+    readonly hasMore: boolean;
+}
+interface ThreadSnapshot {
+    readonly thread: AnyThread;
+    /** True until the page's topic exists (`thread.id` starts with `v:`). */
+    readonly virtual: boolean;
+    /** Top-level comments with their loaded replies nested in `children`. */
+    readonly comments: readonly Comment[];
+    readonly sort: Sort;
+    readonly status: ThreadStatus;
+    readonly error: CommentsError | null;
+    readonly page: number;
+    readonly hasMore: boolean;
+    readonly loadingMore: boolean;
+    /** Top-level comments that arrived live and wait for `showPending()`. */
+    readonly pendingNew: number;
+    readonly branches: Readonly<Record<number, BranchState>>;
+    /** The reader's own comments that went to the review queue. */
+    readonly awaitingApproval: readonly Pending[];
+    readonly connection: ConnectionMode;
+}
+type ThreadEvent = {
+    type: "change";
+    snapshot: ThreadSnapshot;
+} | {
+    type: "comment.posted";
+    comment: Comment;
+} | {
+    type: "comment.pending";
+    pending: Pending;
+} | {
+    type: "comment.edited";
+    comment: Comment;
+} | {
+    type: "comment.removed";
+    id: number;
+} | {
+    type: "comment.received";
+    comment: Comment;
+    buffered: boolean;
+} | {
+    type: "thread.created";
+    thread: Thread;
+};
+interface PostOptions {
+    body: string;
+    /** Id of the comment being replied to (never a post number). */
+    replyTo?: number;
+    typingDurationMsecs?: number;
+    composerOpenDurationMsecs?: number;
+    /** Timer to read when the durations are not passed; defaults to `thread.composer`. */
+    composer?: ComposerTimer;
+}
+type PostResult = {
+    type: "created";
+    comment: Comment;
+} | {
+    type: "pending";
+    pending: Pending;
+};
+interface FlagOptions {
+    type: FlagType;
+    message?: string;
+}
+interface CommentContext {
+    ancestors: Comment[];
+    ancestorsTruncated: boolean;
+    comment: Comment;
+}
+interface ThreadHandle {
+    /** Current handle; changes from `v:…` to the topic id once the thread is created. */
+    readonly id: string;
+    /** Default timer for the thread's main composer. */
+    readonly composer: ComposerTimer;
+    /** Immutable; the same object is returned until something changes. */
+    snapshot(): ThreadSnapshot;
+    subscribe(listener: (event: ThreadEvent) => void): () => void;
+    load(): Promise<void>;
+    loadMore(): Promise<void>;
+    loadReplies(commentId: number): Promise<void>;
+    setSort(sort: Sort): Promise<void>;
+    post(options: PostOptions): Promise<PostResult>;
+    edit(commentId: number, body: string): Promise<Comment>;
+    remove(commentId: number): Promise<void>;
+    like(commentId: number): Promise<Comment>;
+    unlike(commentId: number): Promise<Comment>;
+    flag(commentId: number, options: FlagOptions): Promise<void>;
+    pin(commentId: number): Promise<void>;
+    unpin(commentId: number): Promise<void>;
+    /** Markdown source, for editing. */
+    raw(commentId: number): Promise<string>;
+    /** Moves live-arrived top-level comments into `comments`. */
+    showPending(): void;
+    /** Loads a comment with its ancestors into the tree (deep links). */
+    context(commentId: number): Promise<CommentContext>;
+    dispose(): void;
+}
+
+interface OpenThreadOptions {
+    /** Defaults to `<link rel="canonical">`, else `location.href`. */
+    url?: string;
+    /** Defaults to `document.title`. */
+    title?: string;
+    /** Optional stable key, namespaced by the page's canonical host on the forum. */
+    identifier?: string;
+    /** Initial sort; defaults to the forum's default. */
+    sort?: Sort;
+}
+interface UploadOptions {
+    filename?: string;
+    /** Marks the file as pasted from the clipboard. */
+    pasted?: boolean;
+}
+interface CommentsClient {
+    /** Normalized forum base URL. */
+    readonly forum: string;
+    readonly forumOrigin: string;
+    readonly locale: string | undefined;
+    readonly auth: CommentsAuth;
+    readonly threads: {
+        /** Resolves (or creates) the page's thread and loads its first page of comments. */
+        open(options?: OpenThreadOptions): Promise<ThreadHandle>;
+    };
+    readonly attachments: {
+        upload(threadId: string, file: Blob, options?: UploadOptions): Promise<Upload>;
+    };
+    /** Cached; refetched after sign-in and sign-out. */
+    config(): Promise<Config>;
+    /** Batched per tick, at most 50 refs per request. Keys are encoded refs (see `encodeRef`). */
+    counts(refs: readonly CountRef[]): Promise<Counts>;
+    count(ref: CountRef): Promise<number>;
+    /** Cooks markdown into sanitized HTML (signed-in only). */
+    preview(body: string): Promise<string>;
+    /** User search for @mentions (signed-in only). */
+    mentions(query: string, threadId?: string): Promise<Commenter[]>;
+    /** Stops realtime, timers and listeners for every thread of this client. */
+    dispose(): void;
+}
+
+/** `auto` follows `prefers-color-scheme`; `inherit` leaves the colours to the page. */
+type Theme = "auto" | "light" | "dark" | "inherit";
+
+/**
+ * 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";
+
+/** How an attribute's string becomes a prop: a list means one of those values. */
+type AttributeType = "string" | "number" | "boolean" | readonly string[];
+interface AttributeSpec {
+    /** The camelCase prop (and element property) the attribute feeds. */
+    readonly prop: string;
+    readonly type: AttributeType;
+}
+/** Attribute name to spec; the keys are the element's `observedAttributes`. */
+type AttributeSchema = Readonly<Record<string, AttributeSpec>>;
+
+declare const HTMLElementBase: typeof HTMLElement;
+/**
+ * A custom element that renders a React tree into its own shadow root:
+ * attributes become props (see `schema`), `gc-*` classes become `::part()`
+ * names, and the tree re-renders once per task however many attributes change.
+ */
+declare abstract class ReactHostElement<P extends object> extends HTMLElementBase {
+    #private;
+    /** Attribute to prop mapping; subclasses override it and call `reflect()`. */
+    static readonly schema: AttributeSchema;
+    static get observedAttributes(): string[];
+    /** Mirrors the schema's props onto the prototype as attribute-backed accessors. */
+    static reflect(this: typeof ReactHostElement<object>): void;
+    protected constructor(mountTag: string, styles: readonly string[]);
+    connectedCallback(): void;
+    disconnectedCallback(): void;
+    attributeChangedCallback(): void;
+    /** Re-renders once the current task ends; a no-op before the element is connected. */
+    protected requestRender(): void;
+    /** The current attribute values as props. */
+    protected props(): P;
+    /** The React tree for `props`; `null` renders nothing. */
+    protected abstract render(props: P): unknown;
+    /** Dispatches `gc:<name>` from the host; it bubbles and crosses the shadow boundary. */
+    protected emit(name: string, detail?: unknown): void;
+}
+
+/** `<discourse-comments>` attributes and the `<Comments>` props they map to. */
+declare const COMMENTS_ATTRIBUTES: {
+    readonly forum: {
+        readonly prop: "forum";
+        readonly type: "string";
+    };
+    readonly identifier: {
+        readonly prop: "identifier";
+        readonly type: "string";
+    };
+    readonly url: {
+        readonly prop: "url";
+        readonly type: "string";
+    };
+    readonly title: {
+        readonly prop: "title";
+        readonly type: "string";
+    };
+    readonly sort: {
+        readonly prop: "sort";
+        readonly type: readonly ["best", "hot", "newest", "oldest"];
+    };
+    readonly "sign-in": {
+        readonly prop: "signIn";
+        readonly type: readonly ["inline", "on-submit", "manual"];
+    };
+    readonly theme: {
+        readonly prop: "theme";
+        readonly type: readonly ["auto", "light", "dark", "inherit"];
+    };
+    readonly locale: {
+        readonly prop: "locale";
+        readonly type: "string";
+    };
+    readonly "max-depth": {
+        readonly prop: "maxDepth";
+        readonly type: "number";
+    };
+    readonly "read-only": {
+        readonly prop: "readOnly";
+        readonly type: "boolean";
+    };
+    readonly highlight: {
+        readonly prop: "highlight";
+        readonly type: "number";
+    };
+    readonly "guidelines-url": {
+        readonly prop: "guidelinesUrl";
+        readonly type: "string";
+    };
+    readonly unstyled: {
+        readonly prop: "unstyled";
+        readonly type: "boolean";
+    };
+    readonly debug: {
+        readonly prop: "debug";
+        readonly type: "boolean";
+    };
+};
+/** The props read from a `<discourse-comments>` element's attributes. */
+interface DiscourseCommentsElementProps {
+    forum?: string;
+    identifier?: string;
+    url?: string;
+    title?: string;
+    sort?: Sort;
+    signIn?: SignInMode;
+    theme?: Theme;
+    locale?: string;
+    maxDepth?: number;
+    readOnly?: boolean;
+    highlight?: number;
+    guidelinesUrl?: string;
+    unstyled?: boolean;
+    debug?: boolean;
+}
+/**
+ * `<discourse-comments forum identifier url title sort sign-in theme locale
+ * max-depth read-only highlight guidelines-url unstyled debug>`: the drop-in
+ * comments section in a shadow root with the default stylesheet. Every
+ * attribute is also a property, and the widget's events are dispatched from the
+ * element as `gc:<type>` custom events (`gc:comment.posted`, `gc:error`, …).
+ */
+declare class DiscourseCommentsElement extends ReactHostElement<DiscourseCommentsElementProps> {
+    #private;
+    static readonly schema: {
+        readonly forum: {
+            readonly prop: "forum";
+            readonly type: "string";
+        };
+        readonly identifier: {
+            readonly prop: "identifier";
+            readonly type: "string";
+        };
+        readonly url: {
+            readonly prop: "url";
+            readonly type: "string";
+        };
+        readonly title: {
+            readonly prop: "title";
+            readonly type: "string";
+        };
+        readonly sort: {
+            readonly prop: "sort";
+            readonly type: readonly ["best", "hot", "newest", "oldest"];
+        };
+        readonly "sign-in": {
+            readonly prop: "signIn";
+            readonly type: readonly ["inline", "on-submit", "manual"];
+        };
+        readonly theme: {
+            readonly prop: "theme";
+            readonly type: readonly ["auto", "light", "dark", "inherit"];
+        };
+        readonly locale: {
+            readonly prop: "locale";
+            readonly type: "string";
+        };
+        readonly "max-depth": {
+            readonly prop: "maxDepth";
+            readonly type: "number";
+        };
+        readonly "read-only": {
+            readonly prop: "readOnly";
+            readonly type: "boolean";
+        };
+        readonly highlight: {
+            readonly prop: "highlight";
+            readonly type: "number";
+        };
+        readonly "guidelines-url": {
+            readonly prop: "guidelinesUrl";
+            readonly type: "string";
+        };
+        readonly unstyled: {
+            readonly prop: "unstyled";
+            readonly type: "boolean";
+        };
+        readonly debug: {
+            readonly prop: "debug";
+            readonly type: "boolean";
+        };
+    };
+    forum: string | undefined;
+    identifier: string | undefined;
+    url: string | undefined;
+    sort: Sort | undefined;
+    signIn: SignInMode | undefined;
+    theme: Theme | undefined;
+    locale: string | undefined;
+    maxDepth: number | undefined;
+    readOnly: boolean;
+    highlight: number | undefined;
+    guidelinesUrl: string | undefined;
+    unstyled: boolean;
+    debug: boolean;
+    constructor();
+    /**
+     * The client the widget uses: one set here (for options such as `headers`),
+     * else the page-wide shared client for `forum`. `null` without either.
+     */
+    get client(): CommentsClient | null;
+    set client(client: CommentsClient | null);
+    protected render(props: DiscourseCommentsElementProps): unknown;
+}
+
+declare const FORMATS: readonly ["text", "number"];
+/** `<discourse-comment-count>` attributes and the `<CommentCount>` props they map to. */
+declare const COUNT_ATTRIBUTES: {
+    readonly forum: {
+        readonly prop: "forum";
+        readonly type: "string";
+    };
+    readonly identifier: {
+        readonly prop: "identifier";
+        readonly type: "string";
+    };
+    readonly host: {
+        readonly prop: "host";
+        readonly type: "string";
+    };
+    readonly url: {
+        readonly prop: "url";
+        readonly type: "string";
+    };
+    readonly "topic-id": {
+        readonly prop: "topicId";
+        readonly type: "number";
+    };
+    readonly format: {
+        readonly prop: "format";
+        readonly type: readonly ["text", "number"];
+    };
+};
+/** The props read from a `<discourse-comment-count>` element's attributes. */
+interface DiscourseCommentCountElementProps {
+    forum?: string;
+    identifier?: string;
+    host?: string;
+    url?: string;
+    topicId?: number;
+    /** `text` is "12 comments"; `number` is just the number. */
+    format?: (typeof FORMATS)[number];
+}
+/**
+ * `<discourse-comment-count forum identifier host url topic-id format>`:
+ * "12 comments" for a page, fetched once and batched with the other counts on
+ * the page. Unstyled: it inherits the page's font and colour.
+ */
+declare class DiscourseCommentCountElement extends ReactHostElement<DiscourseCommentCountElementProps> {
+    #private;
+    static readonly schema: {
+        readonly forum: {
+            readonly prop: "forum";
+            readonly type: "string";
+        };
+        readonly identifier: {
+            readonly prop: "identifier";
+            readonly type: "string";
+        };
+        readonly host: {
+            readonly prop: "host";
+            readonly type: "string";
+        };
+        readonly url: {
+            readonly prop: "url";
+            readonly type: "string";
+        };
+        readonly "topic-id": {
+            readonly prop: "topicId";
+            readonly type: "number";
+        };
+        readonly format: {
+            readonly prop: "format";
+            readonly type: readonly ["text", "number"];
+        };
+    };
+    forum: string | undefined;
+    identifier: string | undefined;
+    host: string | undefined;
+    url: string | undefined;
+    topicId: number | undefined;
+    format: DiscourseCommentCountElementProps["format"];
+    constructor();
+    /** The client the count uses: one set here, else the shared client for `forum`. */
+    get client(): CommentsClient | null;
+    set client(client: CommentsClient | null);
+    protected render(props: DiscourseCommentCountElementProps): unknown;
+}
+
+interface DefineElementsOptions {
+    /** Tag name for the comments section; default `discourse-comments`. */
+    comments?: string;
+    /** Tag name for the count; default `discourse-comment-count`. */
+    count?: string;
+}
+declare const COMMENTS_TAG = "discourse-comments";
+declare const COUNT_TAG = "discourse-comment-count";
+/**
+ * Registers the elements, skipping names that are already defined (importing
+ * the module does this with the default names). Pass other names to register
+ * the same elements under them as well.
+ */
+declare function defineElements({ comments, count, }?: DefineElementsOptions): void;
+
+/** `gc:<type>` events dispatched by `<discourse-comments>`, keyed by event name. */
+type DiscourseCommentsEventMap = {
+    [E in CommentsEvent as `gc:${E["type"]}`]: CustomEvent<E>;
+} & {
+    /** With `sign-in="manual"`, an anonymous reader asked to like or reply. */
+    "gc:sign-in-required": CustomEvent<undefined>;
+};
+declare global {
+    interface HTMLElementTagNameMap {
+        "discourse-comments": DiscourseCommentsElement;
+        "discourse-comment-count": DiscourseCommentCountElement;
+    }
+    interface HTMLElementEventMap extends DiscourseCommentsEventMap {
+    }
+}
+
+export { type AttributeSchema, type AttributeSpec, type AttributeType, COMMENTS_ATTRIBUTES, COMMENTS_TAG, COUNT_ATTRIBUTES, COUNT_TAG, type CommentsEvent, type DefineElementsOptions, DiscourseCommentCountElement, type DiscourseCommentCountElementProps, DiscourseCommentsElement, type DiscourseCommentsElementProps, type DiscourseCommentsEventMap, defineElements };