tyrell-components 1.0.0-RC17 → 1.0.0-RC19

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -3,6 +3,14 @@
3
3
  * Cardinality follows native <select>: default single (scalar value, picking closes
4
4
  * the popup), `multiple` toggles options and submits repeated `name=` FormData entries.
5
5
  * Skins: default form field, `compact` content-hugging trigger, slot="trigger" custom.
6
+ *
7
+ * The selection is the `value` attribute/property, nothing else. Options are a
8
+ * plain list: the select draws their check through `option.checked`, a
9
+ * property, and never writes selection state onto them. A closed single select
10
+ * shows the picked option itself in its trigger (manual slot assignment), so
11
+ * nothing is added to the children a framework renders. `external-selection` hands
12
+ * the selection to the app: it marks the options it holds `selected`, the
13
+ * select reads those marks and reports picks as `change` events.
6
14
  */
7
15
  import type { Flavor, Size } from "../types/common.js";
8
16
  import { type Placement } from "../utils/positioning.js";
@@ -18,13 +26,13 @@ interface SelectState {
18
26
  search: string;
19
27
  highlightedIndex: number;
20
28
  filteredTags: TagData[];
21
- selectedValues: string[];
22
29
  mode: "desktop" | "mobile";
23
30
  }
24
31
  /**
25
32
  * Ty Select Component
26
33
  */
