@controleonline/ui-common 1.2.98 → 1.2.100

package/docs/homepage-1056.md

@@ -0,0 +1,12 @@
+# Homepage ADMIN/MANAGER — app-community#1056
+
+Soft appearance is opt-in for HomePage only. Existing menu routes/parameters, permissions, stores and translations are preserved. App-provided homepage colors and components are used only in this appearance. Default consumers retain their current behavior.
+
+Source: https://github.com/ControleOnline/app-community/issues/1056
+Local evidence: 40 homepage tests and 34 runtime footer/zoom tests passed. No production authorization.
+
+## Web login translation bootstrap
+
+Keep the navigation tree mounted while translations initialize. Hide the shell and disable pointer/accessibility interaction until the existing translation readiness contract succeeds. Unmounting navigation during login resets its route and repeatedly mounts/registers the bottom bar, causing React maximum update depth. No route, permission, translation source, theme or zoom changes. Native behavior is unchanged.
+
+Regression evidence: app-community homepage bootstrapNavigation.test.js reproduced maximum update depth before the fix, then passed after it. 44 tests across 9 homepage suites passed. Runtime Dev reproduced the unfixed bug; new runtime verification is required after consuming ui-common 1.2.95.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@controleonline/ui-common",
-  "version": "1.2.98",
+  "version": "1.2.100",
   "author": "ControleOnline",
   "description": "ControleOnline Common Quasar UI Component",
   "license": "MIT",

package/src/api/index.js

@@ -1,3 +1,4 @@
+import {readStoredSessionToken} from '@controleonline/ui-common/src/utils/storedSessionToken';
 import myFetch from '@controleonline/ui-common/src/api/fetch';
 import axios from 'axios';
 import {env as APP_ENV} from '@env';
