kennel 0.2.1 → 0.2.2

package/kernel/packages/ui/src/components/viewer-options.tsx

@@ -0,0 +1,166 @@
+import type { ComponentProps, ReactNode } from "react"
+import { Ellipsis } from "lucide-react"
+
+import {
+  DropdownMenu,
+  DropdownMenuCheckboxItem,
+  DropdownMenuContent,
+  DropdownMenuItem,
+  DropdownMenuLabel,
+  DropdownMenuSeparator,
+  DropdownMenuShortcut,
+  DropdownMenuTrigger,
+} from "@raggle-ai/ui/components/dropdown-menu"
+import { cn } from "@raggle-ai/ui/lib/utils"
+
+/**
+ * A single entry in a file viewer's options menu. The `kind` field decides
+ * which interactive primitive renders the entry:
+ *
+ * - `separator` – a divider to group related actions
+ * - `label` – a non-interactive group heading
+ * - `item` – a clickable action (optionally destructive / disabled / icons)
+ * - `checkbox` – a toggle action with a live checked state
+ */
+export type ViewerAction =
+  | { kind: "separator" }
+  | { kind: "label"; label: string }
+  | {
+      kind: "item"
+      id: string
+      label: string
+      run: () => void
+      /** Leading icon shown next to the label. */
+      icon?: ReactNode
+      /** Short explanatory hint shown under the label. */
+      description?: string
+      /** Keyboard hint shown right-aligned (caller is responsible for wiring it). */
+      shortcut?: string
+      variant?: "default" | "destructive"
+      disabled?: boolean
+      /** Native tooltip explaining why the action is disabled. */
+      disabledReason?: string
+    }
+  | {
+      kind: "checkbox"
+      id: string
+      label: string
+      checked: boolean
+      run: (checked: boolean) => void
+      icon?: ReactNode
+      description?: string
+      shortcut?: string
+      disabled?: boolean
+      disabledReason?: string
+    }
+
+/**
+ * Interactive options dropdown for file viewers (documents, sessions, …).
+ *
+ * The menu is keyboard navigable (arrow keys, Enter, Escape) via the Radix
+ * dropdown primitives, groups actions with labels and separators, shows icons
+ * and shortcut hints, renders live checkbox toggles, and marks destructive
+ * actions in the destructive color. Rendering the trigger/button always; the
+ * menu content only mounts while open.
+ */
+export function ViewerOptions({
+  actions = [],
+  label = "View options",
+  align = "end",
+  className,
+  contentClassName,
+}: {
+  actions?: ViewerAction[]
+  /** Accessible name for the trigger button (a "View options" ellipsis). */
+  label?: string
+  align?: ComponentProps<typeof DropdownMenuContent>["align"]
+  className?: string
+  contentClassName?: string
+}) {
+  if (!actions.length) return null
+  return (
+    <DropdownMenu>
+      <DropdownMenuTrigger asChild>
+        <button
+          type="button"
+          aria-label={label}
+          aria-haspopup="menu"
+          className={cn("app-options-trigger", className)}
+        >
+          <Ellipsis aria-hidden="true" />
+        </button>
+      </DropdownMenuTrigger>
+      <DropdownMenuContent
+        align={align}
+        className={cn("app-folder-popover min-w-56", contentClassName)}
+      >
+        {actions.map((action, index) => {
+          if (action.kind === "separator") {
+            return <DropdownMenuSeparator key={`separator-${index}`} />
+          }
+          if (action.kind === "label") {
+            return (
+              <DropdownMenuLabel key={action.label}>
+                {action.label}
+              </DropdownMenuLabel>
+            )
+          }
+          if (action.kind === "checkbox") {
+            return (
+              <DropdownMenuCheckboxItem
+                key={action.id}
+                checked={action.checked}
+                disabled={action.disabled}
+                onCheckedChange={action.run}
+                title={action.disabledReason}
+              >
+                {action.icon}
+                <span className="flex min-w-0 flex-1 flex-col gap-0.5">
+                  <span className="flex items-center gap-2">
+                    <span className="truncate">{action.label}</span>
+                    {action.shortcut ? (
+                      <DropdownMenuShortcut>
+                        {action.shortcut}
+                      </DropdownMenuShortcut>
+                    ) : null}
+                  </span>
+                  {action.description ? (
+                    <span className="text-muted-foreground text-xs font-normal">
+                      {action.description}
+                    </span>
+                  ) : null}
+                </span>
+              </DropdownMenuCheckboxItem>
+            )
+          }
+          return (
+            <DropdownMenuItem
+              key={action.id}
+              disabled={action.disabled}
+              variant={action.variant}
+              onSelect={action.run}
+              title={action.disabledReason}
+            >
+              {action.icon}
+              <span className="flex min-w-0 flex-1 flex-col gap-0.5">
+                <span className="flex items-center gap-2">
+                  <span className="truncate">{action.label}</span>
+                  {action.shortcut ? (
+                    <DropdownMenuShortcut>
+                      {action.shortcut}
+                    </DropdownMenuShortcut>
+                  ) : null}
+                </span>
+                {action.description ? (
+                  <span className="text-muted-foreground text-xs font-normal">
+                    {action.description}
+                  </span>
+                ) : null}
+              </span>
+            </DropdownMenuItem>
+          )
+        })}
+      </DropdownMenuContent>
+    </DropdownMenu>
+  )
+}

