@fusion.dev/helix-templates 0.138.0 → 0.140.0

package/templates/vue-vite/src/LandingPage.vue

@@ -0,0 +1,102 @@
+<script setup lang="ts">
+import { roster } from './data.ts'
+import { DOCS } from './docs.ts'
+
+/* **A locale named, so the number reads the same everywhere.**
+   `toLocaleString()` with no argument reads the machine's locale, so the same
+   number is grouped two ways on two machines. */
+const figure = new Intl.NumberFormat('en-US')
+</script>
+
+<!--
+  The first screen, and the only page here about the starter itself.
+
+  Delete it once you know your way around: nothing else imports it, and the
+  route it answers becomes yours.
+
+  **The calls to action are anchors.** A button that navigates is a link
+  dressed as a button, and the two are different things to a keyboard and to
+  a screen reader. The base stylesheet styles an anchor that asks with
+  `data-button`, so a link can look like one and stay a link.
+-->
+<template>
+  <div class="stack">
+    <header class="first-screen">
+      <!-- **The light behind the first screen**: a helix, drawn by the library in
+           the theme's colors, so a new brand color relights it. It shows one still
+           frame where motion is reduced, and a gradient where the browser draws
+           without a GPU. -->
+      <helix-aura class="first-light" data-layer :speed="0.4" :terminus="0.8" variant="braid" />
+      <div class="hero">
+        <helix-tag emphasis="subtle" tone="primary">Starter</helix-tag>
+        <helix-text as="h1" variant="display">Helix design system</helix-text>
+        <helix-text as="p" class="lede" variant="body">
+          Web components in your brand's colors, drawn from one set of tokens.
+        </helix-text>
+        <div class="actions">
+          <a data-button="solid" data-button-tone="primary" href="#/overview">See the data view</a>
+          <a data-button href="#/join">Open the form</a>
+        </div>
+      </div>
+
+      <!-- **The library at work, on the first screen.** The figures are the roster
+           the data view draws, read from the same module, so the panel is the app
+           itself, on glass over the light. -->
+      <helix-card class="specimen" material="glass" separation="outlined">
+        <helix-text as="h2" slot="header" variant="title">The roster, in three figures</helix-text>
+        <helix-stat-group divided>
+          <helix-stat>
+            {{ roster.people }}
+            <span slot="label">People</span>
+          </helix-stat>
+          <helix-stat>
+            {{ roster.teams }}
+            <span slot="label">Teams</span>
+          </helix-stat>
+          <helix-stat>
+            {{ figure.format(roster.reviews) }}
+            <span slot="label">Reviews</span>
+          </helix-stat>
+        </helix-stat-group>
+        <a data-link href="#/overview" slot="footer">Open the data view</a>
+      </helix-card>
+    </header>
+
+    <section class="section">
+      <helix-text as="h2" variant="subheading">What you have</helix-text>
+      <!-- **Each tile is a link, which is what `data-card` is for.** The base layer
+           draws the ring, moves the card's border to the brand on hover, and leaves
+           focus alone. Nothing inside may be interactive, since a link inside a link
+           is neither valid nor reachable. -->
+      <div class="features">
+        <a class="feature" data-card :href="DOCS.elements">
+          <helix-card separation="outlined">
+            <span class="feature-mark"><helix-icon name="cube" /></span>
+            <helix-text as="h3" variant="title">Custom elements</helix-text>
+            <helix-text as="p" emphasis="muted" variant="body">
+              One import in <helix-code>src/main.ts</helix-code> registers every tag.
+            </helix-text>
+          </helix-card>
+        </a>
+        <a class="feature" data-card :href="DOCS.tokens">
+          <helix-card separation="outlined">
+            <span class="feature-mark"><helix-icon name="palette" /></span>
+            <helix-text as="h3" variant="title">One set of tokens</helix-text>
+            <helix-text as="p" emphasis="muted" variant="body">
+              Every color, size, and space, in light and dark.
+            </helix-text>
+          </helix-card>
+        </a>
+        <a class="feature" data-card :href="DOCS.parts">
+          <helix-card separation="outlined">
+            <span class="feature-mark"><helix-icon name="sliders-horizontal" /></span>
+            <helix-text as="h3" variant="title">Parts to style</helix-text>
+            <helix-text as="p" emphasis="muted" variant="body">
+              Reach inside a component with <helix-code>::part()</helix-code>.
+            </helix-text>
+          </helix-card>
+        </a>
+      </div>
+    </section>
+  </div>
+</template>

