@saasira/holi 0.1.4 → 0.1.6

package/CHANGELOG.md

@@ -2,6 +2,24 @@
 
 All notable changes to this project are documented in this file.
 
+## [0.1.5] - 2026-03-19
+
+### Added
+
+- Added runtime page-layout composition with configurable layout resolution, named `block` and `region` slot mapping, and optional inherited slot fallbacks.
+- Added layout-owned asset placement through `layout-head` for real head nodes and `tail` for deferred body-end assets.
+- Added in-memory template and layout registries backed by bundled `dist/components.html` and `dist/layouts.html`.
+
+### Changed
+
+- Stopped injecting bundled component templates into the live page body; templates now stay in an internal registry.
+- Renamed the primary bundled component-template artifact from `holi.html` to `components.html` while keeping `holi.html` as a compatibility bundle.
+- Extended the example/build pipeline and smoke checks to cover runtime layout composition and layout asset containers.
+
+### Validation
+
+- Verified with `npm run build`, `npm run smoke:examples`, and `npm pack --dry-run`.
+
 ## [0.1.4] - 2026-03-19
 
 ### Changed

package/README.md

@@ -26,7 +26,7 @@ Canonical reference: `docs/holi-principles.md`.
   - Tag: `<tabs></tabs>`
   - Attribute: `<section component="tabs"></section>`
   - Role: `<section role="tabs"></section>`
-- Template library bundling (`dist/holi.html`) and runtime template injection.
+- Component-template bundling (`dist/components.html`) and runtime in-memory template registration.
 - Template bindings:
   - `@{expression}` interpolation
   - `data-if`, `data-show`, `data-open`, `visible`
@@ -73,27 +73,48 @@ Main artifacts:
 
 - `dist/holi.js`
 - `dist/holi.css`
-- `dist/holi.html` (templates)
+- `dist/components.html` (component templates)
+- `dist/layouts.html` (layout templates)
+- `dist/holi.html` (legacy compatibility bundle)
+- `dist/layouts/**` (optional runtime-resolved layouts)
 - Example site output: `public/examples/**`
 
+## CDN Quick Start
+
+For application pages that consume Holi directly from a CDN, use the published npm package via jsDelivr:
+
+```html
+<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@saasira/holi@0.1.5/dist/holi.css" />
+<script src="https://cdn.jsdelivr.net/npm/@saasira/holi@0.1.5/dist/holi.js"></script>
+<link rel="preload" as="fetch" href="https://cdn.jsdelivr.net/npm/@saasira/holi@0.1.5/dist/components.html" crossorigin="anonymous" />
+```
+
+Direct file URLs:
+
+- `https://cdn.jsdelivr.net/npm/@saasira/holi@0.1.5/dist/holi.js`
+- `https://cdn.jsdelivr.net/npm/@saasira/holi@0.1.5/dist/holi.css`
+- `https://cdn.jsdelivr.net/npm/@saasira/holi@0.1.5/dist/components.html`
+
+Pin an exact version in production so releases remain repeatable.
+
 ## CDN Usage
 
 Holi can be shipped directly from a free CDN after publishing the package to npm.
 
-Recommended jsDelivr links for `v0.1.4`:
+Recommended jsDelivr links for `v0.1.5`:
 
 ```html
-<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@saasira/holi@0.1.4/dist/holi.css" />
-<script src="https://cdn.jsdelivr.net/npm/@saasira/holi@0.1.4/dist/holi.js"></script>
-<link rel="preload" as="fetch" href="https://cdn.jsdelivr.net/npm/@saasira/holi@0.1.4/dist/holi.html" crossorigin="anonymous" />
+<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@saasira/holi@0.1.5/dist/holi.css" />
+<script src="https://cdn.jsdelivr.net/npm/@saasira/holi@0.1.5/dist/holi.js"></script>
+<link rel="preload" as="fetch" href="https://cdn.jsdelivr.net/npm/@saasira/holi@0.1.5/dist/components.html" crossorigin="anonymous" />
 ```
 
 Fallback unpkg links:
 
 ```html
-<link rel="stylesheet" href="https://unpkg.com/@saasira/holi@0.1.4/dist/holi.css" />
-<script src="https://unpkg.com/@saasira/holi@0.1.4/dist/holi.js"></script>
-<link rel="preload" as="fetch" href="https://unpkg.com/@saasira/holi@0.1.4/dist/holi.html" crossorigin="anonymous" />
+<link rel="stylesheet" href="https://unpkg.com/@saasira/holi@0.1.5/dist/holi.css" />
+<script src="https://unpkg.com/@saasira/holi@0.1.5/dist/holi.js"></script>
+<link rel="preload" as="fetch" href="https://unpkg.com/@saasira/holi@0.1.5/dist/components.html" crossorigin="anonymous" />
 ```
 
 Repository setup details for automated npm publishing are documented in `docs/CDN.md`.
