@cosmicdrift/kumiko-renderer 0.328.0 → 0.328.1

package/src/hooks/__tests__/use-query.test.tsx

@@ -1,149 +0,0 @@
-import { afterEach, beforeEach, describe, expect, jest, test } from "bun:test";
-import type { Dispatcher } from "@cosmicdrift/kumiko-headless";
-import { act, renderHook } from "@testing-library/react";
-import type { ReactNode } from "react";
-import { DispatcherProvider } from "../../context/dispatcher-context";
-import { useQuery } from "../use-query";
-
-type QueryFn = Dispatcher["query"];
-
-function makeDispatcher(query: QueryFn): Dispatcher {
-  return {
-    write: (async () => ({ isSuccess: true, data: {} })) as unknown as Dispatcher["write"],
-    query,
-    batch: (async () => ({ isSuccess: true, results: [] })) as unknown as Dispatcher["batch"],
-    statusStore: {
-      getState: () => "online",
-      subscribe: () => () => {},
-    } as unknown as Dispatcher["statusStore"],
-    async *stream() {},
-    pendingWrites: () => [],
-    pendingFiles: () => [],
-  };
-}
-
-function wrapperFor(dispatcher: Dispatcher) {
-  return ({ children }: { readonly children: ReactNode }) => (
-    <DispatcherProvider dispatcher={dispatcher}>{children}</DispatcherProvider>
-  );
-}
-
-function countingDispatcher(): { dispatcher: Dispatcher; calls: () => number } {
-  let calls = 0;
-  const query = (async () => {
-    calls += 1;
-    return { isSuccess: true, data: { n: calls } };
-  }) as unknown as QueryFn;
-  return { dispatcher: makeDispatcher(query), calls: () => calls };
-}
-
-async function advance(ms: number): Promise<void> {
-  await act(async () => {
-    jest.advanceTimersByTime(ms);
-  });
-}
-
-const QUERY_TYPE = "f:query:x:list";
-
-describe("useQuery refetchIntervalMs", () => {
-  beforeEach(() => {
-    jest.useFakeTimers();
-  });
-  afterEach(() => {
-    jest.useRealTimers();
-  });
-
-  test("re-runs the query on every interval tick", async () => {
-    const { dispatcher, calls } = countingDispatcher();
-    const { result } = renderHook(
-      () => useQuery<{ n: number }>(QUERY_TYPE, {}, { refetchIntervalMs: 1000 }),
-      {
-        wrapper: wrapperFor(dispatcher),
-      },
-    );
-    await advance(0);
-    expect(calls()).toBe(1);
-
-    await advance(1000);
-    expect(calls()).toBe(2);
-    await advance(1000);
-    expect(calls()).toBe(3);
-    expect(result.current.data).toEqual({ n: 3 });
-  });
-
-  test("unmount stops the ticks", async () => {
-    const { dispatcher, calls } = countingDispatcher();
-    const { unmount } = renderHook(() => useQuery(QUERY_TYPE, {}, { refetchIntervalMs: 1000 }), {
-      wrapper: wrapperFor(dispatcher),
-    });
-    await advance(1000);
-    const before = calls();
-    unmount();
-    await advance(5000);
-    expect(calls()).toBe(before);
-  });
-
-  test("enabled: false never ticks", async () => {
-    const { dispatcher, calls } = countingDispatcher();
-    renderHook(() => useQuery(QUERY_TYPE, {}, { enabled: false, refetchIntervalMs: 1000 }), {
-      wrapper: wrapperFor(dispatcher),
-    });
-    await advance(5000);
-    expect(calls()).toBe(0);
-  });
-
-  test("a tick while a fetch is in flight is skipped instead of aborting it", async () => {
-    let calls = 0;
-    let release: (() => void) | undefined;
-    const query = (async (_type: string, _payload: unknown, opts?: { signal?: AbortSignal }) => {
-      calls += 1;
-      await new Promise<void>((resolve) => {
-        release = resolve;
-      });
-      return opts?.signal?.aborted
-        ? { isSuccess: false, error: { code: "aborted", message: "aborted", i18nKey: "x" } }
-        : { isSuccess: true, data: { done: true } };
-    }) as unknown as QueryFn;
-    const { result } = renderHook(
-      () => useQuery<{ done: boolean }>(QUERY_TYPE, {}, { refetchIntervalMs: 1000 }),
-      {
-        wrapper: wrapperFor(makeDispatcher(query)),
-      },
-    );
-    await advance(0);
-    expect(calls).toBe(1);
-
-    await advance(3000);
-    expect(calls).toBe(1);
-
-    await act(async () => {
-      release?.();
-    });
-    expect(result.current.data).toEqual({ done: true });
-
-    await advance(1000);
-    expect(calls).toBe(2);
-  });
-
-  test("background ticks do not flip loading to true", async () => {
-    const { dispatcher, calls } = countingDispatcher();
-    const seenLoading: boolean[] = [];
-    const { result } = renderHook(
-      () => {
-        const r = useQuery<{ n: number }>(QUERY_TYPE, {}, { refetchIntervalMs: 1000 });
-        seenLoading.push(r.loading);
-        return r;
-      },
-      { wrapper: wrapperFor(dispatcher) },
-    );
-    await advance(0);
-    expect(result.current.loading).toBe(false);
-    seenLoading.length = 0;
-
-    await advance(1000);
-    await advance(1000);
-    expect(calls()).toBe(3);
-    expect(result.current.data).toEqual({ n: 3 });
-    expect(seenLoading.every((l) => l === false)).toBe(true);
-  });
-});

