Open-source platform for 3D AI agents. Turn text or a photo into a rigged, animated GLB avatar, give it an LLM brain, memory and a wallet, and embed it anywhere with one web component. Remote MCP server, x402 payments, Three.js, browser-native.
JavaScript 3d-generationai-agentsanimationavatardigital-humangenerative-aiglbgltfimage-to-3dllmmcpmcp-servermodel-context-protocolsolanatext-to-3dthreejsweb-componentswebglwebxrx402
/**
* Shared list/grid controls toolkit — E03.
*
* One data-source-agnostic toolbar for every browse surface (/discover,
* /marketplace, …): a debounced search input, a sort <select>, filter chip
* segments, and a results count, all URL-synced so views are shareable and the
* browser back/forward button restores them.
*
* The toolkit owns the CHROME (controls + their state + URL plumbing). It does
* NOT fetch — the caller passes an `onChange(state, meta)` callback and runs
* whatever real API it already uses. Loading / empty / error rendering is
* delegated to the shared state-kit so every surface reads as one product.
*
* Two ways to use it:
*
* 1. Controller (full adoption — /discover):
* const lc = createListControls({
* mount: el, segments: [...], sortOptions: [...],
* searchPlaceholder: '…', onChange: (s) => loadPage(s),
* });
* The controller renders the bar, wires events + debounce, syncs the URL,
* and calls onChange whenever the user changes anything (and once on init
* after hydrating from the URL).
*
* 2. Helpers (incremental adoption — surfaces with bespoke markup):
* import { debounce, syncStateToUrl, readStateFromUrl } from './list-controls.js';
* Pure functions a page can drop into its existing wiring without ceding
* control of its DOM.
*
* CSS: ensureListControlsStyles() injects the stylesheet once (idempotent),
* mirroring the state-kit pattern. The bar reuses the canonical design tokens
* — never a parallel palette.
*/
import { ensureStateKitStyles } from './state-kit.js';
const STYLE_ID = 'tws-list-controls-styles';
function esc(s) {
return String(s == null ? '' : s).replace(
/[&<>"']/g,
(c) => ({ '&': '&', '<': '<', '>': '>', '"': '"', "'": ''' })[c],
);
}
/**
* CSS.escape with a safe fallback for environments that don't expose it (older
* runtimes, some test harnesses). Segment keys are author-controlled simple
* identifiers, so the fallback only needs to neutralise selector metacharacters.
*/
function cssEscape(s) {
const str = String(s == null ? '' : s);
if (typeof CSS !== 'undefined' && typeof CSS.escape === 'function') return CSS.escape(str);
return str.replace(/[^a-zA-Z0-9_-]/g, '\\$&');
}
// ── Pure helpers (incremental-adoption surface) ─────────────────────────────
/**
* Trailing-edge debounce. Returns a wrapped fn plus a `.cancel()` to drop any
* pending call (e.g. on teardown or an explicit clear).
* @param {Function} fn
* @param {number} [wait=200]
*/
export function debounce(fn, wait = 200) {
let t;
const wrapped = (...args) => {
clearTimeout(t);
t = setTimeout(() => fn(...args), wait);
};
wrapped.cancel = () => clearTimeout(t);
wrapped.flush = (...args) => {
clearTimeout(t);
fn(...args);
};
return wrapped;
}
/**
* Read a list-view state object from the current URL's querystring.
* Only keys present in `defaults` are read; anything else is ignored so a page
* never picks up stray params. Values are coerced to the type of their default.
*
* @param {Record<string, string|null>} defaults e.g. { q:'', sort:'newest', chain:'' }
* @param {URLSearchParams} [params]
* @returns {Record<string, string>}
*/
export function readStateFromUrl(defaults, params = new URLSearchParams(location.search)) {
const out = {};
for (const key of Object.keys(defaults)) {
const v = params.get(key);
out[key] = v == null ? defaults[key] : v;
}
return out;
}
/**
* Reflect a state object into the URL. Keys whose value equals the matching
* `defaults` entry are dropped (canonical short URLs). Uses replaceState by
* default to avoid history spam on each keystroke; pass push:true for
* user-meaningful changes (chip click, sort change) so back/forward step
* through them.
*
* @param {Record<string, string>} stateObj
* @param {Record<string, string|null>} defaults
* @param {{ push?: boolean }} [opts]
*/
export function syncStateToUrl(stateObj, defaults, { push = false } = {}) {
const url = new URL(location.href);
for (const key of Object.keys(defaults)) {
const val = stateObj[key];
if (val == null || val === '' || val === defaults[key]) url.searchParams.delete(key);
else url.searchParams.set(key, String(val));
}
if (url.href === location.href) return;
if (push) history.pushState({}, '', url);
else history.replaceState({}, '', url);
}
// ── CSS injection ───────────────────────────────────────────────────────────
/** Inject the list-controls stylesheet once. Idempotent and SSR-safe. */
export function ensureListControlsStyles() {
if (typeof document === 'undefined') return;
ensureStateKitStyles(); // controls live alongside state-kit empty/error blocks
if (document.getElementById(STYLE_ID)) return;
const style = document.createElement('style');
style.id = STYLE_ID;
style.textContent = LIST_CONTROLS_CSS;
(document.head || document.documentElement).appendChild(style);
}
// ── Controller ──────────────────────────────────────────────────────────────
/**
* @typedef {Object} Segment
* @property {string} key state key this segment writes to (e.g. 'filter', 'source')
* @property {string} [label] optional group label (visually hidden, used for aria-label)
* @property {Array<{value:string,label:string}>} options
*
* @typedef {Object} ListControlsConfig
* @property {Element} mount container the bar renders into
* @property {string} [searchKey='q'] state key the search input writes to
* @property {string} [searchPlaceholder]
* @property {string} [searchLabel='Search']
* @property {Array<{value:string,label:string}>} [sortOptions]
* @property {string} [sortKey='sort']
* @property {Segment[]} [segments]
* @property {Record<string,string>} [defaults] default value per state key
* @property {number} [debounceMs=200]
* @property {boolean} [urlSync=true] when false the toolkit never touches the
* URL — the caller owns it (e.g. a page with a legacy/custom query scheme).
* Hydration from the URL still happens via `hydrate`.
* @property {(params:URLSearchParams, defaults:Record<string,string>) => Record<string,string>} [hydrate]
* custom reader for the initial state (defaults to readStateFromUrl).
* @property {(state:Record<string,string>, meta:{reason:string}) => void} onChange
*/
/**
* Build and wire a list-controls bar. Returns a handle exposing the live state,
* imperative setters, and a teardown.
* @param {ListControlsConfig} config
*/
export function createListControls(config) {
ensureListControlsStyles();
const {
mount,
searchKey = 'q',
searchPlaceholder = 'Search…',
searchLabel = 'Search',
sortOptions = [],
sortKey = 'sort',
segments = [],
debounceMs = 200,
urlSync = true,
hydrate,
onChange,
} = config;
if (!mount) throw new Error('createListControls: mount element is required');
// Assemble the full default map: search + sort + every segment's first option.
const defaults = { [searchKey]: '', ...(config.defaults || {}) };
if (sortOptions.length && !(sortKey in defaults)) defaults[sortKey] = sortOptions[0].value;
for (const seg of segments) {
if (!(seg.key in defaults)) defaults[seg.key] = seg.options[0]?.value ?? '';
}
// Hydrate from URL so deep links + back/forward restore filters. A page with
// a custom/legacy query scheme supplies its own reader via `hydrate`.
const readState = (params) =>
hydrate ? hydrate(params, defaults) : readStateFromUrl(defaults, params);
const state = readState(new URLSearchParams(location.search));
mount.classList.add('tws-lc');
mount.innerHTML = buildBarHTML({
state,
searchKey,
searchPlaceholder,
searchLabel,
sortOptions,
sortKey,
segments,
});
const $ = (sel) => mount.querySelector(sel);
const searchInput = $('[data-lc="search"]');
const searchClear = $('[data-lc="search-clear"]');
const sortSelect = $('[data-lc="sort"]');
const countEl = $('[data-lc="count"]');
const emit = (reason, push) => {
if (urlSync) syncStateToUrl(state, defaults, { push });
onChange?.({ ...state }, { reason });
};
// ── Search (debounced) ──
const runSearch = debounce(() => {
const next = searchInput.value.trim();
if (next === state[searchKey]) return;
state[searchKey] = next;
emit('search', false);
}, debounceMs);
if (searchInput) {
searchInput.addEventListener('input', () => {
updateClearVisibility();
runSearch();
});
// Enter flushes immediately (don't make the user wait out the debounce).
searchInput.addEventListener('keydown', (e) => {
if (e.key === 'Enter') {
e.preventDefault();
runSearch.flush();
}
});
}
searchClear?.addEventListener('click', () => {
searchInput.value = '';
state[searchKey] = '';
updateClearVisibility();
runSearch.cancel();
emit('search-clear', true);
searchInput.focus();
});
// ── Sort ──
sortSelect?.addEventListener('change', () => {
state[sortKey] = sortSelect.value;
emit('sort', true);
});
// ── Segment chips (delegated, survives nothing — bar is built once) ──
mount.addEventListener('click', (e) => {
const chip = e.target.closest('[data-lc-seg]');
if (!chip) return;
const key = chip.dataset.lcSeg;
const value = chip.dataset.lcValue;
if (state[key] === value) return;
state[key] = value;
for (const c of mount.querySelectorAll(`[data-lc-seg="${cssEscape(key)}"]`)) {
const active = c.dataset.lcValue === value;
c.classList.toggle('active', active);
c.setAttribute('aria-pressed', active ? 'true' : 'false');
}
emit('segment', true);
});
// ── Keyboard arrow nav within a chip group ──
mount.addEventListener('keydown', (e) => {
if (e.key !== 'ArrowRight' && e.key !== 'ArrowLeft') return;
const chip = e.target.closest('[data-lc-seg]');
if (!chip) return;
const group = chip.closest('[data-lc-seg-group]');
if (!group) return;
const chips = [...group.querySelectorAll('[data-lc-seg]')];
const i = chips.indexOf(chip);
const next = e.key === 'ArrowRight' ? chips[i + 1] : chips[i - 1];
if (next) {
e.preventDefault();
next.focus();
}
});
function updateClearVisibility() {
if (searchClear) searchClear.hidden = !searchInput.value;
}
updateClearVisibility();
// Restore on popstate so back/forward re-hydrate the bar + re-run onChange.
const onPop = () => {
const restored = readState(new URLSearchParams(location.search));
Object.assign(state, restored);
syncControlsToState();
onChange?.({ ...state }, { reason: 'popstate' });
};
window.addEventListener('popstate', onPop);
function syncControlsToState() {
if (searchInput) searchInput.value = state[searchKey] || '';
updateClearVisibility();
if (sortSelect) sortSelect.value = state[sortKey] ?? sortSelect.value;
for (const seg of segments) {
for (const c of mount.querySelectorAll(`[data-lc-seg="${cssEscape(seg.key)}"]`)) {
const active = c.dataset.lcValue === state[seg.key];
c.classList.toggle('active', active);
c.setAttribute('aria-pressed', active ? 'true' : 'false');
}
}
}
syncControlsToState();
return {
/** Current state snapshot (copy). */
getState: () => ({ ...state }),
/** True when any control differs from its default (drives "clear filters"). */
isFiltered: () => Object.keys(defaults).some((k) => state[k] !== defaults[k]),
/** Programmatically reset every control to its default and re-emit. */
reset: () => {
Object.assign(state, defaults);
runSearch.cancel();
syncControlsToState();
emit('reset', true);
},
/** Set the visible results count (or hide it with null/''). */
setCount: (text) => {
if (!countEl) return;
countEl.textContent = text || '';
countEl.hidden = !text;
},
/** Fire onChange once after wiring (callers that don't want an init call skip this). */
emitInitial: () => onChange?.({ ...state }, { reason: 'init' }),
destroy: () => {
runSearch.cancel();
window.removeEventListener('popstate', onPop);
},
};
}
// ── Bar markup ───────────────────────────────────────────────────────────────
function buildBarHTML({ state, searchKey, searchPlaceholder, searchLabel, sortOptions, sortKey, segments }) {
const searchVal = esc(state[searchKey] || '');
const searchHTML = `
<div class="tws-lc-search">
<svg class="tws-lc-search-icon" width="15" height="15" viewBox="0 0 16 16" fill="none" aria-hidden="true">
<circle cx="7" cy="7" r="5" stroke="currentColor" stroke-width="1.5"/>
<path d="M11 11l3 3" stroke="currentColor" stroke-width="1.5" stroke-linecap="round"/>
</svg>
<input type="search" data-lc="search" value="${searchVal}"
placeholder="${esc(searchPlaceholder)}" aria-label="${esc(searchLabel)}"
autocomplete="off" spellcheck="false" />
<button type="button" class="tws-lc-search-clear" data-lc="search-clear"
aria-label="Clear search"${searchVal ? '' : ' hidden'}>
<svg width="12" height="12" viewBox="0 0 12 12" fill="none" aria-hidden="true">
<path d="M2 2l8 8M10 2l-8 8" stroke="currentColor" stroke-width="1.6" stroke-linecap="round"/>
</svg>
</button>
</div>`;
const segmentsHTML = segments
.map((seg) => {
const active = state[seg.key];
const chips = seg.options
.map((o) => {
const on = o.value === active;
return `<button type="button" class="tws-lc-chip${on ? ' active' : ''}"
data-lc-seg="${esc(seg.key)}" data-lc-value="${esc(o.value)}"
aria-pressed="${on ? 'true' : 'false'}">${esc(o.label)}</button>`;
})
.join('');
return `<div class="tws-lc-chips" role="group"${seg.label ? ` aria-label="${esc(seg.label)}"` : ''} data-lc-seg-group>${chips}</div>`;
})
.join('');
const sortHTML = sortOptions.length
? `<div class="tws-lc-sort">
<label class="tws-lc-sort-label" for="tws-lc-sort-${esc(sortKey)}">Sort</label>
<div class="tws-lc-select">
<select id="tws-lc-sort-${esc(sortKey)}" data-lc="sort" aria-label="Sort results">
${sortOptions
.map(
(o) =>
`<option value="${esc(o.value)}"${o.value === state[sortKey] ? ' selected' : ''}>${esc(o.label)}</option>`,
)
.join('')}
</select>
<svg class="tws-lc-select-caret" width="11" height="7" viewBox="0 0 12 8" fill="none" aria-hidden="true">
<path d="M1 1.5L6 6.5L11 1.5" stroke="currentColor" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round"/>
</svg>
</div>
</div>`
: '';
return `
<div class="tws-lc-row tws-lc-row--primary">
${searchHTML}
${sortHTML}
</div>
${segmentsHTML ? `<div class="tws-lc-row tws-lc-row--segments">${segmentsHTML}</div>` : ''}
<div class="tws-lc-count" data-lc="count" role="status" aria-live="polite" hidden></div>`;
}
// ── CSS ───────────────────────────────────────────────────────────────────────
const LIST_CONTROLS_CSS = `
/* ═══════════════════════════════════════════════════════════════════════════
three.ws list-controls — shared search / sort / filter toolbar (E03)
Source: src/shared/list-controls.js · Namespace: tws-lc-*
Token-driven only; no parallel palette.
═══════════════════════════════════════════════════════════════════════════ */
.tws-lc {
display: flex;
flex-direction: column;
gap: var(--space-sm, 0.618rem);
}
.tws-lc-row {
display: flex;
align-items: center;
gap: var(--space-sm, 0.618rem);
flex-wrap: wrap;
}
.tws-lc-row--segments { gap: var(--space-md, 1rem); }
/* ── Search ── */
.tws-lc-search {
position: relative;
flex: 1 1 260px;
min-width: 0;
display: flex;
align-items: center;
}
.tws-lc-search-icon {
position: absolute;
left: 12px;
color: var(--ink-dim, #888);
pointer-events: none;
}
.tws-lc-search input {
width: 100%;
padding: 9px 34px 9px 34px;
background: var(--surface-1, rgba(255,255,255,0.03));
border: 1px solid var(--stroke, rgba(255,255,255,0.08));
border-radius: var(--radius-md, 10px);
color: var(--ink, #e8e8e8);
font: var(--weight-medium, 500) var(--text-md, 13px)/1.2 var(--font-body, system-ui, sans-serif);
transition: border-color var(--duration-fast, 140ms) var(--ease-standard, ease),
background var(--duration-fast, 140ms) var(--ease-standard, ease);
}
.tws-lc-search input::placeholder { color: var(--ink-faint, rgba(255,255,255,0.45)); }
.tws-lc-search input:hover { border-color: var(--stroke-strong, rgba(255,255,255,0.14)); }
.tws-lc-search input:focus-visible,
.tws-lc-search input:focus {
outline: none;
border-color: var(--accent, #fff);
background: var(--surface-2, rgba(255,255,255,0.05));
}
.tws-lc-search input[type='search']::-webkit-search-cancel-button {
-webkit-appearance: none;
appearance: none;
}
.tws-lc-search-clear {
position: absolute;
right: 7px;
width: 22px;
height: 22px;
display: grid;
place-items: center;
border: 0;
border-radius: var(--radius-pill, 999px);
background: var(--surface-3, rgba(255,255,255,0.08));
color: var(--ink-dim, #888);
cursor: pointer;
transition: background var(--duration-fast, 140ms) var(--ease-standard, ease),
color var(--duration-fast, 140ms) var(--ease-standard, ease);
}
.tws-lc-search-clear:hover { background: var(--surface-3, rgba(255,255,255,0.12)); color: var(--ink, #e8e8e8); }
.tws-lc-search-clear:focus-visible {
outline: var(--focus-ring-width, 2px) solid var(--focus-ring-color, #fff);
outline-offset: var(--focus-ring-offset, 2px);
}
/* ── Chips / segments ── */
.tws-lc-chips {
display: inline-flex;
gap: var(--space-2xs, 0.236rem);
flex-wrap: wrap;
}
.tws-lc-chip {
padding: 7px 13px;
background: transparent;
border: 1px solid var(--stroke-strong, rgba(255,255,255,0.14));
border-radius: var(--radius-sm, 6px);
color: var(--ink-dim, #888);
font: var(--weight-medium, 500) var(--text-md, 13px)/1 var(--font-body, system-ui, sans-serif);
cursor: pointer;
white-space: nowrap;
transition: border-color var(--duration-fast, 140ms) var(--ease-standard, ease),
color var(--duration-fast, 140ms) var(--ease-standard, ease),
background var(--duration-fast, 140ms) var(--ease-standard, ease);
}
.tws-lc-chip:hover { border-color: var(--stroke-strong, rgba(255,255,255,0.28)); color: var(--ink, #e8e8e8); }
.tws-lc-chip.active {
background: var(--surface-3, rgba(255,255,255,0.10));
border-color: var(--accent, rgba(255,255,255,0.4));
color: var(--ink-bright, #fff);
}
.tws-lc-chip:focus-visible {
outline: var(--focus-ring-width, 2px) solid var(--focus-ring-color, #fff);
outline-offset: var(--focus-ring-offset, 2px);
}
/* ── Sort select ── */
.tws-lc-sort {
display: inline-flex;
align-items: center;
gap: var(--space-xs, 0.382rem);
color: var(--ink-dim, #888);
font-size: var(--text-md, 13px);
flex-shrink: 0;
}
.tws-lc-sort-label { color: var(--ink-dim, #888); }
.tws-lc-select { position: relative; display: inline-flex; align-items: center; }
.tws-lc-select select {
appearance: none;
-webkit-appearance: none;
padding: 8px 30px 8px 11px;
background: var(--surface-2, rgba(255,255,255,0.05));
border: 1px solid var(--stroke-strong, rgba(255,255,255,0.14));
border-radius: var(--radius-md, 10px);
color: var(--ink, #e8e8e8);
font: var(--weight-medium, 500) var(--text-md, 13px)/1 var(--font-body, system-ui, sans-serif);
cursor: pointer;
transition: background var(--duration-fast, 140ms) var(--ease-standard, ease),
border-color var(--duration-fast, 140ms) var(--ease-standard, ease);
}
.tws-lc-select select:hover { background: var(--surface-3, rgba(255,255,255,0.08)); border-color: var(--stroke-strong, rgba(255,255,255,0.28)); }
.tws-lc-select select:focus-visible {
outline: var(--focus-ring-width, 2px) solid var(--focus-ring-color, #fff);
outline-offset: var(--focus-ring-offset, 2px);
}
.tws-lc-select select option { background: var(--bg-1, #1a1a1a); color: var(--ink, #e6e6e6); }
.tws-lc-select-caret {
position: absolute;
right: 10px;
color: var(--ink-dim, #888);
pointer-events: none;
}
/* ── Result count ── */
.tws-lc-count {
font-size: var(--text-sm, 12px);
color: var(--ink-dim, #888);
font-variant-numeric: tabular-nums;
}
@media (max-width: 600px) {
.tws-lc-row--primary { flex-direction: column; align-items: stretch; }
.tws-lc-sort { justify-content: space-between; }
.tws-lc-select select { flex: 1; }
}
`;
if (typeof window !== 'undefined') {
window.twsListControls = {
createListControls,
debounce,
readStateFromUrl,
syncStateToUrl,
ensureListControlsStyles,
};
}