npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2026 – Pkg Stats / Ryan Hefner

jg-react-ui

v0.10.0

Published

Consumer-themed React components with Moldea-derived APIs, explicit styling contracts, and reusable application behavior.

Readme

jg-react-ui

Consumer-themed React components with retained Moldea-derived APIs.

Install

pnpm add jg-react-ui

Usage

import { createElement } from 'react';
import { Button } from 'jg-react-ui/components/button';
const saveAction = createElement(Button, { size: 'touch' }, 'Save changes');

Import Tailwind once, then jg-react-ui/styles.css. Supply --background, --foreground, --primary, --primary-foreground, --secondary, --secondary-foreground, --destructive, --chart-1 (success), --chart-2 (warning), --border, --radius, --jg-ui-font-sans, --jg-ui-font-mono, --jg-ui-shadow-inset, --jg-ui-shadow-surface, --code, --code-foreground, --jg-ui-shadow-raised, and --jg-ui-inverse-color-scheme in your own theme. Colors must be complete CSS color values. .dark selects dark utility variants; this package supplies no brand palette. For the JG palette and fonts, use jg-personal-react-ui instead.

Button, Badge, IconTile, and Alert retain Moldea’s APIs from commit 2920a7b0a6e814e95872fcdd6dd8746ae422c038, including variants, sizes, refs, badges, and asChild where supported. The exported badgeVariants, iconTileVariants, and alertVariants retain their source signatures. Badge defaults to a span; IconTile is decorative unless aria-hidden={false} is supplied; static Alert uses role="alert", with phrasing-content title and description slots. Button’s touch sizes preserve at least 44px under a coarse pointer, including on tablets. Button’s asChild requires exactly one element and retains Base UI’s button semantics, including when that element is an anchor. Use the child’s explicit role="link" when it represents navigation.

All JavaScript entries are safe to import during server rendering. Styles remain explicit CSS imports. UI preference schemas retain the complete theme, diff layout, wrapping, and install-dismissal record; the dismissal timestamp is an ISO datetime string or null. Providers create their stores per mounted tree and perform no browser storage I/O during rendering.

Preferences, themes, and notifications derive from the same pinned Moldea commit. Package adaptations replace the global store and private application registry with provider-local SSR-safe stores and scoped error feedback, validate captured namespaces against jg-storage’s rules, preserve cancellation, and allow explicit null dismissal resets. Theme effects use React’s browser lifecycle, and the notification host preserves the configured font and hydrates into a body portal.

Badge and Alert asChild also require exactly one element, otherwise they throw Error("asChild requires exactly one valid React element child."). For interaction="redirect", slot an anchor; for interaction="action", slot a native button. The interaction option supplies styling, while the native child supplies keyboard semantics. Keep supplementary AlertAction controls inside a static Alert, away from interactive parent buttons or anchors. A linked Badge remains compact by default; add coarse-pointer minimum dimensions when it is a standalone touch target.

ErrorFeedbackProvider scopes application-owned error copy and access-loss classification to a React tree. Pass a resolver from createErrorFeedback in jg-exception; useErrorFeedbackResolver reads the nearest policy. Without a provider, unknown diagnostics and codes remain private behind generic copy. Cancellation stays recognizable, and a throwing application policy falls back safely.

Preferences, theme, and notifications

Compose UiPreferencesProvider, ThemeProvider, and one Toastr host in that order. ThemeToggleButton retains the source Button props and request callback. The document theme and Sonner notification channel are document-wide; keep one theme owner and one notification host per document even when independent preference roots are mounted.

Sonner injects its base notification CSS when its browser module loads. Package theme styles remain explicit imports. All JavaScript entries remain importable without browser globals on the server.

The preference provider supports explicit local, read-only, and remote modes. Local mode reads and writes best-effort browser storage and follows matching cross-tab events. Read-only mode exposes a snapshot and denies updates. Remote mode requires complete initialPreferences and an async persistPreferences adapter: updates are optimistic, saves run sequentially and coalesce newer snapshots, and a rejected save rolls back to the latest authoritative props. The application owns network requests and cache invalidation. Pending requests cannot update storage or show notifications after unmount.

