@chelone/vue 0.0.0-stage → 0.1.1

package/dist/controllers/use-create-controller.js

@@ -0,0 +1,25 @@
+import { createCreateController } from "@chelone/core";
+import { reactive, computed } from "vue";
+import { useCheloneContext } from "../context.js";
+import { useRequiredResource } from "../resource-context.js";
+import { useMicroStore } from "../store/use-micro-store.js";
+import { toControllerContext } from "./controller-context.js";
+function useCreateController(options = {}) {
+  const ctx = useCheloneContext();
+  const resource = useRequiredResource("useCreateController", options);
+  const controller = createCreateController(
+    toControllerContext(ctx),
+    resource,
+    options
+  );
+  const state = useMicroStore(controller);
+  return reactive({
+    record: computed(() => state.value.record),
+    isPending: computed(() => state.value.isPending),
+    saving: computed(() => state.value.saving),
+    save: controller.save
+  });
+}
+export {
+  useCreateController
+};

package/dist/controllers/use-delete-controller.d.ts

@@ -0,0 +1,20 @@
+/**
+ * `useDeleteController` — the Vue bridge for the vanilla core delete controller,
+ * the twin of `@chelone/react`'s `useDeleteController` (`controller-hooks.ts`).
+ * A delete has NOTHING to fetch; the only acquired resource is the shared
+ * `MutationObserver`, attached on mount and released on scope disposal through
+ * `useMicroStore`'s 4R lifecycle.
+ *
+ * `deleteOne` is the controller's own pipeline: delete → notify `deleted` →
+ * request the list redirect → strip the id from the `${resource}.selectedIds`
+ * selection. A provider error notifies `http_error` and resolves; it never rejects.
+ */
+import { type DeleteController, type DeleteControllerOptions, type DeleteControllerState, type MicroStore, type RecordOf, type ResourceMap } from "@chelone/core";
+/** Options for {@link useDeleteController}: the core delete options + a resource override. */
+export interface UseDeleteControllerOptions extends DeleteControllerOptions {
+    /** Target a specific resource; defaults to the ambient `<Resource>` name. */
+    resource?: string;
+}
+/** The reactive result: the delete-controller state (unwrapped, live) plus the stable `deleteOne`. */
+export type UseDeleteControllerReturn<TRecord> = DeleteControllerState & Omit<DeleteController<TRecord>, keyof MicroStore<DeleteControllerState>>;
+export declare function useDeleteController<TResources extends ResourceMap = ResourceMap, TName extends keyof TResources & string = keyof TResources & string>(options?: UseDeleteControllerOptions): UseDeleteControllerReturn<RecordOf<TResources, TName>>;

package/dist/controllers/use-delete-controller.js

@@ -0,0 +1,23 @@
+import { createDeleteController } from "@chelone/core";
+import { reactive, computed } from "vue";
+import { useCheloneContext } from "../context.js";
+import { useRequiredResource } from "../resource-context.js";
+import { useMicroStore } from "../store/use-micro-store.js";
+import { toControllerContext } from "./controller-context.js";
+function useDeleteController(options = {}) {
+  const ctx = useCheloneContext();
+  const resource = useRequiredResource("useDeleteController", options);
+  const controller = createDeleteController(
+    toControllerContext(ctx),
+    resource,
+    options
+  );
+  const state = useMicroStore(controller);
+  return reactive({
+    saving: computed(() => state.value.saving),
+    deleteOne: controller.deleteOne
+  });
+}
+export {
+  useDeleteController
+};

package/dist/controllers/use-edit-controller.d.ts

