@synetics/ui 0.7.0-alpha

package/src/showcase/forms/components/field-state-demo.syn

@@ -0,0 +1,70 @@
+/**
+ * Field State Demo
+ * form.observe() → reactive isDirty / getData() snapshot
+ * Uses FormProvider + TextField — state tracked via form.observe() API
+ */
+
+import { createSignal, createEffect, onCleanup } from '@synetics/synetics.dev';
+import { createForm, f } from '@synetics/formular.dev';
+import type { IFormular } from '@synetics/formular.dev';
+import { FormProvider, TextField } from '@/components/formular';
+
+export component FieldStateDemo() {
+  const [form, setForm] = createSignal<IFormular<{ nickname: string; bio: string }> | null>(null);
+
+  createForm({
+    schema: f.object({
+      nickname: f.string().min(2).max(30).nonempty().debounce(200),
+      bio: f.string().max(160).optional().debounce(200),
+    }),
+    defaultValues: { nickname: '', bio: '' },
+  }).then(setForm);
+
+  const [snapshot, setSnapshot] = createSignal<Record<string, unknown>>({});
+  const [isDirty, setIsDirty] = createSignal(false);
+
+  let unsub: (() => void) | undefined;
+
+  createEffect(() => {
+    unsub?.();
+    const currentForm = form();
+    if (!currentForm) return;
+    unsub = currentForm.observe(undefined, () => {
+      setSnapshot(currentForm.getData());
+      setIsDirty(currentForm.getFormFlags().isDirty ?? false);
+    });
+  });
+
+  onCleanup(() => {
+    unsub?.();
+    form()?.clear();
+  });
+
+  return (
+    <div class="demo-card">
+      <h3 class="demo-title">3️⃣ form.observe() + getData()</h3>
+      <p class="demo-desc">
+        <code>form.observe(undefined, cb)</code> fires on any change.
+        <code>form.getData()</code> + <code>form.getFormFlags().isDirty</code> for reactive snapshot.
+      </p>
+
+      {!form() ? (
+        <p class="status-loading">⏳ Initialising form engine…</p>
+      ) : (
+        <FormProvider form={form()!} onSaveCallback={() => {}} onQuitCallback={() => {}}>
+          <TextField name="nickname" label="Nickname (2–30)" showErrors={true} showGuides={true} />
+          <TextField name="bio" label="Bio (max 160)" showErrors={true} showGuides={true} />
+
+          <div class="state-panel">
+            <span class={`badge ${isDirty() ? 'badge--on' : 'badge--off'}`}>
+              {isDirty() ? '✏️ dirty' : '✔ pristine'}
+            </span>
+            {Object.keys(snapshot()).length > 0 ? (
+              <pre class="result-pre">{JSON.stringify(snapshot(), null, 2)}</pre>
+            ) : null}
+          </div>
+        </FormProvider>
+      )}
+    </div>
+  );
+}

package/src/showcase/forms/components/index.ts

@@ -0,0 +1,9 @@
+/**
+ * Forms Components Index
+ */
+
+export { AsyncValidationDemo } from './async-validation-demo.syn';
+export { BasicFormDemo } from './basic-form-demo.syn';
+export { FieldStateDemo } from './field-state-demo.syn';
+export { SubmissionDemo } from './submission-demo.syn';
+export { ValidationDemo } from './validation-demo.syn';

package/src/showcase/forms/components/submission-demo.syn

