@synetics/ui 0.7.0-alpha

package/src/components/atoms/spinner/spinner.type.ts

@@ -0,0 +1,40 @@
+/**
+ * Spinner component type definitions
+ */
+
+import type { ComponentSize } from '@synetics/design-tokens'
+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'
+
+/**
+ * Spinner component props
+ */
+export interface ISpinnerProps extends Pulsar.HtmlExtends<'span'> {
+  /**
+   * Component configuration
+   */
+  config?: IComponentConfig
+  
+  /**
+   * Component styling
+   */
+  styling?: IComponentStyling
+  
+  /**
+   * Size of the spinner
+   * @default 'md'
+   */
+  size?: ComponentSize
+  
+  /**
+   * CSS class name
+   */
+  className?: string
+  
+  /**
+   * Label for screen readers
+   * @default 'Loading'
+   */
+  label?: string
+}

package/src/components/atoms/stack/index.ts

@@ -0,0 +1,7 @@
+/**
+ * Stack Module
+ * Exports the Stack components
+ */
+
+export { HStack, Stack, VStack } from './stack.syn';
+export type { IStackProps } from './stack.type';

package/src/components/atoms/stack/stack.syn

@@ -0,0 +1,79 @@
+/**
+ * Stack Component - Declarative Implementation
+ * Flexbox layout using design tokens
+ */
+
+import { cn } from '@synetics/design-tokens';
+import type { IStackProps } from './stack.type';
+
+/**
+ * Stack component
+ * Creates a flexbox layout - atomic component
+ */
+export const Stack = ({
+  direction = 'vertical',
+  spacing = 'md',
+  align,
+  justify,
+  wrap = false,
+  children,
+  className,
+  ...rest
+}: IStackProps): HTMLElement => {
+  const spacingClasses = {
+    xs: 'gap-1',
+    sm: 'gap-2',
+    md: 'gap-4',
+    lg: 'gap-6',
+    xl: 'gap-8',
+    '2xl': 'gap-12',
+  };
+
+  const alignClasses = {
+    start: 'items-start',
+    center: 'items-center',
+    end: 'items-end',
+    stretch: 'items-stretch',
+  };
+
+  const justifyClasses = {
+    start: 'justify-start',
+    center: 'justify-center',
+    end: 'justify-end',
+    'space-between': 'justify-between',
+    'space-around': 'justify-around',
+    'space-evenly': 'justify-evenly',
+  };
+
+  const stackClasses = cn(
+    'flex transition-all duration-200',
+    direction === 'vertical' ? 'flex-col' : 'flex-row',
+    typeof spacing === 'string' && spacingClasses[spacing as keyof typeof spacingClasses],
+    align && alignClasses[align],
+    justify && justifyClasses[justify],
+    wrap && 'flex-wrap',
+    className
+  );
+
+  const customStyle = typeof spacing !== 'string' ? `gap: ${spacing}` : undefined;
+
+  return (
+    <div className={stackClasses} style={customStyle} {...rest}>
+      {children}
+    </div>
+  );
+};
+
+/**
+ * VStack - Vertical Stack helper
+ */
+export const VStack = (props: IStackProps): HTMLElement => (
+  <Stack {...props} direction="vertical" />
+);
+
+/**
+ * HStack - Horizontal Stack helper
+ */
+export const HStack = (props: IStackProps): HTMLElement => (
+  <Stack {...props} direction="horizontal" />
+);

package/src/components/atoms/stack/stack.type.ts

@@ -0,0 +1,42 @@
+/**
+ * Stack component props interface
+ */
+
+import type { Pulsar } from '@synetics/synetics.dev';
+import type { Spacing, StackAlign, StackJustify } from '../../enums';
+
+export interface IStackProps extends Pulsar.HtmlExtends<'div'> {
+  /**
+   * Stack direction
+   * @default 'vertical'
+   */
+  readonly direction?: 'horizontal' | 'vertical';
+
+  /**
+   * Spacing between items
+   * @default 'md'
+   */
+  readonly spacing?: Spacing;
+
+  /**
+   * Align items
+   */
+  readonly align?: StackAlign;
+
+  /**
+   * Justify content
+   */
+  readonly justify?: StackJustify;
+
+  /**
+   * Allow wrapping
+   * @default false
+   */
+  readonly wrap?: boolean;
+
+  /**
+   * Stack children - supports all JSX patterns
+   * Including conditionals, arrays, and primitives
+   */
+  readonly children?: Pulsar.Children;
+}

