@iress-oss/ids-components 6.0.0-alpha.3 → 6.0.0-alpha.30

package/dist/patterns/Shadow/meta/Thumbnail.d.ts

@@ -0,0 +1,2 @@
+declare const Thumbnail: () => import("react/jsx-runtime").JSX.Element;
+export default Thumbnail;

package/dist/patterns/Shadow/meta/index.d.ts

@@ -0,0 +1,7 @@
+declare const _default: {
+    heading: string;
+    href: string;
+    tags: string[];
+    Thumbnail: import('react').LazyExoticComponent<() => import("react/jsx-runtime").JSX.Element>;
+};
+export default _default;

package/dist/patterns/SideNav/SideNav.d.ts

@@ -0,0 +1,156 @@
+import { ElementType, MouseEventHandler, ReactNode } from 'react';
+import { MaterialSymbol } from 'material-symbols';
+import { IressStyledProps } from '../../types';
+/**
+ * A flat navigation item shown in the side panel.
+ */
+export interface SideNavSubItem {
+    /** Unique key for the item. */
+    key: string;
+    /** Display label for the sub-item. */
+    label: ReactNode;
+    /** URL for the navigation link — renders an anchor. */
+    href?: string;
+    /** Custom element type for third-party routing libraries. */
+    element?: ElementType;
+    /** Optional click handler for side-effects. */
+    onClick?: MouseEventHandler;
+    /** Whether this sub-item is currently active/selected. */
+    active?: boolean;
+}
+/**
+ * A group of sub-items displayed as an expandable drawer in the side panel.
+ */
+export interface SideNavSideMenuGroup {
+    /** Unique key for the group. */
+    key: string;
+    /** Display label for the drawer header. */
+    label: ReactNode;
+    /** Child items shown inside this drawer. */
+    children: SideNavSubItem[];
+    /** Whether this drawer is active/expanded. */
+    active?: boolean;
+}
+/**
+ * A panel content entry — either a flat item or a group of items.
+ *
+ * When mixing flat items and groups in a single array, ensure all `key` values
+ * are unique across both types to avoid React reconciliation issues.
+ */
+export type SideNavPanelItem = SideNavSubItem | SideNavSideMenuGroup;
+/**
+ * A top-level navigation item with a rail icon and optional panel children.
+ */
+export interface SideNavItem {
+    /** Unique key for the item. */
+    key: string;
+    /** Icon shown on the rail (Material Symbol name). */
+    icon: MaterialSymbol;
+    /** Display label for the item. */
+    label: ReactNode;
+    /** Accessible label for the rail icon tooltip. */
+    ariaLabel?: string;
+    /**
+     * Content shown in the side panel when this item is active.
+     * Can be flat sub-items, grouped sub-items, or a mix of both.
+     */
+    children?: SideNavPanelItem[];
+    /** URL for navigation. */
+    href?: string;
+    /** Custom element type for third-party routing libraries. */
+    element?: ElementType;
+    /** Optional click handler for side-effects. */
+    onClick?: MouseEventHandler;
+    /** Show a divider after this item in the rail. */
+    divider?: boolean;
+}
+/**
+ * Common props shared by all IressSideNav configurations.
+ */
+interface IressSideNavBaseProps extends Omit<IressStyledProps<'nav'>, 'width'> {
+    /** Array of navigation items defining the rail icons. */
+    items: SideNavItem[];
+    /** Callback fired when the active item changes via a rail click. */
+    onActiveItemKeyChange?: (key: string) => void;
+    /**
+     * Override: label displayed at the top of the side panel.
+     * When provided alongside sideMenuItems, this replaces the active item's label.
+     */
+    sideMenuLabel?: ReactNode;
+    /** Whether the side panel is expanded (controlled). */
+    expanded?: boolean;
+    /**
+     * Default expanded state (uncontrolled).
+     * @default false
+     */
+    defaultExpanded?: boolean;
+    /** Callback when the expanded state changes. */
+    onExpandedChange?: (expanded: boolean) => void;
+    /**
+     * Whether to show numbered headers in the expanded side menu.
+     * @default false
+     */
+    numbered?: boolean;
+    /** Content rendered at the top of the expanded side panel. */
+    header?: ReactNode;
+    /** Content rendered at the bottom of the expanded side panel. */
+    footer?: ReactNode;
+    /**
+     * Accessible label for the navigation landmark.
+     * @default 'Side navigation'
+     */
+    'aria-label'?: string;
+    /**
+     * Label text for the expand button (accessibility).
+     * @default 'Expand navigation'
+     */
+    expandLabel?: string;
+    /**
+     * Label text for the collapse button (accessibility).
+     * @default 'Collapse navigation'
+     */
+    collapseLabel?: string;
+    /**
+     * Width of the side panel when expanded. Can be a CSS length value or number (pixels).
+     * @default '250px'
+     */
+    width?: string | number;
+}
+/**
+ * When no `sideMenuItems` override is provided, `activeItemKey` is required
+ * to determine which rail item's children appear in the panel.
+ */
+interface IressSideNavWithActiveItem extends IressSideNavBaseProps {
+    /**
+     * Key of the active rail item.
+     * Sets the initial selection and can be updated externally.
+     * Rail clicks update the internal active item automatically.
+     */
+    activeItemKey: string;
+    sideMenuItems?: never;
+}
+/**
+ * When `sideMenuItems` are provided, they override the panel content
+ * and `activeItemKey` becomes optional (used only for rail highlighting).
+ */
+interface IressSideNavWithSideMenuItems extends IressSideNavBaseProps {
+    /**
+     * Override: content to display in the side panel instead of
+     * `items[activeItemKey].children`. Can be flat items, groups, or a mix.
+     */
+    sideMenuItems: SideNavPanelItem[];
+    /**
+     * Key of the active rail item.
+     * Optional when sideMenuItems is provided — used only for rail highlighting.
+     */
+    activeItemKey?: string;
+}
+/**
+ * Props for the IressSideNav component.
+ */
+export type IressSideNavProps = IressSideNavWithActiveItem | IressSideNavWithSideMenuItems;
+export declare const IressSideNav: {
+    ({ "aria-label": ariaLabel, activeItemKey, className, collapseLabel, "data-testid": dataTestId, defaultExpanded, expanded, expandLabel, footer, header, items, numbered, onActiveItemKeyChange, onExpandedChange, sideMenuItems, sideMenuLabel, style, width: widthProp, ...restProps }: IressSideNavProps): import("react/jsx-runtime").JSX.Element;
+    displayName: string;
+};
+export {};

