@kubex/zinc 1.0.24 → 1.0.98

package/docs/pages/components/rating.md

@@ -1,7 +1,7 @@
 ---
 meta:
   title: Rating
-  description:
+  description: Ratings allow users to view and provide feedback using a star rating system.
 layout: component
 ---
 
@@ -9,20 +9,344 @@ layout: component
 <zn-rating></zn-rating>
 ```
 
+:::tip
+This component works with standard `<form>` elements. Please refer to the section
+on [form controls](/getting-started/form-controls) to learn more about form submission and client-side validation.
+:::
+
 ## Examples
 
-### Form example with Value and Name
+### Basic Rating
+
+A basic rating component displays stars that can be clicked to set a rating value.
+
+```html:preview
+<zn-rating label="Rate this product"></zn-rating>
+```
+
+### With Value
+
+Use the `value` attribute to set an initial rating value.
+
+```html:preview
+<zn-rating value="3" label="Product rating"></zn-rating>
+```
+
+### Maximum Rating
+
+Use the `max` attribute to change the maximum number of stars. The default is 5.
+
+```html:preview
+<zn-rating max="10" value="7" label="Rate out of 10"></zn-rating>
+<br />
+<zn-rating max="3" value="2" label="Difficulty level"></zn-rating>
+```
+
+### Precision
+
+Use the `precision` attribute to control the granularity of ratings. The default precision is 1 (whole stars).
+
+```html:preview
+<zn-rating value="2.5" precision="0.5" label="Half star precision"></zn-rating>
+<br />
+<zn-rating value="3.75" precision="0.25" label="Quarter star precision"></zn-rating>
+<br />
+<zn-rating value="3.33" precision="0.1" label="Tenth star precision"></zn-rating>
+```
+
+### Readonly
+
+Use the `readonly` attribute to display a rating that cannot be changed. This is useful for showing existing ratings.
+
+```html:preview
+<zn-rating value="4" readonly label="Average rating"></zn-rating>
+<br />
+<zn-rating value="3.5" precision="0.5" readonly label="Customer reviews"></zn-rating>
+```
+
+### Disabled
+
+Use the `disabled` attribute to disable the rating component.
+
+```html:preview
+<zn-rating disabled label="Rating disabled"></zn-rating>
+<br />
+<zn-rating value="3" disabled label="Rating disabled with value"></zn-rating>
+```
+
+### Sizes
+
+Use the `size` attribute to change the rating size. Available sizes are `small`, `medium` (default), and `large`.
+
+```html:preview
+<zn-rating size="small" value="3" label="Small rating"></zn-rating>
+<br />
+<zn-rating size="medium" value="3" label="Medium rating"></zn-rating>
+<br />
+<zn-rating size="large" value="3" label="Large rating"></zn-rating>
+```
+
+### Custom Symbols
+
+Use the `getSymbol` property to customize the symbols displayed. By default, the component uses star icons from the Material icon library.
+
+```html:preview
+<zn-rating id="custom-symbol-heart" value="3" label="Rate with hearts"></zn-rating>
+<br />
+<zn-rating id="custom-symbol-emoji" value="4" max="5" label="Rate with emojis"></zn-rating>
+
+<script type="module">
+  const heartRating = document.querySelector('#custom-symbol-heart');
+  heartRating.getSymbol = () => '<zn-icon src="favorite" library="material"></zn-icon>';
+
+  const emojiRating = document.querySelector('#custom-symbol-emoji');
+  emojiRating.getSymbol = () => '<zn-icon src="sentiment_satisfied" library="material"></zn-icon>';
+</script>
+```
+
+### Hover Effects
+
+The rating component displays hover effects by default, scaling the hovered star and all preceding stars.
 
 ```html:preview
