kiln.js

[nelsonpecora]

Per @rmfarrell:

I find the schema.yml problematic enough that I think it needs a refactor

The Problem

• The Schema is tightly coupled with Kiln. This creates a lot of cognitive overhead for developers new to the schema file and also violates the open/closed principle. In order to extend the functionality of a kiln component, you have to change the interface of the schema, requiring a new version. Currently, a lot of implementation logic is bound up with the config file.
• A declarative interface isn't the best solution for a kiln configuration. I'll get into this more, there are so many new use-cases in Kiln that there is no way to ship a "complete" interface for Kiln inputs. It's always going to be a moving target.
• It's difficult to read. It's a bit harder to tell what is going on with the schema because so much of the schema has low-level concerns like how an HTML input should be formatted.

Proposed Solution

Decoupling the Schema-y bits

I think we should remove everything from schema.yml that is not a schema. I feel the schema should look more like this.

Person:
  name: 
    type: text
    min: 2
    max: 25
  bio:
    required: false
    type: long_text
    min: 0
    max: 999
  tel: 
    type: phone
  email: 
    type: email
  contacts:
    type: has_many
    model: Person
    max_count: 99
    min_count: 0
  company:
    type: has_one
    model: Company
    required: true

• a model has a set of fields.
• each field has a type.
• those types have a additional parameters that depend on the type
  • kiln should have enough about a phone type to generate a generic phone type input.
  • the has_one/has_many type link to references to other components. How this link is maintained is the concern of Amphora and its adapters. It's enough to declare it here without worrying about the implementation.
  • it's each Vue component's responsibility to validate its part of the schema declaration .

With this simpler schema, it's a lot easier to document, validate and extend.

Configuring Kiln?

I feel the Configuration of Kiln is better done imperitavely. My proposal is to expose access to the Vue inputs via a set of facades. These facades wrap the vue components and provide a limited set of methods and event callbacks so a Clay developer has a lot more freedom to modify the kiln inputs without having to know anything about the underlying Vue code.

I think this should be done via a kiln.js file in the component's folder. It would expect to export a callback hook. This hook would provide each input specified in the schema, and make them open to extension via a facade which exposes a limited number of very simple methods. This (very rough) example illustrates this:

import { KilnInput, KilnGroup, MagicButton } from 'kiln-components'


/**
 * Apply custom functionality to Kiln inputs
 * @param {Object} inputs object of input facades attached to the component 
 * corresponding to each property of the schema
 * @param {Object} context information about the URL or whatever data about the 
 * page-level stuff this appears in 
 */
export function(inputs, context) {

  // "wrap" the input 
  // (in practice that might not actually wrap the component but be contained by it)
  // exposed names are automatically converted to camelCase
  const email = new KilnInput(inputs.email)
  const phone = new KilnInput(inputs.phone)

  // yeah, this example's contrived
  const hasFax = new KilnInput(inputs.hasFax)

  // hide the fax input until hasFax is checked
  const fax = new KilnInput(inputs.fax).hide()
  hasFax.onChange((val) => {
    if (val) return fax.show()
    return fax.hide()
  })

  // Apply a magic button to Email
  // pass it's functionality as second arg
  const contactBook = new MagicButton('email', fetchContacts(...))
  
  // Other methods on the facade
  // These methods are chainable (where possible)
  email.onSave()
  email.onChange()
  email.hide()
  email.show()
  email.remove()

  // returns an array of child inputs if has a has_many
  email.children()
  email.parent()


  // Setter/Getter
  email.value

  // direct access to the HTMLElement
  email.html

  // move all contact info into a group & give it the label 'Contacts'
  // show it intially
  const contacts = new KilnGroup([
    email,
    phone,
    hasFax,
    fax
  ], 'Contacts').select()
}

Hopefully this makes schema.yml more readable, the Kiln interface more powerful and readable and allows us to remove a lot of highly business-specific stuff in Kiln that is best left to the Clay instance.

[nelsonpecora]

Schema should contain:

• fields
• field data type (main input)
• label + description
• validation
• static options, as needed
• groups with static fields

Facades (kiln.js) should contain:

• dynamic hide/show logic (_reveal, site specificity, etc)
• dynamic validation logic
• dynamic options (site specific, magic button, etc)
• groups with dynamic fields

Major Changes:

• component readmes (and readme generator scripts) will be removed
• all fields must be specified with a data type in schema (to be saved by kiln/amphora)
• complex _reveal logic will live in kiln.js Bug: Multiple _reveal conditionals #1309 _reveal doesn't work for checkbox-group #1285
• arguments would be strictly validation by the specific input Validate props, 🔪 all args #1300
• most (of not all) magic-button logic would move to kiln.js update and consolidate magic-button api #1294
• instead of _has, all fields would have a type maybe change _has to something more explicit? #1254
• dynamic _placeholder logic (e.g. for groups) would live in kiln.js
• dynamic, complex args would live in kiln.js Allow collapse text to change based on logic #1220

[jonwinton]

This was the center of some Slack discussion and here are the key takeaways:

• Validation would be a great place to start
• We've discussed validation being implemented on the server, we need to discuss how this feature becomes isomorphic and not just a Kiln feature