tyrell-components 1.0.0-TC59 → 1.0.0-TC60

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: {
@@ -164,41 +168,18 @@ export declare class TySelect extends TyComponent<SelectState> {
164
168
  default: string;
165
169
  };
166
170
  };
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;
171
+ private readonly _uid;
186
172
  private _state;
187
- private _stubClickHandler;
188
- private _tagClickHandler;
189
- private _searchInputHandler;
190
- private _blockSearchClick;
173
+ private _scrollLockId;
191
174
  private _keyboardHandler;
192
- private _debounce;
193
175
  private _searchDebounceTimer;
194
176
  private _optionsScrollbar;
195
177
  private _childObserver;
196
- private _selectedClone;
197
178
  private _customFlavorSheet;
198
179
  private _ariaTrigger;
199
180
  private _ariaObserver;
200
181
  constructor();
201
- /** TyComponent handles property capture automatically. */
182
+ /** TyComponent renders right after this on the first connect. */
202
183
  protected onConnect(): void;
203
184
  /** Custom (non-built-in) flavors — see utils/flavor-sheet.ts. */
204
185
  private _syncCustomFlavor;
@@ -206,10 +187,9 @@ export declare class TySelect extends TyComponent<SelectState> {
206
187
  /** Handle state synchronization BEFORE render. */
207
188
  protected onPropertiesChanged(changes: PropertyChange[]): void;
208
189
  /**
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.
190
+ * Toggle the loading visual state on the open popup: a centered spinner in
191
+ * place of the options; the search input stays usable. Reads the loader
192
+ * registry each time, so a newly registered loader shows next time.
213
193
  */
214
194
  private applyLoadingState;
215
195
  /** Form value: a plain entry for single, FormData with repeated entries for multiple (HTMX standard). */
@@ -221,34 +201,8 @@ export declare class TySelect extends TyComponent<SelectState> {
221
201
  */
222
202
  focus(options?: FocusOptions): void;
223
203
  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
- */
204
+ /** The selection: the `value` property. external-selection holds none. */
205
+ private getSelectedValues;
252
206
  private getTagElements;
253
207
  /**
254
208
  * The options on offer: all but the ones the author hid (`hidden`, like a
@@ -257,59 +211,49 @@ export declare class TySelect extends TyComponent<SelectState> {
257
211
  */
258
212
  private getOfferedTags;
259
213
  private getTagData;
214
+ private findOption;
215
+ /** Draw each option's check from the selection (or, external, the app's marks). */
216
+ private paintOptions;
260
217
  /**
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.
267
- */
268
- private deselectTag;
269
- /**
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.
218
+ * The option the trigger shows: single select, list closed, the picked
219
+ * option — if it is a direct child (only those can be slotted).
279
220
  */
280
- private getSelectedValues;
281
- private syncSelectedTags;
221
+ private shownOption;
282
222
  /**
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.
223
+ * Every child goes to the slot it asks for, the rest to the list — except
224
+ * the option the trigger shows. The real node: page CSS styles it, and the
225
+ * children a framework rendered stay exactly its own.
288
226
  */
289
- private ensureOptionRoles;
290
- /** Central update function — synchronizes everything via TyComponent's property system. */
227
+ private assignSlots;
228
+ /** What the trigger shows, and where every child is slotted. */
229
+ private syncTrigger;
230
+ /** Set the selection; with `dispatchChange`, also fire `change` (a user action). */
291
231
  private updateComponentValue;
292
- /**
293
- * Build rich item info for values, read off the matching option elements
294
- */
232
+ /** Rich item info for values, read off the matching options. */
295
233
  private getSelectedItems;
296
234
  private calculatePosition;
297
235
  private _setupOptionsScrollbar;
298
236
  private _destroyOptionsScrollbar;
237
+ /** Open the popup (desktop dropdown or mobile full-screen dialog). */
238
+ private open;
239
+ private close;
299
240
  /**
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.
241
+ * `<dialog>.showModal()` puts the popup in the top layer but does NOT stop
242
+ * the page behind it from scrolling: the shared scroll lock does.
307
243
  */
244
+ private lockPageScroll;
245
+ private unlockPageScroll;
246
+ private setExpanded;
308
247
  private openDropdown;
309
248
  private closeDropdown;
310
- /** Open mobile modal — <dialog> handles z-index natively. */
311
249
  private openMobileModal;
312
250
  private closeMobileModal;
251
+ /**
252
+ * On close: empty the search box and show every option again. With
253
+ * external-search the app filters, so it gets an empty `search` instead
254
+ * (right away, not debounced: its list should be reset before a reopen).
255
+ */
256
+ private resetSearch;
313
257
  private handleStubClick;
314
258
  /**
315
259
  * .select-clear click — must stop propagation before it bubbles to the
@@ -317,22 +261,12 @@ export declare class TySelect extends TyComponent<SelectState> {
317
261
  */
318
262
  private handleClearClick;
319
263
  /**
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.
264
+ * Keyboard-open the closed stub: it is a div with tabindex="0", so
265
+ * Enter/Space don't click it. handleKeyboard takes over once open.
326
266
  */
327
267
  private handleStubKeydown;
328
268
  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
- */
269
+ /** Pick an option: click, Enter on a highlighted one, allow-create's exact match. */
336
270
  private selectByTag;
337
271
  /**
338
272
  * allow-create: Enter with unmatched search text mints a new option.
@@ -343,21 +277,18 @@ export declare class TySelect extends TyComponent<SelectState> {
343
277
  */
344
278
  private tryCreateFromSearch;
345
279
  /**
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.
280
+ * Multiple + allow-create: clear the search box and show the full (now
281
+ * longer) list, so the next tag can be typed right away.
349
282
  */
350
283
  private clearSearchAfterCreate;
351
- private blockSearchClick;
284
+ private searchInput;
352
285
  private handleSearchInput;
353
286
  private handleKeyboard;
354
287
  /**
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).
288
+ * Next tag index in `direction` (-1/1) that a click would accept, wrapping
289
+ * around: not disabled, and not out of sight (`tags` is the list as it was
290
+ * offered; an option can get `hidden` while open, by a server patch).
291
+ * -1 if there is none.
361
292
  */
362
293
  private nextEnabledTagIndex;
363
294
  private filterTags;
@@ -369,23 +300,29 @@ export declare class TySelect extends TyComponent<SelectState> {
369
300
  private updateOptionsVisibility;
370
301
  private clearHighlights;
371
302
  private highlightTag;
372
- /** Dispatch the search event for external search handling, with optional debounce. */
303
+ /** external-search: fire `search`, after `debounce` ms when set. */
373
304
  private dispatchSearchEvent;
374
305
  private fireSearchEvent;
375
306
  /**
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.
307
+ * Popup lifecycle events. They do NOT bubble, like native <dialog>
308
+ * open/close: a bubbling `close` from a select in a ty-modal would close
309
+ * the modal. On open, external-search also gets an empty `search`, a hook
310
+ * to reset or refetch the list.
379
311
  */
380
312
  private fireOpenEvent;
381
313
  private fireCloseEvent;
382
314
  private dispatchChangeEvent;
315
+ /** One sync of everything the state shows; idempotent. */
383
316
  protected render(): void;
317
+ /**
318
+ * The options changed while the list is open (a morph, an external-search
319
+ * swap): filter the new ones by the query (a morph also strips the marks
320
+ * of the old filter), and let the keyboard walk them, not the old ones.
321
+ */
322
+ private refreshOpenList;
384
323
  /**
385
324
  * 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.
325
+ * already-built shadow DOM (build() writes the markup once).
389
326
  */
390
327
  private syncFieldChrome;
391
328
  /**
@@ -398,24 +335,24 @@ export declare class TySelect extends TyComponent<SelectState> {
398
335
  */
399
336
  private syncTriggerAria;
400
337
  /**
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.
338
+ * Reflect constraint validation to the owning <form> via ElementInternals:
339
+ * empty + required => valueMissing, with a native <select>'s message.
340
+ * Disabled fields, and external-selection (the app holds the selection),
341
+ * are barred from it.
407
342
  */
408
343
  private updateValidity;
409
344
  /**
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.
345
+ * A slotted trigger (slot="trigger") replaces the field chrome. has-trigger
346
+ * on the host sizes it to the trigger (Blink can't parse :has() inside
347
+ * :host()); render() puts it back if a morph strips it.
348
+ */
349
+ private syncTriggerSlot;
350
+ /**
351
+ * Build the shadow DOM once. Mobile (touch, narrow) gets a full-screen
352
+ * dialog with a selected strip; desktop an anchored dropdown. The mode is
353
+ * fixed here: everything wired below belongs to one of them.
412
354
  */
413
- private setupTriggerSlot;
414
- private setupEventListeners;
415
- private buildStubClasses;
416
- private renderDesktop;
417
- private renderMobile;
418
- private setupMobileEventListeners;
355
+ private build;
419
356
  /**
420
357
  * The dialog was closed by someone else — a ty-modal around this select
421
358
  * closes the dialogs still open inside it. Run our own close too, so the
@@ -426,28 +363,19 @@ export declare class TySelect extends TyComponent<SelectState> {
426
363
  * reopened since then is open again: both are no-ops.
427
364
  */
428
365
  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
366
  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. */
367
+ /** "Label (n)" with the count in its own muted span. */
437
368
  private setMobileSectionTitle;
438
369
  /**
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.
370
+ * Hand the dialog's spare height to one section: a phone has no room for
371
+ * two usefully tall lists. Selecting from the list hands it back to
372
+ * "available".
444
373
  */
445
374
  private expandMobileSection;
446
375
  /**
447
376
  * The selected values as dismissible chips, pinned above the available
448
377
  * 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.
378
+ * Rebuilt wholesale: the strip is small.
451
379
  */
452
380
  private renderMobileSelectedChips;
453
381
  /**
@@ -457,39 +385,25 @@ export declare class TySelect extends TyComponent<SelectState> {
457
385
  * more options than fit without scrolling.
458
386
  */
459
387
  private shouldShowSearch;
460
- /**
461
- * Toggle the search row (desktop header / mobile input) per shouldShowSearch.
462
- */
388
+ /** Toggle the search row (desktop header / mobile input) per shouldShowSearch. */
463
389
  private updateSearchVisibility;
464
390
  /**
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
391
+ * The trigger, list closed:
392
+ * - single: the picked option itself (`shown`), else its label, else the placeholder
393
+ * - multiple + field: the labels, comma-joined (ellipsis via CSS)
470
394
  * - multiple + compact: placeholder + count badge
395
+ * Open, the list shows what is picked: the trigger shows the placeholder.
471
396
  */
472
397
  private updateSelectionDisplay;
473
398
  /**
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.).
399
+ * Deselect a value WITH a change event, like a pick in the popup (HTMX
400
+ * hx-trigger="change" etc.). Used by ty-selected-options chips.
484
401
  */
485
402
  deselectValue(value: string): void;
486
403
  /**
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.
404
+ * Clear the selection WITH a change event (action: 'clear'), for a custom
405
+ * trigger's own clear control. Shows no validation message (a code reset
406
+ * after a save shouldn't flag the field); the built-in × does.
493
407
  */
494
408
  clear(): void;
495
409
  get value(): string;
@@ -520,6 +434,12 @@ export declare class TySelect extends TyComponent<SelectState> {
520
434
  set notSearchable(value: boolean);
521
435
  get externalSearch(): boolean;
522
436
  set externalSearch(value: boolean);
437
+ get externalSelection(): boolean;
438
+ set externalSelection(value: boolean);
439
+ get allowCreate(): boolean;
440
+ set allowCreate(value: boolean);
441
+ get createTransform(): "none" | "slug";
442
+ set createTransform(value: "none" | "slug");
523
443
  get debounce(): number;
524
444
  set debounce(value: number | string);
525
445
  get size(): Size;