@@ -215,8 +216,8 @@ async function requestSmokeUrl(url, options) {
 export const api = {
   device: JSON.parse(localStorage.getItem('device') || '{}'),
   masterDevice: JSON.parse(localStorage.getItem('master-device') || '{}'),
-
-
+
+
   upload: async function (uri, formData) {
     const token = await this.getToken();
     const appDomain = resolveAppDomain(APP_ENV.DOMAIN);
@@ -242,8 +243,8 @@ export const api = {
   fetch: async function (uri, options = {}) {
     if (typeof options.headers === 'undefined')
       Object.assign(options, { headers: new Headers() });
-
-    // Always refresh device from localStorage in case it was set after module load
+
+    // Always refresh device from localStorage in case it was set after module load
     try {
       this.device = JSON.parse(localStorage.getItem('device') || '{}');
     } catch (e) {
@@ -270,16 +271,16 @@ export const api = {
     if (options.body) {
       if (typeof options.body === 'object') {
         bodyDeviceId = options.body.device || null;
-      } else if (typeof options.body === 'string') {
-        try {
-          const parsedBody = JSON.parse(options.body);
-          bodyDeviceId = parsedBody?.device || null;
-        } catch (e) {
-          bodyDeviceId = null;
-        }
-      }
-    }
-
+      } else if (typeof options.body === 'string') {
+        try {
+          const parsedBody = JSON.parse(options.body);
+          bodyDeviceId = parsedBody?.device || null;
+        } catch (e) {
+          bodyDeviceId = null;
+        }
+      }
+    }
+
     const requestDevice = resolveRequestDevice(
       this.masterDevice,
       this.device,
@@ -296,10 +297,10 @@ export const api = {
         options.headers.set('DEVICE-TYPE', requestDeviceType);
       }
     }
-    if (options.responseType != 'text') {
-      options.headers.set('Content-Type', MIME_TYPE);
-      options.headers.set('Accept', MIME_TYPE);
-    }
+    if (options.responseType != 'text') {
+      options.headers.set('Content-Type', MIME_TYPE);
+      options.headers.set('Accept', MIME_TYPE);
+    }
     options.headers.set('App-Domain', resolveAppDomain(APP_ENV.DOMAIN));
 
     if (options.body && typeof options.body != 'string') {
@@ -310,28 +311,13 @@ export const api = {
     if (options.params) {
       uri = this.buildQueryString(uri, options);
     }
-    return myFetch(uri, options).catch(e => {
-      throw e;
-    });
-  },
-  async getToken() {
-    const sessionString = localStorage.getItem('session');
-    let session = null;
-    if (sessionString) {
-      try {
-        const cleanString =
-          typeof sessionString == 'string' &&
-            sessionString.startsWith('__q_objt|')
-            ? sessionString.substring('__q_objt|'.length)
-            : sessionString;
-        session = JSON.parse(cleanString); // Transforma a string em objeto
-      } catch (e) {
-        console.error('Failed to parse session from localStorage', e);
-      }
-    }
-
-    return session?.token || session?.api_key;
-  },
+    return myFetch(uri, options).catch(e => {
+      throw e;
+    });
+  },
+  async getToken() {
+    return readStoredSessionToken();
+  },
   serialize(obj, prefix = '') {
     const pairs = [];
 
@@ -344,12 +330,12 @@ export const api = {
 
         const value = obj[key];
         let fullKey = prefix ? `${prefix}.${key}` : key; // Usa ponto para objetos
-
-        if (value === null || value === undefined) {
-          pairs.push(`${fullKey}=`);
-        } else if (typeof value === 'object' && !Array.isArray(value)) {
-          // Objeto aninhado: chama serialize recursivamente com ponto
-          pairs.push(...this.serialize(value, fullKey));
+
+        if (value === null || value === undefined) {
+          pairs.push(`${fullKey}=`);
+        } else if (typeof value === 'object' && !Array.isArray(value)) {
+          // Objeto aninhado: chama serialize recursivamente com ponto
+          pairs.push(...this.serialize(value, fullKey));
         } else if (Array.isArray(value)) {
           // Array: adiciona [] e itera sobre os valores
           if (value.length === 0) {
@@ -364,14 +350,14 @@ export const api = {
             });
           }
         } else {
-          // Valor simples
-          pairs.push(`${fullKey}=${encodeURIComponent(value)}`);
-        }
-      }
-    }
-    return pairs;
-  },
-
+          // Valor simples
+          pairs.push(`${fullKey}=${encodeURIComponent(value)}`);
+        }
+      }
+    }
+    return pairs;
+  },
+
   buildQueryString(uri, options) {
     const safeUri = stripDomainQueryParams(uri);
 

package/src/react/components/AnimatedModal.js

@@ -38,6 +38,8 @@ export default function AnimatedModal({
   onRequestClose,
   children,
   style,
+  overlayColor,
+  contentStyle,
 }) {
   const [showing, setShowing] = useState(visible);
   const [keyboardHeight, setKeyboardHeight] = useState(0);
@@ -125,6 +127,8 @@ export default function AnimatedModal({
   const overlayStyle = [
     styles.overlay,
     style,
+  overlayColor,
+  contentStyle,
     Platform.OS === 'android' ? {paddingBottom: keyboardHeight} : null,
   ];
 
@@ -152,11 +156,12 @@ export default function AnimatedModal({
             style={[
               StyleSheet.absoluteFillObject,
               styles.overlayBg,
+              overlayColor ? {backgroundColor: overlayColor} : null,
               {opacity: overlayOpacity},
             ]}
           />
           <Animated.View
-            style={[styles.content, {transform: [{translateY: slideY}]}]}>
+            style={[styles.content, contentStyle, {transform: [{translateY: slideY}]}]}>
             {normalizedChildren}
           </Animated.View>
           <Toasts

package/src/react/components/BottomNavigationBar.js

@@ -1,10 +1,13 @@
 import React, {useLayoutEffect, useMemo} from 'react';
 import {Pressable, Text, View} from 'react-native';
-import Icon from 'react-native-vector-icons/Feather';
+import LegacyIcon from 'react-native-vector-icons/Feather';
+import HomeIcon from '@controleonline/../../src/components/HomeIcon';
 import {useTheme} from './DefaultProvider';
 import RuntimeInfoFooter from './RuntimeInfoFooter';
 import {resolveMenuRouteParams} from '../utils/menuNavigation';
 import createStyles from './BottomNavigationBar.styles';
+import softenStyles from './BottomNavigationBar.soft.styles';
+import {resolveHomepagePalette} from '@controleonline/../../src/styles/homepagePalette';
 
 const BottomNavigationBar = ({
   navigation,
@@ -14,7 +17,11 @@ const BottomNavigationBar = ({
   colors = {},
   testID = 'bottom-navigation',
   useModernWebChromeProps = false,
+  appearance = 'soft',
+  placement = 'overlay',
 }) => {
+  const Icon = appearance === 'soft' ? HomeIcon : LegacyIcon;
+  colors = appearance === 'soft' ? resolveHomepagePalette(colors) : colors;
   const theme = useTheme?.() || {};
   const runtimeFooter = theme?.runtimeFooter || null;
   const registerBottomNavigation =
@@ -31,14 +38,14 @@ const BottomNavigationBar = ({
 
   const styles = useMemo(
     () =>
-      createStyles({
+      softenStyles(createStyles({
         activeBackground,
         dockBackground,
         dockBorder,
         dockShadow,
         activeBorder,
         useModernWebChromeProps,
-      }),
+      }), colors, appearance),
     [
       activeBackground,
       activeBorder,
@@ -46,6 +53,7 @@ const BottomNavigationBar = ({
       dockBorder,
       dockShadow,
       useModernWebChromeProps,
+      appearance,
     ],
   );
 
@@ -97,9 +105,7 @@ const BottomNavigationBar = ({
 
   const routeItems = Array.isArray(items) ? items : [];
   const knownRoute = routeItems.some(item => item?.route === activeRouteName);
-  const effectiveActiveRoute = knownRoute
-    ? activeRouteName
-    : routeItems[0]?.route || '';
+  const effectiveActiveRoute = knownRoute ? activeRouteName : '';
 
   const navigateTo = item => {
     try {
@@ -116,15 +122,18 @@ const BottomNavigationBar = ({
     ? [styles.host, styles.hostPointerEventsBoxNone]
     : styles.host;
   const footerProps = {
+    appearance,
     appVersion: runtimeFooter?.appVersion,
-    colors: runtimeFooter?.colors || {},
+    colors: appearance === 'soft'
+      ? {...runtimeFooter?.colors, footerBackground: colors.footerBackground, footerText: colors.footerText}
+      : runtimeFooter?.colors || {},
     mainCompany: runtimeFooter?.mainCompany,
     device: runtimeFooter?.device,
     useModernWebChromeProps,
   };
 
   return (
-    <View {...hostProps} style={hostStyle}>
+    <View {...hostProps} style={[hostStyle, placement === 'inline' ? {position: 'relative', flexShrink: 0, zIndex: 0} : null]}>
       <View style={styles.stack}>
         <View style={styles.dock} testID={testID}>
           <View style={styles.itemsRow}>
@@ -141,6 +150,8 @@ const BottomNavigationBar = ({
                 <Pressable
                   key={item.route}
                   accessibilityRole="button"
+                  accessibilityLabel={item.label}
+                  accessibilityState={{selected: isActive, disabled: Boolean(isDisabled)}}
                   disabled={isDisabled}
                   onPress={() => navigateTo(item)}
                   style={({pressed}) => [

package/src/react/components/BottomNavigationBar.soft.styles.js

@@ -0,0 +1,29 @@
+import {Platform} from 'react-native';
+
+// Shared compact chrome on every route; explicit legacy consumers can opt out.
+export default (styles, colors, appearance) => appearance !== 'soft' ? styles : {
+  ...styles,
+  dock: [styles.dock, {
+    paddingHorizontal: 0,
+    paddingTop: 0,
+    paddingBottom: 0,
+    borderWidth: 0,
+    borderTopWidth: 1,
+    borderColor: colors.navigationBorder,
+    borderTopLeftRadius: 0,
+    borderTopRightRadius: 0,
+    elevation: 0,
+    shadowOpacity: 0,
+    ...(Platform.OS === 'web' ? {boxShadow: 'none'} : {}),
+  }],
+  itemsRow: [styles.itemsRow, {minHeight: 56, paddingHorizontal: 8, paddingVertical: 4}],
+  item: [styles.item, {minHeight: 46, paddingVertical: 3, borderRadius: 10}],
+  iconWrap: [styles.iconWrap, {width: 22, height: 22, marginBottom: 2}],
+  itemLabel: [styles.itemLabel, {fontSize: 11, lineHeight: 14, fontWeight: '400'}],
+  footerSlot: [styles.footerSlot, {
+    borderTopWidth: 1,
+    borderColor: colors.navigationBorder,
+    paddingHorizontal: 0,
+    minHeight: 28,
+  }],
+};

package/src/react/components/DefaultProvider.styles.js

@@ -12,6 +12,10 @@ const styles = StyleSheet.create({
   shell: {
     flex: 1,
   },
+  translationPending: {
+    visibility: 'hidden',
+    opacity: 0,
+  },
   content: {
     flex: 1,
     minHeight: 0,

package/src/react/components/DefaultProvider.web.js

@@ -395,15 +395,18 @@ export const DefaultProvider = ({
 
   useWebThemePalette({resolveDomainThemeColors, baseThemeColors, mainCompany, resolveThemePalette, runtimeColors, applyPaletteToRuntimeColors, applyThemeCssVariables, actions, currentCompany, isShopClientApp});
 
-  if (requiresTranslateBootstrap && !isTranslateBootstrapReady) {
-    return <View style={providerStyles.loadingContainer} />;
-  }
+  const translationPending = requiresTranslateBootstrap && !isTranslateBootstrapReady;
 
   return (
       <ThemeContext.Provider value={themeContextValue}>
         <View
+          pointerEvents={translationPending ? 'none' : 'auto'}
+          aria-hidden={translationPending}
           style={[
             providerStyles.shell,
+            // Keep navigation mounted while translations load. Unmounting it
+            // resets the login route and repeatedly registers the bottom bar.
+            translationPending && providerStyles.translationPending,
             {
               backgroundColor: colors?.background || runtimeColors.background,
             },

package/src/react/components/ProductCatalogCacheService.js

@@ -1,45 +1,53 @@
-import React, {useEffect} from 'react';
-import {useStore} from '@store';
-
-const ProductCatalogCacheService = () => {
-  const categoriesStore = useStore('categories');
-  const productsStore = useStore('products');
-
-  const categoryActions = categoriesStore.actions;
-  const productActions = productsStore.actions;
-
-  const {messages, message} = categoriesStore.getters;
-
-  useEffect(() => {
-    if (
-      messages &&
-      messages.length > 0 &&
-      (!message || Object.keys(message).length === 0)
-    ) {
-      const nextMessages = [...messages];
-      categoryActions.setMessage(nextMessages.pop());
-      categoryActions.setMessages(nextMessages);
-    }
-  }, [categoryActions, message, messages]);
-
-  useEffect(() => {
-    if (!message || Object.keys(message).length === 0) {
-      return;
-    }
-
-    if (message?.command !== 'clear-product-cache') {
-      categoryActions.setMessage(null);
-      return;
-    }
-
-    localStorage.setItem('categories', JSON.stringify([]));
-    localStorage.removeItem('categories-company');
-    categoryActions.setItems([]);
-    productActions.setItems([]);
-    categoryActions.setMessage(null);
-  }, [categoryActions, message, productActions]);
-
-  return null;
-};
-
-export default ProductCatalogCacheService;
+import React, {useEffect} from 'react';
+import {useStore} from '@store';
+import {invalidateProductCatalogCache} from '../utils/productCatalogCacheRevision';
+
+const ProductCatalogCacheService = () => {
+  const categoriesStore = useStore('categories');
+  const productsStore = useStore('products');
+
+  const categoryActions = categoriesStore.actions;
+  const productActions = productsStore.actions;
+
+  const {messages, message} = categoriesStore.getters;
+
+  useEffect(() => {
+    if (
+      messages &&
+      messages.length > 0 &&
+      (!message || Object.keys(message).length === 0)
+    ) {
+      const nextMessages = [...messages];
+      categoryActions.setMessage(nextMessages.pop());
+      categoryActions.setMessages(nextMessages);
+    }
+  }, [categoryActions, message, messages]);
+
+  useEffect(() => {
+    if (!message || Object.keys(message).length === 0) {
+      return;
+    }
+
+    if (message?.command !== 'clear-product-cache') {
+      categoryActions.setMessage(null);
+      return;
+    }
+
+    invalidateProductCatalogCache();
+    for (const context of ['products', 'supplies']) {
+      localStorage.removeItem(`categories:${context}`);
+      localStorage.removeItem(`categories-company:${context}`);
+    }
+    localStorage.setItem('categories', JSON.stringify([]));
+    localStorage.removeItem('categories-company');
+    categoryActions.setItems([]);
+    productActions.setItems([]);
+    categoryActions.setReload?.(true);
+    productActions.setReload?.(true);
+    categoryActions.setMessage(null);
+  }, [categoryActions, message, productActions]);
+
+  return null;
+};
+
+export default ProductCatalogCacheService;

package/src/react/components/RuntimeBottomNavigationBar.js

@@ -19,6 +19,8 @@ const {
 } = require('@controleonline/ui-common/src/react/utils/bottomNavigationToolbar');
 
 const RuntimeBottomNavigationBar = ({
+  appearance = 'soft',
+  placement = 'overlay',
   activeRouteName: activeRouteNameProp,
   colors: colorsOverride,
   disabled: disabledOverride,
@@ -41,13 +43,16 @@ const RuntimeBottomNavigationBar = ({
   const peopleGetters = peopleStore?.getters || {};
   const currentCompany = peopleGetters.currentCompany || {};
   const themeColors = themeGetters.colors || {};
-  const [runtimeMenus, setRuntimeMenus] = useState([]);
+  const [menuState, setMenuState] = useState({scope: '', menus: []});
   const preset = presetKey ? getBottomNavigationPreset(presetKey) : null;
   const routeAliases = routeAliasesProp || preset?.routeAliases || {};
   const appType = normalizeAppType(app_type);
+  const menuScope = JSON.stringify([appType, currentCompany?.id, menuType, presetKey]);
+  const runtimeMenus = menuState.scope === menuScope ? menuState.menus : [];
 
   // Always consult menus-people for role-aware toolbar; preset is fallback only.
   useEffect(() => {
+    const setRuntimeMenus = menus => setMenuState({scope: menuScope, menus});
     if (!currentCompany?.id || !menuType) {
       setRuntimeMenus(
         resolveToolbarRuntimeMenus({
@@ -104,7 +109,7 @@ const RuntimeBottomNavigationBar = ({
     return () => {
       cancelled = true;
     };
-  }, [appType, currentCompany?.id, menuType, preset, presetKey]);
+  }, [appType, currentCompany?.id, menuType, preset, presetKey, menuScope]);
 
   const colors = useMemo(() => {
     if (colorsOverride) {
@@ -150,15 +155,19 @@ const RuntimeBottomNavigationBar = ({
   const knownRoute = navItems.some(item => item.route === resolvedActiveRoute);
   const effectiveActiveRoute = knownRoute
     ? resolvedActiveRoute
-    : navItems[0]?.route || activeRouteName;
+    : activeRouteName;
 
   const isDisabled =
     typeof disabledOverride === 'boolean'
       ? disabledOverride
       : !currentCompany || Object.keys(currentCompany).length === 0;
 
+  if (!navItems.length) return null;
+
   return (
     <BottomNavigationBar
+      appearance={appearance}
+      placement={placement}
       activeRouteName={effectiveActiveRoute}
       colors={colors}
       disabled={isDisabled}

package/src/react/components/RuntimeInfoFooter.home.spacing.js

@@ -0,0 +1,5 @@
+// Keep the native safe area outside the centered content row.
+export default (appearance, platform, bottomInset) => appearance === 'soft' ? {
+  contentPadding: 4,
+  safeAreaBottom: platform === 'web' ? 0 : Math.max(Number(bottomInset) || 0, 0),
+} : null;

package/src/react/components/RuntimeInfoFooter.js

@@ -22,6 +22,7 @@ import {
 } from '@controleonline/ui-common/src/react/utils/runtimeFooter';
 import styles from './RuntimeInfoFooter.styles';
 import RuntimeFooterMarqueeText from './RuntimeFooterMarqueeText';
+import resolveHomeFooterSpacing from './RuntimeInfoFooter.home.spacing';
 
 const ROTATION_INTERVAL_MS = 4000;
 const COMPACT_BREAKPOINT = 720;
@@ -66,6 +67,7 @@ const RuntimeInfoFooter = ({
   device,
   colors,
   useModernWebChromeProps = false,
+  appearance = 'legacy',
 }) => {
   const {width} = useWindowDimensions();
   const insets = useSafeAreaInsets();
@@ -258,6 +260,7 @@ const RuntimeInfoFooter = ({
       : inlineText
   ) || primaryText || device?.id || '';
   const backgroundColor = colors?.footerBackground;
+  const homeSpacing = resolveHomeFooterSpacing(appearance, Platform.OS, insets.bottom);
   const borderColor = colors?.footerBorder;
   const textColor = resolveVisibleFooterTextColor(colors);
   const loadingColor = colors?.footerLink || colors?.primary || textColor;
@@ -267,7 +270,9 @@ const RuntimeInfoFooter = ({
     : styles.shell;
 
   return (
-    <View {...shellProps} style={shellStyle}>
+    <View {...shellProps} style={[shellStyle, homeSpacing && {
+      paddingBottom: homeSpacing.safeAreaBottom, backgroundColor,
+    }]}>
       <View
         testID="runtime-info-footer"
         style={[
@@ -276,7 +281,8 @@ const RuntimeInfoFooter = ({
           {
             backgroundColor,
             borderTopColor: borderColor,
-            paddingBottom: bottomInset,
+            paddingBottom: homeSpacing ? homeSpacing.contentPadding : bottomInset,
+            ...(homeSpacing && !showDebugInfo ? {paddingTop: homeSpacing.contentPadding} : {}),
           },
         ]}>
         <View style={styles.primaryRow}>

package/src/react/components/UserAvatar.js

@@ -1,3 +1,4 @@
+import {readStoredSessionToken} from '../../utils/storedSessionToken';
 import React, {useEffect, useMemo, useState} from 'react';
 import {Image, Platform, StyleSheet, Text, View} from 'react-native';
 import {env as APP_ENV} from '@env';
@@ -14,18 +15,6 @@ const isBackendDownloadUrl = uri =>
 /** Session cache: gravatar URL → true (ok) | false (missing). Avoids repeat probes. */
 const gravatarProbeCache = new Map();
 
-const readSessionToken = () => {
-  if (typeof localStorage === 'undefined' || !localStorage?.getItem) {
-    return '';
-  }
-
-  try {
-    const session = JSON.parse(localStorage.getItem('session') || '{}');
-    return normalizeUrl(session?.api_key || session?.token);
-  } catch {
-    return '';
-  }
-};
 
 /**
  * Probe Gravatar (d=404) via fetch BEFORE exposing URL to <Image>.
@@ -86,7 +75,7 @@ const useDisplayUri = uri => {
         return;
       }
 
-      const token = readSessionToken();
+      const token = readStoredSessionToken();
 
       // Authenticated backend download on web
       if (isBackendDownloadUrl(next) && Platform.OS === 'web' && token) {
@@ -156,6 +145,7 @@ const useDisplayUri = uri => {
 
 const UserAvatar = ({
   imageUrl,
+  imageHeaders,
   email,
   name,
   size = 40,
@@ -215,7 +205,8 @@ const UserAvatar = ({
     <View style={containerStyle}>
       {displayUri ? (
         <Image
-          source={{uri: displayUri}}
+          source={imageHeaders && Platform.OS !== 'web' && displayUri === imageUrl
+            ? {uri: displayUri, headers: imageHeaders} : {uri: displayUri}}
           style={styles.image}
           onError={() => setSourceIndex(index => index + 1)}
         />

package/src/react/hooks/useBottomNavigationPreference.js

@@ -0,0 +1,49 @@
+import {useEffect, useRef, useState} from 'react';
+import {Platform} from 'react-native';
+
+const nativeStorage = () => {
+  const module = require('@react-native-async-storage/async-storage');
+  return module.default || module;
+};
+const deviceStorage = {
+  getItem: key => Platform.OS === 'web' ? globalThis.localStorage?.getItem(key) : nativeStorage().getItem(key),
+  setItem: (key, value) => Platform.OS === 'web' ? globalThis.localStorage.setItem(key, value) : nativeStorage().setItem(key, value),
+};
+
+// Visibility is personal device state. It never changes server menu permissions.
+export default function useBottomNavigationPreference({enabled, principal, appType, storage = deviceStorage}) {
+  const key = enabled && principal && appType
+    ? `co.bottom-navigation.v1:${encodeURIComponent(appType)}:${encodeURIComponent(principal)}` : '';
+  const current = useRef(key);
+  current.current = key;
+  const [state, setState] = useState({key: '', ready: false, remembered: true, session: null, error: ''});
+  useEffect(() => {
+    current.current = key;
+    let cancelled = false;
+    setState({key, ready: false, remembered: true, session: null, error: ''});
+    if (key) Promise.resolve().then(() => storage.getItem(key)).then(value => {
+      if (!cancelled) setState({key, ready: true, remembered: value !== 'hidden', session: null, error: ''});
+    }).catch(() => {
+      if (!cancelled) setState({key, ready: true, remembered: true, session: null, error: 'Não foi possível recuperar a preferência da barra.'});
+    });
+    return () => {cancelled = true; if (current.current === key) current.current = null;};
+  }, [key, storage]);
+  const ready = Boolean(key && state.key === key && state.ready);
+  const setSessionVisible = visible => {
+    if (ready) setState(previous => ({...previous, session: Boolean(visible), error: ''}));
+  };
+  const setRememberedVisible = async visible => {
+    if (!ready) return false;
+    try {
+      await storage.setItem(key, visible ? 'visible' : 'hidden');
+      if (current.current !== key) return false;
+      setState(previous => ({...previous, remembered: Boolean(visible), session: null, error: ''}));
+      return true;
+    } catch {
+      if (current.current === key) setState(previous => ({...previous, error: 'Não foi possível lembrar a preferência neste aparelho.'}));
+      return false;
+    }
+  };
+  return {ready, visible: ready && (state.session ?? state.remembered), rememberedVisible: ready ? state.remembered : true,
+    error: state.key === key ? state.error : '', setSessionVisible, setRememberedVisible};
+}