@12-apps/ui 1.0.0 → 1.3.1

package/src/components/data-display/DataViews/use-data-views-state.ts

@@ -0,0 +1,349 @@
+"use client";
+
+import { useEffect, useMemo, useRef, useState } from "react";
+
+import { type GridColumn } from "../DataGrid";
+import { type SortFieldDefinition } from "../../layout/ContentToolbar";
+
+import { filterRows } from "./data-views-filter";
+import {
+  buildGridColumns,
+  buildRowActionsColumn,
+  computeActiveFilterCount,
+  defaultSortFields,
+  isActionsColumn,
+} from "./data-views-grid-helpers";
+import {
+  emptyViewState,
+  type DataViewColumn,
+  type DataViewServer,
+  type DataViewState,
+  type DataViewSyncState,
+  type FilterFieldConfig,
+  type RangeFieldConfig,
+  type RangeValue,
+  type RowAction,
+} from "./data-views-types";
+
+/** Inputs the hook needs to own the view state + derived data. */
+interface UseDataViewsStateArgs<T extends Record<string, unknown>> {
+  rows: T[];
+  columns: DataViewColumn<T>[];
+  fields: FilterFieldConfig<T>[];
+  rangeFields: RangeFieldConfig<T>[];
+  getRowId: (row: T) => string | number;
+  onRowClick?: (row: T) => void;
+  appliedState?: DataViewState;
+  /**
+   * URL-driven controls (search/pills/ranges/sort) that re-apply on reference
+   * change while preserving column visibility — see {@link DataViewSyncState}.
+   */
+  syncState?: DataViewSyncState;
+  onStateChange?: (state: DataViewState) => void;
+  testIdPrefix: string;
+  sortFields?: SortFieldDefinition[];
+  rowActions?: RowAction<T>[];
+  rowActionsLeading?: (row: T) => React.ReactNode;
+  /** Bespoke per-row menu rendered in the actions column instead of the auto kebab. */
+  renderRowMenu?: (row: T) => React.ReactNode;
+  /**
+   * When present, the table is BACKEND-driven: `rows` is already the current
+   * page (no in-browser filter/sort/paginate), and query changes re-fetch via
+   * `server.onQueryChange`. Omit for the legacy client-side behaviour.
+   */
+  server?: DataViewServer;
+}
+
+/** A column the user may show/hide via the toolbar's ColumnsMenu. */
+export interface HideableColumn {
+  id: string;
+  label: string;
+}
+
+/** Everything the DataViewsGrid render needs; keeps the component itself thin. */
+export interface DataViewsController<T extends Record<string, unknown>> {
+  state: DataViewState;
+  ranges: Record<string, RangeValue>;
+  patch: (next: Partial<DataViewState>) => void;
+  matched: T[];
+  gridColumns: GridColumn<T>[];
+  /** Columns eligible for the show/hide menu (hideable, with a text header). */
+  hideableColumns: HideableColumn[];
+  /** Toggle one column's visibility in the current view state. */
+  toggleColumn: (id: string, visible: boolean) => void;
+  selectedIds: Set<string | number>;
+  setSelectedIds: (ids: Set<string | number>) => void;
+  selectedRows: T[];
+  clearSelection: () => void;
+  selectAll: () => void;
+  filterOpen: boolean;
+  setFilterOpen: (open: boolean) => void;
+  resolvedSortFields: SortFieldDefinition[];
+  activeSortField: string;
+  activeSortOrder: "asc" | "desc";
+  activeFilterCount: number;
+  /** True when the table is backend-driven (server mode). */
+  serverMode: boolean;
+  /** Server-mode pagination: 1-based current page (1 when client mode). */
+  serverPage: number;
+  /** Server-mode pagination: total pages (1 when client mode). */
+  serverPageCount: number;
+  /** Server-mode: total matched rows across all pages (drives the counter). */
+  serverTotalCount: number;
+  /** Server-mode: request a specific 1-based page (re-fetches via onQueryChange). */
+  changePage: (page: number) => void;
+}
+
+/**
+ * The columns the user may show/hide: explicitly hideable (not `hideable:false`,
+ * which marks structural columns like the image thumbnail or actions kebab) and
+ * carrying a text header to label the checkbox.
+ */
+function computeHideableColumns<T extends Record<string, unknown>>(
+  columns: DataViewColumn<T>[],
+): HideableColumn[] {
+  return columns
+    .filter((col) => col.hideable !== false && typeof col.header === "string" && col.header !== "")
+    .map((col) => ({ id: col.id, label: col.header as string }));
+}
+
+/**
+ * Server-mode wiring extracted from {@link useDataViewsState} (keeps it within
+ * the size/complexity budget): re-fetch on every effective-query change (page
+ * resets to 1) and expose `changePage` for the pagination control. Read the
+ * latest `state`/`server` at fire time so an inline `server` object per render
+ * doesn't loop the effect.
+ */
+function useServerQuery(server: DataViewServer | undefined, state: DataViewState): {
+  changePage: (page: number) => void;
+} {
+  const emit = (page: number): void => {
+    if (!server) return;
+    server.onQueryChange({
+      search: state.search,
+      pills: state.pills,
+      ranges: state.ranges ?? {},
+      sortBy: state.sortBy,
+      page,
+      pageSize: server.pageSize,
+    });
+  };
+  const queryKey = server
+    ? JSON.stringify({ q: state.search, pills: state.pills, ranges: state.ranges ?? {}, sort: state.sortBy })
+    : "";
+  const firstQuery = useRef(true);
+  useEffect(() => {
+    if (!server) return;
+    if (firstQuery.current) {
+      firstQuery.current = false;
+      return;
+    }
+    emit(1);
+    // Emit only when the query key changes; `emit` reads fresh state at fire time.
+  }, [queryKey]);
+  return { changePage: (page: number) => emit(page) };
+}
+
+/** The controller's server-mode derived fields (or client-mode defaults). */
+function serverDerived(
+  server: DataViewServer | undefined,
+  fallbackCount: number,
+): { serverMode: boolean; serverPage: number; serverPageCount: number; serverTotalCount: number } {
+  if (!server) {
+    return { serverMode: false, serverPage: 1, serverPageCount: 1, serverTotalCount: fallbackCount };
+  }
+  return {
+    serverMode: true,
+    serverPage: server.page,
+    serverPageCount: Math.max(1, Math.ceil(server.totalCount / server.pageSize)),
+    serverTotalCount: server.totalCount,
+  };
+}
+
+/**
+ * The rows to render: in server mode `rows` is already the current page (the
+ * backend filtered/sorted/paginated), so it passes through untouched; otherwise
+ * the client search/pill/range filter narrows it.
+ */
+function useMatchedRows<T extends Record<string, unknown>>(
+  server: DataViewServer | undefined,
+  rows: T[],
+  columns: DataViewColumn<T>[],
+  fields: FilterFieldConfig<T>[],
+  rangeFields: RangeFieldConfig<T>[],
+  state: DataViewState,
+): T[] {
+  return useMemo(
+    () =>
+      server
+        ? rows
+        : filterRows(
+            rows,
+            columns,
+            fields,
+            { search: state.search, pills: state.pills, ranges: state.ranges },
+            rangeFields,
+          ),
+    [server, rows, columns, fields, rangeFields, state.search, state.pills, state.ranges],
+  );
+}
+
+/** Add or remove one column id from the visible-columns list. */
+function nextVisibleColumns(current: string[], id: string, visible: boolean): string[] {
+  const without = current.filter((colId) => colId !== id);
+  return visible ? [...without, id] : without;
+}
+
+/**
+ * Reconcile external state changes and surface every change to the caller:
+ * - `appliedState` (a saved view) fully REPLACES the state — it is columns-
+ *   authoritative, so applying a view restores its filters, sort AND columns.
+ * - `syncState` (URL-driven controls) MERGES over the current state, leaving
+ *   `visibleColumns` untouched — so browser back/forward or a same-route
+ *   deep-link re-applies search/pills/sort without wiping a user's hidden columns.
+ * Each channel only fires when its own reference changes (after the first run).
+ */
+function useStateSyncEffects(
+  appliedState: DataViewState | undefined,
+  syncState: DataViewSyncState | undefined,
+  state: DataViewState,
+  onStateChange: ((state: DataViewState) => void) | undefined,
+  setState: React.Dispatch<React.SetStateAction<DataViewState>>,
+): void {
+  const firstApplied = useRef(true);
+  useEffect(() => {
+    if (firstApplied.current) {
+      firstApplied.current = false;
+      return;
+    }
+    if (appliedState) setState(appliedState);
+    // `setState` is a stable useState setter (passed in), included to satisfy
+    // exhaustive-deps; the effect still only re-applies when `appliedState` changes.
+  }, [appliedState, setState]);
+  const firstSync = useRef(true);
+  useEffect(() => {
+    if (firstSync.current) {
+      firstSync.current = false;
+      return;
+    }
+    // Merge — keep the current `visibleColumns` (never URL-carried); only the
+    // URL-driven controls change.
+    if (syncState) setState((prev) => ({ ...prev, ...syncState }));
+  }, [syncState, setState]);
+  useEffect(() => {
+    onStateChange?.(state);
+  }, [state, onStateChange]);
+}
+
+/**
+ * Append the auto kebab actions column unless the page already defines one. The
+ * column is added when there are `rowActions` OR a bespoke `renderRowMenu` (an
+ * entity's self-contained menu that owns its own popups).
+ */
+function appendActionsColumn<T extends Record<string, unknown>>(
+  columns: DataViewColumn<T>[],
+  opts: {
+    rowActions?: RowAction<T>[];
+    rowActionsLeading?: (row: T) => React.ReactNode;
+    renderRowMenu?: (row: T) => React.ReactNode;
+    testIdPrefix: string;
+    getRowId: (row: T) => string | number;
+  },
+): DataViewColumn<T>[] {
+  const { rowActions, rowActionsLeading, renderRowMenu, testIdPrefix, getRowId } = opts;
+  if ((!rowActions && !renderRowMenu) || columns.some(isActionsColumn)) return columns;
+  return [
+    ...columns,
+    buildRowActionsColumn({
+      rowActions: rowActions ?? [],
+      leading: rowActionsLeading,
+      testIdPrefix,
+      getRowId,
+      renderRowMenu,
+    }),
+  ];
+}
+
+/**
+ * Owns the DataViews view state (search/pills/ranges/sort/visibleColumns),
+ * multi-select, the filter-panel toggle, and every derived value (filtered rows,
+ * grid columns, active sort/filter counts). Extracted from the component so the
+ * render stays within the size/complexity budget.
+ */
+export function useDataViewsState<T extends Record<string, unknown>>({
+  rows,
+  columns,
+  fields,
+  rangeFields,
+  getRowId,
+  onRowClick,
+  appliedState,
+  syncState,
+  onStateChange,
+  testIdPrefix,
+  sortFields,
+  rowActions,
+  rowActionsLeading,
+  renderRowMenu,
+  server,
+}: UseDataViewsStateArgs<T>): DataViewsController<T> {
+  // Append the auto kebab column unless the page defines one (see helper).
+  const columnsWithActions = useMemo(
+    () =>
+      appendActionsColumn(columns, { rowActions, rowActionsLeading, renderRowMenu, testIdPrefix, getRowId }),
+    [columns, rowActions, rowActionsLeading, renderRowMenu, testIdPrefix, getRowId],
+  );
+  const allColumnIds = useMemo(() => columnsWithActions.map((col) => col.id), [columnsWithActions]);
+  // Seed once: a saved view (`appliedState`) or a pristine all-columns state, with
+  // the URL-driven controls (`syncState`) merged over it so a deep-linked filter
+  // is reflected on first render. Column visibility is never URL-carried.
+  const [state, setState] = useState<DataViewState>(() => {
+    const seed = appliedState ?? emptyViewState(allColumnIds);
+    return syncState ? { ...seed, ...syncState } : seed;
+  });
+  const [selectedIds, setSelectedIdsState] = useState<Set<string | number>>(new Set());
+  const [filterOpen, setFilterOpen] = useState(false);
+
+  useStateSyncEffects(appliedState, syncState, state, onStateChange, setState);
+
+  const patch = (next: Partial<DataViewState>): void => setState((prev) => ({ ...prev, ...next }));
+  const matched = useMatchedRows(server, rows, columns, fields, rangeFields, state);
+  // Server mode: re-fetch on query change (page resets to 1) + drive pagination.
+  const { changePage } = useServerQuery(server, state);
+  const gridColumns = useMemo(
+    () => buildGridColumns(columnsWithActions, state.visibleColumns, onRowClick),
+    [columnsWithActions, onRowClick, state.visibleColumns],
+  );
+  const hideableColumns = useMemo(() => computeHideableColumns(columnsWithActions), [columnsWithActions]);
+  const toggleColumn = (id: string, visible: boolean): void =>
+    setState((prev) => ({ ...prev, visibleColumns: nextVisibleColumns(prev.visibleColumns, id, visible) }));
+  const selectedRows = useMemo(
+    () => matched.filter((row) => selectedIds.has(getRowId(row))),
+    [matched, selectedIds, getRowId],
+  );
+  const resolvedSortFields = sortFields ?? defaultSortFields(columns);
+  const activeSort = state.sortBy?.[0];
+
+  return {
+    state,
+    ranges: state.ranges ?? {},
+    patch,
+    matched,
+    gridColumns,
+    hideableColumns,
+    toggleColumn,
+    selectedIds,
+    setSelectedIds: setSelectedIdsState,
+    selectedRows,
+    clearSelection: () => setSelectedIdsState(new Set()),
+    selectAll: () => setSelectedIdsState(new Set(matched.map((row) => getRowId(row)))),
+    filterOpen,
+    setFilterOpen,
+    resolvedSortFields,
+    activeSortField: activeSort?.id ?? resolvedSortFields[0]?.value ?? "",
+    activeSortOrder: activeSort?.dir === "desc" ? "desc" : "asc",
+    activeFilterCount: computeActiveFilterCount(state, fields, rangeFields),
+    ...serverDerived(server, matched.length),
+    changePage,
+  };
+}

