@esri/calcite-components 1.0.0-next.596 → 1.0.0-next.597

package/dist/types/stencil-public-runtime.d.ts

@@ -221,7 +221,8 @@ export declare type ErrorHandler = (err: any, element?: HTMLElement) => void;
  */
 export declare const setMode: (handler: ResolutionHandler) => void;
 /**
- * getMode
+ * `getMode()` is used for libraries which provide multiple "modes" for styles.
+ * @param ref a reference to the node to get styles for
  */
 export declare function getMode<T = string | undefined>(ref: any): T;
 export declare function setPlatformHelpers(helpers: {
@@ -234,6 +235,8 @@ export declare function setPlatformHelpers(helpers: {
 /**
  * Get the base path to where the assets can be found. Use `setAssetPath(path)`
  * if the path needs to be customized.
+ * @param path the path to use in calculating the asset path. this value will be
+ * used in conjunction with the base asset path
  */
 export declare function getAssetPath(path: string): string;
 /**
@@ -246,18 +249,22 @@ export declare function getAssetPath(path: string): string;
  * `setAssetPath(document.currentScript.src)`, or using a bundler's replace plugin to
  * dynamically set the path at build time, such as `setAssetPath(process.env.ASSET_PATH)`.
  * But do note that this configuration depends on how your script is bundled, or lack of
- * bunding, and where your assets can be loaded from. Additionally custom bundling
+ * bundling, and where your assets can be loaded from. Additionally custom bundling
  * will have to ensure the static assets are copied to its build directory.
+ * @param path the asset path to set
  */
 export declare function setAssetPath(path: string): string;
 /**
- * getElement
+ * Retrieve a Stencil element for a given reference
+ * @param ref the ref to get the Stencil element for
  */
 export declare function getElement(ref: any): HTMLStencilElement;
 /**
  * Schedules a new render of the given instance or element even if no state changed.
  *
- * Notice `forceUpdate()` is not syncronous and might perform the DOM render in the next frame.
+ * Notice `forceUpdate()` is not synchronous and might perform the DOM render in the next frame.
+ *
+ * @param ref the node/element to force the re-render of
  */
 export declare function forceUpdate(ref: any): void;
 /**
@@ -272,6 +279,8 @@ export interface HTMLStencilElement extends HTMLElement {
  * in the best moment to perform DOM mutation without causing layout thrashing.
  *
  * For further information: https://developers.google.com/web/fundamentals/performance/rendering/avoid-large-complex-layouts-and-layout-thrashing
+ *
+ * @param task the DOM-write to schedule
  */
 export declare function writeTask(task: RafCallback): void;
 /**
@@ -279,6 +288,8 @@ export declare function writeTask(task: RafCallback): void;
  * in the best moment to perform DOM reads without causing layout thrashing.
  *
  * For further information: https://developers.google.com/web/fundamentals/performance/rendering/avoid-large-complex-layouts-and-layout-thrashing
+ *
+ * @param task the DOM-read to schedule
  */
 export declare function readTask(task: RafCallback): void;
 /**

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

@@ -30,6 +30,16 @@ export declare function queryElementRoots<T extends Element = Element>(element:
   id?: string;
 }): T | null;
 export declare function closestElementCrossShadowBoundary<T extends Element = Element>(element: Element, selector: string): T | null;
+/**
+ * This utility helps invoke a callback as it traverses a node and its ancestors until reaching the root document.
+ *
+ * Returning early or undefined in `onVisit` will continue traversing up the DOM tree. Otherwise, traversal will halt with the returned value as the result of the function
+ *
+ * @param element
+ * @param onVisit
+ */
+export declare function walkUpAncestry<T = any>(element: Element, onVisit: (node: Node) => T): T;
+export declare function containsCrossShadowBoundary(element: Element, maybeDescendant: Element): boolean;
 export interface FocusableElement extends HTMLElement {
   setFocus?: () => Promise<void>;
 }

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

@@ -1,15 +1,14 @@
-import { GlobalAttrComponent } from "./globalAttributes";
 export declare const locales: string[];
-export declare function createLocaleNumberFormatter(locale: string, numberingSystem?: string): Intl.NumberFormat;
-export declare function delocalizeNumberString(numberString: string, locale: string): string;
-export declare function getGroupSeparator(locale: string): string;
-export declare function getDecimalSeparator(locale: string): string;
-export declare function getMinusSign(locale: string): string;
-export declare function localizeNumberString(numberString: string, locale: string, displayGroupSeparator?: boolean, numberingSystem?: string): string;
+export declare const numberingSystems: readonly ["arab", "arabext", "bali", "beng", "deva", "fullwide", "gujr", "guru", "hanidec", "khmr", "knda", "laoo", "latn", "limb", "mlym", "mong", "mymr", "orya", "tamldec", "telu", "thai", "tibt"];
+export declare type NumberingSystem = typeof numberingSystems[number];
+export declare const defaultNumberingSystem: "arab" | "arabext" | "bali" | "beng" | "deva" | "fullwide" | "gujr" | "guru" | "hanidec" | "khmr" | "knda" | "laoo" | "latn" | "limb" | "mlym" | "mong" | "mymr" | "orya" | "tamldec" | "telu" | "thai" | "tibt";
+export declare const getSupportedNumberingSystem: (numberingSystem: string) => NumberingSystem;
+export declare function getSupportedLocale(locale: string): string;
 /**
  * This interface is for components that need to determine locale from the lang attribute.
  */
-export interface LangComponent extends GlobalAttrComponent {
+export interface LocalizedComponent {
+  el: HTMLElement;
   /**
    * BCP 47 language tag for desired language and country format
    *
@@ -19,11 +18,80 @@ export interface LangComponent extends GlobalAttrComponent {
    * @mdn [lang](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/lang)
    */
   locale?: string;
+  /**
+   * Used to store the effective locale to avoid multiple lookups.
+   *
+   * This is an internal property and should:
+   *
+   * - use the `@State` decorator
+   * - be initialized to ""
+   *
+   * Components should watch this prop to ensure messages are updated.
+   *
+   * @Watch("effectiveLocale")
+   * effectiveLocaleChange(): void {
+   *   updateMessages(this, this.effectiveLocale);
+   * }
+   */
+  effectiveLocale: string;
 }
 /**
- * This util helps resolve a component's locale.
- * It will also fall back on the deprecated `locale` if a component implemented this previously.
+ * This utility sets up internals for messages support.
+ *
+ * It needs to be called in `connectedCallback` before any logic that depends on locale
+ *
+ * @param component
+ */
+export declare function connectLocalized(component: LocalizedComponent): void;
+/**
+ * This is only exported for components that implemented the now deprecated `locale` prop.
+ *
+ * Do not use this utils for new components.
+ *
+ * @param component
+ */
+export declare function updateEffectiveLocale(component: LocalizedComponent): void;
+/**
+ * This utility tears down internals for messages support.
+ *
+ * It needs to be called in `disconnectedCallback`
  *
  * @param component
  */
-export declare function getLocale(component: LangComponent): string;
+export declare function disconnectLocalized(component: LocalizedComponent): void;
+interface NumberStringFormatOptions {
+  numberingSystem: NumberingSystem;
+  locale: string;
+  useGrouping: boolean;
+}
+/**
+ * This util formats and parses numbers for localization
+ */
+declare class NumberStringFormat {
+  numberingSystem: string;
+  locale: string;
+  useGrouping: boolean;
+  /**
+   * The actual group separator for the specified locale
+   * some white space group separators don't render correctly in the browser
+   * so we replace them with a normal <SPACE>
+   */
+  actualGroup: string;
+  /** the corrected group separator */
+  group: string;
+  decimal: string;
+  minusSign: string;
+  digits: Array<string>;
+  getDigitIndex: any;
+  numberFormatter: Intl.NumberFormat;
+  /**
+   * This method needs to be called before localize/delocalize to ensure the options are up to date
+   *
+   * @param options
+   */
+  setOptions: (options: NumberStringFormatOptions) => void;
+  delocalize: (numberString: string) => string;
+  localize: (numberString: string) => string;
+}
+export declare const numberStringFormatter: NumberStringFormat;
+export {};

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

@@ -8,7 +8,8 @@ export declare class BigDecimal {
   static _divRound(dividend: bigint, divisor: bigint): bigint;
   static fromBigInt(bigint: bigint): bigint;
   toString(): string;
-  formatToParts(locale: string, numberingSystem?: string): Intl.NumberFormatPart[];
+  formatToParts(formatter: Intl.NumberFormat): Intl.NumberFormatPart[];
+  format(formatter: Intl.NumberFormat): string;
   add(num: string): bigint;
   subtract(num: string): bigint;
   multiply(num: string): bigint;
@@ -16,8 +17,5 @@ export declare class BigDecimal {
 }
 export declare function isValidNumber(numberString: string): boolean;
 export declare function parseNumberString(numberString?: string): string;
-export declare function sanitizeDecimalString(decimalString: string): string;
-export declare function sanitizeNegativeString(negativeString: string): string;
-export declare function sanitizeLeadingZeroString(zeroString: string): string;
-export declare function sanitizeNumberString(numberString: string): string;
+export declare const sanitizeNumberString: (numberString: string) => string;
 export declare function sanitizeExponentialNumberString(numberString: string, func: (s: string) => string): string;

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

@@ -1,7 +1,11 @@
+export interface ExtendedMutationObserver extends MutationObserver {
+  new: () => ExtendedMutationObserver;
+  unobserve(target: Node): void;
+}
 declare type ObserverType = "mutation" | "intersection" | "resize";
 declare type ObserverCallbackType<T extends ObserverType> = T extends "mutation" ? MutationCallback : T extends "intersection" ? IntersectionObserverCallback : T extends "resize" ? ResizeObserverCallback : never;
 declare type ObserverOptions<T extends ObserverType> = T extends "mutation" ? MutationObserverInit : T extends "intersection" ? IntersectionObserverInit : T extends "resize" ? never : never;
-declare type ObserverInstanceType<T extends ObserverType> = T extends "mutation" ? MutationObserver : T extends "intersection" ? IntersectionObserver : T extends "resize" ? ResizeObserver : never;
+declare type ObserverInstanceType<T extends ObserverType> = T extends "mutation" ? ExtendedMutationObserver : T extends "intersection" ? IntersectionObserver : T extends "resize" ? ResizeObserver : never;
 /**
  * This utility ensures observers are created only for browser contexts.
  *

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

@@ -0,0 +1,88 @@
+import { LocalizedComponent } from "./locale";
+export declare type MessageBundle = Record<string, string>;
+export declare const componentLangToMessageBundleCache: Record<string, Promise<MessageBundle>>;
+/**
+ * This util helps preserve existing intlProp usage when they have not been replaced by overrides.
+ *
+ * @param component
+ */
+export declare function overridesFromIntlProps(component: T9nComponent): MessageBundle;
+/**
+ * This utility sets up the messages used by the component. It should be awaited in the `componentWillLoad` lifecycle hook.
+ *
+ * @param component
+ */
+export declare function setUpMessages(component: T9nComponent): Promise<void>;
+/**
+ * This utility must be set up for the component to update its default message bundle if the locale changes.
+ *
+ * It can be set up in **either** of the following ways:
+ *
+ * 1. called from `LocalizedComponent`'s `onLocaleChange` method or
+ * 2. called from a watcher configured to watch `LocalizedComponent`'s `effectiveLocale` prop
+ *
+ * @param component
+ * @param lang
+ */
+export declare function updateMessages(component: T9nComponent, lang: string): Promise<void>;
+/**
+ * This utility sets up internals for messages support.
+ *
+ * It needs to be called in `connectedCallback`
+ *
+ * **Note**: this must be called after `LocalizedComponent`'s `connectLocalized` method.
+ *
+ * @param component
+ */
+export declare function connectMessages(component: T9nComponent): void;
+/**
+ * This utility tears down internals for messages support.
+ *
+ * It needs to be called in `disconnectedCallback`
+ *
+ * @param component
+ */
+export declare function disconnectMessages(component: T9nComponent): void;
+/**
+ * This interface enables components to support built-in translation strings.
+ *
+ * **Notes**:
+ *
+ * This requires `LocalizedComponent` to be implemented.
+ * To avoid unnecessary lookups, composite components should set `lang` on internal t9n components.
+ */
+export interface T9nComponent extends LocalizedComponent {
+  el: HTMLElement;
+  /**
+   * This property holds all messages used by the component's rendering.
+   *
+   * This prop should use the `@State` decorator.
+   */
+  messages: MessageBundle;
+  /**
+   * This property holds the component's default messages.
+   *
+   * This prop should use the `@State` decorator.
+   */
+  defaultMessages: MessageBundle;
+  /**
+   * This property holds all user message overrides.
+   *
+   * This prop should use the `@Prop` decorator.
+   */
+  messageOverrides: Partial<MessageBundle>;
+  /**
+   * This private method ensures messages are kept in sync.
+   *
+   * This method should be empty and configured to watch for changes on `defaultMessages`, `messageOverrides` and any associated Intl prop.
+   *
+   * @Watch("intlMyPropA")
+   * @Watch("intlMyPropZ")
+   * @Watch("defaultMessages")
+   * @Watch("messageOverrides")
+   * onMessagesChange(): void {
+   *  \/* wired up by t9n util *\/
+   * }
+   */
+  onMessagesChange(): void;
+}

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

@@ -24,6 +24,6 @@ export declare function getMeridiem(hour: string): Meridiem;
 export declare function isValidTime(value: string): boolean;
 export declare function localizeTimePart(value: string, part: TimePart, locale: string): string;
 export declare function localizeTimeString(value: string, locale?: string, includeSeconds?: boolean): string;
-export declare function localizeTimeStringToParts(value: string, locale?: string): LocalizedTime;
+export declare function localizeTimeStringToParts(value: string, locale: string): LocalizedTime;
 export declare function getTimeParts(value: string, locale?: string): Intl.DateTimeFormatPart[];
 export declare function parseTimeString(value: string): Time;

package/hydrate/index.d.ts

@@ -1,4 +1,4 @@
-// Generated by dts-bundle-generator v5.3.0
+// Generated by dts-bundle-generator v6.12.0
 
 export declare function createWindowFromHtml(templateHtml: string, uniqueId: string): any;
 export interface HydrateDocumentOptions {