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 to learn more.

Recommended IDE Setup

• VS Code + Volar (and disable Vetur) + TypeScript Vue Plugin (Volar).

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:

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:

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.

Single bracket bout director assignment

Hover over a bracket pairing for a compact action dropdown; clicking the pairing still opens the bout directly. The dropdown offers Open bout, Resume bout, or Edit bout according to status. Assign director is enabled by default for scheduled bouts except the final and grand final; a parent can explicitly disable showBoutDirectorAssignment when needed. When a director is assigned, the hover menu shows their name as static text in the assigned ring/connector color above Assign Director, with bright blue as a fallback when no color is supplied. Active and completed bouts show their saved director above Resume bout or Edit bout. Unassigned bouts omit the name. No permanent icon is rendered.

<Bracket
  v-bind="bracketProps"
  :showBoutDirectorAssignment="canManageAssignments"
  @request:bout-director="openStaffDirectorPicker"
/>

request:bout-director carries a detached copy of the current bout, including BoutId and DEBoutId when supplied. The app opens its Staff-based picker, saves the choice, and passes updated planned coverage through plannedDirectingStations and plannedBoutAssignments. This action does not start the bout or change referee, score, sequence, or completion fields. Active, completed, and unidentified bouts have no assignment action. Planning is independent of directing eligibility, so future slots represented as BYE placeholders can also be assigned. Scheduled future bouts can be assigned before both competitors are known.

The dropdown opens after a short hover delay and stays open while moving into it. Keyboard focus reveals it immediately; Arrow Down enters its actions, arrows move between actions, and Escape dismisses it and restores focus. It closes on outside clicks or scrolling. The HoverBoutActions Storybook example includes a mock parent picker. Production distribution and section assignment remain app-owned. For standalone TableauBoutCard usage, pass plannedDirectorName and plannedDirectorColor to display planned assignment context without changing the bout's saved referee fields. TableauColumn accepts the plannedStationByBout lookup used by Tableau and forwards each planned director name and color. Each complete connector uses the receiving bout's planned director/ring color, including both feeders and the joining line. A receiving bout with no planned director has a neutral connector.

Storybook planned coverage

All bracket stories enable director assignment. The default examples start with two directors. The story parent splits scheduled main-bracket bouts into contiguous halves for two directors and quarters for four, through the semifinals, inclusive. Finals, placement, and consolation rounds receive no automatic assignments; eligible bouts there remain available for anyone to claim, including a fresh director.

Three, five, and six directors use near-equal contiguous groups within each round. Known opening BYEs add no work; future empty slots remain plannable. With two or four directors, section boundaries stay aligned with bracket halves or quarters even when BYEs make workloads uneven. With other counts, boundaries can shift as rounds narrow. Adding a director redistributes scheduled coverage and preserves existing plans for active and completed bouts. Manual bout assignment remains available through the semifinals. Finals cannot be preassigned and remain available to claim when both competitors are known.

The ThreeDirectors, FourDirectors, FiveDirectors, and SixDirectors stories demonstrate the counts. Distribution lives in the story parent simulation; reusable components still receive explicit plannedDirectingStations and plannedBoutAssignments from the consuming app.

The right-column director cards include a remove control. Bracket emits request:remove-planned-director with the selected station, including its RingId and Director. The consuming app removes that station from planned coverage, redistributes scheduled work as needed, and supplies the updated props. Removing planned coverage does not clear saved referee fields or change active/completed bouts. The story demonstrates removal, redistribution, removing the last director, and adding a removed director again.

DE director roster contract

Supply availableDirectors and rings to Bracket to enable the roster modal. Add director and Manage open a list with selection checkboxes and a ring dropdown per person. The parent prepares eligible staff and optional default rings from Staff and pool assignments; staff who only help in DE need no pool assignment. This package does not read or change the Staff screen or pool data.

