monobill-mintui 0.6.611 → 0.6.613

package/README.md

@@ -1,349 +1,123 @@
 # MintUI
 
-A modern **framework-agnostic** UI kit built as **pure JavaScript Web Components** (no framework dependencies). Works in Vue, React, Angular, Svelte, or vanilla JavaScript!
+MintUI is a considered collection of native HTML custom elements. Import the components you need and use them in plain HTML, Vue, React, Angular, or another framework that supports custom elements.
 
-**100% Framework Independent**: Components are built with pure JavaScript and native Web Component APIs. No Vue, React, or any other framework required!
+Component styles use Tailwind CSS utilities while developing. `npm run build` compiles the styles for all 38 components into separate CSS files and creates an aggregate stylesheet. Importing a component's JavaScript entry registers its JavaScript dependencies and automatically loads the separate CSS files for that component and its dependencies. Consuming projects do not need Tailwind or a framework.
 
-**Requires Tailwind CSS**: Components use Tailwind CSS classes and require Tailwind to be installed in your project. This ensures optimal tree-shaking and minimal CSS output.
+## Install
 
-## Installation
-
-```bash
-npm install monobill-mintui
+```sh
+npm install mint-ui
 ```
 
-## ⚠️ IMPORTANT: Tailwind Configuration Required
-
-**After installing, you MUST configure Tailwind CSS to scan the mintui package files.** Without this, Tailwind classes won't work!
+### Install components with the CLI
 
-### Basic Configuration
+The `mint-ui` command installs one component at a time, detects the current project, and wires the component into its entry point. In an interactive terminal, use the arrow keys to confirm or change the detected setup. Choose **Other (manual import)** when you want to manage imports yourself.
 
-Add this to your `tailwind.config.js`:
+The CLI supports Vue, Angular, React, Svelte, and plain HTML projects. It detects the project type and lets you confirm or change the detected setup with the arrow keys. It then configures the project so you can use the element directly. For plain HTML it adds the required styles and module script to `index.html`.
 
-```js
-import mintuiPreset from 'monobill-mintui/tailwind-preset'
-
-export default {
-  presets: [mintuiPreset], // ⚠️ REQUIRED: Enforces dark mode color (#0A0A0A)
-  content: [
-    "./src/**/*.{vue,js,ts,jsx,tsx,html}",
-    "./node_modules/monobill-mintui/dist/**/*.js", // ⚠️ REQUIRED: Add this line
-  ],
-  // ... rest of your config
-}
+```sh
+npx mint-ui install button
+npx mint-ui update
+npx mint-ui list
 ```
 
-**CommonJS format:**
-
-```js
-const mintuiPreset = require('monobill-mintui/tailwind-preset')
-
-module.exports = {
-  presets: [mintuiPreset], // ⚠️ REQUIRED: Enforces dark mode color (#0A0A0A)
-  content: [
-    "./src/**/*.{vue,js,ts,jsx,tsx,html}",
-    "./node_modules/monobill-mintui/dist/**/*.js", // ⚠️ REQUIRED: Add this line
-  ],
-  // ... rest of your config
-}
-```
-
-**After updating your Tailwind config, rebuild your CSS** (restart your dev server or rebuild your Tailwind output).
-
-### Dark Mode Color
-
-The mintui preset enforces the base dark mode color `#0A0A0A` for `gray-900`. This ensures consistent dark mode styling across all apps using mintui. The preset automatically sets this color, so all components will use the correct dark mode background.
-
-## Icon Configuration
-
-Icons are loaded from SVG files. By default, icons load from the CDN at `https://assets.gomonobill.com/mintui/icons/` for optimal caching and performance.
+- `npx mint-ui install button` installs and configures only the Button component. Repeat with another component name to add it to the project.
+- `npx mint-ui update` updates MintUI and reconfigures the components recorded in `mintui.json`.
+- `npx mint-ui list` prints the available component names.
 
-### Configuring Icon Source
+If MintUI is already installed in the project, run `mint-ui install button` and `mint-ui update` directly (or use the equivalent package-manager exec command).
 
-You can configure where icons are loaded from using a meta tag:
+After installation, use the custom element directly:
 
-**Default (CDN):**
 ```html
-<!-- Icons load from CDN by default -->
-<mint-icon name="caret-up"></mint-icon>
+<mint-button>Test</mint-button>
 ```
 
