@outfit.io/react

A library of React components that can be used in order to create outfit templates.

Installation

npm i @outfit.io/react

Usage

Wrap your template in the OutfitProvider and pass window.payload to its templateProps prop.

Then when you want to access your template inputs, use the useOutfit hook to get account, team, user and template inputs.

const { metadata: { account, team, user }, inputs } = useOutfit();

Components

• OutfitProvider
• Page
• Limiter
• Placeholder
• Image
• BackgroundImage

Page

The base component we use in almost all templates to create a document page.

Page Props

• trim (Boolean) - sets trim marks on/off.
• mysteryPixel (Boolean) - applies the mystery pixel height fix (where an extra page renders incorrectly on export)
• backgroundColor (String) - sets the backgound color. Defaults to #ffffff.
• trimColor (String) - sets the trim marks color. Defaults to rgba(0, 0, 0, 0.5).

Placeholder

<Placeholder
    image="https://files.stg.outfit.io/media_library_items/57987/Asset%252020.png"
    opacity="0.3"
    offset={false}
    hide
/>

Placeholder Props

• image (String) - Placeholder image to be used. Default is an empty string and a default image will show.
• opacity (String) - Used to set the css value of opacity on the placeholder image. Use between 0-1. Default is 0.3.
• offset (Boolean) - Used to add or remove the extra 3mm bleed on each side of the placeholder. If using the Page component, the default is fine. Default is true.
• hide (Boolean) - Used to add or remove the placeholder. Default is false.

Limiter

The Limiter component wraps other elements and triggers an overflow warning when the defined limits are exceeded. Possible limit types include:

• height
• line count
• characters

The Limiter component can also be configured to run textfit. This will dynamically adjust the font size to best fit the area within the Limiter.

Limiter Props

Limiter props include those related to styling, onClick, height/line/character limits and config for textfit.

Limiter Props - General

• overflowColor (String) - the color of the overflow message
• overflowBackgroundColor (String) - the background-color of the overflow message
• overflowMessage (String) - a custom overflow message that overrides the default overflow messages.
• onClick (Function) - any callback that you want placed on the actual div that the limiter renders, e.g. onInlineEditClick
• ensureAllImagesLoad (Boolean) - if true the Limiter will wait for all images in the document to load before running. This can be important in cases where images would change the area available to the text.

Limiter Props - Line/Character

• maxLines (Number)
  • the max lines the text will be limited to
  • if this prop is used while textfit is enabled, the max set here will also be used by textfit
• maxChars (Number) - the max characters the text will be limited to.

Limiter Props - Max Height

• maxHeight (Number/String)
  • if a number, the max height will be the number, e.g. 100, in pixels
  • if a string, different modes are possible:
    • "self" - the max height will be the scroll height of the text
    • "parent" - the max height will be the height of the parent element
    • "outerbox" - This mode will trigger an overflow if the top of the Limiter is higher up the page than its parent or if the bottom of the element is lower down the page than its parent
    • "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 Limiter. It will also trigger an overflow if the top of any direct children needs are higher on the page than the top of the Limiter

Limiter Props - Textfit

• textfit (Boolean) - if set, textfit will run
• textfitConfig (Object) - object containing possible textfit config/settings:
  • maxFontSize (Number) - the max font size the textfit will be limited to, defaults to 100
  • minFontSize (Number) - the min font size the textfit will be limited to, defaults to 50
  • fontUnit (String) - the unit of measurement for the textfit. Defaults to %
  • widthOnly (Boolean) - if true, textfit will only use width to calculate font size. Defaults to false
  • heightOnly (Boolean) - if true, textfit will only use height to calculate font size. Defaults to false
  • overflowDetectionMode (String)
    • the method used while determining if there is available space for text (and therefore if a larger/smaller font size is appropriate).
    • If overflowDetectionMode is not specified, textfit defaults to using the bounding box of theLimiter's parent element as the limit.
    • Other possible modes:
      • "innerbox" - detects if any child elements of the Limiter have exceeded the Limiter's bounding box
      • "text" - detects if any text nodes have exceeded the right or bottom sides of the Limiter's bounding box
      • "scroll" - detects if the Limiter's scrollWidth or scrollHeight has exceeded the Limiter's original width/height.

Line/Height/Character Limit - Examples

<Limiter maxLines={2}>
    {someElements}
</Limiter>

<Limiter maxHeight={200}>
    {someElements}
</Limiter>

<Limiter maxChars={50}>
    {someElements}
</Limiter>

Note: only one limit type should be used per Limiter component, e.g. NOT:

<Limiter maxLines={2} maxChars={20}> // DON'T DO THIS
    {someElements}
</Limiter>

Line/Height/Character Limit - Usage

