wp-typia 0.16.0 → 0.16.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wp-typia",
-  "version": "0.16.0",
+  "version": "0.16.2",
   "description": "Canonical CLI package for wp-typia scaffolding and project workflows",
   "packageManager": "bun@1.3.11",
   "type": "module",
@@ -65,7 +65,7 @@
     "@bunli/tui": "0.6.0",
     "@bunli/utils": "0.6.0",
     "@wp-typia/api-client": "^0.4.2",
-    "@wp-typia/project-tools": "0.16.0",
+    "@wp-typia/project-tools": "0.16.1",
     "better-result": "^2.7.0",
     "react": "19.2.0",
     "react-dom": "19.2.0",

package/src/ui/README.md

@@ -15,3 +15,29 @@ Constraints:
   shell automation.
 - `@wp-typia/project-tools` remains the runtime library; these screens should only
   collect input and hand the resolved command state back to `wp-typia`.
+
+Alternate-buffer lifecycle contract:
+
+- `LazyFlow` owns pre-mount lifecycle safety for lazy loader failures and loading-time quit.
+- Mounted flows must use the shared alternate-buffer lifecycle helper instead of ad hoc exit logic.
+- `create`, `add`, and `migrate` must always call `runtime.exit()` on submit success, cancel, and quit.
+- Runtime execution failures use exit-on-failure: report the error, then exit immediately.
+
+First-party form interaction contract:
+
+- `create`, `add`, and `migrate` use a shared first-party form layer instead of relying on `SchemaForm` field traversal.
+- Small viewport safety is part of the `wp-typia` contract: active fields must stay inside a scrollable viewport and footer help must not overlap the form body.
+- Keyboard traversal is owned locally by `wp-typia`.
+  - `Tab` / `Shift+Tab` move across the visible field order.
+  - Select fields handle arrow-key movement and preserve traversal when moving back out to the next field.
+  - Checkbox fields use `Space` / `Enter` to toggle without trapping focus.
+  - Hidden conditional fields must never keep focus or leak stale values into submit payloads.
+- `Ctrl+S` submit must stay reachable through the shared first-party field layer, not only through Bunli's form-level hotkeys.
+
+Regression and triage contract:
+
+- The committed regression contract is the first-party model and layout test suite under `packages/wp-typia/tests`.
+- `create-flow-layout.test.ts` keeps the small-viewport scroll model and checkbox-cluster ordering pinned.
+- `tui-interaction-models.test.ts` keeps visible field ordering and submit sanitization pinned for `add` and `migrate`.
+- The committed tests deliberately stop short of a repo-level PTY smoke because the alternate-buffer harness cost and flake surface outweighed the regression value for this round.
+- If a future regression needs terminal-level confirmation, reproduce it from the real `wp-typia` command first before classifying it as a Bunli-level issue.

package/src/ui/add-flow-model.ts

