@kosmeo-ui/react 0.1.0

package/src/components/feedback/emptyState/index.tsx

@@ -0,0 +1,32 @@
+"use client";
+
+import { ReactNode } from "react";
+import "./styles.css";
+
+export interface EmptyStateProps {
+  children: ReactNode;
+  /** "inline" = small grey text suitable inside a list (default). "block" = padded, centered. */
+  layout?: "inline" | "block";
+  icon?: ReactNode;
+  /** Call-to-action rendered below children. Only used with layout="block". */
+  action?: ReactNode;
+}
+
+const EmptyState = ({
+  children,
+  layout = "inline",
+  icon,
+  action,
+}: EmptyStateProps) => {
+  return (
+    <div className={`k-empty-state k-empty-state-${layout}`}>
+      {icon && <div className="k-empty-state-icon">{icon}</div>}
+      <div className="k-empty-state-body">{children}</div>
+      {layout === "block" && action && (
+        <div className="k-empty-state-action">{action}</div>
+      )}
+    </div>
+  );
+};
+
+export default EmptyState;

package/src/components/feedback/emptyState/styles.css

@@ -0,0 +1,32 @@
+.k-empty-state-inline {
+  font-size: 0.875rem;
+  color: var(--text-color);
+  opacity: 0.65;
+  font-style: italic;
+  padding: 0.5rem 0;
+}
+
+.k-empty-state-block {
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  justify-content: center;
+  gap: 0.75rem;
+  padding: 2rem 1rem;
+  text-align: center;
+  color: var(--text-color);
+  opacity: 0.75;
+}
+
+.k-empty-state-icon {
+  font-size: 2rem;
+  opacity: 0.5;
+}
+
+.k-empty-state-block .k-empty-state-body {
+  font-size: 0.9375rem;
+}
+
+.k-empty-state-action {
+  margin-top: 0.25rem;
+}

package/src/components/feedback/loadingOverlay/index.tsx

@@ -0,0 +1,49 @@
+"use client";
+
+import { useEffect, useRef, useState } from "react";
+import Spinner from "../spinner/index.js";
+import "./styles.css";
+
+export interface LoadingProps {
+  /** Whether or not the loading overlay should be shown */
+  show: boolean;
+  /** Message to display below the loading image */
+  message: string;
+  /** If true, overlay covers entire viewport. If false, stays within parent element (parent must have position: relative) */
+  fullPage?: boolean;
+}
+
+const LoadingOverlay = (props: LoadingProps) => {
+  const { fullPage = true } = props;
+  const [showLoader, setShowLoader] = useState(false);
+  const loadStartTime = useRef<number | null>(null);
+
+  useEffect(() => {
+    if (props.show) {
+      loadStartTime.current = Date.now();
+      setShowLoader(true);
+    } else if (loadStartTime.current) {
+      const loadTime = Date.now() - loadStartTime.current;
+      if (loadTime >= 1000) setShowLoader(false);
+      else {
+        const timeout = setTimeout(() => {
+          setShowLoader(false);
+        }, 1000 - loadTime);
+        return () => clearTimeout(timeout);
+      }
+    }
+  }, [props.show]);
+
+  return (
+    <div
+      className={`k-loading-container ${fullPage ? "k-loading-container-fixed" : "k-loading-container-absolute"} ${showLoader ? "k-loading-visible" : "k-loading-hidden"}`}
+    >
+      <div className="k-loading-content">
+        <Spinner size="lg" />
+        <p className="k-loading-message">{props.message}</p>
+      </div>
+    </div>
+  );
+};
+
+export default LoadingOverlay;

package/src/components/feedback/loadingOverlay/styles.css

