@varialkit/button 0.1.1

package/docs.md

@@ -0,0 +1,173 @@
+# Button
+
+The Button component is a fundamental interactive element that triggers user actions. It supports several visual variants, size settings for spacing, and is designed to be highly versatile.
+
+## How to Use
+
+To use the Button, import it from the `@solara/button` package:
+
+```tsx
+import { Button } from "@solara/button";
+
+export function MyComponent() {
+  return <Button label="Click Me" />;
+}
+```
+
+## Best Practices
+
+-   **Clarity is Key**: The button's label should clearly describe the action it performs.
+-   **Consistent Usage**: Use variants consistently across your application to create a predictable user experience.
+-   **Limit Primary Buttons**: Use the `primary` variant for the most important action on a page. Avoid using multiple primary buttons in the same view.
+-   **Destructive Actions**: Use the `destructive` prop for actions that are difficult or impossible to undo, such as deleting data.
+
+## Props
+
+The Button component accepts the following props:
+
+| Prop          | Type                                                     | Default     | Description                                                                                                                         |
+| ------------- | -------------------------------------------------------- | ----------- | ----------------------------------------------------------------------------------------------------------------------------------- |
+| `label`       | `string`                                                 | _Required_* | The text content displayed inside the button. Required unless `iconOnly` is set.                                                   |
+| `variant`     | `"primary" | "default" | "tertiary" | "ghost" | "accent"` | `"default"`   | The visual style of the button. See [Variants](#variants) for more details.                                                         |
+| `size`        | `"small" | "medium" | "large"`               | `"medium"`    | Controls the button's internal padding and font size. See [Size](#size) for more details.       |
+| `radius`      | `"default" | "none" | "full"`                         | `"default"`   | Controls the button's border radius. `"default"` is a standard radius, `"none"` is a sharp corner, and `"full"` is a pill shape.      |
+| `destructive` | `boolean`                                                | `false`     | When `true`, applies a destructive style to the button, indicating a potentially dangerous action. See [Destructive](#destructive). |
+| `disabled`    | `boolean`                                                | `false`     | When `true`, the button is not interactive and has a disabled style.                                                                |
+| `iconLeft`    | `SolaraIconName | IconProps`                             | `undefined` | Renders a leading icon before the label.                                                                                            |
+| `iconRight`   | `SolaraIconName | IconProps`                             | `undefined` | Renders a trailing icon after the label.                                                                                            |
+| `iconOnly`    | `SolaraIconName | IconProps`                             | `undefined` | Renders an icon-only button. Provide `aria-label` (or `label`) for accessibility.                                                   |
+
+_Required unless `iconOnly` is set._
+
+The Button also accepts standard `button` props such as `className`, `style`, `type`, `onClick`, and `aria-*`.
+
+## Variants
+
+The `variant` prop allows you to control the button's visual appearance.
+
+### Primary
+
+Primary buttons are used for the main call-to-action on a page. They should be used sparingly to draw attention to the most important action.
+
+```tsx
+<Button label="Submit" variant="primary" />
+```
+
+### Default
+
+Default buttons are used for secondary actions. They have a visible border and are less prominent than primary buttons.
+
+```tsx
+<Button label="Cancel" variant="default" />
+```
+
+### Tertiary
+
+Tertiary buttons are used for less important actions. They have a transparent background and a border.
+
+```tsx
+<Button label="Learn More" variant="tertiary" />
+```
+
+### Ghost
+
+Ghost buttons are used for the least prominent actions. They have a transparent background and no border, making them suitable for clean, minimalist layouts.
+
+```tsx
+<Button label="Dismiss" variant="ghost" />
+```
+
+### Accent
+
+Accent buttons use the primary accent color to draw attention to important actions without being as strong as the primary button.
+
+```tsx
+<Button label="New Feature" variant="accent" />
+```
+
+## Size
+
+The `size` prop adjusts the button's padding and font size to fit different layout requirements.
+
+### Small
+
+Small buttons have reduced padding and a smaller font size, making them suitable for compact interfaces.
+
+```tsx
+<Button label="Compact" size="small" />
+```
+
+### Medium
+
+Medium buttons have standard padding and font size. This is the default setting.
+
+```tsx
+<Button label="Standard" size="medium" />
+```
+
+### Large
+
+Large buttons have increased padding and a larger font size, making them more prominent and easier to click on touch devices.
+
+```tsx
+<Button label="Spacious" size="large" />
+```
+
+## Radius And Density Behavior
+
+Button radius is token-driven and density-aware:
+
+- default radius uses the scaled radius token path (currently based on `--radius-2` with `--radius-multiplier`)
+- global density radius tuning in the docs controls updates button rounding in real time
+- `radius="none"` always forces square corners
+- `radius="full"` always forces pill corners
+
+This means radius density tuning affects default buttons, while explicit shape modes intentionally override it.
+
+## Destructive
+
+The `destructive` prop can be combined with any variant to indicate a potentially dangerous action, such as deleting data. When `true`, the button will be styled with a red background and white text.
+
+```tsx
+<Button label="Delete" destructive />
+```
+
+### Destructive Ghost
+
+The `destructive` prop can also be combined with the `ghost` variant for a less intrusive but still clear destructive action.
+
+```tsx
+<Button label="Delete" variant="ghost" destructive />
+```
+
+## Disabled State
+
+When a button is disabled, it cannot be clicked and has a visually distinct style. This is useful for preventing actions that are not currently available.
+
+```tsx
+<Button label="Saving..." disabled />
+```
+
+## Accessibility
+
+The `Button` component is designed with accessibility in mind.
+
+-   **Keyboard Navigation**: The button is focusable and can be activated using the `Enter` or `Space` key.
+-   **Screen Readers**: The button's label is read by screen readers. If you are using an icon-only button, be sure to provide an `aria-label` (or `label`) for screen reader users.
+
+## Icons
+
+The Button component can render icons on the left or right of the label, or as an icon-only control.
+Icons inherit the button text color by default, and button styles force icon strokes/fills to match `currentColor`.
+You can pass full `IconProps` to adjust size or stroke width; color is always aligned to the button text.
+
+```tsx
+<Button label="Back" iconLeft="arrow_chevron_left_16" />
+<Button label="Next" iconRight="arrow_chevron_right_16" />
+```
+
+### Icon-Only
+
+```tsx
+<Button iconOnly="arrow_line_up_16" aria-label="Upload" />
+```

package/examples.tsx

@@ -0,0 +1,264 @@
+import React from "react";
+import type { ReactElement } from "react";
+import { Button } from "./src/Button";
+import type { ButtonRadius, ButtonSize, ButtonVariant } from "./src/Button.types";
+import type { SolaraIconName } from "@solara/icons";
+import { iconNames } from "@solara/icons";
+
+type StoryControlOption = {
+  label: string;
+  value: string;
+};
+
+type StoryControl = {
+  name: string;
+  label?: string;
+  type: "select" | "text" | "boolean" | "number";
+  options?: Array<string | StoryControlOption>;
+  min?: number;
+  max?: number;
+  step?: number;
+};
+
+type StoryDefinition = {
+  title: string;
+  description?: string;
+  render: (props: Record<string, unknown>) => ReactElement;
+  controls?: StoryControl[];
+  initialProps?: Record<string, unknown>;
+  showProps?: boolean;
+  applyPropsToPreview?: boolean;
+  code?: string;
+};
+
+export const stories: Record<string, StoryDefinition> = {
+  playground: {
+    title: "Playground",
+    description: "Tweak the props to explore the Button API.",
+    render: (props) => {
+      const iconLeft = (props.iconLeft as SolaraIconName) || undefined;
+      const iconRight = (props.iconRight as SolaraIconName) || undefined;
+      const iconOnly = (props.iconOnly as SolaraIconName) || undefined;
+
+      return (
+        <Button
+          label={(props.label as string) ?? "Primary"}
+          variant={props.variant as ButtonVariant}
+          size={props.size as ButtonSize}
+          radius={props.radius as ButtonRadius}
+          destructive={props.destructive as boolean}
+          disabled={props.disabled as boolean}
+          iconLeft={iconLeft}
+          iconRight={iconRight}
+          iconOnly={iconOnly}
+        />
+      );
+    },
+    controls: [
+      { name: "label", label: "Label", type: "text" },
+      {
+        name: "variant",
+        label: "Variant",
+        type: "select",
+        options: ["default", "primary", "tertiary", "ghost", "accent"]
+      },
+      {
+        name: "size",
+        label: "Size",
+        type: "select",
+        options: ["small", "medium", "large"]
+      },
+      {
+        name: "radius",
+        label: "Radius",
+        type: "select",
+        options: ["default", "none", "full"]
+      },
+      {
+        name: "destructive",
+        label: "Destructive",
+        type: "boolean"
+      },
+      {
+        name: "disabled",
+        label: "Disabled",
+        type: "boolean"
+      },
+      {
+        name: "iconLeft",
+        label: "Icon Left",
+        type: "select",
+        options: ["", ...iconNames]
+      },
+      {
+        name: "iconRight",
+        label: "Icon Right",
+        type: "select",
+        options: ["", ...iconNames]
+      },
+      {
+        name: "iconOnly",
+        label: "Icon Only",
+        type: "select",
+        options: ["", ...iconNames]
+      }
+    ],
+    initialProps: {
+      label: "Primary",
+      variant: "primary",
+      size: "medium",
+      radius: "default",
+      destructive: false,
+      disabled: false,
+      iconLeft: "",
+      iconRight: "",
+      iconOnly: ""
+    }
+  },
+  overview: {
+    title: "Overview",
+    showProps: true,
+    render: () => (
+      <div style={{ display: "flex", gap: "1rem", alignItems: "center" }}>
+        <Button label="Primary" variant="primary" />
+        <Button label="Default" variant="default" />
+      </div>
+    ),
+    code: `import { Button } from "@solara/button";
+
+export function Example() {
+  return (
+    <div style={{ display: "flex", gap: "1rem", alignItems: "center" }}>
+      <Button label="Primary" variant="primary" />
+      <Button label="Default" variant="default" />
+    </div>
+  );
+}
+`
+  },
+  variants: {
+    title: "Variants",
+    showProps: false,
+    render: () => (
+      <div style={{ display: "flex", gap: "1rem", alignItems: "center" }}>
+        <Button label="Primary" variant="primary" />
+        <Button label="Default" variant="default" />
+        <Button label="Tertiary" variant="tertiary" />
+        <Button label="Ghost" variant="ghost" />
+      </div>
+    ),
+    code: `import { Button } from "@solara/button";
+
+export function Example() {
+  return (
+    <div style={{ display: "flex", gap: "1rem", alignItems: "center" }}>
+      <Button label="Primary" variant="primary" />
+      <Button label="Default" variant="default" />
+      <Button label="Tertiary" variant="tertiary" />
+      <Button label="Ghost" variant="ghost" />
+    </div>
+  );
+}
+`
+  },
+  icons: {
+    title: "Icons",
+    showProps: false,
+    render: () => (
+      <div style={{ display: "flex", gap: "1rem", alignItems: "center" }}>
+        <Button label="Back" iconLeft="arrow_chevron_left_16" />
+        <Button label="Next" iconRight="arrow_chevron_right_16" variant="primary" />
+        <Button label="Swap" iconLeft="arrow_swap_16" iconRight="arrow_swap_16" variant="tertiary" />
+      </div>
+    ),
+    code: `import { Button } from "@solara/button";
+
+export function Example() {
+  return (
+    <div style={{ display: "flex", gap: "1rem", alignItems: "center" }}>
+      <Button label="Back" iconLeft="arrow_chevron_left_16" />
+      <Button label="Next" iconRight="arrow_chevron_right_16" variant="primary" />
+      <Button label="Swap" iconLeft="arrow_swap_16" iconRight="arrow_swap_16" variant="tertiary" />
+    </div>
+  );
+}
+`
+  },
+  iconOnly: {
+    title: "Icon Only",
+    showProps: false,
+    render: () => (
+      <div style={{ display: "flex", gap: "1rem", alignItems: "center" }}>
+        <Button iconOnly="arrow_line_up_16" aria-label="Upload" />
+        <Button iconOnly="arrow_line_down_16" aria-label="Download" variant="primary" />
+        <Button iconOnly="arrow_line_rotate_right_16" aria-label="Refresh" variant="ghost" />
+      </div>
+    ),
+    code: `import { Button } from "@solara/button";
+
+export function Example() {
+  return (
+    <div style={{ display: "flex", gap: "1rem", alignItems: "center" }}>
+      <Button iconOnly="arrow_line_up_16" aria-label="Upload" />
+      <Button iconOnly="arrow_line_down_16" aria-label="Download" variant="primary" />
+      <Button iconOnly="arrow_line_rotate_right_16" aria-label="Refresh" variant="ghost" />
+    </div>
+  );
+}
+`
+  },
+  destructive: {
+    title: "Destructive",
+    showProps: false,
+    render: () => (
+      <div style={{ display: "flex", flexDirection: "column", gap: "1rem" }}>
+        <div style={{ display: "flex", gap: "1rem" }}>
+          <Button label="Delete" variant="primary" destructive />
+          <Button label="Delete" destructive />
+        </div>
+        <div style={{ display: "flex", gap: "1rem" }}>
+          <Button label="Delete" variant="tertiary" destructive />
+          <Button label="Delete" variant="ghost" destructive />
+        </div>
+      </div>
+    ),
+    code: `import { Button } from "@solara/button";
+
+export function Example() {
+  return (
+    <div style={{ display: "flex", flexDirection: "column", gap: "1rem" }}>
+      <div style={{ display: "flex", gap: "1rem" }}>
+        <Button label="Delete" variant="primary" destructive />
+        <Button label="Delete" destructive />
+      </div>
+      <div style={{ display: "flex", gap: "1rem" }}>
+        <Button label="Delete" variant="tertiary" destructive />
+        <Button label="Delete" variant="ghost" destructive />
+      </div>
+    </div>
+  );
+}
+`
+  },
+  disabled: {
+    title: "Disabled",
+    showProps: false,
+    render: () => (
+      <div style={{ display: "flex", gap: "1rem" }}>
+        <Button label="Disabled" disabled />
+        <Button label="Disabled" variant="primary" disabled />
+      </div>
+    ),
+    code: `import { Button } from "@solara/button";
+
+export function Example() {
+  return (
+    <div style={{ display: "flex", gap: "1rem" }}>
+      <Button label="Disabled" disabled />
+      <Button label="Disabled" variant="primary" disabled />
+    </div>
+  );
+}
+`
+  }
+};

package/package.json

@@ -0,0 +1,27 @@
+{
+  "name": "@varialkit/button",
+  "version": "0.1.1",
+  "type": "module",
+  "main": "src/index.ts",
+  "types": "src/index.ts",
+  "exports": {
+    ".": "./src/index.ts",
+    "./examples": "./examples/index.tsx"
+  },
+  "dependencies": {
+    "@varialkit/icons": "0.1.1"
+  },
+  "files": [
+    "src",
+    "docs.md",
+    "examples",
+    "examples.tsx"
+  ],
+  "peerDependencies": {
+    "react": "^19.0.0"
+  },
+  "devDependencies": {
+    "@types/react": "19.0.10",
+    "react": "19.0.0"
+  }
+}

package/src/Button.scss

@@ -0,0 +1,200 @@
+
+.sol-button {
+  border: 1px solid transparent;
+  // Use a slightly larger base radius so density radius tuning is visibly apparent on buttons.
+  --button-radius: var(--radius-2-scaled, calc(var(--radius-2) * var(--radius-multiplier, 1)));
+  border-radius: var(--button-radius);
+  cursor: pointer;
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  transition: background-color 0.2s ease, border-color 0.2s ease, color 0.2s ease, opacity 0.2s ease, box-shadow 0.2s ease, filter 0.2s ease;
+  --button-padding-y: var(--space-2);
+  --button-padding-x: var(--space-3);
+  --button-font-weight: var(--font-weight-body, 500);
+  --button-font-size: var(--font-size-body-scaled);
+  --button-line-height: var(--line-height-caption-scaled);
+  --button-text-decoration: var(--text-decoration-body, none);
+  --button-active-text-decoration: var(--text-decoration-body, none);
+  --button-icon-gap: var(--space-2);
+  padding: calc(var(--button-padding-y) * var(--spacing-multiplier))
+    calc(var(--button-padding-x) * var(--spacing-multiplier));
+  font-size: var(--button-font-size);
+  line-height: var(--button-line-height);
+  font-weight: var(--button-font-weight);
+  text-decoration: var(--button-text-decoration);
+  gap: calc(var(--button-icon-gap) * var(--spacing-multiplier));
+
+  &:focus-visible {
+    outline: none;
+    box-shadow: 0 0 0 3px var(--color-focus-halo);
+  }
+
+  &:disabled {
+    opacity: 0.5;
+    cursor: not-allowed;
+  }
+
+  &[data-radius="none"] {
+    border-radius: 0;
+  }
+
+  &[data-radius="full"] {
+    border-radius: 9999px;
+  }
+
+  &[data-size="small"] {
+    --button-padding-y: var(--space-1);
+    --button-padding-x: var(--space-2);
+    --button-font-weight: var(--font-weight-footnote, 500);
+    --button-font-size: var(--font-size-footnote-scaled);
+    --button-line-height: var(--line-height-footnote-scaled);
+    --button-text-decoration: var(--text-decoration-caption, none);
+    --button-active-text-decoration: var(--text-decoration-caption, none);
+  }
+
+  &[data-size="large"] {
+    --button-padding-y: var(--space-3);
+    --button-padding-x: var(--space-4);
+    --button-font-weight: var(--font-weight-subhead, 500);
+    --button-font-size: var(--font-size-body-scaled);
+    --button-line-height: var(--line-height-body-scaled);
+    --button-text-decoration: var(--text-decoration-subhead, none);
+    --button-active-text-decoration: var(--text-decoration-subhead, none);
+  }
+
+  &[data-icon-only="true"] {
+    --button-padding-x: var(--button-padding-y);
+    --button-icon-gap: 0;
+  }
+
+  &.primary {
+    background-color: var(--color-primary);
+    color: var(--color-on-primary);
+
+    &:not(:disabled):hover {
+      filter: brightness(0.9);
+    }
+
+    &:not(:disabled):active {
+      filter: brightness(0.8);
+      text-decoration: var(--button-active-text-decoration);
+    }
+
+    &[data-destructive="true"] {
+      background-color: var(--color-destructive);
+      color: var(--color-on-destructive);
+      border-color: transparent;
+    }
+  }
+
+  &.default {
+    background-color: var(--color-surface-300);
+    color: var(--color-on-surface);
+    border: 1px solid var(--color-surface-400);
+
+    &:not(:disabled):hover {
+      background-color: var(--color-surface-400);
+    }
+
+    &:not(:disabled):active {
+      background-color: var(--color-surface-500);
+      text-decoration: var(--button-active-text-decoration);
+    }
+
+    &[data-destructive="true"] {
+      background-color: var(--color-destructive);
+      color: var(--color-on-destructive);
+      border-color: transparent;
+    }
+  }
+
+  &.tertiary {
+    background-color: transparent;
+    color: var(--color-on-surface);
+    border: 1px solid var(--color-surface-400);
+
+    &:not(:disabled):hover {
+      background-color: var(--color-surface-200);
+    }
+
+    &:not(:disabled):active {
+      background-color: var(--color-surface-300);
+      text-decoration: var(--button-active-text-decoration);
+    }
+
+    &[data-destructive="true"] {
+      color: var(--color-destructive);
+      border-color: var(--color-destructive);
+      background-color: transparent;
+    }
+  }
+
+  &.ghost {
+    background-color: transparent;
+    color: var(--color-on-surface);
+
+    &:not(:disabled):hover {
+      background-color: var(--color-surface-200);
+    }
+
+    &:not(:disabled):active {
+      background-color: var(--color-surface-300);
+      text-decoration: var(--button-active-text-decoration);
+    }
+
+    &[data-destructive="true"] {
+      color: var(--color-destructive);
+      background-color: transparent;
+      border-color: transparent;
+
+      &:not(:disabled):hover {
+        background-color: var(--color-surface-200);
+      }
+    }
+  }
+
+  &.accent {
+    background-color: var(--color-accent-primary);
+    color: var(--color-text-inverse);
+
+    &:not(:disabled):hover {
+      filter: brightness(0.9);
+    }
+
+    &:not(:disabled):active {
+      filter: brightness(0.8);
+      text-decoration: var(--button-active-text-decoration);
+    }
+
+    &[data-destructive="true"] {
+      background-color: var(--color-destructive);
+      color: var(--color-on-destructive);
+      border-color: transparent;
+    }
+  }
+}
+
+.sol-button__icon {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  line-height: 0;
+}
+
+.sol-button .solara-icon {
+  color: currentColor;
+}
+
+.sol-button .solara-icon [stroke]:not([stroke="none"]) {
+  stroke: currentColor;
+}
+
+.sol-button .solara-icon [fill]:not([fill="none"]) {
+  fill: currentColor;
+}
+
+.sol-button__label {
+  display: inline-flex;
+  align-items: center;
+}

package/src/Button.tsx

@@ -0,0 +1,64 @@
+import "./Button.scss";
+import { Icon } from "@solara/icons";
+import type { IconProps } from "@solara/icons";
+import type { ButtonIcon, ButtonProps } from "./Button.types";
+
+const normalizeIconProps = (icon: ButtonIcon): IconProps =>
+  typeof icon === "string" ? { name: icon } : icon;
+
+const resolveIconProps = (icon: ButtonIcon): IconProps => {
+  const iconProps = normalizeIconProps(icon);
+
+  return {
+    ...iconProps,
+    style: {
+      ...iconProps.style,
+      // Force button icon color to follow the button's text color.
+      color: "currentColor"
+    }
+  };
+};
+
+const renderIcon = (icon: ButtonIcon, position: "left" | "right" | "only") => (
+  <span className={`sol-button__icon sol-button__icon--${position}`}>
+    <Icon {...resolveIconProps(icon)} />
+  </span>
+);
+
+export function Button({
+  label,
+  variant = "default",
+  size = "medium",
+  radius = "default",
+  destructive = false,
+  iconLeft,
+  iconRight,
+  iconOnly,
+  className,
+  disabled,
+  type,
+  "aria-label": ariaLabel,
+  ...props
+}: ButtonProps) {
+  const isIconOnly = Boolean(iconOnly);
+  // Default aria-label to the label when an icon-only button is used.
+  const resolvedAriaLabel = ariaLabel ?? (isIconOnly ? label : undefined);
+
+  return (
+    <button
+      type={type ?? "button"}
+      data-size={size}
+      data-radius={radius}
+      data-destructive={destructive}
+      data-icon-only={isIconOnly ? "true" : undefined}
+      disabled={disabled}
+      className={["sol-button", variant, className].filter(Boolean).join(" ")}
+      aria-label={resolvedAriaLabel}
+      {...props}>
+      {isIconOnly && iconOnly ? renderIcon(iconOnly, "only") : null}
+      {!isIconOnly && iconLeft ? renderIcon(iconLeft, "left") : null}
+      {!isIconOnly && label ? <span className="sol-button__label">{label}</span> : null}
+      {!isIconOnly && iconRight ? renderIcon(iconRight, "right") : null}
+    </button>
+  );
+}

package/src/Button.types.ts

@@ -0,0 +1,19 @@
+import type React from "react";
+import type { IconProps } from "@solara/icons";
+
+export type ButtonVariant = "primary" | "default" | "tertiary" | "ghost" | "accent";
+export type ButtonSize = "small" | "medium" | "large";
+export type ButtonRadius = "default" | "none" | "full";
+
+export type ButtonIcon = IconProps | IconProps["name"];
+
+export type ButtonProps = Omit<React.ButtonHTMLAttributes<HTMLButtonElement>, "children"> & {
+  label?: string;
+  variant?: ButtonVariant;
+  size?: ButtonSize;
+  radius?: ButtonRadius;
+  destructive?: boolean;
+  iconLeft?: ButtonIcon;
+  iconRight?: ButtonIcon;
+  iconOnly?: ButtonIcon;
+};

package/src/index.ts

@@ -0,0 +1,2 @@
+export { Button } from "./Button";
+export type { ButtonIcon, ButtonProps, ButtonRadius, ButtonSize, ButtonVariant } from "./Button.types";