@@ -0,0 +1,29 @@
+/**
+ * `useEditController` — the Vue bridge for the vanilla core edit controller, the
+ * twin of `@chelone/react`'s `useEditController` (`controller-hooks.ts`). It
+ * fetches ONE record (a `getOne` `QueryObserver` over `ctx.queryClient`) and
+ * exposes a `save` that persists through the core update mutation.
+ *
+ * The seam is identical to {@link useListController}: the controller owns the
+ * vanilla `query-core` observers over the vue-query `QueryClient` `<Admin>`
+ * provides; `useMicroStore` is the single subscribe bridge (4R acquire on mount,
+ * release on scope disposal). `save` is the controller's own `save` — at this
+ * layer it is the raw core save pipeline (validate → persist → notify, resolving
+ * server field errors); the FORM reconciliation (`form.reset(saved)`, field-
+ * error mapping) is layered on top in the form composables (Task 6), exactly as
+ * the React twin keeps `controller-hooks` thin and composes the form in
+ * `form-hooks`.
+ *
+ * The record `id` defaults to the ambient `:id` route param (read through the
+ * router adapter) when not passed — mirroring how the React `<Edit>` view reads
+ * `useParams().id`. Pass `id` explicitly to target a record without a router.
+ */
+import { type EditController, type EditControllerOptions, type EditControllerState, type MicroStore, type RecordOf, type ResourceMap } from "@chelone/core";
+/** Options for {@link useEditController}: the core edit options (id optional) + a resource override. */
+export interface UseEditControllerOptions<TRecord> extends Partial<EditControllerOptions<TRecord>> {
+    /** Target a specific resource; defaults to the ambient `<Resource>` name. */
+    resource?: string;
+}
+/** The reactive result: the edit-controller state (unwrapped, live) plus the stable `save`. */
+export type UseEditControllerReturn<TRecord> = EditControllerState<TRecord> & Omit<EditController<TRecord>, keyof MicroStore<EditControllerState<TRecord>>>;
+export declare function useEditController<TResources extends ResourceMap = ResourceMap, TName extends keyof TResources & string = keyof TResources & string>(options?: UseEditControllerOptions<RecordOf<TResources, TName>>): UseEditControllerReturn<RecordOf<TResources, TName>>;

package/dist/controllers/use-edit-controller.js

@@ -0,0 +1,40 @@
+import { createEditController } from "@chelone/core";
+import { reactive, computed } from "vue";
+import { useCheloneContext } from "../context.js";
+import { useRequiredResource } from "../resource-context.js";
+import { useRouterAdapterOptional } from "../router/adapter.js";
+import { useMicroStore } from "../store/use-micro-store.js";
+import { toControllerContext } from "./controller-context.js";
+function resolveId(explicit) {
+  if (explicit !== void 0) return explicit;
+  const adapter = useRouterAdapterOptional();
+  const id = adapter?.useParams().value.id;
+  if (id === void 0) {
+    throw new Error(
+      "useEditController: no `id` option and no `:id` route param — pass an id or render under an edit route."
+    );
+  }
+  return id;
+}
+function useEditController(options = {}) {
+  const ctx = useCheloneContext();
+  const resource = useRequiredResource("useEditController", options);
+  const id = resolveId(options.id);
+  const controller = createEditController(
+    toControllerContext(ctx),
+    resource,
+    { ...options, id }
+  );
+  const state = useMicroStore(controller);
+  return reactive({
+    record: computed(() => state.value.record),
+    isPending: computed(() => state.value.isPending),
+    isFetching: computed(() => state.value.isFetching),
+    error: computed(() => state.value.error),
+    saving: computed(() => state.value.saving),
+    save: controller.save
+  });
+}
+export {
+  useEditController
+};

package/dist/controllers/use-infinite-list-controller.d.ts

@@ -0,0 +1,25 @@
+/**
+ * `useInfiniteListController` — the Vue bridge for the vanilla core infinite
+ * list controller, the twin of `@chelone/react`'s hook (`infinite-hooks.ts`)
+ * and the sibling of `useListController`: one controller built at `setup`
+ * (construction is INERT), attached by `useMicroStore` on mount and released on
+ * scope disposal, behind a `reactive` facade of state and stable actions.
+ *
+ * Filters and sort live in the store only: the composable never reads or
+ * writes the location.
+ */
+import { type InfiniteListController, type InfiniteListControllerState, type ListControllerOptions, type MicroStore, type RecordOf, type ResourceMap } from "@chelone/core";
+/** Options for {@link useInfiniteListController}: the core list options + a resource override. */
+export interface UseInfiniteListControllerOptions extends ListControllerOptions {
+    /** Target a specific resource; defaults to the ambient `<Resource>` name. */
+    resource?: string;
+}
+/** The reactive result: every field of the infinite state (live) plus the stable actions. */
+export type UseInfiniteListControllerReturn<TRecord> = InfiniteListControllerState<TRecord> & Omit<InfiniteListController<TRecord>, keyof MicroStore<InfiniteListControllerState<TRecord>>>;
+/**
+ * Load a resource list page by page. `fetchNextPage` appends the next page to
+ * `data`; any change to filter, sort, page or perPage drops the loaded pages
+ * and starts over. The controller attaches on mount and releases on scope
+ * disposal. `options` are read once at `setup`.
+ */
+export declare function useInfiniteListController<TResources extends ResourceMap = ResourceMap, TName extends keyof TResources & string = keyof TResources & string>(options?: UseInfiniteListControllerOptions): UseInfiniteListControllerReturn<RecordOf<TResources, TName>>;

