@q1travel/design-system 0.5.1 → 0.6.1

package/contracts/button-api-compatibility.md

@@ -20,7 +20,13 @@ New recommended code examples and product migrations use only the canonical API.
 
 When a canonical prop and its deprecated alias are both defined, the canonical prop wins. Resolution uses nullish precedence, so `svgOnly={false}` still overrides `iconOnly={true}`, and a defined `aria-label` still overrides `ariaLabel`.
 
-IconButton requires either `aria-label` or the deprecated `ariaLabel` at the TypeScript boundary. Its development warning evaluates the resolved accessible name.
+IconButton requires either `aria-label` or the deprecated `ariaLabel` at the TypeScript boundary. Its built-package runtime warning evaluates the resolved accessible name so JavaScript consumers retain the same guard after package build.
+
+## Native Button Props
+
+Button and IconButton accept native button props, ARIA attributes, `data-*` attributes, and DOM event handlers. `data-*` values accept React-renderable scalar metadata (`string`, `number`, `boolean`, `null`, or `undefined`); `null` and `undefined` omit the attribute. They forward those props to the real `<button>` instead of a wrapper so menu semantics, roving focus, hover, and pointer-down behavior remain attached to the interactive element.
+
+Package-owned semantics are applied after native props. `type`, `className`, `disabled`, loading `aria-disabled`/`tabIndex`, the resolved accessible name, `ref`, and the loading click guard therefore keep their documented behavior. Outside loading, a consumer-provided `tabIndex` or `aria-disabled` remains intact. The canonical native `aria-keyshortcuts` value wins over the compatibility `ariaKeyshortcuts` field by nullish precedence.
 
 ## Component-Owned Semantics
 
@@ -43,6 +49,9 @@ The scan covers the current local checkouts named below; it is not evidence abou
 
 - `npm run check` verifies the documentation build, source contracts, and real-browser behavior.
 - `npm run build:pkg` builds the package and verifies emitted declarations, consumer type compatibility, and package runtime behavior.
+- The package API gate renders the built package, not source modules, so it proves native-prop passthrough and the JavaScript accessible-name warning survive publication build transforms.
+- The clean-tarball consumer gate installs the generated tarball in an isolated consumer, imports Button and IconButton from that installed package, and executes loading/native-prop and JavaScript accessible-name contracts against the installed runtime.
+- The browser menu-ARIA passthrough proof uses a hidden, non-navigation fixture rendered by the real components. Public specimens must not claim popup semantics without implementing the corresponding interaction.
 - Both gates are required for this migration. Neither gate publishes a package.
 
 ## Removal Conditions
@@ -61,3 +70,4 @@ Until then, the aliases remain tested public compatibility contracts.
 - This contract does not migrate `q1travel-web`.
 - This contract does not choose a package version, publish a package, or remove an alias.
 - This contract does not change Button size, loading, variant, route, or styling contracts beyond the decorative slot boundary described above.
+- This contract does not move button semantics or event handlers to a wrapper.

package/dist-pkg/design-system.d.ts

@@ -1,4 +1,6 @@
 import { AnchorHTMLAttributes } from 'react';
+import { ButtonHTMLAttributes } from 'react';
+import { ComponentPropsWithoutRef } from 'react';
 import { FocusEventHandler } from 'react';
 import { HTMLAttributes } from 'react';
 import { InputHTMLAttributes } from 'react';
@@ -239,11 +241,8 @@ export declare type ButtonLinkProps = Omit<ButtonBaseProps, 'type'> & {
     ref?: Ref<HTMLAnchorElement>;
 };
 
