@jsenv/navi 0.0.1 → 0.1.1

package/src/components/table/table_css.js

@@ -0,0 +1,211 @@
+import { Z_INDEX_EDITING } from "./z_indexes.js";
+
+/*
+ * Box-shadow border mapping template:
+ *
+ * box-shadow:
+ *   inset 0 1px 0 0 color,    // Top border
+ *   inset 1px 0 0 0 color,    // Left border
+ *   inset -1px 0 0 0 color,   // Right border
+ *   inset 0 -1px 0 0 color;   // Bottom border
+ */
+
+import.meta.css = /* css */ `
+  .navi_table_root {
+    position: relative;
+    max-width: var(--table-max-width, none);
+    max-height: var(--table-max-height, none);
+  }
+
+  .navi_table_container {
+    --border-color: #e1e1e1;
+    --focus-border-color: #0078d4;
+    position: relative;
+  }
+
+  .navi_table {
+    border-radius: 2px;
+    border-spacing: 0; /* Required for manual border collapse */
+  }
+  .navi_table_cell {
+    white-space: nowrap;
+    overflow: hidden;
+    text-overflow: ellipsis;
+    background-color: var(--background-color, transparent);
+  }
+
+  .navi_table_cell[data-align-x="start"] {
+    text-align: left;
+  }
+  .navi_table_cell[data-align-x="center"] {
+    text-align: center;
+  }
+  .navi_table_cell[data-align-y="end"] {
+    text-align: right;
+  }
+  .navi_table_cell[data-align-x="start"] {
+    vertical-align: top;
+  }
+  .navi_table_cell[data-align-y="center"] {
+    vertical-align: middle;
+  }
+  .navi_table_cell[data-align-y="end"] {
+    vertical-align: bottom;
+  }
+
+  /* Table borders using ::before pseudo-elements */
+  /* Default: each cell draws all its own borders (no border-collapse) */
+  .navi_table_cell {
+    border: none; /* Remove default borders - we'll use pseudo-elements */
+    /* Required for pseudo-element positioning */
+    position: relative;
+  }
+
+  .navi_table_cell::before {
+    content: "";
+    position: absolute;
+    inset: 0;
+    pointer-events: none;
+    box-shadow:
+      inset 0 1px 0 0 var(--border-color),
+      inset 1px 0 0 0 var(--border-color),
+      inset -1px 0 0 0 var(--border-color),
+      inset 0 -1px 0 0 var(--border-color);
+  }
+  .navi_table_cell::after {
+    content: "";
+    position: absolute;
+    /* Default: include bottom and right borders (owned by this cell) */
+    inset: 0;
+    pointer-events: none;
+  }
+
+  /* padding */
+  .navi_table_cell {
+    padding-left: 12px;
+    padding-right: 12px;
+    padding-top: 8px;
+    padding-bottom: 8px;
+  }
+  .navi_table_cell[data-width-xxs] {
+    padding-left: 0;
+    padding-right: 0;
+  }
+  .navi_table_cell[data-height-xxs] {
+    padding-top: 0;
+    padding-bottom: 0;
+  }
+  .navi_table_cell[data-editing] input {
+    padding: 0;
+    padding-left: 12px;
+  }
+  .navi_table [data-sticky-left-frontier] {
+    /* padding-left: 12px; */
+    /* 12 px + 5px of the sticky frontier */
+    /* padding-right: 17px; */
+  }
+
+  .navi_table_cell {
+    user-select: none;
+  }
+
+  /* Number column specific styling */
+  .navi_row_number_cell {
+    text-align: center;
+    background: #fafafa;
+    font-weight: 500;
+    color: #666;
+    user-select: none;
+  }
+
+  .navi_table_cell_content_bold_clone {
+    font-weight: bold; /* force bold to compute max width */
+    visibility: hidden; /* not visible */
+    display: block; /* in-flow so it contributes to width */
+    height: 0; /* zero height so it doesn't change layout height */
+    overflow: hidden; /* avoid any accidental height */
+    pointer-events: none; /* inert */
+  }
+
+  /* Border-collapse mode: each cell only owns specific borders to avoid doubling */
+
+  /* Base rule: all cells get right and bottom borders */
+  .navi_table[data-border-collapse] .navi_table_cell::before {
+    box-shadow:
+      inset -1px 0 0 0 var(--border-color),
+      inset 0 -1px 0 0 var(--border-color);
+  }
+
+  /* Header cells (all th) get top border in addition to right and bottom */
+  .navi_table[data-border-collapse] .navi_table_cell[data-first-row]::before {
+    box-shadow:
+      inset 0 1px 0 0 var(--border-color),
+      inset -1px 0 0 0 var(--border-color),
+      inset 0 -1px 0 0 var(--border-color);
+  }
+
+  /* First column cells get left border in addition to right and bottom */
+  .navi_table[data-border-collapse]
+    .navi_table_cell[data-first-column]::before {
+    box-shadow:
+      inset 1px 0 0 0 var(--border-color),
+      inset -1px 0 0 0 var(--border-color),
+      inset 0 -1px 0 0 var(--border-color);
+  }
+
+  /* Header first column gets all four borders */
+  .navi_table[data-border-collapse]
+    .navi_table_cell[data-first-row][data-first-column]::before {
+    box-shadow:
+      inset 0 1px 0 0 var(--border-color),
+      inset 1px 0 0 0 var(--border-color),
+      inset -1px 0 0 0 var(--border-color),
+      inset 0 -1px 0 0 var(--border-color);
+  }
+
+  /* Focus styles */
+  .navi_table_cell[data-focus] {
+    outline: none; /* Remove default outline */
+  }
+
+  .navi_table_cell[data-focus]::after {
+    box-shadow:
+      inset 0 2px 0 0 var(--focus-border-color),
+      inset -2px 0 0 0 var(--focus-border-color),
+      inset 0 -2px 0 0 var(--focus-border-color),
+      inset 2px 0 0 0 var(--focus-border-color) !important;
+  }
+
+  .navi_table {
+    font-size: 16px;
+    font-family: Arial;
+
+    --editing-border-color: #a8c7fa;
+  }
+
+  .navi_table_cell[data-editing] .navi_table_cell_content {
+    outline: 2px solid #a8c7fa;
+    outline-offset: 0px;
+  }
+
+  .navi_table_cell[data-editing] input {
+    width: 100%;
+    height: 100%;
+    display: inline-flex;
+    flex-grow: 1;
+    border-radius: 0; /* match table cell border-radius */
+    border: none;
+    font-size: 16px;
+  }
+
+  .navi_table_cell[data-editing]
+    input[type="number"]::-webkit-inner-spin-button {
+    width: 14px;
+    height: 30px;
+  }
+
+  .navi_table_cell[data-editing] {
+    outline: 2px solid var(--editing-border-color);
+    z-index: ${Z_INDEX_EDITING};
+  }
+`;

