Last call for @nextcloud/vue v9 breaking changes

[ShGKme]

Before releasing the final v9.0.0 and making it the main branch we should make sure that all required breaking changes are applied.

When possible, migration should be simple:

• Removed API must be marked deprecated in v8
• Changed API should have a compatible API in v8

Current breaking changes

• Vue 2 -> Vue 3
• CJS dropped
  • ✅ Forward-compatible via ESM
• dist and .js extension dropped from import path
  • ✅ Forward-compatible by just using the new paths like @nextcloud/vue/components/NcButton.
• NcSettingsSection: limitWidth prop was removed
  • ✅ Deprecated in v8
• NcAppSidebar: closing and opening events were removed
  • ✅ Forward-compatible via update:open
• v-model related changes
  • ✅ Forward-compatible via:
    • feat: forward compatibility with v9 on v-model props/events #6172
    • feat: add v-model support for input-like components #5418
• #default slot changed to #icon for the leading icon in Nc*Field
  • ✅ Forward-compatible via:
    • feat(Nc*Field): add #icon slot for forward compatibility with v9, #default slot is deprecated #6399
• isFullscreen and isMobile are removed
  • ✅ Corresponding composables are available on both versions
• exact prop removed from VueRouter-related components
  • ✅ Comes from Vue Router migration

Proposals with breaking changes

• feat: Allow to import without dist #6385
  • ✅ Deprecated in v8 and forward-compatible
• [next] feat!: remove plugin #6349
  • ✅ Deprecated in v8 and forward-compatible
• [next] fix!: make 'box-sizing: border-box' a default behaviour for all containers #6390
  • ✅ Can be manually applied in v8, forward-compatible
• feat: Allow to import without dist #6385
  • ✅ Deprecated in v8 and forward-compatible
• refactor: Use boolean props with default value false #6452
  • ✅ Deprecated in v8 and forward-compatible
• refactor!: Drop clickOutsideOptions mixin and refactor using components #6429
  • ✅ Deprecated in v8 (not used)

[raimund-schluessler]

There was the idea to remove icon class support. Don't know whether this is still planned or not #3007

See #5048 as well.

[susnux]

There was the idea to remove icon class support

Yes but not now I think, there is too much old stuff that simply would break.
We also do not have agreed yet on an alternative, especially if icons are set by e.g. PHP API.
There is a discussion somewhere what to do (always inline SVG, custom icon library, etc), also a problem is we use MDI a lot but thats not where we want to go so even that is only a intermediate step.

Do we want to rename exports like Components to components or remove dist part?

Would love to see all of that, but it does not have to be breaking, we can support both without any new files (just add an alias to the exports in the package json).

Remove plugin #6349

💯

[ShGKme]

Proposal: get rid of other mixins:

• clickOutsideOptions
  • Remove
  • I haven't found usage anywhere, used internally
  • @susnux Assigned
• userStatus
  • Remove?
  • I haven't found usage anywhere
  • Alternatively can be migrated to composable/library
• richEditor
  • Remove?
  • Used in Talk and server/apps/comments
  • Can be replaced with NcRichText
  • @Antreesy and @ShGKme assigned

[susnux]

One thing that annoys for probably as long as I work with nc-vue, but maybe I just have to live with it:

type is native attribute of a button, but we misuse it for NcButton thus we have nativeType.
Maybe we can / should (or maybe not at all) change both to:

• type the native type
• color for the button color like primary / secondary.

The problem here is:

1. Do we really want to do that, as this requires many changes in apps (though probably doable with sed)
2. Only partly doable in a forward compatible way (we can introduce color instead of type easily and deprecate type but for nativeType -> type this is only doable if e.g. color is set then use type otherwise nativeType).

But as said if you do not agree with me here, then I can live with it ;)

[ShGKme]

One thing that annoys for probably as long as I work with nc-vue

Yes. It breaks the rule of not naming component's interface same as native, when it has different meaning.

• color for the button color like primary / secondary.

Or variant/kind, as it is not about the color, but "visual semantics"?

1. Do we really want to do that, as this requires many changes in apps (though probably doable with sed)

It's also a change for NcActions.

2. Only partly doable in a forward compatible way (we can introduce color instead of type easily and deprecate type but for nativeType -> type this is only doable if e.g. color is set then use type otherwise nativeType).

Maybe it's not so complex. Values for type and nativeType are not intersetcing.

If the value is button | submit | reset - it's the native type.
If the value is primary | secondary | ... - it's the old type.

[ShGKme]

Question: shall we add more runtime warnings for deprecated stuff?

[ShGKme]

But how about appearance as this is basically visually and kind or variant could also be used for shape or behavior.

I'd still vote for kind or variant, because it describes what kind or what variant of buttons it is.
While appearence also includes things like size.

And to keep wording simpler (appearance has more places for typos, especially for non-native speakers).

[raimund-schluessler]

I would vote for variant.

[susnux]

we should make sure that all required breaking changes are applied.

One thing that I worked on last year but not 100% finished was migrating the NcDatetimePicker, maybe I find some time to work on it.
The library we use currently is not maintained for 2 years, that's why I started to migrate it.
Currently trying to make it as less breaking as possible, but its horrible that we "wrap a library" instead of provide our own props / events interface and abstract the library.
Because that would allow easier change of the underlying implementation.

[ShGKme]

Currently trying to make it as less breaking as possible, but its horrible that we "wrap a library" instead of provide our own props / events interface and abstract the library.
Because that would allow easier change of the underlying implementation.

I mentioned it in useHotKey creation PR recently - I'd even make a rule that if we develop a component based on an external lib, we should never expose its interface through a transparent wrapper.

It binds component too much on externals...

[ShGKme]

Proposal: make sure exports are consistent, e.g.:

• Only named exports are used apart from components
• Only a single component is exported from /components/*

[ShGKme]

Proposal: check is all the functions are still actual, e.g.:

• contactsMenu
• isA11yActivation

[ShGKme]

Proposal: decompose "super" components.

A super-component is a large component that tries to do too much work for different, sometimes very narrow, cases.

Why

Such components often have tens of props, complex implementation and 1000-2000+ lines of code, while 200-400 is a limit for a good component.

Examples

• NcActions, covers:
  • Simple menus, including navigation and inline feature
  • Custom menus with custom button contents
  • Dialogs with forms
• NcSelect
  • Universal component, but has UserSelect as built-in feature
• NcAvatar
  • Minimal: just an image
  • Maximum: user metadata fetching + user status + contacts menu
• NcAppSidebar
  • On one hand - a universal sidebar
  • On another - contents Files-specific app features such as "favorite"
  • Same with NcModal with viewer-only features

What to do

• Decompose to base components and more specific components
  • e.g. NcSelect => NcSelect + NcUserSelect
• Make a base component extendable and customize in place where needed
  • e.g. NcAppSidebar for Files app use cases

[ShGKme]

Proposal: remove or rework NcListItemIcon. Its name is completely wrong anyway.