package/dist/controllers/use-infinite-list-controller.js

@@ -0,0 +1,40 @@
+import { createInfiniteListController, listControllerActions } from "@chelone/core";
+import { reactive, computed } from "vue";
+import { useCheloneContext } from "../context.js";
+import { useRequiredResource } from "../resource-context.js";
+import { useMicroStore } from "../store/use-micro-store.js";
+import { toControllerContext } from "./controller-context.js";
+function useInfiniteListController(options = {}) {
+  const ctx = useCheloneContext();
+  const resource = useRequiredResource(
+    "useInfiniteListController",
+    options
+  );
+  const controller = createInfiniteListController(toControllerContext(ctx), resource, options);
+  const state = useMicroStore(controller);
+  const facade = reactive({
+    data: computed(() => state.value.data),
+    total: computed(() => state.value.total),
+    pageInfo: computed(() => state.value.pageInfo),
+    isPending: computed(() => state.value.isPending),
+    isFetching: computed(() => state.value.isFetching),
+    isFetchingNextPage: computed(() => state.value.isFetchingNextPage),
+    isFetchingPreviousPage: computed(() => state.value.isFetchingPreviousPage),
+    error: computed(() => state.value.error),
+    page: computed(() => state.value.page),
+    perPage: computed(() => state.value.perPage),
+    sort: computed(() => state.value.sort),
+    filter: computed(() => state.value.filter),
+    displayedFilters: computed(() => state.value.displayedFilters),
+    selectedIds: computed(() => state.value.selectedIds),
+    hasNextPage: computed(() => state.value.hasNextPage),
+    hasPreviousPage: computed(() => state.value.hasPreviousPage),
+    ...listControllerActions(controller),
+    fetchNextPage: controller.fetchNextPage,
+    fetchPreviousPage: controller.fetchPreviousPage
+  });
+  return facade;
+}
+export {
+  useInfiniteListController
+};

package/dist/controllers/use-list-controller.d.ts

