@amazon-devices/kepler-a11y-settings-interface-turbo 1.0.0-rn-83

package/LICENSE

@@ -0,0 +1,7 @@
+Copyright 2025 Amazon.com, Inc. or its affiliates.  All rights reserved.
+
+These materials are licensed as "Program Materials" under the Program Materials License Agreement (the "Agreement").  The Agreement is available at https://developer.amazon.com/support/legal/pml.  See the Agreement for the specific terms and conditions of the Agreement.  Capitalized terms not defined in this file have the meanings given to them in the Agreement.  
+
+If you do not agree to the above terms and conditions, you may not use any file in this package. 
+
+YOUR USE OF THE PROGRAM MATERIALS IN OR ASSOCIATED WITH THIS PACKAGE IS AT YOUR SOLE RISK.  IN NO EVENT WILL AMAZON BE LIABLE FOR ANY DAMAGES, INCLUDING WITHOUT LIMITATION ANY DIRECT, INDIRECT, CONSEQUENTIAL, SPECIAL, INCIDENTAL, OR PUNITIVE DAMAGES (INCLUDING FOR ANY LOSS OF GOODWILL, BUSINESS INTERRUPTION, LOST PROFITS OR DATA, OR COMPUTER FAILURE OR MALFUNCTION) ARISING FROM OR RELATING TO SUCH PROGRAM MATERIALS, HOWEVER CAUSED AND REGARDLESS OF THE THEORY OF LIABILITY, EVEN IF AMAZON HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.  THESE LIMITATIONS AND DISCLAIMERS APPLY EXCEPT TO THE EXTENT PROHIBITED BY APPLICABLE LAW.

package/README.md

