internetarchive / internetarchive/query-shaper

Support imperative/headless generation without a real Target element

Open
#30 0 comments 0 reactions 0 assignees View on GitHub
ready-for-agent
Dominant language
TypeScript
Stars
1
Forks
0
PR merge metrics
No merged PRs in 30d

Description

## Problem Statement

`` currently requires a real Target (`for="..."` pointing at
an ``/``) to do anything at all — session establishment
happens on the Target's `focus`, and generation is triggered by the
Target's `input` event, reading `this.target.value` as the Search Text.
There's no way to ask a headless instance for Suggestions against
arbitrary text without wiring up a real DOM input element, even when the
text is coming from somewhere else entirely (a chat message, a
programmatic call, a value that was never typed into any input at all).

## Proposed Solution

A new public method, e.g. `generate(text: string): void`, that triggers
the same generation pipeline `#generateInner` already runs, but takes the
text as a parameter instead of reading `this.target.value`. Emits the
same `query-shaper-generating`/`query-shaper-suggestions`/
`query-shaper-error` events as today. Reuses the existing session
lifecycle, debounce (or bypasses it, since an explicit call already
signals intent), and Suggestion-parsing machinery as-is.

Purely additive: no `for=`-driven behavior changes, this just adds a
second entry point for the same generation pipeline. A `<query-shaper>`
instance could be used with a real Target as today, or headless and
Target-less, driven entirely by JS.

## Motivation

Came up while discussing extracting the docs page's Q&A feature into an
independent chat component — a chat widget wants to hand arbitrary
message text to something for suggestion/keyword-style generation
without having a real search input in the picture at all.

Status: Not yet implemented. Filed to track for whenever this is
prioritized — not urgent, no current blocker.

Contributor guide

No contributing guide indexed for this repository

Research direction

Start by tracing the existing #generateInner pipeline and the Target focus/input event handlers that establish sessions and read search text. Add the public text-driven entry point without changing for= behavior, and verify that it emits the existing generating, suggestions, and error events for headless and Target-backed use.

Written by the indexing model from the issue text.

Assessment

Tech stack
typescript
Domain
frontend
Issue type
Feature
Difficulty
3/5
Estimated time
1-2 days
Activity status
Quiet
Clarity
Mostly clear
Newbie friendliness
55/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.