Skip to content

Commit

Permalink
docs(navigation-secondary): improve jsdoc and code tab (#964)
Browse files Browse the repository at this point in the history
* docs(navigation-secondary): improve jsdoc and code tab

* docs(navigation-secondary): improve visible property jsdoc

* docs(navigation-secondary): improve shadowparts jsdoc

* docs: remove htmlexample shortcode

* docs(navigation-secondary): move playground to code tab

* docs(navigation-secondary): add system tokens to jsdoc

* docs(navigation-secondary): modify required text

* docs(navigation-secondary): fix typo in jsdoc

* docs(playground): added a border around plaground parts

* docs: prefer logical properties

* chore(navigation-secondary): add changeset

* fix(navigation-secondary): remove defaults from system tokens

* docs(navigation-secondary): change path for lightdom to cdn url

* chore(navigation-secondary): update changeset

* fix(navigation-secondary): remove syntax annotations

---------

Co-authored-by: Nikki Massaro Kauffman <nmassaro@redhat.com>
  • Loading branch information
zeroedin and nikkimk committed May 18, 2023
1 parent 68e95a6 commit 4861f8a
Show file tree
Hide file tree
Showing 9 changed files with 182 additions and 185 deletions.
5 changes: 5 additions & 0 deletions .changeset/heavy-cheetahs-bow.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
---
"@rhds/elements": patch
---

`<rh-navigation-secondary>`: corrected css parts and css properties manifest documentation
11 changes: 10 additions & 1 deletion docs/scss/_utility.scss
Original file line number Diff line number Diff line change
Expand Up @@ -71,7 +71,7 @@
margin: 32px 0 16px;
font-size: 18px;
line-height: 25px;

@include breakpoint(lima) {
font-size: 20px;
line-height: 26px;
Expand Down Expand Up @@ -1213,3 +1213,12 @@ ol.example-notes {
counter-increment: list;
}
}

playground-project > *:defined {
border-block-end: var(--rh-border-width-sm, 1px) solid var(--rh-border-subtle-on-light, #C7C7C7);
border-inline-start: var(--rh-border-width-sm, 1px) solid var(--rh-border-subtle-on-light, #C7C7C7);
border-inline-end: var(--rh-border-width-sm, 1px) solid var(--rh-border-subtle-on-light, #C7C7C7);
}
playground-project > *:defined:first-child {
border-block-start: var(--rh-border-width-sm, 1px) solid var(--rh-border-subtle-on-light, #C7C7C7);
}
172 changes: 25 additions & 147 deletions elements/rh-navigation-secondary/demo/rh-navigation-secondary.html
Original file line number Diff line number Diff line change
Expand Up @@ -2,188 +2,66 @@
<link rel="stylesheet" href="../rh-navigation-secondary-lightdom.css">
<script type="module" src="rh-navigation-secondary.js"></script>

<div class="mock-nav"></div>
<rh-navigation-secondary role="navigation">
<a href="#" slot="logo" id="logo-id">
Red Hat Ansible Automation Platform
Logo/Title
</a>
<ul slot="nav" aria-labelledby="logo-id">
<li>
<rh-navigation-secondary-dropdown>
<a href="#" slot="link">Explore</a>
<a href="#dropdown-fallback-url" slot="link">Dropdown</a>
<rh-navigation-secondary-menu slot="menu">
<rh-navigation-secondary-menu-section>
<h2 slot="header" id="ansible-platform">
<a href="#">Why Red Hat Ansible Automation Platforms</a>
</h2>
<ul slot="links" aria-labelledby="ansible-platform"">
<li>
<a href="#">
Integrations
<pf-icon set="patternfly" icon="arrow" size="sm" loading="idle"></pf-icon>
</a>
</li>
<li><a href="#">Custom success stories</a></li>
<li>
<a href="#">
What is ansible
<pf-icon icon="icon-new-window" color="info" size="sm"></pf-icon>
</a>
</li>
<li><a href="#">Why choose Red Hat for automation?</a></li>
<li><a href="#">Edge automation with Red Hat Ansible Automation Platform</a></li>
</ul>
<rh-cta slot="cta">
<a href="#">Section Level CTA</a>
</rh-cta>
</rh-navigation-secondary-menu-section>
<rh-navigation-secondary-menu-section>
<h2 slot="header">
<a href="#">Additional Features</a>
</h2>
<h3 slot="header">Section</h3>
<ul slot="links">
<li><a href="#">Automation execution environments</a></li>
<li><a href="#">Automation controller</a></li>
<li>
<a href="#">
Automation mesh
<pf-icon set="patternfly" icon="arrow" size="sm" loading="idle"></pf-icon>
</a>
</li>
<li><a href="#">Ansible Content Collections</a></li>
<li>
<a href="#">
Automation Hub
<pf-icon set="patternfly" icon="arrow" size="sm" loading="idle"></pf-icon>
</a>
</li>
<li>
<a href="#">
Red Hat Insights for Red Hat Ansible Automation Platform
<pf-icon set="patternfly" icon="arrow" size="sm" loading="idle"></pf-icon>
</a>
</li>
<li>
<a href="#">
Automation services catalog
<pf-icon set="patternfly" icon="arrow" size="sm" loading="idle"></pf-icon>
</a>
</li>
<li>
<a href="#">
Ansible content tools
<pf-icon set="patternfly" icon="arrow" size="sm" loading="idle"></pf-icon>
</a>
</li>
<li><a href="#">Link</a></li>
<li><a href="#">Link</a></li>
<li><a href="#">Link</a></li>
</ul>
<rh-cta slot="cta">
<a href="#">Section Level CTA</a>
<a href="#">Section CTA</a>
</rh-cta>
</rh-navigation-secondary-menu-section>
<rh-navigation-secondary-menu-section>
<h2 slot="header">
<a href="#">Additional Features</a>
</h2>
<h3 slot="header">Section</h3>
<ul slot="links">
<li><a href="#">Automation execution environments</a></li>
<li><a href="#">Automation controller</a></li>
<li>
<a href="#">
Automation mesh
<pf-icon set="patternfly" icon="arrow" size="sm" loading="idle"></pf-icon>
</a>
</li>
<li><a href="#">Ansible Content Collections</a></li>
<li>
<a href="#">
Automation Hub
<pf-icon set="patternfly" icon="arrow" size="sm" loading="idle"></pf-icon>
</a>
</li>
<li>
<a href="#">
Red Hat Insights for Red Hat Ansible Automation Platform
<pf-icon set="patternfly" icon="arrow" size="sm" loading="idle"></pf-icon>
</a>
</li>
<li>
<a href="#">
Automation services catalog
<pf-icon set="patternfly" icon="arrow" size="sm" loading="idle"></pf-icon>
</a>
</li>
<li>
<a href="#">
Ansible content tools
<pf-icon set="patternfly" icon="arrow" size="sm" loading="idle"></pf-icon>
</a>
</li>
<li><a href="#">Link</a></li>
<li><a href="#">Link</a></li>
<li><a href="#">Link</a></li>
</ul>
<rh-cta slot="cta">
<a href="#">Section Level CTA</a>
<a href="#">Section CTA</a>
</rh-cta>
</rh-navigation-secondary-menu-section>
</rh-navigation-secondary-menu>
</rh-navigation-secondary-dropdown>
</li>
<li>
<li>
<rh-navigation-secondary-dropdown>
<a href="#" slot="link">Use cases</a>
<a href="#dropdown-fallback-url" slot="link">Dropdown</a>
<rh-navigation-secondary-menu slot="menu">
<ul>
<li>
<a href="#">
Infrastructure
<pf-icon set="patternfly" icon="arrow" size="sm" loading="idle"></pf-icon>
</a>
</li>
<li>
<a href="#">
Applications
<pf-icon set="patternfly" icon="arrow" size="sm" loading="idle"></pf-icon>
</a>
</li>
<li>
<a href="#">
Networks
<pf-icon set="patternfly" icon="arrow" size="sm" loading="idle"></pf-icon>
</a>
</li>
</ul>
<ul>
<li>
<a href="#">
Containers
<pf-icon set="patternfly" icon="arrow" size="sm" loading="idle"></pf-icon>
</a>
</li>
<li>
<a href="#">
Security
<pf-icon set="patternfly" icon="arrow" size="sm" loading="idle"></pf-icon>
</a>
</li>
<li>
<a href="#">
Cloud
<pf-icon set="patternfly" icon="arrow" size="sm" loading="idle"></pf-icon>
</a>
</li>
<li><a href="#">Link</a></li>
<li><a href="#">Link</a></li>
<li><a href="#">Link</a></li>
<li><a href="#">Link</a></li>
<li><a href="#">Link</a></li>
<li><a href="#">Link</a></li>
</ul>
</rh-navigation-secondary-menu>
</rh-navigation-secondary-dropdown>
</li>
<li><a href="#">Documentation</a></li>
<li><a href="#">Extra Placeholder</a></li>
</li>
<li><a href="#">Link</a></li>
<li><a href="#">Link</a></li>
</ul>
<rh-cta slot="cta">
<a href="#">Get started</a>
<a href="#">Call to Action</a>
</rh-cta>
</rh-navigation-secondary>

<rh-context-provider color-palette="lightest">
<div class="space-holder">
<h2 >Content Placeholder</h2>
<h2>Content Placeholder</h2>
<a href="#">Link placeholder</a>
<p>Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nunc tincidunt luctus odio, vitae accumsan tortor sagittis et. Integer facilisis rutrum suscipit. Morbi elementum purus vel varius tincidunt. Nulla fringilla lacus a nulla vehicula tincidunt. Praesent a turpis et elit laoreet ullamcorper et et metus. Praesent malesuada massa in tellus bibendum congue. Curabitur mollis purus et metus eleifend sagittis. Vivamus fringilla tincidunt sem id euismod. Maecenas a vestibulum nisl. Sed libero metus, ultrices in tortor facilisis, semper rhoncus nunc. Nullam ut diam et felis posuere lobortis vitae id leo. Sed hendrerit ex libero, a faucibus tellus maximus et. Aliquam erat volutpat. Phasellus vestibulum a lacus eget eleifend. Pellentesque ipsum nunc, scelerisque non neque id, bibendum vestibulum ante.</p>
<p>Maecenas venenatis sollicitudin leo, vitae tincidunt lectus dapibus vel. Integer quis sapien dui. Nulla sagittis dapibus suscipit. Pellentesque consequat dapibus lorem id feugiat. Fusce ornare sapien at lacus porta maximus. Praesent gravida faucibus tellus et lobortis. Praesent ullamcorper facilisis semper. Praesent lobortis enim lacus, ut facilisis ex tristique in. Sed lobortis tortor ut sem lacinia pharetra. Nunc a varius risus. Proin volutpat eget justo quis fermentum. Nunc quis vestibulum ipsum. Donec vulputate laoreet sapien id mattis. Phasellus non enim laoreet, euismod mauris vel, vulputate est.</p>
Expand Down
14 changes: 3 additions & 11 deletions elements/rh-navigation-secondary/docs/00-overview.md
Original file line number Diff line number Diff line change
@@ -1,23 +1,15 @@
{% section %}
## Overview

The Secondary navigation is used to connect a series of pages together. It displays wayfinding content and links relevant to the page it is placed on. It should be used in conjunction with the <a href="../navigation-primary">Primary navigation</a>

{{ tagName | getElementDescription }}
{% endsection %}

{% section %}
## Sample component

![Example of an navigation secondary component][secondary-nav-example] {style="margin-block:var(--rh-space-2xl, 32px);--inline-img-max-width: 1000px;"}
{% endsection %}


{% section %}
## Demos
View a live version of this component and see how it can be customized.
{% playground tagName=tagName %}{% endplayground %}
{% cta href="./demo/", target="_blank" %}
View the `<rh-navigation-secondary>` demo in a new tab
For a live example of this component in action, {% cta href="./demo/", target="_blank" %}
view the `<rh-navigation-secondary>` demo in a new tab
{% endcta %}
{% endsection %}

Expand Down
79 changes: 74 additions & 5 deletions elements/rh-navigation-secondary/docs/40-code.md
Original file line number Diff line number Diff line change
@@ -1,9 +1,78 @@
{% renderOverview %}{% endrenderOverview %}
{% renderInstallation %}
~~~html
<link rel="stylesheet" href="https://redhatstatic.com/dx/v1-alpha/@rhds/elements@1.0.2/rh-navigation-secondary/rh-navigation-secondary-lightdom.css">
~~~
Lightdom CSS is required to ensure a reduced [Cumulative Layout Shift (CLS)](https://web.dev/cls/) experience before the component has fully initialized.
{% endrenderInstallation %}

{% renderSlots %}{% endrenderSlots %}
{% section headline="Usage", headingLevel="2" -%}
View a live version of this component and see how it can be customized.
{% playground tagName=tagName %}{% endplayground %}
{% cta href="./demo/", target="_blank" %}
View the `<rh-navigation-secondary>` demo in a new tab
{% endcta %}
{% endsection %}

{% renderAttributes %}{% endrenderAttributes %}
{% section headline="&lt;rh-navigation-secondary&gt;", headingLevel="2" -%}

{% renderMethods %}{% endrenderMethods %}
{% renderSlots for='rh-navigation-secondary', level=3 %}{% endrenderSlots %}

{% renderEvents %}{% endrenderEvents %}
{% renderAttributes for='rh-navigation-secondary', level=3 %}{% endrenderAttributes %}

{% renderMethods for='rh-navigation-secondary', level=3 %}{% endrenderMethods %}

{% renderEvents for='rh-navigation-secondary', level=3 %}{% endrenderEvents %}

{% renderCssParts for='rh-navigation-secondary', level=3 %}{% endrenderCssParts %}

{% renderCssCustomProperties for='rh-navigation-secondary', level=3 %}{% endrenderCssCustomProperties %}
{% endsection %}

{% section headline="&lt;rh-navigation-secondary-dropdown&gt;", headingLevel="2" -%}

{% renderSlots for='rh-navigation-secondary-dropdown', level=3 %}{% endrenderSlots %}

{% renderAttributes for='rh-navigation-secondary-dropdown', level=3 %}{% endrenderAttributes %}

{% renderMethods for='rh-navigation-secondary-dropdown', level=3 %}{% endrenderMethods %}

{% renderEvents for='rh-navigation-secondary-dropdown', level=3 %}{% endrenderEvents %}

{% renderCssParts for='rh-navigation-secondary-dropdown', level=3 %}{% endrenderCssParts %}

{% renderCssCustomProperties for='rh-navigation-secondary-dropdown', level=3 %}{% endrenderCssCustomProperties %}

{% endsection %}

{% section headline="&lt;rh-navigation-secondary-menu&gt;", headingLevel="2" -%}

{% renderSlots for='rh-navigation-secondary-menu', level=3 %}{% endrenderSlots %}

{% renderAttributes for='rh-navigation-secondary-menu', level=3 %}{% endrenderAttributes %}

{% renderMethods for='rh-navigation-secondary-menu', level=3 %}{% endrenderMethods %}

{% renderEvents for='rh-navigation-secondary-menu', level=3 %}{% endrenderEvents %}

{% renderCssParts for='rh-navigation-secondary-menu', level=3 %}{% endrenderCssParts %}

{% renderCssCustomProperties for='rh-navigation-secondary-menu', level=3 %}{% endrenderCssCustomProperties %}

{% endsection %}

{% section headline="&lt;rh-navigation-secondary-menu-section&gt;", headingLevel="2" -%}

{% renderSlots for='rh-navigation-secondary-menu-section', level=3 %}{% endrenderSlots %}

{% renderAttributes for='rh-navigation-secondary-menu-section', level=3 %}{% endrenderAttributes %}

{% renderMethods for='rh-navigation-secondary-menu-section', level=3 %}{% endrenderMethods %}

{% renderEvents for='rh-navigation-secondary-menu-section', level=3 %}{% endrenderEvents %}

{% renderCssParts for='rh-navigation-secondary-menu-section', level=3 %}{% endrenderCssParts %}

{% renderCssCustomProperties for='rh-navigation-secondary-menu-section', level=3 %}{% endrenderCssCustomProperties %}

{% endsection %}
Original file line number Diff line number Diff line change
Expand Up @@ -33,10 +33,17 @@ import styles from './rh-navigation-secondary-dropdown.css';
/**
* @summary A wrapper component to upgrade a top level nav link to include dropdown functionality
*
* @slot link - Link for dropdown, expects `<a>`
* @slot menu - Menu for dropdown, expects `<rh-navigation-secondary-menu>`
* @slot link - Link for dropdown, expects `<a>` element
* @slot menu - Menu for dropdown, expects `<rh-navigation-secondary-menu>` element
*
* @fires { SecondaryNavDropdownExpandEvent } change - Fires when a dropdown is clicked
*
* @cssprop --rh-font-size-body-text-md
* @cssprop --rh-color-text-brand-on-light
* @cssprop --rh-color-border-subtle-on-light
* @cssprop --rh-color-text-primary-on-light
* @cssprop --rh-color-surface-lightest
* @cssprop --rh-box-shadow-sm
**/
@customElement('rh-navigation-secondary-dropdown')
export class RhNavigationSecondaryDropdown extends LitElement {
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -11,11 +11,16 @@ import styles from './rh-navigation-secondary-menu-section.css';
/**
* @summary 'A menu section which auto upgrades header and sibling link list accessibility attributes'
*
* @slot header - Adds a header tag to section, expects `<h1>, <h2>, <h3>, <h4>, <h5>, <h6>`
* @slot links - Adds a ul tag to section, expects `<ul>, <ol>`
* @slot cta - Adds a section level CTA, expects `<rh-cta>`
* @slot header - Adds a header tag to section, expects `<h1> | <h2> | <h3> | <h4> | <h5> | <h6>` element
* @slot links - Adds a ul tag to section, expects `<ul> | <ol>` element
* @slot cta - Adds a section level CTA, expects `<rh-cta>` element
*
* @csspart container - container, <section> element
*
* @cssprop --rh-font-family-heading
* @cssprop --rh-font-size-body-text-md
* @cssprop --rh-space-xl
*
* @csspart base - container, <section> element
**/
@customElement('rh-navigation-secondary-menu-section')
export class RhNavigationSecondaryMenuSection extends LitElement {
Expand Down
Loading

0 comments on commit 4861f8a

Please sign in to comment.