Infer attrs for implementing HOCs

[rudyxu1102]

• Start Date: 2023-01-01
• Target Major Version: 3.x
• Reference Issues:
  • [QUESTION] How to allow HTML attributes as props while using Typescript JSX? core#3452
  • Expose the native attributes of elements such as button and P in the component core#5423
  • How to determine that a component can accept native html attributes of a specific element? core#6528
  • How to set a props type with InputHTMLAttributes? core#7546
  • Is it possible to support the type-based autocomplettion for those fallthrough attributes? core#7981
  • How to access props in "extended" component core#8264
  • How to write a passthrough wrapper component? core#8508
  • 建议新增为 typescript 服务 defineAttrs core#8620
  • How to extend props types for a wrapper component with fallthrough attributes? core#8902
  • [Docs] Add guide for building HOCs in TypeScript core#9272
• Implementation PR:
  • feat(types): support inferring attrs  core#7444
  • Volar

Summary

Allowing to infer attrs by using attrs option of defineComponent or defineCustomElement.
And in the setup-script, passing generic type in the defineAttrs<T> will also infer attrs to T.

Basic example

Using defineComponent

Options Api

const Comp = defineComponent({
  props: {
    foo: String
  },
  attrs: Object as AttrsType<{
    bar?: number
  }>,
  created() {
    this.$attrs.bar // number | undefined
  }
});

<Comp foo={'str'} bar={1} />;

Composition Api

const Comp = defineComponent({
  props: {
    foo: {
      type: String,
      required: true
    }
  },
  attrs: Object as AttrsType<{
    bar?: number
  }>,
  setup(props, { attrs }) {
    props.foo; // string
    attrs.bar; // number | undefined
  }
});
<Comp foo={'str'} bar={1} />;

Functional Components

const Comp = defineComponent(
  (props: { foo: string }, ctx) => {
    ctx.attrs.bar; // number | undefined
    return () => (
      <div>{props.foo}</div>
    )
  },
  {
    attrs: Object as AttrsType<{
      bar?: number
    }>
  }
);
<Comp foo={'str'} bar={1} />;

Using defineAttrs<T> in setup-script

// MyImg.vue
<script setup lang="ts">
const attrs = defineAttrs<{ bar?: number }>();
</script>

Complie Output:

import { useAttrs as _useAttrs, defineComponent as _defineComponent } from 'vue'

export default /*#__PURE__*/_defineComponent({
  setup(__props, { expose: __expose }) {
  __expose();

      const attrs = _useAttrs()
      
return { attrs }
}

})

Using defineCustomElement

const Comp = defineComponent({
  props: {
    foo: String
  },
  attrs: Object as AttrsType<{
    bar?: number
  }>,
  created() {
    this.$attrs.bar // number | undefined
  }
});

Motivation

This proposal is mainly to infer attrs using defineComponent.

When using typescript in Vue3, the fallthrough attributes is unable to be used. It's not appropriate obviously that only one can be chosen from typescript and Fallthrough Attributes. In most cases, we choose typescript and set attributes to props option instead of using the fallthrough attributes.

Main scenes:

1. Wrapping a native HTML element in a new component, such as img.

• Option Api

import { defineComponent, type ImgHTMLAttributes, type AttrsType } from 'vue';

const MyImg = defineComponent({
    props: {
        foo: String
    },
    attrs: Object as AttrsType<ImgHTMLAttributes>,
    created() {
        this.$attrs.class // any
        this.$attrs.style // StyleValue | undefined
        this.$attrs.onError // ((payload: Event) => void) | undefined
        this.$attrs.src // string | undefined
    },
    render() {
        return <img {...this.$attrs} />
    }
});

<MyImg class={'str'} style={'str'} src={'https://xxx.com/aaa.jpg'} onError={(e) => {
  e; // Event
}}/>;

• Setup Script

// MyImg.vue
<script setup lang="ts">
import { type ImgHTMLAttributes } from 'vue';
const attrs = defineAttrs<ImgHTMLAttributes>();
</script>

