@kosmeo-ui/react 0.1.0

package/src/components/navigation/tabs/index.tsx

@@ -0,0 +1,49 @@
+"use client";
+
+import { ReactNode } from "react";
+import "./styles.css";
+
+export interface TabItem {
+  key: string;
+  label: ReactNode;
+  content?: ReactNode;
+  disabled?: boolean;
+}
+
+export interface TabsProps {
+  tabs: TabItem[];
+  active: string;
+  onChange: (key: string) => void;
+  /** Render strip only — caller controls content placement. Defaults to false (component renders both). */
+  stripOnly?: boolean;
+}
+
+const Tabs = ({ tabs, active, onChange, stripOnly }: TabsProps) => {
+  const activeTab = tabs.find((t) => t.key === active);
+  return (
+    <div className="k-tabs">
+      <div className="k-tabs-strip" role="tablist">
+        {tabs.map((t) => (
+          <button
+            key={t.key}
+            type="button"
+            role="tab"
+            aria-selected={t.key === active}
+            disabled={t.disabled}
+            className={`k-tabs-button${t.key === active ? " k-tabs-button-active" : ""}`}
+            onClick={() => onChange(t.key)}
+          >
+            {t.label}
+          </button>
+        ))}
+      </div>
+      {!stripOnly && activeTab?.content && (
+        <div className="k-tabs-content" role="tabpanel">
+          {activeTab.content}
+        </div>
+      )}
+    </div>
+  );
+};
+
+export default Tabs;

package/src/components/navigation/tabs/styles.css

@@ -0,0 +1,46 @@
+.k-tabs {
+  display: flex;
+  flex-direction: column;
+}
+
+.k-tabs-strip {
+  display: flex;
+  flex-wrap: wrap;
+  gap: 0.25rem;
+  border-bottom: 0.0625rem solid var(--border-color);
+  margin-bottom: 1rem;
+}
+
+.k-tabs-button {
+  appearance: none;
+  background: transparent;
+  border: none;
+  border-bottom: 0.1875rem solid transparent;
+  color: var(--text-color);
+  cursor: pointer;
+  font-size: 0.9375rem;
+  font-weight: 500;
+  padding: 0.625rem 0.9375rem;
+  margin-bottom: -0.0625rem;
+  transition:
+    color 0.15s ease,
+    border-color 0.15s ease;
+}
+
+.k-tabs-button:hover:not(:disabled) {
+  color: var(--primary-color);
+}
+
+.k-tabs-button-active {
+  color: var(--primary-color);
+  border-bottom-color: var(--primary-color);
+}
+
+.k-tabs-button:disabled {
+  opacity: 0.5;
+  cursor: not-allowed;
+}
+
+.k-tabs-content {
+  flex: 1;
+}

package/src/components/overlays/confirmationModal/index.tsx

@@ -0,0 +1,48 @@
+"use client";
+
+import Button from "../../buttons/button/index.js";
+import Modal from "../modal/index.js";
+
+export interface ConfirmationModalProps {
+  show: boolean;
+  handleHide: () => void;
+  handleConfirm: () => void;
+  title: string;
+  body: string;
+  confirmButtonText: string;
+  cancelButtonText?: string;
+  isLoading?: boolean;
+}
+
+const ConfirmationModal = (props: ConfirmationModalProps) => {
+  return (
+    <Modal
+      show={props.show}
+      title={props.title}
+      onClose={props.handleHide}
+      footerButtons={[
+        <Button
+          key="cancel"
+          variant="secondary"
+          onClick={props.handleHide}
+          disabled={props.isLoading}
+        >
+          {props.cancelButtonText || "Cancel"}
+        </Button>,
+        <Button
+          key="confirm"
+          variant="danger"
+          onClick={props.handleConfirm}
+          isLoading={props.isLoading}
+          disabled={props.isLoading}
+        >
+          {props.confirmButtonText}
+        </Button>,
+      ]}
+    >
+      {props.body}
+    </Modal>
+  );
+};
+
+export default ConfirmationModal;

package/src/components/overlays/modal/index.tsx

