@scalepad/ui 0.1.0

package/src/components/Table/SortableColumnHeader.tsx

@@ -0,0 +1,99 @@
+import { ChevronDown, ChevronsUpDown, ChevronUp } from 'lucide-react';
+
+import { Group, UnstyledButton } from '@mantine/core';
+
+import { Text } from '../Typography';
+
+export interface SortableColumnHeaderProps {
+  /**
+   * Column label text
+   */
+  label: string;
+  /**
+   * Props to spread on the header (from useTableSort.getSortProps)
+   */
+  sortProps: {
+    onClick: () => void;
+    'aria-sort': 'ascending' | 'descending' | 'none';
+  };
+  /**
+   * Text alignment
+   * @default 'left'
+   */
+  align?: 'left' | 'right' | 'center';
+}
+
+/**
+ * Reusable sortable column header component
+ *
+ * Displays a column label with a sort indicator icon that changes based on sort state:
+ * - No sort: ChevronsUpDown (dimmed)
+ * - Ascending: ChevronUp
+ * - Descending: ChevronDown
+ *
+ * Uses a semantic button element for full keyboard and screen reader accessibility.
+ * The button responds to Enter/Space key presses and announces sort state via aria-sort.
+ *
+ * @example
+ * ```tsx
+ * const sort = useTableSort({ ... });
+ *
+ * <Table.Th>
+ *   <SortableColumnHeader
+ *     label="Name"
+ *     sortProps={sort.getSortProps('name')}
+ *   />
+ * </Table.Th>
+ *
+ * <Table.Th>
+ *   <SortableColumnHeader
+ *     label="Count"
+ *     sortProps={sort.getSortProps('count')}
+ *     align="right"
+ *   />
+ * </Table.Th>
+ * ```
+ */
+export function SortableColumnHeader({
+  label,
+  sortProps,
+  align = 'left',
+}: SortableColumnHeaderProps) {
+  const { onClick, 'aria-sort': ariaSort } = sortProps;
+
+  // Determine which icon to show based on sort state
+  const SortIcon =
+    ariaSort === 'ascending'
+      ? ChevronUp
+      : ariaSort === 'descending'
+        ? ChevronDown
+        : ChevronsUpDown;
+
+  // Dim the icon when no sort is applied
+  const iconOpacity = ariaSort === 'none' ? 0.5 : 1;
+
+  // Determine justification based on alignment
+  const justifyContent =
+    align === 'right'
+      ? 'flex-end'
+      : align === 'center'
+        ? 'center'
+        : 'flex-start';
+
+  return (
+    <UnstyledButton
+      onClick={onClick}
+      aria-sort={ariaSort}
+      aria-label={`Sort by ${label}`}
+      style={{
+        width: '100%',
+        userSelect: 'none',
+      }}
+    >
+      <Group gap="4px" justify={justifyContent} wrap="nowrap">
+        <Text variant="caption2.stronger">{label}</Text>
+        <SortIcon size={16} opacity={iconOpacity} aria-hidden="true" />
+      </Group>
+    </UnstyledButton>
+  );
+}

package/src/components/Table/TableSkeletonRows.figma.tsx

@@ -0,0 +1,22 @@
+import figma from '@figma/code-connect';
+
+import { TableSkeletonRows } from './TableSkeletonRows';
+
+/**
+ * -- This file was auto-generated by Code Connect --
+ * None of your props could be automatically mapped to Figma properties.
+ * You should update the `props` object to include a mapping from your
+ * code props to Figma properties, and update the `example` function to
+ * return the code example you'd like to see in Figma
+ */
+
+figma.connect(
+  TableSkeletonRows,
+  'https://www.figma.com/design/VCLfybgU3OaUUPrQdBaVmP/LM-Design-System?node-id=303%3A246698',
+  {
+    props: {},
+    example: _props => (
+      <TableSkeletonRows columns={[{ width: 160 }, { width: 80 }]} rowCount={3} />
+    ),
+  }
+);

