@next-vibe/checker 1.0.11 → 1.0.12

package/src/app/api/[locale]/system/unified-interface/shared/widgets/logic/section.ts

@@ -0,0 +1,90 @@
+/**
+ * Section Widget Logic
+ * Shared data extraction and processing for SECTION widget
+ * Used by both React and CLI implementations
+ */
+
+import type { WidgetData } from "../types";
+
+/**
+ * Processed section data structure
+ */
+export interface ProcessedSection {
+  title: string;
+  content: WidgetData;
+  description?: string;
+  collapsible?: boolean;
+  defaultExpanded?: boolean;
+}
+
+/**
+ * Check if section is empty (has no meaningful content)
+ */
+export function isSectionEmpty(value: Record<string, WidgetData>): boolean {
+  const entries = Object.entries(value);
+  if (entries.length === 0) {
+    return true;
+  }
+
+  // Check if all values are empty/null/undefined
+  return entries.every((entry) => {
+    const val = entry[1];
+    if (val === null || val === undefined) {
+      return true;
+    }
+    if (Array.isArray(val) && val.length === 0) {
+      return true;
+    }
+    if (typeof val === "object" && Object.keys(val).length === 0) {
+      return true;
+    }
+    return false;
+  });
+}
+
+/**
+ * Extract and validate section data from WidgetData
+ */
+export function extractSectionData(value: WidgetData): ProcessedSection | null {
+  // Section must be an object
+  if (typeof value !== "object" || value === null || Array.isArray(value)) {
+    return null;
+  }
+
+  // Extract required title
+  const title =
+    "title" in value && typeof value.title === "string" ? value.title : "";
+
+  if (!title) {
+    return null;
+  }
+
+  // Extract required content
+  const content = "content" in value ? value.content : null;
+
+  if (content === null || content === undefined) {
+    return null;
+  }
+
+  // Extract optional properties
+  const description =
+    "description" in value && typeof value.description === "string"
+      ? value.description
+      : undefined;
+  const collapsible =
+    "collapsible" in value && typeof value.collapsible === "boolean"
+      ? value.collapsible
+      : false;
+  const defaultExpanded =
+    "defaultExpanded" in value && typeof value.defaultExpanded === "boolean"
+      ? value.defaultExpanded
+      : true;
+
+  return {
+    title,
+    content,
+    description,
+    collapsible,
+    defaultExpanded,
+  };
+}

package/src/app/api/[locale]/system/unified-interface/shared/widgets/logic/stats-grid.ts

@@ -0,0 +1,71 @@
+/**
+ * Stats Grid Widget Logic
+ * Shared data extraction and processing for STATS_GRID widget
+ * Used by both React and CLI implementations
+ */
+
+import type { WidgetData } from "../types";
+import type { ProcessedMetricCard } from "./metric-card";
+import { extractMetricCardData } from "./metric-card";
+
+/**
+ * Processed stats grid data structure
+ */
+export interface ProcessedStatsGrid {
+  stats: ProcessedMetricCard[];
+  columns: number;
+  title?: string;
+}
+
+/**
+ * Extract and validate stats grid data from WidgetData
+ */
+export function extractStatsGridData(
+  value: WidgetData,
+): ProcessedStatsGrid | null {
+  // Narrow to object type first
+  const isObject =
+    typeof value === "object" && value !== null && !Array.isArray(value);
+
+  if (!isObject) {
+    return null;
+  }
+
+  // Extract stats array
+  const stats =
+    "stats" in value && Array.isArray(value.stats) ? value.stats : [];
+
+  if (stats.length === 0) {
+    return null;
+  }
+
+  // Extract optional properties
+  const columns =
+    "columns" in value && typeof value.columns === "number" ? value.columns : 3;
+  const title =
+    "title" in value && typeof value.title === "string"
+      ? value.title
+      : undefined;
+
+  // Process each stat using metric card extractor
+  const processedStats = stats
+    .map((stat: WidgetData) => extractMetricCardData(stat))
+    .filter((stat): stat is ProcessedMetricCard => stat !== null);
+
+  if (processedStats.length === 0) {
+    return null;
+  }
+
+  return {
+    stats: processedStats,
+    columns: Math.max(1, Math.min(4, columns)),
+    title,
+  };
+}
+
+/**
+ * Get grid columns count
+ */
+export function getStatsGridColumns(columns: number): number {
+  return Math.max(1, Math.min(4, columns));
+}

package/src/app/api/[locale]/system/unified-interface/shared/widgets/logic/tabs.ts

