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.

examples/diagnostic-output/package.json

@@ -18,4 +18,4 @@
     "tsx": "catalog:",
     "typescript": "catalog:"
   }
-}
+}

packages/core/src/cli.ts

@@ -108,7 +108,6 @@ export async function cli<TSchema extends z.ZodType = z.ZodType>(
       middleware: options.middleware,
       name: options.name,
       prompts: options.prompts,
-      spinner: options.spinner,
       status: options.status,
       version,
     })

packages/core/src/context/create-context.ts

@@ -17,7 +17,6 @@ import type {
   Log,
   Meta,
   Prompts,
-  Spinner,
   Status,
   Store,
   StoreMap,
@@ -45,11 +44,6 @@ export interface CreateContextOptions<TArgs extends AnyRecord, TConfig extends A
   readonly log?: Log
   readonly prompts?: Prompts
   readonly status?: Status
-  /**
-   * @deprecated Use `status` instead. When provided, creates a Status
-   * wrapper around this spinner for backwards compatibility.
-   */
-  readonly spinner?: Spinner
 }
 
 /**
@@ -141,8 +135,7 @@ function resolveCommonDefaults(dc: DisplayConfig): {
 }
 
 /**
- * Resolve the Status instance from options, supporting the deprecated
- * `spinner` override for backwards compatibility.
+ * Resolve the Status instance from options or create a default one.
  *
  * @private
  * @param options - The create context options.
@@ -162,7 +155,6 @@ function resolveStatus<TArgs extends AnyRecord, TConfig extends AnyRecord>(
   return createContextStatus({
     defaults: commonDefaults,
     progressConfig: dc.progress,
-    spinner: options.spinner,
     spinnerConfig: dc.spinner,
   })
 }

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/runtime/runtime.ts

@@ -52,7 +52,6 @@ export async function createRuntime<TSchema extends z.ZodType>(
           version: options.version,
         },
         prompts: options.prompts,
-        spinner: options.spinner,
         status: options.status,
       })
 

packages/core/src/runtime/types.ts

@@ -1,14 +1,7 @@
 import type { AsyncResult, Result } from '@kidd-cli/utils/fp'
 import type { z } from 'zod'
 
-import type {
-  CommandContext,
-  DisplayConfig,
-  Log,
-  Prompts,
-  Spinner,
-  Status,
-} from '@/context/types.js'
+import type { CommandContext, DisplayConfig, Log, Prompts, Status } from '@/context/types.js'
 import type {
   ArgsDef,
   CliConfigOptions,
@@ -30,7 +23,6 @@ export interface RuntimeOptions<TSchema extends z.ZodType = z.ZodType> {
   readonly log?: Log
   readonly prompts?: Prompts
   readonly status?: Status
-  readonly spinner?: Spinner
 }
 
 /**

packages/core/src/screen/index.ts

@@ -0,0 +1,13 @@
+/**
+ * Screen runtime — mounts Ink, wires context, manages the output store.
+ *
+ * A peer to `command/` at the core level. Users never import from
+ * `screen/output/` directly.
+ *
+ * @module
+ */
+
+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

@@ -5,8 +5,6 @@
  * @module
  */
 
-export { Output } from './output.js'
-
 export { useOutputStore } from './use-output-store.js'
 
 export { createOutputStore } from './store.js'

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

@@ -27,9 +27,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/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'
 
 // ---------------------------------------------------------------------------

packages/core/src/stories/viewer/components/field-control.tsx

@@ -1,12 +1,9 @@
 import type { Option } from '@inkjs/ui'
+import { ConfirmInput, MultiSelect, Select, TextInput } from '@inkjs/ui'
 import { Box, Text } from 'ink'
 import type { ReactElement } from 'react'
 import { match } from 'ts-pattern'
 
-import { ConfirmInput } from '../../../ui/confirm.js'
-import { MultiSelect } from '../../../ui/multi-select.js'
-import { Select } from '../../../ui/select.js'
-import { TextInput } from '../../../ui/text-input.js'
 import type { FieldControlKind } from '../../types.js'
 
 // ---------------------------------------------------------------------------

packages/core/src/stories/viewer/components/preview.tsx

@@ -4,8 +4,8 @@ import type { ComponentType, ReactElement } from 'react'
 import { useMemo, useRef } from 'react'
 import { match } from 'ts-pattern'
 
-import { ScrollArea } from '../../../ui/scroll-area.js'
-import { useSize } from '../../../ui/use-size.js'
+import { ScrollArea } from '../../../ui/layout/scroll-area.js'
+import { useSize } from '../../../ui/layout/use-size.js'
 import type { FieldDescriptor, Story } from '../../types.js'
 import type { FieldError } from '../../validate.js'
 import { applyDecorators } from '../utils.js'

packages/core/src/stories/viewer/components/props-editor.tsx

@@ -2,8 +2,8 @@ import { Box, Text } from 'ink'
 import type { ReactElement } from 'react'
 import { match } from 'ts-pattern'
 
-import type { TabItem } from '../../../ui/tabs.js'
-import { Tabs } from '../../../ui/tabs.js'
+import type { TabItem } from '../../../ui/layout/tabs.js'
+import { Tabs } from '../../../ui/layout/tabs.js'
 import type { FieldControlKind, FieldDescriptor } from '../../types.js'
 import type { FieldError } from '../../validate.js'
 import { FieldControl } from './field-control.js'

packages/core/src/stories/viewer/components/sidebar.tsx

@@ -5,8 +5,8 @@ import type { ReactElement } from 'react'
 import { useEffect, useMemo, useRef, useState } from 'react'
 import { match } from 'ts-pattern'
 
