@mks2508/mks-ui 0.1.4 → 0.2.1

package/src/react-ui/ui/Accordion/Accordion.types.ts

@@ -0,0 +1,199 @@
+/**
+ * Type definitions for the Accordion component.
+ *
+ * All interfaces follow the IPrefix convention. Type aliases do not.
+ * Slot types define the visual regions available for style overrides.
+ *
+ * @module @mks2508/mks-ui/react/ui/Accordion/Accordion.types
+ */
+
+import type { Accordion as AccordionPrimitive } from '@base-ui/react/accordion';
+import type { HTMLMotionProps } from 'motion/react';
+
+import type { IBaseConfig, SlotOverrides } from '@/core/types';
+import type { AccordionVariantProps } from './Accordion.styles';
+
+// ---------------------------------------------------------------------------
+// Slot type
+// ---------------------------------------------------------------------------
+
+/**
+ * Named visual regions of the Accordion that can be styled via the `slots` prop.
+ *
+ * | Slot        | Element                                     |
+ * |-------------|---------------------------------------------|
+ * | `root`      | Outer accordion container                   |
+ * | `item`      | Individual collapsible section               |
+ * | `header`    | Header wrapper around the trigger            |
+ * | `trigger`   | Clickable element that toggles the panel     |
+ * | `panel`     | Collapsible content area with animation      |
+ *
+ * @example
+ * ```tsx
+ * <Accordion slots={{ trigger: 'text-cyan-400', panel: 'bg-zinc-900/50' }} />
+ * ```
+ */
+export type AccordionSlot = 'root' | 'item' | 'header' | 'trigger' | 'panel';
+
+// ---------------------------------------------------------------------------
+// Context types (no IPrefix — type aliases)
+// ---------------------------------------------------------------------------
+
+/**
+ * Internal context for the Accordion root, tracks the current value.
+ */
+export type AccordionContextType = {
+  /** Currently expanded item value(s). */
+  value: string | string[] | undefined;
+  /** Setter to update the expanded item value(s). */
+  setValue: (value: string | string[] | undefined) => void;
+};
+
+/**
+ * Internal context for an individual AccordionItem, tracks open state.
+ */
+export type AccordionItemContextType = {
+  /** Whether this item's panel is currently expanded. */
+  isOpen: boolean;
+  /** Setter to toggle this item's open state. */
+  setIsOpen: (open: boolean) => void;
+};
+
+// ---------------------------------------------------------------------------
+// Config (IPrefix — interface)
+// ---------------------------------------------------------------------------
+
+/**
+ * Behavioral configuration for the Accordion component.
+ * Extends {@link IBaseConfig} with accordion-specific options.
+ *
+ * @example
+ * ```tsx
+ * <Accordion config={{ keepRendered: true, animation: { duration: 0.4 } }} />
+ * ```
+ */
+export interface IAccordionConfig extends IBaseConfig {
+  /**
+   * When `true`, accordion panels remain in the DOM when collapsed
+   * (hidden visually but not unmounted). Useful for preserving
+   * form state or avoiding expensive re-renders.
+   *
+   * @default false
+   */
+  keepRendered?: boolean;
+}
+
+// ---------------------------------------------------------------------------
+// Component prop interfaces (IPrefix)
+// ---------------------------------------------------------------------------
+
+/**
+ * Props for the root Accordion component.
+ *
+ * @example
+ * ```tsx
+ * <Accordion
+ *   variant="bordered"
+ *   defaultValue={['item-1']}
+ *   slots={{ root: 'bg-muted/30', trigger: 'font-semibold' }}
+ * >
+ *   <AccordionItem value="item-1">...</AccordionItem>
+ * </Accordion>
+ * ```
+ */
+export interface IAccordionProps
+  extends Omit<
+      React.ComponentProps<typeof AccordionPrimitive.Root>,
+      'className'
+    >,
+    AccordionVariantProps {
+  /** Additional CSS class applied to the root element. */
+  className?: string;
+  /** Style overrides for individual visual regions. */
+  slots?: SlotOverrides<AccordionSlot>;
+  /** Behavioral configuration. */
+  config?: IAccordionConfig;
+}
+
+/**
+ * Props for an individual AccordionItem.
+ *
+ * @example
+ * ```tsx
+ * <AccordionItem value="item-1" className="border-none">
+ *   <AccordionHeader>...</AccordionHeader>
+ *   <AccordionPanel>Content</AccordionPanel>
+ * </AccordionItem>
+ * ```
+ */
+export interface IAccordionItemProps
+  extends React.ComponentProps<typeof AccordionPrimitive.Item> {
+  /** Style overrides for individual visual regions. */
+  slots?: SlotOverrides<AccordionSlot>;
+}
+
+/**
+ * Props for the AccordionHeader wrapper.
+ *
+ * @example
+ * ```tsx
+ * <AccordionHeader className="bg-muted/20">
+ *   <AccordionTrigger>Section Title</AccordionTrigger>
+ * </AccordionHeader>
+ * ```
+ */
+export interface IAccordionHeaderProps
+  extends React.ComponentProps<typeof AccordionPrimitive.Header> {
+  /** Style overrides for individual visual regions. */
+  slots?: SlotOverrides<AccordionSlot>;
+}
+
+/**
+ * Props for the AccordionTrigger button.
+ *
+ * @example
+ * ```tsx
+ * <AccordionTrigger className="text-foreground hover:text-primary">
+ *   Click to expand
+ * </AccordionTrigger>
+ * ```
+ */
+export interface IAccordionTriggerProps
+  extends React.ComponentProps<typeof AccordionPrimitive.Trigger> {
+  /** Style overrides for individual visual regions. */
+  slots?: SlotOverrides<AccordionSlot>;
+}
+
+/**
+ * Props for the AccordionPanel collapsible content area.
+ *
+ * Extends Motion's HTMLMotionProps for full animation control.
+ * The `keepMounted` and `render` props from the base primitive are
+ * omitted because they are managed internally by the animation logic.
+ *
+ * @example
+ * ```tsx
+ * <AccordionPanel
+ *   keepRendered
+ *   transition={{ duration: 0.5, ease: 'easeOut' }}
+ * >
+ *   <p>Collapsible content here.</p>
+ * </AccordionPanel>
+ * ```
+ */
+export interface IAccordionPanelProps
+  extends Omit<
+      Omit<React.ComponentProps<typeof AccordionPrimitive.Panel>, 'keepMounted' | 'render'>,
+      keyof HTMLMotionProps<'div'>
+    >,
+    HTMLMotionProps<'div'> {
+  /**
+   * When `true`, the panel stays mounted in the DOM even when collapsed.
+   * Useful for preserving internal state (e.g. form inputs).
+   *
+   * @default false
+   */
+  keepRendered?: boolean;
+  /** Style overrides for individual visual regions. */
+  slots?: SlotOverrides<AccordionSlot>;
+}

