A lightweight, type-safe Web Component library built for the Genie ecosystem. Grimoire provides beautifully styled, customizable components with built-in dark/light theme support.
- 🎨 Theme-Aware: Built-in dark/light mode support with flexible theming options
- 🔧 Type-Safe: Full TypeScript support with comprehensive type definitions
- 🪄 Magik Integration: Built on @magik_io/mote for powerful DOM manipulation
- 📦 Tree-Shakeable: ES modules with dynamic imports for optimal bundle size
- 🎯 Standards-Based: Pure Web Components using Custom Elements API
- 💅 CSS Variables: Fully customizable via CSS custom properties
# Using pnpm (recommended)
pnpm add @magik_io/grimoire
# Using npm
npm install @magik_io/grimoire
# Using yarn
yarn add @magik_io/grimoire- Node.js 22.x or higher
- pnpm 9.x or higher (for development)
<!DOCTYPE html><htmllang="en"><head><metacharset="UTF-8"><title>Grimoire Demo</title></head><body><!-- Use components in your HTML --><slide-togglelabel="Enable notifications" checked="true"></slide-toggle><e-sig>John Doe</e-sig><scripttype="module">import{Grimoire}from'@magik_io/grimoire';// Define which components you want to useawaitGrimoire.Define('slide-toggle','e-sig');</script></body></html>A beautiful, animated toggle switch component.
<slide-togglelabel="Dark Mode"
checked="false"
name="darkModeToggle"></slide-toggle>Attributes:
label(string): The label text displayed next to the togglechecked(boolean): Initial checked state (default:false)name(string): Name attribute for the input element
Properties:
activated: Get/set the toggle state programmatically
Events:
change: Fired when the toggle state changesdetail.checked: Current checked state
CSS Variables:
--st-body-bg: Background color
--st-checked-bg: Background color when checked
--st-border-width: Border width
--st-border-color: Border color
--st-color: Text color
--st-check-bg: Checkbox background
--st-check-bg-image: Checkbox background imageExample:
consttoggle=document.querySelector('slide-toggle');// Listen for changestoggle.addEventListener('change',(e)=>{console.log('Toggle is now:',e.detail.checked);});// Programmatically controltoggle.activated=true;An elegant electronic signature component with multiple font choices.
<e-sigfont="dancing-script" icon="fas fa-pen">
Antonio Bourassa
</e-sig>Attributes:
font(string): Font style for the signaturedancing-script(default)great-vibeshomemade-applemarck-scriptsacramentosatisfy
icon(string): Font Awesome icon class (default:fas fa-cog)
CSS Variables:
--eSig-bg: Background color
--eSig-border-color: Border color
--eSig-border-style: Border style
--eSig-border-radius: Border radius
--eSig-border-width: Border width
--eSig-line-height: Line height
--eSig-padding: Padding
--eSig-margin-bottom: Bottom margin
--eSig-color: Text colorFeatures:
- Click the icon to open a font selection modal
- Interactive font preview
- Responsive scaling
Note: You'll need to include Google Fonts in your HTML:
<linkhref="https://fonts.googleapis.com/css?family=Dancing+Script|Great+Vibes|Homemade+Apple|Marck+Script|Sacramento|Satisfy" rel="stylesheet">Grimoire provides flexible theming options:
Uses CSS media queries to detect system preferences:
Grimoire.Configure({chroma: 'browser'});Uses body classes (.dark and .light):
Grimoire.Configure({chroma: 'class'});Define your own theme classes:
Grimoire.Configure({chroma: {dark: 'my-dark-theme',light: 'my-light-theme'}});Disable theme switching:
Grimoire.Configure({chroma: false});Only load the components you need to keep your bundle small:
// Load only SlideToggleawaitGrimoire.Define('slide-toggle');// Load multiple componentsawaitGrimoire.Define('slide-toggle','e-sig');Override CSS variables globally or per-component:
/* Global overrides */:root {
--st-checked-bg:#ff6b6b;
--eSig-bg:#f0f0f0;
}
/* Dark mode overrides */@media (prefers-color-scheme: dark) {
:root {
--st-checked-bg:#ff4757;
--eSig-bg:#2c2c2c;
}
}
/* Component-specific overrides */slide-toggle {
--st-checked-bg: green;
}Full type definitions are included:
import{Grimoire,typeGrimoireTemplateNames}from'@magik_io/grimoire';constcomponents: GrimoireTemplateNames[]=['slide-toggle','e-sig'];awaitGrimoire.Define(...components);// Type-safe component referencesconsttoggle=document.querySelector('slide-toggle')asHTMLElement&{activated: boolean;};Grimoire uses a sophisticated component registration system:
- Dynamic Imports: Components are loaded on-demand
- Style Extraction: CSS is automatically extracted and injected
- Theme Management: Automatic light/dark theme handling
- Custom Elements: Standards-based Web Components
Each component uses a ComponentDescriptor that defines:
- Component name and HTML tag
- Element class (extends
HTMLElement) - Style configuration (base styles, CSS variables, theme variants)
- Type of custom element
exportdefaultnewComponentDescriptor({name: 'my-component',element: MyComponent,type: 'custom-element',style: {base: CSSVars=>CSSVars`/* CSS */`,vars: {/* CSS variables */},theme: {light: {/* light theme vars */},dark: {/* dark theme vars */}}}});# Clone the repository
git clone https://github.com/MagikIO/grimoire.git
cd grimoire
# Install dependencies
pnpm install
# Start development server
pnpm dev# Build for production
pnpm build# Bump version, push tags, and publish
pnpm iterateGrimoire supports all modern browsers that implement:
- Custom Elements v1
- ES2022
- CSS Custom Properties
- ES Modules
Tested on:
- Chrome/Edge 90+
- Firefox 88+
- Safari 14+
- @magik_io/mote - Lightweight DOM manipulation library
- ulid - Universally Unique Lexicographically Sortable Identifiers
Contributions are welcome! Please read our Contributing Guide for details on our code of conduct and the process for submitting pull requests.
MIT © Antonio B.
See CHANGELOG.md for a list of changes.
- 🐛 Report a bug
- 💡 Request a feature
- 📧 Contact: Abourassa@AssetVal.com
- @magik_io/mote - DOM manipulation library
- @magik_io/lint_golem - ESLint configuration
Made with ✨ by MagikIO