@wix/patterns 1.477.0 → 1.479.0

package/dist/templates/cms-collection-entity/ItemsApp.tsx

@@ -0,0 +1,28 @@
+import React from 'react';
+import { withDashboard } from '@wix/patterns';
+import { WixPatternsProvider } from '@wix/patterns/provider';
+import { PatternsReactRoute, PatternsReactRouter } from '@wix/patterns/router';
+import { ItemsCollectionPage } from './ItemsCollectionPage';
+import { ItemEntityPage } from './ItemEntityPage';
+
+export const ItemsApp = withDashboard(() => (
+  <WixPatternsProvider>
+    <PatternsReactRouter>
+      <PatternsReactRoute
+        type="collection"
+        path="/"
+        element={<ItemsCollectionPage />}
+      />
+      <PatternsReactRoute
+        type="editEntity"
+        path="/:id"
+        element={<ItemEntityPage />}
+      />
+      <PatternsReactRoute
+        type="createEntity"
+        path="/new"
+        element={<ItemEntityPage />}
+      />
+    </PatternsReactRouter>
+  </WixPatternsProvider>
+));

package/dist/templates/cms-collection-entity/ItemsCollectionPage.tsx

@@ -0,0 +1,56 @@
+import React from 'react';
+import {
+  CollectionEmptyState,
+  CollectionErrorState,
+  CollectionNoResultsState,
+  PrimaryActions,
+} from '@wix/patterns';
+import { CollectionPage } from '@wix/patterns/page';
+import { usePatternsNavigate } from '@wix/patterns/router';
+// The schema entry's Table and hook, not the root ones: these take the source first.
+import { Table, useTableCollection } from '@wix/patterns/schema';
+import { useCmsSchemaSource } from '@wix/patterns-cms';
+import { COLLECTION_ID, type CmsItem } from './collection';
+
+export const ItemsCollectionPage = () => {
+  const { navigateToEntityPage } = usePatternsNavigate<CmsItem>();
+  const openNew = () => navigateToEntityPage({ path: '/new' });
+
+  // Each page builds its own source from the same collection id.
+  const source = useCmsSchemaSource<CmsItem>({ collectionId: COLLECTION_ID });
+
+  // The source supplies the fetch, the search, the item key and name, and one
+  // column per schema field.
+  const state = useTableCollection(source, { persistQueryToUrl: true });
+
+  return (
+    <CollectionPage>
+      <CollectionPage.Header
+        title={{ text: 'Items' }}
+        primaryAction={<PrimaryActions label="Add item" onClick={openNew} />}
+      />
+      <CollectionPage.Content>
+        <Table
+          state={state}
+          emptyState={
+            <CollectionEmptyState
+              title="No items yet"
+              addNewCta={{ text: 'Add item', onClick: openNew }}
+            />
+          }
+          noResultsState={<CollectionNoResultsState title="No items match" />}
+          errorState={(err, { retry }) => (
+            <CollectionErrorState
+              title="Couldn't load items"
+              subtitle={String(err)}
+              action={{ text: 'Retry', onClick: retry }}
+            />
+          )}
+          onRowClick={(item: CmsItem) =>
+            navigateToEntityPage({ path: `/${item._id}`, entity: item })
+          }
+        />
+      </CollectionPage.Content>
+    </CollectionPage>
+  );
+};

package/dist/templates/cms-collection-entity/collection.ts

@@ -0,0 +1,9 @@
+// The CMS collection both pages read. For a collection your app ships, this is
+// the full scoped id: your app namespace, a slash, and the collection's id suffix.
+export const COLLECTION_ID = 'your-app-namespace/items';
+
+// A CMS row always has an _id. Every other field comes from the schema, so none
+// is declared here.
+export interface CmsItem extends Record<string, unknown> {
+  _id: string;
+}

package/dist/templates/cms-collection-entity/page.tsx

@@ -0,0 +1,32 @@
+// The dashboard page's entry file. A Wix CLI app has to hand the page location
+// to the router itself: PatternsReactRouter reads it from the location prop of
+// withDashboard (in ItemsApp), and nothing else supplies it. Leaving it out
+// passes tsc and the build, and fails only when the page is opened.
+import React, { useEffect, useState } from 'react';
+import { dashboard } from '@wix/dashboard';
+import { WixDesignSystemProvider } from '@wix/design-system';
+import '@wix/design-system/styles.global.css';
+import { ItemsApp } from './ItemsApp';
+
+type PageLocation = Parameters<
+  Parameters<typeof dashboard.observeState>[0]
+>[1]['pageLocation'];
+
+const Page = () => {
+  const [location, setLocation] = useState<PageLocation | undefined>();
+
+  useEffect(() => {
+    const subscription = dashboard.observeState((_pageParams, environment) => {
+      setLocation(environment.pageLocation);
+    });
+    return () => subscription.disconnect();
+  }, []);
+
+  return (
+    <WixDesignSystemProvider>
+      {location ? <ItemsApp location={location} /> : null}
+    </WixDesignSystemProvider>
+  );
+};
+
+export default Page;

