@maropost-ui/liquidsky-ui 0.1.80 → 1.0.0-alpha.2

package/README.md

@@ -35,9 +35,10 @@ The following packages are required as peer dependencies:
 npm install @maropost-ui/liquidsky-ui
 ```
 ```typescript
-import { AppBreadcrumb } from '@maropost-ui/liquidsky-ui'
+import { AppBreadcrumb, TheThemeSwitcher } from '@maropost-ui/liquidsky-ui'
 ```
 
+Theme lives in `TheUserDropdown`: click **Theme** for Classic / Marobase. Light / Dark sun–moon controls appear on the right only for Marobase. Persist key is `liquidsky-theme`.
 
 ## Test identifiers (`v-mp-test`)
 
@@ -55,7 +56,6 @@ MP_TEST_COMPONENT_DEFAULTS.AppDialogWrapper.ids
 
 Storybook: **Directives → MpTest** (catalog of defaults).
 
-
 ------------------------------------------------------------------------
 
 ------------------------------------------------------------------------
@@ -155,67 +155,132 @@ You may also keep using **`v-btn`**, **`v-tooltip`**, etc., after Liquidsky is i
 -------------------------------------------------------------------------
 
 
-## @maropost-ui/liquidsky-ui Local Development Guide
-Use these methods to test @maropost-ui/liquidsky-ui changes in your consuming project (e.g., commerce-frontend or commerce-backoffice) without publishing to npm. Both leverage npm's linking and packaging features for rapid iteration in your app workflow.
+## Local development in a consuming app
+
+Use **`npm install`** for CI, teammates, and anything that should match production. Use **`npm link`** only when you are changing Liquidsky locally and want the app to pick up rebuilt `dist/` without publishing.
+
+Liquidsky ships **Vuetify** as a dependency. Commerce apps typically do not declare `vuetify` themselves.
 
+### Webpack `vue.config.js` (required for Vue CLI apps)
 
+Add this whether the app uses `npm install` or `npm link`. It keeps a single Vue copy and tells webpack where Vuetify is.
 
-### 🚀 Method 1: npm link (Recommended for Active Development)
-Creates a symlink for instant hot-reloading of changes.
+```js
+const path = require('path')
+const { createLiquidskyWebpackResolve } = require('@maropost-ui/liquidsky-ui/webpack')
 
-> **Note:** This method does **not** work well with Webpack. If you are using Vite, this is the preferred approach. Otherwise, use Method 2.
+const liquidskyResolve = createLiquidskyWebpackResolve(__dirname)
+
+module.exports = {
+  transpileDependencies: ['@maropost-ui/liquidsky-ui'],
+  configureWebpack: {
+    resolve: {
+      ...liquidskyResolve,
+      alias: {
+        '@': path.resolve(__dirname, 'src'),
+        ...liquidskyResolve.alias,
+      },
+    },
+  },
+}
+```
 
-#### Steps:
+`@maropost-ui/liquidsky-ui/webpack` exists only in Liquidsky versions that include this helper. Install from this repo (pack / path) until that version is published.
 
-1. **Clone the repository:**
-   ```bash
-   git clone <repo-url> liquidsky-frontend
-   cd liquidsky-frontend
-   git checkout main
-   ```
+---
 
-2. **Install dependencies and build the package:**
-   ```bash
-   npm install
-   npm run dev
-   ```
+### Method 1: `npm install` (normal / published / pack)
 
-3. **Create a local npm link:**
-   ```bash
-   npm link
-   ```
+No `link:webpack`. No `--app`. npm hoists Vuetify into the app’s `node_modules`.
 
-4. **In your consuming project (e.g., `commerce-frontend`):**
-   ```bash
-   cd /path/to/your/consuming-project
-   npm link @maropost-ui/liquidsky-ui
-   ```
+**From the registry** (after the helper is published):
 
-Now, any changes you make in the `liquidsky-frontend` package will be reflected in your consuming project after rebuilding the library. This is useful for rapid development and testing across multiple projects locally.
+```bash
+cd /path/to/maropost-frontend-app   # or maropost-cloud-frontend / commerce-backoffice-frontend
+npm install @maropost-ui/liquidsky-ui
+```
 
-### 📦 Method 2: Local npm pack (For Stable Builds)
-Generates a distributable .tgz file for one-off installs.
+**From this repo, without publishing:**
 
-#### Step 1: Clone and build the library
 ```bash
