@aphrody/m3-ai 3.3.2 → 3.3.5

package/src/ModelSelector.tsx

@@ -0,0 +1,319 @@
+// SPDX-License-Identifier: Apache-2.0 AND MIT
+// Derived from SpaceUI (packages/aphrody-spaceui/packages/ai/src/ModelSelector.tsx), MIT, rebuilt on Material Design 3.
+
+"use client";
+
+import { Popover, usePopover, SelectPill, type SelectPillProps } from "@aphrody/m3-primitives";
+import { clsx } from "clsx";
+import { forwardRef, useEffect, useMemo, useRef, useState } from "react";
+
+import { type ChatLabels, formatLabel, resolveChatLabels } from "./chatLabels";
+import { ChatIcon } from "./chatIcons";
+import { focusRing } from "./internal";
+import type { ModelOption } from "./types";
+
+export interface ModelSelectorProps {
+  /** Available models */
+  models: ModelOption[];
+  /** Currently selected model ID */
+  value: string;
+  /** Called when a model is selected */
+  onChange: (value: string) => void;
+  /** Placeholder when nothing selected */
+  placeholder?: string;
+  /** Search placeholder */
+  searchPlaceholder?: string;
+  /** SelectPill variant */
+  variant?: SelectPillProps["variant"];
+  /** SelectPill size */
+  size?: SelectPillProps["size"];
+  /** Controlled popover (optional) */
+  popover?: ReturnType<typeof usePopover>;
+  /** Additional trigger className */
+  className?: string;
+  /** Disabled state */
+  disabled?: boolean;
+  /** Visible strings; `placeholder` / `searchPlaceholder` win over them. English defaults. */
+  labels?: Partial<ChatLabels>;
+}
+
+/** Group models by provider, keeping the order of first appearance. */
+export function groupModelsByProvider(
+  models: ModelOption[],
+  search = "",
+): Record<string, ModelOption[]> {
+  const q = search.trim().toLowerCase();
+  const filtered = q
+    ? models.filter((m) => m.name.toLowerCase().includes(q) || m.provider.toLowerCase().includes(q))
+    : models;
+
+  return filtered.reduce(
+    (acc, model) => {
+      if (!acc[model.provider]) acc[model.provider] = [];
+      acc[model.provider].push(model);
+      return acc;
+    },
+    Object.create(null) as Record<string, ModelOption[]>,
+  );
+}
+
+export interface ModelOptionListProps {
+  /** Models grouped by provider (see {@link groupModelsByProvider}). */
+  grouped: Record<string, ModelOption[]>;
+  /** Currently selected model ID */
+  value: string;
+  /** Called when a model is picked */
+  onSelect: (value: string) => void;
+  className?: string;
+  labels?: Partial<ChatLabels>;
+}
+
+/**
+ * The M3 menu list of the model selector: provider section headers (`text-title-small`),
+ * 48 dp two-line items (`text-label-large` + `text-body-small` supporting text), the selected
+ * item on `secondary-container`, capabilities as small outlined chips.
+ */
+export function ModelOptionList({
+  grouped,
+  value,
+  onSelect,
+  className,
+  labels,
+}: ModelOptionListProps) {
+  const l = resolveChatLabels(labels);
+  const providers = Object.entries(grouped);
+  const models = providers.flatMap(([, providerModels]) => providerModels);
+  const [focusedId, setFocusedId] = useState(value);
+  const focusId = models.some((model) => model.id === focusedId)
+    ? focusedId
+    : (models.find((model) => model.id === value)?.id ?? models[0]?.id);
+  return (
+    <div
+      // oxlint-disable-next-line jsx-a11y/prefer-tag-over-role -- M3 menu whose options are rich rows (headers, supporting text, chips); a native <select>/<datalist> cannot render them.
+      role="listbox"
+      aria-label={l.models}
+      tabIndex={-1}
+      onKeyDown={(event) => {
+        if (event.defaultPrevented) return;
+        const options = Array.from(
+          event.currentTarget.querySelectorAll<HTMLButtonElement>('[role="option"]'),
+        );
+        const index = options.indexOf(event.target as HTMLButtonElement);
+        if (index < 0) return;
+        let next: number;
+        switch (event.key) {
+          case "ArrowDown":
+            next = (index + 1) % options.length;
+            break;
+          case "ArrowUp":
+            next = (index - 1 + options.length) % options.length;
+            break;
+          case "Home":
+            next = 0;
+            break;
+          case "End":
+            next = options.length - 1;
+            break;
+          default:
+            return;
+        }
+        event.preventDefault();
+        options[next]!.focus();
+      }}
+      className={clsx("flex flex-col", className)}
+    >
+      {providers.map(([provider, providerModels], groupIndex) => (
+        <div
+          key={provider}
+          // oxlint-disable-next-line jsx-a11y/prefer-tag-over-role -- provider section of the custom listbox with a visible M3 header row; <optgroup> only exists inside a native <select>.
+          role="group"
+          aria-label={provider}
+          className={clsx(groupIndex > 0 && "mt-1 border-t border-outline-variant pt-1")}
+        >
+          <div className="px-3 pt-2 pb-1 text-title-small text-on-surface-variant">{provider}</div>
+          {providerModels.map((model) => {
+            const selected = model.id === value;
+            return (
+              <button
+                key={model.id}
+                type="button"
+                // oxlint-disable-next-line jsx-a11y/prefer-tag-over-role -- M3 two-line menu item (label, supporting text, capability chips, check icon); a native <option> can only hold text.
+                role="option"
+                aria-selected={selected}
+                tabIndex={model.id === focusId ? 0 : -1}
+                onFocus={() => setFocusedId(model.id)}
+                onClick={() => onSelect(model.id)}
+                className={clsx(
+                  "flex min-h-12 w-full items-center gap-3 px-3 py-2 text-left",
+                  "transition-colors duration-200 ease-standard",
+                  selected
+                    ? "bg-secondary-container text-on-secondary-container"
+                    : "text-on-surface hover:bg-on-surface/8 active:bg-on-surface/10",
+                  focusRing,
+                  "focus-visible:outline-offset-[-3px]",
+                )}
+              >
+                <div className="min-w-0 flex-1">
+                  <div className="truncate text-label-large">{model.name}</div>
+                  {model.context_window || model.capabilities?.length ? (
+                    <div className="mt-0.5 flex flex-wrap items-center gap-1">
+                      {model.context_window ? (
+                        <span
+                          className={clsx(
+                            "text-body-small",
+                            selected ? "text-on-secondary-container" : "text-on-surface-variant",
+                          )}
+                        >
+                          {formatLabel(l.contextTokens, {
+                            count: model.context_window.toLocaleString(),
+                          })}
+                        </span>
+                      ) : null}
+                      {model.capabilities?.map((capability) => (
+                        <span
+                          key={capability}
+                          className={clsx(
+                            "inline-flex h-5 items-center rounded-small border border-outline-variant px-1.5 text-label-small",
+                            selected ? "text-on-secondary-container" : "text-on-surface-variant",
+                          )}
+                        >
+                          {capability}
+                        </span>
+                      ))}
+                    </div>
+                  ) : null}
+                </div>
+                {selected && <ChatIcon name="check" size={20} />}
+              </button>
+            );
+          })}
+        </div>
+      ))}
+      {providers.length === 0 && (
+        <div className="px-3 py-3 text-center text-body-small text-on-surface-variant">
+          {l.noModels}
+        </div>
+      )}
+    </div>
+  );
+}
+
+/**
+ * The menu's search field. It mounts with the popover content and takes focus then (replaces
+ * `autoFocus`), so typing filters the list as soon as the menu opens.
+ */
+function ModelSearchField({
+  value,
+  onChange,
+  placeholder,
+}: {
+  value: string;
+  onChange: (value: string) => void;
+  placeholder: string;
+}) {
+  const inputRef = useRef<HTMLInputElement>(null);
+
+  useEffect(() => {
+    inputRef.current?.focus();
+  }, []);
+
+  return (
+    <div className="px-2 pb-2">
+      <label className="flex h-10 items-center gap-2 rounded-full bg-surface-container-high px-3 text-on-surface-variant focus-within:bg-surface-container-highest">
+        <ChatIcon name="search" size={20} />
+        <input
+          ref={inputRef}
+          value={value}
+          onChange={(event) => onChange(event.target.value)}
+          placeholder={placeholder}
+          aria-label={placeholder}
+          className="min-w-0 flex-1 bg-transparent text-body-large text-on-surface outline-none placeholder:text-on-surface-variant"
+        />
+      </label>
+    </div>
+  );
+}
+
+export const ModelSelector = forwardRef<HTMLButtonElement, ModelSelectorProps>(
+  (
+    {
+      models,
+      value,
+      onChange,
+      placeholder,
+      searchPlaceholder,
+      variant,
+      size,
+      popover: externalPopover,
+      className,
+      disabled,
+      labels,
+    },
+    ref,
+  ) => {
+    const l = resolveChatLabels(labels);
+    const internalPopover = usePopover();
+    const popover = externalPopover ?? internalPopover;
+    const [search, setSearch] = useState("");
+
+    const selectedModel = models.find((m) => m.id === value);
+
+    const grouped = useMemo(() => groupModelsByProvider(models, search), [models, search]);
+
+    return (
+      <Popover.Root
+        open={popover.open}
+        onOpenChange={(open) => {
+          popover.setOpen(open);
+          if (!open) setSearch("");
+        }}
+      >
+        <Popover.Trigger asChild>
+          <SelectPill
+            ref={ref}
+            variant={variant}
+            size={size}
+            disabled={disabled}
+            aria-haspopup="listbox"
+            hideCaret
+            className={clsx("w-full", className)}
+          >
+            <span className="min-w-0 flex-1 truncate">
+              {selectedModel?.name ?? placeholder ?? l.selectModel}
+            </span>
+            <ChatIcon name="expand_more" size={18} />
+          </SelectPill>
+        </Popover.Trigger>
+        <Popover.Content
+          align="end"
+          sideOffset={8}
+          style={{ width: 280 }}
+          className="overflow-hidden rounded-extra-small! py-2"
+        >
+          {/* Search */}
+          <ModelSearchField
+            value={search}
+            onChange={setSearch}
+            placeholder={searchPlaceholder ?? l.searchModels}
+          />
+
+          {/* Grouped results */}
+          <div className="max-h-[320px] overflow-y-auto">
+            <ModelOptionList
+              grouped={grouped}
+              value={value}
+              labels={labels}
+              onSelect={(id) => {
+                onChange(id);
+                popover.setOpen(false);
+                setSearch("");
+              }}
+            />
+          </div>
+        </Popover.Content>
+      </Popover.Root>
+    );
+  },
+);
+
+ModelSelector.displayName = "ModelSelector";