package/dist/patterns/SideNav/SideNav.helpers.d.ts

@@ -0,0 +1,5 @@
+import { SideNavPanelItem, SideNavSideMenuGroup } from './SideNav';
+/**
+ * Type guard to check if a panel item is a group (has children).
+ */
+export declare const isSideNavGroup: (item: SideNavPanelItem) => item is SideNavSideMenuGroup;

package/dist/patterns/SideNav/SideNav.helpers.js

@@ -0,0 +1,4 @@
+const i = (r) => "children" in r && Array.isArray(r.children);
+export {
+  i as isSideNavGroup
+};

package/dist/patterns/SideNav/SideNav.js

@@ -0,0 +1,212 @@
+import { jsxs as m, jsx as i } from "react/jsx-runtime";
+import { useMemo as J } from "react";
+import { c as L } from "../../css-DVJ-ALYD.js";
+import { c as O } from "../../cx-DN21T1EH.js";
+import { s as Q } from "../../factory-CcYfm2kB.js";
+import { s as R } from "../../is-valid-prop-C5D641yn.js";
+import { IressMenu as N } from "../../components/Menu/Menu.js";
+import "../../components/Menu/Menu.styles.js";
+import "../../components/Menu/MenuItem/MenuItem.styles.js";
+import "../../components/Menu/MenuGroup/MenuGroup.styles.js";
+import "../../components/Menu/MenuDivider/MenuDivider.js";
+import { IressMenuGroup as U } from "../../components/Menu/MenuGroup/MenuGroup.js";
+import { IressMenuItem as n } from "../../components/Menu/MenuItem/MenuItem.js";
+import "../../components/Menu/MenuText/MenuText.js";
+import { GlobalCSSClass as V } from "../../enums.js";
+import { propagateTestid as l } from "../../helpers/utility/propagateTestid.js";
+import { sideNav as C } from "./SideNav.styles.js";
+import { useSideNavState as W } from "./hooks/useSideNavState.js";
+import { isSideNavGroup as X } from "./SideNav.helpers.js";
+import { IressText as Y } from "../../components/Text/Text.js";
+const Z = ({
+  "aria-label": u = "Side navigation",
+  activeItemKey: y,
+  className: S,
+  collapseLabel: p = "Collapse navigation",
+  "data-testid": a,
+  defaultExpanded: x,
+  expanded: _,
+  expandLabel: c = "Expand navigation",
+  footer: f,
+  header: v,
+  items: h,
+  numbered: $ = !1,
+  onActiveItemKeyChange: w,
+  onExpandedChange: M,
+  sideMenuItems: A,
+  sideMenuLabel: E,
+  style: G,
+  width: d,
+  ...g
+}) => {
+  const [j, K] = J(
+    () => R(g),
+    [g]
+  ), H = typeof d == "number" ? `${d}px` : d, {
+    isExpanded: t,
+    toggleExpanded: P,
+    resolvedActiveItemKey: q,
+    setActiveItemKey: z,
+    panelContent: B,
+    panelLabel: k,
+    hasPanelContent: D
+  } = W({
+    items: h,
+    activeItemKey: y,
+    onActiveItemKeyChange: w,
+    sideMenuItems: A,
+    sideMenuLabel: E,
+    expanded: _,
+    defaultExpanded: x,
+    onExpandedChange: M
+  }), r = C({ expanded: t }), F = C.raw({ expanded: t });
+  return /* @__PURE__ */ m(
+    Q.nav,
+    {
+      ...K,
+      "aria-label": u,
+      className: O(
+        L(F.root, j),
+        S,
+        V.SideNav
+      ),
+      "data-testid": a,
+      style: {
+        "--iress-width": H,
+        ...G
+      },
+      children: [
+        /* @__PURE__ */ m(
+          N,
+          {
+            variant: "rail",
+            "data-testid": l(a, "rail"),
+            children: [
+              h.map((e) => /* @__PURE__ */ i(
+                n,
+                {
+                  icon: e.icon,
+                  href: e.href,
+                  element: e.element,
+                  onClick: (s) => {
+                    z(e.key), e.onClick?.(s);
+                  },
+                  "aria-label": e.ariaLabel ?? (typeof e.label == "string" ? e.label : void 0),
+                  selected: q === e.key,
+                  "data-testid": l(a, `rail-item-${e.key}`),
+                  divider: e.divider,
+                  children: e.label
+                },
+                e.key
+              )),
+              /* @__PURE__ */ i(
+                n,
+                {
+                  className: r.toggle,
+                  listItemStyle: { className: r.toggle },
+                  icon: t ? "keyboard_double_arrow_left" : "keyboard_double_arrow_right",
+                  onClick: P,
+                  "aria-expanded": t,
+                  "aria-label": t ? p : c,
+                  "data-testid": l(a, "toggle"),
+                  children: t ? p : c
+                }
+              )
+            ]
+          }
+        ),
+        /* @__PURE__ */ i(
+          "div",
+          {
+            className: r.panel,
+            "data-testid": l(a, "panel"),
+            "aria-hidden": !t,
+            children: /* @__PURE__ */ i("div", { className: r.panelContent, children: /* @__PURE__ */ m("div", { className: r.panelContentInner, children: [
+              v && /* @__PURE__ */ i(
+                "div",
+                {
+                  className: r.header,
+                  "data-testid": l(a, "header"),
+                  children: v
+                }
+              ),
+              k && /* @__PURE__ */ i(
+                Y,
+                {
+                  className: r.panelHeading,
+                  element: "h2",
+                  textStyle: "typography.heading.3",
+                  "data-testid": l(a, "panel-heading"),
+                  children: k
+                }
+              ),
+              D && /* @__PURE__ */ i(
+                N,
+                {
+                  variant: "side",
+                  numbered: $,
+                  "data-testid": l(a, "side-menu"),
+                  children: B.map(
+                    (e, s) => X(e) ? /* @__PURE__ */ i(
+                      U,
+                      {
+                        label: e.label,
+                        defaultActive: e.active,
+                        "data-testid": l(
+                          a,
+                          `side-group-${e.key ?? s}`
+                        ),
+                        children: e.children.map((o, b) => /* @__PURE__ */ i(
+                          n,
+                          {
+                            href: o.href,
+                            element: o.element,
+                            onClick: o.onClick,
+                            selected: o.active,
+                            "data-testid": l(
+                              a,
+                              `side-item-${o.key ?? b}`
+                            ),
+                            children: o.label
+                          },
+                          o.key ?? b
+                        ))
+                      },
+                      e.key ?? s
+                    ) : /* @__PURE__ */ i(
+                      n,
+                      {
+                        href: e.href,
+                        element: e.element,
+                        onClick: e.onClick,
+                        selected: e.active,
+                        "data-testid": l(
+                          a,
+                          `side-item-${e.key ?? s}`
+                        ),
+                        children: e.label
+                      },
+                      e.key ?? s
+                    )
+                  )
+                }
+              ),
+              f && /* @__PURE__ */ i(
+                "div",
+                {
+                  className: r.footer,
+                  "data-testid": l(a, "footer"),
+                  children: f
+                }
+              )
+            ] }) })
+          }
+        )
+      ]
+    }
+  );
+};
+Z.displayName = "IressSideNav";
+export {
+  Z as IressSideNav
+};

