@kosmeo-ui/react 0.1.0

package/src/components/layout/card/index.tsx

@@ -0,0 +1,96 @@
+"use client";
+
+import ProgressBar from "../../feedback/progressBar/index.js";
+import { MouseEventHandler, ReactNode } from "react";
+import { PropsWithVariant } from "../../types.js";
+import "./styles.css";
+
+export interface CardHeader {
+  title: ReactNode;
+  actions?: ReactNode;
+}
+
+export interface CardProgress {
+  current: number;
+  total: number;
+  label?: ReactNode;
+}
+
+export interface CardProps extends PropsWithVariant {
+  children: ReactNode;
+  hoverable?: boolean;
+  onClick?: MouseEventHandler<HTMLDivElement>;
+  padding?: "none" | "small" | "default" | "large";
+  /** Optional header bar. Title left, actions right. Accepts a `{ title, actions }` object or any ReactNode. */
+  header?: CardHeader | ReactNode;
+  /** Optional progress bar rendered below the header. */
+  progress?: CardProgress;
+  /** Optional footer slot rendered below the body (e.g. action buttons). */
+  footer?: ReactNode;
+  /** Body text alignment. Defaults to "left". */
+  align?: "left" | "center";
+}
+
+const isStructuredHeader = (header: unknown): header is CardHeader =>
+  typeof header === "object" &&
+  header !== null &&
+  "title" in (header as Record<string, unknown>);
+
+const Card = (props: CardProps) => {
+  const {
+    hoverable = false,
+    padding = "default",
+    variant = "primary",
+    align = "left",
+    header,
+    progress,
+    footer,
+  } = props;
+  const cardClasses = [
+    "k-card",
+    hoverable ? "k-card-hoverable" : "",
+    `k-card-padding-${padding}`,
+    `k-card-${variant}`,
+    `k-card-align-${align}`,
+  ]
+    .filter(Boolean)
+    .join(" ");
+
+  return (
+    <div className={cardClasses} onClick={props.onClick}>
+      {(header !== undefined || progress) && (
+        <div className="k-card-header">
+          {header !== undefined &&
+            (isStructuredHeader(header) ? (
+              <div className="k-card-header-row">
+                <div className="k-card-header-title">{header.title}</div>
+                {header.actions && (
+                  <div className="k-card-header-actions">{header.actions}</div>
+                )}
+              </div>
+            ) : (
+              <div className="k-card-header-row">{header}</div>
+            ))}
+          {progress && (
+            <div className="k-card-progress">
+              {progress.label && (
+                <div className="k-card-progress-label">{progress.label}</div>
+              )}
+              <ProgressBar
+                progress={
+                  progress.total > 0
+                    ? Math.round((progress.current / progress.total) * 100)
+                    : 0
+                }
+              />
+            </div>
+          )}
+        </div>
+      )}
+      <div className="k-card-body">{props.children}</div>
+      {footer && <div className="k-card-footer">{footer}</div>}
+    </div>
+  );
+};
+
+export default Card;

package/src/components/layout/card/styles.css