Optional storageId defaults to jg-ui-preferences. It must be non-empty and contain only ASCII letters, digits, underscores, and hyphens. getUiPreferencesStorageKey returns its raw jg-storage: key. IDs are captured for the provider lifetime; use a keyed remount to change namespaces. Invalid IDs fail before storage access or initialization-script creation.

Render ThemeInitializationScript in the document head before application JavaScript, using the same storageId as the provider and your CSP nonce when required. Server snapshots use initial props or defaults, then storage synchronizes after hydration. See the recipes for composition and the shared owned error contracts.

Controls, forms, and plain text

Forms, select/choice controls, tabs, dropdown menus, tooltips, copy feedback, progress, dividers, empty states, links, inline code, and plain typography/table primitives retain the same pinned Moldea APIs. The application owns form validation and associations. Set your app root's font-sans bg-background text-foreground classes, supply both shadow roles and code color roles, and compose labelled touch rows around compact checkbox/radio/switch glyphs. Fields use at least 16px text under a coarse pointer; touch tabs and menu rows retain 44px targets. tw-animate-css supplies the retained enter/exit animation utilities through the explicit package stylesheet.

TabsList requires overflowBehavior: 'scroll' | 'truncate'; composite labels in a truncated list need title or aria-label. Select and menu dismiss aliases honor intentional cancellation. Select keeps the source's accepted forceMount/sticky aliases without additional Base UI behavior. Slotted controls require one valid element and retain their component-specific native Error guards. Menus and tooltips retain their portal and positioning APIs.

CopyButton writes exact text during the initiating gesture, blocks overlapping writes, and starts feedback after fulfillment. Its feedback duration remains milliseconds. copyLabel supplies a scoped ready name, visible label/copiedLabel and native naming overrides are retained, failures use the nearest error policy, and cancellation stays silent. It clears timers and ignores late feedback after unmount. TextLink adds secure rel tokens and a new-tab announcement; TableContainer accepts native region/name/focus props for keyboard-scrollable tables.

Dialogs, drawers, and layout

Dialog, AlertDialog, Drawer, ConfirmationDialog, and page/layout primitives retain the pinned compound APIs. DialogContent requires a size and direct DialogHeader, DialogBody, and optional DialogFooter children; asChild accepts one panel element containing those regions. Use an element that permits the dialog role, such as a div; place a form inside the body and associate fixed submit actions with its form ID. Drawer requires a side, its content requires a size, and its direct regions are ordered header, body, optional footer. AlertDialogContent requires a direct header and footer. Invalid composition and invalid slotted children retain native Error guards.

Medium and large dialogs become full-screen pages on phones, with generated Back and desktop close controls. Body regions own scrolling, while headers and actions stay fixed. Compact modal close controls retain their fine-pointer appearance and have actual 44px targets under a coarse pointer. The default initial focus skips unusable controls; initialFocus and generated control icons/labels remain configurable. Overlay dismissal stays disabled by default for dialogs. isDismissalDisabled blocks on-page dismissal; committed navigation still cancels obsolete dialogs.

DialogNavigationProvider, DialogNavigationObserver, and useDialogNavigationDismissal directly reuse jg-react-router's implementations and context. Place the observer inside the router, with persistent dialog hosts under the same provider. Navigation dismissal does not create history entries. The host application owns route history and its navigation UI; drawers close on route actions through an explicit DrawerClose composition or application state.

Mount one ConfirmationDialog per document and use useConfirmationDialogStore.getState().openConfirmationDialog(options). This imperative store retains the source's document-wide session API; do not mutate it while server rendering. Completion resets the session before calling the application callback, which receives true on confirmation and undefined on cancellation. The application owns async work and callback errors. Controlled dialog children remain immutable through closing transitions, then release at completion. Mobile return snapshots ignore stale callbacks and are skipped for reduced motion or unsupported browsers.