@@ -0,0 +1,78 @@
+/**
+ * Submission Demo
+ * form.submit() → onSubmit async → onSuccess / onError lifecycle
+ * Uses FormProvider + TextField — FInputField handles all DOM binding via field.register() + field.ref()
+ */
+
+import { createSignal, onCleanup } from '@synetics/synetics.dev';
+import { createForm, f } from '@synetics/formular.dev';
+import type { IFormular } from '@synetics/formular.dev';
+import { FormProvider, TextField } from '@/components/formular';
+
+type SubmitStatus = 'idle' | 'submitting' | 'success' | 'error';
+
+export component SubmissionDemo() {
+  const [status, setStatus] = createSignal<SubmitStatus>('idle');
+  const [submitResult, setSubmitResult] = createSignal('');
+
+  const [form, setForm] = createSignal<IFormular<{ firstName: string; lastName: string }> | null>(null);
+
+  createForm({
+    schema: f.object({
+      firstName: f.string().min(1).nonempty().debounce(200),
+      lastName: f.string().min(1).nonempty().debounce(200),
+    }),
+    defaultValues: { firstName: '', lastName: '' },
+    onSubmit: async (data) => {
+      setStatus('submitting');
+      await new Promise<void>((resolve) => setTimeout(resolve, 800));
+      return data;
+    },
+    onSuccess: (data) => {
+      setSubmitResult(JSON.stringify(data, null, 2));
+      setStatus('success');
+    },
+    onError: (err) => {
+      setSubmitResult(String(err));
+      setStatus('error');
+    },
+  }).then(setForm);
+
+  onCleanup(() => form()?.clear());
+
+  const statusColor = () => {
+    const s = status();
+    if (s === 'success') return 'status--success';
+    if (s === 'error') return 'status--error';
+    if (s === 'submitting') return 'status--loading';
+    return '';
+  };
+
+  return (
+    <div class="demo-card">
+      <h3 class="demo-title">4️⃣ Submit Lifecycle</h3>
+      <p class="demo-desc">
+        <code>form.submit()</code> → validates → <code>onSubmit</code> async → <code>onSuccess</code> / <code>onError</code>.
+        All field binding via <code>field.register()</code> + <code>field.ref()</code> inside <code>FInputField</code>.
+      </p>
+
+      {!form() ? (
+        <p class="status-loading">⏳ Initialising form engine…</p>
+      ) : (
+        <FormProvider form={form()!} onSaveCallback={() => setSubmitResult('')} onQuitCallback={() => { setStatus('idle'); setSubmitResult(''); }}>
+          <TextField name="firstName" label="First Name" showErrors={true} showGuides={true} />
+          <TextField name="lastName" label="Last Name" showErrors={true} showGuides={true} />
+
+          {status() !== 'idle' ? (
+            <div class={`submit-status ${statusColor()}`}>
+              <strong>{status().toUpperCase()}</strong>
+              {submitResult() ? (
+                <pre class="result-pre">{submitResult()}</pre>
+              ) : null}
+            </div>
+          ) : null}
+        </FormProvider>
+      )}
+    </div>
+  );
+}

package/src/showcase/forms/components/validation-demo.syn

@@ -0,0 +1,59 @@
+/**
+ * Validation Demo
+ * Schema validators (min/email/number range) — FieldValidation auto-rendered inside TextField
+ */
+
+import { createSignal, onCleanup } from '@synetics/synetics.dev';
+import { createForm, f } from '@synetics/formular.dev';
+import type { IFormular } from '@synetics/formular.dev';
+import { FormProvider, TextField } from '@/components/formular';
+
+export component ValidationDemo() {
+  const [form, setForm] = createSignal<IFormular<{ password: string; age: number }> | null>(null);
+
+  createForm({
+    schema: f.object({
+      password: f.string().min(8).nonempty().debounce(200),
+      age: f.number().min(18).max(120),
+    }),
+    defaultValues: { password: '', age: 0 },
+  }).then(setForm);
+
+  onCleanup(() => form()?.clear());
+
+  const [isValid, setIsValid] = createSignal<boolean | null>(null);
+
+  const handleValidateAll = async () => {
+    const result = await form()?.validateForm();
+    setIsValid(result ?? false);
+  };
+
+  return (
+    <div class="demo-card">
+      <h3 class="demo-title">2️⃣ Schema Validators</h3>
+      <p class="demo-desc">
+        <code>f.string().min(8)</code> / <code>f.number().min(18).max(120)</code>.
+        <code>FieldValidation</code> auto-rendered inside <code>TextField</code>. Debounce: 200ms.
+      </p>
+
+      {!form() ? (
+        <p class="status-loading">⏳ Initialising form engine…</p>
+      ) : (
+        <FormProvider form={form()!} onSaveCallback={() => {}} onQuitCallback={() => {}}>
+          <TextField name="password" label="Password (min 8 chars)" showErrors={true} showGuides={true} />
+          <TextField name="age" label="Age (18–120)" showErrors={true} showGuides={true} />
+
+          <button class="submit-btn" onClick={handleValidateAll}>
+            🔍 Validate All
+          </button>
+
+          {isValid() !== null ? (
+            <p class={isValid() ? 'status-ok' : 'status-fail'}>
+              {isValid() ? '✅ All fields valid' : '❌ Form has errors'}
+            </p>
+          ) : null}
+        </FormProvider>
+      )}
+    </div>
+  );
+}

