@chelone/vue 0.0.0-stage → 0.1.0

package/dist/array/array-context.d.ts

@@ -0,0 +1,63 @@
+/**
+ * The array-input iterator contexts — the Vue twin of `@chelone/react`'s
+ * `ArrayInputProvider` / `IteratorRowProvider` / `useIteratorItem`
+ * (`array-hooks.ts`). They carry the iterator + per-row op verbs down to an
+ * iterator row, and scope each row's children under `${arraySource}[${index}]`
+ * so a child `<input source="sku">` binds `items[0].sku` (and a sourceless
+ * scalar child binds `tags[0]`).
+ *
+ * Idiom translation from the React twin: React threads two `createContext`
+ * providers (the array iterator + the current row) and wraps children in a
+ * `SourceContextProvider`. Vue `provide`s each under a typed `InjectionKey`;
+ * {@link provideArrayInput} and {@link provideIteratorRow} additionally
+ * `provideSourceScope` (the array's scope, then the row's `[index]` layer) — the
+ * two responsibilities React's `<…Provider>` components fold together. `total`
+ * travels as a reactive ref so a row reading it re-renders on structure changes.
+ */
+import type { ArrayRow } from "@chelone/core";
+import { type InjectionKey, type Ref } from "vue";
+import type { UseArrayInputResult } from "./use-array-input.js";
+/** The iterator + per-row op verbs an iterator row consumes via {@link useIteratorItem}. */
+export interface ArrayInputContextValue {
+    /** The reactive row count. */
+    total: Readonly<Ref<number>>;
+    /** Removes the row at `index`. */
+    remove(index: number): void;
+    /** Moves the row at `from` to `to`. */
+    reOrder(from: number, to: number): void;
+}
+/** The provide/inject key for the ambient array iterator. */
+export declare const ArrayInputContextKey: InjectionKey<ArrayInputContextValue>;
+/**
+ * Provides the array iterator to its rows AND scopes children under the array's
+ * own path (so a scalar `<input source="">` binds the array field). Call in the
+ * array-input component's `setup`, then render one {@link provideIteratorRow}
+ * per row.
+ */
+export declare function provideArrayInput(array: UseArrayInputResult): void;
+/** The provide/inject key for the current iterator row. */
+export declare const IteratorRowContextKey: InjectionKey<ArrayRow>;
+/**
+ * Wraps one iterator row: exposes it to {@link useIteratorItem} and scopes
+ * children under `${arraySource}[${index}]` (labels stay index-free — the row
+ * scope passes labels through unchanged). Call in a row component whose instance
+ * is keyed by `row.id` (NOT the index) so Vue reuses it through reorders,
+ * preserving focus and DOM identity.
+ */
+export declare function provideIteratorRow(row: ArrayRow): void;
+/** What a single iterator row exposes to its children (ra's iterator item). */
+export interface IteratorItem {
+    /** The row's current position. */
+    index: number;
+    /** The reactive total row count. */
+    total: Readonly<Ref<number>>;
+    /** Removes THIS row. */
+    remove(): void;
+    /** Moves THIS row to `newIndex`. */
+    reOrder(newIndex: number): void;
+}
+/**
+ * The current iterator row: `{ index, total, remove, reOrder }`. Throws outside a
+ * {@link provideIteratorRow}. `remove`/`reOrder` act on THIS row.
+ */
+export declare function useIteratorItem(): IteratorItem;

package/dist/array/array-context.js

