❤
npm
Sign UpSign In

wurld

0.2.2 • Public • Published

Wurld v0.2.2 BETA

IMPORTANT: This is a beta version and, until v1, any feature updates, e.g. v0.3.x, may contain breaking changes. Use caution when updating, while in beta!

Installing

npm install wurld

Initializing

Wurld.register()

This will register everything wurld has globally.

Params

  • options (Object) - Default: {}
    • If nothing is provided, it will register everything wurld has to offer with default values set in place. The following are optional properties for this object
      • components (Array)
        • If this option is not provided then all components will be globally registered, otherwise individual components can be registered by passing an array of the components, as strings. They would be cased in the same way as components, e.g. 'WurldInput'
      • config (Object)
        • Many of the directives, filters, and methods can be configured, usually by changing what their global defaults are. To configure one of them, you simply add a property to this, with the key being the same name as the directive, filter, or method you would like to configure. The individual directives, filters, and methods in this doc will describe what their configuration options are, if any.
import Wurld from 'wurld'
 
Wurld.register();

Components (Helpers)

WurldDynamicTag

Props

  • tag (String) required
    • the HTML tag you want it to be

DOM Structure

<tag-you-passed-as-a-prop>
    <slot> // Anything you put in as a child of this component

Components (Fields)

Attributes You can pass attributes, similar to how you would pass the props, as long as it is not defined as a prop for the given component. Normally, these attributes would only go to the root element of the component. However, for these components you can pass an attribute to a child element in the following format: element:attribute="value" this will then apply the attribute to the elements of the element name given. It will still pass the attributes to the parent element if given in the traditional format, i.e. without the in-between colon.

NOTE: This will still work as a v-bind with a colon in front of the element.

WurldCheckbox

Props

  • labelBefore (Boolean) Default: false
    • The element(s) will normally be placed after the element(s), in the document flow. However if this prop is set to true, the element(s) will appear before the element(s), in the document flow.
  • legend (String) Default: null
    • If set, the root element will be a , rather than a
      , and a will be created as the first child of the , with it's content set as the value of this prop.
  • name (String) Default: null
    • If set, will add the "name" attribute to the element(s). If the options prop's array has more than one element, it will append a "[]" after the name, for the purposes of form submission.
  • options (Array) required
    • The array is an array of objects. Using an array of objects can garauntee the checkboxes appearing in specific a order, if desired. Each object has a "label" and "value" property. The "value" property of the object will be used as the "value" attribute for the element(s) and the "label" property will be used for the checkbox's element. If this Array has more than one object, the "name" attributes for the element(s) will have a "[]" appended after them for the purposes of form submission.
  • uid (String) Default: null
    • If set, the element(s) "id" attribute would be set to this prop's value. Also, the element(s) "for" attribute would also be set to the same value. These unique identifiers will also have the key of the option object from the options array appended to the end of it, as there can be more than one of these elements. This prop should be unique. If this is not set the formerly mentioned attributes will be generated a uid.
  • value (Array) Default: null
    • Normally, you would use v-model on this component, which itself will set this prop. Either way, if this prop is set, the "checked" attribute on the element(s) will be set to true if any of this Arrays elements match it's value.

Attributes Below are the child elements you can pass attributes to, along with a list of attributes it will not accept, if any.

  • checkbox
    • id - this is given either the uid prop or the generated uid if the uid prop is not provided, if neither of the label nor uid props are set then no id will out on the .
    • name - use the prop instead.
    • type - this is automatically set to "checkbox"
    • value - use the prop instead.
    • checked - this is automatically set based on the value prop and what boxes are checked
  • label
    • for - this is given either the uid prop or the generated uid if the uid prop is not provided.
  • legend
  • group - This is the wrapping div that surrounds the label and checkbox combinations

Emitted Events

  • input Output: Array | null
    • Set up to emit the 'input' event for use with v-model.

DOM Structure

