@ciridae/ui 0.17.0 → 1.0.1

package/dist/feedback/contract.d.ts

@@ -0,0 +1,252 @@
+import type { FeedbackCreateRequest, FeedbackAttachment, FeedbackErrorDetail, FeedbackItem, FeedbackMessage, FeedbackMessageCreateRequest, FeedbackStatusEvent, FeedbackSummary, FeedbackUpdateRequest } from "./generated/types.gen.js";
+declare const feedbackCreateHeadersSchema: import("zod/index.cjs").ZodObject<{
+    'Idempotency-Key': import("zod/index.cjs").ZodUUID;
+    'X-POSTHOG-SESSION-ID': import("zod/index.cjs").ZodOptional<import("zod/index.cjs").ZodNullable<import("zod/index.cjs").ZodString>>;
+}, import("zod/v4/core/schemas.cjs").$strip>;
+declare const feedbackAttachmentSchema: import("zod/index.cjs").ZodObject<{
+    id: import("zod/index.cjs").ZodString;
+    name: import("zod/index.cjs").ZodString;
+    size: import("zod/index.cjs").ZodInt;
+    url: import("zod/index.cjs").ZodOptional<import("zod/index.cjs").ZodNullable<import("zod/index.cjs").ZodURL>>;
+}, import("zod/v4/core/schemas.cjs").$strip>;
+declare const feedbackCreateInputSchema: import("zod/index.cjs").ZodObject<{
+    subject: import("zod/index.cjs").ZodString;
+    description: import("zod/index.cjs").ZodString;
+    type: import("zod/index.cjs").ZodEnum<{
+        general: "general";
+        bug: "bug";
+        feature: "feature";
+    }>;
+    urgency: import("zod/index.cjs").ZodDefault<import("zod/index.cjs").ZodOptional<import("zod/index.cjs").ZodEnum<{
+        normal: "normal";
+        emergency: "emergency";
+    }>>>;
+    affectedScope: import("zod/index.cjs").ZodDefault<import("zod/index.cjs").ZodOptional<import("zod/index.cjs").ZodEnum<{
+        unknown: "unknown";
+        everyone: "everyone";
+        just_me: "just_me";
+        my_team: "my_team";
+    }>>>;
+}, import("zod/v4/core/schemas.cjs").$strict>;
+declare const feedbackErrorResponseSchema: import("zod/index.cjs").ZodObject<{
+    detail: import("zod/index.cjs").ZodObject<{
+        code: import("zod/index.cjs").ZodEnum<{
+            feedback_access_denied: "feedback_access_denied";
+            feedback_auth_unavailable: "feedback_auth_unavailable";
+            feedback_invalid_token: "feedback_invalid_token";
+            feedback_not_editable: "feedback_not_editable";
+            feedback_not_found: "feedback_not_found";
+            feedback_not_replyable: "feedback_not_replyable";
+            feedback_scope_not_found: "feedback_scope_not_found";
+            feedback_unavailable: "feedback_unavailable";
+        }>;
+        detail: import("zod/index.cjs").ZodString;
+    }, import("zod/v4/core/schemas.cjs").$strip>;
+}, import("zod/v4/core/schemas.cjs").$strip>;
+declare const feedbackItemSchema: import("zod/index.cjs").ZodObject<{
+    id: import("zod/index.cjs").ZodUUID;
+    subject: import("zod/index.cjs").ZodString;
+    description: import("zod/index.cjs").ZodString;
+    type: import("zod/index.cjs").ZodEnum<{
+        general: "general";
+        bug: "bug";
+        feature: "feature";
+    }>;
+    urgency: import("zod/index.cjs").ZodEnum<{
+        normal: "normal";
+        emergency: "emergency";
+    }>;
+    affectedScope: import("zod/index.cjs").ZodEnum<{
+        unknown: "unknown";
+        everyone: "everyone";
+        just_me: "just_me";
+        my_team: "my_team";
+    }>;
+    status: import("zod/index.cjs").ZodEnum<{
+        in_progress: "in_progress";
+        completed: "completed";
+        received: "received";
+        discussion_required: "discussion_required";
+        no_action: "no_action";
+        withdrawn: "withdrawn";
+    }>;
+    createdAt: import("zod/index.cjs").ZodISODateTime;
+    updatedAt: import("zod/index.cjs").ZodISODateTime;
+    canEdit: import("zod/index.cjs").ZodBoolean;
+    canWithdraw: import("zod/index.cjs").ZodBoolean;
+    canReply: import("zod/index.cjs").ZodBoolean;
+    createdAt_epoch_milliseconds: import("zod/index.cjs").ZodInt;
+    updatedAt_epoch_milliseconds: import("zod/index.cjs").ZodInt;
+    statusTimeline: import("zod/index.cjs").ZodArray<import("zod/index.cjs").ZodObject<{
+        id: import("zod/index.cjs").ZodString;
+        status: import("zod/index.cjs").ZodEnum<{
+            in_progress: "in_progress";
+            completed: "completed";
+            received: "received";
+            discussion_required: "discussion_required";
+            no_action: "no_action";
+            withdrawn: "withdrawn";
+        }>;
+        createdAt: import("zod/index.cjs").ZodISODateTime;
+        createdAt_epoch_milliseconds: import("zod/index.cjs").ZodInt;
+    }, import("zod/v4/core/schemas.cjs").$strip>>;
+    messages: import("zod/index.cjs").ZodArray<import("zod/index.cjs").ZodObject<{
+        id: import("zod/index.cjs").ZodString;
+        author: import("zod/index.cjs").ZodObject<{
+            role: import("zod/index.cjs").ZodEnum<{
+                operator: "operator";
+                reporter: "reporter";
+            }>;
+            name: import("zod/index.cjs").ZodString;
+        }, import("zod/v4/core/schemas.cjs").$strip>;
+        body: import("zod/index.cjs").ZodString;
+        createdAt: import("zod/index.cjs").ZodISODateTime;
+        editedAt: import("zod/index.cjs").ZodNullable<import("zod/index.cjs").ZodISODateTime>;
+        createdAt_epoch_milliseconds: import("zod/index.cjs").ZodInt;
+        editedAt_epoch_milliseconds: import("zod/index.cjs").ZodNullable<import("zod/index.cjs").ZodInt>;
+    }, import("zod/v4/core/schemas.cjs").$strip>>;
+    attachments: import("zod/index.cjs").ZodDefault<import("zod/index.cjs").ZodOptional<import("zod/index.cjs").ZodArray<import("zod/index.cjs").ZodObject<{
+        id: import("zod/index.cjs").ZodString;
+        name: import("zod/index.cjs").ZodString;
+        size: import("zod/index.cjs").ZodInt;
+        url: import("zod/index.cjs").ZodOptional<import("zod/index.cjs").ZodNullable<import("zod/index.cjs").ZodURL>>;
+    }, import("zod/v4/core/schemas.cjs").$strip>>>>;
+}, import("zod/v4/core/schemas.cjs").$strip>;
+declare const feedbackListResponseSchema: import("zod/index.cjs").ZodObject<{
+    items: import("zod/index.cjs").ZodArray<import("zod/index.cjs").ZodObject<{
+        id: import("zod/index.cjs").ZodUUID;
+        subject: import("zod/index.cjs").ZodString;
+        description: import("zod/index.cjs").ZodString;
+        type: import("zod/index.cjs").ZodEnum<{
+            general: "general";
+            bug: "bug";
+            feature: "feature";
+        }>;
+        urgency: import("zod/index.cjs").ZodEnum<{
+            normal: "normal";
+            emergency: "emergency";
+        }>;
+        affectedScope: import("zod/index.cjs").ZodEnum<{
+            unknown: "unknown";
+            everyone: "everyone";
+            just_me: "just_me";
+            my_team: "my_team";
+        }>;
+        status: import("zod/index.cjs").ZodEnum<{
+            in_progress: "in_progress";
+            completed: "completed";
+            received: "received";
+            discussion_required: "discussion_required";
+            no_action: "no_action";
+            withdrawn: "withdrawn";
+        }>;
+        createdAt: import("zod/index.cjs").ZodISODateTime;
+        updatedAt: import("zod/index.cjs").ZodISODateTime;
+        canEdit: import("zod/index.cjs").ZodBoolean;
+        canWithdraw: import("zod/index.cjs").ZodBoolean;
+        canReply: import("zod/index.cjs").ZodBoolean;
+        createdAt_epoch_milliseconds: import("zod/index.cjs").ZodInt;
+        updatedAt_epoch_milliseconds: import("zod/index.cjs").ZodInt;
+    }, import("zod/v4/core/schemas.cjs").$strip>>;
+}, import("zod/v4/core/schemas.cjs").$strip>;
+declare const feedbackMessageCreateInputSchema: import("zod/index.cjs").ZodObject<{
+    body: import("zod/index.cjs").ZodString;
+}, import("zod/v4/core/schemas.cjs").$strict>;
+declare const feedbackMessageSchema: import("zod/index.cjs").ZodObject<{
+    id: import("zod/index.cjs").ZodString;
+    author: import("zod/index.cjs").ZodObject<{
+        role: import("zod/index.cjs").ZodEnum<{
+            operator: "operator";
+            reporter: "reporter";
+        }>;
+        name: import("zod/index.cjs").ZodString;
+    }, import("zod/v4/core/schemas.cjs").$strip>;
+    body: import("zod/index.cjs").ZodString;
+    createdAt: import("zod/index.cjs").ZodISODateTime;
+    editedAt: import("zod/index.cjs").ZodNullable<import("zod/index.cjs").ZodISODateTime>;
+    createdAt_epoch_milliseconds: import("zod/index.cjs").ZodInt;
+    editedAt_epoch_milliseconds: import("zod/index.cjs").ZodNullable<import("zod/index.cjs").ZodInt>;
+}, import("zod/v4/core/schemas.cjs").$strip>;
+declare const feedbackStatusEventSchema: import("zod/index.cjs").ZodObject<{
+    id: import("zod/index.cjs").ZodString;
+    status: import("zod/index.cjs").ZodEnum<{
+        in_progress: "in_progress";
+        completed: "completed";
+        received: "received";
+        discussion_required: "discussion_required";
+        no_action: "no_action";
+        withdrawn: "withdrawn";
+    }>;
+    createdAt: import("zod/index.cjs").ZodISODateTime;
+    createdAt_epoch_milliseconds: import("zod/index.cjs").ZodInt;
+}, import("zod/v4/core/schemas.cjs").$strip>;
+declare const feedbackStatusSchema: import("zod/index.cjs").ZodEnum<{
+    in_progress: "in_progress";
+    completed: "completed";
+    received: "received";
+    discussion_required: "discussion_required";
+    no_action: "no_action";
+    withdrawn: "withdrawn";
+}>;
+declare const feedbackSummarySchema: import("zod/index.cjs").ZodObject<{
+    id: import("zod/index.cjs").ZodUUID;
+    subject: import("zod/index.cjs").ZodString;
+    description: import("zod/index.cjs").ZodString;
+    type: import("zod/index.cjs").ZodEnum<{
+        general: "general";
+        bug: "bug";
+        feature: "feature";
+    }>;
+    urgency: import("zod/index.cjs").ZodEnum<{
+        normal: "normal";
+        emergency: "emergency";
+    }>;
+    affectedScope: import("zod/index.cjs").ZodEnum<{
+        unknown: "unknown";
+        everyone: "everyone";
+        just_me: "just_me";
+        my_team: "my_team";
+    }>;
+    status: import("zod/index.cjs").ZodEnum<{
+        in_progress: "in_progress";
+        completed: "completed";
+        received: "received";
+        discussion_required: "discussion_required";
+        no_action: "no_action";
+        withdrawn: "withdrawn";
+    }>;
+    createdAt: import("zod/index.cjs").ZodISODateTime;
+    updatedAt: import("zod/index.cjs").ZodISODateTime;
+    canEdit: import("zod/index.cjs").ZodBoolean;
+    canWithdraw: import("zod/index.cjs").ZodBoolean;
+    canReply: import("zod/index.cjs").ZodBoolean;
+    createdAt_epoch_milliseconds: import("zod/index.cjs").ZodInt;
+    updatedAt_epoch_milliseconds: import("zod/index.cjs").ZodInt;
+}, import("zod/v4/core/schemas.cjs").$strip>;
+declare const feedbackTypeSchema: import("zod/index.cjs").ZodEnum<{
+    general: "general";
+    bug: "bug";
+    feature: "feature";
+}>;
+declare const feedbackUpdateInputSchema: import("zod/index.cjs").ZodObject<{
+    subject: import("zod/index.cjs").ZodOptional<import("zod/index.cjs").ZodNullable<import("zod/index.cjs").ZodString>>;
+    description: import("zod/index.cjs").ZodOptional<import("zod/index.cjs").ZodNullable<import("zod/index.cjs").ZodString>>;
+}, import("zod/v4/core/schemas.cjs").$strict>;
+declare const feedbackMaxLengths: {
+    readonly description: number;
+    readonly subject: number;
+};
+/** How many files one create request takes, and the most bytes each may hold. */
+declare const feedbackAttachmentLimits: {
+    readonly count: number;
+    readonly bytes: number;
+};
+type FeedbackAffectedScope = FeedbackSummary["affectedScope"];
+type FeedbackCreateInput = FeedbackCreateRequest;
+type FeedbackErrorCode = FeedbackErrorDetail["code"];
+type FeedbackMessageCreateInput = FeedbackMessageCreateRequest;
+type FeedbackStatus = FeedbackSummary["status"];
+type FeedbackType = FeedbackSummary["type"];
+type FeedbackUrgency = FeedbackSummary["urgency"];
+type FeedbackUpdateInput = FeedbackUpdateRequest;
+export { feedbackAttachmentLimits, feedbackAttachmentSchema, type FeedbackAttachment, feedbackCreateHeadersSchema, feedbackCreateInputSchema, feedbackErrorResponseSchema, feedbackItemSchema, feedbackListResponseSchema, feedbackMessageCreateInputSchema, feedbackMessageSchema, feedbackMaxLengths, feedbackStatusEventSchema, feedbackStatusSchema, feedbackSummarySchema, feedbackTypeSchema, feedbackUpdateInputSchema, type FeedbackAffectedScope, type FeedbackCreateInput, type FeedbackErrorCode, type FeedbackItem, type FeedbackMessage, type FeedbackMessageCreateInput, type FeedbackStatus, type FeedbackStatusEvent, type FeedbackSummary, type FeedbackType, type FeedbackUrgency, type FeedbackUpdateInput, };

