```
This enables:
- CSS targeting for styling overrides
- Testing queries for component selection
- Debug inspection in DevTools
---
## Empty States
> **TL;DR:** Always check for null/empty data and render a graceful fallback.
```tsx
if (!data || data.length === 0) {
return (
{label &&
{label}
}
No data available
);
}
```
Handle all edge cases:
- `null` or `undefined` data
- Empty arrays
- Missing required fields
---
## Value Formatting
> **TL;DR:** Use `formatDisplayValue()` for values and `fieldToLabel()` for auto-labels.
### formatDisplayValue()
```tsx
import { formatDisplayValue } from './utils';
{formatDisplayValue(value)}
```
Handles:
- Large numbers: `1234567` becomes `1.2M`
- Thousands: `12345` becomes `12.3K`
- Null/undefined: displays `--`
- Booleans: `Yes`/`No`
- Dates: Localized format
### fieldToLabel()
```tsx
import { fieldToLabel } from './utils';
// Auto-generate labels from field names
fieldToLabel('totalRevenue') // "Total Revenue"
fieldToLabel('order_count') // "Order Count"
fieldToLabel('avgValue') // "Avg Value"
```
### Common Pattern
```tsx
const label = block.label || fieldToLabel(block.binding?.field || '');
```
---
## Static Variants
> **TL;DR:** Export both `ComponentName` (dynamic) and `StaticComponent` (standalone).
### Dynamic Component (DSL-driven)
Used by the LiquidUI renderer. Receives `LiquidComponentProps`:
```tsx
export function DataTable({ block, data }: LiquidComponentProps) {
const resolvedData = resolveBinding(block.binding, data);
// ...
}
```
### Static Component (standalone)
Used directly in React apps with explicit props:
```tsx
interface StaticTableProps {
data: Record
[];
columns?: string[];
title?: string;
sortable?: boolean;
}
export function StaticTable({ data, columns, title, sortable }: StaticTableProps) {
// No binding resolution needed
}
```
### Export Pattern
```tsx
// In component file
export { ComponentName, StaticComponent };
export default ComponentName;
// In index.ts - register for DSL usage
export const liquidComponents = {
typename: ComponentName,
};
```
---
## SSR Handling
> **TL;DR:** Use `isBrowser` check for components requiring browser APIs.
```tsx
import { isBrowser } from './utils';
export function ChartComponent({ block, data }: LiquidComponentProps) {
if (!isBrowser) {
return (
[Chart placeholder - {data.length} points]
);
}
// Browser-only rendering (Recharts, etc.)
return (
...
);
}
```
---
## Checklist
Before submitting a new component, verify:
- [ ] File follows standard structure with section headers
- [ ] Uses `tokens` for all style values (no hardcoded colors/spacing)
- [ ] Has `data-liquid-type` attribute on root element
- [ ] Handles empty/null data states
- [ ] Uses `formatDisplayValue()` for value display
- [ ] Uses `fieldToLabel()` for auto-labels
- [ ] Has SSR placeholder if browser-dependent
- [ ] Includes both dynamic and static variants
- [ ] Registered in `liquidComponents` map
- [ ] Exported from `index.ts`
---
## Quick Reference
### Imports
```tsx
import type { LiquidComponentProps } from './utils';
import {
tokens,
chartColors,
cardStyles,
buttonStyles,
inputStyles,
mergeStyles,
getLayoutStyles,
getBlockColor,
formatDisplayValue,
fieldToLabel,
generateId,
isBrowser,
} from './utils';
import { resolveBinding } from '../data-context';
```
### Props Interface
```tsx
interface LiquidComponentProps {
block: Block; // Parsed block from DSL
data: DataContext; // Data for binding resolution
children?: ReactNode;
className?: string;
}
```
### Block Properties
```tsx
const value = resolveBinding(block.binding, data);
const label = block.label || fieldToLabel(block.binding?.field || '');
const color = getBlockColor(block);
const layoutStyles = getLayoutStyles(block);
const columns = block.columns;
```