@@ -0,0 +1,48 @@
+.k-loading-container {
+  top: 0;
+  left: 0;
+  width: 100%;
+  height: 100%;
+  z-index: 300;
+  background-color: var(--background-color);
+}
+
+.k-loading-container-fixed {
+  position: fixed;
+}
+
+.k-loading-container-absolute {
+  position: absolute;
+}
+
+.k-loading-visible {
+  visibility: visible;
+  opacity: 1;
+}
+
+.k-loading-hidden {
+  visibility: hidden;
+  opacity: 0;
+  transition:
+    visibility 0s 0.25s,
+    opacity 0.25s linear;
+}
+
+.k-loading-content {
+  display: flex;
+  flex-direction: column;
+  justify-content: center;
+  align-items: center;
+  height: 100%;
+}
+
+.k-loading-message {
+  font-size: 2rem;
+  text-align: center;
+}
+
+.k-loading-logo {
+  max-width: 30rem;
+  min-width: 10rem;
+  width: 50%;
+}

package/src/components/feedback/progressBar/index.tsx

@@ -0,0 +1,34 @@
+"use client";
+
+import { PropsWithVariant } from "../../types.js";
+import "./styles.css";
+
+export interface ProgressBarProps extends PropsWithVariant {
+  /** The current progress value, a number between 0 and 100 */
+  progress: number;
+  /** **_Optional_** prop for whether to show the percent value on the bar */
+  showPercentage?: boolean;
+}
+
+const ProgressBar = (props: ProgressBarProps) => {
+  const { showPercentage = true, variant = "primary" } = props;
+  const clampedProgress = Math.max(0, Math.min(100, props.progress));
+
+  const fillBorderRadius =
+    clampedProgress === 100 ? "0.25rem" : "0.25rem 0 0 0.25rem";
+
+  return (
+    <div className={`k-progress-bar-container`}>
+      <div
+        className={`k-progress-bar-fill k-progress-bar-fill-${variant}`}
+        style={{ width: `${clampedProgress}%`, borderRadius: fillBorderRadius }}
+      >
+        {showPercentage && clampedProgress > 0 && (
+          <span className="k-progress-bar-text">{clampedProgress}%</span>
+        )}
+      </div>
+    </div>
+  );
+};
+
+export default ProgressBar;

package/src/components/feedback/progressBar/styles.css

@@ -0,0 +1,42 @@
+.k-progress-bar-container {
+  width: 100%;
+  height: 1.5625rem;
+  background-color: var(--background-color-dark);
+  border-radius: 0.25rem;
+  overflow: hidden;
+  box-shadow: inset 0 0.0625rem 0.1875rem var(--shadow-color);
+}
+
+.k-progress-bar-fill {
+  height: 100%;
+  background-color: var(--success-color);
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  color: var(--text-color-light);
+  font-weight: 600;
+  transition: width 0.5s ease-in-out;
+}
+
+.k-progress-bar-text {
+  font-size: var(--text-size-sm);
+}
+
+.k-progress-bar-fill-primary {
+  background-color: var(--primary-color);
+}
+.k-progress-bar-fill-secondary {
+  background-color: var(--secondary-color);
+}
+.k-progress-bar-fill-light {
+  background-color: var(--light-color);
+}
+.k-progress-bar-fill-warning {
+  background-color: var(--warning-color);
+}
+.k-progress-bar-fill-danger {
+  background-color: var(--danger-color);
+}
+.k-progress-bar-fill-success {
+  background-color: var(--success-color);
+}

package/src/components/feedback/spinner/index.tsx

@@ -0,0 +1,23 @@
+"use client";
+
+import { PropsWithSize, PropsWithVariant } from "../../types.js";
+import "./styles.css";
+
+export interface SpinnerProps extends PropsWithSize, PropsWithVariant {}
+
+const Spinner = (props: SpinnerProps) => {
+  const { size = "md", variant = "primary" } = props;
+  return (
+    <div
+      className={`k-spinner k-spinner-${size} k-spinner-${variant}`}
+      role="status"
+      aria-live="polite"
+      aria-label="Loading..."
+    >
+      {/* Visually hidden text using the .k-sr-only class */}
+      <span className="k-sr-only">Loading...</span>
+    </div>
+  );
+};
+
+export default Spinner;

package/src/components/feedback/spinner/styles.css

