Skip to content

epic incubator

Jump to bottom
Ben Elan edited this page Oct 16, 2024 · 1 revision

Issue Template

Title: Epic: <description>

Body:

### Background

<!-- details -->

### Plan of action

<!-- List of key tasks with detail (subtasks are useful too) -->

- [ ] <task breakdown>

Epics

1.0.0

Update list-item-like (need a better term) components to use action, content and default slot patterns - https://github.com/Esri/calcite-design-system/issues/2884

Until we officially name this pattern, this draft will refer to it as the SangmaTemplate™ (ST)

Terminology

  • default slot - an unnamed slot that is used to place any children appended to the component (this is external to the ST)
  • default content - the content that should be rendered by default by a component (e.g., heading/summary in a list item)
  • content slot - the "content"-named slot that provides the root interactive component for the hit area, it can be replaced entirely by the user

Template structure

The ST defines 3 main areas:

  • start actions (optional) -
  • content area (required) – this provides the hit area for interactions, this should be a "content"-named slot where the component's default content resides. Other than the default content's root, no other component inside must be interactive. It may have the following slots:
    • start content (optional)
    • end content (optional)
  • end actions (optional)

Here's a simplified example of the template to showcase the slots:

<div class="template-container">
  <slot name="actions-start"></slot>
  <slot name="content">
    <button>
      <slot name="content-start"></slot>
      {/* default content */}
      <slot name="content-end"></slot>
    </button>
  </slot>
  <slot name="actions-end"></slot>
</div>

The component design will determine whether the start/end action areas are needed.

Convenience content properties

Components implementing ST, may have convenience content properties wherever applicable to enable users to quickly set content that follows design guidelines. Examples of these are, heading, summary or icon. Note: these convenience properties are external to the template and more of a pattern for components to apply.

As we apply ST, some existing properties may surface as redundant and could be deprecated. Any instances of this should be marked and considered for deprecation.

Built-in styling for known components

To aid design consistency, action slots will include styling for the following components:

  • calcite-action
  • calcite-handle
  • calcite-icon

The default styling should exclusively consist of padding and alignment

Protecting internal slotted content ⚠️

In some cases, a component may use a slot from ST internally to provide default content that should not be replaced when the user slots content. For these cases, the component must slot elements internally and not use default slot content.

[JCF] ⚠️ Not feasible without rearranging the DOM, impacts user-provided content by adding nodes to the light DOM, which is user-controlled - possibly could be achieved via 'internal'/'private' slots (pending design approval)

