@sundaeswap/sprinkles 0.5.0 → 0.6.1

package/src/Sprinkle/prompts.ts

@@ -97,7 +97,7 @@ export const selectCancellable = createPrompt<
   unknown | null,
   SelectConfig<unknown>
 >((config, done) => {
-  const { loop = true, pageSize = 7 } = config;
+  const { loop = true, pageSize = 15 } = config;
   const theme = makeTheme(selectTheme, config.theme);
   const [status, setStatus] = useState<"idle" | "done" | "cancelled">("idle");
   const prefix = usePrefix({ status: status === "cancelled" ? "done" : status, theme });
@@ -203,6 +203,76 @@ export const selectCancellable = createPrompt<
   return `${prefix} ${config.message} ${helpTip}\n${page}`;
 });
 
+/**
+ * Clears N lines above the cursor.
+ * Used after prompts to clean up menu output.
+ */
+export function clearLines(count: number): void {
+  // Move up and clear each line
+  process.stdout.write("\x1b[1A\x1b[2K".repeat(count));
+}
+
+/**
+ * Select prompt that clears its output after completion.
+ * Returns the selected value or null if cancelled.
+ */
+export async function selectWithClear<T>(
+  config: SelectConfig<T>,
+): Promise<T | null> {
+  const result = await selectCancellable(config as SelectConfig<unknown>);
+
+  // Clear the "done" line that inquirer left behind
+  // Move up one line, clear it, move cursor to start
+  process.stdout.write("\x1b[1A\x1b[2K\x1b[G");
+
+  return result as T | null;
+}
+
+/**
+ * Input prompt that clears its output after completion.
+ * Returns the input value or null if cancelled.
+ */
+export async function inputWithClear(
+  config: InputConfig,
+): Promise<string | null> {
+  const result = await inputCancellable(config);
+
+  // Clear the "done" line
+  process.stdout.write("\x1b[1A\x1b[2K\x1b[G");
+
+  return result;
+}
+
+/**
+ * Password prompt that clears its output after completion.
+ * Returns the password or null if cancelled.
+ */
+export async function passwordWithClear(
+  config: PasswordConfig,
+): Promise<string | null> {
+  const result = await passwordCancellable(config);
+
+  // Clear the "done" line
+  process.stdout.write("\x1b[1A\x1b[2K\x1b[G");
+
+  return result;
+}
+
+/**
+ * Confirm prompt that clears its output after completion.
+ * Returns true/false or null if cancelled.
+ */
+export async function confirmWithClear(
+  config: ConfirmConfig,
+): Promise<boolean | null> {
+  const result = await confirmCancellable(config);
+
+  // Clear the "done" line
+  process.stdout.write("\x1b[1A\x1b[2K\x1b[G");
+
+  return result;
+}
+
 interface InputConfig {
   message: string;
   default?: string;

package/src/Sprinkle/type-guards.ts

@@ -7,6 +7,7 @@ import {
   Kind,
   type TBigInt,
   type TLiteral,
+  type TNull,
   type TObject,
   type TSchema,
   type TString,
@@ -17,6 +18,7 @@ import {
   type TRef,
   type TImport,
   type TOptional,
+  type Static,
   OptionalKind,
 } from "@sinclair/typebox";
 
@@ -49,3 +51,43 @@ export const isUnion = (t: TSchema): t is TUnion => t[Kind] === "Union";
  */
 export const isSensitive = (t: TSchema): boolean =>
   isString(t) && t.sensitive === true;
+
+/**
+ * Check if a schema is a Null type.
+ */
+export const isNull = (t: TSchema): t is TNull => t[Kind] === "Null";
+
+/**
+ * Check if a schema allows null values.
+ * Returns true for TNull or unions containing TNull.
+ */
+export const isNullable = (t: TSchema): boolean => {
+  if (isNull(t)) return true;
+  if (isUnion(t)) return t.anyOf.some((member) => isNull(member));
+  return false;
+};
+
+/**
+ * Unwrap a nullable type to get the non-null inner type.
+ * For unions with Null, returns the union without the Null member.
+ * For single non-null member unions, returns just that type.
+ */
+export const unwrapNullable = (t: TSchema): TSchema => {
+  if (isUnion(t)) {
+    const nonNull = t.anyOf.filter((member) => !isNull(member));
+    if (nonNull.length === 1) return nonNull[0]!;
+    return { ...t, anyOf: nonNull } as TSchema;
+  }
+  return t;
+};
+
+/**
+ * Check if a schema has a default value defined.
+ */
+export const hasDefault = (t: TSchema): boolean => "default" in t;
+
+/**
+ * Get the default value from a schema, if defined.
+ */
+export const getDefault = <T extends TSchema>(t: T): Static<T> | undefined =>
+  t.default as Static<T> | undefined;

package/src/Sprinkle/types.ts

@@ -71,3 +71,46 @@ export class UserCancelledError extends Error {
     this.name = "UserCancelledError";
   }
 }
+
+// --- Menu-based FillInStruct types ---
+
+/**
+ * State tracking for a single field during menu-based editing.
+ */
+export type FieldState<T = unknown> =
+  | { status: "unset" }
+  | { status: "set"; value: T }
+  | { status: "null" }; // explicitly set to null
+
+/**
+ * Result of counting required fields in a schema.
+ */
+export interface RequiredFieldCount {
+  total: number;
+  filled: number;
+}
+
+/**
+ * Result from field menu interaction.
+ */
+export type FieldMenuResult<T = unknown> =
+  | { action: "edit" }
+  | { action: "view" }
+  | { action: "clear" }
+  | { action: "setNull" }
+  | { action: "reset"; defaultValue: T }
+  | { action: "back" };
+
+/**
+ * Result from object menu interaction.
+ */
+export type ObjectMenuResult<T = unknown> =
+  | { action: "submit"; value: T }
+  | { action: "cancel" };
+
+/**
+ * Result from array menu interaction.
+ */
+export type ArrayMenuResult<T = unknown> =
+  | { action: "done"; value: T[] }
+  | { action: "back" };

package/src/Sprinkle/utils/field-utils.ts

@@ -0,0 +1,158 @@
+/**
+ * Field utilities for menu-based struct editing.
+ * Provides required field counting and label building.
+ */
+
+import type { TObject, TSchema } from "@sinclair/typebox";
+import type { FieldState, RequiredFieldCount } from "../types.js";
+import {
+  isOptional,
+  isNullable,
+  hasDefault,
+  getDefault,
+  isLiteral,
+} from "../type-guards.js";
+import { formatValuePreview } from "./formatting.js";
+
+/**
+ * Count required fields in an object schema and how many are filled.
+ *
+ * @param type - The object schema
+ * @param state - Map of field names to their current state
+ * @returns Count of total required fields and how many are filled
+ */
+export function countRequiredFields(
+  type: TObject,
+  state: Map<string, FieldState>,
+): RequiredFieldCount {
+  const fields = type.properties as Record<string, TSchema>;
+  let total = 0;
+  let filled = 0;
+
+  for (const [fieldName, fieldType] of Object.entries(fields)) {
+    // Skip optional fields - they're not required
+    if (isOptional(fieldType)) {
+      continue;
+    }
+
+    // Non-nullable fields with defaults don't require user input
+    if (hasDefault(fieldType) && !isNullable(fieldType)) {
+      continue;
+    }
+
+    // Literal fields auto-fill, so they're not required from the user
+    if (isLiteral(fieldType)) {
+      continue;
+    }
+
+    // This is a required field
+    total++;
+
+    // Check if it's filled
+    const fieldState = state.get(fieldName);
+    if (fieldState?.status === "set" || fieldState?.status === "null") {
+      filled++;
+    }
+  }
+
+  return { total, filled };
+}
+
+/**
+ * Determine if a field is required (must have a value to submit).
+ *
+ * @param fieldType - The field's schema
+ * @returns true if the field is required
+ */
+export function isFieldRequired(fieldType: TSchema): boolean {
+  // Optional fields are not required
+  if (isOptional(fieldType)) {
+    return false;
+  }
+
+  // Literal fields auto-fill, so they're not required from the user
+  if (isLiteral(fieldType)) {
+    return false;
+  }
+
+  // Non-nullable fields with defaults are not required (default will be used)
+  if (hasDefault(fieldType) && !isNullable(fieldType)) {
+    return false;
+  }
+
+  return true;
+}
+
+/**
+ * Build a display label for a field in the menu.
+ *
+ * @param fieldName - The field name
+ * @param fieldType - The field's schema
+ * @param state - The current state of the field
+ * @returns Formatted label string
+ */
+export function buildFieldLabel(
+  fieldName: string,
+  fieldType: TSchema,
+  state: FieldState,
+): string {
+  const required = isFieldRequired(fieldType);
+  const requiredMarker = required ? " *" : "";
+
+  switch (state.status) {
+    case "unset": {
+      // Check for default value
+      if (hasDefault(fieldType)) {
+        const defaultVal = getDefault(fieldType);
+        const preview = formatValuePreview(defaultVal, 30);
+        return `${fieldName}: [default: ${preview}]${requiredMarker}`;
+      }
+      return `${fieldName}: [not set]${requiredMarker}`;
+    }
+
+    case "null":
+      return `${fieldName}: null${requiredMarker}`;
+
+    case "set": {
+      const preview = formatValuePreview(state.value, 40);
+      return `${fieldName}: ${preview}${requiredMarker}`;
+    }
+  }
+}
+
+/**
+ * Get the initial FieldState for a field based on its type and any existing value.
+ *
+ * @param _fieldType - The field's schema (reserved for future logic)
+ * @param existingValue - Existing value if editing
+ * @returns Initial FieldState
+ */
+export function getInitialFieldState<T>(
+  _fieldType: TSchema,
+  existingValue?: T,
+): FieldState<T> {
+  if (existingValue === undefined) {
+    return { status: "unset" };
+  }
+
+  if (existingValue === null) {
+    return { status: "null" };
+  }
+
+  return { status: "set", value: existingValue };
+}
+
+/**
+ * Check if all required fields are filled in the state map.
+ *
+ * @param type - The object schema
+ * @param state - Map of field names to their current state
+ * @returns true if all required fields have values
+ */
+export function allRequiredFieldsFilled(
+  type: TObject,
+  state: Map<string, FieldState>,
+): boolean {
+  const { total, filled } = countRequiredFields(type, state);
+  return filled >= total;
+}

package/src/Sprinkle/utils/formatting.ts

@@ -0,0 +1,127 @@
+/**
+ * Formatting utilities for menu-based struct editing.
+ * Provides value preview, path formatting, and breadcrumb generation.
+ */
+
+/**
+ * Format a value for display in a menu item.
+ * Truncates long values and provides type-appropriate previews.
+ *
+ * @param value - The value to format
+ * @param maxLength - Maximum length before truncation (default 40)
+ * @returns Formatted string representation
+ */
+export function formatValuePreview(value: unknown, maxLength = 40): string {
+  if (value === null) {
+    return "null";
+  }
+
+  if (value === undefined) {
+    return "[not set]";
+  }
+
+  if (typeof value === "string") {
+    const escaped = JSON.stringify(value);
+    if (escaped.length <= maxLength) {
+      return escaped;
+    }
+    // Truncate inside the quotes (guard against negative maxLength from recursion)
+    return `"${value.slice(0, Math.max(0, maxLength - 5))}..."`;
+  }
+
+  if (typeof value === "number" || typeof value === "bigint") {
+    return String(value);
+  }
+
+  if (typeof value === "boolean") {
+    return String(value);
+  }
+
+  if (Array.isArray(value)) {
+    return `[${value.length} item${value.length === 1 ? "" : "s"}]`;
+  }
+
+  if (typeof value === "object") {
+    // For objects, try to show a meaningful preview
+    const keys = Object.keys(value);
+    if (keys.length === 0) {
+      return "{}";
+    }
+
+    // If object has a single key (like union type), show it
+    if (keys.length === 1) {
+      const key = keys[0]!;
+      const innerValue = (value as Record<string, unknown>)[key];
+      const innerPreview = formatValuePreview(innerValue, maxLength - key.length - 6);
+      const preview = `{ ${key}: ${innerPreview} }`;
+      if (preview.length <= maxLength) {
+        return preview;
+      }
+      return `{ ${key}: ... }`;
+    }
+
+    // Multiple keys - show abbreviated
+    const firstKey = keys[0]!;
+    return `{ ${firstKey}: ..., +${keys.length - 1} }`;
+  }
+
+  return String(value).slice(0, maxLength);
+}
+
+/**
+ * Format a path array for display, stripping the "root" prefix.
+ *
+ * @param path - Array of path segments (e.g., ["root", "settings", "name"])
+ * @returns Formatted path string (e.g., "settings.name")
+ */
+export function formatPath(path: string[]): string {
+  // Filter out "root" prefix
+  const filtered = path.filter((segment) => segment !== "root");
+  if (filtered.length === 0) {
+    return "";
+  }
+  return filtered.join(".");
+}
+
+/**
+ * Format a path as a breadcrumb trail for nested navigation.
+ * Truncates from the left if too long.
+ *
+ * @param path - Array of path segments
+ * @param maxLength - Maximum total length (default 50)
+ * @returns Breadcrumb string (e.g., "settings → permissions → mint")
+ */
+export function formatBreadcrumb(path: string[], maxLength = 50): string {
+  // Filter out "root" prefix
+  const filtered = path.filter((segment) => segment !== "root");
+  if (filtered.length === 0) {
+    return "";
+  }
+
+  const separator = " \u2192 "; // Unicode right arrow
+  const joined = filtered.join(separator);
+
+  if (joined.length <= maxLength) {
+    return joined;
+  }
+
+  // Truncate from left, keeping most recent segments
+  const ellipsis = "...";
+  let result = "";
+  for (let i = filtered.length - 1; i >= 0; i--) {
+    const segment = filtered[i]!;
+    const candidate = i === filtered.length - 1 ? segment : segment + separator + result;
+    if (candidate.length + ellipsis.length + separator.length > maxLength && i < filtered.length - 1) {
+      return ellipsis + separator + result;
+    }
+    result = candidate;
+  }
+
+  // Safety clamp: if we still exceeded maxLength (e.g., last segment alone is too long),
+  // fall back to just the ellipsis to honor the maxLength contract.
+  if (result.length > maxLength) {
+    return ellipsis;
+  }
+
+  return result;
+}

package/src/Sprinkle/utils/index.ts

@@ -0,0 +1,17 @@
+/**
+ * Utility functions for menu-based struct editing.
+ */
+
+export {
+  formatValuePreview,
+  formatPath,
+  formatBreadcrumb,
+} from "./formatting.js";
+
+export {
+  countRequiredFields,
+  isFieldRequired,
+  buildFieldLabel,
+  getInitialFieldState,
+  allRequiredFieldsFilled,
+} from "./field-utils.js";