package/src/components/table/table_ui.jsx

@@ -0,0 +1,49 @@
+import { visibleRectEffect } from "@jsenv/dom";
+import { createPortal, forwardRef } from "preact/compat";
+import { useLayoutEffect } from "preact/hooks";
+
+import { Z_INDEX_TABLE_UI } from "./z_indexes.js";
+
+import.meta.css = /* css */ `
+  .navi_table_ui {
+    position: fixed;
+    z-index: ${Z_INDEX_TABLE_UI};
+    overflow: hidden; /* Ensure UI elements cannot impact scrollbars of the document  */
+    inset: 0;
+    pointer-events: none; /* UI elements must use pointer-events: auto if they need to be interactive */
+    /* background: rgba(0, 255, 0, 0.2); */
+  }
+`;
+
+export const TableUI = forwardRef((props, ref) => {
+  const { tableRef, tableId, children } = props;
+
+  // ui positioning
+  useLayoutEffect(() => {
+    const ui = ref.current;
+    const table = tableRef.current;
+    if (!ui || !table) {
+      return null;
+    }
+
+    // TODO: external code should be able to call tableVisibleRectEffect.check();
+    // (for the drag operation when we scroll)
+    // -> actually not that important because browser will dispatch "scroll" events
+    // cause by programmatic scrolls before re-painting
+    // -> no intermediate state visible to the user where overlay is not in sync
+    const tableVisibleRectEffect = visibleRectEffect(table, (visibleRect) => {
+      ui.style.setProperty("--table-visual-left", `${visibleRect.left}px`);
+      ui.style.setProperty("--table-visual-width", `${visibleRect.width}px`);
+      ui.style.setProperty("--table-visual-top", `${visibleRect.top}px`);
+      ui.style.setProperty("--table-visual-height", `${visibleRect.height}px`);
+    });
+    return tableVisibleRectEffect.disconnect;
+  });
+
+  return createPortal(
+    <div ref={ref} className="navi_table_ui" data-overlay-for={tableId}>
+      {children}
+    </div>,
+    document.body,
+  );
+});

