Step components

change/@ni-nimble-components-0f9f3301-9f8e-4a37-9bd5-bcfd51aa944e.json

@@ -0,0 +1,7 @@
+{
+  "type": "patch",
+  "comment": "step and anchor-step",
+  "packageName": "@ni/nimble-components",
+  "email": "1588923+rajsite@users.noreply.github.com",
+  "dependentChangeType": "patch"
+}

packages/nimble-components/docs/css-guidelines.md

@@ -108,9 +108,11 @@ Some takeaways from the example:
 
 ## Prefer cascade for state changes
 
-If you find yourself in complex logic with lots of `:not()` selectors it's possible the code should be reorganized to leverage the CSS cascade for overriding states.
+Avoid using [`:not()` selectors](https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/Selectors/:not) or [selector lists](https://developer.mozilla.org/en-US/docs/Web/CSS/Guides/Selectors/Selector_structure#selector_list) (`#main, .content {}`) and instead rely on CSS cascade for overriding states. This will likely result in groups of properties being duplicated across multiple selectors and that is desired and expected.
+
+Each selector should represent a single, clear state of the control and define a minimal set of properties that override the base configuration of the control. Duplicated property values are avoided by using well-named design tokens or private css custom properties.
 
-States should flow from plain control -> hover -> focus -> active -> error -> disabled (which overrides all the others).
+States should flow from plain control -> hover -> focus -> active -> disabled (which overrides all the others).
 
 For example:
 
@@ -119,8 +121,6 @@ For example:
 :host(:hover) {}
 :host(${focusVisible}) {} /* focusVisible is specific to FAST */
 :host(:active) {}
-:host(:invalid) {}
-:host(.custom-state) {}
 :host([disabled]) {} /* disabled styles override all others in the cascade*/
 ```
 
@@ -131,20 +131,26 @@ Useful reference: [When do the :hover, :focus, and :active pseudo-classes apply?
 New controls and existing controls undergoing major refactoring should migrate to [CSS Cascade Layers with `@layer`](https://developer.mozilla.org/en-US/docs/Web/CSS/@layer) for organizing styles that override states. Cascade Layers with `@layer` define the order of precedence when multiple cascade layers are present. This helps enforce that property overrides have higher specificity over base styles without needing to modify selectors to increase specificity.
 
 For consistency, control styles using CSS Cascade Layers should follow these practices:
--   Define the cascade layers: `@layer base, hover, focusVisible, active, disabled, top`
-    -   Avoid changing the order of layers, changing layer names, or creating additional layers.
--   Layers in the stylesheet should follow the order by which they are defined above.
--   Ensure that all styles are in a layer; no styles for the control should be outside of a layer.
--   Styles in layers should continue to follow existing best organization practices, including grouping using document order.
+- Define the following cascade layers list exactly: `@layer base, hover, focusVisible, active, disabled, top;`
+  - The cascade layers list should be the first style defined in a control's top-level `css`.
+  - Avoid changing the order of layers, changing layer names, or creating additional layers.
+- Layers in the stylesheet should follow the order by which they are defined above.
+- Ensure that all styles are in a layer; no styles for the control should be outside of a layer.
+  - This includes leveraging shared styles that are imported. Note: imported styles must be shared as `cssPartial` instead of as a top-level `css` to be used in a layer.
+  - Custom states, like `appearance`, `checked`, etc. should be configured within one of the existing layers (likely in `base` with interaction overrides in different layers).
+- Styles in layers should continue to follow existing best organization practices, including grouping using document order.
 
 For example:
 ```css
-@layer base, hover, focusVisible, active, disabled, top
+@layer base, hover, focusVisible, active, disabled, top;
 
 @layer base {
     :host {
         border: green;
     }
+    :host([custom-state]) {
+        border: violet;
+    }
 }
 @layer hover {}
 @layer focusVisible {}
@@ -153,6 +159,9 @@ For example:
     :host([disabled]) {
         border: gray;
     }
+    :host([disabled][custom-state]) {
+        border: darkviolet;
+    }
 }
 @layer top {}
 ```

packages/nimble-components/src/anchor-step/index.ts

@@ -1,6 +1,12 @@
-import { DesignSystem, FoundationElement } from '@ni/fast-foundation';
+import { DesignSystem, type AnchorOptions } from '@ni/fast-foundation';
+import { attr, nullableNumberConverter } from '@ni/fast-element';
 import { styles } from './styles';
 import { template } from './template';
+import { AnchorBase } from '../anchor-base';
+import { mixinSeverityPattern } from '../patterns/severity/types';
+import type { StepPattern } from '../patterns/step/types';
+import { StepInternals } from '../patterns/step/models/step-internals';
+import { AnchorStepSeverity } from './types';
 
 declare global {
     interface HTMLElementTagNameMap {
@@ -11,12 +17,60 @@ declare global {
 /**
  * A nimble-styled anchor step for a stepper
  */
-export class AnchorStep extends FoundationElement {}
+export class AnchorStep extends mixinSeverityPattern(AnchorBase) implements StepPattern {
+    /**
+     * @public
+     * @remarks
+     * HTML Attribute: disabled
+     */
+    @attr()
+    public severity: AnchorStepSeverity = AnchorStepSeverity.default;
 
-const nimbleAnchorStep = AnchorStep.compose({
+    /**
+     * @public
+     * @remarks
+     * HTML Attribute: disabled
+     */
+    @attr({ mode: 'boolean' })
+    public disabled = false;
+
+    /**
+     * @public
+     * @remarks
+     * HTML Attribute: readonly
+     */
+    @attr({ attribute: 'readonly', mode: 'boolean' })
+    public readOnly = false;
+
+    /**
+     * @public
+     * @remarks
+     * HTML Attribute: selected
+     */
+    @attr({ mode: 'boolean' })
+    public selected = false;
+
+    /**
+     * @public
+     * @remarks
+     * HTML Attribute: tabindex
+     */
+    @attr({ attribute: 'tabindex', converter: nullableNumberConverter })
+    public override tabIndex!: number;
+
+    /**
+     * @internal
+     */
+    public readonly stepInternals = new StepInternals();
+}
+
+const nimbleAnchorStep = AnchorStep.compose<AnchorOptions>({
     baseName: 'anchor-step',
     template,
-    styles
+    styles,
+    shadowOptions: {
+        delegatesFocus: true
+    }
 });
 
 DesignSystem.getOrCreate().withPrefix('nimble').register(nimbleAnchorStep());

packages/nimble-components/src/anchor-step/styles.ts

@@ -1,6 +1,12 @@
 import { css } from '@ni/fast-element';
-import { display } from '../utilities/style/display';
+import { styles as stepStyles } from '../patterns/step/styles';
 
 export const styles = css`