@@ -0,0 +1,120 @@
+import { z } from "zod";
+
+import {
+	FIRST_PARTY_SELECT_FIELD_BODY_HEIGHT,
+	FIRST_PARTY_TEXT_FIELD_BODY_HEIGHT,
+	getFirstPartyScrollTop,
+	getFirstPartyViewportHeight,
+} from "./first-party-form-model";
+
+export const addFlowSchema = z.object({
+	anchor: z.string().optional(),
+	block: z.string().optional(),
+	"data-storage": z.string().optional(),
+	kind: z
+		.enum(["block", "variation", "pattern", "binding-source", "hooked-block"])
+		.default("block"),
+	name: z.string().optional(),
+	"persistence-policy": z.string().optional(),
+	position: z.string().optional(),
+	template: z.string().optional(),
+});
+
+export type AddFlowValues = z.infer<typeof addFlowSchema>;
+
+export type AddFieldName =
+	| "kind"
+	| "name"
+	| "template"
+	| "block"
+	| "anchor"
+	| "position"
+	| "data-storage"
+	| "persistence-policy";
+
+const ADD_FIELD_ORDER = [
+	"kind",
+	"name",
+	"template",
+	"block",
+	"anchor",
+	"position",
+	"data-storage",
+	"persistence-policy",
+] as const satisfies ReadonlyArray<AddFieldName>;
+
+const ADD_FIELD_HEIGHTS: Record<AddFieldName, number> = {
+	anchor: FIRST_PARTY_TEXT_FIELD_BODY_HEIGHT,
+	block: FIRST_PARTY_SELECT_FIELD_BODY_HEIGHT,
+	"data-storage": FIRST_PARTY_SELECT_FIELD_BODY_HEIGHT,
+	kind: FIRST_PARTY_SELECT_FIELD_BODY_HEIGHT,
+	name: FIRST_PARTY_TEXT_FIELD_BODY_HEIGHT,
+	"persistence-policy": FIRST_PARTY_SELECT_FIELD_BODY_HEIGHT,
+	position: FIRST_PARTY_SELECT_FIELD_BODY_HEIGHT,
+	template: FIRST_PARTY_SELECT_FIELD_BODY_HEIGHT,
+};
+
+export function isAddPersistenceTemplate(template?: string): boolean {
+	return template === "persistence" || template === "compound";
+}
+
+export function getVisibleAddFieldNames(values: Partial<AddFlowValues>): Array<AddFieldName> {
+	switch (values.kind ?? "block") {
+		case "variation":
+			return ["kind", "name", "block"];
+		case "pattern":
+			return ["kind", "name"];
+		case "binding-source":
+			return ["kind", "name"];
+		case "hooked-block":
+			return ["kind", "name", "anchor", "position"];
+		case "block":
+		default:
+			return ADD_FIELD_ORDER.filter((name) => {
+				if (name === "data-storage" || name === "persistence-policy") {
+					return isAddPersistenceTemplate(values.template);
+				}
+				return name === "kind" || name === "name" || name === "template";
+			});
+	}
+}
+
+export function getAddViewportHeight(terminalHeight = 24): number {
+	return getFirstPartyViewportHeight(terminalHeight);
+}
+
+export function getAddScrollTop(options: {
+	activeFieldName: string | null;
+	values: Partial<AddFlowValues>;
+	viewportHeight: number;
+}): number {
+	const { activeFieldName, values, viewportHeight } = options;
+	return getFirstPartyScrollTop({
+		activeFieldName,
+		fieldHeights: ADD_FIELD_HEIGHTS,
+		visibleFieldNames: getVisibleAddFieldNames(values),
+		viewportHeight,
+	});
+}
+
+export function sanitizeAddSubmitValues(values: AddFlowValues): Record<string, unknown> {
+	const visibleFields = new Set(getVisibleAddFieldNames(values));
+	const sanitized: Record<string, unknown> = {};
+
+	for (const fieldName of visibleFields) {
+		const value = values[fieldName];
+		if (typeof value === "string") {
+			const trimmed = value.trim();
+			if (trimmed.length > 0) {
+				sanitized[fieldName] = trimmed;
+			}
+			continue;
+		}
+
+		if (value !== undefined && value !== null) {
+			sanitized[fieldName] = value;
+		}
+	}
+
+	return sanitized;
+}

package/src/ui/add-flow.tsx

@@ -1,34 +1,95 @@
-import { useState } from "react";
+import { createElement, useMemo } from "react";
 
-import { useRuntime } from "@bunli/runtime/app";
-import { Alert, SchemaForm } from "@bunli/tui";
+import {
+	Form,
+	type SelectOption,
+	useFormContext,
+	useTerminalDimensions,
+} from "@bunli/tui";
 import { HOOKED_BLOCK_POSITION_IDS } from "@wp-typia/project-tools";
-import { z } from "zod";
 
 import { executeAddCommand } from "../runtime-bridge";
+import { useAlternateBufferLifecycle } from "./alternate-buffer-lifecycle";
+import {
+	type AddFlowValues,
+	addFlowSchema,
+	getAddScrollTop,
+	getAddViewportHeight,
+	getVisibleAddFieldNames,
+	isAddPersistenceTemplate,
+	sanitizeAddSubmitValues,
+} from "./add-flow-model";
+import {
+	FirstPartyScrollBox,
+	FirstPartySelectField,
+	FirstPartyTextField,
+} from "./first-party-form";
+import { getWrappedFieldNeighbors } from "./first-party-form-model";
 
