Skip to content

Commit ae28a5b

Browse files
bvallierbvallier
committed
release: v1.0.60
1 parent c7a4816 commit ae28a5b

9 files changed

Lines changed: 475 additions & 6 deletions

File tree

‎AGENTS.md‎

Lines changed: 181 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,181 @@
1+
# TinyPivot Agent Guide
2+
3+
Monorepo containing a framework-agnostic core library and wrappers for Vue 3 and React.
4+
5+
## MANDATORY: Build for Both Vue AND React
6+
7+
**STOP! Before implementing ANY feature, bug fix, or UI change:**
8+
9+
1. You MUST implement it in BOTH `packages/vue` AND `packages/react`
10+
2. A task is NOT complete until both frameworks have the feature
11+
3. Never submit work that only updates one framework
12+
13+
**Checklist for EVERY change:**
14+
- [ ] Implemented in `packages/vue`
15+
- [ ] Implemented in `packages/react`
16+
- [ ] Both implementations have identical behavior
17+
- [ ] Both implementations have identical appearance
18+
- [ ] Shared logic moved to `packages/core`
19+
- [ ] `pnpm type-check` passes
20+
- [ ] `pnpm build` succeeds
21+
22+
## Project Structure
23+
24+
```
25+
packages/
26+
core/ # Shared logic, types, utilities (framework-agnostic)
27+
vue/ # Vue 3 components (uses core)
28+
react/ # React components (uses core)
29+
demo/ # Demo application (Vue-based)
30+
```
31+
32+
## Build & Verification Commands
33+
34+
**No automated tests exist.** Verification relies on type-checking and manual demo testing.
35+
36+
| Command | Description |
37+
|---------|-------------|
38+
| `pnpm install` | Install dependencies |
39+
| `pnpm build` | Build all packages (core → vue → react) |
40+
| `pnpm dev` | Watch mode for all packages |
41+
| `pnpm type-check` | **CRITICAL:** Run after any change |
42+
| `pnpm demo` | Start demo app for manual verification |
43+
44+
Build individual packages:
45+
```bash
46+
pnpm --filter @smallwebco/tinypivot-core build
47+
pnpm --filter @smallwebco/tinypivot-vue build
48+
pnpm --filter @smallwebco/tinypivot-react build
49+
```
50+
51+
## Code Style & Conventions
52+
53+
### TypeScript
54+
- **Strict mode enabled** - No `any` unless absolutely necessary
55+
- **Shared types** go in `packages/core/src/types/index.ts`
56+
- **Export all public APIs** in each package's `index.ts`
57+
58+
### Import Order
59+
```typescript
60+
// 3. Core package imports (types first)
61+
import type { ColumnStats } from '@smallwebco/tinypivot-core'
62+
import { exportToCSV } from '@smallwebco/tinypivot-core'
63+
// 1. Framework imports (React/Vue)
64+
import React, { useCallback, useMemo, useState } from 'react'
65+
// 2. Third-party libraries
66+
import { createPortal } from 'react-dom'
67+
// 4. Local imports (hooks/composables, then components)
68+
import { useExcelGrid } from '../hooks/useExcelGrid'
69+
import { ColumnFilter } from './ColumnFilter'
70+
```
71+
72+
### Vue Components (`packages/vue`)
73+
- Use `<script setup lang="ts">` with Composition API
74+
- Use scoped CSS with `.vpg-` prefixed class names
75+
- PascalCase for component files (e.g., `DataGrid.vue`)
76+
77+
```vue
78+
<script setup lang="ts">
79+
const props = withDefaults(defineProps<{
80+
data: Record<string, unknown>[]
81+
loading?: boolean
82+
}>(), { loading: false })
83+
84+
const emit = defineEmits<{
85+
(e: 'cellClick', payload: { row: number, col: number }): void
86+
}>()
87+
</script>
88+
```
89+
90+
### React Components (`packages/react`)
91+
- Functional components with hooks only
92+
- Use `useCallback` for event handlers, `useMemo` for expensive computations
93+
- Match Vue's prop interface exactly
94+
95+
```tsx
96+
interface DataGridProps {
97+
data: Record<string, unknown>[]
98+
loading?: boolean
99+
onCellClick?: (payload: { row: number, col: number }) => void
100+
}
101+
102+
export function DataGrid({ data, loading = false, onCellClick }: DataGridProps) {
103+
// ...
104+
}
105+
```
106+
107+
### Core Package (`packages/core`)
108+
- Keep functions pure and framework-agnostic
109+
- No DOM manipulation or framework-specific APIs
110+
- Export type guards alongside types (e.g., `isNumericRange`)
111+
112+
### Naming Conventions
113+
114+
| Type | Convention | Example |
115+
|------|------------|---------|
116+
| Components | PascalCase | `DataGrid`, `ColumnFilter` |
117+
| Hooks/Composables | camelCase with `use` prefix | `useExcelGrid` |
118+
| Types/Interfaces | PascalCase | `PivotConfig`, `ColumnStats` |
119+
| CSS Classes | kebab-case with `vpg-` prefix | `vpg-data-grid` |
120+
| Constants | SCREAMING_SNAKE_CASE | `MIN_COL_WIDTH` |
121+
122+
### Error Handling
123+
- Use early returns for validation
124+
- Provide sensible defaults over throwing errors
125+
- Handle null/undefined gracefully in display functions
126+
127+
```typescript
128+
function formatCellValue(value: unknown): string {
129+
if (value === null || value === undefined)
130+
return ''
131+
return String(value)
132+
}
133+
```
134+
135+
## Workflow for Agents
136+
137+
1. **Analyze**: Check `packages/core` first. Can the change be shared?
138+
2. **Implement**:
139+
- Modify `packages/core` if needed
140+
- Implement in **Framework A** (e.g., Vue)
141+
- **IMMEDIATELY** port to **Framework B** (e.g., React)
142+
3. **Verify**:
143+
- Run `pnpm type-check` to catch API mismatches
144+
- Run `pnpm build` to ensure successful compilation
145+
- (Optional) Check `pnpm demo` if UI changes were made
146+
4. **Commit**: Message should reflect changes in both frameworks
147+
148+
**REMINDER: A feature is NOT done until it exists in both Vue and React.**
149+
150+
## Cursor/Copilot Rules
151+
152+
From `.cursor/rules/vuereact.mdc`:
153+
> "When writing code, make sure to address the issue at hand for both Vue and React... goal is to have the same codebase... which should live in core."
154+
155+
## Key Files Reference
156+
157+
| Purpose | Vue | React |
158+
|---------|-----|-------|
159+
| Main Component | `packages/vue/src/components/DataGrid.vue` | `packages/react/src/components/DataGrid.tsx` |
160+
| Grid Logic | `packages/vue/src/composables/useExcelGrid.ts` | `packages/react/src/hooks/useExcelGrid.ts` |
161+
| Pivot Logic | `packages/vue/src/composables/usePivotTable.ts` | `packages/react/src/hooks/usePivotTable.ts` |
162+
| Shared Types | `packages/core/src/types/index.ts` | (imports from core) |
163+
| Styles | `packages/vue/src/style.css` | `packages/react/src/style.css` |
164+
165+
## Common Patterns
166+
167+
### Adding a New Prop
168+
1. Add to `DataGridProps` in `packages/core/src/types/index.ts`
169+
2. Add to Vue component's `defineProps` with default
170+
3. Add to React component's interface with default in destructuring
171+
4. Implement feature logic in both frameworks
172+
173+
### Adding a New Event
174+
1. Add event type to `packages/core/src/types/index.ts`
175+
2. Vue: Add to `defineEmits`, call with `emit('eventName', payload)`
176+
3. React: Add callback prop (`onEventName`), call with `onEventName?.(payload)`
177+
178+
### Adding Shared Utility
179+
1. Create function in `packages/core/src/utils/index.ts`
180+
2. Export from `packages/core/src/index.ts`
181+
3. Import in both packages from `@smallwebco/tinypivot-core`