package/templates/vue-vite/src/OverviewPage.vue

@@ -0,0 +1,69 @@
+<script setup lang="ts">
+import { members } from './data.ts'
+import { DOCS } from './docs.ts'
+</script>
+
+<!--
+  The data view.
+
+  **The schema is markup and the data is a property.** The columns are
+  elements you can read in the HTML, and `rows` is the whole result handed over
+  at once, since a table of ten thousand rows cannot be written out as
+  elements. The table sorts, pages, and selects out of that array on its own.
+
+  **Selection is keyed on `row-key`, so it survives a sort and a page.**
+  `app.css` paints the chosen row through the parts the table names for it.
+-->
+<template>
+  <div class="stack">
+    <header class="hero">
+      <helix-text emphasis="muted" variant="label">Data view</helix-text>
+      <helix-text as="h1" variant="heading">Roster</helix-text>
+      <helix-text as="p" class="lede" emphasis="muted" variant="body">
+        Twelve people from a local module. Sort a column, turn a page, or tick a row and watch the
+        rule in <helix-code>src/app.css</helix-code> paint it.
+      </helix-text>
+    </header>
+
+    <section class="section">
+      <helix-data-table
+        default-sort="name:asc"
+        label="Roster"
+        :page-size="6"
+        row-key="id"
+        :rows="members"
+        selectable
+      >
+        <!-- **Every column declares what it may give up.** A floor and a share:
+             the floor is what the words need, and the share is how the slack is
+             divided. At 390 the four columns and the checkboxes fit the box, and
+             below 376 the table scrolls its own box. -->
+        <helix-table-column field="name" sortable width="minmax(5.5rem, 1.6fr)">
+          Name
+        </helix-table-column>
+        <helix-table-column field="team" sortable width="minmax(4.5rem, 1fr)">
+          Team
+        </helix-table-column>
+        <helix-table-column field="role" width="minmax(4.5rem, 1fr)">Role</helix-table-column>
+        <!-- `end` lines the digits up under each other. `max-content`, since a
+             column of numerals has one right width. -->
+        <helix-table-column field="reviews" sortable text-align="end" width="max-content">
+          Reviews
+        </helix-table-column>
+
+        <!-- The footer is a row across the table: anything you slot goes at the
+             start, and the table's own pagination sits at the end. -->
+        <helix-text emphasis="subtle" slot="footer" variant="caption">
+          {{ members.length }} people
+        </helix-text>
+      </helix-data-table>
+
+      <!-- A footnote to the table, so it takes the section's gap. -->
+      <helix-text as="p" emphasis="muted" variant="caption">
+        Filtering, column reordering, resizing, virtualized rows, and a server mode for large
+        results are on
+        <a data-link :href="DOCS.table">the component's own page</a>.
+      </helix-text>
+    </section>
+  </div>
+</template>

package/templates/vue-vite/src/SignupForm.vue

