npm package: @joe-truecode/components
Description: Framework-agnostic UI components using TailwindCSS v4 and Alpine.js.
Latest version: 1.0.1

lit/mycomponents/README.md
# MyComponents

A framework-agnostic UI component library built with **TypeScript**, **TailwindCSS v4**, and **Alpine.js**. This package is designed for maximum compatibility and ease of use in any modern frontend stack, including React, Vue, Laravel, and plain HTML.

---

## Table of Contents

- [Project Structure](#project-structure)
- [Getting Started](#getting-started)
- [Editing & Adding Features](#editing--adding-features)
  - [Adding New Components](#adding-new-components)
  - [Using TailwindCSS & Alpine.js](#using-tailwindcss--alpinejs)
  - [TypeScript Best Practices](#typescript-best-practices)
- [Building & Development](#building--development)
- [Deploying & Publishing](#deploying--publishing)
- [Consuming in Other Frameworks](#consuming-in-other-frameworks)
  - [React](#react)
  - [Vue](#vue)
  - [Laravel & Blade](#laravel--blade)
  - [Plain HTML/JS](#plain-htmljs)
- [Troubleshooting](#troubleshooting)
- [References](#references)

---

## Project Structure

```
mycomponents/
├── dist/                # Build output
├── src/
│   ├── index.ts         # Entry point, exports components
│   ├── style.css        # TailwindCSS entry
│   └── index.html       # Demo HTML
├── package.json
├── postcss.config.js
├── tailwind.config.js
├── webpack.config.ts
├── tsconfig.json
└── README.md
```

---

## Getting Started

1. **Install dependencies:**
   ```sh
   npm install
   ```

2. **Development mode (hot reload):**
   ```sh
   npm run dev
   ```
   Visit [http://localhost:3000](http://localhost:3000) to see the demo.

3. **Production build:**
   ```sh
   npm run build
   ```

---

## Editing & Adding Features

### Adding New Components

1. **Create a new TypeScript file in `src/`**  
   Example: `src/my-button.ts`
   ```ts
   export class MyButton extends HTMLElement {
     connectedCallback() {
       this.innerHTML = `
         <button class="bg-green-500 text-white px-4 py-2 rounded" @click="alert('Clicked!')">
           <slot>Click Me</slot>
         </button>
       `;
       window.Alpine && window.Alpine.initTree(this);
     }
   }
   if (!customElements.get('my-button')) {
     customElements.define('my-button', MyButton);
   }
   ```

2. **Export your component in `src/index.ts`:**
   ```ts
   export * from './my-button';
   ```

3. **Use Tailwind utility classes and Alpine.js directives as needed.**

### Using TailwindCSS & Alpine.js

- **TailwindCSS:**  
  Use utility classes directly in your component templates.
- **Alpine.js:**  
  Use `x-data`, `x-show`, `@click`, etc. Alpine is globally available.

### TypeScript Best Practices

- Use strict types for all custom elements.
- Use `declare global` for extending the `window` object if needed.
- Always check if a custom element is already defined before registering.

---

## Building & Development

- **Development:**  
  `npm run dev` (Webpack dev server, hot reload)
- **Production:**  
  `npm run build` (Outputs to `dist/`)
- **Type checking:**  
  `npm run typecheck`

---

## Deploying & Publishing

1. **Login to npm (if not already):**
   ```sh
   npm login
   ```

2. **Publish:**
   ```sh
   npm publish --access public
   ```

3. **After publishing:**  
   Your package can be installed via npm in any project.

---

## Consuming in Other Frameworks

### React

1. **Install the package:**
   ```sh
   npm install mycomponents
   ```

2. **Import the bundle in your entry file (e.g., `index.tsx`):**
   ```ts
   import 'mycomponents/dist/bundle.js';
   import 'mycomponents/dist/bundle.css'; // If you extract CSS separately
   ```

3. **Use the custom element in JSX:**
   ```jsx
   <my-toggle></my-toggle>
   ```

   > Note: For TypeScript, add a declaration for custom elements:
   ```ts
   declare namespace JSX {
     interface IntrinsicElements {
       'my-toggle': React.DetailedHTMLProps<React.HTMLAttributes<HTMLElement>, HTMLElement>;
     }
   }
   ```

### Vue

1. **Install and import as above.**
2. **Use in templates:**
   ```html
   <my-toggle></my-toggle>
   ```

### Laravel & Blade

1. **Install via npm/yarn.**
2. **Include the bundle in your Blade template:**
   ```blade
   <script src="{{ mix('node_modules/mycomponents/dist/bundle.js') }}"></script>
   <link rel="stylesheet" href="{{ mix('node_modules/mycomponents/dist/bundle.css') }}">
   <my-toggle></my-toggle>
   ```

### Plain HTML/JS

1. **Include the bundle via CDN or local build:**
   ```html
   <script src="path/to/bundle.js"></script>
   <link rel="stylesheet" href="path/to/bundle.css">
   <my-toggle></my-toggle>
   ```

---

## Troubleshooting

- **TailwindCSS not working?**  
  Ensure you are using the correct PostCSS plugin: `@tailwindcss/postcss`.
- **Custom elements not rendering?**  
  Make sure the bundle is loaded before using the elements.
- **TypeScript errors for custom elements in React?**  
  Add a JSX namespace declaration as shown above.
- **Alpine.js not working?**  
  Ensure `window.Alpine` is available and `initTree` is called in your component.

---

## References

- [TailwindCSS v4 Announcement](https://tailwindcss.com/blog/tailwindcss-v4)
- [Alpine.js Documentation](https://alpinejs.dev/)
- [Web Components Guide](https://developer.mozilla.org/en-US/docs/Web/Web_Components)
- [TypeScript Custom Elements](https://www.typescriptlang.org/docs/handbook/declaration-files/templates/web-component-dts.html)
- [PostCSS Plugin Migration](https://tailwindcss.com/docs/installation#using-tailwind-with-postcss)

---

**Happy hacking!**  
Feel free to open issues or PRs for improvements.