@q1travel/design-system 0.6.0 → 0.7.0

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,5 +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';
@@ -240,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>;
 };
@@ -756,7 +754,7 @@ declare type IconButtonAccessibleName = {
     ariaLabel: string;
 };
 
-export declare type IconButtonProps = IconButtonAccessibleName & {
+declare type IconButtonBaseProps = {
     variant?: ButtonVariant;
     size?: ButtonSize;
     circle?: boolean;
@@ -766,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>;
 };
 
@@ -889,7 +886,7 @@ 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 Navigation({ className, orientation, ...props }: NavigationProps): JSX.Element;
 
 export declare function NavigationGroup({ label, icon, expanded, defaultExpanded, onExpandedChange, children, }: NavigationGroupProps): JSX.Element;
 
@@ -927,6 +924,7 @@ export declare type NavigationItemProps = NavigationItemAsLink | NavigationItemA
 
 export declare type NavigationProps = HTMLAttributes<HTMLElement> & {
     'aria-label': string;
+    orientation?: 'vertical' | 'horizontal';
 };
 
 export declare function NavigationSection({ label, action, children, className, ...props }: NavigationSectionProps): JSX.Element;
@@ -1081,6 +1079,44 @@ export declare function ScrollerWithButtons({ axis, contentName, label, children
     children: ReactNode;
 }): JSX.Element;
 
+export declare function SearchDialog({ open, onOpenChange, query, onQueryChange, sections, onSelect, renderTrigger, label, placeholder, emptyTitle, clearQueryLabel, }: SearchDialogProps): JSX.Element;
+
+export declare type SearchDialogItem = {
+    id: string;
+    label: string;
+    description?: string;
+    disabled?: boolean;
+};
+
+export declare type SearchDialogProps = {
+    open: boolean;
+    onOpenChange: (open: boolean) => void;
+    query: string;
+    onQueryChange: (query: string) => void;
+    sections: SearchDialogSection[];
+    onSelect: (item: SearchDialogItem) => void;
+    renderTrigger: (props: SearchDialogTriggerProps) => ReactNode;
+    label: string;
+    placeholder?: string;
+    emptyTitle?: string;
+    clearQueryLabel?: string;
+};
+
+export declare type SearchDialogSection = {
+    id: string;
+    heading?: string;
+    items: SearchDialogItem[];
+};
+
+export declare type SearchDialogTriggerProps = {
+    ref: (node: HTMLButtonElement | null) => void;
+    type: 'button';
+    onClick: () => void;
+    'aria-haspopup': 'dialog';
+    'aria-expanded': boolean;
+    'aria-controls': string;
+};
+
 export declare function SearchInput({ id, ariaLabel, placeholder, defaultValue, disabled, loading, kbdHint, icon, }: {
     id: string;
     ariaLabel: string;