@dcrackel/hematournamentui 1.0.708 → 1.0.709

package/README.md

@@ -1,106 +1,132 @@
-# Vue 3 + Vite
-
-This template should help get you started developing with Vue 3 in Vite. The template uses Vue 3 `<script setup>` SFCs, check out the [script setup docs](https://v3.vuejs.org/api/sfc-script-setup.html#sfc-script-setup) to learn more.
-
-## Recommended IDE Setup
-
-- [VS Code](https://code.visualstudio.com/) + [Volar](https://marketplace.visualstudio.com/items?itemName=Vue.volar) (and disable Vetur) + [TypeScript Vue Plugin (Volar)](https://marketplace.visualstudio.com/items?itemName=Vue.vscode-typescript-vue-plugin).
-
-## Publishing a Storybook Library to NPM
-
-Follow this guide to publish your Storybook library to NPM, making it available for others to easily npm install.
-
-## Shared CSS
-
-Build the package stylesheet as a separate step:
-
-```bash
-npm run build:package-css
-```
-
-The generated file is `dist/hematournamentui-tailwind.css`. Consuming apps should import it from the package instead of manually copying `tailwind/output.css`:
-
-```js
-import '@dcrackel/hematournamentui/tailwind.css';
-```
-
-Use `npm run build:tailwind` for Storybook's local `tailwind/output.css` workflow. Use `npm run build:package-css` when preparing CSS for the parent app or package publish.
-
-# 1. Setup & Prerequisites
-
-Ensure you have an account on npm. If not, you can create one for free.
-Verify node and npm installations:
-
-```
-Copy code
-node -v
-npm -v
-```
-
-# 2. Preparing Your Storybook Library
-
-a. Building the Library
-Compile your library with Vite or your bundler:
-
-```
-vite build
-```
-
-b. Update package.json
-Ensure the following fields are set:
-
-name: Name of your package.
-version: Version number.
-main: Main entry file (e.g., dist/index.js).
-files: Files to include, e.g., ["dist"].
-
-# 3. Logging in to NPM
-
-Login to npm (if you haven't already):
-
-```
-npm login
-```
-
-Provide your username, password, and email.
-
-# 4. Publishing to NPM
-
-a. Default (Private Package)
-For scoped private packages (@username/project-name):
-
-```
-npm publish
-```
-
-b. Public Package
-For public packages:
-
-```
-npm publish --access=public
-```
-
-# 5. Verifying Your Package
-
-Check on the npm website to verify your package's publication.
-
-Check the registry name
-
-```
-npm get registry
-```
-
-# 6. Installing and Using the Library
-
-To install the library:
-
-```
-npm install your-library-name
-```
-
-Users can then import and utilize your library's components.
-
-Notes:
-
-Always update the version in package.json before republishing.
-Ensure only necessary files are bundled to prevent package bloat.
+# Vue 3 + Vite
+
+This template should help get you started developing with Vue 3 in Vite. The template uses Vue 3 `<script setup>` SFCs, check out the [script setup docs](https://v3.vuejs.org/api/sfc-script-setup.html#sfc-script-setup) to learn more.
+
+## Recommended IDE Setup
+
+- [VS Code](https://code.visualstudio.com/) + [Volar](https://marketplace.visualstudio.com/items?itemName=Vue.volar) (and disable Vetur) + [TypeScript Vue Plugin (Volar)](https://marketplace.visualstudio.com/items?itemName=Vue.vscode-typescript-vue-plugin).
+
+## Publishing a Storybook Library to NPM
+
+Follow this guide to publish your Storybook library to NPM, making it available for others to easily npm install.
+
+## Shared CSS
+
+Build the package stylesheet as a separate step:
+
+```bash
+npm run build:package-css
+```
+
+The generated file is `dist/hematournamentui-tailwind.css`. Consuming apps should import it from the package instead of manually copying `tailwind/output.css`:
+
+```js
+import '@dcrackel/hematournamentui/tailwind.css';
+```
+
+Use `npm run build:tailwind` for Storybook's local `tailwind/output.css` workflow. Use `npm run build:package-css` when preparing CSS for the parent app or package publish.
+
+## Person profile drafts and Save
+
+`PersonManagement` edits a detached draft and emits `submit:person` with a detached snapshot only when the user saves a valid form. `BaseInput` emits `update:value` synchronously; consumers should debounce their own expensive searches or validation.
+
+```vue
+<PersonManagement
+  :personProfile="person"
+  :saving="saving"
+  :disabled="readOnly"
+  :draftResetKey="profileRevision"
+  @submit:person="savePerson"
+  @update:image="handleDraftImage"
+  @error:image="handleImageError"
+/>
+```
+
+The parent owns API calls, save failures, and authoritative reloads. After a successful reload, supply the refreshed `personProfile` and increment `draftResetKey` in the same update. Selecting a different `PersonId` resets the draft automatically. Updates for the same person preserve unsaved edits until the reset key changes; remounting with a versioned Vue `key` also works.
+
+`saving` and `disabled` disable the form's native controls and prevent new edits and save/delete/merge actions. An upload started earlier may still finish updating the draft. Saving shows accessible busy feedback. Image uploads temporarily disable Save until they finish. Validation failures show a summary across tabs, with links back to the invalid fields' tabs.
+
+Draft `LegalName` and `EmailAddress` take precedence over legacy names and email relations, including explicit empty strings. The library continues emitting `EmailAddress`; the parent maps it to backend `Email` and omits stale `PersonEmails` as required by its API. An explicit `HemaRatingsId: null` displays blank and never falls back to old ratings. Blank ID edits remain blank in the draft; the parent converts them to `null` and normalizes valid positive integer IDs.
+
+Successful uploads update the same draft's `ProfileImage` and emit `update:image` with the URL. That event is a draft notification and should not automatically persist the profile. `ImageCropper` emits successful edits as `update:url`, busy state as `update:uploading`, and failures separately as `error:load` or `error:upload`. `PersonManagement` displays image failures and forwards them as `error:image` with `{ type: 'load' | 'upload', message, url?, status? }`; failures never emit a null image edit.
+
+UI regression tests cover the draft and event contracts. Live backend save/reload checks for email, HR ID changes/clears, first-time profiles, and images remain the consuming application's responsibility; a skipped ratings refresh is separate from profile save success.
+
+# 1. Setup & Prerequisites
+
+Ensure you have an account on npm. If not, you can create one for free.
+Verify node and npm installations:
+
+```
+Copy code
+node -v
+npm -v
+```
+
+# 2. Preparing Your Storybook Library
+
+a. Building the Library
+Compile your library with Vite or your bundler:
+
+```
+vite build
+```
+
+b. Update package.json
+Ensure the following fields are set:
+
+name: Name of your package.
+version: Version number.
+main: Main entry file (e.g., dist/index.js).
+files: Files to include, e.g., ["dist"].
+
+# 3. Logging in to NPM
+
+Login to npm (if you haven't already):
+
+```
+npm login
+```
+
+Provide your username, password, and email.
+
+# 4. Publishing to NPM
+
+a. Default (Private Package)
+For scoped private packages (@username/project-name):
+
+```
+npm publish
+```
+
+b. Public Package
+For public packages:
+
+```
+npm publish --access=public
+```
+
+# 5. Verifying Your Package
+
+Check on the npm website to verify your package's publication.
+
+Check the registry name
+
+```
+npm get registry
+```
+
+# 6. Installing and Using the Library
+
+To install the library:
+
+```
+npm install your-library-name
+```
+
+Users can then import and utilize your library's components.
+
+Notes:
+
+Always update the version in package.json before republishing.
+Ensure only necessary files are bundled to prevent package bloat.