Vuestic contribution manual

[m0ksem]

Docs for contributors.

In progress and must be moved to vuestic.dev as page, not issue.

[m0ksem]

Overview modules diagram

flowchart RL
    subgraph "@vuestic/nuxt"
        module
        runtime("runtime (plugin)")
    end

    subgraph "@vuestic/docs"
        page-configs
        docs-components("components")
        locales
    end

    subgraph "extensions"
        subgraph "ag-grid"
        end
    end

    subgraph vuestic-ui
        direction LR
  
        components
        composables
        utils

        subgraph styles 
        direction TB
             subgraph essential
              css-variables
            end
         
            subgraph modules
              typography
              grid
              d("reset (normalize)")
            end
           
            subgraph resources
              mixins
              variables
            end
        end

        subgraph services
        direction LR
            global-config
            color-config
            component-config
            icon-config
        end

        subgraph plugin
            direction LR
            createVuestic
            createVuesticEssential
        end
    end

Loading

Use case

• Install vuestic
  • Add to existing or new project with vue-cli
  • Install as nuxt module
  • Install manually
    • Install with CDN iife build (no cases yet, but seems to be possible)
  • Install extensions
    • Install ag-grid theme
• Configure vuestic
  • Change default colors and/or add own colors
  • Change components default props
  • Configure icons
    • Configure IconsService to handle any icon font
    • Add own iconAliases
  • Tree-shake
    • Choose only few components to use, do not budle others
    • Choose only few (or remove completely) css modules.
    • Choose only few services to use
• Use ?

[m0ksem]

Components

File structure

va-[component-name]  // component directory
|- 📁 components // inner components specific to this component
|---- 📝Va[SubComposableName].vue
|- 📁 hooks // specific composables to this component
|---- 📝use[ComposableName].ts 
|- 📁 plugins // plugins that required for this component (usually you don't need plugin)
|---- index.ts // here should be exported all plugins using named exports 
|- 📁 tests
|---- 📝 Va[ComponentName].spec.js // compoennt tests
|---- 📝 use[ComposableName].spec.js // compoennt tests
|- 📁 utils  // Prefer using composables, but store here stuff to make component clean (not recomended folder)
|- 📝 _variables.scss // component css variables
|- 📝 index.ts // all stuff that will be exported from `vuestic-ui`
|- 📝 types.ts // specific types for this component
|- 📝 Va[ComponentName].demo.vue // component demo
|- 📝 Va[ComponentName].vue // component itself

Exports

From ./types.ts must be exported all types, that you need to have. e.g. prop types, emit events etc.
From ./index.ts must be exported (using named exports) component and it's subcomponents. All from this file must be exported in /src/components/index.ts
From ./plugin/index.ts must be exported plugin, that use defineVuesticPlugin with named export. This plugin will be available in vuestic-ui root exports.

Warning
./plugins is still experimental folder, you likely don't need to use it.

WithTransportConfig

withTransportConfig - helper function from transport-config service that allow user to provide default prop values.

Note
Make sure all component use withTransportConfig wrapper.

Styleguide

We write all component in Composition API. This allows use to re-use a lot of functional from composables.
Checklist:

• Provide component name with Va prefix;
• Provide va- prefix for CSS variables;
• CSS variables must be used to change look of component. E.g. don't use css variables for styles that are not going to be changed by user;
• Use props from composables if needed;
• Type complex types with PropType;
• Prefer default value for props, instead of required;
• Make sure component support stateful mode;
• Explicitly provide emits filed. We use it in documentation later;
• Use as much composables as you can.;
• Remember about SSR. Use SSR-friendly composables like useClickOnly, useDocument, useEvent etc;
• Remember that user can access component methods with ref. Return methods like focus, validate from setup function;
• Follow CSS variables guide;
• Use css-variables only if you think that this can be helpful for user:
  good: color, font, border
  bad: align-items, top, left
• Use BEM;
• Use SCSS mixins;
• Do not use scoped styles in components;
• Follow Accessibility guide e.g. do not forget about hover state, aria attributes, use semantic html;

[m0ksem]

Composables

Composable - function, that will be injected in component in setup function. Usually it provides reactive variables, computeds or methods.

Great example of composables: https://vueuse.org/

Checklist:

• Start composable name with use;
• Write composable in one file. If you have large composable, split it in multiple small composables. If these composables useless without each other, use folder with index.ts and export one composable from here;
• Composable can return one object (reactive or ref) or object that contain refs, methods, computeds;
• It's okay to reuse composables:

export useDocument = () => useClientOnly(() => document)

• Export (or even re-export) types in composable.
• Export all in /src/composables/index.ts;
• Write tests under /src/composables/tests/use[ComposableName].spec.ts

[m0ksem]

Styles

There are three types of style

• CSS modules - css file with styles, usually with global styles. CSS modules must be independent and produce one feature. e.g. typography, grid-system, normalize;
• SCSS resources - there must be only SCSS variables (! prefer CSS variables instead) or SCSS mixins. They can be split in modules, but no style must be included in these files.
• Essential - css, that must be included in user's app. e.g. css-variables.

File structure

Note
This is not true yet, we want this structure later.

/styles 
|- 📁 essential
|---- 📝css-variables.scss
|---- 📝index.scss
|- 📁 modules // specific composables to this component
|---- 📁[module-name]
|--------- 📝 index.scss
|--------- 📝 mixins.scss
|--------- 📝 variables.scss
|---- 📝 typography.scss
|---- 📝 index.scss
|- 📁 resources
|---- 📝 variables.scss
|---- 📝 mixins.scss
|---- 📝 index.scss

[m0ksem]

Services

Ideally all services must be independent and user must be able to remove them easily, but here two exceptions: GlobalConfig, ColorConfig - these two are essential for vuestic components, at least for now.

File structure

/services/[service-name]
|-  📁 tests 
|-  📁 plugin
|---- 📝 index.ts // plugin with `defineVuesticPlugin`. Plugin later will be used by user in tree-shaking
|-- 📝 index.ts // all service types for export
|-- 📝 index.ts // all services exports

Still not sure how standartize services...