@intentface/ui 0.0.0-stage → 0.7.0

package/dist/message/message.d.ts

@@ -0,0 +1,58 @@
+import { type ReactNode } from "react";
+import { type ChipSegment } from "../chip-markdown.js";
+import type { PrimitiveProps } from "../internal/primitive-props.js";
+export type MessageState = {
+    /** Opaque role string; the consumer owns the concrete set. Surfaced as data-role. */
+    role: string;
+    /** Present as data-error when true. */
+    error: boolean;
+    /** Present as data-last when true. */
+    last: boolean;
+};
+export type MessageRootProps = Omit<PrimitiveProps<"div", MessageState>, "role"> & {
+    role: string;
+    isLast?: boolean;
+    isError?: boolean;
+};
+/**
+ * One turn's container. Reports the role and position as data attributes and
+ * renders no layout of its own, so the bubble, avatar and actions around it
+ * stay yours.
+ * Renders a `<div>` element.
+ */
+export declare const MessageRoot: ({ role, isLast, isError, className, render, style, ...elementProps }: MessageRootProps) => import("react").ReactElement<unknown, string | import("react").JSXElementConstructor<any>>;
+export type MessageTurnProps = PrimitiveProps<"div">;
+/**
+ * Groups consecutive messages from one role into a single visual turn.
+ * Renders a `<div>` element.
+ */
+export declare const MessageTurn: ({ className, render, style, ...elementProps }: MessageTurnProps) => import("react").ReactElement<unknown, string | import("react").JSXElementConstructor<any>>;
+export type MessageChipSegment = Extract<ChipSegment, {
+    type: "chip";
+}>;
+export type MessageTextProps = Omit<PrimitiveProps<"span">, "children"> & {
+    children: string;
+    renderText?: (text: string, index: number) => ReactNode;
+    renderChip?: (chip: MessageChipSegment, index: number) => ReactNode;
+};
+/**
+ * Message text with inline chips reconstructed from the wire format, so a
+ * stored message rebuilds its own chips with no sidecar metadata.
+ * Renders a `<span>` element.
+ */
+export declare const MessageText: ({ children, className, render, style, renderText, renderChip, ...elementProps }: MessageTextProps) => import("react").ReactElement<unknown, string | import("react").JSXElementConstructor<any>>;
+export type MessageSelection = {
+    text: string;
+    range: Range;
+};
+export declare const readMessageSelection: (scope: HTMLElement) => MessageSelection | null;
+export declare const useMessageSelection: (scope: HTMLElement | null) => MessageSelection | null;
+/**
+ * Resolves the owning message's content element from an invisible anchor node
+ * rendered anywhere inside the message. Scoping to message-content keeps the
+ * toolbar off markers, sources, and actions elsewhere in the message.
+ */
+export declare const useMessageSelectionScope: () => {
+    anchorRef: (node: HTMLElement | null) => void;
+    contentElement: HTMLElement | null;
+};

package/dist/message/message.js