‎CLAUDE.md‎

Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,24 @@
1+
# TinyPivot Project Rules
2+
3+
## Multi-Framework Sync
4+
5+
This project provides both Vue and React packages. When implementing a feature or fix:
6+
7+
- **Always implement in both frameworks**: Any feature, bug fix, or UI change made to the Vue package (`packages/vue`) must also be implemented in the React package (`packages/react`), and vice versa.
8+
- **Keep implementations consistent**: The behavior, appearance, and API should match as closely as possible between frameworks.
9+
- **Test both builds**: Run `pnpm build:vue` and `pnpm build:react` (or `pnpm build`) to verify both packages compile successfully.
10+
11+
## Package Structure
12+
13+
- `packages/core` - Shared logic, types, and utilities (framework-agnostic)
14+
- `packages/vue` - Vue 3 components
15+
- `packages/react` - React components
16+
17+
## Component Correspondence
18+
19+
| Vue Component | React Component |
20+
|--------------|-----------------|
21+
| `PivotSkeleton.vue` | `PivotSkeleton.tsx` |
22+
| `DataGrid.vue` | `DataGrid.tsx` |
23+
| `PivotConfig.vue` | `PivotConfig.tsx` |
24+
| `ColumnFilter.vue` | `ColumnFilter.tsx` |

0 commit comments

Comments
 (0)