-    ${display('flex')}
+    ${stepStyles}
+    ${'' /* Anchor specific styles */}
+    @layer base {
+        .control {
+            text-decoration: none;
+        }
+    }
 `;

packages/nimble-components/src/anchor-step/template.ts

@@ -1,6 +1,68 @@
-import { html } from '@ni/fast-element';
+import { html, ref, slotted, ViewTemplate } from '@ni/fast-element';
+import { type FoundationElementTemplate, type AnchorOptions, startSlotTemplate, endSlotTemplate } from '@ni/fast-foundation';
 import type { AnchorStep } from '.';
+import { severityTextTemplate } from '../patterns/severity/template';
 
-export const template = html<AnchorStep>`
-    <template>anchor step</template>
+export const template: FoundationElementTemplate<
+ViewTemplate<AnchorStep>,
+AnchorOptions
+> = (context, definition) => html<AnchorStep>`
+    <template slot="step">
+        <div class="
+            container
+            ${x => (x.stepInternals.orientation === 'vertical' ? 'vertical' : '')}
+            ${x => (x.stepInternals.last ? 'last' : '')}
+        ">
+            <a
+                class="control"
+                part="control"
+                download="${x => x.download}"
+                href=${x => (x.disabled ? null : x.href)}
+                hreflang="${x => x.hreflang}"
+                ping="${x => x.ping}"
+                referrerpolicy="${x => x.referrerpolicy}"
+                rel="${x => x.rel}"
+                target="${x => x.target}"
+                type="${x => x.type}"
+                tabindex="${x => x.tabIndex}"
+                aria-atomic="${x => x.ariaAtomic}"
+                aria-busy="${x => x.ariaBusy}"
+                aria-controls="${x => x.ariaControls}"
+                aria-current="${x => x.ariaCurrent}"
+                aria-describedby="${x => x.ariaDescribedby}"
+                aria-details="${x => x.ariaDetails}"
+                aria-disabled="${x => x.ariaDisabled}"
+                aria-errormessage="${x => x.ariaErrormessage}"
+                aria-expanded="${x => x.ariaExpanded}"
+                aria-flowto="${x => x.ariaFlowto}"
+                aria-haspopup="${x => x.ariaHaspopup}"
+                aria-hidden="${x => x.ariaHidden}"
+                aria-invalid="${x => x.ariaInvalid}"
+                aria-keyshortcuts="${x => x.ariaKeyshortcuts}"
+                aria-label="${x => x.ariaLabel}"
+                aria-labelledby="${x => x.ariaLabelledby}"
+                aria-live="${x => x.ariaLive}"
+                aria-owns="${x => x.ariaOwns}"
+                aria-relevant="${x => x.ariaRelevant}"
+                aria-roledescription="${x => x.ariaRoledescription}"
+                ${ref('control')}
+            >
+                <div class="icon">
+                    <slot ${slotted('defaultSlottedContent')}></slot>
+                </div>
+                <div class="content">
+                    <div class="title-wrapper">
+                        ${startSlotTemplate(context, definition)}
+                        <div class="title"><slot name="title"></slot></div>
+                        ${endSlotTemplate(context, definition)}
+                        <div class="line"></div>
+                    </div>
+                    <div class="subtitle">
+                        <slot name="subtitle"></slot>
+                    </div>
+                </div>
+            </a>
+            ${severityTextTemplate}
+        </div>
+    </template>
 `;

