@aceshooting/lyra-ui 5.2.0 → 6.0.0

package/dist/components/forms/locale-picker/locale-picker.class.d.ts

@@ -0,0 +1,221 @@
+import { type TemplateResult, type PropertyValues } from 'lit';
+import { LyraElement } from '../../../internal/lyra-element.js';
+/** One offered locale row. `label` overrides the derived `localeNativeName(tag)` endonym when
+ *  given -- e.g. offering a locale before its strings are registered ("Français (bientôt)"). */
+export interface LyraLocaleEntry {
+    /** BCP-47 locale tag, e.g. `'pt-BR'`. */
+    tag: string;
+    /** Overrides `localeNativeName(tag)` when given. */
+    label?: string;
+}
+/** `locales` accepts either a plain array of BCP-47 tags (endonym label derived automatically)
+ *  or `{ tag, label }` rows for custom labels/ordering/subsets. */
+export type LyraLocaleCatalog = string[] | LyraLocaleEntry[];
+/** Visual size, same `2xs`–`xl` scale as `<lr-select>`'s `size`. */
+export type LyraLocalePickerSize = '2xs' | 'xs' | 's' | 'm' | 'l' | 'xl';
+export interface LyraLocalePickerEventMap {
+    'lr-change': CustomEvent<{
+        value: string;
+        previousValue: string;
+    }>;
+    blur: CustomEvent<undefined>;
+    focus: CustomEvent<undefined>;
+}
+/**
+ * `<lr-locale-picker>` — a closed-list locale switcher over the library's own locale registry.
+ *
+ * With `locales` left unset (the default), the offered rows are exactly
+ * `getRegisteredLyraLocales()` — every locale with strings registered via `registerLyraLocale()`,
+ * plus `'en'` (always available through the library's built-in English fallback) — kept live via
+ * `subscribeLyraLocaleRegistry()` so a locale registered after mount (e.g. a lazily-loaded
+ * translation pack) appears without a manual refresh. Passing an explicit `locales` array
+ * overrides the auto-discovered list entirely: a curated subset, a custom order, custom labels,
+ * or a locale the host wants to offer before its strings are registered.
+ *
+ * `value` is the *committed* selection (form-submitted, drives `lr-change`) and starts `''`.
+ * While unset, the trigger displays `effectiveLocale` (the same ancestor-`lang`/registry
+ * resolution every other component already uses) as a live preview — but that preview is never a
+ * commitment: `checkValidity()`/`required` are governed by the real `value`, which stays `''`
+ * until the host sets it or the user actually picks a row. This mirrors a native `<select>`
+ * rendering its first option's text without that being a committed selection.
+ *
+ * Built directly on the shared trigger-button/`aria-activedescendant` listbox technique
+ * `<lr-select>` uses (not composed from it) — a plain closed list, no filter/free-text mode; a
+ * locale catalog is realistically dozens of rows, not thousands, so `<lr-combobox>`'s filterable
+ * model would be more surface than the job needs.
+ *
+ * Selecting a row sets `value` and emits a cancelable `lr-change` — if a listener doesn't call
+ * `event.preventDefault()`, the component applies the pick itself via `setLyraLocale()`. A host
+ * that wants to intercept the pick (e.g. persist it to a profile first) calls
+ * `event.preventDefault()`; `value` still updates so the trigger reflects the pick, but the
+ * page-level locale is untouched until the host calls `setLyraLocale()` itself.
+ *
+ * Does not touch `document.documentElement.lang`/`dir` — applying a picked locale's writing
+ * direction to the page is left to the host, which already has everything it needs from
+ * `lr-change`'s `value` to do that itself.
+ *
+ * @customElement lr-locale-picker
+ * @event lr-change - The selection changed. `detail: { value, previousValue }`. Cancelable —
+ *   `event.preventDefault()` stops the automatic `setLyraLocale()` call without reverting `value`.
+ * @event blur - Re-dispatched from the internal trigger button as a bubbling, composed event.
+ * @event focus - Re-dispatched from the internal trigger button as a bubbling, composed event.
+ * @slot label - Custom label content.
+ * @slot hint - Custom hint content.
+ * @slot error - Custom error content.
+ * @csspart form-control - The outer wrapper around label, trigger, listbox, error and hint.
+ * @csspart form-control-label - The `<label>` element (only rendered — and only contributes to
+ *   the accessible name — once `label` is non-empty).
+ * @csspart trigger - The trigger button (positioning anchor).
+ * @csspart listbox - The options popover.
+ * @csspart option - An option row.
+ * @csspart option-flag - The row's leading `<lr-flag>` (present only while `showFlags` is on).
+ * @csspart option-label - An option row's label wrapper (native name + tag).
+ * @csspart option-tag - An option row's secondary line — the raw BCP-47 tag.
+ * @csspart expand-icon - The dropdown indicator.
+ * @csspart hint - The hint message.
+ * @csspart error - The error message.
+ * @cssprop --lr-locale-picker-trigger-padding - Trigger padding shorthand, scaled by `size`.
+ * @cssprop --lr-locale-picker-trigger-min-height - Trigger block-size floor, scaled by `size`.
+ * @cssprop --lr-locale-picker-trigger-height - Exact trigger height. Unset by default (a floor
+ *   only via `-trigger-min-height`); set a length to both floor and cap the trigger, e.g. to
+ *   pixel-match a sibling field in the same toolbar row.
+ * @cssprop --lr-locale-picker-font-size - Trigger font size, scaled by `size`.
+ * @cssprop --lr-locale-picker-expand-size - Decorative expand-icon box size, scaled by `size`.
+ * @cssprop [--lr-locale-picker-option-active-bg=var(--lr-color-brand-quiet)] - Background of a
+ *   hovered or keyboard-active option row.
+ */
+export declare class LyraLocalePicker extends LyraElement<LyraLocalePickerEventMap> {
+    static formAssociated: boolean;
+    static styles: import("lit").CSSResultGroup[];
+    static properties: {
+        disabled: {
+            type: BooleanConstructor;
+            reflect: boolean;
+            noAccessor: boolean;
+        };
+        required: {
+            type: BooleanConstructor;
+            reflect: boolean;
+            noAccessor: boolean;
+        };
+        value: {
+            noAccessor: boolean;
+        };
+        name: {
+            reflect: boolean;
+            noAccessor: boolean;
+        };
+    };
+    /** The offered locale list. Empty (the default) auto-discovers every locale registered via
+     *  `registerLyraLocale()` (plus `'en'`) through `getRegisteredLyraLocales()`, kept live via
+     *  `subscribeLyraLocaleRegistry()`. An explicit array overrides the auto-discovered list
+     *  entirely. */
+    locales: LyraLocaleCatalog;
+    /** Each row's leading `<lr-flag>`. The composition recipe this component supersedes
+     *  (`lr-popover` + `lr-flag`) already pairs a locale switcher with flags by convention --
+     *  defaulting to `true` keeps that continuity; set `false` for text-only rows. */
+    showFlags: boolean;
+    label: string;
+    hint: string;
+    errorText: string;
+    open: boolean;
+    /** Visual size — same `2xs`–`xl` scale as `lr-select`'s `size`. */
+    size: LyraLocalePickerSize;
+    private activeIndex;
+    private touched;
+    private hasHintSlot;
+    private hasErrorSlot;
+    private hasLabelSlot;
+    private registryTick;
+    private triggerElement?;
+    private internals;
+    private validityController;
+    private listId;
+    private controlId;
+    private cleanup?;
+    private stopRegistrySubscription?;
+    private _value;
+    private _fieldsetDisabled;
+    private _name;
+    private _disabled;
+    private _required;
+    private _defaultValue;
+    private typeAheadBuffer;
+    private typeAheadTimer?;
+    constructor();
+    /** Focus the internal trigger. */
+    focus(options?: FocusOptions): void;
+    /** Blur the internal trigger. */
+    blur(): void;
+    /** Activates the internal trigger -- `HTMLElement.prototype.click()` on a custom element with
+     *  no native click semantics is otherwise a silent no-op. Mirrors `<lr-select>`'s identical
+     *  `click()`. */
+    click(): void;
+    get form(): HTMLFormElement | null;
+    get labels(): NodeList;
+    get validity(): ValidityState;
+    get validationMessage(): string;
+    get willValidate(): boolean;
+    connectedCallback(): void;
+    disconnectedCallback(): void;
+    attributeChangedCallback(name: string, old: string | null, val: string | null): void;
+    protected willUpdate(): void;
+    /** The current locale tag (empty string when nothing is committed). */
+    get value(): string;
+    set value(next: string);
+    get name(): string;
+    set name(next: string);
+    get disabled(): boolean;
+    set disabled(next: boolean);
+    get required(): boolean;
+    set required(next: boolean);
+    /** Whether the control is disabled explicitly or by an ancestor fieldset. */
+    get effectiveDisabled(): boolean;
+    private updateValidity;
+    formResetCallback(): void;
+    formStateRestoreCallback(state: string | File | FormData | null, _mode?: 'restore' | 'autocomplete'): void;
+    formDisabledCallback(disabled: boolean): void;
+    checkValidity(): boolean;
+    reportValidity(): boolean;
+    /** `locales` normalized to `{ tag, label }[]`: an explicit non-empty catalog wins outright
+     *  (in either the `string[]` or `{tag,label}[]` form); otherwise every locale
+     *  `getRegisteredLyraLocales()` currently reports. */
+    private get normalizedEntries();
+    /** The tag actually shown in the trigger: the committed `value` once set, else a live preview
+     *  of `effectiveLocale` -- never a committed selection, see the class doc's value/preview
+     *  split. */
+    private get previewTag();
+    private labelFor;
+    private show;
+    private hide;
+    private onDocPointer;
+    protected updated(changed: PropertyValues): void;
+    /** Commits `tag`: sets `value`, closes the popup, then emits a cancelable `lr-change` --
+     *  applying `setLyraLocale(tag)` itself only when the listener doesn't veto it. Unconditional
+     *  on every explicit pick (no reselect-guard), mirroring `<lr-model-select>`'s identical
+     *  `commitValue()` -- the closest sibling precedent for this event shape. */
+    private commit;
+    private onTriggerClick;
+    private onTriggerBlur;
+    private onTriggerFocus;
+    private onLabelSlotChange;
+    private onHintSlotChange;
+    private onErrorSlotChange;
+    /** Standard listbox type-ahead: moves to the next row whose native name starts with the
+     *  accumulated buffer, cycling from just after the "current" row (the active row while open,
+     *  the preview tag while closed). While open this only moves `activeIndex` (a highlight,
+     *  matching Arrow-key nav); while closed it commits immediately, matching `<lr-select>`'s
+     *  identical closed-state type-ahead. */
+    private typeAhead;
+    private onKeyDown;
+    private onListboxMouseDown;
+    private onListboxClick;
+    private renderRows;
+    render(): TemplateResult;
+}
+declare global {
+    interface HTMLElementTagNameMap {
+        'lr-locale-picker': LyraLocalePicker;
+    }
+}
+//# sourceMappingURL=locale-picker.class.d.ts.map

package/dist/components/forms/locale-picker/locale-picker.class.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"locale-picker.class.d.ts","sourceRoot":"","sources":["../../../../src/components/forms/locale-picker/locale-picker.class.ts"],"names":[],"mappings":"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"}