May 2024 Summary

Updates since 2.6.0

New Components and initiatives

• Carousel and Carousel Item
• Tile redesign
• Validation support

Carousel and Carousel Item

Introducing new components, Carousel and Carousel Item, which facilitate the display of and navigation through a set of related items. The components are often used to contextually display related onboarding tips, or display messaging, media, or other related content.

The components support contextual onboarding, which could be presented within a Modal or Popover for a fleeting workflow, or within a Block or Panel for a static experience.

The components also provide autoplay with the autoplay property. When initialized, Carousel will automatically rotate through its Carousel Items

Explore additional resources on Carousel's autoplay, and Carousel best practices and recommendations.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
<calcite-carousel autoplay label="Charting features">
    <calcite-carousel-item label="Pie chart">
        <div class="carousel-custom-content">
            <calcite-chip scale="l" icon="pie-chart"></calcite-chip>
            <span>
                Pie charts are a great way to visualize data. They're easy to understand
                and can be used in a variety of ways.
            </span>
        </div>
    </calcite-carousel-item>
    <calcite-carousel-item label="Scatter plot">
        <div class="carousel-custom-content">
            <calcite-chip scale="l" icon="graph-scatter-plot"></calcite-chip>
            <span>
                The scatter plot displays the relationship between multiple variables. It's a
                great way to visualize data.
            </span>
        </div>
    </calcite-carousel-item>
    <calcite-carousel-item label="Histogram">
        <div class="carousel-custom-content">
            <calcite-chip scale="l" icon="box-chart"></calcite-chip>
            <span>
                Box charts are another great way to visualize data to illustrate trends and ranges.
            </span>
        </div>
    </calcite-carousel-item>
</calcite-carousel>

Tile redesign

Since February, Tile has been consolidated to support selection, previously only offered through Tile Select. Additionally, a new component, Tile Group, is available that consumes Tile with responsive design in mind, also offering a scale property.

The redesign provides two new slots content-top and content-bottom, where non-actionable content can be placed at the top and bottom of the component respectively.

1
2
3
4
<calcite-tile icon="heavy-snow" heading="Mount Frost" description="Base snow depth is 41-cm with all lifts open. Surface conditions are good.">
  <calcite-chip class="new" kind="brand" slot="content-top" scale="s">New</calcite-chip>
  <calcite-chip class="new" kind="outline" slot="content-bottom">Report conditions</calcite-chip>
</calcite-tile>

Validation support

In February's summary form validation was introduced, which included new properties for components in forms, such as the ability to customize validation messages and icons when a form component's status property is "invalid".

Now form components support the ValidityState interface representing the validity states that an element can be in, with respect to constraint validation. Together, they help explain why an element's value fails to validate, if it's not valid.

The support enables solutions that can fit use cases, such as patternMismatch, where if the user has provided a pattern not accepted, an error message, icon, and status can be added to the form component:

1
2
3
<calcite-label for="email-address" layout="inline">Email address:
  <calcite-input name="email-address" type="email" id="email-address" pattern="[a-z]{2}.+@example\.com" required />
</calcite-label>

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
const SHOW_VALIDATION_MESSAGES_ON_BLUR = true;
const VALIDITY_STATES = ["patternMismatch"];
const ELEMENT_CONSTRAINTS = [{
  id: "email-address",
  patternMismatch: {
    message: "Please enter a valid email address with at least three characters."
  },
}];

function checkElementConstraints(el, constraints) {
  // Clears custom validation message if all constraints are met
  if (el?.validity?.valid) {
    el.validationMessage = "";
    el.validationIcon = false;
    el.status = "idle";
    return;
  }

  // Iterates through the validity states and sets the custom validation content
  for (const state of VALIDITY_STATES) {
    if (el?.validity[state] && Object.hasOwn(constraints, state)) {
      el.validationMessage = constraints[state]?.message ?? "";
      el.validationIcon = constraints[state]?.icon ?? true;

      if (SHOW_VALIDATION_MESSAGES_ON_BLUR) {
        el.status = "invalid";
      }
      return;
    }
  }
}

