fix(forms): stop placeholders reading as values a blank field doesn't submit

[dawsontoth]

⊙ Problem

Some Fabric placeholders show a real-looking value that a blank field does not submit (#1294). Users read the field as already filled and leave it blank, or retype the grey text by hand. The worst case is OAuth Scope: a blank Scope saved an empty string, and that empty string replaces the provider's preset scope, so sign-in ran with no scope at all.

❓ Your call: every row in the table below is a UX wording call. Each row is a one-line text change except Scope, so any of them can be reverted on its own.

💡 Solution

I went through all ~70 placeholders in src and sorted each one with a single rule. A placeholder that shows a value must either be what a blank field submits, or read as an example. Instructions ("Search…", "Choose Role") and placeholders that already match what a blank field submits are left alone (see Left unchanged below).

Where	Field	Before	After	Why
Org → Settings → OAuth (add + edit)	Scope	placeholder openid email profile, but a blank field sent ''	placeholder unchanged; a blank field now sends openid email profile	Makes the placeholder true. See the evidence below
Org → Settings → OAuth (add + edit)	Domain	company.okta.com	e.g. company.okta.com	Required field that looked filled in
New cluster (self-managed)	Optional Cluster Load Balancer Host Name	example.your-company.com	e.g. cluster.your-company.com	Optional field: a blank one sets no host name, but it looked set
Applications → Import, and Redeploy	Install Command	npm install	Leave blank to install dependencies automatically	A blank field already gets Harper's automatic install. Typing npm install is not the same thing: it opts out of the automatic install. Evidence below
Schema editor → field → Index options	Index type	HNSW	e.g. HNSW	A blank type means a standard index, not HNSW, so users thought they had a vector index
API explorer → Authorize → Bearer	Token	eyJhbGciOi…	e.g. eyJhbGciOi…	A cut-off JWT looks like a token that is already stored

❓ Your call: on edit, a provider saved with an empty scope gets openid email profile written the next time anyone saves it, even if the admin only changed the domain. Today that config signs in with an empty scope, so this repairs it, but it is a write the admin didn't type.

❓ Your call: HNSW is Harper's only custom index type, so e.g. slightly implies there are others. The fuller fix the issue mentions is a dropdown (Standard / HNSW). I didn't do that because the schema editor's text fields round-trip any directive argument as-is, and a dropdown would drop unknown values.

Evidence for the behavioral claims (traced, not assumed):

• Scope. Studio sends '' for a blank Scope. Central manager passes the stored value to @harperfast/oauth unchanged. That library's buildProviderConfig spreads it over the preset: config.ts:79-82 @ v1.6.0, the version central manager pins. v2.9.0 still keeps an explicit '' (config.ts:548-552). The authorize request then sends scope: this.config.scope || '' (OAuthProvider.ts:76 @ v1.6.0).
• Install Command. Harper runs a custom command only when one is set (Application.ts:4402). Otherwise it uses the package manager from package.json devEngines.packageManager (:4457), and falls back to npm with --omit=dev (:4540). A redeploy with a blank command writes no install block (operations.js:793). Harper 5.0.0 and 4.7 use the same order: custom command, then devEngines, then npm.
• Index type. CUSTOM_INDEXES holds only HNSW (customIndexes.ts:4), and a blank type returns early as a standard index (databases.ts:3482). Distance left blank is cosine (HierarchicalNavigableSmallWorld.ts:543-548), so its cosine placeholder stays.

Left unchanged

• Already what a blank field submits: new-org Name and Subdomain, cluster Host Name and Operations API Port, Create Table's Primary Key id and Database data, Import Data's Database data, the schema editor's Database data, table/endpoint name overrides and Distance cosine, and the new application's Name.
• Instructions, not values: search and filter boxes, Choose … selects, Your password, Leave blank to keep existing, Okta Client ID/Secret, Optional, Page.
• Already examples: e.g. us-east-1, e.g. 100OFF, e.g. example.com, *.example.com, e.g. https, operations, wss, e.g. 280ms, medium distribution.
• Conventional, or deliberately value-shaped: you@company.com on the auth pages reads as a template. The secret editor's ******** deliberately signals a hidden existing value, next to Reveal. The cluster instance protocol select's https:// placeholder never shows, because secure is always set. In the admin-only notification composer, the link sample lists two alternatives joined by "or", and a blank message is rejected when you submit.

Skipped (would conflict)

• Import Data → CSV URL https://example.com/data.csv → e.g. https://example.com/data.csv. I skipped it because open PR feat(status): list Harper jobs on a Jobs tab, and follow a CSV import's job in a toast #1880 adds ImportDataModal.progress.test.tsx, which queries getByPlaceholderText('https://example.com/data.csv'). That test would break when the two merge. It is a one-line follow-up once feat(status): list Harper jobs on a Jobs tab, and follow a CSV import's job in a toast #1880 lands.

🔧 Changes

• src/features/organization/settings/index.tsx:
  • adds a DEFAULT_OAUTH_SCOPE constant. It is used as the add form's default value and in both Scope placeholders (edit, add).
  • when Scope is blank, the add and edit submit paths now send that default.
  • both Domain placeholders now start with e.g. (edit, add).
  • Also fixed: the provider card's icon-only edit (pencil) button had no accessible name. It now has aria-label="Edit provider", which the new test also uses to find it.
• These placeholders now start with e.g.:
  • load balancer host name in ClusterFQDN.tsx
  • index type in FieldRow.tsx
  • bearer token in SettingsPanel.tsx (dprint re-wrapped this line)
• The Install Command placeholder now says what a blank field does, in RedeployApplicationModal.tsx and ImportInstructions.tsx.

✅ Verification

• End-to-end route: not observable end-to-end here, because it needs a real Okta tenant to sign in against. The submit payload is covered by a new component test instead: src/features/organization/settings/index.test.tsx renders the real page against a mocked apiClient. It checks three things: that a blank Scope on add sends exactly the placeholder's value, that an edit of a provider with no stored scope sends the default, and that a typed scope is kept. Mutation-checked: with both fallbacks reverted, the first two tests fail (expected ' ' / '' to be 'openid email profile').
• The other rows only change placeholder text. No test on stage queries those placeholders, and none of the open PRs that touch these files changes or queries them (checked feat(deploy): follow a rolling deploy's restart job, and show canary certification #1868, Show a failed app import or redeploy once, and keep a failed import beside its form #1871, feat(deploy): stage a release now and activate it later (Harper 5.3+) #1876, fix(sidebars): resize every sidebar with one pointer hook that never sticks mid-drag #1805 and fix(auth): finish sign-out when a storage write throws #1813). feat(status): list Harper jobs on a Jobs tab, and follow a CSV import's job in a toast #1880 does query the CSV URL placeholder, which is why that row was skipped.
• Gates: focused npx vitest run on all touched directories, 19 files / 221 tests, exit 0. npx tsc -b exit 0, npx oxlint exit 0, npx dprint check exit 0. The pre-commit hook ran the full suite (396 files, 3,666 passed / 11 skipped), oxlint, dprint and commitlint, all green.
• Design assessment: no new or changed API surface, no cross-layer boundary, no shared core behavior. The only behavior change is in the org settings submit path.
• Cross-model review: one full round. codex (graded) and gemini both ran. Neither Cursor lens produced a receipt, because the 1Password SSH agent refused the reviewer's git fetch. The Harper domain adjudicator failed on an expired Claude OAuth session, so the outside findings were triaged by hand:
  • Taken: codex's two nits. The test now imports @/features/organization/settings, and instead of a comment explaining an unnamed-button selector, the edit button has an accessible name. I also renamed the add test, since gemini pointed out it clears Scope to whitespace rather than leaving it untouched.
  • Declined: move the fallback into a zod transform. Both schemas are module-private with one consumer each. A transform would split useForm's input and output types to protect a hypothetical second consumer.
  • Declined: put the install-command guidance in a description instead of the placeholder. A placeholder shows exactly when the field is blank, which is when this guidance applies (gemini's "cleared and forgot" case re-shows it). A FormDescription would also collide with open PR feat(deploy): stage a release now and activate it later (Harper 5.3+) #1876, which adds that same import to both files.
  • Declined: drop the comment on DEFAULT_OAUTH_SCOPE. It states a constraint the code can't show: a blank scope is stored as-is and overrides the provider preset.
  • The fixes went into an amended commit with no second round, since the legs that failed would hit the same infrastructure problems again.

Closes #1294

🤖 Generated with Claude Code

Related PRs: none found
Complexity: easy

_{Review-Coverage: authored=claude; ran=gemini,codex; blocked=cursor-grok(no-receipt),cursor-composer(no-receipt),domain(auth); declined=cursor-kimi,cursor-muse; rounds=1; full=1 @ 53c9df4}

_{Review-Attention: study ~11m (critical: FieldRow.tsx; raised: degraded review) @ 53c9df4}

[gemini-code-assist]

Code Review

This pull request improves user experience and form validation by updating several input placeholders for clarity, adding accessibility labels, and ensuring that empty or whitespace-only OAuth scope inputs default to a standard fallback value. Additionally, a new test suite has been added to verify the OAuth scope behavior under various conditions. There are no review comments, and the changes look correct and well-tested.

[github-actions]

Coverage Report

Status	Category	Percentage	Covered / Total
🔵	Lines	67.9%	10155 / 14954
🔵	Statements	68.04%	10833 / 15921
🔵	Functions	61.38%	2625 / 4276
🔵	Branches	62.79%	7719 / 12293

File Coverage

File	Stmts	Branches	Functions	Lines	Uncovered Lines
Changed Files
src/features/clusters/upsert/fields/ClusterFQDN.tsx	0%	100%	0%	0%	18-37
src/features/instance/apis/explorer/SettingsPanel.tsx	94.02%	82.19%	93.33%	93.93%	42, 206, 371-377, 394
src/features/instance/applications/components/NewApplication/ImportInstructions.tsx	62.5%	100%	50%	62.5%	33, 91-128
src/features/instance/applications/components/SchemaEditorView/FieldRow.tsx	42.55%	66.66%	22.85%	38.09%	58, 60, 62, 64, 84-91, 127-268
src/features/organization/settings/index.tsx	73.61%	69.76%	64.7%	75.71%	83, 121, 122, 134-138, 145-146, 151-152, 157-160, 199, 263-369, 404-405, 479-480

Generated in workflow #2100 for commit 53c9df4 by the Vitest Coverage Report Action