package/src/react-ui/ui/Accordion/index.tsx

@@ -0,0 +1,362 @@
+'use client';
+
+/**
+ * Accordion component with animated expand/collapse panels.
+ *
+ * Built on top of Base UI's Accordion primitive with Motion (Framer Motion)
+ * animations. Supports controlled and uncontrolled modes, multiple expanded
+ * items, and the StyleSlots pattern for granular style overrides.
+ *
+ * @module @mks2508/mks-ui/react/ui/Accordion
+ *
+ * @example
+ * ```tsx
+ * import {
+ *   Accordion,
+ *   AccordionItem,
+ *   AccordionHeader,
+ *   AccordionTrigger,
+ *   AccordionPanel,
+ * } from '@mks2508/mks-ui';
+ *
+ * function FAQ() {
+ *   return (
+ *     <Accordion variant="bordered" defaultValue={['q1']}>
+ *       <AccordionItem value="q1">
+ *         <AccordionHeader>
+ *           <AccordionTrigger>What is mks-ui?</AccordionTrigger>
+ *         </AccordionHeader>
+ *         <AccordionPanel>
+ *           A modern React component library with animations.
+ *         </AccordionPanel>
+ *       </AccordionItem>
+ *     </Accordion>
+ *   );
+ * }
+ * ```
+ */
+
+import * as React from 'react';
+import { Accordion as AccordionPrimitive } from '@base-ui/react/accordion';
+import { AnimatePresence, motion } from 'motion/react';
+
+import { cn } from '@/react-ui/lib/utils';
+import { getStrictContext } from '@/react-ui/lib/get-strict-context';
+import { useControlledState } from '@/react-ui/hooks/State/UseControlledState';
+
+import { AccordionStyles, accordionVariants } from './Accordion.styles';
+import type {
+  AccordionContextType,
+  AccordionItemContextType,
+  IAccordionProps,
+  IAccordionItemProps,
+  IAccordionHeaderProps,
+  IAccordionTriggerProps,
+  IAccordionPanelProps,
+} from './Accordion.types';
+
+// ---------------------------------------------------------------------------
+// Context
+// ---------------------------------------------------------------------------
+
+const [AccordionProvider, useAccordion] =
+  getStrictContext<AccordionContextType>('AccordionContext');
+
+const [AccordionItemProvider, useAccordionItem] =
+  getStrictContext<AccordionItemContextType>('AccordionItemContext');
+
+// ---------------------------------------------------------------------------
+// Accordion (root)
+// ---------------------------------------------------------------------------
+
+/**
+ * Root Accordion container. Manages which items are expanded and
+ * provides context to child components.
+ *
+ * Supports both controlled (`value` + `onValueChange`) and uncontrolled
+ * (`defaultValue`) usage patterns.
+ *
+ * @param props - {@link IAccordionProps}
+ * @returns The rendered accordion container
+ *
+ * @example
+ * ```tsx
+ * // Uncontrolled with default expansion
+ * <Accordion defaultValue={['item-1']}>
+ *   <AccordionItem value="item-1">...</AccordionItem>
+ *   <AccordionItem value="item-2">...</AccordionItem>
+ * </Accordion>
+ *
+ * // Controlled
+ * const [value, setValue] = useState<string[]>(['item-1']);
+ * <Accordion value={value} onValueChange={setValue} variant="bordered">
+ *   ...
+ * </Accordion>
+ * ```
+ */
+function Accordion({
+  variant,
+  className,
+  slots,
+  config: _config,
+  ...props
+}: IAccordionProps) {
+  const [value, setValue] = useControlledState<string | string[] | undefined>({
+    value: props?.value,
+    defaultValue: props?.defaultValue,
+    onChange: props?.onValueChange as (
+      value: string | string[] | undefined,
+    ) => void,
+  });
+
+  return (
+    <AccordionProvider value={{ value, setValue }}>
+      <AccordionPrimitive.Root
+        data-slot="accordion"
+        className={cn(accordionVariants({ variant }), slots?.root, className)}
+        {...props}
+        onValueChange={setValue}
+      />
+    </AccordionProvider>
+  );
+}
+
+// ---------------------------------------------------------------------------
+// AccordionItem
+// ---------------------------------------------------------------------------
+
+/**
+ * Individual collapsible section within an Accordion.
+ * Tracks its own open/closed state derived from the parent context.
+ *
+ * @param props - {@link IAccordionItemProps}
+ * @returns The rendered accordion item
+ *
+ * @example
+ * ```tsx
+ * <AccordionItem value="section-1" className="border-primary/20">
+ *   <AccordionHeader>
+ *     <AccordionTrigger>Section Title</AccordionTrigger>
+ *   </AccordionHeader>
+ *   <AccordionPanel>Section content</AccordionPanel>
+ * </AccordionItem>
+ * ```
+ */
+function AccordionItem({ slots, className, ...props }: IAccordionItemProps) {
+  const { value } = useAccordion();
+  const [isOpen, setIsOpen] = React.useState(
+    value?.includes(props?.value) ?? false,
+  );
+
+  React.useEffect(() => {
+    setIsOpen(value?.includes(props?.value) ?? false);
+  }, [value, props?.value]);
+
+  return (
+    <AccordionItemProvider value={{ isOpen, setIsOpen }}>
+      <AccordionPrimitive.Item
+        data-slot="accordion-item"
+        className={cn(AccordionStyles.item, slots?.item, className)}
+        {...props}
+      />
+    </AccordionItemProvider>
+  );
+}
+
+// ---------------------------------------------------------------------------
+// AccordionHeader
+// ---------------------------------------------------------------------------
+
+/**
+ * Header wrapper for an accordion trigger. Provides semantic structure
+ * and consistent spacing around the trigger element.
+ *
+ * @param props - {@link IAccordionHeaderProps}
+ * @returns The rendered accordion header
+ *
+ * @example
+ * ```tsx
+ * <AccordionHeader className="bg-muted/10">
+ *   <AccordionTrigger>Section Title</AccordionTrigger>
+ * </AccordionHeader>
+ * ```
+ */
+function AccordionHeader({
+  slots,
+  className,
+  ...props
+}: IAccordionHeaderProps) {
+  return (
+    <AccordionPrimitive.Header
+      data-slot="accordion-header"
+      className={cn(AccordionStyles.header, slots?.header, className)}
+      {...props}
+    />
+  );
+}
+
+// ---------------------------------------------------------------------------
+// AccordionTrigger
+// ---------------------------------------------------------------------------
+
+/**
+ * Clickable trigger that toggles the associated AccordionPanel.
+ * Rendered as a button for accessibility.
+ *
+ * @param props - {@link IAccordionTriggerProps}
+ * @returns The rendered accordion trigger
+ *
+ * @example
+ * ```tsx
+ * <AccordionTrigger className="text-foreground hover:text-primary">
+ *   Click to expand
+ * </AccordionTrigger>
+ * ```
+ */
+function AccordionTrigger({
+  slots,
+  className,
+  ...props
+}: IAccordionTriggerProps) {
+  return (
+    <AccordionPrimitive.Trigger
+      data-slot="accordion-trigger"
+      className={cn(AccordionStyles.trigger, slots?.trigger, className)}
+      {...props}
+    />
+  );
+}
+
+// ---------------------------------------------------------------------------
+// AccordionPanel
+// ---------------------------------------------------------------------------
+
+/**
+ * Animated collapsible panel that shows/hides content with a smooth
+ * height transition powered by Motion (Framer Motion).
+ *
+ * Uses a mask-image technique for a polished reveal/hide effect.
+ * When `keepRendered` is `true`, the panel stays in the DOM even when
+ * collapsed (useful for preserving form state).
+ *
+ * @param props - {@link IAccordionPanelProps}
+ * @returns The rendered animated accordion panel
+ *
+ * @example
+ * ```tsx
+ * // Standard panel (unmounts on collapse)
+ * <AccordionPanel>
+ *   <p>Content revealed on expand</p>
+ * </AccordionPanel>
+ *
+ * // Persistent panel (stays mounted)
+ * <AccordionPanel keepRendered transition={{ duration: 0.5 }}>
+ *   <form>...</form>
+ * </AccordionPanel>
+ * ```
+ */
+function AccordionPanel({
+  transition = { duration: 0.35, ease: 'easeInOut' },
+  hiddenUntilFound,
+  keepRendered = false,
+  slots,
+  className,
+  ...props
+}: IAccordionPanelProps) {
+  const { isOpen } = useAccordionItem();
+
+  const maskStyle: React.CSSProperties = {
+    maskImage:
+      'linear-gradient(black var(--mask-stop), transparent var(--mask-stop))',
+    WebkitMaskImage:
+      'linear-gradient(black var(--mask-stop), transparent var(--mask-stop))',
+    overflow: 'hidden',
+  };
+
+  return (
+    <AnimatePresence>
+      {keepRendered ? (
+        <AccordionPrimitive.Panel
+          hidden={false}
+          hiddenUntilFound={hiddenUntilFound}
+          keepMounted
+          render={
+            <motion.div
+              key="accordion-panel"
+              data-slot="accordion-panel"
+              className={cn(AccordionStyles.panel, slots?.panel, className)}
+              initial={{ height: 0, opacity: 0, '--mask-stop': '0%', y: 20 }}
+              animate={
+                isOpen
+                  ? { height: 'auto', opacity: 1, '--mask-stop': '100%', y: 0 }
+                  : { height: 0, opacity: 0, '--mask-stop': '0%', y: 20 }
+              }
+              transition={transition}
+              style={maskStyle}
+              {...(props as any)}
+            />
+          }
+        />
+      ) : (
+        isOpen && (
+          <AccordionPrimitive.Panel
+            hidden={false}
+            hiddenUntilFound={hiddenUntilFound}
+            keepMounted
+            render={
+              <motion.div
+                key="accordion-panel"
+                data-slot="accordion-panel"
+                className={cn(AccordionStyles.panel, slots?.panel, className)}
+                initial={{ height: 0, opacity: 0, '--mask-stop': '0%', y: 20 }}
+                animate={{
+                  height: 'auto',
+                  opacity: 1,
+                  '--mask-stop': '100%',
+                  y: 0,
+                }}
+                exit={{ height: 0, opacity: 0, '--mask-stop': '0%', y: 20 }}
+                transition={transition}
+                style={maskStyle}
+                {...props}
+              />
+            }
+          />
+        )
+      )}
+    </AnimatePresence>
+  );
+}
+
+// ---------------------------------------------------------------------------
+// Exports
+// ---------------------------------------------------------------------------
+
+export {
+  Accordion,
+  AccordionItem,
+  AccordionHeader,
+  AccordionTrigger,
+  AccordionPanel,
+  useAccordionItem,
+};
+
+// Re-export types
+export type {
+  IAccordionProps,
+  IAccordionItemProps,
+  IAccordionHeaderProps,
+  IAccordionTriggerProps,
+  IAccordionPanelProps,
+  IAccordionConfig,
+  AccordionSlot,
+  AccordionContextType,
+  AccordionItemContextType,
+} from './Accordion.types';
+
+// Re-export styles and variants
+export {
+  AccordionStyles,
+  accordionVariants,
+  type AccordionVariantProps,
+} from './Accordion.styles';

