Merge branch 'main' into rajdeep/SWC-1018

Author: Rajdeepc

.changeset/fix-color-wheel-step.md

@@ -0,0 +1,5 @@
+---
+'@spectrum-web-components/color-wheel': patch
+---
+
+Fixed `<sp-color-wheel>` step attribute functionality for keyboard navigation. The step attribute now properly controls the increment size when using arrow keys to navigate the color wheel.

.changeset/four-lions-enjoy.md

@@ -0,0 +1,7 @@
+---
+'@spectrum-web-components/menu': minor
+---
+
+**Fixed** : Fix iPad scrolling issue in picker dropdown where scrolling through menu items would accidentally select the first touched item and close the picker.
+
+The fix implements touch gesture detection to distinguish between scrolling and selection. Added `isScrolling` getter for public API access. Test on iPad devices with long menus to validate scrolling behavior and selection accuracy.

.changeset/plenty-eyes-mate.md

@@ -0,0 +1,7 @@
+---
+'@spectrum-web-components/contextual-help': patch
+---
+
+Fixed a typo in the default `info` variant label from "Informations" to "Information".
+
+Additionally, added package dependency for `@spectrum-web-components/[email protected]`.

.circleci/config.yml

@@ -22,7 +22,7 @@ parameters:
     # 3. Commit this change to the PR branch where the changes exist.
     current_golden_images_hash:
         type: string
-        default: dd2217ab088b6a78c6d95aa4751396726f24fa0f
+        default: e919c253a7cb75ee16c0ef680b50a032236f7275
     wireit_cache_name:
         type: string
         default: wireit

.eslintrc.json

@@ -16,6 +16,15 @@
             "extends": ["plugin:jsonc/recommended-with-jsonc"],
             "files": ["*.json"],
             "parser": "jsonc-eslint-parser",
+            "rules": {
+                "jsonc/sort-keys": ["warn"],
+                "notice/notice": "off"
+            }
+        },
+        {
+            "extends": ["plugin:jsonc/recommended-with-jsonc"],
+            "files": ["package.json"],
+            "parser": "jsonc-eslint-parser",
             "rules": {
                 "jsonc/sort-keys": [
                     "warn",
@@ -65,14 +74,18 @@
                             "cpu",
                             "publishConfig"
                         ],
-                        "pathPattern": ".*" // Hits the all properties
+                        "pathPattern": "^$" // Top-level properties
                     },
                     {
+                        /*
+                         * This rule excludes export conditions from alphabetical sorting.
+                         * Since node.js processes export conditions in order and chooses the
+                         * first match, they need to be ordered logically, not alphabetically.
+                         */
                         "order": { "type": "asc" },
-                        "pathPattern": ".*"
+                        "pathPattern": "^(?!exports\\[).*" // All properties except export conditions
                     }
-                ],
-                "notice/notice": "off"
+                ]
             }
         },
         {

packages/.eslintrc.json

@@ -134,6 +134,15 @@
             "extends": ["plugin:jsonc/recommended-with-jsonc"],
             "files": ["*.json"],
             "parser": "jsonc-eslint-parser",
+            "rules": {
+                "jsonc/sort-keys": ["warn"],
+                "notice/notice": "off"
+            }
+        },
+        {
+            "extends": ["plugin:jsonc/recommended-with-jsonc"],
+            "files": ["package.json"],
+            "parser": "jsonc-eslint-parser",
             "rules": {
                 "jsonc/sort-keys": [
                     "warn",
@@ -183,14 +192,18 @@
                             "cpu",
                             "publishConfig"
                         ],
-                        "pathPattern": ".*" // Hits the all properties
+                        "pathPattern": "^$" // Top-level properties
                     },
                     {
+                        /*
+                         * This rule excludes export conditions from alphabetical sorting.
+                         * Since node.js processes export conditions in order and chooses the
+                         * first match, they need to be ordered logically, not alphabetically.
+                         */
                         "order": { "type": "asc" },
-                        "pathPattern": ".*"
+                        "pathPattern": "^(?!exports\\[).*" // All properties except export conditions
                     }
-                ],
-                "notice/notice": "off"
+                ]
             }
         }
     ]