@@ -0,0 +1,93 @@
+"use client";
+import { jsx as _jsx } from "react/jsx-runtime";
+// Headless message parts. Owns the role/error/last data-attribute contract,
+// chip-segment text parsing (with render inversion for markdown/styled chips),
+// timestamp formatting, and the text-selection subsystem. Entrance animation,
+// popovers, tooltips, icons, and thumbnails belong to the styled layer.
+//
+// Every part supports the Base UI render prop: pass a ReactElement to swap the
+// underlying element (props are merged onto it), or a function `(props, state)`
+// for full control. The root's data attributes (data-role, data-error,
+// data-last) are generated from its state object, so the render callback and
+// CSS consumers see the same state.
+import { Fragment, useCallback, useEffect, useMemo, useState } from "react";
+import { parseChipSegments } from "../chip-markdown.js";
+import { useRenderElement } from "../internal/render/useRenderElement.js";
+/**
+ * One turn's container. Reports the role and position as data attributes and
+ * renders no layout of its own, so the bubble, avatar and actions around it
+ * stay yours.
+ * Renders a `<div>` element.
+ */
+export const MessageRoot = ({ role, isLast = false, isError = false, className, render, style, ...elementProps }) => {
+    const state = useMemo(() => ({ role, error: isError, last: isLast }), [role, isError, isLast]);
+    return useRenderElement("div", { className, render, style }, { state, props: [{ "data-message": "" }, elementProps] });
+};
+/**
+ * Groups consecutive messages from one role into a single visual turn.
+ * Renders a `<div>` element.
+ */
+export const MessageTurn = ({ className, render, style, ...elementProps }) => useRenderElement("div", { className, render, style }, { props: [{ "data-message-turn": "" }, elementProps] });
+/**
+ * Message text with inline chips reconstructed from the wire format, so a
+ * stored message rebuilds its own chips with no sidecar metadata.
+ * Renders a `<span>` element.
+ */
+export const MessageText = ({ children, className, render, style, renderText, renderChip, ...elementProps }) => {
+    const segments = parseChipSegments(children);
+    const segmentNodes = segments.map((segment, index) => segment.type === "text" ? (_jsx(Fragment, { children: renderText ? renderText(segment.text, index) : segment.text }, index)) : (_jsx(Fragment, { children: renderChip ? (renderChip(segment, index)) : (_jsx("span", { "data-message-chip": "", children: segment.label })) }, index)));
+    return useRenderElement("span", { className, render, style }, { props: [{ "data-message-text": "", children: segmentNodes }, elementProps] });
+};
+export const readMessageSelection = (scope) => {
+    const selection = window.getSelection();
+    if (!selection || selection.isCollapsed || selection.rangeCount === 0)
+        return null;
+    const text = selection.toString();
+    if (text.trim().length === 0)
+        return null;
+    // Both endpoints must sit inside this message — a cross-message selection
+    // has its common ancestor outside the scope and resolves to null.
+    const range = selection.getRangeAt(0);
+    if (!scope.contains(range.commonAncestorContainer))
+        return null;
+    // Clone so later mutations of the live selection don't move our anchor.
+    return { text, range: range.cloneRange() };
+};
+// Subscribe to the document selection, scoped to `scope`. Samples when the
+// gesture settles (mouseup / keyup) instead of on every selectionchange drag
+// tick; selectionchange only clears the value once the selection collapses.
+export const useMessageSelection = (scope) => {
+    const [selection, setSelection] = useState(null);
+    useEffect(() => {
+        if (!scope)
+            return;
+        const readSelection = () => setSelection(readMessageSelection(scope));
+        const hideWhenCollapsed = () => {
+            const current = window.getSelection();
+            if (!current || current.isCollapsed)
+                setSelection(null);
+        };
+        document.addEventListener("mouseup", readSelection);
+        document.addEventListener("keyup", readSelection);
+        document.addEventListener("selectionchange", hideWhenCollapsed);
+        return () => {
+            document.removeEventListener("mouseup", readSelection);
+            document.removeEventListener("keyup", readSelection);
+            document.removeEventListener("selectionchange", hideWhenCollapsed);
+        };
+    }, [scope]);
+    return selection;
+};
+/**
+ * Resolves the owning message's content element from an invisible anchor node
+ * rendered anywhere inside the message. Scoping to message-content keeps the
+ * toolbar off markers, sources, and actions elsewhere in the message.
+ */
+export const useMessageSelectionScope = () => {
+    const [contentElement, setContentElement] = useState(null);
+    const anchorRef = useCallback((node) => {
+        const messageRoot = node?.closest("[data-message]");
+        setContentElement(messageRoot?.querySelector("[data-message-content]") ?? null);
+    }, []);
+    return { anchorRef, contentElement };
+};

package/dist/message-utils.d.ts

@@ -0,0 +1,55 @@
+import { type ChatMessage, type FilePart, type ReasoningPart, type TextPart, type ToolPart, type UnknownPart } from "./types.js";
+/** Classifies message parts into coarse groups for chronological rendering. */
+export type SegmentType = "reasoning" | "tool" | "text" | "file";
+/**
+ * A contiguous run of same-typed message parts. Used by message renderers to
+ * group reasoning blocks, tool calls, text chunks, etc.
+ */
+export type MessageSegment = {
+    type: "reasoning";
+    parts: ReasoningPart[];
+} | {
+    type: "tool";
+    parts: ToolPart[];
+} | {
+    type: "text";
+    parts: TextPart[];
+} | {
+    type: "file";
+    parts: FilePart[];
+};
+/**
+ * Maps a single message part to its segment type.
+ * Returns `null` for parts that are not rendered chronologically.
+ */
+export declare const partSegmentType: (part: UnknownPart) => SegmentType | null;
+/**
+ * Groups an array of message parts into contiguous segments of the same type.
+ * Adjacent parts with the same type are merged into a single segment. This
+ * preserves chronological order for interleaved rendering (e.g. reasoning
+ * interspersed with tool calls).
+ */
+export declare const getSegmentedParts: (parts: readonly UnknownPart[]) => MessageSegment[];
+/** A conversational turn: a user message plus its trailing assistant/tool replies. */
+export type Turn<Message extends ChatMessage<unknown, UnknownPart> = ChatMessage> = {
+    key: string;
+    messages: Message[];
+};
+/**
+ * Groups messages into turns. A new turn starts at every user message;
+ * non-user messages attach to the current turn. A conversation that opens with
+ * a non-user message still gets a leading turn so nothing is dropped. The turn
+ * key is the first message's id — stable while the trailing assistant message
+ * streams, so React keys and entrance animations stay put.
+ */
+export declare const groupTurns: <Message extends ChatMessage<unknown, UnknownPart>>(messages: readonly Message[], turnStartRole?: string) => Turn<Message>[];
+/** Aggregated text content from all text segments in a message. */
+export type TextInfo = {
+    parts: TextPart[];
+    /** Concatenated text content of all text parts. */
+    text: string;
+};
+/** Extracts all text parts from a message and concatenates their content. */
+export declare const getTextInfo: (segments: readonly MessageSegment[]) => TextInfo;
+/** Extracts all file attachment parts from segments. */
+export declare const getFileParts: (segments: readonly MessageSegment[]) => FilePart[];

