@publicplan/kern-react-kit 1.3.1 → 1.3.3

package/dist/skills/kern-react-kit/references/REFERENCE.md

@@ -0,0 +1,316 @@
+# Technical Reference: Kern React Kit
+
+## Installation & Setup
+
+### NPM Installation
+```bash
+npm install @publicplan/kern-react-kit react react-dom
+```
+
+### Required Peer Dependencies
+- React 18.2.0 or higher
+- React DOM 18.2.0 or higher (or React 19.1.0+)
+
+### ESM/CommonJS Support
+The library ships with:
+- **ESM**: `dist/index.js` (default for `import`)
+- **CommonJS**: `dist/index.cjs` (for `require()`)
+- **Types**: `dist/index.d.ts` (ESM), `dist/index.d.cts` (CJS)
+- **Styles**: `dist/index.css`
+
+### Basic Setup in React App
+```typescript
+// src/main.tsx (or App.tsx)
+import React from 'react';
+import ReactDOM from 'react-dom/client';
+import App from './App';
+
+// Import styles globally
+import '@publicplan/kern-react-kit/index.css';
+
+ReactDOM.createRoot(document.getElementById('root')!).render(
+  <React.StrictMode>
+    <App />
+  </React.StrictMode>
+);
+```
+
+## API Stability & Import Contracts
+
+### Public API (Stable)
+The following are guaranteed to be stable and forward-compatible:
+1. **Named exports from main entry**: `import { Button, Card, ... } from '@publicplan/kern-react-kit'`
+2. **Type exports**: `import type { ButtonProps, CardProps, ... } from '@publicplan/kern-react-kit'`
+3. **Subpath exports**: `import { Button } from '@publicplan/kern-react-kit/Button'`
+4. **Style sheet**: `@publicplan/kern-react-kit/index.css`
+5. **Input components**: `TextInput`, `TextareaInput`, `CheckboxInput`, `RadioInput`, `SelectInput`,
+   `EmailInput`, `UrlInput`, `TelInput`, `DateInput`, `PasswordInput`, `NumberInput`, `FileInput`, `CheckboxList`
+
+### Internal/Unstable (Do Not Use)
+Avoid importing:
+- Anything from `dist/` or `dist/components/*/internal`
+- Context or hook internals (unless explicitly re-exported at top level)
+- SCSS files (use CSS variables instead)
+- Test utilities from `__tests__/`
+
+### Deprecation Policy
+Breaking changes will be announced via:
+- CHANGELOG.md updates
+- Major version bump in semver
+- Notice in release notes on GitHub
+
+## Theming & CSS Variables
+
+### Theme Customization
+All components use CSS custom properties. Override them at the `:root` level or scoped to a parent:
+
+```css
+/* Global override */
+:root {
+  --kern-color-primary: #0066cc;
+  --kern-color-secondary: #666666;
+  --kern-spacing-xs: 0.5rem;
+  --kern-spacing-sm: 1rem;
+  --kern-spacing-md: 1.5rem;
+  --kern-spacing-lg: 2rem;
+  --kern-spacing-xl: 3rem;
+  --kern-radius-sm: 0.25rem;
+  --kern-radius-md: 0.5rem;
+  --kern-radius-lg: 1rem;
+  --kern-shadow-sm: 0 1px 3px rgba(0, 0, 0, 0.1);
+  --kern-shadow-md: 0 4px 6px rgba(0, 0, 0, 0.1);
+  --kern-shadow-lg: 0 10px 15px rgba(0, 0, 0, 0.1);
+}
+
+/* Scoped override (e.g., for a specific card) */
+.my-special-card {
+  --kern-color-primary: #ff6600;
+  --kern-spacing-lg: 4rem;
+}
+```
+
+### Available CSS Variables
+- **Colors**: `--kern-color-{primary,secondary,success,warning,error,neutral,*}`
+- **Spacing**: `--kern-spacing-{xs,sm,md,lg,xl}`
+- **Radius**: `--kern-radius-{sm,md,lg}`
+- **Shadows**: `--kern-shadow-{sm,md,lg}`
+- **Typography**: `--kern-font-{body,heading,mono,*}`, `--kern-font-size-{sm,md,lg,xl}`
+- **Z-index**: `--kern-z-{dropdown,sticky,fixed,modal,tooltip}`
+
+See `src/styles/_variables.scss` in the repository for the complete list.
+
+## Styling & CSS Architecture
+
+### Class Naming Convention
+All component classes use the `kern-` prefix:
+- `.kern-btn` (Button)
+- `.kern-card` (Card)
+- `.kern-input` (Input)
+- `.kern-label` (Label)
+- `.kern-modal` (Dialog modal)
+- `.kern-sr-only` (Screen reader only utility)
+
+### CSS Utility Classes
+Commonly used utility classes:
+- `.kern-sr-only`: Hide visually but keep accessible to screen readers
+- `.kern-flex`, `.kern-grid`: Layout utilities
+- `.kern-text-{sm,md,lg}`: Typography sizes
+
+### Custom Styling Components
+```css
+/* my-custom-styles.css */
+.my-button-wrapper .kern-btn {
+  --kern-color-primary: #my-color;
+  border-radius: 999px; /* Override radius if needed */
+}
+```
+
+### SCSS & PostCSS
+The library uses SCSS internally, but **do not depend on SCSS exports**. The compiled CSS is the public interface.
+
+## Accessibility Guidelines
+
+### Components Guarantee
+- **Semantic HTML**: All components use correct HTML elements (`button`, `input`, etc.)
+- **ARIA Labels**: Interactive components have `aria-label`, `aria-labelledby`, or explicit text content
+- **Keyboard Accessible**: Tab navigation, Enter/Space to activate, Escape to close modals
+- **Focus Management**: Focus is managed appropriately (e.g., returns to trigger after modal closes)
+- **Color Contrast**: All text meets WCAG AA standards (4.5:1 for normal text)
+- **Testing**: Components are tested with axe-core and vitest-axe
+
+### Developer Responsibilities
+When using components:
+1. **Provide context**: Use `TextInput`'s `label` prop or `Label` with `htmlFor`
+2. **Handle focus**: Manage focus for dynamic content
+3. **Use semantic HTML**: Don't repurpose components for unintended purposes
+4. **Test accessibility**: Run accessibility tests in your own code (axe, jest-axe, etc.)
+5. **Provide alt text**: For images and icons, use `alt` or `aria-label`
+6. **Icons in Alert/Link**: Icons are `aria-hidden="true"` by default; if the icon conveys meaning, set `aria-hidden={false}` and provide `aria-label`.
+
+Example:
+```typescript
+import { TextInput } from '@publicplan/kern-react-kit';
+
+// ✅ Correct: Labeled input with helper text
+<TextInput
+  id="username"
+  name="username"
+  label="Username"
+  hintText="Your login username"
+  aria-describedby="help-text"
+/>
+<span id="help-text">Your login username</span>
+
+// ❌ Incorrect: Orphaned input, no label
+<TextInput placeholder="Username" />
+```
+
+### WCAG 2.1 Level AA Compliance
+All components are designed to meet WCAG 2.1 Level AA standards. Agents must not modify component behavior in ways that break accessibility.
+
+## Testing Expectations
+
+### Unit Testing with Vitest
+- Test files use `vitest` and `@testing-library/react`
+- Pattern: `ComponentName.test.tsx` in `__tests__/components/`
+- Expect components to accept standard React props (ref, className, etc.)
+- Use `render()` from `@testing-library/react`
+
+```typescript
+import { render, screen } from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+import { Button } from '@publicplan/kern-react-kit';
+
+describe('Button', () => {
+  test('renders with text', () => {
+    render(<Button>Click me</Button>);
+    expect(screen.getByRole('button', { name: /click me/i })).toBeInTheDocument();
+  });
+
+  test('fires onClick handler', async () => {
+    const user = userEvent.setup();
+    const handleClick = vi.fn();
+    render(<Button onClick={handleClick}>Click</Button>);
+    await user.click(screen.getByRole('button'));
+    expect(handleClick).toHaveBeenCalled();
+  });
+});
+```
+
+### Storybook Stories
+- All components have Storybook stories for isolated development
+- Location: `ComponentName.stories.tsx` co-located with component
+- Stories demonstrate default, variant, and edge-case states
+- Use Storybook Docs addon for automatically generated documentation
+
+### E2E Testing with Playwright
+- E2E tests live in `__tests__/e2e/`
+- Test real user workflows in a browser
+- Pattern: Playwright test files (`.spec.ts`)
+
+## Build Artifacts
+
+### What Gets Published
+The `package.json` has `"files": ["dist/"]`, so only the `dist/` folder is published to npm:
+- `dist/index.js` (ESM)
+- `dist/index.cjs` (CommonJS)
+- `dist/index.css` (Compiled stylesheet)
+- `dist/index.d.ts` (Type definitions)
+- `dist/components/*/index.{js,cjs,d.ts}` (Component exports)
+- `dist/skills/` (This skill documentation—included!)
+
+### Build Command
+```bash
+npm run build
+```
+
+This runs:
+1. `build:skills` – Copy skill docs from `skills/` to `dist/skills/`
+2. `tsdown` – Transpile TypeScript and output ESM/CJS to `dist/`
+3. `sass` – Compile global styles to `dist/index.css`
+
+### Incremental Builds
+For development, use:
+```bash
+npm run dev
+```
+
+This starts Vite in dev mode for fast iteration.
+
+## CommonJS & ESM Compatibility
+
+### Module Resolution
+The package exports both ESM and CommonJS entry points:
+
+**ESM (Node 12+, modern bundlers)**:
+```javascript
+import { Button } from '@publicplan/kern-react-kit';
+```
+
+**CommonJS (Node.js)**:
+```javascript
+const { Button } = require('@publicplan/kern-react-kit');
+```
+
+Both are compiled from the same TypeScript source and have identical behavior.
+
+### Tree-Shaking
+ESM builds support tree-shaking. Unused components are removed during bundling:
+```javascript
+// Only Button code is included in the bundle
+import { Button } from '@publicplan/kern-react-kit';
+```
+
+## Performance Considerations
+
+### Component Rendering
+- Components are optimized with `React.memo` where beneficial
+- Avoid passing inline objects as props (memoize or use useMemo)
+- Use `ref` for imperative operations sparingly
+
+Example:
+```typescript
+// ✅ Good: Stable object
+const buttonProps = { variant: 'primary' as const };
+<Button {...buttonProps}>Click</Button>
+
+// ❌ Avoid: Inline object recreated on each render
+<Button {...{ variant: 'primary' }}>Click</Button>
+```
+
+### Bundle Size
+Kern React Kit is a lean library (~45KB gzipped including CSS). Avoid importing unused components; modern bundlers tree-shake unused code automatically.
+
+## Debugging
+
+### Enable Debug Logging
+Some components log development hints (e.g., missing required props) in development mode. Check the browser console.
+
+### Check Compiled Styles
+If styles don't apply, verify:
+1. `@publicplan/kern-react-kit/index.css` is imported in your app
+2. CSS custom properties are defined (fallback values apply if missing)
+3. No CSS specificity conflicts override component styles
+
+### Type Checking
+Run TypeScript compiler in watch mode:
+```bash
+npx tsc --noEmit --watch
+```
+
+## Versioning & Compatibility Matrix
+
+| React Version | Kern Kit Support |
+|---|---|
+| 18.2.0 – 18.x | ✅ Full |
+| 19.1.0+ | ✅ Full |
+| < 18.2.0 | ❌ Not supported |
+
+Semantic versioning is used:
+- **Major**: Breaking changes (e.g., removed components, prop signature changes)
+- **Minor**: New features, new components (backward compatible)
+- **Patch**: Bug fixes, security updates
+
+---
+
+*Last updated: 2026-03-03*

