@synetics/ui 0.7.0-alpha

package/src/components/organisms/retractable-panel/retractable-panel.syn

@@ -0,0 +1,141 @@
+/**
+ * RetractablePanel component implementation
+ * Framework: Pulsar
+ * Organism: Collapsible panel with header, body, and footer
+ * Pattern: Fully declarative with CSS-only animations, controlled by parent
+ */
+
+import { cn, roundedClasses, shadowClasses } from '@synetics/design-tokens';
+import { Button } from '../../molecules/button';
+import { ComponentConfigBuilder } from '../../utils/component-config-builder/component-config-builder';
+import { ComponentStylingBuilder } from '../../utils/component-styling-builder/component-styling-builder';
+import { type IRetractablePanelProps } from './retractable-panel.type';
+
+// External to the component so it's compiled ONCE!
+const panelDefaultConfig = new ComponentConfigBuilder('primary').rounded('lg').shadow('md').build();
+
+// External to the component so it's compiled ONCE!
+const panelDefaultStyling = new ComponentStylingBuilder()
+  .base('bg-white overflow-hidden')
+  .border('border border-neutral-200')
+  .build();
+
+/**
+ * RetractablePanel component
+ * Creates a collapsible panel that can expand/collapse horizontally or vertically
+ * Uses CSS transitions for smooth animations without imperative DOM manipulation
+ *
+ * State is controlled by parent via isExpanded prop and onToggle callback
+ */
+export const RetractablePanel = ({
+  config = panelDefaultConfig,
+  styling = panelDefaultStyling,
+  header,
+  footer,
+  children,
+  direction = 'vertical',
+  isExpanded = true,
+  position = 'none',
+  maxHeight = '400px',
+  maxWidth = '400px',
+  onToggle,
+  showToggleButton = true,
+  toggleIcon,
+  animationDuration = 300,
+  ...rest
+}: IRetractablePanelProps): HTMLElement => {
+  const handleToggle = () => {
+    if (onToggle) {
+      onToggle(!isExpanded);
+    }
+  };
+
+  const positionClasses = {
+    top: 'fixed top-0 left-0 right-0 z-50',
+    right: 'fixed top-0 right-0 bottom-0 z-50',
+    bottom: 'fixed bottom-0 left-0 right-0 z-50',
+    left: 'fixed top-0 left-0 bottom-0 z-50',
+    none: 'relative',
+  };
+
+  const className = cn(
+    styling.base,
+    styling.border,
+    positionClasses[position],
+    config.rounded ? roundedClasses[config.rounded] : '',
+    config.shadow ? shadowClasses[config.shadow] : '',
+    config.className,
+    styling.custom
+  );
+
+  // Content wrapper classes - uses CSS for collapse animation
+  const contentClassName = cn(
+    'overflow-hidden transition-all',
+    direction === 'vertical' ? 'flex flex-col' : 'flex flex-row'
+  );
+
+  // Build content style dynamically based on expanded state
+  const transitionProp = direction === 'vertical' ? 'max-height' : 'max-width';
+  const maxSize = direction === 'vertical' ? maxHeight : maxWidth;
+
+  const contentStyle = [
+    `transition-duration: ${animationDuration}ms`,
+    `transition-property: ${transitionProp}`,
+    'transition-timing-function: cubic-bezier(0.4, 0, 0.2, 1)',
+    `${transitionProp}: ${isExpanded ? maxSize : '0'}`,
+  ].join('; ');
+
+  // Toggle icon rotation based on expanded state
+  const iconRotation = isExpanded ? '0deg' : direction === 'vertical' ? '-180deg' : '-90deg';
+
+  // Default toggle icon (chevron) with rotation based on expanded state
+  const defaultToggleIcon = (
+    <svg
+      width="20"
+      height="20"
+      viewBox="0 0 20 20"
+      fill="none"
+      xmlns="http://www.w3.org/2000/svg"
+      style={`transition: transform ${animationDuration}ms ease; transform: rotate(${iconRotation})`}
+    >
+      <path
+        d="M5 7.5L10 12.5L15 7.5"
+        stroke="currentColor"
+        stroke-width="2"
+        stroke-linecap="round"
+        stroke-linejoin="round"
+      />
+    </svg>
+  );
+
+  return (
+    <div className={className} {...rest}>
+      {/* Header */}
+      {header && (
+        <div className="flex items-center justify-between px-6 py-4 border-b border-neutral-200 bg-neutral-50">
+          <div className="flex-1">{header}</div>
+          {showToggleButton && (
+            <Button
+              config={new ComponentConfigBuilder('primary').variant('ghost').size('sm').build()}
+              onclick={handleToggle}
+              aria-label={isExpanded ? 'Collapse panel' : 'Expand panel'}
+              aria-expanded={isExpanded ? 'true' : 'false'}
+            >
+              {toggleIcon || defaultToggleIcon}
+            </Button>
+          )}
+        </div>
+      )}
+
+      {/* Body (collapsible content) - CSS-only animation */}
+      <div className={contentClassName} style={contentStyle}>
+        <div className="px-6 py-4">{children}</div>
+      </div>
+
+      {/* Footer - only shown when expanded */}
+      {footer && isExpanded && (
+        <div className="px-6 py-4 border-t border-neutral-200 bg-neutral-50">{footer}</div>
+      )}
+    </div>
+  );
+};