-git clone <repo-url> liquidsky-frontend
 cd liquidsky-frontend
-git checkout main
 npm install
 npm run build
+npm pack
+```
+
+```bash
+cd /path/to/maropost-frontend-app   # or maropost-cloud-frontend / commerce-backoffice-frontend
+npm unlink --no-save @maropost-ui/liquidsky-ui   # only if you previously npm-linked
+npm install /path/to/liquidsky-frontend/maropost-ui-liquidsky-ui-<version>.tgz
 ```
-#### Step 2: Create package
+
+Prefer the `.tgz` over `npm install /path/to/liquidsky-frontend`. A folder install can still symlink and hit the same webpack issue as a repo-root `npm link`.
+
+---
+
+### Method 2: `npm link` (local Liquidsky changes)
+
+**Do not `npm link` from this repo root in a Webpack app.** Webpack follows that symlink into Liquidsky’s `node_modules` and loads a second Vue.
+
+#### Vite consumers
+
 ```bash
-npm pack
-Creates liquidsky-ui-<version>.tgz.
+cd liquidsky-frontend
+npm install
+npm run dev
+npm link
+```
+
+```bash
+cd /path/to/your-vite-app
+npm link @maropost-ui/liquidsky-ui
+```
+
+#### Webpack consumers (maropost-frontend-app / maropost-cloud-frontend / commerce-backoffice-frontend)
+
+`--app` is **one-time setup** for that app (creates `node_modules/vuetify` if it is missing). You do not pass the path on later rebuilds.
+
+The `--` after `npm run link:webpack` forwards flags to the script.
+
+**Once per webpack app:**
+
+```bash
+cd liquidsky-frontend
+npm install
+npm run build
+npm run link:webpack -- --app /path/to/maropost-frontend-app
+# or
+npm run link:webpack -- --app /path/to/maropost-cloud-frontend
+# or
+npm run link:webpack -- --app /path/to/commerce-backoffice-frontend
 ```
 
-#### Step 3: Install in consuming project
 ```bash
-cd /path/to/commerce-backoffice  # or your project
-npm install ../../path/to/liquidsky-frontend/liquidsky-ui-<version>.tgz
+cd /path/to/maropost-frontend-app   # or maropost-cloud-frontend / commerce-backoffice-frontend
+npm unlink --no-save @maropost-ui/liquidsky-ui   # if you previously linked the repo root
+npm link @maropost-ui/liquidsky-ui
 ```
 
+If a **repo-root** link is still registered globally:
+
+```bash
+npm unlink -g @maropost-ui/liquidsky-ui
+```
+
+**Every later rebuild** (no `--app`):
+
+```bash
+cd liquidsky-frontend
+npm run link:webpack
+# or, rebuild on save:
+npm run link:webpack:watch
+```
+
+Then restart or refresh the webpack app. `link:webpack` copies `dist/` to `../.liquidsky-ui-link` (a folder with no Liquidsky Vue) and runs `npm link` from there.
+
+Use `--app` again only if you clone a new consumer, delete `node_modules`, or Vuetify disappears from the app.
+
 ------------------------------------------------------------------------
 
 
@@ -318,4 +383,3 @@ stories/
 ```
 
 
-

package/dist/assets/raw-svg.d.ts

@@ -0,0 +1,4 @@
+declare module '*.svg?raw' {
+    const source: string;
+    export default source;
+}

package/dist/components/MpSectionRail/types.d.ts

