@monimesl/dot-cli 1.0.0-beta.0 → 1.0.0-beta.10

package/dist/templates/showcase/pages/dash/reminders/controller.ts

@@ -0,0 +1,73 @@
+import { errorMessage } from '@monimesl/dot-runtime';
+
+import state from './state';
+
+function dateIn(days: number): string {
+  const date = new Date();
+  date.setDate(date.getDate() + days);
+  const month = String(date.getMonth() + 1).padStart(2, '0');
+  const day = String(date.getDate()).padStart(2, '0');
+  return `${date.getFullYear()}-${month}-${day}`;
+}
+
+async function noteAfter(request: PromiseLike<unknown>): Promise<string> {
+  try {
+    await request;
+    return '';
+  } catch (error) {
+    return errorMessage(error);
+  }
+}
+
+export default definePage({
+  initialState: state,
+  configs: { navigationBar: { title: 'Reminders' } },
+  hooks: {
+    async onShow() {
+      await this.actions.refresh();
+    },
+  },
+  actions: {
+    async refresh() {
+      try {
+        this.setState({ reminders: await this.dash.reminders.list() });
+      } catch (error) {
+        this.setState({ note: errorMessage(error) });
+      }
+    },
+    // A 13th still to come rejects with 'failed', so cancel one first.
+    async remindTomorrow() {
+      const note = await noteAfter(
+        this.dash.reminders.set({
+          key: 'concert',
+          title: 'Jazz Night is tomorrow',
+          message: 'Doors open at 7',
+          page: '/basics/concert?concert=jazz-night',
+          schedule: { start: dateIn(1), time: '09:00' },
+        }),
+      );
+      this.setState({ note });
+      await this.actions.refresh();
+    },
+    async remindWeekly() {
+      const note = await noteAfter(
+        this.dash.reminders.set({
+          key: 'weekly-gigs',
+          title: 'New gigs this week',
+          schedule: {
+            start: dateIn(1),
+            time: '18:00',
+            repeat: { every: 'week', days: ['fri'] },
+            end: { after: 4 },
+          },
+        }),
+      );
+      this.setState({ note });
+      await this.actions.refresh();
+    },
+    async cancel(_state, event: DataEvent<{ key: string }>) {
+      await this.dash.reminders.cancel(event.data.key);
+      await this.actions.refresh();
+    },
+  },
+});

package/dist/templates/showcase/pages/dash/reminders/state.ts

@@ -0,0 +1,6 @@
+import type { Reminder } from '@monimesl/dot-runtime';
+
+export default {
+  reminders: [] as Reminder[],
+  note: '',
+};

package/dist/templates/showcase/pages/dash/reminders/view.dml

@@ -0,0 +1,34 @@
+<View>
+  <Text variant="title">dash.reminders</Text>
+  <Text>Notifications that bring the person back to a page of the dot. Dash never acts by itself.</Text>
+
+  <View gap="small">
+    <Text variant="subtitle">set</Text>
+    <Text variant="caption" tone="muted">Once, or repeating as transfer reminders do. It needs the reminders permission in dot.json, and a dot can have 12 still to come.</Text>
+    <View direction="row" gap="small" wrap>
+      <Button onClick="remindTomorrow">Remind me tomorrow</Button>
+      <Button variant="secondary" onClick="remindWeekly">Every Friday</Button>
+    </View>
+  </View>
+
+  <View gap="small">
+    <Text variant="subtitle">list and cancel</Text>
+    <Text variant="caption" tone="muted">The dot's own, which the person can also delete in Dash. Tap one to cancel it.</Text>
+    <View variant="card" gap="small">
+      <If condition="{{ reminders.length > 0 }}">
+        <List>
+          <For each="{{ reminders }}" item="reminder" key="key">
+            <ListItem icon="bell" title="{{ reminder.title }}" subtitle="{{ reminder.schedule.start }} at {{ reminder.schedule.time || '09:00' }}" value="Cancel" data-key="{{ reminder.key }}" onTap="cancel" />
+          </For>
+        </List>
+      </If>
+      <Else>
+        <Text variant="caption" tone="muted">None yet.</Text>
+      </Else>
+    </View>
+  </View>
+
+  <If condition="{{ note }}">
+    <Notice tone="danger">{{ note }}</Notice>
+  </If>
+</View>