package/src/components/organisms/retractable-panel/retractable-panel.type.ts

@@ -0,0 +1,52 @@
+/**
+ * RetractablePanel component props interface
+ * Panel that can collapse/expand horizontally or vertically
+ */
+
+import type { Pulsar } from '@synetics/synetics.dev';
+import type { IComponentConfig } from '../../utils/component-config-builder/component-config.type';
+import type { IComponentStyling } from '../../utils/component-styling-builder/component-styling.type';
+
+export interface IRetractablePanelProps extends Pulsar.HtmlExtends<'div'> {
+  /** Component configuration (color, size, state, etc.) */
+  config?: IComponentConfig;
+
+  /** Component styling (colors, spacing, borders, etc.) */
+  styling?: IComponentStyling;
+
+  /** Panel header content */
+  header?: Pulsar.Children;
+
+  /** Panel footer content */
+  footer?: Pulsar.Children;
+
+  /** Panel body content (main content area) */
+  children?: Pulsar.Children;
+
+  /** Direction of collapse animation */
+  direction?: 'horizontal' | 'vertical';
+
+  /** Initial expanded/collapsed state */
+  isExpanded?: boolean;
+
+  /** Position of the panel (for fixed positioning) */
+  position?: 'top' | 'right' | 'bottom' | 'left' | 'none';
+
+  /** Maximum height when expanded (for vertical) */
+  maxHeight?: string;
+
+  /** Maximum width when expanded (for horizontal) */
+  maxWidth?: string;
+
+  /** Callback when expand/collapse state changes */
+  onToggle?: (isExpanded: boolean) => void;
+
+  /** Show toggle button in header */
+  showToggleButton?: boolean;
+
+  /** Custom toggle button icon */
+  toggleIcon?: HTMLElement;
+
+  /** Animation duration in ms */
+  animationDuration?: number;
+}

package/src/components/organisms/select/index.ts

@@ -0,0 +1,7 @@
+/**
+ * Select component exports
+ */
+
+export type { ISelectOption } from './select-option.type';
+export { Select } from './select.syn';
+export type { ISelectProps } from './select.type';

package/src/components/organisms/select/select-option.type.ts

@@ -0,0 +1,9 @@
+/**
+ * Select option type
+ */
+
+export interface ISelectOption {
+  readonly value: string
+  readonly label: string
+  readonly disabled?: boolean
+}

package/src/components/organisms/select/select.syn