@@ -0,0 +1,45 @@
+import type { RouteLocationRaw } from 'vue-router';
+export interface MpSectionRailItem {
+    slug: string;
+    label: string;
+    /** Lucide icon name (kebab-case). Omit for text-only rows (Settings flavor). */
+    icon?: string;
+    to: RouteLocationRaw;
+    /** Route names that keep this item highlighted (the section's children/editors). */
+    match?: string[];
+    /** Optional count chip shown at the end of the row. */
+    count?: number;
+    /** Renders an external-link glyph after the label. */
+    external?: boolean;
+}
+export interface MpSectionRailGroup {
+    /** Optional uppercase group heading. */
+    title?: string;
+    items: MpSectionRailItem[];
+}
+export interface MpSectionRailSwitchOption {
+    id: string;
+    label: string;
+    caption?: string;
+    icon?: string;
+}
+export interface MpSectionRailProps {
+    /** Accessible name for the rail's nav landmark. */
+    ariaLabel: string;
+    groups: MpSectionRailGroup[];
+    /** Plain heading (module flavor, e.g. "Settings"). */
+    title?: string;
+    backTo?: RouteLocationRaw;
+    backLabel?: string;
+    /** Entity identity card (entity flavor, e.g. a store). */
+    identity?: {
+        name: string;
+        caption?: string;
+        icon?: string;
+    };
+    /** Other entities the user can jump to; renders the switcher menu on the identity card. */
+    switcherOptions?: MpSectionRailSwitchOption[];
+    switcherLabel?: string;
+    searchable?: boolean;
+    searchPlaceholder?: string;
+}

package/dist/components/TheAppShell/index.d.ts

@@ -0,0 +1 @@
+export { default } from './TheAppShell.vue';

package/dist/components/TheHeader/index.d.ts

@@ -0,0 +1,3 @@
+export { default } from './TheHeader.vue';
+export { default as ClassicHeader } from './Classic/TheHeader.vue';
+export { default as MarobaseHeader } from './Marobase/TheHeader.vue';

package/dist/components/TheHeader/types.d.ts

@@ -0,0 +1,68 @@
+import type { NotificationIconProps } from '../../types/NotificationIconProps';
+import type { MpNotificationsMenuProps } from '../../types/MpNotificationsMenuProps';
+import type { NotificationItem } from '../../types/TheNotificationDrawerProps';
+import type { MpTestIdProps } from '../../types/MpTestIdProps';
+export type CreateNewMenuIcon = 'dashboard' | 'email-campaign' | 'segment' | 'automation' | 'contact-list';
+/** A destination shown in the Marobase header's Create new menu. */
+export type CreateNewMenuItem = {
+    /** Stable key for rendering the item. */
+    id: string;
+    title: string;
+    description?: string;
+    /** Icon rendered by the library. */
+    icon?: CreateNewMenuIcon;
+    /** Optional keyboard hint displayed at the end of the item. */
+    shortcut?: string;
+    /** Application-owned navigation or creation action. */
+    onClick: () => void;
+};
+export type MpNotificationsMenuBindings = MpNotificationsMenuProps & {
+    onOpen?: () => void;
+    onClose?: () => void;
+    onSeeAll?: () => void;
+    onMarkAllRead?: () => void;
+    onNotificationClick?: (notification: NotificationItem) => void;
+    onDownload?: (notification: NotificationItem) => void;
+    onRetry?: () => void;
+    onLoadMore?: () => void;
+};
+/** Application-owned permissions and navigation for Liquidsky's header controls. */
+export type HeaderActions = {
+    /** Items for the Marobase Create new (+) menu. When omitted, + retains its What's new action. */
+    createNewItems?: CreateNewMenuItem[];
+    showSettings?: boolean;
+    settingsHref?: string;
+    onSettingsClick?: (event: MouseEvent) => void;
+    onDaVinciClick: () => void;
+    onWhatsNewClick: () => void;
+    helpCenterUrl?: string;
+    raiseTicketUrl?: string;
+};
+export type TheHeaderProps = {
+    /** Opt into the theme's utility controls in place of the default timezone. */
+    actions?: HeaderActions;
+    /** notification count e.g. 5 */
+    notificationCount?: number;
+    /** timezone e.g. UTC, EST, etc. */
+    timezone?: string;
+    /** route to preferences : on click to timezone it will open the preferences page*/
+    routeToPreferences?: string;
+    /** is page loading e.g. true or false */
+    isPageLoading: boolean;
+    /** toggle left menu e.g. true or false */
+    toggleLeftMenu: () => void;
+    /** user menu items e.g. [{ title: "Profile", icon: "mdi-account", action: () => {} }, { title: "Settings", icon: "mdi-cog", action: () => {} }] */
+    userMenuItems?: any[];
+    /** username e.g. John Doe */
+    username?: string;
+    /** logout e.g. () => {} */
+    logout?: () => void;
+    /** account id e.g. 20001 */
+    accountId?: string | number;
+    /** show app bar nav icon e.g. true or false */
+    hideAppBarNavIcon?: boolean;
+    /** notification icon props e.g. { icon: "mdi-bell", color: "primary" } */
+    notificationIconProps?: NotificationIconProps;
+    /** Marobase notification menu data, states, and application-owned action handlers. */
+    notificationMenuProps?: MpNotificationsMenuBindings;
+} & MpTestIdProps;

