Prepare 1.0.0 beta release

docs/src/components/combobox.md

@@ -106,7 +106,7 @@ toc:
 <section class="prose">
   <dl>
     <dt><code class="highlight language-html">&lt;div class="combobox"&gt;</code></dt>
-    <dd>Root element. Add <code>data-multiple="true"</code> for multiple selection and <code>data-auto-highlight="true"</code> to highlight the first match while filtering.</dd>
+    <dd>Root element. Add <code>data-auto-highlight="true"</code> to highlight the first match while filtering. Add <code>data-format="object"</code> to serialize selected values as <code>{ value, label }</code> objects in the hidden input. Add <code>data-filter="manual"</code> when your app owns filtering, such as remote autocomplete or a local Lunr index.</dd>
     <dt><code class="highlight language-html">&lt;input type="text" role="combobox"&gt;</code></dt>
     <dd>The editable control. It should include <code>aria-expanded</code>, <code>aria-controls</code>, and <code>aria-autocomplete="list"</code>.</dd>
     <dt><code class="highlight language-html">&lt;div class="combobox-chips"&gt;</code> <span class="badge-secondary">Multiple only</span></dt>
@@ -118,7 +118,7 @@ toc:
     <dt><code class="highlight language-html">&lt;div role="option" data-value="..."&gt;</code></dt>
     <dd>Selectable option. Options can contain custom HTML; use <code>data-label</code> when the visible input should use different text than the rendered content.</dd>
     <dt><code class="highlight language-html">&lt;input type="hidden"&gt;</code></dt>
-    <dd>Submitted value. Single mode stores a string; multiple mode stores a JSON array.</dd>
+    <dd>Submitted value. Single mode stores a string; multiple mode stores a JSON array. With <code>data-format="object"</code>, single mode stores a JSON object and multiple mode stores a JSON array of objects.</dd>
   </dl>
 </section>
 
@@ -131,7 +131,7 @@ toc:
     <dt><code>basecoat:popover</code></dt>
     <dd>Dispatched on <code>document</code> when the popup opens so other popup components can close.</dd>
     <dt><code>change</code></dt>
-    <dd>Dispatched on selection changes with <code>event.detail.value</code>.</dd>
+    <dd>Dispatched on selection changes with <code>event.detail.value</code> and <code>event.detail.selected</code>. <code>value</code> is the canonical value or array of values; <code>selected</code> is the matching <code>{ value, label }</code> object or array.</dd>
   </dl>
 </section>
 
@@ -141,6 +141,10 @@ toc:
   <dl>
     <dt><code>value</code></dt>
     <dd>Gets or sets the selected value. Multiple mode uses an array.</dd>
+    <dt><code>selected</code></dt>
+    <dd>Gets the selected <code>{ value, label }</code> object. Multiple mode returns an array.</dd>
+    <dt><code>setValue(value)</code></dt>
+    <dd>Sets the selected value. Accepts plain values or <code>{ value, label }</code> objects, which is useful when hydrating remote autocomplete selections before the option exists in the list.</dd>
     <dt><code>select(value)</code></dt>
     <dd>Selects an option by value.</dd>
     <dt><code>deselect(value)</code> <span class="badge-secondary">Multiple only</span></dt>
@@ -149,6 +153,8 @@ toc:
     <dd>Toggles a selected value.</dd>
     <dt><code>refresh()</code></dt>
     <dd>Rescans options after changing children inside the existing <code>role="listbox"</code> element.</dd>
+    <dt><code>data-filter="manual"</code></dt>
+    <dd>Disables Basecoat's built-in text filtering. Update the listbox options yourself, then call <code>combobox.refresh()</code>.</dd>
     <dt><code>window.basecoat.refresh(combobox)</code></dt>
     <dd>Calls the component refresh method through the global dispatcher.</dd>
   </dl>

docs/src/components/command.md

@@ -150,7 +150,7 @@ toc:
     <dd>Dialog variant. Wraps one <code>&lt;div class="command"&gt;</code>. Add <code>aria-label</code> or <code>aria-labelledby</code> for an accessible name.
       <dl>
         <dt><code class="highlight language-html">&lt;div class="command"&gt;</code></dt>