@@ -0,0 +1,50 @@
+/**
+ * `useListController` — the Vue bridge for the vanilla core list controller, the
+ * twin of `@chelone/react`'s `useListController` (`controller-hooks.ts`). It
+ * wraps `createListController` (unchanged core) through the Task-2 `useMicroStore`
+ * reactivity bridge and returns a `reactive` view of controller state plus the
+ * controller's stable actions.
+ *
+ * How the fetch is driven (the "vue-query wiring"): the controller itself owns a
+ * `QueryObserver` over `ctx.queryClient` — the SAME vanilla `query-core`
+ * observer the React adapter's controllers use. `<Admin>` creates the
+ * `@tanstack/vue-query` `QueryClient` and provides it on the Chelone context;
+ * `toControllerContext` hands it to `createListController`, whose observer reads
+ * and writes that client's cache. So there is no `useQuery` hook in the seam —
+ * the controller drives the query, and `useMicroStore` is the single subscribe seam
+ * that turns the controller's `MicroStore` snapshots into Vue reactivity (the
+ * 4R acquire fires on the first `store.subscribe`, release on scope disposal).
+ *
+ * Binding pattern (mirrors the React twin): the controller is constructed ONCE
+ * at `setup` (construction is INERT — no subscriptions, no fetch until the first
+ * subscriber), and `useMicroStore` attaches on mount / releases on unmount. `ctx` /
+ * `resource` / `options` are read once at `setup`; to target a different
+ * resource, mount a fresh instance (the Vue analog of React's remount-with-key).
+ */
+import { type ListController, type ListControllerOptions, type ListControllerState, type MicroStore, type RecordOf, type ResourceMap } from "@chelone/core";
+/** Options for {@link useListController}: the core list options + a resource override. */
+export interface UseListControllerOptions extends ListControllerOptions {
+    /** Target a specific resource; defaults to the ambient `<Resource>` name. */
+    resource?: string;
+    /**
+     * Sync list params (filter / sort / page / perPage / displayedFilters) to the
+     * URL query string, ra-core `useListParams`-style: the initial params are
+     * SEEDED from the location on mount (deep-linkable), re-seeded when the
+     * location changes later (back/forward, a followed link), and every param
+     * change is PUSHED back with `replace: true`. Default `true` for a top-level resource
+     * list. Set `false` for an embedded / reference list (mirrors ra-core's
+     * `disableSyncWithLocation`) to keep the pure store/KV behavior.
+     *
+     * Effective only when a `RouterAdapter` is present above the composable;
+     * without one (standalone / many unit tests) the sync degrades to a no-op and
+     * the store/KV behavior is used regardless of this flag.
+     */
+    syncWithLocation?: boolean;
+}
+/**
+ * The reactive result: every field of `ListControllerState` (unwrapped, live)
+ * plus the controller's stable actions (`setPage`/`setSort`/`toggleItem`/…). The
+ * same shape the React twin returns, minus the `MicroStore` plumbing.
+ */
+export type UseListControllerReturn<TRecord> = ListControllerState<TRecord> & Omit<ListController<TRecord>, keyof MicroStore<ListControllerState<TRecord>>>;
+export declare function useListController<TResources extends ResourceMap = ResourceMap, TName extends keyof TResources & string = keyof TResources & string>(options?: UseListControllerOptions): UseListControllerReturn<RecordOf<TResources, TName>>;

package/dist/controllers/use-list-controller.js

@@ -0,0 +1,62 @@
+import { createListController, listPatchFromSearch, serializeListState, listControllerActions } from "@chelone/core";
+import { onScopeDispose, watch, reactive, computed } from "vue";
+import { useCheloneContext } from "../context.js";
+import { useRequiredResource } from "../resource-context.js";
+import { useRouterAdapterOptional } from "../router/adapter.js";
+import { useMicroStore } from "../store/use-micro-store.js";
+import { toControllerContext } from "./controller-context.js";
+function useListController(options = {}) {
+  const ctx = useCheloneContext();
+  const resource = useRequiredResource("useListController", options);
+  const adapter = useRouterAdapterOptional();
+  const syncEnabled = (options.syncWithLocation ?? true) && adapter != null;
+  const location = syncEnabled && adapter ? adapter.useLocation() : null;
+  const navigate = syncEnabled && adapter ? adapter.useNavigate() : null;
+  const controller = createListController(
+    toControllerContext(ctx),
+    resource,
+    options
+  );
+  const seed = location ? listPatchFromSearch(location.value.search) : null;
+  if (seed) controller.setParams(seed);
+  const state = useMicroStore(controller);
+  if (navigate && location) {
+    let lastPushed = serializeListState(controller.getSnapshot());
+    const unsubscribe = controller.subscribe(() => {
+      const search = serializeListState(controller.getSnapshot());
+      if (search === lastPushed) return;
+      lastPushed = search;
+      navigate(`${location.value.pathname}${search}`, { replace: true });
+    });
+    onScopeDispose(unsubscribe);
+    watch(
+      () => location.value.search,
+      (search) => {
+        if (search === lastPushed) return;
+        const patch = listPatchFromSearch(search);
+        if (patch) controller.setParams(patch);
+      }
+    );
+  }
+  return reactive({
+    data: computed(() => state.value.data),
+    total: computed(() => state.value.total),
+    pageInfo: computed(() => state.value.pageInfo),
+    isPending: computed(() => state.value.isPending),
+    isFetching: computed(() => state.value.isFetching),
+    error: computed(() => state.value.error),
+    page: computed(() => state.value.page),
+    perPage: computed(() => state.value.perPage),
+    sort: computed(() => state.value.sort),
+    filter: computed(() => state.value.filter),
+    displayedFilters: computed(() => state.value.displayedFilters),
+    selectedIds: computed(() => state.value.selectedIds),
+    hasNextPage: computed(() => state.value.hasNextPage),
+    hasPreviousPage: computed(() => state.value.hasPreviousPage),
+    ...listControllerActions(controller),
+    defaultPerPage: controller.defaultPerPage
+  });
+}
+export {
+  useListController
+};

