graycoreio/daffodil

<h1>Sidebar</h1>
<p>Sidebar is a component used to display additional information to the side of a page that may be fixed or collapsible.</p>

<h2>Overview</h2>
<p>Sidebars are often used for navigation, but it's built to be flexible and extensible so that it can be used for any content. Sidebar supports a header and footer component with minimal default styling.</p>

<h3>Basic sidebar</h3>
<p>The default setting for sidebar is <code>mode="side"</code> and <code>side="left"</code>.
</p>

<design-land-article-encapsulated>
  <design-land-example-viewer-container example="basic-sidebar"></design-land-example-viewer-container>
</design-land-article-encapsulated>

<h3>Implementing the main and sidebar content</h3>
<p>The main and sidebar content should be placed inside of the <code>&lt;daff-sidebar-viewport&gt;</code>. The sidebar content should be placed inside of the <code>&lt;daff-sidebar&gt;</code>.</p>

<p>A viewport navigation can be:<p>

<h4>Placed alongside the <code>&lt;daff-sidebar&gt;</code> using the <code>[daff-sidebar-viewport-nav]</code> selector.</h4>
<pre><code>&lt;daff-sidebar-viewport (backdropClicked)="toggleOpen()"&gt;
  &lt;nav daff-sidebar-viewport-nav daff-navbar&gt;
    Nav content
  &lt;/nav&gt;    
  &lt;daff-sidebar mode="over" [open]="open"&gt;
    &lt;div class="sidebar-content"&gt;
      Sidebar content
    &lt;/div&gt;
  &lt;/daff-sidebar&gt;
  &lt;div class="page-content"&gt;
    Page content
  &lt;/div&gt;
&lt;/daff-sidebar-viewport&gt;</code></pre>

<p>Additionally, a <code>[daff-sidebar-viewport-nav]</code> that is paired with a <code>side-fixed</code> sidebar can be placed <code>above</code> or <code>beside</code> to the sidebar. It's placed <code>above</code> by default but can be updated by using the <code>navPlacement</code> property on the <code>&lt;daff-sidebar-viewport&gt;</code>.</p>

<h4>Placed inside of the viewport content by omitting the <code>[daff-sidebar-viewport-nav]</code> selector from the nav component.</h4>

<pre><code>&lt;daff-sidebar-viewport (backdropClicked)="toggleOpen()"&gt;
  &lt;nav daff-navbar&gt;
    Nav content
  &lt;/nav&gt;    
  &lt;daff-sidebar mode="over" [open]="open"&gt;
    &lt;div class="sidebar-content"&gt;
      Sidebar content
    &lt;/div&gt;
  &lt;/daff-sidebar&gt;
  &lt;div class="page-content"&gt;
    Page content
  &lt;/div&gt;
&lt;/daff-sidebar-viewport&gt;</code></pre>

<h4>Required imports</h4>
<p>The <code>BrowserAnimationsModule</code> or <code>NoopAnimationsModule</code> must be imported in the particular Angular <code>&#64;NgModule</code> the sidebar is used in for the sidebar to render and work properly.</p>

<h3>Header and footer</h3>
<p>The <code>&lt;daff-sidebar-header&gt;</code> includes optional title (<code>[daffSidebarHeaderTitle]</code>) and action (<code>[daffSidebarHeaderAction]</code>) selectors, and a slot to render custom content. The action selector should be used along with the <code>&lt;daff-icon-button&gt;</code> (view <a routerLink="/button">Button Documentation</a>) to make sure that the action is positioned correctly and it passes WCAG guidelines.</p>

<p>The <code>&lt;daff-sidebar-footer&gt;</code> is a "holder" component with minimal default styling. Its main purpose is to position the footer at the bottom of the sidebar, allowing the sidebar's content to overflow and scroll while ensuring that the footer remains constantly visible.</p>

<p>Both the header and footer are optional components that will not render in the DOM if they are not used.</p>

<h3>Opening and closing a sidebar</h3>
<p>The <code>open</code> property is used to set the open state for a sidebar.</p>

