@peektravel/app-utilities 0.5.4 → 0.6.0

package/dist/ui/index.d.cts

@@ -71,6 +71,25 @@ declare abstract class OdyElement extends HTMLElement {
      * to call on every attribute change without losing the original children.
      */
     protected mount(chrome: string): void;
+    /**
+     * Move slotted content out of a portaled chrome node (dialog/panel/bubble)
+     * back into the captured slot fragment, so it survives `disconnectedCallback`
+     * tearing that node down and is re-slotted by the re-render on reconnect.
+     * Portal components call this before `removePortal(...)`; without it, moving
+     * the element in the DOM would permanently lose the consumer's content.
+     */
+    protected reclaimPortaledSlot(node: ParentNode | null | undefined): void;
+    appendChild<T extends Node>(node: T): T;
+    insertBefore<T extends Node>(node: T, child: Node | null): T;
+    removeChild<T extends Node>(child: T): T;
+    replaceChild<T extends Node>(node: Node, child: T): T;
+    /**
+     * Append an element the component owns (chrome / portaled nodes) as a direct
+     * host child, bypassing the slot-forwarding {@link appendChild} override.
+     * Portal-based components use this to re-home a portaled node before a
+     * re-render rebuilds the chrome.
+     */
+    protected adopt(node: Node): void;
     /** Read a string attribute with a fallback. */
     protected attr(name: string, fallback?: string): string;
     /** Whether a boolean attribute is present and not explicitly `"false"`. */
@@ -92,6 +111,13 @@ declare function escapeHtml(value: string): string;
 /**
  * Join class-name fragments, dropping falsy entries. Keeps component templates
  * readable when classes are conditional.
+ *
+ * The result is HTML-escaped because it is always interpolated into a
+ * `class="…"` attribute (or assigned to `el.className`). Many components build
+ * a class fragment from a raw, unvalidated attribute (`ody-tag--${attr('color')}`,
+ * `--size-${attr('size')}`, …); without escaping, a value containing a `"` would
+ * break out of the attribute and inject markup (DOM XSS). Legitimate class tokens
+ * contain none of the escaped characters, so this is a no-op for real class names.
  */
 declare function classes(...parts: Array<string | false | null | undefined>): string;
 /**
@@ -433,6 +459,8 @@ interface OdyToggleOption {
  * Attributes:
  * - `options` — JSON array of {@link OdyToggleOption} (e.g.
  *   `options='[{"value":"day","label":"Day"},{"value":"week","label":"Week"}]'`).
+ *   Also settable as a JS **property** (`el.options = [...]`) — accepts an array
+ *   or a JSON string, so a framework binding (`options={items}`) works directly.
  * - `selected` — the currently-selected option value.
  * - `size` — `base` | `small` (default `base`).
  * - `disabled` — disables the whole group.
@@ -440,6 +468,9 @@ interface OdyToggleOption {
 declare class OdyToggleButton extends OdyElement {
     #private;
     static observedAttributes: string[];
+    /** Options: the JS property wins, else the JSON `options` attribute. */
+    get options(): OdyToggleOption[];
+    set options(next: OdyToggleOption[] | string);
     connectedCallback(): void;
     disconnectedCallback(): void;
     protected render(): void;
@@ -760,6 +791,13 @@ declare class OdyMoneyInput extends OdyElement {
     set value(next: string);
     /** Decimal precision for the configured currency. */
     get precision(): number;
+    /**
+     * Reflect a `value` change into the live control in place instead of a full
+     * re-render, so a framework-controlled `value` binding never drops focus or
+     * caret while the user is typing. Other observed attributes change the chrome
+     * and still re-render via the base implementation.
+     */
+    attributeChangedCallback(name?: string, oldValue?: string | null, newValue?: string | null): void;
     protected render(): void;
 }
 
@@ -783,6 +821,13 @@ declare class OdyPercentageInput extends OdyElement {
     /** Current percentage value. */
     get value(): string;
     set value(next: string);
+    /**
+     * Reflect a `value` change into the live control in place instead of a full
+     * re-render, so a framework-controlled `value` binding never drops focus or
+     * caret while the user is typing. Other observed attributes change the chrome
+     * and still re-render via the base implementation.
+     */
+    attributeChangedCallback(name?: string, oldValue?: string | null, newValue?: string | null): void;
     protected render(): void;
 }
 
@@ -810,6 +855,12 @@ declare class OdyCheckbox extends OdyElement {
     /** Convenience alias for {@link checked}. */
     get value(): boolean;
     set value(next: boolean);
+    /**
+     * Reflect `checked` / `indeterminate` in place instead of a full re-render, so
+     * selecting the box (mouse or keyboard) never rebuilds the native `<input>`
+     * and drops focus. Other observed attributes still re-render via the base.
+     */
+    attributeChangedCallback(name?: string, oldValue?: string | null, newValue?: string | null): void;
     protected render(): void;
 }
 
@@ -838,8 +889,15 @@ declare class OdyRadioButtonGroup extends OdyElement {
     /** The selected option value. */
     get value(): string;
     set value(next: string);
-    /** Parsed `options`; malformed JSON yields an empty list. */
+    /** Options: the JS property wins, else the JSON `options` attribute. */
     get options(): OdyRadioOption[];
+    set options(next: OdyRadioOption[] | string);
+    /**
+     * Reflect a `value` change by re-checking the matching radio in place instead
+     * of rebuilding the fieldset — a full re-render would replace the focused
+     * radio and break keyboard (arrow-key) navigation between options.
+     */
+    attributeChangedCallback(name?: string, oldValue?: string | null, newValue?: string | null): void;
     protected render(): void;
 }
 
@@ -859,10 +917,12 @@ interface OdyCheckboxOption {
  *
  * Attributes:
  * - `options` — JSON array, e.g. `options='[{"label":"A","value":"a"}]'`. Also
- *   a settable JS property ({@link options}): `el.options = [...]` mirrors
- *   `<ody-dropdown-*>` and writes the JSON attribute.
- * - `value` — comma-separated selected values (also a JS array property,
- *   {@link value}).
+ *   a settable JS property ({@link options}): `el.options = [...]` (array or JSON
+ *   string) mirrors `<ody-dropdown-*>`; the property is the source of truth and
+ *   is not reflected back onto the attribute.
+ * - `value` — selected values (also a JS array property, {@link value}). The
+ *   reflected attribute is a JSON array (values with commas round-trip); a
+ *   legacy comma-separated attribute is still accepted when read.
  * - `select-all-label` — when present, renders the parent select-all row.
  * - `size` — `base` | `small` (default `small`).
  * - `disabled` — boolean flag applied to every checkbox.
@@ -872,18 +932,27 @@ interface OdyCheckboxOption {
 declare class OdyCheckboxGroup extends OdyElement {
     #private;
     static observedAttributes: string[];
-    /** The selected option values. */
+    /**
+     * The selected option values. The reflected `value` attribute is serialized
+     * as a JSON array so values containing commas round-trip; a legacy
+     * comma-separated attribute is still read for backwards compatibility.
+     */
     get value(): string[];
     set value(next: string[]);
-    /** Parsed `options`; malformed JSON yields an empty list. */
+    /** Options: the JS property wins, else the JSON `options` attribute. */
     get options(): OdyCheckboxOption[];
     /**
-     * Accepts an array of `{ label, value }` and stores it as the JSON `options`
-     * attribute. Mirrors `<ody-dropdown-*>` so `el.options = [...]` works across
-     * the data-driven elements. `options` is observed, so this triggers a
-     * re-render via `attributeChangedCallback`.
+     * Accepts an array of `{ label, value }` (or a JSON string) and stores it as
+     * the source of truth. Mirrors `<ody-dropdown-*>` so `el.options = [...]`
+     * works, without reflecting a large JSON blob onto the DOM attribute.
      */
-    set options(next: OdyCheckboxOption[]);
+    set options(next: OdyCheckboxOption[] | string);
+    /**
+     * Reflect a `value` change by updating each checkbox (and the select-all
+     * parent) in place, so toggling an option keeps focus instead of rebuilding
+     * the group. Other observed attributes still re-render via the base.
+     */
+    attributeChangedCallback(name?: string, oldValue?: string | null, newValue?: string | null): void;
     protected render(): void;
 }
 
@@ -967,6 +1036,7 @@ declare class OdyCopyButton extends OdyElement {
     #private;
     static observedAttributes: string[];
     protected render(): void;
+    disconnectedCallback(): void;
 }
 
 /**
@@ -1173,11 +1243,13 @@ interface OdyToastOptions {
  * {@link toast} lazily creates and portals one for you.
  */
 declare class OdyToastHost extends OdyElement {
+    #private;
     protected render(): void;
     /** Render and stack a toast, returning a handle to dismiss it early. */
     push(message: string, options?: OdyToastOptions): {
         dismiss: () => void;
     };
+    disconnectedCallback(): void;
 }
 /**
  * Show a toast notification, lazily creating an {@link OdyToastHost} portaled to
@@ -1241,6 +1313,7 @@ declare abstract class OdySelectBase extends OdyElement {
     protected abstract triggerContent(): string;
     /** ARIA `aria-multiselectable` value for the listbox (`'true'`/`'false'`). */
     protected abstract get multiselectable(): boolean;
+    connectedCallback(): void;
     protected render(): void;
     /** Open the panel and start listening for outside clicks. */
     protected openPanel(): void;
@@ -1353,7 +1426,8 @@ type OdyDateFormatter = (date: Date) => string;
  * - `range` — boolean; enables start/end range selection.
  * - `first-day-of-week` — `0`–`6` (0 = Sunday, default `0`).
  * - `placeholder` — trigger text shown when no value is selected.
- * - `presets` — JSON `[{ "label", "value" }]` shortcut buttons.
+ * - `presets` — JSON `[{ "label", "value" }]` shortcut buttons. Also settable
+ *   as a JS **property** (`el.presets = [...]`) — accepts an array or JSON string.
  * - `display-format` — how the selected date is shown to the user:
  *   `short` | `medium` (default) | `long` | `full`. The displayed text is
  *   localized via `Intl.DateTimeFormat` for the element's `lang`; the `value`
@@ -1371,10 +1445,15 @@ type OdyDateFormatter = (date: Date) => string;
 declare class OdyDatePicker extends OdyElement {
     #private;
     static observedAttributes: string[];
+    /** Preset list: the JS property wins, else the JSON `presets` attribute. */
+    get presets(): OdyDatePreset[];
+    set presets(next: OdyDatePreset[] | string);
     /** Disable arbitrary days; not an attribute (functions can't serialize). */
-    isDateDisallowed?: OdyDateDisallowed;
+    get isDateDisallowed(): OdyDateDisallowed | undefined;
+    set isDateDisallowed(fn: OdyDateDisallowed | undefined);
     /** Custom trigger-label formatter; wins over `display-format`/`Intl`. */
-    formatDate?: OdyDateFormatter;
+    get formatDate(): OdyDateFormatter | undefined;
+    set formatDate(fn: OdyDateFormatter | undefined);
     /** Whether the popover is currently shown. */
     get isOpen(): boolean;
     /** Show the popover and focus the roving day. */

package/dist/ui/index.d.ts

@@ -71,6 +71,25 @@ declare abstract class OdyElement extends HTMLElement {
      * to call on every attribute change without losing the original children.
      */
     protected mount(chrome: string): void;
+    /**
+     * Move slotted content out of a portaled chrome node (dialog/panel/bubble)
+     * back into the captured slot fragment, so it survives `disconnectedCallback`
+     * tearing that node down and is re-slotted by the re-render on reconnect.
+     * Portal components call this before `removePortal(...)`; without it, moving
+     * the element in the DOM would permanently lose the consumer's content.
+     */
+    protected reclaimPortaledSlot(node: ParentNode | null | undefined): void;
+    appendChild<T extends Node>(node: T): T;
+    insertBefore<T extends Node>(node: T, child: Node | null): T;
+    removeChild<T extends Node>(child: T): T;
+    replaceChild<T extends Node>(node: Node, child: T): T;
+    /**
+     * Append an element the component owns (chrome / portaled nodes) as a direct
+     * host child, bypassing the slot-forwarding {@link appendChild} override.
+     * Portal-based components use this to re-home a portaled node before a
+     * re-render rebuilds the chrome.
+     */
+    protected adopt(node: Node): void;
     /** Read a string attribute with a fallback. */
     protected attr(name: string, fallback?: string): string;
     /** Whether a boolean attribute is present and not explicitly `"false"`. */
@@ -92,6 +111,13 @@ declare function escapeHtml(value: string): string;
 /**
  * Join class-name fragments, dropping falsy entries. Keeps component templates
  * readable when classes are conditional.
+ *
+ * The result is HTML-escaped because it is always interpolated into a
+ * `class="…"` attribute (or assigned to `el.className`). Many components build
+ * a class fragment from a raw, unvalidated attribute (`ody-tag--${attr('color')}`,
+ * `--size-${attr('size')}`, …); without escaping, a value containing a `"` would
+ * break out of the attribute and inject markup (DOM XSS). Legitimate class tokens
+ * contain none of the escaped characters, so this is a no-op for real class names.
  */
 declare function classes(...parts: Array<string | false | null | undefined>): string;
 /**
@@ -433,6 +459,8 @@ interface OdyToggleOption {
  * Attributes:
  * - `options` — JSON array of {@link OdyToggleOption} (e.g.
  *   `options='[{"value":"day","label":"Day"},{"value":"week","label":"Week"}]'`).
+ *   Also settable as a JS **property** (`el.options = [...]`) — accepts an array
+ *   or a JSON string, so a framework binding (`options={items}`) works directly.
  * - `selected` — the currently-selected option value.
  * - `size` — `base` | `small` (default `base`).
  * - `disabled` — disables the whole group.
@@ -440,6 +468,9 @@ interface OdyToggleOption {
 declare class OdyToggleButton extends OdyElement {
     #private;
     static observedAttributes: string[];
+    /** Options: the JS property wins, else the JSON `options` attribute. */
+    get options(): OdyToggleOption[];
+    set options(next: OdyToggleOption[] | string);
     connectedCallback(): void;
     disconnectedCallback(): void;
     protected render(): void;
@@ -760,6 +791,13 @@ declare class OdyMoneyInput extends OdyElement {
     set value(next: string);
     /** Decimal precision for the configured currency. */
     get precision(): number;
+    /**
+     * Reflect a `value` change into the live control in place instead of a full
+     * re-render, so a framework-controlled `value` binding never drops focus or
+     * caret while the user is typing. Other observed attributes change the chrome
+     * and still re-render via the base implementation.
+     */
+    attributeChangedCallback(name?: string, oldValue?: string | null, newValue?: string | null): void;
     protected render(): void;
 }
 
@@ -783,6 +821,13 @@ declare class OdyPercentageInput extends OdyElement {
     /** Current percentage value. */
     get value(): string;
     set value(next: string);
+    /**
+     * Reflect a `value` change into the live control in place instead of a full
+     * re-render, so a framework-controlled `value` binding never drops focus or
+     * caret while the user is typing. Other observed attributes change the chrome
+     * and still re-render via the base implementation.
+     */
+    attributeChangedCallback(name?: string, oldValue?: string | null, newValue?: string | null): void;
     protected render(): void;
 }
 
@@ -810,6 +855,12 @@ declare class OdyCheckbox extends OdyElement {
     /** Convenience alias for {@link checked}. */
     get value(): boolean;
     set value(next: boolean);
+    /**
+     * Reflect `checked` / `indeterminate` in place instead of a full re-render, so
+     * selecting the box (mouse or keyboard) never rebuilds the native `<input>`
+     * and drops focus. Other observed attributes still re-render via the base.
+     */
+    attributeChangedCallback(name?: string, oldValue?: string | null, newValue?: string | null): void;
     protected render(): void;
 }
 
@@ -838,8 +889,15 @@ declare class OdyRadioButtonGroup extends OdyElement {
     /** The selected option value. */
     get value(): string;
     set value(next: string);
-    /** Parsed `options`; malformed JSON yields an empty list. */
+    /** Options: the JS property wins, else the JSON `options` attribute. */
     get options(): OdyRadioOption[];
+    set options(next: OdyRadioOption[] | string);
+    /**
+     * Reflect a `value` change by re-checking the matching radio in place instead
+     * of rebuilding the fieldset — a full re-render would replace the focused
+     * radio and break keyboard (arrow-key) navigation between options.
+     */
+    attributeChangedCallback(name?: string, oldValue?: string | null, newValue?: string | null): void;
     protected render(): void;
 }
 
@@ -859,10 +917,12 @@ interface OdyCheckboxOption {
  *
  * Attributes:
  * - `options` — JSON array, e.g. `options='[{"label":"A","value":"a"}]'`. Also
- *   a settable JS property ({@link options}): `el.options = [...]` mirrors
- *   `<ody-dropdown-*>` and writes the JSON attribute.
- * - `value` — comma-separated selected values (also a JS array property,
- *   {@link value}).
+ *   a settable JS property ({@link options}): `el.options = [...]` (array or JSON
+ *   string) mirrors `<ody-dropdown-*>`; the property is the source of truth and
+ *   is not reflected back onto the attribute.
+ * - `value` — selected values (also a JS array property, {@link value}). The
+ *   reflected attribute is a JSON array (values with commas round-trip); a
+ *   legacy comma-separated attribute is still accepted when read.
  * - `select-all-label` — when present, renders the parent select-all row.
  * - `size` — `base` | `small` (default `small`).
  * - `disabled` — boolean flag applied to every checkbox.
@@ -872,18 +932,27 @@ interface OdyCheckboxOption {
 declare class OdyCheckboxGroup extends OdyElement {
     #private;
     static observedAttributes: string[];
-    /** The selected option values. */
+    /**
+     * The selected option values. The reflected `value` attribute is serialized
+     * as a JSON array so values containing commas round-trip; a legacy
+     * comma-separated attribute is still read for backwards compatibility.
+     */
     get value(): string[];
     set value(next: string[]);
-    /** Parsed `options`; malformed JSON yields an empty list. */
+    /** Options: the JS property wins, else the JSON `options` attribute. */
     get options(): OdyCheckboxOption[];
     /**
-     * Accepts an array of `{ label, value }` and stores it as the JSON `options`
-     * attribute. Mirrors `<ody-dropdown-*>` so `el.options = [...]` works across
-     * the data-driven elements. `options` is observed, so this triggers a
-     * re-render via `attributeChangedCallback`.
+     * Accepts an array of `{ label, value }` (or a JSON string) and stores it as
+     * the source of truth. Mirrors `<ody-dropdown-*>` so `el.options = [...]`
+     * works, without reflecting a large JSON blob onto the DOM attribute.
      */
-    set options(next: OdyCheckboxOption[]);
+    set options(next: OdyCheckboxOption[] | string);
+    /**
+     * Reflect a `value` change by updating each checkbox (and the select-all
+     * parent) in place, so toggling an option keeps focus instead of rebuilding
+     * the group. Other observed attributes still re-render via the base.
+     */
+    attributeChangedCallback(name?: string, oldValue?: string | null, newValue?: string | null): void;
     protected render(): void;
 }
 
@@ -967,6 +1036,7 @@ declare class OdyCopyButton extends OdyElement {
     #private;
     static observedAttributes: string[];
     protected render(): void;
+    disconnectedCallback(): void;
 }
 
 /**
@@ -1173,11 +1243,13 @@ interface OdyToastOptions {
  * {@link toast} lazily creates and portals one for you.
  */
 declare class OdyToastHost extends OdyElement {
+    #private;
     protected render(): void;
     /** Render and stack a toast, returning a handle to dismiss it early. */
     push(message: string, options?: OdyToastOptions): {
         dismiss: () => void;
     };
+    disconnectedCallback(): void;
 }
 /**
  * Show a toast notification, lazily creating an {@link OdyToastHost} portaled to
@@ -1241,6 +1313,7 @@ declare abstract class OdySelectBase extends OdyElement {
     protected abstract triggerContent(): string;
     /** ARIA `aria-multiselectable` value for the listbox (`'true'`/`'false'`). */
     protected abstract get multiselectable(): boolean;
+    connectedCallback(): void;
     protected render(): void;
     /** Open the panel and start listening for outside clicks. */
     protected openPanel(): void;
@@ -1353,7 +1426,8 @@ type OdyDateFormatter = (date: Date) => string;
  * - `range` — boolean; enables start/end range selection.
  * - `first-day-of-week` — `0`–`6` (0 = Sunday, default `0`).
  * - `placeholder` — trigger text shown when no value is selected.
- * - `presets` — JSON `[{ "label", "value" }]` shortcut buttons.
+ * - `presets` — JSON `[{ "label", "value" }]` shortcut buttons. Also settable
+ *   as a JS **property** (`el.presets = [...]`) — accepts an array or JSON string.
  * - `display-format` — how the selected date is shown to the user:
  *   `short` | `medium` (default) | `long` | `full`. The displayed text is
  *   localized via `Intl.DateTimeFormat` for the element's `lang`; the `value`
@@ -1371,10 +1445,15 @@ type OdyDateFormatter = (date: Date) => string;
 declare class OdyDatePicker extends OdyElement {
     #private;
     static observedAttributes: string[];
+    /** Preset list: the JS property wins, else the JSON `presets` attribute. */
+    get presets(): OdyDatePreset[];
+    set presets(next: OdyDatePreset[] | string);
     /** Disable arbitrary days; not an attribute (functions can't serialize). */
-    isDateDisallowed?: OdyDateDisallowed;
+    get isDateDisallowed(): OdyDateDisallowed | undefined;
+    set isDateDisallowed(fn: OdyDateDisallowed | undefined);
     /** Custom trigger-label formatter; wins over `display-format`/`Intl`. */
-    formatDate?: OdyDateFormatter;
+    get formatDate(): OdyDateFormatter | undefined;
+    set formatDate(fn: OdyDateFormatter | undefined);
     /** Whether the popover is currently shown. */
     get isOpen(): boolean;
     /** Show the popover and focus the roving day. */