@wix/design-system 1.193.0 → 1.195.0

package/dist/docs/components/BoxExamples.md

@@ -0,0 +1,349 @@
+
+## Feature Examples
+
+
+### Structure
+- description: <p>Render any kind of content inside of a box. Boxes must include at least one element, and can wrap multiple child elements.</p>
+- example: 
+```jsx 
+<Box>
+  <StorybookComponents.Placeholder>Content</StorybookComponents.Placeholder>
+</Box>;
+```
+
+### Dimensions
+- description: <p>Control the component size by setting its <code>width</code> and <code>height</code> in pixels or percentage. The box container size will automatically equal the size of content added inside if these values are not specified.</p>
+- example: 
+```jsx 
+<StorybookComponents.Stack flexDirection="column">
+  <Box width="100%" height="100px">
+    <StorybookComponents.Placeholder>
+      Width 100%, Height 100px
+    </StorybookComponents.Placeholder>
+  </Box>
+  <Box width="50%" height="50px">
+    <StorybookComponents.Placeholder>
+      Width 50%, Height 50px
+    </StorybookComponents.Placeholder>
+  </Box>
+</StorybookComponents.Stack>;
+```
+
+### Direction
+- description: <p>Control the <code>direction</code> in which child elements will be listed inside a box. There are 2 types of directions supported:</p><li><code>horizontal</code> lists items in a single row.</li><li><code>vertical</code> lists items in a single column. This layout will automatically extend each item to the full width of the box.</li>
+- example: 
+```jsx 
+<StorybookComponents.Stack flexDirection="column">
+  <Box direction="horizontal">
+    <StorybookComponents.Placeholder>
+      Horizontal
+    </StorybookComponents.Placeholder>
+    <StorybookComponents.Placeholder>
+      Horizontal
+    </StorybookComponents.Placeholder>
+    <StorybookComponents.Placeholder>
+      Horizontal
+    </StorybookComponents.Placeholder>
+  </Box>
+  <Box direction="vertical">
+    <StorybookComponents.Placeholder>Vertical</StorybookComponents.Placeholder>
+    <StorybookComponents.Placeholder>Vertical</StorybookComponents.Placeholder>
+    <StorybookComponents.Placeholder>Vertical</StorybookComponents.Placeholder>
+  </Box>
+</StorybookComponents.Stack>;
+```
+
+### Gap
+- description: <p>Control the space between elements contained inside a box with <code>gap</code> prop. WSR spacing tokens and values are shown in pixels.</p>
+- example: 
+```jsx 
+<StorybookComponents.Stack flexDirection="column">
+  <Box gap="SP1">
+    <StorybookComponents.Placeholder>6px gap</StorybookComponents.Placeholder>
+    <StorybookComponents.Placeholder>6px gap</StorybookComponents.Placeholder>
+    <StorybookComponents.Placeholder>6px gap</StorybookComponents.Placeholder>
+  </Box>
+  <Box gap="48px">
+    <StorybookComponents.Placeholder>48px gap</StorybookComponents.Placeholder>
+    <StorybookComponents.Placeholder>48px gap</StorybookComponents.Placeholder>
+    <StorybookComponents.Placeholder>48px gap</StorybookComponents.Placeholder>
+  </Box>
+</StorybookComponents.Stack>;
+```
+
+### Horizontal alignment
+- description: <p>Align child elements of an X-axis inside a box with <code>align</code> prop as follows:</p><li><code>left</code></li><li><code>center</code></li><li><code>right</code></li><li><code>space-between</code>distributes child items evenly.</li>
+- example: 
+```jsx 
+<StorybookComponents.Stack>
+  <StorybookComponents.Placeholder>
+    <Box align="left">Left</Box>
+  </StorybookComponents.Placeholder>
+  <StorybookComponents.Placeholder>
+    <Box align="center">Center</Box>
+  </StorybookComponents.Placeholder>
+  <StorybookComponents.Placeholder>
+    <Box align="right">Right</Box>
+  </StorybookComponents.Placeholder>
+  <StorybookComponents.Placeholder>
+    <Box align="space-between">
+      <Box>Space</Box>
+      <Box>Between</Box>
+    </Box>
+  </StorybookComponents.Placeholder>
+</StorybookComponents.Stack>;
+```
+
+### Vertical alignment
+- description: <p>Align child elements of a Y-axis inside a box with <code>verticalAlign</code> prop as follows:</p><li><code>top</code></li><li><code>middle</code></li><li><code>bottom</code></li><li><code>space-between</code> distributes child items evenly.</li>
+- example: 
+```jsx 
+<StorybookComponents.Stack>
+  <StorybookComponents.Placeholder height="50px">
+    <Box verticalAlign="top" height="100%">
+      Top
+    </Box>
+  </StorybookComponents.Placeholder>
+  <StorybookComponents.Placeholder height="50px">
+    <Box verticalAlign="middle" height="100%">
+      Middle
+    </Box>
+  </StorybookComponents.Placeholder>
+  <StorybookComponents.Placeholder height="50px">
+    <Box verticalAlign="bottom" height="100%">
+      Bottom
+    </Box>
+  </StorybookComponents.Placeholder>
+  <StorybookComponents.Placeholder height="50px">
+    <Box verticalAlign="space-between" direction="vertical" height="100%">
+      <Box>Space</Box>
+      <Box>Between</Box>
+    </Box>
+  </StorybookComponents.Placeholder>
+</StorybookComponents.Stack>;
+```
+
+### Padding
+- description: <p>Control the amount of white space around child elements inside a box. Padding can be defined by:</p><li><code>padding</code> which defines the amount of white space from all sides.</li><li><code>paddingTop</code>, <code>paddingRight</code>, <code>paddingBottom</code>, and<code>paddingLeft</code> which define the amount of white space from a specific side only.</li>
+- example: 
+```jsx 
+<StorybookComponents.Stack>
+  <StorybookComponents.Placeholder>
+    <Box padding="SP4">Equal padding</Box>
+  </StorybookComponents.Placeholder>
+  <StorybookComponents.Placeholder>
+    <Box
+      paddingTop="SP2"
+      paddingRight="SP10"
+      paddingBottom="SP2"
+      paddingLeft="SP10"
+    >
+      Different side paddings
+    </Box>
+  </StorybookComponents.Placeholder>
+  <StorybookComponents.Placeholder>
+    <Box>No padding</Box>
+  </StorybookComponents.Placeholder>
+</StorybookComponents.Stack>;
+```
+
+### Margin
+- description: <p>Control the amount of white space around the box component itself with different properties. </p><li>Define the amount of space from all sides with <code>margin</code>.</li><li>Define the amount of space for a specific side only with <code>marginTop</code>, <code>marginRight</code>, <code>marginBottom</code> or <code>marginLeft</code> .</li>
+- example: 
+```jsx 
+<StorybookComponents.Stack>
+  <Box height="18px" width="100%">
+    <StorybookComponents.Placeholder>No margin</StorybookComponents.Placeholder>
+  </Box>
+  <Box height="18px" width="100%" margin="SP6 SP2">
+    <StorybookComponents.Placeholder>
+      With margin
+    </StorybookComponents.Placeholder>
+  </Box>
+</StorybookComponents.Stack>;
+```
+
+### Color
+- description: <p>Control the background and text color of a component with:</p><li><code>backgroundColor</code> to specify the background fill color.</li><li><code>color</code> to specify the text color.</li><p></p><p>Properties include WSR color variables and natively supported values, such as HEX, RGB, etc.</p>
+- example: 
+```jsx 
+<StorybookComponents.Stack>
+  <Box padding="SP4" margin="SP2" backgroundColor="D80" color="D10">
+    Dark text
+  </Box>
+  <Box padding="SP4" margin="SP2" backgroundColor="D10" color="D80">
+    Light text
+  </Box>
+  <Box padding="SP4" margin="SP2" backgroundColor="B10" color="D80">
+    Light text
+  </Box>
+  <Box padding="SP4" margin="SP2" backgroundColor="G10" color="D80">
+    Light text
+  </Box>
+  <Box padding="SP4" margin="SP2" backgroundColor="Y10" color="D10">
+    Dark text
+  </Box>
+</StorybookComponents.Stack>;
+```
+
+### Border
+- description: <p>Control the style of a border with the following properties:</p><li><code>border</code> enables a border and sets its width and style. This prop does not include WSR color variable keys.</li><li><code>borderColor</code> specifies the border color.</li><li><code>borderTopColor</code>, <code>borderRightColor</code>, <code>borderBottomColor</code>, <code>borderLeftColor</code> specifies the border color per edge.</li><li><code>borderRadius</code> specifies the corner radius.</li>
+- example: 
+```jsx 
+<StorybookComponents.Stack>
+  <Box
+    padding="SP6"
+    margin="SP1"
+    border="1px solid"
+    borderColor="D50"
+    borderRadius={0}
+  ></Box>
+  <Box
+    padding="SP6"
+    margin="SP1"
+    border="2px dotted"
+    borderColor="D40"
+    borderRadius={6}
+  ></Box>
+  <Box
+    padding="SP6"
+    margin="SP1"
+    border="3px dashed"
+    borderColor="D30"
+    borderRadius={12}
+  ></Box>
+  <Box
+    padding="SP6"
+    margin="SP1"
+    border="6px solid"
+    borderColor="D20"
+    borderRadius={72}
+  ></Box>
+</StorybookComponents.Stack>;
+```
+
+### Inline
+- description: <p>Define how a box behaves as an inline element when placed next to other components.</p>
+- example: 
+```jsx 
+<StorybookComponents.Stack flexDirection="column">
+  <Text>
+    This is a sentence with an action at the end of it.
+    <Box>
+      <TextButton>Add link</TextButton>
+    </Box>
+  </Text>
+  <Text>
+    This is a sentence with an action at the end of it.
+    <Box inline>
+      <TextButton>Add link</TextButton>
+    </Box>
+  </Text>
+</StorybookComponents.Stack>;
+```
+
+
+
+
+    
+
+
+## Common Use Case Examples
+
+
+### Content arrangement
+- description: <p>Use a box to arrange elements inside of other components in a desired way.</p>
+- example: 
+```jsx 
+() => {
+  const options = [
+    {
+      value: (
+        <Box verticalAlign="middle">
+          <Image width="48px" height="48px" />
+          <Box marginLeft="SP3" direction="vertical">
+            <Heading size="small">Structured data</Heading>
+            <Text size="small" secondary>
+              Make your product eligible for rich results in search engines.
+            </Text>
+          </Box>
+        </Box>
+      ),
+      width: '80%',
+    },
+    {
+      value: (
+        <IconButton skin="inverted">
+          <Icons.ChevronDown />
+        </IconButton>
+      ),
+      align: 'right',
+    },
+  ];
+
+  return <TableListItem options={options} />;
+};
+```
+
+### List item
+- description: <p>A combination of boxes can be used to construct custom widgets and list items.</p>
+- example: 
+```jsx 
+() => (
+  <Box height={160}>
+    <Box align="center" verticalAlign="middle" width={180}>
+      <Image
+        height="180px"
+        borderRadius="8px 0px 0px 8px"
+        src="running_man.png"
+      />
+    </Box>
+    <Box
+      direction="vertical"
+      borderRadius="0px 8px 8px 0px"
+      verticalAlign="space-between"
+      padding="18px 24px"
+      backgroundColor="D80"
+      flexGrow={1}
+    >
+      <Box verticalAlign="space-between" flexGrow={1}>
+        <Box direction="vertical" gap="3px">
+          <Heading size="small">Get running!</Heading>
+          <Text size="small" secondary>
+            Scheduled for April 26, 2021
+          </Text>
+        </Box>
+      </Box>
+      <Box align="space-between">
+        <Box gap="24px">
+          <Box verticalAlign="middle" gap="0px">
+            <Icons.LockUnlockedSmall />
+            <Box marginLeft={1}>
+              <Text size="small">Public</Text>
+            </Box>
+          </Box>
+          <Box verticalAlign="middle">
+            <Box marginLeft={1}>
+              <Text size="small">Join for Free</Text>
+            </Box>
+          </Box>
+        </Box>
+        <Box>
+          <Box verticalAlign="middle">
+            <Box gap="SP2">
+              <IconButton priority="secondary" size="small">
+                <Icons.MoreSmall />
+              </IconButton>
+              <Button priority="secondary" size="small">
+                Edit
+              </Button>
+            </Box>
+          </Box>
+        </Box>
+      </Box>
+    </Box>
+  </Box>
+);
+```
+
+