package/dist/patterns/SideNav/SideNav.styles.d.ts

@@ -0,0 +1,14 @@
+export declare const sideNav: import('../../styled-system/types').SlotRecipeRuntimeFn<"footer" | "header" | "toggle" | "root" | "rail" | "panel" | "panelContent" | "panelContentInner" | "panelHeading", {
+    expanded: {
+        true: {
+            panel: {
+                maxWidth: "var(--iress-width, 260px)";
+            };
+        };
+        false: {
+            panel: {
+                maxWidth: "[0]";
+            };
+        };
+    };
+}>;

package/dist/patterns/SideNav/SideNav.styles.js

@@ -0,0 +1,87 @@
+import { s as e } from "../../sva-CsHRIRDW.js";
+const n = e({
+  slots: [
+    "root",
+    "rail",
+    "panel",
+    "panelContent",
+    "panelContentInner",
+    "panelHeading",
+    "header",
+    "footer",
+    "toggle"
+  ],
+  base: {
+    root: {
+      display: "flex",
+      flexDirection: "row",
+      height: "12/12",
+      gap: "spacing.3"
+    },
+    rail: {
+      display: "flex",
+      flexDirection: "column",
+      alignItems: "center",
+      flexShrink: 0
+    },
+    panel: {
+      maxWidth: "[0]",
+      overflow: "hidden",
+      transition: "[max-width 0.3s ease-in-out]"
+    },
+    panelContent: {
+      width: "var(--iress-width, 260px)"
+    },
+    panelContentInner: {
+      display: "flex",
+      flexDirection: "column",
+      border: "table",
+      borderRadius: "radius.system.layout",
+      m: "spacing.4",
+      boxShadow: "0 4px 20px #00327126",
+      pb: "spacing.2"
+    },
+    panelHeading: {
+      flexShrink: 0,
+      px: "spacing.4",
+      pt: "spacing.4",
+      pb: "spacing.2",
+      color: "colour.primary.text"
+    },
+    header: {
+      flexShrink: 0,
+      px: "spacing.4",
+      pt: "spacing.4"
+    },
+    footer: {
+      flexShrink: 0,
+      px: "spacing.4",
+      py: "spacing.2",
+      borderTop: "table",
+      mt: "auto"
+    },
+    toggle: {
+      mt: "auto"
+    }
+  },
+  variants: {
+    expanded: {
+      true: {
+        panel: {
+          maxWidth: "var(--iress-width, 260px)"
+        }
+      },
+      false: {
+        panel: {
+          maxWidth: "[0]"
+        }
+      }
+    }
+  },
+  defaultVariants: {
+    expanded: !1
+  }
+});
+export {
+  n as sideNav
+};