div.WurldCheckbox | fieldset.WurldCheckbox // if legend is set then it uses fieldset otherwise it uses div
    legend // if legend is set
        .WurldCheckbox__group *repeatable*
            label *repeatable* // if labelBrefore = true
            input[type="checkbox"] *repeatable*
            label *repeatable* // if labelBefore = false

WurldInput

Props

  • label (HTML String) Default: null
    • If set, will create a with the given HTML string as its content. This will also trigger an uid to be placed onto the "for" attrbute and the "id" attibute. This uid would be generated if the uid prop is not set.
  • labelAfter (Boolean) Default: false
    • If label prop is set, the will normally be placed before the , in the document flow. However if the label prop is set, and this prop is set to true, the will appear after the , in the document flow.
  • name (String) Default: null
    • If set, will add the "name" attribute to the , with whatever is set here as its value.
  • uid (String) Default: null
    • If set, the "id" attribute would be set to this prop's value. Also, if the label prop is set the "for" attribute would also be set to the same value. This prop should be unique. If this is not set, and a label prop is given the formerly mentioned attributes will be generated a uid.
  • type (String) Default: 'text'
    • Will pass the type to the . Best if something close to text, e.g. password or email.
  • value (String) Default: null
    • Normally, you would use v-model on this component, which itself will set this prop. Either way, if this prop is set, the "value" attribute on the will be set this prop's value.

Attributes Below are the child elements you can pass attributes to, along with a list of attributes it will not accept, if any.

  • label
    • for - this is given either the uid prop or the generated uid if the uid prop is not provided.
  • input
    • id - this is given either the uid prop or the generated uid if the uid prop is not provided, if neither of the label nor uid props are set then no id will out on the .
    • name - use the prop instead.
    • type - use the prop instead.
    • value - use the prop instead.

Emitted Events

  • input Output: String
    • Set up to emit the 'input' event for use with v-model.

DOM Structure

div.WurldText
    label // if labelAfter = false
    input
    label // if labelAfter = true

WurldRadioButton

Props

  • labelBefore (Boolean) Default: false
    • The element(s) will normally be placed after the element(s), in the document flow. However if this prop is set to true, the element(s) will appear before the element(s), in the document flow.
  • legend (String) Default: null
    • If set, the root element will be a , rather than a
      , and a will be created as the first child of the , with it's content set as the value of this prop.
  • name (String) Default: null
    • If set, will add the "name" attribute to the element(s).
  • options (Array) required
    • The array is an array of objects. Using an array of objects can garauntee the radios appearing in specific a order, if desired. Each object has a "label" and "value" property. The "value" property of the object will be used as the "value" attribute for the element(s) and the "label" property will be used for the radio's element.
  • uid (String) Default: null
    • If set, the element(s) "id" attribute would be set to this prop's value. Also, the element(s) "for" attribute would also be set to the same value. These unique identifiers will also have the key of the option object from the options array appended to the end of it, as there can be more than one of these elements. This prop should be unique. If this is not set the formerly mentioned attributes will be generated a uid.
  • value (String) Default: null
    • Normally, you would use v-model on this component, which itself will set this prop. Either way, if this prop is set, the "checked" attribute on the element(s) will be set to true if this prop match it's value.

Attributes Below are the child elements you can pass attributes to, along with a list of attributes it will not accept, if any.

  • radio
    • id - this is given either the uid prop or the generated uid if the uid prop is not provided, if neither of the label nor uid props are set then no id will out on the .
    • name - use the prop instead.
    • type - this is automatically set to "radio"
    • value - use the prop instead.
    • checked - this is automatically set based on the value prop and what boxes are checked
  • label
    • for - this is given either the uid prop or the generated uid if the uid prop is not provided.
  • legend
  • group - This is the wrapping div that surrounds the label and radio combinations

Emitted Events

  • input Output: String | null
    • Set up to emit the 'input' event for use with v-model.

DOM Structure

div.WurldRadioButton | fieldset.WurldRadioButton // if legend is set then it uses fieldset otherwise it uses div
    legend // if legend is set
        .WurldRadioButton__group *repeatable*
            label *repeatable* // if labelBrefore = true
            input[type="radio"] *repeatable*
            label *repeatable* // if labelBefore = false