package/src/components/atoms/textarea/index.ts

@@ -0,0 +1,6 @@
+/**
+ * Textarea component exports
+ */
+
+export { Textarea } from './textarea.syn';
+export type { ITextareaProps } from './textarea.type';

package/src/components/atoms/textarea/textarea.syn

@@ -0,0 +1,78 @@
+/**
+ * Textarea component implementation
+ * Framework: Pulsar
+ */
+
+import { cn, roundedClasses, textareaSizeClasses } from '@synetics/design-tokens';
+import { ComponentConfigBuilder } from '../../utils/component-config-builder/component-config-builder';
+import { ComponentStylingBuilder } from '../../utils/component-styling-builder/component-styling-builder';
+import { Skeleton } from '../skeleton';
+import { type ITextareaProps } from './textarea.type';
+
+// External to the component so it's compiled ONCE!
+const textareaDefaultConfig = new ComponentConfigBuilder('primary')
+  .size('md')
+  .rounded('md')
+  .build();
+
+// External to the component so it's compiled ONCE!
+const textareaDefaultStyling = new ComponentStylingBuilder()
+  .base('block border font-medium focus:outline-none resize-y touch-target')
+  .transition('transition-all duration-200')
+  .border('border-neutral-300')
+  .focus('focus:ring-4 focus:ring-primary-100 focus:border-primary-600 focus:shadow-md')
+  .background('bg-white text-neutral-900')
+  .readOnly('bg-neutral-50 cursor-default')
+  .disabled('bg-neutral-100 text-neutral-500 cursor-not-allowed opacity-50')
+  .build();
+/**
+ * Textarea component
+ * Creates an accessible textarea - atomic component (single element output)
+ */
+export const Textarea = ({
+  config = textareaDefaultConfig,
+  styling = textareaDefaultStyling,
+  value,
+  defaultValue,
+  rows = 4,
+  ...rest
+}: ITextareaProps): HTMLElement => {
+  if (config.loading) {
+    return (
+      <Skeleton
+        width={config.fullWidth ? 'w-full' : 'w-64'}
+        height="h-24"
+        rounded={config.rounded}
+      />
+    );
+  }
+
+  const className = cn(
+    styling.base,
+    styling.transition,
+    styling.border,
+    styling.focus,
+    config.size ? textareaSizeClasses[config.size] : '',
+    config.disabled
+      ? styling.disabled
+      : 'readOnly' in rest && rest.readOnly
+        ? styling.readOnly
+        : styling.background,
+    config.rounded ? roundedClasses[config.rounded] : '',
+    config.fullWidth ? 'w-full' : '',
+    config.className,
+    styling.custom
+  );
+
+  return (
+    <textarea
+      rows={rows}
+      className={className}
+      value={value !== undefined ? String(value) : undefined}
+      defaultValue={defaultValue !== undefined ? String(defaultValue) : undefined}
+      disabled={config.disabled || false}
+      ariaBusy={config.loading ? 'true' : 'false'}
+      {...rest}
+    />
+  );
+};

package/src/components/atoms/textarea/textarea.type.ts

@@ -0,0 +1,28 @@
+/**
+ * Textarea component props interface
+ * [COPILOT] this is an unique component
+ * [COPILOT] this is a textarea element
+ * [COPILOT] can have default value
+ * [COPILOT] it must accepts all HTMLTextAreaElement rest props from consumer
+ * [COPILOT] can have a default skeletton behavior on Loading (reuse available skeletton component) that replaces the actual component in loading time
+ * [COPILOT] it must contains all regular ARIA that could be expected for this kid of component
+ */
+
+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 ITextareaProps extends Omit<Pulsar.HtmlExtends<'textarea'>, 'value' | 'defaultValue'> {
+  // Component configuration
+  readonly config?: IComponentConfig
+  
+  // Component styling
+  readonly styling?: IComponentStyling
+  
+  // Textarea value
+  readonly value?: string
+  readonly defaultValue?: string
+  
+  // Textarea rows
+  readonly rows?: number
+}

