@fusion.dev/helix-templates 0.34.2 → 0.35.1

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

@@ -0,0 +1,191 @@
+import { roster } from './data.js'
+import { DOCS } from './docs.js'
+import { Link } from './routes.js'
+
+/**
+ * **A locale named rather than left to the machine.** `toLocaleString()` with no
+ * argument reads the environment's locale, which is the server's in one template
+ * and the reader's in both, so the same number is grouped two ways and the
+ * markup React hydrates does not match the markup it rendered.
+ */
+const figure = new Intl.NumberFormat('en-US')
+
+/**
+ * The first screen, and the only page here that is about the starter rather
+ * than built out of it.
+ *
+ * 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.** A
+ * scaffold called `my-app` opening on an `<h1>my-app</h1>` tells its reader
+ * nothing they did not type thirty seconds ago, and spends the loudest line on
+ * the page doing it.
+ *
+ * **Anchors, not a `Button` with an `href`.** A button that navigates is a link
+ * wearing a button's clothes, 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 without being one.
+ */
+export function Landing() {
+  return (
+    <div className="stack">
+      <header className="first-screen">
+        <div className="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" className="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 className="actions">
+            <Link data-button="solid" data-button-tone="primary" href="/overview">
+              See the data view
+            </Link>
+            <Link data-button href="/join">
+              Open the form
+            </Link>
+          </div>
+        </div>
+
+        {/* **What the first screen has to look at, and the honest thing to look
+            at is the library working.** The figures are the roster the data view
+            draws, read from the same module, so the panel is the app rather than
+            a decoration of it. `helix-stat` sets the number on the display face
+            at a size the type scale does not reach, which is the one place on a
+            page where the number is the design. */}
+        <helix-card className="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>
+          <Link data-link href="/overview" slot="footer">
+            Open the data view
+          </Link>
+        </helix-card>
+      </header>
+
+      <section className="section">
+        <helix-text as="h2" variant="subheading">
+          What you have
+        </helix-text>
+        {/* Three paragraphs about one installed thing, so they take a rule each
+            rather than a box each. `app.css` says why at more length. */}
+        <div className="facts">
+          <article className="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 className="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 className="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 className="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.** A
+            card with an anchor in its footer gives a reader a target the size of
+            three words inside a box the size of a paragraph, and the box is what
+            they aim at. The recipe is in the base layer: it draws the ring, moves
+            the card's border to the brand on hover, and leaves focus alone. So
+            nothing inside may be interactive, a link inside a link being neither
+            valid nor reachable. */}
+        <helix-grid columns={2} gap="md">
+          <Link data-card href="/overview">
+            <helix-card separation="outlined">
+              {/* The route beside the name rather than under the text: slotted
+                  into the header the two sit on one baseline, and a row of
+                  cards stretched to a common height has nothing left floating
+                  in the middle of it. */}
+              <helix-flex align="baseline" gap="sm" justify="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>
+          </Link>
+
+          <Link data-card href="/join">
+            <helix-card separation="outlined">
+              <helix-flex align="baseline" gap="sm" justify="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>
+          </Link>
+        </helix-grid>
+      </section>
+    </div>
+  )
+}

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

@@ -10,6 +10,8 @@ import '@fusion.dev/helix-styles/helix.css'
    are finding your feet; `@fusion.dev/helix/button` and its siblings are subpath
    exports when you would rather 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.js'
 

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

@@ -0,0 +1,91 @@
+import { members } from './data.js'
+import { DOCS } from './docs.js'
+
+/**
+ * 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,
+ * because 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: none of it is
+ * wired up here, and none of it is a handler you have to write.
+ *
+ * **Selection is keyed on `row-key`, so it survives a sort and a page.** A row
+ * is chosen by its identity rather than by where it happened to be sitting, and
+ * `app.css` paints the chosen row through the parts the table names for it.
+ */
+export function Overview() {
+  return (
+    <div className="stack">
+      <header className="hero">
+        <helix-text emphasis="muted" variant="label">
+          Data view
+        </helix-text>
+        <helix-text as="h1" variant="heading">
+          Roster
+        </helix-text>
+        <helix-text as="p" className="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 className="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, and that is the whole of
+              the narrow-window story.** A column left to itself takes
+              `minmax(max-content, 1fr)`, which refuses to go below its longest
+              cell however little room there is, so the last column is pushed
+              outside the box and the reader has to scroll the table sideways to
+              read a value. A floor and a share instead: the floor is what the
+              words need, the share is how the slack is divided. Measured 16 Sep
+              2026: at 390 the four columns and the checkboxes come to 358 in a box
+              of 358, so nothing is cut and nothing wraps; the floors alone come to
+              344, so at a 376 pixel window they exactly fit and below it the table
+              scrolls its own box, which is honest, and it fades whichever edge has
+              more behind it. */}
+          <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, which is the whole reason
+              a number column is a different thing from a text one. `max-content`
+              because a column of numerals has one right width and no reason to
+              take a share of anything. */}
+          <helix-table-column align="end" field="reviews" sortable width="max-content">
+            Reviews
+          </helix-table-column>
+
+          {/* The footer is a row across the table, not a corner: 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 rather than the next block of the page, so it
+            takes the section's gap and not the stack's. */}
+        <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/react-vite/src/routes.tsx

