super_core library

Super Core — the shared GeniusLink design-system foundation for the Super toolkit. Single source of truth for the visual identity that every Super package reads from, so the whole toolkit looks like one product.

v2.0.0 — dynamic brand tokens, custom fonts, forked app bars

Breaking. The former static const SuperTokens class is removed. Brand tokens (accent + semantic palette, font families, radii, the 4px spacing scale, control metrics, motion) are now the instance fields of the immutable SuperTokensData carried by the theme (SuperThemeData.tokens / SuperMaterialThemeData.tokens) — so a theme can override any of them:

SuperMaterialThemeData.light(
  tokens: const SuperTokensData(radiusCard: 12), // dynamic override
);
final tokens = SuperThemeData.of(context).tokens; // read at a call site

There are NO static token constants — read every token dynamically from the ambient theme (SuperThemeData.of(context).tokens.x). The default values live only as the literals in the SuperTokensData constructor; the single default instance is SuperTokensData.fallback.

Custom fonts. SuperMaterialThemeData.light / .dark accept a fontFamily, and a textTheme whose family is honored when mergeTextTheme is true (the family is applied over the default GeniusLink type ramp, preserving its sizes / weights / spacing).

Widgets. SuperAppBar and SuperSliverAppBar are full forks of Flutter's AppBar / SliverAppBar with a positionable subtitle (SubtitlePosition) and responsive action overflow (SuperAppBarTheme). SuperCard gains expand/collapse (vertical or horizontal) plus leading / trailing slots (SuperCardTheme). SuperDialog is removed — use Flutter's themed showDialog / AlertDialog (styled by SuperMaterialThemeData).

v1.3.0 — complete ThemeData + ColorScheme

SuperMaterialThemeData now generates a GeniusLink default for every ThemeData property (top-level colors, density, the remaining component themes) and SuperPalette's color schemes fill every Material 3 role (the fixed accent roles + the full surface-container ramp). The Scaffold and app bar are painted ColorScheme.surface (the page background) while cards and fields sit on lifted surface tokens; the OS status + navigation bars are kept in sync via systemOverlayStyle. Precedence is unchanged: explicit override > palette-generated > Flutter default.

v1.0.0 — SuperPalette + SuperMaterialThemeData

Pick a palette and generate complete Material 3 ThemeData:

MaterialApp(
  theme:     SuperMaterialThemeData.light(palette: SuperPalette.bluePalette),
  darkTheme: SuperMaterialThemeData.dark(palette: SuperPalette.bluePalette),
);

Palette switching at runtime:

setState(() => _palette = SuperPalette.greenPalette);
// Rebuild MaterialApp — both light and dark themes update automatically.

All Super components adapt automatically: SuperMaterialThemeData registers SuperThemeData as a ThemeExtension, so SuperThemeData.of(context) picks up palette-derived surface tokens without extra wiring.

Pre-v1.0.0 API (unchanged)

MaterialApp(
  theme:     ThemeData(extensions: const [SuperThemeData.light]),
  darkTheme: ThemeData(extensions: const [SuperThemeData.dark]),
);
final t = SuperThemeData.of(context); // falls back to .dark

Exported symbols

Symbol Purpose
SuperPalette Six built-in palettes (10 shades + semantic getters)
SuperMaterialThemeData Material 3 ThemeData generator (+ tokens, fontFamily, mergeTextTheme)
SuperTokensData Dynamic brand tokens carried by the theme (with default* constants)
SuperThemeData Swappable light/dark ThemeExtension (carries tokens)
SuperAppBarTheme AppBarTheme + subtitle position + responsive action limits
SuperCardTheme CardThemeData + expand / leading-trailing defaults
SuperText GeniusLink static type ramp as TextStyles
SuperTextTheme Responsive named type ramp (displayLg → labelSm), built from tokens via GoogleFonts
SuperFormat Intl-free formatters
SuperMarker Section-marker bar intents
Widgets SectionCard, AccentSectionCard, SectionHeader, StatusPill, SuperButton, Hairline, FieldShell, SuperCard, SuperSnackBar, SuperAppBar, SuperSliverAppBar