package/src/components/atoms/toggle/index.ts

@@ -0,0 +1,6 @@
+/**
+ * Toggle component exports
+ */
+
+export { Toggle } from './toggle.syn';
+export type { IToggleProps } from './toggle.type';

package/src/components/atoms/toggle/toggle.syn

@@ -0,0 +1,69 @@
+/**
+ * Toggle component implementation
+ * Framework: Pulsar
+ */
+
+import { cn, toggleSizeClasses } from '@synetics/design-tokens';
+import { ComponentConfigBuilder } from '../../utils/component-config-builder/component-config-builder';
+import { ComponentStylingBuilder } from '../../utils/component-styling-builder/component-styling-builder';
+import { Skeleton } from '../skeleton';
+import { type IToggleProps } from './toggle.type';
+
+// External to the component so it's compiled ONCE!
+const toggleDefaultConfig = new ComponentConfigBuilder('primary')
+  .size('md')
+  .rounded('full')
+  .build();
+
+// External to the component so it's compiled ONCE!
+const toggleDefaultStyling = new ComponentStylingBuilder()
+  .base(
+    'relative inline-flex items-center rounded-full cursor-pointer focus:outline-none transition-all duration-200 state-layer touch-target-comfortable'
+  )
+  .focus('focus:ring-4 focus:ring-primary-100 focus:ring-offset-2')
+  .background('bg-neutral-300 aria-checked:bg-primary-600')
+  .disabled('opacity-40 cursor-not-allowed')
+  .build();
+
+/**
+ * Toggle component
+ * Creates an accessible toggle switch - atomic component (single element output)
+ */
+export const Toggle = ({
+  config = toggleDefaultConfig,
+  styling = toggleDefaultStyling,
+  checked = false,
+  ...rest
+}: IToggleProps): HTMLElement => {
+  if (config.loading) {
+    return (
+      <Skeleton
+        width={config.size ? toggleSizeClasses[config.size].split(' ')[0] : 'w-11'}
+        height={config.size ? toggleSizeClasses[config.size].split(' ')[1] : 'h-6'}
+        rounded="full"
+      />
+    );
+  }
+
+  const className = cn(
+    styling.base,
+    styling.focus,
+    styling.background,
+    config.size ? toggleSizeClasses[config.size] : '',
+    config.disabled ? styling.disabled : '',
+    config.className,
+    styling.custom
+  );
+
+  return (
+    <button
+      type="button"
+      role="switch"
+      ariaChecked={checked ? 'true' : 'false'}
+      className={className}
+      disabled={config.disabled || false}
+      ariaBusy={config.loading ? 'true' : 'false'}
+      {...rest}
+    />
+  );
+};

package/src/components/atoms/toggle/toggle.type.ts

@@ -0,0 +1,27 @@
+/**
+ * Toggle component props interface
+ * [COPILOT] this is an unique component
+ * [COPILOT] this component can be wether vertical / horizontal oriented
+ * [COPILOT] can have default value
+ * [COPILOT] can have a default skeletton behavior on Loading (reuse available skeletton component) that replaces the actual component in loading time
+ * [COPILOT] it must contains all regular ARIA that could be expected for this kid of component
+ */
+
+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 IToggleProps extends Pulsar.HtmlExtends<'button'> {
+  // Component configuration
+  readonly config?: IComponentConfig
+  
+  // Component styling
+  readonly styling?: IComponentStyling
+  
+  // Toggle checked state
+  readonly checked?: boolean
+  readonly defaultChecked?: boolean
+  
+  // Toggle change handler
+  readonly onChange?: (checked: boolean) => void
+}

package/src/components/atoms/tooltip/index.ts

@@ -0,0 +1,5 @@
+/**
+ * Tooltip component - Index
+ */
+
+export { Tooltip } from './tooltip.syn';

package/src/components/atoms/tooltip/tooltip.syn

