Skip to content

Commit fa54cc1

Browse files
Copilothotlong
Copilot
and
hotlong
committed
Add missing documentation files for mapping and block schemas
Co-authored-by: hotlong <50353452+hotlong@users.noreply.github.com>
1 parent 8bd3729 commit fa54cc1

File tree

2 files changed

+246
-0
lines changed

2 files changed

+246
-0
lines changed

‎content/docs/references/data/mapping.mdx‎

Lines changed: 94 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,94 @@
1+
---
2+
title: Mapping
3+
description: Mapping protocol schemas
4+
---
5+
6+
# Mapping
7+
8+
<Callout type="info">
9+
**Source:** `packages/spec/src/data/mapping.zod.ts`
10+
</Callout>
11+
12+
## TypeScript Usage
13+
14+
```typescript
15+
import { MappingSchema, FieldMappingSchema, TransformType } from '@objectstack/spec/data';
16+
import type { Mapping, FieldMapping } from '@objectstack/spec/data';
17+
18+
// Validate data
19+
const result = MappingSchema.parse(data);
20+
```
21+
22+
---
23+
24+
## FieldMapping
25+
26+
### Properties
27+
28+
| Property | Type | Required | Description |
29+
| :--- | :--- | :--- | :--- |
30+
| **source** | `string \| string[]` | ✅ | Source column header(s) |
31+
| **target** | `string \| string[]` | ✅ | Target object field(s) |
32+
| **transform** | `Enum<'none' \| 'constant' \| 'lookup' \| 'split' \| 'join' \| 'javascript' \| 'map'>` | optional | Transformation type (default: 'none') |
33+
| **params** | `object` | optional | Configuration for transform |
34+
35+
### Transform Params Properties
36+
37+
| Property | Type | Required | Description |
38+
| :--- | :--- | :--- | :--- |
39+
| **value** | `any` | optional | Value for constant transform |
40+
| **object** | `string` | optional | Lookup Object for lookup transform |
41+
| **fromField** | `string` | optional | Match on field (e.g. "name") for lookup |
42+
| **toField** | `string` | optional | Value to take (e.g. "_id") for lookup |
43+
| **autoCreate** | `boolean` | optional | Create if missing for lookup |
44+
| **valueMap** | `Record<string, any>` | optional | Value mapping for map transform (e.g. { "Open": "draft" }) |
45+
| **separator** | `string` | optional | Separator for split/join transforms |
46+
47+
---
48+
49+
## Mapping
50+
51+
Defines a reusable data mapping configuration for ETL operations.
52+
53+
**NAMING CONVENTION:**
54+
Mapping names are machine identifiers and must be lowercase snake_case.
55+
56+
**Examples of good mapping names:**
57+
- `salesforce_to_crm`
58+
- `csv_import_contacts`
59+
- `api_sync_orders`
60+
61+
**Examples of bad mapping names (will be rejected):**
62+
- `SalesforceToCRM` (PascalCase)
63+
- `CSV Import` (spaces)
64+
65+
### Properties
66+
67+
| Property | Type | Required | Description |
68+
| :--- | :--- | :--- | :--- |
69+
| **name** | `string` | ✅ | Mapping unique name (lowercase snake_case) |
70+
| **label** | `string` | optional | Human readable label |
71+
| **sourceFormat** | `Enum<'csv' \| 'json' \| 'xml' \| 'sql'>` | optional | Source data format (default: 'csv') |
72+
| **targetObject** | `string` | ✅ | Target Object Name |
73+
| **fieldMapping** | `object[]` | ✅ | Column Mappings |
74+
| **mode** | `Enum<'insert' \| 'update' \| 'upsert'>` | optional | Data operation mode (default: 'insert') |
75+
| **upsertKey** | `string[]` | optional | Fields to match for upsert (e.g. email) |
76+
| **extractQuery** | `object` | optional | Query to run for export only |
77+
| **errorPolicy** | `Enum<'skip' \| 'abort' \| 'retry'>` | optional | Error handling strategy (default: 'skip') |
78+
| **batchSize** | `number` | optional | Batch size for operations (default: 1000) |
79+
80+
---
81+
82+
## TransformType
83+
84+
Built-in helpers for converting data during import.
85+
86+
### Allowed Values
87+
88+
* `none` - Direct copy
89+
* `constant` - Use a hardcoded value
90+
* `lookup` - Resolve FK (Name → ID)
91+
* `split` - "John Doe" → ["John", "Doe"]
92+
* `join` - ["John", "Doe"] → "John Doe"
93+
* `javascript` - Custom script (Review security!)
94+
* `map` - Value mapping (e.g. "Active" → "active")

‎content/docs/references/ui/block.mdx‎

