@object-ui/fields 6.2.3 → 7.1.0

package/src/index.tsx

@@ -8,9 +8,10 @@
 
 import React from 'react';
 import type { FieldMetadata, SelectOptionMetadata } from '@object-ui/types';
-import { ComponentRegistry } from '@object-ui/core';
+import { ComponentRegistry, percentDisplayValue } from '@object-ui/core';
+import { useLocalization } from '@object-ui/i18n';
 import { Badge, Avatar, AvatarFallback, Button, Checkbox, EmptyValue, cn } from '@object-ui/components';
-import { Check, X, Copy, Phone as PhoneIcon } from 'lucide-react';
+import { Check, X, Copy, Phone as PhoneIcon, MapPin } from 'lucide-react';
 import { useObjectTranslation } from '@object-ui/react';
 import { SchemaRendererContext as _SchemaRendererContext } from '@object-ui/react';
 
@@ -222,13 +223,23 @@ export interface CellRendererProps {
  */
 export function coerceToSafeValue(value: unknown): string | number | boolean | null | undefined {
   if (value == null) return value as null | undefined;
-  if (typeof value === 'string' || typeof value === 'number' || typeof value === 'boolean') return value;
+  if (typeof value === 'number' || typeof value === 'boolean') return value;
+  if (typeof value === 'string') {
+    // A reference/expanded value can arrive as a JSON-encoded object string —
+    // e.g. an unresolved external-id reference '{"externalId":"Website Relaunch"}'.
+    // Parse and extract a human label instead of leaking raw JSON into the cell.
+    const s = value.trim();
+    if ((s.startsWith('{') && s.endsWith('}')) || (s.startsWith('[') && s.endsWith(']'))) {
+      try { return coerceToSafeValue(JSON.parse(s)); } catch { /* not JSON — fall through */ }
+    }
+    return value;
+  }
   if (value instanceof Date) return value.toISOString();
   if (Array.isArray(value)) {
     return value.map((v) => {
       if (v != null && typeof v === 'object') {
         const obj = v as Record<string, unknown>;
-        return String(obj.name || obj.label || obj.id || obj._id || '[Object]');
+        return String(obj.name || obj.label || obj.externalId || obj.id || obj._id || '[Object]');
       }
       return String(v);
     }).join(', ');
@@ -241,8 +252,8 @@ export function coerceToSafeValue(value: unknown): string | number | boolean | n
     if ('$oid' in obj) return String(obj.$oid);
     // MongoDB date wrapper: { $date: "2024-01-01T00:00:00Z" }
     if ('$date' in obj) return String(obj.$date);
-    // Expanded reference / general object: extract name/label/id
-    return String(obj.name || obj.label || obj.id || obj._id || '[Object]');
+    // Expanded reference / general object: extract name/label/externalId/id
+    return String(obj.name || obj.label || obj.externalId || obj.id || obj._id || '[Object]');
   }
   return String(value);
 }
@@ -256,6 +267,9 @@ export function coerceToSafeValue(value: unknown): string | number | boolean | n
  * Trailing `.00` is dropped when the value is a whole number — Salesforce
  * convention: `$1,234.50` keeps cents; `$1,234` does not.
  */
+import { resolveFieldCurrency } from './currency';
+export { resolveFieldCurrency };
+
 export function formatCurrency(value: number, currency?: string): string {
   const isWhole = Number.isFinite(value) && value === Math.trunc(value);
   const maxFrac = isWhole ? 0 : 2;
@@ -327,8 +341,9 @@ export function formatNumber(value: number, decimals: number = 2): string {
  * Handles both decimal (0.8 = 80%) and whole number (80 = 80%) inputs.
  */
 export function formatPercent(value: number, precision: number = 0): string {
-  // If value is between -1 and 1 (exclusive), treat as decimal (e.g. 0.8 → 80%)
-  const displayValue = (value > -1 && value < 1) ? value * 100 : value;
+  // Scale a fraction-stored percent (0.8 → 80%) via the shared core helper, so
+  // the list cell and the dashboard measure formatter (`formatMeasure`) agree.
+  const displayValue = percentDisplayValue(value);
   return `${displayValue.toFixed(precision)}%`;
 }
 
@@ -454,18 +469,12 @@ export function CurrencyCellRenderer({ value, field }: CellRendererProps): React
   if (value == null) return <EmptyValue />;
   
   const safe = coerceToSafeValue(value);
-  const currencyField = field as any;
-  // Honor `currency` (legacy/grid configs), `defaultCurrency` (canonical
-  // top-level), and `currencyConfig.defaultCurrency` (the nested shape
-  // emitted by `@objectstack/spec` Field.currency() with currencyConfig).
-  // When none is supplied, render as a plain formatted number —
-  // silently assuming USD for unconfigured currency fields was
-  // misleading for non-USD orgs (e.g. RMB amounts displayed as $).
-  const currency: string | undefined =
-    currencyField.currency ||
-    currencyField.defaultCurrency ||
-    currencyField.currencyConfig?.defaultCurrency ||
-    undefined;
+  // Resolve the display currency via the shared precedence: field `currency` →
+  // `currencyConfig.defaultCurrency` → the tenant default (ADR-0053). When none
+  // is known, render a plain number — never a guessed symbol (silently assuming
+  // USD mis-displays non-USD orgs, e.g. RMB amounts shown as $).
+  const { currency: tenantCurrency } = useLocalization();
+  const currency = resolveFieldCurrency(field as any, tenantCurrency);
   const num = Number(safe);
   const formatted = !isNaN(num)
     ? formatCurrency(num, currency)
@@ -769,8 +778,52 @@ function hashToColor(value: string): string {
   return BADGE_FALLBACK_PALETTE[idx];
 }
 
+/**
+ * Map a hex color (e.g. '#8B5CF6') to the nearest named palette color the
+ * badge/dot maps understand. Object field options almost always declare colors
+ * as HEX, so without this the explicit author color is ignored and a semantic/
+ * hash heuristic takes over (e.g. a purple 'In Review' rendered alarming-red).
+ * Low-saturation hexes resolve to 'gray'; otherwise bucket by hue.
+ */
+function hexToPaletteName(hex: string): string | undefined {
+  const m = /^#?([0-9a-fA-F]{3}|[0-9a-fA-F]{6})$/.exec(hex.trim());
+  if (!m) return undefined;
+  let h = m[1];
+  if (h.length === 3) h = h.split('').map((c) => c + c).join('');
+  const r = parseInt(h.slice(0, 2), 16) / 255;
+  const g = parseInt(h.slice(2, 4), 16) / 255;
+  const b = parseInt(h.slice(4, 6), 16) / 255;
+  const max = Math.max(r, g, b), min = Math.min(r, g, b), d = max - min;
+  const l = (max + min) / 2;
+  const sat = d === 0 ? 0 : d / (1 - Math.abs(2 * l - 1));
+  if (sat < 0.22) return 'gray';
+  let hue: number;
+  if (max === r) hue = (((g - b) / d) % 6 + 6) % 6;
+  else if (max === g) hue = (b - r) / d + 2;
+  else hue = (r - g) / d + 4;
+  hue *= 60;
+  if (hue >= 345 || hue < 15) return 'red';
+  if (hue < 30) return 'orange';
+  if (hue < 60) return 'yellow';
+  if (hue < 170) return 'green';
+  if (hue < 238) return 'blue';
+  if (hue < 250) return 'indigo';
+  if (hue < 295) return 'purple';
+  return 'pink';
+}
+
+/** Normalize an option color to a named palette key: pass known names through,
+ *  resolve hex to the nearest palette color, else undefined. */
+function resolveColorName(color?: string): string | undefined {
+  if (!color) return undefined;
+  if (BADGE_COLOR_MAP[color]) return color;
+  if (color.charAt(0) === '#') return hexToPaletteName(color);
+  return undefined;
+}
+
 export function getBadgeColorClasses(color?: string, val?: unknown): string {
-  if (color && BADGE_COLOR_MAP[color]) return BADGE_COLOR_MAP[color];
+  const named = resolveColorName(color);
+  if (named && BADGE_COLOR_MAP[named]) return BADGE_COLOR_MAP[named];
   if (val == null || val === '') return 'bg-muted text-muted-foreground border-border';
   const key = String(val).toLowerCase().replace(/[\s-]/g, '_');
   const semantic = SEMANTIC_COLOR_MAP[key];
@@ -790,7 +843,8 @@ export function getBadgeColorClasses(color?: string, val?: unknown): string {
  * supplied so the caller can fall back to its own default.
  */
 export function getSemanticColorName(color?: string, val?: unknown): string | undefined {
-  if (color && BADGE_COLOR_MAP[color]) return color;
+  const named = resolveColorName(color);
+  if (named && BADGE_COLOR_MAP[named]) return named;
   if (val == null || val === '') return undefined;
   const key = String(val).toLowerCase().replace(/[\s-]/g, '_');
   const semantic = SEMANTIC_COLOR_MAP[key];
@@ -862,7 +916,7 @@ export function SelectCellRenderer({ value, field }: CellRendererProps): React.R
     if (appearance === 'dot') {
       // Resolve a real CSS color for the dot. Prefer explicit option color,
       // then semantic mapping for the value, then deterministic palette.
-      const colorName = option?.color
+      const colorName = resolveColorName(option?.color)
         || SEMANTIC_COLOR_MAP[String(val).toLowerCase().replace(/[\s-]/g, '_')]
         || hashToColor(String(val).toLowerCase().replace(/[\s-]/g, '_'));
       const dotClass = DOT_COLOR_MAP[colorName] || DOT_COLOR_MAP.gray;
@@ -1044,31 +1098,44 @@ export function FileCellRenderer({ value, field }: CellRendererProps): React.Rea
  */
 export function ImageCellRenderer({ value }: CellRendererProps): React.ReactElement {
   if (!value) return <EmptyValue />;
-  
+
+  // An image value may be a plain URL string, an object ({ url | src | href }),
+  // or an array of either. Normalize so a string-URL field (common — e.g. a
+  // `cover` seeded with a CDN link) renders a thumbnail instead of a broken
+  // <img src=""> placeholder.
+  const urlOf = (v: any): string =>
+    typeof v === 'string' ? v : (v?.url || v?.src || v?.href || v?.thumbnailUrl || '');
+  const nameOf = (v: any, fallback: string): string =>
+    (v && typeof v === 'object' && (v.name || v.original_name)) || fallback;
+
   if (Array.isArray(value)) {
+    const imgs = value.map((v) => ({ url: urlOf(v), name: nameOf(v, 'Image') })).filter((i) => i.url);
+    if (imgs.length === 0) return <EmptyValue />;
     return (
       <div className="flex -space-x-2">
-        {value.slice(0, 3).map((img, idx) => (
+        {imgs.slice(0, 3).map((img, idx) => (
           <img
             key={idx}
-            src={img.url || ''}
+            src={img.url}
             alt={img.name || `Image ${idx + 1}`}
             className="size-8 rounded-md border-2 border-white object-cover"
           />
         ))}
-        {value.length > 3 && (
+        {imgs.length > 3 && (
           <div className="size-8 rounded-md border-2 border-white bg-gray-100 flex items-center justify-center text-xs font-medium text-gray-600">
-            +{value.length - 3}
+            +{imgs.length - 3}
           </div>
         )}
       </div>
     );
   }
-  
+
+  const url = urlOf(value);
+  if (!url) return <EmptyValue />;
   return (
     <img
-      src={value.url || ''}
-      alt={value.name || 'Image'}
+      src={url}
+      alt={nameOf(value, 'Image')}
       className="size-10 rounded-md object-cover"
     />
   );
@@ -1112,6 +1179,24 @@ export function LookupCellRenderer({ value, field }: CellRendererProps): React.R
 
   if (value == null || value === '') return <EmptyValue />;
 
+  // A reference can arrive as a JSON-encoded object string — e.g. an
+  // unresolved external-id reference '{"externalId":"Website Relaunch"}'.
+  // Parse it and render a label instead of leaking raw JSON into the cell.
+  if (typeof value === 'string') {
+    const s = value.trim();
+    if (s.startsWith('{') && s.endsWith('}')) {
+      try {
+        const parsed = JSON.parse(s) as Record<string, unknown>;
+        if (parsed && typeof parsed === 'object') {
+          const display =
+            pickRecordDisplayName(parsed) ||
+            String(parsed.externalId ?? parsed.id ?? parsed._id ?? '');
+          if (display) return <span className="truncate">{display}</span>;
+        }
+      } catch { /* not JSON — fall through to normal resolution */ }
+    }
+  }
+
   // Server-side $expand returns the related record as a nested object
   // (e.g. { id, name }). Render its display name directly — no fetch needed.
   if (!Array.isArray(value) && typeof value === 'object') {
@@ -1323,6 +1408,117 @@ export function resolveCellRendererType(fieldOrType: string | { type?: string; f
   return fieldOrType.type || 'text';
 }
 
+/**
+ * Renders structured/embedded values (json, object, composite, record,
+ * address, geolocation) as compact, readable JSON. Objects and arrays are
+ * stringified; primitives fall through to their string form.
+ */
+export function JsonCellRenderer({ value }: CellRendererProps): React.ReactElement {
+  if (value == null || value === '') return <EmptyValue />;
+  let text: string;
+  if (typeof value === 'object') {
+    try {
+      text = JSON.stringify(value);
+    } catch {
+      text = String(value);
+    }
+  } else {
+    text = String(value);
+  }
+  return <span className="font-mono text-xs text-gray-600 truncate" title={text}>{text}</span>;
+}
+
+/**
+ * Renders a `color` value as a swatch alongside its hex/string value.
+ */
+export function ColorSwatchCellRenderer({ value }: CellRendererProps): React.ReactElement {
+  if (value == null || value === '') return <EmptyValue />;
+  const color = String(value);
+  return (
+    <span className="inline-flex items-center gap-1.5 text-sm">
+      <span
+        className="h-3.5 w-3.5 rounded border border-black/10 shrink-0"
+        style={{ backgroundColor: color }}
+        aria-hidden="true"
+      />
+      <span className="font-mono text-xs">{color}</span>
+    </span>
+  );
+}
+
+const LazyMarkdownContent = React.lazy(() => import('./widgets/MarkdownContent'));
+
+/**
+ * Renders `markdown` / `richtext` values as formatted GFM markdown (lazy-loaded,
+ * sanitized) instead of the raw markup string.
+ */
+export function MarkdownCellRenderer({ value }: CellRendererProps): React.ReactElement {
+  if (value == null || value === '') return <EmptyValue />;
+  return (
+    <React.Suspense fallback={<span className="text-sm text-muted-foreground">{String(value).slice(0, 80)}</span>}>
+      <LazyMarkdownContent value={String(value)} />
+    </React.Suspense>
+  );
+}
+
+/**
+ * Minimal HTML sanitizer for display: drops <script>/<style>/<iframe> blocks,
+ * inline event handlers, and javascript: URLs. Defense-in-depth — stored HTML
+ * is authored by users with write access, but is never trusted blindly.
+ */
+function sanitizeHtml(html: string): string {
+  return html
+    .replace(/<\s*(script|style|iframe|object|embed)[^>]*>[\s\S]*?<\s*\/\s*\1\s*>/gi, '')
+    .replace(/\son\w+\s*=\s*("[^"]*"|'[^']*'|[^\s>]+)/gi, '')
+    .replace(/(href|src)\s*=\s*("javascript:[^"]*"|'javascript:[^']*')/gi, '$1="#"');
+}
+
+/**
+ * Renders an `html` value as sanitized, formatted HTML instead of raw markup.
+ */
+export function HtmlCellRenderer({ value }: CellRendererProps): React.ReactElement {
+  if (value == null || value === '') return <EmptyValue />;
+  return (
+    <div
+      className="prose prose-sm max-w-none dark:prose-invert break-words"
+      dangerouslySetInnerHTML={{ __html: sanitizeHtml(String(value)) }}
+    />
+  );
+}
+
+/**
+ * Renders a `location`/`geolocation` value as readable coordinates with a pin.
+ * Accepts `{ lat, lng }` / `{ latitude, longitude }`, a `"lat,lng"` string,
+ * or a `[lat, lng]` array. Falls back to compact JSON for anything else.
+ */
+export function LocationCellRenderer({ value }: CellRendererProps): React.ReactElement {
+  if (value == null || value === '') return <EmptyValue />;
+  let lat: number | undefined;
+  let lng: number | undefined;
+  if (typeof value === 'object' && !Array.isArray(value)) {
+    const v = value as Record<string, any>;
+    lat = typeof v.lat === 'number' ? v.lat : typeof v.latitude === 'number' ? v.latitude : undefined;
+    lng = typeof v.lng === 'number' ? v.lng : typeof v.lon === 'number' ? v.lon : typeof v.longitude === 'number' ? v.longitude : undefined;
+  } else if (Array.isArray(value) && value.length === 2) {
+    lat = Number(value[0]);
+    lng = Number(value[1]);
+  } else if (typeof value === 'string') {
+    const parts = value.split(',').map((s) => parseFloat(s.trim()));
+    if (parts.length === 2 && !isNaN(parts[0]) && !isNaN(parts[1])) {
+      [lat, lng] = parts;
+    }
+  }
+  if (typeof lat === 'number' && typeof lng === 'number' && !isNaN(lat) && !isNaN(lng)) {
+    return (
+      <span className="inline-flex items-center gap-1 text-sm tabular-nums">
+        <MapPin className="h-3.5 w-3.5 shrink-0 text-muted-foreground" aria-hidden="true" />
+        {lat.toFixed(4)}, {lng.toFixed(4)}
+      </span>
+    );
+  }
+  return <JsonCellRenderer value={value} field={{} as any} />;
+}
+
 /**
  * Get the appropriate cell renderer for a field type
  */
@@ -1336,32 +1532,61 @@ export function getCellRenderer(fieldType: string): React.FC<CellRendererProps>
   const standardMap: Record<string, React.FC<CellRendererProps>> = {
     text: TextCellRenderer,
     textarea: TextCellRenderer,
-    markdown: TextCellRenderer,
-    html: TextCellRenderer,
+    markdown: MarkdownCellRenderer,
+    html: HtmlCellRenderer,
+    richtext: MarkdownCellRenderer,
+    code: TextCellRenderer,
+    qrcode: TextCellRenderer,
     number: NumberCellRenderer,
     currency: CurrencyCellRenderer,
     percent: PercentCellRenderer,
+    progress: PercentCellRenderer,
+    slider: NumberCellRenderer,
+    rating: NumberCellRenderer,
     boolean: BooleanCellRenderer,
+    toggle: BooleanCellRenderer,
     date: DateCellRenderer,
     datetime: DateTimeCellRenderer,
     time: TextCellRenderer,
     select: SelectCellRenderer,
     status: SelectCellRenderer,
+    multiselect: SelectCellRenderer,
+    radio: SelectCellRenderer,
+    checkboxes: SelectCellRenderer,
+    tags: SelectCellRenderer,
     lookup: LookupCellRenderer,
     master_detail: LookupCellRenderer,
+    tree: LookupCellRenderer,
     email: EmailCellRenderer,
     url: UrlCellRenderer,
     phone: PhoneCellRenderer,
     file: FileCellRenderer,
+    video: FileCellRenderer,
+    audio: FileCellRenderer,
     image: ImageCellRenderer,
+    avatar: ImageCellRenderer,
+    signature: ImageCellRenderer,
     formula: FormulaCellRenderer,
     summary: FormulaCellRenderer,
     auto_number: TextCellRenderer,
     user: UserCellRenderer,
     owner: UserCellRenderer,
     password: () => <span>••••••</span>,
-    location: TextCellRenderer, // Default fallback
-    object: () => <span className="text-gray-500 italic">[Object]</span>,
+    secret: () => <span>••••••</span>,
+    location: LocationCellRenderer,
+    geolocation: LocationCellRenderer,
+    address: JsonCellRenderer,
+    color: ColorSwatchCellRenderer,
+    json: JsonCellRenderer,
+    object: JsonCellRenderer,
+    composite: JsonCellRenderer,
+    record: JsonCellRenderer,
+    repeater: ({ value }: CellRendererProps) => {
+      const n = Array.isArray(value) ? value.length : 0;
+      return n > 0
+        ? <span className="text-gray-500 italic">{n} 项</span>
+        : <EmptyValue />;
+    },
     vector: () => <span className="text-gray-500 italic">[Vector]</span>,
     grid: () => <span className="text-gray-500 italic">[Grid]</span>,
   };
@@ -1402,38 +1627,66 @@ export function mapFieldTypeToFormType(fieldType: string): string {
     textarea: 'field:textarea',
     markdown: 'field:markdown', // Markdown editor (fallback to textarea)
     html: 'field:html', // Rich text editor (fallback to textarea)
-    
+    richtext: 'field:richtext', // WYSIWYG rich-text editor
+    secret: 'field:password', // encrypted-at-rest value — mask input like a password
+
     // Numeric fields
     number: 'field:number',
     currency: 'field:currency',
     percent: 'field:percent',
-    
+    slider: 'field:slider',
+    progress: 'field:slider', // bounded 0..100 progress — edit via slider
+    rating: 'field:rating',
+
     // Date/Time fields
     date: 'field:date',
     datetime: 'field:datetime',
     time: 'field:time',
-    
+
     // Boolean
     boolean: 'field:boolean',
-    
+    toggle: 'field:boolean', // toggle is a boolean rendered as a switch
+
     // Selection fields
     select: 'field:select',
+    multiselect: 'field:multiselect',
+    radio: 'field:radio',
+    checkboxes: 'field:checkboxes',
+    tags: 'field:tags',
     lookup: 'field:lookup',
     master_detail: 'field:master_detail',
-    
+    tree: 'field:lookup', // hierarchical reference — pick the parent via a lookup
+
     // Contact fields
     email: 'field:email',
     phone: 'field:phone',
     url: 'field:url',
-    
-    // File fields
+
+    // File / media fields
     file: 'field:file',
     image: 'field:image',
-    
-    // Special fields
+    avatar: 'field:avatar',
+    video: 'field:file', // uploads as a file
+    audio: 'field:file', // uploads as a file
+    signature: 'field:signature',
+
+    // Special / enhanced fields
     password: 'field:password',
     location: 'field:location', // Location/map field (fallback to input)
-    
+    geolocation: 'field:geolocation',
+    address: 'field:address',
+    color: 'field:color',
+    code: 'field:code',
+    json: 'field:code', // JSON edited in the code editor
+    qrcode: 'field:qrcode',
+    vector: 'field:vector',
+
+    // Embedded structured values (stored as JSON on the row)
+    object: 'field:object',
+    composite: 'field:object', // embedded object
+    record: 'field:object', // name-keyed map
+    repeater: 'field:grid', // embedded array of rows
+
     // Auto-generated/computed fields (typically read-only)
     formula: 'field:formula',
     summary: 'field:summary',
@@ -1665,12 +1918,19 @@ const fieldWidgetMap: Record<string, () => Promise<{ default: React.ComponentTyp
   'phone': () => import('./widgets/PhoneField').then(m => ({ default: m.PhoneField })),
   'url': () => import('./widgets/UrlField').then(m => ({ default: m.UrlField })),
   
+  // Selection fields (multi-value / option groups)
+  'multiselect': () => import('./widgets/MultiSelectField').then(m => ({ default: m.MultiSelectField })),
+  'radio': () => import('./widgets/RadioField').then(m => ({ default: m.RadioField })),
+  'checkboxes': () => import('./widgets/CheckboxesField').then(m => ({ default: m.CheckboxesField })),
+  'tags': () => import('./widgets/TagsField').then(m => ({ default: m.TagsField })),
+
   // Specialized fields
   'currency': () => import('./widgets/CurrencyField').then(m => ({ default: m.CurrencyField })),
   'percent': () => import('./widgets/PercentField').then(m => ({ default: m.PercentField })),
   'password': () => import('./widgets/PasswordField').then(m => ({ default: m.PasswordField })),
   'markdown': () => import('./widgets/RichTextField').then(m => ({ default: m.RichTextField })),
   'html': () => import('./widgets/RichTextField').then(m => ({ default: m.RichTextField })),
+  'richtext': () => import('./widgets/RichTextField').then(m => ({ default: m.RichTextField })),
   'lookup': () => import('./widgets/LookupField').then(m => ({ default: m.LookupField })),
   // master_detail represents the child-side FK to its parent. In create/edit forms it
   // must render as a single-value lookup picker (it is typically NOT NULL). The legacy
@@ -1719,6 +1979,33 @@ const fieldWidgetMap: Record<string, () => Promise<{ default: React.ComponentTyp
  * // Register only the text field
  * registerField('text');
  */
+// Field types whose short name collides with a display/ui/view/plugin component
+// registered elsewhere (e.g. the display widgets and form-input primitives in
+// @object-ui/components, or the markdown display plugin). These remain
+// accessible via the namespaced `field:<type>` key — which is how forms resolve
+// them (see form.tsx renderFieldComponent + mapFieldTypeToFormType) — but must
+// not overwrite the bare `<type>` fallback, which the display/ui primitive owns
+// and which page schemas expect (e.g. `{ type: 'markdown', content }` → the
+// markdown renderer, not the RichText editor). Without skipFallback each of
+// these logged a "bare-name fallback is being overwritten" warning at boot.
+const FIELD_TYPES_SKIP_FALLBACK = new Set([
+  // Display widgets (text/html/image/avatar/grid live in @object-ui/components
+  // or @object-ui/layout as the bare-name owners).
+  'text',
+  'html',
+  'image',
+  'avatar',
+  'grid',
+  // Form-input primitives owned by `ui:*` in @object-ui/components.
+  'textarea',
+  'select',
+  'email',
+  'password',
+  'slider',
+  // Display renderer owned by `plugin-markdown:markdown`.
+  'markdown',
+]);
+
 export function registerField(fieldType: string): void {
   const loader = fieldWidgetMap[fieldType];
   if (!loader) {
@@ -1730,7 +2017,10 @@ export function registerField(fieldType: string): void {
   const LazyFieldWidget = React.lazy(loader);
   
   // Register with field namespace - NO WRAPPER to allow form renderer to control label/layout
-  ComponentRegistry.register(fieldType, LazyFieldWidget, { namespace: 'field' });
+  ComponentRegistry.register(fieldType, LazyFieldWidget, {
+    namespace: 'field',
+    skipFallback: FIELD_TYPES_SKIP_FALLBACK.has(fieldType),
+  });
 }
 
 /**
@@ -1755,26 +2045,43 @@ export function registerAllFields(): void {
  */
 export function registerFields() {
   // Basic fields - wrapped for documentation compatibility
-  ComponentRegistry.register('text', createFieldRenderer(TextField), { namespace: 'field' });
-  ComponentRegistry.register('textarea', createFieldRenderer(TextAreaField), { namespace: 'field' });
+  // `text` collides with the display text widget in @object-ui/components.
+  // Display semantics ({ type: 'text', content: '...' }) are the dominant
+  // usage across the docs/blocks catalog, so we keep this renderer accessible
+  // only via the namespaced `field:text` key and let the display widget win
+  // the bare `text` lookup.
+  ComponentRegistry.register('text', createFieldRenderer(TextField), { namespace: 'field', skipFallback: true });
+  // `textarea`/`select` collide with the `ui:*` form-input primitives that own
+  // the bare keys; namespaced-only (forms use `field:<type>`). See the shared
+  // FIELD_TYPES_SKIP_FALLBACK note above registerField().
+  ComponentRegistry.register('textarea', createFieldRenderer(TextAreaField), { namespace: 'field', skipFallback: true });
   ComponentRegistry.register('number', createFieldRenderer(NumberField), { namespace: 'field' });
   ComponentRegistry.register('boolean', createFieldRenderer(BooleanField), { namespace: 'field' });
-  ComponentRegistry.register('select', createFieldRenderer(SelectField), { namespace: 'field' });
+  ComponentRegistry.register('select', createFieldRenderer(SelectField), { namespace: 'field', skipFallback: true });
   ComponentRegistry.register('date', createFieldRenderer(DateField), { namespace: 'field' });
   ComponentRegistry.register('datetime', createFieldRenderer(DateTimeField), { namespace: 'field' });
   ComponentRegistry.register('time', createFieldRenderer(TimeField), { namespace: 'field' });
   
   // Contact fields - wrapped for documentation compatibility
-  ComponentRegistry.register('email', createFieldRenderer(EmailField), { namespace: 'field' });
+  // `email` collides with the `ui:email` input variant; namespaced-only so the
+  // display/input primitive keeps the bare key (forms use `field:email`).
+  ComponentRegistry.register('email', createFieldRenderer(EmailField), { namespace: 'field', skipFallback: true });
   ComponentRegistry.register('phone', createFieldRenderer(PhoneField), { namespace: 'field' });
   ComponentRegistry.register('url', createFieldRenderer(UrlField), { namespace: 'field' });
   
   // Specialized fields - wrapped for documentation compatibility
   ComponentRegistry.register('currency', createFieldRenderer(CurrencyField), { namespace: 'field' });
   ComponentRegistry.register('percent', createFieldRenderer(PercentField), { namespace: 'field' });
-  ComponentRegistry.register('password', createFieldRenderer(PasswordField), { namespace: 'field' });
-  ComponentRegistry.register('markdown', createFieldRenderer(RichTextField), { namespace: 'field' });
-  ComponentRegistry.register('html', createFieldRenderer(RichTextField), { namespace: 'field' });
+  // `password` collides with the `ui:password` input variant; namespaced-only.
+  ComponentRegistry.register('password', createFieldRenderer(PasswordField), { namespace: 'field', skipFallback: true });
+  // `markdown` collides with the markdown DISPLAY renderer (plugin-markdown:markdown),
+  // which owns bare `{ type: 'markdown', content }`; the field renderer here is the
+  // RichText editor, reached by forms via `field:markdown`. Namespaced-only.
+  ComponentRegistry.register('markdown', createFieldRenderer(RichTextField), { namespace: 'field', skipFallback: true });
+  // `html` collides with the HTML-rendering display widget. Keep the
+  // markdown field, but expose the HTML field only via `field:html` so the
+  // display widget remains the default for { type: 'html', content }.
+  ComponentRegistry.register('html', createFieldRenderer(RichTextField), { namespace: 'field', skipFallback: true });
   ComponentRegistry.register('lookup', createFieldRenderer(LookupField), { namespace: 'field' });
   // master_detail = child-side FK lookup (single value, typically required). See
   // fieldWidgetMap above for rationale.
@@ -1782,7 +2089,8 @@ export function registerFields() {
   
   // File fields
   ComponentRegistry.register('file', createFieldRenderer(FileField), { namespace: 'field' });
-  ComponentRegistry.register('image', createFieldRenderer(ImageField), { namespace: 'field' });
+  // `image` collides with the display image widget; namespaced-only.
+  ComponentRegistry.register('image', createFieldRenderer(ImageField), { namespace: 'field', skipFallback: true });
   
   // Location field
   ComponentRegistry.register('location', createFieldRenderer(LocationField), { namespace: 'field' });
@@ -1799,14 +2107,17 @@ export function registerFields() {
   // Complex data types
   ComponentRegistry.register('object', createFieldRenderer(ObjectField), { namespace: 'field' });
   ComponentRegistry.register('vector', createFieldRenderer(VectorField), { namespace: 'field' });
-  ComponentRegistry.register('grid', createFieldRenderer(GridField), { namespace: 'field' });
+  // `grid` collides with the layout grid component; namespaced-only.
+  ComponentRegistry.register('grid', createFieldRenderer(GridField), { namespace: 'field', skipFallback: true });
   
   // NEW: Additional field types from @objectstack/spec
   ComponentRegistry.register('color', createFieldRenderer(ColorField), { namespace: 'field' });
-  ComponentRegistry.register('slider', createFieldRenderer(SliderField), { namespace: 'field' });
+  // `slider` collides with the `ui:slider` display control; namespaced-only.
+  ComponentRegistry.register('slider', createFieldRenderer(SliderField), { namespace: 'field', skipFallback: true });
   ComponentRegistry.register('rating', createFieldRenderer(RatingField), { namespace: 'field' });
   ComponentRegistry.register('code', createFieldRenderer(CodeField), { namespace: 'field' });
-  ComponentRegistry.register('avatar', createFieldRenderer(AvatarField), { namespace: 'field' });
+  // `avatar` collides with the display avatar widget; namespaced-only.
+  ComponentRegistry.register('avatar', createFieldRenderer(AvatarField), { namespace: 'field', skipFallback: true });
   ComponentRegistry.register('address', createFieldRenderer(AddressField), { namespace: 'field' });
   ComponentRegistry.register('geolocation', createFieldRenderer(GeolocationField), { namespace: 'field' });
   ComponentRegistry.register('signature', createFieldRenderer(SignatureField), { namespace: 'field' });
@@ -1854,6 +2165,10 @@ export * from './widgets/GeolocationField';
 export * from './widgets/SignatureField';
 export * from './widgets/QRCodeField';
 export * from './widgets/MasterDetailField';
+export * from './widgets/MultiSelectField';
+export * from './widgets/RadioField';
+export * from './widgets/CheckboxesField';
+export * from './widgets/TagsField';
 
 // Initialize registry
 registerAllFields();