From 8aafea456d50cd3998054000d719e3cb515fa062 Mon Sep 17 00:00:00 2001
From: Lea Verou <lea@verou.me>
Date: Tue, 17 Dec 2024 16:22:11 -0500
Subject: [PATCH] Flesh out Essentials pages a little (still heavily WIP)

---
 docs/docs/essentials/details.md |  22 +++++-
 docs/docs/essentials/input.md   | 125 +++++++++++++++-----------------
 docs/docs/essentials/table.md   |  49 ++++++++++++-
 3 files changed, 123 insertions(+), 73 deletions(-)

diff --git a/docs/docs/essentials/details.md b/docs/docs/essentials/details.md
index db81ca684..9652c3192 100644
--- a/docs/docs/essentials/details.md
+++ b/docs/docs/essentials/details.md
@@ -3,8 +3,6 @@ title: Details
 tags: essentials
 ---
 
-## Details
-
 Individual details look like this.
 
 <details>
@@ -12,8 +10,25 @@ Individual details look like this.
   <p>Ut lectus arcu bibendum at varius. Convallis a cras semper auctor neque vitae. Odio pellentesque diam volutpat commodo sed egestas. Amet dictum sit amet justo donec enim diam vulputate ut.</p>
 </details>
 
-Grouping them provides accordion-style functionality.
+## Examples
 