@@ -0,0 +1,64 @@
+.k-spinner {
+  border-radius: 50%;
+  display: inline-block;
+  animation: spin 0.8s linear infinite;
+}
+
+@keyframes spin {
+  0% {
+    transform: rotate(0deg);
+  }
+  100% {
+    transform: rotate(360deg);
+  }
+}
+
+.k-spinner-lg {
+  height: 3.75rem;
+  width: 3.75rem;
+  border: 0.375rem solid var(--shadow-color);
+}
+
+.k-spinner-md {
+  height: 2.5rem;
+  width: 2.5rem;
+  border: 0.25rem solid var(--shadow-color);
+}
+
+.k-spinner-sm {
+  height: 1.25rem;
+  width: 1.25rem;
+  border: 0.125rem solid var(--shadow-color);
+}
+
+.k-spinner-primary {
+  border-left-color: var(--primary-color);
+}
+.k-spinner-secondary {
+  border-left-color: var(--secondary-color);
+}
+.k-spinner-light {
+  border-left-color: var(--light-color);
+}
+.k-spinner-success {
+  border-left-color: var(--success-color);
+}
+.k-spinner-danger {
+  border-left-color: var(--danger-color);
+}
+.k-spinner-warning {
+  border-left-color: var(--warning-color);
+}
+
+/* Visually hidden class for accessibility text */
+.k-sr-only {
+  position: absolute;
+  width: 0.0625rem;
+  height: 0.0625rem;
+  padding: 0;
+  margin: -0.0625rem;
+  overflow: hidden;
+  clip: rect(0, 0, 0, 0);
+  white-space: nowrap;
+  border: 0;
+}

package/src/components/feedback/tooltip/index.tsx

@@ -0,0 +1,101 @@
+"use client";
+
+import { useEffect, useRef, useState } from "react";
+import Portal from "../../overlays/portal/index.js";
+import "./styles.css";
+import useFloatingPosition, {
+  FloatingSide,
+} from "../../../hooks/useFloatingPosition.js";
+
+type TooltipSide = Exclude<FloatingSide, "below">;
+
+export interface TooltipProps {
+  /** The element(s) that the Tooltip will appear around */
+  children: React.ReactElement<
+    React.HTMLAttributes<HTMLElement> & { ref?: React.Ref<HTMLElement> }
+  >;
+  /** The content to appear inside the Tooltip */
+  content: React.ReactNode;
+  /**
+   * **_Optional_** position of the Tooltip relative to the children.
+   *
+   * Defaults to `top`.
+   */
+  position?: TooltipSide;
+  /**
+   * **_Optional_** whether the tooltip container should take full width.
+   *
+   * Defaults to `false`.
+   */
+  fullWidth?: boolean;
+  /**
+   * **_Optional_** whether the tooltip is disabled.
+   *
+   * Defaults to `false`.
+   */
+  disabled?: boolean;
+}
+
+const Tooltip = (props: TooltipProps) => {
+  const { position = "top", fullWidth = false, disabled = false } = props;
+
+  const [isVisible, setIsVisible] = useState(false);
+  const tooltipRef = useRef<HTMLDivElement>(null);
+
+  const { anchorRef, position: tooltipPos } = useFloatingPosition({
+    isOpen: isVisible,
+    side: position,
+    floatingRef: tooltipRef,
+    offset: 13,
+    clampViewport: true,
+  });
+
+  useEffect(() => {
+    if (!isVisible) return;
+    const handleScroll = () => setIsVisible(false);
+    window.addEventListener("scroll", handleScroll, true);
+    return () => {
+      window.removeEventListener("scroll", handleScroll, true);
+    };
+  }, [isVisible]);
+
+  const handleMouseEnter = () => !disabled && setIsVisible(true);
+  const handleMouseLeave = () => setIsVisible(false);
+  const handleFocus = () => !disabled && setIsVisible(true);
+  const handleBlur = () => setIsVisible(false);
+
+  return (
+    <>
+      <div
+        ref={anchorRef}
+        className={`k-tooltip-container ${
+          fullWidth ? "k-tooltip-container-full-width" : ""
+        }`}
+        onMouseEnter={handleMouseEnter}
+        onMouseLeave={handleMouseLeave}
+        onFocus={handleFocus}
+        onBlur={handleBlur}
+      >
+        {props.children}
+      </div>
+      {isVisible && (
+        <Portal>
+          <div
+            ref={tooltipRef}
+            className={`k-tooltip-wrapper k-tooltip-${position} k-tooltip-wrapper-${
+              tooltipPos ? "visible" : "hidden"
+            }`}
+            style={{
+              top: `${tooltipPos?.top ?? 0}px`,
+              left: `${tooltipPos?.left ?? 0}px`,
+            }}
+          >
+            <div className="k-tooltip-content">{props.content}</div>
+          </div>
+        </Portal>
+      )}
+    </>
+  );
+};
+
+export default Tooltip;

