@synetics/ui 0.7.0-alpha

package/src/components/enums/button-type.type.ts

@@ -0,0 +1,5 @@
+/**
+ * Button type
+ */
+
+export type ButtonType = 'button' | 'submit' | 'reset'

package/src/components/enums/container-max-width.type.ts

@@ -0,0 +1,5 @@
+/**
+ * Container Max Width Type
+ */
+
+export type ContainerMaxWidth = 'xs' | 'sm' | 'md' | 'lg' | 'xl' | '2xl' | 'full';

package/src/components/enums/container-padding.type.ts

@@ -0,0 +1,5 @@
+/**
+ * Container Padding Type
+ */
+
+export type ContainerPadding = 'none' | 'xs' | 'sm' | 'md' | 'lg' | 'xl';

package/src/components/enums/divider-orientation.type.ts

@@ -0,0 +1,5 @@
+/**
+ * Divider Orientation Type
+ */
+
+export type DividerOrientation = 'horizontal' | 'vertical';

package/src/components/enums/drawer-placement.type.ts

@@ -0,0 +1,5 @@
+/**
+ * Drawer Placement Type
+ */
+
+export type DrawerPlacement = 'left' | 'right' | 'top' | 'bottom';

package/src/components/enums/drawer-size.type.ts

@@ -0,0 +1,5 @@
+/**
+ * Drawer Size Type
+ */
+
+export type DrawerSize = 'sm' | 'md' | 'lg' | 'xl' | 'full';

package/src/components/enums/icon-position.type.ts

@@ -0,0 +1,5 @@
+/**
+ * Icon position type
+ */
+
+export type IconPosition = 'left' | 'right'

package/src/components/enums/index.ts

@@ -0,0 +1,27 @@
+/**
+ * Component enums - Index
+ */
+
+export { type AlertVariant } from './alert-variant.type';
+export { type AvatarSize } from './avatar-size.type';
+export { type ButtonType } from './button-type.type';
+export { type ContainerMaxWidth } from './container-max-width.type';
+export { type ContainerPadding } from './container-padding.type';
+export { type DividerOrientation } from './divider-orientation.type';
+export { type DrawerPlacement } from './drawer-placement.type';
+export { type DrawerSize } from './drawer-size.type';
+export { type IconPosition } from './icon-position.type';
+export { type InputType } from './input-type.type';
+export { type ModalSize } from './modal-size.type';
+export { type PopoverPlacement } from './popover-placement.type';
+export { type PopoverTrigger } from './popover-trigger.type';
+export { type ProgressSize } from './progress-size.type';
+export { type ProgressVariant } from './progress-variant.type';
+export { type Spacing } from './spacing.type';
+export { type StackAlign } from './stack-align.type';
+export { type StackJustify } from './stack-justify.type';
+export { type ToastPosition } from './toast-position.type';
+export { type ToastVariant } from './toast-variant.type';
+export { type TooltipPlacement } from './tooltip-placement.type';
+export { type TypographyTag } from './typography-tag.type';
+export { type TypographyVariant } from './typography-variant.type';

package/src/components/enums/input-type.type.ts

@@ -0,0 +1,5 @@
+/**
+ * Input type
+ */
+
+export type InputType = 'text' | 'number' | 'email' | 'password' | 'tel' | 'url' | 'search'

package/src/components/enums/modal-size.type.ts

@@ -0,0 +1,5 @@
+/**
+ * Modal Size Type
+ */
+
+export type ModalSize = 'sm' | 'md' | 'lg' | 'xl' | 'full';

package/src/components/enums/popover-placement.type.ts

@@ -0,0 +1,5 @@
+/**
+ * Popover Placement Type
+ */
+
+export type PopoverPlacement = 'top' | 'bottom' | 'left' | 'right';

package/src/components/enums/popover-trigger.type.ts

@@ -0,0 +1,5 @@
+/**
+ * Popover Trigger Type
+ */
+
+export type PopoverTrigger = 'click' | 'hover';

package/src/components/enums/progress-size.type.ts

@@ -0,0 +1,5 @@
+/**
+ * Progress Size Type
+ */
+
+export type ProgressSize = 'sm' | 'md' | 'lg';

