refactor(core): reorganize UI into component library

.changeset/reorganize-ui-components.md

@@ -0,0 +1,5 @@
+---
+'@kidd-cli/core': minor
+---
+
+Reorganize UI components into prompts, display, and layout modules. Add new prompt components (Autocomplete, GroupMultiSelect, PathInput, SelectKey), display components (Alert, ProgressBar, Spinner, StatusMessage), and extract screen module with provider and context.

codspeed.yml

@@ -1,6 +1,6 @@
 benchmarks:
-  - name: "icons --help"
+  - name: 'icons --help'
     exec: node examples/icons/dist/index.mjs --help
 
-  - name: "icons status"
+  - name: 'icons status'
     exec: node examples/icons/dist/index.mjs status

examples/tui/package.json

@@ -6,6 +6,7 @@
   "scripts": {
     "dev": "kidd dev",
     "build": "kidd build",
+    "stories": "kidd stories --cwd ../../packages/core",
     "typecheck": "tsgo --noEmit"
   },
   "dependencies": {

package.json

@@ -14,6 +14,7 @@
     "lint:fix": "oxlint --fix --ignore-pattern node_modules",
     "build": "turbo run build --filter='./packages/*'",
     "dev": "turbo run dev",
+    "stories": "pnpm build && kidd stories --cwd packages/core",
     "test": "turbo run test test:integration",
     "test:integration": "vitest run --config vitest.exports.config.ts",
     "test:coverage": "turbo run test:coverage --filter='./packages/*'",
@@ -33,6 +34,7 @@
   "devDependencies": {
     "@changesets/cli": "^2.30.0",
     "@clack/prompts": "^1.1.0",
+    "@kidd-cli/cli": "workspace:*",
     "@types/node": "catalog:",
     "@typescript/native-preview": "7.0.0-dev.20260323.1",
     "@vitest/coverage-v8": "catalog:",

packages/core/src/context/prompts.ts

@@ -1,9 +1,3 @@
-/**
- * Factory for creating the interactive prompt methods on the context.
- *
- * @module
- */
-
 import type { Readable, Writable } from 'node:stream'
 
 import * as clack from '@clack/prompts'

packages/core/src/context/resolve-defaults.ts

@@ -1,9 +1,3 @@
-/**
- * Shared utilities for resolving clack per-call defaults from display config.
- *
- * @module
- */
-
 import type { Readable, Writable } from 'node:stream'
 
 // ---------------------------------------------------------------------------

packages/core/src/context/status.ts

@@ -1,9 +1,3 @@
-/**
- * Factory for creating the {@link Status} indicator methods on the context.
- *
- * @module
- */
-
 import type { Writable } from 'node:stream'
 
 import * as clack from '@clack/prompts'
@@ -95,7 +89,7 @@
 
     async tasks(tasks: readonly TaskDef[]): Promise<void> {
       // Accepted exception: kidd's TaskDef.task returns `Promise<string | void>`,
       // clack expects separate `Promise<string> | Promise<void>`. The cast bridges this.
       await clack.tasks(
         tasks.map((t) => ({
           title: t.title,

packages/core/src/index.ts

@@ -5,6 +5,8 @@ export { autoload } from './autoload.js'
 export { decorateContext } from './context/decorate.js'
 export { middleware } from './middleware.js'
 export { defineConfig } from '@kidd-cli/config'
+export { screen, useScreenContext } from './screen/index.js'
+export type { ScreenDef, ScreenExit } from './screen/index.js'
 export type {
   CliConfig,
   Command,
@@ -29,6 +31,7 @@ export type {
   ProgressBar,
   ProgressOptions,
   Prompts,
+  ScreenContext,
   SelectOptions,
   Spinner,
   Status,

packages/core/src/lib/log.ts

@@ -1,9 +1,3 @@
-/**
- * Factory for creating a {@link Log} instance backed by `@clack/prompts`.
- *
- * @module
- */
-
 import type { Writable } from 'node:stream'
 
 import * as clack from '@clack/prompts'

packages/core/src/middleware/auth/oauth-server.ts

@@ -1,12 +1,3 @@
-/**
- * Shared utilities for OAuth-based auth resolvers.
- *
- * Extracted from the local HTTP server, browser-launch, and
- * lifecycle patterns shared by the PKCE and device-code flows.
- *
- * @module
- */
-
 import { execFile } from 'node:child_process'
 import { createServer } from 'node:http'
 import type { IncomingMessage, Server, ServerResponse } from 'node:http'

packages/core/src/middleware/icons/definitions.ts

@@ -1,12 +1,3 @@
-/**
- * Predefined icon definitions organized by category.
- *
- * Each icon has a Nerd Font glyph and an emoji fallback. The middleware
- * resolves to one or the other based on font detection.
- *
- * @module
- */
-
 import { match } from 'ts-pattern'
 
 import type { IconCategory, IconDefinition } from './types.js'

packages/core/src/middleware/icons/icons.ts

@@ -1,12 +1,3 @@
-/**
- * Icons middleware factory.
- *
- * Detects Nerd Font availability, optionally prompts for installation,
- * and decorates `ctx.icons` with an icon resolver.
- *
- * @module
- */
-
 import { decorateContext } from '@/context/decorate.js'
 import { middleware } from '@/middleware.js'
 import type { Middleware } from '@/types/index.js'

packages/core/src/middleware/report/report.ts

@@ -1,12 +1,3 @@
-/**
- * Report middleware factory.
- *
- * Decorates `ctx.report` with a structured reporting API for checks,
- * findings, and summaries backed by format functions.
- *
- * @module
- */
-
 import { decorateContext } from '@/context/decorate.js'
 import { formatCheck } from '@/lib/format/check.js'
 import { formatFinding } from '@/lib/format/finding.js'

packages/core/src/middleware/report/types.ts

@@ -1,9 +1,3 @@
-/**
- * Types for the report middleware.
- *
- * @module
- */
-
 import type { CheckInput, FindingInput, SummaryInput } from '@/lib/format/types.js'
 
 // ---------------------------------------------------------------------------

packages/core/src/screen/index.ts

@@ -0,0 +1,4 @@
+export { screen } from './screen.js'
+export type { ScreenDef, ScreenExit } from './screen.js'
+
+export { useScreenContext } from './provider.js'

packages/core/src/ui/output/index.ts → packages/core/src/screen/output/index.ts

@@ -1,12 +1,3 @@
-/**
- * Screen output system for rendering `ctx.log`, `ctx.status.spinner`, and
- * `ctx.report` inside React/Ink screen components.
- *
- * @module
- */
-
-export { Output } from './output.js'
-
 export { useOutputStore } from './use-output-store.js'
 
 export { createOutputStore } from './store.js'

packages/core/src/ui/output/screen-log.ts → packages/core/src/screen/output/screen-log.ts

@@ -1,10 +1,3 @@
-/**
- * Screen-backed {@link Log} implementation that pushes entries
- * to an {@link OutputStore} instead of writing to stderr.
- *
- * @module
- */
-
 import { match } from 'ts-pattern'
 
 import type { Log, LogMessageOptions, NoteOptions, StreamLog } from '@/context/types.js'

packages/core/src/ui/output/screen-report.ts → packages/core/src/screen/output/screen-report.ts

@@ -1,10 +1,3 @@
-/**
- * Screen-backed {@link Report} implementation that pushes entries
- * to an {@link OutputStore} instead of writing to stderr.
- *
- * @module
- */
-
 import type { CheckInput, FindingInput, SummaryInput } from '@/lib/format/types.js'
 import type { Report } from '@/middleware/report/types.js'
 

packages/core/src/ui/output/screen-spinner.ts → packages/core/src/screen/output/screen-spinner.ts

@@ -1,10 +1,3 @@
-/**
- * Screen-backed {@link Spinner} implementation that updates
- * spinner state in an {@link OutputStore} instead of writing to stderr.
- *
- * @module
- */
-
 import type { Spinner } from '@/context/types.js'
 
 import type { OutputStore } from './types.js'

packages/core/src/ui/output/store-key.ts → packages/core/src/screen/output/store-key.ts

@@ -1,10 +1,3 @@
-/**
- * Utility functions for attaching and retrieving the {@link OutputStore}
- * on a screen context object via a hidden Symbol key.
- *
- * @module
- */
-
 import type { ScreenContext } from '../../context/types.js'
 import type { OutputStore } from './types.js'
 
@@ -27,9 +20,13 @@ const OUTPUT_STORE_KEY: unique symbol = Symbol('kidd.outputStore')
  * Options for {@link injectOutputStore}.
  */
 interface InjectOutputStoreOptions {
-  /** The screen context record to extend. */
+  /**
+   * The screen context record to extend.
+   */
   readonly ctx: Record<string | symbol, unknown>
-  /** The output store to attach. */
+  /**
+   * The output store to attach.
+   */
   readonly store: OutputStore
 }
 

packages/core/src/ui/output/store.ts → packages/core/src/screen/output/store.ts

@@ -1,11 +1,3 @@
-/**
- * External store for screen output entries and spinner state.
- *
- * Compatible with React's `useSyncExternalStore` for reactive rendering.
- *
- * @module
- */
-
 import type {
   OutputEntry,
   OutputEntryInput,

packages/core/src/ui/output/types.ts → packages/core/src/screen/output/types.ts

@@ -1,9 +1,3 @@
-/**
- * Types for the screen output system.
- *
- * @module
- */
-
 import type { CheckInput, FindingInput, SummaryInput } from '@/lib/format/types.js'
 
 // ---------------------------------------------------------------------------

packages/core/src/ui/output/use-output-store.ts → packages/core/src/screen/output/use-output-store.ts

@@ -1,9 +1,3 @@
-/**
- * Hook to access the {@link OutputStore} from the screen context.
- *
- * @module
- */
-
 import { useScreenContext } from '../provider.js'
 import { getOutputStore } from './store-key.js'
 import type { OutputStore } from './types.js'

packages/core/src/ui/screen.tsx → packages/core/src/screen/screen.tsx

@@ -7,7 +7,7 @@ import { match } from 'ts-pattern'
 
 import type { CommandContext, ImperativeContextKeys, ScreenContext } from '../context/types.js'
 import type { ArgsDef, Command, InferArgsMerged, Resolvable } from '../types/index.js'
-import { FullScreen, LEAVE_ALT_SCREEN } from './fullscreen.js'
+import { FullScreen, LEAVE_ALT_SCREEN } from '../ui/layout/fullscreen.js'
 import { createScreenLog } from './output/screen-log.js'
 import { createScreenReport } from './output/screen-report.js'
 import { createScreenSpinner } from './output/screen-spinner.js'

packages/core/src/stories/decorators.tsx

@@ -3,8 +3,8 @@ import type { ComponentType, ReactElement } from 'react'
 import React from 'react'
 
 import type { ScreenContext } from '../context/types.js'
-import { FullScreen } from '../ui/fullscreen.js'
-import { KiddProvider } from '../ui/provider.js'
+import { KiddProvider } from '../screen/provider.js'
+import { FullScreen } from '../ui/layout/fullscreen.js'
 import type { Decorator } from './types.js'
 
 // ---------------------------------------------------------------------------