Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/puzzle/puzzle-shell
The standard design for Puzzle tools
https://github.com/puzzle/puzzle-shell
design-system lit storybook webcomponents
Last synced: 2 months ago
JSON representation
The standard design for Puzzle tools
- Host: GitHub
- URL: https://github.com/puzzle/puzzle-shell
- Owner: puzzle
- License: apache-2.0
- Created: 2021-03-29T09:24:11.000Z (almost 4 years ago)
- Default Branch: main
- Last Pushed: 2024-11-11T10:18:00.000Z (2 months ago)
- Last Synced: 2024-11-11T10:25:34.690Z (2 months ago)
- Topics: design-system, lit, storybook, webcomponents
- Language: TypeScript
- Homepage: https://puzzle.github.io/puzzle-shell
- Size: 15.1 MB
- Stars: 7
- Watchers: 7
- Forks: 2
- Open Issues: 5
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
README
# Puzzle Shell
[](https://github.com/puzzle/puzzle-shell/actions/workflows/lint.yml)
[](https://github.com/puzzle/puzzle-shell/actions/workflows/storybook.yml)
[](https://github.com/puzzle/puzzle-shell/actions/workflows/bom.yml)
The standard design for Puzzle tools as a set of [Web Components](https://en.wikipedia.org/wiki/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](https://puzzle.github.io/puzzle-shell) that lists and documents all Puzzle Shell components and contains usage examples.
Check out the [changelog](./CHANGELOG.md) for the latest changes.
## Usage
### JavaScript Modules (ESM)
You can install this package with NPM:
```bash
npm i @puzzleitc/puzzle-shell
```
Or Yarn:
```bash
yarn add @puzzleitc/puzzle-shell
```
Or PNPM:
```bash
pnpm add @puzzleitc/puzzle-shell
```
Then, with a bundler like [Vite](https://vitejs.dev/), you can import the package in your main JavaScript file to include all components:
```javascript
import "@puzzleitc/puzzle-shell";
import "@puzzleitc/puzzle-shell/style.css";
```
Or you can import specific components:
```javascript
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:
```html
```
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](https://duckduckgo.com/?q=npm+cdn&ia=web) (or self-serve it) and include it as follows:
```html
```
## Linting etc.
To scan the project for linting or type errors, run:
```bash
npm run lint
```
To automatically fix many linting errors & reformat code using Prettier, run:
```bash
npm run lint:fix
```
To automatically generate the `custom-elements.json` manifest using the [web-component-analyzer](https://github.com/runem/web-component-analyzer), run:
```bash
npm run manifest
```
## Tryout Components with Storybook
To run a local instance of Storybook, run:
```bash
npm run storybook
```
To build a production version of Storybook, run:
```bash
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.:
```html
window.pzshBreakpoint = 1024;
```
## 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](https://docs.npmjs.com/cli/v7/commands/npm-version) (updates `package.json` and creates Git tag)
- Execute `npm publish` to upload the new package version