@@ -0,0 +1,39 @@
+import { type AnchorHTMLAttributes, useEffect, useState } from 'react'
+
+/* **The whole router, which is a hash and a listener.**
+
+   A starter should not pick your router for you, and two pages need
+   `location.hash` and one event. Swap this file for the router you want: the two
+   names it exports are Next.js's, so the rest of the app reads the same in
+   either template and nothing else here has to change.
+
+   A hash rather than the History API, because the History API wants a server
+   that answers every path with the same document, and `vite preview` and
+   whatever you deploy to each have to be told to. A hash asks nothing of
+   either. */
+
+/** Where the reader is, as a path, so the overview is `/`. */
+const read = (): string => window.location.hash.slice(1) || '/'
+
+/**
+ * A destination, addressed the way the Next.js template addresses one.
+ *
+ * Everything but `href` goes straight through to the anchor, which is what
+ * `next/link` does and is why a `data-button` or a `slot` reads the same in both
+ * templates. The path is written as a path: the hash is this component's
+ * business and nobody else's.
+ */
+export function Link({ href, ...rest }: AnchorHTMLAttributes<HTMLAnchorElement>) {
+  return <a {...rest} href={`#${href ?? '/'}`} />
+}
+
+/** The current path, and a re-render whenever it changes. */
+export function usePathname(): string {
+  const [path, setPath] = useState(read)
+  useEffect(() => {
+    const follow = () => setPath(read())
+    window.addEventListener('hashchange', follow)
+    return () => window.removeEventListener('hashchange', follow)
+  }, [])
+  return path
+}

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

