@fusion.dev/helix-templates 0.138.0 → 0.139.0

package/templates/solid-vite/src/data.ts

@@ -0,0 +1,81 @@
+/**
+ * The rows the overview draws.
+ *
+ * A local module and no network, so the starter runs with nothing behind it.
+ * Point `rows` at whatever you fetch and the table does not change: it takes the
+ * whole result and does the sorting, the filtering and the paging itself. Past
+ * the size a browser can hold, `mode="server"` inverts that and the table asks
+ * you for a page instead.
+ */
+
+/**
+ * One person on the roster.
+ *
+ * **A type alias and not an interface**, which TypeScript makes load-bearing
+ * here: `rows` takes `Readonly<Record<string, unknown>>`, an interface has no
+ * implicit index signature, and so an interface of exactly these fields is not
+ * assignable to it. The error names the index signature and not the shape, so
+ * it reads as though the data were wrong.
+ */
+export type Member = {
+  /**
+   * A stable identity, which is what `row-key` names.
+   *
+   * Sorting moves a row's element rather than rewriting every cell in it, so
+   * without one a sort throws away focus and anything attached to a row.
+   */
+  readonly id: string
+  /**
+   * What the reader is here to find.
+   */
+  readonly name: string
+  /**
+   * A number rather than a formatted string, so the column sorts by size.
+   *
+   * A cell showing `2.4k` sorts as text unless the column's `compare` says what
+   * the value underneath is, which is the one thing here that is cheap to get
+   * right now and expensive to add later.
+   */
+  readonly reviews: number
+  /**
+   * What they do.
+   */
+  readonly role: string
+  /**
+   * Who they do it with.
+   */
+  readonly team: string
+}
+
+export const members: readonly Member[] = [
+  { id: 'm-01', name: 'Ada Okonkwo', reviews: 184, role: 'Staff', team: 'Platform' },
+  { id: 'm-02', name: 'Bruno Salas', reviews: 96, role: 'Senior', team: 'Payments' },
+  { id: 'm-03', name: 'Cai Wen', reviews: 231, role: 'Principal', team: 'Platform' },
+  { id: 'm-04', name: 'Dilara Yilmaz', reviews: 64, role: 'Senior', team: 'Growth' },
+  { id: 'm-05', name: 'Esi Mensah', reviews: 148, role: 'Staff', team: 'Payments' },
+  { id: 'm-06', name: 'Felix Braun', reviews: 39, role: 'Engineer', team: 'Growth' },
+  { id: 'm-07', name: 'Gita Raman', reviews: 112, role: 'Senior', team: 'Platform' },
+  { id: 'm-08', name: 'Hana Sato', reviews: 57, role: 'Engineer', team: 'Design' },
+  { id: 'm-09', name: 'Ivan Petrov', reviews: 88, role: 'Senior', team: 'Payments' },
+  { id: 'm-10', name: 'Jo Lindqvist', reviews: 21, role: 'Engineer', team: 'Design' },
+  { id: 'm-11', name: 'Kwame Asante', reviews: 73, role: 'Staff', team: 'Growth' },
+  { id: 'm-12', name: 'Lena Fischer', reviews: 12, role: 'Engineer', team: 'Design' },
+]
+
+/** The teams the form offers, read from the roster so the two cannot disagree. */
+export const teams: readonly string[] = [...new Set(members.map((one) => one.team))].toSorted()
+
+/**
+ * The same roster as three figures, for the panel on the first screen.
+ *
+ * Derived rather than written out, so the panel cannot claim a number the table
+ * does not show.
+ */
+export const roster = {
+  /** How many rows the data view has. */
+  people: members.length,
+  /** Every review on the roster, added up. */
+  reviews: members.reduce((total, one) => total + one.reviews, 0),
+  /** How many teams they are spread across. */
+  teams: teams.length,
+}

package/templates/solid-vite/src/diagnostics.ts

@@ -0,0 +1,24 @@
+/**
+ * Helix diagnostics, which `main.tsx` loads in development only.
+ *
+ * It finds the Helix mistakes that are valid CSS and therefore silent, such as
+ * a `::part()` naming a part nothing publishes, and an attribute value outside
+ * the set a component takes. Each finding prints once in DevTools, and a badge
+ * in the corner of the page lists them while there are any.
+ *
+ * **Checked against the Helix you installed**, from the lint data it ships, so
+ * nothing is loaded from the network.
+ *
+ * To print the findings in your terminal as well, run `npx helix diagnostics`
+ * from `@fusion.dev/helix-cli` beside the dev server, and add
+ * `sinks: { relay: true }` below.
+ */
+import { initDiagnostics } from '@fusion.dev/helix-diagnostics'
+import lint from '@fusion.dev/helix/lint.json'
+
+initDiagnostics({
+  environment: 'development',
+  /* The route is in the hash, so each page's findings are kept apart. */
+  page: () => window.location.hash.slice(1) || '/',
+  tiers: [{ lint }],
+})

package/templates/solid-vite/src/docs.ts