package/dist/controllers/use-prev-next-controller.d.ts

@@ -0,0 +1,35 @@
+/**
+ * `usePrevNextController` — the neighbours of the ambient record in the list
+ * the user came from. The Vue twin of `@chelone/react`'s `prev-next-hooks.ts`:
+ * the list's persisted sort and filter, read from the page its query cached, or
+ * from a `limit`-row fetch when that page cannot serve. Needs a record and a
+ * resource in context.
+ *
+ * Composables over pure core functions rather than a `MicroStore` controller:
+ * the record id changes each time the user steps.
+ *
+ * Divergences from the React twin: the options may be a ref or getter, and the
+ * return is a reactive object. The ambient record is injected as a ref and read
+ * inside computeds, so the neighbours follow it; `useRecordContext` unwraps
+ * once, at call time. The store key is read once, in `setup`
+ * (see `useStoreItem`).
+ */
+import { type LooseRecord, type PrevNextOptions } from "@chelone/core";
+import { type MaybeRefOrGetter } from "vue";
+export interface UsePrevNextControllerOptions extends PrevNextOptions {
+    /** Step from this record instead of the ambient one. */
+    record?: LooseRecord;
+}
+export interface UsePrevNextControllerReturn {
+    hasPrev: boolean;
+    hasNext: boolean;
+    prevPath: string | undefined;
+    nextPath: string | undefined;
+    /** Position of the record in the whole list, from 0. */
+    index: number | undefined;
+    total: number | undefined;
+    error: Error | null;
+    isPending: boolean;
+    isFetching: boolean;
+}
+export declare function usePrevNextController(options?: MaybeRefOrGetter<UsePrevNextControllerOptions>): UsePrevNextControllerReturn;

package/dist/controllers/use-prev-next-controller.js

@@ -0,0 +1,75 @@
+import { getPrevNextParams, getListOptions, canUseCachedPage, resolvePrevNext } from "@chelone/core";
+import { useQueryClient, useQuery } from "@tanstack/vue-query";
+import { computed, toValue, inject, reactive } from "vue";
+import { useCheloneContext } from "../context.js";
+import { RecordContextKey } from "../record/record-context.js";
+import { useResourceContext } from "../resource-context.js";
+import { useStoreItem } from "../store/use-store-item.js";
+import { useCreatePath } from "../router/nav-composables.js";
+const FIVE_MINUTES = 5 * 60 * 1e3;
+function usePrevNextController(options = {}) {
+  const opts = computed(() => toValue(options));
+  const resource = useResourceContext();
+  const ambient = inject(RecordContextKey, null);
+  const record = computed(() => opts.value.record ?? ambient?.value);
+  const ctx = useCheloneContext();
+  const queryClient = useQueryClient();
+  const createPath = useCreatePath();
+  const [stored] = useStoreItem(
+    `${opts.value.storeKey || resource}.listParams`
+  );
+  const params = computed(() => getPrevNextParams(stored.value, opts.value));
+  const cachedPage = computed(
+    () => resource ? queryClient.getQueryData(
+      getListOptions(ctx, resource, params.value.cached).queryKey
+    ) : void 0
+  );
+  const pagination = computed(
+    () => params.value.cached.pagination
+  );
+  const canUseCache = computed(
+    () => record.value != null && canUseCachedPage(
+      record.value.id,
+      cachedPage.value,
+      pagination.value.page,
+      pagination.value.perPage
+    )
+  );
+  const query = useQuery(
+    computed(() => ({
+      ...getListOptions(ctx, resource ?? "", params.value.fetch),
+      enabled: !!resource && record.value != null && !canUseCache.value,
+      staleTime: FIVE_MINUTES
+    }))
+  );
+  const resolved = computed(() => {
+    const list = canUseCache.value ? cachedPage.value : query.data.value;
+    if (record.value == null || !list) return void 0;
+    const { page, perPage } = pagination.value;
+    return resolvePrevNext(
+      record.value.id,
+      list.data,
+      list.total,
+      canUseCache.value ? (page - 1) * perPage : 0
+    );
+  });
+  const prevId = computed(() => resolved.value?.prevId ?? null);
+  const nextId = computed(() => resolved.value?.nextId ?? null);
+  const pathTo = (id) => id == null ? void 0 : createPath({ type: opts.value.linkType ?? "edit", resource, id });
+  return reactive({
+    hasPrev: computed(() => prevId.value != null),
+    hasNext: computed(() => nextId.value != null),
+    prevPath: computed(() => pathTo(prevId.value)),
+    nextPath: computed(() => pathTo(nextId.value)),
+    index: computed(() => resolved.value?.index),
+    total: computed(() => resolved.value?.total),
+    error: computed(() => canUseCache.value ? null : query.error.value),
+    isPending: computed(
+      () => record.value == null || !canUseCache.value && query.isPending.value
+    ),
+    isFetching: computed(() => !canUseCache.value && query.isFetching.value)
+  });
+}
+export {
+  usePrevNextController
+};