window.onload = () => {
  // Blurs event listeners to check validation constraints of elements with custom messages
  ELEMENT_CONSTRAINTS.forEach((data) => {
    document.querySelector(`#${data.id}`)?.addEventListener("blur", ({ target }) =>
      checkElementConstraints(target, data)
    );
  });
};

Feature enhancements

• Slider custom labeling
• Slider fill placement
• Read only support for Input Time Zone and Combobox
• Button adds the download property
• Color Picker adds clearable property
• Avatar background color generation
• Panel and Flow Item content slots
• Icon performance improvements

Slider custom labeling

A new property labelFormatter is available for Slider, which accepts a synchronous function that dynamically updates the component's handle text to accommodate custom labels in response to changes.

1
2
3
4
5
6
7
8
9
10
11
12
13
<label>Temperature:</label>
<calcite-slider
  id="singleFormattedLabelSlider"
  label-handles
  label-ticks
  ticks="10"
  min="0"
  max="100"
  value="50"
  step="1"
  min-label="Temperature"
  precise
></calcite-slider>

1
2
3
4
5
6
7
8
9
10
11
12
13
const singleValueSlider = document.getElementById("singleFormattedLabelSlider");
singleValueSlider.labelFormatter = function (value, type) {
  if (type === "value") {
    return value < 60 ? "🥶" : value > 80 ? "🥵" : "😎";
  }
  if (type === "tick") {
    return value === singleValueSlider.min
      ? "Cold"
      : value === singleValueSlider.max
      ? "Hot"
      : undefined;
  }
};

Slider fill placement

Another Slider property, fillPlacement, is available and can be used to specify which part of the component's rail should be highlighted relative to the handle. This property has no effect when the component is configured to show a range of values.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
<calcite-label>
  Maximum speed (MPH):
  <calcite-slider
    value="85"
    min="0"
    max="200"
    precise
    ticks="50"
    label-ticks
    label-handles
    fill-placement="start"
    scale="l"
   >
   </calcite-slider>
</calcite-label>

Read only support for Input Time Zone and Combobox

The Input Time Zone and Combobox components now support the readOnly property. This addition ensures consistent styling with other components like Input Date Picker and Input Time Picker. The readOnly property allows users to view the component's value without enabling editing, maintaining the ability to submit values while preventing unwanted changes.

Button adds the download property

Button now offers the download property. When coupled with the href property, download can be passed to the underlying element, matching native behavior and enhancing functionality.

1
    <calcite-button icon-start="download" download href="example.jpg">Download image</calcite-button>

Color Picker adds clearable property

The Color Picker component now includes the clearable property, deprecating the allowEmpty property for consistency with other components. When present, clearable allows an empty color (null) as a value. If false, a color value is enforced, and clearing the input or blurring will not be permitted. This change standardizes the nomenclature across components.

Panel and Flow Item content slots

Panel and Flow Item include two new slots, "content-top" and "content-bottom", positioned below the action-bar and above the "footer" slots respectively.

1
2
3
4
5
6
7
8
9
10
11
12
13
    <calcite-flow id="example-flow">
      <calcite-flow-item heading="Spatial Data Collaboration Agreement">
        <div slot="content-top" id="modal-title">
          Read and accept the terms
        </div>
        <calcite-label slot="content-bottom" layout="inline-space-between">
          <calcite-checkbox></calcite-checkbox>I agree to the terms
        </calcite-label>
        <calcite-button slot="footer" width="full">
          Done
        </calcite-button>
      </calcite-flow-item>
    </calcite-flow>

Avatar background color generation

Avatar now ensures different backgrounds are generated for similar values specified in its username, fullName, and userId properties using a randomly generated accessible background color.