package/dist/feedback/contract.js

@@ -0,0 +1,32 @@
+import { zBodyCreateFeedbackV1ProjectsProjectIdEnvironmentsEnvironmentFeedbackPost, zCreateFeedbackV1ProjectsProjectIdEnvironmentsEnvironmentFeedbackPostHeaders, zFeedbackCreateRequest, zFeedbackAttachment, zFeedbackErrorResponse, zFeedbackItem, zFeedbackListResponse, zFeedbackMessage, zFeedbackMessageCreateRequest, zFeedbackStatusEvent, zFeedbackSummary, zFeedbackUpdateRequest, } from "./generated/zod.gen.js";
+const feedbackCreateHeadersSchema = zCreateFeedbackV1ProjectsProjectIdEnvironmentsEnvironmentFeedbackPostHeaders;
+const feedbackAttachmentSchema = zFeedbackAttachment;
+const feedbackCreateInputSchema = zFeedbackCreateRequest;
+const feedbackErrorResponseSchema = zFeedbackErrorResponse;
+const feedbackItemSchema = zFeedbackItem;
+const feedbackListResponseSchema = zFeedbackListResponse;
+const feedbackMessageCreateInputSchema = zFeedbackMessageCreateRequest;
+const feedbackMessageSchema = zFeedbackMessage;
+const feedbackStatusEventSchema = zFeedbackStatusEvent;
+const feedbackStatusSchema = zFeedbackSummary.shape.status;
+const feedbackSummarySchema = zFeedbackSummary;
+const feedbackTypeSchema = zFeedbackCreateRequest.shape.type;
+const feedbackUpdateInputSchema = zFeedbackUpdateRequest;
+const feedbackMaxLengths = {
+    description: requireMaximum(zFeedbackCreateRequest.shape.description.maxLength, "description"),
+    subject: requireMaximum(zFeedbackCreateRequest.shape.subject.maxLength, "subject"),
+};
+const feedbackFilesMaximum = zBodyCreateFeedbackV1ProjectsProjectIdEnvironmentsEnvironmentFeedbackPost.shape.files
+    .unwrap()
+    .unwrap()._zod.bag.maximum;
+/** How many files one create request takes, and the most bytes each may hold. */
+const feedbackAttachmentLimits = {
+    count: requireMaximum(typeof feedbackFilesMaximum === "number" ? feedbackFilesMaximum : null, "files"),
+    bytes: requireMaximum(zFeedbackAttachment.shape.size.maxValue, "attachment size"),
+};
+function requireMaximum(value, field) {
+    if (value === null)
+        throw new Error(`Feedback contract is missing the ${field} maximum.`);
+    return value;
+}
+export { feedbackAttachmentLimits, feedbackAttachmentSchema, feedbackCreateHeadersSchema, feedbackCreateInputSchema, feedbackErrorResponseSchema, feedbackItemSchema, feedbackListResponseSchema, feedbackMessageCreateInputSchema, feedbackMessageSchema, feedbackMaxLengths, feedbackStatusEventSchema, feedbackStatusSchema, feedbackSummarySchema, feedbackTypeSchema, feedbackUpdateInputSchema, };