@@ -0,0 +1,230 @@
+# Overview
+@amazon-devices/kepler-a11y-settings-interface-turbo provides accessibility settings APIs and UI scaling hooks for Kepler applications.
+
+# Getting Started
+
+## Installation
+In the package.json file, add the @amazon-devices/kepler-a11y-settings-interface-turbo package as a dependency:
+
+From the command line, run the following:
+
+```bash
+npm install @amazon-devices/kepler-a11y-settings-interface-turbo
+```
+
+Or, you can manually edit the package.json file as shown:
+
+```json
+"dependencies": {
+  ...
+  "@amazon-devices/kepler-a11y-settings-interface-turbo": "1.x", // or latest major version
+  ...
+}
+```
+
+Then run `npm install`.
+
+# Usage
+
+## Settings Getters, Setters, and Listeners
+
+### Basic Settings Management
+Use the KeplerA11ySettingsInterface to get, set, and listen for accessibility setting changes:
+
+```typescript
+import KeplerA11ySettingsInterface from '@amazon-devices/kepler-a11y-settings-interface-turbo';
+
+// Get current settings (getter methods return Promises)
+KeplerA11ySettingsInterface.isScreenReaderEnabled().then(isEnabled => {
+  console.log('Screen reader enabled:', isEnabled);
+});
+
+KeplerA11ySettingsInterface.getUiScaleSetting().then(scale => {
+  console.log('Current UI scale:', scale);
+});
+
+KeplerA11ySettingsInterface.getColorCorrectionMode().then(mode => {
+  console.log('Color correction mode:', mode);
+});
+
+// Set settings (requires com.amazon.devconf.privilege.accessibility.write permission)
+await KeplerA11ySettingsInterface.setScreenReaderEnabled(true);
+await KeplerA11ySettingsInterface.setUiScaleSetting(3);
+await KeplerA11ySettingsInterface.setColorCorrectionMode('deuteranomaly');
+```
+
+### Event Listeners
+Add listeners to respond to accessibility setting changes. Listener registration and
+removal methods are asynchronous and return Promises:
+
+```typescript
+import KeplerA11ySettingsInterface from '@amazon-devices/kepler-a11y-settings-interface-turbo';
+
+// Listen for screen reader state changes
+const handleScreenReaderChange = (enabled: boolean) => {
+  console.log(`Screen reader ${enabled ? 'enabled' : 'disabled'}`);
+  // Respond to screen reader state
+};
+
+const success = await KeplerA11ySettingsInterface.addScreenReaderStateListener(handleScreenReaderChange);
+if (!success) {
+  console.warn('Failed to register screen reader listener');
+}
+
+// Remember to remove listeners when component unmounts
+await KeplerA11ySettingsInterface.removeScreenReaderStateListener();
+```
+
+### Captioning Preferences
+Manage closed captioning settings:
+
+```typescript
+import KeplerA11ySettingsInterface, { CaptioningProps } from '@amazon-devices/kepler-a11y-settings-interface-turbo';
+
+// Get current captioning preferences
+KeplerA11ySettingsInterface.getCaptionPreferences().then(captionPrefs => {
+  console.log('Current caption preferences:', captionPrefs);
+});
+
+// Set captioning preferences
+const newPrefs: CaptioningProps = {
+  textSize: 'large',
+  textColor: 'white',
+  textFont: 'sans_serif',
+  textEdgeStyle: 'drop_shadowed',
+  textOpacity: 'percent_100'
+};
+
+await KeplerA11ySettingsInterface.setCaptionPreferences(newPrefs);
+```
+
+## UI Scale Setting Hooks
+
+### React Hooks for Dynamic Scaling
+Use the provided hooks to create responsive UI that automatically adapts to scale setting changes.
+These hooks are necessary where UI sizes are defined, in the case that the associated UI element should
+scale.
+
+If you are using UI elements that have already wrapped underlying predefined sizes with these hooks,
+you simply need to wrap your App definition in the UiScaleSettingContextProvider.
+
+```typescript
+import React from 'react';
+import { View, StyleSheet } from 'react-native';
+import { 
+  UiScaleSettingContextProvider, 
+  useScaledSize, 
+  useScalingMultiplier,
+  useUiScaleSetting 
+} from '@amazon-devices/kepler-a11y-settings-interface-turbo';
+
+const CONTENT_WIDTH_DEFAULT_BASE = 144;
+const CONTENT_HEIGHT_DEFAULT_BASE = 80;
+const LOGO_DEFAULT_WIDTH = 57;
+const LOGO_DEFAULT_HEIGHT = 24;
+
+const styles = StyleSheet.create({
+  viewStyle: {
+    marginLeft: 8,
+    alignItems: 'center',
+    zIndex: 0,
+  },
+  text: {
+    fontSize: 14,
+    color: '#666',
+    fontFamily: 'sans-serif',
+  },
+});
+
+const App = () => {
+  // Get scaled dimensions that automatically update when scale setting changes
+  const contentWidthDefault = useScaledSize(CONTENT_WIDTH_DEFAULT_BASE, { 
+    itemType: 'medium_upscale' 
+  });
+  const contentHeightDefault = useScaledSize(CONTENT_HEIGHT_DEFAULT_BASE, { 
+    itemType: 'medium_upscale' 
+  });
+  
+  // Get scaling multiplier for related dimensions
+  const assetScalingMultiplier = useScalingMultiplier(LOGO_DEFAULT_WIDTH, { 
+    itemType: 'image' 
+  });
+
+  // Memoize the style sheet so it only updates when the contentWidthDefault or
+  // contentHeightDefault change via the useScaledSize hook.
+  const viewStyle = React.useMemo(
+    () => ({
+      ...styles.viewStyle,
+      width: contentWidthDefault,
+      height: contentHeightDefault,
+    }),
+    [contentWidthDefault, contentHeightDefault],
+  );
+
+  // Memoize the style sheet so it only updates when the assetScalingMultiplier
+  // changes via the useScalingMultiplier hook.
+  const assetStyle = React.useMemo(
+    () => ({
+      width: LOGO_DEFAULT_WIDTH * assetScalingMultiplier,
+      height: LOGO_DEFAULT_HEIGHT * assetScalingMultiplier,
+      marginRight: 12,
+    }),
+    [assetScalingMultiplier],
+  );
+
+  // Get current scale factor to display below
+  const currentScale = useUiScaleSetting();
+
+  return (
+    <View style={viewStyle}>
+      <Image style={assetStyle} source={logoSource} />
+      <Text style={styles.text}>Current scale: {currentScale}</Text>
+    </View>
+  );
+};
+
+// Wrap your app with the provider.  This will cause all UI elements utilizing
+// the useScaledSize and useScalingMultiplier hooks to respond dynamically to
+// UiScaleSetting setting changes, even if the UI element is imported from another
+// library.
+const AppWithProvider = () => (
+  <UiScaleSettingContextProvider>
+    <App />
+  </UiScaleSettingContextProvider>
+);
+
+export default AppWithProvider;
+```
+
+### Scaling Types
+The library supports different scaling behaviors for various UI elements:
+
+- `'low_upscale'` - Large items that scale minimally (e.g., cards)
+- `'medium_upscale'` - Standard UI elements with moderate scaling
+- `'large_upscale'` - Small elements that need significant scaling (e.g., buttons)
+- `'low_downscale'` - Whitespace that reduces at higher scales
+- `'large_downscale'` - Large padding that reduces dramatically
+- `'text'` - Text elements with corresponding line height scaling
+- `'image'` - Images and visual assets
+
+### Advanced Scaling Options
+Control scaling limits with optional parameters:
+
+```typescript
+const scaledWidth = useScaledSize(100, {
+  itemType: 'medium_upscale',
+  maxSize: 200,  // Never exceed 200 units
+  minSize: 50    // Never go below 50 units
+});
+```
+
+### Density Independent Pixels (DIP)
+
+The scaling APIs (`useScaledSize`, `useScalingMultiplier`, `getScaledSize`, `getScalingMultiplier`)
+support both Density Independent Pixel (DIP) and physical pixel inputs, depending on whether the
+consuming application has enabled the `PLATFORM_DENSITY_INDEPENDENT_PIXEL` runtime feature flag
+in its `react-native.config.js`.
+
+- **DIP enabled** (`PLATFORM_DENSITY_INDEPENDENT_PIXEL: true`): Size values passed to the scaling
+  APIs are expected to be in density-independent pixels.
+- **DIP not enabled**: Size values are expected to be in physical pixels.

