@programmerg/bs-elements 0.1.0

package/LICENSE.md

@@ -0,0 +1,9 @@
+MIT License
+
+Copyright (c) 2026 Gelencsér Gergő
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -0,0 +1,148 @@
+<p align="center">
+  <img src="logo.svg" alt="bs-elements" width="128" height="128">
+</p>
+
+# bs-elements
+
+A **Bootstrap 5–based, framework-agnostic Web Component library** built around the Bootstrap philosophy: 
+_class-first markup, minimal abstraction, and a thin DOM wrapper_.
+
+bs-elements augments existing Bootstrap HTML and JavaScript with a **declarative Custom Element API** 
+— without hiding, replacing, or reinventing Bootstrap.
+
+## 🎯 Goals
+
+- Expose Bootstrap 5 components as **Custom Elements**
+- Work everywhere: **Vanilla JS, React, Vue, Svelte**
+- Preserve **full Bootstrap compatibility** (HTML, JS API, events)
+- Reduce boilerplate while adding behavior
+
+Explicitly not a goal:
+
+- Inventing a new design system
+- Replacing Bootstrap CSS
+- Shadow DOM isolation
+
+## 🚀 Getting started
+
+Good old way
+
+1. Follow the [official guide](https://getbootstrap.com/docs/5.3/getting-started/introduction/)
+2. replace `bootstrap.boundle.min.js` with `bs-elements.boundle.min.js`
+3. or add the `<script src="bs-elements.min.js"></script>` next to it
+
+ES Modules
+
+- Use the `<script src="bs-elements.esm.js" type="module"></script>`
+- or install it with the command: `npm i programmerg/bs-elements`
+- then you can import it as `import * from 'bs-elements'`
+
+## 🧠 Design Principles
+
+### Bootstrap-first
+
+- Bootstrap documentation is the **single source of truth**
+- DOM structure follows Bootstrap, not the component
+- Classes are primary; properties are secondary
+- The original Bootstrap JS API must continue to work unchanged
+
+### Thin DOM wrapper
+
+- No custom markup generation
+- The Custom Element **is the root element**, not an extra wrapper
+- Components enhance existing DOM with behavior
+- Child markup may be intelligently assisted when missing
+
+### Light DOM only
+
+- No Shadow DOM
+- Bootstrap CSS, utilities, and overrides work exactly as expected
+
+### Attribute → state → option mapping
+
+- Attributes initialize internal state
+- Attribute changes update state
+- The imperative JS API is optional and secondary
+- State changes re-initialize the underlying Bootstrap instance
+
+```html
+<bs-modal class="modal" data-bs-backdrop="static" open></bs-modal>
+```
+
+### Event compatibility
+
+Event names are identical to Bootstrap events
+
+`show.bs.modal`, `shown.bs.modal`, ...
+
+### Idempotent DOM manipulation
+
+- Synchronization is repeatable and safe
+- No duplicated nodes
+- No destructive re-rendering
+- The same HTML remains stable across updates
+
+## 🛠️ Technical Decisions
+
+### Custom Elements
+
+- Not exposed as part of the public API surface
+- Chosen for:
+  - reactive attribute handling
+  - lifecycle hooks
+  - reduced boilerplate
+
+### Bootstrap
+
+- Bootstrap 5 CSS is an external dependency
+- Bootstrap 5 JS is an internal dependency, 
+ 
+We wrap it — we do not reimplement it!
+
+## 📦 Component Categories
+
+### Base components
+
+_Wrappers around native Bootstrap JS behavior:_
+
+`bs-alert`, `bs-button`, `bs-carousel`, `bs-collapse`, `bs-dropdown`, `bs-modal`, `bs-offcanvas`, `bs-popover`, `bs-tab`, `bs-toast`, `bs-tooltip`
+
+Responsibilities:
+
+- Attribute → option mapping
+- Lifecycle synchronization
+- Event forwarding
+
+### Extra components
+
+_Components not provided by Bootstrap itself._
+
+Responsibilities:
+
+- Encapsulate higher-level or domain-specific behavior
+
+## 🔁 Content Routing
+
+- Components do not render templates
+- All children stay in the light DOM
+- The component may:
+  - recognize child roles
+  - add required classes
+  - move nodes when structurally necessary
+
+**Auto boilerplate generation**
+
+If required Bootstrap structure is missing, BsElements fills the gap.
+
+```html
+<bs-modal>
+  <div class="modal-header">Title</div>
+  <p>This will automatically become the modal-body</p>
+</bs-modal>
+```
+
+## 📡 Lifecycle
+
+- `connectedCallback` → initialize Bootstrap instance
+- Attribute changes → synchronize options
+- `disconnectedCallback` → clean up