cloudfour/core-hbs-helpers

Handlebars helpers that we usually need

core-hbs-helpers's Issues

dummyImgSrc missing from documentation

On the doxdox site, the documentation for dummyImgSrc is missing. I just checked, and it's the only one that's not showing up. I'm not sure why, since there's what appears to be a properly formatted docblock in the code.

toTitle helper is kinda confusing

⚠️ Note: I might just be a dummy.

But I never remember that toTitle only strips off numeric prefixes and nothing else.

For some reason I always assume it will do this. Which isn't even a common need now that there are capitalize helpers.

Now that Drizzle doesn't rely on filename prefixes, it could be that we don't even need this helper. ¯_(ツ)_/¯

Helpers should throw exceptions where applicable

Currently, some do and some don't. I think it's worthwhile to make all helpers that are unfriendly to type-ambiguous arguments throw exceptions when inoperable input is passed in.

Small, logical helpers like if / ifAnd / ifOr should be consolidated somehow

Per the discussion in #1, we should figure out a way to simplify these.

Timestamp helper could be updated based on latest moment.js

The timestamp helper in this repo was written during a transitional time for Moment.js. It has a few quirks that could be corrected:

• It uses Date.now() when Moment will default to the current date/time.
• It uses Date.parse() instead of Moment's improved and highly customizable parsing.
• It uses an isNaN check instead of Moment's stricter isValid method (which could potentially be used to provide more helpful error messages via isValidAt).
• It lacks the ability to activate UTC mode, which can come in very handy for timestamps that are formatted with timezone assumptions.
• It specifies a defaultFormat, which is not really necessary (.format() will output just fine without any arguments).

Add ESLint

We should use eslint in this repo.

• add cloudfour standard config
• add https://eslint.org/docs/rules/valid-jsdoc (to ensure our doxdox keeps working)

Consider replacing "and" and "or" helpers with "all" and "any"

We currently have and and or helpers, which support two arguments.

It would be nice if instead we had helpers that resolved to true if all or any arguments resolve to true. This would work for two or more arguments.

Example helpers from a personal project:

var R = require('ramda');

function all () {
  var options = R.last(arguments);
  var result = true;
  var values;
  var i;

  if (R.isNil(options.fn)) {
    options = undefined;
    values = arguments;
  } else {
    values = R.dropLast(1, arguments);
  }

  for (i = 0; i < values.length; i++) {
    if (!values[i]) {
      result = false;
      break;
    }
  }

  if (options) {
    return result ? options.fn(this) : options.inverse(this);
  }

  return result;
};

function any () {
  var options = R.last(arguments);
  var values, result;

  if (R.isNil(options.fn)) {
    options = undefined;
    values = arguments;
  } else {
    values = R.dropLast(1, arguments);
  }

  result = R.any(R.__, values);

  if (options) {
    return result ? options.fn(this) : options.inverse(this);
  }

  return result;
};

Update readme to link to documentation

This project would be a good fit for https://doxdox.org

We can just output to README.md as Markdown.

Dependency Dashboard

This issue lists Renovate updates and detected dependencies. Read the Dependency Dashboard docs to learn more.

This repository currently has no open or pending branches.

Detected dependencies

github-actions

.github/workflows/ci.yml

• actions/checkout v4@b4ffde65f46336ab88eb53be808477a3936bae11
• actions/setup-node v4

npm

package.json

• capitalize ^2.0.0
• chance ^1.0.3
• handlebars ^4.0.3
• ltx ^3.0.0
• moment ^2.10.6
• num2fraction ^1.2.2
• ramda ^0.29.0
• require-dir ^1.0.0
• tinycolor2 ^1.3.0
• tap-spec 5.0.0
• tape 5.7.5

nvm

.nvmrc

• node 20

---

• Check this box to trigger a request for Renovate to run again on this repository

Set up CI

Things to check on CI:

• Run eslint, ensure there are no lint errors
• Run prettier, ensure there aren't formatting changes

Also add "build passing" badge

ESnext?

I've been totally spoiled by our other repos. In particular, I think Handlebars helpers would benefit a lot from the new parameter stuff.

But, I understand the value of keeping these things lean as well. There could be performance issues or something similar. I'd consider this a low priority nicety.

The naming of "translator" helpers should be normalized

Per discussion in #1, we should consistently rename all helpers that translate and return their input value:

For example:

{{toSlug "Some Title"}}
{{toTitle "some-file-name"}}
{{toFixed someNumber}}
{{toFraction someDecimal}}

Consider replacing moment.js in timestamp helper with leaner alternative

See: https://github.com/you-dont-need/You-Dont-Need-Momentjs

toFraction should not require triple-slash

The toFraction helper currently requires a triple-slash to avoid encoding the already-encoded fraction special characters:

{{toFraction "1.25"}} // => 1¼
{{{toFraction "1.25"}}} // => 1¼

I can see one of the following solutions working instead (in order of my preference):

1. Appending the unicode characters themselves for Handlebars to escape.
2. Returning the result as a Handlebars.safeString (more info)

Nit: LICENSE isn't Markdown

According to GitHub, the license info is "typically named LICENSE or LICENSE.txt." Not sure why ours has the .md extension. ¯_(ツ)_/¯

Update `npm install` in README to install from NPM

