torch-glare 1.3.0 → 1.5.0

package/docs/components/section-block.md

@@ -0,0 +1,275 @@
+---
+name: SectionBlock
+title: SectionBlock
+description: Sectioned card container with a colored title badge for grouping related content like forms, tables, or lists.
+category: layout
+group: Layout & Containers
+tags: [layout, card, section, container, form, group]
+status: stable
+version: 1.1.22
+dependencies:
+  - "class-variance-authority": "^0.7.0"
+---
+
+# SectionBlock
+
+> A card container with an optional colored title badge. Use it to group related content — custom field forms, tables, settings groups — under a clear, color-coded heading.
+
+## Installation
+
+```bash
+npx torch-glare add SectionBlock
+```
+
+## Import
+
+```typescript
+import { SectionBlock, type SectionColor } from "@/components/SectionBlock";
+```
+
+## Basic Usage
+
+```tsx
+import { SectionBlock } from "@/components/SectionBlock";
+
+export function Example() {
+  return (
+    <SectionBlock color="Blue" title="Project details">
+      <p className="text-content-presentation-action-light-primary py-4">
+        Card body content goes here.
+      </p>
+    </SectionBlock>
+  );
+}
+```
+
+## API Reference
+
+### Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `color` | `SectionColor` | `"Blue"` | Color of the title badge. One of `Blue`, `Yellow`, `Green`, `Red`, `Orange`, `Purple`, `Pink`, `Gray`. |
+| `title` | `ReactNode` | — | Title rendered inside the colored badge. Optional — when omitted, the header is hidden entirely. Accepts any ReactNode (string, JSX with icons, links, etc.). |
+| `containerClassName` | `string` | — | Class name applied to the outer container (alongside `className`). |
+| `headerClassName` | `string` | — | Class name applied to the header wrapper around the title badge. |
+| `bodyClassName` | `string` | — | Class name applied to the body wrapper holding `children`. |
+| `className` | `string` | — | Standard React class name on the outer container. |
+| `children` | `ReactNode` | — | Body content. |
+| `...rest` | `HTMLAttributes<HTMLDivElement>` | — | All standard div props except `title` (which is overridden). |
+
+### TypeScript
+
+```typescript
+export type SectionColor =
+  | "Blue"
+  | "Yellow"
+  | "Green"
+  | "Red"
+  | "Orange"
+  | "Purple"
+  | "Pink"
+  | "Gray";
+
+export interface SectionBlockProps
+  extends Omit<HTMLAttributes<HTMLDivElement>, "title"> {
+  color?: SectionColor;
+  title?: ReactNode;
+  containerClassName?: string;
+  headerClassName?: string;
+  bodyClassName?: string;
+}
+```
+
+The component is a `forwardRef<HTMLDivElement, SectionBlockProps>`.
+
+## Examples
+
+### All Colors
+
+```tsx
+import { SectionBlock, type SectionColor } from "@/components/SectionBlock";
+
+const COLORS: SectionColor[] = [
+  "Blue",
+  "Yellow",
+  "Green",
+  "Red",
+  "Orange",
+  "Purple",
+  "Pink",
+  "Gray",
+];
+
+export function AllColors() {
+  return (
+    <div className="flex flex-col gap-[24px]">
+      {COLORS.map((color) => (
+        <SectionBlock key={color} color={color} title={`${color} section`}>
+          <p className="text-content-presentation-action-light-primary py-4">
+            This is a {color.toLowerCase()} sectioned card.
+          </p>
+        </SectionBlock>
+      ))}
+    </div>
+  );
+}
+```
+
+### No Title
+
+When `title` is omitted, the header is hidden but the body padding remains.
+
+```tsx
+<SectionBlock>
+  <p className="text-content-presentation-action-light-primary py-4">
+    A SectionBlock without a title — header is hidden, body still padded.
+  </p>
+</SectionBlock>
+```
+
+### Rich Title with Icon
+
+`title` accepts any ReactNode, so you can pass JSX with icons, counts, links, etc.
+
+```tsx
+<SectionBlock
+  color="Purple"
+  title={
+    <span className="flex items-center gap-[6px]">
+      <i className="ri-magic-line" />
+      Rich title with icon
+    </span>
+  }
+>
+  <p className="text-content-presentation-action-light-primary py-4">
+    The title prop is fully customizable.
+  </p>
+</SectionBlock>
+```
+
+### Custom Fields Form
+
+A common pattern: pair `SectionBlock` with a row layout to build labeled-field forms.
+
+```tsx
+import { type ReactNode } from "react";
+import { SectionBlock } from "@/components/SectionBlock";
+import { InputField } from "@/components/InputField";
+import { ActionButton } from "@/components/ActionButton";
+
+export function CustomFieldsForm() {
+  return (
+    <SectionBlock
+      color="Blue"
+      title={
+        <span className="flex items-center gap-[6px]">
+          <i className="ri-edit-box-line" />
+          Custom fields
+        </span>
+      }
+    >
+      <FieldRow
+        label="Name"
+        required
+        right={
+          <div className="flex flex-1 items-center gap-[12px]">
+            <InputField placeholder="First Name*" className="flex-1" />
+            <InputField placeholder="Last Name*" className="flex-1" />
+          </div>
+        }
+      />
+
+      <RowDivider />
+
+      <FieldRow
+        label="Department"
+        right={<InputField placeholder="Write Hint Here" className="flex-1" />}
+      />
+
+      <RowDivider />
+
+      <FieldRow
+        label="Alias names"
+        right={
+          <InputField
+            placeholder="Write Hint Here"
+            className="flex-1"
+            childrenSide={
+              <ActionButton aria-label="Add alias name">
+                <i className="ri-add-line" />
+              </ActionButton>
+            }
+          />
+        }
+      />
+    </SectionBlock>
+  );
+}
+
+interface FieldRowProps {
+  label: string;
+  required?: boolean;
+  right: ReactNode;
+}
+
+function FieldRow({ label, required, right }: FieldRowProps) {
+  return (
+    <div className="flex items-center gap-[24px] py-[18px]">
+      <div className="flex w-[220px] shrink-0 items-center gap-[6px]">
+        <span className="typography-body-medium-regular text-content-presentation-action-light-primary">
+          {label}
+        </span>
+        {required && (
+          <span className="typography-body-small-medium text-content-presentation-state-negative">
+            (Required)
+          </span>
+        )}
+      </div>
+      <div className="flex flex-1 items-center">{right}</div>
+    </div>
+  );
+}
+
+function RowDivider() {
+  return <div className="h-px w-full bg-border-presentation-global-primary" />;
+}
+```
+
+### Custom Layout (override defaults)
+
+Use `containerClassName`, `headerClassName`, and `bodyClassName` to override the built-in spacing and width without losing the title/body structure.
+
+```tsx
+<SectionBlock
+  color="Green"
+  title="Compact card"
+  containerClassName="w-[600px] pt-[4px] pb-[16px]"
+  bodyClassName="px-[24px]"
+>
+  <p className="text-content-presentation-action-light-primary py-2">
+    Tighter, narrower variant.
+  </p>
+</SectionBlock>
+```
+
+## Patterns
+
+- **Color coding**: Use distinct colors to help users scan a page of multiple sections (e.g., Blue for primary forms, Yellow for warnings, Red for destructive zones).
+- **No-title sections**: Drop the `title` prop entirely when the section's purpose is obvious from context — keeps the body padding without the visual weight of a header.
+- **Composing with form fields**: `SectionBlock` does not impose any inner layout — pair it with helpers like the `FieldRow` pattern above, or with `InputField`, `Form`, or `FieldSection` for more structured forms.
+- **Default width**: The component ships with `w-[1100px]`. Override via `containerClassName="w-full"` (or any specific width) for narrower containers.
+
+## Accessibility
+
+- The container is a plain `<div>`. If the section represents a distinct landmark, add `role="region"` and an `aria-label` (or use `aria-labelledby` pointing at the title).
+- The title is rendered as styled text inside a badge `<div>`, not as a heading element. If the section needs a heading semantically, wrap your `title` content in an appropriate `<h2>`/`<h3>` and reset its margin via Tailwind classes.
+
+## Troubleshooting
+
+| Issue | Fix |
+|-------|-----|
+| Card overflows on small screens | Default width is `w-[1100px]`. Override with `containerClassName="w-full"` or a smaller fixed width. |
+| Title not showing | The `title` prop is optional — omitting it hides the entire header. Pass any non-null `ReactNode` to render it. |
+| Badge color looks wrong | `color` only accepts the predefined `SectionColor` values. For custom badge colors, override via `headerClassName` and a custom child node. |
+| Need a different background | The body uses `bg-background-presentation-form-base`. Override via `containerClassName` (your class wins via `cn()` merging). |