-import { ScrollArea } from '../../../ui/scroll-area.js'
-import { useSize } from '../../../ui/use-size.js'
+import { ScrollArea } from '../../../ui/layout/scroll-area.js'
+import { useSize } from '../../../ui/layout/use-size.js'
 import type { Story, StoryEntry, StoryGroup } from '../../types.js'
 
 // ---------------------------------------------------------------------------

packages/core/src/stories/viewer/stories-app.tsx

@@ -8,7 +8,7 @@ import type { ReactElement } from 'react'
 import { useCallback, useEffect, useMemo, useState } from 'react'
 import { match } from 'ts-pattern'
 
-import { FullScreen } from '../../ui/fullscreen.js'
+import { FullScreen } from '../../ui/layout/fullscreen.js'
 import type { StoryRegistry } from '../registry.js'
 import { schemaToFieldDescriptors } from '../schema.js'
 import type { Story, StoryEntry, StoryGroup } from '../types.js'

packages/core/src/stories/viewer/stories-check.tsx

@@ -5,8 +5,8 @@ import type { ReactElement } from 'react'
 import { useEffect, useRef } from 'react'
 import { match } from 'ts-pattern'
 
-import { Output } from '../../ui/output/index.js'
-import { useScreenContext } from '../../ui/provider.js'
+import { useScreenContext } from '../../screen/provider.js'
+import { Output } from '../../ui/output.js'
 import { checkStories } from '../check.js'
 import { discoverStories } from '../discover.js'
 import { createStoryImporter } from '../importer.js'

packages/core/src/test/context.test.ts

@@ -1,6 +1,6 @@
 import { describe, expect, it } from 'vitest'
 
-import { createTestContext, mockLog, mockPrompts, mockSpinner, mockStatus } from './context.js'
+import { createTestContext, mockLog, mockPrompts, mockStatus } from './context.js'
 
 describe('test context factory', () => {
   it('should return a context with default args', () => {
@@ -54,12 +54,6 @@ describe('test context factory', () => {
     expect(ctx.status).toBe(status)
   })
 
-  it('should accept custom spinner via deprecated option', () => {
-    const spinner = mockSpinner()
-    const { ctx } = createTestContext({ spinner })
-    expect(ctx.status.spinner).toBe(spinner)
-  })
-
   it('should provide status with stub methods by default', () => {
     const { ctx } = createTestContext()
     expect(() => ctx.status.spinner.start('loading...')).not.toThrow()

packages/core/src/test/context.ts

@@ -169,16 +169,20 @@ export function mockStatus(spinnerOverride?: Spinner): Status {
       isCancelled: false,
     })),
     tasks: vi.fn(async () => {}),
-    taskLog: vi.fn((): TaskLogHandle => ({
-      message: vi.fn(),
-      success: vi.fn(),
-      error: vi.fn(),
-      group: vi.fn((): TaskLogGroupHandle => ({
+    taskLog: vi.fn(
+      (): TaskLogHandle => ({
         message: vi.fn(),
         success: vi.fn(),
         error: vi.fn(),
-      })),
-    })),
+        group: vi.fn(
+          (): TaskLogGroupHandle => ({
+            message: vi.fn(),
+            success: vi.fn(),
+            error: vi.fn(),
+          })
+        ),
+      })
+    ),
   } as Status
 }
 
@@ -216,8 +220,7 @@ function resolvePrompts(opts: TestContextOptions): Prompts {
 }
 
 /**
- * Resolve the status instance from overrides, supporting the deprecated
- * `spinner` override for backwards compatibility.
+ * Resolve the status instance from overrides or create a mock.
  *
  * @private
  * @param opts - Test context options.
@@ -227,9 +230,6 @@ function resolveStatus(opts: TestContextOptions): Status {
   if (opts.status !== undefined) {
     return opts.status
   }
-  if (opts.spinner !== undefined) {
-    return mockStatus(opts.spinner)
-  }
   return mockStatus()
 }
 

packages/core/src/test/types.ts

@@ -1,6 +1,6 @@
 import type { vi } from 'vitest'
 
-import type { CommandContext, Log, Prompts, Spinner, Status } from '@/context/types.js'
+import type { CommandContext, Log, Prompts, Status } from '@/context/types.js'
 import type {
   AnyRecord,
   CliConfigOptions,
@@ -33,11 +33,6 @@ export interface TestContextOptions<
   readonly log?: Log
   readonly prompts?: Prompts
   readonly status?: Status
-  /**
-   * @deprecated Use `status` instead. When provided, creates a Status
-   * wrapper around this spinner for backwards compatibility.
-   */
-  readonly spinner?: Spinner
 }
 
 /**

packages/core/src/types/cli.ts

@@ -1,6 +1,6 @@
 import type { z } from 'zod'
 
-import type { DisplayConfig, Log, Prompts, Spinner, Status } from '@/context/types.js'
+import type { DisplayConfig, Log, Prompts, Status } from '@/context/types.js'
 
 import type { CommandMap, CommandsConfig } from './command.js'
 import type { Middleware } from './middleware.js'
@@ -167,11 +167,6 @@ export interface CliOptions<TSchema extends z.ZodType = z.ZodType> {
    * `@clack/prompts`-backed status indicators are created automatically.
    */
   readonly status?: Status
-  /**
-   * @deprecated Use `status` instead. When provided, creates a Status
-   * wrapper around this spinner for backwards compatibility.
-   */
-  readonly spinner?: Spinner
   /**
    * When `true` (the default), yargs rejects unknown flags with an error.
    * Set to `false` to allow unknown flags to pass through unchecked.