package/dist/message-utils.js

@@ -0,0 +1,79 @@
+// Derivation helpers over the structural message contract in types.ts.
+// Pure functions — no React, no styling. Renderers and panel-state hooks share
+// these so they stay decoupled from concrete part shapes.
+import { isFilePart, isReasoningPart, isTextPart, isToolPart, } from "./types.js";
+/**
+ * Maps a single message part to its segment type.
+ * Returns `null` for parts that are not rendered chronologically.
+ */
+export const partSegmentType = (part) => {
+    if (isReasoningPart(part))
+        return "reasoning";
+    if (isTextPart(part))
+        return "text";
+    if (isFilePart(part))
+        return "file";
+    if (isToolPart(part))
+        return "tool";
+    return null;
+};
+/**
+ * Groups an array of message parts into contiguous segments of the same type.
+ * Adjacent parts with the same type are merged into a single segment. This
+ * preserves chronological order for interleaved rendering (e.g. reasoning
+ * interspersed with tool calls).
+ */
+export const getSegmentedParts = (parts) => {
+    const segments = [];
+    for (const part of parts) {
+        const segType = partSegmentType(part);
+        if (!segType)
+            continue;
+        const last = segments.at(-1);
+        if (last && last.type === segType) {
+            last.parts.push(part);
+        }
+        else {
+            segments.push({ type: segType, parts: [part] });
+        }
+    }
+    return segments;
+};
+/**
+ * Groups messages into turns. A new turn starts at every user message;
+ * non-user messages attach to the current turn. A conversation that opens with
+ * a non-user message still gets a leading turn so nothing is dropped. The turn
+ * key is the first message's id — stable while the trailing assistant message
+ * streams, so React keys and entrance animations stay put.
+ */
+export const groupTurns = (messages, 
+// The role that starts a new turn — opaque, so consumers with a different
+// role set can group correctly.
+turnStartRole = "user") => {
+    const turns = [];
+    for (const message of messages) {
+        const currentTurn = turns.at(-1);
+        if (message.role === turnStartRole || !currentTurn) {
+            turns.push({ key: message.id, messages: [message] });
+        }
+        else {
+            currentTurn.messages.push(message);
+        }
+    }
+    return turns;
+};
+/** Extracts all text parts from a message and concatenates their content. */
+export const getTextInfo = (segments) => {
+    const parts = segments
+        .filter((s) => s.type === "text")
+        .flatMap((s) => s.parts);
+    const text = parts.map((p) => p.text).join("");
+    return { parts, text };
+};
+/** Extracts all file attachment parts from segments. */
+export const getFileParts = (segments) => segments
+    .filter((s) => s.type === "file")
+    .flatMap((s) => s.parts);
+// Chain/reasoning/source extraction (and ask-user extraction) is the consuming
+// app's concern — grouping conventions, header formats, and dedup rules are
+// product policy. This package ships only the generic segmentation above.

package/dist/nav/index.d.ts

@@ -0,0 +1,4 @@
+export * as Nav from "./index.parts.js";
+export type { NavActionProps, NavGroupProps, NavGroupState, NavGuide, NavIconProps, NavItemProps, NavItemState, NavLabelProps, NavListProps, NavListState, NavPartState, NavRootProps, NavToggleProps, NavToggleState, NavTriggerProps, NavTriggerState, } from "./nav.js";
+export type { NavState, NavStore } from "./store.js";
+export { useNav, useNavStore } from "./store.js";

package/dist/nav/index.js

