@lynx-go/ui-kit 0.0.0-stage → 0.1.1

package/src/kernel/types.ts

@@ -0,0 +1,128 @@
+/**
+ * kernel —— 元概念的契约与纯代数（零依赖、零 react import）。
+ *
+ * 三个交互原语（问/令/听）+ 一个交互面（Resource）。
+ * 设计依据：docs/design.md §2。
+ */
+
+// ============ 流几何 ============
+
+/** 不透明定位令牌；collection 的 cursor window 与 subscription 共享。 */
+export type Cursor = string;
+
+export type FieldValue = string | number | boolean | ReadonlyArray<string>;
+
+export type Operator = "eq" | "ne" | "contains" | "in" | "gt" | "lt" | "gte" | "lte" | "exists";
+
+/** 构造侧类型化（可收窄为 `keyof T & string`）、解码侧宽容（string）。 */
+type FieldKeyBrand = string & { readonly __fieldKey?: unique symbol };
+export type FieldKey<F extends string = string> = F | FieldKeyBrand;
+
+export interface QueryWindow {
+  /** 必传（torchwood 契约：pageSize 缺省即截断事故） */
+  size: number;
+  /** keyset 方言：不透明续读令牌 */
+  cursor?: Cursor;
+  /** offset 方言（配合 Segment.total） */
+  range?: { offset: number };
+}
+
+export interface Order {
+  field: FieldKey;
+  dir: "asc" | "desc";
+}
+
+export type Predicate =
+  | { field: FieldKey; op: Operator; value: FieldValue }
+  | { all: ReadonlyArray<Predicate> }
+  | { any: ReadonlyArray<Predicate> };
+
+/** 集合查询的结构化意图。分页只是 window 的字段，不是概念。 */
+export interface CollectionQuery {
+  predicate?: Predicate;
+  order?: ReadonlyArray<Order>;
+  window: QueryWindow;
+}
+
+/** 查询结果段。字段命名刻意与 useInfiniteQuery 的 getNextPageParam 对齐。 */
+export interface Segment<T> {
+  rows: ReadonlyArray<T>;
+  /** offset 方言必有；leaderboards 型 keyset 也附带 */
+  total?: number;
+  /** 仅还有下页时出现（"返回数 < size"不代表到底） */
+  nextCursor?: Cursor;
+}
+
+// ============ 失败通道（封闭集） ============
+// 失败 = 无法产出领域可用值的传输/会话/协议层状况。
+// 网络断层是 typed failure（可捕获、可重试、可渲染），不是 defect——defect 只留程序错误（§5 缝 1）。
+
+export type ApiError =
+  | { kind: "network"; cause?: unknown }
+  | { kind: "auth" }
+  | { kind: "forbidden" }
+  | { kind: "not-found" }
+  | { kind: "server"; status: number; message?: string }
+  | { kind: "decode"; detail: string };
+
+const API_ERROR_KINDS = new Set(["network", "auth", "forbidden", "not-found", "server", "decode"]);
+
+export function isApiError(value: unknown): value is ApiError {
+  return (
+    typeof value === "object" &&
+    value !== null &&
+    API_ERROR_KINDS.has((value as { kind?: unknown }).kind as string)
+  );
+}
+
+/** 封闭集的配套：绑定为 Query/Mutation 注入的默认重试分类。 */
+export function isRetryable(error: ApiError): boolean {
+  return error.kind === "network" || error.kind === "server";
+}
+
+// ============ 结果通道（已知分支 + ok 载荷兜底） ============
+
+export type CommandResult<P = unknown> =
+  | { status: "ok"; payload: P }
+  | {
+      status: "rejected";
+      /** 机器可判别（双 console 后端都有 code/message——契约不能丢判别码） */
+      code?: string;
+      message: string;
+      fieldErrors?: Record<string, string>;
+    }
+  | { status: "conflict"; message: string };
+
+// ============ 订阅（听） ============
+
+export interface SubscriptionPolicy {
+  /** 环形缓冲容量（超限丢最旧） */
+  buffer: number;
+  pauseable?: boolean;
+  retry?: {
+    /** 退避序列，例 [1000, 2000, 4000]。退避耗尽 → stalled，轮询兜底是消费方组合 */
+    backoffMs: ReadonlyArray<number>;
+  };
+}
+
+/** 终态分诊归 transport：票据/base64/E_EVENTS_GONE/部署 state 解析全在消费方适配器。 */
+export interface FrameSource<F> {
+  [Symbol.asyncIterator](): AsyncIterator<F>;
+  /** 迭代器 return（正常结束）时引擎读到的终结原因 */
+  readonly closeReason: "ended" | "gapped" | "auth" | "transport";
+}
+
+export interface Transport<F> {
+  open(cursor: Cursor | null, signal: AbortSignal): FrameSource<F>;
+  /** 重连前钩子（torchwood realtime 的"先 refresh 再重订"）；自带恢复的 transport 可不实现 */
+  beforeReconnect?(): Promise<void>;
+}
+
+export type SubscriptionStatus =
+  | "live"
+  | "reconnecting"
+  | "paused"
+  | "gapped"
+  | "stalled"
+  | "ended"
+  | "error";

