Merge branch 'mdx-pt-1' of github.com:ionic-team/ionic-docs into mdx-…

…pt-3

_templates/README.md

@@ -21,12 +21,12 @@ If you need a component for multiple versions of Ionic Framework, you (currently
 
 ## Usage
 
-Once you've generated your playground, you need to add it to the main markdown file in the docs (e.g. [docs/api/button.md](../docs/api/button.md)) by doing something similar to the following example:
+Once you've generated your playground, you need to add it to the main markdown file in the docs (e.g. [docs/api/button.md](../docs/api/button.mdx)) by doing something similar to the following example:
 
 ```
 ## Feature
 
-import Feature from '@site/static/usage/v7/button/feature/index.md';
+import Feature from '@site/static/usage/v8/button/feature/index.md';
 
 <Feature />
 ```

_templates/playground/new/demo.html.ejs.t

@@ -8,8 +8,8 @@ to: "<%= `static/usage/v${version}/${name}/${path}/demo.html` %>"
     <meta charset="UTF-8" />
     <meta name="viewport" content="width=device-width, initial-scale=1.0" />
     <title><%= h.changeCase.titleCase(name) %></title>
-    <link rel="stylesheet" href="<%= directoryChanges %>../../../common.css" />
-    <script src="<%= directoryChanges %>../../../common.js"></script>
+    <link rel="stylesheet" href="<%= directoryChanges %>../../common.css" />
+    <script src="<%= directoryChanges %>../../common.js"></script>
     <script type="module" src="https://cdn.jsdelivr.net/npm/@ionic/core@<%= version %>/dist/ionic/ionic.esm.js"></script>
     <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@ionic/core@<%= version %>/css/ionic.bundle.css" /><% if (css){ %>
 

_templates/playground/new/index.js

@@ -54,8 +54,8 @@ module.exports = {
               type: 'select',
               name: 'version',
               message: 'Select the Ionic Framework version for the playground',
-              initial: '7',
-              choices: ['6', '7'],
+              initial: '8',
+              choices: ['6', '7', '8'],
             },
             {
               type: 'toggle',
@@ -77,7 +77,7 @@ module.exports = {
 
             const playgroundName = changeCase.pascal(answers.path.split('/').pop());
             console.log(
-              `\nTo use this playground in a docs markdown file, include\nthe following:\n\n## ${playgroundName}\n\nimport ${playgroundName} from '@site/static/usage/v7/${answers.name}/${answers.path}/index.md';\n\n<${playgroundName} />\n`
+              `\nTo use this playground in a docs markdown file, include\nthe following:\n\n## ${playgroundName}\n\nimport ${playgroundName} from '@site/static/usage/v${answers.version}/${answers.name}/${answers.path}/index.md';\n\n<${playgroundName} />\n`
             );
 
             return answers;

cspell-wordlist.txt

@@ -12,6 +12,7 @@ Swiper
 Udemy
 Vetur
 Wistia
+WCAG
 
 actionsheet
 fabs

docs/angular/slides.mdx

@@ -102,7 +102,7 @@ The `ion-slides` component had additional styling that helped create a native lo
 ```css
 swiper-container {
   --swiper-pagination-bullet-inactive-color: var(--ion-color-step-200, #cccccc);
-  --swiper-pagination-color: var(--ion-color-primary, #3880ff);
+  --swiper-pagination-color: var(--ion-color-primary, #0054e9);
   --swiper-pagination-progressbar-bg-color: rgba(var(--ion-text-color-rgb, 0, 0, 0), 0.25);
   --swiper-scrollbar-bg-color: rgba(var(--ion-text-color-rgb, 0, 0, 0), 0.1);
   --swiper-scrollbar-drag-bg-color: rgba(var(--ion-text-color-rgb, 0, 0, 0), 0.5);

docs/api/accordion-group.mdx

@@ -0,0 +1,59 @@
+---
+title: "ion-accordion-group"
+---
+import Props from '@ionic-internal/component-api/v8/accordion-group/props.md';
+import Events from '@ionic-internal/component-api/v8/accordion-group/events.md';
+import Methods from '@ionic-internal/component-api/v8/accordion-group/methods.md';
+import Parts from '@ionic-internal/component-api/v8/accordion-group/parts.md';
+import CustomProps from '@ionic-internal/component-api/v8/accordion-group/custom-props.md';
+import Slots from '@ionic-internal/component-api/v8/accordion-group/slots.md';
+
+import EncapsulationPill from '@components/page/api/EncapsulationPill';
+
+<EncapsulationPill type="shadow" />
+
+Accordion group is a container for accordion instances. It manages the state of the accordions and provides keyboard navigation.
+
+See the [Accordion](./accordion) documentation for more information.
+
+
+## Interfaces
+
+### AccordionGroupChangeEventDetail
+
+```typescript
+interface AccordionGroupChangeEventDetail<T = any> {
+  value: T;
+}
+```
+
+### AccordionGroupCustomEvent
+
+While not required, this interface can be used in place of the `CustomEvent` interface for stronger typing with Ionic events emitted from this component.
+
+```typescript
+interface AccordionGroupCustomEvent<T = any> extends CustomEvent {
+  detail: AccordionGroupChangeEventDetail<T>;
+  target: HTMLIonAccordionGroupElement;
+}
+```
+
+
+
+## Properties
+<Props />
+
+## Events
+<Events />
+
+## Methods
+<Methods />
+
+## CSS Shadow Parts
+<Parts />
+
+## CSS Custom Properties
+<CustomProps />
+
+## Slots
+<Slots />

docs/api/accordion.mdx

@@ -0,0 +1,217 @@
+---
+title: "ion-accordion"
+---
+import Props from '@ionic-internal/component-api/v8/accordion/props.md';
+import Events from '@ionic-internal/component-api/v8/accordion/events.md';
+import Methods from '@ionic-internal/component-api/v8/accordion/methods.md';
+import Parts from '@ionic-internal/component-api/v8/accordion/parts.md';
+import CustomProps from '@ionic-internal/component-api/v8/accordion/custom-props.md';
+import Slots from '@ionic-internal/component-api/v8/accordion/slots.md';
+
+<head>
+  <title>ion-accordion: Accordion Components: How to Build & Examples</title>
+  <meta name="description" content="Ion-accordion components provide collapsible sections in content to reduce vertical space and organize information. Learn how to build one and see examples." />
+</head>
+
+import EncapsulationPill from '@components/page/api/EncapsulationPill';
+
+<EncapsulationPill type="shadow" />
+
+
+Accordions provide collapsible sections in your content to reduce vertical space while providing a way of organizing and grouping information. All `ion-accordion` components should be grouped inside `ion-accordion-group` components.
+
+## Basic Usage
+
+import Basic from '@site/static/usage/v8/accordion/basic/index.md';
+
+<Basic />
+
+## Toggle Accordions
+
+Which accordion is open is controlled by setting the `value` property on `ion-accordion-group`. Setting this property allows developers to programmatically expand or collapse certain accordions.
+
+import Toggle from '@site/static/usage/v8/accordion/toggle/index.md';
+
+<Toggle />
+
+## Listen for Accordion State Changes
+
+:::caution
+Most `ionChange` events emitted by other components such as [Input](./input) and [Textarea](./textarea) bubble. As a result, these events will bubble up and cause your `ionChange` listener on the Accordion Group to fire if the associated components are used inside of an Accordion.
+
+When using other components that emit `ionChange` inside of Accordion it is recommended to have the `ionChange` callback on Accordion Group check the `target` key on the event passed to the callback to verify that `ionChange` is coming from the Accordion Group and not any descendants.
+:::
+
+Developers can listen for the `ionChange` event to be notified when accordions expand or collapse.
+
+import ListenChanges from '@site/static/usage/v8/accordion/listen-changes/index.md';
+
+<ListenChanges />
+
+## Multiple Accordions
+
+Developers can allow multiple accordions to be open at once with the `multiple` property.
+
+import Multiple from '@site/static/usage/v8/accordion/multiple/index.md';
+
+<Multiple />
+
+## Disabling Accordions
+
+### Individual Accordion
+
+Individual accordions can be disabled with the `disabled` property on `ion-accordion`.
+
+import DisableIndividual from '@site/static/usage/v8/accordion/disable/individual/index.md';
+
+<DisableIndividual />
+
+### Accordion Group
+
+The accordion group can be disabled with the `disabled` property on `ion-accordion-group`.
+
+import DisableGroup from '@site/static/usage/v8/accordion/disable/group/index.md';
+
+<DisableGroup />
+
+## Readonly Accordions
+
+### Individual Accordion
+
+Individual accordions can be disabled with the `readonly` property on `ion-accordion`.
+
+import ReadonlyIndividual from '@site/static/usage/v8/accordion/readonly/individual/index.md';
+
+<ReadonlyIndividual />
+
+### Accordion Group
+
+The accordion group can be disabled with the `readonly` property on `ion-accordion-group`.
+
+import ReadonlyGroup from '@site/static/usage/v8/accordion/readonly/group/index.md';
+
+<ReadonlyGroup />
+
+## Anatomy
+
+### Header
+
+The `header` slot is used as the toggle that will expand or collapse your accordion. We recommend you use an `ion-item` here to take advantage of the accessibility and theming functionalities.
+
+When using `ion-item` in the `header` slot, the `ion-item`'s `button` prop is set to `true` and the `detail` prop is set to `false`. In addition, we will also automatically add a toggle icon to the `ion-item`. This icon will automatically be rotated when you expand or collapse the accordion. See [Customizing Icons](#icons) for more information.
+
+### Content
+
+The `content` slot is used as the part of the accordion that is revealed or hidden depending on the state of your accordion. You can place anything here except for another `ion-content` instance as only one instance of `ion-content` should be added per page.
+
+## Customization
+
+### Expansion Styles
+
+There are two built in expansion styles: `compact` and `inset`. This expansion style is set via the `expand` property on `ion-accordion-group`.
+
+When `expand="inset"`, the accordion group is given a border radius. On `md` mode, the entire accordion will shift down when it is opened.
+
+import ExpansionStyles from '@site/static/usage/v8/accordion/customization/expansion-styles/index.md';
+
+<ExpansionStyles />
+
+### Advanced Expansion Styles
+
+You can customize the expansion behavior by styling based on the accordion's state. There are four state classes applied to `ion-accordion`. Styling using these classes can allow you to create advanced state transitions:
+
+| Class Name | Description |
+| ---------- | ----------- |
+| `.accordion-expanding` | Applied when the accordion is actively expanding |
+| `.accordion-expanded` | Applied when the accordion is fully expanded |
+| `.accordion-collapsing` | Applied when the accordion is actively collapsing |
+| `.accordion-collapsed` | Applied when the accordion is fully collapsed |
+
+If you need to target specific pieces of the accordion, we recommend targeting the element directly. For example, if you want to customize the ion-item in your header slot when the accordion is expanded, you can use the following selector:
+
+```css
+ion-accordion.accordion-expanding ion-item[slot="header"],
+ion-accordion.accordion-expanded ion-item[slot="header"] {
+  --color: red;
+}
+```
+
+import AdvancedExpansionStyles from '@site/static/usage/v8/accordion/customization/advanced-expansion-styles/index.md';
+
+<AdvancedExpansionStyles />
+
+### Icons
+
+When using an `ion-item` in the `header` slot, we automatically add an `ion-icon`. The type of icon used can be controlled by the `toggleIcon` property, and the slot it is added to can be controlled with the `toggleIconSlot` property.
+
+If you would like to manage the icon yourself or use an icon that is not an `ion-icon`, you can add the `ion-accordion-toggle-icon` class to the icon element.
+
+Regardless of which option you choose, the icon will automatically be rotated when you expand or collapse the accordion.
+
+import Icons from '@site/static/usage/v8/accordion/customization/icons/index.md';
+
+<Icons />
+
+### Theming
+
+Since `ion-accordion` acts as a shell around the header and content elements, you can easily theme the accordion however you would like. You can theme the header by targeting the slotted `ion-item`. Since you are using `ion-item`, you also have access to all of the [ion-item CSS Variables](./item#css-custom-properties) and [ion-item Shadow Parts](./item#css-shadow-parts). Theming the content is also easily achieved by targeting the element that is in the `content` slot.
+
+import Theming from '@site/static/usage/v8/accordion/customization/theming/index.md';
+
+<Theming />
+
+## Accessibility
+
+### Animations
+
+By default, animations are enabled when expanding or collapsing an accordion item. Animations will be automatically disabled when the `prefers-reduced-motion` media query is supported and set to `reduce`. For browsers that do not support this, animations can be disabled by setting the `animated` config in your Ionic Framework app.
+
+import AccessibilityAnimations from '@site/static/usage/v8/accordion/accessibility/animations/index.md';
+
+<AccessibilityAnimations />
+
+### Keyboard Navigation
+
+When used inside an `ion-accordion-group`, `ion-accordion` has full keyboard support for interacting with the component. The following table details what each key does:
+
+| Key                | Function                                                     |
+| ------------------ | ------------------------------------------------------------ |
+| `Space` or `Enter` | When focus is on the accordion header, the accordion will collapse or expand depending on the state of the component. |
+| `Tab`              | Moves focus to the next focusable element.                   |
+| `Shift` + `Tab`    | Moves focus to the previous focusable element.               |
+| `Down Arrow`       | - When focus is on an accordion header, moves focus to the next accordion header.  <br />- When focus is on the last accordion header, moves focus to the first accordion header. |
+| `Up Arrow`         | - When focus is on an accordion header, moves focus to the previous accordion header.  <br />- When focus is on the first accordion header, moves focus to the last accordion header. |
+| `Home`             | When focus is on an accordion header, moves focus to the first accordion header. |
+| `End`              | When focus is on an accordion header, moves focus to the last accordion header. |
+
+## Performance
+
+### Animations
+
+The accordion animation works by knowing the height of the `content` slot when the animation starts. The accordion expects that this height will remain consistent throughout the animation. As a result, developers should avoid performing any operation that may change the height of the content during the animation.
+
+For example, using [ion-img](./img) may cause layout shifts as it lazily loads images. This means that as the animation plays, `ion-img` will load the image data, and the dimensions of  `ion-img` will change to account for the loaded image data. This can result in the height of the `content` slot changing. Developers have a few options for avoiding this:
+
+1. Use an `img` element without any lazy loading. `ion-img` always uses lazy loading, but `img` does not use lazy loading by default. This is the simplest option and works well if you have small images that do not significantly benefit from lazy loading.
+
+2. Set a minimum width and height on `ion-img`. If you need to use lazy loading and know the dimensions of the images ahead of time (such as if you are loading icons of the same size), you can set the `ion-img` to have a minimum width or height using CSS. This gives developers the benefit of lazy loading while avoiding layout shifts. This works when using an `img` element with `loading="lazy"` too!
+
+3. If neither of these options are applicable, developers may want to consider disabling animations altogether by using the `animated` property on [ion-accordion-group](./accordion-group).
+
+## Properties
+<Props />
+
+## Events
+<Events />
+
+## Methods
+<Methods />
+
+## CSS Shadow Parts
+<Parts />
+
+## CSS Custom Properties
+<CustomProps />
+
+## Slots
+<Slots />