dashronym 0.2.0

Accessible inline acronym definitions for Flutter.

dashronym

Dashronym turns acronyms in Flutter text into accessible inline definition tooltips. Give it a map of terms and descriptions, then use it with an existing Text or with DashronymText.

Requirements

Dashronym 0.2.x requires:

• Dart >=3.10.0 <4.0.0
• Flutter >=3.38.1

Installation

dependencies:
  dashronym: ^0.2.0

Then run flutter pub get and import the package:

import 'package:dashronym/dashronym.dart';

Quick start

final acronyms = DashronymRegistry({
  'API': 'Application Programming Interface',
  'SDK': 'Software Development Kit',
});

class Overview extends StatelessWidget {
  const Overview({super.key});

  @override
  Widget build(BuildContext context) {
    return const Text(
      'The SDK provides an API for your application.',
    ).dashronyms(registry: acronyms);
  }
}

Registered uppercase acronyms containing 2–10 ASCII letters match in ordinary text by default. Only terms in the registry become interactive. Change the length bounds with DashronymConfig when needed.

DashronymText provides the same behavior directly:

DashronymText(
  'The SDK provides an API for your application.',
  registry: acronyms,
)

Share a registry

Use DashronymScope when several widgets use the same definitions:

DashronymScope(
  registry: acronyms,
  child: const Article(),
)

Widgets below the scope can omit the registry:

const Text('Install the SDK first.').dashronyms()

const DashronymText('Then call the API.')

Explicit widget arguments override values inherited from the nearest scope. At most one tooltip is open within a DashronymScope; independent scopes coordinate their tooltips separately and do not interfere with each other.

Matching

Bare uppercase acronyms are enabled by default. Marker-wrapped terms such as (API), 'API', and "API" are also supported.

To require markers, disable bare matching:

DashronymScope(
  registry: acronyms,
  config: const DashronymConfig(enableBareAcronyms: false),
  child: const Article(),
)

DashronymConfig also controls the accepted marker pairs and minimum and maximum term lengths. Use its copying factory for custom markers:

final config = DashronymConfig.withMarkers(
  acceptMarkers: const ['()', '«»'],
);

Rich text

The extension also works with Text.rich and keeps the surrounding span styles:

Text.rich(
  TextSpan(
    children: [
      const TextSpan(text: 'Use the '),
      TextSpan(
        text: 'SDK',
        style: Theme.of(context).textTheme.labelLarge,
      ),
      const TextSpan(text: ' to call the API.'),
    ],
  ),
).dashronyms(registry: acronyms)

Existing WidgetSpans are preserved. A TextSpan with its own semanticsLabel remains an author-controlled accessibility boundary.

Theme

Pass a DashronymTheme to one widget or install it as a Flutter theme extension:

MaterialApp(
  theme: ThemeData(
    extensions: const [
      DashronymTheme(
        acronymStyle: TextStyle(color: Colors.indigo),
        cardElevation: 10,
        tooltipMaxWidth: 360,
      ),
    ],
  ),
  home: DashronymScope(
    registry: acronyms,
    child: const Article(),
  ),
)

A theme passed directly to DashronymText, Text.dashronyms(), or DashronymScope takes precedence over the app theme.

Custom tooltip content

Use tooltipBuilder when the definition needs an application-owned surface:

DashronymText(
  'Review the API.',
  registry: acronyms,
  tooltipBuilder: (context, details) {
    return Card(
      child: ListTile(
        title: Text(details.acronym),
        subtitle: Text(details.description),
        trailing: IconButton(
          tooltip: 'Close definition',
          onPressed: details.hideTooltip,
          icon: const Icon(Icons.close),
        ),
      ),
    );
  },
)

Dashronym still handles overlay positioning, viewport constraints, focus, and dismissal. Your builder just owns the content.

Accessibility and interaction

Matched terms are keyboard-focusable controls.

• Tap, click, Enter, or Space opens or toggles a definition.
• Escape, an outside tap, scrolling, or a viewport change dismisses it.
• Focus can move into custom tooltip controls and returns to the trigger after closing.
• At most one tooltip is open per DashronymScope; independent scopes don't interfere with each other.
• Tooltip surfaces stay within the visible viewport.
• Definition state and content are exposed to assistive technologies.

Custom builders should keep their controls keyboard-reachable, label them clearly, and call details.hideTooltip to close. Test with real assistive tech, not just automated checks.

Localization

Dashronym includes English strings and safely falls back to English when its delegate is not installed. Apps that configure Flutter localization can add:

localizationsDelegates: const [
  DashronymLocalizations.delegate,
  // Keep your app's existing Flutter and application delegates here.
],

Keep the app's existing supportedLocales; Dashronym's English strings fall back safely for other locales.

Resources

• Example application
• Migration guide
• Contributing guide
• Security policy

Dashronym is available under the BSD 3-Clause License.