The director column starts with compact icon-and-label buttons: Manage, Redistribute, and Refresh. Their full descriptions are available as tooltips and accessible labels. Redistribute emits request:redistribute-scheduled-bouts; the parent redistributes scheduled coverage and returns updated assignment props, preserving active and completed bouts. Refresh emits request:refresh-assignments; the parent reloads current stations and assignments and supplies fresh props. Both events have no payload and leave existing data visible until the parent responds. The toolbar uses the same availableDirectors and rings availability as Manage. Standalone BracketDirectorAssignmentPanel consumers enable it with canManageDirectors and receive the same request events.

availableDirectors contains { PersonId, DisplayName, Color, PortraitUrl?, DefaultRingId? }. rings contains { RingId, RingName, Color?, Disabled? }. Saved plannedDirectingStations keep the existing { RingId, RingName, Color, Director: { PersonId, DisplayName, PortraitUrl? } } shape. Director IDs identify people; ring IDs identify coverage stations. One selected director per ring matches the current station and bout-assignment contract. The modal permits changing both draft rows before saving a ring swap and reports duplicate or missing rings.

Saving emits update:planned-directing-stations with a detached full station list. Unchecking a person removes them from DE coverage. Ring changes are made in the modal; right-column cards display the selected ring as plain text. The parent saves the intent, redistributes scheduled coverage as appropriate, and returns authoritative props. Existing active/completed bout fields and pool assignments remain parent-owned. Each director keeps their supplied color when changing rings.

If those new data props are omitted, the existing request:add-planned-director callback remains available for parent-owned add UI. BracketDirectorsModal is also exported for standalone use with show, availableDirectors, rings, and stations; it emits update:show and submit:stations.

Phone directing view

Below 768px, the bracket shows the bout list with connection status and planned ring suggestions. The organising panel and assignment actions are unavailable on phones, even when their props are enabled. Completed bouts sit in a collapsed section for score corrections. Returning to desktop restores the selected List View or Tableau.

Phone event navigation keeps Pools, Pool Results, Bracket, Final Results, and Penalties accessible in a scrolling row. Edit, Staff, Displays, and Checkin remain in the desktop organiser menu. Selecting List View on desktop does not change the navigation. The PhoneDirector bracket story demonstrates this responsive layout; use a viewport narrower than 768px.

Event waitlist setting

The event wizard exposes an Enable Waitlist toggle beneath Max Fencers on Basic Info. The boolean event field WaitlistEnabled defaults to true when absent and preserves an explicit false. Both update:submit and save:step include the field on the event payload, separately from rules. The consuming app persists it and returns the saved value through the event prop; registration availability and capacity enforcement remain app-owned.

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.

<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.

Existing-event step saves

EditEventInfo and EditEventWizard accept editMode, controlled step (1–5), saving, saveError, and saveNotice props.

With editMode enabled, steps 1–4 display Save and Continue and step 5 displays Save. Every save emits save:step with { event, step }. The component does not advance itself: the consuming app persists the section, supplies the saved event, and changes step after success. Keep step and the draft unchanged on failure. Set saving while pending to disable editing and show inline feedback.

update:dirty emits a boolean when the draft changes or is reset from saved props. navigate:step requests Back navigation; update:cancel requests cancellation. The consuming app owns unsaved-change protection and routing. These events are forwarded by EditEventInfo.

The default editMode: false retains creation's Next/Back navigation and one update:submit at the end. No API calls or persistence are implemented in this package. Storybook's EditWithStepSaves example simulates successful saves; SavingStep and StepSaveFailed show the pending and failure states.

Tournament and event prices

TournamentManagement's Basic tab edits tournament.BasePrice; the event wizard's Basic Info step edits event.EventPrice. Both fields support decimal amounts and zero. Tournament base prices display two decimal places when loaded and after leaving the input. Missing or null prices show a 0.00 placeholder, and clearing a price saves zero. Negative and nonnumeric prices prevent submission.

submit:tournament includes numeric BasePrice. The wizard includes numeric EventPrice in both update:submit and save:step.event, separate from event rules. The consuming app owns currency, persistence, and supplying refreshed price values through props.