2. Wrapping a component from UI library in a new component, such as el-button from element-plus.

• Option Api

import { defineComponent, type AttrsType } from 'vue';

const Comp = defineComponent({
    props: {
        foo: String
    },
    emits: {
        baz: (val: number) => true
    },
    render() {
        return <div>{this.foo}</div>
    }
});

const MyComp = defineComponent({
    props: {
        bar: Number
    },
    attrs: Object as AttrsType<typeof Child>,
    created() {
        this.$attrs.class // unknown
        this.$attrs.style // unknown
        this.$attrs.onBaz; // ((val: number) => any) | undefined
        this.$attrs.foo; // string | undefined
    },
    render() {
        return <Comp {...this.$attrs} />
    }
});

<MyComp class={'str'} style={'str'} bar={1} foo={'str'} onBaz={(val) => { 
    val; // number
}} />;

• Setup Script

// MyButton.vue
<script setup lang="ts">
import { Button } from 'element-plus';
const attrs = defineAttrs<typeof Button>();
</script>

Unresolved questions

Naming suggestions or improvements on the API are welcome.

[cawa-93]

How it will work in functional components?

[rudyxu1102]

Here is TS Playground about functional components.

[jods4]

I don't understand the motivation or the design.

attrs is supposed to be the catch-all for anything bound on a component that the component doesn't know about (i.e. props).
How/why would you type that? Aren't re-inventing props? Why is a well-known, typed attribute not a prop?

In motivation you say:

When using typescript in Vue3, the fallthrough attributes is unable to be used.

As a Typescript user, I don't understand. I use TS and fall-through with no obvious issue, so I think it'd be worthwhile going into a little more details what the limitation is. Maybe even open an issue about it, there might be a more idiomatic way to fix the limitation you encounter without turning attrs into props2.

[jods4]

I see, I have written several components that just enhance "native" tags in this way and have experienced the same.

It doesn't bother me that much for HTML controls because there's usually few tag-specific attributes, but it's much worse when you wrap a Vue component (as you said: to provide some contextually meaningful defaults).

The fallthrough itself works but you've lost all props typings from the inner component.

This can be worked-around by re-declaring all props and re-binding them (en masse using v-bind), but it's a tedious and brittle approach, as the props type must be locally declared in the same file and can't be imported from another file (currently a tooling limitation); so you must duplicate everything and keep it in sync when it changes -- esp. terrible if the component comes from third-party and has tons of props.

As much as I'd love to see a solution to this problem, I am not sure how this RFC solves it.
Sure, the implicit fall-through of attrs removes the need for v-bind, but that's IMHO by far not the worst issue here.
You would still need to re-declare all properties of the inner component.

For this specific goal, it'd be kind of nice if the tooling would have some smarts when a Component has inheritAttrs and a single inner component -> IDE provides some additional default props from underlying component.

[leopiccionia]

Yeah, something like useAttrs<HTMLButtonElement> (or like useAttrs<Omit<HTMLButtonElement, keyof _ComponentProps>>) would be cool. Better yet if it was automatically inferred.

[rudyxu1102]

Yeah, something like useAttrs<HTMLButtonElement> (or like useAttrs<Omit<HTMLButtonElement, keyof _ComponentProps>>) would be cool. Better yet if it was automatically inferred.

useAttrs<T> is in the proposal.

[jods4]

Note that you're basically asking for Vue tooling to lift its single-file limitation.
That would be super cool but it's a big thing to ask as a sub-part of a larger RFC.

More details if it's unclear what I mean by that:
To be useful, tooling needs to know what the type HTMLButtonElement is, which implies it sees the whole TS compilation (it comes from tslib). Likewise, it would need to see the props type of Vue components in other files.

AFAIK this is currently a limitation of defineProps in script setup, and it would apply similarly to a new defineAttrs.

