@lokalise/harmony 1.11.0 → 1.11.1

package/dist/types/src/components/Sidebar/Sidebar.stories.d.ts

@@ -1,89 +1,5 @@
 import { Meta, StoryObj } from '@storybook/react';
 import { Sidebar } from './Sidebar';
-/**
- * ## Overview
- * Sidebar is a self-contained component using widgets.
- *
- * ## Available Widgets
- *
- * ### `Sidebar.Top`
- * Use to wrap up a top section of the Sidebar
- *
- * ### `Sidebar.Bottom`
- * Use to wrap up a bottom section of the Sidebar
- *
- * ### `Sidebar.Avatar`
- * Display company main avatar / logo in the top section
- * ```
- * src: string;
- * href?: string; ('/')
- * ariaLabel?: string; ('Home')
- * alt?: string; ('Lokalise')
- * ```
- *
- * ### `Sidebar.IconLink`
- * Display link with an icon. Mainly used in the top section
- * ```
- * to: string;
- * label: string;
- * icon: FC<SvgIconProps>
- * ```
- *
- * ### `Sidebar.Menu`
- * Use this widget for simple side menu. Currently utilised for `Help` section
- * ```
- * icon: FC<SvgIconProps>
- * children: ReactNode; (representing menu list)
- * ```
- *
- * ### `Sidebar.ProfileMenu`
- * Contextual component, requires initial configuration
- * ```
- * teams: SidebarTeam[];
- * currentTeamId: number;
- * planId: number;
- * isLimitedView: boolean;
- * isTeamSuspended: boolean;
- * canAccessTeamSettings: boolean;
- * isEndOfTrialActive: boolean;
- * trialDaysLeft: number;
- * isProviderAlpha: boolean;
- * ```
- * and works with internal widgets
- *
- * #### `Sidebar.TeamSwitch`
- * Uses available teams (other than current) and allows user to switch between them
- * ```
- * onSwitchTeam: (team: SidebarTeam) => void;
- * ```
- *
- * #### `Sidebar.TeamMenuItem`
- * Uses context of current team, and depending on ability to switch team or not,
- * it renders as a div or clickable MenuItem. If used with TeamSwitch, it triggers `onSwitchTeams`
- * callback, passing relevant team as an argument
- * ```
- * team?: SidebarTeam; (fallbacks to currentTeam from context if not passed)
- * onClick?: (team: SidebarTeam) => void;
- * hidePlanLabel?: boolean;
- * ```
- *
- * #### `Sidebar.ProfileSettingsMenuItem`
- * Menu item that comes with a small user's email and renders conditionally, only if team
- * is not suspended or is not at the end of a trial
- * ```
- * href: string;
- * userEmail: string;
- * onClick?: () => void; (additional onClick for any tracking events)
- * hideBottomDivider?: boolean;
- * ```
- *
- * #### `Sidebar.UpgradeMenuItem`
- * Menu item conditionally rendering only if `showUpgradeButton` is `true`. It renders correct
- * upgrade note depending on the current team plan and red arrow up to indicate an update option
- * ```
- * upgradeOptionHref: string;
- * ```
- */
 declare const meta: Meta<typeof Sidebar>;
 type Story = StoryObj<typeof Sidebar>;
 export declare const FullSidebar: Story;

package/dist/types/src/components/Sidebar/Widgets/Avatar/Avatar.d.ts

@@ -1,11 +1,16 @@
 type AvatarProps = {
+    /** URL of the avatar/logo image */
     src: string;
+    /** Link destination when avatar is clicked. Defaults to '/' */
     href?: string;
+    /** Accessibility label for the avatar link. Defaults to 'Home' */
     ariaLabel?: string;
+    /** Alt text for the avatar image. Defaults to 'Lokalise' */
     alt?: string;
 };
 /**
- * Display company main avatar / logo in the top section
+ * Display company main avatar / logo in the top section of the Sidebar.
+ * Used as the main branding element and home navigation link.
  */
 export declare const Avatar: ({ src, href, ariaLabel, alt }: AvatarProps) => import("react/jsx-runtime").JSX.Element;
 export {};

package/dist/types/src/components/Sidebar/Widgets/IconLink/IconLink.d.ts

@@ -1,12 +1,22 @@
 import { SvgIconProps } from '@lokalise/louis';
 import { FC } from 'react';
 type IconLinkProps = {
+    /** URL destination for the link */
     to: string;
+    /** Text to display in the tooltip when hovering over the icon */
     label: string;
+    /** Icon component from @lokalise/louis to display */
     icon: FC<SvgIconProps>;
 };
 /**
- * Display link with an icon. Mainly used in the top section
+ * A navigation link component that displays an icon with a tooltip.
+ * When hovered, shows a tooltip with the label text.
+ * The link is highlighted when the current URL matches its destination.
+ *
+ * @example
+ * ```tsx
+ * <IconLink to="/projects" label="Projects" icon={FolderOpenIcon} />
+ * ```
  */
 export declare const IconLink: ({ label, to, icon: Icon }: IconLinkProps) => import("react/jsx-runtime").JSX.Element;
 export {};