+### Right-to-Left languages
+
+The details styling automatically adapts to right-to-left languages:
+
+```html {.example}
+<details lang="ar" dir="rtl">
+  <summary>تبديلني</summary>
+  استخدام طريقة لوريم إيبسوم لأنها تعطي توزيعاَ طبيعياَ -إلى حد ما- للأحرف عوضاً عن
+</details>
+```
+
+## Accordions
+
+In [modern browsers](https://caniuse.com/mdn-html_elements_details_name),
+grouping `<details>` elements via the `name` attribute provides accordion-style functionality:
+
+```html {.example}
 <details name="details-accordion">
   <summary>Enim diam</summary>
   <p>Nunc faucibus a pellentesque sit amet porttitor. Adipiscing tristique risus nec feugiat in fermentum. Leo duis ut diam quam nulla porttitor massa id. Mauris nunc congue nisi vitae.</p>
@@ -28,3 +43,4 @@ Grouping them provides accordion-style functionality.
   <summary>Ut porttitor</summary>
   <p>Eu facilisis sed odio morbi quis commodo odio aenean sed. Sit amet purus gravida quis blandit turpis cursus. Eu consequat ac felis donec et odio pellentesque diam volutpat.</p>
 </details>
+```
diff --git a/docs/docs/essentials/input.md b/docs/docs/essentials/input.md
index c8e072c81..24d167b29 100644
--- a/docs/docs/essentials/input.md
+++ b/docs/docs/essentials/input.md
@@ -2,79 +2,53 @@
 title: Form Inputs
 tags: essentials
 ---
+<style>
+wa-code-demo::part(preview) {
+  display: grid;
+  grid-template-columns: 1fr 1fr;
+  gap: 2rem;
+}
+</style>
 
-## Forms
-
-<div style="display: grid; grid-template-columns: 1fr 1fr; gap: 2rem;" class="wa">
-
-<label for="input-text">Input (text)</label>
-<input type="text" id="input-text" placeholder="placeholder">
+## Text fields
 
+```html {.example}
+<label>Input (text) <input type="text" placeholder="placeholder"></label>
 <wa-input label="WA Input (text)" type="text" placeholder="placeholder"></wa-input>
 
-<label for="input-number">Input (number)</label>
-<input type="number" id="input-number">
-
+<label>Input (number) <input type="number"></label>
 <wa-input label="WA Input (number)" type="number"></wa-input>
 
-<label for="input-password">Input (password)</label>
-<input type="password" id="input-password" required>
-
+<label>Input (password) <input type="password" required></label>
 <wa-input label="WA Input (password)" type="password" required></wa-input>
 
-<label for="input-datetime-local">Input (datetime-local)</label>
-<input type="datetime-local" id="input-datetime-local"></input>
-
-<wa-input label="WA Input (datetime-local)" type="datetime-local"></wa-input>
-
-<label for="input-email">Input (email)</label>
-<input type="email" id="input-email">
-
+<label>Input (email) <input type="email"></label>
 <wa-input label="WA Input (email)" type="email"></wa-input>
 
-<label for="input-search">Input (search)</label>
-<input type="search" id="input-search">
-
+<label>Input (search) <input type="search"></label>
 <wa-input label="WA Input (search)" type="search"></wa-input>
 
-<label for="input-tel">Input (tel)</label>
-<input type="tel" id="input-tel">
-
+<label>Input (tel) <input type="tel"></label>
 <wa-input label="WA Input (tel)" type="tel"></wa-input>
 
-<label for="input-url">Input (url)</label>
-<input type="url" id="input-url">
-
+<label>Input (url) <input type="url"></label>
 <wa-input label="WA Input (url)" type="url"></wa-input>
 
-<input type="checkbox" id="input-checkbox"></input>
-<label for="input-checkbox">Input (checkbox)</label>
+<label>Textarea <textarea></textarea></label>
+<wa-textarea label="WA Textarea"></wa-textarea>
+```
 
+## Choice inputs
+
+```html {.example}
+<label><input type="checkbox"> Input (checkbox)</label>
 <wa-checkbox>WA Checkbox</wa-checkbox>
 
-<label for="input-color">Input (color)</label>
-<input type="color" id="input-color"></input>
-
-<wa-color-picker label="WA Color Picker"></wa-color-picker>
-
-<label for="input-date">Input (date)</label>
-<input type="date" id="input-date"></input>
-
-<wa-input label="WA Input (date)" type="date"></wa-input>
-
-<label for="input-time">Input (time)</label>
-<input type="time" id="input-time"></input>
-
-<wa-input label="WA Input (time)" type="time"></wa-input>
-
 <fieldset>
   <legend>Radio Group:</legend>
-  <input type="radio" id="radio-1" name="radio" value="radio-1" checked />
-  <label for="radio-1">Radio 1</label>
-  <input type="radio" id="radio-2" name="radio" value="radio-2" />
-  <label for="radio-2">Radio 2</label>
-  <input type="radio" id="radio-3" name="radio" value="radio-3" />
-  <label for="radio-3">Radio 3</label>
+  <label><input type="radio" name="radio" value="radio-1" checked> Radio 1</label>
+  <label><input type="radio"name="radio" value="radio-2" /> Radio 2</label>
+  <label><input type="radio"  name="radio" value="radio-3" /> Radio 3</label>
 </fieldset>
 
 <fieldset>
@@ -84,34 +58,51 @@ tags: essentials
     <wa-radio value="radio-3">Radio</wa-radio>
   </wa-radio-group>
 </fieldset>
+```
 
-<label for="input-range">Input (range)</label>
-<input type="range" id="input-range">
+## Color picker
+
+```html {.example}
+<label>Input (color) <input type="color"></label>
+
+<wa-color-picker label="WA Color Picker"></wa-color-picker>
+```
+
+## Time and date Pickers
+
+```html {.example}
+<label>Input (datetime-local) <input type="datetime-local"></label>
+<wa-input label="WA Input (datetime-local)" type="datetime-local"></wa-input>
+
+<label>Input (date) <input type="date"></label>
+<wa-input label="WA Input (date)" type="date"></wa-input>
+
+<label>Input (time) <input type="time"></label>
+<wa-input label="WA Input (time)" type="time"></wa-input>
+```
+
+## Slider
+
+```html {.example}
+<label>Input (range)<input type="range"></label>
 
 <wa-range label="WA Range"></wa-range>
+```
 
-<div>
-  <label for="textarea">Textarea</label>
-  <textarea id="textarea"></textarea>
-</div>
+## Select dropdown
 
-<wa-textarea label="WA Textarea"></wa-textarea>
-
-<div>
-<label for="select">Select</label>
+```html {.example}
+<label>Select
   <select id="select">
     <option value="option-1">Option 1</option>
     <option value="option-2">Option 2</option>
     <option value="option-3">Option 3</option>
   </select>
-</div>
+</label>
 
 <wa-select label="WA Select">
   <wa-option value="option-1">Option 1</wa-option>
   <wa-option value="option-2">Option 2</wa-option>
   <wa-option value="option-3">Option 3</wa-option>
 </wa-select>
-
-
-</div>
-
+```
diff --git a/docs/docs/essentials/table.md b/docs/docs/essentials/table.md
index 8f8837862..a249c59dc 100644
--- a/docs/docs/essentials/table.md
+++ b/docs/docs/essentials/table.md
@@ -1,10 +1,9 @@
 ---
-title: Tables
+title: Table
 tags: essentials
 ---
 
-## Tables
-
+```html {.example}
 <table>
   <caption>I'm just a table</caption>
   <thead>
@@ -42,4 +41,48 @@ tags: essentials
     </tr>
   </tbody>
 </table>
+```
 
+## Alternating rows
+
+You can use the `wa-alternating-row-colors` class to add alternating row colors to your table:
+
+```html {.example}
+<table class="wa-alternating-row-colors">
+  <caption>I'm just a table</caption>
+  <thead>
+    <tr>
+      <th>Column 1</th>
+      <th>Column 2</th>
+      <th>Column 3</th>
+      <th>Column 4</th>
+    </tr>
+  </thead>
+  <tbody>
+    <tr>
+      <td>Cell</td>
+      <td>Cell</td>
+      <td>Cell</td>
+      <td>Cell</td>
+    </tr>
+    <tr>
+      <td>Cell</td>
+      <td>Cell</td>
+      <td>Cell</td>
+      <td>Cell</td>
+    </tr>
+    <tr>
+      <td>Cell</td>
+      <td>Cell</td>
+      <td>Cell</td>
+      <td>Cell</td>
+    </tr>
+    <tr>
+      <td>Cell</td>
+      <td>Cell</td>
+      <td>Cell</td>
+      <td>Cell</td>
+    </tr>
+  </tbody>
+</table>
+```