Develop (#12)

* initiated dev environment

* ops: updated SOnar name

* ops (ci): standardize publish validation and dependabot across all packages

- Replace git tag --list strategy with package.json-driven tag validation
  in all 16 publish workflows; use git rev-parse to verify the exact tag
  exists rather than guessing the latest repo-wide tag
- Update error guidance to reflect feat/** → develop → master flow
- Standardize dependabot to npm-only, grouped, monthly cadence across
  all 16 packages; remove github-actions ecosystem updates
- Add missing dependabot.yml to AuthKit-UI, ChartKit-UI, HealthKit,
  HooksKit, paymentkit, StorageKit

* chore(COMPT-138): apply repository-wide prettier baseline (#4)

- Run prettier --write across repository
- No logic/behavior changes
- Unblocks CI PR Validation format gate for feature PRs
- verify passes: lint + typecheck + tests

* Feat/compt 30 state storage hooks (#6)

* feat(COMPT-30): add useDebounce, useLocalStorage, useSessionStorage hooks

- useDebounce<T>(value, delay): returns debounced value, resets timer on value/delay change
- useLocalStorage<T>(key, initial): syncs with localStorage, SSR-safe, JSON serialization
- useSessionStorage<T>(key, initial): same pattern for sessionStorage
- Shared storage.ts helper with readStorageValue/writeStorageValue (SSR guard + parse fallback)
- All three exported from src/hooks/index.ts -> src/index.ts
- Full test coverage: timer reset, JSON sync, parse error fallback, SSR guard
- tsc --noEmit passes, lint passes (0 warnings), 13/13 tests pass

* chore(COMPT-30): add changeset, update copilot-instructions, fix husky pre-commit

- .changeset/COMPT-30-state-storage-hooks.md: minor bump summary for 0.0.1 release
- .github/instructions/copilot-instructions.md: updated to HooksKit package identity,
  real src structure with COMPT-30 hooks marked, COMPT-XX branch naming convention
- .husky/pre-commit: removed deprecated husky v9 shebang lines (breaks in v10)

* Feat/compt 31 dom event hooks (#8)

* feat(COMPT-31): add useMediaQuery, useWindowSize, useClickOutside, useIntersectionObserver

- useMediaQuery(query): tracks matchMedia via useSyncExternalStore, SSR-safe (server snapshot false)
- useWindowSize(): returns {width, height}, debounced 100ms on resize, SSR-safe ({0,0})
- useClickOutside(ref, handler): fires on mousedown/touchstart outside ref; handler via ref pattern
- useIntersectionObserver(ref, options?): IntersectionObserverEntry|null, disconnects on unmount
- All listeners registered in useEffect with cleanup return
- All SSR-safe: typeof window === undefined guards
- Zero runtime dependencies
- tsc --noEmit passes, lint passes (0 warnings), 26/26 tests pass, coverage >= 95%
- All four exported from src/hooks/index.ts -> src/index.ts
- Changeset added, copilot-instructions.md updated for epic COMPT-2

* test(COMPT-31): reduce duplicated test blocks for Sonar quality gate

- remove accidental duplicated useMediaQuery suite block
- extract shared viewport setup in useWindowSize tests
- extract shared mount helper in useClickOutside tests
- keep behavior coverage unchanged

* Feat/compt 32 async lifecycle hooks (#9)

* feat(COMPT-32): add usePrevious, useToggle, useInterval, useTimeout, useIsFirstRender

- usePrevious<T>(value): previous render value via state-derivation; undefined on first render
- useToggle(initial?): boolean toggle with stable useCallback reference
- useInterval(callback, delay|null): fires at cadence, stops on null, latest callback via ref
- useTimeout(callback, delay|null): fires once, cancels on null or unmount, latest callback via ref
- useIsFirstRender(): true only on first render (scoped eslint-disable for intentional ref access)
- All timer cleanup in useEffect return — StrictMode safe
- Zero runtime deps; tsc --noEmit passes, lint passes, 25/25 tests, hooks coverage >= 98%
- All five exported from src/hooks/index.ts -> src/index.ts
- Changeset added, copilot-instructions.md updated with all three COMPT groups complete

* refactor(COMPT-32): move hook tests to src/hooks/__tests__/

- Moved all 5 hook test files from src/hooks/ to src/hooks/__tests__/
- Updated relative imports from ./hook to ../hook
- No logic changes; all 25 tests still pass

* test(COMPT-33): consolidate all hook tests into src/hooks/__tests__/ (#10)

- Move useDebounce, useLocalStorage, useSessionStorage, useMediaQuery,
  useWindowSize, useClickOutside, useIntersectionObserver tests to __tests__/
- Update relative imports from ./ to ../
- All 12 hooks covered: fake timers for debounce/interval/timeout/windowSize,
  mock matchMedia, mock IntersectionObserver, storage parse-error guards
- 55 tests passing, 97.44% line coverage (>= 85% AC)

* security: added CODEOWNER file for branches security

* ops: updated release check workflow

* ops: updated relese check workflow#

* feat(COMPT-34): README, v0.1.0 version bump, publish preparation (#11)

- Full README with installation, SSR note, 12 hook examples with types
- Remove __hooks_placeholder from hooks barrel
- Fix COMPT-30 changeset package name (reactts-developerkit -> hooks-kit)
- Apply changeset version bump: 0.0.0 -> 0.1.0
- Remove duplicate root-level test files (already in __tests__/)
- Update copilot-instructions.md with COMPT-34 status

Co-authored-by: a-elkhiraooui-ciscode <a.elkhiraoui@ciscod.com>

* ci: update release check workflow

* ops: updated release check jobs.

* v0.1.0

* fix(ci): correct sonar test directory and inclusion patterns

---------

Co-authored-by: Zaiidmo <zaiidmoumnii@gmail.com>
Co-authored-by: Zaiid Moumni <141942826+Zaiidmo@users.noreply.github.com>

Author: a-elkhiraooui-ciscode

.github/CODEOWNERS

@@ -0,0 +1 @@
+* @CISCODE-MA/devops

.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,82 @@
-# 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** (COMPT-32 ✅) — `usePrevious`, `useToggle`, `useInterval`, `useTimeout`, `useIsFirstRender`
+- **Test Suite** (COMPT-33 ✅) — Full coverage for all 12 hooks, all tests in `src/hooks/__tests__/`
+- **README & Publish** (COMPT-34 ✅) — Full README with usage examples, v0.1.0 published to `@ciscode/hooks-kit`
+
+### Module Responsibilities:
+
+- Generic, fully-typed hooks with inference at call site
+- SSR-safe (`typeof window === 'undefined'` guards in every DOM 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 ✅
+  │   ├── usePrevious.ts              # COMPT-32 ✅
+  │   ├── useToggle.ts                # COMPT-32 ✅
+  │   ├── useInterval.ts              # COMPT-32 ✅
+  │   ├── useTimeout.ts               # COMPT-32 ✅
+  │   ├── useIsFirstRender.ts         # COMPT-32 ✅
+  │   ├── index.ts                    # Hook barrel
+  │   └── __tests__/                  # All hook tests (COMPT-33 ✅)
+  │       ├── useDebounce.test.ts
+  │       ├── useLocalStorage.test.ts
+  │       ├── useSessionStorage.test.ts
+  │       ├── useMediaQuery.test.ts
+  │       ├── useWindowSize.test.ts
+  │       ├── useClickOutside.test.ts
+  │       ├── useIntersectionObserver.test.ts
+  │       ├── usePrevious.test.ts
+  │       ├── useToggle.test.ts
+  │       ├── useInterval.test.ts
+  │       ├── useTimeout.test.ts
+  │       └── useIsFirstRender.test.ts
+  ├── 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
@@ -277,18 +301,17 @@ export type { ButtonProps, ModalProps, InputProps, FormProps } from './component
 **1. Branch Creation:**
 
 ```bash
-feature/UI-MODULE-123-add-datepicker
-bugfix/UI-MODULE-456-fix-modal-focus
-refactor/UI-MODULE-789-extract-button-styles
+feat/COMPT-30-state-storage-hooks
+bugfix/COMPT-XX-short-description
 ```
 
-**2. Task Documentation:**
+> Branch names must reference the Jira ticket (COMPT-XX format). Pull from `develop` before opening PR.
 
-Create task file:
+**PR targets:**
 
-```
-docs/tasks/active/UI-MODULE-123-add-datepicker.md
-```
+- Feature branches → `develop`
+- `develop` → `master` on Friday release only
+- Never open a PR directly to `master`
 
 **Task structure:**
 

.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'
+          node-version: '22'
           registry-url: 'https://registry.npmjs.org'
-          cache: npm
+          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 }}