@unraid/shared-components

shared-components

https://unraid.github.io/shared-components/

Usage Instructions

Add to your Unraid Vue.js project. Note that you must have access to the Unraid NPM Org and have an Access Token added to your ENV that has the correct permissions.

npm i @unraid/shared-components

Animated Unraid Logo Loader

<template>
    <div class="tw-flex tw-flex-wrap tw--mx-3">
        <div v-if="loading" class="tw-w-full tw-flex tw-justify-center tw-p-16">
            <unraid-loading class="tw-max-w-140px tw-px-3" />
        </div>
        <some-fancy-component v-else />
    </div>
</template>

<script>
import { UnraidLoading } from '@unraid/shared-components';
…
export default {
    …
    components: {
      UnraidLoading,
      …
    },
    …
};
</script>

SVGs

Inline SVG with import from shared-components

• For when you can't or don't need the full SVG Sprite
  • ex: Launchpad, RegWiz, & User Profile component fall under both

Uses vue-svg-loader configured for Vue CLI

<template>
  <div>
    <UnraidSvgUiWarning class="fill-current w-8 h-8 md:w-12 md:h-12 mx-auto mb-4" />
    …
    <UnraidSvgUiUsb class="fill-current w-6 h-6 mr-4" />
  </div>
</template>

<script>
import UnraidSvgUiUsb from '@unraid/shared-components/assets/svg/ui/usb.svg';
import UnraidSvgUiWarning from '@unraid/shared-components/assets/svg/ui/warning.svg';

export default {
  components: {
    UnraidSvgUiUsb,
    UnraidSvgUiWarning,
  },
};
</script>

SVG Sprite with custom SVG Icon Component

Uses svg-sprite to generate an SVG Sprite based on individual files with ./assets/svg/**/.

Then in Vue vue-svg-sprite is used within our .vue templates to display the SVGs from the generated SVG Sprite.

Pre-usage Setup

If you don't already have svg-sprite installed globally run yarn global add svg-sprite.

Because npm packages aren't really intended to have assets like images or font files we need to add a postinstall script to the parent project's package.json that will be using this SVG component of shared-components. This ensures the parent project can generate the SVG sprite and save it to the project's directory.

Step 1a - full sprite lib

"postinstall": "svg-sprite --config node_modules/@unraid/shared-components/svg-sprite.config.json 'node_modules/@unraid/shared-components/assets/svg/./**/*.svg'"

Step 1b - case only sprite example

"postinstall": "svg-sprite --config node_modules/@unraid/shared-components/svg-sprite.config.json 'node_modules/@unraid/shared-components/assets/svg/case/*.svg'"

Note to remove the case-- prefix when referring to the cases in the sprite when using this method

Step 2

You'll also want to update your .gitignore to include the directory that's created on postinstall

references that helped me figure this out:

• https://forums.meteor.com/t/npm-package-assets-like-fonts-font-awesome/21327
• https://github.com/rails/webpacker/issues/1817
• https://github.com/webpack/webpack/issues/7353

Step 3, set ENV var for Sprite SVG path (optional)

There may be use cases where your sprite needs additional path prefixes, like when hosting on Github pages

VUE_APP_SPRITE_URL_PREFIX="https://unraid.github.io/shared-components/"

Using the UnraidSvgIcon component in your project

Symbol names are automatically generated based on the individual SVG file's location. For example, if your SVG is located at assets/svg/ui/example.svg then the symbol prop value will be ui--example.

<template>
  <div>
    …
      <p class="tw-relative tw-mt-3 tw-pl-8">
        <!-- 
          - The symbol prop is required. Refer to SVGs in assets dir for options.
          - Uses classes to size and style your SVG
        -->
        <unraid-svg-icon 
          symbol="ui--example"
          class="tw-absolute tw-top-0 tw-left-0 tw-w-4 tw-h-4 tw-mr-2" />
        <a :href="exampleUrl" target="_blank">{{ exampleDetails }}</a>
      </p>
    …
  </div>
</template>
<script>
import { UnraidSvgIcon } from '@unraid/shared-components';
…
export default {
    …
    components: {
        …
        UnraidSvgIcon
    },
    …
}
</script>

Adding a new icon to the SVG Sprite (WIP)

• Export your SVG with no fill. Sometimes in your editor this means setting the fill to #000000.
• Remove any width or height attributes from the SVG Code (this may not be necessary, will determine soon)
• Add your raw exported SVG file to assets/svg/<relevant_dir>/
• Commit the new SVG to the repo
• Push to origin
• Now in your project you should be able to run yarn upgrade @unraid/shared-components to get the new version of the shared-components repo / "package".
  • Because we added the postinstall script to our project's package.json after running yarn the new version of the SVG Sprite was generated.
• Now refer to the usage instructions above, referencing your new SVG via the symbol prop for the component.

Contributing

Pull requests are welcome. For major changes, please open an issue first to discuss what you would like to change.

Please make sure to update tests as appropriate.

npm run install
npm run serve
npm run build
npm run test:unit
npm run test:e2e
npm run lint

Adding a Component

• Checkout a new topic branch
• Create your new .vue component file in src/components
• Import your new component to src/app.vue so you can see it for development purposes
• Add your new component to be exported src/components/index.js. Following the same naming convention that's already in place.

• export { default as UnraidExample } from './example.vue';

• Commit your save points
• Once ready for other eyes create a PR
• Once PR is approved we will run npm publish to deploy latest version to NPM

Deploy to GH Pages - https://unraid.github.io/shared-components/

Run the following script included with the repo to deploy your current HEAD to GH Pages.

./deploy-gh-pages.sh

See article for details

TODO

• Tests