@@ -0,0 +1,89 @@
+"use client";
+
+import React, { PropsWithChildren, useEffect, useRef, useState } from "react";
+import useFocusTrap from "../../../hooks/useFocusTrap.js";
+import Button from "../../buttons/button/index.js";
+import Portal from "../portal/index.js";
+import "./styles.css";
+
+export type ModalSize = "sm" | "md" | "lg" | "full";
+
+interface ModalProps extends PropsWithChildren {
+  /** A function that is called when the modal is closed */
+  onClose: () => void;
+  /** **_Optional_** title to appear at the top of the Modal */
+  title?: React.ReactNode;
+  /** **_Optional_** flag for whether or not to show the Modal */
+  show?: boolean;
+  /** Options buttons to add to the bottom of the modal */
+  footerButtons?: React.ReactNode[];
+  /**
+   * **_Optional_** size variant. `full` renders edge-to-edge at ~90% of the
+   * viewport — use for dense content (tables, search results, side-by-side
+   * editors) that would feel cramped at `lg`.
+   */
+  size?: ModalSize;
+}
+
+const Modal = (props: ModalProps) => {
+  const { size = "md" } = props;
+  const [shouldRender, setShouldRender] = useState(props.show);
+  const [isAnimating, setIsAnimating] = useState(false);
+  const contentRef = useRef<HTMLDivElement>(null);
+
+  useEffect(() => {
+    if (props.show) {
+      setIsAnimating(false);
+      setShouldRender(true);
+    } else {
+      setIsAnimating(true);
+      const timer = setTimeout(() => {
+        setIsAnimating(false);
+        setShouldRender(false);
+      }, 200);
+      return () => clearTimeout(timer);
+    }
+  }, [props.show]);
+
+  useEffect(() => {
+    if (!props.show) return;
+    const handler = (e: KeyboardEvent) => {
+      if (e.key === "Escape") props.onClose();
+    };
+    document.addEventListener("keydown", handler);
+    return () => document.removeEventListener("keydown", handler);
+  }, [props.show, props.onClose]);
+
+  useFocusTrap(contentRef, !!props.show && !!shouldRender);
+
+  if (!shouldRender) return null;
+
+  return (
+    <Portal>
+      <div className={`k-modal-overlay ${isAnimating ? "closing" : ""}`}>
+        <div
+          ref={contentRef}
+          className={`k-modal-content ${isAnimating ? "closing" : ""} ${size}`}
+          role="dialog"
+          aria-modal="true"
+        >
+          {props.title && <div className="k-modal-header">{props.title}</div>}
+          <div className="k-modal-body">{props.children}</div>
+          <div className="k-modal-footer">
+            {props.footerButtons ? (
+              props.footerButtons.map((button, index) => (
+                <React.Fragment key={index}>{button}</React.Fragment>
+              ))
+            ) : (
+              <Button onClick={props.onClose} variant="secondary">
+                Close
+              </Button>
+            )}
+          </div>
+        </div>
+      </div>
+    </Portal>
+  );
+};
+
+export default Modal;

package/src/components/overlays/modal/styles.css

@@ -0,0 +1,137 @@
+@keyframes fadeIn {
+  from {
+    opacity: 0;
+  }
+  to {
+    opacity: 1;
+  }
+}
+
+@keyframes fadeOut {
+  from {
+    opacity: 1;
+  }
+  to {
+    opacity: 0;
+  }
+}
+
+@keyframes scaleIn {
+  from {
+    transform: scale(0.95);
+  }
+  to {
+    transform: scale(1);
+  }
+}
+
+@keyframes scaleOut {
+  from {
+    transform: scale(1);
+  }
+  to {
+    transform: scale(0.95);
+  }
+}
+
+.k-modal-overlay {
+  position: fixed;
+  inset: 0;
+  background-color: var(--background-color-overlay);
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  z-index: 9999;
+  padding: 1rem;
+  opacity: 1;
+  pointer-events: auto;
+  animation: fadeIn 0.2s ease-out forwards;
+}
+
+.k-modal-content {
+  background-color: var(--background-color-light);
+  border-radius: 0.5rem;
+  padding: 1rem;
+  box-shadow:
+    0 1.25rem 1.5625rem -0.3125rem var(--shadow-color),
+    0 0.5rem 0.625rem -0.375rem var(--shadow-color);
+  max-width: 40rem;
+  width: 100%;
+  display: flex;
+  flex-direction: column;
+  gap: 1rem;
+  opacity: 1;
+  transform: scale(1);
+  pointer-events: auto;
+  animation: scaleIn 0.2s ease-out forwards;
+  max-height: 80vh;
+  overflow: hidden;
+}
+
+.k-modal-content.sm {
+  max-width: 20rem;
+}
+
+.k-modal-content.md {
+  max-width: 40rem;
+}
+
+.k-modal-content.lg {
+  max-width: 60rem;
+}
+
+.k-modal-content.full {
+  max-width: 90vw;
+  max-height: 90vh;
+  width: 90vw;
+  height: 90vh;
+}
+
+.k-modal-overlay.closing {
+  animation: fadeOut 0.2s ease-in forwards;
+  pointer-events: none;
+}
+
+.k-modal-content.closing {
+  animation: scaleOut 0.2s ease-in forwards;
+  pointer-events: none;
+}
+
+.k-modal-header {
+  padding-bottom: 0.5rem;
+  border-bottom: 0.0625rem solid var(--border-color);
+  font-size: var(--text-size-xl);
+  font-weight: 700;
+  color: var(--text-color);
+}
+
+.k-modal-body {
+  display: flex;
+  flex-direction: column;
+  padding-top: 0.5rem;
+  padding-bottom: 0.5rem;
+  color: var(--text-color-secondary);
+  overflow-y: auto;
+  min-height: 0;
+  flex: 1;
+}
+
+.k-modal-message {
+  font-size: var(--text-size-lg);
+  font-weight: 600;
+  color: var(--text-color);
+  margin-bottom: 1rem;
+}
+
+.k-modal-footer {
+  padding-top: 0.5rem;
+  border-top: 0.0625rem solid var(--border-color);
+  display: flex;
+  justify-content: end;
+  gap: 0.5rem;
+  flex-wrap: wrap;
+}
+
+.k-modal-close-button {
+  margin-top: 1rem;
+}