PageShell, PageHeader, PageHeaderRow, PageHeaderTitleGroup, PageHeaderMetadata, PageTitle, PageDescription, Stack, Inline, and Surface preserve the native semantic props and shared geometry. Supply --jg-ui-shadow-surface alongside the other generic theme roles. The stylesheet supplies source page-gutter spacing and the drawer gutter hooks; it does not reset the document's palette or typography.

Drawer also takes side: 'bottom', a bottom sheet for phones: it spans the view's width, grows with its content up to all but 3rem of the view's height, closes with a swipe down, and pads its body for the home indicator. ResponsiveDialog opens a Dialog from the md breakpoint up and that sheet below it, from one open state, title, optional description, and body; initialFocus targets the dialog and sheetInitialFocus the sheet, such as nothing that opens the keyboard. It adds no history entry, so pair it with a URL-backed state, such as jg-react-router's useSearchParamDialog, for Back to close it on phones.

InnerPageBar is an inner page's sticky top bar, placed first in its PageShell: Back to the page it was reached from, through jg-react-router's page return, or to its parent, the title cut to fit, and the page's actions. It sits below the notch, and its height is --inner-page-bar-height, 3.5rem unless the app sets it, so sticky offsets and scroll padding read the same value. ViewNav switches a page's views with a row of link buttons, never tabs: the selected one is marked as the current page, and the row scrolls sideways with complete labels, showing the selected link and any link the keyboard focuses.

Routing and query recovery

RouterRoot retains the source data-router outlet, pending progress, and shared dialog observer. It requires React Router's data router and the shared router peer. Route progress respects the top safe-area inset. It does not add history entries or change page focus/scroll policy; compose jg-react-router's PageOutlet when the host wants that behavior. GlobalErrorBoundary reads the thrown route error, focuses its labelled recovery main, preserves native refs, and cancels obsolete dialog sessions; GlobalErrorBoundaryView accepts an explicit error without router context. Recovery defaults to jg-sw's updateApp, with an optional onRefreshClick. Unknown errors and recovery failures use scoped safe feedback. Pending refresh and retry actions ignore overlapping clicks.

QueryBoundary, QueryLoader, LoadMoreButton, QueryErrorAlert, and QueryErrorToastr retain the structural query APIs. The boundary delegates initial resolution to jg-tanstack-query's shared hook: stale unapproved data waits, current data survives background failures, a new resolutionKey starts over, and access loss hides data immediately. After access loss, caller approval cannot restore data until every query settles successfully with current data. The nearest ErrorFeedbackProvider owns access-loss classification and visible copy; no application registry ships with these packages.

The default error slot is an inline blocking/retained alert. Custom renderers can use a persistent QueryErrorToastr for retained content. Supply a unique stable toastId per active failure owner and one Toastr host per document. Toast publication follows commit effects so a later-mounted host receives initial failures, and stale queued feedback is cancelled. Retry reads the latest committed queries and policy, ignores active fetches/overlapping retries, and keeps failures actionable until recovery; unmount cleanup preserves a same-ID replacement. Retry settles every failed query, including rejected or synchronously throwing adapters. Cancelled errors produce no outage alert or toast. Load-more click callbacks run first and may cancel the request with preventDefault.

Default compact pagination and recovery actions preserve their fine-pointer geometry and have at least 44px targets under a coarse pointer. JG's global recovery surface uses the foundation's inverse palette in both themes. Generic consumers set --jg-ui-inverse-color-scheme to match their recovery surface (dark or light); selection and focus use its primary roles. Query clients, network adapters, pagination limits, application code maps, and routing history remain host-owned.

RouteLoadError is the route error element for a page whose code couldn't load, which jg-react-router's createLazyRoute and loadRouteModule reject with ROUTE_MODULE_UNAVAILABLE: after an update it says the page opens once the app reloads, offline that it opens once the browser is back online, with Reload either way, and it never reloads on its own. Place it on a pathless route that groups the lazy pages inside the layout; every other error goes on to the next boundary. QueryFailure, as a QueryBoundary's renderErrorAlert, illustrates a first read that failed, and says when the browser is offline. LoadMoreButton takes autoLoad, which loads the next page as the control nears the viewport, 512px below it by default, and again after each page while it stays near; a failed page hides it, and the button stays for keyboards.

