sdaia-ui 1.0.1

package/src/components/ButtonsWithSdaiaTouch/ButtonsWithSdaiaTouch.tsx

@@ -0,0 +1,130 @@
+'use client';
+
+import { forwardRef } from 'react';
+import { cn } from '../../lib/cn';
+import type { ButtonsWithSdaiaTouchProps } from './ButtonsWithSdaiaTouch.types';
+import { ButtonHoverPattern } from './ButtonHoverPattern';
+import {
+  VARIANT_CLASSES,
+  DESTRUCTIVE_VARIANT_CLASSES,
+  SELECTED_CLASSES,
+  DISABLED_CLASSES,
+  SIZE_CLASSES,
+  ICON_ONLY_SIZE_CLASSES,
+  ICON_SIZE_CLASSES,
+  FOCUS_RING,
+} from '../Button/Button.variants';
+import {
+  HOVER_PATTERN_CLASSES,
+  DESTRUCTIVE_HOVER_PATTERN_CLASSES,
+} from './ButtonsWithSdaiaTouch.variants';
+
+export const ButtonsWithSdaiaTouch = forwardRef<HTMLButtonElement, ButtonsWithSdaiaTouchProps>(
+  function ButtonsWithSdaiaTouch(
+    {
+      variant = 'primary',
+      size = 'md',
+      disabled = false,
+      leadingIcon,
+      trailingIcon,
+      leftIcon,
+      rightIcon,
+      iconOnly = false,
+      selected = false,
+      fullWidth = false,
+      destructive = false,
+      as,
+      children,
+      className,
+      ...rest
+    },
+    ref,
+  ) {
+    const Comp = as ?? 'button';
+    const isDisabled = disabled;
+
+    const leading = leadingIcon ?? leftIcon;
+    const trailing = trailingIcon ?? rightIcon;
+
+    const isDestructive = destructive || variant === 'destructive';
+
+    let variantClass: string;
+    if (isDisabled) {
+      variantClass = DISABLED_CLASSES[variant];
+    } else if (selected) {
+      variantClass = SELECTED_CLASSES[variant];
+    } else if (isDestructive && variant !== 'destructive') {
+      variantClass = DESTRUCTIVE_VARIANT_CLASSES[variant] ?? VARIANT_CLASSES[variant];
+    } else {
+      variantClass = VARIANT_CLASSES[variant];
+    }
+
+    const sizeClass = iconOnly ? ICON_ONLY_SIZE_CLASSES[size] : SIZE_CLASSES[size];
+    const iconSizeClass = ICON_SIZE_CLASSES[size];
+
+    const patternColorClass = isDestructive
+      ? DESTRUCTIVE_HOVER_PATTERN_CLASSES[variant] ?? HOVER_PATTERN_CLASSES[variant]
+      : HOVER_PATTERN_CLASSES[variant];
+
+    return (
+      <Comp
+        ref={ref}
+        data-slot="button-sdaia-touch"
+        data-anatomy="1"
+        disabled={isDisabled}
+        aria-pressed={selected ? true : undefined}
+        className={cn(
+          'group relative overflow-hidden inline-flex items-center justify-center font-[500] motion-feedback cursor-pointer',
+          sizeClass,
+          variantClass,
+          !isDisabled && FOCUS_RING,
+          fullWidth && 'w-full',
+          className,
+        )}
+        {...rest}
+      >
+        {!isDisabled && patternColorClass ? (
+          <span
+            data-slot="hover-pattern"
+            aria-hidden="true"
+            className={cn(
+              'pointer-events-none absolute inset-0 z-0 flex items-center justify-center overflow-hidden',
+              patternColorClass,
+            )}
+          >
+            <ButtonHoverPattern className="h-[2px] w-[2px] origin-center scale-100 transition-transform duration-400 ease-out group-hover:scale-[600] group-hover:duration-[6500ms]" />
+          </span>
+        ) : null}
+        {leading ? (
+          <span
+            data-slot="leading-icon"
+            data-anatomy="3"
+            className={cn(
+              'relative z-10 inline-flex items-center justify-center flex-shrink-0',
+              iconSizeClass,
+            )}
+          >
+            {leading}
+          </span>
+        ) : null}
+        {!iconOnly && (
+          <span data-anatomy="2" className="relative z-10">
+            {children}
+          </span>
+        )}
+        {trailing ? (
+          <span
+            data-slot="trailing-icon"
+            data-anatomy="4"
+            className={cn(
+              'relative z-10 inline-flex items-center justify-center flex-shrink-0',
+              iconSizeClass,
+            )}
+          >
+            {trailing}
+          </span>
+        ) : null}
+      </Comp>
+    );
+  },
+);

