@kosmeo-ui/react 0.1.0

package/src/components/data-display/dataTable/index.tsx

@@ -0,0 +1,206 @@
+"use client";
+
+import { TableColumn, TableLeadingColumn, TableRow } from "./types.js";
+import { useVirtualizer } from "@tanstack/react-virtual";
+import parseDataKey from "./utils/parseDataKey.js";
+import { useMemo, type RefObject } from "react";
+import "../table/styles.css";
+import "./styles.css";
+
+export interface DataTableProps<TData> {
+  columns: TableColumn<TData>[];
+  rows: TableRow<TData>[];
+  /** Optional leading column (used by InfiniteScroll for checkbox). */
+  leadingColumn?: TableLeadingColumn<TData>;
+  /** Row click handler. Receives the row data. */
+  onRowClick?: (data: TData) => void;
+  /**
+   * Scroll container to virtualize against. When set AND the row count
+   * crosses VIRTUALIZATION_THRESHOLD, only visible rows are rendered.
+   * Virtualization is strictly opt-in: omit this prop to render all rows.
+   */
+  scrollParentRef?: RefObject<HTMLElement | null>;
+  /** Striped rows. Defaults to true. */
+  striped?: boolean;
+  /** Bordered cells. Defaults to true. */
+  bordered?: boolean;
+  /** Hover highlight. Defaults to true. */
+  hover?: boolean;
+}
+
+// Below this row count the DOM cost is negligible and virtualization's
+// layout-thrash overhead isn't worth it. Above it, scrolling starts to
+// feel sluggish without windowing.
+const VIRTUALIZATION_THRESHOLD = 100;
+
+// Reasonable starting guess for row height. react-virtual measures real
+// heights via measureElement, so this only affects the first paint before
+// a row has been measured.
+const ESTIMATED_ROW_HEIGHT = 56;
+
+// Render extra rows above/below the viewport so fast scrolls don't flash
+// blank space before react-virtual catches up.
+const OVERSCAN = 8;
+
+const DataTable = <TData extends object>(props: DataTableProps<TData>) => {
+  const {
+    columns,
+    rows,
+    leadingColumn,
+    onRowClick,
+    scrollParentRef,
+    striped = true,
+    bordered = true,
+    hover = true,
+  } = props;
+
+  const shouldVirtualize =
+    !!scrollParentRef && rows.length > VIRTUALIZATION_THRESHOLD;
+
+  const virtualizer = useVirtualizer({
+    count: rows.length,
+    getScrollElement: () => scrollParentRef?.current ?? null,
+    estimateSize: () => ESTIMATED_ROW_HEIGHT,
+    overscan: OVERSCAN,
+    enabled: shouldVirtualize,
+  });
+
+  const tableColumns = useMemo(() => {
+    const headers = [];
+    if (leadingColumn) {
+      headers.push(
+        <th key="leading" className="k-data-table-leading">
+          {leadingColumn.header}
+        </th>
+      );
+    }
+    for (const c of columns) {
+      const content = c.headerElement ? c.headerElement(c.title) : c.title;
+      const alignClass = c.align ? `k-data-table-align-${c.align}` : "";
+      headers.push(
+        <th
+          key={headers.length}
+          className={`k-data-table-header-cell ${alignClass}`.trim()}
+          style={{ width: c.width, minWidth: c.minWidth, maxWidth: c.maxWidth }}
+        >
+          {content}
+        </th>
+      );
+    }
+    return headers;
+  }, [columns, leadingColumn]);
+
+  const renderRow = (row: TableRow<TData>) => {
+    const cells = [];
+    if (leadingColumn) {
+      const disable = leadingColumn.disableRowClick ?? true;
+      cells.push(
+        <td
+          key="leading"
+          className="k-data-table-leading"
+          onClick={disable ? (e) => e.stopPropagation() : undefined}
+        >
+          {leadingColumn.cell(row)}
+        </td>
+      );
+    }
+    for (const c of columns) {
+      const alignClass = c.align ? `k-data-table-align-${c.align}` : "";
+      const content = c.cellElement
+        ? c.cellElement(row.data, row.index)
+        : c.dataKey
+          ? parseDataKey(c.dataKey, row.data)
+          : undefined;
+      cells.push(
+        <td
+          key={cells.length}
+          className={alignClass}
+          onClick={c.disableRowClick ? (e) => e.stopPropagation() : undefined}
+        >
+          {content}
+        </td>
+      );
+    }
+    return cells;
+  };
+
+  const columnSpan = columns.length + (leadingColumn ? 1 : 0);
+
+  const body = shouldVirtualize
+    ? (() => {
+        const virtualRows = virtualizer.getVirtualItems();
+        const totalSize = virtualizer.getTotalSize();
+        const topSpacer = virtualRows[0]?.start ?? 0;
+        const bottomSpacer =
+          virtualRows.length > 0
+            ? totalSize - (virtualRows[virtualRows.length - 1]?.end ?? 0)
+            : 0;
+
+        return (
+          <>
+            {topSpacer > 0 && (
+              <tr aria-hidden="true">
+                <td
+                  className="k-data-table-spacer"
+                  colSpan={columnSpan}
+                  style={{ height: topSpacer }}
+                />
+              </tr>
+            )}
+            {virtualRows.map((vr) => {
+              const row = rows[vr.index];
+              return (
+                <tr
+                  key={row.index}
+                  data-index={vr.index}
+                  ref={virtualizer.measureElement}
+                  className={onRowClick ? "k-data-table-row-clickable" : ""}
+                  onClick={() => onRowClick?.(row.data)}
+                >
+                  {renderRow(row)}
+                </tr>
+              );
+            })}
+            {bottomSpacer > 0 && (
+              <tr aria-hidden="true">
+                <td
+                  className="k-data-table-spacer"
+                  colSpan={columnSpan}
+                  style={{ height: bottomSpacer }}
+                />
+              </tr>
+            )}
+          </>
+        );
+      })()
+    : rows.map((row) => (
+        <tr
+          key={row.index}
+          className={onRowClick ? "k-data-table-row-clickable" : ""}
+          onClick={() => onRowClick?.(row.data)}
+        >
+          {renderRow(row)}
+        </tr>
+      ));
+
+  const tableClasses = [
+    "k-table",
+    striped ? "k-table-striped" : "",
+    hover ? "k-table-hover" : "",
+    bordered ? "k-table-bordered" : "",
+  ]
+    .filter(Boolean)
+    .join(" ");
+
+  return (
+    <table className={tableClasses}>
+      <thead>
+        <tr>{tableColumns}</tr>
+      </thead>
+      <tbody>{body}</tbody>
+    </table>
+  );
+};
+
+export default DataTable;
+export type { TableColumn, TableRow, TableLeadingColumn } from "./types.js";

