harebear-ui 0.7.0 → 0.8.1

package/dist/components/ai/assistant.d.ts

@@ -0,0 +1,94 @@
+import { SpeechSource } from "./dictation.js";
+import * as React from "react";
+export interface AssistantMessage {
+  id: string;
+  role: "user" | "assistant";
+  /** Text or nodes: Prose, ActionReceipts, ToolSteps. */
+  content: React.ReactNode;
+}
+/** What the open page tells the assistant: use it as context, and its suggestions fill the dock's empty state. */
+export interface AssistantPage {
+  /** Stable key for the page, e.g. the route. */
+  id: string;
+  title?: string;
+  /** Anything the send handler needs: the open list, the selected record. */
+  data?: unknown;
+  suggestions?: string[];
+}
+export interface AssistantSendContext {
+  page: AssistantPage | null;
+  /** The conversation before this message. */
+  messages: AssistantMessage[];
+  /** Add a message (a streamed reply, a receipt) while the handler runs. Returns its id. */
+  append: (message: Omit<AssistantMessage, "id"> & {
+    id?: string;
+  }) => string;
+  /** Replace a message's content, e.g. while a reply streams in. */
+  update: (id: string, content: React.ReactNode) => void;
+}
+export interface AssistantContextValue {
+  open: boolean;
+  setOpen: (open: boolean) => void;
+  toggle: () => void;
+  messages: AssistantMessage[];
+  /** True while the send handler runs. */
+  pending: boolean;
+  page: AssistantPage | null;
+  setPage: (page: AssistantPage | null) => void;
+  /** Adds the user message, opens the dock and runs the app's onSend. */
+  send: (text: string) => Promise<void>;
+  append: AssistantSendContext["append"];
+  update: AssistantSendContext["update"];
+  clear: () => void;
+}
+export interface AssistantProviderProps {
+  /**
+   * The app's send handler. Return the reply (text or nodes) to append it, or call `append` / `update` yourself
+   * (for streaming or receipts) and return nothing. A thrown error is shown as the reply.
+   */
+  onSend: (text: string, context: AssistantSendContext) => React.ReactNode | Promise<React.ReactNode>;
+  initialMessages?: AssistantMessage[];
+  defaultOpen?: boolean;
+  children?: React.ReactNode;
+}
+/**
+ * Keeps one assistant conversation across pages: open state, messages, the open page as context, and the app's
+ * send handler. Mount it above the router outlet; read it with useAssistant().
+ */
+declare function AssistantProvider({ onSend, initialMessages, defaultOpen, children }: AssistantProviderProps): React.JSX.Element;
+/** The assistant state from AssistantProvider. Throws outside one. */
+export declare function useAssistant(): AssistantContextValue;
+/**
+ * Tells the assistant which page is open, for as long as the calling component is mounted. The page is replaced
+ * when `page.id` changes; other fields are read at send time.
+ */
+export declare function useAssistantPage(page: AssistantPage): void;
+export interface AssistantDockProps extends Omit<React.ComponentProps<"section">, "title"> {
+  /** Assistant name in the header and launcher, e.g. "HomeBot". Default "Assistant". */
+  title?: string;
+  /** Header and launcher icon. Default a sparkle. */
+  icon?: React.ReactNode;
+  /** Link to the full-screen chat. Shows an expand button in the header. */
+  fullScreenHref?: string;
+  /** Empty state heading. Default "How can I help?". */
+  emptyTitle?: React.ReactNode;
+  /** Empty state line under the heading. */
+  emptyDescription?: React.ReactNode;
+  /** Suggestion pills in the empty state. Default: the open page's suggestions. */
+  suggestions?: string[];
+  /** Composer placeholder. Default `Ask ${title}`. */
+  placeholder?: string;
+  /** Speech source for the mic. Default the browser's; `false` hides the mic. */
+  dictation?: SpeechSource | false;
+  /** Show the floating launcher button while closed. Default true. Turn off when another control opens it. */
+  launcher?: boolean;
+  /** Label of the launcher. Default `Ask ${title}`. */
+  launcherLabel?: string;
+}
+/**
+ * The assistant as a floating panel over the page (it never reflows the page): header, empty state with
+ * suggestions, message list, AskBox. A soft launcher button opens it. Escape closes it. Needs AssistantProvider.
+ * Sits above AppNav's phone tab bar.
+ */
+declare function AssistantDock({ title, icon, fullScreenHref, emptyTitle, emptyDescription, suggestions, placeholder, dictation, launcher, launcherLabel, className, ...props }: AssistantDockProps): React.JSX.Element | null;
+export { AssistantDock, AssistantProvider };

