@strato-admin/cloudscape 0.1.0

package/src/button/SaveButton.tsx

@@ -0,0 +1,19 @@
+
+import { useTranslate } from '@strato-admin/core';
+import { Button, ButtonProps } from './Button';
+
+export interface SaveButtonProps extends Omit<ButtonProps, 'children'> {
+  label?: string;
+}
+
+export const SaveButton = ({ label, variant = 'primary', ...props }: SaveButtonProps) => {
+  const translate = useTranslate();
+
+  return (
+    <Button variant={variant} formAction="submit" nativeButtonAttributes={{ type: 'submit' }} {...props}>
+      {label || translate('ra.action.save', { _: 'Save' })}
+    </Button>
+  );
+};
+
+export default SaveButton;

package/src/button/index.ts

@@ -0,0 +1,5 @@
+export * from './Button';
+export * from './EditButton';
+export * from './BulkDeleteButton';
+export * from './SaveButton';
+export * from './CreateButton';

package/src/collection-hooks/index.ts

@@ -0,0 +1,2 @@
+export * from './useCollection';
+export * from './interfaces';

package/src/collection-hooks/interfaces.ts

@@ -0,0 +1,80 @@
+// shim for dom types
+interface CustomEventLike<T> {
+  detail: T;
+}
+
+export interface TableColumnDisplay {
+  id: string;
+  visible: boolean;
+}
+
+export interface CollectionPreferences {
+  pageSize?: number;
+  wrapLines?: boolean;
+  stripedRows?: boolean;
+  visibleContent?: ReadonlyArray<string>;
+  contentDisplay?: ReadonlyArray<TableColumnDisplay>;
+  contentDensity?: 'comfortable' | 'compact';
+}
+
+export interface UseCollectionOptions<_T> {
+  filtering?: any;
+  pagination?: any;
+  sorting?: any;
+  preferences?: {
+    pageSizeOptions?: ReadonlyArray<{ value: number; label?: string }>;
+    visibleContentOptions?: ReadonlyArray<{
+      id: string;
+      label: string;
+      editable?: boolean;
+    }>;
+    contentDisplayOptions?: ReadonlyArray<{
+      id: string;
+      label: string;
+      alwaysVisible?: boolean;
+    }>;
+    wrapLines?: boolean;
+    stripedRows?: boolean;
+    visibleContent?: ReadonlyArray<string>;
+    contentDisplay?: ReadonlyArray<TableColumnDisplay>;
+  };
+}
+
+export interface UseCollectionResult<T> {
+  items: ReadonlyArray<T> | undefined;
+  collectionProps: {
+    selectedItems: T[];
+    onSelectionChange(event: CustomEventLike<{ selectedItems: T[] }>): void;
+    trackBy: string | ((item: T) => string);
+    sortingColumn?: { sortingField?: string };
+    sortingDescending?: boolean;
+    onSortingChange?(
+      event: CustomEventLike<{ sortingColumn: { sortingField?: string }; isDescending?: boolean }>,
+    ): void;
+  };
+  paginationProps: {
+    disabled?: boolean;
+    currentPageIndex: number;
+    pagesCount: number;
+    onChange(event: CustomEventLike<{ currentPageIndex: number }>): void;
+  };
+  filterProps: {
+    filteringText: string;
+    onChange(event: CustomEventLike<{ filteringText: string }>): void;
+  };
+  preferencesProps: {
+    preferences: CollectionPreferences;
+    onConfirm(event: CustomEventLike<CollectionPreferences>): void;
+    pageSizeOptions?: ReadonlyArray<{ value: number; label?: string }>;
+    visibleContentOptions?: ReadonlyArray<{
+      id: string;
+      label: string;
+      editable?: boolean;
+    }>;
+    contentDisplayOptions?: ReadonlyArray<{
+      id: string;
+      label: string;
+      alwaysVisible?: boolean;
+    }>;
+  };
+}

package/src/collection-hooks/useCollection.test.ts

