@object-ui/fields 6.2.2 → 7.0.0

package/dist/index.d.ts

@@ -1,2 +1,300 @@
-export * from './packages/fields/src/index'
-export {}
+import { default as React } from 'react';
+import { FieldMetadata } from '@object-ui/types';
+import { resolveFieldCurrency } from './currency';
+/**
+ * Heuristic: detect strings that look like opaque foreign-key IDs (e.g. nanoid
+ * or BSON ObjectId). Used so we don't display random gibberish to users when
+ * a lookup wasn't expanded.
+ */
+export declare function isLikelyOpaqueId(v: unknown): boolean;
+/**
+ * Cell renderer props
+ */
+export interface CellRendererProps {
+    value: any;
+    field: FieldMetadata;
+    isEditing?: boolean;
+    onChange?: (value: any) => void;
+}
+/**
+ * Coerce a value to a safe primitive for rendering.
+ * Handles MongoDB wrapper types ($numberDecimal, $oid, $date), expanded
+ * reference objects, and arrays so that no raw object is ever passed as
+ * a React child — preventing React error #310.
+ */
+export declare function coerceToSafeValue(value: unknown): string | number | boolean | null | undefined;
+export { resolveFieldCurrency };
+export declare function formatCurrency(value: number, currency?: string): string;
+/**
+ * Format currency value in compact form for mobile display.
+ * E.g., $150,000 → $150K, $1,200,000 → $1.2M
+ * When `currency` is undefined, returns a compact number without symbol.
+ */
+export declare function formatCompactCurrency(value: number, currency?: string): string;
+/**
+ * Format a plain number with thousands separators, no currency symbol.
+ * Used as a safe fallback when a currency-typed field has no `currency`
+ * configured — we'd rather render `1,234.50` than silently assume USD.
+ */
+export declare function formatNumber(value: number, decimals?: number): string;
+/**
+ * Format percent value
+ * Handles both decimal (0.8 = 80%) and whole number (80 = 80%) inputs.
+ */
+export declare function formatPercent(value: number, precision?: number): string;
+/**
+ * Humanize a snake_case or kebab-case string into Title Case.
+ * Used as fallback label when no explicit option.label exists.
+ *
+ * Examples:
+ *   "in_progress" → "In Progress"
+ *   "high-priority" → "High Priority"
+ *   "active" → "Active"
+ */
+export declare function humanizeLabel(value: string): string;
+/**
+ * Format date as relative time (e.g., "2 days ago", "Today", "Overdue 3d")
+ */
+export declare function formatRelativeDate(value: string | Date | number): string;
+/**
+ * Format date value
+ */
+export declare function formatDate(value: string | Date | number, style?: string): string;
+/**
+ * Format datetime value
+ */
+export declare function formatDateTime(value: string | Date | number): string;
+/**
+ * Text field cell renderer
+ */
+export declare function TextCellRenderer({ value }: CellRendererProps): React.ReactElement;
+/**
+ * Number field cell renderer
+ */
+export declare function NumberCellRenderer({ value, field }: CellRendererProps): React.ReactElement;
+/**
+ * Currency field cell renderer
+ */
+export declare function CurrencyCellRenderer({ value, field }: CellRendererProps): React.ReactElement;
+/**
+ * Percent field cell renderer with mini progress bar
+ */
+export declare function PercentCellRenderer({ value, field }: CellRendererProps): React.ReactElement;
+/**
+ * Boolean field cell renderer (Airtable-style checkbox)
+ * Supports semantic rendering for completion fields (green indicator)
+ * and warning badge for active/enabled fields when false.
+ */
+export declare function BooleanCellRenderer({ value, field }: CellRendererProps): React.ReactElement;
+/**
+ * Date field cell renderer
+ */
+export declare function DateCellRenderer({ value, field }: CellRendererProps): React.ReactElement;
+/**
+ * DateTime field cell renderer (Airtable-style with date and time visually separated)
+ */
+export declare function DateTimeCellRenderer({ value }: CellRendererProps): React.ReactElement;
+export declare function getBadgeColorClasses(color?: string, val?: unknown): string;
+/**
+ * Resolve a semantic color name (e.g. "red", "green") for a value, suitable
+ * for callers that need a raw color token rather than CSS classes (for
+ * example, the Gantt renderer paints bars via inline styles).
+ *
+ * Resolution order: explicit option color → semantic value mapping →
+ * deterministic hash fallback. Returns `undefined` only when no value is
+ * supplied so the caller can fall back to its own default.
+ */
+export declare function getSemanticColorName(color?: string, val?: unknown): string | undefined;
+/**
+ * Map a semantic color name to its Tailwind -500 hex value. Used by
+ * inline-style consumers (Gantt bars). Falls back to the supplied default
+ * (or the platform default blue) when the name is unrecognized.
+ */
+export declare function getSemanticHex(name?: string, fallback?: string): string;
+/**
+ * Select field cell renderer.
+ *
+ * Two visual styles, controlled by `field.appearance` (renderer-level option,
+ * not part of the `@objectstack/spec` field schema):
+ *   - `'badge'` (default for spec compatibility): soft-pill colored badge.
+ *   - `'dot'`: a small colored dot followed by the option label. Used by
+ *     dense list/grid contexts to keep the table visually quiet — repeated
+ *     filled badges across many rows create heavy visual noise.
+ *
+ * Metadata always wins: callers can pass `appearance: 'badge'` on the field
+ * descriptor to force the legacy badge in any context.
+ */
+export declare function SelectCellRenderer({ value, field }: CellRendererProps): React.ReactElement;
+/**
+ * Email field cell renderer
+ */
+export declare function EmailCellRenderer({ value }: CellRendererProps): React.ReactElement;
+/**
+ * URL field cell renderer
+ */
+export declare function UrlCellRenderer({ value }: CellRendererProps): React.ReactElement;
+/**
+ * Phone field cell renderer
+ */
+export declare function PhoneCellRenderer({ value }: CellRendererProps): React.ReactElement;
+/**
+ * File field cell renderer
+ */
+export declare function FileCellRenderer({ value, field }: CellRendererProps): React.ReactElement;
+/**
+ * Image field cell renderer (with thumbnails)
+ */
+export declare function ImageCellRenderer({ value }: CellRendererProps): React.ReactElement;
+/**
+ * Lookup/Master-Detail field cell renderer.
+ *
+ * Display order:
+ * 1. Embedded record object (`{ id, name, ... }` from `$expand`) → use its name
+ * 2. Static `field.options[]` (e.g. when the lookup is a closed enum) → look up label
+ * 3. Fetch-on-demand: when the value is a primitive ID and `field.reference_to`
+ *    is known, resolve via dataSource and show the related record's display name.
+ *    Falls back to a muted placeholder while pending and on failure.
+ */
+export declare function LookupCellRenderer({ value, field }: CellRendererProps): React.ReactElement;
+/**
+ * Formula field cell renderer (read-only)
+ */
+export declare function FormulaCellRenderer({ value }: CellRendererProps): React.ReactElement;
+/**
+ * User/Owner field cell renderer (with avatars)
+ */
+export declare function UserCellRenderer({ value }: CellRendererProps): React.ReactElement;
+/**
+ * Register a custom field renderer
+ * @param type Field type (e.g. 'text', 'location', 'my-custom-type')
+ * @param renderer React component to render the field
+ */
+export declare function registerFieldRenderer(type: string, renderer: React.FC<CellRendererProps>): void;
+/**
+ * Resolve the canonical cell-renderer key for a field. Accepts either a
+ * raw type string (back-compat) or a field-metadata object so that
+ * format hints (`format: 'phone'` etc.) can promote a plain `text`
+ * field to its richer renderer counterpart.
+ */
+export declare function resolveCellRendererType(fieldOrType: string | {
+    type?: string;
+    format?: string;
+} | null | undefined): string;
+/**
+ * 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 declare function JsonCellRenderer({ value }: CellRendererProps): React.ReactElement;
+/**
+ * Renders a `color` value as a swatch alongside its hex/string value.
+ */
+export declare function ColorSwatchCellRenderer({ value }: CellRendererProps): React.ReactElement;
+/**
+ * Renders `markdown` / `richtext` values as formatted GFM markdown (lazy-loaded,
+ * sanitized) instead of the raw markup string.
+ */
+export declare function MarkdownCellRenderer({ value }: CellRendererProps): React.ReactElement;
+/**
+ * Renders an `html` value as sanitized, formatted HTML instead of raw markup.
+ */
+export declare function HtmlCellRenderer({ value }: CellRendererProps): React.ReactElement;
+/**
+ * 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 declare function LocationCellRenderer({ value }: CellRendererProps): React.ReactElement;
+/**
+ * Get the appropriate cell renderer for a field type
+ */
+export declare function getCellRenderer(fieldType: string): React.FC<CellRendererProps>;
+/**
+ * Map field type to form component type
+ *
+ * @param fieldType - The ObjectQL field type identifier to convert
+ * (for example: `"text"`, `"number"`, `"date"`, `"lookup"`).
+ * @returns The normalized form field type string used in the form schema
+ * (for example: `"input"`, `"textarea"`, `"date-picker"`, `"select"`).
+ */
+export declare function mapFieldTypeToFormType(fieldType: string): string;
+/**
+ * Formats file size in bytes to human-readable string
+ * @param bytes - File size in bytes (must be non-negative)
+ * @returns Formatted string (e.g., "5 MB", "1.5 GB")
+ */
+export declare function formatFileSize(bytes: number): string;
+/**
+ * Build validation rules from field metadata
+ * @param field - Field metadata from ObjectStack
+ * @returns Validation rule object compatible with react-hook-form
+ */
+export declare function buildValidationRules(field: any): any;
+/**
+ * Evaluate a conditional expression for field visibility
+ * @param condition - Condition object from field metadata
+ * @param formData - Current form values
+ * @returns Whether the condition is met
+ */
+export declare function evaluateCondition(condition: any, formData: any): boolean;
+export declare function registerField(fieldType: string): void;
+/**
+ * Register all field types (for backward compatibility)
+ * This function auto-registers all field widgets on import.
+ *
+ * For better tree-shaking, use registerField() to register only needed fields.
+ *
+ * @example
+ * // Register all fields at once
+ * registerAllFields();
+ */
+export declare function registerAllFields(): void;
+/**
+ * Legacy function - kept for backward compatibility
+ * @deprecated Use registerAllFields() instead
+ */
+export declare function registerFields(): void;
+export * from './widgets/types';
+export * from './widgets/TextField';
+export * from './widgets/NumberField';
+export * from './widgets/BooleanField';
+export * from './widgets/SelectField';
+export * from './widgets/DateField';
+export * from './widgets/DateTimeField';
+export * from './widgets/TimeField';
+export * from './widgets/EmailField';
+export * from './widgets/PhoneField';
+export * from './widgets/UrlField';
+export * from './widgets/CurrencyField';
+export * from './widgets/PercentField';
+export * from './widgets/PasswordField';
+export * from './widgets/TextAreaField';
+export * from './widgets/RichTextField';
+export * from './widgets/LookupField';
+export * from './widgets/RecordPickerDialog';
+export * from './widgets/FileField';
+export * from './widgets/ImageField';
+export { ImageCropperDialog } from './widgets/ImageCropperDialog';
+export type { ImageCropperDialogProps } from './widgets/ImageCropperDialog';
+export * from './widgets/LocationField';
+export * from './widgets/FormulaField';
+export * from './widgets/SummaryField';
+export * from './widgets/AutoNumberField';
+export * from './widgets/UserField';
+export * from './widgets/ObjectField';
+export * from './widgets/VectorField';
+export * from './widgets/GridField';
+export * from './widgets/ColorField';
+export * from './widgets/SliderField';
+export * from './widgets/RatingField';
+export * from './widgets/CodeField';
+export * from './widgets/AvatarField';
+export * from './widgets/AddressField';
+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';