package/src/components/data-display/dataTable/styles.css

@@ -0,0 +1,54 @@
+.k-data-table-leading {
+  text-align: center;
+  vertical-align: middle;
+  width: 3rem;
+}
+
+.k-data-table-spacer {
+  padding: 0;
+  border: 0;
+}
+
+.k-data-table-header-cell {
+  text-align: center;
+}
+
+.k-data-table-row-clickable {
+  cursor: pointer;
+}
+
+.k-data-table-row-clickable:hover {
+  background-color: var(--bg-hover) !important;
+}
+
+/* Alignment classes using flexbox for reliable alignment of any content */
+td.k-data-table-align-left,
+th.k-data-table-align-left {
+  text-align: left;
+}
+
+td.k-data-table-align-left > *,
+th.k-data-table-align-left > * {
+  margin-right: auto;
+}
+
+td.k-data-table-align-center,
+th.k-data-table-align-center {
+  text-align: center;
+}
+
+td.k-data-table-align-center > *,
+th.k-data-table-align-center > * {
+  margin-left: auto;
+  margin-right: auto;
+}
+
+td.k-data-table-align-right,
+th.k-data-table-align-right {
+  text-align: right;
+}
+
+td.k-data-table-align-right > *,
+th.k-data-table-align-right > * {
+  margin-left: auto;
+}