package/src/components/Table/TableSkeletonRows.tsx

@@ -0,0 +1,113 @@
+import { Flex, Skeleton, Table } from '@mantine/core';
+
+export interface SkeletonColumnConfig {
+  /**
+   * Skeleton width (number in px or string like '100%')
+   */
+  width: number | string;
+  /**
+   * Skeleton height in px (defaults to 16)
+   */
+  height?: number;
+  /**
+   * Whether this is a circular skeleton (e.g., for avatars)
+   */
+  circle?: boolean;
+  /**
+   * Alignment - adds marginLeft: auto for 'right', auto margins for 'center'
+   */
+  align?: 'left' | 'right' | 'center';
+  /**
+   * Border radius for pill-shaped skeletons (e.g., badges)
+   */
+  radius?: 'xl' | 'lg' | 'md' | 'sm' | 'xs';
+  /**
+   * Whether this is a flex cell with multiple items (e.g., avatar + name)
+   */
+  flex?: boolean;
+  /**
+   * Gap between flex items (only used when flex=true)
+   */
+  gap?: 'xs' | 'sm' | 'md' | 'lg';
+  /**
+   * Cell padding override (use Mantine spacing tokens)
+   */
+  px?: number | string;
+}
+
+export interface TableSkeletonRowsProps {
+  /**
+   * Column configuration for skeleton cells
+   */
+  columns: SkeletonColumnConfig[];
+  /**
+   * Number of rows to render
+   */
+  rowCount: number;
+}
+
+/**
+ * TableSkeletonRows component
+ * Renders skeleton loading rows for tables with configurable column layouts
+ *
+ * @example
+ * ```tsx
+ * const columns = [
+ *   { width: 120, flex: true, circle: true }, // Avatar + name
+ *   { width: 60, align: 'right' },            // Number column
+ *   { width: 70, radius: 'xl', align: 'right' }, // Badge column
+ * ];
+ *
+ * <Table.Tbody>
+ *   {loading ? (
+ *     <TableSkeletonRows columns={columns} rowCount={5} />
+ *   ) : (
+ *     data.map(row => <Table.Tr key={row.id}>...</Table.Tr>)
+ *   )}
+ * </Table.Tbody>
+ * ```
+ */
+export function TableSkeletonRows({
+  columns,
+  rowCount,
+}: TableSkeletonRowsProps) {
+  // Helper to determine margin style based on alignment
+  const getAlignmentStyle = (align?: 'left' | 'right' | 'center') => {
+    if (!align || align === 'left') return undefined;
+    if (align === 'right') return { marginLeft: 'auto' };
+    if (align === 'center') return { marginLeft: 'auto', marginRight: 'auto' };
+    return undefined;
+  };
+
+  return (
+    <>
+      {Array.from({ length: rowCount }).map((_, rowIndex) => (
+        <Table.Tr key={`skeleton-row-${rowIndex}`}>
+          {columns.map((col, colIndex) => (
+            <Table.Td key={`skeleton-cell-${rowIndex}-${colIndex}`} px={col.px}>
+              {col.flex ? (
+                // Flex cell with multiple items (e.g., avatar + name)
+                <Flex gap={col.gap ?? 'xs'} align="center">
+                  {col.circle && <Skeleton circle height={26} width={26} />}
+                  <Skeleton
+                    height={col.height ?? 16}
+                    width={col.width}
+                    radius={col.radius}
+                  />
+                </Flex>
+              ) : (
+                // Single skeleton cell
+                <Skeleton
+                  height={col.height ?? 16}
+                  width={col.width}
+                  radius={col.radius}
+                  style={getAlignmentStyle(col.align)}
+                />
+              )}
+            </Table.Td>
+          ))}
+        </Table.Tr>
+      ))}
+    </>
+  );
+}

package/src/components/Table/index.ts