@@ -0,0 +1,80 @@
+/**
+ * Tabs Widget Logic
+ * Shared data extraction and processing for TABS widget
+ * Used by both React and CLI implementations
+ */
+
+import type { WidgetData } from "../types";
+
+/**
+ * Tab item structure
+ */
+export interface TabItem {
+  id: string;
+  label: string;
+  content: WidgetData;
+  disabled?: boolean;
+}
+
+/**
+ * Processed tabs data structure
+ */
+export interface ProcessedTabs {
+  tabs: TabItem[];
+  activeTab?: string;
+  variant?: "default" | "pills" | "underline";
+}
+
+/**
+ * Extract and validate tabs data from WidgetData
+ */
+export function extractTabsData(value: WidgetData): ProcessedTabs | null {
+  // Handle object value with tabs properties
+  if (typeof value === "object" && value !== null && !Array.isArray(value)) {
+    const tabs = "tabs" in value && Array.isArray(value.tabs) ? value.tabs : [];
+    const activeTab =
+      "activeTab" in value && typeof value.activeTab === "string"
+        ? value.activeTab
+        : undefined;
+    const variant =
+      "variant" in value && typeof value.variant === "string"
+        ? (value.variant as "default" | "pills" | "underline")
+        : "default";
+
+    // Validate tabs
+    const validTabs = tabs
+      .filter((t) => typeof t === "object" && t !== null)
+      .map((t) => ({
+        id: "id" in t && typeof t.id === "string" ? t.id : "",
+        label: "label" in t && typeof t.label === "string" ? t.label : "",
+        content: "content" in t ? t.content : null,
+        disabled:
+          "disabled" in t && typeof t.disabled === "boolean"
+            ? t.disabled
+            : false,
+      }))
+      .filter((t) => t.id && t.label);
+
+    if (validTabs.length === 0) {
+      return null;
+    }
+
+    return {
+      tabs: validTabs,
+      activeTab: activeTab || validTabs[0].id,
+      variant,
+    };
+  }
+
+  // Invalid type
+  return null;
+}
+
+/**
+ * Get active tab from tabs
+ */
+export function getActiveTab(data: ProcessedTabs): TabItem | null {
+  return (
+    data.tabs.find((tab) => tab.id === data.activeTab) || data.tabs[0] || null
+  );
+}

package/src/app/api/[locale]/system/unified-interface/shared/widgets/logic/text.ts

@@ -0,0 +1,105 @@
+/**
+ * Text Widget Logic
+ * Shared data extraction and processing for TEXT widget
+ * Used by both React and CLI implementations
+ */
+
+import type { WidgetData } from "../types";
+
+/**
+ * Processed text data structure
+ */
+export interface ProcessedText {
+  text: string;
+  truncate?: number;
+  format?: "plain" | "code" | "pre";
+}
+
+/**
+ * Extract and validate text data from WidgetData
+ */
+export function extractTextData(value: WidgetData): ProcessedText | null {
+  // Handle string value directly
+  if (typeof value === "string") {
+    return {
+      text: value,
+      format: "plain",
+    };
+  }
+
+  // Handle number value
+  if (typeof value === "number") {
+    return {
+      text: String(value),
+      format: "plain",
+    };
+  }
+
+  // Handle boolean value
+  if (typeof value === "boolean") {
+    return {
+      text: value ? "true" : "false",
+      format: "plain",
+    };
+  }
+
+  // Handle object value with text properties
+  if (typeof value === "object" && value !== null && !Array.isArray(value)) {
+    const text =
+      "text" in value && typeof value.text === "string" ? value.text : "";
+    const truncate =
+      "truncate" in value && typeof value.truncate === "number"
+        ? value.truncate
+        : undefined;
+    const format =
+      "format" in value && typeof value.format === "string"
+        ? value.format
+        : "plain";
+
+    if (!text) {
+      return null;
+    }
+
+    return {
+      text,
+      truncate,
+      format:
+        format === "code" || format === "pre" || format === "plain"
+          ? format
+          : "plain",
+    };
+  }
+
+  // Handle null/undefined
+  if (value === null || value === undefined) {
+    return null;
+  }
+
+  // Handle array by converting to JSON
+  if (Array.isArray(value)) {
+    return {
+      text: JSON.stringify(value),
+      format: "code",
+    };
+  }
+
+  return null;
+}
+
+/**
+ * Truncate text to specified length
+ */
+export function truncateText(text: string, maxLength?: number): string {
+  if (!maxLength || text.length <= maxLength) {
+    return text;
+  }
+  // oxlint-disable-next-line prefer-template
+  return text.slice(0, maxLength - 3) + "...";
+}
+
+/**
+ * Format text value for display
+ */
+export function formatText(text: string, truncate?: number): string {
+  return truncateText(text, truncate);
+}

package/src/app/api/[locale]/system/unified-interface/shared/widgets/logic/title.ts