package/src/components/enums/progress-variant.type.ts

@@ -0,0 +1,5 @@
+/**
+ * Progress Variant Type
+ */
+
+export type ProgressVariant = 'primary' | 'success' | 'warning' | 'error';

package/src/components/enums/readme.md

@@ -0,0 +1 @@
+this folder contains all common enums that's not applies to feature slice pattern

package/src/components/enums/spacing.type.ts

@@ -0,0 +1,5 @@
+/**
+ * Spacing Type
+ */
+
+export type Spacing = 'xs' | 'sm' | 'md' | 'lg' | 'xl' | '2xl' | string;

package/src/components/enums/stack-align.type.ts

@@ -0,0 +1,5 @@
+/**
+ * Stack Align Type
+ */
+
+export type StackAlign = 'start' | 'center' | 'end' | 'stretch';

package/src/components/enums/stack-justify.type.ts

@@ -0,0 +1,11 @@
+/**
+ * Stack Justify Type
+ */
+
+export type StackJustify =
+  | 'start'
+  | 'center'
+  | 'end'
+  | 'space-between'
+  | 'space-around'
+  | 'space-evenly';

package/src/components/enums/toast-position.type.ts

@@ -0,0 +1,11 @@
+/**
+ * Toast Position Type
+ */
+
+export type ToastPosition =
+  | 'top-left'
+  | 'top-center'
+  | 'top-right'
+  | 'bottom-left'
+  | 'bottom-center'
+  | 'bottom-right';

package/src/components/enums/toast-variant.type.ts

@@ -0,0 +1,5 @@
+/**
+ * Toast Variant Type
+ */
+
+export type ToastVariant = 'success' | 'warning' | 'error' | 'info';

package/src/components/enums/tooltip-placement.type.ts

@@ -0,0 +1,5 @@
+/**
+ * Tooltip Placement Type
+ */
+
+export type TooltipPlacement = 'top' | 'bottom' | 'left' | 'right';

package/src/components/enums/typography-tag.type.ts

@@ -0,0 +1,5 @@
+/**
+ * Typography tag type
+ */
+
+export type TypographyTag = 'h1' | 'h2' | 'h3' | 'h4' | 'h5' | 'h6' | 'p' | 'span' | 'label' | 'div'

package/src/components/enums/typography-variant.type.ts

@@ -0,0 +1,5 @@
+/**
+ * Typography variant type
+ */
+
+export type TypographyVariant = 'h1' | 'h2' | 'h3' | 'h4' | 'h5' | 'h6' | 'body1' | 'body2' | 'caption' | 'overline'

package/src/components/formular/components/debug/form-data-display.syn