@@ -0,0 +1,51 @@
+import { createRowSourceScope } from "@chelone/core";
+import { provide, inject } from "vue";
+import { provideSourceScope, useSourceScope } from "../form/form-context.js";
+const ArrayInputContextKey = /* @__PURE__ */ Symbol("chelone-array-input-context");
+function provideArrayInput(array) {
+  provide(ArrayInputContextKey, {
+    total: array.total,
+    remove: array.remove,
+    reOrder: array.reOrder
+  });
+  provideSourceScope(array.scope);
+}
+function useArrayInputContext() {
+  const ctx = inject(ArrayInputContextKey, null);
+  if (!ctx) {
+    throw new Error(
+      "useIteratorItem: no provideArrayInput() found above this row."
+    );
+  }
+  return ctx;
+}
+const IteratorRowContextKey = /* @__PURE__ */ Symbol(
+  "chelone-iterator-row"
+);
+function provideIteratorRow(row) {
+  const parentScope = useSourceScope();
+  provide(IteratorRowContextKey, row);
+  provideSourceScope(createRowSourceScope(parentScope, row.index));
+}
+function useIteratorItem() {
+  const row = inject(IteratorRowContextKey, null);
+  if (!row) {
+    throw new Error(
+      "useIteratorItem: no provideIteratorRow() found above this component."
+    );
+  }
+  const array = useArrayInputContext();
+  return {
+    index: row.index,
+    total: array.total,
+    remove: () => array.remove(row.index),
+    reOrder: (newIndex) => array.reOrder(row.index, newIndex)
+  };
+}
+export {
+  ArrayInputContextKey,
+  IteratorRowContextKey,
+  provideArrayInput,
+  provideIteratorRow,
+  useIteratorItem
+};

package/dist/array/index.d.ts

@@ -0,0 +1,4 @@
+export type { ArrayInputContextValue, IteratorItem, } from "./array-context.js";
+export { ArrayInputContextKey, IteratorRowContextKey, provideArrayInput, provideIteratorRow, useIteratorItem, } from "./array-context.js";
+export type { ArrayFieldState, UseArrayInputOptions, UseArrayInputResult, } from "./use-array-input.js";
+export { useArrayInput } from "./use-array-input.js";

package/dist/array/use-array-input.d.ts

@@ -0,0 +1,55 @@
+/**
+ * `useArrayInput` — the array-input workhorse, the Vue twin of `@chelone/react`'s
+ * `useArrayInput` (`array-hooks.ts`, ra's ArrayInput iterator rebridged onto
+ * form-core arrays). It binds ONE array field to the ambient form through a
+ * vanilla {@link ArrayBinding}, exposing stable-id rows plus the ra iterator op
+ * verbs (add/insert/replace/remove/swap/reOrder/clear) and the array field's own
+ * error state.
+ *
+ * Idiom translation from the React twin: React holds the binding in `useState`
+ * and recreates it on form/source change, drives the 4R attach via a constant
+ * `useSyncExternalStore`, and reads rows/total through a STRUCTURAL
+ * `useSyncExternalStore` (re-renders only on row-set changes, never on row value
+ * edits). Vue's `setup` runs once with a stable form + source, so the binding is
+ * constructed once; the structural `subscribe` drives both the 4R attach (first
+ * subscriber mounts the array field) AND the row/total `shallowRef`s — because
+ * `getRows()` is reference-stable between structure changes, assigning the same
+ * cached array is a no-op, so a row value edit never re-renders the iterator. The
+ * array field's error/meta ride a separate {@link useSubscribable} over the field
+ * binding, projected through `computed`.
+ */
+import type { ArrayBindingUpdateOptions, ArrayRow, SourceScope, TranslatableMessage } from "@chelone/core";
+import { type ComputedRef, type Ref } from "vue";
+export interface UseArrayInputOptions extends ArrayBindingUpdateOptions {
+    /** The array field path RELATIVE to the ambient source scope. */
+    source: string;
+}
+/** The array field's own reactive error state (min-length validators, etc.). */
+export interface ArrayFieldState {
+    invalid: ComputedRef<boolean>;
+    isTouched: ComputedRef<boolean>;
+    isDirty: ComputedRef<boolean>;
+    /** The first array-field error, normalized to a displayable/translatable payload. */
+    error: ComputedRef<string | TranslatableMessage | undefined>;
+}
+/** ra-parity iterator surface: the reactive row set plus the op verbs. */
+export interface UseArrayInputResult {
+    /** The array field path (final, source-scoped). */
+    source: string;
+    /** Stable-id rows — reference-stable until the row STRUCTURE changes. */
+    rows: Readonly<Ref<readonly ArrayRow[]>>;
+    /** The current row count. */
+    total: Readonly<Ref<number>>;
+    /** The scope children bind under (the array's own path). */
+    scope: SourceScope;
+    /** Appends a row (scalar `''`, object first-row-keys-nulled + defaults). */
+    add(item?: unknown): void;
+    insert(index: number, item?: unknown): void;
+    replace(index: number, item: unknown): void;
+    remove(index: number): void;
+    swap(indexA: number, indexB: number): void;
+    reOrder(from: number, to: number): void;
+    clear(): void;
+    fieldState: ArrayFieldState;
+}
+export declare function useArrayInput(options: UseArrayInputOptions): UseArrayInputResult;

