@grackle-ai/web-components 0.107.2

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

@@ -0,0 +1,135 @@
+@use '../../styles/mixins' as *;
+
+// Edit wrapper that supports wrapping hint/error below the input
+.editFieldWrapper {
+  display: flex;
+  flex-wrap: wrap;
+  flex: 1;
+  min-width: 0;
+  align-items: center;
+  gap: var(--space-xs);
+}
+
+.editInput {
+  @include input-field;
+  font-size: var(--font-size-sm);
+  padding: 2px var(--space-xs);
+  flex: 1;
+  min-width: 0;
+}
+
+.editTextarea {
+  @include input-field;
+  font-size: var(--font-size-sm);
+  padding: var(--space-xs) var(--space-sm);
+  flex: 1;
+  min-width: 0;
+  resize: vertical;
+  min-height: 60px;
+  font-family: inherit;
+  line-height: 1.5;
+}
+
+.editSelect {
+  @include input-field;
+  font-size: var(--font-size-sm);
+  padding: 2px var(--space-xs);
+  flex: 1;
+  min-width: 0;
+  cursor: pointer;
+}
+
+// Validation error message
+.editError {
+  font-size: 10px;
+  color: var(--accent-red);
+  margin-top: 2px;
+  flex-basis: 100%;
+}
+
+// Red border for invalid inputs
+.editInputInvalid {
+  border-color: var(--accent-red) !important;
+  box-shadow: 0 0 0 1px var(--accent-red-dim);
+}
+
+// Keyboard hint shown below editing inputs
+.editHint {
+  font-size: 10px;
+  color: var(--text-tertiary);
+  opacity: 0.7;
+  margin-top: 2px;
+  font-family: var(--font-mono);
+  flex-basis: 100%;
+}
+
+// Unsaved dot indicator
+.unsavedDot {
+  width: 6px;
+  height: 6px;
+  border-radius: 50%;
+  background: var(--accent-yellow);
+  flex-shrink: 0;
+}
+
+// Click-to-edit wrapper — makes the whole value area clickable
+.metaValueClickable {
+  display: inline-flex;
+  align-items: center;
+  gap: var(--space-xs);
+  cursor: pointer;
+  border-radius: var(--radius-sm);
+  padding: 1px var(--space-xs);
+  margin: -1px calc(-1 * var(--space-xs));
+  transition: background var(--transition-fast);
+  background: none;
+  border: none;
+  text-align: left;
+  color: inherit;
+  font: inherit;
+
+  &:hover {
+    background: var(--bg-overlay);
+  }
+}
+
+// Pencil icon with opacity transition
+.editButton {
+  background: none;
+  border: none;
+  color: var(--text-tertiary);
+  cursor: pointer;
+  padding: 2px;
+  font-size: var(--font-size-sm);
+  opacity: 0.4;
+  transition: opacity var(--transition-fast);
+  flex-shrink: 0;
+
+  &:hover {
+    opacity: 1;
+    color: var(--accent-green);
+  }
+}
+
+// Italic gray placeholder for empty values
+.metaPlaceholder {
+  color: var(--text-tertiary);
+  font-style: italic;
+}
+
+// Checkbox + label styling
+.worktreeToggle {
+  display: flex;
+  align-items: center;
+  gap: var(--space-sm);
+  font-size: var(--font-size-sm);
+  color: var(--text-secondary);
+  cursor: pointer;
+
+  input[type="checkbox"] {
+    accent-color: var(--accent-green);
+    width: 16px;
+    height: 16px;
+    cursor: pointer;
+  }
+}

package/src/components/editable/EditableSelect.tsx

