torch-glare 2.4.0 → 2.4.2

package/docs/migration/changelog.md

@@ -0,0 +1,38 @@
+---
+title: Changelog & Upgrading
+description: How to upgrade copied TORCH Glare components and where to find release notes.
+group: migration
+keywords: [changelog, migration, upgrade, update]
+---
+
+# Changelog & Upgrading
+
+## Upgrading in a copy-in library
+
+Because components are **copied into your project**, upgrading is not an `npm update`. To pull
+the latest component source, re-run the CLI:
+
+```bash
+# Re-sync everything already installed with the latest templates
+npx torch-glare@latest update
+```
+
+`update` overwrites your local copies, so review the diff and re-apply any local changes you
+made. To upgrade a single component, re-add it:
+
+```bash
+npx torch-glare@latest add Button
+```
+
+## Release notes
+
+- **v1.1.16** — see [CHANGELOG-1.1.16.md](../CHANGELOG-1.1.16.md) (adds `TextEditor`,
+  `ChartBlockTool`, and related components).
+
+For the authoritative version, check the `version` field in the package's `package.json` or
+run `npx torch-glare --version`.
+
+## See also
+
+- [CLI reference](../reference/cli.md)
+- [Architecture](../explanation/architecture.md)

package/docs/reference/cli.md

@@ -0,0 +1,87 @@
+---
+title: CLI Reference
+description: The torch-glare CLI — copy components, hooks, utils, layouts, and providers into your project.
+group: reference
+keywords: [cli, torch-glare, init, add, copy-in, glare.json]
+---
+
+# CLI Reference
+
+TORCH Glare is a **copy-in** component library: the `torch-glare` CLI copies source files
+directly into your project (like shadcn/ui). You own the copied code and import it from your
+own local path — you never import components from the npm package.
+
+Run any command with `npx` (no global install required):
+
+```bash
+npx torch-glare@latest <command> [name]
+```
+
+Run a command **without** a name to pick from an interactive list.
+
+## Commands
+
+| Command | Description |
+| --- | --- |
+| `init` | Create `glare.json` and set up Tailwind. Run once per project. |
+| `add [Component]` | Copy a component **and its dependencies** into your project. |
+| `hook [hook]` | Copy a hook (usually pulled in automatically as a dependency). |
+| `util [util]` | Copy a utility (e.g. `cn`, usually pulled in automatically). |
+| `layout [layout]` | Copy a layout. |
+| `provider [provider]` | Copy a provider (e.g. `ThemeProvider`). |
+| `update` | Re-sync everything already installed with the latest templates. |
+
+Component names are **case-sensitive PascalCase** — `add DatePicker`, not `add datepicker`.
+
+## `init`
+
+```bash
+npx torch-glare@latest init
+```
+
+Creates `glare.json` and configures Tailwind. `glare.json` controls where files are copied:
+
+```json
+{
+  "path": "@/"
+}
+```
+
+Files are copied into `<path>/components`, `<path>/hooks`, `<path>/utils`,
+`<path>/layouts`, and `<path>/providers`. Import them from that path.
+
+## `add`
+
+```bash
+npx torch-glare@latest add Button
+```
+
+Copies `Button` **plus its full dependency closure** — nested components, hooks, and utils —
+and installs any required npm packages (e.g. `@radix-ui/*`) using your project's package
+manager. After adding, import from your local alias:
+
+```tsx
+import { Button } from "@/components/Button";
+
+export function Example() {
+  return <Button variant="PrimeStyle">Click me</Button>;
+}
+```
+
+Existing files are never overwritten; use `update` to re-sync.
+
+## `update`
+
+```bash
+npx torch-glare@latest update
+```
+
+Re-copies every installed component, hook, util, layout, and provider from the latest
+templates. Review the diff afterward, since it overwrites your local copies.
+
+## See also
+
+- [Theme reference](./theme.md)
+- [Components reference](./components.md)
+- [Hooks reference](./hooks.md)
+- [Providers reference](./providers.md)

package/docs/reference/components.md

@@ -30,7 +30,7 @@ Interactive button component with multiple variants and sizes.
 
 - **File**: [button.md](../components/button.md)
 - **Props**: `variant`, `size`, `theme`, `buttonType`, `disabled`