package/dist/patterns/SideNav/hooks/useSideNavState.d.ts

@@ -0,0 +1,47 @@
+import { SideNavItem, SideNavPanelItem } from '../SideNav';
+import { ReactNode } from 'react';
+export interface UseSideNavStateProps {
+    /** Array of navigation items defining the rail. */
+    items: SideNavItem[];
+    /**
+     * Key of the active rail item.
+     * Sets the initial selection and can be updated externally.
+     * Internal state is maintained for click-driven navigation.
+     */
+    activeItemKey?: string;
+    /** Callback fired when the active item changes via rail click. */
+    onActiveItemKeyChange?: (key: string) => void;
+    /** Override: content for the side panel (same type as children). */
+    sideMenuItems?: SideNavPanelItem[];
+    /** Override: label for the side panel heading. */
+    sideMenuLabel?: ReactNode;
+    /** Controlled expanded state. */
+    expanded?: boolean;
+    /** Default expanded state (uncontrolled). */
+    defaultExpanded?: boolean;
+    /** Callback when expanded state changes. */
+    onExpandedChange?: (expanded: boolean) => void;
+}
+export interface UseSideNavStateReturn {
+    /** Whether the panel is currently expanded. */
+    isExpanded: boolean;
+    /** Toggle the expanded state. */
+    toggleExpanded: () => void;
+    /** The resolved active item key. */
+    resolvedActiveItemKey: string | undefined;
+    /** Set the active item key (used by rail click handlers). */
+    setActiveItemKey: (key: string) => void;
+    /** The currently active item from items array. */
+    activeItem: SideNavItem | undefined;
+    /** Content entries to render in the side panel. */
+    panelContent: SideNavPanelItem[];
+    /** Resolved label for the side panel heading. */
+    panelLabel: ReactNode;
+    /** Whether the panel has any content to show. */
+    hasPanelContent: boolean;
+}
+/**
+ * Internal hook that manages the SideNav expanded/collapsed state
+ * and resolves which content to display in the side panel.
+ */
+export declare const useSideNavState: ({ items, activeItemKey, onActiveItemKeyChange, sideMenuItems, sideMenuLabel, expanded, defaultExpanded, onExpandedChange, }: UseSideNavStateProps) => UseSideNavStateReturn;