package/dist/array/use-array-input.js

@@ -0,0 +1,59 @@
+import { createArrayBinding, createArraySourceScope } from "@chelone/core";
+import { shallowRef, onScopeDispose, watchEffect, computed } from "vue";
+import { firstFieldError } from "../form/field-error.js";
+import { useCheloneFormContext, useSourceScope } from "../form/form-context.js";
+import { useSubscribable } from "../form/subscribe-ref.js";
+function toBindingUpdate(options) {
+  return {
+    defaultValue: options.defaultValue,
+    scalar: options.scalar,
+    itemDefaults: options.itemDefaults,
+    validate: options.validate,
+    schema: options.schema,
+    validatorMeta: options.validatorMeta
+  };
+}
+function useArrayInput(options) {
+  const { form } = useCheloneFormContext();
+  const parentScope = useSourceScope();
+  const source = parentScope.getSource(options.source);
+  const binding = createArrayBinding(form, {
+    ...toBindingUpdate(options),
+    source
+  });
+  const rows = shallowRef(binding.getRows());
+  const total = shallowRef(binding.getTotal());
+  const unsubscribe = binding.subscribe(() => {
+    rows.value = binding.getRows();
+    total.value = binding.getTotal();
+  });
+  onScopeDispose(unsubscribe);
+  const fieldState = useSubscribable(
+    binding.field
+  );
+  watchEffect(() => binding.update(toBindingUpdate(options)));
+  const scope = createArraySourceScope(parentScope, options.source);
+  const error = computed(() => firstFieldError(fieldState.value.meta.errorMap));
+  return {
+    source,
+    rows,
+    total,
+    scope,
+    add: binding.add,
+    insert: binding.insert,
+    replace: binding.replace,
+    remove: binding.remove,
+    swap: binding.swap,
+    reOrder: binding.reOrder,
+    clear: binding.clear,
+    fieldState: {
+      invalid: computed(() => error.value !== void 0),
+      isTouched: computed(() => fieldState.value.meta.isTouched),
+      isDirty: computed(() => fieldState.value.meta.isDirty),
+      error
+    }
+  };
+}
+export {
+  useArrayInput
+};

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