@@ -0,0 +1,9 @@
+export {
+  SortableColumnHeader,
+  type SortableColumnHeaderProps,
+} from './SortableColumnHeader';
+export {
+  TableSkeletonRows,
+  type TableSkeletonRowsProps,
+  type SkeletonColumnConfig,
+} from './TableSkeletonRows';

package/src/components/TableActionsMenu.tsx

@@ -0,0 +1,58 @@
+import type { ReactNode } from 'react';
+
+import { MoreVertical } from 'lucide-react';
+
+import { IconButton } from './IconButton';
+import { Menu } from './Menu';
+
+export interface TableActionsMenuProps {
+  /**
+   * Menu items to display in the dropdown
+   */
+  children: ReactNode;
+  /**
+   * Aria label for the action button
+   * @default "Row actions"
+   */
+  ariaLabel?: string;
+}
+
+/**
+ * Reusable action menu for table rows with three-dot icon
+ *
+ * Handles all the boilerplate for rendering a consistent action menu:
+ * - Three-dot icon button
+ * - Menu dropdown with proper positioning
+ * - Consistent styling and accessibility
+ *
+ * @example
+ * ```tsx
+ * createActionsColumn<UserData>({
+ *   cell: ({ row }) => (
+ *     <TableActionsMenu>
+ *       <Menu.Item onClick={() => handleEdit(row.original)}>
+ *         Edit
+ *       </Menu.Item>
+ *       <Menu.Item onClick={() => handleDelete(row.original)}>
+ *         Delete
+ *       </Menu.Item>
+ *     </TableActionsMenu>
+ *   ),
+ * })
+ * ```
+ */
+export function TableActionsMenu({
+  children,
+  ariaLabel = 'Row actions',
+}: TableActionsMenuProps) {
+  return (
+    <Menu position="bottom-end" withArrow>
+      <Menu.Target>
+        <IconButton variant="ghost" color="gray" aria-label={ariaLabel}>
+          <MoreVertical size={16} />
+        </IconButton>
+      </Menu.Target>
+      <Menu.Dropdown miw={260}>{children}</Menu.Dropdown>
+    </Menu>
+  );
+}

package/src/components/TableCard.tsx

@@ -0,0 +1,29 @@
+import type { ReactNode } from 'react';
+
+import { Paper, type PaperProps } from '@mantine/core';
+
+export interface TableCardProps extends PaperProps {
+  children: ReactNode;
+  /**
+   * Whether to show a border around the table card
+   * @default true
+   */
+  withBorder?: boolean;
+}
+
+/**
+ * TableCard Component
+ * Wraps tables with a consistent card-style background and border.
+ * Use this as the default wrapper for all Table components.
+ */
+export function TableCard({
+  children,
+  withBorder = true,
+  ...props
+}: TableCardProps) {
+  return (
+    <Paper withBorder={withBorder} radius="lg" shadow="0" p={0} {...props}>
+      {children}
+    </Paper>
+  );
+}

package/src/components/TableContainer/TableContainer.tsx