WurldSelect

Props

  • disabled (Boolean) Default: false
    • If true, adds the "disabled" attribute to the .
  • label (HTML String) Default: null
    • If set, will create a with the given HTML string as its content. This will also trigger an uid to be placed onto the "for" attrbute and the "id" attibute. This uid would be generated if the uid prop is not set.
  • labelAfter (Boolean) Default: false
    • If label prop is set, the will normally be placed before the , in the document flow. However if the label prop is set, and this prop is set to true, the will appear after the , in the document flow.
  • name (String) Default: null
    • If set, will add the "name" attribute to the , with whatever is set here as its value. If the readonly prop is set to true, then the "name" attribute wil instead be placed on an .
  • options (Array) required
    • The array is an array of objects. Using an array of objects can garauntee the options appearing in specific a order, if desired. Each object has a "label" and "value" property. The "value" property will be used as the values for the and the "label" property will be used as the labels, i.e. what the user will visually see as the option. However, instead of a string as a value for the "value" property, another array could be set instead. This will make the "label" property the label of an and the child array of objects will be set for child elements.
  • placeholder (String) Default: null
    • If set, will create an initial , with a value of an empty string, and content of whatever is set here. If the required prop is true, and once the value prop is truthy, this initial will be removed. If the required prop is false, this initial will always remain, to be reselectable.
  • readonly (Boolean) Default: false
    • If true, the becomes disabled and the "name" attribute, if any, is removed. An is created which will instead have the "name" attribute, if any, and will recieve a "value" attribute, which will be populated with whatever is passed through the value prop.
  • required (Boolean) Default: false
    • If true, adds the "required" attribute to the . Additionally, if the placeholder prop also has a value, then the created placeholder will be removed once the value prop is truthy.
  • uid (String) Default: null
    • If set, the "id" attribute would be set to this prop's value. Also, if the label prop is set the "for" attribute would also be set to the same value. This prop should be unique. If this is not set, and a label prop is given the formerly mentioned attributes will be generated a uid.
  • value (String) Default: null
    • Normally, you would use v-model on this component, which itself will set this prop. Either way, if this prop is set, the that has a value equal to this prop will recieve the "selected" attribute.

Attributes Below are the child elements you can pass attributes to, along with a list of attributes it will not accept, if any.

  • label
    • for - this is given either the uid prop or the generated uid if the uid prop is not provided.
  • select
    • disabled - use the disabled prop instead, because it is used in some logic with the readonly prop which select elements normally don't have as an attribute.
    • id - this is given either the uid prop or the generated uid if the uid prop is not provided, if neither of the label nor uid props are set then no id will out on the .
    • name - use the prop instead.
    • required - use the prop instead, because this will remove the placeholder , if a placeholder is provided once a value is set.
  • option
    • value - see the options prop.
    • selected - use the value prop instead.
  • optgroup
    • label - see the options prop.

Emitted Events

  • input Output: String
    • Set up to emit the 'input' event for use with v-model.

DOM Structure

div.WurldSelect
    label // if labelAfter = false
    select
        option[value=""] // if placeholder has a value AND if value has no value OR required is false
        option *repeatable* // if the "value" property of the current object of the options array is a string
        optgroup *repeatable* // if the "value" property of the current object of the options array is another array
            option *repeatable*
    input[type="hidden"] // if readonly is true
    label // if labelAfter = true

WurldTextarea

Props

  • label (HTML String) Default: null
    • If set, will create a with the given HTML string as its content. This will also trigger an uid to be placed onto the "for" attrbute and the
  • labelAfter (Boolean) Default: false
    • If label prop is set, the will normally be placed before the
  • name (String) Default: null
    • If set, will add the "name" attribute to the
  • uid (String) Default: null
    • If set, the
  • value (String) Default: null
    • Normally, you would use v-model on this component, which itself will set this prop. Either way, if this prop is set, the "value" attribute on the