@@ -0,0 +1,68 @@
+/**
+ * Auth composables over `@tanstack/vue-query` — the Vue twin of
+ * `@chelone/react`'s `auth-hooks.ts` (`useGetIdentity` / `useAuthState` /
+ * `useLogout`). Each wraps core's framework-agnostic query/mutation options
+ * (`identityQueryOptions` / `authStateQueryOptions`) around the ambient
+ * `authProvider`, reusing the SAME vue-query client `<Admin>` installs under
+ * `VUE_QUERY_CLIENT`.
+ *
+ * The V3-a app shell ported the three the shell needs (`useGetIdentity` /
+ * `useAuthState` / `useLogout`); the V3-c auth wave adds the login mutation
+ * (`useLogin`) and the access check (`useCanAccess`) the login page + gate
+ * consume. `useCheloneAuthProvider` throws when no provider is configured (parity
+ * with the React twin), so every one of these must run past an authProvider
+ * guard — `<UserMenu>` mounts its identity-reading body only when a provider is
+ * present, exactly as the React twin isolates the read.
+ */
+import { type CanAccessParams, type UserIdentity } from "@chelone/core";
+import { type ComputedRef } from "vue";
+/** Read the authenticated user's identity (`getIdentity`) as a vue-query query. */
+export declare function useGetIdentity(): import("@tanstack/vue-query").UseQueryReturnType<UserIdentity, Error>;
+export interface UseOptionalIdentityResult {
+    /** The signed-in identity (`undefined` until resolved, or when unavailable). */
+    identity: ComputedRef<UserIdentity | undefined>;
+    /** Whether the identity query is in flight (false when unavailable). */
+    isPending: ComputedRef<boolean>;
+}
+/**
+ * Read the signed-in identity without requiring an `authProvider` — the Vue twin
+ * of the React `useOptionalIdentity`. Unlike {@link useGetIdentity}, which
+ * THROWS without a provider, this yields `identity: undefined` and
+ * `isPending: false` when there is no provider or it has no `getIdentity`, and
+ * when `getIdentity` rejects. It shares `useGetIdentity`'s query key, so both
+ * read one cached call.
+ */
+export declare function useOptionalIdentity(): UseOptionalIdentityResult;
+/**
+ * Read the current auth state (`checkAuth` → `{ authenticated }`) as a vue-query
+ * query. Never rejects — a `checkAuth` rejection maps to `authenticated: false`.
+ */
+export declare function useAuthState(): import("@tanstack/vue-query").UseQueryReturnType<{
+    authenticated: boolean;
+}, Error>;
+/**
+ * A login mutation — calls the provider's `login(params)` on `mutate(...)` /
+ * `mutateAsync(...)`. The Vue twin of the React `useLogin`; `<LoginForm>` calls
+ * `mutateAsync(credentials)` and catches a rejection to surface an auth-error
+ * notification (the form `save` contract must resolve, never reject).
+ */
+export declare function useLogin(): import("@tanstack/vue-query").UseMutationReturnType<void | {
+    redirectTo?: string;
+}, Error, Record<string, unknown>, unknown, Omit<import("@tanstack/query-core").MutationObserverIdleResult<void | {
+    redirectTo?: string;
+}, Error, Record<string, unknown>, unknown>, "reset" | "mutate"> | Omit<import("@tanstack/query-core").MutationObserverLoadingResult<void | {
+    redirectTo?: string;
+}, Error, Record<string, unknown>, unknown>, "reset" | "mutate"> | Omit<import("@tanstack/query-core").MutationObserverErrorResult<void | {
+    redirectTo?: string;
+}, Error, Record<string, unknown>, unknown>, "reset" | "mutate"> | Omit<import("@tanstack/query-core").MutationObserverSuccessResult<void | {
+    redirectTo?: string;
+}, Error, Record<string, unknown>, unknown>, "reset" | "mutate">>;
+/** A logout mutation — calls the provider's `logout(params)` on `mutate(...)`. */
+export declare function useLogout(): import("@tanstack/vue-query").UseMutationReturnType<string | void, Error, unknown, unknown, Omit<import("@tanstack/query-core").MutationObserverIdleResult<string | void, Error, unknown, unknown>, "reset" | "mutate"> | Omit<import("@tanstack/query-core").MutationObserverLoadingResult<string | void, Error, unknown, unknown>, "reset" | "mutate"> | Omit<import("@tanstack/query-core").MutationObserverErrorResult<string | void, Error, unknown, unknown>, "reset" | "mutate"> | Omit<import("@tanstack/query-core").MutationObserverSuccessResult<string | void, Error, unknown, unknown>, "reset" | "mutate">>;
+/**
+ * Read whether the current user may perform `action` on `resource` (+ optional
+ * `record`) as a vue-query query — the Vue twin of the React `useCanAccess`.
+ * Defaults to granted when the provider omits `canAccess` (via
+ * `canAccessQueryOptions`).
+ */
+export declare function useCanAccess(params: CanAccessParams): import("@tanstack/vue-query").UseQueryReturnType<boolean, Error>;

