@sundaeswap/sprinkles 0.5.0 → 0.6.0

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";