feat: add starlight dev server & plop

Author: itsmedardan

.gitignore

@@ -1,22 +1,57 @@
+# Dependencies
+node_modules/
+.pnp
+.pnp.js
+
+# Build outputs
 dist/
+.stencil/
+.turbo/
+.astro/
 
-*~
-*.sw[mnpcod]
+# Testing
+coverage/
+*.spec.js.map
+
+# Logs
 *.log
-*.lock
-*.tmp
-*.tmp.*
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+pnpm-debug.log*
+lerna-debug.log*
 log.txt
+
+# Editor
+*~
+*.sw[mnpcod]
 *.sublime-project
 *.sublime-workspace
+.vscode/*
+!.vscode/extensions.json
+!.vscode/settings.json
+.idea/
 
-.stencil/
+# Temporary
+*.tmp
+*.tmp.*
+*.lock
+
+# Cache
 .sass-cache/
 .versions/
-node_modules/
-$RECYCLE.BIN/
+.cache/
 
+# OS
 .DS_Store
 Thumbs.db
 UserInterfaceState.xcuserstate
+$RECYCLE.BIN/
+
+# Environment
 .env
+.env.local
+.env.production
+
+# Storybook
+storybook-static/

README.md

@@ -0,0 +1,239 @@
+# J26 Web Components
+
+A monorepo containing Stencil web components, design tokens, and Astro Starlight documentation.
+
+## Prerequisites
+
+- Node.js (v18 or higher)
+- pnpm (v10.7.0 or higher)
+
+## Getting Started
+
+```bash
+# Install dependencies
+pnpm install
+
+# Start development (builds tokens & components, starts hot reload for all packages)
+pnpm dev
+```
+
+The dev server will start:
+- Design tokens watch mode (rebuilds on changes)
+- Components watch mode (rebuilds on changes)
+- Astro Starlight docs (http://localhost:4321)
+
+## Available Scripts
+
+All commands should be run from the **root directory**.
+
+### Development
+
+```bash
+# Start full development environment with hot reloading
+# (Builds tokens & components, then starts watch mode for all)
+pnpm dev
+
+# Fast component-only dev with Stencil's built-in HMR server
+# (Faster rebuilds, but components shown in Stencil's UI, not Astro)
+pnpm dev:components
+
+# Start only docs (components must be built first)
+pnpm docs:dev
+
+# Start Storybook (legacy, use docs instead)
+pnpm storybook
+```
+
+**Hot Reloading Performance:**
+- **Token changes**: ~50-200ms rebuild time
+- **Component changes**: ~1-3s rebuild time (optimized with incremental builds)
+- **Astro doc changes**: Instant HMR
+- Use `pnpm dev:components` for fastest component iteration (Stencil's dev server with native HMR)
+
+### Building
+
+```bash
+# Build tokens and components only
+pnpm build
+
+# Build everything (tokens, components, and docs)
+pnpm build:all
+
+# Build specific packages
+pnpm tokens:build
+pnpm components:build
+pnpm docs:build
+
+# Preview production docs build
+pnpm docs:preview
+```
+
+### Testing
+
+```bash
+# Run unit tests
+pnpm test
+
+# Run tests in watch mode
+pnpm test:watch
+
+# Run E2E tests
+pnpm test:e2e
+```
+
+### Code Quality
+
+```bash
+# Check code with Biome
+pnpm lint
+
+# Fix linting issues
+pnpm lint:fix
+
+# Format code
+pnpm format
+```
+
+### Generating Components
+
+```bash
+# Generate a new component with plop
+pnpm plop
+
+# Or use Stencil's generator
+pnpm generate
+```
+
+The plop generator will:
+- Create component files (.tsx, .css, .spec.ts, .e2e.ts, .stories.tsx)
+- Generate Starlight documentation (with consistent structure)
+- Update package.json exports automatically
+
+### Cleanup
+
+```bash
+# Remove all node_modules and build artifacts
+pnpm clean
+
+# Clean and reinstall dependencies
+pnpm clean:install
+
+# Clean build artifacts and rebuild
+pnpm clean:build
+```
+
+## Project Structure
+
+```
+j26-web-components/
+├── packages/
+│   ├── design-tokens/    # Design tokens (CSS custom properties)
+│   ├── ui-webc/          # Stencil web components
+│   └── docs/             # Astro Starlight documentation
+├── package.json          # Root package with scripts
+└── pnpm-workspace.yaml   # Workspace configuration
+```
+
+## Creating a New Component
+
+1. Run the plop generator:
+   ```bash
+   pnpm plop
+   ```
+
+2. Follow the prompts:
+   - Component name (e.g., `my-button`)
+   - Component description
+
+3. The generator creates:
+   - Component files in `packages/ui-webc/src/components/`
+   - Documentation in `packages/docs/src/content/docs/components/`
+
+4. Customize the generated files:
+   - Update component logic in `.tsx` file
+   - Add styles in `.css` file
+   - Update documentation with real examples
+   - Customize API reference (props, events)
+   - Add variants and examples
+
+5. Test your component:
+   ```bash
+   pnpm dev
+   ```
+   Navigate to http://localhost:4321 to see your component documentation.
+
+## Documentation Structure
+
+All component documentation follows this structure:
+
+1. **Overview** - Brief description of the component
+2. **Installation** - How to install the package
+3. **Usage** - TypeScript and HTML examples
+4. **API Reference** - Properties and Events tables
+5. **Examples** - Default example with preview
+6. **Variants** - Different component variations
+
+## Development Workflow
+
+1. **Start development**: `pnpm dev`
+2. **Make changes** to components in `packages/ui-webc/src/components/`
+3. **View changes** in Astro docs at http://localhost:4321
+4. **Add/update documentation** in `packages/docs/src/content/docs/`
+5. **Test** with `pnpm test`
+6. **Lint** with `pnpm lint:fix`
+7. **Build** with `pnpm build` before committing
+
+## Using Components
+
+### Installation
+
+```bash
+npm install @scouterna/ui-webc
+```
+
+### Usage
+
+```typescript
+// Import and register the components
+import { defineCustomElements } from '@scouterna/ui-webc/loader';
+
+defineCustomElements();
+```
+
+```html
+<!-- Use components in your HTML -->
+<scout-button variant="primary">Click me</scout-button>
+```
+
+## Troubleshooting
+
+### Components not loading in docs
+
+Make sure you've built the components:
+```bash
+pnpm components:build
+```
+
+### Design tokens not found
+
+Build tokens first:
+```bash
+pnpm tokens:build
+```
+
+### Clean start
+
+If you encounter issues, try a clean rebuild:
+```bash
+pnpm clean:install
+pnpm dev
+```
+
+## Contributing
+
+1. Create a new component with `pnpm plop`
+2. Follow the existing component structure
+3. Update documentation with real examples
+4. Add tests for your component
+5. Run `pnpm lint:fix` before committing
+6. Ensure `pnpm build` succeeds

package.json

@@ -3,8 +3,27 @@
   "private": true,
   "license": "MIT",
   "scripts": {
+    "dev": "pnpm tokens:build && pnpm components:build && pnpm -r --parallel --filter=\"@scouterna/design-tokens\" --filter=\"@scouterna/ui-webc\" --filter=\"docs\" dev",
+    "dev:components": "pnpm tokens:build && pnpm --filter @scouterna/ui-webc dev",
+    "build": "pnpm -r --filter @scouterna/design-tokens --filter @scouterna/ui-webc build",
+    "build:all": "pnpm -r --filter @scouterna/design-tokens --filter @scouterna/ui-webc --filter docs build",
+    "tokens:build": "pnpm --filter @scouterna/design-tokens build",
+    "components:build": "pnpm --filter @scouterna/ui-webc build",
+    "docs:dev": "pnpm --filter docs dev",
+    "docs:build": "pnpm --filter docs build",
+    "docs:preview": "pnpm --filter docs preview",
+    "test": "pnpm --filter @scouterna/ui-webc test",
+    "test:watch": "pnpm --filter @scouterna/ui-webc test.watch",
+    "test:e2e": "pnpm --filter @scouterna/ui-webc test.e2e",
     "lint": "biome check",
-    "lint:fix": "biome check --write"
+    "lint:fix": "biome check --write",
+    "format": "biome format --write .",
+    "plop": "pnpm --filter @scouterna/ui-webc plop",
+    "generate": "pnpm --filter @scouterna/ui-webc generate",
+    "storybook": "pnpm tokens:build && pnpm -r --parallel --filter=\"@scouterna/design-tokens\" --filter=\"@scouterna/ui-webc\" dev",
+    "clean": "pnpm -r exec rm -rf node_modules dist .turbo .stencil .astro && rm -rf node_modules",
+    "clean:install": "pnpm clean && pnpm install",
+    "clean:build": "pnpm -r exec rm -rf dist .turbo .stencil .astro && pnpm build:all"
   },
   "devDependencies": {
     "@biomejs/biome": "2.2.0",

packages/design-tokens/package.json

@@ -11,7 +11,9 @@
   ],
   "type": "module",
   "scripts": {
-    "build": "node build-tokens.mjs"
+    "build": "node build-tokens.mjs",
+    "watch": "node --watch build-tokens.mjs",
+    "dev": "node --watch build-tokens.mjs"
   },
   "keywords": [],
   "author": "",

packages/docs/astro.config.mjs

@@ -17,7 +17,21 @@ export default defineConfig({
       customCss: [
         "@scouterna/design-tokens/tokens.css",
         "./src/styles/global.css",
+        "./src/styles/components.css",
+        "./src/styles/highlight.css",
       ],
+      head: [
+        {
+          tag: 'script',
+          attrs: {
+            src: '/component-loader.js',
+            type: 'module',
+          },
+        },
+      ],
+      components: {
+        Head: './src/components/ComponentLoader.astro',
+      },
       social: [
         {
           icon: "github",
@@ -33,6 +47,10 @@ export default defineConfig({
             { label: "Example Guide", slug: "guides/example" },
           ],
         },
+        {
+          label: "Components",
+          autogenerate: { directory: "components" },
+        },
         {
           label: "Reference",
           autogenerate: { directory: "reference" },
@@ -47,5 +65,19 @@ export default defineConfig({
 
   vite: {
     plugins: [tailwindcss()],
+    server: {
+      watch: {
+        // Watch the ui-webc source files for faster HMR
+        ignored: ['!**/node_modules/@scouterna/ui-webc/**'],
+      },
+      fs: {
+        // Allow serving files from the monorepo root
+        allow: ['../..'],
+      },
+    },
+    optimizeDeps: {
+      // Don't pre-bundle the components so changes are picked up faster
+      exclude: ['@scouterna/ui-webc'],
+    },
   },
 });