package/dist/auth/auth-hooks.js

@@ -0,0 +1,54 @@
+import { authStateQueryOptions, identityQueryOptions, canAccessQueryOptions } from "@chelone/core";
+import { useQuery, useMutation } from "@tanstack/vue-query";
+import { computed } from "vue";
+import { useCheloneAuthProvider, useCheloneContext } from "../context.js";
+function useGetIdentity() {
+  return useQuery(identityQueryOptions(useCheloneAuthProvider()));
+}
+function useOptionalIdentity() {
+  const { authProvider } = useCheloneContext();
+  const hasGetIdentity = authProvider?.getIdentity != null;
+  const query = useQuery({
+    // A stub provider satisfies the option factory's type when none is
+    // configured; the query is disabled in that case so it never runs.
+    ...identityQueryOptions(
+      authProvider ?? {}
+    ),
+    enabled: hasGetIdentity
+  });
+  return {
+    // A disabled query reports `isPending: true`; a rejected one has no data.
+    identity: computed(
+      () => !hasGetIdentity || query.isError.value ? void 0 : query.data.value
+    ),
+    isPending: computed(
+      () => !hasGetIdentity || query.isError.value ? false : query.isPending.value
+    )
+  };
+}
+function useAuthState() {
+  return useQuery(authStateQueryOptions(useCheloneAuthProvider()));
+}
+function useLogin() {
+  const authProvider = useCheloneAuthProvider();
+  return useMutation({
+    mutationFn: (params) => authProvider.login(params)
+  });
+}
+function useLogout() {
+  const authProvider = useCheloneAuthProvider();
+  return useMutation({
+    mutationFn: (params) => authProvider.logout(params)
+  });
+}
+function useCanAccess(params) {
+  return useQuery(canAccessQueryOptions(useCheloneAuthProvider(), params));
+}
+export {
+  useAuthState,
+  useCanAccess,
+  useGetIdentity,
+  useLogin,
+  useLogout,
+  useOptionalIdentity
+};

package/dist/auth/permissions-hooks.d.ts