@@ -0,0 +1,72 @@
+/**
+ * Title Widget Logic
+ * Shared data extraction and processing for TITLE widget
+ * Used by both React and CLI implementations
+ */
+
+import type { WidgetData } from "../types";
+
+/**
+ * Processed title data structure
+ */
+export interface ProcessedTitle {
+  text: string;
+  level: 1 | 2 | 3 | 4 | 5 | 6;
+  subtitle?: string;
+  align?: "left" | "center" | "right";
+}
+
+/**
+ * Extract and validate title data from WidgetData
+ */
+export function extractTitleData(value: WidgetData): ProcessedTitle | null {
+  // Handle string value directly
+  if (typeof value === "string") {
+    return {
+      text: value,
+      level: 2,
+      align: "left",
+    };
+  }
+
+  // Handle object value with title properties
+  if (typeof value === "object" && value !== null && !Array.isArray(value)) {
+    const text =
+      "text" in value && typeof value.text === "string" ? value.text : "";
+
+    if (!text) {
+      return null;
+    }
+
+    const level =
+      "level" in value && typeof value.level === "number" ? value.level : 2;
+    const subtitle =
+      "subtitle" in value && typeof value.subtitle === "string"
+        ? value.subtitle
+        : undefined;
+    const align =
+      "align" in value && typeof value.align === "string"
+        ? value.align
+        : "left";
+
+    return {
+      text,
+      level:
+        level === 1 ||
+        level === 2 ||
+        level === 3 ||
+        level === 4 ||
+        level === 5 ||
+        level === 6
+          ? level
+          : 2,
+      subtitle,
+      align:
+        align === "center" || align === "right" || align === "left"
+          ? align
+          : "left",
+    };
+  }
+
+  return null;
+}

package/src/app/api/[locale]/system/unified-interface/shared/widgets/types.ts