@@ -0,0 +1,413 @@
+import { renderHook, act } from '@testing-library/react';
+import { vi, describe, it, expect } from 'vitest';
+import { useListContext } from '@strato-admin/core';
+import { useCollection } from './useCollection';
+
+vi.mock('@strato-admin/core', () => ({
+  useListContext: vi.fn(),
+}));
+
+describe('useCollection', () => {
+  it('should return collection items and pagination props', () => {
+    const mockSetPage = vi.fn();
+    const mockData = [{ id: 1, name: 'Item 1' }];
+
+    (useListContext as any).mockReturnValue({
+      data: mockData,
+      page: 1,
+      isPending: false,
+      isFetching: false,
+      isLoading: false,
+      setPage: mockSetPage,
+      selectedIds: [],
+      onSelect: vi.fn(),
+    });
+
+    const { result } = renderHook(() => useCollection({}));
+
+    expect(result.current.items).toEqual(mockData);
+    expect(result.current.paginationProps.currentPageIndex).toBe(1);
+    expect(result.current.paginationProps.disabled).toBe(false);
+  });
+
+  it('should call setPage with the correct page index when onChange is called', () => {
+    const mockSetPage = vi.fn();
+
+    (useListContext as any).mockReturnValue({
+      data: [],
+      page: 1,
+      isPending: false,
+      isFetching: false,
+      isLoading: false,
+      setPage: mockSetPage,
+      selectedIds: [],
+      onSelect: vi.fn(),
+    });
+
+    const { result } = renderHook(() => useCollection({}));
+
+    act(() => {
+      result.current.paginationProps.onChange({ detail: { currentPageIndex: 2 } });
+    });
+
+    expect(mockSetPage).toHaveBeenCalledWith(2); // React Admin and Cloudscape both use 1-based indexing
+  });
+
+  it('should return selected items based on selectedIds', () => {
+    const mockData = [
+      { id: 1, name: 'Item 1' },
+      { id: 2, name: 'Item 2' },
+      { id: 3, name: 'Item 3' },
+    ];
+    const mockSelectedIds = [1, 3];
+
+    (useListContext as any).mockReturnValue({
+      data: mockData,
+      page: 1,
+      isPending: false,
+      isFetching: false,
+      isLoading: false,
+      setPage: vi.fn(),
+      selectedIds: mockSelectedIds,
+      onSelect: vi.fn(),
+    });
+
+    const { result } = renderHook(() => useCollection({}));
+
+    expect(result.current.collectionProps.selectedItems).toEqual([
+      { id: 1, name: 'Item 1' },
+      { id: 3, name: 'Item 3' },
+    ]);
+  });
+
+  it('should include dummy objects for selectedIds not in current data', () => {
+    const mockData = [{ id: 1, name: 'Item 1' }];
+    const mockSelectedIds = [1, 2];
+
+    (useListContext as any).mockReturnValue({
+      data: mockData,
+      page: 1,
+      isPending: false,
+      isFetching: false,
+      isLoading: false,
+      setPage: vi.fn(),
+      selectedIds: mockSelectedIds,
+      onSelect: vi.fn(),
+    });
+
+    const { result } = renderHook(() => useCollection({}));
+
+    expect(result.current.collectionProps.selectedItems).toEqual([{ id: 1, name: 'Item 1' }, { id: 2 }]);
+  });
+
+  it('should call onSelect when onSelectionChange is called', () => {
+    const mockOnSelect = vi.fn();
+    const mockData = [
+      { id: 1, name: 'Item 1' },
+      { id: 2, name: 'Item 2' },
+    ];
+
+    (useListContext as any).mockReturnValue({
+      data: mockData,
+      page: 1,
+      isPending: false,
+      isFetching: false,
+      isLoading: false,
+      setPage: vi.fn(),
+      selectedIds: [],
+      onSelect: mockOnSelect,
+    });
+
+    const { result } = renderHook(() => useCollection({}));
+
+    act(() => {
+      result.current.collectionProps.onSelectionChange({
+        detail: {
+          selectedItems: [{ id: 2, name: 'Item 2' }],
+        },
+      });
+    });
+
+    expect(mockOnSelect).toHaveBeenCalledWith([2]);
+  });
+
+  it('should return sorting props from sort object', () => {
+    (useListContext as any).mockReturnValue({
+      data: [],
+      sort: { field: 'name', order: 'DESC' },
+      setSort: vi.fn(),
+      page: 1,
+      isPending: false,
+      isFetching: false,
+      isLoading: false,
+      setPage: vi.fn(),
+      selectedIds: [],
+      onSelect: vi.fn(),
+    });
+
+    const { result } = renderHook(() => useCollection({}));
+
+    expect(result.current.collectionProps.sortingColumn).toEqual({ sortingField: 'name' });
+    expect(result.current.collectionProps.sortingDescending).toBe(true);
+  });
+
+  it('should call setSort when onSortingChange is called', () => {
+    const mockSetSort = vi.fn();
+    (useListContext as any).mockReturnValue({
+      data: [],
+      sort: { field: 'name', order: 'ASC' },
+      setSort: mockSetSort,
+      page: 1,
+      isPending: false,
+      isFetching: false,
+      isLoading: false,
+      setPage: vi.fn(),
+      selectedIds: [],
+      onSelect: vi.fn(),
+    });
+
+    const { result } = renderHook(() => useCollection({}));
+
+    act(() => {
+      result.current.collectionProps.onSortingChange!({
+        detail: {
+          sortingColumn: { sortingField: 'price' },
+          isDescending: true,
+        },
+      });
+    });
+
+    expect(mockSetSort).toHaveBeenCalledWith({ field: 'price', order: 'DESC' });
+  });
+
+  it('should disable pagination if loading, fetching, or pending', () => {
+    (useListContext as any).mockReturnValue({
+      data: [],
+      page: 1,
+      isPending: true,
+      isFetching: false,
+      isLoading: false,
+      setPage: vi.fn(),
+      selectedIds: [],
+      onSelect: vi.fn(),
+    });
+
+    const { result } = renderHook(() => useCollection({}));
+    expect(result.current.paginationProps.disabled).toBe(true);
+  });
+
+  it('should return filteringText from filterValues.q', () => {
+    (useListContext as any).mockReturnValue({
+      data: [],
+      page: 1,
+      isPending: false,
+      isFetching: false,
+      isLoading: false,
+      setPage: vi.fn(),
+      selectedIds: [],
+      onSelect: vi.fn(),
+      filterValues: { q: 'search term', status: 'active' },
+      setFilters: vi.fn(),
+    });
+
+    const { result } = renderHook(() => useCollection({}));
+
+    expect(result.current.filterProps.filteringText).toBe('search term');
+  });
+
+  it('should call setFilters with updated q value when filter onChange is called', () => {
+    const mockSetFilters = vi.fn();
+    (useListContext as any).mockReturnValue({
+      data: [],
+      page: 1,
+      isPending: false,
+      isFetching: false,
+      isLoading: false,
+      setPage: vi.fn(),
+      selectedIds: [],
+      onSelect: vi.fn(),
+      filterValues: { status: 'active' },
+      setFilters: mockSetFilters,
+    });
+
+    const { result } = renderHook(() => useCollection({}));
+
+    act(() => {
+      result.current.filterProps.onChange({
+        detail: { filteringText: 'new search' },
+      });
+    });
+
+    expect(mockSetFilters).toHaveBeenCalledWith({ status: 'active', q: 'new search' });
+  });
+
+  it('should return preferencesProps with pageSize from perPage', () => {
+    (useListContext as any).mockReturnValue({
+      data: [],
+      perPage: 50,
+      setPerPage: vi.fn(),
+      page: 1,
+      isPending: false,
+      isFetching: false,
+      isLoading: false,
+      setPage: vi.fn(),
+      selectedIds: [],
+      onSelect: vi.fn(),
+    });
+
+    const { result } = renderHook(() => useCollection({}));
+
+    expect(result.current.preferencesProps.preferences.pageSize).toBe(50);
+  });
+
+  it('should call setPerPage when preferences onConfirm is called with new pageSize', () => {
+    const mockSetPerPage = vi.fn();
+    (useListContext as any).mockReturnValue({
+      data: [],
+      perPage: 25,
+      setPerPage: mockSetPerPage,
+      page: 1,
+      isPending: false,
+      isFetching: false,
+      isLoading: false,
+      setPage: vi.fn(),
+      selectedIds: [],
+      onSelect: vi.fn(),
+    });
+
+    const { result } = renderHook(() => useCollection({}));
+
+    act(() => {
+      result.current.preferencesProps.onConfirm({
+        detail: { pageSize: 50 },
+      });
+    });
+
+    expect(mockSetPerPage).toHaveBeenCalledWith(50);
+  });
+
+  it('should not call setPerPage if pageSize is unchanged', () => {
+    const mockSetPerPage = vi.fn();
+    (useListContext as any).mockReturnValue({
+      data: [],
+      perPage: 25,
+      setPerPage: mockSetPerPage,
+      page: 1,
+      isPending: false,
+      isFetching: false,
+      isLoading: false,
+      setPage: vi.fn(),
+      selectedIds: [],
+      onSelect: vi.fn(),
+    });
+
+    const { result } = renderHook(() => useCollection({}));
+
+    act(() => {
+      result.current.preferencesProps.onConfirm({
+        detail: { pageSize: 25 },
+      });
+    });
+
+    expect(mockSetPerPage).not.toHaveBeenCalled();
+  });
+
+  it('should initialize visibleContent from visibleContentOptions if provided', () => {
+    (useListContext as any).mockReturnValue({
+      data: [],
+      perPage: 25,
+      setPerPage: vi.fn(),
+      page: 1,
+      isPending: false,
+      isFetching: false,
+      isLoading: false,
+      setPage: vi.fn(),
+      selectedIds: [],
+      onSelect: vi.fn(),
+    });
+
+    const visibleContentOptions = [
+      { id: 'id', label: 'ID' },
+      { id: 'name', label: 'Name' },
+    ];
+    const { result } = renderHook(() =>
+      useCollection({
+        preferences: {
+          visibleContentOptions,
+        },
+      }),
+    );
+
+    expect(result.current.preferencesProps.preferences.visibleContent).toEqual(['id', 'name']);
+  });
+
+  it('should initialize visibleContent and contentDisplay from preferences if provided', () => {
+    (useListContext as any).mockReturnValue({
+      data: [],
+      perPage: 25,
+      setPerPage: vi.fn(),
+      page: 1,
+      isPending: false,
+      isFetching: false,
+      isLoading: false,
+      setPage: vi.fn(),
+      selectedIds: [],
+      onSelect: vi.fn(),
+    });
+
+    const visibleContent = ['id', 'name'];
+    const contentDisplay = [
+      { id: 'id', visible: true },
+      { id: 'name', visible: true },
+      { id: 'price', visible: false },
+    ];
+
+    const { result } = renderHook(() =>
+      useCollection({
+        preferences: {
+          visibleContent,
+          contentDisplay,
+        },
+      }),
+    );
+
+    expect(result.current.preferencesProps.preferences.visibleContent).toEqual(visibleContent);
+    expect(result.current.preferencesProps.preferences.contentDisplay).toEqual(contentDisplay);
+  });
+
+  it('should update wrapLines and stripedRows when preferences onConfirm is called', () => {
+    (useListContext as any).mockReturnValue({
+      data: [],
+      perPage: 25,
+      setPerPage: vi.fn(),
+      page: 1,
+      isPending: false,
+      isFetching: false,
+      isLoading: false,
+      setPage: vi.fn(),
+      selectedIds: [],
+      onSelect: vi.fn(),
+    });
+
+    const { result } = renderHook(() =>
+      useCollection({
+        preferences: {
+          wrapLines: false,
+          stripedRows: false,
+        },
+      }),
+    );
+
+    expect(result.current.preferencesProps.preferences.wrapLines).toBe(false);
+    expect(result.current.preferencesProps.preferences.stripedRows).toBe(false);
+
+    act(() => {
+      result.current.preferencesProps.onConfirm({
+        detail: { wrapLines: true, stripedRows: true },
+      });
+    });
+
+    expect(result.current.preferencesProps.preferences.wrapLines).toBe(true);
+    expect(result.current.preferencesProps.preferences.stripedRows).toBe(true);
+  });
+});

