@mshuja288/aksuicore 0.2.1 → 0.4.0

package/src/patterns/RecordWorkspace.tsx

@@ -1,6 +1,14 @@
 "use client";
 
-import { useMemo, useState, useSyncExternalStore, type MouseEvent, type ReactNode } from "react";
+import {
+  useEffect,
+  useMemo,
+  useRef,
+  useState,
+  useSyncExternalStore,
+  type MouseEvent,
+  type ReactNode,
+} from "react";
 import { createPortal } from "react-dom";
 import { Pagination } from "../primitives/Pagination";
 import { Select, type SelectOption } from "../primitives/Select";
@@ -23,13 +31,67 @@ export type TableColumn<T> = {
   /** When set, filter uses an exact-match Select instead of text contains. */
   filterOptions?: SelectOption[];
   filterPlaceholder?: string;
+  /** When false, column starts hidden. Default true. */
+  defaultVisible?: boolean;
+  /** Key sent to export APIs when different from `key` (e.g. PascalCase property name). */
+  exportKey?: string;
 };
 
+/** Formats supported by the shared table download control (matches akscore TableExport). */
+export type ExportDownloadFormat = "csv" | "xlsx" | "json";
+
+/** Column descriptors passed to `onDownload` (visible columns only). */
+export type ExportColumnRef = {
+  key: string;
+  header: string;
+};
+
+const EXPORT_FORMAT_OPTIONS: { format: ExportDownloadFormat; label: string }[] = [
+  { format: "csv", label: "CSV" },
+  { format: "xlsx", label: "Excel" },
+  { format: "json", label: "JSON" },
+];
+
 type SortDirection = "asc" | "desc";
 type SortState = { key: string; direction: SortDirection };
 type DetailLine = { label: string; value: string };
 type TooltipState = { x: number; y: number; lines: DetailLine[] };
 
+function defaultVisibleKeys<T>(columns: TableColumn<T>[]) {
+  return columns.filter((column) => column.defaultVisible !== false).map((column) => column.key);
+}
+
+function readStoredColumnKeys(prefsKey: string | undefined, fallback: string[], allowed: Set<string>) {
+  if (!prefsKey || typeof window === "undefined") {
+    return fallback;
+  }
+  try {
+    const raw = window.localStorage.getItem(prefsKey);
+    if (!raw) {
+      return fallback;
+    }
+    const parsed = JSON.parse(raw) as unknown;
+    if (!Array.isArray(parsed)) {
+      return fallback;
+    }
+    const keys = parsed.filter((entry): entry is string => typeof entry === "string" && allowed.has(entry));
+    return keys.length > 0 ? keys : fallback;
+  } catch {
+    return fallback;
+  }
+}
+
+function writeStoredColumnKeys(prefsKey: string | undefined, keys: string[]) {
+  if (!prefsKey || typeof window === "undefined") {
+    return;
+  }
+  try {
+    window.localStorage.setItem(prefsKey, JSON.stringify(keys));
+  } catch {
+    /* ignore quota / private mode */
+  }
+}
+
 function compareColumnValues<T>(column: TableColumn<T>, left: T, right: T) {
   const leftRaw = column.display ? column.display(left) : column.value(left);
   const rightRaw = column.display ? column.display(right) : column.value(right);
@@ -88,6 +150,14 @@ function ResetIcon() {
   );
 }
 