package/src/components/feedback/tooltip/styles.css

@@ -0,0 +1,84 @@
+.k-tooltip-container {
+  position: relative;
+  display: inline-block;
+}
+
+.k-tooltip-container-full-width {
+  width: 100%;
+}
+
+.k-tooltip-container-full-width .k-button {
+  width: 100%;
+}
+
+.k-tooltip-wrapper {
+  position: fixed;
+  pointer-events: none;
+  z-index: 9999;
+  transition:
+    opacity 0.2s ease-in-out,
+    visibility 0.2s ease-in-out;
+  overflow: visible;
+}
+
+.k-tooltip-wrapper-hidden {
+  opacity: 0;
+  visibility: hidden;
+}
+
+.k-tooltip-wrapper-visible {
+  opacity: 1;
+  visibility: visible;
+}
+
+.k-tooltip-content {
+  position: relative;
+  background-color: var(--text-color);
+  color: var(--text-color-light);
+  padding: 0.5rem 0.75rem;
+  border-radius: 0.25rem;
+  font-size: var(--text-size-sm);
+  white-space: normal;
+  max-width: 12.5rem;
+  text-align: center;
+  box-sizing: border-box;
+}
+
+.k-tooltip-content::after {
+  content: "";
+  position: absolute;
+  border-width: 0.3125rem;
+  border-style: solid;
+  display: block;
+  width: 0;
+  height: 0;
+  box-sizing: border-box;
+}
+
+.k-tooltip-top .k-tooltip-content::after {
+  bottom: -0.625rem; /* Double the border-width to ensure visibility */
+  left: 50%;
+  transform: translateX(-50%);
+  border-color: var(--text-color) transparent transparent transparent;
+}
+
+.k-tooltip-bottom .k-tooltip-content::after {
+  top: -0.625rem; /* Double the border-width to ensure visibility */
+  left: 50%;
+  transform: translateX(-50%);
+  border-color: transparent transparent var(--text-color) transparent;
+}
+
+.k-tooltip-left .k-tooltip-content::after {
+  right: -0.625rem; /* Double the border-width to ensure visibility */
+  top: 50%;
+  transform: translateY(-50%);
+  border-color: transparent transparent transparent var(--text-color);
+}
+
+.k-tooltip-right .k-tooltip-content::after {
+  left: -0.625rem; /* Double the border-width to ensure visibility */
+  top: 50%;
+  transform: translateY(-50%);
+  border-color: transparent var(--text-color) transparent transparent;
+}

package/src/components/forms/detailField/index.tsx

@@ -0,0 +1,25 @@
+"use client";
+
+import { ReactNode } from "react";
+import "./styles.css";
+
+export interface DetailFieldProps {
+  label: ReactNode;
+  value: ReactNode;
+  /** Optional inline action (edit, copy). */
+  action?: ReactNode;
+}
+
+const DetailField = ({ label, value, action }: DetailFieldProps) => {
+  return (
+    <div className="k-detail-field">
+      <div className="k-detail-field-label">{label}</div>
+      <div className="k-detail-field-value">
+        <span>{value}</span>
+        {action && <span className="k-detail-field-action">{action}</span>}
+      </div>
+    </div>
+  );
+};
+
+export default DetailField;