Lines changed: 152 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,152 @@
1+
---
2+
title: Block
3+
description: Block protocol schemas
4+
---
5+
6+
# Block
7+
8+
<Callout type="info">
9+
**Source:** `packages/spec/src/ui/block.zod.ts`
10+
</Callout>
11+
12+
## TypeScript Usage
13+
14+
```typescript
15+
import {
16+
PageHeaderProps,
17+
PageTabsProps,
18+
PageCardProps,
19+
RecordDetailsProps,
20+
RecordRelatedListProps,
21+
RecordHighlightsProps,
22+
ComponentPropsMap
23+
} from '@objectstack/spec/ui';
24+
25+
// Validate data
26+
const result = PageHeaderProps.parse(data);
27+
```
28+
29+
---
30+
31+
## Component Props Map
32+
33+
Maps Component Type to its Property Schema. Available component types:
34+
35+
### Structure Components
36+
37+
* `page:header`
38+
* `page:tabs`
39+
* `page:card`
40+
* `page:footer`
41+
* `page:sidebar`
42+
* `page:accordion`
43+
* `page:section`
44+
45+
### Record Components
46+
47+
* `record:details`
48+
* `record:related_list`
49+
* `record:highlights`
50+
* `record:activity`
51+
* `record:chatter`
52+
* `record:path`
53+
54+
### Navigation Components
55+
56+
* `app:launcher`
57+
* `nav:menu`
58+
* `nav:breadcrumb`
59+
60+
### Utility Components
61+
62+
* `global:search`
63+
* `global:notifications`
64+
* `user:profile`
65+
66+
### AI Components
67+
68+
* `ai:chat_window`
69+
* `ai:suggestion`
70+
71+
---
72+
73+
## PageHeaderProps
74+
75+
### Properties
76+
77+
| Property | Type | Required | Description |
78+
| :--- | :--- | :--- | :--- |
79+
| **title** | `string` | ✅ | Page title |
80+
| **subtitle** | `string` | optional | Page subtitle |
81+
| **icon** | `string` | optional | Icon name |
82+
| **breadcrumb** | `boolean` | optional | Show breadcrumb (default: true) |
83+
| **actions** | `string[]` | optional | Action IDs to show in header |
84+
85+
---
86+
87+
## PageTabsProps
88+
89+
### Properties
90+
91+
| Property | Type | Required | Description |
92+
| :--- | :--- | :--- | :--- |
93+
| **type** | `Enum<'line' \| 'card' \| 'pill'>` | optional | Tab type (default: 'line') |
94+
| **position** | `Enum<'top' \| 'left'>` | optional | Tab position (default: 'top') |
95+
| **items** | `object[]` | ✅ | Tab items |
96+
97+
### Tab Item Properties
98+
99+
| Property | Type | Required | Description |
100+
| :--- | :--- | :--- | :--- |
101+
| **label** | `string` | ✅ | Tab label |
102+
| **icon** | `string` | optional | Tab icon |
103+
| **children** | `any[]` | ✅ | Child components |
104+
105+
---
106+
107+
## PageCardProps
108+
109+
### Properties
110+
111+
| Property | Type | Required | Description |
112+
| :--- | :--- | :--- | :--- |
113+
| **title** | `string` | optional | Card title |
114+
| **bordered** | `boolean` | optional | Show border (default: true) |
115+
| **actions** | `string[]` | optional | Action IDs |
116+
| **children** | `any[]` | ✅ | Card content |
117+
118+
---
119+
120+
## RecordDetailsProps
121+
122+
### Properties
123+
124+
| Property | Type | Required | Description |
125+
| :--- | :--- | :--- | :--- |
126+
| **columns** | `Enum<'1' \| '2' \| '3' \| '4'>` | optional | Number of columns (default: '2') |
127+
| **layout** | `Enum<'auto' \| 'custom'>` | optional | Layout mode (default: 'auto') |
128+
| **sections** | `string[]` | optional | Section IDs to show (for custom layout) |
129+
130+
---
131+
132+
## RecordRelatedListProps
133+
134+
### Properties
135+
136+
| Property | Type | Required | Description |
137+
| :--- | :--- | :--- | :--- |
138+
| **objectName** | `string` | ✅ | Related object name |
139+
| **relationshipField** | `string` | ✅ | Field on related object that points to this record |
140+
| **columns** | `string[]` | ✅ | Fields to display |
141+
| **sort** | `string` | optional | Sort order |
142+
| **limit** | `number` | optional | Maximum number of records (default: 5) |
143+
144+
---
145+
146+
## RecordHighlightsProps
147+
148+
### Properties
149+
150+
| Property | Type | Required | Description |
151+
| :--- | :--- | :--- | :--- |
152+
| **fields** | `string[]` | ✅ | Key fields to highlight (minimum 1, maximum 7) |

0 commit comments

Comments
 (0)