Skip to content

Commit 1eade56

Browse files
authored
feat(translation-widget): two-pane card with copy, count, clear and loading (#71)
1 parent 064455f commit 1eade56

5 files changed

Lines changed: 544 additions & 145 deletions

File tree

‎content/docs/components/translation/translation-widget.mdx‎

Lines changed: 98 additions & 33 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
---
22
title: Translation Widget
3-
description: Side-by-side translation view with an editable target pane, RTL-aware layout, and soft claymorphism styling. Controlled and uncontrolled modes built in.
3+
description: Side-by-side translation card with language pickers, swap, copy, character count, and a loading state. RTL-aware and themed with shadcn tokens.
44
---
55

66
import { PreviewComponents } from "@/components/docs/preview-components";
@@ -94,28 +94,36 @@ export function Translate() {
9494

9595
## Props
9696

97-
| Prop | Type | Required | Description |
98-
| ---------------------- | ------------------------ | -------- | --------------------------------------------------------------------------------------- |
99-
| `locales` | `Locale[]` | No | Locales for the per-pane language pickers; omit to show static chips |
100-
| `sourceLocale` | `string` | No | BCP 47 code of the source locale (e.g. `"en"`); provide to control it |
101-
| `defaultSourceLocale` | `string` | No | Initial source locale when uncontrolled (default: `locales[0]`, else `"en"`) |
102-
| `onSourceLocaleChange` | `(code: string) => void` | No | Callback when the source locale changes |
103-
| `targetLocale` | `string` | No | BCP 47 code of the target locale (e.g. `"fr"`, `"ar"`); provide to control it |
104-
| `defaultTargetLocale` | `string` | No | Initial target locale when uncontrolled (default: `locales[1]`, else `"en"`) |
105-
| `onTargetLocaleChange` | `(code: string) => void` | No | Callback when the target locale changes |
106-
| `sourceText` | `string` | No | Source text — pass this to control the source pane |
107-
| `onSourceChange` | `(text: string) => void` | No | Callback when the source text changes; makes the pane editable |
108-
| `targetText` | `string` | No | Target text — pass this to control the target pane (read-only without `onTargetChange`) |
109-
| `defaultTargetText` | `string` | No | Initial target text when uncontrolled |
110-
| `onTargetChange` | `(text: string) => void` | No | Callback when the target text changes |
111-
| `onSwap` | `() => void` | No | Called after the swap button exchanges locales and texts |
112-
| `sourcePlaceholder` | `string` | No | Placeholder for the source pane |
113-
| `targetPlaceholder` | `string` | No | Placeholder for the target pane |
114-
| `sourceLabel` | `string` | No | Accessible label for the source pane (default: `"Source text"`) |
115-
| `targetLabel` | `string` | No | Accessible label for the target pane (default: `"Target text"`) |
116-
| `readOnlySource` | `boolean` | No | Keep the source pane read-only even with `onSourceChange` |
117-
| `dir` | `"ltr" \| "rtl"` | No | Override the auto-detected layout direction |
118-
| `className` | `string` | No | Additional CSS classes |
97+
| Prop | Type | Required | Description |
98+
| ---------------------- | ----------------------------- | -------- | ---------------------------------------------------------------------------------------- |
99+
| `locales` | `Locale[]` | No | Locales for the per-pane language pickers; omit to show static chips |
100+
| `sourceLocale` | `string` | No | BCP 47 code of the source locale (e.g. `"en"`); provide to control it |
101+
| `defaultSourceLocale` | `string` | No | Initial source locale when uncontrolled (default: `locales[0]`, else `"en"`) |
102+
| `onSourceLocaleChange` | `(code: string) => void` | No | Callback when the source locale changes |
103+
| `targetLocale` | `string` | No | BCP 47 code of the target locale (e.g. `"fr"`, `"ar"`); provide to control it |
104+
| `defaultTargetLocale` | `string` | No | Initial target locale when uncontrolled (default: `locales[1]`, else `"en"`) |
105+
| `onTargetLocaleChange` | `(code: string) => void` | No | Callback when the target locale changes |
106+
| `sourceText` | `string` | No | Source text — pass this to control the source pane |
107+
| `defaultSourceText` | `string` | No | Initial source text when uncontrolled |
108+
| `onSourceChange` | `(text: string) => void` | No | Callback when the source text changes; makes the pane editable |
109+
| `targetText` | `string` | No | Target text — pass this to control the target pane (read-only without `onTargetChange`) |
110+
| `defaultTargetText` | `string` | No | Initial target text when uncontrolled |
111+
| `onTargetChange` | `(text: string) => void` | No | Callback when the target text changes |
112+
| `onSwap` | `() => void` | No | Called after the swap button exchanges locales and texts |
113+
| `sourcePlaceholder` | `string` | No | Placeholder for the source pane |
114+
| `targetPlaceholder` | `string` | No | Placeholder for the target pane |
115+
| `sourceLabel` | `string` | No | Accessible label for the source pane (default: `"Source text"`) |
116+
| `targetLabel` | `string` | No | Accessible label for the target pane (default: `"Target text"`) |
117+
| `readOnlySource` | `boolean` | No | Keep the source pane read-only even with `onSourceChange` |
118+
| `showCount` | `boolean` | No | Show the source character count (default: `true`) |
119+
| `maxLength` | `number` | No | Character limit for both panes; the count shows `n / max` |
120+
| `showClear` | `boolean` | No | Show a clear button under an editable source (default: `true`) |
121+
| `showCopy` | `boolean` | No | Show a copy-to-clipboard button under the target (default: `true`) |
122+
| `onTargetCopy` | `(text: string) => void` | No | Called with the target text after it is copied |
123+
| `loading` | `boolean` | No | Show a skeleton in the target pane and mark it `aria-busy` |
124+
| `classNames` | `TranslationWidgetClassNames` | No | Per-part class overrides: `root`, `header`, `pane`, `textarea`, `footer`, `swap`, `chip` |
125+
| `dir` | `"ltr" \| "rtl"` | No | Override the auto-detected layout direction |
126+
| `className` | `string` | No | Additional CSS classes |
119127

120128
Any other prop — `id`, `data-*`, `aria-*` — is spread onto the root element, and the
121129
ref is forwarded to it.
@@ -178,8 +186,8 @@ or controlled (`sourceLocale` + `onSourceLocaleChange`, same for the target). Wh
178186
## Swap
179187

180188
The swap button between the panes exchanges **both** the locales and the texts —
181-
source ↔ target — and fires `onSwap`. The icon points sideways (⇄) when the panes
182-
sit side by side and rotates to ↕ when they stack on narrow screens. The button
189+
source ↔ target — and fires `onSwap`. It sits in the header bar between the two
190+
language pickers, and its icon spins half a turn on every swap. The button
183191
carries an `aria-label="Swap languages"` and is disabled when any exchanged value
184192
is controlled without a change handler, since the swap could not be applied:
185193

@@ -198,6 +206,59 @@ is controlled without a change handler, since the swap could not be applied:
198206
/>
199207
```
200208

209+
## Toolbar
210+
211+
Each pane ends in a small toolbar. The source shows a live character count —
212+
`n / max` when you pass `maxLength`, turning destructive at the limit — and a clear
213+
button when the pane is editable. The target has a copy button that confirms with a
214+
check and announces "Translation copied to clipboard" to screen readers:
215+
216+
```tsx
217+
<TranslationWidget
218+
sourceLocale="en"
219+
targetLocale="fr"
220+
sourceText={source}
221+
onSourceChange={setSource}
222+
maxLength={500}
223+
onTargetCopy={(text) => analytics.track("translation-copied", { length: text.length })}
224+
/>
225+
```
226+
227+
Turn any of it off with `showCount={false}`, `showClear={false}` or `showCopy={false}`.
228+
229+
## Loading state
230+
231+
While a translation is in flight, pass `loading` to replace the target text with a
232+
pulsing skeleton. The textarea is marked `aria-busy` and copying is disabled:
233+
234+
```tsx
235+
const [loading, setLoading] = useState(false);
236+
237+
async function translate(text: string) {
238+
setLoading(true);
239+
setTarget(await api.translate(text, targetLocale));
240+
setLoading(false);
241+
}
242+
243+
<TranslationWidget loading={loading} /* … */ />;
244+
```
245+
246+
## Customization
247+
248+
Every part takes extra classes through `classNames`, merged after the defaults with
249+
`cn`, so your classes win:
250+
251+
```tsx
252+
<TranslationWidget
253+
classNames={{
254+
root: "rounded-2xl shadow-lg",
255+
header: "bg-muted/50",
256+
textarea: "font-serif text-lg",
257+
swap: "bg-primary text-primary-foreground",
258+
}}
259+
/>
260+
```
261+
201262
## RTL support
202263

203264
When the target locale is an RTL language (`ar`, `he`, `fa`, `ur`, …) or carries an
@@ -212,29 +273,33 @@ Pass `dir` to set the widget's direction explicitly.
212273

213274
## Features
214275

215-
- **Side-by-side panes** — source and target text areas in one responsive row
276+
- **Side-by-side panes** — source and target in one card, stacked on narrow screens
216277
- **Language pickers** — pass `locales` for a Language Switcher per pane; static chips otherwise
217278
- **Swap button** — exchanges both locales and texts, with `onSwap` and an accessible label
218279
- **Editable target** — uncontrolled, or controlled with `targetText` + `onTargetChange` (a controlled target without a handler renders read-only so typed text is never silently dropped)
219280
- **RTL-aware** — per-pane `dir` and `lang` follow each locale; pane order stays fixed
220-
- **Accessible** — labelled textareas, `lang` attributes, visible focus rings
281+
- **Toolbar** — character count with `maxLength`, clear, and copy-to-clipboard
282+
- **Loading state** — skeleton target pane with `aria-busy`
283+
- **Accessible** — labelled textareas, `lang` attributes, visible focus rings, live copy announcement
221284
- **Keyboard support** — Tab between panes, type to translate
222-
- **Claymorphism styling** — soft raised card with recessed, pressed-in textareas
223-
- **Dark mode** — built with Tailwind CSS, dark-mode compatible
285+
- **Themeable** — shadcn tokens (`bg-card`, `border`, `muted`, `ring`), so it follows your theme and dark mode
286+
- **Customizable** — `classNames` for every part
287+
- **Motion** — spring swap icon and copy confirmation, respecting reduced-motion settings
224288
- **Controlled/uncontrolled** — works with or without `targetText`; same for locales
225289

226290
## Design
227291

228-
The widget uses a claymorphism treatment: a large-radius card with a soft drop
229-
shadow and an inner top highlight, and textareas that read as recessed via an
230-
inset shadow. Colours are Tailwind utilities — no CSS-variable tokens — so the
231-
component drops into any project and restyles with `className`.
292+
One card, split into a source pane and a slightly tinted target pane, with both
293+
language pickers and the swap button in a shared header bar — the layout people
294+
know from translation tools. Colors come from shadcn's semantic tokens, so the
295+
widget takes on your theme, radius and dark mode without extra configuration.
232296

233297
## Dependencies
234298

235299
This component uses:
236300

237301
- `clsx` and `tailwind-merge` (bundled as dependencies)
302+
- `lucide-react` for icons and `motion` for the swap and copy animations
238303
- the [Language Switcher](/docs/components/language-switchers/language-switcher) component (pulled in automatically via registry dependencies)
239304

240305
Peer dependencies:

‎src/registry/components/index.ts‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -22,7 +22,7 @@ export { NavBar } from "./navbar";
2222
export type { NavBarProps, NavBarClassNames, NavLink } from "./navbar";
2323

2424
export { TranslationWidget } from "./translation-widget";
25-
export type { TranslationWidgetProps } from "./translation-widget";
25+
export type { TranslationWidgetProps, TranslationWidgetClassNames } from "./translation-widget";
2626

2727
export { LocaleNumber } from "./locale-number";
2828
export type { LocaleNumberProps } from "./locale-number";

0 commit comments

Comments
 (0)