package/dist/components/ai/assistant.js

@@ -0,0 +1,231 @@
+"use client";
+import { AskBox } from "./ask-box.js";
+import { AssistantAvatar, ChatMessage, ChatThread, TypingIndicator } from "./chat.js";
+import { Button } from "../ui/button.js";
+import { useToastClearance } from "../../lib/toast-clearance.js";
+import { cn } from "../../lib/utils.js";
+import * as React from "react";
+import { jsx, jsxs } from "react/jsx-runtime";
+import { Maximize2Icon, SparklesIcon, XIcon } from "lucide-react";
+// src/components/ai/assistant.tsx
+const AssistantContext = React.createContext(null);
+let nextId = 0;
+const newId = () => `m${Date.now().toString(36)}${(nextId++).toString(36)}`;
+/**
+* Keeps one assistant conversation across pages: open state, messages, the open page as context, and the app's
+* send handler. Mount it above the router outlet; read it with useAssistant().
+*/
+function AssistantProvider({ onSend, initialMessages = [], defaultOpen = false, children }) {
+	const [open, setOpen] = React.useState(defaultOpen);
+	const [messages, setMessages] = React.useState(initialMessages);
+	const [pending, setPending] = React.useState(false);
+	const [page, setPage] = React.useState(null);
+	const messagesRef = React.useRef(messages);
+	messagesRef.current = messages;
+	const pageRef = React.useRef(page);
+	pageRef.current = page;
+	const onSendRef = React.useRef(onSend);
+	onSendRef.current = onSend;
+	const append = React.useCallback((m) => {
+		const id = m.id ?? newId();
+		setMessages((list) => [...list, {
+			...m,
+			id
+		}]);
+		return id;
+	}, []);
+	const update = React.useCallback((id, content) => {
+		setMessages((list) => list.map((m) => m.id === id ? {
+			...m,
+			content
+		} : m));
+	}, []);
+	const send = React.useCallback(async (text) => {
+		const before = messagesRef.current;
+		append({
+			role: "user",
+			content: text
+		});
+		setOpen(true);
+		setPending(true);
+		try {
+			const reply = await onSendRef.current(text, {
+				page: pageRef.current,
+				messages: before,
+				append,
+				update
+			});
+			if (reply !== void 0 && reply !== null && reply !== false) append({
+				role: "assistant",
+				content: reply
+			});
+		} catch (e) {
+			append({
+				role: "assistant",
+				content: e instanceof Error ? e.message : "Something went wrong."
+			});
+		} finally {
+			setPending(false);
+		}
+	}, [append, update]);
+	const value = React.useMemo(() => ({
+		open,
+		setOpen,
+		toggle: () => setOpen((v) => !v),
+		messages,
+		pending,
+		page,
+		setPage,
+		send,
+		append,
+		update,
+		clear: () => setMessages([])
+	}), [
+		open,
+		messages,
+		pending,
+		page,
+		send,
+		append,
+		update
+	]);
+	return /* @__PURE__ */ jsx(AssistantContext.Provider, {
+		value,
+		children
+	});
+}
+/** The assistant state from AssistantProvider. Throws outside one. */
+function useAssistant() {
+	const ctx = React.useContext(AssistantContext);
+	if (!ctx) throw new Error("useAssistant must be used inside <AssistantProvider>");
+	return ctx;
+}
+/**
+* Tells the assistant which page is open, for as long as the calling component is mounted. The page is replaced
+* when `page.id` changes; other fields are read at send time.
+*/
+function useAssistantPage(page) {
+	const { setPage } = useAssistant();
+	const latest = React.useRef(page);
+	latest.current = page;
+	React.useEffect(() => {
+		setPage(latest.current);
+		return () => setPage(null);
+	}, [page.id, setPage]);
+}
+/**
+* The assistant as a floating panel over the page (it never reflows the page): header, empty state with
+* suggestions, message list, AskBox. A soft launcher button opens it. Escape closes it. Needs AssistantProvider.
+* Sits above AppNav's phone tab bar.
+*/
+function AssistantDock({ title = "Assistant", icon = /* @__PURE__ */ jsx(SparklesIcon, {}), fullScreenHref, emptyTitle = "How can I help?", emptyDescription, suggestions, placeholder, dictation, launcher = true, launcherLabel, className, ...props }) {
+	const { open, setOpen, messages, pending, page, send } = useAssistant();
+	const [draft, setDraft] = React.useState("");
+	const titleId = React.useId();
+	const panelRef = React.useRef(null);
+	const launcherRef = React.useRef(null);
+	const wasOpen = React.useRef(open);
+	const pills = suggestions ?? page?.suggestions ?? [];
+	React.useEffect(() => {
+		if (open && !wasOpen.current) panelRef.current?.querySelector("textarea")?.focus();
+		if (!open && wasOpen.current) launcherRef.current?.focus();
+		wasOpen.current = open;
+	}, [open]);
+	const submit = (text) => {
+		if (pending) return;
+		setDraft("");
+		panelRef.current?.querySelector("textarea")?.focus();
+		send(text);
+	};
+	useToastClearance("--hb-toast-launcher", "3.5rem", !open && launcher);
+	if (!open) {
+		if (!launcher) return null;
+		return /* @__PURE__ */ jsxs("button", {
+			ref: launcherRef,
+			type: "button",
+			"data-slot": "assistant-launcher",
+			"aria-expanded": false,
+			onClick: () => setOpen(true),
+			className: "fixed right-4 bottom-[calc(var(--hb-bottom-inset,0px)+var(--hb-fab-inset,0px)+1rem)] z-40 flex h-12 items-center gap-2 rounded-full border border-border bg-card pr-5 pl-2 text-sm font-medium text-foreground shadow-card outline-none hover:bg-muted focus-visible:ring-4 focus-visible:ring-ring/20 md:right-6 md:bottom-6",
+			children: [/* @__PURE__ */ jsx(AssistantAvatar, { icon }), launcherLabel ?? `Ask ${title}`]
+		});
+	}
+	return /* @__PURE__ */ jsxs("section", {
+		ref: panelRef,
+		"data-slot": "assistant-dock",
+		role: "dialog",
+		"aria-modal": "false",
+		"aria-labelledby": titleId,
+		onKeyDown: (e) => {
+			if (e.key === "Escape") {
+				e.stopPropagation();
+				setOpen(false);
+			}
+		},
+		className: cn("fixed inset-x-2 bottom-[calc(var(--hb-bottom-inset,0px)+0.5rem)] z-40 flex h-[min(40rem,calc(100dvh-var(--hb-bottom-inset,0px)-1rem))] flex-col overflow-hidden rounded-2xl border border-border bg-card shadow-card duration-200 animate-in fade-in slide-in-from-bottom-4 motion-reduce:animate-none sm:inset-x-auto sm:right-4 sm:w-104 md:right-6 md:bottom-6 md:h-[min(40rem,calc(100dvh-3rem))]", className),
+		...props,
+		children: [
+			/* @__PURE__ */ jsxs("header", {
+				className: "flex items-center gap-2.5 py-2.5 pr-2.5 pl-4",
+				children: [
+					/* @__PURE__ */ jsx(AssistantAvatar, { icon }),
+					/* @__PURE__ */ jsx("h2", {
+						id: titleId,
+						className: "min-w-0 flex-1 truncate text-[15px] font-semibold",
+						children: title
+					}),
+					fullScreenHref && /* @__PURE__ */ jsx(Button, {
+						asChild: true,
+						variant: "ghost",
+						size: "icon",
+						shape: "pill",
+						children: /* @__PURE__ */ jsx("a", {
+							href: fullScreenHref,
+							"aria-label": "Open full screen",
+							children: /* @__PURE__ */ jsx(Maximize2Icon, {})
+						})
+					}),
+					/* @__PURE__ */ jsx(Button, {
+						variant: "ghost",
+						size: "icon",
+						shape: "pill",
+						"aria-label": `Close ${title}`,
+						onClick: () => setOpen(false),
+						children: /* @__PURE__ */ jsx(XIcon, {})
+					})
+				]
+			}),
+			messages.length === 0 ? /* @__PURE__ */ jsxs("div", {
+				"data-slot": "assistant-dock-empty",
+				className: "flex flex-1 flex-col justify-end gap-1 overflow-y-auto px-5 pb-3",
+				children: [/* @__PURE__ */ jsx("p", {
+					className: "text-lg font-semibold",
+					children: emptyTitle
+				}), emptyDescription && /* @__PURE__ */ jsx("p", {
+					className: "text-sm text-muted-foreground",
+					children: emptyDescription
+				})]
+			}) : /* @__PURE__ */ jsxs(ChatThread, {
+				className: "px-4 pt-2",
+				contentClassName: "gap-5",
+				children: [messages.map((m) => /* @__PURE__ */ jsx(ChatMessage, {
+					role: m.role,
+					avatar: false,
+					children: m.content
+				}, m.id)), pending && /* @__PURE__ */ jsx(TypingIndicator, { label: "Working" })]
+			}),
+			/* @__PURE__ */ jsx("div", {
+				className: "px-3 pt-2 pb-3",
+				children: /* @__PURE__ */ jsx(AskBox, {
+					value: draft,
+					onValueChange: setDraft,
+					onSubmit: submit,
+					placeholder: placeholder ?? `Ask ${title}`,
+					suggestions: messages.length === 0 ? pills : void 0,
+					dictation
+				})
+			})
+		]
+	});
+}
+export { AssistantDock, AssistantProvider, useAssistant, useAssistantPage };