package/docs/components/select.md

@@ -535,6 +535,30 @@ test('Select meets WCAG standards', async () => {
 })
 ```
 
+## Known Limitations & Frontend Patterns
+
+### `Select` does not stretch to fill its container by default
+
+The shipped `SelectTrigger` base styles do not include `w-full`, so when placed inside a CSS grid or flex column the trigger collapses to the width of its placeholder/selected text. This breaks row alignment in forms whenever `Select` is mixed with `InputField` or other full-width controls.
+
+**Always pass `className="w-full h-10"` on form-context `Select` usages**:
+
+```tsx
+<Select
+  className="w-full h-10"
+  value={type}
+  onValueChange={setType}
+  options={typeOptions}
+  placeholder="Select type"
+/>
+```
+
+For inline / compact / table-cell usages where you genuinely want the trigger to be content-sized, omit `w-full` (or pass `w-auto`).
+
+### Numeric/financial selects
+
+When `Select` is the source of a number (account code, fiscal period), keep the displayed `label` formatted (e.g. `"JV-001 — Journal Voucher"`) but the `value` as the raw key (`"JV"`). Do **not** put numeric formatting in the `value` itself.
+
 ## Accessibility
 
 ### Keyboard Support

package/docs/components/simple-select.md

@@ -547,6 +547,40 @@ test('SimpleSelect meets WCAG standards', async () => {
 })
 ```
 