package/dist/patterns/SideNav/hooks/useSideNavState.js

@@ -0,0 +1,57 @@
+import { useState as A, useEffect as I, useCallback as u } from "react";
+import { useControlledState as N } from "../../../hooks/useControlledState.js";
+const y = ({
+  items: n,
+  activeItemKey: o,
+  onActiveItemKeyChange: c,
+  sideMenuItems: l,
+  sideMenuLabel: v,
+  expanded: m,
+  defaultExpanded: C = !1,
+  onExpandedChange: i
+}) => {
+  const {
+    value: a,
+    setValue: t,
+    isControlled: r
+  } = N({
+    component: "IressSideNav",
+    defaultValue: C,
+    onChange: i ? (e) => i(e ?? !1) : void 0,
+    propName: "expanded",
+    value: m
+  }), [s, p] = A(o);
+  I(() => {
+    p(o);
+  }, [o]);
+  const d = s ? n.find((e) => e.key === s) : void 0, f = l ?? d?.children ?? [], x = v ?? d?.label, E = f.length > 0, S = u(
+    (e) => {
+      if (p(e), c?.(e), !r) {
+        const b = n.find((g) => g.key === e);
+        (l ?? b?.children ?? []).length > 0 && t(!0);
+      }
+    },
+    [
+      n,
+      l,
+      r,
+      t,
+      c
+    ]
+  ), h = u(() => {
+    t(!a);
+  }, [a, t]);
+  return {
+    isExpanded: !!a,
+    toggleExpanded: h,
+    resolvedActiveItemKey: s,
+    setActiveItemKey: S,
+    activeItem: d,
+    panelContent: f,
+    panelLabel: x,
+    hasPanelContent: E
+  };
+};
+export {
+  y as useSideNavState
+};

package/dist/patterns/SideNav/index.d.ts

@@ -0,0 +1,2 @@
+export * from './SideNav';
+export * from './SideNav.styles';

package/dist/patterns/SideNav/index.js

@@ -0,0 +1,6 @@
+import { IressSideNav as o } from "./SideNav.js";
+import { sideNav as a } from "./SideNav.styles.js";
+export {
+  o as IressSideNav,
+  a as sideNav
+};

package/dist/patterns/SideNav/meta/Thumbnail.d.ts

@@ -0,0 +1,2 @@
+declare const Thumbnail: () => import("react/jsx-runtime").JSX.Element;
+export default Thumbnail;

package/dist/patterns/SideNav/meta/index.d.ts

@@ -0,0 +1,7 @@
+declare const _default: {
+    heading: string;
+    href: string;
+    tags: string[];
+    Thumbnail: import('react').LazyExoticComponent<() => import("react/jsx-runtime").JSX.Element>;
+};
+export default _default;