package/src/showcase/forms/forms-test.syn

@@ -0,0 +1,179 @@
+/**
+ * P1-01 Forms Showcase — step 3: submit lifecycle
+ *  Step 1 ✓  fields render, errors on blur
+ *  Step 2 ✓  live isDirty / isValid badges + getData() snapshot
+ *  Step 3 ✓  Submit button → validate → onSubmit → success/error status
+ *
+ * Architecture note: formular.dev v simple-api.ts
+ *  simple-api.ts#schemaToDescriptors sets validationOptions:{} (does not bridge
+ *  schema _refinements to IValidationOptions), so form.submit() always passes
+ *  hasValidationOptions check.  We compensate by per-field safeParse on
+ *  demoSchema.shape.* inside onSubmit — if invalid, throws → DirectSubmissionStrategy
+ *  re-throws → showcase catch → failure banner.
+ */
+
+import { createSignal, onCleanup, useSync } from '@synetics/synetics.dev';
+import { createForm, f } from '@synetics/formular.dev';
+import type { IFormular } from '@synetics/formular.dev';
+import { PageHeader } from '../common/components/page-header.syn';
+import { FormProvider, TextField } from '@/components/formular';
+
+type FormData = { username: string; email: string };
+
+/** Keep schema reference so we can safeParse inside onSubmit */
+const demoSchema = f.object({
+  username: f.string().min(3).max(20).nonempty().debounce(200),
+  email:    f.string().email().nonempty().debounce(200),
+});
+
+/**
+ * FormStatePanel — mounts only after form is ready, safe to subscribe.
+ * Subscribes to every field observer channel so formular.dev mutations
+ * flow into Pulsar signals.
+ * isValid uses schema.safeParse (per-field) — same gate as onSubmit — so badge
+ * and submit ALWAYS agree regardless of internal field.input.isValid state.
+ */
+export component FormStatePanel({ form, schema }: { form: IFormular<FormData>; schema: any }) {
+  // Subscribe via notifiers bus (accept/dismiss) — NOT observers bus.
+  // debounceNotify('onUiUpdate') fires on every value change and after validation.
+  // Key per field: "${fieldName}.form-panel.sync" — must be unique.
+  const state = useSync(
+    (notify) => {
+      const notifiers = (form as any).fields.map((field: any) => {
+        const nm = field.input.notificationManager;
+        const n = {
+          event: {
+            types: ['onUiUpdate'],
+            target: `${field.input.name}.form-panel`,
+            action: 'sync',
+            emitterName: 'form-panel',
+            name: field.input.name,
+            toFlags: () => ''
+          },
+          method: () => notify()
+        };
+        nm.accept(n);
+        return () => nm.dismiss(n);
+      });
+      return () => notifiers.forEach((u: any) => u());
+    },
+    () => ({
+      // isDirty: read per-field — form.isDirty requires checkChanges() explicitly
+      isDirty: (form as any).fields.some((f: any) => f.input.isDirty),
+      // isValid: use schema.safeParse per field — same gate as onSubmit — guarantees
+      // badge and submit always agree regardless of internal validation engine state.
+      isValid: (() => {
+        const s = schema as any;
+        const fields = (form as any).fields as any[];
+        return fields.every((f: any) => {
+          const fieldSchema = s.shape?.[f.input.name];
+          return fieldSchema ? fieldSchema.safeParse(f.input.value ?? '').success : true;
+        });
+      })(),
+    })
+  );
+
+  const [snapshot, setSnapshot] = createSignal('');
+  const [submitResult, setSubmitResult] = createSignal<{ ok: boolean; msg: string } | null>(null);
+
+  return (
+    <div class="demo-card" style="margin-top:1rem;padding:1rem">
+      <h3 style="font-weight:600;margin-bottom:.5rem">Form state</h3>
+      <div style="display:flex;gap:.5rem;margin-bottom:.75rem">
+        <span style={() => `padding:2px 8px;border-radius:4px;font-size:.8rem;font-weight:600;${state().isDirty ? 'background:#fef3c7;color:#92400e' : 'background:#f3f4f6;color:#6b7280'}`}>
+          {() => state().isDirty ? '✎ dirty' : '○ pristine'}
+        </span>
+        <span style={() => `padding:2px 8px;border-radius:4px;font-size:.8rem;font-weight:600;${state().isValid ? 'background:#d1fae5;color:#065f46' : 'background:#fee2e2;color:#991b1b'}`}>
+          {() => state().isValid ? '✓ valid' : '✗ invalid'}
+        </span>
+      </div>
+      <div style="display:flex;gap:.5rem;margin-bottom:.5rem">
+        <button
+          style="padding:4px 12px;background:#3b82f6;color:#fff;border-radius:4px;font-size:.8rem;cursor:pointer"
+          onclick={() => setSnapshot(JSON.stringify((form as any).getData?.() ?? {}, null, 2))}
+        >
+          getData()
+        </button>
+        <button
+          style="padding:4px 12px;background:#7c3aed;color:#fff;border-radius:4px;font-size:.8rem;cursor:pointer"
+          onclick={async () => {
+            setSubmitResult(null);
+            try {
+              const result = await (form as any).submit();
+              if (result === null || result === undefined) {
+                setSubmitResult({ ok: false, msg: 'Validation failed — fix errors above.' });
+              } else {
+                setSubmitResult({ ok: true, msg: JSON.stringify(result, null, 2) });
+              }
+            } catch (e: any) {
+              setSubmitResult({ ok: false, msg: String(e?.message ?? e) });
+            }
+          }}
+        >
+          submit()
+        </button>
+      </div>
+      {() => submitResult()
+        ? (
+            <div style={() => `margin-top:.5rem;padding:.5rem;border-radius:4px;font-size:.8rem;border:1px solid ${submitResult()!.ok ? '#6ee7b7' : '#fca5a5'};background:${submitResult()!.ok ? '#ecfdf5' : '#fff1f2'};color:${submitResult()!.ok ? '#065f46' : '#9f1239'}`}>
+              <strong>{() => submitResult()!.ok ? '✓ submit() succeeded' : '✗ submit() failed'}</strong>
+              {() => submitResult()!.ok
+                ? <pre style="margin-top:.25rem;font-size:.75rem;overflow:auto;background:transparent">{() => submitResult()!.msg}</pre>
+                : <p style="margin-top:.25rem">{() => submitResult()!.msg}</p>
+              }
+            </div>
+          )
+        : null
+      }
+      {() => snapshot()
+        ? <pre style="margin-top:.5rem;font-size:.75rem;background:#f8fafc;padding:.5rem;border-radius:4px;overflow:auto">{() => snapshot()}</pre>
+        : null
+      }
+    </div>
+  );
+};
+
+export component FormsTestPage() {
+  const [form, setForm] = createSignal<IFormular<FormData> | null>(null);
+
+  createForm<FormData>({
+    schema: demoSchema,
+    defaultValues: { username: '', email: '' },
+    onSubmit: async (data: FormData) => {
+      // Step 3 proof: bridges the simple-api.ts validation gap.
+      // ObjectSchema has no _parse, so use per-field safeParse from shape.
+      const s = demoSchema as any;
+      const uR = s.shape.username.safeParse(data.username);
+      const eR = s.shape.email.safeParse(data.email);
+      if (!uR.success) throw new Error(uR.error?.message ?? 'username: invalid');
+      if (!eR.success) throw new Error(eR.error?.message ?? 'email: invalid');
+      console.info('[forms-demo] onSubmit:', data);
+    },
+  }).then(setForm);
+
+  onCleanup(() => form()?.clear());
+
+  return (
+    <div>
+      <PageHeader
+        title="Forms — binding proof"
+        emoji="📋"
+        description="Type, blur — errors appear below inputs. State badges update live."
+      />
+
+      {!form() ? (
+        <p class="status-loading">⏳ Initialising form…</p>
+      ) : (
+        <div>
+          <div class="demo-card">
+            <FormProvider form={form()!} onSaveCallback={() => {}} onQuitCallback={() => {}}>
+              <TextField name="username" label="Username (3–20 chars)" showErrors={true} showGuides={true} />
+              <TextField name="email"    label="Email"                 showErrors={true} showGuides={true} />
+            </FormProvider>
+          </div>
+          <FormStatePanel form={form()!} schema={demoSchema} />
+        </div>
+      )}
+    </div>
+  );
+}

