crosswords-js
Advanced tools
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:
Inspired by the excellent free online crosswords on The Guardian Crosswords.
Demo: dwmkerr.github.io/crosswords-js/
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
);
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
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).
This project is currently a work in progress. The overall design goals are:
There are two pipelines that run for the project:
Whenever a pull request is raised, the Pull Request Workflow is run. This will:
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.
When a Release Please pull request is merged to main, the Release Please Workflow is run. This will:
NPM_TOKEN secret is setEach 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.
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
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}"
 Dave Kerr 📖 💻 ⚠️ |  Paul Spain 📖 💻 ⚠️ |
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:
a or d for across or down in the clue text (meaning we don't have to have two arrays of clues)FAQs
Tiny, lightweight crosswords for HTML5/JS/CSS.
We found that crosswords-js demonstrated a not healthy version release cadence and project activity because the last version was released a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
Socket CEO Feross Aboukhadijeh discusses open source security challenges, including zero-day attacks and supply chain risks, on the Cyber Security Council podcast.
Security News
Research
Socket researchers uncover how threat actors weaponize Out-of-Band Application Security Testing (OAST) techniques across the npm, PyPI, and RubyGems ecosystems to exfiltrate sensitive data.
Security News
Research
A malicious npm campaign is targeting Ethereum developers by impersonating Hardhat plugins and the Nomic Foundation, stealing sensitive data like private keys.