EDIT: Or maybe not. I think the limitation applies to the Vue compiler, as defineProps is translated into a props definition object (it needs to know all the keys and the tool only looks at a single file without full TS context).
As long as the new macro does not impact view compilation (i.e. it's fully discarded), it should be ok.
I think Volar has access to the full TS compilation so IDE support should be ok.

[rudyxu1102]

AFAIK this is currently a limitation of defineProps in script setup, and it would apply similarly to a new defineAttrs.

I agree with you. This Proposal still not resolves the limitation of defineProps. I think that it's related to unresolved questions of script-setup-RFC. That would be cool if someone implement this feature.

[cawa-93]

Also, do not forget about the events. For example, a <details> element has not only a specific open attribute, but also a specific toggle event. IDE should propose it for v-on

[rudyxu1102]

Thank you for such positive feedback. It works on specific events.
I wrote a demo that wrapped <image> element. Please clone this repository (branch: image-element) and run it.

[cawa-93]

Thank you for so such positive feedback. It works on specific events. I wrote a demo that wrapped <image> element. Please clone this repository and run it.

It's doesn't work in webstorm


🤷🏻‍♂️

[rudyxu1102]

It's related to vuejs/language-tools#1240. It works fine in VS Code.

[rudyxu1102]

Updated

Since the slots option is already supported, I think using the attrs option may be more in line with user habits, instead of using the second parameter as stated in the RFC.

1. Option Component

const Comp = defineComponent({
    slots: Object as SlotsType<{
        foo?: { data: string }
    }>,
    attrs: Object as AttrsType<{
        bar?: string
    }>,
    setup(props, { slots, attrs }) {
        console.log(attrs.bar)
        slots.foo?.({ data: 'a' })
    }
});
<Comp bar={"str"} />;

2. Functional Component

const Comp = defineComponent(
  (props: { foo: string }, ctx) => {
    console.log(ctx.attrs.bar)
    return () => (
      <div>{props.foo}</div>
    )
  },
  {
    slots: Object as SlotsType<{
        baz?:  { data: string }
    }>,
    attrs: Object as AttrsType<{
      bar?: number
    }>
  }
);
<Comp bar={1} foo={"str"} />;

See vuejs/core#7444

[rudyxu1102]

Specific scenes

1. Wrapping a html element

import { defineComponent, type ImgHTMLAttributes, type AttrsType } from 'vue';

const MyImg = defineComponent({
    props: {
        foo: String
    },
    attrs: Object as AttrsType<ImgHTMLAttributes>,
    created() {
        this.$attrs.class // any
        this.$attrs.style // StyleValue | undefined
    },
    render() {
        return <img {...this.$attrs} />
    }
});
<MyImg class={'str'} style={'str'} src={'str'} />;

2. Wrapping a component

import { defineComponent, type AttrsType, type ExtractPropsAndEvents } from 'vue';

const Child = defineComponent({
    props: {
        foo: String
    },
    emits: {
        baz: (val: number) => true
    },
    render() {
        return <div>{this.foo}</div>
    }
});

const Comp = defineComponent({
    props: {
        bar: Number
    },
    attrs: Object as AttrsType<ExtractPropsAndEvents<typeof Child>>,
    created() {
        this.$attrs.class // unknown
        this.$attrs.style // unknown
    },
    render() {
        return <Child {...this.$attrs} />
    }
});

<Comp class={'str'} style={'str'} bar={1} foo={'str'} onBaz={(val) => { 
    val; // number
}} />;

[rudyxu1102]

Update

I'm going to use AttrsType directly instead of ExtractPropsAndEvents, because using ExtractPropsAndEvents will confuse the user with attrs and props.

2. Wrapping a component

import { defineComponent, type AttrsType } from 'vue';

const Child = defineComponent({
    props: {
        foo: String
    },
    emits: {
        baz: (val: number) => true
    },
    render() {
        return <div>{this.foo}</div>
    }
});

const Comp = defineComponent({
    props: {
        bar: Number
    },
    attrs: Object as AttrsType<typeof Child>,
    created() {
        this.$attrs.class // unknown
        this.$attrs.style // unknown
    },
    render() {
        return <Child {...this.$attrs} />
    }
});

<Comp class={'str'} style={'str'} bar={1} foo={'str'} onBaz={(val) => { 
    val; // number
}} />;

[rudyxu1102]

Update

In order to be consistent with the usage habits of defineSlots, I plan to use defineAttrs instead of useAttrs.

[pikax]

Can you please update the discussing and the rendered when updating the proposal, instead of updating comments or the implementation

[rudyxu1102]

Updated.

[pikax]

I have a few questions that this RFC does not seem to be clear:

• What would be the difference between a prop and a attribute?
• What would happen if the user sent the wrong type to an attribute? In props we do runtime validation.
• Do the plugins or tools need to make changes to support this RFC?
• Should attributes be implicitly optional?
• How the user understands:

// both 
const comp = defineComponent({  props: { foo: Number}, attrs: null as { bar: Number} })

// runtime error
<Comp foo={"1"}/> 
// not runtime error
<Comp bar={"1"}/>

---

I would argue if you're expecting the user to pass a specific prop, you should be controlling that through properties, since you're expecting those properties, since you even declaring them...

Currently there's already ways to do what this SFC is trying to add:

Comp.vue

<script setup lang="ts">
const props = defineProps<{
    foo: number
}>();
</script>

playground

For the usage inside of the component, you can always cast your attributes:

// I would agree supporting T on `defineAttrs` instead.
const attrs =defineAttrs() as { bar?: number }

[rudyxu1102]

Good point and thanks for your review. Actually, I also use the implementation you mentioned above in my project, like the following code.

TS Playground

This is a simple and efficient way, but you need to cast type twice at least and this is a bit difficult to understand for typescript newbies. I have no problem with this implementation, but I think it needs to be added in the document.

[rudyxu1102]

What would be the difference between a prop and a attribute?

props can be thought of as attributes of the current component, while attrs can be thought of as attributes of the child component.

What would happen if the user sent the wrong type to an attribute? In props we do runtime validation.

• If you wrap a vue component, there is still a runtime validation. Vue SFC Playground.
• If you wrap an html element, then as you said there is no runtime validation. Vue SFC Playground

Do the plugins or tools need to make changes to support this RFC?

Volar needs support the defineAttrs macro.

Should attributes be implicitly optional?

The attributes extracted from a Vue component or an html element have been processed to determine whether they are optional.

How the user understands:
// both
const comp = defineComponent({ props: { foo: Number}, attrs: null as { bar: Number} })

// runtime error
<Comp foo={"1"}/>
// not runtime error
<Comp bar={"1"}/>

I think jsx verification and runtime verification can be separated. In fact, some components now have the situation you mentioned above, e.g. Element Plus Playground. This example has strict jsx validation but no strict runtime validation.

[jods4]

Here's a take on this issue with minimal impact on Vue core and its type system.
What if Volar / vue-tsc / vscode-typescript-vue-plugin did the following trick with types:

If the component has inheritAttrs: true then these tools should merge the Props types of its root component into its own Props type -- but for the Props generic type parameter only, not as real runtime-defined props.

No runtime nor component metadata change: child component props are still undefined attrs on the wrapper, that are simply inherited.

No change to the complex Vue Component type either, as we piggy-back on the existing Props generic argument.
Indeed attrs that are inherited into props can be handled "as if" they were identical props on the parent.

With this, during compilation we'd get errors for incorrect types, like for real props.
In IDE we'd get completion, like for real props.
And this could be automatic thanks to Volar plugins, without even any code change.

[pikax]

I'll create an RFC and a PoC vuejs/core-vapor#4 (comment), I think that would be the way to tackle this sort of issue for HoC

[teleskop150750]

it would be nice to see something similar to splitProps.

type IAttrs = {
  'prop1': string
  'prop2': number
  'aria-label': string
  [key: string]: any
}


const [props, attrs] = defineAttrs<IAttrs>(['prop1', 'prop2'])