package/src/components/forms/detailField/styles.css

@@ -0,0 +1,27 @@
+.k-detail-field {
+  display: flex;
+  flex-direction: column;
+  gap: 0.25rem;
+  min-width: 0;
+}
+
+.k-detail-field-label {
+  font-size: 0.75rem;
+  font-weight: 600;
+  text-transform: uppercase;
+  letter-spacing: 0.04em;
+  color: var(--text-color-secondary);
+}
+
+.k-detail-field-value {
+  display: flex;
+  align-items: center;
+  gap: 0.5rem;
+  font-size: 0.9375rem;
+  word-break: break-word;
+}
+
+.k-detail-field-action {
+  display: inline-flex;
+  align-items: center;
+}

package/src/components/forms/fieldShell/index.tsx

@@ -0,0 +1,66 @@
+"use client";
+
+import MandatoryAsterisk from "../requiredAsterisk/index.js";
+import { ReactNode } from "react";
+import "./styles.css";
+
+interface FieldShellProps {
+  /** Field label rendered above the input. */
+  label?: ReactNode;
+  /** Whether the field is required — shows asterisk next to a string label. */
+  required?: boolean;
+  /** `htmlFor` target id, used when label is a string. */
+  htmlFor?: string;
+  /** Optional right-aligned annotation in the label row (e.g. char count). */
+  labelAside?: ReactNode;
+  /** Optional error message rendered below the input. */
+  error?: ReactNode;
+  /** Optional helper text rendered below the input (hidden when `error` is set). */
+  helperText?: ReactNode;
+  /** The input element itself. */
+  children: ReactNode;
+  /** Internal-only: additional class for sibling ui-component shells to apply field-type modifiers. */
+  className?: string;
+}
+
+/** Shared shell for form fields — label + asterisk + optional char count + error/helper. */
+const FieldShell = ({
+  label,
+  required,
+  htmlFor,
+  labelAside,
+  error,
+  helperText,
+  children,
+  className = "",
+}: FieldShellProps) => (
+  <div className={`k-field-shell ${className}`.trim()}>
+    {(label || labelAside) && (
+      <div className="k-field-shell-label-row">
+        {label && (
+          <label htmlFor={htmlFor} className="k-field-shell-label">
+            {typeof label === "string" ? (
+              <>
+                {label}
+                {required && <MandatoryAsterisk />}
+              </>
+            ) : (
+              label
+            )}
+          </label>
+        )}
+        {labelAside && (
+          <span className="k-field-shell-aside">{labelAside}</span>
+        )}
+      </div>
+    )}
+    {children}
+    {error ? (
+      <div className="k-field-shell-error">{error}</div>
+    ) : helperText ? (
+      <div className="k-field-shell-helper">{helperText}</div>
+    ) : null}
+  </div>
+);
+
+export default FieldShell;

package/src/components/forms/fieldShell/styles.css

@@ -0,0 +1,38 @@
+.k-field-shell {
+  width: 100%;
+  display: flex;
+  flex-direction: column;
+}
+
+.k-field-shell-label-row {
+  display: flex;
+  justify-content: space-between;
+  align-items: baseline;
+  margin-bottom: 0.1rem;
+}
+
+.k-field-shell-label {
+  display: block;
+  font-size: 0.875rem;
+  font-weight: 500;
+  color: var(--text-color);
+}
+
+.k-field-shell-aside {
+  font-weight: 500;
+  font-size: var(--text-size-sm);
+  color: var(--text-color-secondary);
+  margin-left: 0.5rem;
+}
+
+.k-field-shell-error {
+  margin-top: 0.25rem;
+  font-size: 0.8125rem;
+  color: var(--danger-color);
+}
+
+.k-field-shell-helper {
+  margin-top: 0.25rem;
+  font-size: 0.8125rem;
+  color: var(--text-color-secondary);
+}