@ozura/elements 1.3.1-next.77 → 1.3.1-next.79

package/README.md

@@ -28,6 +28,7 @@ Card data is collected inside Ozura-hosted iframes so raw numbers never touch yo
   - [vault.createBankToken()](#vaultcreatebanktokenoptions)
   - [vault.reset()](#vaultreset)
   - [vault.destroy()](#vaultdestroy)
+  - [vault.getFieldStates()](#vaultgetfieldstates)
   - [vault.debugState()](#vaultdebugstate)
   - [OzElement events](#ozelement-events)
 - [React API](#react-api)
@@ -36,6 +37,7 @@ Card data is collected inside Ozura-hosted iframes so raw numbers never touch yo
   - [Individual field components](#individual-field-components)
   - [OzBankCard](#ozbankcard)
   - [useOzElements()](#useozelements)
+  - [useFieldStates()](#usefieldstates)
 - [Styling](#styling)
   - [Per-element styles](#per-element-styles)
   - [Global appearance](#global-appearance)
@@ -595,6 +597,29 @@ try {
 
 ---
 
+### vault.getFieldStates()
+
+```ts
+vault.getFieldStates(): FieldStatesSnapshot
+```
+
+Returns a snapshot of every created field's current state, keyed by element type. Each entry is `{ empty, complete, valid, error?, cardBrand? }`. Call it whenever you need the latest state — typically from an `OzElement` `change` listener — to gate the submit button, show per-field errors, or display the card brand, without wiring bookkeeping per field.
+
+```ts
+cardNumber.on('change', () => {
+  const s = vault.getFieldStates();
+  // {
+  //   cardNumber: { empty: false, complete: true,  valid: true,  cardBrand: 'visa' },
+  //   cvv:        { empty: false, complete: false, valid: false, error: 'Invalid CVV' },
+  // }
+  payBtn.disabled = !(s.cardNumber?.valid && s.expirationDate?.valid && s.cvv?.valid);
+});
+```
+
+Keys exist only for fields you have created (card and bank fields are combined), so access with `?.`. The result is a set of shallow copies — mutating it does not affect the vault. In React/Vue, prefer the reactive [`useFieldStates()`](#usefieldstates) instead of calling this on every change.
+
+---
+
 ### vault.debugState()
 
 ```ts
@@ -785,7 +810,7 @@ import { OzBankAccountNumber, OzBankRoutingNumber } from '@ozura/elements/react'
 ### useOzElements()
 
 ```ts
-const { createToken, createBankToken, reset, ready, initError, tokenizeCount } = useOzElements();
+const { createToken, createBankToken, reset, ready, initError, tokenizeCount, isComplete, isBankComplete, isTokenizing } = useOzElements();
 ```
 
 Must be called from inside an `<OzElements>` provider tree.
@@ -798,11 +823,41 @@ Must be called from inside an `<OzElements>` provider tree.
 | `ready` | `boolean` | `true` when the tokenizer **and** all mounted element iframes are ready. Gate your submit button on this. See note below. |
 | `initError` | `Error \| null` | Non-null if `OzVault.create()` failed (e.g. session endpoint unreachable). Render a fallback UI. |
 | `tokenizeCount` | `number` | Number of successful tokenizations in the current session. Resets on session refresh or provider re-init. Useful for tracking calls against `sessionLimit`. |
+| `isComplete` | `boolean` | `true` when every mounted **card** field reports complete and valid. Gate the pay button on it without wiring per-field `onChange`. Reactive — updates as the customer types. |
+| `isBankComplete` | `boolean` | Same as `isComplete`, but for mounted **bank** fields (`OzBankCard` / bank elements). Card and bank completion are tracked independently. |
+| `isTokenizing` | `boolean` | `true` while `createToken()` / `createBankToken()` is in progress (including the transparent wax-key refresh). Keep the pay button disabled to prevent double-submission. |
 
 > **`ready` vs `vault.isReady`:** `ready` from `useOzElements()` is a composite — it combines `vault.isReady` (tokenizer loaded) with element readiness (all mounted input iframes loaded). `vault.isReady` alone is insufficient for gating a submit button. Always use `ready` from `useOzElements()` in React.
 
 ---
 
+### useFieldStates()
+
+```ts
+const fields = useFieldStates();
+```
+
+Reactive snapshot of every created field's state, keyed by element type — `{ empty, complete, valid, error?, cardBrand? }` per field. Recomputes on every field change. It is a **standalone hook** (not part of `useOzElements()`), so only the components that need per-field state re-render on input. Must be called inside an `<OzElements>` provider; returns `{}` otherwise.
+
+```tsx
+import { useFieldStates } from '@ozura/elements/react';
+
+function CardErrors() {
+  const fields = useFieldStates();
+  return (
+    <>
+      {fields.cardNumber?.error && <span className="err">{fields.cardNumber.error}</span>}
+      {fields.cvv?.error && <span className="err">{fields.cvv.error}</span>}
+      {fields.cardNumber?.cardBrand && <BrandIcon brand={fields.cardNumber.cardBrand} />}
+    </>
+  );
+}
+```
+
+Keys exist only for fields you have created (card and bank combined), so access with `?.`.
+
+---
+
 ## Vue API
 
 > 📖 Vue 3 integration using the Composition API. Requires `vue >= 3.3`. No `.vue` SFC files needed in your setup — components work with `<script setup>` or the Options API.
@@ -885,6 +940,31 @@ Must be called from inside an `<OzElements>` provider tree.
 | `initError` | `Ref<Error \| null>` | Non-null if `OzVault.create()` failed. Render a fallback UI. |
 | `tokenizeCount` | `Ref<number>` | Successful tokenizations in the current session. Resets on session refresh. |
 | `reset` | `() => void` | Clear all fields without destroying the vault. Call after a declined payment. |
+| `isComplete` | `ComputedRef<boolean>` | `true` when every mounted **card** field reports complete and valid. Gate the pay button on it. |
+| `isBankComplete` | `ComputedRef<boolean>` | Same as `isComplete`, but for mounted **bank** fields. Tracked independently. |
+| `isTokenizing` | `ComputedRef<boolean>` | `true` while `createToken()` / `createBankToken()` is in progress (incl. wax-key refresh). Keep the pay button disabled. |
+
+### useFieldStates()
+
+```ts
+const fields = useFieldStates(); // ComputedRef<FieldStatesSnapshot>
+```
+
+Reactive snapshot of every created field's state, keyed by element type — `{ empty, complete, valid, error?, cardBrand? }` per field. Returns a `ComputedRef` that recomputes on every field change. Must be called from inside an `<OzElements>` provider tree (throws otherwise).
+
+```vue
+<script setup>
+import { useFieldStates } from '@ozura/elements/vue';
+const fields = useFieldStates();
+</script>
+
+<template>
+  <span v-if="fields.cvv?.error" class="err">{{ fields.cvv.error }}</span>
+  <BrandIcon v-if="fields.cardNumber?.cardBrand" :brand="fields.cardNumber.cardBrand" />
+</template>
+```
+
+Keys exist only for fields you have created (card and bank combined); access with `?.`.
 
 ### Field props and events
 

package/dist/react/types/index.d.ts

@@ -86,7 +86,7 @@ export interface ElementChangeEvent {
     complete: boolean;
     valid: boolean;
     /** Card brand — only present on cardNumber elements */
-    cardBrand?: string;
+    cardBrand?: CardBrand;
     /** Parsed month (01-12) — only present on expirationDate elements */
     month?: string;
     /** Parsed 2-digit year — only present on expirationDate elements */

package/dist/server/types/index.d.ts

@@ -86,7 +86,7 @@ export interface ElementChangeEvent {
     complete: boolean;
     valid: boolean;
     /** Card brand — only present on cardNumber elements */
-    cardBrand?: string;
+    cardBrand?: CardBrand;
     /** Parsed month (01-12) — only present on expirationDate elements */
     month?: string;
     /** Parsed 2-digit year — only present on expirationDate elements */

package/dist/types/types/index.d.ts

@@ -86,7 +86,7 @@ export interface ElementChangeEvent {
     complete: boolean;
     valid: boolean;
     /** Card brand — only present on cardNumber elements */
-    cardBrand?: string;
+    cardBrand?: CardBrand;
     /** Parsed month (01-12) — only present on expirationDate elements */
     month?: string;
     /** Parsed 2-digit year — only present on expirationDate elements */

package/dist/vue/types/index.d.ts

@@ -86,7 +86,7 @@ export interface ElementChangeEvent {
     complete: boolean;
     valid: boolean;
     /** Card brand — only present on cardNumber elements */
-    cardBrand?: string;
+    cardBrand?: CardBrand;
     /** Parsed month (01-12) — only present on expirationDate elements */
     month?: string;
     /** Parsed 2-digit year — only present on expirationDate elements */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ozura/elements",
-  "version": "1.3.1-next.77",
+  "version": "1.3.1-next.79",
   "description": "PCI-compliant card tokenization SDK for the Ozura Vault — collect card data in iframe-isolated fields and tokenize without PCI scope",
   "main": "dist/oz-elements.umd.js",
   "module": "dist/oz-elements.esm.js",