fvn-ui 0.1.0-alpha.1

package/README.md

@@ -0,0 +1,57 @@
+## fvn-ui
+Minimal vanilla JS component library with layout helpers. Zero dependencies.
+
+> **Note:** Requires a bundler that handles CSS imports (Vite, Webpack, Parcel, etc.)
+
+```js
+import { layout, button, switchComponent } from 'fvn-ui'
+```
+
+Or use the `ui` namespace for cleaner access (also avoids reserved words like `switch`):
+```js
+import { ui } from 'fvn-ui'
+
+ui.button({ label: 'Save' })
+ui.switch({ label: 'Dark mode' })
+ui.layout.row([ ... ])
+```
+
+Tree-shakeable imports:
+```js
+import 'fvn-ui/style.css'
+import { button } from 'fvn-ui/button'
+import { card } from 'fvn-ui/card'
+```
+
+### Components
+
+| Component | Description |
+|-----------|-------------|
+| `button` | Buttons with variants, colors, icons |
+| `card` | Container with title, description, content |
+| `dialog` / `modal` / `tooltip` | Modal dialogs and popovers |
+| `confirm` | Confirmation dialog with trigger button |
+| `input` | Text input with label and validation |
+| `checkbox` / `switch` / `toggle` | Boolean inputs (use `ui.switch()` or `switchComponent`) |
+| `radio` | Radio button group |
+| `select` | Dropdown with filter and multiselect (use `ui.select()` or `selectComponent`) |
+| `tabs` | Tabbed content |
+| `collapsible` | Expandable sections |
+| `dashboard` | View management with navigation |
+| `avatar` / `image` / `svg` | Media components |
+| `label` | Text label |
+
+### Layout Helpers
+
+All functions accept arguments in any order — parent element, config object, and children array are detected by type, not position.
+
+```js
+import { el, row, col, layout } from 'fvn-ui'
+
+layout.row({ gap: 4 }, [ button({ label: 'A' }), button({ label: 'B' }) ])
+layout.col(parent, { gap: 2, align: 'center', children: [el('div', { onclick })] })
+```
+
+### Documentation
+
+Each component has JSDoc with examples. See source files in `src/fvn-ui/components/` or [example page](https://fvn-dev.github.io/fvn-ui/).

package/package.json

@@ -0,0 +1,63 @@
+{
+  "name": "fvn-ui",
+  "version": "0.1.0-alpha.1",
+  "description": "Minimalist vanilla JS component library",
+  "type": "module",
+  "sideEffects": [
+    "**/*.css"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "main": "./src/fvn-ui/index.js",
+  "module": "./src/fvn-ui/index.js",
+  "exports": {
+    ".": "./src/fvn-ui/index.js",
+    "./style.css": "./src/fvn-ui/style.css",
+    "./button": "./src/fvn-ui/components/button.js",
+    "./card": "./src/fvn-ui/components/card.js",
+    "./dialog": "./src/fvn-ui/components/dialog.js",
+    "./input": "./src/fvn-ui/components/input.js",
+    "./select": "./src/fvn-ui/components/select.js",
+    "./checkbox": "./src/fvn-ui/components/checkbox.js",
+    "./switch": "./src/fvn-ui/components/switch.js",
+    "./toggle": "./src/fvn-ui/components/toggle.js",
+    "./tabs": "./src/fvn-ui/components/tabs.js",
+    "./avatar": "./src/fvn-ui/components/avatar.js",
+    "./collapsible": "./src/fvn-ui/components/collapsible.js",
+    "./confirm": "./src/fvn-ui/components/confirm.js",
+    "./dashboard": "./src/fvn-ui/components/dashboard.js",
+    "./image": "./src/fvn-ui/components/image.js",
+    "./label": "./src/fvn-ui/components/label.js",
+    "./radio": "./src/fvn-ui/components/radio.js",
+    "./svg": "./src/fvn-ui/components/svg.js",
+    "./dom": "./src/fvn-ui/dom.js"
+  },
+  "files": [
+    "src/fvn-ui"
+  ],
+  "keywords": [
+    "ui",
+    "components",
+    "vanilla-js"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/fvn-dev/fvn-ui"
+  },
+  "scripts": {
+    "dev": "vite",
+    "start": "vite",
+    "build": "vite build",
+    "doc": "documentation build src/fvn-ui/**/*.js -f json -o docs/api.json",
+    "lint": "eslint src/",
+    "lint:fix": "eslint src/ --fix"
+  },
+  "devDependencies": {
+    "documentation": "^14.0.3",
+    "eslint": "^9.0.0",
+    "sass": "^1.97.3",
+    "vite": "^7.2.4"
+  }
+}

package/src/fvn-ui/LLM.md

@@ -0,0 +1,312 @@
+# fvn-ui — LLM Reference
+
+A minimalist vanilla JS component library. No framework, no build complexity. Use existing CSS utility classes — avoid creating new CSS.
+
+## Philosophy
+
+1. **Use existing classes** — The library provides extensive utility classes. Compose with them.
+2. **Props become classes** — Shorthand props like `padding: 4` become `pad-4` classes automatically.
+3. **Flexible arguments** — Components accept args in any order: `(parent, config)` or `(config)` or `('text', config)`.
+4. **Return DOM elements** — All components return native HTMLElements with added methods.
+
+---
+
+## Import Styles
+
+```js
+// Individual imports (tree-shakeable)
+import { button, card, layout } from 'fvn-ui'
+
+// Namespaced import (cleaner DX, avoids reserved words)
+import { ui } from 'fvn-ui'
+
+ui.button({ label: 'Save' })
+ui.switch({ label: 'Dark mode' })  // vs switchComponent
+ui.select({ options: [...] })       // vs selectComponent
+```
+
+---
+
+## Core: `el(tag, config)`
+
+Creates DOM elements. The foundation of everything.
+
+```js
+el('div', { class: 'flex gap-2', text: 'Hello' })
+el('button', { onClick: handler, disabled: true })
+el('<h1>HTML string</h1>')  // Parse HTML
+```
+
+**Config options:**
+- `class` — string | array | object (truthy keys become classes)
+- `text` — safe textContent
+- `html` — innerHTML (trusted only)
+- `children` — array of elements/strings to append
+- `data` — object for data-* attributes
+- `style` — object for inline styles
+- `on[Event]` — event handlers (onClick, onInput, etc.)
+- `ref` — callback with element: `ref: (el) => myRef = el`
+
+---
+
+## Layout: `layout.row()` / `layout.col()`
+
+Flexbox containers with sensible defaults.
+
+```js
+layout.row([child1, child2])                       // horizontal, gap-2
+layout.row({ gap: 4, children: [child1, child2] }) // children as prop
+layout.col({ justify: 'between' }, [...])          // children as separate arg
+```
+
+**Props:** `gap`, `align`, `justify`, `padding`, `width`, `flex`, `children`
+
+---
+
+## Shorthand Props → Classes
+
+These props are automatically converted to utility classes:
+
+| Prop | Class | Example |
+|------|-------|---------|
+| `padding: 4` | `pad-4` | 4-unit padding |
+| `gap: 2` | `gap-2` | 2-unit gap |
+| `width: 'full'` | `w-full` | full width |
+| `border: true` | `border` | standard border |
+| `shade: true` | `shade` | shaded background |
+| `small: true` | `small` | small text |
+| `muted: true` | `muted` | muted text color |
+| `flex: 1` | `flex-1` | flex-grow: 1 |
+
+Use `props: false` to disable defaults (e.g., `border: false` on card).
+
+---
+
+## Components
+
+### `button({ label, variant, color, icon, shape })`
+
+```js
+button({ label: 'Save', variant: 'primary' })
+button({ label: 'Delete', color: 'red', icon: 'trash' })
+button({ icon: 'settings', variant: 'ghost', shape: 'round' })
+```
+
+| Prop | Values |
+|------|--------|
+| `label` / `text` | Button text |
+| `variant` | `'default'` `'primary'` `'secondary'` `'outline'` `'ghost'` `'minimal'` |
+| `color` | `'primary'` `'red'` `'green'` `'blue'` `'pink'` `'yellow'` `'orange'` |
+| `shape` | `'round'` |
+| `icon` | Icon name from svg.js |
+| `size` | `'small'` `'medium'` `'large'` |
+| `disabled` | boolean |
+
+**Methods:** `btn.toggleLoading('Loading...')`, `btn.setLabel('Done', 3000)`
+
+---
+
+### `card({ title, description, content })`
+
+```js
+card({ title: 'Settings', description: 'Configure your app', content: [...] })
+card({ title: 'Note', content: 'Plain text content', border: false })
+```
+
+| Prop | Description |
+|------|-------------|
+| `title` | Card header title |
+| `description` | Subtitle text |
+| `content` | string, element, array, or function |
+| `border` | `false` to remove border (default: true) |
+| `padding` | Override default padding |
+
+---
+
+### `input({ label, placeholder, onSubmit })`
+
+```js
+input({ label: 'Email', placeholder: 'you@example.com' })
+input({ label: 'Search', onSubmit: (value) => search(value) })
+```
+
+| Prop | Description |
+|------|-------------|
+| `label` | Input label |
+| `placeholder` | Placeholder text |
+| `value` | Initial value |
+| `size` | `'default'` `'large'` |
+| `onSubmit` | Called on Enter key |
+
+---
+
+### `switchComponent({ label, checked, color, onChange })`
+
+```js
+switchComponent({ label: 'Dark mode', checked: true })
+switchComponent({ label: 'Notifications', color: 'primary', onChange: (v) => save(v) })
+```
+
+---
+
+### `checkbox({ label, checked, color, onChange })`
+
+```js
+checkbox({ label: 'Accept terms', checked: false })
+checkbox({ label: 'Premium', color: 'blue', checked: true })
+```
+
+---
+
+### `radio({ items, value, color, onChange })`
+
+```js
+radio({
+  value: 'apple',
+  items: [
+    { value: 'apple', label: 'Apple' },
+    { value: 'banana', label: 'Banana' }
+  ]
+})
+```
+
+---
+
+### `selectComponent({ options, value, placeholder, onChange })`
+
+```js
+selectComponent({
+  label: 'Country',
+  placeholder: 'Select...',
+  options: [
+    { value: 'us', label: 'United States' },
+    { value: 'uk', label: 'United Kingdom' }
+  ]
+})
+```
+
+---
+
+### `tabs({ items, variant, active })`
+
+```js
+tabs({
+  variant: 'outline',
+  items: [
+    { label: 'Tab 1', render: () => content1 },
+    { label: 'Tab 2', render: () => content2 }
+  ]
+})
+```
+
+| Prop | Values |
+|------|--------|
+| `variant` | `'default'` `'outline'` `'border'` `'minimal'` `'ghost'` |
+| `active` | Index of initially active tab |
+| `color` | Tab color |
+| `shape` | `'round'` |
+
+---
+
+### `dialog({ content, variant })` / `modal()` / `tooltip()`
+
+```js
+// Programmatic modal
+modal({ open: clickEvent, content: card({ title: 'Confirm' }) })
+
+// Hover tooltip
+tooltip({ open: mouseEvent, content: 'Tooltip text', inverted: true })
+
+// Pre-built confirm dialog
+confirm({
+  label: 'Delete',
+  title: 'Are you sure?',
+  description: 'This cannot be undone',
+  confirm: 'Delete',
+  cancel: 'Cancel',
+  onConfirm: () => handleDelete()
+})
+```
+
+| Prop | Description |
+|------|-------------|
+| `open` / `toggled` | Event or element to trigger |
+| `content` | Dialog content |
+| `variant` / `type` | `'modal'` `'tooltip'` |
+| `position` | `'top'` `'bottom'` `'left'` `'right'` |
+| `inverted` | Dark background |
+
+---
+
+### `avatar({ name, src, description, color, size, variant })`
+
+```js
+avatar({ name: 'John Doe', description: 'Admin', color: 'blue' })
+avatar({ src: 'photo.jpg', name: 'Jane', size: 'large', variant: 'square' })
+```
+
+---
+
+### `collapsible({ label, content, open })`
+
+```js
+collapsible({
+  label: 'Advanced Settings',
+  content: card({ title: 'Settings' })
+})
+```
+
+---
+
+### `label(text, { small, muted })`
+
+```js
+label('Section Title')
+label('Helper text', { small: true, muted: true })
+```
+
+---
+
+### `image({ src, alt, lazy })`
+
+```js
+image({ src: 'photo.jpg', alt: 'Description' })  // lazy-loads by default
+```
+
+---
+
+## Available Utility Classes
+
+### Layout
+`flex`, `flex-col`, `flex-1`, `gap-{1-10}`, `align-{start|center|end|stretch}`, `justify-{start|center|end|between}`
+
+### Spacing
+`pad-{1-10}`, `margin-{1-10}`, `block-{1-10}`, `inline-{1-10}`
+
+### Width
+`w-full`, `w-auto`, `w-{1-10}`
+
+### Text
+`small`, `muted`, `bold`
+
+### Visual
+`border`, `border-{color}`, `shade`, `rounded`
+
+---
+
+## Colors
+
+Available color tokens: `primary`, `red`, `green`, `blue`, `pink`, `yellow`, `orange`
+
+Use with `color` prop on components, or as CSS variables: `var(--primary)`, `var(--red)`, etc.
+
+---
+
+## Best Practices for LLMs
+
+1. **Don't create new CSS** — Use utility classes and component props
+2. **Use layout helpers** — `layout.row([...])` and `layout.col([...])` for structure
+3. **Compose components** — Nest cards, buttons, inputs as children
+4. **Use shorthand props** — `padding: 4` not `class: 'pad-4'`
+5. **Return from render functions** — Tab/collapsible content uses `render: () => element`
+6. **Handle events** — Use `onClick`, `onChange`, `onSubmit` props

package/src/fvn-ui/components/avatar.css

@@ -0,0 +1,53 @@
+.ui-avatar {
+  --size: calc(3.25 * var(--core));
+  display: inline-flex;
+  align-items: center;
+  gap: var(--space-2);
+  font-size: calc(.3 * var(--size));;
+}
+
+.ui-avatar--round {
+  & .ui-avatar__box {
+    border-radius: 50%;
+  }
+}
+
+.ui-avatar--medium {
+  --size: calc(3.75 * var(--core));
+}
+
+.ui-avatar--large {
+  --size: calc(4.5 * var(--core));
+}
+
+.ui-avatar__box {
+  width: var(--size);
+  height: var(--size);
+  border-radius: var(--radius);
+  background: var(--bg, var(--hover));
+  color: var(--fg, var(--text));
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  overflow: hidden;
+  flex-shrink: 0;
+}
+
+.ui-avatar__image {
+  width: 100%;
+  height: 100%;
+}
+
+.ui-avatar__fallback {
+  font-size: calc(var(--size) * .4);
+  font-weight: 500;
+  text-transform: uppercase;
+  letter-spacing: .02em;
+}
+
+.ui-avatar__info {
+  display: flex;
+  flex-direction: column;
+  gap: calc(.025 * var(--size));
+  min-width: 0;
+}

package/src/fvn-ui/components/avatar.js

@@ -0,0 +1,69 @@
+import { el, parseArgs, configToClasses, bemFactory } from '../dom.js'
+import { image } from './image.js'
+import './text.css'
+import './avatar.css'
+
+const bem = bemFactory('avatar');
+
+const getInitials = (name) => {
+  if (!name) {
+    return '';
+  }
+  const parts = name.trim().split(/\s+/);
+  return parts.length > 1
+    ? (parts[0][0] + parts.at(-1)[0]).toUpperCase()
+    : name.slice(0, 2).toUpperCase();
+};
+
+/**
+ * Creates an avatar with image or initials fallback
+ * @param {Object} config
+ * @param {string} [config.src] - Image URL
+ * @param {string} [config.name] - Name (used for initials fallback and alt text)
+ * @param {string} [config.description] - Description text below name
+ * @param {'round'|'square'} [config.variant='round'] - Avatar shape
+ * @param {'small'|'medium'|'large'} [config.size='small'] - Avatar size
+ * @param {'primary'|'red'|'green'|'blue'|'pink'} [config.color] - Background color for initials
+ * @param {string} [config.id] - Registers to dom.avatar[id] and dom[id]
+ * @returns {HTMLDivElement} Avatar element
+ * @example
+ * avatar({ name: 'John Doe', description: 'Admin', color: 'blue' })
+ * avatar({ src: 'photo.jpg', name: 'Jane', size: 'large', variant: 'square' })
+ */
+export function avatar(...args) {
+  const {
+    parent,
+    src,
+    name,
+    description,
+    variant = 'round',
+    size = 'small',
+    color,
+    props,
+    ...rest
+  } = parseArgs(...args);
+
+  const initials = getInitials(name);
+
+  return el('div', parent, {
+    ...rest,
+    class: [bem(), variant !== 'square' && bem('round'), size && bem(size), configToClasses(props), rest.class],
+    children: [
+      el('div', {
+        class: bem.el('box'),
+        data: { uiCol: color || (src ? null : 'primary') },
+        children: [
+          src ? image({ src, alt: name || '', class: bem.el('image') }) : null,
+          !src && initials && el('span', { class: bem.el('fallback'), text: initials })
+        ]
+      }),
+      (name || description) && el('div', {
+        class: bem.el('info'),
+        children: [
+          name && el('span', { class: 'ui-name', text: name }),
+          description && el('span', { class: 'ui-subtitle', text: description })
+        ]
+      })
+    ]
+  });
+}

package/src/fvn-ui/components/button.css

@@ -0,0 +1,143 @@
+.ui-btn {
+  --bg: transparent;
+  --fg: var(--text);
+  border: 1px solid transparent;
+  background: var(--bg);
+  color: var(--fg);
+  border-radius: var(--radius);
+  padding: var(--input-padding);
+  cursor: pointer;
+  user-select: none;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  gap: var(--space-2);
+  position: relative;
+  white-space: nowrap;
+  font: inherit;
+  font-weight: 500;
+  font-size: .9em;
+  transition: var(--core-transition);
+}
+.ui-btn > div {
+  position: relative;
+  z-index: 1;
+  pointer-events: none;
+}
+.ui-btn--muted {
+  color: var(--muted);
+}
+[aria-expanded="true"] .ui-btn--muted,
+:focus-visible + .ui-btn--muted {
+  color: var(--fg);
+}
+.ui-btn:hover {
+  color: var(--fg);
+}
+.ui-btn--sub {
+  --bg: transparent;
+}
+.ui-btn--round {
+   --input-padding: calc(var(--space) * .75) calc(var(--space) * 1.75);
+  border-radius: 999px;
+  gap: var(--space-3);
+}
+.ui-btn--square {
+  --input-padding: calc(var(--space) * .75);
+  aspect-ratio: 1;
+}
+.ui-btn--stripped {
+  --input-padding: 0;
+}
+.ui-btn--minimal {
+  --bg: transparent;
+  --fg: var(--text);
+  &:before {
+    content: '';
+    background: var(--fg);
+    opacity: var(--border-opacity, .25);
+    position: absolute;
+    width: calc(100% - (2 * var(--space)));
+    height: 1px;
+    top: 50%;
+    transform: translatey(.65em);
+  }
+  &:hover:before {
+    opacity: 1;
+  }
+}
+.ui-btn--minimal.ui-col-sub:not(:hover):before {
+  opacity: var(--border-opacity-sub, .25);
+}
+.ui-btn--hover:hover {
+  background: var(--hover);
+  border-color: transparent;
+}
+.ui-btn--hover-sub:hover {
+  --fg: var(--inverted, var(--back));
+  --bg: var(--hover);
+}
+.ui-btn--filled:after {
+  content: '';
+  position: absolute;
+  inset: -1px;
+  border-radius: inherit;
+  transition: opacity var(--core-transition);
+  background: var(--back);
+  opacity: 0;
+  pointer-events: none;
+}
+.ui-btn--filled:hover:after { 
+  opacity: .2;
+}
+.ui-btn:disabled { 
+  opacity: .5; 
+  cursor: not-allowed; 
+}
+.ui-btn--outline {
+  border-color: var(--border);
+}
+.ui-btn__icon {
+  position: relative;
+  width: var(--icon-size, var(--icon-size-default));
+  display: flex;
+  align-items: center;
+  justify-content: center;
+}
+.ui-btn__icon > svg {
+  position: absolute;
+}
+.ui-btn__icon > span {
+  position: relative;
+}
+.ui-btn__icon > span > svg {
+  position: absolute;
+  top: 50%;
+  left: 50%;
+  transform: translate(-50%, -50%);
+}
+
+.ui-btn.loading {
+  --icon-size: var(--core);
+
+  flex-direction: row-reverse;
+  pointer-events: none;
+  position: relative;
+  padding-left: calc(3.5 * var(--space));
+
+  &::before {
+    content: '';
+    width: var(--icon-size, var(--icon-size-default));
+    height: var(--icon-size, var(--icon-size-default));
+    border: 1px solid var(--fg);
+    border-radius: 50%;
+    border-color: var(--fg) var(--fg) var(--fg) transparent;
+    animation: loadingSpin 1s linear infinite;
+    position: absolute;
+    left: var(--space);
+  }
+}
+
+@keyframes loadingSpin {
+  100% { transform: rotate(359deg); }
+}