@object-ui/react 3.0.3 → 3.1.0

package/src/spec-bridge/bridges/dashboard.ts

@@ -0,0 +1,180 @@
+/**
+ * ObjectUI
+ * Copyright (c) 2024-present ObjectStack Inc.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+import type { SchemaNode } from '@object-ui/core';
+import type { BridgeContext, BridgeFn } from '../types';
+
+interface DashboardWidget {
+  title?: string;
+  description?: string;
+  type?: string;
+  chartConfig?: any;
+  colorVariant?: string;
+  actionUrl?: string;
+  actionType?: string;
+  actionIcon?: string;
+  object?: string;
+  filter?: any;
+  categoryField?: string;
+  valueField?: string;
+  aggregate?: string;
+  measures?: any[];
+  layout?: any;
+  options?: any;
+  responsive?: any;
+  aria?: { ariaLabel?: string; ariaDescribedBy?: string; role?: string };
+}
+
+interface DashboardHeader {
+  showTitle?: boolean;
+  showDescription?: boolean;
+  actions?: Array<{
+    label: string;
+    actionUrl?: string;
+    actionType?: string;
+    icon?: string;
+  }>;
+  [key: string]: any;
+}
+
+interface GlobalFilter {
+  field: string;
+  label?: string;
+  type?: string;
+  options?: string[];
+  optionsFrom?: {
+    object: string;
+    valueField: string;
+    labelField?: string;
+    filter?: any;
+  };
+  defaultValue?: any;
+  scope?: string;
+  targetWidgets?: string[];
+}
+
+interface DashboardSpec {
+  name?: string;
+  label?: string;
+  description?: string;
+  widgets?: DashboardWidget[];
+  globalFilters?: GlobalFilter[];
+  header?: DashboardHeader;
+  // P1.3 additions
+  refreshInterval?: number;
+  dateRange?: {
+    field?: string;
+    defaultRange?: string;
+    allowCustomRange?: boolean;
+  };
+  aria?: { ariaLabel?: string; ariaDescribedBy?: string; role?: string };
+  performance?: any;
+}
+
+function mapWidget(widget: DashboardWidget, index: number): SchemaNode {
+  const node: SchemaNode = {
+    type: widget.type ?? 'chart',
+    id: `widget-${index}`,
+  };
+
+  if (widget.title) node.title = widget.title;
+  if (widget.description) node.description = widget.description;
+  if (widget.chartConfig) node.chartConfig = widget.chartConfig;
+  if (widget.colorVariant) node.colorVariant = widget.colorVariant;
+  if (widget.actionUrl) node.actionUrl = widget.actionUrl;
+  if (widget.actionType) node.actionType = widget.actionType;
+  if (widget.actionIcon) node.actionIcon = widget.actionIcon;
+  if (widget.object) node.object = widget.object;
+  if (widget.filter) node.filter = widget.filter;
+  if (widget.categoryField) node.categoryField = widget.categoryField;
+  if (widget.valueField) node.valueField = widget.valueField;
+  if (widget.aggregate) node.aggregate = widget.aggregate;
+  if (widget.measures) node.measures = widget.measures;
+  if (widget.layout) node.layout = widget.layout;
+  if (widget.options) node.options = widget.options;
+  if (widget.responsive) node.responsive = widget.responsive;
+  if (widget.aria) node.aria = widget.aria;
+
+  return node;
+}
+
+function mapGlobalFilters(filters: GlobalFilter[]): SchemaNode {
+  return {
+    type: 'filter-bar',
+    id: 'dashboard-filters',
+    filters: filters.map((f) => {
+      const mapped: Record<string, any> = { field: f.field };
+      if (f.label) mapped.label = f.label;
+      if (f.type) mapped.type = f.type;
+      if (f.options) mapped.options = f.options;
+      if (f.optionsFrom) mapped.optionsFrom = f.optionsFrom;
+      if (f.defaultValue != null) mapped.defaultValue = f.defaultValue;
+      if (f.scope) mapped.scope = f.scope;
+      if (f.targetWidgets) mapped.targetWidgets = f.targetWidgets;
+      return mapped;
+    }),
+  };
+}
+
+function mapHeader(header: DashboardHeader): SchemaNode {
+  const node: SchemaNode = {
+    type: 'dashboard-header',
+    id: 'dashboard-header',
+    ...header,
+  };
+  return node;
+}
+
+/** Transforms a Dashboard spec into a dashboard layout SchemaNode */
+export const bridgeDashboard: BridgeFn<DashboardSpec> = (
+  spec: DashboardSpec,
+  _context: BridgeContext,
+): SchemaNode => {
+  const widgetNodes = (spec.widgets ?? []).map(mapWidget);
+
+  const bodyChildren: SchemaNode[] = [];
+
+  if (spec.header) {
+    bodyChildren.push(mapHeader(spec.header));
+  }
+
+  if (spec.globalFilters && spec.globalFilters.length > 0) {
+    bodyChildren.push(mapGlobalFilters(spec.globalFilters));
+  }
+
+  // P1.3 — Date range filter
+  if (spec.dateRange) {
+    bodyChildren.push({
+      type: 'date-range-filter',
+      id: 'dashboard-date-range',
+      ...spec.dateRange,
+    });
+  }
+
+  bodyChildren.push({
+    type: 'widget-grid',
+    id: 'dashboard-widgets',
+    body: widgetNodes,
+  });
+
+  const node: SchemaNode = {
+    type: 'dashboard',
+    id: spec.name,
+    body: bodyChildren,
+  };
+
+  if (spec.label) node.label = spec.label;
+  if (spec.description) node.description = spec.description;
+  if (spec.refreshInterval != null) node.refreshInterval = spec.refreshInterval;
+
+  // P1.6 — i18n & ARIA
+  if (spec.aria) node.aria = spec.aria;
+  if (spec.performance) node.performance = spec.performance;
+
+  return node;
+};