Text, avatars, and illustrations

ClampedText clamps a text to 2 to 6 lines, 3 by default, with Show all only when the clamp cuts it off and Show less after, measured whether it shows clamped or in full; the toggle names the text it controls and sits in a wrapping row with any details. Pass isExpanded and onExpandedChange when a list keeps each row's state. PathText renders a path or identifier with <wbr> after /, \, _, . and -, so it wraps there and copies whole. Avatar shows an image on a tile of a fixed size, xs to xl, filling it or fit="inset" for a logo, and the first character of its fallback in the same tile when there's no image or it fails to load; an empty alt makes it decorative. Illustration draws an empty list, conversation or checklist, an error, or being offline in the theme's tokens, hidden from assistive technology.

File uploads and audio input

FileUpload, FileUploadDialog, ImageUploadField, and AudioInput retain the pinned source props and callbacks. File uploads reuse jg-react's admission, concurrency, progress, cancellation, and retry queue. The caller supplies validation and transport callbacks; no endpoint, authorization policy, storage service, or transcription provider is included. Upload adapters must honor their abort signal. The image field displays the caller's current image and falls back safely when its preview fails; the caller owns object URL creation and revocation.

The upload dialog finalizes successful results through onSubmit, retries finalization without reuploading, and reports abandoned successful items through onDiscard. The caller owns remote cleanup and callback failures. Audio input owns microphone tracks, recorder handlers, waveform contexts, intervals, and deferred commands. Obsolete permission/transcription results cannot update a replacement session or call completion after unmount. Recording reset is immediate; closing retains the source's short visual reset delay.

transcribe receives the captured recording and returns text. Users can send directly or edit the transcription first; a failed send retries the authored text without transcribing again. Provider operations remain caller-owned and should have their own deadline/cancellation policy. Recording/transcription error callbacks receive diagnostic exceptions, while visible feedback uses the nearest scoped resolver. The seven owned audio codes and stable messages are listed in errors/README.md; coded provider exceptions preserve their diagnostic identity. Canceled permission/transcription work stays silent and can be restarted; diagnostic callbacks still run. Optional result callbacks remain optional. Standalone review remains the default. Supply onTranscriptionApply to place Transcribe results directly in the main input while onTranscriptionResult handles Send separately; isResultActionVisible={false} uses Transcribe as the sole result action. Progress stays on the active button, with a screen-reader announcement. Pending work blocks dismissal and restart.

Set presentation="inline" to replace the mic trigger with an in-flow recorder. Use IInlineAudioInputProps with isOpen, defaultIsOpen or onOpenChange to manage inline opening. Dialog mode uses the original IAudioInputProps and dialog-named open-state props. Inline capture waits for the open state to commit. With autoStart={false} a controlled closed recorder only requests opening. Call its start control after the accepted open. A mic-triggered inline open focuses Cancel recording when focus still belongs to the triggering interaction. Standalone review, information and actionable errors are available in secondary dialogs.

Use inlineLayout="toolbar" with the inline presentation to match a message composer. The recorder fits on one line, groups its live indicator, waveform and elapsed time, and keeps its action size during transcription and submission. Restart remains beside Transcribe and Send. The waveform scales with the composer width and shrinks when space is tight. Taller bars use a compressed display amplitude so quieter speech stays visible without changing the recording. Starting feedback stays visible on phones; wider toolbars also show the recording status. Capacity stays quiet below 90%. At 90%, the phone timer becomes an amber warning badge with an exclamation marker; desktop uses the status slot. Tapping the warning opens capacity details while the waveform stays visible and no row is added. Error recovery and optional transcript review open their usual dialogs.

For the rest of the composer, use Button with size="toolbar" for icon actions and apply jg-ui-toolbar-actions to each flex action group. The shared stylesheet gives narrow or touch-capable layouts 44 px targets and a 32 px face for filled and outlined actions. At 640 px and wider, fine-pointer layouts without touch use 32 px targets. Icons are 16 px and the action groups have a 4 px gap at that breakpoint. Use ghost buttons for secondary actions and ArrowUp for the filled submit action.

