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
ionic-team · Nov 4, 2024 · 1b41f05 · 1b41f05
1 parent 776d6af
commit 1b41f05
Show file tree

Hide file tree

Showing 12 changed files with 371 additions and 1 deletion.
diff --git a/docs/api/segment-content.md 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';
+
+<head>
+  <title>ion-segment-content: Display control element for swipeable segments</title>
+  <meta name="description" content="ion-segment-contents are wrapper elements used to control the display of child elements when using swipeable segments." />
+</head>
+
+import EncapsulationPill from '@components/page/api/EncapsulationPill';
+
+<EncapsulationPill type="shadow" />
+
+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).
+
+<!-- Reuse swipeable segments playground -->
+
+import Swipeable from '@site/static/usage/v8/segment/swipeable/index.md';
+
+<Swipeable />
+
+## Properties
+<Props />
+
+## Events
+<Events />
+
+## Methods
+<Methods />
+
+## CSS Shadow Parts
+<Parts />
+
+## CSS Custom Properties
+<CustomProps />
+
+## Slots
+<Slots />
diff --git a/docs/api/segment-view.md 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';
+
+<head>
+  <title>ion-segment-view: Controller element for swipeable segments</title>
+  <meta name="description" content="ion-segment-views are wrapper elements that link a group of segment contents to a segment" />
+</head>
+
+import EncapsulationPill from '@components/page/api/EncapsulationPill';
+
+<EncapsulationPill type="shadow" />
+
+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
+<Props />
+
+## Events
+<Events />
+
+## Methods
+<Methods />
+
+## CSS Shadow Parts
+<Parts />
+
+## CSS Custom Properties
+<CustomProps />
+
+## Slots
+<Slots />
diff --git 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';
 <Toolbar />
 
 
+## 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';
+
+<Swipeable />
+
 ## Theming
 
 ### Colors

