@xsolla/xui-b2b-sidebar 0.194.0 → 0.195.0

package/README.md

@@ -1,6 +1,6 @@
 # Sidebar
 
-A composable navigation sidebar for B2B admin surfaces. Renders an expanded panel with grouped menu items and a parallel collapsed icon strip with hover popovers, both driven by the same `SidebarProvider` so the active route, link component, and collapsed state stay in sync.
+A composable navigation sidebar for B2B admin surfaces. Renders an expanded panel with grouped menu items and a parallel collapsed icon strip with hover popovers, both driven by the same `SidebarProvider` so the active route, link component, collapsed state and label translations stay in sync.
 
 ## Installation
 
@@ -25,11 +25,20 @@ import {
   SidebarTrigger,
   SidebarChatButton,
   SidebarCollapsed,
+  SidebarPinnedList,
+  getPinnedCollapsedItem,
+  DEFAULT_SIDEBAR_LABELS,
+  resolveSidebarLabels,
   type SidebarProps,
   type SidebarProviderProps,
   type SidebarMenuItemProps,
   type SidebarMenuCollapsibleProps,
   type SidebarCollapsedProps,
+  type SidebarChatButtonProps,
+  type SidebarTriggerProps,
+  type SidebarPinnedItem,
+  type SidebarPinnedListProps,
+  type SidebarLabels,
   type SidebarItemType,
   type SidebarLinkProps,
   type SidebarLinkActiveCheck,
@@ -114,6 +123,80 @@ function AppShell({ pathname }: { pathname: string }) {
 }
 ```
 
+## Localisation
+
+Menu labels, group headings and popover titles are consumer-supplied props, so they are localisable by construction. The strings the sidebar renders **on its own behalf** — the chat button, the collapse/expand toggle, the pin controls, the "Beta" tag and the navigation landmark — are collected in a single `SidebarLabels` map. Override any subset once on `SidebarProvider`:
+
+```tsx
+import { SidebarProvider } from "@xsolla/xui-b2b-sidebar";
+import { useTranslation } from "react-i18next";
+
+function LocalisedShell({ children }: { children: React.ReactNode }) {
+  const { t } = useTranslation();
+
+  return (
+    <SidebarProvider
+      pathname={location.pathname}
+      labels={{
+        navigation: t("sidebar.navigation"),
+        expandSidebar: t("sidebar.expand"),
+        collapseSidebar: t("sidebar.collapse"),
+        chat: t("sidebar.chat"),
+        openChat: t("sidebar.openChat"),
+        pin: t("sidebar.pin"),
+        unpin: t("sidebar.unpin"),
+        pinItem: t("sidebar.pinItem"),
+        unpinItem: t("sidebar.unpinItem"),
+        beta: t("sidebar.beta"),
+        pinned: t("sidebar.pinned"),
+      }}
+    >
+      {children}
+    </SidebarProvider>
+  );
+}
+```
+
+Every key is optional — omitted keys keep their English default from `DEFAULT_SIDEBAR_LABELS`.
+
+### Label keys
+
+| Key               | Default              | Where it appears                                                  |
+| ----------------- | -------------------- | ----------------------------------------------------------------- |
+| `navigation`      | `"Sidebar navigation"` | `aria-label` on the root `role="navigation"` landmark.           |
+| `expandSidebar`   | `"Expand sidebar"`   | `aria-label` on the toggle while collapsed (both modes).          |
+| `collapseSidebar` | `"Collapse sidebar"` | `aria-label` on the toggle while expanded.                        |
+| `chat`            | `"Chat"`             | Visible text on the expanded-mode `SidebarChatButton`.            |
+| `openChat`        | `"Open chat"`        | `aria-label` on the collapsed-mode icon-only chat button.         |
+| `pin`             | `"Pin"`              | Pin-toggle tooltip while the item is unpinned.                    |
+| `unpin`           | `"Unpin"`            | Pin-toggle tooltip while the item is pinned.                      |
+| `pinItem`         | `"Pin item"`         | Pin-toggle `aria-label` while unpinned.                           |
+| `unpinItem`       | `"Unpin item"`       | Pin-toggle `aria-label` while pinned.                             |
+| `beta`            | `"Beta"`             | Trailing tag rendered when `beta` is set on a menu item.          |
+| `pinned`          | `"Pinned"`           | Default title of the collapsed-mode pinned-shortcuts popover.     |
+
+### Precedence
+
+Per-instance props beat the provider, which beats the defaults:
+
+```
+component prop  >  SidebarProvider labels  >  DEFAULT_SIDEBAR_LABELS
+```
+
+Use a per-instance prop only when one occurrence needs to differ — e.g. two sidebars on one page needing distinct landmark names:
+
+```tsx
+<Sidebar navigationLabel={t("sidebar.secondaryNavigation")}>{/* ... */}</Sidebar>
+```
+
+### `getPinnedCollapsedItem`
+
+This helper is a plain function, not a component, so it cannot read provider context. Pass the translated title through `options.label`:
+
+```tsx
+const pinnedItem = getPinnedCollapsedItem(pinnedItems, { label: t("sidebar.pinned") });
+```
+
 ## API Reference
 
 None of the sidebar components extend `ThemeOverrideProps` — they read theme via `useResolvedTheme()` from the surrounding provider. Wrap the app in a theme provider if you need to override mode or product context.
@@ -127,6 +210,7 @@ None of the sidebar components extend `ThemeOverrideProps` — they read theme v
 | `onCollapsedChange` | `(collapsed: boolean) => void`    | —            | Called when the user toggles via `SidebarTrigger` or the collapsed-mode toggle.                               |
 | `pathname`          | `string`                          | `""`         | Current route, used for active-state matching and `matchPaths` auto-expand.                                   |
 | `linkComponent`     | `ComponentType<SidebarLinkProps>` | plain `<a>`  | Router link component.                                                                                        |
+| `labels`            | `Partial<SidebarLabels>`          | English      | Translations for the strings the sidebar renders itself. See [Localisation](#localisation).                   |
 | `children`          | `ReactNode`                       | —            | Sidebar tree.                                                                                                 |
 
 ### `useSidebar()`
@@ -141,44 +225,53 @@ function useSidebar(): {
   LinkComponent: React.ComponentType<SidebarLinkProps>;
   expandedId: string | null;
   onExpandedIdChange: (id: string | null) => void;
+  labels: SidebarLabels;
 };
 ```
 
-`expandedId` / `onExpandedIdChange` coordinate which `SidebarMenuCollapsible` is open — only one at a time.
+`expandedId` / `onExpandedIdChange` coordinate which `SidebarMenuCollapsible` is open — only one at a time. `labels` is always fully resolved (provider overrides merged over the defaults), so consumers can read it without null checks.
 
 ### `<Sidebar>`
 
-| Prop                   | Type                | Default | Description                                            |
-| ---------------------- | ------------------- | ------- | ------------------------------------------------------ |
-| `collapsedItems`       | `SidebarItemType[]` | `[]`    | Top icons in the collapsed strip.                      |
-| `collapsedToolItems`   | `SidebarItemType[]` | `[]`    | Tool icons rendered after a spacer.                    |
-| `collapsedBottomItems` | `SidebarItemType[]` | `[]`    | Bottom icons (e.g. Settings, Billing).                 |
-| `showChat`             | `boolean`           | `true`  | Render the chat button in the collapsed footer.        |
-| `onChatClick`          | `() => void`        | —       | Click handler for the chat button.                     |
-| `chatBadge`            | `boolean`           | `false` | Show an unread-indicator dot on the chat button.       |
-| `children`             | `ReactNode`         | —       | The expanded tree (`SidebarContent`, `SidebarFooter`). |
+| Prop                   | Type                | Default              | Description                                            |
+| ---------------------- | ------------------- | -------------------- | ------------------------------------------------------ |
+| `collapsedItems`       | `SidebarItemType[]` | `[]`                 | Top icons in the collapsed strip.                      |
+| `collapsedToolItems`   | `SidebarItemType[]` | `[]`                 | Tool icons rendered after a spacer.                    |
+| `collapsedBottomItems` | `SidebarItemType[]` | `[]`                 | Bottom icons (e.g. Settings, Billing).                 |
+| `showChat`             | `boolean`           | `true`               | Render the chat button in the collapsed footer.        |
+| `onChatClick`          | `() => void`        | —                    | Click handler for the chat button.                     |
+| `chatBadge`            | `boolean`           | `false`              | Show an unread-indicator dot on the chat button.       |
+| `navigationLabel`      | `string`            | `labels.navigation`  | `aria-label` for the navigation landmark.              |
+| `children`             | `ReactNode`         | —                    | The expanded tree (`SidebarContent`, `SidebarFooter`). |
 
 ### `<SidebarMenuItem>`
 
-| Prop              | Type                      | Default | Description                                                                         |
-| ----------------- | ------------------------- | ------- | ----------------------------------------------------------------------------------- |
-| `to`              | `string`                  | —       | Route URL passed through to `linkComponent`.                                        |
-| `label`           | `ReactNode`               | —       | Text label.                                                                         |
-| `icon`            | `ReactNode`               | —       | Leading icon (hidden when `isNested`).                                              |
-| `exact`           | `boolean`                 | —       | Exact-match flag forwarded to the link component.                                   |
-| `external`        | `boolean`                 | —       | Marks the link as external (sets `target`/`rel`).                                   |
-| `hasExternalIcon` | `boolean`                 | —       | Shows the external-link icon at the trailing edge.                                  |
-| `target`          | `string \| null`          | —       | Anchor target.                                                                      |
-| `onClick`         | `SidebarLinkClickHandler` | —       | Click handler.                                                                      |
-| `dataId`          | `string`                  | —       | `data-id` attribute for tests/analytics.                                            |
-| `isActive`        | `SidebarLinkActiveCheck`  | —       | Custom active-check forwarded to the link.                                          |
-| `isPinned`        | `boolean`                 | —       | Renders the icon at 12px to indicate a pinned item.                                 |
-| `showBadge`       | `boolean`                 | —       | Shows a small alert dot next to the label.                                          |
-| `hasTooltip`      | `boolean`                 | —       | Truncates labels longer than 20 chars and shows the full text on hover.             |
-| `beta`            | `boolean`                 | —       | Renders a "Beta" tag at the trailing edge.                                          |
-| `multiLine`       | `boolean`                 | —       | Allows the label to wrap to multiple lines.                                         |
-| `extra`           | `ReactNode`               | —       | Slot rendered between the icon and the label.                                       |
-| `isNested`        | `boolean`                 | `false` | Set when rendered inside `SidebarMenuSub` (drops the icon, indents under the rail). |
+| Prop              | Type                      | Default            | Description                                                                         |
+| ----------------- | ------------------------- | ------------------ | ----------------------------------------------------------------------------------- |
+| `to`              | `string`                  | —                  | Route URL passed through to `linkComponent`.                                        |
+| `label`           | `ReactNode`               | —                  | Text label.                                                                         |
+| `icon`            | `ReactNode`               | —                  | Leading icon (hidden when `isNested`).                                              |
+| `exact`           | `boolean`                 | —                  | Exact-match flag forwarded to the link component.                                   |
+| `external`        | `boolean`                 | —                  | Marks the link as external (sets `target`/`rel`).                                   |
+| `hasExternalIcon` | `boolean`                 | —                  | Shows the external-link icon at the trailing edge.                                  |
+| `target`          | `string \| null`          | —                  | Anchor target.                                                                      |
+| `onClick`         | `SidebarLinkClickHandler` | —                  | Click handler.                                                                      |
+| `dataId`          | `string`                  | —                  | `data-id` attribute for tests/analytics.                                            |
+| `isActive`        | `SidebarLinkActiveCheck`  | —                  | Custom active-check forwarded to the link.                                          |
+| `isPinned`        | `boolean`                 | —                  | Renders the icon at 12px to indicate a pinned item.                                 |
+| `onPinToggle`     | `(e) => void`             | —                  | Renders a pin/unpin toggle on hover (always visible when pinned).                   |
+| `dragHandle`      | `boolean`                 | —                  | On a pinned item, swaps the pin glyph for a drag handle on row hover.               |
+| `showBadge`       | `boolean`                 | —                  | Shows a small alert dot next to the label.                                          |
+| `hasTooltip`      | `boolean`                 | —                  | Truncates labels longer than 20 chars and shows the full text on hover.             |
+| `beta`            | `boolean`                 | —                  | Renders a "Beta" tag at the trailing edge.                                          |
+| `multiLine`       | `boolean`                 | —                  | Allows the label to wrap to multiple lines.                                         |
+| `extra`           | `ReactNode`               | —                  | Slot rendered between the icon and the label.                                       |
+| `isNested`        | `boolean`                 | `false`            | Set when rendered inside `SidebarMenuSub` (drops the icon, indents under the rail). |
+| `pinLabel`        | `string`                  | `labels.pin`       | Pin-toggle tooltip while unpinned.                                                  |
+| `unpinLabel`      | `string`                  | `labels.unpin`     | Pin-toggle tooltip while pinned.                                                    |
+| `pinAriaLabel`    | `string`                  | `labels.pinItem`   | Pin-toggle `aria-label` while unpinned.                                             |
+| `unpinAriaLabel`  | `string`                  | `labels.unpinItem` | Pin-toggle `aria-label` while pinned.                                               |
+| `betaLabel`       | `string`                  | `labels.beta`      | Text inside the trailing tag when `beta` is set.                                    |
 
 ### `<SidebarMenuCollapsible>`
 
@@ -194,15 +287,17 @@ function useSidebar(): {
 
 Lower-level collapsed-strip renderer. The `<Sidebar>` component composes this for you; reach for it when you need to render the collapsed strip outside the standard layout.
 
-| Prop               | Type                | Default | Description                                        |
-| ------------------ | ------------------- | ------- | -------------------------------------------------- |
-| `items`            | `SidebarItemType[]` | —       | Top icon items.                                    |
-| `toolItems`        | `SidebarItemType[]` | `[]`    | Tool icons after a spacer.                         |
-| `bottomItems`      | `SidebarItemType[]` | `[]`    | Bottom icons.                                      |
-| `onToggleCollapse` | `() => void`        | —       | Click handler for the toggle button in the footer. |
-| `onChatClick`      | `() => void`        | —       | Click handler for the chat button.                 |
-| `showChat`         | `boolean`           | `true`  | Render the chat button.                            |
-| `chatBadge`        | `boolean`           | `false` | Show the unread dot.                               |
+| Prop               | Type                | Default                | Description                                        |
+| ------------------ | ------------------- | ---------------------- | -------------------------------------------------- |
+| `items`            | `SidebarItemType[]` | —                      | Top icon items.                                    |
+| `toolItems`        | `SidebarItemType[]` | `[]`                   | Tool icons after a spacer.                         |
+| `bottomItems`      | `SidebarItemType[]` | `[]`                   | Bottom icons.                                      |
+| `onToggleCollapse` | `() => void`        | —                      | Click handler for the toggle button in the footer. |
+| `onChatClick`      | `() => void`        | —                      | Click handler for the chat button.                 |
+| `showChat`         | `boolean`           | `true`                 | Render the chat button.                            |
+| `chatBadge`        | `boolean`           | `false`                | Show the unread dot.                               |
+| `chatAriaLabel`    | `string`            | `labels.openChat`      | `aria-label` for the icon-only chat button.        |
+| `expandLabel`      | `string`            | `labels.expandSidebar` | `aria-label` for the expand toggle.                |
 
 ### `<SidebarContent>`
 
@@ -216,9 +311,20 @@ Bordered footer row for the bottom of the sidebar; typically wraps the chat butt
 
 Collapse/expand toggle button. Reads/writes state from the surrounding `SidebarProvider`.
 
+| Prop            | Type     | Default                  | Description                          |
+| --------------- | -------- | ------------------------ | ------------------------------------ |
+| `expandLabel`   | `string` | `labels.expandSidebar`   | `aria-label` used while collapsed.   |
+| `collapseLabel` | `string` | `labels.collapseSidebar` | `aria-label` used while expanded.    |
+
 ### `<SidebarChatButton>`
 
-Branded chat button for the footer. Props: `onClick: () => void`, `badge?: boolean`.
+Branded chat button for the footer.
+
+| Prop      | Type         | Default        | Description                            |
+| --------- | ------------ | -------------- | -------------------------------------- |
+| `onClick` | `() => void` | —              | Click handler.                         |
+| `badge`   | `boolean`    | `false`        | Show the unread-indicator dot.         |
+| `label`   | `string`     | `labels.chat`  | Visible button text.                   |
 
 ### `<SidebarGroup>`
 
@@ -235,6 +341,25 @@ Fragment used as a structural marker inside collapsibles to group nested menu it
 ### Types
 
 ```ts
+interface SidebarLabels {
+  navigation: string;
+  expandSidebar: string;
+  collapseSidebar: string;
+  chat: string;
+  openChat: string;
+  pin: string;
+  unpin: string;
+  pinItem: string;
+  unpinItem: string;
+  beta: string;
+  pinned: string;
+}
+
+declare const DEFAULT_SIDEBAR_LABELS: SidebarLabels;
+declare const resolveSidebarLabels: (
+  overrides?: Partial<SidebarLabels>
+) => SidebarLabels;
+
 type SidebarItemType = {
   to?: string;
   label: ReactNode;
@@ -415,8 +540,10 @@ const mainNavItems: SidebarItemType[] = [
 
 ## Accessibility
 
-- The root sidebar is `role="navigation"` with `aria-label="Sidebar navigation"`. The expanded and collapsed panes are toggled via `aria-hidden` so only one is announced at a time.
-- `SidebarTrigger` and the collapsed-mode toggle have `aria-pressed` and a context-aware `aria-label` (`"Expand sidebar"` / `"Collapse sidebar"`).
+- The root sidebar is `role="navigation"` with an `aria-label` from `labels.navigation` (default `"Sidebar navigation"`, per-instance override via `navigationLabel`). The expanded and collapsed panes are toggled via `aria-hidden` so only one is announced at a time.
+- `SidebarTrigger` and the collapsed-mode toggle have `aria-pressed` and a context-aware `aria-label` (`labels.expandSidebar` / `labels.collapseSidebar`).
+- The pin toggle exposes `aria-pressed` plus `labels.pinItem` / `labels.unpinItem` as its `aria-label`, and a tooltip carrying `labels.pin` / `labels.unpin`.
+- Every one of those strings is translatable through the provider's `labels` prop — assistive-technology users get the app's language, not English.
 - Each `SidebarMenuCollapsible` header is a `<button>` with `aria-expanded` and `aria-controls` linking to its region.
 - Collapsed icon items with children expose `aria-haspopup="menu"`; their popovers are keyboard-reachable (focus opens, blur closes after 150ms, Escape closes immediately). Leaf items (no children) render as native links and navigate on click or Enter.
 - Truncated labels (`hasTooltip`) fall back to a Tooltip with the full text.
@@ -427,3 +554,4 @@ const mainNavItems: SidebarItemType[] = [
 - Only one `SidebarMenuCollapsible` is open at a time; the section auto-expands when `pathname` matches one of `matchPaths` (a leading `/<merchantId>` numeric prefix is stripped before matching).
 - Hover popovers in collapsed mode are rendered into a portal on `document.body` and positioned with viewport-clamped `position: fixed` math.
 - Active route detection lives in the consumer's `linkComponent` — apply `activeClassName` when the link matches the current route.
+- `labels` overrides are merged over the defaults once per provider render and serialised for memoisation, so passing an inline object literal does not thrash the context.

package/native/index.d.mts

@@ -1,5 +1,56 @@
 import React, { MouseEvent, ReactNode } from 'react';
 
+/**
+ * Every user-visible string the sidebar renders on its own behalf.
+ *
+ * Labels for menu items, groups and popovers come from the consumer as props,
+ * so they are already localisable. The strings collected here are the ones the
+ * component library hard-codes internally — visible text (`chat`, `beta`) and
+ * assistive-technology text (`navigation`, `expandSidebar`, `pinItem`, …).
+ *
+ * Override them once on `SidebarProvider`:
+ *
+ * ```tsx
+ * <SidebarProvider labels={{ chat: "Chat", expandSidebar: "Ouvrir le menu" }}>
+ * ```
+ *
+ * Every override is optional — omitted keys fall back to
+ * {@link DEFAULT_SIDEBAR_LABELS}. Individual components also accept per-instance
+ * label props that take precedence over the provider value.
+ */
+interface SidebarLabels {
+    /** `aria-label` on the root `role="navigation"` landmark. */
+    navigation: string;
+    /** `aria-label` on the toggle when the sidebar is collapsed. */
+    expandSidebar: string;
+    /** `aria-label` on the toggle when the sidebar is expanded. */
+    collapseSidebar: string;
+    /** Visible text on the expanded-mode chat button. */
+    chat: string;
+    /** `aria-label` on the collapsed-mode icon-only chat button. */
+    openChat: string;
+    /** Pin-toggle tooltip when the item is not pinned. */
+    pin: string;
+    /** Pin-toggle tooltip when the item is pinned. */
+    unpin: string;
+    /** Pin-toggle `aria-label` when the item is not pinned. */
+    pinItem: string;
+    /** Pin-toggle `aria-label` when the item is pinned. */
+    unpinItem: string;
+    /** Visible text in the trailing "Beta" tag. */
+    beta: string;
+    /** Default label for the collapsed-mode pinned-shortcuts popover. */
+    pinned: string;
+}
+/** English defaults — used whenever a label is not overridden. */
+declare const DEFAULT_SIDEBAR_LABELS: SidebarLabels;
+/**
+ * Merge a partial override map over {@link DEFAULT_SIDEBAR_LABELS}. Returns the
+ * shared default object untouched when there is nothing to override, so the
+ * common case allocates nothing.
+ */
+declare const resolveSidebarLabels: (overrides?: Partial<SidebarLabels>) => SidebarLabels;
+
 type SidebarLinkClickHandler = (event?: MouseEvent<HTMLElement>) => void;
 type SidebarLinkActiveCheck = (match: unknown, location: {
     pathname: string;
@@ -27,12 +78,20 @@ interface SidebarContextValue {
     LinkComponent: React.ComponentType<SidebarLinkProps>;
     expandedId: string | null;
     onExpandedIdChange: (id: string | null) => void;
+    /** Fully-resolved label set — provider overrides merged over the defaults. */
+    labels: SidebarLabels;
 }
 interface SidebarProviderProps {
     collapsed?: boolean;
     onCollapsedChange?: (collapsed: boolean) => void;
     pathname?: string;
     linkComponent?: React.ComponentType<SidebarLinkProps>;
+    /**
+     * Translations for the strings the sidebar renders on its own behalf
+     * (chat button, collapse/expand toggle, pin controls, "Beta" tag, nav
+     * landmark). Partial — omitted keys keep their English default.
+     */
+    labels?: Partial<SidebarLabels>;
     children: ReactNode;
     testID?: string;
 }
@@ -91,6 +150,10 @@ type SidebarItemType = {
  *       </SidebarFooter>
  *     </Sidebar>
  *   </SidebarProvider>
+ *
+ * Strings the sidebar renders on its own behalf (nav landmark, chat button,
+ * collapse toggle, pin controls, "Beta" tag) are localised through the
+ * `labels` prop on `SidebarProvider`.
  */
 
 interface SidebarProps {
@@ -106,6 +169,12 @@ interface SidebarProps {
     onChatClick?: () => void;
     /** Whether the chat button shows a notification badge */
     chatBadge?: boolean;
+    /**
+     * `aria-label` for the navigation landmark. Defaults to the provider's
+     * `navigation` label; set this when a page renders more than one sidebar and
+     * each landmark needs a distinct name.
+     */
+    navigationLabel?: string;
     children: ReactNode;
     testID?: string;
 }
@@ -119,7 +188,14 @@ declare const SidebarFooter: React.FC<{
     children: ReactNode;
 }>;
 
-declare const SidebarTrigger: React.FC;
+interface SidebarTriggerProps {
+    /** `aria-label` used while collapsed. Defaults to the provider's `expandSidebar` label. */
+    expandLabel?: string;
+    /** `aria-label` used while expanded. Defaults to the provider's `collapseSidebar` label. */
+    collapseLabel?: string;
+    testID?: string;
+}
+declare const SidebarTrigger: React.FC<SidebarTriggerProps>;
 
 interface SidebarGroupProps {
     label?: string;
@@ -158,6 +234,16 @@ interface SidebarMenuItemProps {
     extra?: ReactNode;
     /** Whether this item is inside a SidebarMenuSub (parent collapsible sets nested styling) */
     isNested?: boolean;
+    /** Pin-toggle tooltip while unpinned. Defaults to the provider's `pin` label. */
+    pinLabel?: string;
+    /** Pin-toggle tooltip while pinned. Defaults to the provider's `unpin` label. */
+    unpinLabel?: string;
+    /** Pin-toggle `aria-label` while unpinned. Defaults to the provider's `pinItem` label. */
+    pinAriaLabel?: string;
+    /** Pin-toggle `aria-label` while pinned. Defaults to the provider's `unpinItem` label. */
+    unpinAriaLabel?: string;
+    /** Text inside the trailing tag when `beta` is set. Defaults to the provider's `beta` label. */
+    betaLabel?: string;
     testID?: string;
 }
 declare const SidebarMenuItem: React.FC<SidebarMenuItemProps>;
@@ -185,6 +271,8 @@ declare const SidebarMenuSub: React.FC<{
 interface SidebarChatButtonProps {
     onClick?: () => void;
     badge?: boolean;
+    /** Visible button text. Defaults to the provider's `chat` label. */
+    label?: string;
     testID?: string;
 }
 declare const SidebarChatButton: React.FC<SidebarChatButtonProps>;
@@ -197,6 +285,10 @@ interface SidebarCollapsedProps {
     onChatClick?: () => void;
     showChat?: boolean;
     chatBadge?: boolean;
+    /** `aria-label` for the icon-only chat button. Defaults to the provider's `openChat` label. */
+    chatAriaLabel?: string;
+    /** `aria-label` for the expand toggle. Defaults to the provider's `expandSidebar` label. */
+    expandLabel?: string;
     testID?: string;
 }
 declare const SidebarCollapsed: React.FC<SidebarCollapsedProps>;
@@ -234,10 +326,14 @@ declare const SidebarPinnedList: React.FC<SidebarPinnedListProps>;
  * Helper for the collapsed sidebar: returns a single `SidebarItemType` whose
  * popover lists every pinned shortcut. Spread it into `collapsedItems` at the
  * position you want the Pin button to appear. Returns `null` when no items.
+ *
+ * This is a plain function rather than a component, so it cannot read the
+ * `SidebarProvider` labels — pass `options.label` with your translated string
+ * to localise the popover title (defaults to the English "Pinned").
  */
 declare const getPinnedCollapsedItem: (items: SidebarPinnedItem[], options?: {
     label?: string;
     dataId?: string;
 }) => SidebarItemType | null;
 
-export { Sidebar, SidebarChatButton, SidebarCollapsed, type SidebarCollapsedProps, SidebarContent, SidebarFooter, SidebarGroup, type SidebarItemType, type SidebarLinkActiveCheck, type SidebarLinkClickHandler, type SidebarLinkProps, SidebarMenu, SidebarMenuCollapsible, type SidebarMenuCollapsibleProps, SidebarMenuItem, type SidebarMenuItemProps, SidebarMenuSub, type SidebarPinnedItem, SidebarPinnedList, type SidebarPinnedListProps, type SidebarProps, SidebarProvider, type SidebarProviderProps, SidebarTrigger, getPinnedCollapsedItem, useSidebar };
+export { DEFAULT_SIDEBAR_LABELS, Sidebar, SidebarChatButton, type SidebarChatButtonProps, SidebarCollapsed, type SidebarCollapsedProps, SidebarContent, SidebarFooter, SidebarGroup, type SidebarItemType, type SidebarLabels, type SidebarLinkActiveCheck, type SidebarLinkClickHandler, type SidebarLinkProps, SidebarMenu, SidebarMenuCollapsible, type SidebarMenuCollapsibleProps, SidebarMenuItem, type SidebarMenuItemProps, SidebarMenuSub, type SidebarPinnedItem, SidebarPinnedList, type SidebarPinnedListProps, type SidebarProps, SidebarProvider, type SidebarProviderProps, SidebarTrigger, type SidebarTriggerProps, getPinnedCollapsedItem, resolveSidebarLabels, useSidebar };

package/native/index.d.ts

@@ -1,5 +1,56 @@
 import React, { MouseEvent, ReactNode } from 'react';
 
+/**
+ * Every user-visible string the sidebar renders on its own behalf.
+ *
+ * Labels for menu items, groups and popovers come from the consumer as props,
+ * so they are already localisable. The strings collected here are the ones the
+ * component library hard-codes internally — visible text (`chat`, `beta`) and
+ * assistive-technology text (`navigation`, `expandSidebar`, `pinItem`, …).
+ *
+ * Override them once on `SidebarProvider`:
+ *
+ * ```tsx
+ * <SidebarProvider labels={{ chat: "Chat", expandSidebar: "Ouvrir le menu" }}>
+ * ```
+ *
+ * Every override is optional — omitted keys fall back to
+ * {@link DEFAULT_SIDEBAR_LABELS}. Individual components also accept per-instance
+ * label props that take precedence over the provider value.
+ */
+interface SidebarLabels {
+    /** `aria-label` on the root `role="navigation"` landmark. */
+    navigation: string;
+    /** `aria-label` on the toggle when the sidebar is collapsed. */
+    expandSidebar: string;
+    /** `aria-label` on the toggle when the sidebar is expanded. */
+    collapseSidebar: string;
+    /** Visible text on the expanded-mode chat button. */
+    chat: string;
+    /** `aria-label` on the collapsed-mode icon-only chat button. */
+    openChat: string;
+    /** Pin-toggle tooltip when the item is not pinned. */
+    pin: string;
+    /** Pin-toggle tooltip when the item is pinned. */
+    unpin: string;
+    /** Pin-toggle `aria-label` when the item is not pinned. */
+    pinItem: string;
+    /** Pin-toggle `aria-label` when the item is pinned. */
+    unpinItem: string;
+    /** Visible text in the trailing "Beta" tag. */
+    beta: string;
+    /** Default label for the collapsed-mode pinned-shortcuts popover. */
+    pinned: string;
+}
+/** English defaults — used whenever a label is not overridden. */
+declare const DEFAULT_SIDEBAR_LABELS: SidebarLabels;
+/**
+ * Merge a partial override map over {@link DEFAULT_SIDEBAR_LABELS}. Returns the
+ * shared default object untouched when there is nothing to override, so the
+ * common case allocates nothing.
+ */
+declare const resolveSidebarLabels: (overrides?: Partial<SidebarLabels>) => SidebarLabels;
+
 type SidebarLinkClickHandler = (event?: MouseEvent<HTMLElement>) => void;
 type SidebarLinkActiveCheck = (match: unknown, location: {
     pathname: string;
@@ -27,12 +78,20 @@ interface SidebarContextValue {
     LinkComponent: React.ComponentType<SidebarLinkProps>;
     expandedId: string | null;
     onExpandedIdChange: (id: string | null) => void;
+    /** Fully-resolved label set — provider overrides merged over the defaults. */
+    labels: SidebarLabels;
 }
 interface SidebarProviderProps {
     collapsed?: boolean;
     onCollapsedChange?: (collapsed: boolean) => void;
     pathname?: string;
     linkComponent?: React.ComponentType<SidebarLinkProps>;
+    /**
+     * Translations for the strings the sidebar renders on its own behalf
+     * (chat button, collapse/expand toggle, pin controls, "Beta" tag, nav
+     * landmark). Partial — omitted keys keep their English default.
+     */
+    labels?: Partial<SidebarLabels>;
     children: ReactNode;
     testID?: string;
 }
@@ -91,6 +150,10 @@ type SidebarItemType = {
  *       </SidebarFooter>
  *     </Sidebar>
  *   </SidebarProvider>
+ *
+ * Strings the sidebar renders on its own behalf (nav landmark, chat button,
+ * collapse toggle, pin controls, "Beta" tag) are localised through the
+ * `labels` prop on `SidebarProvider`.
  */
 
 interface SidebarProps {
@@ -106,6 +169,12 @@ interface SidebarProps {
     onChatClick?: () => void;
     /** Whether the chat button shows a notification badge */
     chatBadge?: boolean;
+    /**
+     * `aria-label` for the navigation landmark. Defaults to the provider's
+     * `navigation` label; set this when a page renders more than one sidebar and
+     * each landmark needs a distinct name.
+     */
+    navigationLabel?: string;
     children: ReactNode;
     testID?: string;
 }
@@ -119,7 +188,14 @@ declare const SidebarFooter: React.FC<{
     children: ReactNode;
 }>;
 
-declare const SidebarTrigger: React.FC;
+interface SidebarTriggerProps {
+    /** `aria-label` used while collapsed. Defaults to the provider's `expandSidebar` label. */
+    expandLabel?: string;
+    /** `aria-label` used while expanded. Defaults to the provider's `collapseSidebar` label. */
+    collapseLabel?: string;
+    testID?: string;
+}
+declare const SidebarTrigger: React.FC<SidebarTriggerProps>;
 
 interface SidebarGroupProps {
     label?: string;
@@ -158,6 +234,16 @@ interface SidebarMenuItemProps {
     extra?: ReactNode;
     /** Whether this item is inside a SidebarMenuSub (parent collapsible sets nested styling) */
     isNested?: boolean;
+    /** Pin-toggle tooltip while unpinned. Defaults to the provider's `pin` label. */
+    pinLabel?: string;
+    /** Pin-toggle tooltip while pinned. Defaults to the provider's `unpin` label. */
+    unpinLabel?: string;
+    /** Pin-toggle `aria-label` while unpinned. Defaults to the provider's `pinItem` label. */
+    pinAriaLabel?: string;
+    /** Pin-toggle `aria-label` while pinned. Defaults to the provider's `unpinItem` label. */
+    unpinAriaLabel?: string;
+    /** Text inside the trailing tag when `beta` is set. Defaults to the provider's `beta` label. */
+    betaLabel?: string;
     testID?: string;
 }
 declare const SidebarMenuItem: React.FC<SidebarMenuItemProps>;
@@ -185,6 +271,8 @@ declare const SidebarMenuSub: React.FC<{
 interface SidebarChatButtonProps {
     onClick?: () => void;
     badge?: boolean;
+    /** Visible button text. Defaults to the provider's `chat` label. */
+    label?: string;
     testID?: string;
 }
 declare const SidebarChatButton: React.FC<SidebarChatButtonProps>;
@@ -197,6 +285,10 @@ interface SidebarCollapsedProps {
     onChatClick?: () => void;
     showChat?: boolean;
     chatBadge?: boolean;
+    /** `aria-label` for the icon-only chat button. Defaults to the provider's `openChat` label. */
+    chatAriaLabel?: string;
+    /** `aria-label` for the expand toggle. Defaults to the provider's `expandSidebar` label. */
+    expandLabel?: string;
     testID?: string;
 }
 declare const SidebarCollapsed: React.FC<SidebarCollapsedProps>;
@@ -234,10 +326,14 @@ declare const SidebarPinnedList: React.FC<SidebarPinnedListProps>;
  * Helper for the collapsed sidebar: returns a single `SidebarItemType` whose
  * popover lists every pinned shortcut. Spread it into `collapsedItems` at the
  * position you want the Pin button to appear. Returns `null` when no items.
+ *
+ * This is a plain function rather than a component, so it cannot read the
+ * `SidebarProvider` labels — pass `options.label` with your translated string
+ * to localise the popover title (defaults to the English "Pinned").
  */
 declare const getPinnedCollapsedItem: (items: SidebarPinnedItem[], options?: {
     label?: string;
     dataId?: string;
 }) => SidebarItemType | null;
 
-export { Sidebar, SidebarChatButton, SidebarCollapsed, type SidebarCollapsedProps, SidebarContent, SidebarFooter, SidebarGroup, type SidebarItemType, type SidebarLinkActiveCheck, type SidebarLinkClickHandler, type SidebarLinkProps, SidebarMenu, SidebarMenuCollapsible, type SidebarMenuCollapsibleProps, SidebarMenuItem, type SidebarMenuItemProps, SidebarMenuSub, type SidebarPinnedItem, SidebarPinnedList, type SidebarPinnedListProps, type SidebarProps, SidebarProvider, type SidebarProviderProps, SidebarTrigger, getPinnedCollapsedItem, useSidebar };
+export { DEFAULT_SIDEBAR_LABELS, Sidebar, SidebarChatButton, type SidebarChatButtonProps, SidebarCollapsed, type SidebarCollapsedProps, SidebarContent, SidebarFooter, SidebarGroup, type SidebarItemType, type SidebarLabels, type SidebarLinkActiveCheck, type SidebarLinkClickHandler, type SidebarLinkProps, SidebarMenu, SidebarMenuCollapsible, type SidebarMenuCollapsibleProps, SidebarMenuItem, type SidebarMenuItemProps, SidebarMenuSub, type SidebarPinnedItem, SidebarPinnedList, type SidebarPinnedListProps, type SidebarProps, SidebarProvider, type SidebarProviderProps, SidebarTrigger, type SidebarTriggerProps, getPinnedCollapsedItem, resolveSidebarLabels, useSidebar };