Merge pull request #2115 from epam/feature/new-ds-docs

[Docs]: added docs for new props in dataSources.

app/src/docs/_examples/dataSources/DataSourcePropsPatch.example.tsx

@@ -0,0 +1,66 @@
+import React, { useMemo, useState } from 'react';
+import { DataSourceViewer } from '@epam/uui-docs';
+import { DataSourceState, ItemsMap, ItemsMapParams, useArrayDataSource } from '@epam/uui-core';
+
+interface Item {
+    id: string;
+    name: string;
+    parentId?: string;
+}
+
+const items: Item[] = [
+    { id: '1', name: 'Parent 1' },
+    { id: '1.1', name: 'Child 1.1', parentId: '1' },
+    { id: '1.2', name: 'Child 1.2', parentId: '1' },
+
+    { id: '2', name: 'Parent 2' },
+    { id: '2.1', name: 'Child 2.1', parentId: '2' },
+    { id: '2.2', name: 'Child 2.2', parentId: '2' },
+
+    { id: '3', name: 'Parent 3' },
+    { id: '3.2', name: 'Child 3.2', parentId: '3' },
+    { id: '3.1', name: 'Child 3.1', parentId: '3' },
+];
+
+const params: ItemsMapParams<Item, string> = { getId: (item) => item.id };
+
+export default function DataSourcePropsPatchExample() {
+    const patch1 = useMemo(() => ItemsMap.fromObject<string, Item>(
+        { 4: { id: '4', name: 'Parent 4' } },
+        params,
+    ), []);
+
+    const patch2 = useMemo(() => ItemsMap.fromObject<string, Item>(
+        { 1: { id: '1', name: 'Parent 1 with new name' } },
+        params,
+    ), []);
+
+    const [value1, onValueChange1] = useState<DataSourceState>({});
+    const dataSource1 = useArrayDataSource({
+        items,
+        patch: patch1,
+    }, []);
+
+    const [value2, onValueChange2] = useState<DataSourceState>({});
+    const dataSource2 = useArrayDataSource({
+        items,
+        patch: patch2,
+    }, []);
+
+    return (
+        <>
+            <DataSourceViewer
+                exampleTitle="Add new element to the list"
+                value={ value1 }
+                onValueChange={ onValueChange1 }
+                dataSource={ dataSource1 }
+            />
+            <DataSourceViewer
+                exampleTitle="Update existing element"
+                value={ value2 }
+                onValueChange={ onValueChange2 }
+                dataSource={ dataSource2 }
+            />
+        </>
+    );
+}

app/src/docs/_examples/dataSources/DataSourcePropsPatchFixItemBetweenSortings.example.tsx

@@ -0,0 +1,103 @@
+import React, { useState } from 'react';
+import { DataSourceState, IImmutableMap, ItemsMap, SortingOption, useArrayDataSource, useForm } from '@epam/uui-core';
+import { DataSourceTableViewer, sortableDataSourceColumns } from '@epam/uui-docs';
+
+interface Item {
+    id: string;
+    name: string;
+    parentId?: string;
+}
+
+interface FormState {
+    items: IImmutableMap<string, Item>;
+}
+
+const items: Record<string, Item> = {
+    1: { id: '1', name: 'Parent 1' },
+    1.1: { id: '1.1', name: 'Child 1.1', parentId: '1' },
+    1.2: { id: '1.2', name: 'Child 1.2', parentId: '1' },
+
+    2: { id: '2', name: 'Parent 2' },
+    2.1: { id: '2.1', name: 'Child 2.1', parentId: '2' },
+    2.2: { id: '2.2', name: 'Child 2.2', parentId: '2' },
+
+    3: { id: '3', name: 'Parent 3' },
+    3.2: { id: '3.2', name: 'Child 3.2', parentId: '3' },
+    3.1: { id: '3.1', name: 'Child 3.1', parentId: '3' },
+};
+
+const itemsMap = ItemsMap.fromObject<string, Item>(items, { getId: ({ id }) => id });
+
+const defaultSorting: SortingOption<Item>[] = [{ field: 'name', direction: 'asc' }];
+
+export default function DataSourcePropsPatchFixItemBetweenSortingsExample() {
+    const { lens: lens1, value: formValue1 } = useForm<FormState>({
+        value: { items: itemsMap },
+        onSave: () => Promise.resolve(),
+    });
+
+    const { lens: lens2, value: formValue2 } = useForm<FormState>({
+        value: { items: itemsMap },
+        onSave: () => Promise.resolve(),
+    });
+
+    const { lens: lens3, value: formValue3 } = useForm<FormState>({
+        value: { items: itemsMap },
+        onSave: () => Promise.resolve(),
+    });
+
+    const [value1, onValueChange1] = useState<DataSourceState<any, string>>({ sorting: defaultSorting });
+    const dataSource1 = useArrayDataSource({
+        items: Object.values(items),
+        patch: formValue1.items,
+        getRowOptions: (item) => ({
+            ...lens1.prop('items').key(item.id).toProps(),
+        }),
+    }, []);
+
+    const [value2, onValueChange2] = useState<DataSourceState<any, string>>({ sorting: defaultSorting });
+    const dataSource2 = useArrayDataSource({
+        items: Object.values(items),
+        patch: formValue2.items,
+        getRowOptions: (item) => ({
+            ...lens2.prop('items').key(item.id).toProps(),
+        }),
+        fixItemBetweenSortings: true,
+    }, []);
+
+    const [value3, onValueChange3] = useState<DataSourceState<any, string>>({ sorting: defaultSorting });
+    const dataSource3 = useArrayDataSource({
+        items: Object.values(items),
+        patch: formValue3.items,
+        getRowOptions: (item) => ({
+            ...lens3.prop('items').key(item.id).toProps(),
+        }),
+        fixItemBetweenSortings: false,
+    }, []);
+
+    return (
+        <>
+            <DataSourceTableViewer
+                exampleTitle="With fixing rows between sortings by default"
+                value={ value1 }
+                onValueChange={ onValueChange1 }
+                dataSource={ dataSource1 }
+                columns={ sortableDataSourceColumns }
+            />
+            <DataSourceTableViewer
+                exampleTitle="With fixing rows between sortings"
+                value={ value2 }
+                onValueChange={ onValueChange2 }
+                dataSource={ dataSource2 }
+                columns={ sortableDataSourceColumns }
+            />
+            <DataSourceTableViewer
+                exampleTitle="Without fixing rows between sortings"
+                value={ value3 }
+                onValueChange={ onValueChange3 }
+                dataSource={ dataSource3 }
+                columns={ sortableDataSourceColumns }
+            />
+        </>
+    );
+}