@@ -0,0 +1,240 @@
+import type React from "react";
+
+import type { ResponseType } from "@/app/api/[locale]/shared/types/response.schema";
+import type { WidgetType } from "@/app/api/[locale]/system/unified-interface/shared/types/enums";
+import type { UserRoleValue } from "@/app/api/[locale]/user/user-roles/enum";
+import type { CountryLanguage } from "@/i18n/core/config";
+import type { TranslatedKeyType } from "@/i18n/core/scoped-translation";
+import type { TParams } from "@/i18n/core/static-types";
+
+import type { UnifiedField } from "../types/endpoint";
+import type { Platform } from "../types/platform";
+import type { ExtractWidgetConfig } from "./configs";
+
+export type WidgetData =
+  | string
+  | number
+  | boolean
+  | null
+  | undefined
+  | string[]
+  | number[]
+  | WidgetData[]
+  | { [key: string]: WidgetData };
+
+export interface WidgetInput<TKey extends string> {
+  field: UnifiedField<TKey>;
+  value: WidgetData;
+  context: WidgetRenderContext;
+}
+
+export type WidgetActionType =
+  | "click"
+  | "edit"
+  | "delete"
+  | "create"
+  | "navigate"
+  | "refresh"
+  | "retry"
+  | "cancel"
+  | "submit";
+
+export type WidgetActionPayload =
+  | { type: "click"; fieldName: string; value?: string | number | boolean }
+  | { type: "edit"; fieldName: string; oldValue: string; newValue: string }
+  | { type: "delete"; id: string }
+  | { type: "create"; data: Record<string, string | number | boolean> }
+  | { type: "navigate"; url: string }
+  | { type: "refresh" }
+  | { type: "retry" }
+  | { type: "cancel" }
+  | { type: "submit"; data: Record<string, string | number | boolean> };
+
+export interface WidgetAction {
+  type: WidgetActionType;
+  payload: WidgetActionPayload;
+  metadata?: {
+    fieldName?: string;
+    fieldPath?: string;
+    timestamp?: number;
+  };
+}
+
+export interface WidgetRenderContext {
+  locale: CountryLanguage;
+  isInteractive: boolean;
+  permissions: readonly UserRoleValue[];
+  onNavigate?: (url: string) => void;
+  platform?:
+    | typeof Platform.TRPC
+    | typeof Platform.NEXT_PAGE
+    | typeof Platform.NEXT_API
+    | typeof Platform.CLI
+    | typeof Platform.CLI_PACKAGE;
+  theme?: "light" | "dark" | "system";
+  endpointFields?: Record<string, WidgetData>; // Original endpoint fields for nested path lookup
+  disabled?: boolean; // Disable all form inputs
+  response?: ResponseType<WidgetData>; // Full ResponseType from endpoint (includes success/error state)
+  /**
+   * Optional scoped translation function for this endpoint
+   * When provided, widgets should use this instead of the global translation function
+   * This enables module-specific translations with type safety
+   * Note: Uses method syntax for bivariance - accepts both narrow (scoped) and broad (string) key types
+   */
+  scopedT: (locale: CountryLanguage) => {
+    t(key: string, params?: TParams): TranslatedKeyType;
+  };
+  /**
+   * Endpoint mutations available for widgets to trigger directly
+   * Widgets can call these methods to perform CRUD operations
+   * This enables definition-driven interactions without custom handlers
+   */
+  endpointMutations?: {
+    create?: {
+      submit: (data: Record<string, WidgetData>) => Promise<void>;
+      isSubmitting?: boolean;
+    };
+    update?: {
+      submit: (data: Record<string, WidgetData>) => Promise<void>;
+      isSubmitting?: boolean;
+    };
+    delete?: {
+      submit: (data: Record<string, WidgetData>) => Promise<void>;
+      isSubmitting?: boolean;
+    };
+    read?: {
+      refetch: () => Promise<void>;
+      isLoading?: boolean;
+    };
+  };
+}
+
+/**
+ * Base widget component props.
+ */
+export interface WidgetComponentProps<TKey extends string> {
+  field: UnifiedField<TKey>;
+  fieldName?: string;
+  value: WidgetData;
+  context: WidgetRenderContext;
+  className?: string;
+  onSubmit?: () => void;
+  isSubmitting?: boolean;
+}
+
+/**
+ * Field type with narrowed widget config based on WidgetType discriminator.
+ */
+export type NarrowedField<
+  TKey extends string,
+  T extends WidgetType,
+> = UnifiedField<TKey> & {
+  ui: ExtractWidgetConfig<T, TKey>;
+};
+
+// ============================================================================
+// DISCRIMINATED UNION TYPES FOR TYPE-SAFE WIDGET PROPS
+// ============================================================================
+
+/**
+ * Base widget props shared across all platforms.
+ * The `widgetType` field acts as the discriminator for the union.
+ */
+export interface BaseWidgetProps<TKey extends string, T extends WidgetType> {
+  widgetType: T;
+  field: NarrowedField<TKey, T>;
+  value: WidgetData;
+}
+
+/**
+ * Maps each WidgetType to its base props.
+ * Used to create discriminated unions that TypeScript can narrow automatically.
+ */
+export type WidgetPropsMap<TKey extends string> = {
+  [T in WidgetType]: BaseWidgetProps<TKey, T>;
+};
+
+/**
+ * Union of all widget props - TypeScript narrows this in switch statements.
+ */
+export type WidgetPropsUnion<TKey extends string> =
+  WidgetPropsMap<TKey>[WidgetType];
+
+/**
+ * React-specific widget props. Extends base props with React context and form handling.
+ */
+export interface ReactWidgetProps<
+  T extends WidgetType,
+  TKey extends string,
+> extends BaseWidgetProps<TKey, T> {
+  context: WidgetRenderContext;
+  fieldName?: string;
+  onAction?: (action: WidgetAction) => void | Promise<void>;
+  className?: string;
+  onSubmit?: () => void;
+  isSubmitting?: boolean;
+}
+
+/**
+ * Value-only React widget props for widgets that don't need field definition.
+ * Use this for leaf widgets that only consume value/context (e.g., MetricCardWidget).
+ */
+export interface ValueOnlyReactWidgetProps<T extends WidgetType> {
+  widgetType: T;
+  value: WidgetData;
+  context: WidgetRenderContext;
+  className?: string;
+}
+
+/**
+ * Maps each WidgetType to React-specific props.
+ */
+export type ReactWidgetPropsMap<TKey extends string> = {
+  [T in WidgetType]: ReactWidgetProps<T, TKey>;
+};
+
+/**
+ * Union of all React widget props.
+ */
+export type ReactWidgetPropsUnion<TKey extends string> =
+  ReactWidgetPropsMap<TKey>[WidgetType];
+
+export type WidgetRenderer<TKey extends string> = (
+  props: WidgetComponentProps<TKey>,
+) => React.ReactElement | string | null;
+
+export interface WidgetRegistryEntry<TKey extends string> {
+  type: WidgetType;
+  component:
+    | React.ComponentType<WidgetComponentProps<TKey>>
+    | WidgetRenderer<TKey>;
+  platforms?: Array<
+    | typeof Platform.TRPC
+    | typeof Platform.NEXT_PAGE
+    | typeof Platform.NEXT_API
+    | typeof Platform.CLI
+  >;
+  supportsEditing?: boolean;
+  supportsCRUD?: boolean;
+}
+
+export interface WidgetErrorBoundaryProps {
+  children: React.ReactNode;
+  locale: CountryLanguage;
+  fallback?: React.ReactElement;
+  onError?: (error: Error, errorInfo: React.ErrorInfo) => void;
+}
+
+export interface WidgetLoadingProps {
+  message?: string;
+  size?: "sm" | "md" | "lg";
+}
+
+export interface WidgetEmptyStateProps {
+  message: string;
+  icon?: string;
+  action?: {
+    label: string;
+    onClick: () => void;
+  };
+}