chore(dropzone): S2 migration

[cdransf]

Description

Umbrella PR for the swc-dropzone 1st-gen → 2nd-gen Spectrum 2 migration. All phase PRs target this branch and are merged here before this PR lands on main.

Migration plan: CONTRIBUTOR-DOCS/03_project-planning/03_components/dropzone/migration-plan.md

Phase PRs

Phase	Jira	PR	Status
Phase 1 — Plan	SWC-2147	#6424	Done
Phase 2 — Structure	SWC-2148	#6436	Done
Phase 3 — API	SWC-2148	#6436	Done
Phase 4 — Accessibility	SWC-2148	#6436	Done
Phase 5 — Styling	SWC-2149	#6446	Review
Phase 6 — Testing	SWC-2150	#6448	Review
Phase 7 — Documentation	SWC-2151	—	To do
Phase 8 — Review	SWC-2152	—	To do

Reviewers: individual phase PRs are the right place for line-level review. This PR is for final integration sign-off.

Motivation and context

swc-dropzone is part of the Spectrum 2 component migration workstream. Key changes from 1st-gen:

• Tag rename: sp-dropzone → swc-dropzone
• Events renamed: all four events now use the swc- prefix (swc-dropzone-should-accept, swc-dropzone-dragover, swc-dropzone-dragleave, swc-dropzone-drop)
• role="group" handling: set in connectedCallback with an hasAttribute guard so consumers can override with a different role; no longer hardcoded in the render template
• Shadow DOM live region: a role="status" aria-live="polite" region announces drag state changes ("File ready to drop", "Drop to replace existing file", "File accepted") to screen readers — not present in 1st-gen
• No host tabindex: 1st-gen required consumers to add tabindex="0"; 2nd-gen removes this — the browse control in the slot owns the Tab stop
• New size attribute: s | m | l (default m) controls illustrated icon scale and container dimensions per Figma; additive and non-breaking for existing consumers
• dropEffect getter/setter: validated against the DataTransfer enum at runtime with a dev warning; intentionally not reflected as an attribute (controls browser chrome, not component state)
• Debounced drag-leave: 100 ms debounce on dragleave prevents flicker from child element drag events
• Drop event ordering fix: swc-dropzone-drop fires while dragged is still true so listeners read the correct state; dragged transitions to false after dispatch

Out of scope

The following are intentionally deferred and not part of this PR:

• SVG stroke border: Figma shows a dashed stroke rendered as an inline SVG <rect> for accurate rounded-corner dashes. Spectrum CSS currently uses a CSS border; team alignment is required before the SVG approach can land. Deferred to a follow-up; the styling phase ships a CSS dashed border as an interim.
• swc-illustrated-message styling strategy: how swc-dropzone passes accent-color treatment to the slotted illustrated message in the dragged state is unresolved (Q8 in the migration plan). The --mod-illustrated-message-* passthrough pattern from 1st-gen does not carry forward; this requires a joint decision with the swc-illustrated-message owners.
• swc-illustrated-message button-group slot: the recommended canonical slot pattern (swc-illustrated-message with browse control in its button-group slot) depends on a net-new slot that is additive in the swc-illustrated-message migration plan (A3). Examples use an interim pattern until that slot ships.
• Removing 1st-gen sp-dropzone: the 1st-gen package remains; consumers get the consumer migration guide and deprecation guidance.

Related issue(s)

• fixes SWC-2148
• Epic: SWC-2145

Author's checklist

• I have read the CONTRIBUTING and PULL_REQUESTS documents.
• I have reviewed the Accessibility Practices for this feature, see: Aria Practices
• I have added automated tests to cover my changes.
• I have included a well-written changeset if my change needs to be published.
• I have included updated documentation if my change required it.

Reviewer's checklist

• Includes a Github Issue with appropriate flag or Jira ticket number without a link
• Includes thoughtfully written changeset if changes suggested include patch, minor, or major features
• Automated tests cover all use cases and follow best practices for writing
• Validated on all supported browsers
• All VRTs are approved before the author can update Golden Hash

Manual review test cases

Spot-check in the PR Storybook preview once CI generates it.

• Default render and slot content

  1. Go to Action Button → Docs in the preview Storybook
  2. Verify the drop zone renders with no built-in illustrated content (slot is empty by default)
  3. Slot a swc-illustrated-message with a browse button — verify both render correctly inside the zone
  4. Verify dragged attribute appears on the host when a file is dragged over and disappears on drop or leave
  5. Verify filled attribute persists after setting dropzone.filled = true in the console