package/src/components/data-display/dataTable/types.ts

@@ -0,0 +1,71 @@
+import { ReactNode } from "react";
+
+/**
+ * DataKey is the key used to access the data in the data object.
+ *
+ * To access nested data, use dot notation.
+ *
+ * For example, if the data object is { foo: { bar: "baz" } }, then the dataKey would be "foo.bar"
+ *
+ * To access an array, use bracket notation.
+ *
+ * For example, if the data object is { foo: ["bar", "baz"] }, then the dataKey would be "foo[0]"
+ *
+ * To access an array of objects, use dot notation and bracket notation.
+ *
+ * For example, if the data object is { foo: [{ bar: "baz" }] }, then the dataKey would be "foo[0].bar"
+ */
+export type DataKey = string;
+
+export interface TableColumn<TData> {
+  /**
+   * The title to render inside the <th> tags
+   *
+   * NOTE: This is also the value that will be passed to the headerElement function.
+   */
+  title: string;
+  /**
+   * Required if there is no cellElement function.
+   *
+   * DataKey is the key used to access the data in the data object.
+   *
+   * This data is what will be displayed in the <td> tags.
+   */
+  dataKey?: DataKey;
+  /** When true, the column is omitted from the rendered table. */
+  hidden?: boolean;
+  /** The desired fixed width of the column */
+  width?: React.CSSProperties["width"];
+  /** The desired minimum width of the column */
+  minWidth?: React.CSSProperties["minWidth"];
+  /** The desired maximum width of the column */
+  maxWidth?: React.CSSProperties["maxWidth"];
+  /** Text alignment for the column content. Defaults to 'left' */
+  align?: "left" | "center" | "right";
+  /**
+   * When true, clicking on cells in this column will not trigger the row click handler
+   */
+  disableRowClick?: boolean;
+  /**
+   * React Element to render inside the <th> tags.
+   */
+  headerElement?: (title: string) => ReactNode | string;
+  /**
+   * React Element to render inside the <td> tags. Receives the row data and
+   * the zero-based row index — index is needed by inline-editable tables that
+   * dispatch updates targeting a specific row.
+   */
+  cellElement?: (rowData: TData, index: number) => ReactNode | string;
+}
+
+export interface TableRow<TData> {
+  index: number;
+  data: TData;
+}
+
+export interface TableLeadingColumn<TData> {
+  header: ReactNode;
+  cell: (row: TableRow<TData>) => ReactNode;
+  /** When true, clicks on the leading cell don't trigger the row click. Defaults to true. */
+  disableRowClick?: boolean;
+}

package/src/components/data-display/dataTable/utils/parseDataKey.ts

@@ -0,0 +1,39 @@
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+const parseDataKey = (dataKey: string, data: any) => {
+  let value = data;
+  let more = false;
+  do {
+    const dotIndex = dataKey.indexOf(".");
+    const bracketIndex = dataKey.indexOf("[");
+    if (bracketIndex === -1 && dotIndex === -1) {
+      value = value[dataKey];
+      more = false;
+    } else if (bracketIndex === -1) {
+      const key = dataKey.substring(0, dotIndex);
+      value = value[key];
+      dataKey = dataKey.substring(dotIndex + 1);
+      more = true;
+    } else if (dotIndex === -1) {
+      const key = dataKey.substring(0, bracketIndex);
+      const index = dataKey.substring(bracketIndex + 1, dataKey.indexOf("]"));
+      value = value[key][parseInt(index)];
+      dataKey = dataKey.substring(dataKey.indexOf("]") + 1);
+      more = true;
+    } else if (bracketIndex < dotIndex) {
+      const key = dataKey.substring(0, bracketIndex);
+      const index = dataKey.substring(bracketIndex + 1, dataKey.indexOf("]"));
+      value = value[key][parseInt(index)];
+      dataKey = dataKey.substring(dataKey.indexOf("]") + 1);
+      more = true;
+    } else {
+      const key = dataKey.substring(0, dotIndex);
+      value = value[key];
+      dataKey = dataKey.substring(dotIndex + 1);
+      more = true;
+    }
+  } while (more);
+  if (value === undefined) throw new Error(`Invalid dataKey: ${dataKey}`);
+  return value;
+};
+
+export default parseDataKey;