package/src/components/data-display/DateTimeDisplay/DateTimeDisplay.hooks.ts

@@ -0,0 +1,104 @@
+import { useMemo } from 'react';
+
+import type { DateTimeDisplayProps } from './DateTimeDisplay.types';
+
+type DateFormat = NonNullable<DateTimeDisplayProps['dateFormat']>;
+type TimeFormat = NonNullable<DateTimeDisplayProps['timeFormat']>;
+
+/**
+ * Format a date for display
+ */
+function formatDatePart(date: Date, format: DateFormat): string {
+  const options: Intl.DateTimeFormatOptions = {
+    year: 'numeric',
+    month: format === 'numeric' ? '2-digit' : format === 'short' ? 'short' : 'long',
+    day: format === 'numeric' ? '2-digit' : 'numeric',
+  };
+  return date.toLocaleDateString(undefined, options);
+}
+
+/**
+ * Format time for display
+ */
+function formatTimePart(date: Date, timeFormat: TimeFormat, showTimezone: boolean): string {
+  const options: Intl.DateTimeFormatOptions = {
+    hour: 'numeric',
+    minute: '2-digit',
+    hour12: timeFormat === '12h',
+    ...(showTimezone && { timeZoneName: 'short' }),
+  };
+  return date.toLocaleTimeString(undefined, options);
+}
+
+interface DateTimeParts {
+  /** null when no date was given or the given one does not parse. */
+  dateObj: Date | null;
+  formattedDate: string | null;
+  formattedTime: string | null;
+  /** The long form shown in the tooltip. */
+  fullDateTime: string | null;
+}
+
+interface DateTimePartsArgs {
+  date: DateTimeDisplayProps['date'];
+  dateFormat: DateFormat;
+  timeFormat: TimeFormat;
+  showTimezone: boolean;
+}
+
+const isValidDate = (date: Date | null): date is Date =>
+  date !== null && !isNaN(date.getTime());
+
+/**
+ * A date landing exactly on midnight is taken to carry no time of day — callers
+ * pass date-only values as `new Date('2026-08-05')`, which parses to 00:00:00.
+ * The cost is that a genuine midnight timestamp renders without its time.
+ */
+const hasTimeOfDay = (date: Date): boolean =>
+  !(date.getHours() === 0 && date.getMinutes() === 0 && date.getSeconds() === 0);
+
+const longForm = (date: Date, withTime: boolean): string => {
+  const dateParts: Intl.DateTimeFormatOptions = {
+    weekday: 'long',
+    year: 'numeric',
+    month: 'long',
+    day: 'numeric',
+  };
+
+  if (!withTime) return date.toLocaleDateString(undefined, dateParts);
+
+  return date.toLocaleString(undefined, {
+    ...dateParts,
+    hour: 'numeric',
+    minute: '2-digit',
+    second: '2-digit',
+    timeZoneName: 'short',
+  });
+};
+
+export const useDateTimeParts = ({
+  date,
+  dateFormat,
+  timeFormat,
+  showTimezone,
+}: DateTimePartsArgs): DateTimeParts => {
+  const dateObj = useMemo(() => {
+    if (!date) return null;
+    return date instanceof Date ? date : new Date(date);
+  }, [date]);
+
+  return useMemo(() => {
+    if (!isValidDate(dateObj)) {
+      return { dateObj: null, formattedDate: null, formattedTime: null, fullDateTime: null };
+    }
+
+    const withTime = hasTimeOfDay(dateObj);
+
+    return {
+      dateObj,
+      formattedDate: formatDatePart(dateObj, dateFormat),
+      formattedTime: withTime ? formatTimePart(dateObj, timeFormat, showTimezone) : null,
+      fullDateTime: longForm(dateObj, withTime),
+    };
+  }, [dateObj, dateFormat, timeFormat, showTimezone]);
+};

