Add contentFormatter for tooltips and error/warning bubbles, format i18n texts, add missing high-dose warning
This commit is contained in:
129
docs/README.content-formater.md
Normal file
129
docs/README.content-formater.md
Normal file
@@ -0,0 +1,129 @@
|
||||
# Content Formatting Usage Guide
|
||||
|
||||
The `contentFormatter` utility (`src/utils/contentFormatter.tsx`) provides markdown-style formatting for various UI content throughout the application.
|
||||
|
||||
## Supported Formatting
|
||||
|
||||
- **Bold:** `**text**` → **text**
|
||||
- **Italic:** `*text*` → *text*
|
||||
- **Bold + Italic:** `***text***` → ***text***
|
||||
- **Underline:** `__text__` → <u>text</u>
|
||||
- **Line breaks:** `\n` (use `\\n` in translation strings)
|
||||
- **Links:** `[text](url)` → clickable link with yellow underline
|
||||
|
||||
## Current Usage
|
||||
|
||||
### 1. Tooltips (✅ Already Implemented)
|
||||
|
||||
All tooltips in `settings.tsx` use `formatContent()`:
|
||||
|
||||
```tsx
|
||||
import { formatContent } from '../utils/contentFormatter';
|
||||
|
||||
<TooltipContent>
|
||||
<p className="text-xs max-w-xs">
|
||||
{formatContent(t('myTooltip'))}
|
||||
</p>
|
||||
</TooltipContent>
|
||||
```
|
||||
|
||||
**Example translation:**
|
||||
```typescript
|
||||
myTooltip: "This is a tooltip.\\n\\n**Important:** Some key info.\\n\\n***Default:*** 11h."
|
||||
```
|
||||
|
||||
## Potential Future Usage
|
||||
|
||||
### 2. Error/Warning Messages in Form Fields
|
||||
|
||||
The formatter can be applied to `errorMessage` and `warningMessage` props in form components:
|
||||
|
||||
**Current implementation** (plain text):
|
||||
```tsx
|
||||
<FormNumericInput
|
||||
errorMessage="Value must be between 5 and 50"
|
||||
warningMessage="Value is outside typical range"
|
||||
/>
|
||||
```
|
||||
|
||||
**With formatting** (enhanced):
|
||||
```tsx
|
||||
import { formatContent } from '../utils/contentFormatter';
|
||||
|
||||
// In FormNumericInput component (form-numeric-input.tsx):
|
||||
{hasError && isFocused && errorMessage && (
|
||||
<div className="absolute top-full left-0 w-full mt-1 p-2 bg-red-100 dark:bg-red-900/20 border border-red-300 dark:border-red-700 rounded text-xs text-red-800 dark:text-red-200 z-50">
|
||||
{formatContent(errorMessage)}
|
||||
</div>
|
||||
)}
|
||||
```
|
||||
|
||||
**Example with formatting:**
|
||||
```typescript
|
||||
errorMessage={t('errorEliminationHalfLife')}
|
||||
|
||||
// In translations:
|
||||
errorEliminationHalfLife: "**Invalid value.**\\n\\nHalf-life must be between **5h** and **50h**.\\n\\nSee [reference ranges](https://example.com)."
|
||||
```
|
||||
|
||||
### 3. Info Boxes
|
||||
|
||||
Static info boxes (like `advancedSettingsWarning`) could support formatting:
|
||||
|
||||
**Current:**
|
||||
```tsx
|
||||
<p className="text-yellow-800 dark:text-yellow-200">
|
||||
{t('advancedSettingsWarning')}
|
||||
</p>
|
||||
```
|
||||
|
||||
**With formatting:**
|
||||
```tsx
|
||||
<div className="text-yellow-800 dark:text-yellow-200">
|
||||
{formatContent(t('advancedSettingsWarning'))}
|
||||
</div>
|
||||
```
|
||||
|
||||
**Example translation:**
|
||||
```typescript
|
||||
advancedSettingsWarning: "⚠️ **Warning:**\\n\\nThese parameters affect simulation accuracy.\\n\\nOnly adjust if you have ***specific clinical data*** or research references."
|
||||
```
|
||||
|
||||
### 4. Modal Content
|
||||
|
||||
Dialog/modal descriptions could use formatting for better readability:
|
||||
|
||||
```tsx
|
||||
<DialogDescription>
|
||||
{formatContent(t('deleteConfirmation'))}
|
||||
</DialogDescription>
|
||||
|
||||
// Translation:
|
||||
deleteConfirmation: "Are you sure you want to delete this data?\\n\\n**This action cannot be undone.**\\n\\nConsider [exporting a backup](export) first."
|
||||
```
|
||||
|
||||
## Implementation Checklist
|
||||
|
||||
To add formatting support to a component:
|
||||
|
||||
1. ✅ Import the formatter: `import { formatContent } from '../utils/contentFormatter'`
|
||||
2. ✅ Wrap the content: `{formatContent(text)}`
|
||||
3. ✅ Update translations to use `\\n`, `**bold**`, `*italic*`, etc.
|
||||
4. ✅ Test in both light and dark themes
|
||||
5. ✅ Ensure links open in new tabs (already handled by formatter)
|
||||
|
||||
## Notes
|
||||
|
||||
- The formatter returns React nodes, so it should replace the content, not be nested inside `{}`
|
||||
- Links automatically get `target="_blank"` and `rel="noopener noreferrer"`
|
||||
- Link color is yellow (`text-yellow-300`) to maintain visibility in dark themes
|
||||
- Line breaks use `\\n` in translation files (double backslash for escaping)
|
||||
- The formatter is safe for user-generated content (doesn't execute scripts)
|
||||
|
||||
## Benefits
|
||||
|
||||
- **Improved readability:** Structure complex information with line breaks and emphasis
|
||||
- **Consistency:** Unified formatting across tooltips, errors, warnings, and info boxes
|
||||
- **Accessibility:** Links and emphasis improve screen reader experience
|
||||
- **Maintainability:** Simple markdown-style syntax in translation files
|
||||
- **I18n friendly:** All formatting stays in translation strings, easy to translate
|
||||
Reference in New Issue
Block a user