@grackle-ai/web-components 0.107.2

package/src/components/editable/EditableTextField.tsx

@@ -0,0 +1,153 @@
+import { useEffect, useRef, type JSX, type ReactNode } from "react";
+import { useEditableField } from "./useEditableField.js";
+import styles from "./EditableField.module.scss";
+
+/** Props for EditableTextField. */
+export interface EditableTextFieldProps {
+  /** Current persisted value. */
+  value: string;
+  /** Called when the user saves. Required in edit mode. */
+  onSave: (value: string) => void;
+  /** Optional validation — return an error string, or undefined if valid. */
+  validate?: (value: string) => string | undefined;
+  /** "edit" (default) for click-to-edit, "create" for always-editable. */
+  mode?: "edit" | "create";
+  /** Unique field identifier for coordination. */
+  fieldId?: string;
+  /** Which field is currently being edited (parent coordination). */
+  activeFieldId?: string | null; // eslint-disable-line @rushstack/no-new-null
+  /** Callback to tell the parent which field is active. */
+  onActivate?: (fieldId: string | null) => void; // eslint-disable-line @rushstack/no-new-null
+  /** Called on every keystroke in create mode. */
+  onChange?: (value: string) => void;
+  /** Custom display renderer (e.g., link for repoUrl). */
+  renderDisplay?: (value: string) => ReactNode | undefined;
+  /** Placeholder text shown when empty. */
+  placeholder?: string;
+  /** Max character length for the input. */
+  maxLength?: number;
+  /** Accessible label for the input. */
+  ariaLabel?: string;
+  /** Base test ID — gets `-input` / `-button` suffixes appended. */
+  "data-testid"?: string;
+}
+
+/** Reusable click-to-edit text input field. */
+export function EditableTextField(props: EditableTextFieldProps): JSX.Element {
+  const {
+    value,
+    onSave,
+    validate,
+    mode = "edit",
+    fieldId = "text",
+    activeFieldId,
+    onActivate,
+    onChange,
+    renderDisplay,
+    placeholder,
+    maxLength,
+    ariaLabel,
+    "data-testid": testId,
+  } = props;
+
+  const inputRef = useRef<HTMLInputElement>(null);
+
+  const field = useEditableField({
+    value,
+    onSave,
+    validate,
+    fieldId,
+    activeFieldId,
+    onActivate,
+    enterToSave: true,
+    trimOnSave: true,
+  });
+
+  // Auto-focus when entering edit mode
+  useEffect(() => {
+    if (field.isEditing) {
+      const timer = window.setTimeout(() => {
+        inputRef.current?.focus();
+      }, 0);
+      return () => window.clearTimeout(timer);
+    }
+  }, [field.isEditing]);
+
+  // Create mode: always show input, no blur-to-save
+  if (mode === "create") {
+    const handleChange = (e: React.ChangeEvent<HTMLInputElement>): void => {
+      onChange?.(e.target.value);
+    };
+
+    const validationError = validate?.(value);
+
+    return (
+      <div className={styles.editFieldWrapper}>
+        <input
+          className={`${styles.editInput} ${validationError ? styles.editInputInvalid : ""}`}
+          value={value}
+          onChange={handleChange}
+          maxLength={maxLength}
+          placeholder={placeholder}
+          aria-label={ariaLabel}
+          data-testid={testId ? `${testId}-input` : undefined}
+        />
+        {validationError && (
+          <span className={styles.editError} data-testid="edit-error">{validationError}</span>
+        )}
+      </div>
+    );
+  }
+
+  // Edit mode: toggle between display and input
+  if (field.isEditing) {
+    return (
+      <div className={styles.editFieldWrapper}>
+        <input
+          ref={inputRef}
+          className={`${styles.editInput} ${field.error ? styles.editInputInvalid : ""}`}
+          value={field.draft}
+          onChange={(e) => field.setDraft(e.target.value)}
+          onBlur={field.handleBlur}
+          onKeyDown={field.handleKeyDown}
+          maxLength={maxLength}
+          placeholder={placeholder}
+          aria-label={ariaLabel}
+          data-testid={testId ? `${testId}-input` : undefined}
+        />
+        {field.isDirty && <span className={styles.unsavedDot} title="Unsaved changes" />}
+        {field.error && (
+          <span className={styles.editError} data-testid="edit-error">{field.error}</span>
+        )}
+        <span className={styles.editHint}>Enter to save &middot; Esc to cancel</span>
+      </div>
+    );
+  }
+
+  // Display mode — uses <span role="button"> to avoid nested interactive elements
+  // when renderDisplay returns links or other interactive content
+  const displayContent = renderDisplay?.(value);
+  return (
+    <span
+      role="button"
+      tabIndex={0}
+      className={styles.metaValueClickable}
+      onClick={() => field.startEdit()}
+      onKeyDown={(e) => { if (e.key === "Enter" || e.key === " ") { e.preventDefault(); field.startEdit(); } }}
+      title="Click to edit"
+      aria-label={ariaLabel}
+      data-testid={testId ? `${testId}-button` : undefined}
+    >
+      {displayContent !== undefined ? displayContent : (
+        value ? (
+          <span>{value}</span>
+        ) : (
+          <span className={styles.metaPlaceholder}>{placeholder || "None"}</span>
+        )
+      )}
+      <span className={styles.editButton} aria-hidden="true">
+        &#x270F;&#xFE0F;
+      </span>
+    </span>
+  );
+}