packages/avatar/README.md

@@ -1,30 +1,36 @@
-## Description
+## Overview
 
-An `<sp-avatar>` is a great way to feature a visual representation of a user.
+An `<sp-avatar>` is a thumbnail representation of an entity, such as a user or an organization. Avatars can have a defined image, which is usually uploaded by a user.
+
+[View the design documentation for this component.](https://spectrum.adobe.com/page/avatar/)
 
 ### Usage
 
 [![See it on NPM!](https://img.shields.io/npm/v/@spectrum-web-components/avatar?style=for-the-badge)](https://www.npmjs.com/package/@spectrum-web-components/avatar)
 [![How big is this package in your project?](https://img.shields.io/bundlephobia/minzip/@spectrum-web-components/avatar?style=for-the-badge)](https://bundlephobia.com/result?p=@spectrum-web-components/avatar)
 [![Try it on Stackblitz](https://img.shields.io/badge/Try%20it%20on-Stackblitz-blue?style=for-the-badge)](https://stackblitz.com/edit/vitejs-vite-swzc3ix8)
 
-```
+```zsh
 yarn add @spectrum-web-components/avatar
 ```
 
 Import the side effectful registration of `<sp-avatar>` via:
 
-```
+```js
 import '@spectrum-web-components/avatar/sp-avatar.js';
 ```
 
 When looking to leverage the `Avatar` base class as a type and/or for extension purposes, do so via:
 
-```
+```js
 import { Avatar } from '@spectrum-web-components/avatar';
 ```
 
-## Sizes
+### Options
+
+#### Sizes
+
+Avatar sizes scale exponentially, based on the Spectrum type scale. These range from `size-50` to `size-700`. An avatar can also be customized to fit appropriately for your context. The default size is `size-100`.
 
 <sp-tabs selected="100" auto label="Size Attribute Options">
 <sp-tab value="50">50</sp-tab>
@@ -137,6 +143,16 @@ import { Avatar } from '@spectrum-web-components/avatar';
 </sp-tab-panel>
 </sp-tabs>
 
-## Accessibility
+### States
+
+#### Generic avatars
+
+Use branded generic avatars when a user has not set their avatar image. These images are designed to be abstracted from all genders, locales, and cultures.
+
+#### Disabled
+
+An avatar in a disabled state shows that an avatar exists, but is not available or a user is not active in that circumstance. This can be used to maintain layout continuity and communicate that an avatar may become available or active later.
+
+### Accessibility
 
 The `label` attribute of the `<sp-avatar>` will be passed into the `<img>` element as the `alt` tag for use in defining a textual representation of the image displayed.

packages/color-handle/README.md

@@ -1,45 +1,164 @@
-## Description
+## Overview
 
-The `<sp-color-handle>` is used to select a colour on an `<sp-color-area>`, `<sp-color-slider>`, or `<sp-color-wheel>`. It functions similarly to the handle on an `<sp-slider>`.
+The `<sp-color-handle>` is used to select a color on an `<sp-color-area>`, `<sp-color-slider>`, or `<sp-color-wheel>`. It provides a draggable control point for precise color selection within color components.
 
 ### Usage
 
 [![See it on NPM!](https://img.shields.io/npm/v/@spectrum-web-components/color-handle?style=for-the-badge)](https://www.npmjs.com/package/@spectrum-web-components/color-handle)
 [![How big is this package in your project?](https://img.shields.io/bundlephobia/minzip/@spectrum-web-components/color-handle?style=for-the-badge)](https://bundlephobia.com/result?p=@spectrum-web-components/color-handle)
 
-```
+**Note**: `<sp-color-handle>` is a primitive component designed to be used within other color selection components. It's not typically used directly in applications, but rather as part of higher-level color components like `<sp-color-area>`, `<sp-color-slider>`, or `<sp-color-wheel>`.
+
+```bash
 yarn add @spectrum-web-components/color-handle
 ```
 
 Import the side effectful registration of `<sp-color-handle>` via:
 
-```
+```javascript
 import '@spectrum-web-components/color-handle/sp-color-handle.js';
 ```
 
 When looking to leverage the `ColorHandle` base class as a type and/or for extension purposes, do so via:
 
-```
+```javascript
 import { ColorHandle } from '@spectrum-web-components/color-handle';
 ```
 
-## Standard
+### Anatomy
+
+The color handle consists of several key parts:
+
+- A visual handle element that indicates the current position
+- Touch-responsive interaction areas
+- Color display showing the current selected color
+- Opacity checkerboard pattern for transparent colors
+- An optional `sp-color-loupe` that appears above the handle when the properties `open = true` and `disabled = false`
 
 ```html
 <sp-color-handle></sp-color-handle>
 ```
 
-## Disabled
+### Options
+
+#### Color
+
+The `color` property sets the visual color displayed within the handle. This accepts any valid CSS color format. The default color is `rgba(255, 0, 0, 0.5)` (semi-transparent red).
+
+For a complete list of supported color formats, see the [ColorController documentation](/tools/color-controller#supported-color-formats).
+
+**Transparency Support**: When using transparent colors, the handle displays an opacity checkerboard pattern background to clearly show the transparency level.
+
+```html
+<div style="display: flex; gap: 16px; align-items: center; margin: 16px 0;">
+    <!-- Hex color -->
+    <div style="position: relative; height: 20px; margin: 20px;">
+        <sp-color-handle color="#ff0000"></sp-color-handle>
+    </div>
+
+    <!-- RGB format -->
+    <div style="position: relative; height: 20px; margin: 20px;">
+        <sp-color-handle color="rgb(255, 0, 0)"></sp-color-handle>
+    </div>
+
+    <!-- RGBA format with transparency -->
+    <div style="position: relative; height: 20px; margin: 20px;">
+        <sp-color-handle color="rgba(255, 0, 0, 0.5)"></sp-color-handle>
+    </div>
+
+    <!-- HSL format -->
+    <div style="position: relative; height: 20px; margin: 20px;">
+        <sp-color-handle color="hsl(0, 100%, 50%)"></sp-color-handle>
+    </div>
+
+    <!-- Named colors -->
+    <div style="position: relative; height: 20px; margin: 20px;">
+        <sp-color-handle color="red"></sp-color-handle>
+    </div>
+</div>
+```
+
+### States
+
+#### Standard
+
+The default state of the color handle, ready for interaction:
+
+```html
+<sp-color-handle></sp-color-handle>
+```
+
+#### Disabled
+
+A disabled color handle shows that the control exists but is not available for interaction. This maintains layout continuity and communicates that the handle may become available later:
 
 ```html
 <sp-color-handle disabled></sp-color-handle>
 ```
 
-## Open
+#### Open
 
-When the `<sp-color-handle>` uses the `open` property, the `<sp-color-loupe>` component can be used above the handle to show the selected color that would otherwise be covered by a mouse, stylus, or finger on the down/touch state. This can be customized to appear only on finger-input, or always appear regardless of input type.
+When the `open` property is set, the `<sp-color-loupe>` component appears above the handle to show the selected color that would otherwise be covered by a mouse, stylus, or finger on the down/touch state. The loupe automatically appears for touch input (`pointerType === 'touch'`).
 
 ```html
 <div style="height: 72px"></div>
 <sp-color-handle open></sp-color-handle>
 ```
+
+**Automatic Behavior**: The loupe automatically opens when touched and closes when the touch interaction ends. For mouse and stylus input, the loupe remains hidden by default unless explicitly set to `open="true"`.
+
+#### Focused
+
+The color handle can receive keyboard focus when used within interactive color components. The focused state is managed automatically by the parent component and is indicated visually:
+
+```html
+<sp-color-handle focused></sp-color-handle>
+```
+
+### Behaviors
+
+#### Pointer Interactions
+
+The color handle automatically manages pointer events to provide the optimal user experience:
+
+- **Touch Input**: When touched (`pointerType === 'touch'`), the color loupe automatically appears to prevent the finger from obscuring the selected color
+- **Mouse/Stylus Input**: The loupe remains hidden by default for precision pointing devices
+- **Pointer Capture**: The handle captures pointer events during interaction to ensure smooth dragging even when the pointer moves outside the handle area
+- **Event Handling**: The component listens for `pointerdown`, `pointerup`, and `pointercancel` events to manage the interaction lifecycle
+
+#### Color Display
+
+The handle displays the current color with proper support for transparency:
+
+- Transparent colors are shown with an opacity checkerboard pattern background
+- The color updates in real-time as the user interacts with the parent color component
+- Supports all standard CSS color formats
+
+For a complete list of supported color formats, see the [ColorController documentation](/tools/color-controller#supported-color-formats).
+
+### Accessibility
+
+The `<sp-color-handle>` is designed to work as part of accessible color selection components:
+
+#### Keyboard Support
+
+While the color handle itself is not directly keyboard accessible, it works in conjunction with its parent components ([`<sp-color-area>`](/components/color-area), [`<sp-color-slider>`](/components/color-slider), [`<sp-color-wheel>`](/components/color-wheel)) which provide comprehensive keyboard navigation.
+Example: Keyboard accessibility with `sp-color-area` as parent component
+
+```html
+<sp-color-area></sp-color-area>
+```
+
+#### Screen Reader Support
+
+The color handle is rendered as a visual indicator and does not directly interface with screen readers. Accessibility is provided through the parent color component's ARIA implementation.
+
+#### Touch Accessibility
+
+- **Color Loupe**: Automatically appears for touch input to ensure the selected color remains visible
+- **Large Touch Target**: The handle provides an appropriately sized touch target for mobile interaction
+- **Pointer Capture**: Ensures reliable dragging behavior across different touch devices
+
+#### Focus Management
+
+Focus is managed by the parent color component, with the handle reflecting the focused state visually when its parent component has keyboard focus.

packages/color-wheel/src/ColorWheel.ts

@@ -85,13 +85,16 @@ export class ColorWheel extends Focusable {
         this.colorController.color = color;
     }
 
-    private get altered(): number {
-        return this._altered;
-    }
+    private _baseStep: number = 1; // Preserves user's value
 
     private set altered(altered: number) {
         this._altered = altered;
-        this.step = Math.max(1, this.altered * 10);
+        // Don't modify anything here!
+    }
+
+    private get effectiveStep(): number {
+        // Calculate on-the-fly without modifying stored values
+        return this._altered > 0 ? this._baseStep * 10 : this._baseStep;
     }
 
     private _altered = 0;
@@ -112,16 +115,16 @@ export class ColorWheel extends Focusable {
         let delta = 0;
         switch (key) {
             case 'ArrowUp':
-                delta = this.step;
+                delta = this.effectiveStep;
                 break;
             case 'ArrowDown':
-                delta = -this.step;
+                delta = -this.effectiveStep;
                 break;
             case 'ArrowLeft':
-                delta = this.step * (this.isLTR ? -1 : 1);
+                delta = this.effectiveStep * (this.isLTR ? -1 : 1);
                 break;
             case 'ArrowRight':
-                delta = this.step * (this.isLTR ? 1 : -1);
+                delta = this.effectiveStep * (this.isLTR ? 1 : -1);
                 break;
             default:
                 return;
@@ -394,6 +397,12 @@ export class ColorWheel extends Focusable {
         this.addEventListener('blur', this.handleBlur);
     }
 
+    protected override willUpdate(changed: PropertyValues<this>): void {
+        if (changed.has('step')) {
+            this._baseStep = this.step;
+        }
+    }
+
     private observer?: WithSWCResizeObserver['ResizeObserver'];
 
     public override connectedCallback(): void {