package/src/spec-bridge/bridges/form-view.ts

@@ -0,0 +1,109 @@
+/**
+ * ObjectUI
+ * Copyright (c) 2024-present ObjectStack Inc.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+import type { SchemaNode } from '@object-ui/core';
+import type { BridgeContext, BridgeFn } from '../types';
+
+interface FormField {
+  field: string;
+  label?: string;
+  placeholder?: string;
+  helpText?: string;
+  readonly?: boolean;
+  required?: boolean;
+  hidden?: boolean;
+  colSpan?: number;
+  widget?: string;
+  dependsOn?: string[];
+  visibleOn?: string;
+}
+
+interface FormSection {
+  label?: string;
+  collapsible?: boolean;
+  collapsed?: boolean;
+  columns?: number;
+  fields?: FormField[];
+}
+
+interface FormViewSpec {
+  type?: string;
+  data?: any;
+  sections?: FormSection[];
+  groups?: any;
+  // P1.2 additions
+  defaultSort?: any;
+  sharing?: any;
+  aria?: { ariaLabel?: string; ariaDescribedBy?: string; role?: string };
+}
+
+function mapField(field: FormField): Record<string, any> {
+  const mapped: Record<string, any> = {
+    name: field.field,
+    label: field.label ?? field.field,
+  };
+
+  if (field.placeholder) mapped.placeholder = field.placeholder;
+  if (field.helpText) mapped.helpText = field.helpText;
+  if (field.readonly != null) mapped.readonly = field.readonly;
+  if (field.required != null) mapped.required = field.required;
+  if (field.hidden != null) mapped.hidden = field.hidden;
+  if (field.colSpan != null) mapped.colSpan = field.colSpan;
+  if (field.widget) mapped.widget = field.widget;
+  if (field.dependsOn) mapped.dependsOn = field.dependsOn;
+  if (field.visibleOn) mapped.visibleOn = field.visibleOn;
+
+  return mapped;
+}
+
+function mapSection(section: FormSection): Record<string, any> {
+  const mapped: Record<string, any> = {
+    fields: (section.fields ?? []).map(mapField),
+  };
+
+  if (section.label) mapped.label = section.label;
+  if (section.collapsible != null) mapped.collapsible = section.collapsible;
+  if (section.collapsed != null) mapped.collapsed = section.collapsed;
+  if (section.columns != null) mapped.columns = section.columns;
+
+  return mapped;
+}
+
+/** Maps spec formType to ObjectUI formType */
+function mapFormType(type?: string): string | undefined {
+  if (!type) return undefined;
+  const validTypes = ['simple', 'tabbed', 'wizard', 'split', 'drawer', 'modal'];
+  return validTypes.includes(type) ? type : undefined;
+}
+
+/** Transforms a FormView spec into a Form SchemaNode */
+export const bridgeFormView: BridgeFn<FormViewSpec> = (
+  spec: FormViewSpec,
+  _context: BridgeContext,
+): SchemaNode => {
+  const sections = (spec.sections ?? []).map(mapSection);
+  const formType = mapFormType(spec.type);
+
+  const node: SchemaNode = {
+    type: 'object-form',
+    id: `form-${spec.type ?? 'default'}`,
+    sections,
+    data: spec.data,
+  };
+
+  // P1.2 — formType mapping (tabbed, wizard, split, drawer, modal)
+  if (formType) node.formType = formType;
+  if (spec.groups) node.groups = spec.groups;
+  if (spec.defaultSort) node.defaultSort = spec.defaultSort;
+
+  // P1.6 — i18n & ARIA
+  if (spec.sharing) node.sharing = spec.sharing;
+  if (spec.aria) node.aria = spec.aria;
+
+  return node;
+};