package/src/components/ButtonsWithSdaiaTouch/ButtonsWithSdaiaTouch.types.ts

@@ -0,0 +1,4 @@
+import type { ButtonProps, ButtonSize, ButtonVariant } from '../Button/Button.types';
+
+export type ButtonsWithSdaiaTouchProps = ButtonProps;
+export type { ButtonSize, ButtonVariant };

package/src/components/ButtonsWithSdaiaTouch/ButtonsWithSdaiaTouch.variants.ts

@@ -0,0 +1,19 @@
+import type { ButtonVariant } from '../Button/Button.types';
+
+/* ── Hover pattern color per variant (text-* class for currentColor) ── */
+export const HOVER_PATTERN_CLASSES: Partial<Record<ButtonVariant, string>> = {
+  neutral: 'text-[rgba(77,87,97,1)]',
+  primary: 'text-[rgba(16,70,49,1)]',
+  destructive: 'text-[rgba(122,39,26,1)]',
+  'secondary-solid': 'text-[rgba(229,231,235,1)]',
+  'secondary-outline': 'text-[rgba(229,231,235,1)]',
+  subtle: 'text-[rgba(229,231,235,1)]',
+  /* transparent intentionally omitted — no hover pattern */
+};
+
+export const DESTRUCTIVE_HOVER_PATTERN_CLASSES: Partial<Record<ButtonVariant, string>> = {
+  primary: 'text-[rgba(122,39,26,1)]',
+  'secondary-solid': 'text-[rgba(254,205,202,1)]',
+  'secondary-outline': 'text-[rgba(254,205,202,1)]',
+  subtle: 'text-[rgba(254,205,202,1)]',
+};

package/src/components/ButtonsWithSdaiaTouch/index.ts

@@ -0,0 +1,6 @@
+export { ButtonsWithSdaiaTouch } from './ButtonsWithSdaiaTouch';
+export type {
+  ButtonsWithSdaiaTouchProps,
+  ButtonSize,
+  ButtonVariant,
+} from './ButtonsWithSdaiaTouch.types';

package/src/components/CLAUDE.md

