npm package: @hetenho/showcase
Description: A Storybook-like component manager that renders components from multiple frameworks (React, Vue, Solid, Angular, Lit) inside Shadow DOM for complete style isolation.
Latest version: 0.5.0

# Showcase

A Storybook-like component manager that renders components from multiple frameworks (React, Vue, Solid, Angular, Lit) inside Shadow DOM for complete style isolation.

## Features

- 🎨 **Multi-Framework Support**: Develop and showcase components from React, Vue, Solid, Angular, and Lit in one repository
- 🔒 **Shadow DOM Isolation**: Each component renders in its own Shadow DOM, ensuring complete style isolation
- 🧭 **Auto-Discovery**: Automatically finds components based on folder structure (`src/components/react/`, `src/components/vue/`, etc.)
- 🎛️ **Interactive Props Panel**: Edit component props in real-time with schema extraction from TypeScript types
- 🧪 **Visual Snapshot Testing**: Vitest + Playwright integration for visual regression testing
- ⚙️ **Framework Switcher**: Download updated `package.json` files when switching between frameworks
- 📦 **Presets**: Built-in support for Shadcn UI and Base UI component patterns

## Quick Start

### Installation

```bash
npm install
```

### Development

```bash
npm run dev
```

The app will start at `http://localhost:5173` with your components automatically discovered.

### CLI Binary

Run as a CLI tool (like Storybook):

```bash
npx showcase
# or
node bin/showcase.mjs
```

## Component Structure

Organize your components by framework in `src/components/`:

```
src/components/
├── react/
│   ├── Button.tsx
│   └── Button.meta.ts      # Optional: props schema
├── vue/
│   ├── Button.vue
│   └── Button.meta.ts
├── solid/
│   ├── Button.tsx
│   └── Button.meta.ts
├── angular/
│   └── Button.ts
└── lit/
    └── Button.ts
```

### Routes

Components automatically map to routes based on their folder path:
- `src/components/react/Button.tsx` → `/react/button`
- `src/components/vue/ui/Card.vue` → `/vue/ui/card`

## Props Extraction

Showcase automatically extracts component props using multiple strategies:

1. **Meta Files** (highest priority): Create `.meta.ts` files alongside components
   ```ts
   // Button.meta.ts
   export const propsSchema = {
     fields: [
       { name: "label", type: "text", default: "Click me" },
       { name: "disabled", type: "boolean", default: false },
       { name: "variant", type: "text", options: ["primary", "secondary"] }
     ]
   };
   ```

2. **Runtime Inspection**: React components with `propTypes` or `defaultProps` are automatically detected

3. **Function Signatures**: Default parameters in function components are inferred

## Configuration

Create a `showcase.config.ts` in your project root:

```ts
import { defineShowcaseConfig } from "./src/showcase/config/defaults";

export default defineShowcaseConfig({
  componentsDir: "src/components",  // Default component directory
  presets: ["shadcn"],              // Enable presets
  theme: "light",                   // "light" | "dark"
});
```

## Presets

### Shadcn UI

When enabled, Shadcn components follow the `@/components/ui` pattern. Use the scaffold helpers:

```ts
import { scaffoldShadcnButton } from "./showcase/integrations/shadcn";

// Generate a Shadcn-styled Button component
const code = scaffoldShadcnButton("react");
```

### Base UI

Similar support for Base UI (MUI Base) components:

```ts
import { scaffoldBaseUiButton } from "./showcase/integrations/baseUi";

const code = scaffoldBaseUiButton("react");
```

## Testing

### Visual Snapshot Tests

Write visual tests using Vitest and Playwright:

```ts
import { test, expect } from "vitest";
import { ensureViteServer } from "./utils/server";
import { toMatchImageSnapshot } from "vitest-image-snapshot";

expect.extend({ toMatchImageSnapshot });

test("React Button renders correctly", async () => {
  const { page, server } = await ensureViteServer();
  await page.goto("http://localhost:5173/react/button");
  
  const canvas = page.locator('[data-showcase-canvas]');
  await expect(canvas).toHaveScreenshot();
});
```

Run tests:

```bash
# Install Playwright browser first
npx playwright install chromium

# Run tests
npm run test

# Update snapshots
npm run test:update
```

## Framework Switcher

Use the toolbar to switch between frameworks. Click a framework button to:
1. See what dependencies will be added
2. Download an updated `package.json`
3. Replace your existing file and run `npm install`

## Component Adapters

Components are rendered using framework-specific adapters:

- **React**: Uses `react-dom/client` `createRoot`
- **Vue**: Dynamically imports Vue and uses `createApp`
- **Solid**: Uses `solid-js/web` renderer
- **Angular**: Placeholder (implementation pending)
- **Lit**: Placeholder (implementation pending)

### Optional Dependencies

Vue and Solid are loaded dynamically. If not installed, components gracefully fail with helpful error messages.

## Props Panel

The right-side props panel allows:
- Editing props defined in the schema
- Adding custom/extended props on the fly
- Real-time updates to the component

Extended props are persisted in URL state, so you can share component states via URL.

## Development Tips

1. **Fast Refresh**: Works seamlessly with Vite's HMR
2. **Type Safety**: TypeScript is fully supported
3. **Shadow DOM**: Components are completely isolated - no CSS leakage
4. **Lazy Loading**: Framework adapters are loaded on-demand

## Examples

See `src/components/` for example components:
- React Button with meta file
- Vue Button with async factory
- Solid Button with DOM fallback
- Lit Button example

## License

MIT