Tm Quick Action

Top Bar Quick Menu

Build new Tabame quick menu buttons by matching the existing launcher-to-modal structure and the "Instrument Panel" design language used across bookmarks, apps, vault, currency converter, and timezone.

Use these files as the baseline references:

• lib/widgets/itzy/quickmenu/button_bookmarks.dart
• lib/widgets/itzy/quickmenu/button_apps.dart
• lib/widgets/itzy/quickmenu/button_vault.dart
• lib/widgets/itzy/quickmenu/button_currency_converter.dart
• lib/widgets/itzy/quickmenu/button_timezone.dart
• lib/widgets/widgets/panel_header.dart, lib/widgets/widgets/quick_actions_item.dart, lib/models/util/quickmenu_modal.dart

1. Design Philosophy

• High Performance: Interfaces should feel like professional tools (DAWs, IDEs, flight panels) – fast, utilitarian, desktop-oriented.
• Information Density: Maximize data visibility in small spaces without causing cognitive overload.
• Tactile Feedback: Every interaction (hover, drag, tap) must have immediate, precise visual feedback.
• Distilled Aesthetics: Ruthlessly remove generic "AI slop" or standard Material/Cupertino defaults. Avoid glossy/high-glow effects or saturated solid blocks. Use custom shapes, subtle outlines, and alpha-blended color to keep a technical, matte tone.

2. Core Pattern

Start with a small launcher widget that only opens the panel:

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

  @override
  Widget build(BuildContext context) {
    return QuickActionItem(
      message: "Example",
      icon: const Icon(Icons.extension_rounded),
      onTap: () => showQuickMenuModal(
        context: context,
        child: const ExamplePanel(),
      ),
    );
  }
}

Follow this split:

• Keep the top-bar button thin. It should declare the label, icon, and modal entry point only.
• Put state, async work, controllers, and layout logic inside the panel widget.
• Prefer StatelessWidget for the launcher unless the button itself owns transient state.
• Use showQuickMenuModal() for most buttons. Pass maxWidth or heightFactor only when the interaction clearly needs it, like timezone.

3. Global Registration

Every new quick menu button must be registered in lib/models/util/quick_action_list.dart:

// 1. Add import at the top (alphabetical)
import '../../widgets/itzy/quickmenu/button_example.dart';

// 2. Add an entry to quickActionsMap – key is the button's identifier,
//    widget is a factory (not a const instance directly)
final Map<String, QuickAction> quickActionsMap = <String, QuickAction>{
  ...
  "ExampleButton": QuickAction(
    icon: Icons.extension_rounded,
    widget: () => const ExampleButton(),
  ),
};

QuickAction.name is optional and rarely set – the map key is what drives discovery/pinning in settings and the top/bottom bars (see lib/widgets/quickmenu/top_bar.dart, lib/widgets/quickmenu/bottom_bar.dart, lib/widgets/interface/quickmenu/quickactions_settings.dart).

4. Panel Structure

Build the panel as a vertical layout with a strong header and one flexible content area:

class ExamplePanel extends StatefulWidget {
  const ExamplePanel({super.key});

  @override
  State<ExamplePanel> createState() => _ExamplePanelState();
}

class _ExamplePanelState extends State<ExamplePanel> {
  @override
  Widget build(BuildContext context) {
    return Column(
      mainAxisSize: MainAxisSize.min,
      crossAxisAlignment: C.start,
      children: <Widget>[
        const PanelHeader(
          title: "Example",
          icon: Icons.extension_rounded,
        ),
        Flexible(
          child: Material(
            type: MaterialType.transparency,
            child: _buildBody(),
          ),
        ),
      ],
    );
  }
}

PanelHeader (lib/widgets/widgets/panel_header.dart) takes title, icon, and optionally accent (defaults to Design.accent), buttonPressed + buttonIcon (+ buttonTooltip) for a single trailing action, and extraActions for more. It also handles window-drag behavior – always put it first in the column, never recreate its drag/border chrome manually.

Prefer this hierarchy:

• PanelHeader first.
• Flexible body second.
• WindowsScrollView, ListView, or MouseScrollWidget inside the body depending on content density – never SingleChildScrollView.
• Material(type: MaterialType.transparency) around interactive body content when Ink reactions need a Material ancestor.

5. Design Tokens

Reference Design (lib/models/settings.dart) directly inside widget bodies – do not thread accent/onSurface-style colors through function parameters; that indirection is unnecessary now that Design is globally available.

• Accent: Design.accent – drives all interactive/selected state.
• Text: Design.text – replaces Theme.of(context).colorScheme.onSurface.
• Base font size: Design.baseFontSize – replaces hardcoded sizes; add an offset like Design.baseFontSize + 2.5 for emphasis.
• Border radius: Design.borderRadius for theme-driven rounding when a fixed radius isn't called for.

Typography

• Body: Design.baseFontSize to Design.baseFontSize + 2 (≈11.5–13px).
• Metadata/small labels: Design.baseFontSize - 1 to Design.baseFontSize + 0.5 (≈9–11px).
• Headings: Design.baseFontSize + 2.5 and up.
• Letter spacing: 0.3 to 0.7 for technical/uppercase labels.
• Weights: FontWeight.w400 for content, w600/w700 for labels, counts, and headings – never w900.

Spacing & Rhythm

• Panel padding: EdgeInsets.fromLTRB(8, 8, 8, 10) for the main list/body.
• Card spacing: SizedBox(height: 8) between vertical cards.
• Card inner padding: EdgeInsets.fromLTRB(10, 9, 10, 8).
• Section spacing: SizedBox(height: 2) between a header and its description; SizedBox(height: 8-10) before interactive controls (sliders, chips).
• Outer padding: 10px (compact) to 14px (comfortable).
• Standard "bar" item heights: 25px or 30px. Sliders are 20px high.
• Rounded corners: usually 8, 10, 12, 14, 16, or 18.

Colors

• Never use pure black/white. Use withAlpha to layer on the theme surface.
• Cards/rows background: Design.text.withAlpha(7-8).
• Card/row border: Design.text.withAlpha(16).
• Soft accent washes for cards/pills: Design.accent.withAlpha(10) to Design.accent.withAlpha(28).
• Low-contrast separators: Design.text.withAlpha(18) to Design.text.withAlpha(32).
• Hover (active): Design.accent.withAlpha(60). Hover/selection (passive): Design.accent.withAlpha(10-18).
• Selected/emphasized borders: Design.accent.withAlpha(70-90).

6. Key Components & Patterns

Section Labels

Divide content within a panel with labels instead of standard headers – pattern is icon + label + optional count pill + divider:

Widget _buildSectionLabel({required String label, required int count, required IconData icon}) {
  return Row(
    children: <Widget>[
      Icon(icon, size: 14, color: Design.accent),
      const SizedBox(width: 6),
      Text(
        label.toUpperCase(),
        style: TextStyle(
          fontSize: Design.baseFontSize + 1,
          fontWeight: FontWeight.w700,
          letterSpacing: 0.5,
          color: Design.text,
        ),
      ),
      const SizedBox(width: 6),
      Container(
        padding: const EdgeInsets.symmetric(horizontal: 6, vertical: 2),
        decoration: BoxDecoration(color: Design.accent.withAlpha(28), borderRadius: BorderRadius.circular(99)),
        child: Text("$count", style: TextStyle(fontSize: Design.baseFontSize, color: Design.accent)),
      ),
      const SizedBox(width: 8),
      Expanded(child: Divider(height: 1, color: Design.text.withAlpha(20))),
    ],
  );
}

Configuration Cards

A vertical container grouping related settings (used for sidebars, modals, and narrow config panels like the QuickMenu Design panel):

