@toteat-eng/ds-react 2026.8.25 → 2026.8.27

package/dist/components/Button/Button.d.ts

@@ -1,8 +1,43 @@
-import type { ButtonHTMLAttributes, ReactNode } from "react";
+import type { ComponentPropsWithoutRef, ElementType, ReactNode } from "react";
 export type ButtonVariant = "primary" | "secondary" | "ghost" | "outline";
 export type ButtonSize = "small" | "medium" | "large";
 export type ButtonIconPosition = "left" | "right";
-export interface ButtonProps extends ButtonHTMLAttributes<HTMLButtonElement> {
+/**
+ * The DS-owned half of the props — everything not inherited from the rendered element.
+ *
+ * **These names are RESERVED, and a collision fails SILENTLY. Read this before choosing an `as`
+ * target.** `ButtonProps` omits `keyof ButtonOwnProps` from the target's own props, and this
+ * component destructures each of them for its own use and never forwards them. So if the `as` target
+ * has a prop of its own called `size`, `variant`, `loading`, `icon`, `iconPosition`, `fullWidth`,
+ * `children` or `as`, that prop is stripped from the exposed type AND never reaches the target at
+ * runtime — with **no compile error**. Verified in review: an `as` target requiring `size: number`
+ * type-checks clean while receiving no `size` at all.
+ *
+ * This is inherent to the polymorphic-`as` pattern rather than a bug in this file, and it is harmless
+ * for the intended targets (`"a"`, a router `Link` — none of which own these names). But it is a
+ * foot-gun in a primitive three apps consume, so: if you need a target that owns one of these names,
+ * wrap it in a small adapter component that renames the prop, rather than reaching for `as` directly.
+ */
+interface ButtonOwnProps<C extends ElementType> {
+    /**
+     * Render as a different element or component instead of `<button>`.
+     *
+     * Exists for ONE reason: an action that NAVIGATES must be an anchor. A `<button>` that changes
+     * the route is a WCAG anti-pattern — it drops middle-click, open-in-new-tab, copy-link and the
+     * context menu, none of which a click handler can reinstate. Before this prop, a consumer wanting
+     * a link that looks like a button had to hand-copy this file's CSS, because the classes are
+     * CSS-module-hashed and unreachable from outside. That duplication then drifts on every DS release.
+     *
+     * This also honours rule 2 of the DS ("native element at the root — the most specific native
+     * element for the role") rather than working around it.
+     *
+     * @example
+     * // TanStack Router
+     * <Button as={Link} variant="ghost" to="/orders/$id" params={{ id }}>Ver orden</Button>
+     * // plain anchor
+     * <Button as="a" href="https://toteat.com">Sitio</Button>
+     */
+    as?: C;
     variant?: ButtonVariant;
     size?: ButtonSize;
     loading?: boolean;
@@ -10,5 +45,38 @@ export interface ButtonProps extends ButtonHTMLAttributes<HTMLButtonElement> {
     icon?: ReactNode;
     iconPosition?: ButtonIconPosition;
     children: ReactNode;
+    /**
+     * Promoted to a DS-owned prop (was inherited from `ButtonHTMLAttributes`).
+     *
+     * It has to live here, not on the target: `disabled` is not a valid anchor attribute, so once `as`
+     * exists an inherited `disabled` type-checks ONLY for the `<button>` root. That made the entire
+     * disabled-anchor path — `aria-disabled`, `tabIndex={-1}`, click suppression, all implemented and
+     * tested — unreachable from typed consumer code with a `TS2322`. Caught by writing the
+     * `AsAnchor` story; the browser tests missed it because test files sit outside
+     * `tsconfig.app.json`.
+     *
+     * Declaring it here means "disabled" is one DS concept whatever the root element, and each root
+     * expresses it natively: `disabled` on a `<button>`, `aria-disabled` + `tabIndex={-1}` elsewhere.
+     */
+    disabled?: boolean;
+    /**
+     * Declared here for the same reason as `disabled` above: this component destructures `type` and
+     * consumes it, so leaving it to be inherited from the rendered element's attribute surface made
+     * the public type disagree with the runtime. A target that owns a `type` prop would have
+     * type-checked and then silently never received it.
+     *
+     * Applies to the `<button>` root ONLY — it is the native form-submit guard, and `type` means
+     * something unrelated on an `<a>`. Passing it alongside `as` is accepted by the type but has no
+     * effect, which is the same trade the reserved-name caveat above describes. Raised in review on
+     * https://github.com/toteat/ds-react/pull/57.
+     */
+    type?: "button" | "submit" | "reset";
 }
-export declare function Button({ variant, size, loading, fullWidth, icon, iconPosition, disabled, children, className, type, ...props }: ButtonProps): import("react/jsx-runtime").JSX.Element;
+/**
+ * Props accept whatever the rendered element accepts, so `as={Link}` type-checks `to`/`params` and
+ * `as="a"` type-checks `href`. Defaults to `"button"`, so the pre-existing
+ * `ButtonProps` (no type argument) keeps meaning exactly what it meant before — this is additive.
+ */
+export type ButtonProps<C extends ElementType = "button"> = ButtonOwnProps<C> & Omit<ComponentPropsWithoutRef<C>, keyof ButtonOwnProps<C>>;
+export declare function Button<C extends ElementType = "button">({ as, variant, size, loading, fullWidth, icon, iconPosition, disabled, children, className, type, ...props }: ButtonProps<C>): import("react/jsx-runtime").JSX.Element;
+export {};

package/dist/components/Button/__stories__/Button.stories.d.ts

@@ -14,3 +14,11 @@ export declare const Small: Story;
 export declare const Large: Story;
 export declare const AllVariants: Story;
 export declare const AllSizes: Story;
+/**
+ * `as` renders a real anchor while keeping the DS styling, for an action that NAVIGATES. Visual
+ * states worth eyeballing here rather than in a browser test: the focus ring on an `<a>` (it is the
+ * DS ring, not the UA default, because the hashed class lands on the anchor), and how a disabled
+ * anchor looks — it is styled via `aria-disabled`, not the `:disabled` pseudo-class the `<button>`
+ * path uses, so the two disabled looks can drift apart without anything failing.
+ */
+export declare const AsAnchor: Story;