esri / calcite-app-components

A collection of calcite components for building single page applications

This repository has been deprecated and merged into @esri/calcite-components

calcite-app-components

A collection of calcite components for building single page applications. For more information about these components, see the Frequenty Asked Questions.

​

View it live

Getting Started

Please see our Getting Started readme for more information.

Issues

Find a bug or want to request a new feature? Please let us know by submitting an issue.

Browser Support

Chrome Last 2 versions ✔	Firefox Last 2 versions ✔	Edge (Chromium) Last 2 versions ✔	Edge (Legacy) Last 2 versions ✔	Safari Last 2 versions ✔

Contributing

Please see our Contributing readme for more information.

Licensing

Please see our Licensing readme for more information.

calcite-app-components's Issues

Block - Stencil.js

Theming Architecture

Related to: https://devtopia.esri.com/WebGIS/arcgis-js-api/issues/21372

Goal: Allow a dev to set theme in one place at the highest level while also retaining the flexibility to set a theme on an individual component

We need to prototype:

• CSS variable inheritance (Franco)
• Component theme @prop inheriting from their parent by default (Matt) - Looked into this and seems like an inferior approach. to CSS properties
• Consider runtime theme changing
• Alan will proceed with variables in global sass file
• Will reconvene next week (post findings to issue)

Tooling: Setup gh pages with docs and examples

Summary

Setup gh pages with docs and examples

Measure of Success

Pain point:

Users cannot see the docs from the web nor see examples

Desired outcome:

Users can view examples and see docs

Positioning interface + for FloatingPanel & ActionPad

Positioning interface + for FloatingPanel & ActionPad

Tooling: setup proper dependency on `calcite-components`

Summary

Currently, the cacite-components NPM dependency doesn't have any fies in it when you do an NPM install.

Measure of Success

Pain point: There are no files in dependency
Desired outcome: /node_modules/calcite-components/ has files in it we can use.

Set up prettier

For consistency!

Enhancement: Tip - Remove use of data attribute for group title

Description

Currently, the Tip component relies on a data attribute data-group-title.

Using a custom attribute would be a better best practice. There is also no documentation or reference in the code that a user is expected to set this data attribute.

Acceptance Criteria

Use a custom attribute starting with text instead of a data attribute since it is not data, but a text label. Preferably text-group-title. @Prop textGroupTitle;

Desired New Behavior

• We should remove this use and instead use an attribute text-group-title.

Tooling: Setup a git hook to lint prior to code being pushed.

Summary

Linting is an easy step to miss. A git hook will ensure it gets executed.

Measure of Success

Pain point: People are forgetting to lint their code
Desired outcome: Linting is automated so people don't need to worry about it.

Resources (e.g. links to libraries or code snippets)

husky
Git hooks

Setup Stencil doc generation

Setup Stencil doc generation

Enhancement: Tests for Action/ActionBar/ActionPad

Description

Write tests for Action, ActionBar, ActionPad.

Acceptance Criteria (a.k.a. Requirements)

Da tests.

Bug: Block header icon should use calcite-action OR button should honor theme color

Summary

Block header icon should use calcite-action OR button should honor theme color

Code:

 <button
            aria-label={toggleLabel}
            class={CSS.toggle}
            onClick={this.onHeaderClick}
            title={toggleLabel}
          >
            {headerContent}
            <CalciteIcon
              size="16"
              path={open ? chevronUp16 : chevronDown16}
              svgAttributes={{ class: CSS.toggleIcon }}
            />
          </button>

ActionPad - Stencil.js

This is installed and ready for styling.

Need information on positioning #2

Localization support (linguijs)

https://devtopia.esri.com/WebGIS/ui-components-js/issues/47

https://github.com/lingui/js-lingui/tree/master/examples
https://lingui.js.org/index.html also has more details on this in the Guides.

Define component theming pattern

From https://github.com/ArcGIS/calcite-app-components/wiki/2019-Weekly-Meeting#2019-06-07

cc @driskull @pr3tori4n

Enhancement: Remove custom Click event in favor of native Dom Event

Description

Calcite-Action has a custom event it fires when its clicked. This can be replaced with a native event and works better in some cases than the custom event.

Acceptance Criteria

