CrosswordsJS

IMPORTANT: This is work in progress! The API may change dramatically as I work out what is most suitable.

Tiny, lightweight crossword for control for the web. Crosswords.js is:

• Lightweight
• Fast
• Simple
• Framework Free

Inspired by the excellent free online crosswords on The Guardian Crosswords.

Demo: dwmkerr.github.io/crosswords-js/

Index

• Quickstart
• Developer Guide
• Keyboard Functionality
• Crossword Definition Tips
• Design Goals
• Build Pipelines
  • Pull Request Pipeline
  • Release Pipeline
• Adding Contributors
• Managing Releases
• Contributors
• TODO

Quickstart

Install:

npm install crosswords-js

Include the JavaScript and CSS:

<link href="node_modules/crosswords-js/dist/crosswords.css" rel="stylesheet" />
<script src="node_modules/crosswords-js/dist/crosswords.js"></script>

To create a crossword, you start with a Crossword Definition, which is a simple JSON representation of a crossword:

{
  "width": 15,
  "height": 15,
  "acrossClues": [
    {
      "x": 2,
      "y": 1,
      "clue": "1. Conspicuous influence exerted by active troops (8,5)"
    },
    {
      "x": 1,
      "y": 3,
      "clue": "10. A coy sort of miss pointlessly promoting lawlessness (9)"
    }
  ]
}

