@knowark/componarkjs 1.7.3

package/Makefile

@@ -0,0 +1,49 @@
+.PHONY: all tests coverage
+
+setup:
+	npm install -g browser-sync && \
+	npm install -g http-server && \
+	sudo apt-get install build-essential libcairo2-dev \
+	libpango1.0-dev libjpeg-dev libgif-dev librsvg2-dev
+
+install:
+	npm install
+
+test:
+	npm run test
+
+clean:
+	rm -rf ./dist
+
+showcase:
+	npx live-server ./showcase/
+
+dev:
+	npm run dev
+
+prod:
+	npm run prod
+
+push:
+	git push && git push --tags
+
+deploy:
+	sshpass -e rsync -av --delete ./dist/ \
+		${RSYNC_USER}@${RSYNC_HOST}:${RSYNC_DIR}
+
+reset:
+	git reset --hard
+	git clean -xdf
+
+purge:
+	rm -rf ./node_modules
+
+http:
+	http-server -p 8084 -c-1 dist
+
+updates:
+	npx npm-check-updates
+
+upgrade:
+	npx npm-check-updates --upgrade
+	npm install

package/README.md

@@ -0,0 +1,47 @@
+# ComponArk
+
+Pragmatic Web Components Library
+
+Introduction
+============
+
+Componark is a collection of ready to use web components to propel the creation
+of user interfaces. A common *Component* base class is provided to ensure
+inter-component compatibility and common development idioms. This class is only
+a thin wrapper on top of the *HTMLElement* custom elements class, and might be
+extended in your own application code to create new components.
+
+Reference
+=========
+
+- `Base Component <lib/base/component>`_
+
+Components library
+------------------
+
+- `<ark-accordion> <lib/components/accordion>`_
+- `<ark-alert> <lib/components/alert>`_
+- `<ark-audio> <lib/components/audio>`_
+- `<ark-button> <lib/components/button>`_
+- `<ark-camera> <lib/components/camera>`_
+- `<ark-card> <lib/components/card>`_
+- `<ark-chart> <lib/components/chart>`_
+- `<ark-checkbox> <lib/components/checkbox>`_
+- `<ark-droparea> <lib/components/droparea>`_
+- `<ark-gallery> <lib/components/gallery>`_
+- `<ark-icon> <lib/components/icon>`_
+- `<ark-list> <lib/components/list>`_
+- `<ark-input> <lib/components/input>`_
+- `<ark-location> <lib/components/location>`_
+- `<ark-map> <lib/components/map>`_
+- `<ark-modal> <lib/components/modal>`_
+- `<ark-multiselect> <lib/components/multiselect>`_
+- `<ark-paginator> <lib/components/paginator>`_
+- `<ark-radio> <lib/components/radio>`_
+- `<ark-select> <lib/components/select>`_
+- `<ark-sidebar> <lib/components/sidebar>`_
+- `<ark-signature> <lib/components/signature>`_
+- `<ark-spinner> <lib/components/spinner>`_
+- `<ark-splitview> <lib/components/splitview>`_
+- `<ark-tabs> <lib/components/tabs>`_
+- `<ark-tooltip> <lib/components/tooltip>`_

package/knowarkjs.code-workspace

@@ -0,0 +1,29 @@
+{
+  "folders": [
+    {
+      "path": "."
+    }
+  ],
+  "settings": {
+    "editor.tabSize": 2,
+    "editor.insertSpaces": true,
+    "editor.detectIndentation": false
+  },
+  "extensions": {
+    "recommendations": [
+      "bashmish.es6-string-css",
+      "tobermory.es6-string-html",
+      "zjcompt.es6-string-javascript",
+      "xabikos.javascriptsnippets",
+      "graphql.vscode-graphql",
+      "dbaeumer.vscode-eslint",
+      "syler.sass-indented",
+      "yzhang.markdown-all-in-one",
+      "mervin.markdown-formatter",
+      "shd101wyy.markdown-preview-enhanced",
+      "shuworks.vscode-table-formatter",
+      "waderyan.gitblame",
+      "snooty.snooty",
+    ]
+  }
+}

package/lib/base/component/README.rst