package/dist/components/TheSearchBar/index.d.ts

@@ -0,0 +1,3 @@
+export { default } from './TheSearchBar.vue';
+export { default as ClassicSearchBar } from './Classic/TheSearchBar.vue';
+export { default as MarobaseSearchBar } from './Marobase/TheSearchBar.vue';

package/dist/components/TheSearchBar/types.d.ts

@@ -0,0 +1,8 @@
+import type { MpTestIdProps } from '../../types/MpTestIdProps';
+export type TheSearchBarProps = {
+    /** The name of the query parameter to use for search (defaults to 'q') */
+    queryParamName?: string;
+    show?: boolean;
+    placeholder?: string;
+    containerClass?: string;
+} & MpTestIdProps;

package/dist/components/TheSearchBar/useTheSearchBar.d.ts

@@ -0,0 +1,12 @@
+import type { TheSearchBarProps } from './types';
+export declare function useTheSearchBar(props: TheSearchBarProps): {
+    mpTestId: import("vue").ComputedRef<string>;
+    keyword: import("vue").Ref<string | undefined, string | undefined>;
+    clearSearch: () => void;
+    searchPlaceholder: import("vue").ComputedRef<string>;
+    showSearchBar: import("vue").ComputedRef<boolean>;
+    handleSearchKeyup: (event: KeyboardEvent) => void;
+    isFocused: import("vue").Ref<boolean, boolean>;
+    onSearchFocus: () => void;
+    onSearchBlur: () => void;
+};

package/dist/components/TheUnifiedNavigation/index.d.ts

@@ -1,5 +1,9 @@
 export { default as TheUnifiedNavigation } from './TheUnifiedNavigation.vue';
-export { default as UnifiedNavigationBlock } from './UnifiedNavigationBlock.vue';
-export { default as NavigationToggleButton } from './NavigationToggleButton.vue';
-export { default as SubMenuDialog } from './SubMenuDialog.vue';
-export { default as UnifiedNavigationNode } from './UnifiedNavigationNode.vue';
+export { default as ClassicUnifiedNavigation } from './classic/ClassicUnifiedNavigation.vue';
+export { default as UnifiedNavigationBlock } from './classic/UnifiedNavigationBlock.vue';
+export { default as NavigationToggleButton } from './classic/NavigationToggleButton.vue';
+export { default as SubMenuDialog } from './classic/SubMenuDialog.vue';
+export { default as UnifiedNavigationNode } from './classic/UnifiedNavigationNode.vue';
+export { default as MarobaseSidebar } from './marobase/MarobaseSidebar.vue';
+export type { MarobaseSidebarProps, AppSidebarProps } from './marobase/types';
+export { default as TheAppSidebar } from './marobase/MarobaseSidebar.vue';

package/dist/components/TheUnifiedNavigation/marobase/navigation.d.ts

@@ -0,0 +1,7 @@
+import type { UnifiedNavigationItem } from '../../../types/UnifiedNavigationProps';
+export type SidebarSection = {
+    key: string;
+    items: UnifiedNavigationItem[];
+};
+export declare function sidebarSections(items: UnifiedNavigationItem[]): SidebarSection[];
+export declare function scopedPath(item: UnifiedNavigationItem, accountId: string): string | undefined;

package/dist/components/TheUnifiedNavigation/marobase/types.d.ts

@@ -0,0 +1,14 @@
+import type { SidebarGetStarted, UnifiedNavigationProps } from '../../../types/UnifiedNavigationProps';
+export interface MarobaseSidebarProps extends UnifiedNavigationProps {
+    modelValue?: boolean;
+    temporary?: boolean;
+    width?: number;
+    railWidth?: number;
+    brandLabel?: string;
+    getStarted?: SidebarGetStarted;
+    /** Optional controlled section. When omitted, enableStoreMenu supplies route state. */
+    activeSection?: 'store' | null;
+    sectionWidth?: number;
+}
+/** Previous public name for MarobaseSidebarProps. */
+export type AppSidebarProps = MarobaseSidebarProps;