Markdown and code

Markdown retains GFM tables/task lists, heading and prose rendering, uppercase template-variable highlights, image width hints (title="width=560"), renderer/plugin overrides, and standalone YouTube links. Raw HTML is skipped by default. HTTP(S) and relative document links open in secure new tabs by default, with an accessible announcement; fragments and non-web links remain in the current tab. Set shouldOpenLinksInNewTab={false} or supply an anchor renderer for application routing. headingLevelOffset lowers every heading, to h6 at most, so a document shown under a page's own h1 starts at h2. Applications own the trust policy of custom plugins, URL transforms, and renderers.

Message columns need min-width: 0; grid tracks use minmax(0, 1fr). Markdown and InlineCode wrap long paths and unbroken tokens. InlineCode retains preferred separator breaks without changing copied text. Code blocks and tables contain their own horizontal scrolling; Markdown tables have labelled, keyboard-focusable scroll groups. Unlabelled fences remain preformatted code blocks with exact whitespace.

CodeBlock and CodeFileHeader preserve metadata/status/action slots, aliases, syntax highlighting, literal plain mode, custom copy text, and wrapping controls. Declared prose languages or prose file extensions wrap automatically. prefersWrappedCode takes precedence over shouldWrapContent, then automatic prose wrapping and the scoped saved preference. Explicit overrides and read-only providers hide mutation controls. diff and diff-<language> fences preserve source endings, patch markers and multiline syntax. CodePreferencesControls also exposes split/unified preference menus for source surfaces. Compact actions keep the source fine-pointer geometry and use 44px coarse-pointer targets.

The personal adapter maps syntax and file-status roles to jg-personal-ui's existing theme tokens. Generic syntax uses unbranded One-theme fallbacks; supply --syntax-foreground and --syntax-token-{keyword,string,string-expression,comment,function,constant,parameter,punctuation,link} to override them. Token maps are reused across renders, and unchanged Markdown parser inputs are memoized. Every grammar/style import names its exact JavaScript file, so Node imports need no consumer resolver changes.

parseYouTubeVideoUrl validates supported HTTPS single-video links and returns a branded identifier. YouTubeVideo uses the fixed privacy-enhanced origin, strips authored playback parameters, and enables autoplay only through its explicit prop. URL validation/building reuses jg-utilities, with the retained UI's narrower route policy. A forged invalid identifier throws the dependency's documented INVALID_YOUTUBE_VIDEO_ID contract.

Code diffs

CodeDiff runs beneath UiPreferencesProvider and ThemeProvider. It retains source metadata, upstream viewer controls, style overrides, fold renderers, and responsive unified/split preferences. Its runtime is the package's bundled, patched [email protected]; consumers configure no patch or install script. The upstream dependency supplies declarations, while runtime imports use the bundled adapter. React and React DOM remain external.

Bounded excerpts (at most 8192 combined characters and 128 combined lines) render synchronously, including during server rendering and revision changes. Larger comparisons retain the lazy Web Worker path; explicit disableWorker keeps its source meaning. Worker support and Blob-worker permissions depend on the host environment. styles, loadingElement, infiniteLoading, alwaysShowLines, line offsets, gutter renderers, and other retained viewer props remain available. Split view starts at lg by default; narrower layouts use unified rows. Code wraps inside fixed-width cells. The optional tabIndex belongs to the content beneath the stationary file header.

The checked build verifies pristine and patched ESM file identities before bundling, rejects stale hunks, and preserves the worker's separate dynamic chunk. Moldea's patch is unchanged. Local accessibility adaptations make the summary a labelled group and give the all-lines button an explicit name and expanded state. Fold controls have native keyboard behavior and coarse-pointer targets of at least 44px. Complete bundled licenses ship in THIRD-PARTY-NOTICES.md; pnpm build:viewer --write-notices regenerates that file, and ordinary builds check it for staleness. Build tooling and patch sources stay outside the tarball. Turbo’s package-local unit and browser tasks depend on the package build, so test collection always receives the compiled patched viewer. Use Turbo when running these tasks from a fresh checkout.

