@maropost-ui/liquidsky-ui 0.1.77 → 1.0.0-alpha.1

package/README.md

@@ -35,9 +35,11 @@ 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`.
+
 ------------------------------------------------------------------------
 
 ------------------------------------------------------------------------
@@ -137,67 +139,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
 ```
 
-#### 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/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
+```
+
+```bash
+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.
+
 ------------------------------------------------------------------------
 
 

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

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

package/dist/components/AppStepper/useStepper.d.ts

@@ -5,12 +5,12 @@ export declare function useStepper(steps: TStepItem[]): {
         name: string;
         order: number;
         id: number;
-        component?: {
+        component?: import("vue").FunctionalComponent<any, {}, any, {}> | {
             new (...args: any[]): any;
             __isFragment?: never;
             __isTeleport?: never;
             __isSuspense?: never;
-        } | import("vue").FunctionalComponent<any, {}, any, {}> | {
+        } | {
             [x: string]: any;
             setup?: ((this: void, props: import("@vue/shared").LooseRequired<any>, ctx: {
                 attrs: import("vue").Attrs;
@@ -135,12 +135,12 @@ export declare function useStepper(steps: TStepItem[]): {
         name: string;
         order: number;
         id: number;
-        component?: {
+        component?: import("vue").FunctionalComponent<any, {}, any, {}> | {
             new (...args: any[]): any;
             __isFragment?: never;
             __isTeleport?: never;
             __isSuspense?: never;
-        } | import("vue").FunctionalComponent<any, {}, any, {}> | {
+        } | {
             [x: string]: any;
             setup?: ((this: void, props: import("@vue/shared").LooseRequired<any>, ctx: {
                 attrs: import("vue").Attrs;

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,38 @@
+import type { NotificationIconProps } from '../../types/NotificationIconProps';
+import type { MpTestIdProps } from '../../types/MpTestIdProps';
+/** Application-owned permissions and navigation for Liquidsky's header controls. */
+export type HeaderActions = {
+    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;
+} & 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,21 @@ 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 { 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 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

@@ -10,3 +10,4 @@ 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/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;
+};