Attributes Below are the child elements you can pass attributes to, along with a list of attributes it will not accept, if any.

  • label
    • for - this is given either the uid prop or the generated uid if the uid prop is not provided.
  • textarea
    • id - this is given either the uid prop or the generated uid if the uid prop is not provided, if neither of the label nor uid props are set then no id will out on the
    • name - use the prop instead.
    • value - use the prop instead.

Emitted Events

  • input Output: String
    • Set up to emit the 'input' event for use with v-model.

DOM Structure

div.WurldText
    label // if labelAfter = false
    textarea
    label // if labelAfter = true

Directives

sizeObserve

The sizeObserve directive is applied to an element with v-sizeObserve. It will observe the size of the element and apply classes whenever the size raises above a certain width. This will allow responsive design based on the elements width versus the viewports width. Additional modifiers can allow classes to be placed, in addition to the width, based off of the height, top, and left values of the element. Top and left are in comparison to it's parent.

This directive makes use of the ResizeObserver API, with a polyfill, from the resize-observer-polyfill npm module.

NOTE: The width and height are based off the content box, so it will not take margin, padding, or border into account. Therefore is it best to apply this directive to a container.

Config

This section refers to the configuration that can be applied when initially registering Wurld. The options for this directive is the same as value, below. This will adjust the default values for the directive. Any value given to a specific directive's use will override the config option.

Config Default

The following is the registered default, this could change to whatever you would prefer to be the default by changing the config when initially registering Wurld.

{
    width: {
    xxs: 256,
    xs: 512,
    sm: 768,
    md: 1024,
    lg: 1280,
    xl: 1536,
    xxl: 1792
  }
}

Value

  • breakpoints (Object)
    • This object takes four properties: width, height, top, and left. By default, only width is defined. Each of these propertys' values are objects where keys are the classes you would like to apply to the element and the values are the minumum size, in pixels, at which the class is applied. For instance, in the default case, as seen above, if the element's content widthwas 900px it would have the xxs, xs, and sm classes applied to the element.

Modifiers

  • height - This will tell the directive to also observe the height of the element. If a height property is not provided to the breakpoints it will fall back to the width, with 'h-' prepended to the classes. If neither properties are present then this modifier will be ignored.
  • top - This will observe the distance the element is from the top of it's parent. It will only apply classes if a top, class-value object, is provided to the the breakpoints.
  • left - This will observe the distance the element is from the left of it's parent. It will only apply classes if a left, class-value object, is provided to the the breakpoints.

Filters

toPrice

This will convert a string to a "price" string

Config This section refers to the configuration that can be applied when initially registering Wurld. This will change the defaults, but can still be overriden by each use of the toPrice filter. The defaults for this configuration can be seen in the comparable params.

  • pre (String) same as the param below.
  • locale (String) same as the param below.
  • fix (Integer) same as the param below.

Params

  • amount (String / Number)
    • The amount to convert to a price.
  • pre (String) - Default: '$'
    • Anything to precede the amount that is returned.
  • locale (String) - Default: 'en-US'
    • Same arguments accepted by the toLocaleString method.
  • fix (Integer) - Default: 2
    • The amount of digits after the decimal.

Output

The price in the locale number, concatenated to whatever is the 'pre' (preceder) (defaulting to a '$').

toTitleCase

Params

  • string (String)
    • The string you which to convert to title case.

Output

The provided string with the first letter of each word capitalized, and the remaining lowercase.

truncate

Will cut off a string after a certain amount of characters.

Config This section refers to the configuration that can be applied when initially registering Wurld. This will change the defaults, but can still be overriden by each use of the truncate filter. The defaults for this configuration can be seen in the comparable params.

  • limit (Integer) same as the param below.
  • trail (String) same as the param below.

Params

  • string (String)
    • The string you wich to truncate.
  • limit (Integer) - Default: 30
    • The maximum length of the returned string.
  • trail (String) - Default: '...'
    • The string to be concatenated to the end of a truncated string, this counts toward the limit.

