Feat/compt 31 dom event hooks

.changeset/COMPT-31-dom-event-hooks.md

@@ -0,0 +1,23 @@
+---
+"@ciscode/hooks-kit": minor
+---
+
+feat(COMPT-31): add DOM & event hooks — useMediaQuery, useWindowSize, useClickOutside, useIntersectionObserver
+
+Second batch of production-ready hooks for HooksKit (epic COMPT-2).
+
+**New hooks:**
+
+- `useMediaQuery(query)` — tracks `matchMedia`, updates on change via `useSyncExternalStore`, SSR-safe (server snapshot returns `false`)
+- `useWindowSize()` — returns `{ width, height }`, debounced 100ms on resize, SSR-safe (returns `{ 0, 0 }`)
+- `useClickOutside(ref, handler)` — fires on `mousedown` or `touchstart` outside ref element, handler updated via ref pattern to avoid stale closures
+- `useIntersectionObserver(ref, options?)` — returns latest `IntersectionObserverEntry | null`, disconnects observer on unmount
+
+**Implementation details:**
+
+- All listeners registered in `useEffect` and removed in cleanup return
+- All SSR-safe: `typeof window === 'undefined'` guards in every hook
+- `useMediaQuery` uses `useSyncExternalStore` (React 18) — no `setState` in effects
+- Zero runtime dependencies
+- `tsc --noEmit` passes, ESLint passes (0 warnings), 26/26 tests pass, coverage ≥ 95%
+- All four hooks exported from `src/index.ts`

.github/dependabot.yml

@@ -0,0 +1,20 @@
+version: 2
+updates:
+  - package-ecosystem: npm
+    directory: "/"
+    schedule:
+      interval: monthly
+    open-pull-requests-limit: 1
+    groups:
+      npm-dependencies:
+        patterns:
+          - "*"
+    assignees:
+      - CISCODE-MA/cloud-devops
+    labels:
+      - "dependencies"
+      - "npm"
+    commit-message:
+      prefix: "chore(deps)"
+      include: "scope"
+    rebase-strategy: auto

.github/instructions/copilot-instructions.md

@@ -1,58 +1,62 @@
-# Copilot Instructions - React Component Library
+# Copilot Instructions - HooksKit
 
-> **Purpose**: Development guidelines for React component libraries - reusable, well-structured components for modern apps.
+> **Purpose**: Development guidelines for HooksKit — production-ready React hooks with zero runtime deps.
 
 ---
 
 ## 🎯 Module Overview
 
-**Package**: `@ciscode/ui-components` (example)  
-**Type**: React Component Library  
+**Package**: `@ciscode/hooks-kit`  
+**Epic**: COMPT-2 — HooksKit  
+**Type**: React Hooks Library  
 **Framework**: React 18+, TypeScript 5+  
-**Build**: Vite/tsup  
+**Build**: tsup  
 **Testing**: Vitest + React Testing Library  
 **Distribution**: NPM package  
-**Purpose**: Reusable, production-ready React components for building modern UIs
+**Purpose**: 12 production-ready React hooks. Zero runtime deps. SSR-safe.
 
-### Typical Module Responsibilities:
+### Hook Groups:
 
-- Atomic UI components (Button, Input, Card, etc.)
-- Composite components (Form, Modal, Navigation, etc.)
-- Hooks for common patterns
-- Type definitions and props interfaces
-- Accessibility compliance (WCAG 2.1 AA)
-- Theming and customization
-- Comprehensive documentation
+- **State & Storage** (COMPT-30 ✅) — `useDebounce`, `useLocalStorage`, `useSessionStorage`
+- **DOM & Events** (COMPT-31 ✅) — `useMediaQuery`, `useWindowSize`, `useClickOutside`, `useIntersectionObserver`
+- **Async & Lifecycle** — _(upcoming)_
+
+### Module Responsibilities:
+
+- Generic, fully-typed hooks with inference at call site
+- SSR-safe (`typeof window === 'undefined'` guards in every hook)
+- Zero runtime dependencies
+- All listeners registered in `useEffect` and cleaned up on unmount
+- WCAG-accessible patterns where applicable
+- Hooks ≥ 90% coverage
 
 ---
 
 ## 🏗️ Module Structure
 
 ```
 src/
-  ├── components/                     # React components
-  │   ├── Button/
-  │   │   ├── Button.tsx              # Component
-  │   │   ├── Button.test.tsx         # Tests
-  │   │   ├── Button.types.ts         # Props types
-  │   │   └── index.ts                # Exports
-  │   ├── Input/
-  │   ├── Modal/
-  │   └── Form/
-  ├── hooks/                          # Custom hooks
-  │   ├── useModal.ts
-  │   ├── useForm.ts
-  │   └── useModal.test.ts
-  ├── context/                        # Context providers
-  │   ├── ThemeContext.tsx
-  │   └── FormContext.tsx
-  ├── types/                          # TypeScript types
-  │   └── common.types.ts
-  ├── utils/                          # Utilities
-  │   └── classNameUtils.ts
-  └── index.ts                        # Public API
+  ├── components/                     # Minimal supporting components
+  │   ├── NoopButton.tsx
+  │   └── index.ts
+  ├── hooks/                          # All public hooks
+  │   ├── useDebounce.ts              # COMPT-30 ✅
+  │   ├── useLocalStorage.ts          # COMPT-30 ✅
+  │   ├── useSessionStorage.ts        # COMPT-30 ✅
+  │   ├── storage.ts                  # Internal SSR-safe storage helper
+  │   ├── useMediaQuery.ts            # COMPT-31 ✅
+  │   ├── useWindowSize.ts            # COMPT-31 ✅
+  │   ├── useClickOutside.ts          # COMPT-31 ✅
+  │   ├── useIntersectionObserver.ts  # COMPT-31 ✅
+  │   └── index.ts                    # Hook barrel
+  ├── utils/                          # Framework-agnostic utils
+  │   ├── noop.ts
+  │   └── index.ts
+  └── index.ts                        # Public API (only entry point)
 ```
 