package/src/components/data-display/imagePreview/index.tsx

@@ -0,0 +1,42 @@
+"use client";
+
+import Button from "../../buttons/button/index.js";
+import { PropsWithSize } from "../../types.js";
+import "./styles.css";
+
+interface ImagePreviewProps extends PropsWithSize {
+  /** An array of URLs for the images to be previewed. */
+  previewUrls: string[];
+  /** Called when the "Clear" action is pressed. */
+  onClear: () => void;
+  /** Called when the "Change" action is pressed (typically reopens the picker). */
+  onChange: () => void;
+}
+
+const ImagePreview = (props: ImagePreviewProps) => {
+  const { size = "md" } = props;
+  return (
+    <div className={`k-image-preview-area`}>
+      <div className="k-image-previews-grid">
+        {props.previewUrls.map((url, index) => (
+          <img
+            key={index}
+            src={url}
+            alt={`Preview ${index + 1}`}
+            className={`k-image-preview-item k-image-preview-item-${size}`}
+          />
+        ))}
+      </div>
+      <div className="k-image-preview-actions">
+        <Button onClick={props.onChange} variant={"secondary"} size={size}>
+          Change Image{props.previewUrls.length > 1 ? "s" : ""}
+        </Button>
+        <Button size={size} variant="danger" onClick={props.onClear}>
+          Clear {props.previewUrls.length > 1 ? "All Images" : "Image"}
+        </Button>
+      </div>
+    </div>
+  );
+};
+
+export default ImagePreview;

package/src/components/data-display/imagePreview/styles.css

@@ -0,0 +1,52 @@
+.k-image-preview-area {
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  gap: 0.5rem;
+  width: 100%;
+  border: 0.0625rem dashed var(--border-color);
+  border-radius: 0.25rem;
+  padding: 0.5rem;
+}
+
+.k-image-previews-grid {
+  display: flex;
+  flex-wrap: nowrap;
+  gap: 1rem;
+  justify-content: flex-start;
+  width: 100%;
+  overflow-x: auto;
+  padding: 0 0.5rem 0.5rem 0.5rem;
+  box-sizing: border-box;
+}
+
+.k-image-preview-item {
+  object-fit: cover;
+  border-radius: 0.25rem;
+  box-shadow: 0 0.125rem 0.25rem var(--shadow-color);
+  flex-shrink: 0;
+}
+
+.k-image-preview-item-sm {
+  max-width: 7rem;
+  min-width: 7rem;
+  height: 7rem;
+}
+
+.k-image-preview-item-md {
+  max-width: 10rem;
+  min-width: 10rem;
+  height: 10rem;
+}
+
+.k-image-preview-item-lg {
+  max-width: 13rem;
+  min-width: 13rem;
+  height: 13rem;
+}
+
+.k-image-preview-actions {
+  display: flex;
+  gap: 0.5rem;
+  align-items: center;
+}

package/src/components/data-display/infiniteScroll/filters/index.tsx