+function ColumnsIcon() {
+  return (
+    <svg viewBox="0 0 20 20" aria-hidden="true">
+      <path d="M4 4.5h3.5v11H4zM8.25 4.5h3.5v11h-3.5zM12.5 4.5H16v11h-3.5z" fill="none" stroke="currentColor" strokeWidth="1.5" />
+    </svg>
+  );
+}
+
 function ChevronIcon({ open }: { open: boolean }) {
   return (
     <svg className={open ? "side-rail-chevron open" : "side-rail-chevron"} viewBox="0 0 20 20" aria-hidden="true">
@@ -105,6 +175,26 @@ function PreviewIcon() {
   );
 }
 
+function DownloadIcon() {
+  return (
+    <svg viewBox="0 0 20 20" aria-hidden="true">
+      <path d="M10 3.5v8.2" fill="none" stroke="currentColor" strokeWidth="1.8" strokeLinecap="round" />
+      <path d="M6.5 9.2 10 12.8l3.5-3.6" fill="none" stroke="currentColor" strokeWidth="1.8" strokeLinecap="round" strokeLinejoin="round" />
+      <path d="M4 15.5h12" fill="none" stroke="currentColor" strokeWidth="1.8" strokeLinecap="round" />
+    </svg>
+  );
+}
+
+function MoreIcon() {
+  return (
+    <svg viewBox="0 0 20 20" aria-hidden="true">
+      <circle cx="4.5" cy="10" r="1.5" fill="currentColor" />
+      <circle cx="10" cy="10" r="1.5" fill="currentColor" />
+      <circle cx="15.5" cy="10" r="1.5" fill="currentColor" />
+    </svg>
+  );
+}
+
 function DetailList({ lines }: { lines: DetailLine[] }) {
   return (
     <dl className="record-detail-list">
@@ -132,6 +222,14 @@ export function RecordWorkspace<T>({
   onDelete,
   canUpdate,
   canDelete,
+  onDownload,
+  canDownload = true,
+  downloadBusy = false,
+  showColumnPicker = true,
+  columnPrefsKey,
+  visibleColumnKeys,
+  defaultVisibleColumnKeys,
+  onVisibleColumnKeysChange,
   toolbar,
   form,
 }: {
@@ -148,25 +246,104 @@ export function RecordWorkspace<T>({
   onDelete?: (item: T) => void;
   canUpdate?: (item: T) => boolean;
   canDelete?: (item: T) => boolean;
+  /**
+   * When set, shows CSV / Excel / JSON download controls.
+   * Second argument lists currently visible columns (exportKey ?? key).
+   */
+  onDownload?: (format: ExportDownloadFormat, columns: ExportColumnRef[]) => void;
+  canDownload?: boolean;
+  downloadBusy?: boolean;
+  /** Column checklist in the side rail. Default true. */
+  showColumnPicker?: boolean;
+  /** Persist visible column keys in localStorage under this key. */
+  columnPrefsKey?: string;
+  /** Controlled visible column keys. */
+  visibleColumnKeys?: string[];
+  /** Uncontrolled initial visible keys (defaults to columns with defaultVisible !== false). */
+  defaultVisibleColumnKeys?: string[];
+  onVisibleColumnKeysChange?: (keys: string[]) => void;
   toolbar?: ReactNode;
   /** Slot for Add/Update/View dialogs owned by the host app. */
   form?: ReactNode;
 }) {
-  const filterableColumns = columns.filter((column) => column.filterable !== false);
+  const allowedKeys = useMemo(() => new Set(columns.map((column) => column.key)), [columns]);
+  const fallbackKeys = useMemo(
+    () => defaultVisibleColumnKeys ?? defaultVisibleKeys(columns),
+    [columns, defaultVisibleColumnKeys],
+  );
+  const isControlled = visibleColumnKeys !== undefined;
+  const [internalVisibleKeys, setInternalVisibleKeys] = useState<string[]>(() =>
+    readStoredColumnKeys(columnPrefsKey, fallbackKeys, allowedKeys),
+  );
   const [filters, setFilters] = useState<Record<string, string>>({});
   const [sort, setSort] = useState<SortState | null>(null);
   const [sideOpen, setSideOpen] = useState(false);
+  const [downloadOpen, setDownloadOpen] = useState(false);
+  const [columnsOpen, setColumnsOpen] = useState(false);
   const [previewEnabled, setPreviewEnabled] = useState(false);
   const [previewKey, setPreviewKey] = useState<string | number | null>(null);
   const [tooltip, setTooltip] = useState<TooltipState | null>(null);
   const [pageSize, setPageSize] = useState("15");
   const [page, setPage] = useState(1);
+  const [actionsMenuKey, setActionsMenuKey] = useState<string | number | null>(null);
+  const actionsMenuRef = useRef<HTMLDivElement | null>(null);
   const isClient = useIsClient();
 
+  useEffect(() => {
+    if (isControlled) {
+      return;
+    }
+    setInternalVisibleKeys(readStoredColumnKeys(columnPrefsKey, fallbackKeys, allowedKeys));
+  }, [allowedKeys, columnPrefsKey, fallbackKeys, isControlled]);
+
+  const resolvedVisibleKeys = useMemo(() => {
+    const source = isControlled ? visibleColumnKeys! : internalVisibleKeys;
+    const filtered = source.filter((key) => allowedKeys.has(key));
+    return filtered.length > 0 ? filtered : fallbackKeys.filter((key) => allowedKeys.has(key));
+  }, [allowedKeys, fallbackKeys, internalVisibleKeys, isControlled, visibleColumnKeys]);
+
+  const visibleColumns = useMemo(() => {
+    const byKey = new Map(columns.map((column) => [column.key, column]));
+    return resolvedVisibleKeys.map((key) => byKey.get(key)).filter((column): column is TableColumn<T> => Boolean(column));
+  }, [columns, resolvedVisibleKeys]);
+
+  function setVisibleKeys(next: string[]) {
+    const unique = Array.from(new Set(next.filter((key) => allowedKeys.has(key))));
+    const safe = unique.length > 0 ? unique : fallbackKeys.filter((key) => allowedKeys.has(key));
+    if (!isControlled) {
+      setInternalVisibleKeys(safe);
+      writeStoredColumnKeys(columnPrefsKey, safe);
+    }
+    onVisibleColumnKeysChange?.(safe);
+  }
+
+  function toggleColumnVisible(key: string, checked: boolean) {
+    if (checked) {
+      if (resolvedVisibleKeys.includes(key)) {
+        return;
+      }
+      setVisibleKeys([...resolvedVisibleKeys, key]);
+      return;
+    }
+    if (resolvedVisibleKeys.length <= 1) {
+      return;
+    }
+    setVisibleKeys(resolvedVisibleKeys.filter((entry) => entry !== key));
+  }
+
+  function selectAllColumns() {
+    setVisibleKeys(columns.map((column) => column.key));
+  }
+
+  function resetColumns() {
+    setVisibleKeys(fallbackKeys);
+  }
+
+  const filterableColumns = visibleColumns.filter((column) => column.filterable !== false);
+
   const filtered = useMemo(() => {
-    const activeFilters = columns.filter((column) => column.filterable !== false);
     return items.filter((item) =>
-      activeFilters.every((column) => {
+      filterableColumns.every((column) => {
         const query = (filters[column.key] ?? "").trim();
         if (!query) {
           return true;
@@ -179,25 +356,26 @@ export function RecordWorkspace<T>({
         return text.toLowerCase().includes(query.toLowerCase());
       }),
     );
-  }, [items, filters, columns]);
+  }, [items, filters, filterableColumns]);
 
   const sorted = useMemo(() => {
     if (!sort) {
       return filtered;
     }
-    const column = columns.find((entry) => entry.key === sort.key);
+    const column = visibleColumns.find((entry) => entry.key === sort.key);
     if (!column || column.sortable === false) {
       return filtered;
     }
     const direction = sort.direction === "asc" ? 1 : -1;
     return [...filtered].sort((left, right) => compareColumnValues(column, left, right) * direction);
-  }, [filtered, sort, columns]);
+  }, [filtered, sort, visibleColumns]);
 
   const activeFilterCount = useMemo(
     () => filterableColumns.reduce((count, column) => count + ((filters[column.key] ?? "").trim() ? 1 : 0), 0),
     [filterableColumns, filters],
   );
 
+  const hiddenColumnCount = columns.length - visibleColumns.length;
   const showAll = pageSize === "all";
   const numericPageSize = showAll ? Math.max(sorted.length, 1) : Number(pageSize);
   const pageCount = showAll ? 1 : Math.max(1, Math.ceil(sorted.length / numericPageSize));
@@ -205,8 +383,37 @@ export function RecordWorkspace<T>({
   const start = showAll ? 0 : (currentPage - 1) * numericPageSize;
   const pageItems = showAll ? sorted : sorted.slice(start, start + numericPageSize);
   const showAdd = canAdd && Boolean(onAdd);
+  const showDownload = Boolean(onDownload) && canDownload;
   const showFilters = filterableColumns.length > 0;
+  const showColumns = showColumnPicker && columns.length > 0;
   const previewItem = previewKey === null ? null : sorted.find((item) => rowKey(item) === previewKey) ?? null;
+  const exportColumns: ExportColumnRef[] = visibleColumns.map((column) => ({
+    key: column.exportKey ?? column.key,
+    header: column.header,
+  }));
+
+  useEffect(() => {
+    if (actionsMenuKey === null) {
+      return;
+    }
+
+    function onPointerDown(event: globalThis.MouseEvent) {
+      if (actionsMenuRef.current && !actionsMenuRef.current.contains(event.target as Node)) {
+        setActionsMenuKey(null);
+      }
+    }
+
+    document.addEventListener("mousedown", onPointerDown);
+    return () => document.removeEventListener("mousedown", onPointerDown);
+  }, [actionsMenuKey]);
+
+  function requestDownload(format: ExportDownloadFormat) {
+    if (!onDownload || downloadBusy) {
+      return;
+    }
+    onDownload(format, exportColumns);
+    setDownloadOpen(false);
+  }
 
   function cellText(column: TableColumn<T>, item: T) {
     const raw = column.display ? column.display(item) : column.value(item);
@@ -214,13 +421,13 @@ export function RecordWorkspace<T>({
   }
 
   function detailLines(item: T): DetailLine[] {
-    return columns.map((column) => ({
+    return visibleColumns.map((column) => ({
       label: column.header,
       value: cellText(column, item),
     }));
   }
 
-  const previewTitle = previewItem && columns[0] ? cellText(columns[0], previewItem) : null;
+  const previewTitle = previewItem && visibleColumns[0] ? cellText(visibleColumns[0], previewItem) : null;
 
   function changeFilter(key: string, value: string) {
     setFilters((current) => ({ ...current, [key]: value }));
@@ -277,6 +484,108 @@ export function RecordWorkspace<T>({
         ? `1–${sorted.length} of ${sorted.length}`
         : `${start + 1}–${Math.min(start + numericPageSize, sorted.length)} of ${sorted.length}`;
 
+  function renderRowActions(item: T) {
+    const key = rowKey(item);
+    const updateAllowed = canUpdate ? canUpdate(item) : Boolean(onUpdate);
+    const deleteAllowed = canDelete ? canDelete(item) : Boolean(onDelete);
+    const hasActions = Boolean(onView || onUpdate || onDelete);
+    if (!hasActions) {
+      return null;
+    }
+
+    return (
+      <>
+        <div className="row-actions row-actions-desktop">
+          {onView ? (
+            <button type="button" className="ghost row-action" onClick={() => onView(item)}>
+              View
+            </button>
+          ) : null}
+          {onUpdate ? (
+            <button
+              type="button"
+              className="ghost row-action"
+              disabled={!updateAllowed}
+              title={updateAllowed ? "Update" : "Update is not available"}
+              onClick={() => onUpdate(item)}
+            >
+              Update
+            </button>
+          ) : null}
+          {onDelete ? (
+            <button
+              type="button"
+              className="ghost row-action danger"
+              disabled={!deleteAllowed}
+              title={deleteAllowed ? "Delete" : "Delete is not available"}
+              onClick={() => onDelete(item)}
+            >
+              Delete
+            </button>
+          ) : null}
+        </div>
+
+        <div className="row-actions row-actions-mobile" ref={actionsMenuKey === key ? actionsMenuRef : undefined}>
+          <button
+            type="button"
+            className="ghost row-action-menu-trigger"
+            aria-haspopup="menu"
+            aria-expanded={actionsMenuKey === key}
+            aria-label="Row actions"
+            onClick={() => setActionsMenuKey((current) => (current === key ? null : key))}
+          >
+            <MoreIcon />
+          </button>
+          {actionsMenuKey === key ? (
+            <div className="row-action-menu" role="menu">
+              {onView ? (
+                <button
+                  type="button"
+                  role="menuitem"
+                  className="ghost"
+                  onClick={() => {
+                    setActionsMenuKey(null);
+                    onView(item);
+                  }}
+                >
+                  View
+                </button>
+              ) : null}
+              {onUpdate ? (
+                <button
+                  type="button"
+                  role="menuitem"
+                  className="ghost"
+                  disabled={!updateAllowed}
+                  onClick={() => {
+                    setActionsMenuKey(null);
+                    onUpdate(item);
+                  }}
+                >
+                  Update
+                </button>
+              ) : null}
+              {onDelete ? (
+                <button
+                  type="button"
+                  role="menuitem"
+                  className="ghost danger"
+                  disabled={!deleteAllowed}
+                  onClick={() => {
+                    setActionsMenuKey(null);
+                    onDelete(item);
+                  }}
+                >
+                  Delete
+                </button>
+              ) : null}
+            </div>
+          ) : null}
+        </div>
+      </>
+    );
+  }
+
   return (
     <div className="list-workspace" aria-label={title}>
       <div
@@ -296,7 +605,7 @@ export function RecordWorkspace<T>({
               <table className="data-table">
                 <thead>
                   <tr>
-                    {columns.map((column) => {
+                    {visibleColumns.map((column) => {
                       const sortable = column.sortable !== false;
                       const active = sort?.key === column.key ? sort.direction : null;
                       return (
@@ -327,7 +636,7 @@ export function RecordWorkspace<T>({
                 <tbody>
                   {pageItems.length === 0 ? (
                     <tr>
-                      <td colSpan={columns.length + 1}>
+                      <td colSpan={visibleColumns.length + 1}>
                         <p className="hint table-empty">
                           {items.length === 0 ? empty : "No records match the current filters."}
                         </p>
@@ -336,8 +645,6 @@ export function RecordWorkspace<T>({
                   ) : (
                     pageItems.map((item) => {
                       const key = rowKey(item);
-                      const updateAllowed = canUpdate ? canUpdate(item) : Boolean(onUpdate);
-                      const deleteAllowed = canDelete ? canDelete(item) : Boolean(onDelete);
                       const selected = previewEnabled && previewKey === key;
                       return (
                         <tr
@@ -357,39 +664,11 @@ export function RecordWorkspace<T>({
                           onMouseLeave={() => setTooltip(null)}
                           onClick={() => focusRecord(item)}
                         >
-                          {columns.map((column) => (
+                          {visibleColumns.map((column) => (
                             <td key={column.key}>{cellText(column, item)}</td>
                           ))}
                           <td className="actions-col" onClick={(event) => event.stopPropagation()}>
-                            <div className="row-actions">
-                              {onView ? (
-                                <button type="button" className="ghost row-action" onClick={() => onView(item)}>
-                                  View
-                                </button>
-                              ) : null}
-                              {onUpdate ? (
-                                <button
-                                  type="button"
-                                  className="ghost row-action"
-                                  disabled={!updateAllowed}
-                                  title={updateAllowed ? "Update" : "Update is not available"}
-                                  onClick={() => onUpdate(item)}
-                                >
-                                  Update
-                                </button>
-                              ) : null}
-                              {onDelete ? (
-                                <button
-                                  type="button"
-                                  className="ghost row-action danger"
-                                  disabled={!deleteAllowed}
-                                  title={deleteAllowed ? "Delete" : "Delete is not available"}
-                                  onClick={() => onDelete(item)}
-                                >
-                                  Delete
-                                </button>
-                              ) : null}
-                            </div>
+                            {renderRowActions(item)}
                           </td>
                         </tr>
                       );
@@ -463,6 +742,79 @@ export function RecordWorkspace<T>({
                 </button>
               ) : null}
 
+              {showColumns ? (
+                <div className="side-rail-columns">
+                  <button
+                    type="button"
+                    className="ghost side-rail-columns-toggle"
+                    aria-expanded={columnsOpen}
+                    onClick={() => setColumnsOpen((open) => !open)}
+                  >
+                    <ColumnsIcon />
+                    <span>Columns{hiddenColumnCount > 0 ? ` (${visibleColumns.length}/${columns.length})` : ""}</span>
+                  </button>
+                  {columnsOpen ? (
+                    <div className="side-rail-columns-panel" role="group" aria-label="Visible columns">
+                      <div className="side-rail-columns-actions">
+                        <button type="button" className="ghost" onClick={selectAllColumns}>
+                          Select all
+                        </button>
+                        <button type="button" className="ghost" onClick={resetColumns}>
+                          Reset
+                        </button>
+                      </div>
+                      <div className="side-rail-columns-list">
+                        {columns.map((column) => {
+                          const checked = resolvedVisibleKeys.includes(column.key);
+                          const disableUncheck = checked && resolvedVisibleKeys.length <= 1;
+                          return (
+                            <label key={column.key} className="side-rail-column-option">
+                              <input
+                                type="checkbox"
+                                checked={checked}
+                                disabled={disableUncheck}
+                                onChange={(event) => toggleColumnVisible(column.key, event.target.checked)}
+                              />
+                              <span>{column.header}</span>
+                            </label>
+                          );
+                        })}
+                      </div>
+                    </div>
+                  ) : null}
+                </div>
+              ) : null}
+
+              {showDownload ? (
+                <div className="side-rail-download">
+                  <button
+                    type="button"
+                    className="ghost side-rail-download-toggle"
+                    aria-expanded={downloadOpen}
+                    disabled={downloadBusy}
+                    onClick={() => setDownloadOpen((open) => !open)}
+                  >
+                    <DownloadIcon />
+                    <span>{downloadBusy ? "Downloading…" : "Download"}</span>
+                  </button>
+                  {downloadOpen ? (
+                    <div className="side-rail-download-formats" role="group" aria-label="Download format">
+                      {EXPORT_FORMAT_OPTIONS.map((option) => (
+                        <button
+                          key={option.format}
+                          type="button"
+                          className="ghost side-rail-download-format"
+                          disabled={downloadBusy}
+                          onClick={() => requestDownload(option.format)}
+                        >
+                          {option.label}
+                        </button>
+                      ))}
+                    </div>
+                  ) : null}
+                </div>
+              ) : null}
+
               {showFilters ? (
                 <div className="side-rail-filters">
                   <div className="filter-panel-head">
@@ -519,6 +871,37 @@ export function RecordWorkspace<T>({
                   <PlusIcon />
                 </button>
               ) : null}
+              {showColumns ? (
+                <button
+                  type="button"
+                  className="ghost side-rail-icon"
+                  title="Columns"
+                  aria-label="Columns"
+                  onClick={() => {
+                    setSideOpen(true);
+                    setColumnsOpen(true);
+                  }}
+                >
+                  <ColumnsIcon />
+                  {hiddenColumnCount > 0 ? <span className="filter-badge">{hiddenColumnCount}</span> : null}
+                </button>
+              ) : null}
+              {showDownload ? (
+                <button
+                  type="button"
+                  className="ghost side-rail-icon"
+                  title="Download"
+                  aria-label="Download"
+                  aria-expanded={downloadOpen}
+                  disabled={downloadBusy}
+                  onClick={() => {
+                    setSideOpen(true);
+                    setDownloadOpen(true);
+                  }}
+                >
+                  <DownloadIcon />
+                </button>
+              ) : null}
               {showFilters ? (
                 <button
                   type="button"

package/src/patterns/index.ts

@@ -1,2 +1,8 @@
-export { AppShell, type AppShellProps } from "./AppShell";
-export { RecordWorkspace, RecordTable, type TableColumn } from "./RecordWorkspace";
+export { AppShell, type AppShellProps, type MobileNavMode } from "./AppShell";
+export {
+  RecordWorkspace,
+  RecordTable,
+  type TableColumn,
+  type ExportDownloadFormat,
+  type ExportColumnRef,
+} from "./RecordWorkspace";

package/src/primitives/SideNav.tsx

@@ -12,14 +12,16 @@ export function SideNav({
   activeId,
   onSelect,
   label = "Sections",
+  className = "",
 }: {
   items: SideNavItem[];
   activeId: string;
   onSelect: (id: string) => void;
   label?: string;
+  className?: string;
 }) {
   return (
-    <nav className="side-nav" aria-label={label}>
+    <nav className={["side-nav", className].filter(Boolean).join(" ")} aria-label={label}>
       {items.map((item) => (
         <button
           key={item.id}