package/src/spec-bridge/bridges/list-view.ts

@@ -0,0 +1,187 @@
+/**
+ * ObjectUI
+ * Copyright (c) 2024-present ObjectStack Inc.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+import type { SchemaNode } from '@object-ui/core';
+import { normalizeQuickFilters } from '@object-ui/core';
+import type { BridgeContext, BridgeFn } from '../types';
+import type { ListViewGalleryConfig, ListViewTimelineConfig } from '@object-ui/types';
+
+interface ListColumn {
+  field: string;
+  label?: string;
+  width?: number;
+  align?: string;
+  hidden?: boolean;
+  sortable?: boolean;
+  resizable?: boolean;
+  wrap?: boolean;
+  type?: string;
+  pinned?: string;
+  summary?: any;
+  link?: any;
+  action?: any;
+}
+
+interface ListViewSpec {
+  name?: string;
+  label?: string;
+  type?: string;
+  data?: any;
+  columns?: ListColumn[];
+  filter?: any;
+  sort?: any;
+  searchableFields?: string[];
+  filterableFields?: string[];
+  quickFilters?: any[];
+  selection?: any;
+  pagination?: any;
+  rowHeight?: string;
+  resizable?: boolean;
+  striped?: boolean;
+  bordered?: boolean;
+  grouping?: any;
+  rowColor?: any;
+  navigation?: any;
+  kanban?: any;
+  calendar?: any;
+  gantt?: any;
+  gallery?: ListViewGalleryConfig;
+  timeline?: ListViewTimelineConfig;
+  // P1.1 additions
+  rowActions?: string[];
+  bulkActions?: string[];
+  virtualScroll?: boolean;
+  conditionalFormatting?: Array<{ condition: string; style: Record<string, string> }>;
+  inlineEdit?: boolean;
+  exportOptions?: any;
+  emptyState?: { title?: string; message?: string; icon?: string };
+  userActions?: any;
+  appearance?: any;
+  tabs?: any[];
+  addRecord?: any;
+  showRecordCount?: boolean;
+  allowPrinting?: boolean;
+  // P1.6 i18n & ARIA
+  aria?: { ariaLabel?: string; ariaDescribedBy?: string; role?: string };
+  sharing?: any;
+  hiddenFields?: string[];
+  fieldOrder?: string[];
+  description?: string;
+}
+
+function mapColumn(col: ListColumn): Record<string, any> {
+  const mapped: Record<string, any> = {
+    accessorKey: col.field,
+    header: col.label ?? col.field,
+  };
+
+  if (col.width != null) mapped.width = col.width;
+  if (col.align) mapped.align = col.align;
+  if (col.hidden != null) mapped.hidden = col.hidden;
+  if (col.sortable != null) mapped.sortable = col.sortable;
+  if (col.resizable != null) mapped.resizable = col.resizable;
+  if (col.wrap != null) mapped.wrap = col.wrap;
+  if (col.type) mapped.type = col.type;
+  if (col.pinned) mapped.pinned = col.pinned;
+  if (col.summary) mapped.summary = col.summary;
+  if (col.link) mapped.link = col.link;
+  if (col.action) mapped.action = col.action;
+
+  return mapped;
+}
+
+function mapDensity(
+  rowHeight?: string,
+): 'compact' | 'comfortable' | 'spacious' | undefined {
+  if (!rowHeight) return undefined;
+  const map: Record<string, 'compact' | 'comfortable' | 'spacious'> = {
+    compact: 'compact',
+    short: 'compact',
+    comfortable: 'comfortable',
+    spacious: 'spacious',
+    small: 'compact',
+    medium: 'comfortable',
+    large: 'spacious',
+    tall: 'spacious',
+    extra_tall: 'spacious',
+  };
+  return map[rowHeight];
+}
+
+/** Transforms a ListView spec into a DataTable SchemaNode */
+export const bridgeListView: BridgeFn<ListViewSpec> = (
+  spec: ListViewSpec,
+  _context: BridgeContext,
+): SchemaNode => {
+  const columns = (spec.columns ?? []).map(mapColumn);
+  const density = mapDensity(spec.rowHeight);
+
+  const node: SchemaNode = {
+    type: 'object-grid',
+    id: spec.name,
+    columns,
+    data: spec.data,
+  };
+
+  if (spec.label) node.label = spec.label;
+  if (spec.selection) node.selection = spec.selection;
+  if (spec.pagination) node.pagination = spec.pagination;
+  if (spec.sort) node.sort = spec.sort;
+  if (spec.filter) node.filter = spec.filter;
+  if (density) node.density = density;
+  if (spec.grouping) node.grouping = spec.grouping;
+  if (spec.rowColor) node.rowColor = spec.rowColor;
+  if (spec.searchableFields) node.searchableFields = spec.searchableFields;
+  if (spec.filterableFields) node.filterableFields = spec.filterableFields;
+  // Normalize quickFilters: spec format { field, operator, value } → ObjectUI format
+  const normalizedQF = normalizeQuickFilters(spec.quickFilters);
+  if (normalizedQF) node.quickFilters = normalizedQF;
+  if (spec.resizable != null) node.resizable = spec.resizable;
+  if (spec.striped != null) node.striped = spec.striped;
+  if (spec.bordered != null) node.bordered = spec.bordered;
+  if (spec.navigation) node.navigation = spec.navigation;
+  if (spec.kanban) node.kanban = spec.kanban;
+  if (spec.calendar) node.calendar = spec.calendar;
+  if (spec.gantt) node.gantt = spec.gantt;
+  if (spec.gallery) node.gallery = spec.gallery;
+  if (spec.timeline) node.timeline = spec.timeline;
+
+  // P1.1 — Spec Protocol Alignment additions
+  if (spec.rowActions) node.rowActions = spec.rowActions;
+  if (spec.bulkActions) node.bulkActions = spec.bulkActions;
+  if (spec.virtualScroll != null) node.virtualScroll = spec.virtualScroll;
+  if (spec.conditionalFormatting) node.conditionalFormatting = spec.conditionalFormatting;
+  if (spec.inlineEdit != null) node.inlineEdit = spec.inlineEdit;
+  if (spec.exportOptions) node.exportOptions = spec.exportOptions;
+  if (spec.emptyState) node.emptyState = spec.emptyState;
+  if (spec.userActions) node.userActions = spec.userActions;
+  if (spec.appearance) node.appearance = spec.appearance;
+  if (spec.tabs) node.tabs = spec.tabs;
+  if (spec.addRecord) node.addRecord = spec.addRecord;
+  if (spec.showRecordCount != null) node.showRecordCount = spec.showRecordCount;
+  if (spec.allowPrinting != null) node.allowPrinting = spec.allowPrinting;
+
+  // P1.6 — i18n & ARIA
+  if (spec.aria) node.aria = spec.aria;
+  if (spec.sharing) {
+    // Normalize spec sharing format: map type → visibility, set enabled = true
+    const sharing: Record<string, any> = { ...spec.sharing };
+    if (sharing.type && !sharing.visibility) {
+      sharing.visibility = sharing.type === 'collaborative' ? 'team' : 'private';
+    }
+    if (sharing.type && sharing.enabled == null) {
+      sharing.enabled = true;
+    }
+    node.sharing = sharing;
+  }
+  if (spec.hiddenFields) node.hiddenFields = spec.hiddenFields;
+  if (spec.fieldOrder) node.fieldOrder = spec.fieldOrder;
+  if (spec.description) node.description = spec.description;
+
+  return node;
+};