package/dist/docs/components/BreadcrumbsExamples.md

@@ -0,0 +1,249 @@
+
+## Feature Examples
+
+
+### Size
+- description: <p>Control the size of breadcrumbs with the <code>size</code> property. It supports 2 sizes:</p><li><code>medium</code> is used by default in regular page layouts.</li><li>When it's necessary to emphasize the path, use <code>large</code>.</li>
+- example: 
+```jsx 
+<StorybookComponents.Stack flexDirection="column">
+  <Breadcrumbs
+    items={[
+      { id: 0, value: 'Medium' },
+      { id: 1, value: 'Medium' },
+      { id: 2, value: 'Medium' },
+    ]}
+    size="medium"
+    activeId={2}
+  />
+  <Breadcrumbs
+    items={[
+      { id: 0, value: 'Large' },
+      { id: 1, value: 'Large' },
+      { id: 2, value: 'Large' },
+    ]}
+    size="large"
+    activeId={2}
+  />
+</StorybookComponents.Stack>;
+```
+
+### Theme
+- description: <p>Control breadcrumbs' appearance with the <code>theme</code> prop. It supports 3 styles:</p><li><code>onGrayBackground</code> is used by default with the default page header style.</li><li>Use <code>onDarkBackground</code> when breadcrumbs appear on a dark background or an image.</li><li>Use <code>onWhiteBackground</code> when breadcrumbs appear on a white background, for example in a modal.</li>
+- example: 
+```jsx 
+<StorybookComponents.Stack flexDirection="column">
+  <StorybookComponents.Stack padding="24px">
+    <Breadcrumbs
+      theme="onGrayBackground"
+      items={[
+        { id: 0, value: 'On grey background' },
+        { id: 1, value: 'On grey background' },
+        { id: 2, value: 'On grey background' },
+      ]}
+      activeId={2}
+    />
+  </StorybookComponents.Stack>
+  <StorybookComponents.Background skin="dark">
+    <StorybookComponents.Stack padding="24px">
+      <Breadcrumbs
+        theme="onDarkBackground"
+        items={[
+          { id: 0, value: 'On dark background' },
+          { id: 1, value: 'On dark background' },
+          { id: 2, value: 'On dark background' },
+        ]}
+        activeId={2}
+      />
+    </StorybookComponents.Stack>
+  </StorybookComponents.Background>
+  <StorybookComponents.Background skin="light">
+    <StorybookComponents.Stack padding="24px">
+      <Breadcrumbs
+        theme="onWhiteBackground"
+        items={[
+          { id: 0, value: 'On white background' },
+          { id: 1, value: 'On white background' },
+          { id: 2, value: 'On white background' },
+        ]}
+        activeId={2}
+      />
+    </StorybookComponents.Stack>
+  </StorybookComponents.Background>
+</StorybookComponents.Stack>;
+```
+
+### Max width
+- description: <p>Control when a breadcrumb item gets truncated with the <code>itemMaxWidth</code> property. When truncated, the breadcrumb item shows an ellipsis and the full text appears in a tooltip on hover.</p><p></p><p>Default max width is <code>240</code> px.</p><p></p><p>Avoid truncating breadcrumb items at all by setting max width to <code>max-content</code>.</p>
+- example: 
+```jsx 
+() => {
+  const items = [
+    { id: 0, value: 'Title' },
+    { id: 1, value: 'Title' },
+    {
+      id: 2,
+      value: 'Long title is truncated when default maximum width is reached',
+    },
+    { id: 3, value: 'Title' },
+  ];
+
+  return (
+    <StorybookComponents.Stack flexDirection="column">
+      <Breadcrumbs items={items} activeId={3} itemMaxWidth="150px" />
+      <Breadcrumbs items={items} activeId={3} />
+      <Breadcrumbs items={items} activeId={3} itemMaxWidth="max-content" />
+    </StorybookComponents.Stack>
+  );
+};
+```
+
+### Disabled
+- description: <p>Stop users from navigating to a particular breadcrumb item with the <code>disabled</code> property.</p>
+- example: 
+```jsx 
+<Breadcrumbs
+  items={[
+    { id: 0, value: 'Title (Disabled)', disabled: true },
+    { id: 1, value: 'Title' },
+    { id: 2, value: 'Title' },
+    { id: 3, value: 'Title' },
+  ]}
+  activeId={3}
+/>;
+```
+
+
+
+
+    
+
+
+## Common Use Case Examples
+
+
+### Navigation between pages
+- description: <p>Add breadcrumbs to <code><Page.Header/></code> <a href="https://www.wix-style-react.com/storybook/?path=/story/components-layout-page--page-header"></a>to let users quickly navigate back to the previous page in the hierarchy.</p>
+- example: 
+```jsx 
+<Page.Header
+  title="Appointment Hours"
+  subtitle="Set default hours for when you and your staff are available to take appointments."
+  breadcrumbs={
+    <Breadcrumbs
+      activeId="3"
+      items={[
+        { id: '1', value: 'Home', link: '' },
+        { id: '2', value: 'Booking Settings', link: '' },
+        { id: '3', value: 'Appointment Hours', link: '' },
+      ]}
+      onClick={() => {}}
+    />
+  }
+  showBackButton
+  onBackClicked={() => {}}
+  actionsBar={
+    <StorybookComponents.Stack gap="12px">
+      <Button skin="inverted">Cancel</Button>
+      <Button>Save</Button>
+    </StorybookComponents.Stack>
+  }
+/>;
+```
+
+### Navigate between folders
+- description: <p>Use breadcrumbs to let users navigate between folders and files.</p>
+- example: 
+```jsx 
+() => {
+  const renderThumbnail = backgroundImage => (
+    <Cell span={2}>
+      <Thumbnail
+        backgroundImage={backgroundImage}
+        title={
+          <Text secondary size="tiny">
+            {backgroundImage}
+          </Text>
+        }
+        height={132}
+      />
+    </Cell>
+  );
+
+  return (
+    <CustomModalLayout
+      title="Choose images"
+      onCloseButtonClick={() => {}}
+      removeContentPadding={true}
+      showHeaderDivider
+      content={
+        <Box>
+          <Box>
+            <SidebarNext
+              skin="neutral"
+              isLoading={false}
+              selectedKey="2"
+              header={
+                <SidebarHeaderNext>
+                  <Button prefixIcon={<Icons.Add />}>Upload Media</Button>
+                </SidebarHeaderNext>
+              }
+            >
+              <SidebarItemNext itemKey="1">Home</SidebarItemNext>
+              <SidebarDividerNext />
+              <SidebarTitleItemNext>Manage</SidebarTitleItemNext>
+              <SidebarItemNext itemKey="2">Site Files</SidebarItemNext>
+              <SidebarItemNext itemKey="3">My Boards</SidebarItemNext>
+              <SidebarItemNext itemKey="4">Trash</SidebarItemNext>
+              <SidebarDividerNext />
+              <SidebarTitleItemNext>Explore</SidebarTitleItemNext>
+              <SidebarItemNext itemKey="5">Media from Wix</SidebarItemNext>
+              <SidebarItemNext itemKey="6">Shutterstock</SidebarItemNext>
+              <SidebarItemNext itemKey="7">Unsplash</SidebarItemNext>
+            </SidebarNext>
+          </Box>
+          <Box direction="vertical" width="100%">
+            <Box direction="vertical" padding="24px">
+              <Search />
+            </Box>
+            <Box padding="0px 24px 24px 24px">
+              <Breadcrumbs
+                theme="onWhiteBackground"
+                items={[
+                  { id: 0, value: 'Site Files', link: '' },
+                  { id: 1, value: 'Stores', link: '' },
+                  { id: 2, value: 'Product images', link: '' },
+                  { id: 3, value: 'Photos', link: '' },
+                ]}
+                activeId={3}
+              />
+            </Box>
+            <Box padding="0px 24px">
+              <Layout>
+                {renderThumbnail('ProductExample1.jpg')}
+                {renderThumbnail('ProductExample2.jpg')}
+                {renderThumbnail('ProductExample3.jpg')}
+                {renderThumbnail('ProductExample4.jpg')}
+                {renderThumbnail('ProductExample5.jpg')}
+                {renderThumbnail('ProductExample6.jpg')}
+                {renderThumbnail('ProductExample7.jpg')}
+                {renderThumbnail('ProductExample8.jpg')}
+              </Layout>
+            </Box>
+            <Box paddingTop="60px">
+              <Divider />
+            </Box>
+            <Box padding="12px 24px" align="right">
+              <Box>
+                <Button>Add to Page</Button>
+              </Box>
+            </Box>
+          </Box>
+        </Box>
+      }
+    />
+  );
+};
+```
+
+