Character limits can't be applied to plain text. They require some element wrapping the text, i.e.

<Limiter maxChars={50}>
    I'm some plain text. // DON'T DO THIS
</Limiter>

<Limiter maxChars={50}>
    <p>I'm some text in a p element</p> // DO THIS
</Limiter>

Textfit Examples

<Limiter textfit textfitConfig={{ maxLines: 2 }}>
    {someElements}
</Limiter>

Textfit Usage

Textfit requires a starting font size, so a key to having it work as expected is ensuring that the Limiter has a font-size set or inherited.

Textfit also requires something to tell it if there is more vertical space available to it. The most common ways of doing this are:

• setting maxLines (as in the example above)
• placing a parent element that has a defined height around the Limiter

Limiter - Advanced Usage

Sometimes it may be desirable to get a line count on an element from a separate component or part of your component tree. Or you might need to manually trigger a re-run of validation on a Limiter component.

This can be achieved with a couple of utility functions:

• lineCount(element)
• runValidation(element, limiterProps)

These functions are used internally by the Limiter component. They are just vanilla JS functions that read and update the DOM with normal DOM apis (nothing React involved).

Since you'd be calling these from a React useEffect, you'd pass a ref.current as the element argument to each function.

Additionally, runvalidation requires that you manually pass a limiterProps object (since it can't just pick up the props directly from the Limiter), e.g. if my original Limiter was:

<Limiter ref={limiterRef} maxLines={10}>
    {someElements}
</Limiter>

Then I could re-run it from a useEffect in a parent component with:

runValidation(limiterRef.current, { maxLines: 10 })

Image

This Image component is to be used in place of HTML img elements anytime you need an image to be repositionable.

Why? With Outfit's repositionable image tool and normal img elements, we have a problem where the repo tool isn't aware of the img dimensions. This means a user can crop/select an area with dimensions that don't match the img in the actual document, potentially leading to stretched/squished images.

This component solves that by communicating your image's dimensions to the Outfit platform. With that information, the platform can then lock the aspect ratio of the crop/select area correctly.

NOTE: this component requires that selectable inputs be enabled on your template.

Image Props

• input (Object) - The object provided by the platform for any input, when selectable inputs is toggled on, i.e. an object containing:
  • value (String) - the url for the selected image
  • ids (Object) - the input id and its parent's id
• styles (String) - any CSS styling you wish applied to the image
• onClick (Function) - any callback that you want placed on the img, e.g. onInlineEditClick

e.g.

export const Template = () => {
  const { inputs } = useOutfit();
  const { imageInput } = inputs;

  const imageStyles = `
    width: 200px;
    height: auto;
    padding: 20px;
  `;

  return (
    <Page>
      <Image input={imageInput} styles={imageStyles} onClick={() => onInlineEditClick(imageInput?.ids)} />
    </Page>
  );
};

Background Image

The BackgroundImage component is designed to be used in cases where we would want to have div with a background-image that is repositionable. Like the Image component, the BackgroundImage communicates the image dimensions so that the image repo tool can have its dimensions set correctly.

NOTE: this component requires that selectable inputs be enabled on your template.

Background Image Props

• input (Object) - The object provided by the platform for any input, when selectable inputs is toggled on, i.e. an object containing:
  • value (String) - the url for the selected image
  • ids (Object) - the input id and its parent's id
• styles (String) - any CSS styling you wish applied to the image
• onClick (Function) - any callback that you want placed on the img, e.g. onInlineEditClick

e.g.

export const Template = () => {
  const { inputs } = useOutfit();
  const { backgroundImageInput } = inputs;

  const backgroundImageStyles = `
    width: 200px;
    height: 200px;
    padding: 20px;
  `;

  return (
    <Page>
      <BackgroundImage input={backgroundImageInput} styles={imageStyles} onClick={() => onInlineEditClick(backgroundImageInput?.ids)} />
    </Page>
  );
};

## Hooks

- useOutfit
- useBrandSystem

## Tests
To run unit tests run:
- `npm run test-storybook`

You can interact with these tests in the Storybook console and the 'interactions' tab by running:
- 'npm run storybook'


# Creating a new version

Please create a new version before pushing code to master

To create a new npm realase version, run the following commands:

- `git pull` # Pull latest changes from remote
- `npm ci` # Install dependencies from scratch
- `npm run changeset:add` # Add changeset

you will then be asked which type of release you want to create (patch/minor/major) this will change which number changes in the version number. you will also need to enter a description for the change which will be used as the release notes.

when you push changes to master they will now be published to npm.

## Coming Soon

- Ensure all Page functionality moves over from the web components repo
- BrandSystem injection - Prop on OutfitProvider component