package/src/components/data-display/DateTimeDisplay/DateTimeDisplay.tsx

@@ -1,37 +1,9 @@
 import { Box, Tooltip, Typography } from '@mui/material';
-import { forwardRef, useMemo } from 'react';
+import { forwardRef } from 'react';
 
+import { useDateTimeParts } from './DateTimeDisplay.hooks';
 import type { DateTimeDisplayProps } from './DateTimeDisplay.types';
 
-/**
- * Format a date for display
- */
-function formatDatePart(date: Date, format: 'short' | 'long' | 'numeric'): string {
-  const options: Intl.DateTimeFormatOptions = {
-    year: 'numeric',
-    month: format === 'numeric' ? '2-digit' : format === 'short' ? 'short' : 'long',
-    day: format === 'numeric' ? '2-digit' : 'numeric',
-  };
-  return date.toLocaleDateString(undefined, options);
-}
-
-/**
- * Format time for display
- */
-function formatTimePart(
-  date: Date,
-  timeFormat: '12h' | '24h',
-  showTimezone: boolean,
-): string {
-  const options: Intl.DateTimeFormatOptions = {
-    hour: 'numeric',
-    minute: '2-digit',
-    hour12: timeFormat === '12h',
-    ...(showTimezone && { timeZoneName: 'short' }),
-  };
-  return date.toLocaleTimeString(undefined, options);
-}
-
 /**
  * Get font sizes based on size prop
  */
