feat: add headless handle typeahead components

Author: chrisvander

.npmignore

@@ -1,4 +1,5 @@
 *
+!dist/
 !dist/**
 !package.json
 !README.md

README.md

@@ -69,6 +69,45 @@ To add sign in, create a sign in page and add a standard HTML form that submits
 </form>
 ```
 
+For an unstyled handle typeahead, compose the optional components around the same native form:
+
+```astro
+---
+import HandleField from "at-astro/components/HandleField"
+import HandleInput from "at-astro/components/HandleInput"
+import HandleOption from "at-astro/components/HandleOption"
+import HandleOptions from "at-astro/components/HandleOptions"
+---
+
+<form action="/oauth/login" method="post">
+  <HandleField>
+    <label>
+      Handle
+      <HandleInput autocomplete="off" placeholder="you.bsky.social" required />
+    </label>
+
+    <HandleOptions>
+      <HandleOption>
+        <span data-at-field="displayName"></span>
+        <span>@<span data-at-field="handle"></span></span>
+      </HandleOption>
+    </HandleOptions>
+  </HandleField>
+
+  <button>Sign in</button>
+</form>
+```
+
+`HandleField` uses the integration's configured `publicEndpoint` by default. Pass `endpoint` to query a different service for this field:
+
+```astro
+<HandleField endpoint="https://another-appview.example.com">
+  <!-- HandleInput and HandleOptions -->
+</HandleField>
+```
+
+The single child of `HandleOptions` is an inert native template that is cloned for each suggestion. Bind returned actor fields with `data-at-field="did"`, `data-at-field="handle"`, `data-at-field="displayName"`, or `data-at-field="avatar"`; the avatar binding must be placed on an `<img>`. `HandleField` reports `data-state="idle"`, `loading`, `success`, `empty`, or `error` on its root element so application CSS can respond without coupling to the implementation. The components add no styles, and the submitted value remains an ordinary `input[name="handle"]`. Suggestions are optional and do not restrict which handles can be submitted.
+
 Sign out is just as simple:
 
 ```html

package.json

@@ -28,6 +28,10 @@
       "types": "./dist/middleware.d.mts",
       "default": "./dist/middleware.mjs"
     },
+    "./components/HandleField": "./dist/components/HandleField.astro",
+    "./components/HandleInput": "./dist/components/HandleInput.astro",
+    "./components/HandleOptions": "./dist/components/HandleOptions.astro",
+    "./components/HandleOption": "./dist/components/HandleOption.astro",
     "./pages/*": {
       "types": "./dist/pages/*.d.mts",
       "default": "./dist/pages/*.mjs"

src/components/HandleField.astro

@@ -0,0 +1,19 @@
+---
+import type { HTMLAttributes } from "astro/types"
+import { config } from "at-astro:config"
+
+type Props = HTMLAttributes<"div"> & {
+  /** Override the configured public AT Protocol endpoint for actor typeahead queries. */
+  endpoint?: string | URL
+}
+
+const { endpoint = config.publicEndpoint, ...attributes } = Astro.props
+---
+
+<at-astro-handle-field {...attributes} endpoint={endpoint.toString()}>
+  <slot />
+</at-astro-handle-field>
+
+<script>
+  import "./handle-field-element.mjs"
+</script>

src/components/HandleInput.astro

@@ -0,0 +1,9 @@
+---
+import type { HTMLAttributes } from "astro/types"
+
+type Props = Omit<HTMLAttributes<"input">, "name">
+
+const attributes = Astro.props
+---
+
+<input {...attributes} name="handle" data-at-handle-input />

src/components/HandleOption.astro

@@ -0,0 +1,11 @@
+---
+import type { HTMLAttributes } from "astro/types"
+
+type Props = HTMLAttributes<"li">
+
+const attributes = Astro.props
+---
+
+<li {...attributes}>
+  <slot />
+</li>

src/components/HandleOptions.astro

@@ -0,0 +1,17 @@
+---
+import type { HTMLAttributes } from "astro/types"
+
+type Props = HTMLAttributes<"ul">
+
+if (!Astro.slots.has("default")) {
+  throw new Error("HandleOptions requires one li template")
+}
+
+const attributes = Astro.props
+---
+
+<ul {...attributes} data-at-handle-options role="listbox" hidden>
+  <template data-at-handle-template>
+    <slot />
+  </template>
+</ul>