@@ -0,0 +1,160 @@
+/* Card Component Styles */
+.k-card {
+  background: var(--background-color);
+  border-radius: 0.9375rem;
+  transition: all 0.3s ease;
+  border: 0.0625rem solid var(--border-color);
+}
+
+.k-card-align-left {
+  text-align: left;
+}
+
+.k-card-align-center {
+  text-align: center;
+}
+
+.k-card-hoverable {
+  box-shadow: 0 0.3125rem 0.9375rem var(--shadow-color);
+}
+
+.k-card-hoverable:hover {
+  transform: translateY(-0.3125rem);
+  box-shadow: 0 0.9375rem 1.875rem var(--shadow-color-hover);
+}
+
+.k-card-header {
+  display: flex;
+  flex-direction: column;
+  gap: 0.5rem;
+  padding-bottom: 0.75rem;
+  margin-bottom: 1rem;
+  border-bottom: 0.0625rem solid var(--border-color);
+}
+
+.k-card-header-row {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: 1rem;
+}
+
+.k-card-header-title {
+  font-weight: 600;
+  font-size: 1rem;
+}
+
+.k-card-header-actions {
+  display: flex;
+  align-items: center;
+  gap: 0.5rem;
+}
+
+.k-card-progress {
+  display: flex;
+  flex-direction: column;
+  gap: 0.25rem;
+}
+
+.k-card-progress-label {
+  font-size: 0.8125rem;
+  color: var(--text-color);
+  opacity: 0.7;
+}
+
+.k-card-body {
+  /* container for content below header */
+}
+
+.k-card-footer {
+  display: flex;
+  flex-direction: column;
+  gap: 0.5rem;
+  padding-top: 0.75rem;
+  margin-top: 1rem;
+  border-top: 0.0625rem solid var(--border-color);
+}
+
+/* Padding Variants */
+.k-card-padding-none {
+  padding: 0;
+}
+
+.k-card-padding-small {
+  padding: 1rem;
+}
+
+.k-card-padding-default {
+  padding: 1.5rem;
+}
+
+.k-card-padding-large {
+  padding: 2rem;
+}
+
+/* Color Variants */
+.k-card-primary {
+  border-color: var(--primary-color);
+}
+
+.k-card-primary.k-card-hoverable:hover {
+  border-color: var(--primary-color-hover);
+  box-shadow:
+    0 0.9375rem 1.875rem var(--shadow-color-hover),
+    0 0 0 0.0625rem var(--primary-color);
+}
+
+.k-card-secondary {
+  border-color: var(--secondary-color);
+}
+
+.k-card-secondary.k-card-hoverable:hover {
+  border-color: var(--secondary-color-hover);
+  box-shadow:
+    0 0.9375rem 1.875rem var(--shadow-color-hover),
+    0 0 0 0.0625rem var(--secondary-color);
+}
+
+.k-card-light {
+  border-color: var(--light-color);
+}
+
+.k-card-light.k-card-hoverable:hover {
+  border-color: var(--light-color-hover);
+  box-shadow:
+    0 0.9375rem 1.875rem var(--shadow-color-hover),
+    0 0 0 0.0625rem var(--light-color);
+}
+
+.k-card-danger {
+  border-color: var(--danger-color);
+}
+
+.k-card-danger.k-card-hoverable:hover {
+  border-color: var(--danger-color-hover);
+  box-shadow:
+    0 0.9375rem 1.875rem var(--shadow-color-hover),
+    0 0 0 0.0625rem var(--danger-color);
+}
+
+.k-card-warning {
+  border-color: var(--warning-color);
+}
+
+.k-card-warning.k-card-hoverable:hover {
+  border-color: var(--warning-color-hover);
+  box-shadow:
+    0 0.9375rem 1.875rem var(--shadow-color-hover),
+    0 0 0 0.0625rem var(--warning-color);
+}
+
+.k-card-success {
+  border-color: var(--success-color);
+}
+
+.k-card-success.k-card-hoverable:hover {
+  border-color: var(--success-color-hover);
+  box-shadow:
+    0 0.9375rem 1.875rem var(--shadow-color-hover),
+    0 0 0 0.0625rem var(--success-color);
+}

package/src/components/layout/centered/index.tsx

@@ -0,0 +1,10 @@
+"use client";
+
+import { PropsWithChildren } from "react";
+import "./styles.css";
+
+const Centered = (props: PropsWithChildren) => {
+  return <div className="k-centered">{props.children}</div>;
+};
+
+export default Centered;

package/src/components/layout/centered/styles.css

@@ -0,0 +1,9 @@
+.k-centered {
+  display: flex;
+  flex-direction: column;
+  justify-content: center;
+  align-items: center;
+  width: 100%;
+  height: 100%;
+  padding: 1rem;
+}

package/src/components/layout/col/index.tsx

@@ -0,0 +1,43 @@
+"use client";
+
+import { PropsWithSize, FlexAlign, FlexJustify } from "../../types.js";
+import "./styles.css";
+
+export interface ColProps extends PropsWithSize {
+  /** The child element(s) that will appear in the Col */
+  children: React.ReactNode;
+  /** Inline styles forwarded to the underlying div. */
+  style?: React.CSSProperties;
+  /** Cross-axis alignment (`align-items`). Defaults to `stretch`. */
+  align?: FlexAlign;
+  /** Main-axis alignment (`justify-content`). Defaults to `start`. */
+  justify?: FlexJustify;
+  /** When true, enables `flex-wrap: wrap`. */
+  wrap?: boolean;
+  /** When `"full"`, spans every column of the parent grid (e.g. inside `FormGrid`). */
+  span?: "full";
+  /** Adds a top border + matching top margin/padding above the Col. */
+  divider?: "solid-top";
+}
+
+const Col = (props: ColProps) => {
+  const { size = "md", align, justify, wrap, span, divider, style } = props;
+  const classes = [
+    "k-col",
+    `k-col-${size}`,
+    align ? `k-flex-align-${align}` : "",
+    justify ? `k-flex-justify-${justify}` : "",
+    wrap ? "k-flex-wrap" : "",
+    span ? `k-col-span-${span}` : "",
+    divider ? `k-col-divider-${divider}` : "",
+  ]
+    .filter(Boolean)
+    .join(" ");
+  return (
+    <div className={classes} style={style}>
+      {props.children}
+    </div>
+  );
+};
+
+export default Col;