@@ -0,0 +1,212 @@
+# Components Package Instructions
+
+This folder contains the source code for all design system components.
+
+## Purpose
+
+Components in this folder must follow the design system documentation and visual rules.
+They are reusable UI primitives and component patterns used across the platform.
+
+## Folder Structure
+
+Each component should live in its own folder under `packages/ui/src/components`.
+
+Example:
+- `Button/`
+- `Input/`
+- `Checkbox/`
+- `TextInput/`
+
+Each component folder should have a clear and consistent structure.
+
+Recommended structure:
+- component implementation
+- subcomponents if needed
+- types
+- constants/variant configuration
+- index export
+
+## Component Modeling Rules
+
+Each component is modeled using:
+
+- **States**
+- **Types**
+
+These are different concepts and must not be mixed.
+
+### State
+
+A **state** represents the UI or interaction condition of a component.
+
+Examples:
+- `default`
+- `focused`
+- `placeholder`
+- `disabled`
+- `error`
+- `success`
+- `readOnly`
+
+### Type
+
+A **type** represents a variant or structural style within a state.
+
+Examples:
+- `default`
+- `withIcon`
+- `withPrefix`
+- `withSuffix`
+- `currency`
+- `copy`
+- `card`
+
+A state can contain multiple types.
+
+Example:
+- `focused/default`
+- `focused/withIcon`
+- `placeholder/default`
+- `placeholder/copy`
+
+## Important Rule
+
+Do not treat states and types as synonyms.
+
+- State = condition
+- Type = variation
+
+Every component implementation must preserve this hierarchy.
+
+## Implementation Expectations
+
+When creating or updating a component:
+
+1. Identify all supported states.
+2. Identify all supported types inside each state.
+3. Keep naming consistent with the design documentation.
+4. Avoid hardcoding one-off variations that should instead be modeled as a type.
+5. Reuse shared logic where possible.
+6. Prefer scalable variant-based architecture over duplicated JSX.
+7. Match spacing, typography, borders, radii, and colors to the design system tokens.
+8. Support light and dark mode when required by the system.
+
+## Design Consistency
+
+Claude must use the existing design system patterns already present in this package.
+
+Follow:
+- shared tokens
+- shared typography rules
+- shared spacing rules
+- shared component API conventions
+- existing export conventions
+
+Do not introduce a new pattern if an existing one already solves the problem.
+
+## Component Composition and Reuse
+
+When creating a new component, Claude must first check whether the new component should be composed from existing design system components.
+
+If a new component includes an existing component that already exists in this package, Claude should use the existing component instead of rebuilding it from scratch.
+
+Examples:
+- if a `SlideoutMenu` includes a button, use the existing `Button` component
+- if a component needs an input field, use the existing `Input` or `TextInput` component if appropriate
+- if a component includes checkboxes, toggles, icons, badges, or similar reusable UI parts, use the existing design system components where possible
+
+Do not recreate existing components inside new components unless there is a clear documented reason.
+
+Claude should prefer composition over duplication.
+
+This improves:
+- consistency across the design system
+- cleaner and more maintainable code
+- reuse of existing APIs, styles, and behavior
+- easier updates when shared components change
+
+Before implementing a new component, Claude should:
+1. inspect existing components in this package
+2. identify whether any part of the new component already exists
+3. compose the new component from existing building blocks where appropriate
+4. only create new internal UI pieces when no reusable component already exists
+
+If an existing component is close but not fully sufficient, Claude should prefer extending or enhancing the shared component in a safe reusable way rather than creating a duplicate private version inside the new component.
+
+## API Design
+
+Component props should be:
+- clear
+- minimal
+- composable
+- strongly typed
+
+Prefer explicit prop names.
+Avoid ambiguous props.
+Avoid inconsistent naming across similar components.
+
+## Variants
+
+When possible, model states and types in a structured way.
+
+Possible patterns:
+- variant maps
+- configuration objects
+- typed enums/unions
+- helper functions for class generation
+
+Avoid scattered conditional logic when a component has many states and types.
+
+## Documentation Alignment
+
+When implementing components, align with the design system documentation pages.
+
+If documentation describes:
+- breakpoints
+- responsiveness
+- helper text
+- validation states
+- icons
+- copy action
+- currency suffixes/prefixes
+
+the component implementation should reflect those rules.
+
+## Reusability
+
+Build components for reuse, not only for one screen.
+
+Do not:
+- couple components to page-specific business logic
+- hardcode labels or content
+- create component behavior that only works for one product screen
+
+## Exports
+
+Each component should be exported cleanly from its folder and through the package index when appropriate.
+
+Maintain a predictable export structure.
+
+## When Claude Works in This Folder
+
+Claude should:
+- inspect existing component patterns first
+- follow the state/type model strictly
+- preserve consistency with the design system
+- prefer maintainable abstractions
+- avoid inventing undocumented variants
+- keep implementation scalable for future states and types
+- reuse existing components before creating new internal duplicates
+- prefer composition over rebuilding existing UI primitives
+
+## Theme and RTL Requirements
+
+Every component in this folder must support:
+- light mode
+- dark mode
+- RTL layout for Arabic
+
+Component implementations must not assume LTR-only layout behavior. They should support RTL layout behavior as well.
+
+Use direction-aware alignment and spacing.
+Check icons, prefix/suffix content, helper text, validation states, and inline actions in RTL.

package/src/components/CalendarHeader/CalendarHeader.tsx

