@skutally/ui-library 0.1.0

package/README.md

@@ -0,0 +1,514 @@
+# 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.
+
+---
+
+## Table of Contents
+
+- [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)
+
+---
+
+## 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 */
+}
+```
+
+These are mapped to Tailwind classes via `@theme`:
+
+```css
+@theme {
+  --font-sans: "Inter", "system-ui", "-apple-system", "sans-serif";
+  --font-mono: "JetBrains Mono", "Fira Code", "monospace";
+
+  --color-background: hsl(var(--background));
+  --color-foreground: hsl(var(--foreground));
+  --color-primary: hsl(var(--primary));
+  --color-primary-foreground: hsl(var(--primary-foreground));
+  /* ... etc */
+
+  --radius-lg: var(--radius);
+  --radius-md: calc(var(--radius) - 2px);
+  --radius-sm: calc(var(--radius) - 4px);
+}
+```
+
+### Dark Mode
+
+Dark mode uses the `.dark` class on `<html>`. All CSS variables automatically switch:
+
+```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%;
+}
+```
+
+Toggle implementation:
+
+```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')
+}
+```
+
+### 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
+
+| 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">
+
+<!-- Target binding -->
+<div data-controller-target="targetName">
+
+<!-- Value binding -->
+<div data-controller-name-value="value">
+
+<!-- Action params -->
+<button data-action="click->toast#show"
+        data-toast-type-param="success"
+        data-toast-title-param="Saved!">
+```
+
+---
+
+## Contributing
+
+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
+
+---
+
+## License
+
+MIT — Free to use for personal and commercial projects. No attribution required.
+
+Built with Stimulus.js + Tailwind CSS. Inspired by [shadcn/ui](https://ui.shadcn.com).