package/dist/controllers/use-reference-many-field-controller.d.ts

@@ -0,0 +1,46 @@
+/**
+ * `useReferenceManyFieldController` — the Vue bridge for the vanilla core
+ * reference-many controller, the twin of `@chelone/react`'s hook of the same
+ * name (`reference-hooks.ts`): the rows of `reference` whose `target` equals
+ * `record[source]`, paged by the server through `getManyReference`.
+ *
+ * `record` is the `record` option when given, else the ambient record
+ * (`RecordContextKey`). Only the resolved id is live: when it changes (a record
+ * that arrives late or is swapped) a new controller is built for it and the
+ * previous subscription is released. The other options are read at `setup`.
+ * There is no location sync: the list is embedded in a record.
+ */
+import { type FilterPayload, type ListControllerState, type MicroStore, type RecordOf, type ReferenceManyController, type ResourceMap, type SortPayload } from "@chelone/core";
+import { type MaybeRefOrGetter } from "vue";
+import { type RecordValue } from "../record/record-context.js";
+export interface UseReferenceManyFieldControllerOptions<TName extends string = string> {
+    /** The resource whose rows point at the record. */
+    reference: TName;
+    /** The field on `reference` that holds the foreign key. */
+    target: string;
+    /** The field on the record whose value `target` must equal. Default `"id"`. */
+    source?: string;
+    /** Defaults to the ambient record. */
+    record?: MaybeRefOrGetter<RecordValue>;
+    /** Permanent filter, merged over the user filter for every fetch. */
+    filter?: FilterPayload;
+    /** Initial sort when nothing is persisted. Default id ascending. */
+    sort?: SortPayload | SortPayload[];
+    /** Default 25. */
+    perPage?: number;
+    /** KV namespace for params and selection. Default `${reference}.${target}.${id}`; `false` keeps them in memory. */
+    storeKey?: string | false;
+    /** Debounce delay in ms for `setFilters(..., debounced=true)`. Default 500. */
+    debounce?: number;
+    /** Gates the data fetch only. Default true. */
+    enabled?: boolean;
+}
+/** Live controller state plus the controller's stable actions; the shape a list context publishes. */
+export type UseReferenceManyFieldControllerReturn<TRecord> = ListControllerState<TRecord> & Omit<ReferenceManyController<TRecord>, keyof MicroStore<ListControllerState<TRecord>>>;
+/**
+ * The rows of `reference` whose `target` equals `record[source]`, paged by the
+ * server. Returns a reactive view of the controller state plus its stable
+ * actions. A record without a usable id (absent, or not a string or number)
+ * fetches nothing and reads as an empty, settled list.
+ */
+export declare function useReferenceManyFieldController<TResources extends ResourceMap = ResourceMap, TName extends keyof TResources & string = keyof TResources & string>(options: UseReferenceManyFieldControllerOptions<TName>): UseReferenceManyFieldControllerReturn<RecordOf<TResources, TName>>;