@@ -0,0 +1,5 @@
+// Public surface of @intentface/ui/nav: the `Nav` namespace plus the store and
+// persistence building blocks. No "use client" directive here — see
+// index.parts.ts.
+export * as Nav from "./index.parts.js";
+export { useNav, useNavStore } from "./store.js";

package/dist/nav/index.parts.d.ts

@@ -0,0 +1,3 @@
+export { NavAction as Action, NavGroup as Group, NavIcon as Icon, NavItem as Item, NavLabel as Label, NavList as List, NavRoot as Root, NavToggle as Toggle, NavTrigger as Trigger, } from "./nav.js";
+/** Create a standalone store handle: `<Nav.Root store={…}>` plus `useNavStore(store, selector)` for reading it from outside the tree. */
+export { createNavStore as createStore } from "./store.js";

package/dist/nav/index.parts.js

@@ -0,0 +1,7 @@
+// Part names for the `Nav` namespace. Deliberately carries no "use client"
+// directive: this module and index.ts must stay server-resolvable so a React
+// Server Component can reach Nav.Root and its siblings through them. Each part
+// module carries the directive itself.
+export { NavAction as Action, NavGroup as Group, NavIcon as Icon, NavItem as Item, NavLabel as Label, NavList as List, NavRoot as Root, NavToggle as Toggle, NavTrigger as Trigger, } from "./nav.js";
+/** Create a standalone store handle: `<Nav.Root store={…}>` plus `useNavStore(store, selector)` for reading it from outside the tree. */
+export { createNavStore as createStore } from "./store.js";

package/dist/nav/nav.d.ts

