@tcn/ui 0.17.0 → 0.18.1

package/AI_USAGE.md

@@ -0,0 +1,59 @@
+# @tcn/ui — AI Usage Guide
+
+**Load this file when:** the project uses `@tcn/ui` and you are building UI — layouts, forms, inputs, surfaces, overlays, navigation, or themed components.
+
+> For source files referenced in linked docs, prefix paths with `node_modules/@tcn/ui/` in app projects.
+
+---
+
+## Overview
+
+`@tcn/ui` provides a component library where **surfaces** are the starting point and **layouts** provide structure within them. Themes control all visual appearance.
+
+| Concept | Summary |
+|---|---|
+| **Surfaces** | The starting point. `Panel`, `Card`, `Page`, `Modal`, `Drawer`, `Window` are styled containers that wrap a `Scaffold` internally. `Tooltip`, `Popover`, `PopConfirm`, `Alert` are functional surfaces for contextual feedback. Surfaces provide themed visual treatment — borders, shadows, backgrounds. |
+| **Layouts** | Structure inside surfaces. `Scaffold` (vertical), `Rail` (horizontal), `Header`/`Footer`, `Section`, `Columns`/`Rows`, `Grid`, `Responsive`/`Breakpoint`. Use these to build the internal structure of a surface — headers, footers, columns, sections. |
+| **Inputs** | 20+ input types: `Input`, `Select`, `ComboBox`, `DatePicker`, `Checkbox`, `Radio`, `Switch`, `MaskInput`, etc. |
+| **Form** | `Field`, `HField`/`VField`, `FieldSet`, `FieldPresenter`. Compose with inputs. |
+| **Theming** | Swappable stylesheets (Ergo, Windows 98). CSS layers: `tcn-reset` < `tcn-system` < `tcn-theme`. Components expose `tcn-*` classes and `data-*` attributes. |
+| **Stacks** | `VStack`, `HStack`, `ZStack`, `Box` — the atomic primitives underneath layouts and surfaces. Rarely used directly in apps — prefer named layout components for semantic clarity. Use stacks when building custom reusable components. |
+
+---
+
+## Decision Tree — What Are You Building?
+
+| Task | Read |
+|---|---|
+| Styled containers — panels, cards, pages, modals, drawers, tooltips, popovers | [ai-docs/surfaces.md](ai-docs/surfaces.md) |
+| Structure within surfaces — headers, footers, sections, columns, rows, grids | [ai-docs/layouts.md](ai-docs/layouts.md) |
+| Form with fields (labels, validation, groups) | [ai-docs/form.md](ai-docs/form.md) |
+| Input components (text, select, date, etc.) | [ai-docs/inputs.md](ai-docs/inputs.md) |
+| Overlays/popups (portals, poppers, menus) | [ai-docs/overlay.md](ai-docs/overlay.md) |
+| Navigation (tabs, links) | [ai-docs/navigation.md](ai-docs/navigation.md) |
+| Buttons and toggles | [ai-docs/actions.md](ai-docs/actions.md) |
+| Loading, progress, lazy rendering | [ai-docs/feedback.md](ai-docs/feedback.md) |
+| Theming, CSS variables, custom styling | [ai-docs/themes.md](ai-docs/themes.md) |
+| Text and headings | [ai-docs/typography.md](ai-docs/typography.md) |
+| Drag and resize behavior | [ai-docs/decorators.md](ai-docs/decorators.md) |
+| Chips, badges, key-value tokens | [ai-docs/tokens.md](ai-docs/tokens.md) |
+| Hooks, calendar, ref utilities | [ai-docs/utils.md](ai-docs/utils.md) |
+| Mobile-specific components | [ai-docs/mobile.md](ai-docs/mobile.md) |
+| Building custom components (VStack, HStack, Box primitives) | [ai-docs/stacks.md](ai-docs/stacks.md) |
+
+Only load a topic doc when the current task matches. Do not load all docs preemptively.
+
+**Cross-module hints:** Start with a Surface (Panel, Card, Page), then use Layouts (Header, Footer, Section, Columns) to build its internal structure. Form and Inputs are tightly coupled (inputs slot into Field). Overlay powers positioned surfaces like Modal and Drawer. Themes are needed for any custom styling. Stacks are rarely needed directly — use named layout components instead.
+
+---
+
+## Critical Rules
+
+- **Surfaces first, then layouts** — start with a surface (Panel, Card, Page), then use layouts (Header, Footer, Section, Columns) for internal structure. Stacks are for building custom components, not app-level UI
+- **Dual class names** — every component gets a CSS module class + a `tcn-` prefixed theme class
+- **Data attributes for state** — use `data-disabled`, `data-hierarchy`, `data-size` etc. (not conditional classes)
+- **Composition over configuration** — use `<Select><Option>` not `<Select options={[...]}>`
+- **onChange convention** — value first, event second
+- **Theme variables for custom components** — import from `theme_variables`, never hardcode colors/spacing
+- **Decorators for behavior** — use `<Resizable>` / `<Draggable>` wrappers, not props on layout components
+- **Mobile uses separate roots** — not responsive breakpoints within desktop components