package/src/components/editable/EnvironmentSelect.module.scss

@@ -0,0 +1,17 @@
+.envRow {
+  display: flex;
+  align-items: center;
+  gap: var(--space-sm);
+}
+
+.envDot {
+  width: 8px;
+  height: 8px;
+  border-radius: 50%;
+  flex-shrink: 0;
+}
+
+.envDotGreen  { background: var(--accent-green); }
+.envDotYellow { background: var(--accent-yellow); }
+.envDotRed    { background: var(--accent-red); }
+.envDotGray   { background: var(--text-disabled); }

package/src/components/editable/EnvironmentSelect.stories.tsx

@@ -0,0 +1,61 @@
+import type { Meta, StoryObj } from "@storybook/react";
+import { expect, fn } from "@storybook/test";
+import { EnvironmentSelect } from "./EnvironmentSelect.js";
+import type { Environment } from "../../hooks/types.js";
+import { makeEnvironment } from "../../test-utils/storybook-helpers.js";
+
+const localEnv: Environment = makeEnvironment({
+  id: "env-local",
+  displayName: "Local Machine",
+  adapterType: "local",
+  status: "connected",
+});
+
+const sshEnv: Environment = makeEnvironment({
+  id: "env-ssh",
+  displayName: "Dev Server (SSH)",
+  adapterType: "ssh",
+  status: "ready",
+});
+
+const failedEnv: Environment = makeEnvironment({
+  id: "env-fail",
+  displayName: "Broken Host",
+  adapterType: "ssh",
+  status: "error",
+});
+
+const meta: Meta<typeof EnvironmentSelect> = {
+  component: EnvironmentSelect,
+  title: "App/Editable/EnvironmentSelect",
+  args: {
+    onSave: fn(),
+    environments: [localEnv, sshEnv],
+    value: localEnv.id,
+    "data-testid": "env-select",
+  },
+};
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+/** Default state showing the selected environment with status dot. */
+export const Default: Story = {
+  play: async ({ canvas }) => {
+    const button = canvas.getByTestId("env-select-button");
+    await expect(button).toBeInTheDocument();
+    await expect(button).toHaveTextContent("Local Machine");
+  },
+};
+
+/** Multiple environments including various statuses. */
+export const WithMultipleEnvironments: Story = {
+  args: {
+    environments: [localEnv, sshEnv, failedEnv],
+    value: sshEnv.id,
+  },
+  play: async ({ canvas }) => {
+    const button = canvas.getByTestId("env-select-button");
+    await expect(button).toBeInTheDocument();
+    await expect(button).toHaveTextContent("Dev Server (SSH)");
+  },
+};

package/src/components/editable/EnvironmentSelect.tsx

