@featherk/ui 0.9.5 → 0.9.7

package/README.md

@@ -5,7 +5,7 @@ Vue UI component package for FeatherK.
 ## Components Overview
 
 - **Address**: `USAddress` - Presentational US address renderer driven by a parent-owned `useUSAddress` view model.
-	- Guide: [docs/address/USAddress.md](https://github.com/NantHealth/featherk/blob/integration/packages/ui/docs/address/USAddress.md)
+  - Component guide: [docs/address/USAddress.md](https://github.com/NantHealth/featherk/blob/integration/packages/ui/docs/address/USAddress.md)
 
 ## Importing Components
 
@@ -14,73 +14,17 @@ import { USAddress } from "@featherk/ui";
 import { useUSAddress } from "@featherk/composables/address";
 ```
 
-## Usage
-
-Component styles ship with `@featherk/ui` and are automatically loaded from the package ESM entry.
-
-```vue
-<script setup lang="ts">
-import { ref, toRef } from "vue";
-import { USAddress } from "@featherk/ui";
-import { useUSAddress } from "@featherk/composables/address";
-
-const billingFieldsetRef = ref<HTMLFieldSetElement | null>(null);
-const isAddressRequired = ref(true);
-
-const billingAddress = useUSAddress({
-	fieldsetRef: toRef(() => billingFieldsetRef.value),
-	addressId: "billing-address",
-	required: toRef(() => isAddressRequired.value),
-});
-
-const onFieldsetFocusout = (event: FocusEvent) => {
-	billingAddress.onFieldsetFocusout(event);
-};
-
-function onReset() {
-	billingAddress.reset();
-}
-
-async function onSubmit() {
-	const result = await billingAddress.validateForSubmit();
-	if (!result.isValid) return;
-
-	console.log(result.payload);
-}
-</script>
-
-<template>
-	<form @submit.prevent="onSubmit">
-		<fieldset ref="billingFieldsetRef" @focusout="onFieldsetFocusout">
-			<USAddress
-				id="billing-address"
-				:address="billingAddress"
-				:required="isAddressRequired"
-			/>
-
-			<label for="billing-attn">Attention</label>
-			<input id="billing-attn" type="text" />
-		</fieldset>
-
-		<button type="submit">Submit</button>
-		<button type="button" @click="onReset">Reset</button>
-	</form>
-</template>
-```
-
-`USAddress` is presentational. Parent components own composable orchestration.
-
-Required prop:
-- `address`: pass the object returned by `useUSAddress(...)`.
-
-Submission ownership:
-- Parent form components own submission orchestration, reset behavior, and payload handling.
+For complete setup, behavior, and examples, use the component guide listed in Components Overview.
 
 ## Peer Dependencies
 
 - Required: `vue`
 - Required for `USAddress`: `@progress/kendo-vue-buttons`, `@progress/kendo-vue-dropdowns`, `@progress/kendo-vue-inputs`, `@progress/kendo-vue-labels`
 
+## Styling
+
+Component styles ship with `@featherk/ui` and are automatically loaded from the package ESM entry.
+
 ## Build
 
 Run from repository root:

package/docs/address/USAddress.md

@@ -18,29 +18,49 @@ import { USAddress } from "@featherk/ui";
 import { useUSAddress } from "@featherk/composables/address";
 ```
 
+## Quick Start
+
+1. Call `useUSAddress({ fieldsetRef, addressId, required })` to get the composable API.
+2. Wrap `<USAddress>` inside a `<fieldset>` and bind its `ref` to `fieldsetRef`.
+3. Wire the fieldset's `@focusout` to `onFieldsetFocusout` — this activates
+   delayed validation, which stays suspended until the fieldset loses focus
+   or the form is submitted.
+4. On submit, call `await address.validateForSubmit()`. This sets internal
+   `submitted` state (activating error display) and returns
+   `{ isValid, payload }`, where `payload` is `null` when `isValid` is `false`.
+5. On reset, call `address.reset()`. **Use `type="button"` on the Reset
+   control** — the HTML default is `type="submit"`, which would immediately
+   re-trigger form submission and re-raise the error you just cleared.
+
 ## Basic Usage
 
 ```vue
 <script setup lang="ts">
-import { ref, toRef } from "vue";
+import { ref } from "vue";
 import { USAddress } from "@featherk/ui";
 import { useUSAddress } from "@featherk/composables/address";
 
 const shippingFieldsetRef = ref<HTMLFieldSetElement | null>(null);
+const isShippingAddressRequired = ref(true);
 
+// Step 1: get the composable API; refs can be passed directly (no toRef needed)
 const shippingAddress = useUSAddress({
-  fieldsetRef: toRef(() => shippingFieldsetRef.value),
+  fieldsetRef: shippingFieldsetRef,
   addressId: "shipping-address",
+  required: isShippingAddressRequired,
 });
 
+// Step 3: activates delayed validation on fieldset blur
 const onFieldsetFocusout = (event: FocusEvent) => {
   shippingAddress.onFieldsetFocusout(event);
 };
 
+// Step 5
 function onReset() {
   shippingAddress.reset();
 }
 
+// Step 4
 async function onSubmit() {
   const result = await shippingAddress.validateForSubmit();
   if (!result.isValid) return;
@@ -51,14 +71,22 @@ async function onSubmit() {
 
 <template>
   <form @submit.prevent="onSubmit">
+    <!-- Step 2: fieldsetRef binds here -->
     <fieldset ref="shippingFieldsetRef" @focusout="onFieldsetFocusout">
-      <USAddress id="shipping-address" :address="shippingAddress" />
+      <!-- required must match the same source passed to useUSAddress; messageScope defaults to "fieldset" -->
+      <USAddress
+        id="shipping-address"
+        :address="shippingAddress"
+        :required="isShippingAddressRequired"
+        messageScope="fieldset"
+      />
 
       <label for="shipping-attn">Attention</label>
       <input id="shipping-attn" type="text" />
     </fieldset>
 
     <button type="submit">Submit</button>
+    <!-- Step 5: type="button" required, see Quick Start -->
     <button type="button" @click="onReset">Reset</button>
   </form>
 </template>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@featherk/ui",
-  "version": "0.9.5",
+  "version": "0.9.7",
   "main": "dist/featherk-ui.umd.js",
   "module": "dist/featherk-ui.es.js",
   "types": "dist/index.d.ts",