usage.js

import React from 'react'
import { Link } from 'gatsby'
import PropTypes from 'prop-types'
import styled from 'styled-components'
import { staticBadgeUrl } from '../../core/badge-urls/make-badge-url'
import { advertisedStyles, shieldsLogos } from '../../supported-features.json'
import StaticBadgeMaker from './static-badge-maker'
import DynamicBadgeMaker from './dynamic-badge-maker'
import { H2, H3, Badge, VerticalSpace } from './common'
import { Snippet, StyledCode } from './snippet'

const LogoName = styled.span`
  white-space: nowrap;
`

const Lhs = styled.td`
  text-align: right;
`

const EscapingRuleTable = styled.table`
  margin: auto;
`

const QueryParamTable = styled.table`
  min-width: 50%;
  margin: auto;
  table-layout: fixed;
  border-spacing: 20px 10px;
`

const QueryParamSyntax = styled.td`
  max-width: 300px;
  text-align: left;
`

const QueryParamDocumentation = styled.td`
  max-width: 600px;
  text-align: left;
`

function QueryParam({ snippet, documentation }) {
  return (
    <tr>
      <QueryParamSyntax>
        <Snippet snippet={snippet} />
      </QueryParamSyntax>
      <QueryParamDocumentation>{documentation}</QueryParamDocumentation>
    </tr>
  )
}
QueryParam.propTypes = {
  snippet: PropTypes.string.isRequired,
  documentation: PropTypes.element.isRequired,
}

function EscapingConversion({ lhs, rhs }) {
  return (
    <tr>
      <Lhs>{lhs}</Lhs>
      <td>→</td>
      <td>{rhs}</td>
    </tr>
  )
}
EscapingConversion.propTypes = {
  lhs: PropTypes.element.isRequired,
  rhs: PropTypes.element.isRequired,
}

function ColorExamples({ baseUrl, colors }) {
  return (
    <span>
      {colors.map((color, i) => (
        <Badge
          alt={color}
          key={color}
          src={staticBadgeUrl({ baseUrl, label: '', message: color, color })}
        />
      ))}
    </span>
  )
}
ColorExamples.propTypes = {
  baseUrl: PropTypes.string.isRequired,
  colors: PropTypes.array.isRequired,
}

function StyleExamples({ baseUrl }) {
  return (
    <QueryParamTable>
      <tbody>
        {advertisedStyles.map(style => {
          const snippet = `?style=${style}&logo=appveyor`
          const badgeUrl = staticBadgeUrl({
            baseUrl,
            label: 'style',
            message: style,
            color: 'green',
            namedLogo: 'appveyor',
            style,
          })
          return (
            <QueryParam
              documentation={<Badge alt={style} src={badgeUrl} />}
              key={style}
              snippet={snippet}
            />
          )
        })}
      </tbody>
    </QueryParamTable>
  )
}
StyleExamples.propTypes = {
  baseUrl: PropTypes.string.isRequired,
}

function NamedLogos() {
  const renderLogo = logo => <LogoName key={logo}>{logo}</LogoName>
  const [first, ...rest] = shieldsLogos
  return [renderLogo(first)].concat(
    rest.reduce((result, logo) => result.concat([', ', renderLogo(logo)]), [])
  )
}

function StaticBadgeEscapingRules() {
  return (
    <EscapingRuleTable>
      <tbody>
        <EscapingConversion
          key="dashes"
          lhs={
            <span>
              Dashes <code>--</code>
            </span>
          }
          rhs={
            <span>
              <code>-</code> Dash
            </span>
          }
        />
        <EscapingConversion
          key="underscores"
          lhs={
            <span>
              Underscores <code>__</code>
            </span>
          }
          rhs={
            <span>
              <code>_</code> Underscore
            </span>
          }
        />
        <EscapingConversion
          key="spaces"
          lhs={
            <span>
              <code>_</code> or Space <code>&nbsp;</code>
            </span>
          }
          rhs={
            <span>
              <code>&nbsp;</code> Space
            </span>
          }
        />
      </tbody>
    </EscapingRuleTable>
  )
}