package/dist/components/ai/dictation.d.ts

@@ -0,0 +1,57 @@
+import * as React from "react";
+export interface SpeechSourceHandlers {
+  /** Recognised text. `final` is false for interim guesses that may still change. */
+  onResult: (text: string, final: boolean) => void;
+  /** Listening stopped (silence, stop(), or an error). */
+  onEnd: () => void;
+  onError: (error: string) => void;
+}
+/**
+ * Where dictation comes from. The default is `browserSpeechSource` (the Web Speech API); pass your own to use a
+ * server model: start recording in `start`, call the handlers, and return a function that stops.
+ */
+export interface SpeechSource {
+  isSupported: () => boolean;
+  start: (handlers: SpeechSourceHandlers, options: {
+    lang?: string;
+  }) => () => void;
+}
+/** SpeechSource on the browser's SpeechRecognition API. Unsupported (Firefox, most WebViews) means no mic button. */
+export declare const browserSpeechSource: SpeechSource;
+export interface UseDictationOptions {
+  /** Default browserSpeechSource. */
+  source?: SpeechSource;
+  /** BCP 47 language, e.g. "en-CA". Default: the browser's. */
+  lang?: string;
+  /** Called with each final transcript. */
+  onTranscript: (text: string) => void;
+}
+/** Dictation state for a custom control: `{ supported, listening, interim, error, start, stop }`. */
+export declare function useDictation({ source, lang, onTranscript }: UseDictationOptions): {
+  supported: boolean;
+  listening: boolean;
+  interim: string;
+  error: string | null;
+  start: () => void;
+  stop: () => void;
+};
+export interface DictationButtonProps extends Omit<React.ComponentProps<"div">, "onSubmit"> {
+  /** The composer's current text. Empty shows the mic; text shows send. */
+  value: string;
+  /** Final transcripts, to append to the text. */
+  onTranscript: (text: string) => void;
+  /** Send. Without it, the send button is a submit button for the surrounding form. */
+  onSend?: () => void;
+  source?: SpeechSource;
+  lang?: string;
+  disabled?: boolean;
+  /** Default "Send message". */
+  sendLabel?: string;
+}
+/**
+ * One round button for a composer: a mic when empty, stop (with listening bars) while listening, send once there is
+ * text. Announces "Listening" in a polite live region. Without a supported speech source the mic is hidden and the
+ * button is just send.
+ */
+declare function DictationButton({ value, onTranscript, onSend, source, lang, disabled, sendLabel, className, ...props }: DictationButtonProps): React.JSX.Element;
+export { DictationButton };