package/dist/templates/collection-detail/ItemDetailPage.tsx

@@ -0,0 +1,44 @@
+import React, { useEffect, useState } from 'react';
+import { useParams } from 'react-router-dom';
+import { Card, Loader, Page, Text } from '@wix/design-system';
+import { usePatternsNavigate } from '@wix/patterns/router';
+import { fetchItem, type Item } from './items-api';
+
+// An EntityPage has no read-only mode: fetch and onSave are required, and its
+// actions bar keeps a Save button. A display-only record opens a design-system
+// Page instead.
+export const ItemDetailPage = () => {
+  const { id } = useParams<{ id: string }>();
+  const { navigateToCollectionPage } = usePatternsNavigate();
+  const [item, setItem] = useState<Item | undefined>();
+
+  useEffect(() => {
+    if (id) {
+      fetchItem(id).then(setItem);
+    }
+  }, [id]);
+
+  return (
+    <Page>
+      {/* The way back is the header's back button: there is no Cancel. */}
+      <Page.Header
+        title={item?.name ?? 'Item'}
+        showBackButton
+        onBackClicked={() => navigateToCollectionPage({ path: '/' })}
+      />
+      <Page.Content>
+        {item ? (
+          <Card>
+            <Card.Header title="Details" />
+            <Card.Divider />
+            <Card.Content>
+              <Text>{item.name}</Text>
+            </Card.Content>
+          </Card>
+        ) : (
+          <Loader />
+        )}
+      </Page.Content>
+    </Page>
+  );
+};

package/dist/templates/collection-detail/ItemsApp.tsx

@@ -0,0 +1,26 @@
+import React from 'react';
+import { withDashboard } from '@wix/patterns';
+import { WixPatternsProvider } from '@wix/patterns/provider';
+import { PatternsReactRoute, PatternsReactRouter } from '@wix/patterns/router';
+import { ItemsCollectionPage } from './ItemsCollectionPage';
+import { ItemDetailPage } from './ItemDetailPage';
+
+// The detail route is an editEntity route even though nothing is edited: that
+// type wires the way back to the collection, and it stays the same if the page
+// later grows an edit form.
+export const ItemsApp = withDashboard(() => (
+  <WixPatternsProvider>
+    <PatternsReactRouter>
+      <PatternsReactRoute
+        type="collection"
+        path="/"
+        element={<ItemsCollectionPage />}
+      />
+      <PatternsReactRoute
+        type="editEntity"
+        path="/:id"
+        element={<ItemDetailPage />}
+      />
+    </PatternsReactRouter>
+  </WixPatternsProvider>
+));

package/dist/templates/collection-detail/ItemsCollectionPage.tsx