-- **Variants**: `PrimeStyle`, `ContStyle`, `SecondStyle`, `BorderStyle`, `ErrorStyle`, `SuccessStyle`, `PrimeContStyle`
+- **Variants**: `PrimeStyle`, `BluSecStyle`, `YelSecStyle`, `RedSecStyle`, `BorderStyle`, `PrimeContStyle`, `BluContStyle`, `RedContStyle`
 - **Use Cases**: Primary actions, secondary actions, icon buttons, loading states
 
 ### Input
@@ -521,12 +521,13 @@ Components with size variants typically support:
 
 Button variants:
 - `PrimeStyle` - Primary action
-- `ContStyle` - Contrast style
-- `SecondStyle` - Secondary action
+- `BluSecStyle` - Blue secondary action
+- `YelSecStyle` - Yellow secondary action
+- `RedSecStyle` - Red secondary action
 - `BorderStyle` - Outlined
-- `ErrorStyle` - Destructive action
-- `SuccessStyle` - Success action
-- `PrimeContStyle` - Primary contrast
+- `PrimeContStyle` - Primary container (transparent)
+- `BluContStyle` - Blue container (transparent)
+- `RedContStyle` - Red container (transparent)
 
 ---
 
@@ -535,12 +536,10 @@ Button variants:
 All components are fully typed with TypeScript. Import types from the library:
 
 ```typescript
-import type {
-  ButtonProps,
-  InputProps,
-  SelectProps,
-  // ... other types
-} from '@torch-ai/torch-glare';
+import type { ButtonProps } from "@/components/Button";
+import type { InputProps } from "@/components/InputProps";
+import type { ButtonProps } from "@/components/LoginButton";
+import type { SelectProps } from "@/components/SelectProps";
 ```
 
 ---

package/docs/reference/hooks.md

@@ -30,7 +30,7 @@ Tracks which tree item is most visible in the viewport using the IntersectionObs
 ### Basic Usage
 
 ```tsx
-import { useActiveTreeItem } from '@torch-ai/torch-glare';
+import { useActiveTreeItem } from "@/hooks/useActiveTreeItem";
 
 function TableOfContents() {
   const sectionIds = ['intro', 'features', 'api', 'examples'];
@@ -210,7 +210,7 @@ Detects clicks outside a referenced element and executes a callback. Perfect for
 ### Basic Usage
 
 ```tsx
