@ciridae/ui 0.16.1 → 1.0.1

package/README.md

@@ -1,6 +1,6 @@
 # @ciridae/ui
 
-Ciridae UI package output from https://ciridae-ui.ciridae.app.
+Ciridae React components and Panda preset.
 
 Install from npm:
 
@@ -10,18 +10,23 @@ npm install @ciridae/ui
 
 Use the published package for new and updated consumers.
 
-Theme overrides should target the standard semantic variables after importing the package CSS:
+Panda generates the component styles in your app. Add the preset, scan the package output, and
+recognise its `css` import alias:
 
-```css
-@import "@ciridae/ui/styles.css";
+```ts
+// panda.config.ts
+import { ciridaePreset } from "@ciridae/ui/preset";
+import { defineConfig } from "@pandacss/dev";
 
-:root {
-	--primary: oklch(0.42 0.08 245);
-	--primary-foreground: oklch(0.99 0 0);
-}
+export default defineConfig({
+	presets: ["@pandacss/preset-panda", ciridaePreset],
+	importMap: { css: ["#primitives/css", "styled-system/css"] },
+	include: ["./src/**/*.{ts,tsx}", "./node_modules/@ciridae/ui/dist/**/*.js"],
+});
+```
+
+Import the base stylesheet once at the application root:
 
-.dark {
-	--primary: oklch(0.78 0.07 245);
-	--primary-foreground: oklch(0.12 0.002 260);
-}
+```ts
+import "@ciridae/ui/styles.css";
 ```

package/dist/chat/chat-api-error.d.ts

@@ -0,0 +1,14 @@
+/** A chat API request that the service answered with a non-2xx status. */
+export declare class ChatApiError extends Error {
+    readonly method: string;
+    readonly path: string;
+    readonly status: number;
+    /** The response body as text, for diagnostics; never shown to the user verbatim. */
+    readonly responseBody: string;
+    constructor({ method, path, status, responseBody, }: {
+        method: string;
+        path: string;
+        status: number;
+        responseBody: string;
+    });
+}

package/dist/chat/chat-api-error.js

@@ -0,0 +1,11 @@
+/** A chat API request that the service answered with a non-2xx status. */
+export class ChatApiError extends Error {
+    constructor({ method, path, status, responseBody, }) {
+        super(`${method} ${path} failed with status ${status}`);
+        this.name = "ChatApiError";
+        this.method = method;
+        this.path = path;
+        this.status = status;
+        this.responseBody = responseBody;
+    }
+}

package/dist/chat/chat-client.d.ts

@@ -0,0 +1,37 @@
+import { ChatApiError } from "./chat-api-error.js";
+import { type AnswerQuestionRequest, type Approval, type ApprovalDecision, type ApprovalId, type Attachment, type Conversation, type ConversationId, type ConversationPage, type CreateConversationRequest, type CreatedItem, type CreateItemRequest, type ItemPage, type QuestionId, type Response, type ResponseId } from "./contract.js";
+export { ChatApiError };
+/** Everything the chat sheet needs from the chat service; `createMockChatClient` implements it too. */
+export type ChatClient = {
+    /** Separates this client's cached data from any other client's in a shared query cache. */
+    cacheKey: string;
+    createConversation(request?: CreateConversationRequest): Promise<Conversation>;
+    listConversations(options?: {
+        cursor?: string;
+    }): Promise<ConversationPage>;
+    getConversation(conversationId: ConversationId): Promise<Conversation>;
+    deleteConversation(conversationId: ConversationId): Promise<void>;
+    /** Uploads a file for a later message to reference by `attachment_ids`. */
+    uploadAttachment(file: File): Promise<Attachment>;
+    /** Where the browser loads an attachment's bytes from, or null when the service keeps no copy. */
+    getAttachmentUrl(attachment: Attachment): string | null;
+    /** Starts a response, or joins the running one, and returns that response's id. */
+    createItem(conversationId: ConversationId, request: CreateItemRequest): Promise<CreatedItem>;
+    /** Items with a `seq` greater than `after`, oldest first. */
+    listItems(conversationId: ConversationId, options?: {
+        after?: number;
+    }): Promise<ItemPage>;
+    getResponse(responseId: ResponseId): Promise<Response>;
+    cancelResponse(responseId: ResponseId): Promise<Response>;
+    decideApproval(responseId: ResponseId, approvalId: ApprovalId, decision: ApprovalDecision): Promise<Approval>;
+    /** Answers a waiting question with one list of picked labels or typed text per question. */
+    answerQuestion(conversationId: ConversationId, questionId: QuestionId, answers: AnswerQuestionRequest["answers"]): Promise<void>;
+};
+export type ChatClientSettings = {
+    /** Where the chat API is served, such as the app backend's proxy (`/api/chat`). */
+    baseUrl: string;
+    fetch?: typeof globalThis.fetch;
+    /** Sent with every request; a function is called per request, for short-lived tokens. */
+    headers?: HeadersInit | (() => HeadersInit | Promise<HeadersInit>);
+};
+export declare function createChatClient({ baseUrl, fetch: fetchImplementation, headers, }: ChatClientSettings): ChatClient;

package/dist/chat/chat-client.js

@@ -0,0 +1,66 @@
+import { ChatApiError } from "./chat-api-error.js";
+import { ApprovalSchema, AttachmentSchema, ConversationPageSchema, ConversationSchema, CreatedItemSchema, ItemPageSchema, ResponseSchema, } from "./contract.js";
+export { ChatApiError };
+export function createChatClient({ baseUrl, fetch: fetchImplementation = globalThis.fetch.bind(globalThis), headers, }) {
+    const apiRoot = baseUrl.endsWith("/") ? baseUrl.slice(0, -1) : baseUrl;
+    async function requestJson(method, path, responseSchema, body) {
+        const response = await send(method, path, body);
+        return responseSchema.parse(await response.json());
+    }
+    async function requestWithoutResponseBody(method, path, body) {
+        await send(method, path, body);
+    }
+    async function send(method, path, body) {
+        const requestHeaders = new Headers(typeof headers === "function" ? await headers() : headers);
+        requestHeaders.set("Accept", "application/json");
+        // A multipart body sets its own Content-Type, boundary included.
+        const isFormData = body instanceof FormData;
+        if (body !== undefined && !isFormData)
+            requestHeaders.set("Content-Type", "application/json");
+        const response = await fetchImplementation(`${apiRoot}${path}`, {
+            method,
+            headers: requestHeaders,
+            body: body === undefined ? undefined : isFormData ? body : JSON.stringify(body),
+        });
+        if (!response.ok) {
+            throw new ChatApiError({
+                method,
+                path,
+                status: response.status,
+                responseBody: await response.text(),
+            });
+        }
+        return response;
+    }
+    return {
+        cacheKey: apiRoot,
+        createConversation: (request = {}) => requestJson("POST", "/v1/conversations", ConversationSchema, request),
+        listConversations: ({ cursor } = {}) => requestJson("GET", `/v1/conversations${buildQuery({ cursor })}`, ConversationPageSchema),
+        getConversation: (conversationId) => requestJson("GET", `/v1/conversations/${encodeURIComponent(conversationId)}`, ConversationSchema),
+        deleteConversation: (conversationId) => requestWithoutResponseBody("DELETE", `/v1/conversations/${encodeURIComponent(conversationId)}`),
+        uploadAttachment: (file) => {
+            const form = new FormData();
+            form.append("file", file);
+            return requestJson("POST", "/v1/attachments", AttachmentSchema, form);
+        },
+        // The service serves attachment bytes under the API base, so a relative path joins it.
+        getAttachmentUrl: ({ url }) => url === null || /^[a-z][a-z\d+.-]*:/i.test(url) ? url : `${apiRoot}${url}`,
+        createItem: (conversationId, request) => requestJson("POST", `/v1/conversations/${encodeURIComponent(conversationId)}/items`, CreatedItemSchema, request),
+        listItems: (conversationId, { after } = {}) => requestJson("GET", `/v1/conversations/${encodeURIComponent(conversationId)}/items${buildQuery({
+            after: after === undefined ? undefined : String(after),
+        })}`, ItemPageSchema),
+        getResponse: (responseId) => requestJson("GET", `/v1/responses/${encodeURIComponent(responseId)}`, ResponseSchema),
+        cancelResponse: (responseId) => requestJson("POST", `/v1/responses/${encodeURIComponent(responseId)}/cancel`, ResponseSchema),
+        decideApproval: (responseId, approvalId, decision) => requestJson("POST", `/v1/responses/${encodeURIComponent(responseId)}/approvals/${encodeURIComponent(approvalId)}`, ApprovalSchema, { decision }),
+        answerQuestion: (conversationId, questionId, answers) => requestWithoutResponseBody("POST", `/v1/conversations/${encodeURIComponent(conversationId)}/questions/${encodeURIComponent(questionId)}/answer`, { answers }),
+    };
+}
+function buildQuery(parameters) {
+    const search = new URLSearchParams();
+    for (const [name, value] of Object.entries(parameters)) {
+        if (value !== undefined)
+            search.set(name, value);
+    }
+    const query = search.toString();
+    return query ? `?${query}` : "";
+}

package/dist/chat/chat-hooks.d.ts

@@ -0,0 +1,4 @@
+export { chatQueryKeys } from "./chat-query-keys.js";
+export { conversationItemsQueryOptions } from "./conversation-items-query-options.js";
+export { useChatConversation, type ChatConversationState, type PendingMessage, } from "./use-chat-conversation.js";
+export { useConversationList } from "./use-conversation-list.js";

package/dist/chat/chat-hooks.js

@@ -0,0 +1,4 @@
+export { chatQueryKeys } from "./chat-query-keys.js";
+export { conversationItemsQueryOptions } from "./conversation-items-query-options.js";
+export { useChatConversation, } from "./use-chat-conversation.js";
+export { useConversationList } from "./use-conversation-list.js";

package/dist/chat/chat-query-keys.d.ts

@@ -0,0 +1,10 @@
+import type { ChatClient } from "./chat-client.js";
+import type { ConversationId, ResponseId } from "./contract.js";
+/** Query keys for chat data, scoped by client so two clients never share cached data. */
+export declare const chatQueryKeys: {
+    all: (client: ChatClient) => readonly ["ciridae-chat", string];
+    conversationList: (client: ChatClient) => readonly ["ciridae-chat", string, "conversation-list"];
+    conversation: (client: ChatClient, conversationId: ConversationId | null) => readonly ["ciridae-chat", string, "conversation", (string & import("zod/index.cjs").$brand<"ConversationId">) | null];
+    conversationItems: (client: ChatClient, conversationId: ConversationId | null) => readonly ["ciridae-chat", string, "conversation-items", (string & import("zod/index.cjs").$brand<"ConversationId">) | null];
+    response: (client: ChatClient, responseId: ResponseId | null) => readonly ["ciridae-chat", string, "response", (string & import("zod/index.cjs").$brand<"ResponseId">) | null];
+};

package/dist/chat/chat-query-keys.js

@@ -0,0 +1,8 @@
+/** Query keys for chat data, scoped by client so two clients never share cached data. */
+export const chatQueryKeys = {
+    all: (client) => ["ciridae-chat", client.cacheKey],
+    conversationList: (client) => [...chatQueryKeys.all(client), "conversation-list"],
+    conversation: (client, conversationId) => [...chatQueryKeys.all(client), "conversation", conversationId],
+    conversationItems: (client, conversationId) => [...chatQueryKeys.all(client), "conversation-items", conversationId],
+    response: (client, responseId) => [...chatQueryKeys.all(client), "response", responseId],
+};