Desired New Behavior

Deprecate the use of calciteActionClick

Relevant Info

The Stencil docs encourage the use of native Dom Events on web components.

Helpful Details

Which Component: Calcite-action
Example Use Case:

<!-- Works -->
<calcite-action onClick="console.log('clicked');">
</calcite-action>
<!-- Does not work -->
<calcite-action onCalciteActionClick="console.log('clicked');">
</calcite-action>

Port wiki

https://devtopia.esri.com/WebGIS/ui-components-js/wiki

Decide release schedule + milestones

Decide release schedule + milestones

Tooling: Avoid Prettier + TSLint conflicts

Summary

There are some conflicting out-of-the-box rules from Prettier and TSLint. Conflicting ones should be disabled for a consistent formatting experience 👓 💅.

Measure of Success

Pain point: Conflicting Prettier/TSLint formatting.
Desired outcome: No warnings/errors after formatting code with either tool.

Resources (e.g. links to libraries or code snippets)

https://www.npmjs.com/package/tslint-config-prettier

Research: Sharing data between and component file and it's test files.

Background

• Brittle tests waste time and add frustration to the developer process.
• Hard coding values in a test file makes them brittle.
• A stencil component file can only contain a single export..

Desired Outcome

• What's a convention we can use to share primitive data (e.g. strings) between component files and test files?
• A single source of truth so changes in one place are reflected in both the component file and test file.

Enhancement: Add SvgIcon helper

Description

This icon pattern is showing up often in a few components:

<svg xmlns="http://www.w3.org/2000/svg" height="16" width="16" viewBox="0 0 16 16">
  <path d={ellipsis16} />
</svg>

Signifying the need for a helper to DRY up some code.

Proposal:

<SvgIcon pathData={ellipsis16} size="16" />

Acceptance Criteria

Adding a functional component to aid consume calcite-ui-icons.

Enhancement: Tip Manager - Solidify logic for add/remove behavior creating conflicts

Description

The Tip Manager responds to changes to the tips nested inside. As of now it detects additions/deletions to the list of tips. Some edge-case scenarios can arise that left unmanaged lead to a poor UX. We should nail down the best UX for these scenarios. Depending on the ideal - we may be able to consolidate code between initialLoad logic, and when one of these modifications occur.

Acceptance Criteria

Desired New Behavior

(Still needs to be finalized)

1. When tips are added or removed

   1. reset the selected tip to the first in the list. Ignore any tips that have the "selected" attribute.
      OR
   2. When tips are added and more than one has a selected attribute, select the first tip that's marked selected, or the first tip if none are marked.
   3. When tips are removed, and no tips are marked selected, select the first tip.

2. Always update the group title when the selected tip is changed.

Relevant Info

• Look for opportunities to share logic between the constructor (first load) and the mutation handler (childList change).

Helpful Details

Which Component: Tip Manager

Example Use Case:

1. A dev-user adds a new tip that has the selected attribute, creating a scenario where two tips are "selected".
2. A dev-user removes the tip that was previously selected.

Chore: Uncomment spec tests once Stencil import bug is fixed

Update the following file(s):

Tip Manager Spec File

Blocked by Stencil Issue #1669

There's a bug in Stencil where unit tests (e.g. .spect.ts files) are failing due to ES6 named imports not being properly compiled. Until that bug is fixed or a workaround is discovered, the spec tests won't be ready to uncomment.

Enhancement: Flow - Menu keyboard navigation

Description

Enhancement: Flow - Menu keyboard navigation

Acceptance Criteria (a.k.a. Requirements)

Desired New Behavior

Add ability to navigate the action menu in the Flow header by using the arrow keys.

• The escape key should close the menu
• The down arrow key should focus the next menu item and back to the first if its the last item
• The up arrow key should focus the previous menu item and to the last if its the first item
• The down arrow key on the menu button should open the menu and focus on the first item.
• The up arrow key on the menu button should open the menu and focus on the last item

Relevant Info (e.g. Dependencies, Blockers)

#6

Tooling: Automated accessibility testing

Summary

Automating base accessibility tests for each component would help keep a baseline of accessible components.

Measure of Success

Pain point: Running accessibility tests manually.
Desired outcome: Automatic testing of accessibility for all components in e2e test suite.