+## Known Limitations & Frontend Patterns
+
+### Empty-string option values crash at runtime
+
+`SimpleSelect` is built on Radix UI's `Select` primitive, which **forbids `<Select.Item value="" />`**. Radix reserves the empty string for "clear selection / show placeholder" semantics. Passing an option with `value: ""` throws:
+
+```
+A <Select.Item /> must have a value prop that is not an empty string.
+```
+
+This is a common footgun for filter bars where the natural "All / Any / None" option looks like `{ value: "", label: "All Statuses" }`.
+
+**Workaround — use a sentinel value and translate in both directions:**
+
+```tsx
+<SimpleSelect
+  value={statusFilter || "ALL"}
+  onValueChange={(val) => setStatusFilter(val === "ALL" ? "" : val)}
+  options={[
+    { value: "ALL", label: "All Statuses" },
+    { value: "DRAFT", label: "Draft" },
+    { value: "POSTED", label: "Posted" },
+  ]}
+  className="w-48 h-10"
+  placeholder="All Statuses"
+/>
+```
+
+Pick a sentinel that won't collide with real values (`"ALL"`, `"__NONE__"`, etc.). Map back to the empty string (or `null`/`undefined`, depending on your state shape) inside `onValueChange` so consumers downstream still see the cleared state.
+
+### Width / height — same as `Select`
+
+`SimpleSelect`'s trigger does not include `w-full` by default. For form rows and filter bars, always pass `className="w-full h-10"` (or `className="w-48 h-10"` for narrower filter selects).
+
 ## Accessibility
 
 ### Keyboard Support

package/docs/components/table.md