package/dist/components/TheUserDropdown/index.d.ts

@@ -0,0 +1,3 @@
+export { default as TheUserDropdown } from './TheUserDropdown.vue';
+export { default as ClassicUserDropdown } from './classic/ClassicUserDropdown.vue';
+export { default as MarobaseUserDropdown } from './marobase/MarobaseUserDropdown.vue';

package/dist/components/TheUserDropdown/useUserDropdownMenu.d.ts

@@ -0,0 +1,12 @@
+import type { TheUserDropdownProps } from '../../types/TheUserDropdownProps';
+import type { ThemeAppearance } from '../../themes';
+export declare function userInitialsFromName(username: string | undefined): string;
+export declare function useUserDropdownMenu(props: TheUserDropdownProps, emit: (event: 'logout') => void): {
+    mpTestId: import("vue").ComputedRef<string>;
+    isMenuOpen: import("vue").Ref<boolean, boolean>;
+    family: import("vue").ComputedRef<import("../../themes").ThemeFamily>;
+    userInitials: import("vue").ComputedRef<string>;
+    appearanceToggle: import("vue").WritableComputedRef<ThemeAppearance, ThemeAppearance | ThemeAppearance[] | null>;
+    setFamily: (next: import("../../themes").ThemeFamily) => void;
+    onClickLogoutHandler: () => void;
+};

package/dist/components/index.d.ts

@@ -22,15 +22,23 @@ export { default as AppTooltip } from "./AppTooltip.vue";
 export { default as AppGridTable } from "./AppGridTable.vue";
 export { default as TheAccountDropdown } from "./TheAccountDropdown.vue";
 export { default as TheAppsDropdown } from "./TheAppsDropdown.vue";
-export { default as TheHeader } from "./TheHeader.vue";
+export { default as TheHeader } from "./TheHeader";
+export type { CreateNewMenuIcon, CreateNewMenuItem, HeaderActions, MpNotificationsMenuBindings, TheHeaderProps } from './TheHeader/types';
+export { default as TheAppShell } from "./TheAppShell";
 export { default as TheNavigation } from "./TheNavigation.vue";
 export { default as TheNotificationDrawer } from "./TheNotificationDrawer.vue";
 export { default as TheNotificationIcon } from "./TheNotificationIcon.vue";
-export { default as TheSearchBar } from "./TheSearchBar.vue";
+export { default as MpNotificationsMenu } from "./MpNotificationsMenu.vue";
+export { default as TheSearchBar } from "./TheSearchBar";
 export { default as TheSecondaryNavigation } from "./TheSecondaryNavigation.vue";
+export { default as MpSectionRail } from './MpSectionRail/MpSectionRail.vue';
+export { default as StoreSectionRail } from './MpSectionRail/StoreSectionRail.vue';
+export type { MpSectionRailProps, MpSectionRailItem, MpSectionRailGroup, MpSectionRailSwitchOption } from './MpSectionRail/types';
+export { default as TheThemeSwitcher } from "./TheThemeSwitcher.vue";
 export { default as TheTimezone } from "./TheTimezone/TheTimezone.vue";
-export { default as TheUserDropdown } from "./TheUserDropdown.vue";
-export { TheUnifiedNavigation } from "./TheUnifiedNavigation";
+export { TheUserDropdown, MarobaseUserDropdown } from "./TheUserDropdown";
+export { TheUnifiedNavigation, MarobaseSidebar, TheAppSidebar } from "./TheUnifiedNavigation";
+export type { MarobaseSidebarProps, AppSidebarProps } from "./TheUnifiedNavigation";
 export { default as AlertModal } from "./AlertModal.vue";
 export { default as TheOnboardingBanner } from "./TheOnboardingBanner.vue";
 export { default as TheOnboardingScreenChecklists } from "./TheOnboardingScreenChecklists.vue";

package/dist/composables/index.d.ts

@@ -6,7 +6,10 @@ export { default as useValidation } from "./useValidation";
 export { default as useClipboard } from "./useClipboard";
 export { default as useDebounce } from "./useDebounce";
 export { default as useEmoji } from "./useEmoji";
