1T DROPDOWNS: SETUP GUIDE
Full documentation and examples: see the documentation link on this page.

WHICH ELEMENT TO USE

- 1T - Dropdown v2: single select, multiselect, and server-side search in one element. Recommended for all new pages.
- 1T - Popover: opens a Bubble Group as an anchored menu or a drawer.
- 1T - Dropdown, 1T - MultiSelect, 1T - Dropdown (API) - [BETA]: the original elements. Unchanged and still supported. Keep using them on existing pages if they work for you.

1T - Dropdown v2 and 1T - Popover need native Popover and CSS Anchor Positioning in the browser. See "Browser support" at the end.

--------------------------------------------------
1T - DROPDOWN V2
--------------------------------------------------

1. ADD THE ELEMENT
Drag "1T - Dropdown v2" onto the page (it is under Input forms). Give it a width; height fits its content.

2. CHOOSE WHERE OPTIONS COME FROM

Option A: Dynamic options (bind a Bubble list)
- Dynamic options type: the data type, for example Client.
- Dynamic options: a list expression of that type, for example "Search for Clients".
- Dynamic options text field: the field key to show as the option label, for example name_text. Enter the field key, not an expression. Keys are never treated as HTML.
Each Thing becomes an option. Its unique id is the option value. While Dynamic options is set, Options JSON is ignored.

Option B: Options JSON (static list or your own expression)
Paste or build a JSON array in "Options JSON":
[{"text":"Draft","value":"draft"},{"text":"Sent","value":"sent"}]
- "text" is the label, "value" is the id. Values must be unique and not empty. Text is never rendered as HTML.
- Optional keys per option: "image" (URL), "secondaryText", "badge".
- Groups: {"label":"Group name","options":[ ... ]}.
- If the JSON is invalid, the element keeps its last good state and sets the "Error message" state. The "Invalid options received" event fires.

3. RETURN DATA TYPE
Set "Return data type" to the data type your values represent. Values must be Bubble unique ids for this to work. The "Selected option" and "Selected options" states then return real Things. If your values are plain text, leave it empty and use "Selected value" / "Selected values" instead.

4. SINGLE OR MULTIPLE
- Leave "Allow multiple selections" off for a single select. Use "Default value" for the initial selection.
- Turn it on for a multiselect with removable chips. Use "Default values" for the initial list. "Maximum selections" caps the list (0 or empty = unlimited).

5. BASIC OPTIONS
Placeholder, Searchable, Clearable, Input is disabled, No-results text, Accessible label (the name screen readers announce, for example "Assignee").