@@ -0,0 +1,92 @@
+/**
+ * Select component implementation
+ * Framework: Pulsar
+ * Organism: Native select with options
+ */
+
+import { cn, inputSizeClasses, roundedClasses } from '@synetics/design-tokens';
+import { Skeleton } from '../../atoms/skeleton';
+import { ComponentConfigBuilder } from '../../utils/component-config-builder/component-config-builder';
+import { ComponentStylingBuilder } from '../../utils/component-styling-builder/component-styling-builder';
+import { type ISelectProps } from './select.type';
+
+// External to the component so it's compiled ONCE!
+const selectDefaultConfig = new ComponentConfigBuilder('primary').size('md').rounded('md').build();
+
+// External to the component so it's compiled ONCE!
+const selectDefaultStyling = new ComponentStylingBuilder()
+  .base(
+    'block border font-medium focus:outline-none appearance-none bg-white pr-10 touch-target state-layer'
+  )
+  .transition('transition-all duration-200')
+  .border('border-neutral-300')
+  .focus('focus:ring-4 focus:ring-primary-100 focus:border-primary-600 focus:shadow-md')
+  .disabled('bg-neutral-100 text-neutral-500 cursor-not-allowed opacity-50')
+  .build();
+
+/**
+ * Select component
+ * Creates a native select element with options - organism component
+ */
+export const Select = ({
+  config = selectDefaultConfig,
+  styling = selectDefaultStyling,
+  options,
+  value,
+  defaultValue,
+  placeholder,
+  onChange,
+  ariaLabel,
+  ...rest
+}: ISelectProps): HTMLElement => {
+  if (config.loading) {
+    return (
+      <Skeleton
+        width={config.fullWidth ? 'w-full' : 'w-64'}
+        height="h-10"
+        rounded={config.rounded}
+      />
+    );
+  }
+
+  const className = cn(
+    styling.base,
+    styling.transition,
+    styling.border,
+    styling.focus,
+    config.size ? inputSizeClasses[config.size] : '',
+    config.disabled ? styling.disabled : '',
+    config.rounded ? roundedClasses[config.rounded] : '',
+    config.fullWidth ? 'w-full' : '',
+    config.className,
+    styling.custom
+  );
+
+  return (
+    <select
+      className={className}
+      value={value ?? defaultValue}
+      disabled={config.disabled}
+      title={ariaLabel || placeholder || 'Select an option'}
+      aria-label={ariaLabel || placeholder || 'Select an option'}
+      ariaBusy={config.loading ? 'true' : 'false'}
+      onchange={(e: Event) => {
+        if (onChange) {
+          onChange((e.target as HTMLSelectElement).value);
+        }
+      }}
+      {...rest}
+    >
+      {placeholder && (
+        <option value="" disabled>
+          {placeholder}
+        </option>
+      )}
+      {options.map((option) => (
+        <option value={option.value} disabled={option.disabled}>
+          {option.label}
+        </option>
+      ))}
+    </select>
+  );
+};

package/src/components/organisms/select/select.type.ts

@@ -0,0 +1,31 @@
+/**
+ * Select component props interface
+ * Organism: Native select element with options
+ */
+
+import type { Pulsar } from '@synetics/synetics.dev'
+import { type IComponentConfig } from '../../utils/component-config-builder/component-config.type'
+import { type IComponentStyling } from '../../utils/component-styling-builder/component-styling.type'
+import { type ISelectOption } from './select-option.type'
+
+export interface ISelectProps extends Omit<Pulsar.HtmlExtends<'select'>, 'value' | 'defaultValue' | 'options'> {
+  // Component configuration
+  readonly config?: IComponentConfig
+  
+  // Component styling
+  readonly styling?: IComponentStyling
+  
+  // Select data
+  readonly options: readonly ISelectOption[]
+  readonly value?: string
+  readonly defaultValue?: string
+  
+  // Placeholder
+  readonly placeholder?: string
+  
+  // Accessibility
+  readonly ariaLabel?: string
+  
+  // Change handler
+  readonly onChange?: (value: string) => void
+}

package/src/components/organisms/stepper/INTEGRATION_GUIDE.md