@@ -747,6 +747,81 @@ test('Table meets WCAG standards', async () => {
 })
 ```
 
+## Known Limitations & Frontend Patterns
+
+### `Table` defaults to `w-auto` — always pass `className="w-full"` for data tables
+
+The shipped `Table` base classes include `w-auto`, so the table sizes to its content. Inside a `Card`, `Dialog`, or any flex/grid container with short rows, the table collapses to a narrow column on the left with empty space on the right. This is rarely what you want for a data list.
+
+**Always pass `className="w-full"`** for list/data tables:
+
+```tsx
+<Card className="p-0 overflow-hidden">
+  <CardContent className="p-0 overflow-x-auto">
+    <Table className="w-full">
+      <TableHeader>
+        <TableRow>
+          <TableHead>Number</TableHead>
+          <TableHead>Status</TableHead>
+          <TableHead className="text-right">Total Debit</TableHead>
+        </TableRow>
+      </TableHeader>
+      <TableBody>...</TableBody>
+    </Table>
+  </CardContent>
+</Card>
+```
+
+**Wrap with `overflow-x-auto`** on the parent so wide tables (10+ columns) scroll horizontally inside the card instead of overflowing it.
+
+### Numeric columns: `text-right` on both head and cell
+
+Right-align debit, credit, amount, count columns on **both** `TableHead` and the corresponding `TableCell`:
+
+```tsx
+<TableHead className="text-right">Total Debit</TableHead>
+<TableCell className="text-right font-mono">{voucher.totalDebit}</TableCell>
+```
+
+Use `font-mono` on the cell so digits line up across rows.
+
+### `whitespace-nowrap` on date and numeric cells
+
+Dates and amounts wrap awkwardly when the column is narrow. Add `whitespace-nowrap` on those cells (not on heads):
+
+```tsx
+<TableCell className="whitespace-nowrap">{formatDate(voucher.date)}</TableCell>
+```
+
+### `TableCell` force-wraps children — use `childrenClassName` to override
+
+`TableCell` unconditionally wraps children in an inner `<div>` with `flex justify-start items-center gap-1 min-w-[200px] overflow-hidden` plus a fade-out gradient mask. Three common breakages:
+
+1. **Empty-state rows don't center.** A `flex flex-col items-center` empty state ends up flush left because the outer wrapper's `justify-start` already decided alignment.
+2. **Multi-line content is clipped** by `overflow-hidden` + the gradient mask.
+3. **`flex-col` doesn't work** because the wrapper is `flex` (row) by default.
+
+**Workaround — use the `childrenClassName` prop**, which merges into the inner wrapper, and skip your own outer `<div>`:
+
+```tsx
+<TableRow>
+  <TableCell
+    colSpan={7}
+    childrenClassName="flex flex-col items-center justify-center gap-3 py-12 w-full min-w-0 text-content-presentation-global-secondary"
+  >
+    <i className="ri-inbox-line text-4xl opacity-60" />
+    <p className="typography-body-medium-regular">No data</p>
+    <p className="typography-body-small-regular opacity-80">Try adjusting filters</p>
+  </TableCell>
+</TableRow>
+```
+
+Key overrides on `childrenClassName`:
+
+- `flex flex-col` overrides the default `flex-row`
+- `items-center justify-center` overrides `justify-start`
+- `w-full min-w-0` overrides the hardcoded `min-w-[200px]`
+
 ## Accessibility
 
 ### Keyboard Support

package/docs/components/textarea.md

@@ -425,6 +425,46 @@ test('Textarea meets WCAG standards', async () => {
 })
 ```
 
