# API of `@koobiq/components/inline-edit`

Documented on [Inline edit](https://koobiq.io/en/components/inline-edit.md). NgModule: `KbqInlineEditModule`.

## Components

### KbqInlineEdit (component)

Customizable component that enables edit-in-place logic for specified control and it's view.
This component is projecting edit/view mode templates and adds keyboard/pointer handlers.
Edit mode opens in a positioned overlay that matches the view mode width or can be customized.

```ts
@Component({ selector: 'kbq-inline-edit', exportAs: 'kbqInlineEdit' })
class KbqInlineEdit implements KbqConnectedOverlayOriginProvider, KbqInlineEditSaveRecovery {
    readonly showActions = input<boolean>(false);
    readonly showTooltipOnError = input<boolean>(true);
    readonly validationTooltip = input<string | TemplateRef<unknown>>();
    readonly disabled = input<boolean>(false);
    readonly editModeWidth = input<number | undefined>();
    readonly tooltipPlacement = input<PopUpPlacements>();
    readonly overlayPanelClass = input<string | string[]>('');
    readonly getValueHandler = input<() => unknown>();
    readonly setValueHandler = input<(value: unknown) => void>();
    readonly ariaLabel = input<string | null>(null, {
        alias: 'aria-label'
    });
    readonly compareWith = input<((a: any, b: any) => boolean) | null>(
        (a, b) => a === b
    );
    readonly saveHandler = input<KbqInlineEditSaveHandler>();
    readonly saveErrorHandler = input<KbqInlineEditSaveErrorHandler | null>(
        inject(KBQ_INLINE_EDIT_SAVE_ERROR_HANDLER, { optional: true })
    );
    readonly canSaveOnEnter = input<(event: KeyboardEvent) => boolean>(
        (event: KeyboardEvent): boolean => {
            // A control that runs its own action on Enter would otherwise fire it and save at the same time.
            if (isElement(event.target) && event.target.closest(ENTER_ACTIVATED_SELECTORS)) return false;

            return hasModifierKey(event, 'ctrlKey', 'metaKey') || !(event.target instanceof HTMLTextAreaElement);
        }
    );
    readonly interactiveSelectors = input<string[]>(['a', 'kbq-tag']);
    readonly mode = model<KbqInlineEditMode>('view');
    readonly saved = output<void>();
    readonly canceled = output<void>();
    readonly saveError = output<KbqInlineEditSaveErrorContext>();
    readonly saveStatus: Signal<KbqInlineEditSaveStatus>;
    toggleMode(): void;
    commit(): void;
    retrySave(): void;
    rollback(): void;
}
```

- `[showActions]`: `boolean` — Whether to show save/cancel action buttons in edit mode. Defaults to `false`.
- `[showTooltipOnError]`: `boolean` — Whether to automatically show validation error tooltips on save attempts.
  Has no effect unless `validationTooltip` is set. Defaults to `true`.
- `[validationTooltip]`: `string | TemplateRef<unknown>` — Custom validation tooltip message.
- `[disabled]`: `boolean` — Disables the component, preventing interaction and mode switching. Only allows menu dropdown.
  Defaults to `false`.
- `[editModeWidth]`: `number | undefined` — Custom width in pixels for the edit mode overlay. Auto-calculated if not set.
- `[tooltipPlacement]`: `PopUpPlacements` — User-defined tooltip placement
- `[overlayPanelClass]`: `string | string[]` — Classes to be passed to the inline edit panel.
- `[getValueHandler]`: `() => unknown` — Handler function to retrieve the current value
- `[setValueHandler]`: `(value: unknown) => void` — Handler function to update the value
- `[aria-label]`: `string | null` — Accessible name of the control that opens the editor. Defaults to the localized "Edit"; set a
  field-specific name where the projected value alone doesn't say what is being edited.
- `[compareWith]`: `((a: any, b: any) => boolean) | null` — Whether the value still equals the one the editor opened with, in which case `saveHandler` is not called.
  The default suits text and numbers; bind your own for arrays and objects, or `null` to send every time.
  A failed save is always retried, however the values compare.
- `[saveHandler]`: `KbqInlineEditSaveHandler` — Saves a valid value in the background: edit mode closes right away and view mode reports how the request
  went. Without it, a valid value is saved immediately.
- `[saveErrorHandler]`: `KbqInlineEditSaveErrorHandler | null` — Reaction to a failed save for this inline edit alone. Defaults to `KBQ_INLINE_EDIT_SAVE_ERROR_HANDLER`;
  bind `null` to leave it without one.
- `[canSaveOnEnter]`: `(event: KeyboardEvent) => boolean` — Customizable function that checks if saving on enter available.
- `[interactiveSelectors]`: `string[]` — CSS selectors for elements in view mode that should handle clicks instead of opening edit mode.
  Override to replace or extend the default list.

  ```html
  <kbq-inline-edit [interactiveSelectors]="['a', 'kbq-tag', 'button']">
  ```
- `[(mode)]`: `KbqInlineEditMode` — Current mode. Two-way bindable: `[(mode)]` opens and closes the editor programmatically, and
  `(modeChange)` alone reports every transition.
- `[localeOverrides]`: `KbqPartialLocaleData | undefined` — Localized strings for this element and its subtree, keyed by locale section. Every key is optional at
  every depth.
- `(saved)`: `void` — Emitted when the inline edit is saved successfully.
- `(canceled)`: `void` — Emitted when the inline edit is canceled and changes are discarded.
- `(saveError)`: `KbqInlineEditSaveErrorContext` — Emitted when a `saveHandler` request fails. Silent once the row is destroyed; `saveErrorHandler` is not.
- `saveStatus`: `Signal<KbqInlineEditSaveStatus>` — State of the background save started by `saveHandler`.
- `toggleMode()`: `void` — Manually switch mode. Does nothing while a `saveHandler` request is in flight.
- `commit()`: `void` — Saves the current value, running the same validation as a normal save.
- `retrySave()`: `void` — Repeats the request for a value the server rejected. Does nothing unless the last save failed.
- `rollback()`: `void` — Discards the value the server rejected, restoring the last saved one and closing the editor.

## Directives

### KbqInlineEditMenu (directive)

This directive enhances element acting as dropdown trigger,
visually indicating the active state with the `kbq-active` class.
Also, it prevents click/keydown events from being propagated to disable mode toggling of parent component.

```ts
@Directive({ selector: '[kbqInlineEditMenu]', exportAs: 'kbqInlineEditMenu' })
class KbqInlineEditMenu {}
```

### KbqInlineEditPlaceholder (directive)

Directive for easy using styles of inline edit placeholder publicly.

```ts
@Directive({
    selector: '[kbqInlineEditPlaceholder]',
    exportAs: 'kbqInlineEditPlaceholder'
})
class KbqInlineEditPlaceholder {}
```

## Types

### KbqInlineEditMode (type)

```ts
type KbqInlineEditMode = 'view' | 'edit';
```

### KbqInlineEditSaveErrorContext (interface)

Failed save, reported through `saveError` and `KBQ_INLINE_EDIT_SAVE_ERROR_HANDLER`.

```ts
interface KbqInlineEditSaveErrorContext<E = any> {
    readonly error: E;
    readonly inlineEdit: KbqInlineEditSaveRecovery;
}
```

- `error`: `E` — Parameterise the interface to type this.
- `inlineEdit`: `KbqInlineEditSaveRecovery` — Inline edit whose save failed.

### KbqInlineEditSaveErrorHandler (type)

Reaction to a failed save, e.g. opening a toast.

```ts
type KbqInlineEditSaveErrorHandler = (context: KbqInlineEditSaveErrorContext) => void;
```

### KbqInlineEditSaveHandler (type)

Saves the edited value, e.g. sends it to a server. Only the first emission counts, and the observable must emit
or complete: destroying the row does not cancel it, so one that never settles keeps the row in memory.

Called without a receiver, so bind an arrow function rather than a method that relies on `this`.

```ts
type KbqInlineEditSaveHandler = () => Observable<unknown>;
```

### KbqInlineEditSaveRecovery (interface)

Recovery a failed-save notification can offer: retry, edit again, discard the unsaved value.

```ts
interface KbqInlineEditSaveRecovery {
    retrySave(): void;
    toggleMode(): void;
    rollback(): void;
}
```

### KbqInlineEditSaveStatus (type)

State of the save request started by `saveHandler`. `progress` is `pending` past the indicator delay.

```ts
type KbqInlineEditSaveStatus = 'idle' | 'pending' | 'progress' | 'error';
```

## Constants

### KBQ_INLINE_EDIT_SAVE_ERROR_HANDLER (const)

Reports every failed save the same way across the application. Declare it in the root injector.

```ts
const KBQ_INLINE_EDIT_SAVE_ERROR_HANDLER: InjectionToken<KbqInlineEditSaveErrorHandler>;
```

### kbqInlineEditSaveProgressDelay (const)

Delay before the save progress state appears, so a fast response causes no flicker.

```ts
const kbqInlineEditSaveProgressDelay: number;
```

### kbqInlineEditSaveProgressMinimumDuration (const)

Minimum time the save progress state stays once it has appeared.

```ts
const kbqInlineEditSaveProgressMinimumDuration: number;
```