package/src/components/layout/col/styles.css

@@ -0,0 +1,27 @@
+.k-col {
+  display: flex;
+  flex-direction: column;
+  width: 100%;
+}
+
+.k-col-sm {
+  gap: 0.5rem;
+}
+
+.k-col-md {
+  gap: 1rem;
+}
+
+.k-col-lg {
+  gap: 1.5rem;
+}
+
+.k-col-span-full {
+  grid-column: 1 / -1;
+}
+
+.k-col-divider-solid-top {
+  margin-top: 0.5rem;
+  padding-top: 0.5rem;
+  border-top: 1px solid var(--border-color);
+}

package/src/components/layout/page/index.tsx

@@ -0,0 +1,56 @@
+"use client";
+
+import Spinner from "../../feedback/spinner/index.js";
+import Centered from "../centered/index.js";
+import { ReactNode } from "react";
+import "./styles.css";
+
+export type PageGap = "none" | "sm" | "md";
+export type PageMaxWidth = "none" | "narrow" | "default" | "wide";
+
+export interface PageProps {
+  children?: ReactNode;
+  /** Fill parent height (`height: 100%`). Use for list pages with internal scroll regions. */
+  fillHeight?: boolean;
+  /** Apply 1.5rem padding (1rem on small screens). */
+  padded?: boolean;
+  /** Vertical gap between direct children. */
+  gap?: PageGap;
+  /** Centered max-width constraint. */
+  maxWidth?: PageMaxWidth;
+  /** Loading state. Renders a centered spinner when true. */
+  loading?: boolean;
+}
+
+const Page = ({
+  children,
+  fillHeight,
+  padded,
+  gap = "none",
+  maxWidth = "default",
+  loading,
+}: PageProps) => {
+  const classes = [
+    "k-page",
+    fillHeight && "k-page-fill",
+    padded && "k-page-padded",
+    gap !== "none" && `k-page-gap-${gap}`,
+    maxWidth !== "none" && `k-page-max-${maxWidth}`,
+  ]
+    .filter(Boolean)
+    .join(" ");
+
+  if (loading) {
+    return (
+      <div className={`${classes} k-page-loading`}>
+        <Centered>
+          <Spinner />
+        </Centered>
+      </div>
+    );
+  }
+
+  return <div className={classes}>{children}</div>;
+};
+
+export default Page;

package/src/components/layout/page/styles.css

@@ -0,0 +1,53 @@
+.k-page {
+  display: flex;
+  flex-direction: column;
+  width: 100%;
+  box-sizing: border-box;
+}
+
+.k-page-fill {
+  height: 100%;
+  min-height: 0;
+}
+
+.k-page-padded {
+  padding: 1.5rem;
+}
+
+.k-page-gap-sm {
+  gap: 0.75rem;
+}
+
+.k-page-gap-md {
+  gap: 1.5rem;
+}
+
+.k-page-max-narrow {
+  max-width: 48rem;
+  margin: 0 auto;
+}
+
+.k-page-max-default {
+  max-width: 80rem;
+  margin: 0 auto;
+}
+
+.k-page-max-wide {
+  max-width: 100%;
+  margin: 0 auto;
+}
+
+.k-page-loading {
+  align-items: center;
+  justify-content: center;
+  min-height: 12rem;
+}
+
+@media (max-width: 640px) {
+  .k-page-padded {
+    padding: 1rem;
+  }
+  .k-page-gap-md {
+    gap: 1rem;
+  }
+}

package/src/components/layout/row/index.tsx