-**Load from Local Server:**
-```html
-<meta name="mint-icon-base-url" content="local">
-```
-
-**Load from Custom Endpoint:**
-```html
-<meta name="mint-icon-base-url" content="/custom/path/to/icons">
-<!-- or -->
-<meta name="mint-icon-base-url" content="https://your-cdn.com/icons">
-```
-
-**Explicitly Use CDN:**
-```html
-<meta name="mint-icon-base-url" content="cdn">
-```
-
-### Icon Files Setup
-
-If using local icons, ensure SVG files are available in your `public/icons/` directory. The icon component expects files named like `/icons/caret-up.svg`, `/icons/caret-down.svg`, etc.
-
-## Usage
-
-### Framework-Agnostic Web Components
-
-Components are Web Components (Custom Elements) that work in **any framework**:
+The CLI uses the project's npm, pnpm, Yarn, or Bun lockfile to choose its package manager.
 
-#### Vanilla JavaScript / HTML
+## Plain HTML
 
 ```html
-<!DOCTYPE html>
-<html>
-<head>
-  <script type="module">
-    import 'monobill-mintui'
-  </script>
-</head>
-<body>
-  <mint-button variant="primary">Click me</mint-button>
-  <mint-switch id="mySwitch"></mint-switch>
-  
-  <script>
-    document.getElementById('mySwitch').addEventListener('change', (e) => {
-      console.log('Toggled:', e.detail.checked)
-    })
-  </script>
-</body>
-</html>
-```
-
-#### Vue 3
-
-**⚠️ IMPORTANT: Configure Vue to recognize custom elements**
-
-You must configure Vue to treat `mint-*` elements as custom elements, not Vue components.
-
-**For Vite projects**, add this to your `vite.config.js` or `vite.config.ts`:
+<script type="module">
+  import './node_modules/mint-ui/dist/components/button/browser.js'
+</script>
 
-```js
-import { defineConfig } from 'vite'
-import vue from '@vitejs/plugin-vue'
-
-export default defineConfig({
-  plugins: [
-    vue({
-      template: {
-        compilerOptions: {
-          isCustomElement: (tag) => tag.startsWith('mint-'),
-        },
-      },
-    }),
-  ],
-})
+<mint-button variant="solid" tone="action">Get started</mint-button>
 ```
 
-**For Vue CLI projects**, add this to your `vue.config.js`:
+Import individual components for smaller application bundles:
 
 ```js
-module.exports = {
-  chainWebpack: (config) => {
-    config.module
-      .rule('vue')
-      .use('vue-loader')
-      .tap((options) => {
-        options.compilerOptions = {
-          ...options.compilerOptions,
-          isCustomElement: (tag) => tag.startsWith('mint-'),
-        }
-        return options
-      })
-  },
-}
+import 'mint-ui/button'
+import 'mint-ui/switch'
 ```
 
-**For Nuxt 3**, add this to your `nuxt.config.ts`:
+Package subpath imports such as `import 'mint-ui/button'` automatically import the component's compiled CSS and dependencies in bundlers. For native browser modules, use the `browser.js` entry shown above; it loads the same separate CSS files at runtime. `mint-ui/styles.css` remains available when an application prefers importing the entire compiled stylesheet once.
 
-```ts
-export default defineNuxtConfig({
-  vue: {
-    compilerOptions: {
-      isCustomElement: (tag) => tag.startsWith('mint-'),
-    },
-  },
-})
-```
+## Frameworks
 
-**Usage example:**
-
-```vue
-<template>
-  <mint-button variant="primary" @click="handleClick">
-    Click me
-  </mint-button>
-  <mint-switch :checked="enabled" @change="handleChange" />
-  <mint-input label="Name" v-model="name" />
-  <mint-select label="Country" v-model="country">
-    <option value="us">United States</option>
-    <option value="ca">Canada</option>
-  </mint-select>
-</template>
-
-<script setup>
-import { ref } from 'vue'
-import 'monobill-mintui'
-
-const enabled = ref(false)
-const name = ref('')
-const country = ref('')
-
-const handleClick = () => console.log('Clicked!')
-const handleChange = (e) => {
-  enabled.value = e.detail?.checked ?? e.target.checked
-}
-</script>
-```
+Register the custom elements once in the application's entry point, then use their HTML tags in your templates. Events are standard DOM events. Boolean controls expose properties such as `checked` and also emit `change` events.
 
