National Puppy Menace

    @svag/lib

    2.0.0 • Public • Published

    @svag/lib

    npm version

    @svag/lib is a library for drawing SVGs from JavaScript with a set of useful methods, such as to create elements and rounded corners. It is used in other svag packages, e.g., @svag/window

    yarn add -E @svag/lib

    Table Of Contents

    Types

    There are some common types used by various methods. They are described in this section.

    Coordinate: A coordinate used for drawing.

    Name Type Description Default
    x* number The x position of the coordinate. -
    y* number The y position of the coordinate. -

    string|number length: A length is a distance measurement, given as a number along with a unit.

    string percentage: Percentages are specified as a number followed by a % character.

    API

    The package library exports a number of functions, including makeElement and minify.

    import { makeElement, minify } from '@svag/lib'

    makeElement(
      name: string,
      options?: MakeElementOptions,
    ): string

    This function will create an element as a string given its name and the options. The attributes will be split by new lines whenever the line width reaches the length of 100 symbols, and each line of the content will be indented by 2 spaces as well.

    MakeElementOptions: Options to make a new element.

    Name Type Description Default
    content string|string[] The content to write inside of the element, such as string or an array of strings. -
    attributes object A map of attributes to add to the element. -
    import { makeElement } from '@svag/lib'
    
    const circle = makeElement('circle', {
      attributes: {
        cx: 50,
        cy: 50,
        r: 25,
      },
    })
    const rect = makeElement('rect', {
      attributes: {
        width: '100',
        height: '100',
      },
    })
    const g = makeElement('g', {
      attributes: {
        fill: 'green',
      },
      // 1. SET Single content attribute
      content: rect,
    })
    const element = makeElement('g', {
      name: 'g',
      attributes: {
        test: true,
        'font-size': '12px',
      },
      // 2. SET Multiple content attributes
      content: [circle, g],
    })
    <g test="true" font-size="12px">
      <circle cx="50" cy="50" r="25"/>
      <g fill="green">
        <rect width="100" height="100"/>
      </g>
    </g>

    minify(
      svg: string,
    ): string

    Removes the whitespace between the elements in the input string.

    import { minify } from '@svag/lib'
    
    const svg = `
    <g>
      <circle fill="#FF5F52" cx="5" cy="5" r="5.25"/>
      <circle stroke="#E33E32" stroke-width="1" cx="5" cy="5" r="5.5"/>
    </g>
    <g>
      <circle fill="#FFBE05" cx="25" cy="5" r="5.25"/>
      <circle stroke="#E2A100" stroke-width="1" cx="25" cy="5" r="5.5"/>
    </g>
    <g>
      <circle fill="#15CC35" cx="45" cy="5" r="5.25"/>
      <circle stroke="#17B230" stroke-width="1" cx="45" cy="5" r="5.5"/>
    </g>
    `
    
    const minified = minify(svg)
    <g><circle fill="#FF5F52" cx="5" cy="5" r="5.25"/><circle stroke="#E33E32" stroke-width="1" cx="5" cy="5" r="5.5"/></g><g><circle fill="#FFBE05" cx="25" cy="5" r="5.25"/><circle stroke="#E2A100" stroke-width="1" cx="25" cy="5" r="5.5"/></g><g><circle fill="#15CC35" cx="45" cy="5" r="5.25"/><circle stroke="#17B230" stroke-width="1" cx="45" cy="5" r="5.5"/></g>

    roundedCorner(
      from: Coordinate,
      to: Coordinate,
      anticlockwise?: boolean,
    ): string

    Create a C directive to include in a path element to create a rounded corner. If anticlockwise argument is passed, the path will follow the counter-clockwise movement.

    Clockwise: The table below shows the corners drawn clockwise.

    Direction Usage Output Preview
    Top Right
    import { roundedCorner } from '@svag/lib'
    const C = roundedCorner({
      x: 0,
      y: 1,
    }, {
      x: 50,
      y: 51,
    })
    C 25 1, 50 26, 50 51

    top-right

    Bottom Right
    import { roundedCorner } from '@svag/lib'
    
    const C = roundedCorner({
      x: 60,
      y: 0,
    }, {
      x: 10,
      y: 50,
    })
    C 60 25, 35 50, 10 50

    bottom-right

    Bottom Left
    import { roundedCorner } from '@svag/lib'
    
    const C = roundedCorner({
      x: 60,
      y: 60,
    }, {
      x: 10,
      y: 10,
    })
    C 35 60, 10 35, 10 10

    bottom-left

    Top Left
    import { roundedCorner } from '@svag/lib'
    
    const C = roundedCorner({
      x: 1,
      y: 60,
    }, {
      x: 51,
      y: 10,
    })
    C 1 35, 26 10, 51 10

    top-left

    Anticlockwise: The table below shows the corners drawn anticlockwise.

    Direction Usage Output Preview
    Top Right
    import { roundedCorner } from '@svag/lib'
    
    const C = roundedCorner({
      x: 60,
      y: 60,
    }, {
      x: 10,
      y: 10,
    }, true)
    C 60 35, 35 10, 10 10

    anticlockwise top-right

    Top Left
    import { roundedCorner } from '@svag/lib'
    
    const C = roundedCorner({
      x: 60,
      y: 1,
    }, {
      x: 10,
      y: 51,
    }, true)
    C 35 1, 10 26, 10 51

    anticlockwise top-left

    Bottom Left
    import { roundedCorner } from '@svag/lib'
    const C = roundedCorner({
      x: 1,
      y: 0,
    }, {
      x: 51,
      y: 50,
    }, true)
    C 1 25, 26 50, 51 50

    anticlockwise bottom-left

    Bottom Right
    import { roundedCorner } from '@svag/lib'
    
    const C = roundedCorner({
      x: 1,
      y: 60,
    }, {
      x: 51,
      y: 10,
    }, true)
    C 26 60, 51 35, 51 10

    anticlockwise bottom-right

    Elements

    This section describes how to create individual elements.

    svg(
      options: SVGOption,
    ): string

    Generate an svg element with given content and dimensions.

    SVGOptions: An option for creating an svg.

    Name Type Description Default
    width* number The width of the svg. -
    height* number The height of the svg. -
    content* string The content to put inside of the svg. -
    stretch boolean Expand the svg to the width of the container by not setting width and height attributes. true
    import { svg } from '@svag/lib'
    
    const stretchedSvg = svg({
      height: 100,
      width: 100,
      content: '<example />',
    })
    <svg version="1.1" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink"
         viewBox="0, 0, 100, 100">
      <example />
    </svg>

    To generate an svg which will not adjust its size to the viewport, the stretch option needs to be set to false.

    import { svg } from '@svag/lib'
    
    const fixedSvg = svg({
      height: 100,
      width: 100,
      content: '<example />',
      stretch: false,
    })
    <svg version="1.1" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink"
         viewBox="0, 0, 100, 100" width="100px" height="100px">
      <example />
    </svg>

    rect(
      attributes: RectAttributes,
    ): string

    Create a <rect> element.

    RectAttributes: Non-global attributes for the element.

    Name Type Description Default
    x length|percentage This attribute determines the x coordinate of the rect. 0
    y length|percentage This attribute determines the y coordinate of the rect. 0
    width 'auto'|length|percentage This attribute determines the width of the rect. auto
    height 'auto'|length|percentage This attribute determines the height of the rect. auto
    rx 'auto'|length|percentage This attribute determines the horizontal corner radius of the rect. auto
    ry 'auto'|length|percentage This attribute determines the vertical corner radius of the rect. auto
    pathLength number This attribute lets specify the total length for the path, in user units. -
    import { rect } from '@svag/lib'
    
    const image = rect({
      height: 100,
      width: 100,
      rx: '0.5em',
      ry: '0.5em',
    })
    <rect height="100" width="100" rx="0.5em" ry="0.5em"/>

    TODO

    • [ ] Create an alias for each SVG element, e.g., circle, etc, and parse their documentation from MDN.
    • [ ] Update documentary to make sure that types are linked to their description.
    • [ ] Update alamode to be able to write XML syntax (JSX transform).
    • [ ] Update minify to work correctly with attributes on new lines.

    Copyright

    Some of the element documentation, including rect was taken directly from MDN.

    (c) SVaG 2018

    Install

    npm i @svag/lib

    DownloadsWeekly Downloads

    7

    Version

    2.0.0

    License

    MIT

    Unpacked Size

    38.3 kB

    Total Files

    14

    Last publish

    Collaborators

    • zvr