@@ -0,0 +1,162 @@
+import { type FormEvent, useState } from 'react'
+import { teams } from './data.js'
+import { DOCS } from './docs.js'
+
+/** 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>`.
+ * That is what `ElementInternals` buys, and the submit below 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` instead.
+ */
+export function SignupForm() {
+  const [handle, setHandle] = useState('')
+  const [messages, setMessages] = useState<readonly Message[]>([])
+
+  const join = (event: FormEvent<HTMLFormElement>) => {
+    /* The page answers this, 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 className="stack">
+      <header className="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" className="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, so a
+          wide window is a page rather than a form with a void beside it. At 390
+          the two stack and the notes read as a postscript. */}
+      <div className="split">
+      <form className="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 is what shows once the reader
+            has touched the field. Set `feedback` to say it in your own words
+            instead, and it shows from the first paint rather than after a
+            mistake. */}
+        <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.** The handler
+            is a prop named for the event, so `onhelix-before-change` hears
+            `helix-before-change`. 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()`
+            and then setting the value you want. Declining to call `setHandle` is
+            not a refusal, and leaves the element holding what you did not
+            accept. */}
+        <helix-input
+          hint="Lowercase and hyphens, whatever you type."
+          label="Handle"
+          name="handle"
+          onhelix-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>
+          {teams.map((team) => (
+            <helix-option key={team} value={team}>
+              {team}
+            </helix-option>
+          ))}
+        </helix-select>
+
+        {/* A switch is a thing happening now rather than an answer a form asks
+            for, 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 className="notes">
+          {/* The one fact a reader needs before typing their name into a page
+              they have had for five minutes, which is why it is a callout and
+              not the fourth line of a paragraph. `tone` is the meaning and the
+              component decides what that looks like: a tint mixed from the
+              status color 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 frequently never announced. Nothing
+          creates or destroys a message here either: the items are state, and a
+          dismissed one asks to go through `helix-dismiss`. */}
+      <helix-toast>
+        {messages.map((message) => (
+          <helix-toast-item
+            dismissible
+            duration={8000}
+            key={message.id}
+            onhelix-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>
+        ))}
+      </helix-toast>
+    </div>
+  )
+}

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

@@ -0,0 +1,38 @@
+import { DOCS } from './docs.js'
+
+/**
+ * The bar's counterpart, on every route.
+ *
+ * **It is here so that a page ends rather than stops.** The overview is a
+ * heading, a table and a caption, which on a tall window left the bottom third
+ * of the screen empty and read as a layout that had run out. A footer is the
+ * ordinary answer: it puts a floor under the content, and it is where the links
+ * a reader wants once rather than constantly belong, which is why the landing
+ * page no longer carries them itself.
+ *
+ * `data-link="subtle"` reads as body text until it is hovered, which is what a
+ * row of links under a rule should do: they are a destination, not a sentence
+ * asking to be read.
+ */
+export function SiteFooter() {
+  return (
+    <footer className="site-footer">
+      <div className="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 className="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.react}>
+            React
+          </a>
+        </div>
+      </div>
+    </footer>
+  )
+}

package/templates/react-vite/src/site-header.tsx

@@ -0,0 +1,85 @@
+import { useState } from 'react'
+import { Link, usePathname } from './routes.js'
+
+/** 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' }
+
+/**
+ * The bar across the top: the wordmark, the destinations, and the color mode.
+ */
+export function SiteHeader() {
+  const path = usePathname()
+  /* `system` is the resting state and what the markup is served in, so the
+     control draws the same glyph on the server and on the first client paint. */
+  const [mode, setMode] = useState<Mode>('system')
+
+  /**
+   * One attribute, two modes, and no second stylesheet.
+   *
+   * Every Helix token is written once as a `light-dark()` pair, so which half
+   * resolves is decided by `color-scheme` and nothing else. `data-color-mode`
+   * sets it, and because `color-scheme` inherits the attribute works on any
+   * element, not only on the root: put it on a panel for a light preview inside
+   * a dark page.
+   *
+   * `system` removes the attribute rather than writing out whichever mode is
+   * current, which would freeze the page there the moment the reader's machine
+   * changed.
+   */
+  const cycle = () => {
+    const next = MODES[(MODES.indexOf(mode) + 1) % MODES.length]
+    setMode(next)
+    if (next === 'system') {
+      delete document.documentElement.dataset.colorMode
+      return
+    }
+    document.documentElement.dataset.colorMode = next
+  }
+
+  return (
+    <helix-app-header material="glass" sticky>
+      {/* The wordmark is the way back to the first page, which is what a reader
+          expects of one, 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
+          landing page leads with what this is rather than with what you called
+          it.
+
+          The mark is a placeholder for your own, and it is drawn in
+          `--helix-color-brand-mark`, the token for the brand as a graphic. */}
+      <Link className="wordmark" data-link="quiet" href="/" slot="start">
+        <helix-icon name="cube" />
+        <helix-text variant="body-strong">__PROJECT_NAME__</helix-text>
+      </Link>
+
+      {/* The links are yours. Navigation owns the marker that travels between
+          them and renders no anchors of its own, because a router renders its
+          own and could not render them inside this shadow root. The base layer
+          styles them, `aria-current="page"` included. */}
+      <helix-navigation label="Pages">
+        <Link aria-current={path === '/overview' ? 'page' : undefined} href="/overview">
+          Overview
+        </Link>
+        <Link aria-current={path === '/join' ? 'page' : undefined} href="/join">
+          Join
+        </Link>
+      </helix-navigation>
+
+      {/* An icon with no words has no accessible name unless it is given one,
+          which is the whole reason this is its own element rather than a button
+          with a glyph in it. */}
+      <helix-icon-button
+        label={`Color mode: ${mode}`}
+        onClick={cycle}
+        slot="end"
+        title={`Color mode: ${mode}`}
+      >
+        <helix-icon name={MARKS[mode]} />
+      </helix-icon-button>
+    </helix-app-header>
+  )
+}

package/templates.json

@@ -2,21 +2,21 @@
   "placeholder": "__PROJECT_NAME__",
   "templates": [
     {
-      "description": "React and TypeScript on Vite. The shortest path to a running component.",
+      "description": "React and TypeScript on Vite. The shortest path to a running app.",
       "id": "react-vite",
       "named": [
         "index.html",
         "package.json",
-        "src/App.tsx"
+        "src/site-header.tsx"
       ],
       "title": "React (Vite)"
     },
     {
-      "description": "React and TypeScript on the Next.js App Router, with the elements registered once.",
+      "description": "React and TypeScript on the Next.js App Router, with the three pages as real routes.",
       "id": "react-nextjs",
       "named": [
         "app/layout.tsx",
-        "app/page.tsx",
+        "app/site-header.tsx",
         "package.json"
       ],
       "title": "React (Next.js)"