package/src/react/bindings.ts

@@ -0,0 +1,231 @@
+import { keepPreviousData, useQuery } from "@tanstack/react-query";
+import { useNavigate, useSearch } from "@tanstack/react-router";
+import {
+  type ApiError,
+  advance,
+  type CollectionQuery,
+  type CommandsRecord,
+  type Order,
+  type Predicate,
+  type QueryWindow,
+  type Resource,
+  type ResourceScope,
+  type Segment,
+  type SubsRecord,
+  scoped,
+} from "../kernel";
+import type { FlatPatch, QuerySearchSchema } from "../schema";
+import { batchQueryOptions, collectionQueryOptions, recordQueryOptions } from "./options";
+
+/**
+ * useCollection —— collection Query ↔ URL ↔ Table 的绑定。
+ *
+ * 写入契约（design.md §2.1.1）：
+ * - 一切 setter 走函数式 search（对象字面量会静默 strip 消费方自定义参数）；
+ * - 翻页 = push（历史栈即分页栈）；谓词/排序变化 = replace + 清游标回第一页；
+ * - 绑定不在渲染期 navigate。
+ */
+export interface CollectionHandle<T> {
+  rows: ReadonlyArray<T>;
+  segment: Segment<T> | undefined;
+  /** 当前解码后的完整查询（URL + schema 默认值即真相） */
+  query: CollectionQuery;
+  status: "loading" | "empty" | "error" | "success";
+  error: ApiError | null;
+  total: number | undefined;
+  isFetching: boolean;
+  refetch: () => void;
+  /** replace + 回第一页 */
+  setPredicate(predicate: Predicate | null): void;
+  /** replace + 回第一页（keyset 游标与方向耦合） */
+  setOrder(order: ReadonlyArray<Order> | null): void;
+  /** push —— 历史即分页栈 */
+  setWindow(window: QueryWindow): void;
+  /** 游标推进；返回 false = 不可算（keyset prev 走浏览器历史） */
+  next(): boolean;
+  prev(): boolean;
+  reset(): void;
+  /** 逃生舱：直接打 URL 补丁（含消费方自定义参数） */
+  searchPatch(patch: FlatPatch, options?: { replace?: boolean }): void;
+}
+
+const EMPTY_ROWS: ReadonlyArray<never> = [];
+
+export interface UseCollectionOptions {
+  /** 调用方路由 id（Route.id——search 解码锚定活跃 match；pathless 布局下与 fullPath 不同形） */
+  from: string;
+  /** collectionQuerySchema 的返回值（与路由 validateSearch 共用同一实例） */
+  search: QuerySearchSchema;
+  scope?: ResourceScope;
+  query?: {
+    staleTime?: number;
+    refetchInterval?: number | false;
+    enabled?: boolean;
+    /** 默认 true：翻页/过滤过渡不闪 loading */
+    keepPrevious?: boolean;
+  };
+}
+
+export function useCollection<T, ID, C extends CommandsRecord<ID>, S extends SubsRecord>(
+  resource: Resource<T, ID, C, S>,
+  options: UseCollectionOptions,
+): CollectionHandle<T> {
+  // from 是调用方路由的 id（useSearch 按路由 id 找活跃 match；pathless
+  // 布局下 Route.fullPath 与 id 不同形——fleetly 试点实咬，契约 = Route.id）。
+  const rawSearch = useSearch({ from: options.from as never, strict: false }) as unknown as Record<
+    string,
+    unknown
+  >;
+  // navigate 不带 from：TanStack Router 的 navigate({to:"."}) 把 from 当路径
+  // 模板解析（pathless 段不在路径里），而 useSearch 的 from 是路由 id——两个
+  // hook 的 from 语义不同。demo 顶层路由 id==path 掩盖了差异；嵌套/带参/
+  // pathless 路由下带 from 的 "." 解析会产出 "_shell/..." 假路径。不带 from
+  // 时 "." 对当前 match 的真实路径解析，全形态正确（写入契约 §2.1.1 不变：
+  // setter 只在事件期调用，不在渲染期）。
+  const navigate = useNavigate() as unknown as (opts: {
+    to: string;
+    search: (prev: Record<string, unknown>) => Record<string, unknown>;
+    replace?: boolean;
+  }) => Promise<void>;
+
+  const target = options.scope ? scoped(resource, options.scope) : resource;
+  const query = options.search.decode(rawSearch);
+  const keepPrevious = options.query?.keepPrevious !== false;
+
+  const result = useQuery<Segment<T>, ApiError>({
+    ...collectionQueryOptions(target, query, {
+      ...(options.query?.staleTime !== undefined ? { staleTime: options.query.staleTime } : {}),
+      ...(options.query?.refetchInterval !== undefined
+        ? { refetchInterval: options.query.refetchInterval }
+        : {}),
+      ...(options.query?.enabled !== undefined ? { enabled: options.query.enabled } : {}),
+    }),
+    ...(keepPrevious ? { placeholderData: keepPreviousData } : {}),
+  });
+
+  const searchPatch = (patch: FlatPatch, navOptions?: { replace?: boolean }) => {
+    void navigate({
+      to: ".",
+      search: (prev: Record<string, unknown>) => ({ ...prev, ...patch }),
+      replace: navOptions?.replace ?? false,
+    });
+  };
+
+  const setPredicate = (predicate: Predicate | null) => {
+    searchPatch(options.search.patch({ predicate: predicate ?? null }), { replace: true });
+  };
+  const setOrder = (order: ReadonlyArray<Order> | null) => {
+    searchPatch(options.search.patch({ order: order ?? null }), { replace: true });
+  };
+  const setWindow = (window: QueryWindow) => {
+    searchPatch(options.search.patch({ window }), { replace: false });
+  };
+  const next = (): boolean => {
+    const segment = result.data;
+    if (!segment) return false;
+    const w = advance(query.window, segment, "next");
+    if (!w) return false;
+    setWindow(w);
+    return true;
+  };
+  const prev = (): boolean => {
+    const segment = result.data;
+    if (!segment) return false;
+    const w = advance(query.window, segment, "prev");
+    if (!w) return false;
+    setWindow(w);
+    return true;
+  };
+  const reset = () => {
+    searchPatch(
+      {
+        q: undefined,
+        filter: undefined,
+        sort: undefined,
+        cursor: undefined,
+        page: undefined,
+      },
+      { replace: true },
+    );
+  };
+
+  const rows = result.data?.rows ?? EMPTY_ROWS;
+  const status: CollectionHandle<T>["status"] = result.isPending
+    ? "loading"
+    : result.isError
+      ? "error"
+      : rows.length === 0
+        ? "empty"
+        : "success";
+
+  return {
+    rows,
+    segment: result.data,
+    query,
+    status,
+    error: result.error ?? null,
+    total: result.data?.total,
+    isFetching: result.isFetching,
+    refetch: () => void result.refetch(),
+    setPredicate,
+    setOrder,
+    setWindow,
+    next,
+    prev,
+    reset,
+    searchPatch,
+  };
+}
+
+export interface RecordHandle<T> {
+  data: T | undefined;
+  status: "loading" | "error" | "success";
+  error: ApiError | null;
+  refetch: () => void;
+}
+
+export function useRecord<T, ID, C extends CommandsRecord<ID>, S extends SubsRecord>(
+  resource: Resource<T, ID, C, S>,
+  options: { id: ID | undefined; scope?: ResourceScope; query?: { staleTime?: number } },
+): RecordHandle<T> {
+  const target = options.scope ? scoped(resource, options.scope) : resource;
+  const result = useQuery<T, ApiError>({
+    ...recordQueryOptions(target, options.id, {
+      ...(options.query?.staleTime !== undefined ? { staleTime: options.query.staleTime } : {}),
+    }),
+  });
+  return {
+    data: result.data,
+    status: result.isPending ? "loading" : result.isError ? "error" : "success",
+    error: result.error ?? null,
+    refetch: () => void result.refetch(),
+  };
+}
+
+export interface BatchHandle<T, ID> {
+  rows: ReadonlyArray<T>;
+  byId: ReadonlyMap<ID, T>;
+  status: "loading" | "error" | "success";
+}
+
+export function useBatch<T, ID, C extends CommandsRecord<ID>, S extends SubsRecord>(
+  resource: Resource<T, ID, C, S>,
+  ids: ReadonlyArray<ID>,
+  options: { scope?: ResourceScope; query?: { staleTime?: number } } = {},
+): BatchHandle<T, ID> {
+  const target = options.scope ? scoped(resource, options.scope) : resource;
+  const result = useQuery<ReadonlyArray<T>, ApiError>({
+    ...batchQueryOptions(target, ids, {
+      ...(options.query?.staleTime !== undefined ? { staleTime: options.query.staleTime } : {}),
+    }),
+  });
+  const rows = result.data ?? EMPTY_ROWS;
+  const byId = new Map(
+    rows.map((row) => [target.getId ? target.getId(row) : (row as unknown as { id: ID }).id, row]),
+  );
+  return {
+    rows,
+    byId,
+    status: result.isPending ? "loading" : result.isError ? "error" : "success",
+  };
+}