@@ -0,0 +1,83 @@
+/**
+ * Tooltip component
+ * Framework: Pulsar
+ */
+
+import { cn } from '@synetics/design-tokens';
+import type { TooltipPlacement } from '../../enums/tooltip-placement.type';
+import type { ITooltipProps } from './tooltip.type';
+
+/**
+ * Tooltip component
+ * Simple tooltip with placement and delay support
+ */
+export const Tooltip = ({
+  content,
+  placement = 'top',
+  showDelay = 200,
+  hideDelay = 0,
+  children,
+  className,
+  ...rest
+}: ITooltipProps): HTMLElement => {
+  let showTimeout: number | null = null;
+  let hideTimeout: number | null = null;
+  let tooltipElement: HTMLElement | null = null;
+
+  const placementClasses: Record<TooltipPlacement, string> = {
+    top: 'bottom-full left-1/2 -translate-x-1/2 mb-2',
+    bottom: 'top-full left-1/2 -translate-x-1/2 mt-2',
+    left: 'right-full top-1/2 -translate-y-1/2 mr-2',
+    right: 'left-full top-1/2 -translate-y-1/2 ml-2',
+  };
+
+  const showTooltip = () => {
+    if (hideTimeout) {
+      clearTimeout(hideTimeout);
+      hideTimeout = null;
+    }
+
+    showTimeout = setTimeout(() => {
+      if (tooltipElement) {
+        tooltipElement.classList.remove('opacity-0', 'pointer-events-none');
+        tooltipElement.classList.add('opacity-100', 'animate-fade-in');
+      }
+    }, showDelay) as unknown as number;
+  };
+
+  const hideTooltip = () => {
+    if (showTimeout) {
+      clearTimeout(showTimeout);
+      showTimeout = null;
+    }
+
+    hideTimeout = setTimeout(() => {
+      if (tooltipElement) {
+        tooltipElement.classList.remove('opacity-100');
+        tooltipElement.classList.add('opacity-0', 'pointer-events-none');
+      }
+    }, hideDelay) as unknown as number;
+  };
+
+  return (
+    <div
+      className={cn('relative inline-block', className)}
+      onmouseenter={showTooltip}
+      onmouseleave={hideTooltip}
+      {...rest}
+    >
+      {children}
+      <div
+        ref={(el: HTMLElement | null) => (tooltipElement = el)}
+        className={cn(
+          'absolute z-50 px-2 py-1 text-sm text-white bg-neutral-900 rounded-md whitespace-nowrap',
+          'transition-opacity duration-200 opacity-0 pointer-events-none',
+          placementClasses[placement]
+        )}
+        role="tooltip"
+      >
+        {content}
+      </div>
+    </div>
+  );
+};

package/src/components/atoms/tooltip/tooltip.type.ts

@@ -0,0 +1,36 @@
+/**
+ * Tooltip component props interface
+ */
+
+import type { Pulsar } from '@synetics/synetics.dev';
+import type { TooltipPlacement } from '../../enums';
+
+export interface ITooltipProps extends Pulsar.HtmlExtends<'div'> {
+  /**
+   * Tooltip content
+   */
+  readonly content: string | HTMLElement;
+
+  /**
+   * Tooltip placement
+   * @default 'top'
+   */
+  readonly placement?: TooltipPlacement;
+
+  /**
+   * Delay before showing tooltip (ms)
+   * @default 200
+   */
+  readonly showDelay?: number;
+
+  /**
+   * Delay before hiding tooltip (ms)
+   * @default 0
+   */
+  readonly hideDelay?: number;
+
+  /**
+   * Children element
+   */
+  readonly children: any;
+}

package/src/components/atoms/typography/index.ts

@@ -0,0 +1,6 @@
+/**
+ * Typography component exports
+ */
+
+export { Typography } from './typography.syn';
+export type { ITypographyProps } from './typography.type';

package/src/components/atoms/typography/typography.syn