-declare type ButtonProps = ButtonBaseProps & {
-    onClick?: MouseEventHandler<HTMLButtonElement>;
-    onFocus?: FocusEventHandler<HTMLButtonElement>;
-    onBlur?: FocusEventHandler<HTMLButtonElement>;
-    onKeyDown?: KeyboardEventHandler<HTMLButtonElement>;
+declare type ButtonProps = ButtonBaseProps & Omit<ComponentPropsWithoutRef<'button'>, keyof ButtonBaseProps> & {
+    [dataAttribute: `data-${string}`]: string | number | boolean | null | undefined;
     /** 供 focus 管理、测量、浮层定位等场景使用。 */
     ref?: Ref<HTMLButtonElement>;
 };
@@ -521,6 +520,54 @@ export declare type ContextMenuEntry = {
     type: 'separator';
 };
 
+export declare function ContextSwitcher({ currentContext, groups, open, defaultOpen, onOpenChange, onSelect, pendingId, errorMessage, footerActions, onFooterAction, label, }: ContextSwitcherProps): JSX.Element;
+
+export declare type ContextSwitcherAction = {
+    id: string;
+    label: ReactNode;
+    textValue: string;
+    icon?: ReactNode;
+    disabled?: boolean;
+};
+
+export declare type ContextSwitcherCurrent = {
+    label: ReactNode;
+    description?: ReactNode;
+    avatar?: ReactNode;
+    textValue: string;
+};
+
+export declare type ContextSwitcherGroup = {
+    id: string;
+    label: ReactNode;
+    textValue: string;
+    selectedId?: string;
+    items: ContextSwitcherItem[];
+};
+
+export declare type ContextSwitcherItem = {
+    id: string;
+    label: ReactNode;
+    textValue: string;
+    description?: ReactNode;
+    avatar?: ReactNode;
+    disabled?: boolean;
+};
+
+export declare type ContextSwitcherProps = {
+    currentContext: ContextSwitcherCurrent;
+    groups: ContextSwitcherGroup[];
+    open?: boolean;
+    defaultOpen?: boolean;
+    onOpenChange?: (open: boolean) => void;
+    onSelect: (item: ContextSwitcherItem) => void;
+    pendingId?: string;
+    errorMessage?: ReactNode;
+    footerActions?: ContextSwitcherAction[];
+    onFooterAction?: (action: ContextSwitcherAction) => void;
+    label?: string;
+};
+
 export declare function ControlOption({ id, label, description, error, indeterminate, ref, type, ...rest }: ControlOptionOwnProps & (FieldShellProps | FieldBareProps) & CheckboxOnlyProps & {
     type: 'checkbox' | 'radio';
 } & NativeInputProps): JSX.Element;
@@ -707,7 +754,7 @@ declare type IconButtonAccessibleName = {
     ariaLabel: string;
 };
 
-export declare type IconButtonProps = IconButtonAccessibleName & {
+declare type IconButtonBaseProps = {
     variant?: ButtonVariant;
     size?: ButtonSize;
     circle?: boolean;
@@ -717,11 +764,10 @@ export declare type IconButtonProps = IconButtonAccessibleName & {
     type?: 'button' | 'submit' | 'reset';
     className?: string;
     children?: ReactNode;
-    onClick?: MouseEventHandler<HTMLButtonElement>;
-    'aria-describedby'?: string;
-    onFocus?: FocusEventHandler<HTMLButtonElement>;
-    onBlur?: FocusEventHandler<HTMLButtonElement>;
-    onKeyDown?: KeyboardEventHandler<HTMLButtonElement>;
+};
+
+export declare type IconButtonProps = IconButtonAccessibleName & IconButtonBaseProps & Omit<ComponentPropsWithoutRef<'button'>, keyof IconButtonBaseProps | 'aria-label'> & {
+    [dataAttribute: `data-${string}`]: string | number | boolean | null | undefined;
     ref?: Ref<HTMLButtonElement>;
 };
 
@@ -840,6 +886,74 @@ declare type NativeInputProps = Omit<InputHTMLAttributes<HTMLInputElement>, 'id'
 
 declare type NativeInputProps_2 = Omit<InputHTMLAttributes<HTMLInputElement>, 'type'>;
 
+export declare function Navigation({ className, ...props }: NavigationProps): JSX.Element;
+
+export declare function NavigationGroup({ label, icon, expanded, defaultExpanded, onExpandedChange, children, }: NavigationGroupProps): JSX.Element;
+
+export declare type NavigationGroupProps = {
+    label: ReactNode;
+    icon?: ReactNode;
+    expanded?: boolean;
+    defaultExpanded?: boolean;
+    onExpandedChange?: (expanded: boolean) => void;
+    children: ReactNode;
+};
+
+export declare function NavigationItem(props: NavigationItemProps): JSX.Element;
+
+export declare type NavigationItemAsButton = NavigationItemOwnProps & {
+    href?: undefined;
+} & Omit<ButtonHTMLAttributes<HTMLButtonElement>, keyof NavigationItemOwnProps>;
+
+export declare type NavigationItemAsLink = NavigationItemOwnProps & {
+    href: string;
+} & Omit<AnchorHTMLAttributes<HTMLAnchorElement>, keyof NavigationItemOwnProps | 'href'>;
+
+declare type NavigationItemOwnProps = {
+    active?: boolean;
+    disabled?: boolean;
+    icon?: ReactNode;
+    badge?: ReactNode;
+    description?: ReactNode;
+    action?: ReactNode;
+    children: ReactNode;
+    className?: string;
+};
+
+export declare type NavigationItemProps = NavigationItemAsLink | NavigationItemAsButton;
+
+export declare type NavigationProps = HTMLAttributes<HTMLElement> & {
+    'aria-label': string;
+};
+
+export declare function NavigationSection({ label, action, children, className, ...props }: NavigationSectionProps): JSX.Element;
+
+declare type NavigationSectionLabel = Exclude<ReactNode, boolean | null | undefined>;
+
+declare type NavigationSectionNativeProps = Omit<HTMLAttributes<HTMLElement>, keyof NavigationSectionOwnProps>;
+
+declare type NavigationSectionOwnProps = {
+    label?: ReactNode;
+    action?: ReactNode;
+    children: ReactNode;
+    className?: string;
+};
+
+export declare type NavigationSectionProps = NavigationSectionWithLabel | NavigationSectionWithAccessibleName;
+
+declare type NavigationSectionWithAccessibleName = NavigationSectionNativeProps & Omit<NavigationSectionOwnProps, 'action'> & {
+    label?: undefined;
+    action?: never;
+} & ({
+    'aria-label': string;
+} | {
+    'aria-labelledby': string;
+});
+
+declare type NavigationSectionWithLabel = NavigationSectionNativeProps & Omit<NavigationSectionOwnProps, 'label'> & {
+    label: NavigationSectionLabel;
+};
+
 export declare function Note({ tone, size, filled, disabled, label, action, children, }: {
     tone?: NoteTone;
     size?: NoteSize;
@@ -1015,6 +1129,26 @@ export declare function ShowMore({ items, initial, noBorder, initialExpanded, }:
     initialExpanded?: boolean;
 }): JSX.Element;
 
+export declare const Sidebar: typeof SidebarRoot & {
+    Header: typeof SidebarHeader;
+    Content: typeof SidebarContent;
+    Footer: typeof SidebarFooter;
+};
+
+declare function SidebarContent({ className, ...props }: SidebarSlotProps): JSX.Element;
+
+declare function SidebarFooter({ className, ...props }: SidebarSlotProps): JSX.Element;
+
+declare function SidebarHeader({ className, ...props }: SidebarSlotProps): JSX.Element;
+
+export declare type SidebarProps = HTMLAttributes<HTMLElement> & {
+    'aria-label': string;
+};
+
+declare function SidebarRoot({ className, ...props }: SidebarProps): JSX.Element;
+
+export declare type SidebarSlotProps = HTMLAttributes<HTMLDivElement>;
+
 export declare function Skeleton({ shape, animated, show, className, children, }: {
     shape?: SkeletonShape;
     animated?: boolean;