README
¶
Table preference contract v1
This package defines and validates table presentation preferences. It contains no store, listener, MCP server, or business-specific table definitions.
Forge defaults to a browser-local adapter. Hosts may inject an external adapter
with async get(key), set(key, preferences), and reset(key) methods. The Go
client validates both outbound preferences and inbound external responses.
An external MCP integration implements Transport.Call and maps these operations
to its own tool names. It handles MCP initialization/envelopes/authentication.
The normalized payload contract is:
| Operation | Request | Response |
|---|---|---|
| get | {"key":"..."} |
null or the preference JSON object |
| set | {"key":"...","preferences":{...}} |
{} |
| reset | {"key":"..."} |
{} |
Preferences have version: 1, ordered columns containing id, optional
visible, numeric width, displayName, align, and tooltip; optional
sort: {columnId, direction}, density: compact|normal, and frozenColumnIds.
The contract is intentionally limited to user choices: no row data, handlers,
links, tool definitions, authorization state, or arbitrary CSS is persisted.
Limits: 64 KiB payloads, 256 columns/frozen IDs, 256-character IDs/display names, 1024-character tooltips, widths 24–4096 pixels, and opaque keys up to 512 characters. IDs must be unique; sort is asc/desc; alignment is left/center/right. Unknown fields and versions are rejected. The JSON schema is shipped alongside the Go validation code for external implementations.
The host must scope keys by workspace and authenticated principal. A raw table key is not an authorization boundary. External servers derive identity from trusted authentication, not a user ID inside a preference payload. Adapter failures must not silently fall back to another account's local preferences.
On hydration, Forge reconciles IDs against current metadata, ignores removed columns, appends newly introduced columns, and preserves non-excludable and authorization constraints. Preferences never authorize access to a column.
Run go test ./service/ui/tablepreference.
Workspace configuration
Optional extension/forge/preferences.yaml:
version: 1
tablePreferences:
adapter: browser
namespace: personal-tables
For an externally shipped MCP provider:
version: 1
tablePreferences:
adapter: mcp
mcp:
serverRef: user-preferences
tools:
get: table_preferences_get
set: table_preferences_set
reset: table_preferences_reset
LoadConfig validates the declaration. The host publishes its
tablePreferences value and passes it as connectorConfig.tablePreferences
to Forge. For MCP it resolves the already-configured server and injects
services.tablePreferences; no service is started by this package. Browser is
the missing-file default. Invalid MCP configuration or an unavailable configured
provider is an error, never an implicit fallback to browser storage.
Documentation
¶
Overview ¶
Package tablepreference validates presentation preferences exchanged with an external adapter. It does not implement storage or host an MCP server.
Index ¶
Constants ¶
const ConfigPath = "extension/forge/preferences.yaml"
const MaxBytes = 64 << 10
const Version = 1
Variables ¶
var Schema []byte
Schema describes the portable preference document. Validate additionally enforces unique column IDs, key hygiene and the encoded payload size limit.
Functions ¶
func Validate ¶
func Validate(p *Preferences) error
func ValidateKey ¶
ValidateKey treats the key as opaque. The host must namespace it by workspace and authenticated principal; it must not trust a caller-supplied user ID.
Types ¶
type AdapterConfig ¶
type Column ¶
type Column struct {
ID string `json:"id"`
Visible *bool `json:"visible,omitempty"`
Width *float64 `json:"width,omitempty"`
DisplayName *string `json:"displayName,omitempty"`
Align string `json:"align,omitempty"`
Tooltip *string `json:"tooltip,omitempty"`
}
Column order in this slice is the user's preferred display order.
type Config ¶
type Config struct {
Version int `json:"version" yaml:"version"`
TablePreferences AdapterConfig `json:"tablePreferences" yaml:"tablePreferences"`
}
func DefaultConfig ¶
func DefaultConfig() Config
func LoadConfig ¶
LoadConfig reads a workspace's optional declaration. Missing configuration selects browser storage; malformed explicit configuration fails visibly.
type MCP ¶
type MCP struct {
ServerRef string `json:"serverRef" yaml:"serverRef"`
Tools Tools `json:"tools" yaml:"tools"`
}
MCP selects an existing host-configured server, never a credential or URL.
type Preferences ¶
type Preferences struct {
Version int `json:"version"`
Columns []Column `json:"columns,omitempty"`
Sort *Sort `json:"sort,omitempty"`
Density string `json:"density,omitempty"`
FrozenColumnIDs []string `json:"frozenColumnIds,omitempty"`
}
func Decode ¶
func Decode(data []byte) (*Preferences, error)
Decode rejects runtime metadata, row values, and other unknown fields.
type Request ¶
type Request struct {
Key string `json:"key"`
Preferences *Preferences `json:"preferences,omitempty"`
}
type Transport ¶
type Transport interface {
Call(context.Context, string, json.RawMessage) (json.RawMessage, error)
}
Transport maps get/set/reset operations to external MCP tools (or another host adapter). It unwraps the MCP envelope into the JSON contract below. Authentication, workspace authorization and persistence belong to the host.
Source Files