{
setFieldType(type);
setValue('');
- if (!FIELD_TYPE_META[type].supportsExpression) {
- setMode('literal');
- }
};
if (deleted) return null;
@@ -415,6 +407,33 @@ export const InlineValidation: Story = {
},
};
+export const Disabled: Story = {
+ render: () => (
+
+ {}}
+ onValueChange={() => {}}
+ onModeChange={() => {}}
+ onFieldTypeChange={() => {}}
+ onRequiredChange={() => {}}
+ variables={[{ label: 'Item ID', value: 'item.id' }]}
+ disabled
+ />
+
+ ),
+ parameters: {
+ docs: {
+ description: {
+ story:
+ 'Use `disabled` to stop the author editing the field. It disables the value control, the lock, the value-mode menu, and the header controls. A locked field stays editable: the lock only marks the value read-only for the person filling in the form.',
+ },
+ },
+ },
+};
+
const MODE_ITEMS: { mode: QuickFormFieldMode; label: string; icon: typeof Type }[] = [
{ mode: 'literal', label: 'Fixed value', icon: Type },
{ mode: 'expression', label: 'Expression', icon: Code2 },
@@ -690,9 +709,6 @@ function ResponsiveDemo() {
const handleFieldTypeChange = (type: QuickFieldType) => {
setFieldType(type);
setValue('');
- if (!FIELD_TYPE_META[type].supportsExpression) {
- setMode('literal');
- }
};
const label = (fieldId: string) => (
diff --git a/packages/apollo-wind/src/components/ui/quick-form-field/quick-form-field.test.tsx b/packages/apollo-wind/src/components/ui/quick-form-field/quick-form-field.test.tsx
index f5c6966bb4..6b46356399 100644
--- a/packages/apollo-wind/src/components/ui/quick-form-field/quick-form-field.test.tsx
+++ b/packages/apollo-wind/src/components/ui/quick-form-field/quick-form-field.test.tsx
@@ -5,10 +5,46 @@ import { describe, expect, it, vi } from 'vitest';
import { QuickFormField } from './quick-form-field';
describe('QuickFormField', () => {
- it('renders a read-only display value when locked', () => {
- render(Custom editor
);
render(
{
expect.objectContaining({
value: 'item.id',
readOnly: true,
+ disabled: true,
onValueChange: undefined,
})
);
});
- it('does not attach a value-change handler to the built-in expression input while locked', () => {
+ it('does not attach a value-change handler to the built-in expression input while disabled', () => {
const handleChange = vi.fn();
render(
- {
variables={[{ label: 'Item ID', value: 'item.id' }]}
/>
);
- expect(screen.getByRole('button', { name: 'Insert variable' })).toBeDisabled();
+ expect(screen.getByRole('button', { name: 'Insert variable' })).not.toBeDisabled();
});
it('appends the selected variable to the current value when Insert variable is used', async () => {
@@ -720,13 +726,13 @@ describe('QuickFormField', () => {
);
});
- it('grows the multi-select box to hold wrapped chips, and only while unlocked', () => {
+ it('grows the multi-select box to hold wrapped chips, and only in literal mode', () => {
const { container, rerender } = render(
- {
await user.click(screen.getByRole('button', { name: 'AI assist' }));
expect(screen.getByText('Ausgabe: Datum-Ausdruck')).toBeInTheDocument();
- await user.type(screen.getByRole('textbox'), 'next week');
+ await user.type(screen.getByLabelText('Describe what you want'), 'next week');
await user.click(screen.getByRole('button', { name: 'Generate' }));
expect(await screen.findByText('Wird generiert')).toBeInTheDocument();
reject(new Error('nope'));
expect(await screen.findByText('Fehlgeschlagen')).toBeInTheDocument();
});
-
- it('shows a locked boolean with the strings labels', () => {
- render(
- onModeChange?.(next)}
- modesDisabled={!offersModes && menuActions.length > 0}
- disabled={!offersModes && menuActions.length === 0}
+ modesDisabled={!onModeChange && menuActions.length > 0}
+ disabled={disabled || (!onModeChange && menuActions.length === 0)}
actions={menuActions}
triggerLabel={strings.valueModeAriaLabel}
literalDescription={strings.literalDescriptions[fieldType] ?? typeMeta.fixedDescription}
@@ -148,25 +144,25 @@ export function QuickFormField({
fieldActions: strings.moreActionsAriaLabel,
}}
/>
- ) : null;
+ );
+
+ const controlProps: QuickFormFieldControlProps = {
+ id: fieldId,
+ value,
+ onValueChange: editableOnValueChange,
+ onBlur: onValueBlur,
+ readOnly: !editableOnValueChange,
+ disabled,
+ placeholder: valuePlaceholder,
+ fieldType,
+ 'aria-invalid': error ? true : undefined,
+ 'aria-describedby': error ? validationId : undefined,
+ 'aria-errormessage': error ? validationId : undefined,
+ 'data-slot': 'input-group-control',
+ };
- // Resolved before the tree so returning nothing falls back to the built-in
- // control. Offered the raw mode, not `effectiveMode`: the coercion protects
- // the built-in rendering and must not decide for a consumer with its own editor.
- const modeControl =
- renderModeControl?.(mode, {
- id: fieldId,
- value,
- onValueChange: editableOnValueChange,
- onBlur: onValueBlur,
- readOnly: !editableOnValueChange,
- placeholder: valuePlaceholder,
- fieldType,
- 'aria-invalid': error ? true : undefined,
- 'aria-describedby': error ? validationId : undefined,
- 'aria-errormessage': error ? validationId : undefined,
- 'data-slot': 'input-group-control',
- }) ?? null;
+ // Resolved before the tree so returning nothing falls back to the built-in control.
+ const modeControl = renderModeControl?.(mode, controlProps) ?? null;
// Switching mode is a prelude to writing the value, so focus the control.
// Skipped on mount so rendering a form cannot steal focus.
@@ -186,7 +182,7 @@ export function QuickFormField({
}
if (e.key === 'Escape') {
e.preventDefault();
- onValueChange?.(committedRef.current);
+ editableOnValueChange?.(committedRef.current);
e.currentTarget.blur();
}
};
@@ -214,10 +210,157 @@ export function QuickFormField({
});
};
- // Locked fields are read-only, not disabled — the raw control (switch, date
- // picker, select) has nothing left to do once editing is blocked, so it's
- // replaced with plain, selectable text showing the same value.
- const lockedDisplayValue = getLockedDisplayValue(fieldType, value, options, strings);
+ // Shared by the expression input and the literal text input, which both
+ // track the caret for Insert variable.
+ const textInputProps = {
+ id: fieldId,
+ ref: valueInputRef,
+ readOnly: !editableOnValueChange,
+ disabled,
+ value,
+ onChange: (e: React.ChangeEvent) => editableOnValueChange?.(e.target.value),
+ onFocus: (e: React.FocusEvent) => {
+ committedRef.current = value;
+ caretRef.current = {
+ start: e.currentTarget.selectionStart ?? value.length,
+ end: e.currentTarget.selectionEnd ?? value.length,
+ };
+ },
+ onSelect: (e: React.SyntheticEvent) => {
+ const el = e.currentTarget;
+ caretRef.current = {
+ start: el.selectionStart ?? 0,
+ end: el.selectionEnd ?? el.selectionStart ?? 0,
+ };
+ },
+ onKeyDown: handleValueKeyDown,
+ onBlur: (e: React.FocusEvent) => {
+ // Clicking the Insert trigger blurs this input, so this is the last
+ // moment the caret is knowable.
+ caretRef.current = {
+ start: e.currentTarget.selectionStart ?? value.length,
+ end: e.currentTarget.selectionEnd ?? value.length,
+ };
+ onValueBlur?.();
+ },
+ placeholder: valuePlaceholder,
+ };
+
+ const literalControl =
+ fieldType === 'boolean' ? (
+
+ editableOnValueChange?.(String(checked))}
+ onBlur={onValueBlur}
+ disabled={!editableOnValueChange}
+ />
+
+ ) : fieldType === 'date' ? (
+ {
+ setDatePopoverOpen(open);
+ if (!open) onValueBlur?.();
+ }}
+ >
+
+
+ {value ? (
+ formatDateValue(value)
+ ) : (
+ {strings.pickDate}
+ )}
+
+
+
+ editableOnValueChange?.(date ? toDateOnlyString(date) : '')}
+ initialFocus
+ />
+
+
+ ) : fieldType === 'datetime' ? (
+ // A timestamp needs the time of day, so it uses DateTimePicker rather
+ // than the date branch's Calendar popover. Stored as an ISO string.
+ editableOnValueChange?.(date ? date.toISOString() : '')}
+ onOpenChange={(open) => {
+ if (!open) onValueBlur?.();
+ }}
+ disabled={!editableOnValueChange}
+ placeholder={valuePlaceholder}
+ />
+ ) : fieldType === 'file' ? (
+ editableOnValueChange?.(files.map((f) => f.name).join(', '))}
+ disabled={!editableOnValueChange}
+ onBlur={onValueBlur}
+ aria-invalid={controlProps['aria-invalid']}
+ aria-describedby={controlProps['aria-describedby']}
+ aria-errormessage={controlProps['aria-errormessage']}
+ />
+ ) : fieldType === 'single-select' ? (
+ {
+ setSelectOpen(open);
+ if (!open && selectOpen) onValueBlur?.();
+ }}
+ value={value || undefined}
+ onValueChange={editableOnValueChange}
+ disabled={!editableOnValueChange}
+ >
+
+
+
+ {options.map((option) => (
+
+ {option.label}
+
+ ))}
+
+
+ ) : fieldType === 'multi-select' ? (
+ editableOnValueChange?.(JSON.stringify(selected))}
+ placeholder={strings.selectOptions}
+ disabled={!editableOnValueChange}
+ onBlur={onValueBlur}
+ />
+ ) : (
+
- {typeMeta.supportsExpression ? (
-
- {(showLock || leadingAddon !== undefined) && leadingAddon !== null && (
-
- {leadingAddon !== undefined
- ? leadingAddon
- : showLock && (
-
- )}
-
- {modeControl ??
- (effectiveMode === 'expression' ? (
- renderExpressionEditor ? (
- renderExpressionEditor({
- id: fieldId,
- value,
- onValueChange: editableOnValueChange,
- onBlur: onValueBlur,
- readOnly: !editableOnValueChange,
- placeholder: valuePlaceholder,
- fieldType,
- 'aria-invalid': error ? true : undefined,
- 'aria-describedby': error ? validationId : undefined,
- 'aria-errormessage': error ? validationId : undefined,
- 'data-slot': 'input-group-control',
- })
- ) : (
- editableOnValueChange?.(e.target.value)}
- onFocus={(e) => {
- committedRef.current = value;
- caretRef.current = {
- start: e.currentTarget.selectionStart ?? value.length,
- end: e.currentTarget.selectionEnd ?? value.length,
- };
- }}
- onSelect={(e) => {
- const el = e.currentTarget;
- caretRef.current = {
- start: el.selectionStart ?? 0,
- end: el.selectionEnd ?? el.selectionStart ?? 0,
- };
- }}
- onKeyDown={handleValueKeyDown}
- onBlur={(e) => {
- caretRef.current = {
- start: e.currentTarget.selectionStart ?? value.length,
- end: e.currentTarget.selectionEnd ?? value.length,
- };
- onValueBlur?.();
- }}
- placeholder={valuePlaceholder}
- className="font-mono"
- />
- )
- ) : locked ? (
-
- onValueChange?.(String(checked))}
- onBlur={onValueBlur}
- disabled={!onValueChange}
- />
-
- ) : fieldType === 'date' ? (
- {
- setDatePopoverOpen(open);
- if (!open) onValueBlur?.();
- }}
- >
-
-
- {value ? (
- formatDateValue(value)
- ) : (
- {strings.pickDate}
- )}
-
-
-
- onValueChange?.(date ? toDateOnlyString(date) : '')}
- initialFocus
+
+ {(showLock || leadingAddon !== undefined) && leadingAddon !== null && (
+
+ {leadingAddon !== undefined
+ ? leadingAddon
+ : showLock && (
+
-
- ) : fieldType === 'datetime' ? (
- // A timestamp needs the time of day, so it uses DateTimePicker rather
- // than the date branch's Calendar popover. Stored as an ISO string.
- onValueChange?.(date ? date.toISOString() : '')}
- onOpenChange={(open) => {
- if (!open) onValueBlur?.();
- }}
- disabled={!onValueChange}
- placeholder={valuePlaceholder}
- />
- ) : fieldType === 'file' ? (
- onValueChange?.(files.map((f) => f.name).join(', '))}
- disabled={!onValueChange}
- onBlur={onValueBlur}
- aria-invalid={error ? true : undefined}
- aria-describedby={error ? validationId : undefined}
- aria-errormessage={error ? validationId : undefined}
- />
- ) : (
- onValueChange?.(e.target.value)}
- onFocus={(e) => {
- committedRef.current = value;
- caretRef.current = {
- start: e.currentTarget.selectionStart ?? value.length,
- end: e.currentTarget.selectionEnd ?? value.length,
- };
- }}
- onSelect={(e) => {
- const el = e.currentTarget;
- caretRef.current = {
- start: el.selectionStart ?? 0,
- end: el.selectionEnd ?? el.selectionStart ?? 0,
- };
- }}
- onKeyDown={handleValueKeyDown}
- onBlur={(e) => {
- // Clicking the Insert trigger blurs this input, so this is the
- // last moment the caret is knowable.
- caretRef.current = {
- start: e.currentTarget.selectionStart ?? value.length,
- end: e.currentTarget.selectionEnd ?? value.length,
- };
- onValueBlur?.();
- }}
- placeholder={valuePlaceholder}
- />
- ))}
+ )}
+
+ )}
- {trailingAddon !== null && (trailingAddon !== undefined || builtInMenu) && (
-
- {trailingAddon !== undefined ? trailingAddon : builtInMenu}
-
- )}
-
- ) : (
-
- {(showLock || leadingAddon !== undefined) && leadingAddon !== null && (
-
- {leadingAddon !== undefined
- ? leadingAddon
- : showLock && (
-
- )}
+ {modeControl ??
+ (mode === 'expression' ? (
+ renderExpressionEditor ? (
+ renderExpressionEditor(controlProps)
+ ) : (
+ {
- setSelectOpen(open);
- if (!open && selectOpen) onValueBlur?.();
- }}
- value={value || undefined}
- onValueChange={onValueChange}
- disabled={!onValueChange}
- >
-
-
-
- {options.map((option) => (
-
- {option.label}
-
- ))}
-
-
- ) : fieldType === 'multi-select' ? (
- onValueChange?.(JSON.stringify(selected))}
- placeholder={strings.selectOptions}
- disabled={!onValueChange}
- onBlur={onValueBlur}
- />
- ) : null)}
- {/* A select can still be bound to a variable, so the consumer's
- trailing control renders here too or it loses its mode switch. */}
- {trailingAddon !== null && (trailingAddon !== undefined || builtInMenu) && (
-
- {trailingAddon !== undefined ? trailingAddon : builtInMenu}
-
- )}
-
- )}
+ {trailingAddon !== null && (
+
+ {trailingAddon !== undefined ? trailingAddon : builtInMenu}
+
+ )}
+
{belowValue}
diff --git a/packages/apollo-wind/src/components/ui/quick-form-field/types.ts b/packages/apollo-wind/src/components/ui/quick-form-field/types.ts
index c9616a4f8e..6928824c28 100644
--- a/packages/apollo-wind/src/components/ui/quick-form-field/types.ts
+++ b/packages/apollo-wind/src/components/ui/quick-form-field/types.ts
@@ -37,6 +37,10 @@ export type QuickFieldType =
interface FieldTypeMeta {
label: string;
icon: LucideIcon;
+ /**
+ * @deprecated Will expand mode support in future update. Currently unused.
+ * Removed in the next major release.
+ */
supportsExpression: boolean;
fixedLabel: string;
fixedDescription: string;
@@ -88,14 +92,14 @@ export const FIELD_TYPE_META: Record = {
'single-select': {
label: 'Single select',
icon: List,
- supportsExpression: false,
+ supportsExpression: true,
fixedLabel: 'Fixed value',
fixedDescription: 'Choose one option',
},
'multi-select': {
label: 'Multi select',
icon: ListChecks,
- supportsExpression: false,
+ supportsExpression: true,
fixedLabel: 'Fixed value',
fixedDescription: 'Choose one or more options',
},
@@ -156,8 +160,9 @@ export interface QuickFormFieldStrings {
valueFieldLabel: (typeLabel: string) => string;
/** The computed field name in expression mode, from the (localized) type label. */
expressionFieldLabel: (typeLabel: string) => string;
- /** A locked boolean's displayed text. */
+ /** @deprecated No longer rendered: a locked boolean keeps its Switch. Removed in the next major release. */
trueLabel: string;
+ /** @deprecated No longer rendered: a locked boolean keeps its Switch. Removed in the next major release. */
falseLabel: string;
requiredTooltip: string;
requiredAriaLabel: string;
@@ -268,33 +273,60 @@ export interface VariableInsertContext {
caret: { start: number; end: number } | null;
}
+/** What a consumer-rendered value control receives from `renderModeControl` or `renderExpressionEditor`. */
+export interface QuickFormFieldControlProps {
+ id: string;
+ value: string;
+ /** Omitted while the field is disabled or has no `onValueChange`. */
+ onValueChange?: (value: string) => void;
+ onBlur?: () => void;
+ readOnly: boolean;
+ disabled: boolean;
+ placeholder: string;
+ fieldType: QuickFieldType;
+ 'aria-invalid'?: AriaAttributes['aria-invalid'];
+ 'aria-describedby'?: string;
+ 'aria-errormessage'?: string;
+ 'data-slot'?: string;
+}
+
export interface QuickFormFieldProps {
/** Current field value. Encoding depends on fieldType (e.g. multi-select is a JSON array string). */
value?: string;
- /** Called when the user edits the value (only fires while unlocked). */
+ /** Called when the user edits the value. Never fires while `disabled`. */
onValueChange?: (value: string) => void;
/** Called when the active value control loses focus. */
onValueBlur?: () => void;
- /** Whether the field is read-only. Defaults to true. */
+ /**
+ * Whether the value is read-only for the person filling in the form. It is
+ * configuration the author sets, so the value stays editable here; use
+ * `disabled` to stop editing. Defaults to true.
+ */
locked?: boolean;
/** Called when the user toggles the lock. */
onLockedChange?: (locked: boolean) => void;
/** Whether the built-in lock control renders. Defaults to true. */
showLock?: boolean;
+ /**
+ * Disables every built-in control: the value control, the lock, the mode and
+ * actions menu, and the header's type picker, Required switch, Insert
+ * variable and AI assist. `headerActions` are the consumer's to disable.
+ */
+ disabled?: boolean;
/**
* Replaces the leading lock toggle with a semantic prefix such as `=`.
* Pass `null` to suppress the built-in toggle; omitting the prop preserves it.
*/
leadingAddon?: ReactNode;
/**
- * Replaces the trailing fixed/expression menu with a consumer-provided action
- * for expression-capable field types. Pass `null` to suppress the built-in
+ * Replaces the trailing fixed/expression menu with a consumer-provided
+ * action. Pass `null` to suppress the built-in
* menu; omitting the prop preserves it.
*/
trailingAddon?: ReactNode;
/** Adds a field-level overflow menu beside the value control. */
more?: QuickFormFieldMoreActions;
- /** How the value is expressed. Defaults to 'literal'; `expression` falls back to `literal` for types that cannot hold one. */
+ /** How the value is expressed. Defaults to 'literal'. */
mode?: QuickFormFieldMode;
/** Called when the user switches modes. */
onModeChange?: (mode: QuickFormFieldMode) => void;
@@ -306,19 +338,7 @@ export interface QuickFormFieldProps {
* existing callers; `renderModeControl` wins when both are supplied and it
* returns something for `expression`.
*/
- renderExpressionEditor?: (props: {
- id: string;
- value: string;
- onValueChange?: (value: string) => void;
- onBlur?: () => void;
- readOnly: boolean;
- placeholder: string;
- fieldType: QuickFieldType;
- 'aria-invalid'?: AriaAttributes['aria-invalid'];
- 'aria-describedby'?: string;
- 'aria-errormessage'?: string;
- 'data-slot'?: string;
- }) => ReactNode;
+ renderExpressionEditor?: (props: QuickFormFieldControlProps) => ReactNode;
/**
* Renders the value control for a given mode, replacing the built-in one.
* `variable` and `prompt` have no built-in editor, and a surface that authors
@@ -328,22 +348,7 @@ export interface QuickFormFieldProps {
* for the field's type, so an unhandled mode degrades to the literal editor
* rather than rendering an empty row.
*/
- renderModeControl?: (
- mode: QuickFormFieldMode,
- props: {
- id: string;
- value: string;
- onValueChange?: (value: string) => void;
- onBlur?: () => void;
- readOnly: boolean;
- placeholder: string;
- fieldType: QuickFieldType;
- 'aria-invalid'?: AriaAttributes['aria-invalid'];
- 'aria-describedby'?: string;
- 'aria-errormessage'?: string;
- 'data-slot'?: string;
- }
- ) => ReactNode;
+ renderModeControl?: (mode: QuickFormFieldMode, props: QuickFormFieldControlProps) => ReactNode;
/**
* Takes over what choosing a variable does to the value. The component owns
* the picker and hands back the chosen entry exactly as supplied in
diff --git a/packages/apollo-wind/src/components/ui/quick-form-field/utils.ts b/packages/apollo-wind/src/components/ui/quick-form-field/utils.ts
index d95ed8be71..a41a6c64e7 100644
--- a/packages/apollo-wind/src/components/ui/quick-form-field/utils.ts
+++ b/packages/apollo-wind/src/components/ui/quick-form-field/utils.ts
@@ -1,4 +1,4 @@
-import type { QuickFieldType, QuickFormFieldOption } from './types';
+import type { QuickFormFieldOption } from './types';
export const DEFAULT_SELECT_OPTIONS: QuickFormFieldOption[] = [
{ label: 'Option 1', value: 'option-1' },
@@ -59,59 +59,3 @@ export function formatDateValue(value: string): string {
? date.toLocaleDateString(undefined, { year: 'numeric', month: 'long', day: 'numeric' })
: value;
}
-
-// Separate from formatDateValue so the date-only output stays unchanged.
-/** Formats a datetime field's value, falling back to the raw value when unparseable. */
-export function formatDateTimeValue(value: string): string {
- const date = parseDateValue(value);
- return date
- ? date.toLocaleString(undefined, {
- year: 'numeric',
- month: 'long',
- day: 'numeric',
- hour: 'numeric',
- minute: '2-digit',
- })
- : value;
-}
-
-/**
- * Computes the plain-text shown in place of the real control once a field is locked.
- * Boolean/single-select/multi-select resolve their stored value to a display label;
- * everything else (including an invalid date, so the component never throws on
- * external input) falls back to the raw value.
- */
-export function getLockedDisplayValue(
- fieldType: QuickFieldType,
- value: string,
- options: QuickFormFieldOption[],
- booleanLabels: { trueLabel: string; falseLabel: string } = {
- trueLabel: 'True',
- falseLabel: 'False',
- }
-): string {
- switch (fieldType) {
- case 'boolean':
- if (value === 'true') return booleanLabels.trueLabel;
- if (value === 'false') return booleanLabels.falseLabel;
- return '';
- case 'date':
- return value ? formatDateValue(value) : '';
- case 'datetime':
- return value ? formatDateTimeValue(value) : '';
- case 'single-select':
- return options.find((option) => option.value === value)?.label ?? value;
- case 'multi-select': {
- const parsed = parseListValue(value);
- // A malformed value (not JSON, or an array with no string entries) also
- // parses to an empty list -- fall back to the raw value so it's still
- // visible, rather than rendering as if the field were genuinely empty.
- if (parsed.length === 0 && value && value !== '[]') {
- return value;
- }
- return parsed.map((v) => options.find((option) => option.value === v)?.label ?? v).join(', ');
- }
- default:
- return value;
- }
-}
diff --git a/packages/apollo-wind/src/index.ts b/packages/apollo-wind/src/index.ts
index a4ae265b5e..4f7b25512b 100644
--- a/packages/apollo-wind/src/index.ts
+++ b/packages/apollo-wind/src/index.ts
@@ -647,6 +647,7 @@ export type { PromptValueControlProps } from './components/ui/prompt-value-contr
export { PromptValueControl } from './components/ui/prompt-value-control';
export type {
QuickFieldType,
+ QuickFormFieldControlProps,
QuickFormFieldMode,
QuickFormFieldMoreActions,
QuickFormFieldOption,