@skutally/ui-library 0.1.1 → 0.1.2

package/README.md

@@ -1,514 +1,85 @@
-# UI Library
+# ui-library
 
-A ui-style component library for HTML, Tailwind CSS v4, and Stimulus.js. Copy and paste beautifully designed, accessible components into your projects. No npm dependency — the code is yours.
+A CLI for adding beautifully designed components to your HTML + Tailwind CSS v4 + Stimulus.js projects.
 
----
+This is NOT a component library you install as a dependency. It's a collection of re-usable components that you copy into your apps and customize. The code is yours.
 
-## Table of Contents
+## init
 
-- [Overview](#overview)
-- [Tech Stack](#tech-stack)
-- [Project Structure](#project-structure)
-- [Getting Started](#getting-started)
-  - [Prerequisites](#prerequisites)
-  - [Installation](#installation)
-  - [Development](#development)
-- [CLI Tool](#cli-tool)
-- [Theming](#theming)
-  - [CSS Variables](#css-variables)
-  - [Dark Mode](#dark-mode)
-  - [Adding Custom Colors](#adding-custom-colors)
-- [Components](#components)
-  - [Component List](#component-list)
-  - [Component Usage Pattern](#component-usage-pattern)
-  - [Component API Reference](#component-api-reference)
-- [Framework Integration](#framework-integration)
-  - [Rails (Hotwire)](#rails-hotwire)
-- [Accessibility](#accessibility)
-- [Contributing](#contributing)
+Use the `init` command to initialize dependencies for a new project.
 
----
+The `init` command creates a `components.json` config file and sets up `src/base.css` with Tailwind CSS v4 theme variables.
 
-## Overview
-
-This is NOT a traditional component library you install as a dependency. It's a collection of 23 re-usable components that you copy and paste into your apps and customize to your needs.
-
-Why copy/paste instead of npm install?
-- Full ownership and control over the code
-- No version conflicts or breaking updates
-- Customize everything — styles, behavior, markup
-- Zero runtime dependency on this library
-
----
-
-## Tech Stack
-
-| Technology | Version | Purpose |
-|---|---|---|
-| Tailwind CSS | v4.2+ | Utility-first styling with `@theme` directive |
-| Stimulus.js | Latest | Lightweight JavaScript behavior via controllers |
-| HTML | 5 | Semantic markup with ARIA attributes |
-| Node.js | 18+ | CLI tool and build scripts |
-
-Fonts (from Google Fonts):
-- Inter (400, 500, 600, 700) — UI text
-- JetBrains Mono (400, 500) — Code blocks
-
----
-
-## Project Structure
-
-ui-library/
-├── bin/
-│   └── cli.js                    # CLI tool for component management
-├── src/
-│   ├── base.css                  # Tailwind v4 theme config + CSS variables
-│   ├── controllers.js            # Demo page controller aggregator
-│   └── controllers/              # Stimulus.js controllers (19 files)
-│       ├── accordion.js
-│       ├── alert.js
-│       ├── badge.js
-│       ├── button.js
-│       ├── card.js
-│       ├── checkbox.js
-│       ├── dropdown.js
-│       ├── input.js
-│       ├── modal.js
-│       ├── popover.js
-│       ├── progress.js
-│       ├── radio.js
-│       ├── sheet.js
-│       ├── slider.js
-│       ├── table.js
-│       ├── tabs.js
-│       ├── toast.js
-│       ├── toggle.js
-│       └── tooltip.js
-├── components/                   # Component HTML templates (23 files)
-│   ├── accordion.html
-│   ├── alert.html
-│   ├── avatar.html
-│   ├── badge.html
-│   ├── breadcrumb.html
-│   ├── button.html
-│   ├── card.html
-│   ├── checkbox.html
-│   ├── dropdown.html
-│   ├── input.html
-│   ├── modal.html
-│   ├── popover.html
-│   ├── progress.html
-│   ├── radio.html
-│   ├── separator.html
-│   ├── sheet.html
-│   ├── skeleton.html
-│   ├── slider.html
-│   ├── table.html
-│   ├── tabs.html
-│   ├── toast.html
-│   ├── toggle.html
-│   └── tooltip.html
-├── registry/
-│   └── registry.json             # Component metadata & dependency graph
-├── templates/
-│   └── components.json           # Project init template
-├── dist/
-│   └── output.css                # Compiled Tailwind CSS output
-├── index.html                    # Component showcase / demo page
-├── docs.html                     # Documentation page
-├── blocks.html                   # Pre-built page blocks & templates
-└── package.json
-
-
-## Getting Started
-
-### Prerequisites
-
-- Node.js 18 or higher
-- npm (comes with Node.js)
-
-### Installation
-
-Step 1: Create your project
-
-mkdir my-project && cd my-project
-npm init -y
-
-Step 2: Install Tailwind CSS v4
-
-npm install tailwindcss @tailwindcss/cli
-
-
-Step 3: Add Stimulus.js
-
-<!-- Option A: CDN (simplest) -->
-<script src="https://cdn.jsdelivr.net/npm/@hotwired/stimulus/dist/stimulus.umd.js"></script>
-
-# Option B: npm
-npm install @hotwired/stimulus
-
-
-Step 4: Initialize UI Library
-
-npx ui-library init
-
-
-This creates:
-- `components.json` — project configuration
-- `src/base.css` — Tailwind v4 theme with CSS variables
-
-Step 5: Add components
-
-
-npx ui-library add button
-npx ui-library add modal tabs accordion
-
-
-Step 6: Build CSS and start developing
-
-# Watch mode (development)
-npx @tailwindcss/cli -i src/base.css -o dist/output.css --watch
-
-# Production build (minified)
-npx @tailwindcss/cli -i src/base.css -o dist/output.css --minify
-
-
-Step 7: Link CSS and Stimulus in your HTML
-
-
-### Development
-
-If you cloned this repository directly:
-
-# Install dependencies
-npm install
-
-# Watch CSS changes during development
-npm run dev
-
-# Build for production
-npm run build
-
-# Start local server
-npm run serve
-
-# Build + serve
-
-
-## CLI Tool
-
-The CLI (`bin/cli.js`) provides four commands:
-
- `ui-library init`
-
-Initializes a project with `components.json` and `src/base.css`.
-
-npx ui-library init\
-
-### `ui-library add <name> [name...]`
-
-Installs components with automatic dependency resolution.
-
-npx ui-library add button
-npx ui-library add modal tabs accordion
-npx ui-library add slider checkbox radio
-
-
-- Copies controller JS to `src/controllers/`
-- Copies HTML template to `components/ui/`
-- Auto-resolves dependencies (e.g., `modal` automatically adds `button`)
-- Prints registration hints after install
-
-### `ui-library list`
-
-Lists all 23 available components with descriptions.
-
-npx ui-library list
-
-
-### `ui-library diff <name>`
-
-Checks if your local controller differs from the registry version.
-
-npx ui-library diff button
-
-### `components.json` Configuration
-
-```json
-{
-  "$schema": "https://ui-library.dev/schema.json",
-  "style": "default",
-  "tailwind": {
-    "version": 4,
-    "css": "src/base.css",
-    "cssVariables": true
-  },
-  "aliases": {
-    "controllers": "src/controllers",
-    "components": "components/ui"
-  }
-}
-
-| Option | Description |
-|---|---|
-| `style` | Style preset for components. Default: `"default"` |
-| `tailwind.version` | Tailwind CSS version. Currently supports v4 |
-| `tailwind.css` | Path to CSS file with Tailwind v4 theme |
-| `tailwind.cssVariables` | Use CSS variables for theming. Default: `true` |
-| `aliases.controllers` | Directory for Stimulus controllers |
-| `aliases.components` | Directory for component HTML templates |
-
----
-
-## Theming
-
-### CSS Variables
-
-All theming is done via CSS variables in `src/base.css` using Tailwind v4's `@theme` directive. No `tailwind.config.js` needed.
-
-Color convention: Each semantic color has a `background` and `foreground` pair:
-
-```css
-:root {
-  --background: 0 0% 100%;        /* Page background */
-  --foreground: 240 10% 3.9%;     /* Page text */
-
-  --card: 0 0% 100%;              /* Card background */
-  --card-foreground: 240 10% 3.9%;
-
-  --primary: 240 5.9% 10%;        /* Primary actions */
-  --primary-foreground: 0 0% 98%;
-
-  --muted: 240 4.8% 95.9%;        /* Muted/subtle elements */
-  --muted-foreground: 240 3.8% 46.1%;
-
-  --accent: 240 4.8% 95.9%;       /* Accent/hover states */
-  --accent-foreground: 240 5.9% 10%;
-
-  --destructive: 0 84.2% 60.2%;   /* Destructive actions */
-  --destructive-foreground: 0 0% 98%;
-
-  --border: 240 5.9% 90%;         /* Border color */
-  --input: 240 5.9% 90%;          /* Input border */
-  --ring: 240 5.9% 10%;           /* Focus ring */
-  --radius: 0.5rem;               /* Border radius */
-}
+```bash
+npx @skutally/ui-library init
 ```
 
-These are mapped to Tailwind classes via `@theme`:
+## add
 
-```css
-@theme {
-  --font-sans: "Inter", "system-ui", "-apple-system", "sans-serif";
-  --font-mono: "JetBrains Mono", "Fira Code", "monospace";
+Use the `add` command to add components to your project.
 
-  --color-background: hsl(var(--background));
-  --color-foreground: hsl(var(--foreground));
-  --color-primary: hsl(var(--primary));
-  --color-primary-foreground: hsl(var(--primary-foreground));
-  /* ... etc */
+The `add` command copies a component to your project and automatically resolves all required dependencies.
 
-  --radius-lg: var(--radius);
-  --radius-md: calc(var(--radius) - 2px);
-  --radius-sm: calc(var(--radius) - 4px);
-}
+```bash
+npx @skutally/ui-library add [component]
 ```
 
-### Dark Mode
-
-Dark mode uses the `.dark` class on `<html>`. All CSS variables automatically switch:
+### Example
 
-```css
-.dark {
-  --background: 240 10% 3.9%;
-  --foreground: 0 0% 98%;
-  --primary: 0 0% 98%;
-  --primary-foreground: 240 5.9% 10%;
-  --muted: 240 3.7% 15.9%;
-  --muted-foreground: 240 5% 64.9%;
-  --accent: 240 3.7% 15.9%;
-  --accent-foreground: 0 0% 98%;
-  --destructive: 0 62.8% 30.6%;
-  --destructive-foreground: 0 0% 98%;
-  --border: 240 3.7% 15.9%;
-  --input: 240 3.7% 15.9%;
-  --ring: 240 4.9% 83.9%;
-}
+```bash
+npx @skutally/ui-library add button
 ```
 
-Toggle implementation:
+You can also add multiple components at once:
 
-```javascript
-// Toggle dark mode
-function toggleDarkMode() {
-  document.documentElement.classList.toggle('dark')
-  const isDark = document.documentElement.classList.contains('dark')
-  localStorage.setItem('theme', isDark ? 'dark' : 'light')
-}
-
-// Load saved preference on page load (place in <head> to prevent FOUC)
-if (localStorage.getItem('theme') === 'dark' ||
-    (!localStorage.getItem('theme') &&
-     window.matchMedia('(prefers-color-scheme: dark)').matches)) {
-  document.documentElement.classList.add('dark')
-}
+```bash
+npx @skutally/ui-library add modal tabs accordion
 ```
 
-### Adding Custom Colors
-
-1. Define the variable in `:root`:
-
-:root {
-  --warning: 38 92% 50%;
-  --warning-foreground: 48 96% 89%;
-}
-
-2. Add to the `@theme` block:
-
-@theme {
-  --color-warning: hsl(var(--warning));
-  --color-warning-foreground: hsl(var(--warning-foreground));
-}
-
-3. Use in HTML:
- 
-<div class="bg-warning text-warning-foreground">Warning message</div>
-
-
-## Components
-
-### Component List
+Run the command without any arguments to view a list of all available components:
 
-| Component | Has JS Controller | Dependencies | Description |
-|---|---|---|---|
-| Accordion | Yes | — | Vertically stacked interactive headings that reveal content |
-| Alert | Yes | — | Callout for important messages (info, success, warning, danger) |
-| Avatar | No | — | Image element with fallback for user profiles |
-| Badge | Yes | — | Small status descriptor with variant styles |
-| Breadcrumb | No | — | Path hierarchy navigation |
-| Button | Yes | — | Clickable button with 8 variants and 6 sizes |
-| Card | Yes | — | Container with border and shadow |
-| Checkbox | Yes | — | Toggle between checked/unchecked states |
-| Dropdown | Yes | — | Menu triggered by a button click |
-| Input | Yes | — | Text input with variants and icon support |
-| Modal | Yes | button | Dialog overlay requiring user interaction |
-| Popover | Yes | — | Floating panel anchored to trigger element |
-| Progress | Yes | — | Horizontal completion progress bar |
-| Radio | Yes | — | Mutually exclusive option group |
-| Separator | No | — | Visual divider between content sections |
-| Sheet | Yes | button | Panel that slides from screen edge |
-| Skeleton | No | — | Placeholder animation while loading |
-| Slider | Yes | — | Draggable input for selecting numeric value |
-| Table | Yes | — | Data table with sortable column headers |
-| Tabs | Yes | — | Layered sections displaying one panel at a time |
-| Toast | Yes | — | Temporary notification with auto-dismiss |
-| Toggle | Yes | — | Switch control (on/off) |
-| Tooltip | Yes | — | Popup showing info on hover |
-
-### Component Usage Pattern
-
-All components follow the same Stimulus.js conventions:
-
-1. Attach a controller:
-
-
-<button data-controller="button">Click me</button>
-
-
-2. Configure with values:
-
-
-<button data-controller="button"
-        data-button-variant-value="destructive"
-        data-button-size-value="lg">
-  Delete
-</button>
-
-
-3. Bind actions:
-
-<div data-controller="modal">
-  <button data-action="click->modal#open">Open Modal</button>
-  <div data-modal-target="overlay" class="hidden">
-    <!-- modal content -->
-  </div>
-</div>
-
-4. Register controllers in your app:
-
-```javascript
-import { Application } from "@hotwired/stimulus"
-import ButtonController from "./src/controllers/button.js"
-import ModalController from "./src/controllers/modal.js"
-
-const app = Application.start()
-app.register("button", ButtonController)
-app.register("modal", ModalController)
-
-
-## Accessibility
-
-Built-in accessibility features across all components:
-
-- ARIA roles: `role="button"`, `role="dialog"`, `role="tabpanel"`, `role="switch"`, `role="progressbar"`
-- ARIA attributes: `aria-checked`, `aria-valuenow`, `aria-valuemin`, `aria-valuemax`
-- Keyboard navigation: Escape to close modals, dropdowns, sheets, and popovers
-- Focus management: Auto-focus on first input in modals, visible focus rings (`focus-visible:ring-2`)
-- Semantic HTML: Proper use of `<button>`, `<input>`, `<label>`, `<nav>`, `<table>`
-- Disabled states: `disabled:opacity-50 disabled:pointer-events-none`
-
----
-
-## Key Styling Patterns
-
-| Pattern | Implementation |
-|---|---|
-| Utility-first | All Tailwind classes, no custom CSS |
-| CSS Variables | Semantic colors via custom properties |
-| Dark Mode | `.dark` class toggle on `<html>` |
-| Transitions | `duration-200`, `transition-all`, `transition-opacity` |
-| Focus States | `focus-visible:ring-2 focus-visible:ring-ring` |
-| Disabled States | `disabled:opacity-50 disabled:pointer-events-none` |
-| Responsive | Mobile-first with `sm:`, `md:`, `lg:` breakpoints |
-
----
-
-## Data Attributes Quick Reference
-
-```html
-<!-- Controller binding -->
-<div data-controller="component-name">
-
-<!-- Action binding -->
-<button data-action="click->controller#method">
+```bash
+npx @skutally/ui-library list
+```
 
-<!-- Target binding -->
-<div data-controller-target="targetName">
+## diff
 
-<!-- Value binding -->
-<div data-controller-name-value="value">
+Use the `diff` command to check if your local component differs from the registry version.
 
-<!-- Action params -->
-<button data-action="click->toast#show"
-        data-toast-type-param="success"
-        data-toast-title-param="Saved!">
+```bash
+npx @skutally/ui-library diff button
 ```
 
----
+## Documentation
 
-## Contributing
+Visit the [documentation page](https://skutally.github.io/ui-library/docs.html) to view the full docs.
 
-1. Clone the repository
-2. Run `npm install`
-3. Run `npm run dev` to watch CSS changes
-4. Open `index.html` in your browser (or run `npm run serve`)
-5. Edit components in `components/` and controllers in `src/controllers/`
-6. Update `registry/registry.json` if adding new components
+## Components
 
----
+- Accordion
+- Alert
+- Avatar
+- Badge
+- Breadcrumb
+- Button
+- Card
+- Checkbox
+- Dropdown
+- Input
+- Modal
+- Popover
+- Progress
+- Radio
+- Separator
+- Sheet
+- Skeleton
+- Slider
+- Table
+- Tabs
+- Toast
+- Toggle
+- Tooltip
 
 ## License
 
-MIT — Free to use for personal and commercial projects. No attribution required.
-
-Built with Html + Stimulus.js + Tailwind CSS.
+Licensed under the [MIT license](LICENSE).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@skutally/ui-library",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "description": "A modern UI component library for HTML, Tailwind CSS & Stimulus.js. Copy-paste components into your project.",
   "type": "module",
   "bin": {