@@ -0,0 +1,230 @@
+# Stepper Integration Guide for Atomos
+
+## 📦 Integration Steps
+
+### 1. Copy to Atomos Repository
+
+Copy the entire Stepper folder structure to your Atomos repository:
+
+```bash
+# From your current project
+cd e:\Sources\e-b-svs\e-b-svs\src\modules\services\components\Stepper
+
+# Copy to atomos.dev repository
+# Assuming atomos.dev is cloned at your preferred location
+# Recommended location: src/organisms/stepper/
+```
+
+Recommended structure in atomos.dev:
+```
+atomos.dev/
+  src/
+    organisms/
+      stepper/
+        Step.tsx
+        Stepper.tsx
+        StepperSummary.tsx
+        index.ts
+        README.md
+        stepper.stories.tsx
+        adapters/
+          atomosFormAdapter.ts
+          rhfAdapter.ts
+          index.ts
+        components/
+          StepperContent.tsx
+          StepperDebug.tsx
+          StepperFooter.tsx
+          StepperHeader.tsx
+        core/
+          actions.ts
+          formAdapter.ts
+          helpers.ts
+          models.ts
+          state.ts
+          reducer/
+            *.ts
+```
+
+### 2. Update Imports
+
+After copying to Atomos, update imports to use Atomos aliases:
+
+```typescript
+// Change all @atomos/ui references in stories to actual Atomos components
+import { FormProvider, FormInput, FormSelect } from '@/atoms/form'
+import { useFormContext } from '@/contexts/form'
+```
+
+### 3. Add to Atomos Exports
+
+In `atomos.dev/src/organisms/index.ts`:
+
+```typescript
+export {
+  Stepper,
+  Step,
+  StepperSummary,
+  useStepperContext,
+  createRHFAdapter,
+  createAtomosFormAdapter
+} from './stepper'
+
+export type {
+  StepperProps,
+  StepperContext,
+  StepperOptions,
+  FormAdapter,
+  FormState
+} from './stepper'
+```
+
+### 4. Create Example Page
+
+Create `atomos.dev/examples/forms/multi-step-form.tsx`:
+
+```typescript
+import { Stepper, Step, createAtomosFormAdapter } from '@atomos/ui'
+import { FormProvider, FormInput, FormSelect } from '@atomos/ui'
+
+export function MultiStepFormExample() {
+  // Example implementation using Atomos FormProvider
+}
+```
+
+### 5. Update package.json
+
+In `atomos.dev/package.json`, ensure proper exports:
+
+```json
+{
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    },
+    "./organisms/stepper": {
+      "import": "./dist/organisms/stepper/index.js",
+      "require": "./dist/organisms/stepper/index.cjs"
+    }
+  }
+}
+```
+
+### 6. Build and Test
+
+```bash
+cd atomos.dev
+pnpm install
+pnpm build
+pnpm dev  # Test in dev mode
+
+# Test Storybook
+pnpm storybook
+```
+
+### 7. Publish
+
+```bash
+# Increment version
+pnpm version minor  # or patch
+
+# Publish to npm
+pnpm publish --access public
+
+# Tag release on GitHub
+git tag -a v1.x.0 -m "Add Stepper organism"
+git push origin v1.x.0
+```
+
+## 🎨 Styling Adjustments
+
+The Stepper uses CSS classes. You may want to convert to Tailwind:
+
+### Before (CSS):
+```css
+.stepper-frame { /* ... */ }
+```
+
+### After (Tailwind):
+```tsx
+<div className="flex flex-col gap-4 p-6 bg-gray-900 rounded-lg">
+```
+
+Review these files for styling updates:
+- [StepperHeader.tsx](../components/StepperHeader.tsx)
+- [StepperFooter.tsx](../components/StepperFooter.tsx)
+- [StepperContent.tsx](../components/StepperContent.tsx)
+
+## ✅ Testing Checklist
+
+- [ ] Copy all files to atomos.dev
+- [ ] Update imports to use Atomos components
+- [ ] Add exports to main index
+- [ ] Convert CSS to Tailwind classes
+- [ ] Test with Atomos FormProvider
+- [ ] Test with React Hook Form
+- [ ] Build successfully
+- [ ] Storybook stories work
+- [ ] Write unit tests
+- [ ] Update main documentation
+- [ ] Publish to npm
+- [ ] Test installation in external project
+
+## 📚 Documentation Updates
+
+Update these files in atomos.dev:
+1. `README.md` - Add Stepper to main features
+2. `docs/organisms/stepper.md` - Detailed component docs
+3. `CHANGELOG.md` - Document the addition
+4. Storybook stories - Already created in `stepper.stories.tsx`
+
+## 🔗 Dependencies
+
+Ensure these are in `atomos.dev/package.json`:
+
+```json
+{
+  "dependencies": {
+    "react": "^18.0.0",
+    "react-dom": "^18.0.0"
+  },
+  "peerDependencies": {
+    "react": "^18.0.0",
+    "react-dom": "^18.0.0",
+    "react-hook-form": "^7.0.0"  // Optional - only if using RHF adapter
+  }
+}
+```
+
+## 🚀 Usage in Projects
+
+Once published, users can install and use:
+
+```bash
+npm install @atomos/ui
+```
+
+```tsx
+import { Stepper, Step, createAtomosFormAdapter } from '@atomos/ui'
+
+// Use with Atomos FormProvider or React Hook Form
+```
+
+## 📝 Notes
+
+- The Stepper is **100% form-library agnostic**
+- Includes adapters for both RHF and Atomos FormProvider
+- Easy to add more adapters (Formik, etc.)
+- Fully typed with TypeScript
+- Follows Atomic Design principles
+- Ready for tree-shaking via tsup build
+
+## 🤝 Contributing
+
+After integration, contributors can:
+1. Add more form library adapters
+2. Enhance validation logic
+3. Add more UI themes
+4. Improve accessibility
+5. Add more example stories