Import this single barrel to get the whole foundation:

import 'package:super_core/super_core.dart';

Classes

AccentSectionCard
A card with a leading accent bar and a distinct tinted header area.
CacheFailure
A failure originating from a local data source (file read, parse, cache).
Failure
Base type for a recoverable failure surfaced to the domain / presentation.
FieldShell
The label + control + hint/error chrome around a form control.
Hairline
A 1px divider. Horizontal by default; pass vertical for a column rule.
NoParams
Marker for usecases that take no arguments: call(NoParams()).
RemoteFailure
A failure originating from a remote data source (network, async fetch).
SectionCard
A section card. Supply child and optionally a header via title + subtitle + marker / accentColor / icon, or a pre-built header.
SectionHeader
A section header — optional icon container + colored marker bar + title
StatusPill
A small uppercase status pill.
SuperAppBar
A GeniusLink app bar forked from Material's AppBar, with a positionable subtitle and responsive action overflow. Implements PreferredSizeWidget so it drops straight into Scaffold.appBar.
SuperAppBarTheme
An AppBarThemeData extended with the Super app-bar configuration: subtitlePosition and the responsive action-overflow limits (maxActions / maxMobileActions / maxTabletActions / maxDesktopActions).
SuperButton
A primary or secondary text button with brand hover/press states.
SuperCard
A surface card — the general container primitive of the design system.
SuperCardTheme
A CardThemeData extended with SuperCard configuration: the expand direction + animation, whether a tap toggles expansion, whether a chevron affordance is shown, the interior padding, and the resting / selected border colors.
SuperConstants
Kit-wide non-visual constants.
A single ALL-CAPS footer action link.
SuperFormat
Number + currency + byte formatting helpers. No intl dependency.
SuperGridTile
A GeniusLink grid / dashboard card.
SuperIconButton
A 32x32 icon button — current bg tints to inputBg on hover, 4px radius.
SuperInteractiveStateThemeData
The interactive-state treatment for Super components.
SuperListTile
A GeniusLink list row. Provide any subset of leading, title, subtitle, supporting, trailing; the tile lays them out with the design system's density, spacing, type and interaction states.
SuperMargin
Responsive outer margin bundle (space around a container).
SuperMaterialThemeData
A ThemeData subclass that is fully configured from a SuperPalette and a SuperDeviceMode, and additionally exposes the Super toolkit's SuperThemeData via the superTheme field (kept in sync with the registered ThemeExtension).
SuperMetrics
An immutable snapshot of every responsive token scale for one SuperDeviceMode. Obtain via SuperMetrics.of.
SuperPadding
Responsive inner padding bundle (space inside a container).
SuperPalette
A complete color palette — 10 ordered shades plus derived semantic tokens.
SuperResponsive<T>
A value that varies across the three SuperDeviceModes.
SuperSection
A section card with an optional header, optional footer, optional collapse.
SuperSectionFooter
A footer row — brand / status micro-copy on the leading edge and a set of action links on the trailing edge, separated by a hairline rule.
SuperSectionFooterThemeData
Configurable defaults for SuperSectionFooter / SuperFooterLink.
SuperSectionHeader
A section / page header — see SuperSectionHeaderStyle for the two forms.
SuperSectionHeaderThemeData
Configurable defaults for SuperSectionHeader.
SuperSectionThemeData
Configurable defaults for the SuperSection shell.
SuperSemanticColor
One resolved semantic color — the full set of roles for a single intent.
SuperSemanticColors
The structured semantic color bundle — one SuperSemanticColor per intent.
SuperSizing
Responsive sizing scale (control heights, icon + touch-target sizes).
SuperSlider
A responsive, snapping content carousel. Provide either children or (itemBuilder + itemCount).
SuperSliderController
Imperative handle for a SuperSlider — lets a host module drive navigation (external buttons, keyboard shortcuts) and observe the active page.
SuperSliverAppBar
A GeniusLink sliver app bar forked from Material's SliverAppBar, with a positionable subtitle and responsive action overflow.
SuperSnackBar
Shows and builds GeniusLink toasts. Never instantiated — call the statics.
SuperSpacing
Responsive spacing scale (gaps between elements). All multiples of the 4px base unit; larger form-factors breathe more.
SuperTextTheme
The GeniusLink type ramp as a TextTheme subclass.
SuperThemeData
SuperTileMarker
A section-marker pill (the GeniusLink signature 4px bar), sized to height.
SuperTileMetrics
Resolved density metrics for a tile.
SuperTileShimmer
A subtle indeterminate shimmer used by the tile loading states.
SuperTileVisualState
The pointer/keyboard state of a tile, used to resolve its surface treatment.
SuperTokensData
An immutable bundle of the theme-level GeniusLink brand tokens — the accent
SyncUseCase<Output, Params>
A synchronous variant for pure, non-async actions.
UnexpectedFailure
An unexpected / unclassified failure.
UseCase<Output, Params>
A single business action producing a Result of Output from Params.
ValidationFailure
A validation failure (bad input, constraint violation).