@@ -0,0 +1,111 @@
+import React from 'react';
+import {
+  CollectionEmptyState,
+  CollectionErrorState,
+  CollectionNoResultsState,
+  CollectionSearch,
+  CollectionToolbarFilters,
+  MultiSelectCheckboxFilter,
+  Table,
+  stringsArrayFilter,
+  useStaticListFilterCollection,
+  useTableCollection,
+} from '@wix/patterns';
+import { CollectionPage } from '@wix/patterns/page';
+import { usePatternsNavigate } from '@wix/patterns/router';
+import { fetchItemsPage, type Item, type ItemStatus } from './items-api';
+
+const STATUS_LABELS: Record<ItemStatus, string> = {
+  ACTIVE: 'Active',
+  ARCHIVED: 'Archived',
+};
+
+// Module level: one filter per page, not one per render. Its name is not the
+// visible title (that comes from the label props below); it feeds
+// accessibility legends, BI and data hooks.
+const statusFilter = stringsArrayFilter<ItemStatus>({
+  name: 'Status',
+  itemKey: (status) => status,
+  itemName: (status) => STATUS_LABELS[status] ?? status,
+});
+
+export const ItemsCollectionPage = () => {
+  const { navigateToEntityPage } = usePatternsNavigate<Item>();
+
+  const state = useTableCollection<Item, { status: typeof statusFilter }>({
+    queryName: 'items',
+    paginationMode: 'cursor',
+    itemKey: (item) => item.id,
+    itemName: (item) => item.name,
+    filters: { status: statusFilter },
+    // Every declared filter and the search term are read here. One that never
+    // reaches the query still renders, and narrows nothing.
+    fetchData: (query) =>
+      fetchItemsPage({
+        limit: query.limit,
+        cursor: query.cursor ?? undefined,
+        search: query.search,
+        filters: { status: query.filters.status },
+      }),
+    fetchErrorMessage: ({ err }) =>
+      err instanceof Error ? err.message : 'Failed to load items',
+  });
+
+  const statusOptions = useStaticListFilterCollection(statusFilter, [
+    'ACTIVE',
+    'ARCHIVED',
+  ]);
+
+  return (
+    <CollectionPage>
+      {/* Read-only: nothing to create, so no primary action. */}
+      <CollectionPage.Header title={{ text: 'Items' }} />
+      <CollectionPage.Content>
+        <Table
+          state={state}
+          // Search is on by default, so a table without this prop ships a box
+          // that reaches no query.
+          search={<CollectionSearch placeholder="Search items" />}
+          filters={
+            <CollectionToolbarFilters>
+              <MultiSelectCheckboxFilter
+                filter={statusFilter}
+                collection={statusOptions}
+                toolbarItemProps={{ label: 'Status' }}
+                accordionItemProps={{ label: 'Status' }}
+              />
+            </CollectionToolbarFilters>
+          }
+          emptyState={<CollectionEmptyState title="No items yet" />}
+          noResultsState={
+            <CollectionNoResultsState
+              title="No items match"
+              subtitle="Try another search or clear the filters."
+            />
+          }
+          // Without it a failed query looks like a slow one: skeletons, forever.
+          errorState={(err, { retry }) => (
+            <CollectionErrorState
+              title="Couldn't load items"
+              subtitle={String(err)}
+              action={{ text: 'Retry', onClick: retry }}
+            />
+          )}
+          // Rows open the read-only detail route. Passing the row lets it title
+          // itself before its fetch.
+          onRowClick={(item) =>
+            navigateToEntityPage({ path: `/${item.id}`, entity: item })
+          }
+          columns={[
+            { id: 'name', title: 'Name', render: (item) => item.name },
+            {
+              id: 'status',
+              title: 'Status',
+              render: (item) => STATUS_LABELS[item.status],
+            },
+          ]}
+        />
+      </CollectionPage.Content>
+    </CollectionPage>
+  );
+};

package/dist/templates/collection-detail/items-api.ts

@@ -0,0 +1,66 @@
+// Where the page's data comes from. Replace each function body with your own
+// calls (an SDK, a REST endpoint) and keep the signatures: the pages call only
+// these, so nothing else changes when the data source does.
+//
+// The in-memory list below exists only so the template runs as-is.
+
+export type ItemStatus = 'ACTIVE' | 'ARCHIVED';
+
+export interface Item {
+  id: string;
+  name: string;
+  status: ItemStatus;
+}
+
+export interface ItemsPageQuery {
+  limit: number;
+  cursor?: string;
+  search?: string;
+  filters: { status?: ItemStatus[] | null };
+}
+
+export interface ItemsPage {
+  items: Item[];
+  // Always present, and undefined on the last page: an empty string reads as
+  // "there is another page" and the table keeps asking for it.
+  cursor: string | undefined;
+}
+
+let items: Item[] = [
+  { id: '1', name: 'First item', status: 'ACTIVE' },
+  { id: '2', name: 'Second item', status: 'ARCHIVED' },
+];
+
+export async function fetchItemsPage(
+  query: ItemsPageQuery,
+): Promise<ItemsPage> {
+  const term = query.search?.trim().toLowerCase();
+  const statuses = query.filters.status;
+  const matching = items.filter(
+    (item) =>
+      (!term || item.name.toLowerCase().includes(term)) &&
+      (!statuses?.length || statuses.includes(item.status)),
+  );
+  const start = query.cursor ? Number(query.cursor) : 0;
+  const end = start + query.limit;
+  return {
+    items: matching.slice(start, end),
+    cursor: end < matching.length ? String(end) : undefined,
+  };
+}
+
+export async function fetchItem(id: string): Promise<Item | undefined> {
+  return items.find((item) => item.id === id);
+}
+
+export async function saveItem(
+  item: Partial<Item> & { name: string },
+): Promise<Item> {
+  const saved: Item = {
+    id: item.id ?? String(Date.now()),
+    status: item.status ?? 'ACTIVE',
+    name: item.name,
+  };
+  items = [...items.filter((existing) => existing.id !== saved.id), saved];
+  return saved;
+}

