quick-reference.md

title
Quick Reference

Quick Reference

Terminology

Term	Meaning
combinator	A function intended to be combined with other functions via composition.
pipe	An array of synchronous functions (that will be composed using pipe).
flow	An array of (possibly) asynchronous functions (that will be composed using flow).
input(s)	A value (or values) passed into combinator.
component	A Web Component or Custom Element.
handle	An object that encapsulates a component.

Handle Class

Properties

Name	Description
root	If the component is a Web Component, refers to shadow, otherwise refers to dom.
dom	A reference to the component itself.
shadow	A reference to the component’s shadow DOM, if applicable. May be defined using the shadow initialization combinator.
html	Reflects the component’s innerHTML property. The diff initialization combinator redefines this to perform a diff instead of setting innerHTML directly.

Methods

Name	Arguments	Description
on	name, handler	Define an event handler using addEventListener for the named event.
dispatch	name, detail	Dispatch the named event using dispatchEvent for the named event, with optional detail property.

Mixin Combinators

Mixin combinators are “top-level” combinators that “mixin” features into the Handle. You can use the mixin function for this:

class extends Handle
  c.mixin @, [
    c.tag "x-greeting"
    # ... more mixins ...
  ]

(Handles may be anonymous classes since they’re only instantiated by a Custom Element, never directly.)

Name	Arguments	Description
connect	pipe	Define the handler for the connectedCallback.
diff	-	Defines (or overrides) the html property that updates the DOM using a diff algorithm.
disconnect	pipe	Define the handler for the disconnectedCallback. [Not yet implemented.]
initialize	pipe	Defines the handler for the handle construction. Called once during the component lifecycle.
tag	name	Defines the custom element class and registers it with the tag name.

Initialize Combinators

Initialize combinators can be used with the initialize or connect mixin combinators. Iniitalize combinators are always synchronous.

Name	Arguments	Description
activate	flow	Defines a handler for activation, when the component becomes visible in the viewport.
click	selector, flow	Defines a handler for a click event targeting the given selector. Convenience combinator.
deactivate	flow	Defines a handler for deactivation, when the component is no longer visible in the viewport.
describe	flow	Defines a handler for changes to the component's dataset. The component’s description (an object corresponding to the component’s dataset) is passed into the flow.
event	name, pipe	Defines a handler for the named event, ex: click. Uses event delegation.
navigate	name, flow	Define a handler for window navigation (popstate events).
observe	name, flow	Defines and observes the named property in the handle. Defines a handler for changes.
ready	-	Defines a handler for when initialization is complete. Useful for adding asynchronous actions into initialization, such as render.
shadow	-	Create a shadowRoot for the component, accessible via the handle shadow property.
submit	select, flow

Action Combinators

Action combinators are typically used within flows in response to events. Action combinators may be synchronous or asynchronous. The event loop yields after each action regardless. However, synchronous combinators may be used as initializers.

Name	Arguments	Type	Description
assign	name	sync	Assign (via Object.assign the input to the named property.
call	function	async	Call the function, with this bound to the handle.
description	-	sync	Returns the component description (an object corresponding to the component’s dataset).
disable	-	sync	Disable all enabled form inputs.
dispatch	name	sync	Dispatch an event from the component.
enable	-	sync	Enable all disabled form inputs.
form	-	sync	Returns an object corresponding to the component FormData.
get	name	async	Returns the value of the named property.
render	template	async	Render the element to the DOM using the given template. The template takes the handle instance and returns an HTML string.
reset	-	sync	Resets the component form inputs.
set	name	sync	Sets the named property to the input.
sheet	dictionary, css	sync	Applies a dictionary of named stylesheets (CSS or Stylesheet objects) to the component. (Named stylesheets allow you to add and remove stylesheets in without recompling them.)

Event Combinators

Event combinators are used to compose event handlers. A common pattern is to test if the event target is contained by an element with a given selector and run a flow.

c.event "click", [
  c.within "h1", [
	  c.intercept
    c.call ->
      @greeting = if @greeting == "Hello" then "Goodbye" else "Hello"
  ]
]

Name	Arguments	Description
intercept	-	Convenience combinator for prevent and stop.
matches	selector, pipe	Invokes the given flow only if the target matches the selector.
within	selector, pipe	Invokes the given flow only if an ancestor of the target matches the selector.
prevent	-	Calls preventDefault on the input event.
stop	-	Calls stopPropagation on the input event.
target	-	Returns the event target.