@fusion.dev/helix-templates 0.137.0 → 0.139.0

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

@@ -0,0 +1,139 @@
+<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 heading says what this is, and the project's name stays in the bar.**
+
+  **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">
+      <div class="hero">
+        <helix-text emphasis="muted" variant="label">Helix starter</helix-text>
+        <helix-text as="h1">Every tag on this page is Helix</helix-text>
+        <helix-text as="p" class="lede" emphasis="muted" variant="body">
+          Nothing here is a wrapper: the tags are the library's own elements, and every color,
+          size and space inside them comes from one set of tokens. Three routes are laid down, and
+          all of them are yours.
+        </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 figures are the roster the data view draws, read from the same
+           module, so the panel is the app at work. `helix-stat` sets the number
+           on the display face at a size the type scale does not reach. -->
+      <helix-card class="specimen" 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>
+      <!-- Three paragraphs about one installed thing, so they take a rule each
+           and no box. `app.css` says why at more length. -->
+      <div class="facts">
+        <article class="fact">
+          <helix-text as="h3" variant="title">Elements, not wrappers</helix-text>
+          <helix-text as="p" emphasis="muted" variant="body">
+            They are custom elements, so you write the tags and there is no per-component import
+            to keep in step. One line in <helix-code>src/main.ts</helix-code> registers all of
+            them, and a subpath like <helix-code>@fusion.dev/helix/tabs</helix-code> registers
+            one.
+          </helix-text>
+          <a data-link :href="DOCS.elements">Using the elements</a>
+        </article>
+
+        <article class="fact">
+          <helix-text as="h3" variant="title">One set of tokens</helix-text>
+          <helix-text as="p" emphasis="muted" variant="body">
+            Every color is written once as a light and dark pair, so the control in the bar moves
+            the whole page by setting a single attribute on the root. Type, spacing, radii and
+            control sizes come from the same place.
+          </helix-text>
+          <a data-link :href="DOCS.tokens">Tokens</a>
+        </article>
+
+        <article class="fact">
+          <helix-text as="h3" variant="title">A short stylesheet</helix-text>
+          <helix-text as="p" emphasis="muted" variant="body">
+            <helix-code>src/app.css</helix-code> holds this page's measure, the rhythm between its
+            blocks, and nothing a component already draws. Where a component leaves a decision
+            open it names a part: the data view reaches one to paint the row you tick.
+          </helix-text>
+          <a data-link :href="DOCS.parts">Overriding a component</a>
+        </article>
+      </div>
+    </section>
+
+    <section class="section">
+      <helix-text as="h2" variant="subheading">Where to go next</helix-text>
+      <!-- **The whole card is the 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. -->
+      <helix-grid :columns="2" gap="md">
+        <a data-card href="#/overview">
+          <helix-card separation="outlined">
+            <helix-flex align-items="baseline" gap="sm" justify-content="between" slot="header">
+              <helix-text as="h3" variant="title">The data view</helix-text>
+              <helix-text emphasis="subtle" variant="code">/overview</helix-text>
+            </helix-flex>
+            <helix-text as="p" emphasis="muted" variant="body">
+              Twelve people from a local module, sorted, paged and selected with nothing wired up.
+              The columns are markup you can read and the rows are one property, which is what
+              keeps the same component working at ten thousand.
+            </helix-text>
+          </helix-card>
+        </a>
+
+        <a data-card href="#/join">
+          <helix-card separation="outlined">
+            <helix-flex align-items="baseline" gap="sm" justify-content="between" slot="header">
+              <helix-text as="h3" variant="title">The form</helix-text>
+              <helix-text emphasis="subtle" variant="code">/join</helix-text>
+            </helix-flex>
+            <helix-text as="p" emphasis="muted" variant="body">
+              Five controls a <helix-code>&lt;form&gt;</helix-code> reads with
+              <helix-code>FormData</helix-code>, because every one of them is a real form
+              participant. The email field's complaint is the browser's own.
+            </helix-text>
+          </helix-card>
+        </a>
+      </helix-grid>
+    </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 that asks you
+        for a page are all 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 reader has
+             touched the field. 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">
+          Nothing is posted anywhere. Submit it and the message shows exactly what a server would
+          have been handed.
+        </helix-callout>
+        <helix-text as="h2" variant="title">What this is showing</helix-text>
+        <helix-text as="p" emphasis="muted" variant="body">
+          Every control is a form-associated custom element, so the submit reads them with
+          <helix-code>new FormData(form)</helix-code> and nothing gathers the answers by hand.
+          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 complaint is the browser's own, in the reader's language.
+          Handle is the controlled one: it refuses the change and writes back what it will accept.
+        </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 in here, with its API, its parts and its examples, has a page.
+      </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,72 @@
+<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, so the control draws the same glyph before and
+   after the reader first touches it. */
+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
+ * freeze the page there the moment the reader's machine 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>