@adia-ai/web-components 0.8.6 → 0.8.8

package/patterns/form-system/form-system.examples.html

@@ -0,0 +1,383 @@
+<header>
+    <div>
+      <h1>Form System</h1>
+    </div>
+    <p>AdiaUI's form system uses <code>UIFormElement</code> and <code>ElementInternals</code> to give custom elements native form participation, constraint validation, and auto-validation UX.</p>
+  </header>
+
+<section data-section data-property="overview">
+  <h2 variant="section">Overview</h2>
+  <p>
+    HTML forms expect native elements (<code>&lt;input&gt;</code>, <code>&lt;select&gt;</code>)
+    to participate in submission, validation, and reset. Custom elements are invisible to
+    forms by default. AdiaUI solves this with <code>UIFormElement</code>, a base class
+    that bridges custom elements into the native form lifecycle via the
+    <code>ElementInternals</code> API.
+  </p>
+  <p>
+    Any component that extends <code>UIFormElement</code> can be placed inside a
+    <code>&lt;form&gt;</code> and will:
+  </p>
+  <ul>
+    <li>Submit its value with the form (via <code>name</code> attribute)</li>
+    <li>Participate in constraint validation (required, pattern, minlength, maxlength)</li>
+    <li>Surface validation errors automatically on submit, blur, and input</li>
+    <li>Reset when the form resets</li>
+    <li>Be disabled when the form or fieldset is disabled</li>
+  </ul>
+</section>
+
+<section data-section data-property="components-using-uiformelement">
+  <h2 variant="section">Components Using UIFormElement</h2>
+  <p>
+    The following components extend <code>UIFormElement</code> and participate in forms:
+  </p>
+  <table>
+    <thead>
+      <tr>
+        <th>Component</th>
+        <th>Tag</th>
+        <th>Value Type</th>
+      </tr>
+    </thead>
+    <tbody>
+      <tr><td>Input</td><td><code>input-ui</code></td><td>String</td></tr>
+      <tr><td>Textarea</td><td><code>textarea-ui</code></td><td>String</td></tr>
+      <tr><td>Select</td><td><code>select-ui</code></td><td>String</td></tr>
+      <tr><td>Check</td><td><code>check-ui</code></td><td>String (on/off)</td></tr>
+      <tr><td>Switch</td><td><code>switch-ui</code></td><td>String (on/off)</td></tr>
+      <tr><td>Radio</td><td><code>radio-ui</code></td><td>String</td></tr>
+      <tr><td>Slider</td><td><code>slider-ui</code></td><td>Number (as string)</td></tr>
+      <tr><td>Range</td><td><code>range-ui</code></td><td>Number (as string)</td></tr>
+      <tr><td>Search</td><td><code>search-ui</code></td><td>String</td></tr>
+      <tr><td>Segmented</td><td><code>segmented-ui</code></td><td>String</td></tr>
+      <tr><td>OTP Input</td><td><code>otp-input-ui</code></td><td>String</td></tr>
+      <tr><td>Calendar Picker</td><td><code>calendar-picker-ui</code></td><td>Date string</td></tr>
+      <tr><td>Color Picker</td><td><code>color-picker-ui</code></td><td>Color string</td></tr>
+      <tr><td>Upload</td><td><code>upload-ui</code></td><td>File(s)</td></tr>
+    </tbody>
+  </table>
+</section>
+
+<section data-section data-property="elementinternals">
+  <h2 variant="section">ElementInternals</h2>
+  <p>
+    <code>ElementInternals</code> is the browser API that lets custom elements act as form
+    controls. AdiaUI's <code>UIFormElement</code> sets <code>static formAssociated = true</code>
+    to opt in, then uses the internals object to:
+  </p>
+  <ul>
+    <li><code>setFormValue(val)</code> — set the value submitted with the form</li>
+    <li><code>setValidity(flags, message, anchor)</code> — set validation state</li>
+    <li><code>checkValidity()</code> / <code>reportValidity()</code> — trigger validation</li>
+    <li>Access <code>.form</code>, <code>.labels</code>, <code>.validity</code></li>
+  </ul>
+  <code-ui language="javascript">class UIFormElement extends UIElement {
+  static formAssociated = true;
+
+  // Provided by the browser when formAssociated is true:
+  // this.internals = this.attachInternals();
+
+  get form() { return this.internals.form; }
+  get validity() { return this.internals.validity; }
+  get validationMessage() { return this.internals.validationMessage; }
+}</code-ui>
+</section>
+
+<section data-section data-property="constraint-validation">
+  <h2 variant="section">Constraint Validation</h2>
+  <p>
+    <code>UIFormElement</code> implements four constraint types that mirror native HTML
+    validation:
+  </p>
+  <table>
+    <thead>
+      <tr>
+        <th>Attribute</th>
+        <th>Validity Flag</th>
+        <th>Default Message</th>
+      </tr>
+    </thead>
+    <tbody>
+      <tr>
+        <td><code>required</code></td>
+        <td><code>valueMissing</code></td>
+        <td>"This field is required."</td>
+      </tr>
+      <tr>
+        <td><code>pattern="regex"</code></td>
+        <td><code>patternMismatch</code></td>
+        <td>"Please match the requested format."</td>
+      </tr>
+      <tr>
+        <td><code>minlength="n"</code></td>
+        <td><code>tooShort</code></td>
+        <td>"Please use at least n characters."</td>
+      </tr>
+      <tr>
+        <td><code>maxlength="n"</code></td>
+        <td><code>tooLong</code></td>
+        <td>"Please use no more than n characters."</td>
+      </tr>
+    </tbody>
+  </table>
+  <code-ui language="html">&lt;form&gt;
+  &lt;input-ui name="email" required pattern="[^@]+@[^@]+"
+    data-msg-required="Email is required"
+    data-msg-pattern="Enter a valid email"&gt;
+  &lt;/input-ui&gt;
+
+  &lt;input-ui name="username" required minlength="3" maxlength="20"
+    data-msg-minlength="Username must be at least 3 characters"
+    data-msg-maxlength="Username cannot exceed 20 characters"&gt;
+  &lt;/input-ui&gt;
+
+  &lt;button-ui type="submit" text="Submit" variant="primary"&gt;&lt;/button-ui&gt;
+&lt;/form&gt;</code-ui>
+</section>
+
+<section data-section data-property="auto-validation-lifecycle">
+  <h2 variant="section">Auto-Validation Lifecycle</h2>
+  <p>
+    AdiaUI implements a progressive validation UX that avoids showing errors prematurely.
+    The lifecycle is:
+  </p>
+  <ol>
+    <li><strong>On form submit:</strong> The browser fires the <code>invalid</code> event on any
+    field that fails validation. <code>UIFormElement</code> catches this, sets
+    <code>aria-invalid="true"</code>, and populates the <code>error</code> attribute with
+    the validation message.</li>
+    <li><strong>On input (while invalid):</strong> If the field currently has an error, every
+    keystroke re-validates. As soon as the value passes, the error is cleared immediately.
+    This gives instant positive feedback.</li>
+    <li><strong>On blur (if dirty):</strong> When the user tabs away from a field they have
+    typed in, validation runs. This catches errors on fields the user has interacted with
+    but not submitted.</li>
+    <li><strong>On form reset:</strong> All validation state is cleared — <code>error</code>
+    attribute removed, <code>aria-invalid</code> removed, dirty flag reset.</li>
+  </ol>
+  <p data-note>
+    The "dirty" flag ensures blur validation only fires after the user has actually
+    interacted with the field. A pristine field that receives focus and then loses it
+    will not show an error.
+  </p>
+</section>
+
+<section data-section data-property="custom-error-messages">
+  <h2 variant="section">Custom Error Messages</h2>
+  <p>
+    Override the default validation messages using <code>data-msg-*</code> attributes
+    on any form element:
+  </p>
+  <table>
+    <thead>
+      <tr>
+        <th>Attribute</th>
+        <th>Overrides</th>
+      </tr>
+    </thead>
+    <tbody>
+      <tr>
+        <td><code>data-msg-required</code></td>
+        <td>Message when field is empty and <code>required</code></td>
+      </tr>
+      <tr>
+        <td><code>data-msg-pattern</code></td>
+        <td>Message when value doesn't match <code>pattern</code></td>
+      </tr>
+      <tr>
+        <td><code>data-msg-minlength</code></td>
+        <td>Message when value is shorter than <code>minlength</code></td>
+      </tr>
+      <tr>
+        <td><code>data-msg-maxlength</code></td>
+        <td>Message when value exceeds <code>maxlength</code></td>
+      </tr>
+    </tbody>
+  </table>
+  <code-ui language="html">&lt;input-ui
+  name="phone"
+  required
+  pattern="\d{3}-\d{3}-\d{4}"
+  data-msg-required="Phone number is required"
+  data-msg-pattern="Use format: 123-456-7890"&gt;
+&lt;/input-ui&gt;</code-ui>
+</section>
+
+<section data-section data-property="manual-control">
+  <h2 variant="section">Manual Control</h2>
+  <p>
+    For cases where you need to validate programmatically or set custom errors
+    (e.g. server-side validation), use these methods:
+  </p>
+  <table>
+    <thead>
+      <tr>
+        <th>Method</th>
+        <th>Returns</th>
+        <th>Description</th>
+      </tr>
+    </thead>
+    <tbody>
+      <tr>
+        <td><code>validate()</code></td>
+        <td><code>boolean</code></td>
+        <td>Runs all constraints, surfaces error if invalid, clears if valid</td>
+      </tr>
+      <tr>
+        <td><code>setInvalid(message)</code></td>
+        <td><code>void</code></td>
+        <td>Sets a custom error — useful for async/server validation</td>
+      </tr>
+      <tr>
+        <td><code>setValid()</code></td>
+        <td><code>void</code></td>
+        <td>Clears all validation errors and <code>aria-invalid</code></td>
+      </tr>
+      <tr>
+        <td><code>syncValue(val)</code></td>
+        <td><code>void</code></td>
+        <td>Updates the form value and re-runs constraint validation</td>
+      </tr>
+    </tbody>
+  </table>
+  <code-ui language="javascript">const emailField = document.querySelector('input-ui[name="email"]');
+
+// Programmatic validation
+if (!emailField.validate()) {
+  console.log(emailField.validationMessage);
+}
+
+// Server-side error
+async function onSubmit() {
+  const res = await fetch('/api/check-email', { ... });
+  if (!res.ok) {
+    emailField.setInvalid('This email is already registered');
+  }
+}
+
+// Clear error after user action
+emailField.setValid();
+
+// Update form value programmatically
+emailField.syncValue('new@example.com');</code-ui>
+</section>
+
+<section data-section data-property="form-lifecycle-callbacks">
+  <h2 variant="section">Form Lifecycle Callbacks</h2>
+  <p>
+    <code>UIFormElement</code> implements the standard form-associated custom element
+    callbacks. Subclasses can override the hook methods:
+  </p>
+  <table>
+    <thead>
+      <tr>
+        <th>Browser Callback</th>
+        <th>Override Hook</th>
+        <th>When It Fires</th>
+      </tr>
+    </thead>
+    <tbody>
+      <tr>
+        <td><code>formResetCallback()</code></td>
+        <td><code>onFormReset()</code></td>
+        <td>When the parent form is reset</td>
+      </tr>
+      <tr>
+        <td><code>formDisabledCallback(disabled)</code></td>
+        <td><code>onFormDisabled(disabled)</code></td>
+        <td>When a parent fieldset is disabled/enabled</td>
+      </tr>
+      <tr>
+        <td><code>formAssociatedCallback(form)</code></td>
+        <td><code>onFormAssociated(form)</code></td>
+        <td>When the element is associated with a form</td>
+      </tr>
+      <tr>
+        <td><code>formStateRestoreCallback(state, reason)</code></td>
+        <td><code>onFormStateRestore(state, reason)</code></td>
+        <td>When browser restores form state (back/forward navigation)</td>
+      </tr>
+    </tbody>
+  </table>
+</section>
+
+<section data-section data-property="live-demo">
+  <h2 variant="section">Live Demo</h2>
+  <p>Try submitting the form below without filling in the fields to see auto-validation in action:</p>
+  <div data-artifact-container>
+  <div data-artifact-item data-artifact-label="form">
+    <form data-chunk="form-system-live-demo" style="display:flex; flex-direction:column; gap:var(--a-space-3); max-width:400px;" onsubmit="event.preventDefault();">
+          <field-ui label="Full Name">
+            <input-ui name="fullname" required minlength="2" data-msg-required="Please enter your name" data-msg-minlength="Name must be at least 2 characters">
+          </input-ui>
+          </field-ui>
+
+          <field-ui label="Email">
+            <input-ui name="email" required pattern="[^@\s]+@[^@\s]+\.[^@\s]+" data-msg-required="Email is required" data-msg-pattern="Please enter a valid email address">
+          </input-ui>
+          </field-ui>
+
+          <field-ui label="Username">
+            <input-ui name="username" required minlength="3" maxlength="15" pattern="[a-z0-9_]+" data-msg-required="Username is required" data-msg-minlength="At least 3 characters" data-msg-maxlength="No more than 15 characters" data-msg-pattern="Lowercase letters, numbers, and underscores only">
+          </input-ui>
+          </field-ui>
+
+          <div style="display:flex; gap:var(--a-space-2);">
+            <button-ui type="submit" text="Submit" variant="primary"></button-ui>
+            <button-ui type="reset" text="Reset" variant="outline"></button-ui>
+          </div>
+        </form>
+  </div>
+</div>
+</section>
+
+<section data-section data-property="extending-uiformelement">
+  <h2 variant="section">Extending UIFormElement</h2>
+  <p>
+    To create a new form-participating component, extend <code>UIFormElement</code>
+    and call <code>syncValue()</code> whenever the internal value changes:
+  </p>
+  <code-ui language="javascript">import { UIFormElement } from '@core/form.js';
+
+class MyRating extends UIFormElement {
+  static properties = {
+    ...UIFormElement.properties,
+    max: { type: Number, default: 5, reflect: true },
+  };
+
+  render() {
+    // Render stars, handle clicks...
+  }
+
+  #onStarClick(rating) {
+    this.value = String(rating);
+    this.syncValue(this.value);  // updates form + runs validation
+    this.dispatch('change', { value: this.value });
+  }
+
+  onFormReset() {
+    this.value = '';
+    // Reset visual state...
+  }
+}
+
+customElements.define('my-rating', MyRating);</code-ui>
+  <p data-note>
+    Always call <code>syncValue()</code> after changing the component's value. This
+    updates the form's submission data and runs constraint validation so errors
+    clear as soon as the value becomes valid.
+  </p>
+</section>
+
+<section data-section data-property="rules">
+  <h2 variant="section">Authoring rules</h2>
+  <ul>
+    <li><strong>Extend <code>UIFormElement</code>, not <code>UIElement</code></strong>, when the component must participate in native form submission. <code>UIFormElement</code> handles <code>ElementInternals</code>, constraint validation, and the dirty-state lifecycle automatically.</li>
+    <li><strong>Always call <code>syncValue()</code></strong> after changing the component's internal value. This updates the form's submission data and runs constraint validation so errors clear as soon as the value becomes valid.</li>
+    <li><strong>Do not manipulate the <code>field-ui</code> error attribute directly.</strong> Use <code>setCustomError()</code> and <code>clearErrors()</code> from the base class — these coordinate with the field wrapper's ARIA live region.</li>
+    <li><strong>Every form control needs a <code>name</code> attribute</strong> for its value to be included in <code>FormData</code> on submit. Components without <code>name</code> are invisible to the form.</li>
+    <li><strong>Required validation belongs on <code>field-ui required</code></strong>, not only on the inner control. The field wrapper surfaces the asterisk and the ARIA required state; the inner control handles native constraint validation.</li>
+    <li><strong>Never bypass the auto-validation lifecycle</strong> by setting <code>validity.valid = false</code> from the outside. If you need a custom error from application code, use the MCP <code>submit_feedback</code> pattern or call <code>setCustomValidity()</code> on the internal form element.</li>
+  </ul>
+</section>