• All sizes render correctly

  1. Go to Dropzone → Sizes in the preview Storybook
  2. Verify s, m, and l all render at the expected visual scale (illustration icon and container dimensions)
  3. Confirm m matches the Figma default treatment

• Drag-and-drop interaction

  1. Go to Dropzone → Behaviors in the preview Storybook
  2. Drag a file over the zone — verify the border transitions to the accent/dragged visual state
  3. Move the pointer out — verify the zone returns to its default state after the 100 ms debounce (no flicker on child element hover)
  4. Drop a file — verify swc-dropzone-drop fires and event.target.dragged is true at the time of dispatch
  5. Set dropzone.filled = true after drop — verify the zone transitions to the filled visual state

• Drag rejection (swc-dropzone-should-accept)

  1. Go to Dropzone → Behaviors in the preview Storybook
  2. Add a listener that calls event.preventDefault() on swc-dropzone-should-accept
  3. Drag a file over — verify the cursor shows none (rejection cursor) and dragged does not become true

• Consumer role preserved

  1. Add <swc-dropzone role="region" aria-label="Upload"> to the page
  2. Verify role="region" is not overwritten by the component on upgrade

• Breaking changes documented in the consumer migration guide

  1. Go to Dropzone → Migration guide in the preview Storybook
  2. Confirm all four renamed events are documented with before/after code examples
  3. Confirm the tabindex removal is noted with the recommended browse-control pattern
  4. Confirm the new size attribute is noted as additive

Device review

• Did it pass in Desktop?
• Did it pass in (emulated) Mobile?
• Did it pass in (emulated) iPad?

Accessibility testing checklist

• Keyboard (required — document steps below)

  1. Go to Dropzone → Docs in the preview Storybook
  2. Press Tab — verify focus moves to the browse control inside the slot, not to the swc-dropzone host (host has no tabindex)
  3. Verify the focus ring is visible on the browse control, not on the host element
  4. Press Enter or Space on the browse control — verify the OS file picker opens
  5. Tab past the component — verify focus exits cleanly with no focus trap
  6. Confirm there is no keyboard path to activate the drop zone itself (drag-and-drop is pointer-only; browse control is the keyboard equivalent)

• Screen reader (required — document steps below)

  1. Open Dropzone → Accessibility in the preview Storybook with VoiceOver (macOS) or NVDA (Windows)
  2. Navigate to the drop zone — verify it is announced as "group" with the aria-label value (e.g. "Upload files, group")
  3. Drag a file over the zone — verify the live region announces "File ready to drop"
  4. Drop the file and set filled = true — verify the live region announces "File accepted"
  5. Drag over the filled zone — verify the live region announces "Drop to replace existing file"
  6. Leave the zone without dropping — verify the live region clears after the 100 ms debounce (no stale announcement)
  7. Confirm the host swc-dropzone element is announced once as a group; the shadow DOM role="status" region is not surfaced as a separate interactive element

[changeset-bot]

⚠️ No Changeset found

Latest commit: 2acf4ea

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

[github-actions]

📚 Branch Preview Links

• Documentation Site (first-gen)
• Storybook (first-gen)
• Storybook (second-gen)

🔍 First Generation Visual Regression Test Results

When a visual regression test fails (or has previously failed while working on this branch), its results can be found in the following URLs:

• Spectrum | Light | Medium | LTR
• Spectrum | Dark | Large | RTL
• Express | Light | Medium | LTR
• Express | Dark | Large | RTL
• Spectrum-two | Light | Medium | LTR
• Spectrum-two | Dark | Large | RTL
• High Contrast Mode | Medium | LTR

Deployed to Azure Blob Storage: pr-6437

If the changes are expected, update the current_golden_images_cache hash in the circleci config to accept the new images. Instructions are included in that file.
If the changes are unexpected, you can investigate the cause of the differences and update the code accordingly.

[coveralls]

Coverage Report for CI Build 28253319581

Coverage remained the same at 96.246%

Details

• Coverage remained the same as the base build.
• Patch coverage: No coverable lines changed in this PR.
• No coverage regressions found.

Uncovered Changes

No uncovered changes found.

Coverage Regressions

No coverage regressions found.

---

Coverage Stats

Relevant Lines:	39173
Covered Lines:	37902
Line Coverage:	96.76%
Relevant Branches:	6457
Covered Branches:	6015
Branch Coverage:	93.15%
Branches in Coverage %:	Yes
Coverage Strength:	458.76 hits per line

---

💛 - Coveralls