@monimesl/dot-cli 1.0.0-beta.1 → 1.0.0-beta.3

package/dist/templates/showcase/dot.ts

@@ -3,7 +3,7 @@ import { logger } from '@monimesl/dot-runtime';
 import { swatchColors } from './pages/basics/colors/palette';
 
 export default defineDot({
-  // Folders under pages/, as the home page lists them. The first opens when the dot starts.
+  // Each page is a folder under pages/, here in the home page's order. The dot opens on the first.
   pages: [
     'index',
     // How a page works.
@@ -57,5 +57,6 @@ export default defineDot({
       },
     },
   },
+  // logger() writes each page load, event, navigation and state change to the console.
   plugins: [logger()],
 });

package/dist/templates/showcase/pages/basics/bars/controller.ts

@@ -24,8 +24,8 @@ export default definePage({
     },
     togglePainted(state) {
       const painted = !state.painted;
-      // A pale sky by day, the night over Freetown by dark. Undefined puts the theme's back. Cards,
-      // fields and quieter text follow the background, unless the page sets those too.
+      // A pale sky in light mode, the night over Freetown in dark. Undefined puts the theme's back.
+      // Cards, fields and quieter text follow the background, unless the page sets those too.
       if (painted) {
         this.setColors({ background: { light: '#E3F2FD', dark: '#0B1A2E' } });
       } else {

package/dist/templates/showcase/pages/basics/bars/view.dml

@@ -16,12 +16,13 @@
         <Button variant="secondary" onClick="toggleColors">{{ colored ? 'Plain bar' : 'Green bar' }}</Button>
         <Button variant="secondary" onClick="toggleNavigationBar">{{ navigationBarHidden ? 'Show the bar' : 'Hide the bar' }}</Button>
       </View>
+      <Text variant="caption" tone="muted">A title can be up to 60 characters. With the bar hidden, Dash still shows a capsule at the top right with the dot's menu, so keep that corner free.</Text>
     </View>
   </View>
 
   <View gap="small">
     <Text variant="subtitle">setColors</Text>
-    <Text variant="caption" tone="muted">configs.colors or setColors give a page its own colours, for light and dark, such as its background. Dash paints the background behind the page too, makes cards and fields that sit on it, and picks text, bar and status bar colours that read on it. The Page colours page has more.</Text>
+    <Text variant="caption" tone="muted">configs.colors or setColors give a page its own colours, for light and dark, such as its background. Dash picks text and bar colours that read on it. The Page colours page has more.</Text>
     <View variant="card">
       <Button variant="secondary" onClick="togglePainted">{{ painted ? 'Theme background' : 'Sky background' }}</Button>
     </View>

package/dist/templates/showcase/pages/basics/bindings/state.ts

@@ -3,11 +3,11 @@ export default {
   syntax: '{{ name }}',
   name: 'Mariama',
   stageName: null as string | null,
-  // Le, in the leone since 2022, when it dropped three zeros.
+  // In leones (SLE), the new leone of 2022.
   price: 150,
   tickets: 4,
   genres: ['kriofusion', 'palm-wine', 'gumbe'],
-  // state.ts runs in the service, so it can read the .env file's values too.
+  // A binding reads only the page's state, so a value from .env goes in it first.
   greeting: env.GREETING,
   // Worked out in the controller, since a binding can't call a function.
   shout: 'MARIAMA',

package/dist/templates/showcase/pages/basics/bindings/view.dml

@@ -13,7 +13,7 @@
 
   <View gap="small">
     <Text variant="subtitle">Expressions</Text>
-    <Text variant="caption" tone="muted">Maths, comparisons, ? : and ?? work. Calling a function doesn't: work the value out in the controller, as shout is here.</Text>
+    <Text variant="caption" tone="muted">Maths, comparisons, ? : and ?? work. A binding can't call a function, so work the value out in the controller, as shout is here.</Text>
     <View variant="card" gap="small">
       <Text>{{ tickets }} {{ tickets === 1 ? 'ticket' : 'tickets' }} at Le {{ price }} each: Le {{ tickets * price }}</Text>
       <Text>Stage name: {{ stageName ?? 'none yet' }}</Text>
@@ -33,7 +33,7 @@
 
   <View gap="small">
     <Text variant="subtitle">env</Text>
-    <Text variant="caption" tone="muted">Values in the dot's .env file. Anyone with the dot can read them, so never put a secret there.</Text>
+    <Text variant="caption" tone="muted">Values in the dot's .env file, copied into state.ts to show here. Anyone with the dot can read them, so never put a secret there.</Text>
     <View variant="card">
       <Text>{{ greeting }}</Text>
     </View>

package/dist/templates/showcase/pages/basics/colors/controller.ts

@@ -31,7 +31,7 @@ export default definePage({
     },
     useCustom(state) {
       const light = state.customLight.trim();
-      // One colour is enough: it's used in dark too.
+      // One colour is enough. It's used in dark mode too.
       const dark = state.customDark.trim() || light;
       if (!HEX_COLOR.test(light) || !HEX_COLOR.test(dark)) {
         this.setState({ customError: 'Write a colour as # and six digits, such as #FFF3E0' });

package/dist/templates/showcase/pages/basics/concert/view.dml

@@ -10,7 +10,7 @@
       <Notice tone="info">Opened for {{ buyer }}. buyer isn't in share's options, so a shared link leaves it out.</Notice>
     </If>
     <Else>
-      <Notice tone="success">Opened from a link: it carried the concert, and nothing else.</Notice>
+      <Notice tone="success">Opened from a link. It carried the concert and nothing else.</Notice>
     </Else>
     <Text variant="caption" tone="muted">Tap ••• then Share. The link opens this concert.</Text>
   </If>

package/dist/templates/showcase/pages/basics/control-flow/controller.ts

@@ -12,7 +12,7 @@ export default definePage({
     }),
     restock: (state) => ({ shows: state.shows.map((show) => ({ ...show, left: 20 })) }),
     toggleSignedIn: (state) => ({ signedIn: !state.signedIn }),
-    // Changes the list's order. The key keeps each row's place right.
+    // Changes the list's order. The For's key lets each row move with its item.
     shuffle: (state) => ({ genres: [...state.genres.slice(1), state.genres[0]!] }),
   },
 });

package/dist/templates/showcase/pages/basics/control-flow/view.dml

@@ -18,7 +18,7 @@
 
   <View gap="small">
     <Text variant="subtitle">For, with ElseIf inside</Text>
-    <Text variant="caption" tone="muted">item names each show. key gives each a lasting id, so its row stays the same row when the list changes. ElseIf checks another condition when the one above is false.</Text>
+    <Text variant="caption" tone="muted">item names each show. key names the field that tells the shows apart, so each row stays with its show when the list changes. ElseIf checks another condition when the one above is false.</Text>
     <View variant="card" gap="medium">
       <For each="{{ shows }}" item="show" key="id">
         <View direction="row" align="center" gap="small">

package/dist/templates/showcase/pages/basics/events/controller.ts

@@ -14,7 +14,7 @@ export default definePage({
   initialState: state,
   configs: { navigationBar: { title: 'Events' } },
   mutations: {
-    // No detail: a tap is all there is to know.
+    // A tap has no detail. It only says the tap happened.
     countTap: (state, event: DotEvent) => ({
       taps: state.taps + 1,
       ...describe('countTap', event),

package/dist/templates/showcase/pages/basics/events/view.dml

@@ -19,7 +19,7 @@
 
   <View gap="small">
     <Text variant="subtitle">Taps</Text>
-    <Text variant="caption" tone="muted">Button raises click. View, ListItem, Link and Chip raise tap.</Text>
+    <Text variant="caption" tone="muted">A Button raises click, so it takes onClick. View, ListItem, Link and Chip raise tap, so they take onTap.</Text>
     <View variant="card" direction="row" align="center" gap="small">
       <Button variant="secondary" onClick="countTap">Tap me</Button>
       <View variant="card" grow onTap="countTap">

package/dist/templates/showcase/pages/basics/hooks/controller.ts

@@ -16,7 +16,8 @@ export default definePage({
     onLoad(options) {
       this.setState({ lastClosed, runs: ran([], `onLoad ${JSON.stringify(options)}`) });
     },
-    // Runs each time the page comes into view: after onLoad, and when a page above it closes.
+    // Runs each time the page comes into view: after onLoad, when a page above it closes, and when
+    // the dot comes back from the background.
     onShow() {
       this.setState((current) => ({ runs: ran(current.runs, 'onShow') }));
     },

package/dist/templates/showcase/pages/basics/hooks/view.dml

@@ -9,7 +9,7 @@
         <Text>{{ run.id }}. {{ run.hook }}</Text>
       </For>
     </View>
-    <Text variant="caption" tone="muted">Open another page, then come back: this page runs onHide, then onShow.</Text>
+    <Text variant="caption" tone="muted">Open another page, then come back. This page runs onHide, then onShow.</Text>
     <Button variant="secondary" onClick="openAnother">Open another page</Button>
   </View>
 
@@ -32,6 +32,6 @@
 
   <View gap="small">
     <Text variant="subtitle">The dot's hooks</Text>
-    <Text variant="caption" tone="muted">dot.ts can have hooks too: onLaunch runs once when the dot starts, and onError gets any error a page doesn't catch.</Text>
+    <Text variant="caption" tone="muted">dot.ts can have hooks too. onLaunch runs once when the dot starts. onError gets any error a page doesn't catch.</Text>
   </View>
 </View>

package/dist/templates/showcase/pages/basics/navigation/controller.ts

@@ -11,6 +11,7 @@ export default definePage({
       this.setState({ depth, from, trail: `${from} › ${depth}`, options: JSON.stringify(options) });
     },
   },
+  // Only actions have this.navigation, so only they open and close pages.
   actions: {
     openAnother(state) {
       this.navigation.push('basics/navigation', { depth: String(state.depth), trail: state.trail });

package/dist/templates/showcase/pages/basics/navigation/view.dml

@@ -22,7 +22,7 @@
 
   <View gap="small">
     <Text variant="subtitle">back</Text>
-    <Text variant="caption" tone="muted">Closes this page, or as many as you ask. On the first page, it closes the dot.</Text>
+    <Text variant="caption" tone="muted">Closes this page, or as many as you ask. It never closes the first page. To close the dot, call this.dash.dot.close().</Text>
     <View direction="row" gap="small">
       <Button variant="secondary" onClick="back">Back</Button>
       <Button variant="secondary" onClick="backTwo" disabled="{{ depth < 3 }}">Back two</Button>

package/dist/templates/showcase/pages/basics/pick-genre/controller.ts

@@ -5,9 +5,9 @@ export default definePage({
   initialState: state,
   configs: {
     navigationBar: { title: 'Choose a genre' },
-    // This page's own background: a warm Salone sunset by day, the evening after it by dark. Dash
-    // paints it behind the page, makes the list's cards to match, and picks text and bar colours
-    // that read on it. Going back shows the page below in its own colours again.
+    // This page's own background, a warm Salone sunset in light mode and the evening after it in
+    // dark. Dash paints it behind the page, makes the list's cards to match, and picks text and bar
+    // colours that read on it. Going back shows the page below in its own colours again.
     colors: { background: { light: '#FFF3E0', dark: '#2B1A0E' } },
   },
   actions: {

package/dist/templates/showcase/pages/basics/share/view.dml

@@ -1,10 +1,10 @@
 <View>
   <Text variant="title">Share links</Text>
-  <Text>Dash's ••• menu has Share. It shares a link to the dot, which opens its first page. A page can let the link open it instead, with some of its options.</Text>
+  <Text>Dash's menu, ••• (⋮ on Android), has Share. It shares a link to the dot, which opens its first page. A page can let the link open it instead, with some of its options.</Text>
 
   <View gap="small">
     <Text variant="subtitle">definePage({ share })</Text>
-    <Text variant="caption" tone="muted">share: { options: ['concert'] } lets the link open the page with its concert option. Options not on the list stay out of the link, so nothing private goes in it. Write share out in place: the build reads it.</Text>
+    <Text variant="caption" tone="muted">share: { options: ['concert'] } lets the link open the page with its concert option. Options not on the list stay out of the link, so nothing private goes in it. Write share out in place, as the build reads it without running the code.</Text>
     <Text variant="caption" tone="muted">Open a concert, then tap ••• and Share.</Text>
     <List>
       <For each="{{ concerts }}" item="concert" key="id">

package/dist/templates/showcase/pages/basics/state/controller.ts

@@ -2,21 +2,30 @@ import state from './state';
 
 export default definePage({
   initialState: state,
+  // What Dash's bars show on this page. The Bars page has more.
   configs: { navigationBar: { title: 'State' } },
+  // A mutation gets the state and returns only the fields that change. It can't wait, so it can't
+  // call Dash.
   mutations: {
     increment: (state) => {
       const count = state.count + 1;
+      // State is read-only, so make a new list rather than change the old one.
       return { count, taps: [{ id: count }, ...state.taps] };
     },
     reset: () => ({ count: 0, taps: [] }),
   },
+  // An action can wait, call Dash, open pages and run other handlers. It changes the state with
+  // this.setState or a mutation.
   actions: {
     fillUp() {
+      // this.state is the latest state. The state an action gets is from when it started, so it
+      // wouldn't see the cheers this loop adds.
       while (this.state.count < this.state.limit) {
         this.mutations.increment();
       }
     },
     undo() {
+      // setState takes the fields to change, or a function that gets the latest state.
       this.setState((current) => ({ count: current.count - 1, taps: current.taps.slice(1) }));
     },
   },

package/dist/templates/showcase/pages/basics/state/state.ts

@@ -2,9 +2,12 @@ export interface Tap {
   id: number;
 }
 
+// State is plain data, as in JSON: text, numbers, true and false, null, lists and objects. Each
+// open copy of the page gets its own. For "no value", use null, as setState skips undefined fields.
 export default {
   title: 'cheers for an encore',
   count: 0,
   limit: 5,
+  // `as Tap[]` tells TypeScript what the empty list will hold.
   taps: [] as Tap[],
 };

package/dist/templates/showcase/pages/components/carousel/view.dml

@@ -4,7 +4,7 @@
 
   <View gap="small">
     <Text variant="subtitle">autoplay, loop and effect</Text>
-    <Text variant="caption" tone="muted">Gen Z artists. The slides move on their own every 3 seconds, start over at the end, and pause when you touch them. effect="scale" shrinks the slides beside the one in view.</Text>
+    <Text variant="caption" tone="muted">Gen Z artists. autoplay moves the slides every interval, here 3000 milliseconds, and pauses while you touch them. loop goes on from the last slide to the first. effect="scale" shrinks the slides beside the one in view.</Text>
     <Carousel autoplay loop interval="3000" gap="medium" effect="scale" indicator="dots">
       <For each="{{ artists }}" item="artist" key="id">
         <View variant="card" align="center" gap="medium">
@@ -23,7 +23,7 @@
 
   <View gap="small">
     <Text variant="subtitle">index and onChange</Text>
-    <Text variant="caption" tone="muted">How Salone music grew, from palm-wine to Gen Z. The page sets the slide with index, and onChange tells it when you swipe. The buttons move the slides, so indicator="none" hides the dots.</Text>
+    <Text variant="caption" tone="muted">How Salone music grew, from palm-wine to Gen Z. index sets the slide. When you swipe, onChange sends the new slide's index. The buttons move the slides here, so indicator="none" hides the dots.</Text>
     <Carousel index="{{ chapter }}" indicator="none" effect="slide" gap="small" padding="small" onChange="showChapter">
       <For each="{{ chapters }}" item="card" key="title">
         <View variant="card" align="center" gap="medium">

package/dist/templates/showcase/pages/components/feedback/controller.ts

@@ -8,7 +8,8 @@ export default definePage({
     restart: () => ({ progress: 0 }),
     toggleBusy: (state) => ({ busy: !state.busy }),
     toggleLoaded: (state) => ({ loaded: !state.loaded }),
-    // A toast lasts its default time unless the button gives one, in milliseconds.
+    // A button's data-duration, in milliseconds, is how long its Toast stays. Without one, the
+    // Toast stays for its default time.
     showToast: (
       _state,
       event: DataEvent<{ message: string; tone: string; duration?: string }>,

package/dist/templates/showcase/pages/components/feedback/state.ts

@@ -6,9 +6,9 @@ export interface PaymentStep {
   status: StepStatus;
 }
 
-// Sending Le 500 to Fatmata Conteh in Bo.
+// Sending SLE 500 to Fatmata Conteh in Bo.
 const PAYMENT = [
-  { title: 'Paid', text: 'Le 500 from your wallet' },
+  { title: 'Paid', text: 'SLE 500 from your wallet' },
   { title: 'Sent', text: 'On its way to Bo' },
   { title: 'Received', text: 'By Fatmata Conteh' },
 ];

package/dist/templates/showcase/pages/components/feedback/view.dml

@@ -14,7 +14,7 @@
 
   <View gap="small">
     <Text variant="subtitle">Skeleton</Text>
-    <Text variant="caption" tone="muted">Shows the shape of what is loading: lines of text, a circle or a box.</Text>
+    <Text variant="caption" tone="muted">Shows the shape of what's loading, as lines of text, a circle or a box.</Text>
     <View variant="card">
       <If condition="{{ loaded }}">
         <View direction="row" align="center" gap="large">
@@ -65,7 +65,7 @@
     <Text variant="subtitle">A busy Button</Text>
     <Text variant="caption" tone="muted">loading shows a spinner, and the button ignores taps.</Text>
     <View variant="card">
-      <Button loading="{{ busy }}">{{ busy ? 'Paying…' : 'Pay Le 300 for two tickets' }}</Button>
+      <Button loading="{{ busy }}">{{ busy ? 'Paying…' : 'Pay SLE 300 for two tickets' }}</Button>
       <Switch label="Busy" checked="{{ busy }}" onChange="toggleBusy" />
     </View>
   </View>

package/dist/templates/showcase/pages/components/forms/controller.ts

@@ -3,10 +3,10 @@ import { errorMessage } from '@monimesl/dot-runtime';
 import type { TicketType } from './state';
 import state, { SHOWS, TICKETS } from './state';
 
-// 2 tickets of a Le 1,200 type -> "Le 2,400"
+// 2 tickets of an SLE 1,200 type -> "SLE 2,400"
 function total(tickets: number, ticket: TicketType): string {
   const leones = tickets * TICKETS[ticket].price;
-  return `Le ${leones.toLocaleString('en-US')}`;
+  return `SLE ${leones.toLocaleString('en-US')}`;
 }
 
 export default definePage({

package/dist/templates/showcase/pages/components/forms/state.ts

@@ -18,7 +18,7 @@ export default {
   // The order, as the summary shows it.
   showName: 'Not chosen yet',
   ticketName: TICKETS.regular.name,
-  total: `Le ${2 * TICKETS.regular.price}`,
+  total: `SLE ${2 * TICKETS.regular.price}`,
   name: '',
   email: '',
   phone: '',

package/dist/templates/showcase/pages/components/forms/view.dml

@@ -15,7 +15,7 @@
 
   <View gap="small">
     <Text variant="subtitle">Input</Text>
-    <Text variant="caption" tone="muted">type sets the keyboard: text, email, phone, number or password. prefix and suffix sit inside the field. error shows under it.</Text>
+    <Text variant="caption" tone="muted">type sets the keyboard, such as email, phone, number or password. prefix and suffix sit inside the field. error shows under it, in place of hint. onSubmit comes when the person presses return, here in the promo code.</Text>
     <View variant="card">
       <Input label="Name" placeholder="Mariama Kamara" value="{{ name }}" maxLength="40" onChange="setName" />
       <Input label="Email" type="email" placeholder="mariama@example.com" hint="{{ eTickets ? 'For the e-tickets' : 'Turn on e-tickets below to use it' }}" value="{{ email }}" disabled="{{ !eTickets }}" onChange="setEmail" />
@@ -37,9 +37,9 @@
     <Text variant="caption" tone="muted">One choice from a few. A Radio, or the whole group, can be disabled.</Text>
     <View variant="card">
       <RadioGroup label="Ticket" value="{{ ticket }}" disabled="{{ sending }}" onChange="setTicket">
-        <Radio value="regular" label="Regular · Le 150" />
-        <Radio value="vip" label="VIP, near the stage · Le 400" />
-        <Radio value="table" label="Table for four · Le 1,200" />
+        <Radio value="regular" label="Regular · SLE 150" />
+        <Radio value="vip" label="VIP, near the stage · SLE 400" />
+        <Radio value="table" label="Table for four · SLE 1,200" />
         <Radio value="backstage" label="Backstage · sold out" disabled />
       </RadioGroup>
     </View>
@@ -90,7 +90,7 @@
     <Notice tone="danger" title="Not booked">{{ failure }}</Notice>
   </If>
 
-  <Text variant="caption" tone="muted">A Footer keeps its buttons at the bottom of the screen.</Text>
+  <Text variant="caption" tone="muted">A Footer keeps its buttons at the bottom of the screen. Put it last in the page's View.</Text>
   <Footer>
     <Button onClick="send" loading="{{ sending }}" disabled="{{ !agreed }}">Buy tickets</Button>
   </Footer>

package/dist/templates/showcase/pages/components/icons/controller.ts

@@ -4,6 +4,7 @@ export default definePage({
   initialState: state,
   configs: { navigationBar: { title: 'Icons' } },
   mutations: {
+    // The Toast raises onHide once it goes. Clearing its message lets the same one show again.
     clearToast: () => ({ toast: '' }),
   },
   actions: {

package/dist/templates/showcase/pages/components/icons/state.ts

@@ -1,5 +1,5 @@
 export default {
-  // Every icon name, as Icon's name, and ListItem's, Chip's, GridItem's and EmptyState's icon take.
+  // Every icon name. Icon's name, and the icon of ListItem, Chip, GridItem and EmptyState, take these.
   names: [
     'arrow-down',
     'arrow-left',

package/dist/templates/showcase/pages/components/images/controller.ts

@@ -2,7 +2,7 @@ import { errorMessage } from '@monimesl/dot-runtime';
 
 import state from './state';
 
-// AUDACITY's id in Apple's catalog; its cover's address can change, so the page looks it up.
+// AUDACITY's id in Apple's catalog. Its cover's address can change, so the page looks it up.
 const AUDACITY = 6811765244;
 
 interface Lookup {

package/dist/templates/showcase/pages/components/images/state.ts

@@ -1,7 +1,7 @@
 export default {
   size: 64,
   loaded: '',
-  // Built at run time, so the build doesn't check that the file exists.
+  // Kept in state, not written in the view, so the build doesn't check that the file exists.
   missing: 'statics/missing.png',
   failure: '',
   // The cover of Drizilik's album AUDACITY, which the page asks Apple's catalog for.

package/dist/templates/showcase/pages/components/images/view.dml

@@ -14,7 +14,7 @@
 
   <View gap="small">
     <Text variant="subtitle">From the web</Text>
-    <Text variant="caption" tone="muted">The cover of Drizilik's album AUDACITY. With aspect="1:1" and no width, it fills the card.</Text>
+    <Text variant="caption" tone="muted">The cover of Drizilik's album AUDACITY. A web picture loads only from a host in dot.json's network.hosts. With aspect="1:1" and no width, it fills the card.</Text>
     <View variant="card" gap="small">
       <If condition="{{ cover }}">
         <Image src="{{ cover }}" alt="The cover of AUDACITY, by Drizilik" aspect="1:1" />
@@ -32,7 +32,7 @@
 
   <View gap="small">
     <Text variant="subtitle">shape and fit</Text>
-    <Text variant="caption" tone="muted">Rounded, square or circle. fit="contain" shows the whole picture; cover, the default, fills the box.</Text>
+    <Text variant="caption" tone="muted">shape is rounded, square or circle. fit="cover", the default, fills the box and crops. fit="contain" shows the whole picture.</Text>
     <View variant="card" direction="row" align="center" gap="large">
       <Image src="statics/logo.png" alt="Rounded" width="56" height="56" shape="rounded" />
       <Image src="statics/logo.png" alt="Square" width="56" height="56" shape="square" />
@@ -44,7 +44,7 @@
 
   <View gap="small">
     <Text variant="subtitle">onLoad</Text>
-    <Text variant="caption" tone="muted">Tells the page the picture's own size once it loads. The size on screen comes from state here.</Text>
+    <Text variant="caption" tone="muted">Comes once the picture loads, with its own size in event.detail.width and height. The size on screen comes from state here.</Text>
     <View variant="card" gap="small">
       <Image src="statics/logo.png" alt="Logo" width="{{ size }}" height="{{ size }}" onLoad="logoLoaded" />
       <Text>{{ size }} × {{ size }} on screen, {{ loaded }} in the file</Text>
@@ -57,7 +57,7 @@
 
   <View gap="small">
     <Text variant="subtitle">onError</Text>
-    <Text variant="caption" tone="muted">Tells the page why a picture didn't load.</Text>
+    <Text variant="caption" tone="muted">Comes when a picture fails to load. event.detail.message says which one.</Text>
     <View variant="card">
       <If condition="{{ failure }}">
         <Text>{{ failure }}</Text>

package/dist/templates/showcase/pages/components/layout/controller.ts

@@ -14,7 +14,8 @@ export default definePage({
   initialState: state,
   configs: { navigationBar: { title: 'Layout' } },
   hooks: {
-    // The shelf's covers come from Apple's catalog.
+    // The shelf's covers come from Apple's catalog. Dash sends requests only to the hosts in
+    // dot.json's network.hosts. The Network page shows more.
     async onLoad() {
       const ids = this.state.releases.map((release) => release.id).join(',');
       try {
@@ -48,6 +49,7 @@ export default definePage({
     openSection: (_state, event: DataEvent<{ name: string }>) => ({
       section: event.data.name,
     }),
+    // Scroll's change carries the index of the child at the start, once the row stops.
     showFirst: (_state, event: IndexEvent) => ({ first: event.detail.index }),
     shelfStart: () => ({ first: 0 }),
     shelfEnd: (state) => ({ first: state.releases.length - 1 }),

package/dist/templates/showcase/pages/components/layout/view.dml

@@ -4,7 +4,7 @@
 
   <View gap="small">
     <Text variant="subtitle">View</Text>
-    <Text variant="caption" tone="muted">A View puts its items in a column or a row. variant="card" gives it a card's look. Change the one below.</Text>
+    <Text variant="caption" tone="muted">A View puts its children in a column, or in a row with direction="row". variant="card" gives it a card's look. Change the one below.</Text>
     <View variant="card" direction="{{ direction }}" justify="{{ justify }}" align="{{ align }}" gap="{{ gap }}" wrap="{{ wrap }}">
       <Button variant="secondary">Palm-wine</Button>
       <Button variant="secondary">Gumbe</Button>
@@ -43,7 +43,7 @@
 
   <View gap="small">
     <Text variant="subtitle">grow and onTap</Text>
-    <Text variant="caption" tone="muted">grow fills the space left over: the song grows, the year does not. A View can be tapped: tap the song.</Text>
+    <Text variant="caption" tone="muted">grow makes a View fill the space left over. The song grows and the year doesn't. A View with onTap can be tapped, so tap the song.</Text>
     <View direction="row" gap="small">
       <View variant="card" grow onTap="playSong">
         <Text>{{ playing ? 'Playing Exodus, by Drizilik' : 'Exodus, by Drizilik' }}</Text>
@@ -72,7 +72,7 @@
 
   <View gap="small">
     <Text variant="subtitle">Stack</Text>
-    <Text variant="caption" tone="muted">A Stack lays its children on top of each other, such as words over a picture.</Text>
+    <Text variant="caption" tone="muted">A Stack lays its children on top of each other, the first at the bottom, such as words over a picture.</Text>
     <Stack radius="large" aspect="16:9">
       <View background="gold" />
       <View justify="end" padding="large">
@@ -89,7 +89,7 @@
 
   <View gap="small">
     <Text variant="subtitle">Scroll</Text>
-    <Text variant="caption" tone="muted">A Scroll moves a row sideways. It stops at the start of each release. The buttons scroll it too.</Text>
+    <Text variant="caption" tone="muted">A Scroll moves a row sideways. snap="start" stops it at the start of a release. Once it stops, onChange sends the index of the first release in view. Setting index scrolls there, as the buttons do.</Text>
     <Scroll gap="medium" snap="start" index="{{ first }}" onChange="showFirst">
       <For each="{{ releases }}" item="release" key="id">
         <View gap="small">
@@ -113,7 +113,7 @@
 
   <View gap="small">
     <Text variant="subtitle">Grid</Text>
-    <Text variant="caption" tone="muted">A Grid keeps its columns the same width. A GridItem shows an icon or a picture, with a label.</Text>
+    <Text variant="caption" tone="muted">A Grid keeps its columns the same width, 4 unless columns says. A GridItem shows an icon or a picture, with a label and an optional badge.</Text>
     <View variant="card" gap="medium">
       <Grid columns="4" gap="small">
         <GridItem icon="microphone" label="Artists" data-name="Artists" onTap="openSection" />

package/dist/templates/showcase/pages/components/lists/view.dml

@@ -1,10 +1,10 @@
 <View>
   <Text variant="title">Lists</Text>
-  <Text>A List shows rows in a card. A ListItem can show an icon or a picture, a subtitle, and a value or a badge at its end. A row you can tap shows an arrow.</Text>
+  <Text>A List shows rows in a card. A ListItem can show an icon or a picture, a subtitle, and a value or a badge at its end. A row with onTap shows an arrow.</Text>
 
   <View gap="small">
     <Text variant="subtitle">List and ListItem</Text>
-    <Text variant="caption" tone="muted">Artists in a small list. Tap one: its data-id tells the page which one.</Text>
+    <Text variant="caption" tone="muted">Tap an artist. The row's data-id tells the page which one.</Text>
     <List>
       <For each="{{ artists }}" item="artist" key="id">
         <ListItem icon="microphone" title="{{ artist.name }}" subtitle="{{ artist.song }}" value="{{ artist.genre }}" data-id="{{ artist.id }}" onTap="choose" />
@@ -16,9 +16,9 @@
   </View>
 
   <View gap="small">
-    <Text variant="subtitle">size="md", with a picture and a badge</Text>
-    <Text variant="caption" tone="muted">Medium lists have more room. A ListItem's children show at its end, in place of value.</Text>
-    <List size="md">
+    <Text variant="subtitle">A picture and a badge</Text>
+    <Text variant="caption" tone="muted">A ListItem's children show at its end, in place of value.</Text>
+    <List>
       <For each="{{ releases }}" item="release" key="id">
         <ListItem image="statics/logo.png" title="{{ release.title }}" subtitle="{{ release.artist }} · {{ release.year }}">
           <Badge tone="{{ release.tone }}">{{ release.note }}</Badge>
@@ -29,7 +29,7 @@
 
   <View gap="small">
     <Text variant="subtitle">onEndReached</Text>
-    <Text variant="caption" tone="muted">Comes when the last row scrolls into view, so the page can add more. {{ chart.length }} of {{ chartSize }} songs so far.</Text>
+    <Text variant="caption" tone="muted">Comes as the last row nears the screen, so the page can add more. It comes again once there's a new last row. {{ chart.length }} of {{ chartSize }} songs so far.</Text>
     <List onEndReached="showMore">
       <For each="{{ chart }}" item="song" key="id">
         <ListItem title="{{ song.id }}. {{ song.title }}" value="{{ song.plays }}" />
@@ -52,7 +52,7 @@
 
   <View gap="small">
     <Text variant="subtitle">Disclosure</Text>
-    <Text variant="caption" tone="muted">A row that opens to show more, such as an answer. The person opens and closes it, and open sets how it starts.</Text>
+    <Text variant="caption" tone="muted">A row that opens to show more, such as an answer. The person opens and closes it, and open sets how it starts. onToggle sends event.detail.open each time.</Text>
     <View variant="card" gap="none">
       <Disclosure title="Can I get a refund?" subtitle="Tickets and refunds" open>
         <Text>Yes, until the Friday before the show. After that, you can give your ticket to someone else.</Text>
@@ -70,7 +70,7 @@
 
   <View gap="small">
     <Text variant="subtitle">EmptyState</Text>
-    <Text variant="caption" tone="muted">Shows when a list has nothing in it, with a way forward.</Text>
+    <Text variant="caption" tone="muted">Shows where a list has nothing yet. Its children, such as a button, show under its text.</Text>
     <View variant="card">
       <If condition="{{ saved.length > 0 }}">
         <For each="{{ saved }}" item="title" key="*this">

package/dist/templates/showcase/pages/components/money/controller.ts

@@ -1,6 +1,6 @@
 import state from './state';
 
-// The code this page accepts; a real dot checks it with its server.
+// The code this page accepts. A real dot checks it with its server.
 const RIGHT_CODE = '123456';
 
 // In dollars, as the pledge field sends them.

package/dist/templates/showcase/pages/components/money/view.dml

@@ -4,7 +4,7 @@
 
   <View gap="small">
     <Text variant="subtitle">AmountInput</Text>
-    <Text variant="caption" tone="muted">Formats the amount as you type. It sends a number in cents, the minor unit, so 150 is SLE 1.50.</Text>
+    <Text variant="caption" tone="muted">Formats the amount as you type. onChange sends a number in cents, the minor unit, so 150 is SLE 1.50. An empty field sends null.</Text>
     <AmountInput label="Tip for the band" placeholder="0.00" value="{{ amount }}" disabled="{{ locked }}" onChange="setAmount" hint="The QR code below asks for it" />
     <Switch label="Lock the tip" checked="{{ locked }}" onChange="setLocked" />
   </View>
@@ -31,7 +31,7 @@
 
   <View gap="small">
     <Text variant="subtitle">CodeInput</Text>
-    <Text variant="caption" tone="muted">A one-time code, one box per digit. Type it, paste it, or let the phone fill it from an SMS. onComplete comes when the last box fills.</Text>
+    <Text variant="caption" tone="muted">A one-time code, one box per digit. Type it, paste it, or let the phone fill it from an SMS. onComplete comes when the last box fills, with the code in event.detail.value.</Text>
     <If condition="{{ verified }}">
       <Notice tone="success" title="Code accepted">Your two tickets are confirmed.</Notice>
       <Button variant="secondary" onClick="startAgain">Start again</Button>