@@ -0,0 +1,164 @@
+import { useCallback, useEffect, useRef, type JSX, type ReactNode } from "react";
+import { useEditableField } from "./useEditableField.js";
+import styles from "./EditableField.module.scss";
+
+/** A single option in the select dropdown. */
+export interface SelectOption {
+  value: string;
+  label: string;
+}
+
+/** Props for EditableSelect. */
+export interface EditableSelectProps {
+  /** Current persisted value. */
+  value: string;
+  /** Called when the user selects a new value. Required in edit mode. */
+  onSave: (value: string) => void;
+  /** "edit" (default) for click-to-edit, "create" for always-visible. */
+  mode?: "edit" | "create";
+  /** Available options for the dropdown. */
+  options: SelectOption[];
+  /** 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 change in create mode. */
+  onChange?: (value: string) => void;
+  /** Custom display renderer for the selected value. */
+  renderDisplay?: (value: string) => ReactNode | undefined;
+  /** Placeholder text when no value is selected. */
+  placeholder?: string;
+  /** Accessible label for the select. */
+  ariaLabel?: string;
+  /** Base test ID — gets `-select` / `-button` suffixes appended. */
+  "data-testid"?: string;
+}
+
+/** Reusable click-to-edit select dropdown. */
+export function EditableSelect(props: EditableSelectProps): JSX.Element {
+  const {
+    value,
+    onSave,
+    mode = "edit",
+    options,
+    fieldId = "select",
+    activeFieldId,
+    onActivate,
+    onChange,
+    renderDisplay,
+    placeholder,
+    ariaLabel,
+    "data-testid": testId,
+  } = props;
+
+  const selectRef = useRef<HTMLSelectElement>(null);
+
+  const field = useEditableField({
+    value,
+    onSave,
+    fieldId,
+    activeFieldId,
+    onActivate,
+    enterToSave: false,
+    trimOnSave: false,
+  });
+
+  // Auto-focus when entering edit mode
+  useEffect(() => {
+    if (field.isEditing) {
+      const timer = window.setTimeout(() => {
+        selectRef.current?.focus();
+      }, 0);
+      return () => window.clearTimeout(timer);
+    }
+  }, [field.isEditing]);
+
+  /** Select saves immediately on change and exits edit mode. */
+  const handleSelectChange = useCallback((e: React.ChangeEvent<HTMLSelectElement>) => {
+    const newValue = e.target.value;
+    field.ignoreInitialBlurRef.current = false;
+    if (newValue !== value) {
+      onSave(newValue);
+    }
+    field.cancelEdit();
+  }, [value, onSave, field]);
+
+  /** Blur just cancels (no auto-save for selects). */
+  const handleSelectBlur = useCallback((event: React.FocusEvent) => {
+    if (field.ignoreInitialBlurRef.current) {
+      field.ignoreInitialBlurRef.current = false;
+      return;
+    }
+    if (
+      event.relatedTarget instanceof HTMLElement &&
+      event.relatedTarget.dataset.editAction === fieldId
+    ) {
+      return;
+    }
+    field.cancelEdit();
+  }, [fieldId, field]);
+
+  // Create mode: always show select
+  if (mode === "create") {
+    return (
+      <select
+        className={styles.editSelect}
+        value={value}
+        onChange={(e) => onChange?.(e.target.value)}
+        aria-label={ariaLabel}
+        data-testid={testId ? `${testId}-select` : undefined}
+      >
+        {options.map((opt) => (
+          <option key={opt.value} value={opt.value}>{opt.label}</option>
+        ))}
+      </select>
+    );
+  }
+
+  // Edit mode: show select dropdown
+  if (field.isEditing) {
+    return (
+      <select
+        ref={selectRef}
+        className={styles.editSelect}
+        value={field.draft}
+        onChange={handleSelectChange}
+        onBlur={handleSelectBlur}
+        title={ariaLabel}
+        aria-label={ariaLabel}
+        data-testid={testId ? `${testId}-select` : undefined}
+      >
+        {options.map((opt) => (
+          <option key={opt.value} value={opt.value}>{opt.label}</option>
+        ))}
+      </select>
+    );
+  }
+
+  // Display mode
+  const displayContent = renderDisplay?.(value);
+  const selectedLabel = options.find((o) => o.value === value)?.label;
+  return (
+    <button
+      type="button"
+      className={styles.metaValueClickable}
+      onClick={() => field.startEdit()}
+      title="Click to change"
+      aria-label={ariaLabel}
+      data-testid={testId ? `${testId}-button` : undefined}
+    >
+      {displayContent !== undefined ? displayContent : (
+        selectedLabel ? (
+          <span>{selectedLabel}</span>
+        ) : (
+          <span className={styles.metaPlaceholder}>{placeholder || "None"}</span>
+        )
+      )}
+      <span className={styles.editButton} aria-hidden="true">
+        &#x270F;&#xFE0F;
+      </span>
+    </button>
+  );
+}

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

@@ -0,0 +1,50 @@
+import type { Meta, StoryObj } from "@storybook/react";
+import { expect, fn } from "@storybook/test";
+import { EditableTextArea } from "./EditableTextArea.js";
+
+const meta: Meta<typeof EditableTextArea> = {
+  title: "Primitives/Editable/EditableTextArea",
+  tags: ["autodocs"],
+  component: EditableTextArea,
+  args: {
+    value: "Multi-line\ntext content",
+    onSave: fn(),
+    "data-testid": "test-area",
+  },
+};
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+/** Display mode shows the value with an edit button. */
+export const DisplayMode: Story = {
+  play: async ({ canvas }) => {
+    const button = canvas.getByTestId("test-area-button");
+    await expect(button).toBeInTheDocument();
+    await expect(button).toHaveAttribute("role", "button");
+  },
+};
+
+/** Display button is keyboard-accessible (tabIndex, role, focusable). */
+export const KeyboardAccessible: Story = {
+  play: async ({ canvas }) => {
+    const button = canvas.getByTestId("test-area-button");
+    await expect(button).toHaveAttribute("role", "button");
+    await expect(button).toHaveAttribute("tabindex", "0");
+
+    button.focus();
+    await expect(button).toHaveFocus();
+  },
+};
+
+/** Create mode renders as an always-visible textarea. */
+export const CreateMode: Story = {
+  args: {
+    mode: "create",
+    value: "",
+    placeholder: "Enter description",
+  },
+  play: async ({ canvas }) => {
+    const textarea = canvas.getByTestId("test-area-input");
+    await expect(textarea).toBeInTheDocument();
+  },
+};

