@joyfill/components

v4.0.0-rc10

Published

3 days ago

Joyfill UI Components

0High
0Medium
0Low

jdpagley

sayo96

jeremypagley

Install

npm install @joyfill/components or yarn add @joyfill/components

Getting Started

Head over to Joyfill developer docs to learn more, find guided tutorials and much more.

JoyDoc

React Usage


import { JoyDoc, getDefaultDocument } from '@joyfill/components';

const App = () => {
  return (
    <JoyDoc
      doc={getDefaultDocument()}
      mode="edit"
      onChange={(changelogs, doc) => console.log(changelogs, doc)}
    />
  );
}

Javascript Usage (CDN)

<!DOCTYPE html>
<html>
  <head>
    <title>Joyfill for Javascript Example</title>
    <base href=".">
    <meta charset="UTF-8" />
    <script src=" https://cdn.jsdelivr.net/npm/@joyfill/components@latest/dist/joyfill.min.js"></script>
  </head>
  <body>
    <div id="joyfill"></div>
    <script>

      Joyfill.JoyDoc(
        document.getElementById('joyfill'),
        {
          mode: 'edit',
          onChange: (changelogs, doc) => console.log('onChange: ', changelogs, doc),
        }
      );

    </script>
  </body>
</html>

Javascript Usage (Module)

//index.html

<!DOCTYPE html>
<html>
  <head>
    <title>Joyfill for Javascript Example</title>
    <base href=".">
    <meta charset="UTF-8" />
  </head>
  <body>
    <div id="joyfill"></div>
    <script type="module" src="./index.js"></script>
  </body>
</html>

//index.js

import Joyfill from "@joyfill/components/dist/joyfill.min.js";

Joyfill.JoyDoc(
  document.getElementById('joyfill'),
  {
    mode: 'edit',
    onChange: (changelogs, doc) => console.log('onChange: ', changelogs, doc),
  }
);

JoyDoc Properties

mode: 'edit' | 'fill' | 'readonly'
- Required*
- Enables and disables certain JoyDoc functionality and features.
- Options
  - edit is the mode where the form/pdf is desinged, styled, and configured.
  - fill is the mode where you simply input the field data into the built form/pdf.
  - readonly is the mode where everything is locked down and you're simply viewing the form/pdf and the inputed data.
width: number
- Specifies the width of the form view
- Default: 816px
height: number
- Specifies the height of the form view
- Required for field lazy loading
- Default: 1056px
view: 'mobile' | undefined
- Specifies that the mobile view should be displayed
- The width: <screen_width>, view: 'mobile', and mode: 'fill properties enables filling out of forms in responsive web view.
lazyload: boolean
- Specifies form fields should be lazy loaded
- Default: false
doc: object
- The default JoyDoc JSON starting object to load into the component view. Must be in the JoyDoc JSON data structure.
initialPageId: string
- Specify the initial page to display in the form.
- Utilize the _id property of a Page object. For instance, page._id.
- If page is not found within the doc it will fallback to displaying the first page in the pages array.
theme: object
- Specifies the theme. See theming section below for list of supported properties.
features: object
- Specify what optional features should be enabled or disabled.
- readableIds: boolean (beta)
  - Default: false
  - Enables new readableID functionality. Instead of the default ObjectID format, you can add text1, customerAge, address, etc. as field _ids. This supports easier formula targeting.
  - Enabling this feature is required for formulas feature.
- formulas: boolean (beta)
  - Default: false
  - Enables new formulas feature. This allows you to perform arithmetic operations and other calculation based operations on fields.
- repeatingHeaderAndFooter: boolean (beta)
  - Default: false
  - Enables repeating header and footer functionality for pages. This feature is only available in our Web SDK and will not be visible in mobile SDKs.
- validateSchema: boolean
  - Default: true
  - Enforces internal Joyfill Schema validation and error UI. Set to false to disable internal Joyfill Schema validation.
