From 9a40ae3b05c75627507323e6aaff3f0bd023b701 Mon Sep 17 00:00:00 2001
From: Tanner Reits <47483144+tanner-reits@users.noreply.github.com>
Date: Mon, 4 Nov 2024 17:24:18 -0500
Subject: [PATCH] docs(): merge feature-8.4 docs (#3877)
* docs(select): add `modal` interface to `ion-select` docs (#3872)
* docs(select): update select docs for modal interface
* fix(select): point playground to correct demo
* feat(segment): add playground & docs for segment view (#3875)
* feat(segment): add playground & docs for segment view
* fix(segment-view): api import version
* fix(segment-content): usage & common API sections
* Force CI run
---
docs/api/segment-content.md | 52 +++++++++++++++++
docs/api/segment-view.md | 40 +++++++++++++
docs/api/segment.md | 16 ++++++
docs/api/select.md | 32 +++++++----
sidebars.js | 2 +-
.../segment/swipeable/angular/angular_css.md | 20 +++++++
.../segment/swipeable/angular/angular_html.md | 18 ++++++
static/usage/v8/segment/swipeable/demo.html | 56 +++++++++++++++++++
static/usage/v8/segment/swipeable/index.md | 29 ++++++++++
.../usage/v8/segment/swipeable/javascript.md | 39 +++++++++++++
.../v8/segment/swipeable/react/react_css.md | 20 +++++++
.../v8/segment/swipeable/react/react_tsx.md | 30 ++++++++++
static/usage/v8/segment/swipeable/vue.md | 50 +++++++++++++++++
.../angular/example_component_html.md | 8 +++
.../angular/example_component_ts.md | 6 ++
.../customization/interface-options/demo.html | 16 ++++++
.../interface-options/javascript.md | 16 ++++++
.../customization/interface-options/react.md | 14 +++++
.../customization/interface-options/vue.md | 15 +++++
.../v8/select/interfaces/modal/angular.md | 11 ++++
.../v8/select/interfaces/modal/demo.html | 30 ++++++++++
.../usage/v8/select/interfaces/modal/index.md | 13 +++++
.../v8/select/interfaces/modal/javascript.md | 11 ++++
.../usage/v8/select/interfaces/modal/react.md | 18 ++++++
.../usage/v8/select/interfaces/modal/vue.md | 22 ++++++++
25 files changed, 573 insertions(+), 11 deletions(-)
create mode 100644 docs/api/segment-content.md
create mode 100644 docs/api/segment-view.md
create mode 100644 static/usage/v8/segment/swipeable/angular/angular_css.md
create mode 100644 static/usage/v8/segment/swipeable/angular/angular_html.md
create mode 100644 static/usage/v8/segment/swipeable/demo.html
create mode 100644 static/usage/v8/segment/swipeable/index.md
create mode 100644 static/usage/v8/segment/swipeable/javascript.md
create mode 100644 static/usage/v8/segment/swipeable/react/react_css.md
create mode 100644 static/usage/v8/segment/swipeable/react/react_tsx.md
create mode 100644 static/usage/v8/segment/swipeable/vue.md
create mode 100644 static/usage/v8/select/interfaces/modal/angular.md
create mode 100644 static/usage/v8/select/interfaces/modal/demo.html
create mode 100644 static/usage/v8/select/interfaces/modal/index.md
create mode 100644 static/usage/v8/select/interfaces/modal/javascript.md
create mode 100644 static/usage/v8/select/interfaces/modal/react.md
create mode 100644 static/usage/v8/select/interfaces/modal/vue.md
diff --git a/docs/api/segment-content.md b/docs/api/segment-content.md
new file mode 100644
index 00000000000..3c17b07eceb
--- /dev/null
+++ b/docs/api/segment-content.md
@@ -0,0 +1,52 @@
+---
+title: "ion-segment-content"
+---
+
+import Props from '@ionic-internal/component-api/v8/segment-content/props.md';
+import Events from '@ionic-internal/component-api/v8/segment-content/events.md';
+import Methods from '@ionic-internal/component-api/v8/segment-content/methods.md';
+import Parts from '@ionic-internal/component-api/v8/segment-content/parts.md';
+import CustomProps from '@ionic-internal/component-api/v8/segment-content/custom-props.mdx';
+import Slots from '@ionic-internal/component-api/v8/segment-content/slots.md';
+
+
+ ion-segment-content: Display control element for swipeable segments
+
+
+
+import EncapsulationPill from '@components/page/api/EncapsulationPill';
+
+
+
+Segment content is a wrapper element used to control the display of child elements when using swipeable segments. Segment content elements are children of a single
+[segment view](./segment-view.md) instance that is linked to a [segment](./segment.md). See our [swipeable segments](./segment.md#swipeable-segments) documentation
+for more information on how to use segment contents.
+
+## Usage
+
+Each `ion-segment-content` needs a unique `id` attribute. This will be used to link the segment content to a segment button via the button's
+[contentId property](./segment-button.md#properties).
+
+
+
+import Swipeable from '@site/static/usage/v8/segment/swipeable/index.md';
+
+
+
+## Properties
+
+
+## Events
+
+
+## Methods
+
+
+## CSS Shadow Parts
+
+
+## CSS Custom Properties
+
+
+## Slots
+
\ No newline at end of file
diff --git a/docs/api/segment-view.md b/docs/api/segment-view.md
new file mode 100644
index 00000000000..5d0054c4ff8
--- /dev/null
+++ b/docs/api/segment-view.md
@@ -0,0 +1,40 @@
+---
+title: "ion-segment-view"
+---
+
+import Props from '@ionic-internal/component-api/v8/segment-view/props.md';
+import Events from '@ionic-internal/component-api/v8/segment-view/events.md';
+import Methods from '@ionic-internal/component-api/v8/segment-view/methods.md';
+import Parts from '@ionic-internal/component-api/v8/segment-view/parts.md';
+import CustomProps from '@ionic-internal/component-api/v8/segment-view/custom-props.mdx';
+import Slots from '@ionic-internal/component-api/v8/segment-view/slots.md';
+
+
+ ion-segment-view: Controller element for swipeable segments
+
+
+
+import EncapsulationPill from '@components/page/api/EncapsulationPill';
+
+
+
+Segment view is a wrapper element that links a group of [segment contents](./segment-content.md) to a [segment](./segment.md) when using swipeable segments.
+See our [swipeable segments](./segment.md#swipeable-segments) documentation for more information on how to use segment views.
+
+## Properties
+
+
+## Events
+
+
+## Methods
+
+
+## CSS Shadow Parts
+
+
+## CSS Custom Properties
+
+
+## Slots
+
\ No newline at end of file
diff --git a/docs/api/segment.md b/docs/api/segment.md
index 9fe74f7a326..f07a1a1a5a4 100644
--- a/docs/api/segment.md
+++ b/docs/api/segment.md
@@ -49,6 +49,22 @@ import Toolbar from '@site/static/usage/v8/toolbar/segments/index.md';
+## Swipeable Segments
+
+Each [segment button](./segment-button.md) can be associated with a [segment content](./segment-content.md) element that will be displayed
+when the segment is active. With this approach, each segment's content can be swiped or scrolled between and the segment will be updated
+to reflect the currently visible content.
+
+:::warning
+If no initial `value` is assigned to the `ion-segment` when using swipeable segments, the segment will default to the value of the first segment button.
+
+Segment buttons cannot be disabled when used with swipeable segments.
+:::
+
+import Swipeable from '@site/static/usage/v8/segment/swipeable/index.md';
+
+
+
## Theming
### Colors
diff --git a/docs/api/select.md b/docs/api/select.md
index 7f74734bde9..8a310608fce 100644
--- a/docs/api/select.md
+++ b/docs/api/select.md
@@ -70,7 +70,7 @@ import SingleSelectionExample from '@site/static/usage/v8/select/basic/single-se
## Multiple Selection
-By adding the `multiple` attribute to select, users are able to select multiple options. When multiple options can be selected, the alert or popover overlay presents users with a checkbox styled list of options. The select component's value receives an array of all of the selected option values.
+By adding the `multiple` attribute to select, users are able to select multiple options. When multiple options can be selected, the alert, popover, or modal overlay presents users with a checkbox styled list of options. The select component's value receives an array of all of the selected option values.
:::note
@@ -86,7 +86,7 @@ import MultipleSelectionExample from '@site/static/usage/v8/select/basic/multipl
## Interfaces
-By default, select uses [ion-alert](alert.md) to open up the overlay of options in an alert. The interface can be changed to use [ion-action-sheet](action-sheet.md) or [ion-popover](popover.md) by passing `action-sheet` or `popover`, respectively, to the `interface` property. Read on to the other sections for the limitations of the different interfaces.
+By default, select uses [ion-alert](alert.md) to open up the overlay of options in an alert. The interface can be changed to use [ion-action-sheet](action-sheet.md), [ion-popover](popover.md), or [ion-modal](modal.md) by passing `action-sheet`, `popover`, or `modal`, respectively, to the `interface` property. Read on to the other sections for the limitations of the different interfaces.
### Alert
@@ -107,6 +107,12 @@ import PopoverExample from '@site/static/usage/v8/select/interfaces/popover/inde
+### Modal
+
+import ModalExample from '@site/static/usage/v8/select/interfaces/modal/index.md';
+
+
+
## Responding to Interaction
The main ways of handling user interaction with the select are the `ionChange`, `ionDismiss`, and `ionCancel` events. See [Events](#events) for more details on these and other events that select fires.
@@ -161,15 +167,19 @@ The alert supports two buttons: `Cancel` and `OK`. Each button's text can be cus
The `action-sheet` and `popover` interfaces do not have an `OK` button, clicking on any of the options will automatically close the overlay and select that value. The `popover` interface does not have a `Cancel` button, clicking on the backdrop will close the overlay.
+The `modal` interface has a single `Close` button in the header. This button is only responsible for dismissing the modal. Any selections made will persist
+after clicking this button or if the modal is dismissed using an alternative method.
+
import ButtonTextExample from '@site/static/usage/v8/select/customization/button-text/index.md';
## Interface Options
-Since select uses the alert, action sheet and popover interfaces, options can be passed to these components through the `interfaceOptions` property. This can be used to pass a custom header, subheader, css class, and more.
+Since select uses the alert, action sheet, popover, and modal interfaces, options can be passed to these components through the `interfaceOptions` property. This can be used to pass a custom header, subheader, css class, and more.
-See the [ion-alert docs](alert.md), [ion-action-sheet docs](action-sheet.md), and [ion-popover docs](popover.md) for the properties that each interface accepts.
+See the [ion-alert docs](alert.md), [ion-action-sheet docs](action-sheet.md), [ion-popover docs](popover.md), and [ion-modal docs](modal.md)
+for the properties that each interface accepts.
Note: `interfaceOptions` will not override `inputs` or `buttons` with the `alert` interface.
@@ -207,11 +217,13 @@ import StylingSelectExample from '@site/static/usage/v8/select/customization/sty
### Styling Select Interface
-Customizing the interface dialog should be done by following the Customization section in that interface's documentation:
+Customizing the interface dialog should be done by following the styling sections (CSS shadow parts, CSS custom properties, and slots) in
+that interface's documentation:
-- [Alert Customization](alert.md#customization)
-- [Action Sheet Customization](action-sheet.md#customization)
-- [Popover Customization](popover.md#customization)
+- [Alert](alert.md#css-shadow-parts)
+- [Action Sheet](action-sheet.md#css-shadow-parts)
+- [Popover](popover.md#css-shadow-parts)
+- [Modal](modal.md#css-shadow-parts)
However, the Select Option does set a class for easier styling and allows for the ability to pass a class to the overlay option, see the [Select Options documentation](select-option.md) for usage examples of customizing options.
@@ -304,7 +316,7 @@ These keyboard interactions apply to all `ion-select` elements when the followin
Single selection keyboard interaction follows the [ARIA implementation patterns of a radio](https://www.w3.org/WAI/ARIA/apg/patterns/radio/).
-These keyboard interactions apply to `ion-action-sheet`, `ion-alert`, and `ion-popover` elements when the overlay is presented and focused.
+These keyboard interactions apply to `ion-action-sheet`, `ion-alert`, `ion-popover`, and `ion-modal` elements when the overlay is presented and focused.
| Key | Description |
| --------------------- | ------------------------------------------------------------ |
@@ -321,7 +333,7 @@ These keyboard interactions apply to `ion-action-sheet`, `ion-alert`, and `ion-p
Multiple selection keyboard interaction follows the [ARIA implementation patterns of a checkbox](https://www.w3.org/WAI/ARIA/apg/patterns/checkbox/).
-These keyboard interactions apply to `ion-alert` and `ion-popover` elements when the overlay is presented and multiple selection is enabled.
+These keyboard interactions apply to `ion-alert`, `ion-popover`, and `ion-modal` elements when the overlay is presented and multiple selection is enabled.
| Key | Description |
| ------------------ | ------------------------------------------------------------ |
diff --git a/sidebars.js b/sidebars.js
index 5b125c92e04..5af37c7fce2 100644
--- a/sidebars.js
+++ b/sidebars.js
@@ -450,7 +450,7 @@ module.exports = {
type: 'category',
label: 'Segment',
collapsed: false,
- items: ['api/segment', 'api/segment-button'],
+ items: ['api/segment', 'api/segment-button', 'api/segment-content', 'api/segment-view'],
},
{
type: 'category',
diff --git a/static/usage/v8/segment/swipeable/angular/angular_css.md b/static/usage/v8/segment/swipeable/angular/angular_css.md
new file mode 100644
index 00000000000..dd13ba75999
--- /dev/null
+++ b/static/usage/v8/segment/swipeable/angular/angular_css.md
@@ -0,0 +1,20 @@
+```css
+ion-segment-view {
+ height: 150px;
+}
+
+ion-segment-content {
+ display: flex;
+ align-items: center;
+ justify-content: center;
+}
+ion-segment-content:nth-of-type(1) {
+ background: lightpink;
+}
+ion-segment-content:nth-of-type(2) {
+ background: lightblue;
+}
+ion-segment-content:nth-of-type(3) {
+ background: lightgreen;
+}
+```
diff --git a/static/usage/v8/segment/swipeable/angular/angular_html.md b/static/usage/v8/segment/swipeable/angular/angular_html.md
new file mode 100644
index 00000000000..0d372f239c5
--- /dev/null
+++ b/static/usage/v8/segment/swipeable/angular/angular_html.md
@@ -0,0 +1,18 @@
+```html
+
+
+ First
+
+
+ Second
+
+
+ Third
+
+
+
+ First
+ Second
+ Third
+
+```
diff --git a/static/usage/v8/segment/swipeable/demo.html b/static/usage/v8/segment/swipeable/demo.html
new file mode 100644
index 00000000000..cd7b789a00e
--- /dev/null
+++ b/static/usage/v8/segment/swipeable/demo.html
@@ -0,0 +1,56 @@
+
+
+
+
+
+ Segment - Swipeable
+
+
+
+
+
+
+
+
+
+
+
+
+
+ First
+
+
+ Second
+
+
+ Third
+
+
+
+ First
+ Second
+ Third
+
+
+
+
+
diff --git a/static/usage/v8/segment/swipeable/index.md b/static/usage/v8/segment/swipeable/index.md
new file mode 100644
index 00000000000..e19de64f789
--- /dev/null
+++ b/static/usage/v8/segment/swipeable/index.md
@@ -0,0 +1,29 @@
+import Playground from '@site/src/components/global/Playground';
+
+import javascript from './javascript.md';
+import react_main_tsx from './react/react_tsx.md';
+import react_main_css from './react/react_css.md';
+import vue from './vue.md';
+import angular_html from './angular/angular_html.md';
+import angular_css from './angular/angular_css.md';
+
+
diff --git a/static/usage/v8/segment/swipeable/javascript.md b/static/usage/v8/segment/swipeable/javascript.md
new file mode 100644
index 00000000000..01308f07a94
--- /dev/null
+++ b/static/usage/v8/segment/swipeable/javascript.md
@@ -0,0 +1,39 @@
+```html
+
+
+ First
+
+
+ Second
+
+
+ Third
+
+
+
+ First
+ Second
+ Third
+
+
+
+```
diff --git a/static/usage/v8/segment/swipeable/react/react_css.md b/static/usage/v8/segment/swipeable/react/react_css.md
new file mode 100644
index 00000000000..dd13ba75999
--- /dev/null
+++ b/static/usage/v8/segment/swipeable/react/react_css.md
@@ -0,0 +1,20 @@
+```css
+ion-segment-view {
+ height: 150px;
+}
+
+ion-segment-content {
+ display: flex;
+ align-items: center;
+ justify-content: center;
+}
+ion-segment-content:nth-of-type(1) {
+ background: lightpink;
+}
+ion-segment-content:nth-of-type(2) {
+ background: lightblue;
+}
+ion-segment-content:nth-of-type(3) {
+ background: lightgreen;
+}
+```
diff --git a/static/usage/v8/segment/swipeable/react/react_tsx.md b/static/usage/v8/segment/swipeable/react/react_tsx.md
new file mode 100644
index 00000000000..e571d9c793e
--- /dev/null
+++ b/static/usage/v8/segment/swipeable/react/react_tsx.md
@@ -0,0 +1,30 @@
+```tsx
+import React from 'react';
+import { IonLabel, IonSegment, IonSegmentButton, IonSegmentContent, IonSegmentView } from '@ionic/react';
+
+import './main.css';
+
+function Example() {
+ return (
+ <>
+
+
+ First
+
+
+ Second
+
+
+ Third
+
+
+
+ First
+ Second
+ Third
+
+
+ );
+}
+export default Example;
+```
diff --git a/static/usage/v8/segment/swipeable/vue.md b/static/usage/v8/segment/swipeable/vue.md
new file mode 100644
index 00000000000..ea28874f811
--- /dev/null
+++ b/static/usage/v8/segment/swipeable/vue.md
@@ -0,0 +1,50 @@
+```html
+
+
+
+ First
+
+
+ Second
+
+
+ Third
+
+
+
+ First
+ Second
+ Third
+
+
+
+
+
+
+```
diff --git a/static/usage/v8/select/customization/interface-options/angular/example_component_html.md b/static/usage/v8/select/customization/interface-options/angular/example_component_html.md
index f459af75729..34316637911 100644
--- a/static/usage/v8/select/customization/interface-options/angular/example_component_html.md
+++ b/static/usage/v8/select/customization/interface-options/angular/example_component_html.md
@@ -28,5 +28,13 @@
Blue
+
+
+
+ Reese's
+ Snickers
+ Twix
+
+
```
diff --git a/static/usage/v8/select/customization/interface-options/angular/example_component_ts.md b/static/usage/v8/select/customization/interface-options/angular/example_component_ts.md
index c3f34d0adaf..5f8bc6929ca 100644
--- a/static/usage/v8/select/customization/interface-options/angular/example_component_ts.md
+++ b/static/usage/v8/select/customization/interface-options/angular/example_component_ts.md
@@ -23,5 +23,11 @@ export class ExampleComponent {
header: 'Colors',
subHeader: 'Select your favorite color',
};
+
+ customModalOptions = {
+ header: 'Favorite Candy',
+ breakpoints: [0, 0.5],
+ initialBreakpoint: 0.5,
+ };
}
```
diff --git a/static/usage/v8/select/customization/interface-options/demo.html b/static/usage/v8/select/customization/interface-options/demo.html
index 5530c9bb72c..5b861edbeb7 100644
--- a/static/usage/v8/select/customization/interface-options/demo.html
+++ b/static/usage/v8/select/customization/interface-options/demo.html
@@ -49,6 +49,14 @@
Blue
+
+
+
+ Reese's
+ Snickers
+ Twix
+
+
@@ -78,6 +86,14 @@
subHeader: 'Select your favorite color',
};
customActionSheetSelect.interfaceOptions = customActionSheetOptions;
+
+ const customModalSelect = document.getElementById('customModalSelect');
+ const customModalOptions = {
+ header: 'Favorite Candy',
+ breakpoints: [0, 0.5],
+ initialBreakpoint: 0.5,
+ };
+ customModalSelect.interfaceOptions = customModalOptions;