hintful_prefs 1.0.0
hintful_prefs: ^1.0.0 copied to clipboard
shared_preferences-backed persistent store for hintful — show a hint or tour once per app version, out of the box.
hintful_prefs #
shared_preferences-backed persistent store for
hintful — show a hint or tour once
per app version, out of the box.
The hintful core stays dependency-free ("dart:ui + widgets only"): the
HintStore contract lives there, storage implementations live outside it.
This companion package ships the ready-made persistent store so a product app
does not have to write even the three-line CallbackHintStore.
Getting started #
dependencies:
hintful: ^1.0.0
hintful_prefs: ^1.0.0
import 'package:hintful/hintful.dart';
import 'package:hintful_prefs/hintful_prefs.dart';
Future<void> main() async {
WidgetsFlutterBinding.ensureInitialized();
final prefs = await SharedPreferences.getInstance();
// One call at startup: every controller reads this store — no per-call
// store:, no controller field.
Hintful.configure(store: SharedPreferencesHintStore(prefs));
runApp(const MyApp());
}
final controller = HintController();
// Shows once per app version: a version bump re-shows it. `mark:` arms the
// version gate and records the tour on the exit you pick.
await controller.tryShowTour(
HintTour(
id: 'intro',
minShowVersion: '1.2.0', // "new in 1.2.0"
steps: [
HintStep(
targetId: 'addSet',
content: HintStepContent(title: 'Log your set'),
),
],
),
mark: HintMarkPolicy.onAnyExit,
);
What it provides #
SharedPreferencesHintStore— implements the two-memberHintStorecontract (shouldShow/markShown). Keys are namespaced underprefix(defaulthintful.) so hint records never collide with the app's own preferences.markShownis fire-and-forget: the in-memory cache updates synchronously, so a restart in the same session already sees it.shouldShowdoes not restate the rule: it callshintful'sHintStore.shouldShowVersion— the same gateInMemoryHintStoreandCallbackHintStorecall.clear()— a debug/dev tool that forgets every hint record under this store's prefix (the production "show again" is a version bump — see theHintStoredocs inhintful). Not part of the abstract contract: a concrete store may expose its own.compareHintVersions(a, b)— re-exported fromhintful: the one segment-wise version ordering the core stores, this store and any app-side store gate on ("1.10.0" > "1.9.0", missing segments count as0). It is the comparison insideHintStore.shouldShowVersion(frompackage:hintful/hintful.dart), which is the whole rule — prefer it over composingcompareHintVersionsby hand.
Development #
Requires Dart ≥ 3.2 / Flutter ≥ 3.16 (same floor as hintful) and
shared_preferences ^2.3.0.
See the hintful documentation for the
full API, best practices and FAQ. MIT licensed.