@@ -0,0 +1,155 @@
+/**
+ * FormDataDisplay - Real-time form data viewer
+ *
+ * Subscribes to NotificationManager observers to watch form changes.
+ * Demonstrates debouncing by tracking when notifications fire.
+ */
+
+import { createSignal, useEffect } from '@synetics/synetics.dev/hooks';
+import { useFormContext } from '../form-context';
+
+interface FormDataUpdate {
+  data: Record<string, any>;
+  timestamp: string;
+  updateCount: number;
+}
+
+export const FormDataDisplay = (): HTMLElement => {
+  const { form } = useFormContext();
+  const [updates, setUpdates] = createSignal<FormDataUpdate[]>([]);
+  const [updateCount, setUpdateCount] = createSignal(0);
+
+  useEffect(() => {
+    if (!form) {
+      console.warn('[FormDataDisplay] Form not available');
+      return;
+    }
+
+    try {
+      console.log('[FormDataDisplay] Subscribing to form observers via form.observe()...');
+
+      // Subscribe to each field's notifications via the new form.observe() API
+      const unsubscribers: Array<() => void> = [];
+
+      if (form.fields && Array.isArray(form.fields)) {
+        form.fields.forEach((field: any, index: number) => {
+          const fieldId = field?.input?.id;
+          const fieldName = field?.input?.name || `field_${index}`;
+
+          if (fieldId) {
+            console.log(
+              `[FormDataDisplay] Setting up observer for field: ${fieldName} (id: ${fieldId})`
+            );
+
+            // Create a callback that will be called when notifications fire
+            const handleFieldChange = () => {
+              console.log(`[FormDataDisplay] FIRED CALLBACK FOR FIELD: ${fieldName} (${fieldId})`);
+
+              const now = new Date();
+              const timestamp = now.toLocaleTimeString('en-US', {
+                hour12: false,
+                hour: '2-digit',
+                minute: '2-digit',
+                second: '2-digit',
+                fractionalSecondDigits: 3,
+              });
+
+              const newCount = updateCount() + 1;
+              setUpdateCount(newCount);
+
+              try {
+                const formData = form.getData();
+                const update: FormDataUpdate = {
+                  data: formData,
+                  timestamp,
+                  updateCount: newCount,
+                };
+
+                setUpdates((prev) => {
+                  const newUpdates = [update, ...prev];
+                  return newUpdates.slice(0, 10);
+                });
+
+                console.log(
+                  `🔄 [FormDataDisplay] Update #${newCount} at ${timestamp} (${fieldName}):`,
+                  formData
+                );
+              } catch (err) {
+                console.error('[FormDataDisplay] Error getting form data:', err);
+              }
+            };
+
+            // Subscribe to the field via the new form.observe() API
+            const unsub = (form as any).observe(String(fieldId), handleFieldChange);
+            console.log(`✅ [FormDataDisplay] Subscribed to field: ${fieldName}`);
+            unsubscribers.push(unsub);
+          }
+        });
+      }
+
+      console.log(`✅ [FormDataDisplay] Subscribed to ${unsubscribers.length} field observers`);
+
+      // Return cleanup function
+      return () => {
+        unsubscribers.forEach((unsub) => {
+          try {
+            unsub();
+          } catch (err) {
+            console.warn('[FormDataDisplay] Error unsubscribing:', err);
+          }
+        });
+        console.log(
+          `🧹 [FormDataDisplay] Unsubscribed from ${unsubscribers.length} field observers`
+        );
+      };
+    } catch (err) {
+      console.error('[FormDataDisplay] Error setting up observers:', err);
+    }
+  }, [form]); // Only run once when form changes
+
+  return (
+    <div className="mt-8 p-6 bg-gray-900 rounded-lg shadow-lg">
+      <div className="flex items-center justify-between mb-4">
+        <h3 className="text-lg font-semibold text-white">Live Form Data (Debounced Updates)</h3>
+        <div className="text-sm text-gray-400">
+          Total Updates: <span className="text-blue-400 font-mono">{updateCount()}</span>
+        </div>
+      </div>
+
+      <div className="space-y-3">
+        {updates().length === 0 ? (
+          <div className="text-gray-500 text-sm italic p-4 bg-gray-800 rounded">
+            No updates yet. Start typing in the form fields above...
+          </div>
+        ) : (
+          updates().map((update, index) => (
+            <div
+              key={`${update.timestamp}-${index}`}
+              className={`p-4 rounded ${
+                index === 0 ? 'bg-blue-900 border-2 border-blue-500' : 'bg-gray-800'
+              } transition-all duration-300`}
+            >
+              <div className="flex items-center justify-between mb-2">
+                <span className="text-xs font-mono text-gray-400">
+                  Update #{update.updateCount}
+                </span>
+                <span className="text-xs font-mono text-blue-400">{update.timestamp}</span>
+              </div>
+              <pre className="text-sm text-green-400 overflow-x-auto">
+                {JSON.stringify(update.data, null, 2)}
+              </pre>
+            </div>
+          ))
+        )}
+      </div>
+
+      <div className="mt-4 p-3 bg-gray-800 rounded border border-gray-700">
+        <p className="text-xs text-gray-400 leading-relaxed">
+          💡 <strong className="text-white">Tip:</strong> Type quickly in the fields above and watch
+          how the updates are <span className="text-blue-400">debounced</span>. The timestamp shows
+          when each debounced update fires, not every keystroke.
+        </p>
+      </div>
+    </div>
+  );
+}

