The standard design for Puzzle tools as a set of Web Components.
The Puzzle Shell project strives for the following goals:
- Integration of internal tools & solutions into the Puzzle identity
- Uniform and consistent presentation with recognizability across tools & solutions
- Providing a flexible construction kit without rigid specifications
Part of this project is the Puzzle Shell Storybook that lists and documents all Puzzle Shell components and contains usage examples.
You can install this package with NPM:
npm i @puzzleitc/puzzle-shellOr Yarn:
yarn add @puzzleitc/puzzle-shellOr PNPM:
pnpm add @puzzleitc/puzzle-shellThen, with a bundler like Vite, you can import the package in your main JavaScript file to include all components:
import "@puzzleitc/puzzle-shell";
import "@puzzleitc/puzzle-shell/style.css";Or you can import specific components:
import "@puzzleitc/puzzle-shell/components/Topbar.js";
import "@puzzleitc/puzzle-shell/style.css"; // Only onceEither way the components are then ready to use in your markup:
<pzsh-topbar></pzsh-topbar>We suggest to include the library this way if possible.
Alternatively you can use a pre-bundled version of the Puzzle Shell that includes Lit as a carefree package. You can even reference the package from a NPM CDN (or self-serve it) and include it as follows:
<html>
<head>
<link
rel="stylesheet"
href="https://unpkg.com/@puzzleitc/puzzle-shell/dist/style.css"
/>
<script
type="module"
src="https://unpkg.com/@puzzleitc/puzzle-shell/dist/bundle.js"
></script>
</head>
<body>
<pzsh-container>
<pzsh-topbar></pzsh-topbar>
<main></main>
<pzsh-footer></pzsh-footer>
</pzsh-container>
</body>
</html>To scan the project for linting or type errors, run:
npm run lintTo automatically fix many linting errors & reformat code using Prettier, run:
npm run lint:fixTo automatically generate the custom-elements.json manifest using the web-component-analyzer, run:
npm run manifestTo run a local instance of Storybook, run:
npm run storybookTo build a production version of Storybook, run:
npm run build-storybookThe mobile/desktop breakpoint of the Puzzle Shell is at 800px per default. Below that screen width, the hamburger menu is displayed, paddings will change etc. To customize this breakpoint, you can set the global window.pzshBreakpoint property to another value before the Puzzle Shell import, e.g.:
<script>
window.pzshBreakpoint = 1024;
</script>
<script
type="module"
src="/path/to/@puzzleitc/puzzle-shell/dist/puzzle-shell.js"
></script>To publish a new package version, do the following:
- Build the library with
npm run build - Execute
npm run manifestto make sure thecustom-elements.jsonmanifest is up-to-date - Update the
CHANGELOG.md - Bump the version with npm version (updates
package.jsonand creates Git tag) - Execute
npm publishto upload the new package version