package/src/components/table/use_cells_and_columns.js

@@ -0,0 +1,90 @@
+import { useMemo, useState } from "preact/hooks";
+
+export const useCellsAndColumns = (cells, columns) => {
+  const [columnIds, idToColumnMap] = useMemo(() => {
+    const columnIds = [];
+    const idToColumnMap = new Map();
+    for (const column of columns) {
+      const columnId = column.id;
+      columnIds.push(columnId);
+      idToColumnMap.set(columnId, column);
+    }
+    return [columnIds, idToColumnMap];
+  }, [columns]);
+  const [orderedAllColumnIds, setOrderedAllColumnIds] = useState(columnIds);
+  const orderedColumnIds = [];
+  for (const columnId of orderedAllColumnIds) {
+    if (!columnIds.includes(columnId)) {
+      // generated column (like the row column)
+      continue;
+    }
+    orderedColumnIds.push(columnId);
+  }
+  const orderedColumns = [];
+  for (const columnId of orderedColumnIds) {
+    const column = idToColumnMap.get(columnId);
+    orderedColumns.push(column);
+  }
+
+  // Base cell values in original column order (2D array: rows x columns)
+  const [baseCells, setBaseCells] = useState(cells);
+
+  // Memoized index mapping for performance - maps display index to original index
+  const columnOrderedIndexMap = useMemo(() => {
+    const indexMap = new Map();
+    for (let columnIndex = 0; columnIndex < columnIds.length; columnIndex++) {
+      const columnIdAtThisIndex = orderedColumnIds[columnIndex];
+      const originalIndex = columnIds.indexOf(columnIdAtThisIndex);
+      indexMap.set(columnIndex, originalIndex);
+    }
+    return indexMap;
+  }, [columnIds, orderedColumnIds]);
+
+  // Derived state: reorder cell values according to column display order
+  const orderedCells = useMemo(() => {
+    const reorderedCells = [];
+    for (let y = 0; y < baseCells.length; y++) {
+      const originalRow = baseCells[y];
+      const reorderedRow = [];
+      for (let x = 0; x < orderedColumnIds.length; x++) {
+        const columnOrderedIndex = columnOrderedIndexMap.get(x);
+        const cellValue = originalRow[columnOrderedIndex];
+        reorderedRow.push(cellValue);
+      }
+      reorderedCells.push(reorderedRow);
+    }
+    return reorderedCells;
+  }, [baseCells, columnOrderedIndexMap, orderedColumnIds.length]);
+
+  const setCellValue = ({ columnIndex, rowIndex }, value) => {
+    const originalColumnIndex = columnOrderedIndexMap.get(columnIndex);
+    if (originalColumnIndex === undefined) {
+      console.warn(`Invalid column index: ${columnIndex}`);
+      return;
+    }
+    setBaseCells((previousCells) => {
+      const newCells = [];
+      for (let y = 0; y < previousCells.length; y++) {
+        const currentRow = previousCells[y];
+        if (y !== rowIndex) {
+          newCells.push(currentRow);
+          continue;
+        }
+        const newRow = [];
+        for (let x = 0; x < currentRow.length; x++) {
+          const cellValue = x === originalColumnIndex ? value : currentRow[x];
+          newRow.push(cellValue);
+        }
+        newCells.push(newRow);
+      }
+      return newCells;
+    });
+  };
+
+  return {
+    cells: orderedCells,
+    setCellValue,
+    columns: orderedColumns,
+    setColumnOrder: setOrderedAllColumnIds,
+  };
+};

