From 62d44d5ffca16b71bb0848943339ff09b3cf04fd Mon Sep 17 00:00:00 2001
From: Brandy Carney <brandyscarney@gmail.com>
Date: Mon, 30 Sep 2024 15:37:07 -0400
Subject: [PATCH 1/2] docs(app): add demo for setFocus method

---
 docs/api/app.md                               |  8 ++-
 .../angular/example_component_html.md         | 12 +++++
 .../set-focus/angular/example_component_ts.md | 19 +++++++
 static/usage/v8/app/set-focus/demo.html       | 49 +++++++++++++++++++
 static/usage/v8/app/set-focus/index.md        | 25 ++++++++++
 static/usage/v8/app/set-focus/javascript.md   | 23 +++++++++
 static/usage/v8/app/set-focus/react.md        | 35 +++++++++++++
 static/usage/v8/app/set-focus/vue.md          | 33 +++++++++++++
 8 files changed, 203 insertions(+), 1 deletion(-)
 create mode 100644 static/usage/v8/app/set-focus/angular/example_component_html.md
 create mode 100644 static/usage/v8/app/set-focus/angular/example_component_ts.md
 create mode 100644 static/usage/v8/app/set-focus/demo.html
 create mode 100644 static/usage/v8/app/set-focus/index.md
 create mode 100644 static/usage/v8/app/set-focus/javascript.md
 create mode 100644 static/usage/v8/app/set-focus/react.md
 create mode 100644 static/usage/v8/app/set-focus/vue.md

diff --git a/docs/api/app.md b/docs/api/app.md
index 30f22a6f860..d44752b6ff1 100644
--- a/docs/api/app.md
+++ b/docs/api/app.md
@@ -15,7 +15,6 @@ import Slots from '@ionic-internal/component-api/v8/app/slots.md';
 
 import EncapsulationPill from '@components/page/api/EncapsulationPill';
 
-
 App is a container element for an Ionic application. There should only be one `<ion-app>` element per project. An app can have many Ionic components including menus, headers, content, and footers. The overlay components get appended to the `<ion-app>` when they are presented.
 
 Using `ion-app` enables the following behaviors:
@@ -27,6 +26,13 @@ Using `ion-app` enables the following behaviors:
 * [Ripple effect](./ripple-effect) when activating buttons on Material Design mode
 * Other tap and focus utilities which make the experience of using an Ionic app feel more native
 
+## Programmatic Focus
+
+As mentioned earlier, the `ion-app` component provides focus utilities for Ionic components with the `ion-focusable` class. The `setFocus` method allows you to programmatically focus an element in response to user actions. However, it should not be used when the element is focused due to a keyboard event, as the focus utility will handle that automatically.
+
+import SetFocus from '@site/static/usage/v8/app/set-focus/index.md';
+
+<SetFocus />
 
 ## Properties
 <Props />