package/dist/templates/collection-detail/page.tsx

@@ -0,0 +1,32 @@
+// The dashboard page's entry file. A Wix CLI app has to hand the page location
+// to the router itself: PatternsReactRouter reads it from the location prop of
+// withDashboard (in ItemsApp), and nothing else supplies it. Leaving it out
+// passes tsc and the build, and fails only when the page is opened.
+import React, { useEffect, useState } from 'react';
+import { dashboard } from '@wix/dashboard';
+import { WixDesignSystemProvider } from '@wix/design-system';
+import '@wix/design-system/styles.global.css';
+import { ItemsApp } from './ItemsApp';
+
+type PageLocation = Parameters<
+  Parameters<typeof dashboard.observeState>[0]
+>[1]['pageLocation'];
+
+const Page = () => {
+  const [location, setLocation] = useState<PageLocation | undefined>();
+
+  useEffect(() => {
+    const subscription = dashboard.observeState((_pageParams, environment) => {
+      setLocation(environment.pageLocation);
+    });
+    return () => subscription.disconnect();
+  }, []);
+
+  return (
+    <WixDesignSystemProvider>
+      {location ? <ItemsApp location={location} /> : null}
+    </WixDesignSystemProvider>
+  );
+};
+
+export default Page;

package/dist/templates/collection-entity/ItemEntityPage.tsx

@@ -0,0 +1,73 @@
+import React from 'react';
+import { useParams } from 'react-router-dom';
+import { Card, FormField, Input } from '@wix/design-system';
+import { EntityPage, useEntityPage, useEntityPageContext } from '@wix/patterns';
+import { useController, useForm } from '@wix/patterns/form';
+import { fetchItem, saveItem, type Item } from './items-api';
+
+// The form's shape is yours, and need not match the saved type.
+type ItemFormFields = { name: string };
+
+// One component serves both /new and /:id.
+export const ItemEntityPage = () => {
+  const { id } = useParams<{ id?: string }>();
+  const form = useForm<ItemFormFields>();
+
+  const state = useEntityPage<Item, ItemFormFields>({
+    // The collection route, for the router's back navigation.
+    parentPath: '/',
+    // A getter: a successful create moves /new to /:id while the page stays mounted.
+    isNewEntity: () => !id,
+    form,
+    fetch: async () => ({ entity: id ? await fetchItem(id) : undefined }),
+    onSave: async () => ({
+      updatedEntity: await saveItem({ id, ...form.getValues() }),
+    }),
+    saveSuccessToast: 'Item saved',
+    saveErrorToast: () => 'Failed to save the item',
+  });
+
+  return (
+    <EntityPage state={state}>
+      <EntityPage.Header title={{ text: id ? 'Edit item' : 'New item' }} />
+      <EntityPage.Content>
+        <EntityPage.MainContent>
+          <Card>
+            <Card.Header title="Details" />
+            <Card.Divider />
+            <Card.Content>
+              <NameField />
+            </Card.Content>
+          </Card>
+        </EntityPage.MainContent>
+      </EntityPage.Content>
+    </EntityPage>
+  );
+};
+
+// One controller per field. It reads the page's form, and it renders inside
+// Card.Content, where the entity has loaded, so its default value is the saved one.
+const NameField = () => {
+  const page = useEntityPageContext<Item, ItemFormFields>();
+  const { field, fieldState } = useController({
+    name: 'name',
+    control: page.form.control,
+    defaultValue: page.entity?.name ?? '',
+    rules: { required: { value: true, message: 'A name is required' } },
+  });
+  return (
+    <FormField
+      label="Name"
+      required
+      status={fieldState.error ? 'error' : undefined}
+      statusMessage={fieldState.error?.message}
+    >
+      <Input
+        inputRef={field.ref}
+        value={field.value}
+        onChange={field.onChange}
+        onBlur={field.onBlur}
+      />
+    </FormField>
+  );
+};

package/dist/templates/collection-entity/ItemsApp.tsx

@@ -0,0 +1,30 @@
+import React from 'react';
+import { withDashboard } from '@wix/patterns';
+import { WixPatternsProvider } from '@wix/patterns/provider';
+import { PatternsReactRoute, PatternsReactRouter } from '@wix/patterns/router';
+import { ItemsCollectionPage } from './ItemsCollectionPage';
+import { ItemEntityPage } from './ItemEntityPage';
+
+// The provider is a parent of everything that reads the collection or the
+// router, never a sibling of it.
+export const ItemsApp = withDashboard(() => (
+  <WixPatternsProvider>
+    <PatternsReactRouter>
+      <PatternsReactRoute
+        type="collection"
+        path="/"
+        element={<ItemsCollectionPage />}
+      />
+      <PatternsReactRoute
+        type="editEntity"
+        path="/:id"
+        element={<ItemEntityPage />}
+      />
+      <PatternsReactRoute
+        type="createEntity"
+        path="/new"
+        element={<ItemEntityPage />}
+      />
+    </PatternsReactRouter>
+  </WixPatternsProvider>
+));

