@mihcm/ui 0.14.1

package/src/Carousel.tsx

@@ -0,0 +1,292 @@
+'use client';
+
+/**
+ * Carousel (web variant — React DOM).
+ *
+ * Composable carousel powered by `embla-carousel-react`.
+ *
+ *   <Carousel>
+ *     <CarouselContent>
+ *       <CarouselItem>Slide 1</CarouselItem>
+ *       <CarouselItem>Slide 2</CarouselItem>
+ *       <CarouselItem>Slide 3</CarouselItem>
+ *     </CarouselContent>
+ *     <CarouselPrevious />
+ *     <CarouselNext />
+ *   </Carousel>
+ *
+ * Wiki: docs/components/Carousel.md
+ */
+import {
+  createContext,
+  forwardRef,
+  useCallback,
+  useContext,
+  useEffect,
+  useState,
+  type HTMLAttributes,
+  type KeyboardEvent,
+} from 'react';
+import useEmblaCarousel, {
+  type UseEmblaCarouselType,
+} from 'embla-carousel-react';
+import { Button, type ButtonProps } from './Button.js';
+import { cn } from './internal/cn.js';
+
+/* ── Inline icons (avoids a lucide-react dep on the ui package) ──── */
+
+function ArrowLeftIcon() {
+  return (
+    <svg
+      aria-hidden="true"
+      xmlns="http://www.w3.org/2000/svg"
+      viewBox="0 0 24 24"
+      fill="none"
+      stroke="currentColor"
+      strokeWidth={2}
+      strokeLinecap="round"
+      strokeLinejoin="round"
+      className="h-4 w-4"
+    >
+      <path d="m12 19-7-7 7-7" />
+      <path d="M19 12H5" />
+    </svg>
+  );
+}
+
+function ArrowRightIcon() {
+  return (
+    <svg
+      aria-hidden="true"
+      xmlns="http://www.w3.org/2000/svg"
+      viewBox="0 0 24 24"
+      fill="none"
+      stroke="currentColor"
+      strokeWidth={2}
+      strokeLinecap="round"
+      strokeLinejoin="round"
+      className="h-4 w-4"
+    >
+      <path d="M5 12h14" />
+      <path d="m12 5 7 7-7 7" />
+    </svg>
+  );
+}
+
+/* ── Types ────────────────────────────────────────────────────────── */
+
+export type CarouselApi = UseEmblaCarouselType[1];
+type UseCarouselParams = Parameters<typeof useEmblaCarousel>;
+type CarouselOptions = UseCarouselParams[0];
+type CarouselPlugin = UseCarouselParams[1];
+
+export type CarouselProps = {
+  opts?: CarouselOptions;
+  plugins?: CarouselPlugin;
+  orientation?: 'horizontal' | 'vertical';
+  setApi?: (api: CarouselApi) => void;
+};
+
+type CarouselContextValue = {
+  carouselRef: ReturnType<typeof useEmblaCarousel>[0];
+  api: ReturnType<typeof useEmblaCarousel>[1];
+  scrollPrev: () => void;
+  scrollNext: () => void;
+  canScrollPrev: boolean;
+  canScrollNext: boolean;
+} & CarouselProps;
+
+/* ── Context ──────────────────────────────────────────────────────── */
+
+const CarouselContext = createContext<CarouselContextValue | null>(null);
+
+export function useCarousel() {
+  const ctx = useContext(CarouselContext);
+  if (!ctx) throw new Error('useCarousel must be used within a <Carousel>');
+  return ctx;
+}
+
+/* ── Root ──────────────────────────────────────────────────────────── */
+
+export const Carousel = forwardRef<
+  HTMLDivElement,
+  HTMLAttributes<HTMLDivElement> & CarouselProps
+>(function Carousel(
+  { orientation = 'horizontal', opts, setApi, plugins, className, children, ...props },
+  ref,
+) {
+  const [carouselRef, api] = useEmblaCarousel(
+    { ...opts, axis: orientation === 'horizontal' ? 'x' : 'y' },
+    plugins,
+  );
+  const [canScrollPrev, setCanScrollPrev] = useState(false);
+  const [canScrollNext, setCanScrollNext] = useState(false);
+
+  const onSelect = useCallback((emblaApi: NonNullable<CarouselApi>) => {
+    setCanScrollPrev(emblaApi.canScrollPrev());
+    setCanScrollNext(emblaApi.canScrollNext());
+  }, []);
+
+  const scrollPrev = useCallback(() => api?.scrollPrev(), [api]);
+  const scrollNext = useCallback(() => api?.scrollNext(), [api]);
+
+  const handleKeyDown = useCallback(
+    (event: KeyboardEvent<HTMLDivElement>) => {
+      const prevKey = orientation === 'horizontal' ? 'ArrowLeft' : 'ArrowUp';
+      const nextKey = orientation === 'horizontal' ? 'ArrowRight' : 'ArrowDown';
+
+      if (event.key === prevKey) {
+        event.preventDefault();
+        scrollPrev();
+      } else if (event.key === nextKey) {
+        event.preventDefault();
+        scrollNext();
+      }
+    },
+    [orientation, scrollPrev, scrollNext],
+  );
+
+  useEffect(() => {
+    if (!api || !setApi) return;
+    setApi(api);
+  }, [api, setApi]);
+
+  useEffect(() => {
+    if (!api) return;
+    // Initial state sync — necessary for Embla's deferred initialisation
+    // eslint-disable-next-line react-hooks/set-state-in-effect
+    onSelect(api);
+    api.on('reInit', onSelect);
+    api.on('select', onSelect);
+    return () => {
+      api.off('select', onSelect);
+      api.off('reInit', onSelect);
+    };
+  }, [api, onSelect]);
+
+  return (
+    <CarouselContext.Provider
+      value={{
+        carouselRef,
+        api,
+        opts,
+        orientation,
+        scrollPrev,
+        scrollNext,
+        canScrollPrev,
+        canScrollNext,
+      }}
+    >
+      <div
+        ref={ref}
+        onKeyDownCapture={handleKeyDown}
+        className={cn('relative', className)}
+        role="region"
+        aria-roledescription="carousel"
+        {...props}
+      >
+        {children}
+      </div>
+    </CarouselContext.Provider>
+  );
+});
+
+/* ── Content ──────────────────────────────────────────────────────── */
+
+export const CarouselContent = forwardRef<
+  HTMLDivElement,
+  HTMLAttributes<HTMLDivElement>
+>(function CarouselContent({ className, ...props }, ref) {
+  const { carouselRef, orientation } = useCarousel();
+  return (
+    <div ref={carouselRef} className="overflow-hidden">
+      <div
+        ref={ref}
+        className={cn(
+          'flex',
+          orientation === 'horizontal' ? '-ml-4' : '-mt-4 flex-col',
+          className,
+        )}
+        {...props}
+      />
+    </div>
+  );
+});
+
+/* ── Item ──────────────────────────────────────────────────────────── */
+
+export const CarouselItem = forwardRef<
+  HTMLDivElement,
+  HTMLAttributes<HTMLDivElement>
+>(function CarouselItem({ className, ...props }, ref) {
+  const { orientation } = useCarousel();
+  return (
+    <div
+      ref={ref}
+      role="group"
+      aria-roledescription="slide"
+      className={cn(
+        'min-w-0 shrink-0 grow-0 basis-full',
+        orientation === 'horizontal' ? 'pl-4' : 'pt-4',
+        className,
+      )}
+      {...props}
+    />
+  );
+});
+
+/* ── Previous ────────────────────────────────────────────────────── */
+
+export const CarouselPrevious = forwardRef<HTMLButtonElement, ButtonProps>(
+  function CarouselPrevious({ className, variant = 'outline', size = 'icon', ...props }, ref) {
+    const { orientation, scrollPrev, canScrollPrev } = useCarousel();
+    return (
+      <Button
+        ref={ref}
+        variant={variant}
+        size={size}
+        className={cn(
+          'absolute h-8 w-8 rounded-full',
+          orientation === 'horizontal'
+            ? '-left-12 top-1/2 -translate-y-1/2'
+            : '-top-12 left-1/2 -translate-x-1/2 rotate-90',
+          className,
+        )}
+        disabled={!canScrollPrev}
+        onClick={scrollPrev}
+        {...props}
+      >
+        <ArrowLeftIcon />
+        <span className="sr-only">Previous slide</span>
+      </Button>
+    );
+  },
+);
+
+/* ── Next ─────────────────────────────────────────────────────────── */
+
+export const CarouselNext = forwardRef<HTMLButtonElement, ButtonProps>(
+  function CarouselNext({ className, variant = 'outline', size = 'icon', ...props }, ref) {
+    const { orientation, scrollNext, canScrollNext } = useCarousel();
+    return (
+      <Button
+        ref={ref}
+        variant={variant}
+        size={size}
+        className={cn(
+          'absolute h-8 w-8 rounded-full',
+          orientation === 'horizontal'
+            ? '-right-12 top-1/2 -translate-y-1/2'
+            : '-bottom-12 left-1/2 -translate-x-1/2 rotate-90',
+          className,
+        )}
+        disabled={!canScrollNext}
+        onClick={scrollNext}
+        {...props}
+      >
+        <ArrowRightIcon />
+        <span className="sr-only">Next slide</span>
+      </Button>
+    );
+  },
+);