diff --git a/static/usage/v8/app/set-focus/angular/example_component_html.md b/static/usage/v8/app/set-focus/angular/example_component_html.md
new file mode 100644
index 00000000000..877143505d3
--- /dev/null
+++ b/static/usage/v8/app/set-focus/angular/example_component_html.md
@@ -0,0 +1,12 @@
+```html
+<ion-button id="buttonToFocus" fill="outline">Button</ion-button>
+
+<ion-radio-group value="a">
+  <ion-radio id="radioToFocus" value="a">Radio</ion-radio>
+</ion-radio-group>
+
+<br />
+
+<ion-button (click)="focusElement('#buttonToFocus')">Focus Button</ion-button>
+<ion-button (click)="focusElement('#radioToFocus')">Focus Radio</ion-button>
+```
diff --git a/static/usage/v8/app/set-focus/angular/example_component_ts.md b/static/usage/v8/app/set-focus/angular/example_component_ts.md
new file mode 100644
index 00000000000..9970bf3e4dd
--- /dev/null
+++ b/static/usage/v8/app/set-focus/angular/example_component_ts.md
@@ -0,0 +1,19 @@
+```ts
+import { Component } from '@angular/core';
+
+@Component({
+  selector: 'app-example',
+  templateUrl: 'example.component.html',
+  styleUrls: ['example.component.css'],
+})
+export class ExampleComponent {
+  focusElement(id: string) {
+    const el = document.querySelector(id) as HTMLElement;
+
+    const app = el.closest('ion-app');
+    if (app) {
+      app.setFocus([el]);
+    }
+  }
+}
+```
diff --git a/static/usage/v8/app/set-focus/demo.html b/static/usage/v8/app/set-focus/demo.html
new file mode 100644
index 00000000000..780037033a2
--- /dev/null
+++ b/static/usage/v8/app/set-focus/demo.html
@@ -0,0 +1,49 @@
+<!DOCTYPE html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>App</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>
+      .container {
+        display: grid;
+        grid-template-columns: repeat(2, auto);
+        column-gap: 10px;
+        justify-items: center;
+      }
+    </style>
+  </head>
+
+  <body>
+    <ion-app>
+      <ion-content>
+        <div class="container">
+          <ion-button id="buttonToFocus" fill="outline">Button</ion-button>
+
+          <ion-radio-group value="a">
+            <ion-radio id="radioToFocus" value="a">Radio</ion-radio>
+          </ion-radio-group>
+
+          <ion-button onClick="focusElement('#buttonToFocus')">Focus Button</ion-button>
+          <ion-button onClick="focusElement('#radioToFocus')">Focus Radio</ion-button>
+        </div>
+
+        <script>
+          function focusElement(id) {
+            const el = document.querySelector(id);
+
+            const app = el.closest('ion-app');
+            if (app) {
+              app.setFocus([el]);
+            }
+          }
+        </script>
+      </ion-content>
+    </ion-app>
+  </body>
+</html>
diff --git a/static/usage/v8/app/set-focus/index.md b/static/usage/v8/app/set-focus/index.md
new file mode 100644
index 00000000000..8f33bf88f40
--- /dev/null
+++ b/static/usage/v8/app/set-focus/index.md
@@ -0,0 +1,25 @@
+import Playground from '@site/src/components/global/Playground';
+
+import javascript from './javascript.md';
+import react from './react.md';
+import vue from './vue.md';
+
+import angular_example_component_html from './angular/example_component_html.md';
+import angular_example_component_ts from './angular/example_component_ts.md';
+
+<Playground
+  version="8"
+  code={{
+    javascript,
+    react,
+    vue,
+    angular: {
+      files: {
+        'src/app/example.component.html': angular_example_component_html,
+        'src/app/example.component.ts': angular_example_component_ts,
+      },
+    },
+  }}
+  src="usage/v8/app/set-focus/demo.html"
+  size="sm"
+/>
diff --git a/static/usage/v8/app/set-focus/javascript.md b/static/usage/v8/app/set-focus/javascript.md
new file mode 100644
index 00000000000..810c8b6ae0f
--- /dev/null
+++ b/static/usage/v8/app/set-focus/javascript.md
@@ -0,0 +1,23 @@
+```html
+<ion-button id="buttonToFocus" fill="outline">Button</ion-button>
+
+<ion-radio-group value="a">
+  <ion-radio id="radioToFocus" value="a">Radio</ion-radio>
+</ion-radio-group>
+
+<br />
+
+<ion-button onClick="focusElement('#buttonToFocus')">Focus Button</ion-button>
+<ion-button onClick="focusElement('#radioToFocus')">Focus Radio</ion-button>
+
+<script>
+  function focusElement(id) {
+    const el = document.querySelector(id);
+
+    const app = el.closest('ion-app');
+    if (app) {
+      app.setFocus([el]);
+    }
+  }
+</script>
+```
diff --git a/static/usage/v8/app/set-focus/react.md b/static/usage/v8/app/set-focus/react.md
new file mode 100644
index 00000000000..c550f8f7728
--- /dev/null
+++ b/static/usage/v8/app/set-focus/react.md
@@ -0,0 +1,35 @@
+```tsx
+import React from 'react';
+import { IonButton, IonRadio, IonRadioGroup } from '@ionic/react';
+
+function Example() {
+  function focusElement(id: string) {
+    const el = document.querySelector(id) as HTMLElement;
+
+    const app = el.closest('ion-app');
+    if (app) {
+      app.setFocus([el]);
+    }
+  }
+
+  return (
+    <>
+      <IonButton id="buttonToFocus" fill="outline">
+        Button
+      </IonButton>
+
+      <IonRadioGroup value="a">
+        <IonRadio id="radioToFocus" value="a">
+          Radio
+        </IonRadio>
+      </IonRadioGroup>
+
+      <br />
+
+      <IonButton onClick={() => focusElement('#buttonToFocus')}>Focus Button</IonButton>
+      <IonButton onClick={() => focusElement('#radioToFocus')}>Focus Radio</IonButton>
+    </>
+  );
+}
+export default Example;
+```
diff --git a/static/usage/v8/app/set-focus/vue.md b/static/usage/v8/app/set-focus/vue.md
new file mode 100644
index 00000000000..4af15e195df
--- /dev/null
+++ b/static/usage/v8/app/set-focus/vue.md
@@ -0,0 +1,33 @@
+```html
+<template>
+  <ion-button id="buttonToFocus" fill="outline">Button</ion-button>
+
+  <ion-radio-group value="a">
+    <ion-radio id="radioToFocus" value="a">Radio</ion-radio>
+  </ion-radio-group>
+
+  <br />
+
+  <ion-button @click="focusElement('#buttonToFocus')">Focus Button</ion-button>
+  <ion-button @click="focusElement('#radioToFocus')">Focus Radio</ion-button>
+</template>
+
+<script lang="ts">
+  import { IonButton, IonRadio, IonRadioGroup } from '@ionic/vue';
+  import { defineComponent } from 'vue';
+
+  export default defineComponent({
+    components: { IonButton, IonRadio, IonRadioGroup },
+    methods: {
+      focusElement(id) {
+        const el = document.querySelector(id);
+
+        const app = el.closest('ion-app');
+        if (app) {
+          app.setFocus([el]);
+        }
+      },
+    },
+  });
+</script>
+```

From 342fa37b5cf799c3e6acbd52ec352a7d43af6051 Mon Sep 17 00:00:00 2001
From: Brandy Carney <brandyscarney@gmail.com>
Date: Tue, 1 Oct 2024 10:11:54 -0400
Subject: [PATCH 2/2] docs: copy editing

---
 docs/api/app.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/api/app.md b/docs/api/app.md
index d44752b6ff1..5e20f74cd20 100644
--- a/docs/api/app.md
+++ b/docs/api/app.md
@@ -28,7 +28,7 @@ Using `ion-app` enables the following behaviors:
 
 ## Programmatic Focus
 
-As mentioned earlier, the `ion-app` component provides focus utilities for Ionic components with the `ion-focusable` class. The `setFocus` method allows you to programmatically focus an element in response to user actions. However, it should not be used when the element is focused due to a keyboard event, as the focus utility will handle that automatically.
+Ionic offers focus utilities for components with the `ion-focusable` class. These utilities automatically manage focus for components when certain keyboard keys, like <kbd>Tab</kbd>, are pressed. Components can also be programmatically focused in response to user actions using the `setFocus` method from `ion-app`.
 
 import SetFocus from '@site/static/usage/v8/app/set-focus/index.md';