package/src/components/formular/components/examples/advanced-text-field.syn

@@ -0,0 +1,211 @@
+/**
+ * Example: Advanced TextField using the unified useField hook
+ *
+ * This demonstrates how the unified hook consolidates ALL field behaviors:
+ * - Value management
+ * - Validation display
+ * - Focus/blur handling
+ * - Disabled/required states
+ * - Touch tracking
+ * - All with just ONE hook call!
+ */
+
+import { ShowRegistry as Show } from '@synetics/synetics.dev';
+import { useField } from '../../hooks/use-field';
+import { useFormContext } from '../form-context';
+
+export interface IAdvancedTextFieldProps {
+  /** Field name from form */
+  name: string;
+  /** Optional label override (otherwise uses field.label()) */
+  label?: string;
+  /** Optional placeholder */
+  placeholder?: string;
+  /** Whether to show validation errors */
+  showErrors?: boolean;
+  /** Whether to show validation guides */
+  showGuides?: boolean;
+  /** Optional CSS class */
+  className?: string;
+}
+
+/**
+ * Advanced TextField demonstrating the unified useField hook
+ *
+ * Shows how ONE hook gives you everything:
+ * - Value sync
+ * - Validation state
+ * - Focus management
+ * - Disabled/required handling
+ * - Touch tracking
+ */
+export const AdvancedTextField = ({
+  name,
+  label: labelOverride,
+  placeholder,
+  showErrors = true,
+  showGuides = true,
+  className = '',
+}: IAdvancedTextFieldProps): HTMLElement => {
+  const formContext = useFormContext();
+  const field = formContext.getField(name);
+
+  if (!field) {
+    return <div className="text-red-600">Field "{name}" not found</div>;
+  }
+
+  // ✅ ONE HOOK TO RULE THEM ALL
+  // Get EVERYTHING from formular in a single, optimized hook call
+  const {
+    // Value management
+    value,
+    setValue,
+
+    // Validation
+    hasErrors,
+    errors,
+    guides,
+    isValid,
+
+    // State
+    isDirty,
+    isPristine,
+    isTouched,
+    isFocused,
+
+    // Properties
+    isDisabled,
+    isRequired,
+    label: fieldLabel,
+    type,
+
+    // Actions
+    focus,
+    blur,
+    reset,
+    touch,
+  } = useField(field);
+
+  // Use label from prop or field
+  const displayLabel = labelOverride ?? fieldLabel();
+
+  // ==================== EVENT HANDLERS ====================
+  const handleInput = (e: Event) => {
+    const input = e.target as HTMLInputElement;
+    setValue(input.value);
+  };
+
+  const handleFocus = () => {
+    // Auto-mark as touched when focused
+    if (!isTouched()) {
+      touch();
+    }
+  };
+
+  const handleBlur = () => {
+    blur();
+    // Mark as touched on blur
+    if (!isTouched()) {
+      touch();
+    }
+  };
+
+  const handleReset = () => {
+    reset();
+  };
+
+  // ==================== DYNAMIC CSS CLASSES ====================
+  // Build dynamic classes based on reactive field state
+  const inputClasses = () => {
+    const classes = ['pulsar-input', className];
+
+    if (hasErrors()) classes.push('input-error');
+    if (isValid()) classes.push('input-valid');
+    if (isDirty()) classes.push('input-dirty');
+    if (isPristine()) classes.push('input-pristine');
+    if (isFocused()) classes.push('input-focused');
+    if (isTouched()) classes.push('input-touched');
+    if (isDisabled()) classes.push('input-disabled');
+
+    return classes.join(' ');
+  };
+
+  return (
+    <div className="advanced-text-field">
+      {/* Label with required indicator */}
+      <label className="block mb-2 font-medium">
+        {displayLabel}
+        {isRequired() && <span className="text-red-500 ml-1">*</span>}
+
+        {/* Status badges */}
+        <span className="ml-2 text-xs text-gray-500">
+          {isDirty() && <span className="badge-dirty">(modified)</span>}
+          {isFocused() && <span className="badge-focused">(focused)</span>}
+        </span>
+      </label>
+
+      {/* Input with reactive classes and state */}
+      <input
+        type={type()}
+        value={value()}
+        oninput={handleInput}
+        onfocus={handleFocus}
+        onblur={handleBlur}
+        placeholder={placeholder}
+        disabled={isDisabled()}
+        required={isRequired()}
+        className={inputClasses()}
+        aria-invalid={hasErrors()}
+        aria-required={isRequired()}
+      />
+
+      {/* Action buttons */}
+      <div className="mt-2 flex gap-2">
+        <button type="button" onclick={handleReset} disabled={isPristine()} className="btn-reset">
+          Reset
+        </button>
+        <button type="button" onclick={focus} className="btn-focus">
+          Focus
+        </button>
+      </div>
+
+      {/* Validation errors */}
+      <Show when={() => showErrors && hasErrors()}>
+        <div className="validation-errors mt-2">
+          {errors().map((error, index) => (
+            <p key={error.message || `error-${index}`} className="text-red-600 text-sm">
+              {error.message}
+            </p>
+          ))}
+        </div>
+      </Show>
+
+      {/* Validation guides */}
+      <Show when={() => showGuides && guides().length > 0}>
+        <div className="validation-guides mt-2">
+          {guides().map((guide, index) => (
+            <p key={guide.message || `guide-${index}`} className="text-blue-600 text-sm">
+              {guide.message}
+            </p>
+          ))}
+        </div>
+      </Show>
+
+      {/* Debug info (optional - remove in production) */}
+      {import.meta.env.DEV && (
+        <div className="debug-info mt-2 p-2 bg-gray-100 text-xs">
+          <strong>Debug State:</strong>
+          <ul>
+            <li>Value: {JSON.stringify(value())}</li>
+            <li>Valid: {isValid() ? '✓' : '✗'}</li>
+            <li>Dirty: {isDirty() ? 'Yes' : 'No'}</li>
+            <li>Touched: {isTouched() ? 'Yes' : 'No'}</li>
+            <li>Focused: {isFocused() ? 'Yes' : 'No'}</li>
+            <li>Disabled: {isDisabled() ? 'Yes' : 'No'}</li>
+            <li>Required: {isRequired() ? 'Yes' : 'No'}</li>
+          </ul>
+        </div>
+      )}
+    </div>
+  );
+};