@@ -0,0 +1,149 @@
+<script setup lang="ts">
+import type { HelixInputHelixBeforeChangeElementEvent } from '@fusion.dev/helix/vue'
+import { ref } from 'vue'
+import { teams } from './data.ts'
+import { DOCS } from './docs.ts'
+
+/** One message in the toast region, and what it says. */
+interface Message {
+  readonly id: number
+  readonly text: string
+}
+
+const handle = ref('')
+const messages = ref<readonly Message[]>([])
+
+/**
+ * The page takes the submit, so nothing navigates. Remove `preventDefault()`
+ * and the form posts to the server like any other, with the same names.
+ */
+const join = (event: Event) => {
+  event.preventDefault()
+  const answers = [...new FormData(event.currentTarget as HTMLFormElement).entries()]
+    .map(([field, value]) => `${field}=${value}`)
+    .join('  ')
+  messages.value = [...messages.value, { id: Date.now(), text: answers }]
+}
+
+/**
+ * **A controlled value, which is the one habit to unlearn.** A Helix element
+ * is not read-only: writing `value` seeds it, and the element goes on applying
+ * its own changes. So taking the decision means refusing the change with
+ * `preventDefault()`, then setting the value you want. Leaving `handle` as it
+ * was does not refuse anything.
+ */
+const takeHandle = (event: HelixInputHelixBeforeChangeElementEvent) => {
+  event.preventDefault()
+  handle.value = event.detail.value.toLowerCase().replaceAll(/[^a-z0-9-]/g, '')
+}
+
+const dismiss = (id: number) => {
+  messages.value = messages.value.filter((one) => one.id !== id)
+}
+</script>
+
+<!--
+  The form.
+
+  **Every control here is a form-associated custom element**, so a `<form>`
+  collects them, resets them, and validates them the way it does an `<input>`.
+  The submit proves it: it reads the answers with `new FormData(form)`, and
+  nothing gathers them by hand.
+
+  There is no wrapping `Field` component. A label in one shadow root cannot
+  name a control in another, so every control renders its own `label`, `hint`,
+  and `feedback`.
+-->
+<template>
+  <div class="stack">
+    <header class="hero">
+      <helix-text emphasis="muted" variant="label">Form</helix-text>
+      <helix-text as="h1" variant="heading">Join the roster</helix-text>
+      <helix-text as="p" class="lede" emphasis="muted" variant="body">
+        Five controls, and a <helix-code>&lt;form&gt;</helix-code> reads every one of them the way
+        it reads an <helix-code>input</helix-code>.
+      </helix-text>
+    </header>
+
+    <!-- The form takes a column of its own and the notes take what is left. At
+         390 the two stack, and the notes read as a postscript. -->
+    <div class="split">
+      <form class="form" @submit="join">
+        <helix-input autocomplete="name" label="Name" name="name" required />
+
+        <!-- Validation is the platform's: `type` and `required` are set on the
+             real input inside, and its own message shows once the field has been
+             touched. Set `feedback` to say it in your own words. -->
+        <helix-input
+          hint="Where we send the welcome note."
+          label="Email"
+          name="email"
+          required
+          type="email"
+        />
+
+        <!-- `@helix-before-change` binds with `addEventListener`, so it takes
+             the event's own name. -->
+        <helix-input
+          hint="Lowercase and hyphens, whatever you type."
+          label="Handle"
+          name="handle"
+          :value="handle"
+          @helix-before-change="takeHandle"
+        />
+
+        <helix-select label="Team" name="team" placeholder="Pick one" required>
+          <helix-option v-for="team in teams" :key="team" :value="team">{{ team }}</helix-option>
+        </helix-select>
+
+        <!-- A switch is a thing happening now, which is why it says on and off.
+             It still submits, as `on`. -->
+        <helix-switch label="Send me the weekly digest" name="digest" />
+
+        <helix-button emphasis="solid" tone="primary" type="submit">Join</helix-button>
+      </form>
+
+      <aside class="notes">
+        <!-- The one fact you need before typing your name into a page you have
+             had for five minutes, so it is a callout. `tone` is the meaning,
+             and the component draws it with a tint and a bar on the inline
+             start, so it survives being read in grayscale. -->
+        <helix-callout tone="info">
+          The form posts nothing. Submit it, and a message shows exactly what a server would
+          receive.
+        </helix-callout>
+        <helix-text as="h2" variant="title">What the form shows</helix-text>
+        <helix-text as="p" emphasis="muted" variant="body">
+          Every control is a form-associated custom element, so the submit reads them all with
+          <helix-code>new FormData(form)</helix-code>. Reset the form and they all go back,
+          the way an <helix-code>input</helix-code> does.
+        </helix-text>
+        <helix-text as="p" emphasis="muted" variant="body">
+          Leave the email wrong and the browser shows its own message, in your language. Handle is
+          the controlled field: the page refuses each change and writes back a cleaned value.
+        </helix-text>
+        <a data-link :href="DOCS.forms">Forms</a>
+      </aside>
+    </div>
+
+    <!-- **The region is rendered whether or not there is anything in it.**
+         Assistive technology subscribes to a live region, and one that arrives
+         already holding its message is often never announced. A dismissed
+         message asks to go through `helix-dismiss`. -->
+    <helix-toast>
+      <helix-toast-item
+        v-for="message in messages"
+        :key="message.id"
+        dismissible
+        :duration="8000"
+        tone="success"
+        @helix-dismiss="dismiss(message.id)"
+      >
+        <helix-flex direction="column" gap="2xs">
+          <helix-text variant="body-strong">Read by the form</helix-text>
+          <helix-text variant="code">{{ message.text }}</helix-text>
+        </helix-flex>
+      </helix-toast-item>
+    </helix-toast>
+  </div>
+</template>