package/src/ModelUnavailable.tsx

@@ -0,0 +1,116 @@
+// SPDX-License-Identifier: Apache-2.0
+// "Model unavailable" state of a local chat: downloading, loading, or down, with an optional
+// determinate M3 linear progress indicator and a retry action.
+
+"use client";
+
+import { clsx } from "clsx";
+
+import { type ChatLabels, formatLabel, resolveChatLabels } from "./chatLabels";
+import { ChatIcon } from "./chatIcons";
+import { CircularIndicator, focusRing } from "./internal";
+
+export type ModelAvailabilityPhase = "downloading" | "loading" | "unavailable";
+
+export interface ModelUnavailableProps {
+  phase?: ModelAvailabilityPhase;
+  /** Why the model cannot answer (backend message, already localized by the caller). */
+  reason?: string;
+  /** Download or load progress, 0..1; omit for an indeterminate state. */
+  progress?: number | null;
+  onRetry?: () => void;
+  labels?: Partial<ChatLabels>;
+  className?: string;
+}
+
+/** Clamp a progress fraction to 0..1; non-finite values give `null` (indeterminate). */
+export function clampProgress(progress: number | null | undefined): number | null {
+  if (progress === null || progress === undefined || !Number.isFinite(progress)) return null;
+  return Math.min(1, Math.max(0, progress));
+}
+
+export function ModelUnavailable({
+  phase = "unavailable",
+  reason,
+  progress,
+  onRetry,
+  labels,
+  className,
+}: ModelUnavailableProps) {
+  const l = resolveChatLabels(labels);
+  const value = clampProgress(progress);
+  const busy = phase !== "unavailable";
+  const title =
+    phase === "downloading"
+      ? l.modelDownloading
+      : phase === "loading"
+        ? l.modelLoading
+        : l.modelUnavailable;
+  const percent = value === null ? null : Math.round(value * 100);
+
+  return (
+    <div
+      // oxlint-disable-next-line jsx-a11y/prefer-tag-over-role -- live region wrapping block content (title, progress, action); <output> only holds phrasing content.
+      role="status"
+      aria-live="polite"
+      aria-busy={busy || undefined}
+      className={clsx(
+        "m3-model-unavailable flex flex-col gap-3 rounded-large px-4 py-4",
+        busy
+          ? "bg-surface-container-high text-on-surface"
+          : "bg-error-container text-on-error-container",
+        className,
+      )}
+    >
+      <div className="flex items-start gap-3">
+        {busy ? (
+          <CircularIndicator size={24} label={title} className="mt-0.5" />
+        ) : (
+          <ChatIcon name="cloud_off" size={24} className="mt-0.5" />
+        )}
+        <div className="min-w-0 flex-1">
+          <p className="m-0 text-title-medium">{title}</p>
+          {reason ? <p className="m-0 mt-1 text-body-medium opacity-90">{reason}</p> : null}
+        </div>
+        {percent !== null ? (
+          <span className="shrink-0 text-label-large">
+            {formatLabel(l.progressPercent, { percent })}
+          </span>
+        ) : null}
+      </div>
+      {busy && value !== null ? (
+        <div
+          // oxlint-disable-next-line jsx-a11y/prefer-tag-over-role -- M3 linear determinate indicator with a track gap; a native <progress> cannot be styled to the spec.
+          role="progressbar"
+          aria-label={title}
+          aria-valuemin={0}
+          aria-valuemax={100}
+          aria-valuenow={percent ?? undefined}
+          className="flex h-1 w-full items-center gap-1"
+        >
+          <span
+            className="h-1 rounded-full bg-primary transition-[width] duration-300 ease-standard"
+            style={{ width: `${(value * 100).toFixed(1)}%` }}
+          />
+          <span className="h-1 flex-1 rounded-full bg-secondary-container" />
+        </div>
+      ) : null}
+      {onRetry && !busy ? (
+        <div className="flex justify-end">
+          <button
+            type="button"
+            onClick={onRetry}
+            className={clsx(
+              "inline-flex h-10 items-center gap-2 rounded-full bg-error px-6 text-label-large text-on-error",
+              "transition-colors duration-200 ease-standard hover:bg-error/92",
+              focusRing,
+            )}
+          >
+            <ChatIcon name="refresh" size={18} />
+            <span>{l.retry}</span>
+          </button>
+        </div>
+      ) : null}
+    </div>
+  );
+}

