@synetics/ui 0.7.0-alpha

package/src/showcase/forms/pages/dependent-fields-page.syn

@@ -0,0 +1,122 @@
+/**
+ * Forms Demo — Dependent / Conditional Fields
+ * Demonstrates: form.observe() driving show/hide of a downstream field.
+ *
+ * When country === 'us', a US-state SelectField appears.
+ * When country changes away from 'us', the state field clears and hides.
+ *
+ * Pattern:
+ *   createEffect → form.observe('country', cb) → setShowState(...)
+ *   <Show when={showState}> wraps the dependent field.
+ */
+
+import { createSignal, createEffect, onCleanup } from '@synetics/synetics.dev';
+import { createForm, f } from '@synetics/formular.dev';
+import type { IExtendedInput, IFormular, IOptionItem } from '@synetics/formular.dev';
+import { PageHeader } from '../../common/components/page-header.syn';
+import { FormProvider, SelectField, TextField } from '@/components/formular';
+
+type DependentData = {
+  country: string;
+  state:   string;
+};
+
+const COUNTRY_OPTIONS: IOptionItem[] = [
+  { value: '',   label: '— Select a country —' },
+  { value: 'us', label: 'United States' },
+  { value: 'uk', label: 'United Kingdom' },
+  { value: 'ca', label: 'Canada' },
+  { value: 'au', label: 'Australia' },
+];
+
+const US_STATE_OPTIONS: IOptionItem[] = [
+  { value: '',   label: '— Select a state —' },
+  { value: 'ca', label: 'California' },
+  { value: 'ny', label: 'New York' },
+  { value: 'tx', label: 'Texas' },
+  { value: 'fl', label: 'Florida' },
+  { value: 'wa', label: 'Washington' },
+];
+
+export component DependentFieldsPage() {
+  const [form, setForm] = createSignal<IFormular<DependentData> | null>(null);
+  const [showState, setShowState] = createSignal(false);
+
+  createForm<DependentData>({
+    schema: f.object({
+      country: f.string().nonempty().debounce(200),
+      state:   f.string().optional().debounce(200),
+    }),
+    defaultValues: { country: '', state: '' },
+  }).then((resolved: IFormular<DependentData>) => {
+    const countryField: IExtendedInput | undefined = resolved.getField('country');
+    if (countryField) countryField.options = COUNTRY_OPTIONS;
+
+    const stateField: IExtendedInput | undefined = resolved.getField('state');
+    if (stateField) stateField.options = US_STATE_OPTIONS;
+
+    setForm(resolved);
+  });
+
+  onCleanup(() => form()?.clear());
+
+  // Wire observer once form is ready.
+  createEffect(() => {
+    const f = form();
+    if (!f) return;
+
+    // onCleanup() is forbidden inside createEffect re-runs (Pulsar lifecycle-hooks
+    // requires component render context). The component-level onCleanup above calls
+    // form.clear(), which disposes all observers when the page unmounts.
+    f.observe('country', () => {
+      const countryField: IExtendedInput | undefined = f.getField('country');
+      const val = String(countryField?.value ?? '');
+      const isUs = val === 'us';
+      setShowState(isUs);
+
+      // Clear state when country changes away from US.
+      if (!isUs) {
+        // field.setValue lives on IInputBase (field.input), not IExtendedInput directly.
+        const stateField: IExtendedInput | undefined = f.getField('state');
+        stateField?.input.setValue('');
+      }
+    });
+  });
+
+  return (
+    <div>
+      <PageHeader
+        title="Dependent / Conditional Fields"
+        emoji="🔗"
+        color="#10b981"
+        description="form.observe('country', cb) → shows a US-state picker only when country is 'United States'."
+      />
+
+      {!form() ? (
+        <p class="status-loading">⏳ Initialising form…</p>
+      ) : (
+        <FormProvider form={form()!} onSaveCallback={() => {}} onQuitCallback={() => {}}>
+          <div class="demo-card">
+            <p class="demo-desc">
+              Select <strong>United States</strong> to reveal the state picker.
+              Changing to any other country clears and hides it.
+            </p>
+
+            <div style="display:flex;flex-direction:column;gap:1rem">
+              <SelectField name="country" />
+
+              {showState() ? (
+                <div class="demo-revealed">
+                  <p class="demo-revealed__note">
+                    🗺️ US state revealed by <code>form.observe('country', cb)</code>
+                  </p>
+                  <SelectField name="state" />
+                </div>
+              ) : null}
+            </div>
+          </div>
+        </FormProvider>
+      )}
+    </div>
+  );
+}