@@ -134,12 +155,92 @@ Repository setup details for automated npm publishing are documented in `docs/CD
 - Component styles: `src/styles/components/<componentname>.css`
 - Component templates: `src/templates/components/<componentname>.html`
 - Shared utilities: `src/scripts/utils/<utilityname>.js`
+- Optional layout templates:
+  - library layouts: `src/templates/layouts/*.html`
+  - example/app layouts in examples: `src/examples/layouts/*.html`
 - Example sources:
   - `src/examples/pages/*.html`
   - `src/examples/styles/*.css`
   - `src/examples/scripts/*.js`
 - Built examples: `public/examples/**` (referencing `dist/holi.js` and `dist/holi.css`)
 
+## Page Layout Composition
+
+Holi supports runtime page composition with a layout template plus named placeholders.
+
+Supported structure:
+
+```html
+<page layout="3x9" layouts-base="/examples/layouts/">
+  <block name="head">
+    <region name="meta">
+      <meta name="page-layout-demo" content="true" />
+    </region>
+    <region name="styles">
+      <style>.page-title { letter-spacing: 0.02em; }</style>
+    </region>
+    <region name="scripts">
+      <script>window.pageLayoutExampleLoaded = true;</script>
+    </region>
+  </block>
+
+  <block name="header">
+    <h1 class="page-title">Project Dashboard</h1>
+  </block>
+
+  <block name="main">
+    <region name="lhs"><div>Navigation</div></region>
+    <region name="middle"><div>Primary content</div></region>
+    <region name="rhs"><div>Context tools</div></region>
+  </block>
+</page>
+```
+
+Layout template example:
+
+```html
+<template id="page-layout-3x9" data-layout="3x9">
+  <layout-head data-layout-head="true">
+    <meta name="example-layout" content="3x9" />
+    <slot name="meta"></slot>
+    <slot name="styles"></slot>
+    <slot name="scripts"></slot>
+  </layout-head>
+
+  <header><slot name="header"></slot></header>
+  <slot name="main">
+    <main>
+      <aside><slot name="lhs"></slot></aside>
+      <section><slot name="middle"></slot></section>
+      <aside><slot name="rhs"></slot></aside>
+    </main>
+  </slot>
+</template>
+```
+
+Rules:
+
+- Top-level `block[name]` fills a matching layout slot.
+- Direct `region[name]` inside a block fills matching nested slots inside that block's assigned subtree.
+- Missing slots are empty by default.
+- Set `inherit-missing="true"` on `page` to keep fallback slot content.
+- Use `renderer="browser"` on source pages to show the built-in placeholder until runtime composition completes.
+- After browser or compiler rendering completes, both `renderer` and `rendered` should be removed from the final page node.
+- Use `layout-src` for an explicit layout file or `layouts-base` for a layout folder.
+- Page-level attributes `title`, `description`, `canonical`, and `lang` are applied to the real document metadata.
+- Page-level `theme` is applied to the real `<body>` element for theme scoping and switching.
+- Use `<layout-head data-layout-head="true">` for shared head assets in layouts.
+- Use `<tail data-layout-tail="true">` for deferred body-end assets in layouts.
+- Non-script nodes from `layout-head` go to the real HTML `<head>`.
+- Nodes from `tail` are appended near the end of `<body>`.
+- Built-in region `meta` always targets the real HTML `<head>`.
+- Built-in regions `styles` and `page-styles` always target the real HTML `<head>`, even when the layout does not declare those slots.
+- Built-in regions `scripts` and `page-scripts` always target the end of `<body>`, even when the layout does not declare those slots.
+- Use `styles` for external asset nodes such as `<link rel="stylesheet" href="...">`.
+- Use `scripts` for external asset nodes such as `<script src="..."></script>`.
+- Use `page-styles` for inline `<style>` tags.
+- Use `page-scripts` for inline `<script>` tags.
+
 ## Holi vs React / Angular / Vue
 
 | Area | Holi | React | Angular | Vue |
@@ -170,4 +271,38 @@ Practical summary:
 
 - Holi exports `window.HoliApp` / `window.Holi`.
 - Auto init can be disabled with `window.HoliAutoInit = false` before loading `dist/holi.js`.
-- Templates are loaded from `dist/holi.html` (with runtime fallback paths).
+- Component templates are loaded from `dist/components.html` (with runtime fallback paths).
+- Layout templates are loaded from `dist/layouts.html` (with runtime fallback paths).
+
+## OfflineIndicator
+
+`OfflineIndicator` provides a template-driven connectivity banner with automatic polling and queue count display.
+
+Supported declaration styles:
+
+- `<offline></offline>`
+- `<section component="offline"></section>`
+- `<section role="offline"></section>`
+- `[data-offline]`
+
+Useful attributes:
+
+- `scope="page|block|inline"`
+- `position="top-left|top-right|bottom-left|bottom-right|top-center|bottom-center"`
+- `host="#selector"` for `scope="block"`
+- `ping-url="/api/ping"`
+- `heartbeat-ms="2500"`
+- `probe-timeout-ms="1800"`
+- `duration="1200"`
+- `max-attempts="4"`
+
+Instance/static helpers:
+
+- `el.offlineIndicator.retryConnection()`
+- `el.offlineIndicator.simulateOffline()`
+- `el.offlineIndicator.simulateOnline()`
+- `window.OfflineIndicator.queue(payload)`
+- `window.OfflineIndicator.clearQueue()`
+- `window.OfflineIndicator.create(options)`
+
+See [offline example](/D:/Work/Self/Holi/src/examples/pages/offline.html) for page-scoped, block-scoped, and queue-sync scenarios.