Form refactors

Author: gallayl

.cursor/rules/SHADES_COMPONENTS.mdc

@@ -210,6 +210,100 @@ export const LoginForm = Shade({
 });
 ```
 
+## Form Handling
+
+### Always use `Form<T>` from `@furystack/shades-common-components`
+
+Never use raw `<form>` HTML elements. The `Form<T>` component provides type-safe form data collection, two-tier validation (input + form level), and integration with all form field components (`Input`, `Select`, `Checkbox`, etc.).
+
+### Pattern: Typed Form Payload
+
+Every form needs:
+
+1. A **payload type** describing the form data shape
+2. A **type-guard `validate` function** that narrows `unknown` to the payload type
+3. A `Form<T>` component with `validate` and `onSubmit` props
+
+```typescript
+import { Form, Input, Button } from '@furystack/shades-common-components';
+
+type CreateStackPayload = {
+  name: string;
+  displayName: string;
+  description: string;
+  mainDirectory: string;
+};
+
+const isCreateStackPayload = (data: unknown): data is CreateStackPayload => {
+  const d = data as CreateStackPayload;
+  return d.name?.length > 0 && d.displayName?.length > 0 && d.mainDirectory?.length > 0;
+};
+
+// In render:
+<Form<CreateStackPayload>
+  validate={isCreateStackPayload}
+  onSubmit={(data) => {
+    // `data` is fully typed as CreateStackPayload
+    void handleSubmit(data);
+  }}
+  style={{ display: 'flex', flexDirection: 'column', gap: '16px' }}
+>
+  <Input name="name" labelTitle="Name" variant="outlined" required />
+  <Input name="displayName" labelTitle="Display Name" variant="outlined" required />
+  <Input name="description" labelTitle="Description" variant="outlined" />
+  <Input name="mainDirectory" labelTitle="Main Directory" variant="outlined" required />
+  <Button type="submit" variant="contained">Create</Button>
+</Form>
+```
+
+### Use `Checkbox` component instead of raw `<input type="checkbox">`
+
+```typescript
+import { Checkbox } from '@furystack/shades-common-components';
+
+// ✅ Good - uses Checkbox component, integrates with Form<T>
+<Checkbox name="autoFetchEnabled" labelTitle="Auto-fetch" checked={initialValue} />
+
+// ❌ Avoid - raw checkbox, no FormService integration
+<label>
+  <input type="checkbox" name="autoFetchEnabled" checked={initialValue} />
+  Auto-fetch
+</label>
+```
+
+### Forbidden Patterns
+
+Never use these patterns for form data handling:
+
+```typescript
+// ❌ FORBIDDEN - raw <form> tag
+<form onsubmit={(ev) => { ... }}>
+
+// ❌ FORBIDDEN - FormData extraction from DOM
+const formData = new FormData(ev.target as HTMLFormElement);
+const data = Object.fromEntries(formData.entries()) as Record<string, string>;
+
+// ❌ FORBIDDEN - useRef to imperatively read form data
+const formRef = useRef<HTMLFormElement>('myForm');
+const data = new FormData(formRef.current);
+
+// ❌ FORBIDDEN - direct DOM value access for form fields
+oninput={(ev) => setValue((ev.target as HTMLInputElement).value)}
+```
+
+### Form Field Components
+
+Use these components from `@furystack/shades-common-components` inside `Form<T>`:
+
+- `Input` - Text, number, email, password fields
+- `Select` - Single/multi select dropdowns
+- `Checkbox` - Boolean checkboxes
+- `TextArea` - Multi-line text input
+- `Switch` - Toggle switches
+- `Radio` / `RadioGroup` - Radio button groups
+
+All form field components automatically register with the parent `Form<T>` via the `FormService` and participate in validation.
+
 ## Theming
 
 ### Access Theme Properties
@@ -332,6 +426,7 @@ initializeShadeRoot({
 6. **useDisposable for cleanup** - Manage subscriptions properly
 7. **Use common components** - Leverage `@furystack/shades-common-components`
 8. **Consistent theming** - Use `ThemeProviderService` for styles
+9. **Use `Form<T>` for all forms** - Never use raw `<form>` tags, `FormData`, or `useRef` for form handling
 
 **Component Checklist:**
 
@@ -341,3 +436,4 @@ initializeShadeRoot({
 - [ ] Observable subscriptions use `useObservable`
 - [ ] Manual subscriptions cleaned up with `useDisposable`
 - [ ] Theme values from `ThemeProviderService`
+- [ ] Forms use `Form<T>` with typed payload and validate function

frontend/src/components/entity-forms/dependency-form.tsx

@@ -1,7 +1,18 @@
 import { createComponent, Shade } from '@furystack/shades'
-import { Button, Input } from '@furystack/shades-common-components'
+import { Button, Form, Input } from '@furystack/shades-common-components'
 import type { Dependency } from 'common'
 
+type DependencyFormPayload = {
+  name: string
+  checkCommand: string
+  installationHelp: string
+}
+
+const isDependencyFormPayload = (data: unknown): data is DependencyFormPayload => {
+  const d = data as DependencyFormPayload
+  return d.name?.length > 0 && d.checkCommand?.length > 0
+}
+
 type DependencyFormProps = {
   initial?: Partial<Dependency>
   stackName: string
@@ -14,19 +25,17 @@ export const DependencyForm = Shade<DependencyFormProps>({
   shadowDomName: 'shade-dependency-form',
   render: ({ props }) => {
     return (
-      <form
-        style={{ display: 'flex', flexDirection: 'column', gap: '16px', maxWidth: '600px' }}
-        onsubmit={async (ev) => {
-          ev.preventDefault()
-          const formData = new FormData(ev.target as HTMLFormElement)
-          const data = Object.fromEntries(formData.entries()) as Record<string, string>
-          await props.onSubmit({
+      <Form<DependencyFormPayload>
+        validate={isDependencyFormPayload}
+        onSubmit={(data) =>
+          void props.onSubmit({
             stackName: props.stackName,
             name: data.name,
             checkCommand: data.checkCommand,
             installationHelp: data.installationHelp,
           })
-        }}
+        }
+        style={{ display: 'flex', flexDirection: 'column', gap: '16px', maxWidth: '600px' }}
       >
         <h2 style={{ margin: '0' }}>{props.mode === 'create' ? 'Add Dependency' : 'Edit Dependency'}</h2>
         <Input
@@ -60,7 +69,7 @@ export const DependencyForm = Shade<DependencyFormProps>({
             {props.mode === 'create' ? 'Add' : 'Save'}
           </Button>
         </div>
-      </form>
+      </Form>
     )
   },
 })

frontend/src/components/entity-forms/github-repo-form.tsx

@@ -1,7 +1,18 @@
 import { createComponent, NestedRouteLink, Shade } from '@furystack/shades'
-import { Button, Input } from '@furystack/shades-common-components'
+import { Button, Form, Input } from '@furystack/shades-common-components'
 import type { GitHubRepository } from 'common'
 
+type GitHubRepoFormPayload = {
+  url: string
+  displayName: string
+  description: string
+}
+
+const isGitHubRepoFormPayload = (data: unknown): data is GitHubRepoFormPayload => {
+  const d = data as GitHubRepoFormPayload
+  return d.url?.length > 0 && d.displayName?.length > 0
+}
+
 type GitHubRepoFormProps = {
   initial?: Partial<GitHubRepository>
   stackName: string
@@ -15,19 +26,17 @@ export const GitHubRepoForm = Shade<GitHubRepoFormProps>({
   shadowDomName: 'shade-github-repo-form',
   render: ({ props }) => {
     return (
-      <form
-        style={{ display: 'flex', flexDirection: 'column', gap: '16px', maxWidth: '600px' }}
-        onsubmit={async (ev) => {
-          ev.preventDefault()
-          const formData = new FormData(ev.target as HTMLFormElement)
-          const data = Object.fromEntries(formData.entries()) as Record<string, string>
-          await props.onSubmit({
+      <Form<GitHubRepoFormPayload>
+        validate={isGitHubRepoFormPayload}
+        onSubmit={(data) =>
+          void props.onSubmit({
             stackName: props.stackName,
             url: data.url,
             displayName: data.displayName,
             description: data.description,
           })
-        }}
+        }
+        style={{ display: 'flex', flexDirection: 'column', gap: '16px', maxWidth: '600px' }}
       >
         <h2 style={{ margin: '0' }}>{props.mode === 'create' ? 'Add GitHub Repository' : 'Edit Repository'}</h2>
         <Input
@@ -65,7 +74,7 @@ export const GitHubRepoForm = Shade<GitHubRepoFormProps>({
             {props.mode === 'create' ? 'Add' : 'Save'}
           </Button>
         </div>
-      </form>
+      </Form>
     )
   },
 })

frontend/src/components/entity-forms/service-form.tsx

@@ -1,7 +1,25 @@
 import { createComponent, NestedRouteLink, Shade } from '@furystack/shades'
-import { Button, Input, Select } from '@furystack/shades-common-components'
+import { Button, Checkbox, Form, Input, Select } from '@furystack/shades-common-components'
 import type { GitHubRepository, ServiceView } from 'common'
 
+type ServiceFormPayload = {
+  displayName: string
+  description: string
+  workingDirectory: string
+  repositoryId: string
+  runCommand: string
+  installCommand: string
+  buildCommand: string
+  autoFetchEnabled: string
+  autoFetchIntervalMinutes: string
+  autoRestartOnFetch: string
+}
+
+const isServiceFormPayload = (data: unknown): data is ServiceFormPayload => {
+  const d = data as ServiceFormPayload
+  return d.displayName?.length > 0 && d.runCommand?.length > 0
+}
+
 type ServiceFormProps = {
   initial?: Partial<ServiceView>
   stackName: string
@@ -16,13 +34,10 @@ export const ServiceForm = Shade<ServiceFormProps>({
   shadowDomName: 'shade-service-form',
   render: ({ props }) => {
     return (
-      <form
-        style={{ display: 'flex', flexDirection: 'column', gap: '16px', maxWidth: '600px' }}
-        onsubmit={async (ev) => {
-          ev.preventDefault()
-          const formData = new FormData(ev.target as HTMLFormElement)
-          const data = Object.fromEntries(formData.entries()) as Record<string, string>
-          await props.onSubmit({
+      <Form<ServiceFormPayload>
+        validate={isServiceFormPayload}
+        onSubmit={(data) =>
+          void props.onSubmit({
             stackName: props.stackName,
             displayName: data.displayName,
             description: data.description,
@@ -35,7 +50,8 @@ export const ServiceForm = Shade<ServiceFormProps>({
             autoFetchIntervalMinutes: parseInt(data.autoFetchIntervalMinutes, 10) || 60,
             autoRestartOnFetch: data.autoRestartOnFetch === 'on',
           })
-        }}
+        }
+        style={{ display: 'flex', flexDirection: 'column', gap: '16px', maxWidth: '600px' }}
       >
         <h2 style={{ margin: '0' }}>{props.mode === 'create' ? 'Create Service' : 'Edit Service'}</h2>
 
@@ -100,10 +116,11 @@ export const ServiceForm = Shade<ServiceFormProps>({
         />
         <h4 style={{ margin: '0', opacity: '0.7' }}>Configuration</h4>
         <div style={{ display: 'flex', gap: '16px', alignItems: 'center' }}>
-          <label style={{ display: 'flex', alignItems: 'center', gap: '6px' }}>
-            <input type="checkbox" name="autoFetchEnabled" checked={props.initial?.autoFetchEnabled ?? false} />
-            Auto-fetch
-          </label>
+          <Checkbox
+            name="autoFetchEnabled"
+            labelTitle="Auto-fetch"
+            checked={props.initial?.autoFetchEnabled ?? false}
+          />
           <Input
             name="autoFetchIntervalMinutes"
             labelTitle="Fetch interval (min)"
@@ -112,10 +129,11 @@ export const ServiceForm = Shade<ServiceFormProps>({
             value={String(props.initial?.autoFetchIntervalMinutes ?? 60)}
             style={{ width: '150px' }}
           />
-          <label style={{ display: 'flex', alignItems: 'center', gap: '6px' }}>
-            <input type="checkbox" name="autoRestartOnFetch" checked={props.initial?.autoRestartOnFetch ?? false} />
-            Auto-restart on fetch
-          </label>
+          <Checkbox
+            name="autoRestartOnFetch"
+            labelTitle="Auto-restart on fetch"
+            checked={props.initial?.autoRestartOnFetch ?? false}
+          />
         </div>
         <div style={{ display: 'flex', gap: '8px', justifyContent: 'flex-end' }}>
           {props.cancelHref ? (
@@ -131,7 +149,7 @@ export const ServiceForm = Shade<ServiceFormProps>({
             {props.mode === 'create' ? 'Create' : 'Save'}
           </Button>
         </div>
-      </form>
+      </Form>
     )
   },
 })

frontend/src/components/entity-forms/stack-form.tsx

@@ -1,7 +1,19 @@
 import { createComponent, NestedRouteLink, Shade } from '@furystack/shades'
-import { Button, Input } from '@furystack/shades-common-components'
+import { Button, Form, Input } from '@furystack/shades-common-components'
 import type { StackView } from 'common'
 
+type StackFormPayload = {
+  name: string
+  displayName: string
+  description: string
+  mainDirectory: string
+}
+
+const isStackFormPayload = (data: unknown): data is StackFormPayload => {
+  const d = data as StackFormPayload
+  return d.name?.length > 0 && d.displayName?.length > 0 && d.mainDirectory?.length > 0
+}
+
 type StackFormProps = {
   initial?: Partial<StackView>
   onSubmit: (data: Partial<StackView>) => void | Promise<void>
@@ -14,19 +26,17 @@ export const StackForm = Shade<StackFormProps>({
   shadowDomName: 'shade-stack-form',
   render: ({ props }) => {
     return (
-      <form
-        style={{ display: 'flex', flexDirection: 'column', gap: '16px', maxWidth: '600px' }}
-        onsubmit={async (ev) => {
-          ev.preventDefault()
-          const formData = new FormData(ev.target as HTMLFormElement)
-          const data = Object.fromEntries(formData.entries()) as Record<string, string>
-          await props.onSubmit({
+      <Form<StackFormPayload>
+        validate={isStackFormPayload}
+        onSubmit={(data) =>
+          void props.onSubmit({
             name: data.name,
             displayName: data.displayName,
             description: data.description,
             mainDirectory: data.mainDirectory,
           })
-        }}
+        }
+        style={{ display: 'flex', flexDirection: 'column', gap: '16px', maxWidth: '600px' }}
       >
         <h2 style={{ margin: '0' }}>{props.mode === 'create' ? 'Create Stack' : 'Edit Stack'}</h2>
 
@@ -77,7 +87,7 @@ export const StackForm = Shade<StackFormProps>({
             {props.mode === 'create' ? 'Create' : 'Save'}
           </Button>
         </div>
-      </form>
+      </Form>
     )
   },
 })