torch-glare-mcp 1.0.3 → 1.0.5

package/docs/components/alert-dialog.md

@@ -456,6 +456,166 @@ function PermissionAlert() {
 | `variant` | `ButtonVariant` | `'RedSecStyle'` | Button variant |
 | `buttonType` | `'button' \| 'icon'` | `'icon'` | Button type |
 
+## Known Limitations & Frontend Patterns
+
+### Every AlertDialog subcomponent ships without panel/typography defaults — and worse than `Dialog`
+
+`AlertDialogContent` ships with `p-[12px]` (too tight), `AlertDialogHeader` with `flex justify-between` (instead of `flex-col` for stacked title+description), `AlertDialogFooter` with `flex-col-reverse sm:flex-row` (vertical-on-mobile), and `AlertDialogDescription` with the bizarre `bg-background-presentation-form-base border ... rounded-[8px] p-[24px_48px_48px_48px]` — a 48 px-padded bordered box wrapped around what should be a one-line subtitle.
+
+**Production-tested override** — patch `AlertDialog.tsx` once after `npx torch-glare add AlertDialog`. Same surface-token corrections as `Dialog`: use `bg-background-presentation-body-primary` and `text-content-presentation-global-*`, never `*-system-*` and never `form-base`.
+
+```tsx
+"use client";
+
+import * as React from "react";
+import * as AlertDialogPrimitive from "@radix-ui/react-alert-dialog";
+import { cn } from "@/utils/cn";
+
+const AlertDialog = AlertDialogPrimitive.Root;
+const AlertDialogTrigger = AlertDialogPrimitive.Trigger;
+const AlertDialogPortal = AlertDialogPrimitive.Portal;
+
+const AlertDialogOverlay = React.forwardRef<
+  React.ElementRef<typeof AlertDialogPrimitive.Overlay>,
+  React.ComponentPropsWithoutRef<typeof AlertDialogPrimitive.Overlay>
+>(({ className, ...props }, ref) => (
+  <AlertDialogPrimitive.Overlay
+    ref={ref}
+    className={cn(
+      "fixed inset-0 z-50 bg-black/60",
+      "data-[state=open]:animate-in data-[state=closed]:animate-out",
+      "data-[state=closed]:fade-out-0 data-[state=open]:fade-in-0",
+      className,
+    )}
+    {...props}
+  />
+));
+AlertDialogOverlay.displayName = AlertDialogPrimitive.Overlay.displayName;
+
+const AlertDialogContent = React.forwardRef<
+  React.ElementRef<typeof AlertDialogPrimitive.Content>,
+  React.ComponentPropsWithoutRef<typeof AlertDialogPrimitive.Content>
+>(({ className, ...props }, ref) => (
+  <AlertDialogPortal>
+    <AlertDialogOverlay />
+    <AlertDialogPrimitive.Content
+      ref={ref}
+      className={cn(
+        "fixed left-[50%] top-[50%] z-50 translate-x-[-50%] translate-y-[-50%]",
+        "flex flex-col items-stretch justify-start",
+        "w-[92vw] sm:max-w-md",
+        "bg-background-presentation-body-primary",
+        "border border-border-presentation-global-primary",
+        "rounded-xl shadow-lg",
+        "p-0 gap-0 overflow-hidden",
+        "duration-200 data-[state=open]:animate-in data-[state=closed]:animate-out",
+        className,
+      )}
+      {...props}
+    />
+  </AlertDialogPortal>
+));
+AlertDialogContent.displayName = AlertDialogPrimitive.Content.displayName;
+
+const AlertDialogHeader = ({ className, ...props }: React.HTMLAttributes<HTMLDivElement>) => (
+  <div
+    className={cn("flex flex-col space-y-1.5 text-left px-6 pt-5 pb-2", className)}
+    {...props}
+  />
+);
+AlertDialogHeader.displayName = "AlertDialogHeader";
+
+const AlertDialogFooter = ({ className, ...props }: React.HTMLAttributes<HTMLDivElement>) => (
+  <div
+    className={cn("flex flex-row justify-end gap-2 px-6 py-4", className)}
+    {...props}
+  />
+);
+AlertDialogFooter.displayName = "AlertDialogFooter";
+
+const AlertDialogTitle = React.forwardRef<
+  React.ElementRef<typeof AlertDialogPrimitive.Title>,
+  React.ComponentPropsWithoutRef<typeof AlertDialogPrimitive.Title>
+>(({ className, ...props }, ref) => (
+  <AlertDialogPrimitive.Title
+    ref={ref}
+    className={cn(
+      "typography-headers-small-semibold text-content-presentation-global-primary",
+      className,
+    )}
+    {...props}
+  />
+));
+AlertDialogTitle.displayName = AlertDialogPrimitive.Title.displayName;
+
+const AlertDialogDescription = React.forwardRef<
+  React.ElementRef<typeof AlertDialogPrimitive.Description>,
+  React.ComponentPropsWithoutRef<typeof AlertDialogPrimitive.Description>
+>(({ className, ...props }, ref) => (
+  <AlertDialogPrimitive.Description
+    ref={ref}
+    className={cn(
+      "typography-body-small-regular text-content-presentation-global-secondary px-6 pb-2",
+      className,
+    )}
+    {...props}
+  />
+));
+AlertDialogDescription.displayName = AlertDialogPrimitive.Description.displayName;
+
+const AlertDialogAction = AlertDialogPrimitive.Action;
+const AlertDialogCancel = AlertDialogPrimitive.Cancel;
+
+export {
+  AlertDialog,
+  AlertDialogTrigger,
+  AlertDialogPortal,
+  AlertDialogOverlay,
+  AlertDialogContent,
+  AlertDialogHeader,
+  AlertDialogFooter,
+  AlertDialogTitle,
+  AlertDialogDescription,
+  AlertDialogAction,
+  AlertDialogCancel,
+};
+```
+
+Critical default decisions:
+
+- **Drop the bordered box on `AlertDialogDescription`.** The shipped default wraps the description in a 48 px-padded bordered box, which produces a visually heavy nested panel. Description is a one-line subtitle — same typography pattern as `DialogDescription`.
+- **`AlertDialogHeader` → `flex flex-col` (NOT `flex justify-between`)** so title and description stack with proper rhythm.
+- **`AlertDialogFooter` → `flex-row justify-end`** on all viewports, no `flex-col-reverse sm:flex-row` weirdness.
+- **`AlertDialogDescription` carries `px-6 pb-2`** since alert dialogs typically don't have a separate body section between header and footer.
+- Surface and text tokens are **identical to `Dialog`** — `bg-background-presentation-body-primary` + `text-content-presentation-global-primary` + `text-content-presentation-global-secondary`. Never `*-system-*`. Never `form-base`. Never `action-secondary`.
+
+### Standard usage after the override
+
+Once the patches above are in place, every consumer renders correctly with bare components:
+
+```tsx
+<AlertDialog open={open} onOpenChange={setOpen}>
+  <AlertDialogContent>
+    <AlertDialogHeader>
+      <AlertDialogTitle>Delete this template?</AlertDialogTitle>
+      <AlertDialogDescription>
+        This action cannot be undone. The template will be permanently removed.
+      </AlertDialogDescription>
+    </AlertDialogHeader>
+    <AlertDialogFooter>
+      <AlertDialogCancel asChild>
+        <Button type="button" variant="BorderStyle" size="M">Cancel</Button>
+      </AlertDialogCancel>
+      <AlertDialogAction asChild>
+        <Button type="button" variant="RedColStyle" size="M" onClick={handleDelete}>
+          Delete
+        </Button>
+      </AlertDialogAction>
+    </AlertDialogFooter>
+  </AlertDialogContent>
+</AlertDialog>
+```
+
 ## Variants
 
 ### Default Variant

package/docs/components/date-picker.md

@@ -579,6 +579,84 @@ describe('DatePicker', () => {
 })
 ```
 
+## Known Limitations & Frontend Patterns
+
+### `onChange` payload type does not match what TypeScript thinks
+
+`DatePicker` props extend `HTMLAttributes<HTMLInputElement>`, which makes `onChange` look like `(e: ChangeEvent<HTMLInputElement>) => void` where `e.target.value: string`. **At runtime the value is a `Date | Date[] | DateRange`**, not a string — the component dispatches a hand-rolled pseudo-event with the typed payload behind a `string` type assertion.
+
+**Workaround — cast through `unknown` on every call site:**
+
+```tsx
+<DatePicker
+  mode="single"
+  value={startDate}
+  onChange={(e) =>
+    setStartDate(e.target.value as unknown as Date | undefined)
+  }
+/>
+```
+
+For `mode="multiple"`:
+
+```tsx
+onChange={(e) => setDates(e.target.value as unknown as Date[] | undefined)}
+```
+
+For `mode="range"`:
+
+```tsx
+onChange={(e) => setRange(e.target.value as unknown as DateRange | undefined)}
+```
+
+The `as unknown as Date` shape is required — TypeScript will reject `as Date` directly because `string` and `Date` don't overlap.
+
+### `TimePickerValue` interface — `hour`/`minute` are strings, not numbers
+
+The shipped runtime uses `string` for `hour`, `minute`, and `time` (`"AM" | "PM"`). If you derive your own state from `TimePickerValue`, type those fields as `string`, not `number`, regardless of what older docs claim.
+
+### Internal `<Picker>` value/onChange types are incompatible with `TimePickerValue` — `tsc` fails out of the box
+
+`DatePicker.tsx` wraps `torch-react-mobile-picker`'s `<Picker>` and passes a concrete `TimePickerValue` (`{ hour, minute, time }`) where the picker's generic `PickerValue` (`Record<string, string>`) is expected. Strict TypeScript builds fail immediately:
+
+```
+DatePicker.tsx: Type 'TimePickerValue' is not assignable to type 'PickerValue'.
+  Index signature for type 'string' is missing in type 'TimePickerValue'.
+DatePicker.tsx: Type '(e: TimePickerValue) => void' is not assignable to type
+  '(value: PickerValue, key: string) => void'.
+```
+
+**Workaround — add `as any` casts at the `<Picker>` boundary** (and only there, so consumer types stay honest):
+
+```tsx
+<Picker
+  value={value as any}
+  onChange={((e: TimePickerValue) => {
+    onChange(e);
+  }) as any}
+  wheelMode="normal"
+>
+```
+
+Patch this manually after `npx torch-glare add DatePicker` — otherwise `pnpm build` (which runs `tsc -b`) will fail. The same `Ref` import in the file is also unused and trips `noUnusedLocals`; remove it while you're in there.
+
+### `npx torch-glare add DatePicker` does not install `utils/dateFormat.ts`
+
+The CLI ships `DatePicker.tsx` without copying the `dateFormat.ts` utility it imports, so the component fails to build immediately after install:
+
+```
+[plugin:vite:import-analysis] Failed to resolve import "../utils/dateFormat"
+from "DatePicker.tsx".
+```
+
+**Workaround until the CLI is fixed:** create `utils/dateFormat.ts` manually with the three exports the component needs:
+
+- `TimePickerValue` (`{ hour: string; minute: string; time: "AM" | "PM" }`)
+- `applyTimeToDateValue(value, timePickerValue)` — applies the time picker value to the date value
+- `formatDateValueToString(value, timePickerValue, dateFormat)` — formats the date value to a display string
+
+Reverse-engineer the implementation from the call sites in `DatePicker.tsx` until the CLI copies it automatically.
+
 ## Accessibility
 
 - **Keyboard Navigation**:

package/docs/components/dialog.md

@@ -482,6 +482,195 @@ export const DialogCloseButton: React.ForwardRefExoticComponent<
 >
 ```
 
+## Known Limitations & Frontend Patterns
+
+### Every Dialog subcomponent ships without panel/typography defaults
+
+`DialogContent`, `DialogHeader`, `DialogFooter`, `DialogTitle`, and `DialogDescription` all ship without surfaces, padding, rounded corners, or theme-correct typography. The official "bare" example renders an invisible/transparent panel, and the shipped `DialogTitle` defaults to `text-content-system-global-primary` (a light-on-dark token) which renders white-on-white on the correct light surface.
+
+**Critical token corrections** (the previous override was wrong):
+
+- The right surface is `bg-background-presentation-body-primary` — NOT `bg-background-presentation-form-base` (form-base is for input field surfaces) and NOT `bg-background-system-action-secondary` (that's a brand-dark inverted action surface).
+- The right title token is `text-content-presentation-global-primary` — NOT `text-content-system-global-primary`.
+- The right description token is `text-content-presentation-global-secondary` — NOT the shipped triple-stack `"text-sm text-muted-foreground text-content-system-global-primary"`.
+
+**Production-tested override** — patch `Dialog.tsx` once after `npx torch-glare add Dialog`, then every consumer renders correctly with bare components:
+
+```tsx
+"use client";
+
+import * as React from "react";
+import * as DialogPrimitive from "@radix-ui/react-dialog";
+import { cn } from "@/utils/cn";
+
+const Dialog = DialogPrimitive.Root;
+const DialogTrigger = DialogPrimitive.Trigger;
+const DialogPortal = DialogPrimitive.Portal;
+
+const DialogOverlay = React.forwardRef<
+  React.ElementRef<typeof DialogPrimitive.Overlay>,
+  React.ComponentPropsWithoutRef<typeof DialogPrimitive.Overlay>
+>(({ className, ...props }, ref) => (
+  <DialogPrimitive.Overlay
+    ref={ref}
+    className={cn(
+      "fixed inset-0 z-50 bg-black/60",
+      "data-[state=open]:animate-in data-[state=closed]:animate-out",
+      "data-[state=closed]:fade-out-0 data-[state=open]:fade-in-0",
+      className,
+    )}
+    {...props}
+  />
+));
+DialogOverlay.displayName = DialogPrimitive.Overlay.displayName;
+
+const DialogContent = React.forwardRef<
+  React.ElementRef<typeof DialogPrimitive.Content>,
+  React.ComponentPropsWithoutRef<typeof DialogPrimitive.Content>
+>(({ className, children, ...props }, ref) => (
+  <DialogPortal>
+    <DialogOverlay />
+    <DialogPrimitive.Content
+      ref={ref}
+      className={cn(
+        "fixed left-[50%] top-[50%] z-50 translate-x-[-50%] translate-y-[-50%]",
+        "flex flex-col items-stretch justify-start",
+        "w-[92vw] sm:max-w-lg",
+        "bg-background-presentation-body-primary",
+        "border border-border-presentation-global-primary",
+        "rounded-xl shadow-lg",
+        "p-0 gap-0 overflow-hidden",
+        "max-h-[90vh]",
+        "duration-200 data-[state=open]:animate-in data-[state=closed]:animate-out",
+        className,
+      )}
+      {...props}
+    >
+      {children}
+    </DialogPrimitive.Content>
+  </DialogPortal>
+));
+DialogContent.displayName = DialogPrimitive.Content.displayName;
+
+const DialogHeader = ({ className, ...props }: React.HTMLAttributes<HTMLDivElement>) => (
+  <div
+    className={cn("flex flex-col space-y-1.5 text-left px-6 pt-5 pb-4", className)}
+    {...props}
+  />
+);
+DialogHeader.displayName = "DialogHeader";
+
+const DialogFooter = ({ className, ...props }: React.HTMLAttributes<HTMLDivElement>) => (
+  <div
+    className={cn("flex flex-row justify-end gap-2 px-6 py-4", className)}
+    {...props}
+  />
+);
+DialogFooter.displayName = "DialogFooter";
+
+const DialogTitle = React.forwardRef<
+  React.ElementRef<typeof DialogPrimitive.Title>,
+  React.ComponentPropsWithoutRef<typeof DialogPrimitive.Title>
+>(({ className, ...props }, ref) => (
+  <DialogPrimitive.Title
+    ref={ref}
+    className={cn(
+      "typography-headers-small-semibold text-content-presentation-global-primary",
+      className,
+    )}
+    {...props}
+  />
+));
+DialogTitle.displayName = DialogPrimitive.Title.displayName;
+
+const DialogDescription = React.forwardRef<
+  React.ElementRef<typeof DialogPrimitive.Description>,
+  React.ComponentPropsWithoutRef<typeof DialogPrimitive.Description>
+>(({ className, ...props }, ref) => (
+  <DialogPrimitive.Description
+    ref={ref}
+    className={cn(
+      "typography-body-small-regular text-content-presentation-global-secondary",
+      className,
+    )}
+    {...props}
+  />
+));
+DialogDescription.displayName = DialogPrimitive.Description.displayName;
+
+export {
+  Dialog,
+  DialogTrigger,
+  DialogPortal,
+  DialogOverlay,
+  DialogContent,
+  DialogHeader,
+  DialogFooter,
+  DialogTitle,
+  DialogDescription,
+};
+```
+
+Critical default decisions, and why:
+
+- **`bg-background-presentation-body-primary`** for the panel surface — it's the body-surface token that pairs correctly with `text-content-presentation-global-primary` across all themes. `form-base` and `action-secondary` are wrong choices that the previous version of this doc recommended.
+- **`p-0 gap-0 overflow-hidden`** on `DialogContent` — padding is delegated to `DialogHeader`/`DialogFooter` (and the form body). Keeping the content padding-free lets header/footer touch the rounded corners cleanly.
+- **`DialogHeader` → `flex flex-col space-y-1.5 ... px-6 pt-5 pb-4`** — column layout (NOT `flex justify-between` like the shipped default) so title and description stack with a tight 6 px gap. Padding lives here, not on the content.
+- **`DialogFooter` → `flex flex-row justify-end gap-2 px-6 py-4`** — horizontal on all viewports (NOT `flex-col-reverse sm:flex-row` like the shipped default). The shipped vertical-on-mobile pattern looks broken on narrow phones too.
+- **`w-[92vw] sm:max-w-lg`** — 92 % of viewport on mobile, 512 px max from `sm` up. Override per-dialog with `className="sm:max-w-110"` (440 px) or `sm:max-w-2xl` (672 px) for wider forms.
+
+### Form body lives outside the form-padded `DialogFooter`
+
+Place the `<form>` between `DialogHeader` and `DialogFooter`, with the footer as a **sibling outside the form** so its padding doesn't compound with the form body's padding. Use `type="button"` + `onClick={handleSubmit(onSubmit)}` on the submit button rather than `type="submit"`:
+
+```tsx
+<Dialog open={open} onOpenChange={onOpenChange}>
+  <DialogContent className="sm:max-w-110">
+    <DialogHeader>
+      <DialogTitle>Create Folder</DialogTitle>
+      <DialogDescription>Add a new folder.</DialogDescription>
+    </DialogHeader>
+
+    <form className="flex flex-col gap-4 px-6 py-5">
+      <LabelField
+        label="Folder Name"
+        requiredLabel="*"
+        {...register("name")}
+        className="w-full *:w-full"
+      />
+    </form>
+
+    <DialogFooter>
+      <Button type="button" variant="BorderStyle" size="M" onClick={() => onOpenChange(false)}>
+        Cancel
+      </Button>
+      <Button type="button" variant="PrimeStyle" size="M" onClick={handleSubmit(onSubmit)}>
+        Create
+      </Button>
+    </DialogFooter>
+  </DialogContent>
+</Dialog>
+```
+
+The `px-6 py-5` body padding matches the header/footer's horizontal `px-6` rhythm so the columns line up vertically across the panel.
+
+### `DialogTitle` with icon
+
+Plain `<DialogTitle>Create Account</DialogTitle>` is fine, but you can pass JSX with an icon for instant entity recognition:
+
+```tsx
+<DialogHeader>
+  <DialogTitle>
+    <div className="flex items-center gap-2">
+      <i className="ri-bank-line text-content-presentation-state-information" />
+      <span>Create Account</span>
+    </div>
+  </DialogTitle>
+</DialogHeader>
+```
+
+Pick an icon that matches the entity (`ri-bank-line` for accounts, `ri-calendar-line` for fiscal periods, `ri-receipt-line` for vouchers, etc.).
+
 ## Common Patterns
 
 ### Alert/Confirmation Pattern

package/docs/components/input-field.md

@@ -426,6 +426,42 @@ test('InputField meets WCAG standards', async () => {
 })
 ```
 
+## Known Limitations & Frontend Patterns
+
+### Form-row alignment (h-10)
+
+When mixing `InputField` with `Select`, `<input type="date">`, or other form controls in a multi-column row, default heights don't always match. The shipped pattern that keeps everything on a 40 px baseline:
+
+```tsx
+<InputField
+  className="h-10"
+  icon={<i className="ri-hashtag text-base" />}
+  placeholder="e.g. JV-001"
+  errorMessage={errors.code?.message}
+  toolTipSide="top"
+  {...register("code")}
+/>
+```
+
+Recommendations:
+
+- Pass `className="h-10"` on every form-context `InputField`. Pair with `Select` set to `className="w-full h-10"` so the row aligns.
+- Use `errorMessage` + `toolTipSide` instead of rendering a separate `<p>` below the field — the built-in tooltip is less visually noisy and is what the component is designed for.
+- Add an `icon` prop (`<i className="ri-* text-base" />`) for visual scannability; this is standard across most form fields in production apps.
+
+> ⚠️ **Do not use `variant="SystemStyle"`** to "fix" the form look — `SystemStyle` is reserved for internal library system surfaces. Use the default `PresentationStyle` plus `className="h-10"`. See the rules banner at the top of every doc response.
+
+### Field wrapper for forms
+
+Wrap each labeled field in `flex flex-col gap-1.5` (not `space-y-1.5`) so labels align cleanly at the top of multi-column rows:
+
+```tsx
+<div className="flex flex-col gap-1.5">
+  <Label>Voucher Number *</Label>
+  <InputField className="h-10" icon={...} {...register("number")} />
+</div>
+```
+
 ## Accessibility
 
 ### Keyboard Support

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

package/docs/how-to/form-and-list-recipes.md

@@ -0,0 +1,379 @@
+---
+title: Form & List Page Recipes
+description: Production-tested patterns for building create dialogs, list pages, journal-line grids, and login layouts with TORCH Glare. Captures the "what actually ships" decisions for app-builders.
+keywords: [recipes, patterns, form, list, dialog, journal, line-items, login, filter-bar, grid]
+---
+
+# Form & List Page Recipes
+
+Battle-tested layouts and component combinations from production frontend work.
+Use these as the starting point for create dialogs, list/filter pages,
+line-item grids, and login flows.
+
+> All examples use the `presentation` color tokens. Never substitute
+> `*-system-*` tokens or `variant="SystemStyle"` — see the rules banner at
+> the top of every doc response.
+
+---
+
+## Recipe 1 — Multi-column form row with consistent baselines
+
+**Use case:** A row in a create dialog that mixes `InputField`, `Select`, and
+date inputs. Default heights don't match across components, so you have to
+opt in to alignment explicitly.
+
+```tsx
+<div className="grid grid-cols-3 gap-4">
+  <div className="flex flex-col gap-1.5">
+    <Label>Voucher Type *</Label>
+    <Select
+      className="w-full h-10"
+      value={type}
+      onValueChange={setType}
+      options={typeOptions}
+      placeholder="Select type"
+    />
+  </div>
+
+  <div className="flex flex-col gap-1.5">
+    <Label>Date *</Label>
+    <InputField
+      className="h-10"
+      type="date"
+      icon={<i className="ri-calendar-line text-base" />}
+      {...register("date")}
+    />
+  </div>
+
+  <div className="flex flex-col gap-1.5">
+    <Label>Fiscal Period *</Label>
+    <Select
+      className="w-full h-10"
+      value={period}
+      onValueChange={setPeriod}
+      options={periodOptions}
+      placeholder="Select period"
+    />
+  </div>
+</div>
+```
+
+Key rules:
+
+- **Every form control gets `h-10`** — both `InputField` and `Select` (which
+  also needs `w-full`).
+- **Wrap each field in `flex flex-col gap-1.5`**, not `space-y-1.5`, so labels
+  sit cleanly at the top of the row.
+- **Use `<InputField type="date">`** instead of a native `<input type="date">`
+  so you keep the icon slot and consistent styling.
+
+---
+
+## Recipe 2 — List page with filter bar + data table
+
+**Use case:** Every list page (vouchers, accounts, bank accounts, etc.) needs
+the same filter bar — a search input + one or more select filters above a
+data table.
+
+```tsx
+{/* Filter bar */}
+<div className="flex items-center gap-3">
+  <div className="flex-1 max-w-sm">
+    <InputField
+      className="h-10"
+      icon={<i className="ri-search-line text-base" />}
+      placeholder="Search..."
+      value={search}
+      onChange={(e) => setSearch(e.target.value)}
+    />
+  </div>
+
+  <SimpleSelect
+    className="w-48 h-10"
+    value={statusFilter || "ALL"}
+    onValueChange={(val) => setStatusFilter(val === "ALL" ? "" : val)}
+    options={[
+      { value: "ALL", label: "All Statuses" },
+      { value: "DRAFT", label: "Draft" },
+      { value: "POSTED", label: "Posted" },
+    ]}
+    placeholder="All Statuses"
+  />
+</div>
+
+{/* Data table */}
+<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>
+          <TableHead className="text-right">Total Credit</TableHead>
+        </TableRow>
+      </TableHeader>
+      <TableBody>
+        {rows.length === 0 ? (
+          <TableRow>
+            <TableCell
+              colSpan={4}
+              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 vouchers</p>
+              <p className="typography-body-small-regular opacity-80">
+                Try adjusting your filters
+              </p>
+            </TableCell>
+          </TableRow>
+        ) : (
+          rows.map((v) => (
+            <TableRow key={v.id}>
+              <TableCell className="whitespace-nowrap">{v.number}</TableCell>
+              <TableCell>{v.status}</TableCell>
+              <TableCell className="text-right font-mono whitespace-nowrap">
+                {v.totalDebit}
+              </TableCell>
+              <TableCell className="text-right font-mono whitespace-nowrap">
+                {v.totalCredit}
+              </TableCell>
+            </TableRow>
+          ))
+        )}
+      </TableBody>
+    </Table>
+  </CardContent>
+</Card>
+```
+
+Key rules:
+
+- **Never use a native `<select>`** — `SimpleSelect` keeps styling consistent
+  with the rest of your forms.
+- **Never manually position a search icon with absolute positioning** —
+  `InputField`'s `icon` prop is built for this.
+- **Numeric columns get `text-right` on both `TableHead` and `TableCell`**,
+  plus `font-mono` on the cell so digits line up.
+- **Empty states use `childrenClassName`** on `TableCell` to bypass the
+  default `flex-row justify-start min-w-[200px]` wrapper. See `Table.md`
+  → "TableCell force-wraps children" for why.
+- **The "All / Any" filter option needs a sentinel value** (`"ALL"` here)
+  because Radix forbids `value=""`. See `SimpleSelect.md` for details.
+
+---
+
+## Recipe 3 — Journal lines / line-item grid (display: contents)
+
+**Use case:** A repeating-row layout (journal lines, invoice line items,
+purchase order rows) with a header, N data rows, and a totals row — where
+columns must align across all rows.
+
+The naïve approach (each row is its own `display: grid`) breaks: short
+footer content collapses to a different width than long input content,
+and columns drift across rows. The fix is **one parent grid** with
+`className="contents"` on each row wrapper so the row's children become
+direct grid items of the parent.
+
+```tsx
+<div className="grid w-full grid-cols-[32px_minmax(0,2.5fr)_minmax(0,3fr)_minmax(0,1.5fr)_minmax(0,1.5fr)_36px] gap-x-3 gap-y-2 px-2">
+  {/* Header cells (direct grid items) */}
+  <div>#</div>
+  <div>Account</div>
+  <div>Description</div>
+  <div>Debit</div>
+  <div>Credit</div>
+  <div />
+
+  {/* Data rows — wrapper uses className="contents" so its children become
+      direct grid items of the parent grid */}
+  {lines.map((line, idx) => (
+    <div key={line.key} className="contents">
+      <div>{idx + 1}</div>
+      <Select
+        className="w-full h-10"
+        value={line.accountId}
+        onValueChange={(v) => updateLine(line.key, { accountId: v })}
+        options={accountOptions}
+      />
+      <InputField
+        className="h-10"
+        value={line.description}
+        onChange={(e) => updateLine(line.key, { description: e.target.value })}
+      />
+      <InputField
+        className="h-10 text-right font-mono"
+        type="number"
+        value={line.debit}
+        onChange={(e) => updateLine(line.key, { debit: e.target.value })}
+      />
+      <InputField
+        className="h-10 text-right font-mono"
+        type="number"
+        value={line.credit}
+        onChange={(e) => updateLine(line.key, { credit: e.target.value })}
+      />
+      <button onClick={() => removeLine(line.key)} aria-label="Delete row">
+        <i className="ri-delete-bin-line" />
+      </button>
+    </div>
+  ))}
+
+  {/* Totals row — direct grid items, no wrapper */}
+  <div />
+  <div />
+  <div className="text-right">Totals</div>
+  <div className="text-right font-mono">{totalDebit}</div>
+  <div className="text-right font-mono">{totalCredit}</div>
+  <div />
+</div>
+```
+
+Key rules:
+
+- **`className="contents"`** on the row wrapper is the critical trick. The
+  wrapper renders nothing of its own, so its children become direct grid
+  items of the parent.
+- **`minmax(0, Xfr)`** columns prevent content-driven blowout when a single
+  cell has a long value.
+- **Fixed-width columns** (the `32px` row-number column, the `36px` delete
+  column) are absolute pixel widths; flexible columns use `fr`.
+- **Header alignment**: Debit/Credit headers are `text-left` because the
+  column starts at the input's left edge — right-aligning the header would
+  visually disconnect it from the column. The values inside the input are
+  right-aligned via `text-right font-mono` on the input itself.
+
+---
+
+## Recipe 4 — `DialogTitle` with icon
+
+**Use case:** Plain `<DialogTitle>Create Account</DialogTitle>` lacks visual
+hierarchy. Adding a relevant icon makes dialogs instantly recognizable.
+
+```tsx
+<DialogHeader>
+  <DialogTitle>
+    <div className="flex items-center gap-2">
+      <i className="ri-bank-line text-content-presentation-state-information" />
+      <span>Create Account</span>
+    </div>
+  </DialogTitle>
+</DialogHeader>
+```
+
+Pick an icon that matches the entity:
+
+| Entity | Icon |
+|---|---|
+| Account | `ri-bank-line` |
+| Fiscal period / year | `ri-calendar-line` |
+| Voucher / journal | `ri-receipt-line` |
+| Number series | `ri-hashtag` |
+| Posting rule | `ri-settings-3-line` |
+| Exchange rate | `ri-exchange-line` |
+| Bank / cash account | `ri-bank-card-line` |
+
+---
+
+## Recipe 5 — Two-column login layout
+
+**Use case:** A login page with brand panel on the left and form on the right.
+Communicates product identity better than a single centered card.
+
+```tsx
+import { Card, CardContent } from "@/components/Card";
+import { InputField } from "@/components/InputField";
+import { LoginButton } from "@/components/LoginButton";
+
+export function LoginPage() {
+  return (
+    <div className="grid min-h-screen grid-cols-1 lg:grid-cols-2">
+      {/* Brand panel — hidden on mobile */}
+      <div
+        className={[
+          "hidden lg:flex flex-col justify-center gap-6 p-12",
+          "bg-linear-to-br from-background-presentation-action-primary/20",
+          "via-background-presentation-form-base",
+          "to-background-presentation-state-information/10",
+        ].join(" ")}
+      >
+        <h1 className="typography-headers-large-medium">
+          Welcome to Torch Finance
+        </h1>
+        <ul className="flex flex-col gap-3">
+          {features.map((f) => (
+            <li key={f.title} className="flex items-start gap-3">
+              <span
+                className={[
+                  "mt-0.5 inline-flex h-6 w-6 items-center justify-center",
+                  "rounded-full bg-background-presentation-state-success-primary",
+                  "text-content-presentation-action-dark-primary",
+                ].join(" ")}
+              >
+                <i className="ri-check-line" />
+              </span>
+              <div>
+                <p className="typography-body-medium-medium">{f.title}</p>
+                <p className="typography-body-small-regular text-content-presentation-global-secondary">
+                  {f.description}
+                </p>
+              </div>
+            </li>
+          ))}
+        </ul>
+      </div>
+
+      {/* Form panel */}
+      <div className="flex items-center justify-center p-6">
+        <Card className="w-full max-w-md">
+          <CardContent className="flex flex-col gap-4 p-8">
+            <h2 className="typography-headers-medium-medium">Sign in</h2>
+
+            <InputField
+              className="h-10"
+              type="email"
+              icon={<i className="ri-mail-line text-base" />}
+              placeholder="Email"
+              errorMessage={errors.email?.message}
+              {...register("email")}
+            />
+
+            <InputField
+              className="h-10"
+              type={showPassword ? "text" : "password"}
+              icon={<i className="ri-lock-line text-base" />}
+              childrenSide={
+                <button
+                  type="button"
+                  onClick={() => setShowPassword((v) => !v)}
+                  aria-label={showPassword ? "Hide password" : "Show password"}
+                >
+                  <i className={showPassword ? "ri-eye-off-line" : "ri-eye-line"} />
+                </button>
+              }
+              placeholder="Password"
+              errorMessage={errors.password?.message}
+              {...register("password")}
+            />
+
+            <LoginButton isLoading={isSubmitting} type="submit">
+              Sign in
+            </LoginButton>
+          </CardContent>
+        </Card>
+      </div>
+    </div>
+  );
+}
+```
+
+Key rules:
+
+- **`hidden lg:flex`** hides the brand panel on mobile; the form panel
+  stretches to full width below the breakpoint.
+- **`bg-linear-to-br from-* via-* to-*`** is Tailwind v4 gradient syntax. For
+  v3 use `bg-gradient-to-br`.
+- **`LoginButton` has a built-in `isLoading` prop** — wire it to your form's
+  submitting state instead of writing your own loading spinner.
+- **Use `InputField`'s `childrenSide`** for the password show/hide toggle —
+  the slot is built for trailing actions like this.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "torch-glare-mcp",
-  "version": "1.0.3",
+  "version": "1.0.5",
   "description": "MCP server for TORCH Glare component library — gives AI assistants full access to component docs, API references, code examples, and design system info",
   "type": "module",
   "main": "dist/index.js",