package/dist/components/ai/dictation.js

@@ -0,0 +1,148 @@
+"use client";
+import { Button } from "../ui/button.js";
+import { cn } from "../../lib/utils.js";
+import * as React from "react";
+import { jsx, jsxs } from "react/jsx-runtime";
+import { ArrowUpIcon, MicIcon } from "lucide-react";
+// src/components/ai/dictation.tsx
+function recognitionCtor() {
+	if (typeof window === "undefined") return void 0;
+	const w = window;
+	return w.SpeechRecognition ?? w.webkitSpeechRecognition;
+}
+/** SpeechSource on the browser's SpeechRecognition API. Unsupported (Firefox, most WebViews) means no mic button. */
+const browserSpeechSource = {
+	isSupported: () => recognitionCtor() !== void 0,
+	start(handlers, { lang }) {
+		const Ctor = recognitionCtor();
+		if (!Ctor) {
+			handlers.onError("not-supported");
+			handlers.onEnd();
+			return () => {};
+		}
+		const rec = new Ctor();
+		if (lang) rec.lang = lang;
+		rec.interimResults = true;
+		rec.continuous = false;
+		rec.onresult = (e) => {
+			for (let i = e.resultIndex; i < e.results.length; i++) {
+				const r = e.results[i];
+				if (r) handlers.onResult(r[0].transcript, r.isFinal);
+			}
+		};
+		rec.onerror = (e) => handlers.onError(e.error);
+		rec.onend = () => handlers.onEnd();
+		rec.start();
+		return () => rec.stop();
+	}
+};
+const noopSubscribe = () => () => {};
+/** Dictation state for a custom control: `{ supported, listening, interim, error, start, stop }`. */
+function useDictation({ source = browserSpeechSource, lang, onTranscript }) {
+	const supported = React.useSyncExternalStore(noopSubscribe, source.isSupported, () => false);
+	const [listening, setListening] = React.useState(false);
+	const [interim, setInterim] = React.useState("");
+	const [error, setError] = React.useState(null);
+	const stopRef = React.useRef(null);
+	const onTranscriptRef = React.useRef(onTranscript);
+	onTranscriptRef.current = onTranscript;
+	const stop = React.useCallback(() => {
+		stopRef.current?.();
+	}, []);
+	const start = React.useCallback(() => {
+		if (stopRef.current) return;
+		setError(null);
+		setInterim("");
+		setListening(true);
+		stopRef.current = source.start({
+			onResult: (text, final) => {
+				if (final) {
+					setInterim("");
+					onTranscriptRef.current(text.trim());
+				} else setInterim(text);
+			},
+			onError: (e) => setError(e),
+			onEnd: () => {
+				stopRef.current = null;
+				setInterim("");
+				setListening(false);
+			}
+		}, { lang });
+	}, [source, lang]);
+	React.useEffect(() => () => stopRef.current?.(), []);
+	return {
+		supported,
+		listening,
+		interim,
+		error,
+		start,
+		stop
+	};
+}
+/**
+* One round button for a composer: a mic when empty, stop (with listening bars) while listening, send once there is
+* text. Announces "Listening" in a polite live region. Without a supported speech source the mic is hidden and the
+* button is just send.
+*/
+function DictationButton({ value, onTranscript, onSend, source, lang, disabled, sendLabel = "Send message", className, ...props }) {
+	const d = useDictation({
+		source,
+		lang,
+		onTranscript
+	});
+	const hasText = value.trim().length > 0;
+	return /* @__PURE__ */ jsxs("div", {
+		"data-slot": "dictation-button",
+		className: cn("flex shrink-0 items-center", className),
+		...props,
+		children: [/* @__PURE__ */ jsx("span", {
+			role: "status",
+			"aria-live": "polite",
+			className: "sr-only",
+			children: d.listening ? "Listening" : ""
+		}), d.listening ? /* @__PURE__ */ jsx(Button, {
+			type: "button",
+			size: "icon",
+			shape: "pill",
+			className: "size-10 gap-0.5",
+			"aria-label": "Stop dictation",
+			onClick: d.stop,
+			children: /* @__PURE__ */ jsx(ListeningBars, {})
+		}) : !hasText && d.supported ? /* @__PURE__ */ jsx(Button, {
+			type: "button",
+			variant: "ghost",
+			size: "icon",
+			shape: "pill",
+			className: "size-10",
+			"aria-label": "Dictate",
+			disabled,
+			onClick: d.start,
+			children: /* @__PURE__ */ jsx(MicIcon, {})
+		}) : /* @__PURE__ */ jsx(Button, {
+			type: onSend ? "button" : "submit",
+			size: "icon",
+			shape: "pill",
+			className: "size-10",
+			"aria-label": sendLabel,
+			disabled: disabled || !hasText,
+			onClick: onSend,
+			children: /* @__PURE__ */ jsx(ArrowUpIcon, {})
+		})]
+	});
+}
+function ListeningBars() {
+	return /* @__PURE__ */ jsx("span", {
+		"aria-hidden": "true",
+		className: "flex h-4 items-center gap-0.5",
+		children: [
+			0,
+			150,
+			300,
+			450
+		].map((delay) => /* @__PURE__ */ jsx("span", {
+			className: "h-full w-0.75 origin-center animate-listening rounded-full bg-current motion-reduce:scale-y-75",
+			style: { animationDelay: `${delay}ms` }
+		}, delay))
+	});
+}
+export { DictationButton, browserSpeechSource, useDictation };

