@thinkpixellab-public/px-vue 3.0.42 → 4.0.0

package/README.md

@@ -1,83 +1,41 @@
 # px-vue
 
-General purpose vue components that can be used across projects.
+This template should help get you started developing with Vue 3 in Vite.
 
-## Instructions
+## Recommended IDE Setup
 
-There is a basic dev environment in this project that use the VueCLI to serve the contents of
-dev.vue. This file can be thought of as a scratch file and shouldn't contain anything that needs to
-be preserved.
+[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).
 
-## Structure
+## Customize configuration
 
-There is no primary entry point into this package so individual components or other files need to be imported directly. The package uses the same project structure as most of our other Vue projects (e.g. components in the /components folder, etc.).
+See [Vite Configuration Reference](https://vitejs.dev/config/).
 
-```javascript
-import PxToggle from '@thinkpixellab-public/px-vue/components/PxToggle.vue';
-```
-
-## Dependency on px-styles
-
-#### TLDR;
-
-When you import a component in your Vue project you may also need to include a file at the root of your project called `/px-styles.config.scss` that configures px-styles. If that file isn't present, many of the components in this package won't build.
-
-The most basic version of this file looks like this:
-
-```scss
-/*
-    px-styles.config.scss
-*/
-
-// import the library (so we can configure it)
-@use '@thinkpixellab-public/px-styles' as px;
-
-// add configuration as needed (this is optional)
-@include px.config('colors:accent', purple);
+## Project Setup
 
-// initialize
-@include px.init();
+```sh
+npm install
 ```
 
-#### Longer Explanation
+### Compile and Hot-Reload for Development
 
-Many of the components require px-styles. To ensure that px-styles has been initialized in the context of the project where the components are being used (e.g. has the correct configuration settings from the project, not arbitrary defaults or configuration set here), the components need to be able to reference a config file from that project.
-
-Here's the werid problem in a nutshell:
-
-1. **SomeProject** imports **PxToggle.vue** from **@thinkpixellab\px-vue**
-2. **PxToggle** style section imports **px-styles** from **@thinkpixellab/px-styles**
-3. **px-styles** needs to be configured somehow but that configuration should come from **SomeProject** and sass is really bad at figuring that out dynamically.
-
-So, the solution becomes:
-
-1. **PxToggle** looks for a file called **px-styles.scss** at the root of **SomeProject** which it expects to do the job of configuring px-styles.
-
-Because we use a hard coded path to px-styles.scss, that file will get resolved within the project that is importing the component instead the root of this package.
+```sh
+npm run dev
+```
 
-## Aliasing a Local Version During Development
+### Compile and Minify for Production
 
-To resolve `@thinkpixellab-public/px-vue` from a local folder during development, you can extend webpack as follows
+```sh
+npm run build
+```
 
-```js
-const path = require('path');
+### Run Unit Tests with [Vitest](https://vitest.dev/)
 
-// add to webpack config
-{
-    resolve: {
-        alias: {
-            '@thinkpixellab-public/px-vue': path.resolve(__dirname, '../px-vue'),
-        },
-    }
-}
+```sh
+npm run test:unit
 ```
 
-Note that if using vue-cli you need to add the above to a file called `vue.config.js` in the project root that looks like this:
+### Lint with [ESLint](https://eslint.org/)
 
-```js
-module.exports = {
-    configureWebpack: {
-        // add the config from above
-    },
-};
+```sh
+npm run lint
 ```

package/{components → bases}/PxBase.vue

@@ -1,3 +1,7 @@
+<!--
+    #VUE3 Deprecate
+-->
+
 <script>
 export default {
     methods: {

package/bases/PxBaseDate.vue

@@ -0,0 +1,49 @@
+<!--
+    #VUE3 Todo
+-->
+
+<script>
+/**
+ * Base class for managing a date-focused component. Exposes a v-model prop called date and a
+ * synced data value called dateValue. Both the v-model and :sync should work for two-way binding.
+ */
+
+export default {
+    model: {
+        prop: 'date',
+        event: 'changed',
+    },
+
+    props: {
+        /**
+         *  Publicly exposed date property (use .dateValue if modifying internally).
+         */
+        date: { type: Date, default: null },
+    },
+    data() {
+        return {
+            dateValue: this.date,
+        };
+    },
+    watch: {
+        date: {
+            handler(nv) {
+                this.dateValue = nv;
+            },
+        },
+        dateValue(nv) {
+            /**
+             * Fired when the date changes. Expected to primarily be used for :sync scenarios.
+             * @property {Date} nv The new date value.
+             */
+            this.$emit('update:date', nv);
+
+            /**
+             * Fired when the date changes.
+             * @property {Date} nv The new date value.
+             */
+            this.$emit('changed', nv);
+        },
+    },
+};
+</script>

package/bases/PxBaseIcon.vue

@@ -0,0 +1,32 @@
+<!--
+    #VUE3 Todo
+-->
+
+<!--
+    Adds properties that describe an icon that will ultimately be used with PxIcon. This can be used
+    as a mixin or just a guide for the correct pattern for expose PxIcon properties on a parent
+    component.
+
+    Usage:
+
+    <my-component>
+        <px-icon :icon="icon" v-bind="iconProps" />
+    </my-component>
+
+-->
+
+<script>
+export default {
+    props: {
+        /**
+         * The icon for the component, either the name of an app-level icon or else the svg src for an icon.
+         */
+        icon: { type: String, default: null },
+
+        /**
+         * Additional customization for the icon (an object containing attributes that will be bound on the PxIcon instance). (see PxIcon for details).
+         */
+        iconProps: { type: Object, default: null },
+    },
+};
+</script>

package/bases/PxBaseItems.vue

@@ -0,0 +1,105 @@
+<!--
+    #VUE3 Done (has breaking changes)
+
+    Provides basic items services for controls that maintain lists of items.
+
+-->
+
+<script>
+function getFromItem(item, propOrFunc) {
+    if (!item) {
+        return undefined;
+    }
+
+    if (typeof propOrFunc == 'string' && propOrFunc in item) {
+        return item[propOrFunc];
+    }
+
+    if (typeof propOrFunc == 'function') {
+        return propOrFunc(item);
+    }
+
+    return undefined;
+}
+
+export default {
+    props: {
+        items: { type: Array },
+
+        /**
+         * Value needed to get a unique id from a given item. Can either be a string representing
+         * the property name or a function that takes the item and returns the id.
+         */
+        itemsKey: { type: [String, Function], default: 'id' },
+
+        /**
+         * Value needed to get a string representation (label) for a given item. Can either be a
+         * string representing the property name or a function that takes the item and returns the id.
+         */
+        itemsLabel: { type: [String, Function], default: 'label' },
+
+        /**
+         * Value needed to determine whether an item has been disabled. Can either be a string
+         * representing the property name or a function that takes the item and returns the id.
+         */
+        itemsDisabled: { type: [String, Function], default: 'disabled' },
+    },
+    computed: {
+        itemKeys() {
+            if (this.items && Array.isArray(this.items)) {
+                return this.items.map(item => this.getItemKey(item));
+            }
+            return [];
+        },
+    },
+    methods: {
+        getItem(key) {
+            if (typeof key !== 'undefined') {
+                return this.items.find(item => this.getItemKey(item) === key);
+            }
+            return undefined;
+        },
+
+        getItemKey(item) {
+            if (!this.isValidItem(item)) {
+                return undefined;
+            }
+            return getFromItem(item, this.itemsKey);
+        },
+
+        getItemLabel(item) {
+            if (!this.isValidItem(item)) {
+                return undefined;
+            }
+            return getFromItem(item, this.itemsLabel);
+        },
+
+        getItemDisabled(item) {
+            if (!this.isValidItem(item)) {
+                return undefined;
+            }
+            return getFromItem(item, this.itemsDisabled);
+        },
+
+        getItemKeyLabel(key) {
+            const item = this.getItem(key);
+            if (item) {
+                return this.getItemLabel(item);
+            }
+            return undefined;
+        },
+
+        getItemKeyIndex(key) {
+            return (this.items || []).indexOf(this.getItem(key));
+        },
+
+        isValidItem(item) {
+            return !!this.items.includes(item);
+        },
+
+        isValidItemKey(key) {
+            return !!this.itemKeys.includes(key);
+        },
+    },
+};
+</script>