package/dist/feedback/feedback-cache.d.ts

@@ -0,0 +1,6 @@
+import type { FeedbackItem, FeedbackMessage } from "./contract.js";
+import type { QueryClient } from "@tanstack/react-query";
+declare function cacheCreatedFeedbackItem(queryClient: QueryClient, queryRoot: readonly string[], item: FeedbackItem): Promise<void>;
+declare function refreshFeedbackItem(queryClient: QueryClient, queryRoot: readonly string[], item: FeedbackItem): Promise<void>;
+declare function appendFeedbackMessage(queryClient: QueryClient, queryRoot: readonly string[], feedbackId: string, message: FeedbackMessage): Promise<void>;
+export { appendFeedbackMessage, cacheCreatedFeedbackItem, refreshFeedbackItem };

package/dist/feedback/feedback-cache.js

@@ -0,0 +1,58 @@
+async function cacheCreatedFeedbackItem(queryClient, queryRoot, item) {
+    const itemsKey = [...queryRoot, "items"];
+    await queryClient.cancelQueries({ queryKey: itemsKey, exact: true });
+    queryClient.setQueryData(itemsKey, (summaries = []) => [
+        item,
+        ...summaries.filter((summary) => summary.id !== item.id),
+    ]);
+    return queryClient.invalidateQueries({ queryKey: itemsKey, exact: true });
+}
+async function refreshFeedbackItem(queryClient, queryRoot, item) {
+    const itemKey = [...queryRoot, "item", item.id];
+    const itemsKey = [...queryRoot, "items"];
+    await Promise.all([
+        queryClient.cancelQueries({ queryKey: itemKey, exact: true }),
+        queryClient.cancelQueries({ queryKey: itemsKey, exact: true }),
+    ]);
+    queryClient.setQueryData(itemKey, (cached) => cached
+        ? {
+            ...item,
+            messages: mergeFeedbackMessages(item.messages, cached.messages),
+        }
+        : item);
+    queryClient.setQueryData(itemsKey, (summaries) => summaries?.map((summary) => (summary.id === item.id ? item : summary)));
+    return queryClient.invalidateQueries({ queryKey: itemsKey, exact: true });
+}
+async function appendFeedbackMessage(queryClient, queryRoot, feedbackId, message) {
+    const itemKey = [...queryRoot, "item", feedbackId];
+    await queryClient.cancelQueries({ queryKey: itemKey, exact: true });
+    let updated = false;
+    queryClient.setQueryData(itemKey, (item) => {
+        if (!item)
+            return item;
+        updated = true;
+        if (item.messages.some((existing) => existing.id === message.id))
+            return item;
+        return {
+            ...item,
+            messages: [...item.messages, message],
+            updatedAt: message.createdAt,
+            updatedAt_epoch_milliseconds: message.createdAt_epoch_milliseconds,
+        };
+    });
+    const invalidations = [
+        queryClient.invalidateQueries({ queryKey: [...queryRoot, "items"], exact: true }),
+    ];
+    if (!updated) {
+        invalidations.push(queryClient.invalidateQueries({ queryKey: itemKey, exact: true }));
+    }
+    await Promise.all(invalidations);
+}
+function mergeFeedbackMessages(serverMessages, cachedMessages) {
+    const serverMessageIds = new Set(serverMessages.map((message) => message.id));
+    return [
+        ...serverMessages,
+        ...cachedMessages.filter((message) => !serverMessageIds.has(message.id)),
+    ];
+}
+export { appendFeedbackMessage, cacheCreatedFeedbackItem, refreshFeedbackItem };

