@naptics/vue-collection 0.0.2 → 0.0.4

package/README.md

@@ -2,26 +2,134 @@
 
 Vue Collection is a collection of styled and fully functional Vue components which can easily be integrated into our projects.
 
-## Showroom 🎆
+## Demo Page 🎆
 
-You can take a look at all components on [Gitlab Pages](https://naptx.gitlab.io/libraries/vue-collection/).
+You can take a look at all components on [GitHub Pages](https://naptics.github.io/vue-collection/).
 
-## Integrate Vue Collection into a new project 🔨
+## Project Setup 🚧
 
-1. Create a new vue-project with `npm init vue@latest`. Add at least typescript, jsx, vue-router, eslint and prettier.
+This section shows how to create a new Vue project with the recommended tech-stack to be ready to install Vue Collection afterwards.
+
+1. Create a new vue-project with `npm init vue@latest`. Add at least typescript, jsx, eslint and prettier.
 2. Remove boilerplate code.
 3. Follow the instructions to [install tailwind](https://tailwindcss.com/docs/installation/using-postcss).
     - `npm install -D tailwindcss postcss autoprefixer`
     - `npx tailwindcss init`
     - ... follow the further instructions
-    - When creating the App.css add contents of this repo's `App.css`
-4. Add tailwind forms with `npm install -D @tailwindcss/forms`
-5. Copy the tailwind configuration `tailwind.config.js` to your project.
-6. Add other dependencies with `npm install @headlessui/vue @heroicons/vue vue-i18n awesome-phonenumber @popperjs/core`
-7. Copy files from `.vscode` to your project. Remove `.vscode/settings.json` file from `.gitignore`. Copy `.prettierrc` to your project.
-8. Make sure typescript config is correct. Double check with this repo.
-9. Copy the contents of `src/components/base` (without the tests), `src/i18n` and `src/utils/vue-collection` to your project.
-10. Create your `App.tsx` file (you probably deleted earlier) and add a router view to the app. Link the `App.css` to it. Then you're ready to add a `HomeView` and link it to the router. Make sure to always use the `createView` and `createComponent` functions defined in the `src/utils/vue` file.
-11. Close your project and reopen it again. Now all weird warnings should go away.
-12. You're ready to go: Run your app with `npm run dev`.
-13. Don't forget to configure primary, secondary and default color in `tailwind.config.js`. Also choose which classes are white-listed.
+4. Add tailwind forms with `npm install -D @tailwindcss/forms`.
+5. Add other dependencies with `npm install @heroicons/vue vue-i18n`
+6. Copy files from `.vscode` to your project. Remove `.vscode/settings.json` file from `.gitignore`. Copy `.prettierrc` to your project.
+7. Make sure typescript config is correct. Double check with this repo.
+
+## Installation Guide 🔨
+
+These are the steps to add Vue Collection to an existing project. You may have to go through the steps of `Project Setup` and check if you have the neccesary (peer-)dependencies installed.
+
+1. Go to [npmjs.com](https://npmjs.com), sign in with naptics and create a new read-only classic access token.
+2. Save your access token under `~/.npmrc` with the following content, replacing `YOUR_TOKEN` with the access token.
+
+```
+//registry.npmjs.org/:_authToken=YOUR_TOKEN
+```
+
+3. Install Vue Collection with `npm i @naptics/vue-collection`.
+4. Add tailwind config -> See below
+5. Register i18n provider -> See below
+
+## Create new components
+
+After you have installed Vue Collection, you can start building components using the `createComponent` and the `createView` funcitions, which are exported by Vue Collection. They enforce you to only use the neccesary API provided by Vue and create components in a uniform way.
+
+## Tailwind Config
+
+With this tailwind config file, Vue Collection works as expected. Feel free to change the `default`, `primary` and `secondary` colors and add whatever is needed in your project.
+
+```js
+// tailwind.config.js
+
+/* eslint-disable no-undef */
+const colors = require('tailwindcss/colors')
+
+const unresolvedConfig = require('tailwindcss/defaultConfig')
+const resolveConfig = require('tailwindcss/resolveConfig')
+const config = resolveConfig(unresolvedConfig)
+
+const allShades = '50|100|200|300|400|500|600|700|800|900'
+const usedColors = 'default|primary|secondary|green|red|yellow|blue'
+const smallSizes = '1|2|3|4|5|6|7|8|9|10|11|12|14|16|18|20'
+
+/** @type {import('tailwindcss').Config} */
+module.exports = {
+    content: ['./src/**/*.{tsx,ts}', './node_modules/@naptics/vue-collection/**/*.{jsx,js}'],
+    safelist: [
+        {
+            pattern: new RegExp(`^(bg|text)-(${usedColors})-(${allShades})$`),
+            variants: ['hover'],
+        },
+        {
+            pattern: new RegExp(`^ring-(${usedColors})-(${allShades})$`),
+            variants: ['focus-visible'],
+        },
+        {
+            pattern: new RegExp(`^(w|h)-(${smallSizes})$`),
+        },
+    ],
+    theme: {
+        extend: {
+            colors: {
+                default: colors.slate,
+                primary: colors.violet,
+                secondary: colors.fuchsia,
+            },
+            minHeight: config.theme.spacing,
+        },
+    },
+    plugins: [require('@tailwindcss/forms')],
+}
+```
+
+## Register i18n Provider
+
+These are two sample files, how the i18n provider can be registered by using `vue-i18n`. The translation files of Vue Collection have to be added to the i18n provider in order for the Vue Collection components to work properly.
+
+```ts
+// src/i18n/index.ts
+
+import en from './en'
+import de from './de'
+import { createI18n } from 'vue-i18n'
+import { registerTranslationProvider } from '@naptics/vue-collection/i18n'
+
+const i18n = createI18n({
+    legacy: false,
+    locale: 'de',
+    messages: {
+        en,
+        de,
+    },
+})
+
+registerTranslationProvider({
+    trsl(key, params) {
+        return i18n.global.t(key, params == null ? {} : params)
+    },
+    trslc(key, count, params) {
+        const newCount = count ?? 0
+        const newParams = { n: newCount, ...params }
+        return i18n.global.t(key, newParams, { plural: newCount })
+    },
+})
+```
+
+```ts
+// src/i18n/de.ts
+
+import vueCollection from '@naptics/vue-collection/i18n/de/vue-collection.json'
+
+const de = {
+    ['vue-collection']: vueCollection,
+    // other translation files
+}
+
+export default de
+```

package/components/NAlert.js

@@ -0,0 +1,81 @@
+import { createVNode as _createVNode } from "vue";
+import { createComponent, createProps } from '../utils/component';
+import { CheckCircleIcon, ExclamationCircleIcon, InformationCircleIcon, XMarkIcon } from '@heroicons/vue/24/solid';
+import { computed } from 'vue';
+import NIconButton from './NIconButton';
+import NLoadingIndicator from './NLoadingIndicator';
+export const nAlertProps = createProps({
+  /**
+   * The variant of the alert. This defines its color and icon.
+   */
+  variant: {
+    type: String,
+    default: 'success'
+  },
+  /**
+   * The text of the alert.
+   */
+  text: String,
+  /**
+   * If set to `true` the X-button of the alert is hidden.
+   */
+  hideX: Boolean,
+  /**
+   * This is called, when the X-button is clicked.
+   */
+  onDismiss: Function
+});
+/**
+ * The `NAlert` is a fully styled alert with multiple variants.
+ * It can be used as a normal blocking element or as part of an alert queue.
+ */
+export default createComponent('NAlert', nAlertProps, props => {
+  const variant = computed(() => VARIANTS[props.variant]);
+  return () => _createVNode("div", {
+    "class": `rounded-md p-3 shadow-lg bg-${variant.value.color}-50`
+  }, [_createVNode("div", {
+    "class": "flex items-center"
+  }, [_createVNode("div", {
+    "class": "flex flex-shrink-0 items-center"
+  }, [variant.value.icon()]), _createVNode("div", {
+    "class": "ml-3 flex-grow"
+  }, [_createVNode("p", {
+    "class": `text-sm font-medium text-${variant.value.color}-900`
+  }, [props.text])]), !props.hideX && _createVNode("div", {
+    "class": "flex items-center flex-shrink-0 ml-3"
+  }, [_createVNode(NIconButton, {
+    "color": variant.value.color,
+    "size": 5,
+    "icon": XMarkIcon,
+    "onClick": props.onDismiss
+  }, null)])])]);
+});
+const icon = (icon, color) => () => _createVNode(icon, {
+  "class": `h-5 w-5 text-${color}-500`
+}, null);
+const VARIANTS = {
+  success: {
+    icon: icon(CheckCircleIcon, 'green'),
+    color: 'green'
+  },
+  info: {
+    icon: icon(InformationCircleIcon, 'blue'),
+    color: 'blue'
+  },
+  warning: {
+    icon: icon(ExclamationCircleIcon, 'yellow'),
+    color: 'yellow'
+  },
+  error: {
+    icon: icon(ExclamationCircleIcon, 'red'),
+    color: 'red'
+  },
+  loading: {
+    icon: () => _createVNode(NLoadingIndicator, {
+      "color": "blue",
+      "size": 7,
+      "shade": 500
+    }, null),
+    color: 'blue'
+  }
+};

package/components/NBadge.js

@@ -0,0 +1,57 @@
+import { createVNode as _createVNode } from "vue";
+import { createComponent, createProps } from '../utils/component';
+import NTooltip, { mapTooltipProps, nToolTipPropsForImplementor } from './NTooltip';
+export const nBadgeProps = createProps({
+  /**
+   * The text of the badge. Can alternatively be passed in the default slot.
+   */
+  text: String,
+  /**
+   * The text size, a standard tailwind text-size class.
+   */
+  textSize: {
+    type: String,
+    default: 'text-sm'
+  },
+  /**
+   * The color of the badge.
+   */
+  color: {
+    type: String,
+    default: 'primary'
+  },
+  /**
+   * The background shade of the badge.
+   */
+  shade: {
+    type: Number,
+    default: 200
+  },
+  /**
+   * The text shade of the badge.
+   */
+  textShade: {
+    type: Number,
+    default: 900
+  },
+  /**
+   * If set to `true` the badges text is all-caps. Default is `true`.
+   */
+  allCaps: {
+    type: Boolean,
+    default: true
+  },
+  ...nToolTipPropsForImplementor
+});
+/**
+ * The `NBadge` is a styled element to wrap a text.
+ */
+export default createComponent('NBadge', nBadgeProps, (props, {
+  slots
+}) => {
+  return () => _createVNode(NTooltip, mapTooltipProps(props), {
+    default: () => [_createVNode("div", {
+      "class": ['px-2 py-1 rounded-md font-semibold shadow', `${props.textSize} bg-${props.color}-${props.shade} text-${props.color}-${props.textShade}`, props.allCaps ? 'uppercase' : '']
+    }, [slots.default?.() || props.text])]
+  });
+});

package/components/NBreadcrub.js

@@ -0,0 +1,66 @@
+import { createVNode as _createVNode, Fragment as _Fragment } from "vue";
+import { createComponent, createProps } from '../utils/component';
+import { ChevronRightIcon } from '@heroicons/vue/24/solid';
+import NLink from './NLink';
+export const nBreadcrumbProps = createProps({
+  /**
+   * The items of the breadcrumb.
+   */
+  items: {
+    type: Array,
+    default: () => []
+  },
+  /**
+   * The color of the breadcrumbs text and icons.
+   */
+  color: {
+    type: String,
+    default: 'primary'
+  },
+  /**
+   * The text-size of the breadcrumb labels.
+   */
+  textSize: {
+    type: String,
+    default: 'text-base'
+  },
+  /**
+   * The icon which is used as a seperator between two breadcrumb items.
+   */
+  icon: {
+    type: Function,
+    default: ChevronRightIcon
+  },
+  /**
+   * The size of the icon in tailwind units.
+   */
+  iconSize: {
+    type: Number,
+    default: 5
+  },
+  /**
+   * A slot the replace the breadcrumb labels.
+   */
+  item: Function,
+  /**
+   * A slot to replace the separators between the breadcrumb labels.
+   * The passsed item is the item before the seperator.
+   */
+  seperator: Function
+});
+/**
+ * The `NBreadcrumb` is a styled breadcrumb which can be used as a navigation in hierarchical views.
+ */
+export default createComponent('NBreadcrumb', nBreadcrumbProps, props => {
+  return () => _createVNode("div", {
+    "class": "flex flex-wrap items-center"
+  }, [props.items.map((item, index) => _createVNode(_Fragment, null, [props.item?.(item, index) || _createVNode(NLink, {
+    "textSize": props.textSize,
+    "route": item.route,
+    "color": props.color
+  }, {
+    default: () => [item.label]
+  }), index < props.items.length - 1 && (props.seperator?.(item, index) || _createVNode(props.icon, {
+    "class": `mx-2 w-${props.iconSize} h-${props.iconSize} text-${props.color}-500`
+  }, null))]))]);
+});

package/components/NButton.js

@@ -0,0 +1,65 @@
+import { createVNode as _createVNode } from "vue";
+import { createComponent, createProps } from '../utils/component';
+import { computed } from 'vue';
+import NLoadingIndicator from './NLoadingIndicator';
+import NTooltip, { mapTooltipProps, nToolTipPropsForImplementor } from './NTooltip';
+export const nButtonProps = createProps({
+  /**
+   * The color of the button.
+   */
+  color: {
+    type: String,
+    default: 'primary'
+  },
+  /**
+   * The html attribute, which indicates the type of the button.
+   */
+  type: {
+    type: String,
+    default: 'button'
+  },
+  /**
+   * If set to `true` the button is disabled and no interaction is possible.
+   */
+  disabled: Boolean,
+  /**
+   * If set to `true` the button will show a loading animation.
+   * Setting `loading` to `true` will also disable the button.
+   */
+  loading: Boolean,
+  /**
+   * If set to `true` the button will appear smaller.
+   */
+  small: Boolean,
+  /**
+   * This is called, when the button is clicked.
+   */
+  onClick: Function,
+  ...nToolTipPropsForImplementor
+});
+/**
+ * The `NButton` is a styled button.
+ */
+export default createComponent('NButton', nButtonProps, (props, {
+  slots
+}) => {
+  const isDisabled = computed(() => props.loading || props.disabled);
+  return () => _createVNode(NTooltip, mapTooltipProps(props), {
+    default: () => [_createVNode("button", {
+      "disabled": isDisabled.value,
+      "type": props.type,
+      "class": [`block w-full font-medium rounded-md focus:outline-none focus-visible:ring-2 shadow text-${props.color}-900 relative`, isDisabled.value ? `bg-${props.color}-100 text-opacity-20 cursor-default` : `bg-${props.color}-200 hover:bg-${props.color}-300 focus-visible:ring-${props.color}-500`, props.small ? 'py-1 px-2 text-xs' : 'py-2 px-4 text-sm'],
+      "onClick": props.onClick
+    }, [_createVNode("span", {
+      "class": {
+        'opacity-10': props.loading
+      }
+    }, [slots.default?.()]), props.loading && _createVNode("div", {
+      "class": "absolute inset-0 flex items-center justify-center opacity-50"
+    }, [_createVNode(NLoadingIndicator, {
+      "color": props.color,
+      "size": props.small ? 4 : 6,
+      "shade": 600
+    }, null)])])]
+  });
+});

package/components/NCheckbox.js

@@ -0,0 +1,42 @@
+import { createVNode as _createVNode } from "vue";
+import { createComponent, createProps } from '../utils/component';
+import { vModelProps } from '../utils/vModel';
+import { nextTick, ref } from 'vue';
+export const nCheckboxProps = createProps({
+  ...vModelProps(Boolean),
+  /**
+   * The color of the checkbox.
+   */
+  color: {
+    type: String,
+    default: 'primary'
+  },
+  /**
+   * If set to `true` the checkbox is disabled and no interaction is possible.
+   */
+  disabled: Boolean
+});
+/**
+ * The `NCheckbox` is a styled checkbox.
+ */
+export default createComponent('NCheckbox', nCheckboxProps, props => {
+  const toggle = () => {
+    props.onUpdateValue?.(!props.value);
+    forceUpdate();
+  };
+  const checkBoxRef = ref();
+  const updateKey = ref(0);
+  const forceUpdate = () => {
+    updateKey.value += 1;
+    nextTick(() => checkBoxRef.value?.focus());
+  };
+  return () => _createVNode("input", {
+    "type": "checkbox",
+    "ref": checkBoxRef,
+    "checked": props.value,
+    "disabled": props.disabled,
+    "onClick": toggle,
+    "key": updateKey.value,
+    "class": [`h-5 w-5 border-default-300 rounded focus:outline-none focus:ring-0 focus-visible:ring-2 focus-visible:ring-${props.color}-500`, props.disabled ? `cursor-default bg-default-100 text-${props.color}-200` : `cursor-pointer text-${props.color}-400`]
+  }, null);
+});

package/components/NCheckboxLabel.js

@@ -0,0 +1,39 @@
+import { createVNode as _createVNode } from "vue";
+import { createComponent, createProps } from '../utils/component';
+import NCheckbox, { nCheckboxProps } from './NCheckbox';
+export const nCheckboxLabelProps = createProps({
+  ...nCheckboxProps,
+  /**
+   * The title of the checkbox.
+   */
+  title: String,
+  /**
+   * The description of the checkbox.
+   */
+  description: String,
+  /**
+   * If set to `true`, a smaller margin is applied between the label and the checkbox.
+   */
+  compact: Boolean
+});
+/**
+ * The `NCheckboxLabel` is a checkbox with a title and a description.
+ */
+export default createComponent('NCheckboxLabel', nCheckboxLabelProps, props => {
+  const toggleValue = () => {
+    if (!props.disabled) props.onUpdateValue?.(!props.value);
+  };
+  return () => _createVNode("div", {
+    "class": "flex items-center"
+  }, [_createVNode(NCheckbox, props, null), _createVNode("div", {
+    "class": `${props.compact ? 'ml-2' : 'ml-3'} text-sm`
+  }, [_createVNode("label", {
+    "onClick": toggleValue,
+    "class": ['font-medium select-none', props.disabled ? 'text-default-300' : 'text-default-700 cursor-pointer']
+  }, [props.title]), _createVNode("p", {
+    "class": props.disabled ? 'text-default-300' : 'text-default-500'
+  }, [_createVNode("span", {
+    "onClick": toggleValue,
+    "class": ['select-none', props.disabled ? '' : 'cursor-pointer']
+  }, [props.description])])])]);
+});

package/components/NCrudModal.js

@@ -0,0 +1,105 @@
+import { mergeProps as _mergeProps, createVNode as _createVNode } from "vue";
+import { trsl } from '../i18n';
+import { createComponent, createProps } from '../utils/component';
+import { ref } from 'vue';
+import NButton from './NButton';
+import NDialog from './NDialog';
+import NFormModal, { nFormModalProps } from './NFormModal';
+export const nCrudModalProps = createProps({
+  ...nFormModalProps,
+  /**
+   * The text of the remove-button.
+   */
+  removeText: {
+    type: String,
+    default: trsl('vue-collection.action.remove')
+  },
+  /**
+   * The color of the remove-button.
+   */
+  removeColor: {
+    type: String,
+    default: 'red'
+  },
+  /**
+   * The title of the dialog which appears when clicking on the remove-button.
+   */
+  removeDialogTitle: String,
+  /**
+   * The text of the dialog which appears when clicking on the remove-button.
+   */
+  removeDialogText: String,
+  /**
+   * The variant of the dialog which appears when clicking on the remove-button. Default is `remove`.
+   */
+  removeDialogVariant: {
+    type: String,
+    default: 'remove'
+  },
+  /**
+   * The text of the dialog's ok-button. Is already set by the `removeDialogVariant` but can be overridden.
+   */
+  removeDialogOkText: String,
+  /**
+   * If set to `true` the modal will close itself when `onRemove` is called.
+   */
+  closeOnRemove: {
+    type: Boolean,
+    default: true
+  },
+  /**
+   * This is called, when the remove-button has been clicked and the dialog has been accepted.
+   */
+  onRemove: Function
+});
+/**
+ * The `NCrudModal` is a {@link NFormModal} which has some convenience features for a CRUD-scenario.
+ * It has an integrated remove-button with a user-dialog to remove the editing element.
+ * When the dialog is accepted `onRemove` is called.
+ */
+export default createComponent('NCrudModal', nCrudModalProps, (props, {
+  slots
+}) => {
+  const removeDialog = ref();
+  const remove = () => {
+    removeDialog.value?.show().then(result => {
+      if (result) {
+        props.onRemove?.();
+        if (props.closeOnRemove) props.onUpdateValue?.(false);
+      }
+    });
+  };
+  return () => _createVNode(NFormModal, _mergeProps(props, {
+    "footer": props.footer || (({
+      ok,
+      cancel
+    }) => _createVNode("div", {
+      "class": "flex justify-between"
+    }, [_createVNode("div", null, [_createVNode(NButton, {
+      "color": props.removeColor,
+      "onClick": remove
+    }, {
+      default: () => [props.removeText]
+    })]), _createVNode("div", null, [_createVNode(NButton, {
+      "color": props.cancelColor,
+      "onClick": cancel
+    }, {
+      default: () => [props.cancelText]
+    }), _createVNode(NButton, {
+      "color": props.okColor,
+      "onClick": ok,
+      "class": "ml-2",
+      "disabled": props.okDisabled
+    }, {
+      default: () => [props.okText]
+    })])]))
+  }), {
+    default: () => [slots.default?.(), _createVNode(NDialog, {
+      "ref": removeDialog,
+      "variant": props.removeDialogVariant,
+      "title": props.removeDialogTitle,
+      "text": props.removeDialogText,
+      "okText": props.removeDialogOkText
+    }, null)]
+  });
+});