@lumx/react 4.19.1-next.0 → 4.20.0-next.0

package/index.d.ts

@@ -5271,14 +5271,17 @@ interface TabListProps$1 extends HasClassName, HasTheme {
     layout?: TabListLayout;
     /** Position of the tabs in the list (requires 'clustered' layout). */
     position?: Alignment;
+    /** `role` applied to the inner `__links` container */
+    role?: 'navigation' | 'tablist';
     /** ref to the wrapper element */
     ref?: CommonRef;
 }
+type TabListPropsToOverride = 'role';
 
 /**
  * Defines the props of the component.
  */
-interface TabListProps extends GenericProps$1, ReactToJSX<TabListProps$1> {
+interface TabListProps extends GenericProps$1, ReactToJSX<TabListProps$1, TabListPropsToOverride> {
 }
 
 /**
@@ -5286,6 +5289,8 @@ interface TabListProps extends GenericProps$1, ReactToJSX<TabListProps$1> {
  *
  * Implements WAI-ARIA `tablist` role {@see https://www.w3.org/TR/wai-aria-practices-1.1/examples/tabs/tabs-1/tabs.html#rps_label}
  *
+ * Renders a `role="navigation"` landmark instead when used outside a `TabProvider` (nav-link mode).
+ *
  * @param  props Component props.
  * @param  ref   Component ref.
  * @return React element.
@@ -5293,9 +5298,14 @@ interface TabListProps extends GenericProps$1, ReactToJSX<TabListProps$1> {
 declare const TabList: Comp<TabListProps, HTMLDivElement>;
 
 /**
- * Defines the props of the component.
+ * Element a `Tab` can render as: `'button'` (default, classic tab), `'a'` (nav-link, `href`
+ * required via {@link HasRequiredLinkHref}), or any `ElementType` (nav-link, e.g. a router `Link`).
  */
-interface TabProps$1 extends HasClassName {
+type TabElement = 'a' | 'button' | ElementType;
+/**
+ * Defines the props of the component (independent of the `as` element).
+ */
+interface CommonTabProps extends HasClassName {
     /** Children are not supported. */
     children?: never;
     /** Icon (SVG path). */
@@ -5306,6 +5316,11 @@ interface TabProps$1 extends HasClassName {
     id?: string;
     /** Whether the tab is active or not. */
     isActive?: boolean;
+    /**
+     * WAI-ARIA `tab` role, resolved by the framework wrapper from `TabProvider` presence:
+     * `'tab'` inside a provider (classic tab mode), `undefined` outside (nav-link mode).
+     */
+    role?: 'tab';
     /** Whether the component is disabled or not. */
     isDisabled?: boolean;
     /** Label content. */
@@ -5326,23 +5341,38 @@ interface TabProps$1 extends HasClassName {
     tabIndexProp?: string;
     /** Name of the prop used to attach the keypress event (framework-dependent). */
     keyPressProp?: string;
-    /** ID applied to the tab button element (for aria-labelledby on the panel). */
-    tabId?: string;
     /** ID of the associated tab panel (for aria-controls). */
     tabPanelId?: string;
     /** Icon component injected by the framework wrapper. */
     Icon: any;
     /** Text component injected by the framework wrapper. */
     Text: any;
-    /** Forward ref to the underlying button element. */
+    /** Forward ref to the underlying element. */
     ref?: CommonRef;
 }
-type TabPropsToOverride = 'isAnyDisabled' | 'shouldActivateOnFocus' | 'changeToTab' | 'tabIndex' | 'tabIndexProp' | 'keyPressProp' | 'tabId' | 'tabPanelId' | 'Icon' | 'Text';
+/**
+ * Polymorphic `as` surface for `Tab`. Not `HasPolymorphicAs<E>`: core JSX is type-checked under
+ * both the React and Vue namespaces, so spreading React DOM prop types would break the Vue
+ * cross-check. `href` is required at compile time when `as === 'a'` (via {@link HasRequiredLinkHref}).
+ */
+type TabAsProps<E extends TabElement = 'button'> = {
+    as?: E;
+} & (E extends 'a' ? HasRequiredLinkHref<'a'> : unknown);
+/**
+ * Props of the `Tab` component. Polymorphic on `as` (element selection only): `as` picks the
+ * rendered element, while **mode is driven by `TabProvider` presence** (via the wrapper-resolved
+ * `role`), not by `as`. The `href` conditional's false branch is `unknown` (not a record) to avoid
+ * widening `keyof TabProps`.
+ */
+type TabProps$1<E extends TabElement = 'button'> = CommonTabProps & TabAsProps<E>;
+type TabPropsToOverride = 'as' | 'role' | 'isAnyDisabled' | 'shouldActivateOnFocus' | 'changeToTab' | 'tabIndex' | 'tabIndexProp' | 'keyPressProp' | 'tabPanelId' | 'Icon' | 'Text';
 
 /**
- * Defines the props of the component.
+ * Defines the props of the component. Polymorphic on `as` (element selection only): `as` picks the
+ * rendered element (`as="a"` with required `href`, or `as={RouterLink}`), while the mode
+ * (`role="tab"` vs nav-link) is driven by `TabProvider` presence. The forwarded ref type follows `as`.
  */
-interface TabProps extends GenericProps$1, ReactToJSX<TabProps$1, TabPropsToOverride> {
+type TabProps<E extends ElementType$1 = 'button'> = GenericProps$1 & HasPolymorphicAs$1<E> & HasRequiredLinkHref$1<E> & ReactToJSX<TabProps$1, TabPropsToOverride> & {
     /** Children are not supported. */
     children?: never;
     /** Icon (SVG path). */
@@ -5357,17 +5387,44 @@ interface TabProps extends GenericProps$1, ReactToJSX<TabProps$1, TabPropsToOver
     isDisabled?: boolean;
     /** Label content. */
     label: string | ReactNode;
-}
+};
 /**
  * Tab component.
  *
  * Implements WAI-ARIA `tab` role {@see https://www.w3.org/TR/wai-aria-practices-1.1/examples/tabs/tabs-1/tabs.html#rps_label}
+ * when rendered inside a `TabProvider`.
+ *
+ * Outside a `TabProvider` (nav-link mode): plain link, no `role="tab"`/roving tabindex/`changeToTab`
+ * dispatch — only `aria-current` marks the active item.
  *
  * @param  props Component props.
- * @param  ref   Component ref.
+ * @param  ref   Component ref (type follows `as`).
  * @return React element.
  */
-declare const Tab: Comp<TabProps, HTMLButtonElement>;
+declare const Tab: (<E extends ElementType$1 = "button">(props: GenericProps$1 & React$1.PropsWithoutRef<React$1.ComponentProps<E>> & {
+    as?: E | undefined;
+} & HasRequiredLinkHref$1<E> & ReactToJSX<TabProps$1, TabPropsToOverride> & {
+    /** Children are not supported. */
+    children?: never;
+    /** Icon (SVG path). */
+    icon?: IconProps["icon"];
+    /** Icon component properties. */
+    iconProps?: Omit<IconProps, "icon">;
+    /** Native id property. */
+    id?: string;
+    /** Whether the tab is active or not. */
+    isActive?: boolean;
+    /** Whether the component is disabled or not. */
+    isDisabled?: boolean;
+    /** Label content. */
+    label: string | ReactNode;
+} & React$1.ComponentProps<E> & {
+    ref?: ComponentRef<E> | undefined;
+}) => React.JSX.Element) & {
+    displayName: string;
+    className: string;
+    defaultProps: Partial<TabProps$1<"button">>;
+};
 
 /**
  * Defines the props of the component.

package/index.js

@@ -20935,10 +20935,12 @@ const TabList$1 = props => {
     className,
     layout = DEFAULT_PROPS$7.layout,
     position = DEFAULT_PROPS$7.position,
+    role = 'tablist',
     theme,
     ref,
     ...forwardedProps
   } = props;
+  const LinkWrapper = role === 'navigation' ? 'nav' : 'div';
   return /*#__PURE__*/jsx("div", {
     ref: ref,
     ...forwardedProps,
@@ -20947,9 +20949,9 @@ const TabList$1 = props => {
       [`position-${position}`]: Boolean(position),
       [`theme-${theme}`]: Boolean(theme)
     })),
-    children: /*#__PURE__*/jsx("div", {
+    children: /*#__PURE__*/jsx(LinkWrapper, {
       className: element$4('links'),
-      role: "tablist",
+      role: role,
       "aria-label": ariaLabel,
       children: children
     })
@@ -20961,6 +20963,8 @@ const TabList$1 = props => {
  *
  * Implements WAI-ARIA `tablist` role {@see https://www.w3.org/TR/wai-aria-practices-1.1/examples/tabs/tabs-1/tabs.html#rps_label}
  *
+ * Renders a `role="navigation"` landmark instead when used outside a `TabProvider` (nav-link mode).
+ *
  * @param  props Component props.
  * @param  ref   Component ref.
  * @return React element.
@@ -20972,14 +20976,19 @@ const TabList = forwardRef((props, ref) => {
     ...forwardedProps
   } = props;
   const tabListRef = React__default.useRef(null);
+  const role = useTabProviderContextState() === undefined ? 'navigation' : 'tablist';
+
+  // Classic roving tabindex (role="tab"). Disabled in nav-link mode: nav links keep their
+  // native per-link Tab stops, so this path is never engaged there.
   useRovingTabIndexContainer({
-    containerRef: tabListRef,
+    containerRef: role === 'navigation' ? null : tabListRef,
     itemSelector: '[role="tab"]'
   });
   return TabList$1({
+    ...forwardedProps,
     theme,
-    ref: mergeRefs(ref, tabListRef),
-    ...forwardedProps
+    role,
+    ref: mergeRefs(ref, tabListRef)
   });
 });
 TabList.displayName = COMPONENT_NAME$6;
@@ -21005,9 +21014,11 @@ const {
 } = bem(CLASSNAME$6);
 
 /**
- * Tab component.
- *
- * Implements WAI-ARIA `tab` role {@see https://www.w3.org/TR/wai-aria-practices-1.1/examples/tabs/tabs-1/tabs.html#rps_label}
+ * Tab component. Two modes keyed on `TabProvider` presence (via the wrapper-resolved `role`):
+ * tab mode (`role === 'tab'`, inside a provider) implements the WAI-ARIA `tab` role
+ * {@see https://www.w3.org/TR/wai-aria-practices-1.1/examples/tabs/tabs-1/tabs.html#rps_label};
+ * nav-link mode (no provider) renders plain link semantics (`aria-current`, no tab role/aria).
+ * `as` only selects the rendered element and applies in both modes.
  *
  * @param  props Component props.
  * @param  ref   Component ref.
@@ -21015,6 +21026,7 @@ const {
  */
 const Tab$1 = props => {
   const {
+    as = 'button',
     className,
     icon,
     iconProps = {},
@@ -21022,6 +21034,7 @@ const Tab$1 = props => {
     isDisabled,
     id,
     isActive,
+    role,
     label,
     handleFocus,
     handleKeyPress,
@@ -21031,107 +21044,145 @@ const Tab$1 = props => {
     changeToTab,
     tabPanelId,
     shouldActivateOnFocus,
-    tabId,
     Icon,
     Text,
     ref,
     ...forwardedProps
   } = props;
-  const changeToCurrentTab = () => {
-    if (isAnyDisabled) {
-      return;
-    }
-    changeToTab?.();
-  };
-  const onFocus = event => {
-    handleFocus?.(event);
-    if (shouldActivateOnFocus) {
+  let rawClickableProps;
+  if (role === 'tab') {
+    // Mode: WAI-ARIA `tab` role (inside a TabProvider)
+    const changeToCurrentTab = () => {
+      if (isAnyDisabled) {
+        return;
+      }
+      changeToTab?.();
+    };
+    const onFocus = event => {
+      handleFocus?.(event);
+      if (shouldActivateOnFocus) {
+        changeToCurrentTab();
+      }
+    };
+    const onKeyPress = event => {
+      handleKeyPress?.(event);
+      if (event.key !== 'Enter' || isAnyDisabled) {
+        return;
+      }
       changeToCurrentTab();
-    }
-  };
-  const onKeyPress = event => {
-    handleKeyPress?.(event);
-    if (event.key !== 'Enter' || isAnyDisabled) {
-      return;
-    }
-    changeToCurrentTab();
-  };
-  return /*#__PURE__*/jsxs("button", {
-    ref: ref,
-    ...forwardedProps,
-    type: "button",
-    id: tabId,
+    };
+    rawClickableProps = {
+      ...forwardedProps,
+      'aria-disabled': isAnyDisabled ? 'true' : 'false',
+      handleClick: changeToCurrentTab,
+      onFocus,
+      role: 'tab',
+      'aria-selected': isActive,
+      'aria-controls': tabPanelId,
+      [keyPressProp]: onKeyPress,
+      [tabIndexProp]: isActive ? 0 : tabIndex
+    };
+  } else {
+    // Mode: nav link
+    const {
+      onClick,
+      ...rest
+    } = forwardedProps;
+    rawClickableProps = {
+      ...rest,
+      isDisabled,
+      handleClick: onClick,
+      'aria-current': isActive ? 'page' : undefined
+    };
+  }
+  return RawClickable({
+    ...rawClickableProps,
+    as,
+    id,
     className: classnames(className, block$6({
       'is-active': isActive,
       'is-disabled': isAnyDisabled
     })),
-    onClick: changeToCurrentTab,
-    [keyPressProp]: onKeyPress,
-    onFocus: onFocus,
-    role: "tab",
-    [tabIndexProp]: isActive ? 0 : tabIndex,
-    "aria-disabled": isAnyDisabled,
-    "aria-selected": isActive,
-    "aria-controls": tabPanelId,
-    children: [icon && /*#__PURE__*/jsx(Icon, {
-      icon: icon,
-      size: Size.xs,
-      ...iconProps
-    }), label && /*#__PURE__*/jsx(Text, {
-      as: "span",
-      truncate: true,
-      children: label
-    })]
+    ref: ref,
+    children: /*#__PURE__*/jsxs(Fragment, {
+      children: [icon && /*#__PURE__*/jsx(Icon, {
+        icon: icon,
+        size: Size.xs,
+        ...iconProps
+      }), label && /*#__PURE__*/jsx(Text, {
+        as: "span",
+        truncate: true,
+        children: label
+      })]
+    })
   });
 };
 
 /**
- * Defines the props of the component.
+ * Defines the props of the component. Polymorphic on `as` (element selection only): `as` picks the
+ * rendered element (`as="a"` with required `href`, or `as={RouterLink}`), while the mode
+ * (`role="tab"` vs nav-link) is driven by `TabProvider` presence. The forwarded ref type follows `as`.
  */
 
 /**
  * Tab component.
  *
  * Implements WAI-ARIA `tab` role {@see https://www.w3.org/TR/wai-aria-practices-1.1/examples/tabs/tabs-1/tabs.html#rps_label}
+ * when rendered inside a `TabProvider`.
+ *
+ * Outside a `TabProvider` (nav-link mode): plain link, no `role="tab"`/roving tabindex/`changeToTab`
+ * dispatch — only `aria-current` marks the active item.
  *
  * @param  props Component props.
- * @param  ref   Component ref.
+ * @param  ref   Component ref (type follows `as`).
  * @return React element.
  */
-const Tab = forwardRef((props, ref) => {
+const Tab = Object.assign(forwardRefPolymorphic((props, ref) => {
   const {
     isAnyDisabled,
     otherProps
   } = useDisableStateProps(props);
   const {
+    as = 'button',
     isActive: propIsActive,
     id,
     onFocus,
     onKeyPress,
     ...forwardedProps
   } = otherProps;
+
+  // Register into the provider (if any) so it can track this tab's index / active state.
   const tabState = useTabProviderContext('tab', id);
+  // In a provider => tab mode (role="tab"); outside => nav-link mode. Mirrors TabList's role.
+  const inProvider = tabState !== undefined;
   const {
     isLazy: _isLazy,
+    tabId,
     ...state
   } = tabState ?? {};
+  // Without a provider there's no active index, so this collapses to the caller-provided value.
   const isActive = propIsActive || state?.isActive;
   return Tab$1({
-    id,
+    ...forwardedProps,
     ...state,
+    as,
+    role: inProvider ? 'tab' : undefined,
     Icon,
     Text,
     ref,
+    // Falls back to the caller-provided `id` when there's no TabProvider to generate one.
+    id: tabId || id,
     isActive,
     isAnyDisabled,
+    isDisabled: isAnyDisabled,
     handleFocus: onFocus,
-    handleKeyPress: onKeyPress,
-    ...forwardedProps
+    handleKeyPress: onKeyPress
   });
+}), {
+  displayName: COMPONENT_NAME$5,
+  className: CLASSNAME$6,
+  defaultProps: DEFAULT_PROPS$6
 });
-Tab.displayName = COMPONENT_NAME$5;
-Tab.className = CLASSNAME$6;
-Tab.defaultProps = DEFAULT_PROPS$6;
 
 /**
  * Component display name.