diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..9ec947b --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,94 @@ +# react-tip-magic + +A React tooltip library with a guided-tour hook (`useTour`) and a keyboard-shortcut +discovery menu (`TipAdvisor`). One tooltip element is rendered at a time and moved +between targets; tours reuse that same element as their panel. + +## Commands + +```bash +npm run validate # typecheck + lint + format:check + test - run before every commit +npm test # vitest, jsdom +npm run dev # Storybook on :6006 +npm run build # library (dist/index.mjs, .cjs, styles.css) +``` + +## Layout + +| Path | Holds | +| -------------------------- | ------------------------------------------------------------------------------------------------------------- | +| `src/components/` | React components. `Tooltip` renders the single tooltip; the rest are internals mounted by `TipMagicProvider`. | +| `src/hooks/` | Public hooks and the API objects behind `useTipMagic()`. | +| `src/hooks/useTour/utils/` | Tour helpers: DOM managers (classes) and pure functions. | +| `src/utils/` | Pure helpers shared across components. Tests in `__tests__/` beside them. | +| `src/types/` | All public types. `tour.ts` re-exports through `index.ts`. | +| `src/styles/` | One stylesheet per concern, all imported by `index.css`. | +| `src/*.mdx` | The docs published to GitHub Pages. Updating the README does not reach them. | + +## Conventions + +- **Class names and data attributes live in constants**, never inline strings: + `CSS_CLASSES` and `PRIMARY_ACTION_ATTRIBUTE` in `src/constants/`, `TOUR_CSS_CLASSES` + and `TOUR_DATA_ATTRIBUTES` in `src/hooks/useTour/constants.ts`. One name per value - + don't re-export a constant under a second name. +- **Pure logic goes in a `utils` module with its own test**, not inline in a component. + `tooltipStyles`, `groupCompatibility` and `autoFocusTarget` are the pattern. +- Options flow `TooltipShowOptions` → `ParsedTooltipData` → `Tooltip`, merged in + `useTooltipAPI` with the `...(options.x !== undefined && { x: options.x })` idiom. +- `DATA_ATTRIBUTES` in `src/constants/index.ts` is dead - it is documented as unused and + nothing reads it. Don't add live values to it. +- Comments are for things the code cannot say. Gotchas belong in this file. + +## Releasing + +No changesets. Bump `package.json` (`npm version --no-git-tag-version`) and merge: +`publish.yml` asks the registry whether that version exists, so a failed publish retries +on the next push rather than stranding the bump. + +## Gotchas + +**`dangerouslySetInnerHTML` is re-applied on every render.** React rewrites the subtree +even when the html string is byte-identical. Anything focused inside it is dropped to +``, an `` or autoplaying `