Resources (e.g. links to libraries or code snippets)

https://www.npmjs.com/package/jest-axe
https://www.npmjs.com/package/axe-puppeteer

New Component: calcite-flow and calcite-flow-item

API Design

<calcite-flow id="flow-control">
  <calcite-flow-panel heading="First Panel">
    <div slot="menu-actions">
      <button>Save</button>
      <button>Cancel</button>
    </div>
    <div slot="footer-actions">
      <button>Save</button>
      <button>Cancel</button>
    </div>
    <p>content 1</p>
  </calcite-flow-panel>
</calcite-flow>

calcite-flow

Methods

back() => Promise<any>

Returns

Type: Promise<any>

calcite-flow-panel

Properties

Property	Attribute	Description	Type	Default
heading	heading		string	null
labels	--		Labels	{ back: "Back", openMenu: "Open menu", closeMenu: "Close menu" }
menuOpen	menu-open		boolean	false
showBackButton	show-back-button		boolean	false

Events

Event	Description	Type
calciteFlowPanelBackClick		CustomEvent<any>
calciteFlowPanelRegister		CustomEvent<any>
calciteFlowPanelUnregister		CustomEvent<any>

Setup TypeScript and TSLint in package

Setup TypeScript and TSLint in package

Tooling: Add TSLint rule to ensure consistent spacing between class members

Summary

Automate newline formatting.

Stems from #48 (comment).

Measure of Success

Pain point: Having to manually check newline formatting.

Desired outcome: Automate newline usage between class members.

Resources (e.g. links to libraries or code snippets)

• https://palantir.github.io/tslint/rules/no-consecutive-blank-lines/
• https://github.com/chinchiheather/tslint-lines-between-class-members

cc @pr3tori4n

Tip Component - Stencil.js

Description

A dismissible window that displays information for an end-user.

User Stories

Jake

Jake is a developer who uses Calcite-components to build apps.

1. As a developer using the Calcite-tip component, I'd like the ability to control when a tip is hidden or shown programatically so I can utilize my own business logic to determine when a tip is appropriate to show or hide.
2. As a developer using the Calcite-tip component, I'd like the ability to set the tip as hidden at authoring time so I can satisfy my business reason to delay showing the tip and so the tip does not flash for a moment on page load.

Tom

Tom is an end user who is using an App that Jake built.

1. As a user who has finished reading the Tip, I'd like to be able to dismiss it so that it no longer takes up space on my screen.
2. As a user who has dismissed a Tip, I'd like the tip to stay hidden if I refresh the page so I don't have to dismiss it every time the page refreshes.

Requirements

• Default initial state of the tip component is visible.
• The tip supports accepting dynamic content at author time: thumbnail, heading, body copy and link.
• There is a mechanism for controlling the state of the tip component after initial load in code.
• There is a close button that an end-user can use to dismiss the tip.
• If the tip's state is changed either via code or by user action, the state persists after a page refresh.

Bug: Inconsistent design between Bock/Section expand icon

Summary

Bug: Inconsistent design between Bock/Section expand icon

Actual Behavior

The expanded state of the block points up.
The expanded state of the section points down.

Expected Behavior

Both state should be consistent

Reproduction Steps

1. View the block sample page

Relevant Info

Research: Modifying a custom elements light dom is not working in Edge

Background

• Web Components in Edge and IE are supported via a polyfill.
  • Stencil.js browser support notes
  • A general polyfill exists but it's unclear if Stencil uses this or something else.
• Stack Overflow Question
• Stencil Bug

Desired Outcome

• Find out if this behavior is a bug, and a fix can be expected or if it's a limitation on how much native behavior the polyfill is capable of shimming.
• Find out if there is a workaround, or if there are some best practices we can put in place that mitigate this issue.
• Find out if IE11 shares this issue.

Enhancement: Accessibility pass on components

Description

Let's take a pass an ensure our markup is semantic, and that we're using proper aria roles, labels and states.

Acceptance Criteria (a.k.a. Requirements)

Desired Change

1. All interactive elements use an appropriate tag, such as <button> or <a>

• Address styling adjustments tag changes may introduce.

1. Add aria role attributes to describe purpose, where sensible:

• role attributes to describe purpose

1. Add aria states as necessary, notably:

• aria-hidden when something is hidden/visible
• aria-disabled when something is disabled/enabled
• aria-expanded when an element is expanded/collapsed

1. Make sure aria-states get toggled by Javascript when the state changes.
2. Add aria-labels as necessary, notably:

• aria-haspopup
• aria-modal
• aria-multiselectable

Relevant Info (e.g. Dependencies, Blockers)

• https://w3c.github.io/using-aria/
• Using semantic elements can save a lot of work. If proper semantic HTML is used, the aria attributes become redundant and we can omit them.
• https://developer.mozilla.org/en-US/docs/Web/Accessibility/An_overview_of_accessible_web_applications_and_widgets

Helpful Details

Which Component: All of them should get a pass.
Example Use Case: Vision impaired person is using an app with our components via a screen-reader.
Testing process: https://arcgis.github.io/interactive-design/a11y/#/Accessibility-testing-process

Enmancement: [ActionBar] Add collapse/expand as default last calcite-action-group

Description

Add calcite-action-group justify-bottom by default with a single action to toggle the expanded attribute.

Acceptance Criteria (a.k.a. Requirements)

Desired New Behavior

• ActionBar has expand/collapse button by default.
• Dev user can disable this action.
• Dev user can still add either more actions to the bottom group or add new bottom justified groups.

Desired Change to Look and Feel

Use chevrons-left-16 and chevrons-right-16 as the icons.

Relevant Info (e.g. Dependencies, Blockers)

Helpful Details

Which Component: ActionBar

Github: Setup labels

What labels would be helpful for us? Should we have the same as the API?

New Component: List component

Description

should list all inputs and selected and check boxes.

User Stories

User wants to use this multiple select item and receive all that items as an event call back.

Acceptance Criteria (a.k.a. Requirements)

Desired Behavior

1. user should be able to see list items
2. selected options returned
3. selected state should be applied whenever selecte
4. if clicked again should unselect the item

Desired Look & Feel

Out of Scope (anything not v1)

Helpful Details

Documentation - Calcite App Components V1

Documentation for calcite-app-components V1:

• general snippet about what the component does
• methods and properties and general uses for public consumption
• note dependencies on other components

Components:

• Action
• ActionBar
• ActionPad
• Block - block content md still needs to be done but all others are done
• FloatingPanel
• FlowManager
• FlowManagerItem
• Shell
• ShellPanel
• Tip
• TipManager

Question: Should <calcite-block-section> be its own component?

Question

Should <calcite-block-section> be its own component? Currently, it's block-specific, but would there be use cases where the same design would apply in a non-block context?

Helpful Details

Topic: Possible new component.

Context: Stemmed from Block PR: #78 (comment)

cc @pr3tori4n

Github: Setup issue templates

Github: Setup issue templates

Clean up stencil.config.ts typing

#14 uses any to work around an incompatible typing from the postcss plugin. This can be removed once stencil-community/stencil-postcss#16 lands.

New Component: calcite-shell and calcite-shell-panel

Related Issue: calcite-shell component #3 and #2

Summary

Add CalciteShell and CalciteShellPanel- New Components

This is the shell or frame of the application which can house panels, content, header, footer and a floating panel.

Please see this slidedeck for proposed concept.
pass: js-frame

CalciteShellPanel

Properties

Property	Attribute	Description	Type	Default
primary	primary		boolean	false

<calcite-shell-panel primary>
    <calcite-action-bar slot="action-bar" />
    <!-- default slot -->
    <calcite-flow-control />
    <!-- /default slot -->
</calcite-shell-panel>

CalciteShell

<calcite-shell>
  <calcite-shell-panel slot="primary-panel" primary />
  <calcite-shell-panel slot="contextual-panel" />
  <h2 slot="header">My App</h2>
  <calcite-tip-manager slot="tip-manager" />
  <calcite-floating-panel slot="floating-panel" />
  <calcite-action-pad slot="action-pad" />
  <!-- default slot -->
  <div>MapView | SceneView</div>
  <!-- /default slot -->
