# KunUI

> Cross-framework component library — 87 Tailwind v4 Vue components, framework-agnostic design tokens + core, with a Nuxt layer. Published on npm under the @kungal scope; the four packages are versioned in lockstep.

Packages:
- @kungal/ui-tokens: Tailwind v4 design tokens (CSS): semantic colors, radius, z-index, animations, dark variant, optional base layer.
- @kungal/ui-core: Framework-agnostic TypeScript core: cn(), the variant/class matrix, the radius system, the bundled-icon registry, shared types (KunUIColor, KunUser, …).
- @kungal/ui-vue: The Vue 3 component layer (works in any Vue 3.5+ app).
- @kungal/ui-nuxt: A Nuxt 4 layer that wraps @kungal/ui-vue and auto-imports everything + injects NuxtLink / @nuxt/icon / @nuxt/image.

## Critical rules (read before using)

- **HTML is never sanitized.** KunUI ships no sanitizer. KunContent (the `content` prop, rendered via v-html) and useKunMessage(msg, type, dur, richText=true) render raw HTML exactly as given. Sanitize untrusted/user HTML yourself (e.g. DOMPurify) BEFORE passing it in. Fully-trusted/author content may be passed directly.
- **Icons are bundled, never fetched.** KunIcon renders inline SVG from an in-memory registry seeded with the icons the components need — it NEVER calls the Iconify API at runtime. Use bundled names like `lucide:check`. Register your own with registerKunIcon(name, {body}) / registerKunIcons({...}) from @kungal/ui-core at startup. Unknown names render the injected iconComponent fallback (the Nuxt layer wires @nuxt/icon; plain Vue renders nothing).
- **The consumer owns the Tailwind entry.** KunUI does NOT ship one all-in-one stylesheet. Your app's CSS entry must contain: `@import 'tailwindcss';` then `@import '@kungal/ui-tokens';` then `@import '@kungal/ui-vue/style.css';` (scoped component styles) plus `@source` directives pointing at @kungal/ui-vue and @kungal/ui-core so Tailwind generates the utility classes the components use. Under pnpm, install @kungal/ui-vue and @kungal/ui-core as DIRECT deps so the @import/@source resolve. Dark mode = toggle the `kun-dark-mode` class on <html>.

## Install

Nuxt — `extends: ["@kungal/ui-nuxt"]` in nuxt.config, then add the CSS entry:

```bash
pnpm add @kungal/ui-nuxt @kungal/ui-vue @kungal/ui-core @kungal/ui-tokens tailwindcss @tailwindcss/vite
```

Plain Vue — `app.use(KunUI)` (or import components directly):

```bash
pnpm add @kungal/ui-vue @kungal/ui-core @kungal/ui-tokens tailwindcss @tailwindcss/vite
```

See the Integration guide for the required Tailwind entry stylesheet.

## Documentation