package/src/react/command.ts

@@ -0,0 +1,122 @@
+import { useForm } from "@tanstack/react-form";
+import { useMutation, useQueryClient } from "@tanstack/react-query";
+import {
+  type ApiError,
+  type CommandDescriptor,
+  type CommandResult,
+  invalidationPredicate,
+  type QuerySelector,
+  type ResourceScope,
+  runCommand,
+} from "../kernel";
+
+/**
+ * useCommand —— Command 原语的绑定（问/令/听的"令"）。
+ *
+ * - rejected/conflict 是**结果**（mutation.data），只有失败（网络/401/解码）走 mutation.error；
+ * - ok 后执行失效：descriptor.invalidates 声明优先，缺省 = 同资源全部查询（内置动词默认失效）；
+ *   selector 默认与命令 ctx scope 相交（project A 的命令不清 project B 的缓存）；
+ * - treatAs 裁决在 kernel runCommand 单源完成；
+ * - 库不内置 toast：onSettled 回调交消费方（sonner 等）。
+ */
+export interface UseCommandOptions<Payload> {
+  scope?: ResourceScope;
+  onSettled?: (result: CommandResult<Payload> | null, failure: ApiError | null) => void;
+}
+
+export interface CommandHandle<Input, Payload> {
+  mutate(input: Input): void;
+  mutateAsync(input: Input): Promise<CommandResult<Payload>>;
+  /** 最近一次结果（结果通道，非异常） */
+  result: CommandResult<Payload> | null;
+  pending: boolean;
+  /** 失败通道（ApiError）——与结果两分 */
+  failure: ApiError | null;
+  reset(): void;
+}
+
+export function useCommand<Input, Payload, ID = never>(
+  descriptor: CommandDescriptor<Input, Payload, ID>,
+  options: UseCommandOptions<Payload> = {},
+): CommandHandle<Input, Payload> {
+  const queryClient = useQueryClient();
+  const scope = options.scope ?? {};
+
+  const mutation = useMutation<CommandResult<Payload>, ApiError, Input>({
+    mutationFn: (input) => runCommand(descriptor, input, scope),
+    onSuccess: (result) => {
+      if (result.status === "ok") {
+        const selectors: ReadonlyArray<QuerySelector> =
+          descriptor.invalidates ??
+          (descriptor.__resource !== undefined ? [{ resource: descriptor.__resource }] : []);
+        if (selectors.length > 0) {
+          void queryClient.invalidateQueries({
+            predicate: invalidationPredicate(selectors, scope),
+          });
+        }
+      }
+      options.onSettled?.(result, null);
+    },
+    onError: (error) => options.onSettled?.(null, error),
+  });
+
+  return {
+    mutate: (input) => mutation.mutate(input),
+    mutateAsync: mutation.mutateAsync,
+    result: mutation.data ?? null,
+    pending: mutation.isPending,
+    failure: mutation.error ?? null,
+    reset: mutation.reset,
+  };
+}
+
+/**
+ * useCommandForm —— Command × TanStack Form 的表单绑定（design.md §5.4）。
+ *
+ * - rejected → onSubmit 返回 { form: message, fields: fieldErrors }（v1 文档化路径；
+ *   setErrorMap 已被 v2 alpha 删除——不建在被删的 API 上）；
+ * - conflict → form 级消息；ok → 失效已在 useCommand 完成，reveal 载荷经绑定状态暴露
+ *   （不进 Query 缓存、卸载即弃）；
+ * - 服务端驱动 defaultValues 重播（dirty 不覆盖）由消费方经 key 重挂或 form.reset 实现（后续块内建）。
+ */
+export interface UseCommandFormOptions<Input extends object, Payload> {
+  defaultValues: Input;
+  scope?: ResourceScope;
+  onSettled?: (result: CommandResult<Payload> | null, failure: ApiError | null) => void;
+}
+
+export function useCommandForm<Input extends object, Payload, ID = never>(
+  descriptor: CommandDescriptor<Input, Payload, ID>,
+  options: UseCommandFormOptions<Input, Payload>,
+) {
+  const command = useCommand(descriptor, {
+    scope: options.scope,
+    onSettled: options.onSettled,
+  });
+
+  const form = useForm({
+    defaultValues: options.defaultValues,
+    onSubmit: async ({ value }) => {
+      const result = await command.mutateAsync(value);
+      if (result.status === "rejected") {
+        return {
+          form: result.message,
+          ...(result.fieldErrors ? { fields: result.fieldErrors } : {}),
+        };
+      }
+      if (result.status === "conflict") {
+        return { form: result.message };
+      }
+      return undefined;
+    },
+  });
+
+  return {
+    form,
+    submitting: command.pending || form.state.isSubmitting,
+    result: command.result,
+    /** 一次性 reveal 载荷（ok payload）：token/邀请等"只在这一帧存在"的值 */
+    reveal: command.result?.status === "ok" ? command.result.payload : undefined,
+    command,
+  };
+}