@@ -0,0 +1,152 @@
+import { type ReactNode } from "react";
+import type { PrimitiveProps } from "../internal/primitive-props.js";
+import { type TransitionStatus } from "../internal/render/transition.js";
+import type { NavStore } from "./store.js";
+/**
+ * What a list draws down its left edge, as a ladder rather than three flags.
+ *
+ * Each rung implies the one before it — a rail lives in the indent lane, an
+ * elbow needs a rail to turn off — so they were never independent, and
+ * expressing them as booleans meant guarding against combinations that mean
+ * nothing.
+ */
+export type NavGuide = "none" | "indent" | "rail" | "branches";
+export type NavPartState = {
+    /** How deeply nested this part's list is. 0 is the top level. */
+    depth: number;
+    nested: boolean;
+};
+export type NavListState = NavPartState & {
+    guide: NavGuide;
+    /** Always true for a top-level list — only a group's list collapses. */
+    open: boolean;
+    transitionStatus: TransitionStatus;
+};
+export type NavItemState = NavPartState & {
+    active: boolean;
+    disabled: boolean;
+};
+export type NavGroupState = NavPartState & {
+    open: boolean;
+};
+export type NavTriggerState = NavGroupState & {
+    active: boolean;
+    disabled: boolean;
+};
+export type NavRootProps = PrimitiveProps<"div", NavPartState> & {
+    /** Groups open when nothing controls them. Read it from the request on the
+     *  server, if you persist it, so the first paint is already right. Nothing
+     *  here reads storage — `onExpandedChange` is the other half. */
+    defaultExpanded?: string[];
+    expanded?: string[];
+    onExpandedChange?: (expanded: string[]) => void;
+    /** An explicit `Nav.createStore()` handle. Must be stable for the Root's life. */
+    store?: NavStore;
+    /** What every list draws down its left edge, unless it says otherwise. */
+    guide?: NavGuide;
+    /** Wrap at the ends when arrowing past the first or last row. */
+    loop?: boolean;
+    /** Disables every row at once — a read-only view of the tree. */
+    disabled?: boolean;
+    /** Seek a row by typing its label. */
+    typeahead?: boolean;
+    children?: ReactNode;
+};
+/**
+ * The provider and container. Owns the keyboard handling for the whole tree,
+ * so roving focus and typeahead work without any row registering itself.
+ * Renders a `<div>` element.
+ */
+export declare const NavRoot: ({ defaultExpanded, expanded, onExpandedChange, store: storeProp, guide, loop, disabled, typeahead, className, render, style, ...elementProps }: NavRootProps) => import("react").JSX.Element;
+export type NavListProps = PrimitiveProps<"div", NavListState> & {
+    /**
+     * What this list draws down its left edge, overriding the Root's default:
+     * `"indent"` for space alone, `"rail"` for a line down it, `"branches"` to
+     * turn that line into each row that forks.
+     *
+     * Draw them yourself from `data-indent` / `data-rail` / `data-branches` — the
+     * package publishes the signal, never the geometry.
+     */
+    guide?: NavGuide;
+    /** Keep a collapsed list in the DOM behind `hidden="until-found"`, so the
+     *  browser's find-in-page can reveal it. Costs the rows staying mounted. */
+    keepMounted?: boolean;
+    children?: ReactNode;
+};
+/**
+ * A level of the tree. A list inside a group is that group's collapsible
+ * panel; a top-level list is not collapsible, having no trigger above it.
+ * Renders a `<div>` element.
+ */
+export declare const NavList: ({ guide, keepMounted, className, render, style, ...elementProps }: NavListProps) => import("react").JSX.Element | null;
+export type NavGroupProps = PrimitiveProps<"div", NavGroupState> & {
+    /** Identifies the group in the expanded set, and in persistence. */
+    value: string;
+    disabled?: boolean;
+    children?: ReactNode;
+};
+/**
+ * A collapsible branch. Recursive by construction — a group's list may hold
+ * further groups, to any depth, with no second set of parts for the nesting.
+ */
+export declare const NavGroup: ({ value, disabled, className, render, style, ...elementProps }: NavGroupProps) => import("react").JSX.Element;
+export type NavItemProps = PrimitiveProps<"div", NavItemState> & {
+    /** Identifies the row for roving focus and typeahead. */
+    value: string;
+    /** The route this row points at is the one being shown. */
+    active?: boolean;
+    disabled?: boolean;
+    children?: ReactNode;
+};
+/**
+ * A leaf row. A `div[role="button"]` rather than an anchor, so an action can
+ * sit inside it — swap the element with `render={<Link href="…" />}` when you
+ * want a real navigation, or handle `onClick` and route yourself.
+ */
+export declare const NavItem: ({ value, active, disabled, className, render, style, ...elementProps }: NavItemProps) => import("react").ReactElement<unknown, string | import("react").JSXElementConstructor<any>>;
+export type NavTriggerProps = PrimitiveProps<"div", NavTriggerState> & {
+    active?: boolean;
+    disabled?: boolean;
+    children?: ReactNode;
+};
+/**
+ * The row that opens a group — its heading and its disclosure in one, because
+ * in a sidebar they are the same thing you click. Takes no `value`: it belongs
+ * to the group it is written inside.
+ *
+ * Put a `Nav.Toggle` inside it and the two come apart: pressing the row
+ * activates it like `Nav.Item`, and the caret opens the group and carries
+ * `aria-expanded`. The arrow keys open and close it from the row either way.
+ */
+export declare const NavTrigger: ({ active, disabled, className, render, style, ...elementProps }: NavTriggerProps) => import("react").JSX.Element;
+export type NavToggleState = NavPartState & {
+    open: boolean;
+    disabled: boolean;
+};
+export type NavToggleProps = PrimitiveProps<"div", NavToggleState> & {
+    children?: ReactNode;
+};
+/**
+ * The caret inside a row — the control that opens a branch whose row is also a
+ * page. Mounting it makes pressing the row activate the page. Out of the roving
+ * order, like `Nav.Action`, since the arrow keys already open the group from
+ * the row, and it stops every event it handles: anything that escaped would
+ * activate the row, or follow its link, on its way out of opening the group.
+ */
+export declare const NavToggle: ({ className, render, style, ...elementProps }: NavToggleProps) => import("react").ReactElement<unknown, string | import("react").JSXElementConstructor<any>>;
+export type NavLabelProps = PrimitiveProps<"span", NavPartState>;
+/** The row's text. Its own element so it can truncate while the row does not. */
+export declare const NavLabel: ({ className, render, style, ...elementProps }: NavLabelProps) => import("react").ReactElement<unknown, string | import("react").JSXElementConstructor<any>>;
+export type NavIconProps = PrimitiveProps<"span", NavPartState>;
+/** Decoration. `aria-hidden`, so it stays out of the row's accessible name. */
+export declare const NavIcon: ({ className, render, style, ...elementProps }: NavIconProps) => import("react").ReactElement<unknown, string | import("react").JSXElementConstructor<any>>;
+export type NavActionProps = PrimitiveProps<"div", NavPartState> & {
+    children?: ReactNode;
+};
+/**
+ * A control inside a row — the "…" that opens a menu. Out of the roving order,
+ * so arrowing walks rows rather than stopping at every affordance, and it stops
+ * every event it handles: anything that escaped would activate the row on its
+ * way out of opening the menu.
+ */
+export declare const NavAction: ({ className, render, style, ...elementProps }: NavActionProps) => import("react").ReactElement<unknown, string | import("react").JSXElementConstructor<any>>;