package/src/components/overlays/portal/index.tsx

@@ -0,0 +1,18 @@
+"use client";
+
+import { createPortal } from "react-dom";
+import { ReactNode } from "react";
+
+interface PortalProps {
+  children: ReactNode;
+  /** Target node. Defaults to `document.body`. */
+  target?: Element | DocumentFragment;
+}
+
+/** Thin wrapper around `createPortal` — single seam for overlay-root swaps. */
+const Portal = ({ children, target }: PortalProps) => {
+  if (typeof document === "undefined") return null;
+  return createPortal(children, target ?? document.body);
+};
+
+export default Portal;

package/src/components/types.ts

@@ -0,0 +1,46 @@
+export type Variant =
+  | "primary"
+  | "secondary"
+  | "light"
+  | "danger"
+  | "warning"
+  | "success"
+  | "custom"
+  | "link";
+
+export type Size = "sm" | "md" | "lg";
+
+export type FlexAlign = "start" | "center" | "end" | "baseline" | "stretch";
+export type FlexJustify = "start" | "center" | "end" | "between" | "around";
+
+export interface PropsWithVariant {
+  /**
+   * **_Optional_** variant for styling the component. Accepts one of the following:
+   *
+   * - `primary`
+   * - `secondary`
+   * - `light`
+   * - `warning`
+   * - `danger`
+   * - `success`
+   * - `custom` (badge only; requires `color` prop)
+   * - `link` (button only; styled as inline text link)
+   *
+   * Defaults to `primary`
+   */
+
+  variant?: Variant;
+}
+
+export interface PropsWithSize {
+  /**
+   * **_Optional_** size for the component. Accepts one of the following:
+   *
+   * - `sm`
+   * - `md`
+   * - `lg`
+   *
+   * Defaults to `md`
+   */
+  size?: Size;
+}

package/src/css.d.ts

@@ -0,0 +1 @@
+declare module "*.css";

package/src/hooks/index.ts

@@ -0,0 +1,17 @@
+export { default as useInfiniteArchivableCursor } from "./useInfiniteArchivableCursor.js";
+export {
+  default as useInfinite,
+  type UseInfiniteReturn,
+} from "./useInfinite.js";
+export { default as useInfiniteCursor } from "./useInfiniteCursor.js";
+export { default as useScrollIntoView } from "./useScrollIntoView.js";
+export { default as useDebouncedValue } from "./useDebouncedValue.js";
+export { default as useOutsideClick } from "./useOutsideClick.js";
+export { default as useListKeyboard } from "./useListKeyboard.js";
+export { default as useLocalStorage } from "./useLocalStorage.js";
+export { default as useFocusTrap } from "./useFocusTrap.js";
+export {
+  default as useFloatingPosition,
+  type FloatingPosition,
+  type FloatingSide,
+} from "./useFloatingPosition.js";

package/src/hooks/useDebouncedValue.ts

@@ -0,0 +1,20 @@
+"use client";
+
+import { useEffect, useState } from "react";
+
+/**
+ * Returns `value` after it has remained unchanged for `delay` milliseconds.
+ * Resets the timer on every change.
+ */
+const useDebouncedValue = <T>(value: T, delay: number): T => {
+  const [debounced, setDebounced] = useState(value);
+
+  useEffect(() => {
+    const id = setTimeout(() => setDebounced(value), delay);
+    return () => clearTimeout(id);
+  }, [value, delay]);
+
+  return debounced;
+};
+
+export default useDebouncedValue;

package/src/hooks/useFloatingPosition.ts