<p>By default, sidebar supports two methods of closing itself: clicking on the backdrop of the sidebar viewport or pressing <code>ESC</code> when the sidebar has focus.</p>

<table>
  <thead>
    <tr>
      <th>Method</th>
      <th></th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td>
        <code>(backdropClicked)</code>
      </td>
      <td>Set on the <code>&lt;daff-sidebar-viewport&gt;</code></td>
    </tr>
    <tr>
      <td>
        <code>(escapePressed)</code>
      </td>
      <td>Set on the <code>&lt;daff-sidebar&gt;</code></td>
    </tr>
  </tbody>
</table>

<h3>Modes</h3>
<p><code>&lt;daff-sidebar&gt;</code> can be rendered four different ways by using the <code>mode</code> property. If <code>mode</code> is not specified, <code>side</code> is used by default.</p>

<table>
  <thead>
    <tr>
      <th>Mode</th>
      <th>Description</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td><code>side</code></td>
      <td>Sidebar is placed alongside the content</td>
    </tr>
    <tr>
      <td><code>side-fixed</code></td>
      <td>Sidebar is placed alongside the content and will scroll separately from the content</td>
    </tr>
    <tr>
      <td><code>over</code></td>
      <td>Sidebar slides over the rest of the content in the viewport and covering it with a backdrop</td>
    </tr>
    <tr>
      <td><code>under</code></td>
      <td>Sidebar freezes in place and and the content slides above it, while also being covered by a backdrop</td>
    </tr>
  </tbody>
</table>

<h3>Sides</h3>
<p><code>&lt;daff-sidebar&gt;</code> can be positioned on either side of a screen by using the <code>side</code> property. If <code>side</code> is not specified, <code>left</code> is used by default.</p>

<table>
  <thead>
    <tr>
      <th>Side</th>
      <th>Description</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td><code>left</code></td>
      <td>Places sidebar on the left side of the screen</td>
    </tr>
    <tr>
      <td><code>right</code></td>
      <td>Places sidebar on the right side of the screen</td>
    </tr>
  </tbody>
</table>

<h3>Custom styles</h3>
<h4>Changing a sidebar's width</h4>
<p>The default width of a sidebar is <code>240px</code>. It can be changed by setting it via CSS:</p>

<pre><code>daff-sidebar &lcub;
  width: 320px;
&rcub;</code></pre>

<h4>Changing a side-fixed sidebar's top offset position</h4>
<p>The default offset position of a sidebar is <code>0px</code>. The <code>--daff-sidebar-side-fixed-top-shift</code> variable can be used to adjust the top offset position for a primary sidebar and its viewport content.</p>

<pre><code>body &lcub;
  --daff-sidebar-side-fixed-top-shift: 64px;
&rcub;</code></pre>

<h3>Examples</h3>
<h4>Over and under sidebars</h4>
<design-land-article-encapsulated>
  <design-land-example-viewer-container example="over-and-under-sidebars"></design-land-example-viewer-container>
</design-land-article-encapsulated>

<h4>Side fixed sidebar</h4>
<design-land-article-encapsulated>
  <design-land-example-viewer-container example="side-fixed-sidebar"></design-land-example-viewer-container>
</design-land-article-encapsulated>

<h4>Sidebar with sticky content</h4>
<design-land-article-encapsulated>
  <design-land-example-viewer-container example="sidebar-with-sticky-content"></design-land-example-viewer-container>
</design-land-article-encapsulated>

<h3>Accessibility</h3>
<p>A meaningful <code>role</code> should be set on all sidebars depending on how they are used. When the <code>&lt;daff-sidebar-header&gt;</code> is not used or there is no title for the sidebar, a meaningful <code>aria-label</code> should be set to describe the sidebar.</p>

<h4>Focus</h4>
<p>Focus trapping is enabled for <code>over</code> and <code>under</code> modes, and disabled for <code>side</code> and <code>side-fixed</code> modes. When a sidebar is opened, the first tabbable element within the will receive focus. When a sidebar is closed, the element that was focused before the sidebar was opened will be re-focused.</p>