package/dist/feedback/feedback-center-model.d.ts

@@ -0,0 +1,8 @@
+import type { CommentItemData } from "./comment-types.js";
+import type { FeedbackItem, FeedbackMessage, FeedbackSummary } from "./contract.js";
+import type { UserFeedbackItem } from "./feedback-tracking-types.js";
+declare function toPresentationItem(item: FeedbackSummary): UserFeedbackItem;
+declare function toCommentsByFeedbackId(feedbackId: string | undefined, messages: FeedbackMessage[]): Record<string, CommentItemData[]>;
+declare function canReply(feedbackId: string, summaries: FeedbackSummary[], detail: FeedbackItem | undefined): boolean;
+declare function requireSelectedId(selectedId: string | undefined): string;
+export { canReply, requireSelectedId, toCommentsByFeedbackId, toPresentationItem };

package/dist/feedback/feedback-center-model.js

@@ -0,0 +1,37 @@
+function toPresentationItem(item) {
+    return {
+        affectedScope: item.affectedScope,
+        description: item.description,
+        id: item.id,
+        status: item.status,
+        subject: item.subject,
+        submittedAt: item.createdAt,
+        type: item.type,
+        updatedAt: item.updatedAt,
+        urgency: item.urgency,
+    };
+}
+function toCommentsByFeedbackId(feedbackId, messages) {
+    if (!feedbackId)
+        return {};
+    return {
+        [feedbackId]: messages.map((message) => ({
+            author: { id: message.author.role, name: message.author.name },
+            body: message.body,
+            createdAt: message.createdAt,
+            id: message.id,
+            updatedAt: message.editedAt ?? undefined,
+        })),
+    };
+}
+function canReply(feedbackId, summaries, detail) {
+    if (detail?.id === feedbackId)
+        return detail.canReply;
+    return summaries.find((item) => item.id === feedbackId)?.canReply ?? false;
+}
+function requireSelectedId(selectedId) {
+    if (!selectedId)
+        throw new Error("Feedback selection is required.");
+    return selectedId;
+}
+export { canReply, requireSelectedId, toCommentsByFeedbackId, toPresentationItem };

