# TuffEx

<p align="center">
  <img src="https://img.shields.io/npm/v/@talex-touch/tuffex?style=flat-square&logo=npm&color=ff6b6b" alt="NPM Version">
  <img src="https://img.shields.io/badge/Vue-3.5+-4fc08d?style=flat-square&logo=vue.js" alt="Vue 3.5+">
  <img src="https://img.shields.io/badge/tree%20shaking-%E2%9C%93-success?style=flat-square" alt="Tree Shaking">
</p>

TuffEx is the Vue 3 UI source package in the Tuff ecosystem, focused on tactile interaction, animation, and desktop-style UI composition. Runtime demos and public documentation are hosted by Nexus; this package only owns component source, builds, tests, and package audits.

## Installation

```bash
pnpm add @talex-touch/tuffex
```

## Usage

### On-demand import

Use subpath imports for new app and package integrations. This keeps the package root and full stylesheet out of business bundles by default.

```ts
import { createApp } from 'vue'
import { TxButton } from '@talex-touch/tuffex/button'
import { TxCard } from '@talex-touch/tuffex/card'
import { TxDrawer } from '@talex-touch/tuffex/drawer'
import '@talex-touch/tuffex/base.css'
import '@talex-touch/tuffex/button/style.css'
import '@talex-touch/tuffex/card/style.css'
import '@talex-touch/tuffex/drawer/style.css'

const app = createApp(App)
app.use(TxButton)
app.use(TxCard)
app.use(TxDrawer)
```

`@talex-touch/tuffex/base.css` contains shared tokens and global utilities. Keep `@talex-touch/tuffex/style.css` only for legacy full-style imports.

#### Each stylesheet holds one component's rules

`<component>/style.css` contains that component's own rules and nothing else. A
component that builds on others — `progress-bar` uses `tooltip`, which uses
`base-anchor`, which uses `base-surface` — needs their stylesheets imported too,
or it renders unstyled in those parts with no error to point at it.

They used to be self-contained, which meant the base-surface rules were copied
into 26 packages and the spinner's into 29: 2.2 MiB of stylesheets, 68% of it
the same bytes repeated, and a page using five components paid for base-surface
five times over.

Install the build plugin and it works out the set for you, in dependency order:

```ts
// vite.config.ts
import { tuffexOnDemandStylePlugin } from '@talex-touch/tuffex/vite'

export default defineConfig({
  plugins: [tuffexOnDemandStylePlugin()],
})
```

With it in place, importing the component is enough — the stylesheets follow,
and a shared one is loaded once however many components ask for it. A page built
from five components drops from 208 KiB of CSS to 90 KiB (14 KiB gzipped).

Without the plugin, import the closure yourself. `dist/es/style-deps.json` maps
each component to what it depends on.

### Legacy full import

```ts
import { createApp } from 'vue'
import TuffEx from '@talex-touch/tuffex'
import '@talex-touch/tuffex/style.css'

const app = createApp(App)
app.use(TuffEx)
```

The root entry is retained for compatibility and migration windows. Prefer component subpaths for new code.

### Utilities

```ts
import { createToastManager, useVibrate } from '@talex-touch/tuffex/utils'
```

## Component Inventory

Current source-of-truth export modules: **185**.

Every module ships in exactly one of three suites, each exposed as its own category entry:

```ts
import { TxButton } from '@talex-touch/tuffex/base'
import { TxCommandPalette } from '@talex-touch/tuffex/pro'
import { TxPromptBar } from '@talex-touch/tuffex/ai'
```

### base — Basics

General, form, layout, navigation, data, feedback and status components. Import from `@talex-touch/tuffex/base`.

- `General (10)`: `button`, `icon`, `icon-chip`, `icon-picker`, `avatar`, `tag`, `badge`, `status-badge`, `kbd`, `divider`
- `Form (24)`: `form`, `input`, `textarea`, `number-input`, `search-input`, `tag-input`, `sensitive-input`, `scrub-field`, `select`, `flat-select`, `search-select`, `tree-select`, `cascader`, `picker`, `date-picker`, `radio`, `flat-radio`, `checkbox`, `switch`, `slider`, `segmented-slider`, `rating`, `file-uploader`, `image-uploader`
- `Layout (11)`: `container`, `flex`, `grid`, `grid-layout`, `stack`, `splitter`, `scroll`, `collapse`, `card`, `card-item`, `group-block`
- `Navigation (10)`: `tabs`, `tab-bar`, `nav-bar`, `sidebar-nav`, `breadcrumb`, `steps`, `pagination`, `dropdown-menu`, `flat-dropdown`, `context-menu`
- `Data Display (12)`: `data-table`, `descriptions`, `tree`, `sortable-list`, `timeline`, `transfer`, `stat-card`, `cell-link`, `dot-indicator`, `filter-chips`, `markdown-view`, `image-gallery`
- `Feedback (14)`: `dialog`, `modal`, `drawer`, `popover`, `tooltip`, `toast`, `toast-panel`, `alert`, `status-hint`, `progress`, `progress-bar`, `spinner`, `loading-overlay`, `selection-actions`
- `Status & Empty (13)`: `empty`, `empty-state`, `no-data`, `no-selection`, `search-empty`, `error-state`, `offline-state`, `permission-state`, `guide-state`, `blank-slate`, `loading-state`, `skeleton`, `layout-skeleton`

### pro — Advanced

Advanced interaction, visualization, effects and low-level primitives. Import from `@talex-touch/tuffex/pro`.