package/src/components/table/use_object_array_to_cells.js

@@ -0,0 +1,46 @@
+import { useMemo } from "preact/hooks";
+
+/**
+ * Custom hook for converting an array of objects into a 2D array of cell values.
+ *
+ * This hook is essential for table components that receive data as objects but need
+ * to work with a 2D array structure for rendering and manipulation:
+ *
+ * 1. **Object to Array Conversion**: Extracts values from object properties based
+ *    on column definitions, creating a consistent 2D array structure.
+ *
+ * 2. **Column Mapping**: Uses column names/keys to determine which object property
+ *    corresponds to each column position.
+ *
+ * 3. **Missing Data Handling**: Provides fallback values when object properties
+ *    don't exist for specific columns.
+ *
+ * 4. **Performance**: Memoized to avoid unnecessary recalculations when data
+ *    or column definitions haven't changed.
+ *
+ * Common use case: Converting API response data (array of objects) into table-ready
+ * format for rendering with existing cell management hooks.
+ */
+
+/**
+ * Convert an array of objects into a 2D array of cell values
+ * @param {Array<Object>} data - Array of objects to convert
+ * @param {Array<Object>} columns - Column definitions
+ * @param {string} columns[].key - Property key to extract from each object
+ * @param {*} [columns[].defaultValue] - Default value when property is missing (optional)
+ * @returns {Array<Array>} 2D array of cell values
+ */
+export const useObjectArrayToCells = (data, columns) => {
+  // Convert object array to 2D cell values array
+  const cellValues = useMemo(() => {
+    return data.map((rowObject) =>
+      columns.map((column) => {
+        const value = rowObject[column.key];
+        // Return the value if it exists, otherwise use default or empty string
+        return value !== undefined ? value : (column.defaultValue ?? "");
+      }),
+    );
+  }, [data, columns]);
+
+  return cellValues;
+};

package/src/components/table/z_indexes.js

@@ -0,0 +1,23 @@
+export const Z_INDEX_EDITING = 1; /* To go above neighbours, but should not be too big to stay under the sticky cells */
+
+/* needed because cell uses position:relative, sticky must win even if before in DOM order */
+export const Z_INDEX_STICKY_COLUMN = Z_INDEX_EDITING + 1;
+export const Z_INDEX_STICKY_ROW = Z_INDEX_STICKY_COLUMN + 1;
+export const Z_INDEX_STICKY_CORNER = Z_INDEX_STICKY_ROW + 1;
+
+export const Z_INDEX_STICKY_FRONTIER_BACKDROP = Z_INDEX_STICKY_CORNER + 1;
+export const Z_INDEX_STICKY_FRONTIER_PREVIEW =
+  Z_INDEX_STICKY_FRONTIER_BACKDROP + 1;
+export const Z_INDEX_STICKY_FRONTIER_GHOST =
+  Z_INDEX_STICKY_FRONTIER_PREVIEW + 1;
+
+export const Z_INDEX_TABLE_UI_CONTAINER = Z_INDEX_STICKY_CORNER + 1;
+export const Z_INDEX_DRAGGING_CLONE = Z_INDEX_STICKY_CORNER + 1; // above sticky cells
+export const Z_INDEX_RESIZER_BACKDROP = Z_INDEX_STICKY_CORNER + 1; // above sticky cells
+
+export const Z_INDEX_CELL_FOREGROUND = 1;
+export const Z_INDEX_STICKY_FRONTIER_HANDLE = 2; // above the cell placeholder to keep the sticky frontier visible
+export const Z_INDEX_RESIZER_HANDLE = Z_INDEX_STICKY_FRONTIER_HANDLE + 1;
+export const Z_INDEX_DROP_PREVIEW = Z_INDEX_STICKY_CORNER + 1;
+
+export const Z_INDEX_TABLE_UI = Z_INDEX_STICKY_CORNER + 1;

package/src/components/tablist/tablist.jsx