@@ -0,0 +1,76 @@
+/**
+ * R2 permissions / access composables — the Vue twin of the React adapter's
+ * `usePermissions` / `useLogoutIfAccessDenied` / `useWatchDataErrors`
+ * (`@chelone/react`'s `auth-hooks.ts`). Each wraps the additive, framework-
+ * agnostic core pieces (`permissionsQueryOptions` / `checkError`) around the
+ * ambient `authProvider`, reusing the SAME vue-query client `<Admin>` installs.
+ *
+ * Idiom translation from the React twin: React re-derives its result object each
+ * render and runs the data-error subscription in a `useEffect`; Vue returns
+ * `ComputedRef`s off the vue-query result refs (template-reactive) and runs the
+ * cache subscription in `setup` with an `onScopeDispose` teardown.
+ */
+import { type ComputedRef } from "vue";
+/** The result of {@link usePermissions} (reactive refs). */
+export interface UsePermissionsResult<PermissionsType = unknown> {
+    /** The current user's permissions (`undefined` until resolved / unconfigured). */
+    permissions: ComputedRef<PermissionsType | undefined>;
+    /** Whether the permissions query is in flight (always `false` when unconfigured). */
+    isPending: ComputedRef<boolean>;
+    /** The error, if the provider's `getPermissions` rejected. */
+    error: ComputedRef<unknown>;
+    /** Re-run the permissions query. */
+    refetch: () => void;
+}
+/** Options for {@link usePermissions}. */
+export interface UsePermissionsOptions {
+    /** Query stale time (ms). Defaults to 5 minutes. */
+    staleTime?: number;
+    /** Disable the query entirely (default `true`). */
+    enabled?: boolean;
+}
+/**
+ * Fetch the current user's permissions via `authProvider.getPermissions`
+ * (R2 parity with ra-core's `usePermissions`). Undefined-tolerant and no-throw:
+ *
+ * - No `authProvider`, or no `getPermissions` on it → `{ permissions: undefined,
+ *   isPending: false }` (access control / permissions not configured).
+ * - Otherwise wraps {@link permissionsQueryOptions} via vue-query.
+ *
+ * Unlike {@link useCanAccess}/{@link useGetIdentity} (which THROW without a
+ * provider), this degrades gracefully so a no-auth app can call it to gate
+ * optional features.
+ */
+export declare function usePermissions<PermissionsType = unknown>(params?: unknown, options?: UsePermissionsOptions): UsePermissionsResult<PermissionsType>;
+/** The callback returned by {@link useLogoutIfAccessDenied}. */
+export type LogoutIfAccessDenied = (error?: unknown) => Promise<boolean>;
+/**
+ * Returns a callback that runs `authProvider.checkError(error)` against a
+ * data/mutation error and, if the session is invalid (checkError REJECTS), logs
+ * the user out, notifies, and redirects to the login page (R2 parity with
+ * ra-core's `useLogoutIfAccessDenied`).
+ *
+ * Fail-safe by construction:
+ * - No `authProvider` → no-op, resolves `false`.
+ * - checkError RESOLVES (an ordinary data error) → no-op, resolves `false`.
+ * - checkError REJECTS → logout + notify + redirect, resolves `true`. Only an
+ *   auth rejection ever logs the user out; ordinary data errors never do.
+ *
+ * The reject payload's hints (`redirectTo`, `logoutUser`, `message`) are honored
+ * via the vanilla core {@link checkError} triage: `logoutUser: false` downgrades
+ * to a "not authorized" notice + optional redirect without ending the session;
+ * `message: false` suppresses the notification.
+ */
+export declare function useLogoutIfAccessDenied(): LogoutIfAccessDenied;
+/**
+ * Wire `checkError` → auto-logout into the DATA ERROR PATH (R2). Subscribes to
+ * the shared QueryClient's query + mutation caches and, on every settled error,
+ * runs {@link useLogoutIfAccessDenied} — so a 401/403 surfaced by the
+ * dataProvider auto-logs-out (checkError rejects) while an ordinary data error is
+ * left alone (checkError resolves).
+ *
+ * Auth-subsystem queries (`["auth", …]` — checkAuth / canAccess / getIdentity /
+ * getPermissions) are skipped to avoid feedback loops. A no-op without an
+ * `authProvider`. Mounted once by `<AdminShell>` (inside `<Admin>`'s context).
+ */
+export declare function useWatchDataErrors(): void;

package/dist/auth/permissions-hooks.js