@@ -0,0 +1,86 @@
+import type { ReactNode } from 'react';
+
+import { Box, Flex, Paper } from '@mantine/core';
+
+export interface TableContainerProps {
+  /**
+   * The controls section (search, filters, buttons, etc.)
+   */
+  controls?: ReactNode;
+  /**
+   * Optional filters bar (e.g., applied filter badges)
+   * Appears between controls and children
+   */
+  filtersBar?: ReactNode;
+  /**
+   * Optional action bar (e.g., bulk actions when items are selected)
+   */
+  actionBar?: ReactNode;
+  /**
+   * The table or empty state content
+   */
+  children: ReactNode;
+  /**
+   * Whether to show a border around the table container
+   * @default false
+   */
+  withBorder?: boolean;
+  /**
+   * When true, hides controls and filters bar (e.g. during initial load)
+   * @default false
+   */
+  isLoading?: boolean;
+}
+
+/**
+ * TableContainer Component
+ *
+ * A reusable container for tables with controls, optional filters bar, and optional action bar.
+ * Wraps table controls, filters bar, action bar, and the table itself in a bordered Paper container.
+ *
+ * @example
+ * ```tsx
+ * <TableContainer
+ *   controls={
+ *     <Flex justify="space-between" align="center" gap="md" wrap="wrap">
+ *       <TextInput placeholder="Search..." />
+ *       <Button>Export</Button>
+ *     </Flex>
+ *   }
+ *   filtersBar={
+ *     <AppliedFiltersManagerBar
+ *       filterCategories={filters}
+ *       onClearAll={clearFilters}
+ *     />
+ *   }
+ *   actionBar={
+ *     <BulkActionBar
+ *       selectedCount={3}
+ *       onDelete={handleDelete}
+ *       onClose={handleClose}
+ *     />
+ *   }
+ * >
+ *   <MyTable data={data} withBorder={false} />
+ * </TableContainer>
+ * ```
+ */
+export function TableContainer({
+  controls,
+  filtersBar,
+  actionBar,
+  children,
+  withBorder = true,
+  isLoading = false,
+}: TableContainerProps) {
+  return (
+    <Paper radius="lg" p={0} py="md" withBorder={withBorder}>
+      <Flex direction="column" gap="lg">
+        {!isLoading && <Box px="md">{controls}</Box>}
+        {!isLoading && filtersBar && <Box px="md">{filtersBar}</Box>}
+        {children}
+        {actionBar}
+      </Flex>
+    </Paper>
+  );
+}

package/src/components/TableContainer/index.ts

@@ -0,0 +1,2 @@
+export { TableContainer } from './TableContainer';
+export type { TableContainerProps } from './TableContainer';

package/src/components/TableControlBar/TableControlBar.tsx

@@ -0,0 +1,156 @@
+import type { ReactNode } from 'react';
+
+import { CloudDownload } from 'lucide-react';
+
+import { Flex } from '@mantine/core';
+
+import { IconButton } from '../IconButton';
+import { SearchTextInput } from '../TextInput';
+import { TableSelectionButton } from './TableSelectionButton';
+
+export interface TableControlBarProps {
+  /**
+   * Placeholder text for the search input
+   */
+  searchPlaceholder: string;
+
+  /**
+   * Current search value
+   */
+  searchValue: string;
+
+  /**
+   * Callback when search value changes
+   */
+  onSearchChange: (value: string) => void;
+
+  /**
+   * Optional key to force reset/remount of search input
+   * Change this value to clear the search input state
+   */
+  searchKey?: string | number;
+
+  /**
+   * Whether selection mode is active
+   */
+  isSelectionMode: boolean;
+
+  /**
+   * Entity name for the selection button (e.g., "Apps", "Devices", "Users")
+   */
+  entityName: string;
+
+  /**
+   * Callback to toggle selection mode
+   */
+  onToggleSelection: () => void;
+
+  /**
+   * Optional custom filter controls to display between search and selection button
+   */
+  customFilters?: ReactNode;
+
+  /**
+   * Optional custom actions to display on the right side instead of default Download CSV button
+   */
+  rightActions?: ReactNode;
+
+  /**
+   * Whether to show the Download CSV button
+   * @default true
+   */
+  showDownloadButton?: boolean;
+
+  /**
+   * Optional callback when Download CSV button is clicked
+   */
+  onDownloadCSV?: () => void;
+
+  /**
+   * Whether to show the selection button
+   * @default true
+   */
+  canSelectItems?: boolean;
+
+  /**
+   * Whether right-side action controls are disabled (selection button and download CSV).
+   * Search input and custom filters remain enabled to allow filtering/searching.
+   * @default false
+   */
+  disabled?: boolean;
+}
+
+/**
+ * Main container component for standardized table controls
+ *
+ * Displays search, filters, selection button, and action buttons in a consistent layout
+ *
+ * @example
+ * ```tsx
+ * <TableControlBar
+ *   searchPlaceholder="Search by Name"
+ *   searchValue={searchQuery}
+ *   onSearchChange={setSearchQuery}
+ *   isSelectionMode={selection.isSelectionMode}
+ *   entityName="Devices"
+ *   onToggleSelection={selection.toggleSelectionMode}
+ *   customFilters={<FilterButton />}
+ *   rightActions={<ExportButton />}
+ * />
+ * ```
+ */
+export function TableControlBar({
+  searchPlaceholder,
+  searchValue,
+  onSearchChange,
+  searchKey,
+  isSelectionMode,
+  entityName,
+  onToggleSelection,
+  customFilters,
+  rightActions,
+  showDownloadButton = true,
+  onDownloadCSV,
+  canSelectItems = true,
+  disabled = false,
+}: TableControlBarProps) {
+  return (
+    <Flex justify="space-between" align="center" gap="md" wrap="wrap">
+      {/* Left side: Search and filters - always enabled to allow filtering/searching */}
+      <Flex gap="sm" align="center">
+        <SearchTextInput
+          key={searchKey}
+          placeholder={searchPlaceholder}
+          value={searchValue}
+          onChange={e => onSearchChange(e.currentTarget.value)}
+          debounceMs={300}
+          w="320px"
+        />
+        {customFilters}
+      </Flex>
+
+      {/* Right side: Selection button and actions - disabled when no data */}
+      <Flex gap="sm" align="center">
+        {canSelectItems && (
+          <TableSelectionButton
+            isSelectionMode={isSelectionMode}
+            entityName={entityName}
+            onClick={onToggleSelection}
+            disabled={disabled}
+          />
+        )}
+        {rightActions ||
+          (showDownloadButton && (
+            <IconButton
+              variant="outline"
+              size="sm"
+              onClick={onDownloadCSV}
+              disabled={disabled}
+            >
+              <CloudDownload size={16} />
+            </IconButton>
+          ))}
+      </Flex>
+    </Flex>
+  );
+}

