bryanbraun / checkboxland

Render anything as HTML checkboxes

Checkboxland

Checkboxland is a JavaScript library for rendering anything as HTML checkboxes.

You can use it to display animations, text, images, video, and arbitrary data. It also supports plugins, so you can add your own APIs.

Checkboxland is dependency-free, framework-agnostic, and fun! 🙃

For more details see the docs.

Setup

Install this package via npm:

npm install checkboxland

Example

Import it into your application, and create a checkbox grid:

import { Checkboxland } from 'checkboxland';

const cbl = new Checkboxland({ dimensions: '8x7', selector: '#my-container' });

// Create a data representation of the heart.
const heart = [
  [0,1,1,0,0,1,1,0],
  [1,0,0,1,1,0,0,1],
  [1,0,0,0,0,0,0,1],
  [1,0,0,0,0,0,0,1],
  [0,1,0,0,0,0,1,0],
  [0,0,1,0,0,1,0,0],
  [0,0,0,1,1,0,0,0],
];

// This updates the grid with the data we provided.
cbl.setData(heart);

Contributing

Checkboxland is designed to be extendable. If you want to add a feature, first ask yourself if it could be done as an external plugin.

If you contribution requires a change to the core library, follow these steps:

1. Fork/Clone the repo.
2. Make your changes on a feature branch.
3. Run the docs site locally (npm run dev) to confirm that the demos still work as expected.
4. Submit a Pull Request.

License

MIT

checkboxland's Issues

Normalize checkbox colors across browsers using "accent-color"

Currently different browsers display different default checkbox colors:

Edge:

Safari:

Chrome:

We can use the new accent-color CSS property to make them all the same color across browsers (at least for the browsers that support it). I'd suggest that we make them all the same as the safari color (since it's blue-ish and that browser doesn't yet support accent-color yet).

For now, we can start by just adding these style changes to this normalize stylesheet (and possibly renaming the stylesheet from normalize-size.css to normalize.css): https://github.com/bryanbraun/checkboxland/blob/main/docs/css/cbl-normalize-size.css .

Add support for new renderImage and renderVideo dataSources

The renderImage and renderVideo plugins would be a bit more flexible if they accepted other dataSources like:

• UInt8ClampedArray
• ArrayBuffer
  • We would need to convert it into a UInt8ClampedArray before we could put it on our canvas (see https://jameshfisher.com/2020/03/01/how-to-write-an-arraybuffer-to-a-canvas/).

These dataSources would add support for additional use cases, including:

• Uploading longer videos (those that are too long to be successfully converted to a data URL).
• Enable uploading of animated gifs, using third-party conversion tools like Gifler or Gifuct.
• ...probably other ones!

Replace "@pika/pack" and it's plugins with a better publishing method

@pika/pack is no longer being developed. See the archived repo here: https://github.com/FredKSchott/pika-pack

We should transition this to a better supported publishing method. The key features I'd want to support is:

• Allows me to write the code in a valid, runnable, ESModule format.
• Bundles specifically to esmodules output format (see: https://parceljs.org/features/targets/#outputformat)
• Includes a way to generate typings
  • If the tool doesn't support this out of the box, we could use JSDoc style type annotations and a one-time .d.ts build step that runs prior to publishing, as described in this post: https://dev.to/open-wc/generating-typescript-definition-files-from-javascript-5bp2

Option 1: Parcel

• Tried and true.
• I suspect it doesn't support type publishing.

Option: 2: Publish to JSR

• This would be a good proof of concept for JSR, and testing it out on a "fun" library like this feels low risk
• It feels promising. More details here: https://syntax.fm/show/737/jsr-the-new-typescript-package-registry-npm-killer

Suggestion: basic drawing

I thought that maybe a plugin to draw things like the standard 2d canvas context api would improve the thing a lot.
@bryanbraun What do you think about that?

Safari: the CSP blocks AnchorJS's dynamic style creation, causing anchor-js to fail.

In Safari, anchor-js fails to load because the newly-added CSP is blocking dynamic style addition.

This appears to be a browser bug, specific to Safari. This issue describes what's happening, as such:

Based on a Twitter convo with @mikewest https://twitter.com/tabatkins/status/1189288783738523648, it looks like the restriction on script-created style elements is probably an accident of implementation, not an intentional restriction. Thus script-created CSSStyleSheets should be fine to stay un-restricted by CSP.

Thus, we could wait until Safari fixes it, or remove / loosen the CSP significantly (perhaps with style-src: 'unsafe-inline');

When this package is minified/bundled, the extension names can get stripped, which throws errors

Steps to reproduce:

1. Import this package via webpack, and create a Checkboxland instance in your code: var cbl = new Checkboxland();
2. Create a bundle: npx webpack
3. Load the page, and see this error

Uncaught Error: Your plugin must be a function with a "name" property.

Note this is being thrown on Checkboxland's internal plugins, like print and marquee.

Lasers demo: beam sometimes fails when clicking on the edge

In the lasers demo, if you click on the edge of the grid, there's a chance that the beam fails to deploy, like this checkbox in the bottom-right:

There are no javascript errors. It's likely because the randomly chosen direction points in such a way that the code doesn't know which way it needs to be reflected.

typescript support (plugins)

what a fun library! thanks @bryanbraun 👏

i noticed you're using pika for automatically building types. this is rad for the main checkboxland instance, but, when it comes to plugins those types are not inferred. since a plugin's js file does not export its internal functions, pika doesnt either.

---

for example, in print.js, if the print function is exported too

export default {
  name: 'print',
  exec: print,
  print // added this line
}

THEN, i believe the output .d.ts file would look something like:

declare namespace _default {
    export const name: string;
    export { print as exec };
    export { print as print }; // added this line
}
export default _default;
declare function print(text: any, options?: {}): any;

and THEN people using your lib in typescript could augment the main checkboxland class w plugins as needed, something like:

import { Checkboxland } from 'checkboxland';
import CblPluginPrintTypes from '../../node_modules/checkboxland/dist-types/plugins/print/print';
// augmented 
type CblPluggedIn = Checkboxland & typeof CblPluginPrintTypes;
const cbl = new Checkboxland({ dimensions }) as CblPluggedIn;
cbl.print('words'); // works correctly without ts errors

---

of course, there are other ways to correctly add plugin typings to the cbl class in typescript and maybe you have an idea for the builtin plugins, just offering one solution.

cheers

Suggestion: 'ghost mode'

Hi, I did something like this a few years ago, see:

http://johnhorner.info/dot-matrix/

not nearly as modern as yours. However I also came up with 'ghost mode' which uses disabled checkboxes instead of checked ones for a muted effect. You could also have inverted ghost mode, where the background boxes were disabled and the foreground enabled? Possibly even very crude anti-aliasing.

Anyway, love your work, just a suggestion.

sh: pika: command not found

I try to run this locally and I get sh: pika: command not found

I guess pika is missing in dependencies? I have no idea what that is. I see pika-pack but no pika

Allow users to set individual checkbox colors via the API

not sure if this could be doable with a plug-in, but it was harder than I expected to find an answer that tells me how to change color of the checkbox.

Apparently the key property is accent-color: https://stackoverflow.com/questions/4148499/how-to-style-a-checkbox-using-css/58570835#58570835

Cycle through the demos at the top of the page automatically

Like the matterjs docs do.

Ideally:

• They cycle automatically, but if you click to look at a specific one it interrupts the cycle permanently.

Extra credit:

• We find a way to prevent the flash between demos, possibly by having the next iFrame loads behind the existing one, and then having the existing one disappear.

Does this plugin work with gatsby.js for react?

Unable to get it to run on first try importing the example code as it's own component

Receiving the error
Warning: validateDOMNesting(...): <a> cannot appear as a descendant of <a>. and
TypeError: Cannot set property 'innerHTML' of null

thank you!

Add a basic "Dithering" option to renderImage() and renderVideo()

Rendering Images and Videos would likely look better if we were to pass the pixel data through a dithering algorithm (see https://en.wikipedia.org/wiki/Dither).

We could probably pull in a library or basic algorithm off the shelf, add it to renderMediaAsCheckboxes.js, and expose it as an option in the renderImage() and renderVideo() plugins (either as a boolean, or—if there are multiple options—as a string/enum).

No default import for common-js is making it hard for webpack-like systems to import things.

I think some of these tools look for index.js by default but currently, there is no index.js.

From JSDeliver:

From Codepen (possibly related):

Here's a workaround, if you're using es6 modules (which you can in codepen):

import { Checkboxland } from '//unpkg.com/checkboxland?module';

Make the "Conways Game of Life" demo interactive

Here's the link to the demo: https://www.bryanbraun.com/checkboxland/docs/demos/game-of-life/

Currently, if you pause the game, check some boxes, and then unpause, the newly checked boxes don't affect the game. They are simply overridden by the internal state of the game.

A nice improvement would be to make it interactive. We could do this by pulling the state of the grid from Checkboxland with each iteration (using .getData()), and feeding that into our Conways code.

Get a bunch of cool images

• OG images for the docs site
• OG image for the github repo
• A good demo image for the top of the README.
• Images to include in a blog post.
  • Animated gifs, for each of the demos

User input events

Is there any way to detect user clicks? Do you plan to add this in the future?