This definition needs to be compiled into a Crossword Model. The model is a two dimensional array of cells. This model is used as the input to create the DOM. Compiling the model validates it, making sure that there are no incongruities in the structure (such as overlapping clues, clues which don't fit in the bounds and so on):

//  Load the crosswords.js API and the crossword definition.
const CrosswordsJS = require('crosswords-js');
const crosswordDefintion = require('./my-crossword.json');

//  Compile the crossword.
try {
  const crosswordModel = CrosswordsJS.compileCrossword(crosswordDefinition);
} catch (err) {
  console.log(`Error compiling crossword: ${err}`);
}

The model can be used to build the DOM for a crossword:

//  Build the crossword HTML, as a child of the document body element.
var crosswordDom = new CrosswordsJS.CrosswordsDOM(
  crosswordModel,
  document.body
);

Developer Guide

Ensure you are using Node LTS. I recommend using Node Version Manager for this:

nvm install --lts --latest-npm
nvm use --lts

Check out the code, then, from the root directory, run:

# Fetch all dependent packages
npm install
# Start the sample app
npm start

The sample will run at the address localhost:8080.

Run the tests with:

npm test

Linting is provided by eslint, which is configured to use prettier:

# Lint the code, or lint and fix.
npm run lint
npm run lint:fix

Documentation and HTML can be checked for standard conformance using prettier:

# Check html and docs for correctness, or check and fix.
npm run prettier
npm run prettier:fix

To automate all these checks on each commit to your local git repository, create a pre-commit hook in your repository:

# From the root directory of the package...
cat << EOF > .git/hooks/pre-commit
#!/bin/sh
npm run prettier:fix && \\
npm run lint:fix && \\
npm test
EOF
chmod u+x .git/hooks/pre-commit

Keyboard Functionality

• Left/Right/Up/Down: Move (if possible) to the cell in the direction specified.
• Space: Move to the next cell in the focused clue, if one exists.
• Backspace: Move to the previous cell in the focused clue, if one exists.
• Tab: Move to the first cell of the next clue, 'wrapping' to the first clue.
• A-Z: Enter the character. Not locale aware!
• Enter: Switch between across and down.

Crossword Definition Tips

How do I create a clue which spans multiple parts of a crossword?

This is a little fiddly. I have tried to ensure the syntax is as close to what a reader would see in a printed crossword to make this as clear as possible. Here is an example:

{
  "downClues": [{
    "x": 6, "y": 1
    "clue": "4,21. The king of 7, this general axed threat strategically (9)"
  }],
  "acrossClues": [{
    "x": 1, "y": 11,
    "clue": "21 See 4 (3,5)"
  }]
}

Note that the answer structure (which would be (9,3,5) in a linear clue) has separated. However, the crossword will render the full answer structure for the first clue (and nothing for the others).

An example of a crossword with many non-linear clues is at: https://www.theguardian.com/crosswords/cryptic/28038 - I have used this crossword for testing (but not included the definition in the codebase as I don't have permissions to distribute it).

Design Goals

This project is currently a work in progress. The overall design goals are:

1. This should be agnostic to the type of crossword. It shouldn't depend on any proprietary formats or structures used by specific publications.
2. This should be accessible, and show how to make interactive content which is inclusive and supports modern accessibility patterns.
3. This project should be simple to use, without requiring a lot of third party dependencies or knowledge.

Build Pipelines

There are two pipelines that run for the project:

Pull Request Pipeline

Whenever a pull request is raised, the Pull Request Workflow is run. This will:

• Install dependencies
• Lint
• Run Tests
• Upload Coverage

Each stage is run on all recent Node versions, except for the 'upload coverage' stage which only runs for the Node.js LTS version. When a pull request is merged to the main branch, if the changes trigger a new release, then Release Please will open a Release Pull Request. When this request is merged, the Release Pipeline is run.

Release Pipeline

When a Release Please pull request is merged to main, the Release Please Workflow is run. This will:

• Install dependencies
• Lint
• Run Tests
• Upload Coverage
• Deploy to NPM if the NPM_TOKEN secret is set

Each stage is run on all recent Node versions, except for the 'upload coverage' stage which only runs for the Node.js LTS version.

⚠️ note that the NPM Publish step sets the package to public - don't forget to change this if you have a private module.

Adding Contributors

To add contributors, use a comment like the below in any pull request:

@all-contributors please add @<username> for docs, code, tests

More detailed documentation is available at:

allcontributors.org/docs/en/bot/usage

Managing Releases

When changes to main are made, the Release Please stage of the pipeline will work out whether a new release should be generated (by checking if there are user facing changes) and also what the new version number should be (by checking the log of conventional commits). Once this is done, if a release is required, a new pull request is opened that will create the release.

Force a specific release version with this command:

version="0.1.0"
git commit --allow-empty -m "chore: release ${version}" -m "Release-As: ${version}"

Contributors

TODO

This is a scattergun list of things to work on, once a good chunk of these have been done the larger bits can be moved to GitHub Issues:

• [x] bug: backspace moves backwards, I think that deleting the letter is a better action for this (with left/up/ key to move backwards)
• [ ] bug: Demo site is not tracking latest version
• [ ] feat(docs): improve the demo site image (its an old one at the moment!)
• [ ] feat(samples): show how we can check answers or highlight incorrect entries (see issue #9)
• [ ] feat(samples): allow us to switch between 2-3 crosswords on the sample
• [ ] feat(samples): cursor initially on the first clue
• [ ] feat(dom): support a keyboard scheme or configurable keybindings so that keys for navigating / editing the crossword can be specified in config (allowing for schemes such as 'the guardian' or 'the age'
• [x] fix: the border on word separators slightly offsets the rendering of the grid
• [ ] feat(accessibility): get screenreader requirements
• [ ] refactor: Simplify the static site by removing Angular and Bootstrap, keeping everything as lean and clean as possible. Later, replace with a React sample? OR have multiple samples, one for each common framework?
• [ ] refactor: finish refactoring classes to simple functions (compileCrossword, createDOM etc)
• [x] feat: support clues which span non-contiguous ranges (such as large clues with go both across and down).
• [ ] feat: simplify the crossword model by using a or d for across or down in the clue text (meaning we don't have to have two arrays of clues)
• [ ] feat: allow italics with underscores, or bold with stars (i.e. very basic markdown)...
• [x] feat: clicking the first letter of a clue which is part of another clue should allow for a toggle between directions
• [ ] todo: document the clue structure
• [ ] refactor: re-theme site to a clean black and white serif style, more like a newspaper
• [x] build: enforce linting (current it is allowed to fail)