ngp-accessibility 1.0.3 → 1.0.6

package/README.md

@@ -5,6 +5,7 @@ React accessibility package with translation, text sizing, contrast modes, and v
 ## Features
 
 - 🌐 Multi-language support (English, Tagalog, Cebuano/Visayan)
+- 🌐 Google auto-translation for page content with manual UI fallback
 - 📏 Text size adjustment (increase/decrease)
 - 🎨 High contrast mode
 - 🔄 Negative contrast mode
@@ -31,9 +32,11 @@ import "ngp-accessibility/dist/styles.css";
 
 function App() {
   return (
-    <AccessibilityProvider>
+    <AccessibilityProvider googleTranslateTargetSelector="main">
       <AccessibilityToolbar />
-      <YourContent />
+      <main>
+        <YourContent />
+      </main>
     </AccessibilityProvider>
   );
 }
@@ -50,11 +53,13 @@ import "ngp-accessibility/dist/styles.css";
 
 function App() {
   return (
-    <AccessibilityProvider>
+    <AccessibilityProvider googleTranslateTargetSelector="#page-content">
       <div style={{ textAlign: "right", padding: "10px" }}>
         <AccessibilityDropdown />
       </div>
-      <YourContent />
+      <section id="page-content">
+        <YourContent />
+      </section>
     </AccessibilityProvider>
   );
 }
@@ -78,11 +83,102 @@ When voice command is enabled, you can use:
 
 Wrap your app with this provider.
 
+Props:
+
+- `translations`: Manual translations for your own keyed content through `t()`.
+- `googleTranslateTargetSelector`: CSS selector for the DOM subtree that should be eligible for Google auto-translation. Defaults to `main`.
+
+Example:
+
+```tsx
+<AccessibilityProvider googleTranslateTargetSelector="#article-content">
+  <Header />
+  <AccessibilityDropdown />
+  <div id="article-content">
+    <ArticlePage />
+  </div>
+</AccessibilityProvider>
+```
+
+Only the subtree matched by `googleTranslateTargetSelector` should contain the content you want Google to translate. Elements outside that path are marked as `notranslate`.
+
+### Language Behavior
+
+`setLanguage(lang)` updates the current language state once, and the package applies that language in 3 different ways:
+
+1. Toolbar and dropdown UI labels use `translate(key)`.
+2. Your app's keyed content uses `t(key)`.
+3. Google Translate auto-translates the subtree matched by `googleTranslateTargetSelector`.
+
+This means the package now supports 2 language modes:
+
+- Manual UI language: If the selected language exists in the built-in package dictionary, the accessibility controls use those manual labels.
+- Google-only language: If the selected language does not have a built-in package dictionary, the accessibility controls fall back to English while Google still translates the page content.
+
+Example:
+
+- `tl`: package UI uses manual Tagalog labels, and page content can also be translated.
+- `ja`: package UI falls back to English unless you add manual Japanese labels, while Google translates the selected page subtree to Japanese.
+
+### Manual Translation For Specific Content
+
+Yes, this setup is more flexible when you want manual translations only for specific components or content.
+
+Use `translations` plus `t(key)` when you want full control over exact wording in your own app content. Use Google Translate for the rest of the page content inside your translation target.
+
+Example:
+
+```tsx
+const myTranslations = {
+  en: {
+    heroTitle: "Welcome",
+    heroBody: "This section is manually translated.",
+  },
+  ja: {
+    heroTitle: "ようこそ",
+    heroBody: "このセクションは手動で翻訳されています。",
+  },
+};
+
+function Hero() {
+  const { t } = useAccessibility();
+
+  return (
+    <section>
+      <h1>{t("heroTitle")}</h1>
+      <p>{t("heroBody")}</p>
+    </section>
+  );
+}
+
+function App() {
+  return (
+    <AccessibilityProvider
+      translations={myTranslations}
+      googleTranslateTargetSelector="main"
+    >
+      <AccessibilityDropdown />
+      <main>
+        <Hero />
+        <OtherPageContent />
+      </main>
+    </AccessibilityProvider>
+  );
+}
+```
+
+In that setup:
+
+- `Hero` can use your manual translations through `t(key)`.
+- other content inside `main` can still be translated by Google.
+- the accessibility toolbar/dropdown uses built-in package labels when available, otherwise English fallback.
+
 ### useAccessibility()
 
 Hook that returns:
 
 - `language`, `setLanguage(lang)`
+- `hasManualTranslations`
 - `textSize`, `increaseText()`, `decreaseText()`
 - `highContrast`, `toggleHighContrast()`
 - `negativeContrast`, `toggleNegativeContrast()`
@@ -90,7 +186,8 @@ Hook that returns:
 - `underlineLinks`, `toggleUnderlineLinks()`
 - `readableFont`, `toggleReadableFont()`
 - `voiceEnabled`, `toggleVoice()`