-#### React
-
-```jsx
-import { useState } from 'react'
-import 'monobill-mintui'
-
-function App() {
-  const [enabled, setEnabled] = useState(false)
-
-  return (
-    <>
-      <mint-button variant="primary" onClick={() => console.log('Clicked!')}>
-        Click me
-      </mint-button>
-      <mint-switch 
-        checked={enabled}
-        onChange={(e) => setEnabled(e.detail?.checked ?? e.target.checked)}
-      />
-      <mint-input label="Name" />
-      <mint-select label="Country">
-        <option value="us">United States</option>
-        <option value="ca">Canada</option>
-      </mint-select>
-    </>
-  )
-}
+```js
+import 'mint-ui/button'
+import 'mint-ui/checkbox'
 ```
 
-#### Angular
-
-```typescript
-import { Component } from '@angular/core'
-import 'monobill-mintui'
-
-@Component({
-  selector: 'app-root',
-  template: `
-    <mint-button variant="primary" (click)="handleClick()">
-      Click me
-    </mint-button>
-    <mint-switch [checked]="enabled" (change)="handleChange($event)">
-    </mint-switch>
-  `
-})
-export class AppComponent {
-  enabled = false
-  handleClick() { console.log('Clicked!') }
-  handleChange(e: any) { 
-    this.enabled = e.detail?.checked ?? e.target.checked 
-  }
+```html
+<mint-checkbox label="Send me product updates"></mint-checkbox>
+```
+
+## Components
+
+| Component | Custom element | Documentation |
+|---|---|---|
+| Button | `<mint-button>` | [Button](docs/components/button.md) |
+| Switch | `<mint-switch>` | [Switch](docs/components/switch.md) |
+| Checkbox | `<mint-checkbox>` | [Checkbox](docs/components/checkbox.md) |
+| Choice | `<mint-choice>` | [Choice](docs/components/choice.md) |
+| Spinner | `<mint-spinner>` | [Spinner](docs/components/spinner.md) |
+| Icon | `<mint-icon>` | [Icon](docs/components/icon.md) |
+| Text | `<mint-text>` | [Text](docs/components/text.md) |
+| Stack | `<mint-stack>` | [Stack](docs/components/stack.md) |
+| Card | `<mint-card>` | [Card](docs/components/card.md) |
+| Link | `<mint-link>` | [Link](docs/components/link.md) |
+| Page | `<mint-page>` | [Page](docs/components/page.md) |
+| Grid | `<mint-grid>` | [Grid](docs/components/grid.md) |
+| Modal | `<mint-modal>` | [Modal](docs/components/modal.md) |
+| Popover | `<mint-popover>` | [Popover](docs/components/popover.md) |
+| Back Button | `<mint-back-button>` | [Back Button](docs/components/back-button.md) |
+
+## Styling
+
+Component styles are split into separate files. Import only the CSS modules for the components your app uses; Vite and other CSS-aware bundlers combine them into one application CSS file. For example, use `mint-ui/button.css` with `mint-ui/button`. Theme the default palette with CSS custom properties:
+
+```css
+@import "mint-ui/theme.css";
+
+:root {
+  --mint-color-primary: #315943;
+  --mint-color-surface: #ffffff;
+  --mint-color-text: #28372d;
+  --mint-color-border: #dfe6e0;
 }
 ```
 
-## Available Components
-
-- **mint-button** - Button component with multiple variants
-- **mint-switch** - Toggle switch component
-- **mint-input** - Text input, textarea, and various input types
-- **mint-select** - Select dropdown component
-- **mint-checkbox** - Checkbox component
-- **mint-choice** - Radio button group component (parent container with mint-choice-option children)
-- **mint-tags** - Tags input component with add/remove and sorting capabilities
-- **mint-date-picker** - Date picker component
-- **mint-dropzone** - File upload component
-- **mint-form** - Form component with validation
-- **mint-icon** - Icon component
-- **mint-text** - Text component with typography variants
-- **mint-card** - Card component
-- **mint-modal** - Modal dialog component
-- **mint-popover** - Popover component
-- **mint-spinner** - Loading spinner component
-- **mint-stack** - Stack layout component
-- **mint-grid** - Grid layout component
-- **mint-page** - Page container component
-- **mint-link** - Link component
-- **mint-back-button** - Back button component
-
-## Requirements
-
-- **Tailwind CSS** - Required. Components use Tailwind utility classes.
-- **No framework required!** Components are pure JavaScript Web Components
-- **No JavaScript dependencies!** Built with native Web Component APIs
-- Modern browser with Web Components support (all modern browsers)
-
-### ⚠️ Critical: Tailwind Configuration
-
-**You MUST add the mintui package to your Tailwind content paths AND use the preset**, otherwise the classes won't be included in your CSS and dark mode colors won't be correct:
+The `theme.css` file provides the light palette by default and switches to its dark palette when the root element has `data-mint-theme="dark"` (or the legacy `dark` class). Update a token at any time with CSS or JavaScript; components respond immediately:
 
 ```js
-// tailwind.config.js (ES modules)
-import mintuiPreset from 'monobill-mintui/tailwind-preset'
-
-export default {
-  presets: [mintuiPreset], // ⚠️ REQUIRED: Enforces dark mode color (#0A0A0A)
-  content: [
-    "./src/**/*.{vue,js,ts,jsx,tsx,html}",
-    "./node_modules/monobill-mintui/dist/**/*.js", // ⚠️ REQUIRED
-  ],
-  // ... rest of your config
-}
-```
-
-```js
-// tailwind.config.js (CommonJS)
-const mintuiPreset = require('monobill-mintui/tailwind-preset')
-
-module.exports = {
-  presets: [mintuiPreset], // ⚠️ REQUIRED: Enforces dark mode color (#0A0A0A)
-  content: [
-    "./src/**/*.{vue,js,ts,jsx,tsx,html}",
-    "./node_modules/monobill-mintui/dist/**/*.js", // ⚠️ REQUIRED
-  ],
-  // ... rest of your config
-}
+document.documentElement.style.setProperty('--mint-color-primary', '#6a4c93')
+document.documentElement.dataset.mintTheme = 'dark'
 ```
 
-**After updating your Tailwind config, rebuild your CSS** (restart your dev server or rebuild your Tailwind output).
+Available tokens include `--mint-color-primary`, `--mint-color-info`, `--mint-color-warning`, `--mint-color-danger`, `--mint-color-success`, `--mint-color-text`, `--mint-color-text-secondary`, `--mint-color-text-muted`, `--mint-color-surface`, `--mint-color-surface-raised`, `--mint-color-surface-muted`, `--mint-color-border`, and `--mint-color-focus`. Component styles include light-mode fallbacks, so `theme.css` is only needed when you want the shared palette, runtime theming, or dark mode.
 
-## Troubleshooting
+## Develop
 
-### Tailwind classes not working?
-
-1. **Check your Tailwind config** - Make sure you've added `./node_modules/monobill-mintui/dist/**/*.js` to the `content` array
-2. **Rebuild your CSS** - Restart your dev server or rebuild your Tailwind output
-3. **Check the package name** - Make sure you're using `monobill-mintui` (not `mintui`) in the path
-4. **Verify the path** - The path should point to `dist/**/*.js` inside the node_modules folder
-
-## Development
-
-```bash
-# Install dependencies
+```sh
 npm install
-
-# Run development server
 npm run dev
-
-# Build for production
 npm run build
 ```
 
-## License
-
-MIT
+Component source styles use Tailwind during development. The build compiles and packages all component and aggregate CSS; the documentation site imports that built output, and consuming projects do not need Tailwind.

package/bin/component-dependencies.json

@@ -0,0 +1,131 @@
+{
+  "alert": [
+    "text",
+    "icon"
+  ],
+  "back-button": [
+    "button",
+    "spinner",
+    "icon"
+  ],
+  "bottom-navigation": [
+    "icon"
+  ],
+  "button": [
+    "spinner",
+    "icon"
+  ],
+  "card": [
+    "text"
+  ],
+  "chart": [],
+  "checkbox": [
+    "icon"
+  ],
+  "chip": [
+    "icon"
+  ],
+  "choice": [],
+  "clickable": [],
+  "collapsible": [],
+  "confirm-action": [
+    "modal",
+    "button",
+    "spinner",
+    "icon",
+    "text",
+    "stack"
+  ],
+  "date-picker": [
+    "input",
+    "icon",
+    "popover",
+    "stack"
+  ],
+  "dropzone": [
+    "icon"
+  ],
+  "form": [],
+  "grid": [],
+  "icon": [],
+  "input": [
+    "icon"
+  ],
+  "link": [],
+  "modal": [
+    "button",
+    "spinner",
+    "icon",
+    "text",
+    "stack"
+  ],
+  "navigation": [
+    "button",
+    "spinner",
+    "icon",
+    "link",
+    "popover",
+    "stack"
+  ],
+  "off-canvas": [
+    "button",
+    "spinner",
+    "icon",
+    "text",
+    "stack"
+  ],
+  "page": [],
+  "popover": [
+    "stack"
+  ],
+  "resource-table": [
+    "table",
+    "input",
+    "icon",
+    "button",
+    "spinner",
+    "popover",
+    "stack"
+  ],
+  "search": [
+    "icon",
+    "chip",
+    "input",
+    "button",
+    "spinner"
+  ],
+  "select": [
+    "icon"
+  ],
+  "side-navigation": [
+    "icon",
+    "text",
+    "popover",
+    "stack"
+  ],
+  "sortable": [],
+  "spinner": [],
+  "stack": [],
+  "switch": [
+    "icon"
+  ],
+  "table": [],
+  "tabs": [],
+  "tags": [
+    "chip",
+    "icon",
+    "button",
+    "spinner",
+    "popover",
+    "stack"
+  ],
+  "text": [],
+  "time-picker": [
+    "input",
+    "icon",
+    "popover",
+    "stack",
+    "text"
+  ],
+  "toast": []
+}