package/src/TaskCreateForm.tsx

@@ -0,0 +1,123 @@
+// SPDX-License-Identifier: Apache-2.0 AND MIT
+// Derived from SpaceUI (packages/aphrody-spaceui/packages/ai/src/TaskCreateForm.tsx), MIT, rebuilt on Material Design 3.
+
+import { Button, Input, Select, SelectOption, TextArea } from "@aphrody/m3-primitives";
+import { clsx } from "clsx";
+import { useCallback, useEffect, useId, useRef, useState } from "react";
+
+import type { TaskPriority } from "./types";
+import { TASK_PRIORITY_LABEL } from "./types";
+
+export interface TaskCreateFormData {
+  title: string;
+  description: string;
+  priority: TaskPriority;
+}
+
+export interface TaskCreateFormProps {
+  onSubmit: (data: TaskCreateFormData) => void;
+  onCancel?: () => void;
+  defaultPriority?: TaskPriority;
+  isSubmitting?: boolean;
+  className?: string;
+}
+
+const PRIORITIES: TaskPriority[] = ["critical", "high", "medium", "low"];
+
+/**
+ * Inline task creation on an M3 surface: title and description text fields, a priority select,
+ * and M3 actions (filled `Create`, text `Cancel`).
+ */
+export function TaskCreateForm({
+  onSubmit,
+  onCancel,
+  defaultPriority = "medium",
+  isSubmitting,
+  className,
+}: TaskCreateFormProps) {
+  const [title, setTitle] = useState("");
+  const [description, setDescription] = useState("");
+  const [priority, setPriority] = useState<TaskPriority>(defaultPriority);
+  const titleInputId = useId();
+  const descriptionInputId = useId();
+  const titleInputRef = useRef<HTMLInputElement>(null);
+
+  // Focus the title when the form mounts (replaces `autoFocus`).
+  useEffect(() => {
+    titleInputRef.current?.focus();
+  }, []);
+
+  const canSubmit = title.trim().length > 0 && !isSubmitting;
+
+  const handleSubmit = useCallback(() => {
+    if (!canSubmit) return;
+    onSubmit({ title: title.trim(), description: description.trim(), priority });
+    setTitle("");
+    setDescription("");
+    setPriority(defaultPriority);
+  }, [canSubmit, onSubmit, title, description, priority, defaultPriority]);
+
+  return (
+    <div
+      className={clsx(
+        "flex flex-col gap-3 rounded-medium bg-surface-container-low p-4 text-on-surface",
+        className,
+      )}
+    >
+      <div className="flex items-center gap-2">
+        <label htmlFor={titleInputId} className="sr-only">
+          Task Title
+        </label>
+        <Input
+          ref={titleInputRef}
+          id={titleInputId}
+          type="text"
+          size="lg"
+          value={title}
+          onChange={(e) => setTitle(e.target.value)}
+          onKeyDown={(e) => {
+            if (e.key === "Enter") handleSubmit();
+            if (e.key === "Escape") onCancel?.();
+          }}
+          placeholder="Task title..."
+          className="min-w-0 flex-1"
+          disabled={isSubmitting}
+        />
+        <Select
+          value={priority}
+          size="lg"
+          onChange={(value) => setPriority(value as TaskPriority)}
+          disabled={isSubmitting}
+        >
+          {PRIORITIES.map((p) => (
+            <SelectOption key={p} value={p}>
+              {TASK_PRIORITY_LABEL[p]}
+            </SelectOption>
+          ))}
+        </Select>
+      </div>
+      <label htmlFor={descriptionInputId} className="sr-only">
+        Description
+      </label>
+      <TextArea
+        id={descriptionInputId}
+        value={description}
+        onChange={(e) => setDescription(e.target.value)}
+        placeholder="Description (optional)"
+        rows={2}
+        className="w-full resize-none"
+        disabled={isSubmitting}
+      />
+      <div className="flex items-center justify-end gap-2">
+        {onCancel && (
+          <Button variant="text" size="lg" onClick={onCancel} disabled={isSubmitting}>
+            Cancel
+          </Button>
+        )}
+        <Button variant="filled" size="lg" disabled={!canSubmit} onClick={handleSubmit}>
+          Create
+        </Button>
+      </div>
+    </div>
+  );
+}