@trunkjs/content-pane 1.0.1 → 1.0.2

package/CHANGELOG.md

@@ -1,3 +1,7 @@
+## 1.0.2 (2025-08-13)
+
+This was a version bump only for content-pane to align it with other projects, there were no code changes.
+
 ## 1.0.1 (2025-08-11)
 
 This was a version bump only for content-pane to align it with other projects, there were no code changes.

package/README.md

@@ -1,215 +1,83 @@
-# content-pane
+# tj-content-pane
 
-This library was generated with [Nx](https://nx.dev).
+Transforms plain html to a tree structure of sections, articles, and other elements. js-content-pane is a pure
+Client-Side Rendering (CSR) solution. It is designed to style the unstyled output of static site generators (SSG) like
+Jekyll, Hugo, or others. These provide SEO-friendly HTML output, but the structure is often not ideal for styling.
 
-A lightweight toolkit for turning a flat block of HTML content into a, styled “content pane.” It provides:
+![Demo Markdown](docs/tj-content-pane-title1.png)
 
-- A Web Component (<content-area2>) that automatically:
-  - Builds a nested section structure from your headings and horizontal rules.
-  - Applies layout transformations based on a compact layout attribute syntax.
-- A small set of utilities you can call programmatically:
-  - SectionTreeBuilder: wraps related content into nested <section> containers.
-  - applyLayout: transforms elements based on a layout string (tag#id.class1.class2).
-  - attrAssign: helper to assign attributes to selected children.
+Most Static Site Generators (SSG) support Kramdown, where you can assign attributes to elements in the markdown source by
+using the `{: layout="selector" slot="slotname"}` syntax.
 
-Status: experimental / evolving API.
+## Basic Usage
 
-## Why use content-pane?
+Wrap the area that should be transformed with the Custom Element:
 
-If you have document-like content (headings, paragraphs, images, etc.) and want:
-- Automatic, semantic grouping of content into sections
-- Declarative, inline layout instructions per element
-- A no-shadow-DOM approach that keeps your stylesheets simple
+```html
+<tj-content-pane>
+    <h1>Header 1</h1>
+    <p>This is content below the header element.</p>
+</tj-content-pane>
+```
 
-…content-pane is for you.
+Normally this will happen in the template of a static site generator, like this:
 
-## Packages and exports
+```html
+<tj-content-pane> {{content}} </tj-content-pane>
+```
 
-Install or import from:
-- @trunkjs/content-pane
+## Layouts
 
-Exports:
-- Web Component: registered as custom element content-area2
-- Functions:
-  - applyLayout(elementOrElements, { recursive = true })
-  - attrAssign(element, multiQuerySelector, attributes)
-  - SectionTreeBuilder class
+The Attribute `layout` can be used to specify a layout for the element. Use the css selector syntax to specify
+tag, id or classes.
 
-Import examples:
-- Register the custom element (side-effect import): import '@trunkjs/content-pane'
-- Use utilities: import { applyLayout, attrAssign } from '@trunkjs/content-pane'
+```markdown
+## Header 2
+{: layout="#id1.class1"}
 
-## The <content-area2> Web Component
+This is content below the section element.
+```
 
-The component is defined without Shadow DOM (createRenderRoot returns this), so your global CSS can style the generated structure directly.
+Will be transformed to:
 
-What it does on connect:
-1. Waits for DOMContentLoaded
-2. Builds a section tree from its direct children using SectionTreeBuilder
-3. Applies layout transformations to itself and its descendants using applyLayout
+```html
+<section class="class1" id="id1">
+    <h2>Header 2</h2>
+    <p>This is content below the section element.</p>
+</section>
+```
 
-Tag name: content-area2
+### Subelements
 
-Note: The internal class is ContentAreaElement2. The static is getter returns 'tj-content-area' but the actual registered tag is content-area2.
+The strcutrure of the content is defined by the h2-h6 elements.
 
-### Quick start (browser)
+```markdown
+## Header 2
 
-- Include content-area2 on your page
-- Ensure the module is imported so the element is defined
-- Add headings and content as children
+text
 
-Example:
-<!-- somewhere in your app bootstrap -->
-<script type="module">
-  import '@trunkjs/content-pane'; // registers <content-area2>
-</script>
+### Header 3
 
-<content-area2>
-  <h2 layout="2">Introduction</h2>
-  <p>This is the intro paragraph.</p>
+text
 
-  <h3>Details</h3>
-  <p>Some detailed text.</p>
+### Header 3
 
-  <hr> <!-- becomes a mid-level divider -->
-  <h2 layout="+2">More</h2>
-  <p>Additional information appended at the same level as previous H2.</p>
+text
+```
 
-  <!-- An element with layout that transforms into an <aside> -->
-  <div layout="2.5;aside#toc.toc right">
-    <p>Table of contents here…</p>
-  </div>
-</content-area2>
+will transform to: (By default, the h2 elements are transformed to section elements, and h3-h6 elements to divs)
 
-## The SectionTreeBuilder
-
-SectionTreeBuilder rearranges a flat list of nodes into nested <section> elements based on:
-- Heading levels (H1–H6) mapped to a 10s scale (H2 → 20, H3 → 30, …). H1 is treated as H2.
-- Horizontal rules (HR) which become implicit dividers at lastFixedI + 5.
-- Optional layout prefix directives on elements to influence grouping.
-
-It processes only element nodes (other node types are appended as-is) and respects a small “index” (i) model for nesting.
-
-### Layout prefix for sectioning
-
-If a node has a layout attribute, the prefix can shape the sectioning behavior:
-
-Pattern: ^(\+|-|)([0-9]?\.?[0-9]?|)(;|$)
-
-- Variant:
-  - + → append: place the node inside the existing container at the computed level
-  - - → skip: do not start a new section for this node; it’s appended to the current container
-  - (none) → new: create a new section container at this level
-- Level number:
-  - Optional number (e.g., 2, 2.5) scaled to 10s internally (2 → 20). If absent, heading tags provide the default.
-  - Decimals allow interleaving content between heading levels (e.g., 2.5 sits between H2 (20) and H3 (30)).
-
-When creating a new <section>, SectionTreeBuilder:
-- Moves attributes beginning with layout from the original node onto the new section and removes them from the original.
-- Copies attributes starting with section- and converts section-* class names to classes on the section wrapper (prefix removed).
-- For HR elements, copies all attributes to the section wrapper.
-
-Note: The attribute handling is intentionally conservative to avoid disrupting your original elements more than necessary.
-
-### Programmatic usage
-
-import { SectionTreeBuilder } from '@trunkjs/content-pane';
-
-const container = document.querySelector('#my-content') as HTMLElement;
-const stb = new SectionTreeBuilder(container);
-stb.arrange(Array.from(container.children));
-
-This will restructure the container’s children into nested <section> elements.
-
-## applyLayout
-
-applyLayout transforms elements based on a compact layout attribute:
-- Syntax: [prefix][;]selector
-  - Prefix: the same prefix as used by SectionTreeBuilder, typically used for sectioning (see above). applyLayout strips this prefix before applying the selector.
-  - Selector: a simplified CSS-like “element definition” of the form tag#id.class1.class2. If tag is omitted, defaults to div.
-
-Behavior:
-- For each element with a layout attribute, applyLayout:
-  - Parses the layout string, ignoring any leading sectioning prefix
-  - Creates a replacement element using the parsed tag, id, and classes
-  - Moves the original element’s children into the replacement element
-  - Replaces the original element in the DOM
-- If the selector’s tag is a custom element name (contains -) and that element is not registered, applyLayout replaces it with an error element (TjErrorElement) to prevent infinite recursion and to make the issue visible in the DOM.
-
-Options:
-- recursive (default: true): apply the transformation to descendants as well.
-
-Return value:
-- An array of HTMLElements that were processed or produced by replacements.
-
-Example:
-import { applyLayout } from '@trunkjs/content-pane';
-
-const el = document.querySelector('#article')!;
-applyLayout(el, { recursive: true });
-
-<!-- Before -->
-<div id="sidebar" layout="2;aside#right.aside-panel">
-  <p>Sidebar content</p>
-</div>
-
-<!-- After (conceptually) -->
-<aside id="right" class="aside-panel" layout="2;aside#right.aside-panel">
-  <p>Sidebar content</p>
-</aside>
-
-Note: applyLayout preserves the original layout attribute on the replacement element so you can re-run the layout step if needed or inspect the intent.
-
-### Manual before-layout hook
-
-If a custom element used as a replacement implements a beforeLayoutCallback(origElement, instance, children) method, it will be called before children are attached and layout is applied to descendants. Returning false from this method will skip recursive layout for that element, allowing it to manage its own internal layout.
-
-Type signature:
-interface ManualBeforeLayoutElement {
-  beforeLayoutCallback(origElement: HTMLElement, instance: this, children: Element[]): void | boolean;
-}
-
-## attrAssign
-
-Utility to assign attributes to multiple selected descendants using a simple multi-selector separated by |.
-
-Signature:
-attrAssign(element: HTMLElement, multiQuerySelector: string, attributes: Record<string, string>): HTMLElement[]
-
-- multiQuerySelector example: ':scope > .aside | :scope > *:has(img)'
-- Returns an array of HTMLElements that received the attributes.
-
-Example:
-import { attrAssign } from '@trunkjs/content-pane';
-
-const host = document.querySelector('section')!;
-attrAssign(host, ':scope > img | :scope > figure', { slot: 'media' });
-
-## Styling the generated structure
-
-Because <content-area2> does not use Shadow DOM, you can style:
-- section wrappers produced by SectionTreeBuilder
-- any elements produced by applyLayout
-- your original content elements
-
-Typical patterns:
-- Target sections based on heading-derived structure
-- Use IDs and classes assigned via layout or attrAssign
-- Combine with CSS container queries for responsive layouts
-
-## Notes and caveats
-
-- H1 is treated as H2 (i = 20) to keep top-level content consistent.
-- HR becomes a divider at half-steps (+5) between major heading levels.
-- The package assumes you will either:
-  - Use <content-area2>, which orchestrates both steps, or
-  - Manually call SectionTreeBuilder then applyLayout in that order.
-- If you reference an unregistered custom element in a layout selector, an error element is inserted to make the problem visible and to avoid infinite recursion.
-
-## Building
-
-Run `nx build content-pane` to build the library.
-
-## Running unit tests
-
-Run `nx test content-pane` to execute the unit tests via [Vitest](https://vitest.dev/).
+```html
+<section>
+    <h2>Header 2</h2>
+    <p>text</p>
+    <div>
+        <h3>Header 3</h3>
+        <p>text</p>
+    </div>
+    <div>
+        <h3>Header 3</h3>
+        <p>text</p>
+    </div>
+</section>
+```

package/index.d.ts

@@ -1,3 +1,4 @@
 export * from './components/tj-content-pane/TjContentPane';
 export * from './lib/apply-layout';
 export * from './lib/attrAssign';
+export * from './lib/SectionTreeBuilder';

package/index.js

@@ -1,9 +1,12 @@
 var C = Object.defineProperty;
-var E = (n, t, r) => t in n ? C(n, t, { enumerable: !0, configurable: !0, writable: !0, value: r }) : n[t] = r;
-var h = (n, t, r) => E(n, typeof t != "symbol" ? t + "" : t, r);
-import { unsafeCSS as A, LitElement as N, html as _, ReactiveElement as L } from "lit";
-import { property as k, customElement as x } from "lit/decorators.js";
-import { create_element as w, LoggingMixin as I, Stopwatch as T, waitForDomContentLoaded as P } from "@trunkjs/browser-utils";
+var _ = (n, t, r) => t in n ? C(n, t, { enumerable: !0, configurable: !0, writable: !0, value: r }) : n[t] = r;
+var h = (n, t, r) => _(n, typeof t != "symbol" ? t + "" : t, r);
+import { unsafeCSS as E, LitElement as A, html as N, ReactiveElement as I } from "lit";
+import { property as L, customElement as y } from "lit/decorators.js";
+import { create_element as b, LoggingMixin as k, Stopwatch as T, waitForDomContentLoaded as P } from "@trunkjs/browser-utils";
+function V(n) {
+  return n && typeof n == "object" && "__I__" in n && typeof n.__I__ == "object" && "i" in n.__I__;
+}
 class S {
   constructor(t, r = !1) {
     h(this, "rootNode");
@@ -35,7 +38,7 @@ class S {
     return o;
   }
   createNewContainerNode(t, r) {
-    const o = this.getAttributeRecords(t, t.tagName === "HR"), e = w("section", o);
+    const o = this.getAttributeRecords(t, t.tagName === "HR"), e = b("section", o);
     return e.__IT = r, e;
   }
   arrangeSingleNode(t, r) {
@@ -69,12 +72,12 @@ class S {
   }
 }
 const $ = ":host{--border-color: red;--background-color: lightgray;font-family:Arial,sans-serif}#error-fixed-indicator{position:fixed;top:10px;right:10px;cursor:pointer;z-index:100000;padding:5px 10px;width:auto;max-width:90vw;min-width:100px;height:auto;box-shadow:0 4px 8px #0003;border:5px solid white;color:#fff;background-color:red;animation:blink 1s infinite;border-radius:15px;font-size:20px;font-weight:700;font-family:Arial,sans-serif}@keyframes blink{0%,to{background-color:#000}50%{background-color:red}}#error{background-color:var(--background-color);border:3px solid var(--border-color);padding:10px;margin:10px;border-radius:5px}h1{color:red;font-size:24px;margin:0}.error-details{font-size:14px;max-height:200px;overflow:auto}";
-var y = Object.defineProperty, j = Object.getOwnPropertyDescriptor, M = (n, t, r) => t in n ? y(n, t, { enumerable: !0, configurable: !0, writable: !0, value: r }) : n[t] = r, v = (n, t, r, o) => {
-  for (var e = o > 1 ? void 0 : o ? j(t, r) : t, s = n.length - 1, i; s >= 0; s--)
+var w = Object.defineProperty, M = Object.getOwnPropertyDescriptor, O = (n, t, r) => t in n ? w(n, t, { enumerable: !0, configurable: !0, writable: !0, value: r }) : n[t] = r, v = (n, t, r, o) => {
+  for (var e = o > 1 ? void 0 : o ? M(t, r) : t, s = n.length - 1, i; s >= 0; s--)
     (i = n[s]) && (e = (o ? i(t, r, e) : i(e)) || e);
-  return o && e && y(t, r, e), e;
-}, O = (n, t, r) => M(n, t + "", r);
-let f = class extends N {
+  return o && e && w(t, r, e), e;
+}, R = (n, t, r) => O(n, t + "", r);
+let f = class extends A {
   constructor(t = "An error occurred", r) {
     super();
     h(this, "originalCode");
@@ -85,7 +88,7 @@ let f = class extends N {
     return "tj-error-element";
   }
   render() {
-    return _`
+    return N`
       <div id="error-fixed-indicator" @click=${() => this.scrollIntoView({ behavior: "smooth" })}>
         Err: ${this.message}
       </div>
@@ -101,14 +104,14 @@ let f = class extends N {
     `;
   }
 };
-O(f, "styles", [A($)]);
+R(f, "styles", [E($)]);
 v([
-  k({ type: String, reflect: !0 })
+  L({ type: String, reflect: !0 })
 ], f.prototype, "message", 2);
 f = v([
-  x("tj-error-element")
+  y("tj-error-element")
 ], f);
-function R(n, { allowAttributes: t = !0, ignoreGaps: r = !0 } = {}) {
+function j(n, { allowAttributes: t = !0, ignoreGaps: r = !0 } = {}) {
   let o = "div", e = null, s = [], i = [], l = {};
   const d = /(^[a-z][\w-]*)|#[\w-]+|\.[\w:-]+|\[\s*([\w-]+)(?:\s*=\s*(['"]?)(.*?)\3)?\s*\]/gi;
   let a = 0;
@@ -137,10 +140,10 @@ function D(n) {
 function F(n, t, r) {
   var u, c;
   console.log("Applying layout to element:", n, "with layout:", r);
-  const o = /^(\+|-|)([0-9]+\.?[0-9]*);?/, e = r.replace(o, ""), s = R(e), i = { class: "" };
+  const o = /^(\+|-|)([0-9]+\.?[0-9]*);?/, e = r.replace(o, ""), s = j(e), i = { class: "" };
   s.attrsMap.class && (i.class = s.attrsMap.class + " "), i.class += s.classes.join(" "), i.id = s.id, ((u = i.class) == null ? void 0 : u.trim()) === "" && delete i.class, ((c = i.id) == null ? void 0 : c.trim()) === "" && delete i.id;
   const l = s.tag || "div";
-  let d = !1, a = w(l, { ...i, layoutOrig: r });
+  let d = !1, a = b(l, { ...i, layoutOrig: r });
   if (l.includes("-") && !customElements.get(l))
     console.warn(`Custom element <${l}> is not registered.`), a = new f(`Custom element <${l}> is not registered.`, n.outerHTML), n.replaceWith(a), a.append(n), d = !0;
   else {
@@ -180,7 +183,7 @@ var W = Object.getOwnPropertyDescriptor, z = (n, t, r, o) => {
     (i = n[s]) && (e = i(e) || e);
   return e;
 };
-let b = class extends I(L) {
+let x = class extends k(I) {
   static get is() {
     return "tj-content-pane";
   }
@@ -197,10 +200,10 @@ let b = class extends I(L) {
     t.arrange(r), g(Array.from(this.children), { recursive: !0 }), n.lap("after arrange");
   }
 };
-b = z([
-  x("tj-content-pane")
-], b);
-function V(n, t, r) {
+x = z([
+  y("tj-content-pane")
+], x);
+function J(n, t, r) {
   const o = [], e = t.split("|");
   for (const s of e) {
     const i = n.querySelectorAll(s.trim());
@@ -214,7 +217,9 @@ function V(n, t, r) {
   return o;
 }
 export {
-  b as ContentAreaElement2,
+  x as ContentAreaElement2,
+  S as SectionTreeBuilder,
   g as applyLayout,
-  V as attrAssign
+  J as attrAssign,
+  V as isSectionTreeElement
 };

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@trunkjs/content-pane",
-    "version": "1.0.1",
+    "version": "1.0.2",
     "main": "./index.js",
     "dependencies": {
         "@trunkjs/browser-utils": "^1.0.12",