@wix/patterns 1.366.0 → 1.370.0

package/dist/docs/SettingsPage.Card.md

@@ -0,0 +1,246 @@
+# SettingsPage.Card
+
+**Category:** Base Components/Pages/Settings Page
+
+## Examples
+
+### Basic
+
+This example demonstrates a basic usage of the `Card` in both the main and supplementary content.
+
+```tsx
+import React from 'react';
+import {
+  SettingsPage,
+  SettingsPageState,
+  useSettings,
+  useSettingsPage,
+} from '@wix/patterns';
+import { useForm } from '@wix/patterns/form';
+import { Box, Card, Text } from '@wix/design-system';
+
+interface MySettings {
+  id: string;
+  name?: string;
+  createdAt: Date;
+  updatedAt: Date;
+}
+
+function Basic() {
+  const form = useForm();
+  const state: SettingsPageState<MySettings> = useSettingsPage<MySettings>({
+    form,
+    onCancel: async () => console.log('Cancel clicked!'),
+    onSave: async () => {
+      const formValues = form.getValues();
+      console.log('formValues', formValues); // Save updated settings
+    },
+    saveErrorToast: (e) => 'Failed to save',
+    fetch: () =>
+      Promise.resolve({
+        settings: {
+          id: 'id',
+          name: 'Settings Name',
+          createdAt: new window.Date(),
+          updatedAt: new window.Date(),
+        },
+      }),
+  });
+
+  const settings = useSettings<MySettings>(state);
+
+  return (
+    <SettingsPage state={state}>
+      <SettingsPage.Header title={{ text: settings?.name ?? '' }} />
+      <SettingsPage.Content>
+        <SettingsPage.MainContent>
+          <SettingsPage.Card minHeight="24px">
+            <Card.Header title="Main Content Card" />
+            <Card.Divider />
+            <Card.Content>
+              <Box gap="SP2" direction="vertical">
+                <Text>Hi from the main content!</Text>
+              </Box>
+            </Card.Content>
+          </SettingsPage.Card>
+        </SettingsPage.MainContent>
+        <SettingsPage.AdditionalContent>
+          <SettingsPage.Card minHeight="24px">
+            <Card.Header title="Side Content Card" />
+            <Card.Divider />
+            <Card.Content>
+              <Box gap="SP2" direction="vertical">
+                <Text>Hi from the side panel!</Text>
+              </Box>
+            </Card.Content>
+          </SettingsPage.Card>
+        </SettingsPage.AdditionalContent>
+      </SettingsPage.Content>
+    </SettingsPage>
+  );
+}
+```
+
+---
+
+### Card States
+
+This example showcases various card statuses: `loading`, `error`, and `success`. Each status displays a corresponding state: Skeleton for `loading`, an Error state for `error`, or the actual children component for `success`.
+
+```tsx
+import React from 'react';
+import {
+  SettingsPage,
+  SettingsPageState,
+  useSettings,
+  useSettingsPage,
+} from '@wix/patterns';
+import { useForm } from '@wix/patterns/form';
+import { Box, Card, Text } from '@wix/design-system';
+import { CardContainerProps } from '../../../dist/types/components/CardContainer';
+
+interface MySettings {
+  id: string;
+  name?: string;
+  createdAt: Date;
+  updatedAt: Date;
+}
+
+function States() {
+  const form = useForm();
+  const state: SettingsPageState<MySettings> = useSettingsPage<MySettings>({
+    form,
+    onCancel: async () => console.log('Cancel clicked!'),
+    onSave: async () => {
+      const formValues = form.getValues();
+      console.log('formValues', formValues); // Save updated settings
+    },
+    saveErrorToast: (e) => 'Failed to save',
+    fetch: () =>
+      Promise.resolve({
+        settings: {
+          id: 'id',
+          name: 'Settings Name',
+          createdAt: new window.Date(),
+          updatedAt: new window.Date(),
+        },
+      }),
+  });
+
+  const settings = useSettings<MySettings>(state);
+
+  const [status1, setStatus1] =
+    React.useState<CardContainerProps['status']>('loading');
+
+  const [status2, setStatus2] =
+    React.useState<CardContainerProps['status']>('error');
+
+  React.useEffect(() => {
+    window.setTimeout(() => {
+      setStatus1('success');
+    }, 5000);
+  }, []);
+
+  return (
+    <SettingsPage state={state}>
+      <SettingsPage.Header title={{ text: settings?.name ?? '' }} />
+      <SettingsPage.Content>
+        <SettingsPage.MainContent>
+          <SettingsPage.Card minHeight="24px" status={status1}>
+            <Card.Header title="Loading -> Success" />
+            <Card.Divider />
+            <Card.Content>
+              <Box gap="SP2" direction="vertical">
+                <Text>It took a while but I'm here now!</Text>
+              </Box>
+            </Card.Content>
+          </SettingsPage.Card>
+        </SettingsPage.MainContent>
+        <SettingsPage.AdditionalContent>
+          <SettingsPage.Card minHeight="24px" status="loading">
+            <Card.Header title="Loading..." />
+            <Card.Divider />
+            <Card.Content>
+              <Box gap="SP2" direction="vertical">
+                <Text>Just a sec...</Text>
+              </Box>
+            </Card.Content>
+          </SettingsPage.Card>
+          <SettingsPage.Card
+            minHeight="24px"
+            status={status2}
+            errorState={{
+              action: {
+                text: 'Retry',
+                onClick: () => {
+                  setStatus2('loading');
+                  window.setTimeout(() => {
+                    setStatus2('success');
+                  }, 2000);
+                },
+              },
+            }}
+          >
+            <Card.Header title="Error Card" />
+            <Card.Divider />
+            <Card.Content>
+              <Box gap="SP2" direction="vertical">
+                <Text>Just a sec...</Text>
+              </Box>
+            </Card.Content>
+          </SettingsPage.Card>
+        </SettingsPage.AdditionalContent>
+      </SettingsPage.Content>
+    </SettingsPage>
+  );
+}
+```
+
+## API
+
+### Overview
+
+A card container used inside [`SettingsPage.MainContent`](./?path=/story/base-components-pages-settings-page--settingspage-maincontent) or [`SettingsPage.AdditionalContent`](./?path=/story/base-components-pages-settings-page--settingspage-additionalcontent). It wraps form fields and content sections with a card layout, and supports loading/error/success states for async content.
+
+```tsx
+import { SettingsPage } from '@wix/patterns/page';
+```
+
+### Extends
+
+[Card](https://www.docs.wixdesignsystem.com/?path=/story/components-layout-card--card)
+
+### Composition
+
+```tsx
+
+  
+  
+    
+        {/* ← this component */}
+        
+          {/* form fields */}
+        
+      
+    
+  
+
+```
+
+### Props
+
+| Prop | Type | Required | Default | Description |
+|------|------|----------|---------|-------------|
+| `status` | `"error" \| "loading" \| "idle" \| "success"` | No | - | Additional loading flag, if you need to show loader after the main entity is fetched. Also, if an error occurs on a side request (other than passed to `fetch`), you can use `error` to show the card error state. Alongside with `error` you also need to pass `errorState.onRetry` callback, which should change the `status` accordingly. |
+| `minHeight` | `string` | No | - | Height of content while loading (not including paddings) |
+| `errorState` | `ErrorCardProps` | No | - | Card Error State configuration |
+| `id` | `string` | No | - | Identifier of the card. If you want to open a page and auto-scroll and focus ont his card, pass in the the query params `anchor={yourCardId}`. |
+| `children` | `ReactNode` | No | - | Contains elements inside the card such as `<Card.Header/>`, `<Card.Subeader/>`, `<Card.Content/>` or `<Card.Divider/>`. |
+| `controls` | `ReactNode` | No | - | Contains elements that control the component, usually a `<CloseButton/>`. |
+| `stretchVertically` | `boolean` | No | - | Makes a card stretch vertically to max height in a layout or container. |
+| `hideOverflow` | `boolean` | No | - | Defines whether to hide portions of card content that overflows its dimensions. |
+| `showShadow` | `boolean` | No | - | Defines whether to apply a drop shadow effect. |
+| `dataHook` | `string` | No | - | Applies a data-hook HTML attribute that can be used in tests. |
+| `className` | `string` | No | - | Specifies a CSS class name to be appended to the component's root element. |
+| `highlight` | `"focus"` | No | - | Applies a highlighting effect on the borders of the component. |
+

package/dist/docs/SettingsPage.Content.md

@@ -0,0 +1,24 @@
+# SettingsPage.Content
+
+**Category:** Base Components/Pages/Settings Page
+
+## API
+
+### Overview
+
+A layout slot for the body of a [`SettingsPage`](./?path=/story/base-components-pages-settings-page--settingspage). Wraps `` and optionally `` to create the two-column layout.
+
+```tsx
+import { SettingsPage } from '@wix/patterns/page';
+```
+
+### Usage
+
+This component acts as a container for [SettingsPage.MainContent](./?path=/story/base-components-pages-settings-page--settingspage-maincontent) and [SettingsPage.AdditionalContent](./?path=/story/base-components-pages-settings-page--settingspage-additionalcontent) components. For examples of how this component is used, please refer to the [SettingsPage](./?path=/story/base-components-pages-settings-page--settingspage&tab=Examples) examples.
+
+### Props
+
+| Prop | Type | Required | Default | Description |
+|------|------|----------|---------|-------------|
+| `children` | `ReactNode` | Yes | - | <SettingsPage.MainContent> and, if needed, <Settings.AdditionalContent> elements |
+

package/dist/docs/SettingsPage.Header.md

@@ -0,0 +1,176 @@
+# SettingsPage.Header
+
+**Category:** Base Components/Pages/Settings Page
+
+## Examples
+
+### Basic
+
+This example shows a basic usage of `SettingsPage.Header`.
+
+```tsx
+import React from 'react';
+import {
+  SettingsPage,
+  useSettingsPage,
+  SettingsPageState,
+  useSettings,
+} from '@wix/patterns';
+import { useForm } from '@wix/patterns/form';
+import { Card, Text } from '@wix/design-system';
+
+interface MySettings {
+  id: string;
+  name?: string;
+  createdAt: Date;
+  updatedAt: Date;
+}
+
+function Basic() {
+  const form = useForm();
+  const state: SettingsPageState<MySettings> = useSettingsPage<MySettings>({
+    form,
+    onCancel: async () => console.log('Cancel clicked!'),
+    onSave: async () => {
+      const formValues = form.getValues();
+      console.log('formValues', formValues); // Save updated settings
+    },
+    saveErrorToast: () => 'Failed to save',
+    fetch: () =>
+      Promise.resolve({
+        settings: {
+          id: 'id',
+          name: 'Settings Name',
+          createdAt: new window.Date(),
+          updatedAt: new window.Date(),
+        },
+      }),
+  });
+
+  const settings = useSettings<MySettings>(state);
+
+  return (
+    <SettingsPage state={state}>
+      <SettingsPage.Header title={{ text: settings?.name || 'New Settings' }} />
+      <SettingsPage.MainContent>
+        <SettingsPage.Content>
+          <SettingsPage.Card minHeight="24px">
+            <Card.Header title="Card" />
+            <Card.Divider />
+            <Card.Content>
+              <Text>Simple card</Text>
+            </Card.Content>
+          </SettingsPage.Card>
+        </SettingsPage.Content>
+      </SettingsPage.MainContent>
+    </SettingsPage>
+  );
+}
+```
+
+---
+
+### More Actions
+
+This example displays a header with more actions CTA. To learn how to create a more actions menu, see [`MoreActions`](./?path=/story/features-actions-more-actions--more-actions).
+
+```tsx
+import React from 'react';
+import {
+  SettingsPage,
+  useSettingsPage,
+  SettingsPageState,
+  useSettings,
+  MoreActions,
+} from '@wix/patterns';
+import { useForm } from '@wix/patterns/form';
+import { DummyEntity } from '@wix/ambassador-cairo-dummyservice-v1-dummy-entity/types';
+import { Card, Text } from '@wix/design-system';
+import { InvoiceSmall } from '@wix/wix-ui-icons-common';
+
+function Basic() {
+  const form = useForm();
+  const state: SettingsPageState<DummyEntity> = useSettingsPage<DummyEntity>({
+    form,
+    onCancel: async () => console.log('Cancel clicked!'),
+    onSave: async () => {
+      const formValues = form.getValues();
+      console.log('formValues', formValues); // Save updated settings
+    },
+    saveErrorToast: () => 'Failed to save',
+    fetch: () =>
+      Promise.resolve({
+        settings: {
+          id: 'id',
+          name: 'Settings Name',
+        },
+      }),
+  });
+
+  const settings = useSettings<DummyEntity>(state);
+
+  return (
+    <SettingsPage state={state}>
+      <SettingsPage.Header
+        moreActions={
+          <MoreActions
+            items={[
+              [
+                {
+                  text: 'Open Subscriptions',
+                  prefixIcon: <InvoiceSmall />,
+                  onClick: () => {
+                    console.log('Open Subscriptions');
+                  },
+                },
+              ],
+            ]}
+          />
+        }
+        title={{ text: settings?.name || 'New Settings' }}
+      />
+      <SettingsPage.MainContent>
+        <SettingsPage.Content>
+          <SettingsPage.Card minHeight="24px">
+            <Card.Header title="Card" />
+            <Card.Divider />
+            <Card.Content>
+              <Text>Simple card</Text>
+            </Card.Content>
+          </SettingsPage.Card>
+        </SettingsPage.Content>
+      </SettingsPage.MainContent>
+    </SettingsPage>
+  );
+}
+```
+
+## API
+
+### Overview
+
+The header component for a [`SettingsPage`](./?path=/story/base-components-pages-settings-page--settingspage). Renders the page title, optional subtitle, and a more-actions menu. Place it as a direct child of ``.
+
+```tsx
+import { SettingsPage } from '@wix/patterns/page';
+```
+
+### Composition
+
+```tsx
+
+  }
+  />
+  ...
+
+```
+
+### Props
+
+| Prop | Type | Required | Default | Description |
+|------|------|----------|---------|-------------|
+| `moreActions` | `MoreActionsElement` | No | - | <MoreActions /> |
+| `breadcrumbs` | `ReactElement<Breadcrumbs, string \| JSXElementConstructor<any>>` | No | - | Page breadcrumbs |
+| `title` | `{ text: string; badges?: (Pick<BadgeProps, "skin" \| "prefixIcon" \| "suffixIcon"> & { text: string; })[] \| undefined; }` | Yes | - | Page title text and optional badges |
+| `subtitle` | `PageSubTitleProps` | No | - | Page subtitle text |
+

package/dist/docs/SettingsPage.MainContent.md

@@ -0,0 +1,24 @@
+# SettingsPage.MainContent
+
+**Category:** Base Components/Pages/Settings Page
+
+## API
+
+### Overview
+
+A slot component for the main content area of a [`SettingsPage`](./?path=/story/base-components-pages-settings-page--settingspage). Place it inside ``. This is where you render the primary form fields and cards.
+
+```tsx
+import { SettingsPage } from '@wix/patterns/page';
+```
+
+### Usage
+
+This component acts as a container for [SettingsPage.Card](./?path=/story/base-components-pages-settings-page--settingspage-card) child components and is displayed on the left side of the Page layout. For examples of how this component is used, please refer to the [SettingsPage](./?path=/story/base-components-pages-settings-page--settingspage&tab=Examples) examples.
+
+### Props
+
+| Prop | Type | Required | Default | Description |
+|------|------|----------|---------|-------------|
+| `dataHook` | `string` | No | - | Applies a data-hook HTML attribute that can be used in tests |
+