7 Commits
Author SHA1 Message Date
ImBenjiandClaude Opus 5.5 d3b232f0ee feat(garage_updates): an auto updater for garage apps
Asks Garage for the newest release of a project, downloads it with resume,
checks the sha256, installs it beside the old one and restarts into it.
Splash on garage_ui, a native stub and a first time installer for windows,
bundle swap on mac, the system installer on android. No-op on web.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01KHotisA4hV2xmuZsHTksFX
2026-10-12 06:37:02 +01:00
ImBenjiandClaude Opus 5.5 444933b004 feat(garage_ui): an item view in four layouts, a breadcrumb and a file drop target
ItemView draws a set of named things as a list, a two line list, a table
with sortable headers or a grid, and ItemViewModeSwitch lets whoever is
looking pick. Columns drop from the end on a narrow pane before the name
gets squeezed.

Breadcrumb is ghost buttons with chevrons. FileDropTarget takes files
dragged in from outside and shows the focus ring while one is held over
it; it sits on desktop_drop, which is a new dependency.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01KHotisA4hV2xmuZsHTksFX
2026-10-11 06:09:03 +01:00
ImBenjiandClaude Opus 5 cc2fe99d02 fix(garage_ui): a Select trigger was as tall as whatever contained it
The value sat in an Align with no heightFactor, and an Align with no
factor on an axis FILLS that axis. The Row hands its children a loose
vertical constraint, so the trigger took every pixel it was offered:
600 in a test against the default viewport, and "however tall the pane
is" in the app, while every button and field beside it sat on
controlHeight. The other _Btn branch never hit it because it goes
through an IntrinsicHeight.

Width still fills, which is the part that Align was there for.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01FkzfwZf59HNP6R8jXcC1NR
2026-10-11 03:37:08 +01:00
ImBenjiandClaude Opus 5 7aa5cb8f8b feat(garage_ui): PageHeading, a real extraBold, and a mono that chains
The weight helpers went through _StyledText, which merges a style naming
one property and lets everything else in scope stand. That works for a
colour and it doesnt work for a weight: google_fonts encodes the weight
in the family NAME, so merging w800 over an already resolved family
changes no font file and skia synthesises instead. Skia has one fake
bold, so w600, w700 and w800 all came out the same stroke and extraBold
was indistinguishable from bold. They re-resolve the family now, keeping
whichever face is in scope, so .mono().bold() and .bold().mono() both
land on the real mono bold.

PageHeading is lifted out of the hub, where it was drawn by hand above
every section. A&A's licence page wanted the same block and a lookalike
drifts from the original inside a day.

pageGutter and propertiesSectionGap are new density tokens. Both were
local magic numbers - `fontSize * 3` copied into every app that copied
the hub, and a flat gapLg that a dense editor pane full of sections
wears badly.

garage_auth takes an optional handoff code on signIn/beginSignIn and
sends it as _handoff, so a desktop build can hand its user to the web
one without a second sign in.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01FkzfwZf59HNP6R8jXcC1NR
2026-10-09 15:21:48 +01:00
ImBenjiandClaude Opus 5.5 b5e5ed5b75 Add a design system for Claude Design, generated from garage_ui
Tokens come out of garage_ui/tool/export_design_tokens_test.dart, the
components are CSS on top of them, and the cards cover foundations,
components and whole hub and Arcs & Angles screens.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_013F4NWNvYcdeSgqbWMT1VQ7
2026-09-23 23:19:02 +01:00
ImBenjiandClaude Opus 5.5 572c09039f Rewrite the garage_ui style guide, add a ghost destructive button
The old guide had drifted a long way from the package. The new one is
built from blender mode in Arcs & Angles and the Garage hub, and leads with
letting the theme, density and colour scheme do the talking.

ghostDestructive is for remove/revoke/delete in a row, so apps stop hand
colouring ghost buttons red.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_013F4NWNvYcdeSgqbWMT1VQ7
2026-09-23 19:51:45 +01:00
ImBenjiandClaude Opus 5.5 21c380595f Pin by commit in the docs, tags trip pub up
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_013F4NWNvYcdeSgqbWMT1VQ7
2026-09-23 18:53:41 +01:00
97 changed files with 14116 additions and 498 deletions
+13 -7
View File
@@ -30,7 +30,7 @@ Everything here is MIT licensed, see [LICENSE](LICENSE).
## Install
The packages arent on pub.dev. Git-depend on this repo, pick the package with
`path:`, and pin a tag:
`path:`, and pin the commit of a release tag:
```yaml
dependencies:
@@ -38,20 +38,26 @@ dependencies:
git:
url: https://git.imbenji.dev/IMBENJI.NET/Garage-SDKs.git
path: garage_auth
ref: v0.1.0
ref: b2692019197e60d44ddd3ecab4917caf71ff45c3 # v0.1.0
garage_entitlements:
git:
url: https://git.imbenji.dev/IMBENJI.NET/Garage-SDKs.git
path: garage_entitlements
ref: v0.1.0
ref: b2692019197e60d44ddd3ecab4917caf71ff45c3 # v0.1.0
```
Pin a tag, dont float `main`. `garage_entitlements` decides who gets the paid
Pin, dont float `main`. `garage_entitlements` decides who gets the paid
features, and "it changed under us" is not a fun thing to debug.
`garage_entitlements` and `garage_iap` layer on `garage_auth`. You get it
transitively, but declare it too — you'll be constructing a `GarageAuth`
yourself anyway, and keep all of them on the same `ref`.
Use the tag's **full commit hash**, not the tag name. `garage_entitlements` and
`garage_iap` pull in `garage_auth` by relative path, which pub turns into a git
dep at the resolved commit hash — so if your app asks for `garage_auth` at
`v0.1.0`, pub sees two different sources for the same package and refuses to
resolve. Same hash on every garage package and it just works. Keep the tag name
in a comment so you can tell which release it is.
You'll be constructing a `GarageAuth` yourself, so declare `garage_auth`
directly even when you only really want entitlements or iap.
**Working on the SDKs at the same time as an app?** Point the app at a local
checkout with a gitignored `pubspec_overrides.yaml`, so edits hot reload with
+125
View File
@@ -0,0 +1,125 @@
# Garage design system
The look of every Garage app — the hub, the payment portal, Arcs & Angles — as
tokens, CSS and preview cards, for designing new Garage screens.
It's generated from the Flutter package, not drawn separately:
`tokens.css` and `tokens.json` come out of
`garage_ui/tool/export_design_tokens_test.dart`, and `components.css` only
uses those tokens. Don't edit the token files by hand — change garage_ui and
rerun:
```sh
cd garage_ui && flutter test tool/export_design_tokens_test.dart
```
```
design_system/
tokens.css, tokens.json colours, density, type, shape — generated
components.css the components, built on the tokens
foundations/ colour, type, spacing, shape, density
components/ buttons, fields, selects, lists, dialogs, …
patterns/ whole screens from the hub and Arcs & Angles
```
## The one rule: let the theme speak
The colour scheme, the density and the component's variant decide every
colour, font size, weight, icon size, padding, radius and gap. Designing a
Garage screen is choosing **which component** and **which variant**. Then
leave it alone.
- No custom colours, font sizes or weights on a component or its contents.
- No icon sizes or colours — an icon takes them from where it sits.
- No hand-picked padding, gaps or radii. Use the `--gap-*` and `--radius-*`
tokens, and let components that already carry spacing keep it.
- No home-made badges, pills, warning boxes or popovers built from a box with
a fill and a border. If a component doesnt exist, that's a gap in the system,
not an invitation.
- No shadows. Everything is flat — surfaces are separated by a step in
lightness and a hairline border.
If something looks wrong, the answer is a different variant or a different
component.
## Setting up a screen
```html
<html data-scheme="carbon" data-density="product">
<link rel="stylesheet" href="components.css">
```
- **Scheme:** `carbon` (default — true black, no accent hue; what the Garage
apps run), `dark`, `light`.
- **Density:** `product` (default — web and product apps, 12px text, 33px
controls), `compact` (dense desktop tools like Arcs & Angles, 10px text, 23px
controls), `normal` (compact but roomier). Pick one per app. Don't mix.
Type is Geist, and Geist Mono for numbers and readouts. Body text is weight
300, control labels 400, primary buttons 600.
## Layout
Every Garage screen is the same shape: a `chrome` ground, `panel`s standing on
it, and `panel-gap` gutters between them.
```html
<div class="shell">
<nav class="panel sunken">…rail…</nav>
<main class="panel">…workspace…</main>
</div>
```
Headers and footers are `chrome-bar`s. Only one panel is highlighted
(`panel active`) at a time.
A hub page is a centred column inside the workspace panel: a `page-heading`,
then either a stack of `properties-section`s or `sub-heading` + `settings-list`
forms. See `patterns/`.
## Choosing components
**Buttons**
| Variant | For |
|---|---|
| `primary` | the one action on the view, or the thing that's on / chosen |
| `secondary` | a neutral filled control; the selected nav item; a button welded to a field |
| `outline` | a normal action that isn't the main one — Cancel, Retry |
| `ghost` | chrome, toolbars, nav items, row actions |
| `ghost-destructive` | remove / revoke / delete as a row action |
| `destructive` | the confirm button of a destructive dialog |
| `link`, `text` | inline in copy |
Icon-only buttons are `btn icon-only`. A nav item is ghost with a leading icon,
left-aligned, secondary when selected — never primary. Toolbar toggles are
primary when on, outline when off.
**Fields**
- Free text: the default outline `field`.
- Values inside a properties section: `field secondary`. A read-only value is a
read-only secondary field — **never bare text** in a value slot.
- Selects: secondary in a properties section, `ghost` in a settings list,
outline elsewhere.
- Numbers in an editor: secondary, centred, unit as a muted suffix.
**Lists**
- `properties-section` — a boxed card of label/value rows. Inspectors,
account pages, one card per record in a list. Controls inside are secondary.
- `settings-list` — unboxed rows ruled between entries, for forms. Controls
inside are ghost; text fields are outline.
**Subtitles** are short static descriptions of what something is. Never live
data — no counts, dates, names, emails or statuses. Facts go in rows.
**Dialogs** are `dialog` with the actions in their band: outline Cancel, then
a primary or destructive confirm. Max width is fixed; don't widen it.
**Loading** is a spinner. No skeletons. **Empty** is one muted line.
**Error** is the message, muted, and an outline Retry.
+538
View File
@@ -0,0 +1,538 @@
/* garage_ui components, in plain css. Built on tokens.css - every value here
is a token or a formula the flutter package uses too. If something needs a
new number, it goes in garage_ui first and comes out through the export.
The odd literal is only here because the dart source has the same literal,
and its commented where it happens.
Set data-scheme / data-density on <html> (or any container) and everything
below follows.
States: every :hover / :active has an .is-hovered / .is-active twin, so a
card can show a state sat still without anyone pointing at it. */
@import url("tokens.css");
*, *::before, *::after { box-sizing: border-box; }
body, .gu {
margin: 0;
background: var(--background);
color: var(--foreground);
font-family: var(--font-sans);
font-size: var(--font-size);
line-height: var(--line-height);
font-weight: var(--weight-body);
-webkit-font-smoothing: antialiased;
}
/* a nested scheme / density container has to re-resolve the things body set,
or it just inherits the outer values and only the components change */
[data-scheme] { background: var(--background); color: var(--foreground); }
[data-density] { font-size: var(--font-size); line-height: var(--line-height); }
/* ---- type ------------------------------------------------------------ */
.text-xxs { font-size: var(--text-xxs); }
.text-xs { font-size: var(--text-xs); }
.text-sm { font-size: var(--text-sm); }
.text-lg { font-size: var(--text-lg); line-height: 1.3; }
.medium { font-weight: var(--weight-medium); }
.semibold { font-weight: var(--weight-semibold); }
.bold { font-weight: 700; }
.muted { color: var(--muted-foreground); }
.mono { font-family: var(--font-mono); font-weight: 400; }
/* PageHeading - title a step up, muted line under it, gapXs in from the side
(the margin a properties section carries). trailing sits gapMd off the
heading, centred on the whole block not the title line */
.page-heading { padding: 0 var(--gap-xs); display: grid; grid-template-columns: minmax(0, 1fr) auto; column-gap: var(--gap-md); align-items: center; }
.page-heading > :not(.trailing) { grid-column: 1; }
.page-heading .title { font-size: var(--text-lg); font-weight: var(--weight-control); line-height: 1.3; }
.page-heading .subtitle { margin-top: var(--gap-xs); color: var(--muted-foreground); }
/* the hub puts a gapXs between two asides when theres more then one */
.page-heading > .trailing { grid-column: 2; grid-row: 1 / span 2; display: flex; align-items: center; gap: var(--gap-xs); }
/* subHeading - the same shape one size down, more room over it than under */
.sub-heading { padding: var(--gap-xxl) var(--gap-xs) var(--gap-lg); display: grid; grid-template-columns: minmax(0, 1fr) auto; column-gap: var(--gap-md); align-items: center; }
.sub-heading > :not(.action) { grid-column: 1; }
.sub-heading .title { font-size: var(--text-sm); font-weight: var(--weight-semibold); }
.sub-heading .subtitle { margin-top: var(--gap-xxs); font-size: var(--text-xxs); color: var(--muted-foreground); }
.sub-heading > .action { grid-column: 2; grid-row: 1 / span 2; display: flex; align-items: center; gap: var(--gap-xs); }
.caption { font-size: var(--text-xxs); font-weight: var(--weight-semibold); color: var(--muted-foreground); }
/* ---- icons ----------------------------------------------------------- */
/* lucide, as inline svg. size comes from where it sits, never the call site */
.icon { width: var(--icon-sm); height: var(--icon-sm); flex: none; stroke: currentColor; fill: none;
stroke-width: 2; stroke-linecap: round; stroke-linejoin: round; }
.icon-md { width: var(--icon-md); height: var(--icon-md); }
.icon-lg { width: var(--icon-lg); height: var(--icon-lg); }
/* ---- buttons --------------------------------------------------------- */
/* every variant shares the same control padding - only the density moves it.
link and text included, they just dont paint a box */
.btn {
display: inline-flex; align-items: center; justify-content: center;
gap: var(--control-gap);
height: var(--control-height);
padding: 0 var(--control-padding-x);
border: var(--control-border-width) solid transparent;
border-radius: var(--radius-md);
background: transparent;
color: var(--foreground);
font: inherit; font-size: var(--font-size); font-weight: var(--weight-control);
white-space: nowrap; cursor: pointer; user-select: none;
outline: none;
}
.btn:focus-visible { box-shadow: 0 0 0 3px color-mix(in srgb, var(--ring) 50%, transparent); }
.btn:disabled, .btn.disabled { cursor: default; color: var(--muted-foreground); }
.btn.icon-only { width: var(--control-height); padding: 0; }
.btn.stretch { display: flex; width: 100%; }
.btn.align-left { justify-content: flex-start; }
.btn.primary { background: var(--primary); border-color: var(--control-border); color: var(--primary-foreground); font-weight: var(--weight-semibold); }
.btn.primary:hover:not(:disabled), .btn.primary.is-hovered { background: var(--primary-hovered); }
.btn.secondary { background: var(--secondary); border-color: var(--control-border); color: var(--secondary-foreground); }
.btn.secondary:hover:not(:disabled), .btn.secondary.is-hovered { background: var(--secondary-hovered); }
/* outline shares the text field's fill + stroke on purpose - one family */
.btn.outline { background: var(--control-fill); border-color: var(--control-border); }
.btn.outline .icon { color: var(--muted-foreground); }
.btn.outline:hover:not(:disabled), .btn.outline.is-hovered { background: var(--control-fill-hovered); }
/* ghost tints what its standing on instead of painting a colour */
.btn.ghost:hover:not(:disabled), .btn.ghost.is-hovered { background: color-mix(in srgb, var(--foreground) 7%, transparent); }
.btn.ghost:active:not(:disabled), .btn.ghost.is-active { background: color-mix(in srgb, var(--foreground) 12%, transparent); }
.btn.ghost-destructive { color: var(--destructive); }
.btn.ghost-destructive:hover:not(:disabled), .btn.ghost-destructive.is-hovered { background: color-mix(in srgb, var(--destructive) 12%, transparent); }
.btn.ghost-destructive:active:not(:disabled), .btn.ghost-destructive.is-active { background: color-mix(in srgb, var(--destructive) 20%, transparent); }
/* white is a literal in button.dart - "straight up white regardless of light or dark mode" */
.btn.destructive { background: color-mix(in srgb, var(--destructive) 50%, transparent); color: #fff; border-color: transparent; }
.btn.destructive:hover:not(:disabled), .btn.destructive.is-hovered { background: color-mix(in srgb, var(--destructive) 80%, transparent); }
.btn.link:hover:not(:disabled), .btn.link.is-hovered { text-decoration: underline; }
.btn.text { color: var(--muted-foreground); }
.btn.text:hover:not(:disabled), .btn.text.is-hovered { color: var(--primary); }
/* disabled, per variant, straight off button.dart. primary goes to a muted
foreground slab so its label still reads; secondary keeps its fill and
only the label dims; destructive swaps to the primary foreground */
.btn.primary:disabled, .btn.primary.disabled { background: var(--muted-foreground); color: var(--primary-foreground); }
.btn.secondary:disabled, .btn.secondary.disabled { background: var(--secondary); color: var(--muted-foreground); }
.btn.ghost-destructive:disabled, .btn.ghost-destructive.disabled { background: transparent; color: var(--muted-foreground); }
.btn.destructive:disabled, .btn.destructive.disabled { background: var(--primary-foreground); color: var(--muted-foreground); }
/* text has no disabled look in the source, it just stays muted */
.btn.text:disabled, .btn.text.disabled { color: var(--muted-foreground); }
/* button group - joined, only the outer corners round */
.btn-group { display: inline-flex; }
.btn-group > * { border-radius: 0; }
.btn-group > *:first-child { border-top-left-radius: var(--radius-md); border-bottom-left-radius: var(--radius-md); }
.btn-group > *:last-child { border-top-right-radius: var(--radius-md); border-bottom-right-radius: var(--radius-md); }
.btn-group > * + * { margin-left: calc(var(--control-border-width) * -1); }
.btn-group.fill { display: flex; }
.btn-group.fill > * { flex: 1; }
/* span: the group takes the width its given and ONE member (.grow) takes the
slack - a field with its IconButton welded on, the button keeping its square */
.btn-group.span { display: flex; width: 100%; }
.btn-group > .grow { flex: 1; min-width: 0; }
.btn-group.vertical { flex-direction: column; }
.btn-group.vertical > * { border-radius: 0; }
.btn-group.vertical > *:first-child { border-radius: var(--radius-md) var(--radius-md) 0 0; }
.btn-group.vertical > *:last-child { border-radius: 0 0 var(--radius-md) var(--radius-md); }
.btn-group.vertical > *:only-child { border-radius: var(--radius-md); }
.btn-group.vertical > * + * { margin-left: 0; margin-top: calc(var(--control-border-width) * -1); }
/* a group inside a group - a corner only rounds where BOTH groups say so
(ButtonGroupCorners.merge, its a product of the two) */
.btn-group:not(.vertical) > .btn-group:not(:first-child) > * { border-top-left-radius: 0; border-bottom-left-radius: 0; }
.btn-group:not(.vertical) > .btn-group:not(:last-child) > * { border-top-right-radius: 0; border-bottom-right-radius: 0; }
.btn-group.vertical > .btn-group:not(:first-child) > * { border-top-left-radius: 0; border-top-right-radius: 0; }
.btn-group.vertical > .btn-group:not(:last-child) > * { border-bottom-left-radius: 0; border-bottom-right-radius: 0; }
/* ---- text fields ----------------------------------------------------- */
.field {
display: inline-flex; align-items: center; gap: var(--control-gap);
height: var(--control-height);
padding: 0 calc(var(--control-padding-x) - var(--control-border-width));
background: var(--control-fill);
border: var(--control-border-width) solid var(--control-border);
border-radius: var(--radius-md);
color: var(--foreground);
font-weight: var(--weight-control);
min-width: 0;
}
/* only an outline field that can be typed in reacts - secondary is a flat
secondary fill in every state, and a read only one is just looked at */
.field:not(.secondary):not(.readonly):hover, .field:not(.secondary):not(.readonly).is-hovered { background: var(--control-fill-hovered); }
.field:not(.secondary):not(.readonly):focus-within, .field:not(.secondary):not(.readonly).is-focused { background: var(--control-fill-focused); }
.field input, .field textarea {
all: unset; flex: 1; min-width: 0; width: 100%;
font-family: var(--font-sans); font-size: var(--font-size); font-weight: var(--weight-control);
color: inherit;
}
.field input::placeholder { color: var(--muted-foreground); }
.field .icon, .field .unit { color: var(--muted-foreground); }
.field.secondary { background: var(--secondary); color: var(--secondary-foreground); }
.field.secondary .icon { color: var(--secondary-foreground); }
/* one rule for "you cant change this" - the value AND the icons beside it */
.field.readonly, .field.readonly .icon { color: var(--muted-foreground); }
.field.center input { text-align: center; }
/* ValueField(monospace:) - for ids and skus, read a character at a time */
.field.mono input { font-family: var(--font-mono); }
/* a rejected value: the outline goes full destructive, never the fill */
.field.error { border-color: var(--destructive); }
.field.stretch { display: flex; width: 100%; }
/* ---- select ---------------------------------------------------------- */
/* the value sits in the middle of the TRIGGER - a chevron's worth of nothing
on the left balances the chevron on the right */
.select { display: inline-flex; align-items: center; justify-content: space-between; cursor: pointer; gap: var(--control-gap);
height: var(--control-height); padding: 0 calc(var(--control-padding-x) - var(--control-border-width));
background: var(--control-fill); border: var(--control-border-width) solid var(--control-border);
border-radius: var(--radius-md); color: var(--foreground); font-weight: var(--weight-control); white-space: nowrap; }
.select::before { content: ""; flex: none; width: var(--icon-sm); }
.select > span { flex: 1; min-width: 0; text-align: center; }
.select .placeholder { color: var(--muted-foreground); }
.select .chevron { color: color-mix(in srgb, currentColor 50%, transparent); }
.select:hover, .select.is-hovered { background: var(--control-fill-hovered); }
.select.secondary { background: var(--secondary); color: var(--secondary-foreground); }
.select.secondary:hover, .select.secondary.is-hovered { background: var(--secondary-hovered); }
.select.ghost { background: transparent; border-color: transparent; }
.select.ghost:hover, .select.ghost.is-hovered { background: var(--popover-item-hovered); }
.select.disabled { color: var(--muted-foreground); cursor: default; }
.select.disabled:hover { background: var(--control-fill); }
.select.secondary.disabled:hover { background: var(--secondary); }
.select.ghost.disabled:hover { background: transparent; }
.select.error { border-color: var(--destructive); }
/* the select popup - its own surface, not a menu. inset is half the container
gap, the corner is concentric with the rows (less 2, a literal in
select.dart - the full sum read too soft) */
.select-popup {
display: inline-flex; flex-direction: column; gap: var(--gap-xxs);
padding: calc(var(--container-gap) * 0.5);
background: var(--popover);
border: var(--control-border-width) solid var(--popover-border);
border-radius: calc(var(--radius-md) + var(--container-gap) * 0.5 + var(--control-border-width) - 2px);
color: var(--foreground);
}
.select-popup .option {
display: flex; align-items: center; justify-content: space-between; gap: var(--control-gap);
height: var(--popup-row-height);
padding: 0 calc(var(--control-padding-x) - var(--control-border-width));
border: var(--control-border-width) solid transparent;
border-radius: var(--radius-md);
font-weight: var(--weight-control); white-space: nowrap; cursor: default;
}
.select-popup .option:hover, .select-popup .option.is-hovered { background: var(--popover-item-hovered); }
.select-popup .option.disabled { color: var(--muted-foreground); }
/* the selected row IS a secondary button, stroke and all, with the check */
.select-popup .option.selected { background: var(--secondary); border-color: var(--control-border); color: var(--secondary-foreground); }
.select-popup .option.selected:hover, .select-popup .option.selected.is-hovered { background: var(--secondary-hovered); }
/* once anything is selected every row reserves the check column, mirrored on
the left, so the labels stay centred on the row */
.select-popup:has(.option.selected) .option::before,
.select-popup:has(.option.selected) .option:not(.selected)::after { content: ""; flex: none; width: var(--icon-sm); }
/* ---- popovers, menus, tooltips --------------------------------------- */
/* MenuPopup - the 2px inset and 1px border are literals in menu.dart */
.popover {
display: inline-flex; flex-direction: column;
background: var(--popover);
border: 1px solid var(--popover-border);
border-radius: var(--radius-md);
padding: 2px;
font-weight: var(--weight-control);
}
/* a row: an 18px icon slot and a 4px gap after it, the icon nudged toward the
edge by (4 - padding) / 2. 18, 4 and the 4px row radius are all literals in
menu.dart */
.menu-item {
display: flex; align-items: center; gap: 4px;
height: var(--menu-row-height);
padding: 0 var(--control-padding-x);
border-radius: 4px;
color: var(--foreground); font-weight: var(--weight-control); white-space: nowrap; cursor: default;
}
.menu-item > .icon:first-child { margin: 0 calc((18px - var(--icon-sm)) / 2); position: relative; left: calc((4px - var(--control-padding-x)) / 2); }
.menu-item .icon { color: var(--muted-foreground); }
.menu-item .shortcut { margin-left: auto; padding-left: var(--container-gap); color: var(--muted-foreground); font-size: var(--font-size); }
.menu-item:hover, .menu-item.is-hovered { background: var(--row-hovered); }
.menu-item.disabled { color: color-mix(in srgb, var(--foreground) 50%, transparent); }
.menu-item.disabled .icon { color: color-mix(in srgb, var(--muted-foreground) 50%, transparent); }
.menu-item.disabled:hover { background: transparent; }
/* MenuLabel - same padding as a row, so the same height, just semibold */
.menu-label { display: flex; align-items: center; height: var(--menu-row-height); padding: 0 var(--control-padding-x); font-weight: var(--weight-semibold); white-space: nowrap; }
/* 4px either side is a literal in menu.dart */
.menu-divider { height: 1px; background: var(--divider); margin: 4px 0; }
/* TooltipContainer - three quarters of the container padding across, three
quarters of the container gap down */
.tooltip {
display: inline-block;
background: var(--tooltip-background);
border: 1px solid var(--tooltip-border);
border-radius: var(--radius-sm);
padding: calc(var(--container-gap) * 0.75) calc(var(--container-padding) * 0.75);
color: var(--foreground);
font-size: var(--font-size); font-weight: var(--weight-control);
}
/* ---- selection controls ---------------------------------------------- */
/* 16px box, 1px border - literals in selection_controls.dart */
.checkbox {
display: inline-flex; align-items: center; justify-content: center; flex: none;
width: 16px; height: 16px;
background: var(--secondary);
border: 1px solid var(--control-border);
border-radius: var(--radius-sm);
}
.checkbox.checked { background: var(--primary); border-color: var(--primary); }
/* the tick is drawn, not an icon: a 9 x 6.5 check on a 1px round stroke, same
geometry as AnimatedCheckPainter. the mask box is half a pixel bigger each
side so the round caps dont get clipped */
.checkbox.checked::after {
content: ""; width: 10px; height: 7.5px;
background: var(--primary-foreground);
-webkit-mask: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='-0.5 -0.5 10 7.5'%3E%3Cpolyline points='0,3.25 3.15,6.5 9,0' fill='none' stroke='black' stroke-width='1' stroke-linecap='round' stroke-linejoin='round'/%3E%3C/svg%3E") center / contain no-repeat;
mask: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='-0.5 -0.5 10 7.5'%3E%3Cpolyline points='0,3.25 3.15,6.5 9,0' fill='none' stroke='black' stroke-width='1' stroke-linecap='round' stroke-linejoin='round'/%3E%3C/svg%3E") center / contain no-repeat;
}
.checkbox.indeterminate::after { content: ""; width: 8px; height: 8px; background: var(--primary); border-radius: var(--radius-xs); }
.checkbox.disabled { border-color: var(--muted); }
/* (32 + 4) x (16 + 4) is literal in the source; the inset is a quarter of the
container gap and the thumb is a square filling whats left */
.switch {
display: inline-flex; align-items: stretch; flex: none;
width: 36px; height: 20px; padding: calc(var(--container-gap) * 0.25);
background: var(--switch-track-inactive);
border-radius: var(--radius-xl);
}
.switch::after { content: ""; height: 100%; aspect-ratio: 1; border-radius: var(--radius-lg); background: var(--foreground); }
.switch.on { background: var(--primary); justify-content: flex-end; }
.switch.on::after { background: var(--background); }
.switch.disabled { background: var(--muted); }
.switch.disabled::after { background: var(--muted-foreground); }
/* ---- surfaces & layout ----------------------------------------------- */
/* the whole look: chrome ground, panels standing on it, panel-gap gutters */
.shell { background: var(--chrome); padding: var(--panel-gap); display: flex; gap: var(--panel-gap); }
.panel {
background: var(--background);
border: var(--panel-border-width) solid var(--panel-border);
border-radius: var(--panel-radius);
overflow: hidden;
}
.panel.active { border-color: var(--panel-border-highlighted); }
.panel.sunken { background: var(--surface-sunken); }
.chrome-bar {
display: flex; align-items: center; gap: var(--gap-sm);
height: var(--chrome-bar-height);
background: var(--chrome);
padding: 0 var(--gap-lg);
}
.chrome-bar .vr { width: 1px; height: 12px; background: var(--divider); }
.panel-header { display: flex; align-items: center; gap: 2px; padding: 10px 10px 8px; }
.panel-header .icon { width: 12px; height: 12px; margin: 0 3px; color: var(--foreground); }
.panel-header .title { font-weight: var(--weight-medium); flex: 1; }
/* a nav rail's category, as the hub draws it - gapMd round the run, a
semibold caption over it, gapXxs between the buttons only */
.nav-group { padding: var(--gap-md); display: flex; flex-direction: column; gap: var(--gap-xxs); }
.nav-group > .caption { padding: 0 var(--gap-sm) calc(var(--gap-xs) - var(--gap-xxs)); }
/* explorer tree rows (A&A). an 18px slot for the chevron and one for the
icon, 2px between, 12px glyphs - all literals in explorer_panel.dart. the
hover is inset 2px with a 3px corner, same file */
.explorer-row {
--depth: 0;
position: relative; isolation: isolate;
display: flex; align-items: center; gap: 2px;
height: var(--explorer-row-height);
padding: 0 var(--explorer-row-end-padding) 0 calc(var(--explorer-row-base-padding) + var(--depth) * 18px);
color: var(--row-text); white-space: nowrap;
}
.explorer-row.depth-1 { --depth: 1; }
.explorer-row.depth-2 { --depth: 2; }
.explorer-row.depth-3 { --depth: 3; }
.explorer-row > .slot { flex: none; width: 18px; display: flex; align-items: center; justify-content: center; }
.explorer-row .icon { width: 12px; height: 12px; }
.explorer-row .chevron { color: var(--muted-foreground); }
.explorer-row > .name { flex: 1; min-width: 0; overflow: hidden; text-overflow: ellipsis; }
.explorer-row:hover::before, .explorer-row.is-hovered::before {
content: ""; position: absolute; inset: 2px; z-index: -1;
background: var(--row-hovered); border-radius: 3px;
}
.card {
background: var(--card);
border: 1px solid var(--properties-section-border);
border-radius: var(--radius-xl);
padding: var(--container-padding);
}
.outlined {
background: var(--background);
border: 1px solid var(--control-border);
border-radius: var(--radius-xl);
}
.divider { height: 1px; background: var(--divider); border: 0; margin: 0; }
/* ---- properties section --------------------------------------------- */
.properties-section {
margin: 0 var(--gap-xs) var(--properties-section-gap);
background: var(--card);
border: 1px solid var(--properties-section-border);
border-radius: var(--radius-sm);
overflow: hidden;
}
.properties-section > .header {
display: flex; align-items: center; gap: var(--gap-sm);
padding: var(--control-padding-y) var(--control-padding-x);
color: var(--row-text); font-weight: var(--weight-semibold);
}
.properties-section > .header .chevron { color: var(--muted-foreground); }
/* the header's own subtitle - captionStyle, so the ambient weight not the title's */
.properties-section > .header .subtitle { display: block; font-size: var(--text-xxs); color: var(--muted-foreground); font-weight: var(--weight-body); }
.properties-section > .header .trailing { margin-left: auto; font-weight: var(--weight-control); }
/* the last row gets more room under it than the step between rows */
.properties-section > .rows { padding: 0 var(--control-padding-x) var(--gap-md); display: flex; flex-direction: column; gap: var(--gap-xs); }
.properties-section > .actions {
display: flex; justify-content: flex-end; gap: var(--gap-sm);
border-top: 1px solid var(--properties-section-border);
background: color-mix(in srgb, var(--card) 55%, var(--muted));
padding: var(--gap-sm) var(--control-padding-x);
}
/* PropertyRow - the label up to the split, the control from it. the gap comes
out of the label's padding, so the control's edge lands right on the split.
it wraps, so an .error or .description can take a line of its own under it */
.property-row { display: flex; flex-wrap: wrap; align-items: center; }
.property-row > .label { flex: 0 0 calc(var(--property-split) * 100%); padding-right: var(--property-label-gap); min-width: 0; color: var(--row-text); text-align: right; }
.property-row > .label .subtitle { display: block; font-size: var(--text-xxs); color: var(--muted-foreground); }
.property-row > .label .tag { font-size: var(--text-xxs); color: var(--muted-foreground); margin-left: var(--gap-xs); }
.property-row > .value { flex: 1 1 0; min-width: 0; min-height: var(--property-row-height); display: flex; align-items: center; gap: var(--control-gap); }
.property-row > .value > .field, .property-row > .value > .select, .property-row > .value > .btn-group.span { flex: 1; }
/* why the value was refused - under the row, centred, destructive */
.property-row > .error { flex: 0 0 100%; margin-top: var(--gap-xs); text-align: center; font-size: var(--text-xxs); color: var(--destructive); }
/* copy about the setting, in a box that matches the outline controls */
.property-row > .description {
flex: 0 0 100%; margin-top: var(--gap-xs);
padding: var(--gap-xs) var(--control-padding-x);
background: var(--control-fill);
border: var(--control-border-width) solid var(--control-border);
border-radius: var(--radius-md);
text-align: center; font-size: var(--text-xxs); color: var(--muted-foreground);
}
/* ---- settings list --------------------------------------------------- */
/* ruled BETWEEN rows, and the rule overshoots the text by the row inset so it
reads as a divider rather than the edge of a box */
.settings-list { display: flex; flex-direction: column; }
.settings-list > .settings-row + .settings-row { border-top: 1px solid var(--divider); }
.settings-row { display: flex; flex-wrap: wrap; align-items: center; column-gap: var(--gap-md); padding: var(--gap-md) var(--gap-sm); }
.settings-row > .label { flex: 1 1 0; min-width: 0; font-size: var(--text-xs); font-weight: var(--weight-control); color: var(--foreground); }
.settings-row > .label .subtitle { display: block; margin-top: var(--gap-xxs); font-size: var(--text-xxs); font-weight: var(--weight-body); color: var(--muted-foreground); }
.settings-row > .label .tag { font-size: var(--text-xxs); font-weight: var(--weight-control); color: var(--muted-foreground); margin-left: var(--gap-xs); }
/* a loose Flexible: at most what the label leaves, field pinned right. a
select or a button keeps its own width, a text field fills the slot.
the minimum lives here rather than on the label so the label can stay a
plain block - its the height of a row WITH a subtitle, so a list mixing the
two doesnt come out ragged */
.settings-row > .field-slot {
flex: 1 1 0; min-width: 0;
min-height: calc(var(--label-column-height) + var(--gap-xxs));
display: flex; align-items: center; justify-content: flex-end;
}
.settings-row > .field-slot > .field { flex: 1; }
.settings-row > .error { flex: 0 0 100%; margin-top: var(--gap-sm); font-size: var(--text-xxs); color: var(--destructive); }
.settings-row > .description { flex: 0 0 100%; margin-top: var(--gap-sm); font-size: var(--text-xxs); color: var(--muted-foreground); }
.settings-row > .error + .description { margin-top: var(--gap-xxs); }
/* ---- dialogs, toasts ------------------------------------------------- */
/* AlertDialog's barrier - black at 0.8, no blur */
.modal-backdrop { background: rgb(0 0 0 / 0.8); }
/* pane overlays keep the lighter frosted scrim */
.scrim { background: color-mix(in srgb, var(--background) 35%, transparent); backdrop-filter: blur(3px); }
.dialog {
width: 100%; max-width: var(--dialog-max-width);
background: var(--card);
border: 1px solid var(--properties-section-border);
border-radius: var(--radius-xxl);
overflow: hidden;
}
.dialog > .body { padding: calc(var(--container-padding) * 1.2) calc(var(--container-padding) * 1.4) calc(var(--container-padding) * 0.6); display: flex; flex-direction: column; gap: var(--container-gap); }
.dialog > .body .title { font-size: var(--text-xs); font-weight: var(--weight-semibold); }
.dialog > .body .content { font-size: var(--text-xs); color: var(--muted-foreground); }
.dialog > .actions {
display: flex; justify-content: flex-end; gap: var(--container-gap);
border-top: 1px solid var(--properties-section-border);
background: color-mix(in srgb, var(--card) 55%, var(--muted));
padding: var(--gap-sm) var(--control-padding-x);
}
/* the desktop toast. 300 wide, the 32px badge, the 18px glyph, the white on
it and the 3px bar are all literals in toast.dart */
.toast {
--toast-accent: var(--primary);
display: flex; flex-direction: column;
width: 300px;
background: var(--popover);
border: 1px solid var(--popover-border);
border-radius: var(--radius-md);
overflow: hidden;
}
.toast.success { --toast-accent: var(--chart-2); }
.toast.error { --toast-accent: var(--destructive); }
.toast > .body { display: flex; align-items: flex-start; gap: var(--container-gap); padding: var(--container-gap); }
.toast .badge {
flex: none; width: 32px; height: 32px;
display: flex; align-items: center; justify-content: center;
border: var(--control-border-width) solid var(--control-border);
border-radius: var(--radius-md);
color: #fff;
}
.toast .badge .icon { width: 18px; height: 18px; }
.toast .text { flex: 1; min-width: 0; }
/* title and subtitle are the same text, told apart by colour only */
.toast .title { font-weight: var(--weight-control); color: var(--foreground); }
.toast .subtitle { margin-top: calc(var(--container-gap) * 0.375); font-weight: var(--weight-control); color: var(--muted-foreground); }
/* the countdown - the accent drains off the right, over the border colour at 0.4 */
.toast > .drain { display: flex; height: 3px; background: color-mix(in srgb, var(--popover-border) 40%, transparent); }
.toast > .drain > span { background: var(--toast-accent); }
/* CircularProgressIndicator - no track, a 1.35pi arc (~243deg) on a 4px
round stroke, 18px, primary, once round every 900ms. all literal in
misc.dart. the two dots are the round caps */
.spinner {
position: relative; flex: none;
width: 18px; height: 18px; border-radius: 50%;
background: conic-gradient(var(--primary) 0 243deg, transparent 0);
-webkit-mask: radial-gradient(farthest-side, transparent calc(100% - 4px), #000 calc(100% - 3.5px));
mask: radial-gradient(farthest-side, transparent calc(100% - 4px), #000 calc(100% - 3.5px));
animation: gu-spin 0.9s linear infinite;
}
.spinner::before, .spinner::after {
content: ""; position: absolute; left: 7px; top: 0;
width: 4px; height: 4px; border-radius: 50%;
background: var(--primary);
transform-origin: 2px 9px;
}
.spinner::after { transform: rotate(243deg); }
@keyframes gu-spin { to { transform: rotate(360deg); } }
@@ -0,0 +1,94 @@
<!-- @dsCard group="Components" -->
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<title>Button groups</title>
<link rel="stylesheet" href="../components.css">
<style>
.ds { padding: 0 var(--container-padding) var(--container-padding); }
.ds-block { padding: 0 var(--gap-xs); }
.ds-half + .ds-half { margin-top: var(--gap-lg); }
.ds-block > .caption { padding-bottom: var(--gap-xs); }
.ds-half { display: grid; grid-template-columns: 1fr 1fr; gap: var(--gap-xl); }
.ds-rules { margin: 0; padding: 0 var(--gap-xs) 0 var(--gap-xl); display: flex; flex-direction: column; gap: var(--gap-xxs); }
</style>
</head>
<body>
<main class="ds">
<div class="sub-heading">
<div class="title">Button groups</div>
<div class="subtitle">Controls joined into one. Only the outer corners round.</div>
</div>
<div class="ds-half">
<div class="ds-block">
<div class="caption">Button welded to a field</div>
<div class="btn-group span">
<label class="field grow"><input value="gk_live_4f8a2c91" aria-label="Client ID"></label>
<button class="btn secondary icon-only" aria-label="Copy"><svg class="icon" viewBox="0 0 24 24"><rect width="14" height="14" x="8" y="8" rx="2" ry="2" /><path d="M4 16c-1.1 0-2-.9-2-2V4c0-1.1.9-2 2-2h10c1.1 0 2 .9 2 2" /></svg></button>
</div>
</div>
<div class="ds-block">
<div class="caption">Segmented choice</div>
<div class="btn-group fill">
<button class="btn secondary">Off</button>
<button class="btn primary">Optional</button>
<button class="btn secondary">Required</button>
</div>
</div>
</div>
<div class="ds-half">
<div class="ds-block">
<div class="caption">Vertical, with a group nested in it</div>
<div class="btn-group vertical span">
<label class="field"><input placeholder="Email" aria-label="Email"></label>
<div class="btn-group span">
<label class="field grow"><input placeholder="Password" type="password" aria-label="Password"></label>
<button class="btn outline icon-only" aria-label="Show password"><svg class="icon" viewBox="0 0 24 24"><path d="M2.062 12.348a1 1 0 0 1 0-.696 10.75 10.75 0 0 1 19.876 0 1 1 0 0 1 0 .696 10.75 10.75 0 0 1-19.876 0" /><circle cx="12" cy="12" r="3" /></svg></button>
</div>
</div>
</div>
<div class="ds-block">
<div class="caption">Toolbar toggles - primary on, outline off</div>
<div class="chrome-bar">
<button class="btn primary icon-only" aria-label="Bold"><svg class="icon" viewBox="0 0 24 24"><path d="M6 12h9a4 4 0 0 1 0 8H7a1 1 0 0 1-1-1V5a1 1 0 0 1 1-1h7a4 4 0 0 1 0 8" /></svg></button>
<button class="btn outline icon-only" aria-label="Italic"><svg class="icon" viewBox="0 0 24 24"><line x1="19" x2="10" y1="4" y2="4" /><line x1="14" x2="5" y1="20" y2="20" /><line x1="15" x2="9" y1="4" y2="20" /></svg></button>
<button class="btn outline icon-only" aria-label="Underline"><svg class="icon" viewBox="0 0 24 24"><path d="M6 4v6a6 6 0 0 0 12 0V4" /><line x1="4" x2="20" y1="20" y2="20" /></svg></button>
<span class="vr"></span>
<div class="btn-group">
<button class="btn primary icon-only" aria-label="Align left"><svg class="icon" viewBox="0 0 24 24"><path d="M21 5H3" /><path d="M15 12H3" /><path d="M17 19H3" /></svg></button>
<button class="btn outline icon-only" aria-label="Align centre"><svg class="icon" viewBox="0 0 24 24"><path d="M21 5H3" /><path d="M17 12H7" /><path d="M19 19H5" /></svg></button>
<button class="btn outline icon-only" aria-label="Align right"><svg class="icon" viewBox="0 0 24 24"><path d="M21 5H3" /><path d="M21 12H9" /><path d="M21 19H7" /></svg></button>
</div>
</div>
</div>
</div>
<div class="sub-heading">
<div class="title">Use it for</div>
</div>
<ul class="ds-rules">
<li>A field with its one action welded on: a spanning group, the field grows, then a secondary IconButton.</li>
<li>Groups nest. A corner only rounds where both groups agree it's an outer one.</li>
<li>A segmented choice: fill the group, chosen one primary, the rest secondary, labels centred.</li>
<li>Editor toolbar toggles: primary when on, outline when off.</li>
</ul>
<div class="sub-heading">
<div class="title">Dont</div>
</div>
<ul class="ds-rules">
<li>Leave a segmented control shrunk to its labels. It should span its field.</li>
<li>Mix the primary-on toggle pattern and Toggle on the same surface.</li>
<li>Use a secondary off state unless its a master switch whose off state matters.</li>
</ul>
</main>
</body>
</html>
+130
View File
@@ -0,0 +1,130 @@
<!-- @dsCard group="Components" -->
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<title>Buttons</title>
<link rel="stylesheet" href="../components.css">
<style>
.ds { padding: 0 var(--container-padding) var(--container-padding); }
.ds-row { display: flex; flex-wrap: wrap; align-items: center; gap: var(--gap-sm); padding: 0 var(--gap-xs); }
.ds-block + .ds-block { margin-top: var(--gap-lg); }
.ds-block > .caption { padding: 0 var(--gap-xs) var(--gap-xs); }
.ds-table { width: 100%; border-collapse: collapse; }
.ds-table td { padding: var(--gap-xs) var(--gap-xs); border-top: var(--control-border-width) solid var(--divider); vertical-align: middle; }
.ds-table tr:first-child td { border-top: 0; }
.ds-table td:first-child { width: 30%; }
.ds-rules { margin: 0; padding: 0 var(--gap-xs) 0 var(--gap-xl); display: flex; flex-direction: column; gap: var(--gap-xxs); }
</style>
</head>
<body>
<main class="ds">
<div class="sub-heading">
<div class="title">Buttons</div>
<div class="subtitle">Pick the variant, then stop. The theme does the rest.</div>
</div>
<div class="ds-block">
<div class="caption">Variants</div>
<div class="ds-row">
<button class="btn primary">Save</button>
<button class="btn secondary">Duplicate</button>
<button class="btn outline">Cancel</button>
<button class="btn ghost">Settings</button>
<button class="btn ghost-destructive">Remove</button>
<button class="btn destructive">Delete</button>
<button class="btn link">Learn more</button>
<button class="btn text">Forgot password?</button>
</div>
</div>
<div class="ds-block">
<div class="caption">With a leading icon</div>
<div class="ds-row">
<button class="btn primary"><svg class="icon" viewBox="0 0 24 24"><path d="M5 12h14" /><path d="M12 5v14" /></svg>New product</button>
<button class="btn outline"><svg class="icon" viewBox="0 0 24 24"><path d="M12 15V3" /><path d="M21 15v4a2 2 0 0 1-2 2H5a2 2 0 0 1-2-2v-4" /><path d="m7 10 5 5 5-5" /></svg>Export</button>
<button class="btn ghost"><svg class="icon" viewBox="0 0 24 24"><path d="M9.671 4.136a2.34 2.34 0 0 1 4.659 0 2.34 2.34 0 0 0 3.319 1.915 2.34 2.34 0 0 1 2.33 4.033 2.34 2.34 0 0 0 0 3.831 2.34 2.34 0 0 1-2.33 4.033 2.34 2.34 0 0 0-3.319 1.915 2.34 2.34 0 0 1-4.659 0 2.34 2.34 0 0 0-3.32-1.915 2.34 2.34 0 0 1-2.33-4.033 2.34 2.34 0 0 0 0-3.831A2.34 2.34 0 0 1 6.35 6.051a2.34 2.34 0 0 0 3.319-1.915" /><circle cx="12" cy="12" r="3" /></svg>Settings</button>
<button class="btn ghost-destructive"><svg class="icon" viewBox="0 0 24 24"><path d="M10 11v6" /><path d="M14 11v6" /><path d="M19 6v14a2 2 0 0 1-2 2H7a2 2 0 0 1-2-2V6" /><path d="M3 6h18" /><path d="M8 6V4a2 2 0 0 1 2-2h4a2 2 0 0 1 2 2v2" /></svg>Revoke</button>
</div>
</div>
<div class="ds-block">
<div class="caption">Icon only - IconButton, never a Button with just an icon in it</div>
<div class="ds-row">
<button class="btn primary icon-only" aria-label="Add"><svg class="icon" viewBox="0 0 24 24"><path d="M5 12h14" /><path d="M12 5v14" /></svg></button>
<button class="btn secondary icon-only" aria-label="Copy"><svg class="icon" viewBox="0 0 24 24"><rect width="14" height="14" x="8" y="8" rx="2" ry="2" /><path d="M4 16c-1.1 0-2-.9-2-2V4c0-1.1.9-2 2-2h10c1.1 0 2 .9 2 2" /></svg></button>
<button class="btn outline icon-only" aria-label="Refresh"><svg class="icon" viewBox="0 0 24 24"><path d="M3 12a9 9 0 0 1 9-9 9.75 9.75 0 0 1 6.74 2.74L21 8" /><path d="M21 3v5h-5" /><path d="M21 12a9 9 0 0 1-9 9 9.75 9.75 0 0 1-6.74-2.74L3 16" /><path d="M8 16H3v5" /></svg></button>
<button class="btn ghost icon-only" aria-label="Edit"><svg class="icon" viewBox="0 0 24 24"><path d="M21.174 6.812a1 1 0 0 0-3.986-3.987L3.842 16.174a2 2 0 0 0-.5.83l-1.321 4.352a.5.5 0 0 0 .623.622l4.353-1.32a2 2 0 0 0 .83-.497z" /><path d="m15 5 4 4" /></svg></button>
<button class="btn ghost-destructive icon-only" aria-label="Delete"><svg class="icon" viewBox="0 0 24 24"><path d="M10 11v6" /><path d="M14 11v6" /><path d="M19 6v14a2 2 0 0 1-2 2H7a2 2 0 0 1-2-2V6" /><path d="M3 6h18" /><path d="M8 6V4a2 2 0 0 1 2-2h4a2 2 0 0 1 2 2v2" /></svg></button>
</div>
</div>
<div class="ds-block">
<div class="caption">Disabled</div>
<div class="ds-row">
<button class="btn primary" disabled>Save</button>
<button class="btn secondary" disabled>Duplicate</button>
<button class="btn outline" disabled>Cancel</button>
<button class="btn ghost" disabled>Settings</button>
<button class="btn ghost-destructive" disabled>Remove</button>
<button class="btn destructive" disabled>Delete</button>
<button class="btn link" disabled>Learn more</button>
</div>
</div>
<div class="ds-block">
<div class="caption">Hovered</div>
<div class="ds-row">
<button class="btn primary is-hovered">Save</button>
<button class="btn secondary is-hovered">Duplicate</button>
<button class="btn outline is-hovered">Cancel</button>
<button class="btn ghost is-hovered">Settings</button>
<button class="btn ghost-destructive is-hovered">Remove</button>
<button class="btn destructive is-hovered">Delete</button>
<button class="btn link is-hovered">Learn more</button>
<button class="btn text is-hovered">Forgot password?</button>
</div>
</div>
<div class="sub-heading">
<div class="title">Variants mean something</div>
</div>
<table class="ds-table">
<tr><td><button class="btn primary">Primary</button></td><td>The one action, or the thing thats on or chosen. One per view, ideally.</td></tr>
<tr><td><button class="btn secondary">Secondary</button></td><td>A neutral filled control. A resting toggle, a button welded to a field, the selected nav item.</td></tr>
<tr><td><button class="btn outline">Outline</button></td><td>A normal action that isnt the main one. Cancel, Retry, Previous and Next.</td></tr>
<tr><td><button class="btn ghost">Ghost</button></td><td>Chrome, toolbars, nav items, row actions. Anything that shouldnt compete.</td></tr>
<tr><td><button class="btn destructive">Destructive</button></td><td>The confirm button of a destructive dialog.</td></tr>
<tr><td><button class="btn ghost-destructive">Ghost destructive</button></td><td>A destructive trigger that isnt a filled slab. Remove, Revoke, Delete in a row.</td></tr>
<tr><td><button class="btn link">Link</button> <button class="btn text">Text</button></td><td>Inline, in running copy.</td></tr>
</table>
<div class="sub-heading">
<div class="title">Use it for</div>
</div>
<ul class="ds-rules">
<li>Dialogs: Cancel is outline, confirm is primary or destructive.</li>
<li>Retry after an error, and an empty state's call to action: outline.</li>
<li>Panel header actions: a ghost IconButton, each in a Tooltip.</li>
<li>An action in a settings row: ghost. In a property row: secondary.</li>
</ul>
<div class="sub-heading">
<div class="title">Dont</div>
</div>
<ul class="ds-rules">
<li>Bold a button label, or colour its text or icon by hand.</li>
<li>Hand-colour a ghost button red. Thats what ghost destructive is for.</li>
<li>Set an alignment unless the button is stretched wider than its label.</li>
<li>Force a compact density on a button to make it fit.</li>
</ul>
</main>
</body>
</html>
+66
View File
@@ -0,0 +1,66 @@
<!-- @dsCard group="Components" -->
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<title>Dialogs</title>
<link rel="stylesheet" href="../components.css">
<style>
.ds { padding: 0 var(--container-padding) var(--container-padding); }
.ds-stage { display: flex; flex-direction: column; align-items: center; gap: var(--gap-xl); padding: var(--gap-xxl) var(--container-padding); border-radius: var(--radius-xl); }
.ds-rules { margin: 0; padding: 0 var(--gap-xs) 0 var(--gap-xl); display: flex; flex-direction: column; gap: var(--gap-xxs); }
</style>
</head>
<body>
<main class="ds">
<div class="sub-heading">
<div class="title">Dialogs</div>
<div class="subtitle">A small confirm, over a dimmed page.</div>
</div>
<div class="modal-backdrop ds-stage">
<div class="dialog" role="alertdialog" aria-labelledby="d1-title">
<div class="body">
<div class="title" id="d1-title">Delete this product?</div>
<div class="content">People who already bought it keep their licence. It cant be sold again.</div>
</div>
<div class="actions">
<button class="btn outline">Cancel</button>
<button class="btn destructive">Delete</button>
</div>
</div>
<div class="dialog" role="alertdialog" aria-labelledby="d2-title">
<div class="body">
<div class="title" id="d2-title">Publish changes?</div>
<div class="content">The new price goes live at checkout straight away.</div>
</div>
<div class="actions">
<button class="btn outline">Cancel</button>
<button class="btn primary">Publish</button>
</div>
</div>
</div>
<div class="sub-heading">
<div class="title">Use it for</div>
</div>
<ul class="ds-rules">
<li>showDialog with an AlertDialog: a title, a line of content and its actions.</li>
<li>Cancel is outline. Confirm is primary, or destructive when it removes something.</li>
<li>Bigger jobs, like settings or export, go in a pane overlay instead.</li>
</ul>
<div class="sub-heading">
<div class="title">Dont</div>
</div>
<ul class="ds-rules">
<li>Constrain the dialog's width. It caps itself at the dialog max width.</li>
<li>Build the action row by hand. The dialog draws its own band.</li>
</ul>
</main>
</body>
</html>
+110
View File
@@ -0,0 +1,110 @@
<!-- @dsCard group="Components" -->
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<title>Feedback</title>
<link rel="stylesheet" href="../components.css">
<style>
.ds { padding: 0 var(--container-padding) var(--container-padding); }
.ds-row { display: flex; flex-wrap: wrap; gap: var(--gap-md); padding: 0 var(--gap-xs); align-items: flex-start; }
.ds-grid { display: grid; grid-template-columns: 1fr 1fr 1fr; gap: var(--gap-xl); padding: 0 var(--gap-xs); }
.ds-cell { display: flex; flex-direction: column; gap: var(--gap-xs); }
.ds-state { flex: 1; display: flex; flex-direction: column; align-items: center; justify-content: center; gap: var(--gap-sm); padding: var(--gap-xxl) var(--gap-md); }
.ds-rules { margin: 0; padding: 0 var(--gap-xs) 0 var(--gap-xl); display: flex; flex-direction: column; gap: var(--gap-xxs); }
</style>
</head>
<body>
<main class="ds">
<div class="sub-heading">
<div class="title">Feedback</div>
<div class="subtitle">Toasts, and the three states a page can be in.</div>
</div>
<div class="ds-row">
<div class="toast" role="status">
<div class="body">
<div class="badge"><svg class="icon" viewBox="0 0 24 24"><circle cx="12" cy="12" r="10" /><path d="M12 16v-4" /><path d="M12 8h.01" /></svg></div>
<div class="text">
<div class="title">Link copied</div>
<div class="subtitle">Paste it anywhere a buyer can reach.</div>
</div>
<button class="btn outline icon-only" aria-label="Close"><svg class="icon" viewBox="0 0 24 24"><path d="M18 6 6 18" /><path d="m6 6 12 12" /></svg></button>
</div>
<div class="drain"><span style="width: 80%"></span></div>
</div>
<div class="toast success" role="status">
<div class="body">
<div class="badge"><svg class="icon" viewBox="0 0 24 24"><circle cx="12" cy="12" r="10" /><path d="m9 12 2 2 4-4" /></svg></div>
<div class="text">
<div class="title">Saved</div>
<div class="subtitle">Your changes are live.</div>
</div>
<button class="btn outline icon-only" aria-label="Close"><svg class="icon" viewBox="0 0 24 24"><path d="M18 6 6 18" /><path d="m6 6 12 12" /></svg></button>
</div>
<div class="drain"><span style="width: 45%"></span></div>
</div>
<div class="toast error" role="alert">
<div class="body">
<div class="badge"><svg class="icon" viewBox="0 0 24 24"><circle cx="12" cy="12" r="10" /><line x1="12" x2="12" y1="8" y2="12" /><line x1="12" x2="12.01" y1="16" y2="16" /></svg></div>
<div class="text">
<div class="title">Couldnt save</div>
<div class="subtitle">Check your connection and try again.</div>
</div>
<button class="btn outline icon-only" aria-label="Close"><svg class="icon" viewBox="0 0 24 24"><path d="M18 6 6 18" /><path d="m6 6 12 12" /></svg></button>
</div>
<div class="drain"><span style="width: 20%"></span></div>
</div>
</div>
<div class="sub-heading">
<div class="title">Loading, empty, error</div>
<div class="subtitle">The plainest thing that works.</div>
</div>
<div class="ds-grid">
<div class="ds-cell">
<div class="caption">Loading</div>
<div class="ds-state outlined">
<div class="spinner" role="progressbar" aria-label="Loading"></div>
</div>
</div>
<div class="ds-cell">
<div class="caption">Empty</div>
<div class="ds-state outlined">
<div class="text-xs muted">No coupons yet.</div>
</div>
</div>
<div class="ds-cell">
<div class="caption">Error</div>
<div class="ds-state outlined">
<div class="text-xs muted">Couldnt load orders.</div>
<button class="btn outline">Retry</button>
</div>
</div>
</div>
<div class="sub-heading">
<div class="title">Use it for</div>
</div>
<ul class="ds-rules">
<li>showAppToast with a title, a subtitle and a severity: info, success or error. The severity colours the drain bar, nothing else.</li>
<li>Loading is a spinner. Empty is one muted line. Error is the message muted and an outline Retry.</li>
</ul>
<div class="sub-heading">
<div class="title">Dont</div>
</div>
<ul class="ds-rules">
<li>Use skeletons or shimmer.</li>
<li>Hand-build a toast out of a card and some padding.</li>
<li>Hand-build a warning box. A page that wants more is asking for a new garage_ui component.</li>
</ul>
</main>
</body>
</html>
+73
View File
@@ -0,0 +1,73 @@
<!-- @dsCard group="Components" -->
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<title>Menus and tooltips</title>
<link rel="stylesheet" href="../components.css">
<style>
.ds { padding: 0 var(--container-padding) var(--container-padding); }
.ds-grid { display: grid; grid-template-columns: 1fr 1fr 1fr; gap: var(--gap-xl); padding: 0 var(--gap-xs); align-items: start; }
.ds-cell { display: flex; flex-direction: column; align-items: flex-start; gap: var(--gap-xs); }
.ds-rules { margin: 0; padding: 0 var(--gap-xs) 0 var(--gap-xl); display: flex; flex-direction: column; gap: var(--gap-xxs); }
</style>
</head>
<body>
<main class="ds">
<div class="sub-heading">
<div class="title">Menus and tooltips</div>
<div class="subtitle">Floating surfaces. Flat, no shadow.</div>
</div>
<div class="ds-grid">
<div class="ds-cell">
<div class="caption">Menu</div>
<div class="popover" role="menu">
<div class="menu-label">Edit</div>
<div class="menu-item" role="menuitem"><svg class="icon" viewBox="0 0 24 24"><circle cx="6" cy="6" r="3" /><path d="M8.12 8.12 12 12" /><path d="M20 4 8.12 15.88" /><circle cx="6" cy="18" r="3" /><path d="M14.8 14.8 20 20" /></svg>Cut<span class="shortcut">⌘ + X</span></div>
<div class="menu-item is-hovered" role="menuitem"><svg class="icon" viewBox="0 0 24 24"><rect width="14" height="14" x="8" y="8" rx="2" ry="2" /><path d="M4 16c-1.1 0-2-.9-2-2V4c0-1.1.9-2 2-2h10c1.1 0 2 .9 2 2" /></svg>Copy<span class="shortcut">⌘ + C</span></div>
<div class="menu-item" role="menuitem"><svg class="icon" viewBox="0 0 24 24"><path d="M11 14h10" /><path d="M16 4h2a2 2 0 0 1 2 2v1.344" /><path d="m17 18 4-4-4-4" /><path d="M8 4H6a2 2 0 0 0-2 2v14a2 2 0 0 0 2 2h12a2 2 0 0 0 1.793-1.113" /><rect x="8" y="2" width="8" height="4" rx="1" /></svg>Paste<span class="shortcut">⌘ + V</span></div>
<div class="menu-divider"></div>
<div class="menu-item" role="menuitem"><svg class="icon" viewBox="0 0 24 24"><path d="M10 11v6" /><path d="M14 11v6" /><path d="M19 6v14a2 2 0 0 1-2 2H7a2 2 0 0 1-2-2V6" /><path d="M3 6h18" /><path d="M8 6V4a2 2 0 0 1 2-2h4a2 2 0 0 1 2 2v2" /></svg>Delete</div>
</div>
</div>
<div class="ds-cell">
<div class="caption">Context menu</div>
<div class="popover" role="menu">
<div class="menu-item" role="menuitem"><svg class="icon" viewBox="0 0 24 24"><path d="M3 12a9 9 0 1 0 9-9 9.75 9.75 0 0 0-6.74 2.74L3 8" /><path d="M3 3v5h5" /></svg>Reset to Default</div>
<div class="menu-item" role="menuitem"><svg class="icon" viewBox="0 0 24 24"><rect width="14" height="14" x="8" y="8" rx="2" ry="2" /><path d="M4 16c-1.1 0-2-.9-2-2V4c0-1.1.9-2 2-2h10c1.1 0 2 .9 2 2" /></svg>Copy</div>
<div class="menu-item disabled" aria-disabled="true" role="menuitem"><svg class="icon" viewBox="0 0 24 24"><path d="M11 14h10" /><path d="M16 4h2a2 2 0 0 1 2 2v1.344" /><path d="m17 18 4-4-4-4" /><path d="M8 4H6a2 2 0 0 0-2 2v14a2 2 0 0 0 2 2h12a2 2 0 0 0 1.793-1.113" /><rect x="8" y="2" width="8" height="4" rx="1" /></svg>Paste</div>
</div>
</div>
<div class="ds-cell">
<div class="caption">Tooltip</div>
<button class="btn ghost icon-only" aria-label="Copy"><svg class="icon" viewBox="0 0 24 24"><rect width="14" height="14" x="8" y="8" rx="2" ry="2" /><path d="M4 16c-1.1 0-2-.9-2-2V4c0-1.1.9-2 2-2h10c1.1 0 2 .9 2 2" /></svg></button>
<span class="tooltip" role="tooltip">Copy client ID</span>
</div>
</div>
<div class="sub-heading">
<div class="title">Use it for</div>
</div>
<ul class="ds-rules">
<li>MenuButton rows, with MenuLabel and MenuDivider to group them.</li>
<li>showContextMenu for right-click. Property rows get Reset, Copy and Paste, greyed when theres nothing to do.</li>
<li>A tooltip on every icon-only button, with plain text in it.</li>
</ul>
<div class="sub-heading">
<div class="title">Dont</div>
</div>
<ul class="ds-rules">
<li>Hand-build a popover out of a container with a fill, border and radius.</li>
<li>Colour tooltip text, or pad the tooltip yourself.</li>
<li>Add a shadow to a menu. Surfaces are separated by their border and fill.</li>
</ul>
</main>
</body>
</html>
@@ -0,0 +1,94 @@
<!-- @dsCard group="Components" -->
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<title>Properties section</title>
<link rel="stylesheet" href="../components.css">
<style>
.ds { padding: 0 var(--container-padding) var(--container-padding); }
.ds-rules { margin: 0; padding: 0 var(--gap-xs) 0 var(--gap-xl); display: flex; flex-direction: column; gap: var(--gap-xxs); }
</style>
</head>
<body>
<main class="ds">
<div class="sub-heading">
<div class="title">Properties section</div>
<div class="subtitle">A boxed card of label and value rows.</div>
</div>
<div class="properties-section">
<div class="header" role="button" aria-expanded="true">
<svg class="icon chevron" viewBox="0 0 24 24"><path d="m6 9 6 6 6-6" /></svg>
<span>Subscription</span>
<span class="trailing muted">Active</span>
</div>
<div class="rows">
<div class="property-row">
<div class="label">Plan</div>
<div class="value"><label class="field secondary readonly"><input value="Pro, monthly" readonly disabled aria-label="Plan"></label></div>
</div>
<div class="property-row">
<div class="label">Seats<span class="subtitle">People who can sign in</span></div>
<div class="value"><label class="field secondary error"><input value="0" aria-label="Seats"></label></div>
<div class="error">Needs at least one seat</div>
</div>
<div class="property-row">
<div class="label">Billing</div>
<div class="value">
<div class="select secondary" role="button">
<span>Monthly</span>
<svg class="icon chevron" viewBox="0 0 24 24"><path d="m7 15 5 5 5-5" /><path d="m7 9 5-5 5 5" /></svg>
</div>
</div>
<div class="description">Switching takes effect from the next invoice, not this one.</div>
</div>
<div class="property-row">
<div class="label">Invoices</div>
<div class="value"><button class="btn secondary">Open billing portal</button></div>
</div>
</div>
<div class="actions">
<button class="btn ghost">Reset</button>
<button class="btn ghost-destructive">Cancel plan</button>
</div>
</div>
<div class="sub-heading">
<div class="title">The value slot is never bare text</div>
<div class="subtitle">A read-only value is a secondary field, read only and disabled.</div>
</div>
<ul class="ds-rules">
<li>Beside real fields, bare text reads as a caption and the column goes ragged.</li>
<li>A button in the value slot sits left and keeps its own width. It doesnt stretch.</li>
<li>A refused value says why in the row's error, under it. Copy about the setting goes in the description box.</li>
</ul>
<div class="sub-heading">
<div class="title">Use it for</div>
</div>
<ul class="ds-rules">
<li>Inspectors, account and security pages, and lists of records, one section per record.</li>
<li>A status or count in the header's trailing slot. It stays visible when collapsed.</li>
<li>What the section can do, in the actions band under the rows.</li>
</ul>
<div class="sub-heading">
<div class="title">Dont</div>
</div>
<ul class="ds-rules">
<li>Use outline fields or ghost selects in here. Controls in a section are secondary.</li>
<li>Put live data in the subtitle. No counts, dates, names or statuses.</li>
<li>Add gaps between sections. Each one carries its own margin.</li>
</ul>
</main>
</body>
</html>
+84
View File
@@ -0,0 +1,84 @@
<!-- @dsCard group="Components" -->
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<title>Select</title>
<link rel="stylesheet" href="../components.css">
<style>
.ds { padding: 0 var(--container-padding) var(--container-padding); }
.ds-grid { display: grid; grid-template-columns: 1fr 1fr 1fr; gap: var(--gap-xl); padding: 0 var(--gap-xs); align-items: start; }
.ds-cell { display: flex; flex-direction: column; align-items: flex-start; gap: var(--gap-xs); min-width: 0; }
.ds-open { display: flex; flex-direction: column; gap: var(--gap-xs); align-items: flex-start; padding: var(--gap-lg) var(--gap-xs) 0; }
.ds-rules { margin: 0; padding: 0 var(--gap-xs) 0 var(--gap-xl); display: flex; flex-direction: column; gap: var(--gap-xxs); }
</style>
</head>
<body>
<main class="ds">
<div class="sub-heading">
<div class="title">Select</div>
<div class="subtitle">One value from a list, in a popup.</div>
</div>
<div class="ds-grid">
<div class="ds-cell">
<div class="caption">Outline - the default</div>
<div class="select" role="button">
<span>Engineering</span>
<svg class="icon chevron" viewBox="0 0 24 24"><path d="m7 15 5 5 5-5" /><path d="m7 9 5-5 5 5" /></svg>
</div>
</div>
<div class="ds-cell">
<div class="caption">Secondary - in a property row</div>
<div class="select secondary" role="button">
<span>Monthly</span>
<svg class="icon chevron" viewBox="0 0 24 24"><path d="m7 15 5 5 5-5" /><path d="m7 9 5-5 5 5" /></svg>
</div>
</div>
<div class="ds-cell">
<div class="caption">Ghost - in a settings row</div>
<div class="select ghost" role="button">
<span>All regions</span>
<svg class="icon chevron" viewBox="0 0 24 24"><path d="m7 15 5 5 5-5" /><path d="m7 9 5-5 5 5" /></svg>
</div>
</div>
</div>
<div class="ds-open">
<div class="caption">Open</div>
<div class="select" role="button">
<span>Engineering</span>
<svg class="icon chevron" viewBox="0 0 24 24"><path d="m7 15 5 5 5-5" /><path d="m7 9 5-5 5 5" /></svg>
</div>
<div class="select-popup" role="listbox">
<div class="option" role="option">Design</div>
<div class="option selected" role="option" aria-selected="true">Engineering<svg class="icon" viewBox="0 0 24 24"><path d="M20 6 9 17l-5-5" /></svg></div>
<div class="option is-hovered" role="option">Finance</div>
<div class="option" role="option">Support</div>
</div>
</div>
<div class="sub-heading">
<div class="title">Use it for</div>
</div>
<ul class="ds-rules">
<li>Outline by default, beside other outline fields.</li>
<li>Secondary in a property row. The row forces it anyway.</li>
<li>Ghost in a settings row, or where it reports a value rather than offering a control.</li>
</ul>
<div class="sub-heading">
<div class="title">Dont</div>
</div>
<ul class="ds-rules">
<li>Give a toolbar select a literal width.</li>
<li>Put a ghost select inside a properties section.</li>
</ul>
</main>
</body>
</html>
@@ -0,0 +1,59 @@
<!-- @dsCard group="Components" -->
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<title>Selection controls</title>
<link rel="stylesheet" href="../components.css">
<style>
.ds { padding: 0 var(--container-padding) var(--container-padding); }
.ds-grid { display: grid; grid-template-columns: 1fr 1fr; gap: var(--gap-xl); padding: 0 var(--gap-xs); }
.ds-cell { display: flex; flex-direction: column; gap: var(--gap-md); }
.ds-cell > .caption { margin-bottom: calc(var(--gap-xs) - var(--gap-md)); }
.ds-pair { display: inline-flex; align-items: center; gap: var(--gap-sm); }
.ds-rules { margin: 0; padding: 0 var(--gap-xs) 0 var(--gap-xl); display: flex; flex-direction: column; gap: var(--gap-xxs); }
</style>
</head>
<body>
<main class="ds">
<div class="sub-heading">
<div class="title">Selection controls</div>
<div class="subtitle">On or off. Checkbox or Switch, one per surface.</div>
</div>
<div class="ds-grid">
<div class="ds-cell">
<div class="caption">Checkbox</div>
<label class="ds-pair"><span class="checkbox" role="checkbox" aria-checked="false"></span>Snap to grid</label>
<label class="ds-pair"><span class="checkbox checked" role="checkbox" aria-checked="true"></span>Show labels</label>
</div>
<div class="ds-cell">
<div class="caption">Switch</div>
<label class="ds-pair"><span class="switch" role="switch" aria-checked="false"></span>Email receipts</label>
<label class="ds-pair"><span class="switch on" role="switch" aria-checked="true"></span>Active</label>
<label class="ds-pair muted"><span class="switch disabled" role="switch" aria-checked="false" aria-disabled="true"></span>Managed by your organisation</label>
</div>
</div>
<div class="sub-heading">
<div class="title">Use it for</div>
</div>
<ul class="ds-rules">
<li>Checkbox in dense editor panels. Arcs and Angles uses it throughout.</li>
<li>Switch in rows on a product page. The hub uses it in settings rows.</li>
</ul>
<div class="sub-heading">
<div class="title">Dont</div>
</div>
<ul class="ds-rules">
<li>Mix checkboxes and switches on one surface.</li>
<li>Recolour the track, thumb or tick. The accent is primary.</li>
</ul>
</main>
</body>
</html>
@@ -0,0 +1,74 @@
<!-- @dsCard group="Components" -->
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<title>Settings list</title>
<link rel="stylesheet" href="../components.css">
<style>
.ds { padding: 0 var(--container-padding) var(--container-padding); }
.ds-rules { margin: 0; padding: 0 var(--gap-xs) 0 var(--gap-xl); display: flex; flex-direction: column; gap: var(--gap-xxs); }
</style>
</head>
<body>
<main class="ds">
<div class="sub-heading">
<div class="title">Product</div>
<div class="subtitle">What people see at checkout</div>
</div>
<div class="settings-list">
<div class="settings-row">
<div class="label">Name<span class="tag">Required</span><span class="subtitle">Shown on receipts</span></div>
<div class="field-slot"><label class="field"><input value="Pro plan" aria-label="Name"></label></div>
</div>
<div class="settings-row">
<div class="label">Billing<span class="subtitle">How often it charges</span></div>
<div class="field-slot">
<div class="select ghost" role="button">
<span>Monthly</span>
<svg class="icon chevron" viewBox="0 0 24 24"><path d="m7 15 5 5 5-5" /><path d="m7 9 5-5 5 5" /></svg>
</div>
</div>
</div>
<div class="settings-row">
<div class="label">Checkout link</div>
<div class="field-slot">
<button class="btn ghost"><svg class="icon" viewBox="0 0 24 24"><rect width="14" height="14" x="8" y="8" rx="2" ry="2" /><path d="M4 16c-1.1 0-2-.9-2-2V4c0-1.1.9-2 2-2h10c1.1 0 2 .9 2 2" /></svg>Copy link</button>
</div>
</div>
<div class="settings-row">
<div class="label">Price<span class="tag">Required</span></div>
<div class="field-slot"><label class="field error"><input value="0.00" aria-label="Price"><span class="unit">GBP</span></label></div>
<div class="error">A paid product needs a price above zero</div>
<div class="description">Buyers see this converted to their own currency at checkout.</div>
</div>
</div>
<div class="sub-heading">
<div class="title">Use it for</div>
</div>
<ul class="ds-rules">
<li>Forms on the page ground: products, coupons, clients.</li>
<li>Selects, buttons and icon buttons are ghost. Text fields are outline, read-only ones too.</li>
<li>"Required" goes in the row's action slot, beside the label.</li>
<li>Why a value was refused goes in the row's error slot, under the row.</li>
</ul>
<div class="sub-heading">
<div class="title">Dont</div>
</div>
<ul class="ds-rules">
<li>Use secondary fields here. With no card behind them, filled controls float.</li>
<li>Stretch a select or a button to a column. They keep their own width - only a text field fills its slot.</li>
<li>Write a sentence in the subtitle. That goes in the description.</li>
</ul>
</main>
</body>
</html>
+98
View File
@@ -0,0 +1,98 @@
<!-- @dsCard group="Components" -->
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<title>Text fields</title>
<link rel="stylesheet" href="../components.css">
<style>
.ds { padding: 0 var(--container-padding) var(--container-padding); }
.ds-grid { display: grid; grid-template-columns: 1fr 1fr 1fr; gap: var(--gap-lg) var(--gap-xl); padding: 0 var(--gap-xs); }
.ds-cell { display: flex; flex-direction: column; gap: var(--gap-xs); min-width: 0; }
.ds-rules { margin: 0; padding: 0 var(--gap-xs) 0 var(--gap-xl); display: flex; flex-direction: column; gap: var(--gap-xxs); }
</style>
</head>
<body>
<main class="ds">
<div class="sub-heading">
<div class="title">Text fields</div>
<div class="subtitle">Outline for free text, secondary for values.</div>
</div>
<div class="ds-grid">
<div class="ds-cell">
<div class="caption">Outline - the default</div>
<label class="field stretch"><input placeholder="Product name" aria-label="Product name"></label>
</div>
<div class="ds-cell">
<div class="caption">Outline, filled in</div>
<label class="field stretch"><input value="Pro plan" aria-label="Product name"></label>
</div>
<div class="ds-cell">
<div class="caption">With a leading icon</div>
<label class="field stretch">
<svg class="icon" viewBox="0 0 24 24"><path d="m21 21-4.34-4.34" /><circle cx="11" cy="11" r="8" /></svg>
<input placeholder="Search" aria-label="Search">
</label>
</div>
<div class="ds-cell">
<div class="caption">Secondary</div>
<label class="field secondary stretch"><input value="1280" aria-label="Width"></label>
</div>
<div class="ds-cell">
<div class="caption">Read only</div>
<label class="field secondary readonly stretch"><input value="prod_8f2k1c" readonly disabled aria-label="Product ID"></label>
</div>
<div class="ds-cell">
<div class="caption">Numeric, centred, with a unit</div>
<label class="field secondary center stretch">
<input value="24" aria-label="Stroke width">
<span class="unit">px</span>
</label>
</div>
<div class="ds-cell">
<div class="caption">Error - the outline reddens, never the fill</div>
<label class="field error stretch"><input value="pro plan!" aria-label="Slug"></label>
</div>
<div class="ds-cell">
<div class="caption">Outline, hovered</div>
<label class="field stretch is-hovered"><input value="Pro plan" aria-label="Product name"></label>
</div>
<div class="ds-cell">
<div class="caption">Read only, monospace - ids and skus</div>
<label class="field secondary readonly mono stretch"><input value="usr_8f2c41d9a7" readonly disabled aria-label="User ID"></label>
</div>
</div>
<div class="sub-heading">
<div class="title">Use it for</div>
</div>
<ul class="ds-rules">
<li>Outline for free text: names, search, a composer, a form.</li>
<li>Secondary for numeric property values and read-only values.</li>
<li>Inside a property row the field is forced to secondary. You dont pick.</li>
<li>A read-only value is a read-only, disabled field. Never bare text.</li>
</ul>
<div class="sub-heading">
<div class="title">Dont</div>
</div>
<ul class="ds-rules">
<li>Hand-roll a red line under a field. Use the row's error slot.</li>
<li>Put a secondary field in a settings list, or an outline one in a properties section.</li>
<li>Colour or size the icon. The field does it.</li>
</ul>
</main>
</body>
</html>
+140
View File
@@ -0,0 +1,140 @@
<!-- @dsCard group="Foundations" -->
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<title>Colour</title>
<link rel="stylesheet" href="../components.css">
<style>
body { padding: var(--container-padding); }
.group { margin-top: var(--gap-lg); }
.group > .caption { margin-bottom: var(--gap-sm); padding: 0 var(--gap-xxs); }
.swatches { display: grid; grid-template-columns: repeat(4, 1fr); gap: var(--gap-md); }
.sw { display: flex; gap: var(--gap-sm); align-items: flex-start; min-width: 0; }
.sw .chip { flex: none; width: 32px; height: 32px; border-radius: var(--radius-sm); border: var(--control-border-width) solid var(--divider); }
.sw .meta { min-width: 0; display: flex; flex-direction: column; gap: var(--gap-xxs); }
.sw .for { font-size: var(--text-xxs); }
.schemes { margin-top: var(--gap-xl); display: flex; flex-direction: column; gap: var(--gap-sm); }
.strip { display: flex; align-items: center; gap: var(--gap-md); padding: var(--gap-sm) var(--gap-md); border-radius: var(--radius-md); border: var(--control-border-width) solid var(--panel-border); }
.strip .name { width: calc(var(--control-height) * 1.6); flex: none; }
.strip .chips { display: flex; flex-wrap: wrap; gap: var(--gap-sm); }
.strip .set { display: flex; gap: var(--gap-xxs); }
.strip .mini { width: 12px; height: 12px; border-radius: var(--radius-xs); border: var(--control-border-width) solid var(--divider); }
</style>
</head>
<body>
<div class="page-heading">
<div class="title">Colour</div>
<div class="subtitle">37 slots per scheme. Carbon is the default. Pick the slot by what the thing is.</div>
</div>
<div class="group">
<div class="caption">Ground & surfaces</div>
<div class="swatches">
<div class="sw"><div class="chip" style="background: var(--background)"></div><div class="meta"><span class="mono">--background</span><span class="mono muted">#0d0d0d</span><span class="for muted">Page ground, and a panel's fill</span></div></div>
<div class="sw"><div class="chip" style="background: var(--chrome)"></div><div class="meta"><span class="mono">--chrome</span><span class="mono muted">#010101</span><span class="for muted">Header and footer bars, the gutter between panels</span></div></div>
<div class="sw"><div class="chip" style="background: var(--surface-sunken)"></div><div class="meta"><span class="mono">--surface-sunken</span><span class="mono muted">#0a0a0a</span><span class="for muted">One step below the ground: rails, panel bodies</span></div></div>
<div class="sw"><div class="chip" style="background: var(--card)"></div><div class="meta"><span class="mono">--card</span><span class="mono muted">#1b1b1b</span><span class="for muted">Raised surface: cards, properties sections, dialogs</span></div></div>
<div class="sw"><div class="chip" style="background: var(--muted)"></div><div class="meta"><span class="mono">--muted</span><span class="mono muted">#0f0f0f</span><span class="for muted">De-emphasised fill</span></div></div>
</div>
</div>
<div class="group">
<div class="caption">Text</div>
<div class="swatches">
<div class="sw"><div class="chip" style="background: var(--foreground)"></div><div class="meta"><span class="mono">--foreground</span><span class="mono muted">#f2f2f2</span><span class="for muted">Default text</span></div></div>
<div class="sw"><div class="chip" style="background: var(--muted-foreground)"></div><div class="meta"><span class="mono">--muted-foreground</span><span class="mono muted">#8f8f8f</span><span class="for muted">Secondary text, hints, units</span></div></div>
<div class="sw"><div class="chip" style="background: var(--row-text)"></div><div class="meta"><span class="mono">--row-text</span><span class="mono muted">#c2c2c2</span><span class="for muted">A row's resting label</span></div></div>
<div class="sw"><div class="chip" style="background: var(--row-hovered)"></div><div class="meta"><span class="mono">--row-hovered</span><span class="mono muted">#222222</span><span class="for muted">A hovered row in lists and menus</span></div></div>
</div>
</div>
<div class="group">
<div class="caption">Controls</div>
<div class="swatches">
<div class="sw"><div class="chip" style="background: var(--control-fill)"></div><div class="meta"><span class="mono">--control-fill</span><span class="mono muted">#080808</span><span class="for muted">Shared fill of every control</span></div></div>
<div class="sw"><div class="chip" style="background: var(--control-fill-hovered)"></div><div class="meta"><span class="mono">--control-fill-hovered</span><span class="mono muted">#070707</span><span class="for muted">Control fill, hovered</span></div></div>
<div class="sw"><div class="chip" style="background: var(--control-fill-focused)"></div><div class="meta"><span class="mono">--control-fill-focused</span><span class="mono muted">#000000</span><span class="for muted">Control fill, focused</span></div></div>
<div class="sw"><div class="chip" style="background: var(--control-border)"></div><div class="meta"><span class="mono">--control-border</span><span class="mono muted">#2a2a2a</span><span class="for muted">Shared stroke of every control</span></div></div>
<div class="sw"><div class="chip" style="background: var(--secondary)"></div><div class="meta"><span class="mono">--secondary</span><span class="mono muted">#303030</span><span class="for muted">A neutral filled control</span></div></div>
<div class="sw"><div class="chip" style="background: var(--secondary-hovered)"></div><div class="meta"><span class="mono">--secondary-hovered</span><span class="mono muted">#424242</span><span class="for muted">Secondary, hovered</span></div></div>
<div class="sw"><div class="chip" style="background: var(--secondary-foreground)"></div><div class="meta"><span class="mono">--secondary-foreground</span><span class="mono muted">#f2f2f2</span><span class="for muted">Text on secondary</span></div></div>
<div class="sw"><div class="chip" style="background: var(--switch-track-inactive)"></div><div class="meta"><span class="mono">--switch-track-inactive</span><span class="mono muted">#0f0f0f</span><span class="for muted">A switch while off</span></div></div>
</div>
</div>
<div class="group">
<div class="caption">Floating</div>
<div class="swatches">
<div class="sw"><div class="chip" style="background: var(--popover)"></div><div class="meta"><span class="mono">--popover</span><span class="mono muted">#000000</span><span class="for muted">Menus, select popups, anything floating</span></div></div>
<div class="sw"><div class="chip" style="background: var(--popover-border)"></div><div class="meta"><span class="mono">--popover-border</span><span class="mono muted">#1c1c1c</span><span class="for muted">A popover's edge</span></div></div>
<div class="sw"><div class="chip" style="background: var(--popover-item-hovered)"></div><div class="meta"><span class="mono">--popover-item-hovered</span><span class="mono muted">#1f1f1f</span><span class="for muted">Hover inside select and date popups</span></div></div>
<div class="sw"><div class="chip" style="background: var(--tooltip-background)"></div><div class="meta"><span class="mono">--tooltip-background</span><span class="mono muted">#080808</span><span class="for muted">Tooltips, above everything</span></div></div>
<div class="sw"><div class="chip" style="background: var(--tooltip-border)"></div><div class="meta"><span class="mono">--tooltip-border</span><span class="mono muted">#1f1f1f</span><span class="for muted">A tooltip's edge</span></div></div>
</div>
</div>
<div class="group">
<div class="caption">Accent & state</div>
<div class="swatches">
<div class="sw"><div class="chip" style="background: var(--primary)"></div><div class="meta"><span class="mono">--primary</span><span class="mono muted">#e8e8e8</span><span class="for muted">The accent. The one thing that's on or chosen</span></div></div>
<div class="sw"><div class="chip" style="background: var(--primary-hovered)"></div><div class="meta"><span class="mono">--primary-hovered</span><span class="mono muted">#fefefe</span><span class="for muted">Primary, hovered</span></div></div>
<div class="sw"><div class="chip" style="background: var(--primary-foreground)"></div><div class="meta"><span class="mono">--primary-foreground</span><span class="mono muted">#000000</span><span class="for muted">Text on primary</span></div></div>
<div class="sw"><div class="chip" style="background: var(--destructive)"></div><div class="meta"><span class="mono">--destructive</span><span class="mono muted">#c43333</span><span class="for muted">Delete, revoke, discard</span></div></div>
<div class="sw"><div class="chip" style="background: var(--ring)"></div><div class="meta"><span class="mono">--ring</span><span class="mono muted">#ffffff</span><span class="for muted">Keyboard focus</span></div></div>
</div>
</div>
<div class="group">
<div class="caption">Lines & panels</div>
<div class="swatches">
<div class="sw"><div class="chip" style="background: var(--border)"></div><div class="meta"><span class="mono">--border</span><span class="mono muted">#010101</span><span class="for muted">General outline</span></div></div>
<div class="sw"><div class="chip" style="background: var(--divider)"></div><div class="meta"><span class="mono">--divider</span><span class="mono muted">#202020</span><span class="for muted">A seam between things</span></div></div>
<div class="sw"><div class="chip" style="background: var(--panel-border)"></div><div class="meta"><span class="mono">--panel-border</span><span class="mono muted">#222222</span><span class="for muted">A panel's edge, resting</span></div></div>
<div class="sw"><div class="chip" style="background: var(--panel-border-highlighted)"></div><div class="meta"><span class="mono">--panel-border-highlighted</span><span class="mono muted">#3a3a3a</span><span class="for muted">The lit panel's edge</span></div></div>
<div class="sw"><div class="chip" style="background: var(--properties-section-border)"></div><div class="meta"><span class="mono">--properties-section-border</span><span class="mono muted">#272727</span><span class="for muted">A properties section's edge</span></div></div>
</div>
</div>
<div class="group">
<div class="caption">Charts</div>
<div class="swatches">
<div class="sw"><div class="chip" style="background: var(--chart-1)"></div><div class="meta"><span class="mono">--chart-1</span><span class="mono muted">#f45b69</span><span class="for muted">Data visualisation</span></div></div>
<div class="sw"><div class="chip" style="background: var(--chart-2)"></div><div class="meta"><span class="mono">--chart-2</span><span class="mono muted">#86d957</span><span class="for muted">Data visualisation</span></div></div>
<div class="sw"><div class="chip" style="background: var(--chart-3)"></div><div class="meta"><span class="mono">--chart-3</span><span class="mono muted">#62a7ff</span><span class="for muted">Data visualisation</span></div></div>
<div class="sw"><div class="chip" style="background: var(--chart-4)"></div><div class="meta"><span class="mono">--chart-4</span><span class="mono muted">#ffc857</span><span class="for muted">Data visualisation</span></div></div>
<div class="sw"><div class="chip" style="background: var(--chart-5)"></div><div class="meta"><span class="mono">--chart-5</span><span class="mono muted">#ff8c42</span><span class="for muted">Data visualisation</span></div></div>
</div>
</div>
<div class="schemes">
<div class="caption">Other schemes, same slots in the same order</div>
<div class="gu strip" data-scheme="light">
<span class="name medium">Light</span>
<div class="chips">
<div class="set"><div class="mini" style="background: var(--background)" title="--background"></div><div class="mini" style="background: var(--chrome)" title="--chrome"></div><div class="mini" style="background: var(--surface-sunken)" title="--surface-sunken"></div><div class="mini" style="background: var(--card)" title="--card"></div><div class="mini" style="background: var(--muted)" title="--muted"></div></div>
<div class="set"><div class="mini" style="background: var(--foreground)" title="--foreground"></div><div class="mini" style="background: var(--muted-foreground)" title="--muted-foreground"></div><div class="mini" style="background: var(--row-text)" title="--row-text"></div><div class="mini" style="background: var(--row-hovered)" title="--row-hovered"></div></div>
<div class="set"><div class="mini" style="background: var(--control-fill)" title="--control-fill"></div><div class="mini" style="background: var(--control-fill-hovered)" title="--control-fill-hovered"></div><div class="mini" style="background: var(--control-fill-focused)" title="--control-fill-focused"></div><div class="mini" style="background: var(--control-border)" title="--control-border"></div><div class="mini" style="background: var(--secondary)" title="--secondary"></div><div class="mini" style="background: var(--secondary-hovered)" title="--secondary-hovered"></div><div class="mini" style="background: var(--secondary-foreground)" title="--secondary-foreground"></div><div class="mini" style="background: var(--switch-track-inactive)" title="--switch-track-inactive"></div></div>
<div class="set"><div class="mini" style="background: var(--popover)" title="--popover"></div><div class="mini" style="background: var(--popover-border)" title="--popover-border"></div><div class="mini" style="background: var(--popover-item-hovered)" title="--popover-item-hovered"></div><div class="mini" style="background: var(--tooltip-background)" title="--tooltip-background"></div><div class="mini" style="background: var(--tooltip-border)" title="--tooltip-border"></div></div>
<div class="set"><div class="mini" style="background: var(--primary)" title="--primary"></div><div class="mini" style="background: var(--primary-hovered)" title="--primary-hovered"></div><div class="mini" style="background: var(--primary-foreground)" title="--primary-foreground"></div><div class="mini" style="background: var(--destructive)" title="--destructive"></div><div class="mini" style="background: var(--ring)" title="--ring"></div></div>
<div class="set"><div class="mini" style="background: var(--border)" title="--border"></div><div class="mini" style="background: var(--divider)" title="--divider"></div><div class="mini" style="background: var(--panel-border)" title="--panel-border"></div><div class="mini" style="background: var(--panel-border-highlighted)" title="--panel-border-highlighted"></div><div class="mini" style="background: var(--properties-section-border)" title="--properties-section-border"></div></div>
<div class="set"><div class="mini" style="background: var(--chart-1)" title="--chart-1"></div><div class="mini" style="background: var(--chart-2)" title="--chart-2"></div><div class="mini" style="background: var(--chart-3)" title="--chart-3"></div><div class="mini" style="background: var(--chart-4)" title="--chart-4"></div><div class="mini" style="background: var(--chart-5)" title="--chart-5"></div></div>
</div>
</div>
<div class="gu strip" data-scheme="dark">
<span class="name medium">Dark</span>
<div class="chips">
<div class="set"><div class="mini" style="background: var(--background)" title="--background"></div><div class="mini" style="background: var(--chrome)" title="--chrome"></div><div class="mini" style="background: var(--surface-sunken)" title="--surface-sunken"></div><div class="mini" style="background: var(--card)" title="--card"></div><div class="mini" style="background: var(--muted)" title="--muted"></div></div>
<div class="set"><div class="mini" style="background: var(--foreground)" title="--foreground"></div><div class="mini" style="background: var(--muted-foreground)" title="--muted-foreground"></div><div class="mini" style="background: var(--row-text)" title="--row-text"></div><div class="mini" style="background: var(--row-hovered)" title="--row-hovered"></div></div>
<div class="set"><div class="mini" style="background: var(--control-fill)" title="--control-fill"></div><div class="mini" style="background: var(--control-fill-hovered)" title="--control-fill-hovered"></div><div class="mini" style="background: var(--control-fill-focused)" title="--control-fill-focused"></div><div class="mini" style="background: var(--control-border)" title="--control-border"></div><div class="mini" style="background: var(--secondary)" title="--secondary"></div><div class="mini" style="background: var(--secondary-hovered)" title="--secondary-hovered"></div><div class="mini" style="background: var(--secondary-foreground)" title="--secondary-foreground"></div><div class="mini" style="background: var(--switch-track-inactive)" title="--switch-track-inactive"></div></div>
<div class="set"><div class="mini" style="background: var(--popover)" title="--popover"></div><div class="mini" style="background: var(--popover-border)" title="--popover-border"></div><div class="mini" style="background: var(--popover-item-hovered)" title="--popover-item-hovered"></div><div class="mini" style="background: var(--tooltip-background)" title="--tooltip-background"></div><div class="mini" style="background: var(--tooltip-border)" title="--tooltip-border"></div></div>
<div class="set"><div class="mini" style="background: var(--primary)" title="--primary"></div><div class="mini" style="background: var(--primary-hovered)" title="--primary-hovered"></div><div class="mini" style="background: var(--primary-foreground)" title="--primary-foreground"></div><div class="mini" style="background: var(--destructive)" title="--destructive"></div><div class="mini" style="background: var(--ring)" title="--ring"></div></div>
<div class="set"><div class="mini" style="background: var(--border)" title="--border"></div><div class="mini" style="background: var(--divider)" title="--divider"></div><div class="mini" style="background: var(--panel-border)" title="--panel-border"></div><div class="mini" style="background: var(--panel-border-highlighted)" title="--panel-border-highlighted"></div><div class="mini" style="background: var(--properties-section-border)" title="--properties-section-border"></div></div>
<div class="set"><div class="mini" style="background: var(--chart-1)" title="--chart-1"></div><div class="mini" style="background: var(--chart-2)" title="--chart-2"></div><div class="mini" style="background: var(--chart-3)" title="--chart-3"></div><div class="mini" style="background: var(--chart-4)" title="--chart-4"></div><div class="mini" style="background: var(--chart-5)" title="--chart-5"></div></div>
</div>
</div>
</div>
</body>
</html>
+89
View File
@@ -0,0 +1,89 @@
<!-- @dsCard group="Foundations" -->
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<title>Density</title>
<link rel="stylesheet" href="../components.css">
<style>
body { padding: var(--container-padding); }
.block { margin-top: var(--gap-xl); }
.block > .caption { margin-bottom: var(--gap-sm); padding: 0 var(--gap-xxs); }
.tiers { display: grid; grid-template-columns: repeat(3, minmax(0, 1fr)); gap: var(--gap-md); align-items: start; }
.tier { border: var(--control-border-width) solid var(--panel-border); border-radius: var(--radius-lg); padding: var(--gap-md) 0 0; min-width: 0; display: flex; flex-direction: column; gap: var(--gap-sm); }
.tier > .caption, .tier > .ctl { padding: 0 var(--gap-md); }
.tier > .ctl { display: flex; }
.tier > .ctl > .field, .tier > .ctl > .select { flex: 1; }
.tier .properties-section { margin-top: var(--gap-xxs); }
.rows { display: flex; flex-direction: column; }
.rows .r { display: grid; grid-template-columns: 1.1fr 0.9fr 0.9fr 0.9fr; gap: var(--gap-md); align-items: baseline; padding: var(--gap-sm) var(--gap-xs); }
.rows .r + .r { border-top: var(--control-border-width) solid var(--divider); }
</style>
</head>
<body>
<div class="page-heading">
<div class="title">Density</div>
<div class="subtitle">Three tiers. Pick one for the app, don't tune it.</div>
</div>
<div class="block">
<div class="caption">Same controls, three tiers</div>
<div class="tiers">
<div class="gu tier" data-density="compact">
<div class="caption">Compact</div>
<div class="ctl"><button class="btn primary">Save</button></div>
<div class="ctl"><label class="field"><input placeholder="Name"></label></div>
<div class="ctl"><div class="select"><span>Monthly</span><svg class="icon chevron" viewBox="0 0 24 24"><path d="m7 15 5 5 5-5" /><path d="m7 9 5-5 5 5" /></svg></div></div>
<div class="properties-section">
<div class="rows">
<div class="property-row"><span class="label">Width</span><div class="value"><label class="field secondary center"><input value="120"><span class="unit">px</span></label></div></div>
</div>
</div>
</div>
<div class="gu tier" data-density="normal">
<div class="caption">Normal</div>
<div class="ctl"><button class="btn primary">Save</button></div>
<div class="ctl"><label class="field"><input placeholder="Name"></label></div>
<div class="ctl"><div class="select"><span>Monthly</span><svg class="icon chevron" viewBox="0 0 24 24"><path d="m7 15 5 5 5-5" /><path d="m7 9 5-5 5 5" /></svg></div></div>
<div class="properties-section">
<div class="rows">
<div class="property-row"><span class="label">Width</span><div class="value"><label class="field secondary center"><input value="120"><span class="unit">px</span></label></div></div>
</div>
</div>
</div>
<div class="gu tier" data-density="product">
<div class="caption">Product</div>
<div class="ctl"><button class="btn primary">Save</button></div>
<div class="ctl"><label class="field"><input placeholder="Name"></label></div>
<div class="ctl"><div class="select"><span>Monthly</span><svg class="icon chevron" viewBox="0 0 24 24"><path d="m7 15 5 5 5-5" /><path d="m7 9 5-5 5 5" /></svg></div></div>
<div class="properties-section">
<div class="rows">
<div class="property-row"><span class="label">Width</span><div class="value"><label class="field secondary center"><input value="120"><span class="unit">px</span></label></div></div>
</div>
</div>
</div>
</div>
</div>
<div class="block">
<div class="caption">The numbers</div>
<div class="rows">
<div class="r"><span></span><span class="medium">Compact</span><span class="medium">Normal</span><span class="medium">Product</span></div>
<div class="r"><span class="mono muted">font-size</span><span class="mono">10</span><span class="mono">10</span><span class="mono">12</span></div>
<div class="r"><span class="mono muted">control-height</span><span class="mono">23</span><span class="mono">27</span><span class="mono">33</span></div>
<div class="r"><span class="mono muted">chrome-bar-height</span><span class="mono">31</span><span class="mono">37</span><span class="mono">43</span></div>
<div class="r"><span class="muted">For</span><span>Dense desktop tools</span><span>The same, roomier</span><span>Web and product apps</span></div>
<div class="r"><span class="muted">Used by</span><span>Arcs &amp; Angles</span><span>A&amp;A "Comfortable"</span><span>The hub</span></div>
</div>
</div>
</body>
</html>
+77
View File
@@ -0,0 +1,77 @@
<!-- @dsCard group="Foundations" -->
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<title>Shape</title>
<link rel="stylesheet" href="../components.css">
<style>
body { padding: var(--container-padding); }
.block { margin-top: var(--gap-xl); }
.block > .caption { margin-bottom: var(--gap-sm); padding: 0 var(--gap-xxs); }
.radii { display: grid; grid-template-columns: repeat(6, 1fr); gap: var(--gap-md); }
.radius { display: flex; flex-direction: column; gap: var(--gap-xs); }
.radius .box { height: calc(var(--control-height) * 1.6); background: var(--card); border: var(--control-border-width) solid var(--control-border); }
.facts { display: grid; grid-template-columns: repeat(3, 1fr); gap: var(--gap-md); }
.facts .card { display: flex; flex-direction: column; gap: var(--gap-xxs); padding: var(--gap-md) var(--gap-lg); }
.demo { border-radius: var(--radius-lg); overflow: hidden; border: var(--control-border-width) solid var(--panel-border); }
.demo .shell { height: calc(var(--control-height) * 5); }
.demo .rail { width: 30%; }
.demo .main { flex: 1; }
.demo .panel { display: flex; flex-direction: column; }
.demo .panel .body { flex: 1; padding: 0 var(--gap-md) var(--gap-md); }
.demo .foot { padding: var(--gap-sm) var(--gap-lg); }
</style>
</head>
<body>
<div class="page-heading">
<div class="title">Shape</div>
<div class="subtitle">Small radii, flat surfaces. Borders and surface steps do the separating.</div>
</div>
<div class="block">
<div class="caption">Radii</div>
<div class="radii">
<div class="radius"><div class="box" style="border-radius: var(--radius-xs)"></div><span class="mono">radius-xs</span><span class="mono muted">2</span></div>
<div class="radius"><div class="box" style="border-radius: var(--radius-sm)"></div><span class="mono">radius-sm</span><span class="mono muted">4</span></div>
<div class="radius"><div class="box" style="border-radius: var(--radius-md)"></div><span class="mono">radius-md</span><span class="mono muted">6 · controls</span></div>
<div class="radius"><div class="box" style="border-radius: var(--radius-lg)"></div><span class="mono">radius-lg</span><span class="mono muted">8</span></div>
<div class="radius"><div class="box" style="border-radius: var(--radius-xl)"></div><span class="mono">radius-xl</span><span class="mono muted">10 · cards</span></div>
<div class="radius"><div class="box" style="border-radius: var(--radius-xxl)"></div><span class="mono">radius-xxl</span><span class="mono muted">12 · dialogs</span></div>
</div>
</div>
<div class="block">
<div class="caption">Panels</div>
<div class="facts">
<div class="card"><span class="mono">panel-radius</span><span class="mono muted">10</span></div>
<div class="card"><span class="mono">panel-gap</span><span class="mono muted">5</span></div>
<div class="card"><span class="mono">panel-border-width</span><span class="mono muted">1.15</span></div>
</div>
</div>
<div class="block">
<div class="caption">Flat, no shadows</div>
<div class="demo">
<div class="chrome-bar"><span class="medium">Chrome</span></div>
<div class="shell">
<div class="panel sunken rail">
<div class="panel-header"><span class="title">Rail</span></div>
<div class="body muted">Sunken panel</div>
</div>
<div class="panel active main">
<div class="panel-header"><span class="title">Workspace</span></div>
<div class="body muted">The lit panel. Only one at a time.</div>
</div>
</div>
</div>
<div class="foot muted">Chrome ground, panels standing on it, panel-gap gutters between.</div>
</div>
</body>
</html>
+80
View File
@@ -0,0 +1,80 @@
<!-- @dsCard group="Foundations" -->
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<title>Spacing</title>
<link rel="stylesheet" href="../components.css">
<style>
body { padding: var(--container-padding); }
.block { margin-top: var(--gap-xl); }
.block > .caption { margin-bottom: var(--gap-sm); padding: 0 var(--gap-xxs); }
.tiers { display: grid; grid-template-columns: 1fr 1fr; gap: var(--gap-md); }
.tier { border: var(--control-border-width) solid var(--panel-border); border-radius: var(--radius-lg); padding: var(--gap-md) var(--gap-lg); }
.tier > .caption { margin-bottom: var(--gap-sm); }
.bar-row { display: flex; align-items: center; gap: var(--gap-md); min-height: var(--line-box); padding: var(--gap-xxs) 0; }
.bar-row .tok { flex: 0 0 48%; white-space: nowrap; }
.bar-row .bar { height: var(--gap-sm); background: var(--primary); border-radius: var(--radius-xs); flex: none; }
.bar-row .px { font-size: var(--text-xxs); }
</style>
</head>
<body>
<div class="page-heading">
<div class="title">Spacing</div>
<div class="subtitle">Gaps come from the density tier. Never a literal.</div>
</div>
<div class="block">
<div class="caption">Gap ladder</div>
<div class="tiers">
<div class="gu tier" data-density="product">
<div class="caption">Product (and normal)</div>
<div class="bar-row"><span class="tok mono muted">gap-xxs</span><div class="bar" style="width: var(--gap-xxs)"></div><span class="px mono muted">3</span></div>
<div class="bar-row"><span class="tok mono muted">gap-xs</span><div class="bar" style="width: var(--gap-xs)"></div><span class="px mono muted">5</span></div>
<div class="bar-row"><span class="tok mono muted">gap-sm</span><div class="bar" style="width: var(--gap-sm)"></div><span class="px mono muted">8</span></div>
<div class="bar-row"><span class="tok mono muted">gap-md</span><div class="bar" style="width: var(--gap-md)"></div><span class="px mono muted">10</span></div>
<div class="bar-row"><span class="tok mono muted">gap-lg</span><div class="bar" style="width: var(--gap-lg)"></div><span class="px mono muted">15</span></div>
<div class="bar-row"><span class="tok mono muted">gap-xl</span><div class="bar" style="width: var(--gap-xl)"></div><span class="px mono muted">20</span></div>
<div class="bar-row"><span class="tok mono muted">gap-xxl</span><div class="bar" style="width: var(--gap-xxl)"></div><span class="px mono muted">30</span></div>
</div>
<div class="gu tier" data-density="compact">
<div class="caption">Compact</div>
<div class="bar-row"><span class="tok mono muted">gap-xxs</span><div class="bar" style="width: var(--gap-xxs)"></div><span class="px mono muted">2</span></div>
<div class="bar-row"><span class="tok mono muted">gap-xs</span><div class="bar" style="width: var(--gap-xs)"></div><span class="px mono muted">4</span></div>
<div class="bar-row"><span class="tok mono muted">gap-sm</span><div class="bar" style="width: var(--gap-sm)"></div><span class="px mono muted">6</span></div>
<div class="bar-row"><span class="tok mono muted">gap-md</span><div class="bar" style="width: var(--gap-md)"></div><span class="px mono muted">8</span></div>
<div class="bar-row"><span class="tok mono muted">gap-lg</span><div class="bar" style="width: var(--gap-lg)"></div><span class="px mono muted">12</span></div>
<div class="bar-row"><span class="tok mono muted">gap-xl</span><div class="bar" style="width: var(--gap-xl)"></div><span class="px mono muted">16</span></div>
<div class="bar-row"><span class="tok mono muted">gap-xxl</span><div class="bar" style="width: var(--gap-xxl)"></div><span class="px mono muted">24</span></div>
</div>
</div>
</div>
<div class="block">
<div class="caption">Heights and containers</div>
<div class="tiers">
<div class="gu tier" data-density="product">
<div class="caption">Product</div>
<div class="bar-row"><span class="tok mono muted">control-height</span><div class="bar" style="width: var(--control-height)"></div><span class="px mono muted">33</span></div>
<div class="bar-row"><span class="tok mono muted">property-row-height</span><div class="bar" style="width: var(--property-row-height)"></div><span class="px mono muted">36</span></div>
<div class="bar-row"><span class="tok mono muted">chrome-bar-height</span><div class="bar" style="width: var(--chrome-bar-height)"></div><span class="px mono muted">43</span></div>
<div class="bar-row"><span class="tok mono muted">container-gap</span><div class="bar" style="width: var(--container-gap)"></div><span class="px mono muted">10</span></div>
<div class="bar-row"><span class="tok mono muted">container-padding</span><div class="bar" style="width: var(--container-padding)"></div><span class="px mono muted">20</span></div>
</div>
<div class="gu tier" data-density="compact">
<div class="caption">Compact</div>
<div class="bar-row"><span class="tok mono muted">control-height</span><div class="bar" style="width: var(--control-height)"></div><span class="px mono muted">23</span></div>
<div class="bar-row"><span class="tok mono muted">property-row-height</span><div class="bar" style="width: var(--property-row-height)"></div><span class="px mono muted">28</span></div>
<div class="bar-row"><span class="tok mono muted">chrome-bar-height</span><div class="bar" style="width: var(--chrome-bar-height)"></div><span class="px mono muted">31</span></div>
<div class="bar-row"><span class="tok mono muted">container-gap</span><div class="bar" style="width: var(--container-gap)"></div><span class="px mono muted">8</span></div>
<div class="bar-row"><span class="tok mono muted">container-padding</span><div class="bar" style="width: var(--container-padding)"></div><span class="px mono muted">16</span></div>
</div>
</div>
</div>
</body>
</html>
+99
View File
@@ -0,0 +1,99 @@
<!-- @dsCard group="Foundations" -->
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<title>Type</title>
<link rel="stylesheet" href="../components.css">
<style>
body { padding: var(--container-padding); }
.block { margin-top: var(--gap-xl); }
.block > .caption { margin-bottom: var(--gap-sm); padding: 0 var(--gap-xxs); }
.faces { display: grid; grid-template-columns: 1fr 1fr; gap: var(--gap-md); }
.faces .card { display: flex; flex-direction: column; gap: var(--gap-xs); }
.tiers { display: grid; grid-template-columns: 1fr 1fr; gap: var(--gap-md); }
.tier { border: var(--control-border-width) solid var(--panel-border); border-radius: var(--radius-lg); padding: var(--gap-md) var(--gap-lg); }
.tier > .caption { margin-bottom: var(--gap-sm); }
.step { display: flex; align-items: baseline; gap: var(--gap-md); padding: var(--gap-xs) 0; }
.step + .step { border-top: var(--control-border-width) solid var(--divider); }
.step .tok { flex: none; width: calc(var(--control-height) * 3.6); white-space: nowrap; font-size: var(--font-size); }
.weights { display: grid; grid-template-columns: repeat(4, 1fr); gap: var(--gap-md); }
.weights .card { display: flex; flex-direction: column; gap: var(--gap-xs); }
.rows { display: flex; flex-direction: column; }
.rows .r { display: grid; grid-template-columns: 1fr 1.3fr 1fr; gap: var(--gap-md); align-items: baseline; padding: var(--gap-sm) var(--gap-xs); }
.rows .r + .r { border-top: var(--control-border-width) solid var(--divider); }
</style>
</head>
<body>
<div class="page-heading">
<div class="title">Type</div>
<div class="subtitle">Geist for everything, Geist Mono for numbers and readouts.</div>
</div>
<div class="block">
<div class="caption">Families</div>
<div class="faces">
<div class="card">
<span class="text-lg">Geist</span>
<span class="muted">--font-sans. Body, controls, headings.</span>
</div>
<div class="card">
<span class="text-lg mono">Geist Mono 0123</span>
<span class="muted">--font-mono. Readouts, ids, stats.</span>
</div>
</div>
</div>
<div class="block">
<div class="caption">Size ladder</div>
<div class="tiers">
<div class="gu tier" data-density="product">
<div class="caption">Product</div>
<div class="step"><span class="tok mono muted">text-lg 22</span><span class="text-lg">Page title</span></div>
<div class="step"><span class="tok mono muted">text-sm 17</span><span class="text-sm">Section heading</span></div>
<div class="step"><span class="tok mono muted">text-xs 13</span><span class="text-xs">List text</span></div>
<div class="step"><span class="tok mono muted">font-size 12</span><span>Body and controls</span></div>
<div class="step"><span class="tok mono muted">text-xxs 11</span><span class="text-xxs">Captions</span></div>
</div>
<div class="gu tier" data-density="compact">
<div class="caption">Compact</div>
<div class="step"><span class="tok mono muted">text-lg 18</span><span class="text-lg">Page title</span></div>
<div class="step"><span class="tok mono muted">text-sm 14</span><span class="text-sm">Section heading</span></div>
<div class="step"><span class="tok mono muted">text-xs 11</span><span class="text-xs">List text</span></div>
<div class="step"><span class="tok mono muted">font-size 10</span><span>Body and controls</span></div>
<div class="step"><span class="tok mono muted">text-xxs 9</span><span class="text-xxs">Captions</span></div>
</div>
</div>
</div>
<div class="block">
<div class="caption">Weights</div>
<div class="weights">
<div class="card"><span class="text-sm">Aa</span><span class="muted">Body 300</span></div>
<div class="card"><span class="text-sm" style="font-weight: var(--weight-control)">Aa</span><span class="muted">Control 400</span></div>
<div class="card"><span class="text-sm medium">Aa</span><span class="muted">Medium 500</span></div>
<div class="card"><span class="text-sm semibold">Aa</span><span class="muted">Semibold 600</span></div>
</div>
</div>
<div class="block">
<div class="caption">Job to style</div>
<div class="rows">
<div class="r"><span class="muted">Page title</span><span class="text-lg">Products</span><span class="mono muted">text-lg</span></div>
<div class="r"><span class="muted">Subtitle</span><span class="muted">What this page is for</span><span class="mono muted">muted</span></div>
<div class="r"><span class="muted">Section heading</span><span class="text-sm semibold">Billing</span><span class="mono muted">text-sm, 600</span></div>
<div class="r"><span class="muted">Nav group caption</span><span class="caption">Account</span><span class="mono muted">text-xxs, 600, muted</span></div>
<div class="r"><span class="muted">Hint, unit, empty line</span><span class="muted">Nothing here yet</span><span class="mono muted">muted</span></div>
<div class="r"><span class="muted">Mono readout</span><span class="mono muted">60 fps · 12.4 ms</span><span class="mono muted">mono, muted</span></div>
</div>
</div>
</body>
</html>
+173
View File
@@ -0,0 +1,173 @@
<!-- @dsCard group="Patterns" -->
<!doctype html>
<html lang="en" data-scheme="carbon" data-density="compact">
<head>
<meta charset="utf-8">
<title>Editor shell</title>
<link rel="stylesheet" href="../components.css">
<style>
/* scaffolding - GarageShell: header, a chrome workspace with the canvas Panel and a
sidebar split top/bottom, footer. panelGap gutters, no gutter above or below */
html, body { background: var(--chrome); }
.screen { width: 1200px; height: 760px; display: flex; flex-direction: column; background: var(--chrome); }
.workspace { flex: 1; min-height: 0; display: flex; gap: var(--panel-gap); padding: 0 var(--panel-gap); }
.canvas { flex: 1; min-width: 0; }
.sidebar { width: 320px; flex: none; display: flex; flex-direction: column; gap: var(--panel-gap); }
.sidebar > .panel { flex: 1; min-height: 0; display: flex; }
/* header: menu words left, perf + file name right, toggles on the true centre */
.header { position: relative; }
.header .menus { display: flex; }
.header .spacer { flex: 1; }
.header .file { width: 150px; text-align: center; }
.header .centre { position: absolute; left: 50%; top: 50%; transform: translate(-50%, -50%); display: flex; gap: var(--gap-sm); }
/* a panel page: sunken body, PanelHeader, then the list */
.page { flex: 1; min-width: 0; background: var(--surface-sunken); display: flex; flex-direction: column; }
.page .body { flex: 1; min-height: 0; overflow: hidden; padding-top: var(--gap-md); }
/* properties tab strip - hand-rolled in the app too (see "Dont copy these") */
.tabs { width: 40px; flex: none; background: var(--chrome); border-right: 1px solid var(--divider);
padding: var(--gap-xs) 0 var(--gap-xs) var(--gap-xs); display: flex; flex-direction: column; gap: var(--gap-xs); }
.tabs .tab { display: flex; justify-content: center; padding-right: var(--gap-xs); border: 1px solid transparent; }
.tabs .tab.on { background: var(--surface-sunken); border-color: var(--divider); border-right-color: transparent;
border-radius: var(--radius-sm) 0 0 var(--radius-sm); margin-right: -1px; }
.tabs .split { height: var(--gap-xl); }
/* footer: three blocks, muted mono */
.footer > div { flex: 1; display: flex; align-items: center; gap: var(--gap-md); }
.footer .mid { justify-content: center; }
.footer .end { justify-content: flex-end; }
</style>
</head>
<body>
<div class="screen">
<!-- header ChromeBar -->
<header class="chrome-bar header">
<div class="menus">
<button class="btn ghost">File</button>
<button class="btn ghost">Edit</button>
<button class="btn ghost">Tools</button>
<button class="btn ghost">Insert</button>
<button class="btn ghost">View</button>
<button class="btn ghost">Info</button>
</div>
<div class="spacer"></div>
<span class="mono muted">60 fps</span>
<span class="vr"></span>
<span class="file muted">Northern loop.ana</span>
<div class="centre">
<div class="btn-group">
<button class="btn primary icon-only" aria-label="Snapping, on"><svg class="icon" viewBox="0 0 24 24" aria-hidden="true"><path d="m12 15 4 4" /> <path d="M2.352 10.648a1.205 1.205 0 0 0 0 1.704l2.296 2.296a1.205 1.205 0 0 0 1.704 0l6.029-6.029a1 1 0 1 1 3 3l-6.029 6.029a1.205 1.205 0 0 0 0 1.704l2.296 2.296a1.205 1.205 0 0 0 1.704 0l6.365-6.367A1 1 0 0 0 8.716 4.282z" /> <path d="m5 8 4 4" /></svg></button>
<button class="btn secondary icon-only" aria-label="Snap options"><svg class="icon" viewBox="0 0 24 24" aria-hidden="true"><path d="m6 9 6 6 6-6" /></svg></button>
</div>
<button class="btn outline icon-only" aria-label="Continuous arcs, off"><svg class="icon" viewBox="0 0 24 24" aria-hidden="true"><circle cx="19" cy="5" r="2" /> <circle cx="5" cy="19" r="2" /> <path d="M5 17A12 12 0 0 1 17 5" /></svg></button>
</div>
</header>
<div class="workspace">
<!-- the canvas: an empty Panel, the app paints the map in it -->
<main class="panel canvas"></main>
<aside class="sidebar">
<!-- top: explorer -->
<section class="panel">
<div class="page">
<div class="panel-header"><svg class="icon" viewBox="0 0 24 24" aria-hidden="true"><path d="M12.83 2.18a2 2 0 0 0-1.66 0L2.6 6.08a1 1 0 0 0 0 1.83l8.58 3.91a2 2 0 0 0 1.66 0l8.58-3.9a1 1 0 0 0 0-1.83z" /> <path d="M2 12a1 1 0 0 0 .58.91l8.6 3.91a2 2 0 0 0 1.65 0l8.58-3.9A1 1 0 0 0 22 12" /> <path d="M2 17a1 1 0 0 0 .58.91l8.6 3.91a2 2 0 0 0 1.65 0l8.58-3.9A1 1 0 0 0 22 17" /></svg><span class="title">Explorer</span></div>
<div class="body">
<div class="explorer-row"><span class="slot"><svg class="icon chevron" viewBox="0 0 24 24" aria-hidden="true"><path d="m6 9 6 6 6-6" /></svg></span><span class="slot"><svg class="icon" viewBox="0 0 24 24" aria-hidden="true"><path d="M20 20a2 2 0 0 0 2-2V8a2 2 0 0 0-2-2h-7.9a2 2 0 0 1-1.69-.9L9.6 3.9A2 2 0 0 0 7.93 3H4a2 2 0 0 0-2 2v13a2 2 0 0 0 2 2Z" /></svg></span><span class="name">Northern loop</span></div>
<div class="explorer-row depth-1 is-hovered"><span class="slot"></span><span class="slot"><svg class="icon" viewBox="0 0 24 24" aria-hidden="true"><circle cx="6" cy="19" r="3" /> <path d="M9 19h8.5a3.5 3.5 0 0 0 0-7h-11a3.5 3.5 0 0 1 0-7H15" /> <circle cx="18" cy="5" r="3" /></svg></span><span class="name">Loop line</span></div>
<div class="explorer-row depth-1"><span class="slot"></span><span class="slot"><svg class="icon" viewBox="0 0 24 24" aria-hidden="true"><circle cx="6" cy="19" r="3" /> <path d="M9 19h8.5a3.5 3.5 0 0 0 0-7h-11a3.5 3.5 0 0 1 0-7H15" /> <circle cx="18" cy="5" r="3" /></svg></span><span class="name">Harbour branch</span></div>
<div class="explorer-row depth-1"><span class="slot"></span><span class="slot"><svg class="icon" viewBox="0 0 24 24" aria-hidden="true"><path d="M20 10c0 4.993-5.539 10.193-7.399 11.799a1 1 0 0 1-1.202 0C9.539 20.193 4 14.993 4 10a8 8 0 0 1 16 0" /> <circle cx="12" cy="10" r="3" /></svg></span><span class="name">Market Street</span></div>
<div class="explorer-row depth-1"><span class="slot"></span><span class="slot"><svg class="icon" viewBox="0 0 24 24" aria-hidden="true"><path d="M20 10c0 4.993-5.539 10.193-7.399 11.799a1 1 0 0 1-1.202 0C9.539 20.193 4 14.993 4 10a8 8 0 0 1 16 0" /> <circle cx="12" cy="10" r="3" /></svg></span><span class="name">Quayside</span></div>
<div class="explorer-row depth-1"><span class="slot"></span><span class="slot"><svg class="icon" viewBox="0 0 24 24" aria-hidden="true"><path d="M20 10c0 4.993-5.539 10.193-7.399 11.799a1 1 0 0 1-1.202 0C9.539 20.193 4 14.993 4 10a8 8 0 0 1 16 0" /> <circle cx="12" cy="10" r="3" /></svg></span><span class="name">Mill Lane</span></div>
<div class="explorer-row depth-1"><span class="slot"></span><span class="slot"><svg class="icon" viewBox="0 0 24 24" aria-hidden="true"><path d="M20 10c0 4.993-5.539 10.193-7.399 11.799a1 1 0 0 1-1.202 0C9.539 20.193 4 14.993 4 10a8 8 0 0 1 16 0" /> <circle cx="12" cy="10" r="3" /></svg></span><span class="name">Northgate</span></div>
<div class="explorer-row"><span class="slot"><svg class="icon chevron" viewBox="0 0 24 24" aria-hidden="true"><path d="m9 18 6-6-6-6" /></svg></span><span class="slot"><svg class="icon" viewBox="0 0 24 24" aria-hidden="true"><path d="M20 20a2 2 0 0 0 2-2V8a2 2 0 0 0-2-2h-7.9a2 2 0 0 1-1.69-.9L9.6 3.9A2 2 0 0 0 7.93 3H4a2 2 0 0 0-2 2v13a2 2 0 0 0 2 2Z" /></svg></span><span class="name">Labels</span></div>
<div class="explorer-row"><span class="slot"><svg class="icon chevron" viewBox="0 0 24 24" aria-hidden="true"><path d="m9 18 6-6-6-6" /></svg></span><span class="slot"><svg class="icon" viewBox="0 0 24 24" aria-hidden="true"><path d="M6 22a2 2 0 0 1-2-2V4a2 2 0 0 1 2-2h8a2.4 2.4 0 0 1 1.704.706l3.588 3.588A2.4 2.4 0 0 1 20 8v12a2 2 0 0 1-2 2z" /> <path d="M14 2v5a1 1 0 0 0 1 1h5" /> <path d="M10 12.5 8 15l2 2.5" /> <path d="m14 12.5 2 2.5-2 2.5" /></svg></span><span class="name">Scripts</span></div>
</div>
</div>
</section>
<!-- bottom: properties tab strip + the selected panel page -->
<section class="panel active">
<div class="tabs">
<div class="tab on"><button class="btn ghost icon-only" aria-label="Canvas"><svg class="icon" viewBox="0 0 24 24" aria-hidden="true"><path d="M10 15h4" /> <path d="m14.817 10.995-.971-1.45 1.034-1.232a2 2 0 0 0-2.025-3.238l-1.82.364L9.91 3.885a2 2 0 0 0-3.625.748L6.141 6.55l-1.725.426a2 2 0 0 0-.19 3.756l.657.27" /> <path d="m18.822 10.995 2.26-5.38a1 1 0 0 0-.557-1.318L16.954 2.9a1 1 0 0 0-1.281.533l-.924 2.122" /> <path d="M4 12.006A1 1 0 0 1 4.994 11H19a1 1 0 0 1 1 1v7a2 2 0 0 1-2 2H6a2 2 0 0 1-2-2z" /></svg></button></div>
<div class="tab"><button class="btn ghost icon-only" aria-label="Lines"><svg class="icon" viewBox="0 0 24 24" aria-hidden="true"><rect width="18" height="18" x="3" y="3" rx="2" /> <path d="M9 8h7" /> <path d="M8 12h6" /> <path d="M11 16h5" /></svg></button></div>
<div class="split"></div>
<div class="tab"><button class="btn ghost icon-only" aria-label="Object Properties"><svg class="icon" viewBox="0 0 24 24" aria-hidden="true"><path d="M10 5H3" /> <path d="M12 19H3" /> <path d="M14 3v4" /> <path d="M16 17v4" /> <path d="M21 12h-9" /> <path d="M21 19h-5" /> <path d="M21 5h-7" /> <path d="M8 10v4" /> <path d="M8 12H3" /></svg></button></div>
<div class="tab"><button class="btn ghost icon-only" aria-label="Script"><svg class="icon" viewBox="0 0 24 24" aria-hidden="true"><path d="M6 22a2 2 0 0 1-2-2V4a2 2 0 0 1 2-2h8a2.4 2.4 0 0 1 1.704.706l3.588 3.588A2.4 2.4 0 0 1 20 8v12a2 2 0 0 1-2 2z" /> <path d="M14 2v5a1 1 0 0 0 1 1h5" /> <path d="M10 12.5 8 15l2 2.5" /> <path d="m14 12.5 2 2.5-2 2.5" /></svg></button></div>
</div>
<div class="page">
<div class="panel-header"><svg class="icon" viewBox="0 0 24 24" aria-hidden="true"><path d="M10 15h4" /> <path d="m14.817 10.995-.971-1.45 1.034-1.232a2 2 0 0 0-2.025-3.238l-1.82.364L9.91 3.885a2 2 0 0 0-3.625.748L6.141 6.55l-1.725.426a2 2 0 0 0-.19 3.756l.657.27" /> <path d="m18.822 10.995 2.26-5.38a1 1 0 0 0-.557-1.318L16.954 2.9a1 1 0 0 0-1.281.533l-.924 2.122" /> <path d="M4 12.006A1 1 0 0 1 4.994 11H19a1 1 0 0 1 1 1v7a2 2 0 0 1-2 2H6a2 2 0 0 1-2-2z" /></svg><span class="title">Canvas</span></div>
<div class="body">
<section class="properties-section">
<div class="header"><svg class="icon chevron" viewBox="0 0 24 24" aria-hidden="true"><path d="m6 9 6 6 6-6" /></svg>Grid</div>
<div class="rows">
<div class="property-row">
<div class="label">Show grid</div>
<div class="value"><span class="checkbox checked"></span></div>
</div>
<div class="property-row">
<div class="label">Grid Z-level</div>
<div class="value"><div class="field secondary center"><input value="0"></div></div>
</div>
<div class="property-row">
<div class="label">Watermark</div>
<div class="value"><span class="checkbox"></span></div>
</div>
</div>
</section>
<section class="properties-section">
<div class="header"><svg class="icon chevron" viewBox="0 0 24 24" aria-hidden="true"><path d="m6 9 6 6 6-6" /></svg>Bounds</div>
<div class="rows">
<div class="property-row">
<div class="label">Unbounded</div>
<div class="value"><span class="checkbox"></span></div>
</div>
<div class="property-row">
<div class="label">Size</div>
<div class="value">
<div class="btn-group vertical span">
<div class="field secondary center"><span class="unit">W</span><input value="120"></div>
<div class="field secondary center"><span class="unit">H</span><input value="80"></div>
</div>
</div>
</div>
</div>
</section>
<section class="properties-section">
<div class="header"><svg class="icon chevron" viewBox="0 0 24 24" aria-hidden="true"><path d="m6 9 6 6 6-6" /></svg>Stations</div>
<div class="rows">
<div class="property-row">
<div class="label">Label size</div>
<div class="value"><div class="field secondary center"><input value="14"><span class="unit">px</span></div></div>
</div>
<div class="property-row">
<div class="label">Size subtitle by scale</div>
<div class="value"><span class="checkbox checked"></span></div>
</div>
</div>
</section>
</div>
</div>
</section>
</aside>
</div>
<!-- footer ChromeBar: muted mono stats -->
<footer class="chrome-bar footer">
<div><span class="mono muted">© 2026 IMBENJI.NET LTD - ARCS &amp; ANGLES</span></div>
<div class="mid"><span class="mono muted">X: 0 · Y: 0</span><span class="vr"></span><span class="mono muted">Zoom: 100%</span></div>
<div class="end">
<span class="mono muted">Segments: 48</span><span class="vr"></span>
<span class="mono muted">Nodes: 112</span><span class="vr"></span>
<span class="mono muted">Stations: 36</span><span class="vr"></span>
<span class="mono muted">v2.4.0</span>
</div>
</footer>
</div>
</body>
</html>
+135
View File
@@ -0,0 +1,135 @@
<!-- @dsCard group="Patterns" -->
<!doctype html>
<html lang="en" data-scheme="carbon" data-density="product">
<head>
<meta charset="utf-8">
<title>Hub form</title>
<link rel="stylesheet" href="../components.css">
<style>
/* scaffolding only - the mock screen and the hub's Measure (railWidth = fontSize*18,
contentMax = fontSize*56, pageGutter = fontSize*3). every value is a token */
html, body { background: var(--chrome); }
.screen { width: 1100px; height: 720px; }
.shell { height: 100%; align-items: stretch; }
.rail { width: calc(var(--font-size) * 18); flex: none; display: flex; flex-direction: column; }
.rail .wordmark { height: calc(var(--font-size) * 9); display: flex; align-items: center; justify-content: center; }
.rail .groups { flex: 1; min-height: 0; overflow: hidden; }
.rail .foot { padding: var(--gap-md) var(--gap-md) var(--gap-lg); }
.workspace { flex: 1; min-width: 0; }
/* contentMax plus a pageGutter either side, centred in the pane */
.column { width: 100%; max-width: calc(var(--font-size) * (56 + 6)); margin: 0 auto; align-self: center;
padding: var(--gap-xxl) calc(var(--font-size) * 3); }
.workspace { display: flex; flex-direction: column; }
.pane-back { padding: var(--gap-sm) var(--gap-sm) 0; }
.column { padding-top: var(--gap-lg); }
.column > .page-heading { margin-bottom: var(--gap-md); }
</style>
</head>
<body>
<div class="screen">
<div class="shell">
<!-- nav rail: a sunken Panel -->
<nav class="panel sunken rail">
<div class="wordmark"><span class="text-lg semibold">Garage</span></div>
<hr class="divider">
<div class="groups">
<div class="nav-group">
<div class="caption">Settings</div>
<button class="btn ghost stretch align-left"><svg class="icon" viewBox="0 0 24 24" aria-hidden="true"><path d="M19 21v-2a4 4 0 0 0-4-4H9a4 4 0 0 0-4 4v2" /> <circle cx="12" cy="7" r="4" /></svg>Account</button>
<button class="btn ghost stretch align-left"><svg class="icon" viewBox="0 0 24 24" aria-hidden="true"><path d="M20 13c0 5-3.5 7.5-7.66 8.95a1 1 0 0 1-.67-.01C7.5 20.5 4 18 4 13V6a1 1 0 0 1 1-1c2 0 4.5-1.2 6.24-2.72a1.17 1.17 0 0 1 1.52 0C14.51 3.81 17 5 19 5a1 1 0 0 1 1 1z" /> <path d="m9 12 2 2 4-4" /></svg>Security</button>
<button class="btn ghost stretch align-left"><svg class="icon" viewBox="0 0 24 24" aria-hidden="true"><path d="M12 17V7" /> <path d="M16 8h-6a2 2 0 0 0 0 4h4a2 2 0 0 1 0 4H8" /> <path d="M4 3a1 1 0 0 1 1-1 1.3 1.3 0 0 1 .7.2l.933.6a1.3 1.3 0 0 0 1.4 0l.934-.6a1.3 1.3 0 0 1 1.4 0l.933.6a1.3 1.3 0 0 0 1.4 0l.933-.6a1.3 1.3 0 0 1 1.4 0l.934.6a1.3 1.3 0 0 0 1.4 0l.933-.6A1.3 1.3 0 0 1 19 2a1 1 0 0 1 1 1v18a1 1 0 0 1-1 1 1.3 1.3 0 0 1-.7-.2l-.933-.6a1.3 1.3 0 0 0-1.4 0l-.934.6a1.3 1.3 0 0 1-1.4 0l-.933-.6a1.3 1.3 0 0 0-1.4 0l-.933.6a1.3 1.3 0 0 1-1.4 0l-.934-.6a1.3 1.3 0 0 0-1.4 0l-.933.6a1.3 1.3 0 0 1-.7.2 1 1 0 0 1-1-1z" /></svg>Payments</button>
<button class="btn ghost stretch align-left"><svg class="icon" viewBox="0 0 24 24" aria-hidden="true"><path d="M10 22V7a1 1 0 0 0-1-1H4a2 2 0 0 0-2 2v12a2 2 0 0 0 2 2h12a2 2 0 0 0 2-2v-5a1 1 0 0 0-1-1H2" /> <rect x="14" y="2" width="8" height="8" rx="1" /></svg>Authorised apps</button>
</div>
<hr class="divider">
<div class="nav-group">
<div class="caption">Developer</div>
<button class="btn secondary stretch align-left"><svg class="icon" viewBox="0 0 24 24" aria-hidden="true"><path d="M4 20h16a2 2 0 0 0 2-2V8a2 2 0 0 0-2-2h-7.93a2 2 0 0 1-1.66-.9l-.82-1.2A2 2 0 0 0 7.93 3H4a2 2 0 0 0-2 2v13c0 1.1.9 2 2 2Z" /> <path d="M8 10v4" /> <path d="M12 10v2" /> <path d="M16 10v6" /></svg>Projects</button>
</div>
<hr class="divider">
<div class="nav-group">
<div class="caption">Garage Platform</div>
<button class="btn ghost stretch align-left"><svg class="icon" viewBox="0 0 24 24" aria-hidden="true"><path d="M11.017 2.814a1 1 0 0 1 1.966 0l1.051 5.558a2 2 0 0 0 1.594 1.594l5.558 1.051a1 1 0 0 1 0 1.966l-5.558 1.051a2 2 0 0 0-1.594 1.594l-1.051 5.558a1 1 0 0 1-1.966 0l-1.051-5.558a2 2 0 0 0-1.594-1.594l-5.558-1.051a1 1 0 0 1 0-1.966l5.558-1.051a2 2 0 0 0 1.594-1.594z" /> <path d="M20 2v4" /> <path d="M22 4h-4" /> <circle cx="4" cy="20" r="2" /></svg>Assistant</button>
<button class="btn ghost stretch align-left"><svg class="icon" viewBox="0 0 24 24" aria-hidden="true"><path d="M10 15H6a4 4 0 0 0-4 4v2" /> <path d="m14.305 16.53.923-.382" /> <path d="m15.228 13.852-.923-.383" /> <path d="m16.852 12.228-.383-.923" /> <path d="m16.852 17.772-.383.924" /> <path d="m19.148 12.228.383-.923" /> <path d="m19.53 18.696-.382-.924" /> <path d="m20.772 13.852.924-.383" /> <path d="m20.772 16.148.924.383" /> <circle cx="18" cy="15" r="3" /> <circle cx="9" cy="7" r="4" /></svg>Users</button>
<button class="btn ghost stretch align-left"><svg class="icon" viewBox="0 0 24 24" aria-hidden="true"><path d="M2.586 17.414A2 2 0 0 0 2 18.828V21a1 1 0 0 0 1 1h3a1 1 0 0 0 1-1v-1a1 1 0 0 1 1-1h1a1 1 0 0 0 1-1v-1a1 1 0 0 1 1-1h.172a2 2 0 0 0 1.414-.586l.814-.814a6.5 6.5 0 1 0-4-4z" /> <circle cx="16.5" cy="7.5" r=".5" fill="currentColor" /></svg>Roles</button>
<button class="btn ghost stretch align-left"><svg class="icon" viewBox="0 0 24 24" aria-hidden="true"><path d="M15 12h-5" /> <path d="M15 8h-5" /> <path d="M19 17V5a2 2 0 0 0-2-2H4" /> <path d="M8 21h12a2 2 0 0 0 2-2v-1a1 1 0 0 0-1-1H11a1 1 0 0 0-1 1v1a2 2 0 1 1-4 0V5a2 2 0 1 0-4 0v2a1 1 0 0 0 1 1h3" /></svg>Audit log</button>
<button class="btn ghost stretch align-left"><svg class="icon" viewBox="0 0 24 24" aria-hidden="true"><path d="M22 12h-2.48a2 2 0 0 0-1.93 1.46l-2.35 8.36a.25.25 0 0 1-.48 0L9.24 2.18a.25.25 0 0 0-.48 0l-2.35 8.36A2 2 0 0 1 4.49 12H2" /></svg>Status</button>
</div>
</div>
<hr class="divider">
<div class="foot">
<button class="btn ghost stretch align-left"><svg class="icon" viewBox="0 0 24 24" aria-hidden="true"><path d="m16 17 5-5-5-5" /> <path d="M21 12H9" /> <path d="M9 21H5a2 2 0 0 1-2-2V5a2 2 0 0 1 2-2h4" /></svg>Sign out</button>
</div>
</nav>
<!-- workspace: a routed detail, so the pane carries the way back and the page wears its own heading -->
<main class="panel workspace">
<div class="pane-back"><button class="btn ghost"><svg class="icon" viewBox="0 0 24 24" aria-hidden="true"><path d="m12 19-7-7 7-7" /> <path d="M19 12H5" /></svg>Back to project</button></div>
<div class="column">
<div class="page-heading">
<div class="title">Pro licence</div>
<div class="subtitle">Something you sell, and what it goes for.</div>
<div class="trailing">
<button class="btn ghost-destructive"><svg class="icon" viewBox="0 0 24 24" aria-hidden="true"><path d="M10 11v6" /> <path d="M14 11v6" /> <path d="M19 6v14a2 2 0 0 1-2 2H7a2 2 0 0 1-2-2V6" /> <path d="M3 6h18" /> <path d="M8 6V4a2 2 0 0 1 2-2h4a2 2 0 0 1 2 2v2" /></svg>Delete</button>
<button class="btn ghost"><svg class="icon" viewBox="0 0 24 24" aria-hidden="true"><path d="M15 3h6v6" /> <path d="M10 14 21 3" /> <path d="M18 13v6a2 2 0 0 1-2 2H5a2 2 0 0 1-2-2V8a2 2 0 0 1 2-2h6" /></svg>Preview checkout</button>
</div>
</div>
<div class="sub-heading">
<div class="title">Details</div>
<div class="subtitle">What it is and how its sold</div>
</div>
<div class="settings-list">
<div class="settings-row">
<div class="label">Name<span class="tag">Required</span><span class="subtitle">What a buyer sees</span></div>
<div class="field-slot"><div class="field"><input value="Pro licence"></div></div>
</div>
<div class="settings-row">
<div class="label">SKU<span class="subtitle">How an app asks for it. Fixed once created</span></div>
<div class="field-slot"><div class="field readonly mono"><input value="pro_licence" disabled></div></div>
</div>
<div class="settings-row">
<div class="label">Use case<span class="subtitle">What's being sold, which sets the tax</span></div>
<div class="field-slot"><div class="select ghost"><span>Downloadable software</span><svg class="icon chevron" viewBox="0 0 24 24" aria-hidden="true"><path d="m7 15 5 5 5-5" /><path d="m7 9 5-5 5 5" /></svg></div></div>
</div>
<div class="settings-row">
<div class="label">Checkout<span class="subtitle">Who takes the card details</span></div>
<div class="field-slot"><div class="select ghost"><span>Stripe Checkout</span><svg class="icon chevron" viewBox="0 0 24 24" aria-hidden="true"><path d="m7 15 5 5 5-5" /><path d="m7 9 5-5 5 5" /></svg></div></div>
</div>
<div class="settings-row">
<div class="label">Key lifetime<span class="subtitle">Seconds. Empty inherits the project's</span></div>
<div class="field-slot"><div class="field error"><input value="a day"></div></div>
<div class="error">Has to be a whole number of seconds</div>
</div>
</div>
<div class="sub-heading">
<div class="title">Pricing</div>
<div class="subtitle">What it costs, and how often</div>
<div class="action"><button class="btn ghost"><svg class="icon" viewBox="0 0 24 24" aria-hidden="true"><path d="M5 12h14" /> <path d="M12 5v14" /></svg>Add price</button></div>
</div>
<section class="properties-section">
<div class="header">
<svg class="icon chevron" viewBox="0 0 24 24" aria-hidden="true"><path d="m6 9 6 6 6-6" /></svg>
<div><div>Default price</div><span class="subtitle">What it goes on sale at</span></div>
</div>
<div class="rows">
<div class="property-row">
<div class="label">Price</div>
<div class="value"><div class="field secondary"><input value="12.00"><span class="unit">GBP</span></div></div>
</div>
<div class="property-row">
<div class="label">Billing</div>
<div class="value"><div class="select secondary"><span>Monthly</span><svg class="icon chevron" viewBox="0 0 24 24" aria-hidden="true"><path d="m7 15 5 5 5-5" /><path d="m7 9 5-5 5 5" /></svg></div></div>
</div>
</div>
</section>
</div>
</main>
</div>
</div>
</body>
</html>
+151
View File
@@ -0,0 +1,151 @@
<!-- @dsCard group="Patterns" -->
<!doctype html>
<html lang="en" data-scheme="carbon" data-density="product">
<head>
<meta charset="utf-8">
<title>Hub page</title>
<link rel="stylesheet" href="../components.css">
<style>
/* scaffolding only - the mock screen and the hub's Measure (railWidth = fontSize*18,
contentMax = fontSize*56, pageGutter = fontSize*3). every value is a token */
html, body { background: var(--chrome); }
.screen { width: 1100px; height: 720px; }
.shell { height: 100%; align-items: stretch; }
.rail { width: calc(var(--font-size) * 18); flex: none; display: flex; flex-direction: column; }
.rail .wordmark { height: calc(var(--font-size) * 9); display: flex; align-items: center; justify-content: center; }
.rail .groups { flex: 1; min-height: 0; overflow: hidden; }
.rail .foot { padding: var(--gap-md) var(--gap-md) var(--gap-lg); }
.workspace { flex: 1; min-width: 0; }
/* contentMax plus a pageGutter either side, centred in the pane */
.column { width: 100%; max-width: calc(var(--font-size) * (56 + 6)); margin: 0 auto; align-self: center;
padding: var(--gap-xxl) calc(var(--font-size) * 3); }
.column > .page-heading { margin-bottom: var(--gap-xxl); }
</style>
</head>
<body>
<div class="screen">
<div class="shell">
<!-- nav rail: a sunken Panel -->
<nav class="panel sunken rail">
<div class="wordmark"><span class="text-lg semibold">Garage</span></div>
<hr class="divider">
<div class="groups">
<div class="nav-group">
<div class="caption">Settings</div>
<button class="btn secondary stretch align-left"><svg class="icon" viewBox="0 0 24 24" aria-hidden="true"><path d="M19 21v-2a4 4 0 0 0-4-4H9a4 4 0 0 0-4 4v2" /> <circle cx="12" cy="7" r="4" /></svg>Account</button>
<button class="btn ghost stretch align-left"><svg class="icon" viewBox="0 0 24 24" aria-hidden="true"><path d="M20 13c0 5-3.5 7.5-7.66 8.95a1 1 0 0 1-.67-.01C7.5 20.5 4 18 4 13V6a1 1 0 0 1 1-1c2 0 4.5-1.2 6.24-2.72a1.17 1.17 0 0 1 1.52 0C14.51 3.81 17 5 19 5a1 1 0 0 1 1 1z" /> <path d="m9 12 2 2 4-4" /></svg>Security</button>
<button class="btn ghost stretch align-left"><svg class="icon" viewBox="0 0 24 24" aria-hidden="true"><path d="M12 17V7" /> <path d="M16 8h-6a2 2 0 0 0 0 4h4a2 2 0 0 1 0 4H8" /> <path d="M4 3a1 1 0 0 1 1-1 1.3 1.3 0 0 1 .7.2l.933.6a1.3 1.3 0 0 0 1.4 0l.934-.6a1.3 1.3 0 0 1 1.4 0l.933.6a1.3 1.3 0 0 0 1.4 0l.933-.6a1.3 1.3 0 0 1 1.4 0l.934.6a1.3 1.3 0 0 0 1.4 0l.933-.6A1.3 1.3 0 0 1 19 2a1 1 0 0 1 1 1v18a1 1 0 0 1-1 1 1.3 1.3 0 0 1-.7-.2l-.933-.6a1.3 1.3 0 0 0-1.4 0l-.934.6a1.3 1.3 0 0 1-1.4 0l-.933-.6a1.3 1.3 0 0 0-1.4 0l-.933.6a1.3 1.3 0 0 1-1.4 0l-.934-.6a1.3 1.3 0 0 0-1.4 0l-.933.6a1.3 1.3 0 0 1-.7.2 1 1 0 0 1-1-1z" /></svg>Payments</button>
<button class="btn ghost stretch align-left"><svg class="icon" viewBox="0 0 24 24" aria-hidden="true"><path d="M10 22V7a1 1 0 0 0-1-1H4a2 2 0 0 0-2 2v12a2 2 0 0 0 2 2h12a2 2 0 0 0 2-2v-5a1 1 0 0 0-1-1H2" /> <rect x="14" y="2" width="8" height="8" rx="1" /></svg>Authorised apps</button>
</div>
<hr class="divider">
<div class="nav-group">
<div class="caption">Developer</div>
<button class="btn ghost stretch align-left"><svg class="icon" viewBox="0 0 24 24" aria-hidden="true"><path d="M4 20h16a2 2 0 0 0 2-2V8a2 2 0 0 0-2-2h-7.93a2 2 0 0 1-1.66-.9l-.82-1.2A2 2 0 0 0 7.93 3H4a2 2 0 0 0-2 2v13c0 1.1.9 2 2 2Z" /> <path d="M8 10v4" /> <path d="M12 10v2" /> <path d="M16 10v6" /></svg>Projects</button>
</div>
<hr class="divider">
<div class="nav-group">
<div class="caption">Garage Platform</div>
<button class="btn ghost stretch align-left"><svg class="icon" viewBox="0 0 24 24" aria-hidden="true"><path d="M11.017 2.814a1 1 0 0 1 1.966 0l1.051 5.558a2 2 0 0 0 1.594 1.594l5.558 1.051a1 1 0 0 1 0 1.966l-5.558 1.051a2 2 0 0 0-1.594 1.594l-1.051 5.558a1 1 0 0 1-1.966 0l-1.051-5.558a2 2 0 0 0-1.594-1.594l-5.558-1.051a1 1 0 0 1 0-1.966l5.558-1.051a2 2 0 0 0 1.594-1.594z" /> <path d="M20 2v4" /> <path d="M22 4h-4" /> <circle cx="4" cy="20" r="2" /></svg>Assistant</button>
<button class="btn ghost stretch align-left"><svg class="icon" viewBox="0 0 24 24" aria-hidden="true"><path d="M10 15H6a4 4 0 0 0-4 4v2" /> <path d="m14.305 16.53.923-.382" /> <path d="m15.228 13.852-.923-.383" /> <path d="m16.852 12.228-.383-.923" /> <path d="m16.852 17.772-.383.924" /> <path d="m19.148 12.228.383-.923" /> <path d="m19.53 18.696-.382-.924" /> <path d="m20.772 13.852.924-.383" /> <path d="m20.772 16.148.924.383" /> <circle cx="18" cy="15" r="3" /> <circle cx="9" cy="7" r="4" /></svg>Users</button>
<button class="btn ghost stretch align-left"><svg class="icon" viewBox="0 0 24 24" aria-hidden="true"><path d="M2.586 17.414A2 2 0 0 0 2 18.828V21a1 1 0 0 0 1 1h3a1 1 0 0 0 1-1v-1a1 1 0 0 1 1-1h1a1 1 0 0 0 1-1v-1a1 1 0 0 1 1-1h.172a2 2 0 0 0 1.414-.586l.814-.814a6.5 6.5 0 1 0-4-4z" /> <circle cx="16.5" cy="7.5" r=".5" fill="currentColor" /></svg>Roles</button>
<button class="btn ghost stretch align-left"><svg class="icon" viewBox="0 0 24 24" aria-hidden="true"><path d="M15 12h-5" /> <path d="M15 8h-5" /> <path d="M19 17V5a2 2 0 0 0-2-2H4" /> <path d="M8 21h12a2 2 0 0 0 2-2v-1a1 1 0 0 0-1-1H11a1 1 0 0 0-1 1v1a2 2 0 1 1-4 0V5a2 2 0 1 0-4 0v2a1 1 0 0 0 1 1h3" /></svg>Audit log</button>
<button class="btn ghost stretch align-left"><svg class="icon" viewBox="0 0 24 24" aria-hidden="true"><path d="M22 12h-2.48a2 2 0 0 0-1.93 1.46l-2.35 8.36a.25.25 0 0 1-.48 0L9.24 2.18a.25.25 0 0 0-.48 0l-2.35 8.36A2 2 0 0 1 4.49 12H2" /></svg>Status</button>
</div>
</div>
<hr class="divider">
<div class="foot">
<button class="btn ghost stretch align-left"><svg class="icon" viewBox="0 0 24 24" aria-hidden="true"><path d="m16 17 5-5-5-5" /> <path d="M21 12H9" /> <path d="M9 21H5a2 2 0 0 1-2-2V5a2 2 0 0 1 2-2h4" /></svg>Sign out</button>
</div>
</nav>
<!-- workspace: a Panel with the capped, centred reading column -->
<main class="panel workspace">
<div class="column">
<div class="page-heading">
<div class="title">Account</div>
<div class="subtitle">Your personal details and how you appear on Garage.</div>
</div>
<section class="properties-section">
<div class="header">
<svg class="icon chevron" viewBox="0 0 24 24" aria-hidden="true"><path d="m6 9 6 6 6-6" /></svg>
<div><div>Account</div><span class="subtitle">Your names, sign-in email and account identifiers</span></div>
</div>
<div class="rows">
<div class="property-row">
<div class="label">Username</div>
<div class="value">
<div class="btn-group span">
<div class="field secondary readonly grow"><input value="ellis" disabled></div>
<button class="btn secondary">Change</button>
</div>
</div>
</div>
<div class="property-row">
<div class="label">Display name</div>
<div class="value"><div class="field secondary"><input value="Ellis Hart"></div></div>
</div>
<div class="property-row">
<div class="label">Email</div>
<div class="value"><div class="field secondary readonly"><input value="ellis@hartworks.dev" disabled></div></div>
</div>
<div class="property-row">
<div class="label">Member since</div>
<div class="value"><div class="field secondary readonly"><input value="6 Sep 2026" disabled></div></div>
</div>
<div class="property-row">
<div class="label">User ID</div>
<div class="value">
<div class="btn-group span">
<div class="field secondary readonly mono grow"><input value="usr_8f2c41d9a7" disabled></div>
<button class="btn secondary icon-only" aria-label="Copy"><svg class="icon" viewBox="0 0 24 24" aria-hidden="true"><rect width="14" height="14" x="8" y="8" rx="2" ry="2" /> <path d="M4 16c-1.1 0-2-.9-2-2V4c0-1.1.9-2 2-2h10c1.1 0 2 .9 2 2" /></svg></button>
</div>
</div>
</div>
</div>
</section>
<section class="properties-section">
<div class="header">
<svg class="icon chevron" viewBox="0 0 24 24" aria-hidden="true"><path d="m6 9 6 6 6-6" /></svg>
<div><div>Personal information</div><span class="subtitle">The name and details on your account</span></div>
</div>
<div class="rows">
<div class="property-row">
<div class="label">Legal name</div>
<div class="value"><div class="field secondary readonly"><input value="Ellis Jordan Hart" disabled></div></div>
</div>
<div class="property-row">
<div class="label">Date of birth</div>
<div class="value"><div class="field secondary readonly"><input value="14 Mar 1994" disabled></div></div>
</div>
</div>
</section>
<section class="properties-section">
<div class="header">
<svg class="icon chevron" viewBox="0 0 24 24" aria-hidden="true"><path d="m6 9 6 6 6-6" /></svg>
<div><div>Password</div><span class="subtitle">Used to sign in when a passkey isn't available</span></div>
</div>
<div class="rows">
<div class="property-row">
<div class="label">Password</div>
<div class="value">
<div class="btn-group span">
<div class="field secondary readonly grow"><svg class="icon" viewBox="0 0 24 24" aria-hidden="true"><rect width="18" height="11" x="3" y="11" rx="2" ry="2" /> <path d="M7 11V7a5 5 0 0 1 10 0v4" /></svg><input value="Hidden" disabled></div>
<button class="btn secondary icon-only" aria-label="Change password"><svg class="icon" viewBox="0 0 24 24" aria-hidden="true"><path d="M21.174 6.812a1 1 0 0 0-3.986-3.987L3.842 16.174a2 2 0 0 0-.5.83l-1.321 4.352a.5.5 0 0 0 .623.622l4.353-1.32a2 2 0 0 0 .83-.497z" /> <path d="m15 5 4 4" /></svg></button>
</div>
</div>
</div>
</div>
</section>
</div>
</main>
</div>
</div>
</body>
</html>
+112
View File
@@ -0,0 +1,112 @@
<!-- @dsCard group="Patterns" -->
<!doctype html>
<html lang="en" data-scheme="carbon" data-density="compact">
<head>
<meta charset="utf-8">
<title>Settings pane</title>
<link rel="stylesheet" href="../components.css">
<style>
/* scaffolding - the editor's chrome at dialog size: 580 x 420 at compact, a 176 rail
and a content Panel on the chrome ground */
html, body { background: var(--background); }
.stage { width: 700px; height: 520px; display: flex; align-items: center; justify-content: center; }
.pane { width: 580px; height: 420px; border-radius: var(--panel-radius); overflow: hidden; }
.shell { height: 100%; align-items: stretch; }
.rail { width: 176px; flex: none; display: flex; flex-direction: column; }
.rail .search { padding: var(--gap-sm); }
/* the editor's rail is narrower than the hub's, so its categories inset gapSm not gapMd */
.rail .nav-group { padding-inline: var(--gap-sm); }
.content { flex: 1; min-width: 0; }
.content .scroll { padding: var(--gap-xl) var(--gap-sm) var(--gap-xxl); }
.content .page-heading { margin-bottom: var(--gap-lg); }
</style>
</head>
<body>
<div class="stage">
<div class="pane">
<div class="shell">
<nav class="panel sunken rail">
<div class="search"><label class="field stretch"><svg class="icon" viewBox="0 0 24 24" aria-hidden="true"><path d="m21 21-4.34-4.34" /> <circle cx="11" cy="11" r="8" /></svg><input placeholder="Search"></label></div>
<hr class="divider">
<div class="nav-group">
<div class="caption">Settings</div>
<button class="btn ghost stretch align-left"><svg class="icon" viewBox="0 0 24 24" aria-hidden="true"><path d="M19 21v-2a4 4 0 0 0-4-4H9a4 4 0 0 0-4 4v2" /> <circle cx="12" cy="7" r="4" /></svg>Account</button>
<button class="btn ghost stretch align-left"><svg class="icon" viewBox="0 0 24 24" aria-hidden="true"><rect width="20" height="14" x="2" y="5" rx="2" /> <line x1="2" x2="22" y1="10" y2="10" /> <path d="M6 14h2" /></svg>Billing</button>
<button class="btn secondary stretch align-left"><svg class="icon" viewBox="0 0 24 24" aria-hidden="true"><path d="M12 22a1 1 0 0 1 0-20 10 9 0 0 1 10 9 5 5 0 0 1-5 5h-2.25a1.75 1.75 0 0 0-1.4 2.8l.3.4a1.75 1.75 0 0 1-1.4 2.8z" /> <circle cx="13.5" cy="6.5" r=".5" fill="currentColor" /> <circle cx="17.5" cy="10.5" r=".5" fill="currentColor" /> <circle cx="6.5" cy="12.5" r=".5" fill="currentColor" /> <circle cx="8.5" cy="7.5" r=".5" fill="currentColor" /></svg>Appearance</button>
<button class="btn ghost stretch align-left"><svg class="icon" viewBox="0 0 24 24" aria-hidden="true"><path d="M12 22v-5" /> <path d="M15 8V2" /> <path d="M17 8a1 1 0 0 1 1 1v4a4 4 0 0 1-4 4h-4a4 4 0 0 1-4-4V9a1 1 0 0 1 1-1z" /> <path d="M9 8V2" /></svg>Integrations</button>
</div>
<hr class="divider">
<div class="nav-group">
<div class="caption">Editor</div>
<button class="btn ghost stretch align-left"><svg class="icon" viewBox="0 0 24 24" aria-hidden="true"><path d="M10 8h.01" /> <path d="M12 12h.01" /> <path d="M14 8h.01" /> <path d="M16 12h.01" /> <path d="M18 8h.01" /> <path d="M6 8h.01" /> <path d="M7 16h10" /> <path d="M8 12h.01" /> <rect width="20" height="16" x="2" y="4" rx="2" /></svg>Keymap</button>
</div>
</nav>
<main class="panel content">
<div class="scroll">
<div class="page-heading">
<div class="title">Appearance</div>
<div class="subtitle">How the editor and the map are drawn.</div>
</div>
<section class="properties-section">
<div class="header">
<svg class="icon chevron" viewBox="0 0 24 24" aria-hidden="true"><path d="m6 9 6 6 6-6" /></svg>
<div><div>Editor</div><span class="subtitle">Colours the interface itself is drawn in</span></div>
</div>
<div class="rows">
<div class="property-row">
<div class="label">Colour scheme</div>
<div class="value"><div class="select secondary"><span>Carbon</span><svg class="icon chevron" viewBox="0 0 24 24" aria-hidden="true"><path d="m7 15 5 5 5-5" /><path d="m7 9 5-5 5 5" /></svg></div></div>
</div>
<div class="property-row">
<div class="label">Accent</div>
<div class="value"><div class="select secondary"><span>Default</span><svg class="icon chevron" viewBox="0 0 24 24" aria-hidden="true"><path d="m7 15 5 5 5-5" /><path d="m7 9 5-5 5 5" /></svg></div></div>
</div>
<div class="property-row">
<div class="label">Dark mode</div>
<div class="value"><span class="checkbox checked"></span></div>
</div>
</div>
</section>
<section class="properties-section">
<div class="header">
<svg class="icon chevron" viewBox="0 0 24 24" aria-hidden="true"><path d="m6 9 6 6 6-6" /></svg>
<div><div>Interface</div><span class="subtitle">How much room a control takes up</span></div>
</div>
<div class="rows">
<div class="property-row">
<div class="label">Density</div>
<div class="value"><div class="select secondary"><span>Compact</span><svg class="icon chevron" viewBox="0 0 24 24" aria-hidden="true"><path d="m7 15 5 5 5-5" /><path d="m7 9 5-5 5 5" /></svg></div></div>
</div>
</div>
</section>
<section class="properties-section">
<div class="header">
<svg class="icon chevron" viewBox="0 0 24 24" aria-hidden="true"><path d="m6 9 6 6 6-6" /></svg>
<div><div>Canvas</div><span class="subtitle">The map's own colours, separate from the editor's</span></div>
</div>
<div class="rows">
<div class="property-row">
<div class="label">Colour scheme</div>
<div class="value"><div class="select secondary"><span>Follow editor</span><svg class="icon chevron" viewBox="0 0 24 24" aria-hidden="true"><path d="m7 15 5 5 5-5" /><path d="m7 9 5-5 5 5" /></svg></div></div>
</div>
<div class="property-row">
<div class="label">Dark mode</div>
<div class="value"><span class="checkbox checked"></span></div>
</div>
</div>
</section>
</div>
</main>
</div>
</div>
</div>
</body>
</html>
+68
View File
@@ -0,0 +1,68 @@
<!-- @dsCard group="Patterns" -->
<!doctype html>
<html lang="en" data-scheme="carbon" data-density="product">
<head>
<meta charset="utf-8">
<title>Page states</title>
<link rel="stylesheet" href="../components.css">
<style>
/* scaffolding - three workspace Panels on the chrome ground, one state each:
loading (a spinner), empty (one muted line), error (muted message + outline retry) */
html, body { background: var(--chrome); }
.screen { width: 1100px; height: 440px; }
.shell { height: 100%; align-items: stretch; }
.shell > .panel { flex: 1; min-width: 0; display: flex; flex-direction: column;
padding: var(--gap-xxl) var(--gap-xl); }
.shell > .panel > .page-heading { margin-bottom: var(--gap-xxl); }
.fill { flex: 1; display: flex; flex-direction: column; align-items: center; justify-content: center; gap: var(--gap-md); }
.note { padding: var(--gap-md) var(--container-padding); display: flex; flex-direction: column; align-items: flex-start; gap: var(--gap-md); }
</style>
</head>
<body>
<div class="screen">
<div class="shell">
<!-- loading -->
<section class="panel">
<div class="page-heading">
<div class="title">Payments</div>
<div class="subtitle">What you've bought, and what you're still paying for.</div>
</div>
<div class="fill"><div class="spinner" role="status" aria-label="Loading"></div></div>
</section>
<!-- empty -->
<section class="panel">
<div class="page-heading">
<div class="title">Projects</div>
<div class="subtitle">Applications you build and sell on Garage.</div>
</div>
<div class="fill">
<div class="muted">No projects yet</div>
</div>
</section>
<!-- error: still a section, with nothing in it -->
<section class="panel">
<div class="page-heading">
<div class="title">Security</div>
<div class="subtitle">Your password, passkeys and signed-in devices.</div>
</div>
<section class="properties-section">
<div class="header">
<svg class="icon chevron" viewBox="0 0 24 24" aria-hidden="true"><path d="m6 9 6 6 6-6" /></svg>
<div><div>Passkeys</div><span class="subtitle">Sign in with your device instead of a password</span></div>
</div>
<div class="rows">
<div class="note">
<div class="muted">Couldn't load your passkeys.</div>
<button class="btn outline">Try again</button>
</div>
</div>
</section>
</section>
</div>
</div>
</body>
</html>
+259
View File
@@ -0,0 +1,259 @@
/* garage_ui design tokens. Generated by garage_ui/tool/export_design_tokens_test.dart
- dont edit by hand, rerun the export.
Scheme: data-scheme="carbon" (default) | "dark" | "light"
Density: data-density="product" (default) | "normal" | "compact" */
@import url("https://fonts.googleapis.com/css2?family=Geist:wght@300;400;500;600;700&family=Geist+Mono:wght@400;500&display=swap");
:root {
--font-sans: "Geist", system-ui, sans-serif;
--font-mono: "Geist Mono", ui-monospace, monospace;
--weight-body: 300;
--weight-control: 400;
--weight-medium: 500;
--weight-semibold: 600;
--radius-xs: 2px;
--radius-sm: 4px;
--radius-md: 6px;
--radius-lg: 8px;
--radius-xl: 10px;
--radius-xxl: 12px;
--panel-radius: 10px;
--panel-gap: 5px;
--panel-border-width: 1.15px;
--property-split: 0.4;
--property-label-gap: 10px;
--dialog-max-width: 350px;
}
:root, [data-scheme="carbon"] {
--background: #0d0d0d;
--foreground: #f2f2f2;
--chrome: #010101;
--surface-sunken: #0a0a0a;
--card: #1b1b1b;
--muted: #0f0f0f;
--muted-foreground: #8f8f8f;
--row-text: #c2c2c2;
--row-hovered: #222222;
--popover: #000000;
--popover-border: #1c1c1c;
--popover-item-hovered: #1f1f1f;
--tooltip-background: #080808;
--tooltip-border: #1f1f1f;
--primary: #e8e8e8;
--primary-hovered: #fefefe;
--primary-foreground: #000000;
--secondary: #303030;
--secondary-hovered: #424242;
--secondary-foreground: #f2f2f2;
--destructive: #c43333;
--control-fill: #080808;
--control-fill-hovered: #070707;
--control-fill-focused: #000000;
--control-border: #2a2a2a;
--switch-track-inactive: #0f0f0f;
--border: #010101;
--divider: #202020;
--panel-border: #222222;
--panel-border-highlighted: #3a3a3a;
--properties-section-border: #272727;
--ring: #ffffff;
--chart-1: #f45b69;
--chart-2: #86d957;
--chart-3: #62a7ff;
--chart-4: #ffc857;
--chart-5: #ff8c42;
}
[data-scheme="dark"] {
--background: #303030;
--foreground: #e6e6e6;
--chrome: #171717;
--surface-sunken: #272727;
--card: #3d3d3d;
--muted: #1d1d1d;
--muted-foreground: #999999;
--row-text: #c1c1c1;
--row-hovered: #474747;
--popover: #191919;
--popover-border: #2d2d2d;
--popover-item-hovered: #424242;
--tooltip-background: #1d1d1d;
--tooltip-border: #303030;
--primary: #4772b3;
--primary-hovered: #6b8fc4;
--primary-foreground: #ffffff;
--secondary: #565656;
--secondary-hovered: #676767;
--secondary-foreground: #e6e6e6;
--destructive: #a9575f;
--control-fill: #1d1d1d;
--control-fill-hovered: #222222;
--control-fill-focused: #1a1a1a;
--control-border: #353535;
--switch-track-inactive: #1d1d1d;
--border: #171717;
--divider: #454545;
--panel-border: #464646;
--panel-border-highlighted: #606060;
--properties-section-border: #4c4c4c;
--ring: #6592d7;
--chart-1: #ff3352;
--chart-2: #8bdc00;
--chart-3: #2890ff;
--chart-4: #edba18;
--chart-5: #ed5700;
}
[data-scheme="light"] {
--background: #f2f2f4;
--foreground: #1a1a1c;
--chrome: #cdcdd5;
--surface-sunken: #e7e7ea;
--card: #fefeff;
--muted: #d7d7de;
--muted-foreground: #65656d;
--row-text: #3b3b40;
--row-hovered: #fefeff;
--popover: #d1d1d8;
--popover-border: #ededf0;
--popover-item-hovered: #fefeff;
--tooltip-background: #d7d7de;
--tooltip-border: #f2f2f4;
--primary: #3a63a1;
--primary-hovered: #537fc1;
--primary-foreground: #ffffff;
--secondary: #fefeff;
--secondary-hovered: #fefeff;
--secondary-foreground: #1a1a1c;
--destructive: #b3474f;
--control-fill: #d7d7de;
--control-fill-hovered: #e0e0e4;
--control-fill-focused: #d3d3d9;
--control-border: #f9f9fa;
--switch-track-inactive: #d7d7de;
--border: #cdcdd5;
--divider: #d8d8de;
--panel-border: #d7d7dd;
--panel-border-highlighted: #fefeff;
--properties-section-border: #eaeaff;
--ring: #4880d5;
--chart-1: #ff3352;
--chart-2: #8bdc00;
--chart-3: #2890ff;
--chart-4: #edba18;
--chart-5: #ed5700;
}
:root, [data-density="product"] {
--font-size: 12px;
--line-height: 1.25;
--line-box: 15px;
--control-height: 33px;
--control-padding-x: 10px;
--control-padding-y: 9px;
--control-gap: 5px;
--control-border-width: 1px;
--menu-row-height: 33px;
--popup-row-height: 33px;
--explorer-row-height: 29px;
--chrome-bar-height: 43px;
--property-row-height: 36px;
--label-column-height: 31px;
--properties-section-gap: 15px;
--explorer-row-base-padding: 8px;
--explorer-row-end-padding: 12px;
--list-row-indent: 10px;
--container-gap: 10px;
--container-padding: 20px;
--gap-xxs: 3px;
--gap-xs: 5px;
--gap-sm: 8px;
--gap-md: 10px;
--gap-lg: 15px;
--gap-xl: 20px;
--gap-xxl: 30px;
--text-xxs: 11px;
--text-xs: 13px;
--text-sm: 17px;
--text-lg: 22px;
--icon-sm: 12px;
--icon-md: 20px;
--icon-lg: 24px;
}
[data-density="compact"] {
--font-size: 10px;
--line-height: 1.1;
--line-box: 11px;
--control-height: 23px;
--control-padding-x: 10px;
--control-padding-y: 6px;
--control-gap: 4px;
--control-border-width: 1px;
--menu-row-height: 20px;
--popup-row-height: 20px;
--explorer-row-height: 22px;
--chrome-bar-height: 31px;
--property-row-height: 28px;
--label-column-height: 26px;
--properties-section-gap: 6px;
--explorer-row-base-padding: 4px;
--explorer-row-end-padding: 10px;
--list-row-indent: 6px;
--container-gap: 8px;
--container-padding: 16px;
--gap-xxs: 2px;
--gap-xs: 4px;
--gap-sm: 6px;
--gap-md: 8px;
--gap-lg: 12px;
--gap-xl: 16px;
--gap-xxl: 24px;
--text-xxs: 9px;
--text-xs: 11px;
--text-sm: 14px;
--text-lg: 18px;
--icon-sm: 10px;
--icon-md: 20px;
--icon-lg: 24px;
}
[data-density="normal"] {
--font-size: 10px;
--line-height: 1.1;
--line-box: 11px;
--control-height: 27px;
--control-padding-x: 12px;
--control-padding-y: 8px;
--control-gap: 5px;
--control-border-width: 1px;
--menu-row-height: 26px;
--popup-row-height: 26px;
--explorer-row-height: 30px;
--chrome-bar-height: 37px;
--property-row-height: 30px;
--label-column-height: 26px;
--properties-section-gap: 15px;
--explorer-row-base-padding: 8px;
--explorer-row-end-padding: 14px;
--list-row-indent: 12px;
--container-gap: 10px;
--container-padding: 20px;
--gap-xxs: 3px;
--gap-xs: 5px;
--gap-sm: 8px;
--gap-md: 10px;
--gap-lg: 15px;
--gap-xl: 20px;
--gap-xxl: 30px;
--text-xxs: 9px;
--text-xs: 11px;
--text-sm: 14px;
--text-lg: 18px;
--icon-sm: 10px;
--icon-md: 20px;
--icon-lg: 24px;
}
+256
View File
@@ -0,0 +1,256 @@
{
"_generated": "by garage_ui/tool/export_design_tokens_test.dart - dont edit by hand",
"fonts": {
"sans": "Geist",
"mono": "Geist Mono"
},
"weights": {
"body": 300,
"control": 400,
"medium": 500,
"semibold": 600
},
"schemes": {
"carbon": {
"background": "#0d0d0d",
"foreground": "#f2f2f2",
"chrome": "#010101",
"surface-sunken": "#0a0a0a",
"card": "#1b1b1b",
"muted": "#0f0f0f",
"muted-foreground": "#8f8f8f",
"row-text": "#c2c2c2",
"row-hovered": "#222222",
"popover": "#000000",
"popover-border": "#1c1c1c",
"popover-item-hovered": "#1f1f1f",
"tooltip-background": "#080808",
"tooltip-border": "#1f1f1f",
"primary": "#e8e8e8",
"primary-hovered": "#fefefe",
"primary-foreground": "#000000",
"secondary": "#303030",
"secondary-hovered": "#424242",
"secondary-foreground": "#f2f2f2",
"destructive": "#c43333",
"control-fill": "#080808",
"control-fill-hovered": "#070707",
"control-fill-focused": "#000000",
"control-border": "#2a2a2a",
"switch-track-inactive": "#0f0f0f",
"border": "#010101",
"divider": "#202020",
"panel-border": "#222222",
"panel-border-highlighted": "#3a3a3a",
"properties-section-border": "#272727",
"ring": "#ffffff",
"chart-1": "#f45b69",
"chart-2": "#86d957",
"chart-3": "#62a7ff",
"chart-4": "#ffc857",
"chart-5": "#ff8c42"
},
"dark": {
"background": "#303030",
"foreground": "#e6e6e6",
"chrome": "#171717",
"surface-sunken": "#272727",
"card": "#3d3d3d",
"muted": "#1d1d1d",
"muted-foreground": "#999999",
"row-text": "#c1c1c1",
"row-hovered": "#474747",
"popover": "#191919",
"popover-border": "#2d2d2d",
"popover-item-hovered": "#424242",
"tooltip-background": "#1d1d1d",
"tooltip-border": "#303030",
"primary": "#4772b3",
"primary-hovered": "#6b8fc4",
"primary-foreground": "#ffffff",
"secondary": "#565656",
"secondary-hovered": "#676767",
"secondary-foreground": "#e6e6e6",
"destructive": "#a9575f",
"control-fill": "#1d1d1d",
"control-fill-hovered": "#222222",
"control-fill-focused": "#1a1a1a",
"control-border": "#353535",
"switch-track-inactive": "#1d1d1d",
"border": "#171717",
"divider": "#454545",
"panel-border": "#464646",
"panel-border-highlighted": "#606060",
"properties-section-border": "#4c4c4c",
"ring": "#6592d7",
"chart-1": "#ff3352",
"chart-2": "#8bdc00",
"chart-3": "#2890ff",
"chart-4": "#edba18",
"chart-5": "#ed5700"
},
"light": {
"background": "#f2f2f4",
"foreground": "#1a1a1c",
"chrome": "#cdcdd5",
"surface-sunken": "#e7e7ea",
"card": "#fefeff",
"muted": "#d7d7de",
"muted-foreground": "#65656d",
"row-text": "#3b3b40",
"row-hovered": "#fefeff",
"popover": "#d1d1d8",
"popover-border": "#ededf0",
"popover-item-hovered": "#fefeff",
"tooltip-background": "#d7d7de",
"tooltip-border": "#f2f2f4",
"primary": "#3a63a1",
"primary-hovered": "#537fc1",
"primary-foreground": "#ffffff",
"secondary": "#fefeff",
"secondary-hovered": "#fefeff",
"secondary-foreground": "#1a1a1c",
"destructive": "#b3474f",
"control-fill": "#d7d7de",
"control-fill-hovered": "#e0e0e4",
"control-fill-focused": "#d3d3d9",
"control-border": "#f9f9fa",
"switch-track-inactive": "#d7d7de",
"border": "#cdcdd5",
"divider": "#d8d8de",
"panel-border": "#d7d7dd",
"panel-border-highlighted": "#fefeff",
"properties-section-border": "#eaeaff",
"ring": "#4880d5",
"chart-1": "#ff3352",
"chart-2": "#8bdc00",
"chart-3": "#2890ff",
"chart-4": "#edba18",
"chart-5": "#ed5700"
}
},
"densities": {
"compact": {
"font-size": 10.0,
"line-height": 1.1,
"line-box": 11.0,
"control-height": 23.0,
"control-padding-x": 10.0,
"control-padding-y": 6.0,
"control-gap": 4.0,
"control-border-width": 1.0,
"menu-row-height": 20.0,
"popup-row-height": 20.0,
"explorer-row-height": 22.0,
"chrome-bar-height": 31.0,
"property-row-height": 28.0,
"label-column-height": 26.0,
"properties-section-gap": 6.0,
"explorer-row-base-padding": 4.0,
"explorer-row-end-padding": 10.0,
"list-row-indent": 6.0,
"container-gap": 8.0,
"container-padding": 16.0,
"gap-xxs": 2.0,
"gap-xs": 4.0,
"gap-sm": 6.0,
"gap-md": 8.0,
"gap-lg": 12.0,
"gap-xl": 16.0,
"gap-xxl": 24.0,
"text-xxs": 9.0,
"text-xs": 11.0,
"text-sm": 14.0,
"text-lg": 18.0,
"icon-sm": 10.0,
"icon-md": 20.0,
"icon-lg": 24.0
},
"normal": {
"font-size": 10.0,
"line-height": 1.1,
"line-box": 11.0,
"control-height": 27.0,
"control-padding-x": 12.0,
"control-padding-y": 8.0,
"control-gap": 5.0,
"control-border-width": 1.0,
"menu-row-height": 26.0,
"popup-row-height": 26.0,
"explorer-row-height": 30.0,
"chrome-bar-height": 37.0,
"property-row-height": 30.0,
"label-column-height": 26.0,
"properties-section-gap": 15.0,
"explorer-row-base-padding": 8.0,
"explorer-row-end-padding": 14.0,
"list-row-indent": 12.0,
"container-gap": 10.0,
"container-padding": 20.0,
"gap-xxs": 3.0,
"gap-xs": 5.0,
"gap-sm": 8.0,
"gap-md": 10.0,
"gap-lg": 15.0,
"gap-xl": 20.0,
"gap-xxl": 30.0,
"text-xxs": 9.0,
"text-xs": 11.0,
"text-sm": 14.0,
"text-lg": 18.0,
"icon-sm": 10.0,
"icon-md": 20.0,
"icon-lg": 24.0
},
"product": {
"font-size": 12.0,
"line-height": 1.25,
"line-box": 15.0,
"control-height": 33.0,
"control-padding-x": 10.0,
"control-padding-y": 9.0,
"control-gap": 5.0,
"control-border-width": 1.0,
"menu-row-height": 33.0,
"popup-row-height": 33.0,
"explorer-row-height": 29.0,
"chrome-bar-height": 43.0,
"property-row-height": 36.0,
"label-column-height": 31.0,
"properties-section-gap": 15.0,
"explorer-row-base-padding": 8.0,
"explorer-row-end-padding": 12.0,
"list-row-indent": 10.0,
"container-gap": 10.0,
"container-padding": 20.0,
"gap-xxs": 3.0,
"gap-xs": 5.0,
"gap-sm": 8.0,
"gap-md": 10.0,
"gap-lg": 15.0,
"gap-xl": 20.0,
"gap-xxl": 30.0,
"text-xxs": 11.0,
"text-xs": 13.0,
"text-sm": 17.0,
"text-lg": 22.0,
"icon-sm": 12.0,
"icon-md": 20.0,
"icon-lg": 24.0
}
},
"shape": {
"radius-xs": 2.0,
"radius-sm": 4.0,
"radius-md": 6.0,
"radius-lg": 8.0,
"radius-xl": 10.0,
"radius-xxl": 12.0,
"panel-radius": 10.0,
"panel-gap": 5.0,
"panel-border-width": 1.15,
"property-split": 0.4,
"property-label-gap": 10,
"dialog-max-width": 350
}
}
+458 -460
View File
@@ -1,503 +1,501 @@
# Garage UI style guide
# garage_ui style guide
This is not the widget API reference (read the source for that — every file in
`lib/` is short and commented). This is the *other* half: which widget, which
variant, which colour token, in which situation. Getting a Garage app to use
`Button` and `Panel` is easy. Getting it to actually look like a Garage app —
right variant for the right emphasis, right token for the right surface, right
gap for the right kind of space — is the part that doesn't fall out of the
API. That's what this document is for.
How to build a screen out of garage_ui so it actually looks like a Garage app.
The API is in the source. This is the other half: which widget, which variant,
where — and, mostly, what to leave alone.
It's written from **observed usage** in Arcs & Angles (metro_map_maker) and
Music Maker, the two real apps built on this package. Every rule below is
backed by a real call site, not a guess at what "should" be idiomatic. Where
a pattern only has 1-2 examples, that's said explicitly — treat it as a lead,
not a law.
It's written from the two apps that are the reference:
## Where this comes from
- **Arcs & Angles, blender mode** (`metro_map_maker`, `lib/pages/blender/`) — a
dense desktop editor on the `compact` density.
- **The Garage hub** (`garage_dashboard_portal`) — a web product on the
`product` density.
Two influences, and they are not the same kind of influence — conflating them
is the usual misreading:
Where those two do something the guide says not to, it's listed at the end
under [Dont copy these](#dont-copy-these). An existing call site is not
precedent.
- **shadcn (via `shadcn_flutter`) — the API surface.** Variant names
(`.primary` / `.secondary` / `.outline` / `.ghost` / `.destructive`), the
`ColourScheme` slot vocabulary, the dot-constructor shape. This is why a
shadcn snippet usually *compiles*.
- **Blender — the rendering.** Flat chrome, bordered panels, dense controls,
no elevation, a properties pane with a hard split down it. This is why the
same snippet doesn't *look* like shadcn once it runs.
So: **not a pixel-for-pixel restyle of shadcn.** The names carried over; the
geometry, the density and the entire chrome layer did not. `shadcn_flutter`
was dropped as a dependency once the port finished — nothing here defers to
it, and where the two disagree on how something should look, this package
wins. Expect ported code to compile and then need its spacing and emphasis
re-picked against the tables below.
## The one rule: let the theme speak
## Mental model
garage_ui already knows what everything should look like. The colour scheme,
the density and the variant between them decide every colour, font size,
weight, icon size, padding, radius and gap. Your job is to pick the **widget**
and the **variant**. Then stop.
A Garage app has three layers, outside-in:
So, inside or around a garage_ui component, don't:
1. **Chrome** — the app's own furniture: headers, footers, the menu bar, the
shell that docks everything else. Flat, dark, no elevation. Reads as part
of the window, not as content sitting on the window.
2. **Panels** — bordered, rounded, elevated-feeling regions that hold actual
tool content (explorer trees, property inspectors, docked windows). This
is where most of the UI actually lives.
3. **Controls** — buttons, fields, selects, menus. Live inside panels or
chrome, never bare against the app background.
- pass a `TextStyle` with a `fontSize`, `fontWeight` or `color`
- give an `Icon` a `size:` or `color:`
- write a literal `EdgeInsets`, `SizedBox`, `Gap(8)` or `BorderRadius.circular(8)`
- pass `alignment:` to a button that doesnt need it
- force `density: ControlDensity.compact` on a control to make it "fit"
- wrap a dialog's content in a `ConstrainedBox(maxWidth: 360)`
- build a `Container` with a fill, border and radius to make a badge, a pill, a
warning box or a popover
Nothing in this system uses Flutter's Material widgets. There is no
`ThemeData.dark()`, no `Colors.black`, no `Scaffold`. Every colour comes from
`ColourScheme`, every size comes from `Density`, every font comes from
`Typography`. If a widget you're building reaches for `package:flutter/material.dart`
or a literal `Color(0x...)` outside `theme/*.dart`, that's the tell you've
stepped outside the system.
Every one of those is a number or a colour that was chosen once, per call site,
and stops agreeing with the rest of the app the moment the density, scheme or
accent changes. The components are built as families — outline buttons share
text fields' fill, stroke and radius on purpose so they "read as one family
instead of each getting styled by hand per call site". One override breaks the
family.
## Getting the theme
When something looks wrong, the fix is a different variant, a different
widget, or a change **in garage_ui** so every app gets it. Not a local
override. That's how `ButtonStyle.ghostDestructive` came about: apps kept
hand-colouring ghost buttons red, so it became a variant.
What you *can* reach for, when a component doesnt cover it:
- `Gap.xs()` … `Gap.xxl()` and `density.gapXs` … for space between things
- `density.textXxs` … `density.textLg`, or the text extensions, for text size
- `theme.typography.medium` / `.semiBold` for weight
- `scheme.<slot>` for colour, when you're drawing something garage_ui doesnt
have a widget for
These are tokens — they move with the theme. A literal never does.
## Setting up
```dart
final theme = GarageTheme.of(context);
final cs = theme.colorScheme;
final theme = ThemeData(
colorScheme: GarageSchemes.carbon, // or your own, see below
density: const Density.product(), // or .compact() / .normal()
);
GarageApp.router(routerConfig: router, theme: theme);
```
Everything hangs off `theme`: `theme.colorScheme`, `theme.density`,
`theme.typography`, `theme.iconTheme`, `theme.radiusMd` / `.borderRadiusMd`
(and `Sm`/`Lg`/`Xl`/`Xxl`), `theme.panelRadius`, `theme.panelGap`.
`GarageApp` is built on `WidgetsApp`, not `MaterialApp`, and installs
`GarageTheme` plus the scroll behaviour and scrollbar. Nothing in garage_ui
touches Material. If a file reaches for `package:flutter/material.dart`, it has
left the system.
One exception: an app's *unaccented* scheme — the one nobody's accent-colour
override has touched — is read through the app's settings provider, not
`GarageTheme.of(context)`. In Arcs & Angles that's
`context.watch<SettingsProvider>().anaScheme`. Reach for this specifically
when you need `chrome` on something that must stay neutral even if the user
picked a wild accent colour (this is rare — most code never needs to do this,
because `ChromeBar`/`Panel`/`GarageShell` already read `chrome`/`panel`
internally). See "Colour tokens" below for why `chrome` gets this treatment.
Leave the rest of `ThemeData` on its defaults — `scaling 1.0`, `radius 0.5`
(so `radiusSm 4`, `radiusMd 6`), `panelRadius 10`, `panelGap 5`. Both
reference apps do.
## Colour tokens
Read the theme with `GarageTheme.of(context)`: `.colorScheme`, `.density`,
`.typography`, `.iconTheme`, `.radiusMd` and friends.
`ColourScheme` (in `theme/colour_scheme.dart`) is one flat list of named
colours — no light/dark split, no derived roles computed at paint time. Every
field is authored by hand per scheme (Arcs & Angles ships eleven: zinc,
crimson, slate, forest, stone, teal, indigo, amber, carbon, fuchsia, plus each
one's light twin). When you add a new UI surface, you're choosing which of
these *existing* tokens it belongs to — you're not inventing a new colour.
### Colour schemes
### Base semantic slots (shadcn-shaped, still the backbone)
| Token | What it's for |
|---|---|
| `background` / `foreground` | The app's base surface and default text colour. |
| `card` / `cardForeground` | `Card`/`SurfaceCard` fill and the text colour merged inside them. |
| `popover` / `popoverForeground` / `popoverBorder` | Dropdowns, select popups, context menus — anything that floats over content in an `OverlayPortal`. |
| `primary` / `primaryHovered` / `primaryForeground` | The accent. Active/engaged control state, the one CTA in a dialog. Swappable per-user via `withAccent()`. |
| `secondary` / `secondaryHovered` / `secondaryForeground` | Neutral filled control — a resting toggle, an attached-to-a-field icon button. Not an accent colour, just "has a fill." |
| `muted` / `mutedForeground` | De-emphasised text/backgrounds — labels, hints, disabled-adjacent copy. `.muted()` text extension reads `mutedForeground`. |
| `destructive` | Delete/discard/record actions. Used sparingly — 3 call sites total in Arcs & Angles. |
| `border` | Generic 1px outline — text field default border colour, general dividing lines. |
| `divider` | A line *between* things in a layout (menu separators, section dividers) — conceptually different from `border` even though schemes often set them equal. |
| `ring` | Keyboard-focus outline. Not the canvas selection ring — see `canvasSelectionRing`. |
| `chart1`-`chart5` | Reserved for data visualisation, unused by the UI kit itself. |
### App-chrome slots (the part shadcn never had)
| Token | What it's for |
|---|---|
| `chrome` | Header/footer/menu-bar background. Deliberately nudged off `background` so it reads as *app furniture*, not content. Read via the unaccented scheme (see above) — chrome shouldn't shift when the user picks an accent. `ChromeBar` and `GarageShell` apply this for you; you'd only reach for it by hand building a header from scratch (see `blender_header.dart`, `scene_stats_hud.dart`). |
| `panel` / `panelBorder` / `panelBorderHighlighted` | `Panel`'s fill and border — resting vs. "this is the active/hovered one" (see `Panel(active: ...)`). This is the surface docked tool content lives in. |
| `input` / `inputBackground` / `inputBackgroundHovered` / `inputBackgroundFocused` / `inputBorder` | Text field fill (three interaction states) and border. |
| `explorerRowEven` / `explorerRowOdd` / `explorerRowHovered` / `explorerRowText` | Zebra-striped tree/list rows (explorer panel, layer lists). |
| `menuItemText` / `menuItemHovered` | Dropdown/menu row text and hover fill. |
| `popoverItemHovered` | Hover fill for popover rows that aren't menu items (kept distinct from `menuItemHovered` while the two are still being evaluated — may merge later). |
| `tooltipBackground` / `tooltipBorder` | Tooltips get their own pair rather than reusing `popover*` — they sit on top of *everything* and want more contrast than a panel-level surface. |
| `propertiesSectionBackground` / `propertiesSectionBorder` / `propertiesSectionLabel` | The boxed sub-sections inside an object-properties panel. |
| `canvasBackdrop` / `canvasPaper` / `canvasGridMinor` / `canvasGridMajor` / `canvasGridMajorDot` / `canvasBoundary` | Authored canvas colours — not derived at paint time, these are picked by hand per scheme like everything else. App-specific (Arcs & Angles' map canvas); a non-canvas app can mostly ignore this group. |
| `canvasAlignmentGuide` | Smart-guide lines while dragging/resizing. Deliberately its own slot, not `ring` — `ring` is keyboard focus, a different job. |
| `canvasSelectionRing` | Selection outline/handles. Tracks `primary` for most schemes but exists as its own slot so an achromatic scheme (carbon: near-black/near-white primary) can still give selection actual hue. If you add `withAccent()` support anywhere, remember `canvasSelectionRing` needs the same brightened-for-visibility treatment `_brightenForSelectionRing` gives it, or an accent override leaves the selection ring the one thing on screen still showing the old colour. |
### Authoring a new scheme
Look at `settings_state.dart` in the host app, not the package — that's where
the actual eleven-scheme palette lives (the package only defines the *type*
and the neutral fallback used in tests/demos). Each scheme is grouped under
`// ── Accounted for ──` vs `// ── not reviewed yet ──` comments — that's a
live audit trail, not decoration; keep using it as new tokens get added so
it's visible which colours were deliberately chosen vs. still riding an old
default.
## Density & spacing
`Density` (`theme/theme_data.dart`) is the **only** place pixel heights get
hand-set. Everything else — icon size, padding, line-box height — is a
derived getter. The class doc lays out the chain in full; the short version:
- You set `controlHeight` (23 compact / 27 normal), `fontSize` (10, both
densities), `lineHeight` (1.1, both densities).
- `lineBox = (fontSize * lineHeight).roundToDouble()` falls out of those.
- `iconSize = lineBox` — a control icon always matches the text beside it.
- `controlPaddingY = (controlHeight - lineBox) / 2` — padding is *derived
from* the height target, never the other way round.
**Never hand-type a control height or a vertical padding.** If a number needs
tuning, it belongs in `Density`, not at the call site — that's exactly the
mistake the class doc says produced four different control heights and a
stray `Transform.translate` before this system existed.
Two densities are in active use: `ButtonDensity.compact` (54 call sites) is
the default for tool chrome — toolbars, menus, panels. `ButtonDensity.normal`
(5 call sites) shows up for things meant to feel less cramped — e.g. the
`Button.primary` "confirm this row" pattern in `blender_properties_section.dart`
via `ButtonDensity.fromTheme(theme)`. Default to compact unless you have a
specific reason not to.
Two spacing scales, don't mix them up:
- `controlGap` — INSIDE a control (icon-to-label gap). Tighter, on purpose.
It's also the base unit the gap scale below is derived from.
- `containerGap` / `containerPadding` — between controls in a panel/popover/
dialog, and the padding inside one.
### The gap scale
Layout spacing between widgets comes off `theme.density`, not a literal:
| Step | compact | normal | Use it for |
|---|---|---|---|
| `gapXxs` | 2 | 3 | hairline — a label sat directly above its value |
| `gapXs` | 4 | 5 | tight — icon-adjacent, or items reading as one unit |
| `gapSm` | 6 | 8 | snug |
| `gapMd` | 8 | 10 | **the default** — related but distinct |
| `gapLg` | 12 | 15 | section-level, within a panel or form |
| `gapXl` | 16 | 20 | between major blocks |
| `gapXxl` | 24 | 30 | page-level |
Don't hand-author 37 colours. `GarageSchemes` ships `dark`, `light` and
`carbon` (the one the Garage apps run), and `ColourScheme.derive` builds a
complete scheme from four:
```dart
const Gap.md(), // <- this, not Gap(8)
```
`Gap` has a named constructor per step. They resolve their extent from the
theme at build time, so a call site stays `const` and still tracks the density
- no `GarageTheme.of(context)` needed in a build method just because it
contains a gap. `Gap(n)` with a literal still works and still wins, for the
rare thing that genuinely isn't on the scale.
When in doubt, reach for `gapMd`. It's the same 8px `Gap(8)` was, so the old
advice hasn't changed — it just has a name now, and it moves when the density
does instead of staying 8 forever.
`gapMd` equals `containerGap` and `gapXl` equals `containerPadding` at both
densities. That's not arranged, it's what those two were already set to, which
is the evidence `controlGap` is the right base unit —
`test/density_gap_scale_test.dart` holds it to that.
**Reaching for a literal is now the exception, not the rule.** Before the
scale existed the two Garage web frontends had drifted to sixteen distinct gap
values between them, including a 3, a 5 and ten 14s. If a step doesn't fit,
that's worth a conversation about the scale rather than a one-off number.
## Buttons — variant semantics
`Button` and `IconButton` both expose five named constructors:
`.primary` / `.secondary` / `.outline` / `.ghost` / `.destructive`. Real usage
across both apps settles into a clear pattern — this is the single most
useful thing in this document:
| Variant | Meaning | Evidence |
|---|---|---|
| **ghost** | Default, lowest-emphasis action. Toolbar icons, dialog close (X) buttons, settings-cog buttons. Most common `IconButton` variant by a wide margin (15 sites). | `pane_dialog.dart` close button, `blender_editor.dart` header icons |
| **outline** | Second most common (`Button.outline`: 14 sites). The "resting/inactive" half of a toggle pair, AND the standard "Cancel"/dismissive action in a dialog action row. | `export_dialog_widgets.dart`: `Button.outline(onPressed: onCancel, child: Text("Cancel"))` |
| **secondary** | Neutral filled control — NOT a toggle's resting state (that's outline), more like "has a job but isn't the emphasised one." An icon button glued onto a text field (browse/file-picker button in a `ButtonGroup`) — see *Properties* below; the field goes `TextFieldVariant.secondary` to match, and reaching for `outline` here is the usual slip. Also used as a toggle's resting state in a couple of places (Music Maker's transport controls) — outline and secondary are somewhat interchangeable for "not active right now," pick whichever reads better against the surrounding controls. | `export_dialog_widgets.dart` browse button, Music Maker transport |
| **primary** | The accent colour. Two jobs: (1) the *engaged* half of a toggle-button pair — `condition ? primary : outline` is the standard toggle idiom, used repeatedly (`_SnapPopoverButton`, `draw_panel.dart` eyedropper, Music Maker play/pause); (2) the single confirm/CTA action in a dialog, almost always via the `PrimaryButton` shorthand rather than `Button.primary` directly. | `_open ? IconButton.primary(...) : IconButton.outline(...)` |
| **destructive** | Reserved for genuinely dangerous/irreversible actions — delete, record. Rare on purpose (3 sites total). Don't reach for it just because something is "important." | Music Maker's record toggle: `recording ? IconButton.destructive(...) : IconButton.secondary(...)` |
**The toggle-button recipe** (this exact shape appears in every editor):
```dart
active
? IconButton.primary(
density: ButtonDensity.compact,
icon: Icon(LucideIcons.some_icon).iconSmall,
onPressed: onToggle,
)
: IconButton.outline(
density: ButtonDensity.compact,
icon: Icon(LucideIcons.some_icon).iconSmall,
onPressed: onToggle,
)
```
**The dialog action-row recipe** (`export_dialog_widgets.dart`, verbatim shape):
```dart
Row(
children: [
const Spacer(),
Button.outline(onPressed: onCancel, child: const Text("Cancel")),
const Gap(8),
PrimaryButton(onPressed: enabled ? onConfirm : null, child: Text(confirmLabel)),
],
ColourScheme.derive(
brightness: Brightness.dark,
background: ...,
foreground: ...,
primary: ...,
)
```
There are also bare `PrimaryButton` / `SecondaryButton` / `OutlineButton` /
`GhostButton` / `DestructiveButton` widgets (no `.constructor` dot-syntax) —
lighter-weight wrappers around the same variants. `PrimaryButton` specifically
is the idiomatic way to write a dialog's confirm button, over `Button.primary`.
Every other slot is derived on a perceptual lightness ladder — surfaces step
up or down from the background, strokes are measured off the surface they
outline, text is a fraction of the background-to-foreground span. Any derived
slot can be pinned by passing it. `schemes.dart` is the worked example.
A user-picked accent goes through `scheme.withAccent(colour)`, which swaps
`primary`, `primaryHovered`, `ring` and a contrasting `primaryForeground`, and
nothing else.
### Density: pick the tier, don't tune it
| | `compact` | `normal` | `product` |
|---|---|---|---|
| For | dense desktop tools | the same, roomier | web / product apps |
| Used by | Arcs & Angles | A&A "Comfortable" | the hub |
| `fontSize` | 10 | 10 | 12 |
| `controlHeight` | 23 | 27 | 33 |
| `chromeBarHeight` | 31 | 37 | 43 |
Use the named constructor. `Density()` is the same as `Density.compact()`,
which is a trap for a product app.
`Density`'s fields are the only hand-set pixel values in the system; padding,
icon size and line boxes are derived from them. If a tier feels wrong, that's
a conversation about the tier, not a reason to set sizes at call sites.
Controls follow the theme's tier. A per-control `density:` override exists for
exactly one job — a header bar that has to match a 23px menu bar — and even
then it mixes tiers (compact geometry, the theme's font). Don't use it to make
something smaller.
## Colour: what the slots are for
You mostly wont touch these — the components read them. When you do draw
something yourself, pick the slot by what the thing *is*.
| Slot | What it is |
|---|---|
| `background` / `foreground` | the page ground and default text. Also a `Panel`'s fill |
| `chrome` | header and footer bars, and the gutter between panels |
| `surfaceSunken` | one step below the ground — side rails, panel bodies, list backgrounds |
| `card` | raised surface — cards, properties sections, dialogs |
| `muted` / `mutedForeground` | de-emphasised fill / secondary text, hints, units |
| `rowText` / `rowHovered` | a row's resting label colour / hovered row, in lists and menus |
| `popover` / `popoverBorder` | menus, select popups, anything floating |
| `tooltipBackground` / `tooltipBorder` | tooltips, which sit above everything |
| `primary` (+`Hovered`, `Foreground`) | the accent. The one thing that's on or chosen |
| `secondary` (+`Hovered`, `Foreground`) | a neutral filled control |
| `destructive` | delete, revoke, discard |
| `controlFill` (+`Hovered`, `Focused`), `controlBorder` | the shared fill and stroke of every control — fields, selects, outline buttons, checkboxes |
| `switchTrackInactive` | a Switch while off |
| `border` / `divider` | general outline / a seam between things |
| `panelBorder` / `panelBorderHighlighted` | a Panel's edge, resting / the lit one |
| `propertiesSectionBorder` | a properties section's edge |
| `ring` | keyboard focus |
| `popoverItemHovered` | hover inside select and date popups |
| `chart1`–`chart5` | data visualisation |
There is no `panel`, `input*`, `explorerRow*`, `menuItem*` or `canvas*` slot any
more. App-specific colours (A&A's canvas) belong in the app, derived with
`shiftLstar` so they sit on the same ladder.
## Space
- Between siblings: `Gap.xxs()` … `Gap.xxl()`. They resolve against the
density at build time.
- In padding: `density.gapXs` … `density.gapXxl`, `containerGap`,
`containerPadding`.
- Never a literal. `Gap(8)` is 8 in compact and wrong everywhere else.
| | `xxs` | `xs` | `sm` | `md` | `lg` | `xl` | `xxl` |
|---|---|---|---|---|---|---|---|
| compact | 2 | 4 | 6 | 8 | 12 | 16 | 24 |
| normal, product | 3 | 5 | 8 | 10 | 15 | 20 | 30 |
A lot of the spacing is already in the components. `PropertiesSection` carries
its own margin (`gapXs` either side, `gapLg` below), so a stack of sections
needs no gaps between them. `SettingsList` insets its own rows. Don't add
padding around things that already have it.
## Type
- The ambient text is `fontSize` at w300. Plain `Text("...")` is already right
for body copy.
- Controls render their own labels at w400; primary buttons at w600 as optical
compensation. Don't bold a button label.
- Size steps are the extensions: `.xSmall()` (`textXs`), `.small()` (`textSm`),
`.large()` (`textLg`). Weight: `.medium()`, `.semiBold()`, `.bold()`.
Secondary text: `.muted()`.
- The step below the control font, `textXxs`, has no extension; read
`density.textXxs` when you need it (group captions).
- Numbers and readouts: `theme.typography.monoStyle(...)`.
| Job | How |
|---|---|
| Page title | `Text(title).large()` |
| Page / section subtitle | muted text under it |
| Section heading inside a page | `.small().semiBold()` |
| Nav group caption | `density.textXxs`, w600, `.muted()` |
| Hint, unit, empty-state line | `.muted()` (hub list text: `.xSmall().muted()`) |
| Footer stats, perf readouts | `monoStyle`, muted |
`.muted()` colours **text** only. It does nothing to an `Icon`.
## Icons
- Source: `flutter_lucide`, re-exported through `garage_ui.dart` as
`LucideIcons`. **Names are snake_case** (`LucideIcons.file_plus`,
`LucideIcons.chevron_right`) — this is `flutter_lucide`'s native spelling,
used directly. There is no camelCase shim in this package.
- Three tiers: `.iconSmall` (`density.iconSize`), `.iconMedium` (20px),
`.iconLarge` (24px). Set size via the extension, never a hardcoded `size:`.
- **`Button` and `IconButton` already apply `small` to everything inside
them** — `leading`, `trailing` and the child — so a bare `Icon` in a button
is correctly sized and needs no extension. Reach for one only to *override*
that. Outside a button the ambient default is `medium` (20px), which is
usually too big for a control-adjacent icon; that's where a bare `Icon` does
go wrong.
- `small` is `1.1 × fontSize` — 13px at product, 11px at compact/normal — not
the line box. It was the line box, which is tidy for layout (an icon-only
control matches a text control's height for free) and wrong for the eye:
lucide glyphs fill their box nearly edge to edge while a 12px font caps out
around 8.5px, so a line-box icon read ~70% taller than the text next to it.
Control height is unaffected either way — that comes from `controlHeight`.
- Muted/de-emphasised icon: chain `.muted()` after the size extension —
`Icon(LucideIcons.chevron_left).iconSmall.muted()`.
- Lucide only: `LucideIcons.x`.
- Inside a control's `leading` / `trailing` / `icon` slot: a bare
`const Icon(LucideIcons.x)`. The control sizes and colours it — the variant's
icon theme is merged over everything inside the button.
- Outside a control, `.iconSmall` / `.iconMedium` / `.iconLarge` set size only
(never colour). `iconSmall` equals `fontSize`: 10 compact, 12 product.
- No literal `size: 13`.
## Typography
`theme.typography` exposes `normal` / `medium` (weight-only styles) and
`small` (the shared control font — size and line-height come from `Density`,
never set this by hand). Two font-family helpers:
## Surfaces and layout
- `theme.typography.sansStyle(style)` — Geist, the UI's default face.
- `theme.typography.monoStyle(style)` — Geist Mono. Reach for this
specifically for **numeric readouts**: perf stats, transport time,
coordinates — anywhere the content is a number that benefits from
fixed-width digits. Not for general UI text.
Both apps are the same shape: a `chrome` ground, `Panel`s standing on it, and
`panelGap` gutters between them.
Text-widget shorthands (`Widget` extensions, merge over ambient
`DefaultTextStyle`): `.xSmall()` / `.small()` / `.large()`, `.medium()` /
`.semiBold()` / `.bold()`, `.muted()`.
### The text ladder
The three size shorthands come off `density`, not literals:
| Shorthand | Token | compact / normal | Use it for |
|---|---|---|---|
| `.xSmall()` | `textXs` | 11 | dialog copy, headings, hints — and the ambient body size |
| `.small()` | `textSm` | 14 | body copy a step above the controls |
| `.large()` | `textLg` | 18 | headings |
`textXs` sits one step above `density.fontSize` — 11 against a 10px control
font — and is also what `GarageTheme` sets as the ambient body size, so page
copy and dialog copy are the same size by construction.
It was `x1.2` (12) for a while, which put every dialog title and page heading a
fifth above the controls beneath them. That read as oversized rather than as
hierarchy — weight and colour carry the emphasis, not size.
What was wrong before is that the two were *unlinked*: these were hardcoded
`12`/`14`/`18` multiplied by `scaling`, while the control font comes off
`Density` and is deliberately not scaled. The intended 12-vs-10 held at scaling
1.0 and drifted to 14.4-vs-10 at 1.2 — the ratio moved with scaling. Deriving
them pins it, and makes `density.fontSize` the single knob that moves every
piece of app text together.
`scaling` is deliberately **not** applied to these. It still moves the
medium/large icon tiers, border widths and `GarageTheme`'s own
`DefaultTextStyle` — but text that has to line up with a control cannot be on
a different axis from the control.
## Structural widgets
- **`Panel`** — the bordered, rounded surface for docked tool content. Two
modes: standalone (tracks its own hover) or controlled (`active: bool`,
parent drives it — used when multiple panels need to be mutually exclusive,
e.g. only one lit at a time in a Blender-style three-pane layout). Border
goes from `panelBorder` to `panelBorderHighlighted` when active/hovered.
- **`ChromeBar`** — the shared treatment for a header/footer strip: fixed
height, `chrome` background, padding. Both the header and footer in an
editor should be built from this rather than a raw `Container`, so they
stay pixel-identical in height (`kChromeBarHeight`, shared constant).
- **`EditorShell`** — header / center / optional left+right docks / footer,
stacked as one frame. The outermost layout of a whole editor screen.
- **`GarageShell`** — main content + two stacked sidebar panes with a
draggable resize handle between main and sidebar, plus centralised hover
(only one of the three panes lit at once). This is the Blender-style
three-pane editor shell, factored out so it isn't hand-rolled per app.
- **`ButtonGroup`** — lays controls out in a row (or column) and zeroes the
corners where they touch, so they read as one connected control rather than
two things that happen to be adjacent. A field with a button welded to its
end (password + edit, path + browse, input + unit) is a `ButtonGroup`, not a
`Row` with a `Gap` in it. Nested groups merge rather than shadow — an inner
group can be told to drop both its top and its start edge, which is how a
stacked field/eye/button cluster avoids a doubled stroke down the seam.
Watch `expands`. It defaults to `false`, which wraps the flex in an
`IntrinsicHeight`; the group stretches its children on the cross axis, so
without that wrapper it needs a bounded height from its parent and throws
`BoxConstraints forces an infinite height` when it doesn't get one. Only
pass `expands: true` when the parent already gives it a height.
- **`Card`** vs **`SurfaceCard`** — `Card` always draws its own
`OutlinedContainer` (border + fill). `SurfaceCard` additionally understands
sheet-overlay context: inside a sheet it collapses to just padding, because
the sheet is already the surface and a nested card would double up the
border. Default to `Card` unless the content might end up inside a sheet.
- **`OutlinedContainer`** — the base primitive `Card`/`Panel` build on:
border + radius + optional shadow. Reach for it directly for one-off
floating chrome that isn't quite a card — e.g. a mobile slide-in panel:
```dart
OutlinedContainer(
borderColor: GarageTheme.of(context).colorScheme.border,
boxShadow: [
BoxShadow(color: const Color(0xff000000).withValues(alpha: 0.15), blurRadius: 4, spreadRadius: 2),
],
child: ...,
)
```
A bigger, "floating well above the app" shadow (splash/welcome overlay)
goes heavier and uses negative spread to keep the blur from reading as a
hard edge: `blurRadius: 40, spreadRadius: -8, offset: Offset(0, 20)`, alpha
`0.4`. Scale shadow weight to how far off the page the thing is meant to
read as floating — a docked panel border shadow and a modal-over-everything
shadow should not look like the same intensity.
## Properties — the settings-row system
Any screen that is a list of *things you can change* is built from
`PropertiesSection` + `PropertyRow`. This covers settings panes, inspectors,
and account screens. Do not assemble one out of `Column` + `Text` + a
divider — the split alignment, the collapse behaviour, the actions band and
the row minimum height are all in here already.
- **`PropertiesSection`** — a titled, collapsible block: `title`, `subtitle`,
`rows`, an optional `actions` band along the bottom for section-level
buttons (Save / Reset / Refresh), and `collapsed` + `onToggle` driven by the
parent so several sections can be remembered independently.
- **`PropertyRow`** — one setting. `label` on the left of the split, `child`
(the control) on the right. `split` is the fraction of the width sitting
left of that line, so every row in a section lines its controls up at the
same x. `labelless: true` for a row that has no name of its own.
### `subtitle` vs `description` — the one that gets got wrong
Both are muted second lines. They are not interchangeable, and picking the
wrong one is the single most common mistake against this component:
| | Where it renders | What it's for |
|---|---|---|
| **`subtitle`** | Inside the **label column**, under the label, holding the same right-alignment against the split | *Naming the value.* "Last used 3d ago", "Never used", "2 permissions · last used 5m ago" — text that says **which** row this is |
| **`description`** | **Full width** under the whole row, spanning label *and* control | *Explaining the setting.* Consequences, caveats, what changes when you change it — "Permanently remove this account… This cannot be undone." |
The test: does the sentence identify **this particular item** (subtitle), or
does it explain **what the control does** (description)? A list of five
passkeys wants five subtitles, not five full-width paragraphs.
**Never put explanatory copy in `child`.** It is the single failure mode this
component has. A paragraph in the control column shares a cell with the
control, so the copy wraps to three lines, the button gets squeezed against
the right edge, and the section's split alignment stops meaning anything
because every row's control now starts somewhere different. `child` is for
the control. Copy goes in `description`.
```dart
// WRONG - copy competing with the control for the same column
PropertyRow(
label: "Delete account",
scheme: scheme,
child: Row(children: [
Expanded(child: Text("Permanently remove this account…").muted()),
const Gap.md(),
Button.destructive(onPressed: onDelete, child: const Text("Delete…")),
]),
)
// RIGHT - the slot that already exists for it
PropertyRow(
label: "Delete account",
scheme: scheme,
description: "Permanently remove this account, all sign-in methods, and "
"any OAuth grants. This cannot be undone.",
child: Button.destructive(onPressed: onDelete, child: const Text("Delete…")),
)
```
ColoredBox(chrome)
Padding(panelGap)
Row[ Panel(rail), SizedBox(width: panelGap), Expanded(Panel(workspace)) ]
```
A row that is *only* explanation and has no control at all is still a
`PropertyRow` — give it the `description` and pass `const SizedBox.shrink()`
as the child.
A&A gets this from `GarageShell` (header, footer, main, a sidebar split top and
bottom). The hub builds the same shape by hand because it needs a nav rail.
Only one panel is lit at a time (`panelBorderHighlighted`).
### Fields inside a property row
- **`ChromeBar`** for a header or footer — it's `chromeBarHeight` tall on
`chrome`.
- **`Panel`** for a docked region. Flat, `background` fill, 1.15 border.
- **`PanelHeader(icon, title, scheme, trailing:)`** at the top of a panel body.
A&A's panel pages are all `ColoredBox(surfaceSunken)` →
`PanelHeader(bottomPadding: 0)` → `ScrollEdgeFade(ListView(...))`.
- **`Card` / `SurfaceCard`** for a raised block (`card` fill, `radiusXl`).
- **`OutlinedContainer`** for a bordered box that isn't a card.
- **Flat.** No shadows on anything — the border and the surface step are what
separate things. The package's sheet, menu and popup surfaces are all
shadowless.
`TextField` takes a `variant`: `TextFieldVariant.outline` (default) or
`.secondary`. Inside a properties pane, prefer `.secondary` — it matches the
filled treatment the surrounding controls use, and it pairs with
`ButtonStyle.secondary()` when a button is welded to the field in a
`ButtonGroup`. An `outline` field next to a `secondary` button (or the
reverse) reads as two controls from different screens.
A value the user is not allowed to edit — a password, a verified email — is
still a field: `readOnly: true, enabled: false` with a stand-in value, not a
bare `Text` floating in the column. It keeps the row's geometry and tells the
reader "this is a value that lives here" rather than "this is a caption."
## Buttons
## The menu system — one model, two renderers
### Variants mean something
This is the pattern from the `AppMenuGroup` model in `app_menu.dart`, and
it's worth calling out on its own because it's easy to accidentally
reinvent per-app (it has been, twice):
| Variant | Means |
|---|---|
| `primary` | the one action, or the thing that's on / chosen. One per view, ideally |
| `secondary` | a neutral filled control — a resting toggle, a button welded to a field, the selected item in a nav |
| `outline` | a normal action that isn't the main one — Cancel, Retry, Previous / Next |
| `ghost` | chrome, toolbars, nav items, row actions — anything that shouldn't compete |
| `destructive` | the confirm button of a destructive dialog |
| `ghostDestructive` | a destructive *trigger* that isnt a filled slab — Remove, Revoke, Delete in a row |
| `link` / `text` | inline, in running copy |
Define the menu once as data — `List<AppMenuGroup>` (`AppMenuGroup` →
`AppMenuAction` / `AppMenuCheck` / `AppMenuSeparator`) — not as widgets. Then:
`Button.primary(...)`, `Button.ghostDestructive(...)` etc. take a `style:`;
the `PrimaryButton` / `OutlineButton` / … wrappers take `density:` directly.
1. **In-app render**: walk the model into `Menubar`/`MenuButton`/
`MenuCheckbox`/`MenuDivider` widgets (see `_toMenuItem`/`_menuItemsFor` in
either app's menu code for the translation).
2. **Native macOS bar**: `AppMenuNativeRenderer.build(menus, appName: ...)`
pushed into an `AppMenuNotifier` sitting above the app's `Router`, via
`PlatformMenuHost`.
### By context
Both renderers must consume the **same** computed `menus` value from the
**same** build pass — not two independent calls to whatever builds the model.
Two separate computations drift: they'll watch slightly different state,
recompute at different times, and eventually disagree about what's checked or
what a shortcut is (this exact bug shipped and had to be fixed). Compute
once, hand the value to both. Gate the native push on
`AppMenuNativeRenderer.signature(menus)`, not the list itself — building a
fresh `AppMenuGroup` tree (and fresh `SingleActivator`s inside it) on every
build is normal and fine, but pushing to the native bar on every build is not
— the signature is what turns "recomputed every frame" into "pushed only
when it actually changed."
| Where | What |
|---|---|
| Icon only, anywhere | `IconButton.<variant>`, never a `Button` with just an icon in it |
| Panel header actions | `IconButton.ghost`, each in a `Tooltip` |
| Nav rail item | `ButtonStyle.ghost`, `secondary` when selected (never primary), `alignment: centerLeft`, `leading: Icon` |
| Toolbar / header toggle | `IconButton.primary` when on, `outline` when off (`secondary` off for a master switch whose off state matters) |
| Segmented choice | `ButtonGroup.horizontal`, `Expanded` children, chosen one `primary`, rest `secondary`, `alignment: center` |
| Button welded to a field | `ButtonGroup.horizontal[field, IconButton.secondary]` |
| Action inside a PropertyRow | `ButtonStyle.secondary` (the row doesnt force buttons, you pick it) |
| Action in a SettingsRow | ghost |
| Dialog | Cancel `outline`, confirm `Button.primary` or `Button.destructive` |
| Retry after an error | `outline` |
| Empty-state call to action | `outline`, centred |
| Full-width stacked flow buttons (auth) | primary last, every one `alignment: Alignment.center` |
## Anti-patterns
### Alignment
- **No `package:flutter/material.dart`.** Not even for `Colors.black`. Use
`Color(0xff000000)` / `Color(0xffffffff)` — literal, not `Colors.*`. The UI
kit is deliberately `WidgetsApp`-based, not `MaterialApp`-based, so an app
built on it shouldn't reach for Material either.
- **Don't hand-type a control height, icon size, or vertical padding.** It
belongs in `Density` as a named field with everything else derived from it.
- **Don't build `chrome`/`panel` treatment from raw `Container` + hardcoded
colour.** Use `ChromeBar`/`Panel`/`EditorShell`/`GarageShell` — they read
the right token (and in chrome's case, the right *unaccented* scheme) for
you.
- **Don't hand-roll a settings row.** `PropertiesSection` + `PropertyRow`
exist, and a `Column` of `Text` + control + divider will silently lose the
split alignment, the collapse state and the actions band. If you find
yourself writing `Row(children: [Expanded(Text(...)), Gap, Button])` inside
a settings pane, you want `description:` instead.
- **Don't glue a button to a field with a `Gap`.** That's a `ButtonGroup` —
it merges the touching corners so the pair reads as one control.
- **Don't build a menu as widgets directly.** Model it as `AppMenuGroup` data
first (see above), even if there's currently only one renderer consuming
it — a native menu bar tends to get added later, and retrofitting a model
under existing widget-only menu code is exactly the refactor that
motivated this document.
- **Don't reach for `destructive` for "this matters."** It means
delete/discard/record — genuinely dangerous, genuinely irreversible.
Leave `alignment:` off unless the button is stretched wider than its label.
Then:
- `Alignment.center` for full-width buttons and segments.
- `Alignment.centerLeft` only for nav and list rows, and only with a
**leading** icon.
Never `centerLeft` with a trailing-only icon. When alignment is set and exactly
one of leading / trailing is present, `Button` puts an invisible spacer on the
empty side so the label lands on the true centre — with `centerLeft` that just
indents the label behind a phantom icon.
### Toggles
`Toggle` is the package's on/off button: ghost while off, secondary while on.
Editor toolbars use the primary-on pattern above instead. Pick one per surface.
## Inputs
### Text fields
- **Default (`outline`)** for free text: names, search, a composer, a form.
- **`secondary`** for numeric property values and read-only values.
- Inside a `PropertyRow` you don't choose — the row wraps its child in a
`PropertySlotScope` and `TextField`, `Select` and `DateInput` are forced to
secondary. An explicit `variant:` loses. (Buttons aren't forced.)
- Numeric editor fields (A&A): secondary, `textAlign: center`,
`InputFeature.scrub(...)`, a unit as a trailing muted `Text`. Put trailing
features before `scrub` — list order is render order.
- A read-only value is a `TextField(readOnly: true, enabled: false)`, never a
bare `Text` (see below).
### Select
`SelectVariant.secondary` in property rows (forced anyway), `ghost` in a
`SettingsRow` or where the select reports a value rather than offering a
control, default `outline` elsewhere.
### Booleans
A&A uses `Checkbox` throughout. The hub uses `Switch` in rows. Either is
fine; don't mix them within one surface.
### Errors
Use the row's `error:` slot (`PropertyRow` and `SettingsRow` both have one).
It reddens the outline, never the fill. Don't hand-roll a red `Text` under a
field. "Required" goes in the row's `action:` slot.
## Properties and settings
The two list shapes, and the hub's two page archetypes.
**`PropertiesSection` + `PropertyRow`** — a boxed card of label/value rows. For
inspectors, account and security pages, and lists of records (one collapsible
section per record, then the hub's `Pager`).
- The value slot is **always a field or a control**, never bare `Text`. A
read-only value is a secondary `TextField(readOnly: true, enabled: false)` —
the hub wraps that as `ValueField`. Beside real fields, bare text reads as a
caption and the column goes ragged.
- A button in the value slot goes in `Align(centerLeft)` so it doesn't stretch.
- Controls here are secondary.
- Editor rows carry `PropertyActions` (right-click reset / copy / paste).
- A status badge or count goes in the section's `trailing`, which stays
visible when collapsed.
- Actions go in the section's `actions:` band.
**`SettingsList` + `SettingsRow`** — unboxed rows ruled between entries, on
the page ground. For forms: products, coupons, clients.
- There's no card, so filled controls would float. Selects, buttons and icon
buttons are **ghost**; text fields are the default **outline** — read-only
ones too.
Converting one to the other means changing the variants, not just the
container.
### Subtitle vs description
- `subtitle` is a short **static** line saying what the thing is. Never live
data: no counts, dates, names, emails, statuses or "3 of 5". This holds
everywhere — page headings, section headings, rows, and record cards in a
list. A record's identifying data goes in its rows.
- `description` is longer copy about a setting.
## Dialogs, sheets, panes, overlays
- **Confirm / small dialog:** `showDialog` → `AlertDialog(title, content,
actions: [cancel, confirm])`. It's `card`-filled, capped at
`kDialogMaxWidth` (350) and renders the actions in its own band. Don't
constrain its width yourself, and don't build the action row by hand.
- **Bottom sheet:** `showSheet(...)` with `SheetRow`s.
- **Big pane** (settings, export — A&A): `showPaneOverlay`, blurred scrim,
inside the same chrome → Panel → gutter shape as the editor.
- **Toasts:** `showAppToast(context: context, title: ..., subtitle: ..., severity: ...)`.
- **Tooltips:** `Tooltip(tooltip: (_) => TooltipContainer(child: Text(msg)))`,
unstyled.
- **Menus:** `MenuButton`, `MenuDivider`, `MenuLabel`; `showContextMenu` for
right-click; app menus as `AppMenuItem` data.
## Loading, empty, error
- **Loading:** a `CircularProgressIndicator`. No skeletons, no shimmer.
- **Empty:** one muted line.
- **Error:** the message muted, and an outline Retry.
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.
**Arcs & Angles**
- `IconButton.ghost(icon: Icon(x, size: 13))` in panel headers, the tab strip
and the agent composer — should be a bare `Icon`.
- Tooltip text forced to `foreground` or `background`, custom
`TooltipContainer` padding.
- Literal font sizes in the agent panel and the download modal.
- The hand-rolled snap popover, `PaneDialog` title bar and properties tab
strip.
- Plain `Text` values in settings and download `PropertyRow`s.
- Literal `SizedBox` / `EdgeInsets` spacing outside the settings modal.
**The hub**
- Ghost and link buttons hand-coloured `destructive` ("Remove", "Revoke",
"Refund", "Delete?") — use `ButtonStyle.ghostDestructive`.
- `TextStyle(fontWeight: w600)` on primary labels in the older auth steps.
- Four competing badges (disabled compact buttons, disabled coloured
`IconButton`s, `SandboxTag`, `Pill`), and hand-built warning boxes
(`FlowError`, the delete-account box, `_Banner`).
- `ConstrainedBox(maxWidth: 360/380)` around dialog content.
- Literal widths on toolbar selects.
- Outline text fields and ghost selects inside `PropertiesSection`s;
secondary fields inside `SettingsList`s.
- Record-card and detail-page subtitles carrying data (sku · price, buyer ·
date, counts, emails).
- About 37 hand-written copies of `ValueField`, and a bare `Text` value in two
role rows.
- Hand-built toasts (`showToast` + `SurfaceCard` + literal padding) instead of
`showAppToast`.
- `ControlDensity.compact` on ordinary buttons outside a header.
+2 -2
View File
@@ -15,7 +15,7 @@ dependencies:
git:
url: https://git.imbenji.dev/IMBENJI.NET/Garage-SDKs.git
path: garage_ui
ref: v0.1.0
ref: b2692019197e60d44ddd3ecab4917caf71ff45c3 # v0.1.0
```
Leave that alone. Clone this repo somewhere, then next to the app's
@@ -109,7 +109,7 @@ Once the change works locally:
1. Commit and push it in this repo.
2. Tag a new version, e.g. `v0.1.1`, and push the tag.
3. In each app that should get it, bump `ref:` to the new tag. Do it on purpose,
3. In each app that should get it, bump `ref:` to the new tag's full commit hash. Do it on purpose,
per app — dont float `main`.
4. Check the app builds **without** the override. Move it aside, resolve against
the real tag, and analyze:
+9 -2
View File
@@ -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<void> 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<void> 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<void> signIn() => beginSignIn();
Future<void> 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
+46
View File
@@ -0,0 +1,46 @@
import "package:flutter/widgets.dart";
import "package:flutter_lucide/flutter_lucide.dart";
import "button.dart";
/// One step in a [Breadcrumb].
class BreadcrumbItem {
const BreadcrumbItem({required this.label, this.onPressed});
final String label;
/// null for somewhere you cant go, which is how the last one is drawn
/// whatever you pass - its where you allready are.
final VoidCallback? onPressed;
}
/// Where you are, as a run of ghost buttons with a chevron between them.
///
/// Buttons rather than links, because everything else on a Garage page that
/// takes you somewhere is a button and a row of underlined text would be the
/// only thing on the screen that wasnt.
///
/// It wraps. A path deeper than the pane is wide goes onto a second line
/// instead of scrolling sideways or folding its middle into a menu - you can
/// allways see the whole of where you are.
class Breadcrumb extends StatelessWidget {
const Breadcrumb({super.key, required this.items});
final List<BreadcrumbItem> items;
@override
Widget build(BuildContext context) {
return Wrap(
crossAxisAlignment: WrapCrossAlignment.center,
children: [
for (var i = 0; i < items.length; i++) ...[
if (i > 0) const Icon(LucideIcons.chevron_right),
Button.ghost(
onPressed: i == items.length - 1 ? null : items[i].onPressed,
child: Text(items[i].label),
),
],
],
);
}
}
+137
View File
@@ -186,6 +186,17 @@ class ButtonVariance implements AbstractButtonStyle {
margin: _buttonZeroMargin,
);
// ghost, but for the remove/revoke/delete kind of action that doesnt deserve
// a filled red slab. before this existed every call site hand coloured a
// ghost button's text + icon, which is exactly the override we dont want
static const AbstractButtonStyle ghostDestructive = ButtonVariance(
decoration: _buttonGhostDestructiveDecoration,
mouseCursor: _buttonMouseCursor,
textStyle: _buttonGhostDestructiveTextStyle,
iconTheme: _buttonGhostDestructiveIconTheme,
margin: _buttonZeroMargin,
);
@override
final ButtonStateProperty<Decoration> decoration;
@override
@@ -307,6 +318,14 @@ class ButtonStyle implements AbstractButtonStyle {
this.paddingOverride,
}) : variance = ButtonVariance.destructive;
const ButtonStyle.ghostDestructive({
this.size = ButtonSize.normal,
this.density,
this.shape = ButtonShape.rectangle,
this.squarePadding = false,
this.paddingOverride,
}) : variance = ButtonVariance.ghostDestructive;
// icon flavours — same as above but default to icon density (square padding)
const ButtonStyle.primaryIcon({
this.size = ButtonSize.normal,
@@ -348,6 +367,14 @@ class ButtonStyle implements AbstractButtonStyle {
this.paddingOverride,
}) : variance = ButtonVariance.destructive;
const ButtonStyle.ghostDestructiveIcon({
this.size = ButtonSize.normal,
this.density,
this.shape = ButtonShape.rectangle,
this.squarePadding = true,
this.paddingOverride,
}) : variance = ButtonVariance.ghostDestructive;
@override
ButtonStateProperty<Decoration> get decoration {
if (shape == ButtonShape.circle) {
@@ -923,6 +950,56 @@ IconThemeData _buttonDestructiveIconTheme(
);
}
// GHOST DESTRUCTIVE
/// Ghost with the destructive colour on the label and icon. Same wash as ghost
/// on hover, just tinted with `destructive` instead of the foreground so the
/// highlight agrees with the text.
Decoration _buttonGhostDestructiveDecoration(
BuildContext context,
Set<WidgetState> states,
) {
final themeData = GarageTheme.of(context);
final radius = BorderRadius.circular(themeData.radiusMd);
final tint = themeData.colorScheme.destructive;
if (states.contains(WidgetState.disabled)) {
return BoxDecoration(color: const Color(0x00000000), borderRadius: radius);
}
if (states.contains(WidgetState.pressed)) {
return BoxDecoration(color: tint.withValues(alpha: 0.2), borderRadius: radius);
}
if (states.contains(WidgetState.hovered)) {
return BoxDecoration(color: tint.withValues(alpha: 0.12), borderRadius: radius);
}
return BoxDecoration(color: const Color(0x00000000), borderRadius: radius);
}
TextStyle _buttonGhostDestructiveTextStyle(
BuildContext context,
Set<WidgetState> states,
) {
var themeData = GarageTheme.of(context);
return themeData.typography.small.copyWith(
color: states.contains(WidgetState.disabled)
? themeData.colorScheme.mutedForeground
: themeData.colorScheme.destructive,
);
}
IconThemeData _buttonGhostDestructiveIconTheme(
BuildContext context,
Set<WidgetState> states,
) {
var themeData = GarageTheme.of(context);
return IconThemeData(
color: states.contains(WidgetState.disabled)
? themeData.colorScheme.mutedForeground
: themeData.colorScheme.destructive,
size: themeData.iconTheme.small.size,
);
}
// ---------------------------------------------------------------------------
// button group border merging
// ---------------------------------------------------------------------------
@@ -1327,6 +1404,46 @@ class Button extends StatefulWidget {
this.disableFocusOutline = false,
});
const Button.ghostDestructive({
super.key,
this.statesController,
this.leading,
this.trailing,
this.leadingGap,
this.trailingGap,
required this.child,
this.onPressed,
this.focusNode,
this.alignment,
this.enabled,
this.style = const ButtonStyle.ghostDestructive(),
this.disableTransition = false,
this.onFocus,
this.onHover,
this.disableHoverEffect = false,
this.enableFeedback,
this.onTapDown,
this.onTapUp,
this.onTapCancel,
this.onSecondaryTapDown,
this.onSecondaryTapUp,
this.onSecondaryTapCancel,
this.onTertiaryTapDown,
this.onTertiaryTapUp,
this.onTertiaryTapCancel,
this.onLongPressStart,
this.onLongPressUp,
this.onLongPressMoveUpdate,
this.onLongPressEnd,
this.onSecondaryLongPress,
this.onTertiaryLongPress,
this.semanticLabel,
this.semanticToggled,
this.semanticSelected,
this.marginAlignment,
this.disableFocusOutline = false,
});
@override
State<Button> createState() => _ButtonState();
}
@@ -2185,6 +2302,26 @@ class IconButton extends StatelessWidget {
this.shape = ButtonShape.rectangle,
});
const IconButton.ghostDestructive({
super.key,
required this.icon,
this.onPressed,
this.enabled,
this.leading,
this.trailing,
this.alignment,
this.size = ButtonSize.normal,
this.focusNode,
this.disableTransition = false,
this.onHover,
this.onFocus,
this.enableFeedback,
this.semanticLabel,
this.variance = ButtonVariance.ghostDestructive,
this.density,
this.shape = ButtonShape.rectangle,
});
@override
Widget build(BuildContext context) {
return Button(
+86
View File
@@ -0,0 +1,86 @@
import "package:cross_file/cross_file.dart";
import "package:desktop_drop/desktop_drop.dart" as dd;
import "package:flutter/widgets.dart";
import "theme/garage_theme.dart";
export "package:cross_file/cross_file.dart" show XFile;
/// Somewhere files can be dragged onto from outside the app.
///
/// Flutter has nothing for this, so its desktop_drop underneath - macOS,
/// Windows, Linux and the web. What this adds is the Garage side of it: while
/// something is being held over [child] it gets the focus ring, the same one
/// a focused field gets, because "this is where that will land" is the same
/// statement.
///
/// Folders arent walked. A dropped folder comes through [onDropFolders] as
/// its path and nothing else, so the caller decides whether thats an upload
/// of everything in it or a polite no.
class FileDropTarget extends StatefulWidget {
const FileDropTarget({
super.key,
required this.child,
required this.onDrop,
this.onDropFolders,
this.enabled = true,
});
final Widget child;
final ValueChanged<List<XFile>> onDrop;
final ValueChanged<List<String>>? onDropFolders;
/// Off, and drags pass over it as if it wasnt there.
final bool enabled;
@override
State<FileDropTarget> createState() => _FileDropTargetState();
}
class _FileDropTargetState extends State<FileDropTarget> {
bool _over = false;
void _done(dd.DropDoneDetails details) {
setState(() => _over = false);
final files = <XFile>[];
final folders = <String>[];
for (final item in details.files) {
if (item is dd.DropItemDirectory) {
folders.add(item.path);
} else {
files.add(item);
}
}
if (files.isNotEmpty) widget.onDrop(files);
if (folders.isNotEmpty) widget.onDropFolders?.call(folders);
}
@override
Widget build(BuildContext context) {
final theme = GarageTheme.of(context);
return dd.DropTarget(
enable: widget.enabled,
onDragEntered: (_) => setState(() => _over = true),
onDragExited: (_) => setState(() => _over = false),
onDragDone: _done,
// foreground, so the ring is drawn over the child and takes no room.
// As a border it would shove everything in by its own width the moment
// a drag came in
child: DecoratedBox(
position: DecorationPosition.foreground,
decoration: BoxDecoration(
borderRadius: BorderRadius.circular(theme.radiusSm),
border: _over
? Border.all(
color: theme.colorScheme.ring,
width: theme.density.controlBorderWidth * 2,
)
: null,
),
child: widget.child,
),
);
}
}
+4
View File
@@ -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";
@@ -42,6 +43,9 @@ export "semantics_scope.dart";
export "scroll_edge_fade.dart";
export "scrollbar.dart";
export "settings_list.dart";
export "item_view.dart";
export "breadcrumb.dart";
export "drop_target.dart";
export "field_error.dart";
export "tab_view.dart";
export "sheet.dart";
+590
View File
@@ -0,0 +1,590 @@
import "package:flutter/gestures.dart" show kSecondaryMouseButton;
import "package:flutter/widgets.dart";
import "package:flutter_lucide/flutter_lucide.dart";
import "button.dart";
import "surface.dart" show Divider;
import "theme/garage_theme.dart";
/// How an [ItemView] lays its entries out.
///
/// Four, because theres no one right answer for a list of things with names:
/// its a matter of how many there are, how much the picture of one tells you,
/// and what the person looking is trying to find. So the mode is a value the
/// caller holds, and [ItemViewModeSwitch] is there to let whoevers looking
/// pick it.
enum ItemViewMode {
/// One line each: picture, name, then the cells down the right.
list,
/// Name with the cells as a muted second line under it. The one that still
/// reads on a phone.
twoLine,
/// [list] with a header row, and the headers sort.
table,
/// Tiles. For when the picture is the point.
grid,
}
/// A column of cells in an [ItemView], after the name.
class ItemColumn {
const ItemColumn({
required this.id,
required this.label,
this.ems = 7,
this.sortable = true,
});
/// What [ItemEntry.cells] is keyed on, and what comes back from onSort.
final String id;
final String label;
/// Width, in multiples of the density's font size rather than pixels - so a
/// denser theme gets narrower columns along with its smaller text, instead
/// of the same columns with more air in them.
final double ems;
final bool sortable;
}
/// One thing in an [ItemView].
class ItemEntry {
const ItemEntry({
required this.id,
required this.title,
required this.leading,
this.cells = const {},
this.trailing,
this.onOpen,
this.onContext,
});
final String id;
final String title;
/// The picture: an icon, a thumbnail. Built at whatever size the mode wants
/// it, which is an icon's worth in a row and most of a tile in the grid - so
/// its a builder and not a widget. Fill the square you are given.
final Widget Function(BuildContext context, double extent) leading;
/// column id -> what to show under it. A missing one is an empty cell.
final Map<String, String> cells;
/// Far right of a row, top corner of a tile. An overflow button, usually.
final Widget? trailing;
final VoidCallback? onOpen;
/// Right click, or a long press where theres no right button. Handed the
/// global position so a context menu can open where the pointer is.
final ValueChanged<Offset>? onContext;
}
/// The id [ItemView] reports when the NAME header is pressed. Its not one of
/// the caller's columns, so it needs a name of its own.
const String kItemTitleColumn = "title";
/// A set of named things - files, mostly - in one of four layouts.
///
/// It doesnt sort, page or load. It draws what its given in the order its
/// given, and says when a header was pressed; what that means is the callers
/// business, since only the caller knows whether "size" sorts as a number.
///
/// Not a scroller either. Height comes from the entries and a pane does the
/// scrolling, same as [SettingsList] and a run of sections.
class ItemView extends StatelessWidget {
const ItemView({
super.key,
required this.mode,
required this.entries,
this.columns = const [],
this.titleLabel = "Name",
this.sortColumn,
this.sortAscending = true,
this.onSort,
});
final ItemViewMode mode;
final List<ItemEntry> entries;
final List<ItemColumn> columns;
/// Header over the names, in [ItemViewMode.table].
final String titleLabel;
final String? sortColumn;
final bool sortAscending;
final ValueChanged<String>? onSort;
/// Columns that fit beside a name thats still worth reading.
///
/// They go from the END. The last column is the least important one by
/// convention - a date after a size after a kind - and a row that kept all
/// its columns and squeezed the name down to "inv…" has thrown away the one
/// thing every row is for.
List<ItemColumn> _fitting(double width, double em) {
final nameFloor = em * 14;
var kept = [...columns];
double used() => kept.fold(0.0, (n, c) => n + c.ems * em);
while (kept.isNotEmpty && width - used() < nameFloor) {
kept.removeLast();
}
return kept;
}
@override
Widget build(BuildContext context) {
final theme = GarageTheme.of(context);
final density = theme.density;
if (mode == ItemViewMode.grid) {
return _ItemGrid(entries: entries, columns: columns);
}
return LayoutBuilder(
builder: (context, box) {
final shown = mode == ItemViewMode.twoLine
? const <ItemColumn>[]
: _fitting(box.maxWidth, density.fontSize);
return Column(
crossAxisAlignment: CrossAxisAlignment.stretch,
mainAxisSize: MainAxisSize.min,
children: [
if (mode == ItemViewMode.table) ...[
_HeaderRow(
titleLabel: titleLabel,
columns: shown,
sortColumn: sortColumn,
sortAscending: sortAscending,
onSort: onSort,
hasTrailing: entries.any((e) => e.trailing != null),
),
Divider(color: theme.colorScheme.divider),
],
for (var i = 0; i < entries.length; i++) ...[
// between, not around - see SettingsList, its the same list
if (i > 0) Divider(color: theme.colorScheme.divider),
_ItemRow(
key: ValueKey("item-${entries[i].id}"),
entry: entries[i],
columns: shown,
// every column, whatever fitted: the second line is where the
// ones that didnt fit go
subtitleColumns: mode == ItemViewMode.twoLine ? columns : const [],
),
],
],
);
},
);
}
}
String _joined(ItemEntry entry, List<ItemColumn> columns) => [
for (final c in columns)
if ((entry.cells[c.id] ?? "").isNotEmpty) entry.cells[c.id]!,
].join(" · ");
/// Hover fill, tap to open, right click for the menu. Shared by a row and a
/// tile so the two cant drift into behaving differently.
class _Pressable extends StatefulWidget {
const _Pressable({required this.entry, required this.builder});
final ItemEntry entry;
final Widget Function(BuildContext context, bool hovered) builder;
@override
State<_Pressable> createState() => _PressableState();
}
class _PressableState extends State<_Pressable> {
bool _hover = false;
@override
Widget build(BuildContext context) {
final entry = widget.entry;
final open = entry.onOpen;
final menu = entry.onContext;
return MouseRegion(
cursor: open == null ? MouseCursor.defer : SystemMouseCursors.click,
onEnter: (_) => setState(() => _hover = true),
onExit: (_) => setState(() => _hover = false),
child: Listener(
// a Listener and not onSecondaryTap: the trailing button sits inside
// this, and a gesture detector out here would fight it for the tap
onPointerDown: menu == null
? null
: (e) {
if (e.buttons == kSecondaryMouseButton) menu(e.position);
},
child: GestureDetector(
behavior: HitTestBehavior.opaque,
onTap: open,
onLongPressStart: menu == null ? null : (d) => menu(d.globalPosition),
child: Semantics(
button: open != null,
label: entry.title,
child: widget.builder(context, _hover && open != null),
),
),
),
);
}
}
class _ItemRow extends StatelessWidget {
const _ItemRow({
super.key,
required this.entry,
required this.columns,
required this.subtitleColumns,
});
final ItemEntry entry;
final List<ItemColumn> columns;
final List<ItemColumn> subtitleColumns;
@override
Widget build(BuildContext context) {
final theme = GarageTheme.of(context);
final density = theme.density;
final scheme = theme.colorScheme;
final twoLine = subtitleColumns.isNotEmpty;
final subtitle = twoLine ? _joined(entry, subtitleColumns) : "";
// an icon's worth on one line. two lines have the height for a picture
// you can actualy make out, so it gets the whole label stack
final extent = twoLine ? density.labelColumnHeight : density.iconSize;
return _Pressable(
entry: entry,
builder: (context, hovered) => ColoredBox(
color: hovered ? scheme.rowHovered : const Color(0x00000000),
child: Padding(
padding: EdgeInsets.symmetric(
horizontal: density.listRowIndent,
vertical: twoLine ? density.gapSm : density.explorerRowPaddingY,
),
child: Row(
crossAxisAlignment: CrossAxisAlignment.center,
children: [
SizedBox.square(
dimension: extent,
child: entry.leading(context, extent),
),
SizedBox(width: density.gapSm),
Expanded(
child: Column(
crossAxisAlignment: CrossAxisAlignment.start,
mainAxisSize: MainAxisSize.min,
children: [
Text(
entry.title,
maxLines: 1,
overflow: TextOverflow.ellipsis,
style: TextStyle(color: scheme.foreground),
),
if (subtitle.isNotEmpty) ...[
SizedBox(height: density.gapXxs),
Text(
subtitle,
maxLines: 1,
overflow: TextOverflow.ellipsis,
style: TextStyle(
fontSize: density.textXxs,
color: scheme.mutedForeground,
),
),
],
],
),
),
for (final c in columns)
SizedBox(
width: c.ems * density.fontSize,
child: Text(
entry.cells[c.id] ?? "",
maxLines: 1,
overflow: TextOverflow.ellipsis,
textAlign: TextAlign.end,
style: TextStyle(color: scheme.mutedForeground),
),
),
if (entry.trailing != null) ...[
SizedBox(width: density.gapSm),
entry.trailing!,
],
],
),
),
),
);
}
}
class _HeaderRow extends StatelessWidget {
const _HeaderRow({
required this.titleLabel,
required this.columns,
required this.sortColumn,
required this.sortAscending,
required this.onSort,
required this.hasTrailing,
});
final String titleLabel;
final List<ItemColumn> columns;
final String? sortColumn;
final bool sortAscending;
final ValueChanged<String>? onSort;
final bool hasTrailing;
Widget _label(
BuildContext context,
String id,
String text, {
required bool end,
required bool sortable,
}) {
final theme = GarageTheme.of(context);
final density = theme.density;
final scheme = theme.colorScheme;
final sorted = sortColumn == id;
final press = sortable && onSort != null ? () => onSort!(id) : null;
final style = TextStyle(
fontSize: density.textXxs,
color: sorted ? scheme.foreground : scheme.mutedForeground,
);
return MouseRegion(
cursor: press == null ? MouseCursor.defer : SystemMouseCursors.click,
child: GestureDetector(
behavior: HitTestBehavior.opaque,
onTap: press,
child: Semantics(
button: press != null,
label: sorted
? "$text, sorted ${sortAscending ? "ascending" : "descending"}"
: text,
excludeSemantics: true,
child: Row(
mainAxisAlignment: end ? MainAxisAlignment.end : MainAxisAlignment.start,
children: [
Flexible(
child: Text(text, maxLines: 1, overflow: TextOverflow.ellipsis, style: style),
),
if (sorted) ...[
SizedBox(width: density.gapXxs),
Icon(
sortAscending ? LucideIcons.arrow_up : LucideIcons.arrow_down,
size: density.textXxs,
color: scheme.foreground,
),
],
],
),
),
),
);
}
@override
Widget build(BuildContext context) {
final density = GarageTheme.of(context).density;
return Padding(
padding: EdgeInsets.symmetric(
horizontal: density.listRowIndent,
vertical: density.gapXs,
),
child: Row(
children: [
// over the names, not over the pictures: the header starts where
// the text of a row starts
SizedBox(width: density.iconSize + density.gapSm),
Expanded(
child: _label(context, kItemTitleColumn, titleLabel, end: false, sortable: true),
),
for (final c in columns)
SizedBox(
width: c.ems * density.fontSize,
child: _label(context, c.id, c.label, end: true, sortable: c.sortable),
),
// holds the place of the rows' trailing button, or every column
// sits one button to the right of its header
if (hasTrailing) SizedBox(width: density.gapSm + density.controlHeight),
],
),
);
}
}
class _ItemGrid extends StatelessWidget {
const _ItemGrid({required this.entries, required this.columns});
final List<ItemEntry> entries;
final List<ItemColumn> columns;
@override
Widget build(BuildContext context) {
final theme = GarageTheme.of(context);
final density = theme.density;
final scheme = theme.colorScheme;
final gap = density.gapMd;
return LayoutBuilder(
builder: (context, box) {
// as many as fit at about this wide, then stretched to share the row
// out evenly so theres no ragged strip down the right
final want = density.fontSize * 12;
final across = ((box.maxWidth + gap) / (want + gap)).floor().clamp(1, 12);
final tile = (box.maxWidth - gap * (across - 1)) / across;
return Wrap(
spacing: gap,
runSpacing: gap,
children: [
for (final entry in entries)
SizedBox(
key: ValueKey("item-${entry.id}"),
width: tile,
child: _Pressable(
entry: entry,
builder: (context, hovered) => DecoratedBox(
decoration: BoxDecoration(
color: hovered ? scheme.rowHovered : null,
borderRadius: BorderRadius.circular(theme.radiusSm),
),
child: Padding(
padding: EdgeInsets.all(density.gapXs),
child: Column(
crossAxisAlignment: CrossAxisAlignment.stretch,
mainAxisSize: MainAxisSize.min,
children: [
AspectRatio(
aspectRatio: 4 / 3,
child: DecoratedBox(
decoration: BoxDecoration(
color: scheme.surfaceSunken,
borderRadius: BorderRadius.circular(theme.radiusXs),
border: Border.all(
color: scheme.border,
width: density.controlBorderWidth,
),
),
child: ClipRRect(
borderRadius: BorderRadius.circular(theme.radiusXs),
child: LayoutBuilder(
builder: (context, inner) => Center(
child: SizedBox.square(
dimension: inner.maxHeight,
child: entry.leading(context, inner.maxHeight),
),
),
),
),
),
),
SizedBox(height: density.gapXs),
Row(
crossAxisAlignment: CrossAxisAlignment.center,
children: [
Expanded(
child: Column(
crossAxisAlignment: CrossAxisAlignment.start,
mainAxisSize: MainAxisSize.min,
children: [
Text(
entry.title,
maxLines: 1,
overflow: TextOverflow.ellipsis,
style: TextStyle(color: scheme.foreground),
),
SizedBox(height: density.gapXxs),
Text(
_joined(entry, columns),
maxLines: 1,
overflow: TextOverflow.ellipsis,
style: TextStyle(
fontSize: density.textXxs,
color: scheme.mutedForeground,
),
),
],
),
),
if (entry.trailing != null) entry.trailing!,
],
),
],
),
),
),
),
),
],
);
},
);
}
}
/// The four layouts as a row of buttons, for whoever is looking to pick one.
///
/// The one thats on is primary and the rest secondary, the way a tool thats
/// armed is drawn everywhere else.
class ItemViewModeSwitch extends StatelessWidget {
const ItemViewModeSwitch({
super.key,
required this.mode,
required this.onChanged,
this.modes = ItemViewMode.values,
});
final ItemViewMode mode;
final ValueChanged<ItemViewMode> onChanged;
/// Leave some out where they make no sense - a grid of things with no
/// picture, say.
final List<ItemViewMode> modes;
static IconData _icon(ItemViewMode m) => switch (m) {
ItemViewMode.list => LucideIcons.list,
ItemViewMode.twoLine => LucideIcons.rows_2,
ItemViewMode.table => LucideIcons.table,
ItemViewMode.grid => LucideIcons.layout_grid,
};
static String _name(ItemViewMode m) => switch (m) {
ItemViewMode.list => "List",
ItemViewMode.twoLine => "Detailed list",
ItemViewMode.table => "Table",
ItemViewMode.grid => "Grid",
};
@override
Widget build(BuildContext context) {
return ButtonGroup.horizontal(
children: [
for (final m in modes)
if (m == mode)
IconButton.primary(
icon: Icon(_icon(m)),
semanticLabel: "${_name(m)} view, selected",
onPressed: () => onChanged(m),
)
else
IconButton.secondary(
icon: Icon(_icon(m)),
semanticLabel: "${_name(m)} view",
onPressed: () => onChanged(m),
),
],
);
}
}
+85
View File
@@ -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!,
],
),
);
}
}
+8 -9
View File
@@ -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,
+28 -6
View File
@@ -454,7 +454,18 @@ class _SelectState<T> extends State<Select<T>> {
SizedBox(width: gap),
],
Expanded(
child: Align(alignment: Alignment.center, child: valueChild),
// heightFactor, or this Align eats the whole viewport. An Align with
// no factor on an axis FILLS that axis, and the Row hands its
// children a loose vertical constraint, so the trigger measured 600
// tall in a test and "however tall the pane is" in the app - while
// every button and field beside it sat on controlHeight. The other
// _Btn branch never hit it because its wrapped in an IntrinsicHeight.
// Width still fills, which is the bit we actually wanted.
child: Align(
alignment: Alignment.center,
heightFactor: 1,
child: valueChild,
),
),
if (!widget.iconOnly) ...[
SizedBox(width: gap),
@@ -585,7 +596,9 @@ class SelectPopup<T> extends StatefulWidget {
/// whether the search field is shown (only in builder mode).
final bool enableSearch;
/// whether the list shrink-wraps (static lists do, builder lists scroll).
/// whether the rows are a plain Column (static lists) or a lazy ListView
/// (builder lists, which can be long). Both only take the height they
/// need - see [_listView].
final bool shrinkWrap;
const SelectPopup({
@@ -657,9 +670,9 @@ class _SelectPopupState<T> extends State<SelectPopup<T>> {
// nothing to measure - asking a column how wide it wants to be and then
// ignoring the answer is just a layout pass nobody reads.
//
// [shrinkWrap] still decides the VERTICAL: a static list is a scrolling
// Column that takes only the height it needs, the builder path is a lazy
// ListView.
// [shrinkWrap] picks which list: a static one is a scrolling Column, the
// builder path is a lazy ListView. Either way the popup ends up as tall
// as its rows and no taller.
return _popupSurface(theme, column);
}
@@ -729,10 +742,19 @@ class _SelectPopupState<T> extends State<SelectPopup<T>> {
);
}
// shrinkWrap regardless of [widget.shrinkWrap] - that flag is about which
// list we build, not how tall it ends up. A ListView left to expand eats
// every pixel of popupMaxHeight its handed, so a one-row "Search lines"
// popup opened a 312px wall of empty surface under its single row.
//
// This stays lazy: the incoming maxHeight is bounded (the overlay's
// ConstrainedBox, then Flexible), so the shrink wrapping viewport still
// only lays out as far as that extent and stops. Its the *unbounded* case
// that forces a full layout pass, and we never hand it one.
return ListView.separated(
controller: _scrollController,
padding: EdgeInsets.all(inset),
shrinkWrap: widget.shrinkWrap,
shrinkWrap: true,
itemCount: count,
separatorBuilder: (context, _) => Gap(_popupRowGap(theme)),
itemBuilder: (context, index) =>
+24
View File
@@ -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
+78 -12
View File
@@ -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 "<Family>_<weight>", 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);
+2
View File
@@ -7,6 +7,8 @@ environment:
sdk: ^3.10.0-75.1.beta
dependencies:
cross_file: ^0.3.5+5
desktop_drop: ^0.8.4
flutter:
sdk: flutter
flutter_lucide: ^1.11.0
+134
View File
@@ -0,0 +1,134 @@
import "package:flutter/widgets.dart";
import "package:flutter_test/flutter_test.dart";
import "package:garage_ui/garage_ui.dart";
import "support/test_scheme.dart";
Widget _host(Widget child, {double width = 700}) => Directionality(
textDirection: TextDirection.ltr,
child: GarageTheme(
data: ThemeData(colorScheme: testScheme, density: const Density()),
child: Align(
alignment: Alignment.topLeft,
child: SizedBox(width: width, child: child),
),
),
);
const _columns = [
ItemColumn(id: "size", label: "Size"),
ItemColumn(id: "modified", label: "Modified"),
];
List<ItemEntry> _entries({void Function(String id)? opened}) => [
for (final (id, name, size) in [
("a", "Holiday photos", ""),
("b", "invoice-0412.pdf", "212 KB"),
("c", "clip.mov", "1.4 GB"),
])
ItemEntry(
id: id,
title: name,
leading: (context, extent) => SizedBox.square(dimension: extent),
cells: {"size": size, "modified": "3 Oct"},
onOpen: () => opened?.call(id),
),
];
void main() {
testWidgets("a list is ruled between rows and has no header", (tester) async {
await tester.pumpWidget(
_host(ItemView(mode: ItemViewMode.list, entries: _entries(), columns: _columns)),
);
expect(find.byType(Divider), findsNWidgets(2));
expect(find.text("Size"), findsNothing);
expect(find.text("212 KB"), findsOneWidget);
});
testWidgets("a table has headers, and pressing one says which", (tester) async {
final pressed = <String>[];
await tester.pumpWidget(
_host(
ItemView(
mode: ItemViewMode.table,
entries: _entries(),
columns: _columns,
sortColumn: "size",
onSort: pressed.add,
),
),
);
await tester.tap(find.text("Modified"));
await tester.tap(find.text("Name"));
expect(pressed, ["modified", kItemTitleColumn]);
});
testWidgets("too narrow, and columns go from the end before the name does", (tester) async {
await tester.pumpWidget(
_host(
ItemView(mode: ItemViewMode.table, entries: _entries(), columns: _columns),
width: 260,
),
);
expect(find.text("Modified"), findsNothing);
expect(find.text("Size"), findsOneWidget);
expect(find.text("invoice-0412.pdf"), findsOneWidget);
expect(tester.takeException(), isNull);
});
testWidgets("two lines puts the cells under the name, skipping empty ones", (tester) async {
await tester.pumpWidget(
_host(ItemView(mode: ItemViewMode.twoLine, entries: _entries(), columns: _columns)),
);
expect(find.text("212 KB · 3 Oct"), findsOneWidget);
// the folder has no size, and doesnt get a stray separator for it
expect(find.text("3 Oct"), findsOneWidget);
});
testWidgets("the grid lays tiles out and a tile opens", (tester) async {
final opened = <String>[];
await tester.pumpWidget(
_host(ItemView(mode: ItemViewMode.grid, entries: _entries(opened: opened.add), columns: _columns)),
);
final first = tester.getTopLeft(find.text("Holiday photos"));
final second = tester.getTopLeft(find.text("invoice-0412.pdf"));
expect(first.dy, second.dy, reason: "side by side at this width");
await tester.tap(find.text("clip.mov"));
expect(opened, ["c"]);
expect(tester.takeException(), isNull);
});
testWidgets("the grid survives a phone", (tester) async {
await tester.pumpWidget(
_host(ItemView(mode: ItemViewMode.grid, entries: _entries(), columns: _columns), width: 150),
);
expect(tester.takeException(), isNull);
});
testWidgets("the switch reports the mode that was pressed", (tester) async {
ItemViewMode? got;
await tester.pumpWidget(
_host(ItemViewModeSwitch(mode: ItemViewMode.list, onChanged: (m) => got = m)),
);
await tester.tap(find.bySemanticsLabel("Grid view"));
expect(got, ItemViewMode.grid);
});
testWidgets("the last crumb is where you are, and doesnt go anywhere", (tester) async {
final went = <String>[];
await tester.pumpWidget(
_host(
Breadcrumb(
items: [
BreadcrumbItem(label: "Files", onPressed: () => went.add("files")),
BreadcrumbItem(label: "Work", onPressed: () => went.add("work")),
BreadcrumbItem(label: "Invoices", onPressed: () => went.add("invoices")),
],
),
),
);
await tester.tap(find.text("Work"));
await tester.tap(find.text("Invoices"));
expect(went, ["work"]);
});
}
@@ -0,0 +1,197 @@
// Dumps the real theme values out to design_system/, so the design system
// never has to be typed out by hand (and never drifts from the package).
//
// cd garage_ui && flutter test tool/export_design_tokens_test.dart
//
// its a "test" only because thats the easiest way to get a flutter binding
// without an app. it writes files, it doesnt assert anything interesting.
import "dart:convert";
import "dart:io";
import "package:flutter/widgets.dart";
import "package:flutter_test/flutter_test.dart";
import "package:garage_ui/theme.dart";
String _hex(Color c) {
final argb = c.toARGB32();
final a = (argb >> 24) & 0xff;
final rgb = (argb & 0xffffff).toRadixString(16).padLeft(6, "0");
if (a == 0xff) return "#$rgb";
return "#$rgb${a.toRadixString(16).padLeft(2, "0")}";
}
Map<String, String> _colours(ColourScheme s) => {
"background": _hex(s.background),
"foreground": _hex(s.foreground),
"chrome": _hex(s.chrome),
"surface-sunken": _hex(s.surfaceSunken),
"card": _hex(s.card),
"muted": _hex(s.muted),
"muted-foreground": _hex(s.mutedForeground),
"row-text": _hex(s.rowText),
"row-hovered": _hex(s.rowHovered),
"popover": _hex(s.popover),
"popover-border": _hex(s.popoverBorder),
"popover-item-hovered": _hex(s.popoverItemHovered),
"tooltip-background": _hex(s.tooltipBackground),
"tooltip-border": _hex(s.tooltipBorder),
"primary": _hex(s.primary),
"primary-hovered": _hex(s.primaryHovered),
"primary-foreground": _hex(s.primaryForeground),
"secondary": _hex(s.secondary),
"secondary-hovered": _hex(s.secondaryHovered),
"secondary-foreground": _hex(s.secondaryForeground),
"destructive": _hex(s.destructive),
"control-fill": _hex(s.controlFill),
"control-fill-hovered": _hex(s.controlFillHovered),
"control-fill-focused": _hex(s.controlFillFocused),
"control-border": _hex(s.controlBorder),
"switch-track-inactive": _hex(s.switchTrackInactive),
"border": _hex(s.border),
"divider": _hex(s.divider),
"panel-border": _hex(s.panelBorder),
"panel-border-highlighted": _hex(s.panelBorderHighlighted),
"properties-section-border": _hex(s.propertiesSectionBorder),
"ring": _hex(s.ring),
"chart-1": _hex(s.chart1),
"chart-2": _hex(s.chart2),
"chart-3": _hex(s.chart3),
"chart-4": _hex(s.chart4),
"chart-5": _hex(s.chart5),
};
Map<String, num> _density(Density d) {
final t = ThemeData(colorScheme: GarageSchemes.carbon, density: d);
return {
"font-size": d.fontSize,
"line-height": d.lineHeight,
"line-box": d.lineBox,
"control-height": d.controlHeight,
"control-padding-x": d.buttonPaddingX,
"control-padding-y": d.controlPaddingY,
"control-gap": d.controlGap,
"control-border-width": d.controlBorderWidth,
"menu-row-height": d.menuRowHeight,
"popup-row-height": d.popupRowHeight,
"explorer-row-height": d.explorerRowHeight,
"chrome-bar-height": d.chromeBarHeight,
"property-row-height": d.propertyRowHeight,
// the label + subtitle stack a SettingsRow is sized off
"label-column-height": d.labelColumnHeight,
"properties-section-gap": d.propertiesSectionGap,
"explorer-row-base-padding": d.explorerRowBasePadding,
"explorer-row-end-padding": d.explorerRowEndPadding,
"list-row-indent": d.listRowIndent,
"container-gap": d.containerGap,
"container-padding": d.containerPadding,
"gap-xxs": d.gapXxs,
"gap-xs": d.gapXs,
"gap-sm": d.gapSm,
"gap-md": d.gapMd,
"gap-lg": d.gapLg,
"gap-xl": d.gapXl,
"gap-xxl": d.gapXxl,
"text-xxs": d.textXxs,
"text-xs": d.textXs,
"text-sm": d.textSm,
"text-lg": d.textLg,
"icon-sm": t.iconTheme.small.size ?? d.iconSize,
"icon-md": t.iconTheme.medium.size ?? 20,
"icon-lg": t.iconTheme.large.size ?? 24,
};
}
String _num(num n) => n == n.roundToDouble() ? n.round().toString() : n.toString();
void main() {
test("export design tokens", () {
final out = Directory("../design_system");
out.createSync(recursive: true);
final t = ThemeData(colorScheme: GarageSchemes.carbon);
final schemes = {
"carbon": _colours(GarageSchemes.carbon),
"dark": _colours(GarageSchemes.dark),
"light": _colours(GarageSchemes.light),
};
final densities = {
"compact": _density(const Density.compact()),
"normal": _density(const Density.normal()),
"product": _density(const Density.product()),
};
final shape = {
"radius-xs": t.radiusXs,
"radius-sm": t.radiusSm,
"radius-md": t.radiusMd,
"radius-lg": t.radiusLg,
"radius-xl": t.radiusXl,
"radius-xxl": t.radiusXxl,
"panel-radius": t.panelRadius,
"panel-gap": t.panelGap,
"panel-border-width": 1.15,
"property-split": 0.4,
"property-label-gap": 10,
"dialog-max-width": 350,
};
File("${out.path}/tokens.json").writeAsStringSync(
const JsonEncoder.withIndent(" ").convert({
"_generated": "by garage_ui/tool/export_design_tokens_test.dart - dont edit by hand",
"fonts": {"sans": "Geist", "mono": "Geist Mono"},
"weights": {"body": 300, "control": 400, "medium": 500, "semibold": 600},
"schemes": schemes,
"densities": densities,
"shape": shape,
}),
);
final css = StringBuffer()
..writeln("/* garage_ui design tokens. Generated by garage_ui/tool/export_design_tokens_test.dart")
..writeln(" - dont edit by hand, rerun the export.")
..writeln(" Scheme: data-scheme=\"carbon\" (default) | \"dark\" | \"light\"")
..writeln(" Density: data-density=\"product\" (default) | \"normal\" | \"compact\" */")
..writeln()
..writeln("@import url(\"https://fonts.googleapis.com/css2?family=Geist:wght@300;400;500;600;700&family=Geist+Mono:wght@400;500&display=swap\");")
..writeln();
void block(String selector, Map<String, String> vars) {
css.writeln("$selector {");
vars.forEach((k, v) => css.writeln(" --$k: $v;"));
css.writeln("}");
css.writeln();
}
block(":root", {
"font-sans": "\"Geist\", system-ui, sans-serif",
"font-mono": "\"Geist Mono\", ui-monospace, monospace",
"weight-body": "300",
"weight-control": "400",
"weight-medium": "500",
"weight-semibold": "600",
for (final e in shape.entries)
e.key: (e.key == "property-split") ? _num(e.value) : "${_num(e.value)}px",
});
schemes.forEach((name, vars) {
final sel = name == "carbon" ? ":root, [data-scheme=\"carbon\"]" : "[data-scheme=\"$name\"]";
block(sel, vars);
});
// the default block has to come FIRST. `:root` and `[data-density=x]` are
// the same specificity, so whichever is later wins - with product last,
// <html data-density="compact"> quietly rendered product
final densityOrder = ["product", "compact", "normal"];
for (final name in densityOrder) {
final vars = densities[name]!;
final sel = name == "product" ? ":root, [data-density=\"product\"]" : "[data-density=\"$name\"]";
block(sel, {
for (final e in vars.entries)
e.key: e.key == "line-height" ? _num(e.value) : "${_num(e.value)}px",
});
}
File("${out.path}/tokens.css").writeAsStringSync(css.toString());
});
}
+21
View File
@@ -0,0 +1,21 @@
MIT License
Copyright (c) 2026 IMBENJI.NET LTD
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.
+6
View File
@@ -0,0 +1,6 @@
include: package:flutter_lints/flutter.yaml
linter:
rules:
# the SDK prints caught errors to console on purpose for debugging
avoid_print: false
+9
View File
@@ -0,0 +1,9 @@
*.iml
.gradle
/local.properties
/.idea/workspace.xml
/.idea/libraries
.DS_Store
/build
/captures
.cxx
+58
View File
@@ -0,0 +1,58 @@
group = "net.imbenji.garage_updates"
version = "1.0-SNAPSHOT"
buildscript {
val kotlinVersion = "2.3.20"
repositories {
google()
mavenCentral()
}
dependencies {
classpath("com.android.tools.build:gradle:9.0.1")
classpath("org.jetbrains.kotlin:kotlin-gradle-plugin:$kotlinVersion")
}
}
allprojects {
repositories {
google()
mavenCentral()
}
}
plugins {
id("com.android.library")
}
android {
namespace = "net.imbenji.garage_updates"
compileSdk = 36
compileOptions {
sourceCompatibility = JavaVersion.VERSION_17
targetCompatibility = JavaVersion.VERSION_17
}
sourceSets {
getByName("main") {
java.srcDirs("src/main/kotlin")
}
}
defaultConfig {
minSdk = 24
}
}
kotlin {
compilerOptions {
jvmTarget = org.jetbrains.kotlin.gradle.dsl.JvmTarget.JVM_17
}
}
dependencies {
// FileProvider, the only way to hand the installer a file since android 7
implementation("androidx.core:core:1.13.1")
}
@@ -0,0 +1 @@
rootProject.name = "garage_updates"
@@ -0,0 +1,19 @@
<manifest xmlns:android="http://schemas.android.com/apk/res/android">
<!-- without this the system installer refuses an apk that came from us -->
<uses-permission android:name="android.permission.REQUEST_INSTALL_PACKAGES" />
<application>
<!-- our own subclass + authority, so it cant collide with a file
provider the app (or another plugin) allready declares -->
<provider
android:name="net.imbenji.garage_updates.GarageUpdatesFileProvider"
android:authorities="${applicationId}.garage_updates.files"
android:exported="false"
android:grantUriPermissions="true">
<meta-data
android:name="android.support.FILE_PROVIDER_PATHS"
android:resource="@xml/garage_updates_paths" />
</provider>
</application>
</manifest>
@@ -0,0 +1,6 @@
package net.imbenji.garage_updates
import androidx.core.content.FileProvider
// nothing in it. it exists so the manifest entry has a class name of its own
class GarageUpdatesFileProvider : FileProvider()
@@ -0,0 +1,106 @@
package net.imbenji.garage_updates
import android.content.Context
import android.content.Intent
import android.os.Build
import android.util.Log
import androidx.core.content.FileProvider
import io.flutter.embedding.engine.plugins.FlutterPlugin
import io.flutter.plugin.common.MethodCall
import io.flutter.plugin.common.MethodChannel
import io.flutter.plugin.common.MethodChannel.MethodCallHandler
import io.flutter.plugin.common.MethodChannel.Result
import java.io.File
// The android half of garage_updates. Two things dart cant do for itself:
// find out who installed the app, and hand an apk to the system installer.
// The installer always asks the person, theres no silent path and we dont
// want one.
class GarageUpdatesPlugin : FlutterPlugin, MethodCallHandler {
private lateinit var channel: MethodChannel
private lateinit var context: Context
override fun onAttachedToEngine(binding: FlutterPlugin.FlutterPluginBinding) {
context = binding.applicationContext
channel = MethodChannel(binding.binaryMessenger, "net.imbenji.garage_updates")
channel.setMethodCallHandler(this)
}
override fun onDetachedFromEngine(binding: FlutterPlugin.FlutterPluginBinding) {
channel.setMethodCallHandler(null)
}
override fun onMethodCall(call: MethodCall, result: Result) {
when (call.method) {
"info" -> result.success(
mapOf(
"installer" to installerPackageName(),
"cacheDir" to context.cacheDir.absolutePath,
)
)
"installerPackageName" -> result.success(installerPackageName())
"install" -> {
val path = call.argument<String>("path")
if (path == null) {
result.error("bad_args", "install needs a path", null)
return
}
install(File(path), result)
}
else -> result.notImplemented()
}
}
// "com.android.vending" for a play store install, null for a sideload
private fun installerPackageName(): String? {
val pm = context.packageManager
return try {
if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.R) {
pm.getInstallSourceInfo(context.packageName).installingPackageName
} else {
@Suppress("DEPRECATION")
pm.getInstallerPackageName(context.packageName)
}
} catch (e: Exception) {
Log.e(TAG, "couldnt read the installer package name", e)
null
}
}
private fun install(apk: File, result: Result) {
if (!apk.exists()) {
result.error("missing", "No apk at ${apk.path}", null)
return
}
try {
val uri = FileProvider.getUriForFile(
context,
"${context.packageName}.garage_updates.files",
apk,
)
val intent = Intent(Intent.ACTION_VIEW).apply {
setDataAndType(uri, "application/vnd.android.package-archive")
// the installer is another app, it needs lending the file
addFlags(Intent.FLAG_GRANT_READ_URI_PERMISSION)
// we only have the application context, not an activity
addFlags(Intent.FLAG_ACTIVITY_NEW_TASK)
}
context.startActivity(intent)
result.success(null)
} catch (e: Exception) {
// an apk outside the shared cache folder lands here too
Log.e(TAG, "couldnt open the installer for ${apk.path}", e)
result.error("install_failed", e.message ?: "The installer could not be opened", null)
}
}
companion object {
private const val TAG = "garage_updates"
}
}
@@ -0,0 +1,5 @@
<?xml version="1.0" encoding="utf-8"?>
<!-- only the staging folder in the cache is ever shared, and only with the installer -->
<paths>
<cache-path name="garage_updates" path="garage_updates/" />
</paths>
+117
View File
@@ -0,0 +1,117 @@
import "package:flutter/widgets.dart";
import "package:garage_ui/garage_ui.dart";
import "package:garage_updates/garage_updates.dart";
import "package:go_router/go_router.dart";
// The whole integration is the one call at the top of main. Everything under
// it is just an app with a "restart to update" button, which is the only
// other thing an app has to do for itself.
//
// Run it with `flutter run` and the updater prints that this copy isnt an
// install and stays out of the way - it only ever touches a release build
// that the installer (or a previous update) put in place.
Future<void> main(List<String> args) async {
// an app with helpers of its own (an agent, a tray) stops them here
GarageUpdater.instance.onBeforeRestart = () async {
print("about to restart into the new build");
};
await GarageUpdater.launch(
args: args,
project: "proj_example",
build: 12, // the number after the + in pubspec's version
label: "v2610-1",
branding: const UpdaterBranding(
name: "Example App",
logo: Icon(LucideIcons.package),
),
mode: UpdateMode.prompt,
);
runApp(const ExampleApp());
}
final _theme = ThemeData(
colorScheme: GarageSchemes.carbon,
density: const Density.product(),
);
final _router = GoRouter(
routes: [
GoRoute(path: "/", builder: (context, state) => const HomePage()),
],
);
class ExampleApp extends StatelessWidget {
const ExampleApp({super.key});
@override
Widget build(BuildContext context) {
return GarageApp.router(routerConfig: _router, theme: _theme, title: "Example App");
}
}
class HomePage extends StatefulWidget {
const HomePage({super.key});
@override
State<HomePage> createState() => _HomePageState();
}
class _HomePageState extends State<HomePage> {
String? _error;
Future<void> _restart() async {
try {
await GarageUpdater.instance.restartToUpdate();
} on UpdateError catch (e) {
// a UAC prompt turned down, say. the update is still waiting
print("couldnt restart into the update: $e");
if (mounted) setState(() => _error = e.message);
}
}
@override
Widget build(BuildContext context) {
final updater = GarageUpdater.instance;
return Scaffold(
child: Center(
child: ValueListenableBuilder<UpdateInfo?>(
valueListenable: updater.ready,
builder: (context, waiting, _) {
final latest = waiting?.latest;
return Column(
mainAxisSize: MainAxisSize.min,
children: [
Text("Example App ${updater.label}").large().semiBold(),
const Gap.sm(),
if (latest == null)
const Text("Up to date").muted()
else ...[
Text("${latest.label} is ready to install").muted(),
const Gap.sm(),
// the notes are the apps to show, the splash never does
if (latest.notes.isNotEmpty) Text(latest.notes).muted(),
const Gap.lg(),
Button(
style: const ButtonStyle.primary(),
onPressed: _restart,
child: const Text("Restart to update"),
),
],
if (_error != null) ...[
const Gap.md(),
Text(_error!).muted(),
],
],
);
},
),
),
);
}
}
+24
View File
@@ -0,0 +1,24 @@
name: garage_updates_example
description: "Minimal example of an app that updates itself with garage_updates."
publish_to: 'none'
version: 0.1.0+12
environment:
sdk: ^3.10.0
flutter: ">=3.5.0"
dependencies:
flutter:
sdk: flutter
garage_ui:
path: ../../garage_ui
garage_updates:
path: ../
go_router: ^14.6.2
dev_dependencies:
flutter_lints: ^6.0.0
flutter:
+20
View File
@@ -0,0 +1,20 @@
// The updater without flutter: ask Garage for the newest release, download it
// with resume, check the sha256, install it and restart.
//
// A headless dart program (an agent, a cli) imports this one. A flutter app
// wants package:garage_updates/garage_updates.dart instead, which is this
// plus the splash.
//
// final engine = UpdateEngine.detect(project: "<project id>", build: 12);
// final info = await engine.check();
// if (info.hasUpdate) {
// await engine.download(info.latest!);
// await engine.install(info.latest!);
// await engine.restart(args: args);
// }
//
// android isnt in here, installing an apk needs a platform channel.
library;
export "src/core/models.dart";
export "src/core/io.dart" if (dart.library.js_interop) "src/core/web.dart";
+25
View File
@@ -0,0 +1,25 @@
// Auto updates for a flutter app, akin to Discord's. One call at the top of
// main and the rest happens on its own:
//
// Future<void> main(List<String> args) async {
// await GarageUpdater.launch(
// args: args,
// project: "<project id>",
// build: 12,
// label: "v2610-1",
// branding: UpdaterBranding(name: "Garage Stash", logo: "assets/logo.png"),
// );
// runApp(const MyApp());
// }
//
// While the app runs, GarageUpdater.instance.ready says when a newer build has
// been downloaded, and restartToUpdate() moves over to it.
//
// On the web every call is a no-op.
library;
export "src/core/models.dart"
show UpdateInfo, UpdateRelease, UpdateAsset, UpdateStatus, UpdateError, UpdateDriver, DownloadProgress;
export "src/branding.dart" show UpdaterBranding, UpdateMode;
export "src/splash.dart" show UpdateSplash, UpdateSplashApp, SplashController, SplashStage;
export "src/updater.dart" show GarageUpdater;
+39
View File
@@ -0,0 +1,39 @@
import "package:flutter/widgets.dart";
import "package:garage_ui/garage_ui.dart";
/// What happens to an update the app could carry on without.
enum UpdateMode {
/// found at launch = downloaded and installed there and then, behind the
/// splash. The app starts allready up to date
silent,
/// never installed from the splash. Its fetched in the background and
/// `GarageUpdater.instance.ready` tells the app, which asks the person
prompt,
}
/// Whose splash it is.
class UpdaterBranding {
const UpdaterBranding({required this.name, this.logo, this.theme})
: assert(
logo == null || logo is Widget || logo is String || logo is ImageProvider,
"logo is an asset path, an ImageProvider or a Widget",
);
/// the developers name for the app, shown under the logo
final String name;
/// an asset path ("assets/logo.png"), an [ImageProvider], or any widget
final Object? logo;
/// the splash wears carbon at the product tier unless told otherwise
final ThemeData? theme;
Widget? buildLogo() {
final l = logo;
if (l is Widget) return l;
if (l is String) return Image.asset(l);
if (l is ImageProvider) return Image(image: l);
return null;
}
}
+138
View File
@@ -0,0 +1,138 @@
import "dart:async";
import "dart:convert";
import "dart:ffi" show Abi;
import "dart:io";
import "models.dart";
const kDefaultApiBase = "https://pay.imbenji.net/api";
/// Asks Garage what the newest release is. No sign in, one GET.
class UpdateClient {
UpdateClient({
required this.project,
String apiBase = kDefaultApiBase,
HttpClient? httpClient,
this.timeout = const Duration(seconds: 20),
}) : apiBase = apiBase.endsWith("/") ? apiBase.substring(0, apiBase.length - 1) : apiBase,
_http = httpClient ?? HttpClient();
final String project;
final String apiBase;
final Duration timeout;
final HttpClient _http;
Uri checkUri({required String platform, required String arch, required int build}) {
return Uri.parse("$apiBase/v1/updates/${Uri.encodeComponent(project)}").replace(
queryParameters: {"platform": platform, "arch": arch, "build": "$build"},
);
}
/// `GET /v1/updates/:pid`. Throws [UpdateError] when the server cant be
/// reached or says no, a 200 with an odd body comes back as unknown.
Future<UpdateInfo> check({
required String platform,
required String arch,
required int build,
}) async {
final uri = checkUri(platform: platform, arch: arch, build: build);
final HttpClientResponse res;
final String body;
try {
final req = await _http.getUrl(uri).timeout(timeout);
req.headers.set(HttpHeaders.acceptHeader, "application/json");
res = await req.close().timeout(timeout);
body = await res.transform(utf8.decoder).join().timeout(timeout);
} on TimeoutException catch (e) {
print("[garage_updates] the update check timed out: $e");
throw UpdateError("timeout", "The update check timed out");
} catch (e, st) {
print("[garage_updates] the update check didnt get through: $e\n$st");
throw UpdateError("network", "Couldn't reach the update server");
}
if (res.statusCode != 200) {
// the store api's errors are {"error": code, "message": ...}
var code = "http_${res.statusCode}";
var message = "The update server answered ${res.statusCode}";
try {
final j = jsonDecode(body);
if (j is Map) {
if (j["error"] is String) code = j["error"] as String;
if (j["message"] is String) message = j["message"] as String;
}
} catch (e) {
print("[garage_updates] update check ${res.statusCode} with a body that isnt json: $e");
}
throw UpdateError(code, message);
}
Object? json;
try {
json = jsonDecode(body);
} catch (e) {
print("[garage_updates] the update check answered something that isnt json: $e");
return const UpdateInfo(status: UpdateStatus.unknown);
}
final info = UpdateInfo.fromJson(json);
final latest = info.latest;
if (latest == null) return info;
// hosted assets come back absolute, but dont fall over on a relative one
final resolved = _resolve(latest.asset.url);
if (resolved == latest.asset.url) return info;
return UpdateInfo(
status: info.status,
minimumBuild: info.minimumBuild,
latest: UpdateRelease(
label: latest.label,
build: latest.build,
notes: latest.notes,
publishedAt: latest.publishedAt,
asset: UpdateAsset(
url: resolved,
filename: latest.asset.filename,
format: latest.asset.format,
size: latest.asset.size,
sha256: latest.asset.sha256,
),
),
);
}
String _resolve(String url) {
final u = Uri.tryParse(url);
if (u == null || u.hasScheme) return url;
return Uri.parse("$apiBase/").resolve(url.startsWith("/") ? url.substring(1) : url).toString();
}
void close() => _http.close(force: true);
}
/// "windows" | "macos" | "android", or null where theres nothing to update
String? currentUpdatePlatform() {
if (Platform.isWindows) return "windows";
if (Platform.isMacOS) return "macos";
if (Platform.isAndroid) return "android";
return null;
}
/// The arch to ask for. The server falls back to `universal` by itself, so
/// this only has to be honest about the machine.
String currentUpdateArch() {
final abi = Abi.current();
if (abi == Abi.windowsX64 || abi == Abi.macosX64 || abi == Abi.androidX64 || abi == Abi.linuxX64) {
return "x64";
}
if (abi == Abi.windowsArm64 ||
abi == Abi.macosArm64 ||
abi == Abi.androidArm64 ||
abi == Abi.linuxArm64) {
return "arm64";
}
// 32 bit android and the like. only a universal asset can suit it
return "universal";
}
+276
View File
@@ -0,0 +1,276 @@
import "dart:async";
import "dart:convert";
import "dart:io";
import "package:crypto/crypto.dart";
import "models.dart";
// Fetches one release asset into the staging folder.
//
// The bytes land in `update.part`, with a little json beside it saying which
// build + sha they belong to. A cut connection leaves both where they are and
// the next go asks for `Range: bytes=N-`. Only once the whole file hashes to
// what Garage recorded does it get its real name.
const _partName = "update.part";
const _metaName = "update.part.json";
class Downloader {
Downloader({
HttpClient? httpClient,
this.quietTimeout = const Duration(seconds: 30),
this.retries = 3,
this.retryPause = const Duration(seconds: 2),
}) : _http = httpClient ?? HttpClient();
final HttpClient _http;
/// how long the line may say nothing before we call it dead
final Duration quietTimeout;
/// extra goes after the first, each one resuming
final int retries;
final Duration retryPause;
static File partFile(Directory staging) => File(_join(staging.path, _partName));
static File metaFile(Directory staging) => File(_join(staging.path, _metaName));
/// where a finished, verified download of [release] sits
static File finishedFile(Directory staging, UpdateRelease release) {
final ext = release.asset.format.isEmpty ? "bin" : release.asset.format;
return File(_join(staging.path, "update-${release.build}.$ext"));
}
Future<File> fetch({
required UpdateRelease release,
required Directory staging,
DownloadProgress? onProgress,
}) async {
final asset = release.asset;
if (asset.sha256.isEmpty) {
// never install something we cant check
throw UpdateError("no_checksum", "The release has no checksum to verify against");
}
await staging.create(recursive: true);
final done = finishedFile(staging, release);
final part = partFile(staging);
final meta = metaFile(staging);
if (await done.exists()) {
if (await sha256Of(done) == asset.sha256) {
onProgress?.call(await done.length(), await done.length());
return done;
}
print("[garage_updates] ${done.path} doesnt match its checksum any more, fetching it again");
await _remove(done);
}
await _sweep(staging, keep: done);
if (!await _partIsOurs(meta, release)) {
if (await part.exists()) {
print("[garage_updates] throwing away a stale part file, it was for another build");
}
await _remove(part);
await _writeMeta(meta, release);
}
var attempt = 0;
while (true) {
try {
await _pull(asset, part, onProgress);
break;
} on UpdateError catch (e) {
if (!_worthRetrying(e) || attempt >= retries) rethrow;
print("[garage_updates] download stopped (${e.message}), going again");
} catch (e, st) {
// a cut connection, a quiet line. the part file stays for the resume
print("[garage_updates] download stopped: $e\n$st");
if (attempt >= retries) {
throw UpdateError("download", "The download kept failing: $e");
}
}
attempt++;
await Future<void>.delayed(retryPause);
}
final got = await sha256Of(part);
if (got != asset.sha256) {
print("[garage_updates] checksum mismatch, wanted ${asset.sha256} got $got");
await _remove(part);
await _remove(meta);
throw UpdateError("checksum_mismatch", "The download didn't match its checksum");
}
await part.rename(done.path);
await _remove(meta);
return done;
}
bool _worthRetrying(UpdateError e) => e.code == "restart" || e.code == "server";
Future<void> _pull(UpdateAsset asset, File part, DownloadProgress? onProgress) async {
var have = await part.exists() ? await part.length() : 0;
if (asset.size > 0 && have > asset.size) {
print("[garage_updates] the part file is bigger than the release, starting over");
await _remove(part);
have = 0;
}
// all there allready, only the checksum left to do
if (asset.size > 0 && have == asset.size) {
onProgress?.call(have, asset.size);
return;
}
final res = await _open(Uri.parse(asset.url), have);
var append = false;
if (res.statusCode == HttpStatus.partialContent) {
final start = _rangeStart(res.headers.value(HttpHeaders.contentRangeHeader));
if (start == have) {
append = true;
} else if (start == 0) {
have = 0;
} else {
await _drain(res);
await _remove(part);
throw UpdateError("restart", "The server resumed from the wrong place");
}
} else if (res.statusCode == HttpStatus.ok) {
// it ignored the range and sent the lot. fine, start the file again
if (have > 0) print("[garage_updates] the server ignored the range, downloading from the top");
have = 0;
} else if (res.statusCode == HttpStatus.requestedRangeNotSatisfiable) {
await _drain(res);
await _remove(part);
throw UpdateError("restart", "The server wouldn't resume the download");
} else {
await _drain(res);
if (res.statusCode >= 500) {
throw UpdateError("server", "The download server answered ${res.statusCode}");
}
throw UpdateError("http_${res.statusCode}", "The download was refused (${res.statusCode})");
}
int? total;
if (res.contentLength >= 0) {
total = have + res.contentLength;
} else if (asset.size > 0) {
total = asset.size;
}
final out = await part.open(mode: append ? FileMode.writeOnlyAppend : FileMode.writeOnly);
var received = have;
try {
onProgress?.call(received, total);
await for (final chunk in res.timeout(quietTimeout)) {
await out.writeFrom(chunk);
received += chunk.length;
onProgress?.call(received, total);
}
} finally {
await out.close();
}
if (total != null && received < total) {
throw HttpException("the download ended early, $received of $total bytes");
}
}
// Walks the redirects by hand. A hosted download is a 302 to a presigned url
// that only lives a few minutes, so a resume has to start from the original
// link every time - which is why nothing here remembers where it ended up.
Future<HttpClientResponse> _open(Uri uri, int have) async {
for (var hop = 0; hop < 6; hop++) {
final req = await _http.getUrl(uri).timeout(quietTimeout);
req.followRedirects = false;
// dart asks for gzip by itself and unpacks it, which makes a nonsense
// of byte ranges
req.headers.removeAll(HttpHeaders.acceptEncodingHeader);
if (have > 0) req.headers.set(HttpHeaders.rangeHeader, "bytes=$have-");
final res = await req.close().timeout(quietTimeout);
final location = res.headers.value(HttpHeaders.locationHeader);
if (res.isRedirect || (_redirects.contains(res.statusCode) && location != null)) {
await _drain(res);
if (location == null) {
throw UpdateError("redirect", "The download redirected to nowhere");
}
uri = uri.resolve(location);
continue;
}
return res;
}
throw UpdateError("redirect", "The download redirected too many times");
}
static const _redirects = {301, 302, 303, 307, 308};
int? _rangeStart(String? contentRange) {
// "bytes 100-999/1000"
if (contentRange == null) return null;
final m = RegExp(r"bytes\s+(\d+)-").firstMatch(contentRange);
return m == null ? null : int.tryParse(m.group(1)!);
}
Future<void> _drain(HttpClientResponse res) async {
try {
await res.drain<void>().timeout(quietTimeout);
} catch (e) {
print("[garage_updates] couldnt drain a response we didnt want: $e");
}
}
Future<bool> _partIsOurs(File meta, UpdateRelease release) async {
if (!await meta.exists()) return false;
try {
final j = jsonDecode(await meta.readAsString());
return j is Map && j["build"] == release.build && j["sha256"] == release.asset.sha256;
} catch (e) {
print("[garage_updates] unreadable part note, treating the part as stale: $e");
return false;
}
}
Future<void> _writeMeta(File meta, UpdateRelease release) async {
await meta.writeAsString(
jsonEncode({"build": release.build, "sha256": release.asset.sha256}),
flush: true,
);
}
// finished downloads of other builds, nobody is going to install those now
Future<void> _sweep(Directory staging, {required File keep}) async {
try {
await for (final e in staging.list()) {
if (e is! File || e.path == keep.path) continue;
final name = e.uri.pathSegments.last;
if (name.startsWith("update-")) await _remove(e);
}
} catch (e) {
print("[garage_updates] couldnt tidy the staging folder: $e");
}
}
void close() => _http.close(force: true);
}
/// sha256 of a file as lower case hex, read as a stream so a big download
/// never sits in memory
Future<String> sha256Of(File f) async {
final digest = await sha256.bind(f.openRead()).first;
return digest.toString();
}
Future<void> _remove(File f) async {
try {
if (await f.exists()) await f.delete();
} catch (e) {
print("[garage_updates] couldnt delete ${f.path}: $e");
}
}
String _join(String a, String b) => a.endsWith(Platform.pathSeparator) ? "$a$b" : "$a${Platform.pathSeparator}$b";
+184
View File
@@ -0,0 +1,184 @@
import "dart:async";
import "dart:io";
import "client.dart";
import "downloader.dart";
import "installer.dart";
import "models.dart";
/// The whole updater with no flutter in it: check, download, install,
/// restart. The splash drives one of these, and so can a headless program.
///
/// final engine = UpdateEngine.detect(project: "...", build: 12);
/// final info = await engine.check();
/// if (info.hasUpdate) {
/// await engine.download(info.latest!);
/// await engine.install(info.latest!);
/// await engine.restart(args: args);
/// }
class UpdateEngine implements UpdateDriver {
UpdateEngine({
required this.project,
required this.build,
String apiBase = kDefaultApiBase,
Installer? installer,
String? notInstalledReason,
UpdateClient? client,
Downloader? downloader,
String? arch,
void Function(int code)? exitProcess,
}) : _installer = installer,
notInstalledReason = installer != null ? null : (notInstalledReason ?? "no installer"),
client = client ?? UpdateClient(project: project, apiBase: apiBase),
downloader = downloader ?? Downloader(),
arch = arch ?? currentUpdateArch(),
_exit = exitProcess ?? exit;
/// Looks at where this process is running from and builds the engine for
/// it. Somewhere the updater didnt put it = an engine that does nothing.
factory UpdateEngine.detect({
required String project,
required int build,
String apiBase = kDefaultApiBase,
}) {
final found = detectInstall();
return UpdateEngine(
project: project,
build: build,
apiBase: apiBase,
installer: found.installer,
notInstalledReason: found.reason,
);
}
final String project;
/// the build this process is
final int build;
final String arch;
final UpdateClient client;
final Downloader downloader;
final Installer? _installer;
final void Function(int code) _exit;
@override
final String? notInstalledReason;
@override
FutureOr<void> Function()? onBeforeRestart;
@override
bool get installed => _installer != null;
Installer? get installer => _installer;
bool _saidNotInstalled = false;
final Set<int> _saidBlocked = {};
/// Says once why this copy wont be updated. Returns [installed].
bool reportIfNotInstalled() {
if (installed) return true;
if (!_saidNotInstalled) {
_saidNotInstalled = true;
print("[garage_updates] not updating this copy: $notInstalledReason");
}
return false;
}
@override
Future<bool> noteStart() async {
final inst = _installer;
if (inst == null) return false;
return inst.noteStart(build);
}
@override
Future<UpdateInfo> check() async {
final inst = _installer;
if (inst == null) {
reportIfNotInstalled();
return const UpdateInfo(status: UpdateStatus.unknown);
}
final info = await client.check(platform: inst.platform, arch: arch, build: build);
final latest = info.latest;
if (latest == null) return info;
if (latest.build <= build) {
// the server only offers newer ones, but never go backwards on its say so
return UpdateInfo(status: UpdateStatus.current, minimumBuild: info.minimumBuild);
}
if (inst.blockedBuilds().contains(latest.build)) {
if (_saidBlocked.add(latest.build)) {
print("[garage_updates] build ${latest.build} failed to start on this machine before, not taking it again");
}
// still required if it was, theres just nothing here that can be installed
return UpdateInfo(
status: info.isRequired ? UpdateStatus.required : UpdateStatus.current,
minimumBuild: info.minimumBuild,
);
}
return info;
}
@override
Future<void> download(UpdateRelease release, {DownloadProgress? onProgress}) async {
final inst = _need();
await downloader.fetch(release: release, staging: inst.staging, onProgress: onProgress);
}
/// true when [release] is allready downloaded and verified
Future<bool> isDownloaded(UpdateRelease release) async {
final inst = _installer;
if (inst == null) return false;
return Downloader.finishedFile(inst.staging, release).exists();
}
@override
Future<void> install(UpdateRelease release) async {
final inst = _need();
final file = Downloader.finishedFile(inst.staging, release);
if (!await file.exists()) {
throw UpdateError("not_downloaded", "Build ${release.build} hasn't been downloaded");
}
await inst.apply(file, release, runningBuild: build);
}
@override
Future<void> restart({List<String> args = const []}) async {
final inst = _need();
final before = onBeforeRestart;
if (before != null) {
try {
await before();
} catch (e, st) {
// the apps own tidy up going wrong shouldnt strand it on the old build
print("[garage_updates] onBeforeRestart threw, restarting anyway: $e\n$st");
}
}
await inst.relaunch(args);
if (inst.exitsOnRestart) _exit(0);
}
@override
Future<void> markHealthy() async {
await _installer?.markHealthy();
}
Installer _need() {
final inst = _installer;
if (inst == null) {
throw UpdateError("not_installed", "This copy of the app can't be updated: $notInstalledReason");
}
return inst;
}
void close() {
client.close();
downloader.close();
}
}
@@ -0,0 +1,99 @@
import "dart:io";
import "mac_installer.dart";
import "models.dart";
import "windows_installer.dart";
/// The part that differs per platform: where downloads go, how a verified
/// archive becomes the installed app, and how the app is started again.
abstract class Installer {
/// "windows" | "macos" | "android", what the check is asked for
String get platform;
/// where the `.part` file and the finished download live
Directory get staging;
/// builds that failed to start here and must not be offered again
List<int> blockedBuilds();
/// Turns the verified [archive] into the installed app. Does not restart.
Future<void> apply(File archive, UpdateRelease release, {required int runningBuild});
/// Starts the app again. The caller ends this process afterwards when
/// [exitsOnRestart] says so.
Future<void> relaunch(List<String> args);
/// false on android, where the system installer does the restarting
bool get exitsOnRestart;
/// Counts a start of [build]. true = the previous build was just put back
/// because this one kept dying, relaunch.
Future<bool> noteStart(int build);
Future<void> markHealthy();
}
typedef ProcessRunner = Future<ProcessResult> Function(String exe, List<String> args);
typedef ProcessStarter = Future<void> Function(String exe, List<String> args);
Future<ProcessResult> defaultRunner(String exe, List<String> args) => Process.run(exe, args);
Future<void> defaultStarter(String exe, List<String> args) async {
// detached, it has to outlive us
await Process.start(exe, args, mode: ProcessStartMode.detached);
}
/// What [detectInstall] found. Exactly one of the two is set.
class InstallDetection {
const InstallDetection.found(Installer this.installer) : reason = null;
const InstallDetection.none(String this.reason) : installer = null;
final Installer? installer;
/// why this copy of the app isnt one we can update
final String? reason;
}
/// Works out whether this process is running from somewhere the updater put
/// it. A dev build, `flutter run`, `dart run`, a folder that isnt
/// `app-<build>`, a translocated or read only mac bundle: all "none", and the
/// updater then leaves the app completly alone.
InstallDetection detectInstall({
String? executable,
Map<String, String>? environment,
String? platform,
bool? product,
}) {
// debug + profile builds and anything run off the jit. a release build is
// the only thing that should ever get swapped
product ??= const bool.fromEnvironment("dart.vm.product");
if (!product) return const InstallDetection.none("this isn't a release build");
final exe = executable ?? Platform.resolvedExecutable;
final env = environment ?? Platform.environment;
switch (platform ?? Platform.operatingSystem) {
case "windows":
return WindowsInstaller.locate(exe, environment: env);
case "macos":
return MacInstaller.locate(exe, environment: env);
default:
return InstallDetection.none("no installer for ${platform ?? Platform.operatingSystem} here");
}
}
/// last bit of a path, whichever way the slashes lean
String baseName(String path) {
var p = path;
while (p.length > 1 && (p.endsWith("/") || p.endsWith("\\"))) {
p = p.substring(0, p.length - 1);
}
final cut = p.lastIndexOf(RegExp(r"[/\\]"));
return cut < 0 ? p : p.substring(cut + 1);
}
String joinPath(String a, String b, [String? c]) {
final sep = Platform.pathSeparator;
final ab = a.endsWith(sep) ? "$a$b" : "$a$sep$b";
return c == null ? ab : "$ab$sep$c";
}
+12
View File
@@ -0,0 +1,12 @@
// everything in core that needs dart:io. see core.dart
export "client.dart";
export "downloader.dart";
export "engine.dart";
export "installer.dart";
export "mac_installer.dart";
export "state.dart";
export "windows_installer.dart";
/// false on the web, where theres nothing to update
const bool kUpdatesSupported = true;
@@ -0,0 +1,343 @@
import "dart:convert";
import "dart:io";
import "installer.dart";
import "models.dart";
import "state.dart";
// macOS. No stub here, the bundle is swapped where it stands:
//
// unpack the zip with ditto, move the running .app out to
// ~/Library/Application Support/<bundle id>/garage_updates/previous.app,
// move the new one into its place, `open -n` it.
//
// A running app carries on fine after its bundle is moved, the files are
// still open. The fallback the windows stub does (3 starts that never get to
// markHealthy = go back) is done in here too, by noteStart().
const _maxFailedStarts = 3;
class MacInstaller implements Installer {
MacInstaller({
required this.bundle,
required this.bundleId,
required this.support,
ProcessRunner? run,
}) : _run = run ?? defaultRunner;
/// the .app we are running out of
final Directory bundle;
final String bundleId;
/// `~/Library/Application Support/<bundle id>/garage_updates`
final Directory support;
final ProcessRunner _run;
late final StateFile state = StateFile(File(joinPath(support.path, "state.json")));
Directory get previousApp => Directory(joinPath(support.path, "previous.app"));
static InstallDetection locate(String executable, {Map<String, String>? environment}) {
final env = environment ?? Platform.environment;
final bundle = _bundleOf(executable);
if (bundle == null) {
return InstallDetection.none("${baseName(executable)} isn't running from an app bundle");
}
final path = bundle.path;
if (path.contains("/AppTranslocation/")) {
// gatekeeper runs a quarantined app from a random read only mount untill
// its been moved by hand. nothing to swap there
return const InstallDetection.none("the app is translocated, move it to Applications first");
}
if (path.contains("/Build/Products/") || path.contains("/DerivedData/")) {
return const InstallDetection.none("the app is running out of a build folder");
}
if (!_writable(bundle.parent.path) || !_writable(path)) {
return InstallDetection.none("$path can't be replaced by this user");
}
final id = readBundleId(bundle);
if (id == null) {
return const InstallDetection.none("the bundle has no CFBundleIdentifier");
}
final home = env["HOME"];
if (home == null || home.isEmpty) {
return const InstallDetection.none("no HOME to keep the update state in");
}
return InstallDetection.found(MacInstaller(
bundle: bundle,
bundleId: id,
support: Directory("$home/Library/Application Support/$id/garage_updates"),
));
}
// the OUTERMOST .app in the path. a helper in Contents/MacOS, or in a login
// item bundle nested inside, still belongs to the app around it
static Directory? _bundleOf(String executable) {
final parts = executable.split("/");
for (var i = 0; i < parts.length - 1; i++) {
if (parts[i].endsWith(".app") && parts[i].length > 4) {
return Directory(parts.sublist(0, i + 1).join("/"));
}
}
return null;
}
static bool _writable(String path) {
try {
return Process.runSync("/bin/test", ["-w", path]).exitCode == 0;
} catch (e) {
print("[garage_updates] couldnt check whether $path is writable: $e");
return false;
}
}
@override
String get platform => "macos";
@override
bool get exitsOnRestart => true;
@override
Directory get staging => Directory(joinPath(support.path, "staging"));
@override
List<int> blockedBuilds() => state.read()?.blocked ?? const [];
@override
Future<void> apply(File archive, UpdateRelease release, {required int runningBuild}) async {
final unpack = Directory(joinPath(support.path, "unpack"));
await _wipe(unpack);
await unpack.create(recursive: true);
try {
switch (release.asset.format) {
case "zip":
await _must("/usr/bin/ditto", ["-x", "-k", archive.path, unpack.path], "unpack the update");
case "dmg":
await _fromDmg(archive, unpack);
default:
throw UpdateError("format", "A mac release has to be a zip or a dmg, not ${release.asset.format}");
}
final fresh = _findApp(unpack);
if (fresh == null) {
throw UpdateError("no_app", "There's no .app inside the update");
}
// dont let a mislabelled asset replace us with some other app
final freshId = readBundleId(fresh);
if (freshId != null && freshId != bundleId) {
throw UpdateError("wrong_app", "The update is for $freshId, this is $bundleId");
}
await _swap(fresh);
} finally {
await _wipe(unpack);
}
state.update((s) {
// what we are running is the truth, whatever the file last thought
s.previous = runningBuild;
s.current = release.build;
s.failedStarts = 0;
}, createIfMissing: true);
try {
if (archive.existsSync()) archive.deleteSync();
} catch (e) {
print("[garage_updates] couldnt remove ${archive.path} after installing it: $e");
}
}
Future<void> _swap(Directory fresh) async {
await _wipe(previousApp);
await support.create(recursive: true);
await _move(bundle.path, previousApp.path);
try {
await _move(fresh.path, bundle.path);
} catch (e, st) {
print("[garage_updates] couldnt move the new bundle in, putting the old one back: $e\n$st");
await _move(previousApp.path, bundle.path);
rethrow;
}
}
Future<void> _fromDmg(File dmg, Directory unpack) async {
final mount = Directory(joinPath(support.path, "mount"));
await _wipe(mount);
await mount.create(recursive: true);
await _must(
"/usr/bin/hdiutil",
["attach", "-nobrowse", "-readonly", "-noautoopen", "-mountpoint", mount.path, dmg.path],
"open the disk image",
);
try {
final app = _findApp(mount);
if (app == null) throw UpdateError("no_app", "There's no .app inside the disk image");
await _must(
"/usr/bin/ditto",
[app.path, joinPath(unpack.path, baseName(app.path))],
"copy the app off the disk image",
);
} finally {
final res = await _run("/usr/bin/hdiutil", ["detach", mount.path, "-force"]);
if (res.exitCode != 0) {
print("[garage_updates] couldnt detach ${mount.path}: ${res.stderr}");
}
await _wipe(mount);
}
}
// top level, or one folder down (a zip of a folder holding the app)
Directory? _findApp(Directory dir) {
final found = <Directory>[];
void look(Directory d, int depth) {
for (final e in d.listSync(followLinks: false)) {
if (e is! Directory) continue;
final name = baseName(e.path);
if (name == "__MACOSX") continue;
if (name.endsWith(".app")) {
found.add(e);
} else if (depth == 0) {
look(e, 1);
}
}
}
look(dir, 0);
if (found.isEmpty) return null;
final ours = baseName(bundle.path);
for (final f in found) {
if (baseName(f.path) == ours) return f;
}
return found.first;
}
@override
Future<void> relaunch(List<String> args) async {
await _must(
"/usr/bin/open",
["-n", bundle.path, if (args.isNotEmpty) ...["--args", ...args]],
"start the app again",
);
}
@override
Future<bool> noteStart(int build) async {
final s = state.read() ?? UpdateState();
if (s.current != build) {
// a build this file has never seen start. put there by hand, most likely
if (!previousApp.existsSync()) s.previous = null;
s.current = build;
s.failedStarts = 0;
}
if (s.failedStarts >= _maxFailedStarts && s.previous != null && previousApp.existsSync()) {
print("[garage_updates] build $build failed to start ${s.failedStarts} times, going back to ${s.previous}");
try {
await _swapBack();
} catch (e, st) {
print("[garage_updates] couldnt put the previous build back: $e\n$st");
return false;
}
if (!s.blocked.contains(build)) s.blocked.add(build);
s.current = s.previous;
s.previous = null;
s.failedStarts = 0;
state.write(s);
return true;
}
s.failedStarts++;
state.write(s);
return false;
}
Future<void> _swapBack() async {
final failed = Directory(joinPath(support.path, "failed.app"));
await _wipe(failed);
await _move(bundle.path, failed.path);
try {
await _move(previousApp.path, bundle.path);
} catch (e) {
print("[garage_updates] the previous bundle wouldnt move back, restoring: $e");
await _move(failed.path, bundle.path);
rethrow;
}
await _wipe(failed);
}
@override
Future<void> markHealthy() async {
final s = state.read();
if (s != null && s.failedStarts == 0) return;
state.update((s) => s.failedStarts = 0, createIfMissing: true);
}
Future<void> _move(String from, String to) async {
try {
await Directory(from).rename(to);
return;
} on FileSystemException catch (e) {
// another volume, rename cant cross those. mv copies when it has to
print("[garage_updates] rename $from -> $to failed (${e.osError?.message}), trying mv");
}
await _must("/bin/mv", [from, to], "move ${baseName(from)}");
}
Future<void> _must(String exe, List<String> args, String what) async {
final res = await _run(exe, args);
if (res.exitCode != 0) {
print("[garage_updates] ${baseName(exe)} ${args.join(" ")} exited ${res.exitCode}\n${res.stdout}\n${res.stderr}");
throw UpdateError("install_failed", "Couldn't $what");
}
}
Future<void> _wipe(Directory d) async {
try {
if (await d.exists()) await d.delete(recursive: true);
} catch (e) {
print("[garage_updates] couldnt remove ${d.path}: $e");
}
}
}
/// CFBundleIdentifier out of a bundles Info.plist, null when there isnt one
String? readBundleId(Directory app) {
final plist = File("${app.path}/Contents/Info.plist");
if (!plist.existsSync()) return null;
try {
final text = utf8.decode(plist.readAsBytesSync(), allowMalformed: true);
if (!text.startsWith("bplist")) {
final m = RegExp(r"<key>\s*CFBundleIdentifier\s*</key>\s*<string>([^<]+)</string>").firstMatch(text);
if (m != null) return m.group(1)!.trim();
}
// a binary plist, or xml laid out some way the regex didnt expect
final res = Process.runSync(
"/usr/libexec/PlistBuddy",
["-c", "Print :CFBundleIdentifier", plist.path],
);
if (res.exitCode == 0) {
final id = (res.stdout as String).trim();
if (id.isNotEmpty) return id;
}
} catch (e) {
print("[garage_updates] couldnt read ${plist.path}: $e");
}
return null;
}
+208
View File
@@ -0,0 +1,208 @@
import "dart:async";
// The shapes the update check hands back, and the one interface the flutter
// half drives. Nothing in here touches dart:io, so it compiles for the web
// where the whole package is a no-op.
enum UpdateStatus {
/// nothing newer for this platform
current,
/// theres a newer build, the app may carry on without it
available,
/// this build is below the projects minimum. the app must not start
required,
/// the server couldnt tell (no build sent), or we couldnt read its answer
unknown,
}
class UpdateAsset {
const UpdateAsset({
required this.url,
required this.filename,
required this.format,
required this.size,
required this.sha256,
});
final String url;
final String filename;
/// "zip" | "dmg" | "apk"
final String format;
final int size;
final String sha256;
static UpdateAsset? fromJson(Object? raw) {
if (raw is! Map) return null;
final url = _str(raw["url"]);
if (url == null || url.isEmpty) return null;
final filename = _str(raw["filename"]) ?? "";
var format = (_str(raw["format"]) ?? "").toLowerCase();
if (format.isEmpty) {
// older answers might not carry it, the filename says the same thing
final dot = filename.lastIndexOf(".");
if (dot >= 0) format = filename.substring(dot + 1).toLowerCase();
}
return UpdateAsset(
url: url,
filename: filename,
format: format,
size: _int(raw["size"]) ?? 0,
sha256: (_str(raw["sha256"]) ?? "").toLowerCase(),
);
}
Map<String, dynamic> toJson() => {
"url": url,
"filename": filename,
"format": format,
"size": size,
"sha256": sha256,
};
}
class UpdateRelease {
const UpdateRelease({
required this.label,
required this.build,
required this.asset,
this.notes = "",
this.publishedAt,
});
final String label;
final int build;
final String notes;
final DateTime? publishedAt;
final UpdateAsset asset;
static UpdateRelease? fromJson(Object? raw) {
if (raw is! Map) return null;
final build = _int(raw["build"]);
final asset = UpdateAsset.fromJson(raw["asset"]);
// a release we cant order or cant download is no use to anyone
if (build == null || asset == null) return null;
final published = _str(raw["published_at"]);
return UpdateRelease(
label: _str(raw["label"]) ?? "",
build: build,
notes: _str(raw["notes"]) ?? "",
publishedAt: published == null ? null : DateTime.tryParse(published),
asset: asset,
);
}
Map<String, dynamic> toJson() => {
"label": label,
"build": build,
"notes": notes,
"published_at": publishedAt?.toUtc().toIso8601String(),
"asset": asset.toJson(),
};
}
class UpdateInfo {
const UpdateInfo({required this.status, this.minimumBuild, this.latest});
final UpdateStatus status;
final int? minimumBuild;
final UpdateRelease? latest;
/// true when theres something to download
bool get hasUpdate =>
latest != null && (status == UpdateStatus.available || status == UpdateStatus.required);
bool get isRequired => status == UpdateStatus.required;
/// Reads the body of `GET /v1/updates/:pid`. Never throws on a strange
/// shape, it just comes back as unknown.
factory UpdateInfo.fromJson(Object? raw) {
if (raw is! Map) return const UpdateInfo(status: UpdateStatus.unknown);
final latest = UpdateRelease.fromJson(raw["latest"]);
var status = switch (_str(raw["status"])) {
"current" => UpdateStatus.current,
"available" => UpdateStatus.available,
"required" => UpdateStatus.required,
_ => UpdateStatus.unknown,
};
// says theres an update but didnt send one we can use
if (latest == null && (status == UpdateStatus.available || status == UpdateStatus.required)) {
print("[garage_updates] the check said ${status.name} but sent no usable release");
status = UpdateStatus.unknown;
}
return UpdateInfo(
status: status,
minimumBuild: _int(raw["minimum_build"]),
latest: latest,
);
}
UpdateInfo withStatus(UpdateStatus s) =>
UpdateInfo(status: s, minimumBuild: minimumBuild, latest: latest);
}
/// Anything the updater gives up on. `code` is stable, `message` is for a log.
class UpdateError implements Exception {
UpdateError(this.code, this.message);
final String code;
final String message;
@override
String toString() => "UpdateError($code): $message";
}
/// bytes so far, and the total when we know it
typedef DownloadProgress = void Function(int received, int? total);
/// What the splash and the background check drive. The real one is
/// `UpdateEngine` in core, the web gets none at all.
abstract class UpdateDriver {
/// false for a dev build, `flutter run`, a translocated mac bundle and so
/// on. When its false nothing else here does anything
bool get installed;
/// why not, for the one line that gets printed
String? get notInstalledReason;
/// Run right before the app is restarted into the new build, so an app can
/// stop its own helper processes first.
FutureOr<void> Function()? onBeforeRestart;
/// Counts this start. Comes back true when the last update kept failing to
/// start and the old build was put back - the caller should [restart].
Future<bool> noteStart();
Future<UpdateInfo> check();
/// Downloads + verifies. Safe to call again, it picks up where it stopped.
Future<void> download(UpdateRelease release, {DownloadProgress? onProgress});
/// Installs what [download] fetched. Does not restart.
Future<void> install(UpdateRelease release);
/// Starts the app again and ends this process. On android the system
/// installer does the restarting, so this returns.
Future<void> restart({List<String> args = const []});
Future<void> markHealthy();
}
String? _str(Object? v) => v is String ? v : null;
int? _int(Object? v) {
if (v is int) return v;
if (v is double && v.isFinite) return v.toInt();
if (v is String) return int.tryParse(v.trim());
return null;
}
+228
View File
@@ -0,0 +1,228 @@
import "dart:convert";
import "dart:io";
// `garage_updates.json` on windows (shared with the stub) and `state.json` on
// the mac. Same fields on both.
class UpdateState {
UpdateState({
this.exe,
this.current,
this.previous,
this.failedStarts = 0,
List<int>? blocked,
Map<String, dynamic>? extra,
}) : blocked = blocked ?? [],
extra = extra ?? {};
/// the real exe inside a version folder. windows only
String? exe;
int? current;
int? previous;
/// starts of `current` that never reached markHealthy
int failedStarts;
/// builds that failed 3 starts on this machine, never offered here again
List<int> blocked;
/// keys we dont know about. the stub may write more than we read, and
/// writing the file back must not lose them
Map<String, dynamic> extra;
factory UpdateState.fromJson(Map<dynamic, dynamic> j) {
final known = {"exe", "current", "previous", "failed_starts", "blocked"};
final blocked = <int>[];
final raw = j["blocked"];
if (raw is List) {
for (final b in raw) {
final n = _int(b);
if (n != null && !blocked.contains(n)) blocked.add(n);
}
}
return UpdateState(
exe: j["exe"] is String ? j["exe"] as String : null,
current: _int(j["current"]),
previous: _int(j["previous"]),
failedStarts: _int(j["failed_starts"]) ?? 0,
blocked: blocked,
extra: {
for (final e in j.entries)
if (e.key is String && !known.contains(e.key)) e.key as String: e.value,
},
);
}
Map<String, dynamic> toJson() => {
...extra,
if (exe != null) "exe": exe,
"current": current,
"previous": previous,
"failed_starts": failedStarts,
"blocked": blocked,
};
}
class StateFile {
StateFile(this.file);
final File file;
/// null when its missing, half written or not ours. Says which on the
/// console, never throws.
UpdateState? read() {
final j = _readObject(file);
return j == null ? null : UpdateState.fromJson(j);
}
/// Write to a temp file beside it, then rename over the top, so a reader
/// never sees half a file.
bool write(UpdateState state) => _writeObject(file, state.toJson());
/// Read, change, write. Without [createIfMissing] it does nothing when the
/// file cant be read, rather than writing an empty state over whatever the
/// stub had in there. The mac owns its file so it passes true, a damaged
/// one just gets started again.
bool update(void Function(UpdateState s) change, {bool createIfMissing = false}) {
var state = read();
if (state == null) {
if (!createIfMissing) return false;
state = UpdateState();
}
change(state);
return write(state);
}
}
/// What one person on the machine knows about the install, for when the
/// install itself is somewhere they cant write (Program Files). The stub
/// keeps it in `%LOCALAPPDATA%\<app id>\garage_updates.json` and it only
/// ever exists for an install like that.
class UserState {
UserState({
this.failedStarts = 0,
List<int>? blocked,
this.forCurrent,
this.runInstead,
}) : blocked = blocked ?? [];
int failedStarts;
/// builds that failed 3 starts for this user
List<int> blocked;
/// the `current` of the install the count was made against
int? forCurrent;
/// the build the stub starts for this user instead of `current`
int? runInstead;
factory UserState.fromJson(Map<dynamic, dynamic> j) {
final blocked = <int>[];
final raw = j["blocked"];
if (raw is List) {
for (final b in raw) {
final n = _int(b);
if (n != null && !blocked.contains(n)) blocked.add(n);
}
}
final count = _int(j["failed_starts"]) ?? 0;
return UserState(
failedStarts: count < 0 ? 0 : count,
blocked: blocked,
forCurrent: _int(j["for_current"]),
runInstead: _int(j["run_instead"]),
);
}
Map<String, dynamic> toJson() => {
"failed_starts": failedStarts,
"blocked": blocked,
"for_current": forCurrent,
"run_instead": runInstead,
};
/// The count and the build to run instead only mean anything for the
/// `current` they were made against. Once an update has gone in they start
/// again, what got blocked stays blocked. Same rule as the stub.
void settleFor(int? current) {
if (forCurrent == current) return;
forCurrent = current;
failedStarts = 0;
runInstead = null;
}
}
class UserStateFile {
UserStateFile(this.file);
final File file;
UserState? read() {
final j = _readObject(file);
return j == null ? null : UserState.fromJson(j);
}
bool write(UserState state) => _writeObject(file, state.toJson());
/// Same deal as [StateFile.update]. The app never passes
/// [createIfMissing], starting this file is the stubs job.
bool update(void Function(UserState s) change, {bool createIfMissing = false}) {
var state = read();
if (state == null) {
if (!createIfMissing) return false;
state = UserState();
}
change(state);
return write(state);
}
}
Map<dynamic, dynamic>? _readObject(File file) {
try {
if (!file.existsSync()) return null;
final text = file.readAsStringSync();
if (text.trim().isEmpty) {
print("[garage_updates] ${file.path} is empty");
return null;
}
final j = jsonDecode(text);
if (j is! Map) {
print("[garage_updates] ${file.path} isnt an object");
return null;
}
return j;
} catch (e) {
// most likely caught mid write by the other side
print("[garage_updates] couldnt read ${file.path}: $e");
return null;
}
}
bool _writeObject(File file, Map<String, dynamic> json) {
final tmp = File("${file.path}.tmp");
try {
file.parent.createSync(recursive: true);
tmp.writeAsStringSync(const JsonEncoder.withIndent(" ").convert(json), flush: true);
tmp.renameSync(file.path);
return true;
} catch (e, st) {
print("[garage_updates] couldnt write ${file.path}: $e\n$st");
try {
if (tmp.existsSync()) tmp.deleteSync();
} catch (e2) {
print("[garage_updates] and couldnt clear up ${tmp.path}: $e2");
}
return false;
}
}
int? _int(Object? v) {
if (v is int) return v;
if (v is double && v.isFinite) return v.toInt();
if (v is String) return int.tryParse(v.trim());
return null;
}
+4
View File
@@ -0,0 +1,4 @@
// the web's half of core: nothing. a site is updated by deploying it
/// false on the web, where theres nothing to update
const bool kUpdatesSupported = false;
@@ -0,0 +1,294 @@
import "dart:io";
import "installer.dart";
import "models.dart";
import "state.dart";
// Windows. The app never unpacks anything itself, the stub in <root> does:
//
// <root>\<AppExe>.exe the stub
// <root>\app-<build>\... a version folder, we are running out of one
// <root>\garage_updates.json state, the stubs and ours
//
// An install in Program Files cant be written by whoever is running the app,
// so there the stub keeps the count of starts in a file of the users own
// (see [UserState]). Everything read here is the two put together.
//
// All this side does is hand the stub a verified zip (`--garage-apply`), with
// a UAC prompt in front of it when <root> is in Program Files, and then start
// the stub again so it launches the new folder.
class WindowsInstaller implements Installer {
WindowsInstaller({
required this.root,
required this.stub,
required this.runningFolderBuild,
Map<String, String>? environment,
ProcessRunner? run,
ProcessStarter? start,
bool Function()? rootWritable,
}) : _env = environment ?? Platform.environment,
_run = run ?? defaultRunner,
_start = start ?? defaultStarter,
_rootWritableOverride = rootWritable;
final Directory root;
final File stub;
/// the number off the `app-<build>` folder this process lives in
final int runningFolderBuild;
final Map<String, String> _env;
final ProcessRunner _run;
final ProcessStarter _start;
final bool Function()? _rootWritableOverride;
late final StateFile state = StateFile(File(joinPath(root.path, "garage_updates.json")));
static final _versionFolder = RegExp(r"^app-(\d+)$");
static InstallDetection locate(String executable, {Map<String, String>? environment}) {
final folder = File(executable).parent;
final m = _versionFolder.firstMatch(baseName(folder.path));
if (m == null) {
return InstallDetection.none("${baseName(executable)} isn't running out of an app-<build> folder");
}
final root = folder.parent;
final stateFile = File(joinPath(root.path, "garage_updates.json"));
if (!stateFile.existsSync()) {
return const InstallDetection.none("there's no garage_updates.json beside the version folder");
}
final stub = _findStub(root, StateFile(stateFile).read(), executable);
if (stub == null) {
return const InstallDetection.none("there's no stub exe beside the version folder");
}
return InstallDetection.found(WindowsInstaller(
root: root,
stub: stub,
runningFolderBuild: int.parse(m.group(1)!),
environment: environment,
));
}
// the stub carries the apps exe name. a helper (stash-agent.exe) isnt named
// after it, so the state file is asked first and our own name second
static File? _findStub(Directory root, UpdateState? state, String executable) {
final names = <String>[
if (state?.exe != null) baseName(state!.exe!),
baseName(executable),
];
for (final n in names) {
final f = File(joinPath(root.path, n));
if (f.existsSync()) return f;
}
try {
final exes = root
.listSync()
.whereType<File>()
.where((f) => f.path.toLowerCase().endsWith(".exe"))
.toList();
if (exes.length == 1) return exes.single;
} catch (e) {
print("[garage_updates] couldnt look for the stub in ${root.path}: $e");
}
return null;
}
@override
String get platform => "windows";
@override
bool get exitsOnRestart => true;
/// "just me" installs are, Program Files isnt
bool get rootWritable {
final over = _rootWritableOverride;
if (over != null) return over();
final probe = File(joinPath(root.path, ".garage_updates_probe"));
try {
probe.writeAsStringSync("");
probe.deleteSync();
return true;
} on FileSystemException {
// the expected answer for Program Files, not worth a line in the log
return false;
}
}
/// The installer may leave `app_id` in the state file, otherwise the
/// folders name does.
String get appId {
final id = state.read()?.extra["app_id"];
// the stub wont make a folder out of one with these in, so neither do we
if (id is String && id.trim().isNotEmpty && !id.contains(RegExp("[\\\\/:*?\"<>|]"))) return id.trim();
return baseName(root.path);
}
/// `%LOCALAPPDATA%\<app id>\garage_updates.json`, the stubs count of starts
/// for this user when it couldnt write the one in root. The file is only
/// there for an install like that, we never make it.
UserStateFile? get userState {
final local = _env["LOCALAPPDATA"];
if (local == null || local.isEmpty) return null;
return UserStateFile(File(joinPath(local, appId, "garage_updates.json")));
}
UserState? _mine(UpdateState? rootState) {
final mine = userState?.read();
mine?.settleFor(rootState?.current);
return mine;
}
/// The build the stub starts for this user. `current`, unless that one
/// kept dying on them and the stub went back a build without being able to
/// say so in root.
int? get startsBuild {
final s = state.read();
final other = _mine(s)?.runInstead;
if (other != null && other != s?.current && Directory(joinPath(root.path, "app-$other")).existsSync()) {
return other;
}
return s?.current;
}
@override
Directory get staging {
if (rootWritable) return Directory(joinPath(root.path, "staging"));
final local = _env["LOCALAPPDATA"];
if (local == null || local.isEmpty) {
print("[garage_updates] no LOCALAPPDATA, staging in the temp folder");
return Directory(joinPath(Directory.systemTemp.path, appId, "staging"));
}
return Directory(joinPath(local, appId, "staging"));
}
@override
List<int> blockedBuilds() {
final s = state.read();
final out = <int>[...?s?.blocked];
// what failed for this user, on an install they cant write to
for (final b in _mine(s)?.blocked ?? const <int>[]) {
if (!out.contains(b)) out.add(b);
}
return out;
}
@override
Future<void> apply(File archive, UpdateRelease release, {required int runningBuild}) async {
if (release.asset.format != "zip") {
throw UpdateError("format", "A windows release has to be a zip, not ${release.asset.format}");
}
final args = ["--garage-apply", archive.path, "${release.build}"];
final ProcessResult res;
if (rootWritable) {
res = await _run(stub.path, args);
} else {
// one UAC prompt. powershell is only the thing that can ask for it
res = await _run(powershellPath(_env), elevationArgs(stub.path, args));
}
if (res.exitCode != 0) {
print("[garage_updates] the stub exited ${res.exitCode}\n${res.stdout}\n${res.stderr}");
if (res.exitCode == kElevationRefused) {
throw UpdateError("elevation_refused", "Administrator permission was not given");
}
throw UpdateError("install_failed", "The update could not be installed (${res.exitCode})");
}
// belt and braces. a stub that said 0 but didnt move `current` would have
// us restart straight back into the old build, forever
final now = state.read();
if (now != null && now.current != release.build) {
throw UpdateError("install_failed", "The update did not take, still on build ${now.current}");
}
try {
if (archive.existsSync()) archive.deleteSync();
} catch (e) {
print("[garage_updates] couldnt remove ${archive.path} after installing it: $e");
}
}
@override
Future<void> relaunch(List<String> args) => _start(stub.path, args);
/// the stub counts starts on windows, before it launches us
@override
Future<bool> noteStart(int build) async => false;
@override
Future<void> markHealthy() async {
final s = state.read();
if (s != null && s.failedStarts != 0) state.update((s) => s.failedStarts = 0);
// the stub counted in here instead if it couldnt write to root
final mine = userState;
final u = mine?.read();
if (mine != null && u != null && u.failedStarts != 0) mine.update((u) => u.failedStarts = 0);
}
}
/// ERROR_CANCELLED, what windows gives when the UAC prompt is turned down
const kElevationRefused = 1223;
String powershellPath(Map<String, String> env) {
final sys = env["SystemRoot"] ?? env["SYSTEMROOT"] ?? env["windir"];
if (sys != null && sys.isNotEmpty) {
final full = "$sys\\System32\\WindowsPowerShell\\v1.0\\powershell.exe";
if (File(full).existsSync()) return full;
}
return "powershell";
}
/// The powershell command line that runs [exe] elevated and passes its exit
/// code back out. Start-Process -Verb RunAs is ShellExecute "runas".
List<String> elevationArgs(String exe, List<String> args) {
final line = args.map(windowsQuoteArg).join(" ");
// without the try a refused prompt leaves $p null and powershell exits 0
final script = "\$ErrorActionPreference = 'Stop'; "
"try { "
"\$p = Start-Process -FilePath ${powershellQuote(exe)} -ArgumentList ${powershellQuote(line)} "
"-Verb RunAs -Wait -PassThru -WindowStyle Hidden; "
"exit \$p.ExitCode "
"} catch { [Console]::Error.WriteLine(\$_); exit $kElevationRefused }";
return ["-NoProfile", "-ExecutionPolicy", "Bypass", "-WindowStyle", "Hidden", "-Command", script];
}
/// a single quoted powershell string, nothing inside it is expanded
String powershellQuote(String s) => "'${s.replaceAll("'", "''")}'";
/// One argument the way CommandLineToArgvW wants it. Backslashes only matter
/// in front of a quote, which is the bit everyone gets wrong with a path that
/// ends in one.
String windowsQuoteArg(String arg) {
if (arg.isNotEmpty && !arg.contains(RegExp("[ \t\n\"]"))) return arg;
final out = StringBuffer("\"");
var slashes = 0;
for (final ch in arg.split("")) {
if (ch == "\\") {
slashes++;
continue;
}
if (ch == "\"") {
out.write("\\" * (slashes * 2 + 1));
out.write("\"");
} else {
out.write("\\" * slashes);
out.write(ch);
}
slashes = 0;
}
out.write("\\" * (slashes * 2));
out.write("\"");
return out.toString();
}
@@ -0,0 +1,83 @@
import "dart:io";
import "package:flutter/foundation.dart";
import "package:flutter/services.dart";
import "../core/installer.dart";
import "../core/models.dart";
// Android. The apk is downloaded into the apps cache and handed to the system
// installer, which always asks. It also does the restarting, so theres no
// relaunch and no fallback here - a build that wont start is androids problem.
const _channel = MethodChannel("net.imbenji.garage_updates");
const _playStore = "com.android.vending";
class AndroidInstaller implements Installer {
AndroidInstaller(this.cacheDir);
final Directory cacheDir;
static Future<InstallDetection> locate() async {
if (!kReleaseMode) {
// a debug apk is signed with the debug key, a release wouldnt install
// over it anyway
return const InstallDetection.none("this isn't a release build");
}
final Map<String, dynamic>? info;
try {
info = await _channel.invokeMapMethod<String, dynamic>("info");
} catch (e, st) {
print("[garage_updates] couldnt ask android about the install: $e\n$st");
return const InstallDetection.none("the garage_updates plugin didn't answer");
}
if (info?["installer"] == _playStore) {
return const InstallDetection.none("installed from the Play Store, which does the updating");
}
final cache = info?["cacheDir"];
if (cache is! String || cache.isEmpty) {
return const InstallDetection.none("android gave no cache folder to download into");
}
return InstallDetection.found(AndroidInstaller(Directory(cache)));
}
@override
String get platform => "android";
@override
bool get exitsOnRestart => false;
// has to match the cache-path in the plugins file provider xml
@override
Directory get staging => Directory("${cacheDir.path}/garage_updates");
@override
List<int> blockedBuilds() => const [];
@override
Future<void> apply(File archive, UpdateRelease release, {required int runningBuild}) async {
if (release.asset.format != "apk") {
throw UpdateError("format", "An android release has to be an apk, not ${release.asset.format}");
}
try {
await _channel.invokeMethod<void>("install", {"path": archive.path});
} on PlatformException catch (e, st) {
print("[garage_updates] the system installer wouldnt open: $e\n$st");
throw UpdateError("install_failed", e.message ?? "The installer could not be opened");
}
}
@override
Future<void> relaunch(List<String> args) async {}
@override
Future<bool> noteStart(int build) async => false;
@override
Future<void> markHealthy() async {}
}
@@ -0,0 +1 @@
export "driver_io.dart" if (dart.library.js_interop) "driver_stub.dart";
@@ -0,0 +1,31 @@
import "dart:io";
import "../core/engine.dart";
import "../core/models.dart";
import "android_installer.dart";
/// The engine for whatever this is running on. null where the package has
/// nothing to do at all (linux, ios).
Future<UpdateDriver?> openDriver({
required String project,
required int build,
required String apiBase,
}) async {
if (Platform.isWindows || Platform.isMacOS) {
return UpdateEngine.detect(project: project, build: build, apiBase: apiBase);
}
if (Platform.isAndroid) {
// core cant do android, installing an apk goes through the plugin
final found = await AndroidInstaller.locate();
return UpdateEngine(
project: project,
build: build,
apiBase: apiBase,
installer: found.installer,
notInstalledReason: found.reason,
);
}
return null;
}
@@ -0,0 +1,10 @@
import "../core/models.dart";
// the web's half. nothing to update, so no driver
Future<UpdateDriver?> openDriver({
required String project,
required int build,
required String apiBase,
}) async =>
null;
+186
View File
@@ -0,0 +1,186 @@
import "dart:async";
import "package:flutter/foundation.dart";
import "package:flutter/widgets.dart";
import "package:garage_ui/garage_ui.dart";
import "branding.dart";
// What's on screen before the app's own runApp. A fixed layout and nothing to
// configure but the logo and the name: logo, name, one status line, a bar,
// and when a required update wont go in, why and a Retry.
enum SplashStage { checking, downloading, installing, starting }
class SplashController extends ChangeNotifier {
SplashStage _stage = SplashStage.checking;
double? _progress;
String? _error;
Completer<void>? _retry;
SplashStage get stage => _stage;
/// 0 to 1 while theres a number to show, null = busy
double? get progress => _progress;
/// set when a required update failed. the Retry button shows with it
String? get error => _error;
String get statusLine => switch (_stage) {
SplashStage.checking => "Checking for updates",
SplashStage.downloading => "Downloading update",
SplashStage.installing => "Installing",
SplashStage.starting => "Starting",
};
void show(SplashStage stage, {double? progress}) {
_stage = stage;
_progress = progress;
_error = null;
notifyListeners();
}
set progress(double? v) {
if (v == _progress) return;
_progress = v;
notifyListeners();
}
/// Puts the error up and waits for Retry to be pressed.
Future<void> fail(String message) {
_error = message;
// a bar sweeping away under an error reads as still trying
_progress ??= 0;
final c = _retry = Completer<void>();
notifyListeners();
return c.future;
}
void retry() {
final c = _retry;
_retry = null;
_error = null;
notifyListeners();
if (c != null && !c.isCompleted) c.complete();
}
}
class UpdateSplash extends StatelessWidget {
const UpdateSplash({required this.branding, required this.controller, super.key});
final UpdaterBranding branding;
final SplashController controller;
@override
Widget build(BuildContext context) {
final density = GarageTheme.of(context).density;
final logo = branding.buildLogo();
return Scaffold(
child: Center(
child: SizedBox(
width: density.fontSize * 22,
child: ListenableBuilder(
listenable: controller,
builder: (context, _) {
final error = controller.error;
return Column(
mainAxisSize: MainAxisSize.min,
children: [
if (logo != null) ...[
SizedBox.square(dimension: density.controlHeight * 2, child: logo),
const Gap.lg(),
],
Text(branding.name).large().semiBold(),
const Gap.sm(),
Text(controller.statusLine).muted(),
const Gap.lg(),
// the bar has no width of its own, it takes the columns
SizedBox(
width: double.infinity,
child: LinearProgressIndicator(value: controller.progress),
),
if (error != null) ...[
const Gap.xl(),
Text(error).muted(),
const Gap.md(),
Button(
style: const ButtonStyle.outline(),
onPressed: controller.retry,
child: const Text("Retry"),
),
],
],
);
},
),
),
),
);
}
}
/// The tiny app `launch` runs to get the splash on screen. The host app's own
/// runApp replaces it, and [onGone] is how the updater finds out it has.
class UpdateSplashApp extends StatefulWidget {
const UpdateSplashApp({
required this.branding,
required this.controller,
this.onGone,
super.key,
});
final UpdaterBranding branding;
final SplashController controller;
final VoidCallback? onGone;
static final defaultTheme = ThemeData(
colorScheme: GarageSchemes.carbon,
density: const Density.product(),
);
@override
State<UpdateSplashApp> createState() => _UpdateSplashAppState();
}
class _UpdateSplashAppState extends State<UpdateSplashApp> {
late final _delegate = _SplashDelegate(
(context) => UpdateSplash(branding: widget.branding, controller: widget.controller),
);
late final _router = RouterConfig<Object>(routerDelegate: _delegate);
@override
void dispose() {
_delegate.dispose();
widget.onGone?.call();
super.dispose();
}
@override
Widget build(BuildContext context) {
return GarageApp.router(
routerConfig: _router,
theme: widget.branding.theme ?? UpdateSplashApp.defaultTheme,
title: widget.branding.name,
);
}
}
// one page and nowhere to go. GarageApp only comes as a router, and pulling
// go_router into every app that wants updates for this would be daft
class _SplashDelegate extends RouterDelegate<Object> with ChangeNotifier {
_SplashDelegate(this.builder);
final WidgetBuilder builder;
@override
Widget build(BuildContext context) => builder(context);
@override
Future<bool> popRoute() => SynchronousFuture(false);
@override
Future<void> setNewRoutePath(Object configuration) => SynchronousFuture(null);
}
+322
View File
@@ -0,0 +1,322 @@
import "dart:async";
import "package:flutter/foundation.dart";
import "package:flutter/widgets.dart";
import "branding.dart";
import "core/models.dart";
import "platform/driver.dart";
import "splash.dart";
const _defaultApiBase = "https://pay.imbenji.net/api";
/// how long the splash waits on the check before letting the app start
const _checkWait = Duration(seconds: 2);
const _recheckEvery = Duration(hours: 6);
/// after the apps first frame. long enough that a build which dies on the way
/// up doesnt get called healthy
const _healthyAfter = Duration(seconds: 3);
class GarageUpdater {
GarageUpdater._();
/// There before [launch] is called, so an app can set [onBeforeRestart]
/// ahead of a restart that happens inside the splash.
static GarageUpdater get instance => _instance;
static GarageUpdater _instance = GarageUpdater._();
/// The one call, at the top of `main(List<String> args)`. Completes when
/// the app should carry on to its own runApp. For a required update that
/// is never: it restarts into the new build instead.
static Future<void> launch({
required List<String> args,
required String project,
required int build,
required String label,
required UpdaterBranding branding,
String apiBase = _defaultApiBase,
UpdateMode mode = UpdateMode.silent,
}) {
return instance.start(
args: args,
project: project,
build: build,
label: label,
branding: branding,
apiBase: apiBase,
mode: mode,
);
}
final ValueNotifier<UpdateInfo?> _ready = ValueNotifier<UpdateInfo?>(null);
/// null untill a newer build has been downloaded and verified. Then
/// [restartToUpdate] moves over to it.
ValueListenable<UpdateInfo?> get ready => _ready;
/// the same thing as a stream, for anyone who would rather await it
Stream<UpdateInfo> get readyStream => _readyStream.stream;
final _readyStream = StreamController<UpdateInfo>.broadcast();
/// The release notes of the newest build we know about. The splash never
/// shows these, they are for the app.
String? get notes => (_ready.value ?? _lastCheck)?.latest?.notes;
/// what the last check that got an answer said
UpdateInfo? get lastCheck => _lastCheck;
/// the label this build was launched with ("v2610-1")
String? get label => _label;
/// Run right before the app is restarted into a new build. Stop helper
/// processes here.
FutureOr<void> Function()? onBeforeRestart;
UpdateDriver? _driver;
UpdateInfo? _lastCheck;
UpdateMode _mode = UpdateMode.silent;
List<String> _args = const [];
String? _label;
bool _started = false;
bool _fetching = false;
Timer? _recheck;
Timer? _healthy;
/// [launch] with the seams showing. [driver] and [show] are for tests.
@visibleForTesting
Future<void> start({
required List<String> args,
required String project,
required int build,
required String label,
required UpdaterBranding branding,
String apiBase = _defaultApiBase,
UpdateMode mode = UpdateMode.silent,
UpdateDriver? driver,
void Function(Widget app)? show,
Duration checkWait = _checkWait,
}) async {
if (_started) {
print("[garage_updates] launch was called twice, ignoring the second");
return;
}
_started = true;
_args = List.of(args);
_mode = mode;
_label = label;
// a site is updated by deploying it
if (kIsWeb) return;
var d = driver;
if (d == null) {
try {
d = await openDriver(project: project, build: build, apiBase: apiBase);
} catch (e, st) {
print("[garage_updates] couldnt set the updater up, starting without it: $e\n$st");
return;
}
}
if (d == null) return;
if (!d.installed) {
// a dev build, flutter run, a copy that isnt in the layout. hands off
print("[garage_updates] not updating this copy: ${d.notInstalledReason}");
return;
}
_driver = d;
d.onBeforeRestart = () => onBeforeRestart?.call();
try {
// the mac counts its own starts. true = the last update kept dying and
// the old build has just been put back
if (await d.noteStart()) {
await d.restart(args: _args);
}
} catch (e, st) {
print("[garage_updates] couldnt count this start: $e\n$st");
}
WidgetsFlutterBinding.ensureInitialized();
final splash = SplashController();
(show ?? runApp)(UpdateSplashApp(
branding: branding,
controller: splash,
onGone: _hostAppIsUp,
));
await _behindTheSplash(d, splash, checkWait);
splash.show(SplashStage.starting);
_recheck = Timer.periodic(_recheckEvery, (_) => checkNow());
}
Future<void> _behindTheSplash(UpdateDriver d, SplashController splash, Duration wait) async {
while (true) {
splash.show(SplashStage.checking);
final UpdateInfo info;
final asking = d.check();
try {
info = await asking.timeout(wait);
} on TimeoutException {
// no answer in time. the app starts, the answer is dealt with whenever
// it turns up
print("[garage_updates] no answer from the update check yet, starting the app");
unawaited(asking.then(_gotLateAnswer, onError: (Object e, StackTrace st) {
print("[garage_updates] the update check failed: $e\n$st");
}));
return;
} catch (e, st) {
print("[garage_updates] the update check failed, starting the app: $e\n$st");
return;
}
_lastCheck = info;
final latest = info.latest;
if (info.isRequired) {
if (latest == null) {
// below the minimum, and the only newer build is blocked here
await splash.fail("This version can no longer be used, and the update can't be installed here.");
continue;
}
try {
await _fetchAndInstall(d, latest, splash);
await d.restart(args: _args);
} catch (e, st) {
print("[garage_updates] the required update failed: $e\n$st");
await splash.fail(_sayWhy(e));
continue;
}
// only android gets here, its installer is a prompt over the top of us
await splash.fail("Install the update to continue.");
continue;
}
if (latest == null || !info.hasUpdate) return;
if (_mode == UpdateMode.prompt || defaultTargetPlatform == TargetPlatform.android) {
// android always asks, so its never sprung on someone at launch
unawaited(_fetchQuietly(info));
return;
}
try {
await _fetchAndInstall(d, latest, splash);
await d.restart(args: _args);
} catch (e, st) {
// not required, so its not worth keeping anyone out of the app over
print("[garage_updates] couldnt update at launch, starting the old build: $e\n$st");
}
return;
}
}
Future<void> _fetchAndInstall(UpdateDriver d, UpdateRelease latest, SplashController splash) async {
splash.show(SplashStage.downloading, progress: 0);
await d.download(latest, onProgress: (got, total) {
splash.progress = (total == null || total <= 0) ? null : (got / total).clamp(0.0, 1.0);
});
splash.show(SplashStage.installing);
await d.install(latest);
splash.show(SplashStage.starting);
}
String _sayWhy(Object e) {
if (e is UpdateError) return e.message;
return "The update could not be installed.";
}
void _gotLateAnswer(UpdateInfo info) {
_lastCheck = info;
if (info.hasUpdate) unawaited(_fetchQuietly(info));
}
/// Asks again now, and fetches whatever is newer. Runs by itself every 6
/// hours, an app can call it from a "check for updates" button.
Future<UpdateInfo?> checkNow() async {
final d = _driver;
if (d == null) return null;
try {
final info = await d.check();
_lastCheck = info;
if (info.hasUpdate) await _fetchQuietly(info);
return info;
} catch (e, st) {
print("[garage_updates] the background update check failed: $e\n$st");
return null;
}
}
Future<void> _fetchQuietly(UpdateInfo info) async {
final d = _driver;
final latest = info.latest;
if (d == null || latest == null || _fetching) return;
if (_ready.value?.latest?.build == latest.build) return;
_fetching = true;
try {
await d.download(latest);
_ready.value = info;
_readyStream.add(info);
} catch (e, st) {
// the part file is kept, the next check carries on from it
print("[garage_updates] the background download failed: $e\n$st");
} finally {
_fetching = false;
}
}
/// Installs the update that [ready] announced and restarts into it. Throws
/// an [UpdateError] when it wont go in (a UAC prompt turned down, say).
Future<void> restartToUpdate() async {
final d = _driver;
final latest = _ready.value?.latest;
if (d == null || latest == null) {
print("[garage_updates] restartToUpdate with no update waiting, nothing to do");
return;
}
try {
await d.install(latest);
await d.restart(args: _args);
} catch (e, st) {
print("[garage_updates] couldnt restart into build ${latest.build}: $e\n$st");
rethrow;
}
}
/// Tells the updater this build starts fine, which stops it being rolled
/// back. Called for you a few seconds after the first frame.
Future<void> markHealthy() async {
try {
await _driver?.markHealthy();
} catch (e, st) {
print("[garage_updates] couldnt mark this build healthy: $e\n$st");
}
}
// the splash was just torn down, which is the host app's runApp taking over.
// its first frame is the next one
void _hostAppIsUp() {
WidgetsBinding.instance.addPostFrameCallback((_) {
_healthy?.cancel();
_healthy = Timer(_healthyAfter, markHealthy);
});
}
/// Puts a fresh updater in [instance]. Tests only.
@visibleForTesting
static void reset() {
_instance._recheck?.cancel();
_instance._healthy?.cancel();
_instance = GarageUpdater._();
}
}
+37
View File
@@ -0,0 +1,37 @@
name: garage_updates
description: "Auto updates for Garage apps — asks Garage for the newest release, downloads it with resume, checks the sha256, installs it beside the old one and restarts into it."
version: 0.1.0
publish_to: 'none'
environment:
sdk: ^3.10.0
flutter: ">=3.5.0"
dependencies:
flutter:
sdk: flutter
# the splash is drawn with the design system, nothing of its own
garage_ui:
path: ../garage_ui
# sha256 of the download, streamed off disk
crypto: ^3.0.6
dev_dependencies:
flutter_test:
sdk: flutter
flutter_lints: ^6.0.0
flutter:
plugin:
platforms:
android:
package: net.imbenji.garage_updates
pluginClass: GarageUpdatesPlugin
# no channel on windows. ffiPlugin only so the host app's build pulls in
# windows/CMakeLists.txt, which is where the stub exe gets built
windows:
ffiPlugin: true
+167
View File
@@ -0,0 +1,167 @@
import "dart:io";
import "package:flutter_test/flutter_test.dart";
import "package:garage_updates/core.dart";
import "support/fake_server.dart";
void main() {
late FakeServer server;
late UpdateClient client;
setUp(() async {
server = await FakeServer.start(const []);
client = UpdateClient(project: "proj_1", apiBase: "${server.base}/", httpClient: HttpClient());
});
tearDown(() async {
client.close();
await server.close();
});
Future<UpdateInfo> check() => client.check(platform: "windows", arch: "x64", build: 12);
Map<String, dynamic> latest({Object? build = 13}) => {
"label": "v2610-1",
"build": build,
"notes": "Fixed the thing",
"published_at": "2026-10-01T10:00:00Z",
"asset": {
"url": "https://cdn.example.com/app.zip",
"filename": "app.zip",
"format": "zip",
"size": 1234,
"sha256": "ABCDEF",
},
};
test("asks the right url", () async {
server.updateBody = {"status": "current", "minimum_build": null, "latest": null};
await check();
expect(server.log.single, "GET /v1/updates/proj_1");
final uri = client.checkUri(platform: "macos", arch: "arm64", build: 7);
expect(uri.queryParameters, {"platform": "macos", "arch": "arm64", "build": "7"});
// the trailing slash on apiBase didnt double up
expect(uri.path, "/v1/updates/proj_1");
});
test("current", () async {
server.updateBody = {"status": "current", "minimum_build": 4, "latest": null};
final info = await check();
expect(info.status, UpdateStatus.current);
expect(info.minimumBuild, 4);
expect(info.latest, isNull);
expect(info.hasUpdate, isFalse);
});
test("available", () async {
server.updateBody = {"status": "available", "minimum_build": null, "latest": latest()};
final info = await check();
expect(info.status, UpdateStatus.available);
expect(info.hasUpdate, isTrue);
expect(info.isRequired, isFalse);
final l = info.latest!;
expect(l.label, "v2610-1");
expect(l.build, 13);
expect(l.notes, "Fixed the thing");
expect(l.publishedAt, DateTime.utc(2026, 10, 1, 10));
expect(l.asset.url, "https://cdn.example.com/app.zip");
expect(l.asset.filename, "app.zip");
expect(l.asset.format, "zip");
expect(l.asset.size, 1234);
// lower cased, its compared against our own hex
expect(l.asset.sha256, "abcdef");
});
test("required", () async {
server.updateBody = {"status": "required", "minimum_build": 13, "latest": latest()};
final info = await check();
expect(info.status, UpdateStatus.required);
expect(info.isRequired, isTrue);
expect(info.minimumBuild, 13);
});
test("unknown", () async {
server.updateBody = {"status": "unknown", "minimum_build": null, "latest": null};
expect((await check()).status, UpdateStatus.unknown);
});
test("a status we've never heard of is unknown", () async {
server.updateBody = {"status": "sideways", "latest": latest()};
expect((await check()).status, UpdateStatus.unknown);
});
test("numbers as strings, missing keys and the wrong types are put up with", () async {
final l = latest(build: "13");
(l["asset"] as Map)["size"] = "1234";
(l["asset"] as Map).remove("format");
l["notes"] = 42;
l.remove("published_at");
server.updateBody = {"status": "available", "minimum_build": "9", "latest": l};
final info = await check();
expect(info.minimumBuild, 9);
expect(info.latest!.build, 13);
expect(info.latest!.notes, "");
expect(info.latest!.publishedAt, isNull);
expect(info.latest!.asset.size, 1234);
// worked out from the filename
expect(info.latest!.asset.format, "zip");
});
test("available with nothing usable to download is unknown", () async {
final l = latest();
l.remove("asset");
server.updateBody = {"status": "available", "latest": l};
final info = await check();
expect(info.status, UpdateStatus.unknown);
expect(info.hasUpdate, isFalse);
});
test("a body that isnt json, or isnt an object, is unknown", () async {
server.updateBody = "<html>bad gateway</html>";
expect((await check()).status, UpdateStatus.unknown);
server.updateBody = [1, 2, 3];
expect((await check()).status, UpdateStatus.unknown);
});
test("a relative asset url is resolved against the api", () async {
final l = latest();
(l["asset"] as Map)["url"] = "/v1/updates/proj_1/download/a1";
server.updateBody = {"status": "available", "latest": l};
final info = await check();
expect(info.latest!.asset.url, "${server.base}/v1/updates/proj_1/download/a1");
});
test("an error status throws the store api's code", () async {
server.updateStatus = 404;
server.updateBody = {"error": "not_found", "message": "No such project"};
await expectLater(
check(),
throwsA(isA<UpdateError>()
.having((e) => e.code, "code", "not_found")
.having((e) => e.message, "message", "No such project")),
);
});
test("an error status with no json body still throws", () async {
server.updateStatus = 502;
server.updateBody = "bad gateway";
await expectLater(check(), throwsA(isA<UpdateError>().having((e) => e.code, "code", "http_502")));
});
test("a server that isnt there throws network", () async {
await server.close();
await expectLater(check(), throwsA(isA<UpdateError>().having((e) => e.code, "code", "network")));
});
}
+36
View File
@@ -0,0 +1,36 @@
// Not a flutter test, a plain dart program:
//
// dart run test/core_headless.dart
//
// It imports core and nothing else and runs on the standalone vm, which has
// no dart:ui. If core ever picked up a flutter import this wouldnt compile.
import "dart:io";
import "package:garage_updates/core.dart";
Future<void> main() async {
final engine = UpdateEngine.detect(project: "proj_headless", build: 1);
// `dart run` is the jit, so this is a dev copy and the engine must sit still
if (engine.installed) {
stderr.writeln("FAIL: a dart run was taken for an install");
exit(1);
}
engine.reportIfNotInstalled();
final info = await engine.check();
if (info.status != UpdateStatus.unknown) {
stderr.writeln("FAIL: an engine with no install asked the server");
exit(1);
}
final state = StateFile(File("${Directory.systemTemp.path}/garage_updates_headless_missing.json"));
if (state.read() != null) {
stderr.writeln("FAIL: a missing state file read as something");
exit(1);
}
engine.close();
print("core runs headless: supported=$kUpdatesSupported arch=${currentUpdateArch()} platform=${currentUpdatePlatform()}");
}
@@ -0,0 +1,85 @@
import "dart:io";
import "package:flutter_test/flutter_test.dart";
// core.dart is for headless dart programs, so nothing it reaches may import
// flutter. This walks the imports from lib/core.dart (both sides of every
// conditional one) and checks. test/core_headless.dart is the other half: it
// actually runs core on the plain dart vm, which has no dart:ui to give.
final _directive = RegExp(r'''^\s*(?:import|export)\s+([^;]+);''', multiLine: true);
final _uri = RegExp(r'''["']([^"']+)["']''');
Set<String> _walk(File start) {
final seen = <String>{};
final uris = <String>{};
final queue = [start];
while (queue.isNotEmpty) {
final f = queue.removeLast();
if (!seen.add(f.absolute.path)) continue;
for (final d in _directive.allMatches(f.readAsStringSync())) {
for (final m in _uri.allMatches(d.group(1)!)) {
final uri = m.group(1)!;
if (uri.startsWith("dart:") || uri.startsWith("package:")) {
uris.add(uri);
} else {
queue.add(File.fromUri(f.absolute.uri.resolve(uri)));
}
}
}
}
return uris;
}
void main() {
test("core.dart reaches no flutter", () {
final uris = _walk(File("lib/core.dart"));
expect(uris, isNotEmpty);
expect(uris.where((u) => u.startsWith("package:flutter")), isEmpty);
expect(uris.where((u) => u.startsWith("package:garage_ui")), isEmpty);
expect(uris, isNot(contains("dart:ui")));
// and the only package it leans on at all
expect(uris.where((u) => u.startsWith("package:")).toSet(), {"package:crypto/crypto.dart"});
});
test("core's web side reaches no dart:io", () {
final uris = {
..._walk(File("lib/src/core/models.dart")),
..._walk(File("lib/src/core/web.dart")),
};
expect(uris, isNot(contains("dart:io")));
expect(uris, isNot(contains("dart:ffi")));
});
test("the flutter entry point reaches dart:io only behind a conditional import", () {
// everything garage_updates.dart can reach on the web: the stub side of
// each conditional import, never the io side
final seen = <String>{};
final uris = <String>{};
final queue = [File("lib/garage_updates.dart")];
while (queue.isNotEmpty) {
final f = queue.removeLast();
if (!seen.add(f.absolute.path)) continue;
for (final d in _directive.allMatches(f.readAsStringSync())) {
// of a conditional pair the last uri is the one the web gets
final uri = _uri.allMatches(d.group(1)!).last.group(1)!;
if (uri.startsWith("dart:") || uri.startsWith("package:")) {
uris.add(uri);
} else {
queue.add(File.fromUri(f.absolute.uri.resolve(uri)));
}
}
}
expect(seen.where((p) => p.endsWith("driver_stub.dart")), isNotEmpty);
expect(seen.where((p) => p.endsWith("driver_io.dart")), isEmpty);
expect(uris, isNot(contains("dart:io")));
expect(uris, isNot(contains("dart:ffi")));
});
}
+260
View File
@@ -0,0 +1,260 @@
import "dart:convert";
import "dart:io";
import "package:flutter_test/flutter_test.dart";
import "package:garage_updates/core.dart";
import "support/fake_server.dart";
void main() {
late FakeServer server;
late Directory staging;
final data = noise(200 * 1024);
Downloader make({int retries = 0}) => Downloader(
httpClient: HttpClient(),
retries: retries,
retryPause: const Duration(milliseconds: 10),
quietTimeout: const Duration(seconds: 5),
);
setUp(() async {
server = await FakeServer.start(data);
staging = Directory("${Directory.systemTemp.createTempSync("gu_dl_").path}/staging");
});
tearDown(() async {
await server.close();
if (staging.parent.existsSync()) staging.parent.deleteSync(recursive: true);
});
test("downloads, verifies and renames", () async {
final release = server.release();
final seen = <int>[];
int? total;
final file = await make().fetch(
release: release,
staging: staging,
onProgress: (got, t) {
seen.add(got);
total = t;
},
);
expect(file.path, Downloader.finishedFile(staging, release).path);
expect(file.path.endsWith("update-13.zip"), isTrue);
expect(file.readAsBytesSync(), data);
expect(seen.last, data.length);
expect(total, data.length);
// nothing left lying about
expect(Downloader.partFile(staging).existsSync(), isFalse);
expect(Downloader.metaFile(staging).existsSync(), isFalse);
});
test("a cut connection keeps the part, and the next go resumes with Range", () async {
final release = server.release();
server.cutsLeft = 1;
server.cutAfter = 50 * 1024;
await expectLater(
make().fetch(release: release, staging: staging),
throwsA(isA<UpdateError>().having((e) => e.code, "code", "download")),
);
final part = Downloader.partFile(staging);
expect(part.existsSync(), isTrue);
final had = part.lengthSync();
expect(had, greaterThan(0));
expect(had, lessThan(data.length));
expect(Downloader.metaFile(staging).existsSync(), isTrue);
int? firstProgress;
final file = await make().fetch(
release: release,
staging: staging,
onProgress: (got, _) => firstProgress ??= got,
);
expect(server.log, ["GET /blob", "GET /blob bytes=$had-"]);
expect(file.readAsBytesSync(), data);
// progress carried on from where it was, not from nought
expect(firstProgress, had);
});
test("retries by itself, resuming each time", () async {
final release = server.release();
server.cutsLeft = 2;
server.cutAfter = 30 * 1024;
final file = await make(retries: 3).fetch(release: release, staging: staging);
expect(file.readAsBytesSync(), data);
expect(server.log.length, 3);
expect(server.log[0], "GET /blob");
expect(server.log[1], startsWith("GET /blob bytes="));
expect(server.log[2], startsWith("GET /blob bytes="));
});
test("a 200 that ignored the range starts the file again", () async {
final release = server.release();
server.cutsLeft = 1;
server.cutAfter = 50 * 1024;
await expectLater(make().fetch(release: release, staging: staging), throwsA(isA<UpdateError>()));
server.ignoreRange = true;
final file = await make().fetch(release: release, staging: staging);
expect(server.log.last, startsWith("GET /blob bytes="));
// not the old half with the whole file stuck on the end
expect(file.lengthSync(), data.length);
expect(file.readAsBytesSync(), data);
});
test("a hosted download follows the 302, and asks the original url again on resume", () async {
final release = server.release(path: "/hosted");
server.cutsLeft = 1;
server.cutAfter = 40 * 1024;
await expectLater(make().fetch(release: release, staging: staging), throwsA(isA<UpdateError>()));
final had = Downloader.partFile(staging).lengthSync();
// the first presigned url is dead by now. going straight back to it would 403
final file = await make().fetch(release: release, staging: staging);
expect(server.log, [
"GET /hosted",
"GET /blob",
"GET /hosted bytes=$had-",
"GET /blob bytes=$had-",
]);
expect(file.readAsBytesSync(), data);
});
test("a checksum mismatch deletes the download and fails", () async {
final release = server.release(sha256: "0" * 64);
await expectLater(
make(retries: 3).fetch(release: release, staging: staging),
throwsA(isA<UpdateError>().having((e) => e.code, "code", "checksum_mismatch")),
);
expect(Downloader.partFile(staging).existsSync(), isFalse);
expect(Downloader.metaFile(staging).existsSync(), isFalse);
expect(Downloader.finishedFile(staging, release).existsSync(), isFalse);
// and it wasnt retried, the same bytes would come back
expect(server.log.length, 1);
});
test("a stale part for another build is thrown away", () async {
staging.createSync(recursive: true);
Downloader.partFile(staging).writeAsBytesSync(noise(10 * 1024, seed: 99));
Downloader.metaFile(staging).writeAsStringSync(jsonEncode({"build": 12, "sha256": "f" * 64}));
final file = await make().fetch(release: server.release(), staging: staging);
// no Range, it didnt try to carry on from someone elses bytes
expect(server.log, ["GET /blob"]);
expect(file.readAsBytesSync(), data);
});
test("a part for the same build but another sha is stale too", () async {
staging.createSync(recursive: true);
Downloader.partFile(staging).writeAsBytesSync(noise(10 * 1024, seed: 99));
Downloader.metaFile(staging).writeAsStringSync(jsonEncode({"build": 13, "sha256": "f" * 64}));
await make().fetch(release: server.release(), staging: staging);
expect(server.log, ["GET /blob"]);
});
test("a part with no note beside it is stale", () async {
staging.createSync(recursive: true);
Downloader.partFile(staging).writeAsBytesSync(noise(10 * 1024, seed: 99));
final file = await make().fetch(release: server.release(), staging: staging);
expect(server.log, ["GET /blob"]);
expect(file.readAsBytesSync(), data);
});
test("a part that is allready whole only gets verified", () async {
final release = server.release();
staging.createSync(recursive: true);
Downloader.partFile(staging).writeAsBytesSync(data);
Downloader.metaFile(staging)
.writeAsStringSync(jsonEncode({"build": release.build, "sha256": release.asset.sha256}));
final file = await make().fetch(release: release, staging: staging);
expect(server.log, isEmpty);
expect(file.readAsBytesSync(), data);
});
test("a finished download is reused, and other builds' are swept", () async {
final release = server.release();
await make().fetch(release: release, staging: staging);
File("${staging.path}/update-9.zip").writeAsStringSync("old");
server.log.clear();
await make().fetch(release: release, staging: staging);
expect(server.log, isEmpty);
// asking for a newer one clears the old finished files out
server.data = server.data.sublist(0, 1000);
final next = server.release(build: 14);
await make().fetch(release: next, staging: staging);
expect(File("${staging.path}/update-9.zip").existsSync(), isFalse);
expect(Downloader.finishedFile(staging, release).existsSync(), isFalse);
expect(Downloader.finishedFile(staging, next).existsSync(), isTrue);
});
test("a 404 fails without retrying", () async {
await expectLater(
make(retries: 3).fetch(release: server.release(path: "/gone"), staging: staging),
throwsA(isA<UpdateError>().having((e) => e.code, "code", "http_404")),
);
expect(server.log.length, 1);
});
test("a release with no checksum is refused", () async {
await expectLater(
make().fetch(release: server.release(sha256: ""), staging: staging),
throwsA(isA<UpdateError>().having((e) => e.code, "code", "no_checksum")),
);
expect(server.log, isEmpty);
});
test("a line that goes quiet times out", () async {
// accepts the connection and then says nothing at all
final silent = await ServerSocket.bind(InternetAddress.loopbackIPv4, 0);
final held = <Socket>[];
silent.listen(held.add);
final release = UpdateRelease(
label: "v13",
build: 13,
asset: UpdateAsset(
url: "http://127.0.0.1:${silent.port}/blob",
filename: "app.zip",
format: "zip",
size: data.length,
sha256: server.sha,
),
);
final d = Downloader(
httpClient: HttpClient(),
retries: 0,
quietTimeout: const Duration(milliseconds: 300),
);
await expectLater(
d.fetch(release: release, staging: staging),
throwsA(isA<UpdateError>().having((e) => e.code, "code", "download")),
);
d.close();
for (final s in held) {
s.destroy();
}
await silent.close();
});
}
+180
View File
@@ -0,0 +1,180 @@
import "dart:convert";
import "dart:io";
import "package:flutter_test/flutter_test.dart";
import "package:garage_updates/core.dart";
import "support/fake_install.dart";
import "support/fake_server.dart";
// the engine end to end against the pretend windows install: a real check, a
// real download off the fake server, the fake stub doing the installing
void main() {
late FakeServer server;
late FakeWindowsInstall fake;
late UpdateEngine engine;
final exits = <int>[];
Map<String, dynamic> answer(String status, {int build = 13, int? minimum}) => {
"status": status,
"minimum_build": minimum,
"latest": server.release(build: build).toJson(),
};
setUp(() async {
exits.clear();
server = await FakeServer.start(noise(64 * 1024));
fake = FakeWindowsInstall.create();
final found = WindowsInstaller.locate(fake.exe.path, environment: const {});
engine = UpdateEngine(
project: "proj_1",
build: 12,
installer: found.installer,
client: UpdateClient(project: "proj_1", apiBase: server.base, httpClient: HttpClient()),
downloader: Downloader(httpClient: HttpClient(), retries: 0),
arch: "x64",
exitProcess: exits.add,
);
});
tearDown(() async {
engine.close();
await server.close();
fake.dispose();
});
test("check, download, install, restart", () async {
server.updateBody = answer("available");
final order = <String>[];
engine.onBeforeRestart = () async {
// the stub has allready been run by the time the app is asked to tidy up
order.add("before restart, stub runs so far: ${fake.runs.length}");
};
final info = await engine.check();
expect(info.status, UpdateStatus.available);
expect(server.log.single, "GET /v1/updates/proj_1");
final latest = info.latest!;
expect(await engine.isDownloaded(latest), isFalse);
await engine.download(latest);
expect(await engine.isDownloaded(latest), isTrue);
final zip = "${fake.root.path}/staging/update-13.zip";
expect(File(zip).existsSync(), isTrue);
await engine.install(latest);
expect(exits, isEmpty, reason: "installing must not restart by itself");
await engine.restart(args: ["--route=/x"]);
expect(exits, [0]);
expect(order, ["before restart, stub runs so far: 1"]);
for (var i = 0; i < 100 && fake.runs.length < 2; i++) {
await Future<void>.delayed(const Duration(milliseconds: 50));
}
expect(fake.runs, [
["--garage-apply", zip, "13"],
["--route=/x"],
]);
// the stub was handed the bytes the server sent
expect(File("${fake.root.path}/app-13/unpacked-from.zip").readAsBytesSync(), server.data);
});
test("an onBeforeRestart that throws doesnt stop the restart", () async {
engine.onBeforeRestart = () => throw StateError("the agent wouldnt stop");
await engine.restart();
expect(exits, [0]);
});
test("a build that failed to start here is never offered again", () async {
// 11 is in the fake installs blocked list
server.updateBody = answer("available", build: 11);
engine = UpdateEngine(
project: "proj_1",
build: 9,
installer: engine.installer,
client: engine.client,
downloader: engine.downloader,
arch: "x64",
exitProcess: exits.add,
);
final lines = await printsOf(() async {
final first = await engine.check();
expect(first.status, UpdateStatus.current);
expect(first.latest, isNull);
expect(first.hasUpdate, isFalse);
await engine.check();
});
// said once, not every six hours for ever
expect(lines.where((l) => l.contains("failed to start on this machine")).length, 1);
});
test("a build that failed for this user on a read only install isnt offered to them again", () async {
// the stub went back to 12 for them. root still says 13 and blocks nothing
Directory("${fake.root.path}/app-13").createSync();
fake.stateFile.writeAsStringSync('{ "exe": "garage_stash.exe", "current": 13, "previous": 12, "failed_starts": 0, "blocked": [] }');
for (var i = 0; i < 4; i++) {
fake.plainLaunch(readOnly: true);
}
server.updateBody = answer("available", build: 13);
engine = UpdateEngine(
project: "proj_1",
build: 12,
installer: fake.installer(readOnly: true),
client: engine.client,
downloader: engine.downloader,
arch: "x64",
exitProcess: exits.add,
);
final info = await engine.check();
expect(info.status, UpdateStatus.current);
expect(info.hasUpdate, isFalse);
// the one after it is
server.updateBody = answer("available", build: 14);
expect((await engine.check()).latest!.build, 14);
});
test("a blocked build that is also required stays required, with nothing to install", () async {
server.updateBody = answer("required", build: 11, minimum: 11);
engine = UpdateEngine(
project: "proj_1",
build: 9,
installer: engine.installer,
client: engine.client,
downloader: engine.downloader,
arch: "x64",
);
final info = await engine.check();
expect(info.status, UpdateStatus.required);
expect(info.latest, isNull);
});
test("an answer offering our own build, or an older one, is current", () async {
server.updateBody = answer("available", build: 12);
expect((await engine.check()).status, UpdateStatus.current);
server.updateBody = answer("available", build: 5);
expect((await engine.check()).hasUpdate, isFalse);
});
test("install before download says so", () async {
await expectLater(
engine.install(server.release()),
throwsA(isA<UpdateError>().having((e) => e.code, "code", "not_downloaded")),
);
expect(fake.runs, isEmpty);
});
test("markHealthy reaches the state file", () async {
await engine.markHealthy();
expect((jsonDecode(fake.stateFile.readAsStringSync()) as Map)["failed_starts"], 0);
});
}
+296
View File
@@ -0,0 +1,296 @@
@TestOn("mac-os")
library;
import "dart:io";
import "package:flutter_test/flutter_test.dart";
import "package:garage_updates/core.dart";
import "support/fake_install.dart";
UpdateRelease _release(int build, {String format = "zip"}) => UpdateRelease(
label: "v$build",
build: build,
asset: UpdateAsset(url: "http://x/app.$format", filename: "app.$format", format: format, size: 3, sha256: "aa"),
);
void main() {
late Directory tmp;
late Directory apps;
late Directory bundle;
late MacInstaller mac;
setUp(() {
// resolved, /var is a symlink to /private/var and the paths get compared
tmp = Directory(Directory.systemTemp.createTempSync("gu_mac_").resolveSymbolicLinksSync());
apps = Directory("${tmp.path}/Applications")..createSync();
bundle = makeApp(apps, marker: "build 12");
mac = MacInstaller(
bundle: bundle,
bundleId: "net.imbenji.foo",
support: Directory("${tmp.path}/Library/Application Support/net.imbenji.foo/garage_updates"),
);
});
tearDown(() {
Process.runSync("/bin/chmod", ["-R", "u+w", tmp.path]);
tmp.deleteSync(recursive: true);
});
// a zip of build [build], sitting in staging the way the downloader leaves it
File stagedZip(int build, {String id = "net.imbenji.foo", String name = "Foo.app"}) {
final src = Directory("${tmp.path}/src-$build")..createSync();
final app = makeApp(src, marker: "build $build", id: id, name: name);
mac.staging.createSync(recursive: true);
return zipApp(app, File("${mac.staging.path}/update-$build.zip"));
}
group("finding the install", () {
test("an exe inside a bundle finds it, its id and where the state goes", () {
final found = MacInstaller.locate("${bundle.path}/Contents/MacOS/Foo", environment: {"HOME": tmp.path});
expect(found.reason, isNull);
final m = found.installer as MacInstaller;
expect(m.bundle.path, bundle.path);
expect(m.bundleId, "net.imbenji.foo");
expect(m.support.path, "${tmp.path}/Library/Application Support/net.imbenji.foo/garage_updates");
expect(m.state.file.path, endsWith("garage_updates/state.json"));
expect(m.previousApp.path, endsWith("garage_updates/previous.app"));
});
test("a helper nested in the bundle belongs to the outer app", () {
final helper = "${bundle.path}/Contents/Library/LoginItems/Helper.app/Contents/MacOS/Helper";
final found = MacInstaller.locate(helper, environment: {"HOME": tmp.path});
expect((found.installer as MacInstaller).bundle.path, bundle.path);
});
test("a bare executable is not an install", () {
final found = MacInstaller.locate("${tmp.path}/bin/dart", environment: {"HOME": tmp.path});
expect(found.installer, isNull);
expect(found.reason, contains("app bundle"));
});
test("a translocated bundle is not an install", () {
final found = MacInstaller.locate(
"/private/var/folders/xx/T/AppTranslocation/ABCD-1234/d/Foo.app/Contents/MacOS/Foo",
environment: {"HOME": tmp.path},
);
expect(found.installer, isNull);
expect(found.reason, contains("translocated"));
});
test("a build folder is not an install", () {
final found = MacInstaller.locate(
"${tmp.path}/proj/build/macos/Build/Products/Release/Foo.app/Contents/MacOS/Foo",
environment: {"HOME": tmp.path},
);
expect(found.installer, isNull);
expect(found.reason, contains("build folder"));
});
test("a bundle in a folder we cant write to is not an install", () {
Process.runSync("/bin/chmod", ["555", apps.path]);
final found = MacInstaller.locate("${bundle.path}/Contents/MacOS/Foo", environment: {"HOME": tmp.path});
expect(found.installer, isNull);
expect(found.reason, contains("can't be replaced"));
});
test("reads the bundle id out of a binary plist too", () {
final plist = "${bundle.path}/Contents/Info.plist";
final res = Process.runSync("/usr/bin/plutil", ["-convert", "binary1", plist]);
expect(res.exitCode, 0, reason: "${res.stderr}");
expect(readBundleId(bundle), "net.imbenji.foo");
});
});
group("the swap", () {
test("unpacks with ditto, keeps the old bundle as previous.app, puts the new one in place", () async {
final zip = stagedZip(13);
await mac.noteStart(12);
await mac.apply(zip, _release(13), runningBuild: 12);
expect(markerOf(bundle), "build 13");
expect(markerOf(mac.previousApp), "build 12");
// still a bundle someone could run
expect(File("${bundle.path}/Contents/MacOS/Foo").existsSync(), isTrue);
expect(readBundleId(bundle), "net.imbenji.foo");
final s = mac.state.read()!;
expect(s.current, 13);
expect(s.previous, 12);
expect(s.failedStarts, 0);
expect(zip.existsSync(), isFalse);
expect(Directory("${mac.support.path}/unpack").existsSync(), isFalse);
// and nothing else turned up beside the app
expect(apps.listSync().map((e) => e.uri.pathSegments.where((s) => s.isNotEmpty).last), ["Foo.app"]);
});
test("a second update replaces previous.app", () async {
await mac.apply(stagedZip(13), _release(13), runningBuild: 12);
await mac.apply(stagedZip(14), _release(14), runningBuild: 13);
expect(markerOf(bundle), "build 14");
expect(markerOf(mac.previousApp), "build 13");
expect(mac.state.read()!.previous, 13);
});
test("an update for some other app is refused and nothing moves", () async {
final zip = stagedZip(13, id: "com.someone.else");
await expectLater(
mac.apply(zip, _release(13), runningBuild: 12),
throwsA(isA<UpdateError>().having((e) => e.code, "code", "wrong_app")),
);
expect(markerOf(bundle), "build 12");
expect(mac.previousApp.existsSync(), isFalse);
});
test("a zip with no app in it is refused and nothing moves", () async {
final junk = Directory("${tmp.path}/junk")..createSync();
File("${junk.path}/readme.txt").writeAsStringSync("hello");
mac.staging.createSync(recursive: true);
final zip = File("${mac.staging.path}/update-13.zip");
Process.runSync("/usr/bin/ditto", ["-c", "-k", junk.path, zip.path]);
await expectLater(
mac.apply(zip, _release(13), runningBuild: 12),
throwsA(isA<UpdateError>().having((e) => e.code, "code", "no_app")),
);
expect(markerOf(bundle), "build 12");
});
test("a file that isnt a zip at all fails cleanly", () async {
mac.staging.createSync(recursive: true);
final zip = File("${mac.staging.path}/update-13.zip")..writeAsStringSync("not a zip");
await expectLater(
mac.apply(zip, _release(13), runningBuild: 12),
throwsA(isA<UpdateError>()),
);
expect(markerOf(bundle), "build 12");
});
test("the app inside can be one folder down, and named differently", () async {
final src = Directory("${tmp.path}/src/Foo 13")..createSync(recursive: true);
makeApp(src, marker: "build 13", name: "Foo Renamed.app");
mac.staging.createSync(recursive: true);
final zip = File("${mac.staging.path}/update-13.zip");
Process.runSync("/usr/bin/ditto", ["-c", "-k", "--keepParent", src.path, zip.path]);
await mac.apply(zip, _release(13), runningBuild: 12);
// it goes where the running bundle was, under the running bundles name
expect(markerOf(bundle), "build 13");
});
test("a dmg is mounted, copied out of and detached", () async {
final src = Directory("${tmp.path}/dmgsrc")..createSync();
makeApp(src, marker: "build 13");
mac.staging.createSync(recursive: true);
final dmg = File("${mac.staging.path}/update-13.dmg");
final made = Process.runSync(
"/usr/bin/hdiutil",
["create", "-srcfolder", src.path, "-volname", "Foo", "-format", "UDZO", "-ov", dmg.path],
);
expect(made.exitCode, 0, reason: "${made.stderr}");
await mac.apply(dmg, _release(13, format: "dmg"), runningBuild: 12);
expect(markerOf(bundle), "build 13");
expect(markerOf(mac.previousApp), "build 12");
expect(Directory("${mac.support.path}/mount").existsSync(), isFalse);
});
});
group("the fallback", () {
test("three starts with no markHealthy and the fourth goes back", () async {
await mac.noteStart(12);
await mac.markHealthy();
await mac.apply(stagedZip(13), _release(13), runningBuild: 12);
expect(await mac.noteStart(13), isFalse);
expect(await mac.noteStart(13), isFalse);
expect(await mac.noteStart(13), isFalse);
expect(mac.state.read()!.failedStarts, 3);
expect(markerOf(bundle), "build 13");
expect(await mac.noteStart(13), isTrue);
expect(markerOf(bundle), "build 12");
expect(mac.previousApp.existsSync(), isFalse);
expect(Directory("${mac.support.path}/failed.app").existsSync(), isFalse);
final s = mac.state.read()!;
expect(s.current, 12);
expect(s.previous, isNull);
expect(s.failedStarts, 0);
expect(s.blocked, [13]);
expect(mac.blockedBuilds(), [13]);
});
test("markHealthy stops the count", () async {
await mac.apply(stagedZip(13), _release(13), runningBuild: 12);
for (var i = 0; i < 6; i++) {
expect(await mac.noteStart(13), isFalse);
await mac.markHealthy();
}
expect(markerOf(bundle), "build 13");
expect(mac.state.read()!.failedStarts, 0);
expect(mac.state.read()!.blocked, isEmpty);
});
test("with no previous.app theres nowhere to go back to", () async {
for (var i = 0; i < 6; i++) {
expect(await mac.noteStart(12), isFalse);
}
expect(markerOf(bundle), "build 12");
expect(mac.state.read()!.blocked, isEmpty);
});
test("a build put there by hand starts its count from nought", () async {
mac.state.write(UpdateState(current: 12, previous: 9, failedStarts: 3));
// 13 was dragged into Applications, the file knows nothing about it
expect(await mac.noteStart(13), isFalse);
final s = mac.state.read()!;
expect(s.current, 13);
expect(s.failedStarts, 1);
// no previous.app on disk, so no previous
expect(s.previous, isNull);
});
test("a damaged state file is started again rather than trusted", () async {
mac.support.createSync(recursive: true);
mac.state.file.writeAsStringSync('{ "current": 1');
expect(await mac.noteStart(12), isFalse);
expect(mac.state.read()!.current, 12);
expect(mac.state.read()!.failedStarts, 1);
});
});
test("relaunch is open -n on the bundle, arguments after --args", () async {
final calls = <List<String>>[];
final m = MacInstaller(
bundle: bundle,
bundleId: "net.imbenji.foo",
support: mac.support,
run: (exe, args) async {
calls.add([exe, ...args]);
return ProcessResult(1, 0, "", "");
},
);
await m.relaunch(const []);
await m.relaunch(["--route=/settings"]);
expect(calls, [
["/usr/bin/open", "-n", bundle.path],
["/usr/bin/open", "-n", bundle.path, "--args", "--route=/settings"],
]);
});
}
+145
View File
@@ -0,0 +1,145 @@
import "dart:io";
import "package:flutter_test/flutter_test.dart";
import "package:garage_updates/core.dart";
import "support/fake_install.dart";
import "support/fake_server.dart";
// the rule: a copy the updater didnt put there is left completly alone. no
// check, no download, nothing swapped, one line on the console.
void main() {
group("detecting", () {
test("this very test run is not an install", () {
// flutter_tester off the jit, exactly the dev case
final found = detectInstall();
expect(found.installer, isNull);
expect(found.reason, isNotNull);
});
test("a debug build is never an install, wherever it sits", () {
final fake = FakeWindowsInstall.create();
addTearDown(fake.dispose);
final found = detectInstall(executable: fake.exe.path, platform: "windows", product: false);
expect(found.installer, isNull);
expect(found.reason, contains("release build"));
// the same place as a release build is one
expect(detectInstall(executable: fake.exe.path, platform: "windows", product: true).installer, isNotNull);
});
test("flutter run on windows", () {
final found = detectInstall(
executable: r"C:\src\app\build\windows\x64\runner\Debug\app.exe",
platform: "windows",
product: true,
);
expect(found.installer, isNull);
expect(found.reason, contains("app-<build>"));
});
test("a release exe run out of the build folder on windows", () {
final tmp = Directory.systemTemp.createTempSync("gu_dev_");
addTearDown(() => tmp.deleteSync(recursive: true));
final release = Directory("${tmp.path}/build/windows/x64/runner/Release")..createSync(recursive: true);
final found = detectInstall(executable: "${release.path}/app.exe", platform: "windows", product: true);
expect(found.installer, isNull);
});
test("dart run / a bare binary on the mac", () {
final found = detectInstall(
executable: "/opt/homebrew/Cellar/dart/3.8.1/libexec/bin/dart",
platform: "macos",
product: true,
environment: const {"HOME": "/Users/someone"},
);
expect(found.installer, isNull);
expect(found.reason, contains("app bundle"));
});
test("flutter run on the mac", () {
final found = detectInstall(
executable: "/Users/someone/app/build/macos/Build/Products/Debug/App.app/Contents/MacOS/App",
platform: "macos",
product: true,
environment: const {"HOME": "/Users/someone"},
);
expect(found.installer, isNull);
expect(found.reason, contains("build folder"));
});
test("a platform core has no installer for", () {
final found = detectInstall(executable: "/usr/bin/app", platform: "linux", product: true);
expect(found.installer, isNull);
expect(found.reason, contains("linux"));
});
});
group("an engine with no install", () {
late FakeServer server;
late UpdateEngine engine;
final exits = <int>[];
setUp(() async {
exits.clear();
server = await FakeServer.start(noise(1024));
server.updateBody = {"status": "required", "minimum_build": 99, "latest": server.release().toJson()};
engine = UpdateEngine(
project: "proj_1",
build: 12,
notInstalledReason: "this isn't a release build",
client: UpdateClient(project: "proj_1", apiBase: server.base, httpClient: HttpClient()),
downloader: Downloader(httpClient: HttpClient(), retries: 0),
arch: "arm64",
exitProcess: exits.add,
);
});
tearDown(() async {
engine.close();
await server.close();
});
test("says why once, and never asks the server", () async {
expect(engine.installed, isFalse);
expect(engine.notInstalledReason, "this isn't a release build");
final lines = await printsOf(() async {
expect((await engine.check()).status, UpdateStatus.unknown);
expect((await engine.check()).hasUpdate, isFalse);
expect(engine.reportIfNotInstalled(), isFalse);
});
expect(lines, ["[garage_updates] not updating this copy: this isn't a release build"]);
expect(server.log, isEmpty);
});
test("wont download, install or restart", () async {
final release = server.release();
final notInstalled = throwsA(isA<UpdateError>().having((e) => e.code, "code", "not_installed"));
await expectLater(engine.download(release), notInstalled);
await expectLater(engine.install(release), notInstalled);
await expectLater(engine.restart(), notInstalled);
expect(server.log, isEmpty);
expect(exits, isEmpty);
});
test("counting starts and markHealthy are quiet no-ops", () async {
expect(await engine.noteStart(), isFalse);
await engine.markHealthy();
expect(await engine.isDownloaded(server.release()), isFalse);
});
test("detect() off a test run gives exactly this engine", () {
final e = UpdateEngine.detect(project: "proj_1", build: 12);
addTearDown(e.close);
expect(e.installed, isFalse);
expect(e.installer, isNull);
});
});
}
+117
View File
@@ -0,0 +1,117 @@
import "package:flutter/widgets.dart";
import "package:flutter_test/flutter_test.dart";
import "package:garage_ui/garage_ui.dart";
import "package:garage_updates/garage_updates.dart";
void main() {
const branding = UpdaterBranding(
name: "Garage Stash",
logo: SizedBox(key: Key("logo")),
);
Future<SplashController> pumpSplash(WidgetTester t, {UpdaterBranding b = branding, VoidCallback? onGone}) async {
final c = SplashController();
await t.pumpWidget(UpdateSplashApp(branding: b, controller: c, onGone: onGone));
return c;
}
double? bar(WidgetTester t) => t.widget<LinearProgressIndicator>(find.byType(LinearProgressIndicator)).value;
testWidgets("the logo, the name, one status line and a bar", (t) async {
await pumpSplash(t);
expect(find.byKey(const Key("logo")), findsOneWidget);
expect(find.text("Garage Stash"), findsOneWidget);
expect(find.text("Checking for updates"), findsOneWidget);
expect(find.byType(LinearProgressIndicator), findsOneWidget);
// nothing known yet, so the bar just sweeps
expect(bar(t), isNull);
expect(find.text("Retry"), findsNothing);
expect(find.byType(Button), findsNothing);
});
testWidgets("each stage has its line", (t) async {
final c = await pumpSplash(t);
c.show(SplashStage.downloading, progress: 0);
await t.pump();
expect(find.text("Downloading update"), findsOneWidget);
expect(find.text("Checking for updates"), findsNothing);
expect(bar(t), 0);
c.progress = 0.4;
await t.pump();
expect(bar(t), 0.4);
c.show(SplashStage.installing);
await t.pump();
expect(find.text("Installing"), findsOneWidget);
expect(bar(t), isNull);
c.show(SplashStage.starting);
await t.pump();
expect(find.text("Starting"), findsOneWidget);
expect(find.text("Installing"), findsNothing);
});
testWidgets("a failure shows why and a Retry, and Retry clears it", (t) async {
final c = await pumpSplash(t);
c.show(SplashStage.downloading, progress: 0.3);
var retried = false;
c.fail("The download didn't match its checksum").then((_) => retried = true);
await t.pump();
expect(find.text("The download didn't match its checksum"), findsOneWidget);
expect(find.text("Retry"), findsOneWidget);
// the stage it failed at is still what the status line says
expect(find.text("Downloading update"), findsOneWidget);
expect(bar(t), 0.3);
expect(retried, isFalse);
await t.tap(find.text("Retry"));
await t.pump();
expect(retried, isTrue);
expect(find.text("Retry"), findsNothing);
expect(find.text("The download didn't match its checksum"), findsNothing);
});
testWidgets("a failure with nothing measured stops the bar sweeping", (t) async {
final c = await pumpSplash(t);
c.show(SplashStage.installing);
c.fail("The update could not be installed.");
await t.pump();
expect(bar(t), 0);
});
testWidgets("no logo is fine", (t) async {
await pumpSplash(t, b: const UpdaterBranding(name: "Plain"));
expect(find.text("Plain"), findsOneWidget);
expect(find.byType(LinearProgressIndicator), findsOneWidget);
});
testWidgets("its drawn with the garage theme, carbon unless the developer says otherwise", (t) async {
await pumpSplash(t);
var theme = GarageTheme.of(t.element(find.byType(UpdateSplash)));
expect(theme.colorScheme, GarageSchemes.carbon);
final light = ThemeData(colorScheme: GarageSchemes.light);
await t.pumpWidget(const SizedBox());
await pumpSplash(t, b: UpdaterBranding(name: "Light", theme: light));
theme = GarageTheme.of(t.element(find.byType(UpdateSplash)));
expect(theme.colorScheme, GarageSchemes.light);
});
testWidgets("the host app taking over is noticed", (t) async {
var gone = 0;
await pumpSplash(t, onGone: () => gone++);
expect(gone, 0);
// what the apps own runApp does to us
await t.pumpWidget(const SizedBox());
expect(gone, 1);
});
}
+159
View File
@@ -0,0 +1,159 @@
import "dart:convert";
import "dart:io";
import "package:flutter_test/flutter_test.dart";
import "package:garage_updates/core.dart";
void main() {
late Directory dir;
late StateFile state;
setUp(() {
dir = Directory.systemTemp.createTempSync("gu_state_");
state = StateFile(File("${dir.path}/garage_updates.json"));
});
tearDown(() => dir.deleteSync(recursive: true));
test("a missing file reads as null", () {
expect(state.read(), isNull);
});
test("reads what the stub writes", () {
state.file.writeAsStringSync(
'{ "exe": "garage_stash.exe", "current": 12, "previous": 9, "failed_starts": 2, "blocked": [11] }',
);
final s = state.read()!;
expect(s.exe, "garage_stash.exe");
expect(s.current, 12);
expect(s.previous, 9);
expect(s.failedStarts, 2);
expect(s.blocked, [11]);
});
test("a half written file reads as null rather than throwing", () {
state.file.writeAsStringSync('{ "exe": "garage_stash.exe", "curr');
expect(state.read(), isNull);
state.file.writeAsStringSync("");
expect(state.read(), isNull);
state.file.writeAsStringSync("[1, 2]");
expect(state.read(), isNull);
});
test("missing and mistyped fields get sane defaults", () {
state.file.writeAsStringSync('{ "current": "12", "blocked": [11, "x", 11, 10.0], "failed_starts": null }');
final s = state.read()!;
expect(s.exe, isNull);
expect(s.current, 12);
expect(s.previous, isNull);
expect(s.failedStarts, 0);
expect(s.blocked, [11, 10]);
});
test("writing keeps the keys we dont know about", () {
state.file.writeAsStringSync('{ "exe": "a.exe", "current": 12, "app_id": "net.imbenji.stash", "later": {"x": 1} }');
expect(state.update((s) => s.failedStarts = 0), isTrue);
final j = jsonDecode(state.file.readAsStringSync()) as Map;
expect(j["app_id"], "net.imbenji.stash");
expect(j["later"], {"x": 1});
expect(j["exe"], "a.exe");
expect(j["current"], 12);
expect(j["previous"], isNull);
expect(j["failed_starts"], 0);
expect(j["blocked"], isEmpty);
});
test("the write is a replace, no temp file is left", () {
state.write(UpdateState(exe: "a.exe", current: 1));
state.write(UpdateState(exe: "a.exe", current: 2, previous: 1, blocked: [3]));
expect(dir.listSync().map((e) => e.uri.pathSegments.last), ["garage_updates.json"]);
final s = state.read()!;
expect(s.current, 2);
expect(s.previous, 1);
expect(s.blocked, [3]);
});
test("update wont write over a file it couldnt read", () {
state.file.writeAsStringSync('{ "exe": "garage_stash.exe", "curr');
expect(state.update((s) => s.failedStarts = 0), isFalse);
expect(state.file.readAsStringSync(), '{ "exe": "garage_stash.exe", "curr');
});
test("update can start a file that isnt there", () {
state = StateFile(File("${dir.path}/deeper/still/state.json"));
expect(state.update((s) => s.current = 5, createIfMissing: true), isTrue);
expect(state.read()!.current, 5);
});
group("the users file", () {
late UserStateFile mine;
setUp(() => mine = UserStateFile(File("${dir.path}/local/garage_updates.json")));
test("reads what the stub writes", () {
mine.file.parent.createSync();
mine.file.writeAsStringSync('{\n "failed_starts": 2,\n "blocked": [13, 13],\n "for_current": 14,\n "run_instead": null\n}\n');
final u = mine.read()!;
expect(u.failedStarts, 2);
expect(u.blocked, [13]);
expect(u.forCurrent, 14);
expect(u.runInstead, isNull);
});
test("missing, empty and half written all read as null", () {
expect(mine.read(), isNull);
mine.file.parent.createSync();
mine.file.writeAsStringSync("");
expect(mine.read(), isNull);
mine.file.writeAsStringSync('{ "failed_starts": 2, "bl');
expect(mine.read(), isNull);
// and isnt written over
expect(mine.update((u) => u.failedStarts = 0), isFalse);
expect(mine.file.readAsStringSync(), '{ "failed_starts": 2, "bl');
});
test("update doesnt start a file unless its told to", () {
expect(mine.update((u) => u.failedStarts = 0), isFalse);
expect(mine.file.existsSync(), isFalse);
expect(mine.update((u) => u.failedStarts = 1, createIfMissing: true), isTrue);
expect(mine.file.parent.listSync().map((e) => e.uri.pathSegments.last), ["garage_updates.json"]);
expect(jsonDecode(mine.file.readAsStringSync()), {
"failed_starts": 1,
"blocked": [],
"for_current": null,
"run_instead": null,
});
});
test("the count is only good for the current it was made against", () {
final u = UserState(failedStarts: 2, blocked: [13], forCurrent: 13, runInstead: 12);
u.settleFor(13);
expect(u.failedStarts, 2);
expect(u.runInstead, 12);
u.settleFor(14);
expect(u.failedStarts, 0);
expect(u.runInstead, isNull);
expect(u.forCurrent, 14);
expect(u.blocked, [13]);
});
});
test("a write that cant happen says false", () {
// a folder where the file should be
Directory(state.file.path).createSync();
expect(state.write(UpdateState(current: 1)), isFalse);
});
}
@@ -0,0 +1,164 @@
import "dart:io";
import "package:garage_updates/core.dart";
// A pretend windows install in a temp folder. The "stub" is a shell script
// with the stubs name: it writes down the arguments it was given, and for
// --garage-apply does the bookkeeping the real one would.
const _stubScript = r'''#!/bin/sh
dir="$(cd "$(dirname "$0")" && pwd)"
printf '%s\n' "$@" >> "$dir/stub-args.txt"
echo "--" >> "$dir/stub-args.txt"
if [ "$1" = "--garage-apply" ]; then
if [ -f "$dir/stub-exit" ]; then
exit "$(cat "$dir/stub-exit")"
fi
if [ ! -f "$dir/stub-lazy" ]; then
mkdir -p "$dir/app-$3"
cp "$2" "$dir/app-$3/unpacked-from.zip"
printf '{ "exe": "garage_stash.exe", "current": %s, "previous": 12, "failed_starts": 0, "blocked": [] }' "$3" > "$dir/garage_updates.json"
fi
fi
exit 0
''';
class FakeWindowsInstall {
FakeWindowsInstall._(this.tmp);
final Directory tmp;
Directory get root => Directory("${tmp.path}/Garage Stash");
Directory get versionFolder => Directory("${root.path}/app-12");
File get stub => File("${root.path}/garage_stash.exe");
File get exe => File("${versionFolder.path}/garage_stash.exe");
File get stateFile => File("${root.path}/garage_updates.json");
File get argsFile => File("${root.path}/stub-args.txt");
static FakeWindowsInstall create({String? state}) {
final f = FakeWindowsInstall._(Directory.systemTemp.createTempSync("gu_win_"));
f.versionFolder.createSync(recursive: true);
f.exe.writeAsStringSync("the real app, build 12");
File("${f.versionFolder.path}/stash-agent.exe").writeAsStringSync("the agent");
f.stub.writeAsStringSync(_stubScript);
Process.runSync("/bin/chmod", ["+x", f.stub.path]);
f.stateFile.writeAsStringSync(
state ?? '{ "exe": "garage_stash.exe", "current": 12, "previous": 9, "failed_starts": 1, "blocked": [11] }',
);
return f;
}
/// what LOCALAPPDATA is for an installer made by [installer]
Directory get local => Directory("${tmp.path}/Local");
File get userStateFile => File("${local.path}/Garage Stash/garage_updates.json");
/// `readOnly` is an install in Program Files. Nothing is chmodded, the
/// installer is just told it cant write, and [plainLaunch] behaves the same
WindowsInstaller installer({bool readOnly = false}) => WindowsInstaller(
root: root,
stub: stub,
runningFolderBuild: 12,
environment: {"LOCALAPPDATA": local.path},
rootWritable: () => !readOnly,
);
/// The stub being started with no flags, as far as the counting goes: the
/// same sums garage_stub.cpp does, in root when it can write there and in
/// the users own file when it cant. Returns the build it would start.
int plainLaunch({bool readOnly = false}) {
final state = StateFile(stateFile);
final s = state.read()!;
bool there(int? build) => build != null && Directory("${root.path}/app-$build").existsSync();
if (!readOnly) {
if (s.failedStarts >= 3 && there(s.previous)) {
if (!s.blocked.contains(s.current)) s.blocked.add(s.current!);
s.current = s.previous;
s.previous = null;
s.failedStarts = 0;
}
s.failedStarts++;
state.write(s);
return s.current!;
}
final mine = UserStateFile(userStateFile);
final u = mine.read() ?? UserState();
u.settleFor(s.current);
if (u.runInstead != null) {
if (u.runInstead != s.current && there(u.runInstead)) return u.runInstead!;
u.runInstead = null;
u.failedStarts = 0;
}
var run = s.current!;
if (u.failedStarts >= 3 && there(s.previous) && s.previous != s.current && !u.blocked.contains(s.previous)) {
if (!u.blocked.contains(s.current)) u.blocked.add(s.current!);
u.runInstead = s.previous;
u.failedStarts = 0;
run = s.previous!;
}
if (run == s.current) u.failedStarts++;
mine.write(u);
return run;
}
/// every run of the stub, as the list of arguments it got
List<List<String>> get runs {
if (!argsFile.existsSync()) return [];
final out = <List<String>>[];
var cur = <String>[];
for (final line in argsFile.readAsLinesSync()) {
if (line == "--") {
out.add(cur);
cur = <String>[];
} else {
cur.add(line);
}
}
return out;
}
void dispose() {
// a test may have made the root read only
Process.runSync("/bin/chmod", ["-R", "u+w", tmp.path]);
tmp.deleteSync(recursive: true);
}
}
/// A pretend mac app. `Foo.app/Contents/{Info.plist, MacOS/Foo}` with a
/// marker file so a test can tell which build is sitting where.
Directory makeApp(Directory parent, {String name = "Foo.app", String id = "net.imbenji.foo", required String marker}) {
final app = Directory("${parent.path}/$name");
Directory("${app.path}/Contents/MacOS").createSync(recursive: true);
Directory("${app.path}/Contents/Resources").createSync(recursive: true);
File("${app.path}/Contents/Info.plist").writeAsStringSync('''<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
<key>CFBundleExecutable</key>
<string>Foo</string>
<key>CFBundleIdentifier</key>
<string>$id</string>
</dict>
</plist>
''');
File("${app.path}/Contents/MacOS/Foo").writeAsStringSync("#!/bin/sh\necho $marker\n");
File("${app.path}/Contents/Resources/marker.txt").writeAsStringSync(marker);
return app;
}
String markerOf(Directory app) => File("${app.path}/Contents/Resources/marker.txt").readAsStringSync();
/// zips [app] the way a release would be, with the .app at the top
File zipApp(Directory app, File to) {
final res = Process.runSync("/usr/bin/ditto", ["-c", "-k", "--keepParent", app.path, to.path]);
if (res.exitCode != 0) throw StateError("ditto couldnt zip ${app.path}: ${res.stderr}");
return to;
}
@@ -0,0 +1,154 @@
import "dart:async";
import "dart:convert";
import "dart:io";
import "dart:typed_data";
import "package:crypto/crypto.dart";
import "package:garage_updates/core.dart";
/// A file server on loopback that can be told to misbehave.
class FakeServer {
FakeServer._(this._server, this.data);
final HttpServer _server;
Uint8List data;
/// "GET /blob bytes=100-" for every request, in order
final List<String> log = [];
/// send a plain 200 with the whole file whatever Range says
bool ignoreRange = false;
/// how many of the next downloads to cut dead, and after how many bytes
int cutsLeft = 0;
int cutAfter = 0;
/// the json `/v1/updates/<pid>` answers with, and the status it uses
Object? updateBody;
int updateStatus = 200;
/// a /blob request without this sig gets a 403, like an expired presign
String? wantSig;
int _sig = 0;
String get base => "http://127.0.0.1:${_server.port}";
static Future<FakeServer> start(List<int> data) async {
final s = await HttpServer.bind(InternetAddress.loopbackIPv4, 0);
final fake = FakeServer._(s, Uint8List.fromList(data));
s.listen(fake._handle);
return fake;
}
Future<void> close() => _server.close(force: true);
String get sha => sha256.convert(data).toString();
UpdateRelease release({int build = 13, String path = "/blob", String format = "zip", String? sha256}) {
return UpdateRelease(
label: "v$build",
build: build,
notes: "notes for $build",
asset: UpdateAsset(
url: "$base$path",
filename: "app.$format",
format: format,
size: data.length,
sha256: sha256 ?? sha,
),
);
}
Future<void> _handle(HttpRequest req) async {
final range = req.headers.value(HttpHeaders.rangeHeader);
log.add("${req.method} ${req.uri.path}${range == null ? "" : " $range"}");
if (req.uri.path.startsWith("/v1/updates/")) {
req.response.statusCode = updateStatus;
req.response.headers.contentType = ContentType.json;
final body = updateBody;
req.response.write(body is String ? body : jsonEncode(body));
await req.response.close();
return;
}
if (req.uri.path == "/hosted") {
// a fresh "presigned" url every time, the old ones stop working
wantSig = "s${++_sig}";
req.response.statusCode = HttpStatus.found;
req.response.headers.set(HttpHeaders.locationHeader, "/blob?sig=$wantSig");
await req.response.close();
return;
}
if (req.uri.path == "/gone") {
req.response.statusCode = HttpStatus.notFound;
await req.response.close();
return;
}
if (wantSig != null && req.uri.queryParameters["sig"] != wantSig) {
req.response.statusCode = HttpStatus.forbidden;
await req.response.close();
return;
}
var start = 0;
var status = "200 OK";
final extra = <String>[];
if (range != null && !ignoreRange) {
start = int.parse(RegExp(r"bytes=(\d+)-").firstMatch(range)!.group(1)!);
if (start >= data.length) {
req.response.statusCode = HttpStatus.requestedRangeNotSatisfiable;
await req.response.close();
return;
}
status = "206 Partial Content";
extra.add("Content-Range: bytes $start-${data.length - 1}/${data.length}");
}
final body = Uint8List.sublistView(data, start);
// written by hand on the raw socket so it can be dropped mid body
final socket = await req.response.detachSocket(writeHeaders: false);
socket.write("HTTP/1.1 $status\r\n"
"Content-Length: ${body.length}\r\n"
"${extra.map((h) => "$h\r\n").join()}"
"Connection: close\r\n\r\n");
if (cutsLeft > 0) {
cutsLeft--;
socket.add(Uint8List.sublistView(body, 0, cutAfter.clamp(0, body.length)));
await socket.flush();
socket.destroy();
return;
}
socket.add(body);
await socket.flush();
await socket.close();
}
}
/// some bytes that arent all the same
List<int> noise(int length, {int seed = 7}) {
var x = seed;
return List<int>.generate(length, (_) {
x = (x * 1103515245 + 12345) & 0x7fffffff;
return x & 0xff;
});
}
/// runs [body] and hands back everything it printed
Future<List<String>> printsOf(Future<void> Function() body) async {
final lines = <String>[];
await runZonedPrints(body, lines);
return lines;
}
Future<void> runZonedPrints(Future<void> Function() body, List<String> into) {
return runZoned(
body,
zoneSpecification: ZoneSpecification(print: (self, parent, zone, line) => into.add(line)),
);
}
+415
View File
@@ -0,0 +1,415 @@
import "dart:async";
import "package:flutter/foundation.dart";
import "package:flutter/widgets.dart";
import "package:flutter_test/flutter_test.dart";
import "package:garage_ui/garage_ui.dart" show LinearProgressIndicator;
import "package:garage_updates/garage_updates.dart";
// GarageUpdater.launch against a driver that does whatever the test says
class FakeDriver implements UpdateDriver {
FakeDriver({this.installed = true});
@override
bool installed;
@override
String? get notInstalledReason => installed ? null : "this isn't a release build";
@override
FutureOr<void> Function()? onBeforeRestart;
final calls = <String>[];
/// what check() answers. a Completer to answer late, an error to throw
Object? answer;
bool startsKeepFailing = false;
Object? downloadError;
Object? installError;
Completer<void>? downloadGate;
@override
Future<bool> noteStart() async {
calls.add("noteStart");
return startsKeepFailing;
}
@override
Future<UpdateInfo> check() async {
calls.add("check");
final a = answer;
if (a is Completer<UpdateInfo>) return a.future;
if (a is UpdateInfo) return a;
throw a ?? StateError("no answer set");
}
@override
Future<void> download(UpdateRelease release, {DownloadProgress? onProgress}) async {
calls.add("download ${release.build}");
onProgress?.call(50, 100);
await downloadGate?.future;
final e = downloadError;
if (e != null) throw e;
onProgress?.call(100, 100);
}
@override
Future<void> install(UpdateRelease release) async {
calls.add("install ${release.build}");
final e = installError;
if (e != null) throw e;
}
@override
Future<void> restart({List<String> args = const []}) async {
await onBeforeRestart?.call();
calls.add("restart ${args.join(" ")}".trim());
}
@override
Future<void> markHealthy() async => calls.add("markHealthy");
}
const _release = UpdateRelease(
label: "v13",
build: 13,
notes: "Fixed the thing",
asset: UpdateAsset(url: "http://x/app.zip", filename: "app.zip", format: "zip", size: 100, sha256: "aa"),
);
const _current = UpdateInfo(status: UpdateStatus.current);
const _available = UpdateInfo(status: UpdateStatus.available, latest: _release);
const _required = UpdateInfo(status: UpdateStatus.required, minimumBuild: 13, latest: _release);
// the updater leaves a 6 hourly timer running, as it should. flutter_test
// counts timers the moment the body returns, before any tearDown, so the
// tidying has to happen in here
void updaterTest(
String name,
Future<void> Function(WidgetTester t) body, {
TargetPlatform platform = TargetPlatform.macOS,
}) {
testWidgets(name, (t) async {
GarageUpdater.reset();
// a flutter test says its android unless told otherwise
debugDefaultTargetPlatformOverride = platform;
try {
await body(t);
} finally {
// take the splash down first, that schedules the markHealthy timer
await t.pumpWidget(const SizedBox());
await t.pump();
GarageUpdater.reset();
debugDefaultTargetPlatformOverride = null;
}
});
}
void main() {
// starts the updater the way launch() does, with the splash going to the
// tester instead of runApp
({Future<void> done, bool Function() finished, Widget? Function() splash}) start(
FakeDriver driver, {
UpdateMode mode = UpdateMode.silent,
List<String> args = const ["--route=/x"],
}) {
Widget? shown;
var finished = false;
final done = GarageUpdater.instance
.start(
args: args,
project: "proj_1",
build: 12,
label: "v12",
branding: const UpdaterBranding(name: "Garage Stash"),
mode: mode,
driver: driver,
show: (w) => shown = w,
)
.then((_) => finished = true);
return (done: done, finished: () => finished, splash: () => shown);
}
updaterTest("up to date: the splash shows, then the app carries on", (t) async {
final d = FakeDriver()..answer = _current;
final run = start(d);
await t.pump();
expect(run.splash(), isA<UpdateSplashApp>());
await t.pumpWidget(run.splash()!);
await t.pump();
expect(run.finished(), isTrue);
expect(find.text("Starting"), findsOneWidget);
expect(d.calls, ["noteStart", "check"]);
expect(GarageUpdater.instance.ready.value, isNull);
expect(GarageUpdater.instance.label, "v12");
});
updaterTest("no answer in 2 seconds: the app starts, and the late answer is dealt with behind it", (t) async {
final late = Completer<UpdateInfo>();
final d = FakeDriver()..answer = late;
final run = start(d);
await t.pump();
await t.pumpWidget(run.splash()!);
await t.pump(const Duration(milliseconds: 1900));
expect(run.finished(), isFalse);
expect(find.text("Checking for updates"), findsOneWidget);
await t.pump(const Duration(milliseconds: 200));
expect(run.finished(), isTrue);
expect(d.calls, ["noteStart", "check"]);
final heard = <UpdateInfo>[];
GarageUpdater.instance.readyStream.listen(heard.add);
// the server finally answers, the app is long since up
late.complete(_available);
await t.pump();
await t.pump();
expect(d.calls, ["noteStart", "check", "download 13"]);
expect(GarageUpdater.instance.ready.value, same(_available));
expect(heard, [_available]);
expect(GarageUpdater.instance.notes, "Fixed the thing");
// downloaded, not installed. thats the apps call now
expect(d.calls.where((c) => c.startsWith("install")), isEmpty);
});
updaterTest("a check that fails lets the app start", (t) async {
final d = FakeDriver()..answer = UpdateError("network", "Couldn't reach the update server");
final run = start(d);
await t.pump();
await t.pumpWidget(run.splash()!);
await t.pump();
expect(run.finished(), isTrue);
expect(find.text("Retry"), findsNothing);
});
updaterTest("silent + available: downloaded, installed and restarted behind the splash", (t) async {
final gate = Completer<void>();
final d = FakeDriver()
..answer = _available
..downloadGate = gate;
final stopped = <String>[];
GarageUpdater.instance.onBeforeRestart = () => stopped.add("agent stopped");
final run = start(d);
await t.pump();
await t.pumpWidget(run.splash()!);
await t.pump();
await t.pump();
expect(find.text("Downloading update"), findsOneWidget);
expect(t.widget<LinearProgressIndicator>(find.byType(LinearProgressIndicator)).value, 0.5);
expect(run.finished(), isFalse);
gate.complete();
await t.pump();
await t.pump();
expect(d.calls, ["noteStart", "check", "download 13", "install 13", "restart --route=/x"]);
expect(stopped, ["agent stopped"]);
});
updaterTest("silent + available that fails: the old build starts anyway", (t) async {
final d = FakeDriver()
..answer = _available
..installError = UpdateError("install_failed", "The update could not be installed (3)");
final run = start(d);
await t.pump();
await t.pumpWidget(run.splash()!);
await t.pump();
await t.pump();
expect(run.finished(), isTrue);
expect(find.text("Retry"), findsNothing);
expect(d.calls.where((c) => c.startsWith("restart")), isEmpty);
});
updaterTest("prompt + available: nothing is installed, ready fires, restartToUpdate applies it", (t) async {
final d = FakeDriver()..answer = _available;
final run = start(d, mode: UpdateMode.prompt);
await t.pump();
await t.pumpWidget(run.splash()!);
await t.pump();
await t.pump();
expect(run.finished(), isTrue);
expect(d.calls, ["noteStart", "check", "download 13"]);
expect(GarageUpdater.instance.ready.value?.latest?.build, 13);
await GarageUpdater.instance.restartToUpdate();
expect(d.calls, ["noteStart", "check", "download 13", "install 13", "restart --route=/x"]);
});
updaterTest("android never installs at launch unless it has to, its installer always asks", (t) async {
final d = FakeDriver()..answer = _available;
final run = start(d);
await t.pump();
await t.pumpWidget(run.splash()!);
await t.pump();
await t.pump();
expect(run.finished(), isTrue);
expect(d.calls, ["noteStart", "check", "download 13"]);
expect(GarageUpdater.instance.ready.value?.latest?.build, 13);
}, platform: TargetPlatform.android);
updaterTest("required: the app is kept out, a failure offers Retry, and Retry goes again", (t) async {
final d = FakeDriver()
..answer = _required
..downloadError = UpdateError("checksum_mismatch", "The download didn't match its checksum");
final run = start(d);
await t.pump();
await t.pumpWidget(run.splash()!);
await t.pump();
await t.pump();
expect(run.finished(), isFalse);
expect(find.text("The download didn't match its checksum"), findsOneWidget);
expect(find.text("Retry"), findsOneWidget);
// still out, however long its left
await t.pump(const Duration(minutes: 10));
expect(run.finished(), isFalse);
expect(d.calls.where((c) => c.startsWith("install")), isEmpty);
d.downloadError = null;
await t.tap(find.text("Retry"));
await t.pump();
await t.pump();
await t.pump();
expect(d.calls, [
"noteStart",
"check",
"download 13",
"check",
"download 13",
"install 13",
"restart --route=/x",
]);
// a real restart ends the process. the fake comes back, which is androids
// case: the system installer is up and the app still must not start
expect(run.finished(), isFalse);
expect(find.text("Install the update to continue."), findsOneWidget);
});
updaterTest("required is required in prompt mode too", (t) async {
final d = FakeDriver()..answer = _required;
final run = start(d, mode: UpdateMode.prompt);
await t.pump();
await t.pumpWidget(run.splash()!);
await t.pump();
await t.pump();
expect(d.calls, contains("install 13"));
expect(run.finished(), isFalse);
});
updaterTest("required with nothing installable says so and keeps the app out", (t) async {
final d = FakeDriver()..answer = const UpdateInfo(status: UpdateStatus.required, minimumBuild: 13);
final run = start(d);
await t.pump();
await t.pumpWidget(run.splash()!);
await t.pump();
expect(run.finished(), isFalse);
expect(find.text("Retry"), findsOneWidget);
expect(d.calls.where((c) => c.startsWith("download")), isEmpty);
});
updaterTest("not installed in the layout: no splash, no check, nothing", (t) async {
final d = FakeDriver(installed: false);
final run = start(d);
await t.pump();
expect(run.finished(), isTrue);
expect(run.splash(), isNull);
expect(d.calls, isEmpty);
// and the rest of the surface is safe to call
await GarageUpdater.instance.markHealthy();
await GarageUpdater.instance.restartToUpdate();
expect(await GarageUpdater.instance.checkNow(), isNull);
expect(d.calls, isEmpty);
expect(GarageUpdater.instance.ready.value, isNull);
expect(GarageUpdater.instance.notes, isNull);
});
updaterTest("a start that put the old build back restarts before anything else", (t) async {
final d = FakeDriver()
..startsKeepFailing = true
..answer = _current;
start(d);
await t.pump();
expect(d.calls.take(2), ["noteStart", "restart --route=/x"]);
});
updaterTest("markHealthy is called a few seconds after the host apps first frame", (t) async {
final d = FakeDriver()..answer = _current;
final run = start(d);
await t.pump();
await t.pumpWidget(run.splash()!);
await t.pump();
expect(run.finished(), isTrue);
// sat on the splash, the app hasnt drawn anything of its own yet
await t.pump(const Duration(seconds: 10));
expect(d.calls, isNot(contains("markHealthy")));
await t.pumpWidget(const SizedBox(key: Key("the host app")));
await t.pump(const Duration(seconds: 2));
expect(d.calls, isNot(contains("markHealthy")));
await t.pump(const Duration(seconds: 2));
expect(d.calls, contains("markHealthy"));
});
updaterTest("checks again every 6 hours while the app runs", (t) async {
final d = FakeDriver()..answer = _current;
final run = start(d);
await t.pump();
await t.pumpWidget(run.splash()!);
await t.pump();
await t.pumpWidget(const SizedBox());
expect(d.calls.where((c) => c == "check").length, 1);
await t.pump(const Duration(hours: 5, minutes: 59));
expect(d.calls.where((c) => c == "check").length, 1);
d.answer = _available;
await t.pump(const Duration(minutes: 2));
await t.pump();
expect(d.calls.where((c) => c == "check").length, 2);
expect(d.calls, contains("download 13"));
expect(GarageUpdater.instance.ready.value?.latest?.build, 13);
// the same build again in another 6 hours isnt fetched twice
await t.pump(const Duration(hours: 6, minutes: 1));
await t.pump();
expect(d.calls.where((c) => c == "download 13").length, 1);
});
updaterTest("launch twice is ignored the second time", (t) async {
final d = FakeDriver()..answer = _current;
final run = start(d);
await t.pump();
await t.pumpWidget(run.splash()!);
await t.pump();
final again = start(FakeDriver()..answer = _required);
await t.pump();
expect(again.finished(), isTrue);
expect(again.splash(), isNull);
});
}
@@ -0,0 +1,440 @@
import "dart:convert";
import "dart:io";
import "package:flutter_test/flutter_test.dart";
import "package:garage_updates/core.dart";
import "support/fake_install.dart";
UpdateRelease _release(int build, {String format = "zip"}) => UpdateRelease(
label: "v$build",
build: build,
asset: UpdateAsset(url: "http://x/app.$format", filename: "app.$format", format: format, size: 3, sha256: "aa"),
);
void main() {
late FakeWindowsInstall fake;
setUp(() => fake = FakeWindowsInstall.create());
tearDown(() => fake.dispose());
WindowsInstaller locate([String? exe]) {
final found = WindowsInstaller.locate(exe ?? fake.exe.path, environment: const {});
expect(found.reason, isNull);
return found.installer as WindowsInstaller;
}
File zipIn(Directory staging) {
staging.createSync(recursive: true);
return File("${staging.path}/update-13.zip")..writeAsStringSync("zip");
}
group("finding the install", () {
test("an exe inside app-<build> finds the root, the stub and the build", () {
final w = locate();
expect(w.root.path, fake.root.path);
expect(w.stub.path, fake.stub.path);
expect(w.runningFolderBuild, 12);
expect(w.rootWritable, isTrue);
expect(w.staging.path, "${fake.root.path}/staging");
expect(w.blockedBuilds(), [11]);
// the writable probe cleaned up after itself
expect(File("${fake.root.path}/.garage_updates_probe").existsSync(), isFalse);
});
test("a helper exe finds the stub by the name in the state file", () {
final w = locate("${fake.versionFolder.path}/stash-agent.exe");
expect(w.stub.path, fake.stub.path);
});
test("the stub is still found when the state file is half written", () {
fake.stateFile.writeAsStringSync('{ "exe": "garage_st');
final w = locate();
expect(w.stub.path, fake.stub.path);
expect(w.blockedBuilds(), isEmpty);
});
test("a folder that isnt app-<build> is not an install", () {
final dev = Directory("${fake.tmp.path}/build/windows/x64/runner/Release")..createSync(recursive: true);
final found = WindowsInstaller.locate("${dev.path}/garage_stash.exe");
expect(found.installer, isNull);
expect(found.reason, contains("app-<build>"));
});
test("app-<build> with no state file beside it is not an install", () {
fake.stateFile.deleteSync();
final found = WindowsInstaller.locate(fake.exe.path);
expect(found.installer, isNull);
expect(found.reason, contains("garage_updates.json"));
});
test("an old stub left in root by an update isnt taken for the stub", () {
// nothing to go on but whats in the folder: the state wont read and
// the stub isnt named after the exe that is asking
fake.stub.renameSync("${fake.root.path}/launcher.exe");
File("${fake.root.path}/launcher.exe.old").writeAsStringSync("the stub before this one");
File("${fake.root.path}/launcher.exe.old-412-99").writeAsStringSync("and one that wouldnt delete");
fake.stateFile.writeAsStringSync('{ "exe": "garage_st');
final w = locate("${fake.versionFolder.path}/stash-agent.exe");
expect(w.stub.path, "${fake.root.path}/launcher.exe");
});
test("no stub, not an install", () {
fake.stub.deleteSync();
final found = WindowsInstaller.locate(fake.exe.path);
expect(found.installer, isNull);
expect(found.reason, contains("stub"));
});
});
group("applying", () {
test("runs the stub directly when the root is writable", () async {
final w = locate();
final zip = zipIn(w.staging);
await w.apply(zip, _release(13), runningBuild: 12);
expect(fake.runs, [
["--garage-apply", zip.path, "13"],
]);
expect(Directory("${fake.root.path}/app-13").existsSync(), isTrue);
expect(w.state.read()!.current, 13);
// the zip is spent
expect(zip.existsSync(), isFalse);
});
test("a path with spaces reaches the stub as one argument", () async {
final w = locate();
// the root is "Garage Stash", so the zip path has a space in it allready
final zip = zipIn(w.staging);
expect(zip.path, contains(" "));
await w.apply(zip, _release(13), runningBuild: 12);
expect(fake.runs.single[1], zip.path);
});
test("a stub that exits non zero fails the install and keeps the zip", () async {
File("${fake.root.path}/stub-exit").writeAsStringSync("3");
final w = locate();
final zip = zipIn(w.staging);
await expectLater(
w.apply(zip, _release(13), runningBuild: 12),
throwsA(isA<UpdateError>().having((e) => e.code, "code", "install_failed")),
);
expect(zip.existsSync(), isTrue);
expect(w.state.read()!.current, 12);
});
test("a stub that says 0 without moving current is still a failure", () async {
File("${fake.root.path}/stub-lazy").writeAsStringSync("");
final w = locate();
await expectLater(
w.apply(zipIn(w.staging), _release(13), runningBuild: 12),
throwsA(isA<UpdateError>().having((e) => e.code, "code", "install_failed")),
);
});
test("anything but a zip is refused before the stub is run", () async {
final w = locate();
await expectLater(
w.apply(zipIn(w.staging), _release(13, format: "dmg"), runningBuild: 12),
throwsA(isA<UpdateError>().having((e) => e.code, "code", "format")),
);
expect(fake.runs, isEmpty);
});
});
group("a root we cant write to", () {
test("a read only root is noticed", () {
Process.runSync("/bin/chmod", ["555", fake.root.path]);
final w = locate();
expect(w.rootWritable, isFalse);
});
test("staging moves to LOCALAPPDATA, under app_id when the state has one", () {
final local = "${fake.tmp.path}/Local";
var w = WindowsInstaller(
root: fake.root,
stub: fake.stub,
runningFolderBuild: 12,
environment: {"LOCALAPPDATA": local},
rootWritable: () => false,
);
// no app_id in the file, so the folders name
expect(w.staging.path, "$local/Garage Stash/staging");
fake.stateFile.writeAsStringSync('{ "exe": "garage_stash.exe", "current": 12, "app_id": "net.imbenji.stash" }');
w = WindowsInstaller(
root: fake.root,
stub: fake.stub,
runningFolderBuild: 12,
environment: {"LOCALAPPDATA": local},
rootWritable: () => false,
);
expect(w.staging.path, "$local/net.imbenji.stash/staging");
});
test("the stub is run elevated, through powershell", () async {
String? ranExe;
List<String>? ranArgs;
final w = WindowsInstaller(
root: fake.root,
stub: fake.stub,
runningFolderBuild: 12,
environment: {"LOCALAPPDATA": "${fake.tmp.path}/Local"},
rootWritable: () => false,
run: (exe, args) async {
ranExe = exe;
ranArgs = args;
// the elevated stub did its job
fake.stateFile.writeAsStringSync(jsonEncode({"exe": "garage_stash.exe", "current": 13, "previous": 12}));
return ProcessResult(1, 0, "", "");
},
);
final zip = zipIn(w.staging);
await w.apply(zip, _release(13), runningBuild: 12);
expect(ranExe, "powershell");
expect(ranArgs!.sublist(0, ranArgs!.length - 1),
["-NoProfile", "-ExecutionPolicy", "Bypass", "-WindowStyle", "Hidden", "-Command"]);
final script = ranArgs!.last;
expect(script, contains("Start-Process -FilePath '${fake.stub.path}'"));
expect(script, contains("-Verb RunAs"));
expect(script, contains("-Wait"));
// the zip path has a space, so its quoted inside the argument list
expect(script, contains("-ArgumentList '--garage-apply \"${zip.path}\" 13'"));
expect(script, contains("exit \$p.ExitCode"));
// the stub itself was never run unelevated
expect(fake.runs, isEmpty);
});
test("a UAC prompt turned down is its own error", () async {
final w = WindowsInstaller(
root: fake.root,
stub: fake.stub,
runningFolderBuild: 12,
environment: const {},
rootWritable: () => false,
run: (exe, args) async => ProcessResult(1, kElevationRefused, "", "The operation was canceled by the user."),
);
await expectLater(
w.apply(zipIn(Directory("${fake.tmp.path}/st")), _release(13), runningBuild: 12),
throwsA(isA<UpdateError>().having((e) => e.code, "code", "elevation_refused")),
);
});
});
group("starts counted for the user", () {
const state13 = '{ "exe": "garage_stash.exe", "current": 13, "previous": 12, "failed_starts": 0, "blocked": [11] }';
Map userJson() => jsonDecode(fake.userStateFile.readAsStringSync()) as Map;
setUp(() {
Directory("${fake.root.path}/app-13").createSync();
fake.stateFile.writeAsStringSync(state13);
});
test("the count goes in the users file, root is left as it was", () {
final w = fake.installer(readOnly: true);
expect(w.userState!.file.path, fake.userStateFile.path);
expect(fake.plainLaunch(readOnly: true), 13);
expect(fake.plainLaunch(readOnly: true), 13);
expect(userJson(), {"failed_starts": 2, "blocked": [], "for_current": 13, "run_instead": null});
expect(fake.stateFile.readAsStringSync(), state13);
expect(w.startsBuild, 13);
expect(w.blockedBuilds(), [11]);
});
test("the users file goes under app_id when the state has one", () {
fake.stateFile.writeAsStringSync('{ "exe": "garage_stash.exe", "current": 13, "app_id": "net.imbenji.stash" }');
final w = fake.installer(readOnly: true);
expect(w.userState!.file.path, "${fake.local.path}/net.imbenji.stash/garage_updates.json");
// one that couldnt be a folder name is the same as none, as in the stub
fake.stateFile.writeAsStringSync('{ "exe": "garage_stash.exe", "current": 13, "app_id": "net:imbenji" }');
expect(w.userState!.file.path, fake.userStateFile.path);
});
test("markHealthy zeroes the users count and nothing else", () async {
final w = fake.installer(readOnly: true);
fake.plainLaunch(readOnly: true);
fake.plainLaunch(readOnly: true);
await w.markHealthy();
expect(userJson(), {"failed_starts": 0, "blocked": [], "for_current": 13, "run_instead": null});
expect(fake.stateFile.readAsStringSync(), state13);
expect(fake.local.listSync(recursive: true).whereType<File>().map((f) => f.path), [fake.userStateFile.path]);
});
test("three starts that never got healthy: blocked for the user, the previous build runs instead", () {
final w = fake.installer(readOnly: true);
for (var i = 0; i < 3; i++) {
expect(fake.plainLaunch(readOnly: true), 13);
}
expect(w.startsBuild, 13);
expect(fake.plainLaunch(readOnly: true), 12);
expect(userJson(), {
"failed_starts": 0,
"blocked": [13],
"for_current": 13,
"run_instead": 12,
});
// and it stays there
expect(fake.plainLaunch(readOnly: true), 12);
expect(w.startsBuild, 12);
expect(w.blockedBuilds(), [11, 13]);
// nobody else on the machine was moved
expect(fake.stateFile.readAsStringSync(), state13);
});
test("a build to run instead that has gone is not what we say is started", () {
fake.userStateFile.parent.createSync(recursive: true);
fake.userStateFile.writeAsStringSync('{ "failed_starts": 0, "blocked": [13], "for_current": 13, "run_instead": 10 }');
final w = fake.installer(readOnly: true);
expect(w.startsBuild, 13);
expect(fake.plainLaunch(readOnly: true), 13);
expect(userJson()["run_instead"], isNull);
});
test("an update going in starts the count again, what was blocked stays", () {
final w = fake.installer(readOnly: true);
for (var i = 0; i < 4; i++) {
fake.plainLaunch(readOnly: true);
}
expect(w.startsBuild, 12);
// the elevated apply
Directory("${fake.root.path}/app-14").createSync();
fake.stateFile.writeAsStringSync('{ "exe": "garage_stash.exe", "current": 14, "previous": 13, "failed_starts": 0, "blocked": [] }');
// before the stub has even been started again
expect(w.startsBuild, 14);
expect(w.blockedBuilds(), [13]);
expect(fake.plainLaunch(readOnly: true), 14);
expect(userJson(), {"failed_starts": 1, "blocked": [13], "for_current": 14, "run_instead": null});
});
test("a previous that allready failed the user is not gone back to", () {
fake.userStateFile.parent.createSync(recursive: true);
fake.userStateFile.writeAsStringSync('{ "failed_starts": 3, "blocked": [12], "for_current": 13, "run_instead": null }');
expect(fake.plainLaunch(readOnly: true), 13);
expect(userJson()["run_instead"], isNull);
expect(userJson()["blocked"], [12]);
});
test("a users file that is half written is read as none", () async {
fake.userStateFile.parent.createSync(recursive: true);
fake.userStateFile.writeAsStringSync('{ "failed_sta');
final w = fake.installer(readOnly: true);
expect(w.blockedBuilds(), [11]);
expect(w.startsBuild, 13);
await w.markHealthy();
expect(fake.userStateFile.readAsStringSync(), '{ "failed_sta');
});
test("a root that can be written never gets a users file", () async {
final w = fake.installer();
expect(fake.plainLaunch(), 13);
expect(fake.plainLaunch(), 13);
expect(w.state.read()!.failedStarts, 2);
expect(w.blockedBuilds(), [11]);
expect(w.startsBuild, 13);
await w.markHealthy();
expect(w.state.read()!.failedStarts, 0);
expect(fake.userStateFile.existsSync(), isFalse);
expect(fake.local.existsSync(), isFalse);
// and falling back there is still the root file changing
for (var i = 0; i < 3; i++) {
fake.plainLaunch();
}
expect(fake.plainLaunch(), 12);
final s = w.state.read()!;
expect(s.current, 12);
expect(s.blocked, [11, 13]);
expect(w.startsBuild, 12);
expect(fake.local.existsSync(), isFalse);
});
});
group("quoting", () {
test("windows arguments", () {
expect(windowsQuoteArg("--garage-apply"), "--garage-apply");
expect(windowsQuoteArg("13"), "13");
expect(windowsQuoteArg(""), '""');
expect(windowsQuoteArg(r"C:\Program Files\App\x.zip"), r'"C:\Program Files\App\x.zip"');
// a trailing backslash would otherwise eat the closing quote
expect(windowsQuoteArg(r"C:\My Apps\"), r'"C:\My Apps\\"');
expect(windowsQuoteArg(r'say "hi"'), r'"say \"hi\""');
expect(windowsQuoteArg(r'a\"b c'), r'"a\\\"b c"');
});
test("powershell strings", () {
expect(powershellQuote(r"C:\Users\O'Brien\app.exe"), r"'C:\Users\O''Brien\app.exe'");
expect(powershellQuote(r"$env:x `n"), r"'$env:x `n'");
});
test("the elevation script survives a quote in the path", () {
final args = elevationArgs(r"C:\Users\O'Brien\App\app.exe", ["--garage-apply", r"C:\Users\O'Brien\x.zip", "13"]);
expect(args.last, contains(r"-FilePath 'C:\Users\O''Brien\App\app.exe'"));
expect(args.last, contains(r"-ArgumentList '--garage-apply C:\Users\O''Brien\x.zip 13'"));
});
});
test("relaunch starts the stub with the apps own arguments", () async {
final w = locate();
await w.relaunch(["--route=/settings", "two words"]);
// its detached, give it a moment to run
for (var i = 0; i < 100 && fake.runs.isEmpty; i++) {
await Future<void>.delayed(const Duration(milliseconds: 50));
}
expect(fake.runs, [
["--route=/settings", "two words"],
]);
});
test("markHealthy zeroes failed_starts and nothing else", () async {
final w = locate();
await w.markHealthy();
final j = jsonDecode(fake.stateFile.readAsStringSync()) as Map;
expect(j["failed_starts"], 0);
expect(j["current"], 12);
expect(j["previous"], 9);
expect(j["blocked"], [11]);
expect(j["exe"], "garage_stash.exe");
});
test("markHealthy leaves a half written state file alone", () async {
fake.stateFile.writeAsStringSync('{ "exe": "garage_st');
await locate().markHealthy();
expect(fake.stateFile.readAsStringSync(), '{ "exe": "garage_st');
});
test("the stub counts starts on windows, not us", () async {
final w = locate();
expect(await w.noteStart(12), isFalse);
expect(w.state.read()!.failedStarts, 1);
});
}
+26
View File
@@ -0,0 +1,26 @@
# garage_updates on windows is no plugin code at all, only the stub. the
# pubspec says ffiPlugin so that flutter adds this folder to the host apps
# build, and what comes out is garage_stub.exe sat beside the app.
cmake_minimum_required(VERSION 3.14)
set(PROJECT_NAME "garage_updates")
project(${PROJECT_NAME} LANGUAGES CXX)
cmake_policy(VERSION 3.14...3.25)
# the host apps own icon, where flutter create puts it. an app that keeps it
# somewhere else sets GARAGE_STUB_ICON in its windows/CMakeLists.txt before
# generated_plugins.cmake is included
if(NOT GARAGE_STUB_ICON)
set(GARAGE_STUB_ICON "${CMAKE_SOURCE_DIR}/runner/resources/app_icon.ico")
endif()
add_subdirectory("stub")
# flutter installs everything in this list next to the app exe. its meant for
# dlls but its install(FILES), so an exe goes along just the same
set(garage_updates_bundled_libraries
"$<TARGET_FILE:garage_stub>"
PARENT_SCOPE
)
@@ -0,0 +1,71 @@
# the stub exe. in a folder of its own so the runtime switch below stays off
# everything else in the build.
#
# two things can be set before this is added:
# GARAGE_STUB_ICON an .ico for it. shortcuts point at the stub, so this
# is the icon people see
# GARAGE_STUB_OUT_DIR where the exe goes, for a build that has to know
cmake_minimum_required(VERSION 3.14)
# the stub sits on its own in <root>. the vc runtime dlls, if the app ships
# them at all, are a folder down where it cant see them. so its linked static.
# flutters project() runs before its cmake_policy(), which leaves /MD sat in
# the flags and MSVC_RUNTIME_LIBRARY ignored, so both ways are covered
foreach(_flags
CMAKE_CXX_FLAGS CMAKE_CXX_FLAGS_DEBUG CMAKE_CXX_FLAGS_PROFILE CMAKE_CXX_FLAGS_RELEASE
CMAKE_CXX_FLAGS_RELWITHDEBINFO CMAKE_CXX_FLAGS_MINSIZEREL)
if(DEFINED ${_flags})
string(REPLACE "/MDd" "/MTd" ${_flags} "${${_flags}}")
string(REPLACE "/MD" "/MT" ${_flags} "${${_flags}}")
endif()
endforeach()
set(_stub_sources "garage_stub.cpp" "garage_common.h")
if(MSVC)
# as a source so the linker merges it. through the .rc it would collide with
# the manifest the linker makes itself
list(APPEND _stub_sources "garage_stub.exe.manifest")
endif()
set(GARAGE_STUB_ICON_LINE "")
if(GARAGE_STUB_ICON AND EXISTS "${GARAGE_STUB_ICON}")
# forward slashes. a backslash inside an .rc string is an escape
file(TO_CMAKE_PATH "${GARAGE_STUB_ICON}" _stub_icon)
set(GARAGE_STUB_ICON_LINE "1 ICON \"${_stub_icon}\"")
else()
message(STATUS "garage_updates: no icon for the stub, it gets the plain windows one")
endif()
# with msvc and no icon there would be nothing in the .rc at all, so it stays out
if(GARAGE_STUB_ICON_LINE OR NOT MSVC)
set(GARAGE_STUB_MANIFEST_FILE "${CMAKE_CURRENT_SOURCE_DIR}/garage_stub.exe.manifest")
configure_file("garage_stub.rc.in" "${CMAKE_CURRENT_BINARY_DIR}/garage_stub.rc" @ONLY)
list(APPEND _stub_sources "${CMAKE_CURRENT_BINARY_DIR}/garage_stub.rc")
if(NOT MSVC)
set_property(SOURCE "${CMAKE_CURRENT_BINARY_DIR}/garage_stub.rc" APPEND PROPERTY
COMPILE_DEFINITIONS GARAGE_RC_MANIFEST)
endif()
endif()
add_executable(garage_stub WIN32 ${_stub_sources})
target_compile_features(garage_stub PRIVATE cxx_std_17)
target_compile_definitions(garage_stub PRIVATE UNICODE _UNICODE)
set_target_properties(garage_stub PROPERTIES
OUTPUT_NAME "garage_stub"
MSVC_RUNTIME_LIBRARY "MultiThreaded$<$<CONFIG:Debug>:Debug>")
if(MSVC)
# no APPLY_STANDARD_SETTINGS. thats /WX, and this has never been through msvc
target_compile_options(garage_stub PRIVATE /W4 /EHsc /utf-8)
endif()
if(MINGW)
# mingw only looks for wWinMain when its told to
target_link_options(garage_stub PRIVATE -municode "-Wl,--subsystem,windows")
endif()
target_link_libraries(garage_stub PRIVATE user32 shell32 advapi32)
if(GARAGE_STUB_OUT_DIR)
# the empty genex stops visual studio adding a Release\ on the end
set_target_properties(garage_stub PROPERTIES
RUNTIME_OUTPUT_DIRECTORY "${GARAGE_STUB_OUT_DIR}$<0:>")
endif()
+652
View File
@@ -0,0 +1,652 @@
// the bits the stub and the installer both need. header only and everything
// is inline, so whichever of the two doesnt call a function doesnt get told
// off about it.
//
// nothing in here logs. it leaves GetLastError alone for the caller to report.
#pragma once
#ifndef _WIN32_WINNT
#define _WIN32_WINNT 0x0A00
#endif
#ifndef NOMINMAX
#define NOMINMAX
#endif
#include <windows.h>
#include <string.h>
#include <string>
#include <vector>
namespace garage {
inline std::wstring widen(const std::string& s) {
if (s.empty()) return L"";
int n = MultiByteToWideChar(CP_UTF8, 0, s.data(), (int)s.size(), nullptr, 0);
if (n <= 0) return L"";
std::wstring w((size_t)n, L'\0');
MultiByteToWideChar(CP_UTF8, 0, s.data(), (int)s.size(), &w[0], n);
return w;
}
inline std::string narrow(const std::wstring& w) {
if (w.empty()) return "";
int n = WideCharToMultiByte(CP_UTF8, 0, w.data(), (int)w.size(), nullptr, 0, nullptr, nullptr);
if (n <= 0) return "";
std::string s((size_t)n, '\0');
WideCharToMultiByte(CP_UTF8, 0, w.data(), (int)w.size(), &s[0], n, nullptr, nullptr);
return s;
}
inline std::wstring num(long long v) {
return std::to_wstring(v);
}
// "5 Access is denied". winhttp keeps its own messages in its dll
inline std::wstring win_error(DWORD code) {
wchar_t buf[512];
DWORD flags = FORMAT_MESSAGE_FROM_SYSTEM | FORMAT_MESSAGE_IGNORE_INSERTS;
HMODULE from = nullptr;
if (code >= 12000 && code < 12200) {
from = GetModuleHandleW(L"winhttp.dll");
if (from) flags |= FORMAT_MESSAGE_FROM_HMODULE;
}
DWORD n = FormatMessageW(flags, from, code, 0, buf, ARRAYSIZE(buf), nullptr);
while (n > 0 && (buf[n - 1] == L'\r' || buf[n - 1] == L'\n' || buf[n - 1] == L' ' || buf[n - 1] == L'.')) n--;
std::wstring out = num(code);
if (n > 0) {
out += L" ";
out.append(buf, n);
}
return out;
}
// ---- paths ----
// only long ones get the prefix. with it on nothing is normalised any more,
// so short paths are better off without
inline std::wstring lp(const std::wstring& p) {
if (p.size() < 240) return p;
if (p.compare(0, 4, L"\\\\?\\") == 0) return p;
if (p.compare(0, 2, L"\\\\") == 0) return L"\\\\?\\UNC\\" + p.substr(2);
if (p.size() > 2 && p[1] == L':') return L"\\\\?\\" + p;
return p;
}
inline std::wstring join(const std::wstring& a, const std::wstring& b) {
if (a.empty()) return b;
wchar_t last = a[a.size() - 1];
if (last == L'\\' || last == L'/') return a + b;
return a + L"\\" + b;
}
inline std::wstring parent(const std::wstring& p) {
size_t at = p.find_last_of(L"\\/");
if (at == std::wstring::npos) return L"";
return p.substr(0, at);
}
inline std::wstring leaf(const std::wstring& p) {
size_t at = p.find_last_of(L"\\/");
if (at == std::wstring::npos) return p;
return p.substr(at + 1);
}
inline bool exists(const std::wstring& p) {
return GetFileAttributesW(lp(p).c_str()) != INVALID_FILE_ATTRIBUTES;
}
inline bool is_dir(const std::wstring& p) {
DWORD a = GetFileAttributesW(lp(p).c_str());
return a != INVALID_FILE_ATTRIBUTES && (a & FILE_ATTRIBUTE_DIRECTORY) != 0;
}
inline std::wstring absolute(const std::wstring& p) {
DWORD need = GetFullPathNameW(p.c_str(), 0, nullptr, nullptr);
if (need == 0) return p;
std::wstring out((size_t)need, L'\0');
DWORD got = GetFullPathNameW(p.c_str(), need, &out[0], nullptr);
if (got == 0 || got >= need) return p;
out.resize(got);
return out;
}
inline long long file_size(const std::wstring& p) {
WIN32_FILE_ATTRIBUTE_DATA info;
if (!GetFileAttributesExW(lp(p).c_str(), GetFileExInfoStandard, &info)) return -1;
return ((long long)info.nFileSizeHigh << 32) | (long long)info.nFileSizeLow;
}
inline bool same_text(const std::wstring& a, const std::wstring& b) {
return CompareStringOrdinal(a.data(), (int)a.size(), b.data(), (int)b.size(), TRUE) == CSTR_EQUAL;
}
inline bool starts_with(const std::wstring& s, const std::wstring& prefix) {
if (s.size() < prefix.size()) return false;
return CompareStringOrdinal(s.data(), (int)prefix.size(), prefix.data(), (int)prefix.size(), TRUE) == CSTR_EQUAL;
}
inline bool is_ascii(const std::wstring& s) {
for (size_t i = 0; i < s.size(); i++) {
if (s[i] > 126 || s[i] < 32) return false;
}
return true;
}
// deletes a folder and whats in it. keeps going past things it cant delete
// and hands back the first error, the caller says what to do about it
inline bool remove_tree(const std::wstring& dir, DWORD* firstError) {
bool clean = true;
WIN32_FIND_DATAW fd;
HANDLE find = FindFirstFileW(lp(join(dir, L"*")).c_str(), &fd);
if (find != INVALID_HANDLE_VALUE) {
do {
std::wstring name = fd.cFileName;
if (name == L"." || name == L"..") continue;
std::wstring full = join(dir, name);
bool isDir = (fd.dwFileAttributes & FILE_ATTRIBUTE_DIRECTORY) != 0;
bool isLink = (fd.dwFileAttributes & FILE_ATTRIBUTE_REPARSE_POINT) != 0;
if (isDir && !isLink) {
if (!remove_tree(full, firstError)) clean = false;
continue;
}
if (fd.dwFileAttributes & FILE_ATTRIBUTE_READONLY) {
SetFileAttributesW(lp(full).c_str(), fd.dwFileAttributes & ~(DWORD)FILE_ATTRIBUTE_READONLY);
}
// a junction is taken away as a folder, never walked in to
BOOL gone = isDir ? RemoveDirectoryW(lp(full).c_str()) : DeleteFileW(lp(full).c_str());
if (!gone) {
if (firstError && *firstError == 0) *firstError = GetLastError();
clean = false;
}
} while (FindNextFileW(find, &fd));
FindClose(find);
}
if (!RemoveDirectoryW(lp(dir).c_str())) {
DWORD err = GetLastError();
if (err != ERROR_FILE_NOT_FOUND && err != ERROR_PATH_NOT_FOUND) {
if (firstError && *firstError == 0) *firstError = err;
clean = false;
}
}
return clean;
}
inline bool read_file(const std::wstring& path, std::string& out, size_t cap) {
out.clear();
HANDLE h = INVALID_HANDLE_VALUE;
// the other side may be half way through swapping it
for (int i = 0; i < 10; i++) {
h = CreateFileW(lp(path).c_str(), GENERIC_READ,
FILE_SHARE_READ | FILE_SHARE_WRITE | FILE_SHARE_DELETE, nullptr,
OPEN_EXISTING, FILE_ATTRIBUTE_NORMAL, nullptr);
if (h != INVALID_HANDLE_VALUE) break;
if (GetLastError() != ERROR_SHARING_VIOLATION) return false;
Sleep(20);
}
if (h == INVALID_HANDLE_VALUE) return false;
char chunk[4096];
DWORD got = 0;
bool ok = true;
for (;;) {
if (!ReadFile(h, chunk, sizeof(chunk), &got, nullptr)) { ok = false; break; }
if (got == 0) break;
out.append(chunk, got);
if (out.size() > cap) break;
}
DWORD err = GetLastError();
CloseHandle(h);
SetLastError(err);
return ok;
}
// temp file beside it, then swapped in. a reader sees the old one or the new
// one and never half of either
inline bool write_atomic(const std::wstring& path, const std::string& bytes) {
std::wstring tmp = path + L".tmp" + num((long long)GetCurrentProcessId());
HANDLE h = CreateFileW(lp(tmp).c_str(), GENERIC_WRITE, 0, nullptr, CREATE_ALWAYS,
FILE_ATTRIBUTE_NORMAL, nullptr);
if (h == INVALID_HANDLE_VALUE) return false;
DWORD wrote = 0;
bool ok = WriteFile(h, bytes.data(), (DWORD)bytes.size(), &wrote, nullptr) && wrote == (DWORD)bytes.size();
if (ok) FlushFileBuffers(h);
DWORD err = GetLastError();
CloseHandle(h);
if (!ok) {
DeleteFileW(lp(tmp).c_str());
SetLastError(err);
return false;
}
for (int i = 0; i < 20; i++) {
if (MoveFileExW(lp(tmp).c_str(), lp(path).c_str(), MOVEFILE_REPLACE_EXISTING | MOVEFILE_WRITE_THROUGH)) {
return true;
}
err = GetLastError();
// somebody has it open to read. they wont for long
if (err != ERROR_SHARING_VIOLATION && err != ERROR_ACCESS_DENIED) break;
Sleep(25);
}
DeleteFileW(lp(tmp).c_str());
SetLastError(err);
return false;
}
// ---- json ----
// small, but a real parser. objects, arrays, strings, whole numbers, the
// three words. a number with a fraction keeps the part before the dot.
struct JVal {
enum Kind { Null, Bool, Num, Str, Arr, Obj };
Kind kind = Null;
bool b = false;
long long n = 0;
std::string s;
std::vector<std::string> keys;
std::vector<JVal> items;
const JVal* get(const char* key) const {
if (kind != Obj) return nullptr;
for (size_t i = 0; i < keys.size(); i++) {
if (keys[i] == key) return &items[i];
}
return nullptr;
}
std::string str(const char* key) const {
const JVal* v = get(key);
return v && v->kind == Str ? v->s : std::string();
}
long long number(const char* key, long long fallback) const {
const JVal* v = get(key);
return v && v->kind == Num ? v->n : fallback;
}
};
struct JParser {
const char* p;
const char* end;
int depth;
};
inline void j_ws(JParser& j) {
while (j.p < j.end && (*j.p == ' ' || *j.p == '\t' || *j.p == '\r' || *j.p == '\n')) j.p++;
}
inline void j_utf8(std::string& out, unsigned long cp) {
if (cp < 0x80) {
out += (char)cp;
} else if (cp < 0x800) {
out += (char)(0xC0 | (cp >> 6));
out += (char)(0x80 | (cp & 0x3F));
} else if (cp < 0x10000) {
out += (char)(0xE0 | (cp >> 12));
out += (char)(0x80 | ((cp >> 6) & 0x3F));
out += (char)(0x80 | (cp & 0x3F));
} else {
out += (char)(0xF0 | (cp >> 18));
out += (char)(0x80 | ((cp >> 12) & 0x3F));
out += (char)(0x80 | ((cp >> 6) & 0x3F));
out += (char)(0x80 | (cp & 0x3F));
}
}
inline bool j_hex4(JParser& j, unsigned long& out) {
if (j.end - j.p < 4) return false;
out = 0;
for (int i = 0; i < 4; i++) {
char c = *j.p++;
out <<= 4;
if (c >= '0' && c <= '9') out |= (unsigned long)(c - '0');
else if (c >= 'a' && c <= 'f') out |= (unsigned long)(c - 'a' + 10);
else if (c >= 'A' && c <= 'F') out |= (unsigned long)(c - 'A' + 10);
else return false;
}
return true;
}
inline bool j_string(JParser& j, std::string& out) {
if (j.p >= j.end || *j.p != '"') return false;
j.p++;
while (j.p < j.end) {
char c = *j.p++;
if (c == '"') return true;
if (c != '\\') { out += c; continue; }
if (j.p >= j.end) return false;
char e = *j.p++;
switch (e) {
case 'n': out += '\n'; break;
case 't': out += '\t'; break;
case 'r': out += '\r'; break;
case 'b': out += '\b'; break;
case 'f': out += '\f'; break;
case 'u': {
unsigned long cp = 0;
if (!j_hex4(j, cp)) return false;
// two of them make one character above the bmp
if (cp >= 0xD800 && cp < 0xDC00 && j.end - j.p >= 6 && j.p[0] == '\\' && j.p[1] == 'u') {
JParser look = j;
look.p += 2;
unsigned long low = 0;
if (j_hex4(look, low) && low >= 0xDC00 && low < 0xE000) {
cp = 0x10000 + ((cp - 0xD800) << 10) + (low - 0xDC00);
j.p = look.p;
}
}
j_utf8(out, cp);
break;
}
default: out += e; break;
}
}
return false;
}
inline bool j_word(JParser& j, const char* word) {
size_t n = strlen(word);
if ((size_t)(j.end - j.p) < n || strncmp(j.p, word, n) != 0) return false;
j.p += n;
return true;
}
inline bool j_value(JParser& j, JVal& out) {
j_ws(j);
if (j.p >= j.end) return false;
char c = *j.p;
if (c == '"') {
out.kind = JVal::Str;
return j_string(j, out.s);
}
if (c == '{' || c == '[') {
bool isObj = c == '{';
char close = isObj ? '}' : ']';
out.kind = isObj ? JVal::Obj : JVal::Arr;
if (++j.depth > 32) return false;
j.p++;
j_ws(j);
if (j.p < j.end && *j.p == close) { j.p++; j.depth--; return true; }
for (;;) {
if (isObj) {
j_ws(j);
std::string key;
if (!j_string(j, key)) return false;
j_ws(j);
if (j.p >= j.end || *j.p != ':') return false;
j.p++;
out.keys.push_back(key);
}
out.items.push_back(JVal());
if (!j_value(j, out.items.back())) return false;
j_ws(j);
if (j.p >= j.end) return false;
if (*j.p == ',') { j.p++; continue; }
if (*j.p == close) { j.p++; j.depth--; return true; }
return false;
}
}
if (c == '-' || (c >= '0' && c <= '9')) {
bool neg = c == '-';
if (neg) j.p++;
if (j.p >= j.end || *j.p < '0' || *j.p > '9') return false;
long long v = 0;
while (j.p < j.end && *j.p >= '0' && *j.p <= '9') {
if (v < 900000000000000000LL) v = v * 10 + (*j.p - '0');
j.p++;
}
// whatever comes after the whole part is stepped over
while (j.p < j.end && (*j.p == '.' || *j.p == 'e' || *j.p == 'E' || *j.p == '+' || *j.p == '-' ||
(*j.p >= '0' && *j.p <= '9'))) {
j.p++;
}
out.kind = JVal::Num;
out.n = neg ? -v : v;
return true;
}
if (j_word(j, "true")) { out.kind = JVal::Bool; out.b = true; return true; }
if (j_word(j, "false")) { out.kind = JVal::Bool; out.b = false; return true; }
if (j_word(j, "null")) { out.kind = JVal::Null; return true; }
return false;
}
inline bool json_parse(const std::string& text, JVal& out) {
JParser j;
j.p = text.data();
j.end = text.data() + text.size();
j.depth = 0;
// some editors put a bom on the front
if (text.size() >= 3 && (unsigned char)text[0] == 0xEF && (unsigned char)text[1] == 0xBB &&
(unsigned char)text[2] == 0xBF) {
j.p += 3;
}
if (!j_value(j, out)) return false;
j_ws(j);
return j.p == j.end;
}
inline std::string json_quote(const std::string& s) {
static const char hex[] = "0123456789abcdef";
std::string out = "\"";
for (size_t i = 0; i < s.size(); i++) {
unsigned char c = (unsigned char)s[i];
if (c == '"' || c == '\\') {
out += '\\';
out += (char)c;
} else if (c < 0x20) {
out += "\\u00";
out += hex[c >> 4];
out += hex[c & 15];
} else {
out += (char)c;
}
}
out += '"';
return out;
}
inline std::string json_print(const JVal& v) {
switch (v.kind) {
case JVal::Null: return "null";
case JVal::Bool: return v.b ? "true" : "false";
case JVal::Num: return std::to_string(v.n);
case JVal::Str: return json_quote(v.s);
default: break;
}
bool isObj = v.kind == JVal::Obj;
std::string out = isObj ? "{" : "[";
for (size_t i = 0; i < v.items.size(); i++) {
if (i > 0) out += ", ";
if (isObj) out += json_quote(v.keys[i]) + ": ";
out += json_print(v.items[i]);
}
out += isObj ? "}" : "]";
return out;
}
// ---- garage_updates.json ----
struct State {
std::wstring exe;
long long current = -1; // -1 is "there isnt one"
long long previous = -1;
long long failedStarts = 0;
std::vector<long long> blocked;
// anything else thats in the file (the dart side keeps app_id in there).
// not ours, so it goes back out the way it came in
std::vector<std::string> extraKeys;
std::vector<JVal> extraVals;
std::wstring extra(const char* key) const {
for (size_t i = 0; i < extraKeys.size(); i++) {
if (extraKeys[i] == key && extraVals[i].kind == JVal::Str) return widen(extraVals[i].s);
}
return L"";
}
void set_extra(const char* key, const std::wstring& value) {
JVal v;
v.kind = JVal::Str;
v.s = narrow(value);
for (size_t i = 0; i < extraKeys.size(); i++) {
if (extraKeys[i] == key) { extraVals[i] = v; return; }
}
extraKeys.push_back(key);
extraVals.push_back(v);
}
bool is_blocked(long long build) const {
for (size_t i = 0; i < blocked.size(); i++) {
if (blocked[i] == build) return true;
}
return false;
}
};
inline bool parse_state(const std::string& text, State& st) {
JVal root;
if (!json_parse(text, root) || root.kind != JVal::Obj) return false;
st = State();
st.exe = widen(root.str("exe"));
st.current = root.number("current", -1);
st.previous = root.number("previous", -1);
st.failedStarts = root.number("failed_starts", 0);
if (st.failedStarts < 0) st.failedStarts = 0;
const JVal* blocked = root.get("blocked");
if (blocked && blocked->kind == JVal::Arr) {
for (size_t i = 0; i < blocked->items.size(); i++) {
if (blocked->items[i].kind == JVal::Num) st.blocked.push_back(blocked->items[i].n);
}
}
for (size_t i = 0; i < root.keys.size(); i++) {
const std::string& k = root.keys[i];
if (k == "exe" || k == "current" || k == "previous" || k == "failed_starts" || k == "blocked") continue;
st.extraKeys.push_back(k);
st.extraVals.push_back(root.items[i]);
}
return true;
}
inline std::string print_build(long long build) {
return build > 0 ? std::to_string(build) : std::string("null");
}
inline std::string print_state(const State& st) {
std::string out = "{\n";
out += " \"exe\": " + json_quote(narrow(st.exe)) + ",\n";
out += " \"current\": " + print_build(st.current) + ",\n";
out += " \"previous\": " + print_build(st.previous) + ",\n";
out += " \"failed_starts\": " + std::to_string(st.failedStarts) + ",\n";
out += " \"blocked\": [";
for (size_t i = 0; i < st.blocked.size(); i++) {
if (i > 0) out += ", ";
out += std::to_string(st.blocked[i]);
}
out += "]";
for (size_t i = 0; i < st.extraKeys.size(); i++) {
out += ",\n " + json_quote(st.extraKeys[i]) + ": " + json_print(st.extraVals[i]);
}
out += "\n}\n";
return out;
}
inline std::wstring state_path(const std::wstring& root) {
return join(root, L"garage_updates.json");
}
inline std::wstring version_dir(const std::wstring& root, long long build) {
return join(root, L"app-" + num(build));
}
// "app-12" and nothing else. a half unpacked folder has a different name on
// purpose so it never gets past this
inline bool parse_version_name(const std::wstring& name, long long& build) {
if (name.size() < 5 || name.size() > 4 + 17) return false;
if (name.compare(0, 4, L"app-") != 0) return false;
long long v = 0;
for (size_t i = 4; i < name.size(); i++) {
if (name[i] < L'0' || name[i] > L'9') return false;
v = v * 10 + (name[i] - L'0');
}
if (v <= 0) return false;
build = v;
return true;
}
inline std::vector<long long> list_versions(const std::wstring& root) {
std::vector<long long> out;
WIN32_FIND_DATAW fd;
HANDLE find = FindFirstFileW(lp(join(root, L"app-*")).c_str(), &fd);
if (find == INVALID_HANDLE_VALUE) return out;
do {
long long build = 0;
if ((fd.dwFileAttributes & FILE_ATTRIBUTE_DIRECTORY) && parse_version_name(fd.cFileName, build)) {
out.push_back(build);
}
} while (FindNextFileW(find, &fd));
FindClose(find);
return out;
}
// ---- processes ----
// one argument, quoted so that CommandLineToArgvW on the other end gives
// back exactly this
inline std::wstring quote_arg(const std::wstring& arg) {
if (!arg.empty() && arg.find_first_of(L" \t\"") == std::wstring::npos) return arg;
std::wstring out = L"\"";
size_t slashes = 0;
for (size_t i = 0; i < arg.size(); i++) {
wchar_t c = arg[i];
if (c == L'\\') {
slashes++;
continue;
}
if (c == L'"') {
out.append(slashes * 2 + 1, L'\\');
} else {
out.append(slashes, L'\\');
}
slashes = 0;
out += c;
}
// the ones at the very end sit in front of our closing quote
out.append(slashes * 2, L'\\');
out += L"\"";
return out;
}
// runs something with no window and waits for it. `output` (may be null) gets
// its stdout and stderr and has to be an inheritable handle
inline bool run_wait(const std::wstring& exe, const std::wstring& args, const std::wstring& cwd,
HANDLE output, DWORD& exitCode) {
std::wstring cmd = quote_arg(exe);
if (!args.empty()) cmd += L" " + args;
STARTUPINFOW si = {};
si.cb = sizeof(si);
if (output) {
si.dwFlags |= STARTF_USESTDHANDLES;
si.hStdOutput = output;
si.hStdError = output;
}
PROCESS_INFORMATION pi = {};
if (!CreateProcessW(exe.c_str(), &cmd[0], nullptr, nullptr, output ? TRUE : FALSE,
CREATE_NO_WINDOW, nullptr, cwd.empty() ? nullptr : cwd.c_str(), &si, &pi)) {
return false;
}
WaitForSingleObject(pi.hProcess, INFINITE);
exitCode = 1;
GetExitCodeProcess(pi.hProcess, &exitCode);
CloseHandle(pi.hThread);
CloseHandle(pi.hProcess);
return true;
}
} // namespace garage
File diff suppressed because it is too large Load Diff
@@ -0,0 +1,21 @@
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<assembly xmlns="urn:schemas-microsoft-com:asm.v1" manifestVersion="1.0">
<trustInfo xmlns="urn:schemas-microsoft-com:asm.v3">
<security>
<requestedPrivileges>
<requestedExecutionLevel level="asInvoker" uiAccess="false"/>
</requestedPrivileges>
</security>
</trustInfo>
<compatibility xmlns="urn:schemas-microsoft-com:compatibility.v1">
<application>
<supportedOS Id="{8e0f7a12-bfb3-4fe8-b9a5-48fd50a15a9a}"/>
</application>
</compatibility>
<application xmlns="urn:schemas-microsoft-com:asm.v3">
<windowsSettings>
<dpiAwareness xmlns="http://schemas.microsoft.com/SMI/2016/WindowsSettings">PerMonitorV2</dpiAwareness>
<longPathAware xmlns="http://schemas.microsoft.com/SMI/2016/WindowsSettings">true</longPathAware>
</windowsSettings>
</application>
</assembly>
@@ -0,0 +1,9 @@
// the stub is what the shortcuts point at, so it wears the apps icon
#pragma code_page(65001)
@GARAGE_STUB_ICON_LINE@
// msvc gets the manifest handed to the linker instead, two of them collide
#ifdef GARAGE_RC_MANIFEST
1 24 "@GARAGE_STUB_MANIFEST_FILE@"
#endif
@@ -0,0 +1,114 @@
# the first-time installer for an app that uses garage_updates. built once by
# the developer, per app:
#
# cmake -S . -B build -A x64 -DGARAGE_APP_NAME="Garage Stash" -DGARAGE_APP_ID=net.imbenji.stash
# -DGARAGE_PROJECT_ID=<project id> -DGARAGE_EXE_NAME=garage_stash.exe -DGARAGE_ICON=C:/.../app_icon.ico
# cmake --build build --config Release
#
# and out comes "<AppName>-Setup.exe" with the stub inside it. build_installer.bat
# does the same with shorter flags.
cmake_minimum_required(VERSION 3.15)
project(garage_installer LANGUAGES CXX)
# static runtime, its handed to people who have nothing installed yet
set(CMAKE_MSVC_RUNTIME_LIBRARY "MultiThreaded$<$<CONFIG:Debug>:Debug>")
set(GARAGE_APP_NAME "" CACHE STRING "The apps name as people see it")
set(GARAGE_APP_ID "" CACHE STRING "A stable id, e.g. net.imbenji.stash. Names the uninstall entry")
set(GARAGE_PROJECT_ID "" CACHE STRING "The Garage project the releases are published on")
set(GARAGE_EXE_NAME "" CACHE STRING "The apps exe inside a build, e.g. garage_stash.exe")
set(GARAGE_API_BASE "https://pay.imbenji.net/api" CACHE STRING "Where the update check goes")
set(GARAGE_PUBLISHER "" CACHE STRING "Shown in Installed apps. Optional")
set(GARAGE_ICON "" CACHE FILEPATH "An .ico for the installer, the stub and the shortcuts. Optional")
set(GARAGE_DEFAULT_LOCATION "me" CACHE STRING "me (LocalAppData) or everyone (Program Files)")
option(GARAGE_SHOW_CHOICE "Ask just me / everyone. Off goes with the default without asking" ON)
option(GARAGE_DESKTOP_SHORTCUT "A desktop shortcut as well as the start menu one" OFF)
foreach(_needed GARAGE_APP_NAME GARAGE_APP_ID GARAGE_PROJECT_ID GARAGE_EXE_NAME)
if("${${_needed}}" STREQUAL "")
message(FATAL_ERROR "${_needed} has to be set, e.g. -D${_needed}=...")
endif()
endforeach()
if(NOT GARAGE_EXE_NAME MATCHES "\\.exe$")
message(FATAL_ERROR "GARAGE_EXE_NAME is the file name with .exe on it, got \"${GARAGE_EXE_NAME}\"")
endif()
if(GARAGE_APP_ID MATCHES "[\\\\/:*?\"<>| ]")
message(FATAL_ERROR "GARAGE_APP_ID ends up as a folder and a registry key, keep it to letters, digits, dots and dashes")
endif()
if(NOT GARAGE_DEFAULT_LOCATION MATCHES "^(me|everyone)$")
message(FATAL_ERROR "GARAGE_DEFAULT_LOCATION is me or everyone, got \"${GARAGE_DEFAULT_LOCATION}\"")
endif()
if(GARAGE_ICON AND NOT EXISTS "${GARAGE_ICON}")
message(FATAL_ERROR "GARAGE_ICON: theres no ${GARAGE_ICON}")
endif()
# these land inside L"..." in a header
foreach(_text GARAGE_APP_NAME GARAGE_APP_ID GARAGE_PROJECT_ID GARAGE_EXE_NAME GARAGE_API_BASE GARAGE_PUBLISHER)
string(REPLACE "\\" "\\\\" ${_text}_C "${${_text}}")
string(REPLACE "\"" "\\\"" ${_text}_C "${${_text}_C}")
endforeach()
# no slash on the end, the code puts its own on
string(REGEX REPLACE "/+$" "" GARAGE_API_BASE_C "${GARAGE_API_BASE_C}")
set(GARAGE_DEFAULT_EVERYONE_C 0)
if(GARAGE_DEFAULT_LOCATION STREQUAL "everyone")
set(GARAGE_DEFAULT_EVERYONE_C 1)
endif()
set(GARAGE_SHOW_CHOICE_C 0)
if(GARAGE_SHOW_CHOICE)
set(GARAGE_SHOW_CHOICE_C 1)
endif()
set(GARAGE_DESKTOP_SHORTCUT_C 0)
if(GARAGE_DESKTOP_SHORTCUT)
set(GARAGE_DESKTOP_SHORTCUT_C 1)
endif()
set(_generated "${CMAKE_CURRENT_BINARY_DIR}/generated")
configure_file("installer_config.h.in" "${_generated}/installer_config.h" @ONLY)
# the stub is the plugins one, built here with this apps icon on it and put
# somewhere the .rc can name
set(_stub_dir "${CMAKE_CURRENT_SOURCE_DIR}/../windows/stub")
set(GARAGE_STUB_ICON "${GARAGE_ICON}")
set(GARAGE_STUB_OUT_DIR "${CMAKE_CURRENT_BINARY_DIR}/stub_out")
add_subdirectory("${_stub_dir}" "${CMAKE_CURRENT_BINARY_DIR}/stub")
set(GARAGE_STUB_FILE "${GARAGE_STUB_OUT_DIR}/garage_stub.exe")
set(GARAGE_ICON_LINE "")
if(GARAGE_ICON)
file(TO_CMAKE_PATH "${GARAGE_ICON}" _icon)
set(GARAGE_ICON_LINE "1 ICON \"${_icon}\"")
endif()
set(GARAGE_MANIFEST_FILE "${CMAKE_CURRENT_SOURCE_DIR}/installer.exe.manifest")
configure_file("installer.rc.in" "${_generated}/installer.rc" @ONLY)
set(_sources "installer.cpp" "${_generated}/installer_config.h" "${_generated}/installer.rc")
if(MSVC)
list(APPEND _sources "installer.exe.manifest")
endif()
add_executable(garage_installer WIN32 ${_sources})
target_compile_features(garage_installer PRIVATE cxx_std_17)
target_compile_definitions(garage_installer PRIVATE UNICODE _UNICODE)
target_include_directories(garage_installer PRIVATE "${_generated}" "${_stub_dir}")
if(MSVC)
target_compile_options(garage_installer PRIVATE /W4 /EHsc /utf-8)
else()
# not msvc, so nothing merges the manifest for us. it goes in through the .rc
set_property(SOURCE "${_generated}/installer.rc" APPEND PROPERTY COMPILE_DEFINITIONS GARAGE_RC_MANIFEST)
endif()
if(MINGW)
target_link_options(garage_installer PRIVATE -municode "-Wl,--subsystem,windows")
endif()
target_link_libraries(garage_installer PRIVATE
user32 shell32 advapi32 ole32 uuid comctl32 winhttp bcrypt)
# the .rc pulls the stub in as a file, which cmake cant see for itself
add_dependencies(garage_installer garage_stub)
set_property(SOURCE "${_generated}/installer.rc" APPEND PROPERTY OBJECT_DEPENDS "${GARAGE_STUB_FILE}")
# the name with whatever a file name cant have taken out
string(REGEX REPLACE "[\\\\/:*?\"<>|]" "" _file_name "${GARAGE_APP_NAME}")
set_target_properties(garage_installer PROPERTIES OUTPUT_NAME "${_file_name}-Setup")
@@ -0,0 +1,82 @@
@echo off
setlocal
rem builds "<AppName>-Setup.exe" for one app. needs cmake and visual studio's
rem c++ tools, the same things flutter build windows needs.
rem
rem build_installer.bat --name "Garage Stash" --id net.imbenji.stash ^
rem --project <garage project id> --exe garage_stash.exe ^
rem --icon C:\path\app_icon.ico
rem
rem optional:
rem --api <url> where the update check goes (default pay.imbenji.net/api)
rem --publisher "<name>" shown in Installed apps
rem --default me^|everyone which one is ticked to begin with (default me)
rem --hide-choice dont ask, go with the default
rem --desktop a desktop shortcut as well
rem --arch x64^|arm64 default x64
rem --out <folder> where the exe is put (default: the folder youre in)
set "HERE=%~dp0"
set "NAME="
set "ID="
set "PROJECT="
set "EXE="
set "ICON="
set "API=https://pay.imbenji.net/api"
set "PUBLISHER="
set "LOCATION=me"
set "CHOICE=ON"
set "DESKTOP=OFF"
set "ARCH=x64"
set "OUT=%CD%"
:args
if "%~1"=="" goto run
if /i "%~1"=="--name" ( set "NAME=%~2" & shift & shift & goto args )
if /i "%~1"=="--id" ( set "ID=%~2" & shift & shift & goto args )
if /i "%~1"=="--project" ( set "PROJECT=%~2" & shift & shift & goto args )
if /i "%~1"=="--exe" ( set "EXE=%~2" & shift & shift & goto args )
if /i "%~1"=="--icon" ( set "ICON=%~f2" & shift & shift & goto args )
if /i "%~1"=="--api" ( set "API=%~2" & shift & shift & goto args )
if /i "%~1"=="--publisher" ( set "PUBLISHER=%~2" & shift & shift & goto args )
if /i "%~1"=="--default" ( set "LOCATION=%~2" & shift & shift & goto args )
if /i "%~1"=="--arch" ( set "ARCH=%~2" & shift & shift & goto args )
if /i "%~1"=="--out" ( set "OUT=%~f2" & shift & shift & goto args )
if /i "%~1"=="--hide-choice" ( set "CHOICE=OFF" & shift & goto args )
if /i "%~1"=="--desktop" ( set "DESKTOP=ON" & shift & goto args )
echo build_installer: dont know what "%~1" is
exit /b 2
:run
if "%NAME%"=="" ( echo build_installer: --name is needed & exit /b 2 )
if "%ID%"=="" ( echo build_installer: --id is needed & exit /b 2 )
if "%PROJECT%"=="" ( echo build_installer: --project is needed & exit /b 2 )
if "%EXE%"=="" ( echo build_installer: --exe is needed & exit /b 2 )
set "VSARCH=x64"
if /i "%ARCH%"=="arm64" set "VSARCH=ARM64"
rem one build folder per app and arch, so two apps dont share a cache
set "BUILD=%HERE%build\%ID%-%ARCH%"
rem cmake wants forward slashes in a path it is going to paste in to an .rc
if defined ICON set "ICON=%ICON:\=/%"
cmake -S "%HERE%." -B "%BUILD%" -A %VSARCH% ^
"-DGARAGE_APP_NAME=%NAME%" "-DGARAGE_APP_ID=%ID%" "-DGARAGE_PROJECT_ID=%PROJECT%" ^
"-DGARAGE_EXE_NAME=%EXE%" "-DGARAGE_API_BASE=%API%" "-DGARAGE_PUBLISHER=%PUBLISHER%" ^
"-DGARAGE_ICON=%ICON%" "-DGARAGE_DEFAULT_LOCATION=%LOCATION%" ^
-DGARAGE_SHOW_CHOICE=%CHOICE% -DGARAGE_DESKTOP_SHORTCUT=%DESKTOP%
if errorlevel 1 ( echo build_installer: cmake couldnt set the build up & exit /b 1 )
cmake --build "%BUILD%" --config Release
if errorlevel 1 ( echo build_installer: the build failed & exit /b 1 )
if not exist "%OUT%" mkdir "%OUT%"
copy /y "%BUILD%\Release\*-Setup.exe" "%OUT%\" >nul
if errorlevel 1 ( echo build_installer: built, but couldnt copy the exe out of %BUILD%\Release & exit /b 1 )
echo.
echo the installer is in %OUT%
endlocal
File diff suppressed because it is too large Load Diff
@@ -0,0 +1,29 @@
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<assembly xmlns="urn:schemas-microsoft-com:asm.v1" manifestVersion="1.0">
<!-- asInvoker on purpose. "just me" never needs admin, and "everyone" asks for it itself -->
<trustInfo xmlns="urn:schemas-microsoft-com:asm.v3">
<security>
<requestedPrivileges>
<requestedExecutionLevel level="asInvoker" uiAccess="false"/>
</requestedPrivileges>
</security>
</trustInfo>
<!-- the task dialog only exists in version 6 of the common controls -->
<dependency>
<dependentAssembly>
<assemblyIdentity type="win32" name="Microsoft.Windows.Common-Controls" version="6.0.0.0"
processorArchitecture="*" publicKeyToken="6595b64144ccf1df" language="*"/>
</dependentAssembly>
</dependency>
<compatibility xmlns="urn:schemas-microsoft-com:compatibility.v1">
<application>
<supportedOS Id="{8e0f7a12-bfb3-4fe8-b9a5-48fd50a15a9a}"/>
</application>
</compatibility>
<application xmlns="urn:schemas-microsoft-com:asm.v3">
<windowsSettings>
<dpiAwareness xmlns="http://schemas.microsoft.com/SMI/2016/WindowsSettings">PerMonitorV2</dpiAwareness>
<longPathAware xmlns="http://schemas.microsoft.com/SMI/2016/WindowsSettings">true</longPathAware>
</windowsSettings>
</application>
</assembly>
@@ -0,0 +1,12 @@
// made by cmake. the icon, the stub and (not for msvc) the manifest
#pragma code_page(65001)
@GARAGE_ICON_LINE@
// the stub, whole. its written out as <root>\<AppExe>.exe
STUB RCDATA "@GARAGE_STUB_FILE@"
// msvc gets the manifest handed to the linker instead, two of them collide
#ifdef GARAGE_RC_MANIFEST
1 24 "@GARAGE_MANIFEST_FILE@"
#endif
@@ -0,0 +1,24 @@
// made by cmake from the values the installer was built with. dont edit the
// copy in the build folder, it gets written over.
#pragma once
// what people see: the window, the shortcut, the folder, "installed apps"
#define GARAGE_APP_NAME L"@GARAGE_APP_NAME_C@"
// the key of the uninstall entry, and the folder under %LOCALAPPDATA% that
// downloads go to when the install itself is read only
#define GARAGE_APP_ID L"@GARAGE_APP_ID_C@"
#define GARAGE_PROJECT_ID L"@GARAGE_PROJECT_ID_C@"
#define GARAGE_API_BASE L"@GARAGE_API_BASE_C@"
// the apps exe inside a build. the stub goes in root under the same name
#define GARAGE_EXE_NAME L"@GARAGE_EXE_NAME_C@"
#define GARAGE_PUBLISHER L"@GARAGE_PUBLISHER_C@"
// 1 is "everyone on this pc" (program files), 0 is "just me"
#define GARAGE_DEFAULT_EVERYONE @GARAGE_DEFAULT_EVERYONE_C@
// 0 never asks and goes with the default
#define GARAGE_SHOW_CHOICE @GARAGE_SHOW_CHOICE_C@
#define GARAGE_DESKTOP_SHORTCUT @GARAGE_DESKTOP_SHORTCUT_C@