npm - nbhi - Versions diffs - 0.5.0 - Mend

nbhi 0.5.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (7) hide show

package/LICENSE ADDED Viewed

@@ -0,0 +1,21 @@
+MIT License
+Copyright (c) 2026 Roy Niels
+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 ADDED Viewed

@@ -0,0 +1,264 @@
+# What?
+**HTML includes and reactive rendering, all without any build tools**
+d--b is a simple **4KB** library that allows you to include html files into other html files and turns them into [web components](https://developer.mozilla.org/en-US/docs/Web/API/Web_components). Lazy initialization of content (when entering the viewport) and a one line call to update/hydrate content in your html pages. No build tools required, no `package.json` needed.
+# Why?
+d--b is developed to create real-time data driven web sites. It has lower complexity than typical SPA applications but still offers more interactivy and flexibility than server side rendered web sites. _It works well with serverless application and a pub/sub data model_.
+d--b is designed to be composable with other packages to build web sites. It takes the Lego approach, you select the packages for your needs, no lock-in into a single framework with a potential steep learning curve. d--b is build on standard browser supported technologies which means that you only need to read MDN as the source of knowledge.
+d--b minimizes abstractions, just standard HTML, CSS and Javascript. Migrating from a SPA to d--b's multi page application (MPA) approach should mean you can do this one page at the time not having to migrate your whole system at once and pray that everything keeps working.
+# Benefits
+- Buildless web applications (minification is still possible of course) 👍
+- Lightweight: **~4KB** 👍
+- Benefit from standard web component encapsulation 👍
+- Lazy load page content, when about to enter the viewport 👍
+- Just standard web technologies, little abstractions 👍
+- Composable with other packages
+- Support for web component form fields out of the box 👍
+- Multi Page Application (MPA) design
+  - The standard method how the web communicates between server and client 👍
+  - Normal native routing 👍
+  - Better SEO 👍
+  - Each page loads what it needs and no more 👍
+  - Fast initial draw 👍
+# Examples
+Please look in the **examples.html** for working examples.
+# How?
+## Templates
+Templates let you build complex systems and reuse components accross multiple pages, you can define templates in separate files or use them inline as a one-of if you just need the benefits of web components.
+### External templates
+index.html
+```html
+<html>
+  <body>
+    <my-component>Overwritten text</my-component>
+    <script type="module">
+      import initialize from '/d--b.js';
+      await initialize(); // await if loading external templates
+    </script>
+  </body>
+</html>
+```
+/components/my-component.html
+```html
+<div>
+  <slot>Default text</slot>
+</div>
+<style>/* Scoped to the web component */</style>
+```
+### Internal templates
+index.html
+```html
+<html>
+  <body>
+    <template id="my-component">
+      <slot>Default</slot>
+      <style>/* Scoped to the web component */</style>
+    </template>
+    <my-component>Overwrite</my-component>
+    <script type="module">
+      import initialize from '/d--b.js';
+      initialize(); // No await needed for internal templates
+    </script>
+  </body>
+</html>
+```
+_Note: When you use an internal `<template>` you need to define an id, which will be the name of the tag._
+## Options
+```js
+/**
+ * Options for initiating an instance
+ * @param {string} [prefix=db]
+ * @param {string} [source=/components]
+ **/
+import initialize from 'd--b.js'
+initialize({
+  // Prefix to use, ie <db-input> or <db-nav>
+  prefix: 'db',
+  // Where to find external web components, if string it will be a director
+  // when using an object the key is the name (without prefix) of the component
+  // and the value the path to the web-component
+  directory: '/components',
+});
+```
+## Methods
+### .setSlot(value, [slotName], [htmlSelector])
+```js
+/**
+ * Update data in a <slot> tag
+ * @param {string} value - What you want to assign to a <slot>
+ * @param {string} [slotName] - If not given value is assigned to default <slot>
+ * @param {string} [htmlSelector] - Target a html tag in a complex <slot>
+ **/
+const element = document.querySelector('my-component');
+// To default slot
+element.setSlot('Some text');
+// To slot named title
+element.setSlot('Some text', 'title');
+// To slot named title and withing the <em> tag
+element.setSlot('Some text', 'title', 'em');
+```
+### .setChildren(data, [wrapperTag])
+```js
+/**
+ * Updates one or more records in the child template
+ * @param {object|object[]} data - The data to use
+ **/
+const element = document.querySelector('my-component');
+// Update a single child, with data-slot named "title"
+element.setChildren({ title: 'Some value' });
+```
+_Note: Child templates always need to extend an existing tag, like `<tr>`, `<option>`, `<div>`, etc. This is because some parents like `<tbody>`, `<select>` will not render regular non extended web components._
+### .onceVisible(callback)
+```js
+/**
+ * Runs one time when the web component comes into view
+ * @param {function} callback - Callback to run
+ **/
+document.querySelector('my-component').onceVisible(element => {
+  subscribeToData('someCollection', data => element.setChildren(data));
+});
+```
+### .checkValidity() (Only if the webcomponent includes a form element)
+```js
+/**
+ * Checks if the field is valid
+ * @returns boolean
+ **/
+document.querySelector('my-form-field').checkValidity();
+```
+### .validity (Only if the webcomponent includes a form element)
+```js
+/**
+ * Get the standard validity object
+ * @returns ValidityState
+ **/
+document.querySelector('my-form-field').validity;
+```
+### .validationMessage() (Only if the webcomponent includes a form element)
+```js
+/**
+ * Gets the message for an invalid field, handy for bespoke themes
+ * @returns string
+ **/
+document.querySelector('my-form-field').validationMessage();
+```
+### Attributes
+It is possible to set attributes on a web component instance tag like `<my-component>` and they will automatically be assigned to the correct nodes in the underlying `<template>`. Any changes you make to the `<my-component>` attributes will automatically update the underlying component data.
+index.html
+```html
+<my-email data-id="1" value="me@me.com" readonly>User Email</my-email>
+```
+my-component.html
+```html
+<!--
+  Custom attributes like data-id need to be defined in the template, otherwise
+  d--b does not know where to assign the value
+-->
+<label data-id="">
+  <slot></slot>
+  <!-- d--b knows to add value and read only to the input field --->
+  <input type="email" placeholder="email">
+</div>
+```
+```js
+// Calling from JS is also easier, you don't need to find the shadowRoot
+const element = document.querySelector('my-component')
+element.setAttribute('value', 'Some value');
+element.disabled = true;
+```
+_Note: If there are multiple elements that can have an attribute that has been defined on the component instance it will assign it to all instances. You can assign attributes to the `<template>` tag but only if it extends an existing tag_
+# FAQ
+### How to pronounce d--b?
+However you like.
+### No build steps is nice, but I want to use TypeScript
+If you want to use TS you have a couple of options. You can either add a build step, nothing is stopping you, the library supports it. If you want to stay buildless but want to add some sort of type checking and hinting you can consider using JSDoc, it is [supported](https://www.typescriptlang.org/docs/handbook/jsdoc-supported-types.html#author) in TS as well.
+### Creating interactivity is verbose with native js DOM manipulation
+d--b is not designed to be a single solution for everything, if you want to make DOM manipulation for interactivity easier I would suggest using dedicated libraries for that. You can consider [Alpine.js](https://alpinejs.dev/) or [Umbrella.js](https://umbrellajs.com/) for example. d--b is designed with composibility in mind so you decide what to add.
+### External npm packages require me the add build steps again
+You could load them from a CDN if you want to stay 100% buildless, otherwise you could just add a simple minifier and bundler. This will stay very lightweight but probably is more suitable for production environments.
+### Anybody using web component technology?
+Just check out the source code of github.com or youtube.com.
+### We are a team of multiple developers, using a framework ensures we write similar code
+You are correct, when you choose a more opinionated framework it will most likely give more cohesive code overall when you work with multiple developers. However it also gives you lock-in. It is a trade-off that you have to make, depending on the team size and how agile your codebase needs to remain.

package/dist/index.js ADDED Viewed

	@@ -0,0 +1,2 @@
1	+ import{getAttributeMapping as A,updateAttributes as E}from"./attributes.js";export default async({prefix:d="db",source:i="/components"}={})=>{const m=new Set,p=new Set;if(typeof i!="string"\|\|!Object.keys(i).length)throw new Error("source option needs to be a string or an object");if(typeof d!="string"\|\|d==="")throw new Error("prefix option needs to be a string of at least one character");const g=C();h(document.querySelector("body")),await y(document.querySelector("body"));function h(n,o){n.querySelectorAll("template").forEach(t=>{if(!t.id&&o&&(t.id=`${o}-child`),!t.id)throw console.log(t,o),new Error("<template> is missing a mandatory id field");h(t.content,t.id);const e=t.id;S({name:e,template:t})})}function y(n){const o=[...n.querySelectorAll(":not(:defined)")].filter(t=>{const e=t.localName;return t.nodeType===1&&e.includes("-")&&e.startsWith(d)}).map(async t=>{const e=t.localName;if(!p.has(e)){let l=function(u){const f=u.content.querySelector("script");return new Promise(async b=>{if(f){const x=new Blob([f.textContent],{type:"text/javascript"}),w=URL.createObjectURL(x);b((await import(w)).default),URL.revokeObjectURL(w)}else b({})})};p.add(e);const s=await a(e),r=document.createElement("template");r.content.append(...s.children);const c=await l(r);await y(r.content),h(r.content,e),S({name:e,template:r,script:c})}async function a(s){const r=s.split("-").slice(1).join("-"),c=typeof i=="string"?`${i}/${r}.html`:i[r],l=await fetch(c);if(!l.ok)throw new Error(`Could not find component @ ${c}`);const u=await l.text();return new DOMParser().parseFromString(u,"text/html").querySelector("body")}});return Promise.all(o)}function S({name:n,template:o,script:t}){if(m.has(n))return;m.add(n);const e=!!o.content.querySelector("input, select, textarea"),a=A(o.content);customElements.define(n,class extends HTMLElement{static observedAttributes=Object.keys(a);static formAssociated=e;#t=null;constructor(){super();const s=document.importNode(o.content,!0);this.#t=this.attachShadow({mode:"open"}),this.#t.adoptedStyleSheets=g,this.#t.appendChild(s),e&&(this.elementInternals=this.attachInternals(),this.formElement=this.#t.querySelector("input, select, textarea"))}connectedCallback(){typeof t=="function"&&t(this)}attributeChangedCallback(s,r,c){r!==c&&E({name:s,value:c,attributeMapping:a,root:this.#t})}})}function C(){return Array.from(document.styleSheets).filter(n=>n?.ownerNode?.dataset?.inherit==="true").map(n=>{const o=new CSSStyleSheet;try{const t=Array.from(n.cssRules).map(e=>e.cssText).join(`
2	+ `);o.replaceSync(t)}catch(t){console.error("Permission denied for sheet:",n.href)}return o})}};

package/dist/onceVisible.js ADDED Viewed

	@@ -0,0 +1 @@
1	+ import o from"./element.js";export default(r,t)=>{const e=new IntersectionObserver(n=>{n[0].isIntersecting&&(t(),e.disconnect())});e.observe(o(r))};

package/dist/update.js ADDED Viewed

	@@ -0,0 +1,2 @@
1	+ import{getAttributeMapping as $,updateAttributes as O}from"./attributes.js";import P from"./element.js";export default N=>{const f=P(N),d=new WeakMap,b=new WeakMap;let g=new Map,S=1,h;return l=>{if(j(l))throw new Error("Please convert date to string, ie. toISOString()");w(l)?q(l):m(l)?y(f,l):C(l)&&x(f,l);function j(t){return t?.getTime!==void 0}function m(t){return!w(t)&&!C(t)}function C(t){return!w(t)&&t!==null&&typeof t=="object"&&Object.keys(t).length}function w(t){return Array.isArray(t)}function x(t,r){Object.entries(r).forEach(([n,i])=>{if(n.startsWith("$")){const u=n.slice(1);if(t.shadowRoot)i===!1?t.removeAttribute(u):i===!0?t.setAttribute(u,""):t.setAttribute(u,i);else{b.has(t)\|\|b.set(t,$(t));const A=b.get(t);O({name:u,value:i,attributeMapping:A,root:t})}}else y(t,i,n)})}function y(t,r,n){if(t.localName==="option")t.textContent=r;else if(t.localName==="tr"\|\|t.localName==="li"\|\|t.hasAttribute("child")&&!t.shadowRoot)if(t.hasAttribute("data-slot")&&t.dataset.slot===n)t.textContent=r;else{const i=t.querySelector(`[data-slot="${n}"]`);i&&(i.textContent=r)}else if(!n&&t.textContent!==r)t.textContent=r;else{let i=t.querySelector(`[slot="${n}"]`);i\|\|(i=document.createElement("span"),i.setAttribute("slot",n),t.append(i)),i.textContent!==r&&(i.textContent=r)}}function q(t){const r=A();if(!h)throw new Error(`Cannot update ${N}, cannot find child element`);const n=new Map;t.forEach((e,a)=>{const p=u(e,a);let s=g.get(p);s\|\|(s=h.cloneNode(!0),r.append(s)),s.cachedData!==e&&(C(e)?x(s,e):y(s,e),s.cachedData=e),n.set(p,s)}),g.forEach((e,a)=>{n.has(a)\|\|e.remove()});let i;n.forEach(e=>{e!==i?.nextSibling&&r.insertBefore(e,i?i.nextSibling:r.firstChild),i=e}),g=n;function u(e,a){return e&&typeof e=="object"?(d.has(e)\|\|d.set(e,S++),d.get(e)):`p:${e}:${a}`}function A(){const e=M();if(e.localName==="table")return a("tbody","tr");if(e.localName==="ol")return a("ol","li");if(e.localName==="ul")return a("ul","li");if(e.localName==="select")return a("select","option");if(e.querySelector("[child]")){const o=s(e.querySelector("[child]")).parentElement;return p("[child]",o),o.localName==="slot"&&o.hasAttribute("name")&&(h.slot=o.getAttribute("name")),o.localName==="slot"?f:o}throw new Error(`Could not find a parent to assign children to, valid
2	+ options are table, ul, ol, select or a structure with a child attribute`);function a(o,c){const E=s(o);return p(c,E),E}function p(o,c){h\|\|(h=c.querySelector(o).cloneNode(!0),c.replaceChildren())}function s(o){const c=typeof o=="string"?e.querySelector(o):o;if(!c)throw new Error("Cannot update table, missing tbody");return c}function M(){return f.tagName.includes("-")?[...f.shadowRoot.children].find(o=>o.localName!=="script"&&o.localName!=="style"):f}}}}};

package/dist/validate.js ADDED Viewed

@@ -0,0 +1 @@

+ import o from"./element.js";export default s=>{const e=o(s);if(e.elementInternals){let r=function(){return l.tooShort?`The text needs to be at least ${a} characters long`:l.tooLong?`The text needs to be at most ${i} characters long`:t.validationMessage?t.validationMessage:"The value is invalid"};const t=e.formElement,n=t.value,a=t.getAttribute("minlength"),i=t.getAttribute("maxlength"),l={valueMissing:t.validity.valueMissing,typeMismatch:t.validity.typeMismatch,patternMismatch:t.validity.patternMismatch,rangeUnderflow:t.validity.rangeUnderflow,rangeOverflow:t.validity.rangeOverflow,stepMismatch:t.validity.stepMismatch,badInput:t.validity.badInput,customError:t.validity.customError,tooShort:a?n.length<parseInt(a):!1,tooLong:i?n.length>parseInt(i):!1};return e.elementInternals.setFormValue(n),e.elementInternals.setValidity(l,r(),t),e.elementInternals}};

package/package.json ADDED Viewed

@@ -0,0 +1,39 @@
+{
+  "name": "nbhi",
+  "version": "0.5.0",
+  "description": "No-Build HTML Includes (NBHI) is a simple library that allows you to include html files into other html files and turns them into [web components](https://developer.mozilla.org/en-US/docs/Web/API/Web_components). Lazy initialization of content (when entering the viewport) and a one line call to update/hydrate content in your html pages. No build tools required, no `package.json` needed.",
+  "keywords": [
+    "web-components",
+    "html-includes",
+    "no-build",
+    "hydration",
+    "form-validation",
+    "lazy-loading",
+    "mpa",
+    "multi-page-application",
+    "composable"
+  ],
+  "homepage": "https://github.com/royniels/d--b#readme",
+  "bugs": {
+    "url": "https://github.com/royniels/d--b/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/royniels/d--b.git"
+  },
+  "files": [
+    "./dist/**"
+  ],
+  "exports": {
+    ".": "./dist/index.js",
+    "./update.js": "./dist/update.js",
+    "./onceVisible": "./dist/onceVisible.js",
+    "./validate": "./dist/validate.js"
+  },
+  "license": "MIT",
+  "author": "Roy Niels",
+  "type": "module",
+  "scripts": {
+    "test": "echo \"Error: no test specified\" && exit 1"
+  }
+}