@skirbi/dibuho
v0.0.3
Published
Skirbi's component library
Readme
@skirbi/dibuho
Dibuho provides higher-level composition patterns for Skirbi.
Where the other packages have narrower jobs:
@skirbi/sugarprovides Web Component primitives@skirbi/semticprovides semantic HTML components@skirbi/pintaprovides tokens, derivations, and component recipes@skirbi/dibuhoprovides page/component composition patterns
Dibuho is intentionally small. It is not a UI kit and it is not a layout framework. It collects the few reusable patterns that are too specific for Semtic and too structural for Pinta.
Installation
npm install @skirbi/dibuhoRegister components
Register selectively:
import { DibuhoContainerPanel } from '@skirbi/dibuho';
DibuhoContainerPanel.register();Dibuho components stay in the light DOM and build on Semtic components.
CSS
Dibuho ships CSS composition hooks:
@import '@skirbi/dibuho/dibuho.css';
/* optional, but recommended */
@import '@skirbi/pinta/pinta.css';The CSS is gated behind [skirbi-theme], just like Pinta:
<html skirbi-theme>
...
</html>Components
<dibuho-container-panel>
A small composition component for wrapping arbitrary content in a Semtic panel with an optional header.
<dibuho-container-panel title="Payment details">
<p>Use this area for the panel body.</p>
</dibuho-container-panel>Renders roughly as:
<dibuho-container-panel title="Payment details">
<semtic-panel type="card" dibuho-container-panel>
<semtic-stack dibuho-container-panel-stack>
<semtic-header title="Payment details" dibuho-container-panel-header></semtic-header>
<semtic-stack dibuho-container-panel-body>
<p>Use this area for the panel body.</p>
</semtic-stack>
</semtic-stack>
</semtic-panel>
</dibuho-container-panel>Without title, the generated header is removed.
Composition hooks
Dibuho CSS also defines a few attribute hooks for common application patterns. These are plain CSS contracts; they do not require JavaScript.
Info rows
<semtic-flex dibuho-info-grid>
<span>Division A</span>
<span>12 participants</span>
</semtic-flex>Choice grid
<semtic-grid dibuho-choice-grid>
<semtic-choice-card>...</semtic-choice-card>
<semtic-choice-card>...</semtic-choice-card>
</semtic-grid>Filters
<semtic-flex dibuho-filters>
<semtic-toggle type="pill" label="Open"></semtic-toggle>
<semtic-toggle type="pill" label="Closed"></semtic-toggle>
</semtic-flex>Filter grid
<semtic-grid dibuho-filter-grid>
<semtic-toggle label="Has goodie bag"></semtic-toggle>
<semtic-toggle label="Accredited"></semtic-toggle>
</semtic-grid>Sticky actions
<semtic-actions dibuho-sticky-actions>
<button type="submit" lead>Save</button>
</semtic-actions>Error badge
<span dibuho-error-badge>Missing payment</span>Custom templates
dibuho-container-panel supports a custom HTML template with the id
dibuho-container-panel-template.
The template must contain an element with dibuho-container-panel-body. The
header element is optional, but if present it can use
dibuho-container-panel-header.
<template id="dibuho-container-panel-template">
<semtic-panel type="card" dibuho-container-panel>
<semtic-header dibuho-container-panel-header></semtic-header>
<semtic-stack dibuho-container-panel-body></semtic-stack>
</semtic-panel>
</template>Register after the template exists in the document.
Philosophy
Dibuho follows the Skirbi 80% rule:
- keep patterns small
- prefer semantic markup
- use normal CSS for application-specific layout
- move reusable primitives down into Sugar or Semtic when they belong there
- avoid turning composition helpers into a utility framework
Development
Build documentation:
npm run jsdocRun tests:
npm testCode of Conduct
Be human.
Versioning
This project does not follow semver. It follows a Perl-style release philosophy centered on backward compatibility. This translates to the following hard guarantee: We do not intentionally break working code. If a release causes breakage, it will be addressed accordingly.
The x.y.z version number should not be used to infer stability. Consult the
Changes file for important updates, deprecations, and breaking changes.
The current 0.x.z range does not imply alpha, beta, or instability. It is
simply the starting point of the project.
In case we foresee breaking changes, we will add deprecation warnings and give you time to fix things before the breaking change is introduced. Security fixes may cause breakage at any given time without notice.
This package is released by @opndev/rzilla; changes to package.json will be
overridden. Version numbers are autoincremented at release time and bumped in
all relevant files: versioning for humans, not machines.
