@ticatec/uniface-element 0.2.4 → 0.3.0

package/docs/form-panel/grid-form/en/README.md

@@ -0,0 +1,744 @@
+# GridForm
+
+A flexible CSS Grid-based form layout system that provides precise control over field positioning, spanning, and complex layout arrangements.
+
+## Features
+
+- **CSS Grid Layout**: True CSS Grid implementation for complex form layouts
+- **Precise Positioning**: Explicit row and column positioning with `row` and `col` props
+- **Row/Column Spanning**: Fields can span multiple rows and columns
+- **Configurable Columns**: Set any number of columns (default 6)
+- **Layout Modes**: Supports vertical and horizontal field layouts
+- **FormField Integration**: Built-in FormField integration for labels and validation
+- **Complex Layouts**: Perfect for forms with images, cards, and non-uniform layouts
+
+## Installation
+
+```bash
+npm install @ticatec/uniface-element
+```
+
+## Usage
+
+### Basic Usage
+
+```svelte
+<script>
+  import GridForm, { GridField } from '@ticatec/uniface-element/grid-form';
+  import TextEditor from '@ticatec/uniface-element/text-editor';
+  
+  let formData = {};
+</script>
+
+<GridForm columns={3}>
+  <GridField row={1} col={1} label="First Name" required>
+    <TextEditor bind:value={formData.firstName} variant="filled" />
+  </GridField>
+  
+  <GridField row={1} col={2} label="Last Name" required>
+    <TextEditor bind:value={formData.lastName} variant="filled" />
+  </GridField>
+  
+  <GridField row={1} col={3} label="Email">
+    <TextEditor bind:value={formData.email} variant="filled" />
+  </GridField>
+  
+  <GridField row={2} col={1} colSpan={3} label="Address">
+    <TextEditor bind:value={formData.address} variant="filled" />
+  </GridField>
+</GridForm>
+```
+
+### Complex Layout with Image
+
+```svelte
+<script>
+  import GridForm, { GridField, EmptyCell } from '@ticatec/uniface-element/grid-form';
+  import TextEditor from '@ticatec/uniface-element/text-editor';
+  import DatePicker from '@ticatec/uniface-element/date-picker';
+  import OptionsSelect from '@ticatec/uniface-element/options-select';
+  import MemoEditor from '@ticatec/uniface-element/memo-editor';
+  
+  let formData = {};
+  let errors = {};
+  
+  const genderOptions = [
+    { code: 'F', text: 'Female' },
+    { code: 'M', text: 'Male' }
+  ];
+</script>
+
+<GridForm columns={3} style="border: 1px solid #e1e1e1; padding: 20px;">
+  <!-- Profile Image spanning 2 columns and 4 rows -->
+  <GridField 
+    row={1} 
+    col={1} 
+    colSpan={2} 
+    rowSpan={4} 
+    label="Profile Photo" 
+    required 
+    error={errors.photo}
+  >
+    <div style="width: 100%; height: 180px; border: 2px dashed #ccc; display: flex; align-items: center; justify-content: center;">
+      <img 
+        src={formData.photo || 'https://via.placeholder.com/200x180'} 
+        alt="Profile" 
+        style="width: 100%; height: 100%; object-fit: cover;"
+      />
+    </div>
+  </GridField>
+  
+  <!-- Personal details in the right column -->
+  <GridField row={1} col={3} label="Full Name" required error={errors.name}>
+    <TextEditor 
+      bind:value={formData.name} 
+      variant="filled"
+      placeholder="Enter full name"
+    />
+  </GridField>
+  
+  <GridField row={2} col={3} label="Date of Birth" required error={errors.dob}>
+    <DatePicker 
+      bind:value={formData.dob} 
+      variant="filled"
+      max={new Date()}
+    />
+  </GridField>
+  
+  <GridField row={3} col={3} label="Gender" required error={errors.gender}>
+    <OptionsSelect 
+      bind:value={formData.gender} 
+      variant="filled"
+      options={genderOptions}
+    />
+  </GridField>
+  
+  <GridField row={4} col={3} label="Phone Number" error={errors.phone}>
+    <TextEditor 
+      bind:value={formData.phone} 
+      variant="filled"
+      placeholder="Enter phone number"
+    />
+  </GridField>
+  
+  <!-- Full-width notes field -->
+  <GridField row={5} col={1} colSpan={3} label="Additional Notes" error={errors.notes}>
+    <MemoEditor 
+      bind:value={formData.notes} 
+      variant="filled"
+      input$rows={4}
+      input$maxLength={300}
+      showIndicator
+    />
+  </GridField>
+</GridForm>
+```
+
+### Card-Based Layout
+
+```svelte
+<GridForm columns={4}>
+  <!-- Header spanning full width -->
+  <GridField row={1} col={1} colSpan={4} label="Project Information">
+    <h3 style="margin: 0; padding: 1rem; background: #f8f9fa; border-radius: 4px;">
+      Project Details
+    </h3>
+  </GridField>
+  
+  <!-- Main content area -->
+  <GridField row={2} col={1} colSpan={3} rowSpan={2} label="Project Description">
+    <MemoEditor 
+      bind:value={project.description}
+      variant="filled"
+      input$rows={6}
+    />
+  </GridField>
+  
+  <!-- Sidebar information -->
+  <GridField row={2} col={4} label="Priority">
+    <OptionsSelect bind:value={project.priority} options={priorities} />
+  </GridField>
+  
+  <GridField row={3} col={4} label="Status">
+    <OptionsSelect bind:value={project.status} options={statuses} />
+  </GridField>
+  
+  <!-- Footer details -->
+  <GridField row={4} col={1} colSpan={2} label="Start Date">
+    <DatePicker bind:value={project.startDate} variant="filled" />
+  </GridField>
+  
+  <GridField row={4} col={3} colSpan={2} label="End Date">
+    <DatePicker bind:value={project.endDate} variant="filled" />
+  </GridField>
+</GridForm>
+```
+
+## API Reference
+
+### GridForm
+
+Main container component for CSS Grid-based form layout.
+
+#### Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `style` | `string` | `''` | Custom CSS styles for the form container |
+| `columns` | `number` | `6` | Number of columns in the grid |
+| `fieldLayout` | `'vertical' \| 'horizontal'` | `'vertical'` | Layout mode for form fields |
+
+#### Slots
+
+| Slot | Description |
+|------|-------------|
+| default | Form content containing GridField and EmptyCell components |
+
+### GridField
+
+A form field component that can be precisely positioned and span multiple grid cells.
+
+#### Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `label` | `string` | `"Label:"` | Label text for the form field |
+| `label$style` | `string` | `''` | Custom CSS styles for the label |
+| `required` | `boolean` | `false` | Whether the field is required |
+| `error` | `string \| null` | `null` | Error message to display |
+| `arrangement` | `'vertical' \| 'horizontal'` | `'vertical'` | Field arrangement mode |
+| `rowSpan` | `number` | `1` | Number of rows to span |
+| `colSpan` | `number` | `1` | Number of columns to span |
+| `row` | `number \| null` | `null` | Specific row position (1-based) |
+| `col` | `number \| null` | `null` | Specific column position (1-based) |
+| `height` | `string \| undefined` | `undefined` | Custom height for the field |
+| `labelSuffix` | `string` | `':'` | Text to append to the label |
+
+#### Slots
+
+| Slot | Description |
+|------|-------------|
+| default | Form control content (input, select, etc.) |
+
+### EmptyCell
+
+A placeholder cell for spacing and layout control.
+
+#### Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `rowSpan` | `number` | `1` | Number of rows to span |
+| `colSpan` | `number` | `1` | Number of columns to span |
+| `row` | `number` | - | Specific row position (1-based) |
+| `col` | `number` | - | Specific column position (1-based) |
+
+## Grid System
+
+The GridForm uses CSS Grid with configurable columns:
+
+- **columns={3}**: 3-column grid (33.33% each)
+- **columns={4}**: 4-column grid (25% each)
+- **columns={6}**: 6-column grid (16.67% each) - default
+- **columns={12}**: 12-column grid (8.33% each)
+
+### Positioning
+
+- **row/col**: 1-based positioning (row={1} col={1} is top-left)
+- **rowSpan/colSpan**: Span multiple cells
+- **Auto-placement**: Fields without explicit positioning flow naturally
+
+## Layout Examples
+
+### Dashboard-Style Form
+
+```svelte
+<GridForm columns={4}>
+  <!-- Header -->
+  <GridField row={1} col={1} colSpan={4} label="Dashboard Title">
+    <h2 style="margin: 0;">System Configuration</h2>
+  </GridField>
+  
+  <!-- Main settings panel -->
+  <GridField row={2} col={1} colSpan={2} rowSpan={3} label="Server Settings">
+    <div style="padding: 1rem; border: 1px solid #ddd; border-radius: 4px;">
+      <GridForm columns={2}>
+        <GridField label="Host">
+          <TextEditor bind:value={config.host} />
+        </GridField>
+        <GridField label="Port">
+          <TextEditor bind:value={config.port} />
+        </GridField>
+        <GridField colSpan={2} label="Database URL">
+          <TextEditor bind:value={config.dbUrl} />
+        </GridField>
+      </GridForm>
+    </div>
+  </GridField>
+  
+  <!-- Side panels -->
+  <GridField row={2} col={3} colSpan={2} label="System Status">
+    <div style="padding: 1rem; background: #f0f9ff; border-radius: 4px;">
+      <p>System Online</p>
+      <p>Last Updated: {new Date().toLocaleString()}</p>
+    </div>
+  </GridField>
+  
+  <GridField row={3} col={3} label="Environment">
+    <OptionsSelect bind:value={config.env} options={environments} />
+  </GridField>
+  
+  <GridField row={3} col={4} label="Debug Mode">
+    <OptionsSelect bind:value={config.debug} options={[{code: true, text: 'On'}, {code: false, text: 'Off'}]} />
+  </GridField>
+  
+  <GridField row={4} col={3} colSpan={2} label="Actions">
+    <div style="display: flex; gap: 1rem;">
+      <button>Save Config</button>
+      <button>Reset to Defaults</button>
+    </div>
+  </GridField>
+  
+  <!-- Footer -->
+  <GridField row={5} col={1} colSpan={4} label="Additional Notes">
+    <MemoEditor bind:value={config.notes} variant="filled" />
+  </GridField>
+</GridForm>
+```
+
+### Product Form with Image Gallery
+
+```svelte
+<GridForm columns={5}>
+  <!-- Product images -->
+  <GridField row={1} col={1} colSpan={2} rowSpan={3} label="Product Images">
+    <div style="display: grid; grid-template-columns: 1fr 1fr; gap: 0.5rem;">
+      {#each productImages as image, index}
+        <img 
+          src={image} 
+          alt="Product {index + 1}"
+          style="width: 100%; height: 80px; object-fit: cover; border-radius: 4px;"
+        />
+      {/each}
+    </div>
+  </GridField>
+  
+  <!-- Product details -->
+  <GridField row={1} col={3} colSpan={3} label="Product Name" required>
+    <TextEditor bind:value={product.name} variant="filled" />
+  </GridField>
+  
+  <GridField row={2} col={3} label="Price" required>
+    <TextEditor bind:value={product.price} variant="filled" />
+  </GridField>
+  
+  <GridField row={2} col={4} label="Currency">
+    <OptionsSelect bind:value={product.currency} options={currencies} />
+  </GridField>
+  
+  <GridField row={2} col={5} label="Stock">
+    <TextEditor bind:value={product.stock} variant="filled" />
+  </GridField>
+  
+  <GridField row={3} col={3} colSpan={3} label="Category">
+    <OptionsSelect bind:value={product.category} options={categories} />
+  </GridField>
+  
+  <!-- Full-width description -->
+  <GridField row={4} col={1} colSpan={5} label="Product Description">
+    <MemoEditor bind:value={product.description} variant="filled" />
+  </GridField>
+</GridForm>
+```
+
+### Survey Form with Mixed Layouts
+
+```svelte
+<GridForm columns={6}>
+  <!-- Question 1: Full width -->
+  <GridField row={1} col={1} colSpan={6} label="1. How would you rate our service?">
+    <OptionsSelect 
+      bind:value={survey.rating} 
+      options={ratingOptions}
+      variant="filled"
+    />
+  </GridField>
+  
+  <!-- Question 2: Two columns -->
+  <GridField row={2} col={1} colSpan={3} label="2. Your age group">
+    <OptionsSelect bind:value={survey.ageGroup} options={ageGroups} />
+  </GridField>
+  
+  <GridField row={2} col={4} colSpan={3} label="3. Your location">
+    <OptionsSelect bind:value={survey.location} options={locations} />
+  </GridField>
+  
+  <!-- Question 4: Three columns -->
+  <GridField row={3} col={1} colSpan={2} label="4. Income level">
+    <OptionsSelect bind:value={survey.income} options={incomeRanges} />
+  </GridField>
+  
+  <GridField row={3} col={3} colSpan={2} label="5. Education">
+    <OptionsSelect bind:value={survey.education} options={educationLevels} />
+  </GridField>
+  
+  <GridField row={3} col={5} colSpan={2} label="6. Employment">
+    <OptionsSelect bind:value={survey.employment} options={employmentTypes} />
+  </GridField>
+  
+  <!-- Open-ended question -->
+  <GridField row={4} col={1} colSpan={6} label="7. Additional comments" error={errors.comments}>
+    <MemoEditor 
+      bind:value={survey.comments}
+      variant="filled"
+      input$rows={4}
+      placeholder="Please share any additional feedback..."
+    />
+  </GridField>
+</GridForm>
+```
+
+## Validation and Error Handling
+
+```svelte
+<script>
+  let formData = {
+    name: '',
+    email: '',
+    phone: '',
+    address: '',
+    notes: ''
+  };
+  
+  let errors = {};
+  
+  function validateForm() {
+    errors = {};
+    
+    if (!formData.name?.trim()) {
+      errors.name = 'Name is required';
+    }
+    
+    if (!formData.email?.trim()) {
+      errors.email = 'Email is required';
+    } else if (!/\S+@\S+\.\S+/.test(formData.email)) {
+      errors.email = 'Please enter a valid email address';
+    }
+    
+    if (!formData.address?.trim()) {
+      errors.address = 'Address is required';
+    }
+    
+    return Object.keys(errors).length === 0;
+  }
+</script>
+
+<GridForm columns={4}>
+  <GridField row={1} col={1} colSpan={2} label="Full Name" required error={errors.name}>
+    <TextEditor 
+      bind:value={formData.name}
+      variant="filled"
+      placeholder="Enter your full name"
+    />
+  </GridField>
+  
+  <GridField row={1} col={3} colSpan={2} label="Email Address" required error={errors.email}>
+    <TextEditor 
+      bind:value={formData.email}
+      variant="filled"
+      placeholder="Enter email address"
+    />
+  </GridField>
+  
+  <GridField row={2} col={1} colSpan={3} label="Address" required error={errors.address}>
+    <TextEditor 
+      bind:value={formData.address}
+      variant="filled"
+      placeholder="Enter your address"
+    />
+  </GridField>
+  
+  <GridField row={2} col={4} label="Phone">
+    <TextEditor 
+      bind:value={formData.phone}
+      variant="filled"
+      placeholder="Phone number"
+    />
+  </GridField>
+  
+  <GridField row={3} col={1} colSpan={4} label="Additional Notes">
+    <MemoEditor 
+      bind:value={formData.notes}
+      variant="filled"
+      placeholder="Any additional information..."
+    />
+  </GridField>
+  
+  <GridField row={4} col={1} colSpan={4}>
+    <div style="text-align: right; margin-top: 1rem;">
+      <button type="button" on:click={validateForm}>
+        Validate & Submit
+      </button>
+    </div>
+  </GridField>
+</GridForm>
+```
+
+## Styling
+
+### Custom Grid Styling
+
+```svelte
+<GridForm 
+  columns={3}
+  style="
+    max-width: 900px;
+    margin: 2rem auto;
+    padding: 2rem;
+    border: 1px solid #e2e8f0;
+    border-radius: 8px;
+    background: white;
+    box-shadow: 0 4px 6px rgba(0, 0, 0, 0.1);
+    gap: 1.5rem;
+  "
+>
+  <!-- Grid content -->
+</GridForm>
+```
+
+### CSS Classes
+
+```css
+.custom-grid-form {
+  max-width: 1000px;
+  margin: 0 auto;
+  padding: 2rem;
+  background: #fafbfc;
+  border-radius: 8px;
+  box-shadow: 0 2px 8px rgba(0, 0, 0, 0.1);
+}
+
+.custom-grid-form .form-cell {
+  padding: 0.5rem;
+  border-radius: 4px;
+  background: white;
+  box-shadow: 0 1px 3px rgba(0, 0, 0, 0.1);
+}
+
+.custom-grid-form .form-cell.vertical {
+  /* Vertical layout specific styles */
+}
+
+.custom-grid-form .form-cell.horizontal {
+  /* Horizontal layout specific styles */
+}
+```
+
+## Responsive Design
+
+```svelte
+<GridForm columns={4} class="responsive-grid">
+  <GridField row={1} col={1} colSpan={2} label="Field 1">
+    <TextEditor bind:value={field1} />
+  </GridField>
+  
+  <GridField row={1} col={3} colSpan={2} label="Field 2">
+    <TextEditor bind:value={field2} />
+  </GridField>
+  
+  <GridField row={2} col={1} colSpan={4} label="Full Width Field">
+    <MemoEditor bind:value={field3} />
+  </GridField>
+</GridForm>
+
+<style>
+  @media (max-width: 768px) {
+    :global(.responsive-grid) {
+      grid-template-columns: 1fr !important;
+    }
+    
+    :global(.responsive-grid .form-cell) {
+      grid-column: 1 !important;
+      grid-row: auto !important;
+    }
+  }
+</style>
+```
+
+## Best Practices
+
+### 1. Plan Your Grid Layout
+
+Sketch your form layout before implementing:
+
+```svelte
+<!-- 
+Grid Layout Plan (3 columns):
+Row 1: [Image  ] [Name     ] [Phone    ]
+Row 2: [Image  ] [Email    ] [Country  ]
+Row 3: [Image  ] [Address (spans 2 cols)]
+Row 4: [Notes (spans all 3 columns)    ]
+-->
+
+<GridForm columns={3}>
+  <GridField row={1} col={1} rowSpan={3} label="Photo">
+    <!-- Image upload component -->
+  </GridField>
+  
+  <GridField row={1} col={2} label="Name">
+    <TextEditor bind:value={name} />
+  </GridField>
+  
+  <GridField row={1} col={3} label="Phone">
+    <TextEditor bind:value={phone} />
+  </GridField>
+  
+  <!-- Continue with planned layout -->
+</GridForm>
+```
+
+### 2. Use Meaningful Grid Dimensions
+
+Choose column counts that match your content:
+
+```svelte
+<!-- For simple forms: 2-3 columns -->
+<GridForm columns={3}>
+  <!-- Standard 3-column layout -->
+</GridForm>
+
+<!-- For complex forms: 4-6 columns -->
+<GridForm columns={6}>
+  <!-- More flexibility for complex layouts -->
+</GridForm>
+
+<!-- For detailed forms: 12 columns (like Bootstrap) -->
+<GridForm columns={12}>
+  <!-- Maximum flexibility -->
+</GridForm>
+```
+
+### 3. Group Related Fields
+
+Keep related fields visually connected:
+
+```svelte
+<GridForm columns={4}>
+  <!-- Personal Information Section -->
+  <GridField row={1} col={1} colSpan={4} label="Personal Information">
+    <h3 style="margin: 0; padding: 0.5rem; background: #f8f9fa;">
+      Personal Details
+    </h3>
+  </GridField>
+  
+  <GridField row={2} col={1} colSpan={2} label="First Name">
+    <TextEditor bind:value={firstName} />
+  </GridField>
+  
+  <GridField row={2} col={3} colSpan={2} label="Last Name">
+    <TextEditor bind:value={lastName} />
+  </GridField>
+  
+  <!-- Contact Information Section -->
+  <GridField row={3} col={1} colSpan={4} label="Contact Information">
+    <h3 style="margin: 0; padding: 0.5rem; background: #f8f9fa;">
+      Contact Details
+    </h3>
+  </GridField>
+  
+  <!-- Contact fields -->
+</GridForm>
+```
+
+### 4. Handle Empty Space
+
+Use EmptyCell for intentional spacing:
+
+```svelte
+<GridForm columns={5}>
+  <GridField row={1} col={1} colSpan={2} label="Important Field">
+    <TextEditor bind:value={important} />
+  </GridField>
+  
+  <!-- Intentional empty space -->
+  <EmptyCell row={1} col={3} />
+  
+  <GridField row={1} col={4} colSpan={2} label="Another Field">
+    <TextEditor bind:value={another} />
+  </GridField>
+</GridForm>
+```
+
+## Advanced Patterns
+
+### Dynamic Grid Content
+
+```svelte
+<script>
+  let sections = [
+    { id: 1, title: 'Section A', fields: ['field1', 'field2'] },
+    { id: 2, title: 'Section B', fields: ['field3', 'field4', 'field5'] }
+  ];
+  
+  let currentRow = 1;
+</script>
+
+<GridForm columns={4}>
+  {#each sections as section}
+    <GridField row={currentRow} col={1} colSpan={4} label={section.title}>
+      <h3>{section.title}</h3>
+    </GridField>
+    
+    {#each section.fields as field, index}
+      <GridField 
+        row={currentRow + 1 + Math.floor(index / 2)} 
+        col={1 + (index % 2) * 2} 
+        colSpan={2} 
+        label={field}
+      >
+        <TextEditor bind:value={formData[field]} />
+      </GridField>
+    {/each}
+    
+    <!-- Update currentRow for next section -->
+    {currentRow = currentRow + 2 + Math.ceil(section.fields.length / 2)}
+  {/each}
+</GridForm>
+```
+
+## Comparison with Other Form Layouts
+
+| Feature | GridForm | FlexForm | FlexRowForm |
+|---------|----------|----------|-------------|
+| Layout Type | CSS Grid | Flexbox wrapping | Structured rows |
+| Positioning | Explicit (row/col) | Auto-flow | Row-based |
+| Spanning | Rows & columns | Columns only | Columns only |
+| Complexity | Highest | Lowest | Medium |
+| Use Case | Complex layouts | Simple forms | Structured forms |
+| Learning Curve | Steeper | Gentle | Moderate |
+
+## Accessibility Features
+
+- **Logical Tab Order**: Fields flow in logical reading order
+- **Screen Reader Support**: Proper grid structure announced
+- **Keyboard Navigation**: Standard form navigation patterns
+- **Error Association**: Clear error message positioning
+- **Focus Management**: Proper focus flow through grid cells
+
+## Browser Support
+
+- **Modern Browsers**: Chrome, Firefox, Safari, Edge (latest versions)
+- **Mobile Browsers**: iOS Safari, Chrome Mobile, Firefox Mobile
+- **CSS Grid**: Required for layout functionality (IE11+ with prefixes)
+
+## Related Components
+
+- **FormField**: Base form field component with labels and validation
+- **FlexForm**: Simpler automatic-wrapping form layout
+- **FlexRowForm**: Structured row-based form layout
+- **TextEditor**: Single-line text input component
+- **DatePicker**: Date selection component
+
+## License
+
+MIT License - see LICENSE file for details.