package/dist/types/src/components/Sidebar/Widgets/Menu/Menu.d.ts

@@ -1,10 +1,24 @@
 import { SvgIconProps } from '@lokalise/louis';
 import { FC, PropsWithChildren } from 'react';
 type MenuProps = PropsWithChildren<{
+    /** Icon component from @lokalise/louis to display in the menu button */
     icon: FC<SvgIconProps>;
 }>;
 /**
- * Use this widget for simple side menu. Currently utilised for `Help` section
+ * A dropdown menu component that displays an icon button which reveals a menu list when clicked.
+ * The menu is positioned to the right of the button and includes a tooltip.
+ *
+ * Used primarily for dropdown menus in the Sidebar, such as the Help menu.
+ *
+ * @example
+ * ```tsx
+ * <Menu icon={HelpCenterIcon}>
+ *   <MenuItem href="/docs">Documentation</MenuItem>
+ *   <MenuItem href="/tutorial">Tutorials</MenuItem>
+ *   <MenuDivider />
+ *   <MenuItem href="/blog">Blog</MenuItem>
+ * </Menu>
+ * ```
  */
 export declare const Menu: ({ children, icon: Icon }: MenuProps) => import("react/jsx-runtime").JSX.Element;
 export {};

package/dist/types/src/components/Sidebar/Widgets/ProfileMenu/ProfileMenu.d.ts

@@ -1,12 +1,30 @@
 import { ProfileMenuContentProps } from './ProfileMenuContent';
 import { SidebarProfileMenuConfig } from './types';
 type ProfileMenuProps = {
+    /** Configuration object containing team and user settings */
     config: SidebarProfileMenuConfig;
+    /** Render function for the menu content */
     children: ProfileMenuContentProps['children'];
 };
 /**
- * Contextual component, requires initial configuration
- * and works with internal widgets
+ * A contextual menu component that provides team management functionality.
+ * It manages team switching, profile settings, billing options, and upgrade prompts.
+ *
+ * The component uses a render prop pattern to provide context values to its children,
+ * allowing flexible composition of menu items based on user permissions and team status.
+ *
+ * @example
+ * ```tsx
+ * <ProfileMenu config={profileMenuConfig}>
+ *   {({ allowTeamCreation, showBillingButton }) => (
+ *     <>
+ *       <TeamSwitch onSwitchTeam={handleTeamSwitch} />
+ *       {allowTeamCreation && <MenuItem>Create new team</MenuItem>}
+ *       {showBillingButton && <MenuItem href="/billing">Billing</MenuItem>}
+ *     </>
+ *   )}
+ * </ProfileMenu>
+ * ```
  */
 export declare const ProfileMenu: ({ config, children }: ProfileMenuProps) => import("react/jsx-runtime").JSX.Element;
 export {};

package/dist/types/src/components/Sidebar/Widgets/ProfileMenu/ProfileSettingsMenuItem/ProfileSettingsMenuItem.d.ts

@@ -1,12 +1,42 @@
 type ProfileSettingsMenuItemProps = {
+    /** URL to the profile settings page */
     href: string;
+    /** User's email address to display below "Profile Settings" */
     userEmail: string;
+    /** Optional callback function for tracking or additional actions */
     onClick?: () => void;
+    /** Whether to hide the divider that appears below this menu item */
     hideBottomDivider?: boolean;
 };
 /**
- * Menu item that comes with a small user's email and renders conditionally,
- * only if team is not suspended or is not at the end of a trial
+ * A menu item component that provides access to profile settings.
+ *
+ * Features:
+ * - Displays "Profile Settings" with the user's email address below
+ * - Conditionally renders based on team status
+ * - Includes an optional divider below the item
+ * - Will not render if:
+ *   - Team is suspended
+ *   - Team's trial period has ended
+ *
+ * @example
+ * ```tsx
+ * <ProfileSettingsMenuItem
+ *   href="/settings/profile"
+ *   userEmail="user@example.com"
+ *   onClick={() => trackSettingsClick()}
+ * />
+ *
+ * // Without bottom divider
+ * <ProfileSettingsMenuItem
+ *   href="/settings/profile"
+ *   userEmail="user@example.com"
+ *   hideBottomDivider
+ * />
+ * ```
+ *
+ * @note This component must be used within a ProfileMenu component
+ * as it requires access to the ProfileMenu context for team status information.
  */
 export declare const ProfileSettingsMenuItem: ({ href, onClick, userEmail, hideBottomDivider, }: ProfileSettingsMenuItemProps) => import("react/jsx-runtime").JSX.Element | null;
 export {};

package/dist/types/src/components/Sidebar/Widgets/ProfileMenu/TeamMenuItem/TeamMenuItem.d.ts