+> ⚠️ Only export from `src/index.ts`. Deep imports are forbidden.
+
 ---
 
 ## 📝 Naming Conventions

.github/workflows/pr-validation.yml

@@ -0,0 +1,41 @@
+name: CI - PR Validation
+
+on:
+    pull_request:
+        branches: [develop]
+
+permissions:
+    contents: read
+
+jobs:
+    validate:
+        name: CI - PR Validation
+        runs-on: ubuntu-latest
+
+        steps:
+            - name: Checkout
+              uses: actions/checkout@v4
+
+            - name: Setup Node
+              uses: actions/setup-node@v4
+              with:
+                  node-version: 22
+                  cache: npm
+
+            - name: Install
+              run: npm ci
+
+            - name: Format (check)
+              run: npm run format
+
+            - name: Lint
+              run: npm run lint
+
+            - name: Typecheck
+              run: npm run typecheck
+
+            - name: Test
+              run: npm test
+
+            - name: Build
+              run: npm run build

.github/workflows/publish.yml

@@ -20,30 +20,52 @@ jobs:
         with:
           fetch-depth: 0
 
-      - name: Validate tag exists on this push
+      - name: Validate version tag and package.json
         run: |
-          TAG=$(git describe --exact-match --tags HEAD 2>/dev/null || echo "")
-          if [[ -z "$TAG" ]]; then
-            echo "❌ No tag found on HEAD. This push did not include a version tag."
-            echo "To publish, merge to master with a tag: git tag v1.0.0 && git push origin master --tags"
+          PKG_VERSION=$(grep '"version"' package.json | head -1 | sed 's/.*"version": "\([^"]*\)".*/\1/')
+          TAG="v${PKG_VERSION}"
+
+          if [[ -z "$PKG_VERSION" ]]; then
+            echo "❌ ERROR: Could not read version from package.json"
             exit 1
           fi
+
           if [[ ! "$TAG" =~ ^v[0-9]+\.[0-9]+\.[0-9]+$ ]]; then
-            echo "❌ Invalid tag format: $TAG. Expected: v*.*.*"
+            echo "❌ ERROR: Invalid version format in package.json: '$PKG_VERSION'"
+            echo "Expected format: x.y.z  (e.g., 1.0.0, 0.2.3)"
+            exit 1
+          fi
+
+          if ! git rev-parse "$TAG" >/dev/null 2>&1; then
+            echo "❌ ERROR: Tag $TAG not found!"
+            echo ""
+            echo "This typically happens when:"
+            echo "  1. You forgot to run 'npm version patch|minor|major' on your feature branch"
+            echo "  2. You didn't push the tag: git push origin <feat/your-feature> --tags"
+            echo "  3. The tag was created locally but never pushed to remote"
+            echo ""
+            echo "📋 Correct workflow:"
+            echo "  1. On feat/** or feature/**: npm version patch (or minor/major)"
+            echo "  2. Push branch + tag: git push origin feat/your-feature --tags"
+            echo "  3. PR feat/** → develop, then PR develop → master"
+            echo "  4. Workflow automatically triggers on master push"
+            echo ""
             exit 1
           fi
-          echo "✅ Valid tag found: $TAG"
+
+          echo "✅ package.json version: $PKG_VERSION"
+          echo "✅ Tag $TAG exists in repo"
           echo "TAG_VERSION=$TAG" >> $GITHUB_ENV
 
       - name: Setup Node.js
         uses: actions/setup-node@v4
         with:
-          node-version: '20'
-          registry-url: 'https://registry.npmjs.org'
-          cache: npm
+          node-version: "22"
+          registry-url: "https://registry.npmjs.org"
+          cache: "npm"
 
       - name: Install dependencies
-        run: npm install
+        run: npm ci
 
       - name: Build
         run: npm run build --if-present
@@ -55,6 +77,6 @@ jobs:
         run: npm test --if-present 2>/dev/null || true
 
       - name: Publish to NPM
-        run: npm publish --access public --no-git-checks
+        run: npm publish --access public --provenance
         env:
           NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

.github/workflows/release-check.yml

@@ -3,16 +3,6 @@ name: CI - Release Check
 on:
   pull_request:
     branches: [master]
-  workflow_dispatch:
-    inputs:
-      sonar:
-        description: 'Run SonarCloud analysis'
-        required: true
-        default: 'false'
-        type: choice
-        options:
-          - 'false'
-          - 'true'
 
 concurrency:
   group: ci-release-${{ github.ref }}
@@ -27,30 +17,25 @@ jobs:
     permissions:
       contents: read
 
-    # Update these values for your package:
-    # - SONAR_PROJECT_KEY: "CISCODE-MA_YourPackageName"
     env:
-      SONAR_HOST_URL: 'https://sonarcloud.io'
-      SONAR_ORGANIZATION: 'ciscode'
-      SONAR_PROJECT_KEY: 'CISCODE-MA_PACKAGE_NAME_TEMPLATE'
+      SONAR_HOST_URL: "https://sonarcloud.io"
+      SONAR_ORGANIZATION: "ciscode"
+      SONAR_PROJECT_KEY: "CISCODE-MA_HooksKit"
 
     steps:
       - name: Checkout
-        uses: actions/checkout@v4
+        uses: actions/checkout@v6
         with:
           fetch-depth: 0
 
       - name: Setup Node
         uses: actions/setup-node@v4
         with:
-          node-version: '20'
-          cache: npm
+          node-version: "22"
+          cache: "npm"
 
       - name: Install
-        run: npm install
-
-      - name: Audit
-        run: npm audit --prod
+        run: npm ci
 
       - name: Format
         run: npm run format
@@ -68,20 +53,19 @@ jobs:
         run: npm run build
 
       - name: SonarCloud Scan
-        if: ${{ github.event_name == 'workflow_dispatch' && github.event.inputs.sonar == 'true' }}
         uses: SonarSource/sonarqube-scan-action@v6
         env:
           SONAR_TOKEN: ${{ secrets.SONAR_TOKEN }}
           SONAR_HOST_URL: ${{ env.SONAR_HOST_URL }}
         with:
           args: >
-            -Dsonar.organization=${{ env.SONAR_ORGANIZATION }} \
-            -Dsonar.projectKey=${{ env.SONAR_PROJECT_KEY }} \
-            -Dsonar.sources=src \
+            -Dsonar.organization=${{ env.SONAR_ORGANIZATION }}
+            -Dsonar.projectKey=${{ env.SONAR_PROJECT_KEY }}
+            -Dsonar.sources=src
+            -Dsonar.tests=test
             -Dsonar.javascript.lcov.reportPaths=coverage/lcov.info
 
       - name: SonarCloud Quality Gate
-        if: ${{ github.event_name == 'workflow_dispatch' && github.event.inputs.sonar == 'true' }}
         uses: SonarSource/sonarqube-quality-gate-action@v1
         timeout-minutes: 10
         env:

package.json

@@ -1,7 +1,7 @@
 {
-  "name": "@ciscode/reactts-developerkit",
-  "version": "1.0.0",
-  "description": "React TypeScript hybrid library template (components + hooks + utils).",
+  "name": "@ciscode/hooks-kit",
+  "version": "0.0.0",
+  "description": "12 production-ready React hooks. Zero runtime deps. SSR-safe. Groups: state and storage / DOM and events / async and lifecycle.",
   "license": "MIT",
   "private": false,
   "type": "module",
@@ -16,6 +16,10 @@
       "require": "./dist/index.cjs"
     }
   },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/CISCODE-MA/HooksKit.git"
+  },
   "main": "./dist/index.cjs",
   "module": "./dist/index.mjs",
   "types": "./dist/index.d.ts",

src/hooks/index.ts

@@ -1,4 +1,8 @@
 // Example placeholder export — replace with real hooks later.
 export const __hooks_placeholder = true;
 
+export * from './useClickOutside';
+export * from './useIntersectionObserver';
+export * from './useMediaQuery';
+export * from './useWindowSize';
 export * from './useNoop';