package/src/spec-bridge/bridges/page.ts

@@ -0,0 +1,136 @@
+/**
+ * ObjectUI
+ * Copyright (c) 2024-present ObjectStack Inc.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+import type { SchemaNode } from '@object-ui/core';
+import type { BridgeContext, BridgeFn } from '../types';
+
+interface PageComponent {
+  type: string;
+  id?: string;
+  label?: string;
+  properties?: Record<string, any>;
+  events?: Record<string, any>;
+  style?: Record<string, any>;
+  className?: string;
+  visibility?: string;
+  dataSource?: any;
+  responsive?: any;
+  aria?: Record<string, string>;
+}
+
+interface PageRegion {
+  name?: string;
+  width?: string;
+  components?: PageComponent[];
+}
+
+interface PageVariable {
+  name: string;
+  type?: string;
+  defaultValue?: any;
+  source?: string;
+}
+
+interface BlankPageLayoutItem {
+  componentId: string;
+  x: number;
+  y: number;
+  width: number;
+  height: number;
+}
+
+interface PageSpec {
+  name?: string;
+  label?: string;
+  description?: string;
+  icon?: string;
+  type?: string;
+  variables?: PageVariable[];
+  regions?: PageRegion[];
+  template?: string;
+  object?: string;
+  // P1.4 additions
+  blankLayout?: {
+    columns?: number;
+    rowHeight?: number;
+    gap?: number;
+    items?: BlankPageLayoutItem[];
+  };
+  recordReview?: any;
+  isDefault?: boolean;
+  assignedProfiles?: string[];
+  interfaceConfig?: any;
+  aria?: { ariaLabel?: string; ariaDescribedBy?: string; role?: string };
+}
+
+function mapComponent(component: PageComponent): SchemaNode {
+  const node: SchemaNode = {
+    type: component.type,
+    id: component.id,
+  };
+
+  if (component.label) node.label = component.label;
+  if (component.className) node.className = component.className;
+  if (component.properties) {
+    Object.assign(node, component.properties);
+  }
+  if (component.events) node.events = component.events;
+  if (component.visibility) node.visibility = component.visibility;
+  if (component.dataSource) node.dataSource = component.dataSource;
+  if (component.responsive) node.responsive = component.responsive;
+  if (component.aria) node.aria = component.aria;
+
+  return node;
+}
+
+function mapRegion(region: PageRegion): SchemaNode {
+  const children = (region.components ?? []).map(mapComponent);
+  const node: SchemaNode = {
+    type: 'page-region',
+    id: region.name,
+    body: children,
+  };
+  if (region.width) node.width = region.width;
+  return node;
+}
+
+/** Transforms a Page spec into a page layout SchemaNode */
+export const bridgePage: BridgeFn<PageSpec> = (
+  spec: PageSpec,
+  _context: BridgeContext,
+): SchemaNode => {
+  const regions = (spec.regions ?? []).map(mapRegion);
+
+  const node: SchemaNode = {
+    type: 'page',
+    id: spec.name,
+    body: regions,
+  };
+
+  if (spec.label) node.label = spec.label;
+  if (spec.description) node.description = spec.description;
+  if (spec.icon) node.icon = spec.icon;
+  if (spec.type) node.pageType = spec.type;
+  if (spec.variables) node.variables = spec.variables;
+  if (spec.template) node.template = spec.template;
+  if (spec.object) node.object = spec.object;
+
+  // P1.4 — Blank page layout
+  if (spec.blankLayout) node.blankLayout = spec.blankLayout;
+
+  // P1.4 — Additional page properties
+  if (spec.recordReview) node.recordReview = spec.recordReview;
+  if (spec.isDefault != null) node.isDefault = spec.isDefault;
+  if (spec.assignedProfiles) node.assignedProfiles = spec.assignedProfiles;
+  if (spec.interfaceConfig) node.interfaceConfig = spec.interfaceConfig;
+
+  // P1.6 — i18n & ARIA
+  if (spec.aria) node.aria = spec.aria;
+
+  return node;
+};