export default function Usage({ baseUrl }) {
  return (
    <section>
      <H2 id="your-badge">Your Badge</H2>

      <H3>Static</H3>
      <StaticBadgeMaker baseUrl={baseUrl} />

      <VerticalSpace />

      <p>Using dash "-" separator</p>
      <p>
        <Snippet snippet={`${baseUrl}/badge/<LABEL>-<MESSAGE>-<COLOR>.svg`} />
      </p>
      <StaticBadgeEscapingRules />
      <p>Using query string parameters</p>
      <p>
        <Snippet
          snippet={`${baseUrl}/static/v1.svg?label=<LABEL>&message=<MESSAGE>&color=<COLOR>`}
        />
      </p>

      <H3 id="colors">Colors</H3>
      <p>
        <ColorExamples
          baseUrl={baseUrl}
          colors={[
            'brightgreen',
            'green',
            'yellowgreen',
            'yellow',
            'orange',
            'red',
            'blue',
            'lightgrey',
          ]}
        />
        <br />
        <ColorExamples
          baseUrl={baseUrl}
          colors={[
            'success',
            'important',
            'critical',
            'informational',
            'inactive',
          ]}
        />
        <br />
        <ColorExamples
          baseUrl={baseUrl}
          colors={['blueviolet', 'ff69b4', '9cf']}
        />
      </p>

      <H3>Endpoint</H3>

      <p>
        <Snippet snippet={`${baseUrl}/endpoint.svg?url=<URL>&style<STYLE>`} />
      </p>

      <p>
        Create badges from <Link to={'/endpoint'}>your own JSON endpoint</Link>.
      </p>

      <H3 id="dynamic-badge">Dynamic</H3>

      <DynamicBadgeMaker baseUrl={baseUrl} />

      <p>
        <StyledCode>
          {baseUrl}
          /badge/dynamic/json.svg?url=&lt;URL&gt;&amp;label=&lt;LABEL&gt;&amp;query=&lt;
          <a
            href="https://jsonpath.com"
            target="_BLANK"
            title="JSONPath syntax"
          >
            $.DATA.SUBDATA
          </a>
          &gt;&amp;color=&lt;COLOR&gt;&amp;prefix=&lt;PREFIX&gt;&amp;suffix=&lt;SUFFIX&gt;
        </StyledCode>
      </p>
      <p>
        <StyledCode>
          {baseUrl}
          /badge/dynamic/xml.svg?url=&lt;URL&gt;&amp;label=&lt;LABEL&gt;&amp;query=&lt;
          <a href="http://xpather.com" target="_BLANK" title="XPath syntax">
            //data/subdata
          </a>
          &gt;&amp;color=&lt;COLOR&gt;&amp;prefix=&lt;PREFIX&gt;&amp;suffix=&lt;SUFFIX&gt;
        </StyledCode>
      </p>
      <p>
        <StyledCode>
          {baseUrl}
          /badge/dynamic/yaml.svg?url=&lt;URL&gt;&amp;label=&lt;LABEL&gt;&amp;query=&lt;
          <a
            href="https://jsonpath.com"
            target="_BLANK"
            title="YAML (JSONPath) syntax"
          >
            $.DATA.SUBDATA
          </a>
          &gt;&amp;color=&lt;COLOR&gt;&amp;prefix=&lt;PREFIX&gt;&amp;suffix=&lt;SUFFIX&gt;
        </StyledCode>
      </p>

      <VerticalSpace />

      <H2 id="styles">Styles</H2>

      <p>
        The following styles are available. Flat is the default. Examples are
        shown with an optional logo:
      </p>
      <StyleExamples baseUrl={baseUrl} />

      <p>
        Here are a few other parameters you can use: (connecting several with
        "&" is possible)
      </p>
      <QueryParamTable>
        <tbody>
          <QueryParam
            documentation={
              <span>
                Override the default left-hand-side text (
                <a href="https://developer.mozilla.org/en-US/docs/Glossary/percent-encoding">
                  URL-Encoding
                </a>
                {} needed for spaces or special characters!)
              </span>
            }
            key="label"
            snippet="?label=healthinesses"
          />
          <QueryParam
            documentation={
              <span>
                Insert one of the named logos from ({<NamedLogos />}) or{' '}
                <a href="https://simpleicons.org/" target="_BLANK">
                  simple-icons
                </a>
                . Simple-icons are referenced using names as they appear on the
                simple-icons site. If the name includes spaces, replace them
                with dashes (e.g:{' '}
                <StyledCode>?logo=visual-studio-code</StyledCode>)
              </span>
            }
            key="logo"
            snippet="?logo=appveyor"
          />
          <QueryParam
            documentation={<span>Insert custom logo image (≥ 14px high)</span>}
            key="logoSvg"
            snippet="?logo=data:image/png;base64,…"
          />
          <QueryParam
            documentation={
              <span>
                Set the color of the logo (hex, rgb, rgba, hsl, hsla and css
                named colors supported)
              </span>
            }
            key="logoColor"
            snippet="?logoColor=violet"
          />
          <QueryParam
            documentation={
              <span>Set the horizontal space to give to the logo</span>
            }
            key="logoWidth"
            snippet="?logoWidth=40"
          />
          <QueryParam
            documentation={
              <span>
                Specify what clicking on the left/right of a badge should do
                (esp. for social badge style)
              </span>
            }
            key="link"
            snippet="?link=http://left&amp;link=http://right"
          />
          <QueryParam
            documentation={
              <span>
                Set background of the left part (hex, rgb, rgba, hsl, hsla and
                css named colors supported). The legacy name "colorA" is also
                supported.
              </span>
            }
            key="labelColor"
            snippet="?labelColor=abcdef"
          />
          <QueryParam
            documentation={
              <span>
                Set background of the right part (hex, rgb, rgba, hsl, hsla and
                css named colors supported). The legacy name "colorB" is also
                supported.
              </span>
            }
            key="color"
            snippet="?color=fedcba"
          />
          <QueryParam
            documentation={
              <span>
                Set the HTTP cache lifetime (rules are applied to infer a
                default value on a per-badge basis, any values specified below
                the default will be ignored). The legacy name "maxAge" is also
                supported.
              </span>
            }
            key="cacheSeconds"
            snippet="?cacheSeconds=3600"
          />
        </tbody>
      </QueryParamTable>

      <p>
        We support <code>.svg</code>, <code>.json</code>, <code>.png</code> and
        a few others, but use them responsibly.
      </p>
    </section>
  )
}
Usage.propTypes = {
  baseUrl: PropTypes.string.isRequired,
}