@@ -0,0 +1,40 @@
+"use client";
+
+import { PropsWithSize, FlexAlign, FlexJustify } from "../../types.js";
+import "./styles.css";
+
+export interface RowProps extends PropsWithSize {
+  /** The child element(s) that will appear in the Row */
+  children: React.ReactNode;
+  /** Inline styles forwarded to the underlying div. */
+  style?: React.CSSProperties;
+  /** Cross-axis alignment (`align-items`). Defaults to `stretch`. */
+  align?: FlexAlign;
+  /** Main-axis alignment (`justify-content`). Defaults to `start`. */
+  justify?: FlexJustify;
+  /** When true, enables `flex-wrap: wrap`. */
+  wrap?: boolean;
+  /** When true, renders as an inline-flex cluster (auto width, always row direction). Use for badge/tag groups beside other inline content. */
+  inline?: boolean;
+}
+
+const Row = (props: RowProps) => {
+  const { size = "md", align, justify, wrap, inline, style } = props;
+  const classes = [
+    "k-row",
+    `k-row-${size}`,
+    inline ? "k-row-inline" : "",
+    align ? `k-flex-align-${align}` : "",
+    justify ? `k-flex-justify-${justify}` : "",
+    wrap ? "k-flex-wrap" : "",
+  ]
+    .filter(Boolean)
+    .join(" ");
+  return (
+    <div className={classes} style={style}>
+      {props.children}
+    </div>
+  );
+};
+
+export default Row;

package/src/components/layout/row/styles.css

@@ -0,0 +1,33 @@
+.k-row {
+  display: flex;
+  flex-direction: column;
+  width: 100%;
+}
+
+.k-row-inline {
+  display: inline-flex;
+  flex-direction: row;
+  width: auto;
+}
+
+.k-row-sm {
+  gap: 0.5rem;
+}
+
+.k-row-md {
+  gap: 1rem;
+}
+
+.k-row-lg {
+  gap: 1.5rem;
+}
+
+@media (min-width: 640px) {
+  .k-row {
+    flex-direction: row;
+  }
+  .k-row .k-wrapper {
+    flex: 1;
+    min-width: 0;
+  }
+}

package/src/components/layout/sectionHeader/index.tsx

@@ -0,0 +1,77 @@
+"use client";
+
+import { ReactNode } from "react";
+import "./styles.css";
+
+export interface SectionHeaderProps {
+  title: ReactNode;
+  /** Small text shown below the title. */
+  subtitle?: ReactNode;
+  /** Pill/badge row shown beside the title (status pills, tags). */
+  badges?: ReactNode;
+  /** Small text/breadcrumb row shown above the title. */
+  preface?: ReactNode;
+  /** Center-aligned content between the title and actions. */
+  center?: ReactNode;
+  /** Right-side actions (buttons, dropdowns). */
+  actions?: ReactNode;
+  /** Optional element rendered before the title (icon, badge, avatar). */
+  leading?: ReactNode;
+  /** Heading level. Defaults to `h3`. `h1` adds a bottom divider by default. */
+  as?: "h1" | "h2" | "h3" | "h4";
+  /** Reduce vertical spacing. */
+  dense?: boolean;
+  /** Show bottom divider + extra margin. Defaults to `true` when `as="h1"`. */
+  divider?: boolean;
+}
+
+const SectionHeader = ({
+  title,
+  subtitle,
+  badges,
+  preface,
+  center,
+  actions,
+  leading,
+  as: Tag = "h3",
+  dense,
+  divider,
+}: SectionHeaderProps) => {
+  const showDivider = divider ?? Tag === "h1";
+  const classes = [
+    "k-section-header",
+    `k-section-header-${Tag}`,
+    dense && "k-section-header-dense",
+    showDivider && "k-section-header-divider",
+  ]
+    .filter(Boolean)
+    .join(" ");
+
+  return (
+    <header className={classes}>
+      {preface && <div className="k-section-header-preface">{preface}</div>}
+      <div
+        className={
+          center
+            ? "k-section-header-row k-section-header-row-with-center"
+            : "k-section-header-row"
+        }
+      >
+        <div className="k-section-header-left">
+          {leading && <div className="k-section-header-leading">{leading}</div>}
+          <div className="k-section-header-titles">
+            <Tag className="k-section-header-title">{title}</Tag>
+            {subtitle && (
+              <div className="k-section-header-subtitle">{subtitle}</div>
+            )}
+            {badges && <div className="k-section-header-badges">{badges}</div>}
+          </div>
+        </div>
+        {center && <div className="k-section-header-center">{center}</div>}
+        {actions && <div className="k-section-header-actions">{actions}</div>}
+      </div>
+    </header>
+  );
+};
+
+export default SectionHeader;