packages/nimble-components/src/anchor-step/types.ts

@@ -0,0 +1,4 @@
+import { Severity } from '../patterns/severity/types';
+
+export const AnchorStepSeverity = Severity;
+export type AnchorStepSeverity = (typeof AnchorStepSeverity)[keyof typeof AnchorStepSeverity];

packages/nimble-components/src/anchor/styles.ts

@@ -12,7 +12,7 @@ import {
 } from '../theme-provider/design-tokens';
 
 export const styles = css`
-    @layer base, hover, focusVisible, active, disabled;
+    @layer base, hover, focusVisible, active, disabled, top;
 
     @layer base {
         ${display('inline')}

packages/nimble-components/src/breadcrumb-item/styles.ts

@@ -14,7 +14,7 @@ import {
 import { focusVisible } from '../utilities/style/focus';
 
 export const styles = css`
-    @layer base, hover, focusVisible, active, disabled;
+    @layer base, hover, focusVisible, active, disabled, top;
 
     @layer base {
         ${display('inline-flex')}

packages/nimble-components/src/patterns/severity/styles.ts

@@ -0,0 +1,42 @@
+import { cssPartial } from '@ni/fast-element';
+import {
+    failColor,
+    errorTextFontLineHeight,
+    warningColor,
+    errorTextFont,
+    buttonLabelFontColor
+} from '../../theme-provider/design-tokens';
+
+// These styles end up inside a @layer block so must use the
+// cssPartial tag instead of the css tag
+export const styles = cssPartial`
+    .severity-text {
+        display: none;
+    }
+
+    .severity-text {
+        display: block;
+        font: ${errorTextFont};
+        color: ${buttonLabelFontColor};
+        width: 100%;
+        position: absolute;
+        ${'' /* The -2px modifier of the bottom position is to intentionally have the severity text slightly overlap the control by 2px */}
+        bottom: calc(-1 * (${errorTextFontLineHeight} - 2px));
+        left: 0px;
+        overflow: hidden;
+        text-overflow: ellipsis;
+        white-space: nowrap;
+    }
+
+    :host([severity="error"]) .severity-text {
+        color: ${failColor};
+    }
+
+    :host([severity="warning"]) .severity-text {
+        color: ${warningColor};
+    }
+
+    :host([severity]) .severity-text:empty {
+        display: none;
+    }
+`;

packages/nimble-components/src/patterns/severity/template.ts

@@ -0,0 +1,14 @@
+import { html } from '@ni/fast-element';
+import type { SeverityPattern } from './types';
+import { overflow } from '../../utilities/directive/overflow';
+
+export const severityTextTemplate = html<SeverityPattern>`
+    <div
+        class="severity-text"
+        ${overflow('severityHasOverflow')}
+        title="${x => (x.severityHasOverflow && x.severityText ? x.severityText : undefined)}"
+        aria-live="polite"
+    >
+        ${x => x.severityText}
+    </div>
+`;

packages/nimble-components/src/patterns/severity/testing/severity-pattern.pageobject.ts

@@ -0,0 +1,41 @@
+import type { FoundationElement } from '@ni/fast-foundation';
+import { processUpdates } from '../../../testing/async-helpers';
+
+/**
+ * A page object for the elements that use the error pattern mixin.
+ */
+export class SeverityPatternPageObject {
+    public constructor(private readonly element: FoundationElement) {}
+
+    public getDisplayedSeverityText(): string {
+        const severityTextDiv = this.getSeverityTextElement();
+        if (
+            !severityTextDiv
+            || getComputedStyle(severityTextDiv).display === 'none'
+        ) {
+            return '';
+        }
+        return severityTextDiv.textContent?.trim() ?? '';
+    }
+
+    public getSeverityTextTitle(): string {
+        const severityTextDiv = this.getSeverityTextElement();
+        if (!severityTextDiv) {
+            throw new Error('Severity text element not found');
+        }
+        return severityTextDiv.title;
+    }
+
+    public dispatchEventToSeverityText(event: MouseEvent): void {
+        const severityTextDiv = this.getSeverityTextElement();
+        if (!severityTextDiv) {
+            throw new Error('Severity text element not found');
+        }
+        severityTextDiv.dispatchEvent(event);
+        processUpdates();
+    }
+
+    private getSeverityTextElement(): HTMLDivElement | null {
+        return this.element.shadowRoot!.querySelector('.severity-text');
+    }
+}