app/src/docs/_examples/dataSources/DataSourcePropsPatchGetNewItemPosition.example.tsx

@@ -0,0 +1,78 @@
+import React, { useMemo, useState } from 'react';
+import { DataSourceViewer } from '@epam/uui-docs';
+import { DataSourceState, ItemsMap, ItemsMapParams, PatchOrdering, useArrayDataSource } from '@epam/uui-core';
+
+interface Item {
+    id: string;
+    name: string;
+    parentId?: string;
+}
+
+const items: Item[] = [
+    { id: '1', name: 'Parent 1' },
+    { id: '1.1', name: 'Child 1.1', parentId: '1' },
+    { id: '1.2', name: 'Child 1.2', parentId: '1' },
+
+    { id: '2', name: 'Parent 2' },
+    { id: '2.1', name: 'Child 2.1', parentId: '2' },
+    { id: '2.2', name: 'Child 2.2', parentId: '2' },
+
+    { id: '3', name: 'Parent 3' },
+    { id: '3.2', name: 'Child 3.2', parentId: '3' },
+    { id: '3.1', name: 'Child 3.1', parentId: '3' },
+];
+
+const params: ItemsMapParams<Item, string> = { getId: (item) => item.id };
+
+export default function DataSourcePropsPatchGetNewItemPositionExample() {
+    const patch = useMemo(() => ItemsMap.fromObject<string, Item>(
+        {
+            1: { id: '1', name: 'Parent 1 with new name' },
+            4: { id: '4', name: 'Parent 4' },
+        },
+        params,
+    ), []);
+
+    const [value1, onValueChange1] = useState<DataSourceState>({});
+    const dataSource1 = useArrayDataSource({
+        items,
+        patch,
+    }, []);
+
+    const [value2, onValueChange2] = useState<DataSourceState>({});
+    const dataSource2 = useArrayDataSource({
+        items,
+        patch,
+        getNewItemPosition: () => PatchOrdering.TOP,
+    }, []);
+
+    const [value3, onValueChange3] = useState<DataSourceState>({});
+    const dataSource3 = useArrayDataSource({
+        items,
+        patch,
+        getNewItemPosition: () => PatchOrdering.BOTTOM,
+    }, []);
+
+    return (
+        <>
+            <DataSourceViewer
+                exampleTitle="Adding items to the top by default"
+                value={ value1 }
+                onValueChange={ onValueChange1 }
+                dataSource={ dataSource1 }
+            />
+            <DataSourceViewer
+                exampleTitle="Adding items to the top"
+                value={ value2 }
+                onValueChange={ onValueChange2 }
+                dataSource={ dataSource2 }
+            />
+            <DataSourceViewer
+                exampleTitle="Adding items to the bottom"
+                value={ value3 }
+                onValueChange={ onValueChange3 }
+                dataSource={ dataSource3 }
+            />
+        </>
+    );
+}

app/src/docs/_examples/dataSources/DataSourcePropsPatchIsDeleted.example.tsx