package/src/hooks/__tests__/use-stream-handler.test.tsx

@@ -1,107 +0,0 @@
-import { describe, expect, test } from "bun:test";
-import type { Dispatcher, DispatcherError } from "@cosmicdrift/kumiko-headless";
-import { act, renderHook, waitFor } from "@testing-library/react";
-import type { ReactNode } from "react";
-import { DispatcherProvider } from "../../context/dispatcher-context";
-import { useStreamHandler } from "../use-stream-handler";
-
-function makeDispatcher(streamImpl: unknown): Dispatcher {
-  return {
-    write: (async () => ({ isSuccess: true, data: {} })) as unknown as Dispatcher["write"],
-    query: (async () => ({ isSuccess: true, data: {} })) as unknown as Dispatcher["query"],
-    batch: (async () => ({ isSuccess: true, results: [] })) as unknown as Dispatcher["batch"],
-    stream: streamImpl as Dispatcher["stream"],
-    statusStore: {
-      getState: () => "online",
-      subscribe: () => () => {},
-    } as unknown as Dispatcher["statusStore"],
-    pendingWrites: () => [],
-    pendingFiles: () => [],
-  };
-}
-
-function wrapperFor(dispatcher: Dispatcher) {
-  return ({ children }: { readonly children: ReactNode }) => (
-    <DispatcherProvider dispatcher={dispatcher}>{children}</DispatcherProvider>
-  );
-}
-
-describe("useStreamHandler", () => {
-  test("start accumulates chunks then status=done", async () => {
-    const dispatcher = makeDispatcher(async function* () {
-      yield { i: 0 };
-      yield { i: 1 };
-    });
-
-    const { result } = renderHook(() => useStreamHandler<{ i: number }>("f:stream:x:tail"), {
-      wrapper: wrapperFor(dispatcher),
-    });
-
-    await act(async () => {
-      await result.current.start({ count: 2 });
-    });
-
-    await waitFor(() => expect(result.current.status).toBe("done"));
-    expect(result.current.chunks).toEqual([{ i: 0 }, { i: 1 }]);
-    expect(result.current.error).toBeNull();
-  });
-
-  test("stream error sets status=error and error envelope", async () => {
-    const err: DispatcherError = {
-      code: "access_denied",
-      httpStatus: 403,
-      i18nKey: "errors.access",
-      message: "denied",
-    };
-    const dispatcher = makeDispatcher(async function* () {
-      yield* []; // satisfy generator shape; error is the only outcome
-      throw err;
-    });
-
-    const { result } = renderHook(() => useStreamHandler("f:stream:x:tail"), {
-      wrapper: wrapperFor(dispatcher),
-    });
-
-    await act(async () => {
-      await result.current.start();
-    });
-
-    await waitFor(() => expect(result.current.status).toBe("error"));
-    expect(result.current.error?.code).toBe("access_denied");
-  });
-
-  test("abort during stream resets status to idle (no late done)", async () => {
-    let release!: () => void;
-    const gate = new Promise<void>((r) => {
-      release = r;
-    });
-    const dispatcher = makeDispatcher(async function* (
-      _t: string,
-      _p: unknown,
-      opts?: { signal?: AbortSignal },
-    ) {
-      yield { i: 0 };
-      await gate;
-      if (opts?.signal?.aborted) {
-        const e = { code: "aborted", httpStatus: 0, i18nKey: "x", message: "aborted" };
-        throw e;
-      }
-      yield { i: 1 };
-    });
-
-    const { result } = renderHook(() => useStreamHandler<{ i: number }>("f:stream:x:tail"), {
-      wrapper: wrapperFor(dispatcher),
-    });
-
-    let started!: Promise<void>;
-    act(() => {
-      started = result.current.start();
-    });
-    await waitFor(() => expect(result.current.chunks).toEqual([{ i: 0 }]));
-    act(() => result.current.abort());
-    release();
-    await started;
-    expect(result.current.chunks).toEqual([{ i: 0 }]);
-    expect(result.current.status).toBe("idle");
-  });
-});