package/dist/templates/collection-entity/ItemsCollectionPage.tsx

@@ -0,0 +1,120 @@
+import React from 'react';
+import {
+  CollectionEmptyState,
+  CollectionErrorState,
+  CollectionNoResultsState,
+  CollectionSearch,
+  CollectionToolbarFilters,
+  MultiSelectCheckboxFilter,
+  PrimaryActions,
+  Table,
+  stringsArrayFilter,
+  useStaticListFilterCollection,
+  useTableCollection,
+} from '@wix/patterns';
+import { CollectionPage } from '@wix/patterns/page';
+import { usePatternsNavigate } from '@wix/patterns/router';
+import { fetchItemsPage, type Item, type ItemStatus } from './items-api';
+
+const STATUS_LABELS: Record<ItemStatus, string> = {
+  ACTIVE: 'Active',
+  ARCHIVED: 'Archived',
+};
+
+// Module level: one filter per page, not one per render. Its name is not the
+// visible title (that comes from the label props below); it feeds
+// accessibility legends, BI and data hooks.
+const statusFilter = stringsArrayFilter<ItemStatus>({
+  name: 'Status',
+  itemKey: (status) => status,
+  itemName: (status) => STATUS_LABELS[status] ?? status,
+});
+
+export const ItemsCollectionPage = () => {
+  const { navigateToEntityPage } = usePatternsNavigate<Item>();
+  // No record yet, so no entity is passed.
+  const openNew = () => navigateToEntityPage({ path: '/new' });
+
+  const state = useTableCollection<Item, { status: typeof statusFilter }>({
+    queryName: 'items',
+    paginationMode: 'cursor',
+    itemKey: (item) => item.id,
+    itemName: (item) => item.name,
+    filters: { status: statusFilter },
+    // Every declared filter and the search term are read here. One that never
+    // reaches the query still renders, and narrows nothing.
+    fetchData: (query) =>
+      fetchItemsPage({
+        limit: query.limit,
+        cursor: query.cursor ?? undefined,
+        search: query.search,
+        filters: { status: query.filters.status },
+      }),
+    fetchErrorMessage: ({ err }) =>
+      err instanceof Error ? err.message : 'Failed to load items',
+  });
+
+  const statusOptions = useStaticListFilterCollection(statusFilter, [
+    'ACTIVE',
+    'ARCHIVED',
+  ]);
+
+  return (
+    <CollectionPage>
+      <CollectionPage.Header
+        title={{ text: 'Items' }}
+        primaryAction={<PrimaryActions label="Add item" onClick={openNew} />}
+      />
+      <CollectionPage.Content>
+        <Table
+          state={state}
+          // Search is on by default, so a table without this prop ships a box
+          // that reaches no query.
+          search={<CollectionSearch placeholder="Search items" />}
+          filters={
+            <CollectionToolbarFilters>
+              <MultiSelectCheckboxFilter
+                filter={statusFilter}
+                collection={statusOptions}
+                toolbarItemProps={{ label: 'Status' }}
+                accordionItemProps={{ label: 'Status' }}
+              />
+            </CollectionToolbarFilters>
+          }
+          emptyState={
+            <CollectionEmptyState
+              title="No items yet"
+              addNewCta={{ text: 'Add item', onClick: openNew }}
+            />
+          }
+          noResultsState={
+            <CollectionNoResultsState
+              title="No items match"
+              subtitle="Try another search or clear the filters."
+            />
+          }
+          // Without it a failed query looks like a slow one: skeletons, forever.
+          errorState={(err, { retry }) => (
+            <CollectionErrorState
+              title="Couldn't load items"
+              subtitle={String(err)}
+              action={{ text: 'Retry', onClick: retry }}
+            />
+          )}
+          // Passing the row lets the entity page title itself before its fetch.
+          onRowClick={(item) =>
+            navigateToEntityPage({ path: `/${item.id}`, entity: item })
+          }
+          columns={[
+            { id: 'name', title: 'Name', render: (item) => item.name },
+            {
+              id: 'status',
+              title: 'Status',
+              render: (item) => STATUS_LABELS[item.status],
+            },
+          ]}
+        />
+      </CollectionPage.Content>
+    </CollectionPage>
+  );
+};