Skip to content

Commit

Permalink
chore(website): Make it more obvious that enum values have descriptio…
Browse files Browse the repository at this point in the history 
…ns, closes vectordotdev#1618

Signed-off-by: binarylogic <[email protected]>
  • Loading branch information
@binarylogic
binarylogic committed Apr 5, 2020
1 parent 8441a7b commit 85aaf00
Show file tree
Hide file tree
Showing 2 changed files with 81 additions and 47 deletions.
105 changes: 71 additions & 34 deletions website/src/components/Field/index.js
View file
Original file line number Diff line number Diff line change
Expand Up @@ -3,13 +3,17 @@ import classnames from 'classnames';
import {MDXProvider} from '@mdx-js/react';
import CodeBlock from '@theme/CodeBlock';

//
// Misc
//

function isObject(a) {
return (!!a) && (a.constructor === Object);
};

function toTOML(value) {
return JSON.stringify(value);
}
//
// TOML
//

function keyToTOML(key) {
if ( key.includes(".") ) {
Expand All @@ -19,59 +23,71 @@ function keyToTOML(key) {
}
}

function exampleToTOML(name, example) {
function valueToTOML(value) {
return JSON.stringify(value);
}

function kvToTOML(name, example) {
if (isObject(example)) {
if ('name' in example && 'value' in example) {
return `${keyToTOML(example.name)} = ${toTOML(example.value)}`;
return `${keyToTOML(example.name)} = ${valueToTOML(example.value)}`;
} else {
return `${keyToTOML(Object.keys(example)[0])} = ${toTOML(Object.values(example)[0])}`
return `${keyToTOML(Object.keys(example)[0])} = ${valueToTOML(Object.values(example)[0])}`
}
} else if (name) {
return `${name} = ${toTOML(example)}`;
return `${keyToTOML(name)} = ${valueToTOML(example)}`;
} else {
return `${toTOML(example)}`;
return valueToTOML(example);
}
}

//
// Enum
//

function Enum({values}) {
let elements = [];

if (!Array.isArray(values)) {
for (var key in values) {
elements.push(<code key={key} title={values[key]}>{toTOML(key)}</code>);
elements.push(<code key={key} className="with-info-icon" title={values[key]}>{valueToTOML(key)}</code>);
elements.push(" ");
}
} else {
for (var index in values) {
let value = values[index];
elements.push(<code key={value}>{toTOML(value)}</code>);
elements.push(<code key={value}>{valueToTOML(value)}</code>);
elements.push(" ");
}
}

return elements;
}

//
// Examples
//

function Example({name, path, unit, value}) {
let unitText = '';

if (unit) {
unitText = <> ({unit})</>;
}

return <><code>{exampleToTOML(null, value)}</code>{unitText}</>;
return <><code>{valueToTOML(value)}</code>{unitText}</>;
}

function Examples({name, path, values}) {
let code = '';

values.forEach(function (value) {
code += (exampleToTOML(name, value) + "\n");
});
if (path) {
code += `${path}.`;
}

if (path) {
code = `[${path}]\n${code}`;
}
code += (kvToTOML(name, value) + "\n");
});

return (
<div>
Expand All @@ -82,17 +98,34 @@ function Examples({name, path, values}) {
);
}

function Groups({values}) {
//
// Values
//

function Value({unit, value}) {
let unitText = '';

if (unit) {
unitText = <> ({unit})</>;
}

return <><code>{valueToTOML(value)}</code>{unitText}</>;
}

function Values({values}) {
let elements = [];

values.forEach(function (value) {
elements.push(<code key={value}>{value}</code>);
elements.push(" ");
})
values.forEach(value => elements.push(<Value value={value} />));

console.log(elements)

return elements;
}

//
// Relevance
//

function RelevantWhen({value}) {
let relKey = Object.keys(value)[0];
let relValue = Object.values(value)[0];
Expand All @@ -103,35 +136,39 @@ function RelevantWhen({value}) {

return (
<span>
<code><a href={`#${relKey}`}>{relKey}</a></code> = <code>{toTOML(relValue)}</code>
<code><a href={`#${relKey}`}>{relKey}</a></code> = <code>{valueToTOML(relValue)}</code>
</span>
);
}

//
// Fields
//

function FieldFooter({defaultValue, enumValues, examples, groups, name, path, relevantWhen, required, unit}) {
const [showExamples, setShowExamples] = useState(false);

if (defaultValue || enumValues || (examples && examples.length > 0) || (groups && groups.length > 0)) {
return (
<div className="info">
<ul className="info">
{relevantWhen ?
<div>Only {required ? 'required' : 'relevant'} when: <RelevantWhen value={relevantWhen} /></div> :
<li>Only {required ? 'required' : 'relevant'} when: <RelevantWhen value={relevantWhen} /></li> :
null}
{defaultValue !== undefined ?
(defaultValue ?
<div>Default: <Example name={name} path={path} value={defaultValue} unit={unit} /></div> :
<div>No default</div>) :
<li>Default: <Value unit={unit} value={defaultValue} /></li> :
<li>No default</li>) :
null}
{enumValues ?
<div>Enum, must be one of: <Enum values={enumValues} /></div> :
<li>Enum, must be one of: <Enum values={enumValues} /></li> :
null}
<div>
<li>
<div className="show-more" onClick={() => setShowExamples(!showExamples)}>
{showExamples ? "Hide examples" : "View examples"}
</div>
{showExamples && <div className="examples"><Examples name={name} path={path} values={examples} /></div>}
</div>
</div>
{showExamples && <Examples name={name} path={path} values={examples} />}
</li>
</ul>
);
} else {
return null;
Expand All @@ -151,10 +188,10 @@ function Field({children, common, defaultValue, enumValues, examples, groups, na
<li className={classnames('field', 'section', (required ? 'field-required' : ''), (collapse ? 'field-collapsed' : ''))} required={required}>
<div className="badges">
{groups && groups.map((group, idx) => <span key={idx} className="badge badge--secondary">{group}</span>)}
{templateable && <span className="badge badge--primary" title="This option is dynamic and accepts the Vector template syntax">templateable</span>}
{templateable && <span className="badge badge--primary with-info-icon" title="This option is dynamic and accepts the Vector template syntax">templateable</span>}
{type && <span className="badge badge--secondary">{type}{unit && <> ({unit})</>}</span>}
{enumValues && Object.keys(enumValues).length > 0 && <span className="badge badge--secondary" title="This option is an enumation and only allows specific values">enum</span>}
{common && <span className="badge badge--primary" title="This is a popular that we recommend for getting started">common</span>}
{enumValues && Object.keys(enumValues).length > 0 && <span className="badge badge--secondary with-info-icon" title="This option is an enumation and only allows specific values">enum</span>}
{common && <span className="badge badge--primary with-info-icon" title="This is a popular that we recommend for getting started">common</span>}
{required ?
<span className="badge badge--danger">required{relevantWhen && '*'}</span> :
<span className="badge badge--secondary">optional</span>}
Expand Down
23 changes: 10 additions & 13 deletions website/src/css/custom.css
View file
Original file line number Diff line number Diff line change
Expand Up @@ -146,6 +146,12 @@ li + li {
text-decoration: underline;
}

.with-info-icon[title]:after {
content: "ⓘ";
display: inline-block;
margin-left: 0.5em;
}

/**
* a
*/
Expand Down Expand Up @@ -599,31 +605,22 @@ ul.connected-list > li > .sub__title {
margin-bottom: 0.25em;
}

ul.connected-list > li .info {
ul.connected-list > li ul.info {
border-left: 1px solid var(--ifm-hr-border-color);
color: var(--ifm-color-content-secondary);
font-size: 0.9em;
margin-top: calc( var(--ifm-spacing-horizontal) * -1 );
margin-bottom: calc( var(--ifm-spacing-vertical) / 2 );
margin-left: 0.25em;
padding-left: var(--ifm-spacing-horizontal);
}

ul.connected-list > li .info > div:before {
content: "• ";
float: left;
display: block;
width: calc( var(--ifm-spacing-horizontal) * 2);
margin-left: calc( var(--ifm-spacing-horizontal) * -2 );
text-align: center;
padding-left: 0.65em;
}

ul.connected-list > li .info .show-more {
ul.connected-list > li ul.info .show-more {
color: var(--ifm-color-primary);
cursor: pointer;
}

ul.connected-list > li .info .examples {
ul.connected-list > li ul.info .examples {
margin-top: 0.5em;
}

Expand Down

0 comments on commit 85aaf00

Please sign in to comment.