package/src/spec-bridge/index.ts

@@ -0,0 +1,14 @@
+/**
+ * ObjectUI
+ * Copyright (c) 2024-present ObjectStack Inc.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+export { SpecBridge } from './SpecBridge';
+export type { BridgeContext, BridgeFn, ObjectDefLite } from './types';
+export { bridgeListView } from './bridges/list-view';
+export { bridgeFormView } from './bridges/form-view';
+export { bridgePage } from './bridges/page';
+export { bridgeDashboard } from './bridges/dashboard';

package/src/spec-bridge/types.ts

@@ -0,0 +1,38 @@
+/**
+ * ObjectUI
+ * Copyright (c) 2024-present ObjectStack Inc.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+import type { SchemaNode } from '@object-ui/core';
+
+/** Context passed to all bridge functions */
+export interface BridgeContext {
+  /** Current user context for permission checks */
+  user?: Record<string, any>;
+  /** App-level variables */
+  variables?: Record<string, any>;
+  /** Registered object definitions for field metadata lookup */
+  objectDefs?: Record<string, ObjectDefLite>;
+}
+
+/** Lightweight object definition for field metadata resolution */
+export interface ObjectDefLite {
+  name: string;
+  label?: string;
+  fields: Array<{
+    name: string;
+    label?: string;
+    type: string;
+    required?: boolean;
+    options?: Array<{ label: string; value: string }>;
+  }>;
+}
+
+/** A bridge function transforms a spec schema into a SchemaNode tree */
+export type BridgeFn<T = any> = (
+  spec: T,
+  context: BridgeContext,
+) => SchemaNode;