@@ -0,0 +1,99 @@
+import.meta.css = /* css */ `
+  .navi_tablist {
+    display: flex;
+    overflow-x: auto;
+    overflow-y: hidden;
+    justify-content: space-between;
+  }
+
+  .navi_tablist > ul {
+    align-items: center;
+    display: flex;
+    gap: 0.5rem;
+    list-style: none;
+    margin: 0;
+    padding: 0;
+  }
+
+  .navi_tablist > ul > li {
+    display: inline-flex;
+    position: relative;
+  }
+
+  .navi_tab {
+    white-space: nowrap;
+    display: flex;
+    flex-direction: column;
+  }
+
+  .navi_tab_content {
+    transition: background 0.12s ease-out;
+    border-radius: 6px;
+    text-decoration: none;
+    line-height: 30px;
+    display: flex;
+    padding: 0 0.5rem;
+  }
+
+  .navi_tab:hover .navi_tab_content {
+    background: #dae0e7;
+    color: #010409;
+  }
+
+  .navi_tab .active_marker {
+    display: flex;
+    background: transparent;
+    border-radius: 0.1px;
+    width: 100%;
+    z-index: 1;
+    height: 2px;
+    margin-top: 5px;
+  }
+
+  /* Hidden bold clone to reserve space for bold width without affecting height */
+  .navi_tab_content_bold_clone {
+    font-weight: 600; /* force bold to compute max width */
+    visibility: hidden; /* not visible */
+    display: block; /* in-flow so it contributes to width */
+    height: 0; /* zero height so it doesn't change layout height */
+    overflow: hidden; /* avoid any accidental height */
+    pointer-events: none; /* inert */
+  }
+
+  .navi_tab[aria-selected="true"] .active_marker {
+    background: rgb(205, 52, 37);
+  }
+
+  .navi_tab[aria-selected="true"] .navi_tab_content {
+    font-weight: 600;
+  }
+`;
+
+export const TabList = ({ children, ...props }) => {
+  return (
+    <nav className="navi_tablist" role="tablist" {...props}>
+      <ul>
+        {children.map((child) => {
+          return <li key={child.props.key}>{child}</li>;
+        })}
+      </ul>
+    </nav>
+  );
+};
+
+export const Tab = ({ children, selected, ...props }) => {
+  return (
+    <div
+      className="navi_tab"
+      role="tab"
+      aria-selected={selected ? "true" : "false"}
+      {...props}
+    >
+      <div className="navi_tab_content">{children}</div>
+      <div className="navi_tab_content_bold_clone" aria-hidden="true">
+        {children}
+      </div>
+      <span className="active_marker"></span>
+    </div>
+  );
+};

package/src/components/text/overflow.jsx

@@ -0,0 +1,15 @@
+export const Overflow = ({ className, children, afterContent }) => {
+  return (
+    <div
+      className={className}
+      style="display: flex; flex-wrap: wrap; overflow: hidden; width: 100%; box-sizing: border-box; white-space: nowrap; text-overflow: ellipsis;"
+    >
+      <div style="display: flex; flex-grow: 1; width: 0; gap: 0.3em">
+        <div style="overflow: hidden; max-width: 100%; text-overflow: ellipsis;">
+          {children}
+        </div>
+        {afterContent}
+      </div>
+    </div>
+  );
+};

package/src/components/text/text_and_count.jsx

@@ -0,0 +1,28 @@
+import { Overflow } from "./overflow.jsx";
+
+import.meta.css = /* css */ `
+  .text_and_count {
+    display: flex;
+    align-items: center;
+    gap: 3px;
+    flex: 1;
+    white-space: nowrap;
+  }
+
+  .count {
+    position: relative;
+    top: -1px;
+    color: rgba(28, 43, 52, 0.4);
+  }
+`;
+
+export const TextAndCount = ({ text, count }) => {
+  return (
+    <Overflow
+      className="text_and_count"
+      afterContent={count > 0 && <span className="count">({count})</span>}
+    >
+      <span className="label">{text}</span>
+    </Overflow>
+  );
+};

package/src/components/ui_transition.jsx

