esri/calcite-design-system

A monorepo containing the packages for Esri's Calcite Design System

Calcite Design System

This is a monorepo containing Calcite Design System packages. Please see the package-specific readmes for more information.

Contributing

We welcome contributions to this project. See CONTRIBUTING.md for an overview of contribution guidelines.

License

COPYRIGHT © 2024 Esri

All rights reserved under the copyright laws of the United States and applicable international laws, treaties, and conventions.

This material is licensed for use under the Esri Master License Agreement (MLA), and is bound by the terms of that agreement. You may redistribute and use this code without modification, provided you adhere to the terms of the MLA and include this copyright notice.

See use restrictions at http://www.esri.com/legal/pdfs/mla_e204_e300/english

For additional information, contact: Environmental Systems Research Institute, Inc. Attn: Contracts and Legal Services Department 380 New York Street Redlands, California, USA 92373 USA

email: [email protected]

calcite-design-system's Issues

Component: Alert

example: https://ionicframework.com/docs/api/alert

Multi Select Menu

cc: @asangma @patrickarlt
I can start looking at development based existing design. may be we can enhance when we have better design.

This is required for chart authoring experience and designed by Mike Stinson.

Bug: Calcite switch input `name` and `value` attributes overwritten

cc @patrickarlt

I came across this while working on #1. I think this issue is coming from the syncProxyInput method. The method should check whether the this.inputProxy has a name or value before assigning this.name or this.value. It should also check whether this.name or this.value is undefined, to avoid assigning the string "undefined" to the proxy input.

To reproduce:

Pass an input with a name and/or value into calcite-switch's slot:

<label>
  <calcite-switch>
    <input type="checkbox" name='some-name' value='some-value'/>
  </calcite-switch>
  Here's my label
</label>

Expected result

Expect to have calcite-switch's input element to have correct name and value attrs in the outputted DOM, e.g.

<label>
  <calcite-switch>
    <input type="checkbox" name='some-name' value='some-value'/>
  </calcite-switch>
  Here's my label
</label>

Actual result

name and value are overwritten with the string "undefined".

<label>
  <calcite-switch>
    <input type="checkbox" name='undefined' value='undefined'/>
  </calcite-switch>
  Here's my label
</label>

Note that this only happens with name and value. You could pass in some-random-attr='test' and it is maintained.

Workaround

You can put the name and value on calcite-switch directly:

<label>
  <calcite-switch  name='some-name' value='some-value'>
    <input type="checkbox"/>
  </calcite-switch>
  Here's my label
</label>

Component: Buttons

Should support:
type (primary, secondary, inline, etc.),
loading / loading complete,
icon and positioning of icons,
width (default, half, full),
scale (xl,l,m,s,xs, etc.),

LocalStorage improvements for Tabs

Taking a stab at this.... based on comments in #32, we probably want to aggregate each component's localStorage use to a single store, instead of an individual store for each instance of that component.

Tab issue: #8

Can maybe just leave it in the Tab component for now and then abstract into a utility if other components end up using localStorage.

Provide short medium and long INTL format for date picker

One requirement for DatePicker is to support the INTL format this has been an issue with Datepickers in the past as we support 30+ languages
Support for short, medium and long formats as mentioned INTL format

#92

Component: ToggleSwitch

Unable to find a design in Calcite Web 2.0.

Also See: https://ionicframework.com/docs/api/toggle

Create Storybook for Docs

Re: #80

I think a Storybook would be a good way to publish docs... The Calcite Design Site will eventually have design implementation guidance (and be behind Okta), so we'll still need public-facing implementation docs.

There's some discussion on how to integrate Stencil with Storybook, as well as some starters that have been created we could probably leverage:

storybookjs/storybook#4600
https://github.com/DesignByOnyx/stencil-storybook-starter

I think Docz would be a good solution as well, seems pretty similar... https://github.com/DanielNetzer/docz-plugin-stencil

Open to other options here as well, but Storybook (or Docz)... seems to be a pretty easy solution - here's the Calcite React one (Docz): https://calcite-react.netlify.com/

Component: Chips

It'd be nice to provide what Material Design offers: https://material.io/design/components/chips.html

Optional props for: icon, color, "canClose" / deselect (emit a close event). This would be useful for data table "currently selected", filter dropdowns, etc.

Consider allowing a Calcite-avatar (when built) / Calcite-icon to the left of text.

SCSS Methodology

We should decide on a syntax and style for writing SCSS before we reach a point where we have so many components that updating them becomes a chore.

I'm mostly of the mindset that web components allow us to avoid something as heavy as BEM, and use more lightly-scoped class names and 'is-active' type props on components to achieve styling.

