better and simpler docs

Author: nickamantia

playbook/app/pb_kits/playbook/pb_dropdown/docs/_dropdown_dynamic_options.md

@@ -1,44 +1,7 @@
-Dropdown options can be replaced at runtime without a page reload. Use this for dependent fields (for example, a region select that determines city options) or for data loaded from Turbo/custom events.
+You can set up a dropdown to update its options dynamically based on another input (for example, a region select that drives city options). To achieve this:
+- Give the dropdown a unique `id` so it can be targeted by events and linked to a controlling input.
+- Use `context_selector` to point at the controlling select’s `id`. When that select’s value changes, the Dropdown reads the new value as its current context.
+- Use `options_by_context` to pass a hash of option lists. Keys must match the possible values of the controlling select; each key maps to an array of `{ id, label, value }` options that replace the Dropdown’s options for that context.
+- Use `clear_on_context_change` (defaults to `true`) to clear the Dropdown’s current selection whenever the controlling select changes. Set it to `false` if you want to keep a selection that still exists in the new options.
 
-## Declarative: `options_by_context`
-
-Similar to Typeahead, pass a hash of option arrays keyed by the value of a controlling input:
-
-- Give the dependent dropdown a unique `id`
-- Set `context_selector` to the id of the controlling select (or other input)
-- Pass `options_by_context` with keys matching the controller's possible values
-- Optionally set `clear_on_context_change` to `false` to keep the current selection when the context changes (defaults to `true`)
-
-Each option uses the standard Dropdown shape: `{ id, label, value }`. If `id` is omitted, `value` is used.
-
-## Imperative: `pb:dropdown:updateOptions`
-
-Dispatch a document-level custom event to replace options for a specific dropdown:
-
-```javascript
-document.dispatchEvent(new CustomEvent("pb:dropdown:updateOptions", {
-  detail: {
-    dropdownId: "city-dropdown",
-    options: [
-      { id: "nyc", label: "New York", value: "nyc" },
-      { id: "la", label: "Los Angeles", value: "la" },
-    ],
-    clearSelection: true, // optional, defaults to true
-  },
-}));
-```
-
-## Custom and Turbo events: `options_event_type`
-
-Set `options_event_type` to a comma-separated list of event names. When any of those events fire with `detail.options` (and optional `detail.dropdownId`), the matching dropdown replaces its options. This works well with Turbo frame loads or app-specific events:
-
-```javascript
-document.dispatchEvent(new CustomEvent("cities:loaded", {
-  detail: {
-    dropdownId: "city-dropdown",
-    options: [{ id: "chi", label: "Chicago", value: "chi" }],
-  },
-}));
-```
-
-Existing external control events (`pb:dropdown:clear`, `pb:dropdown:select`, and `custom_event_type` for clearing) continue to work alongside option updates.
+You can also replace options imperatively by dispatching `pb:dropdown:updateOptions` with `detail: { dropdownId, options }`, or by setting `options_event_type` to a comma-separated list of custom/Turbo event names. When those events fire with `detail.options` (and optional `detail.dropdownId`), the matching Dropdown updates its options.