@fusion.dev/helix-templates 0.138.0 → 0.140.0

package/templates/svelte-vite/src/Landing.svelte

@@ -0,0 +1,100 @@
+<!--
+  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.
+-->
+<script 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>
+
+<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"></helix-aura>
+    <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"></helix-icon></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"></helix-icon></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"></helix-icon></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>

package/templates/svelte-vite/src/Overview.svelte

@@ -0,0 +1,67 @@
+<!--
+  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.
+-->
+<script lang="ts">
+  import { members } from './data.ts'
+  import { DOCS } from './docs.ts'
+</script>
+
+<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>

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

@@ -0,0 +1,147 @@
+<!--
+  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`.
+-->
+<script lang="ts">
+  import type { HelixInputHelixBeforeChangeElementEvent } from '@fusion.dev/helix/jsx'
+  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
+  }
+
+  let handle = $state('')
+  let messages = $state<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: SubmitEvent) => {
+    event.preventDefault()
+    const answers = [...new FormData(event.currentTarget as HTMLFormElement).entries()]
+      .map(([field, value]) => `${field}=${value}`)
+      .join('  ')
+    messages = [...messages, { 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 = event.detail.value.toLowerCase().replaceAll(/[^a-z0-9-]/g, '')
+  }
+
+  const dismiss = (id: number) => {
+    messages = messages.filter((one) => one.id !== id)
+  }
+</script>
+
+<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" onsubmit={join}>
+      <helix-input autocomplete="name" label="Name" name="name" required></helix-input>
+
+      <!-- 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-input>
+
+      <!-- `onhelix-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}
+        onhelix-before-change={takeHandle}
+      ></helix-input>
+
+      <helix-select label="Team" name="team" placeholder="Pick one" required>
+        {#each teams as team (team)}
+          <helix-option value={team}>{team}</helix-option>
+        {/each}
+      </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-switch>
+
+      <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>
+    {#each messages as message (message.id)}
+      <helix-toast-item
+        dismissible
+        duration={8000}
+        onhelix-dismiss={() => dismiss(message.id)}
+        tone="success"
+      >
+        <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>
+    {/each}
+  </helix-toast>
+</div>

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

@@ -0,0 +1,26 @@
+<!--
+  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.
+-->
+<script lang="ts">
+  import { DOCS } from './docs.ts'
+</script>
+
+<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.svelte}>Svelte</a>
+    </div>
+  </div>
+</footer>

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

@@ -0,0 +1,71 @@
+<!-- The bar across the top: the wordmark, the destinations, and the color mode. -->
+<script lang="ts">
+  import { route } from './routes.svelte.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' }
+
+  /* `system` is the resting state, the mode the page follows until the control is pressed. */
+  let mode = $state<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) + 1) % MODES.length] ?? 'system'
+    mode = next
+    if (next === 'system') {
+      delete document.documentElement.dataset.colorMode
+      return
+    }
+    document.documentElement.dataset.colorMode = next
+  }
+</script>
+
+<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-icon>
+    <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={route.path === '/overview' ? 'page' : undefined} href="#/overview">Overview</a>
+    <a aria-current={route.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.
+
+       Svelte's accessibility check reads the tag, and the button is inside the
+       element's shadow root, with its role and its keys. So the two warnings
+       about a click on an element with neither are ignored here. -->
+  <!-- svelte-ignore a11y_click_events_have_key_events, a11y_no_static_element_interactions -->
+  <helix-icon-button
+    label={`Color mode: ${mode}`}
+    onclick={cycle}
+    slot="end"
+    title={`Color mode: ${mode}`}
+  >
+    <helix-icon name={MARKS[mode]}></helix-icon>
+  </helix-icon-button>
+</helix-app-header>