- [Integration guide](https://github.com/kungal/kun-ui/blob/main/docs/INTEGRATION.md): Full setup for Nuxt and plain Vue: install, the Tailwind entry CSS, dark mode, icons, KunUIConfig, providers, security, SSR, full reference.
- [Using KunUI with AI tools](https://github.com/kungal/kun-ui/blob/main/docs/USING-WITH-AI.md): How to point Claude Code / Cursor at KunUI and a paste-able rules block.
- [Releasing](https://github.com/kungal/kun-ui/blob/main/docs/RELEASING.md): How the four packages are versioned and published (Changesets + npm OIDC).
- [Architecture](https://github.com/kungal/kun-ui/blob/main/docs/architecture.md): Why the library is split into tokens / core / vue / nuxt.
- [Architecture: Flutter](https://github.com/kungal/kun-ui/blob/main/docs/architecture-flutter.md): Why Flutter gets generated tokens/icons/motion and a hand-written widget layer, never shared component code.

## Components

In Nuxt all are auto-imported. In plain Vue import them from @kungal/ui-vue (or register globally via app.use(KunUI)).

### Layout & display
- KunCard: Container/panel with color + variant; renders as a link when given href/to.
- KunDivider: Horizontal/vertical separator with an optional centered label.
- KunHeader: Section heading (scale h1–h6) with brand styling.
- KunInfo: Inline callout box (color, icon, title, description; solid/flat/bordered). Rich body content goes in the default slot — there is no `description` slot; the heading has a `title` slot.
- KunBanner: Full-width one-sentence announcement strip for the top of a page, in normal flow above the sticky header (text or default slot, icon, `solid`/`flat`, `closable`; the `#actions` slot gets `{ dismiss }`). `size="sm"` is a 32px `text-xs` strip for a standing, non-dismissable notice that would otherwise wrap tall on a phone. Bind `v-model`, not `v-if`, so it can collapse on close. `storageKey` keeps a closed banner closed across reloads (localStorage, hidden before first paint under SSR by an inline script; pass `nonce` under a strict CSP); use a new key per announcement.
- KunProgress: Progress bar: linear/striped/gradient/circle, indeterminate, optional label.
- KunBadge: Count/dot badge wrapping a trigger (e.g. a button/icon); `max` caps the count.
- KunChip: Small tag/pill with color + variant.
- KunKbd: Keyboard shortcut badge: `keys="Mod+K"` renders ⌘K on Apple and Ctrl K elsewhere (server renders Ctrl, a Mac switches after mount); screen readers hear key names. `variant="plain"` is the one-line menu form (⇧⌘Z / Ctrl+Shift+Z).
- KunScrollShadow: Horizontal scroll container with edge fade shadows.
- KunSplitPane: Two panes with a draggable, keyboard-adjustable divider (#start / #end slots). `v-model:size` is the primary pane width in px (server-rendered); `resize-end` is the event to persist; `min-size` / `max-size`, `snap-points` (pulled within `snap-threshold`), `primary="end"` for an auxiliary right column. Stacks to one pane (`show-pane`) below `stack-below` of its OWN width (container query, default md = 48rem).
- KunFadeCard: Fade + expand transition wrapper for conditional content.
- KunNull: Empty-state placeholder with a bundled mascot image + caption (`description`, `src`, `isShowSticker`).
- KunAccordion: Collapsible sections (v-model string | string[]; `multiple`, variants light/bordered/splitted). Wraps KunAccordionItem.
- KunAccordionItem: One accordion section: `value` (required), `title`/`icon` or the `title` slot, `disabled`.
- KunSkeleton: Loading placeholder (variant text/circle/rect, width/height); set `loaded` to swap in the real content.
- KunSteps: Step / progress indicator (items array, `current` index; horizontal or vertical). Bind `v-model:current` to make steps clickable (`linear` keeps clicks backward-only); per-item `disabled` and `status: 'error'`.
- KunTimeline: Vertical timeline container for KunTimelineItem.
- KunTimelineItem: One timeline entry (title, time, icon, color + default slot for the body).

### Buttons & feedback
- KunButton: Button: color/variant/size, loading state; renders as a link with href/to.
- KunButtonGroup: Joins adjacent KunButtons into one segmented control (horizontal/vertical; merges the touching radii).
- KunRipple: Material-style ripple effect.
- KunLoading: Loading state: overlay over wrapped content (default slot) or standalone; bundled mascot image (`src`, `loading`, `description`).
- KunCopy: Copy-to-clipboard button with feedback.
- KunRating: Star rating input (v-model number).
- KunReaction: Like / reaction toggle (v-model boolean) with an animated icon and an optional `count`.
- KunShatter: Breaks its slot content into flying glass shards on click, and can fly them back (`pieces`, `gravity`, `reassemble`, `autoRestore`). Compositor-only (transform + opacity), zero deps.

### Media & content
- KunImage: Image with skeleton/aspect/objectFit; uses the injected image component (NuxtImg in Nuxt).
- KunCarousel: Swipeable carousel (arrows, indicators, `loop`, `autoplay` ms, `slidesPerView`). Wraps KunCarouselItem.
- KunCarouselItem: One carousel slide.
- KunImageNative: Bare <img> with class merging (no optimization pipeline).
- KunIcon: Inline SVG icon from the bundled registry; never fetches. `name` like `lucide:x`. Inherits text color.
- KunBrand: Logo + name brand block, links home; optional badge.
- KunContent: Renders HTML (`content`) via v-html with spoiler + inline-image lightbox. DOES NOT sanitize — caller must.
- KunText: Safe-wrapping text block (handles long URLs/underscores).
- KunMarkdown: The KunUI markdown glyph.

### Navigation & overlays
- KunLink: Styled link; uses the injected link component (NuxtLink in Nuxt).
- KunNavItem: One destination of an app shell's navigation: a full-width KunButton, `flat` in `color` and `aria-current="page"` while `current`, `light` otherwise. `stacked` puts the icon over the label (rail, bottom bar); the `#icon` slot takes a KunBadge-wrapped icon for an unread count.
- KunTab: Tab bar (v-model value, items array; variants, orientation). Items with `href` render real <a> for crawlable tab-as-route.
- KunTabPanel: One tab's content. SEO-first: mount=eager (default) SSRs every panel and hides inactive ones with hidden="until-found" (indexable + findable); mount=lazy/unmount opt out. Pairs with KunTab via `value`/`name`.
- KunTabPanels: Optional wrapper sharing active (v-model) + mount/hiddenStrategy defaults across KunTabPanels, and auto-wiring find-in-page reveal.
- KunModal: Dialog teleported to body, focus-trapped, body-scroll-locked, Escape to close (v-model boolean).
- KunDrawer: Slide-in panel from any edge (placement, size; v-model boolean).
- KunTooltip: Hover/focus tooltip (text + trigger slot); `shortcut="Mod+K"` appends KunKbd keys.
- KunPopover: Floating popover anchored to a trigger slot.
- KunHoverCard: Preview card for a link (a user card on an avatar): opens on mouse hover after `openDelay` or on keyboard `:focus-visible`, never on touch; a click is never intercepted — it follows the link and closes the card. The trigger wrapper is `display: contents`, so it does not change the trigger's layout; the card anchors to the trigger slot's first element. No role and no focus move: the link stays the accessible interface, so put nothing in the card that the destination page lacks. The card mounts only while open (fetch in its setup) and its default slot gets `{ close }`; `v-model:open` tracks it. `group` = one open at a time across a list, siblings switch instantly. `disabled` renders the trigger alone.
- KunDropdown: Menu of items anchored to a trigger (items array: `{ type: 'separator' }` rows, per-item `shortcut`, and `children` for one level of submenu).
- KunContextMenu: Right-click context menu (same items array as KunDropdown: separators, `shortcut`, one level of `children`).
- KunCommandPalette: Command-palette SHELL (v-model:open + ⌘K/Ctrl-K, v-model:query): dialog, keyboard nav, grouped rendering, match highlighting, a11y. It does NOT search — YOU compute `items` (flat, or KunCommandGroup[]) from `query`; picking one emits @select.
- KunPagination: Page navigation (v-model:current-page, total-page) with quick-jump.
- KunLightbox: Image lightbox/viewer (v-model:is-open, images array).
- KunLightboxGallery: Gallery wrapper; click an item to open the lightbox.
- KunLightboxGalleryItem: A single gallery item (src + slot for the thumbnail).

### Chat
- KunChatLayout: Responsive chat shell: conversation list and conversation side by side once the layout ITSELF is 48rem wide (container query, not the window), one pane at a time below (`show-conversation`). `resizable` + `v-model:sidebar-size` (px) make the list draggable via KunSplitPane. Slots #sidebar / default / #empty.
- KunChatMessageList: Conversation scrollback for NextMoe `/v2/chat` messages (string ids): sender runs, sticky day pills, unread divider (opens there), older/newer paging without jumps, stick-to-bottom, scroll-down button with unread count, `scrollToSeq(seq)` + highlight, right-click / long-press menu, swipe-left to reply. Emits load-older, load-newer, read, jump, action, react, retry.
- KunChatBubble: One message: own (right, primary tint) or theirs; reply / quote preview, photo or Telegram-mosaic album (lightbox), context card, reactions, time / edited / status (failed → `retry`). A service message renders as a centred pill. Photos show `media.url` unless `resolve-media-url` is passed.
- KunChatText: Renders message `text` + `entities` (UTF-16 ranges): bold, italic, underline, strike, spoiler (click reveals all), code, pre (language + copy), blockquote, links, mentions. No v-html. `preview` = one-line form with masked spoilers.
- KunChatComposer: Message input: auto-grow, Enter sends (touch: newline), composer markdown → `send({ text, entities })`, v-model:reply-to / quote / editing bars, attachments (paste / drop / pick → `attach(files)`), 4096 counter, throttled `typing`.
- KunChatConversationItem: Conversation-list row: avatar, title, time + status, preview (typing › draft › last message), unread / @ badges, muted, pinned, selected; touch swipe actions.
- KunChatHeader: Conversation top bar: back (mobile), avatar, title, subtitle that becomes "typing…"; #actions slot.
- KunChatPinnedBar: Pinned-message bar: newest first, each click emits `jump(seq)` and steps to the next older one.
- KunChatRequestBar: Message-request bar: accept / delete / block / report, with a per-action loading state.
- KunChatMessageMenu: Message context menu at a point: quick-reaction row (expands to the full picker) + site-chosen actions (reply, quote, copy, edit, pin, unpin, delete, report, retry, or custom items).
- KunChatReactionPicker: Reaction vocabulary grid (v-model key | null); animated `image_url` art or native emoji; one reaction per person.
- KunChatTyping: Three-dot typing indicator + "X is typing…"; takes raw typing events and expires each after 6 s (useKunChatTyping).

### Forms
- KunInput: Text input (v-model) with label/helper/error, sizes, variants.
- KunTextarea: Multiline input (v-model) with optional counter.
- KunNumberInput: Numeric input (v-model number|null) with steppers, min/max/step, precision, clamping.
- KunPinInput: OTP / PIN segmented input (v-model string): per-cell entry, paste, masking, complete event.
- KunSelect: Select dropdown (v-model, options array); single/multiple, searchable, clearable. Remote sources via manualFilter + @search + loading + debounce; maxVisibleTags collapses chips; fullWidth/icon/popupWidth/classNames shape it into a filter pill.
- KunAutocomplete: Combobox: a text field (v-model string) with a filtered suggestion list; allowCustomValue / manualFilter.
- KunSwitch: Toggle switch (v-model boolean).
- KunCheckBox: Checkbox (v-model boolean).
- KunCheckBoxGroup: Multi-select checkbox group (v-model array, options array; `max`, orientation, label/error).
- KunSlider: Range slider (v-model number; min/max/step).
- KunRadioGroup: Radio group (v-model, options array; card/classic variants).
- KunDatePicker: Date / date-range picker (date-fns based; v-model). `precision` picks a day, month or year (value 'yyyy-MM-dd' / 'yyyy-MM' / 'yyyy'), orthogonal to `mode`; the panel header zooms out day → month → year.
- KunFileInput: File picker button (v-model File | File[]); default trigger icon is bundled.
- KunTagInput: Tag entry input (v-model string[]; split chars, validation, max).
- KunUpload: Drag/drop image upload with crop (size, aspect).

### People
- KunAvatar: User avatar (KunUser); navigates to userLinkTemplate on click; sticker fallback.
- KunAvatarGroup: Stacked avatars with +N overflow.
- KunUserChip: Avatar + name + description chip.

### Overlay providers (mount once near app root)
- KunMessageProvider: Renders toasts triggered by useKunMessage(). Mount once.
- KunAlertProvider: Renders confirm dialogs triggered by useKunAlert(). Mount once.
- KunLoliProvider: Renders the mascot popup triggered by useKunLoliInfo(). Mount once.
- KunLoli: The standalone mascot popup component.

## Composables

- useKunMessage / useKunMessageState: Trigger / read toasts. useKunMessage(message, type, duration=3000, richText=false, position="top-center").
- useKunAlert / useKunAlertState: Trigger / read confirm dialogs. useKunAlert(opts?) returns Promise<boolean>.
- useKunLoliInfo / useKunLoliState: Trigger / read the mascot popup.
- useKunUIConfig / provideKunUIConfig / installKunUIConfig: Read/set KunUIConfig (rounded, linkComponent, navigate, imageComponent, iconComponent, userLinkTemplate).
- useKunCopy: Copy-to-clipboard helper.
- useKunUniqueId: SSR-safe unique id generation.
- useResolvedRounded: Resolve a component's effective radius.
- useRipple: Ripple effect logic.
- useFilePicker: Programmatic file selection.
- useContentLightbox / useSpoilerContent: Enhancers used by KunContent.

From @kungal/ui-core (framework-agnostic): cn, registerKunIcon, registerKunIcons, getKunIcon, hasKunIcon, the variant class helpers (kunBgClasses, kunTextClasses, kunRingClasses, …), and types KunUIColor, KunUISize, KunUIVariant, KunUIRounded, KunUser.