package/templates/vue-vite/src/SiteFooter.vue

@@ -0,0 +1,28 @@
+<script setup lang="ts">
+import { DOCS } from './docs.ts'
+</script>
+
+<!--
+  The bar's counterpart, on every route.
+
+  **It puts a floor under the content.** The overview is a heading, a table,
+  and a caption, which on a tall window left the bottom third of the screen
+  empty. The footer is also where the links you want once belong.
+
+  `data-link="subtle"` reads as body text until it is hovered, which suits a
+  row of links under a rule.
+-->
+<template>
+  <footer class="site-footer">
+    <div class="footer-row">
+      <helix-text as="p" emphasis="subtle" variant="caption">
+        Every component here has a page, with its API, its parts, and its examples.
+      </helix-text>
+      <div class="footer-links">
+        <a data-link="subtle" :href="DOCS.gallery">Components</a>
+        <a data-link="subtle" :href="DOCS.elements">Documentation</a>
+        <a data-link="subtle" :href="DOCS.vue">Vue</a>
+      </div>
+    </div>
+  </footer>
+</template>

package/templates/vue-vite/src/SiteHeader.vue

@@ -0,0 +1,71 @@
+<script setup lang="ts">
+import { ref } from 'vue'
+import { usePathname } from './routes.ts'
+
+/** What the page can follow, in the order the control cycles them. */
+const MODES = ['system', 'light', 'dark'] as const
+
+type Mode = (typeof MODES)[number]
+
+/** The glyph each mode is announced and drawn with. */
+const MARKS: Record<Mode, string> = { dark: 'moon', light: 'sun', system: 'monitor' }
+
+const path = usePathname()
+/* `system` is the resting state, the mode the page follows until the control is pressed. */
+const mode = ref<Mode>('system')
+
+/**
+ * One attribute, two modes, and no second stylesheet.
+ *
+ * Every Helix token is written once as a `light-dark()` pair, so `color-scheme`
+ * decides which half resolves. `data-color-mode` sets it, and since
+ * `color-scheme` inherits, the attribute works on any element: put it on a
+ * panel for a light preview inside a dark page.
+ *
+ * `system` removes the attribute. Writing out whichever mode is current would
+ * hold the page there when the system's own setting changed.
+ */
+const cycle = () => {
+  const next = MODES[(MODES.indexOf(mode.value) + 1) % MODES.length] ?? 'system'
+  mode.value = next
+  if (next === 'system') {
+    delete document.documentElement.dataset.colorMode
+    return
+  }
+  document.documentElement.dataset.colorMode = next
+}
+</script>
+
+<!-- The bar across the top: the wordmark, the destinations, and the color mode. -->
+<template>
+  <helix-app-header material="glass" sticky>
+    <!-- The wordmark is the way back to the first page, so there is no third
+         destination in the bar saying the same thing. It is also the only name
+         of the project on the screen. The mark is a placeholder for your own,
+         drawn in `--helix-color-brand-mark`, the token for the brand as a
+         graphic. -->
+    <a class="wordmark" data-link="quiet" href="#/" slot="start">
+      <helix-icon name="cube" />
+      <helix-text variant="body-strong">__PROJECT_NAME__</helix-text>
+    </a>
+
+    <!-- The links are yours. Navigation owns the marker that travels between
+         them and renders no anchors of its own. The base layer styles them,
+         `aria-current="page"` included. -->
+    <helix-navigation label="Pages">
+      <a :aria-current="path === '/overview' ? 'page' : undefined" href="#/overview">Overview</a>
+      <a :aria-current="path === '/join' ? 'page' : undefined" href="#/join">Join</a>
+    </helix-navigation>
+
+    <!-- An icon with no words has no accessible name until it is given one,
+         which is why this is its own element. -->
+    <helix-icon-button
+      :label="`Color mode: ${mode}`"
+      slot="end"
+      :title="`Color mode: ${mode}`"
+      @click="cycle"
+    >
+      <helix-icon :name="MARKS[mode]" />
+    </helix-icon-button>
+  </helix-app-header>
+</template>