vueless 0.0.2 → 0.0.4

package/README.md

@@ -0,0 +1,174 @@
+## How to run the project locally
+
+- Install **node.js 16.XX** version (see [instructions](https://nodejs.org/en/download/package-manager/) for your OS).
+
+- Install globally [Yarn](https://classic.yarnpkg.com/lang/en/docs/install/#mac-stable):
+
+```bash
+npm install --global yarn
+```
+
+- Create project folder and clone files from Git into:
+
+```bash
+# download project from remote repository
+git clone origin git@gitlab.com:<project_name>.git
+
+# go to project folder
+cd <project_name>
+```
+
+- Install project dependencies (node_modules):
+
+```bash
+yarn install
+```
+
+- Create environment file:
+
+```bash
+#  for local environment
+cp .env.local.example .env.local
+```
+
+- Run the app in **development** mode:
+
+```bash
+yarn dev
+```
+
+- The project is ready!
+
+## REST API
+
+- Public URL: https://fine.gitbook.io/api/
+
+- Development URL (same but editable):
+
+  - URL: https://app.gitbook.com/s/-MAVM-6BL-A_fpwuMsE1/
+  - Login: i.ivan.gridnev@gmail.com
+  - Password: XZQnUtFEZ4v9PML
+
+Section **AUTH & APPS** contains **Main** application endpoints, while section **APP INSTANCE** contains **Business** application endpoints.
+
+
+## Additional commands
+
+- Open Storybook (frontend base UI components documentation):
+
+```bash
+# run Storybook in development mode (with docs and stories):
+# It's good for debugging components.
+yarn sb:dev-full
+
+# run Storybook in development mode (with docs only):
+yarn sb:dev
+
+# build Storybook (to publish in the web):
+yarn sb:build
+
+# Run the built application from a `/storybook-static` folder in production mode:
+yarn sb:preview
+```
+
+- Run code-style check / formatting:
+
+```bash
+# check code style (only show errors)
+yarn lint
+
+# check code style and fix all possible errors
+yarn lint:fix
+
+# check code style of given file paths (fail pipeline if at least 1 error or warning appears)
+yarn lint:ci
+```
+
+- Run auto tests:
+
+```bash
+# start unit tests
+yarn test:unit
+
+# start end to end tests
+yarn test:e2e
+
+# start end to end tests in headless mode (no UI)
+yarn test:e2e-ci
+```
+
+- Build application:
+
+```bash
+# for the dev / test / production servers
+cp .env.example .env
+
+yarn build
+# TIP: 📐
+# to analise and reduce the build size see the report.html in a project root folder.
+```
+
+- Run the built application from a `/dist` folder in **production mode**:
+
+```bash
+yarn preview
+```
+
+- Automated releases (new app release in GitLab and increase app version number):
+
+```bash
+# increase third app version number (0.0.X).
+yarn release
+
+# increase second app version number (0.X.0).
+yarn release:production
+
+# increase first app version number (X.0.0).
+release:production-major
+```
+
+- Update browserslist DB to the latest version (it changes yarn.lock only):
+
+```bash
+npx browserslist@latest --update-db
+```
+
+- **Note**: `yarn` automatically calls the` postinstall` command,
+  which generate components web-types for IDE (props autocomplete).
+If you need to do this manually, just use the command below:
+
+```bash
+node .mono/our.library.web-types-gen
+```
+
+## Capacitor (iOS & Android apps)
+
+- Update app src after `dist` or `capacitor.config.js` file changes:
+
+```bash
+npx cap copy
+```
+
+- Open iOS app locally:
+
+```bash
+npx cap open ios
+```
+
+- Open Android app locally:
+
+```bash
+npx cap open android
+```
+
+- Sync the app after new capacitor plugin installation:
+
+```bash
+npx cap sync
+```
+
+- Generate app icons and splash screens ([docs](https://github.com/ionic-team/capacitor-assets)):
+
+```bash
+npx @capacitor/assets generate --assetPath 'public/static/capacitor' --iconBackgroundColor '#FFFFFF' --iconBackgroundColorDark '#111827' --splashBackgroundColor '#F3F4F6' --splashBackgroundColorDark '#1F2937' --ios --android
+```

package/index.pcss

@@ -0,0 +1,3 @@
+@tailwind base;
+@tailwind components;
+@tailwind utilities;

package/package.json

@@ -1,20 +1,70 @@
 {
   "name": "vueless",
-  "version": "0.0.2",
-  "description": "Vue Styleless Component Framework",
+  "version": "0.0.4",
+  "license": "MIT",
+  "description": "Vue Styleless Component Framework.",
+  "homepage": "https://vueless.com",
+  "author": "Johnny Grid",
   "main": "index.js",
   "scripts": {
-    "test": "echo \"Error: no test specified\" && exit 1"
+    "lint": "eslint --ext .vue,.js,.ts --no-fix --ignore-path .eslintignore src/ .storybook/ tests/",
+    "lint:fix": "eslint --ext .vue,.js,.ts --fix --ignore-path .eslintignore src/ .storybook/ tests/",
+    "lint:ci": "eslint --ext .vue,.js,.ts --no-fix --ignore-path .eslintignore --max-warnings=0",
+    "release": "release-it patch --ci",
+    "release:production": "release-it minor --ci",
+    "release:production-major": "release-it major --ci",
+    "sb:dev-full": "STORYBOOK_FULL=1 storybook dev -p 6006 --no-open",
+    "sb:dev": "storybook dev -p 6006 --docs --no-open",
+    "sb:build": "NO_PWA=1 storybook build --docs",
+    "sb:preview": "vite preview --host --outDir=storybook-static",
+    "vueless:update": "yarn add -D file:../vite-plugin-vueless file:../vueless-storybook",
+    "postinstall": "node .web-types-gen"
+  },
+  "dependencies": {
+    "@kyvg/vue3-notification": "^3.2.1",
+    "@material-symbols/svg-500": "^0.14.3",
+    "@tailwindcss/forms": "^0.5.4",
+    "@uppy/core": "^3.3.1",
+    "@uppy/drag-drop": "^3.0.2",
+    "@uppy/vue": "^1.0.2",
+    "cva": "^1.0.0-beta.1",
+    "lodash-es": "^4.17.21",
+    "tailwind-merge": "^2.1.0",
+    "tailwindcss": "^3.3.3",
+    "vue-tippy": "^6.0.0-beta.0",
+    "vuedraggable": "^4.1.0",
+    "vuex": "^4.1.0"
+  },
+  "devDependencies": {
+    "@vitejs/plugin-vue": "^5.0.4",
+    "@vue/compiler-sfc": "^3.4.19",
+    "@vue/eslint-config-prettier": "^9.0.0",
+    "@vueless/storybook": "file:../vueless-storybook",
+    "autoprefixer": "^10.4.19",
+    "eslint": "^8.55.0",
+    "eslint-plugin-node": "^11.1.0",
+    "eslint-plugin-prettier": "^5.0.1",
+    "eslint-plugin-storybook": "^0.8.0",
+    "eslint-plugin-tailwindcss": "^3.14.0",
+    "eslint-plugin-vue": "^9.19.2",
+    "globby": "^13.2.2",
+    "postcss": "^8.4.7",
+    "prettier": "^3.1.0",
+    "prettier-eslint": "^16.3.0",
+    "vite": "^5.1.1",
+    "vite-plugin-compression": "^0.5.1",
+    "vite-plugin-eslint": "^1.8.1",
+    "vite-plugin-vueless": "file:../vite-plugin-vueless",
+    "vue": "^3.4.19",
+    "vue-i18n": "^9.9.1",
+    "vue-router": "^4.2.5"
   },
   "repository": {
     "type": "git",
     "url": "git+https://github.com/vuelessjs/vueless.git"
   },
-  "author": "Johnny Grid",
-  "license": "MIT",
   "bugs": {
     "url": "https://github.com/vuelessjs/vueless/issues"
   },
-  "homepage": "https://github.com/vuelessjs/vueless#readme",
   "web-types": "./web-types.json"
 }

package/postcss.config.js

@@ -0,0 +1,9 @@
+module.exports = {
+  plugins: {
+    "postcss-import": {},
+    "tailwindcss/nesting": {},
+    tailwindcss: {},
+    autoprefixer: {},
+    ...(process.env.NODE_ENV === "production" ? { cssnano: {} } : {}),
+  },
+};

package/readme/README.md

@@ -0,0 +1,8 @@
+# Vueless:
+
+See:
+* [installation.md](installation.md)
+* [customization.md](customization.md)
+
+## TODO: Create general readme later
+

package/{_readme → readme}/UNotify.md

@@ -40,7 +40,7 @@ duration: {
 
 ``` javascript
 positionClasses: {
-  page: ".mono-page-wrapper",
+  page: ".vueless-page-wrapper",
   aside: ".aside",
 },
 ```

package/{_readme → readme}/UTopLoader.md

@@ -1,8 +1,8 @@
 ## TopLoader config:
 
-Settings for an `UTopLoader` component (top stripe which appears when API request is pending).
+Settings for an `ULoaderTop` component (top stripe which appears when API request is pending).
 
-To use this layout, you need to import vuex store from `vueless/layout-ui.loader-top/store` and ` vueless/layout-ui.loader/store`.
+To use this layout, you need to import vuex store from `@vueless/layouts/ui.loader-top/store` and ` @vueless/layouts/ui.loader/store`.
 
 **color** – top stripe color.
 - type: String

package/readme/customization.md

@@ -0,0 +1,347 @@
+# Customisation
+
+## Overview
+
+To customize the look and feel of components change a default configuration in the `vueless.config.js`.
+
+## Colors
+
+### Predefined colors
+
+Components are based on a `brand` and a `gray` color. You can change them in your `vueless.config.js`.
+
+```js
+// vueless.config.js
+
+export default {
+  brand: "green",
+  gray: "zinc",
+};
+```
+
+As this module uses Tailwind CSS under the hood, 
+you can use any of the [Tailwind CSS colors](https://tailwindcss.com/docs/customizing-colors#color-palette-reference) or your own custom colors. 
+
+**By default:**
+* the `brand` color is `green`,
+* the `gray` color is `zinc`.
+
+### Custom colors
+
+When [using custom colors](https://tailwindcss.com/docs/customizing-colors#using-custom-colors) or [adding additional colors](https://tailwindcss.com/docs/customizing-colors#adding-additional-colors) through the `extend` key in your `tailwind.config.js`, 
+you'll need to make sure to define all the shades from `50` to `950` as most of them are used in the package components. 
+
+You can [generate your colors](https://tailwindcss.com/docs/customizing-colors#generating-colors) using tools such as https://uicolors.app for example.
+
+```js
+// tailwind.config.js
+
+export default {
+  theme: {
+    extend: {
+      colors: {
+        green: {
+          50: '#EFFDF5',
+          100: '#D9FBE8',
+          200: '#B3F5D1',
+          300: '#75EDAE',
+          400: '#00DC82',
+          500: '#00C16A',
+          600: '#00A155',
+          700: '#007F45',
+          800: '#016538',
+          900: '#0A5331',
+          950: '#052e16'
+        }
+      }
+    }
+  }
+}
+```
+
+### Opacity mode
+
+You can use `mode: "opacity"` to generate all the shades automatically by using `opacity` based on your brand color.
+
+```js
+// vueless.config.js
+
+export default {
+  brand: "orange",
+  gray: "slate",
+  mode: "opacity",
+};
+```
+
+You can set your own brand color in `HEX` format as well.
+
+```js
+// vueless.config.js
+
+export default {
+  brand: "#00C16A",
+  gray: "slate",
+  mode: "opacity",
+};
+```
+
+### Brand CSS Variable
+
+To provide dynamic brand color that can be changed at runtime, this module uses CSS variable.
+
+> We'd advise you to use that color in your components and pages, e.g. `text-brand dark:text-brand`, etc. 
+> so your app automatically adapts when changing your `vueless.config.js`.
+
+To change the brand color, you should call this function whatever you need:
+
+```js
+import { setBrandColor } from "vueless/service.ui";
+
+// set default brand color
+setBrandColor();
+
+// or set brand color from tailwind colors palette
+setBrandColor("red");
+
+// or set your own custom brand color
+setBrandColor("#00C16A");
+```
+
+The `brand` color also has a `DEFAULT` shade that changes based on the theme.
+It is `500` in light mode and `400` in dark mode.
+You can use it as a shortcut in your components and pages, e.g. `text-brand`, `bg-brand`, `focus-visible:ring-brand`, etc.
+
+> For custom hex color, there is only one shade for dark and light themes.
+
+### Smart Safelisting
+
+Components having a `color` prop like `UAvatar`, `UButton`, `URadioGroup`, `UCheckbox`, `UHeader` etc. 
+will use the `brand` or `grayscale` color by default, 
+but will handle all the colors defined in your `tailwind.config.ts` or the default Tailwind CSS colors.
+
+Variant classes of those components are defined with a syntax like `bg-{color}-500 dark:bg-{color}-400` so they can be used with any color. 
+However, this means that Tailwind will not find those classes and therefore will not generate the corresponding CSS.
+
+The library uses the [Tailwind CSS safelist](https://tailwindcss.com/docs/content-configuration#safelisting-classes) feature 
+to force the generation of component colors.
+
+The Vueless will **automatically** detect when you use one of those components with a color and will safelist it for you. 
+This means that if you use a `red` color for a UButton component, the `red` color classes will be safelisted for the UButton component only. 
+This will allow to keep the CSS bundle size as small as possible.
+
+If you bind a dynamic color to a component: `<UBadge :color="color" />`, `<UButton :color="statuses[button.status]" />`, etc. 
+You'll need to safelist the possible color values manually as well.
+
+```js [vueless.config.js]
+// vueless.config.js
+
+export default {
+  safelistColors: ["orange", "amber", "sky"], // applies for all components
+  component: {
+    UButton: {
+      safelistColors: ["red"], // applies only for UButton
+    }
+  }
+}
+```
+
+### Replacing safelist patterns
+
+In some specific cases you can replace safelist config as well:
+
+```js
+// vueless.config.js
+
+export default {
+  component: {
+    UButton: {
+      safelist: (colors) => [
+        { pattern: `bg-(${colors})-500`, variants: ["hover", "focus", "active"] },
+        { pattern: `text-(${colors})-500` },
+      ],
+    }
+  }
+};
+```
+
+## Components
+
+### `vueless.config.js`
+
+Components are styled with Tailwind CSS but classes are all defined in the default `configs/default.config.js` file 
+located in each component folder. You can override those in your own `vueless.config.js`.
+
+```js
+// vueless.config.js
+
+export default {
+  component: {
+    UButton: {
+      button: {
+        base: "bg-red-500 w-full",
+      }
+    }
+  }
+};
+```
+
+Thanks to [tailwind-merge](https://github.com/dcastil/tailwind-merge), the `vueless.config.js` is smartly merged with the default config. 
+This means you don't have to rewrite everything.
+
+You can change this behavior by changing `strategy` in your `vueless.config.js` to:
+* `override` – override default config by custom defined config (keeps only custom config and remove everything else).
+* `replace` – replace default config keys by custom defined config keys, (the rest classes takes from the default config).
+* `merge` – smartly merge custom defined classes with default config classes (default strategy).
+
+```js
+// vueless.config.js
+
+export default {
+  strategy: 'override',
+  component: {
+    UButton: {
+      button: {
+        base: "bg-red-500 w-full",
+      }
+    }
+  }
+};
+```
+
+### `config` prop
+
+Each component has a `config` prop that allows you to customize everything specifically.
+
+```jsx
+<template>
+  <UButton :config="{ button: { base: 'max-w-2xl' } }">
+    <slot />
+  </UButton>
+</template>
+```
+
+> You can find the default classes for each component under the `Config` section.
+
+Thanks to [tailwind-merge](https://github.com/dcastil/tailwind-merge), the `config` prop is smartly merged with the config. 
+This means you don't have to rewrite everything.
+
+For example, the default preset of the `UEmpty` component looks like this:
+
+```js
+{
+  wrapper: "flex flex-col items-center w-full bg-center",
+  header: "mb-4 flex justify-center",
+  footer: "mt-4 flex justify-center",
+  title: {
+    base: "mb-2 font-medium text-center",
+    variants: {
+      size: {
+        sm: "text-base",
+        md: "text-lg",
+        lg: "text-xl",
+      },
+    },
+  },
+  description: {
+    base: "text-center",
+    variants: {
+      size: {
+        sm: "text-sm",
+        md: "text-base",
+        lg: "text-lg",
+      },
+    },
+  },
+  defaultVariants: {
+    size: "md",
+  },
+}
+```
+
+To change the font of the `title`, you only need to write:
+
+```jsx
+<UEmpty 
+  title="The list is empty" 
+  :config="{ title: { base: 'font-bold' } }" 
+/>
+```
+
+This will smartly replace the `font-medium` by `font-bold` and prevent any class duplication and any class priority issue.
+
+You can change this behavior by setting `strategy` to `replace` or `override` inside the `config` prop:
+
+```jsx
+<UButton
+  label="Submmit"
+  :config="{
+    strategy: 'replace',
+    color: {
+      white: {
+        solid: 'bg-white dark:bg-gray-900'
+      }
+    }
+  }"
+/>
+```
+
+### `class` attribute
+
+You can also use the `class` attribute to add classes to the component.
+
+```vue
+<template>
+  <UButton label="Button" class="font-bold" />
+</template>
+```
+
+Again, with [tailwind-merge](https://github.com/dcastil/tailwind-merge), this will smartly merge the classes with the `config` prop and the global and default configs.
+
+### Default values
+
+Some component props like `size`, `color`, `variant`, etc. have a default value that you can override in your `vueless.config.js` 
+or by the `config` prop as well.
+
+```js
+// vueless.config.js
+
+export default {
+  component: {
+    UButton: {
+      defaultVariants: {
+        size: "lg",
+        color: "red",
+        variant: "secondary"
+      }
+    }
+  }
+};
+```
+
+## Icons
+
+The library supports three popular icon libraries:
+* `@material-symbols/svg-{weight}`, where {weight} is number from 100 to 700 (`@material-symbols/svg-500` is default). 
+* `bootstrap-icons`
+* `heroicons`
+
+> The package works only with SVG icons.
+
+### Icons safelist colors
+
+If you set some icon names dynamically in `UIcon` component, then them may be skipped on a build stage.
+To avoid this behavior and include the icons in the build, you can add them into a safelist.
+
+```js
+// vueless.config.js
+
+export default {
+  component: {
+    UIcon: {
+      safelistIcons: ["1k", "2d", "close"],
+    }
+  }
+};
+```
+
+> In this case, the regular and filled icon variants will be added into the build.