@object-ui/fields 0.5.0 → 3.0.0

package/src/fields-edge-cases.stories.tsx

@@ -0,0 +1,407 @@
+/**
+ * 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 { Meta, StoryObj } from '@storybook/react';
+import React, { useState } from 'react';
+import {
+  TextField,
+  NumberField,
+  SelectField,
+  CurrencyField,
+  EmailField,
+  TextAreaField,
+  BooleanField,
+  UrlField,
+} from './index';
+import { FieldMetadata } from '@object-ui/types';
+
+/**
+ * **Field Widgets – Edge Cases** from `@object-ui/fields`.
+ *
+ * Stories that exercise boundary conditions: empty values, overflow text,
+ * RTL content, emoji-only input, error states, disabled state, and readonly
+ * variants across multiple field types.
+ */
+const meta = {
+  title: 'Fields/Edge Cases',
+  parameters: {
+    layout: 'centered',
+  },
+  tags: ['autodocs'],
+  argTypes: {
+    readonly: { control: 'boolean', description: 'Toggle readonly mode' },
+    disabled: { control: 'boolean', description: 'Toggle disabled mode' },
+  },
+} satisfies Meta;
+
+export default meta;
+type Story = StoryObj<any>;
+
+// Wrapper to handle state since these are controlled components
+const FieldWrapper = ({
+  Component,
+  field,
+  initialValue,
+  readonly = false,
+  disabled = false,
+  errorMessage,
+}: {
+  Component: any;
+  field: Partial<FieldMetadata>;
+  initialValue?: any;
+  readonly?: boolean;
+  disabled?: boolean;
+  errorMessage?: string;
+}) => {
+  const [value, setValue] = useState(initialValue);
+
+  const fullField = {
+    name: 'test_field',
+    label: 'Test Field',
+    type: 'text',
+    ...field,
+  } as FieldMetadata;
+
+  return (
+    <div className="w-[350px] space-y-2 p-4 border rounded-lg shadow-sm bg-white">
+      <div className="flex justify-between items-center mb-2">
+        <label className="text-sm font-semibold text-gray-700">{fullField.label}</label>
+        {readonly && (
+          <span className="text-[10px] bg-slate-100 px-2 py-0.5 rounded text-slate-500 font-medium">
+            Read Only
+          </span>
+        )}
+        {disabled && (
+          <span className="text-[10px] bg-slate-100 px-2 py-0.5 rounded text-slate-500 font-medium">
+            Disabled
+          </span>
+        )}
+      </div>
+
+      <Component
+        value={value}
+        onChange={(val: any) => {
+          console.log('onChange', val);
+          setValue(val);
+        }}
+        field={fullField}
+        readonly={readonly}
+        disabled={disabled}
+        errorMessage={errorMessage}
+      />
+
+      {errorMessage && (
+        <div className="text-xs text-destructive mt-1">{errorMessage}</div>
+      )}
+
+      {!readonly && (
+        <div className="text-xs text-muted-foreground mt-4 pt-2 border-t font-mono overflow-hidden text-ellipsis">
+          Value: {JSON.stringify(value)}
+        </div>
+      )}
+    </div>
+  );
+};
+
+// ---------------------------------------------------------------------------
+// 1. Empty / Null / Undefined Values
+// ---------------------------------------------------------------------------
+
+export const EmptyText: Story = {
+  name: 'Empty – Text (undefined)',
+  render: () => (
+    <FieldWrapper
+      Component={TextField}
+      field={{ label: 'Empty Text', type: 'text', placeholder: 'Type here…' }}
+      initialValue={undefined}
+    />
+  ),
+};
+
+export const NullNumber: Story = {
+  name: 'Empty – Number (null)',
+  render: () => (
+    <FieldWrapper
+      Component={NumberField}
+      field={{ label: 'Null Number', type: 'number', precision: 2 }}
+      initialValue={null}
+    />
+  ),
+};
+
+export const EmptySelect: Story = {
+  name: 'Empty – Select (empty string)',
+  render: () => (
+    <FieldWrapper
+      Component={SelectField}
+      field={{
+        label: 'No Selection',
+        type: 'select',
+        options: [
+          { label: 'Option A', value: 'a' },
+          { label: 'Option B', value: 'b' },
+        ],
+      }}
+      initialValue=""
+    />
+  ),
+};
+
+// ---------------------------------------------------------------------------
+// 2. Very Long Strings (overflow handling)
+// ---------------------------------------------------------------------------
+
+const LONG_STRING =
+  'Lorem ipsum dolor sit amet, consectetur adipiscing elit. '.repeat(20).trim();
+
+export const LongText: Story = {
+  name: 'Overflow – Long Text',
+  render: () => (
+    <FieldWrapper
+      Component={TextField}
+      field={{ label: 'Long Value', type: 'text' }}
+      initialValue={LONG_STRING}
+    />
+  ),
+};
+
+export const LongTextArea: Story = {
+  name: 'Overflow – Long TextArea',
+  render: () => (
+    <FieldWrapper
+      Component={TextAreaField}
+      field={{ label: 'Long TextArea', type: 'textarea', rows: 4 }}
+      initialValue={LONG_STRING}
+    />
+  ),
+};
+
+export const LongUrl: Story = {
+  name: 'Overflow – Long URL',
+  render: () => (
+    <FieldWrapper
+      Component={UrlField}
+      field={{ label: 'Long URL', type: 'url' }}
+      initialValue={`https://example.com/${'segment/'.repeat(50)}`}
+    />
+  ),
+};
+
+// ---------------------------------------------------------------------------
+// 3. RTL Text (Arabic)
+// ---------------------------------------------------------------------------
+
+export const RTLText: Story = {
+  name: 'RTL – Arabic Text',
+  render: () => (
+    <FieldWrapper
+      Component={TextField}
+      field={{ label: 'Arabic Input', type: 'text' }}
+      initialValue="مرحبا بالعالم — هذا نص عربي طويل لاختبار الاتجاه"
+    />
+  ),
+};
+
+export const RTLTextArea: Story = {
+  name: 'RTL – Arabic TextArea',
+  render: () => (
+    <FieldWrapper
+      Component={TextAreaField}
+      field={{ label: 'Arabic TextArea', type: 'textarea', rows: 3 }}
+      initialValue="هذا نص عربي يمتد على عدة أسطر.\nالسطر الثاني هنا.\nالسطر الثالث."
+    />
+  ),
+};
+
+// ---------------------------------------------------------------------------
+// 4. Emoji-Only Values
+// ---------------------------------------------------------------------------
+
+export const EmojiText: Story = {
+  name: 'Emoji – Text Field',
+  render: () => (
+    <FieldWrapper
+      Component={TextField}
+      field={{ label: 'Emoji Only', type: 'text' }}
+      initialValue="🚀🔥✨💯🎉🌍"
+    />
+  ),
+};
+
+export const EmojiEmail: Story = {
+  name: 'Emoji – Email Field (invalid)',
+  render: () => (
+    <FieldWrapper
+      Component={EmailField}
+      field={{ label: 'Emoji Email', type: 'email' }}
+      initialValue="🚀@emoji.com"
+    />
+  ),
+};
+
+// ---------------------------------------------------------------------------
+// 5. Error State (with errorMessage prop)
+// ---------------------------------------------------------------------------
+
+export const ErrorText: Story = {
+  name: 'Error – Text Field',
+  render: () => (
+    <FieldWrapper
+      Component={TextField}
+      field={{ label: 'Name', type: 'text', placeholder: 'Required field' }}
+      initialValue=""
+      errorMessage="This field is required."
+    />
+  ),
+};
+
+export const ErrorNumber: Story = {
+  name: 'Error – Number Field',
+  render: () => (
+    <FieldWrapper
+      Component={NumberField}
+      field={{ label: 'Age', type: 'number', precision: 0 }}
+      initialValue={-5}
+      errorMessage="Value must be a positive number."
+    />
+  ),
+};
+
+export const ErrorSelect: Story = {
+  name: 'Error – Select Field',
+  render: () => (
+    <FieldWrapper
+      Component={SelectField}
+      field={{
+        label: 'Priority',
+        type: 'select',
+        options: [
+          { label: 'Low', value: 'low' },
+          { label: 'Medium', value: 'medium' },
+          { label: 'High', value: 'high' },
+        ],
+      }}
+      initialValue=""
+      errorMessage="Please select a priority."
+    />
+  ),
+};
+
+// ---------------------------------------------------------------------------
+// 6. Disabled State
+// ---------------------------------------------------------------------------
+
+export const DisabledText: Story = {
+  name: 'Disabled – Text Field',
+  render: () => (
+    <FieldWrapper
+      Component={TextField}
+      field={{ label: 'Locked Name', type: 'text' }}
+      initialValue="Cannot change this"
+      disabled={true}
+    />
+  ),
+};
+
+export const DisabledNumber: Story = {
+  name: 'Disabled – Number Field',
+  render: () => (
+    <FieldWrapper
+      Component={NumberField}
+      field={{ label: 'Locked Qty', type: 'number', precision: 0 }}
+      initialValue={100}
+      disabled={true}
+    />
+  ),
+};
+
+export const DisabledSelect: Story = {
+  name: 'Disabled – Select Field',
+  render: () => (
+    <FieldWrapper
+      Component={SelectField}
+      field={{
+        label: 'Locked Status',
+        type: 'select',
+        options: [
+          { label: 'Active', value: 'active' },
+          { label: 'Inactive', value: 'inactive' },
+        ],
+      }}
+      initialValue="active"
+      disabled={true}
+    />
+  ),
+};
+
+export const DisabledBoolean: Story = {
+  name: 'Disabled – Boolean Field',
+  render: () => (
+    <FieldWrapper
+      Component={BooleanField}
+      field={{ label: 'Locked Toggle', type: 'boolean' }}
+      initialValue={true}
+      disabled={true}
+    />
+  ),
+};
+
+// ---------------------------------------------------------------------------
+// 7. Readonly State with Various Field Types
+// ---------------------------------------------------------------------------
+
+export const ReadonlyGallery: Story = {
+  name: 'Readonly – Multiple Fields',
+  render: () => (
+    <div className="flex flex-col gap-4">
+      <FieldWrapper
+        Component={TextField}
+        field={{ label: 'Read Only Text', type: 'text' }}
+        initialValue="Immutable value"
+        readonly={true}
+      />
+      <FieldWrapper
+        Component={NumberField}
+        field={{ label: 'Read Only Number', type: 'number', precision: 2 }}
+        initialValue={3.14}
+        readonly={true}
+      />
+      <FieldWrapper
+        Component={CurrencyField}
+        field={{ label: 'Read Only Currency', type: 'currency', currency: 'USD', precision: 2 }}
+        initialValue={9999.99}
+        readonly={true}
+      />
+      <FieldWrapper
+        Component={SelectField}
+        field={{
+          label: 'Read Only Select',
+          type: 'select',
+          options: [
+            { label: 'Active', value: 'active' },
+            { label: 'Archived', value: 'archived' },
+          ],
+        }}
+        initialValue="active"
+        readonly={true}
+      />
+      <FieldWrapper
+        Component={BooleanField}
+        field={{ label: 'Read Only Boolean', type: 'boolean' }}
+        initialValue={false}
+        readonly={true}
+      />
+      <FieldWrapper
+        Component={EmailField}
+        field={{ label: 'Read Only Email', type: 'email' }}
+        initialValue="admin@example.com"
+        readonly={true}
+      />
+    </div>
+  ),
+};