</calcite-shell>
```https://devtopia.esri.com/WebGIS/ui-components-js/issues/5
https://devtopia.esri.com/WebGIS/ui-components-js/pull/40

Enhancement: Create unit test for position class

Description

Enhancement: Create unit test for position class

Acceptance Criteria

Unit test.

Desired New Behavior

Tests

Relevant Info

#38 (comment)

Question: rename calcite-app-components to calcite-shell-components

Question

Should we rename calcite-app-components to calcite-shell-components ?

Helpful Details

Topic: Should we rename calcite-app-components to calcite-shell-components ?
Context: calcite-app-components somewhat generic. This would narrow our components to being used with the calcite-shell. Would that be a good thing or too restrictive?

Enhancement: Tip - `dismissible` attribute experience

Description

Currently, the dismissible property on the calcite-tip component is true by default.

Issue 1: The property was not reflecting to the DOM.

Because the property wasn't reflecting to the DOM, a user wouldn't know if the tip was dismissible because the attribute was not displayed on the DOM. I think for boolean attributes, we should always reflect to the DOM if necessary. This made for some weird logic where to set the dismissible property to false, you would need to explicitly toggle the attribute.

The values "true" and "false" are not allowed on boolean attributes. To represent a false value, the attribute has to be omitted altogether.

Issue 2: I'm not sure if boolean attributes should be true by default

I'm trying to think of an example where there is a boolean attribute in HTML that is true by default. Usually, all the boolean attributes are false by default. Things like selected, disabled, readonly. I think we should probably follow the same pattern and only have boolean attributes that are false by default.

If that is the case, we should probably rename this attribute to be something that is false by default. For example,

• property:nonDismissible attribute: non-dismissible
• property:alwaysVisible attribute: always-visible

Acceptance Criteria

The boolean property is kept in sync with its value on the DOM and does not require setting a string to remove it.

Desired New Behavior

See issue 2 above.

Helpful Details

https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes#Boolean_Attributes
https://html.spec.whatwg.org/multipage/common-microsyntaxes.html#boolean-attributes

Which Component:

calcite-tip

Component: PickList and PickListItem components

A Picker component that allows for the following:

• Multiple selection
• Drag and drop reordering
• A separate "Filter" input component to allow filtering the list

Derived from: https://devtopia.esri.com/WebGIS/ui-components-js/issues/6

User Stories

User wants to use this multiple select item and receive all that items as an event call back.

Acceptance Criteria (a.k.a. Requirements)

note: These modes are tentative. @asangma needs to confirm with design
"Selection mode" means that

• select state is show using a checkbox or radio button.
• no drag-n-drop reordering
• no "edit" mode

"Configuration mode" means that

• select state is shown using the border
• drag-n-drop reordering is available
• "edit" mode is available.

Desired Behavior : end user

In "selection mode" user should be able to

• view a list of items
• view multiple lists of items
  • revealed as "groups" with headings
• select one or many items
  • CTRL / SHFT?
• deselect one or many items
  • CTRL / SHFT?
• know what items are selected
• know whether she can select one or many items
• have access to either a secondary action or additional visual distinction (i.e. icon/graphic)
  • e.g. "more info about this item"
  • icon
  • some graphic

In "configure mode" user should be able to

• toggle one or many items
• know what items are toggled
• have access to either a secondary action or additional visual distinction (i.e. icon/graphic)
  • e.g. "more info about this item"
  • icon
  • some graphic
• remove items
• reorder items via drag and drop (nice to have)

Desired Behavior : developer

Developer should be able to

• get a return of selected items
• apply selected state to items
• allow user to toggle selection on one or many items
• update what items are in a list
• set list to be multi or single select
• set list to be in "configuration" or "selection" mode

API Desgin

calcite-picker

Interface

interface CalcitePicker {

  @Prop({ reflect: true }) textHeading: string;

  @Prop({ reflect: true }) mode: "selection" | "configuration" = "selection";

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

  @Prop({ reflect: true }) dragEnabled = false; /* ignored unless mode is configuration */

  @Prop({ reflect: true }) editEnabled = false; /* ignored unless mode is configuration */

  @Prop({ reflect: false }) data = [];

  @Event() calcitePickerSelectionChanged: EventEmitter;

  @Method() getSelectedRows()
}

<calcite-picker mode="configuration" multiple="true" dragEnabled="true">
  <!-- rows -->
</calcite-picker>

calcite-picker-group

interface CalcitePickerGroup {
  @Prop({ reflect: true }) textGroupTitle: string;
}

calcite-picker-row

interface CalcitePickerRow {
  @Prop() heading: string;

  @Prop() description: string;

  @Prop() value: string;

  @Prop() selected = false;

  @Prop({ reflect: true }) icon: "square" | "circle" | "grip" | null = null;
}

<calcite-picker-row heading="hello world" description="hi" selected value="helloWorld">
  <calcite-action slot="secondaryAction"></calcite-action>
  <calcite-action slot="editAction"></calcite-action>
</calcite-picker-row>

calcite-filter-input

interface CalciteFilterInput {
  @Prop() heading: string;

  @Prop() data: Array<Object>;

  @Event() calciteFilterChange: EventEmitter;
}

<calcite-filter-input heading="search" onCalciteFilterChange="">
</calcite-filter-input>

Setup autoprefixer

Setup autoprefixer

Multi Select Menu for Charts

@asangma for now let this stay in app components if there is a need we can port this to calcite-components. Please add spec for this along with mike here.

Enhancement: use `textString` as `@Prop` for all strings (text-string)

Description

Enhancement: use textString as @Prop for all strings

Acceptance Criteria (a.k.a. Requirements)

Desired New Behavior

Currently, we use @Prop labels or the like for strings. Now, each string should be its own property starting with text for example textClose

Relevant Info (e.g. Dependencies, Blockers)

Teams discussion:

https://teams.microsoft.com/l/message/19:[email protected]/1561150486797?tenantId=aee6e3c9-711e-4c7c-bd27-04f2307db20d&groupId=56fae21a-9407-4943-859f-a9bfcf0bbad3&parentMessageId=1561150486797&teamName=Calcite&channelName=Calcite%20Components&createdTime=1561150486797

Research: Automated CHANGELOG/BREAKING_CHANGES doc generation

Background

For documentation purposes, it would be useful to have an automated way of keeping track of changes/breaking changes.

Desired Outcome

CHANGELOG.md and/or BREAKING_CHANGES.md auto generated from, ideally, commit messages.

Action & ActionBar - Stencil.js

This is installed and ready for styling

calcite-action

Properties

Property	Attribute	Description	Type	Default
active	active		boolean	false
indicator	indicator		boolean	false
label	label		string	null
text	text		string	null
textEnabled	text-enabled		boolean	false

Events

Event	Description	Type
calciteActionClick		CustomEvent<any>

calcite-action-bar

Properties

Property	Attribute	Description	Type	Default
expanded	expanded		boolean	false

---

New Component: Tip Manager

Description

A container for tips that allows you to scroll through one tip at a time, similar to a carousel.

User Stories

Jake

Jake is a developer who uses Calcite-components to build apps.

1. As an app developer, I want a tip bucket where I can add general purpose tips that don't fit elsewhere in the app.

Tom

Tom is an end user who is using an App that Jake built.

1. As an end user, I want to be able to see tips I've dismissed elsewhere so I still have access to those tips.
2. As an end user, I want to be able to see the full bucket of tips, so I can learn about various parts of the app.
3. As an end user, I want to be able to navigate through the tips so I can skip some and/or go back.
4. As an end user, I want to be able to dismiss the window once I'm done reading so it stops taking up screen space.

Acceptance Criteria (a.k.a. Requirements)

Desired Behavior

• Container that contains multiple tips (e.g. calcite-tip component)
• Supports a title for the group of tips.
  • Tip manager supports multiple tip groups.
• Dismissible via a close button.
• Pagination exists to go to 'next' or 'prev' tips.
  • Shows the current tip and the total tips.
  • Is revolving( ex..: clicking next on the last tip cycles back to the first.)

Desired Look & Feel

• Tip Manager content area has a max-height. If tip is taller, user should see a vertical scrollbar.

Other Information

Link to old Tip Manager in React

Tooling: Add Component example

Summary

Create example Component

Measure of Success

Pain point: We should have an example class we can use for creating a new components. we can define how the class is organized and how the parts are grouped with comments.
Desired outcome: A clean simple example gist or file we can use.

...