Enhancement: Complete base package scaffolding

[ViewFromTheBox]

Description

Completes the remaining items from the base package scaffolding (issue #3): adds the feedback component category directory, creates shared hooks and context providers (ThemeProvider + useTheme), and fixes a pre-existing test setup issue.

Closes: #3

Type of Change

• Bug fix (fixes an issue)
• New feature (adds new functionality)
• Enhancement (improves existing functionality)
• Refactoring (code improvement, no behavior change)
• Documentation update
• Performance improvement
• Security fix
• Breaking change (breaks backward compatibility)

Related Issue

Issue: #3

Motivation and Context

Issue #3 was mostly complete but missing two items: the feedback component category directory and shared hooks/context providers (ThemeProvider). These are needed before individual component work can begin.

Changes Made

• Added feedback/ component category with barrel export, tsup entry point, and @artisanpack-ui/react/feedback sub-path export
• Created ThemeProvider context and useTheme hook supporting light/dark/system color schemes with prefers-color-scheme media query listener
• Exported ThemeProvider, useTheme, ThemeContextValue, and ColorScheme from package index
• Fixed test-setup.ts — resolved npm workspace hoisting issue where @testing-library/jest-dom/vitest couldn't resolve vitest from hoisted location; switched to explicit matcher extension
• Added 8 tests covering all ThemeProvider behavior (defaults, manual switching, system preference detection, media query changes)

How Has This Been Tested?

Testing Environment:

• Operating System: macOS
• Node.js: v23.7.0
• Vitest: v4.1.2

Tests Performed:

1. npm test from monorepo root — all 82 tests pass (74 tokens + 8 react)
2. npm run lint — clean
3. npm run format:check on react package files — clean
4. 3 CodeRabbit review passes with all feedback addressed

Accessibility Tests Run

• Keyboard navigation tested
• Screen reader tested
• Color contrast verified
• ARIA labels checked

Details: N/A — no UI components in this PR (foundational code only)

Tests Added

• Unit tests added/updated
• Integration tests added/updated
• All tests passing

Test details: 8 tests in use-theme.test.tsx covering: default system scheme, initial dark system preference detection, custom default scheme, manual switching, system preference media query changes, manual override ignoring system changes, switching back to system mode, error when used outside provider

Documentation

• Inline code documentation added
• README updated
• Wiki updated
• API documentation updated

Documentation details: JSDoc comments on all exported types, interfaces, and functions. README/wiki updates deferred to component implementation PRs.

Pre-Submission Checklist

• Followed contributing guidelines
• Checked for other open PRs for same update
• Code passes all tests
• Code has been linted
• Accessibility tests completed
• Code follows project style guide
• Self-review completed
• Comments added for complex code
• No new warnings generated

Summary by CodeRabbit

• New Features

  • Introduced theme management system with ThemeProvider component and useTheme hook supporting light, dark, and system color scheme preferences.
  • Added new feedback components module (coming soon).

• Tests

  • Added comprehensive test coverage for theme provider and hook functionality.

• Chores

  • Updated build configuration to support new feedback module exports.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Pro

Run ID: 0d2af77c-06ae-4877-9236-8f1922269375

📥 Commits

Reviewing files that changed from the base of the PR and between f591b0d and a14bea3.

⛔ Files ignored due to path filters (1)

• package-lock.json is excluded by !**/package-lock.json

📒 Files selected for processing (7)

• packages/react/package.json
• packages/react/src/__tests__/use-theme.test.tsx
• packages/react/src/components/feedback/index.ts
• packages/react/src/hooks/use-theme.tsx
• packages/react/src/index.ts
• packages/react/src/test-setup.ts
• packages/react/tsup.config.ts

---

📝 Walkthrough

Walkthrough

This pull request introduces a new theme management system via a React context-based ThemeProvider and useTheme hook supporting light, dark, and system color schemes with matchMedia integration for system preference detection. Infrastructure for a feedback component library is added alongside comprehensive test coverage and build configuration updates.

Changes

Cohort / File(s)	Summary
Theme Management packages/react/src/hooks/use-theme.tsx, packages/react/src/__tests__/use-theme.test.tsx	New hook module exporting ColorScheme type, ThemeContextValue interface, ThemeProvider component, and useTheme hook for managing color scheme state with system preference detection via window.matchMedia. Comprehensive Vitest suite with 8 test cases verifying initialization, manual switching, system updates, and error handling.
Package Exports and Public API packages/react/src/index.ts, packages/react/package.json	Added public re-exports for theme utilities (ThemeProvider, useTheme, ThemeContextValue, ColorScheme) and feedback components. Added subpath export ./feedback mapping to ESM and TypeScript declaration files.
Feedback Component Infrastructure packages/react/src/components/feedback/index.ts, packages/react/tsup.config.ts	Placeholder feedback module with TODO comments for planned components (Alert, Toast, Loading, Skeleton, EmptyState, Error). New tsup build entry feedback configured for ESM output generation.
Test Configuration packages/react/src/test-setup.ts	Updated Vitest matcher registration by replacing @testing-library/jest-dom/vitest import with explicit matchers import and expect.extend() call.

Sequence Diagram

sequenceDiagram
    participant Component
    participant ThemeProvider
    participant ThemeContext as Context<ThemeContextValue>
    participant MediaQuery as window.matchMedia
    
    Component->>ThemeProvider: Mount with optional defaultColorScheme
    ThemeProvider->>MediaQuery: Call matchMedia('(prefers-color-scheme: dark)')
    MediaQuery-->>ThemeProvider: Return MediaQueryList with matches state
    ThemeProvider->>ThemeContext: Initialize with resolvedColorScheme based on matches
    ThemeProvider->>MediaQuery: Subscribe to 'change' events
    ThemeProvider-->>Component: Provide context (colorScheme, resolvedColorScheme, setColorScheme)
    
    alt System Preference Change
        MediaQuery->>ThemeProvider: Emit change event
        ThemeProvider->>ThemeContext: Update resolvedColorScheme (if colorScheme === 'system')
        ThemeContext-->>Component: Re-render with new resolvedColorScheme
    end
    
    alt Manual Color Scheme Switch
        Component->>ThemeProvider: Call setColorScheme('dark')
        ThemeProvider->>ThemeContext: Update colorScheme, unsubscribe from matchMedia
        ThemeContext-->>Component: Re-render with new values
    end

Loading

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~22 minutes

Poem

🐰 A theme most clever, dark and light,
With system whispers in the night,
The Provider hops through context trees,
While useTheme hooks float in the breeze,
Feedback awaits its promised day,
Hopping forward in every way! 🌙✨

🚥 Pre-merge checks | ✅ 2 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 50.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (2 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title accurately summarizes the main objective of the PR, which is completing the base package scaffolding by adding feedback component scaffolding and theme management infrastructure.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch enhancement/3-react-base-package-scaffolding

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}