package/src/components/TableControlBar/TableSelectionButton.tsx

@@ -0,0 +1,57 @@
+import { CheckCheck, X } from 'lucide-react';
+
+import { Button } from '../Button';
+
+export interface TableSelectionButtonProps {
+  /**
+   * Whether selection mode is active
+   */
+  isSelectionMode: boolean;
+
+  /**
+   * Entity name for the button label (e.g., "Apps", "Devices", "Users")
+   */
+  entityName: string;
+
+  /**
+   * Callback when button is clicked to toggle selection mode
+   */
+  onClick: () => void;
+
+  /**
+   * Whether the button is disabled
+   * @default false
+   */
+  disabled?: boolean;
+}
+
+/**
+ * Standardized selection toggle button for tables
+ *
+ * @example
+ * ```tsx
+ * <TableSelectionButton
+ *   isSelectionMode={selection.isSelectionMode}
+ *   entityName="Devices"
+ *   onClick={selection.toggleSelectionMode}
+ * />
+ * ```
+ */
+export function TableSelectionButton({
+  isSelectionMode,
+  entityName,
+  onClick,
+  disabled = false,
+}: TableSelectionButtonProps) {
+  return (
+    <Button
+      variant={isSelectionMode ? 'primary' : 'outline'}
+      leftSection={isSelectionMode ? <X size={16} /> : <CheckCheck size={16} />}
+      size="sm"
+      onClick={onClick}
+      disabled={disabled}
+    >
+      {isSelectionMode ? 'Cancel Selection' : `Select ${entityName}`}
+    </Button>
+  );
+}

package/src/components/TableControlBar/index.ts

@@ -0,0 +1,13 @@
+// Components
+export { TableControlBar, type TableControlBarProps } from './TableControlBar';
+export {
+  TableSelectionButton,
+  type TableSelectionButtonProps,
+} from './TableSelectionButton';
+
+// Hook
+export {
+  useTableControlBar,
+  type UseTableControlBarProps,
+  type UseTableControlBarReturn,
+} from './useTableControlBar';