@@ -0,0 +1,110 @@
+"use client";
+
+import { RefObject, useCallback, useEffect, useRef, useState } from "react";
+
+export type FloatingSide = "below" | "top" | "bottom" | "left" | "right";
+
+export interface FloatingPosition {
+  top: number;
+  left: number;
+  width: number;
+}
+
+interface UseFloatingPositionOptions {
+  isOpen: boolean;
+  /** Placement relative to the anchor. `below` matches anchor width (default). */
+  side?: FloatingSide;
+  /** Ref to the floating element — required for `top`/`bottom`/`left`/`right`. */
+  floatingRef?: RefObject<HTMLElement | null>;
+  /** Distance in px between anchor and floating element (ignored for `below`). */
+  offset?: number;
+  /** Clamp position inside the viewport. */
+  clampViewport?: boolean;
+  /** Padding from viewport edges when clamping. */
+  padding?: number;
+}
+
+/**
+ * Tracks the screen position of a floating element anchored to a trigger.
+ * Supports anchored-below dropdowns and side-positioned tooltips/popovers
+ * with optional viewport clamping. Updates on scroll/resize while `isOpen`.
+ */
+const useFloatingPosition = ({
+  isOpen,
+  side = "below",
+  floatingRef,
+  offset = 0,
+  clampViewport = false,
+  padding = 8,
+}: UseFloatingPositionOptions) => {
+  const anchorRef = useRef<HTMLDivElement>(null);
+  const [position, setPosition] = useState<FloatingPosition | null>(null);
+
+  const update = useCallback(() => {
+    const anchor = anchorRef.current;
+    if (!anchor) return;
+    const a = anchor.getBoundingClientRect();
+    const f = floatingRef?.current?.getBoundingClientRect();
+
+    let top = 0;
+    let left = 0;
+
+    if (side === "below") {
+      top = a.bottom;
+      left = a.left;
+    } else {
+      if (!f) return;
+      const centerX = a.left + (a.width - f.width) / 2;
+      const centerY = a.top + (a.height - f.height) / 2;
+      switch (side) {
+        case "top":
+          top = a.top - f.height - offset;
+          left = centerX;
+          break;
+        case "bottom":
+          top = a.bottom + offset;
+          left = centerX;
+          break;
+        case "left":
+          top = centerY;
+          left = a.left - f.width - offset;
+          break;
+        case "right":
+          top = centerY;
+          left = a.right + offset;
+          break;
+      }
+    }
+
+    if (clampViewport && f) {
+      left = Math.max(
+        padding,
+        Math.min(left, window.innerWidth - f.width - padding)
+      );
+      top = Math.max(
+        padding,
+        Math.min(top, window.innerHeight - f.height - padding)
+      );
+    }
+
+    setPosition({ top, left, width: a.width });
+  }, [side, offset, clampViewport, padding, floatingRef]);
+
+  useEffect(() => {
+    if (!isOpen) {
+      setPosition(null);
+      return;
+    }
+    update();
+    window.addEventListener("scroll", update, true);
+    window.addEventListener("resize", update);
+    return () => {
+      window.removeEventListener("scroll", update, true);
+      window.removeEventListener("resize", update);
+    };
+  }, [isOpen, update]);
+
+  return { anchorRef, position, update };
+};
+
+export default useFloatingPosition;

package/src/hooks/useFocusTrap.ts

@@ -0,0 +1,56 @@
+"use client";
+
+import { RefObject, useEffect } from "react";
+
+const FOCUSABLE_SELECTOR = [
+  "button:not([disabled])",
+  "[href]",
+  "input:not([disabled])",
+  "select:not([disabled])",
+  "textarea:not([disabled])",
+  '[tabindex]:not([tabindex="-1"])',
+].join(",");
+
+/**
+ * Traps Tab focus inside `containerRef` while `enabled`. Focuses the first
+ * focusable element on activation and restores the previously focused element
+ * on deactivation.
+ */
+const useFocusTrap = (
+  containerRef: RefObject<HTMLElement | null>,
+  enabled: boolean
+) => {
+  useEffect(() => {
+    if (!enabled) return;
+    const container = containerRef.current;
+    if (!container) return;
+
+    const prevActive = document.activeElement as HTMLElement | null;
+    const getFocusables = () =>
+      Array.from(container.querySelectorAll<HTMLElement>(FOCUSABLE_SELECTOR));
+
+    getFocusables()[0]?.focus();
+
+    const handleKey = (e: KeyboardEvent) => {
+      if (e.key !== "Tab") return;
+      const list = getFocusables();
+      if (list.length === 0) return;
+      const first = list[0];
+      const last = list[list.length - 1];
+      if (e.shiftKey && document.activeElement === first) {
+        e.preventDefault();
+        last.focus();
+      } else if (!e.shiftKey && document.activeElement === last) {
+        e.preventDefault();
+        first.focus();
+      }
+    };
+    document.addEventListener("keydown", handleKey);
+    return () => {
+      document.removeEventListener("keydown", handleKey);
+      prevActive?.focus?.();
+    };
+  }, [enabled, containerRef]);
+};
+
+export default useFocusTrap;