@@ -0,0 +1,128 @@
+/**
+ * UITransition
+ *
+ * A Preact component that enables smooth animated transitions between its children when the content changes.
+ * It observes content keys and phases to create different types of transitions.
+ *
+ * Features:
+ * - Content transitions: Between different content keys (e.g., user profiles, search results)
+ * - Phase transitions: Between loading/content/error states for the same content key
+ * - Automatic size animation to accommodate content changes
+ * - Configurable transition types: "slide-left", "cross-fade"
+ * - Independent duration control for content and phase transitions
+ *
+ * Usage:
+ * - Wrap dynamic content in <UITransition> to animate between states
+ * - Set a unique `data-content-key` on your rendered content to identify each content variant
+ * - Use `data-content-phase` to mark loading/error states for phase transitions
+ * - Configure transition types and durations for both content and phase changes
+ *
+ * Example:
+ *
+ *   <UITransition
+ *     transitionType="slide-left"
+ *     transitionDuration={400}
+ *     phaseTransitionType="cross-fade"
+ *     phaseTransitionDuration={300}
+ *   >
+ *     {isLoading
+ *       ? <Spinner data-content-key={userId} data-content-phase />
+ *       : <UserProfile user={user} data-content-key={userId} />}
+ *   </UITransition>
+ *
+ * When `data-content-key` changes, UITransition animates content transitions.
+ * When `data-content-phase` changes for the same key, it animates phase transitions.
+ */
+
+import { initUITransition } from "@jsenv/dom";
+import { createContext } from "preact";
+import { useContext, useLayoutEffect, useRef, useState } from "preact/hooks";
+
+const ContentKeyContext = createContext();
+
+export const UITransition = ({
+  children,
+  contentKey,
+  sizeTransition,
+  sizeTransitionDuration,
+  transitionType,
+  transitionDuration,
+  phaseTransitionType,
+  phaseTransitionDuration,
+  debugTransition,
+  ...props
+}) => {
+  const [contentKeyFromContext, setContentKeyFromContext] = useState();
+  const effectiveContentKey = contentKey || contentKeyFromContext;
+
+  const ref = useRef();
+  useLayoutEffect(() => {
+    const uiTransition = initUITransition(ref.current);
+    return () => {
+      uiTransition.cleanup();
+    };
+  }, []);
+
+  return (
+    <ContentKeyContext.Provider value={setContentKeyFromContext}>
+      <div
+        ref={ref}
+        {...props}
+        className="ui_transition_container"
+        data-size-transition={sizeTransition ? "" : undefined}
+        data-size-transition-duration={
+          sizeTransitionDuration ? sizeTransitionDuration : undefined
+        }
+        data-content-transition={transitionType ? transitionType : undefined}
+        data-content-transition-duration={
+          transitionDuration ? transitionDuration : undefined
+        }
+        data-phase-transition={
+          phaseTransitionType ? phaseTransitionType : undefined
+        }
+        data-phase-transition-duration={
+          phaseTransitionDuration ? phaseTransitionDuration : undefined
+        }
+        data-debug-transition={debugTransition ? "" : undefined}
+      >
+        <div className="ui_transition_outer_wrapper">
+          <div className="ui_transition_measure_wrapper">
+            <div
+              className="ui_transition_slot"
+              data-content-key={
+                effectiveContentKey ? effectiveContentKey : undefined
+              }
+            >
+              {children}
+            </div>
+            <div className="ui_transition_phase_overlay"></div>
+          </div>
+        </div>
+        <div className="ui_transition_content_overlay"></div>
+      </div>
+    </ContentKeyContext.Provider>
+  );
+};
+
+export const useContentKey = (key, enabled) => {
+  const setKey = useContext(ContentKeyContext);
+  if (setKey && enabled) {
+    setKey(key);
+  }
+  useLayoutEffect(() => {
+    if (!setKey || !enabled) {
+      return null;
+    }
+    return () => {
+      setKey((v) => {
+        if (v !== key) {
+          // the current key is different from the one we set
+          // it means another component set it in the meantime
+          // we should not clear it
+          return v;
+        }
+        return undefined;
+      });
+    };
+  }, [enabled]);
+};