package/dist/controllers/use-reference-many-field-controller.js

@@ -0,0 +1,63 @@
+import { createReferenceManyController } from "@chelone/core";
+import { inject, computed, toValue, reactive } from "vue";
+import { useCheloneContext } from "../context.js";
+import { RecordContextKey } from "../record/record-context.js";
+import { toControllerContext } from "./controller-context.js";
+import { foreignKeyOf, useControllerForId } from "./use-controller-for-id.js";
+function useReferenceManyFieldController(options) {
+  const ctx = useCheloneContext();
+  const ambient = inject(RecordContextKey, null);
+  const controllerCtx = toControllerContext(ctx);
+  const source = options.source ?? "id";
+  const id = computed(
+    () => foreignKeyOf(toValue(options.record) ?? ambient?.value, source)
+  );
+  const bound = useControllerForId(
+    id,
+    (value) => createReferenceManyController(controllerCtx, options.reference, {
+      target: options.target,
+      id: value,
+      filter: options.filter,
+      sort: options.sort,
+      perPage: options.perPage,
+      storeKey: options.storeKey,
+      debounceMs: options.debounce,
+      enabled: options.enabled
+    })
+  );
+  const state = computed(() => bound.value.state.value);
+  const action = (key) => ((...args) => bound.value.controller[key](
+    ...args
+  ));
+  return reactive({
+    data: computed(() => state.value.data),
+    total: computed(() => state.value.total),
+    pageInfo: computed(() => state.value.pageInfo),
+    isPending: computed(() => state.value.isPending),
+    isFetching: computed(() => state.value.isFetching),
+    error: computed(() => state.value.error),
+    page: computed(() => state.value.page),
+    perPage: computed(() => state.value.perPage),
+    sort: computed(() => state.value.sort),
+    filter: computed(() => state.value.filter),
+    displayedFilters: computed(() => state.value.displayedFilters),
+    selectedIds: computed(() => state.value.selectedIds),
+    hasNextPage: computed(() => state.value.hasNextPage),
+    hasPreviousPage: computed(() => state.value.hasPreviousPage),
+    setPage: action("setPage"),
+    setPerPage: action("setPerPage"),
+    setSort: action("setSort"),
+    setFilters: action("setFilters"),
+    setParams: action("setParams"),
+    showFilter: action("showFilter"),
+    hideFilter: action("hideFilter"),
+    select: action("select"),
+    toggleItem: action("toggleItem"),
+    unselectAll: action("unselectAll"),
+    selectAll: action("selectAll"),
+    refetch: action("refetch")
+  });
+}
+export {
+  useReferenceManyFieldController
+};

package/dist/controllers/use-reference-one-field-controller.d.ts

@@ -0,0 +1,36 @@
+/**
+ * `useReferenceOneFieldController` — the Vue bridge for the vanilla core
+ * reference-one controller, the twin of `@chelone/react`'s hook of the same
+ * name (`reference-hooks.ts`): the first row of `reference` whose `target`
+ * equals `record[source]`, read through `getManyReference` as a page of one.
+ *
+ * `record` resolves and rebuilds the same way as
+ * {@link useReferenceManyFieldController}: a new id builds a new controller and
+ * releases the previous subscription.
+ */
+import { type FilterPayload, type MicroStore, type RecordOf, type ReferenceOneController, type ReferenceOneControllerState, type ResourceMap, type SortPayload } from "@chelone/core";
+import { type MaybeRefOrGetter } from "vue";
+import { type RecordValue } from "../record/record-context.js";
+export interface UseReferenceOneFieldControllerOptions<TName extends string = string> {
+    /** The resource whose rows point at the record. */
+    reference: TName;
+    /** The field on `reference` that holds the foreign key. */
+    target: string;
+    /** The field on the record whose value `target` must equal. Default `"id"`. */
+    source?: string;
+    /** Defaults to the ambient record. */
+    record?: MaybeRefOrGetter<RecordValue>;
+    /** Decides which row is first when several match. */
+    sort?: SortPayload | SortPayload[];
+    /** Narrows the lookup. */
+    filter?: FilterPayload;
+    /** Gates the fetch. Default true. */
+    enabled?: boolean;
+}
+/** Live lookup state plus the controller's stable `refetch`. */
+export type UseReferenceOneFieldControllerReturn<TRecord> = ReferenceOneControllerState<TRecord> & Omit<ReferenceOneController<TRecord>, keyof MicroStore<ReferenceOneControllerState<TRecord>>>;
+/**
+ * The first row of `reference` whose `target` equals `record[source]`. A record
+ * without a usable id fetches nothing and reads as settled with no record.
+ */
+export declare function useReferenceOneFieldController<TResources extends ResourceMap = ResourceMap, TName extends keyof TResources & string = keyof TResources & string>(options: UseReferenceOneFieldControllerOptions<TName>): UseReferenceOneFieldControllerReturn<RecordOf<TResources, TName>>;