-const addFlowSchema = z.object({
-	anchor: z.string().optional(),
-	block: z.string().optional(),
-	"data-storage": z.string().optional(),
-	kind: z.enum(["block", "variation", "pattern", "binding-source", "hooked-block"]).default("block"),
-	name: z.string().optional(),
-	"persistence-policy": z.string().optional(),
-	position: z.string().optional(),
-	template: z.string().optional(),
-});
+const kindOptions: SelectOption[] = [
+	{ name: "block", description: "Add a real block slice", value: "block" },
+	{
+		name: "variation",
+		description: "Add a variation to an existing block",
+		value: "variation",
+	},
+	{
+		name: "pattern",
+		description: "Add a PHP block pattern shell",
+		value: "pattern",
+	},
+	{
+		name: "binding-source",
+		description: "Add a shared block bindings source",
+		value: "binding-source",
+	},
+	{
+		name: "hooked-block",
+		description: "Add block.json hook metadata to an existing block",
+		value: "hooked-block",
+	},
+];
 
-type AddFlowValues = z.infer<typeof addFlowSchema>;
+const templateOptions: SelectOption[] = [
+	{ name: "basic", description: "Basic block scaffold", value: "basic" },
+	{
+		name: "interactivity",
+		description: "Interactivity API block scaffold",
+		value: "interactivity",
+	},
+	{
+		name: "persistence",
+		description: "Persistence-enabled block scaffold",
+		value: "persistence",
+	},
+	{
+		name: "compound",
+		description: "Compound parent + child scaffold",
+		value: "compound",
+	},
+];
 
-type AddFlowProps = {
-	cwd: string;
-	initialValues: Partial<AddFlowValues>;
-	workspaceBlockOptions: Array<{
-		description: string;
-		name: string;
-		value: string;
-	}>;
-};
+const dataStorageOptions: SelectOption[] = [
+	{
+		name: "custom-table",
+		description: "Dedicated custom table storage",
+		value: "custom-table",
+	},
+	{
+		name: "post-meta",
+		description: "Persist through post meta",
+		value: "post-meta",
+	},
+];
+
+const persistencePolicyOptions: SelectOption[] = [
+	{
+		name: "authenticated",
+		description: "Authenticated write policy",
+		value: "authenticated",
+	},
+	{ name: "public", description: "Public token policy", value: "public" },
+];
 
 const HOOKED_BLOCK_POSITION_DESCRIPTIONS: Record<
 	(typeof HOOKED_BLOCK_POSITION_IDS)[number],
@@ -40,180 +101,182 @@ const HOOKED_BLOCK_POSITION_DESCRIPTIONS: Record<
 	lastChild: "Insert as the last child of the anchor block",
 };
 