package/src/hooks/use-ai-text.ts

@@ -1,172 +0,0 @@
-import type { DispatcherError } from "@cosmicdrift/kumiko-headless";
-import { useCallback, useEffect, useRef, useState } from "react";
-import { useDispatcher } from "../context/dispatcher-context";
-
-// AiTextField/AiTextArea's client-side surface. Deliberately duplicates the
-// wire-contract shape from kumiko-enterprise's `ai-text` feature instead of
-// importing it — this package is public NPM, ai-text is a private Enterprise
-// package, and the widgets only ever talk HTTP (ai-text-primitive plan doc,
-// Architecture Decision 1). Keep these in lockstep with
-// kumiko-enterprise/packages/ai-text/src/{modes,feature}.ts by hand; there's
-// no compile-time link between the two repos.
-
-export const AI_TEXT_RUN_QN = "ai-text:query:run";
-
-export type AiTextMode = "complete" | "correct" | "translate" | "rewrite";
-export type AiTextRewriteStyle = "formal" | "casual" | "concise" | "expand";
-
-export type AiTextRunPayload =
-  | { readonly mode: "complete"; readonly text: string }
-  | { readonly mode: "correct"; readonly text: string }
-  | { readonly mode: "translate"; readonly text: string; readonly targetLanguage: string }
-  | { readonly mode: "rewrite"; readonly text: string; readonly style?: AiTextRewriteStyle };
-
-export type AiTextUsage = { readonly inputTokens: number; readonly outputTokens: number };
-
-export type AiTextRunResult =
-  | { readonly type: "text"; readonly text: string; readonly usage: AiTextUsage }
-  | { readonly type: "error"; readonly reason: string; readonly usage: AiTextUsage };
-
-// =============================================================================
-// useAiTextAction — one-shot request/response, any mode
-// =============================================================================
-//
-// v1 has no streaming (ai-text-primitive plan doc, sequencing note —
-// SSE-with-auth-reuse needs a framework-core `r.streamHandler` primitive,
-// tracked separately). `complete` goes through this same request/response
-// path as correct/translate/rewrite; `useCompletion` below adds debounce on
-// top for the ghost-text use-case specifically.
-
-export type AiTextActionState =
-  | "idle"
-  | "loading"
-  | "success"
-  | "error"
-  | "cap-exceeded"
-  | "unavailable";
-
-export type UseAiTextActionResult = {
-  readonly run: (payload: AiTextRunPayload) => Promise<AiTextRunResult | null>;
-  readonly state: AiTextActionState;
-  readonly result: AiTextRunResult | null;
-  readonly error: DispatcherError | null;
-  readonly reset: () => void;
-};
-
-function stateForError(error: DispatcherError): AiTextActionState {
-  if (error.code === "cap_exceeded" || error.code === "rate_limited") return "cap-exceeded";
-  if (error.code === "feature_disabled") return "unavailable";
-  return "error";
-}
-
-export function useAiTextAction(): UseAiTextActionResult {
-  const dispatcher = useDispatcher();
-  const [state, setState] = useState<AiTextActionState>("idle");
-  const [result, setResult] = useState<AiTextRunResult | null>(null);
-  const [error, setError] = useState<DispatcherError | null>(null);
-
-  // Track the in-flight call so a newer `run()` cancels an older one, and
-  // unmount doesn't set state after the component is gone — same pattern
-  // as useQuery's activeCtrl.
-  const activeCtrl = useRef<AbortController | null>(null);
-  useEffect(() => {
-    return () => {
-      activeCtrl.current?.abort();
-    };
-  }, []);
-
-  const run = useCallback(
-    async (payload: AiTextRunPayload): Promise<AiTextRunResult | null> => {
-      activeCtrl.current?.abort();
-      const ctrl = new AbortController();
-      activeCtrl.current = ctrl;
-
-      setState("loading");
-      setError(null);
-
-      const res = await dispatcher.query<AiTextRunResult>(AI_TEXT_RUN_QN, payload, {
-        signal: ctrl.signal,
-      });
-      if (ctrl.signal.aborted) return null;
-
-      if (!res.isSuccess) {
-        if (res.error.code === "aborted") return null;
-        setError(res.error);
-        setState(stateForError(res.error));
-        return null;
-      }
-
-      setResult(res.data);
-      setState("success");
-      return res.data;
-    },
-    [dispatcher],
-  );
-
-  const reset = useCallback(() => {
-    activeCtrl.current?.abort();
-    setState("idle");
-    setResult(null);
-    setError(null);
-  }, []);
-
-  return { run, state, result, error, reset };
-}
-
-// =============================================================================
-// useCompletion — debounced ghost-text for AiTextField/AiTextArea
-// =============================================================================
-//
-// Debounce exists to keep the request-rate down against the monthly cap,
-// not for UX polish — every keystroke would otherwise burn a request.
-
-export type UseCompletionResult = {
-  readonly suggestion: string | null;
-  readonly state: AiTextActionState;
-  readonly error: DispatcherError | null;
-  /** Debounced — schedules a completion request `debounceMs` after the
-   *  last call. Calling again before the timer fires replaces it. */
-  readonly requestCompletion: (text: string) => void;
-  /** Cancels any pending/in-flight request and clears the suggestion. */
-  readonly clear: () => void;
-};
-
-const DEFAULT_DEBOUNCE_MS = 500;
-
-export function useCompletion(debounceMs: number = DEFAULT_DEBOUNCE_MS): UseCompletionResult {
-  const { run, state, result, error, reset } = useAiTextAction();
-  const timerRef = useRef<ReturnType<typeof setTimeout> | undefined>(undefined);
-
-  const clearTimer = useCallback(() => {
-    if (timerRef.current !== undefined) {
-      clearTimeout(timerRef.current);
-      timerRef.current = undefined;
-    }
-  }, []);
-
-  const requestCompletion = useCallback(
-    (text: string) => {
-      clearTimer();
-      if (text.length === 0) {
-        reset();
-        // skip: empty text, state already reset above
-        return;
-      }
-      timerRef.current = setTimeout(() => {
-        void run({ mode: "complete", text });
-      }, debounceMs);
-    },
-    [clearTimer, reset, run, debounceMs],
-  );
-
-  const clear = useCallback(() => {
-    clearTimer();
-    reset();
-  }, [clearTimer, reset]);
-
-  useEffect(() => clearTimer, [clearTimer]);
-
-  const suggestion = result?.type === "text" ? result.text : null;
-
-  return { suggestion, state, error, requestCompletion, clear };
-}

