{"version":1,"name":"Ballmac UI","homepage":"https://ui.ballmac.com","registry":"https://ui.ballmac.com/r/{name}.json","namespace":"@ballmac","setup":"npx shadcn@latest registry add @ballmac=https://ui.ballmac.com/r/{name}.json","setupNote":"Optional. @ballmac is in the official shadcn registry directory, so `npx shadcn@latest add @ballmac/` works without it. Run setup once only for an older shadcn CLI, or for the shadcn MCP server, which reads components.json.","items":[{"name":"accordion","kind":"component","type":"registry:ui","title":"Accordion","description":"Vertically stacked disclosure sections on Radix Accordion, single or multiple open, with hairline dividers, a rotating plus and height animation.","category":"primitives","tier":"free","tags":["accordion","disclosure","faq","collapsible","radix"],"version":"1.0.0","updated":"2026-09-28","url":"https://ui.ballmac.com/components/accordion","registryUrl":"https://ui.ballmac.com/r/accordion.json","install":"npx shadcn@latest add @ballmac/accordion","summary":"Show and hide sections of content one at a time (type=\"single\" collapsible) or several at once (type=\"multiple\").","whenToUse":["FAQ sections","Settings or docs with optional detail","Long content where readers scan headings first"],"whenNotToUse":["A single show/hide toggle (use reasoning-disclosure or a Radix Collapsible)","Navigation between views (use tabs)"],"composesWith":["badge"],"dependencies":["radix-ui","lucide-react"],"registryDependencies":["shadcn:utils"],"examples":["accordion-demo","accordion-multiple"],"states":[],"preview":"https://ui.ballmac.com/preview/accordion-demo"},{"name":"activity-feed","kind":"component","type":"registry:ui","title":"Activity Feed","description":"A compact actor and action feed with timestamps and an empty state.","category":"data-display","tier":"free","tags":["activity","history","events"],"version":"1.0.0","updated":"2026-09-30","url":"https://ui.ballmac.com/components/activity-feed","registryUrl":"https://ui.ballmac.com/r/activity-feed.json","install":"npx shadcn@latest add @ballmac/activity-feed","summary":"A compact actor and action feed with timestamps and an empty state.","whenToUse":["Show recent changes made by people or the system"],"whenNotToUse":["Use Timeline for milestone progression"],"composesWith":["timeline"],"dependencies":[],"registryDependencies":["shadcn:utils","i18n"],"examples":["activity-feed-demo","activity-feed-states"],"states":[],"preview":"https://ui.ballmac.com/preview/activity-feed-demo"},{"name":"agent-graph","kind":"component","type":"registry:ui","title":"Agent Graph","description":"A layered graph of how agents, tools, memory and people hand work to each other: nodes that say what they are and what they are doing in words, labelled arrows, the active path drawn heavier, and arrow keys that follow the edges.","category":"ai","tier":"free","tags":["ai","agents","graph","multi-agent","workflow","orchestration","diagram","topology"],"version":"1.0.0","updated":"2026-10-24","url":"https://ui.ballmac.com/components/agent-graph","registryUrl":"https://ui.ballmac.com/r/agent-graph.json","install":"npx shadcn@latest add @ballmac/agent-graph","summary":"nodes is [{ id, label, kind?: agent | tool | human | memory, status?: idle | working | waiting | blocked | done, detail? }]; edges is [{ from, to, label?, active? }]. Columns are computed from the edges; an edge that loops back is drawn under the nodes. selected / defaultSelected / onSelectedChange. layoutGraph(nodes, edges) is exported.","whenToUse":["Showing how a multi-agent system is wired and where the work is right now","A map of tools and people an agent can call"],"whenNotToUse":["Who did what over time; use agent-lanes","A linear list of steps; use trace or agent-plan","Flows with amounts; use flow-sankey"],"composesWith":["agent-roster","agent-lanes","handoff-card","tool-catalog"],"dependencies":["lucide-react"],"registryDependencies":["shadcn:utils","i18n"],"examples":["agent-graph-demo","agent-graph-review"],"states":[],"statesNone":"A presentational diagram: you pass the nodes and edges in, so it has nothing of its own to load or fail.","preview":"https://ui.ballmac.com/preview/agent-graph-demo"},{"name":"agent-lanes","kind":"component","type":"registry:ui","title":"Agent Lanes","description":"A swimlane timeline for multi-agent runs: one lane per agent, steps coloured by what they are doing, dashed handoffs between lanes, a Now line and a detail panel, all reachable with the arrow keys.","category":"ai","tier":"free","tags":["ai","agents","timeline","swimlane","handoff","multi-agent","trace"],"version":"1.0.0","updated":"2026-10-24","url":"https://ui.ballmac.com/components/agent-lanes","registryUrl":"https://ui.ballmac.com/r/agent-lanes.json","install":"npx shadcn@latest add @ballmac/agent-lanes","summary":"lanes is [{ id, name, role?, segments: [{ id, start, end, kind, label, detail? }] }] with times in seconds; kind is thinking | tool | waiting | blocked | done. handoffs is [{ from, to, label? }] using segment ids. Optional duration, now, selected / defaultSelected / onSelectedChange, formatTime.","whenToUse":["Showing what several agents did and when, and who handed work to whom","Finding the step where a run waited or got blocked"],"whenNotToUse":["One agent's linear steps; use trace","A plan with checkable steps; use agent-plan","A project schedule; use the gantt block"],"composesWith":["trace","token-meter","approval-card","tool-call-card"],"dependencies":["lucide-react"],"registryDependencies":["shadcn:utils","direction","i18n"],"examples":["agent-lanes-demo","agent-lanes-blocked"],"states":[],"statesNone":"A presentational chart: you pass the finished or running steps in, so there is nothing for it to load, submit or fail.","preview":"https://ui.ballmac.com/preview/agent-lanes-demo"},{"name":"agent-plan","kind":"component","type":"registry:ui","title":"Agent Plan","description":"A live task plan for agents: a vertical timeline with pending, running, done, failed and skipped steps, nested substeps, expandable output, segmented progress and retry on failure.","category":"ai","tier":"free","tags":["ai","agent","plan","steps","timeline","tasks"],"version":"1.0.0","updated":"2026-09-30","url":"https://ui.ballmac.com/components/agent-plan","registryUrl":"https://ui.ballmac.com/r/agent-plan.json","install":"npx shadcn@latest add @ballmac/agent-plan","summary":"steps is [{ id, title, status, description?, duration?, detail?, error?, steps? }]. Update statuses as the agent works and the timeline, progress bar and screen reader summary follow. onRetry adds a Retry button to failed steps.","whenToUse":["Showing what an agent will do and is doing","Multi-step workflows that can fail part-way"],"whenNotToUse":["A single tool invocation; use tool-call-card","Onboarding checklists; use onboarding-checklist"],"composesWith":["tool-call-card","approval-card","thinking-indicator"],"dependencies":["motion@^12","lucide-react"],"registryDependencies":["shadcn:utils","i18n"],"examples":["agent-plan-demo","agent-plan-failed"],"states":[],"preview":"https://ui.ballmac.com/preview/agent-plan-demo"},{"name":"agent-roster","kind":"component","type":"registry:ui","title":"Agent Roster","description":"Every agent on a team of agents as a card: name and role, a status in words (working, waiting, blocked, idle, offline), what it is doing, a load meter and when it was last active, with status counts that filter the grid.","category":"ai","tier":"free","tags":["ai","agents","roster","status","team","multi-agent","monitor"],"version":"1.0.0","updated":"2026-10-24","url":"https://ui.ballmac.com/components/agent-roster","registryUrl":"https://ui.ballmac.com/r/agent-roster.json","install":"npx shadcn@latest add @ballmac/agent-roster","summary":"agents is [{ id, name, role?, status: working | idle | waiting | blocked | offline, task?, load?: 0..100, lastActive? }]. selected / defaultSelected / onSelectedChange track the picked agent (a second click clears it). Status counts are filters; statuses with no agents are hidden.","whenToUse":["An overview of the agents in a multi-agent product and what each is doing","Picking an agent to open its run, logs or settings"],"whenNotToUse":["One agent's steps; use trace","A table of users; use data-table","Who handed what to whom; use agent-lanes or handoff-card"],"composesWith":["agent-lanes","handoff-card","run-ledger","trace"],"dependencies":["lucide-react"],"registryDependencies":["shadcn:utils","i18n"],"examples":["agent-roster-demo","agent-roster-select"],"states":[],"statesNone":"A presentational overview: the agents are passed in, so it has nothing of its own to load or fail.","preview":"https://ui.ballmac.com/preview/agent-roster-demo"},{"name":"ai-chat","kind":"component","type":"registry:ui","title":"AI Chat","description":"The layout for a chat UI: a message log that sticks to the bottom while replies stream unless the reader scrolls up, a jump-to-latest button, an empty state with suggestions and a footer.","category":"ai","tier":"free","tags":["ai","chat","conversation","llm","scroll","streaming","layout"],"version":"1.0.0","updated":"2026-09-28","url":"https://ui.ballmac.com/components/ai-chat","registryUrl":"https://ui.ballmac.com/r/ai-chat.json","install":"npx shadcn@latest add @ballmac/ai-chat","summary":"Layout only: (a full-height column) > (role=log, auto-scroll) + . Put ai-message items inside ChatMessages and a prompt-input inside ChatFooter. It holds no chat state, so any source works (Vercel AI SDK useChat, your own fetch stream).","whenToUse":["Building an assistant, support bot or copilot panel from ai-message and prompt-input","Any log that receives streaming content and should follow the newest line unless the reader scrolls up","A first-run screen with suggested prompts (ChatEmpty + ChatSuggestions)"],"whenNotToUse":["A single one-off AI answer on a page (use ai-message or streaming-text alone)","Terminal-style command output (use terminal)"],"composesWith":["ai-message","prompt-input","streaming-text","tool-call-card","reasoning-disclosure"],"dependencies":["lucide-react","motion@^12"],"registryDependencies":["button","motion-presets","shadcn:utils","i18n"],"examples":["ai-chat-demo","ai-chat-empty"],"states":[],"preview":"https://ui.ballmac.com/preview/ai-chat-demo"},{"name":"ai-message","kind":"component","type":"registry:ui","title":"AI Message","description":"A chat message with user, assistant and system roles: right-aligned user bubbles, full-width assistant prose, an avatar slot, hover-revealed actions and a hydration-safe timestamp.","category":"ai","tier":"free","tags":["ai","chat","message","llm","assistant","copy"],"version":"1.0.0","updated":"2026-09-28","url":"https://ui.ballmac.com/components/ai-message","registryUrl":"https://ui.ballmac.com/r/ai-message.json","install":"npx shadcn@latest add @ballmac/ai-message","summary":"Render one chat turn. wraps , , (with and ) and . It takes plain children, so it works with the Vercel AI SDK, LangChain or any stream.","whenToUse":["Rendering each turn of an assistant or chatbot conversation","Showing copy, regenerate and feedback buttons under an assistant reply","A system note inside a conversation, such as 'Model switched to a smaller context window'"],"whenNotToUse":["The scrolling conversation layout itself (use ai-chat and put messages inside ChatMessages)","Threaded comments or email-style lists where both sides look alike"],"composesWith":["ai-chat","prompt-input","streaming-text","tool-call-card","reasoning-disclosure","code-block"],"dependencies":["lucide-react"],"registryDependencies":["button","shadcn:utils","i18n"],"examples":["ai-message-demo","ai-message-actions"],"states":[],"preview":"https://ui.ballmac.com/preview/ai-message-demo"},{"name":"ai-orb","kind":"component","type":"registry:ui","title":"AI Orb","description":"A glass orb of drifting theme-colored light that shows whether the assistant is idle, listening, thinking or speaking, and swells with a live voice level.","category":"ai","tier":"free","tags":["ai","orb","voice","assistant","status","visual"],"version":"1.0.0","updated":"2026-09-30","url":"https://ui.ballmac.com/components/ai-orb","registryUrl":"https://ui.ballmac.com/r/ai-orb.json","install":"npx shadcn@latest add @ballmac/ai-orb","summary":"state is idle | listening | thinking | speaking. Pass level (0 to 1) to make it swell with audio. size is sm | default | lg | xl. Colors come from chart-1 to chart-5, so it follows the theme.","whenToUse":["The face of a voice assistant or a full-screen chat","A status mark beside an assistant's name"],"whenNotToUse":["A plain spinner (use spinner)","Anything that must be readable as text; pair it with thinking-indicator"],"composesWith":["voice-input","thinking-indicator","ai-chat"],"dependencies":["motion@^12","class-variance-authority"],"registryDependencies":["shadcn:utils"],"examples":["ai-orb-demo","ai-orb-voice"],"states":[],"preview":"https://ui.ballmac.com/preview/ai-orb-demo"},{"name":"alert-dialog","kind":"component","type":"registry:ui","title":"Alert Dialog","description":"Focus-managed confirmation for consequential actions, with a clear cancel path, optional media, and a token-based destructive action.","category":"feedback","tier":"free","tags":["confirmation","modal","destructive","radix"],"version":"1.0.0","updated":"2026-09-30","url":"https://ui.ballmac.com/components/alert-dialog","registryUrl":"https://ui.ballmac.com/r/alert-dialog.json","install":"npx shadcn@latest add @ballmac/alert-dialog","summary":"Ask for explicit confirmation before a consequential action; cancel remains the safe keyboard path.","whenToUse":["Delete or revoke something permanent","Confirm an action with a material consequence"],"whenNotToUse":["Show information without requiring a choice; use dialog","Confirm a low-risk routine action"],"composesWith":["button"],"dependencies":["radix-ui"],"registryDependencies":["shadcn:utils"],"examples":["alert-dialog-demo","alert-dialog-states"],"states":[],"preview":"https://ui.ballmac.com/preview/alert-dialog-demo"},{"name":"alert","kind":"component","type":"registry:ui","title":"Alert","description":"A semantic callout with five theme-aware tones, clear icon placement, an action row, and opt-in urgent announcements.","category":"feedback","tier":"free","tags":["alert","callout","status"],"version":"1.0.0","updated":"2026-09-29","url":"https://ui.ballmac.com/components/alert","registryUrl":"https://ui.ballmac.com/r/alert.json","install":"npx shadcn@latest add @ballmac/alert","summary":"A semantic callout with five theme-aware tones, clear icon placement, an action row, and opt-in urgent announcements.","whenToUse":["Display a status or important message","Pair a warning with a clear next action"],"whenNotToUse":["Use a toast for transient confirmation"],"composesWith":["badge","button"],"dependencies":["class-variance-authority"],"registryDependencies":["shadcn:utils"],"examples":["alert-demo","alert-states"],"states":[],"preview":"https://ui.ballmac.com/preview/alert-demo"},{"name":"android-frame","kind":"component","type":"registry:ui","title":"Android Frame","description":"A modern Android phone drawn in CSS: satin frame in porcelain, obsidian or sage, centered punch-hole camera, Material-style status bar and gesture or three-button navigation. Children render at phone resolution, scaled to fit.","category":"devices","tier":"free","tags":["mockup","device","phone","android","pixel","mobile","hero"],"version":"1.0.0","updated":"2026-10-01","url":"https://ui.ballmac.com/components/android-frame","registryUrl":"https://ui.ballmac.com/r/android-frame.json","install":"npx shadcn@latest add @ballmac/android-frame","summary":"Wrap a mobile screen in : children render below a status bar at 412 CSS px wide and are scaled to the frame's width. Set the width with className (e.g. w-64).","whenToUse":["Showing an Android or responsive mobile app","Side by side with phone-frame for cross-platform stories"],"whenNotToUse":["iPhone mockups (phone-frame)","Real device screenshots with a bezel"],"composesWith":["phone-frame","tablet-frame","laptop-frame"],"dependencies":["motion@^12"],"registryDependencies":["shadcn:utils","media"],"examples":["android-frame-demo","android-frame-buttons"],"states":[],"preview":"https://ui.ballmac.com/preview/android-frame-demo"},{"name":"animated-beam","kind":"component","type":"registry:ui","title":"Animated Beam","description":"An SVG beam that connects two elements with a curved path and sends a glowing gradient pulse along it. Follows layout changes, pauses off-screen, static under reduced motion.","category":"motion","tier":"free","tags":["beam","connection","integration","diagram","svg","hero","motion"],"version":"1.0.0","updated":"2026-09-29","url":"https://ui.ballmac.com/components/animated-beam","registryUrl":"https://ui.ballmac.com/r/animated-beam.json","install":"npx shadcn@latest add @ballmac/animated-beam","summary":"Give a relative container a ref, give each endpoint element a ref, and render inside the container once per connection. Put endpoint nodes above the beams with relative z-10. The SVG is aria-hidden and pointer-events-none.","whenToUse":["Integration diagrams: tools or data sources flowing into an agent or product","Showing a request path between services on a landing page","Explaining a sync or pipeline visually in a feature section"],"whenNotToUse":["Real, data-driven graphs with many nodes (use a graph library)","Conveying state on its own; label the nodes, the beam is decorative"],"composesWith":["orbiting-circles","dot-pattern","border-beam"],"dependencies":["motion@^12"],"registryDependencies":["shadcn:utils"],"examples":["animated-beam-demo","animated-beam-bidirectional"],"states":[],"preview":"https://ui.ballmac.com/preview/animated-beam-demo"},{"name":"animated-grid","kind":"component","type":"registry:ui","title":"Animated Grid","description":"A decorative hairline grid background where a few random cells softly light up and fade, like instrument lights. SVG, hydration-safe, static under reduced motion.","category":"motion","tier":"free","tags":["background","grid","pattern","hero","decorative","motion"],"version":"1.0.0","updated":"2026-09-28","url":"https://ui.ballmac.com/components/animated-grid","registryUrl":"https://ui.ballmac.com/r/animated-grid.json","install":"npx shadcn@latest add @ballmac/animated-grid","summary":"Place as the first child of a relative container (it is absolute inset-0, aria-hidden, pointer-events-none) and put content after it with relative positioning. Lit cells are picked on the client after mount, so SSR output is just the grid.","whenToUse":["Hero or section backgrounds on developer-tool and SaaS landing pages","Empty states or sign-in screens that need quiet texture"],"whenNotToUse":["Behind dense text or data (it competes with content)","More than one per screen"],"composesWith":["text-reveal","shimmer-text","magnetic-button"],"dependencies":["motion@^12"],"registryDependencies":["shadcn:utils","motion-presets"],"examples":["animated-grid-demo"],"states":[],"preview":"https://ui.ballmac.com/preview/animated-grid-demo"},{"name":"animated-list","kind":"component","type":"registry:ui","title":"Animated List","description":"A live feed where new items spring in at the top and the rest glide down, with leave animations, an item cap, an optional fading tail and a polite announcement for new entries.","category":"motion","tier":"free","tags":["list","feed","notifications","live","spring"],"version":"1.0.0","updated":"2026-10-01","url":"https://ui.ballmac.com/components/animated-list","registryUrl":"https://ui.ballmac.com/r/animated-list.json","install":"npx shadcn@latest add @ballmac/animated-list","summary":"…. Each item needs a stable key. Prepend new entries to your array; layout animation does the rest.","whenToUse":["Live activity, notification and event feeds","Chat-like logs where entries arrive over time"],"whenNotToUse":["Static lists (stagger-list)","Hundreds of rows (virtualize instead)"],"composesWith":["notification-stack","activity-feed","stagger-list"],"dependencies":["motion@^12"],"registryDependencies":["shadcn:utils"],"examples":["animated-list-demo","animated-list-log"],"states":[],"preview":"https://ui.ballmac.com/preview/animated-list-demo"},{"name":"animated-number-flow","kind":"component","type":"registry:ui","title":"Animated Number Flow","description":"A number whose digits roll like an odometer to the new value, with locale and Intl formatting for currency, percent and compact notation, and widths that animate as digits come and go.","category":"motion","tier":"free","tags":["number","odometer","counter","currency","format"],"version":"1.0.0","updated":"2026-10-01","url":"https://ui.ballmac.com/components/animated-number-flow","registryUrl":"https://ui.ballmac.com/r/animated-number-flow.json","install":"npx shadcn@latest add @ballmac/animated-number-flow","summary":". Change value and each digit rolls to its new place. Uses Intl.NumberFormat with a fixed default locale so server and browser agree.","whenToUse":["Prices, balances and stats that change on interaction","Live metrics"],"whenNotToUse":["A one-time count-up on scroll (number-ticker)"],"composesWith":["number-ticker","stat-card","kpi-row"],"dependencies":["motion@^12"],"registryDependencies":["shadcn:utils","i18n"],"examples":["animated-number-flow-demo","animated-number-flow-formats"],"states":[],"preview":"https://ui.ballmac.com/preview/animated-number-flow-demo"},{"name":"animated-tabs","kind":"component","type":"registry:ui","title":"Animated Tabs","description":"Radix Tabs with a pill or underline indicator that slides between triggers on a spring, and panels that fade in. Keeps full keyboard support and ARIA; controlled or uncontrolled.","category":"navigation","tier":"free","tags":["tabs","segmented","navigation","indicator","layout animation","radix"],"version":"1.0.0","updated":"2026-09-29","url":"https://ui.ballmac.com/components/animated-tabs","registryUrl":"https://ui.ballmac.com/r/animated-tabs.json","install":"npx shadcn@latest add @ballmac/animated-tabs","summary":"Same API as Radix Tabs: with AnimatedTabsList, AnimatedTabsTrigger value and AnimatedTabsContent value. The indicator is a Motion layoutId element inside the active trigger.","whenToUse":["Switching between views of the same object (overview, activity, settings)","Settings pages with a few sections","Pricing toggles such as monthly and yearly"],"whenNotToUse":["Page-level navigation between routes (use links)","More than about six options (use a select)","Package-manager command tabs (use install-tabs)"],"composesWith":["install-tabs","code-block"],"dependencies":["motion@^12","radix-ui"],"registryDependencies":["shadcn:utils","motion-presets"],"examples":["animated-tabs-demo","animated-tabs-underline"],"states":[],"preview":"https://ui.ballmac.com/preview/animated-tabs-demo"},{"name":"api-endpoint","kind":"component","type":"registry:ui","title":"API Endpoint","description":"An endpoint reference card: method and path with highlighted parameters, auth, grouped parameter lists, and request and response examples in tabs with copy.","category":"developer","tier":"free","tags":["api","endpoint","docs","rest","reference"],"version":"1.0.0","updated":"2026-10-01","url":"https://ui.ballmac.com/components/api-endpoint","registryUrl":"https://ui.ballmac.com/r/api-endpoint.json","install":"npx shadcn@latest add @ballmac/api-endpoint","summary":"method, path (use {id} for path parameters), summary, description, auth, parameters [{ name, in, type, required, description }], requestExample and responses [{ status, description, example }]. Collapsible; copies the full URL when baseUrl is set.","whenToUse":["Hand-written API reference pages","Internal docs for a small API"],"whenNotToUse":["Generating a full OpenAPI portal (render from the spec with your own loop over this component)"],"composesWith":["snippet-tabs","code-block","json-viewer"],"dependencies":["lucide-react","radix-ui"],"registryDependencies":["shadcn:utils","copy-button","highlight","i18n"],"examples":["api-endpoint-demo","api-endpoint-list"],"states":[],"preview":"https://ui.ballmac.com/preview/api-endpoint-demo"},{"name":"api-key-field","kind":"component","type":"registry:ui","title":"API Key Field","description":"Displays a secret such as an API key, masked by default (sk-live-••••••••a1b2), with a reveal toggle, a copy button that copies the full key, and an optional regenerate action.","category":"developer","tier":"free","tags":["api-key","secret","token","copy","mask","settings","developer"],"version":"1.0.1","updated":"2026-10-02","url":"https://ui.ballmac.com/components/api-key-field","registryUrl":"https://ui.ballmac.com/r/api-key-field.json","install":"npx shadcn@latest add @ballmac/api-key-field","summary":"Show an existing secret: . It is read-only; copy always copies the full value, even while masked.","whenToUse":["API keys, webhook signing secrets and access tokens on settings or developer pages","Showing a newly created key once so the user can copy it"],"whenNotToUse":["Password entry (use an input with type=password)","Secrets you should not send to the browser at all (show only the last four characters from the server)"],"composesWith":["button","dialog"],"dependencies":["lucide-react"],"registryDependencies":["shadcn:utils","i18n"],"examples":["api-key-field-demo"],"states":[],"preview":"https://ui.ballmac.com/preview/api-key-field-demo"},{"name":"app-shell","kind":"component","type":"registry:ui","title":"App Shell","description":"The frame of an application page: skip link, sticky header, sidebar that becomes a sheet on small screens, main area, optional aside and footer.","category":"layout","tier":"free","tags":["layout","dashboard","sidebar","landmarks"],"version":"1.0.0","updated":"2026-09-30","url":"https://ui.ballmac.com/components/app-shell","registryUrl":"https://ui.ballmac.com/r/app-shell.json","install":"npx shadcn@latest add @ballmac/app-shell","summary":"AppShell > AppShellSkipLink, AppShellHeader (with AppShellSidebarTrigger), AppShellSidebar, AppShellMain, AppShellAside, AppShellFooter. Sizes are CSS variables set by props.","whenToUse":["Admin and dashboard pages","Any page with a sidebar, a main column and optional details"],"whenNotToUse":["A collapsible icon-rail sidebar; use sidebar","Marketing pages; use navbar"],"composesWith":["sidebar","navbar","sheet"],"dependencies":["lucide-react"],"registryDependencies":["shadcn:utils","sheet","i18n"],"examples":["app-shell-demo","app-shell-states"],"states":[],"preview":"https://ui.ballmac.com/preview/app-shell-demo"},{"name":"app-window","kind":"component","type":"registry:ui","title":"App Window","description":"The window chrome of a real desktop app (Tauri or Electron): a title bar that drags the window, double-click to maximize, and the controls the platform draws: traffic lights, Windows caption buttons, or none.","category":"macos","tier":"free","tags":["window","titlebar","tauri","electron","desktop","macos","windows","chrome","drag region","feel"],"version":"1.0.1","updated":"2026-10-11","url":"https://ui.ballmac.com/components/app-window","registryUrl":"https://ui.ballmac.com/r/app-window.json","install":"npx shadcn@latest add @ballmac/app-window","summary":"Real window chrome for a Tauri or Electron app. toolbar. It draws the platform's controls (macOS traffic lights on the left, Windows caption buttons on the right, none on iOS or web) from the page's feel, drags the window, and maximizes on double-click. You wire the callbacks; there is no Tauri or Electron dependency.","whenToUse":["The window of a Tauri or Electron app with a hidden native title bar (decorations: false, or titleBarStyle hidden)","A desktop-style web app that should match the platform's window chrome"],"whenNotToUse":["Landing-page mockups of a Mac app (use mac-window)","Modal dialogs inside a web app (use dialog)"],"composesWith":["feel-auto","sidebar","toolbar","button"],"dependencies":[],"registryDependencies":["shadcn:utils","i18n","feel-presets"],"examples":["app-window-demo","app-window-feels"],"states":[],"preview":"https://ui.ballmac.com/preview/app-window-demo"},{"name":"approval-card","kind":"component","type":"registry:ui","title":"Approval Card","description":"A human-in-the-loop confirmation for agent actions: what will happen, risk level in words, the exact command, Approve, Deny and Always allow, a timeout countdown and a recorded decision.","category":"ai","tier":"free","tags":["ai","agent","approval","confirm","safety","human-in-the-loop"],"version":"1.0.0","updated":"2026-09-30","url":"https://ui.ballmac.com/components/approval-card","registryUrl":"https://ui.ballmac.com/r/approval-card.json","install":"npx shadcn@latest add @ballmac/approval-card","summary":"title, description, risk (low | medium | high), details rows and a preview of the exact action. onApprove, onDeny, optional onAlwaysAllow. expiresIn counts down and denies. After a decision the card shows the outcome and moves focus to it.","whenToUse":["Before an agent runs commands, writes files or sends data out","Any action that needs a person's explicit yes"],"whenNotToUse":["Confirming a destructive UI action; use alert-dialog","Reporting what a tool already did; use tool-call-card"],"composesWith":["agent-plan","tool-call-card","ai-message"],"dependencies":["motion@^12","lucide-react"],"registryDependencies":["shadcn:utils","i18n"],"examples":["approval-card-demo","approval-card-risks"],"states":[],"preview":"https://ui.ballmac.com/preview/approval-card-demo"},{"name":"artifact-panel","kind":"component","type":"registry:ui","title":"Artifact Panel","description":"A side panel for things an assistant generates: Preview and Code tabs, version stepping, copy and download, a streaming state and a close button, with the rendered result in your own slot.","category":"ai","tier":"free","tags":["ai","artifact","canvas","preview","code","panel"],"version":"1.0.0","updated":"2026-09-30","url":"https://ui.ballmac.com/components/artifact-panel","registryUrl":"https://ui.ballmac.com/r/artifact-panel.json","install":"npx shadcn@latest add @ballmac/artifact-panel","summary":"title, kind, icon, code, filename, language and children as the preview. versions > 1 adds steppers (version/onVersionChange). streaming shows a progress edge and disables copy and download. onClose adds a close button.","whenToUse":["Code, documents or designs a model produced next to the chat","Anything users iterate on in versions"],"whenNotToUse":["Showing code in the chat; use code-block","Generic tabs; use tabs"],"composesWith":["ai-chat","code-block","resizable"],"dependencies":["motion@^12","lucide-react","radix-ui"],"registryDependencies":["shadcn:utils","i18n"],"examples":["artifact-panel-demo","artifact-panel-streaming"],"states":[],"preview":"https://ui.ballmac.com/preview/artifact-panel-demo"},{"name":"aspect-ratio","kind":"component","type":"registry:ui","title":"Aspect Ratio","description":"A CSS-native ratio frame that reserves space for media and safely handles invalid ratio values.","category":"layout","tier":"free","tags":["media","image","layout"],"version":"1.0.0","updated":"2026-09-29","url":"https://ui.ballmac.com/components/aspect-ratio","registryUrl":"https://ui.ballmac.com/r/aspect-ratio.json","install":"npx shadcn@latest add @ballmac/aspect-ratio","summary":"A CSS-native ratio frame that reserves space for media and safely handles invalid ratio values.","whenToUse":["Reserve image or video space before it loads","Keep cards aligned across a grid"],"whenNotToUse":["Use fixed height when cropping is intentional"],"composesWith":["card"],"dependencies":[],"registryDependencies":["shadcn:utils"],"examples":["aspect-ratio-demo","aspect-ratio-states"],"states":[],"preview":"https://ui.ballmac.com/preview/aspect-ratio-demo"},{"name":"audio-player","kind":"component","type":"registry:ui","title":"Audio Player","description":"A podcast-style audio player: play and pause, skip back and forward, a scrubber with chapter ticks, a named current chapter and a speed control. Works with a real file or as a silent demo.","category":"data-display","tier":"free","tags":["audio","player","podcast","music","media","chapters","speed"],"version":"1.0.0","updated":"2026-10-01","url":"https://ui.ballmac.com/components/audio-player","registryUrl":"https://ui.ballmac.com/r/audio-player.json","install":"npx shadcn@latest add @ballmac/audio-player","summary":"Pass src (omit it for a silent demo), title, duration and optional chapters=[{ start, title }]. Control the position with time and onTimeChange to sync a transcript. variant='compact' is a one-row mini player.","whenToUse":["Podcast episodes, audio articles, voice notes and music previews","Syncing a transcript or chapter list to playback"],"whenNotToUse":["Video (use the native video element or video-dialog)"],"composesWith":["slider","segmented-control","scroll-area"],"dependencies":["lucide-react"],"registryDependencies":["shadcn:utils","slider","i18n"],"examples":["audio-player-demo","audio-player-compact"],"states":[],"preview":"https://ui.ballmac.com/preview/audio-player-demo"},{"name":"aurora-background","kind":"component","type":"registry:ui","title":"Aurora Background","description":"Soft, slowly drifting aurora light made of blurred token-colored glows with fine vertical curtains and an optional radial fade. Pure CSS layers, paused off-screen, still under reduced motion.","category":"backgrounds","tier":"free","tags":["aurora","gradient","glow","background","hero","decorative"],"version":"1.0.0","updated":"2026-09-29","url":"https://ui.ballmac.com/components/aurora-background","registryUrl":"https://ui.ballmac.com/r/aurora-background.json","install":"npx shadcn@latest add @ballmac/aurora-background","summary":"Place as the first child of a relative, overflow-hidden hero; it is absolute inset-0, aria-hidden and pointer-events-none. The light sits along the top edge and fades down, so headline text reads on the page background.","whenToUse":["Behind a hero headline or a launch announcement","Sign-in or waitlist pages that need atmosphere without imagery"],"whenNotToUse":["Behind dense content or data","Several stacked sections (use once per page, at the top)"],"composesWith":["text-reveal","shimmer-text","magnetic-button"],"dependencies":[],"registryDependencies":["shadcn:utils"],"examples":["aurora-background-demo","aurora-background-warm"],"states":[],"preview":"https://ui.ballmac.com/preview/aurora-background-demo"},{"name":"autonomy-dial","kind":"component","type":"registry:ui","title":"Autonomy Dial","description":"A stepped dial for how much an agent may do on its own, from suggest-only to full auto, with what it does alone and what it stops to ask about written out for every step.","category":"ai","tier":"free","tags":["ai","agents","permissions","autonomy","settings","control","safety"],"version":"1.0.0","updated":"2026-10-24","url":"https://ui.ballmac.com/components/autonomy-dial","registryUrl":"https://ui.ballmac.com/r/autonomy-dial.json","install":"npx shadcn@latest add @ballmac/autonomy-dial","summary":"levels is [{ value, label, summary, does: string[], asks: string[] }] from least to most autonomous (defaultAutonomyLevels has four). value / defaultValue / onValueChange. A native radio group, so arrow keys work; the panel under the dial says in words what the chosen level allows.","whenToUse":["Letting people decide how far an agent may go before asking","A settings row for an assistant's permissions"],"whenNotToUse":["A single yes or no approval; use approval-card","A numeric value; use slider"],"composesWith":["approval-card","settings-panel","agent-plan","tool-call-card"],"dependencies":["lucide-react"],"registryDependencies":["shadcn:utils","i18n"],"examples":["autonomy-dial-demo","autonomy-dial-custom"],"states":[],"statesNone":"A control with no data of its own: it shows the levels you pass in and reports the choice.","preview":"https://ui.ballmac.com/preview/autonomy-dial-demo"},{"name":"avatar-circles","kind":"component","type":"registry:ui","title":"Avatar Circles","description":"Overlapping avatars that spread on hover, lift individually with a name and role tooltip, show presence, fall back to initials and end in a +N count that can be a button.","category":"data-display","tier":"free","tags":["avatar","people","stack","presence","team"],"version":"1.0.0","updated":"2026-10-01","url":"https://ui.ballmac.com/components/avatar-circles","registryUrl":"https://ui.ballmac.com/r/avatar-circles.json","install":"npx shadcn@latest add @ballmac/avatar-circles","summary":". Each face is a link or button named with its person (and status). total adds the +N when only some are loaded.","whenToUse":["Showing who is in a project, document or room","Social proof next to a call to action"],"whenNotToUse":["A plain compact row (avatar-stack)","Large member tables (data-table)"],"composesWith":["avatar-stack","avatar","tooltip"],"dependencies":["motion@^12"],"registryDependencies":["shadcn:utils","i18n"],"examples":["avatar-circles-demo","avatar-circles-sizes"],"states":[],"preview":"https://ui.ballmac.com/preview/avatar-circles-demo"},{"name":"avatar-stack","kind":"component","type":"registry:ui","title":"Avatar Stack","description":"An accessible compact row of people with initials, image support, and an overflow count.","category":"data-display","tier":"free","tags":["people","avatar","team"],"version":"1.0.0","updated":"2026-09-30","url":"https://ui.ballmac.com/components/avatar-stack","registryUrl":"https://ui.ballmac.com/r/avatar-stack.json","install":"npx shadcn@latest add @ballmac/avatar-stack","summary":"An accessible compact row of people with initials, image support, and an overflow count.","whenToUse":["Show participants or collaborators in limited space"],"whenNotToUse":["Use Avatar for one person"],"composesWith":["avatar"],"dependencies":[],"registryDependencies":["shadcn:utils"],"examples":["avatar-stack-demo","avatar-stack-states"],"states":[],"preview":"https://ui.ballmac.com/preview/avatar-stack-demo"},{"name":"avatar","kind":"component","type":"registry:ui","title":"Avatar","description":"A Radix avatar with image and initials fallback, three sizes, an optional presence dot, and AvatarGroup for overlapping stacks with a +N overflow counter.","category":"primitives","tier":"free","tags":["avatar","user","profile","presence","radix"],"version":"1.0.0","updated":"2026-09-28","url":"https://ui.ballmac.com/components/avatar","registryUrl":"https://ui.ballmac.com/r/avatar.json","install":"npx shadcn@latest add @ballmac/avatar","summary":"User or team picture with initials fallback while the image loads or if it fails. Add status for presence, and wrap several in AvatarGroup with max to cap the visible count.","whenToUse":["Showing who owns, edited or is assigned to something","Account menus and comment threads","Stacks of collaborators or members with an overflow count"],"whenNotToUse":["Logos or product icons (use an img)","Large profile headers that need a custom shape"],"composesWith":["badge","tooltip","dialog"],"dependencies":["radix-ui","class-variance-authority"],"registryDependencies":["shadcn:utils","i18n"],"examples":["avatar-demo","avatar-group"],"states":[],"preview":"https://ui.ballmac.com/preview/avatar-demo"},{"name":"back-to-top","kind":"component","type":"registry:ui","title":"Back To Top","description":"A floating button that appears after scrolling, draws a progress ring, scrolls smoothly (instantly under reduced motion) and moves focus to the content.","category":"navigation","tier":"free","tags":["button","scroll","floating","progress"],"version":"1.0.0","updated":"2026-09-30","url":"https://ui.ballmac.com/components/back-to-top","registryUrl":"https://ui.ballmac.com/r/back-to-top.json","install":"npx shadcn@latest add @ballmac/back-to-top","summary":"Render once. threshold sets when it appears; container follows a scrollable element; focusTarget chooses where focus lands.","whenToUse":["Long pages, feeds and docs","Panels with a lot of scrolling"],"whenNotToUse":["Short pages","Infinite feeds where returning to the top loses work"],"composesWith":["scroll-progress","button"],"dependencies":["lucide-react","motion@^12"],"registryDependencies":["shadcn:utils","scroll","motion-presets","i18n"],"examples":["back-to-top-demo","back-to-top-states"],"states":[],"preview":"https://ui.ballmac.com/preview/back-to-top-demo"},{"name":"badge","kind":"component","type":"registry:ui","title":"Badge","description":"A small pill label in four variants with an optional status dot and success, warning and error tones. Style links with badgeVariants().","category":"primitives","tier":"free","tags":["badge","status","tag","label","pill"],"version":"1.0.0","updated":"2026-09-28","url":"https://ui.ballmac.com/components/badge","registryUrl":"https://ui.ballmac.com/r/badge.json","install":"npx shadcn@latest add @ballmac/badge","summary":"Short metadata or status label. Use variant for emphasis, status (neutral | success | warning | error) for state with a coloured dot, and badgeVariants() on an for a link.","whenToUse":["Status of a deployment, invoice or job","Counts, plan names and version tags","Small labels on cards and table rows"],"whenNotToUse":["Clickable filters that toggle (use a toggle or button)","Long text (it doesn't wrap)","Notifications that need attention (use an alert or toast)"],"composesWith":["avatar","button","switch"],"dependencies":["radix-ui","class-variance-authority"],"registryDependencies":["shadcn:utils"],"examples":["badge-demo","badge-status"],"states":[],"preview":"https://ui.ballmac.com/preview/badge-demo"},{"name":"banner","kind":"component","type":"registry:ui","title":"Banner","description":"A page-wide announcement with semantic tones, optional action, and controlled or local dismissal.","category":"feedback","tier":"free","tags":["announcement","status","dismissible"],"version":"1.0.0","updated":"2026-09-30","url":"https://ui.ballmac.com/components/banner","registryUrl":"https://ui.ballmac.com/r/banner.json","install":"npx shadcn@latest add @ballmac/banner","summary":"A page-wide announcement with semantic tones, optional action, and controlled or local dismissal.","whenToUse":["Announce a page-level update","Keep a persistent notice above page content"],"whenNotToUse":["Use alert for content scoped to one panel"],"composesWith":["alert","button"],"dependencies":["lucide-react"],"registryDependencies":["shadcn:utils","i18n"],"examples":["banner-demo","banner-states"],"states":[],"preview":"https://ui.ballmac.com/preview/banner-demo"},{"name":"beams-background","kind":"component","type":"registry:ui","title":"Beams Background","description":"Hairline rails with thin light beams rising along them and dissolving near the top, over a soft glow. Canvas, token colors, DPR aware, pauses off-screen, a still frame under reduced motion.","category":"backgrounds","tier":"free","tags":["beams","light","rails","canvas","background","hero","waitlist"],"version":"1.0.0","updated":"2026-09-29","url":"https://ui.ballmac.com/components/beams-background","registryUrl":"https://ui.ballmac.com/r/beams-background.json","install":"npx shadcn@latest add @ballmac/beams-background","summary":"Place as the first child of a relative, overflow-hidden section; it fills it (absolute inset-0, aria-hidden, pointer-events-none). Content goes after it; the rails fade out at the top and bottom edges.","whenToUse":["Waitlist, sign-up or launch sections with centered content","Hero backgrounds for developer tools, infrastructure or AI products"],"whenNotToUse":["Behind long text or tables","Pages that already have another animated background"],"composesWith":["input","button","shimmer-text","text-reveal"],"dependencies":[],"registryDependencies":["shadcn:utils","color"],"examples":["beams-background-demo","beams-background-falling"],"states":[],"preview":"https://ui.ballmac.com/preview/beams-background-demo"},{"name":"bento-grid","kind":"component","type":"registry:ui","title":"Bento Grid","description":"A responsive bento layout of feature cards that span columns and rows. Each BentoCard has a background visual slot, icon, title and description, and a link that slides up on hover or focus.","category":"layout","tier":"free","tags":["bento","grid","features","landing","cards","layout"],"version":"1.0.1","updated":"2026-10-11","url":"https://ui.ballmac.com/components/bento-grid","registryUrl":"https://ui.ballmac.com/r/bento-grid.json","install":"npx shadcn@latest add @ballmac/bento-grid","summary":" with . The grid responds to its own width (container queries): one column below 36rem. The background slot takes any decorative node, such as animated-grid, marquee or number-ticker visuals.","whenToUse":["Landing-page feature sections with 4–7 features of different weight","Product overviews where each tile shows a small live visual","Dashboard home pages with shortcuts"],"whenNotToUse":["Uniform lists of equal items (use a plain grid of cards)","Long text content; cards hold one or two lines"],"composesWith":["animated-grid","marquee","number-ticker","border-beam"],"dependencies":["lucide-react"],"registryDependencies":["shadcn:utils","media","media-image"],"examples":["bento-grid-demo","bento-grid-features"],"states":[],"preview":"https://ui.ballmac.com/preview/bento-grid-demo"},{"name":"billing-card","kind":"component","type":"registry:ui","title":"Billing Card","description":"A subscription summary with plan and price, status, next charge, payment method, seat usage and recent invoices, including failed-payment and trial states.","category":"saas","tier":"free","tags":["billing","subscription","invoices","plan"],"version":"1.0.0","updated":"2026-09-30","url":"https://ui.ballmac.com/components/billing-card","registryUrl":"https://ui.ballmac.com/r/billing-card.json","install":"npx shadcn@latest add @ballmac/billing-card","summary":"plan {name,price,interval,status,renewsOn,seats}, paymentMethod, invoices[], and onChangePlan / onUpdatePayment / onCancel. Dates are ISO strings formatted in UTC.","whenToUse":["Account billing pages","Showing subscription state in settings"],"whenNotToUse":["Choosing a plan; use plan-selector","A line-item invoice table; use table"],"composesWith":["usage-meter","plan-selector","settings-panel"],"dependencies":["lucide-react"],"registryDependencies":["shadcn:utils","i18n"],"examples":["billing-card-demo","billing-card-states"],"states":[],"preview":"https://ui.ballmac.com/preview/billing-card-demo"},{"name":"about-1","kind":"block","type":"registry:block","title":"About 1: company story","description":"A company story page: a large two-tone statement and a wide picture, numbers that count up, the story beside a pull quote, value cards that light up under the pointer, a milestone timeline and a closing call to action.","category":"blocks","blockCategory":"about","tier":"free","tags":["about","company","story","mission","values","timeline","stats","culture","brand","editorial"],"version":"1.0.0","updated":"2026-10-18","url":"https://ui.ballmac.com/blocks/about-1","registryUrl":"https://ui.ballmac.com/r/about-1.json","install":"npx shadcn@latest add @ballmac/about-1","summary":"An About page. . Every part is optional: pass [] for stats, values or milestones, or null for quote or cta, and that section disappears. Without media it draws art from the headline.","whenToUse":["The About or Our story page of a company, studio or product","A manifesto page with numbers, values and history"],"whenNotToUse":["A page of people (use team-1)","A job list (use careers-1)","A landing page (use the hero blocks)"],"composesWith":["header-2","footer-2","team-1","careers-1","gallery-1"],"dependencies":["lucide-react"],"registryDependencies":["shadcn:utils","blur-fade","button","cover-art","media","number-ticker","spotlight-card"],"examples":["about-1-demo","about-1-short"],"states":[],"statesNone":"Static content: nothing to load, submit or fail.","preview":"https://ui.ballmac.com/preview/about-1-demo"},{"name":"access-1","kind":"block","type":"registry:block","title":"Access 1: access review","description":"A periodic access review: each person's role and last use, Keep, Reduce or Remove with lower roles only, people idle for months flagged in words, a keep-everyone-active shortcut, progress, and a confirmation before anyone loses access.","category":"blocks","blockCategory":"access","tier":"free","tags":["access review","permissions","roles","security","compliance","admin","least privilege"],"version":"1.0.0","updated":"2026-10-24","url":"https://ui.ballmac.com/blocks/access-1","registryUrl":"https://ui.ballmac.com/r/access-1.json","install":"npx shadcn@latest add @ballmac/access-1","summary":"A quarterly access review. Promise} />. Each person gets Keep, Reduce (to a lower role) or Remove; undecided people stay as they are. Submit is off until everyone has a decision and asks first when anyone will be removed.","whenToUse":["A workspace admin's quarterly check of who has access","A compliance task that needs a record of every keep, reduce and remove"],"whenNotToUse":["Inviting or changing one person's role; use settings or team blocks","A log of past changes; use audit-1"],"composesWith":["audit-1","settings-1","invite-1","app-shell-1"],"dependencies":["lucide-react"],"registryDependencies":["shadcn:utils","alert-dialog","button","skeleton","state-view","return-focus"],"examples":["access-1-demo","access-1-flagged","access-1-loading","access-1-empty","access-1-error"],"states":[{"id":"loading","title":"Loading","example":"access-1-loading","trigger":"state=\"loading\"","note":"Skeleton cards under the real heading, announced as loading.","preview":"https://ui.ballmac.com/preview/access-1-loading"},{"id":"empty","title":"Nobody to review","example":"access-1-empty","trigger":"state=\"empty\"","note":"Says nobody is to review; emptyState sets the copy.","preview":"https://ui.ballmac.com/preview/access-1-empty"},{"id":"error","title":"Could not load","example":"access-1-error","trigger":"state=\"error\"","note":"An alert saying no decisions were lost, with Try again (onRetry).","preview":"https://ui.ballmac.com/preview/access-1-error"}],"preview":"https://ui.ballmac.com/preview/access-1-demo"},{"name":"agent-1","kind":"block","type":"registry:block","title":"Agent 1: live agent run","description":"One AI agent run as it happens: the task and status, the plan beside it, every note, tool call and approval request in order, approvals that pause the run, the result with copy, and a follow-up box.","category":"blocks","blockCategory":"agents","tier":"free","tags":["ai","agent","run","tool calls","approval","human in the loop","plan","trace","autonomous"],"version":"1.0.0","updated":"2026-10-17","url":"https://ui.ballmac.com/blocks/agent-1","registryUrl":"https://ui.ballmac.com/r/agent-1.json","install":"npx shadcn@latest add @ballmac/agent-1","summary":"An agent run view. …} onDeny onStop onRunAgain onFollowUp />. Map your agent loop's stream (AI SDK tool calls, LangGraph interrupts) onto events.","whenToUse":["Watching an autonomous agent work and approving its risky steps","The detail page of a background agent task"],"whenNotToUse":["A chat conversation (use ai-chat-1 or ai-chat-2)","A list of many runs (use agent-3)","A queue of approvals from many agents (use agent-2)"],"composesWith":["agent-2","agent-3","app-shell-1"],"dependencies":["lucide-react"],"registryDependencies":["shadcn:utils","agent-plan","approval-card","button","skeleton","state-view","tool-call-card"],"examples":["agent-1-demo","agent-1-done","agent-1-loading","agent-1-empty","agent-1-error"],"states":[{"id":"loading","title":"Loading","example":"agent-1-loading","trigger":"state=\"loading\"","note":"A skeleton of the plan and the activity under the real header.","preview":"https://ui.ballmac.com/preview/agent-1-loading"},{"id":"empty","title":"No run yet","example":"agent-1-empty","trigger":"state=\"empty\"","note":"Explains that the plan and progress will appear; emptyState can add a Start button.","preview":"https://ui.ballmac.com/preview/agent-1-empty"},{"id":"error","title":"Could not load","example":"agent-1-error","trigger":"state=\"error\"","note":"An alert with Try again (onRetry).","preview":"https://ui.ballmac.com/preview/agent-1-error"}],"preview":"https://ui.ballmac.com/preview/agent-1-demo"},{"name":"agent-10","kind":"block","type":"registry:block","title":"Agent 10: console with handoff","description":"An agent console: the conversation with each tool call as a step you can open to see what was asked and what came back, Stop while it works, Enter to send, and a clear Take over and Hand back so a person is never mistaken for the agent.","category":"blocks","blockCategory":"agents","tier":"free","tags":["ai","agent","console","chat","handoff","human in the loop","tool calls","support","transcript"],"version":"1.0.0","updated":"2026-10-24","url":"https://ui.ballmac.com/blocks/agent-10","registryUrl":"https://ui.ballmac.com/r/agent-10.json","install":"npx shadcn@latest add @ballmac/agent-10","summary":"Agent console. Promise} onStop={() => void} onHandoff={(takeOver: boolean) => Promise} />. A person's reply is labelled '(a person)' and framed differently. While a person is active the agent is shown as paused.","whenToUse":["Operating or supervising a support or task agent","Any transcript where tool calls and a human takeover matter"],"whenNotToUse":["A public chat widget; use ai-chat-1","Reviewing finished runs; use agent-3"],"composesWith":["agent-1","agent-2","agent-9","escalation-card"],"dependencies":["lucide-react"],"registryDependencies":["shadcn:utils","button","skeleton","state-view"],"examples":["agent-10-demo","agent-10-working","agent-10-human","agent-10-loading","agent-10-empty","agent-10-error"],"states":[{"id":"loading","title":"Loading","example":"agent-10-loading","trigger":"state=\"loading\"","note":"Skeleton bubbles under the real heading, announced as loading.","preview":"https://ui.ballmac.com/preview/agent-10-loading"},{"id":"empty","title":"No messages yet","example":"agent-10-empty","trigger":"state=\"empty\"","note":"Says there are no messages yet; emptyState sets the copy.","preview":"https://ui.ballmac.com/preview/agent-10-empty"},{"id":"error","title":"Could not load","example":"agent-10-error","trigger":"state=\"error\"","note":"An alert saying nothing was sent, with Try again (onRetry). A message that fails to send stays in the box and says why.","preview":"https://ui.ballmac.com/preview/agent-10-error"}],"preview":"https://ui.ballmac.com/preview/agent-10-demo"},{"name":"agent-2","kind":"block","type":"registry:block","title":"Agent 2: approvals inbox","description":"One inbox for every action AI agents are waiting on: requests with their risk, the full request beside the list, Approve and Deny with A and D, J and K to move, and approve all low-risk requests at once.","category":"blocks","blockCategory":"agents","tier":"free","tags":["ai","agent","approvals","human in the loop","inbox","queue","review","keyboard"],"version":"1.0.0","updated":"2026-10-17","url":"https://ui.ballmac.com/blocks/agent-2","registryUrl":"https://ui.ballmac.com/r/agent-2.json","install":"npx shadcn@latest add @ballmac/agent-2","summary":"An approvals queue for many agents. …} onDeny={(id) => …} />. After a decision the next waiting request is selected, so a queue clears from the keyboard.","whenToUse":["A central place where people approve what agents want to do (refunds, emails, deploys, data changes)","Human-in-the-loop review for AI SDK tool calls that need approval or LangGraph interrupts"],"whenNotToUse":["One approval inside a single run (use agent-1 or approval-card)","Approving documents or expenses between people"],"composesWith":["agent-1","agent-3","app-shell-1"],"dependencies":["lucide-react"],"registryDependencies":["shadcn:utils","approval-card","button","kbd","segmented-control","skeleton","state-view"],"examples":["agent-2-demo","agent-2-loading","agent-2-empty","agent-2-error"],"states":[{"id":"loading","title":"Loading","example":"agent-2-loading","trigger":"state=\"loading\"","note":"Skeleton requests and a detail panel under the real heading; the filter is disabled.","preview":"https://ui.ballmac.com/preview/agent-2-loading"},{"id":"empty","title":"All caught up","example":"agent-2-empty","trigger":"state=\"empty\" (or no waiting requests)","note":"Says nothing is waiting. Shown by itself once the last request is decided.","preview":"https://ui.ballmac.com/preview/agent-2-empty"},{"id":"error","title":"Could not load","example":"agent-2-error","trigger":"state=\"error\"","note":"An alert with Try again (onRetry).","preview":"https://ui.ballmac.com/preview/agent-2-error"}],"preview":"https://ui.ballmac.com/preview/agent-2-demo"},{"name":"agent-3","kind":"block","type":"registry:block","title":"Agent 3: runs and traces","description":"AI agent runs with status, time, tokens and cost, filtered and searched, and a trace waterfall for the selected run: model calls, tool calls and retrieval, each span with input, output and error.","category":"blocks","blockCategory":"agents","tier":"free","tags":["ai","agent","observability","trace","waterfall","spans","runs","llm","tokens","cost","debugging"],"version":"1.0.0","updated":"2026-10-17","url":"https://ui.ballmac.com/blocks/agent-3","registryUrl":"https://ui.ballmac.com/r/agent-3.json","install":"npx shadcn@latest add @ballmac/agent-3","summary":"Agent observability. . Map OpenTelemetry GenAI spans, Langfuse or AI SDK telemetry onto spans; a failed span is selected first.","whenToUse":["Debugging what an agent did and where time and tokens went","An admin page of recent agent runs"],"whenNotToUse":["Watching one run live (use agent-1)","General request tracing for web services (use log-stream or a data-table)"],"composesWith":["agent-1","agent-2","app-shell-1"],"dependencies":["lucide-react"],"registryDependencies":["shadcn:utils","json-viewer","segmented-control","skeleton","state-view"],"examples":["agent-3-demo","agent-3-failed","agent-3-loading","agent-3-empty","agent-3-error"],"states":[{"id":"loading","title":"Loading","example":"agent-3-loading","trigger":"state=\"loading\"","note":"A skeleton table and trace; search and the status filter are disabled.","preview":"https://ui.ballmac.com/preview/agent-3-loading"},{"id":"empty","title":"No runs yet","example":"agent-3-empty","trigger":"state=\"empty\" (or runs={[]})","note":"Explains that runs and traces appear once agents work; a filter with no matches says so inside the table instead.","preview":"https://ui.ballmac.com/preview/agent-3-empty"},{"id":"error","title":"Could not load","example":"agent-3-error","trigger":"state=\"error\"","note":"An alert with Try again (onRetry).","preview":"https://ui.ballmac.com/preview/agent-3-error"}],"preview":"https://ui.ballmac.com/preview/agent-3-demo"},{"name":"agent-4","kind":"block","type":"registry:block","title":"Agent 4: prompt playground with model compare","description":"A prompt playground that runs one prompt on two models side by side: system prompt, {{variables}} that become fields, Run with ⌘Enter, each answer with time, tokens and cost, ratings and Pick this one.","category":"blocks","blockCategory":"agents","tier":"free","tags":["ai","llm","prompt","playground","compare","models","evaluation","a/b","variables","prompt engineering"],"version":"1.0.0","updated":"2026-10-17","url":"https://ui.ballmac.com/blocks/agent-4","registryUrl":"https://ui.ballmac.com/r/agent-4.json","install":"npx shadcn@latest add @ballmac/agent-4","summary":"A side-by-side prompt playground. ({ text, latencyMs, tokens: { input, output }, cost })} onRate onPick />. Variables are detected from {{name}} in the prompt and must be filled before running.","whenToUse":["Choosing a model or prompt for a feature by comparing real answers","An internal tool for prompt iteration with ratings saved for evaluation"],"whenNotToUse":["A chat with one model (use ai-chat-1)","Watching an agent run (use agent-1)"],"composesWith":["agent-3","app-shell-1"],"dependencies":["lucide-react"],"registryDependencies":["shadcn:utils","button","kbd","model-picker","textarea","state-view","use-resource"],"examples":["agent-4-demo","agent-4-fresh","agent-4-running","agent-4-error"],"states":[{"id":"submitting","title":"Running","example":"agent-4-running","trigger":"state=\"submitting\"","note":"Both sides show Running…, are marked busy, and Run and the model pickers are disabled.","preview":"https://ui.ballmac.com/preview/agent-4-running"},{"id":"error","title":"A model did not answer","example":"agent-4-error","trigger":"state=\"error\" (or onRun throws)","note":"The side shows an alert with the reason; errorState sets the copy. A thrown Error's message is shown on that side only.","preview":"https://ui.ballmac.com/preview/agent-4-error"}],"preview":"https://ui.ballmac.com/preview/agent-4-demo"},{"name":"agent-5","kind":"block","type":"registry:block","title":"Agent 5: eval results","description":"Evaluation results for a prompt or model change: a verdict that calls out regressions, each metric against the baseline with which way is better, cases filtered to regressions or improvements, and both answers side by side or as a diff.","category":"blocks","blockCategory":"agents","tier":"free","tags":["ai","llm","evals","evaluation","regression","testing","prompt","model","quality","comparison"],"version":"1.0.0","updated":"2026-10-17","url":"https://ui.ballmac.com/blocks/agent-5","registryUrl":"https://ui.ballmac.com/r/agent-5.json","install":"npx shadcn@latest add @ballmac/agent-5","summary":"An evals comparison page. . A regression is a case that passed on the baseline and fails on the candidate; the first one is selected.","whenToUse":["Deciding whether a prompt or model change can ship","Reviewing an eval suite's results in an internal AI tool"],"whenNotToUse":["Trying prompts by hand (use agent-4)","Tracing one run (use agent-3)"],"composesWith":["agent-3","agent-4","app-shell-1"],"dependencies":["lucide-react"],"registryDependencies":["shadcn:utils","button","diff-viewer","segmented-control","skeleton","state-view"],"examples":["agent-5-demo","agent-5-loading","agent-5-empty","agent-5-error"],"states":[{"id":"loading","title":"Loading","example":"agent-5-loading","trigger":"state=\"loading\"","note":"Skeleton metric cards and a case list under the real heading.","preview":"https://ui.ballmac.com/preview/agent-5-loading"},{"id":"empty","title":"No results yet","example":"agent-5-empty","trigger":"state=\"empty\" (or cases={[]})","note":"Asks to run the suite; emptyState can add a Run button.","preview":"https://ui.ballmac.com/preview/agent-5-empty"},{"id":"error","title":"Could not load","example":"agent-5-error","trigger":"state=\"error\"","note":"An alert with Try again (onRetry).","preview":"https://ui.ballmac.com/preview/agent-5-error"}],"preview":"https://ui.ballmac.com/preview/agent-5-demo"},{"name":"agent-6","kind":"block","type":"registry:block","title":"Agent 6: assistant memory","description":"What an AI assistant remembers about someone: a ring splitting memory by kind, a switch to pause it, each memory with its source and use count, edited in place, pinned or forgotten with undo, and Forget everything.","category":"blocks","blockCategory":"agents","tier":"free","tags":["ai","agent","memory","personalization","privacy","assistant","context","preferences","controls"],"version":"1.0.0","updated":"2026-10-17","url":"https://ui.ballmac.com/blocks/agent-6","registryUrl":"https://ui.ballmac.com/r/agent-6.json","install":"npx shadcn@latest add @ballmac/agent-6","summary":"A memory control page for an AI assistant. …} onPin onForget onRestore onForgetAll />. Forgetting calls onForget at once and offers Undo for seven seconds (onRestore); throw from onEdit to keep the old text and show the error.","whenToUse":["Giving people control over what an AI assistant or agent remembers (a trust and privacy requirement in many products)","A settings page for personalization"],"whenNotToUse":["A knowledge base the assistant searches (use sources-list)","Chat history (use ai-chat-1)"],"composesWith":["settings-3","agent-1","agent-3","app-shell-1"],"dependencies":["lucide-react"],"registryDependencies":["shadcn:utils","alert-dialog","blur-fade","button","circular-progress","segmented-control","skeleton","state-view","switch","textarea","return-focus"],"examples":["agent-6-demo","agent-6-editing","agent-6-paused","agent-6-loading","agent-6-empty","agent-6-error"],"states":[{"id":"loading","title":"Loading","example":"agent-6-loading","trigger":"state=\"loading\"","note":"A skeleton of the summary and memory cards under the real heading.","preview":"https://ui.ballmac.com/preview/agent-6-loading"},{"id":"empty","title":"Nothing remembered","example":"agent-6-empty","trigger":"state=\"empty\" (or memories={[]})","note":"Explains how the assistant learns and that the person decides what stays; emptyState sets the copy.","preview":"https://ui.ballmac.com/preview/agent-6-empty"},{"id":"error","title":"Could not load","example":"agent-6-error","trigger":"state=\"error\"","note":"An alert saying nothing was changed, with Try again (onRetry).","preview":"https://ui.ballmac.com/preview/agent-6-error"}],"preview":"https://ui.ballmac.com/preview/agent-6-demo"},{"name":"agent-7","kind":"block","type":"registry:block","title":"Agent 7: agent builder","description":"An agent builder: instructions and model, each tool set to off, ask first or allowed, the knowledge it may read, guardrails, and a live preview that changes with every setting. Publishing shows submitting, success and error.","category":"blocks","blockCategory":"agents","tier":"free","tags":["ai","agent","builder","no-code","tools","permissions","knowledge","guardrails","instructions","publish","preview"],"version":"1.0.0","updated":"2026-10-17","url":"https://ui.ballmac.com/blocks/agent-7","registryUrl":"https://ui.ballmac.com/r/agent-7.json","install":"npx shadcn@latest add @ballmac/agent-7","summary":"An agent configuration page. …} onAddSource onRemoveSource />. The preview shows the first enabled tool: behind an approval card when set to Ask first, as a finished tool call when Allowed.","whenToUse":["Letting people create or edit an AI agent in a no-code way","An internal admin page for configuring an agent's tools, knowledge and limits"],"whenNotToUse":["Chatting with an agent (use ai-chat-1)","Approving an agent's actions as it works (use agent-1 or agent-2)","Choosing a model only (use model-picker)"],"composesWith":["agent-2","agent-3","agent-6","app-shell-1"],"dependencies":["lucide-react"],"registryDependencies":["shadcn:utils","approval-card","badge","blur-fade","button","cover-art","model-picker","segmented-control","skeleton","state-view","switch","textarea","tool-call-card","use-resource"],"examples":["agent-7-demo","agent-7-bare","agent-7-loading","agent-7-publishing","agent-7-published","agent-7-error"],"states":[{"id":"loading","title":"Loading","example":"agent-7-loading","trigger":"state=\"loading\"","note":"A skeleton of the settings and the preview under the real header.","preview":"https://ui.ballmac.com/preview/agent-7-loading"},{"id":"submitting","title":"Publishing","example":"agent-7-publishing","trigger":"state=\"submitting\"","note":"Publish shows a spinner and \"Publishing…\" and is disabled; the status reads Publishing…","preview":"https://ui.ballmac.com/preview/agent-7-publishing"},{"id":"success","title":"Published","example":"agent-7-published","trigger":"state=\"success\"","note":"The button and status say Published until something changes again.","preview":"https://ui.ballmac.com/preview/agent-7-published"},{"id":"error","title":"Could not publish","example":"agent-7-error","trigger":"state=\"error\"","note":"An alert says the changes are kept and why it failed (errorState sets the copy or throw an Error from onPublish).","preview":"https://ui.ballmac.com/preview/agent-7-error"}],"preview":"https://ui.ballmac.com/preview/agent-7-demo"},{"name":"agent-8","kind":"block","type":"registry:block","title":"Agent 8: knowledge manager","description":"A knowledge manager for an AI agent: a health bar across its sources, each source with sync progress or failure and a retry, a switch for whether the agent may use it, and a panel showing which passages come back for a question.","category":"blocks","blockCategory":"agents","tier":"free","tags":["ai","agent","knowledge","rag","sources","retrieval","documents","sync","training data","knowledge base"],"version":"1.0.0","updated":"2026-10-17","url":"https://ui.ballmac.com/blocks/agent-8","registryUrl":"https://ui.ballmac.com/r/agent-8.json","install":"npx shadcn@latest add @ballmac/agent-8","summary":"An agent knowledge page. …} onResync onRemove onToggle onAsk={async (question, sources) => ({ passages: [{ sourceId, text, score }], answer })} defaultQuestion />. The test panel shows retrieval, not a generated answer; onAsk returns your vector search's top passages. Without onAsk it searches each source's excerpts.","whenToUse":["Managing what a support, docs or internal agent may read (RAG sources)","Checking that a question is covered before shipping an agent"],"whenNotToUse":["Showing the sources an answer used (use sources-list and citation)","Configuring tools and instructions (use agent-7)"],"composesWith":["agent-7","agent-6","agent-3","app-shell-1"],"dependencies":["lucide-react"],"registryDependencies":["shadcn:utils","alert-dialog","badge","blur-fade","button","dropdown-menu","match-highlight","skeleton","state-view","switch","return-focus"],"examples":["agent-8-demo","agent-8-no-match","agent-8-empty","agent-8-loading","agent-8-error"],"states":[{"id":"loading","title":"Loading","example":"agent-8-loading","trigger":"state=\"loading\"","note":"A skeleton of the summary, the source cards and the test panel under the real heading.","preview":"https://ui.ballmac.com/preview/agent-8-loading"},{"id":"empty","title":"No sources yet","example":"agent-8-empty","trigger":"state=\"empty\" (or sources={[]})","note":"Explains what knowledge is and offers the three ways to add it as large buttons (website, files, pasted text); emptyState sets the copy.","preview":"https://ui.ballmac.com/preview/agent-8-empty"},{"id":"error","title":"Could not load","example":"agent-8-error","trigger":"state=\"error\"","note":"An alert saying nothing was changed, with Try again (onRetry). A single source that fails to sync shows its reason and Retry on its own card.","preview":"https://ui.ballmac.com/preview/agent-8-error"}],"preview":"https://ui.ballmac.com/preview/agent-8-demo"},{"name":"agent-9","kind":"block","type":"registry:block","title":"Agent 9: autonomy and limits","description":"How much an AI agent may do alone: a plain-words autonomy level, spend caps per run and per day, a step limit and the tools it may use, with a warning for risky mixes and a save bar that holds edits until saved.","category":"blocks","blockCategory":"agents","tier":"free","tags":["ai","agent","autonomy","guardrails","budget","limits","permissions","tools","settings","safety"],"version":"1.0.0","updated":"2026-10-24","url":"https://ui.ballmac.com/blocks/agent-9","registryUrl":"https://ui.ballmac.com/r/agent-9.json","install":"npx shadcn@latest add @ballmac/agent-9","summary":"Agent autonomy and limits. Promise} />. Edits are held until Save; Discard puts them back. A run limit above the daily limit, or a bad step count, blocks saving and says why. Acting on its own with tools that write shows a plain-words warning.","whenToUse":["Where an owner decides how much an agent may do without asking","Spend caps, step limits and tool permissions in one place"],"whenNotToUse":["Choosing the model and prompt; use agent-7","Approving one action; use agent-2"],"composesWith":["agent-2","agent-7","agent-8","cost-1"],"dependencies":["lucide-react"],"registryDependencies":["shadcn:utils","button","skeleton","state-view","switch"],"examples":["agent-9-demo","agent-9-free","agent-9-loading","agent-9-empty","agent-9-error"],"states":[{"id":"loading","title":"Loading","example":"agent-9-loading","trigger":"state=\"loading\"","note":"Skeleton cards under the real heading, announced as loading.","preview":"https://ui.ballmac.com/preview/agent-9-loading"},{"id":"empty","title":"No tools connected","example":"agent-9-empty","trigger":"state=\"empty\"","note":"Says no tools are connected; emptyState sets the copy.","preview":"https://ui.ballmac.com/preview/agent-9-empty"},{"id":"error","title":"Could not load","example":"agent-9-error","trigger":"state=\"error\"","note":"An alert saying nothing was changed, with Try again (onRetry). A save that fails keeps every edit and says why.","preview":"https://ui.ballmac.com/preview/agent-9-error"}],"preview":"https://ui.ballmac.com/preview/agent-9-demo"},{"name":"ai-chat-1","kind":"block","type":"registry:block","title":"AI Chat 1: full chat app pane","description":"A complete assistant screen: collapsible conversation sidebar, model picker, messages with reasoning and tool calls, streaming replies, copy and regenerate, and a prompt with attachments.","category":"blocks","blockCategory":"ai-chat","tier":"free","tags":["ai","chat","assistant","agent","copilot","app"],"version":"1.1.0","updated":"2026-10-11","url":"https://ui.ballmac.com/blocks/ai-chat-1","registryUrl":"https://ui.ballmac.com/r/ai-chat-1.json","install":"npx shadcn@latest add @ballmac/ai-chat-1","summary":"A ready-made chat screen driven entirely by props. Map your chat state (for example the Vercel AI SDK's useChat messages) to `messages`, call your API in `onSubmit`, and pass `streaming` while a reply arrives.","whenToUse":["Assistant, copilot or agent products","Internal AI tools that need history and model choice"],"whenNotToUse":["A small embedded chat widget (compose ai-chat, ai-message and prompt-input instead)"],"composesWith":["hero-3","ai-chat","prompt-input"],"dependencies":["lucide-react"],"registryDependencies":["shadcn:utils","ai-chat","ai-message","button","prompt-input","reasoning-disclosure","select","streaming-text","tool-call-card","state-view","skeleton"],"examples":["ai-chat-1-demo","ai-chat-1-loading","ai-chat-1-error","ai-chat-1-new-chat"],"states":[{"id":"loading","title":"Loading","example":"ai-chat-1-loading","trigger":"state=\"loading\"","note":"The conversation list and prompt stay; the thread shows placeholder messages, announced as loading, and the prompt is disabled.","preview":"https://ui.ballmac.com/preview/ai-chat-1-loading"},{"id":"empty","title":"New chat","example":"ai-chat-1-new-chat","trigger":"state=\"empty\"","note":"A welcome in the thread. emptyState sets the title, description and an action.","preview":"https://ui.ballmac.com/preview/ai-chat-1-new-chat"},{"id":"error","title":"Could not load","example":"ai-chat-1-error","trigger":"state=\"error\"","note":"The messages stay and a failed-reply row sits where the reply would be, with Try again (onRetry), announced as an alert.","preview":"https://ui.ballmac.com/preview/ai-chat-1-error"}],"preview":"https://ui.ballmac.com/preview/ai-chat-1-demo"},{"name":"ai-chat-2","kind":"block","type":"registry:block","title":"AI Chat 2: conversation with artifact panel","description":"A chat that builds things: conversation list, streaming replies, suggestion chips and a side panel with Preview and Code tabs, version history, copy and download. The panel overlays the chat on narrow screens.","category":"blocks","blockCategory":"ai-chat","tier":"free","tags":["ai chat","artifact","assistant","streaming","code","side panel","versions"],"version":"1.1.0","updated":"2026-10-11","url":"https://ui.ballmac.com/blocks/ai-chat-2","registryUrl":"https://ui.ballmac.com/r/ai-chat-2.json","install":"npx shadcn@latest add @ballmac/ai-chat-2","summary":"An assistant UI that produces artifacts. Pass versions=[{ code, preview, note }], defaultMessages, suggestions and onSend(prompt) returning { reply, artifact? } (the 1-based version the reply moves to). Without onSend a built-in script lets you try the whole flow.","whenToUse":["Assistants that write code, documents or designs","Anywhere results deserve their own panel with versions"],"whenNotToUse":["A plain chat pane (use ai-chat-1)"],"composesWith":["app-shell-1","ai-chat-1","mail-1"],"dependencies":["lucide-react"],"registryDependencies":["shadcn:utils","ai-chat","ai-message","artifact-panel","button","prompt-input","streaming-text","state-view","skeleton"],"examples":["ai-chat-2-demo","ai-chat-2-blank","ai-chat-2-loading","ai-chat-2-error","ai-chat-2-new-chat"],"states":[{"id":"loading","title":"Loading","example":"ai-chat-2-loading","trigger":"state=\"loading\"","note":"The conversation list and prompt stay; the thread shows placeholder messages, announced as loading, and the prompt is disabled.","preview":"https://ui.ballmac.com/preview/ai-chat-2-loading"},{"id":"empty","title":"New chat","example":"ai-chat-2-new-chat","trigger":"state=\"empty\"","note":"A welcome in the thread. emptyState sets the title, description and an action.","preview":"https://ui.ballmac.com/preview/ai-chat-2-new-chat"},{"id":"error","title":"Could not load","example":"ai-chat-2-error","trigger":"state=\"error\"","note":"The messages stay and a failed-reply row sits where the reply would be, with Try again (onRetry), announced as an alert.","preview":"https://ui.ballmac.com/preview/ai-chat-2-error"}],"preview":"https://ui.ballmac.com/preview/ai-chat-2-demo"},{"name":"alerts-1","kind":"block","type":"registry:block","title":"Alerts 1: alert rules","description":"The alert rules of a monitoring setup: what each watches, severity, where it notifies, and firing, muted or fine in words, firing first, switch off, mute for an hour, four hours or a day, send a test, all undone with the reason if it fails.","category":"blocks","blockCategory":"alerts","tier":"free","tags":["alerts","monitoring","rules","pager","on-call","notifications","observability","sre"],"version":"1.0.0","updated":"2026-10-24","url":"https://ui.ballmac.com/blocks/alerts-1","registryUrl":"https://ui.ballmac.com/r/alerts-1.json","install":"npx shadcn@latest add @ballmac/alerts-1","summary":"Alert rules. Promise} onMute={(rule, hours) => Promise /* hours 0 means unmute */} onTest={(rule) => Promise} />. Firing rules are listed first. Each action updates the screen at once and is undone if the handler rejects.","whenToUse":["The settings page of a monitoring or alerting tool","An on-call overview of what is firing and what is muted"],"whenNotToUse":["Notification preferences for end users; use settings-1","A feed of past alerts; use audit-1 or log-stream"],"composesWith":["oncall-1","incident-1","runbook-1","slo-1"],"dependencies":["lucide-react"],"registryDependencies":["shadcn:utils","button","skeleton","state-view","switch"],"examples":["alerts-1-demo","alerts-1-quiet","alerts-1-loading","alerts-1-empty","alerts-1-error"],"states":[{"id":"loading","title":"Loading","example":"alerts-1-loading","trigger":"state=\"loading\"","note":"Skeleton rows under the real heading, announced as loading.","preview":"https://ui.ballmac.com/preview/alerts-1-loading"},{"id":"empty","title":"No alert rules yet","example":"alerts-1-empty","trigger":"state=\"empty\"","note":"Says no alert rules yet; emptyState sets the copy. A filter with no match says so.","preview":"https://ui.ballmac.com/preview/alerts-1-empty"},{"id":"error","title":"Could not load","example":"alerts-1-error","trigger":"state=\"error\"","note":"An alert saying nothing was changed or muted, with Try again (onRetry). A change that fails goes back and says why.","preview":"https://ui.ballmac.com/preview/alerts-1-error"}],"preview":"https://ui.ballmac.com/preview/alerts-1-demo"},{"name":"api-1","kind":"block","type":"registry:block","title":"API 1: request explorer","description":"An API explorer: a method, an address, headers and a JSON body, then the answer with its status in words, time and size and the body as a tree; a broken body is caught before sending, with history and Copy as cURL.","category":"blocks","blockCategory":"api","tier":"free","tags":["api","request","http","rest","postman","playground","curl","developer","docs","explorer","json"],"version":"1.0.0","updated":"2026-10-18","url":"https://ui.ballmac.com/blocks/api-1","registryUrl":"https://ui.ballmac.com/r/api-1.json","install":"npx shadcn@latest add @ballmac/api-1","summary":"An API explorer. Promise<{ status, statusText, ms, headers, body }>} />. Send is disabled while the address is not a full https URL or a body is not valid JSON, and says why. Every send is added to a history of six. Copy as cURL builds the command from the current request. Without onSend a built-in demo API for /v1/users answers (401 without an Authorization header, 200, 201, 404, 422).","whenToUse":["API documentation with a try-it panel","A developer dashboard where customers test their keys"],"whenNotToUse":["Showing one endpoint's reference (use api-endpoint)","Watching live traffic (use log-stream)"],"composesWith":["dev-1","webhooks-1","app-shell-1"],"dependencies":["lucide-react"],"registryDependencies":["shadcn:utils","button","copy-button","input","json-viewer","select","skeleton","state-view","textarea"],"examples":["api-1-demo","api-1-created","api-1-notfound","api-1-loading","api-1-error"],"states":[{"id":"loading","title":"Loading","example":"api-1-loading","trigger":"state=\"loading\"","note":"A skeleton request bar and panel under the real heading, announced as loading. While a request is in flight the response panel shows a skeleton and the page is marked busy.","preview":"https://ui.ballmac.com/preview/api-1-loading"},{"id":"error","title":"Could not load","example":"api-1-error","trigger":"state=\"error\"","note":"An alert with Try again (onRetry). A request that gets no answer shows 'No response' with the reason in the response panel.","preview":"https://ui.ballmac.com/preview/api-1-error"}],"preview":"https://ui.ballmac.com/preview/api-1-demo"},{"name":"app-shell-1","kind":"block","type":"registry:block","title":"App Shell 1: collapsible sidebar with command menu","description":"A product frame: workspace switcher, grouped navigation with badges that collapses to an icon rail, top bar with search, notifications and a ⌘K command menu, and a scrolling page slot. A drawer on phones.","category":"blocks","blockCategory":"app-shell","tier":"free","tags":["app shell","sidebar","dashboard layout","navigation","command menu","workspace"],"version":"1.0.0","updated":"2026-10-01","url":"https://ui.ballmac.com/blocks/app-shell-1","registryUrl":"https://ui.ballmac.com/r/app-shell-1.json","install":"npx shadcn@latest add @ballmac/app-shell-1","summary":"The frame around an app. Pass nav=[{ label?, items: [{ id, label, icon?, badge? }] }], workspace, user and a children render function (page) => node; value / onValueChange control the open page.","whenToUse":["Dashboards, admin tools and any multi-page product","A realistic frame for demos and screenshots"],"whenNotToUse":["Marketing sites (use header-2)","Single-screen tools"],"composesWith":["dashboard-1","dashboard-2","settings-1","billing-1","mail-1","kanban-1"],"dependencies":["lucide-react"],"registryDependencies":["shadcn:utils","avatar","button","command","dropdown-menu","kbd","sheet"],"examples":["app-shell-1-demo","app-shell-1-collapsed"],"states":[],"statesNone":"A layout around your own pages; each page inside shows its own states.","preview":"https://ui.ballmac.com/preview/app-shell-1-demo"},{"name":"audit-1","kind":"block","type":"registry:block","title":"Audit 1: audit log","description":"An audit log you can search: who did what to what, when and from where, filters with counts, failed attempts written out, rows that open to show exactly which values changed, show-more paging and an export of what the filter shows.","category":"blocks","blockCategory":"audit","tier":"free","tags":["audit log","security","compliance","activity","admin","export","history"],"version":"1.0.0","updated":"2026-10-24","url":"https://ui.ballmac.com/blocks/audit-1","registryUrl":"https://ui.ballmac.com/r/audit-1.json","install":"npx shadcn@latest add @ballmac/audit-1","summary":"An audit log. Promise} />. Search and the kind filter narrow the list and the count; Export sends what is currently shown. Rows with changes open to show from and to.","whenToUse":["An admin area where owners review security and data activity","A compliance screen that needs an exportable trail"],"whenNotToUse":["A user's own activity feed; use activity-feed","The live output of a process; use log-stream","Agent guardrail checks; use guardrail-feed"],"composesWith":["access-1","settings-1","webhooks-1","app-shell-1"],"dependencies":["lucide-react"],"registryDependencies":["shadcn:utils","button","match-highlight","skeleton","state-view"],"examples":["audit-1-demo","audit-1-failed","audit-1-loading","audit-1-empty","audit-1-error"],"states":[{"id":"loading","title":"Loading","example":"audit-1-loading","trigger":"state=\"loading\"","note":"Skeleton rows under the real heading, announced as loading.","preview":"https://ui.ballmac.com/preview/audit-1-loading"},{"id":"empty","title":"No activity yet","example":"audit-1-empty","trigger":"state=\"empty\"","note":"Says what will appear and when; emptyState sets the copy. A search or filter with no match says so with Clear filters.","preview":"https://ui.ballmac.com/preview/audit-1-empty"},{"id":"error","title":"Could not load","example":"audit-1-error","trigger":"state=\"error\"","note":"An alert saying nothing was changed, with Try again (onRetry).","preview":"https://ui.ballmac.com/preview/audit-1-error"}],"preview":"https://ui.ballmac.com/preview/audit-1-demo"},{"name":"billing-1","kind":"block","type":"registry:block","title":"Billing 1: plan, usage and invoices","description":"A billing page: current plan and monthly cost, usage meters that turn amber near the limit, the card on file with an update dialog (formatted, validated), the billing contact and an invoice list with status and downloads.","category":"blocks","blockCategory":"billing","tier":"free","tags":["billing","subscription","usage","invoices","payment method","plan"],"version":"1.1.1","updated":"2026-10-12","url":"https://ui.ballmac.com/blocks/billing-1","registryUrl":"https://ui.ballmac.com/r/billing-1.json","install":"npx shadcn@latest add @ballmac/billing-1","summary":"The billing screen. Pass plan, usage=[{ label, used, limit?, unit? }], card, contact, invoices, currency and handlers onChangePlan / onUpdateCard (throw to show an error). Real card numbers must go to your payment provider's hosted fields, not through this form.","whenToUse":["Subscription management pages","Usage-based or seat-based products"],"whenNotToUse":["Choosing between plans (use billing-2 or pricing-2)"],"composesWith":["app-shell-1","billing-2","settings-1","settings-3"],"dependencies":["lucide-react"],"registryDependencies":["shadcn:utils","badge","button","dialog","field","input","i18n","state-view","skeleton"],"examples":["billing-1-demo","billing-1-starter","billing-1-loading","billing-1-error","billing-1-no-billing"],"states":[{"id":"loading","title":"Loading","example":"billing-1-loading","trigger":"state=\"loading\"","note":"A skeleton with the same shapes as the ready view, announced as loading; nothing is clickable.","preview":"https://ui.ballmac.com/preview/billing-1-loading"},{"id":"empty","title":"No billing details","example":"billing-1-no-billing","trigger":"state=\"empty\"","note":"A clear message that there is nothing yet. emptyState sets the copy and can add an action.","preview":"https://ui.ballmac.com/preview/billing-1-no-billing"},{"id":"error","title":"Could not load","example":"billing-1-error","trigger":"state=\"error\"","note":"An error with a Try again button (onRetry), announced as an alert.","preview":"https://ui.ballmac.com/preview/billing-1-error"}],"preview":"https://ui.ballmac.com/preview/billing-1-demo"},{"name":"billing-2","kind":"block","type":"registry:block","title":"Billing 2: change plan with proration","description":"A change-plan flow: billing interval, plan cards as radios, a seat stepper that respects the current team, and a sticky summary that works out the prorated charge, the credit and what is due today.","category":"blocks","blockCategory":"billing","tier":"free","tags":["billing","upgrade","downgrade","proration","seats","plans","checkout"],"version":"1.1.0","updated":"2026-10-11","url":"https://ui.ballmac.com/blocks/billing-2","registryUrl":"https://ui.ballmac.com/r/billing-2.json","install":"npx shadcn@latest add @ballmac/billing-2","summary":"Upgrade and downgrade flow. Pass plans=[{ id, name, monthly, yearly, description, features }], currentPlan, currentSeats, today and renewsOn (ISO dates, so server and browser agree) and onConfirm({ plan, seats, interval }) (throw to show an error).","whenToUse":["In-app plan changes","Seat-based products with prorated billing"],"whenNotToUse":["Public pricing pages (use pricing-2 or pricing-3)"],"composesWith":["billing-1","app-shell-1","settings-3"],"dependencies":["lucide-react"],"registryDependencies":["shadcn:utils","badge","button","segmented-control","i18n","state-view","skeleton"],"examples":["billing-2-demo","billing-2-yearly","billing-2-loading","billing-2-error","billing-2-no-plans"],"states":[{"id":"loading","title":"Loading","example":"billing-2-loading","trigger":"state=\"loading\"","note":"A skeleton with the same shapes as the ready view, announced as loading; nothing is clickable.","preview":"https://ui.ballmac.com/preview/billing-2-loading"},{"id":"empty","title":"No plans","example":"billing-2-no-plans","trigger":"state=\"empty\"","note":"A clear message that there is nothing yet. emptyState sets the copy and can add an action.","preview":"https://ui.ballmac.com/preview/billing-2-no-plans"},{"id":"error","title":"Could not load","example":"billing-2-error","trigger":"state=\"error\"","note":"An error with a Try again button (onRetry), announced as an alert.","preview":"https://ui.ballmac.com/preview/billing-2-error"}],"preview":"https://ui.ballmac.com/preview/billing-2-demo"},{"name":"blog-1","kind":"block","type":"registry:block","title":"Blog 1: featured post with filterable grid","description":"A blog index with a large featured post, topic filter chips and a three-column grid. Posts without a photo get a generated cover drawn from theme tokens, in five compositions.","category":"blocks","blockCategory":"blog","tier":"free","tags":["blog","posts","articles","index","filter","cards"],"version":"1.1.0","updated":"2026-10-11","url":"https://ui.ballmac.com/blocks/blog-1","registryUrl":"https://ui.ballmac.com/r/blog-1.json","install":"npx shadcn@latest add @ballmac/blog-1","summary":"The index page of a blog. Pass posts=[{ title, excerpt, category, date, readMinutes, author, role?, href, image?, cover? }]; the first post is featured. Also exports BlogCover for your own cards.","whenToUse":["Company and product blogs","Resource and news pages"],"whenNotToUse":["A single article (use blog-post-1)","Hundreds of posts that need pagination and search"],"composesWith":["blog-post-1","newsletter-1","header-2","footer-2"],"dependencies":["lucide-react"],"registryDependencies":["shadcn:utils","i18n","media","state-view","skeleton"],"examples":["blog-1-demo","blog-1-compact","blog-1-loading","blog-1-error","blog-1-no-posts"],"states":[{"id":"loading","title":"Loading","example":"blog-1-loading","trigger":"state=\"loading\"","note":"A skeleton with the same shapes as the ready view, announced as loading; nothing is clickable.","preview":"https://ui.ballmac.com/preview/blog-1-loading"},{"id":"empty","title":"No posts","example":"blog-1-no-posts","trigger":"state=\"empty\"","note":"A clear message that there is nothing yet. emptyState sets the copy and can add an action.","preview":"https://ui.ballmac.com/preview/blog-1-no-posts"},{"id":"error","title":"Could not load","example":"blog-1-error","trigger":"state=\"error\"","note":"An error with a Try again button (onRetry), announced as an alert.","preview":"https://ui.ballmac.com/preview/blog-1-error"}],"preview":"https://ui.ballmac.com/preview/blog-1-demo"},{"name":"blog-post-1","kind":"block","type":"registry:block","title":"Blog Post 1: article with contents and progress","description":"A long-form article page: centered title and author row, cover, comfortable prose with pull quote and code, sticky table of contents with scroll spy, reading progress bar, author card and related posts.","category":"blocks","blockCategory":"blog","tier":"free","tags":["blog","article","post","prose","table of contents","reading progress"],"version":"1.0.0","updated":"2026-10-01","url":"https://ui.ballmac.com/blocks/blog-post-1","registryUrl":"https://ui.ballmac.com/r/blog-post-1.json","install":"npx shadcn@latest add @ballmac/blog-post-1","summary":"An article template. Pass title, subtitle, author, date and readMinutes, give the body as children (plain h2, h3, p, ul, blockquote and pre are styled), and list the headings in toc.","whenToUse":["Blog posts, guides and announcements","Any long reading page"],"whenNotToUse":["Documentation with a left sidebar (use your docs layout)"],"composesWith":["blog-1","newsletter-1","header-2","footer-2"],"dependencies":["lucide-react"],"registryDependencies":["shadcn:utils","blog-1","breadcrumb","copy-button","scroll-progress","table-of-contents","i18n","media"],"examples":["blog-post-1-demo","blog-post-1-short"],"states":[],"statesNone":"Static content: nothing to load, submit or fail.","preview":"https://ui.ballmac.com/preview/blog-post-1-demo"},{"name":"booking-1","kind":"block","type":"registry:block","title":"Booking 1: class timetable","description":"A weekly class timetable people book from: classes grouped by day, places left written out, one button that does the right thing (book, join the waiting list, cancel, leave), a kind filter, and changes undone with the reason if they fail.","category":"blocks","blockCategory":"booking","tier":"free","tags":["booking","classes","timetable","fitness","studio","waitlist","schedule","wellness"],"version":"1.0.0","updated":"2026-10-24","url":"https://ui.ballmac.com/blocks/booking-1","registryUrl":"https://ui.ballmac.com/r/booking-1.json","install":"npx shadcn@latest add @ballmac/booking-1","summary":"A class timetable. Promise} />. Places left = capacity minus taken (minus you if booked); 3 or fewer says 'Only 2 places left', zero says 'Full' and offers the waiting list. Changes show at once and are undone if onChange rejects.","whenToUse":["A studio, gym or workshop timetable with limited places","Any scheduled session where people can book, queue or cancel"],"whenNotToUse":["A day schedule for staff and patients; use clinic-1","A calendar of events with tickets; use event-1"],"composesWith":["clinic-1","calendar-1","event-1","profile-1"],"dependencies":["lucide-react"],"registryDependencies":["shadcn:utils","button","skeleton","state-view"],"examples":["booking-1-demo","booking-1-loading","booking-1-empty","booking-1-error"],"states":[{"id":"loading","title":"Loading","example":"booking-1-loading","trigger":"state=\"loading\"","note":"Skeleton day headings and cards under the real heading, announced as loading.","preview":"https://ui.ballmac.com/preview/booking-1-loading"},{"id":"empty","title":"No classes this week","example":"booking-1-empty","trigger":"state=\"empty\"","note":"Says no classes this week; emptyState sets the copy.","preview":"https://ui.ballmac.com/preview/booking-1-empty"},{"id":"error","title":"Could not load","example":"booking-1-error","trigger":"state=\"error\"","note":"An alert saying nothing was booked or cancelled, with Try again (onRetry). A booking that fails is undone and says why.","preview":"https://ui.ballmac.com/preview/booking-1-error"}],"preview":"https://ui.ballmac.com/preview/booking-1-demo"},{"name":"calculator-1","kind":"block","type":"registry:block","title":"Calculator 1: pricing estimator","description":"A pricing estimator: sliders for seats, requests and storage, monthly or yearly, add-ons, and a dark summary that picks the cheapest plan that fits, rolls the total as you move, itemizes the sum and offers Talk to us beyond the plans.","category":"blocks","blockCategory":"calculator","tier":"free","tags":["calculator","pricing","estimator","usage","sliders","cost","plans","quote","seats","pay as you go"],"version":"1.0.0","updated":"2026-10-18","url":"https://ui.ballmac.com/blocks/calculator-1","registryUrl":"https://ui.ballmac.com/r/calculator-1.json","install":"npx shadcn@latest add @ballmac/calculator-1","summary":"A usage-based pricing calculator. ...} onTalk />. It picks the cheapest plan whose maxSeats fits, shows each line of the sum and the cost on the other plans, and shows Talk to us when no plan fits. Prices are numbers per month.","whenToUse":["A pricing page for per-seat or usage-based products","Helping a buyer size a plan before they talk to sales"],"whenNotToUse":["Fixed tiers with a feature list (use pricing-1 to pricing-4)","A checkout form"],"composesWith":["pricing-1","faq-1","cta-1","comparison-1"],"dependencies":["lucide-react"],"registryDependencies":["shadcn:utils","animated-number-flow","button","checkbox","segmented-control","slider"],"examples":["calculator-1-demo","calculator-1-enterprise"],"states":[],"statesNone":"Static content: nothing to load, submit or fail.","preview":"https://ui.ballmac.com/preview/calculator-1-demo"},{"name":"calendar-1","kind":"block","type":"registry:block","title":"Calendar 1: week view with mini month","description":"A week calendar: a time grid with overlapping events placed side by side, an all-day row, a now line, a mini month and calendar toggles, event popovers and a new-event dialog. One day at a time on phones.","category":"blocks","blockCategory":"calendar","tier":"free","tags":["calendar","schedule","week view","events","planner","agenda"],"version":"1.1.0","updated":"2026-10-11","url":"https://ui.ballmac.com/blocks/calendar-1","registryUrl":"https://ui.ballmac.com/r/calendar-1.json","install":"npx shadcn@latest add @ballmac/calendar-1","summary":"A scheduling view. Pass defaultEvents=[{ id, title, start, end, calendar, location?, allDay? }] with local 'YYYY-MM-DDTHH:mm' times, calendars, today (YYYY-MM-DD) and now (HH:mm) so the page is identical on the server and in the browser.","whenToUse":["Scheduling, booking and planning screens","A realistic product screenshot"],"whenNotToUse":["Picking a date in a form (use calendar or date-picker)","An agenda list (use calendar-agenda)"],"composesWith":["app-shell-1","kanban-1","mail-1"],"dependencies":["lucide-react"],"registryDependencies":["shadcn:utils","button","calendar","dialog","input","popover","state-view","skeleton"],"examples":["calendar-1-demo","calendar-1-compact","calendar-1-loading","calendar-1-error","calendar-1-no-events"],"states":[{"id":"loading","title":"Loading","example":"calendar-1-loading","trigger":"state=\"loading\"","note":"A skeleton with the same shapes as the ready view, announced as loading; nothing is clickable.","preview":"https://ui.ballmac.com/preview/calendar-1-loading"},{"id":"empty","title":"No events","example":"calendar-1-no-events","trigger":"state=\"empty\"","note":"The real week with no events, so adding one still works.","preview":"https://ui.ballmac.com/preview/calendar-1-no-events"},{"id":"error","title":"Could not load","example":"calendar-1-error","trigger":"state=\"error\"","note":"An error with a Try again button (onRetry), announced as an alert.","preview":"https://ui.ballmac.com/preview/calendar-1-error"}],"preview":"https://ui.ballmac.com/preview/calendar-1-demo"},{"name":"capacity-1","kind":"block","type":"registry:block","title":"Capacity 1: runway","description":"How long until each resource runs out: usage against the limit as a meter, growth per day, the days of runway written as words, the soonest first, a button to ask for more, and a plain 'Not growing' for resources that are not.","category":"blocks","blockCategory":"capacity","tier":"free","tags":["capacity","runway","forecast","storage","limits","infrastructure","planning","sre"],"version":"1.0.0","updated":"2026-10-24","url":"https://ui.ballmac.com/blocks/capacity-1","registryUrl":"https://ui.ballmac.com/r/capacity-1.json","install":"npx shadcn@latest add @ballmac/capacity-1","summary":"Capacity runway. Promise} />. Runway = (limit - used) / perDay, shown as 'Full in about 14 days'; perDay of zero or less says 'Not growing'. Urgent and plan-soon resources come first and offer Ask for more. Exports runway.","whenToUse":["Planning storage, connections or throughput before they run out","An infrastructure review with a clear next action"],"whenNotToUse":["Spend; use cost-1","Reliability targets; use slo-1"],"composesWith":["cost-1","slo-1","queues-1","incident-1"],"dependencies":["lucide-react"],"registryDependencies":["shadcn:utils","button","skeleton","state-view"],"examples":["capacity-1-demo","capacity-1-calm","capacity-1-loading","capacity-1-empty","capacity-1-error"],"states":[{"id":"loading","title":"Loading","example":"capacity-1-loading","trigger":"state=\"loading\"","note":"Skeleton rows under the real heading, announced as loading.","preview":"https://ui.ballmac.com/preview/capacity-1-loading"},{"id":"empty","title":"No resources tracked","example":"capacity-1-empty","trigger":"state=\"empty\"","note":"Says no resources tracked; emptyState sets the copy.","preview":"https://ui.ballmac.com/preview/capacity-1-empty"},{"id":"error","title":"Could not load","example":"capacity-1-error","trigger":"state=\"error\"","note":"An alert saying nothing was changed, with Try again (onRetry). A request that fails says why.","preview":"https://ui.ballmac.com/preview/capacity-1-error"}],"preview":"https://ui.ballmac.com/preview/capacity-1-demo"},{"name":"careers-1","kind":"block","type":"registry:block","title":"Careers 1: open roles with filters and perks","description":"Open roles grouped by team with team filter chips, live search and an empty state, then a hairline grid of perks. Every role row is one large link with location and type.","category":"blocks","blockCategory":"careers","tier":"free","tags":["careers","jobs","hiring","roles","filter","perks"],"version":"1.0.1","updated":"2026-10-11","url":"https://ui.ballmac.com/blocks/careers-1","registryUrl":"https://ui.ballmac.com/r/careers-1.json","install":"npx shadcn@latest add @ballmac/careers-1","summary":"A jobs section. Pass jobs=[{ title, team, location, type?, href }] and optionally perks=[{ icon?, title, description }]; teams and filters are derived from the jobs.","whenToUse":["Company careers pages","Open source projects looking for maintainers"],"whenNotToUse":["A full applicant tracking system"],"composesWith":["team-1","contact-1","header-2","footer-2"],"dependencies":["lucide-react"],"registryDependencies":["shadcn:utils","button","search-field"],"examples":["careers-1-demo","careers-1-small"],"states":[],"statesNone":"Static content: nothing to load, submit or fail.","preview":"https://ui.ballmac.com/preview/careers-1-demo"},{"name":"casestudy-1","kind":"block","type":"registry:block","title":"Case study 1: customer stories","description":"Customer stories for a marketing page: one featured story with its quote and results counting up, a grid of the others with a headline number each, an industry filter, and pictures drawn from each company's name.","category":"blocks","blockCategory":"casestudy","tier":"free","tags":["case study","customer stories","social proof","results","metrics","testimonials","marketing","success stories"],"version":"1.0.0","updated":"2026-10-18","url":"https://ui.ballmac.com/blocks/casestudy-1","registryUrl":"https://ui.ballmac.com/r/casestudy-1.json","install":"npx shadcn@latest add @ballmac/casestudy-1","summary":"Customer stories. . The first story is featured large with its quote; the rest form a grid. An industry filter shows when there are two or more industries. Numbers count up once on scroll and show their final value with reduced motion.","whenToUse":["The social proof section of a marketing site","A customers page linking to full stories"],"whenNotToUse":["Short quotes only (use testimonials-1 or testimonials-2)","A row of customer logos (use logo-cloud-1)"],"composesWith":["hero-1","testimonials-1","cta-1","logo-cloud-1","footer-1"],"dependencies":["lucide-react"],"registryDependencies":["shadcn:utils","blur-fade","cover-art","number-ticker"],"examples":["casestudy-1-demo","casestudy-1-rings"],"states":[],"statesNone":"Static content: nothing to load, submit or fail.","preview":"https://ui.ballmac.com/preview/casestudy-1-demo"},{"name":"changelog-1","kind":"block","type":"registry:block","title":"Changelog 1: release notes timeline","description":"A release-notes page: a sticky version and date beside each release card, optional banner art for headline releases, typed changes with filters and counts, and a show-older button.","category":"blocks","blockCategory":"changelog","tier":"free","tags":["changelog","release notes","updates","versions","timeline","filter"],"version":"1.1.0","updated":"2026-10-11","url":"https://ui.ballmac.com/blocks/changelog-1","registryUrl":"https://ui.ballmac.com/r/changelog-1.json","install":"npx shadcn@latest add @ballmac/changelog-1","summary":"A public changelog page. Pass releases=[{ version, date, title, summary?, changes: { type: 'new' | 'improved' | 'fixed', text }[], cover? }] newest first.","whenToUse":["Product release notes","Open-source project updates"],"whenNotToUse":["A compact in-app feed (use changelog-feed)"],"composesWith":["newsletter-1","header-2","footer-2","hero-6"],"dependencies":["lucide-react"],"registryDependencies":["shadcn:utils","blog-1","button","i18n","media","state-view","skeleton"],"examples":["changelog-1-demo","changelog-1-minimal","changelog-1-loading","changelog-1-error","changelog-1-no-releases"],"states":[{"id":"loading","title":"Loading","example":"changelog-1-loading","trigger":"state=\"loading\"","note":"A skeleton with the same shapes as the ready view, announced as loading; nothing is clickable.","preview":"https://ui.ballmac.com/preview/changelog-1-loading"},{"id":"empty","title":"No releases","example":"changelog-1-no-releases","trigger":"state=\"empty\"","note":"A clear message that there is nothing yet. emptyState sets the copy and can add an action.","preview":"https://ui.ballmac.com/preview/changelog-1-no-releases"},{"id":"error","title":"Could not load","example":"changelog-1-error","trigger":"state=\"error\"","note":"An error with a Try again button (onRetry), announced as an alert.","preview":"https://ui.ballmac.com/preview/changelog-1-error"}],"preview":"https://ui.ballmac.com/preview/changelog-1-demo"},{"name":"charts-1","kind":"block","type":"registry:block","title":"Charts 1: analytics overview","description":"An analytics overview: a range picker, four figures with their change from the period before, a stacked area chart of new and returning visitors, top pages and a sources donut, each with a table view and CSV download.","category":"blocks","blockCategory":"charts","tier":"free","tags":["analytics","charts","dashboard","traffic","visitors","kpi","area","donut","metrics","range"],"version":"1.0.0","updated":"2026-10-18","url":"https://ui.ballmac.com/blocks/charts-1","registryUrl":"https://ui.ballmac.com/r/charts-1.json","install":"npx shadcn@latest add @ballmac/charts-1","summary":". daily is one row per day, oldest first, at least twice the longest range. Figures (visitors, sign-ups, conversion, returning share) and their change from the previous period are worked out from daily. Pages and sources are what you pass; reload them in onRangeChange.","whenToUse":["The overview page of a product or marketing site's analytics","A starting point for any metric dashboard with a range picker"],"whenNotToUse":["A funnel (use funnel-1)","Cohort retention (use retention-1)","One chart only (use chart-area, chart-bar or chart-pie)"],"composesWith":["app-shell-1","funnel-1","retention-1","chart-frame"],"dependencies":["lucide-react"],"registryDependencies":["shadcn:utils","chart-area","chart-bar","chart-pie","kpi-row","segmented-control","skeleton","state-view"],"examples":["charts-1-demo","charts-1-loading","charts-1-empty","charts-1-error"],"states":[{"id":"loading","title":"Loading","example":"charts-1-loading","trigger":"state=\"loading\"","note":"Skeletons shaped like the figures and charts, under the real heading, announced as loading.","preview":"https://ui.ballmac.com/preview/charts-1-loading"},{"id":"empty","title":"No visits yet","example":"charts-1-empty","trigger":"state=\"empty\" (or daily={[]})","note":"Says the numbers appear once people visit; emptyState sets the copy.","preview":"https://ui.ballmac.com/preview/charts-1-empty"},{"id":"error","title":"Could not load","example":"charts-1-error","trigger":"state=\"error\"","note":"An alert with Try again (onRetry).","preview":"https://ui.ballmac.com/preview/charts-1-error"}],"preview":"https://ui.ballmac.com/preview/charts-1-demo"},{"name":"charts-2","kind":"block","type":"registry:block","title":"Charts 2: revenue report","description":"A revenue report: monthly recurring revenue, annual run rate, what was added last month and the largest plan, then revenue by plan as stacked columns and net revenue retention as a line against the 100% mark.","category":"blocks","blockCategory":"charts","tier":"free","tags":["revenue","mrr","finance","charts","retention","saas","report","stacked","dashboard","metrics"],"version":"1.0.0","updated":"2026-10-18","url":"https://ui.ballmac.com/blocks/charts-2","registryUrl":"https://ui.ballmac.com/r/charts-2.json","install":"npx shadcn@latest add @ballmac/charts-2","summary":". One row per month, oldest first. Monthly recurring revenue, annual run rate, the month's net addition and the largest plan are worked out from the rows; plans are fixed to starter, pro and team in this version, so rename them in the source for your own tiers.","whenToUse":["A finance or SaaS revenue page","Showing growth by plan next to retention"],"whenNotToUse":["Traffic and conversion (use charts-1)","A pricing table (use pricing-1)"],"composesWith":["app-shell-1","billing-1","charts-1","chart-frame"],"dependencies":["lucide-react"],"registryDependencies":["shadcn:utils","chart-bar","chart-line","kpi-row","skeleton","state-view"],"examples":["charts-2-demo","charts-2-loading","charts-2-empty","charts-2-error"],"states":[{"id":"loading","title":"Loading","example":"charts-2-loading","trigger":"state=\"loading\"","note":"Skeletons shaped like the figures and the two charts, under the real heading, announced as loading.","preview":"https://ui.ballmac.com/preview/charts-2-loading"},{"id":"empty","title":"No revenue yet","example":"charts-2-empty","trigger":"state=\"empty\" (or months={[]})","note":"Says revenue appears once there are paying customers; emptyState sets the copy.","preview":"https://ui.ballmac.com/preview/charts-2-empty"},{"id":"error","title":"Could not load","example":"charts-2-error","trigger":"state=\"error\"","note":"An alert with Try again (onRetry).","preview":"https://ui.ballmac.com/preview/charts-2-error"}],"preview":"https://ui.ballmac.com/preview/charts-2-demo"},{"name":"charts-3","kind":"block","type":"registry:block","title":"Charts 3: small multiples","description":"Small multiples: one small area chart per metric with the latest value, its change over the period in words and an arrow, which direction is good news, and a written summary for screen readers.","category":"blocks","blockCategory":"charts","tier":"free","tags":["sparkline","small multiples","metrics","kpi","charts","dashboard","trend","health","overview"],"version":"1.0.0","updated":"2026-10-18","url":"https://ui.ballmac.com/blocks/charts-3","registryUrl":"https://ui.ballmac.com/r/charts-3.json","install":"npx shadcn@latest add @ballmac/charts-3","summary":". values are one number per period, oldest first. The latest value and the change from the first value are worked out. format: number | currency | percent (percent values are fractions: 0.045 is 4.5%). better: 'lower' makes a fall count as good news.","whenToUse":["An at-a-glance health page","Comparing many metrics that share a period"],"whenNotToUse":["One metric in depth (use chart-area or chart-line)","Comparing metrics on one scale (use chart-line with several series)"],"composesWith":["app-shell-1","charts-1","stat-card","sparkline"],"dependencies":["lucide-react","motion@^12","recharts@^3"],"registryDependencies":["shadcn:utils","chart","skeleton","state-view"],"examples":["charts-3-demo","charts-3-loading","charts-3-empty","charts-3-error"],"states":[{"id":"loading","title":"Loading","example":"charts-3-loading","trigger":"state=\"loading\"","note":"Six placeholder tiles under the real heading, announced as loading.","preview":"https://ui.ballmac.com/preview/charts-3-loading"},{"id":"empty","title":"No metrics yet","example":"charts-3-empty","trigger":"state=\"empty\" (or metrics={[]})","note":"Says each metric gets a chart once there is a second period; emptyState sets the copy.","preview":"https://ui.ballmac.com/preview/charts-3-empty"},{"id":"error","title":"Could not load","example":"charts-3-error","trigger":"state=\"error\"","note":"An alert with Try again (onRetry).","preview":"https://ui.ballmac.com/preview/charts-3-error"}],"preview":"https://ui.ballmac.com/preview/charts-3-demo"},{"name":"charts-4","kind":"block","type":"registry:block","title":"Charts 4: scorecard","description":"A quarterly scorecard: goals met and average progress, concentric rings for the goals, a radar of the team against its targets and a ranked bar chart, with a table view and CSV download on every chart.","category":"blocks","blockCategory":"charts","tier":"free","tags":["scorecard","okr","goals","radar","radial","ranking","charts","dashboard","team","performance"],"version":"1.0.0","updated":"2026-10-18","url":"https://ui.ballmac.com/blocks/charts-4","registryUrl":"https://ui.ballmac.com/r/charts-4.json","install":"npx shadcn@latest add @ballmac/charts-4","summary":". goals are percents of target (100 is met). profile scores run 0 to 100. The goals met, average progress, biggest gap and leader are worked out from the data.","whenToUse":["Quarterly or sprint reviews","OKR and team performance pages"],"whenNotToUse":["Time series (use charts-1 or charts-3)","Revenue (use charts-2)"],"composesWith":["app-shell-1","goals-1","leaderboard-1","chart-frame"],"dependencies":["lucide-react"],"registryDependencies":["shadcn:utils","chart-bar","chart-radar","chart-radial","kpi-row","skeleton","state-view"],"examples":["charts-4-demo","charts-4-loading","charts-4-empty","charts-4-error"],"states":[{"id":"loading","title":"Loading","example":"charts-4-loading","trigger":"state=\"loading\"","note":"Skeletons shaped like the figures and the three charts, under the real heading, announced as loading.","preview":"https://ui.ballmac.com/preview/charts-4-loading"},{"id":"empty","title":"No goals yet","example":"charts-4-empty","trigger":"state=\"empty\" (or goals={[]})","note":"Says progress appears once a goal is set; emptyState sets the copy.","preview":"https://ui.ballmac.com/preview/charts-4-empty"},{"id":"error","title":"Could not load","example":"charts-4-error","trigger":"state=\"error\"","note":"An alert with Try again (onRetry).","preview":"https://ui.ballmac.com/preview/charts-4-error"}],"preview":"https://ui.ballmac.com/preview/charts-4-demo"},{"name":"chat-1","kind":"block","type":"registry:block","title":"Chat 1: team chat with threads","description":"A team chat: channels and direct messages with unread counts and presence, messages grouped by person and day with a New divider, reactions, threads, @mentions that suggest people, and Retry when a message fails to send.","category":"blocks","blockCategory":"chat","tier":"free","tags":["chat","team chat","messaging","channels","threads","reactions","mentions","slack","realtime","collaboration"],"version":"1.0.0","updated":"2026-10-17","url":"https://ui.ballmac.com/blocks/chat-1","registryUrl":"https://ui.ballmac.com/r/chat-1.json","install":"npx shadcn@latest add @ballmac/chat-1","summary":"A Slack-style team chat. …} onReact onChannelChange />. Messages appear straight away while sending; throw from onSend to mark one Not sent with Retry.","whenToUse":["Team or community messaging inside a product","Customer conversations with internal threads"],"whenNotToUse":["Talking to an AI assistant (use ai-chat-1 or ai-chat-2)","Email-style threads (use mail-1)"],"composesWith":["app-shell-1","settings-2","agent-2"],"dependencies":["lucide-react"],"registryDependencies":["shadcn:utils","avatar","button","skeleton","state-view"],"examples":["chat-1-demo","chat-1-thread","chat-1-loading","chat-1-empty","chat-1-error"],"states":[{"id":"loading","title":"Loading","example":"chat-1-loading","trigger":"state=\"loading\"","note":"Skeleton messages while the channel loads; the sidebar and composer stay usable.","preview":"https://ui.ballmac.com/preview/chat-1-loading"},{"id":"empty","title":"New channel","example":"chat-1-empty","trigger":"state=\"empty\" (or a channel with no messages)","note":"\"This is the start of #channel\" with a prompt to say hello; emptyState sets the copy.","preview":"https://ui.ballmac.com/preview/chat-1-empty"},{"id":"error","title":"Could not load","example":"chat-1-error","trigger":"state=\"error\"","note":"An alert with Try again (onRetry). A single message that fails to send shows Not sent and Retry instead.","preview":"https://ui.ballmac.com/preview/chat-1-error"}],"preview":"https://ui.ballmac.com/preview/chat-1-demo"},{"name":"claims-1","kind":"block","type":"registry:block","title":"Claims 1: claim tracker","description":"An insurance claim tracker: each claim and its stage in words, a line of five stages that stops at the decision when a claim is declined, and the things still needed from the customer with a place to answer each.","category":"blocks","blockCategory":"claims","tier":"free","tags":["insurance","claims","status","tracker","customer portal","documents","case","finance"],"version":"1.0.0","updated":"2026-10-24","url":"https://ui.ballmac.com/blocks/claims-1","registryUrl":"https://ui.ballmac.com/r/claims-1.json","install":"npx shadcn@latest add @ballmac/claims-1","summary":"Claim tracker. Promise} />. A declined claim stops at Decided and later stages are written as not reached.","whenToUse":["A customer portal for insurance, warranty or returns","Any case with stages and requests for information"],"whenNotToUse":["An internal case queue; use tickets-1","A single order's tracking; use status-1"],"composesWith":["tickets-1","upload-1","help-1"],"dependencies":["lucide-react"],"registryDependencies":["shadcn:utils","button","skeleton","state-view"],"examples":["claims-1-demo","claims-1-clear","claims-1-loading","claims-1-empty","claims-1-error"],"states":[{"id":"loading","title":"Loading","example":"claims-1-loading","trigger":"state=\"loading\"","note":"Skeleton list and detail under the real heading, announced as loading.","preview":"https://ui.ballmac.com/preview/claims-1-loading"},{"id":"empty","title":"No claims yet","example":"claims-1-empty","trigger":"state=\"empty\"","note":"Says no claims yet; emptyState sets the copy.","preview":"https://ui.ballmac.com/preview/claims-1-empty"},{"id":"error","title":"Could not load","example":"claims-1-error","trigger":"state=\"error\"","note":"An alert saying nothing was changed, with Try again (onRetry). An answer that fails to send stays in the box and says why.","preview":"https://ui.ballmac.com/preview/claims-1-error"}],"preview":"https://ui.ballmac.com/preview/claims-1-demo"},{"name":"clinic-1","kind":"block","type":"registry:block","title":"Clinic 1: day schedule","description":"A clinic's day: a column per provider, a row per quarter hour, appointments at their real time and length with status written out, one button to move a patient on, and a privacy switch that shows initials only.","category":"blocks","blockCategory":"clinic","tier":"free","tags":["clinic","healthcare","appointments","schedule","front desk","patients","medical","booking"],"version":"1.0.0","updated":"2026-10-24","url":"https://ui.ballmac.com/blocks/clinic-1","registryUrl":"https://ui.ballmac.com/r/clinic-1.json","install":"npx shadcn@latest add @ballmac/clinic-1","summary":"A clinic day view. Promise} />. Select an appointment to see the next actions that fit its status. Initials-only mode hides names in the grid and in the accessible labels.","whenToUse":["A front-desk screen for a clinic, dentist or therapy practice","Any day schedule with providers and check-in steps"],"whenNotToUse":["A calendar for events; use calendar-1","Booking a class for many people; use booking-1"],"composesWith":["booking-1","roster-1","calendar-1","app-shell-1"],"dependencies":["lucide-react"],"registryDependencies":["shadcn:utils","button","skeleton","state-view"],"examples":["clinic-1-demo","clinic-1-private","clinic-1-loading","clinic-1-empty","clinic-1-error"],"states":[{"id":"loading","title":"Loading","example":"clinic-1-loading","trigger":"state=\"loading\"","note":"Skeleton columns under the real heading, announced as loading.","preview":"https://ui.ballmac.com/preview/clinic-1-loading"},{"id":"empty","title":"No appointments today","example":"clinic-1-empty","trigger":"state=\"empty\"","note":"Says no appointments today; emptyState sets the copy.","preview":"https://ui.ballmac.com/preview/clinic-1-empty"},{"id":"error","title":"Could not load","example":"clinic-1-error","trigger":"state=\"error\"","note":"An alert saying no appointment was changed, with Try again (onRetry). A status update that fails goes back and says why.","preview":"https://ui.ballmac.com/preview/clinic-1-error"}],"preview":"https://ui.ballmac.com/preview/clinic-1-demo"},{"name":"comments-1","kind":"block","type":"registry:block","title":"Comments 1: threaded discussion","description":"A threaded discussion: a composer where @ offers people, replies, emoji reactions that count and toggle, editing and deleting your own, resolving a thread, and a comment that appears at once and stays with Retry if it cannot be saved.","category":"blocks","blockCategory":"comments","tier":"free","tags":["comments","discussion","thread","replies","mentions","reactions","collaboration","feedback","conversation"],"version":"1.0.0","updated":"2026-10-18","url":"https://ui.ballmac.com/blocks/comments-1","registryUrl":"https://ui.ballmac.com/r/comments-1.json","install":"npx shadcn@latest add @ballmac/comments-1","summary":"Threaded comments. Promise} onEdit onDelete onReact={(id, emoji, on) => ...} onResolve={(id, resolved) => ...} />. Typing @ opens a people list (arrows, Enter or Tab pick, Escape closes); only @Name that matches a person is highlighted. Times are 'N min ago' from now; pass now yourself, the block never reads the clock. Only comments whose author equals me can be edited or deleted. Reject onPost to show Not posted with Retry.","whenToUse":["Comments on a document, task, design or post","A team discussion with mentions and reactions"],"whenNotToUse":["Real-time chat (use chat-1)","A support conversation with private notes (use tickets-1)"],"composesWith":["tickets-1","tasks-1","editor-1","app-shell-1"],"dependencies":["lucide-react"],"registryDependencies":["shadcn:utils","button","cover-art","skeleton","state-view","textarea"],"examples":["comments-1-demo","comments-1-failed","comments-1-loading","comments-1-empty","comments-1-error"],"states":[{"id":"loading","title":"Loading","example":"comments-1-loading","trigger":"state=\"loading\"","note":"A skeleton composer and comments under the real heading, announced as loading.","preview":"https://ui.ballmac.com/preview/comments-1-loading"},{"id":"empty","title":"No comments yet","example":"comments-1-empty","trigger":"state=\"empty\" (or comments={[]})","note":"Invites the first comment and mentions @; the composer stays usable. emptyState sets the copy.","preview":"https://ui.ballmac.com/preview/comments-1-empty"},{"id":"error","title":"Could not load","example":"comments-1-error","trigger":"state=\"error\"","note":"An alert saying nothing was changed, with Try again (onRetry). A comment that fails to post stays with Not posted and Retry.","preview":"https://ui.ballmac.com/preview/comments-1-error"}],"preview":"https://ui.ballmac.com/preview/comments-1-demo"},{"name":"comparison-1","kind":"block","type":"registry:block","title":"Comparison 1: us versus the alternatives","description":"A product-versus-alternatives table where your column is lifted into its own card, with yes, partly, no and text values and a row of headline results. Phones switch between alternatives.","category":"blocks","blockCategory":"comparison","tier":"free","tags":["comparison","versus","alternatives","table","switch","features"],"version":"1.0.0","updated":"2026-10-01","url":"https://ui.ballmac.com/blocks/comparison-1","registryUrl":"https://ui.ballmac.com/r/comparison-1.json","install":"npx shadcn@latest add @ballmac/comparison-1","summary":"A switch-from-X page section. Pass product, competitors=[{ key, name }] and rows=[{ label, hint?, values: { us, [key]: true | false | 'partial' | text } }].","whenToUse":["Landing pages aimed at people evaluating alternatives","Migration and 'vs' pages"],"whenNotToUse":["Comparing your own plans (use pricing-3)"],"composesWith":["pricing-2","testimonials-2","cta-1","faq-2"],"dependencies":["lucide-react"],"registryDependencies":["shadcn:utils","segmented-control"],"examples":["comparison-1-demo","comparison-1-single"],"states":[],"statesNone":"Static content: nothing to load, submit or fail.","preview":"https://ui.ballmac.com/preview/comparison-1-demo"},{"name":"contact-1","kind":"block","type":"registry:block","title":"Contact 1: form with contact methods","description":"A contact section with a validated form (name, email, topic, message with counter, consent), loading, error and thank-you states, beside tiles for email, chat, phone and office with a response-time pill.","category":"blocks","blockCategory":"contact","tier":"free","tags":["contact","form","support","validation","email","sales"],"version":"1.1.0","updated":"2026-10-11","url":"https://ui.ballmac.com/blocks/contact-1","registryUrl":"https://ui.ballmac.com/r/contact-1.json","install":"npx shadcn@latest add @ballmac/contact-1","summary":"Contact page section. Pass methods, topics and onSubmit(values) (throw to show an error). Validation, focus on the first error, loading and the thank-you screen are built in.","whenToUse":["Contact and support pages","Sales enquiry sections"],"whenNotToUse":["Newsletter signup (use newsletter-1)","Authenticated in-app feedback (use feedback-widget)"],"composesWith":["faq-2","header-2","footer-2","careers-1"],"dependencies":["lucide-react"],"registryDependencies":["shadcn:utils","button","checkbox","field","input","select","status-dot","textarea","use-resource"],"examples":["contact-1-demo","contact-1-support","contact-1-sending","contact-1-sent","contact-1-error"],"states":[{"id":"submitting","title":"Sending","example":"contact-1-sending","trigger":"state=\"submitting\"","note":"Every field and button is disabled while the request is in flight, the button shows a spinner, and the form is marked busy.","preview":"https://ui.ballmac.com/preview/contact-1-sending"},{"id":"success","title":"Message sent","example":"contact-1-sent","trigger":"state=\"success\"","note":"The confirmation screen the flow ends on.","preview":"https://ui.ballmac.com/preview/contact-1-sent"},{"id":"error","title":"Could not send","example":"contact-1-error","trigger":"state=\"error\"","note":"An alert above the form with the message (errorState.description to change it); the fields stay editable so it can be fixed.","preview":"https://ui.ballmac.com/preview/contact-1-error"}],"preview":"https://ui.ballmac.com/preview/contact-1-demo"},{"name":"cost-1","kind":"block","type":"registry:block","title":"Cost 1: cloud cost explorer","description":"Where the cloud bill goes: the total against last period and the budget in words, spend by service as a treemap, a waterfall of what changed since last period, and unusual costs with their cause to mark as looked at.","category":"blocks","blockCategory":"cost","tier":"free","tags":["cloud cost","finops","spend","budget","treemap","waterfall","infrastructure","anomalies"],"version":"1.0.0","updated":"2026-10-24","url":"https://ui.ballmac.com/blocks/cost-1","registryUrl":"https://ui.ballmac.com/r/cost-1.json","install":"npx shadcn@latest add @ballmac/cost-1","summary":"A cloud cost explorer. Promise} />. The period control switches everything. The comparison and the budget are written in words ('$1,640 more than the period before', '$240 left of $16,000').","whenToUse":["A FinOps or engineering-management view of infrastructure spend","Explaining why a bill moved"],"whenNotToUse":["A customer's invoice; use invoice-1","Usage against a plan quota; use the usage-meter component"],"composesWith":["capacity-1","slo-1","dashboard-1","app-shell-1"],"dependencies":["lucide-react"],"registryDependencies":["shadcn:utils","bullet-chart","button","segmented-control","skeleton","state-view","treemap","waterfall-chart"],"examples":["cost-1-demo","cost-1-last","cost-1-loading","cost-1-empty","cost-1-error"],"states":[{"id":"loading","title":"Loading","example":"cost-1-loading","trigger":"state=\"loading\"","note":"Skeleton for the figures, the treemap and the waterfall under the real heading, announced as loading.","preview":"https://ui.ballmac.com/preview/cost-1-loading"},{"id":"empty","title":"No cost data yet","example":"cost-1-empty","trigger":"state=\"empty\"","note":"Says no cost data yet; emptyState sets the copy.","preview":"https://ui.ballmac.com/preview/cost-1-empty"},{"id":"error","title":"Could not load","example":"cost-1-error","trigger":"state=\"error\"","note":"An alert saying nothing was changed, with Try again (onRetry). A failed acknowledgement keeps the cost listed and says why.","preview":"https://ui.ballmac.com/preview/cost-1-error"}],"preview":"https://ui.ballmac.com/preview/cost-1-demo"},{"name":"course-1","kind":"block","type":"registry:block","title":"Course 1: curriculum and progress","description":"A course page: a hero with a progress ring and a Continue button for the next lesson, expandable modules with their own progress, lessons you can open or mark done, locked ones with the reason, and a certificate that unlocks at the end.","category":"blocks","blockCategory":"course","tier":"free","tags":["course","curriculum","lessons","learning","progress","modules","lms","education","certificate","training"],"version":"1.0.0","updated":"2026-10-18","url":"https://ui.ballmac.com/blocks/course-1","registryUrl":"https://ui.ballmac.com/r/course-1.json","install":"npx shadcn@latest add @ballmac/course-1","summary":"A course page. ...} onToggleDone={(lesson, done) => ...} />. Progress, the ring, time left, the next lesson for Continue and the certificate unlock are worked out from the lessons. A locked lesson is disabled and says why.","whenToUse":["A course landing and progress page in a learning product","Onboarding academies and training programs"],"whenNotToUse":["A single lesson player","A list of courses to browse (use a card grid)"],"composesWith":["app-shell-1","profile-1","onboarding-1"],"dependencies":["lucide-react"],"registryDependencies":["shadcn:utils","button","cover-art","skeleton","state-view"],"examples":["course-1-demo","course-1-new","course-1-complete","course-1-loading","course-1-empty","course-1-error"],"states":[{"id":"loading","title":"Loading","example":"course-1-loading","trigger":"state=\"loading\"","note":"A skeleton hero and module cards, announced as loading.","preview":"https://ui.ballmac.com/preview/course-1-loading"},{"id":"empty","title":"No lessons yet","example":"course-1-empty","trigger":"state=\"empty\" (or modules={[]})","note":"Says the first lessons are on their way; emptyState sets the copy.","preview":"https://ui.ballmac.com/preview/course-1-empty"},{"id":"error","title":"Could not load","example":"course-1-error","trigger":"state=\"error\"","note":"An alert saying progress is safe, with Try again (onRetry).","preview":"https://ui.ballmac.com/preview/course-1-error"}],"preview":"https://ui.ballmac.com/preview/course-1-demo"},{"name":"crm-1","kind":"block","type":"registry:block","title":"CRM 1: contact and deal record","description":"A contact record for a sales team: the pipeline stage you can move, deal value, last contact and an overdue follow-up worked out from the day you pass, and a timeline of notes, calls, emails and meetings with a form to log the next.","category":"blocks","blockCategory":"crm","tier":"free","tags":["crm","contact","deal","pipeline","sales","leads","activity","follow-up","customer record","account"],"version":"1.0.0","updated":"2026-10-18","url":"https://ui.ballmac.com/blocks/crm-1","registryUrl":"https://ui.ballmac.com/r/crm-1.json","install":"npx shadcn@latest add @ballmac/crm-1","summary":"A CRM contact record. Promise} onStageChange={(index) => ...} onFollowUp={(date) => ...} />. Last contact and the follow-up status (Due in N days, Due today, Overdue by N days) are worked out from today; pass it yourself, the block never reads the clock. A logged item appears at once; reject onLog and it stays with Not saved and Retry.","whenToUse":["A customer or lead record in a CRM or support tool","An account page for sales and customer success"],"whenNotToUse":["A list or board of deals (use kanban-1)","A support conversation (use tickets-1)"],"composesWith":["directory-1","tickets-1","invoice-1","app-shell-1"],"dependencies":["lucide-react"],"registryDependencies":["shadcn:utils","button","cover-art","input","skeleton","state-view","textarea"],"examples":["crm-1-demo","crm-1-won","crm-1-loading","crm-1-empty","crm-1-error"],"states":[{"id":"loading","title":"Loading","example":"crm-1-loading","trigger":"state=\"loading\"","note":"A skeleton header, timeline and side panel, announced as loading.","preview":"https://ui.ballmac.com/preview/crm-1-loading"},{"id":"empty","title":"Contact not found","example":"crm-1-empty","trigger":"state=\"empty\"","note":"Says they may have been merged or removed; emptyState sets the copy and can add a link back.","preview":"https://ui.ballmac.com/preview/crm-1-empty"},{"id":"error","title":"Could not load","example":"crm-1-error","trigger":"state=\"error\"","note":"An alert saying nothing was changed, with Try again (onRetry). A logged activity that fails to save stays in the timeline with Not saved and Retry.","preview":"https://ui.ballmac.com/preview/crm-1-error"}],"preview":"https://ui.ballmac.com/preview/crm-1-demo"},{"name":"cron-1","kind":"block","type":"registry:block","title":"Cron 1: scheduled jobs","description":"The scheduled jobs of a product: each schedule in plain words beside its cron expression, an on and off switch, the last run written out, the next runs, and a Run now button that asks first.","category":"blocks","blockCategory":"cron","tier":"free","tags":["cron","scheduled jobs","scheduler","automation","backups","tasks","devops","timers"],"version":"1.0.0","updated":"2026-10-24","url":"https://ui.ballmac.com/blocks/cron-1","registryUrl":"https://ui.ballmac.com/r/cron-1.json","install":"npx shadcn@latest add @ballmac/cron-1","summary":"Scheduled jobs. Promise} onRunNow={(job) => Promise} />. Exports describeCron(expr), which turns common five-field expressions into a sentence (every N minutes or hours, daily, weekdays, weekends, one weekday, monthly) and says 'A custom schedule' for the rest instead of guessing.","whenToUse":["An admin page for cron jobs and background schedules","Letting a team pause a job or run it once by hand"],"whenNotToUse":["The workers and their failed jobs; use queues-1","Automations built by users with triggers and steps; use workflow-1"],"composesWith":["queues-1","audit-1","pipeline-1","slo-1"],"dependencies":["lucide-react"],"registryDependencies":["shadcn:utils","alert-dialog","button","skeleton","state-view","switch","return-focus"],"examples":["cron-1-demo","cron-1-loading","cron-1-empty","cron-1-error"],"states":[{"id":"loading","title":"Loading","example":"cron-1-loading","trigger":"state=\"loading\"","note":"Skeleton rows under the real heading, announced as loading.","preview":"https://ui.ballmac.com/preview/cron-1-loading"},{"id":"empty","title":"No scheduled jobs","example":"cron-1-empty","trigger":"state=\"empty\"","note":"Says no scheduled jobs; emptyState sets the copy.","preview":"https://ui.ballmac.com/preview/cron-1-empty"},{"id":"error","title":"Could not load","example":"cron-1-error","trigger":"state=\"error\"","note":"An alert saying nothing was changed or started, with Try again (onRetry). A switch that fails goes back and says why.","preview":"https://ui.ballmac.com/preview/cron-1-error"}],"preview":"https://ui.ballmac.com/preview/cron-1-demo"},{"name":"cta-1","kind":"block","type":"registry:block","title":"CTA 1: framed call to action","description":"A closing call-to-action panel: large heading, one line of reassurance and two buttons, over a softly lit animated grid.","category":"blocks","blockCategory":"cta","tier":"free","tags":["cta","call to action","signup","landing"],"version":"1.0.0","updated":"2026-09-28","url":"https://ui.ballmac.com/blocks/cta-1","registryUrl":"https://ui.ballmac.com/r/cta-1.json","install":"npx shadcn@latest add @ballmac/cta-1","summary":"The last section before the footer: one decisive action. Edit title, description and the two actions.","whenToUse":["End of landing and pricing pages","Between long content sections to prompt sign-up"],"whenNotToUse":["Top of the page (use a hero)"],"composesWith":["footer-1","faq-1"],"dependencies":["lucide-react"],"registryDependencies":["shadcn:utils","animated-grid","button"],"examples":["cta-1-demo"],"states":[],"statesNone":"Static content: nothing to load, submit or fail.","preview":"https://ui.ballmac.com/preview/cta-1-demo"},{"name":"cta-2","kind":"block","type":"registry:block","title":"CTA 2: waitlist over light beams","description":"A waitlist or newsletter signup over rising light beams: heading, email field with validation, loading, success and error states.","category":"blocks","blockCategory":"cta","tier":"free","tags":["cta","waitlist","newsletter","signup","beams"],"version":"1.0.0","updated":"2026-09-29","url":"https://ui.ballmac.com/blocks/cta-2","registryUrl":"https://ui.ballmac.com/r/cta-2.json","install":"npx shadcn@latest add @ballmac/cta-2","summary":"Email capture section. Wire `onSubmit(email)` to your API (throw on failure); the block handles loading, success and error states.","whenToUse":["Pre-launch waitlists","Newsletter signup at the end of a page"],"whenNotToUse":["Collecting more than an email (use a form page)"],"composesWith":["hero-4","features-3","footer-1"],"dependencies":["lucide-react"],"registryDependencies":["shadcn:utils","beams-background","button","input"],"examples":["cta-2-demo"],"states":[],"statesNone":"Static content: nothing to load, submit or fail.","preview":"https://ui.ballmac.com/preview/cta-2-demo"},{"name":"cta-3","kind":"block","type":"registry:block","title":"CTA 3: install command","description":"A closing call-to-action for developer products: heading, two buttons and a copyable install command with package-manager tabs, over a soft dotted glow.","category":"blocks","blockCategory":"cta","tier":"free","tags":["cta","install","command","developer","copy","package manager"],"version":"1.0.0","updated":"2026-10-01","url":"https://ui.ballmac.com/blocks/cta-3","registryUrl":"https://ui.ballmac.com/r/cta-3.json","install":"npx shadcn@latest add @ballmac/cta-3","summary":"The last section of a developer landing page. Set command (run through npm, pnpm, yarn and bun) or commands for explicit per-manager strings.","whenToUse":["Libraries, CLIs and APIs","Docs landing pages"],"whenNotToUse":["Consumer products without a command line"],"composesWith":["hero-2","features-6","faq-2","footer-2"],"dependencies":["lucide-react"],"registryDependencies":["shadcn:utils","button","install-tabs"],"examples":["cta-3-demo","cta-3-custom"],"states":[],"statesNone":"Static content: nothing to load, submit or fail.","preview":"https://ui.ballmac.com/preview/cta-3-demo"},{"name":"dashboard-1","kind":"block","type":"registry:block","title":"Dashboard 1: sales overview","description":"A sales dashboard page: a date-range switch that recomputes everything, four KPI cards with change and trend, a revenue area chart against the previous period, revenue by channel and a recent-orders table.","category":"blocks","blockCategory":"dashboard","tier":"free","tags":["dashboard","analytics","kpi","chart","orders","sales","table"],"version":"1.1.0","updated":"2026-10-11","url":"https://ui.ballmac.com/blocks/dashboard-1","registryUrl":"https://ui.ballmac.com/r/dashboard-1.json","install":"npx shadcn@latest add @ballmac/dashboard-1","summary":"The first screen of a store or SaaS admin. Pass getSeries(range) returning { label, revenue, previous, orders }[], plus channels, orders and currency; the KPIs, deltas and chart are derived from the series.","whenToUse":["Admin home pages","Sales, billing and usage overviews"],"whenNotToUse":["Traffic analytics (use dashboard-2)"],"composesWith":["app-shell-1","dashboard-2","billing-1","settings-1"],"dependencies":["lucide-react","recharts@^3"],"registryDependencies":["shadcn:utils","badge","button","chart","segmented-control","sparkline","i18n","state-view","skeleton"],"examples":["dashboard-1-demo","dashboard-1-week","dashboard-1-loading","dashboard-1-error","dashboard-1-no-data"],"states":[{"id":"loading","title":"Loading","example":"dashboard-1-loading","trigger":"state=\"loading\"","note":"A skeleton with the same shapes as the ready view, announced as loading; nothing is clickable.","preview":"https://ui.ballmac.com/preview/dashboard-1-loading"},{"id":"empty","title":"No sales yet","example":"dashboard-1-no-data","trigger":"state=\"empty\"","note":"A clear message that there is nothing yet. emptyState sets the copy and can add an action.","preview":"https://ui.ballmac.com/preview/dashboard-1-no-data"},{"id":"error","title":"Could not load","example":"dashboard-1-error","trigger":"state=\"error\"","note":"An error with a Try again button (onRetry), announced as an alert.","preview":"https://ui.ballmac.com/preview/dashboard-1-error"}],"preview":"https://ui.ballmac.com/preview/dashboard-1-demo"},{"name":"dashboard-2","kind":"block","type":"registry:block","title":"Dashboard 2: traffic analytics","description":"A web analytics page: a live-now pill, date range and compare switch, a visitors line chart against the previous period, traffic sources as a donut, devices, top countries and a top-pages table.","category":"blocks","blockCategory":"dashboard","tier":"free","tags":["dashboard","analytics","traffic","line chart","donut","visitors","web"],"version":"1.1.0","updated":"2026-10-11","url":"https://ui.ballmac.com/blocks/dashboard-2","registryUrl":"https://ui.ballmac.com/r/dashboard-2.json","install":"npx shadcn@latest add @ballmac/dashboard-2","summary":"A traffic dashboard. Pass getSeries(range) returning { label, visitors, previous }[], plus sources, devices, pages, countries and live (null hides the pill).","whenToUse":["Site and product analytics","Marketing performance pages"],"whenNotToUse":["Sales and revenue (use dashboard-1)"],"composesWith":["app-shell-1","dashboard-1","settings-1"],"dependencies":["lucide-react","recharts@^3"],"registryDependencies":["shadcn:utils","chart","segmented-control","status-dot","switch","i18n","state-view","skeleton"],"examples":["dashboard-2-demo","dashboard-2-week","dashboard-2-loading","dashboard-2-error","dashboard-2-no-data"],"states":[{"id":"loading","title":"Loading","example":"dashboard-2-loading","trigger":"state=\"loading\"","note":"A skeleton with the same shapes as the ready view, announced as loading; nothing is clickable.","preview":"https://ui.ballmac.com/preview/dashboard-2-loading"},{"id":"empty","title":"No traffic yet","example":"dashboard-2-no-data","trigger":"state=\"empty\"","note":"A clear message that there is nothing yet. emptyState sets the copy and can add an action.","preview":"https://ui.ballmac.com/preview/dashboard-2-no-data"},{"id":"error","title":"Could not load","example":"dashboard-2-error","trigger":"state=\"error\"","note":"An error with a Try again button (onRetry), announced as an alert.","preview":"https://ui.ballmac.com/preview/dashboard-2-error"}],"preview":"https://ui.ballmac.com/preview/dashboard-2-demo"},{"name":"deploys-1","kind":"block","type":"registry:block","title":"Deploys 1: deploy history","description":"The deploy history of a product: version, what changed, who shipped it and when, how it ended in words, one environment at a time, the live version marked, and a confirmed rollback to any earlier version that succeeded.","category":"blocks","blockCategory":"deploys","tier":"free","tags":["deploys","releases","rollback","history","ci","cd","versions","devops"],"version":"1.0.0","updated":"2026-10-24","url":"https://ui.ballmac.com/blocks/deploys-1","registryUrl":"https://ui.ballmac.com/r/deploys-1.json","install":"npx shadcn@latest add @ballmac/deploys-1","summary":"Deploy history. Promise} />. The first environment shows at first; a control switches. The newest successful deploy per environment is Live; only earlier successful ones offer Roll back to this, behind a confirmation naming both versions.","whenToUse":["A release page where people check what is live and go back if needed","An audit of what shipped to each environment"],"whenNotToUse":["The stages of one deploy; use pipeline-1","Changes to settings; use audit-1"],"composesWith":["pipeline-1","incident-1","audit-1","status-1"],"dependencies":["lucide-react"],"registryDependencies":["shadcn:utils","alert-dialog","button","skeleton","state-view","return-focus"],"examples":["deploys-1-demo","deploys-1-failing","deploys-1-loading","deploys-1-empty","deploys-1-error"],"states":[{"id":"loading","title":"Loading","example":"deploys-1-loading","trigger":"state=\"loading\"","note":"Skeleton rows under the real heading, announced as loading.","preview":"https://ui.ballmac.com/preview/deploys-1-loading"},{"id":"empty","title":"Nothing deployed yet","example":"deploys-1-empty","trigger":"state=\"empty\"","note":"Says nothing has been deployed yet; emptyState sets the copy.","preview":"https://ui.ballmac.com/preview/deploys-1-empty"},{"id":"error","title":"Could not load","example":"deploys-1-error","trigger":"state=\"error\"","note":"An alert saying nothing was rolled back or changed, with Try again (onRetry). A rollback that does not start says why.","preview":"https://ui.ballmac.com/preview/deploys-1-error"}],"preview":"https://ui.ballmac.com/preview/deploys-1-demo"},{"name":"desktop-1","kind":"block","type":"registry:block","title":"Desktop 1: preferences window","description":"The Settings window of a Tauri or Electron app: toolbar tabs on macOS, a side nav with setting cards on Windows. Launch at login, menu bar, appearance, a global shortcut recorder and update settings that apply as they change.","category":"blocks","blockCategory":"desktop","tier":"free","tags":["desktop","preferences","settings","tauri","electron","macos","windows","shortcut","hotkey","feel"],"version":"1.0.1","updated":"2026-10-17","url":"https://ui.ballmac.com/blocks/desktop-1","registryUrl":"https://ui.ballmac.com/r/desktop-1.json","install":"npx shadcn@latest add @ballmac/desktop-1","summary":"A complete preferences window. persist(v)} onCheckForUpdates />. Panes: General, Appearance, Shortcuts (a key-combination recorder that writes ⇧⌘Space on a Mac and Ctrl+Shift+Space on Windows), Updates, Advanced, plus extraPanes. Layout follows the feel: toolbar tabs and a pane-named title on macOS, side nav and setting cards on Windows.","whenToUse":["The Settings or Preferences window of a Tauri or Electron app","A desktop-style web app that needs app-level preferences"],"whenNotToUse":["Account settings saved with a button (use settings-1)","A settings page inside a web app's layout (use settings-2 or settings-panel)"],"composesWith":["app-window","feel-auto","desktop-3","desktop-6"],"dependencies":["lucide-react","radix-ui"],"registryDependencies":["shadcn:utils","app-window","button","segmented-control","select","switch","direction","feel-presets","shortcut"],"examples":["desktop-1-demo","desktop-1-windows","desktop-1-custom"],"states":[],"statesNone":"Settings apply the moment they change, as desktop apps do: nothing to load, submit or fail.","preview":"https://ui.ballmac.com/preview/desktop-1-demo"},{"name":"desktop-2","kind":"block","type":"registry:block","title":"Desktop 2: menu bar and tray panel","description":"The panel of a menu bar app on macOS or a tray flyout on Windows: a clipboard history with search, pins, a pause switch, keyboard selection and Preferences and Quit, with loading, empty and error states.","category":"blocks","blockCategory":"desktop","tier":"free","tags":["desktop","menu bar","tray","status item","popover","clipboard","tauri","electron","macos","windows","feel"],"version":"1.0.0","updated":"2026-10-17","url":"https://ui.ballmac.com/blocks/desktop-2","registryUrl":"https://ui.ballmac.com/r/desktop-2.json","install":"npx shadcn@latest add @ballmac/desktop-2","summary":"A status-item app panel. . frame draws a menu bar slice (macOS) or taskbar (Windows) around it for marketing pages; frame={false} renders only the panel for the real tray window. Swap the list for your own content by forking the file: the header, search, listbox and footer are separate parts.","whenToUse":["The popover of a macOS menu bar app or a Windows tray app built with Tauri or Electron","Showing a menu bar utility on its landing page"],"whenNotToUse":["Command search across an app (use command or spotlight-search)","A plain dropdown menu (use dropdown-menu)"],"composesWith":["desktop-1","app-window","feel-auto"],"dependencies":["lucide-react"],"registryDependencies":["shadcn:utils","button","kbd","skeleton","state-view","switch","feel-presets"],"examples":["desktop-2-demo","desktop-2-windows","desktop-2-loading","desktop-2-empty","desktop-2-error"],"states":[{"id":"loading","title":"Loading","example":"desktop-2-loading","trigger":"state=\"loading\"","note":"Skeleton rows the shape of history items, announced as loading; search and Clear are disabled.","preview":"https://ui.ballmac.com/preview/desktop-2-loading"},{"id":"empty","title":"Nothing copied yet","example":"desktop-2-empty","trigger":"state=\"empty\"","note":"Explains that copied items will appear; emptyState sets the copy and can add an action.","preview":"https://ui.ballmac.com/preview/desktop-2-empty"},{"id":"error","title":"Could not load","example":"desktop-2-error","trigger":"state=\"error\"","note":"An alert with Try again (onRetry); Preferences and Quit still work.","preview":"https://ui.ballmac.com/preview/desktop-2-error"}],"preview":"https://ui.ballmac.com/preview/desktop-2-demo"},{"name":"desktop-3","kind":"block","type":"registry:block","title":"Desktop 3: software update","description":"The update window of a desktop app, the whole cycle: checking, a new version with release notes, downloading with progress, ready to relaunch, up to date and failed. Buttons follow each platform's order and wording.","category":"blocks","blockCategory":"desktop","tier":"free","tags":["desktop","update","updater","sparkle","release notes","tauri","electron","macos","windows","progress","feel"],"version":"1.0.0","updated":"2026-10-17","url":"https://ui.ballmac.com/blocks/desktop-3","registryUrl":"https://ui.ballmac.com/r/desktop-3.json","install":"npx shadcn@latest add @ballmac/desktop-3","summary":"An updater window. Leave state out and it runs itself: { …; report(0.5) }} onRelaunch onSkip onRemindLater />. Or drive it from your updater with state (loading = checking, submitting + progress = downloading, success = ready, empty = up to date, error). macOS: Title Case buttons, default button last. Windows: sentence case, default button first.","whenToUse":["The update prompt of a Tauri app (tauri-plugin-updater) or an Electron app (electron-updater)","A changelog-style \"what's new\" window after an update"],"whenNotToUse":["A public changelog page (use changelog-1)","A small in-app banner that an update exists (use banner)"],"composesWith":["desktop-1","app-window","feel-auto"],"dependencies":["lucide-react"],"registryDependencies":["shadcn:utils","app-window","button","checkbox","progress","spinner","state-view","use-resource","feel-presets"],"examples":["desktop-3-demo","desktop-3-windows","desktop-3-checking","desktop-3-downloading","desktop-3-ready","desktop-3-up-to-date","desktop-3-error"],"states":[{"id":"loading","title":"Checking","example":"desktop-3-checking","trigger":"state=\"loading\"","note":"A spinner and \"Checking for updates…\" with the current version; marked busy.","preview":"https://ui.ballmac.com/preview/desktop-3-checking"},{"id":"submitting","title":"Downloading","example":"desktop-3-downloading","trigger":"state=\"submitting\" progress={0.4}","note":"A progress bar with megabytes done of the total; the release notes stay readable and Hide keeps it going in the background.","preview":"https://ui.ballmac.com/preview/desktop-3-downloading"},{"id":"success","title":"Ready to relaunch","example":"desktop-3-ready","trigger":"state=\"success\"","note":"\"Install and Relaunch\" (macOS) or \"Restart now\" (Windows) calls onRelaunch; the other button installs on quit.","preview":"https://ui.ballmac.com/preview/desktop-3-ready"},{"id":"empty","title":"Up to date","example":"desktop-3-up-to-date","trigger":"state=\"empty\"","note":"Says the current version is the newest, with OK.","preview":"https://ui.ballmac.com/preview/desktop-3-up-to-date"},{"id":"error","title":"Download failed","example":"desktop-3-error","trigger":"state=\"error\"","note":"Says nothing was changed and offers Try Again (onRetry); errorState sets the copy.","preview":"https://ui.ballmac.com/preview/desktop-3-error"}],"preview":"https://ui.ballmac.com/preview/desktop-3-demo"},{"name":"desktop-4","kind":"block","type":"registry:block","title":"Desktop 4: licence activation","description":"Licence activation for a paid desktop app: a trial meter, a key field that cleans up pasted keys, activation that shows why a key failed, the licensed view with deactivate, and a trial-ended mode.","category":"blocks","blockCategory":"desktop","tier":"free","tags":["desktop","licence","license","activation","trial","paywall","license key","tauri","electron","macos","windows","feel"],"version":"1.0.0","updated":"2026-10-17","url":"https://ui.ballmac.com/blocks/desktop-4","registryUrl":"https://ui.ballmac.com/r/desktop-4.json","install":"npx shadcn@latest add @ballmac/desktop-4","summary":"A licence window. { const r = await validate(key); if (!r.ok) throw new Error(r.reason); return { licensedTo: r.email, plan: 'Pro' } }} onContinueTrial onDeactivate />. trialDaysLeft={0} switches to the trial-ended mode with Quit instead of Continue. Pass licence to open on the licensed view.","whenToUse":["Activating a paid Tauri or Electron app with a licence key (Dodo Payments, Lemon Squeezy, Keygen, Paddle)","The window shown when a trial ends"],"whenNotToUse":["Web subscriptions with sign-in (use billing-1 or pricing blocks)","Entering a one-time code (use verify-1 or input-otp)"],"composesWith":["desktop-1","desktop-6","app-window","feel-auto"],"dependencies":["lucide-react"],"registryDependencies":["shadcn:utils","app-window","button","input","progress","state-view","use-resource","feel-presets"],"examples":["desktop-4-demo","desktop-4-windows","desktop-4-expired","desktop-4-activating","desktop-4-activated","desktop-4-error"],"states":[{"id":"submitting","title":"Activating","example":"desktop-4-activating","trigger":"state=\"submitting\"","note":"The field goes read-only and Activate shows a spinner and \"Activating…\"; announced politely.","preview":"https://ui.ballmac.com/preview/desktop-4-activating"},{"id":"success","title":"Activated","example":"desktop-4-activated","trigger":"state=\"success\" (or pass licence)","note":"Who it is licensed to and on which device, with Done and, when onDeactivate is set, Deactivate.","preview":"https://ui.ballmac.com/preview/desktop-4-activated"},{"id":"error","title":"Key refused","example":"desktop-4-error","trigger":"state=\"error\"","note":"The reason under the field, announced as an alert and linked to it; errorState.description sets it. Thrown Error messages from onActivate show the same way.","preview":"https://ui.ballmac.com/preview/desktop-4-error"}],"preview":"https://ui.ballmac.com/preview/desktop-4-demo"},{"name":"desktop-5","kind":"block","type":"registry:block","title":"Desktop 5: permissions setup","description":"The first-run permissions window: why each one is needed, Allow for ones not asked yet, the exact System Settings path for ones turned off, a re-check on return, and Continue once required ones are on.","category":"blocks","blockCategory":"desktop","tier":"free","tags":["desktop","permissions","onboarding","first run","privacy","accessibility","screen recording","tauri","electron","macos","windows","feel"],"version":"1.0.0","updated":"2026-10-17","url":"https://ui.ballmac.com/blocks/desktop-5","registryUrl":"https://ui.ballmac.com/r/desktop-5.json","install":"npx shadcn@latest add @ballmac/desktop-5","summary":"A permissions onboarding window. status} onOpenSettings={(id) => open(url)} onRecheck={() => refresh()} onContinue />. onRecheck runs when the window regains focus, which is when people return from System Settings.","whenToUse":["First run of a Tauri or Electron app that needs Accessibility, Screen Recording, Microphone, Camera, Full Disk Access or Notifications","A Permissions pane that shows what is on and off"],"whenNotToUse":["Product onboarding questions (use onboarding-1)","Cookie consent on a website"],"composesWith":["desktop-1","desktop-4","app-window","feel-auto"],"dependencies":["lucide-react"],"registryDependencies":["shadcn:utils","app-window","button","skeleton","state-view","feel-presets"],"examples":["desktop-5-demo","desktop-5-windows","desktop-5-loading","desktop-5-error"],"states":[{"id":"loading","title":"Checking","example":"desktop-5-loading","trigger":"state=\"loading\"","note":"Skeleton rows while the current statuses are read; Continue is disabled.","preview":"https://ui.ballmac.com/preview/desktop-5-loading"},{"id":"error","title":"Could not read","example":"desktop-5-error","trigger":"state=\"error\"","note":"An alert that points to System Settings, with Try again (onRetry).","preview":"https://ui.ballmac.com/preview/desktop-5-error"}],"preview":"https://ui.ballmac.com/preview/desktop-5-demo"},{"name":"desktop-6","kind":"block","type":"registry:block","title":"Desktop 6: About window","description":"The About window of a desktop app: icon, name, version and build with a copy button, links, open-source acknowledgements and Check for updates. Small and centered on macOS, a dialog with OK on Windows.","category":"blocks","blockCategory":"desktop","tier":"free","tags":["desktop","about","version","acknowledgements","credits","licenses","tauri","electron","macos","windows","feel"],"version":"1.0.0","updated":"2026-10-17","url":"https://ui.ballmac.com/blocks/desktop-6","registryUrl":"https://ui.ballmac.com/r/desktop-6.json","install":"npx shadcn@latest add @ballmac/desktop-6","summary":"An About window. . Acknowledgements open in the same window with a Back button; the copy button puts \"Acme Version 2.4.1 (241)\" on the clipboard.","whenToUse":["The About item in a Tauri or Electron app's app menu","Crediting the open-source licences a desktop app ships with"],"whenNotToUse":["A company About page on a website (use team-1 or a marketing block)"],"composesWith":["desktop-1","desktop-3","app-window","feel-auto"],"dependencies":["lucide-react"],"registryDependencies":["shadcn:utils","app-window","button","feel-presets"],"examples":["desktop-6-demo","desktop-6-windows"],"states":[],"statesNone":"Static content: nothing to load, submit or fail.","preview":"https://ui.ballmac.com/preview/desktop-6-demo"},{"name":"desktop-7","kind":"block","type":"registry:block","title":"Desktop 7: welcome window","description":"The window a desktop app opens with when nothing is open: name and version, ways to start (new, open, clone) with shortcuts, and recent projects to search, open with Enter and remove from the list.","category":"blocks","blockCategory":"desktop","tier":"free","tags":["desktop","welcome","start","recent","projects","launcher","tauri","electron","macos","windows","feel"],"version":"1.0.0","updated":"2026-10-17","url":"https://ui.ballmac.com/blocks/desktop-7","registryUrl":"https://ui.ballmac.com/r/desktop-7.json","install":"npx shadcn@latest add @ballmac/desktop-7","summary":"A welcome or launcher window. . Recents are a combobox with a listbox: type to search, arrows to move, Enter to open.","whenToUse":["The start window of an editor, IDE or document app built with Tauri or Electron","Choosing a recent project before the main window opens"],"whenNotToUse":["A dashboard home inside a web app (use dashboard-1)","Signing in (use login-1)"],"composesWith":["desktop-1","desktop-6","app-window","feel-auto"],"dependencies":["lucide-react"],"registryDependencies":["shadcn:utils","app-window","button","checkbox","skeleton","state-view","feel-presets","shortcut"],"examples":["desktop-7-demo","desktop-7-windows","desktop-7-loading","desktop-7-empty","desktop-7-error"],"states":[{"id":"loading","title":"Loading recents","example":"desktop-7-loading","trigger":"state=\"loading\"","note":"Skeleton rows in the Recent column while the list is read; the start actions work straight away.","preview":"https://ui.ballmac.com/preview/desktop-7-loading"},{"id":"empty","title":"First launch","example":"desktop-7-empty","trigger":"state=\"empty\" (or recents={[]})","note":"Says opened projects will be listed; emptyState can add an action.","preview":"https://ui.ballmac.com/preview/desktop-7-empty"},{"id":"error","title":"Could not read recents","example":"desktop-7-error","trigger":"state=\"error\"","note":"An alert in the Recent column with Try again (onRetry); the start actions still work.","preview":"https://ui.ballmac.com/preview/desktop-7-error"}],"preview":"https://ui.ballmac.com/preview/desktop-7-demo"},{"name":"desktop-8","kind":"block","type":"registry:block","title":"Desktop 8: keyboard shortcuts editor","description":"A shortcuts editor: commands grouped and searchable by name or by pressing the keys, a recorder on each row, a warning with Replace when keys are taken, reset per command, Restore defaults, and each platform's notation.","category":"blocks","blockCategory":"desktop","tier":"free","tags":["desktop","keyboard","shortcuts","hotkeys","keybindings","preferences","tauri","electron","macos","windows","feel"],"version":"1.0.0","updated":"2026-10-17","url":"https://ui.ballmac.com/blocks/desktop-8","registryUrl":"https://ui.ballmac.com/r/desktop-8.json","install":"npx shadcn@latest add @ballmac/desktop-8","summary":"A keybindings editor. save(overrides)} />. values holds only what differs from the defaults ('' means removed). Conflicts are found with normalizeShortcut, so Ctrl and Mod count as one key on Windows.","whenToUse":["The Keyboard Shortcuts pane or window of a desktop or power-user web app","Letting people remap commands that a command palette also runs"],"whenNotToUse":["A read-only cheat sheet (use keyboard-shortcuts)","One global shortcut (use the recorder in desktop-1)"],"composesWith":["desktop-1","keyboard-shortcuts","command","app-window"],"dependencies":["lucide-react"],"registryDependencies":["shadcn:utils","app-window","button","feel-presets","shortcut"],"examples":["desktop-8-demo","desktop-8-windows"],"states":[],"statesNone":"Shortcuts are local settings that apply as they change: nothing to load, submit or fail.","preview":"https://ui.ballmac.com/preview/desktop-8-demo"},{"name":"dev-1","kind":"block","type":"registry:block","title":"Dev 1: developers page","description":"A developers page: a 14-day request chart with errors stacked, success rate and median time, API keys shown in full once and revoked behind a confirmation, and a request log with filter, responses and copy as curl.","category":"blocks","blockCategory":"developer","tier":"free","tags":["developer","api","api keys","request log","usage","test mode","live mode","curl","logs","dashboard","platform"],"version":"1.0.0","updated":"2026-10-17","url":"https://ui.ballmac.com/blocks/dev-1","registryUrl":"https://ui.ballmac.com/r/dev-1.json","install":"npx shadcn@latest add @ballmac/dev-1","summary":"A developer dashboard page. ({ id, secret })} onRevokeKey onEnvChange defaultEnv />. The secret returned by onCreateKey is shown once in a copy banner and only its last four characters are kept in the list.","whenToUse":["The developer or API section of a platform product","Letting customers manage keys and debug requests themselves"],"whenNotToUse":["Showing one secret in a settings form (use api-key-field)","Webhook endpoints and deliveries (use webhook-card)","Server logs for operators (use log-stream)"],"composesWith":["settings-4","settings-5","app-shell-1","agent-3"],"dependencies":["lucide-react"],"registryDependencies":["shadcn:utils","alert-dialog","badge","blur-fade","button","copy-button","json-viewer","number-ticker","segmented-control","skeleton","state-view","return-focus"],"examples":["dev-1-demo","dev-1-live","dev-1-empty","dev-1-loading","dev-1-error"],"states":[{"id":"loading","title":"Loading","example":"dev-1-loading","trigger":"state=\"loading\"","note":"A skeleton of the usage chart, the keys and the request log under the real heading.","preview":"https://ui.ballmac.com/preview/dev-1-loading"},{"id":"empty","title":"No requests yet","example":"dev-1-empty","trigger":"state=\"empty\" (or requests={[]})","note":"Explains that requests appear within seconds and gives a ready curl command to make the first one, with a copy button.","preview":"https://ui.ballmac.com/preview/dev-1-empty"},{"id":"error","title":"Could not load","example":"dev-1-error","trigger":"state=\"error\"","note":"An alert saying keys are safe and nothing changed, with Try again (onRetry).","preview":"https://ui.ballmac.com/preview/dev-1-error"}],"preview":"https://ui.ballmac.com/preview/dev-1-demo"},{"name":"devices-1","kind":"block","type":"registry:block","title":"Devices 1: Mac, iPad, iPhone and Watch lineup","description":"A lineup of laptop, tablet, phone and watch frames with their own token-drawn screens, scaled as one picture. Buttons underneath bring a device forward and dim the rest.","category":"blocks","blockCategory":"devices","tier":"free","tags":["devices","mac","ipad","iphone","watch","multi-platform","lineup"],"version":"1.0.0","updated":"2026-10-01","url":"https://ui.ballmac.com/blocks/devices-1","registryUrl":"https://ui.ballmac.com/r/devices-1.json","install":"npx shadcn@latest add @ballmac/devices-1","summary":"A multi-platform section. Edit eyebrow, title, description and captions; pass screens={{ mac, ipad, iphone, watch }} to replace the sample screens, each laid out at its real device width (1280, 834, 393, 208).","whenToUse":["Apps that ship on several Apple platforms","Showing responsive or cross-device behaviour"],"whenNotToUse":["Single-platform products (use hero-5 or showcase-1)"],"composesWith":["hero-5","features-4","download-1","pricing-4"],"dependencies":["lucide-react"],"registryDependencies":["shadcn:utils","laptop-frame","phone-frame","tablet-frame","watch-frame"],"examples":["devices-1-demo","devices-1-custom"],"states":[],"statesNone":"Static content: nothing to load, submit or fail.","preview":"https://ui.ballmac.com/preview/devices-1-demo"},{"name":"directory-1","kind":"block","type":"registry:block","title":"Directory 1: people directory","description":"A people directory: search across names, roles, teams and cities, department chips with live counts, a location filter, a grid and a compact list, each person with availability and their local time right now.","category":"blocks","blockCategory":"directory","tier":"free","tags":["directory","people","team","employees","contacts","company","who is who","time zones","staff"],"version":"1.0.0","updated":"2026-10-18","url":"https://ui.ballmac.com/blocks/directory-1","registryUrl":"https://ui.ballmac.com/r/directory-1.json","install":"npx shadcn@latest add @ballmac/directory-1","summary":"A people directory. . Local times are worked out from now plus each utcOffset; pass now yourself, the block never reads the clock. Department chips and the location menu come from the data.","whenToUse":["An internal company directory or a team page with filters","Remote teams that need to see where people are and what time it is for them"],"whenNotToUse":["A reporting hierarchy (use orgchart-1)","A marketing team section with photos (use team-1)"],"composesWith":["orgchart-1","app-shell-1","about-1"],"dependencies":["lucide-react"],"registryDependencies":["shadcn:utils","button","cover-art","match-highlight","segmented-control","select","skeleton","state-view"],"examples":["directory-1-demo","directory-1-list","directory-1-loading","directory-1-empty","directory-1-error"],"states":[{"id":"loading","title":"Loading","example":"directory-1-loading","trigger":"state=\"loading\"","note":"Skeleton cards under the real heading, announced as loading.","preview":"https://ui.ballmac.com/preview/directory-1-loading"},{"id":"empty","title":"Nobody listed","example":"directory-1-empty","trigger":"state=\"empty\" (or people={[]})","note":"Says people appear once added; emptyState sets the copy. A search with no match says so with Clear filters.","preview":"https://ui.ballmac.com/preview/directory-1-empty"},{"id":"error","title":"Could not load","example":"directory-1-error","trigger":"state=\"error\"","note":"An alert with Try again (onRetry).","preview":"https://ui.ballmac.com/preview/directory-1-error"}],"preview":"https://ui.ballmac.com/preview/directory-1-demo"},{"name":"dispatch-1","kind":"block","type":"registry:block","title":"Dispatch 1: field service board","description":"A dispatch board for field work: waiting jobs with urgent ones first and named, a lane per technician with their jobs in time order, assignment by a labelled select instead of a drag, take-back, and changes undone with the reason.","category":"blocks","blockCategory":"dispatch","tier":"free","tags":["dispatch","field service","technicians","jobs","scheduling","trades","logistics","assign"],"version":"1.0.0","updated":"2026-10-24","url":"https://ui.ballmac.com/blocks/dispatch-1","registryUrl":"https://ui.ballmac.com/r/dispatch-1.json","install":"npx shadcn@latest add @ballmac/dispatch-1","summary":"A dispatch board. Promise} />. Waiting jobs list urgent first. Assigning uses a labelled select (no drag), and only a scheduled job can be taken back.","whenToUse":["An office view for assigning field jobs to technicians","Any queue where jobs wait and are given to people"],"whenNotToUse":["A kitchen's tickets by station; use kitchen-1","A calendar of a person's day; use calendar-1"],"composesWith":["workorder-1","kitchen-1","roster-1","locations-1"],"dependencies":["lucide-react"],"registryDependencies":["shadcn:utils","button","skeleton","state-view"],"examples":["dispatch-1-demo","dispatch-1-loading","dispatch-1-empty","dispatch-1-error"],"states":[{"id":"loading","title":"Loading","example":"dispatch-1-loading","trigger":"state=\"loading\"","note":"Skeleton for the waiting list and the lanes under the real heading, announced as loading.","preview":"https://ui.ballmac.com/preview/dispatch-1-loading"},{"id":"empty","title":"No jobs today","example":"dispatch-1-empty","trigger":"state=\"empty\"","note":"Says no jobs today; emptyState sets the copy.","preview":"https://ui.ballmac.com/preview/dispatch-1-empty"},{"id":"error","title":"Could not load","example":"dispatch-1-error","trigger":"state=\"error\"","note":"An alert saying nothing was assigned or changed, with Try again (onRetry). A failed assignment is undone and says why.","preview":"https://ui.ballmac.com/preview/dispatch-1-error"}],"preview":"https://ui.ballmac.com/preview/dispatch-1-demo"},{"name":"donations-1","kind":"block","type":"registry:block","title":"Donations 1: donation page","description":"A donation page for a charity: what each amount does, once or every month, which cause, an optional card-fee cover, anonymous giving, a progress bar to the goal, and a thank you that says exactly what was given.","category":"blocks","blockCategory":"donations","tier":"free","tags":["donations","charity","nonprofit","fundraising","giving","checkout","monthly","impact"],"version":"1.0.0","updated":"2026-10-24","url":"https://ui.ballmac.com/blocks/donations-1","registryUrl":"https://ui.ballmac.com/r/donations-1.json","install":"npx shadcn@latest add @ballmac/donations-1","summary":"Donation page. Promise} />. The total, including the fee cover, is always shown before the button. Giving anonymously removes the name requirement and sends no name.","whenToUse":["A charity or open source project asking for gifts","Any pay-what-you-choose page with a clear impact"],"whenNotToUse":["A store checkout; use billing-1","A fixed plan subscription; use pricing-1"],"composesWith":["billing-1","trust-1","testimonials-1"],"dependencies":["lucide-react"],"registryDependencies":["shadcn:utils","button","skeleton","state-view"],"examples":["donations-1-demo","donations-1-monthly","donations-1-loading","donations-1-empty","donations-1-error"],"states":[{"id":"loading","title":"Loading","example":"donations-1-loading","trigger":"state=\"loading\"","note":"Skeleton progress and form under the real heading, announced as loading.","preview":"https://ui.ballmac.com/preview/donations-1-loading"},{"id":"empty","title":"Giving is not open yet","example":"donations-1-empty","trigger":"state=\"empty\"","note":"Says giving is not open yet; emptyState sets the copy.","preview":"https://ui.ballmac.com/preview/donations-1-empty"},{"id":"error","title":"Could not load","example":"donations-1-error","trigger":"state=\"error\"","note":"An alert saying you were not charged, with Try again (onRetry). A gift that fails keeps the form filled and says why.","preview":"https://ui.ballmac.com/preview/donations-1-error"}],"preview":"https://ui.ballmac.com/preview/donations-1-demo"},{"name":"download-1","kind":"block","type":"registry:block","title":"Download 1: Mac app download with release notes","description":"A Mac app download section: app icon and version, an Apple silicon or Intel choice that swaps the file, copyable checksum and Homebrew command, install steps and release notes you can flip between.","category":"blocks","blockCategory":"download","tier":"free","tags":["download","mac","app","release notes","homebrew","checksum","install"],"version":"1.0.0","updated":"2026-10-01","url":"https://ui.ballmac.com/blocks/download-1","registryUrl":"https://ui.ballmac.com/r/download-1.json","install":"npx shadcn@latest add @ballmac/download-1","summary":"The download page of a Mac app. Pass app, tagline, downloads={ arm64: { href, file, size, sha256? }, x64: {...} }, requirements, brew, steps and releases=[{ version, date, changes: [{ type, text }] }].","whenToUse":["Direct-download Mac apps","Any desktop app with separate builds per chip"],"whenNotToUse":["App Store only apps (link to the store instead)","Web apps"],"composesWith":["hero-5","showcase-1","features-7","pricing-4"],"dependencies":["lucide-react"],"registryDependencies":["shadcn:utils","button","copy-button","mac-icons","segmented-control","i18n","media"],"examples":["download-1-demo","download-1-simple"],"states":[],"statesNone":"Static content: nothing to load, submit or fail.","preview":"https://ui.ballmac.com/preview/download-1-demo"},{"name":"editor-1","kind":"block","type":"registry:block","title":"Editor 1: Markdown with live preview","description":"A Markdown editor with live preview: a toolbar and shortcuts that wrap the selection, a preview built from safe elements, word count and reading time, and autosave that says Saved, Saving, Unsaved changes or Not saved with Retry.","category":"blocks","blockCategory":"editor","tier":"free","tags":["editor","markdown","writing","notes","preview","autosave","text editor","docs","wysiwyg","composer"],"version":"1.0.0","updated":"2026-10-18","url":"https://ui.ballmac.com/blocks/editor-1","registryUrl":"https://ui.ballmac.com/r/editor-1.json","install":"npx shadcn@latest add @ballmac/editor-1","summary":"A Markdown editor. Promise} onChange={(value) => ...} defaultTab='write' | 'preview' />. Supports headings (1 to 3), bold, italic, inline code, links (http, https, mailto only), bulleted and numbered lists, quotes and rules. Ctrl or Command with B, I, K format and S saves now. Saving happens autosaveMs after the last keystroke; reject onSave to show Not saved with Retry. The preview never uses dangerouslySetInnerHTML.","whenToUse":["Notes, docs, release notes and posts written in Markdown","A comment or message composer that needs formatting"],"whenNotToUse":["A full rich text editor with tables and images","A short single-line field (use input)"],"composesWith":["app-shell-1","tickets-1","changelog-1","help-1"],"dependencies":["lucide-react"],"registryDependencies":["shadcn:utils","button","skeleton","state-view"],"examples":["editor-1-demo","editor-1-preview","editor-1-failed","editor-1-loading","editor-1-error"],"states":[{"id":"loading","title":"Loading","example":"editor-1-loading","trigger":"state=\"loading\"","note":"A skeleton toolbar and page under the real heading, announced as loading.","preview":"https://ui.ballmac.com/preview/editor-1-loading"},{"id":"error","title":"Could not load","example":"editor-1-error","trigger":"state=\"error\"","note":"An alert saying nothing was changed, with Try again (onRetry). A save that fails shows Not saved with Retry and keeps the text.","preview":"https://ui.ballmac.com/preview/editor-1-error"}],"preview":"https://ui.ballmac.com/preview/editor-1-demo"},{"name":"error-1","kind":"block","type":"registry:block","title":"Error 1: friendly 404, 403 and 500 page","description":"An error page with giant fading numerals whose zero is a ring with an orbiting moon, plain-language copy per status, home and back buttons, site search and helpful links.","category":"blocks","blockCategory":"error","tier":"free","tags":["error","404","not found","500","403","page"],"version":"1.0.1","updated":"2026-10-11","url":"https://ui.ballmac.com/blocks/error-1","registryUrl":"https://ui.ballmac.com/r/error-1.json","install":"npx shadcn@latest add @ballmac/error-1","summary":"Drop into not-found.tsx or error.tsx. Set status ('404' | '403' | '500'); override title and description if you like; pass onSearch to wire the search box, links for next steps and reference for a request id.","whenToUse":["Next.js not-found.tsx and error.tsx","Any missing, forbidden or failed page"],"whenNotToUse":["Inline errors inside a form or panel (use alert or empty-state)"],"composesWith":["header-2","footer-2","contact-1"],"dependencies":["lucide-react","motion@^12"],"registryDependencies":["shadcn:utils","button","search-field","motion-presets"],"examples":["error-1-demo","error-1-server"],"states":[],"statesNone":"This block is the error page itself.","preview":"https://ui.ballmac.com/preview/error-1-demo"},{"name":"event-1","kind":"block","type":"registry:block","title":"Event 1: agenda and my schedule","description":"An event page with its agenda: dates, venue and a countdown, the schedule by day with a filter per track, a star on each session to build your own schedule, a warning for overlaps, and a calendar file download.","category":"blocks","blockCategory":"event","tier":"free","tags":["event","conference","agenda","schedule","sessions","speakers","tracks","calendar","ics","summit","meetup"],"version":"1.0.0","updated":"2026-10-18","url":"https://ui.ballmac.com/blocks/event-1","registryUrl":"https://ui.ballmac.com/r/event-1.json","install":"npx shadcn@latest add @ballmac/event-1","summary":"An event agenda. . Days and tracks come from the sessions; overlaps among saved sessions are found for you; 'Add to my calendar' builds an .ics file in the browser using utcOffset. Pass now yourself; the block never reads the clock.","whenToUse":["A conference, meetup or webinar series page with a schedule","An internal offsite agenda"],"whenNotToUse":["Ticket purchase (use a pricing block)","A month calendar of many events (use calendar-1)"],"composesWith":["hero-1","pricing-1","faq-1","footer-1"],"dependencies":["lucide-react"],"registryDependencies":["shadcn:utils","button","cover-art"],"examples":["event-1-demo","event-1-saved"],"states":[],"statesNone":"Static content: nothing to load, submit or fail.","preview":"https://ui.ballmac.com/preview/event-1-demo"},{"name":"expenses-1","kind":"block","type":"registry:block","title":"Expenses 1: expense report","description":"An expense report you can finish: lines with category, amount and receipt, a total by category, rules checked as you go (receipt needed over a threshold, category limits), an add form, and Submit that lists what needs fixing.","category":"blocks","blockCategory":"expenses","tier":"free","tags":["expenses","expense report","receipts","reimbursement","travel","finance","approval","spending","claims"],"version":"1.0.0","updated":"2026-10-18","url":"https://ui.ballmac.com/blocks/expenses-1","registryUrl":"https://ui.ballmac.com/r/expenses-1.json","install":"npx shadcn@latest add @ballmac/expenses-1","summary":"An expense report. ...} onSubmit={(lines, total) => Promise} />. The total and the category breakdown are worked out from the lines. A line over receiptOver without a receipt blocks Submit and is named in the message; a line over its category limit shows a warning but does not block. Adding a line validates the merchant and amount. Reject onSubmit to show the reason and stay open.","whenToUse":["Employee expense claims and reimbursements","Trip or project cost reports"],"whenNotToUse":["A customer invoice (use invoice-1)","Hours worked (use timesheet-1)"],"composesWith":["timesheet-1","invoice-1","app-shell-1","upload-1"],"dependencies":["lucide-react"],"registryDependencies":["shadcn:utils","button","input","select","skeleton","state-view"],"examples":["expenses-1-demo","expenses-1-clean","expenses-1-loading","expenses-1-empty","expenses-1-error"],"states":[{"id":"loading","title":"Loading","example":"expenses-1-loading","trigger":"state=\"loading\"","note":"A skeleton summary and list under the real heading, announced as loading.","preview":"https://ui.ballmac.com/preview/expenses-1-loading"},{"id":"empty","title":"No expenses yet","example":"expenses-1-empty","trigger":"state=\"empty\" (or lines={[]})","note":"Says to add what you paid for; emptyState sets the copy and can add a button.","preview":"https://ui.ballmac.com/preview/expenses-1-empty"},{"id":"error","title":"Could not load","example":"expenses-1-error","trigger":"state=\"error\"","note":"An alert saying nothing was changed, with Try again (onRetry). A failed submit says nothing was lost, in place beside the button.","preview":"https://ui.ballmac.com/preview/expenses-1-error"}],"preview":"https://ui.ballmac.com/preview/expenses-1-demo"},{"name":"experiments-1","kind":"block","type":"registry:block","title":"Experiments 1: A/B test results","description":"A/B test results with the statistics done: each variant's rate with its 95% confidence interval on one shared axis, lift, chance to beat the control, and a plain verdict: a winner, no clear difference, or more traffic needed.","category":"blocks","blockCategory":"experiments","tier":"free","tags":["experiments","ab test","a/b testing","conversion","statistics","significance","confidence interval","growth","optimization"],"version":"1.0.0","updated":"2026-10-18","url":"https://ui.ballmac.com/blocks/experiments-1","registryUrl":"https://ui.ballmac.com/r/experiments-1.json","install":"npx shadcn@latest add @ballmac/experiments-1","summary":"A/B test results. ...} />. Pass raw counts: rates, Wilson 95% intervals, relative lift, chance to beat the control (normal approximation), a two-sided p-value and the verdict are worked out. The verdict is a winner (p below 1 minus confidence), a loser, 'not enough data' with the visitors still needed at 80% power, or 'no clear difference'.","whenToUse":["An experimentation or growth tool showing test results","A landing-page testing report"],"whenNotToUse":["Plain KPI cards (use stats-1 or a dashboard block)","Many metrics over time (use a chart)"],"composesWith":["app-shell-1","funnel-1","settings-5"],"dependencies":["lucide-react"],"registryDependencies":["shadcn:utils","button","skeleton","state-view"],"examples":["experiments-1-demo","experiments-1-early","experiments-1-flat","experiments-1-loading","experiments-1-empty","experiments-1-error"],"states":[{"id":"loading","title":"Loading","example":"experiments-1-loading","trigger":"state=\"loading\"","note":"A skeleton verdict and variant rows under the real heading, announced as loading.","preview":"https://ui.ballmac.com/preview/experiments-1-loading"},{"id":"empty","title":"No results yet","example":"experiments-1-empty","trigger":"state=\"empty\" (or variants={[]})","note":"Says results appear once visitors have seen the versions; emptyState sets the copy.","preview":"https://ui.ballmac.com/preview/experiments-1-empty"},{"id":"error","title":"Could not load","example":"experiments-1-error","trigger":"state=\"error\"","note":"An alert saying nothing was changed, with Try again (onRetry).","preview":"https://ui.ballmac.com/preview/experiments-1-error"}],"preview":"https://ui.ballmac.com/preview/experiments-1-demo"},{"name":"faq-1","kind":"block","type":"registry:block","title":"FAQ 1: accordion with heading","description":"Frequently asked questions in an accessible accordion, with the heading and a help line in a side column on desktop.","category":"blocks","blockCategory":"faq","tier":"free","tags":["faq","accordion","questions","support"],"version":"1.0.0","updated":"2026-09-28","url":"https://ui.ballmac.com/blocks/faq-1","registryUrl":"https://ui.ballmac.com/r/faq-1.json","install":"npx shadcn@latest add @ballmac/faq-1","summary":"An FAQ section. Pass items=[{ question, answer }]; the first answer starts open.","whenToUse":["Pricing pages and landing pages","Support and onboarding pages"],"whenNotToUse":["Long documentation (use a docs page)"],"composesWith":["pricing-1","cta-1"],"dependencies":[],"registryDependencies":["shadcn:utils","accordion"],"examples":["faq-1-demo"],"states":[],"statesNone":"Static content: nothing to load, submit or fail.","preview":"https://ui.ballmac.com/preview/faq-1-demo"},{"name":"faq-2","kind":"block","type":"registry:block","title":"FAQ 2: searchable with topic filters","description":"Frequently asked questions with live search that highlights matches, topic filters with counts, a friendly empty state and a support prompt. Topics scroll sideways on phones.","category":"blocks","blockCategory":"faq","tier":"free","tags":["faq","search","accordion","help","support","filter"],"version":"1.0.0","updated":"2026-10-01","url":"https://ui.ballmac.com/blocks/faq-2","registryUrl":"https://ui.ballmac.com/r/faq-2.json","install":"npx shadcn@latest add @ballmac/faq-2","summary":"A help-centre style FAQ. Pass categories=[{ name, questions: [{ question, answer }] }]; an All filter and search are built in.","whenToUse":["More than eight questions across topics","Pricing and product pages that attract many questions"],"whenNotToUse":["A handful of questions (use faq-1)"],"composesWith":["pricing-2","pricing-3","cta-1","footer-1"],"dependencies":["lucide-react"],"registryDependencies":["shadcn:utils","accordion","button","search-field"],"examples":["faq-2-demo","faq-2-compact"],"states":[],"statesNone":"Static content: nothing to load, submit or fail.","preview":"https://ui.ballmac.com/preview/faq-2-demo"},{"name":"features-1","kind":"block","type":"registry:block","title":"Features 1: bento grid","description":"Bento feature grid of spotlight cards in two sizes, with an animated stat and keyboard-shortcut hints mixed in for texture.","category":"blocks","blockCategory":"features","tier":"free","tags":["features","bento","grid","landing"],"version":"1.0.0","updated":"2026-09-28","url":"https://ui.ballmac.com/blocks/features-1","registryUrl":"https://ui.ballmac.com/r/features-1.json","install":"npx shadcn@latest add @ballmac/features-1","summary":"A four-cell bento grid for a product's main features. Edit the cells directly; each is a SpotlightCard with an icon, title, body and optional extra content.","whenToUse":["Showing 3–6 headline features with visual variety","SaaS and developer product landing pages"],"whenNotToUse":["Long lists of features (use features-2)"],"composesWith":["hero-1","pricing-1"],"dependencies":["lucide-react"],"registryDependencies":["shadcn:utils","kbd","number-ticker","spotlight-card"],"examples":["features-1-demo"],"states":[],"statesNone":"Static content: nothing to load, submit or fail.","preview":"https://ui.ballmac.com/preview/features-1-demo"},{"name":"features-2","kind":"block","type":"registry:block","title":"Features 2: numbered icon grid","description":"Six features in a hairline grid of numbered cells with an icon, title and one sentence each. Pass your own features array.","category":"blocks","blockCategory":"features","tier":"free","tags":["features","grid","icons","landing"],"version":"1.0.0","updated":"2026-09-28","url":"https://ui.ballmac.com/blocks/features-2","registryUrl":"https://ui.ballmac.com/r/features-2.json","install":"npx shadcn@latest add @ballmac/features-2","summary":"A calm, scannable grid for 3–9 features. Pass features=[{ icon, title, body }] with lucide icons.","whenToUse":["Listing several product benefits evenly","Developer tools and libraries"],"whenNotToUse":["Two or three features that need visuals (use features-1)"],"composesWith":["hero-2","cta-1"],"dependencies":["lucide-react"],"registryDependencies":["shadcn:utils"],"examples":["features-2-demo"],"states":[],"statesNone":"Static content: nothing to load, submit or fail.","preview":"https://ui.ballmac.com/preview/features-2-demo"},{"name":"features-3","kind":"block","type":"registry:block","title":"Features 3: integrations hub with beams","description":"Integrations section: heading, description and checked benefits beside a hub diagram where animated beams flow between your product and six tools.","category":"blocks","blockCategory":"features","tier":"free","tags":["features","integrations","animated beam","diagram"],"version":"1.0.0","updated":"2026-09-29","url":"https://ui.ballmac.com/blocks/features-3","registryUrl":"https://ui.ballmac.com/r/features-3.json","install":"npx shadcn@latest add @ballmac/features-3","summary":"Explains integrations or data flow. Pass up to six `integrations` ({ name, icon }) and set hubIcon/hubLabel for your product.","whenToUse":["Integrations or connectors pages","Showing that a product sits between many tools (AI agents, automation, sync)"],"whenNotToUse":["Listing more than six integrations (use a logo grid)"],"composesWith":["hero-4","features-1","cta-2"],"dependencies":["lucide-react"],"registryDependencies":["shadcn:utils","animated-beam"],"examples":["features-3-demo"],"states":[],"statesNone":"Static content: nothing to load, submit or fail.","preview":"https://ui.ballmac.com/preview/features-3-demo"},{"name":"features-4","kind":"block","type":"registry:block","title":"Features 4: Mac app bento","description":"Bento feature grid for a desktop app: menu bar companion, keyboard shortcuts, privacy, iCloud sync and notifications, each with a small live visual.","category":"blocks","blockCategory":"features","tier":"free","tags":["features","bento","mac app","desktop"],"version":"1.0.0","updated":"2026-09-29","url":"https://ui.ballmac.com/blocks/features-4","registryUrl":"https://ui.ballmac.com/r/features-4.json","install":"npx shadcn@latest add @ballmac/features-4","summary":"Feature section for Mac or desktop apps. Edit eyebrow/title/description props; change the five BentoCards and their visuals in the source to match your features.","whenToUse":["Desktop or Mac app landing pages","Showing five features with visuals instead of icons"],"whenNotToUse":["Web SaaS feature lists (use features-1 or features-2)"],"composesWith":["hero-5","pricing-1","testimonials-1"],"dependencies":["lucide-react"],"registryDependencies":["shadcn:utils","bento-grid","kbd"],"examples":["features-4-demo"],"states":[],"statesNone":"Static content: nothing to load, submit or fail.","preview":"https://ui.ballmac.com/preview/features-4-demo"},{"name":"features-5","kind":"block","type":"registry:block","title":"Features 5: scrolling product tour","description":"Numbered steps on the left; as each scrolls into view, a sticky panel on the right crossfades to its picture. On phones every step carries its own picture.","category":"blocks","blockCategory":"features","tier":"free","tags":["features","tour","sticky","scroll","steps","how it works"],"version":"1.0.0","updated":"2026-10-01","url":"https://ui.ballmac.com/blocks/features-5","registryUrl":"https://ui.ballmac.com/r/features-5.json","install":"npx shadcn@latest add @ballmac/features-5","summary":"A how-it-works section that shows the product as you read. Pass steps=[{ title, description, points?, visual }] where visual is any ReactNode.","whenToUse":["Explaining a workflow in three to five steps","Products where each step has a distinct screen"],"whenNotToUse":["Long feature lists (use features-2)","Pages without room to scroll"],"composesWith":["hero-7","logo-cloud-1","testimonials-1","cta-1"],"dependencies":["lucide-react","motion@^12"],"registryDependencies":["shadcn:utils","avatar","badge","media"],"examples":["features-5-demo","features-5-custom"],"states":[],"statesNone":"Static content: nothing to load, submit or fail.","preview":"https://ui.ballmac.com/preview/features-5-demo"},{"name":"features-6","kind":"block","type":"registry:block","title":"Features 6: tabbed showcase","description":"Pill tabs with a sliding indicator switch between feature panels: heading, checked points and link beside a product picture. Tabs scroll sideways on phones.","category":"blocks","blockCategory":"features","tier":"free","tags":["features","tabs","showcase","panels","product"],"version":"1.0.0","updated":"2026-10-01","url":"https://ui.ballmac.com/blocks/features-6","registryUrl":"https://ui.ballmac.com/r/features-6.json","install":"npx shadcn@latest add @ballmac/features-6","summary":"A compact way to show several feature areas without a long scroll. Pass tabs=[{ value, label, icon?, title, description, points?, link?, visual }].","whenToUse":["Four to six equal feature areas","Pages that need to stay short"],"whenNotToUse":["A single story told in order (use features-5)"],"composesWith":["hero-6","logo-cloud-1","pricing-2","cta-1"],"dependencies":["lucide-react"],"registryDependencies":["shadcn:utils","animated-tabs","badge","media"],"examples":["features-6-demo","features-6-two"],"states":[],"statesNone":"Static content: nothing to load, submit or fail.","preview":"https://ui.ballmac.com/preview/features-6-demo"},{"name":"features-7","kind":"block","type":"registry:block","title":"Features 7: menu bar app tour","description":"A feature picker for menu bar apps: choose a feature and a miniature desktop shows the app's panel hanging from its menu bar icon, with quick capture, clipboard history, a focus timer and shortcuts drawn from tokens.","category":"blocks","blockCategory":"features","tier":"free","tags":["features","menu bar","mac","tour","shortcuts","panel","utility"],"version":"1.0.0","updated":"2026-10-01","url":"https://ui.ballmac.com/blocks/features-7","registryUrl":"https://ui.ballmac.com/r/features-7.json","install":"npx shadcn@latest add @ballmac/features-7","summary":"For menu bar and utility apps. Pass features=[{ id, title, description, keys?, icon?, panel }] where panel is the UI that hangs from the menu bar icon; time sets the clock in the mock menu bar.","whenToUse":["Menu bar utilities and background apps","Anything the user reaches with a shortcut"],"whenNotToUse":["Window-based apps (use features-4 or showcase-1)"],"composesWith":["hero-5","showcase-1","download-1","pricing-4"],"dependencies":["lucide-react","motion@^12","radix-ui"],"registryDependencies":["shadcn:utils","kbd","media"],"examples":["features-7-demo","features-7-two"],"states":[],"statesNone":"Static content: nothing to load, submit or fail.","preview":"https://ui.ballmac.com/preview/features-7-demo"},{"name":"flags-1","kind":"block","type":"registry:block","title":"Flags 1: feature flags manager","description":"A feature flags manager: a switch per environment, a production rollout slider, flags fully on for months marked ready to remove, a confirmation before changing production, and failed saves undone with the reason.","category":"blocks","blockCategory":"flags","tier":"free","tags":["feature flags","toggles","rollout","release","environments","launchdarkly","experiments","developer","production"],"version":"1.0.0","updated":"2026-10-18","url":"https://ui.ballmac.com/blocks/flags-1","registryUrl":"https://ui.ballmac.com/r/flags-1.json","install":"npx shadcn@latest add @ballmac/flags-1","summary":"A feature flags manager. Promise} />. A flag is 'Ready to remove' when it is on in production at 100% and unchanged for 90 days or more. Changing Production asks first and says who it affects; other environments change at once. Reject onChange and the flag goes back with the message. Rollout moves in steps of 5 and needs Save.","whenToUse":["An internal tool for releasing features gradually","A settings area of a developer product with flags or toggles per environment"],"whenNotToUse":["A user's own preference switches (use settings-1)","A/B test results (use experiments-1)"],"composesWith":["experiments-1","webhooks-1","dev-1","app-shell-1"],"dependencies":["lucide-react"],"registryDependencies":["shadcn:utils","alert-dialog","button","match-highlight","skeleton","slider","state-view","switch","return-focus"],"examples":["flags-1-demo","flags-1-open","flags-1-loading","flags-1-empty","flags-1-error"],"states":[{"id":"loading","title":"Loading","example":"flags-1-loading","trigger":"state=\"loading\"","note":"Skeleton rows under the real heading, announced as loading.","preview":"https://ui.ballmac.com/preview/flags-1-loading"},{"id":"empty","title":"No flags yet","example":"flags-1-empty","trigger":"state=\"empty\" (or flags={[]})","note":"Explains what a flag is; emptyState sets the copy and can add a button. A search with no match says so with Clear filters.","preview":"https://ui.ballmac.com/preview/flags-1-empty"},{"id":"error","title":"Could not load","example":"flags-1-error","trigger":"state=\"error\"","note":"An alert saying nothing was changed, with Try again (onRetry). A change that fails to save is undone with its message under the flag.","preview":"https://ui.ballmac.com/preview/flags-1-error"}],"preview":"https://ui.ballmac.com/preview/flags-1-demo"},{"name":"fleet-1","kind":"block","type":"registry:block","title":"Fleet 1: vehicle fleet","description":"A fleet overview: each vehicle with where it is, status in words, fuel or charge, distance to the next service, and faults, filter by status, message the driver, book a service, all undone with the reason if it fails.","category":"blocks","blockCategory":"fleet","tier":"free","tags":["fleet","vehicles","logistics","transport","telematics","drivers","maintenance","operations"],"version":"1.0.0","updated":"2026-10-24","url":"https://ui.ballmac.com/blocks/fleet-1","registryUrl":"https://ui.ballmac.com/r/fleet-1.json","install":"npx shadcn@latest add @ballmac/fleet-1","summary":"Fleet overview. Promise} onBookService={(vehicle) => Promise} />. Low level and service soon are called out in words.","whenToUse":["A dispatcher or fleet manager overview","Any list of assets with location, level and upkeep"],"whenNotToUse":["A live map; place this beside one","Driver payroll or trips history"],"composesWith":["inspection-1","capacity-1","alerts-1"],"dependencies":["lucide-react"],"registryDependencies":["shadcn:utils","button","skeleton","state-view"],"examples":["fleet-1-demo","fleet-1-service","fleet-1-loading","fleet-1-empty","fleet-1-error"],"states":[{"id":"loading","title":"Loading","example":"fleet-1-loading","trigger":"state=\"loading\"","note":"Skeleton cards under the real heading, announced as loading.","preview":"https://ui.ballmac.com/preview/fleet-1-loading"},{"id":"empty","title":"No vehicles yet","example":"fleet-1-empty","trigger":"state=\"empty\"","note":"Says no vehicles yet; emptyState sets the copy. A filter with no match says so.","preview":"https://ui.ballmac.com/preview/fleet-1-empty"},{"id":"error","title":"Could not load","example":"fleet-1-error","trigger":"state=\"error\"","note":"An alert saying nothing was sent or booked, with Try again (onRetry). An action that fails says why.","preview":"https://ui.ballmac.com/preview/fleet-1-error"}],"preview":"https://ui.ballmac.com/preview/fleet-1-demo"},{"name":"floorplan-1","kind":"block","type":"registry:block","title":"Floorplan 1: restaurant floor","description":"A restaurant floor plan: tables where they stand, worded as free, seated, reserved or needs clearing, a waiting list, seat a party at a table that fits, clear or clean a table, all undone with the reason if it fails.","category":"blocks","blockCategory":"floorplan","tier":"free","tags":["restaurant","floor plan","tables","seating","host","reservations","waitlist","hospitality"],"version":"1.0.0","updated":"2026-10-24","url":"https://ui.ballmac.com/blocks/floorplan-1","registryUrl":"https://ui.ballmac.com/r/floorplan-1.json","install":"npx shadcn@latest add @ballmac/floorplan-1","summary":"Restaurant floor. Promise} onStatus={(tableId, status) => Promise} />. x and y are percentages. Only free or reserved tables that fit the party can be chosen. Changes show at once and are undone if the handler rejects.","whenToUse":["A host stand or front-of-house screen","Any room plan where things have a place and a state (tables, desks, beds)"],"whenNotToUse":["Booking by customers; use salon-1","Seat selection for an event with hundreds of seats"],"composesWith":["salon-1","queues-1","kitchen-1"],"dependencies":["lucide-react"],"registryDependencies":["shadcn:utils","button","skeleton","state-view"],"examples":["floorplan-1-demo","floorplan-1-busy","floorplan-1-loading","floorplan-1-empty","floorplan-1-error"],"states":[{"id":"loading","title":"Loading","example":"floorplan-1-loading","trigger":"state=\"loading\"","note":"Skeleton plan under the real heading, announced as loading.","preview":"https://ui.ballmac.com/preview/floorplan-1-loading"},{"id":"empty","title":"No tables set up","example":"floorplan-1-empty","trigger":"state=\"empty\"","note":"Says no tables are set up; emptyState sets the copy.","preview":"https://ui.ballmac.com/preview/floorplan-1-empty"},{"id":"error","title":"Could not load","example":"floorplan-1-error","trigger":"state=\"error\"","note":"An alert saying nothing was changed, with Try again (onRetry). A seat or clear that fails goes back and says why.","preview":"https://ui.ballmac.com/preview/floorplan-1-error"}],"preview":"https://ui.ballmac.com/preview/floorplan-1-demo"},{"name":"footer-1","kind":"block","type":"registry:block","title":"Footer 1: columns with newsletter","description":"Site footer with brand and tagline, an optional newsletter form, up to four link columns and a legal bar.","category":"blocks","blockCategory":"footer","tier":"free","tags":["footer","newsletter","navigation","links"],"version":"1.0.0","updated":"2026-09-28","url":"https://ui.ballmac.com/blocks/footer-1","registryUrl":"https://ui.ballmac.com/r/footer-1.json","install":"npx shadcn@latest add @ballmac/footer-1","summary":"The bottom of every marketing page. Pass groups of links; pass onSubscribe to show the newsletter form (you handle the email).","whenToUse":["Marketing sites and landing pages"],"whenNotToUse":["App screens behind login (keep chrome minimal)"],"composesWith":["header-1","cta-1"],"dependencies":[],"registryDependencies":["shadcn:utils","button","input"],"examples":["footer-1-demo"],"states":[],"statesNone":"Static content: nothing to load, submit or fail.","preview":"https://ui.ballmac.com/preview/footer-1-demo"},{"name":"footer-2","kind":"block","type":"registry:block","title":"Footer 2: giant wordmark","description":"Brand, tagline and a live status pill beside three link columns, a legal bar with icon links, and an oversized wordmark that sinks into a fading gradient along the bottom.","category":"blocks","blockCategory":"footer","tier":"free","tags":["footer","wordmark","links","status","brand"],"version":"1.0.0","updated":"2026-10-01","url":"https://ui.ballmac.com/blocks/footer-2","registryUrl":"https://ui.ballmac.com/r/footer-2.json","install":"npx shadcn@latest add @ballmac/footer-2","summary":"A confident site footer. Pass columns, socials, legal and legalLinks; the wordmark scales to the footer width from its length.","whenToUse":["Brand-led marketing sites","Pages that end with a big visual moment"],"whenNotToUse":["Footers that need a newsletter form (use footer-1)"],"composesWith":["cta-3","cta-1","faq-2","header-2"],"dependencies":["lucide-react"],"registryDependencies":["shadcn:utils","status-dot"],"examples":["footer-2-demo","footer-2-long"],"states":[],"statesNone":"Static content: nothing to load, submit or fail.","preview":"https://ui.ballmac.com/preview/footer-2-demo"},{"name":"forgot-password-1","kind":"block","type":"registry:block","title":"Forgot Password 1: request, resend and reset","description":"The whole password-recovery flow in one card: request a link, check-your-email with a resend countdown, choose a new password with confirmation and strength, and a success screen. Focus moves to each new heading.","category":"blocks","blockCategory":"auth","tier":"free","tags":["forgot password","reset password","auth","recovery","email","countdown"],"version":"1.1.0","updated":"2026-10-11","url":"https://ui.ballmac.com/blocks/forgot-password-1","registryUrl":"https://ui.ballmac.com/r/forgot-password-1.json","install":"npx shadcn@latest add @ballmac/forgot-password-1","summary":"Use it on /forgot-password (initialView 'request') and on the page the emailed link opens (initialView 'reset'). Pass onRequest(email) and onReset(password); throw to show an error.","whenToUse":["Any app with passwords","The page an emailed reset link opens"],"whenNotToUse":["Passwordless-only products"],"composesWith":["login-2","login-1","verify-1"],"dependencies":["lucide-react"],"registryDependencies":["shadcn:utils","button","field","input","password-input","use-resource"],"examples":["forgot-password-1-demo","forgot-password-1-reset","forgot-password-1-submitting","forgot-password-1-success","forgot-password-1-error"],"states":[{"id":"submitting","title":"Sending the link","example":"forgot-password-1-submitting","trigger":"state=\"submitting\"","note":"Every field and button is disabled while the request is in flight, the button shows a spinner, and the form is marked busy.","preview":"https://ui.ballmac.com/preview/forgot-password-1-submitting"},{"id":"success","title":"Check your email","example":"forgot-password-1-success","trigger":"state=\"success\"","note":"The confirmation screen the flow ends on.","preview":"https://ui.ballmac.com/preview/forgot-password-1-success"},{"id":"error","title":"Could not send","example":"forgot-password-1-error","trigger":"state=\"error\"","note":"An alert above the form with the message (errorState.description to change it); the fields stay editable so it can be fixed.","preview":"https://ui.ballmac.com/preview/forgot-password-1-error"}],"preview":"https://ui.ballmac.com/preview/forgot-password-1-demo"},{"name":"funnel-1","kind":"block","type":"registry:block","title":"Funnel 1: conversion funnel","description":"A conversion funnel: bars sized against the first step, joined by connectors that narrow as people drop away, with share kept and people lost at each step, the biggest leak written out, a group switch and a panel for any chosen step.","category":"blocks","blockCategory":"funnel","tier":"free","tags":["funnel","conversion","analytics","drop-off","checkout","growth","steps","dashboard","metrics"],"version":"1.0.0","updated":"2026-10-18","url":"https://ui.ballmac.com/blocks/funnel-1","registryUrl":"https://ui.ballmac.com/r/funnel-1.json","install":"npx shadcn@latest add @ballmac/funnel-1","summary":"A conversion funnel. . Counts must be people who reached each step, first to last. Share of the first step, share kept from the step before, people lost, overall conversion and the biggest leak (the largest proportional drop) are worked out. A segment switch shows when there are two or more groups.","whenToUse":["Analytics for signup, onboarding or checkout flows","Showing where a growth experiment should focus"],"whenNotToUse":["Results of an A/B test (use experiments-1)","Trends over time (use a chart)"],"composesWith":["experiments-1","app-shell-1","dashboard-1"],"dependencies":["lucide-react"],"registryDependencies":["shadcn:utils","segmented-control","skeleton","state-view"],"examples":["funnel-1-demo","funnel-1-single","funnel-1-loading","funnel-1-empty","funnel-1-error"],"states":[{"id":"loading","title":"Loading","example":"funnel-1-loading","trigger":"state=\"loading\"","note":"Skeleton bars that narrow like the real funnel, under the real heading, announced as loading.","preview":"https://ui.ballmac.com/preview/funnel-1-loading"},{"id":"empty","title":"No data yet","example":"funnel-1-empty","trigger":"state=\"empty\" (or segments={[]})","note":"Says the funnel appears once visitors move through the steps; emptyState sets the copy.","preview":"https://ui.ballmac.com/preview/funnel-1-empty"},{"id":"error","title":"Could not load","example":"funnel-1-error","trigger":"state=\"error\"","note":"An alert with Try again (onRetry).","preview":"https://ui.ballmac.com/preview/funnel-1-error"}],"preview":"https://ui.ballmac.com/preview/funnel-1-demo"},{"name":"gallery-1","kind":"block","type":"registry:block","title":"Gallery 1: filterable gallery with lightbox","description":"A photo gallery: filter chips with counts, a gap-free masonry of tiles that fade in, and a lightbox with caption, counter, thumbnail strip, arrow-key and swipe navigation, and a link to the original.","category":"blocks","blockCategory":"gallery","tier":"free","tags":["gallery","photos","images","masonry","lightbox","portfolio","filter","media","grid","carousel"],"version":"1.0.0","updated":"2026-10-18","url":"https://ui.ballmac.com/blocks/gallery-1","registryUrl":"https://ui.ballmac.com/r/gallery-1.json","install":"npx shadcn@latest add @ballmac/gallery-1","summary":"A gallery page. . src takes a URL, an image with alt text or any element (a next/image); without it the tile shows art drawn from the id. Categories come from the items.","whenToUse":["A photo, event, studio or portfolio gallery","Showing work or places with captions and the option to see each larger"],"whenNotToUse":["A product image carousel on a store page (use carousel)","Logos (use logo-cloud-1)","One hero picture (use media with a frame)"],"composesWith":["header-2","footer-2","cta-1","media"],"dependencies":["lucide-react"],"registryDependencies":["shadcn:utils","button","cover-art","dialog","direction","masonry-grid","media","skeleton","state-view","return-focus"],"examples":["gallery-1-demo","gallery-1-lightbox","gallery-1-team","gallery-1-loading","gallery-1-empty","gallery-1-error"],"states":[{"id":"loading","title":"Loading","example":"gallery-1-loading","trigger":"state=\"loading\"","note":"Skeleton tiles of different heights under the real heading, announced as loading.","preview":"https://ui.ballmac.com/preview/gallery-1-loading"},{"id":"empty","title":"No pictures yet","example":"gallery-1-empty","trigger":"state=\"empty\" (or items={[]})","note":"Says pictures will appear; a category with nothing in it offers Show everything. emptyState sets the copy.","preview":"https://ui.ballmac.com/preview/gallery-1-empty"},{"id":"error","title":"Could not load","example":"gallery-1-error","trigger":"state=\"error\"","note":"An alert with Try again (onRetry).","preview":"https://ui.ballmac.com/preview/gallery-1-error"}],"preview":"https://ui.ballmac.com/preview/gallery-1-demo"},{"name":"gantt-1","kind":"block","type":"registry:block","title":"Gantt 1: project timeline","description":"A project timeline: bars placed by real dates with a progress fill, milestones, dependency arrows, a today line, three zoom levels, a sticky task column, a details panel and a table of the same data for screen readers.","category":"blocks","blockCategory":"gantt","tier":"free","tags":["gantt","timeline","project","schedule","roadmap","planning","milestones","dependencies","project management"],"version":"1.0.0","updated":"2026-10-18","url":"https://ui.ballmac.com/blocks/gantt-1","registryUrl":"https://ui.ballmac.com/r/gantt-1.json","install":"npx shadcn@latest add @ballmac/gantt-1","summary":"A Gantt chart. . Status is worked out for you: done at progress 1, late when the end date has passed, in progress when it has started, planned otherwise. Pass today yourself (an ISO date); the block never reads the clock. A milestone has the same start and end.","whenToUse":["Showing a project plan with dates, progress and dependencies","A read-only schedule overview in a project tool or a client report"],"whenNotToUse":["A board of cards by status (use kanban-1)","Booking rooms or people by the hour (use calendar-pro-1)","A simple list of dated items (use timeline or tasks-1)"],"composesWith":["tasks-1","kanban-1","app-shell-1","calendar-1"],"dependencies":["lucide-react","motion"],"registryDependencies":["shadcn:utils","button","segmented-control","skeleton","state-view"],"examples":["gantt-1-demo","gantt-1-days","gantt-1-months","gantt-1-loading","gantt-1-empty","gantt-1-error"],"states":[{"id":"loading","title":"Loading","example":"gantt-1-loading","trigger":"state=\"loading\"","note":"A skeleton chart under the real heading, announced as loading; zoom and Today are disabled.","preview":"https://ui.ballmac.com/preview/gantt-1-loading"},{"id":"empty","title":"No tasks yet","example":"gantt-1-empty","trigger":"state=\"empty\" (or tasks={[]})","note":"Says the plan draws itself once tasks have dates; emptyState sets the copy and can add a button.","preview":"https://ui.ballmac.com/preview/gantt-1-empty"},{"id":"error","title":"Could not load","example":"gantt-1-error","trigger":"state=\"error\"","note":"An alert saying nothing was changed, with Try again (onRetry).","preview":"https://ui.ballmac.com/preview/gantt-1-error"}],"preview":"https://ui.ballmac.com/preview/gantt-1-demo"},{"name":"goals-1","kind":"block","type":"registry:block","title":"Goals 1: objectives and key results","description":"Objectives and key results for a period: progress worked out from start, current and target, a pace mark on each bar for where it should be today, on track, at risk or behind in words, overall progress, team filter and in-place updates.","category":"blocks","blockCategory":"goals","tier":"free","tags":["goals","okr","okrs","objectives","key results","progress","targets","quarter","planning","team"],"version":"1.0.0","updated":"2026-10-18","url":"https://ui.ballmac.com/blocks/goals-1","registryUrl":"https://ui.ballmac.com/r/goals-1.json","install":"npx shadcn@latest add @ballmac/goals-1","summary":"OKRs. Promise} />. Key result progress is (current - start) / (target - start), clamped 0 to 1, so a target below the start means lower is better. Status compares progress with the share of the period gone: within 10 points On track, within 25 At risk, else Behind, 100% Done. Pass today yourself; the block never reads the clock. Reject onUpdate and the old value returns with the message.","whenToUse":["A team or company goals page","A quarterly review dashboard"],"whenNotToUse":["A project plan with dates and dependencies (use gantt-1)","A list of to-dos (use tasks-1)"],"composesWith":["gantt-1","tasks-1","funnel-1","app-shell-1"],"dependencies":["lucide-react"],"registryDependencies":["shadcn:utils","button","cover-art","input","skeleton","state-view"],"examples":["goals-1-demo","goals-1-late","goals-1-loading","goals-1-empty","goals-1-error"],"states":[{"id":"loading","title":"Loading","example":"goals-1-loading","trigger":"state=\"loading\"","note":"A skeleton summary and objective cards under the real heading, announced as loading.","preview":"https://ui.ballmac.com/preview/goals-1-loading"},{"id":"empty","title":"No goals yet","example":"goals-1-empty","trigger":"state=\"empty\" (or objectives={[]})","note":"Says to set an objective and the results that would show it worked; emptyState sets the copy and can add a button.","preview":"https://ui.ballmac.com/preview/goals-1-empty"},{"id":"error","title":"Could not load","example":"goals-1-error","trigger":"state=\"error\"","note":"An alert saying nothing was changed, with Try again (onRetry). An update that fails to save puts the old number back with the reason.","preview":"https://ui.ballmac.com/preview/goals-1-error"}],"preview":"https://ui.ballmac.com/preview/goals-1-demo"},{"name":"gradebook-1","kind":"block","type":"registry:block","title":"Gradebook 1: class grades","description":"A teacher's gradebook: students down, assignments across, type a score and the weighted average and letter grade update, ungraded work is left out rather than counted as zero, failing students are marked in words, a bad score is refused.","category":"blocks","blockCategory":"gradebook","tier":"free","tags":["education","gradebook","grades","school","teacher","weighted average","class","students"],"version":"1.0.0","updated":"2026-10-24","url":"https://ui.ballmac.com/blocks/gradebook-1","registryUrl":"https://ui.ballmac.com/r/gradebook-1.json","install":"npx shadcn@latest add @ballmac/gradebook-1","summary":"Gradebook. Promise} />. Averages are weighted over graded work only. Scores above the maximum or below 0 are refused with a message.","whenToUse":["A teacher's marking screen","Any grid of people against weighted tasks"],"whenNotToUse":["A report card for parents","A spreadsheet with free formulas; use data-grid"],"composesWith":["roster-1","calendar-1","inspection-1"],"dependencies":["lucide-react"],"registryDependencies":["shadcn:utils","skeleton","state-view"],"examples":["gradebook-1-demo","gradebook-1-ungraded","gradebook-1-loading","gradebook-1-empty","gradebook-1-error"],"states":[{"id":"loading","title":"Loading","example":"gradebook-1-loading","trigger":"state=\"loading\"","note":"Skeleton grid under the real heading, announced as loading.","preview":"https://ui.ballmac.com/preview/gradebook-1-loading"},{"id":"empty","title":"No students yet","example":"gradebook-1-empty","trigger":"state=\"empty\"","note":"Says no students yet; emptyState sets the copy.","preview":"https://ui.ballmac.com/preview/gradebook-1-empty"},{"id":"error","title":"Could not load","example":"gradebook-1-error","trigger":"state=\"error\"","note":"An alert saying no score was changed, with Try again (onRetry). A score that fails to save is put back and says why.","preview":"https://ui.ballmac.com/preview/gradebook-1-error"}],"preview":"https://ui.ballmac.com/preview/gradebook-1-demo"},{"name":"habits-1","kind":"block","type":"registry:block","title":"Habits 1: streaks and weekly goals","description":"A habit tracker: each habit with its streak (kept alive until today ends), best streak, this week against its goal, the last seven days to tick, twelve weeks as a grid, a ring for today, and ticks that go back if they fail.","category":"blocks","blockCategory":"habits","tier":"free","tags":["habits","streak","habit tracker","routine","goals","daily","wellness","consistency","check-in"],"version":"1.0.0","updated":"2026-10-18","url":"https://ui.ballmac.com/blocks/habits-1","registryUrl":"https://ui.ballmac.com/r/habits-1.json","install":"npx shadcn@latest add @ballmac/habits-1","summary":"A habit tracker. Promise} onAdd={({ name, target }) => Promise} />. The streak is the run of days ending today, or yesterday while today is not done yet, so it only breaks when a day is missed. Best streak, this-week count (Monday to today) and the goal are worked out from done. Pass today yourself; the block never reads the clock. Reject onToggle and the day goes back with the message.","whenToUse":["Wellness, learning and productivity apps with daily routines","A team ritual tracker"],"whenNotToUse":["One-off to-dos (use tasks-1)","Long-term targets with numbers (use goals-1)"],"composesWith":["goals-1","tasks-1","leaderboard-1","app-shell-1"],"dependencies":["lucide-react"],"registryDependencies":["shadcn:utils","button","input","skeleton","state-view"],"examples":["habits-1-demo","habits-1-fresh","habits-1-loading","habits-1-empty","habits-1-error"],"states":[{"id":"loading","title":"Loading","example":"habits-1-loading","trigger":"state=\"loading\"","note":"Skeleton cards under the real heading, announced as loading.","preview":"https://ui.ballmac.com/preview/habits-1-loading"},{"id":"empty","title":"No habits yet","example":"habits-1-empty","trigger":"state=\"empty\" (or habits={[]})","note":"Says to pick one small thing to do most days; emptyState sets the copy and can add a button.","preview":"https://ui.ballmac.com/preview/habits-1-empty"},{"id":"error","title":"Could not load","example":"habits-1-error","trigger":"state=\"error\"","note":"An alert saying nothing was lost, with Try again (onRetry). A tick that fails to save goes back with its reason under the habit.","preview":"https://ui.ballmac.com/preview/habits-1-error"}],"preview":"https://ui.ballmac.com/preview/habits-1-demo"},{"name":"header-1","kind":"block","type":"registry:block","title":"Header 1: sticky with mobile menu","description":"Sticky site header with brand, main links, sign-in and primary action, and an accessible mobile menu that closes on Escape or link tap.","category":"blocks","blockCategory":"header","tier":"free","tags":["header","navbar","navigation","mobile menu"],"version":"1.0.0","updated":"2026-09-28","url":"https://ui.ballmac.com/blocks/header-1","registryUrl":"https://ui.ballmac.com/r/header-1.json","install":"npx shadcn@latest add @ballmac/header-1","summary":"The top navigation bar for a marketing site. Pass links and the two actions; it handles the mobile menu.","whenToUse":["Marketing sites and landing pages","Docs sites with a few top-level sections"],"whenNotToUse":["Apps with deep navigation (use a sidebar)"],"composesWith":["hero-1","hero-2","footer-1"],"dependencies":["lucide-react"],"registryDependencies":["shadcn:utils","button"],"examples":["header-1-demo"],"states":[],"statesNone":"Static content: nothing to load, submit or fail.","preview":"https://ui.ballmac.com/preview/header-1-demo"},{"name":"header-2","kind":"block","type":"registry:block","title":"Header 2: mega menu with mobile sheet","description":"Sticky header with brand, a mega menu of grouped links and a featured card, sign-in and primary actions. On phones the same links open in a slide-in sheet with accordions.","category":"blocks","blockCategory":"header","tier":"free","tags":["header","navbar","mega menu","navigation","sheet","mobile"],"version":"1.0.0","updated":"2026-10-01","url":"https://ui.ballmac.com/blocks/header-2","registryUrl":"https://ui.ballmac.com/r/header-2.json","install":"npx shadcn@latest add @ballmac/header-2","summary":"A navigation header for products with many pages. Pass items (the same shape as mega-menu), brand, logo, secondaryAction and primaryAction.","whenToUse":["Sites with several product areas","Anything that outgrew four top-level links"],"whenNotToUse":["Simple sites with a few links (use header-1)"],"composesWith":["hero-6","hero-7","footer-2","template-launch"],"dependencies":["lucide-react"],"registryDependencies":["shadcn:utils","button","mega-menu","sheet"],"examples":["header-2-demo","header-2-simple"],"states":[],"statesNone":"Static content: nothing to load, submit or fail.","preview":"https://ui.ballmac.com/preview/header-2-demo"},{"name":"help-1","kind":"block","type":"registry:block","title":"Help 1: help center home","description":"A help center home: a hero search that suggests articles as you type with highlighted matches, topic cards that light up under the pointer, popular articles, and ways to reach a person with who is online.","category":"blocks","blockCategory":"help","tier":"free","tags":["help center","support","knowledge base","docs","search","faq","categories","contact","self-serve"],"version":"1.0.0","updated":"2026-10-17","url":"https://ui.ballmac.com/blocks/help-1","registryUrl":"https://ui.ballmac.com/r/help-1.json","install":"npx shadcn@latest add @ballmac/help-1","summary":"A help center home. . Search runs in the browser over title and summary; pass onSearch to log queries or fetch your own results.","whenToUse":["The front page of a help center or knowledge base","Self-serve support before people contact you"],"whenNotToUse":["A short list of questions (use faq-1)","A documentation site's navigation (use sidebar and command)","A contact form (use contact-1)"],"composesWith":["header-2","footer-2","faq-1","contact-1"],"dependencies":["lucide-react"],"registryDependencies":["shadcn:utils","blur-fade","button","cover-art","dot-pattern","kbd","match-highlight","skeleton","spotlight-card","state-view"],"examples":["help-1-demo","help-1-searching","help-1-no-results","help-1-loading","help-1-empty","help-1-error"],"states":[{"id":"loading","title":"Loading","example":"help-1-loading","trigger":"state=\"loading\"","note":"Skeleton topic cards and article rows under the real heading; search is disabled.","preview":"https://ui.ballmac.com/preview/help-1-loading"},{"id":"empty","title":"No guides yet","example":"help-1-empty","trigger":"state=\"empty\" (or categories={[]})","note":"Says guides will be listed here; emptyState sets the copy. The contact strip stays.","preview":"https://ui.ballmac.com/preview/help-1-empty"},{"id":"error","title":"Could not load","example":"help-1-error","trigger":"state=\"error\"","note":"An alert with Try again (onRetry). The hero and the contact strip stay, so people can still reach you.","preview":"https://ui.ballmac.com/preview/help-1-error"}],"preview":"https://ui.ballmac.com/preview/help-1-demo"},{"name":"hero-1","kind":"block","type":"registry:block","title":"Hero 1: split with product visual","description":"Split hero: badge, word-by-word headline, two calls to action and proof points on the left, a live product summary card on the right, over an animated grid.","category":"blocks","blockCategory":"hero","tier":"free","tags":["hero","landing","saas","split"],"version":"1.0.0","updated":"2026-09-28","url":"https://ui.ballmac.com/blocks/hero-1","registryUrl":"https://ui.ballmac.com/r/hero-1.json","install":"npx shadcn@latest add @ballmac/hero-1","summary":"The top section of a SaaS or product landing page. Edit the props for copy and swap HeroVisual for your own product screenshot or component.","whenToUse":["Landing pages with a product to show","Launch pages that need a clear primary action"],"whenNotToUse":["Developer tools where the install command is the hero (use hero-2)","AI products where a live prompt sells best (use hero-3)"],"composesWith":["header-1","features-1","cta-1"],"dependencies":["lucide-react"],"registryDependencies":["shadcn:utils","animated-grid","badge","button","number-ticker","text-reveal","media"],"examples":["hero-1-demo"],"states":[],"statesNone":"Static content: nothing to load, submit or fail.","preview":"https://ui.ballmac.com/preview/hero-1-demo"},{"name":"hero-2","kind":"block","type":"registry:block","title":"Hero 2: developer tool with install command","description":"Centered hero for developer tools: headline, two actions, package-manager install tabs and a terminal window with a light beam tracing its border.","category":"blocks","blockCategory":"hero","tier":"free","tags":["hero","developer","cli","open source","install"],"version":"1.0.0","updated":"2026-09-28","url":"https://ui.ballmac.com/blocks/hero-2","registryUrl":"https://ui.ballmac.com/r/hero-2.json","install":"npx shadcn@latest add @ballmac/hero-2","summary":"The top section for a CLI, SDK or library: the install command is the call to action. Set `command` to your package's command without the runner.","whenToUse":["Developer tools, SDKs and open-source libraries","Pages where installing is the first step"],"whenNotToUse":["Consumer or visual products (use hero-1)"],"composesWith":["header-1","features-2","footer-1"],"dependencies":["lucide-react"],"registryDependencies":["shadcn:utils","border-beam","button","install-tabs","terminal","text-reveal"],"examples":["hero-2-demo"],"states":[],"statesNone":"Static content: nothing to load, submit or fail.","preview":"https://ui.ballmac.com/preview/hero-2-demo"},{"name":"hero-3","kind":"block","type":"registry:block","title":"Hero 3: AI product with live prompt","description":"Hero for AI products: a real prompt input on the left, and on the right a mock answer with a reasoning panel, a tool call and a streaming reply.","category":"blocks","blockCategory":"hero","tier":"free","tags":["hero","ai","assistant","prompt","agent"],"version":"1.0.0","updated":"2026-09-28","url":"https://ui.ballmac.com/blocks/hero-3","registryUrl":"https://ui.ballmac.com/r/hero-3.json","install":"npx shadcn@latest add @ballmac/hero-3","summary":"Top section for an AI assistant or agent product. The prompt is real: handle onSubmit (e.g. send visitors to sign-up with their question).","whenToUse":["AI assistants, copilots and agents","Products whose value is best shown as a question and answer"],"whenNotToUse":["Products without a conversational interface (use hero-1)"],"composesWith":["ai-chat-1","features-1","pricing-1"],"dependencies":["lucide-react"],"registryDependencies":["shadcn:utils","badge","prompt-input","reasoning-disclosure","streaming-text","tool-call-card","media"],"examples":["hero-3-demo"],"states":[],"statesNone":"Static content: nothing to load, submit or fail.","preview":"https://ui.ballmac.com/preview/hero-3-demo"},{"name":"hero-4","kind":"block","type":"registry:block","title":"Hero 4: split with interactive globe","description":"Split hero with a live pill, headline, two actions and headline stats beside a large draggable WebGL globe marking your regions.","category":"blocks","blockCategory":"hero","tier":"free","tags":["hero","globe","infrastructure","landing","3d"],"version":"1.0.0","updated":"2026-09-29","url":"https://ui.ballmac.com/blocks/hero-4","registryUrl":"https://ui.ballmac.com/r/hero-4.json","install":"npx shadcn@latest add @ballmac/hero-4","summary":"Top-of-page hero for global or infrastructure products. Edit announcement, title, description, actions, stats and globe markers ([lat, long]).","whenToUse":["Infrastructure, hosting, edge or global-reach products","Companies with offices or users worldwide"],"whenNotToUse":["Products where geography doesn't matter (use hero-1 or hero-2)"],"composesWith":["header-1","logo-cloud-1","features-3"],"dependencies":["lucide-react"],"registryDependencies":["shadcn:utils","button","globe","media"],"examples":["hero-4-demo"],"states":[],"statesNone":"Static content: nothing to load, submit or fail.","preview":"https://ui.ballmac.com/preview/hero-4-demo"},{"name":"hero-5","kind":"block","type":"registry:block","title":"Hero 5: Mac app with opening laptop","description":"Centered hero for a Mac app: shiny highlighted headline, download button and requirements, over a laptop whose lid opens into view on a live app window.","category":"blocks","blockCategory":"hero","tier":"free","tags":["hero","mac app","download","laptop","product"],"version":"1.0.0","updated":"2026-09-29","url":"https://ui.ballmac.com/blocks/hero-5","registryUrl":"https://ui.ballmac.com/r/hero-5.json","install":"npx shadcn@latest add @ballmac/hero-5","summary":"Top of a desktop-app landing page. Edit title, highlight, description, actions and requirements; pass `screen` (an image or your UI) to replace the sample app window.","whenToUse":["Landing pages for Mac or desktop apps","Products whose UI is the selling point"],"whenNotToUse":["Web SaaS without a desktop app (use hero-1)","Mobile apps (compose phone-frame instead)"],"composesWith":["header-1","features-4","pricing-1","template-ledger"],"dependencies":["lucide-react"],"registryDependencies":["shadcn:utils","button","gradient-text","laptop-frame","mac-window"],"examples":["hero-5-demo"],"states":[],"statesNone":"Static content: nothing to load, submit or fail.","preview":"https://ui.ballmac.com/preview/hero-5-demo"},{"name":"hero-6","kind":"block","type":"registry:block","title":"Hero 6: gradient mesh with floating cards","description":"Centered hero over a slowly drifting colour mesh, with gradient headline words and product cards that bob and follow the pointer. Cards stack below the buttons on phones.","category":"blocks","blockCategory":"hero","tier":"free","tags":["hero","gradient","mesh","parallax","floating cards","saas"],"version":"1.0.1","updated":"2026-10-11","url":"https://ui.ballmac.com/blocks/hero-6","registryUrl":"https://ui.ballmac.com/r/hero-6.json","install":"npx shadcn@latest add @ballmac/hero-6","summary":"A bold, friendly landing hero. Edit eyebrow, title, highlight (the gradient words), description, actions and highlights; pass `cards` to replace the floating cards.","whenToUse":["Consumer and prosumer SaaS landing pages","Launches that want a memorable first screen"],"whenNotToUse":["Dense developer tools (use hero-2)","Pages that must stay completely static"],"composesWith":["header-1","logo-cloud-1","features-2","pricing-1"],"dependencies":["lucide-react","motion@^12"],"registryDependencies":["shadcn:utils","badge","button","gradient-text","sparkline","motion-presets"],"examples":["hero-6-demo","hero-6-custom"],"states":[],"statesNone":"Static content: nothing to load, submit or fail.","preview":"https://ui.ballmac.com/preview/hero-6-demo"},{"name":"hero-7","kind":"block","type":"registry:block","title":"Hero 7: product screen that tilts into view","description":"Centered hero with a browser frame that leans back and settles flat as you scroll. Ships a sample dashboard drawn with theme tokens; swap in a screenshot or your own UI.","category":"blocks","blockCategory":"hero","tier":"free","tags":["hero","product","screenshot","scroll","browser","dashboard"],"version":"1.0.0","updated":"2026-10-01","url":"https://ui.ballmac.com/blocks/hero-7","registryUrl":"https://ui.ballmac.com/r/hero-7.json","install":"npx shadcn@latest add @ballmac/hero-7","summary":"A landing hero that lets the product do the talking. Edit eyebrow, title, description and actions; pass `screenshot` ({ src, alt }) or `screen` (any UI laid out 1180px wide) to replace the sample dashboard.","whenToUse":["Products with a strong UI","Pages where a first-screen screenshot sells the product"],"whenNotToUse":["Developer tools led by a command (use hero-2)","Products with no visual UI"],"composesWith":["header-1","logo-cloud-1","features-1","testimonials-1"],"dependencies":["lucide-react","motion@^12"],"registryDependencies":["shadcn:utils","badge","browser-frame","button"],"examples":["hero-7-demo","hero-7-custom"],"states":[],"statesNone":"Static content: nothing to load, submit or fail.","preview":"https://ui.ballmac.com/preview/hero-7-demo"},{"name":"import-1","kind":"block","type":"registry:block","title":"Import 1: CSV import with column matching","description":"A data import in four steps: choose a CSV, match its columns to your fields (found for you where names are alike), review which rows are ready and which have problems and why, then import with progress and a summary.","category":"blocks","blockCategory":"import","tier":"free","tags":["import","csv","spreadsheet","upload","column mapping","data migration","validation","bulk","contacts","wizard"],"version":"1.0.0","updated":"2026-10-18","url":"https://ui.ballmac.com/blocks/import-1","registryUrl":"https://ui.ballmac.com/r/import-1.json","install":"npx shadcn@latest add @ballmac/import-1","summary":"A CSV importer. string | null }]} sampleCsv onImport={(rows, progress) => Promise} defaultStep />. Columns are matched by key, label and aliases; required fields must be matched; each row is checked for missing required values, validate() reasons and duplicate emails; only passing rows reach onImport, which can call progress(done). Reject onImport to show its message and keep the rows. Without onImport a run is simulated.","whenToUse":["Importing contacts, products or users from a spreadsheet","Migrating data from another tool"],"whenNotToUse":["Uploading files of any kind (use upload-1)","Editing rows in place (use a data table)"],"composesWith":["upload-1","app-shell-1","data-table"],"dependencies":["lucide-react"],"registryDependencies":["shadcn:utils","button","progress","select","skeleton","state-view"],"examples":["import-1-demo","import-1-match","import-1-review","import-1-loading","import-1-error"],"states":[{"id":"loading","title":"Loading","example":"import-1-loading","trigger":"state=\"loading\"","note":"A skeleton card under the real heading, announced as loading.","preview":"https://ui.ballmac.com/preview/import-1-loading"},{"id":"error","title":"Could not load","example":"import-1-error","trigger":"state=\"error\"","note":"An alert with Try again (onRetry). A failed import keeps you on the last step with your rows and a Try again button.","preview":"https://ui.ballmac.com/preview/import-1-error"}],"preview":"https://ui.ballmac.com/preview/import-1-demo"},{"name":"inbox-1","kind":"block","type":"registry:block","title":"Inbox 1: notifications page","description":"A notifications page grouped by day: unread marked by an accent, mentions and comments with excerpts, requests answered inline (Approve, Deny, Accept, Decline), keyboard triage and an Undo bar after archiving.","category":"blocks","blockCategory":"notifications","tier":"free","tags":["notifications","inbox","activity","alerts","mentions","unread","archive","approvals","triage","keyboard"],"version":"1.0.0","updated":"2026-10-17","url":"https://ui.ballmac.com/blocks/inbox-1","registryUrl":"https://ui.ballmac.com/r/inbox-1.json","install":"npx shadcn@latest add @ballmac/inbox-1","summary":"A notifications page. . Items render as \"actor action target\"; give a system item only an action. Answering an inline request shows its outcome at once.","whenToUse":["The full page behind a notification bell","Mentions, comments and requests that people answer without opening each one"],"whenNotToUse":["A dropdown from a bell (use notification-center)","Email-style threads (use mail-1)","Notification preferences (use settings-2)"],"composesWith":["app-shell-1","settings-2","agent-2","chat-1"],"dependencies":["lucide-react"],"registryDependencies":["shadcn:utils","blur-fade","button","kbd","segmented-control","skeleton","state-view"],"examples":["inbox-1-demo","inbox-1-mentions","inbox-1-empty","inbox-1-loading","inbox-1-error"],"states":[{"id":"loading","title":"Loading","example":"inbox-1-loading","trigger":"state=\"loading\"","note":"Skeleton notifications under the real heading, announced as loading; the filter and Mark all as read are disabled.","preview":"https://ui.ballmac.com/preview/inbox-1-loading"},{"id":"empty","title":"All caught up","example":"inbox-1-empty","trigger":"state=\"empty\" (or nothing in the chosen view)","note":"A friendly message that changes with the view (all, unread, mentions); emptyState sets the copy.","preview":"https://ui.ballmac.com/preview/inbox-1-empty"},{"id":"error","title":"Could not load","example":"inbox-1-error","trigger":"state=\"error\"","note":"An alert saying nothing was lost, with Try again (onRetry).","preview":"https://ui.ballmac.com/preview/inbox-1-error"}],"preview":"https://ui.ballmac.com/preview/inbox-1-demo"},{"name":"incident-1","kind":"block","type":"registry:block","title":"Incident 1: incident command","description":"The page for people fixing an incident: severity and status in words, the impact, who holds commander, comms and ops, a form that posts an update with its new status, updates newest first, and a Resolve button that asks first.","category":"blocks","blockCategory":"incident","tier":"free","tags":["incident","outage","sre","status","severity","postmortem","on-call","devops"],"version":"1.0.0","updated":"2026-10-24","url":"https://ui.ballmac.com/blocks/incident-1","registryUrl":"https://ui.ballmac.com/r/incident-1.json","install":"npx shadcn@latest add @ballmac/incident-1","summary":"An incident command page. Promise} onResolve={() => Promise} onAssign={(role, person) => void} />. Pass incident={null} for no incident. Resolve asks first, posts a final update and closes the form.","whenToUse":["The shared page during an outage","A status workflow where updates and roles are tracked in one place"],"whenNotToUse":["A public status page for customers; use status-1","A list of past incidents; use a table or tickets-1"],"composesWith":["status-1","oncall-1","audit-1","app-shell-1"],"dependencies":["lucide-react"],"registryDependencies":["shadcn:utils","alert-dialog","button","skeleton","state-view","return-focus"],"examples":["incident-1-demo","incident-1-resolved","incident-1-loading","incident-1-empty","incident-1-error"],"states":[{"id":"loading","title":"Loading","example":"incident-1-loading","trigger":"state=\"loading\"","note":"Skeleton for the header, roles and timeline under the page, announced as loading.","preview":"https://ui.ballmac.com/preview/incident-1-loading"},{"id":"empty","title":"No incident right now","example":"incident-1-empty","trigger":"state=\"empty\"","note":"Says there is no incident right now; emptyState sets the copy.","preview":"https://ui.ballmac.com/preview/incident-1-empty"},{"id":"error","title":"Could not load","example":"incident-1-error","trigger":"state=\"error\"","note":"An alert saying nothing was posted, with Try again (onRetry). A failed update keeps your text and says why.","preview":"https://ui.ballmac.com/preview/incident-1-error"}],"preview":"https://ui.ballmac.com/preview/incident-1-demo"},{"name":"inspection-1","kind":"block","type":"registry:block","title":"Inspection 1: checklist inspection","description":"A field inspection checklist: pass, fail or not applicable on each item with what to look for, a required note when something fails, progress through each section, and a submit that says exactly what is missing.","category":"blocks","blockCategory":"inspection","tier":"free","tags":["inspection","checklist","audit","safety","field","compliance","facilities","form"],"version":"1.0.0","updated":"2026-10-24","url":"https://ui.ballmac.com/blocks/inspection-1","registryUrl":"https://ui.ballmac.com/r/inspection-1.json","install":"npx shadcn@latest add @ballmac/inspection-1","summary":"Inspection checklist. Promise} />. A failed item needs a note. Submitting with gaps lists exactly which items are open and moves focus to the first.","whenToUse":["Safety, hygiene or quality inspections on a phone or tablet","Any pass or fail checklist with evidence"],"whenNotToUse":["A survey with free-form questions; use form items","Onboarding steps; use checklist"],"composesWith":["fleet-1","kitchen-1","workorder-1"],"dependencies":["lucide-react"],"registryDependencies":["shadcn:utils","button","skeleton","state-view"],"examples":["inspection-1-demo","inspection-1-done","inspection-1-loading","inspection-1-empty","inspection-1-error"],"states":[{"id":"loading","title":"Loading","example":"inspection-1-loading","trigger":"state=\"loading\"","note":"Skeleton checklist under the real heading, announced as loading.","preview":"https://ui.ballmac.com/preview/inspection-1-loading"},{"id":"empty","title":"No inspection assigned","example":"inspection-1-empty","trigger":"state=\"empty\"","note":"Says no inspection is assigned; emptyState sets the copy.","preview":"https://ui.ballmac.com/preview/inspection-1-empty"},{"id":"error","title":"Could not load","example":"inspection-1-error","trigger":"state=\"error\"","note":"An alert saying nothing was submitted, with Try again (onRetry). A submit that fails keeps every answer and says why.","preview":"https://ui.ballmac.com/preview/inspection-1-error"}],"preview":"https://ui.ballmac.com/preview/inspection-1-demo"},{"name":"integrations-1","kind":"block","type":"registry:block","title":"Integrations 1: directory","description":"A public integrations directory: search that highlights matches, category filters with counts, cards showing what is connected, and a side sheet with what it does and a Connect button that handles waiting and failure.","category":"blocks","blockCategory":"integrations","tier":"free","tags":["integrations","marketplace","apps","directory","connect","plugins","partners","ecosystem"],"version":"1.0.0","updated":"2026-10-18","url":"https://ui.ballmac.com/blocks/integrations-1","registryUrl":"https://ui.ballmac.com/r/integrations-1.json","install":"npx shadcn@latest add @ballmac/integrations-1","summary":"An integrations directory. Promise} onDisconnect defaultOpenId />. Categories come from the data and show counts for the current search. Reject onConnect to show its message in the sheet.","whenToUse":["A marketing page listing what the product connects to","An in-app integrations settings page"],"whenNotToUse":["A row of partner logos (use logo-cloud-1)","Step-by-step setup of one connection (use a wizard)"],"composesWith":["hero-1","logo-cloud-1","cta-1","settings-1","footer-1"],"dependencies":["lucide-react"],"registryDependencies":["shadcn:utils","badge","button","cover-art","match-highlight","sheet","skeleton","state-view"],"examples":["integrations-1-demo","integrations-1-open","integrations-1-loading","integrations-1-empty","integrations-1-error"],"states":[{"id":"loading","title":"Loading","example":"integrations-1-loading","trigger":"state=\"loading\"","note":"Skeleton cards under the real heading, announced as loading.","preview":"https://ui.ballmac.com/preview/integrations-1-loading"},{"id":"empty","title":"No integrations","example":"integrations-1-empty","trigger":"state=\"empty\" (or integrations={[]})","note":"Explains that integrations appear here when added; emptyState sets the copy and can add a button. A search with no match says so with a Clear filters button.","preview":"https://ui.ballmac.com/preview/integrations-1-empty"},{"id":"error","title":"Could not load","example":"integrations-1-error","trigger":"state=\"error\"","note":"An alert with Try again (onRetry). A failed connect shows its message in the sheet.","preview":"https://ui.ballmac.com/preview/integrations-1-error"}],"preview":"https://ui.ballmac.com/preview/integrations-1-demo"},{"name":"inventory-1","kind":"block","type":"registry:block","title":"Inventory 1: stock levels and reordering","description":"A stock overview: stock value, lines low or out, units on the way, and every item with a bar against its reorder point, days of cover at today's pace, status in words, and an order form that suggests how many to buy.","category":"blocks","blockCategory":"inventory","tier":"free","tags":["inventory","stock","warehouse","reorder","products","sku","supply","ecommerce","low stock","levels"],"version":"1.0.0","updated":"2026-10-18","url":"https://ui.ballmac.com/blocks/inventory-1","registryUrl":"https://ui.ballmac.com/r/inventory-1.json","install":"npx shadcn@latest add @ballmac/inventory-1","summary":"A stock overview. Promise} />. Status is Out of stock (0), Low (at or under reorderAt), Plenty (over four times reorderAt) or In stock; days left is onHand divided by perDay; stock value is onHand times cost. The suggested order is two reorder points plus fourteen days of sales, minus what is on hand and on the way. Reject onReorder to show the reason; nothing is marked as ordered.","whenToUse":["An ecommerce or warehouse admin: what to reorder first","A restaurant or retail back office"],"whenNotToUse":["A customer-facing product page","Order history (use a data table)"],"composesWith":["tickets-1","invoice-1","funnel-1","app-shell-1"],"dependencies":["lucide-react"],"registryDependencies":["shadcn:utils","button","input","match-highlight","skeleton","state-view"],"examples":["inventory-1-demo","inventory-1-ordering","inventory-1-loading","inventory-1-empty","inventory-1-error"],"states":[{"id":"loading","title":"Loading","example":"inventory-1-loading","trigger":"state=\"loading\"","note":"Skeleton cards and table under the real heading, announced as loading.","preview":"https://ui.ballmac.com/preview/inventory-1-loading"},{"id":"empty","title":"No stock recorded","example":"inventory-1-empty","trigger":"state=\"empty\" (or items={[]})","note":"Says to add products or connect a store; emptyState sets the copy. A search with no match says so with Clear filters.","preview":"https://ui.ballmac.com/preview/inventory-1-empty"},{"id":"error","title":"Could not load","example":"inventory-1-error","trigger":"state=\"error\"","note":"An alert saying nothing was changed, with Try again (onRetry). An order that fails says nothing was charged, in place.","preview":"https://ui.ballmac.com/preview/inventory-1-error"}],"preview":"https://ui.ballmac.com/preview/inventory-1-demo"},{"name":"invite-1","kind":"block","type":"registry:block","title":"Invite 1: accept a team invitation","description":"The page an invitation email opens: workspace tile, who invited you, your role and what it allows, the account being used, accept and decline, with welcome, declined and expired states.","category":"blocks","blockCategory":"onboarding","tier":"free","tags":["invite","invitation","team","workspace","accept","join"],"version":"1.1.0","updated":"2026-10-11","url":"https://ui.ballmac.com/blocks/invite-1","registryUrl":"https://ui.ballmac.com/r/invite-1.json","install":"npx shadcn@latest add @ballmac/invite-1","summary":"Landing page for an emailed invitation. Pass workspace, inviter, role, email, access, onAccept / onDecline / onRequestNew (throw to show an error) and status ('pending' | 'expired').","whenToUse":["Team and workspace invitations","Sharing links that need an explicit accept"],"whenNotToUse":["Sending invitations (use invite-members)"],"composesWith":["signup-1","login-2","onboarding-1","verify-1"],"dependencies":["lucide-react"],"registryDependencies":["shadcn:utils","badge","button","media","use-resource"],"examples":["invite-1-demo","invite-1-expired","invite-1-joining","invite-1-welcome","invite-1-error"],"states":[{"id":"submitting","title":"Joining","example":"invite-1-joining","trigger":"state=\"submitting\"","note":"Every field and button is disabled while the request is in flight, the button shows a spinner, and the form is marked busy.","preview":"https://ui.ballmac.com/preview/invite-1-joining"},{"id":"success","title":"Welcome","example":"invite-1-welcome","trigger":"state=\"success\"","note":"The confirmation screen the flow ends on.","preview":"https://ui.ballmac.com/preview/invite-1-welcome"},{"id":"error","title":"Could not join","example":"invite-1-error","trigger":"state=\"error\"","note":"An alert above the form with the message (errorState.description to change it); the fields stay editable so it can be fixed.","preview":"https://ui.ballmac.com/preview/invite-1-error"},{"id":"expired","title":"Expired","example":"invite-1-expired","trigger":"status=\"expired\"","note":"The invitation has run out: the page says so and offers to ask for a new one.","preview":"https://ui.ballmac.com/preview/invite-1-expired"}],"preview":"https://ui.ballmac.com/preview/invite-1-demo"},{"name":"invoice-1","kind":"block","type":"registry:block","title":"Invoice 1: invoice you can pay","description":"An invoice you can read, print and pay: parties, dates and line items, totals worked out from the lines, a status from the dates (paid, due in N days, overdue by N days) and a Pay now that handles waiting and failure.","category":"blocks","blockCategory":"invoice","tier":"free","tags":["invoice","billing","payment","receipt","bill","line items","tax","pay now","print","accounting"],"version":"1.0.0","updated":"2026-10-18","url":"https://ui.ballmac.com/blocks/invoice-1","registryUrl":"https://ui.ballmac.com/r/invoice-1.json","install":"npx shadcn@latest add @ballmac/invoice-1","summary":"An invoice. Promise} onDownload />. Subtotal, discount, tax and total are worked out from the lines; status is paid (paidOn set or payment succeeded), overdue by N days, or due in N days, from due and today. Pass today yourself; the block never reads the clock. Reject onPay to show its message.","whenToUse":["A customer-facing invoice page or a payment link","An invoice detail in a billing area"],"whenNotToUse":["A list of invoices (use a data table)","Changing plans with proration (use billing-2)"],"composesWith":["billing-1","billing-2","app-shell-1","settings-5"],"dependencies":["lucide-react"],"registryDependencies":["shadcn:utils","button","skeleton","state-view"],"examples":["invoice-1-demo","invoice-1-due","invoice-1-paid","invoice-1-loading","invoice-1-error"],"states":[{"id":"loading","title":"Loading","example":"invoice-1-loading","trigger":"state=\"loading\"","note":"A skeleton sheet announced as loading.","preview":"https://ui.ballmac.com/preview/invoice-1-loading"},{"id":"error","title":"Could not load","example":"invoice-1-error","trigger":"state=\"error\"","note":"An alert with Try again (onRetry). A failed payment says you were not charged, in place beside Pay now.","preview":"https://ui.ballmac.com/preview/invoice-1-error"}],"preview":"https://ui.ballmac.com/preview/invoice-1-demo"},{"name":"kanban-1","kind":"block","type":"registry:block","title":"Kanban 1: project board with drag and keyboard moves","description":"A project board: columns with counts, rich task cards (tags, priority, due date, comments, assignee), drag and drop with a drop indicator, keyboard pick-up and move with announcements, a Move-to menu, quick add and a person filter.","category":"blocks","blockCategory":"kanban","tier":"free","tags":["kanban","board","tasks","drag and drop","project","keyboard"],"version":"1.1.0","updated":"2026-10-11","url":"https://ui.ballmac.com/blocks/kanban-1","registryUrl":"https://ui.ballmac.com/r/kanban-1.json","install":"npx shadcn@latest add @ballmac/kanban-1","summary":"A task board. Pass defaultColumns=[{ id, title, tasks: [{ id, title, tags?, priority?, assignee?, due?, comments? }] }] and onChange(columns).","whenToUse":["Project and sprint boards","Pipelines, hiring and support queues"],"whenNotToUse":["A simple list of tasks (use a table)"],"composesWith":["app-shell-1","calendar-1","mail-1"],"dependencies":["lucide-react"],"registryDependencies":["shadcn:utils","avatar","badge","button","dropdown-menu","input","state-view","skeleton"],"examples":["kanban-1-demo","kanban-1-simple","kanban-1-loading","kanban-1-error","kanban-1-no-cards"],"states":[{"id":"loading","title":"Loading","example":"kanban-1-loading","trigger":"state=\"loading\"","note":"A skeleton with the same shapes as the ready view, announced as loading; nothing is clickable.","preview":"https://ui.ballmac.com/preview/kanban-1-loading"},{"id":"empty","title":"No cards","example":"kanban-1-no-cards","trigger":"state=\"empty\"","note":"A clear message that there is nothing yet. emptyState sets the copy and can add an action.","preview":"https://ui.ballmac.com/preview/kanban-1-no-cards"},{"id":"error","title":"Could not load","example":"kanban-1-error","trigger":"state=\"error\"","note":"An error with a Try again button (onRetry), announced as an alert.","preview":"https://ui.ballmac.com/preview/kanban-1-error"}],"preview":"https://ui.ballmac.com/preview/kanban-1-demo"},{"name":"kitchen-1","kind":"block","type":"registry:block","title":"Kitchen 1: kitchen display","description":"A kitchen display: a column per station with the oldest ticket first, items with their changes, allergies always spelled out, late and due-soon tickets written in words, a Bump button and a one-step Recall.","category":"blocks","blockCategory":"kitchen","tier":"free","tags":["kitchen display","restaurant","orders","pos","tickets","hospitality","food service","kds"],"version":"1.0.0","updated":"2026-10-24","url":"https://ui.ballmac.com/blocks/kitchen-1","registryUrl":"https://ui.ballmac.com/r/kitchen-1.json","install":"npx shadcn@latest add @ballmac/kitchen-1","summary":"A kitchen display system. Promise} onRecall={(ticket) => Promise} />. A ticket is Due soon at 80% of its target and Late past it. It keeps no clock: update elapsed from your own timer or server.","whenToUse":["A screen over the pass in a restaurant or ghost kitchen","Any station-by-station queue where each job has a target time"],"whenNotToUse":["Taking orders at a till; use an ecommerce checkout block","Pick lists in a warehouse; use dispatch-1 or inventory-1"],"composesWith":["dispatch-1","inventory-1","app-shell-1","status-1"],"dependencies":["lucide-react"],"registryDependencies":["shadcn:utils","button","skeleton","state-view"],"examples":["kitchen-1-demo","kitchen-1-loading","kitchen-1-empty","kitchen-1-error"],"states":[{"id":"loading","title":"Loading","example":"kitchen-1-loading","trigger":"state=\"loading\"","note":"Skeleton columns under the real heading, announced as loading.","preview":"https://ui.ballmac.com/preview/kitchen-1-loading"},{"id":"empty","title":"No tickets","example":"kitchen-1-empty","trigger":"state=\"empty\"","note":"Says no tickets; emptyState sets the copy.","preview":"https://ui.ballmac.com/preview/kitchen-1-empty"},{"id":"error","title":"Could not load","example":"kitchen-1-error","trigger":"state=\"error\"","note":"An alert saying nothing was bumped, with Try again (onRetry). A bump that fails puts the ticket back and says why.","preview":"https://ui.ballmac.com/preview/kitchen-1-error"}],"preview":"https://ui.ballmac.com/preview/kitchen-1-demo"},{"name":"leaderboard-1","kind":"block","type":"registry:block","title":"Leaderboard 1: podium and rankings","description":"A leaderboard: a podium with the leader raised, ranked rows with bars against the leader's score, movement written in words, a week, month and all-time switch, a search, and your own place highlighted and pinned.","category":"blocks","blockCategory":"leaderboard","tier":"free","tags":["leaderboard","ranking","podium","scores","gamification","community","top users","contest","competition"],"version":"1.0.0","updated":"2026-10-18","url":"https://ui.ballmac.com/blocks/leaderboard-1","registryUrl":"https://ui.ballmac.com/r/leaderboard-1.json","install":"npx shadcn@latest add @ballmac/leaderboard-1","summary":"A ranked board. . The block sorts by the chosen period and numbers the ranks itself; change is how many places a person moved (positive is up). Mark the signed-in user with isYou.","whenToUse":["Community, sales, support or learning rankings","A contest or challenge board"],"whenNotToUse":["A table of data with many columns (use data-table)","Showing one person's stats (use stat-card or profile-1)"],"composesWith":["profile-1","app-shell-1","stat-card","header-2"],"dependencies":["lucide-react"],"registryDependencies":["shadcn:utils","avatar","blur-fade","button","cover-art","number-ticker","segmented-control","skeleton","state-view"],"examples":["leaderboard-1-demo","leaderboard-1-pinned","leaderboard-1-loading","leaderboard-1-empty","leaderboard-1-error"],"states":[{"id":"loading","title":"Loading","example":"leaderboard-1-loading","trigger":"state=\"loading\"","note":"A skeleton podium and rows under the real heading, announced as loading; the period switch is disabled.","preview":"https://ui.ballmac.com/preview/leaderboard-1-loading"},{"id":"empty","title":"No scores yet","example":"leaderboard-1-empty","trigger":"state=\"empty\" (or entries={[]})","note":"A friendly message that the board fills up with the first points; emptyState sets the copy.","preview":"https://ui.ballmac.com/preview/leaderboard-1-empty"},{"id":"error","title":"Could not load","example":"leaderboard-1-error","trigger":"state=\"error\"","note":"An alert with Try again (onRetry).","preview":"https://ui.ballmac.com/preview/leaderboard-1-error"}],"preview":"https://ui.ballmac.com/preview/leaderboard-1-demo"},{"name":"listing-1","kind":"block","type":"registry:block","title":"Listing 1: property listing","description":"A property page: a photo gallery with buttons, thumbnails and arrow keys, price and the facts that matter, description and features, and a viewing request form with times to choose from, field errors and a clear result.","category":"blocks","blockCategory":"listing","tier":"free","tags":["real estate","property","listing","estate agent","gallery","viewing","rent","homes"],"version":"1.0.0","updated":"2026-10-24","url":"https://ui.ballmac.com/blocks/listing-1","registryUrl":"https://ui.ballmac.com/r/listing-1.json","install":"npx shadcn@latest add @ballmac/listing-1","summary":"A property listing page. Promise} />. Photos use Media with generated artwork until you pass media. listing={null} shows the no-longer-available state.","whenToUse":["An estate agent's or landlord's property page","Any single-item page with a gallery, key facts and a booking request"],"whenNotToUse":["A search results grid; use directory-1","A product page in a shop; use the ecommerce blocks"],"composesWith":["directory-1","locations-1","gallery-1","header-1"],"dependencies":["lucide-react"],"registryDependencies":["shadcn:utils","button","cover-art","media","skeleton","state-view"],"examples":["listing-1-demo","listing-1-rent","listing-1-loading","listing-1-empty","listing-1-error"],"states":[{"id":"loading","title":"Loading","example":"listing-1-loading","trigger":"state=\"loading\"","note":"Skeleton for the gallery, facts and form under the page, announced as loading.","preview":"https://ui.ballmac.com/preview/listing-1-loading"},{"id":"empty","title":"Listing unavailable","example":"listing-1-empty","trigger":"state=\"empty\"","note":"Says the listing is no longer available and points back to search; pass listing={null}.","preview":"https://ui.ballmac.com/preview/listing-1-empty"},{"id":"error","title":"Could not load","example":"listing-1-error","trigger":"state=\"error\"","note":"An alert saying to check the connection, with Try again (onRetry).","preview":"https://ui.ballmac.com/preview/listing-1-error"}],"preview":"https://ui.ballmac.com/preview/listing-1-demo"},{"name":"locations-1","kind":"block","type":"registry:block","title":"Locations 1: finder on a world map","description":"A locations finder on a dotted world map: pressable pins, a searchable list, filters by type, and a card for the chosen place with address, contacts, directions and whether it is open now in its own time zone.","category":"blocks","blockCategory":"locations","tier":"free","tags":["locations","store locator","offices","map","find us","stores","branches","opening hours","contact"],"version":"1.0.0","updated":"2026-10-18","url":"https://ui.ballmac.com/blocks/locations-1","registryUrl":"https://ui.ballmac.com/r/locations-1.json","install":"npx shadcn@latest add @ballmac/locations-1","summary":"A locations finder. . Open now, closing and opening times are worked out from now, each utcOffset and hours (days default to Monday to Friday). Pass now yourself; the block never reads the clock. Pins are real buttons placed from lat and lng.","whenToUse":["A contact or find-us page for a business with several offices or shops","A store locator on a marketing site"],"whenNotToUse":["One address with a map embed","Turn-by-turn routes or live traffic"],"composesWith":["contact-1","footer-1","about-1","directory-1"],"dependencies":["lucide-react"],"registryDependencies":["shadcn:utils","button","dotted-map","match-highlight","skeleton","state-view"],"examples":["locations-1-demo","locations-1-night","locations-1-loading","locations-1-empty","locations-1-error"],"states":[{"id":"loading","title":"Loading","example":"locations-1-loading","trigger":"state=\"loading\"","note":"A skeleton list and map under the real heading, announced as loading.","preview":"https://ui.ballmac.com/preview/locations-1-loading"},{"id":"empty","title":"No locations","example":"locations-1-empty","trigger":"state=\"empty\" (or places={[]})","note":"Says places appear when a shop or office opens; emptyState sets the copy. A search with no match says so with Clear.","preview":"https://ui.ballmac.com/preview/locations-1-empty"},{"id":"error","title":"Could not load","example":"locations-1-error","trigger":"state=\"error\"","note":"An alert with Try again (onRetry).","preview":"https://ui.ballmac.com/preview/locations-1-error"}],"preview":"https://ui.ballmac.com/preview/locations-1-demo"},{"name":"login-1","kind":"block","type":"registry:block","title":"Login 1: card with SSO and magic link","description":"Centered sign-in card: SSO and email-link buttons, an email and password form with remember me, a loading submit and an inline error.","category":"blocks","blockCategory":"auth","tier":"free","tags":["login","sign in","auth","form","sso"],"version":"1.1.0","updated":"2026-10-11","url":"https://ui.ballmac.com/blocks/login-1","registryUrl":"https://ui.ballmac.com/r/login-1.json","install":"npx shadcn@latest add @ballmac/login-1","summary":"A sign-in screen. Wire onSubmit to your auth (it can be async; the button shows a spinner), pass error to show failures, and onSso/onMagicLink for passwordless options.","whenToUse":["App sign-in pages","Admin or dashboard login"],"whenNotToUse":["Sign-up with many fields (build a form from input, label and checkbox)"],"composesWith":["footer-1"],"dependencies":["lucide-react"],"registryDependencies":["shadcn:utils","button","checkbox","input","label","use-resource"],"examples":["login-1-demo","login-1-submitting","login-1-error"],"states":[{"id":"submitting","title":"Signing in","example":"login-1-submitting","trigger":"state=\"submitting\"","note":"Every field and button is disabled while the request is in flight, the button shows a spinner, and the form is marked busy.","preview":"https://ui.ballmac.com/preview/login-1-submitting"},{"id":"error","title":"Wrong password","example":"login-1-error","trigger":"state=\"error\"","note":"An alert above the form with the message (errorState.description to change it); the fields stay editable so it can be fixed.","preview":"https://ui.ballmac.com/preview/login-1-error"}],"preview":"https://ui.ballmac.com/preview/login-1-demo"},{"name":"login-2","kind":"block","type":"registry:block","title":"Login 2: split screen with testimonial","description":"A split-screen sign-in: SSO and passkey buttons, validated email and password with show/hide, remember me and error state on one side, a soft colour mesh with a customer quote on the other.","category":"blocks","blockCategory":"auth","tier":"free","tags":["login","sign in","auth","split screen","passkey","sso"],"version":"1.1.0","updated":"2026-10-11","url":"https://ui.ballmac.com/blocks/login-2","registryUrl":"https://ui.ballmac.com/r/login-2.json","install":"npx shadcn@latest add @ballmac/login-2","summary":"A full-width sign-in page. Pass onSubmit(values) (throw to show errorMessage), onSso / onPasskey (null hides), quote and author, or visual to replace the right side.","whenToUse":["Product sign-in pages with room for a brand moment","Apps with SSO and passkeys"],"whenNotToUse":["Small centered dialogs (use login-1)"],"composesWith":["signup-1","forgot-password-1","verify-1"],"dependencies":["lucide-react"],"registryDependencies":["shadcn:utils","button","checkbox","field","input","password-input","media","use-resource"],"examples":["login-2-demo","login-2-error","login-2-submitting","login-2-failed"],"states":[{"id":"submitting","title":"Signing in","example":"login-2-submitting","trigger":"state=\"submitting\"","note":"Every field and button is disabled while the request is in flight, the button shows a spinner, and the form is marked busy.","preview":"https://ui.ballmac.com/preview/login-2-submitting"},{"id":"error","title":"Wrong password","example":"login-2-failed","trigger":"state=\"error\"","note":"An alert above the form with the message (errorState.description to change it); the fields stay editable so it can be fixed.","preview":"https://ui.ballmac.com/preview/login-2-failed"}],"preview":"https://ui.ballmac.com/preview/login-2-demo"},{"name":"logo-cloud-1","kind":"block","type":"registry:block","title":"Logo Cloud 1: marquee or grid","description":"Customer logos as an endlessly scrolling row with faded edges, or a static grid with hairline dividers. Wordmarks brighten on hover.","category":"blocks","blockCategory":"logo-cloud","tier":"free","tags":["logos","social proof","customers","marquee"],"version":"1.0.0","updated":"2026-09-29","url":"https://ui.ballmac.com/blocks/logo-cloud-1","registryUrl":"https://ui.ballmac.com/r/logo-cloud-1.json","install":"npx shadcn@latest add @ballmac/logo-cloud-1","summary":"Social proof strip under a hero. Pass `logos` ({ name, icon? | logo? }[]) with your customers' SVG logos via `logo`; choose variant \"marquee\" or \"grid\".","whenToUse":["Directly under a hero","Near pricing to reassure buyers"],"whenNotToUse":["Fewer than four logos (use a single line of text)"],"composesWith":["hero-1","hero-2","testimonials-1"],"dependencies":["lucide-react"],"registryDependencies":["shadcn:utils","marquee"],"examples":["logo-cloud-1-demo","logo-cloud-1-grid"],"states":[],"statesNone":"Static content: nothing to load, submit or fail.","preview":"https://ui.ballmac.com/preview/logo-cloud-1-demo"},{"name":"mail-1","kind":"block","type":"registry:block","title":"Mail 1: three-pane inbox","description":"A working inbox: folders with an unread count, a searchable message list with stars and keyboard navigation, a reading pane with archive, delete, mark unread and reply, and a compose dialog. One pane at a time on phones.","category":"blocks","blockCategory":"mail","tier":"free","tags":["mail","inbox","email","three pane","messages","compose","reply"],"version":"1.1.0","updated":"2026-10-11","url":"https://ui.ballmac.com/blocks/mail-1","registryUrl":"https://ui.ballmac.com/r/mail-1.json","install":"npx shadcn@latest add @ballmac/mail-1","summary":"An email client UI. Pass messages=[{ id, folder, from, subject, body[], time, unread?, starred?, attachments? }], me and onSend(to, subject, body); archive, delete, star, read state, search and reply are handled in state.","whenToUse":["Webmail, support inboxes and notification centres","A realistic product screenshot"],"whenNotToUse":["Chat (use ai-chat-2 or the chat components)"],"composesWith":["app-shell-1","kanban-1","calendar-1"],"dependencies":["lucide-react"],"registryDependencies":["shadcn:utils","avatar","button","dialog","input","search-field","select","textarea","state-view","skeleton"],"examples":["mail-1-demo","mail-1-empty","mail-1-loading","mail-1-error","mail-1-no-messages"],"states":[{"id":"loading","title":"Loading","example":"mail-1-loading","trigger":"state=\"loading\"","note":"A skeleton of the three panes, announced as \"Loading messages\"; nothing is clickable.","preview":"https://ui.ballmac.com/preview/mail-1-loading"},{"id":"empty","title":"No messages","example":"mail-1-no-messages","trigger":"state=\"empty\"","note":"The real interface over an empty mailbox, so Compose still works. emptyState sets the copy.","preview":"https://ui.ballmac.com/preview/mail-1-no-messages"},{"id":"error","title":"Could not load","example":"mail-1-error","trigger":"state=\"error\"","note":"An error in the same frame with a Try again button (onRetry), announced as an alert.","preview":"https://ui.ballmac.com/preview/mail-1-error"}],"preview":"https://ui.ballmac.com/preview/mail-1-demo"},{"name":"matrix-1","kind":"block","type":"registry:block","title":"Matrix 1: service health by region","description":"Service health by region: 30-day availability for every service in every region as a heat grid, each cell good, warning or problem in words and an icon, what is below the line listed, the last incident per cell and a team filter.","category":"blocks","blockCategory":"matrix","tier":"free","tags":["service health","availability","regions","heatmap","uptime","sre","status","reliability"],"version":"1.0.0","updated":"2026-10-24","url":"https://ui.ballmac.com/blocks/matrix-1","registryUrl":"https://ui.ballmac.com/r/matrix-1.json","install":"npx shadcn@latest add @ballmac/matrix-1","summary":"Service health by region. void} />. Built on heat-grid with tone. Cells at or above goodFrom are good, below warnBelow are problems; null means the service does not run there.","whenToUse":["A reliability overview across services and regions","A status board for an engineering team"],"whenNotToUse":["A public status page; use status-1","Error budgets over time; use slo-1"],"composesWith":["slo-1","incident-1","runbook-1","status-1"],"dependencies":["lucide-react"],"registryDependencies":["shadcn:utils","button","heat-grid","skeleton","state-view"],"examples":["matrix-1-demo","matrix-1-ai","matrix-1-loading","matrix-1-empty","matrix-1-error"],"states":[{"id":"loading","title":"Loading","example":"matrix-1-loading","trigger":"state=\"loading\"","note":"Skeleton for the grid and the detail under the real heading, announced as loading.","preview":"https://ui.ballmac.com/preview/matrix-1-loading"},{"id":"empty","title":"No services yet","example":"matrix-1-empty","trigger":"state=\"empty\"","note":"Says no services yet; emptyState sets the copy.","preview":"https://ui.ballmac.com/preview/matrix-1-empty"},{"id":"error","title":"Could not load","example":"matrix-1-error","trigger":"state=\"error\"","note":"An alert saying nothing was changed, with Try again (onRetry).","preview":"https://ui.ballmac.com/preview/matrix-1-error"}],"preview":"https://ui.ballmac.com/preview/matrix-1-demo"},{"name":"matter-1","kind":"block","type":"registry:block","title":"Matter 1: legal matters","description":"A law firm's matters: deadlines that cannot be missed first with overdue and due-soon in words, then each matter with client, lead and status, hours against the month's budget, search, a practice area filter and a show-closed switch.","category":"blocks","blockCategory":"matter","tier":"free","tags":["legal","law firm","matters","deadlines","billable hours","practice management","cases","professional services"],"version":"1.0.0","updated":"2026-10-24","url":"https://ui.ballmac.com/blocks/matter-1","registryUrl":"https://ui.ballmac.com/r/matter-1.json","install":"npx shadcn@latest add @ballmac/matter-1","summary":"A matters list. . The panel on top lists open deadlines soonest first and says 'overdue' or 'in 3 days'; a matter over budget says 'Over budget by 3 h'. Closed matters are hidden until the switch is on.","whenToUse":["A practice-management home for a law firm or any deadline-driven professional service","A list where hours are tracked against a budget"],"whenNotToUse":["A general task list; use tasks-1","Time entry; use timesheet-1"],"composesWith":["timesheet-1","invoice-1","calendar-1","app-shell-1"],"dependencies":["lucide-react"],"registryDependencies":["shadcn:utils","match-highlight","skeleton","state-view"],"examples":["matter-1-demo","matter-1-quiet","matter-1-loading","matter-1-empty","matter-1-error"],"states":[{"id":"loading","title":"Loading","example":"matter-1-loading","trigger":"state=\"loading\"","note":"Skeleton for the dates panel and rows under the real heading, announced as loading.","preview":"https://ui.ballmac.com/preview/matter-1-loading"},{"id":"empty","title":"No matters yet","example":"matter-1-empty","trigger":"state=\"empty\"","note":"Says no matters yet; emptyState sets the copy.","preview":"https://ui.ballmac.com/preview/matter-1-empty"},{"id":"error","title":"Could not load","example":"matter-1-error","trigger":"state=\"error\"","note":"An alert saying nothing was changed, with Try again (onRetry). A search or filter with no match says so.","preview":"https://ui.ballmac.com/preview/matter-1-error"}],"preview":"https://ui.ballmac.com/preview/matter-1-demo"},{"name":"newsletter-1","kind":"block","type":"registry:block","title":"Newsletter 1: signup with topics and sample issue","description":"An editorial newsletter signup: topic chips, an email field with validation, loading, error and success states, avatar social proof, and a tilted sample issue card beside it.","category":"blocks","blockCategory":"newsletter","tier":"free","tags":["newsletter","signup","email","subscribe","topics","form"],"version":"1.1.0","updated":"2026-10-11","url":"https://ui.ballmac.com/blocks/newsletter-1","registryUrl":"https://ui.ballmac.com/r/newsletter-1.json","install":"npx shadcn@latest add @ballmac/newsletter-1","summary":"A newsletter signup section. Pass topics (or [] for none), proof, issue headlines for the preview card, and onSubmit(email, topics); throw to show an error.","whenToUse":["Blogs, changelogs and docs sites","Anywhere readers choose what to receive"],"whenNotToUse":["A waitlist over a dramatic background (use cta-2)"],"composesWith":["blog-1","changelog-1","footer-2","faq-2"],"dependencies":["lucide-react"],"registryDependencies":["shadcn:utils","button","input","media","use-resource"],"examples":["newsletter-1-demo","newsletter-1-simple","newsletter-1-subscribing","newsletter-1-subscribed","newsletter-1-error"],"states":[{"id":"submitting","title":"Subscribing","example":"newsletter-1-subscribing","trigger":"state=\"submitting\"","note":"Every field and button is disabled while the request is in flight, the button shows a spinner, and the form is marked busy.","preview":"https://ui.ballmac.com/preview/newsletter-1-subscribing"},{"id":"success","title":"Subscribed","example":"newsletter-1-subscribed","trigger":"state=\"success\"","note":"The confirmation screen the flow ends on.","preview":"https://ui.ballmac.com/preview/newsletter-1-subscribed"},{"id":"error","title":"Could not subscribe","example":"newsletter-1-error","trigger":"state=\"error\"","note":"An alert above the form with the message (errorState.description to change it); the fields stay editable so it can be fixed.","preview":"https://ui.ballmac.com/preview/newsletter-1-error"}],"preview":"https://ui.ballmac.com/preview/newsletter-1-demo"},{"name":"onboarding-1","kind":"block","type":"registry:block","title":"Onboarding 1: workspace setup wizard","description":"A four-step setup wizard with a progress rail: name and address a workspace (auto-filled), pick goals as cards, invite teammates as removable chips, review, then a finish screen. Slides between steps.","category":"blocks","blockCategory":"onboarding","tier":"free","tags":["onboarding","wizard","setup","workspace","steps","invite"],"version":"1.1.0","updated":"2026-10-11","url":"https://ui.ballmac.com/blocks/onboarding-1","registryUrl":"https://ui.ballmac.com/r/onboarding-1.json","install":"npx shadcn@latest add @ballmac/onboarding-1","summary":"First-run setup after signup. Pass product, domain, goals=[{ id, title, description }] and onComplete(values) with { name, slug, color, goals, invites } (throw to show an error).","whenToUse":["The first screen after signup or verification","Products where a workspace or team has to be created"],"whenNotToUse":["A checklist that lives inside the app (use onboarding-checklist)"],"composesWith":["signup-1","verify-1","invite-1","app-shell"],"dependencies":["lucide-react","motion@^12"],"registryDependencies":["shadcn:utils","button","field","input","use-resource"],"examples":["onboarding-1-demo","onboarding-1-custom","onboarding-1-creating","onboarding-1-ready","onboarding-1-error"],"states":[{"id":"submitting","title":"Creating the workspace","example":"onboarding-1-creating","trigger":"state=\"submitting\"","note":"The review step with its button spinning and the steps locked.","preview":"https://ui.ballmac.com/preview/onboarding-1-creating"},{"id":"success","title":"Workspace ready","example":"onboarding-1-ready","trigger":"state=\"success\"","note":"The confirmation screen the flow ends on.","preview":"https://ui.ballmac.com/preview/onboarding-1-ready"},{"id":"error","title":"Could not create","example":"onboarding-1-error","trigger":"state=\"error\"","note":"An alert above the form with the message (errorState.description to change it); the fields stay editable so it can be fixed.","preview":"https://ui.ballmac.com/preview/onboarding-1-error"}],"preview":"https://ui.ballmac.com/preview/onboarding-1-demo"},{"name":"oncall-1","kind":"block","type":"registry:block","title":"On-call 1: weekly rota","description":"An on-call rota for the week: who is on call now per layer, a grid of days by primary and secondary, days nobody covers called out in words, and a selected shift you can take or ask the person on it to swap.","category":"blocks","blockCategory":"oncall","tier":"free","tags":["on-call","rota","schedule","incident","pager","sre","devops","shifts"],"version":"1.0.0","updated":"2026-10-24","url":"https://ui.ballmac.com/blocks/oncall-1","registryUrl":"https://ui.ballmac.com/r/oncall-1.json","install":"npx shadcn@latest add @ballmac/oncall-1","summary":"A weekly on-call rota. Promise} onRequestSwap={(shift) => Promise} />. null in people means nobody; uncovered shifts are listed in words. Select a shift to take it or ask for a swap.","whenToUse":["An operations page showing who gets paged this week","A team calendar for support or engineering cover"],"whenNotToUse":["A shift roster for hourly staff; use roster-1","A calendar of events; use calendar-1"],"composesWith":["incident-1","status-1","access-1","app-shell-1"],"dependencies":["lucide-react"],"registryDependencies":["shadcn:utils","button","skeleton","state-view"],"examples":["oncall-1-demo","oncall-1-covered","oncall-1-loading","oncall-1-empty","oncall-1-error"],"states":[{"id":"loading","title":"Loading","example":"oncall-1-loading","trigger":"state=\"loading\"","note":"Skeleton for the banner and the grid under the real heading, announced as loading.","preview":"https://ui.ballmac.com/preview/oncall-1-loading"},{"id":"empty","title":"No rota yet","example":"oncall-1-empty","trigger":"state=\"empty\"","note":"Says no rota exists yet; emptyState sets the copy and can add a button.","preview":"https://ui.ballmac.com/preview/oncall-1-empty"},{"id":"error","title":"Could not load","example":"oncall-1-error","trigger":"state=\"error\"","note":"An alert saying nobody was changed, with Try again (onRetry).","preview":"https://ui.ballmac.com/preview/oncall-1-error"}],"preview":"https://ui.ballmac.com/preview/oncall-1-demo"},{"name":"orgchart-1","kind":"block","type":"registry:block","title":"Org chart 1: organization tree","description":"An organization chart drawn as a real tree: connected person cards, a count toggle on every team, search that opens the path to a person, a details panel with manager and direct reports, and the standard tree keys.","category":"blocks","blockCategory":"orgchart","tier":"free","tags":["org chart","organization","hierarchy","team","people","tree","reports","company","about"],"version":"1.0.0","updated":"2026-10-18","url":"https://ui.ballmac.com/blocks/orgchart-1","registryUrl":"https://ui.ballmac.com/r/orgchart-1.json","install":"npx shadcn@latest add @ballmac/orgchart-1","summary":"An org chart. . Pass one root person; everyone below hangs off reports. Search opens the path to the person; the side panel shows the manager and direct reports and lets you jump to them.","whenToUse":["An about or team page showing who reports to whom","An internal directory with reporting lines"],"whenNotToUse":["A grid of team photos with no hierarchy (use team-1)","A flat people directory with filters (use a table)"],"composesWith":["about-1","team-1","app-shell-1"],"dependencies":["lucide-react","motion"],"registryDependencies":["shadcn:utils","button","cover-art","direction","match-highlight","skeleton","state-view"],"examples":["orgchart-1-demo","orgchart-1-open","orgchart-1-loading","orgchart-1-empty","orgchart-1-error"],"states":[{"id":"loading","title":"Loading","example":"orgchart-1-loading","trigger":"state=\"loading\"","note":"Skeleton cards under the real heading, announced as loading.","preview":"https://ui.ballmac.com/preview/orgchart-1-loading"},{"id":"empty","title":"No chart yet","example":"orgchart-1-empty","trigger":"state=\"empty\"","note":"Explains that the chart draws itself once people and reporting lines are added; emptyState sets the copy and can add a button.","preview":"https://ui.ballmac.com/preview/orgchart-1-empty"},{"id":"error","title":"Could not load","example":"orgchart-1-error","trigger":"state=\"error\"","note":"An alert with Try again (onRetry).","preview":"https://ui.ballmac.com/preview/orgchart-1-error"}],"preview":"https://ui.ballmac.com/preview/orgchart-1-demo"},{"name":"pipeline-1","kind":"block","type":"registry:block","title":"Pipeline 1: deploy pipeline","description":"One run of a deploy pipeline: the commit, each stage as a step with its status written out and duration, logs one click away, an approval gate that says who can approve, and a failed stage that offers to run again from there.","category":"blocks","blockCategory":"pipeline","tier":"free","tags":["ci","cd","deploy","pipeline","release","build","approval","devops"],"version":"1.0.0","updated":"2026-10-24","url":"https://ui.ballmac.com/blocks/pipeline-1","registryUrl":"https://ui.ballmac.com/r/pipeline-1.json","install":"npx shadcn@latest add @ballmac/pipeline-1","summary":"A deploy pipeline run. Promise} onRerun={(stageId) => Promise} />. A waiting stage shows its approver and an Approve button; a failed stage offers Run again from here. Only stages with a log are buttons.","whenToUse":["A release page showing where a deploy is and what is blocking it","An approval step before production"],"whenNotToUse":["A list of many runs; use a table","Server logs in real time; use log-stream"],"composesWith":["incident-1","audit-1","status-1","dev-1"],"dependencies":["lucide-react"],"registryDependencies":["shadcn:utils","button","skeleton","state-view"],"examples":["pipeline-1-demo","pipeline-1-failed","pipeline-1-loading","pipeline-1-empty","pipeline-1-error"],"states":[{"id":"loading","title":"Loading","example":"pipeline-1-loading","trigger":"state=\"loading\"","note":"Skeleton for the commit and the stages under the real heading, announced as loading.","preview":"https://ui.ballmac.com/preview/pipeline-1-loading"},{"id":"empty","title":"No runs yet","example":"pipeline-1-empty","trigger":"state=\"empty\"","note":"Says no runs yet; emptyState sets the copy.","preview":"https://ui.ballmac.com/preview/pipeline-1-empty"},{"id":"error","title":"Could not load","example":"pipeline-1-error","trigger":"state=\"error\"","note":"An alert saying nothing was deployed or changed, with Try again (onRetry). A failed approval keeps the gate waiting and says why.","preview":"https://ui.ballmac.com/preview/pipeline-1-error"}],"preview":"https://ui.ballmac.com/preview/pipeline-1-demo"},{"name":"poll-1","kind":"block","type":"registry:block","title":"Poll 1: vote and live results","description":"A poll: pick one option or several, vote, and results appear with each share, the leader marked and your choice highlighted. Your vote counts at once and is taken back with the reason if it fails; change it until the poll closes.","category":"blocks","blockCategory":"poll","tier":"free","tags":["poll","vote","voting","results","survey","feedback","community","roadmap","choose","ballot"],"version":"1.0.0","updated":"2026-10-18","url":"https://ui.ballmac.com/blocks/poll-1","registryUrl":"https://ui.ballmac.com/r/poll-1.json","install":"npx shadcn@latest add @ballmac/poll-1","summary":"A poll. Promise} />. Before voting people choose (radio buttons, or checkboxes with multiple); after voting, or when closed, they see each share, the single leader and their own choice. Votes are counted at once; reject onVote and they are taken back with the message. Changing a vote removes the old choice and adds the new. Time left comes from closesAt and now; pass now yourself, the block never reads the clock.","whenToUse":["Letting users vote on what to build next","Community and event polls with live results"],"whenNotToUse":["A multi-question survey (use survey-1)","Scored questions with right answers (use quiz-1)"],"composesWith":["survey-1","comments-1","changelog-1","app-shell-1"],"dependencies":["lucide-react"],"registryDependencies":["shadcn:utils","button","skeleton","state-view"],"examples":["poll-1-demo","poll-1-voted","poll-1-multiple","poll-1-closed","poll-1-loading","poll-1-empty","poll-1-error"],"states":[{"id":"loading","title":"Loading","example":"poll-1-loading","trigger":"state=\"loading\"","note":"A skeleton question and options, announced as loading.","preview":"https://ui.ballmac.com/preview/poll-1-loading"},{"id":"empty","title":"No poll","example":"poll-1-empty","trigger":"state=\"empty\" (or options={[]})","note":"Says a question appears here when there is one to vote on; emptyState sets the copy.","preview":"https://ui.ballmac.com/preview/poll-1-empty"},{"id":"error","title":"Could not load","example":"poll-1-error","trigger":"state=\"error\"","note":"An alert saying your vote has not been lost, with Try again (onRetry). A vote that fails to save is taken back with its reason in place.","preview":"https://ui.ballmac.com/preview/poll-1-error"}],"preview":"https://ui.ballmac.com/preview/poll-1-demo"},{"name":"portfolio-1","kind":"block","type":"registry:block","title":"Portfolio 1: investments overview","description":"An investment portfolio: total value and its change over a week, month or year, a line you scrub by pointer or arrow keys, an allocation ring, and sortable holdings with price, share, day change and a small trend line.","category":"blocks","blockCategory":"portfolio","tier":"free","tags":["portfolio","investments","holdings","stocks","finance","allocation","wealth","returns","dashboard","assets"],"version":"1.0.0","updated":"2026-10-18","url":"https://ui.ballmac.com/blocks/portfolio-1","registryUrl":"https://ui.ballmac.com/r/portfolio-1.json","install":"npx shadcn@latest add @ballmac/portfolio-1","summary":"An investment portfolio. . Total value, allocation by kind, each holding's share and today's gain are worked out from holdings; the change over the range comes from the first and last point of the series. The line is a slider (Left, Right, Home, End) that reads out any point. Gains and losses carry a sign and an arrow as well as color.","whenToUse":["An investing or wealth app's overview","A finance dashboard showing what is held and how it is doing"],"whenNotToUse":["A trading screen with order entry","A single stock price chart with candles"],"composesWith":["dashboard-1","invoice-1","funnel-1","app-shell-1"],"dependencies":["lucide-react"],"registryDependencies":["shadcn:utils","segmented-control","skeleton","state-view"],"examples":["portfolio-1-demo","portfolio-1-down","portfolio-1-loading","portfolio-1-empty","portfolio-1-error"],"states":[{"id":"loading","title":"Loading","example":"portfolio-1-loading","trigger":"state=\"loading\"","note":"A skeleton chart and table under the real heading, announced as loading.","preview":"https://ui.ballmac.com/preview/portfolio-1-loading"},{"id":"empty","title":"No holdings","example":"portfolio-1-empty","trigger":"state=\"empty\" (or holdings={[]})","note":"Says holdings appear once an account is added or connected; emptyState sets the copy and can add a button.","preview":"https://ui.ballmac.com/preview/portfolio-1-empty"},{"id":"error","title":"Could not load","example":"portfolio-1-error","trigger":"state=\"error\"","note":"An alert saying your holdings are safe, with Try again (onRetry).","preview":"https://ui.ballmac.com/preview/portfolio-1-error"}],"preview":"https://ui.ballmac.com/preview/portfolio-1-demo"},{"name":"pricing-1","kind":"block","type":"registry:block","title":"Pricing 1: two tiers","description":"Two pricing cards side by side with included and excluded features, a highlighted plan with a border beam and badge, and small print.","category":"blocks","blockCategory":"pricing","tier":"free","tags":["pricing","plans","saas","tiers"],"version":"1.0.0","updated":"2026-09-28","url":"https://ui.ballmac.com/blocks/pricing-1","registryUrl":"https://ui.ballmac.com/r/pricing-1.json","install":"npx shadcn@latest add @ballmac/pricing-1","summary":"Pricing for a free-plus-paid or two-plan product. Pass plans=[{ name, price, period, description, features, cta, featured }].","whenToUse":["Freemium products","Two-plan pricing pages"],"whenNotToUse":["Three or more plans side by side"],"composesWith":["faq-1","cta-1"],"dependencies":["lucide-react"],"registryDependencies":["shadcn:utils","badge","border-beam","button"],"examples":["pricing-1-demo"],"states":[],"statesNone":"Static content: nothing to load, submit or fail.","preview":"https://ui.ballmac.com/preview/pricing-1-demo"},{"name":"pricing-2","kind":"block","type":"registry:block","title":"Pricing 2: three tiers with billing toggle","description":"Three plan cards with a monthly/yearly switch. Prices roll to the new value, a savings badge and billed-total line update, and the middle plan is lifted with a border beam.","category":"blocks","blockCategory":"pricing","tier":"free","tags":["pricing","plans","toggle","yearly","saas","tiers"],"version":"1.0.0","updated":"2026-10-01","url":"https://ui.ballmac.com/blocks/pricing-2","registryUrl":"https://ui.ballmac.com/r/pricing-2.json","install":"npx shadcn@latest add @ballmac/pricing-2","summary":"Standard SaaS pricing with a billing toggle. Pass plans=[{ name, description, price: { monthly, yearly } | string, unit?, lead?, features, cta, featured? }].","whenToUse":["SaaS products with three plans","Products that discount annual billing"],"whenNotToUse":["Two plans only (use pricing-1)","Usage-based pricing (use plan-selector or a calculator)"],"composesWith":["faq-2","logo-cloud-1","cta-1","pricing-3"],"dependencies":["lucide-react"],"registryDependencies":["shadcn:utils","animated-number-flow","badge","border-beam","button","segmented-control"],"examples":["pricing-2-demo","pricing-2-custom"],"states":[],"statesNone":"Static content: nothing to load, submit or fail.","preview":"https://ui.ballmac.com/preview/pricing-2-demo"},{"name":"pricing-3","kind":"block","type":"registry:block","title":"Pricing 3: full plan comparison","description":"A feature-by-feature comparison table with a sticky plan header, collapsible groups and a highlighted column. On phones it becomes a plan switcher with one clean list.","category":"blocks","blockCategory":"pricing","tier":"free","tags":["pricing","comparison","table","sticky","plans","features"],"version":"1.0.0","updated":"2026-10-01","url":"https://ui.ballmac.com/blocks/pricing-3","registryUrl":"https://ui.ballmac.com/r/pricing-3.json","install":"npx shadcn@latest add @ballmac/pricing-3","summary":"The detailed pricing table for buyers who compare. Pass plans=[{ key, name, price, period?, cta, featured? }] and groups=[{ title, rows: [{ label, hint?, values: { [planKey]: boolean | string } }] }].","whenToUse":["Below pricing cards, for buyers who want every detail","Products with many differentiating features"],"whenNotToUse":["Two simple plans (pricing-1 is enough)"],"composesWith":["pricing-2","faq-2","cta-1","header-1"],"dependencies":["lucide-react"],"registryDependencies":["shadcn:utils","badge","button","segmented-control"],"examples":["pricing-3-demo","pricing-3-two"],"states":[],"statesNone":"Static content: nothing to load, submit or fail.","preview":"https://ui.ballmac.com/preview/pricing-3-demo"},{"name":"pricing-4","kind":"block","type":"registry:block","title":"Pricing 4: one-time license vs subscription","description":"A pricing section for Mac apps that sell both ways: a Buy once / Subscribe switch, license size cards and a cumulative-cost chart that computes the break-even year.","category":"blocks","blockCategory":"pricing","tier":"free","tags":["pricing","license","subscription","one-time","mac","chart","break-even"],"version":"1.0.0","updated":"2026-10-01","url":"https://ui.ballmac.com/blocks/pricing-4","registryUrl":"https://ui.ballmac.com/r/pricing-4.json","install":"npx shadcn@latest add @ballmac/pricing-4","summary":"Pricing for apps with a one-time license and a subscription. Pass tiers=[{ id, name, description?, once, yearly }], optional renewal (price of paid updates after year 1), years, currency and href(tierId, mode). The chart and the 'pays for itself in year N' message are computed from the numbers.","whenToUse":["Mac and desktop apps that offer a perpetual license next to a subscription","When you want to show buyers the long-run cost honestly"],"whenNotToUse":["Monthly SaaS plans with feature tiers (pricing-1 or pricing-3)"],"composesWith":["download-1","faq-2","cta-1","showcase-1"],"dependencies":["lucide-react","recharts@^3"],"registryDependencies":["shadcn:utils","button","chart","label","radio-group","segmented-control","switch"],"examples":["pricing-4-demo","pricing-4-custom"],"states":[],"statesNone":"Static content: nothing to load, submit or fail.","preview":"https://ui.ballmac.com/preview/pricing-4-demo"},{"name":"profile-1","kind":"block","type":"registry:block","title":"Profile 1: public profile","description":"A public profile: cover and avatar art drawn from the handle, a verified badge, Follow that updates the count and undoes itself on failure, stats that count up, About, pointer-lit project cards and an Activity tab.","category":"blocks","blockCategory":"profile","tier":"free","tags":["profile","user","public profile","portfolio","follow","social","creator","community","activity"],"version":"1.0.0","updated":"2026-10-17","url":"https://ui.ballmac.com/blocks/profile-1","registryUrl":"https://ui.ballmac.com/r/profile-1.json","install":"npx shadcn@latest add @ballmac/profile-1","summary":"A public profile page. …} onMessage onShare />. Without images it draws cover and avatar art from the handle and each project's id. Follow is optimistic: throw from onFollow to undo it.","whenToUse":["The public page of a member, creator, designer or developer in a community or marketplace","A portfolio-style profile with projects and activity"],"whenNotToUse":["Editing your own account (use settings-1)","A company About page (use team-1)","An article author box (use blog-post-1)"],"composesWith":["app-shell-1","chat-1","header-2","footer-2"],"dependencies":["lucide-react"],"registryDependencies":["shadcn:utils","animated-tabs","avatar","badge","blur-fade","button","contribution-graph","cover-art","media","number-ticker","skeleton","spotlight-card","state-view"],"examples":["profile-1-demo","profile-1-following","profile-1-loading","profile-1-empty","profile-1-error"],"states":[{"id":"loading","title":"Loading","example":"profile-1-loading","trigger":"state=\"loading\"","note":"A skeleton of the cover, avatar and project cards, announced as loading.","preview":"https://ui.ballmac.com/preview/profile-1-loading"},{"id":"empty","title":"No projects yet","example":"profile-1-empty","trigger":"state=\"empty\" (or projects={[]})","note":"The profile shows as usual and the Work tab says nothing is shared yet; emptyState sets the copy.","preview":"https://ui.ballmac.com/preview/profile-1-empty"},{"id":"error","title":"Could not load","example":"profile-1-error","trigger":"state=\"error\"","note":"An alert with Try again (onRetry).","preview":"https://ui.ballmac.com/preview/profile-1-error"}],"preview":"https://ui.ballmac.com/preview/profile-1-demo"},{"name":"queues-1","kind":"block","type":"registry:block","title":"Queues 1: job queues","description":"The queues behind a product: jobs waiting, arrival and finish rates, the age of the oldest job, a queue that is filling faster than it drains called out in words, failed jobs with their errors to retry or discard, and a pause switch.","category":"blocks","blockCategory":"queues","tier":"free","tags":["queues","jobs","background jobs","retries","dead letter","workers","devops","monitoring"],"version":"1.0.0","updated":"2026-10-24","url":"https://ui.ballmac.com/blocks/queues-1","registryUrl":"https://ui.ballmac.com/r/queues-1.json","install":"npx shadcn@latest add @ballmac/queues-1","summary":"Background job queues. Promise} onRetryJobs={(queueId, jobId | 'all') => Promise} onDiscard={(queueId, jobId) => Promise} />. A queue is 'Backing up' when jobs arrive over 1.2 times faster than they finish and over 100 wait. Each action updates the screen and reports success or the error.","whenToUse":["An operations view of workers and background jobs","Finding and retrying jobs that failed"],"whenNotToUse":["Scheduled jobs and their next runs; use cron-1","A deploy's stages; use pipeline-1"],"composesWith":["cron-1","slo-1","incident-1","webhooks-1"],"dependencies":["lucide-react"],"registryDependencies":["shadcn:utils","button","skeleton","state-view","switch"],"examples":["queues-1-demo","queues-1-loading","queues-1-empty","queues-1-error"],"states":[{"id":"loading","title":"Loading","example":"queues-1-loading","trigger":"state=\"loading\"","note":"Skeleton rows under the real heading, announced as loading.","preview":"https://ui.ballmac.com/preview/queues-1-loading"},{"id":"empty","title":"No queues yet","example":"queues-1-empty","trigger":"state=\"empty\"","note":"Says no queues yet; emptyState sets the copy.","preview":"https://ui.ballmac.com/preview/queues-1-empty"},{"id":"error","title":"Could not load","example":"queues-1-error","trigger":"state=\"error\"","note":"An alert saying no jobs were changed, with Try again (onRetry). A failed pause or retry puts things back and says why.","preview":"https://ui.ballmac.com/preview/queues-1-error"}],"preview":"https://ui.ballmac.com/preview/queues-1-demo"},{"name":"quiz-1","kind":"block","type":"registry:block","title":"Quiz 1: questions with feedback","description":"A short quiz: one question at a time with progress, single or multiple answers, instant right or wrong with the reason, locked once checked, then a score against the pass mark with a review of every question and a retake.","category":"blocks","blockCategory":"quiz","tier":"free","tags":["quiz","questions","test","exam","assessment","learning","score","pass mark","trivia","knowledge check"],"version":"1.0.0","updated":"2026-10-18","url":"https://ui.ballmac.com/blocks/quiz-1","registryUrl":"https://ui.ballmac.com/r/quiz-1.json","install":"npx shadcn@latest add @ballmac/quiz-1","summary":"A quiz. ...} />. An answer array means choose all that apply (checkboxes); one id means radio buttons. Answers lock once checked. The result shows the score ring, pass or fail, and every question with what you chose when you were wrong.","whenToUse":["A knowledge check at the end of a lesson","A quick assessment or onboarding quiz"],"whenNotToUse":["Collecting opinions (use survey-1)","Timed exams with proctoring"],"composesWith":["course-1","onboarding-1","app-shell-1"],"dependencies":["lucide-react"],"registryDependencies":["shadcn:utils","button"],"examples":["quiz-1-demo","quiz-1-score","quiz-1-empty"],"states":[],"statesNone":"Self-contained: it holds its own answers and has nothing to load, submit or fail.","preview":"https://ui.ballmac.com/preview/quiz-1-demo"},{"name":"recipe-1","kind":"block","type":"registry:block","title":"Recipe 1: scale, check off and time","description":"A recipe you can cook from: change how many it serves and every amount scales the way a cook reads it, switch metric and US units, tick off ingredients and steps, and start a timer on the steps that need waiting.","category":"blocks","blockCategory":"recipe","tier":"free","tags":["recipe","cooking","ingredients","servings","timer","food","kitchen","method","meal","baking"],"version":"1.0.0","updated":"2026-10-18","url":"https://ui.ballmac.com/blocks/recipe-1","registryUrl":"https://ui.ballmac.com/r/recipe-1.json","install":"npx shadcn@latest add @ballmac/recipe-1","summary":"A recipe. . qty is for the recipe's own serves; changing the servings scales every amount. Spoons and cups read as ½ ¼ ⅓ fractions, g and ml as whole numbers (rounded to 5 above 100); US units turn g into oz and ml into fl oz. A step with minutes gets a start, pause and reset timer that says 'Time is up'.","whenToUse":["Food blogs, meal-kit sites and cooking apps","Any how-to with amounts that scale and steps that need waiting"],"whenNotToUse":["A shopping list across recipes","A meal planner calendar"],"composesWith":["gallery-1","reviews-1","comments-1","header-1"],"dependencies":["lucide-react"],"registryDependencies":["shadcn:utils","button","cover-art","segmented-control"],"examples":["recipe-1-demo","recipe-1-baking"],"states":[],"statesNone":"Static content with its own tools: nothing to load, submit or fail.","preview":"https://ui.ballmac.com/preview/recipe-1-demo"},{"name":"rentals-1","kind":"block","type":"registry:block","title":"Rentals 1: rental booking","description":"A rental booking page: choose an item, the days and extras, see price, refundable deposit and pay-today, a clash with days already out named by date, and a reservation that says exactly what was booked.","category":"blocks","blockCategory":"rentals","tier":"free","tags":["rental","booking","reservation","dates","equipment","deposit","hire","marketplace"],"version":"1.0.0","updated":"2026-10-24","url":"https://ui.ballmac.com/blocks/rentals-1","registryUrl":"https://ui.ballmac.com/r/rentals-1.json","install":"npx shadcn@latest add @ballmac/rentals-1","summary":"Rental booking. Promise} />. Both ends of the range count as days. A range that includes a booked day is refused and names it.","whenToUse":["Equipment, vehicle or space hire","Any date-range booking with a deposit"],"whenNotToUse":["A single appointment slot; use salon-1","A hotel with rooms and guests; use booking-1"],"composesWith":["salon-1","booking-1","calendar-1"],"dependencies":["lucide-react"],"registryDependencies":["shadcn:utils","button","skeleton","state-view"],"examples":["rentals-1-demo","rentals-1-long","rentals-1-loading","rentals-1-empty","rentals-1-error"],"states":[{"id":"loading","title":"Loading","example":"rentals-1-loading","trigger":"state=\"loading\"","note":"Skeleton list and summary under the real heading, announced as loading.","preview":"https://ui.ballmac.com/preview/rentals-1-loading"},{"id":"empty","title":"Nothing to rent","example":"rentals-1-empty","trigger":"state=\"empty\"","note":"Says there is nothing to rent; emptyState sets the copy.","preview":"https://ui.ballmac.com/preview/rentals-1-empty"},{"id":"error","title":"Could not load","example":"rentals-1-error","trigger":"state=\"error\"","note":"An alert saying nothing was reserved, with Try again (onRetry). A reservation that fails keeps the choices and says why.","preview":"https://ui.ballmac.com/preview/rentals-1-error"}],"preview":"https://ui.ballmac.com/preview/rentals-1-demo"},{"name":"retention-1","kind":"block","type":"registry:block","title":"Retention 1: cohort heatmap","description":"A cohort retention table as a heatmap: rows of people who started together, columns of later periods, each cell tinted by the share still active, with headline numbers, percent or people, a keyboard grid and a size-weighted average row.","category":"blocks","blockCategory":"retention","tier":"free","tags":["retention","cohorts","heatmap","churn","analytics","engagement","growth","dashboard","cohort analysis"],"version":"1.0.0","updated":"2026-10-18","url":"https://ui.ballmac.com/blocks/retention-1","registryUrl":"https://ui.ballmac.com/r/retention-1.json","install":"npx shadcn@latest add @ballmac/retention-1","summary":"A cohort retention heatmap. . retention is the percent still active in each period starting at period 0; newer cohorts have fewer entries. The average row weights each period by cohort size and only counts cohorts old enough to reach it. Headline numbers (period 1, period 4, trend) are worked out from the table.","whenToUse":["Product analytics: do people come back?","Comparing the quality of signups week by week"],"whenNotToUse":["A step-by-step conversion path (use funnel-1)","A trend line of one metric (use a chart)"],"composesWith":["funnel-1","experiments-1","app-shell-1"],"dependencies":["lucide-react"],"registryDependencies":["shadcn:utils","segmented-control","skeleton","state-view"],"examples":["retention-1-demo","retention-1-monthly","retention-1-loading","retention-1-empty","retention-1-error"],"states":[{"id":"loading","title":"Loading","example":"retention-1-loading","trigger":"state=\"loading\"","note":"Skeleton stat cards and table under the real heading, announced as loading.","preview":"https://ui.ballmac.com/preview/retention-1-loading"},{"id":"empty","title":"No cohorts yet","example":"retention-1-empty","trigger":"state=\"empty\" (or cohorts={[]})","note":"Says retention appears once people have started and a full period has passed; emptyState sets the copy.","preview":"https://ui.ballmac.com/preview/retention-1-empty"},{"id":"error","title":"Could not load","example":"retention-1-error","trigger":"state=\"error\"","note":"An alert with Try again (onRetry).","preview":"https://ui.ballmac.com/preview/retention-1-error"}],"preview":"https://ui.ballmac.com/preview/retention-1-demo"},{"name":"reviews-1","kind":"block","type":"registry:block","title":"Reviews 1: customer reviews","description":"Customer reviews: an average with a bar for each star count that also filters, sorting, a verified-only switch, review cards with Read more, helpful votes that count at once and business replies. All figures are worked out from the reviews.","category":"blocks","blockCategory":"reviews","tier":"free","tags":["reviews","ratings","stars","customer feedback","testimonials","social proof","verified","product reviews"],"version":"1.0.0","updated":"2026-10-18","url":"https://ui.ballmac.com/blocks/reviews-1","registryUrl":"https://ui.ballmac.com/r/reviews-1.json","install":"npx shadcn@latest add @ballmac/reviews-1","summary":"Customer reviews. ...} />. The average, the bar for each star count and the percentage of 4 and 5 stars are worked out from the reviews. Clicking a bar filters by that star count.","whenToUse":["A product or service page with customer reviews","A reviews section under pricing or a store listing"],"whenNotToUse":["A few hand-picked quotes (use testimonials-1 or testimonials-2)","A customer story with results (use casestudy-1)"],"composesWith":["testimonials-1","pricing-1","faq-1","cta-1"],"dependencies":["lucide-react"],"registryDependencies":["shadcn:utils","button","cover-art","select","skeleton","state-view"],"examples":["reviews-1-demo","reviews-1-loading","reviews-1-empty","reviews-1-error"],"states":[{"id":"loading","title":"Loading","example":"reviews-1-loading","trigger":"state=\"loading\"","note":"A skeleton summary and review cards under the real heading, announced as loading.","preview":"https://ui.ballmac.com/preview/reviews-1-loading"},{"id":"empty","title":"No reviews yet","example":"reviews-1-empty","trigger":"state=\"empty\" (or reviews={[]})","note":"Invites the first review, with a Write a review button when onWrite is given. Filters with no match say so in place.","preview":"https://ui.ballmac.com/preview/reviews-1-empty"},{"id":"error","title":"Could not load","example":"reviews-1-error","trigger":"state=\"error\"","note":"An alert with Try again (onRetry).","preview":"https://ui.ballmac.com/preview/reviews-1-error"}],"preview":"https://ui.ballmac.com/preview/reviews-1-demo"},{"name":"roster-1","kind":"block","type":"registry:block","title":"Roster 1: weekly shift planner","description":"A weekly shift roster: a row per person and a column per day, shifts you set, change or mark as time off, hours per person with overtime and rest flags, a coverage row against what each day needs, weeks to page through and a publish step.","category":"blocks","blockCategory":"roster","tier":"free","tags":["roster","shifts","schedule","rota","staff scheduling","rostering","workforce","hospitality","retail","coverage"],"version":"1.0.0","updated":"2026-10-18","url":"https://ui.ballmac.com/blocks/roster-1","registryUrl":"https://ui.ballmac.com/r/roster-1.json","install":"npx shadcn@latest add @ballmac/roster-1","summary":"A shift roster. ...} onPublish={(weekStart) => Promise} />. Hours, overtime against each maxHours, rest between one day's end and the next day's start (under minRest is flagged) and coverage against required are worked out from the shifts. Press a cell to add, edit or remove a shift or mark time off. Reject onPublish to keep the week a draft with the reason.","whenToUse":["Scheduling staff in hospitality, retail, care and support teams","Planning who covers what each day"],"whenNotToUse":["A project timeline (use gantt-1)","Booking one meeting (use a calendar)"],"composesWith":["timesheet-1","directory-1","calendar-1","app-shell-1"],"dependencies":["lucide-react"],"registryDependencies":["shadcn:utils","button","cover-art","dialog","input","select","skeleton","state-view","return-focus"],"examples":["roster-1-demo","roster-1-published","roster-1-loading","roster-1-empty","roster-1-error"],"states":[{"id":"loading","title":"Loading","example":"roster-1-loading","trigger":"state=\"loading\"","note":"A skeleton grid under the real heading, announced as loading.","preview":"https://ui.ballmac.com/preview/roster-1-loading"},{"id":"empty","title":"No staff","example":"roster-1-empty","trigger":"state=\"empty\" (or staff={[]})","note":"Says to add the people who work here; emptyState sets the copy and can add a button.","preview":"https://ui.ballmac.com/preview/roster-1-empty"},{"id":"error","title":"Could not load","example":"roster-1-error","trigger":"state=\"error\"","note":"An alert saying nothing was changed, with Try again (onRetry). A publish that fails says the week is still a draft, in place under the grid.","preview":"https://ui.ballmac.com/preview/roster-1-error"}],"preview":"https://ui.ballmac.com/preview/roster-1-demo"},{"name":"runbook-1","kind":"block","type":"registry:block","title":"Runbook 1: guided runbook","description":"A runbook to follow under pressure: ordered steps with a tick each, the next step marked, commands to copy but never run for you, cautions read before the step, minutes left, and Finish only when every step is done.","category":"blocks","blockCategory":"runbook","tier":"free","tags":["runbook","playbook","incident","sre","operations","checklist","procedure","on-call"],"version":"1.0.0","updated":"2026-10-24","url":"https://ui.ballmac.com/blocks/runbook-1","registryUrl":"https://ui.ballmac.com/r/runbook-1.json","install":"npx shadcn@latest add @ballmac/runbook-1","summary":"A guided runbook. Promise} onComplete={() => Promise} />. The first step not done is marked Next (aria-current='step'). Commands are shown as code with a Copy button and are never executed. Finish is off until every step is ticked.","whenToUse":["The page an on-call engineer follows for a known problem","Any procedure where order matters and each step must be confirmed"],"whenNotToUse":["An onboarding checklist for users; use onboarding-1","A deploy's stages; use pipeline-1"],"composesWith":["incident-1","alerts-1","oncall-1","matrix-1"],"dependencies":["lucide-react"],"registryDependencies":["shadcn:utils","button","skeleton","state-view"],"examples":["runbook-1-demo","runbook-1-done","runbook-1-loading","runbook-1-empty","runbook-1-error"],"states":[{"id":"loading","title":"Loading","example":"runbook-1-loading","trigger":"state=\"loading\"","note":"Skeleton for the progress and the steps under the page, announced as loading.","preview":"https://ui.ballmac.com/preview/runbook-1-loading"},{"id":"empty","title":"No runbook for this","example":"runbook-1-empty","trigger":"state=\"empty\"","note":"Says there is no runbook for this; pass runbook={null} and emptyState sets the copy.","preview":"https://ui.ballmac.com/preview/runbook-1-empty"},{"id":"error","title":"Could not load","example":"runbook-1-error","trigger":"state=\"error\"","note":"An alert saying nothing was changed, with Try again (onRetry). A tick that cannot be saved goes back and says why.","preview":"https://ui.ballmac.com/preview/runbook-1-error"}],"preview":"https://ui.ballmac.com/preview/runbook-1-demo"},{"name":"salon-1","kind":"block","type":"registry:block","title":"Salon 1: appointment booking","description":"A booking page for a salon or clinic: choose services (time and price add up), a stylist or anyone, then a day and a time that stylist is free, a live summary, and a confirmation that says exactly what was booked.","category":"blocks","blockCategory":"salon","tier":"free","tags":["booking","appointments","salon","scheduling","services","clinic","beauty","customer"],"version":"1.0.0","updated":"2026-10-24","url":"https://ui.ballmac.com/blocks/salon-1","registryUrl":"https://ui.ballmac.com/r/salon-1.json","install":"npx shadcn@latest add @ballmac/salon-1","summary":"Appointment booking. Promise} />. Times show only when the chosen stylist is free; changing stylist or day clears the time. A failed booking keeps the choices.","whenToUse":["A customer-facing booking page","Any choose-what, choose-who, choose-when flow"],"whenNotToUse":["A staff calendar; use calendar-1","Class or event tickets; use billing-1"],"composesWith":["floorplan-1","rentals-1","booking-1"],"dependencies":["lucide-react"],"registryDependencies":["shadcn:utils","button","skeleton","state-view"],"examples":["salon-1-demo","salon-1-quiet","salon-1-loading","salon-1-empty","salon-1-error"],"states":[{"id":"loading","title":"Loading","example":"salon-1-loading","trigger":"state=\"loading\"","note":"Skeleton form and summary under the real heading, announced as loading.","preview":"https://ui.ballmac.com/preview/salon-1-loading"},{"id":"empty","title":"Booking is closed","example":"salon-1-empty","trigger":"state=\"empty\"","note":"Says booking is closed; emptyState sets the copy.","preview":"https://ui.ballmac.com/preview/salon-1-empty"},{"id":"error","title":"Could not load","example":"salon-1-error","trigger":"state=\"error\"","note":"An alert saying nothing was booked, with Try again (onRetry). A booking that fails keeps every choice and says why.","preview":"https://ui.ballmac.com/preview/salon-1-error"}],"preview":"https://ui.ballmac.com/preview/salon-1-demo"},{"name":"search-1","kind":"block","type":"registry:block","title":"Search 1: results page","description":"A search results page: a large search box, the type of result as a filter with live counts, a date filter and sort, results with a trail and highlighted words, and a no-results page that suggests what to try.","category":"blocks","blockCategory":"search","tier":"free","tags":["search","results","filters","facets","highlight","query","docs","site search","enterprise search"],"version":"1.0.0","updated":"2026-10-17","url":"https://ui.ballmac.com/blocks/search-1","registryUrl":"https://ui.ballmac.com/r/search-1.json","install":"npx shadcn@latest add @ballmac/search-1","summary":"A site or workspace search results page. . It filters and ranks the results you pass; for server search, pass the results your API returned for onQueryChange and keep the filters here.","whenToUse":["The page behind a site, docs or workspace search","Mixed results of several types that people narrow by type and date"],"whenNotToUse":["A quick-jump palette (use command or spotlight-search)","Searching inside one list (use search-field with the list)","A help center home (use help-1)"],"composesWith":["header-2","footer-2","app-shell-1","match-highlight"],"dependencies":["lucide-react"],"registryDependencies":["shadcn:utils","button","kbd","match-highlight","select","skeleton","state-view"],"examples":["search-1-demo","search-1-few","search-1-no-results","search-1-loading","search-1-error"],"states":[{"id":"loading","title":"Loading","example":"search-1-loading","trigger":"state=\"loading\"","note":"Skeleton filters and results under the real search box, announced as searching; the box is disabled.","preview":"https://ui.ballmac.com/preview/search-1-loading"},{"id":"empty","title":"No results","example":"search-1-no-results","trigger":"state=\"empty\" (or a search that matches nothing)","note":"A page that says what was searched, suggests a spelling (didYouMean), lists what to try and offers to clear filters; emptyState sets the copy.","preview":"https://ui.ballmac.com/preview/search-1-no-results"},{"id":"error","title":"Could not search","example":"search-1-error","trigger":"state=\"error\"","note":"An alert saying the search was kept, with Try again (onRetry).","preview":"https://ui.ballmac.com/preview/search-1-error"}],"preview":"https://ui.ballmac.com/preview/search-1-demo"},{"name":"seatmap-1","kind":"block","type":"registry:block","title":"Seat map 1: choose seats","description":"A seat map for a cinema or venue: rows with walkways, price tiers, taken and wheelchair seats marked in words, a limit and running total, a best-seats-together helper, keyboard arrows, and a hold that survives a lost seat.","category":"blocks","blockCategory":"seatmap","tier":"free","tags":["seat map","seat picker","cinema","theatre","tickets","booking","venue","seating chart","event","reservation"],"version":"1.0.0","updated":"2026-10-18","url":"https://ui.ballmac.com/blocks/seatmap-1","registryUrl":"https://ui.ballmac.com/r/seatmap-1.json","install":"npx shadcn@latest add @ballmac/seatmap-1","summary":"A seat picker. Promise} />. Seat ids are the row letter plus the number ('C7'); gaps are numbers left empty for walkways. Pick for me chooses the best block of neighbouring seats for the party size. Reject onContinue with an error that has taken: ['C7'] and those seats become taken while the rest stay chosen; any other rejection shows its message.","whenToUse":["Cinema, theatre, concert and event seat selection","Any fixed-seat booking such as trains or classrooms"],"whenNotToUse":["General admission tickets (use event-1)","A table or room booking by time (use a calendar)"],"composesWith":["event-1","invoice-1","locations-1","app-shell-1"],"dependencies":["lucide-react"],"registryDependencies":["shadcn:utils","button","skeleton","state-view"],"examples":["seatmap-1-demo","seatmap-1-chosen","seatmap-1-conflict","seatmap-1-loading","seatmap-1-empty","seatmap-1-error"],"states":[{"id":"loading","title":"Loading","example":"seatmap-1-loading","trigger":"state=\"loading\"","note":"A skeleton hall and summary under the real heading, announced as loading.","preview":"https://ui.ballmac.com/preview/seatmap-1-loading"},{"id":"empty","title":"No showing chosen","example":"seatmap-1-empty","trigger":"state=\"empty\"","note":"Says to choose a date and time first; emptyState sets the copy and can add a button.","preview":"https://ui.ballmac.com/preview/seatmap-1-empty"},{"id":"error","title":"Could not load","example":"seatmap-1-error","trigger":"state=\"error\"","note":"An alert saying nothing was held, with Try again (onRetry). A hold that fails says nothing was charged; a lost seat is marked taken and the others stay chosen.","preview":"https://ui.ballmac.com/preview/seatmap-1-error"}],"preview":"https://ui.ballmac.com/preview/seatmap-1-demo"},{"name":"secrets-1","kind":"block","type":"registry:block","title":"Secrets 1: secrets inventory","description":"An inventory of secrets that never shows a value: name, environment, owner, what reads it, when it was last read and how long since it changed, old ones called out in words, search, filters and Rotate behind a confirmation.","category":"blocks","blockCategory":"secrets","tier":"free","tags":["secrets","rotation","credentials","api keys","security","vault","environment variables","compliance"],"version":"1.0.0","updated":"2026-10-24","url":"https://ui.ballmac.com/blocks/secrets-1","registryUrl":"https://ui.ballmac.com/r/secrets-1.json","install":"npx shadcn@latest add @ballmac/secrets-1","summary":"A secrets inventory. Promise} />. It never takes or shows a secret value. A secret not changed for maxAgeDays or more is called out in words; Rotate opens a confirmation that says what happens, then shows the secret as changed today.","whenToUse":["A security or platform page listing every credential and its age","A rotation checklist for a compliance review"],"whenNotToUse":["Editing or revealing values; this is deliberately read-only","API keys for your own users; use api-key-field"],"composesWith":["audit-1","access-1","settings-1","alerts-1"],"dependencies":["lucide-react"],"registryDependencies":["shadcn:utils","alert-dialog","button","match-highlight","skeleton","state-view","return-focus"],"examples":["secrets-1-demo","secrets-1-fresh","secrets-1-loading","secrets-1-empty","secrets-1-error"],"states":[{"id":"loading","title":"Loading","example":"secrets-1-loading","trigger":"state=\"loading\"","note":"Skeleton rows under the real heading, announced as loading.","preview":"https://ui.ballmac.com/preview/secrets-1-loading"},{"id":"empty","title":"No secrets yet","example":"secrets-1-empty","trigger":"state=\"empty\"","note":"Says no secrets yet; emptyState sets the copy. A search or filter with no match says so.","preview":"https://ui.ballmac.com/preview/secrets-1-empty"},{"id":"error","title":"Could not load","example":"secrets-1-error","trigger":"state=\"error\"","note":"An alert saying nothing was rotated or changed, with Try again (onRetry). A rotation that fails leaves the secret as it was and says why.","preview":"https://ui.ballmac.com/preview/secrets-1-error"}],"preview":"https://ui.ballmac.com/preview/secrets-1-demo"},{"name":"settings-1","kind":"block","type":"registry:block","title":"Settings 1: profile and account","description":"An account settings page: profile with username availability, sign-in details with a change-password dialog, language, time zone and appearance, a type-to-confirm delete, and a sticky save bar that appears only when something changed.","category":"blocks","blockCategory":"settings","tier":"free","tags":["settings","profile","account","preferences","save bar","danger zone"],"version":"1.1.0","updated":"2026-10-11","url":"https://ui.ballmac.com/blocks/settings-1","registryUrl":"https://ui.ballmac.com/r/settings-1.json","install":"npx shadcn@latest add @ballmac/settings-1","summary":"Profile and account settings. Pass defaultValues, email, onSave(values) (throw to show an error) and onDeleteAccount; the dirty-state save bar, validation and availability hint are built in.","whenToUse":["Account and profile pages","Any settings screen where edits are saved together"],"whenNotToUse":["Toggle-style settings that save instantly (use settings-2 or settings-panel)"],"composesWith":["app-shell-1","settings-2","settings-3","billing-1"],"dependencies":["lucide-react"],"registryDependencies":["shadcn:utils","alert-dialog","avatar","badge","button","dialog","field","input","password-input","segmented-control","select","textarea","use-resource","state-view","skeleton"],"examples":["settings-1-demo","settings-1-save","settings-1-loading","settings-1-saving","settings-1-saved","settings-1-error"],"states":[{"id":"loading","title":"Loading","example":"settings-1-loading","trigger":"state=\"loading\"","note":"A skeleton of the profile, sign-in and preferences groups under the real heading, announced as loading.","preview":"https://ui.ballmac.com/preview/settings-1-loading"},{"id":"submitting","title":"Saving","example":"settings-1-saving","trigger":"state=\"submitting\"","note":"A save bar appears with a spinner and \"Saving…\" and Save and Discard are disabled.","preview":"https://ui.ballmac.com/preview/settings-1-saving"},{"id":"success","title":"Saved","example":"settings-1-saved","trigger":"state=\"success\"","note":"The bar says \"All changes saved\".","preview":"https://ui.ballmac.com/preview/settings-1-saved"},{"id":"error","title":"Could not save","example":"settings-1-error","trigger":"state=\"error\"","note":"The bar says the save failed and offers to try again; the edits are kept.","preview":"https://ui.ballmac.com/preview/settings-1-error"}],"preview":"https://ui.ballmac.com/preview/settings-1-demo"},{"name":"settings-2","kind":"block","type":"registry:block","title":"Settings 2: notification preferences","description":"Notification settings that save as you go: digest frequency as radio cards, a grid of switches for each event and channel (cards on phones), and quiet hours with times and weekdays.","category":"blocks","blockCategory":"settings","tier":"free","tags":["settings","notifications","preferences","switches","quiet hours","digest"],"version":"1.1.1","updated":"2026-10-12","url":"https://ui.ballmac.com/blocks/settings-2","registryUrl":"https://ui.ballmac.com/r/settings-2.json","install":"npx shadcn@latest add @ballmac/settings-2","summary":"Notification preferences with instant saving. Pass events=[{ id, label, description }], defaultValues and onChange(values) (return a promise; throw to show an error).","whenToUse":["Notification, alert and email preference pages","Settings that apply the moment they are toggled"],"whenNotToUse":["Forms that need an explicit Save (use settings-1)"],"composesWith":["app-shell-1","settings-1","settings-3"],"dependencies":["lucide-react"],"registryDependencies":["shadcn:utils","input","switch","toggle-group","use-resource","state-view","skeleton"],"examples":["settings-2-demo","settings-2-custom","settings-2-loading","settings-2-saving","settings-2-saved","settings-2-error"],"states":[{"id":"loading","title":"Loading","example":"settings-2-loading","trigger":"state=\"loading\"","note":"A skeleton of the digest choice and the notification list under the real heading, announced as loading.","preview":"https://ui.ballmac.com/preview/settings-2-loading"},{"id":"submitting","title":"Saving","example":"settings-2-saving","trigger":"state=\"submitting\"","note":"\"Saving…\" appears beside the heading.","preview":"https://ui.ballmac.com/preview/settings-2-saving"},{"id":"success","title":"Saved","example":"settings-2-saved","trigger":"state=\"success\"","note":"\"Saved\" with a check appears beside the heading.","preview":"https://ui.ballmac.com/preview/settings-2-saved"},{"id":"error","title":"Could not save","example":"settings-2-error","trigger":"state=\"error\"","note":"The heading shows that saving failed; the choices are kept.","preview":"https://ui.ballmac.com/preview/settings-2-error"}],"preview":"https://ui.ballmac.com/preview/settings-2-demo"},{"name":"settings-3","kind":"block","type":"registry:block","title":"Settings 3: team members and roles","description":"Team management: a seats meter, an invite form with role, role filters and search, a member list with role selects, pending invitations and a confirm-before-remove dialog. Stacks cleanly on phones.","category":"blocks","blockCategory":"settings","tier":"free","tags":["settings","team","members","roles","invite","permissions","seats"],"version":"1.1.0","updated":"2026-10-11","url":"https://ui.ballmac.com/blocks/settings-3","registryUrl":"https://ui.ballmac.com/r/settings-3.json","install":"npx shadcn@latest add @ballmac/settings-3","summary":"Workspace member management. Pass members=[{ id, name, email, role, status, lastActive? }], roles, seats and onInvite / onRoleChange / onRemove; the Owner can't be changed or removed.","whenToUse":["Workspace and organisation settings","Any product with roles and seats"],"whenNotToUse":["A first-run invite step (use onboarding-1)","Sending many invites at once (use invite-members)"],"composesWith":["app-shell-1","settings-1","billing-1","invite-1"],"dependencies":["lucide-react"],"registryDependencies":["shadcn:utils","alert-dialog","avatar","badge","button","dropdown-menu","input","search-field","select","state-view","skeleton"],"examples":["settings-3-demo","settings-3-full","settings-3-loading","settings-3-error","settings-3-no-members"],"states":[{"id":"loading","title":"Loading","example":"settings-3-loading","trigger":"state=\"loading\"","note":"A skeleton with the same shapes as the ready view, announced as loading; nothing is clickable.","preview":"https://ui.ballmac.com/preview/settings-3-loading"},{"id":"empty","title":"Nobody yet","example":"settings-3-no-members","trigger":"state=\"empty\"","note":"The real page with nobody on the team, so inviting still works.","preview":"https://ui.ballmac.com/preview/settings-3-no-members"},{"id":"error","title":"Could not load","example":"settings-3-error","trigger":"state=\"error\"","note":"An error with a Try again button (onRetry), announced as an alert.","preview":"https://ui.ballmac.com/preview/settings-3-error"}],"preview":"https://ui.ballmac.com/preview/settings-3-demo"},{"name":"settings-4","kind":"block","type":"registry:block","title":"Settings 4: integrations directory","description":"An integrations page: search, category filters, connected ones first, Connect with progress and the reason when it fails, Manage, Disconnect after a confirmation, coming-soon entries and a request link.","category":"blocks","blockCategory":"settings","tier":"free","tags":["settings","integrations","apps","connect","marketplace","directory","oauth"],"version":"1.0.0","updated":"2026-10-17","url":"https://ui.ballmac.com/blocks/settings-4","registryUrl":"https://ui.ballmac.com/r/settings-4.json","install":"npx shadcn@latest add @ballmac/settings-4","summary":"An integrations directory. accountName} onDisconnect onManage onRequest />. Throw from onConnect to show the reason on the card; categories come from the data.","whenToUse":["The Integrations or Apps page of a SaaS product","Connecting OAuth apps from settings"],"whenNotToUse":["A marketing page that shows logos of integrations (use features-3 or logo-cloud-1)","API keys and webhooks for developers (use api-key-field and webhook-card)"],"composesWith":["app-shell-1","settings-1","settings-3"],"dependencies":["lucide-react"],"registryDependencies":["shadcn:utils","alert-dialog","badge","button","skeleton","state-view","return-focus"],"examples":["settings-4-demo","settings-4-loading","settings-4-empty","settings-4-error"],"states":[{"id":"loading","title":"Loading","example":"settings-4-loading","trigger":"state=\"loading\"","note":"Skeleton cards; search and the category filter are disabled.","preview":"https://ui.ballmac.com/preview/settings-4-loading"},{"id":"empty","title":"No integrations","example":"settings-4-empty","trigger":"state=\"empty\" (or integrations={[]})","note":"A clear message; emptyState can add an action. A search with no matches says so in place.","preview":"https://ui.ballmac.com/preview/settings-4-empty"},{"id":"error","title":"Could not load","example":"settings-4-error","trigger":"state=\"error\"","note":"An alert with Try again (onRetry). A failed Connect shows its reason on that card instead.","preview":"https://ui.ballmac.com/preview/settings-4-error"}],"preview":"https://ui.ballmac.com/preview/settings-4-demo"},{"name":"settings-5","kind":"block","type":"registry:block","title":"Settings 5: audit log","description":"An audit log of who changed what, by people, AI agents, API keys and the system: grouped by day, filtered by who, area and time, searched, each event opening to its IP, a before-and-after diff and raw details, exported as CSV.","category":"blocks","blockCategory":"settings","tier":"free","tags":["settings","audit log","activity","security","compliance","history","admin","export","csv"],"version":"1.0.0","updated":"2026-10-17","url":"https://ui.ballmac.com/blocks/settings-5","registryUrl":"https://ui.ballmac.com/r/settings-5.json","install":"npx shadcn@latest add @ballmac/settings-5","summary":"An audit log page. . The area filter comes from the part of action before the dot.","whenToUse":["Security and compliance pages of a B2B product (SOC 2, enterprise plans)","Showing what AI agents changed, next to what people changed"],"whenNotToUse":["A friendly activity feed for a team (use activity-feed)","Raw server logs (use log-stream)","Agent traces (use agent-3)"],"composesWith":["settings-3","settings-4","agent-3","app-shell-1"],"dependencies":["lucide-react"],"registryDependencies":["shadcn:utils","button","diff-viewer","json-viewer","segmented-control","select","skeleton","state-view"],"examples":["settings-5-demo","settings-5-loading","settings-5-empty","settings-5-error"],"states":[{"id":"loading","title":"Loading","example":"settings-5-loading","trigger":"state=\"loading\"","note":"Skeleton rows; the filters and Export are disabled.","preview":"https://ui.ballmac.com/preview/settings-5-loading"},{"id":"empty","title":"Nothing recorded","example":"settings-5-empty","trigger":"state=\"empty\" (or events={[]})","note":"Says nothing changed in the chosen time range. Filters with no matches say so in place.","preview":"https://ui.ballmac.com/preview/settings-5-empty"},{"id":"error","title":"Could not load","example":"settings-5-error","trigger":"state=\"error\"","note":"An alert with Try again (onRetry).","preview":"https://ui.ballmac.com/preview/settings-5-error"}],"preview":"https://ui.ballmac.com/preview/settings-5-demo"},{"name":"settings-6","kind":"block","type":"registry:block","title":"Settings 6: data and privacy","description":"A data and privacy page: request an export in JSON or CSV and watch it prepare, set how long messages are kept, and delete the account behind a typed confirmation with a grace period you can cancel.","category":"blocks","blockCategory":"settings","tier":"free","tags":["settings","privacy","gdpr","data export","delete account","retention","compliance","download my data","account"],"version":"1.0.0","updated":"2026-10-18","url":"https://ui.ballmac.com/blocks/settings-6","registryUrl":"https://ui.ballmac.com/r/settings-6.json","install":"npx shadcn@latest add @ballmac/settings-6","summary":"A data and privacy settings page. Promise} onDownload retention='30d' | '1y' | 'forever' onRetentionChange analytics onAnalyticsChange deletionDate onDeleteAccount onCancelDeletion />. Reject a promise to show its message in place. Without onRequestExport, a request is simulated so a demo shows the whole path.","whenToUse":["Privacy and data-rights pages (GDPR/CCPA access and erasure)","The danger zone of any account settings"],"whenNotToUse":["Cookie choices on first visit (use cookie-consent)","Who changed what in the workspace (use settings-5)"],"composesWith":["settings-1","settings-5","app-shell-1"],"dependencies":["lucide-react"],"registryDependencies":["shadcn:utils","alert-dialog","button","checkbox","input","progress","segmented-control","select","skeleton","state-view","switch"],"examples":["settings-6-demo","settings-6-deleting","settings-6-loading","settings-6-error"],"states":[{"id":"loading","title":"Loading","example":"settings-6-loading","trigger":"state=\"loading\"","note":"Skeleton cards under the real heading, announced as loading.","preview":"https://ui.ballmac.com/preview/settings-6-loading"},{"id":"error","title":"Could not load","example":"settings-6-error","trigger":"state=\"error\"","note":"An alert saying nothing was changed, with Try again (onRetry). Failed requests show their message in place.","preview":"https://ui.ballmac.com/preview/settings-6-error"}],"preview":"https://ui.ballmac.com/preview/settings-6-demo"},{"name":"showcase-1","kind":"block","type":"registry:block","title":"Showcase 1: interactive Mac desktop","description":"A working Mac desktop for your landing page: wallpaper, a menu bar with menus and a clock, draggable and resizable windows, desktop widgets and a magnifying dock that launches and relaunches them.","category":"blocks","blockCategory":"showcase","tier":"free","tags":["mac","desktop","showcase","windows","dock","menu bar","demo"],"version":"1.0.0","updated":"2026-10-01","url":"https://ui.ballmac.com/blocks/showcase-1","registryUrl":"https://ui.ballmac.com/r/showcase-1.json","install":"npx shadcn@latest add @ballmac/showcase-1","summary":"A hero-sized interactive screenshot. Set app, time (ISO, fixed) and pass your own window content as children; widgets={false} hides the desk widgets and notes={false} the sample Notes window. Windows can be dragged, resized, zoomed and minimized; the dock reopens closed apps.","whenToUse":["Landing pages for Mac apps that want to be tried, not just seen","Under a hero as a live product tour"],"whenNotToUse":["Showing one screenshot (use laptop-frame or browser-frame)","Non-desktop products"],"composesWith":["hero-5","download-1","features-7","devices-1"],"dependencies":["lucide-react"],"registryDependencies":["shadcn:utils","dock","menu-bar","widgets","window-manager"],"examples":["showcase-1-demo","showcase-1-custom"],"states":[],"statesNone":"Static content: nothing to load, submit or fail.","preview":"https://ui.ballmac.com/preview/showcase-1-demo"},{"name":"signup-1","kind":"block","type":"registry:block","title":"Signup 1: form with benefits column","description":"A signup page: validated name, work email and password with a live strength guide, terms checkbox, SSO option and a check-your-inbox confirmation, beside a benefits list with social proof.","category":"blocks","blockCategory":"auth","tier":"free","tags":["signup","register","auth","password strength","form","sso"],"version":"1.1.0","updated":"2026-10-11","url":"https://ui.ballmac.com/blocks/signup-1","registryUrl":"https://ui.ballmac.com/r/signup-1.json","install":"npx shadcn@latest add @ballmac/signup-1","summary":"A registration page. Pass onSubmit(values) (throw to show an error), onSso (null hides), and benefits / pitch / proof for the left column.","whenToUse":["Self-serve SaaS signup","Pages that should sell while they collect details"],"whenNotToUse":["Invitation acceptance (use invite-1)","Multi-step setup (use onboarding-1)"],"composesWith":["login-2","verify-1","onboarding-1","header-2"],"dependencies":["lucide-react"],"registryDependencies":["shadcn:utils","button","checkbox","field","input","password-input","media","use-resource"],"examples":["signup-1-demo","signup-1-simple","signup-1-submitting","signup-1-success","signup-1-error"],"states":[{"id":"submitting","title":"Creating account","example":"signup-1-submitting","trigger":"state=\"submitting\"","note":"Every field and button is disabled while the request is in flight, the button shows a spinner, and the form is marked busy.","preview":"https://ui.ballmac.com/preview/signup-1-submitting"},{"id":"success","title":"Check your inbox","example":"signup-1-success","trigger":"state=\"success\"","note":"The confirmation screen the flow ends on.","preview":"https://ui.ballmac.com/preview/signup-1-success"},{"id":"error","title":"Could not create","example":"signup-1-error","trigger":"state=\"error\"","note":"An alert above the form with the message (errorState.description to change it); the fields stay editable so it can be fixed.","preview":"https://ui.ballmac.com/preview/signup-1-error"}],"preview":"https://ui.ballmac.com/preview/signup-1-demo"},{"name":"slo-1","kind":"block","type":"registry:block","title":"SLO 1: service level objectives","description":"Service level objectives as cards: the goal, how it is going, error budget left in percent and minutes as a labelled meter, burn rate in words, a chart with the target drawn on it, risky ones listed first, and a filter by service.","category":"blocks","blockCategory":"slo","tier":"free","tags":["slo","sli","reliability","error budget","sre","uptime","monitoring","devops"],"version":"1.0.0","updated":"2026-10-24","url":"https://ui.ballmac.com/blocks/slo-1","registryUrl":"https://ui.ballmac.com/r/slo-1.json","install":"npx shadcn@latest add @ballmac/slo-1","summary":"Service level objectives. . Error budget left = 1 minus the shortfall divided by the allowed shortfall; it is shown in percent and minutes. Order is target missed, burning fast (burn 2 or more, or under 25% left), watch, healthy. Exports budgetLeft.","whenToUse":["A reliability overview for a team that promises uptime or speed","Deciding whether it is safe to ship or time to slow down"],"whenNotToUse":["A public status page; use status-1","Live charts of a metric; use charts-1"],"composesWith":["incident-1","queues-1","status-1","dashboard-1"],"dependencies":["lucide-react"],"registryDependencies":["shadcn:utils","skeleton","state-view"],"examples":["slo-1-demo","slo-1-healthy","slo-1-loading","slo-1-empty","slo-1-error"],"states":[{"id":"loading","title":"Loading","example":"slo-1-loading","trigger":"state=\"loading\"","note":"Skeleton cards under the real heading, announced as loading.","preview":"https://ui.ballmac.com/preview/slo-1-loading"},{"id":"empty","title":"No objectives yet","example":"slo-1-empty","trigger":"state=\"empty\"","note":"Says no objectives yet; emptyState sets the copy.","preview":"https://ui.ballmac.com/preview/slo-1-empty"},{"id":"error","title":"Could not load","example":"slo-1-error","trigger":"state=\"error\"","note":"An alert saying nothing was changed, with Try again (onRetry).","preview":"https://ui.ballmac.com/preview/slo-1-error"}],"preview":"https://ui.ballmac.com/preview/slo-1-demo"},{"name":"stats-1","kind":"block","type":"registry:block","title":"Stats 1: headline metrics with trends","description":"Four large numbers in a hairline grid that count up on scroll, each with a change badge, a small trend line and one line of context. Heading and copy sit above.","category":"blocks","blockCategory":"stats","tier":"free","tags":["stats","metrics","numbers","social proof","sparkline"],"version":"1.0.1","updated":"2026-10-11","url":"https://ui.ballmac.com/blocks/stats-1","registryUrl":"https://ui.ballmac.com/r/stats-1.json","install":"npx shadcn@latest add @ballmac/stats-1","summary":"Social proof as numbers. Pass stats=[{ label, value, prefix?, suffix?, decimals?, delta?, trend?, trendLabel?, note? }].","whenToUse":["Under a hero or logo cloud as proof","Company and about pages"],"whenNotToUse":["Live product dashboards (use stat-card or kpi-row)","Numbers you cannot back up"],"composesWith":["hero-7","logo-cloud-1","testimonials-2","cta-1"],"dependencies":["lucide-react"],"registryDependencies":["shadcn:utils","number-ticker","sparkline"],"examples":["stats-1-demo","stats-1-simple"],"states":[],"statesNone":"Static content: nothing to load, submit or fail.","preview":"https://ui.ballmac.com/preview/stats-1-demo"},{"name":"status-1","kind":"block","type":"registry:block","title":"Status 1: system status page","description":"A public status page: an overall banner worked out from the data, each service with a 90-day history you scrub by pointer or arrow keys, live incidents as a timeline of updates, two weeks of past incidents and a subscribe box.","category":"blocks","blockCategory":"status","tier":"free","tags":["status","uptime","incidents","system status","outage","maintenance","reliability","operational","status page"],"version":"1.0.0","updated":"2026-10-18","url":"https://ui.ballmac.com/blocks/status-1","registryUrl":"https://ui.ballmac.com/r/status-1.json","install":"npx shadcn@latest add @ballmac/status-1","summary":"A status page. . The banner is the worst current status; an incident is live until its newest update is resolved. Pass today yourself; the block never reads the clock.","whenToUse":["A public status page for a service","An internal reliability page showing uptime and incidents"],"whenNotToUse":["A single status dot or badge row (use status-dot or status-badge-row)","Raw server logs (use log-stream)"],"composesWith":["header-1","footer-1","settings-5"],"dependencies":["lucide-react"],"registryDependencies":["shadcn:utils","button","input","skeleton","state-view"],"examples":["status-1-demo","status-1-operational","status-1-outage","status-1-loading","status-1-empty","status-1-error"],"states":[{"id":"loading","title":"Loading","example":"status-1-loading","trigger":"state=\"loading\"","note":"A skeleton banner and service rows under the real heading, announced as loading.","preview":"https://ui.ballmac.com/preview/status-1-loading"},{"id":"empty","title":"No services listed","example":"status-1-empty","trigger":"state=\"empty\" (or components={[]})","note":"Says services appear once added; emptyState sets the copy and can add a button.","preview":"https://ui.ballmac.com/preview/status-1-empty"},{"id":"error","title":"Could not load","example":"status-1-error","trigger":"state=\"error\"","note":"An alert that says this does not mean something is down, with Try again (onRetry).","preview":"https://ui.ballmac.com/preview/status-1-error"}],"preview":"https://ui.ballmac.com/preview/status-1-demo"},{"name":"survey-1","kind":"block","type":"registry:block","title":"Survey 1: NPS feedback","description":"A three-question feedback card: the 0 to 10 recommend question as big buttons, a follow-up that changes with the answer, an optional comment, a progress bar, Back that keeps answers, and a failed send that keeps what was typed.","category":"blocks","blockCategory":"survey","tier":"free","tags":["survey","nps","feedback","score","rating","customer satisfaction","csat","poll","form"],"version":"1.0.0","updated":"2026-10-18","url":"https://ui.ballmac.com/blocks/survey-1","registryUrl":"https://ui.ballmac.com/r/survey-1.json","install":"npx shadcn@latest add @ballmac/survey-1","summary":"An NPS survey card. Promise} />. Scores 9 and 10 get the high reasons ('What do you like most?'), everything else the low ones. Reject onSubmit to show the error with the answers kept. Pass state to drive it, or leave it out to run by itself.","whenToUse":["A feedback page linked from an email","Asking for NPS after onboarding or a milestone"],"whenNotToUse":["A floating widget in the app (use feedback-widget)","A long, multi-section form"],"composesWith":["contact-1","app-shell-1"],"dependencies":["lucide-react"],"registryDependencies":["shadcn:utils","button","textarea","use-resource"],"examples":["survey-1-demo","survey-1-sending","survey-1-sent","survey-1-error"],"states":[{"id":"submitting","title":"Sending","example":"survey-1-sending","trigger":"state=\"submitting\"","note":"The comment and buttons are disabled, Send shows a spinner and the card is marked busy.","preview":"https://ui.ballmac.com/preview/survey-1-sending"},{"id":"success","title":"Thank you","example":"survey-1-sent","trigger":"state=\"success\"","note":"The progress bar fills and the card thanks the person; the words change for a fan and for someone who was unhappy.","preview":"https://ui.ballmac.com/preview/survey-1-sent"},{"id":"error","title":"Could not send","example":"survey-1-error","trigger":"state=\"error\"","note":"An alert on the last step saying nothing was lost, with Try again; every answer is still there.","preview":"https://ui.ballmac.com/preview/survey-1-error"}],"preview":"https://ui.ballmac.com/preview/survey-1-demo"},{"name":"tasks-1","kind":"block","type":"registry:block","title":"Tasks 1: task list","description":"A tasks page: a progress ring and quick add, tasks grouped as overdue, today, upcoming and no date, a strike-through that draws itself, inline edit, reordering by button or Alt and arrow keys, shortcuts and Undo on delete.","category":"blocks","blockCategory":"tasks","tier":"free","tags":["tasks","todo","to-do","checklist","productivity","due dates","priority","keyboard","reorder","list"],"version":"1.0.0","updated":"2026-10-18","url":"https://ui.ballmac.com/blocks/tasks-1","registryUrl":"https://ui.ballmac.com/r/tasks-1.json","install":"npx shadcn@latest add @ballmac/tasks-1","summary":"A personal task list. . Pass today yourself (an ISO date) so the server and browser agree about what is overdue; the block never reads the clock. Groups come from due dates.","whenToUse":["A personal or team to-do list inside an app","A today view with overdue items called out"],"whenNotToUse":["A project board (use kanban-1)","A one-time setup checklist (use onboarding-checklist)","Gantt or schedule views"],"composesWith":["app-shell-1","kanban-1","calendar-1","inbox-1"],"dependencies":["lucide-react"],"registryDependencies":["shadcn:utils","blur-fade","button","checkbox","circular-progress","kbd","segmented-control","select","skeleton","state-view"],"examples":["tasks-1-demo","tasks-1-completed","tasks-1-empty","tasks-1-loading","tasks-1-error"],"states":[{"id":"loading","title":"Loading","example":"tasks-1-loading","trigger":"state=\"loading\"","note":"A skeleton of the summary and the task rows under the real heading, announced as loading.","preview":"https://ui.ballmac.com/preview/tasks-1-loading"},{"id":"empty","title":"Nothing to do","example":"tasks-1-empty","trigger":"state=\"empty\" (or tasks={[]})","note":"A calm message pointing at the add box; a filter with no matches says so instead. emptyState sets the copy.","preview":"https://ui.ballmac.com/preview/tasks-1-empty"},{"id":"error","title":"Could not load","example":"tasks-1-error","trigger":"state=\"error\"","note":"An alert saying nothing was lost, with Try again (onRetry).","preview":"https://ui.ballmac.com/preview/tasks-1-error"}],"preview":"https://ui.ballmac.com/preview/tasks-1-demo"},{"name":"team-1","kind":"block","type":"registry:block","title":"Team 1: portrait grid with hover bios","description":"A grid of team portraits with name, role, location and links. On hover or keyboard focus a bio slides up over the photo; phones show it inline. Initial tiles when there is no photo.","category":"blocks","blockCategory":"team","tier":"free","tags":["team","people","about","company","portraits"],"version":"1.0.0","updated":"2026-10-01","url":"https://ui.ballmac.com/blocks/team-1","registryUrl":"https://ui.ballmac.com/r/team-1.json","install":"npx shadcn@latest add @ballmac/team-1","summary":"An About-page team section. Pass members=[{ name, role, bio?, location?, image?, links? }].","whenToUse":["About and careers pages","Showing the humans behind a product"],"whenNotToUse":["Long staff directories (use a table)"],"composesWith":["stats-1","testimonials-2","cta-1","footer-1"],"dependencies":["lucide-react"],"registryDependencies":["shadcn:utils","button","media"],"examples":["team-1-demo","team-1-small"],"states":[],"statesNone":"Static content: nothing to load, submit or fail.","preview":"https://ui.ballmac.com/preview/team-1-demo"},{"name":"testimonials-1","kind":"block","type":"registry:block","title":"Testimonials 1: scrolling wall of quotes","description":"A wall of testimonial cards in three columns that scroll at different speeds in opposite directions, pausing on hover, with a plain list on phones.","category":"blocks","blockCategory":"testimonials","tier":"free","tags":["testimonials","social proof","quotes","marquee"],"version":"1.0.0","updated":"2026-09-29","url":"https://ui.ballmac.com/blocks/testimonials-1","registryUrl":"https://ui.ballmac.com/r/testimonials-1.json","install":"npx shadcn@latest add @ballmac/testimonials-1","summary":"Social proof section: pass `testimonials` ({ quote, name, role }[]); they are spread across three vertical marquees. Replace the placeholder quotes with real ones.","whenToUse":["Landing pages after features or pricing","Showing many short quotes without a carousel"],"whenNotToUse":["One or two quotes (use a single large quote in a section)"],"composesWith":["features-1","pricing-1","cta-1"],"dependencies":[],"registryDependencies":["shadcn:utils","avatar","marquee"],"examples":["testimonials-1-demo"],"states":[],"statesNone":"Static content: nothing to load, submit or fail.","preview":"https://ui.ballmac.com/preview/testimonials-1-demo"},{"name":"testimonials-2","kind":"block","type":"registry:block","title":"Testimonials 2: featured quote with avatar picker","description":"One large quote at a time with the person, role and a highlighted result. A row of avatars switches quotes with arrow keys; optional gentle autoplay that pauses on hover and focus.","category":"blocks","blockCategory":"testimonials","tier":"free","tags":["testimonials","quote","carousel","social proof","avatars"],"version":"1.0.0","updated":"2026-10-01","url":"https://ui.ballmac.com/blocks/testimonials-2","registryUrl":"https://ui.ballmac.com/r/testimonials-2.json","install":"npx shadcn@latest add @ballmac/testimonials-2","summary":"A focused testimonial section. Pass items=[{ quote, name, role, company, image?, result? }]; control the index with value/onValueChange or let it manage itself.","whenToUse":["Three to five strong quotes","Above a pricing or CTA section"],"whenNotToUse":["Many short reviews (use testimonials-1)"],"composesWith":["stats-1","pricing-2","cta-1","logo-cloud-1"],"dependencies":["lucide-react","motion@^12","radix-ui"],"registryDependencies":["shadcn:utils","avatar","badge","button"],"examples":["testimonials-2-demo","testimonials-2-autoplay"],"states":[],"statesNone":"Static content: nothing to load, submit or fail.","preview":"https://ui.ballmac.com/preview/testimonials-2-demo"},{"name":"tickets-1","kind":"block","type":"registry:block","title":"Tickets 1: support ticket","description":"One support ticket as an agent sees it: replies and private notes, a reply timer, a composer that switches between Reply and Internal note with canned replies, and a side panel for the customer, assignee, status and priority.","category":"blocks","blockCategory":"tickets","tier":"free","tags":["tickets","support","helpdesk","customer service","conversation","sla","internal notes","canned replies","inbox"],"version":"1.0.0","updated":"2026-10-18","url":"https://ui.ballmac.com/blocks/tickets-1","registryUrl":"https://ui.ballmac.com/r/tickets-1.json","install":"npx shadcn@latest add @ballmac/tickets-1","summary":"A support ticket. Promise} onStatusChange onPriorityChange onAssign />. The reply timer shows only while the last message is from the customer; it says time left, or how late. A sent reply sets the status to Waiting on customer. Reject onSend and the message stays with Retry. Pass now yourself; the block never reads the clock.","whenToUse":["A helpdesk or support tool's ticket view","An internal request or approval thread with private notes"],"whenNotToUse":["A live chat widget (use chat-1)","A public help center (use help-1)"],"composesWith":["inbox-1","app-shell-1","help-1","directory-1"],"dependencies":["lucide-react"],"registryDependencies":["shadcn:utils","button","cover-art","select","skeleton","state-view","textarea"],"examples":["tickets-1-demo","tickets-1-late","tickets-1-failed","tickets-1-loading","tickets-1-empty","tickets-1-error"],"states":[{"id":"loading","title":"Loading","example":"tickets-1-loading","trigger":"state=\"loading\"","note":"A skeleton conversation and side panel, announced as loading.","preview":"https://ui.ballmac.com/preview/tickets-1-loading"},{"id":"empty","title":"Ticket not found","example":"tickets-1-empty","trigger":"state=\"empty\"","note":"Says the ticket may have been merged or deleted; emptyState sets the copy and can add a link back.","preview":"https://ui.ballmac.com/preview/tickets-1-empty"},{"id":"error","title":"Could not load","example":"tickets-1-error","trigger":"state=\"error\"","note":"An alert saying nothing was changed, with Try again (onRetry). A message that fails to send stays in the thread with Not sent and Retry.","preview":"https://ui.ballmac.com/preview/tickets-1-error"}],"preview":"https://ui.ballmac.com/preview/tickets-1-demo"},{"name":"timesheet-1","kind":"block","type":"registry:block","title":"Timesheet 1: weekly hours","description":"A weekly timesheet: a row per project and a box per day, time typed the way people say it (1.5, 1:30, 90m), totals worked out as you type, daily bars that say when a day runs over, weeks to page through, and submit that locks the week.","category":"blocks","blockCategory":"timesheet","tier":"free","tags":["timesheet","time tracking","hours","weekly","projects","billable","payroll","work log","submit"],"version":"1.0.0","updated":"2026-10-18","url":"https://ui.ballmac.com/blocks/timesheet-1","registryUrl":"https://ui.ballmac.com/r/timesheet-1.json","install":"npx shadcn@latest add @ballmac/timesheet-1","summary":"A weekly timesheet. ...} onSubmit={({ weekStart, minutes, entries }) => Promise} />. Typed time accepts 1.5, 1,5, 1:30, 90m and 2h; entries are stored as minutes. A day over 24 hours is refused with the reason; a weekday over dayTarget shows how much over. Submitting locks that week. Reject onSubmit to show the reason and stay open.","whenToUse":["Time tracking for agencies, consultants and teams","A weekly hours entry before payroll or invoicing"],"whenNotToUse":["A start/stop timer","A calendar of meetings (use calendar-1)"],"composesWith":["invoice-1","goals-1","tasks-1","app-shell-1"],"dependencies":["lucide-react"],"registryDependencies":["shadcn:utils","button","select","skeleton","state-view"],"examples":["timesheet-1-demo","timesheet-1-submitted","timesheet-1-loading","timesheet-1-empty","timesheet-1-error"],"states":[{"id":"loading","title":"Loading","example":"timesheet-1-loading","trigger":"state=\"loading\"","note":"A skeleton grid under the real heading, announced as loading.","preview":"https://ui.ballmac.com/preview/timesheet-1-loading"},{"id":"empty","title":"No projects","example":"timesheet-1-empty","trigger":"state=\"empty\" (or projects={[]})","note":"Says to add a project; emptyState sets the copy and can add a button.","preview":"https://ui.ballmac.com/preview/timesheet-1-empty"},{"id":"error","title":"Could not load","example":"timesheet-1-error","trigger":"state=\"error\"","note":"An alert saying nothing was changed, with Try again (onRetry). A failed submit says nothing was lost, in place under the table.","preview":"https://ui.ballmac.com/preview/timesheet-1-error"}],"preview":"https://ui.ballmac.com/preview/timesheet-1-demo"},{"name":"tour-1","kind":"block","type":"registry:block","title":"Tour 1: guided product tour","description":"A guided product tour: a spotlight lifts one part of your interface out of a dimmed page while a card says what it is for, with Next, Back, arrow keys, Escape, a progress bar, focus that follows the step, and a restart.","category":"blocks","blockCategory":"tour","tier":"free","tags":["product tour","onboarding","walkthrough","tooltips","coachmarks","spotlight","guide","tutorial","first run"],"version":"1.0.0","updated":"2026-10-18","url":"https://ui.ballmac.com/blocks/tour-1","registryUrl":"https://ui.ballmac.com/r/tour-1.json","install":"npx shadcn@latest add @ballmac/tour-1","summary":"A product tour. ...}>{your interface}. Mark the elements to point at with data-tour='search' inside the children; leave children out to tour a built-in sample app. The page behind is inert while the tour runs; the spotlight and card follow each target and the card stays inside the stage, above or below the target.","whenToUse":["First-run onboarding that points at real parts of the interface","Introducing a redesign or a new feature"],"whenNotToUse":["A setup checklist (use onboarding-1)","One-off hints (use tooltip or popover)"],"composesWith":["onboarding-1","app-shell-1","dashboard-1"],"dependencies":["lucide-react"],"registryDependencies":["shadcn:utils","button"],"examples":["tour-1-demo","tour-1-running"],"states":[],"statesNone":"A guided overlay with no data of its own: nothing to load, submit or fail.","preview":"https://ui.ballmac.com/preview/tour-1-demo"},{"name":"trip-1","kind":"block","type":"registry:block","title":"Trip 1: day-by-day itinerary","description":"A trip itinerary: destination, dates and a countdown, then day by day what is booked and when with copyable booking codes and unbooked items marked in words, a cost breakdown, per-person total, type filters and a packing list with progress.","category":"blocks","blockCategory":"trip","tier":"free","tags":["trip","itinerary","travel","vacation","holiday","plan","flights","hotel","packing","booking"],"version":"1.0.0","updated":"2026-10-18","url":"https://ui.ballmac.com/blocks/trip-1","registryUrl":"https://ui.ballmac.com/r/trip-1.json","install":"npx shadcn@latest add @ballmac/trip-1","summary":"A trip itinerary. . Nights, days to go, the total, the per-person cost and the cost by type are worked out from the items; a pending item says Not booked yet and is listed in a notice. Pass today yourself; the block never reads the clock.","whenToUse":["A shared trip plan or a confirmation page for a booked trip","Travel apps and agency itineraries"],"whenNotToUse":["Booking flights or hotels (use a booking flow)","A single event agenda (use event-1)"],"composesWith":["event-1","locations-1","invoice-1","header-1"],"dependencies":["lucide-react"],"registryDependencies":["shadcn:utils","copy-button","cover-art"],"examples":["trip-1-demo","trip-1-underway"],"states":[],"statesNone":"Static content with its own filters and checklist: nothing to load, submit or fail.","preview":"https://ui.ballmac.com/preview/trip-1-demo"},{"name":"trust-1","kind":"block","type":"registry:block","title":"Trust 1: security and trust center","description":"A trust center: certification cards with dates, the security controls behind them, documents where audit reports ask for a request under a confidentiality agreement, a subprocessor table with change alerts, and a disclosure contact.","category":"blocks","blockCategory":"trust","tier":"free","tags":["trust","security","compliance","soc 2","iso 27001","gdpr","hipaa","subprocessors","privacy","enterprise","audit"],"version":"1.0.0","updated":"2026-10-18","url":"https://ui.ballmac.com/blocks/trust-1","registryUrl":"https://ui.ballmac.com/r/trust-1.json","install":"npx shadcn@latest add @ballmac/trust-1","summary":"A security and compliance page. …} onSubscribe={async (email) => …} />. Gated documents open a request dialog with validation and submitting, success and error states.","whenToUse":["The trust, security or compliance page a B2B buyer's security team reads","Sharing SOC 2 and penetration test reports behind a request"],"whenNotToUse":["A privacy policy or terms (plain text pages)","A system status page (use the relay template's status page or stats-pro-2)","A cookie banner (use cookie-consent)"],"composesWith":["header-2","footer-2","about-1","faq-1","contact-1"],"dependencies":["lucide-react"],"registryDependencies":["shadcn:utils","blur-fade","button","checkbox","cover-art","dialog","input","skeleton","spotlight-card","state-view","return-focus"],"examples":["trust-1-demo","trust-1-request","trust-1-loading","trust-1-error"],"states":[{"id":"loading","title":"Loading","example":"trust-1-loading","trigger":"state=\"loading\"","note":"Skeleton certificate and control cards under the real header, announced as loading.","preview":"https://ui.ballmac.com/preview/trust-1-loading"},{"id":"error","title":"Could not load","example":"trust-1-error","trigger":"state=\"error\"","note":"An alert with Try again (onRetry). The header stays so the page never looks broken.","preview":"https://ui.ballmac.com/preview/trust-1-error"}],"preview":"https://ui.ballmac.com/preview/trust-1-demo"},{"name":"upload-1","kind":"block","type":"registry:block","title":"Upload 1: upload manager","description":"An upload manager: a drop area that reacts to dragging, validation that explains each rejection, and a list where every file has its own state (waiting, uploading with progress, finishing, done, or failed with a reason and retry).","category":"blocks","blockCategory":"upload","tier":"free","tags":["upload","files","drag and drop","dropzone","progress","retry","validation","attachments","images","multi-file"],"version":"1.0.0","updated":"2026-10-17","url":"https://ui.ballmac.com/blocks/upload-1","registryUrl":"https://ui.ballmac.com/r/upload-1.json","install":"npx shadcn@latest add @ballmac/upload-1","summary":"A multi-file upload page. { /* send it; call report(0..1); throw to fail */ }} onItemsChange />. Each file is one of queued, uploading, processing, done or failed; rejected files (wrong type, too large, over the limit) are listed as failed with the reason. Without onUpload it simulates uploading.","whenToUse":["Uploading several files to a project, library or ticket","Anywhere progress per file, retry and cancel matter"],"whenNotToUse":["Picking one file in a form (use file-dropzone)","Attaching a file to a chat message (use chat-attachment)","Avatar upload (use file-dropzone with a preview)"],"composesWith":["app-shell-1","billing-1","file-dropzone"],"dependencies":["lucide-react"],"registryDependencies":["shadcn:utils","button","media","skeleton","state-view"],"examples":["upload-1-demo","upload-1-empty","upload-1-loading","upload-1-error"],"states":[{"id":"loading","title":"Loading","example":"upload-1-loading","trigger":"state=\"loading\"","note":"A skeleton of the drop area and the list under the real heading.","preview":"https://ui.ballmac.com/preview/upload-1-loading"},{"id":"empty","title":"Nothing yet","example":"upload-1-empty","trigger":"state=\"empty\" (or defaultItems={[]})","note":"Just the drop area, which is the empty state: it says where to drop and what is accepted.","preview":"https://ui.ballmac.com/preview/upload-1-empty"},{"id":"error","title":"Uploads unavailable","example":"upload-1-error","trigger":"state=\"error\"","note":"An alert with Try again (onRetry) and a drop area that is switched off, so nothing is dropped into a broken page.","preview":"https://ui.ballmac.com/preview/upload-1-error"}],"preview":"https://ui.ballmac.com/preview/upload-1-demo"},{"name":"verify-1","kind":"block","type":"registry:block","title":"Verify 1: one-time code with resend","description":"A code-entry screen: masked email, six slots that accept typing and pasting, automatic submit on the last digit, shake and alert on a wrong code, a resend countdown and an animated success state.","category":"blocks","blockCategory":"auth","tier":"free","tags":["verify","otp","code","two-factor","email","resend"],"version":"1.1.0","updated":"2026-10-11","url":"https://ui.ballmac.com/blocks/verify-1","registryUrl":"https://ui.ballmac.com/r/verify-1.json","install":"npx shadcn@latest add @ballmac/verify-1","summary":"Email or SMS code verification. Pass email, length, onVerify(code) (throw for a wrong code) and onResend. Without onVerify any code except all zeros succeeds, so you can try every state.","whenToUse":["Email confirmation after signup","Two-factor sign-in and sensitive actions"],"whenNotToUse":["Magic links that need no typing"],"composesWith":["signup-1","login-2","forgot-password-1","onboarding-1"],"dependencies":["lucide-react","motion@^12"],"registryDependencies":["shadcn:utils","button","input-otp","use-resource"],"examples":["verify-1-demo","verify-1-four","verify-1-checking","verify-1-verified","verify-1-wrong-code"],"states":[{"id":"submitting","title":"Checking the code","example":"verify-1-checking","trigger":"state=\"submitting\"","note":"The code slots are disabled and the status says it is being checked.","preview":"https://ui.ballmac.com/preview/verify-1-checking"},{"id":"success","title":"Verified","example":"verify-1-verified","trigger":"state=\"success\"","note":"The confirmation screen the flow ends on.","preview":"https://ui.ballmac.com/preview/verify-1-verified"},{"id":"error","title":"Wrong code","example":"verify-1-wrong-code","trigger":"state=\"error\"","note":"The slots turn red, shake once (not under reduced motion) and the status says the code is wrong.","preview":"https://ui.ballmac.com/preview/verify-1-wrong-code"}],"preview":"https://ui.ballmac.com/preview/verify-1-demo"},{"name":"waitlist-1","kind":"block","type":"registry:block","title":"Waitlist 1: referral waitlist","description":"A launch waitlist that grows by referral: an email form with a count of who is waiting, then the person's place in line, their own share link to copy, and a ladder of rewards that fills as friends join.","category":"blocks","blockCategory":"waitlist","tier":"free","tags":["waitlist","launch","referral","early access","signup","invite","viral","coming soon","pre-launch"],"version":"1.0.0","updated":"2026-10-18","url":"https://ui.ballmac.com/blocks/waitlist-1","registryUrl":"https://ui.ballmac.com/r/waitlist-1.json","install":"npx shadcn@latest add @ballmac/waitlist-1","summary":"A referral waitlist. Promise<{ position, link, referrals }>} defaultJoined state />. After joining it shows #position, the share link with a copy button, and rewards that unlock as referrals reaches each at. Reject onJoin to show its message with the email kept.","whenToUse":["A pre-launch landing page that collects emails","Rolling out access in waves with referral rewards"],"whenNotToUse":["A newsletter signup (use newsletter-1)","A full sign-up form (use auth blocks)"],"composesWith":["hero-1","faq-1","footer-1","logo-cloud-1"],"dependencies":["lucide-react"],"registryDependencies":["shadcn:utils","button","copy-button","cover-art","input","number-ticker","use-resource"],"examples":["waitlist-1-demo","waitlist-1-joined","waitlist-1-sending","waitlist-1-error"],"states":[{"id":"submitting","title":"Joining","example":"waitlist-1-sending","trigger":"state=\"submitting\"","note":"The field and button are disabled, the button says Joining with a spinner and the section is marked busy.","preview":"https://ui.ballmac.com/preview/waitlist-1-sending"},{"id":"success","title":"On the list","example":"waitlist-1-joined","trigger":"state=\"success\"","note":"The second screen: place in line, share link and the reward ladder.","preview":"https://ui.ballmac.com/preview/waitlist-1-joined"},{"id":"error","title":"Could not join","example":"waitlist-1-error","trigger":"state=\"error\"","note":"An alert saying the email is still there; the person can press Join again.","preview":"https://ui.ballmac.com/preview/waitlist-1-error"}],"preview":"https://ui.ballmac.com/preview/waitlist-1-demo"},{"name":"webhooks-1","kind":"block","type":"registry:block","title":"Webhooks 1: endpoints and deliveries","description":"A webhooks manager: endpoints with health from recent deliveries, signing secret and events, a delivery log with status codes and timing, payload and response per delivery with Send again, and an add dialog that validates.","category":"blocks","blockCategory":"webhooks","tier":"free","tags":["webhooks","events","endpoints","deliveries","developer","integrations","api","retry","signing secret","logs"],"version":"1.0.0","updated":"2026-10-18","url":"https://ui.ballmac.com/blocks/webhooks-1","registryUrl":"https://ui.ballmac.com/r/webhooks-1.json","install":"npx shadcn@latest add @ballmac/webhooks-1","summary":"A webhooks manager. Promise} onToggle onResend={(endpoint, delivery) => Promise} defaultSelectedId defaultOpenDeliveryId />. Health (Healthy 90% or more, Some failing 50% or more, Failing, Disabled) is worked out from each endpoint's last ten deliveries. Adding requires an https URL and at least one event. Reject onCreate or onResend to show the message in place.","whenToUse":["The developer settings of an API or SaaS product","Debugging why events did not arrive"],"whenNotToUse":["A single webhook status tile (use webhook-card)","Raw logs of everything (use log-stream)"],"composesWith":["dev-1","settings-4","settings-5","app-shell-1"],"dependencies":["lucide-react"],"registryDependencies":["shadcn:utils","button","checkbox","copy-button","dialog","input","json-viewer","skeleton","state-view","switch","return-focus"],"examples":["webhooks-1-demo","webhooks-1-failing","webhooks-1-loading","webhooks-1-empty","webhooks-1-error"],"states":[{"id":"loading","title":"Loading","example":"webhooks-1-loading","trigger":"state=\"loading\"","note":"A skeleton list and panel under the real heading, announced as loading.","preview":"https://ui.ballmac.com/preview/webhooks-1-loading"},{"id":"empty","title":"No endpoints","example":"webhooks-1-empty","trigger":"state=\"empty\" (or endpoints={[]})","note":"Explains what an endpoint is and offers Add an endpoint; emptyState sets the copy.","preview":"https://ui.ballmac.com/preview/webhooks-1-empty"},{"id":"error","title":"Could not load","example":"webhooks-1-error","trigger":"state=\"error\"","note":"An alert saying nothing was changed, with Try again (onRetry). A failed Send again and a failed add show their message in place.","preview":"https://ui.ballmac.com/preview/webhooks-1-error"}],"preview":"https://ui.ballmac.com/preview/webhooks-1-demo"},{"name":"workflow-1","kind":"block","type":"registry:block","title":"Workflow 1: automation builder","description":"An automation builder as a vertical flow: a trigger, then conditions, waits and actions you add, reorder and delete, each opening to its settings, and a test run that shows every step as done or where a condition stopped it.","category":"blocks","blockCategory":"workflow","tier":"free","tags":["workflow","automation","trigger","conditions","actions","zapier","rules","no-code","builder","flow"],"version":"1.0.0","updated":"2026-10-18","url":"https://ui.ballmac.com/blocks/workflow-1","registryUrl":"https://ui.ballmac.com/r/workflow-1.json","install":"npx shadcn@latest add @ballmac/workflow-1","summary":"An automation builder. ...} />. Test run walks the steps with the sample facts; a condition that fails stops it there. Every edit calls onChange with the whole flow.","whenToUse":["Rules and automations in a SaaS product","A no-code 'when this happens, do that' editor"],"whenNotToUse":["A marketing diagram of a workflow (use a features block)","A graph with branches and loops"],"composesWith":["flags-1","webhooks-1","app-shell-1","tickets-1"],"dependencies":["lucide-react"],"registryDependencies":["shadcn:utils","button","input","select","skeleton","state-view","switch"],"examples":["workflow-1-demo","workflow-1-open","workflow-1-loading","workflow-1-empty","workflow-1-error"],"states":[{"id":"loading","title":"Loading","example":"workflow-1-loading","trigger":"state=\"loading\"","note":"Skeleton step cards under the real heading, announced as loading.","preview":"https://ui.ballmac.com/preview/workflow-1-loading"},{"id":"empty","title":"Nothing automated yet","example":"workflow-1-empty","trigger":"state=\"empty\"","note":"Says to pick what starts it and add what should happen; emptyState sets the copy and can add a button.","preview":"https://ui.ballmac.com/preview/workflow-1-empty"},{"id":"error","title":"Could not load","example":"workflow-1-error","trigger":"state=\"error\"","note":"An alert saying nothing was changed, with Try again (onRetry).","preview":"https://ui.ballmac.com/preview/workflow-1-error"}],"preview":"https://ui.ballmac.com/preview/workflow-1-demo"},{"name":"workorder-1","kind":"block","type":"registry:block","title":"Work order 1: repair job","description":"A repair work order: customer, item and reported fault, five steps with one button to advance, parts and labour with subtotal, tax and total, a line form, one-click customer messages, and the history so far.","category":"blocks","blockCategory":"workorder","tier":"free","tags":["work order","repair","service","workshop","field service","parts","labour","job card"],"version":"1.0.0","updated":"2026-10-24","url":"https://ui.ballmac.com/blocks/workorder-1","registryUrl":"https://ui.ballmac.com/r/workorder-1.json","install":"npx shadcn@latest add @ballmac/workorder-1","summary":"A repair work order. Promise} onAddLine={(line) => Promise} onMessage={({ id, text }) => Promise} />. Totals are computed from the lines. Advancing, adding a line and messaging each update the screen and the history.","whenToUse":["A repair shop, workshop or service desk's job page","Any job with steps, billable lines and customer updates"],"whenNotToUse":["A support ticket thread; use tickets-1","An invoice for sending; use invoice-1"],"composesWith":["dispatch-1","invoice-1","tickets-1","inventory-1"],"dependencies":["lucide-react"],"registryDependencies":["shadcn:utils","button","skeleton","state-view"],"examples":["workorder-1-demo","workorder-1-loading","workorder-1-empty","workorder-1-error"],"states":[{"id":"loading","title":"Loading","example":"workorder-1-loading","trigger":"state=\"loading\"","note":"Skeleton for the header, steps and totals under the page, announced as loading.","preview":"https://ui.ballmac.com/preview/workorder-1-loading"},{"id":"empty","title":"No work order selected","example":"workorder-1-empty","trigger":"state=\"empty\"","note":"Says no work order is selected; pass order={null} and emptyState sets the copy.","preview":"https://ui.ballmac.com/preview/workorder-1-empty"},{"id":"error","title":"Could not load","example":"workorder-1-error","trigger":"state=\"error\"","note":"An alert saying nothing was changed, with Try again (onRetry). A failed advance, line or message says why.","preview":"https://ui.ballmac.com/preview/workorder-1-error"}],"preview":"https://ui.ballmac.com/preview/workorder-1-demo"},{"name":"blur-fade","kind":"component","type":"registry:ui","title":"Blur Fade","description":"A wrapper that fades content in while it unblurs and slides a few pixels, once it scrolls into view, with a group that staggers its children.","category":"motion","tier":"free","tags":["fade","blur","reveal","scroll","stagger"],"version":"1.0.0","updated":"2026-10-01","url":"https://ui.ballmac.com/components/blur-fade","registryUrl":"https://ui.ballmac.com/r/blur-fade.json","install":"npx shadcn@latest add @ballmac/blur-fade","summary":"Wrap anything in . wraps each child and staggers them. Shows content instantly under reduced motion.","whenToUse":["Hero and section intros","Lists and cards that should arrive in sequence"],"whenNotToUse":["Text that should animate letter by letter (text-animate)","Content that must be visible without JavaScript before hydration"],"composesWith":["text-animate","bento-grid","card"],"dependencies":["motion@^12"],"registryDependencies":["shadcn:utils"],"examples":["blur-fade-demo","blur-fade-directions"],"states":[],"preview":"https://ui.ballmac.com/preview/blur-fade-demo"},{"name":"border-beam","kind":"component","type":"registry:ui","title":"Border Beam","description":"A short beam of light that travels around the inside edge of its parent's border at a constant speed. Decorative, token-colored, hidden under reduced motion.","category":"motion","tier":"free","tags":["border","glow","highlight","decorative","motion"],"version":"1.0.1","updated":"2026-10-11","url":"https://ui.ballmac.com/components/border-beam","registryUrl":"https://ui.ballmac.com/r/border-beam.json","install":"npx shadcn@latest add @ballmac/border-beam","summary":"Drop as the last child of any element with position: relative and a border radius; it inherits the radius and draws only in a borderWidth-thick ring (aria-hidden, pointer-events-none). Renders a span, so it is valid inside buttons.","whenToUse":["Drawing attention to one highlighted card, such as the recommended pricing plan","Marking a live or running state on a panel (an agent working, a deploy in progress)","A featured call-to-action button"],"whenNotToUse":["Several elements on the same screen; one beam per view","Communicating status on its own (pair it with text; it is hidden under reduced motion)"],"composesWith":["spotlight-card","button","magnetic-button"],"dependencies":["motion@^12"],"registryDependencies":["shadcn:utils","motion-presets"],"examples":["border-beam-demo","border-beam-button"],"states":[],"preview":"https://ui.ballmac.com/preview/border-beam-demo"},{"name":"breadcrumb","kind":"component","type":"registry:ui","title":"Breadcrumb","description":"A compact navigation trail with truncation, semantic current page, and visible keyboard focus.","category":"navigation","tier":"free","tags":["navigation","hierarchy","links"],"version":"1.0.0","updated":"2026-09-29","url":"https://ui.ballmac.com/components/breadcrumb","registryUrl":"https://ui.ballmac.com/r/breadcrumb.json","install":"npx shadcn@latest add @ballmac/breadcrumb","summary":"A compact navigation trail with truncation, semantic current page, and visible keyboard focus.","whenToUse":["Show a location inside a deep hierarchy","Provide a way back to parent sections"],"whenNotToUse":["Use tabs for switching peer views"],"composesWith":["pagination"],"dependencies":["lucide-react"],"registryDependencies":["shadcn:utils","i18n"],"examples":["breadcrumb-demo","breadcrumb-states"],"states":[],"preview":"https://ui.ballmac.com/preview/breadcrumb-demo"},{"name":"browser-frame","kind":"component","type":"registry:ui","title":"Browser Frame","description":"A Safari-style window with traffic lights, a padlocked address field and optional tabs. Children render as the page, either at natural size or laid out at desktop width and scaled to fit.","category":"devices","tier":"free","tags":["mockup","browser","safari","window","screenshot","website","hero"],"version":"1.0.0","updated":"2026-09-29","url":"https://ui.ballmac.com/components/browser-frame","registryUrl":"https://ui.ballmac.com/r/browser-frame.json","install":"npx shadcn@latest add @ballmac/browser-frame","summary":"Wrap web content in . Pass screenWidth={1280} (plus aspectRatio) to render a full desktop layout scaled down, tabs={[\"Home\", \"Docs\"]} for a tab strip, or src for a screenshot. Chrome colors follow the theme tokens.","whenToUse":["Showing a website or web app on a landing page or in docs","Template and theme galleries","Before/after comparisons of a web page"],"whenNotToUse":["Native desktop apps (use laptop-frame, or a plain window)","Mobile layouts (use phone-frame)"],"composesWith":["laptop-frame","phone-frame"],"dependencies":["lucide-react"],"registryDependencies":["shadcn:utils","i18n","media"],"examples":["browser-frame-demo","browser-frame-minimal"],"states":[],"preview":"https://ui.ballmac.com/preview/browser-frame-demo"},{"name":"bullet-chart","kind":"component","type":"registry:ui","title":"Bullet Chart","description":"Stephen Few's bullet chart: a bar for the value, a mark for the target, three shades behind for poor, fair and good, and a sentence saying whether the goal was met. Many measures in a small space, server-rendered.","category":"data-display","tier":"free","tags":["bullet chart","kpi","target","progress","gauge","chart","goals","okr"],"version":"1.0.0","updated":"2026-10-24","url":"https://ui.ballmac.com/components/bullet-chart","registryUrl":"https://ui.ballmac.com/r/bullet-chart.json","install":"npx shadcn@latest add @ballmac/bullet-chart","summary":"items is [{ id, label, value, target?, max?, ranges?: [poorEnd, fairEnd], note?, lowerIsBetter? }]. format(value). Each item reads as a meter and says Target met, Close to target (within 85%) or Behind target. No client code: it renders on the server.","whenToUse":["Comparing several measures to their goals in a small space","KPIs, SLAs and budgets where the target matters more than the trend"],"whenNotToUse":["A single value with no goal; use progress","A trend; use sparkline or chart-line","Proportions of a whole; use treemap or chart-pie"],"composesWith":["stat-card","kpi-row","slo-1","chart-frame"],"dependencies":["lucide-react"],"registryDependencies":["shadcn:utils","i18n"],"examples":["bullet-chart-demo","bullet-chart-lower"],"states":[],"statesNone":"A presentational chart: you pass the numbers in, so it has nothing of its own to load or fail.","preview":"https://ui.ballmac.com/preview/bullet-chart-demo"},{"name":"button-group","kind":"component","type":"registry:ui","title":"Button Group","description":"Join adjacent actions into one compact control surface while retaining each button's visible keyboard focus and accessible name.","category":"primitives","tier":"free","tags":["buttons","actions","toolbar"],"version":"1.0.0","updated":"2026-09-30","url":"https://ui.ballmac.com/components/button-group","registryUrl":"https://ui.ballmac.com/r/button-group.json","install":"npx shadcn@latest add @ballmac/button-group","summary":"Groups closely related actions without turning them into a selection widget.","whenToUse":["Adjacent document or editor actions","Compact controls with one shared boundary"],"whenNotToUse":["Mutually exclusive options; use toggle-group","Unrelated actions"],"composesWith":["button"],"dependencies":[],"registryDependencies":["shadcn:utils"],"examples":["button-group-demo","button-group-states"],"states":[],"preview":"https://ui.ballmac.com/preview/button-group-demo"},{"name":"button","kind":"component","type":"registry:ui","title":"Button","description":"A button with six variants, three sizes, a pill shape and a built-in loading state. buttonVariants() styles links the same way.","category":"primitives","tier":"free","tags":["button","cta","loading","radix"],"version":"1.0.4","updated":"2026-10-12","url":"https://ui.ballmac.com/components/button","registryUrl":"https://ui.ballmac.com/r/button.json","install":"npx shadcn@latest add @ballmac/button","summary":"The base action control. Use variant for emphasis, size for density, and loading while an async action runs.","whenToUse":["Primary and secondary actions","Form submit buttons","Links that should look like buttons (className={buttonVariants()} on an )"],"whenNotToUse":["Navigation inside running text (use a link)","Toggling state (use a switch or toggle)"],"composesWith":["kbd","tooltip"],"dependencies":["radix-ui","class-variance-authority"],"registryDependencies":["shadcn:utils"],"examples":["button-demo","button-variants","button-loading"],"states":[],"preview":"https://ui.ballmac.com/preview/button-demo"},{"name":"calendar-agenda","kind":"component","type":"registry:ui","title":"Calendar Agenda","description":"A day agenda with native date entry, adjacent-day controls, and accessible event times.","category":"data-display","tier":"free","tags":["calendar","agenda","events"],"version":"1.0.0","updated":"2026-09-30","url":"https://ui.ballmac.com/components/calendar-agenda","registryUrl":"https://ui.ballmac.com/r/calendar-agenda.json","install":"npx shadcn@latest add @ballmac/calendar-agenda","summary":"A day agenda with native date entry, adjacent-day controls, and accessible event times.","whenToUse":["Show scheduled events for one day"],"whenNotToUse":["Use a full calendar for month-level date picking"],"composesWith":["timeline"],"dependencies":["lucide-react"],"registryDependencies":["shadcn:utils","i18n"],"examples":["calendar-agenda-demo","calendar-agenda-states"],"states":[],"preview":"https://ui.ballmac.com/preview/calendar-agenda-demo"},{"name":"calendar","kind":"component","type":"registry:ui","title":"Calendar","description":"A date grid for one day, several days or a range, with month and year selects, week numbers, disabled rules and range-end styling, on React DayPicker.","category":"forms","tier":"free","tags":["date","calendar","range","day-picker"],"version":"1.0.1","updated":"2026-10-11","url":"https://ui.ballmac.com/components/calendar","registryUrl":"https://ui.ballmac.com/r/calendar.json","install":"npx shadcn@latest add @ballmac/calendar","summary":"Use mode single, multiple or range with selected and onSelect. All DayPicker props work: disabled, numberOfMonths, captionLayout dropdown, locale.","whenToUse":["Choosing a date or range inside a card or popover","Booking and scheduling","Showing availability with disabled days"],"whenNotToUse":["A date field in a form; use date-picker","Typing a range with inputs; use date-range-picker"],"composesWith":["popover","date-picker","button"],"dependencies":["react-day-picker@^9","lucide-react"],"registryDependencies":["shadcn:utils","direction"],"examples":["calendar-demo","calendar-states"],"states":[],"preview":"https://ui.ballmac.com/preview/calendar-demo"},{"name":"callout","kind":"component","type":"registry:ui","title":"Callout","description":"An editorial guidance panel with a clear kind label, icon, title, and optional action.","category":"feedback","tier":"free","tags":["guidance","tip","note"],"version":"1.0.0","updated":"2026-09-30","url":"https://ui.ballmac.com/components/callout","registryUrl":"https://ui.ballmac.com/r/callout.json","install":"npx shadcn@latest add @ballmac/callout","summary":"An editorial guidance panel with a clear kind label, icon, title, and optional action.","whenToUse":["Add contextual guidance to docs or settings","Explain a recommended next step"],"whenNotToUse":["Use alert for urgent system feedback"],"composesWith":["alert","button"],"dependencies":["lucide-react"],"registryDependencies":["shadcn:utils"],"examples":["callout-demo","callout-states"],"states":[],"preview":"https://ui.ballmac.com/preview/callout-demo"},{"name":"card","kind":"component","type":"registry:ui","title":"Card","description":"A composable content surface with compact spacing, an action slot, and optional interactive feedback.","category":"data-display","tier":"free","tags":["surface","panel","dashboard"],"version":"1.0.1","updated":"2026-10-11","url":"https://ui.ballmac.com/components/card","registryUrl":"https://ui.ballmac.com/r/card.json","install":"npx shadcn@latest add @ballmac/card","summary":"A composable content surface with compact spacing, an action slot, and optional interactive feedback.","whenToUse":["Group a related set of content and actions","Present a dashboard metric or settings panel"],"whenNotToUse":["Use an alert for status messages"],"composesWith":["button","badge"],"dependencies":[],"registryDependencies":["shadcn:utils"],"examples":["card-demo","card-states"],"states":[],"preview":"https://ui.ballmac.com/preview/card-demo"},{"name":"carousel","kind":"component","type":"registry:ui","title":"Carousel","description":"A swipeable, keyboard-operable carousel on Embla with slide labels, dot pagination, vertical mode, loop, and autoplay that pauses on hover, focus and reduced motion.","category":"data-display","tier":"free","tags":["slider","swipe","slides","embla"],"version":"1.0.0","updated":"2026-09-30","url":"https://ui.ballmac.com/components/carousel","registryUrl":"https://ui.ballmac.com/r/carousel.json","install":"npx shadcn@latest add @ballmac/carousel","summary":"Compose Carousel, CarouselContent and CarouselItem with CarouselPrevious, CarouselNext, CarouselDots and CarouselPlayPause. Give Carousel a label.","whenToUse":["Feature highlights and testimonials","Product image galleries","Horizontal lists that overflow"],"whenNotToUse":["Content people must read in full; show it all","A marquee of logos; use marquee"],"composesWith":["card","button"],"dependencies":["embla-carousel-react@^8","lucide-react"],"registryDependencies":["shadcn:utils","motion-presets","i18n","direction"],"examples":["carousel-demo","carousel-states"],"states":[],"preview":"https://ui.ballmac.com/preview/carousel-demo"},{"name":"changelog-feed","kind":"component","type":"registry:ui","title":"Changelog Feed","description":"A release-notes feed with a sticky date and version column, change-type labels, optional media, filter chips with counts and show-more for long releases.","category":"saas","tier":"free","tags":["changelog","release notes","updates","timeline"],"version":"1.0.0","updated":"2026-09-30","url":"https://ui.ballmac.com/components/changelog-feed","registryUrl":"https://ui.ballmac.com/r/changelog-feed.json","install":"npx shadcn@latest add @ballmac/changelog-feed","summary":"entries[] with {id,version,date (ISO),title,summary,changes:[{type,text}],media}. Types: new | improved | fixed | removed. Dates format in UTC.","whenToUse":["Product changelog pages","What's-new surfaces"],"whenNotToUse":["Activity of people on a record; use activity-feed","A single status message; use banner"],"composesWith":["timeline","activity-feed","badge"],"dependencies":["motion@^12","lucide-react"],"registryDependencies":["shadcn:utils","motion-presets","i18n"],"examples":["changelog-feed-demo","changelog-feed-states"],"states":[],"preview":"https://ui.ballmac.com/preview/changelog-feed-demo"},{"name":"chart-area","kind":"component","type":"registry:ui","title":"Chart Area","description":"An area chart with gradient, solid or no fill, stacked or expanded to 100%, four curves and reference lines, in a frame with a table view, a legend that toggles series, patterns for color blindness and loading, empty and error states.","category":"data-display","tier":"free","tags":["chart","area","line","stacked","trend","recharts","graph","timeseries"],"version":"1.0.0","updated":"2026-10-18","url":"https://ui.ballmac.com/components/chart-area","registryUrl":"https://ui.ballmac.com/r/chart-area.json","install":"npx shadcn@latest add @ballmac/chart-area","summary":". curve: monotone | linear | step | natural. stack: none | stacked | expanded (percent). fillMode: gradient | solid | none. Also dots, grid, yFormatter, yDomain, referenceLines, tooltip, legend, patterns, state and every ChartFrame prop. Colors come from the theme's chart colors in order.","whenToUse":["Trends over time, especially more than one series","Part-to-whole over time (stacked or expanded)"],"whenNotToUse":["Comparing a few categories (use chart-bar)","Exact values matter more than shape (use chart-line with dots or the table view)"],"composesWith":["chart-frame","segmented-control","stat-card"],"dependencies":["recharts@^3"],"registryDependencies":["shadcn:utils","chart","chart-frame"],"examples":["chart-area-demo","chart-area-stacked","chart-area-expanded","chart-area-step","chart-area-dots","chart-area-patterns","chart-area-target","chart-area-interactive","chart-area-states"],"states":[],"preview":"https://ui.ballmac.com/preview/chart-area-demo"},{"name":"chart-bar","kind":"component","type":"registry:ui","title":"Chart Bar","description":"A bar chart with upright columns or flat bars, grouped, stacked or expanded to 100%, value labels, one color per category, a highlight, negative coloring and sorting, in a frame with a table view, patterns and states.","category":"data-display","tier":"free","tags":["chart","bar","column","stacked","ranking","comparison","recharts","graph"],"version":"1.0.0","updated":"2026-10-18","url":"https://ui.ballmac.com/components/chart-bar","registryUrl":"https://ui.ballmac.com/r/chart-bar.json","install":"npx shadcn@latest add @ballmac/chart-bar","summary":". layout: columns | bars (flat, for long names). stack: none | stacked | expanded. Also labels, colorBy ('category' for one color per bar), highlight, negativeColor, sort, gap, valueAxis, axisFormatter, referenceLines, legend, patterns, state and every ChartFrame prop.","whenToUse":["Comparing values across categories","Rankings (layout='bars', sort='descending')","Parts of a whole across groups (stack)"],"whenNotToUse":["A trend over time with many points (use chart-area or chart-line)","A single share of a whole (use chart-pie or chart-radial)"],"composesWith":["chart-frame","stat-card","segmented-control"],"dependencies":["recharts@^3"],"registryDependencies":["shadcn:utils","chart","chart-frame","i18n"],"examples":["chart-bar-demo","chart-bar-horizontal","chart-bar-stacked","chart-bar-expanded","chart-bar-labels","chart-bar-categories","chart-bar-negative","chart-bar-ranked","chart-bar-patterns"],"states":[],"preview":"https://ui.ballmac.com/preview/chart-bar-demo"},{"name":"chart-frame","kind":"component","type":"registry:ui","title":"Chart Frame","description":"The card around a Recharts chart: a Table view with CSV download, a legend that toggles series, patterns so series differ by more than color, a summary for screen readers, and loading, empty and error states.","category":"data-display","tier":"free","tags":["chart","recharts","table","accessibility","legend","patterns","csv","states","graph"],"version":"1.0.0","updated":"2026-10-18","url":"https://ui.ballmac.com/components/chart-frame","registryUrl":"https://ui.ballmac.com/r/chart-frame.json","install":"npx shadcn@latest add @ballmac/chart-frame","summary":"Wrap any Recharts chart: {(chart) => …}. Use chart.color(key) for strokes, chart.fill(key) for fills, chart.isHidden(key) for `hide`, chart.defs in , chart.animate for isAnimationActive and chart.rtl to reverse the x axis. The frame adds a Chart/Table switch, a CSV download, a toggling legend, optional patterns, a written summary and state handling. Prefer the ready-made ChartArea, ChartBar, ChartLine, ChartPie, ChartRadar, ChartRadial or ChartScatter when one fits.","whenToUse":["Any chart that people need to read, compare or export","A custom Recharts chart that should be accessible and handle loading and errors"],"whenNotToUse":["A tiny inline trend (use sparkline)","A single ring value (use progress-ring)"],"composesWith":["chart","segmented-control","stat-card"],"dependencies":["motion@^12","lucide-react"],"registryDependencies":["shadcn:utils","chart","segmented-control","skeleton","state-view","toggle","direction","i18n"],"examples":["chart-frame-demo","chart-frame-loading","chart-frame-empty","chart-frame-error"],"states":[{"id":"loading","title":"Loading","example":"chart-frame-loading","trigger":"state=\"loading\"","note":"A skeleton in the shape of the chart (area, bars, donut, lines or radar), under the real title.","preview":"https://ui.ballmac.com/preview/chart-frame-loading"},{"id":"empty","title":"No data yet","example":"chart-frame-empty","trigger":"state=\"empty\" (or data={[]})","note":"Says when the chart will appear; emptyState sets the copy.","preview":"https://ui.ballmac.com/preview/chart-frame-empty"},{"id":"error","title":"Could not load","example":"chart-frame-error","trigger":"state=\"error\"","note":"An alert with Try again (onRetry).","preview":"https://ui.ballmac.com/preview/chart-frame-error"}],"preview":"https://ui.ballmac.com/preview/chart-frame-demo"},{"name":"chart-line","kind":"component","type":"registry:ui","title":"Chart Line","description":"A line chart with four curves, dots or value labels, dashed series, labels at the end of each line instead of a legend and gaps for missing data, in a frame with a table view, a toggling legend, patterns and states.","category":"data-display","tier":"free","tags":["chart","line","trend","timeseries","forecast","recharts","graph"],"version":"1.0.0","updated":"2026-10-18","url":"https://ui.ballmac.com/components/chart-line","registryUrl":"https://ui.ballmac.com/r/chart-line.json","install":"npx shadcn@latest add @ballmac/chart-line","summary":". curve: monotone | linear | step | natural. Also dots, dashed (series keys), directLabels (write names at the line ends and drop the legend), labels (values on points), gaps (null breaks the line), yFormatter, yDomain, referenceLines, legend, patterns, state and every ChartFrame prop.","whenToUse":["Trends where the exact path matters and fills would get in the way","Several series that cross (use directLabels)","Forecast against actual (dashed)"],"whenNotToUse":["Part-to-whole over time (use chart-area with stack)","Comparing a few categories (use chart-bar)"],"composesWith":["chart-frame","stat-card","segmented-control"],"dependencies":["recharts@^3"],"registryDependencies":["chart","chart-frame"],"examples":["chart-line-demo","chart-line-dots","chart-line-dashed","chart-line-direct","chart-line-labels","chart-line-step","chart-line-gaps","chart-line-compare"],"states":[],"preview":"https://ui.ballmac.com/preview/chart-line-demo"},{"name":"chart-pie","kind":"component","type":"registry:ui","title":"Chart Pie","description":"A pie or donut with the total in the hole, outside labels, a pulled-out slice and a half ring, in a frame with a legend that switches slices off, a table of value and share, a written ranking, patterns and states.","category":"data-display","tier":"free","tags":["chart","pie","donut","share","proportion","gauge","recharts","graph"],"version":"1.0.0","updated":"2026-10-18","url":"https://ui.ballmac.com/components/chart-pie","registryUrl":"https://ui.ballmac.com/r/chart-pie.json","install":"npx shadcn@latest add @ballmac/chart-pie","summary":". donut (default) or donut={false}; half for a semicircle; centerLabel (true writes the total; or { value, label }); labels='outside'; highlight (a slice name); gap; legend; patterns; state. The legend switches slices off and the total and shares follow. Slices are rows, not series.","whenToUse":["A few parts of one whole (up to about six)","A goal or quota ring (two slices, custom centerLabel)"],"whenNotToUse":["More than six categories or exact comparison (use chart-bar with layout='bars')","Change over time (use chart-area or chart-line)"],"composesWith":["chart-frame","stat-card"],"dependencies":["recharts@^3"],"registryDependencies":["chart","chart-frame","i18n"],"examples":["chart-pie-demo","chart-pie-full","chart-pie-half","chart-pie-highlight","chart-pie-patterns","chart-pie-center"],"states":[],"preview":"https://ui.ballmac.com/preview/chart-pie-demo"},{"name":"chart-radar","kind":"component","type":"registry:ui","title":"Chart Radar","description":"A radar chart with filled or outlined shapes, polygon or circular rings, dots and a fixed scale, in a frame with a legend that switches series off, a table of every axis, patterns and states.","category":"data-display","tier":"free","tags":["chart","radar","spider","comparison","scorecard","recharts","graph"],"version":"1.0.0","updated":"2026-10-18","url":"https://ui.ballmac.com/components/chart-radar","registryUrl":"https://ui.ballmac.com/r/chart-radar.json","install":"npx shadcn@latest add @ballmac/chart-radar","summary":". fillShape (false draws outlines), dots, grid: polygon | circle | none, domain ([0, 100]), scale (write the scale), legend, patterns, state and every ChartFrame prop.","whenToUse":["Comparing a few things across the same 5 to 8 dimensions","Scorecards and profiles"],"whenNotToUse":["Precise comparison of values (use chart-bar)","More than three or four overlapping series"],"composesWith":["chart-frame","stat-card"],"dependencies":["recharts@^3"],"registryDependencies":["chart","chart-frame"],"examples":["chart-radar-demo","chart-radar-compare","chart-radar-circle","chart-radar-patterns"],"states":[],"preview":"https://ui.ballmac.com/preview/chart-radar-demo"},{"name":"chart-radial","kind":"component","type":"registry:ui","title":"Chart Radial","description":"Radial bars: one ring is a gauge, several are concentric progress rings. Full or half circle, a track, text in the middle, in a frame with a table, patterns and states.","category":"data-display","tier":"free","tags":["chart","radial","gauge","ring","progress","goal","recharts","graph"],"version":"1.0.0","updated":"2026-10-18","url":"https://ui.ballmac.com/components/chart-radial","registryUrl":"https://ui.ballmac.com/r/chart-radial.json","install":"npx shadcn@latest add @ballmac/chart-radial","summary":". One row is a gauge, several rows are concentric rings. half for a semicircle, centerLabel (true writes the first ring's share, or { value, label }), track, valueLabel, legend, patterns, state.","whenToUse":["Progress toward a goal","A single metric against its maximum","Activity or goal rings"],"whenNotToUse":["Parts of a whole (use chart-pie)","Comparing many categories (use chart-bar)"],"composesWith":["chart-frame","stat-card","progress-ring"],"dependencies":["recharts@^3"],"registryDependencies":["chart","chart-frame","i18n"],"examples":["chart-radial-demo","chart-radial-rings","chart-radial-half","chart-radial-patterns"],"states":[],"preview":"https://ui.ballmac.com/preview/chart-radial-demo"},{"name":"chart-scatter","kind":"component","type":"registry:ui","title":"Chart Scatter","description":"A scatter or bubble chart with grouped colors, point sizes from a third number and titled axes, in a frame with a toggling legend, a table of every point with CSV download, and states.","category":"data-display","tier":"free","tags":["chart","scatter","bubble","correlation","distribution","recharts","graph"],"version":"1.0.0","updated":"2026-10-18","url":"https://ui.ballmac.com/components/chart-scatter","registryUrl":"https://ui.ballmac.com/r/chart-scatter.json","install":"npx shadcn@latest add @ballmac/chart-scatter","summary":" with optional zKey (point size), groupKey plus groups ([{ key, label, color? }]), nameKey, xDomain, yDomain, sizeRange, formatters, legend, patterns, state. Every row is one point.","whenToUse":["Relationships between two numbers","Distributions and outliers","Bubble charts with a third measure"],"whenNotToUse":["Trends over time (use chart-line)","Categories with one value each (use chart-bar)"],"composesWith":["chart-frame"],"dependencies":["recharts@^3"],"registryDependencies":["chart","chart-frame","i18n"],"examples":["chart-scatter-demo","chart-scatter-groups","chart-scatter-bubble"],"states":[],"preview":"https://ui.ballmac.com/preview/chart-scatter-demo"},{"name":"chart","kind":"component","type":"registry:ui","title":"Chart","description":"Theme-aware chart wrapper for Recharts with token colors, a styled tooltip and legend, a named figure with a screen-reader summary, and keyboard navigation.","category":"data-display","tier":"free","tags":["chart","recharts","graph","data"],"version":"1.1.0","updated":"2026-10-18","url":"https://ui.ballmac.com/components/chart","registryUrl":"https://ui.ballmac.com/r/chart.json","install":"npx shadcn@latest add @ballmac/chart","summary":"Wrap any Recharts chart in ChartContainer with a config of label and color per series. Use ChartTooltipContent and ChartLegendContent. Always pass label and summary.","whenToUse":["Dashboards and reports","Trends, comparisons and proportions"],"whenNotToUse":["A tiny inline trend; use sparkline","A single ring value; use progress-ring"],"composesWith":["card","stat-card"],"dependencies":["recharts@^3"],"registryDependencies":["shadcn:utils","i18n"],"examples":["chart-demo","chart-bars","chart-donut"],"states":[],"preview":"https://ui.ballmac.com/preview/chart-demo"},{"name":"chat-attachment","kind":"component","type":"registry:ui","title":"Chat Attachment","description":"File chips and image tiles for composers and messages, with type detection, sizes, upload progress, failed-upload retry, remove and open actions, and animated list changes.","category":"ai","tier":"free","tags":["ai","chat","attachment","file","upload","image"],"version":"1.0.0","updated":"2026-09-30","url":"https://ui.ballmac.com/components/chat-attachment","registryUrl":"https://ui.ballmac.com/r/chat-attachment.json","install":"npx shadcn@latest add @ballmac/chat-attachment","summary":" holds . Kind and icon come from the MIME type or extension. Also exports formatFileSize and attachmentKind.","whenToUse":["Files staged in a prompt input before sending","Attachments shown inside a sent message"],"whenNotToUse":["A drag and drop upload area","Generic file tables"],"composesWith":["prompt-input","ai-message"],"dependencies":["motion@^12","lucide-react"],"registryDependencies":["shadcn:utils","i18n"],"examples":["chat-attachment-demo","chat-attachment-tiles"],"states":[],"preview":"https://ui.ballmac.com/preview/chat-attachment-demo"},{"name":"checkbox","kind":"component","type":"registry:ui","title":"Checkbox","description":"A Radix checkbox with checked and indeterminate (mixed) states, a check or minus icon, focus ring and invalid styling, for forms and select-all lists.","category":"primitives","tier":"free","tags":["checkbox","form","indeterminate","radix"],"version":"1.0.1","updated":"2026-10-11","url":"https://ui.ballmac.com/components/checkbox","registryUrl":"https://ui.ballmac.com/r/checkbox.json","install":"npx shadcn@latest add @ballmac/checkbox","summary":"Binary or tri-state choice. Pass checked=\"indeterminate\" for a parent row whose children are partly selected; aria-checked becomes \"mixed\". Pair with Label via id/htmlFor.","whenToUse":["Agreeing to terms or opting into emails","Multi-select lists and table row selection","A select-all control that reflects partial selection"],"whenNotToUse":["Settings that apply immediately (use switch)","Choosing exactly one option from several (use a radio group or select)"],"composesWith":["label","button"],"dependencies":["radix-ui","lucide-react"],"registryDependencies":["shadcn:utils"],"examples":["checkbox-demo","checkbox-indeterminate"],"states":[],"preview":"https://ui.ballmac.com/preview/checkbox-demo"},{"name":"circular-progress","kind":"component","type":"registry:ui","title":"Circular Progress","description":"Concentric progress rings or a 270 degree gauge in theme colors with animated fills, a legend with values and a center slot, for goals, quotas and activity summaries.","category":"data-display","tier":"free","tags":["progress","rings","gauge","activity","chart"],"version":"1.0.0","updated":"2026-10-01","url":"https://ui.ballmac.com/components/circular-progress","registryUrl":"https://ui.ballmac.com/r/circular-progress.json","install":"npx shadcn@latest add @ballmac/circular-progress","summary":"center. One ring is role=meter; several are a named group whose value text lists every ring. sweep=270 makes a gauge.","whenToUse":["Daily goals and multi-metric summaries","Storage, quota or score gauges"],"whenNotToUse":["A single small ring in a table (progress-ring)","Time series (chart)"],"composesWith":["progress-ring","usage-meter","stat-card"],"dependencies":["motion@^12"],"registryDependencies":["shadcn:utils"],"examples":["circular-progress-demo","circular-progress-gauge"],"states":[],"preview":"https://ui.ballmac.com/preview/circular-progress-demo"},{"name":"citation-coverage","kind":"component","type":"registry:ui","title":"Citation Coverage","description":"An AI answer shown claim by claim: a coverage meter, claims with no source underlined and marked in words, numbered source markers, selecting a claim to light up its sources and quote, and a switch to see only the gaps.","category":"ai","tier":"free","tags":["ai","citations","sources","rag","grounding","trust","verification"],"version":"1.0.0","updated":"2026-10-24","url":"https://ui.ballmac.com/components/citation-coverage","registryUrl":"https://ui.ballmac.com/r/citation-coverage.json","install":"npx shadcn@latest add @ballmac/citation-coverage","summary":"claims is [{ id, text, sources: number[] }] in reading order (empty sources means unsupported); sources is [{ id, title, url?, quote? }]. selected / defaultSelected / onSelectedChange pick a claim. Computes the coverage percentage itself.","whenToUse":["Showing people how much of an AI answer is grounded in sources","A review screen where unsupported claims need checking"],"whenNotToUse":["Plain inline citations in a chat message; use citation and sources-list","A list of documents only; use sources-list"],"composesWith":["citation","sources-list","ai-message","streaming-text"],"dependencies":["lucide-react"],"registryDependencies":["shadcn:utils","i18n"],"examples":["citation-coverage-demo","citation-coverage-full"],"states":[],"statesNone":"A presentational review: the claims and sources are passed in, so it has nothing of its own to load or fail.","preview":"https://ui.ballmac.com/preview/citation-coverage-demo"},{"name":"citation","kind":"component","type":"registry:ui","title":"Citation","description":"An inline source marker for AI answers, as a numbered chip or a site pill. Hover or focus opens a preview card with title, excerpt and link, and a pager when one claim has several sources.","category":"ai","tier":"free","tags":["ai","citation","source","reference","hover"],"version":"1.0.0","updated":"2026-09-30","url":"https://ui.ballmac.com/components/citation","registryUrl":"https://ui.ballmac.com/r/citation.json","install":"npx shadcn@latest add @ballmac/citation","summary":"Place right after the claim. Pass an array for several sources. variant is number | pill. The marker is a real link, so touch users open the page directly. Also exports SourceFavicon and hostOf.","whenToUse":["Answers grounded in web or document sources","Footnotes that should not pull the reader away from the text"],"whenNotToUse":["A full list of references; use sources-list","Tooltips with no link; use tooltip"],"composesWith":["sources-list","ai-message","hover-card"],"dependencies":["lucide-react"],"registryDependencies":["shadcn:utils","hover-card","i18n"],"examples":["citation-demo","citation-pill"],"states":[],"preview":"https://ui.ballmac.com/preview/citation-demo"},{"name":"code-block","kind":"component","type":"registry:ui","title":"Code Block","description":"A code panel with filename and language header, line numbers, highlighted lines, a wrap toggle, copy feedback and file tabs. No highlighter bundled; pass Shiki output as children.","category":"developer","tier":"free","tags":["code","snippet","syntax","copy","shiki","tabs","developer","docs"],"version":"1.1.0","updated":"2026-10-19","url":"https://ui.ballmac.com/components/code-block","registryUrl":"https://ui.ballmac.com/r/code-block.json","install":"npx shadcn@latest add @ballmac/code-block","summary":"Two ways to use it. Ready-made: renders plain monospace text. Compound (the same API as shadcn's Code Block, so chat kits and agent output drop in): , with useHighlightedCode(code, language) giving one node per line. For syntax colors, highlight on the server (e.g. Shiki) and pass the result as children plus the raw code for copying. shows several files.","whenToUse":["Code samples in docs, READMEs rendered on the web and blog posts","Showing a changed file with specific lines highlighted","Several related files (component, usage, config) in one panel with tabs"],"whenNotToUse":["One-line install commands for several package managers (use install-tabs)","Terminal sessions with prompts and output (use terminal)","Editable code (use a code editor)"],"composesWith":["install-tabs","terminal","ai-message"],"dependencies":["lucide-react","radix-ui"],"registryDependencies":["shadcn:utils","i18n","highlight"],"examples":["code-block-demo","code-block-tabs","code-block-compound","code-block-highlighted","code-block-diff","code-block-floating","code-block-show-more","code-block-tool-output"],"states":[],"preview":"https://ui.ballmac.com/preview/code-block-demo"},{"name":"collapsible","kind":"component","type":"registry:ui","title":"Collapsible","description":"A single disclosure panel with a generous trigger, visible open state, and reduced-motion-aware content transition.","category":"primitives","tier":"free","tags":["disclosure","details","radix"],"version":"1.0.0","updated":"2026-09-30","url":"https://ui.ballmac.com/components/collapsible","registryUrl":"https://ui.ballmac.com/r/collapsible.json","install":"npx shadcn@latest add @ballmac/collapsible","summary":"Reveals one optional section of information with a keyboard-accessible disclosure trigger.","whenToUse":["Advanced settings","Supporting detail in a dense card"],"whenNotToUse":["Several related disclosures; use accordion","Primary content that should always be visible"],"composesWith":["card"],"dependencies":["radix-ui","lucide-react"],"registryDependencies":["shadcn:utils"],"examples":["collapsible-demo","collapsible-states"],"states":[],"preview":"https://ui.ballmac.com/preview/collapsible-demo"},{"name":"color-picker","kind":"component","type":"registry:ui","title":"Color Picker","description":"A native color chooser paired with an editable hex field and a live swatch.","category":"forms","tier":"free","tags":["color","picker","hex"],"version":"1.0.0","updated":"2026-09-30","url":"https://ui.ballmac.com/components/color-picker","registryUrl":"https://ui.ballmac.com/r/color-picker.json","install":"npx shadcn@latest add @ballmac/color-picker","summary":"A native color chooser paired with an editable hex field and a live swatch.","whenToUse":["Choose a custom brand or annotation color","Edit a color precisely by hexadecimal value"],"whenNotToUse":["Use theme tokens for application chrome"],"composesWith":["input"],"dependencies":[],"registryDependencies":["shadcn:utils","i18n"],"examples":["color-picker-demo","color-picker-states"],"states":[],"preview":"https://ui.ballmac.com/preview/color-picker-demo"},{"name":"combobox","kind":"component","type":"registry:ui","title":"Combobox","description":"A searchable single-choice select with groups, descriptions, keywords, clearable value, invalid state and hidden-input form submission.","category":"forms","tier":"free","tags":["select","search","autocomplete","form"],"version":"1.0.0","updated":"2026-09-30","url":"https://ui.ballmac.com/components/combobox","registryUrl":"https://ui.ballmac.com/r/combobox.json","install":"npx shadcn@latest add @ballmac/combobox","summary":"Pass options with value and label. It opens a filterable list; the trigger is a combobox button that submits through name.","whenToUse":["Choosing from more than about seven options","Time zones, countries, users and frameworks"],"whenNotToUse":["Short lists; use select or radio-group","Choosing several values; use multi-select"],"composesWith":["field","command","popover"],"dependencies":["lucide-react"],"registryDependencies":["shadcn:utils","command","popover","i18n"],"examples":["combobox-demo","combobox-states"],"states":[],"preview":"https://ui.ballmac.com/preview/combobox-demo"},{"name":"command-bar","kind":"component","type":"registry:ui","title":"Command Bar","description":"A command palette with pages: a search-field style trigger, grouped commands, drill-in pages with a breadcrumb, Backspace to go back and a footer of key hints.","category":"navigation","tier":"free","tags":["command palette","search","pages","keyboard"],"version":"1.0.0","updated":"2026-09-30","url":"https://ui.ballmac.com/components/command-bar","registryUrl":"https://ui.ballmac.com/r/command-bar.json","install":"npx shadcn@latest add @ballmac/command-bar","summary":"groups: {heading, items:[{id,label,icon,shortcut,keywords,onSelect,pages}]}. An item with pages opens a second page. hotkey toggles with Cmd/Ctrl; trigger={false} hides the button.","whenToUse":["Global quick actions and navigation","Apps with many commands and sub-choices"],"whenNotToUse":["A macOS-style launcher; use spotlight-search","Choosing one value in a form; use combobox"],"composesWith":["command","kbd","dialog"],"dependencies":["lucide-react"],"registryDependencies":["shadcn:utils","command","kbd","i18n"],"examples":["command-bar-demo","command-bar-states"],"states":[],"preview":"https://ui.ballmac.com/preview/command-bar-demo"},{"name":"command","kind":"component","type":"registry:ui","title":"Command","description":"A filterable command list on cmdk, inline or in a Cmd/Ctrl+K dialog, with groups, shortcuts, descriptions, loading state and page-safe scrolling.","category":"navigation","tier":"free","tags":["command palette","search","cmdk","keyboard"],"version":"1.0.1","updated":"2026-10-11","url":"https://ui.ballmac.com/components/command","registryUrl":"https://ui.ballmac.com/r/command.json","install":"npx shadcn@latest add @ballmac/command","summary":"Compose Command, CommandInput, CommandList, CommandGroup and CommandItem. CommandDialog adds the modal and the ⌘K hotkey.","whenToUse":["Command palettes and quick switchers","Searchable action lists","The list inside a combobox"],"whenNotToUse":["macOS-style launcher visuals; use spotlight-search","A simple select; use select"],"composesWith":["popover","dialog","kbd"],"dependencies":["cmdk@^1","radix-ui","lucide-react"],"registryDependencies":["shadcn:utils","i18n"],"examples":["command-demo","command-dialog"],"states":[],"preview":"https://ui.ballmac.com/preview/command-demo"},{"name":"comparison-table","kind":"component","type":"registry:ui","title":"Comparison Table","description":"A semantic feature matrix with a highlighted choice and accessible boolean values.","category":"data-display","tier":"free","tags":["comparison","pricing","features"],"version":"1.0.0","updated":"2026-09-30","url":"https://ui.ballmac.com/components/comparison-table","registryUrl":"https://ui.ballmac.com/r/comparison-table.json","install":"npx shadcn@latest add @ballmac/comparison-table","summary":"A semantic feature matrix with a highlighted choice and accessible boolean values.","whenToUse":["Compare capabilities across choices"],"whenNotToUse":["Use Description List for one object"],"composesWith":["description-list"],"dependencies":["lucide-react"],"registryDependencies":["shadcn:utils","i18n"],"examples":["comparison-table-demo","comparison-table-states"],"states":[],"preview":"https://ui.ballmac.com/preview/comparison-table-demo"},{"name":"confetti","kind":"component","type":"registry:ui","title":"Confetti","description":"Confetti in your theme colors: fireConfetti(), a useConfetti() hook that fires from an element, and a ConfettiButton. Presets for burst, side cannons, stars and fireworks; nothing fires under reduced motion.","category":"motion","tier":"free","tags":["confetti","celebration","success","canvas","button","motion"],"version":"1.0.0","updated":"2026-09-29","url":"https://ui.ballmac.com/components/confetti","registryUrl":"https://ui.ballmac.com/r/confetti.json","install":"npx shadcn@latest add @ballmac/confetti","summary":"Call fireConfetti({ preset, colors, element }) from an event handler, or useConfetti().fireFrom(buttonRef.current) after an async success. is a Ballmac button that bursts from itself on click. Colors default to --chart-1…5.","whenToUse":["Rewarding a finished milestone: first deploy, upgrade, completed onboarding","Success states after a long async action","Playful marketing buttons (sparingly)"],"whenNotToUse":["Routine actions such as saving a form (use a toast or inline check)","As the only success signal; always show a text confirmation too"],"composesWith":["button","number-ticker"],"dependencies":["canvas-confetti@^1.9.3","class-variance-authority"],"registryDependencies":["shadcn:utils","button","color"],"examples":["confetti-demo","confetti-presets"],"states":[],"preview":"https://ui.ballmac.com/preview/confetti-demo"},{"name":"container-scroll","kind":"component","type":"registry:ui","title":"Container Scroll","description":"A showcase frame that starts tilted back in 3D and flattens to face the reader as it scrolls into view, with a title that lifts alongside.","category":"layout","tier":"free","tags":["3d","scroll","hero","showcase"],"version":"1.0.0","updated":"2026-09-30","url":"https://ui.ballmac.com/components/container-scroll","registryUrl":"https://ui.ballmac.com/r/container-scroll.json","install":"npx shadcn@latest add @ballmac/container-scroll","summary":"{screenshot or live demo}. tilt sets the starting angle; container tracks a scrollable element.","whenToUse":["Product hero sections","Showing a dashboard or app screenshot"],"whenNotToUse":["Content that must stay flat and readable at all times","Pages that scroll inside nested containers without passing container"],"composesWith":["browser-frame","sticky-scroll","bento-grid"],"dependencies":["motion@^12"],"registryDependencies":["shadcn:utils"],"examples":["container-scroll-demo","container-scroll-states"],"states":[],"preview":"https://ui.ballmac.com/preview/container-scroll-demo"},{"name":"context-menu","kind":"component","type":"registry:ui","title":"Context Menu","description":"A right-click, long-press and Shift+F10 menu with submenus, checkbox and radio items, shortcut hints and a destructive style, built on Radix.","category":"primitives","tier":"free","tags":["menu","right-click","overlay","radix"],"version":"1.0.1","updated":"2026-10-11","url":"https://ui.ballmac.com/components/context-menu","registryUrl":"https://ui.ballmac.com/r/context-menu.json","install":"npx shadcn@latest add @ballmac/context-menu","summary":"Shows actions at the pointer on right-click or long-press. Keyboard users open it with Shift+F10 or the Menu key on a focusable trigger.","whenToUse":["File, card and canvas actions","Secondary actions that also exist elsewhere","Desktop-style apps"],"whenNotToUse":["The only way to reach an action; menus must be discoverable, so also offer a dropdown-menu button","Touch-first layouts without a visible trigger"],"composesWith":["dropdown-menu","card"],"dependencies":["radix-ui","lucide-react"],"registryDependencies":["shadcn:utils","direction"],"examples":["context-menu-demo","context-menu-states"],"states":[],"preview":"https://ui.ballmac.com/preview/context-menu-demo"},{"name":"contribution-graph","kind":"component","type":"registry:ui","title":"Contribution Graph","description":"A compact daily activity heatmap with token-based intensity and an accessible summary.","category":"data-display","tier":"free","tags":["heatmap","activity","calendar"],"version":"1.0.0","updated":"2026-09-30","url":"https://ui.ballmac.com/components/contribution-graph","registryUrl":"https://ui.ballmac.com/r/contribution-graph.json","install":"npx shadcn@latest add @ballmac/contribution-graph","summary":"A compact daily activity heatmap with token-based intensity and an accessible summary.","whenToUse":["Show a daily activity pattern over time"],"whenNotToUse":["Use a calendar when dates need interaction"],"composesWith":["activity-feed"],"dependencies":[],"registryDependencies":["shadcn:utils","i18n"],"examples":["contribution-graph-demo","contribution-graph-states"],"states":[],"preview":"https://ui.ballmac.com/preview/contribution-graph-demo"},{"name":"control-center","kind":"component","type":"registry:ui","title":"Control Center","description":"The macOS Control Center panel in frosted glass: toggle tiles with round badges, grouped Wi-Fi, Bluetooth and AirDrop rows, pill sliders with the icon in the track, and a Now Playing tile. Real toggle buttons and Radix sliders.","category":"macos","tier":"free","tags":["control-center","macos","toggles","slider","settings","panel","media"],"version":"1.0.1","updated":"2026-10-11","url":"https://ui.ballmac.com/components/control-center","registryUrl":"https://ui.ballmac.com/r/control-center.json","install":"npx shadcn@latest add @ballmac/control-center","summary":" is a 2-column grid. Put with toggles first, then , and . Toggles are controlled with pressed / onPressedChange or uncontrolled.","whenToUse":["Mac system UI mockups","Quick-settings popovers"],"whenNotToUse":["Full settings pages (use field, switch, slider)"],"composesWith":["menu-bar","mac-window","hud","switch"],"dependencies":["radix-ui","lucide-react"],"registryDependencies":["shadcn:utils","i18n","media","media-image"],"examples":["control-center-demo","control-center-compact"],"states":[],"preview":"https://ui.ballmac.com/preview/control-center-demo"},{"name":"cookie-consent","kind":"component","type":"registry:ui","title":"Cookie Consent","description":"A privacy banner with equal-weight Accept all and Reject non-essential, plus a preferences view with a switch per category and locked required ones.","category":"saas","tier":"free","tags":["privacy","cookies","consent","gdpr"],"version":"1.0.0","updated":"2026-09-30","url":"https://ui.ballmac.com/components/cookie-consent","registryUrl":"https://ui.ballmac.com/r/cookie-consent.json","install":"npx shadcn@latest add @ballmac/cookie-consent","summary":"categories[] with {id,label,description,required}. onConsent receives a map of category to boolean. storageKey saves and remembers the choice in localStorage.","whenToUse":["Sites that set non-essential cookies","Consent prompts for analytics and marketing"],"whenNotToUse":["Legal advice: check your own requirements","Unrelated notices; use banner"],"composesWith":["banner","switch","dialog"],"dependencies":["motion@^12","lucide-react"],"registryDependencies":["shadcn:utils","motion-presets","i18n"],"examples":["cookie-consent-demo","cookie-consent-states"],"states":[],"preview":"https://ui.ballmac.com/preview/cookie-consent-demo"},{"name":"copy-button","kind":"component","type":"registry:ui","title":"Copy Button","description":"A copy-to-clipboard button with a morphing check icon, an optional label, a fallback for blocked clipboards, an error state and a polite announcement.","category":"developer","tier":"free","tags":["copy","clipboard","button","developer"],"version":"1.0.0","updated":"2026-10-01","url":"https://ui.ballmac.com/components/copy-button","registryUrl":"https://ui.ballmac.com/r/copy-button.json","install":"npx shadcn@latest add @ballmac/copy-button","summary":"Pass value (or getValue for content read at click time). label adds visible text, variant is ghost | outline | solid, size sm | default | lg. Falls back to execCommand when navigator.clipboard is blocked and shows 'Copy failed' if both fail.","whenToUse":["Any value a developer will paste: keys, URLs, commands, IDs","Toolbars on code, logs and config"],"whenNotToUse":["Copying a whole code block with a header (code-block has its own button)"],"composesWith":["code-block","api-key-field","terminal"],"dependencies":["motion@^12","lucide-react","class-variance-authority"],"registryDependencies":["shadcn:utils","i18n"],"examples":["copy-button-demo","copy-button-inline"],"states":[],"preview":"https://ui.ballmac.com/preview/copy-button-demo"},{"name":"countdown","kind":"component","type":"registry:ui","title":"Countdown","description":"An SSR-safe timer with controlled or local seconds, pause support, and a completion announcement.","category":"feedback","tier":"free","tags":["timer","countdown","time"],"version":"1.0.0","updated":"2026-09-30","url":"https://ui.ballmac.com/components/countdown","registryUrl":"https://ui.ballmac.com/r/countdown.json","install":"npx shadcn@latest add @ballmac/countdown","summary":"An SSR-safe timer with controlled or local seconds, pause support, and a completion announcement.","whenToUse":["Show time until a short event","Display a temporary offer or session limit"],"whenNotToUse":["Use progress for work completion"],"composesWith":["progress-ring"],"dependencies":[],"registryDependencies":["shadcn:utils","i18n"],"examples":["countdown-demo","countdown-states"],"states":[],"preview":"https://ui.ballmac.com/preview/countdown-demo"},{"name":"cover-art","kind":"component","type":"registry:ui","title":"Cover Art","description":"Cover pictures drawn from a seed in your theme's chart colors: color fields, rings, bars, dots or waves. The same seed always draws the same picture, so an item without an image still looks finished.","category":"backgrounds","tier":"free","tags":["cover","artwork","generative","placeholder","avatar","thumbnail","gradient","seed"],"version":"1.0.0","updated":"2026-10-17","url":"https://ui.ballmac.com/components/cover-art","registryUrl":"https://ui.ballmac.com/r/cover-art.json","install":"npx shadcn@latest add @ballmac/cover-art","summary":" fills its parent with a picture chosen and drawn from the seed; variant: 'mesh' | 'rings' | 'bars' | 'dots' | 'waves' | 'auto'; grid adds a faint grid. Put it in a sized container (an aspect-video div, a size-10 rounded avatar). It is decorative and hidden from screen readers, so keep the item's name as text next to it.","whenToUse":["The fallback for a card, channel, project or agent that has no image","A profile cover or a thumbnail while images load"],"whenNotToUse":["A real photograph or logo (use media)","An animated hero background (use aurora-background or beams-background)"],"composesWith":["media","card","avatar"],"dependencies":[],"registryDependencies":["shadcn:utils"],"examples":["cover-art-demo","cover-art-seeds"],"states":[],"preview":"https://ui.ballmac.com/preview/cover-art-demo"},{"name":"currency-input","kind":"component","type":"registry:ui","title":"Currency Input","description":"A locale-aware money field that formats on blur while keeping editing and caret behavior simple.","category":"forms","tier":"free","tags":["currency","money","input"],"version":"1.0.0","updated":"2026-09-30","url":"https://ui.ballmac.com/components/currency-input","registryUrl":"https://ui.ballmac.com/r/currency-input.json","install":"npx shadcn@latest add @ballmac/currency-input","summary":"A locale-aware money field that formats on blur while keeping editing and caret behavior simple.","whenToUse":["Collect prices, budgets, or payment amounts"],"whenNotToUse":["Use Number Input for unitless quantities"],"composesWith":["number-input"],"dependencies":[],"registryDependencies":["shadcn:utils","i18n"],"examples":["currency-input-demo","currency-input-states"],"states":[],"preview":"https://ui.ballmac.com/preview/currency-input-demo"},{"name":"data-grid","kind":"component","type":"registry:ui","title":"Data Grid","description":"A spreadsheet-style grid for thousands of rows: only visible rows are drawn, cells edit in place, headings sort and resize, columns pin, and it follows the ARIA grid keyboard pattern with undo and paste.","category":"data-display","tier":"free","tags":["grid","table","spreadsheet","virtualized","editable","sorting","keyboard"],"version":"1.0.0","updated":"2026-10-19","url":"https://ui.ballmac.com/components/data-grid","registryUrl":"https://ui.ballmac.com/r/data-grid.json","install":"npx shadcn@latest add @ballmac/data-grid","summary":"Pass columns ({ id, header, accessorKey, type: text | number | boolean | select | date, editable, width, pin }) and rows with data or defaultData. Set height; rows outside it are not drawn. Listen with onDataChange or onCellChange.","whenToUse":["Hundreds to tens of thousands of rows people edit like a spreadsheet","Admin tools, inventories, budgets and review queues with keyboard-heavy users","Wide data that needs pinned columns and resizable headings"],"whenNotToUse":["A small read-only table; use table","Search, filters, column menus and pagination out of the box; use data-table","Formulas, merged cells or multi-sheet workbooks"],"composesWith":["data-table","badge","state-view"],"dependencies":["lucide-react"],"registryDependencies":["shadcn:utils","badge","checkbox","skeleton","state-view","i18n","direction"],"examples":["data-grid-demo","data-grid-virtualized","data-grid-pinned","data-grid-validation","data-grid-controlled","data-grid-loading","data-grid-empty","data-grid-error"],"states":[{"id":"loading","title":"Loading","example":"data-grid-loading","trigger":"state=\"loading\"","note":"Header and rows drawn as skeletons in the same columns, announced as loading; nothing can be edited.","preview":"https://ui.ballmac.com/preview/data-grid-loading"},{"id":"empty","title":"No rows","example":"data-grid-empty","trigger":"state=\"empty\" or data={[]}","note":"A clear message that there are no rows yet; emptyState sets the copy and can add an action. A search with no match says so inside the grid.","preview":"https://ui.ballmac.com/preview/data-grid-empty"},{"id":"error","title":"Could not load","example":"data-grid-error","trigger":"state=\"error\"","note":"An error with a Try again button (onRetry), announced as an alert.","preview":"https://ui.ballmac.com/preview/data-grid-error"}],"preview":"https://ui.ballmac.com/preview/data-grid-demo"},{"name":"data-table","kind":"component","type":"registry:ui","title":"Data Table","description":"A complete data grid on TanStack Table: sortable headers, search, column visibility, row selection, pagination, a loading state and live result counts.","category":"data-display","tier":"free","tags":["table","sorting","filter","pagination","tanstack"],"version":"1.0.0","updated":"2026-09-30","url":"https://ui.ballmac.com/components/data-table","registryUrl":"https://ui.ballmac.com/r/data-table.json","install":"npx shadcn@latest add @ballmac/data-table","summary":"Pass columns (TanStack ColumnDef) and data. Use DataTableColumnHeader for sortable headers. selectable adds checkboxes; pageSize sets rows per page.","whenToUse":["Lists of records people search, sort and select","Admin and billing screens"],"whenNotToUse":["A small static table; use table","Server-side paging for huge datasets without adapting the parts"],"composesWith":["table","badge","dropdown-menu"],"dependencies":["@tanstack/react-table@^8","lucide-react"],"registryDependencies":["shadcn:utils","button","checkbox","dropdown-menu","table","i18n"],"examples":["data-table-demo","data-table-states"],"states":[],"preview":"https://ui.ballmac.com/preview/data-table-demo"},{"name":"date-picker","kind":"component","type":"registry:ui","title":"Date Picker","description":"A button that opens a calendar popover to choose one date, with presets, month and year selects, min and max dates, clearing, invalid state and form submission.","category":"forms","tier":"free","tags":["date","input","popover","form"],"version":"1.0.1","updated":"2026-10-11","url":"https://ui.ballmac.com/components/date-picker","registryUrl":"https://ui.ballmac.com/r/date-picker.json","install":"npx shadcn@latest add @ballmac/date-picker","summary":"Give it a defaultValue or value and onValueChange. presets add quick picks, dropdowns adds month and year selects, name submits YYYY-MM-DD.","whenToUse":["A single date in a form","Deadlines, birthdays and delivery dates","When quick picks like Tomorrow help"],"whenNotToUse":["A date range; use date-range-picker","An always-visible calendar; use calendar"],"composesWith":["field","calendar","popover"],"dependencies":["lucide-react"],"registryDependencies":["shadcn:utils","calendar","popover","i18n"],"examples":["date-picker-demo","date-picker-states"],"states":[],"preview":"https://ui.ballmac.com/preview/date-picker-demo"},{"name":"date-range-picker","kind":"component","type":"registry:ui","title":"Date Range Picker","description":"Two native date controls with inclusive range correction and quick-select presets.","category":"forms","tier":"free","tags":["date","range","calendar"],"version":"1.0.0","updated":"2026-09-30","url":"https://ui.ballmac.com/components/date-range-picker","registryUrl":"https://ui.ballmac.com/r/date-range-picker.json","install":"npx shadcn@latest add @ballmac/date-range-picker","summary":"Two native date controls with inclusive range correction and quick-select presets.","whenToUse":["Pick report or booking date windows"],"whenNotToUse":["Use Date Picker for one date"],"composesWith":["time-picker"],"dependencies":[],"registryDependencies":["shadcn:utils","i18n"],"examples":["date-range-picker-demo","date-range-picker-states"],"states":[],"preview":"https://ui.ballmac.com/preview/date-range-picker-demo"},{"name":"description-list","kind":"component","type":"registry:ui","title":"Description List","description":"A semantic key-value surface with responsive split and stacked layouts.","category":"data-display","tier":"free","tags":["details","key-value","metadata"],"version":"1.0.0","updated":"2026-09-30","url":"https://ui.ballmac.com/components/description-list","registryUrl":"https://ui.ballmac.com/r/description-list.json","install":"npx shadcn@latest add @ballmac/description-list","summary":"A semantic key-value surface with responsive split and stacked layouts.","whenToUse":["Display read-only properties for an object"],"whenNotToUse":["Use a form for editable fields"],"composesWith":["card"],"dependencies":[],"registryDependencies":["shadcn:utils"],"examples":["description-list-demo","description-list-states"],"states":[],"preview":"https://ui.ballmac.com/preview/description-list-demo"},{"name":"desktop-icons","kind":"component","type":"registry:ui","title":"Desktop Icons","description":"A macOS desktop of icons: box-select with the pointer, drag to move with snapping to grid cells, double-click or Return to open, arrow keys to move focus and Alt plus arrows to move an icon.","category":"macos","tier":"free","tags":["desktop","icons","drag","selection","macos"],"version":"1.0.0","updated":"2026-10-01","url":"https://ui.ballmac.com/components/desktop-icons","registryUrl":"https://ui.ballmac.com/r/desktop-icons.json","install":"npx shadcn@latest add @ballmac/desktop-icons","summary":". Positions are grid cells. Icons that land on an occupied cell move to the nearest free one.","whenToUse":["Desktop-style demos and playgrounds","Launch surfaces with draggable shortcuts"],"whenNotToUse":["Ordinary file lists (file-browser)"],"composesWith":["window-manager","finder-window","mac-icons","mac-context-menu"],"dependencies":[],"registryDependencies":["shadcn:utils","mac-icons","i18n"],"examples":["desktop-icons-demo","desktop-icons-window"],"states":[],"preview":"https://ui.ballmac.com/preview/desktop-icons-demo"},{"name":"dialog","kind":"component","type":"registry:ui","title":"Dialog","description":"A Radix modal dialog with a blurred overlay, centered card surface that fits 360 px screens, header and footer parts, optional close button and animations.","category":"primitives","tier":"free","tags":["dialog","modal","overlay","radix"],"version":"1.0.0","updated":"2026-09-28","url":"https://ui.ballmac.com/components/dialog","registryUrl":"https://ui.ballmac.com/r/dialog.json","install":"npx shadcn@latest add @ballmac/dialog","summary":"Modal window that traps focus. Compose Dialog > DialogTrigger (style it with buttonVariants) + DialogContent with DialogHeader (DialogTitle, DialogDescription) and DialogFooter; use DialogClose with buttonVariants for cancel buttons. Avoid asChild so the files also work in Base UI projects.","whenToUse":["Short forms that shouldn't leave the page (edit profile, rename)","Confirming destructive actions","Focused detail views"],"whenNotToUse":["Non-blocking messages (use a toast)","Long multi-step flows (use a page)","Content tied to a control that should stay visible (use a popover)"],"composesWith":["button","input","label","textarea","select"],"dependencies":["radix-ui","lucide-react"],"registryDependencies":["shadcn:utils","i18n"],"examples":["dialog-demo","dialog-confirm"],"states":[],"preview":"https://ui.ballmac.com/preview/dialog-demo"},{"name":"diff-viewer","kind":"component","type":"registry:ui","title":"Diff Viewer","description":"A line-by-line text diff with change counts, line numbers, and accessible change labels.","category":"data-display","tier":"free","tags":["diff","code","comparison"],"version":"1.0.0","updated":"2026-09-30","url":"https://ui.ballmac.com/components/diff-viewer","registryUrl":"https://ui.ballmac.com/r/diff-viewer.json","install":"npx shadcn@latest add @ballmac/diff-viewer","summary":"A line-by-line text diff with change counts, line numbers, and accessible change labels.","whenToUse":["Review before-and-after text changes"],"whenNotToUse":["Use Comparison Table for product features"],"composesWith":["code-block"],"dependencies":[],"registryDependencies":["shadcn:utils","i18n"],"examples":["diff-viewer-demo","diff-viewer-states"],"states":[],"preview":"https://ui.ballmac.com/preview/diff-viewer-demo"},{"name":"dock","kind":"component","type":"registry:ui","title":"Dock","description":"A macOS-style dock whose icons grow with spring physics as the pointer approaches and push their neighbors apart. Labels, running dots, a launch bounce and arrow-key navigation included.","category":"macos","tier":"free","tags":["dock","macos","magnification","toolbar","navigation","motion","app launcher"],"version":"1.0.0","updated":"2026-09-29","url":"https://ui.ballmac.com/components/dock","registryUrl":"https://ui.ballmac.com/r/dock.json","install":"npx shadcn@latest add @ballmac/dock","summary":" is a role=toolbar row (or column with orientation=\"vertical\") of buttons with cursor-proximity magnification; draws the divider. Style each tile through DockItem's className (gradients, colors); icons are sized to about half the tile.","whenToUse":["An app-launcher or quick-links bar on a Mac-flavored landing page or product hero","A floating navigation bar for a portfolio or dashboard with a handful of destinations","Showing off the apps or integrations a product ships with"],"whenNotToUse":["Primary navigation with many text links (use a header or sidebar)","More than about 12 items, or anywhere it would need to scroll horizontally"],"composesWith":["mac-window","menu-bar","dynamic-island"],"dependencies":["motion@^12"],"registryDependencies":["shadcn:utils","direction"],"examples":["dock-demo","dock-vertical"],"states":[],"preview":"https://ui.ballmac.com/preview/dock-demo"},{"name":"dot-pattern","kind":"component","type":"registry:ui","title":"Dot Pattern","description":"A lightweight SVG dot grid background with an optional radial fade and a few softly pulsing glow dots. One pattern element, token colors, hydration-safe, still under reduced motion.","category":"backgrounds","tier":"free","tags":["dots","pattern","grid","svg","background","decorative"],"version":"1.0.0","updated":"2026-09-29","url":"https://ui.ballmac.com/components/dot-pattern","registryUrl":"https://ui.ballmac.com/r/dot-pattern.json","install":"npx shadcn@latest add @ballmac/dot-pattern","summary":"Place as the first child of a relative, overflow-hidden container (absolute inset-0, aria-hidden, pointer-events-none). Add glow for a few pulsing accent dots. The cheapest Ballmac background; safe for large areas.","whenToUse":["Quiet texture behind heroes, feature cards, empty states and auth pages","Large page areas where canvas effects would be too heavy"],"whenNotToUse":["When you want visible motion as the focal point (use flickering-grid or beams-background)"],"composesWith":["orbiting-circles","animated-beam","spotlight-card"],"dependencies":[],"registryDependencies":["shadcn:utils"],"examples":["dot-pattern-demo","dot-pattern-dense"],"states":[],"preview":"https://ui.ballmac.com/preview/dot-pattern-demo"},{"name":"dotted-map","kind":"component","type":"registry:ui","title":"Dotted Map","description":"A world map built from dots, with pulsing markers, optional labels and animated routes between places, as one lightweight SVG with a text summary for screen readers.","category":"data-display","tier":"free","tags":["map","world","dots","markers","locations"],"version":"1.0.2","updated":"2026-10-12","url":"https://ui.ballmac.com/components/dotted-map","registryUrl":"https://ui.ballmac.com/r/dotted-map.json","install":"npx shadcn@latest add @ballmac/dotted-map","summary":". The land mask is built in; nothing is fetched. Higher dots gives finer coastlines.","whenToUse":["Where-we-operate and customer-location sections","Network and traffic visualizations"],"whenNotToUse":["Interactive geographic data or zooming (use a map library)","A 3D globe (globe)"],"composesWith":["globe","stat-card"],"dependencies":["motion@^12"],"registryDependencies":["shadcn:utils","motion-presets","i18n"],"examples":["dotted-map-demo","dotted-map-regions"],"states":[],"preview":"https://ui.ballmac.com/preview/dotted-map-demo"},{"name":"drawer","kind":"component","type":"registry:ui","title":"Drawer","description":"A swipe-to-dismiss panel from any edge on Vaul, with grab handle, header, scrollable body and footer, drag-safe inner content and reduced-motion handling.","category":"primitives","tier":"free","tags":["overlay","mobile","bottom sheet","vaul"],"version":"1.0.0","updated":"2026-09-30","url":"https://ui.ballmac.com/components/drawer","registryUrl":"https://ui.ballmac.com/r/drawer.json","install":"npx shadcn@latest add @ballmac/drawer","summary":"Bottom drawers suit mobile actions; use direction left or right for side panels. Compose DrawerHeader, DrawerBody and DrawerFooter.","whenToUse":["Mobile-first confirmations and pickers","Panels users may want to flick away"],"whenNotToUse":["Desktop settings panels; use sheet","Critical confirmations; use alert-dialog"],"composesWith":["button","sheet"],"dependencies":["vaul@^1"],"registryDependencies":["shadcn:utils"],"examples":["drawer-demo","drawer-states"],"states":[],"preview":"https://ui.ballmac.com/preview/drawer-demo"},{"name":"dropdown-menu","kind":"component","type":"registry:ui","title":"Dropdown Menu","description":"An action menu on a trigger with checkbox and radio items, submenus, shortcut hints and destructive rows, built on Radix for full keyboard and typeahead support.","category":"primitives","tier":"free","tags":["menu","overlay","actions","radix"],"version":"1.0.1","updated":"2026-10-11","url":"https://ui.ballmac.com/components/dropdown-menu","registryUrl":"https://ui.ballmac.com/r/dropdown-menu.json","install":"npx shadcn@latest add @ballmac/dropdown-menu","summary":"Opens a menu of actions from a button. Supports groups, labels, checkbox and radio items, nested submenus, shortcuts and a destructive style.","whenToUse":["Account, row and overflow (…) actions","Sort and view preferences with radio items","Menus with a submenu or checked options"],"whenNotToUse":["Choosing a form value; use select or combobox","Right-click menus; use context-menu","A persistent app menu bar; use menubar"],"composesWith":["button","kbd"],"dependencies":["radix-ui","lucide-react"],"registryDependencies":["shadcn:utils","direction"],"examples":["dropdown-menu-demo","dropdown-menu-states"],"states":[],"preview":"https://ui.ballmac.com/preview/dropdown-menu-demo"},{"name":"dynamic-island","kind":"component","type":"registry:ui","title":"Dynamic Island","description":"A black pill or MacBook-style notch that morphs between live activities (timers, uploads, an AI thinking state, notifications) with a spring layout animation. Each view is announced politely.","category":"macos","tier":"free","tags":["dynamic island","notch","macos","ios","live activity","status","motion","morph"],"version":"1.0.0","updated":"2026-09-29","url":"https://ui.ballmac.com/components/dynamic-island","registryUrl":"https://ui.ballmac.com/r/dynamic-island.json","install":"npx shadcn@latest add @ballmac/dynamic-island","summary":" renders whichever child matches and springs its size and corner radius to fit. Size each view with className (h-/w-/padding); set radius per view; label is announced via a polite live region.","whenToUse":["Showing one live background activity at a time: an upload, a build, a timer, an AI response in progress","A compact status surface pinned to the top of an app or a product mockup","Landing-page heroes that demo a Mac notch or iPhone app"],"whenNotToUse":["Several notifications that need to stay visible together (use notification-stack)","Long or critical messages that must not disappear (use a dialog or an inline alert)"],"composesWith":["dock"],"dependencies":["motion@^12"],"registryDependencies":["shadcn:utils"],"examples":["dynamic-island-demo","dynamic-island-pill"],"states":[],"preview":"https://ui.ballmac.com/preview/dynamic-island-demo"},{"name":"emoji-picker","kind":"component","type":"registry:ui","title":"Emoji Picker","description":"An emoji picker that loads its data on first use: search by name or word, jump between groups, pick a skin tone, recent emoji, a real ARIA grid with arrow keys, and any language from Emojibase.","category":"forms","tier":"free","tags":["emoji","picker","reactions","chat","search","skin tone","grid"],"version":"1.0.0","updated":"2026-10-19","url":"https://ui.ballmac.com/components/emoji-picker","registryUrl":"https://ui.ballmac.com/r/emoji-picker.json","install":"npx shadcn@latest add @ballmac/emoji-picker","summary":" insert(e.emoji)} />. It loads English emoji on first use. For another language pass loadEmojis that returns fromEmojibase(compact, groups) for that language. Wrap it in a popover for a button.","whenToUse":["Chat, comments and reactions where people add emoji","A reaction bar's \"more\" menu","Any text field that needs an emoji button"],"whenNotToUse":["A fixed handful of reactions; show buttons instead","Inserting images or stickers","Custom emoji sets; map them into the same EmojiData and pass loadEmojis"],"composesWith":["popover","textarea","mention-input","rich-text-editor"],"dependencies":["emojibase-data@^18","lucide-react"],"registryDependencies":["shadcn:utils","skeleton","state-view","i18n","direction"],"examples":["emoji-picker-demo","emoji-picker-popover","emoji-picker-german","emoji-picker-loading","emoji-picker-error"],"states":[{"id":"loading","title":"Loading","example":"emoji-picker-loading","trigger":"while the emoji data loads","note":"A grid of skeletons under a disabled search box, announced as loading. The data is fetched the first time the picker is shown.","preview":"https://ui.ballmac.com/preview/emoji-picker-loading"},{"id":"error","title":"Could not load","example":"emoji-picker-error","trigger":"loadEmojis rejects","note":"An error with a Try again button that loads the emoji again, announced as an alert.","preview":"https://ui.ballmac.com/preview/emoji-picker-error"}],"preview":"https://ui.ballmac.com/preview/emoji-picker-demo"},{"name":"empty-state","kind":"component","type":"registry:ui","title":"Empty State","description":"A ready-to-use empty screen with guidance and primary and secondary action slots.","category":"feedback","tier":"free","tags":["empty","placeholder","action"],"version":"1.0.0","updated":"2026-09-30","url":"https://ui.ballmac.com/components/empty-state","registryUrl":"https://ui.ballmac.com/r/empty-state.json","install":"npx shadcn@latest add @ballmac/empty-state","summary":"A ready-to-use empty screen with guidance and primary and secondary action slots.","whenToUse":["Explain an empty collection","Offer a clear first action"],"whenNotToUse":["Use empty for a custom composition"],"composesWith":["empty","button"],"dependencies":["lucide-react"],"registryDependencies":["empty","shadcn:utils"],"examples":["empty-state-demo","empty-state-states"],"states":[],"preview":"https://ui.ballmac.com/preview/empty-state-demo"},{"name":"empty","kind":"component","type":"registry:ui","title":"Empty","description":"A responsive empty-state surface with media, concise guidance, and a dedicated action area.","category":"feedback","tier":"free","tags":["empty","placeholder","state"],"version":"1.0.0","updated":"2026-09-29","url":"https://ui.ballmac.com/components/empty","registryUrl":"https://ui.ballmac.com/r/empty.json","install":"npx shadcn@latest add @ballmac/empty","summary":"A responsive empty-state surface with media, concise guidance, and a dedicated action area.","whenToUse":["Explain why a list has no content","Give the next step after a search yields no results"],"whenNotToUse":["Use a skeleton while loading"],"composesWith":["button"],"dependencies":[],"registryDependencies":["shadcn:utils"],"examples":["empty-demo","empty-states"],"states":[],"preview":"https://ui.ballmac.com/preview/empty-demo"},{"name":"env-editor","kind":"component","type":"registry:ui","title":"Env Editor","description":"A .env editor with masked values, show and hide, name validation and duplicate detection, paste-to-import for whole .env files, and copy as .env.","category":"developer","tier":"free","tags":["env","environment","variables","secrets","config"],"version":"1.0.0","updated":"2026-10-01","url":"https://ui.ballmac.com/components/env-editor","registryUrl":"https://ui.ballmac.com/r/env-editor.json","install":"npx shadcn@latest add @ballmac/env-editor","summary":"Uncontrolled with defaultValue [{ key, value }] or controlled with value [{ id, key, value }] and onChange. Pasting KEY=value lines into a name field, or into the Paste .env box, imports them. parseEnv and formatEnv are exported.","whenToUse":["Project or deployment settings pages","Anywhere people manage secrets as key and value pairs"],"whenNotToUse":["Structured settings with types (settings-panel)","A single secret (api-key-field)"],"composesWith":["api-key-field","settings-panel","copy-button"],"dependencies":["motion@^12","lucide-react"],"registryDependencies":["shadcn:utils","copy-button","i18n"],"examples":["env-editor-demo","env-editor-controlled"],"states":[],"preview":"https://ui.ballmac.com/preview/env-editor-demo"},{"name":"escalation-card","kind":"component","type":"registry:ui","title":"Escalation Card","description":"The moment an AI agent hands a conversation to a person: who is waiting and for how long, why, how the customer seems to feel in words, what the agent understood, the last messages, an editable suggested reply, and Take over and Snooze.","category":"ai","tier":"free","tags":["ai","agents","support","handoff","escalation","human in the loop","inbox","customer service"],"version":"1.0.0","updated":"2026-10-24","url":"https://ui.ballmac.com/components/escalation-card","registryUrl":"https://ui.ballmac.com/r/escalation-card.json","install":"npx shadcn@latest add @ballmac/escalation-card","summary":"customer, channel, reason (required); sentiment calm | frustrated | angry | unknown, waiting, summary string[], messages [{ from: 'customer' | 'agent', text, time? }], suggestedReply (editable). onTakeOver, onSnooze and onSendReply(reply) may return promises; each reports success in words and shows a failure as an alert.","whenToUse":["Showing a person a conversation an agent could not finish, with context and a head start","An inbox row that needs a human decision"],"whenNotToUse":["Approving a tool call; use approval-card","The packet passed between two agents; use handoff-card"],"composesWith":["handoff-card","approval-card","agent-roster","ai-chat"],"dependencies":["lucide-react"],"registryDependencies":["shadcn:utils","i18n"],"examples":["escalation-card-demo","escalation-card-simple"],"states":[],"statesNone":"A presentational card with its own actions: the conversation is passed in, so it has nothing of its own to load, and failures are reported on the card.","preview":"https://ui.ballmac.com/preview/escalation-card-demo"},{"name":"event-calendar","kind":"component","type":"registry:ui","title":"Event Calendar","description":"A full calendar with month, week, day and agenda views: overlapping events side by side, multi-day bars, drag to move, resize or create, keyboard moves, a live now line and locale-aware weeks.","category":"data-display","tier":"free","tags":["calendar","events","schedule","month","week","agenda","drag","timeline"],"version":"1.0.0","updated":"2026-10-19","url":"https://ui.ballmac.com/components/event-calendar","registryUrl":"https://ui.ballmac.com/r/event-calendar.json","install":"npx shadcn@latest add @ballmac/event-calendar","summary":"Pass events [{ id, title, start, end?, allDay?, tone?, location? }] and a label. Hold view and date in state if you need them. For editing set editable and selectable and handle onEventChange(event, { start, end, allDay }) and onRangeSelect.","whenToUse":["Team, booking, room and delivery calendars with several views","Schedulers where people drag events to reschedule or drag across time to add one","A month overview with multi-day events and an agenda list for phones"],"whenNotToUse":["Picking a date in a form; use calendar or date-picker","A resource timeline with rows per person or room","Recurring-event rules or time zone conversion; compute those yourself and pass plain events"],"composesWith":["calendar","popover","badge","dialog"],"dependencies":["lucide-react"],"registryDependencies":["shadcn:utils","button","popover","skeleton","state-view","i18n","direction","calendar-dates"],"examples":["event-calendar-demo","event-calendar-week","event-calendar-day","event-calendar-editable","event-calendar-agenda","event-calendar-loading","event-calendar-empty","event-calendar-error"],"states":[{"id":"loading","title":"Loading","example":"event-calendar-loading","trigger":"state=\"loading\"","note":"A month-shaped skeleton, announced as loading; nothing can be clicked.","preview":"https://ui.ballmac.com/preview/event-calendar-loading"},{"id":"empty","title":"No events","example":"event-calendar-empty","trigger":"events={[]} in the agenda view","note":"The agenda says there is nothing this month and emptyState can add an action; the month and week grids stay as plain calendars.","preview":"https://ui.ballmac.com/preview/event-calendar-empty"},{"id":"error","title":"Could not load","example":"event-calendar-error","trigger":"state=\"error\"","note":"An error with a Try again button (onRetry), announced as an alert.","preview":"https://ui.ballmac.com/preview/event-calendar-error"}],"preview":"https://ui.ballmac.com/preview/event-calendar-demo"},{"name":"feedback-widget","kind":"component","type":"registry:ui","title":"Feedback Widget","description":"A feedback pill that opens a popover with five face ratings as a radio group, optional topic chips and a comment box, then a thank-you confirmation.","category":"saas","tier":"free","tags":["feedback","rating","survey","popover"],"version":"1.0.0","updated":"2026-09-30","url":"https://ui.ballmac.com/components/feedback-widget","registryUrl":"https://ui.ballmac.com/r/feedback-widget.json","install":"npx shadcn@latest add @ballmac/feedback-widget","summary":". onSubmit receives {rating, message, topic}; return a promise to show sending. Dock it in a corner with your own positioning.","whenToUse":["Collecting product feedback in-app","Page 'was this helpful' prompts"],"whenNotToUse":["Long surveys","Support requests; link to a help form"],"composesWith":["popover","rating","textarea"],"dependencies":["motion@^12","lucide-react"],"registryDependencies":["shadcn:utils","motion-presets","popover","i18n"],"examples":["feedback-widget-demo","feedback-widget-states"],"states":[],"preview":"https://ui.ballmac.com/preview/feedback-widget-demo"},{"name":"feel-auto","kind":"foundation","type":"registry:ui","title":"Feel Auto","description":"Picks the platform feel for you: macOS, iOS, Windows or web, from the device, before the first paint. All four feels are included and a user's override is remembered.","category":"foundation","tier":"free","tags":["feel","auto","platform","macos","windows","ios","tauri","electron","detect"],"version":"1.0.0","updated":"2026-10-12","url":"https://ui.ballmac.com/docs/get-started/make-it-yours","registryUrl":"https://ui.ballmac.com/r/feel-auto.json","install":"npx shadcn@latest add @ballmac/feel-auto","summary":"Install once, render in , and the whole app handles like the platform it runs on. A Tauri or Electron app on a Mac becomes macOS and the same app on Windows becomes Windows, with no code branches.","whenToUse":["Desktop apps (Tauri, Electron) that ship to more than one OS","Web apps that should feel native on phones and desktops"],"whenNotToUse":["Apps that always want one feel: install feel-macos, feel-ios or feel-windows instead","Server components that must not read the platform: the feel is applied on the client before paint"],"composesWith":["app-window","feel-presets"],"dependencies":[],"registryDependencies":["feel-presets"],"examples":[],"states":[]},{"name":"field","kind":"component","type":"registry:ui","title":"Field","description":"Form field layout with label, description and error that wire their ids to the control automatically, plus fieldset, legend, orientation and invalid/disabled state.","category":"forms","tier":"free","tags":["form","label","validation","layout"],"version":"1.0.0","updated":"2026-09-30","url":"https://ui.ballmac.com/components/field","registryUrl":"https://ui.ballmac.com/r/field.json","install":"npx shadcn@latest add @ballmac/field","summary":"Wrap a control in Field, spread useFieldControl() on it, and label, description, error, aria-invalid and disabled are connected for you.","whenToUse":["Any labelled form control","Forms with validation messages","Settings rows with a switch or checkbox"],"whenNotToUse":["A single unlabeled search box; use search-field","Complete form state management; combine with your form library"],"composesWith":["input","textarea","select","checkbox","switch","combobox"],"dependencies":["class-variance-authority"],"registryDependencies":["shadcn:utils"],"examples":["field-demo","field-states"],"states":[],"preview":"https://ui.ballmac.com/preview/field-demo"},{"name":"file-browser","kind":"component","type":"registry:ui","title":"File Browser","description":"A file manager for apps: breadcrumb folders, search, sortable columns, row checkboxes with select-all, a bulk-action bar, list and grid views and full keyboard control.","category":"data-display","tier":"free","tags":["files","browser","table","upload","folders"],"version":"1.0.0","updated":"2026-10-01","url":"https://ui.ballmac.com/components/file-browser","registryUrl":"https://ui.ballmac.com/r/file-browser.json","install":"npx shadcn@latest add @ballmac/file-browser","summary":". entries is a FileEntry tree. Sort by name, modified or size (aria-sort). Space selects, Enter opens, arrow keys move.","whenToUse":["Drive-style pages inside an app","Choosing files for download or deletion"],"whenNotToUse":["A Mac-styled window (finder-window)","Plain tables (data-table)"],"composesWith":["data-table","breadcrumb","file-dropzone"],"dependencies":["lucide-react"],"registryDependencies":["shadcn:utils","i18n","direction"],"examples":["file-browser-demo","file-browser-grid"],"states":[],"preview":"https://ui.ballmac.com/preview/file-browser-demo"},{"name":"file-dropzone","kind":"component","type":"registry:ui","title":"File Dropzone","description":"Drop files or browse with native file selection, type and size validation, removable file rows, and live errors.","category":"forms","tier":"free","tags":["upload","files","dropzone"],"version":"1.0.0","updated":"2026-09-30","url":"https://ui.ballmac.com/components/file-dropzone","registryUrl":"https://ui.ballmac.com/r/file-dropzone.json","install":"npx shadcn@latest add @ballmac/file-dropzone","summary":"Drop files or browse with native file selection, type and size validation, removable file rows, and live errors.","whenToUse":["Upload a document or group of assets","Review selected files before submitting"],"whenNotToUse":["Use input for a minimal single-file field"],"composesWith":["button"],"dependencies":["lucide-react"],"registryDependencies":["shadcn:utils","i18n"],"examples":["file-dropzone-demo","file-dropzone-states"],"states":[],"preview":"https://ui.ballmac.com/preview/file-dropzone-demo"},{"name":"file-tree","kind":"component","type":"registry:ui","title":"File Tree","description":"A folder and file explorer with semantic tree navigation and file-type icons.","category":"data-display","tier":"free","tags":["files","folders","tree"],"version":"1.0.0","updated":"2026-09-30","url":"https://ui.ballmac.com/components/file-tree","registryUrl":"https://ui.ballmac.com/r/file-tree.json","install":"npx shadcn@latest add @ballmac/file-tree","summary":"A folder and file explorer with semantic tree navigation and file-type icons.","whenToUse":["Browse a project or document hierarchy"],"whenNotToUse":["Use Tree View for non-file hierarchies"],"composesWith":["tree-view"],"dependencies":["lucide-react"],"registryDependencies":["tree-view","i18n"],"examples":["file-tree-demo","file-tree-states"],"states":[],"preview":"https://ui.ballmac.com/preview/file-tree-demo"},{"name":"finder-window","kind":"component","type":"registry:ui","title":"Finder Window","description":"A working mini Finder: sidebar shortcuts, back and forward history, icon and list views, search, click, shift and command selection, keyboard navigation and a path bar, on a macOS window.","category":"macos","tier":"free","tags":["finder","files","macos","window","browser"],"version":"1.0.0","updated":"2026-10-01","url":"https://ui.ballmac.com/components/finder-window","registryUrl":"https://ui.ballmac.com/r/finder-window.json","install":"npx shadcn@latest add @ballmac/finder-window","summary":". root is a FinderNode tree (folder, file or drive). Double-click or Return opens; Cmd+Up goes to the parent folder.","whenToUse":["Product demos and docs that show a file system","Mac-style apps"],"whenNotToUse":["A real file manager for your app (file-browser)","A single window frame (mac-window)"],"composesWith":["mac-window","toolbar","desktop-icons","mac-context-menu"],"dependencies":["lucide-react"],"registryDependencies":["shadcn:utils","mac-window","mac-icons","i18n"],"examples":["finder-window-demo","finder-window-list"],"states":[],"preview":"https://ui.ballmac.com/preview/finder-window-demo"},{"name":"flickering-grid","kind":"component","type":"registry:ui","title":"Flickering Grid","description":"A canvas grid of small squares that flicker at random brightness, like a busy status board. Pixel-snapped, token-colored, DPR aware, pauses off-screen, static under reduced motion.","category":"backgrounds","tier":"free","tags":["grid","pixels","flicker","canvas","background","hero"],"version":"1.0.0","updated":"2026-09-29","url":"https://ui.ballmac.com/components/flickering-grid","registryUrl":"https://ui.ballmac.com/r/flickering-grid.json","install":"npx shadcn@latest add @ballmac/flickering-grid","summary":"Place as the first child of a relative, overflow-hidden container; it fills it (absolute inset-0, aria-hidden, pointer-events-none). Tune squareSize, gap and maxOpacity for density and contrast.","whenToUse":["Section or hero backgrounds for infrastructure, data or developer products","Feature cards that should feel alive without a focal animation"],"whenNotToUse":["Behind small or low-contrast text (keep maxOpacity low or add a scrim)","Very large full-page areas on low-power devices (use dot-pattern)"],"composesWith":["number-ticker","shimmer-text"],"dependencies":[],"registryDependencies":["shadcn:utils","color"],"examples":["flickering-grid-demo","flickering-grid-accent"],"states":[],"preview":"https://ui.ballmac.com/preview/flickering-grid-demo"},{"name":"floating-nav","kind":"component","type":"registry:ui","title":"Floating Nav","description":"A pill-shaped navigation that floats over the page, with an indicator that glides between items on a spring and optional hide-on-scroll.","category":"navigation","tier":"free","tags":["navigation","pill","floating","mobile"],"version":"1.0.0","updated":"2026-09-30","url":"https://ui.ballmac.com/components/floating-nav","registryUrl":"https://ui.ballmac.com/r/floating-nav.json","install":"npx shadcn@latest add @ballmac/floating-nav","summary":"items: {value,label,href,icon}. position top or bottom; autoHide slides it away on scroll; value/defaultValue/onValueChange pick the active item.","whenToUse":["Landing pages and portfolios","App-style bottom navigation on small screens"],"whenNotToUse":["Sites that need nested menus; use navbar with mega-menu","Long lists of links"],"composesWith":["navbar","button"],"dependencies":["motion@^12"],"registryDependencies":["shadcn:utils","scroll","motion-presets","i18n"],"examples":["floating-nav-demo","floating-nav-states"],"states":[],"preview":"https://ui.ballmac.com/preview/floating-nav-demo"},{"name":"flow-sankey","kind":"component","type":"registry:ui","title":"Flow Sankey","description":"A dependency-free flow diagram: columns placed by the longest chain, crossings reduced, links as thick as their value, nodes as buttons that light up their flows, a detail line, and the same flows as a table for screen readers.","category":"data-display","tier":"free","tags":["sankey","flow","funnel","chart","journey","diagram","conversion","attribution"],"version":"1.0.0","updated":"2026-10-24","url":"https://ui.ballmac.com/components/flow-sankey","registryUrl":"https://ui.ballmac.com/r/flow-sankey.json","install":"npx shadcn@latest add @ballmac/flow-sankey","summary":"nodes is [{ id, label, group? }]; links is [{ source, target, value }]. Columns, order and sizes are computed (layoutSankey is exported). format(value), selected / defaultSelected / onSelectedChange. Links with zero value, unknown ids or a node linking to itself are ignored.","whenToUse":["Showing where traffic, money or users go step by step, with drop-off","Outcomes of agent runs: attempts, tool calls, approvals, results"],"whenNotToUse":["A simple conversion funnel of one path; use funnel-1","Proportions with no steps; use treemap","A graph where cycles matter; use agent-graph"],"composesWith":["treemap","run-ledger","chart-frame","heat-grid"],"dependencies":[],"registryDependencies":["shadcn:utils","i18n"],"examples":["flow-sankey-demo","flow-sankey-agent"],"states":[],"statesNone":"A presentational chart: you pass the nodes and links in, so it has nothing of its own to load or fail.","preview":"https://ui.ballmac.com/preview/flow-sankey-demo"},{"name":"form","kind":"component","type":"registry:ui","title":"Form","description":"React Hook Form wired to Ballmac Field: one FormField renders label, control, description and error with ids, aria-invalid and aria-describedby linked, plus a pending submit button.","category":"forms","tier":"free","tags":["form","validation","react-hook-form","field"],"version":"1.0.0","updated":"2026-09-30","url":"https://ui.ballmac.com/components/form","registryUrl":"https://ui.ballmac.com/r/form.json","install":"npx shadcn@latest add @ballmac/form","summary":"const form = useForm();
}/>. Use rules or a resolver for validation.","whenToUse":["Any form with client validation","Forms that need per-field errors announced"],"whenNotToUse":["A single uncontrolled input; use field","Server actions without client state"],"composesWith":["field","input","checkbox","select"],"dependencies":["react-hook-form@^7"],"registryDependencies":["shadcn:utils","button","field"],"examples":["form-demo","form-states"],"states":[],"preview":"https://ui.ballmac.com/preview/form-demo"},{"name":"git-graph","kind":"component","type":"registry:ui","title":"Git Graph","description":"A commit history with lane-routed branch and merge lines, branch and tag labels, authors and dates, selection, and listbox keyboard navigation.","category":"developer","tier":"free","tags":["git","commits","history","branches","graph"],"version":"1.0.0","updated":"2026-10-01","url":"https://ui.ballmac.com/components/git-graph","registryUrl":"https://ui.ballmac.com/r/git-graph.json","install":"npx shadcn@latest add @ballmac/git-graph","summary":"commits is newest first: [{ hash, parents, message, author, date, branches?, tags? }]. Lanes are computed for you (layoutCommits is exported). selected/onSelect for a detail view. Rows are listbox options.","whenToUse":["Repository or release history views","Explaining a branching strategy in docs"],"whenNotToUse":["Diffs (diff-viewer)","Huge histories without paging"],"composesWith":["diff-viewer","code-block","badge"],"dependencies":["lucide-react"],"registryDependencies":["shadcn:utils","i18n"],"examples":["git-graph-demo","git-graph-linear"],"states":[],"preview":"https://ui.ballmac.com/preview/git-graph-demo"},{"name":"glare-hover","kind":"component","type":"registry:ui","title":"Glare Hover","description":"Wraps any content so a diagonal band of light sweeps across it on hover or keyboard focus, in white for images and dark surfaces or a soft shadow for light ones.","category":"motion","tier":"free","tags":["hover","glare","shine","image","card"],"version":"1.0.0","updated":"2026-10-01","url":"https://ui.ballmac.com/components/glare-hover","registryUrl":"https://ui.ballmac.com/r/glare-hover.json","install":"npx shadcn@latest add @ballmac/glare-hover","summary":"anything. The sweep runs once per hover and resets instantly when the pointer leaves. Pure CSS transitions; nothing renders on pointer move.","whenToUse":["Product images, posters and cards","Anything that deserves a small touch of polish on hover"],"whenNotToUse":["Pointer-following lighting (magic-card or spotlight-card)"],"composesWith":["tilt-card","magic-card","card"],"dependencies":[],"registryDependencies":["shadcn:utils","motion-presets"],"examples":["glare-hover-demo","glare-hover-tones"],"states":[],"preview":"https://ui.ballmac.com/preview/glare-hover-demo"},{"name":"globe","kind":"component","type":"registry:ui","title":"Globe","description":"An interactive WebGL dot globe (cobe) with markers, drag-to-spin momentum and arrow-key control. Colors come from theme tokens and repaint on theme change; starts lazily and pauses off-screen.","category":"backgrounds","tier":"free","tags":["globe","webgl","map","regions","3d","hero","interactive"],"version":"1.0.0","updated":"2026-09-29","url":"https://ui.ballmac.com/components/globe","registryUrl":"https://ui.ballmac.com/r/globe.json","install":"npx shadcn@latest add @ballmac/globe","summary":"Render in a sized container (it is a square, w-full, max 600px). The canvas has role=img and an aria-label; pass label to describe what it shows. It starts WebGL only when scrolled near the viewport.","whenToUse":["Showing global reach: regions, edge locations, offices, customers by country","A hero or feature-card visual for infrastructure, networking or travel products"],"whenNotToUse":["Precise geographic data or choropleths (use a real map library)","Several globes on one page; each is a WebGL context"],"composesWith":["number-ticker","spotlight-card","badge"],"dependencies":["cobe@^0.6"],"registryDependencies":["shadcn:utils","color","i18n"],"examples":["globe-demo","globe-hero"],"states":[],"preview":"https://ui.ballmac.com/preview/globe-demo"},{"name":"glow-border","kind":"component","type":"registry:ui","title":"Glow Border","description":"Wraps any content in a border drawn by a rotating conic gradient in theme colors, with a soft outer glow. Speed, width, radius and arc length are props; it stops at a still angle under reduced motion.","category":"motion","tier":"free","tags":["border","gradient","glow","conic","highlight","pricing","button","motion"],"version":"1.0.0","updated":"2026-09-29","url":"https://ui.ballmac.com/components/glow-border","registryUrl":"https://ui.ballmac.com/r/glow-border.json","install":"npx shadcn@latest add @ballmac/glow-border","summary":"Put content inside ; it renders a padded wrapper whose padding shows a rotating conic gradient and a content surface (bg-card, radius minus width). Use arc={1} for a full rainbow ring, a smaller arc for a comet.","whenToUse":["The recommended plan in a pricing table","One primary call-to-action or an AI entry point","Marking a card as new, live or selected"],"whenNotToUse":["Several elements at once on the same screen (use it for one focal point)","A thin light that travels along an existing border (use border-beam)"],"composesWith":["button","border-beam","tilt-card"],"dependencies":["motion@^12"],"registryDependencies":["shadcn:utils"],"examples":["glow-border-demo","glow-border-button"],"states":[],"preview":"https://ui.ballmac.com/preview/glow-border-demo"},{"name":"gradient-text","kind":"component","type":"registry:ui","title":"Gradient Text","description":"Text filled with a gradient of theme colors that slowly drifts, or a shiny variant that sweeps a glint of light across it on a pause. Static under reduced motion; plain text in forced colors.","category":"text","tier":"free","tags":["text","gradient","headline","shine","hero","motion"],"version":"1.0.1","updated":"2026-10-11","url":"https://ui.ballmac.com/components/gradient-text","registryUrl":"https://ui.ballmac.com/r/gradient-text.json","install":"npx shadcn@latest add @ballmac/gradient-text","summary":"Wrap a few words: ship software inside a heading, or as=\"h2\". variant=\"flow\" (default) drifts the gradient; variant=\"shiny\" adds a periodic white glint. Colors default to --chart-1/4/5/3.","whenToUse":["Highlighting two or three words in a hero headline","Product or plan names (shiny)"],"whenNotToUse":["Body text or long passages (contrast varies along the gradient)","A muted loading shimmer on status text (use shimmer-text)"],"composesWith":["word-rotate","shimmer-text"],"dependencies":["motion@^12"],"registryDependencies":["shadcn:utils","motion-presets"],"examples":["gradient-text-demo","gradient-text-shiny"],"states":[],"preview":"https://ui.ballmac.com/preview/gradient-text-demo"},{"name":"grid-pattern","kind":"component","type":"registry:ui","title":"Grid Pattern","description":"A crisp square-grid background in the border color with optional dashed lines, filled cells, softly lighting random cells and an edge fade, drawn as one SVG pattern.","category":"backgrounds","tier":"free","tags":["grid","pattern","svg","background","lines"],"version":"1.0.0","updated":"2026-10-01","url":"https://ui.ballmac.com/components/grid-pattern","registryUrl":"https://ui.ballmac.com/r/grid-pattern.json","install":"npx shadcn@latest add @ballmac/grid-pattern","summary":" in a relative parent. Random cells are picked after mount so server and browser agree.","whenToUse":["Section and hero backgrounds that need structure","Behind cards and empty states"],"whenNotToUse":["Dots (dot-pattern)","A pointer-reactive grid (interactive-grid)"],"composesWith":["dot-pattern","interactive-grid","animated-grid"],"dependencies":["motion@^12"],"registryDependencies":["shadcn:utils"],"examples":["grid-pattern-demo","grid-pattern-variants"],"states":[],"preview":"https://ui.ballmac.com/preview/grid-pattern-demo"},{"name":"guardrail-feed","kind":"component","type":"registry:ui","title":"Guardrail Feed","description":"A feed of what an agent's guardrails did: each check with its rule, action (blocked, redacted, flagged or allowed) and target, counts that double as filters, and rows that open to show why and the text that matched.","category":"ai","tier":"free","tags":["ai","agents","guardrails","safety","policy","audit","moderation","feed"],"version":"1.0.0","updated":"2026-10-24","url":"https://ui.ballmac.com/components/guardrail-feed","registryUrl":"https://ui.ballmac.com/r/guardrail-feed.json","install":"npx shadcn@latest add @ballmac/guardrail-feed","summary":"events is [{ id, time, rule, action: allowed | blocked | redacted | flagged, target, reason?, match? }] newest first. Counts by action are filter buttons; a row with reason or match opens to show them. defaultOpenId opens one row at first.","whenToUse":["Showing people what an agent's safety rules caught","An audit view of policy checks on an assistant's output or tool use"],"whenNotToUse":["A full audit log of a whole product; use the audit block","The live stream of an agent's steps; use trace or log-stream"],"composesWith":["permission-grid","approval-card","agent-lanes","log-stream"],"dependencies":["lucide-react"],"registryDependencies":["shadcn:utils","i18n"],"examples":["guardrail-feed-demo","guardrail-feed-quiet"],"states":[],"statesNone":"A presentational feed: the events are passed in, so it has nothing of its own to load, and it shows its own empty message.","preview":"https://ui.ballmac.com/preview/guardrail-feed-demo"},{"name":"handoff-card","kind":"component","type":"registry:ui","title":"Handoff Card","description":"The packet one agent passes to another: who hands over to whom, the task, the context that travels with it and its size, the questions still open and the rules to keep, with a status and room for actions.","category":"ai","tier":"free","tags":["ai","agents","handoff","multi-agent","delegation","context"],"version":"1.0.0","updated":"2026-10-24","url":"https://ui.ballmac.com/components/handoff-card","registryUrl":"https://ui.ballmac.com/r/handoff-card.json","install":"npx shadcn@latest add @ballmac/handoff-card","summary":"from and to are { name, role? }; title; context [{ label, detail?, size? }]; questions string[]; constraints string[]; status pending | accepted | returned; at; actions slot. A server-friendly card with no state.","whenToUse":["Showing what one agent passed to another, in a transcript, an inbox or a run view","A human review of a delegation before it is accepted"],"whenNotToUse":["The timeline of who did what when; use agent-lanes","A single step of a plan; use agent-plan"],"composesWith":["agent-lanes","approval-card","trace","agent-roster"],"dependencies":["lucide-react"],"registryDependencies":["shadcn:utils","i18n"],"examples":["handoff-card-demo","handoff-card-returned"],"states":[],"statesNone":"A presentational card: the handoff is passed in, so it has nothing of its own to load or fail.","preview":"https://ui.ballmac.com/preview/handoff-card-demo"},{"name":"heat-grid","kind":"component","type":"registry:ui","title":"Heat Grid","description":"A matrix of values shaded by size, such as models against test cases or services against regions: a real ARIA grid with arrow-key navigation, value text in every cell, a tone mode with icons and words, hatched empty cells and a legend.","category":"data-display","tier":"free","tags":["heatmap","matrix","grid","evals","status","comparison","chart","table"],"version":"1.0.0","updated":"2026-10-24","url":"https://ui.ballmac.com/components/heat-grid","registryUrl":"https://ui.ballmac.com/r/heat-grid.json","install":"npx shadcn@latest add @ballmac/heat-grid","summary":"rows and columns are [{ id, label }]; values is number[][] (rows then columns, null for no data). domain [min, max], format(value), selected / onSelectedChange as [row, col]. tone(value) returns 'good' | 'warn' | 'bad' to classify instead of shade; those cells also show an icon and a word.","whenToUse":["Comparing many things against many conditions at a glance","Eval results, service health by region, usage by hour and weekday"],"whenNotToUse":["A trend over time; use chart-line or sparkline","Exact records people sort and filter; use data-table","A calendar of activity; use contribution-graph"],"composesWith":["chart-frame","data-table","agent-roster","run-ledger"],"dependencies":["lucide-react"],"registryDependencies":["shadcn:utils","direction","i18n"],"examples":["heat-grid-demo","heat-grid-tone"],"states":[],"statesNone":"A presentational chart: you pass the values in, so it has nothing of its own to load or fail.","preview":"https://ui.ballmac.com/preview/heat-grid-demo"},{"name":"highlighter","kind":"component","type":"registry:ui","title":"Highlighter","description":"Hand-drawn marks around inline text: highlight, underline, box, circle, strike-through and brackets, drawn in when the phrase scrolls into view.","category":"text","tier":"free","tags":["highlight","underline","annotation","marker","text"],"version":"1.0.0","updated":"2026-10-01","url":"https://ui.ballmac.com/components/highlighter","registryUrl":"https://ui.ballmac.com/r/highlighter.json","install":"npx shadcn@latest add @ballmac/highlighter","summary":"phrase. Short phrases only: the mark is drawn around one box.","whenToUse":["Drawing attention to a key phrase in copy","Editorial and tutorial text"],"whenNotToUse":["Multi-line passages","Search-result highlighting (use a plain mark element)"],"composesWith":["text-animate","callout"],"dependencies":["motion@^12"],"registryDependencies":["shadcn:utils"],"examples":["highlighter-demo","highlighter-actions"],"states":[],"preview":"https://ui.ballmac.com/preview/highlighter-demo"},{"name":"hover-card","kind":"component","type":"registry:ui","title":"Hover Card","description":"A compact preview of a linked resource that appears on hover or keyboard focus without hiding essential information.","category":"data-display","tier":"free","tags":["preview","link","radix"],"version":"1.0.1","updated":"2026-10-11","url":"https://ui.ballmac.com/components/hover-card","registryUrl":"https://ui.ballmac.com/r/hover-card.json","install":"npx shadcn@latest add @ballmac/hover-card","summary":"Adds optional context to a link for pointer and keyboard users; the link remains useful without the preview.","whenToUse":["Preview a project or profile without navigating","Show supplementary link metadata"],"whenNotToUse":["Interactive actions inside a panel; use popover","Information required to complete a task"],"composesWith":["avatar","badge"],"dependencies":["radix-ui"],"registryDependencies":["shadcn:utils"],"examples":["hover-card-demo","hover-card-states"],"states":[],"preview":"https://ui.ballmac.com/preview/hover-card-demo"},{"name":"hud","kind":"component","type":"registry:ui","title":"HUD","description":"The macOS volume and brightness HUD: a dark frosted square with a big icon and a 16-segment bar, or a slim capsule with a smooth bar. Pops in, restarts its timer when the value changes, fades out and announces the new level.","category":"macos","tier":"free","tags":["hud","volume","brightness","macos","overlay","feedback"],"version":"1.0.0","updated":"2026-10-01","url":"https://ui.ballmac.com/components/hud","registryUrl":"https://ui.ballmac.com/r/hud.json","install":"npx shadcn@latest add @ballmac/hud","summary":" inside a relative container. useTransientHud() gives { visible, show, hide, onVisibleChange }.","whenToUse":["Keyboard-driven level changes in desktop UI demos","Transient feedback for hardware-style controls"],"whenNotToUse":["Toasts and messages (toast)","Persistent controls (slider)"],"composesWith":["control-center","menu-bar","keyboard-shortcuts"],"dependencies":["motion@^12","lucide-react"],"registryDependencies":["shadcn:utils"],"examples":["hud-demo","hud-pill"],"states":[],"preview":"https://ui.ballmac.com/preview/hud-demo"},{"name":"hyper-text","kind":"component","type":"registry:ui","title":"Hyper Text","description":"Characters flip through random letters like a split-flap board and settle left to right, as plain text or on tiles, on load, on scroll or on hover and focus.","category":"text","tier":"free","tags":["text","flip","split-flap","hover","headline"],"version":"1.0.0","updated":"2026-10-01","url":"https://ui.ballmac.com/components/hyper-text","registryUrl":"https://ui.ballmac.com/r/hyper-text.json","install":"npx shadcn@latest add @ballmac/hyper-text","summary":"TEXT. Text is uppercased. The hover trigger is focusable and replays on focus.","whenToUse":["Brand words, status boards, dates and counters","Playful hover headings"],"whenNotToUse":["Anything that must stay readable mid-animation","Long sentences"],"composesWith":["scramble-text","number-ticker"],"dependencies":["motion@^12"],"registryDependencies":["shadcn:utils"],"examples":["hyper-text-demo","hyper-text-hover"],"states":[],"preview":"https://ui.ballmac.com/preview/hyper-text-demo"},{"name":"icon-cloud","kind":"component","type":"registry:ui","title":"Icon Cloud","description":"Icons, logos or labels orbiting on a 3D sphere, spun by dragging, calming under the pointer and when anything has focus, with real list markup so every item stays reachable.","category":"motion","tier":"free","tags":["sphere","3d","logos","cloud","tech stack"],"version":"1.0.0","updated":"2026-10-01","url":"https://ui.ballmac.com/components/icon-cloud","registryUrl":"https://ui.ballmac.com/r/icon-cloud.json","install":"npx shadcn@latest add @ballmac/icon-cloud","summary":"{items}. Each child becomes a list item. Positions come from a Fibonacci sphere and update straight on the DOM. Links inside stay clickable because dragging only starts after a few pixels of movement.","whenToUse":["Showing a technology or partner ecosystem","A playful, interactive hero centerpiece"],"whenNotToUse":["Anything people must read quickly","Long lists (use a grid)"],"composesWith":["orbiting-circles","globe","marquee"],"dependencies":["motion@^12"],"registryDependencies":["shadcn:utils","i18n"],"examples":["icon-cloud-demo","icon-cloud-links"],"states":[],"preview":"https://ui.ballmac.com/preview/icon-cloud-demo"},{"name":"image-cropper","kind":"component","type":"registry:ui","title":"Image Cropper","description":"Crop a picture under a fixed frame: drag to move, wheel, pinch or slider to zoom, straighten and turn by quarters, any aspect ratio or a round avatar, full keyboard control and a canvas export to a file.","category":"forms","tier":"free","tags":["image","crop","avatar","upload","zoom","rotate","canvas"],"version":"1.0.0","updated":"2026-10-19","url":"https://ui.ballmac.com/components/image-cropper","registryUrl":"https://ui.ballmac.com/r/image-cropper.json","install":"npx shadcn@latest add @ballmac/image-cropper","summary":". Get the file with await ref.current.toBlob({ width, type }); onCropComplete gives the area in original pixels to crop on a server. shape=\"round\" for avatars.","whenToUse":["Profile pictures, cover images and product photos cropped before upload","Any upload that needs a fixed aspect ratio","Straightening a slightly tilted photo"],"whenNotToUse":["Free-form selection boxes with resizable handles","Photo editing with filters, text or drawing","Pictures from another site without CORS headers, which cannot be exported"],"composesWith":["file-dropzone","avatar","dialog","button"],"dependencies":["lucide-react"],"registryDependencies":["shadcn:utils","button","skeleton","i18n"],"examples":["image-cropper-demo","image-cropper-aspect","image-cropper-avatar","image-cropper-controlled","image-cropper-loading","image-cropper-error"],"states":[{"id":"loading","title":"Loading","example":"image-cropper-loading","trigger":"no src yet, or while the picture loads","note":"A skeleton in the picture's place, announced as loading; the controls are off.","preview":"https://ui.ballmac.com/preview/image-cropper-loading"},{"id":"error","title":"Could not load","example":"image-cropper-error","trigger":"the picture fails to load","note":"A message with a Try again button, announced as an alert; onError gets the error.","preview":"https://ui.ballmac.com/preview/image-cropper-error"}],"preview":"https://ui.ballmac.com/preview/image-cropper-demo"},{"name":"in-view","kind":"component","type":"registry:ui","title":"In View","description":"A wrapper that knows when it is on screen: it sets a data attribute for CSS, offers a render function and callbacks, and can run a simple entrance.","category":"motion","tier":"free","tags":["viewport","scroll","observer","reveal","trigger"],"version":"1.0.0","updated":"2026-10-01","url":"https://ui.ballmac.com/components/in-view","registryUrl":"https://ui.ballmac.com/r/in-view.json","install":"npx shadcn@latest add @ballmac/in-view","summary":"{content or (inView)=>content}. data-in-view is true or false for Tailwind's data-[in-view=true] variants.","whenToUse":["Starting a video, counter or animation only when seen","Custom reveal styling driven by data-in-view"],"whenNotToUse":["Staggered groups (blur-fade or stagger-list)"],"composesWith":["blur-fade","number-ticker","stagger-list"],"dependencies":["motion@^12"],"registryDependencies":["shadcn:utils"],"examples":["in-view-demo","in-view-state"],"states":[],"preview":"https://ui.ballmac.com/preview/in-view-demo"},{"name":"inline-alert","kind":"component","type":"registry:ui","title":"Inline Alert","description":"A short in-context message with semantic live priority and an optional corrective action.","category":"feedback","tier":"free","tags":["validation","message","status"],"version":"1.0.0","updated":"2026-09-30","url":"https://ui.ballmac.com/components/inline-alert","registryUrl":"https://ui.ballmac.com/r/inline-alert.json","install":"npx shadcn@latest add @ballmac/inline-alert","summary":"A short in-context message with semantic live priority and an optional corrective action.","whenToUse":["Explain a field or form outcome","Show a small inline confirmation"],"whenNotToUse":["Use alert for a larger callout"],"composesWith":["alert","input"],"dependencies":["lucide-react"],"registryDependencies":["shadcn:utils"],"examples":["inline-alert-demo","inline-alert-states"],"states":[],"preview":"https://ui.ballmac.com/preview/inline-alert-demo"},{"name":"input-group","kind":"component","type":"registry:ui","title":"Input Group","description":"One bordered field that wraps an input or textarea with icon, text, button and keyboard-hint addons at either end or above and below.","category":"forms","tier":"free","tags":["input","addon","form","textarea"],"version":"1.0.0","updated":"2026-09-30","url":"https://ui.ballmac.com/components/input-group","registryUrl":"https://ui.ballmac.com/r/input-group.json","install":"npx shadcn@latest add @ballmac/input-group","summary":"Put InputGroupInput or InputGroupTextarea plus InputGroupAddon parts inside InputGroup. The group draws the border, focus ring and invalid state.","whenToUse":["URL and currency prefixes and suffixes","Search fields with a button","Chat composers with a send button"],"whenNotToUse":["A plain field; use input","Attached separate buttons; use button-group"],"composesWith":["field","button","kbd"],"dependencies":["class-variance-authority"],"registryDependencies":["shadcn:utils"],"examples":["input-group-demo","input-group-states"],"states":[],"preview":"https://ui.ballmac.com/preview/input-group-demo"},{"name":"input-otp","kind":"component","type":"registry:ui","title":"Input OTP","description":"A one-time-code field with grouped slots, separator, caret, paste and autofill support, invalid state and reduced-motion-safe animation, on a single real input.","category":"forms","tier":"free","tags":["otp","code","verification","input"],"version":"1.0.0","updated":"2026-09-30","url":"https://ui.ballmac.com/components/input-otp","registryUrl":"https://ui.ballmac.com/r/input-otp.json","install":"npx shadcn@latest add @ballmac/input-otp","summary":" with InputOTPGroup, InputOTPSlot index and InputOTPSeparator. onComplete fires when every slot is filled.","whenToUse":["Two-step sign-in and email verification","PIN entry"],"whenNotToUse":["Free-form text codes; use input","Long passwords; use password-input"],"composesWith":["field","label"],"dependencies":["input-otp@^1","lucide-react"],"registryDependencies":["shadcn:utils"],"examples":["input-otp-demo","input-otp-states"],"states":[],"preview":"https://ui.ballmac.com/preview/input-otp-demo"},{"name":"input","kind":"component","type":"registry:ui","title":"Input","description":"A text input in three heights that match Button, plus InputGroup and InputGroupAddon for leading or trailing icons, units and domains.","category":"primitives","tier":"free","tags":["input","text-field","form","search"],"version":"1.0.1","updated":"2026-10-11","url":"https://ui.ballmac.com/components/input","registryUrl":"https://ui.ballmac.com/r/input.json","install":"npx shadcn@latest add @ballmac/input","summary":"Single-line text field. Use size to match neighbouring buttons, wrap in InputGroup with InputGroupAddon (align start or end) for icons or text like \".com\", and set aria-invalid for error styling.","whenToUse":["Any single-line form field (email, name, URL, search)","Search boxes with a leading icon","Fields with a fixed unit or domain suffix"],"whenNotToUse":["Multi-line text (use textarea)","Choosing from a fixed list (use select)","On/off settings (use switch or checkbox)"],"composesWith":["label","button","kbd","tooltip","dialog"],"dependencies":["class-variance-authority"],"registryDependencies":["shadcn:utils"],"examples":["input-demo","input-with-icon","input-invalid"],"states":[],"preview":"https://ui.ballmac.com/preview/input-demo"},{"name":"install-tabs","kind":"component","type":"registry:ui","title":"Install Tabs","description":"Package-manager tabs for a CLI command (pnpm, npm, yarn, bun) with a copy button. Remembers the reader's choice and keeps every instance on the page in sync.","category":"developer","tier":"free","tags":["install","cli","npm","pnpm","yarn","bun","tabs","copy","docs"],"version":"1.0.0","updated":"2026-09-28","url":"https://ui.ballmac.com/components/install-tabs","registryUrl":"https://ui.ballmac.com/r/install-tabs.json","install":"npx shadcn@latest add @ballmac/install-tabs","summary":" renders pnpm dlx / npx / yarn dlx / bunx --bun variants. Use commands={{ npm: 'npm i x', pnpm: 'pnpm add x' }} for install (not run) commands.","whenToUse":["Install or 'run this CLI' instructions in docs and READMEs","Any page with several install snippets where the reader's package manager should stick"],"whenNotToUse":["A command with its output (use terminal)","Multi-line source code (use code-block)"],"composesWith":["code-block","terminal"],"dependencies":["lucide-react","radix-ui"],"registryDependencies":["shadcn:utils","i18n"],"examples":["install-tabs-demo"],"states":[],"preview":"https://ui.ballmac.com/preview/install-tabs-demo"},{"name":"interactive-grid","kind":"component","type":"registry:ui","title":"Interactive Grid","description":"A canvas grid whose cells light up under the pointer and fade out behind it, leaving a glowing trail, drawn only while something is moving and listening on its parent so content above never blocks it.","category":"backgrounds","tier":"free","tags":["grid","canvas","hover","trail","background"],"version":"1.0.0","updated":"2026-10-01","url":"https://ui.ballmac.com/components/interactive-grid","registryUrl":"https://ui.ballmac.com/r/interactive-grid.json","install":"npx shadcn@latest add @ballmac/interactive-grid","summary":" inside a relative parent. Colors are CSS variable names. It listens to the parent, repaints on theme changes and stops its frame loop when idle.","whenToUse":["Heroes and empty states that should respond to the mouse","Playful 404 pages"],"whenNotToUse":["Touch-only audiences (there is no hover)","Large amounts of text over the grid"],"composesWith":["grid-pattern","flickering-grid","particles"],"dependencies":[],"registryDependencies":["shadcn:utils","color"],"examples":["interactive-grid-demo","interactive-grid-colors"],"states":[],"preview":"https://ui.ballmac.com/preview/interactive-grid-demo"},{"name":"invite-members","kind":"component","type":"registry:ui","title":"Invite Members","description":"Invite teammates by email: type or paste addresses into chips, flag invalid or duplicate ones with an explanation, pick a role, send, and manage pending invitations.","category":"saas","tier":"free","tags":["invite","team","email","roles"],"version":"1.0.0","updated":"2026-09-30","url":"https://ui.ballmac.com/components/invite-members","registryUrl":"https://ui.ballmac.com/r/invite-members.json","install":"npx shadcn@latest add @ballmac/invite-members","summary":"roles[], onInvite(invitations), pending[], onResend/onRevoke, existing[]. Addresses split on comma, space, semicolon or Enter and validate as you go.","whenToUse":["Team and workspace settings","Onboarding step for inviting colleagues"],"whenNotToUse":["Searching existing users; use combobox","Single email field; use input"],"composesWith":["team-switcher","settings-panel","avatar"],"dependencies":["motion@^12","lucide-react"],"registryDependencies":["shadcn:utils","motion-presets","i18n"],"examples":["invite-members-demo","invite-members-states"],"states":[],"preview":"https://ui.ballmac.com/preview/invite-members-demo"},{"name":"item","kind":"component","type":"registry:ui","title":"Item","description":"A flexible list row with media, title, description and actions, in outline, muted and plain variants, that can also render as a link.","category":"data-display","tier":"free","tags":["list","row","media","layout"],"version":"1.0.0","updated":"2026-09-30","url":"https://ui.ballmac.com/components/item","registryUrl":"https://ui.ballmac.com/r/item.json","install":"npx shadcn@latest add @ballmac/item","summary":"Compose rows from ItemMedia, ItemContent, ItemTitle, ItemDescription and ItemActions. asChild styles a link or button as a whole-row target.","whenToUse":["Settings, connected accounts and file lists","Rows with an icon or avatar, text and an action"],"whenNotToUse":["Tabular data with columns; use table","Long card layouts; use card"],"composesWith":["badge","avatar","button"],"dependencies":["radix-ui","class-variance-authority"],"registryDependencies":["shadcn:utils"],"examples":["item-demo","item-states"],"states":[],"preview":"https://ui.ballmac.com/preview/item-demo"},{"name":"json-viewer","kind":"component","type":"registry:ui","title":"JSON Viewer","description":"A collapsible JSON inspector with compact type styling and keyboard-operable branches.","category":"data-display","tier":"free","tags":["json","data","developer"],"version":"1.0.0","updated":"2026-09-30","url":"https://ui.ballmac.com/components/json-viewer","registryUrl":"https://ui.ballmac.com/r/json-viewer.json","install":"npx shadcn@latest add @ballmac/json-viewer","summary":"A collapsible JSON inspector with compact type styling and keyboard-operable branches.","whenToUse":["Inspect nested API responses or configuration"],"whenNotToUse":["Use Code Block for unstructured text"],"composesWith":["code-block"],"dependencies":["lucide-react"],"registryDependencies":["shadcn:utils","i18n"],"examples":["json-viewer-demo","json-viewer-states"],"states":[],"preview":"https://ui.ballmac.com/preview/json-viewer-demo"},{"name":"kanban-board","kind":"component","type":"registry:ui","title":"Kanban Board","description":"A responsive task board with pointer drag and keyboard movement between columns.","category":"data-display","tier":"free","tags":["kanban","tasks","board"],"version":"1.0.0","updated":"2026-09-30","url":"https://ui.ballmac.com/components/kanban-board","registryUrl":"https://ui.ballmac.com/r/kanban-board.json","install":"npx shadcn@latest add @ballmac/kanban-board","summary":"A responsive task board with pointer drag and keyboard movement between columns.","whenToUse":["Organize tasks across workflow stages"],"whenNotToUse":["Use a table for dense sortable records"],"composesWith":["card"],"dependencies":["lucide-react"],"registryDependencies":["shadcn:utils","i18n","direction"],"examples":["kanban-board-demo","kanban-board-states"],"states":[],"preview":"https://ui.ballmac.com/preview/kanban-board-demo"},{"name":"kbd","kind":"component","type":"registry:ui","title":"Kbd","description":"Keyboard key and shortcut display built on the semantic element, in three sizes, with KbdGroup for combinations like ⌘ ⇧ K. Adapts inside tooltips.","category":"primitives","tier":"free","tags":["kbd","keyboard","shortcut","hotkey"],"version":"1.0.0","updated":"2026-09-28","url":"https://ui.ballmac.com/components/kbd","registryUrl":"https://ui.ballmac.com/r/kbd.json","install":"npx shadcn@latest add @ballmac/kbd","summary":"Displays a key or shortcut. Use Kbd for each key and KbdGroup for keys pressed together; it restyles itself for the dark tooltip surface automatically.","whenToUse":["Shortcut hints in menus, tooltips and command palettes","Documentation of keyboard controls","Search inputs that show a ⌘ K hint"],"whenNotToUse":["Inline code or commands (use code)","Buttons that trigger the shortcut (use button)"],"composesWith":["tooltip","button","input"],"dependencies":["class-variance-authority"],"registryDependencies":["shadcn:utils"],"examples":["kbd-demo"],"states":[],"preview":"https://ui.ballmac.com/preview/kbd-demo"},{"name":"keyboard-shortcuts","kind":"component","type":"registry:ui","title":"Keyboard Shortcuts","description":"A searchable shortcut cheat sheet, inline or in a dialog opened by pressing ?, with Command or Ctrl keys chosen for the viewer's platform and spoken key names.","category":"developer","tier":"free","tags":["keyboard","shortcuts","hotkeys","help","dialog"],"version":"1.0.0","updated":"2026-10-01","url":"https://ui.ballmac.com/components/keyboard-shortcuts","registryUrl":"https://ui.ballmac.com/r/keyboard-shortcuts.json","install":"npx shadcn@latest add @ballmac/keyboard-shortcuts","summary":"groups is [{ title, shortcuts: [{ label, keys, sequence?, description? }] }]. Use 'Mod' for Cmd on Mac and Ctrl elsewhere. opens from anywhere outside a text field. platform='auto' corrects after hydration.","whenToUse":["A help overlay for apps with many shortcuts","Docs pages that list hotkeys"],"whenNotToUse":["A single hint beside a button (shortcut-hint)","Binding the shortcuts themselves; this only displays them"],"composesWith":["kbd","shortcut-hint","command-bar","dialog"],"dependencies":["lucide-react"],"registryDependencies":["shadcn:utils","dialog","kbd","i18n"],"examples":["keyboard-shortcuts-demo","keyboard-shortcuts-dialog"],"states":[],"preview":"https://ui.ballmac.com/preview/keyboard-shortcuts-demo"},{"name":"kpi-row","kind":"component","type":"registry:ui","title":"KPI Row","description":"A compact, semantic row of key metrics that adapts from one to four columns.","category":"data-display","tier":"free","tags":["metric","dashboard","summary"],"version":"1.0.0","updated":"2026-09-30","url":"https://ui.ballmac.com/components/kpi-row","registryUrl":"https://ui.ballmac.com/r/kpi-row.json","install":"npx shadcn@latest add @ballmac/kpi-row","summary":"A compact, semantic row of key metrics that adapts from one to four columns.","whenToUse":["Show several related metrics together"],"whenNotToUse":["Use Stat Card when each metric needs more context"],"composesWith":["stat-card"],"dependencies":[],"registryDependencies":["shadcn:utils"],"examples":["kpi-row-demo","kpi-row-states"],"states":[],"preview":"https://ui.ballmac.com/preview/kpi-row-demo"},{"name":"label","kind":"component","type":"registry:ui","title":"Label","description":"An accessible form label built on Radix Label that dims itself when the paired peer control is disabled and never selects text on double-click.","category":"primitives","tier":"free","tags":["label","form","radix"],"version":"1.0.0","updated":"2026-09-28","url":"https://ui.ballmac.com/components/label","registryUrl":"https://ui.ballmac.com/r/label.json","install":"npx shadcn@latest add @ballmac/label","summary":"Text label for a form control. Pair with htmlFor/id; put the control before it with className=\"peer\" (Checkbox and Switch already are) to get disabled styling.","whenToUse":["Naming inputs, textareas, selects, checkboxes and switches","Clickable text next to a checkbox or switch"],"whenNotToUse":["Headings or section titles (use a heading element)","Helper or error text under a field (use a p with text-muted-foreground or text-destructive)"],"composesWith":["input","textarea","checkbox","switch","select"],"dependencies":["radix-ui"],"registryDependencies":["shadcn:utils"],"examples":["label-demo"],"states":[],"preview":"https://ui.ballmac.com/preview/label-demo"},{"name":"laptop-frame","kind":"component","type":"registry:ui","title":"Laptop Frame","description":"A notched aluminium laptop drawn in CSS that scales with its container. Renders children, an image or a video as the screen, and can open its lid when it scrolls into view.","category":"devices","tier":"free","tags":["mockup","device","laptop","macbook","screenshot","hero","3d","scroll"],"version":"1.0.0","updated":"2026-09-29","url":"https://ui.ballmac.com/components/laptop-frame","registryUrl":"https://ui.ballmac.com/r/laptop-frame.json","install":"npx shadcn@latest add @ballmac/laptop-frame","summary":"Wrap a product screen in : children become the display. Pass screenWidth (e.g. 1280) to lay the content out at a desktop resolution and scale it down to fit; openAnimation=\"in-view\" or \"scroll\" swings the lid open.","whenToUse":["Landing-page heroes that show a desktop or web app in context","Feature sections with a live React screen instead of a static screenshot","Scroll-driven product reveals (openAnimation=\"scroll\")"],"whenNotToUse":["Showing a website with its URL and browser chrome (use browser-frame)","Mobile app screens (use phone-frame)"],"composesWith":["browser-frame","phone-frame"],"dependencies":["motion@^12"],"registryDependencies":["shadcn:utils","media"],"examples":["laptop-frame-demo","laptop-frame-scroll"],"states":[],"preview":"https://ui.ballmac.com/preview/laptop-frame-demo"},{"name":"launchpad","kind":"component","type":"registry:ui","title":"Launchpad","description":"The macOS Launchpad: a frosted full-area overlay with search, pages of app icons sized to fit, page dots, wheel and key paging, arrow-key focus across pages and Escape to close.","category":"macos","tier":"free","tags":["launchpad","apps","grid","overlay","macos"],"version":"1.0.0","updated":"2026-10-01","url":"https://ui.ballmac.com/components/launchpad","registryUrl":"https://ui.ballmac.com/r/launchpad.json","install":"npx shadcn@latest add @ballmac/launchpad","summary":". It fills its positioned parent. Pages, rows and columns are computed from the available size.","whenToUse":["Mac desktop demos","App launchers in dashboards"],"whenNotToUse":["Command palettes (command)","Navigation menus"],"composesWith":["dock","mac-icons","spotlight-search"],"dependencies":["motion@^12","lucide-react"],"registryDependencies":["shadcn:utils","i18n","direction"],"examples":["launchpad-demo","launchpad-many"],"states":[],"preview":"https://ui.ballmac.com/preview/launchpad-demo"},{"name":"lens","kind":"component","type":"registry:ui","title":"Lens","description":"A magnifying lens that follows the pointer over an image or any content, moves with the arrow keys when focused, hides on Escape and keeps the copy inside it out of the accessibility tree.","category":"motion","tier":"free","tags":["zoom","magnifier","image","hover","lens"],"version":"1.0.0","updated":"2026-10-01","url":"https://ui.ballmac.com/components/lens","registryUrl":"https://ui.ballmac.com/r/lens.json","install":"npx shadcn@latest add @ballmac/lens","summary":"{image or content}. Works with any child. The magnified copy is inert and aria-hidden. Touch pointers are ignored so scrolling is never blocked.","whenToUse":["Product photos and maps","Inspecting fine detail in diagrams or charts"],"whenNotToUse":["Full-screen image viewing (use a dialog)"],"composesWith":["card","tilt-card"],"dependencies":["motion@^12"],"registryDependencies":["shadcn:utils","i18n"],"examples":["lens-demo","lens-text"],"states":[],"preview":"https://ui.ballmac.com/preview/lens-demo"},{"name":"light-rays","kind":"component","type":"registry:ui","title":"Light Rays","description":"Soft beams of theme-colored light fanning down from the top edge, each swaying and breathing at its own pace, deterministic so the server and browser match.","category":"backgrounds","tier":"free","tags":["light","rays","glow","background","hero"],"version":"1.0.1","updated":"2026-10-11","url":"https://ui.ballmac.com/components/light-rays","registryUrl":"https://ui.ballmac.com/r/light-rays.json","install":"npx shadcn@latest add @ballmac/light-rays","summary":" inside a relative, overflow-hidden parent. Tone is a theme token, so it follows any palette.","whenToUse":["Hero and pricing sections that want warmth","Behind modals and announcement bars"],"whenNotToUse":["Light backgrounds with dark text at high intensity"],"composesWith":["aurora-background","retro-grid","beams-background"],"dependencies":["motion@^12"],"registryDependencies":["shadcn:utils","motion-presets"],"examples":["light-rays-demo","light-rays-tones"],"states":[],"preview":"https://ui.ballmac.com/preview/light-rays-demo"},{"name":"loading-dots","kind":"component","type":"registry:ui","title":"Loading Dots","description":"A compact loading status with staggered token-colored dots that stop for reduced motion.","category":"feedback","tier":"free","tags":["loading","status","animation"],"version":"1.0.0","updated":"2026-09-30","url":"https://ui.ballmac.com/components/loading-dots","registryUrl":"https://ui.ballmac.com/r/loading-dots.json","install":"npx shadcn@latest add @ballmac/loading-dots","summary":"A compact loading status with staggered token-colored dots that stop for reduced motion.","whenToUse":["Indicate short pending work","Pair a compact loader with a button label"],"whenNotToUse":["Use skeleton for a full content placeholder"],"composesWith":["spinner","button"],"dependencies":[],"registryDependencies":["shadcn:utils","i18n"],"examples":["loading-dots-demo","loading-dots-states"],"states":[],"preview":"https://ui.ballmac.com/preview/loading-dots-demo"},{"name":"lock-screen","kind":"component","type":"registry:ui","title":"Lock Screen","description":"A full-screen lock screen in two flavors: macOS (live clock, avatar, password field that shakes when wrong) and iOS (clock, notification stack, flashlight and camera, swipe up to unlock). Hydration-safe clock.","category":"macos","tier":"free","tags":["lock-screen","login","macos","ios","clock","password","wallpaper"],"version":"1.0.1","updated":"2026-10-11","url":"https://ui.ballmac.com/components/lock-screen","registryUrl":"https://ui.ballmac.com/r/lock-screen.json","install":"npx shadcn@latest add @ballmac/lock-screen","summary":" fills its positioned parent until unlocked. variant=\"ios\" takes notifications as children and unlocks by swiping up or pressing the button. Control with locked / onLockedChange.","whenToUse":["Mac or phone UI demos with a login moment","Idle or session-timeout screens"],"whenNotToUse":["Real authentication: the password prop is for demos, check credentials on a server"],"composesWith":["phone-frame","notification-stack","mac-window","menu-bar"],"dependencies":["motion@^12","lucide-react"],"registryDependencies":["shadcn:utils","motion-presets","i18n","media","media-image"],"examples":["lock-screen-demo","lock-screen-ios"],"states":[],"preview":"https://ui.ballmac.com/preview/lock-screen-demo"},{"name":"log-stream","kind":"component","type":"registry:ui","title":"Log Stream","description":"A live log viewer with level filters and counts, search with highlighted matches, wrap, pause with a new-lines counter, follow-the-tail scrolling and copy.","category":"developer","tier":"free","tags":["logs","stream","console","debug","tail"],"version":"1.0.0","updated":"2026-10-01","url":"https://ui.ballmac.com/components/log-stream","registryUrl":"https://ui.ballmac.com/r/log-stream.json","install":"npx shadcn@latest add @ballmac/log-stream","summary":"lines is [{ id, time, level, message, source? }], oldest first; append as lines arrive. Follows the tail while you are at the bottom, shows 'N new lines' when paused or scrolled up. maxLines limits what is rendered.","whenToUse":["Deploy, build and server logs","Streaming output from background jobs"],"whenNotToUse":["A terminal with input (terminal)","Millions of lines (use a virtualized list)"],"composesWith":["terminal","status-dot","copy-button"],"dependencies":["lucide-react"],"registryDependencies":["shadcn:utils","copy-button","i18n"],"examples":["log-stream-demo","log-stream-static"],"states":[],"preview":"https://ui.ballmac.com/preview/log-stream-demo"},{"name":"mac-context-menu","kind":"component","type":"registry:ui","title":"Mac Context Menu","description":"A right-click menu styled like macOS: frosted panel, accent-color highlight, key equivalents, checkmarks, submenus and a red destructive item, on Radix for full keyboard support.","category":"macos","tier":"free","tags":["context menu","macos","right click","menu","shortcuts"],"version":"1.0.0","updated":"2026-10-01","url":"https://ui.ballmac.com/components/mac-context-menu","registryUrl":"https://ui.ballmac.com/r/mac-context-menu.json","install":"npx shadcn@latest add @ballmac/mac-context-menu","summary":"Compose with MacContextMenuItem (icon, shortcut, destructive), CheckboxItem, RadioGroup/RadioItem, Label, Separator and Sub parts. Shift+F10 and long-press also open it.","whenToUse":["Desktop-like apps and file managers","Anywhere you want the macOS look"],"whenNotToUse":["Standard product UI (context-menu)","Click-opened menus (dropdown-menu)"],"composesWith":["finder-window","desktop-icons","context-menu"],"dependencies":["radix-ui","lucide-react"],"registryDependencies":["shadcn:utils"],"examples":["mac-context-menu-demo","mac-context-menu-view"],"states":[],"preview":"https://ui.ballmac.com/preview/mac-context-menu-demo"},{"name":"mac-icons","kind":"component","type":"registry:ui","title":"Mac Icons","description":"Resolution-independent macOS-style icons drawn in SVG and CSS: folders, documents with extension badges, drives and gradient app icons in eight theme-aware colors.","category":"macos","tier":"free","tags":["icons","folder","file","app icon","macos"],"version":"1.0.0","updated":"2026-10-01","url":"https://ui.ballmac.com/components/mac-icons","registryUrl":"https://ui.ballmac.com/r/mac-icons.json","install":"npx shadcn@latest add @ballmac/mac-icons","summary":", , , {glyph}. tone is blue | teal | green | amber | orange | red | purple | graphite. All are decorative (aria-hidden): put the name in text next to them.","whenToUse":["Desktop, Finder and Launchpad recreations","File lists that want recognisable macOS icons"],"whenNotToUse":["Small UI glyphs (use lucide-react icons)"],"composesWith":["finder-window","desktop-icons","launchpad","dock"],"dependencies":[],"registryDependencies":["shadcn:utils"],"examples":["mac-icons-demo","mac-icons-tones"],"states":[],"preview":"https://ui.ballmac.com/preview/mac-icons-demo"},{"name":"mac-window","kind":"component","type":"registry:ui","title":"Mac Window","description":"macOS window chrome: traffic lights whose glyphs appear on hover, a centered title or unified toolbar, an optional translucent sidebar with vibrancy, and active and inactive appearances.","category":"macos","tier":"free","tags":["window","macos","traffic lights","chrome","mockup","sidebar","frame"],"version":"1.0.0","updated":"2026-09-29","url":"https://ui.ballmac.com/components/mac-window","registryUrl":"https://ui.ballmac.com/r/mac-window.json","install":"npx shadcn@latest add @ballmac/mac-window","summary":"Frame content as a Mac app window. Simple: …. Sidebar layout: rows…toolbar buttons. Size the window with className.","whenToUse":["Product screenshots and mockups of a Mac app on a landing page","Framing a code sample, terminal session or settings panel so it reads as desktop software","Interactive app demos where the sidebar and toolbar actually work"],"whenNotToUse":["Modal dialogs in a web app (use dialog)","Browser mockups; this draws native window chrome, not an address bar"],"composesWith":["dock","menu-bar","segmented-control"],"dependencies":[],"registryDependencies":["shadcn:utils","i18n"],"examples":["mac-window-demo","mac-window-stack"],"states":[],"preview":"https://ui.ballmac.com/preview/mac-window-demo"},{"name":"magic-card","kind":"component","type":"registry:ui","title":"Magic Card","description":"A card with a two-color light that follows the pointer along its border, with an optional soft glow inside, driven by CSS variables so moving never re-renders, and a steady light on keyboard focus.","category":"motion","tier":"free","tags":["card","hover","gradient","border","pointer"],"version":"1.0.0","updated":"2026-10-01","url":"https://ui.ballmac.com/components/magic-card","registryUrl":"https://ui.ballmac.com/r/magic-card.json","install":"npx shadcn@latest add @ballmac/magic-card","summary":"content. from and to are chart tokens. Use spotlight-card for a single soft glow and this for a colored border light.","whenToUse":["Feature and pricing cards on dark or light pages","Any card grid that should feel responsive to the pointer"],"whenNotToUse":["Dense data UI","Cards that are not interactive"],"composesWith":["spotlight-card","tilt-card","bento-grid"],"dependencies":["motion@^12"],"registryDependencies":["shadcn:utils"],"examples":["magic-card-demo","magic-card-colors"],"states":[],"preview":"https://ui.ballmac.com/preview/magic-card-demo"},{"name":"magnetic-button","kind":"component","type":"registry:ui","title":"Magnetic Button","description":"The Ballmac Button with a magnetic pull: it drifts toward a nearby mouse pointer on a spring, and its label moves a little further for depth. Takes every Button prop.","category":"motion","tier":"free","tags":["button","cta","hover","spring","pointer","motion"],"version":"1.0.0","updated":"2026-09-28","url":"https://ui.ballmac.com/components/magnetic-button","registryUrl":"https://ui.ballmac.com/r/magnetic-button.json","install":"npx shadcn@latest add @ballmac/magnetic-button","summary":"Use like Button (variant, size, shape, loading, onClick…). The pull only reacts to a mouse, stops while disabled or loading, and is off under reduced motion, where it is a plain Button.","whenToUse":["The single primary call to action in a hero or pricing section","A playful secondary action on a marketing page"],"whenNotToUse":["Forms, toolbars and dense UI (use button)","Several buttons side by side; one magnetic button per view keeps it meaningful","Rendering a link (not supported; use an
with buttonVariants instead)"],"composesWith":["button","border-beam"],"dependencies":["motion@^12"],"registryDependencies":["shadcn:utils","button","motion-presets"],"examples":["magnetic-button-demo"],"states":[],"preview":"https://ui.ballmac.com/preview/magnetic-button-demo"},{"name":"marquee","kind":"component","type":"registry:ui","title":"Marquee","description":"An endless horizontal or vertical scroller for logo rows and testimonials. Speed is in pixels per second, it pauses on hover and focus, and it fills any width.","category":"motion","tier":"free","tags":["animation","scroller","logos","testimonials","ticker","motion"],"version":"1.0.0","updated":"2026-09-28","url":"https://ui.ballmac.com/components/marquee","registryUrl":"https://ui.ballmac.com/r/marquee.json","install":"npx shadcn@latest add @ballmac/marquee","summary":"Put the items directly inside ; it measures one copy, clones as many as the viewport needs (clones are aria-hidden and inert) and loops them with a GPU transform. Under reduced motion it renders a single copy in a scrollable row.","whenToUse":["A row of customer or partner logos under a hero","A wall of short testimonials (vertical, several columns side by side)","A ticker of changelog items, integrations or stats"],"whenNotToUse":["Content people must read or act on in full (use a grid or carousel with controls)","Critical navigation or calls to action"],"composesWith":["spotlight-card","badge","avatar"],"dependencies":["motion@^12"],"registryDependencies":["shadcn:utils"],"examples":["marquee-demo","marquee-vertical"],"states":[],"preview":"https://ui.ballmac.com/preview/marquee-demo"},{"name":"masonry-grid","kind":"component","type":"registry:ui","title":"Masonry Grid","description":"A gap-free multi-column layout for tiles of different heights, built on CSS columns so it never shifts on load, with responsive column counts and optional reveal.","category":"layout","tier":"free","tags":["masonry","grid","gallery","columns"],"version":"1.0.0","updated":"2026-09-30","url":"https://ui.ballmac.com/components/masonry-grid","registryUrl":"https://ui.ballmac.com/r/masonry-grid.json","install":"npx shadcn@latest add @ballmac/masonry-grid","summary":"…. DOM order is reading order: down the first column, then the next.","whenToUse":["Galleries, portfolios and boards","Testimonials or notes of uneven length"],"whenNotToUse":["Rows that must line up across columns; use CSS grid","Sortable boards; use kanban-board"],"composesWith":["card","bento-grid"],"dependencies":["motion@^12"],"registryDependencies":["shadcn:utils","motion-presets"],"examples":["masonry-grid-demo","masonry-grid-states"],"states":[],"preview":"https://ui.ballmac.com/preview/masonry-grid-demo"},{"name":"match-highlight","kind":"component","type":"registry:ui","title":"Match Highlight","description":"Text with the words of a search marked, as search results show them: real mark elements in a theme tint that stays readable in light and dark, plus helpers that split a query and test whether text matches it.","category":"text","tier":"free","tags":["search","highlight","mark","results","query","autocomplete","snippet"],"version":"1.0.0","updated":"2026-10-17","url":"https://ui.ballmac.com/components/match-highlight","registryUrl":"https://ui.ballmac.com/r/match-highlight.json","install":"npx shadcn@latest add @ballmac/match-highlight","summary":" marks every occurrence of every word of the query, ignoring case. queryTokens(query) gives the words, matchesAll(text, query) tests that all of them occur, countMatches(text, query) counts occurrences for ranking. No \"use client\": it works in server components.","whenToUse":["Search results, suggestions and autocomplete rows","Showing why an item matched a filter"],"whenNotToUse":["Syntax highlighting of code (use code-block)","A hand-drawn emphasis mark on a phrase (use highlighter)"],"composesWith":["search-field","command","help-1","search-1"],"dependencies":[],"registryDependencies":["shadcn:utils"],"examples":["match-highlight-demo","match-highlight-live"],"states":[],"statesNone":"A display of text: nothing to load, submit or fail.","preview":"https://ui.ballmac.com/preview/match-highlight-demo"},{"name":"media","kind":"component","type":"registry:ui","title":"Media","description":"A picture slot: reserves the space, lazy-loads, takes a URL, an image with required alt text and a dark-mode file, or your own element, and falls back to artwork if there is no image or it fails.","category":"primitives","tier":"free","tags":["image","picture","slot","screenshot","photo","alt text","aspect ratio","dark mode"],"version":"1.0.1","updated":"2026-10-11","url":"https://ui.ballmac.com/components/media","registryUrl":"https://ui.ballmac.com/r/media.json","install":"npx shadcn@latest add @ballmac/media","summary":"Pass media as a URL (with alt), an object { src, alt, srcDark? }, or any element such as a next/image. aspect reserves the box (video, photo, square, wide, portrait or '3/2'); fit is cover | contain | fill; priority loads an above-the-fold image eagerly. fallback shows when there is no media or the file fails.","whenToUse":["Any place a product screenshot, photo, cover or avatar goes","Blocks and templates that ship with generated artwork but should accept the buyer's own image"],"whenNotToUse":["Icons (use an icon component)","Animated or interactive content that is not an image: pass it as an element"],"composesWith":["hero-1","features-5","blog-1"],"dependencies":[],"registryDependencies":["shadcn:utils","media-image"],"examples":["media-demo","media-dark"],"states":[],"preview":"https://ui.ballmac.com/preview/media-demo"},{"name":"mega-menu","kind":"component","type":"registry:ui","title":"Mega Menu","description":"A data-driven header menu with wide panels of grouped, described links, an optional featured card, and an accordion list for small screens.","category":"navigation","tier":"free","tags":["navigation","dropdown","header","radix"],"version":"1.0.0","updated":"2026-09-30","url":"https://ui.ballmac.com/components/mega-menu","registryUrl":"https://ui.ballmac.com/r/mega-menu.json","install":"npx shadcn@latest add @ballmac/mega-menu","summary":"Pass items: a plain link ({label, href}) or a panel ({label, columns, featured}). MegaMenuMobileList renders the same data for the mobile menu.","whenToUse":["Sites with many products or solutions","Headers that need descriptions beside links"],"whenNotToUse":["A handful of plain links; use navbar","Application commands; use menubar"],"composesWith":["navbar","navigation-menu"],"dependencies":["lucide-react"],"registryDependencies":["shadcn:utils","navigation-menu","i18n"],"examples":["mega-menu-demo","mega-menu-states"],"states":[],"preview":"https://ui.ballmac.com/preview/mega-menu-demo"},{"name":"mention-input","kind":"component","type":"registry:ui","title":"Mention Input","description":"A text field where typing @ or # opens a list of people, channels or tags: highlighted mentions that know their id, async search, arrow-key choosing, whole-mention backspace and a combobox pattern for screen readers.","category":"forms","tier":"free","tags":["mention","at-mention","autocomplete","tags","textarea","comments","combobox"],"version":"1.0.0","updated":"2026-10-19","url":"https://ui.ballmac.com/components/mention-input","registryUrl":"https://ui.ballmac.com/r/mention-input.json","install":"npx shadcn@latest add @ballmac/mention-input","summary":"Hold { text, mentions } in state: . options is an array or a function (query, signal) returning options or a promise. mentionsToMarkup and parseMentionMarkup convert to a string.","whenToUse":["Comments, chat and ticket replies where people are mentioned","Tag or channel pickers inside a sentence","Anywhere you need to know which entity a name in the text referred to"],"whenNotToUse":["Formatting text as well as mentions; use rich-text-editor","Choosing one value from a list; use combobox","Plain multi-line text; use textarea"],"composesWith":["textarea","avatar","rich-text-editor"],"dependencies":["lucide-react"],"registryDependencies":["shadcn:utils","i18n","direction"],"examples":["mention-input-demo","mention-input-async","mention-input-single","mention-input-invalid"],"states":[],"statesNone":"Nothing loads on its own: an async source shows a Searching row in the list while it answers, and a No matches row when it finds nothing.","preview":"https://ui.ballmac.com/preview/mention-input-demo"},{"name":"menu-bar","kind":"component","type":"registry:ui","title":"Menu Bar","description":"A translucent macOS menu bar on Radix Menubar: a bold app menu, menus with key equivalents, submenus and checkmarks, a status area with icon buttons and a hydration-safe live clock.","category":"macos","tier":"free","tags":["menubar","menu","macos","navigation","keyboard shortcuts","clock","status bar"],"version":"1.0.0","updated":"2026-09-29","url":"https://ui.ballmac.com/components/menu-bar","registryUrl":"https://ui.ballmac.com/r/menu-bar.json","install":"npx shadcn@latest add @ballmac/menu-bar","summary":" holds items (Radix Menubar parts with Mac styling) followed by with icon buttons and . Use variant=\"app\" on the app-name trigger and for key equivalents.","whenToUse":["A Mac desktop mockup or product hero where the app's menus should really open","A web app that wants desktop-style menus with keyboard navigation (File, Edit, View)","Status bars that pair a few icon buttons with a clock"],"whenNotToUse":["Site navigation for a marketing page (use a header with links)","A single action menu on a button (use a dropdown menu)"],"composesWith":["mac-window","dock","dynamic-island"],"dependencies":["radix-ui","lucide-react"],"registryDependencies":["shadcn:utils"],"examples":["menu-bar-demo"],"states":[],"preview":"https://ui.ballmac.com/preview/menu-bar-demo"},{"name":"menubar","kind":"component","type":"registry:ui","title":"Menubar","description":"A horizontal application menu bar with roving focus across menus, submenus, shortcuts, checkbox and radio items, built on Radix.","category":"navigation","tier":"free","tags":["menu","application","desktop","radix"],"version":"1.0.1","updated":"2026-10-11","url":"https://ui.ballmac.com/components/menubar","registryUrl":"https://ui.ballmac.com/r/menubar.json","install":"npx shadcn@latest add @ballmac/menubar","summary":"A File / Edit / View style bar. Left and Right move between menus, Down opens one, and hovering across open menus switches them.","whenToUse":["Editors, dashboards and tools with many commands","Desktop-style web apps"],"whenNotToUse":["Website navigation with links; use navigation-menu","The macOS system menu bar mockup; use menu-bar"],"composesWith":["kbd","dropdown-menu"],"dependencies":["radix-ui","lucide-react"],"registryDependencies":["shadcn:utils","direction"],"examples":["menubar-demo","menubar-states"],"states":[],"preview":"https://ui.ballmac.com/preview/menubar-demo"},{"name":"meteors","kind":"component","type":"registry:ui","title":"Meteors","description":"Thin meteors with glowing heads and fading tails streak across a container at a set angle. Randomized after mount (hydration-safe), paused off-screen, hidden under reduced motion.","category":"backgrounds","tier":"free","tags":["meteors","shooting stars","background","card","decorative"],"version":"1.0.0","updated":"2026-09-29","url":"https://ui.ballmac.com/components/meteors","registryUrl":"https://ui.ballmac.com/r/meteors.json","install":"npx shadcn@latest add @ballmac/meteors","summary":"Put inside a relative, overflow-hidden card or section (it is absolute inset-0, aria-hidden, pointer-events-none) and lift content with relative z-10. Meteor positions are generated on the client after mount, so the server renders an empty layer.","whenToUse":["A launch, release or milestone card that should feel special","Dark hero sections or CTA panels that need a hint of motion"],"whenNotToUse":["Dense UI or data tables","Communicating anything; it is decorative and hidden under reduced motion"],"composesWith":["spotlight-card","badge","button"],"dependencies":[],"registryDependencies":["shadcn:utils"],"examples":["meteors-demo","meteors-colored"],"states":[],"preview":"https://ui.ballmac.com/preview/meteors-demo"},{"name":"model-picker","kind":"component","type":"registry:ui","title":"Model Picker","description":"A searchable model selector grouped by provider, with capability icons, locked plans and a detail pane that follows the highlighted model with context window, cost and abilities.","category":"ai","tier":"free","tags":["ai","model","select","combobox","llm","picker"],"version":"1.0.0","updated":"2026-09-30","url":"https://ui.ballmac.com/components/model-picker","registryUrl":"https://ui.ballmac.com/r/model-picker.json","install":"npx shadcn@latest add @ballmac/model-picker","summary":"models is an array of { id, name, provider?, description?, capabilities?, contextWindow?, cost?, isNew?, locked? }. value/onValueChange or defaultValue. Locked models call onLockedSelect. variant default | compact.","whenToUse":["Choosing the model for a chat or an agent","Any picker where options have facts worth comparing"],"whenNotToUse":["A plain short list of choices; use select","Settings with many fields; use settings-panel"],"composesWith":["prompt-input","ai-chat","token-meter"],"dependencies":["lucide-react"],"registryDependencies":["shadcn:utils","popover","command","i18n"],"examples":["model-picker-demo","model-picker-compact"],"states":[],"preview":"https://ui.ballmac.com/preview/model-picker-demo"},{"name":"morphing-text","kind":"component","type":"registry:ui","title":"Morphing Text","description":"Words melt into each other with a blur and threshold effect, cycling through a list, pausing when off screen, with a box that never jumps in width.","category":"text","tier":"free","tags":["text","morph","gooey","transition","hero"],"version":"1.0.0","updated":"2026-10-01","url":"https://ui.ballmac.com/components/morphing-text","registryUrl":"https://ui.ballmac.com/r/morphing-text.json","install":"npx shadcn@latest add @ballmac/morphing-text","summary":". The size comes from className. Uses an SVG threshold filter; the loop stops when off screen or when reduced motion is on.","whenToUse":["A hero word that changes between a few options","Brand or product-name reveals"],"whenNotToUse":["Small body text (the effect needs large type)","Many words per frame"],"composesWith":["word-rotate","hyper-text","text-animate"],"dependencies":["motion@^12"],"registryDependencies":["shadcn:utils"],"examples":["morphing-text-demo","morphing-text-inline"],"states":[],"preview":"https://ui.ballmac.com/preview/morphing-text-demo"},{"name":"multi-select","kind":"component","type":"registry:ui","title":"Multi Select","description":"Search and select several options in a Radix popover with native checkboxes and a selection cap.","category":"forms","tier":"free","tags":["multi-select","filter","checkbox"],"version":"1.0.0","updated":"2026-09-30","url":"https://ui.ballmac.com/components/multi-select","registryUrl":"https://ui.ballmac.com/r/multi-select.json","install":"npx shadcn@latest add @ballmac/multi-select","summary":"Search and select several options in a Radix popover with native checkboxes and a selection cap.","whenToUse":["Choose multiple teammates or categories","Filter a list by several states"],"whenNotToUse":["Use select when only one option is allowed"],"composesWith":["select"],"dependencies":["radix-ui","lucide-react"],"registryDependencies":["shadcn:utils","i18n"],"examples":["multi-select-demo","multi-select-states"],"states":[],"preview":"https://ui.ballmac.com/preview/multi-select-demo"},{"name":"native-select","kind":"component","type":"registry:ui","title":"Native Select","description":"The browser's own select, styled to match the input: three sizes, a placeholder, groups, a leading icon, invalid and disabled states and a loading spinner, so phones keep their picker and forms keep working.","category":"forms","tier":"free","tags":["select","native","dropdown","form","mobile","picker","optgroup"],"version":"1.0.0","updated":"2026-10-19","url":"https://ui.ballmac.com/components/native-select","registryUrl":"https://ui.ballmac.com/r/native-select.json","install":"npx shadcn@latest add @ballmac/native-select","summary":" with children and for groups. It is a real select: use value and onValueChange, or leave it uncontrolled in a form.","whenToUse":["Forms where a short list of choices should use the device's own picker (phones, tablets)","Long lists such as countries or time zones where type-to-jump matters","Anywhere accessibility and autofill should be exactly the browser's"],"whenNotToUse":["Options with icons, descriptions or search; use select or combobox","Choosing many items with chips; use multi-select","A handful of choices that deserve to be seen at once; use radio-group or segmented-control"],"composesWith":["label","input","field"],"dependencies":["class-variance-authority","lucide-react"],"registryDependencies":["shadcn:utils"],"examples":["native-select-demo","native-select-groups","native-select-sizes","native-select-form","native-select-loading","native-select-disabled"],"states":[{"id":"loading","title":"Loading options","example":"native-select-loading","trigger":"loading","note":"A spinner takes the arrow's place and the field is marked busy; it can still be opened, and the options appear when they arrive.","preview":"https://ui.ballmac.com/preview/native-select-loading"},{"id":"disabled","title":"Disabled","example":"native-select-disabled","trigger":"disabled","note":"Dimmed and unavailable to the pointer and keyboard, and left out of the form's data, as a native select is.","preview":"https://ui.ballmac.com/preview/native-select-disabled"}],"preview":"https://ui.ballmac.com/preview/native-select-demo"},{"name":"navbar","kind":"component","type":"registry:ui","title":"Navbar","description":"A responsive site header that gains a border and shadow on scroll, can hide while scrolling down, and turns its links into a sheet menu on small screens.","category":"navigation","tier":"free","tags":["header","navigation","sticky","responsive"],"version":"1.0.0","updated":"2026-09-30","url":"https://ui.ballmac.com/components/navbar","registryUrl":"https://ui.ballmac.com/r/navbar.json","install":"npx shadcn@latest add @ballmac/navbar","summary":"Compose Navbar with NavbarBrand, NavbarLinks/NavbarLink (active sets aria-current), NavbarActions and NavbarMobileMenu with NavbarMobileLink.","whenToUse":["Marketing and docs site headers","Headers that should get out of the way on long pages"],"whenNotToUse":["Application chrome with a sidebar; use app-shell","Wide dropdown panels; add mega-menu"],"composesWith":["mega-menu","button","sheet"],"dependencies":["lucide-react"],"registryDependencies":["shadcn:utils","sheet","scroll","i18n"],"examples":["navbar-demo","navbar-states"],"states":[],"preview":"https://ui.ballmac.com/preview/navbar-demo"},{"name":"navigation-menu","kind":"component","type":"registry:ui","title":"Navigation Menu","description":"A site navigation bar with flyout panels sharing one animated viewport that resizes to its content, with keyboard and pointer intent handling, built on Radix.","category":"navigation","tier":"free","tags":["navigation","header","mega menu","radix"],"version":"1.0.1","updated":"2026-10-11","url":"https://ui.ballmac.com/components/navigation-menu","registryUrl":"https://ui.ballmac.com/r/navigation-menu.json","install":"npx shadcn@latest add @ballmac/navigation-menu","summary":"Top-level triggers open content panels of links. Use navigationMenuTriggerStyle for plain top-level links.","whenToUse":["Marketing site headers","Docs navigation with grouped links"],"whenNotToUse":["An application command menu; use menubar","A small overflow list; use dropdown-menu"],"composesWith":["button","separator"],"dependencies":["radix-ui","lucide-react","class-variance-authority"],"registryDependencies":["shadcn:utils","direction"],"examples":["navigation-menu-demo","navigation-menu-states"],"states":[],"preview":"https://ui.ballmac.com/preview/navigation-menu-demo"},{"name":"neon-card","kind":"component","type":"registry:ui","title":"Neon Card","description":"A card framed by a two-color neon border with a soft outer light and inner glow, tunable thickness, intensity and corner radius, with an optional warm-up flicker that never plays under reduced motion.","category":"motion","tier":"free","tags":["card","neon","glow","border","gradient"],"version":"1.0.1","updated":"2026-10-11","url":"https://ui.ballmac.com/components/neon-card","registryUrl":"https://ui.ballmac.com/r/neon-card.json","install":"npx shadcn@latest add @ballmac/neon-card","summary":"content. Colors are theme tokens, so it follows any theme. The light is strongest in dark mode.","whenToUse":["A single highlighted plan, product or announcement","Dark-themed landing pages"],"whenNotToUse":["Several cards at once","A rotating border (glow-border)"],"composesWith":["glow-border","magic-card","card"],"dependencies":["motion@^12"],"registryDependencies":["shadcn:utils","motion-presets"],"examples":["neon-card-demo","neon-card-tones"],"states":[],"preview":"https://ui.ballmac.com/preview/neon-card-demo"},{"name":"noise-texture","kind":"component","type":"registry:ui","title":"Noise Texture","description":"A film-grain layer made from an SVG turbulence filter, with strength, fineness, blend mode and an optional shimmer, to take the plastic edge off gradients, cards and photos.","category":"backgrounds","tier":"free","tags":["noise","grain","texture","overlay","gradient"],"version":"1.0.1","updated":"2026-10-11","url":"https://ui.ballmac.com/components/noise-texture","registryUrl":"https://ui.ballmac.com/r/noise-texture.json","install":"npx shadcn@latest add @ballmac/noise-texture","summary":" absolutely fills its relative parent. No image file is needed; the grain is an inline SVG data URI.","whenToUse":["Gradient heroes and cards that band or look flat","Giving imagery a printed feel"],"whenNotToUse":["Text-heavy surfaces at high opacity"],"composesWith":["aurora-background","gradient-text","card"],"dependencies":["motion@^12"],"registryDependencies":["shadcn:utils","motion-presets"],"examples":["noise-texture-demo","noise-texture-blends"],"states":[],"preview":"https://ui.ballmac.com/preview/noise-texture-demo"},{"name":"notification-center","kind":"component","type":"registry:ui","title":"Notification Center","description":"A bell with an unread badge that opens grouped notifications with All and Unread views, mark-as-read, dismiss, and an unread count in its accessible name.","category":"saas","tier":"free","tags":["notifications","inbox","bell","popover"],"version":"1.0.0","updated":"2026-09-30","url":"https://ui.ballmac.com/components/notification-center","registryUrl":"https://ui.ballmac.com/r/notification-center.json","install":"npx shadcn@latest add @ballmac/notification-center","summary":"notifications[] with {id,title,description,time,group,read,icon,href}. Handle onMarkRead, onMarkAllRead, onDismiss and onOpenItem in your own state.","whenToUse":["App headers","In-app activity and alerts"],"whenNotToUse":["Transient confirmations; use toast","Long-form updates; use changelog-feed"],"composesWith":["popover","avatar","toast"],"dependencies":["motion@^12","lucide-react"],"registryDependencies":["shadcn:utils","motion-presets","popover","i18n"],"examples":["notification-center-demo","notification-center-states"],"states":[],"preview":"https://ui.ballmac.com/preview/notification-center-demo"},{"name":"notification-stack","kind":"component","type":"registry:ui","title":"Notification Stack","description":"macOS Notification Center cards: collapsed, the newest sits in front with two peeking behind; click or press Enter to spring the stack open. New cards slide in from the top; each can be dismissed.","category":"macos","tier":"free","tags":["notifications","toast","stack","macos","notification center","motion","vibrancy"],"version":"1.0.1","updated":"2026-10-02","url":"https://ui.ballmac.com/components/notification-stack","registryUrl":"https://ui.ballmac.com/r/notification-stack.json","install":"npx shadcn@latest add @ballmac/notification-stack","summary":"Render with body children, newest first. Keep items in state; prepend to add (animates in), filter to dismiss. expanded/defaultExpanded/onExpandedChange control the stack; onClearAll adds a clear button.","whenToUse":["An activity or notification feed in a dashboard corner","A landing-page hero showing the alerts a product sends (deploys, reviews, payments)","Grouping several recent events so they take the space of one"],"whenNotToUse":["Transient feedback after a single action (use a toast)","A single live activity that changes over time (use dynamic-island)"],"composesWith":["dynamic-island","mac-window"],"dependencies":["motion@^12","lucide-react"],"registryDependencies":["shadcn:utils","i18n"],"examples":["notification-stack-demo"],"states":[],"preview":"https://ui.ballmac.com/preview/notification-stack-demo"},{"name":"number-input","kind":"component","type":"registry:ui","title":"Number Input","description":"A bounded numeric field with native spinbutton semantics, step buttons, and controlled or uncontrolled state.","category":"forms","tier":"free","tags":["number","stepper","spinbutton"],"version":"1.0.0","updated":"2026-09-30","url":"https://ui.ballmac.com/components/number-input","registryUrl":"https://ui.ballmac.com/r/number-input.json","install":"npx shadcn@latest add @ballmac/number-input","summary":"A bounded numeric field with native spinbutton semantics, step buttons, and controlled or uncontrolled state.","whenToUse":["Choose a quantity or bounded count","Adjust a value precisely using keys or buttons"],"whenNotToUse":["Use a slider when approximate adjustment is sufficient"],"composesWith":["input"],"dependencies":["lucide-react"],"registryDependencies":["shadcn:utils","i18n"],"examples":["number-input-demo","number-input-states"],"states":[],"preview":"https://ui.ballmac.com/preview/number-input-demo"},{"name":"number-ticker","kind":"component","type":"registry:ui","title":"Number Ticker","description":"Counts up to a number when it scrolls into view, with locale-aware formatting for currency, percentages and decimals.","category":"motion","tier":"free","tags":["animation","counter","stats","motion"],"version":"1.0.1","updated":"2026-10-02","url":"https://ui.ballmac.com/components/number-ticker","registryUrl":"https://ui.ballmac.com/r/number-ticker.json","install":"npx shadcn@latest add @ballmac/number-ticker","summary":"Animated number for stats and KPIs. Respects reduced motion by showing the final value immediately.","whenToUse":["Stat sections on landing pages","Dashboard KPIs that load in"],"whenNotToUse":["Numbers that update every second (animate a live value instead)","Prices users need to read instantly"],"composesWith":["text-reveal","badge"],"dependencies":["motion@^12"],"registryDependencies":["shadcn:utils","motion-presets","i18n"],"examples":["number-ticker-demo","number-ticker-currency"],"states":[],"preview":"https://ui.ballmac.com/preview/number-ticker-demo"},{"name":"onboarding-checklist","kind":"component","type":"registry:ui","title":"Onboarding Checklist","description":"A get-started checklist with a progress ring and segmented bar, expandable steps with actions, checkable tasks and a short celebration when everything is done.","category":"saas","tier":"free","tags":["onboarding","checklist","progress","activation"],"version":"1.0.0","updated":"2026-09-30","url":"https://ui.ballmac.com/components/onboarding-checklist","registryUrl":"https://ui.ballmac.com/r/onboarding-checklist.json","install":"npx shadcn@latest add @ballmac/onboarding-checklist","summary":"steps: {id,title,description,action}. completed/defaultCompleted/onCompletedChange track progress. The open step shows its description and action.","whenToUse":["First-run setup for new accounts","Activation nudges in a dashboard corner"],"whenNotToUse":["Multi-page wizards; use stepper-form","A plain progress bar; use progress"],"composesWith":["progress-ring","card","button"],"dependencies":["motion@^12","lucide-react"],"registryDependencies":["shadcn:utils","motion-presets","i18n"],"examples":["onboarding-checklist-demo","onboarding-checklist-states"],"states":[],"preview":"https://ui.ballmac.com/preview/onboarding-checklist-demo"},{"name":"orbiting-circles","kind":"component","type":"registry:ui","title":"Orbiting Circles","description":"Items that orbit a center on circular tracks while staying upright. Evenly spaced, any radius, speed and direction; stack several for rings. Paused off-screen, static under reduced motion.","category":"motion","tier":"free","tags":["orbit","integrations","icons","rings","hero","motion"],"version":"1.0.0","updated":"2026-09-29","url":"https://ui.ballmac.com/components/orbiting-circles","registryUrl":"https://ui.ballmac.com/r/orbiting-circles.json","install":"npx shadcn@latest add @ballmac/orbiting-circles","summary":"Inside a relative container with a fixed height, render the center element, then one per ring with the orbiting items as children. Each ring fills the container (absolute inset-0) and centers itself; items are laid out evenly around the circle.","whenToUse":["An integrations or ecosystem section: your product in the middle, tools around it","A hero visual for a platform that connects many services"],"whenNotToUse":["Items people must read or click reliably (moving targets); use a grid","More than about 8 items per ring"],"composesWith":["animated-beam","dot-pattern"],"dependencies":[],"registryDependencies":["shadcn:utils"],"examples":["orbiting-circles-demo","orbiting-circles-minimal"],"states":[],"preview":"https://ui.ballmac.com/preview/orbiting-circles-demo"},{"name":"package-badge","kind":"component","type":"registry:ui","title":"Package Badge","description":"An npm-style package card or inline pill with version, weekly downloads and sparkline, size, license, TypeScript and module formats, and a one-click install command.","category":"developer","tier":"free","tags":["npm","package","version","install","badge"],"version":"1.0.0","updated":"2026-10-01","url":"https://ui.ballmac.com/components/package-badge","registryUrl":"https://ui.ballmac.com/r/package-badge.json","install":"npx shadcn@latest add @ballmac/package-badge","summary":"Pass the facts you already have: name, version, description, downloads, trend, size, license, types, formats. variant is card | inline. manager picks npm | pnpm | yarn | bun for the copyable install command. Nothing is fetched.","whenToUse":["Library landing pages and docs","Showing dependencies in a changelog or README-style page"],"whenNotToUse":["Live registry lookups (fetch on the server and pass the result)"],"composesWith":["install-tabs","copy-button","badge"],"dependencies":["lucide-react"],"registryDependencies":["shadcn:utils","copy-button","i18n"],"examples":["package-badge-demo","package-badge-inline"],"states":[],"preview":"https://ui.ballmac.com/preview/package-badge-demo"},{"name":"pagination","kind":"component","type":"registry:ui","title":"Pagination","description":"A semantic page navigation set with current-page feedback, generous targets, and small-screen labels.","category":"navigation","tier":"free","tags":["pages","navigation","links"],"version":"1.0.0","updated":"2026-09-29","url":"https://ui.ballmac.com/components/pagination","registryUrl":"https://ui.ballmac.com/r/pagination.json","install":"npx shadcn@latest add @ballmac/pagination","summary":"A semantic page navigation set with current-page feedback, generous targets, and small-screen labels.","whenToUse":["Navigate a large result set by page","Show a current page and neighboring destinations"],"whenNotToUse":["Use infinite scroll when discrete pages are unnecessary"],"composesWith":["button"],"dependencies":["lucide-react"],"registryDependencies":["shadcn:utils","i18n"],"examples":["pagination-demo","pagination-states"],"states":[],"preview":"https://ui.ballmac.com/preview/pagination-demo"},{"name":"parallel-attempts","kind":"component","type":"registry:ui","title":"Parallel Attempts","description":"Compare several runs of the same task side by side: status, summary, a changed-lines bar, time and cost on each card, a suggested run, and a native radio group to pick one and continue.","category":"ai","tier":"free","tags":["ai","agents","compare","attempts","best-of-n","diff","choose"],"version":"1.0.0","updated":"2026-10-24","url":"https://ui.ballmac.com/components/parallel-attempts","registryUrl":"https://ui.ballmac.com/r/parallel-attempts.json","install":"npx shadcn@latest add @ballmac/parallel-attempts","summary":"attempts is [{ id, label, model?, status: running | done | failed | stopped, summary, added?, removed?, files?, duration?, cost?, progress? }]. value / defaultValue / onValueChange pick a finished attempt; recommended marks one; onChoose adds a confirm button.","whenToUse":["Best-of-n runs where a person chooses the result","Comparing two or more models on the same task"],"whenNotToUse":["Comparing prompts in a table; use the agent-4 block","A single run's steps; use trace or agent-lanes"],"composesWith":["agent-lanes","run-ledger","diff-viewer","approval-card"],"dependencies":["lucide-react"],"registryDependencies":["shadcn:utils","i18n"],"examples":["parallel-attempts-demo","parallel-attempts-choose"],"states":[],"statesNone":"A presentational comparison: you pass in the attempts and their statuses, so it has nothing of its own to load or submit.","preview":"https://ui.ballmac.com/preview/parallel-attempts-demo"},{"name":"particles","kind":"component","type":"registry:ui","title":"Particles","description":"A canvas field of softly twinkling particles with depth, gentle drift and a pointer that attracts or repels them. Token colors, DPR aware, pauses off-screen, still under reduced motion.","category":"backgrounds","tier":"free","tags":["particles","stars","canvas","background","hero","interactive"],"version":"1.0.0","updated":"2026-09-29","url":"https://ui.ballmac.com/components/particles","registryUrl":"https://ui.ballmac.com/r/particles.json","install":"npx shadcn@latest add @ballmac/particles","summary":"Place as the first child of a relative, overflow-hidden container; it fills it (absolute inset-0, aria-hidden, pointer-events-none) and tracks the pointer at window level, so content above it stays clickable.","whenToUse":["Quiet hero or CTA backgrounds, especially on dark surfaces","Space, AI or data themed sections that need depth without imagery"],"whenNotToUse":["Behind long-form text","Many instances on one page (each runs its own canvas loop)"],"composesWith":["text-reveal","shimmer-text","magnetic-button"],"dependencies":[],"registryDependencies":["shadcn:utils","color"],"examples":["particles-demo","particles-rising"],"states":[],"preview":"https://ui.ballmac.com/preview/particles-demo"},{"name":"password-input","kind":"component","type":"registry:ui","title":"Password Input","description":"A password field with a visibility toggle and a four-step strength guide that explains how to improve the entry.","category":"forms","tier":"free","tags":["password","security","strength"],"version":"1.0.0","updated":"2026-09-30","url":"https://ui.ballmac.com/components/password-input","registryUrl":"https://ui.ballmac.com/r/password-input.json","install":"npx shadcn@latest add @ballmac/password-input","summary":"A password field with a visibility toggle and a four-step strength guide that explains how to improve the entry.","whenToUse":["Create or change a password","Give immediate guidance while typing"],"whenNotToUse":["Use input for a standard text field"],"composesWith":["input"],"dependencies":["lucide-react"],"registryDependencies":["shadcn:utils","i18n"],"examples":["password-input-demo","password-input-states"],"states":[],"preview":"https://ui.ballmac.com/preview/password-input-demo"},{"name":"permission-grid","kind":"component","type":"registry:ui","title":"Permission Grid","description":"A grid of everything an agent could do, each row set to Allow, Ask or Deny with native radios, risk written out, a warning when a high-risk action is allowed, grouped rows and one-click presets.","category":"ai","tier":"free","tags":["ai","agents","permissions","settings","safety","tools","approval"],"version":"1.0.0","updated":"2026-10-24","url":"https://ui.ballmac.com/components/permission-grid","registryUrl":"https://ui.ballmac.com/r/permission-grid.json","install":"npx shadcn@latest add @ballmac/permission-grid","summary":"permissions is [{ id, label, description?, risk?: low | medium | high, group? }]; value / defaultValue / onValueChange hold { [id]: 'allow' | 'ask' | 'deny' } (missing ids mean ask). presets is [{ id, label, values }] and fills the grid in one click.","whenToUse":["Letting people decide which tools an agent may use without asking","A permissions page for an assistant or a bot"],"whenNotToUse":["One overall level of freedom; use autonomy-dial","A single approval in the moment; use approval-card","User roles in a workspace; use the access review block"],"composesWith":["autonomy-dial","approval-card","tool-call-card","settings-panel"],"dependencies":["lucide-react"],"registryDependencies":["shadcn:utils","i18n"],"examples":["permission-grid-demo","permission-grid-dial"],"states":[],"statesNone":"A control with no data of its own: it shows the permissions you pass in and reports the choices.","preview":"https://ui.ballmac.com/preview/permission-grid-demo"},{"name":"phone-frame","kind":"component","type":"registry:ui","title":"Phone Frame","description":"A modern phone drawn in CSS: titanium band, side buttons, Dynamic Island, status bar and home indicator. Children render as the screen, laid out at a phone resolution and scaled to fit.","category":"devices","tier":"free","tags":["mockup","device","phone","iphone","mobile","screenshot","hero"],"version":"1.0.0","updated":"2026-09-29","url":"https://ui.ballmac.com/components/phone-frame","registryUrl":"https://ui.ballmac.com/r/phone-frame.json","install":"npx shadcn@latest add @ballmac/phone-frame","summary":"Wrap a mobile screen in : children render below a status bar at 390 CSS px wide and are scaled to the frame's width. Set the frame width with className (e.g. w-64); height follows the phone's aspect ratio.","whenToUse":["Showing a mobile app or responsive site on a landing page","App Store-style feature sections with live React screens","Pairing with laptop-frame to show desktop and mobile together"],"whenNotToUse":["Desktop apps or websites at desktop width (use laptop-frame or browser-frame)","Real device screenshots that already include the bezel"],"composesWith":["laptop-frame"],"dependencies":["motion@^12"],"registryDependencies":["shadcn:utils","media"],"examples":["phone-frame-demo","phone-frame-chat"],"states":[],"preview":"https://ui.ballmac.com/preview/phone-frame-demo"},{"name":"phone-input","kind":"component","type":"registry:ui","title":"Phone Input","description":"A native dialing-code selector paired with a telephone field that preserves the user’s formatting.","category":"forms","tier":"free","tags":["phone","telephone","country"],"version":"1.0.0","updated":"2026-09-30","url":"https://ui.ballmac.com/components/phone-input","registryUrl":"https://ui.ballmac.com/r/phone-input.json","install":"npx shadcn@latest add @ballmac/phone-input","summary":"A native dialing-code selector paired with a telephone field that preserves the user’s formatting.","whenToUse":["Collect a contact number with a dialing prefix","Edit a national number without forced formatting"],"whenNotToUse":["Use input type tel when a country selector is unnecessary"],"composesWith":["input"],"dependencies":[],"registryDependencies":["shadcn:utils","i18n"],"examples":["phone-input-demo","phone-input-states"],"states":[],"preview":"https://ui.ballmac.com/preview/phone-input-demo"},{"name":"plan-selector","kind":"component","type":"registry:ui","title":"Plan Selector","description":"Pricing plan cards that work as a radio group, with a Monthly/Yearly switch that re-prices every plan, a highlighted plan, feature lists and form submission.","category":"saas","tier":"free","tags":["pricing","plans","radio","billing toggle"],"version":"1.0.0","updated":"2026-09-30","url":"https://ui.ballmac.com/components/plan-selector","registryUrl":"https://ui.ballmac.com/r/plan-selector.json","install":"npx shadcn@latest add @ballmac/plan-selector","summary":"plans: {id,name,price:{monthly,yearly},features,highlight,disabled}. value/onValueChange pick a plan; billing/onBillingChange switch period; name submits with a form.","whenToUse":["Upgrade and signup flows","Pricing sections where visitors choose a plan"],"whenNotToUse":["A feature comparison grid; use comparison-table","Displaying the current plan; use billing-card"],"composesWith":["billing-card","comparison-table","radio-group"],"dependencies":["motion@^12","lucide-react"],"registryDependencies":["shadcn:utils","motion-presets","i18n"],"examples":["plan-selector-demo","plan-selector-states"],"states":[],"preview":"https://ui.ballmac.com/preview/plan-selector-demo"},{"name":"popover","kind":"component","type":"registry:ui","title":"Popover","description":"A focus-managed compact surface for controls or details, with collision handling, mobile-safe width, and optional close action.","category":"primitives","tier":"free","tags":["overlay","panel","editor","radix"],"version":"1.0.1","updated":"2026-10-11","url":"https://ui.ballmac.com/components/popover","registryUrl":"https://ui.ballmac.com/r/popover.json","install":"npx shadcn@latest add @ballmac/popover","summary":"Displays a small interactive panel anchored to a control, with managed focus and Escape dismissal.","whenToUse":["Inline editors and compact preferences","Actions needing more room than a menu"],"whenNotToUse":["Long or critical forms; use dialog","Noninteractive link previews; use hover-card"],"composesWith":["button","input"],"dependencies":["radix-ui","lucide-react"],"registryDependencies":["shadcn:utils","i18n"],"examples":["popover-demo","popover-states"],"states":[],"preview":"https://ui.ballmac.com/preview/popover-demo"},{"name":"progress-ring","kind":"component","type":"registry:ui","title":"Progress Ring","description":"A token-colored circular progress meter with a readable center and accessible value.","category":"data-display","tier":"free","tags":["progress","gauge","status"],"version":"1.0.0","updated":"2026-09-30","url":"https://ui.ballmac.com/components/progress-ring","registryUrl":"https://ui.ballmac.com/r/progress-ring.json","install":"npx shadcn@latest add @ballmac/progress-ring","summary":"A token-colored circular progress meter with a readable center and accessible value.","whenToUse":["Show bounded progress in a small area"],"whenNotToUse":["Use Progress for a full-width track"],"composesWith":["progress"],"dependencies":[],"registryDependencies":["shadcn:utils"],"examples":["progress-ring-demo","progress-ring-states"],"states":[],"preview":"https://ui.ballmac.com/preview/progress-ring-demo"},{"name":"progress-steps","kind":"component","type":"registry:ui","title":"Progress Steps","description":"An ordered progress sequence with current-step semantics and optional navigation to completed steps.","category":"feedback","tier":"free","tags":["steps","wizard","progress"],"version":"1.0.0","updated":"2026-09-30","url":"https://ui.ballmac.com/components/progress-steps","registryUrl":"https://ui.ballmac.com/r/progress-steps.json","install":"npx shadcn@latest add @ballmac/progress-steps","summary":"An ordered progress sequence with current-step semantics and optional navigation to completed steps.","whenToUse":["Show a multi-step flow","Let users revisit completed steps"],"whenNotToUse":["Use progress for an unlabelled percentage"],"composesWith":["stepper-form","progress"],"dependencies":["lucide-react"],"registryDependencies":["shadcn:utils","i18n"],"examples":["progress-steps-demo","progress-steps-states"],"states":[],"preview":"https://ui.ballmac.com/preview/progress-steps-demo"},{"name":"progress","kind":"component","type":"registry:ui","title":"Progress","description":"A Radix progress bar with clamped values, optional percentage text, and a reduced-motion-safe pending state.","category":"feedback","tier":"free","tags":["loading","progress","status"],"version":"1.0.0","updated":"2026-09-29","url":"https://ui.ballmac.com/components/progress","registryUrl":"https://ui.ballmac.com/r/progress.json","install":"npx shadcn@latest add @ballmac/progress","summary":"A Radix progress bar with clamped values, optional percentage text, and a reduced-motion-safe pending state.","whenToUse":["Show completion of a bounded task","Show work in progress when completion is unknown"],"whenNotToUse":["Use a spinner for very short waits"],"composesWith":["spinner"],"dependencies":["radix-ui"],"registryDependencies":["shadcn:utils"],"examples":["progress-demo","progress-states"],"states":[],"preview":"https://ui.ballmac.com/preview/progress-demo"},{"name":"progressive-blur","kind":"component","type":"registry:ui","title":"Progressive Blur","description":"A blur that ramps up toward an edge instead of switching on at a line, made of stacked backdrop-filter layers, for scrolling lists, headers, footers and image captions.","category":"motion","tier":"free","tags":["blur","gradient","edge","scroll","backdrop"],"version":"1.0.0","updated":"2026-10-01","url":"https://ui.ballmac.com/components/progressive-blur","registryUrl":"https://ui.ballmac.com/r/progressive-blur.json","install":"npx shadcn@latest add @ballmac/progressive-blur","summary":" inside a relative parent that scrolls or holds an image. Pointer events pass through it. A server component with no JavaScript.","whenToUse":["Scrolling lists that fade out at the edges","Text over images, instead of a dark gradient"],"whenNotToUse":["Browsers or surfaces without backdrop-filter support (it degrades to no blur)"],"composesWith":["scroll-area","card"],"dependencies":[],"registryDependencies":["shadcn:utils"],"examples":["progressive-blur-demo","progressive-blur-sides"],"states":[],"preview":"https://ui.ballmac.com/preview/progressive-blur-demo"},{"name":"prompt-diff","kind":"component","type":"registry:ui","title":"Prompt Diff","description":"Two versions of a prompt compared word by word: removed words struck through and added words underlined so colour is never the only cue, a count of each, {{variables}} marked, side by side or inline, and an optional Restore button.","category":"ai","tier":"free","tags":["ai","prompt","diff","versions","compare","history","text","evals"],"version":"1.0.0","updated":"2026-10-24","url":"https://ui.ballmac.com/components/prompt-diff","registryUrl":"https://ui.ballmac.com/r/prompt-diff.json","install":"npx shadcn@latest add @ballmac/prompt-diff","summary":"before and after are the two texts; beforeLabel / afterLabel name them; mode is 'split' (default) or 'unified'; onRestore adds a 'Restore ' button. Exports diffWords(before, after) returning [{ type: 'same' | 'add' | 'del', text }]. Compares words and keeps spacing; inputs over 200,000 word pairs are shown as fully replaced.","whenToUse":["Reviewing what changed between two prompt versions before shipping or rolling back","Any short text where the exact words changed matter"],"whenNotToUse":["Code or files; use diff-viewer","Comparing model outputs side by side; use parallel-attempts"],"composesWith":["parallel-attempts","run-ledger","heat-grid","diff-viewer"],"dependencies":["lucide-react"],"registryDependencies":["shadcn:utils","i18n"],"examples":["prompt-diff-demo","prompt-diff-inline"],"states":[],"statesNone":"A presentational comparison: you pass the two texts in, so it has nothing of its own to load or fail.","preview":"https://ui.ballmac.com/preview/prompt-diff-demo"},{"name":"prompt-input","kind":"component","type":"registry:ui","title":"Prompt Input","description":"An auto-growing chat input: Enter sends, Shift+Enter adds a line (IME-safe), the send button turns into Stop while streaming, with file attachment chips and a toolbar slot.","category":"ai","tier":"free","tags":["ai","chat","input","textarea","composer","attachments","llm"],"version":"1.0.0","updated":"2026-09-28","url":"https://ui.ballmac.com/components/prompt-input","registryUrl":"https://ui.ballmac.com/r/prompt-input.json","install":"npx shadcn@latest add @ballmac/prompt-input","summary":"The message composer for chat UIs. …} status onStop> renders a textarea, attachment chips and a send button by default; compose PromptInputTextarea, PromptInputAttachments, PromptInputToolbar, PromptInputAttachButton and PromptInputSubmit for custom layouts.","whenToUse":["The input at the bottom of an AI chat","A 'describe what you want' box that sends to a model and can be stopped mid-response","Composer that needs a model picker or other controls next to the send button"],"whenNotToUse":["Plain multi-line form fields (use textarea)","Search boxes with results as you type (use an input or command menu)"],"composesWith":["ai-chat","ai-message"],"dependencies":["lucide-react"],"registryDependencies":["button","shadcn:utils","i18n"],"examples":["prompt-input-demo","prompt-input-attachments"],"states":[],"preview":"https://ui.ballmac.com/preview/prompt-input-demo"},{"name":"pulse-button","kind":"component","type":"registry:ui","title":"Pulse Button","description":"A call-to-action button that sends soft rings outward to ask for attention, calming as soon as it is hovered or focused, and switchable off once the person acts.","category":"motion","tier":"free","tags":["button","pulse","attention","cta","notification"],"version":"1.0.1","updated":"2026-10-11","url":"https://ui.ballmac.com/components/pulse-button","registryUrl":"https://ui.ballmac.com/r/pulse-button.json","install":"npx shadcn@latest add @ballmac/pulse-button","summary":"Label. Rings stop on hover and focus, and when active is false or the button is disabled.","whenToUse":["Onboarding steps and 'try it now' prompts","Live or record buttons"],"whenNotToUse":["More than one per view","Anything permanent: attention fades if it never stops"],"composesWith":["button","shiny-button","status-dot"],"dependencies":["motion@^12"],"registryDependencies":["shadcn:utils","button","motion-presets"],"examples":["pulse-button-demo","pulse-button-tones"],"states":[],"preview":"https://ui.ballmac.com/preview/pulse-button-demo"},{"name":"qr-code","kind":"component","type":"registry:ui","title":"QR Code","description":"A QR code drawn as accessible SVG: square, rounded or dotted modules that keep scannable corner markers, a logo slot, error-correction levels, a clear message when text is too long, and PNG and SVG downloads.","category":"data-display","tier":"free","tags":["qr","code","svg","scan","share","download","wifi"],"version":"1.0.0","updated":"2026-10-19","url":"https://ui.ballmac.com/components/qr-code","registryUrl":"https://ui.ballmac.com/r/qr-code.json","install":"npx shadcn@latest add @ballmac/qr-code","summary":". shape is square, rounded or dots; level is L, M, Q or H; logo is a node drawn in the middle. Use svgRef with downloadQRCode(svg, { format }) for a save button.","whenToUse":["Sharing a link, a Wi-Fi network, a ticket or a pairing code to a phone","Download or print screens that need a crisp code at any size","A branded code with a logo in the middle"],"whenNotToUse":["Reading or scanning codes; this only draws them","Very long text; shorten it first (a link shortener or an id)","A barcode of another kind; this is QR only"],"composesWith":["button","card","dialog"],"dependencies":["uqr@^0.1"],"registryDependencies":["shadcn:utils","i18n"],"examples":["qr-code-demo","qr-code-shapes","qr-code-logo","qr-code-live","qr-code-empty","qr-code-error"],"states":[{"id":"empty","title":"Nothing yet","example":"qr-code-empty","trigger":"value=\"\"","note":"A dashed box that says there is nothing to encode yet, the same size as the code so nothing jumps.","preview":"https://ui.ballmac.com/preview/qr-code-empty"},{"id":"error","title":"Too long","example":"qr-code-error","trigger":"a value longer than a QR code holds","note":"A red box that says the text is too long and to use a shorter link, announced as an alert; onError gets the error.","preview":"https://ui.ballmac.com/preview/qr-code-error"}],"preview":"https://ui.ballmac.com/preview/qr-code-demo"},{"name":"questionnaire","kind":"component","type":"registry:ui","title":"Questionnaire","description":"A multi-step questionnaire with single-choice, multiple-choice, freeform and skippable questions, answer shortcuts, validation and native form data, built on shadcn's headless Questionnaire so the API is the same.","category":"ai","tier":"free","tags":["questionnaire","form","wizard","agent","choices","shortcuts","shadcn"],"version":"1.0.0","updated":"2026-10-19","url":"https://ui.ballmac.com/components/questionnaire","registryUrl":"https://ui.ballmac.com/r/questionnaire.json","install":"npx shadcn@latest add @ballmac/questionnaire","summary":" with a per question: Title, Description, Choices holding and optionally , and an Error. Add with Previous, Skip, Next and Submit. Answers are native FormData.","whenToUse":["An AI agent asking the person to choose between options before it continues","Onboarding and intake steps with a few questions","Surveys where answers become form data"],"whenNotToUse":["One question inside a form; use radio-group or checkbox","A long form with many field types; use form blocks","Quizzes that score answers; compute that yourself from the form data"],"composesWith":["card","dialog","trace","button"],"dependencies":["@shadcn/react@^0.3","lucide-react"],"registryDependencies":["shadcn:utils","button","i18n"],"examples":["questionnaire-demo","questionnaire-multiple","questionnaire-shortcuts","questionnaire-skip","questionnaire-validation","questionnaire-card"],"states":[],"statesNone":"It collects answers and hands them to onSubmit as form data; saving them, and any loading or failure around that, belongs to the page that owns the form.","preview":"https://ui.ballmac.com/preview/questionnaire-demo"},{"name":"radio-group","kind":"component","type":"registry:ui","title":"Radio Group","description":"Single-choice radios with optional full-card labels, descriptions, and large pointer targets around Radix keyboard navigation.","category":"forms","tier":"free","tags":["choice","form","radio","radix"],"version":"1.0.1","updated":"2026-10-11","url":"https://ui.ballmac.com/components/radio-group","registryUrl":"https://ui.ballmac.com/r/radio-group.json","install":"npx shadcn@latest add @ballmac/radio-group","summary":"Choose exactly one option in a form; use descriptive card labels when choices need context.","whenToUse":["A few mutually exclusive preferences","Pricing or delivery options with explanations"],"whenNotToUse":["Many options; use select","Multiple selections; use checkbox or toggle-group"],"composesWith":["label"],"dependencies":["radix-ui","lucide-react"],"registryDependencies":["shadcn:utils","direction"],"examples":["radio-group-demo","radio-group-states"],"states":[],"preview":"https://ui.ballmac.com/preview/radio-group-demo"},{"name":"rainbow-button","kind":"component","type":"registry:ui","title":"Rainbow Button","description":"A button with a border of theme colors circling it and a glow on hover, built on the Ballmac button so every size, variant and focus state still works.","category":"motion","tier":"free","tags":["button","gradient","border","glow","cta"],"version":"1.0.1","updated":"2026-10-11","url":"https://ui.ballmac.com/components/rainbow-button","registryUrl":"https://ui.ballmac.com/r/rainbow-button.json","install":"npx shadcn@latest add @ballmac/rainbow-button","summary":"Use like