package/dist/kepler/tm-manifest.json

@@ -0,0 +1 @@
+{"schema":1,"fileSets":{"native":[{"arch":"aarch64","variant":"release","directoryPath":"aarch64-release"},{"arch":"armv7","variant":"release","directoryPath":"armv7-release"},{"arch":"x86_64","variant":"release","directoryPath":"x86_64-release"},{"arch":"aarch64","variant":"debug","directoryPath":"aarch64-debug"},{"arch":"armv7","variant":"debug","directoryPath":"armv7-debug"},{"arch":"x86_64","variant":"debug","directoryPath":"x86_64-debug"}]}}

package/dist/src/KeplerA11ySettingsInterface.d.ts

@@ -0,0 +1,309 @@
+/**
+ * Copyright (c) 2025 - 2026 Amazon.com, Inc. or its affiliates. All Rights Reserved.
+ *
+ * PROPRIETARY/CONFIDENTIAL
+ *
+ * Use is subject to license terms.
+ *
+ */
+import type { UiScaleSetting, ScalingProps, ColorCorrectionMode, TimeoutMultiplier, CaptionTextSize, CaptionColor, CaptionFont, CaptionEdgeStyle, CaptionOpacity, CaptioningProps, ItemScalingType } from './turbo-modules/KeplerA11ySettingsInterfaceTurbo';
+declare class KeplerA11ySettingsInterface {
+    private __eventEmitter;
+    private __uiScaleSettingListener;
+    private __screenReaderStateListener;
+    private __screenMagnifierStateListener;
+    private __textBannerStateListener;
+    private __colorInversionStateListener;
+    private __colorCorrectionModeListener;
+    private __highContrastTextStateListener;
+    private __audioDescriptionStateListener;
+    private __timeToTakeActionListener;
+    private __closedCaptioningStateListener;
+    private __captioningPreferencesListener;
+    constructor();
+    /**
+     * Adds a listener for UI scale setting changes.
+     * If a listener is already registered, it will be removed and replaced with the new one.
+     * @param handler Callback function invoked on the main thread when UI scale setting changes
+     * @returns Promise that resolves to boolean representing if listener registered successfully.
+     */
+    addUiScaleSettingListener(handler: (newScaleSetting: UiScaleSetting) => void): Promise<boolean>;
+    /**
+     * Removes the UI scale setting listener.
+     * @returns Promise that resolves when the listener has been removed.
+     */
+    removeUiScaleSettingListener(): Promise<void>;
+    /**
+     * Adds a listener for screen reader state changes.
+     * If a listener is already registered, it will be removed and replaced with the new one.
+     * @param handler Callback function invoked on the main thread when screen reader state changes
+     * @returns Promise that resolves to boolean representing if listener registered successfully.
+     */
+    addScreenReaderStateListener(handler: (enabled: boolean) => void): Promise<boolean>;
+    /**
+     * Removes the screen reader state listener.
+     * @returns Promise that resolves when the listener has been removed.
+     */
+    removeScreenReaderStateListener(): Promise<void>;
+    /**
+     * Adds a listener for screen magnifier state changes.
+     * If a listener is already registered, it will be removed and replaced with the new one.
+     * @param handler Callback function invoked on the main thread when screen magnifier state changes
+     * @returns Promise that resolves to boolean representing if listener registered successfully.
+     */
+    addScreenMagnifierStateListener(handler: (enabled: boolean) => void): Promise<boolean>;
+    /**
+     * Removes the screen magnifier state listener.
+     * @returns Promise that resolves when the listener has been removed.
+     */
+    removeScreenMagnifierStateListener(): Promise<void>;
+    /**
+     * Adds a listener for text banner state changes.
+     * If a listener is already registered, it will be removed and replaced with the new one.
+     * @param handler Callback function invoked on the main thread when text banner state changes
+     * @returns Promise that resolves to boolean representing if listener registered successfully.
+     */
+    addTextBannerStateListener(handler: (enabled: boolean) => void): Promise<boolean>;
+    /**
+     * Removes the text banner state listener.
+     * @returns Promise that resolves when the listener has been removed.
+     */
+    removeTextBannerStateListener(): Promise<void>;
+    /**
+     * Adds a listener for color inversion state changes.
+     * If a listener is already registered, it will be removed and replaced with the new one.
+     * @param handler Callback function invoked on the main thread when color inversion state changes
+     * @returns Promise that resolves to boolean representing if listener registered successfully.
+     */
+    addColorInversionStateListener(handler: (enabled: boolean) => void): Promise<boolean>;
+    /**
+     * Removes the color inversion state listener.
+     * @returns Promise that resolves when the listener has been removed.
+     */
+    removeColorInversionStateListener(): Promise<void>;
+    /**
+     * Adds a listener for color correction mode changes.
+     * If a listener is already registered, it will be removed and replaced with the new one.
+     * @param handler Callback function invoked on the main thread when color correction mode changes
+     * @returns Promise that resolves to boolean representing if listener registered successfully.
+     */
+    addColorCorrectionModeListener(handler: (mode: ColorCorrectionMode) => void): Promise<boolean>;
+    /**
+     * Removes the color correction mode listener.
+     * @returns Promise that resolves when the listener has been removed.
+     */
+    removeColorCorrectionModeListener(): Promise<void>;
+    /**
+     * Adds a listener for high contrast text state changes.
+     * If a listener is already registered, it will be removed and replaced with the new one.
+     * @param handler Callback function invoked on the main thread when high contrast text state changes
+     * @returns Promise that resolves to boolean representing if listener registered successfully.
+     */
+    addHighContrastTextStateListener(handler: (enabled: boolean) => void): Promise<boolean>;
+    /**
+     * Removes the high contrast text state listener.
+     * @returns Promise that resolves when the listener has been removed.
+     */
+    removeHighContrastTextStateListener(): Promise<void>;
+    /**
+     * Adds a listener for audio description state changes.
+     * If a listener is already registered, it will be removed and replaced with the new one.
+     * @param handler Callback function invoked on the main thread when audio description state changes
+     * @returns Promise that resolves to boolean representing if listener registered successfully.
+     */
+    addAudioDescriptionStateListener(handler: (enabled: boolean) => void): Promise<boolean>;
+    /**
+     * Removes the audio description state listener.
+     * @returns Promise that resolves when the listener has been removed.
+     */
+    removeAudioDescriptionStateListener(): Promise<void>;
+    /**
+     * Adds a listener for time to take action changes.
+     * If a listener is already registered, it will be removed and replaced with the new one.
+     * @param handler Callback function invoked on the main thread when time to take action changes
+     * @returns Promise that resolves to boolean representing if listener registered successfully.
+     */
+    addTimeToTakeActionListener(handler: (value: TimeoutMultiplier) => void): Promise<boolean>;
+    /**
+     * Removes the time to take action listener.
+     * @returns Promise that resolves when the listener has been removed.
+     */
+    removeTimeToTakeActionListener(): Promise<void>;
+    /**
+     * Adds a listener for closed captioning state changes.
+     * If a listener is already registered, it will be removed and replaced with the new one.
+     * @param handler Callback function invoked on the main thread when closed captioning state changes
+     * @returns Promise that resolves to boolean representing if listener registered successfully.
+     */
+    addClosedCaptioningStateListener(handler: (enabled: boolean) => void): Promise<boolean>;
+    /**
+     * Removes the closed captioning state listener.
+     * @returns Promise that resolves when the listener has been removed.
+     */
+    removeClosedCaptioningStateListener(): Promise<void>;
+    /**
+     * Adds a listener for captioning preferences changes.
+     * If a listener is already registered, it will be removed and replaced with the new one.
+     * @param handler Callback function invoked on the main thread when captioning preferences change
+     * @returns Promise that resolves to boolean representing if listener registered successfully.
+     */
+    addCaptioningPreferencesListener(handler: (preferences: CaptioningProps) => void): Promise<boolean>;
+    /**
+     * Removes the captioning preferences listener.
+     * @returns Promise that resolves when the listener has been removed.
+     */
+    removeCaptioningPreferencesListener(): Promise<void>;
+    /**
+     * Gets the scaling multiplier for the given original size and scaling properties.
+     *
+     * This method should be used to retrieve a scale factor, which can be applied to related
+     * values that do not have the same scaling properties, like the height and width of an image.
+     *
+     * Note: Prefer using the useScalingMultiplier hook from UiScaleSettingContextProvider.
+     *
+     * @param originalSize The original size to scale (in DIP if PLATFORM_DENSITY_INDEPENDENT_PIXEL
+     *   is enabled, or in physical pixels otherwise)
+     * @param scalingProps Properties that define how scaling should be applied
+     * @returns Promise that resolves to the scaling multiplier
+     */
+    getScalingMultiplier(originalSize: number, scalingProps: ScalingProps): Promise<number>;
+    /**
+     * Gets the scaled size for the given original size and scaling properties.
+     *
+     * Note: Prefer using the useScaledSize hook from UiScaleSettingContextProvider.
+     *
+     * @param originalSize The original size to scale (in DIP if PLATFORM_DENSITY_INDEPENDENT_PIXEL
+     *   is enabled, or in physical pixels otherwise)
+     * @param scalingProps Properties that define how scaling should be applied
+     * @returns Promise that resolves to the scaled size
+     */
+    getScaledSize(originalSize: number, scalingProps: ScalingProps): Promise<number>;
+    /**
+     * Gets the current UI scale setting.
+     *
+     * Note: Prefer using the useUiScaleSetting hook from UiScaleSettingContextProvider.
+     *
+     * @returns Promise that resolves to the current UI scale setting
+     */
+    getUiScaleSetting(): Promise<UiScaleSetting>;
+    /**
+     * Checks if screen reader is enabled.
+     * @returns Promise that resolves to true if screen reader is enabled, false otherwise
+     */
+    isScreenReaderEnabled(): Promise<boolean>;
+    /**
+     * Checks if screen magnifier is enabled.
+     * @returns Promise that resolves to true if screen magnifier is enabled, false otherwise
+     */
+    isScreenMagnifierEnabled(): Promise<boolean>;
+    /**
+     * Checks if text banner is enabled.
+     * @returns Promise that resolves to true if text banner is enabled, false otherwise
+     */
+    isTextBannerEnabled(): Promise<boolean>;
+    /**
+     * Checks if color inversion is enabled.
+     * @returns Promise that resolves to true if color inversion is enabled, false otherwise
+     */
+    isColorInversionEnabled(): Promise<boolean>;
+    /**
+     * Gets the current color correction mode.
+     * @returns Promise that resolves to the current color correction mode
+     */
+    getColorCorrectionMode(): Promise<ColorCorrectionMode>;
+    /**
+     * Checks if high contrast text is enabled.
+     * @returns Promise that resolves to true if high contrast text is enabled, false otherwise
+     */
+    isHighContrastTextEnabled(): Promise<boolean>;
+    /**
+     * Checks if audio description is preferred.
+     * @returns Promise that resolves to true if audio description is preferred, false otherwise
+     */
+    isAudioDescriptionPreferred(): Promise<boolean>;
+    /**
+     * Gets the current time to take action setting.
+     * @returns Promise that resolves to the current timeout multiplier
+     */
+    getTimeToTakeAction(): Promise<TimeoutMultiplier>;
+    /**
+     * Checks if closed captioning is enabled.
+     * @returns Promise that resolves to true if closed captioning is enabled, false otherwise
+     */
+    isClosedCaptioningEnabled(): Promise<boolean>;
+    /**
+     * Gets all captioning preferences.
+     * @returns Promise that resolves to object containing all captioning preference settings
+     */
+    getCaptionPreferences(): Promise<CaptioningProps>;
+    /**
+     * Sets the screen reader enabled state.
+     * Requires com.amazon.devconf.privilege.accessibility.write permission.
+     * @param enabled true to enable screen reader, false to disable
+     */
+    setScreenReaderEnabled(enabled: boolean): Promise<void>;
+    /**
+     * Sets the screen magnifier enabled state.
+     * Requires com.amazon.devconf.privilege.accessibility.write permission.
+     * @param enabled true to enable screen magnifier, false to disable
+     */
+    setScreenMagnifierEnabled(enabled: boolean): Promise<void>;
+    /**
+     * Sets the text banner enabled state.
+     * Requires com.amazon.devconf.privilege.accessibility.write permission.
+     * @param enabled true to enable text banner, false to disable
+     */
+    setTextBannerEnabled(enabled: boolean): Promise<void>;
+    /**
+     * Sets the color inversion enabled state.
+     * Requires com.amazon.devconf.privilege.accessibility.write permission.
+     * @param enabled true to enable color inversion, false to disable
+     */
+    setColorInversionEnabled(enabled: boolean): Promise<void>;
+    /**
+     * Sets the color correction mode.
+     * Requires com.amazon.devconf.privilege.accessibility.write permission.
+     * @param mode The color correction mode to set
+     */
+    setColorCorrectionMode(mode: ColorCorrectionMode): Promise<void>;
+    /**
+     * Sets the high contrast text enabled state.
+     * Requires com.amazon.devconf.privilege.accessibility.write permission.
+     * @param enabled true to enable high contrast text, false to disable
+     */
+    setHighContrastTextEnabled(enabled: boolean): Promise<void>;
+    /**
+     * Sets the audio description preference.
+     * Requires com.amazon.devconf.privilege.accessibility.write permission.
+     * @param enabled true to prefer audio description, false otherwise
+     */
+    setAudioDescriptionPreferred(enabled: boolean): Promise<void>;
+    /**
+     * Sets the time to take action multiplier.
+     * Requires com.amazon.devconf.privilege.accessibility.write permission.
+     * @param multiplier The timeout multiplier to set
+     */
+    setTimeToTakeAction(multiplier: TimeoutMultiplier): Promise<void>;
+    /**
+     * Sets the UI scale setting.
+     * Requires com.amazon.devconf.privilege.accessibility.write permission.
+     * @param setting The UI scale setting to set
+     */
+    setUiScaleSetting(setting: UiScaleSetting): Promise<void>;
+    /**
+     * Sets the closed captioning enabled state.
+     * Requires com.amazon.devconf.privilege.accessibility.write permission.
+     * @param enabled true to enable closed captioning, false to disable
+     */
+    setClosedCaptioningEnabled(enabled: boolean): Promise<void>;
+    /**
+     * Sets multiple captioning preferences at once.
+     * Requires com.amazon.devconf.privilege.accessibility.write permission.
+     * @param prefs Object containing captioning preference settings to update.
+     * Only the properties present in the object will be updated.
+     */
+    setCaptionPreferences(prefs: CaptioningProps): Promise<void>;
+}
+declare const _default: KeplerA11ySettingsInterface;
+export default _default;
+export type { UiScaleSetting, ItemScalingType, ScalingProps, ColorCorrectionMode, TimeoutMultiplier, CaptionTextSize, CaptionColor, CaptionFont, CaptionEdgeStyle, CaptionOpacity, CaptioningProps };