# 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.

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

```js
{
    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`.

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

```js

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

1. Use expanded (non-mixin) CSS as much as possible right in the component.

2. 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:

1. 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.

2. 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

3. 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.

---

## Default README

This template should help get you started developing with Vue 3 in Vite.

### Recommended IDE Setup

[VSCode](https://code.visualstudio.com/) +
[Volar](https://marketplace.visualstudio.com/items?itemName=Vue.volar) (and disable Vetur) +
[TypeScript Vue Plugin
(Volar)](https://marketplace.visualstudio.com/items?itemName=Vue.vscode-typescript-vue-plugin).

### Customize configuration

See [Vite Configuration Reference](https://vitejs.dev/config/).

### Project Setup

```sh
npm install
```

#### Compile and Hot-Reload for Development

```sh
npm run dev
```

#### Compile and Minify for Production

```sh
npm run build
```

#### Run Unit Tests with [Vitest](https://vitest.dev/)

```sh
npm run test:unit
```

#### Lint with [ESLint](https://eslint.org/)

```sh
npm run lint
```