torch-glare 2.4.0 → 2.4.2

package/docs/components/form-renderer.md

@@ -0,0 +1,228 @@
+---
+title: FormRenderer
+description: A thin wrapper around FormBuilder. Author fields as JSX children; FormRenderer owns page-vs-drawer display, the absolute title header, and drawer field layout. You compose the Save and pass it via the actions prop.
+component: true
+group: Forms
+keywords: [form-renderer, form, drawer, header, display, view-mode, react-hook-form]
+---
+
+# FormRenderer
+
+A thin wrapper around the compound [FormBuilder](./form-builder.md). You author the
+fields as **JSX children** exactly as you would with `FormBuilder`; `FormRenderer`
+takes care of the surrounding concerns:
+
+- **page vs drawer** display (`display="drawer"` hosts the form in a `FormDrawer`),
+- the **absolute title header** + action bar (page display),
+- **vertical field layout** inside a drawer.
+
+FormRenderer never manufactures a Submit — **you compose the Save and hand it to `actions`**.
+It renders in the form's header action pill (page) or the drawer header (drawer), and a bare
+`<FormBuilder.Submit>` auto-targets this form (even though the header sits outside the `<form>`).
+
+Reach for `FormBuilder` directly when you just want the form. Reach for
+`FormRenderer` when you want the same form to render as a page _or_ a drawer with
+the standard chrome.
+
+```tsx
+<FormRenderer
+  onSubmit={save}
+  resolver={zodResolver(schema)}
+  defaultValues={d}
+  header={{ title: "Item", variant: "new" }}
+  actions={<FormBuilder.Submit>Save</FormBuilder.Submit>}
+>
+  <FormBuilder.Section title="Identity" color="Blue">
+    <FormBuilder.Text name="name" label="Name" required />
+    <FormBuilder.Currency name="price" label="Price" currencySymbol="$" />
+  </FormBuilder.Section>
+</FormRenderer>
+```
+
+## Installation
+
+```bash
+npx torch-glare@latest init
+npx torch-glare@latest add FormRenderer
+```
+
+`add` also pulls in `FormBuilder`, which FormRenderer renders through.
+
+## Imports
+
+```tsx
+import { FormRenderer, FormDrawer } from "@/components/FormRenderer";
+import { FormBuilder } from "@/components/FormBuilder";
+```
+
+## Props
+
+| Prop                                                           | Type                          | Notes                                                                                                                                                                                                                                                                            |
+| -------------------------------------------------------------- | ----------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `children`                                                     | `ReactNode`                   | The form body — `FormBuilder.Section` / field / `FormBuilder.Stepper` JSX.                                                                                                                                                                                                       |
+| `onSubmit` / `onInvalid`                                       | fns                           | Submit / validation-fail callbacks.                                                                                                                                                                                                                                              |
+| `resolver`                                                     | `Resolver`                    | Any react-hook-form resolver, e.g. `zodResolver(schema)`.                                                                                                                                                                                                                        |
+| `defaultValues` / `values`                                     | `DefaultValues` / `T`         | Initial values; `values` re-syncs on change (edit).                                                                                                                                                                                                                              |
+| `mode`                                                         | `'edit' \| 'view'`            | `'view'` renders read-only, no Submit.                                                                                                                                                                                                                                           |
+| `loading` / `resetOnSuccess`                                   | `boolean`                     | Forwarded to `FormBuilder`.                                                                                                                                                                                                                                                      |
+| `fieldDirection`                                               | `'horizontal' \| 'vertical'`  | Defaults to vertical inside a drawer.                                                                                                                                                                                                                                            |
+| `form`                                                         | `UseFormReturn<T>`            | A hoisted `useForm` to bind to — pass when a sibling (e.g. a `summary` `FormSummary`) must read the same live values; the caller owns `resolver`/`defaultValues` on it. Omit to let FormRenderer create its own.                                                                 |
+| `display`                                                      | `'page' \| 'drawer'`          | `'drawer'` wraps the form in `FormDrawer`.                                                                                                                                                                                                                                       |
+| `header`                                                       | `{ title; label?; variant? }` | Absolute title header + action bar (page display); `actions` render in it.                                                                                                                                                                                                       |
+| `summary`                                                      | `ReactNode`                   | A live panel (typically `FormSummary`) rendered beside the form (page) or in the drawer tray (drawer). Give the same hoisted `form` so it reads live values. On a page, a `summary` **plus** a `FormBuilder.Stepper` lays out as three columns — stepper nav · fields · summary. |
+| `actions`                                                      | `ReactNode`                   | The form's action bar — rendered in the header action pill (page) or drawer header (drawer). Put the Save here: `actions={<FormBuilder.Submit>Save</FormBuilder.Submit>}`. A bare `FormBuilder.Submit` auto-targets this form.                                                   |
+| `id`                                                           | `string`                      | `id` on the underlying `<form>`. Optional — FormRenderer generates and wires one otherwise.                                                                                                                                                                                      |
+| `open` / `onOpenChange` / `title` / `badge` / `onOpenInNewTab` | —                             | Drawer control (when `display="drawer"`). `title` / `badge` are strings that override `header.title` / `header.label`.                                                                                                                                                           |
+
+## Drawer & view
+
+```tsx
+// drawer — pass the Save via `actions`; it renders in the drawer header
+<FormRenderer
+  display="drawer" open={open} onOpenChange={setOpen} title="New item" badge="New"
+  onSubmit={save} resolver={r} defaultValues={d}
+  actions={<FormBuilder.Submit>Save</FormBuilder.Submit>}
+>
+  {fields}
+</FormRenderer>
+
+// read-only view — same children, omit `actions` (a view has no Save)
+<FormRenderer mode="view" values={entity} onSubmit={() => {}}>
+  {fields}
+</FormRenderer>
+```
+
+## Stepper
+
+Drop a `FormBuilder.Stepper` in as the child. The Save lives in the header `actions` and
+submits every step's registered fields at once (steps stay mounted, so the whole form is live).
+
+```tsx
+<FormRenderer
+  onSubmit={save}
+  resolver={r}
+  defaultValues={d}
+  header={{ title: "New item", variant: "new" }}
+  actions={<FormBuilder.Submit>Save</FormBuilder.Submit>}
+>
+  <FormBuilder.Stepper>
+    <FormBuilder.Step title="Basics">
+      <FormBuilder.Text name="name" label="Name" required />
+    </FormBuilder.Step>
+  </FormBuilder.Stepper>
+</FormRenderer>
+```
+
+## Summary panel
+
+Pass a hoisted `useForm` as `form` and a `FormSummary` as `summary` — FormRenderer binds
+the form to that instance and lays the panel beside the form (page) or in the drawer tray
+(drawer), so it recomputes live as fields change.
+
+```tsx
+const form = useForm<Invoice>({ resolver, defaultValues })
+
+<FormRenderer
+  form={form}
+  onSubmit={save}
+  header={{ title: 'Invoice', variant: 'new' }}
+  actions={<FormBuilder.Submit>Save invoice</FormBuilder.Submit>}
+  summary={
+    <FormSummary form={form} title="Invoice" subtitle="Summary">
+      <FormSummary.Group title="Total">
+        <FormSummary.Row label="Overall Total" emphasized compute={overallTotal} />
+      </FormSummary.Group>
+    </FormSummary>
+  }
+>
+  {fields}
+</FormRenderer>
+```
+
+Works with `display="drawer"` too — the summary moves into the drawer's tray.
+
+## `FormDrawer` — the drawer wrapper
+
+`FormRenderer` uses `FormDrawer` internally for `display: 'drawer'`. It's also exported
+so you can put a hand-composed `FormBuilder` in a drawer directly. Since the header sits
+outside the `<form>`, wire the Save button to the form via `id` / `form={id}`:
+
+```tsx
+<FormDrawer
+  open={open}
+  onOpenChange={setOpen}
+  title="New item"
+  badge="New"
+  actions={
+    <Button type="submit" form="item-form" is_loading={saving}>
+      Save
+    </Button>
+  }
+>
+  <FormBuilder
+    id="item-form"
+    onSubmit={save}
+    resolver={r}
+    defaultValues={d}
+    fieldDirection="vertical"
+  >
+    …fields…
+  </FormBuilder>
+</FormDrawer>
+```
+
+`FormDrawer` props: `open`, `onOpenChange`, `title`, `badge`, `variant`, `actions`,
+`onOpenInNewTab`, `children`, `summary`. It owns no form state.
+
+### The title
+
+The drawer renders the **same floating header as the page form** — a [HeaderBar](./header-bar.md)
+title pill on the left, a dark action pill on the right — so a form's title looks identical in
+either display. `title` is the plain (uppercased) text, `badge` the colored emphasis pill, and
+`variant` (`new` / `edit` / `detail`) picks the badge colors; `badge` defaults from it
+(New / Edit / View).
+
+```tsx
+<FormDrawer title="Sales Invoice" badge="New" variant="new" … />
+```
+
+Driving it through `FormRenderer`, the `header` prop feeds both displays — including
+`header.variant`, which the drawer previously ignored:
+
+```tsx
+<FormRenderer display="drawer" header={{ title: "Sales Invoice", variant: "edit" }} … />
+```
+
+`title` and `badge` are **plain strings** (they were `ReactNode` before this shared-header
+change) because they render through `HeaderBar`'s uppercase text treatment.
+
+### A summary beside the form
+
+`summary` renders a conclusion panel — typically a [FormSummary](./form-summary.md) — _beside_
+the form rather than inside its scrollable body. `FormDrawer` puts the form in a
+[`DrawerPanel`](./drawer.md#drawerpanel) (the light surface) and the summary next to it with a
+6px gutter; the tray paints nothing, so the summary keeps its own dark background and full
+height, scrolling internally when it outruns the drawer.
+
+Hoist the form so both read the same instance:
+
+```tsx
+const form = useForm({ resolver, defaultValues })
+
+<FormDrawer
+  open={open} onOpenChange={setOpen} title="New item" badge="New"
+  summary={
+    <FormSummary form={form} title="Item" subtitle="Summary">
+      <FormSummary.Group title="Pricing">…rows…</FormSummary.Group>
+    </FormSummary>
+  }
+>
+  <FormBuilder form={form} id="item-form" onSubmit={save} fieldDirection="vertical">
+    …fields…
+  </FormBuilder>
+</FormDrawer>
+```
+
+> `childrenOutside` is the deprecated former name for `summary`. It still works.
+
+`FormRenderer` does **not** forward `summary` — use `FormDrawer` directly when you need one.

package/docs/components/form-stepper.md

@@ -14,10 +14,16 @@ The component is composed of `FormStepper`, `FormStep`, `FormStepIndicator`, and
 
 ## Installation
 
+TORCH Glare is a copy-in library: the CLI copies this component's source into your project
+(you do **not** install it from the npm package). Run `init` once, then `add`:
+
 ```bash
+npx torch-glare@latest init
 npx torch-glare@latest add FormStepper
 ```
 
+`add` also copies any components, hooks, and utilities that `FormStepper` depends on.
+
 ## Imports
 
 ```typescript

package/docs/components/form-summary.md

@@ -0,0 +1,123 @@
+---
+title: FormSummary
+description: A read-only calculation panel displayed beside a form. Each row declares a compute(values) that runs against the live form values, so totals recalculate as the user types.
+component: true
+group: Forms
+keywords: [form-summary, summary, totals, calculation, invoice, panel, react-hook-form, useWatch]
+---
+
+# FormSummary
+
+A read-only **calculation panel** that sits **beside a form** — the invoice-summary
+look: grouped rows of computed totals, right-aligned, in Glare's dark `SystemStyle`
+fields.
+
+Each `FormSummary.Row` declares a **`compute(values)`** that runs against the **live**
+form values, so every total recalculates as the user types.
+
+The panel renders **outside** the form, beside it. Both read the same form, so
+**hoist `useForm`** and hand the instance to each:
+
+```tsx
+const form = useForm({ resolver: zodResolver(schema), defaultValues })
+
+<div className="flex gap-4">
+  <FormBuilder form={form} onSubmit={save} className="min-w-0 flex-1">
+    <FormBuilder.Section title="Line items">…fields…</FormBuilder.Section>
+  </FormBuilder>
+
+  <FormSummary form={form} title="Invoice" subtitle="Summary">
+    <FormSummary.Group title="Total">
+      <FormSummary.Row label="Total Discount" compute={totalDiscount} />
+      <FormSummary.Row label="Overall Total" emphasized compute={overallTotal} />
+      <FormSummary.Row label="Overall Total" currency="IQD" tone="success"
+        compute={v => overallTotal(v) * v.iqdRate} decimals={0} />
+      <FormSummary.Row label="Overall Total" currency="USD" tone="info" compute={overallTotal} />
+    </FormSummary.Group>
+  </FormSummary>
+</div>
+```
+
+`FormBuilder` stays purely an input renderer — it knows nothing about the panel, and
+**you** own the side-by-side layout. Passing `form` to `FormBuilder` makes it use that
+instance instead of creating its own.
+
+### Height
+
+The panel is `h-full` and fills whatever height its parent gives it, scrolling its groups
+(header pinned) once they outrun it. That means **the parent has to have a height** — the
+usual mistake is `items-start` on the flex row, which collapses the panel to its content
+instead. Leave the row at its default `items-stretch`, as above.
+
+To make the panel own the viewport rather than grow with the form, bound the row:
+
+```tsx
+<div className="flex h-[calc(100vh-2rem)] gap-4">
+  <FormBuilder … className="min-w-0 flex-1 overflow-y-auto" />
+  <FormSummary … />
+</div>
+```
+
+> Hoisting the form means a remount `key` no longer resets it. Call `form.reset(defaults)`
+> instead (e.g. when opening a drawer).
+
+## Installation
+
+```bash
+npx torch-glare@latest init
+npx torch-glare@latest add FormSummary
+```
+
+## Imports
+
+```tsx
+import { FormSummary } from '@/components/FormSummary'
+```
+
+## `FormSummary` props
+
+| Prop | Type | Notes |
+|---|---|---|
+| `title` | `ReactNode` | Panel title, e.g. `"Invoice"`. |
+| `subtitle` | `ReactNode` | Muted text beside the title, e.g. `"Summary"`. |
+| `form` | `UseFormReturn` | The form to read values from — required when rendered outside the `<FormBuilder>`. |
+| `width` | `number \| string` | Panel width; default `228`. |
+| `children` | `ReactNode` | `FormSummary.Group` children. |
+
+## `FormSummary.Group` props
+
+| Prop | Type | Notes |
+|---|---|---|
+| `title` | `ReactNode` | The group heading (Customer / Total / Tax / …). Groups are separated by a divider. |
+| `collapsible` | `boolean` | When titled, the heading is a [ConclusionHeader](./conclusion-header.md) that opens/closes **this group's** rows; default `true`. |
+| `defaultOpen` | `boolean` | Initial open state when collapsible; default `true`. |
+
+The main panel title is a plain header — collapsing happens **per group**, not on the whole panel.
+
+## `FormSummary.Row` props
+
+| Prop | Type | Notes |
+|---|---|---|
+| `label` | `ReactNode` | Row label, above the value. |
+| `compute` | `(values) => number \| string` | **The calculation** — receives the live form values. |
+| `value` | `number \| string` | Static value, when there's nothing to compute. |
+| `currency` | `ReactNode` | Currency code, e.g. `"IQD"` — rendered **inside** the field's trailing edge. |
+| `tone` | `'neutral' \| 'success' \| 'info'` | Color of the currency code (green / blue). |
+| `emphasized` | `boolean` | The primary result — lighter, emphasized border. |
+| `decimals` | `number` | Decimal places; default `2` (→ `0.00`). |
+| `action` | `ReactNode` | Trailing slot inside the field, e.g. an `ActionButton`. Shares the slot with `currency`. |
+| `format` | `(value) => string` | Override the default number formatting. |
+
+## Computing totals
+
+`compute` is a plain function of the form values — keep the maths outside the JSX:
+
+```tsx
+const subTotal      = v => v.items.reduce((s, i) => s + i.qty * i.price, 0)
+const totalDiscount = v => v.items.reduce((s, i) => s + i.discount, 0)
+const taxable       = v => Math.max(0, subTotal(v) - totalDiscount(v))
+const totalTax      = v => taxable(v) * (v.taxRate / 100)
+const overallTotal  = v => taxable(v) + totalTax(v)
+```
+
+The panel is **read-only** — it contributes nothing to the submitted values.

package/docs/components/form.md

@@ -1,6 +1,6 @@
 ---
 name: Form
-version: 1.1.15
+version: 2.4.0
 status: stable
 category: components/forms
 tags: [form, validation, react-hook-form, accessible, compound]
@@ -18,25 +18,22 @@ dependencies:
 
 ## Installation
 
+TORCH Glare is a copy-in library: the CLI copies this component's source into your project
+(you do **not** install it from the npm package). Run `init` once, then `add`:
+
 ```bash
-npm install torch-glare react-hook-form
+npx torch-glare@latest init
+npx torch-glare@latest add Form
 ```
 
+`add` also copies any components, hooks, and utilities that `Form` depends on.
+
 ## Import
 
-```typescript
-import {
-  Form,
-  FormField,
-  FormItem,
-  FormLabel,
-  FormControl,
-  FormDescription,
-  FormMessage
-} from 'torch-glare/lib/components/Form'
+Import from your project's local path — the alias configured in `glare.json` (e.g. `@/*`):
 
-// Also import from react-hook-form
-import { useForm } from 'react-hook-form'
+```tsx
+import { Form } from "@/components/Form";
 ```
 
 ## Quick Examples
@@ -52,9 +49,9 @@ import {
   FormLabel,
   FormControl,
   FormMessage
-} from 'torch-glare/lib/components/Form'
-import { Input } from 'torch-glare/lib/components/Input'
-import { Button } from 'torch-glare/lib/components/Button'
+} from '@/components/Form'
+import { Input } from '@/components/Input'
+import { Button } from '@/components/Button'
 
 function BasicForm() {
   const form = useForm({
@@ -213,9 +210,9 @@ function ValidatedForm() {
 ### With Multiple Field Types
 
 ```typescript
-import { Select, SelectTrigger, SelectContent, SelectItem, SelectValue } from 'torch-glare/lib/components/Select'
-import { Checkbox } from 'torch-glare/lib/components/Checkbox'
-import { RadioGroup, RadioGroupItem } from 'torch-glare/lib/components/Radio'
+import { Select, SelectTrigger, SelectContent, SelectItem, SelectValue } from '@/components/Select'
+import { Checkbox } from '@/components/Checkbox'
+import { RadioGroup, RadioGroupItem } from '@/components/Radio'
 
 function MultiFieldForm() {
   const form = useForm({

package/docs/components/header-bar.md

@@ -12,10 +12,16 @@ A presentational header chip used at the top of a form, page, or drawer to commu
 
 ## Installation
 
+TORCH Glare is a copy-in library: the CLI copies this component's source into your project
+(you do **not** install it from the npm package). Run `init` once, then `add`:
+
 ```bash
+npx torch-glare@latest init
 npx torch-glare@latest add HeaderBar
 ```
 
+`add` also copies any components, hooks, and utilities that `HeaderBar` depends on.
+
 ## Imports
 
 ```typescript

package/docs/components/image-attachment.md

@@ -11,16 +11,22 @@ keywords: [image-attachment, file-upload, drag-drop, preview, modal, expandable]
 
 ## Installation
 
-No external dependencies required.
+TORCH Glare is a copy-in library: the CLI copies this component's source into your project
+(you do **not** install it from the npm package). Run `init` once, then `add`:
+
+```bash
+npx torch-glare@latest init
+npx torch-glare@latest add ImageAttachment
+```
+
+`add` also copies any components, hooks, and utilities that `ImageAttachment` depends on.
 
 ## Import
 
-```typescript
-import {
-  ImageAttachment,
-  ExpandableImage,
-  AttachmentImagePreview
-} from '@torch-ui/components'
+Import from your project's local path — the alias configured in `glare.json` (e.g. `@/*`):
+
+```tsx
+import { ImageAttachment } from "@/components/ImageAttachment";
 ```
 
 ## Component Overview
@@ -36,7 +42,7 @@ The ImageAttachment suite consists of three components:
 ### Basic File Upload
 
 ```typescript
-import { ImageAttachment } from '@torch-ui/components'
+import { ImageAttachment } from "@/components/ImageAttachment";
 import { useState } from 'react'
 
 function Example() {
@@ -64,7 +70,7 @@ function Example() {
 ### With Preview
 
 ```typescript
-import { ImageAttachment, ExpandableImage } from '@torch-ui/components'
+import { ImageAttachment, ExpandableImage } from "@/components/ImageAttachment";
 import { useState } from 'react'
 
 function WithPreview() {
@@ -106,12 +112,8 @@ function WithPreview() {
 ### Complete Upload Flow
 
 ```typescript
-import {
-  ImageAttachment,
-  ExpandableImage,
-  AttachmentImagePreview
-} from '@torch-ui/components'
-import { Button } from '@torch-ui/components'
+import { ImageAttachment, ExpandableImage, AttachmentImagePreview } from "@/components/ImageAttachment";
+import { Button } from "@/components/Button";
 import { useState } from 'react'
 
 function CompleteFlow() {
@@ -160,7 +162,7 @@ function CompleteFlow() {
             header={file?.name || 'Image Preview'}
           >
             <Button onClick={handleUpload}>Upload</Button>
-            <Button variant="SecondaryStyle" onClick={handleRemove}>
+            <Button variant="BluSecStyle" onClick={handleRemove}>
               Remove
             </Button>
           </AttachmentImagePreview>
@@ -174,7 +176,7 @@ function CompleteFlow() {
 ### With Drag and Drop (React Dropzone)
 
 ```typescript
-import { ImageAttachment, ExpandableImage } from '@torch-ui/components'
+import { ImageAttachment, ExpandableImage } from "@/components/ImageAttachment";
 import { useDropzone } from 'react-dropzone'
 import { useState } from 'react'
 
@@ -221,7 +223,7 @@ function WithDropzone() {
 ### Multiple File Upload
 
 ```typescript
-import { ImageAttachment, ExpandableImage } from '@torch-ui/components'
+import { ImageAttachment, ExpandableImage } from "@/components/ImageAttachment";
 import { useState } from 'react'
 
 function MultipleFiles() {
@@ -267,8 +269,9 @@ function MultipleFiles() {
 ### With Validation
 
 ```typescript
-import { ImageAttachment } from '@torch-ui/components'
-import { FieldHint, toast } from '@torch-ui/components'
+import { ImageAttachment } from "@/components/ImageAttachment";
+import { FieldHint } from "@/components/FieldHint";
+import { toast } from "@/components/Toast";
 import { useState } from 'react'
 
 function WithValidation() {
@@ -327,12 +330,9 @@ function WithValidation() {
 ### Profile Picture Upload
 
 ```typescript
-import {
-  ImageAttachment,
-  ExpandableImage,
-  AttachmentImagePreview
-} from '@torch-ui/components'
-import { Avatar, Button } from '@torch-ui/components'
+import { ImageAttachment, ExpandableImage, AttachmentImagePreview } from "@/components/ImageAttachment";
+import { Avatar } from "@/components/Avatar";
+import { Button } from "@/components/Button";
 import { useState } from 'react'
 
 function ProfilePictureUpload() {
@@ -400,8 +400,8 @@ function ProfilePictureUpload() {
 ### Gallery Upload
 
 ```typescript
-import { ImageAttachment, ExpandableImage } from '@torch-ui/components'
-import { Button } from '@torch-ui/components'
+import { ImageAttachment, ExpandableImage } from "@/components/ImageAttachment";
+import { Button } from "@/components/Button";
 import { useState } from 'react'
 
 function GalleryUpload() {
@@ -448,7 +448,7 @@ function GalleryUpload() {
               <Button
                 size="S"
                 buttonType="icon"
-                variant="SecondaryStyle"
+                variant="BluSecStyle"
                 className="absolute top-1 right-1 opacity-0 group-hover:opacity-100"
                 onClick={() => handleRemove(image.id)}
               >
@@ -545,11 +545,7 @@ export const AttachmentImagePreview: React.FC<AttachmentImagePreviewProps>
 ### Usage with Types
 
 ```typescript
-import {
-  ImageAttachment,
-  ExpandableImage,
-  AttachmentImagePreview
-} from '@torch-ui/components'
+import { ImageAttachment, ExpandableImage, AttachmentImagePreview } from "@/components/ImageAttachment";
 import { useRef, useState } from 'react'
 
 function TypedExample() {
@@ -585,7 +581,7 @@ function TypedExample() {
 ### Upload with Progress
 
 ```typescript
-import { ImageAttachment } from '@torch-ui/components'
+import { ImageAttachment } from "@/components/ImageAttachment";
 import { useState } from 'react'
 
 function UploadWithProgress() {
@@ -638,7 +634,7 @@ function UploadWithProgress() {
 ### Image Cropper Integration
 
 ```typescript
-import { ImageAttachment, ExpandableImage } from '@torch-ui/components'
+import { ImageAttachment, ExpandableImage } from "@/components/ImageAttachment";
 import { useState } from 'react'
 import Cropper from 'react-easy-crop'
 
@@ -688,11 +684,7 @@ function ImageCropper() {
 
 ```typescript
 import { render, screen, fireEvent, waitFor } from '@testing-library/react'
-import {
-  ImageAttachment,
-  ExpandableImage,
-  AttachmentImagePreview
-} from '@torch-ui/components'
+import { ImageAttachment, ExpandableImage, AttachmentImagePreview } from "@/components/ImageAttachment";
 
 describe('ImageAttachment', () => {
   it('renders labels', () => {
@@ -883,10 +875,16 @@ describe('AttachmentImagePreview', () => {
 
 ### Default Styling
 
-- Drop Zone: 200px min-width, 65px height, dashed border
-- Preview: 180px max-width, 65px height, rounded corners
-- Active State: Background and border color change
-- Hover: Expand button overlay with icon
+Matches the *Attachment-Field-1.0 / Pic-Container-1.0* design:
+
+- **Field box** (`ImageAttachment`): a `#f9f9f9` (`background-presentation-form-field-primary`)
+  rounded container holding an optional preview and the drop zone, `gap-[10px]`.
+- **Drop zone**: fills the box (`flex-1`), 65px tall, transparent with a dashed
+  `border-presentation-action-borderstyle` border; drag-active tints it gray.
+- **Preview thumbnail** (`ExpandableImage`): a fixed **65×65** square, `object-cover`, rounded.
+- **Placeholder** (no image): ocean fill (`badge-ocean-subtle`) + dashed `blue-purple-300`
+  border + paperclip icon; on hover it goes gray (`badge-gray-subtle` / `badge-gray`).
+- **Hover (has image)**: a `black/50` overlay with a fullscreen icon + the `expandLabel`.
 
 ## Best Practices