treeloom-components
    Preparing search index...

    treeloom-components

    treeloom-components

    A minimal component library on treeloom: a set of base HTML element factories, plus richer interactive components built on top of them.

    Three projects (quizzes, workout-planner, the website) had each grown their own, slightly-diverged copy of the same small set of "build a <div>/<input>/<label>/..." treeloom factory functions. This package is those functions ported into one place and reconciled, plus a home for new, richer components none of those projects had yet - starting with a typeahead.

    This is a POC/starter package: only what's needed for the components below. A later pass can round out anything missing (sass theming, more components, a render-only/forwarding-safe listener registry) once a real need for it shows up.

    Thin wrappers around treeloom.createDomItem, one function per real HTML element: anchor, button, div, element (the one every other wrapper builds on), fieldset, footer, form, header, heading, input, label, legend, listItem, main, nav, node (the actual base, wraps createDomItem directly), option, paragraph, radio, select, span, style, submit, table/tableBody/tableData/tableHead/ tableHeading/tableRow, text, textArea, unorderedList.

    Each one returns a DomItem - compose them the same way you would real HTML, then render with treeloom's own renderHtml/documentDomItem as usual.

    createTypeahead({ name, options, value?, placeholder?, label?, className?, readonly? }) builds a filterable select: a free-type input you type into to filter a list of options, and the real <select> (hidden until there's a match) that holds the actual submitted value. The open list holds only the matches. Picking an option copies its label back into the free-type input and collapses the list again.

    • Pointer: click a match. On a phone, the browser's own picker works too.
    • Keys: Down arrow (or Tab) moves into the list, arrows move the highlight, Enter picks, Escape closes the list without picking. Moving between the input and the list keeps it open; focus leaving the whole typeahead closes it.
    • The submitted value is only ever a real pick: untouched, it submits '' (a hidden, empty first option), and editing the text after a pick un-picks it. A highlight is not a pick: closing the list puts the last pick back.
    • label names the input (aria-label) and the list ("<label> matches"). Leave it out when the page labels the input itself.

    Ported from a PHP Blade reference implementation - same two-field shape, same filtering rule (case-insensitive match on value or label text, list only expands once 2+ characters are typed and something matches) - but wired through treeloom's own eventListeners (bound automatically wherever the component gets rendered) instead of attaching to the real DOM by hand.

    Known POC limitation: the typeahead's listeners are plain closures (listenerFunc set directly to a function), not names registered through treeloom's registerListener. That's fine for a component rendered and used locally, but it means this component's events can't currently be forwarded across treeloom's render-only/socket mode (see Cloakfall's own remote play for what that mode looks like) - revisit if a consumer ever needs that.

    Include styles/typeahead.css for the dropdown positioning - the show/hide behaviour itself needs no CSS, it's the native hidden attribute.

    createClearableInput({ name, value?, placeholder?, className?, readonly? }) builds the common "search box" pattern: a regular text input with a small "×" button on its right inner edge that clears it. The button only shows once there's a value to clear (toggled on the input's own input event), and clicking it empties the field and gives it focus back.

    Same POC limitation as the typeahead: plain closures for its listeners, not registered names - fine locally, not yet forwarding-safe.

    Include styles/clearableInput.css for the button's positioning.

    treeloom is a peer dependency (the components are treeloom items, so there must be exactly one copy of treeloom), so install it too:

    npm install treeloom treeloom-components
    

    The stylesheets are in the package's styles/ folder (styles/typeahead.css, styles/clearableInput.css). It is written in TypeScript and ships its types.