package/kernel/packages/ui/src/hooks/use-folder-filter.ts

@@ -0,0 +1,103 @@
+import { useCallback, useMemo, useState } from "react"
+
+import type {
+  FolderFilterChoice,
+  FolderFilterMode,
+  FolderSelection,
+} from "@raggle-ai/ui/lib/folder-filter"
+import { applyFolderFilter } from "@raggle-ai/ui/lib/folder-filter"
+
+export type UseFolderFilterOptions<T> = {
+  /** Owning folder of each item; null when the item has none. */
+  getFolder: (item: T) => string | null
+  /** "exact" keeps the selected folder's items only; "subtree" also keeps descendant items. */
+  mode?: FolderFilterMode
+  /** Include ancestor/outside folders as chips (see `folderFilterChoices`). */
+  allowOutside?: boolean
+  /** Folder everything is shown relative to (the viewed root). */
+  rootFolder: string
+  /** Initial selection (owning folder paths); a selection with no items falls back to all. */
+  initialFolder?: FolderSelection
+}
+
+export type UseFolderFilterResult<T> = {
+  /** Distinct owning-folder choices with counts, root first. */
+  choices: FolderFilterChoice[]
+  /**
+   * Selection entries that still match items. Empty means "all items" —
+   * either nothing is selected or every selected folder lost its items.
+   */
+  effectiveSelected: readonly string[]
+  /** Raw selection state; entries whose folder has no items left may be stale. */
+  selected: readonly string[]
+  /**
+   * Replace the selection. Pass a single folder, an array of folders (an
+   * item passes when any of them matches), or null/[] to show everything.
+   */
+  setSelected: (folder: FolderSelection) => void
+  /** Toggle one owning folder in/out of the selection. */
+  toggle: (folder: string) => void
+  /** Clear the selection back to "all items". */
+  reset: () => void
+  /** Number of items before filtering — shown on the "All" chip. */
+  total: number
+  /** Items after applying the effective selection. */
+  visibleItems: T[]
+}
+
+/**
+ * Folder-filter state for a plugin view: pass the items and a folder
+ * accessor, get the choices, the reconciled (multi-)selection, and the
+ * filtered `visibleItems` in one place. Recomputes only when the items,
+ * accessor, root, mode, or selection change.
+ */
+export function useFolderFilter<T>(
+  items: readonly T[],
+  options: UseFolderFilterOptions<T>,
+): UseFolderFilterResult<T> {
+  const { allowOutside, getFolder, mode, rootFolder } = options
+  const [selected, setSelectedState] = useState<readonly string[]>(() => {
+    const initial = options.initialFolder
+    if (initial === null || initial === undefined) return []
+    return Array.isArray(initial) ? initial : [initial]
+  })
+
+  const setSelected = useCallback((folder: FolderSelection) => {
+    setSelectedState(
+      folder === null || folder === undefined
+        ? []
+        : Array.isArray(folder)
+          ? folder
+          : [folder],
+    )
+  }, [])
+  const toggle = useCallback((folder: string) => {
+    setSelectedState((current) =>
+      current.includes(folder)
+        ? current.filter((entry) => entry !== folder)
+        : [...current, folder],
+    )
+  }, [])
+  const reset = useCallback(() => setSelectedState([]), [])
+
+  const result = useMemo(
+    () =>
+      applyFolderFilter({
+        allowOutside,
+        getFolder,
+        items,
+        mode,
+        rootFolder,
+        selected,
+      }),
+    [allowOutside, getFolder, items, mode, rootFolder, selected],
+  )
+
+  return {
+    ...result,
+    selected,
+    setSelected,
+    toggle,
+    reset,
+  }
+}

package/kernel/packages/ui/src/hooks/use-mobile.ts