@@ -0,0 +1,77 @@
+"use client";
+
+import { InfiniteScrollMenuGeneratedFilter } from "../types.js";
+import { ReactNode, SetStateAction, useCallback } from "react";
+import SelectFilter from "./selectFilter.js";
+import SearchFilter from "./searchFilter.js";
+import RangeFilter from "./rangeFilter.js";
+import ListFilter from "./listFilter.js";
+import "./styles.css";
+
+interface InfiniteScrollMenuFiltersProps {
+  pendingFilters: InfiniteScrollMenuGeneratedFilter[];
+  handleNewPendingFilters: (
+    filters: SetStateAction<InfiniteScrollMenuGeneratedFilter[]>
+  ) => void;
+  children?: ReactNode;
+}
+
+const Filters = (props: InfiniteScrollMenuFiltersProps) => {
+  const handleFilterChange = useCallback(
+    (filter: InfiniteScrollMenuGeneratedFilter) => {
+      props.handleNewPendingFilters((prevFilters) =>
+        prevFilters.map((f) => (f.filterId === filter.filterId ? filter : f))
+      );
+    },
+    [props.handleNewPendingFilters]
+  );
+
+  const getFilter = (filter: InfiniteScrollMenuGeneratedFilter) => {
+    if (filter.type === "SELECT") {
+      return (
+        <SelectFilter
+          key={filter.filterId}
+          filter={filter}
+          onFilterChange={handleFilterChange}
+        />
+      );
+    } else if (filter.type === "RANGE") {
+      return (
+        <RangeFilter
+          key={filter.filterId}
+          filter={filter}
+          onFilterChange={handleFilterChange}
+        />
+      );
+    } else if (filter.type === "SEARCH") {
+      return (
+        <SearchFilter
+          key={filter.filterId}
+          filter={filter}
+          onFilterChange={handleFilterChange}
+        />
+      );
+    } else {
+      return (
+        <ListFilter
+          key={filter.filterId}
+          filter={filter}
+          onFilterChange={handleFilterChange}
+        />
+      );
+    }
+  };
+
+  return (
+    <div className="k-menu-filters-container">
+      <div className="k-menu-filters">
+        {props.pendingFilters.map(getFilter)}
+      </div>
+      {props.children && (
+        <div className="k-menu-filters-buttons">{props.children}</div>
+      )}
+    </div>
+  );
+};
+
+export default Filters;

package/src/components/data-display/infiniteScroll/filters/listFilter.tsx

@@ -0,0 +1,83 @@
+"use client";
+
+import { useCallback, useEffect, useMemo, useState } from "react";
+import { faList } from "@fortawesome/free-solid-svg-icons";
+import Dropdown from "../../../inputs/dropdown/index.js";
+import Button from "../../../buttons/button/index.js";
+import Input from "../../../inputs/input/index.js";
+import "./styles.css";
+import {
+  GeneratedListFilter,
+  InfiniteScrollMenuGeneratedFilter,
+} from "../types.js";
+
+interface InfiniteScrollListFilterProps {
+  filter: GeneratedListFilter;
+  onFilterChange: (filter: InfiniteScrollMenuGeneratedFilter) => void;
+}
+
+const ListFilter = (props: InfiniteScrollListFilterProps) => {
+  const [list, setList] = useState<string>("");
+  const [prevList, setPrevList] = useState<string>("");
+  const [isOpen, setIsOpen] = useState(false);
+
+  useEffect(() => {
+    if (
+      props.filter.list === prevList ||
+      (props.filter.list === undefined && prevList === "")
+    )
+      return;
+    setList(props.filter.list || "");
+    setPrevList(props.filter.list || "");
+    return;
+  }, [props.filter.list, list, prevList]);
+
+  const handleChange = useCallback((e: React.ChangeEvent<HTMLInputElement>) => {
+    setList(e.target.value);
+  }, []);
+
+  const handleSubmit = useCallback(() => {
+    props.onFilterChange({ ...props.filter, list: list });
+    setIsOpen(false);
+  }, [list, props]);
+
+  const handleKeydown = useCallback(
+    (e: React.KeyboardEvent<HTMLInputElement>) => {
+      if (e.key !== "Enter") return;
+      e.preventDefault();
+      handleSubmit();
+    },
+    [handleSubmit]
+  );
+
+  const allowSubmit = useMemo(() => {
+    return list !== prevList;
+  }, [list, prevList]);
+
+  return (
+    <Dropdown
+      size="sm"
+      variant="secondary"
+      label={props.filter.title}
+      align="left"
+      icon={faList}
+      isOpen={isOpen}
+      onOpenChange={setIsOpen}
+    >
+      <div className="k-filter-menu">
+        <Input
+          size="sm"
+          value={list}
+          onChange={handleChange}
+          type="text"
+          onKeyDown={handleKeydown}
+        />
+        <Button size="sm" disabled={!allowSubmit} onClick={handleSubmit}>
+          Add Filter
+        </Button>
+      </div>
+    </Dropdown>
+  );
+};
+
+export default ListFilter;