@@ -0,0 +1,87 @@
+import { type JSX, type ReactNode } from "react";
+import { EditableSelect } from "./EditableSelect.js";
+import type { Environment } from "../../hooks/types.js";
+import styles from "./EnvironmentSelect.module.scss";
+
+/** Props for EnvironmentSelect. */
+export interface EnvironmentSelectProps {
+  /** Currently selected environment ID. */
+  value: string;
+  /** Called when the user selects a new environment. */
+  onSave: (envId: string) => void;
+  /** Available environments. */
+  environments: Environment[];
+  /** Whether to include a "None" option. */
+  allowNone?: boolean;
+  /** Unique field identifier for coordination with other editable fields. */
+  fieldId?: string;
+  /** Which field is currently being edited (parent coordination). */
+  activeFieldId?: string | null; // eslint-disable-line @rushstack/no-new-null
+  /** Callback to tell the parent which field is active. */
+  onActivate?: (fieldId: string | null) => void; // eslint-disable-line @rushstack/no-new-null
+  /** Placeholder text when no value is selected. */
+  placeholder?: string;
+  /** Accessible label. */
+  ariaLabel?: string;
+  /** Base test ID. */
+  "data-testid"?: string;
+}
+
+/** Map environment status to a CSS class for the status dot. */
+function envStatusClass(status: string): string {
+  const s = status.toLowerCase();
+  if (s === "ready" || s === "running" || s === "available" || s === "connected") return styles.envDotGreen;
+  if (s === "provisioning" || s === "starting" || s === "pending" || s === "connecting") return styles.envDotYellow;
+  if (s === "error" || s === "failed" || s === "disconnected") return styles.envDotRed;
+  return styles.envDotGray;
+}
+
+/** Reusable environment selector with status dot display. Click-to-edit EditableSelect. */
+export function EnvironmentSelect(props: EnvironmentSelectProps): JSX.Element {
+  const {
+    value,
+    onSave,
+    environments,
+    allowNone = false,
+    fieldId = "environment",
+    activeFieldId,
+    onActivate,
+    placeholder = "No environment",
+    ariaLabel = "Environment",
+    "data-testid": testId,
+  } = props;
+
+  const selectedEnv = environments.find((e) => e.id === value);
+
+  const options = [
+    ...(allowNone ? [{ value: "", label: "None" }] : []),
+    ...environments.map((env) => ({ value: env.id, label: env.displayName })),
+  ];
+
+  const renderDisplay = (): ReactNode | undefined => {
+    if (selectedEnv) {
+      return (
+        <span className={styles.envRow}>
+          <span className={`${styles.envDot} ${envStatusClass(selectedEnv.status)}`} />
+          {selectedEnv.displayName}
+        </span>
+      );
+    }
+    return undefined;
+  };
+
+  return (
+    <EditableSelect
+      value={value}
+      onSave={onSave}
+      options={options}
+      fieldId={fieldId}
+      activeFieldId={activeFieldId}
+      onActivate={onActivate}
+      renderDisplay={renderDisplay}
+      placeholder={placeholder}
+      ariaLabel={ariaLabel}
+      data-testid={testId}
+    />
+  );
+}

package/src/components/editable/index.ts

@@ -0,0 +1,13 @@
+export { EditableTextField } from "./EditableTextField.js";
+export { EditableTextArea } from "./EditableTextArea.js";
+export { EditableSelect } from "./EditableSelect.js";
+export { EditableCheckbox } from "./EditableCheckbox.js";
+export { EnvironmentSelect } from "./EnvironmentSelect.js";
+export { useEditableField } from "./useEditableField.js";
+
+export type { EditableTextFieldProps } from "./EditableTextField.js";
+export type { EditableTextAreaProps } from "./EditableTextArea.js";
+export type { EditableSelectProps, SelectOption } from "./EditableSelect.js";
+export type { EditableCheckboxProps } from "./EditableCheckbox.js";
+export type { EnvironmentSelectProps } from "./EnvironmentSelect.js";
+export type { UseEditableFieldOptions, UseEditableFieldReturn } from "./useEditableField.js";

package/src/components/editable/useEditableField.test.tsx

