voyager-ionic-core 8.0.1 → 8.1.0

package/dist/types/components/modal/modal-interface.d.ts

@@ -9,6 +9,7 @@ export interface ModalOptions<T extends ComponentRef = ComponentRef> {
     delegate?: FrameworkDelegate;
     animated?: boolean;
     canDismiss?: boolean | ((data?: any, role?: string) => Promise<boolean>);
+    focusTrap?: boolean;
     mode?: Mode;
     keyboardClose?: boolean;
     id?: string;

package/dist/types/components/modal/modal.d.ts

@@ -163,6 +163,24 @@ export declare class Modal implements ComponentInterface, OverlayInterface {
      * frameworks such as Angular, React, and Vue.
      */
     keepContentsMounted: boolean;
+    /**
+     * If `true`, focus will not be allowed to move outside of this overlay.
+     * If `false`, focus will be allowed to move outside of the overlay.
+     *
+     * In most scenarios this property should remain set to `true`. Setting
+     * this property to `false` can cause severe accessibility issues as users
+     * relying on assistive technologies may be able to move focus into
+     * a confusing state. We recommend only setting this to `false` when
+     * absolutely necessary.
+     *
+     * Developers may want to consider disabling focus trapping if this
+     * overlay presents a non-Ionic overlay from a 3rd party library.
+     * Developers would disable focus trapping on the Ionic overlay
+     * when presenting the 3rd party overlay and then re-enable
+     * focus trapping when dismissing the 3rd party overlay and moving
+     * focus back to the Ionic overlay.
+     */
+    focusTrap: boolean;
     /**
      * Determines whether or not a modal can dismiss
      * when calling the `dismiss` method.

package/dist/types/components/picker-column/picker-column.d.ts

@@ -15,6 +15,10 @@ export declare class PickerColumn implements ComponentInterface {
     private isColumnVisible;
     private parentEl?;
     private canExitInputMode;
+    private assistiveFocusable?;
+    private updateValueTextOnScroll;
+    ariaLabel: string | null;
+    ariaLabelChanged(newValue: string): void;
     isActive: boolean;
     el: HTMLIonPickerColumnElement;
     /**
@@ -43,6 +47,8 @@ export declare class PickerColumn implements ComponentInterface {
     numericInput: boolean;
     /**
      * Emitted when the value has changed.
+     *
+     * This event will not emit when programmatically setting the `value` property.
      */
     ionChange: EventEmitter<PickerColumnChangeEventDetail>;
     valueChange(): void;
@@ -69,6 +75,7 @@ export declare class PickerColumn implements ComponentInterface {
      * Use this method instead of the global `pickerColumn.focus()`.
      */
     setFocus(): Promise<void>;
+    connectedCallback(): void;
     private centerPickerItemInView;
     private setPickerItemActiveState;
     /**
@@ -102,5 +109,35 @@ export declare class PickerColumn implements ComponentInterface {
      */
     private exitInputMode;
     get activeItem(): HTMLIonPickerColumnOptionElement | undefined;
+    /**
+     * Find the next enabled option after the active option.
+     * @param stride - How many options to "jump" over in order to select the next option.
+     * This can be used to implement PageUp/PageDown behaviors where pressing these keys
+     * scrolls the picker by more than 1 option. For example, a stride of 5 means select
+     * the enabled option 5 options after the active one. Note that the actual option selected
+     * may be past the stride if the option at the stride is disabled.
+     */
+    private findNextOption;
+    /**
+     * Find the next enabled option after the active option.
+     * @param stride - How many options to "jump" over in order to select the next option.
+     * This can be used to implement PageUp/PageDown behaviors where pressing these keys
+     * scrolls the picker by more than 1 option. For example, a stride of 5 means select
+     * the enabled option 5 options before the active one. Note that the actual option selected
+     *  may be past the stride if the option at the stride is disabled.
+     */
+    private findPreviousOption;
+    private onKeyDown;
+    /**
+     * Utility to generate the correct text for aria-valuetext.
+     */
+    private getOptionValueText;
+    /**
+     * Render an element that overlays the column. This element is for assistive
+     * tech to allow users to navigate the column up/down. This element should receive
+     * focus as it listens for synthesized keyboard events as required by the
+     * slider role: https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Roles/slider_role
+     */
+    private renderAssistiveFocusable;
     render(): any;
 }

package/dist/types/components/popover/popover-interface.d.ts

@@ -12,6 +12,7 @@ export interface PopoverOptions<T extends ComponentRef = ComponentRef> {
     event?: Event;
     delegate?: FrameworkDelegate;
     animated?: boolean;
+    focusTrap?: boolean;
     mode?: Mode;
     keyboardClose?: boolean;
     id?: string;

package/dist/types/components/popover/popover.d.ts

@@ -171,6 +171,24 @@ export declare class Popover implements ComponentInterface, PopoverInterface {
      * behavior in a popover using a list of items.
      */
     keyboardEvents: boolean;
+    /**
+     * If `true`, focus will not be allowed to move outside of this overlay.
+     * If `false`, focus will be allowed to move outside of the overlay.
+     *
+     * In most scenarios this property should remain set to `true`. Setting
+     * this property to `false` can cause severe accessibility issues as users
+     * relying on assistive technologies may be able to move focus into
+     * a confusing state. We recommend only setting this to `false` when
+     * absolutely necessary.
+     *
+     * Developers may want to consider disabling focus trapping if this
+     * overlay presents a non-Ionic overlay from a 3rd party library.
+     * Developers would disable focus trapping on the Ionic overlay
+     * when presenting the 3rd party overlay and then re-enable
+     * focus trapping when dismissing the 3rd party overlay and moving
+     * focus back to the Ionic overlay.
+     */
+    focusTrap: boolean;
     onTriggerChange(): void;
     onIsOpenChange(newValue: boolean, oldValue: boolean): void;
     /**

package/dist/types/components/radio-group/radio-group.d.ts

@@ -27,6 +27,8 @@ export declare class RadioGroup implements ComponentInterface {
     valueChanged(value: any | undefined): void;
     /**
      * Emitted when the value has changed.
+     *
+     * This event will not emit when programmatically setting the `value` property.
      */
     ionChange: EventEmitter<RadioGroupChangeEventDetail>;
     /**

package/dist/types/components/range/range.d.ts

@@ -127,7 +127,7 @@ export declare class Range implements ComponentInterface {
      * - When the user releases the knob after dragging;
      * - When the user moves the knob with keyboard arrows
      *
-     * `ionChange` is not fired when the value is changed programmatically.
+     * This event will not emit when programmatically setting the `value` property.
      */
     ionChange: EventEmitter<RangeChangeEventDetail>;
     /**

package/dist/types/components/searchbar/searchbar.d.ts

@@ -153,6 +153,8 @@ export declare class Searchbar implements ComponentInterface {
      * by the user. This can happen when the element loses focus or
      * when the "Enter" key is pressed. `ionChange` can also fire
      * when clicking the clear or cancel buttons.
+     *
+     * This event will not emit when programmatically setting the `value` property.
      */
     ionChange: EventEmitter<SearchbarChangeEventDetail>;
     /**

package/dist/types/components/segment/segment.d.ts

@@ -43,8 +43,9 @@ export declare class Segment implements ComponentInterface {
      */
     selectOnFocus: boolean;
     /**
-     * Emitted when the value property has changed and any
-     * dragging pointer has been released from `ion-segment`.
+     * Emitted when the value property has changed and any dragging pointer has been released from `ion-segment`.
+     *
+     * This event will not emit when programmatically setting the `value` property.
      */
     ionChange: EventEmitter<SegmentChangeEventDetail>;
     /**

package/dist/types/components/select/select.d.ts

@@ -139,6 +139,8 @@ export declare class Select implements ComponentInterface {
     value?: any | null;
     /**
      * Emitted when the value has changed.
+     *
+     * This event will not emit when programmatically setting the `value` property.
      */
     ionChange: EventEmitter<SelectChangeEventDetail>;
     /**

package/dist/types/components/textarea/textarea.d.ts

@@ -176,6 +176,8 @@ export declare class Textarea implements ComponentInterface {
      * The `ionChange` event is fired when the user modifies the textarea's value.
      * Unlike the `ionInput` event, the `ionChange` event is fired when
      * the element loses focus after its value has been modified.
+     *
+     * This event will not emit when programmatically setting the `value` property.
      */
     ionChange: EventEmitter<TextareaChangeEventDetail>;
     /**

package/dist/types/components/toggle/toggle.d.ts

@@ -75,8 +75,9 @@ export declare class Toggle implements ComponentInterface {
      */
     alignment: 'start' | 'center';
     /**
-     * Emitted when the user switches the toggle on or off. Does not emit
-     * when programmatically changing the value of the `checked` property.
+     * Emitted when the user switches the toggle on or off.
+     *
+     * This event will not emit when programmatically setting the `checked` property.
      */
     ionChange: EventEmitter<ToggleChangeEventDetail>;
     /**

package/dist/types/components.d.ts

@@ -762,6 +762,10 @@ export namespace Components {
           * The color to use from your application's color palette. Default options are: `"primary"`, `"secondary"`, `"tertiary"`, `"success"`, `"warning"`, `"danger"`, `"light"`, `"medium"`, and `"dark"`. For more information on colors, see [theming](/docs/theming/basics).
          */
         "color"?: Color;
+        /**
+          * Controls where the fixed content is placed relative to the main content in the DOM. This can be used to control the order in which fixed elements receive keyboard focus. For example, if a FAB in the fixed slot should receive keyboard focus before the main page content, set this property to `'before'`.
+         */
+        "fixedSlotPlacement": 'after' | 'before';
         /**
           * If `true` and the content does not cause an overflow scroll, the scroll interaction will cause a bounce. If the content exceeds the bounds of ionContent, nothing will change. Note, this does not disable the system bounce on iOS. That is an OS level setting.
          */
@@ -1162,6 +1166,10 @@ export namespace Components {
           * If `true`, a clear icon will appear in the input when there is a value. Clicking it clears the input.
          */
         "clearInput": boolean;
+        /**
+          * The icon to use for the clear button. Only applies when `clearInput` is set to `true`.
+         */
+        "clearInputIcon"?: string;
         /**
           * If `true`, the value will be cleared after focus upon edit. Defaults to `true` when `type` is `"password"`, `false` for all other types.
          */
@@ -1715,6 +1723,10 @@ export namespace Components {
           * Animation to use when the modal is presented.
          */
         "enterAnimation"?: AnimationBuilder;
+        /**
+          * If `true`, focus will not be allowed to move outside of this overlay. If `false`, focus will be allowed to move outside of the overlay.  In most scenarios this property should remain set to `true`. Setting this property to `false` can cause severe accessibility issues as users relying on assistive technologies may be able to move focus into a confusing state. We recommend only setting this to `false` when absolutely necessary.  Developers may want to consider disabling focus trapping if this overlay presents a non-Ionic overlay from a 3rd party library. Developers would disable focus trapping on the Ionic overlay when presenting the 3rd party overlay and then re-enable focus trapping when dismissing the 3rd party overlay and moving focus back to the Ionic overlay.
+         */
+        "focusTrap": boolean;
         /**
           * Returns the current breakpoint of a sheet style modal
          */
@@ -2131,6 +2143,10 @@ export namespace Components {
           * The event to pass to the popover animation.
          */
         "event": any;
+        /**
+          * If `true`, focus will not be allowed to move outside of this overlay. If `false`, focus will be allowed to move outside of the overlay.  In most scenarios this property should remain set to `true`. Setting this property to `false` can cause severe accessibility issues as users relying on assistive technologies may be able to move focus into a confusing state. We recommend only setting this to `false` when absolutely necessary.  Developers may want to consider disabling focus trapping if this overlay presents a non-Ionic overlay from a 3rd party library. Developers would disable focus trapping on the Ionic overlay when presenting the 3rd party overlay and then re-enable focus trapping when dismissing the 3rd party overlay and moving focus back to the Ionic overlay.
+         */
+        "focusTrap": boolean;
         "getParentPopover": () => Promise<HTMLIonPopoverElement | null>;
         "hasController": boolean;
         /**
@@ -4770,7 +4786,7 @@ declare namespace LocalJSX {
          */
         "multiple"?: boolean;
         /**
-          * Emitted when the value property has changed as a result of a user action such as a click. This event will not emit when programmatically setting the value property.
+          * Emitted when the value property has changed as a result of a user action such as a click.  This event will not emit when programmatically setting the `value` property.
          */
         "onIonChange"?: (event: IonAccordionGroupCustomEvent<AccordionGroupChangeEventDetail>) => void;
         /**
@@ -5328,7 +5344,7 @@ declare namespace LocalJSX {
          */
         "onIonBlur"?: (event: IonCheckboxCustomEvent<void>) => void;
         /**
-          * Emitted when the checked property has changed as a result of a user action such as a click. This event will not emit when programmatically setting the checked property.
+          * Emitted when the checked property has changed as a result of a user action such as a click.  This event will not emit when programmatically setting the `checked` property.
          */
         "onIonChange"?: (event: IonCheckboxCustomEvent<CheckboxChangeEventDetail>) => void;
         /**
@@ -5461,6 +5477,10 @@ declare namespace LocalJSX {
           * The color to use from your application's color palette. Default options are: `"primary"`, `"secondary"`, `"tertiary"`, `"success"`, `"warning"`, `"danger"`, `"light"`, `"medium"`, and `"dark"`. For more information on colors, see [theming](/docs/theming/basics).
          */
         "color"?: Color;
+        /**
+          * Controls where the fixed content is placed relative to the main content in the DOM. This can be used to control the order in which fixed elements receive keyboard focus. For example, if a FAB in the fixed slot should receive keyboard focus before the main page content, set this property to `'before'`.
+         */
+        "fixedSlotPlacement"?: 'after' | 'before';
         /**
           * If `true` and the content does not cause an overflow scroll, the scroll interaction will cause a bounce. If the content exceeds the bounds of ionContent, nothing will change. Note, this does not disable the system bounce on iOS. That is an OS level setting.
          */
@@ -5584,7 +5604,7 @@ declare namespace LocalJSX {
          */
         "onIonCancel"?: (event: IonDatetimeCustomEvent<void>) => void;
         /**
-          * Emitted when the value (selected date) has changed.
+          * Emitted when the value (selected date) has changed.  This event will not emit when programmatically setting the `value` property.
          */
         "onIonChange"?: (event: IonDatetimeCustomEvent<DatetimeChangeEventDetail>) => void;
         /**
@@ -5857,6 +5877,10 @@ declare namespace LocalJSX {
           * If `true`, a clear icon will appear in the input when there is a value. Clicking it clears the input.
          */
         "clearInput"?: boolean;
+        /**
+          * The icon to use for the clear button. Only applies when `clearInput` is set to `true`.
+         */
+        "clearInputIcon"?: string;
         /**
           * If `true`, the value will be cleared after focus upon edit. Defaults to `true` when `type` is `"password"`, `false` for all other types.
          */
@@ -5942,7 +5966,7 @@ declare namespace LocalJSX {
          */
         "onIonBlur"?: (event: IonInputCustomEvent<FocusEvent>) => void;
         /**
-          * The `ionChange` event is fired when the user modifies the input's value. Unlike the `ionInput` event, the `ionChange` event is only fired when changes are committed, not as the user types.  Depending on the way the users interacts with the element, the `ionChange` event fires at a different moment: - When the user commits the change explicitly (e.g. by selecting a date from a date picker for `<ion-input type="date">`, pressing the "Enter" key, etc.). - When the element loses focus after its value has changed: for elements where the user's interaction is typing.
+          * The `ionChange` event is fired when the user modifies the input's value. Unlike the `ionInput` event, the `ionChange` event is only fired when changes are committed, not as the user types.  Depending on the way the users interacts with the element, the `ionChange` event fires at a different moment: - When the user commits the change explicitly (e.g. by selecting a date from a date picker for `<ion-input type="date">`, pressing the "Enter" key, etc.). - When the element loses focus after its value has changed: for elements where the user's interaction is typing.  This event will not emit when programmatically setting the `value` property.
          */
         "onIonChange"?: (event: IonInputCustomEvent<InputChangeEventDetail>) => void;
         /**
@@ -6383,6 +6407,10 @@ declare namespace LocalJSX {
           * Animation to use when the modal is presented.
          */
         "enterAnimation"?: AnimationBuilder;
+        /**
+          * If `true`, focus will not be allowed to move outside of this overlay. If `false`, focus will be allowed to move outside of the overlay.  In most scenarios this property should remain set to `true`. Setting this property to `false` can cause severe accessibility issues as users relying on assistive technologies may be able to move focus into a confusing state. We recommend only setting this to `false` when absolutely necessary.  Developers may want to consider disabling focus trapping if this overlay presents a non-Ionic overlay from a 3rd party library. Developers would disable focus trapping on the Ionic overlay when presenting the 3rd party overlay and then re-enable focus trapping when dismissing the 3rd party overlay and moving focus back to the Ionic overlay.
+         */
+        "focusTrap"?: boolean;
         /**
           * The horizontal line that displays at the top of a sheet modal. It is `true` by default when setting the `breakpoints` and `initialBreakpoint` properties.
          */
@@ -6546,7 +6574,7 @@ declare namespace LocalJSX {
          */
         "mode"?: "ios" | "md";
         /**
-          * Emitted when the value has changed.
+          * Emitted when the value has changed.  This event will not emit when programmatically setting the `value` property.
          */
         "onIonChange"?: (event: IonPickerColumnCustomEvent<PickerColumnChangeEventDetail>) => void;
         /**
@@ -6701,6 +6729,10 @@ declare namespace LocalJSX {
           * The event to pass to the popover animation.
          */
         "event"?: any;
+        /**
+          * If `true`, focus will not be allowed to move outside of this overlay. If `false`, focus will be allowed to move outside of the overlay.  In most scenarios this property should remain set to `true`. Setting this property to `false` can cause severe accessibility issues as users relying on assistive technologies may be able to move focus into a confusing state. We recommend only setting this to `false` when absolutely necessary.  Developers may want to consider disabling focus trapping if this overlay presents a non-Ionic overlay from a 3rd party library. Developers would disable focus trapping on the Ionic overlay when presenting the 3rd party overlay and then re-enable focus trapping when dismissing the 3rd party overlay and moving focus back to the Ionic overlay.
+         */
+        "focusTrap"?: boolean;
         /**
           * Additional attributes to pass to the popover.
          */
@@ -6868,7 +6900,7 @@ declare namespace LocalJSX {
          */
         "name"?: string;
         /**
-          * Emitted when the value has changed.
+          * Emitted when the value has changed.  This event will not emit when programmatically setting the `value` property.
          */
         "onIonChange"?: (event: IonRadioGroupCustomEvent<RadioGroupChangeEventDetail>) => void;
         /**
@@ -6926,7 +6958,7 @@ declare namespace LocalJSX {
          */
         "onIonBlur"?: (event: IonRangeCustomEvent<void>) => void;
         /**
-          * The `ionChange` event is fired for `<ion-range>` elements when the user modifies the element's value: - When the user releases the knob after dragging; - When the user moves the knob with keyboard arrows  `ionChange` is not fired when the value is changed programmatically.
+          * The `ionChange` event is fired for `<ion-range>` elements when the user modifies the element's value: - When the user releases the knob after dragging; - When the user moves the knob with keyboard arrows  This event will not emit when programmatically setting the `value` property.
          */
         "onIonChange"?: (event: IonRangeCustomEvent<RangeChangeEventDetail>) => void;
         /**
@@ -7222,7 +7254,7 @@ declare namespace LocalJSX {
          */
         "onIonCancel"?: (event: IonSearchbarCustomEvent<void>) => void;
         /**
-          * The `ionChange` event is fired for `<ion-searchbar>` elements when the user modifies the element's value. Unlike the `ionInput` event, the `ionChange` event is not necessarily fired for each alteration to an element's value.  The `ionChange` event is fired when the value has been committed by the user. This can happen when the element loses focus or when the "Enter" key is pressed. `ionChange` can also fire when clicking the clear or cancel buttons.
+          * The `ionChange` event is fired for `<ion-searchbar>` elements when the user modifies the element's value. Unlike the `ionInput` event, the `ionChange` event is not necessarily fired for each alteration to an element's value.  The `ionChange` event is fired when the value has been committed by the user. This can happen when the element loses focus or when the "Enter" key is pressed. `ionChange` can also fire when clicking the clear or cancel buttons.  This event will not emit when programmatically setting the `value` property.
          */
         "onIonChange"?: (event: IonSearchbarCustomEvent<SearchbarChangeEventDetail>) => void;
         /**
@@ -7280,7 +7312,7 @@ declare namespace LocalJSX {
          */
         "mode"?: "ios" | "md";
         /**
-          * Emitted when the value property has changed and any dragging pointer has been released from `ion-segment`.
+          * Emitted when the value property has changed and any dragging pointer has been released from `ion-segment`.  This event will not emit when programmatically setting the `value` property.
          */
         "onIonChange"?: (event: IonSegmentCustomEvent<SegmentChangeEventDetail>) => void;
         /**
@@ -7392,7 +7424,7 @@ declare namespace LocalJSX {
          */
         "onIonCancel"?: (event: IonSelectCustomEvent<void>) => void;
         /**
-          * Emitted when the value has changed.
+          * Emitted when the value has changed.  This event will not emit when programmatically setting the `value` property.
          */
         "onIonChange"?: (event: IonSelectCustomEvent<SelectChangeEventDetail>) => void;
         /**
@@ -7674,7 +7706,7 @@ declare namespace LocalJSX {
          */
         "onIonBlur"?: (event: IonTextareaCustomEvent<FocusEvent>) => void;
         /**
-          * The `ionChange` event is fired when the user modifies the textarea's value. Unlike the `ionInput` event, the `ionChange` event is fired when the element loses focus after its value has been modified.
+          * The `ionChange` event is fired when the user modifies the textarea's value. Unlike the `ionInput` event, the `ionChange` event is fired when the element loses focus after its value has been modified.  This event will not emit when programmatically setting the `value` property.
          */
         "onIonChange"?: (event: IonTextareaCustomEvent<TextareaChangeEventDetail>) => void;
         /**
@@ -7886,7 +7918,7 @@ declare namespace LocalJSX {
          */
         "onIonBlur"?: (event: IonToggleCustomEvent<void>) => void;
         /**
-          * Emitted when the user switches the toggle on or off. Does not emit when programmatically changing the value of the `checked` property.
+          * Emitted when the user switches the toggle on or off.  This event will not emit when programmatically setting the `checked` property.
          */
         "onIonChange"?: (event: IonToggleCustomEvent<ToggleChangeEventDetail>) => void;
         /**

package/dist/types/utils/config.d.ts

@@ -165,6 +165,13 @@ export interface IonicConfig {
      * Overrides the default platform detection methods.
      */
     platform?: PlatformConfig;
+    /**
+     * @experimental
+     * When defined, Ionic will move focus to the appropriate element after each
+     * page transition. This ensures that users relying on assistive technology
+     * are informed when a page transition happens.
+     */
+    focusManagerPriority?: FocusManagerPriority[];
     /**
      * @experimental
      * If `true`, the [CloseWatcher API](https://github.com/WICG/close-watcher) will be used to handle
@@ -186,6 +193,8 @@ export interface IonicConfig {
     _rel?: (el: any, name: string, cb: any, opts: any) => any;
     _ce?: (eventName: string, opts: any) => any;
 }
+type FocusManagerPriority = 'content' | 'heading' | 'banner';
 export declare const setupConfig: (config: IonicConfig) => any;
 export declare const getMode: () => Mode;
 export declare const ENABLE_HTML_CONTENT_DEFAULT = false;
+export {};

package/dist/types/utils/focus-controller/index.d.ts

@@ -0,0 +1,13 @@
+/**
+ * The focus controller allows us to manage focus within a view so assistive
+ * technologies can inform users of changes to the navigation state. Traditional
+ * native apps have a way of informing assistive technology about a navigation
+ * state change. Mobile browsers have this too, but only when doing a full page
+ * load. In a single page app we do not do that, so we need to build this
+ * integration ourselves.
+ */
+export declare const createFocusController: () => FocusController;
+export type FocusController = {
+    saveViewFocus: (referenceEl?: HTMLElement) => void;
+    setViewFocus: (referenceEl: HTMLElement) => void;
+};

package/dist/types/utils/overlays.d.ts

@@ -134,3 +134,4 @@ export declare const createTriggerController: () => {
     addClickListener: (el: HTMLIonOverlayElement, trigger: string) => void;
     removeClickListener: () => void;
 };
+export declare const FOCUS_TRAP_DISABLE_CLASS = "ion-disable-focus-trap";