@@ -0,0 +1,19 @@
+import * as React from "react"
+
+const MOBILE_BREAKPOINT = 768
+
+export function useIsMobile() {
+  const [isMobile, setIsMobile] = React.useState<boolean | undefined>(undefined)
+
+  React.useEffect(() => {
+    const mql = window.matchMedia(`(max-width: ${MOBILE_BREAKPOINT - 1}px)`)
+    const onChange = () => {
+      setIsMobile(window.innerWidth < MOBILE_BREAKPOINT)
+    }
+    mql.addEventListener("change", onChange)
+    setIsMobile(window.innerWidth < MOBILE_BREAKPOINT)
+    return () => mql.removeEventListener("change", onChange)
+  }, [])
+
+  return !!isMobile
+}

package/kernel/packages/ui/src/index.ts

@@ -0,0 +1,13 @@
+// Barrel for `~/ui` (and the package's `.` export).
+//
+// chat, hooks and lib helpers only. Components stay subpath-only:
+// `@raggle-ai/ui/components/*` — there is no `components` barrel by design.
+// Note: this surface includes `.tsx` modules, so consumers need the `jsx`
+// compiler option (apps/web and plugins already set it).
+export * from "./chat/index"
+export * from "./hooks/use-folder-filter"
+export * from "./hooks/use-mobile"
+export * from "./lib/folder-activity"
+export * from "./lib/folder-filter"
+export * from "./lib/live-tool-call"
+export * from "./lib/utils"

package/kernel/packages/ui/src/lib/document-extensions.ts

@@ -0,0 +1,83 @@
+import type { DocumentResponse } from "kennel-client"
+import type { ComponentType } from "react"
+
+import type { BarkdownMarkdownComponents } from "@raggle-ai/markdown"
+
+/**
+ * Custom renderer for a specific file kind or extension in the document
+ * view. Extensions replace the built-in fallback for the kinds they list and
+ * own any extra extensions they name (e.g. `".kml"`). Matching is exact per
+ * file: an extension renderer wins over the built-in kind fallback.
+ */
+export type DocumentRendererOverride = {
+  /** React component that renders the document body. */
+  component: ComponentType<{ document: DocumentResponse }>
+  /** Preview kinds this renderer replaces ("markdown", "html", "text", …). */
+  kinds?: DocumentResponse["kind"][]
+  /** Extra file extensions owned by this renderer, e.g. ".kml". */
+  extensions?: string[]
+}
+
+/**
+ * Browser-only document extension. Registered explicitly from trusted
+ * modules only — the pattern mirror of `folderPlugins` in `./plugins.ts`:
+ * nothing in a URL is ever turned into an import path.
+ *
+ * - `markdownComponents` are merged into the markdown view (Barkdown's
+ *   `components` extension point), so a plugin can render custom blocks on
+ *   top of plain Markdown instead of the document being a raw file.
+ * - `renderers` take over whole file kinds/extensions before the built-in
+ *   fallback chain in `FileRenderer`.
+ */
+export type DocumentExtension = {
+  /** Stable identifier used in registries and debugging. */
+  id: string
+  /** Human label for the registered surface. */
+  label: string
+  /** Markdown components merged into the markdown view. */
+  markdownComponents?: BarkdownMarkdownComponents
+  /** Custom renderers consulted before the built-in kind fallbacks. */
+  renderers?: DocumentRendererOverride[]
+}
+
+/**
+ * Explicit registry of document extensions. The built-in renderers
+ * (markdown/html/text/code/image/table/eml/binary) stay as fallbacks in
+ * `FileRenderer`; anything listed here overrides or augments them.
+ */
+export const documentExtensions: DocumentExtension[] = []
+
+/** All renderer overrides registered by every document extension. */
+export function documentRendererOverrides(): DocumentRendererOverride[] {
+  return documentExtensions.flatMap((extension) => extension.renderers ?? [])
+}
+
+/** Markdown components contributed by every document extension. */
+export function markdownComponentExtensions(): BarkdownMarkdownComponents {
+  return Object.assign(
+    {},
+    ...documentExtensions.map(
+      (extension) => extension.markdownComponents ?? {},
+    ),
+  )
+}
+
+function extensionOf(path: string) {
+  return path.slice(path.lastIndexOf(".")).toLowerCase()
+}
+
+/**
+ * First registered renderer that owns this document (by kind or by file
+ * extension). Undefined when no extension wants the file, so the caller
+ * falls back to the built-in renderers.
+ */
+export function documentRendererOverride(
+  document: DocumentResponse,
+): DocumentRendererOverride | undefined {
+  return documentRendererOverrides().find((renderer) => {
+    const byKind = renderer.kinds?.includes(document.kind) ?? false
+    const byExtension =
+      renderer.extensions?.includes(extensionOf(document.path)) ?? false
+    return byKind || byExtension
+  })
+}