Output

A truncated string to the limit provided, which includes any trailing string provided.

Methods

clone

Params

  • element (any)
    • any element to clone, intended for arrays and objects.
  • deep (Boolean) - Default: true
    • Whether or not the clone should be performed on every level of an array or object.

Output

A replication of the element, removing references for arrays and object.

cloneRemoveByKeys

Params

  • element (any)
    • any element to clone, intended for arrays and objects.
  • keys (Array)
    • an array of elements, by their keys, to remove from the array or object.
  • deep (Boolean) - Default: true
    • Whether or not the clone should be performed on every level of an array or object.

Output

A replication of the element, removing references for arrays and object and all elements, designated by their keys provided in the second argument.

cloneRemoveByValues

Params

  • element (any)
    • any element to clone, intended for arrays and objects.
  • values (Array)
    • an array of elements, by their values, to remove from the array or object.
  • deep (Boolean) - Default: true
    • Whether or not the clone should be performed on every level of an array or object.

Output

A replication of the element, removing references for arrays and object and all elements, as designated by their values provided in the second argument.

generateUID

This will generate a unique string

Config This section refers to the configuration that can be applied when initially registering Wurld. This will change the defaults, but can still be overriden by each use of the generateUID method. The defaults for this configuration can be seen in the comparable params.

  • prefix (String) same as the param below.
  • length (Integer) same as the param below.

Params

  • prefix (String) - Default: 'guid'
    • What the generated string would begin with.
  • length (Integer) - Default: 8
    • How many characters the generated string will be, not including the prefix.

Output

A generated string of random characters beginning with the prefix.

getAttrs

This method is a special method that allows attributes to be passed to specific elements in the component. Normally, you could only put attributes on the root element of the component by passing something to the component that is not recognized as a prop. You will need to use this method on all elements that you want to be able to pass attributes to when calling the component.

You specify how you want to target the element by passing a non-spaced string as the second argument of this method. When using the component, you can indicate the element, by the non-spaced, followed by a deliminator and then the attribute you wanna pass, e.g. element:attribute="value", in this case, and by default, the deliminator was a ':'. Try to avoid setting a '.' as the deliminator since this is considered a modifier and will not work if you try to v-bind.

You can bind this method to an element, without providing a second argument. This will make it so that you will not have to indicate the element, and any unrecognized props will simply go to any element that has this method without a second parameter, provided that the prequisite below has been met. This is usually done to the root element to simulate vue's normal behavior.

prerequisites

Make sure to set inheritAttrs: false in the component. To prevent unrecognized props from going as attributes to the root element of the component.

Config This section refers to the configuration that can be applied when initially registering Wurld. This will change the defaults, but can still be overriden by each use of the getAttrs method. The defaults for this configuration can be seen in the comparable params.

  • deliminator (String) same as the param below. Avoid setting it to '.' since this is considered a modifier and will not work if you try to v-bind.

params

  • attrs - ($attrs) required
    • Simply send through the vue instance's $attrs property.
  • element - (String) - Default: null
    • put the name of the element, or something descriptory of the element, that will be used before the deliminator to pass an attribute to the given element.
  • deliminator - (String) - Default: ':'
    • This is the deliminator which separates the element name and the attribute when being passed to the component. Avoid setting it to '.' since this is considered a modifier and will not work if you try to v-bind.

isArray

Params

  • element (any)

Output

A boolean indicating if the element provided was an array.

isObject

Params

  • element (any)

Output

A boolean indicating if the element provided was an object.

isObjectEmpty

Params

  • object (Object)

Output

A boolean indicating if the object provided was empty.

Dependencies (1)

Dev Dependencies (8)

Package Sidebar

Install

npm i wurld

Repository

github.com/Secular12/wurld

Homepage

github.com/Secular12/wurld#readme

Weekly Downloads

5

Version

0.2.2

License

none

Unpacked Size

1.24 MB

Total Files

33

Last publish

Collaborators

  • secular12
Try on RunKit
Report malware