We have the HBS helpers published on NPM. Perhaps we should show in the README to install from there instead?

https://www.npmjs.com/package/@cloudfour/hbs-helpers

This:

npm install --save-dev @cloudfour/hbs-helpers

Instead of this:

npm install --save-dev cloudfour/core-hbs-helpers.git

"randomIf" is a potentially confusing name

The {{randomIf}} helper behavior is to render the fn or inverse block at random. IMO, the inclusion of "if" in the name implies that there is some kind of conditional logic.

Would a different name be clearer?

{{#randomBool}}This{{else}}That{{/randomBool}}

{{#trueOrFalse}}This{{else}}That{{/trueOrFalse}}

{{#maybe}}This{{else}}That{{/maybe}}

SVG helper fails a test

The svg helper has a failing test. 🌮

    ✖ Errors when path is not an SVG
    ---------------------------------
      operator: throws
      expected: |-
        '/only supports SVG files\\.$/'
      actual: |-
        { [Error: Incomplete document] message: 'Incomplete document' }
      at: Test.<anonymous> (/Users/erikjung/Projects/cloudfour/core-hbs-helpers/test/svg.spec.js:59:8)

Loosen up `timestamp` regular expression

timestamp

2016-05-16T18:12:09Z
/path/to/repo/core-hbs-helpers/test/timestamp.spec.js:20
test.ok(template().match(iso8601).length > 0, 'Works');
^
TypeError: Cannot read property 'length' of null

moment.js introduced recent changes that cause one of our tests to fail. The suggested action to take is to loosen up the regular expression used in the timestamp test.

Add placeholder img helper

Almost all of our prototyping projects benefit from a placeholder image solution, but most have caveats:

• Placeholder images we save to project asset folders have to be created and managed manually.
• Services like placehold.it or PlaceIMG require external requests, which can hang if connections are slow.
• Client-side solutions like Holder.js require JavaScript, which can be a little tricky to integrate if the project includes both production and documentation-related JavaScript toolkits.

I prototyped a solution that uses a Handlebars helper to generate an SVG based on the provided attributes, encoding it as a data-uri for use in templates. You can see the working prototype here: http://codepen.io/tylersticka/pen/7119ac1f7900118fae7cd5eab2f6e2fa/left?editors=1010

The prototype is tested and working in the latest versions of Safari (desktop + iOS), Chrome and Firefox, as well as IE 10 and up. Tasks remaining:

• Rewrite as a module within this repo
• Write tests for it

Nit: Our use of function.name might be unnecessary

@mrgerardorodriguez asked a good question in this thread:

For my own curiosity, how is capitalize.name resolving to the proper name?

I didn't have an answer, but here is @erikjung's response (source):

https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function/name

But now that you mention it, it's kind of silly to use name on a reference that happens to be using the same value as its own identifier. It would make more sense if we were doing this:

const helper = require('path/to/helper');

Handlebars.registerHelper(helper.name, helper);

Add Tests

This repo needs tests to validate that everything is working as intended when upgrades happen.

Update example comments for dummyImgSrc

This is the lowest of low priorities, but I read these examples first, and then spent a few minutes wondering why my usage of {{placeholder}} wasn't working: https://github.com/cloudfour/core-hbs-helpers/blob/master/lib/dummyImgSrc.js#L62-L68

Should `defaultTo` accept multiple fallbacks?

{{defaultTo something fallback}} is one of my favorite helpers. While writing up cloudfour/drizzle-builder#82, I wondered if it might make sense to accept one or more arguments, returning the first one that evaluates truthy?

Example:

{{defaultTo something somethingElse "okay, fine"}}

Which helpers do we want here?

Currently, we have: https://github.com/cloudfour/core-hbs-helpers/tree/master/lib

├── average.js
├── displayName.js
├── fraction.js *
├── ifAnd.js
├── ifEqual.js
├── ifOr.js
├── random.js
├── randomIf.js
├── slug.js *
├── timestamp.js *
└── toFixed.js *

* renamed from original version

I'm not sure that all of these are useful enough to maintain here, so I welcome others to discuss and decide. Also, there is some room for improvement regarding consistency. For example, some helpers assume more than others about the arguments passed to them, some throw errors, etc. We should make them all appear to have been written by the same person.

Comments are needed

Per discussion in #1, we should include comments in order to document each helper.

Format:

/**
 * This is a helper that helps something.
 *
 * @since v0.1.0
 * @param {String} str
 * @return {String}
 * @see (if applicable)
 * @example
 *
 *   {{toSlug "Some String"}} //=> "some-string"
 */

Add NPM badge

Add badge for our NPM package

NPM HBS Helpers unable to read README

If you view this package on NPM, you'll notice it can't get to the README.

Unable to find a readme for @cloudfour/[email protected]

We should figure out why. 🤔

Add Renovate

All our public tools like this should have a tool installed to make sure we're keeping up-to-date with security patches.

• add renovate
• add renovate badge

Rename for npm publish

• Update package.json name: @cloudfour/hbs-helpers.
• npm version to create new version and tag
• npm publish
• Rename this repo to "hbs-helpers".
• Update package.json repository: cloudfour/hbs-helpers.
• [Maybe] Update package.json cloudfour/core-hbs-helpers.git# endpoints on older projects.

/CC @tylersticka @mrgerardorodriguez