package/dist/components/data/sectioned-list.d.ts

@@ -0,0 +1,37 @@
+import { TaskRowAssignee } from "./task-row.js";
+import * as React from "react";
+export interface SectionedListItem {
+  id: string;
+  title: React.ReactNode;
+  meta?: React.ReactNode;
+  done?: boolean;
+  important?: boolean;
+  assignee?: TaskRowAssignee;
+}
+export interface SectionedListSection {
+  id: string;
+  /** Section heading, e.g. "Today" or "Groceries". Omit for a section without one. */
+  title?: React.ReactNode;
+  items: SectionedListItem[];
+}
+export interface SectionedListProps extends Omit<React.ComponentProps<"div">, "onToggle"> {
+  sections: SectionedListSection[];
+  /** Called when an item's check changes. Update `done` in your data; the row folds away by itself. */
+  onToggle: (id: string, done: boolean) => void;
+  /** Makes item titles buttons, e.g. to open a DetailSheet. */
+  onOpen?: (id: string) => void;
+  /** Shows one add box at the top. Called with the trimmed text on Enter. */
+  onAdd?: (text: string) => void;
+  /** Add box placeholder and label. Default "Add a to-do". */
+  addPlaceholder?: string;
+  /** Shown when no item is open, e.g. <Empty /> or a line of text. */
+  empty?: React.ReactNode;
+  /** Start with the done items shown. Default false. */
+  defaultShowDone?: boolean;
+}
+/**
+ * A to-do list: one add box, sections with headings, done items folded into a "Show N done" toggle, an empty
+ * state. Rows fold in and out with Collapse, so nothing jumps.
+ */
+declare function SectionedList({ sections, onToggle, onOpen, onAdd, addPlaceholder, empty, defaultShowDone, className, ...props }: SectionedListProps): React.JSX.Element;
+export { SectionedList };