attaform 0.0.1 → 0.14.0

package/dist/shared/attaform.BYc9kugA.d.ts

@@ -0,0 +1,124 @@
+import { G as GenericForm, F as FormKey, d as UseFormReturnType, R as RegisterValue } from './attaform.DDXrY-1Q.js';
+import { ComputedRef } from 'vue';
+
+/**
+ * Access an existing form from a descendant component without passing
+ * it through props. Counterpart to `useForm` — `useForm` creates and
+ * provides; `injectForm` looks up via Vue's inject mechanism.
+ *
+ * Two ways to call it:
+ *
+ * ```ts
+ * // Reach the nearest ancestor's anonymous useForm() call.
+ * const form = injectForm<SignupShape>()
+ *
+ * // Reach a specific form by its key — works from anywhere in the app.
+ * const cart = injectForm<CartShape>('cart')
+ * ```
+ *
+ * Resolution rules (no-key form):
+ * - Closest ambient ancestor wins.
+ * - Only anonymous `useForm()` (no `key`) fills the ambient slot;
+ *   keyed forms are reachable only via `injectForm(key)`.
+ * - Inherits the resolved ancestor's `formInstanceId`.
+ *
+ * Resolution rules (keyed form): registry lookup by string key,
+ * independent of component-tree position.
+ *
+ * Returns `null` when no matching form exists (no ambient ancestor, or
+ * the named key isn't registered). A dev-mode warning points at the
+ * call site to help diagnose typos. Always narrow before using:
+ *
+ * ```ts
+ * const form = injectForm<Shape>('signup')
+ * if (!form) return
+ * form.register('email')
+ * ```
+ *
+ * Pass the `Form` generic explicitly — Vue's provide/inject erases
+ * generics, so the library can't recover the shape automatically.
+ *
+ * The form is kept alive for this component's lifetime; once every
+ * consumer unmounts, the form is cleaned up automatically.
+ */
+declare function injectForm<Form extends GenericForm, GetValueFormType extends GenericForm = Form>(key?: FormKey): UseFormReturnType<Form, GetValueFormType> | null;
+
+/**
+ * Re-bind a parent's `v-register` onto an inner native element. Use
+ * inside a component that wraps a single form field whose root is
+ * NOT the input itself (e.g. a labelled-row that renders `<label>`
+ * around the input).
+ *
+ * ```vue
+ * <!-- Parent -->
+ * <MyInput v-register="form.register('email')" />
+ *
+ * <!-- MyInput.vue -->
+ * <script setup lang="ts">
+ *   import { useRegister } from 'attaform'
+ *   const register = useRegister()
+ * </script>
+ *
+ * <template>
+ *   <label class="field">
+ *     <span>Email</span>
+ *     <input v-register="register" />
+ *   </label>
+ * </template>
+ * ```
+ *
+ * Returns a `ComputedRef<RegisterValue | undefined>`. The directive
+ * handles `undefined` gracefully (silent no-op assigner, no listener
+ * attachment), so always pass the result to `v-register` directly.
+ *
+ * Diagnostic: in dev mode, a single `console.warn` fires per instance
+ * at `onMounted` if the captured value is still `undefined` — by then
+ * the parent has had its full mount lifecycle to bind, so a missing
+ * binding is conclusive misuse. The warn does NOT fire on every read
+ * of the computed, and is intentionally silent under SSR
+ * (`renderToString` skips `onMounted`); the CSR hydration pass
+ * surfaces the same diagnostic without double-counting through Nuxt's
+ * `dev:ssr-logs` channel.
+ *
+ * When the wrapper's root IS the input itself, Vue's attribute
+ * fallthrough handles the binding and `useRegister` is unnecessary.
+ * For wrappers that bind multiple fields (compound forms), use
+ * `injectForm<Form>(key?)` and call `ctx.register(...)` directly.
+ */
+
+declare function useRegister(): ComputedRef<RegisterValue | undefined>;
+
+/**
+ * Stable identifiers for library-emitted `ValidationError` codes.
+ *
+ * Convention: `<scope>:<kebab-case-identifier>`. Three scopes are
+ * recognised by the library:
+ *
+ * - `atta:` — emitted by the framework-agnostic core (this map).
+ * - `zod:` — emitted by the Zod adapter; computed inline from
+ *   `issue.code` (e.g. `zod:too_small`). No enum here because
+ *   Zod's code list evolves.
+ * - consumer-defined — anything the consumer's backend / app stamps
+ *   onto a `ValidationError` (via the `parseApiErrors` wire payload
+ *   or `setFieldErrors` directly). Pick a scope (`api:`, `auth:`,
+ *   etc.) and stay consistent.
+ *
+ * Use these constants in tests and error-routing UI:
+ *
+ * ```ts
+ * if (error.code === AttaformErrorCode.NoValueSupplied) {
+ *   // user hasn't filled this field
+ * }
+ * ```
+ */
+declare const AttaformErrorCode: {
+    /** A required field is in the blank set — user hasn't supplied a value. */
+    readonly NoValueSupplied: "atta:no-value-supplied";
+    /** The schema adapter's `validateAtPath` threw synchronously. */
+    readonly AdapterThrew: "atta:adapter-threw";
+    /** The supplied path didn't resolve to any node in the schema. */
+    readonly PathNotFound: "atta:path-not-found";
+};
+type AttaformErrorCode = (typeof AttaformErrorCode)[keyof typeof AttaformErrorCode];
+
+export { AttaformErrorCode as A, injectForm as i, useRegister as u };