akanjs 3.0.0-beta.2 → 3.0.0-beta.20

package/ui/Agent/voice.ts

@@ -1,38 +1,27 @@
-/** A recognition run in progress. `stop` ends it; a final result may still arrive after. */
+/** A final result may still arrive after `stop`. */
 export interface VoiceListener {
   stop: () => void;
 }
 
-/** One utterance being spoken. `cancel` is barge-in; `done` resolves when it finished or was cancelled. */
+/** `done` resolves when the utterance finished or was cancelled. */
 export interface VoiceSpeech {
   cancel: () => void;
   done: Promise<void>;
 }
 
 export interface VoiceHandlers {
-  /** Partial text while the user is still speaking. An engine without interim results simply never calls it. */
+  /** Partial text while the user is still speaking; an engine without interim results never calls it. */
   onInterim?: (text: string) => void;
   onFinal: (text: string) => void;
   onError: (message: string) => void;
 }
 
-/**
- * The seam a voice engine fills — one contract, whatever is behind it: the browser's own recognition, a cloud
- * STT/TTS pair, or a native plugin. The engine speaks and listens; **the framework owns the policy** — when to
- * listen, what to speak, sentence chunking, barge-in, and whether a reply is spoken at all.
- *
- * Shaped as a subscription rather than `listen(): Promise<string>` on purpose. A promise fits push-to-talk and
- * nothing else, and continuous listening could then only arrive as a breaking change; this shape carries both, so
- * hands-free is a later policy decision instead of a later contract.
- *
- * `listen` must be reachable from the click that starts it: microphone permission and, on iOS, the first
- * `speechSynthesis` utterance are both gated on a user gesture.
- */
+/** `listen` must run inside the click that starts it: mic permission and iOS's first utterance need a user gesture. */
 export interface VoiceEngine {
   listen: (handlers: VoiceHandlers) => VoiceListener;
-  /** One sentence at a time, already stripped of markdown. The framework queues; the engine speaks. */
+  /** Handed one markdown-free sentence at a time; the framework queues. */
   speak: (text: string) => VoiceSpeech;
-  /** Answering false hides the controls — a screen that cannot listen should not offer a microphone. */
+  /** `false` hides the microphone. */
   available?: () => boolean;
 }
 
@@ -45,16 +34,6 @@ const link = /\[([^\]]*)\]\([^)]*\)/g;
 const emphasis = /(\*\*\*|\*\*|\*|___|__|_|~~)/g;
 const inlineCode = /`([^`]*)`/g;
 
-/**
- * What of a model's answer should be read aloud.
- *
- * Code blocks, tables, and rules are dropped rather than spoken: a fence read character by character is noise,
- * and a table read cell by cell is worse than silence — in push-to-talk the user is looking at the screen that
- * already renders both. Inline code keeps its content, because that is usually a name worth hearing.
- *
- * Monotonic over a growing source, which is what lets the reader below track one offset: new text never changes
- * how earlier text was rendered, since a fence marker always arrives before the lines it swallows.
- */
 export const speechText = (markdown: string): string => {
   const lines = markdown.replace(/\r\n?/g, "\n").split("\n");
   const kept: string[] = [];
@@ -76,16 +55,8 @@ export const speechText = (markdown: string): string => {
   return kept.join("\n");
 };
 
-/** A terminator counts only with whitespace behind it, so `1.5` is not a sentence and a stream is never cut early. */
 const sentenceEnd = /[.!?。！？…]+\s|\n/g;
 
-/**
- * Reads an assistant answer aloud as it streams in, one sentence at a time.
- *
- * Sentence-at-a-time rather than delta-at-a-time because a delta cuts words in half, and whole-message-at-a-time
- * because that waits for the turn to end. The offset is over `speechText` output, not the raw source, so a code
- * block that arrives mid-answer costs nothing.
- */
 export class VoiceReader {
   readonly #engine: () => VoiceEngine | undefined;
   #queue: string[] = [];
@@ -105,18 +76,12 @@ export class VoiceReader {
     this.#chunk(source, false);
   }
 
-  /**
-   * The turn ended: the last sentence has no whitespace behind it and would otherwise never be spoken. It still
-   * splits what is left, because a whole answer that arrived in one render must not be read as one long utterance.
-   */
+  /** The turn ended: also speaks the last sentence, which has no whitespace behind it. */
   flush(source: string) {
     this.#chunk(source, true);
   }
 
-  /**
-   * A line that is not part of the answer being tracked — the question or approval the loop parked on. It joins
-   * the same queue, so it is spoken after the sentence in flight rather than over it, and Stop still cancels it.
-   */
+  /** Queued behind the sentence in flight, outside the tracked answer; Stop still cancels it. */
   say(text: string) {
     this.#enqueue(speechText(text));
     this.#pump();

package/ui/Badge.tsx

@@ -8,10 +8,8 @@ export { type BadgeVariants, badgeRecipe };
 export type BadgeProps = HTMLAttributes<HTMLSpanElement> & BadgeVariants;
 
 const DefaultBadge = ({ className, variant, size, outline, ...rest }: BadgeProps) => {
-  
   const recipe = useUiRecipe("badge") ?? badgeRecipe;
   return <span className={recipe({ variant, size, outline }, className)} {...rest} />;
 };
 
-/** Status/label pill. Route-overridable via `page/**\/_overrides.tsx` (slot `Badge`). */
 export const Badge = createOverridable("Badge", DefaultBadge);