-- `translate(key)` - Get translated text
+- `translate(key)` - Get translated package UI text with English fallback
+- `t(key)` - Get your app-specific manual text for the current language, then fall back to English, then the raw key
 
 ### AccessibilityToolbar
 

package/dist/AccessibilityContext.d.ts

@@ -1,31 +1,50 @@
 import React, { ReactNode } from "react";
 import { Language, TranslationKey } from "./translations";
+export type ColorBlindMode = "none" | "protanopia" | "deuteranopia" | "tritanopia";
 interface AccessibilityState {
     language: Language;
     textSize: number;
+    textMagnifier: boolean;
+    pauseAnimations: boolean;
+    readingGuide: boolean;
     highContrast: boolean;
     negativeContrast: boolean;
     lightBackground: boolean;
     underlineLinks: boolean;
+    highlightTitles: boolean;
     readableFont: boolean;
     voiceEnabled: boolean;
+    readAloud: boolean;
+    colorBlindMode: ColorBlindMode;
+    focusIndicator: boolean;
 }
 interface AccessibilityContextType extends AccessibilityState {
     setLanguage: (lang: Language) => void;
     increaseText: () => void;
     decreaseText: () => void;
+    toggleTextMagnifier: () => void;
+    togglePauseAnimations: () => void;
+    toggleReadingGuide: () => void;
     toggleHighContrast: () => void;
     toggleNegativeContrast: () => void;
     toggleLightBackground: () => void;
     toggleUnderlineLinks: () => void;
+    toggleHighlightTitles: () => void;
     toggleReadableFont: () => void;
     toggleVoice: () => void;
+    toggleReadAloud: () => void;
+    setColorBlindMode: (mode: ColorBlindMode) => void;
+    toggleFocusIndicator: () => void;
+    hasManualTranslations: boolean;
     translate: (key: TranslationKey) => string;
     t: (key: string) => string;
 }
-interface AccessibilityProviderProps {
+export interface AccessibilityProviderProps {
     children: ReactNode;
     translations?: Partial<Record<Language, Record<string, string>>>;
+    googleTranslateTargetSelector?: string;
+    /** @deprecated Use googleTranslateTargetSelector instead. */
+    translationTargetSelector?: string;
 }
 export declare const AccessibilityProvider: React.FC<AccessibilityProviderProps>;
 export declare const useAccessibility: () => AccessibilityContextType;

package/dist/AccessibilityDropdown.d.ts

@@ -1,24 +1,45 @@
 import React from "react";
 export interface AccessibilityDropdownClasses {
     root?: string;
+    title?: string;
+    trigger?: string;
+    panel?: string;
     toggle?: string;
-    menu?: string;
     section?: string;
-    label?: string;
-    select?: string;
+    sectionHeader?: string;
     button?: string;
     activeButton?: string;
-    voiceButton?: string;
+    select?: string;
+    menu?: string;
 }
 export interface AccessibilityDropdownProps {
     className?: string;
     style?: React.CSSProperties;
     classes?: AccessibilityDropdownClasses;
-    triggerLabel?: React.ReactNode;
-    renderTrigger?: (params: {
+    triggerLabel?: string;
+    renderTrigger?: (props: {
         isOpen: boolean;
         toggle: () => void;
         className: string;
     }) => React.ReactNode;
 }
+export interface AccessibilityDropdownClasses {
+    root?: string;
+    trigger?: string;
+    panel?: string;
+    panelHeader?: string;
+    closeButton?: string;
+}
+export interface AccessibilityDropdownRenderTriggerProps {
+    isOpen: boolean;
+    toggle: () => void;
+    className: string;
+}
+export interface AccessibilityDropdownProps {
+    className?: string;
+    style?: React.CSSProperties;
+    classes?: AccessibilityDropdownClasses;
+    triggerLabel?: string;
+    renderTrigger?: (props: AccessibilityDropdownRenderTriggerProps) => React.ReactNode;
+}
 export declare const AccessibilityDropdown: React.FC<AccessibilityDropdownProps>;

package/dist/index.d.ts

@@ -3,6 +3,7 @@ export { AccessibilityToolbar } from "./AccessibilityToolbar";
 export { AccessibilityDropdown } from "./AccessibilityDropdown";
 export { T } from "./T";
 export { translations, type Language, type TranslationKey, } from "./translations";
+export type { AccessibilityProviderProps } from "./AccessibilityContext";
 export type { AccessibilityToolbarProps, AccessibilityToolbarClasses, } from "./AccessibilityToolbar";
 export type { AccessibilityDropdownProps, AccessibilityDropdownClasses, } from "./AccessibilityDropdown";
 export type { default as React } from "react";