package/src/components/formular/components/form-context/form-context.ts

@@ -0,0 +1,15 @@
+/**
+ * Form context implementation
+ * Provides form operations and field access throughout the component tree
+ */
+
+import { createContext } from '@synetics/synetics.dev';
+import type { IFormContext } from '../../types';
+
+/**
+ * Form context
+ * Must be provided by FormProvider
+ *
+ * @template T - The shape of the form data
+ */
+export const FormContext = createContext<IFormContext<any> | undefined>(undefined);

package/src/components/formular/components/form-context/index.ts

@@ -0,0 +1,6 @@
+/**
+ * Form context exports
+ */
+
+export { FormContext } from './form-context';
+export { useFormContext } from './use-form-context';

package/src/components/formular/components/form-context/use-form-context.ts

@@ -0,0 +1,31 @@
+/**
+ * useFormContext hook
+ * Provides access to form operations and field instances
+ * Must be used within a FormProvider
+ */
+
+import { useContext } from '@synetics/synetics.dev';
+import type { IFormContext } from '../../types';
+import { FormContext } from './form-context';
+
+/**
+ * Hook for accessing form context
+ *
+ * @template T - The shape of the form data
+ * @returns The form context
+ * @throws Error if used outside FormProvider
+ *
+ * @example
+ * ```typescript
+ * const { getField, updateField, validateForm } = useFormContext()
+ * const usernameField = getField('username')
+ * ```
+ */
+export function useFormContext<T extends object = any>(): IFormContext<T> {
+  const context = useContext(FormContext);
+
+  // With signal-based context, the value starts as undefined and updates when Provider executes
+  // No need to check - if there's no Provider, the app will fail when trying to use undefined
+  // If Provider is coming, the signal will update and components will reactively re-render
+  return context!;
+}