diff --git 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
@@ -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
@@ -0,0 +1,18 @@
+```html
+<ion-segment>
+  <ion-segment-button value="first" content-id="first">
+    <ion-label>First</ion-label>
+  </ion-segment-button>
+  <ion-segment-button value="second" content-id="second">
+    <ion-label>Second</ion-label>
+  </ion-segment-button>
+  <ion-segment-button value="third" content-id="third">
+    <ion-label>Third</ion-label>
+  </ion-segment-button>
+</ion-segment>
+<ion-segment-view>
+  <ion-segment-content id="first">First</ion-segment-content>
+  <ion-segment-content id="second">Second</ion-segment-content>
+  <ion-segment-content id="third">Third</ion-segment-content>
+</ion-segment-view>
+```
diff --git a/static/usage/v8/segment/swipeable/demo.html b/static/usage/v8/segment/swipeable/demo.html
@@ -0,0 +1,56 @@
+<!DOCTYPE html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>Segment - Swipeable</title>
+    <link rel="stylesheet" href="../../common.css" />
+    <script src="../../common.js"></script>
+    <script type="module" src="https://cdn.jsdelivr.net/npm/@ionic/core@8/dist/ionic/ionic.esm.js"></script>
+    <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@ionic/core@8/css/ionic.bundle.css" />
+
+    <style>
+      ion-segment-view {
+        height: 168px;
+      }
+
+      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;
+      }
+    </style>
+  </head>
+
+  <body>
+    <ion-app>
+      <ion-content>
+        <ion-segment>
+          <ion-segment-button value="first" content-id="first">
+            <ion-label>First</ion-label>
+          </ion-segment-button>
+          <ion-segment-button value="second" content-id="second">
+            <ion-label>Second</ion-label>
+          </ion-segment-button>
+          <ion-segment-button value="third" content-id="third">
+            <ion-label>Third</ion-label>
+          </ion-segment-button>
+        </ion-segment>
+        <ion-segment-view>
+          <ion-segment-content id="first">First</ion-segment-content>
+          <ion-segment-content id="second">Second</ion-segment-content>
+          <ion-segment-content id="third">Third</ion-segment-content>
+        </ion-segment-view>
+      </ion-content>
+    </ion-app>
+  </body>
+</html>
diff --git a/static/usage/v8/segment/swipeable/index.md 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';
+
+<Playground
+  version="8"
+  code={{
+    javascript,
+    react: {
+      files: {
+        'src/main.tsx': react_main_tsx,
+        'src/main.css': react_main_css,
+      },
+    },
+    vue,
+    angular: {
+      files: {
+        'src/app/example.component.html': angular_html,
+        'src/app/example.component.css': angular_css,
+      },
+    },
+  }}
+  src="usage/v8/segment/swipeable/demo.html"
+/>
diff --git a/static/usage/v8/segment/swipeable/javascript.md b/static/usage/v8/segment/swipeable/javascript.md
@@ -0,0 +1,39 @@
+```html
+<ion-segment>
+  <ion-segment-button value="first" content-id="first">
+    <ion-label>First</ion-label>
+  </ion-segment-button>
+  <ion-segment-button value="second" content-id="second">
+    <ion-label>Second</ion-label>
+  </ion-segment-button>
+  <ion-segment-button value="third" content-id="third">
+    <ion-label>Third</ion-label>
+  </ion-segment-button>
+</ion-segment>
+<ion-segment-view>
+  <ion-segment-content id="first">First</ion-segment-content>
+  <ion-segment-content id="second">Second</ion-segment-content>
+  <ion-segment-content id="third">Third</ion-segment-content>
+</ion-segment-view>
+
+<style>
+  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;
+  }
+</style>
+```
diff --git a/static/usage/v8/segment/swipeable/react/react_css.md 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
@@ -0,0 +1,30 @@
+```tsx
+import React from 'react';
+import { IonLabel, IonSegment, IonSegmentButton, IonSegmentContent, IonSegmentView } from '@ionic/react';
+
+import './main.css';
+
+function Example() {
+  return (
+    <>
+      <IonSegment value="first">
+        <IonSegmentButton value="first" contentId="first">
+          <IonLabel>First</IonLabel>
+        </IonSegmentButton>
+        <IonSegmentButton value="second" contentId="second">
+          <IonLabel>Second</IonLabel>
+        </IonSegmentButton>
+        <IonSegmentButton value="third" contentId="third">
+          <IonLabel>Third</IonLabel>
+        </IonSegmentButton>
+      </IonSegment>
+      <IonSegmentView>
+        <IonSegmentContent id="first">First</IonSegmentContent>
+        <IonSegmentContent id="second">Second</IonSegmentContent>
+        <IonSegmentContent id="third">Third</IonSegmentContent>
+      </IonSegmentView>
+    </>
+  );
+}
+export default Example;
+```
diff --git a/static/usage/v8/segment/swipeable/vue.md b/static/usage/v8/segment/swipeable/vue.md
@@ -0,0 +1,50 @@
+```html
+<template>
+  <ion-segment>
+    <ion-segment-button value="first" content-id="first">
+      <ion-label>First</ion-label>
+    </ion-segment-button>
+    <ion-segment-button value="second" content-id="second">
+      <ion-label>Second</ion-label>
+    </ion-segment-button>
+    <ion-segment-button value="third" content-id="third">
+      <ion-label>Third</ion-label>
+    </ion-segment-button>
+  </ion-segment>
+  <ion-segment-view>
+    <ion-segment-content id="first">First</ion-segment-content>
+    <ion-segment-content id="second">Second</ion-segment-content>
+    <ion-segment-content id="third">Third</ion-segment-content>
+  </ion-segment-view>
+</template>
+
+<style>
+  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;
+  }
+</style>
+
+<script lang="ts">
+  import { IonLabel, IonSegment, IonSegmentButton, IonSegmentContent, IonSegmentView } from '@ionic/vue';
+  import { defineComponent } from 'vue';
+
+  export default defineComponent({
+    components: { IonLabel, IonSegment, IonSegmentButton, IonSegmentContent, IonSegmentView },
+  });
+</script>
+```