kagekiri
    TypeScript icon, indicating that this package has built-in type declarations

    1.4.1 • Public • Published

    kagekiri build status

    Shadow DOM-piercing query APIs. Supports:

    API Interface Support
    querySelector Element, Document
    querySelectorAll Element, Document
    getElementsByClassName Element, Document
    getElementsByTagName Element, Document
    getElementsByTagNameNS Element, Document
    getElementById Document
    getElementsByName Document
    matches Element
    closest Element

    Usage

    Install:

    npm install --save kagekiri

    Query the document or a specific element:

    import { querySelector, querySelectorAll } from 'kagekiri'
    
    // query the document
    const elements = querySelectorAll('.container button')
    const element = querySelector('.container button')
    
    // or a specific element
    const elements = querySelectorAll('button', otherElement)
    const element = querySelector('button', otherElement)

    Example

    A custom element:

    <my-component></my-component>
    <script>
      class MyComponent extends HTMLElement {
        constructor() {
          super()
          const shadowRoot = this.attachShadow({mode: 'open'})
          shadowRoot.innerHTML = '<span class="hello">Hello</span>'
        }
      }
      customElements.define('my-component', MyComponent)
    </script>

    It renders as:

    <my-component>
      <!-- shadow root (open) -->
      <span class="hello">Hello</span>
    </my-component>

    You can't query the .hello element:

    document.querySelector('.hello')    // undefined 😞
    document.querySelectorAll('.hello') // empty 😞

    But with kagekiri you can!

    kagekiri.querySelector('.hello')    // <span> 😃
    kagekiri.querySelectorAll('.hello') // [<span>] 😃

    Your can even query across the shadow boundary!

    kagekiri.querySelector('my-component .hello')   // <span> 😃
    kagekiri.querySelector('my-component > .hello') // <span> 😃

    API

    closest

    closest(selector: string, element: Node): Element | null

    Find the closest ancestor of an element (or the element itself) matching the given CSS selector. Analogous to Element.closest

    Parameters:

    Name Type Description
    selector string CSS selector
    element Node target element to match against, and whose ancestors to match against

    Returns: Element | null


    getElementById

    getElementById(id: string, context?: DocumentOrShadowRoot): Element | null

    Query for an element matching the given ID, or null if not found. Analogous to Document.getElementById

    The default context is document. Choose another DocumentOrShadowRoot to query within that context.

    Parameters:

    Name Type Description
    id string element ID
    context? DocumentOrShadowRoot context to query in, or document by default

    Returns: Element | null


    getElementsByClassName

    getElementsByClassName(names: string, context?: Node): Element[]

    Query for all elements matching a given class name, or multiple if a whitespace-separated list is provided. Analogous to Document.getElementsByClassName.

    Unlike the standard API, this returns a static array of Elements rather than a live HTMLCollection.

    The default context is document. Choose another node to query within that context.

    Parameters:

    Name Type Description
    names string class name or whitespace-separated class names
    context? Node context to query in, or document by default

    Returns: Element[]


    getElementsByName

    getElementsByName(name: string, context?: DocumentOrShadowRoot): Element[]

    Query for all elements matching a given name. Analogous to Document.getElementsByName

    The default context is document. Choose another DocumentOrShadowRoot to query within that context.

    Unlike the standard API, this returns a static array of Elements rather than a live NodeList.

    Parameters:

    Name Type Description
    name string element name attribute
    context? DocumentOrShadowRoot context to query in, or document by default

    Returns: Element[]


    getElementsByTagName

    getElementsByTagName(tagName: string, context?: Node): Element[]

    Query for all elements matching a given tag name. Analogous to Document.getElementsByTagName. The "*" query is supported.

    Unlike the standard API, this returns a static array of Elements rather than a live HTMLCollection.

    The default context is document. Choose another node to query within that context.

    Parameters:

    Name Type Description
    tagName string name of the element tag
    context? Node context to query in, or document by default

    Returns: Element[]


    getElementsByTagNameNS

    getElementsByTagNameNS(namespaceURI: string, localName: string, context?: Node): Element[]

    Query for all elements matching a given tag name and namespace. Analogous to Document.getElementsByTagNameNS. The "*" query is supported.

    Unlike the standard API, this returns a static array of Elements rather than a live NodeList.

    The default context is document. Choose another node to query within that context.

    Parameters:

    Name Type Description
    namespaceURI string namespace URI, or "*" for all
    localName string local name, or "*" for all
    context? Node context to query in, or document by default

    Returns: Element[]


    matches

    matches(selector: string, element: Node): boolean

    Return true if the given Node matches the given CSS selector, or false otherwise. Analogous to Element.closest

    Parameters:

    Name Type Description
    selector string CSS selector
    element Node element to match against

    Returns: boolean


    querySelector

    querySelector(selector: string, context?: Node): Element | null

    Query for a single element matching the CSS selector, or return null if not found. Analogous to Document.querySelector

    The default context is document. Choose another element or DocumentOrShadowRoot to query within that context.

    Parameters:

    Name Type Description
    selector string CSS selector
    context? Node context to query in, or document by default

    Returns: Element | null


    querySelectorAll

    querySelectorAll(selector: string, context?: Node): Element[]

    Query for all elements matching a CSS selector. Analogous to Document.querySelectorAll

    The default context is document. Choose another node to query within that context.

    Parameters:

    Name Type Description
    selector string CSS selector
    context? Node context to query in, or document by default

    Returns: Element[]

    How it works

    kagekiri parses the CSS selector using postcss-selector-parser. Then it queries the entire DOM tree, traverses any shadowRoots it may find, and checks the selector from children to ancestors (the same way a browser would).

    Note that it only works on open shadow DOM. Closed shadow DOM cannot be traversed.

    Slotted elements are considered to be children of their slots (inside the shadow DOM) rather than children of their host components. If you don't want this behavior, you can use the normal DOM APIs (e.g. document.querySelector() or document.querySelectorAll()).

    See the tests for full supported CSS features.

    The name

    kage (shadow) + 切り kiri (cut).

    Roughly, "shadow-cutter."

    Build

    npm run build

    Build TypeScript-based API docs using kagekiri.d.ts, inject them into the README:

    npm run typedoc

    Test

    npm test

    Debug:

    npm run test:debug

    Lint:

    npm run lint

    Fix most lint issues:

    npm run lint:fix

    Test bundle size:

    npm run test:bundlesize

    Install

    npm i kagekiri

    DownloadsWeekly Downloads

    864

    Version

    1.4.1

    License

    BSD-3-Clause

    Unpacked Size

    680 kB

    Total Files

    10

    Last publish

    Collaborators

    • avatar
    • avatar
    • avatar