package/src/react/index.ts

@@ -0,0 +1,46 @@
+export type {
+  SubscriptionEngine,
+  SubscriptionHandle,
+  SubscriptionState,
+} from "../adapters/subscription";
+export {
+  type BatchHandle,
+  type CollectionHandle,
+  type RecordHandle,
+  type UseCollectionOptions,
+  useBatch,
+  useCollection,
+  useRecord,
+} from "./bindings";
+export {
+  type CommandHandle,
+  type UseCommandFormOptions,
+  type UseCommandOptions,
+  useCommand,
+  useCommandForm,
+} from "./command";
+export {
+  createFrameInvalidator,
+  type FrameInvalidator,
+  type UseInvalidateOnFrameOptions,
+  useInvalidateOnFrame,
+} from "./invalidate";
+export {
+  batchQueryOptions,
+  collectionQueryOptions,
+  type QueryEngineOptions,
+  recordQueryOptions,
+} from "./options";
+export {
+  type CanHandle,
+  type IdentityLike,
+  type PermissionState,
+  permissionState,
+  useCan,
+} from "./permissions";
+export {
+  decodePreference,
+  type PreferenceCodec,
+  usePreference,
+} from "./preferences";
+export { type UseSubscriptionOptions, useSubscription } from "./subscription";

package/src/react/invalidate.ts