Pending clarification/discussion/questions

  • Confirm internal content protection story – need for internal content to be overrideable or to provide internal-only content/action slots

  • When users add elements into the "content", they are in charge of styling, focusing and interaction. In order to help content look consistently, we should provide helper components. So far, we only need a heading component for the title and description layout and styling used by many components.

  • value-list will need to revisit its selection state to adopt ST and not introduce visual dissonance (focused item that is selected would show two slightly overlapping outlines)

    • proposal: use leading, selection indicator instead of an outline on the item

  • confirm whether start/end content slots need to be preserved when user slots into "content", if so, we can't support this workflow

  • What are we officially naming this pattern? It'll help with documentation, utilities and tests.

  • Can we define the approach for the proposed included styles for known slotted components? updated in draft ✅

  • Which props are proposed for deprecation? will need to keep track of anything that sticks out ✅

  • Can we audit all components to ensure we support this across the board?

  • Will the "content" slot always have default content?

  • If a "content" slot has default content and a user slots in anything, the default will be overridden. What is the plan to match styling? https://github.com/Esri/calcite-design-system/issues/3032

    • Is it tailwind tokens?
    • Helper components? **the common pattern seems to be for headers (header/summary), so a helper component may be useful and will allow us to bundle functionality (a11y, etc)**✅
    • Simplify styling to lessen impact of this case?

  • If the content area is not interactive, can we define the extent of this? It impacts issues like this https://github.com/Esri/calcite-design-system/issues/2878 & https://github.com/Esri/calcite-design-system/issues/2141 (has alternative path for issue)

  • Can we clarify Content props vs feature/state props?

  • icon slot is separate, but related (see https://github.com/Esri/calcite-design-system/issues/2884) Do we need to include in this effort? let's tackle this separately as not all icons are placed within STs

  • Would this approach also fit https://github.com/Esri/calcite-design-system/issues/1786? Namely, how does the trailing icon (interactive) in accordion-item factor into this structure?

  • Any guidelines to what can and cannot be slotted into the content area? For example, if we slot in interactive components, how will focusing work there? slotting into the "content" slot means the user will determine how the component handles focus (if applicable) ✅

  • Can we confirm the listed components from https://github.com/Esri/calcite-design-system/issues/2884

    • Action
    • Avatar
    • Button
    • Chip
    • FAB
    • Radio Group Item
    • Tab Title
    • Notice

Tasks

  • update components to adopt ST (need list)
    • add component utility to generate the template (should be tackled before updating other components)
    • keep track of any potential redundant convenience props
  • audit redundant convenience props and deprecate
  • update value-list to follow revisited selection state (separate, but ideally in the same milestone)
  • create header helper component (later)

Issue Template

Title: Epic: consistent content/action slot approach for flexibility

Body:

### Background

#### Goals

* Reduce property bloat.
* Standardize props.
* Standardize slots.
* Standardize how hit areas (hover, etc.) work.
* Enable flexibility.*

*Flexibility risks bad choices. We will need to clearly doc the dos/dont's in the SDK to avoid misusage

#### Prop vs slot

* Use props for simple string content, e.g. “heading”, “summary”, “title”, etc.
* Use slots for rich content including our own components.
* Review places where we disallow the default slot.

#### Plan

* Refactor components to use slots when adding external* content.
* For now, retain existing properties, e.g. “icon-start” in Button or “icon” in Action.
* Let those properties remain as convenience properties and consider for deprecation on a case-by-case basis.
* Users can access the related slots.
* Components will include styles for known ::slotted components.

*”external” as in external to the particular component.

#### Content props vs feature/state props

Some indicate enabling a feature or activating a state and don’t explicitly indicate adding/removing content, e.g. “removable” in ValueListItem.
These properties can also benefit from using standardized slots.

#### Action slot vs content slot

A “content” slot would be included inside a component's default hit area.

It is intended for content that is decorative/indicative and probably doesn’t need its own hit area.

Button retains its properties.
It uses those slots to place the icon and set the proper scale.

Users can opt to use the slot if they need to add something other than a CalciteIcon.

Using that slot would supercede the related property.

An “action” slot would be included outside the default hit area to allow it to have its own hit area.

This is intended for components that need more complex interactions.

Button also has action slots that we can use internally for `SplitButton`.

Again, users can use these slots as needed.

### Plan of action

<!-- List of key tasks with detail (subtasks are useful too) -->

- [ ] provide utils to facilitate rendering of content/action slot structure
- [ ] update the following components to kick this off:
  - [ ] accordion-item https://github.com/Esri/calcite-design-system/issues/1786
  - [ ] alert https://github.com/Esri/calcite-design-system/issues/2382
  - [ ] list-item https://github.com/Esri/calcite-design-system/issues/3032 (new `content` slot per updated Figma)
  - [ ] pick-list-item https://github.com/Esri/calcite-design-system/issues/3334 (refactoring to use calcite-list would fix this)
  - [ ] value-list-item  (refactoring to use calcite-list would fix this)
  - [ ] tile https://github.com/Esri/calcite-design-system/issues/3462
  - [ ] tree-item  https://github.com/Esri/calcite-design-system/issues/3127
- [ ] audit additional components that need to be updated to follow this pattern
- [ ] doc for this pattern may influence https://github.com/Esri/calcite-design-system/issues/3097

🚧 Consistent form value access/patterns - ensure form/value components have consistent APIs for a better dev experience

  • Audit relevant components and compare APIs
  • Propose consistent pattern/approach

First pass addressed in https://github.com/Esri/calcite-design-system/pull/2777, needs audit

Issue draft

Title: Epic: Consistent form value access/patterns

Body:

### Background

<!-- details -->

We have a few components that provide access to their value in different ways:

1. `value` property
1. `selectedItem`/`selectedItems` property
1. `selected` property on an a selected item

For consistency, form/value components should expose their associated value following the same pattern.

### Plan of action

<!-- List of key tasks with detail (subtasks are useful too) -->

- [ ] audit relevant components and compare APIs
- [ ] research value-access pattern
- [ ] document agreed-upon pattern from ☝
- [ ] update components <list depends on audit and pattern>

[ongoing 🚧 – needs updated audit] a11y improvements

  • Review a11y report to determine tasks/priorities
  • Review existing issues on repository

Issue draft

Title: Epic: a11y improvements

Body:

### Background

<!-- details -->

Accessibility is a key concern of this project and we have identified some key items to address before 1.0.0.

We will continue to make improvements, but the following list should be tackled before releasing.

### Plan of action

<!-- List of key tasks with detail (subtasks are useful too) -->

- [ ] <violation - should have an issue linked with more breakdown>

Sample apps

  • 3 sample apps
  • Code and doc on CDS site

Documentation sites

  • All components need usage samples
  • All components need a code/visual preview
  • Consistent usage samples
  • (post 1.0) Tone and voice: copy, need a technical writer

Issue draft

Title: `Epic: Consistent usage, slot, and property documentation`

Body:

### Background

Currently a lot of components do not have usage examples, are missing default slots, and have wording and syntax inconsistencies.

### Plan of action

Missing examples, slots, and (maybe) properties need to be added. The existing documentation needs to be consistent.

- [ ] Add missing default slots - #2974
- [ ] Make sure the wording and syntax is consistent (sentence case, verb tense, default slots have a dash e.g. `@slot - xyz`, etc)
- [ ] Add usage examples for all components - #2860
- [ ] Make sure the existing usage examples are up to date
- [ ] Make sure the properties are up to date and consistent

Full testing for components [ongoing 🚧]

  • Automated testing on all components and variations (Screener)

intl/i18n support – improve usage by not requiring translation strings from end-users

  • Find stable, lightweight library to handle translation
  • Define pattern on how to set up bundles per component (follow date-picker approach?)
  • Need automated process to update translation files

Framework integration

  • Provide doc
  • Set up as monorepo
  • Make repo public
  • Patch React output-target to fix Boolean bug?
  • (post 1.0) enable all output targets from stencil-ds-output-targets for seamless integration story

event payload typing

  • Audit custom event payload (could happen before 1.0.0)
  • Determine which ones are not needed (i.e., already have a prop on the component or should have a prop for it) and make internal (could happen before 1.0.0)
  • Only doc and type the ones that don’t have and won’t get a custom prop

event cancelation

  • Audit custom events to see which ones would be need to be made cancelable
  • Should define guidelines on when an event needs to be cancelable

Post 1.0.0+

Deprecate Sass in favor of PostCSS + Tailwind CSS

  • List pros/cons
  • List steps to get started on the work/migration
  • Ensure we don't lose any leveraged feature in the process
  • Ensure dependencies are updated first

Consistent boolean naming - https://github.com/Esri/calcite-design-system/issues/2115

  • Define rule on how to name booleans (could extend to methods, others?)
  • Update components to comply with rule
  • If we do this after 1.0.0, we would need to deprecate and keeping extra props along for a few releases.

splitting input to type-specific components

  • Deprecate calcite-input
  • List which type-specific components we need
  • Keep calcite-input deprecated until we tackle all type-specific ones

validation

  • Consistent UI/UX for components that support validation
  • Provide similar APIs to HTMLInputElement (e.g., validity, validationMessage, etc...)

layout components

TBD (this may no longer be needed if we provide tailwind util classes)

responsive/mobile support

  • Audit components to identify changes needed based on different viewport sizes
  • Identify best approach for adjusting components styles based on viewport (I.e., media queries)

simplify project structure

  • Nest supporting components?

test speeding up - https://github.com/Esri/calcite-design-system/issues/2877

Done

✅ Consistent Shadow DOM usage - https://github.com/Esri/calcite-design-system/issues/2570

  • Audit components not using shadow DOM ☑
  • Define consistent calcite-label clicking approach
  • Define consistent form-submitting approach
  • Define approach for a11y between label & components

Addressed in https://github.com/Esri/calcite-design-system/pull/2777

simplify project structure

  • ✅ Drop calcite- prefix as it won't affect build output

Addressed in https://github.com/Esri/calcite-design-system/pull/3804

Home

Tokens

Clone this wiki locally