Skip to content

Latest commit

 

History

History
150 lines (105 loc) · 4.11 KB

README.md

File metadata and controls

150 lines (105 loc) · 4.11 KB
Raw

Puzzle Shell

Linting Storybook Build Software bill of materials (BOM)

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.

Check out the changelog for the latest changes.

Usage

JavaScript Modules (ESM)

You can install this package with NPM:

npm i @puzzleitc/puzzle-shell

Or Yarn:

yarn add @puzzleitc/puzzle-shell

Or PNPM:

pnpm add @puzzleitc/puzzle-shell

Then, 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 once

Either 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.

Bundled Version

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>

Linting etc.

To scan the project for linting or type errors, run:

npm run lint

To automatically fix many linting errors & reformat code using Prettier, run:

npm run lint:fix

To automatically generate the custom-elements.json manifest using the web-component-analyzer, run:

npm run manifest

Tryout Components with Storybook

To run a local instance of Storybook, run:

npm run storybook

To build a production version of Storybook, run:

npm run build-storybook

Customizing

Mobile/Desktop Breakpoint

The 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>

Publishing

To publish a new package version, do the following:

  • Build the library with npm run build
  • Execute npm run manifest to make sure the custom-elements.json manifest is up-to-date
  • Update the CHANGELOG.md
  • Bump the version with npm version (updates package.json and creates Git tag)
  • Execute npm publish to upload the new package version