@@ -0,0 +1,113 @@
+/**
+ * Typography component implementation
+ * Framework: Pulsar
+ */
+
+import { cn, typographyVariantClasses } from '@synetics/design-tokens';
+import { ComponentConfigBuilder } from '../../utils/component-config-builder/component-config-builder';
+import { ComponentStylingBuilder } from '../../utils/component-styling-builder/component-styling-builder';
+import { Skeleton } from '../skeleton';
+import { type ITypographyProps } from './typography.type';
+
+// External to the component so it's compiled ONCE!
+const typographyDefaultConfig = new ComponentConfigBuilder('primary').build();
+
+// External to the component so it's compiled ONCE!
+const typographyDefaultStyling = new ComponentStylingBuilder()
+  .base('text-neutral-900 transition-colors duration-200')
+  .build();
+
+/**
+ * Typography component
+ * Creates a text element with variant styling - atomic component (single element output)
+ */
+export const Typography = ({
+  config = typographyDefaultConfig,
+  styling = typographyDefaultStyling,
+  tag = 'span',
+  variant = 'body1',
+  truncate = false,
+  noWrap = false,
+  userSelect = true,
+  children,
+  ...rest
+}: ITypographyProps): HTMLElement => {
+  if (config.loading) {
+    return <Skeleton width="w-full" height="h-6" rounded={config.rounded} />;
+  }
+
+  const className = cn(
+    styling.base,
+    variant ? typographyVariantClasses[variant] : '',
+    truncate ? 'truncate' : '',
+    noWrap ? 'whitespace-nowrap' : '',
+    userSelect === false ? 'select-none' : '',
+    config.className,
+    styling.custom
+  );
+
+  // Pulsar doesn't support dynamic component tags, so we need to explicitly render each
+  switch (tag) {
+    case 'h1':
+      return (
+        <h1 className={className} ariaBusy="false" {...rest}>
+          {children}
+        </h1>
+      );
+    case 'h2':
+      return (
+        <h2 className={className} ariaBusy="false" {...rest}>
+          {children}
+        </h2>
+      );
+    case 'h3':
+      return (
+        <h3 className={className} ariaBusy="false" {...rest}>
+          {children}
+        </h3>
+      );
+    case 'h4':
+      return (
+        <h4 className={className} ariaBusy="false" {...rest}>
+          {children}
+        </h4>
+      );
+    case 'h5':
+      return (
+        <h5 className={className} ariaBusy="false" {...rest}>
+          {children}
+        </h5>
+      );
+    case 'h6':
+      return (
+        <h6 className={className} ariaBusy="false" {...rest}>
+          {children}
+        </h6>
+      );
+    case 'p':
+      return (
+        <p className={className} ariaBusy="false" {...rest}>
+          {children}
+        </p>
+      );
+    case 'label':
+      return (
+        <label className={className} ariaBusy="false" {...rest}>
+          {children}
+        </label>
+      );
+    case 'div':
+      return (
+        <div className={className} ariaBusy="false" {...rest}>
+          {children}
+        </div>
+      );
+    case 'span':
+    default:
+      return (
+        <span className={className} ariaBusy="false" {...rest}>
+          {children}
+        </span>
+      );
+  }
+};

package/src/components/atoms/typography/typography.type.ts

@@ -0,0 +1,36 @@
+/**
+ * Typography component props interface
+ * [COPILOT] this is an unique component
+ * [COPILOT] this component can take a DOM Tag as main render TAG
+ * [COPILOT] can have default unset value / empty / null
+ * [COPILOT] can be truncated, wrapped, elipsis
+ * [COPILOT] can be user-select restricted (default unset)
+ * [COPILOT] can have a default skeletton behavior on Loading (reuse available skeletton component) that replaces the actual component in loading time
+ * [COPILOT] it must contains all regular ARIA that could be expected for this kid of component
+ */
+
+import type { Pulsar } from '@synetics/synetics.dev';
+import { type TypographyTag } from '../../enums/typography-tag.type';
+import { type TypographyVariant } from '../../enums/typography-variant.type';
+import { type IComponentConfig } from '../../utils/component-config-builder/component-config.type';
+import { type IComponentStyling } from '../../utils/component-styling-builder/component-styling.type';
+
+export interface ITypographyProps extends Pulsar.HtmlExtends<'span'> {
+  // Component configuration
+  readonly config?: IComponentConfig;
+
+  // Component styling
+  readonly styling?: IComponentStyling;
+
+  // Typography settings
+  readonly tag?: TypographyTag;
+  readonly variant?: TypographyVariant;
+
+  // Text behavior
+  readonly truncate?: boolean;
+  readonly noWrap?: boolean;
+  readonly userSelect?: boolean;
+
+  // Content
+  readonly children?: any;
+}

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

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

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

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