Frontend Cheatsheet

Quick reference for the Fullfinity frontend framework.

Setup

Module Structure

my_module/
└── static/
    └── src/
        └── js/
            └── components.js    # Your components here

Components are auto-loaded based on module dependencies.

Components

Register a Component

const { registry, html, useState } = window.fullfinity;

registry.component('MyComponent', function({ prop1, prop2 }) {
  const [state, setState] = useState(initialValue);

  return html`
    <div class="my-component">
      ${prop1}
    </div>
  `;
});

Use in Template (Jinja2)

<div
  data-component="MyComponent"
  data-props='{"prop1": "value", "prop2": {{ variable | tojson }}}'
></div>

HTML Template Syntax

const { html } = window.fullfinity;

// Elements
html`<div class="container">Content</div>`

// Expressions
html`<span>${value}</span>`

// Events
html`<button onClick=${handleClick}>Click</button>`

// Conditional
html`${condition && html`<div>Shown</div>`}`
html`${condition ? html`<div>A</div>` : html`<div>B</div>`}`

// Lists
html`<ul>${items.map(i => html`<li key=${i.id}>${i.name}</li>`)}</ul>`

// Nested components
html`<${ChildComponent} prop="value" />`

// Refs
html`<input ref=${inputRef} />`

Hooks

const {
  useState,      // Local state
  useEffect,     // Side effects
  useRef,        // Mutable ref
  useCallback,   // Memoized callback
  useMemo,       // Memoized value
  useStore,      // Access store
  useSlot,       // Access slot (re-renders on change)
  useLifecycle,  // Lifecycle callbacks
} = window.fullfinity;

useState

const [value, setValue] = useState(initial);
setValue(newValue);                    // Direct
setValue(prev => prev + 1);            // Functional

useEffect

// Run on every render
useEffect(() => { /* ... */ });

// Run once on mount
useEffect(() => {
  // setup
  return () => { /* cleanup */ };
}, []);

// Run when deps change
useEffect(() => { /* ... */ }, [dep1, dep2]);

useRef

const ref = useRef(initialValue);
ref.current = newValue;  // Mutable, doesn't trigger re-render

// DOM ref
const inputRef = useRef(null);
html`<input ref=${inputRef} />`;
inputRef.current.focus();

useLifecycle

const { useLifecycle } = window.fullfinity;

useLifecycle({
  onMounted: () => console.log('Mounted'),
  onUpdated: () => console.log('Updated'),
  onWillUnmount: () => console.log('Unmounting')
});

Stores

Create Store

const { registry, bus } = window.fullfinity;

registry.store('cart', {
  items: [],
  add(item) {
    this.items.push(item);
    fullfinity.notifyStore('cart');  // Trigger re-renders
    bus.emit('cart:updated');         // Notify listeners
  }
});

Use Store

const { useStore } = window.fullfinity;
const cart = useStore('cart');
cart.add({ id: 1, name: 'Product' });

Event Bus

const { bus } = window.fullfinity;

// Subscribe
const unsubscribe = bus.on('event:name', (data) => { });

// Emit
bus.emit('event:name', { key: 'value' });

// Unsubscribe
unsubscribe();

// Once
bus.once('event:name', (data) => { });

Patching

Wrap Component

const { patch, html } = window.fullfinity;

patch('ExistingComponent', (Original) => function(props) {
  return html`
    <div class="wrapper">
      <${Original} ...${props} />
      <div>Extra content</div>
    </div>
  `;
}, { id: 'my-wrapper' });

With Priority & Conditions

patch('Component', patcher, {
  id: 'my-patch',           // Required for unpatch/after
  priority: 20,             // Lower runs first (default: 10)
  after: 'other-patch',     // Run after this patch
  when: () => condition     // Only apply if true
});

Modify Props

patch('Component', (Original) => function(props) {
  const modifiedProps = { ...props, newProp: 'value' };
  return html`<${Original} ...${modifiedProps} />`;
}, { id: 'props-modifier' });

Remove Patch

const { unpatch } = window.fullfinity;
unpatch('Component', 'my-patch');

Method Patching

const { patchMethod, unpatchMethod } = window.fullfinity;

// Multiple patches stack in priority order
patchMethod('CartWidget', 'computeTotal', function(_super, items) {
  return _super(items) * 0.9;  // 10% discount
}, { id: 'discount', priority: 10 });

patchMethod('CartWidget', 'computeTotal', function(_super, items) {
  return _super(items) + 5;  // Add shipping (runs after discount)
}, { id: 'shipping', priority: 20 });

// Remove a method patch
unpatchMethod('CartWidget', 'computeTotal', 'discount');

Extension Slots

Define Slot (in component)

const { useSlot } = window.fullfinity;

registry.component('ProductCard', function(props) {
  // useSlot re-renders when addons register
  const extras = useSlot('ProductCard:afterPrice');
  return html`
    <div class="product">
      <span class="price">${props.price}</span>
      ${extras.map(C => html`<${C} ...${props} />`)}
    </div>
  `;
});

Register into Slot

registry.slot('ProductCard:afterPrice', LoyaltyBadge, {
  priority: 10,
  id: 'loyalty',
  when: () => userHasLoyalty
});

Remove from Slot

registry.removeSlot('ProductCard:afterPrice', 'loyalty');

Common Patterns

Fetch Data