-export function AddFlow({ cwd, initialValues, workspaceBlockOptions }: AddFlowProps) {
-	const runtime = useRuntime();
-	const [errorMessage, setErrorMessage] = useState<string | null>(null);
+type AddFlowProps = {
+	cwd: string;
+	initialValues: Partial<AddFlowValues>;
+	workspaceBlockOptions: Array<{
+		description: string;
+		name: string;
+		value: string;
+	}>;
+};
 
-	return (
-		<>
-			{errorMessage ? (
-				<Alert message={errorMessage} title="Add failed" tone="danger" />
-			) : null}
-			<SchemaForm
-				fields={[
-					{
-						kind: "select",
-						label: "Kind",
-						name: "kind",
-						options: [
-							{ name: "block", description: "Add a real block slice", value: "block" },
-							{
-								name: "variation",
-								description: "Add a variation to an existing block",
-								value: "variation",
-							},
-							{
-								name: "pattern",
-								description: "Add a PHP block pattern shell",
-								value: "pattern",
-							},
-							{
-								name: "binding-source",
-								description: "Add a shared block bindings source",
-								value: "binding-source",
-							},
-							{
-								name: "hooked-block",
-								description: "Add block.json hook metadata to an existing block",
-								value: "hooked-block",
-							},
-						],
-					},
-					{
-						kind: "text",
-						label: "Block name",
+type AddSelectFieldName = {
+	[K in keyof AddFlowValues]-?: AddFlowValues[K] extends string | undefined ? K : never;
+}[keyof AddFlowValues];
+
+function getAddNameLabel(kind?: string): string {
+	switch (kind) {
+		case "variation":
+			return "Variation name";
+		case "pattern":
+			return "Pattern name";
+		case "binding-source":
+			return "Binding source name";
+		case "hooked-block":
+			return "Target block";
+		case "block":
+		default:
+			return "Block name";
+	}
+}
+
+function AddFlowFields({
+	workspaceBlockOptions,
+}: {
+	workspaceBlockOptions: AddFlowProps["workspaceBlockOptions"];
+}) {
+	const { activeFieldName, values } = useFormContext();
+	const { height: terminalHeight = 24 } = useTerminalDimensions();
+	const addValues = values as Partial<AddFlowValues>;
+	const kind = addValues.kind ?? "block";
+	const template = addValues.template;
+	const viewportHeight = getAddViewportHeight(terminalHeight);
+	const scrollValues = useMemo(() => ({ kind, template }), [kind, template]);
+	const scrollTop = useMemo(
+		() =>
+			getAddScrollTop({
+				activeFieldName,
+				values: scrollValues,
+				viewportHeight,
+			}),
+		[activeFieldName, scrollValues, viewportHeight],
+	);
+
+	const visibleFields = new Set(getVisibleAddFieldNames(addValues));
+	const orderedVisibleFields = useMemo(() => getVisibleAddFieldNames(addValues), [addValues]);
+	const hookedBlockNameUsesSelect = kind === "hooked-block" && workspaceBlockOptions.length > 0;
+	const variationBlockUsesSelect = kind === "variation" && workspaceBlockOptions.length > 0;
+
+	return createElement(
+		FirstPartyScrollBox,
+		{ scrollTop, viewportHeight },
+		[
+			createElement(FirstPartySelectField, {
+				...getWrappedFieldNeighbors(orderedVisibleFields, "kind"),
+				key: "kind",
+				label: "Kind",
+				name: "kind" satisfies AddSelectFieldName,
+				options: kindOptions,
+			}),
+			visibleFields.has("name") && !hookedBlockNameUsesSelect
+				? createElement(FirstPartyTextField, {
+						...getWrappedFieldNeighbors(orderedVisibleFields, "name"),
+						key: `name-text:${kind}`,
+						label: getAddNameLabel(kind),
 						name: "name",
-						visibleWhen: (values) => values.kind === "block",
-					},
-					{
-						kind: "select",
+					})
+				: null,
+			hookedBlockNameUsesSelect
+				? createElement(FirstPartySelectField, {
+						...getWrappedFieldNeighbors(orderedVisibleFields, "name"),
+						key: "name-select:hooked-block",
+						label: getAddNameLabel(kind),
+						name: "name" satisfies AddSelectFieldName,
+						options: workspaceBlockOptions,
+					})
+				: null,
+			visibleFields.has("template")
+				? createElement(FirstPartySelectField, {
+						...getWrappedFieldNeighbors(orderedVisibleFields, "template"),
+						key: "template",
 						label: "Template family",
-						name: "template",
-						options: [
-							{ name: "basic", description: "Basic block scaffold", value: "basic" },
-							{
-								name: "interactivity",
-								description: "Interactivity API block scaffold",
-								value: "interactivity",
-							},
-							{
-								name: "persistence",
-								description: "Persistence-enabled block scaffold",
-								value: "persistence",
-							},
-							{
-								name: "compound",
-								description: "Compound parent + child scaffold",
-								value: "compound",
-							},
-						],
-						visibleWhen: (values) => values.kind === "block",
-					},
-					{
-						kind: "text",
-						label: "Variation name",
-						name: "name",
-						visibleWhen: (values) => values.kind === "variation",
-					},
-					{
-						kind: workspaceBlockOptions.length > 0 ? "select" : "text",
+						name: "template" satisfies AddSelectFieldName,
+						options: templateOptions,
+					})
+				: null,
+			visibleFields.has("block") && !variationBlockUsesSelect
+				? createElement(FirstPartyTextField, {
+						...getWrappedFieldNeighbors(orderedVisibleFields, "block"),
+						key: "block-text",
 						label: "Target block",
 						name: "block",
-						options: workspaceBlockOptions,
-						visibleWhen: (values) => values.kind === "variation",
-					},
-					{
-						kind: "text",
-						label: "Pattern name",
-						name: "name",
-						visibleWhen: (values) => values.kind === "pattern",
-					},
-					{
-						kind: "text",
-						label: "Binding source name",
-						name: "name",
-						visibleWhen: (values) => values.kind === "binding-source",
-					},
-					{
-						kind: workspaceBlockOptions.length > 0 ? "select" : "text",
+					})
+				: null,
+			variationBlockUsesSelect
+				? createElement(FirstPartySelectField, {
+						...getWrappedFieldNeighbors(orderedVisibleFields, "block"),
+						key: "block-select",
 						label: "Target block",
-						name: "name",
+						name: "block" satisfies AddSelectFieldName,
 						options: workspaceBlockOptions,
-						visibleWhen: (values) => values.kind === "hooked-block",
-					},
-					{
-						kind: "text",
+					})
+				: null,
+			visibleFields.has("anchor")
+				? createElement(FirstPartyTextField, {
+						...getWrappedFieldNeighbors(orderedVisibleFields, "anchor"),
+						key: "anchor",
 						label: "Anchor block name",
 						name: "anchor",
-						visibleWhen: (values) => values.kind === "hooked-block",
-					},
-					{
-						kind: "select",
+					})
+				: null,
+			visibleFields.has("position")
+				? createElement(FirstPartySelectField, {
+						...getWrappedFieldNeighbors(orderedVisibleFields, "position"),
+						key: "position",
 						label: "Hook position",
-						name: "position",
+						name: "position" satisfies AddSelectFieldName,
 						options: HOOKED_BLOCK_POSITION_IDS.map((position) => ({
-							name: position,
 							description: HOOKED_BLOCK_POSITION_DESCRIPTIONS[position],
+							name: position,
 							value: position,
 						})),
-						visibleWhen: (values) => values.kind === "hooked-block",
-					},
-					{
-						kind: "select",
+					})
+				: null,
+			visibleFields.has("data-storage") && isAddPersistenceTemplate(template)
+				? createElement(FirstPartySelectField, {
+						...getWrappedFieldNeighbors(orderedVisibleFields, "data-storage"),
+						key: "data-storage",
 						label: "Data storage",
-						name: "data-storage",
-						options: [
-							{
-								name: "custom-table",
-								description: "Dedicated custom table storage",
-								value: "custom-table",
-							},
-							{
-								name: "post-meta",
-								description: "Persist through post meta",
-								value: "post-meta",
-							},
-						],
-						visibleWhen: (values) =>
-							values.kind === "block" &&
-							(values.template === "persistence" || values.template === "compound"),
-					},
-					{
-						kind: "select",
+						name: "data-storage" satisfies AddSelectFieldName,
+						options: dataStorageOptions,
+					})
+				: null,
+			visibleFields.has("persistence-policy") && isAddPersistenceTemplate(template)
+				? createElement(FirstPartySelectField, {
+						...getWrappedFieldNeighbors(orderedVisibleFields, "persistence-policy"),
+						key: "persistence-policy",
 						label: "Persistence policy",
-						name: "persistence-policy",
-						options: [
-							{
-								name: "authenticated",
-								description: "Authenticated write policy",
-								value: "authenticated",
-							},
-							{ name: "public", description: "Public token policy", value: "public" },
-						],
-						visibleWhen: (values) =>
-							values.kind === "block" &&
-							(values.template === "persistence" || values.template === "compound"),
-					},
-				]}
-				initialValues={initialValues}
-				onCancel={() => runtime.exit()}
-				onSubmit={async (values) => {
-					try {
-						setErrorMessage(null);
-						await executeAddCommand({
-							cwd,
-							flags: values,
-							kind: values.kind,
-							name: values.name,
-						});
-						runtime.exit();
-					} catch (error) {
-						setErrorMessage(error instanceof Error ? error.message : String(error));
-					}
-				}}
-				schema={addFlowSchema}
-				title="Extend a wp-typia workspace"
-			/>
-		</>
+						name: "persistence-policy" satisfies AddSelectFieldName,
+						options: persistencePolicyOptions,
+					})
+				: null,
+		],
+	);
+}
+
+export function AddFlow({ cwd, initialValues, workspaceBlockOptions }: AddFlowProps) {
+	const { handleCancel, handleSubmit } = useAlternateBufferLifecycle("wp-typia add failed");
+
+	return (
+		<Form
+			initialValues={initialValues}
+			onCancel={handleCancel}
+			onSubmit={async (values) =>
+				handleSubmit(async () => {
+					const flags = sanitizeAddSubmitValues(values);
+					await executeAddCommand({
+						cwd,
+						flags,
+						kind: values.kind,
+						name: typeof flags.name === "string" ? flags.name : undefined,
+					});
+				})
+			}
+			schema={addFlowSchema}
+			title="Extend a wp-typia workspace"
+		>
+			<AddFlowFields workspaceBlockOptions={workspaceBlockOptions} />
+		</Form>
 	);
 }