1
2
3
<calcite-avatar full-name="John Doe" username="john_doe"></calcite-avatar>
<calcite-avatar full-name="John Doe 1" username="john_doe1"></calcite-avatar>
<calcite-avatar full-name="John Doe 22" username="john_doe-22"></calcite-avatar>

Icon performance improvements

In 2.9.0, the Icon component includes additional performance improvements to render sooner if its already visible or been previously loaded.

Accessibility improvements

• List keyboard sorting for screen reader users
• List Item keyboard accessibility for multiple slotted actions
• Combobox role for VoiceOver support

List keyboard sorting for screen reader users

When List is dragEnabled, the component supports assistive technology and keyboard users in moving its child List Item.

To move an item focus on the component's drag, or handle, button and press the space key to activate sorting on the List Item. To move the item to a new placement in the parent List, use the arrow keys for placement. Explore List's accessibility features for additional keyboard accessibility functionality.

1
2
3
4
5
<calcite-list drag-enabled>
  <calcite-list-item label="Waterfalls"></calcite-list-item>
  <calcite-list-item label="Rivers"></calcite-list-item>
  <calcite-list-item label="Hiking trails"></calcite-list-item>
</calcite-list>

List Item keyboard accessibility for multiple slotted actions

List Items now support multiple slotted actions via keyboard. When multiple Actions are slotted into an item using the "actions-start" and "actions-end" slots, the Actions supplied are accessible via keyboard.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
<calcite-list>
  <calcite-list-item label="Waterfalls" description="Vertical drops from a river." value="waterfalls">
    <calcite-action slot="actions-start" icon="gear" text="Setup the waterfalls layer"></calcite-action>
    <calcite-action slot="actions-start" icon="hammer" text="Troubleshoot the waterfalls layer"></calcite-action>
    <calcite-action slot="actions-end" icon="bookmark" text="Bookmark waterfalls layer"></calcite-action>
    <calcite-action slot="actions-end" icon="plus" text="Add waterfalls layer"></calcite-action>
  </calcite-list-item>
  <calcite-list-item label="Rivers" description="Large naturally flowing watercourses." value="rivers">
    <calcite-action slot="actions-start" icon="gear" text="Setup the rivers layer"></calcite-action>
    <calcite-action slot="actions-start" icon="hammer" text="Troubleshoot the rivers layer"></calcite-action>
    <calcite-action slot="actions-end" icon="bookmark" text="Bookmark rivers layer"></calcite-action>
    <calcite-action slot="actions-end" icon="plus" text="Add rivers layer"></calcite-action>
  </calcite-list-item>
  <calcite-list-item label="Hiking trails" description="Designated routes for hikers to use." value="hiking-trails">
    <calcite-action slot="actions-start" icon="gear" text="Setup the trails layer"></calcite-action>
    <calcite-action slot="actions-start" icon="hammer" text="Troubleshoot the trails layer"></calcite-action>
    <calcite-action slot="actions-end" icon="bookmark" text="Bookmark trails layer"></calcite-action>
    <calcite-action slot="actions-end" icon="plus" text="Add trails layer"></calcite-action>
  </calcite-list-item>
</calcite-list>

Combobox role for VoiceOver support

Combobox now supports VoiceOver keyboard navigation, where users of the assistive technology can navigate into inputs and manually enter values. The fix mitigates the Input Date Picker, where the VoiceOver user can focus on the component's input and manually enter a date entry using VoiceOver's key combinations.

Changes since February 2024

A full list of changes since February, include:

• Features
• Bug fixes
• Performance updates
• Reverts

Features

