reis-mobile 0.3.6 → 0.4.0

package/skills/android-display-glasses-with-jetpack-compose-glimmer/references/android/develop/xr/jetpack-xr-sdk/jetpack-compose-glimmer/cards.md

@@ -0,0 +1,148 @@
+<br />
+
+
+Applicable XR devices This guidance helps you build experiences for these types of XR devices. [Learn about XR device types →](https://developer.android.com/develop/xr/devices) ![](https://developer.android.com/static/images/develop/xr/ai-glasses-icon.svg) Display Glasses [](https://developer.android.com/develop/xr/devices#audio-display) [Learn about XR device types →](https://developer.android.com/develop/xr/devices)
+
+<br />
+
+In Jetpack Compose Glimmer, the [`Card`](https://developer.android.com/reference/kotlin/androidx/xr/glimmer/Card.composable) component serves as the primary
+container for related content, creating a clear visual boundary for digestible
+units of information. Cards are highly adaptable, supporting combinations of
+main content, optional titles, subtitles, and leading or trailing icons. Cards
+fill the maximum available width by default, are focusable, and you can also
+make them clickable. Cards support a vertical arrangement where the header image
+is top-most, followed by the title, subtitle, and body content.
+
+Cards are built on the Jetpack Compose Glimmer [surface system](https://developer.android.com/develop/xr/jetpack-xr-sdk/jetpack-compose-glimmer/surface), so they
+inherit physical properties like depth effects, clipping, and consistent border
+highlights.
+![](https://developer.android.com/static/images/design/ui/glasses/guides/glasses_components_cards.png) **Figure 1.** An example of some different styles of cards in Jetpack Compose Glimmer.
+
+## Anatomy and slots
+
+A Jetpack Compose Glimmer Card is built from several specialized elements that
+let you customize its content and layout.
+
+| Slot | Description |
+|---|---|
+| Header | The top section of the card, designed to hold an image. |
+| Title and subtitle | These text fields provide the main and secondary labels for the card. The title is placed above the subtitle. |
+| Leading icon | An optional icon (typically an [`Icon`](https://developer.android.com/reference/kotlin/androidx/xr/glimmer/Icon.composable)) that appears at the beginning of the card's content area. |
+| Trailing icon | An optional icon that appears at the end of the card's content area. |
+| Main content | The core body of the card for primary [`Text`](https://developer.android.com/reference/kotlin/androidx/xr/glimmer/Text.composable) or content. |
+
+## Card defaults
+
+The following defaults apply to cards:
+
+- **Width**: Cards fill the maximum available width of the display to optimize legibility on display glasses.
+- **Minimum height** : `80.dp`
+- **Text vertical spacing** : `3.dp`
+- **Header shape** : Uses [`RoundedCornerShape`](https://developer.android.com/reference/kotlin/androidx/compose/foundation/shape/package-summary#RoundedCornerShape(androidx.compose.ui.unit.Dp)) with `24.dp` corners
+- **Content padding** : Defaults to [`GlimmerTheme.componentSpacingValues.medium`](https://developer.android.com/reference/kotlin/androidx/xr/glimmer/ComponentSpacingValues#medium()). This affects the outermost padding around header images and the content container.
+- **Shape** : Defaults to [`GlimmerTheme.shapes.medium`](https://developer.android.com/reference/kotlin/androidx/xr/glimmer/Shapes#medium()).
+- **Text rendering** : Uses the default values from
+  [`GlimmerTheme.typography`](https://developer.android.com/reference/kotlin/androidx/xr/glimmer/GlimmerTheme#typography()) for the following slots:
+
+  - Title: [`bodyMedium`](https://developer.android.com/reference/kotlin/androidx/xr/glimmer/Typography#bodyMedium())
+  - Subtitle: [`caption`](https://developer.android.com/reference/kotlin/androidx/xr/glimmer/Typography#caption())
+  - Main content: [`bodySmall`](https://developer.android.com/reference/kotlin/androidx/xr/glimmer/Typography#bodySmall())
+
+## Example: Basic card
+
+The following code shows the minimal code needed to build a card:
+
+
+```kotlin
+Card { Text("This is a card") }
+```
+
+<br />
+
+## Example: Card with multiple slots
+
+The following code shows how to use multiple slots together to build a card:
+
+
+```kotlin
+Card(
+    title = { Text("Card Title", style = GlimmerTheme.typography.titleMedium) },
+    subtitle = { Text("Sub-heading text", style = GlimmerTheme.typography.titleSmall) },
+    leadingIcon = { Icon(FavoriteIcon, contentDescription = "Favorite") },
+    trailingIcon = { Icon(BookmarkIcon, contentDescription = "Bookmark") },
+    header = {
+        Image(
+            painter = myHeaderImage,
+            contentDescription = "Header image",
+            contentScale = ContentScale.FillWidth
+        )
+    },
+) {
+    Text("This is a complete card")
+}
+```
+
+<br />
+
+### Key points about the code
+
+- Shows how to use various card elements, such as [`title`](https://developer.android.com/reference/kotlin/androidx/xr/glimmer/Card.composable), [`subtitle`](https://developer.android.com/reference/kotlin/androidx/xr/glimmer/Card.composable), and [`leadingIcon`](https://developer.android.com/reference/kotlin/androidx/xr/glimmer/Card.composable), to customize the card's content and structure.
+- Uses the [`Card`](https://developer.android.com/reference/kotlin/androidx/xr/glimmer/Card.composable#Card(kotlin.Function0,androidx.compose.ui.Modifier,kotlin.Function0,kotlin.Function0,kotlin.Function0,kotlin.Function0,kotlin.Function0,androidx.compose.ui.graphics.Shape,androidx.compose.ui.graphics.Color,androidx.compose.ui.graphics.Color,androidx.compose.foundation.BorderStroke,androidx.compose.foundation.layout.PaddingValues,androidx.compose.foundation.interaction.MutableInteractionSource,kotlin.Function0)) overload with `onClick` to make the entire card surface interactive.
+
+## Action cards
+
+If you want to include an action button with a card, use an
+[`ActionCard`](https://developer.android.com/reference/kotlin/androidx/xr/glimmer/ActionCard.composable). Action cards have the same elements as standard cards and
+also include an additional `action` parameter that defines the bottom button.
+![](https://developer.android.com/static/images/design/ui/xr/guides/actioncard.png) **Figure 2.** An example of an `ActionCard` in Jetpack Compose Glimmer.
+
+### Example: Basic action card
+
+This code shows how to create an `ActionCard`:
+
+
+```kotlin
+ActionCard(
+    action = {
+        Button(onClick = {}, trailingIcon = { Icon(FavoriteIcon, "Localized description") }) {
+            Text("Send")
+        }
+    }
+) {
+    Text("This is a card with a title, leading icon, header image, and action")
+}
+```
+
+<br />
+
+### Example: Action card with an icon
+
+This code shows how to create a more complex `ActionCard` with icons:
+
+
+```kotlin
+ActionCard(
+    title = { Text("Card Title", style = GlimmerTheme.typography.titleMedium) },
+    subtitle = { Text("Sub-heading text", style = GlimmerTheme.typography.titleSmall) },
+    leadingIcon = { Icon(FavoriteIcon, contentDescription = "Favorite") },
+    header = {
+        Image(
+            painter = myHeaderImage,
+            contentDescription = "Header image",
+            contentScale = ContentScale.FillWidth
+        )
+    },
+    action = {
+        Button(onClick = { /* Handle action */ }) {
+            Text("Action")
+        }
+    }
+) {
+    Text(
+        "This is the main body content of the card, utilizing theme-tokens for consistent styling.",
+        style = GlimmerTheme.typography.bodyMedium
+    )
+}
+```
+
+<br />

package/skills/android-display-glasses-with-jetpack-compose-glimmer/references/android/develop/xr/jetpack-xr-sdk/jetpack-compose-glimmer/focus.md

@@ -0,0 +1,107 @@
+<br />
+
+
+Applicable XR devices This guidance helps you build experiences for these types of XR devices. [Learn about XR device types →](https://developer.android.com/develop/xr/devices) ![](https://developer.android.com/static/images/develop/xr/ai-glasses-icon.svg) Display Glasses [](https://developer.android.com/develop/xr/devices#audio-display) [Learn about XR device types →](https://developer.android.com/develop/xr/devices)
+
+<br />
+
+All Jetpack Compose Glimmer components are designed to work with standard input
+methods, such as a tap or swipe on the glasses' touchpad, while also being
+receptive to lower-level input commands that are specific to the hardware on
+display glasses. Jetpack Compose Glimmer components automatically handle the
+necessary input events.
+
+For standard actions like scroll and drag, use the Jetpack Compose Glimmer
+components to promote a consistent experience. However, for custom components or
+bespoke interaction behaviors, you can use existing Compose APIs like
+[`Modifier.draggable`](https://developer.android.com/reference/kotlin/androidx/compose/ui/Modifier#(androidx.compose.ui.Modifier).draggable(androidx.compose.foundation.gestures.DraggableState,androidx.compose.foundation.gestures.Orientation,kotlin.Boolean,androidx.compose.foundation.interaction.MutableInteractionSource,kotlin.Boolean,kotlin.coroutines.SuspendFunction2,kotlin.coroutines.SuspendFunction2,kotlin.Boolean)) or [`Modifier.scrollable`](https://developer.android.com/reference/kotlin/androidx/compose/ui/Modifier#(androidx.compose.ui.Modifier).scrollable(androidx.compose.foundation.gestures.ScrollableState,androidx.compose.foundation.gestures.Orientation,kotlin.Boolean,kotlin.Boolean,androidx.compose.foundation.gestures.FlingBehavior,androidx.compose.foundation.interaction.MutableInteractionSource)).
+
+## Pointer input and focus
+
+On display glasses, pointer input can affect focus:
+
+- **Tap**: Direct interaction for activating element. Focus moves to an element when a user interacts with it.
+- **Swipe**: Used for navigation and scrolling. Unhandled swipe gestures automatically translate into focus movements, enabling seamless UI navigation without direct pointer input.
+
+<br />
+
+> [!WARNING]
+> **(Temporary requirement) Enable required input flag** :
+>
+> <br />
+>
+> Using a feature of Jetpack Compose, the system can automatically set the initial
+> focus to the very-first focusable element when the screen loads, which is often
+> the top-left item on the screen.
+>
+> This feature is still in development and isn't enabled by default. To activate
+> this feature, set the `isInitialFocusOnFocusableAvailable` flag to `true` in
+> your activity's [`onCreate()`](https://developer.android.com/reference/kotlin/android/app/Activity#onCreate(android.os.Bundle)) method.
+>
+>     import androidx.compose.ui.ExperimentalComposeUiApi
+>     import androidx.compose.ui.ComposeUiFlags
+>
+>     class GlassesActivityExample : ComponentActivity() {
+>         override fun onCreate(savedInstanceState: Bundle?) {
+>             @OptIn(ExperimentalComposeUiApi::class)
+>             ComposeUiFlags.isInitialFocusOnFocusableAvailable = true
+>             super.onCreate(savedInstanceState)
+>         }
+>     }
+>
+> <br />
+>
+<br />
+
+## Navigation behavior and order
+
+Focus movement and order change as a user navigates your app.
+
+### Focus movement
+
+On a scrollable container, focus moves continuously with a swipe on the
+touchpad. For discrete elements like a row of buttons, each swipe moves the
+focus one element at a time.
+
+### Focus order
+
+Just like in Jetpack Compose, Jetpack Compose Glimmer uses one-dimensional focus
+search. To learn more about the order of focus traversal, see [Change focus
+traversal order](https://developer.android.com/develop/ui/compose/touch-input/focus/change-focus-traversal-order#override-one-dimensional).
+
+To change the initially-focused item, you can add a top-level
+[`Modifier.focusGroup()`](https://developer.android.com/reference/kotlin/androidx/compose/ui/Modifier#(androidx.compose.ui.Modifier).focusGroup()) and specify a custom `onEnter`
+[`focusProperty`](https://developer.android.com/reference/kotlin/androidx/compose/ui/Modifier#(androidx.compose.ui.Modifier).focusProperties(kotlin.Function1)):
+
+    Modifier.focusProperties {
+        onEnter = {
+            initialFocus.requestFocus()
+            // Prevent focus from exiting the group
+            cancelFocusChange()
+        }
+    }
+    .focusGroup()
+
+### Scrolling containers
+
+For an optimal user experience, scrolling containers like lists should be the
+only major component on a screen. Avoid placing a scrollable list directly above
+or below other interactive elements, such as buttons, to prevent navigation
+confusion and promote smooth, predictable focus movement.
+
+## Default focus states
+
+Jetpack Compose Glimmer implements default focus states across its interactable
+components, including surfaces, cards, and list items, promoting consistent and
+clear visual feedback during user interaction.
+![](https://developer.android.com/static/images/design/ui/glasses/guides/glasses_ixd_inputs_focus.png) **Figure 1.** Three focus states in Jetpack Compose Glimmer, which are differentiated using outline-based visual feedback.
+
+- **Default** : The button's background color is derived from
+  [`GlimmerTheme.colors.surface`](https://developer.android.com/reference/kotlin/androidx/xr/glimmer/Colors#surface()), its main content calculates the content
+  color of that surface.
+
+- **Focused**: The border width is increased to communicate focus.
+
+- **Focused + Pressed** : The background is set to
+  `GlimmerTheme.colors.surface` at increased opacity to communicate its
+  selected state.

package/skills/android-display-glasses-with-jetpack-compose-glimmer/references/android/develop/xr/jetpack-xr-sdk/jetpack-compose-glimmer/icons.md

@@ -0,0 +1,90 @@
+<br />
+
+
+Applicable XR devices This guidance helps you build experiences for these types of XR devices. [Learn about XR device types →](https://developer.android.com/develop/xr/devices) ![](https://developer.android.com/static/images/develop/xr/ai-glasses-icon.svg) Display Glasses [](https://developer.android.com/develop/xr/devices#audio-display) [Learn about XR device types →](https://developer.android.com/develop/xr/devices)
+
+<br />
+
+In Jetpack Compose Glimmer, the [`Icon`](https://developer.android.com/reference/kotlin/androidx/xr/glimmer/Icon.composable) component is a UI element for
+rendering single-color icons. Icons intelligently handle tinting and scaling so
+that they remain legible and visually consistent with the [`GlimmerTheme`](https://developer.android.com/reference/kotlin/androidx/xr/glimmer/GlimmerTheme.composable).
+
+## Sizes
+
+While icons default to the size provided by [`LocalIconSize`](https://developer.android.com/reference/kotlin/androidx/xr/glimmer/package-summary#LocalIconSize()), you can also
+use the three icon sizes provided to set an specific size. These sizes are also
+used by default for the following contexts:
+
+| Size token | Default usage |
+|---|---|
+| `small` | For standard list items or small chips. |
+| `medium` | For standalone icons and title chips. |
+| `large` | For high-emphasis components like cards. |
+
+## Icon sources
+
+Icons can accept [`ImageVector`](https://developer.android.com/reference/kotlin/androidx/compose/ui/graphics/vector/ImageVector), [`ImageBitmap`](https://developer.android.com/reference/kotlin/androidx/compose/ui/graphics/ImageBitmap), or [`Painter`](https://developer.android.com/reference/kotlin/androidx/compose/ui/graphics/painter/Painter) as
+their source. When defining your own icons, use `ImageVector` where possible to
+promote sharp rendering at any scale on display glasses.
+
+## Color and Tinting
+
+- **Automatic tint** : The icon resolves its color based on the `LocalContentColor` provided by the parent surface `LocalContentColor` provided by the parent surface, such as a [`surface`](https://developer.android.com/reference/kotlin/androidx/xr/glimmer/surface.composable) or [`Button`](https://developer.android.com/reference/kotlin/androidx/xr/glimmer/Button.composable).
+- **Manual Tinting** : Use the `tint` parameter to apply a specific color.
+- **Multicolored Assets** : For icons that should not be tinted (like multicolored brand logos), set `tint = Color.Unspecified`.
+- **Generic Images** : For photographs or generic images that don't follow icon sizing and tinting rules, use the standard [`androidx.compose.foundation.Image`](https://developer.android.com/reference/kotlin/androidx/compose/foundation/Image.composable) instead.
+
+## Example: Basic icon
+
+The following code creates a basic icon:
+
+
+```kotlin
+@Composable
+fun IconSample() {
+    Icon(FavoriteIcon, contentDescription = "Localized description")
+}
+```
+
+<br />
+
+## Example: Icons with color
+
+The following code creates a colored icon using the theme's primary color:
+
+
+```kotlin
+@Composable
+fun ColoredIconSample() {
+    Icon(
+        FavoriteIcon,
+        tint = GlimmerTheme.colors.primary,
+        contentDescription = "Localized description",
+    )
+}
+```
+
+<br />
+
+## Example: Icons with different sizes
+
+The following code creates a icon that is modified to be a specific size:
+
+
+```kotlin
+@Composable
+fun SizedIconSample() {
+    Icon(
+        FavoriteIcon,
+        contentDescription = "Localized description",
+        modifier = Modifier.size(GlimmerTheme.iconSizes.large),
+    )
+}
+```
+
+<br />
+
+### Key points about the code
+
+- The icon's size is customized using [`GlimmerTheme.iconSizes`](https://developer.android.com/reference/kotlin/androidx/xr/glimmer/IconSizes) with a modifier. For icons, the default value is [`GlimmerTheme.iconSizes.medium`](https://developer.android.com/reference/kotlin/androidx/xr/glimmer/IconSizes#medium()). Use these sizes instead of hard-coding values to maintain consistency across your UI.
+- Provides a localized `contentDescription` for the icon. Always provide these descriptions unless the icon is purely decorative.

package/skills/android-display-glasses-with-jetpack-compose-glimmer/references/android/develop/xr/jetpack-xr-sdk/jetpack-compose-glimmer/text.md

@@ -0,0 +1,69 @@
+<br />
+
+
+Applicable XR devices This guidance helps you build experiences for these types of XR devices. [Learn about XR device types →](https://developer.android.com/develop/xr/devices) ![](https://developer.android.com/static/images/develop/xr/ai-glasses-icon.svg) Display Glasses [](https://developer.android.com/develop/xr/devices#audio-display) [Learn about XR device types →](https://developer.android.com/develop/xr/devices)
+
+<br />
+
+In Jetpack Compose Glimmer, the [`Text`](https://developer.android.com/reference/kotlin/androidx/xr/glimmer/Text.composable) component lets you set various text
+properties like color, font size, font style, font weight, font family, letter
+spacing, and text alignment.
+
+Jetpack Compose Glimmer Text is unique because it intelligently manages color
+matching. For example, if no color override is specified, the text defaults to
+the content color provided by the nearest surface that it's sitting on.
+
+## Example: Create a text heading in a box
+
+
+```kotlin
+@Composable
+fun TextSample() {
+    Text(
+        text = "Hello Glimmer",
+        style = GlimmerTheme.typography.titleLarge
+    )
+}
+```
+
+<br />
+
+### Key points about the code
+
+- Because no color is specified, this text looks at the nearest surface to pick the best readable color (usually white).
+
+## Sizing
+
+Typography scale in Jetpack Compose Glimmer is significantly larger than
+standard mobile Material Design. Styles like `TitleLarge` and `BodyLarge` are
+both `30.sp`, and the Caption is `18.sp`:
+
+| Style | Size (sp) | Weight | Line Height |
+|---|---|---|---|
+| titleLarge | 30 | 750 | 36.sp |
+| titleMedium | 24 | 750 | 28.sp |
+| titleSmall | 20 | 750 | 28.sp |
+| bodyLarge | 30 | 520 | 36.sp |
+| bodyMedium | 24 | 520 | 36.sp |
+| bodySmall | 20 | 520 | 28.sp |
+| caption | 18 | 650 | 24.sp |
+
+## Use Google Sans Flex
+
+[Google Sans Flex](https://fonts.google.com/specimen/Google+Sans+Flex?query=google+sans&preview.script=Latn) is a variable font specifically chosen for AI
+glasses that is provided as part of the Jetpack Compose Glimmer. The font's
+rounded corners and adjustable axes allow for ideal optical sizing, ensuring
+that text remains glanceable and legible. If possible, to improve consistency
+for users between your app and the system, use Google Sans Flex for all text
+displayed on display glasses.
+
+To use Google Sans Flex, [add the `glimmer-google-fonts` library to your app's
+dependencies](https://developer.android.com/develop/xr/jetpack-xr-sdk/set-up-sdk#augmented), then apply the font globally to the `GlimmerTheme`:
+
+    @Composable
+    fun GoogleSansFlexTypographySample() {
+        val typography = createGoogleSansFlexTypography()
+        GlimmerTheme(typography = typography) {
+            Text("Hello World", style = GlimmerTheme.typography.titleLarge)
+        }
+    }

package/skills/android-display-glasses-with-jetpack-compose-glimmer/references/android/develop/xr/jetpack-xr-sdk/jetpack-compose-glimmer/title-chips.md

@@ -0,0 +1,82 @@
+<br />
+
+
+Applicable XR devices This guidance helps you build experiences for these types of XR devices. [Learn about XR device types →](https://developer.android.com/develop/xr/devices) ![](https://developer.android.com/static/images/develop/xr/ai-glasses-icon.svg) Display Glasses [](https://developer.android.com/develop/xr/devices#audio-display) [Learn about XR device types →](https://developer.android.com/develop/xr/devices)
+
+<br />
+
+In Jetpack Compose Glimmer, the [`TitleChip`](https://developer.android.com/reference/kotlin/androidx/xr/glimmer/TitleChip.composable) component is a non-interactive
+component that provides brief context or labeling for associated content, such
+as a [`Card`](https://developer.android.com/reference/kotlin/androidx/xr/glimmer/Card.composable) or a [`VerticalList`](https://developer.android.com/reference/kotlin/androidx/xr/glimmer/list/VerticalList.composable).
+
+Use title chips for concise information like a short title, a category name, or
+a status indicator. Normally, you should place title chips above the content
+they describe to establish a clear structural relationship.
+![](https://developer.android.com/static/images/design/ui/glasses/guides/glasses_components_titlechip_anatomy.png) **Figure 1.** An example of a default style title chip and sticky title chip in Jetpack Compose Glimmer. Each title chip has a label (1) and an optional leading icon or entity (2).
+
+## Basic example: Create a short title chip
+
+The following code creates a basic title chip:
+
+
+```kotlin
+@Composable
+fun BasicTitleChipSample() {
+    TitleChip { Text("Messages") }
+}
+```
+
+<br />
+
+## Basic example: Create a title chip with an icon
+
+The following code creates a title chip with an icon:
+
+
+```kotlin
+@Composable
+fun TitleChipWithIconSample() {
+    TitleChip {
+        Icon(FavoriteIcon, contentDescription = "Favorite")
+        Text("Favorites")
+    }
+}
+```
+
+<br />
+
+## Example: Create a title chip with a card
+
+To use a title chip with another component, place the title chip
+[`TitleChipDefaults.associatedContentSpacing`](https://developer.android.com/reference/kotlin/androidx/xr/glimmer/TitleChipDefaults#associatedContentSpacing()) above the other component in
+the composable. The following code creates a title chip with a card:
+
+
+```kotlin
+@Composable
+fun TitleChipWithCardSample() {
+    Column(horizontalAlignment = Alignment.CenterHorizontally) {
+        TitleChip { Text("Title Chip") }
+
+        Spacer(Modifier.height(TitleChipDefaults.associatedContentSpacing))
+
+        Card(
+            title = { Text("Title") },
+            subtitle = { Text("Subtitle") },
+            leadingIcon = { Icon(FavoriteIcon, "Localized description") },
+        ) {
+            Text("Card Content")
+        }
+    }
+}
+```
+
+<br />
+
+### Key points about the code
+
+- The title chip is centered horizontally, which is the usual alignment for a title chip placed above a card.
+- The [`Spacer`](https://developer.android.com/reference/kotlin/androidx/compose/foundation/layout/Spacer.composable#Spacer(androidx.compose.ui.Modifier)) has a fixed height to provide the right amount of vertical spacing between the two components. This is defined using [`TitleChipDefaults.associatedContentSpacing`](https://developer.android.com/reference/kotlin/androidx/xr/glimmer/TitleChipDefaults#associatedContentSpacing()).
+- Uses an optional `leadingIcon` to add additional visual context before the text content.
+- The title chip automatically uses the [`caption`](https://developer.android.com/reference/kotlin/androidx/xr/glimmer/Typography#caption()) style for its text.
+- The title chip isn't interactive. If you need a clickable label, use a [`Button`](https://developer.android.com/reference/kotlin/androidx/xr/glimmer/Button.composable) or another interactive component.