@trunkjs/content-pane 1.0.0

package/CHANGELOG.md

@@ -0,0 +1,81 @@
+# 1.0.0 (2025-08-11)
+
+This was a version bump only for content-pane to align it with other projects, there were no code changes.
+
+## 0.0.14 (2025-08-11)
+
+### 🧱 Updated Dependencies
+
+- Updated browser-utils to 1.0.12
+
+## 0.0.13 (2025-08-11)
+
+### 🧱 Updated Dependencies
+
+- Updated browser-utils to 1.0.11
+
+## 0.0.12 (2025-08-11)
+
+### 🧱 Updated Dependencies
+
+- Updated browser-utils to 1.0.10
+
+## 0.0.11 (2025-08-11)
+
+### 🧱 Updated Dependencies
+
+- Updated browser-utils to 1.0.9
+
+## 0.0.10 (2025-08-11)
+
+### 🧱 Updated Dependencies
+
+- Updated browser-utils to 1.0.8
+
+## 0.0.9 (2025-08-07)
+
+### 🧱 Updated Dependencies
+
+- Updated browser-utils to 1.0.7
+
+## 0.0.8 (2025-08-07)
+
+### 🧱 Updated Dependencies
+
+- Updated browser-utils to 1.0.6
+
+## 0.0.7 (2025-08-07)
+
+### 🧱 Updated Dependencies
+
+- Updated browser-utils to 1.0.5
+
+## 0.0.6 (2025-08-07)
+
+### 🧱 Updated Dependencies
+
+- Updated browser-utils to 1.0.4
+
+## 0.0.5 (2025-08-07)
+
+### 🧱 Updated Dependencies
+
+- Updated browser-utils to 1.0.3
+
+## 0.0.4 (2025-08-07)
+
+### 🧱 Updated Dependencies
+
+- Updated browser-utils to 1.0.2
+
+## 0.0.3 (2025-08-07)
+
+### 🧱 Updated Dependencies
+
+- Updated browser-utils to 1.0.1
+
+## 0.0.2 (2025-08-07)
+
+### 🧱 Updated Dependencies
+
+- Updated browser-utils to 1.0.0

package/README.md