27
34
  export declare class TySelect extends TyComponent<SelectState> {
35
+ protected static slotAssignment: SlotAssignmentMode;
28
36
  protected static properties: {
29
37
  value: {
30
38
  type: "string";
@@ -87,25 +95,21 @@ export declare class TySelect extends TyComponent<SelectState> {
87
95
  type: "boolean";
88
96
  visual: boolean;
89
97
  default: boolean;
90
- aliases: {
91
- "external-search": boolean;
92
- };
98
+ };
99
+ externalSelection: {
100
+ type: "boolean";
101
+ visual: boolean;
102
+ default: boolean;
93
103
  };
94
104
  allowCreate: {
95
105
  type: "boolean";
96
106
  visual: boolean;
97
107
  default: boolean;
98
- aliases: {
99
- "allow-create": boolean;
100
- };
101
108
  };
102
109
  createTransform: {
103
110
  type: "string";
104
111
  visual: boolean;
105
112
  default: string;
106
- aliases: {
107
- "create-transform": boolean;
108
- };
109
113
  coerce: (v: any) => "none" | "slug";
110
114
  };
111
115
  notSearchable: {
@@ -113,13 +117,6 @@ export declare class TySelect extends TyComponent<SelectState> {
113
117
  visual: boolean;
114
118
  default: boolean;
115
119
  };
116
- align: {
117
- type: "string";
118
- visual: boolean;
119
- default: string;
120
- validate: (v: any) => boolean;
121
- coerce: (v: any) => "start" | "end" | "center";
122
- };
123
120
  placement: {
124
121
  type: "string";
125
122
  visual: boolean;
@@ -164,41 +161,18 @@ export declare class TySelect extends TyComponent<SelectState> {
164
161
  default: string;
165
162
  };
166
163
  };
167
- private _name;
168
- private _multiple;
169
- private _compact;
170
- private _placeholder;
171
- private _label;
172
- private _disabled;
173
- private _readonly;
174
- private _required;
175
- private _clearable;
176
- private _externalSearch;
177
- private _allowCreate;
178
- private _createTransform;
179
- private _notSearchable;
180
- private _loading;
181
- private _scrollLockId;
182
- private _size;
183
- private _availableLabel;
184
- private _selectedLabel;
185
- private _noOptionsMessage;
164
+ private readonly _uid;
186
165
  private _state;
187
- private _stubClickHandler;
188
- private _tagClickHandler;
189
- private _searchInputHandler;
190
- private _blockSearchClick;
166
+ private _scrollLockId;
191
167
  private _keyboardHandler;
192
- private _debounce;
193
168
  private _searchDebounceTimer;
194
169
  private _optionsScrollbar;
195
170
  private _childObserver;
196
- private _selectedClone;
197
171
  private _customFlavorSheet;
198
172
  private _ariaTrigger;
199
173
  private _ariaObserver;
200
174
  constructor();
201
- /** TyComponent handles property capture automatically. */
175
+ /** TyComponent renders right after this on the first connect. */
202
176
  protected onConnect(): void;
203
177
  /** Custom (non-built-in) flavors — see utils/flavor-sheet.ts. */
204
178
  private _syncCustomFlavor;
@@ -206,10 +180,9 @@ export declare class TySelect extends TyComponent<SelectState> {
206
180
  /** Handle state synchronization BEFORE render. */
207
181
  protected onPropertiesChanged(changes: PropertyChange[]): void;
208
182
  /**
209
- * Toggle the loading visual state on the open popup.
210
- * Replaces the available-options area with a centered spinner; search input stays usable.
211
- * Pulls the latest registered loader SVG on each call so registry changes
212
- * take effect on the next loading toggle.
183
+ * Toggle the loading visual state on the open popup: a centered spinner in
184
+ * place of the options; the search input stays usable. Reads the loader
185
+ * registry each time, so a newly registered loader shows next time.
213
186
  */
214
187
  private applyLoadingState;
215
188
  /** Form value: a plain entry for single, FormData with repeated entries for multiple (HTMX standard). */
@@ -221,34 +194,8 @@ export declare class TySelect extends TyComponent<SelectState> {
221
194
  */
222
195
  focus(options?: FocusOptions): void;
223
196
  private parseValue;
224
- /** Initialize component state from the value property / pre-selected children. */
225
- private initializeState;
226
- /**
227
- * Declarative init: no `value` attribute, but markup pre-marked one or more
228
- * options `selected` — native <select> semantics. This is the ONE place
229
- * selection is read FROM the DOM rather than treated as a rendering of
230
- * state (see getSelectedValues()): it seeds initial state, once. After
231
- * this, `value` rules — flipping an option's `selected` property later
232
- * does nothing, same as native.
233
- *
234
- * Called from initializeState() at connect AND from the child observer:
235
- * a real HTML parser upgrades a custom element the moment its start tag is
236
- * seen, BEFORE its children exist — `<ty-select>` connects with zero
237
- * `<ty-option>` children when it's part of the page's own markup (as
238
- * opposed to an already-built fragment attached via innerHTML/appendChild,
239
- * where children exist at connect). Calling this only at connect would
240
- * silently miss every option parsed after that instant, which is the
241
- * common case for markup that is literally in the page's initial HTML.
242
- *
243
- * Safe to call repeatedly: no-ops once `value` has ever been explicitly
244
- * set (attribute or property) or state is already non-empty — including
245
- * after a real `.clear()`, which removes `selected` from every option via
246
- * syncSelectedTags, so there is nothing left here to (re-)seed from.
247
- */
248
- private resolveDeclarativeSelection;
249
- /**
250
- * Get all option elements from the component (ty-option preferred, ty-tag accepted)
251
- */
197
+ /** The selection: the `value` property. external-selection holds none. */
198
+ private getSelectedValues;
252
199
  private getTagElements;
253
200
  /**
254
201
  * The options on offer: all but the ones the author hid (`hidden`, like a
@@ -257,59 +204,49 @@ export declare class TySelect extends TyComponent<SelectState> {
257
204
  */
258
205
  private getOfferedTags;
259
206
  private getTagData;
207
+ private findOption;
208
+ /** Draw each option's check from the selection (or, external, the app's marks). */
209
+ private paintOptions;
260
210
  /**
261
- * Select an option - attribute only. The option stays in the list with
262
- * selected styling; chips are rendered out-of-band (ty-selected-options).
263
- */
264
- private selectTag;
265
- /**
266
- * Deselect an option - attribute only.
211
+ * The option the trigger shows: single select, list closed, the picked
212
+ * option — if it is a direct child (only those can be slotted).
267
213
  */
268
- private deselectTag;
214
+ private shownOption;
269
215
  /**
270
- * Get the array of currently selected values.
271
- *
272
- * Reads STATE (`_state.selectedValues`), not the DOM: `value` is the
273
- * selection, and an option's `selected` attribute is a rendering of it
274
- * (written by syncSelectedTags below), never the other way round. This
275
- * matters whenever options don't fully reflect the selection — external
276
- * search legitimately has a selected value with no matching option
277
- * present; a DOM scan would report empty and desync .value, `required`
278
- * validation and the click-toggle logic from what's actually selected.
216
+ * Every child goes to the slot it asks for, the rest to the list — except
217
+ * the option the trigger shows. The real node: page CSS styles it, and the
218
+ * children a framework rendered stay exactly its own.
279
219
  */
280
- private getSelectedValues;
281
- private syncSelectedTags;
282
- /**
283
- * role="option" for every current option/tag — separate from
284
- * syncSelectedTags (which only runs when the `value` property changes)
285
- * so it also covers the "nothing selected yet, value never touched"
286
- * startup case. Idempotent; cheap to call from the child MutationObserver
287
- * on every light-DOM change.
288
- */
289
- private ensureOptionRoles;
290
- /** Central update function — synchronizes everything via TyComponent's property system. */
220
+ private assignSlots;
221
+ /** What the trigger shows, and where every child is slotted. */
222
+ private syncTrigger;
223
+ /** Set the selection; with `dispatchChange`, also fire `change` (a user action). */
291
224
  private updateComponentValue;
292
- /**
293
- * Build rich item info for values, read off the matching option elements
294
- */
225
+ /** Rich item info for values, read off the matching options. */
295
226
  private getSelectedItems;
296
227
  private calculatePosition;
297
228
  private _setupOptionsScrollbar;
298
229
  private _destroyOptionsScrollbar;
230
+ /** Open the popup (desktop dropdown or mobile full-screen dialog). */
231
+ private open;
232
+ private close;
299
233
  /**
300
- * Open dropdown dialog (desktop mode)
301
- *
302
- * `<dialog>.showModal()` puts the dialog in the top layer with a backdrop, but
303
- * does NOT prevent the page behind it from scrolling. We use the shared scroll
304
- * lock utility (overflow:hidden on <html>) to keep wheel/touch scrolling from
305
- * leaking through to the body — same behavior <ty-dropdown> and <ty-modal>
306
- * implement.
234
+ * `<dialog>.showModal()` puts the popup in the top layer but does NOT stop
235
+ * the page behind it from scrolling: the shared scroll lock does.
307
236
  */
237
+ private lockPageScroll;
238
+ private unlockPageScroll;
239
+ private setExpanded;
308
240
  private openDropdown;
309
241
  private closeDropdown;
310
- /** Open mobile modal — <dialog> handles z-index natively. */
311
242
  private openMobileModal;
312
243
  private closeMobileModal;
244
+ /**
245
+ * On close: empty the search box and show every option again. With
246
+ * external-search the app filters, so it gets an empty `search` instead
247
+ * (right away, not debounced: its list should be reset before a reopen).
248
+ */
249
+ private resetSearch;
313
250
  private handleStubClick;
314
251
  /**
315
252
  * .select-clear click — must stop propagation before it bubbles to the
@@ -317,22 +254,12 @@ export declare class TySelect extends TyComponent<SelectState> {
317
254
  */
318
255
  private handleClearClick;
319
256
  /**
320
- * Keyboard-open the (closed) stub. The stub is a plain div with
321
- * tabindex="0", not a native <button> — Enter/Space don't turn into
322
- * click events on their own the way they do for real form controls, and
323
- * without this a keyboard-only user could Tab to the field but never
324
- * open it. document-level handleKeyboard() only runs once already open
325
- * (it early-returns on !this._state.open), so this is the other half.
257
+ * Keyboard-open the closed stub: it is a div with tabindex="0", so
258
+ * Enter/Space don't click it. handleKeyboard takes over once open.
326
259
  */
327
260
  private handleStubKeydown;
328
261
  private handleTagClick;
329
- /**
330
- * Select/toggle a tag by element — the part of handleTagClick that has no
331
- * dependency on a real DOM event, so keyboard/programmatic callers (Enter
332
- * on a highlighted option, allow-create's exact-match dedup) can call it
333
- * directly instead of faking an Event object just to satisfy
334
- * preventDefault()/stopPropagation().
335
- */
262
+ /** Pick an option: click, Enter on a highlighted one, allow-create's exact match. */
336
263
  private selectByTag;
337
264
  /**
338
265
  * allow-create: Enter with unmatched search text mints a new option.
@@ -343,21 +270,18 @@ export declare class TySelect extends TyComponent<SelectState> {
343
270
  */
344
271
  private tryCreateFromSearch;
345
272
  /**
346
- * Multiple + allow-create: clear the search box and re-show the full
347
- * (now-longer) option list so the next tag can be typed immediately —
348
- * the tags-input pattern.
273
+ * Multiple + allow-create: clear the search box and show the full (now
274
+ * longer) list, so the next tag can be typed right away.
349
275
  */
350
276
  private clearSearchAfterCreate;
351
- private blockSearchClick;
277
+ private searchInput;
352
278
  private handleSearchInput;
353
279
  private handleKeyboard;
354
280
  /**
355
- * Next tag index in `direction` (-1/1) that isn't disabled, wrapping
356
- * around — mirrors handleTagClick's disabled check so keyboard nav can
357
- * never land on/select what a click already refuses to. Nor on one out of
358
- * sight: `tags` is the list as it was offered, and an option can get
359
- * `hidden` while it's open (a server patch). Returns -1 if every tag is
360
- * skipped (or there are none).
281
+ * Next tag index in `direction` (-1/1) that a click would accept, wrapping
282
+ * around: not disabled, and not out of sight (`tags` is the list as it was
283
+ * offered; an option can get `hidden` while open, by a server patch).
284
+ * -1 if there is none.
361
285
  */
362
286
  private nextEnabledTagIndex;
363
287
  private filterTags;
@@ -369,23 +293,29 @@ export declare class TySelect extends TyComponent<SelectState> {
369
293
  private updateOptionsVisibility;
370
294
  private clearHighlights;
371
295
  private highlightTag;
372
- /** Dispatch the search event for external search handling, with optional debounce. */
296
+ /** external-search: fire `search`, after `debounce` ms when set. */
373
297
  private dispatchSearchEvent;
374
298
  private fireSearchEvent;
375
299
  /**
376
- * Dispatch lifecycle events for popup open/close.
377
- * On open with external-search, also fire a `search` event with an empty
378
- * query so consumers have a clean hook to reset/refetch the option list.
300
+ * Popup lifecycle events. They do NOT bubble, like native <dialog>
301
+ * open/close: a bubbling `close` from a select in a ty-modal would close
302
+ * the modal. On open, external-search also gets an empty `search`, a hook
303
+ * to reset or refetch the list.
379
304
  */
380
305
  private fireOpenEvent;
381
306
  private fireCloseEvent;
382
307
  private dispatchChangeEvent;
308
+ /** One sync of everything the state shows; idempotent. */
383
309
  protected render(): void;
310
+ /**
311
+ * The options changed while the list is open (a morph, an external-search
312
+ * swap): filter the new ones by the query (a morph also strips the marks
313
+ * of the old filter), and let the keyboard walk them, not the old ones.
314
+ */
315
+ private refreshOpenList;
384
316
  /**
385
317
  * Patch label, required marker and disabled/compact state onto the
386
- * already-built shadow DOM. renderDesktop/renderMobile only write markup on
387
- * first render, so without this toggling `required`, `label`, `disabled` or
388
- * `compact` after connect never showed up.
318
+ * already-built shadow DOM (build() writes the markup once).
389
319
  */
390
320
  private syncFieldChrome;
391
321
  /**
@@ -398,24 +328,24 @@ export declare class TySelect extends TyComponent<SelectState> {
398
328
  */
399
329
  private syncTriggerAria;
400
330
  /**
401
- * Reflect constraint validation to the owning <form> via ElementInternals.
402
- * Without this `required` is only cosmetic — form.checkValidity() (and a
403
- * real submit) never actually blocks on an empty required select. Mirrors
404
- * ty-input's updateValidity(): empty + required => valueMissing, with a
405
- * native <select>'s message; disabled fields are barred from constraint
406
- * validation.
331
+ * Reflect constraint validation to the owning <form> via ElementInternals:
332
+ * empty + required => valueMissing, with a native <select>'s message.
333
+ * Disabled fields, and external-selection (the app holds the selection),
334
+ * are barred from it.
407
335
  */
408
336
  private updateValidity;
409
337
  /**
410
- * When a consumer slots their own trigger (slot="trigger"), strip the
411
- * default field chrome so the trigger is styled entirely by the consumer.
338
+ * A slotted trigger (slot="trigger") replaces the field chrome. has-trigger
339
+ * on the host sizes it to the trigger (Blink can't parse :has() inside
340
+ * :host()); render() puts it back if a morph strips it.
341
+ */
342
+ private syncTriggerSlot;
343
+ /**
344
+ * Build the shadow DOM once. Mobile (touch, narrow) gets a full-screen
345
+ * dialog with a selected strip; desktop an anchored dropdown. The mode is
346
+ * fixed here: everything wired below belongs to one of them.
412
347
  */
413
- private setupTriggerSlot;
414
- private setupEventListeners;
415
- private buildStubClasses;
416
- private renderDesktop;
417
- private renderMobile;
418
- private setupMobileEventListeners;
348
+ private build;
419
349
  /**
420
350
  * The dialog was closed by someone else — a ty-modal around this select
421
351
  * closes the dialogs still open inside it. Run our own close too, so the
@@ -426,28 +356,19 @@ export declare class TySelect extends TyComponent<SelectState> {
426
356
  * reopened since then is open again: both are no-ops.
427
357
  */
428
358
  private syncOnOutsideClose;
429
- private handleMobileStubClick;
430
- /** Keyboard-open the (closed) mobile stub — see handleStubKeydown for why this is needed. */
431
- private handleMobileStubKeydown;
432
- private handleMobileTagClick;
433
359
  private updateMobileSelectedState;
434
- /** "Label (n)" with the count in its own muted span — same shape for both
435
- sections, and re-reads the label so selected-label/available-label
436
- changes after first render show up. */
360
+ /** "Label (n)" with the count in its own muted span. */
437
361
  private setMobileSectionTitle;
438
362
  /**
439
- * Hand the dialog's spare vertical space to one section or the other. Only
440
- * one can own it: on a phone there isn't enough height for two scrollable
441
- * lists to both be usefully tall, so tapping a header trades the space
442
- * rather than splitting it. Selecting from the list hands it back to
443
- * "available" — you're still picking, so that's the list you want open.
363
+ * Hand the dialog's spare height to one section: a phone has no room for
364
+ * two usefully tall lists. Selecting from the list hands it back to
365
+ * "available".
444
366
  */
445
367
  private expandMobileSection;
446
368
  /**
447
369
  * The selected values as dismissible chips, pinned above the available
448
370
  * list so a long list can never scroll the current selection out of sight.
449
- * Rebuilt wholesale: the strip is small, and diffing it would have to
450
- * track chip identity for the sake of a handful of nodes.
371
+ * Rebuilt wholesale: the strip is small.
451
372
  */
452
373
  private renderMobileSelectedChips;
453
374
  /**
@@ -457,39 +378,25 @@ export declare class TySelect extends TyComponent<SelectState> {
457
378
  * more options than fit without scrolling.
458
379
  */
459
380
  private shouldShowSearch;
460
- /**
461
- * Toggle the search row (desktop header / mobile input) per shouldShowSearch.
462
- */
381
+ /** Toggle the search row (desktop header / mobile input) per shouldShowSearch. */
463
382
  private updateSearchVisibility;
464
383
  /**
465
- * Selection summary appropriate to cardinality × skin:
466
- * - single (field or compact): the selected OPTION itself — cloned into
467
- * slot="selected" so rich HTML options display intact (dropdown parity);
468
- * placeholder when empty
469
- * - multiple + field: joined labels (ellipsis via CSS), or placeholder
384
+ * The trigger, list closed:
385
+ * - single: the picked option itself (`shown`), else its label, else the placeholder
386
+ * - multiple + field: the labels, comma-joined (ellipsis via CSS)
470
387
  * - multiple + compact: placeholder + count badge
388
+ * Open, the list shows what is picked: the trigger shows the placeholder.
471
389
  */
472
390
  private updateSelectionDisplay;
473
391
  /**
474
- * Keep exactly one display clone (slot="selected", marked `cloned`) in our
475
- * light DOM matching the given value — or none. The clone never counts as
476
- * an option (getTagElements filters [cloned]) and ty-option's own
477
- * :host([cloned]) styling strips its list-row chrome.
478
- */
479
- private syncSelectedClone;
480
- /**
481
- * Deselect a value programmatically WITH a change event.
482
- * Used by out-of-band chip displays (ty-selected-options) so dismissing a chip
483
- * fires change like any in-popup interaction (HTMX hx-trigger="change" etc.).
392
+ * Deselect a value WITH a change event, like a pick in the popup (HTMX
393
+ * hx-trigger="change" etc.). Used by ty-selected-options chips.
484
394
  */
485
395
  deselectValue(value: string): void;
486
396
  /**
487
- * Clear the entire selection programmatically WITH a change event
488
- * (action: 'clear'). No-op if nothing is selected. Exists so slot="trigger"
489
- * consumers (custom chrome, built-in clear UI hidden by design) can wire
490
- * their own clear icon's click handler to it. Shows no validation
491
- * message (a code reset after a save shouldn't flag the field); the
492
- * built-in × does.
397
+ * Clear the selection WITH a change event (action: 'clear'), for a custom
398
+ * trigger's own clear control. Shows no validation message (a code reset
399
+ * after a save shouldn't flag the field); the built-in × does.
493
400
  */
494
401
  clear(): void;
495
402
  get value(): string;
@@ -520,12 +427,16 @@ export declare class TySelect extends TyComponent<SelectState> {
520
427
  set notSearchable(value: boolean);
521
428
  get externalSearch(): boolean;
522
429
  set externalSearch(value: boolean);
430
+ get externalSelection(): boolean;
431
+ set externalSelection(value: boolean);
432
+ get allowCreate(): boolean;
433
+ set allowCreate(value: boolean);
434
+ get createTransform(): "none" | "slug";
435
+ set createTransform(value: "none" | "slug");
523
436
  get debounce(): number;
524
437
  set debounce(value: number | string);
525
438
  get size(): Size;
526
439
  set size(value: Size);
527
- get align(): "start" | "center" | "end";
528
- set align(value: "start" | "center" | "end");
529
440
  get placement(): Placement | "";
530
441
  set placement(value: Placement | "");
531
442
  get flavor(): Flavor;