@aquera/ngx-smart-text-field

An Angular smart text field component for AI-assisted expression building. It combines a prompt input with a dynamic dropdown that shows matching expressions, a live preview panel, and a loading state — all wired to your AI backend via simple signal-based inputs and event emitters.

Requirements

| Peer dependency | Version | |---|---| | @angular/core / @angular/common | ^21.2.0 | | @aquera/nile | ^1.2.5-beta-1.2 | | @aquera/nile-elements | ^1.7.8-beta-1.1 |

Installation

npm install @aquera/ngx-smart-text-field

Basic usage

<ngx-smart-text-field
  [plan]="plan"
  [expressions]="expressions"
  [generatingResponse]="generatingResponse"
  (generateResponse)="onGenerate($event)"
  (expressionSelected)="onSelected($event)"
/>

import { NgxSmartTextField } from '@aquera/ngx-smart-text-field';

@Component({
  imports: [NgxSmartTextField],
  ...
})
export class MyComponent {
  plan = signal('');
  expressions = signal<DefaultExpression[]>([]);
  generatingResponse = signal(false);

  onGenerate(prompt: string) {
    this.generatingResponse.set(true);
    // call your AI backend, then set generatingResponse to false when done
  }

  onSelected(expression: DefaultExpression) {
    console.log('Selected:', expression);
  }
}

Inputs

All signal-typed inputs must be passed as Angular signal() instances (not plain values).

Required inputs have no meaningful default and must be provided for the component to work correctly. Optional inputs have sensible defaults and can be omitted.

| Input | Required | Type | Default | Description | |---|:---:|---|---|---| | expressions | ✅ | Signal<DefaultExpression[]> | [] | Saved expressions shown in the dropdown for filtering and selection. The component is a no-op without this. | | generatingResponse | ✅ | Signal<boolean> | false | Controls the loading state. Set to true when your AI call starts and back to false when it finishes or errors. | | plan | — | Signal<string> | '' | Current prompt / expression text. Bind this if you need two-way control of the field value. | | generatingPreview | — | Signal<boolean> | false | Set to true while a preview is being generated; triggers a preview refresh after completion. | | showPreview | — | Signal<boolean> | true | Whether to show the preview panel inside the dropdown. | | showCode | — | Signal<boolean> | true | Whether to show the generated code block inside the preview panel. | | generateOnBlur | — | Signal<boolean> | false | Automatically fires generateResponse when the user leaves the field without selecting an expression. | | placeholder | — | Signal<string> | 'Select, Describe, or Enter an expression...' | Placeholder text shown in the prompt field. | | maxRows | — | Signal<number> | 1 | Number of visible text rows when the field is idle. | | maxRowsVisibleOnFocus | — | Signal<number> | 3 | Number of visible text rows when the field is focused. | | showSmartSuggestions | — | Signal<boolean> | false | Enable AI-powered smart suggestions in the dropdown. Requires smartSuggestionsRef and a fetchSmartSuggestions handler. | | smartSuggestionsRef | — | ResourceRef<SmartSuggestions> \| undefined | undefined | Angular resource ref used to feed smart suggestion results into the dropdown. Only needed when showSmartSuggestions is true. |

Outputs

Required outputs must be handled for the component to function correctly. Optional outputs can be ignored if you don't need that feature.

| Output | Required | Payload | Description | |---|:---:|---|---| | generateResponse | ✅ | string | Emitted when the user submits the prompt (Enter key or send button). Your handler must call your AI backend and toggle generatingResponse. | | expressionSelected | ✅ | DefaultExpression | Emitted when the user picks an expression from the dropdown. Your handler should apply the selection to your data model. | | stopGeneratingResponse | — | void | Emitted when the user presses Escape while a response is generating. Handle this to cancel your in-flight AI request. | | generatePreview | — | { previewData: PreviewData; prompt: string; dropdownDetails: DropdownDetails } | Emitted when a preview generation is requested from within the dropdown. Only needed when showPreview is true. | | fetchSmartSuggestions | — | string | Emitted whenever the prompt changes and showSmartSuggestions is true. Use this to (re-)fetch suggestions and update smartSuggestionsRef. |

Types

interface DefaultExpression {
  id: string;
  plan: string;               // the expression text
  previewData: PreviewData;
  prompt?: string;
  default?: boolean;
  aiGenerated?: boolean;
  expandPreview?: boolean;
}

interface PreviewData {
  executionResult: string[];
  generatedCode: string;
  requiredInputs: RequiredInput[];
  responseFormat: any;
  success: boolean;
  error?: string;
}

interface RequiredInput {
  name: string;
  label: string;
  description: string;
  type: string;
  required: boolean;
  placeholder: string;
  exampleValue: string;
  usage: string;
}

interface SmartSuggestions {
  suggestions: string[];
}

Dropdown positioning

The dropdown and loader panels are positioned automatically relative to the prompt field and scroll with it. When the field is near the bottom of the viewport, the panels open upward; otherwise they open downward. If neither direction has enough room, the panel constrains its height and becomes scrollable.

Building from source

ng build ngx-smart-text-field

Build output is placed in dist/ngx-smart-text-field.

Running tests

ng test ngx-smart-text-field

Publishing

cd dist/ngx-smart-text-field
npm publish