@@ -0,0 +1,113 @@
+Component
+*********
+
+This is the base class for the *Componark* library of web components. It might
+be used in application code as well as to create new custom elements, which can
+of course use the pre-built components in this library in their composition.
+
+
+Reference
+=========
+
+Usage
+-----
+
+A new component (i.e. custom element) should be created by just extending the
+*Component* base class.
+
+.. code:: javascript
+
+   import { Component } from 'base/component'
+
+   class MyComponent extends Component {
+
+   }
+
+
+Lifecycle
+---------
+
+The lifecycle of the Componark's base component overlaps with that of the
+standard `custom elements specification <https://developer.mozilla.org/en-US/
+docs/Web/Web_Components/Using_custom_elements#using_the_lifecycle_callbacks>`_.
+Howerver, the *Component* base class provides additional extension points to
+simplify state management and the rendering process.
+
+- constructor()
+    - **init(context: object)**
+- connectedCallback()
+    - **async update()**
+        - **render()**
+        - **async load()**
+
+
+Methods
+-------
+
+constructor()
+^^^^^^^^^^^^^
+
+This is a custom element *standard* method. The constructor *must not*
+receive any parameters and is invoked every time a new instance of a
+*Component* is **created**. The default constructor implementation calls the
+**init()** method with an empty object and that is the place in which custom
+initialization of state should be performed when using componark. The automatic
+syncronization between reflected properties and attributes is also done inside
+the constructor.
+
+init(context: object)
+^^^^^^^^^^^^^^^^^^^^^
+
+The **init()** method is the place where state initialization of the component
+should be made. It is called without context arguments by the constructor on
+component creation and thus, should resiliently handle any form of attributes
+received to set the state of the component before **rendering**. The *init()*
+method should be called as well in parent components, for *updating* the
+state of the nested component and then explicitly invoking **render()** to
+present those changes in the user interface. The **init()** method returns the
+current instance (i.e. *this*) to enable chaining, so don't forget to return
+*super.init()* when extending this method.
+
+connectedCallback()
+^^^^^^^^^^^^^^^^^^^
+
+The *connectedCallback()* method is one of the default lifecycle callbacks or
+reactions of the `custom elements specification
+<https://developer.mozilla.org/en-US/docs/Web/Web_Components/
+Using_custom_elements#using_the_lifecycle_callbacks>`_. This method shouldn't
+be extended directly by Componark's components as there are other methods in
+this reference which are better suited to provide customization and extension.
+The **connectedCallback()** is invoked every time a *Component* is inserted
+into the *DOM* (i.e. injected in the page).
+
+async update()
+^^^^^^^^^^^^^^
+
+The *update()* method is an *asynchronous* consolidation method whose purpose
+is to simultaneously call **render()** and **load()**. The *update()* method is
+called by the *connectedCallback()* standard reaction and after first injection
+might also be called explicitly by user code.
+
+render()
+^^^^^^^^
+
+This method should be extended by every component to set its visual
+representation (i.e. html) based on its current state. The produced document
+string should be assigned to the **content** property of the *Component*
+which in turn will inject it into the *DOM*. Conditionals, loops and any kind
+of logic can be used inside the *render()* method to dynamically set the
+*Components* presentation based on its attributes, properties or any other
+environmental state. The **render()** method returns the current instance
+(i.e. *this*) to enable chaining, so don't forget to return *super.render()*
+when extending this method.
+
+async load()
+^^^^^^^^^^^^
+
+The *load()* lifecycle asynchronous method is the place where custom data
+fetching or other kinds of asynchronous operations should be performed. This
+method is invoked by *connectedCallback()* every time the *Component* is
+injected into the DOM (in an indirect manner through *update()*). After
+finishing its asynchronous tasks (e.g. obtaining some requested external data)
+the *load()* method might change the component's state and presentation and
+even explicitly call *render()*.

package/lib/base/component/component.js