package/src/collection-hooks/useCollection.ts

@@ -0,0 +1,125 @@
+import { useState, useMemo } from 'react';
+import { useListContext, RaRecord } from '@strato-admin/core';
+import { UseCollectionOptions, UseCollectionResult, TableColumnDisplay } from './interfaces';
+
+export function useCollection<T extends RaRecord>(options: UseCollectionOptions<T>): UseCollectionResult<T> {
+  const {
+    data, // Array of the list records, e.g. [{ id: 123, title: 'hello world' }, { ... }
+    total, // Total number of results for the current filters, excluding pagination. Useful to build the pagination controls, e.g. 23
+    isPending, // Boolean, true until the data is available
+    isFetching, // Boolean, true while the data is being fetched, false once the data is fetched
+    isLoading, // Boolean, true until the data is fetched for the first time
+    // Pagination
+    page, // Current page. Starts at 1
+    perPage, // Number of results per page. Defaults to 25
+    setPage, // Callback to change the page, e.g. setPage(3)
+    setPerPage, // Callback to change the number of results per page, e.g. setPerPage(50)
+    // Selection
+    selectedIds, // Array of the selected record IDs
+    onSelect, // Callback to change the selection, e.g. onSelect([123, 456])
+    // Sorting
+    sort, // Current sort. E.g. { field: 'id', order: 'ASC' }
+    setSort, // Callback to change the sort. E.g. setSort({ field: 'id', order: 'ASC' })
+    // Filtering
+    filterValues,
+    setFilters,
+  } = useListContext<T>();
+
+  const [wrapLines, setWrapLines] = useState(options.preferences?.wrapLines);
+  const [stripedRows, setStripedRows] = useState(options.preferences?.stripedRows);
+  const [visibleContent, setVisibleContent] = useState<ReadonlyArray<string> | undefined>(
+    options.preferences?.visibleContent ?? options.preferences?.visibleContentOptions?.map((o) => o.id),
+  );
+  const [contentDisplay, setContentDisplay] = useState<ReadonlyArray<TableColumnDisplay> | undefined>(
+    options.preferences?.contentDisplay ?? options.preferences?.contentDisplayOptions?.map((o) => ({ id: o.id, visible: true })),
+  );
+
+  useMemo(() => {
+    setVisibleContent(
+      options.preferences?.visibleContent ?? options.preferences?.visibleContentOptions?.map((o) => o.id),
+    );
+    setContentDisplay(
+      options.preferences?.contentDisplay ?? options.preferences?.contentDisplayOptions?.map((o) => ({ id: o.id, visible: true })),
+    );
+  }, [options.preferences?.visibleContent, options.preferences?.visibleContentOptions, options.preferences?.contentDisplay, options.preferences?.contentDisplayOptions]);
+
+  const selectedItems = (selectedIds || []).map((id) => {
+    const item = data?.find((i) => i.id === id);
+    if (item) return item;
+    return { id } as T;
+  });
+
+  const items = useMemo(() => {
+    // If it's a client-side list (data contains all records), we need to slice it for pagination.
+    // We detect this by checking if data.length equals total and if data.length is greater than perPage.
+    if (data && total === data.length && data.length > (perPage || 0)) {
+      const p = page || 1;
+      const pp = perPage || 25;
+      return data.slice((p - 1) * pp, p * pp);
+    }
+    return data;
+  }, [data, total, page, perPage]);
+
+  return {
+    items,
+    collectionProps: {
+      selectedItems,
+      onSelectionChange: (event) => onSelect(event.detail.selectedItems.map((item) => item.id)),
+      trackBy: 'id',
+      sortingColumn: sort ? { sortingField: sort.field } : undefined,
+      sortingDescending: sort?.order === 'DESC',
+      onSortingChange: (event) => {
+        const { sortingColumn, isDescending } = event.detail;
+        if (sortingColumn?.sortingField) {
+          setSort({ field: sortingColumn.sortingField, order: isDescending ? 'DESC' : 'ASC' });
+        }
+      },
+    },
+    paginationProps: {
+      disabled: isPending || isFetching || isLoading,
+      currentPageIndex: page,
+      pagesCount: total !== undefined && perPage ? Math.ceil(total / perPage) : 1,
+      onChange: (event) => setPage(event.detail.currentPageIndex),
+    },
+    filterProps: {
+      filteringText: filterValues?.q || '',
+      onChange: (event) => {
+        setFilters({ ...filterValues, q: event.detail.filteringText });
+      },
+    },
+    preferencesProps: {
+      preferences: {
+        pageSize: perPage,
+        wrapLines,
+        stripedRows,
+        visibleContent,
+        contentDisplay,
+      },
+      onConfirm: (event) => {
+        const {
+          pageSize,
+          wrapLines: newWrapLines,
+          stripedRows: newStripedRows,
+          visibleContent: newVisibleContent,
+          contentDisplay: newContentDisplay,
+        } = event.detail;
+        if (pageSize !== undefined && pageSize !== perPage) {
+          setPerPage(pageSize);
+        }
+        if (newWrapLines !== undefined) {
+          setWrapLines(newWrapLines);
+        }
+        if (newStripedRows !== undefined) {
+          setStripedRows(newStripedRows);
+        }
+        if (newVisibleContent !== undefined) {
+          setVisibleContent(newVisibleContent);
+        }
+        if (newContentDisplay !== undefined) {
+          setContentDisplay(newContentDisplay);
+        }
+      },
+      ...options.preferences,
+    },
+  };
+}