package/patterns/form-system/form-system.html

@@ -0,0 +1,48 @@
+<!DOCTYPE html>
+<html lang="en" theme="auto">
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <title>Form System (pattern) — AdiaUI</title>
+
+  <!-- Token base -->
+  <link rel="stylesheet" href="../../styles/resets.css">
+  <link rel="stylesheet" href="../../styles/tokens.css">
+
+  <!-- Component CSS — primitives this pattern composes -->
+  <link rel="stylesheet" href="../../components/button/button.css">
+  <link rel="stylesheet" href="../../components/code/code.css">
+  <link rel="stylesheet" href="../../components/field/field.css">
+  <link rel="stylesheet" href="../../components/input/input.css">
+
+  <!-- Component JS -->
+  <script type="module" src="../../components/button/button.js"></script>
+  <script type="module" src="../../components/code/code.js"></script>
+  <script type="module" src="../../components/field/field.js"></script>
+  <script type="module" src="../../components/input/input.js"></script>
+
+  <style>
+    :where(html, body) { margin: 0; min-height: 100vh; background: var(--md-sys-color-neutral-background); color: var(--md-sys-color-neutral-on-surface); font-family: var(--a-font-family); }
+    main { max-width: 960px; margin-inline: auto; padding: var(--a-space-6) var(--a-space-5); }
+  </style>
+</head>
+<body>
+
+  <main id="demo-root">
+    <p>Loading examples…</p>
+  </main>
+
+  <script type="module">
+    const root = document.getElementById('demo-root');
+    try {
+      const res = await fetch('./form-system.examples.html');
+      if (!res.ok) throw new Error(`fetch failed (${res.status})`);
+      root.innerHTML = await res.text();
+    } catch (err) {
+      root.innerHTML = `<p style="color:var(--a-danger-strong);">Failed to load form-system.examples.html — ${err.message}</p>`;
+      console.error('[form-system.html]', err);
+    }
+  </script>
+
+</body>
+</html>