package/src/components/editable/EditableTextArea.tsx

@@ -0,0 +1,148 @@
+import { useEffect, useRef, type JSX, type ReactNode } from "react";
+import { useEditableField } from "./useEditableField.js";
+import styles from "./EditableField.module.scss";
+
+/** Props for EditableTextArea. */
+export interface EditableTextAreaProps {
+  /** 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., Markdown). */
+  renderDisplay?: (value: string) => ReactNode | undefined;
+  /** Placeholder text shown when empty. */
+  placeholder?: string;
+  /** Accessible label for the textarea. */
+  ariaLabel?: string;
+  /** Base test ID — gets `-input` / `-button` suffixes appended. */
+  "data-testid"?: string;
+}
+
+/** Reusable click-to-edit textarea field. */
+export function EditableTextArea(props: EditableTextAreaProps): JSX.Element {
+  const {
+    value,
+    onSave,
+    validate,
+    mode = "edit",
+    fieldId = "textarea",
+    activeFieldId,
+    onActivate,
+    onChange,
+    renderDisplay,
+    placeholder,
+    ariaLabel,
+    "data-testid": testId,
+  } = props;
+
+  const textareaRef = useRef<HTMLTextAreaElement>(null);
+
+  const field = useEditableField({
+    value,
+    onSave,
+    validate,
+    fieldId,
+    activeFieldId,
+    onActivate,
+    enterToSave: false,
+    trimOnSave: false,
+  });
+
+  // Auto-focus when entering edit mode
+  useEffect(() => {
+    if (field.isEditing) {
+      const timer = window.setTimeout(() => {
+        textareaRef.current?.focus();
+      }, 0);
+      return () => window.clearTimeout(timer);
+    }
+  }, [field.isEditing]);
+
+  // Create mode: always show textarea, no blur-to-save
+  if (mode === "create") {
+    const handleChange = (e: React.ChangeEvent<HTMLTextAreaElement>): void => {
+      onChange?.(e.target.value);
+    };
+
+    const validationError = validate?.(value);
+
+    return (
+      <div className={styles.editFieldWrapper}>
+        <textarea
+          className={`${styles.editTextarea} ${validationError ? styles.editInputInvalid : ""}`}
+          value={value}
+          onChange={handleChange}
+          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 textarea
+  if (field.isEditing) {
+    return (
+      <div className={styles.editFieldWrapper}>
+        <textarea
+          ref={textareaRef}
+          className={`${styles.editTextarea} ${field.error ? styles.editInputInvalid : ""}`}
+          value={field.draft}
+          onChange={(e) => field.setDraft(e.target.value)}
+          onBlur={field.handleBlur}
+          onKeyDown={field.handleKeyDown}
+          title={ariaLabel}
+          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}>Tab to save &middot; Esc to cancel</span>
+      </div>
+    );
+  }
+
+  // Display mode — uses <span role="button"> to avoid nested interactive elements
+  // when renderDisplay returns links or block-level content (e.g., Markdown)
+  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/EditableTextField.stories.tsx

@@ -0,0 +1,62 @@
+import type { Meta, StoryObj } from "@storybook/react";
+import { expect, fn } from "@storybook/test";
+import { EditableTextField } from "./EditableTextField.js";
+
+const meta: Meta<typeof EditableTextField> = {
+  title: "Primitives/Editable/EditableTextField",
+  tags: ["autodocs"],
+  component: EditableTextField,
+  args: {
+    value: "Hello World",
+    onSave: fn(),
+    "data-testid": "test-field",
+  },
+};
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+/** Display mode shows the value with an edit button. */
+export const DisplayMode: Story = {
+  play: async ({ canvas }) => {
+    await expect(canvas.getByText("Hello World")).toBeInTheDocument();
+    const button = canvas.getByTestId("test-field-button");
+    await expect(button).toBeInTheDocument();
+    await expect(button).toHaveAttribute("role", "button");
+  },
+};
+
+/** Display button is keyboard-accessible (tabIndex, role, focusable). */
+export const KeyboardAccessible: Story = {
+  play: async ({ canvas }) => {
+    const button = canvas.getByTestId("test-field-button");
+    await expect(button).toHaveAttribute("role", "button");
+    await expect(button).toHaveAttribute("tabindex", "0");
+
+    button.focus();
+    await expect(button).toHaveFocus();
+  },
+};
+
+/** Empty value shows placeholder text. */
+export const EmptyShowsPlaceholder: Story = {
+  args: {
+    value: "",
+    placeholder: "Enter a value",
+  },
+  play: async ({ canvas }) => {
+    await expect(canvas.getByText("Enter a value")).toBeInTheDocument();
+  },
+};
+
+/** Create mode renders as an always-visible input. */
+export const CreateMode: Story = {
+  args: {
+    mode: "create",
+    value: "",
+    placeholder: "Enter title",
+  },
+  play: async ({ canvas }) => {
+    const input = canvas.getByTestId("test-field-input");
+    await expect(input).toBeInTheDocument();
+  },
+};