package/dist/templates/showcase/pages/dash/secrets/controller.ts

@@ -1,3 +1,5 @@
+import { errorMessage } from '@monimesl/dot-runtime';
+
 import state from './state';
 
 const SESSION = 'session';
@@ -16,28 +18,49 @@ export default definePage({
   },
   actions: {
     async refresh() {
-      const token = await this.dash.storage.secret.get(SESSION);
-      const signedInAs = await this.dash.storage.cache.get<string>(NAME);
-      this.setState({
-        token: token ? `${token.slice(0, 12)}…` : '',
-        signedInAs: signedInAs ?? '',
-      });
+      try {
+        // null if there's no secret by that name.
+        const token = await this.dash.storage.secret.get(SESSION);
+        const signedInAs = await this.dash.storage.cache.get<string>(NAME);
+        this.setState({
+          token: token ? `${token.slice(0, 12)}…` : '',
+          signedInAs: signedInAs ?? '',
+        });
+      } catch (error) {
+        this.setState({ note: errorMessage(error) });
+      }
     },
+    // A value over 4 KB rejects with 'invalid'. A 33rd secret rejects with 'failed', so remove
+    // one first.
     async signIn(state) {
-      // A real dot gets its token from its own API, once the person signs in there.
-      const token = `demo-${Math.random().toString(36).slice(2)}${Date.now().toString(36)}`;
-      await this.dash.storage.secret.set(SESSION, token);
-      await this.dash.storage.cache.set(NAME, state.name);
-      this.setState({ name: '' });
+      try {
+        // A real dot gets its token from its own API, once the person signs in there.
+        const token = `demo-${Math.random().toString(36).slice(2)}${Date.now().toString(36)}`;
+        await this.dash.storage.secret.set(SESSION, token);
+        await this.dash.storage.cache.set(NAME, state.name);
+        this.setState({ name: '', note: '' });
+      } catch (error) {
+        this.setState({ note: errorMessage(error) });
+      }
       await this.actions.refresh();
     },
     async signOut() {
-      await this.dash.storage.secret.remove(SESSION);
-      await this.dash.storage.cache.remove(NAME);
+      try {
+        await this.dash.storage.secret.remove(SESSION);
+        await this.dash.storage.cache.remove(NAME);
+        this.setState({ note: '' });
+      } catch (error) {
+        this.setState({ note: errorMessage(error) });
+      }
       await this.actions.refresh();
     },
     async forgetAll() {
-      await this.dash.storage.secret.clear();
+      try {
+        await this.dash.storage.secret.clear();
+        this.setState({ note: '' });
+      } catch (error) {
+        this.setState({ note: errorMessage(error) });
+      }
       await this.actions.refresh();
     },
   },

package/dist/templates/showcase/pages/dash/secrets/state.ts

@@ -2,4 +2,5 @@ export default {
   name: '',
   signedInAs: '',
   token: '',
+  note: '',
 };

package/dist/templates/showcase/pages/dash/secrets/view.dml

@@ -23,4 +23,8 @@
   </View>
 
   <Notice tone="warning" title="Keep keys off the phone">Only the token is a secret here: your name is in the cache. Never put API keys in a dot's code or .env, since anyone with the dot can read them.</Notice>
+
+  <If condition="{{ note }}">
+    <Notice tone="danger">{{ note }}</Notice>
+  </If>
 </View>

package/dist/templates/showcase/pages/dash/system/controller.ts

@@ -37,6 +37,7 @@ export default definePage({
         this.setState({ note: errorMessage(error) });
       }
     },
+    // Only https addresses. Anything else rejects with 'invalid'.
     async openDrizilik() {
       try {
         await this.dash.system.openUrl('https://drizilik.com/');
@@ -44,6 +45,7 @@ export default definePage({
         this.setState({ note: errorMessage(error) });
       }
     },
+    // A dot's logic has no timers, so Dash keeps the time.
     async countDown() {
       for (let seconds = 10; seconds > 0; seconds--) {
         this.setState({ showIn: seconds });
@@ -68,6 +70,8 @@ export default definePage({
         this.setState({ note: errorMessage(error) });
       }
     },
+    // A number may have digits, spaces, dashes, +, * and #. Anything else rejects with 'invalid'.
+    // For a USSD code, Dash asks the person first, and rejects with 'cancelled' if they say no.
     async dialNumber(state) {
       try {
         await this.dash.system.dial(state.number);
@@ -76,6 +80,7 @@ export default definePage({
         this.setState({ note: errorMessage(error) });
       }
     },
+    // A phone without a torch rejects with 'unsupported'.
     async toggleTorch(state) {
       const torchOn = !state.torchOn;
       try {

package/dist/templates/showcase/pages/dash/system/view.dml

@@ -58,7 +58,7 @@
 
   <View gap="small">
     <Text variant="subtitle">openUrl</Text>
-    <Text variant="caption" tone="muted">Opens a web page in the phone's browser.</Text>
+    <Text variant="caption" tone="muted">Opens an https web page in the phone's browser.</Text>
     <View variant="card">
       <Button variant="secondary" onClick="openDrizilik">Open Drizilik's website</Button>
     </View>
@@ -66,7 +66,7 @@
 
   <View gap="small">
     <Text variant="subtitle">delay</Text>
-    <Text variant="caption" tone="muted">Waits for a number of milliseconds. Dash keeps time, so it's cancelled when the page closes.</Text>
+    <Text variant="caption" tone="muted">Waits for a number of milliseconds. Like any call still running, it stops when the page closes.</Text>
     <View variant="card">
       <Button variant="secondary" onClick="countDown" disabled="{{ showIn > 0 }}">{{ showIn > 0 ? 'Showtime in ' + showIn + 's' : 'Count down to showtime' }}</Button>
     </View>
@@ -74,7 +74,7 @@
 
   <View gap="small">
     <Text variant="subtitle">dial</Text>
-    <Text variant="caption" tone="muted">Opens the phone's dialer with a number ready, or a USSD code such as *715#. The person taps Call.</Text>
+    <Text variant="caption" tone="muted">Opens the phone's dialer with a number ready, or a USSD code such as *715#. The person taps Call. For a code, Dash asks them first.</Text>
     <View variant="card">
       <Input label="Number or code" type="phone" value="{{ number }}" onChange="setNumber" onSubmit="dialNumber" />
       <Button variant="secondary" onClick="dialNumber" disabled="{{ !number }}">Open the dialer</Button>
@@ -83,7 +83,7 @@
 
   <View gap="small">
     <Text variant="subtitle">torch</Text>
-    <Text variant="caption" tone="muted">Turns the camera's light on or off.</Text>
+    <Text variant="caption" tone="muted">Turns the camera's light on or off, on a phone that has one.</Text>
     <View variant="card">
       <Button variant="secondary" onClick="toggleTorch">{{ torchOn ? 'Turn the torch off' : 'Lights up for the slow song' }}</Button>
     </View>

package/dist/templates/showcase/pages/dash/ui/controller.ts

@@ -5,9 +5,13 @@ import state from './state';
 export default definePage({
   initialState: state,
   configs: { navigationBar: { title: 'Dialogs and pickers' } },
+  // A this.dash call goes to Dash and answers later, so await it. If it fails, it throws a
+  // DashError with a code that says why, such as 'cancelled' or 'denied'. errorMessage(error)
+  // gives text to show for any error. The Calls and errors page lists every code.
   actions: {
     async greet() {
       try {
+        // Resolves with { action }: the id of the button tapped.
         const { action } = await this.dash.ui.alert({
           title: 'Kushé',
           message: 'Kushé means hello in Krio, and tenki means thanks.',
@@ -36,7 +40,8 @@ export default definePage({
         this.setState({ note: errorMessage(error) });
       }
     },
-    // unlessCancelled gives undefined when the person closes the picker, which isn't a problem.
+    // Closing a picker rejects with 'cancelled'. That isn't a problem, so unlessCancelled turns it
+    // into undefined. Any other error still throws. A min after max rejects with 'invalid'.
     async chooseNight(state) {
       try {
         const night = await unlessCancelled(

package/dist/templates/showcase/pages/index/controller.ts

@@ -3,6 +3,7 @@ import state from './state';
 export default definePage({
   initialState: state,
   actions: {
+    // Each row's data-page names its page. The Events and Navigation pages show how this works.
     open(_state, event: DataEvent<{ page: PageId }>) {
       this.navigation.push(event.data.page);
     },

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

@@ -40,7 +40,7 @@ export default {
         {
           page: 'basics/events',
           title: 'Events',
-          covers: 'onTap, onChange, event.detail, data-*',
+          covers: 'onClick, onTap, onChange, event.detail, event.data',
           icon: 'bolt',
         },
         {
@@ -67,6 +67,12 @@ export default {
           covers: 'configs.colors, setColors, background, primary, surfaces',
           icon: 'water',
         },
+        {
+          page: 'basics/theme',
+          title: 'Theme',
+          covers: 'colors, shape, density, elevation, fonts, components, icons, gradients',
+          icon: 'eye',
+        },
         {
           page: 'basics/share',
           title: 'Share links',
@@ -82,13 +88,13 @@ export default {
         {
           page: 'components/layout',
           title: 'Layout',
-          covers: 'View, Stack, Scroll, Grid, Divider',
+          covers: 'View, hidden, disabled, Stack, Scroll, Grid, Divider',
           icon: 'grid',
         },
         {
           page: 'components/styles',
           title: 'Styles',
-          covers: 'background, border, radius, sizes, theme colours',
+          covers: 'background, border, radius, sizes, elevation, buttons, own colours',
           icon: 'star',
         },
         {
@@ -130,9 +136,21 @@ export default {
         {
           page: 'components/tabs',
           title: 'Tabs and chips',
-          covers: 'Tabs, Tab, Chip',
+          covers: 'Tabs, Tab, Tab icons, Chip',
           icon: 'search',
         },
+        {
+          page: 'components/pinned',
+          title: 'Pinned bars',
+          covers: 'Pinned, Tabs variant="bar"',
+          icon: 'location',
+        },
+        {
+          page: 'components/capture',
+          title: 'Pictures of a View',
+          covers: 'View id, captureView',
+          icon: 'image',
+        },
         {
           page: 'components/forms',
           title: 'Forms',
@@ -188,6 +206,12 @@ export default {
           covers: 'pickPhone',
           icon: 'users',
         },
+        {
+          page: 'dash/reminders',
+          title: 'dash.reminders',
+          covers: 'set, cancel and list',
+          icon: 'bell',
+        },
         {
           page: 'dash/account',
           title: 'dash.account',
@@ -216,7 +240,7 @@ export default {
         {
           page: 'dash/files',
           title: 'dash.storage.file',
-          covers: 'write, read, list, move, copy, remove, save, stat, open, usage',
+          covers: 'write, read, list, createFolder, move, copy, remove, save, stat, open, usage',
           icon: 'file',
         },
         {
@@ -234,7 +258,7 @@ export default {
         {
           page: 'dash/calls',
           title: 'Calls and errors',
-          covers: 'timeout, cancel, DashError, isDashError',
+          covers: 'timeout, cancel, DashError, isDashError, supports, dash.dot.close',
           icon: 'warning',
         },
       ],

package/dist/templates/showcase/statics/icons/ticket-stub.svg

@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path fill="#000" fill-rule="evenodd" d="M5 4h14a2 2 0 0 1 2 2v3a3 3 0 0 0 0 6v3a2 2 0 0 1-2 2H5a2 2 0 0 1-2-2v-3a3 3 0 0 0 0-6V6a2 2 0 0 1 2-2zm4 3v2h1.5V7zm0 4v2h1.5v-2zm0 4v2h1.5v-2z"/></svg>

package/dist/templates/starter/.env

@@ -1,3 +1,3 @@
-# Public configuration for the dot. Anyone with the dot can read these variables: never put a
-# secret here. Read them in the service as `env.GREETING`.
+# Public settings for the dot. Code reads each one from `env`, such as `env.GREETING`.
+# They're built into the dot, so anyone who has it can read them. Never put a secret here.
 GREETING=Hello from your dot

package/dist/templates/starter/dot.ts

@@ -1,3 +1,4 @@
 export default defineDot({
+  // Each page is a folder under pages/. The dot opens on the first one.
   pages: ['index'],
 });

package/dist/templates/starter/pages/index/controller.ts

@@ -2,6 +2,8 @@ import state from './state';
 
 export default definePage({
   initialState: state,
+  // A mutation gets the state and returns the fields to change, and the view follows. For steps
+  // that wait, such as a Dash call, use actions instead.
   mutations: {
     increment: (state) => ({ count: state.count + 1 }),
     reset: () => ({ count: 0 }),

package/dist/templates/starter/pages/index/state.ts

@@ -1,4 +1,6 @@
+// The data the page starts with. view.dml shows it with bindings, such as {{ count }}.
 export default {
+  // env holds the values in .env.
   greeting: env.GREETING,
   count: 0,
 };

package/dist/templates/starter/pages/index/view.dml

@@ -3,11 +3,12 @@
     <Image src="statics/logo.png" alt="Logo" width="40" height="40" />
     <Text variant="title">{{ greeting }}</Text>
   </View>
-  <Text>Change pages/index/view.dml and save: the simulator shows it at once.</Text>
+  <Text>Change pages/index/view.dml and save. The simulator shows the change at once.</Text>
 
   <View variant="card" align="center" gap="medium">
     <Text variant="title">{{ count }}</Text>
     <Text tone="muted">{{ count === 1 ? 'tap' : 'taps' }} so far</Text>
+    <!-- onClick names the mutation or action in controller.ts to run. -->
     <View direction="row" gap="small">
       <Button variant="secondary" onClick="reset" disabled="{{ count === 0 }}">Reset</Button>
       <Button onClick="increment">Tap me</Button>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@monimesl/dot-cli",
-  "version": "1.0.0-beta.0",
+  "version": "1.0.0-beta.10",
   "description": "The dotctl command: build mini apps and run them in the simulator",
   "type": "module",
   "repository": {
@@ -24,11 +24,11 @@
   "dependencies": {
     "typescript": "^5.9.3",
     "uqr": "^0.1.3",
-    "@monimesl/dot-compiler": "1.0.0-beta.0",
-    "@monimesl/dot-core": "1.0.0-beta.0",
-    "@monimesl/dot-dml-parser": "1.0.0-beta.0",
-    "@monimesl/dot-script-parser": "1.0.0-beta.0",
-    "@monimesl/dot-simulator": "1.0.0-beta.0"
+    "@monimesl/dot-compiler": "1.0.0-beta.10",
+    "@monimesl/dot-core": "1.0.0-beta.10",
+    "@monimesl/dot-dml-parser": "1.0.0-beta.10",
+    "@monimesl/dot-script-parser": "1.0.0-beta.10",
+    "@monimesl/dot-simulator": "1.0.0-beta.10"
   },
   "devDependencies": {
     "@types/node": "^22.20.4",