@@ -0,0 +1,106 @@
+import { checkError, permissionsQueryOptions } from "@chelone/core";
+import { useQueryClient, useMutation, useQuery } from "@tanstack/vue-query";
+import { onScopeDispose, computed } from "vue";
+import { useCheloneContext } from "../context.js";
+import { useRedirectOptional } from "../router/nav-composables.js";
+function usePermissions(params, options = {}) {
+  const { authProvider } = useCheloneContext();
+  const hasGetPermissions = authProvider?.getPermissions != null;
+  const query = useQuery({
+    ...permissionsQueryOptions(
+      // A stub provider satisfies the option factory's type when none is
+      // configured; the query is disabled in that case so it never runs.
+      authProvider ?? {},
+      params
+    ),
+    staleTime: options.staleTime ?? 5 * 60 * 1e3,
+    enabled: (options.enabled ?? true) && hasGetPermissions
+  });
+  return {
+    // No provider / no getPermissions → permissions not configured. Vue-query
+    // reports a disabled query as `isPending: true` (fetchStatus idle); the
+    // undefined-tolerant contract must win over that.
+    permissions: computed(
+      () => hasGetPermissions ? query.data.value : void 0
+    ),
+    isPending: computed(
+      () => hasGetPermissions ? query.isPending.value : false
+    ),
+    error: computed(() => hasGetPermissions ? query.error.value : null),
+    refetch: () => {
+      void query.refetch();
+    }
+  };
+}
+const DEFAULT_LOGIN_PATH = "/login";
+let logoutTimer;
+function handleRedirect(redirect, url) {
+  if (url.startsWith("http") && typeof window !== "undefined") {
+    window.location.href = url;
+  } else {
+    redirect(() => url);
+  }
+}
+function useLogoutIfAccessDenied() {
+  const { authProvider, notifications } = useCheloneContext();
+  const logout = useMutation({
+    mutationFn: (params) => authProvider?.logout(params) ?? Promise.resolve()
+  });
+  const redirect = useRedirectOptional();
+  return async (error) => {
+    if (!authProvider) return false;
+    const outcome = await checkError(authProvider, error);
+    if (!outcome.logout) return false;
+    if (logoutTimer) return true;
+    logoutTimer = setTimeout(() => {
+      logoutTimer = void 0;
+    }, 0);
+    const { logoutUser, redirectTo, message } = outcome;
+    const isHttpRedirect = redirectTo?.startsWith("http") ?? false;
+    const shouldNotify = message !== false && !isHttpRedirect;
+    if (shouldNotify && notifications) {
+      notifications.notify(
+        typeof message === "string" ? message : logoutUser ? "chelone.notification.logged_out" : "chelone.notification.not_authorized",
+        { type: "error" }
+      );
+    }
+    if (logoutUser) {
+      logout.mutate(redirectTo != null ? { redirectTo } : void 0);
+      handleRedirect(redirect, redirectTo ?? DEFAULT_LOGIN_PATH);
+    } else if (redirectTo) {
+      handleRedirect(redirect, redirectTo);
+    }
+    return true;
+  };
+}
+function isAuthQueryKey(key) {
+  return Array.isArray(key) && key[0] === "auth";
+}
+function useWatchDataErrors() {
+  const queryClient = useQueryClient();
+  const { authProvider } = useCheloneContext();
+  const logoutIfAccessDenied = useLogoutIfAccessDenied();
+  if (!authProvider) return;
+  const queryCache = queryClient.getQueryCache();
+  const mutationCache = queryClient.getMutationCache();
+  const unsubQueries = queryCache.subscribe((event) => {
+    if (event.type !== "updated") return;
+    if (event.action.type !== "error") return;
+    if (isAuthQueryKey(event.query.queryKey)) return;
+    void logoutIfAccessDenied(event.action.error);
+  });
+  const unsubMutations = mutationCache.subscribe((event) => {
+    if (event.type !== "updated") return;
+    if (event.action.type !== "error") return;
+    void logoutIfAccessDenied(event.action.error);
+  });
+  onScopeDispose(() => {
+    unsubQueries();
+    unsubMutations();
+  });
+}
+export {
+  useLogoutIfAccessDenied,
+  usePermissions,
+  useWatchDataErrors
+};

package/dist/choices/choices-context.d.ts