@@ -0,0 +1,233 @@
+// @vitest-environment jsdom
+import { describe, it, expect, vi } from "vitest";
+import { renderHook, act } from "@testing-library/react";
+import { useEditableField } from "./useEditableField.js";
+
+function makeOptions(overrides: Partial<Parameters<typeof useEditableField>[0]> = {}): Parameters<typeof useEditableField>[0] {
+  return {
+    value: "hello",
+    onSave: vi.fn(),
+    fieldId: "name",
+    activeFieldId: null as string | null,
+    onActivate: vi.fn(),
+    ...overrides,
+  };
+}
+
+describe("useEditableField", () => {
+  // ── Lifecycle: start / cancel / save ──────────────────────────
+  it("starts in non-editing state", () => {
+    const opts = makeOptions();
+    const { result } = renderHook(() => useEditableField(opts));
+    expect(result.current.isEditing).toBe(false);
+    expect(result.current.draft).toBe("");
+    expect(result.current.error).toBe("");
+    expect(result.current.isDirty).toBe(false);
+  });
+
+  it("startEdit activates the field and seeds the draft", () => {
+    const opts = makeOptions();
+    const { result } = renderHook(() => useEditableField(opts));
+
+    act(() => result.current.startEdit());
+    expect(opts.onActivate).toHaveBeenCalledWith("name");
+  });
+
+  it("cancelEdit deactivates and clears state", () => {
+    const opts = makeOptions({ activeFieldId: "name" });
+    const { result } = renderHook(() => useEditableField(opts));
+
+    // Seed draft
+    act(() => result.current.startEdit());
+    act(() => result.current.cancelEdit());
+
+    expect(opts.onActivate).toHaveBeenLastCalledWith(null);
+  });
+
+  it("save calls onSave with trimmed value and exits", () => {
+    const onSave = vi.fn();
+    const opts = makeOptions({ value: "old", activeFieldId: "name", onSave });
+    const { result } = renderHook(() => useEditableField(opts));
+
+    act(() => result.current.startEdit());
+    act(() => result.current.setDraft("  new  "));
+    act(() => result.current.save());
+
+    expect(onSave).toHaveBeenCalledWith("new");
+    expect(opts.onActivate).toHaveBeenLastCalledWith(null);
+  });
+
+  it("save without trimOnSave preserves whitespace", () => {
+    const onSave = vi.fn();
+    const opts = makeOptions({ value: "old", activeFieldId: "name", onSave, trimOnSave: false });
+    const { result } = renderHook(() => useEditableField(opts));
+
+    act(() => result.current.startEdit());
+    act(() => result.current.setDraft("  new  "));
+    act(() => result.current.save());
+
+    expect(onSave).toHaveBeenCalledWith("  new  ");
+  });
+
+  it("no-op save when value is unchanged", () => {
+    const onSave = vi.fn();
+    const opts = makeOptions({ value: "hello", activeFieldId: "name", onSave });
+    const { result } = renderHook(() => useEditableField(opts));
+
+    act(() => result.current.startEdit());
+    // Draft is seeded with "hello" by startEdit, don't change it
+    act(() => result.current.save());
+
+    expect(onSave).not.toHaveBeenCalled();
+    expect(opts.onActivate).toHaveBeenLastCalledWith(null); // Still exits edit mode
+  });
+
+  // ── Validation ────────────────────────────────────────────────
+  it("save with validation error shows error and does not call onSave", () => {
+    const onSave = vi.fn();
+    const validate = vi.fn().mockReturnValue("Required");
+    const opts = makeOptions({ value: "old", activeFieldId: "name", onSave, validate });
+    const { result } = renderHook(() => useEditableField(opts));
+
+    act(() => result.current.startEdit());
+    act(() => result.current.setDraft(""));
+    act(() => result.current.save());
+
+    expect(result.current.error).toBe("Required");
+    expect(onSave).not.toHaveBeenCalled();
+  });
+
+  it("setDraft clears the error", () => {
+    const validate = vi.fn().mockReturnValue("Required");
+    const opts = makeOptions({ value: "old", activeFieldId: "name", validate });
+    const { result } = renderHook(() => useEditableField(opts));
+
+    act(() => result.current.startEdit());
+    act(() => result.current.setDraft(""));
+    act(() => result.current.save());
+    expect(result.current.error).toBe("Required");
+
+    act(() => result.current.setDraft("fixed"));
+    expect(result.current.error).toBe("");
+  });
+
+  // ── isDirty ───────────────────────────────────────────────────
+  it("isDirty is true when draft differs from value", () => {
+    const opts = makeOptions({ value: "hello", activeFieldId: "name" });
+    const { result } = renderHook(() => useEditableField(opts));
+
+    act(() => result.current.startEdit());
+    act(() => result.current.setDraft("changed"));
+    expect(result.current.isDirty).toBe(true);
+  });
+
+  it("isDirty is false when draft matches value (after trim)", () => {
+    const opts = makeOptions({ value: "hello", activeFieldId: "name" });
+    const { result } = renderHook(() => useEditableField(opts));
+
+    act(() => result.current.startEdit());
+    act(() => result.current.setDraft("  hello  "));
+    expect(result.current.isDirty).toBe(false);
+  });
+
+  it("isDirty is false when not editing", () => {
+    const opts = makeOptions({ value: "hello", activeFieldId: null });
+    const { result } = renderHook(() => useEditableField(opts));
+    expect(result.current.isDirty).toBe(false);
+  });
+
+  // ── Keyboard handling ─────────────────────────────────────────
+  it("Escape cancels edit", () => {
+    const opts = makeOptions({ activeFieldId: "name" });
+    const { result } = renderHook(() => useEditableField(opts));
+
+    act(() => result.current.startEdit());
+    act(() => {
+      result.current.handleKeyDown({ key: "Escape" } as React.KeyboardEvent);
+    });
+
+    expect(opts.onActivate).toHaveBeenLastCalledWith(null);
+  });
+
+  it("Enter saves when enterToSave is true", () => {
+    const onSave = vi.fn();
+    const opts = makeOptions({ value: "old", activeFieldId: "name", onSave, enterToSave: true });
+    const { result } = renderHook(() => useEditableField(opts));
+
+    act(() => result.current.startEdit());
+    act(() => result.current.setDraft("new"));
+    act(() => {
+      result.current.handleKeyDown({ key: "Enter" } as React.KeyboardEvent);
+    });
+
+    expect(onSave).toHaveBeenCalledWith("new");
+  });
+
+  it("Enter does NOT save when enterToSave is false", () => {
+    const onSave = vi.fn();
+    const opts = makeOptions({ value: "old", activeFieldId: "name", onSave, enterToSave: false });
+    const { result } = renderHook(() => useEditableField(opts));
+
+    act(() => result.current.startEdit());
+    act(() => result.current.setDraft("new"));
+    act(() => {
+      result.current.handleKeyDown({ key: "Enter" } as React.KeyboardEvent);
+    });
+
+    expect(onSave).not.toHaveBeenCalled();
+  });
+
+  // ── Blur guard ────────────────────────────────────────────────
+  it("ignoreInitialBlurRef prevents first blur from saving", () => {
+    const onSave = vi.fn();
+    const opts = makeOptions({ value: "old", activeFieldId: "name", onSave });
+    const { result } = renderHook(() => useEditableField(opts));
+
+    act(() => result.current.startEdit());
+    expect(result.current.ignoreInitialBlurRef.current).toBe(true);
+
+    // Simulate first blur — should be ignored
+    act(() => {
+      result.current.handleBlur({ relatedTarget: null } as unknown as React.FocusEvent);
+    });
+
+    expect(onSave).not.toHaveBeenCalled();
+    expect(result.current.ignoreInitialBlurRef.current).toBe(false);
+  });
+
+  it("blur with data-edit-action matching fieldId is ignored", () => {
+    const onSave = vi.fn();
+    const opts = makeOptions({ value: "old", activeFieldId: "name", onSave });
+    const { result } = renderHook(() => useEditableField(opts));
+
+    act(() => result.current.startEdit());
+    // Clear the initial blur guard
+    result.current.ignoreInitialBlurRef.current = false;
+
+    // Simulate blur to a related element with matching data-edit-action
+    const relatedTarget = document.createElement("button");
+    relatedTarget.dataset.editAction = "name";
+
+    act(() => {
+      result.current.handleBlur({ relatedTarget } as unknown as React.FocusEvent);
+    });
+
+    expect(onSave).not.toHaveBeenCalled();
+  });
+
+  it("blur to unrelated element triggers save", () => {
+    const onSave = vi.fn();
+    const opts = makeOptions({ value: "old", activeFieldId: "name", onSave });
+    const { result } = renderHook(() => useEditableField(opts));
+
+    act(() => result.current.startEdit());
+    result.current.ignoreInitialBlurRef.current = false;
+    act(() => result.current.setDraft("new"));
+
+    act(() => {
+      result.current.handleBlur({ relatedTarget: null } as unknown as React.FocusEvent);
+    });
+
+    expect(onSave).toHaveBeenCalledWith("new");
+  });
+});