Updates

.github/workflows/ci.yml

@@ -0,0 +1,69 @@
+name: CI
+
+on:
+  push:
+    branches: ['main']
+    tags: ['v*']
+  pull_request:
+    branches: ['*']
+
+  workflow_dispatch:
+
+concurrency:
+  group: ${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  validate:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: pnpm/action-setup@v4
+        with:
+          version: 10
+          run_install: false
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22
+          cache: pnpm
+
+      - run: pnpm install
+
+      - run: pnpm validate
+
+      - uses: SonarSource/sonarqube-scan-action@v7.0.0
+        if: "!startsWith(github.ref, 'refs/tags/')"
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          SONAR_TOKEN: ${{ secrets.SONAR_TOKEN }}
+
+  publish:
+    runs-on: ubuntu-latest
+    if: startsWith(github.ref, 'refs/tags/v')
+    needs: validate
+    permissions:
+      id-token: write
+      contents: read
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: pnpm/action-setup@v4
+        with:
+          version: 10
+          run_install: false
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22
+          cache: pnpm
+          registry-url: https://registry.npmjs.org
+
+      - run: npm install -g npm@11
+
+      - run: pnpm install
+
+      - run: pnpm build
+
+      - run: npm publish --provenance

.gitignore

@@ -3,3 +3,6 @@ coverage
 dist
 node_modules
 reports
+
+demo/pnpm-lock.yaml
+**/pnpm-workspace.yaml

CLAUDE.md

@@ -0,0 +1,60 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Commands
+
+### Development
+- `npm run watch` - Build and watch for changes (uses tsup)
+- `npm run build` - Clean and build the library for production
+
+### Testing
+- `npm test` - Run tests in watch mode (development)
+- `npm run test:coverage` - Run tests with coverage report
+- Run a single test: `vitest run test/index.spec.tsx`
+
+### Quality Checks
+- `npm run lint` - Lint and fix code issues
+- `npm run typecheck` - Run TypeScript type checking
+- `npm run validate` - Run full validation suite (lint, typecheck, test, build, size check)
+- `npm run size` - Check bundle size limits
+
+## Architecture
+
+### Core Component Flow
+The library uses a state machine pattern for managing the floater lifecycle:
+
+1. **Main Entry** (`src/index.tsx`): Thin JSX shell that delegates to `useFloater` hook
+   - `useFloater` (`src/modules/useFloater.ts`): All state management, Popper.js integration, event handlers
+   - Status transitions: INIT → IDLE → RENDER → OPENING → OPEN → CLOSING → IDLE
+
+2. **Component Structure**:
+   - `Portal` (`src/components/Portal.tsx`): Manages DOM portal rendering
+   - `Floater` (`src/components/Floater/index.tsx`): The floating UI container
+   - `Container` (`src/components/Floater/Container.tsx`): Content wrapper with title/footer
+   - `Arrow` (`src/components/Floater/Arrow.tsx`): Customizable arrow element
+   - `Wrapper` (`src/components/Wrapper.tsx`): Target element wrapper for beacon mode
+
+3. **Positioning System**: Uses Popper.js v2 with:
+   - Custom modifiers configuration via `getModifiers()` helper
+   - Fallback placements for auto-positioning
+   - Fixed positioning detection for proper scrolling behavior
+
+### Key Patterns
+
+**State Management**: The `useFloater` hook uses `useReducer` with status-based state transitions. A `previousStatus` ref tracks the prior status, and 3 focused `useEffect` hooks handle controlled mode, wrapper positioning, and status transitions.
+
+**Style Merging**: Custom styles are deeply merged with defaults using `deepmerge-ts`. The styles object structure is defined in `src/modules/styles.ts`.
+
+**Event Handling**: Special handling for mobile devices (converts hover to click) and delayed hiding for hover events using timeouts.
+
+**Type Safety**: Uses TypeScript with strict typing. Key type definitions in:
+- `src/types/common.ts`: Component props, states, and common types
+- `src/types/popper.ts`: Popper.js related types
+
+### Testing Approach
+- Uses Vitest with React Testing Library
+- `test/index.spec.tsx`: Rendering, UI, and integration tests
+- `test/modules/useFloater.spec.tsx`: State machine, lifecycle, and event handling tests
+- Coverage requirements: 90% for all metrics
+- Mock components in `test/__fixtures__/`