registry.component('DataList', function({ endpoint }) {
  const { useState, useEffect, html } = window.fullfinity;
  const [data, setData] = useState(null);
  const [loading, setLoading] = useState(true);

  useEffect(() => {
    fetch(endpoint)
      .then(r => r.json())
      .then(setData)
      .finally(() => setLoading(false));
  }, [endpoint]);

  if (loading) return html`<div>Loading...</div>`;
  return html`<ul>${data.map(i => html`<li>${i.name}</li>`)}</ul>`;
});

Form Handling

registry.component('Form', function({ onSubmit }) {
  const { useState, html } = window.fullfinity;
  const [value, setValue] = useState('');

  function handleSubmit(e) {
    e.preventDefault();
    onSubmit(value);
  }

  return html`
    <form onSubmit=${handleSubmit}>
      <input
        value=${value}
        onInput=${e => setValue(e.target.value)}
      />
      <button type="submit">Submit</button>
    </form>
  `;
});

Conditional Classes

html`<div class=${'base ' + (active ? 'active' : '')}>...</div>`
html`<div class=${['base', active && 'active'].filter(Boolean).join(' ')}>...</div>`

API Reference

Registry

registry.component('Name', fn)    // Register
registry.component('Name')        // Get
registry.getOriginal('Name')      // Get unpatched original
registry.hasComponent('Name')     // Check
registry.listComponents()         // List all

registry.store('name', obj)       // Register
registry.store('name')            // Get
registry.hasStore('name')         // Check
registry.listStores()             // List all

registry.slot('Name:slot', Comp, opts)  // Register into slot
registry.getSlot('Name:slot')           // Get slot components
registry.removeSlot('Name:slot', id)    // Remove from slot
registry.listSlots('Name')              // List slots

Data (server API)

// Primitive — use for bespoke, access-controlled routes (/help/…, /shop/api/…, /blog/…)
api.request(path, { method, body, headers, ...fetchOptions })  // JSON request → parsed body (or null)

// Model-endpoint helpers (all built on api.request)
api.fetch(model, id, { fields })              // Read one record by id
api.query(model, { filter, fields, limit, offset, order })  // Query records → { records, total }
api.create(model, data, { ctx, fields })      // Create a record → created record
api.update(model, id, data, { ctx, fields })  // Update a record → updated record
api.execute(model, method, { ids, args })     // Call a model method → result
api.delete(model, id)                         // Delete a record by id

Use these instead of hand-rolling fetch(). api.request sets JSON headers, serializes the body, throws an Error (with the server’s message) on a non-2xx response, and returns the parsed JSON. It passes extra fetch options straight through — e.g. api.request(url, { credentials: 'omit' }) for a public route. The model helpers hit the internal-user record endpoints; for the public portal or storefront, call api.request against your own access-controlled route (which enforces contact/session scoping), not the generic model endpoints.

// bespoke route example
const items = await api.request('/help/suggest?q=' + encodeURIComponent(q), { credentials: 'omit' });
await api.request('/shop/api/cart/add', { method: 'POST', body: { variant_id, qty } });

Toasts

// Pick an intent — colour, icon and duration come with it. Never hand-roll a toast.
toast.success(message, title?)   // 4s   toast.warning(message, title?)  // 6s
toast.error(message, title?)     // 8s   toast.info(message, title?)     // 5s
toast.neutral(message, title?)   // 4s

toast.show({ type, title, message, duration })  // intent decided at runtime; → { close }

See Components → Toasts.

Bottom chrome

// Bars pinned to the bottom edge STACK. Lower order sits closer to the edge:
// an ecommerce buy bar claims 0, the website admin toolbar claims 10.
const release = bottomChrome.claim(el, { order: 0 });   // → () => void
bottomChrome.release(el);                               // or release explicitly
bottomChrome.measure();                                 // recompute now (rarely needed)

Read in CSS — always with the 0px fallback, since both properties are absent when nothing is claimed:

.my-bar      { bottom: var(--ff-chrome-offset, 0px); }              /* in the stack */
.my-launcher { bottom: calc(1rem + var(--ff-bottom-chrome, 0px)); } /* floating above it */

See Components → Bottom Chrome.

PinInput

// One box per character for a short code. Controlled: `value` is the whole string.
html`<${PinInput} label="Verification code" length=${6} value=${code}
                  onInput=${setCode} onComplete=${submit} />`

See Components → PinInput.

Patching

fullfinity.patch('Name', fn, opts)            // Patch component
fullfinity.unpatch('Name', 'patch-id')        // Remove patch
fullfinity.patchMethod('Name', 'method', fn, opts)  // Patch method
fullfinity.unpatchMethod('Name', 'method', 'id')    // Remove method patch
fullfinity.listPatches('Name')                // List patch IDs
fullfinity.listMethodPatches('Name', 'method')     // List method patch IDs

Mounting

fullfinity.mountAll()              // Mount all registered components
fullfinity.mountComponent('Name')  // Mount specific component
fullfinity.unmount(element)        // Unmount from element

Utilities

fullfinity.notifyStore('name')     // Trigger store re-renders
fullfinity.bus.on/emit/off/once    // Event bus

Debugging

// In browser console
window.fullfinity.registry.listComponents()  // See all components
window.fullfinity.registry.listStores()      // See all stores
window.fullfinity.registry.store('cart')     // Inspect store

// Check if component exists
window.fullfinity.registry.hasComponent('ProductCard')

// Inspect patches
window.fullfinity.listPatches('ProductCard')        // See patch IDs
window.fullfinity.registry.getOriginal('ProductCard')  // Get unpatched

// Inspect slots
window.fullfinity.registry.listSlots('ProductCard')  // See slots
window.fullfinity.registry.getSlot('ProductCard:afterPrice')  // Get slot contents