feat(design-system, web-pkg): add explicit explanation to enable/disable sync functionality to avoid confusing the user

[mzner]

add explicit explanation to enable/disable sync functionality to avoid confusing the user

• add tooltip function to Action interface
• remove aria-label when aria-label value is null so that it does not show in the html with empty value

Description

Related Issue

• Fixes Disable/enable sync confudsed users who only use web #10962

Motivation and Context

How Has This Been Tested?

• test environment:
• test case 1:
• test case 2:
• ...

Screenshots (if appropriate):

Types of changes

• Bug fix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing functionality to change)
• Technical debt
• Tests
• Documentation
• Maintenance (e.g. dependency updates or tooling)

Open tasks:

• ...

[update-docs]

Thanks for opening this pull request! The maintainers of this repository would appreciate it if you would create a changelog item based on your changes.

[LukasHirt]

Best to check with @DeepDiver1975 whether mobile clients are really affected or if it's only desktop...

[LukasHirt]

What would you say about being a bit more explicite what the settings actually do? Then maybe the mention that it does not affect web client might be redundant because it might be clear enough from the functionality description.

[LukasHirt]

Won't this result in the action label being read twice in case there is no custom tooltip?

[LukasHirt]

I wonder whether we need to include the action label here or if we can rely only on the tooltip...

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
89.5% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud

[DeepDiver1975]

Thanks for tackling #10962, @mzner — the confusion around enable/disable sync for web-only users is real, and adding an explanation is the right direction. Reviewed as maintainer; a few points to address before this is mergeable.

Accessibility — label likely announced twice (blocking)

Same concern @LukasHirt already raised. The hidden description span is rendered unconditionally and aria-describedby is always set on the button:

<span :id="uniqueId" class="oc-invisible-sr">
  {{ tooltipText }}
</span>

const tooltipText = computed<string>(() => {
  if (action?.tooltip) {
    return `${action.label(actionOptions)} - ${action.tooltip(actionOptions)}`
  }
  return action.label(actionOptions)   // <- falls back to just the label
})

For the large majority of actions (which have no tooltip), tooltipText is exactly action.label(...). So the button ends up with accessible name = label and accessible description = the same label, and screen readers will announce the label twice for every action menu item. Suggested fix:

• Only render the description span and set aria-describedby when action.tooltip is present (gate both on it), and
• in the description expose only the tooltip/explanation text, not label + " - " + tooltip — the label is already the accessible name, so the description should add only the new information (this also addresses @LukasHirt's "do we need the label here" point).

That keeps behavior unchanged for all existing actions and adds the explanation only where one is defined.

Open product question still unresolved

@LukasHirt asked whether mobile clients are actually affected or only desktop, pending @DeepDiver1975's confirmation. The string currently asserts "desktop and mobile clients" — please get that confirmed before merge, since it's user-facing copy. If only desktop is affected the message is inaccurate. (Per @LukasHirt's other suggestion, describing what the setting does may also let you drop the explicit "does not affect web" framing.)

Changelog missing (requested)

This is a user-facing change but there's no changelog/unreleased/ fragment. Please add one following changelog/TEMPLATE, e.g. changelog/unreleased/enhancement-explain-enable-disable-sync.md:

Enhancement: Explain the enable/disable sync action

We've added an explanatory tooltip to the "Enable sync" and "Disable sync"
actions, clarifying which clients they affect, to avoid confusing users who
only use the web client.

https://github.com/owncloud/web/issues/10962
https://github.com/owncloud/web/pull/13486

(I held off pushing this fragment myself since the exact wording depends on resolving the desktop/mobile question above.)

Tests missing

No unit tests were added. ActionMenuItem.spec.ts already exists — please cover the new tooltipText behavior: (a) an action without tooltip produces no extra description / no double labelling, and (b) an action with tooltip exposes the explanation. This also guards the a11y fix above against regression.

Smaller notes (non-blocking)

• OcButton.vue :aria-label="ariaLabel || null" is a good change — drops the empty aria-label="" from the DOM, and no existing OcButton snapshots reference an empty aria-label, so nothing breaks there.
• tooltip?(options?: T): string on the Action interface is reasonable and consistent with label/disabledTooltip.
• The string literal is duplicated across useFileActionsEnableSync.ts and useFileActionsDisableSync.ts — fine to leave inline, just keep both in sync if the copy changes.

Summary: good idea, small footprint, but I'd like the double-announce a11y issue fixed, the desktop/mobile copy confirmed, a changelog fragment added, and a test before merging. Close once those are addressed.