@@ -0,0 +1,115 @@
+import { define, listen, reflect, slot, keys } from "../utils/index.js"
+import styles from '../styles/index.js'
+
+const tag = 'ark-component'
+export class Component extends HTMLElement {
+  constructor() {
+    super()
+    this.binding = "listen"
+    reflect(this, this.reflectedProperties())
+  }
+
+  /**
+   * @param {string} tag
+   * @param {CustomElementConstructor} element
+   * @param {string} styles **/
+  static define(tag, element, styles = null) {
+    define(tag, element, styles)
+  }
+
+  /**
+   * @param {object} styleMap
+   * @return {string} **/
+  styleNames(styleMap) {
+    return keys(styleMap)
+  }
+
+  /**
+   * @param {Object<string, any>} _context
+   * @return {Component} */
+  init(_context = {}) {
+    return this
+  }
+
+  /** @return {string[]} */
+  reflectedProperties() {
+    return []
+  }
+
+  get slots() {
+    return slot(this)
+  }
+
+  /** @param {string} content */
+  set content(content) {
+    this.innerHTML = content
+  }
+
+  /** @return {string} */
+  get content() {
+    return this.innerHTML
+  }
+
+  connectedCallback() {
+    try {
+      !this['state'] && this.init({})
+      this.render()
+    } catch (error) {
+      this.emit("error", error)
+      throw error
+    }
+    this.load()
+  }
+
+  /** @return {Component} */
+  render() {
+    this.classList.add(this.tagName.toLowerCase())
+    listen(this)
+    return this
+  }
+
+  async load() {}
+
+  /**
+   * @param {string} selectors
+   * @return {Component} */
+  select(selectors) {
+    return /** @type {Component} */ (this.querySelector(selectors))
+  }
+
+  /**
+   * @param {string} selectors
+   * @return {NodeListOf<Component>} */
+  selectAll(selectors) {
+    return /** @type {NodeListOf<Component>} */ (this.querySelectorAll(
+      selectors
+    ))
+  }
+
+  /**
+   * @param {string} type
+   * @param {any} detail */
+  emit(type, detail) {
+    this.dispatchEvent(
+      new CustomEvent(type, {
+        detail,
+        bubbles: true,
+        cancelable: true,
+      })
+    )
+  }
+
+  /**
+   * @param {string} resource
+   * @return {any} */
+  resolve(resource) {
+    const event = new CustomEvent("resolve", {
+      detail: { resource },
+      bubbles: true,
+      cancelable: true,
+    })
+    this.dispatchEvent(event)
+    return event.detail[resource]
+  }
+}
+Component.define(tag, Component, styles)

package/lib/base/component/component.test.js

