torch-glare 1.3.0 → 1.5.0

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