@@ -47,6 +19,57 @@ function getFontSizes(size: 'small' | 'medium' | 'large') {
   }
 }
 
+interface StackedProps {
+  formattedDate: string | null;
+  formattedTime: string | null;
+  fontSizes: ReturnType<typeof getFontSizes>;
+  showTooltip: boolean;
+  sx: DateTimeDisplayProps['sx'];
+  dataTestId?: string;
+}
+
+const Stacked = forwardRef<HTMLSpanElement, StackedProps>(
+  ({ formattedDate, formattedTime, fontSizes, showTooltip, sx, dataTestId }, ref) => (
+    <Box
+      component="span"
+      ref={ref}
+      data-testid={dataTestId}
+      sx={{
+        display: 'inline-flex',
+        flexDirection: 'column',
+        lineHeight: 1.3,
+        cursor: showTooltip ? 'help' : 'default',
+        ...sx,
+      }}
+    >
+      <Typography
+        component="span"
+        sx={{
+          fontWeight: 500,
+          fontSize: fontSizes.date,
+        }}
+        data-testid={dataTestId ? `${dataTestId}-date` : undefined}
+      >
+        {formattedDate}
+      </Typography>
+      {formattedTime && (
+        <Typography
+          component="span"
+          sx={{
+            fontSize: fontSizes.time,
+            color: 'text.secondary',
+          }}
+          data-testid={dataTestId ? `${dataTestId}-time` : undefined}
+        >
+          {formattedTime}
+        </Typography>
+      )}
+    </Box>
+  ),
+);
+
+Stacked.displayName = 'DateTimeDisplayStacked';
+
 /**
  * DateTimeDisplay component - displays date and time in a stacked format
  * with date on one line and time on another.
@@ -66,63 +89,16 @@ export const DateTimeDisplay = forwardRef<HTMLSpanElement, DateTimeDisplayProps>
     },
     ref,
   ) => {
-    const dateObj = useMemo(() => {
-      if (!date) return null;
-      return date instanceof Date ? date : new Date(date);
-    }, [date]);
-
-    // Auto-detect if time is midnight (no meaningful time)
-    const hasTime = useMemo(() => {
-      if (!dateObj || isNaN(dateObj.getTime())) return false;
-      // If time is midnight (ignoring milliseconds), assume no time was provided
-      const hours = dateObj.getHours();
-      const minutes = dateObj.getMinutes();
-      const seconds = dateObj.getSeconds();
-      // Check if time is midnight (00:00:00) - ignore milliseconds
-      const isMidnight = hours === 0 && minutes === 0 && seconds === 0;
-      return !isMidnight;
-    }, [dateObj]);
-
-
-    const formattedDate = useMemo(() => {
-      if (!dateObj || isNaN(dateObj.getTime())) return null;
-      return formatDatePart(dateObj, dateFormat);
-    }, [dateObj, dateFormat]);
-
-    const formattedTime = useMemo(() => {
-      if (!dateObj || isNaN(dateObj.getTime()) || !hasTime) return null;
-      return formatTimePart(dateObj, timeFormat, showTimezone);
-    }, [dateObj, hasTime, timeFormat, showTimezone]);
-
-    const fullDateTime = useMemo(() => {
-      if (!dateObj || isNaN(dateObj.getTime())) return null;
-
-      // If no time to show, only show date in tooltip
-      if (!hasTime) {
-        return dateObj.toLocaleDateString(undefined, {
-          weekday: 'long',
-          year: 'numeric',
-          month: 'long',
-          day: 'numeric',
-        });
-      }
-
-      return dateObj.toLocaleString(undefined, {
-        weekday: 'long',
-        year: 'numeric',
-        month: 'long',
-        day: 'numeric',
-        hour: 'numeric',
-        minute: '2-digit',
-        second: '2-digit',
-        timeZoneName: 'short',
-      });
-    }, [dateObj, hasTime]);
-
+    const { dateObj, formattedDate, formattedTime, fullDateTime } = useDateTimeParts({
+      date,
+      dateFormat,
+      timeFormat,
+      showTimezone,
+    });
     const fontSizes = getFontSizes(size);
 
     // Handle invalid or missing date
-    if (!dateObj || isNaN(dateObj.getTime())) {
+    if (!dateObj) {
       return (
         <Box
           component="span"
@@ -136,41 +112,15 @@ export const DateTimeDisplay = forwardRef<HTMLSpanElement, DateTimeDisplayProps>
     }
 
     const content = (
-      <Box
-        component="span"
+      <Stacked
         ref={ref}
-        data-testid={dataTestId}
-        sx={{
-          display: 'inline-flex',
-          flexDirection: 'column',
-          lineHeight: 1.3,
-          cursor: showTooltip ? 'help' : 'default',
-          ...sx,
-        }}
-      >
-        <Typography
-          component="span"
-          sx={{
-            fontWeight: 500,
-            fontSize: fontSizes.date,
-          }}
-          data-testid={dataTestId ? `${dataTestId}-date` : undefined}
-        >
-          {formattedDate}
-        </Typography>
-        {formattedTime && (
-          <Typography
-            component="span"
-            sx={{
-              fontSize: fontSizes.time,
-              color: 'text.secondary',
-            }}
-            data-testid={dataTestId ? `${dataTestId}-time` : undefined}
-          >
-            {formattedTime}
-          </Typography>
-        )}
-      </Box>
+        formattedDate={formattedDate}
+        formattedTime={formattedTime}
+        fontSizes={fontSizes}
+        showTooltip={showTooltip}
+        sx={sx}
+        dataTestId={dataTestId}
+      />
     );
 
     if (!showTooltip) {

package/src/components/data-display/DescriptionItem/DescriptionItem.stories.tsx

@@ -1,4 +1,4 @@
-import { ContentCopy as ContentCopyIcon } from '@mui/icons-material';
+import ContentCopyIcon from '@mui/icons-material/ContentCopy';
 import { Box, Stack } from '@mui/material';
 import type { Meta, StoryObj } from '@storybook/react-vite';