@intentface/ui 0.0.0 → 0.7.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Intentface
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,5 +1,148 @@
 # @intentface/ui
 
-Placeholder release that reserves the name for trusted publishing. Install 0.7.0 or later.
+Headless UI primitives for React — the behavior, state, and wire formats for AI
+chat interfaces and the app shells around them, with no styling of their own.
 
-Formerly `@intentface/chat`. Docs: https://ui.intentface.com
+**The package owns behavior; you own every class.** There is no styled companion
+package and no theme to opt out of.
+The demos on each [docs](https://ui.intentface.com) page are self-contained
+Tailwind, meant to be copied and restyled.
+
+```tsx
+"use client";
+import { Composer } from "@intentface/ui/composer";
+import { Message } from "@intentface/ui/message";
+import { Thread } from "@intentface/ui/thread";
+
+export const Chat = ({ messages, send }: ChatProps) => (
+  <Thread.Root autoScroll="follow" className="relative flex h-dvh flex-col">
+    <Thread.Viewport className="flex-1 overflow-y-auto">
+      <Thread.Content className="mx-auto flex max-w-2xl flex-col gap-4 p-4">
+        {messages.map((message) => (
+          <Message.Root key={message.id} role={message.role}>
+            <Message.Text>{message.text}</Message.Text>
+          </Message.Root>
+        ))}
+      </Thread.Content>
+    </Thread.Viewport>
+
+    <Thread.Composer className="p-4">
+      <Composer.Root onSubmit={send}>
+        <Composer.Container className="rounded-xl border p-2">
+          <Composer.Textarea placeholder="Ask anything" />
+          <Composer.Actions>
+            <Composer.Submit>Send</Composer.Submit>
+          </Composer.Actions>
+        </Composer.Container>
+      </Composer.Root>
+    </Thread.Composer>
+  </Thread.Root>
+);
+```
+
+Every class above is yours; delete them and the chat still works, it just looks
+like unstyled HTML.
+
+## Status
+
+Pre-1.0. The primitives are in real use, but the API is still settling and
+minor releases may contain breaking changes — the usual `0.x` semver contract.
+Pin an exact version if that matters to you, and check the
+[changelog](https://github.com/Intentface/intentface-ui/blob/main/packages/ui/CHANGELOG.md)
+when upgrading.
+
+## Install
+
+```bash
+bun add @intentface/ui
+```
+
+`react` and `react-dom` (v19+) are peer dependencies. Nothing else ships with
+it beyond one small runtime dep (`@floating-ui/dom` for anchored positioning) —
+no editor framework, no animation library.
+
+## What's inside
+
+Each primitive is a separate entry point, exporting an unstyled compound
+component that renders semantic DOM with `data-*` state attributes, context
+hooks, and a `render` prop for swapping the underlying element. Shell, nav and
+tabs are app-shell parts rather than chat parts, and are useful on their own:
+
+| Import | What it is |
+| --- | --- |
+| `@intentface/ui/composer` | Rich-text input over a purpose-built contenteditable engine: `/` and `@` command palette, inline chips, attachments, ask-user flow. One store per `<Composer.Root>`, or bring your own via `Composer.createStore()`. |
+| `@intentface/ui/thread` | Scroll container with at-bottom detection, auto-follow, and docked-composer measurement. |
+| `@intentface/ui/message` | Message parts, turns, chip-segmented text, selection hooks. |
+| `@intentface/ui/steps`, `/reasoning` | Tool-call timelines and reasoning disclosure. |
+| `@intentface/ui/shell` | A collapsible, resizable sidebar beside the viewport it shares the screen with, with an edge hotspot. |
+| `@intentface/ui/nav` | A nav tree with roving focus, typeahead, collapsible groups, and a guide ladder down the left edge. |
+| `@intentface/ui/tabs` | An open-ended, closable tab collection whose panel renders in the layout or anchored to its own tab. |
+| `@intentface/ui/chip`, `/attachments`, `/ask-user` | The remaining building blocks. |
+| `@intentface/ui/generative` | Experimental. Typed helpers that check a model's UI tool call against a catalog, read it while it streams, resolve its data bindings, and write it as Markdown. |
+| `@intentface/ui/types` | The structural message contract + part type guards. |
+| `@intentface/ui/message-utils` | Part segmentation, turn grouping, reasoning/source derivation. |
+| `@intentface/ui/chip-markdown` | The self-describing chip wire format. |
+
+## AI SDK, structurally
+
+The types are framework-agnostic. A Vercel AI SDK `UIMessage` satisfies
+`ChatMessage` structurally, so there's no adapter — pass SDK messages straight
+into the utilities and components:
+
+```tsx
+import { groupTurns } from "@intentface/ui/message-utils";
+import type { UIMessage } from "ai";
+
+const turns = groupTurns(messages); // messages: UIMessage[]
+```
+
+## React Server Components
+
+Each primitive is a namespace, and the root is explicit — `Message.Root`, not
+`Message`. Server components can reach every part:
+
+```tsx
+// A server component — no "use client" needed.
+import { Message } from "@intentface/ui/message";
+
+export const Transcript = ({ messages }: { messages: ChatMessage[] }) => (
+  <>
+    {messages.map((message) => (
+      <Message.Root key={message.id} role={message.role}>
+        <Message.Text>{text(message)}</Message.Text>
+      </Message.Root>
+    ))}
+  </>
+);
+```
+
+The parts are still client components — they carry their own `"use client"` — so
+interactive props behave the way React requires. Pass an event handler from a
+server component and you'll get React's usual error; move that piece into a
+client component:
+
+```tsx
+"use client";
+import { Composer } from "@intentface/ui/composer";
+
+export const Chat = () => (
+  <Composer.Root onSubmit={(data) => send(data)}>
+    <Composer.Container>
+      <Composer.Textarea />
+    </Composer.Container>
+  </Composer.Root>
+);
+```
+
+Hooks (`useComposer`, `useThread`, `useReasoning`, …) are client-only, as usual.
+The pure modules — `/types`, `/message-utils`, `/chip-markdown` — carry no
+directive and import fine anywhere.
+
+## Docs
+
+Full guides, live demos, and the API reference at
+[ui.intentface.com](https://ui.intentface.com).
+
+## License
+
+MIT

package/dist/ask-user/ask-user.d.ts

@@ -0,0 +1,104 @@
+import { type ReactNode, type RefObject } from "react";
+import type { PrimitiveProps } from "../internal/primitive-props.js";
+/** AskUser root container. Stateless — consumers manage all state externally. */
+export type AskUserRootProps = PrimitiveProps<"div">;
+export declare const AskUserRoot: ({ className, render, style, ...elementProps }: AskUserRootProps) => import("react").JSX.Element;
+/** Question heading text. Carries the id `Options` uses as its accessible name. */
+export type AskUserLabelProps = PrimitiveProps<"p">;
+export declare const AskUserLabel: ({ className, render, style, ...elementProps }: AskUserLabelProps) => import("react").ReactElement<unknown, string | import("react").JSXElementConstructor<any>>;
+/** Row container for `Label` and optional `Navigation`. */
+export type AskUserHeaderProps = PrimitiveProps<"div">;
+export declare const AskUserHeader: ({ className, render, style, ...elementProps }: AskUserHeaderProps) => import("react").ReactElement<unknown, string | import("react").JSXElementConstructor<any>>;
+/** Row container for `Previous`, `StepLabel`, and `Next`. */
+export type AskUserNavigationProps = PrimitiveProps<"div">;
+export declare const AskUserNavigation: ({ className, render, style, ...elementProps }: AskUserNavigationProps) => import("react").ReactElement<unknown, string | import("react").JSXElementConstructor<any>>;
+/** Navigate to the previous step. Default accessible name; override via aria-label. */
+export type AskUserPreviousProps = PrimitiveProps<"button">;
+export declare const AskUserPrevious: ({ className, render, style, ...elementProps }: AskUserPreviousProps) => import("react").ReactElement<unknown, string | import("react").JSXElementConstructor<any>>;
+/** Navigate to the next step. Default accessible name; override via aria-label. */
+export type AskUserNextProps = PrimitiveProps<"button">;
+export declare const AskUserNext: ({ className, render, style, ...elementProps }: AskUserNextProps) => import("react").ReactElement<unknown, string | import("react").JSXElementConstructor<any>>;
+/** Step indicator. Reads the current step + total from the composer store; the
+ * consumer supplies the text via `children` — either a node, or a callback
+ * receiving `{ current, total }` (1-based current). No default format. */
+export type AskUserStepLabelState = {
+    current: number;
+    total: number;
+};
+export type AskUserStepLabelProps = Omit<PrimitiveProps<"span">, "children"> & {
+    children?: ReactNode | ((state: AskUserStepLabelState) => ReactNode);
+};
+export declare const AskUserStepLabel: ({ children, className, render, style, ...elementProps }: AskUserStepLabelProps) => import("react").ReactElement<unknown, string | import("react").JSXElementConstructor<any>>;
+/** Fieldset wrapper for `Option` items. Provides `multiSelect`, `groupName`, and highlight state to child options via context. Items self-register on mount (cmdk pattern). */
+type OptionsContextValue = {
+    multiSelect: boolean;
+    groupName: string;
+    highlightedValue: string | null;
+    items: RefObject<string[]>;
+    register: (value: string, getElement: () => HTMLElement | null) => () => void;
+    onItemHover: (value: string) => void;
+};
+export declare const useAskUserOptions: () => OptionsContextValue;
+/** Imperative handle exposed by `AskUser.Options` for keyboard navigation. */
+export type AskUserOptionsHandle = {
+    /** Move highlight by direction, focusing the newly highlighted option (roving tabindex). Returns the new highlighted value (null = past the list boundary). */
+    navigate: (direction: number) => string | null;
+    select: () => {
+        value: string;
+    } | null;
+    clearHighlight: () => void;
+    resetHighlight: () => void;
+    /** Move DOM focus onto the highlighted option (or the first option when none is highlighted). */
+    focusHighlighted: () => void;
+    /** The options container element — the composer attaches its question-mode keydown handling here. */
+    getElement: () => HTMLElement | null;
+    highlightedValue: string | null;
+};
+export type AskUserOptionsProps = Omit<PrimitiveProps<"fieldset">, "value" | "ref"> & {
+    /** When true, options render as multi-select (checkbox semantics in the styled layer). */
+    multiSelect?: boolean;
+    /** Shared `name` attribute for all option inputs in this group. */
+    groupName?: string;
+    /** Imperative ref for keyboard navigation (navigate, select, clearHighlight, resetHighlight). */
+    ref?: RefObject<AskUserOptionsHandle | null>;
+};
+export declare const AskUserOptions: ({ multiSelect, groupName, ref, className, render, style, children, ...elementProps }: AskUserOptionsProps) => import("react").JSX.Element;
+/** Selectable card. Self-registers with parent `Options` on mount (cmdk pattern). Derives highlight state from context. */
+type OptionContextValue = {
+    id: string;
+    value: string;
+    selected: boolean;
+    onSelect?: () => void;
+};
+export declare const useAskUserOption: () => OptionContextValue;
+export type AskUserOptionState = {
+    /** Present as data-highlighted while keyboard/hover highlighted. */
+    highlighted: boolean;
+    /** Present as data-selected while the option is selected. */
+    selected: boolean;
+};
+export type AskUserOptionProps = PrimitiveProps<"label", AskUserOptionState> & {
+    value?: string;
+    selected?: boolean;
+    onSelect?: () => void;
+};
+export declare const AskUserOption: ({ value, selected, onSelect, className, render, style, children, ...elementProps }: AskUserOptionProps) => import("react").JSX.Element;
+/** Flex column wrapper for `OptionLabel` and `OptionDescription`. */
+export type AskUserOptionContentProps = PrimitiveProps<"span">;
+export declare const AskUserOptionContent: ({ className, render, style, ...elementProps }: AskUserOptionContentProps) => import("react").ReactElement<unknown, string | import("react").JSXElementConstructor<any>>;
+/** Option title text. */
+export type AskUserOptionLabelProps = PrimitiveProps<"span">;
+export declare const AskUserOptionLabel: ({ className, render, style, ...elementProps }: AskUserOptionLabelProps) => import("react").ReactElement<unknown, string | import("react").JSXElementConstructor<any>>;
+/** Option subtitle/description text. */
+export type AskUserOptionDescriptionProps = PrimitiveProps<"span">;
+export declare const AskUserOptionDescription: ({ className, render, style, ...elementProps }: AskUserOptionDescriptionProps) => import("react").ReactElement<unknown, string | import("react").JSXElementConstructor<any>>;
+/** Keyboard shortcut hints displayed below the ask-user options. */
+export type AskUserHintsProps = PrimitiveProps<"div">;
+export declare const AskUserHints: ({ className, render, style, ...elementProps }: AskUserHintsProps) => import("react").ReactElement<unknown, string | import("react").JSXElementConstructor<any>>;
+/** Dismiss/skip button. Stateless — wire `onClick` to your dismiss handler. */
+export type AskUserDismissProps = PrimitiveProps<"button">;
+export declare const AskUserDismiss: ({ className, render, style, ...elementProps }: AskUserDismissProps) => import("react").ReactElement<unknown, string | import("react").JSXElementConstructor<any>>;
+/** Continue/submit button — `type=submit` so the enclosing form drives it. */
+export type AskUserContinueProps = PrimitiveProps<"button">;
+export declare const AskUserContinue: ({ className, render, style, ...elementProps }: AskUserContinueProps) => import("react").ReactElement<unknown, string | import("react").JSXElementConstructor<any>>;
+export {};

package/dist/ask-user/ask-user.js

@@ -0,0 +1,245 @@
+"use client";
+import { jsx as _jsx } from "react/jsx-runtime";
+// Headless ask-user questionnaire parts. Owns the option registration system
+// (cmdk pattern), highlight state, and the imperative keyboard-navigation
+// handle. Input widgets (checkbox/radio), icons, and the answered summary
+// belong to the styled layer, which reads state via useAskUserOptions() /
+// useAskUserOption(). Every part supports the Base UI render prop.
+import { createContext, use, useCallback, useId, useImperativeHandle, useInsertionEffect, useLayoutEffect, useMemo, useRef, useState, } from "react";
+import { useComposer } from "../composer/store.js";
+import { useRenderElement } from "../internal/render/useRenderElement.js";
+import { scrollIntoViewWithin } from "../internal/scroll-into-view-within.js";
+const AskUserIdsContext = createContext({ labelId: "", stepLabelId: "" });
+export const AskUserRoot = ({ className, render, style, ...elementProps }) => {
+    const labelId = useId();
+    const stepLabelId = useId();
+    const element = useRenderElement("div", { className, render, style }, { props: [{ "data-ask-user": "" }, elementProps] });
+    const ids = useMemo(() => ({ labelId, stepLabelId }), [labelId, stepLabelId]);
+    return _jsx(AskUserIdsContext, { value: ids, children: element });
+};
+export const AskUserLabel = ({ className, render, style, ...elementProps }) => {
+    const { labelId } = use(AskUserIdsContext);
+    return useRenderElement("p", { className, render, style }, { props: [{ id: labelId || undefined, "data-ask-user-label": "" }, elementProps] });
+};
+export const AskUserHeader = ({ className, render, style, ...elementProps }) => useRenderElement("div", { className, render, style }, { props: [{ "data-ask-user-header": "" }, elementProps] });
+export const AskUserNavigation = ({ className, render, style, ...elementProps }) => useRenderElement("div", { className, render, style }, { props: [{ "data-ask-user-navigation": "" }, elementProps] });
+export const AskUserPrevious = ({ className, render, style, ...elementProps }) => useRenderElement("button", { className, render, style }, { props: [{ "aria-label": "Previous question", "data-ask-user-previous": "" }, elementProps] });
+export const AskUserNext = ({ className, render, style, ...elementProps }) => useRenderElement("button", { className, render, style }, { props: [{ "aria-label": "Next question", "data-ask-user-next": "" }, elementProps] });
+export const AskUserStepLabel = ({ children, className, render, style, ...elementProps }) => {
+    const current = useComposer((composer) => composer.askUser.step) + 1;
+    const total = useComposer((composer) => composer.askUser.questions?.length ?? 0);
+    const { stepLabelId } = use(AskUserIdsContext);
+    const content = typeof children === "function" ? children({ current, total }) : children;
+    return useRenderElement("span", { className, render, style }, {
+        props: [
+            { id: stepLabelId || undefined, "data-ask-user-step-label": "", children: content },
+            elementProps,
+        ],
+    });
+};
+const OptionsContext = createContext({
+    multiSelect: false,
+    groupName: "",
+    highlightedValue: null,
+    items: { current: [] },
+    register: () => () => { },
+    onItemHover: () => { },
+});
+export const useAskUserOptions = () => use(OptionsContext);
+export const AskUserOptions = ({ multiSelect = false, groupName = "", ref, className, render, style, children, ...elementProps }) => {
+    const registeredItems = useRef([]);
+    const itemElements = useRef(new Map());
+    const containerRef = useRef(null);
+    const { labelId, stepLabelId } = use(AskUserIdsContext);
+    const [highlightedValue, setHighlightedValue] = useState(null);
+    // Track highlight in a ref so imperative methods see latest value without re-binding.
+    // Mirrored after commit, not during a render React may discard, and in an
+    // insertion effect: it runs before every layout effect in the tree, and the
+    // options register in theirs, where they may seed the highlight imperatively.
+    const highlightedValueRef = useRef(highlightedValue);
+    useInsertionEffect(() => {
+        highlightedValueRef.current = highlightedValue;
+    });
+    const register = useCallback((itemValue, getElement) => {
+        registeredItems.current = [...registeredItems.current, itemValue];
+        itemElements.current.set(itemValue, getElement);
+        // Auto-highlight whenever an item registers while nothing is highlighted.
+        // Using length === 1 here is fragile: during a step transition, React can
+        // interleave old-item cleanups with new-item setups, so the new first
+        // option may arrive when the list is not exactly length 1.
+        if (highlightedValueRef.current === null) {
+            highlightedValueRef.current = itemValue;
+            setHighlightedValue(itemValue);
+        }
+        return () => {
+            registeredItems.current = registeredItems.current.filter((v) => v !== itemValue);
+            itemElements.current.delete(itemValue);
+            // Clear highlight when the highlighted item deregisters — allows auto-highlight
+            // to fire for the next set of items (e.g. on step change)
+            if (highlightedValueRef.current === itemValue) {
+                highlightedValueRef.current = null;
+                setHighlightedValue(null);
+            }
+        };
+    }, []);
+    const onItemHover = useCallback((itemValue) => {
+        setHighlightedValue(itemValue);
+    }, []);
+    // Roving tabindex: DOM focus follows the highlight for keyboard navigation.
+    // Focus without the browser's scroll, which would also move the page around
+    // an embedded question; bring the option into view within the question's
+    // own scroll area instead.
+    const focusValue = useCallback((itemValue) => {
+        if (itemValue === null)
+            return;
+        const element = itemElements.current.get(itemValue)?.();
+        if (!element)
+            return;
+        element.focus({ preventScroll: true });
+        const boundary = element.closest("[data-ask-user]") ?? element;
+        scrollIntoViewWithin(element.getBoundingClientRect(), element, boundary);
+    }, []);
+    useImperativeHandle(ref, () => ({
+        navigate: (direction) => {
+            const items = registeredItems.current;
+            if (items.length === 0)
+                return null;
+            const previous = highlightedValueRef.current;
+            let next;
+            if (previous === null) {
+                next = (direction > 0 ? items[0] : items[items.length - 1]) ?? null;
+            }
+            else {
+                const currentIndex = items.indexOf(previous);
+                const nextIndex = currentIndex + direction;
+                if (nextIndex >= items.length || nextIndex < 0)
+                    next = null;
+                else
+                    next = items[nextIndex] ?? null;
+            }
+            highlightedValueRef.current = next;
+            setHighlightedValue(next);
+            focusValue(next);
+            return next;
+        },
+        select: () => {
+            const current = highlightedValueRef.current;
+            if (current === null)
+                return null;
+            return { value: current };
+        },
+        clearHighlight: () => {
+            highlightedValueRef.current = null;
+            setHighlightedValue(null);
+        },
+        resetHighlight: () => {
+            // Clear synchronously — the auto-highlight path in `register` will pick
+            // up the first new item when it mounts after a step change.
+            highlightedValueRef.current = null;
+            setHighlightedValue(null);
+        },
+        focusHighlighted: () => {
+            const target = highlightedValueRef.current ?? registeredItems.current[0] ?? null;
+            if (target !== null && highlightedValueRef.current === null) {
+                highlightedValueRef.current = target;
+                setHighlightedValue(target);
+            }
+            focusValue(target);
+        },
+        getElement: () => containerRef.current,
+        get highlightedValue() {
+            return highlightedValueRef.current;
+        },
+    }), [focusValue]);
+    const element = useRenderElement("fieldset", { className, render, style }, {
+        ref: containerRef,
+        props: [
+            {
+                // The options are the real selectable controls (role radio/checkbox
+                // on each option), so the container is their labelled group.
+                role: multiSelect ? "group" : "radiogroup",
+                "aria-labelledby": labelId || undefined,
+                "aria-describedby": stepLabelId || undefined,
+                "data-ask-user-options": "",
+                children,
+            },
+            elementProps,
+        ],
+    });
+    const options = useMemo(() => ({
+        multiSelect,
+        groupName,
+        highlightedValue,
+        items: registeredItems,
+        register,
+        onItemHover,
+    }), [multiSelect, groupName, highlightedValue, register, onItemHover]);
+    return _jsx(OptionsContext, { value: options, children: element });
+};
+const OptionContext = createContext({
+    id: "",
+    value: "",
+    selected: false,
+    onSelect: () => { },
+});
+export const useAskUserOption = () => use(OptionContext);
+export const AskUserOption = ({ value = "", selected = false, onSelect, className, render, style, children, ...elementProps }) => {
+    const id = useId();
+    const { multiSelect, highlightedValue, register, onItemHover } = use(OptionsContext);
+    const optionRef = useRef(null);
+    const isHighlighted = value === highlightedValue;
+    // Self-register on mount, deregister on unmount (true subscription side effect)
+    const registerRef = useRef(register);
+    useInsertionEffect(() => {
+        registerRef.current = register;
+    });
+    useItemRegistration(value, registerRef, optionRef);
+    const element = useRenderElement("label", { className, render, style }, {
+        ref: optionRef,
+        state: { highlighted: isHighlighted, selected },
+        props: [
+            {
+                // The option IS the selectable control: role + checked state live
+                // here, and the roving tabindex makes the highlighted option the
+                // group's single tab stop. Never a native input — the composer's
+                // question-mode key scoping treats inputs as foreign editables.
+                id,
+                role: multiSelect ? "checkbox" : "radio",
+                "aria-checked": selected,
+                tabIndex: isHighlighted ? 0 : -1,
+                "data-ask-user-option": "",
+                onMouseMove: () => onItemHover(value),
+                // Keep highlight and DOM focus unified when focus arrives by other
+                // means (Tab into the group, SR virtual-cursor activation).
+                onFocus: () => onItemHover(value),
+                // Self-contained click selection. The option itself is the control
+                // now, so only a *different* nested interactive element defers —
+                // a bare option stays fully clickable.
+                onClick: (event) => {
+                    const nested = event.target.closest("input,button,[role=checkbox],[role=radio]");
+                    if (nested && nested !== event.currentTarget)
+                        return;
+                    event.preventDefault();
+                    onSelect?.();
+                },
+                children,
+            },
+            elementProps,
+        ],
+    });
+    const option = useMemo(() => ({ id, value, selected, onSelect }), [id, value, selected, onSelect]);
+    return _jsx(OptionContext, { value: option, children: element });
+};
+/** Registers an item value + element with the parent Options container synchronously before paint and deregisters on unmount. */
+const useItemRegistration = (value, registerRef, elementRef) => {
+    // useLayoutEffect ensures items are registered before paint so the initial highlight resolves immediately
+    useLayoutEffect(() => {
+        return registerRef.current(value, () => elementRef.current);
+    }, [value, registerRef, elementRef]);
+};
+export const AskUserOptionContent = ({ className, render, style, ...elementProps }) => useRenderElement("span", { className, render, style }, { props: [{ "data-ask-user-option-content": "" }, elementProps] });
+export const AskUserOptionLabel = ({ className, render, style, ...elementProps }) => useRenderElement("span", { className, render, style }, { props: [{ "data-ask-user-option-label": "" }, elementProps] });
+export const AskUserOptionDescription = ({ className, render, style, ...elementProps }) => useRenderElement("span", { className, render, style }, { props: [{ "data-ask-user-option-description": "" }, elementProps] });
+export const AskUserHints = ({ className, render, style, ...elementProps }) => useRenderElement("div", { className, render, style }, { props: [{ "data-ask-user-hints": "" }, elementProps] });
+export const AskUserDismiss = ({ className, render, style, ...elementProps }) => useRenderElement("button", { className, render, style }, { props: [{ type: "button", "data-ask-user-dismiss": "" }, elementProps] });
+export const AskUserContinue = ({ className, render, style, ...elementProps }) => useRenderElement("button", { className, render, style }, { props: [{ type: "submit", "data-ask-user-continue": "" }, elementProps] });

package/dist/ask-user/index.d.ts

@@ -0,0 +1,3 @@
+export type { AskUserContinueProps, AskUserDismissProps, AskUserHeaderProps, AskUserHintsProps, AskUserLabelProps, AskUserNavigationProps, AskUserNextProps, AskUserOptionContentProps, AskUserOptionDescriptionProps, AskUserOptionLabelProps, AskUserOptionProps, AskUserOptionState, AskUserOptionsHandle, AskUserOptionsProps, AskUserPreviousProps, AskUserRootProps, AskUserStepLabelProps, AskUserStepLabelState, } from "./ask-user.js";
+export { useAskUserOption, useAskUserOptions } from "./ask-user.js";
+export * as AskUser from "./index.parts.js";

package/dist/ask-user/index.js

@@ -0,0 +1,3 @@
+// Public surface of @intentface/ui/ask-user. No directive — see index.parts.ts.
+export { useAskUserOption, useAskUserOptions } from "./ask-user.js";
+export * as AskUser from "./index.parts.js";

package/dist/ask-user/index.parts.d.ts

@@ -0,0 +1 @@
+export { AskUserContinue as Continue, AskUserDismiss as Dismiss, AskUserHeader as Header, AskUserHints as Hints, AskUserLabel as Label, AskUserNavigation as Navigation, AskUserNext as Next, AskUserOption as Option, AskUserOptionContent as OptionContent, AskUserOptionDescription as OptionDescription, AskUserOptionLabel as OptionLabel, AskUserOptions as Options, AskUserPrevious as Previous, AskUserRoot as Root, AskUserStepLabel as StepLabel, } from "./ask-user.js";

package/dist/ask-user/index.parts.js

@@ -0,0 +1,5 @@
+// Part names for the `AskUser` namespace. Deliberately carries no
+// "use client" directive: this module and index.ts must stay server-resolvable
+// so a React Server Component can reach AskUser.Root and its siblings
+// through them. The directive lives one level down, on ask-user.tsx.
+export { AskUserContinue as Continue, AskUserDismiss as Dismiss, AskUserHeader as Header, AskUserHints as Hints, AskUserLabel as Label, AskUserNavigation as Navigation, AskUserNext as Next, AskUserOption as Option, AskUserOptionContent as OptionContent, AskUserOptionDescription as OptionDescription, AskUserOptionLabel as OptionLabel, AskUserOptions as Options, AskUserPrevious as Previous, AskUserRoot as Root, AskUserStepLabel as StepLabel, } from "./ask-user.js";

package/dist/attachments/attachments.d.ts

@@ -0,0 +1,73 @@
+import { type ReactNode } from "react";
+import type { PrimitiveProps } from "../internal/primitive-props.js";
+export type AttachmentItem = {
+    id: string;
+    url: string;
+    filename?: string;
+    mediaType?: string;
+    fileSize?: number;
+};
+export type AttachmentErrorCode = "accept" | "max_file_size" | "max_files";
+export declare const toAttachmentItem: (file: File) => AttachmentItem;
+export declare const revokeAttachmentUrl: (item: Pick<AttachmentItem, "url">) => void;
+export declare const revokeAllAttachmentUrls: (items: Pick<AttachmentItem, "url">[]) => void;
+export declare const matchesAccept: (file: File, accept: string) => boolean;
+export type AttachmentsRootProps = PrimitiveProps<"div">;
+/**
+ * The tray container. Mount it only when there are items to show; it renders
+ * no layout of its own.
+ * Renders a `<div>` element.
+ */
+export declare const AttachmentsRoot: ({ className, render, style, ...elementProps }: AttachmentsRootProps) => import("react").ReactElement<unknown, string | import("react").JSXElementConstructor<any>>;
+export type AttachmentsItemProps = PrimitiveProps<"div">;
+/**
+ * One attachment, as a structural slot with no media taxonomy of its own.
+ * Read the item's `mediaType` and decide what an image or a PDF looks like.
+ * Renders a `<div>` element.
+ */
+export declare const AttachmentsItem: ({ className, render, style, ...elementProps }: AttachmentsItemProps) => import("react").ReactElement<unknown, string | import("react").JSXElementConstructor<any>>;
+export type AttachmentsRemoveProps = PrimitiveProps<"button"> & {
+    onRemove: () => void;
+    /** Names the control per item ("Remove report.pdf") — without it, N remove buttons announce identically. */
+    filename?: string;
+};
+/**
+ * The removal affordance. Named "Remove attachment" by default, or
+ * "Remove {filename}" when `filename` is set, so a row of them does not
+ * announce identically.
+ * Renders a `<button>` element.
+ */
+export declare const AttachmentsRemove: ({ onRemove, filename, className, render, style, ...elementProps }: AttachmentsRemoveProps) => import("react").ReactElement<unknown, string | import("react").JSXElementConstructor<any>>;
+export type AttachmentsDropzoneState = {
+    /** Present as data-visible while files are dragged over the scope. */
+    visible: boolean;
+};
+export type AttachmentsDropzoneProps = PrimitiveProps<"div", AttachmentsDropzoneState> & {
+    visible?: boolean;
+    /** Keep the dropzone mounted (hidden) when not visible. */
+    keepMounted?: boolean;
+    /** CSS selector to portal the dropzone into (e.g. an app shell region). */
+    portalSelector?: string;
+    children?: ReactNode;
+};
+/**
+ * The drop overlay. `portalSelector` only moves where it renders (e.g. over an
+ * app shell region); where files can be dropped is `Composer.Attachments`'
+ * `globalDrop`, not this part.
+ * Renders a `<div>` element.
+ */
+export declare const AttachmentsDropzone: ({ visible, keepMounted, portalSelector, children, className, render, style, ...elementProps }: AttachmentsDropzoneProps) => import("react").ReactElement<unknown, string | import("react").JSXElementConstructor<any>> | null;
+export type AttachmentsErrorProps = PrimitiveProps<"span">;
+/**
+ * The validation slot, as a live region: whatever appears inside announces
+ * immediately. Validation emits a code, never copy, so the message is yours.
+ * Renders a `<span>` element with `role="alert"`.
+ */
+export declare const AttachmentsError: ({ className, render, style, ...elementProps }: AttachmentsErrorProps) => import("react").ReactElement<unknown, string | import("react").JSXElementConstructor<any>>;
+export type AttachmentsTriggerProps = PrimitiveProps<"button">;
+/**
+ * The file-picker button, named "Add attachment" by default. The package owns
+ * no file input; wire this to your own.
+ * Renders a `<button>` element.
+ */
+export declare const AttachmentsTrigger: ({ className, render, style, ...elementProps }: AttachmentsTriggerProps) => import("react").ReactElement<unknown, string | import("react").JSXElementConstructor<any>>;