+## Known Limitations & Frontend Patterns
+
+### `Textarea` auto-sizes to its own content and cannot be made full-width via `className`
+
+The shipped component has these hardcoded base classes:
+
+```
+field-sizing-content w-full min-w-[100px] max-w-[100%]
+```
+
+Two consequences:
+
+1. **`field-sizing-content`** sizes the textarea to its content. An empty textarea collapses to ~100 × 36 px regardless of explicit `width`/`min-height` until the user types enough to expand it.
+2. **`className` is forwarded to the wrapping `Label`**, not the inner `<textarea>` element — so passing `className="w-full min-h-24"` does not override the inner sizing.
+
+Real-world impact: a description textarea inside a full-width card renders as a tiny ~100 × 40 px box even with `className="w-full min-h-24"`.
+
+**Workaround used in production — drop the wrapper and use a plain `<textarea>` with TORCH design tokens:**
+
+```tsx
+<textarea
+  {...register("notes")}
+  placeholder="Optional notes..."
+  rows={4}
+  className={[
+    "w-full min-h-24 px-3 py-2 rounded-lg",
+    "border border-border-presentation-global-primary",
+    "bg-background-presentation-form-field-primary",
+    "text-content-presentation-action-light-primary",
+    "typography-body-medium-regular",
+    "outline-none resize-y",
+    "hover:border-border-presentation-action-hover",
+    "focus:border-border-presentation-state-focus",
+    "transition-colors",
+  ].join(" ")}
+/>
+```
+
+This gives you the TORCH look-and-feel without `field-sizing-content`. Switch back to the wrapped `Textarea` once the underlying component drops the auto-sizing default and forwards `className` correctly.
+
 ## Accessibility
 
 ### Keyboard Support

package/docs/components/toggle.md

@@ -373,6 +373,65 @@ interface CustomToggleProps extends ToggleProps, VariantProps<typeof toggleVaria
 export const Toggle: React.ForwardRefExoticComponent<CustomToggleProps>
 ```
 
+## Known Limitations & Frontend Patterns
+
+> ⚠️ **`Toggle` is icon-only.** Its dimensions are hardcoded squares — `S=22×22`, `M=28×28`, `L=34×34`, `XL=40×40` — so any text label wider than ~3 characters will visually clip. The "Filter Options", "Theme Switcher with text", and similar text-label examples below are misleading: they only render correctly in environments that override the dimensions.
+
+### Use `Button` with variant swap for selectable text chips
+
+For format selectors (DOCX, MD, RTF), tag pickers, filter pills, or any case where the chip carries text wider than ~3 characters, **do not use `Toggle`**. Use `Button` with a `variant` swap to express the selected state:
+
+```tsx
+const FORMATS = ["DOCX", "MD", "RTF", "ODT", "EPUB", "TXT"];
+
+export function FormatPicker({ selected, onSelect }: Props) {
+  return (
+    <div className="flex flex-wrap gap-2">
+      {FORMATS.map((format) => {
+        const isSelected = selected === format;
+        return (
+          <Button
+            key={format}
+            type="button"
+            variant={isSelected ? "PrimeStyle" : "BorderStyle"}
+            size="S"
+            onClick={() => onSelect(format)}
+            className="uppercase"
+          >
+            {format}
+          </Button>
+        );
+      })}
+    </div>
+  );
+}
+```
+
+This gives you:
+
+- Auto-sizing horizontal padding via the button's `px-*` defaults
+- Theme-correct surface and text tokens (button variants are pre-themed)
+- Clear pressed/unpressed visual via `PrimeStyle` (filled) vs `BorderStyle` (outlined)
+- All the focus/disabled/loading states from `Button` for free
+
+### When `Toggle` IS the right component
+
+Reserve `Toggle` for its actual designed use case — **icon-only toolbar actions** with a binary on/off state:
+
+- Bold / Italic / Underline in a rich-text toolbar
+- Play / Pause
+- Grid / List view
+- Mute / Unmute
+- Eye / Eye-slash (show/hide password)
+
+```tsx
+<Toggle pressed={isBold} onPressedChange={setBold} aria-label="Bold">
+  <i className="ri-bold" />
+</Toggle>
+```
+
+The icon must fit within the square dimension — `[&_i]:text-[14px]` for size M, etc.
+
 ## Common Patterns
 
 ### Toolbar Group