6. SERVER-SIDE SEARCH (large data sets)
Turn on "Server-side search". The element stops filtering locally. Then:
- Set "Minimum characters" and "Search debounce (ms)" to control when "Search changed" fires. "Loading text" shows while you fetch.
- Add a workflow: When 1T - Dropdown v2's "Search changed" runs, do "Set options" on the element.
- In "Set options", either pass "Things type" + "Things" (for example Search for Clients with a constraint on the element's "Search term" state) + "Text field", or pass "Options JSON". Pass the element's "Search term" into the action's "Search term" so late results for an old query are discarded.

7. LET USERS CREATE OPTIONS
Turn on "Allow creating options". When a typed term has no match, the user can add it. The trimmed term becomes both text and value. The "Option created" event fires, and "Created option text" / "Created option value" hold what was added. Use that event to save the new record.

8. PLACEMENT AND STYLING
- Preferred placement: Auto, Down, Up, Right, Left, Bottom span-right, Right span-bottom. "Panel alignment" refines the side. Advanced users can set "Custom position-area" and "Custom position fallbacks" (CSS values).
- Colors: Background, Border, Placeholder, Focus, Active option background, Selected option background, Disabled background and text, Secondary text, Badge, Multi-select chip.
- Border width and radius, Item image size, shape, and fit.
- Fonts: family, size (pixels), and weight for the control, the options, and the chips. Empty fields inherit: options from the control, chips from options.

STATES
Selected option, Selected value, Selected label, Selected options, Selected values, Selected labels, Selection count, Search term, Is open, Is disabled, Is loading, Error message, Created option text, Created option value.

EVENTS
Selection changed, Selection cleared, Opened, Closed, Search changed, Invalid options received, Option created.

ACTIONS
Set selected value, Set selected values, Add selected value, Remove selected value, Clear selection, Set options, Open, Close, Focus, Reset.

--------------------------------------------------
1T - POPOVER
--------------------------------------------------

The popover does not draw its own content. It takes a Group you already built and opens it beside a trigger or as a drawer.

1. BUILD THE PIECES
- A trigger: any Bubble element (button, icon, group). Give it an ID Attribute, for example btn-account.
- A content Group: build it as normal, leave it visible on page load, and give it an ID Attribute, for example grp-account. The plugin hides it and shows it when opened.
- Drag "1T - Popover" onto the page (under Visual elements). It can be small; it is not visible at run time.

2. CONNECT THEM
- Instance key: a unique name for this popover, for example account.
- Trigger ID: btn-account
- Content ID: grp-account
- Open on trigger click: on by default. Turn it off if you only open it from workflows.

3. PICK A DISPLAY MODE
- Anchored: opens next to the trigger, like a Group Focus. Set "Preferred placement" with a CSS position-area value, for example bottom span-right (below, left edges aligned) or right span-top. "Position fallbacks" lists what to try if it does not fit; enter none to disable. "Gap" is the space from the trigger in pixels.
- Bottom drawer: slides up from the bottom of the window, centered.
- Right drawer: fills the height of the window against the right edge.
- Responsive drawer: Right drawer on wide screens, Bottom drawer at or below "Mobile breakpoint" (default 640).

4. SIZE AND BEHAVIOR
- Width mode: Fixed, Trigger, or Content. Drawers always use "Width".
- Width, Maximum height, Viewport inset.
- Scroll body ID: the ID of an inner Group that should scroll while the header and footer stay put.
- Modal: dims the page, locks scrolling, and keeps focus inside until closed. Works with any display mode. Required for nested drawers.
- Close on Escape, Close on outside click, Restore focus (return focus to the trigger after closing).
- Accessible label: the dialog name for screen readers.

5. NESTED DRAWERS
Open a drawer from inside another: set the child's "Parent instance key" to the parent's Instance key. Both must be modal drawers. Escape and outside click close only the top level.

6. REPEATING GROUPS
Put the trigger, the content Group, and the 1T - Popover element inside the cell. Give the cell's group an ID Attribute and enter it in "Scope ID" on the popover. Each row then gets its own popover with the same Instance key, Trigger ID, and Content ID.

STATES
Is open, Error message.

EVENTS
Opened, Closed, Configuration error (fires when IDs do not resolve or a setting is invalid; read "Error message").

ACTIONS
Open, Close, Toggle.

--------------------------------------------------
ORIGINAL ELEMENTS: 1T - DROPDOWN, 1T - MULTISELECT, 1T - DROPDOWN (API)
--------------------------------------------------

These elements are unchanged in this release.

- Add the element to the page and size it.
- Return data type: the type of data you want the "Selected option" (or "Selected options") state to return.
- Options: a JSON array with "text" and "value" keys, for example [{"text":"value1","value":"value1id"},{"text":"value2","value":"value2id"}].
- For dynamic data, do a search and use the "format as text" operator on the results to build that JSON array, then put the expression in "Options".
- For static data, paste the JSON array directly into "Options".
- "value" is the unique id used to set the selected state. For a custom data type use the record's Unique ID. For an option set use the Display attribute. For plain text use any value that makes sense for you.
- 1T - Dropdown (API) - [BETA] fetches options from an endpoint instead: it makes a GET request with "search" (what the user typed) and "value" (the default value) parameters. Return the same JSON array.

--------------------------------------------------
BROWSER SUPPORT
--------------------------------------------------

1T - Dropdown v2 and 1T - Popover require native Popover and CSS Anchor Positioning. There is no fallback for browsers that lack them: 1T - Dropdown v2 shows a short message in place of the control, and 1T - Popover reports the problem in its "Error message" state. We have verified the new elements in Chromium-based browsers (Chrome, Edge). We have not yet verified Safari or Firefox. The original three elements are not affected.

--------------------------------------------------
UPDATING
--------------------------------------------------

Updating to v3.0 does not change the original elements. Pages that use them keep working. Pages without them no longer load the dropdown library, which makes those pages lighter. Please test your pages after updating.

Built and maintained by Eli Beachy and Rico Trevisan.