@iress-oss/ids-mcp-server 0.0.1-dev.0

package/generated/docs/components-navbar-recipes-docs.md

@@ -0,0 +1,413 @@
+[](#recipes)Recipes
+===================
+
+[](#custom-navbars)Custom navbars
+---------------------------------
+
+At its essence, the navbar component is a coloured panel. This means you can easily create custom navbars by creating your own content structure and passing everything into the `children` slot.
+
+If you're creating a custom navbar, there are a few things to be aware of. Firstly, some props may not work; for example, the `horizontalAlign` prop won't be applied if there's nothing in the `nav` slot. Similarly, the breakpoint prop won't work if there's nothing in the `nav` slot as it's designed to show and hide `nav` slot content. You can still create responsive designs, but you'll need to set this up yourself.
+
+Secondly, you'll need to make sure your content is accessible; for example using a `nav` element with an `aria-label` when you add navigation links.
+
+### [](#custom-responsive-navbar)Custom responsive navbar
+
+This example uses existing IDS components to create a custom responsive navbar. On smaller screens the main `nav` in the `IressNavbar` is hidden, and a menu button is shown. The menu button triggers a slideout that contains the nav links.
+
+![Iress logo](assets/ids-logo.png)
+
+Custom navbar
+=============
+
+[Link 1](#)[Link 2](#)[Link 3](#)
+
+Hide code
+
+\[data-radix-scroll-area-viewport\] { scrollbar-width: none; -ms-overflow-style: none; -webkit-overflow-scrolling: touch; } \[data-radix-scroll-area-viewport\]::-webkit-scrollbar { display: none; } :where(\[data-radix-scroll-area-viewport\]) { display: flex; flex-direction: column; align-items: stretch; } :where(\[data-radix-scroll-area-content\]) { flex-grow: 1; }
+
+const Navbar \= () \=> {
+  const { showSlideout } \= useSlideout();
+  const containerRef \= useRef<HTMLDivElement | null\>(null);
+  return (
+    <div ref\={containerRef} style\={{ minHeight: '200px' }}\>
+      <IressNavbar
+        nav\={
+          <IressHide hiddenOn\={{ xs: true, md: false }}\>
+            <IressMenu layout\="inline" role\="nav"\>
+              <IressMenuItem href\="#"\>Link 1</IressMenuItem\>
+              <IressMenuItem href\="#"\>Link 2</IressMenuItem\>
+              <IressMenuItem href\="#"\>Link 3</IressMenuItem\>
+            </IressMenu\>
+          </IressHide\>
+        }
+      \>
+        <IressInline gutter\="md" verticalAlign\="middle"\>
+          <IressHide hiddenOn\={{ md: true }}\>
+            <IressButton
+              mode\="tertiary"
+              onClick\={() \=> showSlideout('nav-slideout')}
+            \>
+              <IressIcon name\="bars" size\="2x" />
+            </IressButton\>
+          </IressHide\>
+          <img src\="assets/ids-logo.png" alt\="Iress logo" />
+          <IressText\>
+            <h1\>Custom navbar</h1\>
+          </IressText\>
+        </IressInline\>
+      </IressNavbar\>
+      <IressSlideout
+        id\="nav-slideout"
+        style\={{ '--iress-position': 'absolute' } as never}
+        position\="left"
+        container\={containerRef}
+      \>
+        <nav aria-label\="tertiary navigation"\>
+          <IressMenu role\="nav"\>
+            <IressMenuItem href\="#"\>Link 1</IressMenuItem\>
+            <IressMenuItem href\="#"\>Link 2</IressMenuItem\>
+            <IressMenuItem href\="#"\>Link 3</IressMenuItem\>
+          </IressMenu\>
+        </nav\>
+      </IressSlideout\>
+    </div\>
+  );
+};
+export const ResponsiveNavbar \= () \=> (
+  <IressSlideoutProvider\>
+    <Navbar />
+  </IressSlideoutProvider\>
+);
+
+Copy
+
+### [](#custom-navbar-with-other-ids-components)Custom navbar with other IDS components
+
+Not all navbars contain navigation links; often they contain global actions or filters. The example below shows a navbar containing a user dropdown, two buttons and a global search field.
+
+Because there are no navigation links, we don't need to add a nav element in this example.
+
+![Iress logo](assets/ids-logo.png)
+
+Barry George
+
+Person 1Person 2Person 3
+
+4
+
+**Input**
+
+Hide code
+
+\[data-radix-scroll-area-viewport\] { scrollbar-width: none; -ms-overflow-style: none; -webkit-overflow-scrolling: touch; } \[data-radix-scroll-area-viewport\]::-webkit-scrollbar { display: none; } :where(\[data-radix-scroll-area-viewport\]) { display: flex; flex-direction: column; align-items: stretch; } :where(\[data-radix-scroll-area-content\]) { flex-grow: 1; }
+
+<IressNavbar horizontalAlign\="between"\>
+  <IressInline
+    horizontalAlign\="between"
+    verticalAlign\="middle"
+  \>
+    <img
+      alt\="Iress logo"
+      src\="assets/ids-logo.png"
+    />
+    <IressInline
+      gutter\="md"
+      verticalAlign\="stretch"
+    \>
+      <IressPopover
+        activator\={<IressTooltip tooltipText\="User"\><IressButton append\={<IressIcon name\="chevron-down" />} id\="btn"\><IressHide hiddenOn\={{md: false, xs: true}}\>Barry George</IressHide\><IressHide hiddenOn\={{md: true, xs: false}}\><IressIcon name\="user" /></IressHide\></IressButton\></IressTooltip\>}
+        align\="bottom-start"
+        type\="listbox"
+      \>
+        <IressMenu\>
+          <IressMenuItem\>
+            Person 1          </IressMenuItem\>
+          <IressMenuItem\>
+            Person 2          </IressMenuItem\>
+          <IressMenuItem\>
+            Person 3          </IressMenuItem\>
+        </IressMenu\>
+      </IressPopover\>
+      <IressBadge
+        host\={<IressButton mode\="tertiary"\><IressIcon name\="bell" screenreaderText\="notifications" size\="2x"/></IressButton\>}
+        mode\="danger"
+        pill
+      \>
+        4      </IressBadge\>
+      <IressButton mode\="tertiary"\>
+        <IressIcon
+          name\="plus"
+          screenreaderText\="add details"
+          size\="2x"
+        />
+      </IressButton\>
+      <IressField
+        hiddenLabel
+        label\="Input"
+      \>
+        <IressInput
+          name\="test-input"
+          prepend\={<IressIcon name\="search" />}
+        />
+      </IressField\>
+    </IressInline\>
+  </IressInline\>
+</IressNavbar\>
+
+Copy
+
+[](#secondary-navigation)Secondary navigation
+---------------------------------------------
+
+The Navbar component should only be used for primary navigation.
+
+If your site has secondary navigation, you can use the Menu component. Here are a few examples.
+
+### [](#navbar-combined-with-secondary-navigation)Navbar combined with secondary navigation
+
+You can use an `IressPanel` component to render the secondary navigation directly below your navbar. Use an `IressMenu` component for the links, and make sure you wrap it in a `nav` element. You'll need to add an `aria-label` to the `nav` element to make sure its purpose is clear to screen reader users.
+
+![IDS logo](assets/ids-logo.png)
+
+[Link 1](#)[Link 2](#)[Link 3](#)
+
+Secondary link 1Secondary link 2Secondary link 3
+
+Hide code
+
+\[data-radix-scroll-area-viewport\] { scrollbar-width: none; -ms-overflow-style: none; -webkit-overflow-scrolling: touch; } \[data-radix-scroll-area-viewport\]::-webkit-scrollbar { display: none; } :where(\[data-radix-scroll-area-viewport\]) { display: flex; flex-direction: column; align-items: stretch; } :where(\[data-radix-scroll-area-content\]) { flex-grow: 1; }
+
+<div\>
+  <IressNavbar
+    logo\={<img alt\="IDS logo" src\="assets/ids-logo.png"/>}
+    nav\={<IressMenu layout\="inline" role\="nav"\><IressMenuItem href\="#"\>Link 1</IressMenuItem\><IressMenuItem href\="#" selected\>Link 2</IressMenuItem\><IressMenuItem href\="#"\>Link 3</IressMenuItem\></IressMenu\>}
+  />
+  <IressPanel
+    background\="alt"
+    noBorderRadius
+    padding\="none"
+  \>
+    <nav aria-label\="secondary navigation"\>
+      <IressMenu
+        layout\="inline"
+        role\="nav"
+      \>
+        <IressMenuItem\>
+          Secondary link 1        </IressMenuItem\>
+        <IressMenuItem\>
+          Secondary link 2        </IressMenuItem\>
+        <IressMenuItem\>
+          Secondary link 3        </IressMenuItem\>
+      </IressMenu\>
+    </nav\>
+  </IressPanel\>
+</div\>
+
+Copy
+
+### [](#icon-strips)Icon strips
+
+You can change your secondary navigation to an icon strip by passing in icons to the `IressMenuItem` component. This can be rendered as a vertical strip (default), or a horizontal strip (by setting the `IressMenu` layout to `inline`).
+
+The example below has some custom CSS to fix the menu to the side of its container. This includes setting `--iress-initial-offset` on the slideout element to ensure the slideout is correctly positioned next to the icon strip.
+
+Hide code
+
+\[data-radix-scroll-area-viewport\] { scrollbar-width: none; -ms-overflow-style: none; -webkit-overflow-scrolling: touch; } \[data-radix-scroll-area-viewport\]::-webkit-scrollbar { display: none; } :where(\[data-radix-scroll-area-viewport\]) { display: flex; flex-direction: column; align-items: stretch; } :where(\[data-radix-scroll-area-content\]) { flex-grow: 1; }
+
+export const NavbarIconStrip \= () \=> {
+  const \[secondary, setSecondary\] \= useState(false);
+  const containerRef \= useRef<HTMLDivElement | null\>(null);
+  const handleSecondaryMenuItem \= () \=> !secondary && setSecondary(true);
+  return (
+    <div ref\={containerRef} style\={{ minHeight: '250px', height: '100%' }}\>
+      <IressNavbar
+        style\={
+          {
+            width: 'fit-content',
+            '--iress-nav-padding-x': 0,
+            position: 'relative',
+            zIndex: 1050,
+            height: '100%',
+          } as never
+        }
+      \>
+        <nav aria-label\="secondary navigation"\>
+          <IressMenu role\="nav"\>
+            <IressTooltip align\="right" tooltipText\="Hubs"\>
+              <IressMenuItem onClick\={handleSecondaryMenuItem}\>
+                <IressIcon name\="chart-network" size\="2x" fixedWidth />
+              </IressMenuItem\>
+            </IressTooltip\>
+            <IressTooltip align\="right" tooltipText\="My links"\>
+              <IressMenuItem onClick\={handleSecondaryMenuItem} selected\>
+                <IressIcon name\="link" size\="2x" fixedWidth />
+              </IressMenuItem\>
+            </IressTooltip\>
+            <IressTooltip align\="right" tooltipText\="Portfolios"\>
+              <IressMenuItem onClick\={handleSecondaryMenuItem}\>
+                <IressIcon name\="coins" size\="2x" fixedWidth />
+              </IressMenuItem\>
+            </IressTooltip\>
+            <IressTooltip align\="right" tooltipText\="Research"\>
+              <IressMenuItem onClick\={handleSecondaryMenuItem}\>
+                <IressIcon name\="binoculars" size\="2x" fixedWidth />
+              </IressMenuItem\>
+            </IressTooltip\>
+            <IressTooltip align\="right" tooltipText\="Admin"\>
+              <IressMenuItem onClick\={handleSecondaryMenuItem}\>
+                <IressIcon name\="cogs" size\="2x" fixedWidth />
+              </IressMenuItem\>
+            </IressTooltip\>
+          </IressMenu\>
+        </nav\>
+      </IressNavbar\>
+      <IressSlideout
+        style\={
+          {
+            '--iress-position': 'absolute',
+            '--iress-initial-offset': '4.5rem',
+            zIndex: '1',
+          } as never
+        }
+        position\="left"
+        container\={containerRef}
+        show\={secondary}
+        onShowChange\={(show, reason) \=> {
+          if (reason !== 'outside-press') {
+            setSecondary(show);
+          }
+        }}
+      \>
+        <nav aria-label\="tertiary navigation"\>
+          <IressMenu role\="nav"\>
+            <IressMenuItem href\="#"\>Link 1</IressMenuItem\>
+            <IressMenuItem href\="#"\>Link 2</IressMenuItem\>
+            <IressMenuItem href\="#"\>Link 3</IressMenuItem\>
+            <IressMenuItem href\="#"\>Link 4</IressMenuItem\>
+            <IressMenuItem href\="#"\>Link 5</IressMenuItem\>
+            <IressMenuItem href\="#"\>Link 6</IressMenuItem\>
+          </IressMenu\>
+        </nav\>
+      </IressSlideout\>
+    </div\>
+  );
+};
+
+Copy
+
+### [](#fixed-navigation)Fixed navigation
+
+A common pattern for small screens is to fix navigation links at the bottom of the screen. This can be done by applying some custom CSS to your secondary navigation.
+
+![IDS logo](assets/ids-logo.png)
+
+[](#)
+
+About
+-----
+
+Iress Uncaged is a portal of Iress software, detailing their adherence to Iress Governance & Standards.
+
+Software that is registered with Iress Uncaged will appear [here.](/)
+
+In order to register your software with Uncaged, you will need to create an Atlas YAML in the root of your repo, see here for instructions. Once the YAML is available in your main branch your software will appear in this dashboard within 24 Hours.
+
+Page heading
+============
+
+Some page content...
+
+[
+
+Dashboard
+
+
+
+](#)[
+
+Analysis
+
+
+
+](#)[
+
+Messages
+
+
+
+](#)
+
+Hide code
+
+\[data-radix-scroll-area-viewport\] { scrollbar-width: none; -ms-overflow-style: none; -webkit-overflow-scrolling: touch; } \[data-radix-scroll-area-viewport\]::-webkit-scrollbar { display: none; } :where(\[data-radix-scroll-area-viewport\]) { display: flex; flex-direction: column; align-items: stretch; } :where(\[data-radix-scroll-area-content\]) { flex-grow: 1; }
+
+<div className\="mobile-mockup-wrapper"\>
+  <IressNavbar
+    horizontalAlign\="between"
+    logo\={<img alt\="IDS logo" src\="assets/ids-logo.png"/>}
+    nav\={<IressMenu layout\="inline" role\="nav"\><IressTooltip align\="bottom" tooltipText\="User details"\><IressMenuItem href\="#"\><IressIcon name\="user" size\="2x"/></IressMenuItem\></IressTooltip\><IressPopover activator\={<IressTooltip align\="bottom" tooltipText\="Settings"\><IressMenuItem\><IressIcon name\="cog" size\="2x"/></IressMenuItem\></IressTooltip\>} align\="bottom-end" style\={{'--iress-max-width': '12rem'}} type\="dialog"\><IressPanel data-testid\="about-page"\><IressText\><h2\>About</h2\><p\>Iress Uncaged is a portal of Iress software, detailing their adherence to Iress Governance & Standards.</p\><p\>Software that is registered with Iress Uncaged will appear{' '}<a href\="/"\>here.</a\></p\><p\>In order to register your software with Uncaged, you will need to create an Atlas YAML in the root of your repo, see here for instructions. Once the YAML is available in your main branch your software will appear in this dashboard within 24 Hours.</p\></IressText\></IressPanel\></IressPopover\></IressMenu\>}
+  />
+  <IressPanel\>
+    <IressText\>
+      <h1\>
+        Page heading      </h1\>
+    </IressText\>
+    <IressText\>
+      Some page content...    </IressText\>
+  </IressPanel\>
+  <IressPanel
+    background\="alt"
+    padding\="none"
+    style\={{
+      insetBlockEnd: '0',
+      insetInlineEnd: '0',
+      insetInlineStart: '0',
+      position: 'absolute'
+    }}
+  \>
+    <nav aria-label\="secondary navigation"\>
+      <IressMenu
+        fluid
+        layout\="inline-equal-width"
+      \>
+        <IressMenuItem
+          href\="#"
+          selected
+        \>
+          <IressStack\>
+            <IressIcon name\="tachometer-alt" />
+            <IressText\>
+              Dashboard            </IressText\>
+          </IressStack\>
+        </IressMenuItem\>
+        <IressMenuItem href\="#"\>
+          <IressStack\>
+            <IressIcon name\="chart-line" />
+            <IressText\>
+              Analysis            </IressText\>
+          </IressStack\>
+        </IressMenuItem\>
+        <IressMenuItem href\="#"\>
+          <IressStack\>
+            <IressIcon name\="envelope" />
+            <IressText\>
+              Messages            </IressText\>
+          </IressStack\>
+        </IressMenuItem\>
+      </IressMenu\>
+    </nav\>
+  </IressPanel\>
+</div\>
+
+Copy
+
+On this page
+
+*   [Custom navbars](#custom-navbars)
+    *   [Custom responsive navbar](#custom-responsive-navbar)
+    *   [Custom navbar with other IDS components](#custom-navbar-with-other-ids-components)
+*   [Secondary navigation](#secondary-navigation)
+    *   [Navbar combined with secondary navigation](#navbar-combined-with-secondary-navigation)
+    *   [Icon strips](#icon-strips)
+    *   [Fixed navigation](#fixed-navigation)