npm package: @outfit.io/web-components
Description: Outfit web-components following open-wc recommendations
Author: @outfit.io
Latest version: 0.4.0

# @outfit.io/web-components

These webcomponents follows the [open-wc](https://github.com/open-wc/open-wc) recommendation.

A library of web components that can be used in order to create a outfit template.

##  Node Version Manager (NVM)
Javascript mainly runs in the browser, but we also use Node to run it from the command line.
Like Ruby, there are many versions of Node, so we use another program, Node Version Manager (NVM) to handle switching between them.

Follow the instructions [here](https://github.com/nvm-sh/nvm#installing-and-updating) to install NVM.
You'll need to reload your terminal after this completes.

To confirm that nvm installed correctly, run `nvm --version`. If that doesn't return anything, you may need to update your shell configuration file. This is probably `~/.zshrc` but it could be `~/.bash_profile`, `~/.profile`, or `~/.bashrc` if you're running an old version of MacOS.

Add this line to the configuration file:
```shell
export NVM_DIR="$([ -z "${XDG_CONFIG_HOME-}" ] && printf %s "${HOME}/.nvm" || printf %s "${XDG_CONFIG_HOME}/nvm")" [ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh" # This loads nvm
```

### Node
Once nvm is installed, get and use the version of Node from `.nvmrc` by running these commands:
```shell
cat .nvmrc | nvm install
cat .nvmrc | nvm use
```

This should also install `npm` the node package manager for you. Please ensure that you are using version 6.13.4 as it is the version currently used in the CI pipeline and consistency will avoid hard to debug errors in package resolving.

## Installation

```bash
npm i @outfit.io/web-components
```

## Usage

```html
<script type="module" src="'@outfit.io/web-components/dist/index.js'"></script>

<outfit-page></outfit-page>
<outfit-limiters></outfit-limiters>
```

You can use a CDN url if your developing with ES modules without a build step, e.g:
- `https://unpkg.com/@outfit.io/web-components@[VERSION]/src/index.es.js`

[NPM page](https://www.npmjs.com/package/@outfit.io/web-components)

## Linting and formatting

To scan the project for linting and formatting errors, run

```bash
npm run lint
```

To automatically fix linting and formatting errors, run

```bash
npm run format
```

## Testing with Web Test Runner

To execute a single test run:

```bash
npm run test
```

To run the tests in interactive watch mode run:

```bash
npm run test:watch
```

## Demoing with Storybook

To run a local instance of Storybook for your component, run

```bash
npm run storybook
```

To build a production version of Storybook, run

```bash
npm run storybook:build
```


## Tooling configs

For most of the tools, the configuration is in the `package.json` to minimize the amount of files in your project.

If you customize the configuration a lot, you can consider moving them to individual files.


To run a local development server that serves the basic demo located in `public/index.html` run the two following commands 
```
npm run dev
npm run start
```



### Getting started 
add the components above the body tag in the html file as a ES6 module

```
then anywhere in your react/vue/angular/whatever code you can use the component

### examples
an example of a single line textfit is as follows: 
```html
<outfit-limiter max-lines="1" width-only textfit>
  Text that will stay on a single line
</outfit-limiter>
```

if you waned to make sure the text fitted inside of a div using rem, you would use the following:
```html
<outfit-limiter  textfit font-unit="rem" max-font-size="1.3" min-font-size="0.2">
  Text that will stay on a single line
</outfit-limiter>
```

if you wanted to textfit the font size so that the content stays on 4 lines before but if it gets to 10% of the orignal font size it throws an overflow you would use the following:
```html
<outfit-limiter textfit max-lines="4" min-font-size="10">
  Text that will stay on a single line
</outfit-limiter>
```

if you want to limit to an amount of lines to 4 you can do the following. it doesn't care about the font size inside when counting
```html
<outfit-limiter max-lines="4" >
  <h1>heading</h1>
  <p>din gravida dolor porttitor? Congue pulvinar semper dui nostra elit etiam? Sapien laoreet eros curae aliquam consequat eros! Lorem integer bibendum taciti lectus ante laoreet venenatis leo. Etiam hac odio. Lacinia eget aliquet. Nunc ac per proin, quis torquent velit felis dolor taciti justo. Ipsum libero in litora aliquet class non. Orci faucibus risus! Rhoncus etiam fringilla erat, nisl pharetra sodales arcu, aliquet.</p>
</outfit-limiter>
```

### props available 
```
max-lines (Number) - the max number of lines the text will be limited to
textfit (Boolean) - if set, textfit will run
grow-in-height (Boolean) - if set, the height of the text be 100% while fitting text which means the text will grow in size if possible
max-font-size (Number) - the max font size the textfit will be limited to, defaults to 100
min-font-size (Number) - the min font size the textfit will be limited to, defaults to 50
font-unit (String) - the unit of measurement for the textfit, defaults to %
width-only (Boolean) - if true, textfit will only use width to calculate font size, defaults to false
height-only (Boolean) - if true, textfit will only use height to calculate font size, defaults to false
box (String) - the box model to use for textfit, defaults to just using scroll width and height. There are also 'inner', 'outer' and 'text' modes which use these checks instead to infer if there is space for text
max-height (Number) - the max height the text will be limited to, defaults to self mode
```
### max height modes
```
max-height="self" - the max height will be the scroll height of the text
max-height="parent" - the max height will be the height of the parent element
max-height="css" - the max height will be the max-height CSS property. Useful for when you don't want to set a value in PX
max-height="100" - the max height will be limtied to the number passed in as pixels
max-height="outerbox" - This mode will trigger an overflow if the top of the outfit-limter is higher up the page than it's parent or if the bottom of the element is lower down the page than it's parent
max-height="innerbox" - This is the default mode; This mode will trigger an overflow if any of the direct children nodes bottoms are lower down the page than the bottom of the outfit-limiter. Yes well also trigger and overflow if the top of any direct children needs are higher on the page than the top of the outfit-limiter
```

#### textfit box modes
 textft is programmed to increase the font size if there is more area available and if there isn't decrease the font size until there is enough space. By default this check is done using the parent nodes size. 
 if you pass in the value of `text` to the box prop then it will determine if there is available space based on the location of the bottom and right side of all the inner text node. 
  if you pass in the value of `inner` to the box prop then it will determine if there is available space based the direct children nodes size
  if you pass in the value of `scroll` to the box prop then it will determine if there is available space based the scroll height vs the starting height of the outfit-limiter


if you are using this with non-js templates please disable token values as you will loose focus on the input each time there is an update