package/src/index.tsx

@@ -76,9 +76,12 @@ export function formatCurrency(value: number, currency: string = 'USD'): string
 
 /**
  * Format percent value
+ * Handles both decimal (0.8 = 80%) and whole number (80 = 80%) inputs.
  */
-export function formatPercent(value: number, precision: number = 2): string {
-  return `${(value * 100).toFixed(precision)}%`;
+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;
+  return `${displayValue.toFixed(precision)}%`;
 }
 
 /**
@@ -125,11 +128,13 @@ export function TextCellRenderer({ value }: CellRendererProps): React.ReactEleme
  * Number field cell renderer
  */
 export function NumberCellRenderer({ value, field }: CellRendererProps): React.ReactElement {
-  if (value == null) return <span>-</span>;
+  if (value == null) return <span className="text-muted-foreground">-</span>;
   
   const numField = field as any;
   const precision = numField.precision ?? 0;
-  const formatted = typeof value === 'number' ? value.toFixed(precision) : value;
+  const formatted = typeof value === 'number'
+    ? new Intl.NumberFormat('en-US', { minimumFractionDigits: precision, maximumFractionDigits: precision }).format(value)
+    : value;
   
   return <span className="tabular-nums">{formatted}</span>;
 }
@@ -138,26 +143,46 @@ export function NumberCellRenderer({ value, field }: CellRendererProps): React.R
  * Currency field cell renderer
  */
 export function CurrencyCellRenderer({ value, field }: CellRendererProps): React.ReactElement {
-  if (value == null) return <span>-</span>;
+  if (value == null) return <span className="text-muted-foreground">-</span>;
   
   const currencyField = field as any;
   const currency = currencyField.currency || 'USD';
   const formatted = formatCurrency(Number(value), currency);
   
-  return <span className="tabular-nums font-medium">{formatted}</span>;
+  return <span className="tabular-nums font-medium whitespace-nowrap">{formatted}</span>;
 }
 
 /**
- * Percent field cell renderer
+ * Percent field cell renderer with mini progress bar
  */
 export function PercentCellRenderer({ value, field }: CellRendererProps): React.ReactElement {
-  if (value == null) return <span>-</span>;
+  if (value == null) return <span className="text-muted-foreground">-</span>;
   
   const percentField = field as any;
-  const precision = percentField.precision ?? 2;
-  const formatted = formatPercent(Number(value), precision);
+  const precision = percentField.precision ?? 0;
+  const numValue = Number(value);
+  const formatted = formatPercent(numValue, precision);
+  // Normalize to 0-100 range for progress bar
+  const barValue = (numValue > -1 && numValue < 1) ? numValue * 100 : numValue;
+  const clampedBar = Math.max(0, Math.min(100, barValue));
   
-  return <span className="tabular-nums">{formatted}</span>;
+  return (
+    <div className="flex items-center gap-2">
+      <div
+        className="h-1.5 w-16 rounded-full bg-muted overflow-hidden flex-shrink-0"
+        role="progressbar"
+        aria-valuenow={clampedBar}
+        aria-valuemin={0}
+        aria-valuemax={100}
+      >
+        <div
+          className="h-full rounded-full bg-primary transition-all"
+          style={{ width: `${clampedBar}%` }}
+        />
+      </div>
+      <span className="tabular-nums whitespace-nowrap">{formatted}</span>
+    </div>
+  );
 }
 
 /**

package/src/widgets/BooleanField.tsx

@@ -2,6 +2,10 @@ import React, { useId } from 'react';
 import { Switch, Checkbox, Label } from '@object-ui/components';
 import { FieldWidgetProps } from './types';
 
+/**
+ * BooleanField - Toggle input supporting switch and checkbox variants
+ * Renders as Switch or Checkbox based on field widget configuration
+ */
 export function BooleanField({ value, onChange, field, readonly, ...props }: FieldWidgetProps<boolean>) {
   const config = (field || (props as any).schema) as any;
   // Use simple type assertion for arbitrary custom properties not in BaseFieldMetadata

package/src/widgets/DateField.tsx

@@ -2,6 +2,10 @@ import React from 'react';
 import { Input } from '@object-ui/components';
 import { FieldWidgetProps } from './types';
 
+/**
+ * DateField - Date picker input widget
+ * Uses native date input and displays locale-formatted date in readonly mode
+ */
 export function DateField({ value, onChange, field, readonly, ...props }: FieldWidgetProps<string>) {
   if (readonly) {
     return <span className="text-sm">{value ? new Date(value).toLocaleDateString() : '-'}</span>;

package/src/widgets/DateTimeField.tsx

@@ -2,6 +2,10 @@ import React from 'react';
 import { Input } from '@object-ui/components';
 import { FieldWidgetProps } from './types';
 
+/**
+ * DateTimeField - Combined date and time picker widget
+ * Displays both date and time in locale format when readonly
+ */
 export function DateTimeField({ value, onChange, field, readonly, ...props }: FieldWidgetProps<string>) {
   if (readonly) {
     if (!value) return <span className="text-sm">-</span>;

package/src/widgets/EmailField.tsx

@@ -2,6 +2,10 @@ import React from 'react';
 import { Input } from '@object-ui/components';
 import { FieldWidgetProps } from './types';
 
+/**
+ * EmailField - Email address input with mailto link in readonly mode
+ * Renders as a clickable mailto link when readonly, standard email input otherwise
+ */
 export function EmailField({ value, onChange, field, readonly, errorMessage, ...props }: FieldWidgetProps<string>) {
   const config = field || (props as any).schema;
   if (readonly) {

package/src/widgets/FileField.tsx

@@ -3,6 +3,10 @@ import { Button } from '@object-ui/components';
 import { Upload, X, File as FileIcon } from 'lucide-react';
 import { FieldWidgetProps } from './types';
 
+/**
+ * FileField - File upload widget with drag-and-drop support
+ * Supports single and multiple file uploads with configurable accepted file types
+ */
 export function FileField({ value, onChange, field, readonly, ...props }: FieldWidgetProps<any>) {
   const inputRef = useRef<HTMLInputElement>(null);
   const fileField = (field || (props as any).schema) as any;

package/src/widgets/ImageField.tsx

@@ -3,6 +3,10 @@ import { Button } from '@object-ui/components';
 import { Upload, X, Image as ImageIcon } from 'lucide-react';
 import { FieldWidgetProps } from './types';
 
+/**
+ * ImageField - Image upload widget with preview thumbnails
+ * Supports single and multiple image uploads with drag-and-drop and preview display
+ */
 export function ImageField({ value, onChange, field, readonly, ...props }: FieldWidgetProps<any>) {
   const inputRef = useRef<HTMLInputElement>(null);
   const imageField = (field || (props as any).schema) as any;

package/src/widgets/LocationField.tsx

@@ -2,6 +2,10 @@ import React from 'react';
 import { Input } from '@object-ui/components';
 import { FieldWidgetProps } from './types';
 
+/**
+ * LocationField - Geographic coordinate input for latitude and longitude
+ * Stores location as { latitude, longitude } object and displays as comma-separated pair
+ */
 export function LocationField({ value, onChange, field, readonly, ...props }: FieldWidgetProps<any>) {
   const config = field || (props as any).schema;
   // Location is stored as { latitude, longitude } object

package/src/widgets/NumberField.tsx

@@ -3,6 +3,10 @@ import { Input } from '@object-ui/components';
 import { NumberFieldMetadata } from '@object-ui/types';
 import { FieldWidgetProps } from './types';
 
+/**
+ * NumberField - Numeric input with optional decimal precision
+ * Supports min/max/step constraints and configurable decimal precision
+ */
 export function NumberField({ value, onChange, field, readonly, ...props }: FieldWidgetProps<number>) {
   if (readonly) {
     return <span className="text-sm">{value ?? '-'}</span>;

package/src/widgets/PasswordField.tsx

@@ -4,6 +4,10 @@ import { Button } from '@object-ui/components';
 import { Eye, EyeOff } from 'lucide-react';
 import { FieldWidgetProps } from './types';
 
+/**
+ * PasswordField - Secure password input with visibility toggle
+ * Includes show/hide toggle button and masks value in readonly mode
+ */
 export function PasswordField({ value, onChange, field, readonly, className, ...props }: FieldWidgetProps<string>) {
   const [showPassword, setShowPassword] = useState(false);
   const config = field || (props as any).schema;

package/src/widgets/PercentField.tsx

@@ -2,6 +2,10 @@ import React from 'react';
 import { Input } from '@object-ui/components';
 import { FieldWidgetProps } from './types';
 
+/**
+ * PercentField - Percentage input with configurable decimal precision
+ * Stores values as decimals (0-1) and displays as percentages (0-100%)
+ */
 export function PercentField({ value, onChange, field, readonly, errorMessage, className, ...props }: FieldWidgetProps<number>) {
   const percentField = (field || (props as any).schema) as any;
   const precision = percentField?.precision ?? 2;

package/src/widgets/PhoneField.tsx

@@ -2,6 +2,10 @@ import React from 'react';
 import { Input } from '@object-ui/components';
 import { FieldWidgetProps } from './types';
 
+/**
+ * PhoneField - Telephone number input with tel link in readonly mode
+ * Renders as a clickable tel link when readonly, standard phone input otherwise
+ */
 export function PhoneField({ value, onChange, field, readonly, errorMessage, ...props }: FieldWidgetProps<string>) {
   const config = field || (props as any).schema;
   if (readonly) {

package/src/widgets/SelectField.tsx

@@ -9,6 +9,10 @@ import {
 import { SelectFieldMetadata } from '@object-ui/types';
 import { FieldWidgetProps } from './types';
 
+/**
+ * SelectField - Dropdown selection widget with configurable options
+ * Renders options from field metadata with support for placeholder and readonly display
+ */
 export function SelectField({ value, onChange, field, readonly, ...props }: FieldWidgetProps<string>) {
   const config = (field || (props as any).schema) as SelectFieldMetadata;
   const options = config?.options || [];

package/src/widgets/SignatureField.tsx

@@ -94,7 +94,7 @@ export function SignatureField({ value, onChange, readonly }: FieldWidgetProps<s
   if (readonly && value) {
     return (
       <div className="border rounded p-2 bg-white">
-        <img src={value} alt="Signature" className="max-w-full h-auto" />
+        <img src={value} alt="Signature" loading="lazy" className="max-w-full h-auto" />
       </div>
     );
   }

package/src/widgets/TextAreaField.tsx

@@ -2,6 +2,10 @@ import React from 'react';
 import { Textarea } from '@object-ui/components';
 import { FieldWidgetProps } from './types';
 
+/**
+ * TextAreaField - Multi-line text input widget
+ * Supports configurable row count and preserves whitespace in readonly mode
+ */
 export function TextAreaField({ value, onChange, field, readonly, errorMessage, ...props }: FieldWidgetProps<string>) {
   if (readonly) {
     return (

package/src/widgets/TextField.tsx

@@ -3,6 +3,10 @@ import { Input, Textarea } from '@object-ui/components';
 import { TextareaFieldMetadata } from '@object-ui/types';
 import { FieldWidgetProps } from './types';
 
+/**
+ * TextField - Standard single-line or multi-line text input
+ * Automatically renders as a textarea when rows are configured in field metadata
+ */
 export function TextField({ value, onChange, field, readonly, ...props }: FieldWidgetProps<string>) {
   const fieldData = field || (props as any).schema;
 

package/src/widgets/TimeField.tsx

@@ -2,6 +2,10 @@ import React from 'react';
 import { Input } from '@object-ui/components';
 import { FieldWidgetProps } from './types';
 
+/**
+ * TimeField - Time picker input widget
+ * Uses native time input for hour and minute selection
+ */
 export function TimeField({ value, onChange, field, readonly, ...props }: FieldWidgetProps<string>) {
   if (readonly) {
     return <span className="text-sm">{value || '-'}</span>;