Thoughts? 🍿

Enhancements: Buttons

Catch all for button improvements after upcoming release

• for appearance: inline buttons, place the icon in a trailing position and adjust the spacing accordingly.
• scale icons / inline loader based on scale property
• allow focus state by removing outline: none on all appearance type aside from inline (as underline animation works for focus state in that case)

Component: Label

This arose from #24
cc: @patrickarlt @macandcheese

Conventions: Color variable names

Breakout from: #32 (comment)

Discuss. I'll flesh this out later. 😄

Remove dependency on calcite-fonts

Currently our dependency on calcite-fonts is a private repo. We probably need to remove it as a dependency from package.json and include it some other way like from a CDN.

@paulcpederson I'm assigning you because @julio8a said you might have a solution for this.

Convention: Exposing CSS properties for theming

Components should provide CSS properties for theming. We need to decide on a pattern for this allow users to customize at least the colors of components.

We need a system in place for this. I think I have an idea based on custom properties and fallback values. https://developer.mozilla.org/en-US/docs/Web/CSS/Using_CSS_custom_properties#Custom_property_fallback_values.

This issue has origins in this thread on teams.

I'll work on this next week.

Bug: Calcite Switch `switched` attr not working when proxy input passed in

To reproduce

<calcite-switch switched='true'>
  <input type='checkbox' />
</calcite-switch>

Expected result

Switch should be initially checked.

Actual result

Switch is initially unchecked

Workaround

You can put the checked attr on the input itself:

<calcite-switch>
  <input type='checkbox' checked/>
</calcite-switch>

Read-me link to example site is 404

The link to the example site in the read-me is invalid: https://github.com/Esri/calcite-components

Component: Accordion

Esri/calcite-web#1015

Conventions: Should use a CSS naming convention like BEM?

Breakout from #32 (comment)

Discuss. I'll flesh this out later. 😄

Set up Prettier

Set up Prettier to automate formatting. This will use the same config from calcite-app-components.

Introduce Autoprefixer into the build process

This has 2 major benefits.

1. It eliminates developers needing to intentionally read/write (while deving and code reviewing) vendor prefixes for CSS properties. Less work!
2. It prevents browser-specific bugs from a vendor prefix being accidentally omitted or typo'd.

https://github.com/postcss/autoprefixer

Component: Modal

Esri/calcite-web#1013

Also See: https://ionicframework.com/docs/api/modal

Conventions: Other Esri/ArcGIS component libraries

Discuss. I'll flesh this out later. 😄

Conventions: Document <calcite-example> and basic contributing guide

Breakout of #32 (comment).

Component: Dropdown

Esri/calcite-web#1021 and Esri/calcite-web#1017.

Also See: https://ionicframework.com/docs/api/select

Component: Cards

The current cards in CW are focused towards marketing use cases, meaning any app-focused implementations need to be custom built. I think calcite-components is a good place to have a more comprehensive card component that can support consistent use of icons, title, descriptions, and provide options for click target, multi-select, etc.

Material provides a pretty exhaustive set of available layouts and combinations and would be a good place to draw inspiration from : https://material.io/design/components/cards.html#specs

I'd say this is a "wishlist" item but it's also a place of great inconsistency across apps.

[Conventions] Custom vs native events

It'd be useful to enhance the event namespacing section with info on when to add a custom event vs relying on native browser ones.

Disscussion: Global configuration

Breakout from #32 (comment), #32 (comment).

Discuss. I'll flesh this out later. 😄

Component: Tabs

Esri/calcite-web#1014

Also See: https://ionicframework.com/docs/api/tabs

Calcite-switch won't switch if not wrapped in <label>

cc @paulcpederson @patrickarlt @macandcheese
I will include a fix for this in my upcoming PR for #1.

The most basic usage of calcite-switch is broken, probably as a result of PR 48 (which I wrote):

<calcite-switch></calcite-switch>

You would expect that clicking on the resulting switch would toggle the value, but it doesn't. It works when wrapped in a label, like this:

<label>
  <calcite-switch></calcite-switch>
  click here!
</label>

This is happening because the component's switched prop gets immediately toggled back by the proxyInput mutation observer.

The proximal cause of this bug is in the mutation observer:

this.switched = this.inputProxy.checked; // returns empty string or null
// should be this instead:
this.switched = this.inputProxy.hasAttribute("checked");

More fundamentally however I wrote this bug as a result of a confusing dataflow graph. The DOM is the source of truth, so props are synced to it, but the DOM itself gets updated based on props sometimes:

• user clicks
• toggle this.switched prop
• trigger switchWatcher
• toggle checked attribute on inputProxy
• trigger inputProxy mutation observer
• set this.switched to inputProxy.checked

