diff --git a/docs/garage-ui-style-guide.md b/docs/garage-ui-style-guide.md index db2c3c0..7d03de7 100644 --- a/docs/garage-ui-style-guide.md +++ b/docs/garage-ui-style-guide.md @@ -393,6 +393,77 @@ Plainest thing that works. If a page wants more, it's asking for a new garage_ui component, not a one-off. +## Rules and paradigms + +The sections above say which widget. These say what a screen is *for* — +the calls that aren't visible from the API, learned the hard way from apps +that used the right widgets and still came out wrong. + +### The rail header is the app, not the page + +The band at the top of a nav rail says whose app this is. It is never the +current section's name — that's already the selected nav item, and saying it +twice in the accent turns the header into a page title stuck in the wrong +place. + +- The app's name as a wordmark: all caps, the black cut (w900), default + foreground. Not `primary`, not `.large()`. +- One muted w600 line under it, `textXs`, and the wordmark sized so it's + exactly as wide as that line (measure both, scale by the ratio, clamp). + The hub's `GarageHeader(fillWidth: true)` is the reference. +- The line under it is the app's *context* — the company for the hub, the + stand you're working for an app bound to one. This is the one place a + name is allowed in a subtitle-shaped line, because it's identity, not a + heading. +- The band is `railWidth / 2` tall, contents left-aligned and centred + vertically in a `FittedBox(scaleDown)` so a long context line shrinks the + pair rather than overflowing. +- A full-width `Divider(color: panelBorder)` under it — the wordmark isn't a + destination, so it's ruled off from the list, not sat in it. +- A weight above `.extraBold()` isn't an extension. Go through + `theme.typography.sansStyle(TextStyle(fontWeight: ...))` so the weight picks + the font file; `copyWith(fontWeight:)` on the ambient style gets skia's fake + bold. + + +### A page breathes: the page frame owns its spacing + +A page is a centred reading column: gutter either side, `gapXxl` above the +`PageHeading`, **`gapXxl` under it**, `gapXxl` at the bottom. The gap under +the heading is the biggest on the page on purpose: it separates "what page +this is" from everything on it, so it must be bigger than any gap *between* +things on the page (sections are `gapXxl` apart; nothing inside one is). + +- Gutter: `fontSize * 3` beside a rail, `gapMd` on a phone (sections add + their own `gapXs` on top). Cap at `density.contentMax`. +- The heading gap belongs to whatever builds the page frame (the hub's shell, + an app's page scaffold), not to each screen. Left to screens, every one + picks its own `Gap.xl()` / `Gap.lg()` / nothing, and the pages stop lining + up with each other. +- So the first section heading under a page heading adds **no** space above + itself, because the frame already put it there. Stacking both is how a gap + comes out right on one screen and doubled on the next. +- When in doubt, err roomy. `gapXl` under a title looks fine alone and + cramped beside the hub. + + +### Rule between sections, not just space + +When a page is a stack of separate jobs (fill in the sheet, share it, +check it), whitespace alone doesn't separate them. A heading after a big gap +still reads as a continuation of the section above it, especially when that +section ends in unboxed `SettingsRow`s. Put a rule between them. + +- A full-width `Divider(color: divider)` across the reading column, sitting + in the middle of the `gapXxl` before the next section heading. Not + instead of the gap, and not tight under the heading. +- *Between* sections only. None above the first (the page heading gap is + already there) and none under the last. A rule with nothing after it is + fencing off empty space. +- It's part of the section heading, not something each screen drops in by + hand, so the spacing either side is the same on every page. + + ## Dont copy these Known overrides in the reference apps. They're debt, not patterns. diff --git a/garage_auth/lib/src/garage_auth.dart b/garage_auth/lib/src/garage_auth.dart index ba511ac..1b22b94 100644 --- a/garage_auth/lib/src/garage_auth.dart +++ b/garage_auth/lib/src/garage_auth.dart @@ -102,7 +102,13 @@ class GarageAuth extends ChangeNotifier { // completeSignIn() with the query params. on native it opens the system // browser; the host app catches the inbound deep link and likewise calls // completeSignIn(). this is the lower level half of signIn(). - Future beginSignIn() async { + // + // [handoff] is a code another build of your app minted with + // /auth/handoff/issue - the desktop app sending its user to the web one. It + // stands in for the sign in screen (and consent, when both clients are in + // the same project), so they dont have to sign in twice. A used or expired + // one just means they get the normal sign in. + Future beginSignIn({String? handoff}) async { if (clientId.isEmpty) { throw AuthError("GarageAuth: clientId is empty."); } @@ -127,6 +133,7 @@ class GarageAuth extends ChangeNotifier { "state": state, "code_challenge": challenge, "code_challenge_method": "S256", + if (handoff != null && handoff.isNotEmpty) "_handoff": handoff, }); await _redirect.navigateTo(authUri.toString()); @@ -136,7 +143,7 @@ class GarageAuth extends ChangeNotifier { // future never really "completes" (the page is leaving) — your callback route // drives completeSignIn. on native it's the same begin step; the deep-link // handler completes it. so think of signIn() as "start the flow". - Future signIn() => beginSignIn(); + Future signIn({String? handoff}) => beginSignIn(handoff: handoff); // finishes the exchange. callers pass the query params off the inbound // callback url (web: go_router state.uri.queryParameters, native: parse the diff --git a/garage_ui/lib/garage_ui.dart b/garage_ui/lib/garage_ui.dart index f46e346..c716bfa 100644 --- a/garage_ui/lib/garage_ui.dart +++ b/garage_ui/lib/garage_ui.dart @@ -35,6 +35,7 @@ export "misc.dart"; export "color_input.dart"; export "date_input.dart"; export "panel.dart"; +export "page_heading.dart"; export "editor_chrome.dart"; export "context_menu.dart"; export "properties.dart"; diff --git a/garage_ui/lib/page_heading.dart b/garage_ui/lib/page_heading.dart new file mode 100644 index 0000000..1ae9ff7 --- /dev/null +++ b/garage_ui/lib/page_heading.dart @@ -0,0 +1,85 @@ +import "package:flutter/widgets.dart"; + +import "surface.dart"; +import "theme/garage_theme.dart"; +import "theme/theme_data.dart"; + +/// The heading a page wears above its content. +/// +/// The name a step up, a muted line under it saying what youre looking at, +/// both left aligned on the same margin as whatever follows. Promoted out of +/// the hub, where it was drawn over every section, because A&A's licence page +/// wanted the same thing and a lookalike drifts from the real one within a day +/// of being written. +/// +/// Its a heading, not a bar - nothing chrome coloured, no rule under it, no +/// height of its own beyond what the two lines need. A pane that wants a strip +/// across the top of it wants [ChromeBar] instead. +class PageHeading extends StatelessWidget { + /// How tall this comes out, for a page that needs to know what room is + /// left under it. + /// + /// Derived rather than measured: title on [Density.textLg] over a subtitle + /// on the ambient font, both on Geist's own line box, with a gapXs between. + /// A layout that has to wait for a frame to find this out cant use it on + /// the frame it needs it. + static double heightIn(Density d) => + (d.textLg * Density.geistLineRatio).roundToDouble() + + d.gapXs + + (d.fontSize * Density.geistLineRatio).roundToDouble(); + + const PageHeading({ + required this.title, + this.subtitle, + this.trailing, + super.key, + }); + + final String title; + final String? subtitle; + + /// Sits at the far end of the heading, vertically centred on the whole + /// block rather than on the title line. + /// + /// For the one action that belongs to the SUBJECT rather than to a section + /// of it - Disconnect on an agent, and the like. + final Widget? trailing; + + @override + Widget build(BuildContext context) { + final theme = GarageTheme.of(context); + final density = theme.density; + + final heading = Column( + crossAxisAlignment: CrossAxisAlignment.start, + mainAxisSize: MainAxisSize.min, + children: [ + Text(title, style: theme.typography.normal).large(), + if (subtitle != null) ...[ + const Gap.xs(), + Text( + subtitle!, + style: TextStyle(color: theme.colorScheme.mutedForeground), + ), + ], + ], + ); + + // Nudged in by gapXs: thats the side margin a PropertiesSection carries on + // itself, and without it a heading starts LEFT of the sections it + // introduces - the sort of thing you cant unsee once youve seen it. + return Padding( + padding: EdgeInsets.symmetric(horizontal: density.gapXs), + child: trailing == null + ? heading + : Row( + crossAxisAlignment: CrossAxisAlignment.center, + children: [ + Expanded(child: heading), + Gap(density.gapMd), + trailing!, + ], + ), + ); + } +} diff --git a/garage_ui/lib/properties.dart b/garage_ui/lib/properties.dart index 9162217..55a7a61 100644 --- a/garage_ui/lib/properties.dart +++ b/garage_ui/lib/properties.dart @@ -519,19 +519,18 @@ class PropertiesSection extends StatelessWidget { color: scheme.mutedForeground, ); return Container( - // bottom is gapLg, not gapXs: this margin is what separates one section - // from the NEXT one, and gapXs is the step used between ROWS INSIDE a - // section - so at gapXs a run of sections read as one striped block - // rather than as separate subjects, which is the whole point of giving - // each one its own. Three times the inner step, so the boundary between - // two sections is unambiguously bigger than the boundary between two - // rows. The sides stay gapXs; thats an inset from the pane edge, a - // different job. + // bottom is its own token, not gapXs: this margin is what separates one + // section from the NEXT one, and gapXs is the step used between ROWS + // INSIDE a section - so at gapXs a run of sections read as one striped + // block rather than as separate subjects, which is the whole point of + // giving each one its own. It used to be gapLg flat, which a dense + // editor pane full of sections wears badly, hence the dial. The sides + // stay gapXs; thats an inset from the pane edge, a different job. margin: EdgeInsets.fromLTRB( density.gapXs, 0, density.gapXs, - density.gapLg, + density.propertiesSectionGap, ), decoration: BoxDecoration( color: scheme.card, diff --git a/garage_ui/lib/theme/theme_data.dart b/garage_ui/lib/theme/theme_data.dart index 9eef4e4..2b4867c 100644 --- a/garage_ui/lib/theme/theme_data.dart +++ b/garage_ui/lib/theme/theme_data.dart @@ -96,6 +96,7 @@ class Density { // ---- container-level spacing (panels, popovers, dialogs) ---- this.containerGap = 8.0, this.containerPadding = 16.0, + this.propertiesSectionGap = 6.0, // ---- optical ---- this.controlTextOffset = 0.0, @@ -123,6 +124,7 @@ class Density { listRowIndent = 12.0, containerGap = 10.0, containerPadding = 20.0, + propertiesSectionGap = 15.0, controlTextOffset = 0.0; /// The product tier - for the Garage web apps rather than for A&A. @@ -156,6 +158,7 @@ class Density { listRowIndent = 10.0, containerGap = 10.0, containerPadding = 20.0, + propertiesSectionGap = 15.0, controlTextOffset = 0.0; /// Which tier this token set represents. @@ -230,6 +233,19 @@ class Density { /// and `baseContainerPadding`, which always held the same value.) final double containerPadding; + /// What separates one properties section from the NEXT one. + /// + /// Its own token rather than a step off the gap ladder, because the right + /// answer genuinely isnt the same at every density. A dashboard has a + /// handful of sections and wants air around each so they read as separate + /// subjects; an editor pane stacks eight of them down a 300px column and + /// the air is the thing thats in short supply. Same widget, opposite + /// pressures - so the number is a dial, not a derivation. + /// + /// Whatever its set to it must stay clearly bigger than the gap between two + /// ROWS inside a section, or a run of sections reads as one striped block. + final double propertiesSectionGap; + // ---- optical ---- /// Downward nudge applied to control content so it sits on its optical @@ -443,6 +459,14 @@ class Density { /// The largest step - page-level separation, above the panel scale. double get gapXxl => controlGap * 6; + + /// The inset a page's reading column takes either side, beside a rail. + /// + /// Off the font, not the gap ladder: its measured against the text it + /// frames, 48 at product. Wrong on a phone - a 390pt screen loses a quarter + /// of itself to it - so a phone page wants [gapMd] instead. Was a local + /// `fontSize * 3` in the hub and in every app copying the hub. + double get pageGutter => fontSize * 3; } /// Icon sizes. `small` is the control icon and is derived from the density's diff --git a/garage_ui/lib/theme/typography.dart b/garage_ui/lib/theme/typography.dart index d2f596c..da00c2b 100644 --- a/garage_ui/lib/theme/typography.dart +++ b/garage_ui/lib/theme/typography.dart @@ -70,23 +70,89 @@ extension TextStyleExtension on Widget { style: (t) => TextStyle(fontSize: t.density.textLg), ); - Widget medium() => _StyledText( - child: this, - style: (t) => const TextStyle(fontWeight: FontWeight.w500), - ); - Widget semiBold() => _StyledText( - child: this, - style: (t) => const TextStyle(fontWeight: FontWeight.w600), - ); - Widget bold() => _StyledText( - child: this, - style: (t) => const TextStyle(fontWeight: FontWeight.w700), - ); + // these DONT go through _StyledText. Merging `fontWeight: w800` over an + // already resolved google_fonts family changes nothing about which font + // FILE gets used - the file is the weight - so skia synthesises instead, + // and skia has exactly one fake bold. w600, w700 and w800 all came out the + // same stroke, which is how extraBold ended up looking identical to bold. + Widget medium() => _WeightText(child: this, weight: FontWeight.w500); + Widget semiBold() => _WeightText(child: this, weight: FontWeight.w600); + Widget bold() => _WeightText(child: this, weight: FontWeight.w700); + + /// Top of the ladder. A display weight - for a figure or a name somebody is + /// meant to read across a desk, not for body copy. + Widget extraBold() => _WeightText(child: this, weight: FontWeight.w800); Widget muted() => _StyledText( child: this, style: (t) => TextStyle(color: t.colorScheme.mutedForeground), ); + + /// Geist Mono, keeping whatever size, weight and colour are already in + /// scope. + /// + /// Chains in either order - `.mono().bold()` and `.bold().mono()` both land + /// on the real mono bold, because the weight helpers re-resolve whichever + /// family they find in scope rather than assuming sans. + /// + /// Only w300 and w700 are in main.dart's `pendingFonts`. Any other weight + /// resolves fine and lands a frame or two late. + Widget mono() => _MonoText(child: this); +} + +// mono cant ride on _StyledText the way the weights do. those merge a style +// naming ONE property and dont care what else is in scope, so they compose in +// any order. A family out of google_fonts isnt one property - the family name +// encodes the weight - so this one has to read the inherited style first and +// hand the whole thing over to be re-resolved. +// re-resolves the family for the weight it's setting, keeping whichever face +// is already in scope. sans unless somebody put mono there first. +class _WeightText extends StatelessWidget { + const _WeightText({required this.child, required this.weight}); + + final Widget child; + final FontWeight weight; + + @override + Widget build(BuildContext context) { + final theme = GarageTheme.of(context); + final inherited = DefaultTextStyle.of(context).style; + final wanted = inherited.copyWith(fontWeight: weight); + + // google_fonts names a family "_", so the bit before the + // underscore is the face. taken off typography.mono rather than spelled + // out, so renaming the font doesnt quietly turn every .bold() on a mono + // run back into sans. + String? face(String? family) => family?.split("_").first; + final isMono = face(inherited.fontFamily) == face(theme.typography.mono.fontFamily); + + return DefaultTextStyle.merge( + style: isMono + ? theme.typography.monoStyle(wanted) + : theme.typography.sansStyle(wanted), + child: child, + ); + } +} + +class _MonoText extends StatelessWidget { + const _MonoText({required this.child}); + + final Widget child; + + @override + Widget build(BuildContext context) { + final theme = GarageTheme.of(context); + + // .of(context), not the theme: this is the point of the class. everything + // a caller stacked ABOVE this widget is already merged into here. + final inherited = DefaultTextStyle.of(context).style; + + return DefaultTextStyle.merge( + style: theme.typography.monoStyle(inherited), + child: child, + ); + } } typedef _StyleFromTheme = TextStyle Function(ThemeData theme);