@q1travel/design-system 0.6.0 → 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,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>;
 };