I don't have a solution for this deeper issue. Does anyone else have thoughts on this?

Component Date + Date Range

Draft spec for a date picker component. This is a very common need for almost every team, so would be good to start working on this one. Below is a rough draft:

Date

Browser-consistent date selection can be accomplished with the calcite-date component. Set value, min, and max properties. Value will default to today if no value is provided:

<calcite-date value="2017-06-01" max="2019-06-01"></calcite-date>

We suggest you wrap the component and add a visible label for clarity:

<label>
  Due date
  <calcite-date value="2017-06-01" max="2019-06-01"></calcite-date>
</label>

When using with React, an input can be passed in which will act as the source of truth:

<label>
  Due date
  <calcite-date>
    <input type="date" min="2016-06-01" max="2019-06-01" value="2017-06-01">
  </calcite-date>
</label>

Events:

• calciteDateChange emitted with standard event properties plus details: {date: "2018-03-05"}

Date Range

Frequently a UI will need to ask the user for a start and end date. Wrapping two calcite-date components inside a calcite-date-range will do the legwork of ensuring dates don't overlap:

<calcite-date-range>
  <calcite-date slot="start" value="2017-06-01" min="2016-06-01"></calcite-date>
  <calcite-date slot="end" value="2017-06-01" max="2019-06-01"></calcite-date>
</calcite-date-range>

Events:

• calciteDateRangeChange emitted with standard event properties plus details: {startDate: "2018-03-05", endDate: "2018-03-05"}

---

Questions include:

• how to integrate moment into the build without bloating people's apps
• how to do locale-specific date formatting

---

Assigning to @julio8a to add his designs he's working on into this issue. We can work through API questions here prior to implementation.

Component: Stepper

This is a good candidate for inclusion in Calcite Components - it's used widely across apps and is inconsistently implemented. We'd probably want to support:

• title
• subtext (useful for persisting small contextually relevant data from past steps for a user to see without navigating back, especially on mobile)
• "returnable" - that is, are previously completed steps available to click on to view again
• incorporate mobile designs
• support for "error" (red) state on steps
• possibly include ability to add icons
• slot for step "content" similar to tabs
• should have a vertical orientation available at desktop size (pretty similar to mobile designs)

The latest designs should be on the invite members workflow. I think we can adjust the spacing a tiny bit in our version of the component to utilize our spacing and sizing, and allow the component to be used inside a modal/takeover with a little tighter spacing.

First alpha release

@paulcpederson @julio8a @macandcheese I would like to be able to present Calcite Components at the brown bag session in ~2 weeks. By then do you think we could cut an initial alpha release so I can start to integrate this into the ArcGIS for Developers and Vector Tile Style Editor. IT would be great to have:

• <calcite-tabs> - can replace out current tabs in a few places on ArcGIS for Developers
• <calcite-alerts> - can replace our current alerts in VTSE
• <calcite-modal> - can replace our current modals in both ArcGIS for Developers and VTSE.
• <calcite-accordion> - can replace out current accordion in a few places on ArcGIS for Developers

Would everyone be ok with me standing up some initial build tooling?

Component: Combobox

In a recent meeting we discussed some of the behavior around "select" and "dropdown" type elements discussed in:

• Esri/calcite-app-components#12 (comment)
• Multiselect/Filter Select From #2 (comment)
• #46

In the end we settled on implementing something like the multiple select/filter dropdown @macandcheese proposed in #2 (comment)

The purpose of this component would be to allow a use to pick an item or set of items from a list

In order to accommodate various use cases we should incorporate the following options.

• Permanently open (with user defined height) or open on select - for charting components
• Show/hide chips - for charting components
• Chip position (inline, after list, hidden)
• Filterable or not filterable - for long lists
• Add arbitrary values - for tag lists

Similar to other components that implement form controls I would REALLY like this to look like:

<calcite-super-select>
  <select name="tags" multupile>
    <option value="Test">
    <option value="Foo">
    <option value="Bar">
  </select>
</calcite-super-select>

I also think this could be called something more reasonable like <calcite-combo-select>

Proposed API

Aria role: Listbox. https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Roles/listbox_role

/**
 * @slot - A slot for adding `calcite-select-option`s that will appear inside the component.
 */