+<zn-rating value="0" label="Hover to preview rating"></zn-rating>
+```
+
+:::tip
+**Usage:** Hover effects provide visual feedback to help users understand which rating they will select. The hover effect is automatically disabled for `readonly` and `disabled` ratings.
+:::
 
-<form action="#" method="get">
-  <zn-rating value="2" name="rating"></zn-rating>
-  <zn-button type="submit">Submit</zn-button>
+### Form Integration
+
+Ratings work seamlessly with forms and will be submitted with form data using the `name` attribute.
+
+```html:preview
+<form id="rating-form">
+  <zn-rating name="product-rating" value="0" label="Rate this product" required></zn-rating>
+  <br />
+  <zn-rating name="service-rating" value="4" label="Rate our service"></zn-rating>
+  <br /><br />
+  <zn-button type="submit" color="primary">Submit Review</zn-button>
+  <zn-button type="reset" color="secondary">Reset</zn-button>
 </form>
+
+<script type="module">
+  const form = document.querySelector('#rating-form');
+  form.addEventListener('submit', (event) => {
+    event.preventDefault();
+    const formData = new FormData(form);
+    const data = Object.fromEntries(formData.entries());
+    alert('Form submitted: ' + JSON.stringify(data, null, 2));
+  });
+</script>
+```
+
+### Interactive Example with Value Display
+
+This example demonstrates how the rating value changes as you interact with the component.
+
+```html:preview
+<div>
+  <zn-rating id="interactive-rating" value="0" precision="0.5" label="Rate your experience"></zn-rating>
+  <div id="rating-value" style="margin-top: 1rem; padding: 0.75rem; background: #f5f5f5; border-radius: 4px;">
+    <strong>Current Rating:</strong> <span id="rating-display">0</span> out of 5
+  </div>
+</div>
+
+<script type="module">
+  const rating = document.querySelector('#interactive-rating');
+  const display = document.querySelector('#rating-display');
+
+  // Update display when rating changes
+  const updateDisplay = () => {
+    display.textContent = rating.value || '0';
+  };
+
+  // Listen for value changes
+  rating.addEventListener('click', updateDisplay);
+
+  // Update initial display
+  updateDisplay();
+</script>
+```
+
+### Clearable Rating
+
+Click on the currently selected rating to clear it and set the value back to 0.
+
+```html:preview
+<zn-rating value="3" label="Click selected rating to clear"></zn-rating>
+```
+
+:::tip
+**Usage:** This feature allows users to remove their rating if they change their mind. Clicking on the currently selected star will reset the rating to 0.
+:::
+
+### Display Patterns
+
+Common patterns for displaying ratings in user interfaces.
+
+```html:preview
+<div style="display: flex; align-items: center; gap: 0.5rem;">
+  <zn-rating value="4.5" precision="0.5" readonly size="small"></zn-rating>
+  <span style="font-size: 14px; color: #6D7176;">4.5 out of 5 (1,234 reviews)</span>
+</div>
+
+<br />
+
+<div style="display: flex; align-items: center; gap: 0.5rem;">
+  <zn-rating value="3.75" precision="0.25" readonly></zn-rating>
+  <span style="font-weight: 600;">3.75</span>
+</div>
+
+<br />
+
+<div style="border: 1px solid #E5E7EB; border-radius: 8px; padding: 1.5rem; max-width: 400px;">
+  <h3 style="margin: 0 0 0.5rem 0; font-size: 18px;">Customer Reviews</h3>
+  <div style="display: flex; align-items: center; gap: 0.5rem; margin-bottom: 1rem;">
+    <zn-rating value="4.2" precision="0.1" readonly></zn-rating>
+    <span style="font-size: 20px; font-weight: 600;">4.2</span>
+    <span style="color: #6D7176;">based on 856 reviews</span>
+  </div>
+  <zn-rating value="0" label="Rate this product"></zn-rating>
+</div>
+```
+
+### Accessibility
+
+The rating component includes ARIA attributes for accessibility:
+
+- Uses `role="slider"` to indicate interactive rating control
+- Provides `aria-label` for screen readers (set via the `label` attribute)
+- Includes `aria-valuenow`, `aria-valuemin`, and `aria-valuemax` attributes
+- Respects `aria-disabled` and `aria-readonly` states
+
+```html:preview
+<zn-rating value="3" label="Product quality rating" max="5"></zn-rating>
+```
+
+:::tip
+**Best Practice:** Always provide a descriptive `label` attribute to ensure screen reader users understand what they are rating.
+:::
+
+### Touch Support
+
+The rating component fully supports touch interactions for mobile devices.
+
+```html:preview
+<zn-rating value="0" label="Try on touch device"></zn-rating>
+```
+
+:::tip
+**Usage:** Touch events are handled alongside mouse events, allowing users to drag their finger across the stars to preview and select a rating. The component will update the rating when the touch ends.
+:::
+
+### Custom Styling
+
+Use CSS custom properties to customize the appearance of the rating component.
+
+```html:preview
+<style>
+  .custom-rating {
+    --symbol-color: #CBD5E1;
+    --symbol-color-active: #3B82F6;
+    --symbol-size: 2rem;
+    --symbol-spacing: 8px;
+  }
+
+  .custom-rating-gold {
+    --symbol-color: #E5E7EB;
+    --symbol-color-active: #F59E0B;
+    --symbol-size: 1.5rem;
+  }
+</style>
+
+<zn-rating class="custom-rating" value="4" label="Custom blue rating"></zn-rating>
+<br />
+<zn-rating class="custom-rating-gold" value="3.5" precision="0.5" label="Custom gold rating"></zn-rating>
 ```
 
-### Second Example
+Available CSS custom properties:
+
+- `--symbol-color` - Color of unfilled symbols
+- `--symbol-color-active` - Color of filled/active symbols
+- `--symbol-size` - Size of the symbols
+- `--symbol-spacing` - Spacing between symbols
+
+### Complete Example
+
+Here's a comprehensive example demonstrating multiple rating features in a product review form:
+
+```html:preview
+<form id="complete-rating-form" style="max-width: 500px; padding: 1.5rem; border: 1px solid #E5E7EB; border-radius: 8px;">
+  <h3 style="margin: 0 0 1.5rem 0;">Product Review</h3>
+
+  <zn-rating
+    name="overall-rating"
+    value="0"
+    label="Overall Rating"
+    max="5"
+    precision="0.5"
+    required
+  ></zn-rating>
+
+  <br />
+
+  <zn-rating
+    name="quality-rating"
+    value="0"
+    label="Quality"
+    max="5"
+    size="small"
+  ></zn-rating>
+
+  <br />
+
+  <zn-rating
+    name="value-rating"
+    value="0"
+    label="Value for Money"
+    max="5"
+    size="small"
+  ></zn-rating>
+
+  <br />
 
-TODO
+  <zn-rating
+    name="ease-rating"
+    value="0"
+    label="Ease of Use"
+    max="5"
+    size="small"
+  ></zn-rating>
+
+  <br /><br />
+  <zn-button type="submit" color="primary">Submit Review</zn-button>
+  <zn-button type="reset" color="secondary">Reset</zn-button>
+</form>
+
+<div id="review-output" style="margin-top: 1rem; padding: 1rem; background: #f5f5f5; border-radius: 4px; display: none;">
+  <strong>Review Data:</strong>
+  <pre id="review-data" style="margin-top: 0.5rem; white-space: pre-wrap;"></pre>
+</div>
+
+<script type="module">
+  const form = document.querySelector('#complete-rating-form');
+  const output = document.querySelector('#review-output');
+  const dataDisplay = document.querySelector('#review-data');
+
+  form.addEventListener('submit', (event) => {
+    event.preventDefault();
+    const formData = new FormData(form);
+    const data = Object.fromEntries(formData.entries());
+    dataDisplay.textContent = JSON.stringify(data, null, 2);
+    output.style.display = 'block';
+  });
+
+  form.addEventListener('reset', () => {
+    output.style.display = 'none';
+  });
+</script>
+```