crosswords js
v0.1.14
IMPORTANTE : Este é um trabalho em andamento! A API pode mudar drasticamente à medida que eu descubro o que é mais adequado.
Controle de palavras cruzadas pequeno e leve para a web. palavras cruzadas-js é:
Inspirado nas excelentes palavras cruzadas online gratuitas do The Guardian Crosswords.
Demonstração: dwmkerr.github.io/crosswords-js/
A documentação do projeto está escrita em Markdown e está localizada no repositório em ./docs .
Instale o pacote:
npm install crosswords-jsInclua a fonte do pacote JavaScript minificado e CSS em sua página da web:
< link
href =" node_modules/crosswords-js/dist/crosswords.css "
rel =" stylesheet "
/>
< script src =" node_modules/crosswords-js/dist/crosswords.js " > </ script > Para criar palavras cruzadas, localize ou edite um CrosswordSource , que pode ser import de um arquivo JSON simples para criar um CrosswordDefinition :
{
"width" : 15 ,
"height" : 15 ,
"acrossClues" : [
{
"x" : 1 ,
"y" : 1 ,
"clue" : " 1. Conspicuous influence exerted by active troops (8,5) "
},
...
],
"downClues" : [
{
"x" : 3 ,
"y" : 1 ,
"clue" : " 1. A coy sort of miss pointlessly promoting lawlessness (9) "
},
...
]
}Exemplos completos de arquivos CrosswordSource podem ser encontrados aqui, ali ou em qualquer lugar.
Mais adiante, o CrosswordDefinition precisa ser compilado em um CrosswordModel . A compilação valida o CrosswordDefinition , certificando-se de que não haja incongruências na estrutura, por exemplo:
No seu código JavaScript, carregue o pacote crosswords-js e um CrosswordDefinition :
import { compileCrossword , newCrosswordController } from 'crosswords-js' ;
import crosswordDefinition from 'node_modules/crosswords-js/data/ftimes_17095.json' ;Agora obtenha os elementos DOM que serão os pais da grade de palavras cruzadas e dos blocos de dicas:
Por exemplo, se tivermos elementos
divde espaço reservado em algum lugar de nossa página da web:... < div id =" crossword-grid-placeholder " /> ... < div id =" crossword-clues-placeholder " />Localizamos o elemento por meio do DOM da página da web:
const gridParent = document . getElementById ( 'crossword-grid-placeholder' ) ; const cluesParent = document . getElementById ( 'crossword-clues-placeholder' ) ;
E passe os elementos crosswordDefinition , gridParent e viewParent para o construtor Controller :
let controller = newCrosswordController (
crosswordDefinition ,
gridParent ,
cluesParent ,
) ;Isso vincula o gridView de palavras cruzadas e pistasView ao DOM da página da web.
Você pode usar o controller para manipular programaticamente o gridView - o elemento DOM da grade de palavras cruzadas.
Chame os métodos do manipulador de eventos do usuário do controller diretamente no código
// Check the current clue answer against the solution.
controller . testCurrentClue ( ) ; Vincule os métodos do manipulador de eventos do usuário por meio de atributos id ou class em elementos DOM em sua marcação HTML, como botões .
< div id =" clue-buttons " >
< p > Clue </ p >
< button id =" test-clue " > Test </ button >
< button id =" clean-clue " > Clean </ button >
< button id =" reveal-clue " > Reveal </ button >
< button class =" reset-clue " > Reset </ button >
< button class =" reset-clue " > MoSet </ button >
</ div > // Bind one element with id "test-clue"
controller . bindEventHandlerToId ( "test-clue" , "click" , document ) ;
// Using default arguments for
// eventName ("click") and dom (document)
controller . bindEventHandlerToId ( "reveal-clue" ) ;
// Bind event handler to multiple elements with class "reset-clue"
// default arguments are available as before
controller . bindEventHandlerToClass ( "reset-clue" , "click" , document ) ;
} ) ;
// Bind ALL the user event handlers, using defaults
controller . bindEventHandlersToIds ( ) ;
// Bind the user event handlers to ALL elements with
// the given class(es), passing an array of one or more class names
controller . bindEventHandlersToClass ( [ "reset-clue" ] ) ;Para mais informações sobre estes tópicos, consulte a documentação da API do módulo.
Para obter exemplos, consulte o código do servidor de desenvolvimento.
A biblioteca vem com alguns estilos padrão simples prontos para uso, mas pretende ser facilmente personalizável. Consulte crossword-styling.md para obter detalhes.
O servidor de desenvolvimento é um aplicativo Node.js puro do pacote crosswords-js . Ele exercita quase todas as funcionalidades disponíveis. O código é encontrado no diretório dev deste repositório.
# Open the development server on http://localhost:5173
npm startRecomendamos fortemente que você siga o popular fluxo de trabalho "triangular", conforme recomendado pelo GitHub, ao trabalhar neste projeto. Ajuda a colaboração ao:
- produzindo sequências de commit simples e lineares para solicitações pull, e
- incorporando facilmente alterações no repositório upstream.
Confira o código e abra o diretório raiz do repositório...
git clone https://github.com/dwmkerr/crosswords-js.git &&
cd crosswords-jsentão...
# From the repository root, bootstrap the package and all tools
bin/bootstrap-posix-ish.sh
# Open the development server
npm startSe você estiver executando uma versão moderna do Windows, poderá adicionar uma distribuição Linux ao seu computador usando WSL e seguir as instruções do Linux acima.
Se o script acima falhou ou não se adequa ao seu ambiente...
# Install/update node to latest long-term-support (LTS) version, and install/update npm to latest version.
nvm install --lts --latest-npm
nvm use --ltsgit clone https://github.com/dwmkerr/crosswords-js.git cd crosswords-js
# Fetch all dependent packages
npm install
# Start the development server
npm startSe você instalou o Node Version Manager (nvm) seguindo o procedimento recomendado, poderá manter-se atualizado com as versões mais recentes do nvm, npm, node LTS e as versões mais recentes do pacote para este módulo executando regularmente:
# Update the tools and packages used in this environment
npm run updateVocê pode automatizar as verificações manuais na seção abaixo em cada commit em seu repositório git local.
npm run qa:installSe você precisar ignorar as verificações automatizadas, prepare suas alterações e execute:
git commit --no-verify
Usamos MochaJS para testes unitários. O código-fonte do teste está localizado no repositório em ./test . Execute os testes com:
npm testLinting é fornecido pelo ESLint, que também está configurado para usar Prettier para formatação de código:
# Lint the code.
npm run lint
# Lint and fix the code.
npm run lint:fixA documentação e o HTML podem ser verificados quanto à conformidade padrão usando o Prettier:
# Check html and docs for correctness.
npm run prettier
# Check and fix html and docs for correctness.
npm run prettier:fixA ortografia pode ser verificada usando CSpell:
# Check _staged_ files for spelling.
npm run spell
# Check new and changed files for spelling.
npm run spell:changed
# Check all files for spelling.
npm run spell:allCertifique-se de construir e preparar os ativos de produção
# Build and stage the production assets
npm run build && git add dist/Instale nosso modelo de commit do git. Isso permite que as diretrizes de commit do projeto sejam prefixadas à mensagem padrão do git commit. No diretório raiz do seu repositório:
git config --local commit.template ./.git-commit-template.txt Os ativos de produção do ambiente dev são construídos pelo ViteJS em dev/dist . A pasta dist é criada quando os ativos são criados.
# Build the assets under dev/dist
npm run dev:build Você pode visualizar os ativos de produção executando o seguinte comando e abrindo um navegador em http://localhost:4173/
# Build the assets and preview locally at http://locahost:4173
npm run dev:previewVocê também pode encontrar esses atalhos de teclado na documentação
Estes são os atalhos padrão:
Você pode substituir os atalhos padrão criando seus próprios conjuntos eventBinding . Isso é descrito em um caso de uso de API.
Isso é um pouco complicado. Tentei garantir que a sintaxe fosse o mais próxima do que um leitor veria em palavras cruzadas impressas para deixar isso o mais claro possível. Aqui está um exemplo:
{
"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) "
}]
} Observe que o LengthText (que seria (9,3,5) em uma pista linear) foi separado. No entanto, as palavras cruzadas GridView renderizarão o LengthText completo para o primeiro segmento de pista (principal) (e nada para os segmentos finais).
Um exemplo de palavras cruzadas com muitas pistas multissegmentadas está em: https://www.theguardian.com/crosswords/cryptic/28038 - usei essas palavras cruzadas para teste (mas não incluí a definição na base de código, pois não não tenho permissão para distribuí-lo).
Apoiamos um subconjunto de Markdown.
**bold** text . Essas tags Markdown são convertidas em estilos CSS em pistasView ou em qualquer outro lugar que as pistas sejam exibidas.partial*italic*sa _comp**lic**ated_ example| Estilo | Etiqueta de redução | Exemplo | Classe CSS associada |
|---|---|---|---|
| itálico | _ ou * | Some _italic_ text. | .cw-italic { font-style: italic; } |
| audacioso | __ ou ** | Some **bold** text. | .cw-bold { font-weight: bold; } |
| negrito-itálico | ___ ou *** | Some ___bold, italic___ text. | As aulas acima são combinadas. |
Determinamos as dimensões do GridView dinamicamente sempre que um CrosswordSource é carregado.
O design deste projeto segue o padrão de design Model-view-controller (MVC). A nomenclatura de arquivos e artefatos de código segue esse padrão.
Este projeto é atualmente um trabalho em andamento. Os objetivos gerais do design são:
Existem dois fluxos de trabalho executados para o projeto:
Sempre que uma solicitação pull é gerada, o fluxo de trabalho da solicitação pull é executado. Isto irá:
Cada estágio é executado em todas as versões recentes do Node, exceto o estágio de cobertura de upload , que é executado apenas para a versão LTS do Node.js. Quando uma solicitação pull é mesclada com o branch main , se as alterações acionarem uma nova versão, o Release Please abrirá uma solicitação pull de liberação. Quando esta solicitação é mesclada, o fluxo de trabalho principal é executado.
Quando uma solicitação pull Release Please é mesclada com main, o fluxo de trabalho principal é executado. Isto irá:
NPM_TOKEN estiver definidoCada estágio é executado em todas as versões recentes do Node, exceto o estágio de cobertura de upload , que é executado apenas para a versão LTS do Node.js.
️ Observe que a etapa NPM Publish define o pacote como público - não se esqueça de alterar isso se você tiver um módulo privado.
Para adicionar contribuidores, use um comentário como o abaixo em uma solicitação pull Node.jsy:
@all-contributors please add @<username> for docs, code, tests
Documentação mais detalhada está disponível em:
allcontributors.org/docs/en/bot/usage
Quando alterações no main são feitas, o estágio Release Please do fluxo de trabalho determinará se um novo release deve ser gerado (verificando se há alterações voltadas ao usuário) e também qual deve ser o novo número da versão (verificando o log de versões convencionais). comete). Feito isso, se uma liberação for necessária, uma nova solicitação pull será aberta que criará a liberação.
Force uma versão de lançamento específica com este comando:
# Specify your version. We use Semantic Versioning (https://semver.org/)
version= " 0.1.0 "
git commit --allow-empty -m " chore: release ${version} " -m " Release-As: ${version} " David Kerr | Paulo Espanha | Misha Kaletsky ? |
Esta é uma lista dispersa de coisas para trabalhar, uma vez que uma boa parte delas tenha sido feita, as partes maiores podem ser movidas para Problemas do GitHub:
a ou d para across ou down no texto da pista (o que significa que não precisamos ter duas matrizes de pistas) 
