diff --git a/.rules/guidelines/coding.md b/.rules/guidelines/coding.md index 0d657d79c..88660cc58 100644 --- a/.rules/guidelines/coding.md +++ b/.rules/guidelines/coding.md @@ -30,8 +30,6 @@ Guidelines for Approaching Code Tasks - **Optimize only after functionality is correct** and only where necessary - **Consider maintenance implications** of the implementation - - ## Rationale This structured approach prevents several common issues: diff --git a/.rules/instructions.md b/.rules/instructions.md index 4cbca5075..53ab875f1 100644 --- a/.rules/instructions.md +++ b/.rules/instructions.md @@ -80,12 +80,15 @@ Provide progress updates and explain technical decisions. ## Monorepo Structure & Guidelines ### Project Structure + This is a monorepo with the following structure: + - `packages/` - Library packages (e.g., @rokkit/forms, @rokkit/ui, @rokkit/core) - `sites/` - Demo sites and documentation (e.g., sites/learn) - `apps/` - Applications (if present) ### Library Development (`packages/`) + - Create reusable components and utilities - Follow semantic versioning - Include comprehensive TypeScript definitions @@ -93,6 +96,7 @@ This is a monorepo with the following structure: - Test thoroughly before publishing ### Demo Development (`sites/`) + - Use library packages as dependencies - Use components from the packages (ex. @rokkit/ui) for the demo. Any custom components in the site should build on top of the library components. - Create progressive examples showing feature evolution @@ -100,6 +104,7 @@ This is a monorepo with the following structure: - Include educational documentation ### Styling Guidelines + - Use UnoCSS utility classes throughout - Follow neutral color palette: `neutral-50`, `neutral-100`, etc. - Use semantic colors: `primary-`, `secondary-`, `accent-`, `error-`, `warning-`, `success-` diff --git a/.rules/project/structure.md b/.rules/project/structure.md index d70efb8c2..501359260 100644 --- a/.rules/project/structure.md +++ b/.rules/project/structure.md @@ -24,23 +24,24 @@ rokkit/ This repository contains the following packages with their corresponding folder locations: -| Package Name | Folder Location | Description | -|--------------|-----------------|-------------| -| `@rokkit/actions` | `packages/actions/` | Action utilities and helpers | -| `@rokkit/bits-ui` | `packages/bits-ui/` | Data-driven UI components based on bits-ui | -| `@rokkit/chart` | `packages/chart/` | Chart and visualization components | -| `@rokkit/cli` | `packages/cli/` | Command line interface tools | -| `@rokkit/core` | `packages/core/` | Core utilities and shared code | -| `@rokkit/data` | `packages/data/` | Data manipulation utilities | -| `@rokkit/forms` | `packages/forms/` | Form builder system | -| `@rokkit/helpers` | `packages/helpers/` | Helper functions and utilities | -| `@rokkit/icons` | `packages/icons/` | Icon components and utilities | -| `@rokkit/states` | `packages/states/` | State management utilities | -| `@rokkit/themes` | `packages/themes/` | Theme and styling utilities | -| `@rokkit/tutorial` | `packages/tutorial/` | Tutorial and learning components | -| `@rokkit/ui` | `packages/ui/` | UI component library | +| Package Name | Folder Location | Description | +| ------------------ | -------------------- | ------------------------------------------ | +| `@rokkit/actions` | `packages/actions/` | Action utilities and helpers | +| `@rokkit/bits-ui` | `packages/bits-ui/` | Data-driven UI components based on bits-ui | +| `@rokkit/chart` | `packages/chart/` | Chart and visualization components | +| `@rokkit/cli` | `packages/cli/` | Command line interface tools | +| `@rokkit/core` | `packages/core/` | Core utilities and shared code | +| `@rokkit/data` | `packages/data/` | Data manipulation utilities | +| `@rokkit/forms` | `packages/forms/` | Form builder system | +| `@rokkit/helpers` | `packages/helpers/` | Helper functions and utilities | +| `@rokkit/icons` | `packages/icons/` | Icon components and utilities | +| `@rokkit/states` | `packages/states/` | State management utilities | +| `@rokkit/themes` | `packages/themes/` | Theme and styling utilities | +| `@rokkit/tutorial` | `packages/tutorial/` | Tutorial and learning components | +| `@rokkit/ui` | `packages/ui/` | UI component library | ### Key Package Dependencies + - `@rokkit/core` - Can be used by any package (foundational utilities) - `@rokkit/states` - Used by UI packages for data management - `@rokkit/bits-ui` - Provides data-driven wrappers for bits-ui components @@ -50,11 +51,13 @@ This repository contains the following packages with their corresponding folder ## Package Development (`packages/`) ### Purpose + - Create reusable, framework-agnostic libraries - Provide core functionality for the Rokkit ecosystem - Maintain strict separation of concerns ### Guidelines + - Each package should have a clear, single responsibility - Use semantic versioning for releases - Include comprehensive TypeScript definitions @@ -62,6 +65,7 @@ This repository contains the following packages with their corresponding folder - Test all public APIs extensively ### Structure Pattern + ``` packages/[package-name]/ ├── src/ @@ -77,17 +81,20 @@ packages/[package-name]/ ## Site Development (`sites/`) ### Purpose + - Demonstrate library package capabilities - Provide educational content and examples - Show progressive enhancement patterns ### Guidelines + - Import packages as dependencies (e.g., `@rokkit/forms`) - Create step-by-step learning experiences - Follow established styling patterns - Include both basic and advanced examples ### Learning Site Structure (`sites/learn/`) + ``` sites/learn/ ├── src/ @@ -103,12 +110,14 @@ sites/learn/ ## Development Workflow ### Package Development + 1. Develop in `packages/[name]/src/` 2. Test thoroughly with unit and integration tests 3. Update documentation in `packages/[name]/docs/` 4. Version according to semantic versioning ### Demo Development + 1. Import published packages or use workspace references 2. Create progressive examples in `sites/learn/src/lib/future/` 3. Build route pages in `sites/learn/src/routes/` @@ -117,12 +126,14 @@ sites/learn/ ## Styling System ### UnoCSS Conventions + - **Neutral Colors**: `neutral-50` through `neutral-900` - **Semantic Colors**: `primary-`, `secondary-`, `accent-`, `error-`, `warning-`, `success-` - **Dark Mode**: Always include `dark:` variants - **Interactive States**: Use `hover:`, `focus:`, `active:` variants ### Color Patterns + ```css /* Backgrounds */ bg-surface-50 dark:bg-surface-900 /* Page backgrounds */ @@ -146,12 +157,14 @@ focus:ring-2 focus:ring-primary-500 ## Documentation Standards ### Package Documentation + - Clear API reference in `docs/` folder - Usage examples with code snippets - Migration guides for breaking changes - Contributing guidelines ### Demo Documentation + - Step-by-step tutorials - Progressive complexity examples - Real-world use cases @@ -160,11 +173,13 @@ focus:ring-2 focus:ring-primary-500 ## Cross-Package Dependencies ### Allowed Dependencies + - `@rokkit/core` can be used by any package - UI packages can depend on core utilities - Sites can use any published package ### Dependency Guidelines + - Minimize cross-package dependencies - Use peer dependencies for optional features - Document all external dependencies clearly diff --git a/CLAUDE.md b/CLAUDE.md index 802dd4628..1556ccce5 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -9,7 +9,9 @@ Rokkit is a cutting-edge data-driven UI library built for Svelte 5. It empowers ## Core Principles ### Data-First Design + Components automatically understand and adapt to data structures without requiring data transformation: + ```svelte @@ -17,7 +19,9 @@ Components automatically understand and adapt to data structures without requiri ``` ### Composable Flexibility + Every component is extensible without modification through snippets and component overrides: + ```svelte {#snippet customItem(node)} @@ -27,7 +31,9 @@ Every component is extensible without modification through snippets and componen ``` ### Consistent API Patterns + All selection components follow the same pattern: + - `items`: Data array - `value`: Selected item(s) (bindable) - `fields`: Field mapping configuration @@ -35,7 +41,6 @@ All selection components follow the same pattern: - `child`: Optional child snippet used for specific item. Takes a `Proxy` class instance as input - `children`: standard children snippet for use in key value composite structures like Tabs/TabsGroup - ## Architecture The project is organized as a Bun workspace monorepo with the following structure: @@ -62,6 +67,7 @@ The project is organized as a Bun workspace monorepo with the following structur ## Common Development Commands ### Root Level Commands (Bun Workspace) + - `bun test:unit` - Run unit tests - `bun test:ci` - Run tests in CI mode - `bun coverage` - Generate test coverage report @@ -71,19 +77,24 @@ The project is organized as a Bun workspace monorepo with the following structur - `bun publish:all` - Publish all packages ### Package-Level Commands + Most packages support these commands: + - `bun build` - Build the package - `bun clean` - Clean build artifacts - `bun prepublishOnly` - Prepare for publishing (TypeScript compilation) ### Site Development + For the learn site (must cd into `sites/learn/` first): + - `cd sites/learn && bun dev` - Start development server - `cd sites/learn && bun build` - Build for production - `cd sites/learn && bun preview` - Preview built site - `cd sites/learn && bun test:e2e` - Run end-to-end tests ### Testing + - `bun test:unit` - Run unit tests (from project root) ## Key Technologies @@ -99,13 +110,16 @@ For the learn site (must cd into `sites/learn/` first): ## Development Workflow ### CRITICAL: Progress Tracking + **MUST UPDATE** `.rules/project/progress.md` after any changes to: + - Component status (🔄 In Progress, ✅ Complete, etc.) - Implementation decisions made - Technical challenges encountered - Quality gate completions ### Before Starting Any Component Work + 1. **Ask clarifying questions** to understand requirements 2. **Analyze existing codebase** and provide clear understanding 3. **Present implementation strategy** with step-by-step approach @@ -113,7 +127,9 @@ For the learn site (must cd into `sites/learn/` first): 5. **Confirm approach** before writing any code ### Component Development Standards + All components MUST follow these patterns: + ```svelte let { items = [], // Data array @@ -124,7 +140,9 @@ let { ``` ### Data Handling Pattern + Use the Proxy system from `@rokkit/states` for consistent data access: + ```svelte import { Proxy } from '@rokkit/states' @@ -135,6 +153,7 @@ let proxyItems = $derived(items.map(item => new Proxy(item, fields))) ## Component Implementation Requirements ### Structure Standards + 1. **No internal styling** - components must be completely unstyled 2. **Data attributes only** - use `data-component-element` pattern for styling hooks 3. **Proxy system** - use `@rokkit/states` Proxy for all data access @@ -142,6 +161,7 @@ let proxyItems = $derived(items.map(item => new Proxy(item, fields))) 5. **Accessibility** - proper ARIA attributes and keyboard navigation ### bits-ui Integration + - Use bits-ui components as foundation when available - Wrap with Rokkit API layer (items, fields, value props) - Preserve bits-ui data attributes for theming @@ -150,6 +170,7 @@ let proxyItems = $derived(items.map(item => new Proxy(item, fields))) ## Code Quality Rules The project enforces strict code quality through ESLint: + - Maximum function complexity of 5 - Maximum function length of 30 lines - Maximum nesting depth of 3 @@ -168,6 +189,7 @@ The project enforces strict code quality through ESLint: ## Styling System ### UnoCSS Conventions + - **Neutral Colors**: `neutral-50` through `neutral-900` - **Semantic Colors**: `primary-`, `secondary-`, `accent-`, `error-`, `warning-`, `success-` - **Dark Mode**: Always include `dark:` variants. @@ -175,6 +197,7 @@ The project enforces strict code quality through ESLint: - **Interactive States**: Use `hover:`, `focus:`, `active:` variants ### Color Patterns + ```css /* Backgrounds */ bg-surface-z2 /* Page backgrounds */ @@ -195,6 +218,7 @@ Packages use `workspace:latest` for internal dependencies to ensure consistency ## Quality Requirements Before any component is complete: + - [ ] Follows standard prop pattern (items, value, fields) - [ ] Uses Proxy system for data access - [ ] Supports snippet customization @@ -209,12 +233,13 @@ Before any component is complete: ## Field Mapping System Components adapt to any data structure through the field mapping system: + ```javascript // Custom mapping const fields = { - text: 'name', // Map 'name' to text display - image: 'avatar', // Map 'avatar' to image display - children: 'items' // Map 'items' to nested children + text: 'name', // Map 'name' to text display + image: 'avatar', // Map 'avatar' to image display + children: 'items' // Map 'items' to nested children } ``` @@ -225,6 +250,7 @@ The learn site uses a `StoryBuilder` class for managing interactive examples and ### Basic Usage **stories.js** + ```javascript import { StoryBuilder } from '$lib/components/Story/builder.svelte.js' @@ -235,6 +261,7 @@ export const storyBuilder = new StoryBuilder(sources, modules) ``` **+page.svelte** + ```svelte