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

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
@@ -803,6 +828,33 @@ Must be called from inside an `<OzElements>` provider tree.
 
 ---
 
+### 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.
@@ -886,6 +938,28 @@ Must be called from inside an `<OzElements>` provider tree.
 | `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. |
 
+### 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
 
 All five field components share the same props and emits:

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.78",
   "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",