vueless 0.0.2 → 0.0.4

package/readme/installation.md

@@ -0,0 +1,139 @@
+# Installation
+Learn how to install and configure the package in your Vue app.
+
+## Quick Start
+
+1\. Install `vueless` to your project:
+
+```bash
+# npm
+npm install vueless
+
+# yarn
+yarn add vueless
+
+# pnpm
+pnpm add vueless
+```
+
+2\. Create `vueless.config.js` at the root of your project.
+
+```js
+export default {
+  color: {},
+  component: {},
+};
+```
+
+3\. Add vueless preset into `tailwind.config.js`.
+
+```js
+import { vuelessPreset } from "vueless/service.tailwind";
+
+export default {
+  presets: [vuelessPreset],
+  ...
+};
+```
+
+4\. Add Vueless Vite plugins into `vite.config.js`.
+
+```js
+import { Vueless, VuelessUnpluginComponents } from "vueless/plugin.vite";
+
+export default defineConfig({
+  plugins: [
+    ...
+    Vueless(),
+    VuelessUnpluginComponents(),
+  ],
+  ...
+})
+```
+
+5\. Configure your `package.json`.
+
+```json
+{
+  ...
+  "web-types": "vueless/web-types.json"
+}
+```
+
+Where:
+* `web-types` – add props and values autocompletion to your IDE.
+
+<br/>
+
+That's it! You can now use all the components in your Vue app ✨
+
+## IntelliSense
+If you're using **VSCode** or **JetBrains** IDEs (WebStorm, PHPStorm, etc..) you can configure autocompletion for the classes.
+
+**What you'll get:**
+* Autocompletion on typing.
+* Autocompletion on objects by prefixing them with `/*tw*/`
+* Autocompletion when using the `config` prop.
+
+**An example SFC using IntelliSense:**
+
+```jsx
+<template>
+  <UCard :config="config" />
+</template>
+
+<script setup>
+const config = /*tw*/ {
+  background: 'bg-white dark:bg-slate-900'
+}
+</script>
+```
+
+### VSCode
+* Install [Tailwind CSS IntelliSense](https://marketplace.visualstudio.com/items?itemName=bradlc.vscode-tailwindcss)
+  extension.
+* Set the plugin configuration below in the file `.vscode/settings.json`.
+
+```json
+{
+  "files.associations": {
+      "*.css": "tailwindcss"
+  },
+  "editor.quickSuggestions": {
+      "strings": true
+  },
+  "tailwindCSS.experimental.classRegex": [
+    ["config:\\s*{([^)]*)\\s*}", "[\"'`]([^\"'`]*).*?[\"'`]"],
+    ["/\\*tw\\*/\\s*{([^;]*)}", ":\\s*[\"'`]([^\"'`]*).*?[\"'`]"]
+  ],
+  "tailwindCSS.classAttributes": ["class", "className", "ngClass", "config"]
+}
+```
+
+
+### JetBrains IDEs
+* Check if [Tailwind CSS IntelliSense](https://www.jetbrains.com/help/webstorm/tailwind-css.html) 
+  already installed in the IDE, if not, install it in extensions.
+* Set the plugin configuration below in `Settings` > `Languages & Frameworks` > `Style Sheets` > `Tailwind CSS`.
+
+```json
+{
+  "includeLanguages": {
+    "javascript": "javascript"
+  },
+  "suggestions": true,
+  "classAttributes": ["class", "className", "ngClass", "config"],
+  "experimental": {
+    "classRegex": [
+      ["config:\\s*{([^)]*)\\s*}", "[\"'`]([^\"'`]*).*?[\"'`]"],
+      ["/\\*tw\\*/\\s*{([^;]*)}", ":\\s*[\"'`]([^\"'`]*).*?[\"'`]"]
+    ]
+  }
+}
+```
+
+
+
+
+
+

package/readme/storybook-pages/Customisation.mdx

@@ -0,0 +1,6 @@
+import { Markdown, Meta } from "@storybook/blocks";
+
+import customization from "../customization.md?raw"
+
+<Meta title="2. Customisation" />
+<Markdown className="markdown">{customization}</Markdown>

package/readme/storybook-pages/Installation.mdx

@@ -0,0 +1,7 @@
+import { Markdown, Meta } from "@storybook/blocks";
+
+import installation from "../installation.md?raw"
+
+<Meta title="1. Installation" />
+<Markdown className="markdown">{installation}</Markdown>
+

package/src/composable.ui/index.js

@@ -0,0 +1,395 @@
+import {
+  ref,
+  watchEffect,
+  getCurrentInstance,
+  toValue,
+  useAttrs,
+  Comment,
+  Text,
+  Fragment,
+} from "vue";
+import { cx, globalComponentConfig, strategy } from "../service.ui";
+
+const strategyType = {
+  merge: "merge",
+  replace: "replace",
+  overwrite: "overwrite",
+};
+
+/**
+  Merging component configs in a given sequence (bigger number = bigger priority):
+  1. Default component config
+  2. Custom global component config (/vueless.config.js)
+  3. Component config (:config="{...}" props)
+  4. Component classes (class="...")
+ */
+export default function useUI(defaultConfig = {}, propsConfigGetter = null, topLevelClassKey) {
+  const { name: componentName } = getCurrentInstance().type;
+  const globalConfig = globalComponentConfig[componentName];
+
+  const isStrategyValid = strategy && Object.values(strategyType).includes(strategy);
+  const vuelessStrategy = isStrategyValid ? strategy : strategyType.merge;
+
+  const [firstClassKey] = Object.keys(defaultConfig);
+  const config = ref({});
+  const attrs = useAttrs();
+
+  watchEffect(() => {
+    const propsConfig = propsConfigGetter && propsConfigGetter();
+
+    const mergedConfig = getMergedConfig({
+      defaultConfig,
+      globalConfig,
+      propsConfig,
+      vuelessStrategy,
+    });
+
+    config.value = mergeClassesIntoConfig(mergedConfig, topLevelClassKey || firstClassKey, attrs);
+  });
+
+  function getAttrs(configKey, options) {
+    const cvaClasses = options?.classes || "";
+    const isComponent = options?.isComponent;
+
+    const attrs = useAttrs();
+    const isDev = import.meta.env.DEV;
+    const vuelessAttrs = ref({});
+
+    const commonAttrs = {
+      ...attrs,
+      component: isDev && (attrs.component || componentName || null),
+      "config-key": isDev && (attrs["config-key"] || configKey || null),
+      "child-component": isDev && attrs.component ? componentName : null,
+      "child-config-key": isDev && attrs.component ? configKey : null,
+    };
+
+    // Delete value key to prevent v-model overwrite
+    delete commonAttrs.value;
+
+    watchEffect(() => {
+      const configKeyValue = config.value[configKey];
+      const isObject = typeof configKeyValue === "object";
+
+      const configAttrs = {
+        config: configKeyValue,
+        ...configKeyValue?.defaultVariants,
+      };
+
+      const isTopLevelClassKey = configKey === (topLevelClassKey || firstClassKey);
+
+      const attrClass = isTopLevelClassKey && !isComponent ? attrs.class : "";
+      const configKeyClass = isObject ? configKeyValue.base : configKeyValue;
+
+      vuelessAttrs.value = {
+        ...commonAttrs,
+        class: cx([configKeyClass, toValue(cvaClasses), attrClass]),
+        ...((isObject && configAttrs) || {}),
+      };
+    });
+
+    return vuelessAttrs;
+  }
+
+  return {
+    config,
+    getAttrs,
+    setColor,
+    hasSlotContent,
+  };
+}
+
+/**
+  Get merged config based on config merging strategy.
+  @param {Object} defaultConfig
+  @param {Object} globalConfig
+  @param {Object} propsConfig
+  @param {string} vuelessStrategy - vueless top level merge strategy.
+
+  @returns {Object}
+ */
+function getMergedConfig({ defaultConfig, globalConfig, propsConfig, vuelessStrategy }) {
+  defaultConfig = cloneDeep(defaultConfig);
+
+  const strategy =
+    !globalConfig && !propsConfig
+      ? strategyType.merge
+      : propsConfig?.strategy || globalConfig?.strategy || vuelessStrategy;
+
+  if (strategy === strategyType.merge) {
+    return mergeConfigs({ defaultConfig, globalConfig, propsConfig });
+  }
+
+  if (strategy === strategyType.replace) {
+    return mergeConfigs({ defaultConfig, globalConfig, propsConfig, isReplace: true });
+  }
+
+  if (strategy === strategyType.overwrite) {
+    const isGlobalConfig = globalConfig && Object.keys(globalConfig).length;
+    const isPropsConfig = propsConfig && Object.keys(propsConfig).length;
+
+    return isPropsConfig ? propsConfig : isGlobalConfig ? globalConfig : defaultConfig;
+  }
+}
+
+/**
+  Recursively merge config objects with removing tailwind classes duplicates.
+  @param {Object} defaultConfig
+  @param {Object} globalConfig
+  @param {Object} propsConfig
+  @param {Object} config - final merged config.
+  @param {boolean} isReplace - enables class replacement instead of merge.
+
+  @returns {Object}
+ */
+function mergeConfigs({
+  defaultConfig,
+  globalConfig,
+  propsConfig,
+  config = {},
+  isReplace = false,
+}) {
+  globalConfig = globalConfig || {};
+  propsConfig = propsConfig || {};
+
+  const isGlobalConfig = Object.keys(globalConfig).length;
+  const isPropsConfig = Object.keys(propsConfig).length;
+
+  // Add unique keys from defaultConfig to composedConfig
+  let composedConfig = cloneDeep(defaultConfig);
+
+  // Add unique keys from globalConfig to composedConfig
+  for (let key in globalConfig) {
+    if (!Object.keys(composedConfig).includes(key)) {
+      composedConfig[key] = globalConfig[key];
+    }
+  }
+
+  // Add unique keys from propsConfig to composedConfig
+  for (let key in propsConfig) {
+    if (!Object.keys(composedConfig).includes(key)) {
+      composedConfig[key] = propsConfig[key];
+    }
+  }
+
+  for (let key in composedConfig) {
+    if (isGlobalConfig || isPropsConfig) {
+      if (key === "strategy") {
+        config[key] = propsConfig[key] || globalConfig[key] || defaultConfig[key];
+      } else if (key === "defaultVariants") {
+        config[key] = { ...defaultConfig[key], ...globalConfig[key], ...propsConfig[key] };
+      } else if (key === "compoundVariants") {
+        config[key] = mergeCompoundVariants({
+          defaultConfig: composedConfig,
+          globalConfig,
+          propsConfig,
+          isReplace,
+          key,
+        });
+      } else {
+        const isObjectComposedConfig = typeof composedConfig[key] === "object";
+        const isObjectGlobalConfig = typeof globalConfig[key] === "object";
+        const isObjectPropsConfig = typeof propsConfig[key] === "object";
+
+        const isObject = isObjectComposedConfig || isObjectGlobalConfig || isObjectPropsConfig;
+        const isEmpty = composedConfig[key] === null;
+        const isIconName = /^.*(iconName|IconName)$/.test(key);
+        const isI18n = key === "i18n";
+
+        config[key] =
+          isObject && !isEmpty && !isI18n
+            ? mergeConfigs({
+                defaultConfig: stringToObject(composedConfig[key]),
+                globalConfig: stringToObject(globalConfig[key]),
+                propsConfig: stringToObject(propsConfig[key]),
+                config: stringToObject(composedConfig[key]),
+                isReplace,
+              })
+            : isReplace || isIconName || isI18n
+              ? propsConfig[key] || globalConfig[key] || defaultConfig[key]
+              : cx([defaultConfig[key], globalConfig[key], propsConfig[key]]);
+      }
+    } else {
+      config[key] = composedConfig[key];
+    }
+  }
+
+  return config;
+}
+
+/**
+  Turn simplified nested component config to regular config.
+  @param {Object | String} value
+  @returns {Object}
+ */
+function stringToObject(value) {
+  return typeof value === "object" ? value : { base: value };
+}
+
+/**
+  Merge CVA compound variants arrays.
+  @param {Object} defaultConfig
+  @param {Object} globalConfig
+  @param {Object} propsConfig
+  @param {string} key
+  @param {boolean} isReplace - enables class replacement instead of merge.
+
+  @returns {Array}
+ */
+function mergeCompoundVariants({ defaultConfig, globalConfig, propsConfig, key, isReplace }) {
+  if (
+    (globalConfig[key] && !Array.isArray(globalConfig[key])) ||
+    (propsConfig[key] && !Array.isArray(propsConfig[key])) ||
+    (defaultConfig[key] && !Array.isArray(defaultConfig[key]))
+  ) {
+    // eslint-disable-next-line no-console
+    console.error("CompoundVariants should be an array.");
+  }
+
+  let globalConfigUniqueItems = cloneDeep(globalConfig[key] || []);
+  let propsConfigUniqueItems = cloneDeep(propsConfig[key] || []);
+
+  const config = defaultConfig[key].map((defaultConfigItem) => {
+    /**
+     Compare two objects by keys for match.
+     @param {Object} configItem
+     @returns {Boolean}
+     */
+    function isSameItem(configItem) {
+      const hasConfigItemKeys = Object.keys(defaultConfigItem)
+        .map((key) => defaultConfigItem[key] === configItem[key] || key === "class")
+        .every((item) => !!item);
+
+      const hasDefaultConfigItemKeys = Object.keys(configItem)
+        .map((key) => defaultConfigItem[key] === configItem[key] || key === "class")
+        .every((item) => !!item);
+
+      return hasConfigItemKeys && hasDefaultConfigItemKeys;
+    }
+
+    /**
+     Find the same compound variant item in custom config if exist.
+     @param {Object} config
+     @returns {Object|undefined}
+     */
+    function findItem(config = []) {
+      const globalConfigUniqueItemIndex = globalConfigUniqueItems.findIndex(isSameItem);
+      const propsConfigUniqueItemIndex = propsConfigUniqueItems.findIndex(isSameItem);
+
+      if (~globalConfigUniqueItemIndex) {
+        globalConfigUniqueItems.splice(globalConfigUniqueItemIndex, 1);
+      }
+
+      if (~propsConfigUniqueItemIndex) {
+        propsConfigUniqueItems.splice(propsConfigUniqueItemIndex, 1);
+      }
+
+      return config.find(isSameItem);
+    }
+
+    const globalConfigItem = findItem(globalConfig[key]);
+    const propsConfigItem = findItem(propsConfig[key]);
+
+    return globalConfigItem || propsConfigItem
+      ? {
+          ...defaultConfigItem,
+          class: isReplace
+            ? propsConfigItem?.class || globalConfigItem?.class || defaultConfigItem.class
+            : cx([defaultConfigItem.class, globalConfigItem?.class, propsConfigItem?.class]),
+        }
+      : defaultConfigItem;
+  });
+
+  return [...config, ...globalConfigUniqueItems, ...propsConfigUniqueItems];
+}
+
+/**
+  Merge component classes from "class" attribute into final config.
+  @param {Object} config
+  @param {Object} attrs
+  @param {string} topLevelClassKey
+
+  @returns {Object}
+ */
+function mergeClassesIntoConfig(config, topLevelClassKey, attrs) {
+  if (typeof config[topLevelClassKey] === "object") {
+    config[topLevelClassKey].base = cx([config[topLevelClassKey]?.base, attrs.class]);
+  } else {
+    config[topLevelClassKey] = cx([config[topLevelClassKey], attrs.class]);
+  }
+
+  return config;
+}
+
+/**
+  Check if slot defined, and have a content.
+  @param slot
+  @param props
+
+  @returns {boolean}
+ */
+function hasSlotContent(slot, props = {}) {
+  const asArray = (arg) => (Array.isArray(arg) ? arg : arg != null ? [arg] : []);
+
+  const isVNodeEmpty = (vnode) => {
+    return (
+      !vnode ||
+      asArray(vnode).every(
+        (vnode) =>
+          vnode.type === Comment ||
+          (vnode.type === Text && !vnode.children?.length) ||
+          (vnode.type === Fragment && !vnode.children?.length),
+      )
+    );
+  };
+
+  return !isVNodeEmpty(slot?.(props));
+}
+
+/**
+ Deeply clone given object (same as lodash.cloneDeep).
+ @param {Object} entity
+ @param cache
+
+ @returns {Object}
+ */
+function cloneDeep(entity, cache = new WeakMap()) {
+  const referenceTypes = ["Array", "Object", "Map", "Set", "Date"];
+  const entityType = Object.prototype.toString.call(entity);
+
+  if (
+    !new RegExp(referenceTypes.join("|")).test(entityType) ||
+    entity instanceof WeakMap ||
+    entity instanceof WeakSet
+  ) {
+    return entity;
+  }
+
+  if (cache.has(entity)) {
+    return cache.get(entity);
+  }
+
+  const c = new entity.constructor();
+
+  if (entity instanceof Map) {
+    entity.forEach((value, key) => c.set(cloneDeep(key), cloneDeep(value)));
+  }
+
+  if (entity instanceof Set) {
+    entity.forEach((value) => c.add(cloneDeep(value)));
+  }
+
+  if (entity instanceof Date) {
+    return new Date(entity);
+  }
+
+  cache.set(entity, c);
+
+  return Object.assign(
+    c,
+    ...Object.keys(entity).map((prop) => ({ [prop]: cloneDeep(entity[prop], cache) })),
+  );
+}
+
+function setColor(classes, color) {
+  return classes?.replaceAll("{color}", color);
+}

package/src/service.tailwind/index.js

@@ -0,0 +1,114 @@
+import colors from "tailwindcss/colors";
+import forms from "@tailwindcss/forms";
+import vuelessConfig from "../../vueless.config";
+
+export const grayColors = ["slate", "gray", "zinc", "neutral", "stone"];
+export const brandColors = [
+  "brand",
+  "red",
+  "orange",
+  "amber",
+  "yellow",
+  "lime",
+  "green",
+  "emerald",
+  "teal",
+  "cyan",
+  "sky",
+  "blue",
+  "indigo",
+  "violet",
+  "purple",
+  "fuchsia",
+  "pink",
+  "rose",
+];
+
+export default class TailwindServiceDefault {
+  constructor() {
+    this.vuelessPreset = this.get();
+  }
+
+  /**
+   * Transform CSS variable with RGB numbers into CSS color.
+   * @returns {Function}
+   */
+  static twColorWithOpacity(variableName) {
+    return ({ opacityValue }) => {
+      return opacityValue !== undefined
+        ? `rgba(var(${variableName}), ${opacityValue})`
+        : `rgb(var(${variableName}))`;
+    };
+  }
+
+  /**
+   * Convert sting patterns to RegExp.
+   * @returns {Array} - TailwindCSS safelist.
+   */
+  static getSafelist() {
+    return JSON.parse(process.env.SAFELIST_JSON || "[]").map((rule) => ({
+      ...rule,
+      pattern: new RegExp(rule.pattern),
+    }));
+  }
+
+  /**
+   * Generates preset for TailwindCSS base on Vueless config.
+   * @returns {Object}
+   */
+  get() {
+    const isProd = process.env.NODE_ENV === "production";
+    const brandColor = TailwindServiceDefault.twColorWithOpacity("--color-brand");
+    const { brand, gray } = vuelessConfig;
+
+    let brandPalette = brandColors.includes(brand) ? colors[brand] : colors.green;
+    let grayPalette = grayColors.includes(gray) ? colors[gray] : colors.zinc;
+
+    if (brand === "grayscale") {
+      brandPalette = grayPalette;
+    }
+
+    const prodSafelist = TailwindServiceDefault.getSafelist();
+    const devSafelist = [
+      {
+        pattern: /(border|bg|text|ring)-(.*)-((50|[1-9]00|950)?)$/,
+        variants: ["hover", "focus", "focus-within", "active"],
+      },
+    ];
+
+    return {
+      content: [
+        "./index.html",
+        "./src/**/*.{js,ts,jsx,tsx,vue}",
+        "./vueless.config.{js,ts}",
+        "./node_modules/vueless/**/*.{js,ts,vue}",
+        // TODO: remove it after creating the package
+        "./.vueless/**/*.{js,ts,vue}",
+        "./.vueless-layouts/**/*.{js,ts,vue}",
+        "./.vueless-services/**/*.{js,ts,vue}",
+      ],
+      safelist: isProd ? prodSafelist : devSafelist,
+      theme: {
+        extend: {
+          colors: {
+            brand: { ...brandPalette, DEFAULT: brandColor },
+            gray: grayPalette,
+          },
+          spacing: {
+            "safe-top": "env(safe-area-inset-top)",
+            "safe-bottom": "env(safe-area-inset-bottom)",
+            "safe-left": "env(safe-area-inset-left)",
+            "safe-right": "env(safe-area-inset-right)",
+            "mobile-menu-height": "3.5rem",
+          },
+          fontSize: {
+            "2xs": ["0.625rem", "0.875rem"], //  10px
+          },
+        },
+      },
+      plugins: [forms],
+    };
+  }
+}
+
+export const { vuelessPreset } = new TailwindServiceDefault();