Skip to content

Add missing documentation files for mapping and block schemas #353

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
hotlong merged 2 commits into from
Jan 28, 2026
Merged

Add missing documentation files for mapping and block schemas #353

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
8bd3729
Initial plan
Copilot Jan 28, 2026
fa54cc1
Add missing documentation files for mapping and block schemas
Copilot Jan 28, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
94 changes: 94 additions & 0 deletions content/docs/references/data/mapping.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,94 @@
---
title: Mapping
description: Mapping protocol schemas
---

# Mapping

<Callout type="info">
**Source:** `packages/spec/src/data/mapping.zod.ts`
</Callout>

## TypeScript Usage

```typescript
import { MappingSchema, FieldMappingSchema, TransformType } from '@objectstack/spec/data';
import type { Mapping, FieldMapping } from '@objectstack/spec/data';

// Validate data
const result = MappingSchema.parse(data);
```
Comment on lines +14 to +20

Copilot AI Jan 28, 2026

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The TypeScript Usage example imports MappingSchema, FieldMappingSchema, TransformType, Mapping, and FieldMapping from @objectstack/spec/data, but packages/spec/src/data/index.ts does not currently re-export mapping.zod.ts, so this import path will fail. Either update the data index to export these symbols or adjust the example to import directly from the mapping.zod module so that the snippet reflects the actual public API.

Copilot uses AI. Check for mistakes.

---

## FieldMapping

### Properties

| Property | Type | Required | Description |
| :--- | :--- | :--- | :--- |
| **source** | `string \| string[]` | ✅ | Source column header(s) |
| **target** | `string \| string[]` | ✅ | Target object field(s) |
| **transform** | `Enum<'none' \| 'constant' \| 'lookup' \| 'split' \| 'join' \| 'javascript' \| 'map'>` | optional | Transformation type (default: 'none') |
| **params** | `object` | optional | Configuration for transform |
Comment on lines +28 to +33

Copilot AI Jan 28, 2026

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

In the FieldMapping properties table, each row starts with || instead of the single leading | used elsewhere in the docs, which will prevent this table from rendering correctly as Markdown. Please update the header and data rows here to use a single | so the table formats consistently with other reference pages.

Copilot uses AI. Check for mistakes.

### Transform Params Properties

| Property | Type | Required | Description |
| :--- | :--- | :--- | :--- |
| **value** | `any` | optional | Value for constant transform |
| **object** | `string` | optional | Lookup Object for lookup transform |
| **fromField** | `string` | optional | Match on field (e.g. "name") for lookup |
| **toField** | `string` | optional | Value to take (e.g. "_id") for lookup |
| **autoCreate** | `boolean` | optional | Create if missing for lookup |
| **valueMap** | `Record<string, any>` | optional | Value mapping for map transform (e.g. { "Open": "draft" }) |
| **separator** | `string` | optional | Separator for split/join transforms |

Comment on lines +37 to +46

Copilot AI Jan 28, 2026

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The Transform Params Properties table also uses || at the start of each row, which is inconsistent with the rest of the documentation and likely breaks table rendering. Align this table with the standard Markdown table syntax by using a single leading | for the header, separator, and data rows.

Copilot uses AI. Check for mistakes.
---

## Mapping

Defines a reusable data mapping configuration for ETL operations.

**NAMING CONVENTION:**
Mapping names are machine identifiers and must be lowercase snake_case.

**Examples of good mapping names:**
- `salesforce_to_crm`
- `csv_import_contacts`
- `api_sync_orders`

**Examples of bad mapping names (will be rejected):**
- `SalesforceToCRM` (PascalCase)
- `CSV Import` (spaces)

### Properties

| Property | Type | Required | Description |
| :--- | :--- | :--- | :--- |
| **name** | `string` | ✅ | Mapping unique name (lowercase snake_case) |
| **label** | `string` | optional | Human readable label |
| **sourceFormat** | `Enum<'csv' \| 'json' \| 'xml' \| 'sql'>` | optional | Source data format (default: 'csv') |
| **targetObject** | `string` | ✅ | Target Object Name |
| **fieldMapping** | `object[]` | ✅ | Column Mappings |
| **mode** | `Enum<'insert' \| 'update' \| 'upsert'>` | optional | Data operation mode (default: 'insert') |
| **upsertKey** | `string[]` | optional | Fields to match for upsert (e.g. email) |
| **extractQuery** | `object` | optional | Query to run for export only |
Comment on lines +67 to +76

Copilot AI Jan 28, 2026

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The Mapping properties table currently has || at the beginning of the header and row lines, unlike other reference docs that use a single |, which will cause the table to render incorrectly. Please normalize this to standard Markdown table syntax so the schema properties render properly.

Copilot uses AI. Check for mistakes.
| **errorPolicy** | `Enum<'skip' \| 'abort' \| 'retry'>` | optional | Error handling strategy (default: 'skip') |
| **batchSize** | `number` | optional | Batch size for operations (default: 1000) |

---

## TransformType

Built-in helpers for converting data during import.

### Allowed Values

* `none` - Direct copy
* `constant` - Use a hardcoded value
* `lookup` - Resolve FK (Name → ID)
* `split` - "John Doe" → ["John", "Doe"]
* `join` - ["John", "Doe"] → "John Doe"
* `javascript` - Custom script (Review security!)
* `map` - Value mapping (e.g. "Active" → "active")
152 changes: 152 additions & 0 deletions content/docs/references/ui/block.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,152 @@
---
title: Block
description: Block protocol schemas
---

# Block

<Callout type="info">
**Source:** `packages/spec/src/ui/block.zod.ts`
</Callout>