package/patterns/forms-conditional-and-autocomplete/forms-conditional-and-autocomplete.examples.html

@@ -0,0 +1,189 @@
+<header>
+  <div>
+    <h1>Conditional fields &amp; address autocomplete</h1>
+    <div data-actions>
+      <tag-ui size="sm">field-ui</tag-ui> <tag-ui size="sm">input-ui</tag-ui> <tag-ui size="sm">select-ui</tag-ui> <tag-ui size="sm">card-ui</tag-ui> <tag-ui size="sm">radio-ui</tag-ui>
+    </div>
+  </div>
+  <p>Two adjacent form patterns: revealing fields based on prior answers (07i) and address-input that resolves a free-text query into structured fields (07j). Both compose existing form primitives — the pattern is in the wiring, not in new components.</p>
+</header>
+
+<section data-section data-property="when-to-use">
+  <h2 variant="section">When to use</h2>
+  <p data-note>
+    Conditional reveal: when the field set depends on a categorical
+    answer ("If 'Other', specify…", "If 'Business', show tax ID").
+    Address autocomplete: any place a user enters a postal address
+    that downstream systems need structured (billing, shipping,
+    KYC, support tickets).
+  </p>
+</section>
+
+<section data-section data-property="conditional-reveal">
+  <h2 variant="section">Conditional reveal</h2>
+  <p data-note>A select or radio determines which sub-fields render. Hidden fields are not just `display: none` — they're removed from the form so they don't submit. When revealed, they animate in and the form's height grows; focus moves to the first revealed field.</p>
+  <div data-artifact-container>
+    <div data-artifact-item data-artifact-label="conditional fields">
+      <card-ui data-chunk="forms-conditional-reveal" style="max-width: 560px;">
+        <header>
+          <span slot="heading" variant="section">Account type</span>
+          <text-ui slot="description" color="subtle">We'll show the fields you need based on this</text-ui>
+        </header>
+        <section>
+          <col-ui gap="3">
+            <field-ui label="Account type" required>
+              <select-ui name="account_type">
+                <option value="personal">Personal</option>
+                <option value="business" selected>Business</option>
+                <option value="nonprofit">Non-profit</option>
+              </select-ui>
+            </field-ui>
+            <field-ui label="Legal entity name" hint="Matches your business registration" required>
+              <input-ui name="entity_name" placeholder="Adia Labs, Inc."></input-ui>
+            </field-ui>
+            <field-ui label="Tax ID / EIN" required>
+              <input-ui name="tax_id" placeholder="00-0000000"></input-ui>
+            </field-ui>
+            <field-ui label="Industry">
+              <select-ui name="industry">
+                <option value="">Choose one…</option>
+                <option value="software">Software</option>
+                <option value="retail">Retail</option>
+                <option value="services">Services</option>
+                <option value="other">Other</option>
+              </select-ui>
+            </field-ui>
+            <field-ui label="Industry — please specify" hint="Required when 'Other' is selected" required>
+              <input-ui name="industry_other" placeholder="e.g., Renewable energy"></input-ui>
+            </field-ui>
+          </col-ui>
+        </section>
+      </card-ui>
+    </div>
+  </div>
+</section>
+
+<section data-section data-property="address-autocomplete">
+  <h2 variant="section">Address autocomplete</h2>
+  <p data-note>Single input that opens a `menu-ui` of suggestions as the user types. Each suggestion shows the formatted address with the matched portion highlighted. Selecting a suggestion fills the structured fields below; clicking "Enter manually" reveals the structured fields directly.</p>
+  <div data-artifact-container>
+    <div data-artifact-item data-artifact-label="address autocomplete">
+      <card-ui data-chunk="forms-address-autocomplete" style="max-width: 560px;">
+        <header>
+          <span slot="heading" variant="section">Billing address</span>
+        </header>
+        <section>
+          <col-ui gap="2">
+            <field-ui label="Search address" hint="Start typing — we'll suggest matches">
+              <input-ui name="address_query" placeholder="123 Main St" icon-leading="map-pin" value="500 market"></input-ui>
+            </field-ui>
+            <card-ui raw style="max-width: 100%;" data-shape="popover">
+              <section>
+                <col-ui gap="2">
+                  <row-ui gap="2" align="center">
+                    <icon-ui name="map-pin" size="sm"></icon-ui>
+                    <col-ui gap="0" style="flex: 1;">
+                      <text-ui><strong>500 Market</strong> Street</text-ui>
+                      <text-ui color="subtle" size="sm">San Francisco, CA 94105 · USA</text-ui>
+                    </col-ui>
+                  </row-ui>
+                  <row-ui gap="2" align="center">
+                    <icon-ui name="map-pin" size="sm"></icon-ui>
+                    <col-ui gap="0" style="flex: 1;">
+                      <text-ui><strong>500 Market</strong> Place</text-ui>
+                      <text-ui color="subtle" size="sm">Chattanooga, TN 37402 · USA</text-ui>
+                    </col-ui>
+                  </row-ui>
+                  <row-ui gap="2" align="center">
+                    <icon-ui name="map-pin" size="sm"></icon-ui>
+                    <col-ui gap="0" style="flex: 1;">
+                      <text-ui><strong>500 Market</strong> Square</text-ui>
+                      <text-ui color="subtle" size="sm">Pittsburgh, PA 15222 · USA</text-ui>
+                    </col-ui>
+                  </row-ui>
+                  <divider-ui></divider-ui>
+                  <row-ui gap="2" align="center">
+                    <icon-ui name="pencil-simple" size="sm"></icon-ui>
+                    <text-ui style="flex: 1;">Enter address manually</text-ui>
+                  </row-ui>
+                </col-ui>
+              </section>
+            </card-ui>
+          </col-ui>
+        </section>
+      </card-ui>
+    </div>
+  </div>
+</section>
+
+<section data-section data-property="address-fields">
+  <h2 variant="section">Resolved address — structured fields</h2>
+  <p data-note>After a suggestion is picked (or the user chose "Enter manually"), the structured fields appear, prefilled. The user can correct any line. Country drives the field set — US postal codes are different shape from CA, UK, etc.</p>
+  <div data-artifact-container>
+    <div data-artifact-item data-artifact-label="resolved address fields">
+      <card-ui data-chunk="forms-address-fields" style="max-width: 560px;">
+        <header>
+          <span slot="heading" variant="section">Address details</span>
+          <button-ui slot="action" text="Search again" variant="ghost" size="sm" icon-leading="arrow-counter-clockwise"></button-ui>
+        </header>
+        <section>
+          <col-ui gap="3">
+            <field-ui label="Street address" required>
+              <input-ui name="street1" value="500 Market Street"></input-ui>
+            </field-ui>
+            <field-ui label="Apt / Suite (optional)">
+              <input-ui name="street2" placeholder="Suite 200"></input-ui>
+            </field-ui>
+            <grid-ui columns="2" gap="3">
+              <field-ui label="City" required>
+                <input-ui name="city" value="San Francisco"></input-ui>
+              </field-ui>
+              <field-ui label="State" required>
+                <select-ui name="state">
+                  <option value="CA" selected>California</option>
+                  <option value="NY">New York</option>
+                  <option value="TX">Texas</option>
+                </select-ui>
+              </field-ui>
+            </grid-ui>
+            <grid-ui columns="2" gap="3">
+              <field-ui label="ZIP code" required>
+                <input-ui name="postal_code" value="94105"></input-ui>
+              </field-ui>
+              <field-ui label="Country" required>
+                <select-ui name="country">
+                  <option value="US" selected>United States</option>
+                  <option value="CA">Canada</option>
+                  <option value="GB">United Kingdom</option>
+                </select-ui>
+              </field-ui>
+            </grid-ui>
+          </col-ui>
+        </section>
+      </card-ui>
+    </div>
+  </div>
+</section>
+
+<section data-section data-property="composition">
+  <h2 variant="section">Composition rules</h2>
+  <ul>
+    <li><strong>Hidden fields are removed from the form, not just visually hidden</strong> — `display: none` still submits the value. Use `hidden` attr or detach from the DOM so a stale "Other — please specify" answer doesn't leak.</li>
+    <li><strong>Animate the reveal, focus the first new field</strong> — silent appearance is jarring. A height transition + focus call makes the form feel responsive without a separate page navigation.</li>
+    <li><strong>Country drives the address field set</strong> — US has state + ZIP; Canada has province + postal code; UK has county + postcode. A single "State / Province / Region" mega-label is worse than per-country layouts.</li>
+    <li><strong>Always allow manual entry</strong> — autocomplete services miss new addresses, edge cases, and apartments. The "Enter manually" escape hatch is mandatory.</li>
+    <li><strong>Highlight the matched portion in suggestions</strong> — `<strong>500 Market</strong> Street` reads faster than the unhighlighted full string. Use the user's query, not the API's match field, since they may diverge.</li>
+    <li><strong>Suggestions cap at 5</strong> — beyond that the picker becomes scroll-heavy. Refine the query, don't grow the menu.</li>
+    <li><strong>Required fields stay required when revealed</strong> — conditional reveal is a UX layer, not a constraint layer. The form-level validation should treat revealed required fields as required.</li>
+  </ul>
+</section>
+
+<section data-section data-property="cross-references">
+  <h2 variant="section">See also</h2>
+  <ul>
+    <li><a href="/site/components/field">field-ui</a> · <a href="/site/components/input">input-ui</a> · <a href="/site/components/select">select-ui</a> — form primitives.</li>
+    <li><a href="/site/components/menu">menu-ui</a> — autocomplete popover host.</li>
+    <li><a href="/site/patterns/form-drawer">form-drawer</a> — typical host for these surfaces.</li>
+    <li><a href="/site/patterns/wizard-drawer">wizard-drawer</a> — multi-step form host.</li>
+  </ul>
+</section>