@Relativity - Action Buttons for MUI

If you want low-key responsiveness to api calls or user actions that should give the user "just a little" feedback these buttons should be perfect for you.

Explore the live Storybook for interactive examples and API guides, or visit the package website for a quick demo.

npm install @relativity/mui-action-buttons

For coding assistants, start with the agent usage guide or llms.txt. They include complete examples, the async callback contract, accessibility notes, common mistakes, and a little playful inspiration. Both files ship in the npm package. Storybook Guide / Agents renders the same guide.

The package supports React 18.2 and React 19 with MUI 6 and Emotion 11. React, React DOM, MUI, and Emotion are peer dependencies so the button shares the application's React instance, theme, and styling cache. Both CommonJS and ES module entry points include the "use client" directive for Next.js.

The first button I've implemented is the AIconButton. It takes a string, and an endIcon or startIcon prop.

Example save button:

import { AIconButton } from "@relativity/mui-action-buttons"
import "@relativity/mui-action-buttons/styles.css"
import SaveIcon from "@mui/icons-material/Save"

async function handleSave() {
    //your fancy long-running code goes here
    await new Promise(r => setTimeout(r, 3000))
}

//...

<AIconButton 
    endIcon={<SaveIcon/>} 
    onClick={handleSave}
    >SAVE
</AIconButton>

For async calls, a spinner replaces the icon you passed in until it completes.

If you click a button and the handler completes without error, the original icon returns and the button changes color for 2 seconds.

If the handler throws an error, the button turns red, and displays a warning icon until clicked again.

Local Storybook

Use Node 22.12 or newer (nvm use selects Node 24), then run:

npm ci
npm run storybook

Open http://localhost:6006. Guide / Usage covers installation, the promise lifecycle, API examples, and current limitations. Components / AIconButton includes editable controls, callback actions, light/dark themes, pending/success/error states, dismissal and retry, repeated successes, icon placement, variants, sizes, colors, disabled/full-width buttons, styling, and theme integration. Demo requests run locally without a backend. If port 6006 is occupied, choose another with npm run storybook -- --port 6007.

npm run build-storybook       # Static site in storybook-static/
npm run typecheck:storybook   # Check configuration and stories
npm run storybook:install-browser # Install Chromium once
npm run test:storybook        # Browser rendering and interaction tests
npm run test:storybook:watch  # Watch stories during development

The Accessibility panel reports findings, including existing component limitations; these are warnings in story tests. Storybook dependencies are development-only. The published package contains library assets, the plain Markdown agent guide, and its discovery index.

Website and GitHub Pages

npm run site                 # Develop the landing page at http://localhost:4173
npm run typecheck:site
npm run build:site           # Landing page + Storybook in site-dist/
npm run preview:site         # Preview the complete static site at http://localhost:4173
npm run test:site            # Chromium checks at the /mui-action-buttons/ project path

Install Chromium first with npm run storybook:install-browser if needed. The build serves the landing page at the root, Storybook at storybook/, and plain agent documentation at llms.txt and docs/agents.md. Asset paths are relative so the site works under GitHub's project URL.

GitHub Pages uses GitHub Actions as its publishing source. The workflow builds and checks pull requests without deploying them. Pushes to main publish after the component, package, story, and site checks pass. The workflow can also be run manually on main. Generated files stay out of Git and npm.

Publishing to npm

The separate .github/workflows/publish.yml workflow runs automatically on pushes to main and can be rerun manually on main. It compares package.json with the public npm registry before installing dependencies. If that version already exists (including a version older than latest), it skips tests and publication in this workflow; the regular CI workflow still runs. Registry failures stop publication rather than treating the package as unpublished.

For an unpublished version, it installs with npm ci and requires the publishing gate tests, component tests, package checks, Storybook/site type checks, static site build, and both browser suites to pass. It packs the verified library and passes that tarball to a separate publish job, which rechecks npm and publishes it publicly with the latest tag. Release runs are serialized and not cancelled mid-publication. No version is bumped automatically.

Configure npm trusted publishing once in the npm package's Settings → Trusted Publisher → GitHub Actions:

• Organization or user: relativityboy
• Repository: mui-action-buttons
• Workflow filename: publish.yml (just the filename)
• Environment: leave blank (this workflow has no environment)
• Allowed actions: enable direct publishing with npm publish

The workflow uses Node 24 and npm's OIDC authentication; no NPM_TOKEN secret is required. Configure trust shortly before the first release: npm requires a new trusted publisher to complete its first successful publish within two days.

To release, update both package.json and package-lock.json with npm version <version> --no-git-tag-version, commit the changes, and push to main. A changed, unpublished version triggers the full test-and-publish path. Only put stable releases on this path because it updates latest. Run npm run test:publish locally to check the gate without accessing npm.

The dependency override for @istanbuljs/load-nyc-config selects js-yaml 4, which removes the legacy argparse / sprintf-js dependency chain affected by GHSA-hp3w-g68c-fv3c. The config loader uses the supported load() API. Remove the override when the upstream loader updates its dependency to an unaffected version.