• Add calciteInvalid event for form validation (#9211) (a504508)
• Add validity property to form components (#9210) (e49902b)
• Ensure all components inherit font-family (#8388) (90f8923)
• accordion-item: add setFocus (#7211) (88b793e)
• avatar: ensure different backgrounds are generated for similar usernames, full names and user IDs (#9277) (bab77b5)
• block-section: add icon property (deprecates status) (#8110) (c31bf36)
• button: Add download property (#8882) (fc55dde)
• carousel: Add Carousel and Carousel Item components (#8995) (b1ba428)
• color-picker: Add clearable prop and deprecate allowEmpty (#8910) (f036ac2)
• dropdown-item: update spacing of icons (#7095) (c2e5a99)
• enforce-ref-last-prop: Add fixer (#8671) (688bc51)
• flow-item: add content-top slot (#8980) (e932f3d)
• input-time-zone:
  • Add readonly support (#9111) (153a122)
  • Allow clearing value (#9168) (193bb7d)
• list-item-group: Update list item group styles (#9072) (c734849)
• navigation-logo: Add heading level (#9054) (c2beba8)
• table: Add selection-display property (#9353) (7b52870)
• table-row: Add alignment property (#8961) (1f81fd7)
• pagination: Add navigation methods (#9154) (5ca6a5f)
• panel:
  • add content-top slot (#9293) (df8d71c)
  • add content-bottom slot (#8979) (87da591)
• segmented-control-item: allow displaying and icon when items are empty with a start/end icon (#6413) (9fc610d)
• slider:
  • Add support for custom label formatting (#9179) (710d1ee)
  • Allow configuring fill behavior (#9170) (1b2cdbf)
• split-button: Make dividers consistent (#8142) (2fa432d)
• stepper, stepper-item: add separate change events to stepper and items (deprecates calciteStepperItemChange on the parent) (#2094) (cf6a118)
• tabs: Make component responsive (#8616) (83a2ef4)
• tile: Add content-top and content-bottom slots, deprecate content-start and content-end slots (#8984) (eb000d8)
• tile, tile-group: Support single, multi, single-persist, none selection modes and icon and border selection appearances (#9159) (2d77470)

Bug fixes

• Add type-fest as dependency due to build error (3819688)
• Defer floating-ui updating until component is connected and open (#9443) (6e09589)
• Fix memory leak affecting components using conditionally-rendered slots (#9208) (28701b6)
• preset: Update the focus outline color (#9098) (725f47c)
• t9n: fix error caused by disconnecting components during the setting of initial message overrides (#9240) (192c031)
• action-menu, combobox, dropdown, popover, tooltip: Use click instead of pointerdown for click contexts (#8943) (cd7eed9)
• combobox, input-time-zone: Improve readOnly behavior and styling (#9222) (606d80f)
• input, input-number, input-text, input-date-picker, input-time-picker, filter, menu-item: Ignore canceled events and enforce cancellations where needed (#8952) (d0fa977)
• input-date-picker, date-picker: ensure min/max can be unset (#7889) (89b0bfe)
• input-date-picker, input-time-picker, list: ensure lang change updates messages (#9268) (0213d35)
• action: Maintain equal height when text is not enabled in a small scale (#9051) (407824a)
• block: update text hierarchy and spacing (#9323) (796372e)
• button: Make shadow dom button 100% width (#8490) (dd61b7f)
• calcite-design-tokens: Fix invalid font stacks (#8964) (d55186a)
• card: Do not apply text color to slotted footer items (#8839) (30a2068)
• carousel: Animate items with the same direction (#9325) (6bf7b74)
• checkbox: fix checkbox hit area placement in RTL (#8841) (142ef18)
• chip-group: Improve programmatic Chip selection behavior (#9213) (b7a4c77)
• combobox:
  • Prevent spacebar from opening the menu when focused on chip's close button (#8990) (1a20d0e)
  • Update the focus and hover chevron icon color (#9187) (a1317da)
  • Fix aria-role for proper voiceover support (#9039) (eebe8ca)
  • Update the focused chevron icon color (#9202) (27ac02d)
  • Fix error that occurs when a click is emitted when the component is appended to the DOM (#9373) (34a2bbe)
  • Fix error that occurs in dist-custom-elements (components) output when a click is emitted when the component is appended to the DOM (#9423) (ab521c9)
• date-picker:
  • Ensure proximitySelectionDisabled resets range on post-range-commit selection (#9171) (f466b14)
  • Restore focus on date when navigating month with arrow/page keys (#9063) (db109e0)
• dropdown: Correct positioning behavior when inside a scrollable container (#8973) (2524391)
• dropdown-group: title scale with dropdown scale (#9350) (3529cdd)
• input-date-picker: Update the focus and hover chevron icon color (#9146) (ca895e9)
• input-time-picker:
  • Update toggle icon color (#8955) (ce3ac5c)
  • Ensure selected item is properly displayed when there are other items with the same offset (#9134) (1f94903)
• input, input-number, input-text:
  • Ensure values are initialized properly for dist and components output targets (#8997) (9152211)
  • Restore autofocus, enter-key-mode and input-mode attributes (#9245) (#9306) (0498c6e)
  • Ensure autofocus is available on HTMLElement (#9343) (405a4b0)
• list, list-item, list-item-group: Improve drag experience by indenting items (#9169) (88aab49)
• list, list-item:
  • Calcite-select becomes unresponsive in a list-item if drag-disabled is true (#8957) (e408c62)
  • Support keyboard sorting in screen readers (#9038) (b2e1b9b)
• list:
  • Fix filter box when scrolling in Safari (#8938) (ea8ea1e)
  • Closed list-items no longer render extra space (#9031) (3985004)
  • border items when an item is programmatically opened (#9248) (02183bb)
• list-item: Decrease horizontal spacing between selection icon and content (#9304) (0e828b6)
• panel: Support cancelling the esc key event to prevent closing a panel (#9032) (ecfa5f1)
• popover: Prevent disabled reference elements from toggling popover (#8983) (9f4b14b)
• radio-button: Display validation message in parent group (#9218) (b1e869f)
• select:
  • Update the focus and hover chevron icon color and select focus and hover background color (#9160) (b187340)
  • fix option selection via initial value (#4461) (5206a0b)
• slider:
  • Fix fill placement and tick styling when ranged (#9204) (a84d831)
  • Improve snapping + step logic (#8169) (8b83042)
  • Rename highlightPlacement to fillPlacement (#9195) (9e5a713)
  • Style ticks according to the fill placement (#9196) (5eb4e10)
• stepper: Fix layout when switching modes dynamically to horizontal-single (#8946) (01f58bf)
• stepper-item: Remove delay in highlighting item (#8996) (bcf23dd)
• switch: prevent hover state change when disabled (#7723) (7c47808)
• table: Prevent duplicate scrollbars in certain browsers (#8962) (8434eeb)
• tab: Style focus outline of tab content (#8804) (8f0133f)
• tab-nav: Fix custom element creation error in components build output (#9021) (cc8eb99)
• text-area: remove double transparency applied when disabled (#8374) (90926c2)
• tile:
  • fix spacing between content-top and content-bottom slots (#9241) (0b9443d)
  • apply center alignment only to x-axis (#9288) (75df0ba)
  • slotted content renders within the border (#9358) (045ca2a)
• tile-group: disallow multiple selected attributes on single selection modes (#9271) (885909e)
• tree:
  • allow deselection in single selectionMode (#7900) (cb6ef73)
  • allow single select only and add indicator (#7899) (0d07b59)
• tree-item: Do not select when chevron clicked (#9115) (99ad8f1)

Performance updates

• Update transition-default Tailwind util to only target common, animatable properties (#8797) (f4d016b)
• icon: render icon sooner if already visible or loaded (#9197) (d603ca9)

Reverts

• Refactor(popover): update token pattern (#8889) (c43c280)

Compatability

The 4.30 release of the ArcGIS Maps SDK for JavaScript supports Calcite version 2.8.5. In your application, we recommend using the same version or any version greater than ^2.8.5.

If you are using version 4.29 it is recommended to use Calcite's 2.4.0, or any version greater than ^2.4.0.