@reliability-design/web 1.0.2 → 1.0.6

package/dist/components/rel-quote-page/README.md

@@ -0,0 +1,166 @@
+# rel-quote-page
+
+## Overview
+A comprehensive freight shipping quote form component with all necessary fields for LTL (Less Than Truckload) shipping quotes. Features two main sections (Shipping Details and Commodity Details) with 24+ form fields including location search, service level tabs, radio groups, dropdowns, dimension inputs, and date picker. Automatically dispatches `form-change` events for external form handling.
+
+## Usage
+```html
+<!-- Basic usage -->
+<rel-quote-page></rel-quote-page>
+
+<!-- With form change listener -->
+<rel-quote-page id="quoteForm"></rel-quote-page>
+<script>
+  const form = document.getElementById('quoteForm');
+  form.addEventListener('form-change', (e) => {
+    console.log('Form data:', e.detail);
+    // e.detail contains the complete QuoteFormData object
+  });
+</script>
+
+<!-- Programmatically access form data -->
+<rel-quote-page id="quote"></rel-quote-page>
+<script>
+  const quote = document.getElementById('quote');
+  // Access form data via the formData property
+  console.log(quote.formData.pickupLocation);
+  console.log(quote.formData.serviceLevel);
+  console.log(quote.formData.totalWeight);
+</script>
+```
+
+## API
+
+### Properties
+All form data is managed internally via a reactive `formData` state property (not directly settable). Access it via the `formData` property or the `form-change` event.
+
+## Events
+| Event | Detail | Description |
+|-------|--------|-------------|
+| `form-change` | `QuoteFormData` | Fired whenever any form field changes |
+
+## QuoteFormData Interface
+```typescript
+interface QuoteFormData {
+  // Shipping Details
+  pickupLocation: string;
+  dropoffLocation: string;
+  serviceLevel: "standard" | "guaranteed";
+  originType: "commercial" | "residential";
+  destinationType: "commercial" | "residential";
+  loadingRequirements: string;
+  deliveryRequirements: string;
+  loadingLimitedAccessType: string;
+  deliveryLimitedAccessType: string;
+  pickupDate: string; // Date in YYYY-MM-DD format
+  
+  // Commodity Details
+  isHazmat: boolean;
+  commodity: string;
+  commodityDescription: string;
+  handlingUnits: number;
+  handlingType: string;
+  length: number; // inches
+  width: number; // inches
+  height: number; // inches
+  totalWeight: number; // lbs
+  class: string; // freight class
+  insuredValue: number;
+  nmfcNumber: string;
+}
+```
+
+## Slots
+None. This component provides a complete, self-contained form UI.
+
+## CSS Parts
+None exposed.
+
+## Tokens / CSS Variables
+
+### Semantic Tokens
+- `--rel-fontFamilies-primary` - Font family
+
+### Font Tokens
+- `--rel-fontSizes-xl` - Section titles (24px)
+- `--rel-fontSizes-lg` - Large text
+- `--rel-fontSizes-md` - Subsection titles (16px)
+- `--rel-fontSizes-sm` - Field labels, inputs (14px)
+- `--rel-fontSizes-xs` - Helper text, dimension labels (12px)
+- `--rel-fontWeights-bold` - Section titles
+- `--rel-fontWeights-semibold` - Subsection titles
+- `--rel-fontWeights-medium` - Field labels, radio labels
+
+### Color Tokens
+- `--rel-colors-white` - Component background, input backgrounds, tab background
+- `--rel-colors-black` - Section title, active tab background, radio selected, input focus border
+- `--rel-colors-green-primary` - Subsection title bullet
+- `--rel-colors-red-primary` - Required field asterisks
+- `--rel-colors-gray-heading` - Field labels, subsection titles
+- `--rel-colors-gray-primary` - Input text, radio labels
+- `--rel-colors-gray-placeholder` - Helper text
+- `--rel-colors-gray-border` - Input borders, tab borders
+
+### Border Tokens
+- `--rel-borders-radius-border-radius-300` - Component and input border radius (16px/similar)
+
+### Spacing Tokens
+- `--rel-spacing-space-xl` - Component padding
+- `--rel-spacing-space-2xl` - Section bottom margin
+- `--rel-spacing-space-lg` - Section row gap, field bottom margin
+- `--rel-spacing-space-md` - Subsection margins, field group gap, service level tab bottom margin
+- `--rel-spacing-space-sm` - Input padding, radio group gap
+- `--rel-spacing-space-xs` - Tab padding, dimension input padding
+- `--rel-spacing-space-2xs` - Field label-input gap
+- `--rel-spacing-space-3xs` - Info icon gap, dimension label gap
+
+## Accessibility
+- All required fields are marked with a red asterisk and `required` class
+- Input fields have associated `<label>` elements
+- Radio groups use custom styled divs (not native radios) but support click interaction
+- Helper text provides additional context for complex fields
+- Info icons (`ⓘ`) use `cursor: help` to indicate additional information
+
+### Keyboard Interactions
+- Standard form navigation (Tab, Shift+Tab)
+- Native input keyboard support (text, number, date, select)
+- Service level tabs are `<button>` elements and keyboard accessible
+
+### Focus Behavior
+- Inputs show focus border via `:focus-visible` (black border)
+- Standard browser focus behavior for all form controls
+
+## Notes / Edge Cases
+- **Form sections**:
+  1. **Shipping Details**: Pickup/dropoff locations, service level, origin/destination types, loading/delivery requirements, limited access types, pickup date
+  2. **Commodity Details**: Hazmat status, commodity info, handling units/type, dimensions (L/W/H), total weight, class, insured value, NMFC number
+
+- **Service Level**: Toggle between "Standard" and "Guaranteed" using tab buttons (black background when active)
+
+- **Radio groups**: Custom styled (not native `<input type="radio">`) using divs with visual indicators
+
+- **Dimension inputs**: Grid layout with 4 columns (Length, Width, Height, Total Weight)
+  - Width and Height show "96\" max" helper text
+  - Inputs show unit labels (inches, lbs)
+
+- **Responsive design**: Two-column grid on desktop (`grid-template-columns: 1fr 1fr`), single column on mobile (≤768px)
+
+- **Location inputs**: Include search icon emoji (🔍) on the right side
+
+- **Helper text**: Loading Requirements field includes detailed explanation about inside pickup/delivery and liftgate requirements
+
+- **Info icons**: Small circular icons with `ⓘ` character, `cursor: help`
+
+- **Subsection titles**: Include a green circular bullet (`::before` pseudo-element)
+
+- **Dropdowns**: Custom styled `<select>` with SVG dropdown arrow (appearance: none)
+
+- The component has max-width of 900px and is centered with `margin: 0 auto`
+
+- Box shadow and border radius give the component a card-like appearance
+
+- All form updates trigger the `form-change` event with the complete `formData` object
+
+- Number inputs use `parseInt()` or `parseFloat()` with fallback to 0 for invalid values
+
+- Date input is native HTML5 `type="date"`