package/dist/feedback/feedback-composer-types.d.ts

@@ -0,0 +1,11 @@
+import type { FeedbackAffectedScope, FeedbackType, FeedbackUrgency } from "./contract.js";
+/** What a feedback composer submits: the create request's fields plus the files to attach. */
+type FeedbackSubmitValues = {
+    affectedScope: FeedbackAffectedScope;
+    attachments: File[];
+    description: string;
+    subject: string;
+    type: FeedbackType;
+    urgency: FeedbackUrgency;
+};
+export type { FeedbackSubmitValues };

package/dist/feedback/feedback-controller.d.ts

@@ -0,0 +1,56 @@
+import { type FeedbackClientConfig } from "./client.js";
+import type { CommentItemData } from "./comment-types.js";
+import type { FeedbackItem, FeedbackSummary, FeedbackUpdateInput } from "./contract.js";
+import type { FeedbackSubmitValues } from "./feedback-composer-types.js";
+type FeedbackControllerConfig = FeedbackClientConfig & {
+    cacheScope: string;
+};
+type FeedbackControllerOptions = {
+    active: boolean;
+    config: FeedbackControllerConfig;
+    onFeedbackCreated?: (item: FeedbackItem) => void;
+};
+declare function useFeedbackController({ active, config, onFeedbackCreated }: FeedbackControllerOptions): {
+    createMutation: import("@tanstack/react-query/build/legacy").UseMutationResult<FeedbackItem, Error, {
+        queryRoot: readonly string[];
+        values: FeedbackSubmitValues;
+    }, unknown>;
+    messageMutation: import("@tanstack/react-query/build/legacy").UseMutationResult<import("./contract.js").FeedbackMessage, Error, {
+        body: string;
+        feedbackId: string;
+        queryRoot: readonly string[];
+    }, void>;
+    messageStates: Record<string, FeedbackMessageMutationState>;
+    updateMutation: import("@tanstack/react-query/build/legacy").UseMutationResult<FeedbackItem, Error, {
+        feedbackId: string;
+        input: FeedbackUpdateInput;
+        queryRoot: readonly string[];
+    }, unknown>;
+    withdrawMutation: import("@tanstack/react-query/build/legacy").UseMutationResult<FeedbackItem, Error, {
+        feedbackId: string;
+        queryRoot: readonly string[];
+    }, unknown>;
+    uploadStatus: string | undefined;
+    getAttachmentUrl: (feedbackId: string, attachmentId: string) => Promise<string>;
+    comments: Record<string, CommentItemData[]>;
+    createFeedback: (values: FeedbackSubmitValues) => Promise<FeedbackItem>;
+    createMessage: (feedbackId: string, body: string) => Promise<import("./contract.js").FeedbackMessage>;
+    detailQuery: import("@tanstack/react-query/build/legacy").UseQueryResult<NoInfer<FeedbackItem>, Error>;
+    items: import("./feedback-tracking-types.js").UserFeedbackItem[];
+    itemsQuery: import("@tanstack/react-query/build/legacy").UseQueryResult<NoInfer<FeedbackSummary[]>, Error>;
+    isMessageSubmitting: boolean;
+    messageError: Error | null;
+    selectedDetail: NoInfer<FeedbackItem> | undefined;
+    selectedId: string | undefined;
+    selectedSummary: FeedbackSummary | undefined;
+    selectionScope: string;
+    setSelectedId: (feedbackId: string | undefined) => void;
+    summaries: FeedbackSummary[];
+    updateFeedback: (feedbackId: string, input: FeedbackUpdateInput) => Promise<FeedbackItem>;
+    withdrawFeedback: (feedbackId: string) => Promise<FeedbackItem>;
+};
+type FeedbackMessageMutationState = {
+    error?: Error;
+    isPending: boolean;
+};
+export { type FeedbackControllerConfig, useFeedbackController };