-import { useClickOutside } from '@torch-ai/torch-glare';
+import { useClickOutside } from "@/hooks/useClickOutside";
 import { useState } from 'react';
 
 function Dropdown() {
@@ -383,7 +383,7 @@ Handles element resizing with support for both mouse and touch events, including
 ### Basic Usage
 
 ```tsx
-import { useResize } from '@torch-ai/torch-glare';
+import { useResize } from "@/hooks/useResize";
 import { useRef } from 'react';
 
 function ResizablePanel() {
@@ -630,7 +630,7 @@ Manages tag selection state with comprehensive keyboard navigation support. Supp
 ### Basic Multi-Select
 
 ```tsx
-import { useTagSelection } from '@torch-ai/torch-glare';
+import { useTagSelection } from "@/hooks/useTagSelection";
 import { useRef } from 'react';
 
 function TagSelector() {
@@ -1177,7 +1177,7 @@ const result = useTagSelection({
 
 ```tsx
 import { renderHook } from '@testing-library/react';
-import { useActiveTreeItem } from '@torch-ai/torch-glare';
+import { useActiveTreeItem } from "@/hooks/useActiveTreeItem";
 
 describe('useActiveTreeItem', () => {
   it('should track active item', () => {
@@ -1208,7 +1208,7 @@ describe('useActiveTreeItem', () => {
 
 ```tsx
 import { render, fireEvent } from '@testing-library/react';
-import { useClickOutside } from '@torch-ai/torch-glare';
+import { useClickOutside } from "@/hooks/useClickOutside";
 
 describe('useClickOutside', () => {
   it('should call callback on outside click', () => {
@@ -1245,7 +1245,7 @@ describe('useClickOutside', () => {
 
 ```tsx
 import { renderHook, act } from '@testing-library/react';
-import { useResize } from '@torch-ai/torch-glare';
+import { useResize } from "@/hooks/useResize";
 
 describe('useResize', () => {
   it('should handle resize', () => {
@@ -1279,7 +1279,7 @@ describe('useResize', () => {
 
 ```tsx
 import { renderHook, act } from '@testing-library/react';
-import { useTagSelection } from '@torch-ai/torch-glare';
+import { useTagSelection } from "@/hooks/useTagSelection";
 
 describe('useTagSelection', () => {
   const mockTags = [

package/docs/reference/providers.md

@@ -34,7 +34,7 @@ Manages application theme state with support for light, dark, and system default
 ### Basic Setup
 
 ```tsx
-import { ThemeProvider } from '@torch-ai/torch-glare';
+import { ThemeProvider } from "@/providers/ThemeProvider";
 
 function App() {
   return (
@@ -48,7 +48,7 @@ function App() {
 ### With Default Theme
 
 ```tsx
-import { ThemeProvider } from '@torch-ai/torch-glare';
+import { ThemeProvider } from "@/providers/ThemeProvider";
 
 function App() {
   return (
@@ -62,7 +62,7 @@ function App() {
 ### Consuming Theme with useTheme Hook
 
 ```tsx
-import { useTheme } from '@torch-ai/torch-glare';
+import { useTheme } from "@/providers/ThemeProvider";
 
 function ThemeToggle() {
   const { theme, updateTheme } = useTheme();
@@ -83,7 +83,7 @@ function ThemeToggle() {
 ### Theme Mode Switcher
 
 ```tsx
-import { useTheme } from '@torch-ai/torch-glare';
+import { useTheme } from "@/providers/ThemeProvider";
 
 function ThemeModeSwitcher() {
   const { themeMode, updateMode } = useTheme();
@@ -105,7 +105,7 @@ function ThemeModeSwitcher() {
 ### Complete Theme Control Panel
 
 ```tsx
-import { useTheme } from '@torch-ai/torch-glare';
+import { useTheme } from "@/providers/ThemeProvider";
 
 function ThemeControlPanel() {
   const { theme, themeMode, updateTheme, updateMode } = useTheme();
@@ -166,7 +166,7 @@ function ThemeControlPanel() {
 ### Theme-Aware Component
 
 ```tsx
-import { useTheme } from '@torch-ai/torch-glare';
+import { useTheme } from "@/providers/ThemeProvider";
 
 function ThemedCard({ children }: { children: React.ReactNode }) {
   const { theme } = useTheme();
@@ -188,7 +188,7 @@ function ThemedCard({ children }: { children: React.ReactNode }) {
 ### System Theme Detection
 
 ```tsx
-import { useTheme } from '@torch-ai/torch-glare';
+import { useTheme } from "@/providers/ThemeProvider";
 import { useEffect, useState } from 'react';
 
 function SystemThemeSync() {
@@ -229,7 +229,7 @@ function SystemThemeSync() {
 ### Header with Theme Toggle
 
 ```tsx
-import { useTheme } from '@torch-ai/torch-glare';
+import { useTheme } from "@/providers/ThemeProvider";
 
 function Header() {
   const { theme, updateTheme } = useTheme();
@@ -253,7 +253,7 @@ function Header() {
 ### Settings Page
 
 ```tsx
-import { useTheme } from '@torch-ai/torch-glare';
+import { useTheme } from "@/providers/ThemeProvider";
 import { useState } from 'react';
 
 function SettingsPage() {
@@ -310,7 +310,7 @@ function SettingsPage() {
 
 ```tsx
 // app/layout.tsx
-import { ThemeProvider } from '@torch-ai/torch-glare';
+import { ThemeProvider } from "@/providers/ThemeProvider";
 
 export default function RootLayout({
   children,
@@ -333,7 +333,7 @@ export default function RootLayout({
 
 ```tsx
 // pages/_app.tsx
-import { ThemeProvider } from '@torch-ai/torch-glare';
+import { ThemeProvider } from "@/providers/ThemeProvider";
 import type { AppProps } from 'next/app';
 
 export default function App({ Component, pageProps }: AppProps) {
@@ -351,7 +351,7 @@ export default function App({ Component, pageProps }: AppProps) {
 // main.tsx
 import React from 'react';
 import ReactDOM from 'react-dom/client';
-import { ThemeProvider } from '@torch-ai/torch-glare';
+import { ThemeProvider } from "@/providers/ThemeProvider";
 import App from './App';
 
 ReactDOM.createRoot(document.getElementById('root')!).render(
@@ -478,7 +478,7 @@ The ThemeProvider stores values in localStorage:
 Full TypeScript support with type inference:
 
 ```typescript
-import { useTheme } from '@torch-ai/torch-glare';
+import { useTheme } from "@/providers/ThemeProvider";
 
 function MyComponent() {
   const { theme, themeMode, updateTheme, updateMode } = useTheme();
@@ -506,7 +506,7 @@ function MyComponent() {
 
 ```tsx
 import { render } from '@testing-library/react';
-import { ThemeProvider } from '@torch-ai/torch-glare';
+import { ThemeProvider } from "@/providers/ThemeProvider";
 
 describe('ThemedComponent', () => {
   it('should render with light theme', () => {
@@ -535,7 +535,7 @@ describe('ThemedComponent', () => {
 
 ```tsx
 import { renderHook, act } from '@testing-library/react';
-import { ThemeProvider, useTheme } from '@torch-ai/torch-glare';
+import { ThemeProvider, useTheme } from "@/providers/ThemeProvider";
 
 describe('useTheme', () => {
   it('should update theme', () => {
@@ -630,7 +630,7 @@ The ThemeProvider uses React context, which can cause re-renders. To optimize:
 
 ```tsx
 import { memo } from 'react';
-import { useTheme } from '@torch-ai/torch-glare';
+import { useTheme } from "@/providers/ThemeProvider";
 
 // Memoize components that don't need theme updates
 const ExpensiveComponent = memo(() => {
@@ -647,7 +647,7 @@ function ThemedButton() {
 ### Selective Theme Consumption
 
 ```tsx
-import { useTheme } from '@torch-ai/torch-glare';
+import { useTheme } from "@/providers/ThemeProvider";
 
 // Only consume what you need
 function ThemeToggle() {
@@ -727,7 +727,7 @@ Avoid hydration mismatches:
 
 ```tsx
 import { useEffect, useState } from 'react';
-import { useTheme } from '@torch-ai/torch-glare';
+import { useTheme } from "@/providers/ThemeProvider";
 
 function ClientOnlyThemeButton() {
   const [mounted, setMounted] = useState(false);
@@ -754,7 +754,7 @@ function ClientOnlyThemeButton() {
 Show visual feedback when theme changes:
 
 ```tsx
-import { useTheme } from '@torch-ai/torch-glare';
+import { useTheme } from "@/providers/ThemeProvider";
 import { useState, useEffect } from 'react';
 
 function ThemeToggleWithFeedback() {
@@ -783,7 +783,7 @@ function ThemeToggleWithFeedback() {
 Ensure theme values are valid before updating:
 
 ```tsx
-import { useTheme } from '@torch-ai/torch-glare';
+import { useTheme } from "@/providers/ThemeProvider";
 
 function SafeThemeUpdater({ theme }: { theme: string }) {
   const { updateTheme } = useTheme();
@@ -849,7 +849,7 @@ import { Theme } from 'old-library';
 <Theme mode="dark">
 
 // v2.x (new)
-import { ThemeProvider } from '@torch-ai/torch-glare';
+import { ThemeProvider } from "@/providers/ThemeProvider";
 <ThemeProvider defaultTheme="dark">
 ```
 
@@ -860,7 +860,7 @@ import { ThemeProvider } from '@torch-ai/torch-glare';
 import { ThemeProvider as NextThemeProvider } from 'next-themes';
 
 // TORCH Glare
-import { ThemeProvider } from '@torch-ai/torch-glare';
+import { ThemeProvider } from "@/providers/ThemeProvider";
 
 // Both can coexist if needed, but use TORCH Glare for consistency
 ```

package/docs/reference/tailwind-plugins.md

@@ -352,7 +352,7 @@ The TORCH mode plugin defines the actual color values for:
 ### Integration with ThemeProvider
 
 ```tsx
-import { ThemeProvider } from '@torch-ai/torch-glare';
+import { ThemeProvider } from "@/providers/ThemeProvider";
 
 function App() {
   return (
@@ -622,7 +622,7 @@ export default {
 
 ```tsx
 // app/layout.tsx (Next.js App Router)
-import { ThemeProvider } from '@torch-ai/torch-glare';
+import { ThemeProvider } from "@/providers/ThemeProvider";
 import './globals.css';
 
 export default function RootLayout({

package/docs/reference/theme.md

@@ -0,0 +1,85 @@
+---
+title: Theme Reference
+description: TORCH Glare theming — data-theme, theme modes, ThemeProvider, and useTheme.
+group: reference
+keywords: [theme, dark mode, data-theme, ThemeProvider, useTheme, tokens]
+---
+
+# Theme Reference
+
+TORCH Glare is themed through two `data-*` attributes on the document root and a small
+React context. Every component also accepts a `theme` prop that sets `data-theme` locally.
+
+## Attributes
+
+| Attribute | Values | Meaning |
+| --- | --- | --- |
+| `data-theme` | `"light" \| "dark" \| "default"` | The active color theme. |
+| `data-theme-mode` | `"CSS" \| "TORCH"` | Token resolution mode (`TORCH` is the default). |
+
+Per-component override:
+
+```tsx
+import { Button } from "@/components/Button";
+
+<Button theme="dark" variant="PrimeStyle">Dark button</Button>;
+```
+
+## ThemeProvider
+
+Add the provider once (`npx torch-glare@latest provider ThemeProvider`) and wrap your app.
+It syncs `data-theme` / `data-theme-mode` to `document.documentElement` and persists the
+choice to `localStorage`.
+
+```tsx
+import { ThemeProvider } from "@/providers/ThemeProvider";
+
+export function App({ children }: { children: React.ReactNode }) {
+  return (
+    <ThemeProvider defaultTheme="default" defaultThemeMode="TORCH">
+      {children}
+    </ThemeProvider>
+  );
+}
+```
+
+### Props
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `defaultTheme` | `"light" \| "dark" \| "default"` | `"default"` | Initial theme (unless a stored/`data-theme` value exists). |
+| `defaultThemeMode` | `"CSS" \| "TORCH"` | `"TORCH"` | Initial token mode. |
+
+## useTheme
+
+Read and update the theme from anywhere inside `ThemeProvider`:
+
+```tsx
+import { useTheme } from "@/providers/ThemeProvider";
+
+export function ThemeToggle() {
+  const { theme, updateTheme, themeMode, updateMode } = useTheme();
+
+  return (
+    <button onClick={() => updateTheme(theme === "dark" ? "light" : "dark")}>
+      {theme} / {themeMode}
+    </button>
+  );
+}
+```
+
+### Returned value
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `theme` | `"light" \| "dark" \| "default"` | Current theme. |
+| `themeMode` | `"CSS" \| "TORCH"` | Current token mode. |
+| `updateTheme` | `(theme) => void` | Set the theme (updates DOM + `localStorage`). |
+| `updateMode` | `(mode) => void` | Set the token mode. |
+
+`useTheme` throws if used outside `ThemeProvider`.
+
+## See also
+
+- [Providers reference](./providers.md)
+- [CLI reference](./cli.md)

package/docs/reference/types.md

@@ -37,7 +37,7 @@ export type Themes = "dark" | "light" | "default";
 
 **Usage:**
 ```typescript
-import type { Themes } from '@torch-ai/torch-glare';
+import type { Themes } from "@/utils/types";
 
 interface MyComponentProps {
   theme?: Themes;
@@ -60,12 +60,12 @@ interface MyComponentProps {
 ```typescript
 export type ButtonVariant =
   | "PrimeStyle"      // Primary action
-  | "BlueSecStyle"    // Blue secondary
+  | "BluSecStyle"    // Blue secondary
   | "YelSecStyle"     // Yellow secondary
   | "RedSecStyle"     // Red secondary
   | "BorderStyle"     // Outlined
   | "PrimeContStyle"  // Primary contrast
-  | "BlueContStyle"   // Blue contrast
+  | "BluContStyle"   // Blue contrast
   | "RedContStyle";   // Red contrast
 ```
 
@@ -878,7 +878,7 @@ Button.displayName = 'Button';
 ### Extending Button Props
 
 ```typescript
-import type { ButtonProps } from '@torch-ai/torch-glare';
+import type { ButtonProps } from "@/components/LoginButton";
 
 interface CustomButtonProps extends ButtonProps {
   isLoading?: boolean;