torch-glare 2.3.0 → 2.4.1

package/docs/components/transparent-label.md

@@ -11,13 +11,22 @@ keywords: [transparent-label, text, typography, gradient, fade, truncate]
 
 ## Installation
 
-No external dependencies required.
+TORCH Glare is a copy-in library: the CLI copies this component's source into your project
+(you do **not** install it from the npm package). Run `init` once, then `add`:
+
+```bash
+npx torch-glare@latest init
+npx torch-glare@latest add TransparentLabel
+```
+
+`add` also copies any components, hooks, and utilities that `TransparentLabel` depends on.
 
 ## Import
 
-```typescript
-import { TransparentLabel } from '@torch-ui/components'
-import type { TransparentLabelProps } from '@torch-ui/components'
+Import from your project's local path — the alias configured in `glare.json` (e.g. `@/*`):
+
+```tsx
+import { TransparentLabel } from "@/components/TransparentLabel";
 ```
 
 ## Quick Examples
@@ -25,7 +34,7 @@ import type { TransparentLabelProps } from '@torch-ui/components'
 ### Basic Usage
 
 ```typescript
-import { TransparentLabel } from '@torch-ui/components'
+import { TransparentLabel } from "@/components/TransparentLabel";
 
 function Example() {
   return (
@@ -39,7 +48,7 @@ function Example() {
 ### Different Sizes
 
 ```typescript
-import { TransparentLabel } from '@torch-ui/components'
+import { TransparentLabel } from "@/components/TransparentLabel";
 
 function Sizes() {
   return (
@@ -67,7 +76,7 @@ function Sizes() {
 ### Truncating Long Text
 
 ```typescript
-import { TransparentLabel } from '@torch-ui/components'
+import { TransparentLabel } from "@/components/TransparentLabel";
 
 function TruncatedText() {
   const longText = "This is a very long text that needs to be truncated gracefully with a fade-out effect instead of showing ellipsis or cutting off abruptly"
@@ -85,7 +94,7 @@ function TruncatedText() {
 ### Typography Variants
 
 ```typescript
-import { TransparentLabel } from '@torch-ui/components'
+import { TransparentLabel } from "@/components/TransparentLabel";
 
 function TypographyShowcase() {
   return (
@@ -125,8 +134,8 @@ function TypographyShowcase() {
 ### Card with Fade Effect
 
 ```typescript
-import { TransparentLabel } from '@torch-ui/components'
-import { Card } from '@torch-ui/components'
+import { TransparentLabel } from "@/components/TransparentLabel";
+import { Card } from "@/components/Card";
 
 function ProductCard() {
   return (
@@ -148,7 +157,7 @@ function ProductCard() {
 ### List with Truncated Items
 
 ```typescript
-import { TransparentLabel } from '@torch-ui/components'
+import { TransparentLabel } from "@/components/TransparentLabel";
 
 function TruncatedList() {
   const items = [
@@ -175,7 +184,7 @@ function TruncatedList() {
 ### Navigation with Fade
 
 ```typescript
-import { TransparentLabel } from '@torch-ui/components'
+import { TransparentLabel } from "@/components/TransparentLabel";
 
 function Navigation() {
   const navItems = [
@@ -207,7 +216,7 @@ function Navigation() {
 ### Breadcrumbs
 
 ```typescript
-import { TransparentLabel } from '@torch-ui/components'
+import { TransparentLabel } from "@/components/TransparentLabel";
 
 function Breadcrumbs() {
   const crumbs = [
@@ -240,7 +249,7 @@ function Breadcrumbs() {
 ### Table Cell with Fade
 
 ```typescript
-import { TransparentLabel } from '@torch-ui/components'
+import { TransparentLabel } from "@/components/TransparentLabel";
 
 function DataTable() {
   const data = [
@@ -287,7 +296,7 @@ function DataTable() {
 ### Custom Color with Fade
 
 ```typescript
-import { TransparentLabel } from '@torch-ui/components'
+import { TransparentLabel } from "@/components/TransparentLabel";
 
 function ColoredLabels() {
   return (
@@ -320,7 +329,7 @@ function ColoredLabels() {
 ### RTL Support
 
 ```typescript
-import { TransparentLabel } from '@torch-ui/components'
+import { TransparentLabel } from "@/components/TransparentLabel";
 
 function RTLExample() {
   return (
@@ -451,7 +460,7 @@ export const TransparentLabel: React.FC<TransparentLabelProps>
 ### Usage with Types
 
 ```typescript
-import { TransparentLabel } from '@torch-ui/components'
+import { TransparentLabel } from "@/components/TransparentLabel";
 import { useState } from 'react'
 
 type Size = 'body-medium-regular' | 'body-large-bold' | 'headers-medium-semibold'
@@ -483,7 +492,7 @@ function TypedExample() {
 ### Truncated Text Component
 
 ```typescript
-import { TransparentLabel } from '@torch-ui/components'
+import { TransparentLabel } from "@/components/TransparentLabel";
 import { useState } from 'react'
 
 interface TruncatedTextProps {
@@ -518,7 +527,7 @@ function TruncatedText({ text, maxWidth = '200px', size = 'body-medium-regular'
 ### Responsive Typography
 
 ```typescript
-import { TransparentLabel } from '@torch-ui/components'
+import { TransparentLabel } from "@/components/TransparentLabel";
 import { useMediaQuery } from '@/hooks/useMediaQuery'
 
 function ResponsiveText() {
@@ -540,7 +549,7 @@ function ResponsiveText() {
 
 ```typescript
 import { render, screen } from '@testing-library/react'
-import { TransparentLabel } from '@torch-ui/components'
+import { TransparentLabel } from "@/components/TransparentLabel";
 
 describe('TransparentLabel', () => {
   it('renders text content', () => {

package/docs/components/tree-drop-down.md

@@ -11,14 +11,22 @@ keywords: [tree, dropdown, navigation, expandable, collapsible, accordion, hiera
 
 ## Installation
 
+TORCH Glare is a copy-in library: the CLI copies this component's source into your project
+(you do **not** install it from the npm package). Run `init` once, then `add`:
+
 ```bash
-npm install class-variance-authority
+npx torch-glare@latest init
+npx torch-glare@latest add TreeDropDown
 ```
 
+`add` also copies any components, hooks, and utilities that `TreeDropDown` depends on.
+
 ## Import
 
-```typescript
-import { TreeDropDown } from '@torch-ui/components'
+Import from your project's local path — the alias configured in `glare.json` (e.g. `@/*`):
+
+```tsx
+import { TreeDropDown } from "@/components/TreeDropDown";
 ```
 
 ## Quick Examples
@@ -26,7 +34,7 @@ import { TreeDropDown } from '@torch-ui/components'
 ### Basic Usage
 
 ```typescript
-import { TreeDropDown } from '@torch-ui/components'
+import { TreeDropDown } from "@/components/TreeDropDown";
 
 function Example() {
   return (
@@ -42,7 +50,7 @@ function Example() {
 ### Nested Tree Structure
 
 ```typescript
-import { TreeDropDown } from '@torch-ui/components'
+import { TreeDropDown } from "@/components/TreeDropDown";
 
 function FileTree() {
   return (
@@ -65,7 +73,7 @@ function FileTree() {
 ### Controlled State
 
 ```typescript
-import { TreeDropDown } from '@torch-ui/components'
+import { TreeDropDown } from "@/components/TreeDropDown";
 import { useState } from 'react'
 
 function ControlledTree() {
@@ -92,8 +100,8 @@ function ControlledTree() {
 ### With Custom Labels
 
 ```typescript
-import { TreeDropDown } from '@torch-ui/components'
-import { Badge } from '@torch-ui/components'
+import { TreeDropDown } from "@/components/TreeDropDown";
+import { Badge } from "@/components/Badge";
 
 function TreeWithBadges() {
   return (
@@ -101,7 +109,7 @@ function TreeWithBadges() {
       treeLabel={
         <div className="flex items-center gap-2">
           <span>Notifications</span>
-          <Badge variant="red" label="3" size="XS" />
+          <Badge color="redOrange" label="3" size="XS" />
         </div>
       }
     >
@@ -116,7 +124,7 @@ function TreeWithBadges() {
 ### Documentation Navigation
 
 ```typescript
-import { TreeDropDown } from '@torch-ui/components'
+import { TreeDropDown } from "@/components/TreeDropDown";
 
 function DocsNavigation() {
   return (
@@ -152,7 +160,7 @@ function DocsNavigation() {
 ### Dark Theme
 
 ```typescript
-import { TreeDropDown } from '@torch-ui/components'
+import { TreeDropDown } from "@/components/TreeDropDown";
 
 function DarkTree() {
   return (
@@ -172,7 +180,7 @@ function DarkTree() {
 ### With Icons
 
 ```typescript
-import { TreeDropDown } from '@torch-ui/components'
+import { TreeDropDown } from "@/components/TreeDropDown";
 
 function IconTree() {
   return (
@@ -200,7 +208,7 @@ function IconTree() {
 ### Multi-Level Navigation
 
 ```typescript
-import { TreeDropDown } from '@torch-ui/components'
+import { TreeDropDown } from "@/components/TreeDropDown";
 
 function MultiLevelNav() {
   return (
@@ -227,7 +235,7 @@ function MultiLevelNav() {
 ### Custom Styling
 
 ```typescript
-import { TreeDropDown } from '@torch-ui/components'
+import { TreeDropDown } from "@/components/TreeDropDown";
 
 function StyledTree() {
   return (
@@ -247,7 +255,7 @@ function StyledTree() {
 ### Initially Expanded
 
 ```typescript
-import { TreeDropDown } from '@torch-ui/components'
+import { TreeDropDown } from "@/components/TreeDropDown";
 
 function ExpandedByDefault() {
   return (
@@ -308,7 +316,7 @@ export const TreeDropDown: React.FC<TreeDropDownProps>
 ### Usage with TypeScript
 
 ```typescript
-import { TreeDropDown } from '@torch-ui/components'
+import { TreeDropDown } from "@/components/TreeDropDown";
 import { ReactNode } from 'react'
 
 interface TreeItem {
@@ -337,7 +345,7 @@ function TypedTree({ items }: { items: TreeItem[] }) {
 ### Recursive Tree Structure
 
 ```typescript
-import { TreeDropDown } from '@torch-ui/components'
+import { TreeDropDown } from "@/components/TreeDropDown";
 
 interface TreeNode {
   id: string
@@ -383,7 +391,7 @@ const data: TreeNode[] = [
 ### Expand/Collapse All
 
 ```typescript
-import { TreeDropDown } from '@torch-ui/components'
+import { TreeDropDown } from "@/components/TreeDropDown";
 import { useState } from 'react'
 
 function ExpandCollapseAll() {
@@ -412,7 +420,7 @@ function ExpandCollapseAll() {
 ### With Active State
 
 ```typescript
-import { TreeDropDown } from '@torch-ui/components'
+import { TreeDropDown } from "@/components/TreeDropDown";
 import { useState } from 'react'
 
 function NavigationTree() {
@@ -491,7 +499,7 @@ function NavigationTree() {
 
 ```typescript
 import { render, screen, fireEvent } from '@testing-library/react'
-import { TreeDropDown } from '@torch-ui/components'
+import { TreeDropDown } from "@/components/TreeDropDown";
 
 describe('TreeDropDown', () => {
   it('renders tree label', () => {
@@ -549,7 +557,7 @@ describe('TreeDropDown', () => {
 
 ```typescript
 import { render, screen, fireEvent } from '@testing-library/react'
-import { TreeDropDown } from '@torch-ui/components'
+import { TreeDropDown } from "@/components/TreeDropDown";
 
 test('nested trees work independently', () => {
   render(
@@ -593,7 +601,7 @@ test('nested trees work independently', () => {
 ### Enhanced Accessibility Example
 
 ```typescript
-import { TreeDropDown } from '@torch-ui/components'
+import { TreeDropDown } from "@/components/TreeDropDown";
 import { useState } from 'react'
 
 function AccessibleTree() {
@@ -658,7 +666,7 @@ function AccessibleTree() {
 
 ```diff
 - import { Accordion } from 'other-library'
-+ import { TreeDropDown } from '@torch-ui/components'
++ import { TreeDropDown } from "@/components/TreeDropDown";
 
 - <Accordion title="Section">
 + <TreeDropDown treeLabel="Section">

package/docs/components/tree-sub-layout.md

@@ -12,11 +12,15 @@ A specialized layout component for Next.js applications that provides hierarchic
 
 ## Installation
 
+TORCH Glare is a copy-in library: the CLI copies this component's source into your project
+(you do **not** install it from the npm package). Run `init` once, then `add`:
+
 ```bash
-npx torch-cli add tree-sub-layout
+npx torch-glare@latest init
+npx torch-glare@latest add TreeSubLayout
 ```
 
-**Note**: This component requires Next.js 13+ with App Router.
+`add` also copies any components, hooks, and utilities that `TreeSubLayout` depends on.
 
 ## Imports
 

package/docs/components/tree-view.md

@@ -11,13 +11,22 @@ keywords: [data-views, tree-view, tree, hierarchy, nested, sidebar, parent-child
 
 ## Installation
 
-Part of `torch-glare`. Ships with the `DataViews` folder when you run `npx torch-glare add DataViews` — no separate install. It reuses the sibling `TableView`, the `Card` component, a colocated tree sidebar/drawer, and `lucide-react`.
+TORCH Glare is a copy-in library: the CLI copies this component's source into your project
+(you do **not** install it from the npm package). Run `init` once, then `add`:
+
+```bash
+npx torch-glare@latest init
+npx torch-glare@latest add TreeView
+```
+
+`add` also copies any components, hooks, and utilities that `TreeView` depends on.
 
 ## Import
 
+Import from your project's local path — the alias configured in `glare.json` (e.g. `@/*`):
+
 ```tsx
-import { TreeView, useDataViewsState } from "torch-glare"
-import type { TreeViewProps, TreeConfig, FieldConfig } from "torch-glare"
+import { TreeView } from "@/components/TreeView";
 ```
 
 ## When to use it directly
@@ -54,8 +63,10 @@ const rows = [
 ## Composable Mode example
 
 ```tsx
-import { TreeView, useDataViewsState } from "torch-glare"
-import type { FieldConfig, TreeConfig } from "torch-glare"
+import { TreeView } from "@/components/TreeView";
+import { useDataViewsState } from "@/hooks/useDataViewsState";
+import type { FieldConfig } from "@/components/FieldConfig";
+import type { TreeConfig } from "@/components/TreeConfig";
 
 const fields: FieldConfig[] = [
   { path: "name", type: "text" },

package/docs/explanation/architecture.md

@@ -0,0 +1,54 @@
+---
+title: Architecture
+description: How TORCH Glare is structured — the copy-in distribution model, the CLI, and the registry.
+group: explanation
+keywords: [architecture, copy-in, cli, registry, shadcn]
+---
+
+# Architecture
+
+## Copy-in distribution
+
+TORCH Glare does **not** ship compiled components you import from a package. Instead, the
+published `torch-glare` package contains a CLI plus the raw component source, and
+`npx torch-glare add <Component>` copies that source into your project. This is the same
+model popularized by shadcn/ui.
+
+Consequences:
+
+- **You own the code.** Copied components live in your repo and can be edited freely.
+- **No runtime package dependency.** You import from your own path (`@/components/…`), not
+  from `torch-glare`.
+- **Explicit dependencies.** `add` also copies the component's internal dependencies
+  (nested components, hooks, utils) and installs required npm packages such as `@radix-ui/*`.
+
+## The registry
+
+The dependency graph is described by a generated manifest, `apps/lib/registry.json`. Each
+entry lists a component's npm dependencies and its internal (component/hook/util)
+dependencies. The CLI reads this manifest to resolve the full closure to copy when you run
+`add`, so results are deterministic and testable rather than inferred at install time.
+
+The registry is generated from source (`pnpm run registry`) and validated in CI, so it never
+drifts from the actual imports.
+
+## Layers
+
+| Layer | Location | Role |
+| --- | --- | --- |
+| Components | `components/` | UI built with Radix primitives + CVA variants. |
+| Hooks | `hooks/` | Reusable behavior (e.g. `useClickOutside`). |
+| Utils | `utils/` | Helpers like `cn` (class merging) and types. |
+| Providers | `providers/` | Context providers such as `ThemeProvider`. |
+| Layouts | `layouts/` | Composed page/section scaffolds. |
+
+## AI-facing docs
+
+`llms.txt`, `llms-full.txt`, and `llms-manifest.json` are generated from source
+(`pnpm run llms`) so assistants always get accurate component lists, dependencies, variants,
+and examples. A doc lint (`pnpm run check:ai-docs`) blocks incorrect usage patterns.
+
+## See also
+
+- [Design system](./design-system.md)
+- [CLI reference](../reference/cli.md)

package/docs/explanation/design-system.md

@@ -0,0 +1,52 @@
+---
+title: Design System
+description: The conventions behind TORCH Glare — CVA variants, semantic tokens, sizing, and theming.
+group: explanation
+keywords: [design system, cva, variants, tokens, tailwind, sizing]
+---
+
+# Design System
+
+TORCH Glare components share a small set of conventions so they compose predictably and
+theme uniformly.
+
+## Variants via CVA
+
+Component styling is defined with [class-variance-authority](https://cva.style) (`cva`). Each
+component exposes a `variant` and/or `size` prop whose allowed values come directly from its
+`cva` definition. For example, `Button` has variants
+`PrimeStyle, BluSecStyle, YelSecStyle, RedSecStyle, BorderStyle, PrimeContStyle, BluContStyle, RedContStyle`
+and sizes `S, M, L, XL`.
+
+Because variant names are the source of truth, docs and the `llms.*` files generate their
+variant lists from these definitions — they can't drift.
+
+## Semantic tokens
+
+Colors are addressed through semantic CSS variables, not raw hex, so a single component works
+across themes. Names follow a `--{category}-{context}-{component}-{state}` shape, e.g.
+`background-presentation-action-primary` or `content-presentation-state-negative`. Components
+reference these via Tailwind classes like `bg-background-presentation-action-secondary`.
+
+## Sizing scale
+
+Interactive components use a consistent `S / M / L / XL` scale (some also `XS`). Typography
+components such as `TransparentLabel` instead take a typography-scale `size`
+(e.g. `body-medium-regular`, `headers-large-bold`).
+
+## Theming
+
+Theme is driven by `data-theme` (`light | dark | default`) and `data-theme-mode`
+(`CSS | TORCH`). Every component accepts a `theme` prop for local overrides; app-wide theming
+uses `ThemeProvider`. See the [theme reference](../reference/theme.md).
+
+## Accessibility
+
+Interactive components build on Radix UI primitives for keyboard and ARIA behavior. Custom
+controls add the appropriate attributes directly (for example, a loading `Button` sets
+`aria-busy` and exposes its spinner with `role="status"`).
+
+## See also
+
+- [Architecture](./architecture.md)
+- [Theme reference](../reference/theme.md)

package/docs/how-to/data-views-from-backend-response.md

@@ -14,7 +14,7 @@ back from an API to the props that turn them into a working view.
 ## TL;DR
 
 ```tsx
-import { DataViewsLayout } from "torch-glare"
+import { DataViewsLayout } from "@/components/DataViewsLayout";
 
 // the simplest possible case — just pass the array
 <DataViewsLayout title="Records" data={await api.get("/records")} />
@@ -37,7 +37,7 @@ Add a declarative `fields` map when you want typed rendering (currencies,
 badges, dates) and filters:
 
 ```tsx
-import type { FieldConfig } from "torch-glare"
+import type { FieldConfig } from "@/components/FieldConfig";
 
 const fields: FieldConfig[] = [
   { path: "name", label: "Name", type: "text" },
@@ -134,7 +134,7 @@ changes. This keeps the URL/server as the source of truth.
 
 ```tsx
 import { useState, useEffect } from "react"
-import type { FilterState } from "torch-glare"
+import type { FilterState } from "@/components/FilterState";
 
 function ServerDriven() {
   const [rows, setRows] = useState([])
@@ -161,7 +161,9 @@ When tabs aren't what you want — e.g. a table beside a kanban — bypass
 `DataViewsLayout` and compose the views with `useDataViewsState`.
 
 ```tsx
-import { TableView, KanbanView, useDataViewsState } from "torch-glare"
+import { KanbanView } from "@/components/KanbanView";
+import { TableView } from "@/components/TableView";
+import { useDataViewsState } from "@/hooks/useDataViewsState";
 
 function SplitScreen({ data, fields }) {
   const state = useDataViewsState({ data, fields })
@@ -183,6 +185,7 @@ See each view's reference: [TableView](../components/table-view.md) ·
 
 - **Empty `data`** → all views render their empty state; pass `isLoading` upstream if you fetch async.
 - **Tree tab missing?** No hierarchy was detected. Supply `treeConfig` explicitly or check your `childrenField` / `parentField`.
+- **Unwanted filters?** The panel auto-detects filterable text fields with few unique values (e.g. `id`, `name`). Set `filterable: false` on a field to exclude it. For a field with many options, set `filterVariant: "searchable-select"` to render a searchable dropdown instead of a long checkbox list.
 - **Saved Views don't persist** in tab mode — that's a known limitation documented in [`DataViewsConfigPanel`](../components/data-views-config-panel.md). Use composable mode for real persistence.
 
 ## Related