fieldOptions: [object, ...]
- Overwrite the list of field options that can be dragged and dropped on the form/pdf.
- Field option objects can have any JoyDoc JSON property. Any property set will be used as the new field defaults when dragged and dropped to the form/pdf.
fieldSettings: object
- Customize file, page, and field settings and functionality.
- Head over to the developer docs to learn more about customizing settings in our guides.
onChange: (changelogs: object_array, doc: object) => {}
- Used to listen to any changes to the style, layout, values, etc. across all modes.
- changelogs: object_array
  - Can contain one ore more of the changelog object types supported.
- doc: object
  - Fully updated JoyDoc JSON structure with changes applied.
onUploadAsync: (params: object, fileUploads) => Promise
- Required, if you want to support PDF uploads, page backgrounds, and image fields.
- Must return a promise that will resolve to { url: string }.
  - url must be a valid image url or image base64 uri.
- Utilize this handler to upload images for fields, page backgrounds, etc. to your own asset hosting service.
- params: object
  - target: ('file.update' | 'page.update' | 'field.update') Determines the object within the doc (JoyDoc JSON structure) that was targeted with the change event.
  - _id The _id of the document|template.
  - identifier The identifier of the document|template.
  - fileId The id of the file that the change happened.
  - pageId The id of the page that the change happened.
  - fieldId The id of the field that the change happened.
  - fieldIdentifier The custom id of the field that the change happened.

JoyDoc Field Events

Image
- onFocus(params: object, e: object) * Empty - Triggers onFocus when file upload is initiated (click or file drop) * Populated - Triggers onFocus when when upload is clicked or image is deleted.
- onUploadAsync * When user selects file(s) from the file system. * When files are dragged and dropped onto the field.
- onChange is fired when an option is selected. * Triggers when onUploadAsync has successfully responded with image urls.
Text, Textarea, Number, Date
- onFocus(params: object, e: object) is fired when the field is focused.
  - e.blur
    - Triggers onChange for any pending changes.
    - Triggers onBlur
- onChange is fired when the field value is modified.
- onBlur is fired when the field is blurred.
Dropdown
- onFocus(params: object, e: object) is fired when the field is focused.
  - e.blur
    - Triggers onBlur
- onChange is fired when an option is selected or unselected in the field.
- onBlur is fired when the field is blurred.
MultiSelect
- onFocus is fired when an option is selected or unselected for the first time on the field.
- onChange is fired when an option is selected or unselected in the field.
Selector (Checkbox/Circle etc)
- onFocus(params: object, e: object) is fired when an option is selected or unselected.
- onChange is fired when an option is selected or unselected.
Signature
- onFocus(params: object, e: object) is fired when sign button is clicked.
  - e.blur
    - Closes the signature modal
- onChange is fired when the submit button is clicked.
- onBlur is fired when the modal is closed.
Chart
- onFocus(params: object, e: object) is fired when edit button is clicked.
  - e.blur
    - Closes the chart modal
- onChange is fired when the submit button is clicked.
- onBlur is fired when the modal is closed.
Table / Input Group
- Text Cell
  - onFocus(params: object, e: object) is fired when cell is focused.
    - e.blur
      - Triggers onBlur
  - onChange is fired when the text cell is blurred.
  - onBlur is fired when the cell is blurred.
- Dropdown Cell
  - onFocus(params: object, e: object) is fired when cell is focused.
    - e.blur
      - Triggers onBlur
  - onChange is fired when an option is selected.
  - onBlur is fired when the cell is blurred.
- Image Cell
  - onFocus(params: object, e: object) * Empty - Triggers onFocus when file upload is initiated (click or file drop) * Populated - Triggers onFocus when when upload is clicked or image is deleted.
  - onUploadAsync * When user selects file(s) from the file system. * When files are dragged and dropped onto the field.
  - onChange is fired when an option is selected.
    - Triggers when onUploadAsync has successfully responded with image urls.
Individual Table / Input Group Cell Field
- Text Cell
  - onFocus(params: object, e: object) is fired when the field is focused.
    - e.blur
      - Triggers onChange for any pending changes.
      - Triggers onBlur
  - onChange is fired when the field value is modified.
  - onBlur is fired when the field is blurred.