CalciteSelect { // could this wrap a native <select> element?
  // default title displayed when no value is selected.
  @Prop({reflect: true}) defaultTitle!: string;

  @Prop({ reflect: true }) disabled = false;
  @Prop({ reflect: true }) loading = false;

  // Ability to select multiple or single values.
  // Multiple will display the select as a list without the menu.
  @Prop({ reflect: true }) multiple = false;

  @Prop({ reflect: true }) theme: "light" | "dark" = "light";

  // Version 2 props:
  // @Prop({ reflect: true }) filter = false; // V2
  // @Prop({ reflect: true }) chips = false; // V2
  // @Prop({ reflect: true }) chipValues = []; // V2
  // @Prop({ reflect: true }) chipPosition = "inline" | "after" | "list"; // V2

  @Method()
  async setFocus() {}

  @Event() calciteSelectChange: EventEmitter;
}

/**
 * @slot icon - A slot for adding content that will appear on the leading side of the option.
option.
 */
CalciteSelectOption { // could this wrap a native <option> element?
  @Prop({ reflect: true }) value!: string;
  @Prop({ reflect: true }) title!: string;
  @Prop({ reflect: true }) selected: boolean = false;

  @Event() calciteSelectOptionChange: EventEmitter;
}

Example

<calcite-select>
  <calcite-select-option value="1" title="hello" selected></calcite-select-option>
  <calcite-select-option value="2" title="hi">
    <calcite-icon slot="icon" icon="x">
  </calcite-select-option>
  <calcite-select-option value="3" title="parent">
    <!-- nesting is allowed for indentation like a list item -->
    <calcite-select-option value="4" title="child"></calcite-select-option>
  </calcite-select-option>
</calcite-select>

Floating panel doesn't allow for scrolling overflowed content

This issue appears in the Map Maker project on dev. The dev build is currently broken so I'm using a prd link to also demonstrate the issue.

1. Open this link - http://jsapi.maps.arcgis.com/apps/mapviewer/index.html?webmap=5dbfdbcbf36d4c1d81c22f7039631e59 (This link is production, but the same issue exists on dev, which isn't working ATM)
2. Click the layer name "Dominant copy by U.S. county"
3. Click the "modify style" icon (the 4th option - the one with the shapes - from the top on the right side of the page).
4. Dot Density is already selected. Click "more options" on that card.
5. Click "Edit background style"
6. Click "Outline"
7. Click "Custom Color".
8. Notice there is no way to scroll to the other options while the upper sections are expanded. This component should allow for scrolling content that is longer than the container height.

cc @driskull

Conventions: Slot and Property validation.

Discuss. I'll flesh this out later. 😄

Global: SCSS Imports

Make underlying variables available for each component's scoped SCSS file. We should leverage the calcite-colors, calcite-fonts, etc., repos here. Maybe through a root-level includes.scss file?

It might also be a good time to think about a calcite-tokens or low-level variable library of spacing, shadow values, etc.,

in 'stencil-config'...

globalStyle: 'src/assets/styles/includes.scss',
  plugins: [
    sass({
      injectGlobalPaths: [
       'src/assets/styles/includes.scss'
      ]
    })
  ]

1.0 Release Cleanup

Opening individual issues per component... stay tuned...

Component: Slider

Couldn't find a design in Calcite Web 2.0.

Also See: https://ionicframework.com/docs/api/range

Component: Loader

Esri/calcite-web#1022

Also See: https://ionicframework.com/docs/api/progress-bar

Component: Radio Group

Esri/calcite-web#1030

Also See: https://ionicframework.com/docs/api/radio-group, https://ionicframework.com/docs/api/radio

Conventions: Naming conventions for attributes

@driskull @ycabon Agreed we should document naming conventions #32 (comment).

Examples:

• active not isActive
• disabled not isDisabled

Some components will have to change to accommodate this.

Component: Select

Esri/calcite-web#1017 and Esri/calcite-web#1021

Also See: https://ionicframework.com/docs/api/select

Component: Tree Navigation

http://proto.esri.com/#/detail/Navigation/Tree%20Navigation/1

I'm adding this to the initial list from @paulcpederson because we have a pretty big need for it on both the Developers Site (the existing side nav pattern isn't working for us anymore) and the Vector Tile Style Editor (our existing Angular tree component has issues).

CalciteRadioGroup#focus() should focus first applicable item

As noted in #72 (comment).

Conventions: 3rd party resources

Discuss. I'll flesh this out later. 😄

Tabs: Unregister a tab when it is removed from DOM to keep aria labels in sync

Tabs: Unregister a tab when it is removed from DOM to keep aria labels in sync.

From Teams discussion

Component: Checkbox

Esri/calcite-web#1030

Also See: https://ionicframework.com/docs/api/checkbox

Component: Color Picker

Specs and designs to follow.

Custom :focus styles

Are there any plans or patterns to do custom :focus states?
We sometimes see weird stuff with browser default focus outline.

Of course, we would want to retain accessibility.

I know there's stuff like outliner.js and stuff like that.

cc @driskull @jcfranco

a11yproject.com article