@dcrackel/hematournamentui 1.0.696 → 1.0.698

package/AGENTS.md

@@ -0,0 +1,85 @@
+# Agent Guide
+
+This project is `@dcrackel/hematournamentui`, the shared Vue 3 Storybook/UI package for Meyer Squared tournament screens. It owns reusable presentation components, visual structure, Storybook examples, Tailwind styling, and small UI-only state. The consuming admin/frontend app owns routing, API calls, sockets, auth, localStorage, persistence, and tournament workflow orchestration.
+
+## Code Style
+
+- Prefer small, single-use, named functions over long inline blocks.
+- Prefer guard clauses and early returns over `else`.
+- Avoid `else if`. Use named predicate helpers, lookup maps, or dispatch tables when branching by type/status/action.
+- Prefer predicate dispatch tables over large `switch` statements or long conditional chains.
+- Use clear, boring names for important logic. Favor searchable names that describe the component intent or emitted action.
+- Keep comments sparse. Add comments for domain rules, accessibility choices, or non-obvious sequencing behavior, not for code that reads plainly.
+- Preserve existing component props, emitted events, slots, class contracts, and exported component names unless the change intentionally updates the package API.
+- Do not refactor unrelated files while fixing focused bugs or adding focused UI behavior.
+
+## Component Boundary
+
+- Components in this package should stay dumb, reusable, and presentation-focused.
+- App-specific tournament behavior belongs in the consuming frontend, not in this shared UI package.
+- Components should receive data through props and emit user intent upward for the parent to handle.
+- Emit events for parent-owned work such as persistence, API calls, socket messages, navigation, auth-sensitive behavior, and cross-screen workflow rules.
+- Keep local component state only for UI-only behavior, such as folding/unfolding menus, open/closed modal state when locally controlled, transient hover/focus state, input draft display, and similar presentation concerns.
+- Do not add API clients, socket code, localStorage workflow state, or route-level orchestration to this package unless the explicit goal is to create a reusable UI API around those concerns.
+- Clone incoming objects before building emitted payloads when the component may add or reshape UI-specific fields.
+- Keep emitted payload shapes stable. If an event contract changes, update the related Storybook examples and consuming documentation.
+
+## Atomic Design
+
+- Follow the existing atomic design structure as much as practical: `Atoms`, `Molecules`, `Organisms`, `Templates`, and `Skeletons`.
+- Put primitive, highly reusable controls in `Atoms`, such as base text, icons, inputs, tags, checkboxes, and radio groups.
+- Put small composed controls in `Molecules`, such as modals, filters, menus, button groups, titled inputs, indicators, and compact UI combinations.
+- Put larger reusable feature sections in `Organisms`, such as cards, containers, headers, forms, grids, complex inputs, wizards, and skeleton loaders.
+- Put page-shaped reusable layouts in `Templates`. Templates may compose many organisms, but should still avoid owning app orchestration, API calls, sockets, routing, or persistence.
+- Before creating a new component, check whether the behavior belongs in an existing atom, molecule, organism, or template instead of adding a near-duplicate.
+- Keep lower-level components generic. Do not make atoms or molecules depend on one tournament workflow when a prop, slot, or emitted event can keep them reusable.
+
+## Interaction Pattern
+
+- Prefer optimistic UI for direct user edits: update the visible component state right away, then emit the change upward.
+- The parent should perform persistence/API work and pass authoritative data back down through props.
+- Reconcile prop updates cleanly so the component reflects parent-owned truth after save, refresh, or rollback.
+- Do not block simple visual feedback on API completion unless the user action cannot be represented safely before confirmation.
+- Missing or invalid input data should degrade gracefully in the UI instead of crashing a component.
+
+## Vue Patterns
+
+- Use computed fields when derived data can be expressed declaratively.
+- Keep logic out of templates/JSX where practical. Move meaningful conditions, transformations, and class decisions into named computed values or helpers.
+- Keep Vue methods focused. Fetching, transforming, emitting, and local UI state updates should be separable when practical.
+- Prefer explicit `emits` declarations and prop definitions that document component contracts.
+- Use watchers sparingly. Prefer computed values and direct event handlers unless side effects are truly needed.
+- Keep Storybook stories aligned with the public component API and use them to demonstrate meaningful states, variants, empty states, disabled states, and responsive behavior.
+
+## Styling And Layout
+
+- Use Tailwind for layout, spacing, color, state, and responsive design whenever practical.
+- Prefer CSS/Tailwind responsive behavior over JavaScript-driven breakpoints or resize logic.
+- Keep layout behavior stable across mobile and desktop. Avoid text overlap, dynamic content shifting controls, or assumptions about fixed viewport sizes.
+- Preserve existing visual language and component hierarchy before introducing new style patterns.
+- Keep reusable components theme-friendly. Avoid hard-coding app-specific colors or one-off layout assumptions unless the component already owns that visual contract.
+- Prefer accessible native controls and semantic markup where possible.
+
+## Data Ownership
+
+- Treat this package as a UI surface, not an authoritative data owner.
+- The consuming app owns persisted tournament state, live scoring truth, socket freshness, sequence handling, auth, routing, and recovery after reload/reconnect.
+- Scoreboards, cards, tables, menus, and forms in this package should display provided data and emit user intent; they should not invent tournament workflow state.
+- Keep tournament domain rules explicit when they are needed for rendering. Name conditions that depend on pool vs DE, completed vs active, visible vs hidden, or editable vs read-only.
+- If a rule requires backend knowledge or app workflow context, prefer making it a prop or emitted decision rather than embedding the rule in a shared component.
+
+## Package Boundary
+
+- `src/index.js` is the package export surface. Keep exports intentional and stable.
+- `src/stories` contains reusable components and their Storybook-facing examples. Follow the existing atoms, molecules, organisms, templates, and skeletons structure.
+- `dist` is generated output. Do not edit it by hand.
+- Ignore `dist` and `node_modules` while searching unless debugging generated package output or dependency internals.
+- Do not add consuming-app-only dependencies to this package for one component. Prefer props, slots, events, or small local helpers.
+
+## Validation
+
+- Run focused lint/build checks after UI changes when practical.
+- Useful commands include `npm run lint`, `npm run build-storybook`, `npm run build:tailwind`, and `npm run test`.
+- For component behavior changes, verify emitted events, optimistic display updates, prop reconciliation, empty states, disabled states, and responsive layout.
+- For public API changes, update Storybook stories and check the consuming app contract.
+- Avoid running package version/publish flows unless explicitly requested. `npm run build` currently patches the package version as part of the script.

package/README.md

@@ -10,12 +10,28 @@ This template should help get you started developing with Vue 3 in Vite. The tem
 
 
 
-## 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.
-
-# 1. Setup & Prerequisites
-Ensure you have an account on npm. If not, you can create one for free.
-Verify node and npm installations:
+## 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