@@ -0,0 +1,224 @@
+'use client';
+
+import { forwardRef } from 'react';
+import { cn } from '../../lib/cn';
+import { Button } from '../Button';
+import { ButtonMenu } from '../ButtonMenu';
+import {
+  ArrowLeftIcon,
+  ArrowRightIcon,
+  ChevronDownIcon,
+} from '../../icons/IconFactory';
+import type { CalendarHeaderProps } from './CalendarHeader.types';
+import {
+  ROOT_DESKTOP,
+  ROOT_DESKTOP_CENTER,
+  ROOT_MOBILE,
+  DUAL_MENUS_WRAP,
+  DUAL_ARROWS_WRAP,
+  MOBILE_LABEL,
+  RTL_FLIP_ICON,
+} from './CalendarHeader.variants';
+
+/**
+ * CalendarHeader — the top row of a calendar grid.
+ *
+ * Presents the current month / year and prev / next navigation. Behaviour
+ * is split into four Figma-backed layouts (see {@link CalendarHeaderProps}):
+ * desktop dual, desktop centered, mobile compact, mobile centered.
+ *
+ * Composition
+ * ───────────
+ *   Month / year dropdowns   →  `<ButtonMenu variant="transparent">`
+ *   Arrow nav buttons        →  `<Button variant="transparent" iconOnly>`
+ *   Mobile plain label       →  native `<span>` with typography tokens
+ *   Icons                    →  `ArrowLeftIcon`, `ArrowRightIcon`,
+ *                               `ChevronDownIcon` from the IconFactory
+ *
+ * RTL
+ * ───
+ *   Arrow glyphs are physical (they point a fixed direction) so a
+ *   `rtl:rotate-180` wrapper on each icon preserves the semantic meaning
+ *   of "previous" / "next" when an ancestor has `dir="rtl"`.
+ */
+export const CalendarHeader = forwardRef<HTMLDivElement, CalendarHeaderProps>(
+  function CalendarHeader(
+    {
+      month,
+      year,
+      center = false,
+      mobile = false,
+      onMonthClick,
+      onYearClick,
+      onLabelClick,
+      onPrevious,
+      onNext,
+      disabled = false,
+      previousLabel = 'Previous month',
+      nextLabel = 'Next month',
+      monthMenuLabel = 'Select month',
+      yearMenuLabel = 'Select year',
+      labelMenuLabel = 'Select month and year',
+      className,
+      ...rest
+    },
+    ref,
+  ) {
+    /* ── Reused fragments ───────────────────────────────────── */
+
+    const prevIcon = (
+      <span className={RTL_FLIP_ICON}>
+        <ArrowLeftIcon />
+      </span>
+    );
+
+    const nextIcon = (
+      <span className={RTL_FLIP_ICON}>
+        <ArrowRightIcon />
+      </span>
+    );
+
+    const buttonSize = mobile ? 'sm' : 'lg';
+
+    const prevButton = (
+      <Button
+        variant="transparent"
+        size={buttonSize}
+        iconOnly
+        leadingIcon={prevIcon}
+        onClick={onPrevious}
+        disabled={disabled}
+        aria-label={previousLabel}
+        data-slot="calendar-header-prev"
+      />
+    );
+
+    const nextButton = (
+      <Button
+        variant="transparent"
+        size={buttonSize}
+        iconOnly
+        leadingIcon={nextIcon}
+        onClick={onNext}
+        disabled={disabled}
+        aria-label={nextLabel}
+        data-slot="calendar-header-next"
+      />
+    );
+
+    /* ── Mobile layouts ─────────────────────────────────────── */
+
+    if (mobile) {
+      if (center) {
+        return (
+          <div
+            ref={ref}
+            data-slot="calendar-header"
+            data-layout="mobile-center"
+            className={cn(ROOT_MOBILE, className)}
+            {...rest}
+          >
+            {prevButton}
+            <span className={MOBILE_LABEL} data-slot="calendar-header-label">
+              {month} {year}
+            </span>
+            {nextButton}
+          </div>
+        );
+      }
+
+      return (
+        <div
+          ref={ref}
+          data-slot="calendar-header"
+          data-layout="mobile"
+          className={cn(ROOT_MOBILE, className)}
+          {...rest}
+        >
+          <span className={MOBILE_LABEL} data-slot="calendar-header-label">
+            {month} {year}
+          </span>
+          <Button
+            variant="transparent"
+            size="sm"
+            iconOnly
+            leadingIcon={<ChevronDownIcon />}
+            onClick={onLabelClick}
+            disabled={disabled}
+            aria-label={labelMenuLabel}
+            data-slot="calendar-header-label-trigger"
+          />
+          {nextButton}
+        </div>
+      );
+    }
+
+    /* ── Desktop centered layout ────────────────────────────── */
+
+    if (center) {
+      return (
+        <div
+          ref={ref}
+          data-slot="calendar-header"
+          data-layout="desktop-center"
+          className={cn(ROOT_DESKTOP_CENTER, className)}
+          {...rest}
+        >
+          {prevButton}
+          <ButtonMenu
+            variant="transparent"
+            size="lg"
+            onClick={onLabelClick}
+            disabled={disabled}
+            aria-label={labelMenuLabel}
+            data-slot="calendar-header-label-menu"
+          >
+            {month} {year}
+          </ButtonMenu>
+          {nextButton}
+        </div>
+      );
+    }
+
+    /* ── Desktop dual layout (default) ──────────────────────── */
+
+    return (
+      <div
+        ref={ref}
+        data-slot="calendar-header"
+        data-layout="desktop"
+        className={cn(ROOT_DESKTOP, className)}
+        {...rest}
+      >
+        <div className={DUAL_MENUS_WRAP}>
+          <ButtonMenu
+            variant="transparent"
+            size="lg"
+            onClick={onMonthClick}
+            disabled={disabled}
+            aria-label={monthMenuLabel}
+            data-slot="calendar-header-month"
+          >
+            {month}
+          </ButtonMenu>
+          <ButtonMenu
+            variant="transparent"
+            size="lg"
+            onClick={onYearClick}
+            disabled={disabled}
+            aria-label={yearMenuLabel}
+            data-slot="calendar-header-year"
+          >
+            {year}
+          </ButtonMenu>
+        </div>
+        <div className={DUAL_ARROWS_WRAP}>
+          {prevButton}
+          {nextButton}
+        </div>
+      </div>
+    );
+  },
+);
+
+CalendarHeader.displayName = 'CalendarHeader';