- Dropdown Cell
  - onFocus(params: object, e: object) is fired when the field is focused.
    - e.blur
      - Triggers onBlur
  - onChange is fired when the field value is modified.
  - onBlur is fired when the field is blurred.
- Dropdown Selector Cell
  - onFocus(params: object, e: object) is fired when an option is chosen.
  - onChange is fired when an option is chosen.
- Image Cell
  - onFocus(params: object, e: object) * Empty - Triggers onFocus when file upload is initiated (click or file drop) * Populated - Triggers onFocus when when upload is clicked or image is deleted.
  - onUploadAsync * When user selects file(s) from the file system. * When files are dragged and dropped onto the field.
  - onChange is fired when an option is selected.
    - Triggers when onUploadAsync has successfully responded with image urls.

JoyDocExporter

The JoyDocExporter can be used along with a browser's PDF capabilities to convert the doc to a downloadable PDF.

Important Note: There is an initial field measuring cycle that happens inside of the JoyDocExporter and a PDF should not be generated during that time. An element will be added to the DOM with the pdf-capture-ready class and id that can be used with headless browser libraries. You should only generate the PDF once this DOM node is present.

React Usage


import { JoyDocExporter, getDefaultDocument } from '@joyfill/components';

const App = () => {
  return (
    <JoyDocExporter
      doc={getDefaultDocument()}
      config={{ page: { height: 1056, width: 816, padding: 0 }}}
    />
  );
}

Javascript Usage (CDN)

<!DOCTYPE html>
<html>
  <head>
    <title>Joyfill for Javascript Example</title>
    <base href=".">
    <meta charset="UTF-8" />
    <script src=" https://cdn.jsdelivr.net/npm/@joyfill/components@latest/dist/joyfill.min.js"></script>
  </head>
  <body>
    <div id="joyfill"></div>
    <script>

      Joyfill.JoyDocExporter(
        document.getElementById('joyfill'),
        {
          doc: Joyfill.getDefaultDocument(),
          config: { page: { height: 1056, width: 816, padding: 0 } }
        }
      );

    </script>
  </body>
</html>

JoyDocExporter Properties

doc: object
- The default JoyDoc JSON starting object to load into the component view. Must be in the JoyDoc JSON data structure.
config: object
- page: object
  - height: number
    - Specifies the height (in pixels) to target when laying out fields for the PDF Page that will be generated. For instance, 816 indicates that you want to target a page break every 816px.
  - width: number
    - Specifies the width (in pixels) to target when laying out fields for the PDF Page that will be generated.
  - padding: number
    - Specifies the amount of white-space padding (in pixels) to add to the PDF Page that will be generated.
theme: object
- Specifies the theme. See theming section below for list of supported properties.

Theming

All options below are optional. You can use one or all of the options listed to customize the SDK theme.
You are responsible for ensuring the fontFamily you specify is loaded and available within your application.
All properties that set color must use HEX code. HEX code example: #fffff.
All number options must be specified as numbers, not strings. Numbers will be used with pixel (px) sizing.
Field Styles
- Theme and styles will be applied to the field based on the order below.
  1. First - Style set by the user on the field using the UI style settings.
  2. Second -Field theme property. ie. theme.field.fontColor
  3. Third - Top level theme property. ie theme.fontColorPrimary
  4. Fourth - Internal SDK default style