Container(
  padding: const EdgeInsets.fromLTRB(10, 9, 10, 8),
  decoration: BoxDecoration(
    color: Design.text.withAlpha(7),
    borderRadius: BorderRadius.circular(10),
    border: Border.all(color: Design.text.withAlpha(16)),
  ),
  child: Column(
    crossAxisAlignment: C.start,
    children: <Widget>[
      Row(
        children: <Widget>[
          Expanded(child: Column(...)), // Title & description
          _buildMetaChip(...),          // Value badge
        ],
      ),
      const SizedBox(height: 8),
      Slider(...), // Interactive control
    ],
  ),
)

Highlighted/active card state: background Design.accent.withAlpha(10), border Design.accent.withAlpha(30).

Meta Chips

Compact badges for showing values (hex codes, percentages, toggles):

• Shape: StadiumBorder / BorderRadius.circular(999).
• Padding: EdgeInsets.symmetric(horizontal: 7, vertical: 3).
• Visuals: low-alpha colored background with high-alpha colored text, fontWeight: FontWeight.w700.

Selection Rails (ChoiceChip)

Used for mode switching within a card:

• ChoiceChip with visualDensity: VisualDensity.compact.
• labelStyle: fontSize: Design.baseFontSize + 1.5.
• Selected color: Design.accent.withAlpha(18).

Color Swatches/Pickers

• Use a small swatch (20-22px circle) to show active colors.
• Use InkWell text labels (e.g. "Pick") instead of heavy buttons for secondary actions.

Sticky Bottom Action Bar

Major actions like "Save Changes" or "Add Item" anchor at the bottom while content scrolls independently above:

Widget _buildFixedBottomBar({required String label, required VoidCallback onTap}) {
  return Container(
    padding: const EdgeInsets.symmetric(horizontal: 16, vertical: 12),
    decoration: BoxDecoration(
      border: Border(top: BorderSide(color: Design.text.withAlpha(15))),
    ),
    child: Center(
      child: InkWell(
        onTap: onTap,
        borderRadius: BorderRadius.circular(8),
        child: AnimatedContainer(
          duration: const Duration(milliseconds: 150),
          padding: const EdgeInsets.symmetric(vertical: 9, horizontal: 32),
          decoration: BoxDecoration(
            color: Design.accent.withAlpha(28),
            borderRadius: BorderRadius.circular(8),
            border: Border.all(color: Design.accent.withAlpha(80), width: 1),
          ),
          child: Text(
            label,
            style: TextStyle(
              fontSize: Design.baseFontSize + 1.5,
              fontWeight: FontWeight.w700,
              letterSpacing: 0.5,
              color: Design.accent,
            ),
          ),
        ),
      ),
    ),
  );
}

Avoid "screaming" solid backgrounds, heavy shadows, or glossy gradients – use a subtle accent fill with a more defined accent border instead, and precise single-pixel borders elsewhere.

Use these reference-specific patterns for inspiration:

• button_bookmarks.dart: compact hover rows, light accent bar, grouped sections, restrained text.
• button_apps.dart: collapsible category sections, grid-or-list body, simple empty state, low-noise chrome.
• button_vault.dart: stateful multi-step panel flow, header actions that change with mode, inline error strip.
• button_currency_converter.dart: prominent result card, input-first layout, data cards with light borders, loading states.
• button_timezone.dart: dual-mode panel with planner/settings toggle, chips, search field, structured result cards.

7. Interaction Rules

Design the panel for quick execution, not deep navigation:

• Make the first useful action obvious near the top.
• Keep primary flows inside one modal when possible.
• Prefer inline state transitions over opening nested dialogs unless destructive confirmation is required.
• Close the quick menu after launching an external app, file, or command.
• Do not hide critical actions behind hover-only affordances if the action is essential.
• Use hover feedback on desktop rows and cards – subtle hover tint plus an optional accent bar or trailing icon.
• For list items that should not be traversed with arrows/tabs, wrap them with CancelTraversal(child:).

For button actions:

• Launch apps and files with WinUtils.open(...).
• Close the quick menu after external execution with QuickMenuFunctions.hideQuickMenu() when that matches existing behavior.
• Persist settings with Boxes.updateSettings(...) and mirror to in-memory state.