package/ui/BottomSheet.tsx

@@ -10,20 +10,17 @@ import { config, useSpring } from "react-spring";
 import { buttonRecipe } from "./Button";
 
 interface BottomSheetProps {
-  /** Additional classes for the sheet surface. */
   className?: string;
-  /** Additional classes for the scrolling body. */
   bodyClassName?: string;
-  /** Controlled open state. Left out, the sheet opens from its own trigger and handle. */
+  /** Left out, the sheet opens from its own trigger and handle. */
   open?: boolean;
   onCancel?: () => void;
-  /** Element that opens the sheet. */
   trigger?: ReactNode;
   /** Whole top row of the sheet, replacing the drag handle or the close row. */
   header?: ReactNode;
   /** The grab handle a `half` sheet draws. */
   handle?: ReactNode;
-  /** Element that closes a `full` sheet, inside the default header row. */
+  /** Closes a `full` sheet, inside the default header row. */
   close?: ReactNode;
   children: ReactNode;
   type: "full" | "half";

package/ui/Button.tsx

@@ -12,48 +12,20 @@ export { type ButtonVariants, buttonRecipe };
 
 export type ButtonProps<Result> = Omit<ButtonHTMLAttributes<HTMLButtonElement>, "onClick"> &
   ButtonVariants & {
-    /**
-     * Click handler. Returning a promise is what opts this button into the async states — a plain
-     * synchronous handler renders as an ordinary button with no spinner. Call onError to show the
-     * localized error state without throwing.
-     */
+    /** Returning a promise opts into the pending/success states; `onError` shows a localized error without throwing. */
     onClick?: (
       e: React.MouseEvent<HTMLButtonElement>,
       { onError }: { onError: (error: string) => void },
     ) => Promise<Result> | Result;
-    /** Called after the button briefly enters success state. */
+    /** Called after the brief success state. */
     onSuccess?: (result: Result) => void;
-    /**
-     * How the pending/success indicator is drawn. Both modes keep the button's box fixed — CSS cannot
-     * animate an auto width, so a resizing button can only ever snap.
-     *
-     * `hold` (default) fades a bare indicator over the children, so the box stays exactly the children's
-     * size. `replace` cross-fades to a labelled indicator ("Processing…"); both labels stay stacked in the
-     * DOM, so the box is the wider of the two from the start and still never moves — at the cost of an idle
-     * button that is as wide as its longest state.
-     */
+    /** `hold` (default) fades a bare indicator over the children; `replace` cross-fades to a labelled one and sizes
+     *  the box to the wider label. Either way the box never resizes. */
     loadingMode?: "hold" | "replace";
-    /** Whether a failed action renders its message under the button. Off leaves it to the framework toast. */
+    /** Whether a message passed to `onError` renders under the button. A thrown error is left to its thrower. */
     showError?: boolean;
   };
 
-/**
- * Success mark, entering with `checkIn` (akanjs/ui/styles.css — a 340ms fade plus a 6% overshoot; `pop`'s 1.5x
- * overshoot from zero reads as cartoonish on a glyph this small).
- *
- * The colour is derived from the button, never named — any fixed token fails somewhere: `text-success` vanishes
- * on a `success` button, and a `bg-success` disc lands an unrelated hue on every other fill.
- *
- * `AiFillCheckCircle` is a solid disc with the tick punched out, which is why it is used instead of an outline
- * glyph plus a tinted halo. The disc is `currentColor` (the button's foreground) and the tick is the fill
- * showing through, so the mark reuses the variant's own foreground/background pair — already contrast-checked
- * by themeValidator — at full strength. An earlier attempt put an outline tick on a low-alpha current-colour
- * halo, which did the opposite: tinting the local background toward the glyph's own colour *lowered* the
- * contrast that made the tick readable. (Do not name the class here — Tailwind's source scanner reads comments
- * too, so a class literal in prose compiles to a dead rule.)
- *
- * Sizing is in `em`, so one class covers `xs` through `lg`.
- */
 const successIconClass = "animate-checkIn text-[1.15em]";
 
 const successDwellMs = 700;
@@ -73,9 +45,8 @@ const DefaultButton = <Result = unknown>({
   ...rest
 }: ButtonProps<Result>) => {
   const { l } = usePage();
-  
   const recipe = useUiRecipe("button") ?? buttonRecipe;
-
+  
   const [state, setState] = useState<{
     mode: "idle" | "loading" | "success" | "error";
     error: string | null;
@@ -108,7 +79,6 @@ const DefaultButton = <Result = unknown>({
           void (async () => {
             try {
               const awaited = (await result) as Result;
-              
               if (errored) return;
               setState({ mode: "success", error: null, shown: "success" });
               setTimeout(() => {
@@ -117,14 +87,14 @@ const DefaultButton = <Result = unknown>({
                 onSuccess?.(awaited);
               }, successDwellMs);
             } catch {
-
+              
               setState((s) => ({ ...s, mode: "idle", error: null }));
             }
           })();
         }}
       >
         {loadingMode === "replace" ? (
-
+          
           <span className="grid place-items-center">
             <span
               className={cn(
@@ -183,13 +153,7 @@ const DefaultButton = <Result = unknown>({
   );
 };
 
-/**
- * Button whose async states are driven by the handler's return value: return a promise and it shows a
- * pending indicator, then a brief success state; return nothing and it behaves as a plain button. Resolves
- * to a route-scoped override when a `page/**\/_overrides.tsx` in the route's ancestry declares one,
- * otherwise renders {@link DefaultButton}. The public generic signature is preserved, so
- * `<Button<Todo> onSuccess={(r: Todo) => …} />` still infers.
- */
+/** A promise returned from `onClick` shows a pending indicator, then a brief success state. */
 export const Button = <Result = unknown>(props: ButtonProps<Result>) => {
   const Override = useUiOverride("Button");
   const Impl = (Override ?? DefaultButton) as unknown as ComponentType<ButtonProps<Result>>;

package/ui/ClientSide.tsx

@@ -1,9 +1,7 @@
 import { type ReactNode, Suspense } from "react";
 
 export interface ClientSideProps {
-  /** Content that should render inside a React Suspense boundary on the client. */
   children: ReactNode;
-  /** Optional Suspense fallback. */
   loading?: ReactNode;
 }
 export const ClientSide = ({ children, loading }: ClientSideProps) => {

package/ui/Clipboard.tsx

@@ -21,7 +21,6 @@ export const Clipboard = ({ text, className }: ClipboardProps): ReactElement =>
 
   const handleCopy = async () => {
     if (!text) return;
-    
     await navigator.clipboard.writeText(text);
     setIsCopied(true);
   };