## TypeScript Usage

```typescript
import {
PageHeaderProps,
PageTabsProps,
PageCardProps,
RecordDetailsProps,
RecordRelatedListProps,
RecordHighlightsProps,
ComponentPropsMap
} from '@objectstack/spec/ui';

// Validate data
const result = PageHeaderProps.parse(data);
```

---

## Component Props Map

Maps Component Type to its Property Schema. Available component types:

### Structure Components

* `page:header`
* `page:tabs`
* `page:card`
* `page:footer`
* `page:sidebar`
* `page:accordion`
* `page:section`

### Record Components

* `record:details`
* `record:related_list`
* `record:highlights`
* `record:activity`
* `record:chatter`
* `record:path`

### Navigation Components

* `app:launcher`
* `nav:menu`
* `nav:breadcrumb`

### Utility Components

* `global:search`
* `global:notifications`
* `user:profile`

### AI Components

* `ai:chat_window`
* `ai:suggestion`

---

## PageHeaderProps

### Properties

| Property | Type | Required | Description |
| :--- | :--- | :--- | :--- |
| **title** | `string` | ✅ | Page title |
| **subtitle** | `string` | optional | Page subtitle |
| **icon** | `string` | optional | Icon name |
| **breadcrumb** | `boolean` | optional | Show breadcrumb (default: true) |
| **actions** | `string[]` | optional | Action IDs to show in header |
Comment on lines +77 to +83

Copilot AI Jan 28, 2026

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

In the PageHeaderProps properties table, all rows begin with || rather than a single |, which is inconsistent with other docs and will prevent the Markdown table from rendering correctly. Please switch these rows (header, separator, and data) to use a single leading |.

Copilot uses AI. Check for mistakes.

---

## PageTabsProps

### Properties

| Property | Type | Required | Description |
| :--- | :--- | :--- | :--- |
| **type** | `Enum<'line' \| 'card' \| 'pill'>` | optional | Tab type (default: 'line') |
| **position** | `Enum<'top' \| 'left'>` | optional | Tab position (default: 'top') |
| **items** | `object[]` | ✅ | Tab items |

Comment on lines +91 to +96

Copilot AI Jan 28, 2026

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The PageTabsProps properties table also uses || at the start of each row instead of a single |, which will break the table formatting in the rendered docs. Update this table to match the standard Markdown table syntax used elsewhere in the reference docs.

Copilot uses AI. Check for mistakes.
### Tab Item Properties

| Property | Type | Required | Description |
| :--- | :--- | :--- | :--- |
| **label** | `string` | ✅ | Tab label |
| **icon** | `string` | optional | Tab icon |
| **children** | `any[]` | ✅ | Child components |
Comment on lines +99 to +103

Copilot AI Jan 28, 2026

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

In the Tab Item Properties table, the header and data rows start with || rather than a single |, so the table will not render correctly. Please adjust these rows to use a single leading | to be consistent with the rest of the documentation.

Copilot uses AI. Check for mistakes.

---

## PageCardProps

### Properties

| Property | Type | Required | Description |
| :--- | :--- | :--- | :--- |
| **title** | `string` | optional | Card title |
| **bordered** | `boolean` | optional | Show border (default: true) |
| **actions** | `string[]` | optional | Action IDs |
| **children** | `any[]` | ✅ | Card content |
Comment on lines +111 to +116

Copilot AI Jan 28, 2026

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The PageCardProps properties table is using || at the beginning of each row instead of the standard single |, which is likely to break Markdown table rendering. This should be updated to use a single leading | for the header, separator, and all data rows.

Copilot uses AI. Check for mistakes.

---

## RecordDetailsProps

### Properties

| Property | Type | Required | Description |
| :--- | :--- | :--- | :--- |
| **columns** | `Enum<'1' \| '2' \| '3' \| '4'>` | optional | Number of columns (default: '2') |
| **layout** | `Enum<'auto' \| 'custom'>` | optional | Layout mode (default: 'auto') |
| **sections** | `string[]` | optional | Section IDs to show (for custom layout) |
Comment on lines +124 to +128

Copilot AI Jan 28, 2026

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

For the RecordDetailsProps properties table, each row begins with || instead of a single |, making the table inconsistent with others and potentially invalid Markdown. Please normalize these rows to use a single leading |.

Copilot uses AI. Check for mistakes.

---

## RecordRelatedListProps

### Properties

| Property | Type | Required | Description |
| :--- | :--- | :--- | :--- |
| **objectName** | `string` | ✅ | Related object name |
| **relationshipField** | `string` | ✅ | Field on related object that points to this record |
| **columns** | `string[]` | ✅ | Fields to display |
| **sort** | `string` | optional | Sort order |
| **limit** | `number` | optional | Maximum number of records (default: 5) |
Comment on lines +136 to +142

Copilot AI Jan 28, 2026

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The RecordRelatedListProps properties table also has rows starting with || rather than a single |, which will interfere with proper table rendering. Update the header and all data rows here to use a single leading | as in other reference tables.

Copilot uses AI. Check for mistakes.

---

## RecordHighlightsProps

### Properties

| Property | Type | Required | Description |
| :--- | :--- | :--- | :--- |
| **fields** | `string[]` | ✅ | Key fields to highlight (minimum 1, maximum 7) |
Comment on lines +150 to +152

Copilot AI Jan 28, 2026

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

In the RecordHighlightsProps properties table, the header and data rows start with ||, which is inconsistent with the standard Markdown table syntax used elsewhere and will likely break rendering. Please change these to use a single leading |.

Copilot uses AI. Check for mistakes.