-        <dd>Root command menu. Can also be used standalone without the dialog wrapper.
+        <dd>Root command menu. Can also be used standalone without the dialog wrapper. Add <code>data-filter="manual"</code> when your app owns filtering, such as remote search or a local Lunr index.
           <dl>
             <dt><code class="highlight language-html">&lt;header&gt;</code></dt>
             <dd>Search input wrapper. The macro includes a search icon and input.
@@ -191,6 +191,8 @@ toc:
     <dd>Once the component is initialized, it dispatches a custom non-bubbling <code>basecoat:initialized</code> event on itself.</dd>
     <dt><code>command.refresh()</code></dt>
     <dd>Rescans command items after changing children inside the existing <code>role="menu"</code> list.</dd>
+    <dt><code>data-filter="manual"</code></dt>
+    <dd>Disables Basecoat's built-in text filtering. Update the menu items yourself, then call <code>command.refresh()</code>.</dd>
     <dt><code>window.basecoat.refresh(command)</code></dt>
     <dd>Calls the component refresh method through the global dispatcher.</dd>
   </dl>

docs/src/components/select.md

@@ -114,6 +114,7 @@ toc:
       <ul>
         <li><code>data-placeholder="{ TEXT }"</code> <span class="badge-secondary">Optional</span>: placeholder text shown when no options are selected (multiselect only).</li>
         <li><code>data-close-on-select="true"</code> <span class="badge-secondary">Optional</span>: closes the popover when selecting an option in multiselect mode.</li>
+        <li><code>data-format="object"</code> <span class="badge-secondary">Optional</span>: serializes selected values as <code>{ value, label }</code> objects in the hidden input.</li>
       </ul>
       <dl>
         <dt><code class="highlight language-html">&lt;button type="button"&gt;</code></dt>
@@ -165,6 +166,7 @@ toc:
       <p>The hidden input that holds the selected value.</p>
       <p>For single-select: contains the selected option's value as a string.</p>
       <p>For multiselect: contains a <strong>JSON array</strong> of selected values (e.g., <code>["apple","banana"]</code>). When no options are selected, contains an empty array (<code>[]</code>).</p>
+      <p>With <code>data-format="object"</code>: single-select contains a JSON object (e.g., <code>{"value":"apple","label":"Apple"}</code>) and multiselect contains a JSON array of objects.</p>
       <p><strong>Backend handling:</strong> Parse the JSON value on the server side. For example:</p>
       <ul>
         <li><strong>Python/Flask:</strong> <code>values = json.loads(request.form.get('field', '[]'))</code></li>
@@ -186,10 +188,10 @@ toc:
     <dd>When the popover opens, the component dispatches a custom (non-bubbling) <code>basecoat:popover</code> event on <code>document</code>. Other popover components (Combobox, Dropdown Menu, Popover and Select) listen for this to close any open popovers.</dd>
     <dt><code>change</code></dt>
     <dd>
-      <p>When the selected value changes, the component dispatches a custom (bubbling) <code>change</code> event on itself, with the selected value in <code>event.detail.value</code>:</p>
+      <p>When the selected value changes, the component dispatches a custom (bubbling) <code>change</code> event on itself, with the selected value in <code>event.detail.value</code> and the selected object payload in <code>event.detail.selected</code>:</p>
       <ul>
-        <li>Single select: <code>{ detail: { value: "something" }}</code> (string)</li>
-        <li>Multiple select: <code>{ detail: { value: ["item1", "item2"] }}</code> (array)</li>
+        <li>Single select: <code>{ detail: { value: "apple", selected: { value: "apple", label: "Apple" } }}</code></li>
+        <li>Multiple select: <code>{ detail: { value: ["apple", "banana"], selected: [{ value: "apple", label: "Apple" }, { value: "banana", label: "Banana" }] }}</code></li>
       </ul>
     </dd>
   </dl>
@@ -219,6 +221,10 @@ toc:
 </script>{% endset %}
 {{ code_block(code_value | prettyHtml, "html") }}
     </dd>
+    <dt><code>selected</code> (property)</dt>
+    <dd>
+      <p>Gets the selected <code>{ value, label }</code> object. For multiselect, returns an array.</p>
+    </dd>
     <dt><code>select(value)</code></dt>
     <dd>
       <p>Selects an option by value (i.e. the option with the matching <code>data-value</code> attribute). For single-select, this will close the popover. For multiselect, this adds the value to the selection if not already selected.</p>