package/src/react-ui/ui/AlertDialog/AlertDialog.styles.ts

@@ -0,0 +1,38 @@
+/**
+ * Style slots for the AlertDialog component.
+ *
+ * Defines the visual regions (slots) available for style overrides.
+ * AlertDialog does not use CVA variants since its visual appearance
+ * is primarily controlled by the `from` flip direction prop.
+ *
+ * @module @mks2508/mks-ui/react/ui/AlertDialog/AlertDialog.styles
+ */
+
+import type { StyleSlots } from '@/core/types';
+import type { AlertDialogSlot } from './AlertDialog.types';
+
+/**
+ * Default Tailwind classes for each visual region of the AlertDialog.
+ *
+ * These classes are applied as base styles and can be overridden
+ * via the `slots` prop on individual sub-components.
+ *
+ * @example
+ * ```typescript
+ * import { AlertDialogStyles } from '@mks2508/mks-ui';
+ *
+ * // Access individual slot defaults
+ * console.log(AlertDialogStyles.backdrop); // backdrop base classes
+ * console.log(AlertDialogStyles.popup);    // popup container classes
+ * ```
+ */
+export const AlertDialogStyles: StyleSlots<AlertDialogSlot> = {
+  root: '',
+  backdrop: 'fixed inset-0 z-50 bg-black/80',
+  popup: 'fixed left-1/2 top-1/2 z-50 grid w-full max-w-lg -translate-x-1/2 -translate-y-1/2 gap-4 border border-border bg-background p-6 shadow-lg sm:rounded-lg',
+  header: 'flex flex-col space-y-2 text-center sm:text-left',
+  footer: 'flex flex-col-reverse sm:flex-row sm:justify-end sm:space-x-2',
+  title: 'text-lg font-semibold',
+  description: 'text-sm text-muted-foreground',
+  close: '',
+};