package/src/hooks/use-disclosure.ts

@@ -1,20 +0,0 @@
-import { useCallback, useState } from "react";
-
-// Open/close state for dialogs, sheets and collapsibles — the standard
-// replacement for the hand-rolled `useState(false)` + toggle-callback
-// trio in app screens. All callbacks are referentially stable.
-
-export type UseDisclosureResult = {
-  readonly open: boolean;
-  readonly onOpen: () => void;
-  readonly onClose: () => void;
-  readonly onToggle: () => void;
-};
-
-export function useDisclosure(initialOpen = false): UseDisclosureResult {
-  const [open, setOpen] = useState(initialOpen);
-  const onOpen = useCallback(() => setOpen(true), []);
-  const onClose = useCallback(() => setOpen(false), []);
-  const onToggle = useCallback(() => setOpen((prev) => !prev), []);
-  return { open, onOpen, onClose, onToggle };
-}

package/src/hooks/use-form.ts

@@ -1,78 +0,0 @@
-import type {
-  FormController,
-  FormControllerOptions,
-  FormSnapshot,
-  FormValues,
-} from "@cosmicdrift/kumiko-headless";
-import { createFormController } from "@cosmicdrift/kumiko-headless";
-import { useMemo, useSyncExternalStore } from "react";
-import { useOptionalDispatcher } from "../context/dispatcher-context";
-
-// Thin React wrapper around createFormController. Returns both the
-// controller (imperative — setField, submit, reset) and the current
-// snapshot (reactive — values, errors, isDirty). React subscribes via
-// useSyncExternalStore so re-renders happen exactly when the snapshot
-// reference changes, which the controller guarantees.
-//
-// The `submit.dispatcher` config is filled from context if omitted,
-// so the typical call site is just:
-//   const { snapshot, controller } = useForm({
-//     initial: { ... },
-//     schema,
-//     submit: { type: "foo:create" },
-//   });
-// and the hook wires the ambient DispatcherProvider's dispatcher in.
-
-export type UseFormOptions<TValues extends FormValues, TCtx = unknown> = FormControllerOptions<
-  TValues,
-  TCtx
->;
-
-export type UseFormResult<TValues extends FormValues> = {
-  readonly controller: FormController<TValues>;
-  readonly snapshot: FormSnapshot<TValues>;
-};
-
-export function useForm<TValues extends FormValues, TCtx = unknown>(
-  options: UseFormOptions<TValues, TCtx>,
-): UseFormResult<TValues> {
-  // Optional: a form with no `submit` config (or one with an explicit
-  // dispatcher) never needs the ambient one, and mounting without a
-  // DispatcherProvider must not crash just because useForm was called.
-  const contextDispatcher = useOptionalDispatcher();
-
-  // The controller is created once per mount. `options` mutates across
-  // renders in normal React usage (closures get new references), but
-  // the controller's behaviour depends only on the initial shape — we
-  // deliberately don't re-create on option-identity change, which
-  // would wipe in-flight state and "forget" dirty edits on every
-  // parent re-render. If the app needs a reset, call controller.reset()
-  // or re-mount the form (key prop).
-  // Controller lifetime = hook lifetime. Options deliberately NOT in
-  // the deps array; re-creating on option-identity change would wipe
-  // in-flight state and dirty edits on every parent re-render.
-  // biome-ignore lint/correctness/useExhaustiveDependencies: intentional — controller is lifetime-scoped, not render-scoped
-  const controller = useMemo<FormController<TValues>>(() => {
-    // Default submit.dispatcher to the ambient one when omitted.
-    type FullOptions = FormControllerOptions<TValues, TCtx>;
-    const rawSubmit = options.submit;
-    const submitConfig: FullOptions["submit"] = rawSubmit
-      ? { ...rawSubmit, dispatcher: rawSubmit.dispatcher ?? contextDispatcher }
-      : undefined;
-    const controllerOptions: FullOptions = {
-      ...(options as FullOptions),
-      ...(submitConfig !== undefined && { submit: submitConfig }),
-    };
-    return createFormController<TValues, TCtx>(controllerOptions);
-  }, []);
-
-  const snapshot = useSyncExternalStore(
-    (notify) => controller.subscribe(notify),
-    () => controller.getSnapshot(),
-    // SSR snapshot: same as getSnapshot(). The controller's initial
-    // snapshot is deterministic from options.initial, safe for server.
-    () => controller.getSnapshot(),
-  );
-
-  return { controller, snapshot };
-}