@@ -0,0 +1,327 @@
+import { jest } from '@jest/globals'
+import { Component } from './component.js'
+
+class MockComponent extends Component {
+  init(context = {}) {
+    this.context = context
+    this.data = {}
+    this.dependency = undefined
+    return super.init()
+  }
+
+  reflectedProperties() { return ['code'] }
+
+  erroringHandler (_event) {
+    throw new Error('Something went wrong!')
+  }
+
+  async asyncErroringHandler (_event) {
+    const callback = async () => { 
+      throw new Error('Something went async wrong!') }
+    await callback()
+  }
+
+  render() {
+    this.dependency = this.resolve('Dependency')
+    return super.render()
+  }
+}
+Component.define('mock-component', MockComponent)
+
+
+describe('Component', () => {
+  let container = null
+  let component = null
+  beforeEach(() => {
+    container = document.createElement('div')
+    container.innerHTML = `<mock-component code="XYZ123"></mock-component>`
+    component = container.querySelector('mock-component')
+    document.body.append(container)
+  })
+
+  afterEach(() => {
+    container.remove()
+    container = null
+    component = null
+  })
+
+  it('can be instantiated', () => {
+    expect(component).toBeTruthy()
+  })
+
+  it('has an stable public api', () => {
+    expect(typeof component.constructor.define).toEqual('function')
+    expect(typeof component.init).toEqual('function')
+    expect(typeof component.reflectedProperties).toEqual('function')
+    expect(typeof component.connectedCallback).toEqual('function')
+    expect(typeof component.render).toEqual('function')
+    expect(typeof component.load).toEqual('function')
+    expect(typeof component.select).toEqual('function')
+    expect(typeof component.selectAll).toEqual('function')
+    expect(typeof component.emit).toEqual('function')
+    expect(typeof component.content).toBeDefined()
+  })
+
+  it('has an init method through which state is set', () => {
+    const response = component.init({attribute: 'value'})
+    expect(response).toBe(component)
+  })
+
+  it('can set its content via a property', () => {
+    component.content = `<p>Hello World</p>`
+    const paragraph = component.querySelector('p')
+    expect(component.content).toBe(`<p>Hello World</p>`)
+    expect(paragraph.outerHTML).toBe(`<p>Hello World</p>`)
+  })
+
+  it('can have some of its attributes reflected as properties', () => {
+    expect(component.code).toBe('XYZ123')
+  })
+
+  it('sets its tag name as class when rendered', () => {
+    component.render()
+    expect(component.className).toEqual('mock-component')
+  })
+
+  it('keeps its previous classes after rendering', () => {
+    component.classList.add('custom-class')
+    component.classList.add('custom-class')
+    component.classList.add('special-class')
+    component.render()
+    expect(component.className).toEqual(
+      'mock-component custom-class special-class')
+  })
+
+  it('emits custom events', () => {
+    let detail = null
+    const handler = (event) => {detail = event.detail}
+    component.addEventListener('fire', handler)
+
+    component.emit('fire', {location: 'indoors'})
+
+    expect(detail).toEqual({location: 'indoors'})
+  })
+
+  it('calls the load method on connectedCallback', async () => {
+    const component = document.createElement('mock-component') 
+    const initSpy = jest.spyOn(component, 'init')
+    const renderSpy = jest.spyOn(component, 'render')
+    const loadSpy = jest.spyOn(component, 'load')
+
+    document.body.append(component)
+
+    expect(initSpy).toHaveBeenCalledTimes(1)
+    expect(renderSpy).toHaveBeenCalledTimes(1)
+    expect(loadSpy).toHaveBeenCalledTimes(1)
+  })
+
+  it('catches and re-raises connectedCallback errors', async () => {
+    expect.assertions(1)
+    const component = document.createElement('mock-component') 
+    const consoleError = console.error
+    console.error = jest.fn()
+    component.render = () => { 
+      throw new Error('Render Error!')
+    }
+
+    try {
+      component.connectedCallback()
+    } catch (error) {
+      expect(error.message).toEqual('Render Error!')
+    }
+
+    console.error = consoleError
+  })
+
+
+  it('selects the children matching a selector', () => {
+    container.innerHTML = `
+    <mock-component>
+      <div class="blue"></div>
+      <div class="red"></div>
+      <div class="red"></div>
+    </mock-component>
+    `
+    const component = container.querySelector('mock-component')
+
+    const blue = component.select('.blue')
+    expect(blue.tagName).toEqual('DIV')
+
+    const red = component.selectAll('.red')
+    expect(red.length).toEqual(2)
+  })
+
+  it('retrieves its slots through the slots method', () => {
+    container.innerHTML = `
+    <mock-component>
+      <div slot="header" class="header"></div>
+      <div class="body"></div>
+      <div class="aside"></div>
+      <div slot="footer" class="footer"></div>
+    </mock-component>
+    `
+    const component = container.querySelector('mock-component')
+
+    expect(component.slots).toEqual({
+      header: [component.select('.header')],
+      general: [component.select('.body'), component.select('.aside')],
+      footer: [component.select('.footer')]
+    })
+  })
+  
+  it('binds its properties to children events', async () => {
+    container.innerHTML = `
+    <mock-component>
+      <input type="text" listen on-input="{{ data.value = data }}"></input>
+    </mock-component>
+    `
+
+    const component = container.querySelector('mock-component')
+    const input = component.select('input')
+
+
+    input.dispatchEvent(new InputEvent('input',  {bubbles: true, data: 'E'}))
+
+    expect(component.data.value).toEqual('E')
+  })
+
+  it('binds to the target.value event property by default', async () => {
+    container.innerHTML = `
+    <mock-component>
+      <input type="text" listen on-input="{{ data.value }}"></input>
+    </mock-component>
+    `
+    const component = container.querySelector('mock-component')
+    const input = component.select('input')
+    const inputEvent = new InputEvent('input')
+    const target = { name: 'input', value: 'X' }
+    Object.defineProperty(
+      inputEvent, 'target', { writable: false, value: target });
+
+    input.dispatchEvent(inputEvent)
+
+    expect(component.data.value).toEqual('X')
+  })
+
+  it('binds to the detail custom event property', async () => {
+    container.innerHTML = `
+    <mock-component>
+      <input type="text" listen on-alter="{{ data.value }}"></input>
+    </mock-component>
+    `
+
+    const component = container.querySelector('mock-component')
+    const input = component.select('input')
+
+    input.dispatchEvent(
+      new CustomEvent('alter',  { bubbles: true, detail: 'A' }))
+
+    expect(component.data.value).toEqual('A')
+  })
+
+  it('emits an error event on declared listeners', async () => {
+    container.innerHTML = `
+    <mock-component>
+      <input type="text" listen on-alter="erroringHandler"></input>
+    </mock-component>
+    `
+
+    const component = container.querySelector('mock-component')
+
+    let errorEvent = {}
+    component.addEventListener('error', (event) => errorEvent = event)
+
+    const input = component.select('input')
+
+    input.dispatchEvent(
+      new CustomEvent('alter',  { bubbles: true, detail: 'I will error!' }))
+
+    expect(errorEvent.detail.message).toEqual('Something went wrong!')
+  })
+
+  it('emits an error event on declared async listeners', async () => {
+    container.innerHTML = `
+    <mock-component>
+      <input type="text" listen on-alter="asyncErroringHandler"></input>
+    </mock-component>
+    `
+
+    const component = container.querySelector('mock-component')
+
+    let errorEvent = {}
+    component.addEventListener('error', (event) => errorEvent = event)
+
+    const input = component.select('input')
+
+    input.dispatchEvent(
+      new CustomEvent('alter',  { bubbles: true, detail: 'I will error!' }))
+
+    // Sleep
+    await new Promise(resolve => setTimeout(resolve, 0))
+
+    expect(errorEvent.detail.message).toEqual('Something went async wrong!')
+  })
+
+  it('resolves its resource dependencies using events propagation', () => {
+    const listener = (event) => {
+      const resource = event.detail.resource
+      event.detail[resource] = 'RESOLVED_DEPENDENCY'
+    }
+    document.addEventListener('resolve', listener)
+    container.innerHTML = `
+    <mock-component></mock-component>
+    `
+    const component = container.querySelector('mock-component')
+
+    expect(component.dependency).toEqual('RESOLVED_DEPENDENCY')
+    document.removeEventListener('resolve', listener)
+  })
+
+  it('provides the dependencies requested to it by child components', () => {
+    class ParentComponent extends MockComponent {
+      provide(resource) {
+        if (resource === 'Dependency') {
+          return `RESOURCE: ${resource} PROVIDED BY: ${this.id}`
+        }
+        if (resource === 'state') return { key: 'value' }
+      }
+    }
+    Component.define('parent-component', ParentComponent)
+
+    container.innerHTML = `
+    <parent-component id="parent">
+      <mock-component id="child"></mock-component>
+    </parent-component>
+    `
+    const parent = container.querySelector('#parent')
+    const child = container.querySelector('#child')
+
+    expect(child.dependency).toEqual(
+      "RESOURCE: Dependency PROVIDED BY: parent")
+
+    const state = child.resolve('state')
+    expect(state).toEqual({ key: 'value' })
+
+    const unknown = child.resolve('unknown')
+    expect(unknown).toBe(undefined)
+  })
+
+  it('provides a styleNames utility function for setting styles', () => {
+    container.innerHTML = `
+    <mock-component class></mock-component>
+    `
+    const component = container.querySelector('mock-component')
+    const background = 'primary'
+    const shadow = 'small'
+    const color = ''
+    const styleMap = {
+      [`background-${background}`]: background,
+      [`color-${color}`]: color,
+      [`shadow-${shadow}`]: shadow,
+    }
+
+    const result = component.styleNames(styleMap)
+
+    expect(result).toEqual('background-primary shadow-small')
+  })
+})

package/lib/base/component/index.js

@@ -0,0 +1,3 @@
+export { Component } from './component.js'
+export const css = String.raw
+export const html = String.raw

package/lib/base/index.js

@@ -0,0 +1 @@
+export { Component, css, html } from './component/index.js'

package/lib/base/styles/index.js

@@ -0,0 +1,3 @@
+import styles from './styles.js'
+
+export default styles