@@ -1,13 +1,36 @@
 import { SidebarTeam } from '../../../types';
 type TeamMenuItemProps = {
+    /** Team to display. If not provided, uses the current team from context */
     team?: SidebarTeam;
+    /** Callback for when the team item is clicked. If provided, renders as a clickable MenuItem */
     onClick?: (team: SidebarTeam) => void;
+    /** Whether to hide the plan label (Free/Trial). Useful when displaying multiple teams */
     hidePlanLabel?: boolean;
 };
 /**
- * Uses context of current team, and depending on ability to switch team or not,
- * it renders as a div or clickable MenuItem. If used with TeamSwitch, it triggers `onSwitchTeams`
- * callback, passing relevant team as an argument
+ * A component that displays team information in a menu item format.
+ * Renders team logo (or default user icon), team name, role, and plan label.
+ *
+ * The component can be used in two modes:
+ * 1. As a static display of the current team (when no onClick handler is provided)
+ * 2. As a clickable menu item for team switching (when onClick handler is provided)
+ *
+ * @example
+ * ```tsx
+ * // Static current team display
+ * <TeamMenuItem />
+ *
+ * // Clickable team item for switching
+ * <TeamMenuItem
+ *   team={someTeam}
+ *   onClick={(team) => handleTeamSwitch(team)}
+ *   hidePlanLabel
+ * />
+ * ```
+ *
+ * @note This component must be used within a ProfileMenu component
+ * as it requires access to the ProfileMenu context for current team
+ * and plan information.
  */
 export declare const TeamMenuItem: ({ team, onClick, hidePlanLabel }: TeamMenuItemProps) => import("react/jsx-runtime").JSX.Element | null;
 export {};

package/dist/types/src/components/Sidebar/Widgets/ProfileMenu/TeamSwitch/TeamSwitch.d.ts

@@ -1,9 +1,28 @@
 import { SidebarTeam } from '../../../types';
 type TeamSwitchProps = {
+    /** Callback function triggered when a user selects a different team */
     onSwitchTeam: (team: SidebarTeam) => void;
 };
 /**
- * Uses available teams (other than current) and allows user to switch between them
+ * A component that displays a list of available teams for switching.
+ * It automatically excludes the current team from the list and renders
+ * nothing if there are no other teams available.
+ *
+ * Uses the ProfileMenu context to access the list of other teams and
+ * renders each team as a TeamMenuItem with click functionality.
+ *
+ * @example
+ * ```tsx
+ * <TeamSwitch
+ *   onSwitchTeam={(team) => {
+ *     console.log(`Switching to team: ${team.name}`);
+ *     // Handle team switch logic
+ *   }}
+ * />
+ * ```
+ *
+ * @note This component must be used within a ProfileMenu component
+ * as it requires access to the ProfileMenu context.
  */
 export declare const TeamSwitch: ({ onSwitchTeam }: TeamSwitchProps) => import("react/jsx-runtime").JSX.Element | null;
 export {};

package/dist/types/src/components/Sidebar/Widgets/ProfileMenu/UpgradeMenuItem/UpgradeMenuItem.d.ts

@@ -1,10 +1,26 @@
 type UpgradeMenuItemProps = {
+    /** URL to the upgrade page or pricing options */
     upgradeOptionHref: string;
 };
 /**
- * Menu item conditionally rendering only if `showUpgradeButton` is `true`.
- * It renders correct upgrade note depending on the current team plan
- * and red arrow up to indicate an update option.
+ * A menu item component that displays upgrade call-to-action information.
+ * Only renders when upgrade options should be shown (determined by context).
+ *
+ * The component displays different messages based on the team's current plan:
+ * - For free plans: "Your team is currently on the Free plan"
+ * - For trial plans: "Free trial ends in X days"
+ *
+ * Includes an upgrade icon and "See upgrade options" text, styled to draw attention
+ * to the upgrade opportunity.
+ *
+ * @example
+ * ```tsx
+ * <UpgradeMenuItem upgradeOptionHref="/pricing" />
+ * ```
+ *
+ * @note This component must be used within a ProfileMenu component
+ * as it requires access to the ProfileMenu context for plan information
+ * and visibility control.
  */
 export declare const UpgradeMenuItem: ({ upgradeOptionHref }: UpgradeMenuItemProps) => import("react/jsx-runtime").JSX.Element | null;
 export {};

package/dist/types/src/components/Sidebar/Widgets/ProfileMenu/types.d.ts

@@ -1,5 +1,9 @@
 import { SidebarTeam, SidebarTeamRole } from '../../types';
 export type { SidebarTeam, SidebarTeamRole } from '../../types';
+/**
+ * Configuration object for the Sidebar's ProfileMenu component.
+ * Contains data from various API endpoints and JWT token.
+ */
 export type SidebarProfileMenuConfig = {
     teams: SidebarTeam[];
     isTeamSuspended: boolean;
@@ -12,6 +16,9 @@ export type SidebarProfileMenuConfig = {
     userTeamRole: SidebarTeamRole;
     userEmail: string;
 };
+/**
+ * Extended configuration including computed properties used within the ProfileMenu context.
+ */
 export type SidebarProfileMenuContextProps = SidebarProfileMenuConfig & {
     currentTeam?: SidebarTeam;
     otherTeams: SidebarTeam[];

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@lokalise/harmony",
-    "version": "1.11.0",
+    "version": "1.11.1",
     "author": {
         "name": "Lokalise",
         "url": "https://lokalise.com/"