package/src/components/CalendarHeader/CalendarHeader.types.ts

@@ -0,0 +1,51 @@
+import type { HTMLAttributes, MouseEventHandler, ReactNode } from 'react';
+
+export interface CalendarHeaderProps extends HTMLAttributes<HTMLDivElement> {
+  /** Month label (e.g. "December" / "ديسمبر"). */
+  month: ReactNode;
+  /** Year label (e.g. "2025"). */
+  year: ReactNode;
+  /**
+   * Layout style.
+   *   `false` (default) — month and year menus sit on the start edge, prev/next
+   *                        arrows on the end edge.
+   *   `true`            — a single combined "Month Year" menu is centered
+   *                        between the prev/next arrows.
+   */
+  center?: boolean;
+  /**
+   * Compact mobile layout. When `true`:
+   *   • The month/year dropdowns collapse into a plain label (with a
+   *     chevron-trigger in the non-centered variant).
+   *   • Arrow buttons shrink to `size="sm"` (16 px icon).
+   */
+  mobile?: boolean;
+  /** Fired when the dual-layout month menu is clicked. */
+  onMonthClick?: MouseEventHandler<HTMLButtonElement>;
+  /** Fired when the dual-layout year menu is clicked. */
+  onYearClick?: MouseEventHandler<HTMLButtonElement>;
+  /**
+   * Fired when the combined (center-layout) menu button or the mobile
+   * chevron trigger is clicked. Typically used to open a month/year picker.
+   */
+  onLabelClick?: MouseEventHandler<HTMLButtonElement>;
+  /** Fired when the "previous" arrow is clicked. */
+  onPrevious?: MouseEventHandler<HTMLButtonElement>;
+  /** Fired when the "next" arrow is clicked. */
+  onNext?: MouseEventHandler<HTMLButtonElement>;
+  /** Disables every interactive child. */
+  disabled?: boolean;
+  /** Accessible label for the previous-month button. Default `"Previous month"`. */
+  previousLabel?: string;
+  /** Accessible label for the next-month button. Default `"Next month"`. */
+  nextLabel?: string;
+  /** Accessible label for the month menu (dual layout). Default `"Select month"`. */
+  monthMenuLabel?: string;
+  /** Accessible label for the year menu (dual layout). Default `"Select year"`. */
+  yearMenuLabel?: string;
+  /**
+   * Accessible label for the combined/mobile label trigger.
+   * Default `"Select month and year"`.
+   */
+  labelMenuLabel?: string;
+}