package/dist/controllers/use-reference-one-field-controller.js

@@ -0,0 +1,36 @@
+import { createReferenceOneController } from "@chelone/core";
+import { inject, computed, toValue, reactive } from "vue";
+import { useCheloneContext } from "../context.js";
+import { RecordContextKey } from "../record/record-context.js";
+import { toControllerContext } from "./controller-context.js";
+import { foreignKeyOf, useControllerForId } from "./use-controller-for-id.js";
+function useReferenceOneFieldController(options) {
+  const ctx = useCheloneContext();
+  const ambient = inject(RecordContextKey, null);
+  const controllerCtx = toControllerContext(ctx);
+  const source = options.source ?? "id";
+  const id = computed(
+    () => foreignKeyOf(toValue(options.record) ?? ambient?.value, source)
+  );
+  const bound = useControllerForId(
+    id,
+    (value) => createReferenceOneController(controllerCtx, options.reference, {
+      target: options.target,
+      id: value,
+      sort: options.sort,
+      filter: options.filter,
+      enabled: options.enabled
+    })
+  );
+  const state = computed(() => bound.value.state.value);
+  return reactive({
+    referenceRecord: computed(() => state.value.referenceRecord),
+    isPending: computed(() => state.value.isPending),
+    isFetching: computed(() => state.value.isFetching),
+    error: computed(() => state.value.error),
+    refetch: () => bound.value.controller.refetch()
+  });
+}
+export {
+  useReferenceOneFieldController
+};

package/dist/controllers/use-show-controller.d.ts

@@ -0,0 +1,25 @@
+/**
+ * `useShowController` — the Vue bridge for the vanilla core show controller, the
+ * twin of `@chelone/react`'s `useShowController` (`controller-hooks.ts`). It
+ * fetches ONE record (a `getOne` `QueryObserver` over `ctx.queryClient`) and
+ * exposes it read-only — a show page never mutates, so (unlike
+ * {@link useEditController}) there is no `save`/`saving`.
+ *
+ * The seam is identical to {@link useEditController}: the controller owns the
+ * vanilla `query-core` observer over the vue-query `QueryClient` `<Admin>`
+ * provides; `useMicroStore` is the single subscribe bridge (4R acquire on mount,
+ * release on scope disposal).
+ *
+ * The record `id` defaults to the ambient `:id` route param (read through the
+ * router adapter) when not passed — mirroring how the React `<Show>` view reads
+ * `useParams().id`. Pass `id` explicitly to target a record without a router.
+ */
+import { type MicroStore, type RecordOf, type ResourceMap, type ShowController, type ShowControllerOptions, type ShowControllerState } from "@chelone/core";
+/** Options for {@link useShowController}: the core show options (id optional) + a resource override. */
+export interface UseShowControllerOptions extends Partial<ShowControllerOptions> {
+    /** Target a specific resource; defaults to the ambient `<Resource>` name. */
+    resource?: string;
+}
+/** The reactive result: the show-controller state (unwrapped, live). */
+export type UseShowControllerReturn<TRecord> = ShowControllerState<TRecord> & Omit<ShowController<TRecord>, keyof MicroStore<ShowControllerState<TRecord>>>;
+export declare function useShowController<TResources extends ResourceMap = ResourceMap, TName extends keyof TResources & string = keyof TResources & string>(options?: UseShowControllerOptions): UseShowControllerReturn<RecordOf<TResources, TName>>;