Large-diff results are cached only for the current viewer input, matching the synchronous path's single-revision ownership. A miss recomputes in the real worker; returning to an older revision does not retain its old source/result in memory. Replies for obsolete inputs cannot clear the current revision's loading state. Controlled alwaysShowLines and extraLinesSurroundingDiff changes recompute large comparisons; runtime line references use L-1 and R-1 forms. The checked build applies these local corrections after verifying the unchanged source patch; real-worker regressions reproduce both failures before correction. Work remains local to the viewer, with no cross-root cache or additional persistence.

Markdown editors

MarkdownEditor retains the controlled value/onChange, supportedTools, accessibility props, and auto/compact/wide layouts. Auto measures the owning container and selects wide at 640px. CompactMarkdownEditor and WideMarkdownEditor expose the same props without layout. A changed value replaces the document as one edit that keeps the editor's focus, with the caret at the end of the text, and isn't reported back through onChange. The exported all-tools, authoring, and prose policies retain the source command sets; existing documents remain readable when authoring tools are constrained.

ChatMarkdownEditor defaults to paragraph, H1–H3, bullet/numbered-list, bold/italic, and safe-link formatting. Its optional supportedTools accepts IChatMarkdownEditorTool; add inline-code, code-block and table to the existing seven tools to enable the selection and slash-menu actions together with their document structures. Code retains literal whitespace, character references and language labels; tables retain alignment. Restored/programmatic HTML outside code is removed, unsupported blocks become readable prose, and image alternatives remain text. Pasted raw HTML is retained as literal text before normalization. Supported rich formatting stays intact; rich conversion that loses readable fragments recovers the complete bounded plain representation. Oversized HTML is intercepted before rich parsing and may use independently bounded plain text. The serialized result is checked before replacing the draft; rejected paste leaves the draft and selection intact. Short pastes insert at the caret without extra paragraphs, and one undo removes one paste. Formatting feedback remains until the next edit. Chat YouTube links retain their destinations and queries; video embeds remain document-editor behavior.

Supply a positive safe-integer maxLength, which counts the message without the line break its Markdown ends with. maxEditorHeight defaults to 256px, must be positive and finite, and is constrained to 50dvh by the stylesheet. controlsRef exposes getMarkdown(), focus(), and appendLiteralText(text). Literal insertion escapes Markdown and normally returns false before readiness or when the draft is too long. Pass { allowOverLimit: true } to retain complete dictation, including during initialization, for editing in the main input. Read-only editors reject insertion. The consumer must block button and keyboard submission while over limit. Key the editor by draft identity to clear content and undo history after a successful submission. Initial snapshots retain the controlled draft, and focus waits for the initialized editor. Use these controls to compose caller-owned upload and dictation flows.

Ctrl+Enter and Cmd+Enter flush a pending onChange before requesting submission from prose and embedded code editors, except during composition or while read-only. Enter and Shift+Enter edit by default; isShiftEnterSubmit retains the optional Shift+Enter submission behavior. Live theme changes use CSS tokens without remounting chat editors or replacing their document, selection or undo history. Chat uses the native browser caret so its editing position stays visible as the document scrolls; floating formatting controls stay outside the scrolling surface.

formattingContainer uses inline placement when omitted, reserves external placement with null, and portals the formatting menu into a supplied HTMLElement. The existing styles.css entry includes Milkdown's common/frame styles before editor overrides. The personal package re-exports the generic implementations directly and supplies the shared JG tokens.

Invalid configuration retains these native Error messages:

  • ChatMarkdownEditor maxLength must be a positive safe integer.
  • ChatMarkdownEditor maxEditorHeight must be a positive finite number.

Documentation

The API reference ships as API.md, and app-side examples ship as RECIPES.md. These personal-use packages are unlisted on the public package website.

License

MIT.