Enums

FieldDensity
Vertical density of a field.
PillTone
The semantic intent of a StatusPill.
SubtitlePosition
Where a SuperAppBar / SuperSliverAppBar subtitle is placed relative to its title.
SuperButtonVariant
SuperDeviceMode
The responsive form-factor a SuperMaterialThemeData is generated for.
SuperListTileAlignment
How the title / subtitle stack aligns against tall leading/trailing content.
SuperMarker
The three intents a section-marker bar can express.
SuperSectionHeaderStyle
The visual style of a SuperSectionHeader.
SuperSemanticIntent
The six semantic intents expressed by SuperSemanticColors.
SuperSnackBarTone
The semantic intent of a SuperSnackBar. Drives the leading glyph and the accent color of the icon + action label.
SuperTileDensity
Density presets shared by the tile family. Drives interior padding, the minimum row height and the leading/gap rhythm so dense ERP data-entry screens and roomy dashboards read from the same scale.

Extensions

SuperColorX on Color
Color helpers used across the Super toolkit.
SuperContextX on BuildContext

Functions

arrowGoesInto(LogicalKeyboardKey key, TextDirection dir) → bool
True when a horizontal arrow key points toward deeper nesting for dir — the arrow a tree treats as expand / step-in (right in LTR, left in RTL).
horizontalStep(LogicalKeyboardKey key, TextDirection dir) → int
Resolves a horizontal arrow key to a logical index step for text dir. Returns +1 / -1 for right/left (mirrored under RTL), else 0.
isCommandPressed(Set<LogicalKeyboardKey> pressed) → bool
True when the platform's primary command modifier is held (⌘ on macOS, Ctrl elsewhere). Use for copy/paste/select-all/undo shortcuts.
superTileBorder(SuperThemeData t, SuperTileVisualState state, {bool bordered = true}) → Border?
The border a tile shows in state — accent when selected/focused, else the hairline (or none).
superTileFill(SuperThemeData t, SuperTileVisualState state, {Color? base}) → Color
Resolves the GeniusLink surface fill for a tile in state over base.

Typedefs

Json = Map<String, dynamic>
A JSON object as decoded by dart:convert.
JsonList = List
A JSON list.
Result<T> = ({Failure? failure, T? value})
The result of an operation that can fail: either a Failure (left) or a value of type T (right). A lightweight, dependency-free Either.
RowValidator<T> = String? Function(String value, T row)
A row-aware validator: the value plus the whole row it belongs to.
Validator<T> = String? Function(T value)
A synchronous validator returning an error message, or null when valid.
ValidityChanged = void Function(bool valid)
Reports a field's validity to a host (true == valid).

Exceptions / Errors

CacheException
RemoteException
SuperException
Base type for exceptions thrown inside the data layer.