@@ -0,0 +1,85 @@
+/**
+ * The unified choices context (ra's `ChoicesContext` / `useChoicesContext`), the
+ * Vue twin of `@chelone/react`'s `ChoicesContextProvider` + `useChoicesContext`
+ * (`choices-hooks.ts`). A reference-backed controller (live list — see
+ * {@link useReferenceInput}) OR a synthesized inline-choices list share ONE
+ * shape; `isFromReference` distinguishes them, and the list-mutation actions are
+ * inert no-ops on an inline context.
+ *
+ * Idiom translation from the React twin: React threads the value through a
+ * `createContext` provider + `useContext`; the inline path synthesizes a static
+ * context inside `ChoicesContextProvider`/`useChoicesContext`. Vue `provide`s the
+ * value under a typed `InjectionKey` and reads it with `inject`. The reference
+ * context carries its reactive data through GETTERS (see {@link useReferenceInput})
+ * so a plain property read tracks the controller store — Vue's answer to React
+ * re-deriving the object each render. The inline context is a frozen plain object.
+ */
+import type { FilterPayload, SortPayload } from "@chelone/core";
+import { type InjectionKey } from "vue";
+import type { ChoiceRecord } from "./use-choices.js";
+/**
+ * The choices context every choice input consumes. A reference context fills the
+ * data fields through getters (reactive); an inline context is static. The
+ * list-mutation actions are inert on an inline context.
+ */
+export interface ChoicesContextValue {
+    allChoices: ChoiceRecord[];
+    availableChoices: ChoiceRecord[];
+    selectedChoices: ChoiceRecord[];
+    total: number | undefined;
+    isPending: boolean;
+    isFetching: boolean;
+    error: unknown;
+    page: number;
+    perPage: number;
+    sort: SortPayload;
+    filter: FilterPayload;
+    hasNextPage: boolean | undefined;
+    hasPreviousPage: boolean | undefined;
+    /** The referenced resource name (inline: `undefined`). */
+    resource: string | undefined;
+    /** The FK/source field on the referencing side. */
+    source: string | undefined;
+    /** `true` for a reference context, `false` for an inline-choices context. */
+    isFromReference: boolean;
+    setPage(page: number): void;
+    setPerPage(perPage: number): void;
+    setSort(sort: SortPayload): void;
+    setFilters(filter: FilterPayload, debounce?: boolean): void;
+    setValue(value: unknown): void;
+    refetch(): void;
+}
+/**
+ * A static context over inline choices (ra parity): the full list IS every view,
+ * pagination is off, `isFromReference` is false, and the list-mutation actions
+ * are inert.
+ */
+export declare function synthesizeInlineChoices(choices: readonly (string | ChoiceRecord)[], source?: string): ChoicesContextValue;
+/** Inline-choices config for {@link provideChoicesContext}. */
+export interface InlineChoicesConfig {
+    choices: readonly (string | ChoiceRecord)[];
+    source?: string;
+}
+/** The provide/inject key for the ambient choices context. */
+export declare const ChoicesContextKey: InjectionKey<ChoicesContextValue>;
+/**
+ * Provides an ambient {@link ChoicesContextValue} to choice inputs below (the
+ * Vue analog of React's `<ChoicesContextProvider>`). Accepts either a live
+ * context (from {@link useReferenceInput}) or an inline-choices config that it
+ * synthesizes into a static context. Call in `setup`.
+ */
+export declare function provideChoicesContext(value: ChoicesContextValue | InlineChoicesConfig): void;
+/** Options for {@link useChoicesContext} (props-over-context: inline choices win). */
+export interface UseChoicesContextOptions {
+    /** Inline choices — synthesized into a static context, ignoring any ambient one. */
+    choices?: readonly (string | ChoiceRecord)[];
+    /** The FK/source field (metadata carried onto the synthesized context). */
+    source?: string;
+}
+/**
+ * Resolves the choices context (ra's `useChoicesContext`, props-over-context):
+ * inline `choices` synthesize a static context; otherwise the ambient
+ * {@link provideChoicesContext} value is returned. Throws if neither is present.
+ * Call in `setup`.
+ */
+export declare function useChoicesContext(options?: UseChoicesContextOptions): ChoicesContextValue;