package/src/showcase/forms/pages/cross-validation-page.syn

@@ -0,0 +1,181 @@
+/**
+ * Forms Demo — Cross-field Validation
+ * Demonstrates: password + confirmPassword must match.
+ *
+ * Two approaches shown side-by-side:
+ *
+ * 1. LIVE cross-check via form.observe('confirmPassword', cb)
+ *    Compares confirmPassword to password on every keystroke (after debounce).
+ *    Produces a reactive error message without touching the formular validation engine.
+ *
+ * 2. SUBMIT-TIME cross-check in onSubmit handler
+ *    Schema-level refine() does NOT bridge to live field validation (known limitation
+ *    of simple-api.ts schemaToDescriptors which ignores _refinements). The check
+ *    is therefore enforced in onSubmit using schema.safeParse.
+ *
+ * This page intentionally exposes the gap so the pattern is clearly documented.
+ */
+
+import { createSignal, createEffect, onCleanup } from '@synetics/synetics.dev';
+import { createForm, f } from '@synetics/formular.dev';
+import type { IExtendedInput, IFormular } from '@synetics/formular.dev';
+import { PageHeader } from '../../common/components/page-header.syn';
+import { FormProvider, TextField } from '@/components/formular';
+
+type CrossValidationData = {
+  password:        string;
+  confirmPassword: string;
+};
+
+type SubmitStatus = 'idle' | 'submitting' | 'success' | 'error';
+
+const crossSchema = f.object({
+  password:        f.string().min(8).nonempty().debounce(200),
+  confirmPassword: f.string().min(8).nonempty().debounce(200),
+});
+
+export component CrossValidationPage() {
+  const [form, setForm] = createSignal<IFormular<CrossValidationData> | null>(null);
+
+  /** Live match signal — driven by form.observe('confirmPassword') */
+  const [matchError, setMatchError]     = createSignal<string | null>(null);
+  const [matchOk, setMatchOk]           = createSignal(false);
+  const [submitStatus, setSubmitStatus] = createSignal<SubmitStatus>('idle');
+  const [submitError, setSubmitError]   = createSignal<string | null>(null);
+
+  createForm<CrossValidationData>({
+    schema: crossSchema,
+    defaultValues: { password: '', confirmPassword: '' },
+    onSubmit: async (data: CrossValidationData) => {
+      // submit-time cross-field enforcement
+      if (data.password !== data.confirmPassword) {
+        throw new Error('Passwords do not match.');
+      }
+      setSubmitStatus('submitting');
+      await new Promise<void>((resolve) => setTimeout(resolve, 500));
+      return data;
+    },
+    onSuccess: () => {
+      setSubmitStatus('success');
+      setSubmitError(null);
+    },
+    onError: (err: Error) => {
+      setSubmitStatus('error');
+      setSubmitError(err.message);
+    },
+  }).then(setForm);
+
+  onCleanup(() => form()?.clear());
+
+  /**
+   * Live cross-field observer.
+   * Watches BOTH fields; compares values on every update.
+   * This fires after debounce(200) settles on either field.
+   */
+  createEffect(() => {
+    const f = form();
+    if (!f) return;
+
+    const check = () => {
+      const pwdField:  IExtendedInput | undefined = f.getField('password');
+      const confField: IExtendedInput | undefined = f.getField('confirmPassword');
+      const pwd  = String(pwdField?.value  ?? '');
+      const conf = String(confField?.value ?? '');
+
+      if (!conf) {
+        setMatchError(null);
+        setMatchOk(false);
+        return;
+      }
+      if (pwd === conf) {
+        setMatchError(null);
+        setMatchOk(true);
+      } else {
+        setMatchError('Passwords do not match.');
+        setMatchOk(false);
+      }
+    };
+
+    // onCleanup() is forbidden inside createEffect re-runs (requires component
+    // render context). Component-level onCleanup calls form.clear() on unmount,
+    // which disposes all observers automatically.
+    f.observe('password', check);
+    f.observe('confirmPassword', check);
+  });
+
+  const handleSubmit = async () => {
+    const f = form();
+    if (!f) return;
+    setSubmitStatus('idle');
+    setSubmitError(null);
+    await f.submit();
+  };
+
+  return (
+    <div>
+      <PageHeader
+        title="Cross-field Validation"
+        emoji="🔐"
+        color="#ef4444"
+        description="Password + confirm must match. Live check via form.observe(); submit-time enforcement in onSubmit."
+      />
+
+      {!form() ? (
+        <p class="status-loading">⏳ Initialising form…</p>
+      ) : (
+        <FormProvider form={form()!} onSaveCallback={() => {}} onQuitCallback={() => {}}>
+          <div class="demo-card">
+
+            <div class="demo-banner demo-banner--warn" style="margin-top:0;margin-bottom:1rem">
+              <strong>⚠️ Architecture note:</strong>{' '}
+              <code>f.object().refine()</code> is not bridged by <code>schemaToDescriptors</code>
+              to live field validation. Cross-field rules must be enforced via{' '}
+              <code>form.observe()</code> (live) and <code>onSubmit</code> (submit-time).
+            </div>
+
+            <div style="display:flex;flex-direction:column;gap:.75rem">
+              <TextField name="password"        label="Password (min 8)" showErrors showGuides />
+              <TextField name="confirmPassword" label="Confirm Password"  showErrors showGuides />
+            </div>
+
+            {/* Live match feedback */}
+            {() => matchError() ? (
+              <p class="demo-banner demo-banner--error" style="margin-top:.5rem;padding:.5rem">
+                🔴 {() => matchError()}
+              </p>
+            ) : null}
+
+            {() => matchOk() ? (
+              <p class="demo-banner demo-banner--success" style="margin-top:.5rem;padding:.5rem">
+                🟢 Passwords match
+              </p>
+            ) : null}
+
+            <button
+              type="button"
+              class={() => `btn-demo btn-demo--danger${!matchOk() ? ' btn-demo--disabled' : ''}`}
+              style="margin-top:1rem"
+              onclick={handleSubmit}
+              disabled={() => !matchOk()}
+            >
+              {() => submitStatus() === 'submitting' ? '⏳ Changing password…' : '🔐 Change Password'}
+            </button>
+
+            {() => submitStatus() === 'success' ? (
+              <div class="demo-banner demo-banner--success">
+                <strong>✓ Password changed successfully.</strong>
+              </div>
+            ) : null}
+
+            {() => submitStatus() === 'error' && submitError() ? (
+              <div class="demo-banner demo-banner--error">
+                <strong>✗ {() => submitError()}</strong>
+              </div>
+            ) : null}
+
+          </div>
+        </FormProvider>
+      )}
+    </div>
+  );
+}