torch-glare 2.4.1 → 2.4.2

package/apps/lib/utils/color.ts

@@ -0,0 +1,175 @@
+/**
+ * Pure color-math helpers for the `ColorPicker` component (and anything else that
+ * needs to move between hex, RGB, HSV and HSL). No dependencies, no DOM — safe to
+ * unit-test and to import on the server.
+ *
+ * Conventions:
+ *  - `RGBA` channels are 0–255 (`r`,`g`,`b`) and 0–1 (`a`).
+ *  - `HSV`/`HSL` use `h` 0–360, everything else 0–100.
+ *  - Hex output is uppercase, `#rrggbb` when fully opaque and `#rrggbbaa` otherwise.
+ */
+
+export interface RGBA {
+  r: number;
+  g: number;
+  b: number;
+  a: number;
+}
+
+export interface HSV {
+  h: number;
+  s: number;
+  v: number;
+}
+
+export interface HSL {
+  h: number;
+  s: number;
+  l: number;
+}
+
+/** Clamp `n` into the inclusive `[min, max]` range. */
+export function clamp(n: number, min: number, max: number): number {
+  return n < min ? min : n > max ? max : n;
+}
+
+/** Round to `digits` decimal places (default 0). */
+export function round(n: number, digits = 0): number {
+  const f = 10 ** digits;
+  return Math.round(n * f) / f;
+}
+
+const toHex2 = (n: number) => clamp(Math.round(n), 0, 255).toString(16).padStart(2, "0");
+
+/**
+ * Parse a hex color into `RGBA`. Accepts `#rgb`, `#rgba`, `#rrggbb`, `#rrggbbaa`
+ * with or without the leading `#`. Returns `null` for anything unparseable.
+ */
+export function parseHex(input: string): RGBA | null {
+  if (typeof input !== "string") return null;
+  let hex = input.trim().replace(/^#/, "");
+
+  // Expand shorthand (#rgb / #rgba → #rrggbb(aa)).
+  if (hex.length === 3 || hex.length === 4) {
+    hex = hex
+      .split("")
+      .map((c) => c + c)
+      .join("");
+  }
+
+  if (hex.length !== 6 && hex.length !== 8) return null;
+  if (!/^[0-9a-fA-F]+$/.test(hex)) return null;
+
+  const r = parseInt(hex.slice(0, 2), 16);
+  const g = parseInt(hex.slice(2, 4), 16);
+  const b = parseInt(hex.slice(4, 6), 16);
+  const a = hex.length === 8 ? parseInt(hex.slice(6, 8), 16) / 255 : 1;
+  return { r, g, b, a: round(a, 2) };
+}
+
+/** Format `RGBA` as an uppercase hex string — `#rrggbb` if opaque, else `#rrggbbaa`. */
+export function formatHex({ r, g, b, a }: RGBA): string {
+  const base = `#${toHex2(r)}${toHex2(g)}${toHex2(b)}`.toUpperCase();
+  if (a >= 1) return base;
+  return `${base}${toHex2(clamp(a, 0, 1) * 255).toUpperCase()}`;
+}
+
+/** RGB (0–255) → HSV (h 0–360, s/v 0–100). Alpha is carried through unchanged elsewhere. */
+export function rgbToHsv({ r, g, b }: { r: number; g: number; b: number }): HSV {
+  const rn = r / 255;
+  const gn = g / 255;
+  const bn = b / 255;
+  const max = Math.max(rn, gn, bn);
+  const min = Math.min(rn, gn, bn);
+  const d = max - min;
+
+  let h = 0;
+  if (d !== 0) {
+    if (max === rn) h = ((gn - bn) / d) % 6;
+    else if (max === gn) h = (bn - rn) / d + 2;
+    else h = (rn - gn) / d + 4;
+    h *= 60;
+    if (h < 0) h += 360;
+  }
+  const s = max === 0 ? 0 : d / max;
+  // Keep 2 decimals: HSV is the picker's internal state, so rounding to whole degrees/percents
+  // here would visibly shift a color that was only ever passed in (e.g. #10B981 → #11BA82).
+  return { h: round(h, 2), s: round(s * 100, 2), v: round(max * 100, 2) };
+}
+
+/** HSV (h 0–360, s/v 0–100) → RGB (0–255). */
+export function hsvToRgb({ h, s, v }: HSV): { r: number; g: number; b: number } {
+  const hn = ((h % 360) + 360) % 360;
+  const sn = clamp(s, 0, 100) / 100;
+  const vn = clamp(v, 0, 100) / 100;
+
+  const c = vn * sn;
+  const x = c * (1 - Math.abs(((hn / 60) % 2) - 1));
+  const m = vn - c;
+
+  let rp = 0;
+  let gp = 0;
+  let bp = 0;
+  if (hn < 60) [rp, gp, bp] = [c, x, 0];
+  else if (hn < 120) [rp, gp, bp] = [x, c, 0];
+  else if (hn < 180) [rp, gp, bp] = [0, c, x];
+  else if (hn < 240) [rp, gp, bp] = [0, x, c];
+  else if (hn < 300) [rp, gp, bp] = [x, 0, c];
+  else [rp, gp, bp] = [c, 0, x];
+
+  return {
+    r: round((rp + m) * 255),
+    g: round((gp + m) * 255),
+    b: round((bp + m) * 255),
+  };
+}
+
+/** RGB (0–255) → HSL (h 0–360, s/l 0–100). */
+export function rgbToHsl({ r, g, b }: { r: number; g: number; b: number }): HSL {
+  const rn = r / 255;
+  const gn = g / 255;
+  const bn = b / 255;
+  const max = Math.max(rn, gn, bn);
+  const min = Math.min(rn, gn, bn);
+  const d = max - min;
+  const l = (max + min) / 2;
+
+  let h = 0;
+  let s = 0;
+  if (d !== 0) {
+    s = d / (1 - Math.abs(2 * l - 1));
+    if (max === rn) h = ((gn - bn) / d) % 6;
+    else if (max === gn) h = (bn - rn) / d + 2;
+    else h = (rn - gn) / d + 4;
+    h *= 60;
+    if (h < 0) h += 360;
+  }
+  return { h: round(h), s: round(s * 100), l: round(l * 100) };
+}
+
+/** HSL (h 0–360, s/l 0–100) → RGB (0–255). */
+export function hslToRgb({ h, s, l }: HSL): { r: number; g: number; b: number } {
+  const hn = ((h % 360) + 360) % 360;
+  const sn = clamp(s, 0, 100) / 100;
+  const ln = clamp(l, 0, 100) / 100;
+
+  const c = (1 - Math.abs(2 * ln - 1)) * sn;
+  const x = c * (1 - Math.abs(((hn / 60) % 2) - 1));
+  const m = ln - c / 2;
+
+  let rp = 0;
+  let gp = 0;
+  let bp = 0;
+  if (hn < 60) [rp, gp, bp] = [c, x, 0];
+  else if (hn < 120) [rp, gp, bp] = [x, c, 0];
+  else if (hn < 180) [rp, gp, bp] = [0, c, x];
+  else if (hn < 240) [rp, gp, bp] = [0, x, c];
+  else if (hn < 300) [rp, gp, bp] = [x, 0, c];
+  else [rp, gp, bp] = [c, 0, x];
+
+  return {
+    r: round((rp + m) * 255),
+    g: round((gp + m) * 255),
+    b: round((bp + m) * 255),
+  };
+}

package/docs/components/card.md

@@ -12,7 +12,7 @@ dependencies:
 
 # Card
 
-> A flexible container component for grouping and displaying content. Supports compound architecture with header, description, and content sections. Features hover states and polymorphic rendering.
+> A flexible container component for grouping and displaying content. Supports compound architecture with header, description, and content sections, and polymorphic rendering. Static by default — opt into hover states with `variant="clickable"`.
 
 ## Installation
 
@@ -74,10 +74,11 @@ function Example() {
 ### Clickable Card
 
 ```typescript
+// `variant="clickable"` gives the hover highlight + pointer cursor.
 <Card
   as="button"
+  variant="clickable"
   onClick={() => console.log('Card clicked')}
-  className="cursor-pointer"
 >
   <CardHeader>Interactive Card</CardHeader>
   <CardDescription>Click me to perform an action</CardDescription>
@@ -205,6 +206,7 @@ function ImageCard() {
 
 | Prop | Type | Default | Description |
 |------|------|---------|-------------|
+| `variant` | `'default' \| 'clickable'` | `'default'` | `'default'` is a static container with **no hover effect**. `'clickable'` adds the hover border highlight + pointer cursor — use it when the whole card is an interactive target. |
 | `as` | `React.ElementType` | `'section'` | Element type to render as |
 | `asChild` | `boolean` | `false` | Merge props onto child element |
 | `htmlFor` | `string` | - | For label association when as="label" |

package/docs/components/chart-block-tool.md

@@ -20,15 +20,16 @@ TORCH Glare is a copy-in library: the CLI copies this module's source into your
 
 ```bash
 npx torch-glare@latest init
-npx torch-glare@latest add ChartBlockTool
+npx torch-glare@latest add TextEditor
 ```
 
+`ChartBlockTool` ships as part of the `TextEditor` folder, so `add TextEditor` copies it in.
 It depends on the `chart.js` npm package (installed automatically by the CLI).
 
 ## Import
 
 ```typescript
-import ChartBlockTool, { ChartBlockData } from "@/components/ChartBlockTool";
+import { ChartBlockTool, type ChartBlockData } from "@/components/TextEditor";
 ```
 
 ## Quick Examples
@@ -37,7 +38,7 @@ import ChartBlockTool, { ChartBlockData } from "@/components/ChartBlockTool";
 
 ```typescript
 import EditorJS from "@editorjs/editorjs";
-import ChartBlockTool from "@/components/ChartBlockTool";
+import { ChartBlockTool } from "@/components/TextEditor";
 
 const editor = new EditorJS({
   holder: "editor",
@@ -56,7 +57,7 @@ editors. The block persists as `ChartBlockData` in the editor's saved output.
 ### The saved data shape
 
 ```typescript
-import { ChartBlockData } from "@/components/ChartBlockTool";
+import type { ChartBlockData } from "@/components/TextEditor";
 
 const block: ChartBlockData = {
   chartType: "bar",

package/docs/components/color-picker.md

@@ -0,0 +1,101 @@
+---
+title: ColorPicker
+description: A full Figma-style color picker with a saturation/value area, hue and opacity sliders, an eyedropper, switchable HEX/RGB/HSL inputs, and preset swatches
+group: Forms
+keywords: [color-picker, color, palette, hex, rgb, hsl, hsv, opacity, alpha, eyedropper, swatch]
+---
+
+# ColorPicker
+
+> A full Figma-style color palette opened from **a trigger you supply**: a draggable
+> saturation/value area, a hue slider, an optional opacity slider, an eyedropper (where the
+> browser supports it), switchable **HEX / RGB / HSL** numeric inputs, and preset swatches.
+> The value is always a hex string.
+
+## Installation
+
+```bash
+npx torch-glare@latest init
+npx torch-glare@latest add ColorPicker
+```
+
+`add` also copies its dependencies — `utils/color` (the pure hex/RGB/HSV/HSL math), plus the
+`Popover` and `Input` components.
+
+## Import
+
+```tsx
+import { ColorPicker } from "@/components/ColorPicker";
+```
+
+## Usage
+
+ColorPicker renders **no trigger of its own** — you pass one as its child (rendered via `asChild`,
+so it must forward ref/props to a DOM node). The current color is handed to that child based on
+what it is:
+
+| Child | Receives |
+|---|---|
+| an **input** — native `<input>`/`<textarea>`, or any element already given a `value` prop | the hex as **`value`** (plus an `onChange` that commits a typed hex, if you didn't supply one) |
+| **anything else** | the hex as **`children`** — unless it already has children, which are left untouched |
+
+```tsx
+const [color, setColor] = useState("#3B82F6");
+
+// input child → gets `value={color}`
+<ColorPicker value={color} onChange={setColor}>
+  <input className="…" />
+</ColorPicker>
+
+// non-input child → gets the hex as its content
+<ColorPicker value={color} onChange={setColor}>
+  <Button variant="BorderStyle" />
+</ColorPicker>
+
+// a child with its own content keeps it — render the value yourself
+<ColorPicker value={color} onChange={setColor}>
+  <button type="button">
+    <span style={{ backgroundColor: color }} />
+    {color}
+  </button>
+</ColorPicker>
+```
+
+With presets and opacity disabled (always emits `#rrggbb`):
+
+```tsx
+<ColorPicker
+  value={color}
+  onChange={setColor}
+  alpha={false}
+  presets={["#005ECC", "#047854", "#E30C30", "#F5A623"]}
+>
+  <Button variant="BorderStyle" />
+</ColorPicker>
+```
+
+## Props
+
+| Prop        | Type                       | Default       | Description                                                                 |
+| ----------- | -------------------------- | ------------- | --------------------------------------------------------------------------- |
+| `children`  | `ReactElement`             | — (required)  | The trigger. Gets the hex as `value` if it's an input, else as `children`.   |
+| `value`     | `string`                   | `"#000000"`   | Current color as a hex string (`#rrggbb` or `#rrggbbaa`).                    |
+| `onChange`  | `(hex: string) => void`    | —             | Called on every change. Emits `#rrggbbaa` only when opacity < 100%.         |
+| `presets`   | `string[]`                 | —             | Quick-pick swatches shown at the bottom of the panel.                       |
+| `alpha`     | `boolean`                  | `true`        | Show the opacity slider + input and allow 8-digit output.                    |
+| `disabled`  | `boolean`                  | `false`       | Disable the trigger and all controls.                                       |
+| `theme`     | `"dark" \| "light" \| "default"` | —       | Applied as `data-theme`.                                                     |
+
+## Value format
+
+The value stays `#rrggbb` while fully opaque (backward-compatible with plain hex fields) and is
+promoted to `#rrggbbaa` only when opacity drops below 100%. Feeding a 3-, 6-, or 8-digit hex
+(with or without `#`) back in via `value` is always accepted.
+
+## Notes
+
+- The **eyedropper** button appears only where the native [`EyeDropper` API](https://developer.mozilla.org/docs/Web/API/EyeDropper)
+  is available (Chromium/Edge); it is hidden on Firefox/Safari.
+- Used by `FormBuilder.Color` — see [form-builder.md](./form-builder.md).
+- Color math lives in `utils/color` (`parseHex`, `formatHex`, `rgbToHsv`, `hsvToRgb`,
+  `rgbToHsl`, `hslToRgb`) and is reusable on its own.

package/docs/components/conclusion-header.md

@@ -0,0 +1,80 @@
+---
+title: ConclusionHeader
+description: A clickable section header with a chevron toggle — white-alpha hover surfaces, chevron down when open and sideways when closed, and a "Disabled" badge when disabled. Direction-aware (LTR/RTL). Used for each FormSummary group title.
+component: true
+group: Layout & Containers
+keywords: [conclusion-header, collapsible, header, disclosure, accordion, toggle, chevron, expand, collapse, section]
+---
+
+# ConclusionHeader
+
+A clickable **section header** that toggles a collapsible region, per the
+*Conclusion-Header-2.0* design. Its surfaces are **button overlays** (not an input field): at
+rest the label stands alone, and on hover it gains a `Button/ContStyle-Hover` pill while the
+chevron gains a `Button/Secondary` box. The chevron is hidden at rest while open, shows
+**sideways** when closed (left in LTR, right in RTL), and flips to **down** on hover. When
+`disabled` the label greys out, truncates at 120px, and a gray-subtle `Badge` replaces the
+chevron.
+
+It renders only the header — you own the collapsible body. It works **uncontrolled**
+(manages its own open state) or **controlled** (pass `open` + `onOpenChange`):
+
+```tsx
+// Uncontrolled — reflect the state with onOpenChange
+const [open, setOpen] = useState(true)
+
+<ConclusionHeader label="Invoice" defaultOpen onOpenChange={setOpen} />
+{open && <section>…body…</section>}
+
+// Controlled — you drive `open`
+<ConclusionHeader label="Invoice" open={open} onOpenChange={setOpen} />
+```
+
+## Installation
+
+```bash
+npx torch-glare@latest init
+npx torch-glare@latest add ConclusionHeader
+```
+
+## Imports
+
+```tsx
+import { ConclusionHeader } from '@/components/ConclusionHeader'
+```
+
+## Props
+
+| Prop | Type | Default | Notes |
+|---|---|---|---|
+| `label` | `ReactNode` | — | The header text. |
+| `open` | `boolean` | — | **Controlled** open state. Omit to let the header manage its own. |
+| `defaultOpen` | `boolean` | `true` | Initial open state when **uncontrolled**. |
+| `onOpenChange` | `(open: boolean) => void` | — | Called with the next open state on click. |
+| `disabled` | `boolean` | `false` | Greys the label and shows a `Badge` instead of the chevron. |
+| `disabledLabel` | `string` | `"Disabled"` | Badge text when `disabled`. |
+| `theme` | `'dark' \| 'light' \| 'default'` | — | Theme override; otherwise inherits the nearest `data-theme`. |
+
+Extra props spread to the underlying `<button>`, which is what the header renders — so it is
+focusable, toggles on <kbd>Enter</kbd>/<kbd>Space</kbd>, and exposes `aria-expanded` for
+free. A `ref` is forwarded to that `HTMLButtonElement`.
+
+## Behaviour
+
+- **Open** (rest): label only — no surface, no chevron.
+- **Open hover**: `Button/ContStyle-Hover` pill (label inset 4px) + `Button/Secondary`
+  chevron box with a **down** chevron.
+- **Closed** (rest): label + a bare **sideways** chevron (`<` LTR / `>` RTL), no box.
+- **Closed hover**: same surfaces as open hover; the chevron flips to down.
+- **Disabled**: greyed label truncated at 120px + a `● Disabled` badge sitting beside it
+  (not at the row's end); not clickable.
+
+Direction is inherited from the ambient `dir` — the design's RTL variants are the LTR ones
+mirrored, which the component's logical properties produce automatically.
+
+## Composition
+
+Uses the design-system tokens directly (`Button/Secondary`, `Button/ContStyle-Hover`) rather
+than the input/button components, and reuses [Badge](./badge.md) for the disabled state.
+[FormSummary](./form-summary.md) uses it as each **group** title, so every group of totals
+collapses independently.