package/dist/skills/skills.index.json

@@ -0,0 +1,10 @@
+{
+  "package": "@publicplan/kern-react-kit",
+  "skills": [
+    {
+      "name": "kern-react-kit",
+      "path": "dist/skills/kern-react-kit/SKILL.md",
+      "entry": "dist/skills/kern-react-kit/SKILL.md"
+    }
+  ]
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@publicplan/kern-react-kit",
-  "version": "1.3.1",
+  "version": "1.3.3",
   "type": "module",
   "main": "dist/index.cjs",
   "module": "dist/index.js",
@@ -19,6 +19,8 @@
       }
     },
     "./index.css": "./dist/index.css",
+    "./skills": "./dist/skills/skills.index.json",
+    "./skills/kern-react-kit": "./dist/skills/kern-react-kit/SKILL.md",
     "./*": {
       "import": {
         "types": "./dist/components/*/index.d.ts",
@@ -40,14 +42,16 @@
   "scripts": {
     "prepare": "husky install",
     "dev": "vite --config vite.lib.config.ts",
-    "build": "tsdown && sass src/styles/global.scss dist/index.css --no-source-map",
+    "build:skills": "node scripts/build-skills.mjs",
+    "build": "tsdown && npm run build:skills && sass src/styles/global.scss dist/index.css --no-source-map",
     "lint": "eslint \"./src/**/*.{ts,tsx}\" --ext ts,tsx --report-unused-disable-directives --max-warnings 0",
     "lint:fix": "eslint \"./src/**/*.{ts,tsx}\" --ext ts,tsx --report-unused-disable-directives --fix",
     "test": "vitest",
     "test:watch": "vitest --watch",
     "format": "prettier --ignore-path .gitignore \"./src/**/*.+(ts|js|tsx)\" --write",
     "storybook": "storybook dev --port 6006",
-    "storybook:build": "storybook build -o storybooks/public"
+    "storybook:build": "storybook build -o storybooks/public",
+    "test:e2e": "start-server-and-test storybook http://localhost:6006 'playwright test'"
   },
   "keywords": [],
   "author": "publicplan",
@@ -57,10 +61,11 @@
     "react-dom": "^18.2.0 || ^19.1.0"
   },
   "dependencies": {
-    "@kern-ux/native": "^2.3.0",
+    "@kern-ux/native": "^2.4.0",
     "tslib": "^2.8.1"
   },
   "devDependencies": {
+    "@playwright/test": "^1.58.2",
     "@semantic-release/changelog": "^6.0.3",
     "@semantic-release/commit-analyzer": "^13.0.1",
     "@semantic-release/git": "^10.0.1",
@@ -90,6 +95,7 @@
     "jsdom": "^27.0.0",
     "prettier": "^3.5.3",
     "sass": "^1.89.0",
+    "start-server-and-test": "^2.1.3",
     "storybook-addon-pseudo-states": "^9.1.8",
     "tsdown": "^0.14.1",
     "typescript": "^5.8.3",