130 lines
4.1 KiB
Markdown
130 lines
4.1 KiB
Markdown
# 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
|