- Example of how fontColor is applied to a field: const fontColor = field.fontColor || theme.field.fontColor || theme.fontColor || internal.fontColor
Theme Properties
- fontFamily: string
- fontColorPrimary: string(HEX Code)
- fontColorSecondary: string(HEX Code)
- primaryColor: string(HEX Code)
- primaryOpaqueColor: string(RGBA)
- dangerColor: string(HEX Code)
- warningColor: string(HEX Code)
- backgroundColor: string(Hex Code)
- borderColor: string(Hex Code)
- borderRadius: number
- field: object
  - titleFontSize: number,
  - titleFontColor: string(HEX Code),
  - titleFontStyle: string('italic' | 'normal'),
  - titleFontWeight: string('bold' | 'normal'),
  - titleTextAlign: string('left' | 'center' | 'right'),
  - titleTextTransform: string('uppercase' | 'none'),
  - titleTextDecoration: string('underline' | 'none'),
  - fontSize: number,
  - fontColor: string(HEX Code),
  - fontStyle: string('italic' | 'normal'),
  - fontWeight: string('bold' | 'normal'),
  - textAlign: string('left' | 'center' | 'right'),
  - textTransform: string('uppercase' | 'none'),
  - textDecoration: string('underline' | 'none'),
  - textOverflow: string('ellipsis'),
  - padding: number,
  - borderRadius: number,
  - borderWidth: number,
  - borderColor: string(HEX Code),
  - backgroundColor: string(HEX Code)

Helper Methods

getDefaultDocument
- Get a default Joyfill Document object
getDefaultTemplate
- Get a default Joyfill Template object
getDocumentFromTemplate: ( template: object )
- Generate a Joyfill Document object from a Joyfill Template object
getDefaultPage: ( defaults: object )
- Generate a default Joyfill Page for a Document or Template
duplicate: ( original: object, defaults: object )
- Duplicate a Joyfill Document or Template object.
duplicatePage: ( original: object, fileId: string, pageId: string )
- Duplicate a Joyfill Document or Template Page object.
- Returns: { doc: object, changelogs: array }
  - doc fully updated Document or Template with the page added
  - changelogs array of changelogs for new duplicate page.
applyLogic: ( items: object_array, fields: object_array, fieldLookupKey: string )
- Apply show/hide logic to pages and fields for external filtering.
- Wrapper around @joyfill/conditional-logic library. View library
validator: object
- validate: (doc: object)
  - Use to validate that all visible required fields are filled out. Validation only validates the visible fields for the target view (desktop or mobile) and accounts for conditional logic. Hidden fields or fields on a hidden page are considered valid.
  - Returns object with validation state of the data as a whole and the individual fields.
validateSchema: (doc: object)
- Use to check your JSON data for structural or data type errors that could lead to issues within the SDK. Structural and type checking is done against the Joyfill Schema.
replaceLegacyDateTimeFormats: (doc: object, replacementsLookup: object)
- Replaces the legacy persisted US only formatted options: MM/DD/YYYY, MM/DD/YYYY hh:mma, & hh:mma with custom options to support different timezone preferences.
- Arguments
  - doc the full Joyfill document or template JSON.
  - replacementsLookupObject is the object you define to overwrite the legacy options. It supports date, dateTime, time, and defaultFormat. For instance, if you wanted to overwrite the old US formats to the UK preferred formats you could specify the following object: { date: 'DD-MM-YYYY', dateTime: 'DD-MM-YYYY HH:mm', time: 'HH:mm', defaultFormat: 'DD-MM-YYYY' }
    - date matches and replaces the legacy MM/DD/YYYY.
    - dateTime matches and replaces the legacy MM/DD/YYYY hh:mma.
    - time matches and replaces the legacy hh:mma
    - defaultFormat overwrites the internal default of MM/DD/YYYY that is used when no format is specified in the data.
    - Important Note: Any formats that do not match the specified legacy US patterns and/or are not undefined are left unmodified.
- Returns updatedDoc: object

Contributing

Environment Versions

Module manage yarn
Node version 20+

Commands

Run Tests yarn run test
Coverage Report yarn run coverage
Auto Fix Linting Errors yarn run lint-fix
See Linting Linting yarn run lint
Generate Visual Coverage Report yarn coverage-report -- filename

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

Install

Getting Started

JoyDoc

React Usage

Javascript Usage (CDN)

Javascript Usage (Module)

JoyDoc Properties

JoyDoc Field Events

JoyDocExporter

React Usage

Javascript Usage (CDN)

JoyDocExporter Properties

Theming

Helper Methods

Contributing