package/dist/feedback/feedback-controller.js

@@ -0,0 +1,181 @@
+import { useMutation, useQuery, useQueryClient } from "@tanstack/react-query";
+import * as React from "react";
+import { createFeedbackClient } from "./client.js";
+import { appendFeedbackMessage, cacheCreatedFeedbackItem, refreshFeedbackItem, } from "./feedback-cache.js";
+import { canReply, requireSelectedId, toCommentsByFeedbackId, toPresentationItem, } from "./feedback-center-model.js";
+import { requireConfig } from "./require-config.js";
+import { submitFeedbackWithAttachments } from "./submit-feedback-with-attachments.js";
+function useFeedbackController({ active, config, onFeedbackCreated }) {
+    const client = useFeedbackClient(config);
+    const normalizedCacheScope = requireConfig(config.cacheScope, "cacheScope");
+    const queryClient = useQueryClient();
+    const queryRoot = React.useMemo(() => ["feedback", client.baseUrl, normalizedCacheScope], [client.baseUrl, normalizedCacheScope]);
+    const selectionScope = JSON.stringify([client.baseUrl, normalizedCacheScope]);
+    const [selection, setSelection] = React.useState({ scope: selectionScope });
+    React.useEffect(() => {
+        setSelection((current) => current.scope === selectionScope ? current : { scope: selectionScope });
+    }, [selectionScope]);
+    const selectedId = selection.scope === selectionScope ? selection.feedbackId : undefined;
+    const { detailQuery, itemsQuery } = useFeedbackQueries(client, queryRoot, active, selectedId);
+    const mutations = useFeedbackMutations({ client, onFeedbackCreated, queryClient });
+    const summaries = itemsQuery.data ?? [];
+    const selectedSummary = summaries.find((item) => item.id === selectedId);
+    const selectedDetail = detailQuery.data?.id === selectedId ? detailQuery.data : undefined;
+    const comments = selectedDetail
+        ? toCommentsByFeedbackId(selectedDetail.id, selectedDetail.messages)
+        : {};
+    const createFeedback = (values) => mutations.createMutation.mutateAsync({ queryRoot, values });
+    const createMessage = (feedbackId, body) => mutations.messageMutation.mutateAsync({ body, feedbackId, queryRoot });
+    const messageState = getMessageState(mutations.messageStates, queryRoot, selectedId);
+    const isMessageSubmitting = messageState?.isPending ?? false;
+    const messageError = getMessageError(messageState, selectedId, summaries, detailQuery.data);
+    const updateFeedback = (feedbackId, input) => mutations.updateMutation.mutateAsync({ feedbackId, input, queryRoot });
+    const withdrawFeedback = (feedbackId) => mutations.withdrawMutation.mutateAsync({ feedbackId, queryRoot });
+    const setSelectedId = (feedbackId) => setSelection({ feedbackId, scope: selectionScope });
+    return {
+        getAttachmentUrl: (feedbackId, attachmentId) => client.getAttachmentUrl(feedbackId, attachmentId),
+        comments,
+        createFeedback,
+        createMessage,
+        detailQuery,
+        items: summaries.map(toPresentationItem),
+        itemsQuery,
+        isMessageSubmitting,
+        messageError,
+        selectedDetail,
+        selectedId,
+        selectedSummary,
+        selectionScope,
+        setSelectedId,
+        summaries,
+        updateFeedback,
+        withdrawFeedback,
+        ...mutations,
+    };
+}
+function useFeedbackClient({ baseUrl, getBearerToken }) {
+    return React.useMemo(() => createFeedbackClient({ baseUrl, getBearerToken }), [baseUrl, getBearerToken]);
+}
+function useFeedbackQueries(client, queryRoot, active, selectedId) {
+    const itemsQuery = useQuery({
+        queryKey: [...queryRoot, "items"],
+        queryFn: ({ signal }) => client.list({ signal }),
+        enabled: active,
+        retry: false,
+    });
+    const detailQuery = useQuery({
+        queryKey: [...queryRoot, "item", selectedId],
+        queryFn: ({ signal }) => client.get(requireSelectedId(selectedId), { signal }),
+        enabled: active && selectedId !== undefined,
+        retry: false,
+    });
+    return { detailQuery, itemsQuery };
+}
+function useFeedbackMutations({ client, onFeedbackCreated, queryClient, }) {
+    const [uploadStatus, setUploadStatus] = React.useState();
+    const pendingCreate = React.useRef(undefined);
+    const { messageMutation, messageStates } = useFeedbackMessageMutation(client, queryClient);
+    const createMutation = useMutation({
+        mutationFn: ({ queryRoot, values, }) => {
+            const input = {
+                affectedScope: values.affectedScope,
+                description: values.description,
+                subject: values.subject,
+                type: values.type,
+                urgency: values.urgency,
+            };
+            const fingerprint = JSON.stringify([queryRoot, input]);
+            const idempotencyKey = pendingCreate.current?.fingerprint === fingerprint
+                ? pendingCreate.current.idempotencyKey
+                : crypto.randomUUID();
+            pendingCreate.current = { fingerprint, idempotencyKey };
+            return submitFeedbackWithAttachments({
+                client,
+                input,
+                idempotencyKey,
+                files: values.attachments,
+                onStatus: setUploadStatus,
+            });
+        },
+        onSuccess: (item, { queryRoot }) => {
+            pendingCreate.current = undefined;
+            void cacheCreatedFeedbackItem(queryClient, queryRoot, item).catch(() => undefined);
+            notifyFeedbackCreated(onFeedbackCreated, item);
+        },
+    });
+    const updateMutation = useMutation({
+        mutationFn: ({ feedbackId, input, }) => client.update(feedbackId, input),
+        onSuccess: (item, input) => {
+            void refreshFeedbackItem(queryClient, input.queryRoot, item).catch(() => undefined);
+        },
+    });
+    const withdrawMutation = useMutation({
+        mutationFn: ({ feedbackId }) => client.withdraw(feedbackId),
+        onSuccess: (item, input) => {
+            void refreshFeedbackItem(queryClient, input.queryRoot, item).catch(() => undefined);
+        },
+    });
+    return {
+        createMutation,
+        messageMutation,
+        messageStates,
+        updateMutation,
+        withdrawMutation,
+        uploadStatus,
+    };
+}
+function useFeedbackMessageMutation(client, queryClient) {
+    const [messageStates, setMessageStates] = React.useState({});
+    const messageMutation = useMutation({
+        mutationFn: ({ body, feedbackId, }) => client.createMessage(feedbackId, body),
+        onMutate: (input) => {
+            setMessageStates((current) => ({
+                ...current,
+                [messageErrorKey(input.queryRoot, input.feedbackId)]: { isPending: true },
+            }));
+        },
+        onError: (error, input) => {
+            setMessageStates((current) => ({
+                ...current,
+                [messageErrorKey(input.queryRoot, input.feedbackId)]: {
+                    error,
+                    isPending: false,
+                },
+            }));
+        },
+        onSuccess: (message, input) => {
+            setMessageStates((current) => {
+                const key = messageErrorKey(input.queryRoot, input.feedbackId);
+                if (current[key] === undefined)
+                    return current;
+                const next = { ...current };
+                delete next[key];
+                return next;
+            });
+            void appendFeedbackMessage(queryClient, input.queryRoot, input.feedbackId, message).catch(() => undefined);
+        },
+    });
+    return { messageMutation, messageStates };
+}
+function messageErrorKey(queryRoot, feedbackId) {
+    return JSON.stringify([...queryRoot, "message", feedbackId]);
+}
+function getMessageState(messageStates, queryRoot, selectedId) {
+    return selectedId === undefined
+        ? undefined
+        : messageStates[messageErrorKey(queryRoot, selectedId)];
+}
+function getMessageError(messageState, selectedId, summaries, detail) {
+    return selectedId !== undefined && canReply(selectedId, summaries, detail)
+        ? (messageState?.error ?? null)
+        : null;
+}
+function notifyFeedbackCreated(onFeedbackCreated, item) {
+    try {
+        void Promise.resolve(onFeedbackCreated?.(item)).catch(() => undefined);
+    }
+    catch {
+        // A consumer observer cannot turn a durable create into a failed retry.
+    }
+}
+export { useFeedbackController };

package/dist/feedback/feedback-tracking-types.d.ts

@@ -0,0 +1,14 @@
+import type { FeedbackAffectedScope, FeedbackStatus, FeedbackType, FeedbackUrgency } from "./contract.js";
+/** A submitted feedback item in the shape a reporter's tracking list renders. */
+type UserFeedbackItem = {
+    affectedScope?: FeedbackAffectedScope;
+    description: string;
+    id: string;
+    status: FeedbackStatus;
+    subject: string;
+    submittedAt: string;
+    type: FeedbackType;
+    updatedAt?: string;
+    urgency?: FeedbackUrgency;
+};
+export type { UserFeedbackItem };