package/src/CategoryBar.tsx

@@ -0,0 +1,85 @@
+'use client';
+
+/**
+ * CategoryBar (web variant).
+ *
+ * Segmented distribution bar for status, risk, and allocation summaries.
+ *
+ * Wiki: docs/components/CategoryBar.md
+ */
+import { forwardRef, type HTMLAttributes, type ReactNode } from 'react';
+import { motion } from 'motion/react';
+import { cn } from './internal/cn.js';
+
+export interface CategoryBarItem {
+  label: ReactNode;
+  value: number;
+  className?: string;
+}
+
+export interface CategoryBarProps extends HTMLAttributes<HTMLDivElement> {
+  data: CategoryBarItem[];
+  valueFormatter?: (value: number, percentage: number) => ReactNode;
+  showLegend?: boolean;
+  legendPosition?: 'top' | 'bottom';
+  barClassName?: string;
+}
+
+export const CategoryBar = forwardRef<HTMLDivElement, CategoryBarProps>(function CategoryBar(
+  {
+    data,
+    valueFormatter = (_value, percentage) => `${Math.round(percentage)}%`,
+    showLegend = true,
+    legendPosition = 'bottom',
+    className,
+    barClassName,
+    ...props
+  },
+  ref,
+) {
+  const total = data.reduce((sum, item) => sum + Math.max(0, item.value), 0);
+
+  const legend = showLegend ? (
+    <div className="flex flex-wrap items-center gap-x-4 gap-y-2 text-xs text-muted-foreground">
+      {data.map((item, index) => {
+        const value = Math.max(0, item.value);
+        const percentage = total > 0 ? (value / total) * 100 : 0;
+        return (
+          <span key={index} className="inline-flex items-center gap-2">
+            <span className={cn('size-2.5 rounded-full bg-primary', item.className)} aria-hidden />
+            <span className="text-foreground">{item.label}</span>
+            <span>{valueFormatter(value, percentage)}</span>
+          </span>
+        );
+      })}
+    </div>
+  ) : null;
+
+  return (
+    <div ref={ref} className={cn('space-y-3', className)} {...props}>
+      {legendPosition === 'top' ? legend : null}
+      <div
+        className={cn('flex h-3 w-full overflow-hidden rounded-full bg-muted', barClassName)}
+        role="img"
+        aria-label={data
+          .map((item) => `${String(item.label)} ${total > 0 ? Math.round((item.value / total) * 100) : 0}%`)
+          .join(', ')}
+      >
+        {data.map((item, index) => {
+          const percentage = total > 0 ? (Math.max(0, item.value) / total) * 100 : 0;
+          return (
+            <motion.span
+              key={index}
+              className={cn('h-full bg-primary transition-[width,background-color] duration-500 ease-out', item.className)}
+              initial={{ width: 0 }}
+              animate={{ width: `${percentage}%` }}
+              transition={{ duration: 0.45, ease: 'easeOut' }}
+              title={`${String(item.label)} ${Math.round(percentage)}%`}
+            />
+          );
+        })}
+      </div>
+      {legendPosition === 'bottom' ? legend : null}
+    </div>
+  );
+});