@@ -0,0 +1,29 @@
+/**
+ * The documentation this starter links to.
+ *
+ * **One module, because a link is the thing in a starter most likely to rot.**
+ * A page that composes its own URLs ships a plausible-looking 404 to every
+ * project scaffolded from it, and nobody finds out until a reader clicks one.
+ * Here they are in a list somebody can open and check, and pointing the starter
+ * at a mirror or an internal copy is one edit.
+ *
+ * Checked 16 Sep 2026: every entry answers 200.
+ */
+export const DOCS = {
+  /** How the elements are registered and written, which is the first page to read. */
+  elements: 'https://fusion.dev/helix/docs/using-the-elements',
+  /** What a `<form>` does with these controls, and what it cannot do. */
+  forms: 'https://fusion.dev/helix/docs/forms',
+  /** Every component, with its API, its parts and its examples. */
+  gallery: 'https://fusion.dev/helix/components',
+  /** The light and dark pair, and the attribute that chooses between them. */
+  modes: 'https://fusion.dev/helix/docs/color-modes',
+  /** Reaching a component's parts from a page, which `app.css` does once. */
+  parts: 'https://fusion.dev/helix/docs/overriding-a-component',
+  /** Solid and the other frameworks: props, events, and seeded values. */
+  solid: 'https://fusion.dev/helix/docs/other-frameworks',
+  /** The data view's own page, where the rest of its API is. */
+  table: 'https://fusion.dev/helix/components/data-table',
+  /** Every token, and what each one is for. */
+  tokens: 'https://fusion.dev/helix/docs/tokens',
+} as const

package/templates/solid-vite/src/landing.tsx

@@ -0,0 +1,177 @@
+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')
+
+/**
+ * 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.
+ */
+export function Landing() {
+  return (
+    <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.tsx</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">
+              {/* The route beside the name, on one baseline in the header. */}
+              <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>
+  )
+}

package/templates/solid-vite/src/main.tsx

@@ -0,0 +1,23 @@
+import { render } from 'solid-js/web'
+
+/* Every layer in one import: the tokens, the reset, the utility layer, and the
+   `:not(:defined)` rules that keep a tag from arriving unstyled. It reaches its
+   pieces by bare specifier, so a bundler resolves it and a `<link>` cannot. */
+import '@fusion.dev/helix-styles/helix.css'
+/* A custom element registers as a side effect of being imported, so this line
+   makes every Helix tag in the app real. Import the whole library while you are
+   finding your feet. `@fusion.dev/helix/button` and its siblings are subpath
+   exports, for when you want to pay for only what you use. */
+import '@fusion.dev/helix'
+/* After both, so a rule of yours that names the same thing wins. */
+import './app.css'
+
+import { App } from './App.tsx'
+
+/* **Diagnostics in development, and none of it in a build.** `vite build`
+   replaces `import.meta.env.DEV` with `false` and drops the import with it. */
+if (import.meta.env.DEV) {
+  void import('./diagnostics.ts')
+}
+
+render(() => <App />, document.querySelector('#root') as HTMLElement)

package/templates/solid-vite/src/overview.tsx

@@ -0,0 +1,78 @@
+import { members } from './data.ts'
+import { DOCS } from './docs.ts'
+
+/**
+ * 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.
+ */
+export function Overview() {
+  return (
+    <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>
+  )
+}

package/templates/solid-vite/src/routes.ts

@@ -0,0 +1,22 @@
+import { type Accessor, createSignal } from 'solid-js'
+
+/* **The whole router, which is a hash and a listener.**
+
+   A starter should not pick your router for you, and three pages need
+   `location.hash` and one event. Swap this file for Solid Router when you want
+   nested routes or preloading: its `HashRouter` keeps these addresses.
+
+   A hash, because the History API wants a server that answers every path with
+   the same document, and `vite preview` and wherever you deploy each have to be
+   told to. A hash asks nothing of either. Each link in the app is a plain anchor
+   to `#/` and a path. */
+
+/** Where the reader is, as a path, so the first page is `/`. */
+const read = (): string => window.location.hash.slice(1) || '/'
+
+const [path, setPath] = createSignal(read())
+
+window.addEventListener('hashchange', () => setPath(read()))
+
+/** The current path, kept current as the hash changes. */
+export const pathname: Accessor<string> = path

package/templates/solid-vite/src/signup-form.tsx

@@ -0,0 +1,151 @@
+import { createSignal, For, type JSX } from 'solid-js'
+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
+}
+
+/**
+ * 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`.
+ */
+export function SignupForm() {
+  const [handle, setHandle] = createSignal('')
+  const [messages, setMessages] = createSignal<readonly Message[]>([])
+
+  const join: JSX.EventHandler<HTMLFormElement, SubmitEvent> = (event) => {
+    /* The page takes the submit, so nothing navigates. Remove the line and the
+       form posts to the server like any other, with the same names. */
+    event.preventDefault()
+    const answers = [...new FormData(event.currentTarget).entries()]
+      .map(([field, value]) => `${field}=${value}`)
+      .join('  ')
+    setMessages((sent) => [...sent, { id: Date.now(), text: answers }])
+  }
+
+  return (
+    <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 />
+
+        {/* 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"
+        />
+
+        {/* **A controlled value, which is the one habit to unlearn.** `on:` binds
+            the event by its own name. 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. */}
+        <helix-input
+          hint="Lowercase and hyphens, whatever you type."
+          label="Handle"
+          name="handle"
+          on:helix-before-change={(event) => {
+            event.preventDefault()
+            setHandle(event.detail.value.toLowerCase().replaceAll(/[^a-z0-9-]/g, ''))
+          }}
+          value={handle()}
+        />
+
+        <helix-select label="Team" name="team" placeholder="Pick one" required>
+          <For each={teams}>{(team) => <helix-option value={team}>{team}</helix-option>}</For>
+        </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>
+        <For each={messages()}>
+          {(message) => (
+            <helix-toast-item
+              dismissible
+              duration={8000}
+              on:helix-dismiss={() => {
+                setMessages((sent) => sent.filter((one) => one.id !== 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>
+          )}
+        </For>
+      </helix-toast>
+    </div>
+  )
+}

package/templates/solid-vite/src/site-footer.tsx

@@ -0,0 +1,34 @@
+import { DOCS } from './docs.ts'
+
+/**
+ * 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.
+ */
+export function SiteFooter() {
+  return (
+    <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.solid}>
+            Solid
+          </a>
+        </div>
+      </div>
+    </footer>
+  )
+}