@@ -0,0 +1,215 @@
+# content-pane
+
+This library was generated with [Nx](https://nx.dev).
+
+A lightweight toolkit for turning a flat block of HTML content into a, styled “content pane.” It provides:
+
+- 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.
+
+Status: experimental / evolving API.
+
+## Why use content-pane?
+
+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
+
+…content-pane is for you.
+
+## Packages and exports
+
+Install or import from:
+- @trunkjs/content-pane
+
+Exports:
+- Web Component: registered as custom element content-area2
+- Functions:
+  - applyLayout(elementOrElements, { recursive = true })
+  - attrAssign(element, multiQuerySelector, attributes)
+  - SectionTreeBuilder class
+
+Import examples:
+- Register the custom element (side-effect import): import '@trunkjs/content-pane'
+- Use utilities: import { applyLayout, attrAssign } from '@trunkjs/content-pane'
+
+## The <content-area2> Web Component
+
+The component is defined without Shadow DOM (createRenderRoot returns this), so your global CSS can style the generated structure directly.
+
+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
+
+Tag name: content-area2
+
+Note: The internal class is ContentAreaElement2. The static is getter returns 'tj-content-area' but the actual registered tag is content-area2.
+
+### Quick start (browser)
+
+- Include content-area2 on your page
+- Ensure the module is imported so the element is defined
+- Add headings and content as children
+
+Example:
+<!-- somewhere in your app bootstrap -->
+<script type="module">
+  import '@trunkjs/content-pane'; // registers <content-area2>
+</script>
+
+<content-area2>
+  <h2 layout="2">Introduction</h2>
+  <p>This is the intro paragraph.</p>
+
+  <h3>Details</h3>
+  <p>Some detailed text.</p>
+
+  <hr> <!-- becomes a mid-level divider -->
+  <h2 layout="+2">More</h2>
+  <p>Additional information appended at the same level as previous H2.</p>
+
+  <!-- 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>
+
+## 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/).

package/components/tj-content-pane/TjContentPane.d.ts

@@ -0,0 +1,16 @@
+import { ReactiveElement } from 'lit';
+declare const ContentAreaElement2_base: (abstract new (...args: any[]) => {
+    "__#2364@#debugCached": boolean | null;
+    invalidateDebugCache(): void;
+    readonly _debug: boolean | null;
+    log(...args: any[]): void;
+    warn(...args: any[]): void;
+    error(...args: any[]): void;
+}) & typeof ReactiveElement;
+export declare class ContentAreaElement2 extends ContentAreaElement2_base {
+    static get is(): string;
+    createRenderRoot(): HTMLElement | DocumentFragment;
+    constructor();
+    connectedCallback(): Promise<void>;
+}
+export {};

package/components/tj-error-element/ErrorElement.d.ts

@@ -0,0 +1,9 @@
+import { LitElement } from 'lit';
+export declare class TjErrorElement extends LitElement {
+    static styles: import('lit').CSSResult[];
+    private originalCode?;
+    private message;
+    static get is(): string;
+    constructor(message?: string, originalCode?: string);
+    render(): import('lit-html').TemplateResult<1>;
+}

package/index.d.ts

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

package/index.js

@@ -0,0 +1,219 @@
+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 v, LoggingMixin as I, Stopwatch as T, waitForDomContentLoaded as P } from "@trunkjs/browser-utils";
+class S {
+  constructor(t, r = !1) {
+    h(this, "rootNode");
+    h(this, "currentContainerNode", null);
+    h(this, "containerPath", []);
+    h(this, "containerIndex", [0]);
+    h(this, "lastFixedI", 20);
+    this.debug = r, this.currentContainerNode = this.rootNode = t, this.containerPath.push(this.rootNode);
+  }
+  getI(t) {
+    const r = t.tagName, o = t.getAttribute("layout"), e = { i: -99, variant: "new", tag: "hr", hi: null };
+    if (o) {
+      const s = /^(\+|-|)([0-9]\.?[0-9]?|)(;|$)/, i = o.match(s);
+      i && (console.debug("Layout matches", i), e.variant = i[1] === "+" ? "append" : i[1] === "-" ? "skip" : "new", i[2] !== "" && (e.i = parseFloat(i[2]) * 10));
+    }
+    if (r.startsWith("H") && r.length === 2) {
+      let s = r.substring(1);
+      return e.tag = "h", e.hi = parseInt(s), s === "1" && (s = "2"), e.i === -99 && (e.i = parseInt(s) * 10, this.lastFixedI = e.i), e;
+    }
+    return e.i === -99 && r === "HR" ? (e.i = this.lastFixedI + 5, e) : null;
+  }
+  getAttributeRecords(t, r = !1) {
+    const o = {};
+    for (const e of t.attributes)
+      e.name.startsWith("section-") ? o[e.name] = e.value.replace(/^section-/, "") : e.name.startsWith("layout") ? (o[e.name] = e.value, t.removeAttribute(e.name)) : r && (o[e.name] = e.value);
+    if (!r)
+      for (const e of Array.from(t.classList))
+        e.startsWith("section-") && (o.class = (o.class || "") + " " + e.replace(/^section-/, ""), t.classList.remove(e));
+    return o;
+  }
+  createNewContainerNode(t, r) {
+    const o = this.getAttributeRecords(t, t.tagName === "HR"), e = v("section", o);
+    return e.__IT = r, e;
+  }
+  arrangeSingleNode(t, r) {
+    r.i;
+    let o = 0;
+    for (o = 0; o < this.containerIndex.length && !(this.containerIndex[o] >= r.i); o++)
+      ;
+    let e = null;
+    r.variant === "append" ? (console.log("Appending to container at index", o, "with i", r.i), e = this.containerPath[o]) : e = this.createNewContainerNode(t, r);
+    const s = this.containerPath[o - 1];
+    this.containerPath.length = o, this.containerIndex.length = o, e.appendChild(t), s.appendChild(e), this.containerPath.push(e), this.containerIndex.push(r.i), this.currentContainerNode = e;
+  }
+  appendToCurrentContainer(t) {
+    if (this.currentContainerNode === null)
+      throw new Error("No current container node set");
+    this.currentContainerNode.appendChild(t);
+  }
+  arrange(t) {
+    for (let r of t) {
+      if (r.nodeType !== Node.ELEMENT_NODE) {
+        this.appendToCurrentContainer(r);
+        continue;
+      }
+      const o = r, e = this.getI(o);
+      if (!e || e.variant === "skip") {
+        this.appendToCurrentContainer(r);
+        continue;
+      }
+      this.arrangeSingleNode(o, e);
+    }
+  }
+}
+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 w = Object.defineProperty, j = Object.getOwnPropertyDescriptor, O = (n, t, r) => t in n ? w(n, t, { enumerable: !0, configurable: !0, writable: !0, value: r }) : n[t] = r, y = (n, t, r, o) => {
+  for (var e = o > 1 ? void 0 : o ? j(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 && w(t, r, e), e;
+}, R = (n, t, r) => O(n, t + "", r);
+let p = class extends N {
+  constructor(t = "An error occurred", r) {
+    super();
+    h(this, "originalCode");
+    h(this, "message");
+    this.message = t, this.originalCode = r;
+  }
+  static get is() {
+    return "tj-error-element";
+  }
+  render() {
+    return _`
+      <div id="error-fixed-indicator" @click=${() => this.scrollIntoView({ behavior: "smooth" })}>
+        Err: ${this.message}
+      </div>
+      <div id="error">
+        <h1>Error: ${this.message}</h1>
+        <pre class="error-details">
+          ${this.originalCode ? this.originalCode : "No code provided."}
+        </pre
+        >
+
+        <slot></slot>
+      </div>
+    `;
+  }
+};
+R(p, "styles", [A($)]);
+y([
+  k({ type: String, reflect: !0 })
+], p.prototype, "message", 2);
+p = y([
+  x("tj-error-element")
+], p);
+function D(n, { allowAttributes: t = !0, ignoreGaps: r = !0 } = {}) {
+  let o = "div", e = null, s = [], i = [], l = {};
+  const c = /(^[a-z][\w-]*)|#[\w-]+|\.[\w:-]+|\[\s*([\w-]+)(?:\s*=\s*(['"]?)(.*?)\3)?\s*\]/gi;
+  let a = 0;
+  for (; ; ) {
+    const u = c.exec(n);
+    if (!u || u.index !== a) {
+      if (!r && u && u.index > a)
+        break;
+      break;
+    }
+    const d = u[0];
+    if (d[0] === "#") e = d.slice(1);
+    else if (d[0] === ".") s.push(d.slice(1));
+    else if (d[0] === "[") {
+      if (!t) throw new Error(`Attributes not allowed: '${d}'`);
+      const g = u[2], m = u[4] || void 0;
+      i.push({ name: g, value: m }), l[g] = m;
+    } else o = d;
+    a += d.length;
+  }
+  return { tag: o, id: e, classes: s, attrs: i, attrsMap: l, length: a, rest: n.slice(a) };
+}
+function M(n) {
+  return typeof n.beforeLayoutCallback == "function";
+}
+function F(n, t, r) {
+  console.log("Applying layout to element:", n, "with layout:", r);
+  const o = /^(\+|-|)([0-9]+\.?[0-9]*);?/, e = r.replace(o, ""), s = D(e);
+  let i = {};
+  i.class !== void 0 && (i.class += " "), i.class += s.classes.join(" "), i.id = s.id;
+  let l = s.tag || "div", c = !1, a = v(l, { ...i, layoutOrig: r });
+  if (l.includes("-") && !customElements.get(l))
+    console.warn(`Custom element <${l}> is not registered.`), a = new p(`Custom element <${l}> is not registered.`, n.outerHTML), n.replaceWith(a), a.append(n), c = !0;
+  else {
+    let u = Array.from(n.children);
+    M(a) && (c = a.beforeLayoutCallback(n, a, u) === !1), console.log(
+      "Replacement element created:",
+      a,
+      "with children:",
+      u,
+      "skipChildren:",
+      c
+    ), a.__ORIG_ELEMENT__ = n, a.append(...Array.from(n.children)), n.replaceWith(a);
+  }
+  return {
+    replacementElement: a,
+    skipChildren: c
+  };
+}
+function f(n, t = {}) {
+  console.log("applyLayout called with element:", n, "and options:", t);
+  const { recursive: r = !0 } = t;
+  let o = [];
+  if (Array.isArray(n))
+    return n.forEach((l) => o.push(...f(l, t))), o;
+  if (!(n instanceof HTMLElement))
+    return [];
+  const e = n.getAttribute("layout");
+  let s = !1, i = n;
+  if (e && ({ replacementElement: i, skipChildren: s } = F(n, t, e)), r && !s) {
+    const l = Array.from(i.children);
+    console.log("Applying layout to children:", l, "of element:", i), l.forEach((c) => o.push(...f(c, t)));
+  }
+  return o;
+}
+var W = Object.getOwnPropertyDescriptor, z = (n, t, r, o) => {
+  for (var e = o > 1 ? void 0 : o ? W(t, r) : t, s = n.length - 1, i; s >= 0; s--)
+    (i = n[s]) && (e = i(e) || e);
+  return e;
+};
+let b = class extends I(L) {
+  static get is() {
+    return "tj-content-pane";
+  }
+  createRenderRoot() {
+    return this;
+  }
+  constructor() {
+    super();
+  }
+  async connectedCallback() {
+    const n = new T("SectionTreeBuilder");
+    await P(), super.connectedCallback();
+    const t = new S(this), r = Array.from(this.children);
+    t.arrange(r), f(Array.from(this.children), { recursive: !0 }), n.lap("after arrange");
+  }
+};
+b = z([
+  x("tj-content-pane")
+], b);
+function V(n, t, r) {
+  const o = [], e = t.split("|");
+  for (const s of e) {
+    const i = n.querySelectorAll(s.trim());
+    if (i.length > 0)
+      for (const l of i) {
+        o.push(l);
+        for (const [c, a] of Object.entries(r))
+          l.setAttribute(c, a);
+      }
+  }
+  return o;
+}
+export {
+  b as ContentAreaElement2,
+  f as applyLayout,
+  V as attrAssign
+};

package/lib/SectionTreeBuilder.d.ts

@@ -0,0 +1,28 @@
+export type IType = {
+    /**
+     * Number  10 - 60 - 2.5 -> 25
+     */
+    i: number;
+    variant: "append" | "new" | "skip";
+    tag: "hr" | "h";
+    hi?: number | null;
+};
+export interface SectionTreeElement {
+    __IT: IType;
+}
+export declare function isSectionTreeElement(obj: any): obj is SectionTreeElement;
+export declare class SectionTreeBuilder {
+    debug: boolean;
+    private rootNode;
+    private currentContainerNode;
+    private containerPath;
+    private containerIndex;
+    constructor(rootNode: HTMLElement, debug?: boolean);
+    private lastFixedI;
+    private getI;
+    protected getAttributeRecords(originalNode: HTMLElement, isHR?: boolean): Record<string, string>;
+    protected createNewContainerNode(originalNode: HTMLElement, it: IType): HTMLElement;
+    protected arrangeSingleNode(node: HTMLElement, it: IType): void;
+    private appendToCurrentContainer;
+    arrange(nodes: Node[]): void;
+}

package/lib/apply-layout.d.ts

@@ -0,0 +1,28 @@
+type ApplyLayoutOptions = {
+    recursive?: boolean;
+};
+export interface ManualBeforeLayoutElement {
+    /**
+     * This callback is called before the layout is applied to the element. So the orgiginal element is still attached to the DOM
+     * and all its children are still present.
+     *
+     * You should only
+     *
+     * If the callback returns `false`, the layout engine will not apply the layout to child elements, effectively skipping the layout for this element.
+     * In this case, the element has to handle applyLayout() itself, or it will not be applied at all.
+     *
+     * It can be used to modify the element or its children before the layout is applied.
+     * @param origElement The original element that is being replaced
+     * @param instance The new element that is being created
+     * @param children The children of the original element
+     *
+     * @example
+     * ```typescript
+     * beforeLayoutCallback(origElement, instance, elements) {
+     *   // Modify the instance or its children before the layout is applied
+     *   attrAssign(origElement, ":scope > .aside | :scope > *:has(img)", {slot: "aside"});
+     */
+    beforeLayoutCallback(origElement: HTMLElement, instance: this, children: Element[]): void | boolean;
+}
+export declare function applyLayout(element: HTMLElement | Element | Element[], options?: ApplyLayoutOptions): HTMLElement[];
+export {};

package/lib/attrAssign.d.ts

@@ -0,0 +1 @@
+export declare function attrAssign(element: HTMLElement, multiQuerySelector: string, attributes: Record<string, string>): HTMLElement[];

package/package.json

@@ -0,0 +1,11 @@
+{
+    "name": "@trunkjs/content-pane",
+    "version": "1.0.0",
+    "main": "./index.js",
+    "dependencies": {
+        "@trunkjs/browser-utils": "^1.0.12",
+        "lit": "^3.3.1"
+    },
+    "type": "module",
+    "types": "./index.d.ts"
+}

package/tools/html-parsers.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Parse simple CSS selector prefix from start of string
+ * - Tag optional (defaults to div)
+ * - Supports #id, multiple .classes (with - and :)
+ * - Optional attribute parsing; throws if disabled and attribute found
+ * - Returns attrs array + attrsMap for direct lookup
+ * - Returns rest of string that was not parsed
+ *
+ * @param sel         Selector string
+ * @param options     { allowAttributes?: boolean, ignoreGaps?: boolean }
+ *
+ * @example
+ * parseSelector('div.main#app.other[data-id=123] foo', { ignoreGaps: false })
+ * // {
+ * //   tag:'div', id:'app', classes:['main','other'],
+ * //   attrs:[{name:'data-id',value:'123'}],
+ * //   attrsMap:{'data-id':'123'},
+ * //   length:29, rest:' foo'
+ * // }
+ */
+export declare function parseSelector(sel: string, { allowAttributes, ignoreGaps }?: {
+    allowAttributes?: boolean | undefined;
+    ignoreGaps?: boolean | undefined;
+}): {
+    tag: string;
+    id: string | null;
+    classes: string[];
+    attrs: {
+        name: string;
+        value?: string;
+    }[];
+    attrsMap: Record<string, string | undefined>;
+    length: number;
+    rest: string;
+};