- `Interaction (7)`: `command-palette`, `search-panel`, `markdown-editor`, `code-editor`, `terminal`, `virtual-list`, `version-capsule`
- `Animated controls (3)`: `motion-control`, `motion-form`, `motion-metric`
- `Visualization (5)`: `charts`, `spark-chart`, `allocation-bar`, `diff-table`, `signal-meter`
- `Effects (25)`: `glass-surface`, `gradient-border`, `outline-border`, `border-beam`, `prism-glow`, `corner-overlay`, `gradual-blur`, `edge-fade-mask`, `glow-text`, `keyframe-stroke-text`, `tuff-logo-stroke`, `text-morph`, `icon-morph`, `morph`, `text-transformer`, `transition`, `stagger`, `fusion`, `fusion-surface`, `flow-light`, `liquid`, `flip-overlay`, `image-generation`, `metal-fx`, `voice-beam`
- `Motion (11)`: `card-spread`, `carousel-3d`, `flip-book`, `motion`, `motion-button`, `motion-dock`, `motion-loader`, `motion-text`, `motion-toggle`, `motion-transition`, `physics-motion`
- `Primitives (5)`: `base-surface`, `base-anchor`, `floating`, `auto-sizer`, `resize-box`

Nexus presents the Motion family in its own documentation suite: Buttons, Card Spreads, 3D Carousels, Loaders, Dither Charts and additional text, physics, pointer, scroll, toggle and transition effects. Installation stays within `pro` or the component subpaths; there is no fourth suite installer. `TxMonoChart` and `TxDitherChart` use the existing `@talex-touch/tuffex/charts` SVG/d3 entry, with Mono documented under Data and Dither under Motion.

Motion content, chart data and business state come from the caller. Changing text reuses TextMorph and springs reuse the existing shared compiler/integrator. `useMotionActivity` is exported from `/utils` to gate playback on visibility, document activity, KeepAlive and reduced-motion preference; static content remains available while playback is suspended.

### ai — AI

Chat, agent, reasoning and context components for AI-native interfaces. Import from `@talex-touch/tuffex/ai`.

- `Chat (9)`: `chat`, `prompt-bar`, `attachment-tray`, `mode-chip`, `message-actions`, `suggestion-chips`, `choice-card`, `conversation-stream`, `voice-clip`
- `Agents (10)`: `agents`, `agent-screen`, `agent-trace`, `task-rows`, `tool-call-card`, `tool-chips`, `tool-confirmation`, `approval-card`, `working-indicator`, `bot-avatar`
- `Reasoning (10)`: `ai-elements`, `chain-of-thought`, `reasoning-disclosure`, `thinking-orb`, `stream-element`, `stream-text`, `stream-markdown`, `code-stream`, `inline-citation`, `sources`
- `Context & Insight (5)`: `context-cards`, `context-indicator`, `insight-cards`, `recommendation-card`, `fine-tune-card`
- `Flow (1)`: `flowchart`

Reference:

- Export entry: `packages/components/src/components.ts`
- Suite entries: `packages/components/src/{base,pro,ai}/index.ts`
- Suite taxonomy: `apps/nexus/scripts/recategorize-component-docs.py`
- Public docs: `apps/nexus/content/docs/dev/tools/tuffex.en.mdc`

## Export Convention

- Preferred public names use `Tx*` prefix, for example `TxButton`, `TxDialog`.
- Some modules also keep compatibility aliases (for example `Button` / `TxButton` in certain modules).
- Type exports are included and can be consumed directly from `@talex-touch/tuffex`.

## Documentation

- Online docs: [tuffex.tagzxia.com/docs/dev/tuffex](https://tuffex.tagzxia.com/docs/dev/tuffex)
- Local docs preview: `pnpm -C "apps/nexus" run dev`
- Component Changelog & Since Index: [CHANGELOG.md](./CHANGELOG.md)

## Development

```bash
pnpm install
pnpm -C "packages/tuffex" run lint
pnpm -C "packages/tuffex" run typecheck
pnpm -C "packages/tuffex" run test
pnpm -C "packages/tuffex" run build
pnpm -C "packages/tuffex" run audit:size
pnpm -C "packages/tuffex" run audit:exports
pnpm -C "packages/tuffex" run audit:types
pnpm -C "packages/tuffex" run audit:changelog
```

## Integration with Tuff

TuffEx is the UI foundation of the [Tuff](https://tuff.tagzxia.com) desktop application. Components are shared between the core app and external plugin developers through this standalone library.

## Contributing

- [Report Issues](https://github.com/talex-touch/tuff/issues)
- [Feature Requests](https://github.com/talex-touch/tuff/discussions)
- [Submit PRs](https://github.com/talex-touch/tuff/pulls)

## License

[MIT License](LICENSE) &copy; 2025 TalexDreamSoul

Amicro-derived components retain [the upstream MIT license and copyright](AMICRO-LICENSE), from source commit `43c29ce9cdd16459e3eab4992381b8d35b38776a`. The notice ships with the package. Upstream website assets and externally hosted fonts are not included.

The upstream `DitherBook.tsx` and `SimpleCompExtracted.tsx` declare Apache-2.0 at file level. Their derivatives retain that license and Vue/TuffEx modification notices; the complete [Apache license](AMICRO-APACHE-LICENSE) ships in the package. Retained Lucide 0.546.0 glyph data carries its [ISC and Feather-derived MIT notice](LUCIDE-LICENSE), without a React/Lucide runtime dependency. Package metadata records these combined obligations instead of relabeling all derived code as MIT.