@@ -0,0 +1,49 @@
+import React, { useMemo, useState } from 'react';
+import { DataSourceViewer } from '@epam/uui-docs';
+import { DataSourceState, ItemsMap, ItemsMapParams, useArrayDataSource } from '@epam/uui-core';
+
+interface Item {
+    id: string;
+    name: string;
+    parentId?: string;
+    isDeleted?: boolean;
+}
+
+const items: Item[] = [
+    { id: '1', name: 'Parent 1' },
+    { id: '1.1', name: 'Child 1.1', parentId: '1' },
+    { id: '1.2', name: 'Child 1.2', parentId: '1' },
+
+    { id: '2', name: 'Parent 2' },
+    { id: '2.1', name: 'Child 2.1', parentId: '2' },
+    { id: '2.2', name: 'Child 2.2', parentId: '2' },
+
+    { id: '3', name: 'Parent 3' },
+    { id: '3.2', name: 'Child 3.2', parentId: '3' },
+    { id: '3.1', name: 'Child 3.1', parentId: '3' },
+];
+
+const params: ItemsMapParams<Item, string> = { getId: (item) => item.id };
+
+export default function DataSourcePropsPatchIsDeletedExample() {
+    const patch = useMemo(() => ItemsMap.fromObject<string, Item>(
+        { 1: { id: '1', name: 'Parent 1', isDeleted: true } },
+        params,
+    ), []);
+
+    const [value, onValueChange] = useState<DataSourceState>({});
+    const dataSource = useArrayDataSource({
+        items,
+        patch,
+        isDeleted: (item) => item.isDeleted ?? false,
+    }, []);
+
+    return (
+        <DataSourceViewer
+            exampleTitle="Delete item from the list"
+            value={ value }
+            onValueChange={ onValueChange }
+            dataSource={ dataSource }
+        />
+    );
+}

app/src/docs/_examples/dataSources/DataSourcePropsShowSelectedOnly.example.tsx

@@ -0,0 +1,39 @@
+import React, { useState } from 'react';
+import { DataSourceViewer } from '@epam/uui-docs';
+import { DataSourceState, useArrayDataSource } from '@epam/uui-core';
+
+const items = [
+    { id: '1', name: 'Parent 1' },
+    { id: '1.1', name: 'Child 1.1', parentId: '1' },
+    { id: '1.2', name: 'Child 1.2', parentId: '1' },
+
+    { id: '2', name: 'Parent 2' },
+    { id: '2.1', name: 'Child 2.1', parentId: '2' },
+    { id: '2.2', name: 'Child 2.2', parentId: '2' },
+
+    { id: '3', name: 'Parent 3' },
+    { id: '3.2', name: 'Child 3.2', parentId: '3' },
+    { id: '3.1', name: 'Child 3.1', parentId: '3' },
+];
+
+export default function DataSourcePropsShowSelectedOnlyExample() {
+    const [showSelectedOnly, setShowSelectedOnly] = useState<boolean>(false);
+
+    const [value, onValueChange] = useState<DataSourceState>({ checked: ['1'] });
+    const dataSource = useArrayDataSource({
+        items,
+        rowOptions: { checkbox: { isVisible: true } },
+        showSelectedOnly,
+    }, []);
+
+    return (
+        <DataSourceViewer
+            exampleTitle={ showSelectedOnly ? 'Selected rows only.' : 'All rows.\nPress "Show only selected rows" to see selected ones.' }
+            value={ value }
+            onValueChange={ onValueChange }
+            dataSource={ dataSource }
+            showSelectedOnly={ showSelectedOnly }
+            onShowSelectedOnlyChange={ () => setShowSelectedOnly(!showSelectedOnly) }
+        />
+    );
+}

app/src/docs/dataSources/BaseDataSourceProps.doc.tsx

@@ -10,12 +10,17 @@ export class DataSourcesBaseDataSourcePropsDoc extends BaseDocsBlock {
                 <EditableDocContent fileName="dataSources-base-props" />
 
                 <EditableDocContent title="Common DataSource Props" fileName="dataSources-base-props-overview" />
-                
+
                 <DocExample title="getId and getParentId" path="./_examples/dataSources/DataSourcePropsIds.example.tsx" />
                 <DocExample title="complexIds" path="./_examples/dataSources/DataSourcePropsComplexIds.example.tsx" />
                 <DocExample title="isFoldedByDefault" path="./_examples/dataSources/DataSourcePropsIsFoldedByDefault.example.tsx" />
                 <DocExample title="cascadeSelection" path="./_examples/dataSources/DataSourcePropsCascadeSelection.example.tsx" />
                 <DocExample title="selectAll" path="./_examples/dataSources/DataSourcePropsSelectAll.example.tsx" />
+                <DocExample title="showSelectedOnly" path="./_examples/dataSources/DataSourcePropsShowSelectedOnly.example.tsx" />
+                <DocExample title="patch" path="./_examples/dataSources/DataSourcePropsPatch.example.tsx" />
+                <DocExample title="isDeleted" path="./_examples/dataSources/DataSourcePropsPatchIsDeleted.example.tsx" />
+                <DocExample title="getNewItemPosition" path="./_examples/dataSources/DataSourcePropsPatchGetNewItemPosition.example.tsx" />
+                <DocExample title="fixItemBetweenSortings" path="./_examples/dataSources/DataSourcePropsPatchFixItemBetweenSortings.example.tsx" />
             </>
         );
     }