@thinkpixellab-public/px-vue NPM

px-vue

Storybook

Basic component preview and testing can be done with storybook. Run storybook with npm run dev-px.

Migration Notes / Approach

Two-way Props / v-model

Move away from .sync and use v-model with an argument instead

Minimal v-model Implementation

The minimal implementation allows the parent component to "own" data and pass it the child component as a prop. If the child component wants to update the value, it does so by emitting an event with the preferred value.

<MyComponent v-model:selected="selected" />

{
    emits: ['update:selected'],
    props: {
        selected: { default: null }
    },
    methods: {
        updateSelected(selectedValue) {
            this.$emit('update:selected', selectedValue);
        }
    }
}

Local Data v-model Implementation

In many cases a component should be able to update the data without requiring a parent component to actually provide the data store. In this case we create a data property and keep it in sync with the prop.

By convention the internal data field has the same name ast the prop with "Value" appended. If the prop were named selected, for example, the corresponding data field would be named selectedValue. Internally the component should always use selectedValue instead of selected.

<MyComponent v-model:selected="selected" />

emits: ['update:selected'],
props: {
    selected: { default: null }
},
data() {
    return {
        selectedValue: this.selected
    };
},
watch: {
    selected(nv) {
        this.selectedValue = nv;
    },

    selectedValue(nv) {
        this.$emit('update:selected', nv);
    }
}

Styles / Customization

Component Fallbacks Hardcoded values defined in the component style.
Component Variants Overrides defined within the component

App Defaults App Scoped Defaults App Variants

Usage Defaults Usage Class

Style

FAQ

Where should component styles be defined?

TLDR

Use expanded (non-mixin) CSS as much as possible right in the component.
Repeating styles (e.g. a popup or a button) should generally have their own component and variants for that style.

Since we use single file components, these should obviously be defined in the component. That said, many of our more generic components are currently using px-styles mixins for this (i.e. the whole style section could just be something like @include button()) and I think we should move away from that and instead keep as much of the component's css in an "expanded" state as possible. This makes it much easier to understand what's going on.

Where should styling defaults come from?

We want to have a hierarchy that roughly looks like this:

The component should provide default values in a way that no external CSS or configuration is necessary to get a generic version of the component.
It should be straightforward to define app defaults and these can be encapsulated into a shareable "theme" file that can be customized / used for projects. It also might make sense to have different levels of specificity in that theme. For example a property like "border-radius" might be shared by many controls (button, textbox, dropdown, etc.) so it would make sense that you can define an app-level default for that. But you should also be able to have different values for different components
It makes sense that the component can

Component Defaults App Defaults (with levels of specificty) Variants App Variants

<style>

When should we use CSS variables in custom components?

Is it useful to reexpose CSS variables for properties that already exist like border radius (e.g. px-textbox-border-radius)? It doesn't seem like it because you would define it at the root as the default and then again at usage. Might as well just use border-radius. What about for global defaults? For that we can use SASS config/vars.

On the other hand, it does seem useful to use CSS variables for high level concepts that don't have a semantically equivalent CSS property but would make sense to customize. An example of this might be something like '--toggle-track-background' or in a toggle switch or '--dropdown-arrow-svg' in a dropdown.

These can then be treated like other CSS properties where they would take their default from a SCSS config (with a fallaback) but then be easily overriden in a local style or class.

When should we use v-bind to expose style-related properties as props?

If the value is likely to change a lot based on usage then maybe it makes sense to do this but I think it is rare. Most of the time it's better keep CSS modifications in CSS. Keep styling in styles/CSS for the most part. This doesn't mean never use v-bind in CSS, it just means that we don't want to arbitraily expose many CSS properties as props on the component because it just becomes unclear how you should style or modify the component.