+export { default as useHotkeys } from "./useHotkeys";
+export type { HotkeyBinding, UseHotkeysOptions } from "./useHotkeys";
 export { default as toRefs } from "./toRefs";
 export { default as useUnitConversion } from "./useUnitConversion";
 export { default as useTimezoneTime } from "./useCalculateTime";
 export { default as useMpTestId, resolveMpTestId } from "./useMpTestId";
+export { default as useLiquidSkyTheme, resetLiquidSkyThemeForTests } from "./useLiquidSkyTheme";

package/dist/composables/useHotkeys.d.ts

@@ -0,0 +1,36 @@
+import { type MaybeRefOrGetter } from 'vue';
+export type HotkeyBinding = {
+    key: string;
+    handler: (event: KeyboardEvent) => void;
+};
+export type UseHotkeysOptions = {
+    /** Reactively enables or disables all bindings. */
+    enabled?: MaybeRefOrGetter<boolean>;
+    /** Allow shortcuts while typing in inputs, textareas, selects, or editable content. */
+    allowInEditable?: boolean;
+    /** Ignore key-repeat events. */
+    ignoreRepeat?: boolean;
+    /** Prevent the browser's default action when a binding matches. */
+    preventDefault?: boolean;
+};
+/**
+ * @description Listen for case-insensitive, unmodified keyboard shortcuts and fire matching handlers.
+ * Bindings and the enabled state may be reactive. By default, shortcuts are ignored while the
+ * user is typing, during IME composition, when modifier keys are held, and for repeated keydown
+ * events. The window listener is registered and removed with the owning component lifecycle.
+ *
+ * @example
+ * import { computed, ref } from 'vue'
+ * import { useHotkeys } from '@maropost-ui/liquidsky-ui'
+ *
+ * const menuOpen = ref(false)
+ * const bindings = computed(() => [
+ *   { key: 'D', handler: () => router.push('/dashboard') },
+ *   { key: 'E', handler: () => router.push('/campaigns/new') },
+ * ])
+ *
+ * useHotkeys(bindings, { enabled: menuOpen })
+ */
+export default function useHotkeys(bindings: MaybeRefOrGetter<HotkeyBinding[]>, options?: UseHotkeysOptions): {
+    handleKeydown: (event: KeyboardEvent) => void;
+};

package/dist/composables/useLiquidSkyTheme.d.ts

@@ -0,0 +1,13 @@
+import { type LiquidSkyThemeName, type ThemeAppearance, type ThemeFamily } from '../themes';
+export declare function resetLiquidSkyThemeForTests(): void;
+export default function useLiquidSkyTheme(options?: {
+    persist?: boolean;
+    storageKey?: string;
+}): {
+    themeName: import("vue").Ref<LiquidSkyThemeName, LiquidSkyThemeName>;
+    family: import("vue").ComputedRef<ThemeFamily>;
+    appearance: import("vue").ComputedRef<ThemeAppearance>;
+    setTheme: (name: LiquidSkyThemeName) => void;
+    setFamily: (next: ThemeFamily) => void;
+    setAppearance: (next: ThemeAppearance) => void;
+};

package/dist/composables/useMpTestId.d.ts

@@ -1,13 +1,13 @@
 import { type MpTestBindingObject } from '../directives/MpTest';
+import { type ComputedRef, type MaybeRefOrGetter } from 'vue';
 /**
  * @deprecated Prefer `resolveMpTestBinding` / `v-mp-test`.
  * Legacy `(defaultId, testId?, testIdSuffix?)` still supported.
  */
 export declare function resolveMpTestId(defaultIdOrBinding: string | MpTestBindingObject, testId?: string, testIdSuffix?: string): string;
 /**
- * @deprecated Use `v-mp-test="MP_TEST_IDS.*"` or
- * `v-mp-test="{ action, module, suffix }"`.
+ * @deprecated Prefer `v-mp-test="MP_TEST_IDS.*"` or
+ * `v-mp-test="{ action, module, suffix }"`. This compatibility wrapper remains
+ * available for themed components and consumers using the legacy test-id props.
  */
-export default function useMpTestId(_defaultId: string, _testId?: unknown, _testIdSuffix?: unknown): {
-    readonly value: string;
-};
+export default function useMpTestId(defaultId: string, testId?: MaybeRefOrGetter<string | undefined>, testIdSuffix?: MaybeRefOrGetter<string | undefined>): ComputedRef<string>;