package/src/showcase/forms/pages/dynamic-fields-page.syn

@@ -0,0 +1,245 @@
+/**
+ * Forms Demo — Dynamic Field Array
+ * Demonstrates: pre-created field slots with show/hide via count signal.
+ *
+ * Approach: formular does not natively support runtime field creation, so we
+ * pre-create N slots (MAX_EMAILS = 5) and reveal them one at a time.
+ * This models the most common real-world pattern: bounded dynamic lists.
+ *
+ * A `count` signal drives which slots are visible.
+ * "Add email" increments count (up to MAX_EMAILS).
+ * "Remove last" decrements count and clears the vacated slot.
+ *
+ * On submit: only the first `count` slots are included via getData() slice.
+ *
+ * Schema note: optional slots use plain f.string() (no .email() validator).
+ * Live email validation on `''` would fail the regex immediately when a slot
+ * is revealed or after removeLast clears it. Email format is checked in
+ * handleSubmit after extracting the visible values.
+ */
+
+import { createSignal, 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 DynamicEmailsData = {
+  email0: string;
+  email1: string;
+  email2: string;
+  email3: string;
+  email4: string;
+};
+
+const MAX_EMAILS = 5;
+
+const FIELD_KEYS: ReadonlyArray<keyof DynamicEmailsData> = [
+  'email0',
+  'email1',
+  'email2',
+  'email3',
+  'email4',
+];
+
+// Simple email regex used for submit-time format checking only.
+// Optional slots use f.string() (no live .email() validator) to avoid
+// 'invalid email' errors appearing on empty values.
+const EMAIL_RE = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
+
+type SubmitStatus = 'idle' | 'success' | 'error';
+
+export component DynamicFieldsPage() {
+  const [form, setForm] = createSignal<IFormular<DynamicEmailsData> | null>(null);
+  const [count, setCount]               = createSignal<number>(1);
+  const [submitStatus, setSubmitStatus] = createSignal<SubmitStatus>('idle');
+  const [submitted, setSubmitted]       = createSignal<string[]>([]);
+  const [formatError, setFormatError]   = createSignal<string | null>(null);
+
+  createForm<DynamicEmailsData>({
+    schema: f.object({
+      // email0 is always visible — full live validation.
+      email0: f.string().email().nonempty().debounce(200),
+      // Slots 1-4 are optional. Using plain f.string() avoids the email regex
+      // firing on '' when a slot is first revealed or just cleared by removeLast.
+      // Format is enforced in handleSubmit.
+      email1: f.string().debounce(200),
+      email2: f.string().debounce(200),
+      email3: f.string().debounce(200),
+      email4: f.string().debounce(200),
+    }),
+    defaultValues: { email0: '', email1: '', email2: '', email3: '', email4: '' },
+  }).then(setForm);
+
+  onCleanup(() => form()?.clear());
+
+  const addEmail = () => {
+    setCount((c) => Math.min(c + 1, MAX_EMAILS));
+    setSubmitStatus('idle');
+    setFormatError(null);
+  };
+
+  const removeLast = () => {
+    const c = count();
+    if (c <= 1) return;
+    // Decrement first so the slot is hidden before setValue fires.
+    // This prevents the now-hidden field from briefly showing a validation error
+    // in response to being cleared.
+    setCount((prev) => Math.max(prev - 1, 1));
+    const f = form();
+    if (f) {
+      // field.clear() does not exist on IExtendedInput — clear() lives on IInputBase
+      // (field.input.clear()) or on IFormular (f.clearField). Use clearField via the form.
+      const key: keyof DynamicEmailsData = FIELD_KEYS[c - 1];
+      f.clearField(String(key));
+    }
+    setSubmitStatus('idle');
+    setFormatError(null);
+  };
+
+  const handleSubmit = async () => {
+    const f = form();
+    if (!f) return;
+
+    setFormatError(null);
+
+    // Only validate the visible email0 slot via formular (it has live validators).
+    // Slots 1-4 use plain f.string() so validateForm() has nothing to fire on them.
+    await f.validateForm();
+    const email0Field: IExtendedInput | undefined = f.getField('email0');
+    if (!email0Field?.input.isValid) {
+      setSubmitStatus('error');
+      return;
+    }
+
+    const data = f.getData() as Record<keyof DynamicEmailsData, unknown>;
+    const visibleKeys = FIELD_KEYS.slice(0, count());
+    const emails = visibleKeys
+      .map((key) => String(data[key] ?? '').trim())
+      .filter(Boolean);
+
+    // Submit-time email format check for optional slots (1-4).
+    const badIdx = emails.findIndex((e, i) => i > 0 && !EMAIL_RE.test(e));
+    if (badIdx !== -1) {
+      setFormatError(`Email ${badIdx + 1}: "${emails[badIdx]}" is not a valid email address.`);
+      setSubmitStatus('error');
+      return;
+    }
+
+    setSubmitted(emails);
+    setSubmitStatus('success');
+  };
+
+  return (
+    <div>
+      <PageHeader
+        title="Dynamic Field Array"
+        emoji="➕"
+        color="#f59e0b"
+        description="Pre-created slots (5 max) revealed one-by-one. Demonstrates bounded dynamic lists with formular."
+      />
+
+      {!form() ? (
+        <p class="status-loading">⏳ Initialising form…</p>
+      ) : (
+        <FormProvider form={form()!} onSaveCallback={() => {}} onQuitCallback={() => {}}>
+          <div class="demo-card">
+            <p class="demo-desc">
+              Formular manages a fixed set of <code>email0…email4</code> fields. Only
+              the first <strong>{() => String(count())}</strong> slot(s) are active and validated.
+            </p>
+
+            <div style="display:flex;flex-direction:column;gap:.75rem">
+              {/* Slot 0 — always visible */}
+              <div style="display:flex;align-items:flex-start;gap:.5rem">
+                <div style="flex:1">
+                  <TextField name="email0" label="Email 1" showErrors showGuides />
+                </div>
+              </div>
+
+              {/* Slot 1 */}
+              {() => count() > 1 ? (
+                <div style="display:flex;align-items:flex-start;gap:.5rem">
+                  <div style="flex:1">
+                    <TextField name="email1" label="Email 2" showErrors showGuides />
+                  </div>
+                </div>
+              ) : null}
+
+              {/* Slot 2 */}
+              {() => count() > 2 ? (
+                <div style="display:flex;align-items:flex-start;gap:.5rem">
+                  <div style="flex:1">
+                    <TextField name="email2" label="Email 3" showErrors showGuides />
+                  </div>
+                </div>
+              ) : null}
+
+              {/* Slot 3 */}
+              {() => count() > 3 ? (
+                <div style="display:flex;align-items:flex-start;gap:.5rem">
+                  <div style="flex:1">
+                    <TextField name="email3" label="Email 4" showErrors showGuides />
+                  </div>
+                </div>
+              ) : null}
+
+              {/* Slot 4 */}
+              {() => count() > 4 ? (
+                <div style="display:flex;align-items:flex-start;gap:.5rem">
+                  <div style="flex:1">
+                    <TextField name="email4" label="Email 5" showErrors showGuides />
+                  </div>
+                </div>
+              ) : null}
+            </div>
+
+            {/* Controls */}
+            <div style="display:flex;gap:.5rem;margin-top:1rem;flex-wrap:wrap">
+              <button
+                type="button"
+                class="btn-demo btn-demo--success btn-demo--sm"
+                onclick={addEmail}
+                disabled={() => count() >= MAX_EMAILS}
+              >
+                + Add email
+              </button>
+
+              <button
+                type="button"
+                class="btn-demo btn-demo--danger btn-demo--sm"
+                onclick={removeLast}
+                disabled={() => count() <= 1}
+              >
+                − Remove last
+              </button>
+
+              <button type="button" class="btn-demo btn-demo--primary btn-demo--sm" onclick={handleSubmit}>
+                Submit {() => String(count())} email{() => count() > 1 ? 's' : ''}
+              </button>
+            </div>
+
+            {/* Results */}
+            {() => submitStatus() === 'success' ? (
+              <div class="demo-banner demo-banner--success">
+                <strong>✓ Submitted</strong>
+                <ul style="margin-top:.25rem;font-size:.8rem;padding-left:1.25rem">
+                  {submitted().map((email, i) => (
+                    <li key={String(i)}>{email}</li>
+                  ))}
+                </ul>
+              </div>
+            ) : null}
+
+            {() => submitStatus() === 'error' ? (
+              <div class="demo-banner demo-banner--error">
+                <strong>✗ {() => formatError() ?? 'Fix validation errors above.'}</strong>
+              </div>
+            ) : null}
+
+          </div>
+        </FormProvider>
+      )}
+    </div>
+  );
+}

package/src/showcase/forms/pages/edit-form-page.syn

@@ -0,0 +1,163 @@
+/**
+ * Forms Demo — Edit Pre-populated Form
+ * Demonstrates: FormProvider data={existing} → form.parse() on mount
+ *
+ * A mock profile record is passed as `data` to FormProvider.
+ * FormProvider calls form.parse(data) inside useEffect([data, form]).
+ * form.observe(undefined, cb) tracks dirty state reactively.
+ *
+ * On save: validateForm() → onSaveCallback.
+ * On reset: form.reset() → isDirty clears.
+ */
+
+import { createSignal, createEffect, onCleanup } 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, TextareaField, InputField } from '@/components/formular';
+
+type ProfileData = {
+  firstName: string;
+  lastName:  string;
+  bio:       string;
+  age:       number;
+};
+
+/**
+ * Mock pre-existing record — what a real app would load from an API.
+ */
+const MOCK_PROFILE: ProfileData = {
+  firstName: 'Tadeo',
+  lastName:  'Piana',
+  bio:       'Software engineer building the Synetics framework.',
+  age:       30,
+};
+
+export component EditFormPage() {
+  const [form, setForm] = createSignal<IFormular<ProfileData> | null>(null);
+  const [isDirty, setIsDirty]       = createSignal(false);
+  const [savedData, setSavedData]   = createSignal<Record<string, unknown> | null>(null);
+  const [saveStatus, setSaveStatus] = createSignal<'idle' | 'saved' | 'error'>('idle');
+
+  createForm<ProfileData>({
+    schema: f.object({
+      firstName: f.string().min(1).nonempty().debounce(200),
+      lastName:  f.string().min(1).nonempty().debounce(200),
+      bio:       f.string().max(200).optional().debounce(200),
+      age:       f.number().min(1).max(150),
+    }),
+    defaultValues: MOCK_PROFILE,
+  }).then(setForm);
+
+  onCleanup(() => form()?.clear());
+
+  // Track dirty state via form.observe().
+  createEffect(() => {
+    const f = form();
+    if (!f) return;
+    // 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(undefined, () => {
+      setIsDirty(f.getFormFlags().isDirty ?? false);
+    });
+  });
+
+  const handleSave = async () => {
+    const f = form();
+    if (!f) return;
+    const valid = await f.validateForm();
+    if (!valid) {
+      setSaveStatus('error');
+      return;
+    }
+    setSavedData(f.getData() as Record<string, unknown>);
+    setSaveStatus('saved');
+  };
+
+  const handleReset = () => {
+    form()?.reset();
+    setSaveStatus('idle');
+    setSavedData(null);
+  };
+
+  return (
+    <div>
+      <PageHeader
+        title="Edit Pre-populated Form"
+        emoji="✏️"
+        color="#f59e0b"
+        description="FormProvider data={existingRecord} → form.parse() on mount. Dirty tracking via form.observe()."
+      />
+
+      {!form() ? (
+        <p class="status-loading">⏳ Initialising form…</p>
+      ) : (
+        <div>
+          <div
+            class="demo-card"
+            style={() => `border-left-color:${isDirty() ? '#f59e0b' : '#10b981'}`}
+          >
+            <div style="display:flex;align-items:center;gap:.5rem;margin-bottom:.75rem">
+              <span
+                class={() => `demo-banner ${isDirty() ? 'demo-banner--warn' : 'demo-banner--success'}`}
+                style="padding:2px 8px;margin-top:0;display:inline-block;font-size:.8rem;font-weight:600"
+              >
+                {() => isDirty() ? '✎ modified' : '✔ unmodified'}
+              </span>
+            </div>
+
+            <FormProvider
+              form={form()!}
+              data={MOCK_PROFILE}
+              onSaveCallback={handleSave}
+              onQuitCallback={handleReset}
+            >
+              <div style="display:flex;gap:.75rem;flex-wrap:wrap">
+                <div style="flex:1;min-width:180px">
+                  <TextField name="firstName" label="First Name" showErrors showGuides />
+                </div>
+                <div style="flex:1;min-width:180px">
+                  <TextField name="lastName" label="Last Name" showErrors showGuides />
+                </div>
+              </div>
+              <div style="margin-top:.75rem">
+                <InputField name="age" />
+              </div>
+              <div style="margin-top:.75rem">
+                <TextareaField name="bio" />
+              </div>
+            </FormProvider>
+
+            <div style="display:flex;gap:.5rem;margin-top:1rem">
+              <button type="button" class="btn-demo btn-demo--primary" onclick={handleSave}>
+                💾 Save
+              </button>
+              <button
+                type="button"
+                class="btn-demo btn-demo--danger"
+                onclick={handleReset}
+                disabled={() => !isDirty()}
+              >
+                ↺ Reset
+              </button>
+            </div>
+
+            {saveStatus() === 'saved' && savedData() && (
+              <div class="demo-banner demo-banner--success">
+                <strong>✓ Saved snapshot</strong>
+                <pre style="margin-top:.25rem;font-size:.75rem;overflow:auto">{JSON.stringify(savedData(), null, 2)}</pre>
+              </div>
+            )}
+
+            {saveStatus() === 'error' && (
+              <div class="demo-banner demo-banner--error">
+                <strong>✗ Validation failed — fix errors above.</strong>
+              </div>
+            )}
+          </div>
+        </div>
+      )}
+    </div>
+  );
+}

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