@@ -0,0 +1,81 @@
+import { useQueryClient } from "@tanstack/react-query";
+import { useEffect, useRef } from "react";
+import type { SubscriptionEngine } from "../adapters/subscription";
+import { invalidationPredicate, type QuerySelector, type ResourceScope } from "../kernel";
+
+/**
+ * useInvalidateOnFrame —— 实时失效（design.md §3 派生表：帧到达 → invalidate(选择器)）。
+ *
+ * 组合钩子（非新原语）：订阅帧流 × Query 缓存失效。Selector 语义与 useCommand 的
+ * invalidates 完全同源（invalidationPredicate 单源）；scope 缺省与本组件域相交。
+ *
+ * - filter：帧级谓词（如只对 deleted 帧失效）——过滤是纯函数，热路径零成本；
+ * - throttleMs：失效合并窗口（trailing 单射）。热日志流（>10 帧/s）建议给窗口，
+ *   invalidateQueries 本身幂等且 active 查询去重，缺省 0 = 每帧即射（语义最小惊讶）。
+ */
+
+export interface FrameInvalidator {
+  /** 帧已通过调用方过滤后入队（窗口内合并） */
+  ingest(): void;
+  /** 卸载/重建时丢弃未射的窗口（不给已卸载组件补射失效） */
+  cancel(): void;
+}
+
+/** 纯调度器（可单测；hook 只做 sub.onFrame × queryClient 接线）。 */
+export function createFrameInvalidator(fire: () => void, throttleMs = 0): FrameInvalidator {
+  if (throttleMs <= 0) return { ingest: fire, cancel: () => undefined };
+  let timer: ReturnType<typeof setTimeout> | null = null;
+  return {
+    ingest() {
+      if (timer !== null) return;
+      timer = setTimeout(() => {
+        timer = null;
+        fire();
+      }, throttleMs);
+    },
+    cancel() {
+      if (timer !== null) {
+        clearTimeout(timer);
+        timer = null;
+      }
+    },
+  };
+}
+
+export interface UseInvalidateOnFrameOptions<F> {
+  scope?: ResourceScope;
+  /** 帧级谓词：只对满足的帧失效（缺省全部帧） */
+  filter?: (frame: F) => boolean;
+  /** 失效合并窗口 ms（缺省 0 = 每帧即射） */
+  throttleMs?: number;
+}
+
+export function useInvalidateOnFrame<F>(
+  sub: SubscriptionEngine<F>,
+  selectors: ReadonlyArray<QuerySelector>,
+  options: UseInvalidateOnFrameOptions<F> = {},
+): void {
+  const queryClient = useQueryClient();
+  // 回调/谓词经 ref 透传（标识每渲染变化不应重订帧回调）
+  const optionsRef = useRef(options);
+  optionsRef.current = options;
+  const selectorsKey = JSON.stringify(selectors);
+
+  // biome-ignore lint/correctness/useExhaustiveDependencies: selectors 数组字面量每渲染变化不应重订——经 selectorsKey 锚定
+  useEffect(() => {
+    const invalidator = createFrameInvalidator(() => {
+      void queryClient.invalidateQueries({
+        predicate: invalidationPredicate(selectors, optionsRef.current.scope ?? {}),
+      });
+    }, optionsRef.current.throttleMs ?? 0);
+    const unsubscribe = sub.onFrame((frame) => {
+      const filter = optionsRef.current.filter;
+      if (filter && !filter(frame)) return;
+      invalidator.ingest();
+    });
+    return () => {
+      unsubscribe();
+      invalidator.cancel();
+    };
+  }, [sub, queryClient, selectorsKey]);
+}