package/kernel/packages/ui/src/lib/folder-activity.ts

@@ -0,0 +1,143 @@
+export type FolderIcon = {
+  data?: string
+  mediaType: string
+  source?: "github" | "local" | "favicon"
+  url?: string
+}
+
+export type FolderFile = {
+  activityAt: number
+  /** Owning folder when the file comes from a linked repository. */
+  folder?: string
+  name: string
+  openHref?: string
+  relativePath: string
+}
+
+export type FolderProject = {
+  id: string
+  iconAssetKey?: string
+  name: string
+  relativePath: string
+  worktree: string
+}
+
+export type FolderSkill = {
+  description?: string
+  name: string
+  openHref?: string
+  relativePath: string
+  source: "global" | "local"
+}
+
+export type FolderSession = {
+  client: "claude" | "codex" | "cursor" | "opencode" | "pi"
+  href?: string
+  id: string
+  lastMessageAt?: string
+  messageCount: number
+  resumeCommand?: string
+  title: string
+}
+
+export type FolderCalendar = {
+  count: number
+  items: Array<{
+    id: string
+    title: string
+    start: Date
+    end: Date
+    description?: string
+    color?: string
+  }>
+  title?: string
+}
+
+export type FolderPluginItem = {
+  /** Optional count shown next to the navigation label. */
+  count?: number
+  /** Detection failure detail; the item is still shown but flagged. */
+  error?: string
+  /** Trusted plugin id, registered in the host's explicit browser registry. */
+  id: string
+  label: string
+}
+
+export type FolderMetadata = {
+  assets: Record<string, FolderIcon>
+  files: { items: FolderFile[] }
+  folder: string
+  iconAssetKey?: string
+  configWarnings?: string[]
+  plugins?: { configWarnings?: string[]; items: FolderPluginItem[] }
+  projects: { items: FolderProject[] }
+  sessions: { items: FolderSession[] }
+  skills?: { items: FolderSkill[] }
+  workspace?: {
+    breadcrumbs: Array<{
+      icon?: FolderIcon
+      path: string
+      /** Path segment that owns a schema, i.e. a core folder boundary. */
+      schema?: boolean
+      title: string
+    }>
+    root: string
+    configPath?: string
+    /** Nearest schema of the opened folder itself (if any). */
+    schemaPath?: string
+    /** Schema-declared core folders the shell can offer as navigation targets. */
+    revision?: string
+    state?: "ready" | "error"
+    schemas?: Array<{
+      id?: string
+      count?: number
+      navLabel?: string
+      icon?: string
+      revision?: string
+      indexedAt?: string
+      state?: "ready" | "error"
+      diagnostics?: Array<{ path: string; message: string }>
+      folder: string
+      schemaPath: string
+      title: string
+    }>
+  }
+}
+
+export type FolderTab = "files" | "projects" | "sessions" | "skills"
+
+export function folderTab(search: string): FolderTab | undefined {
+  const tab = new URLSearchParams(search).get("tab")
+  if (
+    tab === "files" ||
+    tab === "projects" ||
+    tab === "sessions" ||
+    tab === "skills"
+  )
+    return tab
+  return undefined
+}
+
+export function relativeTime(value: number | string | undefined) {
+  if (!value) return ""
+  const time = typeof value === "number" ? value : Date.parse(value)
+  if (!Number.isFinite(time)) return ""
+
+  const seconds = Math.round((time - Date.now()) / 1_000)
+  const formatter = new Intl.RelativeTimeFormat(undefined, { numeric: "auto" })
+  if (Math.abs(seconds) < 60) return formatter.format(seconds, "second")
+  const minutes = Math.round(seconds / 60)
+  if (Math.abs(minutes) < 60) return formatter.format(minutes, "minute")
+  const hours = Math.round(minutes / 60)
+  if (Math.abs(hours) < 24) return formatter.format(hours, "hour")
+  const days = Math.round(hours / 24)
+  if (Math.abs(days) < 30) return formatter.format(days, "day")
+  const months = Math.round(days / 30)
+  if (Math.abs(months) < 12) return formatter.format(months, "month")
+  return formatter.format(Math.round(months / 12), "year")
+}
+
+export function sessionClientName(client: FolderSession["client"]) {
+  if (client === "opencode") return "OpenCode"
+  return `${client.slice(0, 1).toUpperCase()}${client.slice(1)}`
+}