@@ -0,0 +1,10 @@
+/**
+ * Forms Demo Pages Index
+ */
+
+export { CrossValidationPage } from './cross-validation-page.syn';
+export { DependentFieldsPage } from './dependent-fields-page.syn';
+export { DynamicFieldsPage } from './dynamic-fields-page.syn';
+export { EditFormPage } from './edit-form-page.syn';
+export { SelectControlsPage } from './select-controls-page.syn';
+export { WizardPage } from './wizard-page.syn';

package/src/showcase/forms/pages/select-controls-page.syn

@@ -0,0 +1,112 @@
+/**
+ * Forms Demo — Select / Checkbox / Toggle / Radio
+ * Demonstrates: CheckboxField · ToggleField · SelectField · RadioGroupField
+ * All option-based controls wired through the same FormProvider.
+ *
+ * Note on options: schemaToDescriptors always initialises options:[].
+ * We populate field.options before mounting (before setForm) so that the
+ * first render already has the correct option list available.
+ */
+
+import { createSignal, onCleanup } from '@synetics/synetics.dev';
+import { createForm, f } from '@synetics/formular.dev';
+import type { IExtendedInput, IFormular, IOptionItem } from '@synetics/formular.dev';
+import { PageHeader } from '../../common/components/page-header.syn';
+import {
+  FormProvider,
+  CheckboxField,
+  ToggleField,
+  SelectField,
+  RadioGroupField,
+} from '@/components/formular';
+
+type SelectControlsData = {
+  newsletter: boolean;
+  notifications: boolean;
+  country: string;
+  plan: string;
+};
+
+const COUNTRY_OPTIONS: IOptionItem[] = [
+  { value: '',   label: '— Select a country —' },
+  { value: 'us', label: 'United States' },
+  { value: 'uk', label: 'United Kingdom' },
+  { value: 'fr', label: 'France' },
+  { value: 'de', label: 'Germany' },
+  { value: 'jp', label: 'Japan' },
+];
+
+const PLAN_OPTIONS: IOptionItem[] = [
+  { value: 'free',       label: '🆓 Free' },
+  { value: 'pro',        label: '⚡ Pro — $9/mo' },
+  { value: 'enterprise', label: '🏢 Enterprise — $49/mo' },
+];
+
+export component SelectControlsPage() {
+  const [form, setForm] = createSignal<IFormular<SelectControlsData> | null>(null);
+
+  createForm<SelectControlsData>({
+    schema: f.object({
+      newsletter:    f.boolean(),
+      notifications: f.boolean(),
+      country:       f.string().nonempty().debounce(200),
+      plan:          f.string().nonempty().debounce(200),
+    }),
+    defaultValues: { newsletter: false, notifications: true, country: '', plan: '' },
+  }).then((resolved: IFormular<SelectControlsData>) => {
+    // Populate options before mounting so first render has them.
+    const countryField: IExtendedInput | undefined = resolved.getField('country');
+    if (countryField) countryField.options = COUNTRY_OPTIONS;
+
+    const planField: IExtendedInput | undefined = resolved.getField('plan');
+    if (planField) planField.options = PLAN_OPTIONS;
+
+    setForm(resolved);
+  });
+
+  onCleanup(() => form()?.clear());
+
+  return (
+    <div>
+      <PageHeader
+        title="Select / Checkbox / Toggle / Radio"
+        emoji="☑️"
+        color="#6366f1"
+        description="CheckboxField · ToggleField · SelectField · RadioGroupField — all wired through one FormProvider."
+      />
+
+      {!form() ? (
+        <p class="status-loading">⏳ Initialising form…</p>
+      ) : (
+        <FormProvider form={form()!} onSaveCallback={() => {}} onQuitCallback={() => {}}>
+
+          <div class="demo-card">
+            <h3 class="demo-title">Boolean controls</h3>
+            <p class="demo-desc">
+              <code>f.boolean()</code> → <code>CheckboxField</code> and <code>ToggleField</code>.
+              Both bind through <code>FCheckboxField</code> / <code>FToggleField</code> primitives.
+            </p>
+            <div style="display:flex;flex-direction:column;gap:.75rem">
+              <CheckboxField name="newsletter" />
+              <ToggleField   name="notifications" />
+            </div>
+          </div>
+
+          <div class="demo-card" style="margin-top:1rem">
+            <h3 class="demo-title">Option-based controls</h3>
+            <p class="demo-desc">
+              Options are set on <code>field.options</code> (type <code>IOptionItem[]</code>) before
+              mounting. <code>SelectField</code> renders a <code>&lt;select&gt;</code>;
+              <code>RadioGroupField</code> renders one <code>FRadioButton</code> per option.
+            </p>
+            <div style="display:flex;flex-direction:column;gap:1rem">
+              <SelectField name="country" />
+              <RadioGroupField name="plan" />
+            </div>
+          </div>
+
+        </FormProvider>
+      )}
+    </div>
+  );
+}